From: JvD_Ericsson Date: Tue, 11 Jun 2024 14:08:56 +0000 (+0100) Subject: Update developer docs X-Git-Tag: 0.0.1~1 X-Git-Url: https://gerrit.o-ran-sc.org/r/gitweb?a=commitdiff_plain;h=f35bdeee818183a69e96cc4ff291b53cd4b7a5c2;p=smo%2Fteiv.git Update developer docs Issue-ID: SMO-150 Change-Id: If9fe16ba4f994a32c2b659f8649c70b6a1d6b88c Signed-off-by: JvD_Ericsson --- diff --git a/docs/api-documentation.rst b/docs/api-documentation.rst new file mode 100644 index 0000000..a2b2f7b --- /dev/null +++ b/docs/api-documentation.rst @@ -0,0 +1,11 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. SPDX-License-Identifier: CC-BY-4.0 +.. Copyright (C) 2024 Nordix Foundation. All rights Reserved +.. Copyright (C) 2024 OpenInfra Foundation Europe. All Rights Reserved + +.. _api: + +APIs +==== + +.. openapi:: ../teiv/src/main/resources/v1/topology-exposure-inventory-openapi.yaml diff --git a/docs/conf.py b/docs/conf.py index 8846070..02fef9f 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -27,4 +27,5 @@ author = "ORAN" extensions = [ 'sphinx.ext.autosectionlabel', + 'sphinxcontrib.openapi' ] diff --git a/docs/data-models-guide.rst b/docs/data-models-guide.rst index a953244..ec112b0 100644 --- a/docs/data-models-guide.rst +++ b/docs/data-models-guide.rst @@ -9,67 +9,14 @@ Topology & Inventory Data Models The following are the currently supported modules in Topology & Inventory. -Common YANG extensions ----------------------- -.. literalinclude:: ../teiv/src/main/resources/models/o-ran-smo-teiv-common-yang-extensions.yang - :language: yang - -Common YANG types ------------------ - -.. image:: _static/data-model/yang-types.svg - :width: 900 - -.. literalinclude:: ../teiv/src/main/resources/models/o-ran-smo-teiv-common-yang-types.yang - :language: yang - -Equipment ---------- - -.. image:: _static/data-model/equipment.svg - :width: 900 - -.. image:: _static/data-model/equipment-relationships.svg - :width: 900 - -.. literalinclude:: ../teiv/src/main/resources/models/o-ran-smo-teiv-equipment.yang - :language: yang - -RAN ---- - -.. image:: _static/data-model/ran.svg - :width: 900 - -.. image:: _static/data-model/ran-relationships.svg - :width: 900 - -.. literalinclude:: ../teiv/src/main/resources/models/o-ran-smo-teiv-ran.yang - :language: yang - -Relationship: Equipment RAN ---------------------------- - -.. image:: _static/data-model/equipment-ran.svg - :width: 900 - -.. literalinclude:: ../teiv/src/main/resources/models/o-ran-smo-teiv-equipment-to-ran.yang - :language: yang - -OAM ---- - -.. image:: _static/data-model/oam.svg - :width: 900 - -.. literalinclude:: ../teiv/src/main/resources/models/o-ran-smo-teiv-oam.yang - :language: yang - -Relationship: OAM RAN ---------------------- - -.. image:: _static/data-model/oam-ran.svg - :width: 900 - -.. literalinclude:: ../teiv/src/main/resources/models/o-ran-smo-teiv-oam-to-ran.yang - :language: yang +.. toctree:: + :maxdepth: 1 + :caption: Contents: + + ./data-models/common-yang-extensions.rst + ./data-models/common-yang-types.rst + ./data-models/equipment.rst + ./data-models/ran.rst + ./data-models/equipment-to-ran.rst + ./data-models/oam.rst + ./data-models/oam-to-ran.rst diff --git a/docs/data-models/common-yang-extensions.rst b/docs/data-models/common-yang-extensions.rst new file mode 100644 index 0000000..f9efe6c --- /dev/null +++ b/docs/data-models/common-yang-extensions.rst @@ -0,0 +1,9 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. SPDX-License-Identifier: CC-BY-4.0 +.. Copyright (C) 2024 Nordix Foundation. All rights Reserved +.. Copyright (C) 2024 OpenInfra Foundation Europe. All Rights Reserved + +Common YANG extensions +---------------------- +.. literalinclude:: ../../teiv/src/main/resources/models/o-ran-smo-teiv-common-yang-extensions.yang + :language: yang diff --git a/docs/data-models/common-yang-types.rst b/docs/data-models/common-yang-types.rst new file mode 100644 index 0000000..78e300c --- /dev/null +++ b/docs/data-models/common-yang-types.rst @@ -0,0 +1,13 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. SPDX-License-Identifier: CC-BY-4.0 +.. Copyright (C) 2024 Nordix Foundation. All rights Reserved +.. Copyright (C) 2024 OpenInfra Foundation Europe. All Rights Reserved + +Common YANG types +----------------- + +.. image:: ../_static/data-model/yang-types.svg + :width: 900 + +.. literalinclude:: ../../teiv/src/main/resources/models/o-ran-smo-teiv-common-yang-types.yang + :language: yang diff --git a/docs/data-models/equipment-to-ran.rst b/docs/data-models/equipment-to-ran.rst new file mode 100644 index 0000000..4bdbb45 --- /dev/null +++ b/docs/data-models/equipment-to-ran.rst @@ -0,0 +1,13 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. SPDX-License-Identifier: CC-BY-4.0 +.. Copyright (C) 2024 Nordix Foundation. All rights Reserved +.. Copyright (C) 2024 OpenInfra Foundation Europe. All Rights Reserved + +Relationship: Equipment RAN +--------------------------- + +.. image:: ../_static/data-model/equipment-ran.svg + :width: 900 + +.. literalinclude:: ../../teiv/src/main/resources/models/o-ran-smo-teiv-equipment-to-ran.yang + :language: yang diff --git a/docs/data-models/equipment.rst b/docs/data-models/equipment.rst new file mode 100644 index 0000000..eecb3aa --- /dev/null +++ b/docs/data-models/equipment.rst @@ -0,0 +1,16 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. SPDX-License-Identifier: CC-BY-4.0 +.. Copyright (C) 2024 Nordix Foundation. All rights Reserved +.. Copyright (C) 2024 OpenInfra Foundation Europe. All Rights Reserved + +Equipment +--------- + +.. image:: ../_static/data-model/equipment.svg + :width: 900 + +.. image:: ../_static/data-model/equipment-relationships.svg + :width: 900 + +.. literalinclude:: ../../teiv/src/main/resources/models/o-ran-smo-teiv-equipment.yang + :language: yang diff --git a/docs/data-models/oam-to-ran.rst b/docs/data-models/oam-to-ran.rst new file mode 100644 index 0000000..853bb17 --- /dev/null +++ b/docs/data-models/oam-to-ran.rst @@ -0,0 +1,13 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. SPDX-License-Identifier: CC-BY-4.0 +.. Copyright (C) 2024 Nordix Foundation. All rights Reserved +.. Copyright (C) 2024 OpenInfra Foundation Europe. All Rights Reserved + +Relationship: OAM RAN +--------------------- + +.. image:: ../_static/data-model/oam-ran.svg + :width: 900 + +.. literalinclude:: ../../teiv/src/main/resources/models/o-ran-smo-teiv-oam-to-ran.yang + :language: yang diff --git a/docs/data-models/oam.rst b/docs/data-models/oam.rst new file mode 100644 index 0000000..e45297d --- /dev/null +++ b/docs/data-models/oam.rst @@ -0,0 +1,13 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. SPDX-License-Identifier: CC-BY-4.0 +.. Copyright (C) 2024 Nordix Foundation. All rights Reserved +.. Copyright (C) 2024 OpenInfra Foundation Europe. All Rights Reserved + +OAM +--- + +.. image:: ../_static/data-model/oam.svg + :width: 900 + +.. literalinclude:: ../../teiv/src/main/resources/models/o-ran-smo-teiv-oam.yang + :language: yang diff --git a/docs/data-models/ran.rst b/docs/data-models/ran.rst new file mode 100644 index 0000000..e9f53ef --- /dev/null +++ b/docs/data-models/ran.rst @@ -0,0 +1,16 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. SPDX-License-Identifier: CC-BY-4.0 +.. Copyright (C) 2024 Nordix Foundation. All rights Reserved +.. Copyright (C) 2024 OpenInfra Foundation Europe. All Rights Reserved + +RAN +--- + +.. image:: ../_static/data-model/ran.svg + :width: 900 + +.. image:: ../_static/data-model/ran-relationships.svg + :width: 900 + +.. literalinclude:: ../../teiv/src/main/resources/models/o-ran-smo-teiv-ran.yang + :language: yang diff --git a/docs/developer-guide.rst b/docs/developer-guide.rst index c89590c..4fd9225 100644 --- a/docs/developer-guide.rst +++ b/docs/developer-guide.rst @@ -116,130 +116,29 @@ ManagedElement, AntennaCapability, and AntennaModule. Supported domains ----------------- -+-------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Domain | Description | -+===================+=============================================================================================================================================================================================================================================================================+ -| RAN | This model contains the topology entities and relations in the RAN domain, which represents the functional capability of the deployed RAN that are relevant to rApps use cases. | -+-------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| EQUIPMENT | This model contains the topology entities and relations in the Equipment domain, which is modelled to understand the physical location of equipment such as antennas associated with a cell/carrier and their relevant properties, for example, tilt, max power, and so on. | -+-------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| OAM | This model contains the topology entities and relations in the O&M domain, which are intended to represent management systems and management interfaces. | -+-------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| REL_EQUIPMENT_RAN | This model contains the topology relations between Equipment and RAN. | -+-------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| REL_OAM_RAN | This model contains the topology relations between O&M and RAN. | -+-------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - - -Retrieving and using topology modules -===================================== - -Topology & Inventory provides APIs to enable users :download:`query module -data <../teiv/src/main/resources/v1/topology-exposure-inventory-openapi.yaml>` -that can be used to understand the existing topology and inventory model, -parse the modules, and understand what objects are supported over the R1 -interface, so adequate queries can be made on topology and inventory data. - -The API endpoints returning lists support pagination. The default value -for number of items returned is 500, which is also the upper limit. - -**Sample request to fetch a list of all modules:** - -:: - - GET https:///topology-inventory//schemas - -To get a list of all modules for a specific domain, use a *domain* query -parameter. For example, /schemas?domain= - -**Sample request to fetch a list of all modules related to the RAN -domain:** - -:: - - GET https:///topology-inventory//schemas?domain=ran - -.. - - **Note:** - Partial matches are also supported in the query parameter - using the ’*’ symbol as a wild card. - If the specified domain does - not exist, an empty list is returned. - -To get a specific module, supply a module name in the path parameter. -For example, /schemas//content - -**Sample request to fetch the module data for the o-ran-smo-teiv-ran -module:** - -:: - - GET https:///topology-inventory//schemas/o-ran-smo-teiv-ran/content - -.. - - **Note:** If the specified module does not exist, an - *INVALID_MODULE_NAME* error is returned. - -Reading and querying topology and inventory -=========================================== - -Reading entities and relationships ----------------------------------- - -To get a list of all entities with all properties in a specified domain -name, use: > /domains/{domainName}/entities - -**Example:** Get all entities in the *RAN* domain: - -:: - - GET https:///topology-inventory//domains/RAN/entities - -To get a list of all available entity types in a specified domain name, -use: > /domains/{domainName}/entity-types - -**Example:** Get all entity types in the *RAN* domain: - -:: - - GET https:///topology-inventory//domains/RAN/entity-types - -To get a list of all available relationship types in a specified domain -name, use: > /domains/{domainName}/relationship-types - -**Example:** Get all relationship types in the *RAN* domain: - -:: - - GET https:///topology-inventory//domains/RAN/relationship-types - -Querying entities and relationships ------------------------------------ - -Use the *targetFilter* parameter to narrow down the fields to return. To -filter the results which match a given criteria, use the *scopeFilter*. -Think of it as an SQL statement, where the *targetFilter* is the SELECT, -and the *scopeFilter* is the WHERE tag. - -A detailed explanation about the *targetFilter* and *scopeFilter* -parameters can be found in :doc:`Supported filter options `. - -**Example:** - -In this example, the user is only interested in NRCellDU entities. -Moreover, the user only wants those records that have sourceIds -containing “SubNetwork=Ireland”. These fields and filters can be defined -in the request as follows: - - **Parameters:** - **targetFilter:** /NRCellDU - **scopeFilter:** - /sourceIds[contains(@item,'SubNetwork=Ireland')] - -:: - - GET https:///topology-inventory//domains/RAN?targetFilter=/NRCellDU&scopeFilter=/sourceIds[contains(@item,'SubNetwork=Ireland')] - -.. - - **Note:** If the targetFilter is not used here, the result contains - all entities and relationships that matches the condition in the RAN - domain. ++-----------------------------------+-------------------------------------------------------+ +| Domain | Description | ++===================================+=======================================================+ +| RAN | | This model contains the topology entities and | +| | | relations in the RAN domain, which represents the | +| | | functional capability of the deployed RAN that | +| | | are relevant to rApps use cases. | ++-----------------------------------+-------------------------------------------------------+ +| EQUIPMENT | | This model contains the topology entities and | +| | | relations in the Equipment domain, which is | +| | | modeled to understand the physical location of | +| | | equipment such as antennas associated with a | +| | | cell/carrier and their relevant properties, for | +| | | example, tilt, max power, and so on. | ++-----------------------------------+-------------------------------------------------------+ +| OAM | | This model contains the topology entities and | +| | | relations in the O&M domain, which are intended | +| | | to represent management systems and management | +| | | interfaces. | ++-----------------------------------+-------------------------------------------------------+ +| REL_EQUIPMENT_RAN | | This model contains the topology relations | +| | | between Equipment and RAN. | ++-----------------------------------+-------------------------------------------------------+ +| REL_OAM_RAN | | This model contains the topology relations | +| | | between O&M and RAN. | ++-----------------------------------+-------------------------------------------------------+ diff --git a/docs/geographical-location-enrichment-api.rst b/docs/geographical-location-enrichment-api.rst index 1966fdc..92fc4ca 100644 --- a/docs/geographical-location-enrichment-api.rst +++ b/docs/geographical-location-enrichment-api.rst @@ -34,25 +34,37 @@ Message Topology CREATE ``ingestionCreate`` CREATE Headers ^^^^^^^^^^^^^^ -+----------------+--------+-----------------------------------------------------------------------------------------------------------------------------------------------+------------------------------+----------------------+---------------------------------------+ -| Name | Type | Description | Value | Constraints | Notes | -+================+========+===============================================================================================================================================+==============================+======================+=======================================+ -| (root) | object | - | - | - | **additional properties are allowed** | -+----------------+--------+-----------------------------------------------------------------------------------------------------------------------------------------------+------------------------------+----------------------+---------------------------------------+ -| ce_id | string | Unique identifier for the event. | - | - | - | -+----------------+--------+-----------------------------------------------------------------------------------------------------------------------------------------------+------------------------------+----------------------+---------------------------------------+ -| ce_source | string | Source of the CloudEvent. | - | format (`uri`) | - | -+----------------+--------+-----------------------------------------------------------------------------------------------------------------------------------------------+------------------------------+----------------------+---------------------------------------+ -| ce_type | string | Event type. It can be one of topology-inventory-ingestion-merge, topology-inventory-ingestion-delete, or topology-inventory-ingestion-create. | - | - | - | -+----------------+--------+-----------------------------------------------------------------------------------------------------------------------------------------------+------------------------------+----------------------+---------------------------------------+ -| content-type | string | Content-type of the data contained within the cloud event. It is application/json. | const (`"application/json"`) | - | - | -+----------------+--------+-----------------------------------------------------------------------------------------------------------------------------------------------+------------------------------+----------------------+---------------------------------------+ -| ce_dataschema | string | URI representing the schema of the data. This references the event-specific yang schema. | - | format (`uri`) | - | -+----------------+--------+-----------------------------------------------------------------------------------------------------------------------------------------------+------------------------------+----------------------+---------------------------------------+ -| ce_time | string | Event timestamp. | - | format (`date-time`) | - | -+----------------+--------+-----------------------------------------------------------------------------------------------------------------------------------------------+------------------------------+----------------------+---------------------------------------+ -| ce_specversion | string | The version of the CloudEvents specification which the event uses. | const (`"1.0"`) | - | - | -+----------------+--------+-----------------------------------------------------------------------------------------------------------------------------------------------+------------------------------+----------------------+---------------------------------------+ ++----------------+--------+-------------------------------------------+--------------------------+-----------------+-------------------+ +| Name | Type | Description | Value | Constraints | Notes | ++================+========+===========================================+==========================+=================+===================+ +| (root) | object | - | - | - | | **additional** | +| | | | | | | **properties** | +| | | | | | | **are allowed** | ++----------------+--------+-------------------------------------------+--------------------------+-----------------+-------------------+ +| ce_id | string | Unique identifier for the event. | - | - | - | ++----------------+--------+-------------------------------------------+--------------------------+-----------------+-------------------+ +| ce_source | string | Source of the CloudEvent. | - | | format | - | +| | | | | | (`uri`) | | ++----------------+--------+-------------------------------------------+--------------------------+-----------------+-------------------+ +| ce_type | string | | Event type. It can be one of | - | - | - | +| | | | topology-inventory-ingestion-merge, | | | | +| | | | topology-inventory-ingestion-delete, or | | | | +| | | | topology-inventory-ingestion-create. | | | | ++----------------+--------+-------------------------------------------+--------------------------+-----------------+-------------------+ +| content-type | string | | Content-type of the data contained | | const | - | - | +| | | | within the cloud event. It is | | (`"application/json"`) | | | +| | | | application/json. | | | | ++----------------+--------+-------------------------------------------+--------------------------+-----------------+-------------------+ +| ce_dataschema | string | | URI representing the schema of the data | - | | format | - | +| | | | This references the event-specific yang | | | (`uri`) | | +| | | | schema. | | | | ++----------------+--------+-------------------------------------------+--------------------------+-----------------+-------------------+ +| ce_time | string | Event timestamp. | - | | format | - | +| | | | | | (`date-time`) | | ++----------------+--------+-------------------------------------------+--------------------------+-----------------+-------------------+ +| ce_specversion | string | | The version of the CloudEvents | const (`"1.0"`) | - | - | +| | | | specification which the event uses. | | | | ++----------------+--------+-------------------------------------------+--------------------------+-----------------+-------------------+ .. @@ -73,21 +85,34 @@ CREATE Headers CREATE Payload ^^^^^^^^^^^^^^ -+------------------------------------------------------------------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Name | Type | Description | -+==================================================================+===============+===========================================================================================================================================================================================================================================================================================================================================+ -| (root) | Object | - | -+------------------------------------------------------------------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| data | - | The data part consists of the actual topology data. It contains all the entities and their associated relationships. | -+------------------------------------------------------------------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| data.entities | Array | Entities are topology objects comprising of an id, consumer data, attributes and metadata for each. It contains the id only in case of delete cloud event. | -+------------------------------------------------------------------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| data.entities.: | Object | Entities schema is adherent to the entity types and attributes mentioned in the yang modules. For yang modules, see [Data Models][Data Models]. | -+------------------------------------------------------------------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| data.relationships | Array | Relationships comprising of an A-side and a B-side for each. The A-side is considered the originating side of the relationship; the B-side is considered the terminating side of the relationship. The order of A-side and B-side is of importance and MUST NOT be changed once defined. It contains the id only in case of delete event. | -+------------------------------------------------------------------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| data.relationships.: | Object | Relationship schema is adherent to the relationship types mentioned in the yang modules. For yang modules, see [Data Models][Data Models]. | -+------------------------------------------------------------------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ ++------------------------------------------------------+---------------+----------------------------------------------------------------+ +| Name | Type | Description | ++======================================================+===============+================================================================+ +| (root) | Object | - | ++------------------------------------------------------+---------------+----------------------------------------------------------------+ +| data | - | | The data part consists of the actual topology data. It | +| | | | contains all the entities and their associated | +| | | | relationships. | ++------------------------------------------------------+---------------+----------------------------------------------------------------+ +| data.entities | Array | | Entities are topology objects comprising of an id, consumer | +| | | | data, attributes and metadata for each. It contains the id | +| | | | only in case of delete cloud event. | ++------------------------------------------------------+---------------+----------------------------------------------------------------+ +| | data.entities | Object | | Entities schema is adherent to the entity types and | +| | . | | | attributes mentioned in the yang modules. For yang modules, | +| | : | | | see [Data Models][Data Models]. | ++------------------------------------------------------+---------------+----------------------------------------------------------------+ +| data.relationships | Array | | Relationships comprising of an A-side and a B-side for each. | +| | | | The A-side is considered the originating side of the | +| | | | relationship; the B-side is considered the terminating side | +| | | | of the relationship. The order of A-side and B-side is of | +| | | | importance and MUST NOT be changed once defined. It | +| | | | contains the id only in case of delete event. | ++------------------------------------------------------+---------------+----------------------------------------------------------------+ +| | data.relationships | Object | | Relationship schema is adherent to the relationship types | +| | . | | | mentioned in the yang modules. For yang modules, | +| | : | | | see [Data Models][Data Models]. | ++------------------------------------------------------+---------------+----------------------------------------------------------------+ Examples of payload *(generated)* @@ -208,25 +233,37 @@ Message Topology MERGE ``ingestionMerge`` MERGE Headers ^^^^^^^^^^^^^ -+----------------+--------+-----------------------------------------------------------------------------------------------------------------------------------------------+------------------------------+----------------------+---------------------------------------+ -| Name | Type | Description | Value | Constraints | Notes | -+================+========+===============================================================================================================================================+==============================+======================+=======================================+ -| (root) | object | - | - | - | **additional properties are allowed** | -+----------------+--------+-----------------------------------------------------------------------------------------------------------------------------------------------+------------------------------+----------------------+---------------------------------------+ -| ce_id | string | Unique identifier for the event. | - | - | - | -+----------------+--------+-----------------------------------------------------------------------------------------------------------------------------------------------+------------------------------+----------------------+---------------------------------------+ -| ce_source | string | Source of the CloudEvent. | - | format (`uri`) | - | -+----------------+--------+-----------------------------------------------------------------------------------------------------------------------------------------------+------------------------------+----------------------+---------------------------------------+ -| ce_type | string | Event type. It can be one of topology-inventory-ingestion-merge, topology-inventory-ingestion-delete, or topology-inventory-ingestion-create. | - | - | - | -+----------------+--------+-----------------------------------------------------------------------------------------------------------------------------------------------+------------------------------+----------------------+---------------------------------------+ -| content-type | string | Content-type of the data contained within the cloud event. It is application/json. | const (`"application/json"`) | - | - | -+----------------+--------+-----------------------------------------------------------------------------------------------------------------------------------------------+------------------------------+----------------------+---------------------------------------+ -| ce_dataschema | string | URI representing the schema of the data. This references the event-specific yang schema. | - | format (`uri`) | - | -+----------------+--------+-----------------------------------------------------------------------------------------------------------------------------------------------+------------------------------+----------------------+---------------------------------------+ -| ce_time | string | Event timestamp. | - | format (`date-time`) | - | -+----------------+--------+-----------------------------------------------------------------------------------------------------------------------------------------------+------------------------------+----------------------+---------------------------------------+ -| ce_specversion | string | The version of the CloudEvents specification which the event uses. | const (`"1.0"`) | - | - | -+----------------+--------+-----------------------------------------------------------------------------------------------------------------------------------------------+------------------------------+----------------------+---------------------------------------+ ++----------------+--------+-------------------------------------------+--------------------------+-----------------+-------------------+ +| Name | Type | Description | Value | Constraints | Notes | ++================+========+===========================================+==========================+=================+===================+ +| (root) | object | - | - | - | | **additional** | +| | | | | | | **properties** | +| | | | | | | **are allowed** | ++----------------+--------+-------------------------------------------+--------------------------+-----------------+-------------------+ +| ce_id | string | Unique identifier for the event. | - | - | - | ++----------------+--------+-------------------------------------------+--------------------------+-----------------+-------------------+ +| ce_source | string | Source of the CloudEvent. | - | | format | - | +| | | | | | (`uri`) | | ++----------------+--------+-------------------------------------------+--------------------------+-----------------+-------------------+ +| ce_type | string | | Event type. It can be one of | - | - | - | +| | | | topology-inventory-ingestion-merge, | | | | +| | | | topology-inventory-ingestion-delete, or | | | | +| | | | topology-inventory-ingestion-create. | | | | ++----------------+--------+-------------------------------------------+--------------------------+-----------------+-------------------+ +| content-type | string | | Content-type of the data contained | | const | - | - | +| | | | within the cloud event. It is | | (`"application/json"`) | | | +| | | | application/json. | | | | ++----------------+--------+-------------------------------------------+--------------------------+-----------------+-------------------+ +| ce_dataschema | string | | URI representing the schema of the data | - | | format | - | +| | | | This references the event-specific yang | | | (`uri`) | | +| | | | schema. | | | | ++----------------+--------+-------------------------------------------+--------------------------+-----------------+-------------------+ +| ce_time | string | Event timestamp. | - | | format | - | +| | | | | | (`date-time`) | | ++----------------+--------+-------------------------------------------+--------------------------+-----------------+-------------------+ +| ce_specversion | string | | The version of the CloudEvents | const (`"1.0"`) | - | - | +| | | | specification which the event uses. | | | | ++----------------+--------+-------------------------------------------+--------------------------+-----------------+-------------------+ .. @@ -248,21 +285,34 @@ MERGE Headers MERGE Payload ^^^^^^^^^^^^^ -+------------------------------------------------------------------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Name | Type | Description | -+==================================================================+===============+===========================================================================================================================================================================================================================================================================================================================================+ -| (root) | Object | - | -+------------------------------------------------------------------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| data | - | The data part consists of the actual topology data. It contains all the entities and their associated relationships. | -+------------------------------------------------------------------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| data.entities | Array | Entities are topology objects comprising of an id, consumer data, attributes and metadata for each. It contains the id only in case of delete cloud event. | -+------------------------------------------------------------------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| data.entities.: | Object | Entities schema is adherent to the entity types and attributes mentioned in the yang modules. For yang modules, see [Data Models][Data Models]. | -+------------------------------------------------------------------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| data.relationships | Array | Relationships comprising of an A-side and a B-side for each. The A-side is considered the originating side of the relationship; the B-side is considered the terminating side of the relationship. The order of A-side and B-side is of importance and MUST NOT be changed once defined. It contains the id only in case of delete event. | -+------------------------------------------------------------------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| data.relationships.: | Object | Relationship schema is adherent to the relationship types mentioned in the yang modules. For yang modules, see [Data Models][Data Models]. | -+------------------------------------------------------------------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ ++------------------------------------------------------+---------------+----------------------------------------------------------------+ +| Name | Type | Description | ++======================================================+===============+================================================================+ +| (root) | Object | - | ++------------------------------------------------------+---------------+----------------------------------------------------------------+ +| data | - | | The data part consists of the actual topology data. It | +| | | | contains all the entities and their associated | +| | | | relationships. | ++------------------------------------------------------+---------------+----------------------------------------------------------------+ +| data.entities | Array | | Entities are topology objects comprising of an id, consumer | +| | | | data, attributes and metadata for each. It contains the id | +| | | | only in case of delete cloud event. | ++------------------------------------------------------+---------------+----------------------------------------------------------------+ +| | data.entities | Object | | Entities schema is adherent to the entity types and | +| | . | | | attributes mentioned in the yang modules. For yang modules, | +| | : | | | see [Data Models][Data Models]. | ++------------------------------------------------------+---------------+----------------------------------------------------------------+ +| data.relationships | Array | | Relationships comprising of an A-side and a B-side for each. | +| | | | The A-side is considered the originating side of the | +| | | | relationship; the B-side is considered the terminating side | +| | | | of the relationship. The order of A-side and B-side is of | +| | | | importance and MUST NOT be changed once defined. It | +| | | | contains the id only in case of delete event. | ++------------------------------------------------------+---------------+----------------------------------------------------------------+ +| | data.relationships | Object | | Relationship schema is adherent to the relationship types | +| | . | | | mentioned in the yang modules. For yang modules, | +| | : | | | see [Data Models][Data Models]. | ++------------------------------------------------------+---------------+----------------------------------------------------------------+ .. @@ -385,25 +435,37 @@ Message Topology DELETE ``ingestionDelete`` DELETE Headers ^^^^^^^^^^^^^^ -+----------------+--------+-----------------------------------------------------------------------------------------------------------------------------------------------+------------------------------+----------------------+---------------------------------------+ -| Name | Type | Description | Value | Constraints | Notes | -+================+========+===============================================================================================================================================+==============================+======================+=======================================+ -| (root) | object | - | - | - | **additional properties are allowed** | -+----------------+--------+-----------------------------------------------------------------------------------------------------------------------------------------------+------------------------------+----------------------+---------------------------------------+ -| ce_id | string | Unique identifier for the event. | - | - | - | -+----------------+--------+-----------------------------------------------------------------------------------------------------------------------------------------------+------------------------------+----------------------+---------------------------------------+ -| ce_source | string | Source of the CloudEvent. | - | format (`uri`) | - | -+----------------+--------+-----------------------------------------------------------------------------------------------------------------------------------------------+------------------------------+----------------------+---------------------------------------+ -| ce_type | string | Event type. It can be one of topology-inventory-ingestion-merge, topology-inventory-ingestion-delete, or topology-inventory-ingestion-create. | - | - | - | -+----------------+--------+-----------------------------------------------------------------------------------------------------------------------------------------------+------------------------------+----------------------+---------------------------------------+ -| content-type | string | Content-type of the data contained within the cloud event. It is application/json. | const (`"application/json"`) | - | - | -+----------------+--------+-----------------------------------------------------------------------------------------------------------------------------------------------+------------------------------+----------------------+---------------------------------------+ -| ce_dataschema | string | URI representing the schema of the data. This references the event-specific yang schema. | - | format (`uri`) | - | -+----------------+--------+-----------------------------------------------------------------------------------------------------------------------------------------------+------------------------------+----------------------+---------------------------------------+ -| ce_time | string | Event timestamp. | - | format (`date-time`) | - | -+----------------+--------+-----------------------------------------------------------------------------------------------------------------------------------------------+------------------------------+----------------------+---------------------------------------+ -| ce_specversion | string | The version of the CloudEvents specification which the event uses. | const (`"1.0"`) | - | - | -+----------------+--------+-----------------------------------------------------------------------------------------------------------------------------------------------+------------------------------+----------------------+---------------------------------------+ ++----------------+--------+-------------------------------------------+--------------------------+-----------------+-------------------+ +| Name | Type | Description | Value | Constraints | Notes | ++================+========+===========================================+==========================+=================+===================+ +| (root) | object | - | - | - | | **additional** | +| | | | | | | **properties** | +| | | | | | | **are allowed** | ++----------------+--------+-------------------------------------------+--------------------------+-----------------+-------------------+ +| ce_id | string | Unique identifier for the event. | - | - | - | ++----------------+--------+-------------------------------------------+--------------------------+-----------------+-------------------+ +| ce_source | string | Source of the CloudEvent. | - | | format | - | +| | | | | | (`uri`) | | ++----------------+--------+-------------------------------------------+--------------------------+-----------------+-------------------+ +| ce_type | string | | Event type. It can be one of | - | - | - | +| | | | topology-inventory-ingestion-merge, | | | | +| | | | topology-inventory-ingestion-delete, or | | | | +| | | | topology-inventory-ingestion-create. | | | | ++----------------+--------+-------------------------------------------+--------------------------+-----------------+-------------------+ +| content-type | string | | Content-type of the data contained | | const | - | - | +| | | | within the cloud event. It is | | (`"application/json"`) | | | +| | | | application/json. | | | | ++----------------+--------+-------------------------------------------+--------------------------+-----------------+-------------------+ +| ce_dataschema | string | | URI representing the schema of the data | - | | format | - | +| | | | This references the event-specific yang | | | (`uri`) | | +| | | | schema. | | | | ++----------------+--------+-------------------------------------------+--------------------------+-----------------+-------------------+ +| ce_time | string | Event timestamp. | - | | format | - | +| | | | | | (`date-time`) | | ++----------------+--------+-------------------------------------------+--------------------------+-----------------+-------------------+ +| ce_specversion | string | | The version of the CloudEvents | const (`"1.0"`) | - | - | +| | | | specification which the event uses. | | | | ++----------------+--------+-------------------------------------------+--------------------------+-----------------+-------------------+ .. @@ -424,21 +486,34 @@ DELETE Headers DELETE Payload ^^^^^^^^^^^^^^ -+------------------------------------------------------------------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Name | Type | Description | -+==================================================================+===============+===========================================================================================================================================================================================================================================================================================================================================+ -| (root) | Object | - | -+------------------------------------------------------------------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| data | - | The data part consists of the actual topology data. It contains all the entities and their associated relationships. | -+------------------------------------------------------------------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| data.entities | Array | Entities are topology objects comprising of an id, consumer data, attributes and metadata for each. It contains the id only in case of delete cloud event. | -+------------------------------------------------------------------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| data.entities.: | Object | Entities schema is adherent to the entity types and attributes mentioned in the yang modules. For yang modules, see [Data Models][Data Models]. | -+------------------------------------------------------------------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| data.relationships | Array | Relationships comprising of an A-side and a B-side for each. The A-side is considered the originating side of the relationship; the B-side is considered the terminating side of the relationship. The order of A-side and B-side is of importance and MUST NOT be changed once defined. It contains the id only in case of delete event. | -+------------------------------------------------------------------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| data.relationships.: | Object | Relationship schema is adherent to the relationship types mentioned in the yang modules. For yang modules, see [Data Models][Data Models]. | -+------------------------------------------------------------------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ ++------------------------------------------------------+---------------+----------------------------------------------------------------+ +| Name | Type | Description | ++======================================================+===============+================================================================+ +| (root) | Object | - | ++------------------------------------------------------+---------------+----------------------------------------------------------------+ +| data | - | | The data part consists of the actual topology data. It | +| | | | contains all the entities and their associated | +| | | | relationships. | ++------------------------------------------------------+---------------+----------------------------------------------------------------+ +| data.entities | Array | | Entities are topology objects comprising of an id, consumer | +| | | | data, attributes and metadata for each. It contains the id | +| | | | only in case of delete cloud event. | ++------------------------------------------------------+---------------+----------------------------------------------------------------+ +| | data.entities | Object | | Entities schema is adherent to the entity types and | +| | . | | | attributes mentioned in the yang modules. For yang modules, | +| | : | | | see [Data Models][Data Models]. | ++------------------------------------------------------+---------------+----------------------------------------------------------------+ +| data.relationships | Array | | Relationships comprising of an A-side and a B-side for each. | +| | | | The A-side is considered the originating side of the | +| | | | relationship; the B-side is considered the terminating side | +| | | | of the relationship. The order of A-side and B-side is of | +| | | | importance and MUST NOT be changed once defined. It | +| | | | contains the id only in case of delete event. | ++------------------------------------------------------+---------------+----------------------------------------------------------------+ +| | data.relationships | Object | | Relationship schema is adherent to the relationship types | +| | . | | | mentioned in the yang modules. For yang modules, | +| | : | | | see [Data Models][Data Models]. | ++------------------------------------------------------+---------------+----------------------------------------------------------------+ .. diff --git a/docs/index.rst b/docs/index.rst index f1568fd..45cc845 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -17,7 +17,9 @@ to share and operate on a common view of the topology. :caption: Contents: ./developer-guide.rst + ./query-api-examples.rst ./data-models-guide.rst ./geographical-location-enrichment-guide.rst ./geographical-location-enrichment-api.rst ./supported-filter-options.rst + ./api-documentation.rst diff --git a/docs/query-api-examples.rst b/docs/query-api-examples.rst new file mode 100644 index 0000000..3ff539a --- /dev/null +++ b/docs/query-api-examples.rst @@ -0,0 +1,121 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. SPDX-License-Identifier: CC-BY-4.0 +.. Copyright (C) 2024 Nordix Foundation. All rights Reserved +.. Copyright (C) 2024 OpenInfra Foundation Europe. All Rights Reserved + +Query API examples +################## + +Retrieving and using topology modules +===================================== + +Topology & Inventory provides APIs to enable users :doc:`query module data +` that can be used to understand the existing +topology and inventory model,parse the modules, and understand what objects +are supported over the R1 interface, so adequate queries can be made on +topology and inventory data. + +The API endpoints returning lists support pagination. The default value +for number of items returned is 500, which is also the upper limit. + +**Sample request to fetch a list of all modules:** + +:: + + GET https:///topology-inventory//schemas + +To get a list of all modules for a specific domain, use a *domain* query +parameter. For example, /schemas?domain= + +**Sample request to fetch a list of all modules related to the RAN +domain:** + +:: + + GET https:///topology-inventory//schemas?domain=ran + +.. + + **Note:** - Partial matches are also supported in the query parameter + using the ’*’ symbol as a wild card. - If the specified domain does + not exist, an empty list is returned. + +To get a specific module, supply a module name in the path parameter. +For example, /schemas//content + +**Sample request to fetch the module data for the o-ran-smo-teiv-ran +module:** + +:: + + GET https:///topology-inventory//schemas/o-ran-smo-teiv-ran/content + +.. + + **Note:** If the specified module does not exist, an + *INVALID_MODULE_NAME* error is returned. + +Reading and querying topology and inventory +=========================================== + +Reading entities and relationships +---------------------------------- + +To get a list of all entities with all properties in a specified domain +name, use: > /domains/{domainName}/entities + +**Example:** Get all entities in the *RAN* domain: + +:: + + GET https:///topology-inventory//domains/RAN/entities + +To get a list of all available entity types in a specified domain name, +use: > /domains/{domainName}/entity-types + +**Example:** Get all entity types in the *RAN* domain: + +:: + + GET https:///topology-inventory//domains/RAN/entity-types + +To get a list of all available relationship types in a specified domain +name, use: > /domains/{domainName}/relationship-types + +**Example:** Get all relationship types in the *RAN* domain: + +:: + + GET https:///topology-inventory//domains/RAN/relationship-types + +Querying entities and relationships +----------------------------------- + +Use the *targetFilter* parameter to narrow down the fields to return. To +filter the results which match a given criteria, use the *scopeFilter*. +Think of it as an SQL statement, where the *targetFilter* is the SELECT, +and the *scopeFilter* is the WHERE tag. + +A detailed explanation about the *targetFilter* and *scopeFilter* +parameters can be found in :doc:`Supported filter options +`. + +**Example:** + +In this example, the user is only interested in NRCellDU entities. +Moreover, the user only wants those records that have sourceIds +containing “SubNetwork=Ireland”. These fields and filters can be defined +in the request as follows: + + **Parameters:** - **targetFilter:** /NRCellDU - **scopeFilter:** + /sourceIds[contains(@item,'SubNetwork=Ireland')] + +:: + + GET https:///topology-inventory//domains/RAN?targetFilter=/NRCellDU&scopeFilter=/sourceIds[contains(@item,'SubNetwork=Ireland')] + +.. + + **Note:** If the targetFilter is not used here, the result contains + all entities and relationships that matches the condition in the RAN + domain. diff --git a/docs/requirements-docs.txt b/docs/requirements-docs.txt index fb15e65..0d32a5a 100644 --- a/docs/requirements-docs.txt +++ b/docs/requirements-docs.txt @@ -1,6 +1,7 @@ tox -Sphinx +sphinx doc8 -docutils < 0.17 +docutils +sphinxcontrib-openapi lfdocs-conf urllib3~=1.26.15 \ No newline at end of file diff --git a/docs/supported-filter-options.rst b/docs/supported-filter-options.rst index c76f9a0..476a1fd 100644 --- a/docs/supported-filter-options.rst +++ b/docs/supported-filter-options.rst @@ -18,9 +18,8 @@ Sample structure using target and scope filters: .. - See :download:`Topology & Inventory - API <../teiv/src/main/resources/v1/topology-exposure-inventory-openapi.yaml>` - for all possible filter options and sample responses for each endpoint. + See :doc:`Topology & Inventory API ` for all possible + filter options and sample responses for each endpoint. Querying simple entities ------------------------ @@ -36,24 +35,59 @@ joined to it. If there is no connection between the RootObject and the other object(s), the query is not constructed. The RootObject still can be retrieved and filtered using the /attributes. -+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------+----------------+---------------------------------+-----------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------+ -| Use case | domainName | entityTypeName | targetFilter | scopeFilter | Query result | -+======================================================================================================================================================================================================================================================================================================================================================================================================+============+================+=================================+=========================================================================================+=======================================================================================================================================+ -| To return the ids for all instances of the entityTypeName used in the query. | RAN | GNBDUFunction | | | All ids of every GNBDUFunction | -+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------+----------------+---------------------------------+-----------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------+ -| To return all attributes of every instance of the entityTypeName used in the query. | RAN | GNBDUFunction | /attributes | | All GNBDUFunctions with every attribute | -+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------+----------------+---------------------------------+-----------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------+ -| To return every instance of the entityTypeName used in the query, but only the attribute that was defined in the *targetFilter* parameter.
Note: The attribute must be a valid field of the object. | RAN | GNBDUFunction | /attributes(gNBId) | | All gNBIds of every GNBDUFunction | -+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------+----------------+---------------------------------+-----------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------+ -| To return every instance of the entityTypeName used in the query, but only the attributes that were defined in the *targetFilter* parameter.
Note: The attributes must be separated by a comma "," when using parenthesis "()". | RAN | GNBDUFunction | /attributes(gNBId, gNBIdLength) | | All gNBIds and gNBIdLengths of every GNBDUFunction | -+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------+----------------+---------------------------------+-----------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------+ -| To return the ids for all instances of the entityTypeName used in the query, that matches the given property in the *scopeFilter* parameter. | RAN | GNBDUFunction | | /sourceIds[contains (@item, 'SubNetwork=Ireland')] | Unique set of ids of GNBDUFunctions, where sourceIds contains *SubNetwork=Ireland* | -+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------+----------------+---------------------------------+-----------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------+ -| To return the ids for all instances of the entityTypeName used in the query, that matches the given attributes in the *scopeFilter* parameter.
Note: The attributes must be separated by a *AND* or *OR*". | RAN | GNBDUFunction | | /attributes [@gNBIdLength=3 and @gNBId=111] | Unique set of ids of GNBDUFunctions, where the gNBIdLength equals 3 and the gNBId equals 111 | -+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------+----------------+---------------------------------+-----------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------+ -| To return the ids for all instances of the entityTypeName used in the query, that satisfies one of the conditions in the *scopeFilter* parameter. A condition is a complete unit of *scopeFilter* parameter surrounded by square brackets.
Note: Multiple conditions can be given in the scopeFilter separated by a semicolon ";" to represent AND, or a pipe symbol "|" to represent OR. | RAN | GNBDUFunction | | /attributes [@gNBIdLength=3] | /sourceIds[contains (@item, 'SubNetwork=Ireland')] | Unique set of ids of GNBDUFunctions, where where the gNBIdLength equals 3 or the sourceIds contains an item with "SubNetwork=Ireland" | -+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------+----------------+---------------------------------+-----------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------+ - ++------------------------------------------+--------+----------------+--------------+------------------------+------------------------+ +| Use case | domain | entityTypeName | targetFilter | scopeFilter | Query result | +| | | | | | | +| | Name | | | | | ++==========================================+========+================+==============+========================+========================+ +| | To return the ids for all instances of | RAN | GNBDUFunction | | | | All ids of every | +| | the entityTypeName used in the query. | | | | | | GNBDUFunction | ++------------------------------------------+--------+----------------+--------------+------------------------+------------------------+ +| | To return all attributes of every | RAN | GNBDUFunction | /attributes | | | All GNBDUFunctions | +| | instance of the entityTypeName used | | | | | | with every attribute | +| | in the query. | | | | | | ++------------------------------------------+--------+----------------+--------------+------------------------+------------------------+ +| | To return every instance of the | RAN | GNBDUFunction | /attributes | | | All gNBIds of every | +| | entityTypeName used in the query, but | | | (gNBId) | | | GNBDUFunction | +| | only the attribute that was | | | | | | +| | defined in the *targetFilter* | | | | | | +| | parameter. Note: The attribute must be | | | | | | +| | a valid field of the object. | | | | | | ++------------------------------------------+--------+----------------+--------------+------------------------+------------------------+ +| | To return every instance of the | RAN | GNBDUFunction | /attributes | | | All gNBIds and | +| | entityTypeName used in the query, but | | | | | | gNBIdLengths of | +| | only the attributes that were | | | (gNBId, | | | every GNBDUFunction | +| | defined in the *targetFilter* | | | gNBIdLength) | | | +| | parameter. Note: The attributes must | | | | | | +| | be separated by a comma "," when | | | | | | +| | using parenthesis "()". | | | | | | ++------------------------------------------+--------+----------------+--------------+------------------------+------------------------+ +| | To return the ids for all instances of | RAN | GNBDUFunction | | /sourceIds | | Unique set of ids | +| | the entityTypeName used in the query, | | | | [contains (@item, | | of GNBDUFunctions, | +| | that matches the given | | | | 'SubNetwork=Ireland')] | | where sourceIds | +| | property in the *scopeFilter* | | | | | | contains | +| | parameter. | | | | | | *SubNetwork=Ireland* | ++------------------------------------------+--------+----------------+--------------+------------------------+------------------------+ +| | To return the ids for all instances of | RAN | GNBDUFunction | | /attributes | | Unique set of ids of | +| | the entityTypeName used in the query, | | | | [@gNBId | | GNBDUFunctions,where | +| | that matches the given attributes in | | | | Length=3 and | | the gNBIdLength | +| | the *scopeFilter* parameter. Note: The | | | | @gNBId=111] | | equals 3 and the | +| | attributes must be separated by a | | | | | | gNBId equals 111 | +| | *AND* or *OR*". | | | | | | ++------------------------------------------+--------+----------------+--------------+------------------------+------------------------+ +| | To return the ids for all instances of | RAN | GNBDUFunction | | /attributes | | Unique set of ids of | +| | the entityTypeName used in the query, | | | | [@gNBId Length=3] | | GNBDUFunctions, | +| | that satisfies one of | | | | | | | where the | +| | the conditions in the *scopeFilter* | | | | | | gNBIdLength equals 3 | +| | parameter. A condition is a complete | | | | /sourceIds | | or the sourceIds | +| | unit of *scopeFilter* | | | | [contains (@item, | | contains an item | +| | represent OR. | | | | 'SubNetwork=Ireland')] | | with | +| | parameter surrounded by square | | | | | | "SubNetwork=Ireland" | +| | brackets. Note: Multiple conditions | | | | | | +| | can be given in the scopeFilter | | | | | | +| | separated by a semicolon ";" to | | | | | | +| | represent AND, or a pipe symbol "|" to | | | | | | ++------------------------------------------+--------+----------------+--------------+------------------------+------------------------+ Querying connected entities --------------------------- @@ -64,15 +98,33 @@ Querying connected entities The *entityTypeName* is used as the root of the queries. -+------------------------------------------------------------------------------------------------------------------------------------------------+-------------+----------------+--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Use case | domainName | entityTypeName | targetFilter | scopeFilter | Query result | -+================================================================================================================================================+=============+================+==============+==================================================================================================================================================================================================================================================+===============================================================================================================================================================================================================================+ -| To return the ids for all instances of an entityTypeName related by an association. | REL_OAM_RAN | ENodeBFunction | | /managed-by-managedElement | All ENodeBFunction entities that are managed by any Managed Element. | -+------------------------------------------------------------------------------------------------------------------------------------------------+-------------+----------------+--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| To return the ids for all instances of an entityTypeName related by an association to another entity specified by its *id*. | REL_OAM_RAN | ENodeBFunction | | /managed-by-managedElement [@id = 'urn\:3gpp:dn: ManagedElement=1'] | All ENodeBFunction entities that are managed by by the Managed Element *urn\:3gpp:dn: ManagedElement=1*. | -+------------------------------------------------------------------------------------------------------------------------------------------------+-------------+----------------+--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| To return the attributes for all instances of an entityTypeName related by one or more associations to other entities specified by their *id*. | REL_OAM_RAN | ENodeBFunction | /attributes | /attributes [@enbId=1] ; /managed-by-managedElement [@id='urn\:3gpp:dn: ManagedElement=1'] | /managed-by-managedElement [@id='urn\:3gpp:dn: ManagedElement=2'] ; /provided-euTranCell [@id='urn\:3gpp:dn: ManagedElement=1, EUtranCell=2'] | All EnodeBFunction entities with enbId as *1* managed by the Managed Element *urn\:3gpp:dn: ManagedElement=1* or *urn\:3gpp:dn: ManagedElement=2*, and provides EuTranCell *urn\:3gpp:dn: ManagedElement=1, EUtranCell=2*. | -+------------------------------------------------------------------------------------------------------------------------------------------------+-------------+----------------+--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ ++------------------------------------------+-------------+----------------+--------------+----------------------------+--------------------------------------------------+ +| Use case | domainName | entityTypeName | targetFilter | scopeFilter | Query result | ++==========================================+=============+================+==============+============================+==================================================+ +| | To return the ids for all instances of | REL_OAM_RAN | ENodeBFunction | | /managed-by-managedElement | | All ENodeBFunction entities that are managed | +| | an entityTypeName related by an | | | | | | by any Managed Element. | +| | association. | | | | | | ++------------------------------------------+-------------+----------------+--------------+----------------------------+--------------------------------------------------+ +| | To return the ids for all instances of | REL_OAM_RAN | ENodeBFunction | | /managed-by-managedElement | | All ENodeBFunction entities that are managed | +| | an entityTypeName related by an | | | | [@id = 'urn\:3gpp:dn: | | by the Managed Element | +| | association to another entity | | | | ManagedElement=1'] | | *urn\:3gpp:dn: ManagedElement=1*. | +| | specified by its *id*. | | | | | | ++------------------------------------------+-------------+----------------+--------------+----------------------------+--------------------------------------------------+ +| | To return the attributes for all | REL_OAM_RAN | ENodeBFunction | /attributes | /attributes [@enbId=1]; | | All EnodeBFunction entities with enbId as *1* | +| | instances of an entityTypeName | | | | | | managed by the Managed Element | +| | related by one or more associations | | | | /managed-by-managedElement | | *urn\:3gpp:dn: ManagedElement=1* or | +| | to other entities specified by their | | | | [@id='urn\:3gpp:dn: | | *urn\:3gpp:dn: ManagedElement=2*, | +| | *id*. | | | | ManagedElement=1'] | | | and provides EuTranCell | +| | | | | | | *urn\:3gpp:dn: ManagedElement=1, EUtranCell=2* | +| | | | | /managed-by-managedElement | | +| | | | | [@id='urn\:3gpp:dn: | | +| | | | | ManagedElement=2'] ; | | +| | | | | | | +| | | | | /provided-euTranCell | | +| | | | | [@id='urn\:3gpp:dn: | | +| | | | | ManagedElement=1, | | +| | | | | EUtranCell=2'] | | ++------------------------------------------+-------------+----------------+--------------+----------------------------+--------------------------------------------------+ Querying entities for relationships @@ -83,16 +135,25 @@ Querying entities for relationships The *entityTypeName* is used as the root of the queries. -+--------------------------------------------------------------------------------------------------------------------+------------+----------------+-------------------------------------------------+--------------+---------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Use case | domainName | entityTypeName | entityId | targetFilter | scopeFilter | Query result | -+====================================================================================================================+============+================+=================================================+==============+=====================================================================+=======================================================================================================================================================================================================+ -| To return the relationships for a given entity specified by its id. | RAN | GNBDUFunction | urn\:3gpp:dn: ManagedElement=1, GNBDUFunction=1 | | | All relations for the GNBDUFunction with id *urn\:3gpp:dn: ManagedElement=1, GNBDUFunction=1*. | -+--------------------------------------------------------------------------------------------------------------------+------------+----------------+-------------------------------------------------+--------------+---------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| To return specific relationships for a given entity specified by its id. | RAN | GNBDUFunction | urn\:3gpp:dn: ManagedElement=1, GNBDUFunction=1 | | /MANAGEDELEMENT _MANAGES _GNBDUFUNCTION | All *MANAGEDELEMENT _MANAGES _GNBDUFUNCTION* relations for the GNBDUFunction with id *urn\:3gpp:dn: ManagedElement=1, GNBDUFunction=1*. | -+--------------------------------------------------------------------------------------------------------------------+------------+----------------+-------------------------------------------------+--------------+---------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| To return specific relationships for an entity specified by its id to another entity using its id and association. | RAN | GNBDUFunction | urn\:3gpp:dn: ManagedElement=1, GNBDUFunction=1 | | /managed-by-managedElement [@id = 'urn\:3gpp:dn: ManagedElement=1'] | All *MANAGEDELEMENT _MANAGES _GNBDUFUNCTION* relations for the GNBDUFunction with id *urn\:3gpp:dn: ManagedElement=1, GNBDUFunction=1* where the managed element is *urn\:3gpp:dn: ManagedElement=1*. | -+--------------------------------------------------------------------------------------------------------------------+------------+----------------+-------------------------------------------------+--------------+---------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - ++------------------------------------------+--------+----------------+-------------------+--------+----------------------------+-----------------------------------------------------+ +| Use case | domain | entityTypeName | entityId | target | scopeFilter | Query result | +| | | | | | | | +| | Name | | | Filter | | | ++==========================================+========+================+===================+========+============================+=====================================================+ +| | To return the relationships for a | RAN | GNBDUFunction | urn\:3gpp:dn: | | | | All relations for the GNBDUFunction with id | +| | given entity specified by its id. | | | ManagedElement=1, | | | | *urn\:3gpp:dn: ManagedElement=1, GNBDUFunction=1* | +| | | | GNBDUFunction=1 | | | | ++------------------------------------------+--------+----------------+-------------------+--------+----------------------------+-----------------------------------------------------+ +| | To return specific relationships for a | RAN | GNBDUFunction | urn\:3gpp:dn: | | /MANAGEDELEMENT | | All *MANAGEDELEMENT _MANAGES _GNBDUFUNCTION* | +| | given entity specified by its id. | | | ManagedElement=1, | | _MANAGES | | relations for the GNBDUFunction with id | +| | | | GNBDUFunction=1 | | _GNBDUFUNCTION | | *urn\:3gpp:dn: ManagedElement=1, GNBDUFunction=1* | ++------------------------------------------+--------+----------------+-------------------+--------+----------------------------+-----------------------------------------------------+ +| | To return specific relationships for | RAN | GNBDUFunction | urn\:3gpp:dn: | | /managed-by-managedElement | | All *MANAGEDELEMENT _MANAGES _GNBDUFUNCTION* | +| | an entity specified by its id to | | | ManagedElement=1, | | [@id = 'urn\:3gpp:dn: | | relations for the GNBDUFunction with id | +| | another entity using its id and | | | GNBDUFunction=1 | | ManagedElement=1'] | | *urn\:3gpp:dn: ManagedElement=1, GNBDUFunction=1* | +| | association. | | | | | | | where the managed element is | +| | | | | | | | *urn\:3gpp:dn: ManagedElement=1*. | ++------------------------------------------+--------+----------------+-------------------+--------+----------------------------+-----------------------------------------------------+ Querying on relationships ------------------------- @@ -102,14 +163,20 @@ Querying on relationships Here, the *relationshipTypeName* is used as the root of the queries. -+----------------------------------------------------------------------------------------------------------+-------------+-----------------------------------------+--------------+-------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Use case | domainName | relationshipTypeName | targetFilter | scopeFilter | Query result | -+==========================================================================================================+=============+=========================================+==============+===================================================================+===============================================================================================================================================================+ -| To return all relationships for a specified relationship type. | REL_OAM_RAN | MANAGEDELEMENT _MANAGES _ENODEBFUNCTION | | | All MANAGEDELEMENT_MANAGES_ENODEBFUNCTION relationships. | -+----------------------------------------------------------------------------------------------------------+-------------+-----------------------------------------+--------------+-------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| To return all relationships for a specified relationship type with a specified association to an entity. | REL_OAM_RAN | MANAGEDELEMENT _MANAGES _ENODEBFUNCTION | | /managed-by-managedElement [@id='urn\:3gpp:dn: ManagedElement=1'] | All MANAGEDELEMENT_MANAGES_ENODEBFUNCTION relationships having an association *managed-by-managedElement* to ManagedElement *urn\:3gpp:dn: ManagedElement=1*. | -+----------------------------------------------------------------------------------------------------------+-------------+-----------------------------------------+--------------+-------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------+ - ++------------------------------------------+-------------+-----------------+--------+----------------------------+-------------------------------------------------+ +| Use case | domainName | relationship | target | scopeFilter | Query result | +| | | Type Name | | | | +| | | | Filter | | | ++==========================================+=============+=================+========+============================+=================================================+ +| | To return all relationships for a | REL_OAM_RAN | MANAGEDELEMENT | | | | All MANAGEDELEMENT_MANAGES_ENODEBFUNCTION | +| | specified relationship | | _MANAGES | | | | relationships | +| | | _ENODEBFUNCTION | | | | ++------------------------------------------+-------------+-----------------+--------+----------------------------+-------------------------------------------------+ +| | To return all relationships for a | REL_OAM_RAN | MANAGEDELEMENT | | /managed-by-managedElement | | All MANAGEDELEMENT_MANAGES_ENODEBFUNCTION | +| | specified relationship type with a | | _MANAGES | | [@id='urn\:3gpp:dn: | | relationships having an association | +| | specified association to an entity. | | _ENODEBFUNCTION | | ManagedElement=1'] | | *managed-by-managedElement* to ManagedElement | +| | | | | | | *urn\:3gpp:dn: ManagedElement=1*. | ++------------------------------------------+-------------+-----------------+--------+----------------------------+-------------------------------------------------+ ..