"cps.ncmp.inventory.yang.resources.from.dmi","Time taken to get list of yang resources from dmi"
"cps.ncmp.cmhandle.state.update.batch","Time taken to update a batch of cm handle states"
"cps.rest.admin.controller.schemaset.create","Time taken to create schemaset from controller"
-"cps.data.controller.datanode.query.v1","Time taken to query data nodes"
-"cps.data.controller.datanode.query.v2","Time taken to query data nodes"
-"cps.data.controller.datanode.query.across.anchors","Time taken to query data nodes across anchors"
"cps.data.controller.datanode.get.v1","Time taken to get data node"
"cps.data.controller.datanode.get.v2","Time taken to get data node"
"cps.data.controller.datanode.get.v3","Time taken to get data node"
"cps.delta.controller.get.delta","Time taken to get delta between anchors"
"cps.delta.controller.get.delta","Time taken to get delta between anchors"
-"cps.module.persistence.schemaset.create","Time taken to store a schemaset (list of module references)"
-"cps.module.persistence.schemaset.createFromNewAndExistingModules","Time taken to store a schemaset (from new and existing)"
+"cps.data.controller.datanode.query.v1","Time taken to query data nodes"
+"cps.data.controller.datanode.query.v2","Time taken to query data nodes"
+"cps.data.controller.datanode.query.across.anchors","Time taken to query data nodes across anchors"
"cps.data.persistence.service.datanode.query","Time taken to query data nodes"
"cps.data.persistence.service.datanode.query.anchors","Time taken to query data nodes across all anchors or list of anchors"
"cps.data.persistence.service.datanode.get","Time taken to get a data node"
"cps.data.persistence.service.datanode.batch.get","Time taken to get data nodes"
+"cps.module.persistence.schemaset.create","Time taken to store a schemaset (list of module references)"
+"cps.module.persistence.schemaset.createFromNewAndExistingModules","Time taken to store a schemaset (from new and existing)"
"cps.dataupdate.events.send","Time taken to send Data Update event"
-"cps.module.service.schemaset.create","Time taken to create (and store) a schemaset"
-"cps.data.service.datanode.query","Time taken to query data nodes"
-"cps.data.service.datanode.query","Time taken to query data nodes with a limit on results"
"cps.data.service.datanode.root.save","Time taken to save a root data node"
"cps.data.service.datanode.child.save","Time taken to save a child data node"
"cps.data.service.list.element.save","Time taken to save list elements"
"cps.data.service.list.delete","Time taken to delete a list or list element"
"cps.delta.service.get.delta","Time taken to get delta between anchors"
"cps.delta.service.get.delta","Time taken to get delta between anchor and a payload"
+"cps.module.service.schemaset.create","Time taken to create (and store) a schemaset"
+"cps.data.service.datanode.query","Time taken to query data nodes"
+"cps.data.service.datanode.query","Time taken to query data nodes with a limit on results"
"cps.utils.yangparser.nodedata.with.parent.parse","Time taken to parse node data with a parent"
"cps.utils.yangparser.nodedata.with.parent.with.yangResourceMap.parse","Time taken to parse node data with a parent"
"cps.yangtextschemasourceset.build","Time taken to build a yang text schema source set"
.. This work is licensed under a Creative Commons Attribution 4.0 International License.
.. http://creativecommons.org/licenses/by/4.0
-.. Copyright (C) 2022-2024 Nordix Foundation
+.. Copyright (C) 2022-2025 OpenInfra Foundation Europe. All rights reserved.
.. DO NOT CHANGE THIS LABEL FOR RELEASE NOTES - EVEN THOUGH IT GIVES A WARNING
.. _cmhandlequerying:
Introduction
============
-For querying CM Handles we have two Post endpoints:
+For querying CM Handles there are 4 endpoints:
-- ncmp/v1/ch/searches Returns all CM Handles which match the query properties provided. Gives a JSON payload of the **details** of all matching CM Handles.
++-------------------------------------+------------------+----------------------+
+| Endpoint | Target | Output |
++-------------------------------------+------------------+----------------------+
+| ncmp/v1/ch/searches | northbound: rApp | cm-handle references |
++-------------------------------------+------------------+----------------------+
+| ncmp/v1/ch/id-searches | northbound: rApp | cm-handle objects |
++-------------------------------------+------------------+----------------------+
+| ncmpInventory/v1/ch/searches | southbound: dmi | cm-handle references |
++-------------------------------------+------------------+----------------------+
+| ncmpInventory/v1/ch/searchCmHandles | southbound: dmi | cm-handle objects |
++-------------------------------------+------------------+----------------------+
-- ncmp/v1/ch/id-searches Returns all CM Handles IDs or Alternate IDs which match the query properties provided. Gives a JSON payload of the **ids** of all matching CM Handles.
-
-/searches returns whole CM Handle object (data) whereas /id-searches returns only CM Handle IDs or Alternate IDs. Otherwise these endpoints are intended to be functionally identical so both can be queried with the same request body. If no matching CM Handles are found an empty array is returned.
+Each of these endpoints utilizes an identical request body structure to define search conditions and related parameters, as described in the subsequent sections.
+If no matching CM Handles are found an empty array is returned.
Parameters
==========
-/id-searches can return either CM Handle IDs or Alternate IDs. This is controlled with an optional parameter outputAlternateId.
-
-- *outputAlternateId=true* returns Alternate IDs
++------------------------------------+-------------------+--------------------------------------+------------------------------------+
+| Parameter | Value | Behavior | Scope |
++------------------------------------+-------------------+--------------------------------------+------------------------------------+
+| outputAlternateId | true | return Alternate Ids | cm-handle reference searches |
++------------------------------------+-------------------+--------------------------------------+------------------------------------+
+| outputAlternateId | false / undefined | return CM Handle Ids | cm-handle reference searches |
++------------------------------------+-------------------+--------------------------------------+------------------------------------+
+| includeAdditionalPropertiesInQuery | true | include additional properties | southbound cm-handle object search |
++------------------------------------+-------------------+--------------------------------------+------------------------------------+
+| includeAdditionalPropertiesInQuery | false / undefined | do not include additional properties | southbound cm-handle object search |
++------------------------------------+-------------------+--------------------------------------+------------------------------------+
-- *outputAlternateId=false* returns CM Handle IDs
-
-Note: Null values will default to false so /id-searches & /id-searches?outputAlternateId will both return CM Handle IDs
Request Body
============
-Currently this endpoint allows three criteria to be query on:
-
-- *hasAllModules* returns CM Handles which have the module names provided.
+Supported search criteria (conditionName in request body)
+
++----------------------------+---------------------------------------------------------------+---------------------------+
+| Condition Name | Description | Scope |
++----------------------------+---------------------------------------------------------------+---------------------------+
+| hasAllModules | find cm handles that have all the given modules | both interfaces |
++----------------------------+---------------------------------------------------------------+---------------------------+
+| hasAllProperties | find cm handles that have all the given public properties | both interfaces |
++----------------------------+---------------------------------------------------------------+---------------------------+
+| hasAllAdditionalProperties | find cm handles that have all the given additional properties | southbound interface only |
++----------------------------+---------------------------------------------------------------+---------------------------+
+| cmHandleWithCpsPath | find cm handles that match the CPS Path provided | both interfaces |
++----------------------------+---------------------------------------------------------------+---------------------------+
+| cmHandleWithDmiPlugin | find cm handles registered by the given dmi plugin | southbound interface only |
++----------------------------+---------------------------------------------------------------+---------------------------+
+| cmHandleWithTrustLevel | find cm handles with the given trust level | both interfaces |
++----------------------------+---------------------------------------------------------------+---------------------------+
-- *hasAllProperties* returns CM Handles which have the properties (key and value) provided.
-
-- *cmHandleWithCpsPath* returns CM Handles which match the CPS Path provided.
-
-Not all request body combinations have been validated and as such request bodies which do not conform to the structure as documented here can produce results in which all CM Handles are returned.
Casing conventions: 'camelCasing' and 'kebab-casing'
----------------------------------------------------
.. note::
- By convention REST JSON return bodies use 'camelCasing'. By convention field names in yang modelled data use 'kebab-casing'. Therefore some inconsistencies can be seen in the JSON use in CPS REST interfaces. For CM Handle related endpoints we return data in 'camelCasing'. But for *cmHandleWithCpsPath*, the query is accessing yang modelled field names and as such needs to use 'kebab-casing'. Therefore the dmi-registry field names should be referenced when using the *cmHandleWithCpsPath* condition: :doc:`modeling`
+ By convention REST JSON return bodies use 'camelCasing'. By convention field names in yang modelled data use 'kebab-casing'.
+ Therefore some inconsistencies can be seen in the JSON use in CPS REST interfaces. For CM Handle related endpoints we return data in 'camelCasing'.
+ But for *cmHandleWithCpsPath*, the query is accessing yang modelled field names and as such needs to use 'kebab-casing'.
+ Therefore the dmi-registry field names should be referenced when using the *cmHandleWithCpsPath* condition: :doc:`modeling`
-Request Body example using all available query criteria. This query would return all CM Handles which have the specified modules my-module-(1-3), have the specified properties of Color yellow, Shape circle, Size small and are in a sync state of ADVISED:
+Examples
+========
+
+Has all Modules
+---------------
+
+With the *hasAllModules* condition, we can provide a list of module names.
+The CM Handles returned will have these module names.
+The parameter names must be as below with the key of each of the module names being "moduleName" where "my-module-X" is to be replaced with the name of the module to query with. The returned CM Handle must have all supplied modules. For the example request, a CM Handle will be returned if it has "my-module-1", "my-module-2" and "my-module-3".
.. code-block:: json
"moduleName": "my-module-3"
}
]
- },
+ }
+ ]
+ }
+
+Has all Properties
+------------------
+
+With the *hasAllProperties* condition, we can provide a list of property keys and values.
+The CM Handles returned will have these properties. The parameter names must be as below with key and value for each property.
+The returned CM Handle must have all supplied properties.
+For the example request, a CM Handle will be returned if it has properties where there is a key of "Color" with value "yellow", a key of "Shape" with value "circle" and a key of "Size" with value "small".
+
+.. code-block:: json
+
+ {
+ "cmHandleQueryParameters": [
{
"conditionName": "hasAllProperties",
"conditionParameters": [
"Size": "small"
}
]
- },
+ }
+ ]
+ }
+
+Has all additional Properties
+-----------------------------
+
+With the *hasAllAdditionalProperties* condition, we can provide a list of property keys and values.
+The CM Handles returned will have these additional properties. The parameter names must be as below with key and value for each property.
+The returned CM Handle must have all supplied properties.
+For the example request, a CM Handle will be returned if it has properties where there is a key of "Price" with value "5", a key of "Year" with value "2022" and a key of "Quantity" with value "12".
+
+.. code-block:: json
+
+ {
+ "cmHandleQueryParameters": [
{
- "conditionName": "cmHandleWithCpsPath",
+ "conditionName": "hasAllAdditionalProperties",
"conditionParameters": [
{
- "cpsPath": "//state[@cm-handle-state='ADVISED']"
- }
- ]
- },
- {
- "conditionName": "cmHandleWithTrustLevel",
- "conditionParameters": [
+ "Price": "5"
+ },
{
- "trustLevel": "COMPLETE"
+ "Year": "2022"
+ },
+ {
+ "Quantity": "12"
}
]
}
}
-Has all Modules
----------------
+CM Handle with CPS Path
+-----------------------
-With the *hasAllModules* condition, we can provide a list of module names. The CM Handles returned will have these module names. The parameter names must be as below with the key of each of the module names being "moduleName" where "my-module-X" is to be replaced with the name of the module to query with. The returned CM Handle must have all supplied modules. For the example request, a CM Handle will be returned if it has "my-module-1", "my-module-2" and "my-module-3".
+The *cmHandleWithCpsPath* condition allows any data of the CM Handle to be queried as long as it is accessible by CPS path.
+CPS path is described in detail in :doc:`cps-path`.
+For this endpoint, the ancestor of CM Handles is appended automatically so that a CM Handle is always returned. For example ``//state[@cm-handle-state='LOCKED']`` will become ``//state[@cm-handle-state='LOCKED']/ancestor::cm-handles``. The yang model for the dmi-registry can be found in :doc:`modeling` under the NCMP Modeling Section. Please note that although CM Handle additional-properties are shown in the dmi-registry yang model, these are considered private properties and cannot be used to query CM Handles. Any attempt to use the additional-properties to query will return an empty array.
.. code-block:: json
{
"cmHandleQueryParameters": [
{
- "conditionName": "hasAllModules",
+ "conditionName": "cmHandleWithCpsPath",
"conditionParameters": [
{
- "moduleName": "my-module-1"
- },
- {
- "moduleName": "my-module-2"
- },
- {
- "moduleName": "my-module-3"
+ "cpsPath": "//state[@cm-handle-state='LOCKED']"
}
]
}
]
}
-Has all Properties
-------------------
+CM Handle with DMI Plugin
+-------------------------
-With the *hasAllProperties* condition, we can provide a list of property keys and values. The CM Handles returned will have these properties. The parameter names must be as below with key and value for each property. The returned CM Handle must have all supplied properties. For the example request, a CM Handle will be returned if it has properties where there is a key of "Color" with value "yellow", a key of "Shape" with value "circle" and a key of "Size" with value "small".
+With the *cmHandleWithDmiPlugin* condition, we can provide a dmi service name.
+The CM Handles returned will have this service in at least one of the following registered service names: dmi-service-name, dmi-data-service-name and dmi-model-service-name.
.. code-block:: json
{
"cmHandleQueryParameters": [
{
- "conditionName": "hasAllProperties",
+ "conditionName": "cmHandleWithDmiPlugin",
"conditionParameters": [
{
- "Color": "yellow"
- },
- {
- "Shape": "circle"
- },
- {
- "Size": "small"
+ "dmi-service-name": "my-dmi-plugin"
}
]
}
]
}
-CM Handle with CPS Path
------------------------
-The *cmHandleWithCpsPath* condition allows any data of the CM Handle to be queried as long as it is accessible by CPS path. CPS path is described in detail in :doc:`cps-path`. For this endpoint, the ancestor of CM Handles is appended automatically so that a CM Handle is always returned. For example ``//state[@cm-handle-state='LOCKED']`` will become ``//state[@cm-handle-state='LOCKED']/ancestor::cm-handles``. The yang model for the dmi-registry can be found in :doc:`modeling` under the NCMP Modeling Section. Please note that although CM Handle additional-properties are shown in the dmi-registry yang model, these are considered private properties and cannot be used to query CM Handles. Any attempt to use the additional-properties to query will return an empty array.
+CM Handle with Trust Level
+--------------------------
+
+With the *cmHandleWithTrustLevel* condition, we can provide just one trust level.
+The CM handles returned will have this trust level.
.. code-block:: json
{
"cmHandleQueryParameters": [
{
- "conditionName": "cmHandleWithCpsPath",
+ "conditionName": "cmHandleWithTrustLevel",
"conditionParameters": [
{
- "cpsPath": "//state[@cm-handle-state='LOCKED']"
+ "trustLevel": "COMPLETE"
}
]
}
]
}
-CM Handle with Trust Level
---------------------------
+Combining Conditions
+--------------------
-With the *cmHandleWithTrustLevel* condition, we can provide just one trust level. The CM handles returned will have this trust level. Providing more than one parameter causes unexpected results. Condition parameter name is not being validated.
+Request Body example using several conditions.
+This query would return all CM Handles which have the specified modules my-module-(1-3), have the specified properties of Color yellow, Shape circle, Size small and are in a sync state of ADVISED:
.. code-block:: json
{
"cmHandleQueryParameters": [
+ {
+ "conditionName": "hasAllModules",
+ "conditionParameters": [
+ {
+ "moduleName": "my-module-1"
+ },
+ {
+ "moduleName": "my-module-2"
+ },
+ {
+ "moduleName": "my-module-3"
+ }
+ ]
+ },
+ {
+ "conditionName": "hasAllProperties",
+ "conditionParameters": [
+ {
+ "Color": "yellow"
+ },
+ {
+ "Shape": "circle"
+ },
+ {
+ "Size": "small"
+ }
+ ]
+ },
+ {
+ "conditionName": "cmHandleWithCpsPath",
+ "conditionParameters": [
+ {
+ "cpsPath": "//state[@cm-handle-state='ADVISED']"
+ }
+ ]
+ },
{
"conditionName": "cmHandleWithTrustLevel",
"conditionParameters": [
]
}
]
- }
\ No newline at end of file
+ }
+++ /dev/null
-.. This work is licensed under a Creative Commons Attribution 4.0 International License.
-.. http://creativecommons.org/licenses/by/4.0
-.. Copyright (C) 2023 Nordix Foundation
-
-.. DO NOT CHANGE THIS LABEL FOR RELEASE NOTES - EVEN THOUGH IT GIVES A WARNING
-.. _inventoryquerying:
-
-
-Inventory Query Endpoints
-#########################
-
-.. toctree::
- :maxdepth: 1
-
-Introduction
-============
-
-For querying the NCMP Inventory we have one Post endpoint:
-
-- ncmpInventory/v1/ch/searches Returns all CM Handles which match the query properties provided. Gives a JSON payload of the **details** of all matching CM Handles.
-
-If no matching CM Handles are found an empty array is returned.
-
-Request Body
-============
-
-Currently this endpoint allows three criteria to be query on:
-
-- *hasAllProperties* returns CM Handles which have the public properties provided.
-
-- *hasAllAdditionalProperties* returns CM Handles which have the private or additional properties (key and value) provided.
-
-- *cmHandleWithDmiPlugin* returns CM Handles which match the CPS Dmi Plugin provided.
-
-Not all request body combinations have been validated and as such request bodies which do not conform to the structure as documented here can produce results in which all CM Handles are returned.
-
-Casing conventions: 'camelCasing' and 'kebab-casing'
-----------------------------------------------------
-
-.. note::
- By convention REST JSON return bodies use 'camelCasing'. By convention field names in yang modelled data use 'kebab-casing'. Therefore some inconsistencies can be seen in the JSON use in CPS REST interfaces. For CM Handle related endpoints we return data in 'camelCasing'. But for *cmHandleWithCpsPath*, the query is accessing yang modelled field names and as such needs to use 'kebab-casing'. Therefore the dmi-registry field names should be referenced when using the *cmHandleWithCpsPath* condition: :doc:`modeling`
-
-Request Body example using all available query criteria. This query would return all CM Handles which have the specified public properties of Color yellow, Shape circle, Size small, have the specified private/additional properties of Price 5, Year 2022 and Quantity 12 and have related to DMI plugin dmiPlugin1:
-
-.. code-block:: json
-
- {
- "cmHandleQueryParameters": [
- {
- "conditionName": "hasAllProperties",
- "conditionParameters": [
- {
- "Color": "yellow"
- },
- {
- "Shape": "circle"
- },
- {
- "Size": "small"
- }
- ]
- },
- {
- "conditionName": "hasAllAdditionalProperties",
- "conditionParameters": [
- {
- "Price": "5"
- },
- {
- "Year": "2022"
- },
- {
- "Quantity": "12"
- }
- ]
- },
- {
- "conditionName": "cmHandleWithDmiPlugin",
- "conditionParameters": [
- {
- "dmiPluginName": "dmiPlugin1"
- }
- ]
- }
- ]
- }
-
-Has all Properties
-------------------
-
-With the *hasAllProperties* condition, we can provide a list of property keys and values. The CM Handles returned will have these public properties. The parameter names must be as below with key and value for each property. The returned CM Handle must have all supplied properties. For the example request, a CM Handle will be returned if it has properties where there is a key of "Color" with value "yellow", a key of "Shape" with value "circle" and a key of "Size" with value "small".
-
-.. code-block:: json
-
- {
- "cmHandleQueryParameters": [
- {
- "conditionName": "hasAllProperties",
- "conditionParameters": [
- {
- "Color": "yellow"
- },
- {
- "Shape": "circle"
- },
- {
- "Size": "small"
- }
- ]
- }
- ]
- }
-
-Has all additional Properties
------------------------------
-
-With the *hasAllAdditionalProperties* condition, we can provide a list of property keys and values. The CM Handles returned will have these additional properties. The parameter names must be as below with key and value for each property. The returned CM Handle must have all supplied properties. For the example request, a CM Handle will be returned if it has properties where there is a key of "Price" with value "5", a key of "Year" with value "2022" and a key of "Quantity" with value "12".
-
-.. code-block:: json
-
- {
- "cmHandleQueryParameters": [
- {
- "conditionName": "hasAllAdditionalProperties",
- "conditionParameters": [
- {
- "Price": "5"
- },
- {
- "Year": "2022"
- },
- {
- "Quantity": "12"
- }
- ]
- }
- ]
- }
-
-Has all DMI Plugins
--------------------
-
-With the *cmHandleWithDmiPlugin* condition, we can provide a dmiPluginName. The CM Handles returned will have this DMI Plugin Name value in at least one of the following related leaves: dmi-service-name, dmi-data-service-name and dmi-model-service-name. For the example request a CM Handle will be returned if it has my-dmi-plugin as a value in at least one of the aforementioned leaves.
-
-.. code-block:: json
-
- {
- "cmHandleQueryParameters": [
- {
- "conditionName": "cmHandleWithDmiPlugin",
- "conditionParameters": [
- {
- "dmi-service-name": "my-dmi-plugin"
- }
- ]
- }
- ]
- }
-
-CM Handle search with CPS Path
-------------------------------
-
-The *cmHandleWithCpsPath* condition allows any data of the CM Handle to be queried as long as it is accessible by CPS path. CPS path is described in detail in :doc:`cps-path`. For this endpoint, the ancestor axis for CM Handles is appended automatically so that a CM Handle is always returned. For example ``/dmi-registry/cm-handles[@module-set-tag='']`` will become ``/dmi-registry/cm-handles[@module-set-tag='']/ancestor::cm-handles``.
-
-.. code-block:: json
-
- {
- "cmHandleQueryParameters": [
- {
- "conditionName": "cmHandleWithCpsPath",
- "conditionParameters": [
- {
- "cpsPath": "/dmi-registry/cm-handles[@module-set-tag='some-value or empty']"
- }
- ]
- }
- ]
- }
\ No newline at end of file
Code Review / cps.git / commitdiff