Address feedbacks: Rename type, improve readme (Azure#14905)

* fix(azure-digitaltwins-core): address feedbacks

* fix(digitaltwins): update for GA

* fix(digitaltwins): address comments

* fix(digitaltwins): update unit tests

* fix(digitaltwins): address more comments

* fix(digitaltwins): fix link error

* fix(digitaltwins): fix link error 2

* fix(digitaltwins): set "unreleased" in changelog

Author: Zoltan Varga

eng/ignore-links.txt

@@ -2,5 +2,4 @@ https://docs.microsoft.com/python/api/overview/azure/{{package_doc_id}}
 https://pypi.org/project/azure-servicebus/7.0.0b7/
 https://github.com/Azure/azure-digital-twins/blob/private-preview/Documentation/how-to-manage-routes.md
 https://pypi.org/project/azure-digitaltwins-core
-
-
+https://docs.microsoft.com/azure/digital-twins/how-to-query-graph#query-limitations

sdk/digitaltwins/azure-digitaltwins-core/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Release History
 
+## 1.0.0 (unreleased)
+
+- The is the GA release containing the following changes:
+  - Added etag and match_condition parameters to upsert_digital_twin and upsert_relationship APIs to support conditional operation.
+  - Rename EventRoute type to DigitalTwinsEventRoute
+  - Rename component_path to component_name
+  - Rename models to dtdl_models
+  - Fix some documentation
+
 ## 1.0.0b1 (2020-10-31)
 
 * Initial Release

sdk/digitaltwins/azure-digitaltwins-core/README.md

@@ -2,8 +2,6 @@
 
 This package contains an SDK for Azure Digital Twins API to provide access to the Azure Digital Twins service for managing twins, models, relationships, etc.
 
-This package contains an isomorphic SDK for Azure Digital Twins API to provide access to the Azure Digital Twins service for managing twins, models, relationships, etc.
-
 ## Getting started
 
 ### Introduction
@@ -194,6 +192,9 @@ print(get_twin)
 
 Query the Azure Digital Twins instance for digital twins using the [Azure Digital Twins Query Store lanaguage](https://review.docs.microsoft.com/azure/digital-twins/concepts-query-language). Query calls support paging. Here's an example of how to query for digital twins and how to iterate over the results.
 
+Note that there may be a delay between before changes in your instance are reflected in queries.
+For more details on query limitations, see (https://docs.microsoft.com/azure/digital-twins/how-to-query-graph#query-limitations)
+
 ```Python Snippet:dt_digitaltwins_query
 query_expression = 'SELECT * FROM digitaltwins'
 query_result = service_client.query_twins(query_expression)

sdk/digitaltwins/azure-digitaltwins-core/azure/digitaltwins/core/__init__.py

@@ -10,14 +10,14 @@
 from ._generated.models import DigitalTwinsModelData
 from ._generated.models import QueryResult
 from ._generated.models import IncomingRelationship
-from ._generated.models import EventRoute
+from ._generated.models import DigitalTwinsEventRoute
 
 __all__ = [
     'DigitalTwinsClient',
     'DigitalTwinsModelData',
     'QueryResult',
     'IncomingRelationship',
-    'EventRoute'
+    'DigitalTwinsEventRoute'
 ]
 
 from ._version import VERSION

sdk/digitaltwins/azure-digitaltwins-core/azure/digitaltwins/core/_digitaltwins_client.py

@@ -13,7 +13,8 @@
 from azure.core import MatchConditions
 
 from ._utils import (
-    prep_if_match
+    prep_if_match,
+    prep_if_none_match
 )
 
 from ._generated import models
@@ -65,6 +66,9 @@ def upsert_digital_twin(self, digital_twin_id, digital_twin, **kwargs):
         :param str digital_twin_id: The Id of the digital twin.
         :param Dict[str, object] digital_twin:
             Dictionary containing the twin to create or update.
+        :keyword str etag: Only perform the operation if the entity does not already exist.
+        :keyword ~azure.core.MatchConditions match_condition:
+            The match condition to use upon the etag
         :return: Dictionary containing the created or updated twin.
         :rtype: Dict[str, object]
         :raises :class: `~azure.core.exceptions.HttpResponseError`
@@ -73,9 +77,13 @@ def upsert_digital_twin(self, digital_twin_id, digital_twin, **kwargs):
         :raises :class: `~azure.core.exceptions.ResourceExistsError`:
             If the digital twin is already exist.
         """
+        etag = kwargs.get("etag", None)
+        match_condition = kwargs.get("match_condition", MatchConditions.Unconditionally)
+
         return self._client.digital_twins.add(
             digital_twin_id,
             digital_twin,
+            if_none_match=prep_if_none_match(etag, match_condition),
             **kwargs
         )
 
@@ -146,12 +154,12 @@ def delete_digital_twin(
         )
 
     @distributed_trace
-    def get_component(self, digital_twin_id, component_path, **kwargs):
+    def get_component(self, digital_twin_id, component_name, **kwargs):
         # type: (str, str, **Any) -> Dict[str, object]
         """Get a component on a digital twin.
 
         :param str digital_twin_id: The Id of the digital twin.
-        :param str component_path: The component being retrieved.
+        :param str component_name: The component being retrieved.
         :return: Dictionary containing the component.
         :rtype: Dict[str, object]
         :raises :class: `~azure.core.exceptions.HttpResponseError`
@@ -160,23 +168,23 @@ def get_component(self, digital_twin_id, component_path, **kwargs):
         """
         return self._client.digital_twins.get_component(
             digital_twin_id,
-            component_path,
+            component_name,
             **kwargs
         )
 
     @distributed_trace
     def update_component(
         self,
         digital_twin_id,
-        component_path,
+        component_name,
         json_patch,
         **kwargs
     ):
         # type: (str, str, Dict[str, object], **Any) -> None
         """Update properties of a component on a digital twin using a JSON patch.
 
         :param str digital_twin_id: The Id of the digital twin.
-        :param str component_path: The component being updated.
+        :param str component_name: The component being updated.
         :param Dict[str, object] json_patch: An update specification described by JSON Patch.
         :keyword str etag: Only perform the operation if the entity's etag matches one of
             the etags provided or * is provided.
@@ -193,7 +201,7 @@ def update_component(
 
         return self._client.digital_twins.update_component(
             digital_twin_id,
-            component_path,
+            component_name,
             patch_document=json_patch,
             if_match=prep_if_match(etag, match_condition),
             **kwargs
@@ -226,17 +234,24 @@ def upsert_relationship(self, digital_twin_id, relationship_id, relationship=Non
         :param str digital_twin_id: The Id of the digital twin.
         :param str relationship_id: The Id of the relationship to retrieve.
         :param Dict[str, object] relationship: Dictionary containing the relationship.
+        :keyword str etag: Only perform the operation if the entity does not already exist.
+        :keyword ~azure.core.MatchConditions match_condition:
+            The match condition to use upon the etag
         :return: The created or updated relationship.
         :rtype: Dict[str, object]
         :raises :class: `~azure.core.exceptions.HttpResponseError`
         :raises :class: `~azure.core.exceptions.ServiceRequestError`: If the request is invalid.
         :raises :class: `~azure.core.exceptions.ResourceNotFoundError`: If there is either no
             digital twin, target digital twin or relationship with the provided id.
         """
+        etag = kwargs.get("etag", None)
+        match_condition = kwargs.get("match_condition", MatchConditions.Unconditionally)
+
         return self._client.digital_twins.add_relationship(
             id=digital_twin_id,
             relationship_id=relationship_id,
             relationship=relationship,
+            if_none_match=prep_if_none_match(etag, match_condition),
             **kwargs
         )
 
@@ -378,7 +393,7 @@ def publish_telemetry(self, digital_twin_id, payload, message_id=None, **kwargs)
     def publish_component_telemetry(
         self,
         digital_twin_id,
-        component_path,
+        component_name,
         payload,
         message_id=None,
         **kwargs
@@ -388,7 +403,7 @@ def publish_component_telemetry(
             one or many destination endpoints (subscribers) defined under.
 
         :param str digital_twin_id: The Id of the digital twin.
-        :param str component_path: The name of the DTDL component.
+        :param str component_name: The name of the DTDL component.
         :param object payload: The telemetry payload to be sent.
         :param str message_id: The message Id.
         :return: None
@@ -404,7 +419,7 @@ def publish_component_telemetry(
 
         return self._client.digital_twins.send_component_telemetry(
             digital_twin_id,
-            component_path,
+            component_name,
             dt_id=message_id,
             telemetry=payload,
             dt_timestamp=timestamp,
@@ -464,7 +479,7 @@ def list_models(self, dependencies_for, **kwargs):
         )
 
     @distributed_trace
-    def create_models(self, model_list=None, **kwargs):
+    def create_models(self, dtdl_models=None, **kwargs):
         # type: (Optional[List[object]], **Any) -> List[~azure.digitaltwins.models.ModelData]
         """Create one or more models. When any error occurs, no models are uploaded.
 
@@ -477,7 +492,7 @@ def create_models(self, model_list=None, **kwargs):
             the provided models already exist.
         """
         return self._client.digital_twin_models.add(
-            model_list,
+            dtdl_models,
             **kwargs
         )
 
@@ -524,12 +539,12 @@ def delete_model(self, model_id, **kwargs):
 
     @distributed_trace
     def get_event_route(self, event_route_id, **kwargs):
-        # type: (str, **Any) -> ~azure.digitaltwins.models.EventRoute
+        # type: (str, **Any) -> DigitalTwinsEventRoute
         """Get an event route.
 
         :param str event_route_id: The Id of the event route.
-        :return: The EventRoute object.
-        :rtype: ~azure.digitaltwins.models.EventRoute
+        :return: The DigitalTwinsEventRoute object.
+        :rtype: DigitalTwinsEventRoute
         :raises :class: `~azure.core.exceptions.HttpResponseError`
         :raises :class: `~azure.core.exceptions.ResourceNotFoundError`: There is no
             event route with the provided id.
@@ -541,13 +556,13 @@ def get_event_route(self, event_route_id, **kwargs):
 
     @distributed_trace
     def list_event_routes(self, **kwargs):
-        # type: (**Any) -> ~azure.core.paging.ItemPaged[~azure.digitaltwins.models.EventRoute]
+        # type: (**Any) -> ~azure.core.paging.ItemPaged[DigitalTwinsEventRoute]
         """Retrieves all event routes.
 
         :keyword int results_per_page: The maximum number of items to retrieve per request.
             The server may choose to return less than the requested max.
-        :return: An iterator instance of list of EventRoute.
-        :rtype: ~azure.core.paging.ItemPaged[~azure.digitaltwins.models.EventRoute]
+        :return: An iterator instance of list of DigitalTwinsEventRoute.
+        :rtype: ~azure.core.paging.ItemPaged[DigitalTwinsEventRoute]
         :raises :class: `~azure.core.exceptions.HttpResponseError`
         :raises :class: `~azure.core.exceptions.ServiceRequestError`: The request is invalid.
         """
@@ -563,11 +578,11 @@ def list_event_routes(self, **kwargs):
 
     @distributed_trace
     def upsert_event_route(self, event_route_id, event_route, **kwargs):
-        # type: (str, "models.EventRoute", **Any) -> None
+        # type: (str, "DigitalTwinsEventRoute", **Any) -> None
         """Create or update an event route.
 
         :param str event_route_id: The Id of the event route to create or update.
-        :param ~azure.digitaltwins.models.EventRoute event_route: The event route data.
+        :param DigitalTwinsEventRoute event_route: The event route data.
         :return: None
         :rtype: None
         :raises :class: `~azure.core.exceptions.HttpResponseError`
@@ -599,6 +614,9 @@ def delete_event_route(self, event_route_id, **kwargs):
     def query_twins(self, query_expression, **kwargs):
         # type: (str, **Any) -> ~azure.core.async_paging.ItemPaged[Dict[str, object]]
         """Query for digital twins.
+            Note: that there may be a delay between before changes in your instance are reflected in queries.
+            For more details on query limitations, see
+            https://docs.microsoft.com/en-us/azure/digital-twins/how-to-query-graph#query-limitations
 
         :param str query_expression: The query expression to execute.
         :return: The QueryResult object.

sdk/digitaltwins/azure-digitaltwins-core/azure/digitaltwins/core/_generated/aio/operations_async/_digital_twins_operations_async.py

@@ -121,7 +121,6 @@ async def add(
         self,
         id: str,
         twin: object,
-        if_none_match: Optional[str] = "*",
         digital_twins_add_options: Optional["models.DigitalTwinsAddOptions"] = None,
         **kwargs
     ) -> Optional[object]:
@@ -145,8 +144,6 @@ async def add(
         :type id: str
         :param twin: The digital twin instance being added. If provided, the $dtId property is ignored.
         :type twin: object
-        :param if_none_match: Only perform the operation if the entity does not already exist.
-        :type if_none_match: str
         :param digital_twins_add_options: Parameter group.
         :type digital_twins_add_options: ~azure.digitaltwins.core.models.DigitalTwinsAddOptions
         :keyword callable cls: A custom type or function that will be passed the direct response
@@ -160,9 +157,11 @@ async def add(
 
         _traceparent = None
         _tracestate = None
+        _if_none_match = None
         if digital_twins_add_options is not None:
             _traceparent = digital_twins_add_options.traceparent
             _tracestate = digital_twins_add_options.tracestate
+            _if_none_match = digital_twins_add_options.if_none_match
         api_version = "2020-10-31"
         content_type = kwargs.pop("content_type", "application/json")
 
@@ -183,8 +182,8 @@ async def add(
             header_parameters['traceparent'] = self._serialize.header("traceparent", _traceparent, 'str')
         if _tracestate is not None:
             header_parameters['tracestate'] = self._serialize.header("tracestate", _tracestate, 'str')
-        if if_none_match is not None:
-            header_parameters['If-None-Match'] = self._serialize.header("if_none_match", if_none_match, 'str')
+        if _if_none_match is not None:
+            header_parameters['If-None-Match'] = self._serialize.header("if_none_match", _if_none_match, 'str')
         header_parameters['Content-Type'] = self._serialize.header("content_type", content_type, 'str')
         header_parameters['Accept'] = 'application/json'
 
@@ -477,7 +476,6 @@ async def add_relationship(
         id: str,
         relationship_id: str,
         relationship: object,
-        if_none_match: Optional[str] = "*",
         digital_twins_add_relationship_options: Optional["models.DigitalTwinsAddRelationshipOptions"] = None,
         **kwargs
     ) -> object:
@@ -509,8 +507,6 @@ async def add_relationship(
         :type relationship_id: str
         :param relationship: The data for the relationship.
         :type relationship: object
-        :param if_none_match: Only perform the operation if the entity does not already exist.
-        :type if_none_match: str
         :param digital_twins_add_relationship_options: Parameter group.
         :type digital_twins_add_relationship_options: ~azure.digitaltwins.core.models.DigitalTwinsAddRelationshipOptions
         :keyword callable cls: A custom type or function that will be passed the direct response
@@ -524,9 +520,11 @@ async def add_relationship(
 
         _traceparent = None
         _tracestate = None
+        _if_none_match = None
         if digital_twins_add_relationship_options is not None:
             _traceparent = digital_twins_add_relationship_options.traceparent
             _tracestate = digital_twins_add_relationship_options.tracestate
+            _if_none_match = digital_twins_add_relationship_options.if_none_match
         api_version = "2020-10-31"
         content_type = kwargs.pop("content_type", "application/json")
 
@@ -548,8 +546,8 @@ async def add_relationship(
             header_parameters['traceparent'] = self._serialize.header("traceparent", _traceparent, 'str')
         if _tracestate is not None:
             header_parameters['tracestate'] = self._serialize.header("tracestate", _tracestate, 'str')
-        if if_none_match is not None:
-            header_parameters['If-None-Match'] = self._serialize.header("if_none_match", if_none_match, 'str')
+        if _if_none_match is not None:
+            header_parameters['If-None-Match'] = self._serialize.header("if_none_match", _if_none_match, 'str')
         header_parameters['Content-Type'] = self._serialize.header("content_type", content_type, 'str')
         header_parameters['Accept'] = 'application/json'