Bibliothèque de client Azure Digital Twins Core pour Python - version 1.2.0

  • Article

Ce package contient un Kit de développement logiciel (SDK) pour l’API Azure Digital Twins afin de fournir l’accès au service Azure Digital Twins pour la gestion des jumeaux, des modèles, des relations, etc.

Clause d’exclusion de responsabilité

La prise en charge des packages Python du SDK Azure pour Python 2.7 a pris fin le 1er janvier 2022. Pour obtenir plus d’informations et poser des questions, reportez-vous à https://github.com/Azure/azure-sdk-for-python/issues/20691

Prise en main

Introduction

Azure Digital Twins est une plateforme de développement pour les solutions IoT de nouvelle génération qui vous permet de créer, d’exécuter et de gérer des représentations numériques de votre environnement d’entreprise, de manière sécurisée et efficace dans le cloud. Avec Azure Digital Twins, la création de représentations d’état opérationnel en direct est rapide et économique, et les représentations numériques restent à jour avec les données en temps réel provenant d’IoT et d’autres sources de données. Si vous débutez avec Azure Digital Twins et souhaitez en savoir plus sur la plateforme, veillez à consulter la page de documentation officielle d’Azure Digital Twins.

Pour une présentation de la programmation par rapport au service Azure Digital Twins, consultez la page du didacticiel de codage pour obtenir un guide pas à pas simple. Consultez ce tutoriel pour découvrir comment interagir avec une instance Azure Digital Twin à l’aide d’une application cliente en ligne de commande. Enfin, pour obtenir un guide rapide sur la création d’une solution Azure Digital Twins de bout en bout pilotée par les données actives de votre environnement, veillez à consulter ce guide utile.

Les guides mentionnés ci-dessus peuvent vous aider à prendre en main les éléments clés d’Azure Digital Twins, tels que la création d’instances Azure Digital Twins, de modèles, de graphiques de jumeaux, etc. Utilisez ce guide d’exemples ci-dessous pour vous familiariser avec les différentes API qui vous aident à programmer par rapport à Azure Digital Twins.

Procédure d’installation

Installez [azure-digitaltwins-core][pypi_package_keys] et azure-identity avec pip :

pip install azure-digitaltwins-core azure-identity

azure-identity est utilisé pour l’authentification Azure Active Directory, comme illustré ci-dessous.

Procédure d'utilisation

Authentification, autorisation

Pour créer un client digital twins, vous avez besoin du point de terminaison d’une instance Azure Digital Twin et des informations d’identification. Pour les exemples ci-dessous, les AZURE_URLvariables d’environnement , AZURE_TENANT_ID, AZURE_CLIENT_IDet AZURE_CLIENT_SECRET doivent être définies. Le client nécessite une instance de TokenCredential ou ServiceClientCredentials. Dans cet exemple, nous expliquons comment utiliser une classe dérivée : DefaultAzureCredentials.

Remarque : Pour accéder au plan de données du service Digital Twins, l’entité doit recevoir des autorisations. Pour ce faire, utilisez la commande Azure CLI : az dt rbac assign-role --assignee '<user-email | application-id>' --role owner -n '<your-digital-twins-instance>'

DefaultAzureCredential prend en charge différents mécanismes d’authentification et détermine le type d’informations d’identification approprié en fonction de l’environnement dans lequel il s’exécute. Il tente d’utiliser plusieurs types d’informations d’identification dans un ordre jusqu’à ce qu’il trouve des informations d’identification fonctionnelles.

Exemple de code
# DefaultAzureCredential supports different authentication mechanisms and determines the appropriate credential type based of the environment it is executing in.
# It attempts to use multiple credential types in an order until it finds a working credential.

# - AZURE_URL: The URL to the ADT in Azure
url = os.getenv("AZURE_URL")

# DefaultAzureCredential expects the following three environment variables:
# - AZURE_TENANT_ID: The tenant ID in Azure Active Directory
# - AZURE_CLIENT_ID: The application (client) ID registered in the AAD tenant
# - AZURE_CLIENT_SECRET: The client secret for the registered application
credential = DefaultAzureCredential()
service_client = DigitalTwinsClient(url, credential)

Concepts clés

Azure Digital Twins est un service Azure IoT qui permet de créer des modèles complets de l’environnement physique. Il peut créer des graphes d’intelligence spatiale afin de modéliser les relations et les interactions entre les personnes, les espaces et les appareils. Pour en savoir plus sur Azure Digital Twins, consultez la documentation Azure Digital Twins.

Exemples

Vous pouvez explorer les API de jumeaux numériques (à l’aide de la bibliothèque cliente) à l’aide des exemples de projet.

Les exemples de projet illustrent les éléments suivants :

  • Instancier le client
  • Créer, obtenir et désactiver des modèles
  • Créer, interroger et supprimer un jumeau numérique
  • Obtenir et mettre à jour les composants d’un jumeau numérique
  • Créer, obtenir et supprimer des relations entre des jumeaux numériques
  • Créer, obtenir et supprimer des itinéraires d’événements pour le jumeau numérique
  • Publier des messages de télémétrie sur un jumeau numérique et un composant de jumeau numérique

Créer, répertorier, désactiver et supprimer des modèles

Créer des modèles

Créons des modèles à l’aide du code ci-dessous. Vous devez passer un tableau contenant la liste des modèles.

temporary_component = {
    "@id": component_id,
    "@type": "Interface",
    "@context": "dtmi:dtdl:context;2",
    "displayName": "Component1",
    "contents": [
    {
        "@type": "Property",
        "name": "ComponentProp1",
        "schema": "string"
    },
    {
        "@type": "Telemetry",
        "name": "ComponentTelemetry1",
        "schema": "integer"
    }
    ]
}

temporary_model = {
    "@id": model_id,
    "@type": "Interface",
    "@context": "dtmi:dtdl:context;2",
    "displayName": "TempModel",
    "contents": [
    {
        "@type": "Property",
        "name": "Prop1",
        "schema": "string"
    },
    {
        "@type": "Component",
        "name": "Component1",
        "schema": component_id
    },
    {
        "@type": "Telemetry",
        "name": "Telemetry1",
        "schema": "integer"
    }
    ]
}

new_models = [temporary_component, temporary_model]
models = service_client.create_models(new_models)
print('Created Models:')
print(models)

Répertorier les modèles

Utilisation list_models de pour récupérer tous les modèles créés

listed_models = service_client.list_models()
for model in listed_models:
    print(model)

Obtenir le modèle

Utilisez get_model avec l’identificateur unique du modèle pour obtenir un modèle spécifique.

# Get a model
get_model = service_client.get_model(model_id)
print('Get Model:')
print(get_model)

Désactiver le modèle

Pour déscommision d’un modèle, transmettez un ID de modèle pour le modèle que vous souhaitez déscommision.

# Decommission a model
service_client.decommission_model(model_id)

Supprimer le modèle

Pour supprimer un modèle, transmettez un ID de modèle pour le modèle que vous souhaitez supprimer.

# Delete a model
service_client.delete_model(model_id)

Créer et supprimer des jumeaux numériques

Créer des jumeaux numériques

Pour créer un jumeau, vous devez fournir l’ID d’un jumeau numérique, par my_twin exemple et le jumeau numérique application/json basé sur le modèle créé précédemment. Vous pouvez consulter l’exemple d’application/json ici.

digital_twin_id = 'digitalTwin-' + str(uuid.uuid4())
temporary_twin = {
    "$metadata": {
        "$model": model_id
    },
    "$dtId": digital_twin_id,
    "Prop1": 42
}

created_twin = service_client.upsert_digital_twin(digital_twin_id, temporary_twin)
print('Created Digital Twin:')
print(created_twin)

Obtenir un jumeau numérique

Il est extrêmement facile d’obtenir un jumeau numérique.

get_twin = service_client.get_digital_twin(digital_twin_id)
print('Get Digital Twin:')
print(get_twin)

Interroger des jumeaux numériques

Interrogez l’instance Azure Digital Twins pour rechercher des jumeaux numériques à l’aide du Magasin des requêtes Azure Digital Twins. Les appels de requête prennent en charge la pagination. Voici un exemple montrant comment interroger des jumeaux numériques et comment itérer sur les résultats.

Notez qu’il peut y avoir un délai entre les modifications apportées à votre instance dans les requêtes. Pour plus d’informations sur les limitations des requêtes, consultez (/azure/digital-twins/how-to-query-graph#query-limitations)

query_expression = 'SELECT * FROM digitaltwins'
query_result = service_client.query_twins(query_expression)
print('DigitalTwins:')
for twin in query_result:
    print(twin)

Supprimer des jumeaux numériques

Supprimez un jumeau numérique simplement en fournissant l’ID d’un jumeau numérique comme indiqué ci-dessous.

service_client.delete_digital_twin(digital_twin_id)

Obtenir et mettre à jour des composants de jumeau numérique

Mettre à jour les composants du jumeau numérique

Pour mettre à jour un composant ou, en d’autres termes, remplacer, supprimer et/ou ajouter une propriété de composant ou une sous-propriété dans Digital Twin, vous devez effectuer l’ID d’un jumeau numérique, le nom du composant et les opérations application/json-patch+json sur le composant du jumeau numérique spécifié. Voici l’exemple de code sur la façon de procéder.

component_name = "Component1"
patch = [
    {
        "op": "replace",
        "path": "/ComponentProp1",
        "value": "value2"
    }
]
service_client.update_component(digital_twin_id, component_name, patch)

Obtenir des composants de jumeau numérique

Obtenez un composant en fournissant le nom d’un composant et l’ID du jumeau numérique auquel il appartient.

get_component = service_client.get_component(digital_twin_id, component_name)
print('Get Component:')
print(get_component)

Créer et répertorier des relations de jumeau numérique

Créer des relations de jumeau numérique

upsert_relationship crée une relation sur un jumeau numérique fourni avec l’ID d’un jumeau numérique, le nom de la relation comme « contains », l’ID d’une relation telle que « FloorContainsRoom » et une relation application/json à créer. Doit contenir la propriété avec la clé « $targetId » pour spécifier la cible de la relation. Vous trouverez des exemples de charges utiles pour les relations ici.

hospital_relationships = [
    {
        "$relationshipId": "BuildingHasFloor",
        "$sourceId": building_twin_id,
        "$relationshipName": "has",
        "$targetId": floor_twin_id,
        "isAccessRestricted": False
    },
    {
        "$relationshipId": "BuildingIsEquippedWithHVAC",
        "$sourceId": building_twin_id,
        "$relationshipName": "isEquippedWith",
        "$targetId": hvac_twin_id
    },
    {
        "$relationshipId": "HVACCoolsFloor",
        "$sourceId": hvac_twin_id,
        "$relationshipName": "controlsTemperature",
        "$targetId": floor_twin_id
    },
    {
        "$relationshipId": "FloorContainsRoom",
        "$sourceId": floor_twin_id,
        "$relationshipName": "contains",
        "$targetId": room_twin_id
    }
]

for relationship in hospital_relationships:
    service_client.upsert_relationship(
        relationship["$sourceId"],
        relationship["$relationshipId"],
        relationship
    )

Répertorier les relations de jumeau numérique

list_relationships et list_incoming_relationships répertorient respectivement toutes les relations et toutes les relations entrantes d’un jumeau numérique.

relationships = service_client.list_relationships(digital_twint_id)
for relationship in relationships:
    print(relationship)

incoming_relationships = service_client.list_incoming_relationships(digital_twin_id)
for incoming_relationship in incoming_relationships:
    print(incoming_relationship)

Créer, répertorier et supprimer des itinéraires d’événements de jumeaux numériques

Créer des itinéraires d’événements

Pour créer un itinéraire d’événements, fournissez l’ID d’un itinéraire d’événement tel que « myEventRouteId » et les données d’itinéraire d’événement contenant le point de terminaison et un filtre facultatif, comme dans l’exemple ci-dessous.

event_route_id = 'eventRoute-' + str(uuid.uuid4())
event_filter = "$eventType = 'DigitalTwinTelemetryMessages' or $eventType = 'DigitalTwinLifecycleNotification'"
route = DigitalTwinsEventRoute(
    endpoint_name=event_hub_endpoint_name,
    filter=event_filter
)
service_client.upsert_event_route(event_route_id, route)

Pour plus d’informations sur la langue du filtre d’itinéraire d’événements, consultez la documentation sur les événements de filtre « comment gérer les itinéraires ».

Répertorier les itinéraires d’événements

Répertoriez un itinéraire d’événement spécifique en fonction de l’ID d’itinéraire d’événement ou de toutes les options de définition d’itinéraires d’événements avec list_event_routes.

event_routes = service_client.list_event_routes()
for event_route in event_routes:
    print(event_route)

Supprimer des itinéraires d’événements

Supprimez un itinéraire d’événement en fonction de l’ID d’itinéraire d’événement.

service_client.delete_event_route(event_route_id)

Publier des messages de télémétrie pour un jumeau numérique

Pour publier un message de télémétrie pour un jumeau numérique, vous devez fournir l’ID du jumeau numérique, ainsi que la charge utile sur laquelle les données de télémétrie qui nécessitent la mise à jour.

digita_twin_id = "<DIGITAL TWIN ID>"
telemetry_payload = '{"Telemetry1": 5}'
service_client.publish_telemetry(
    digita_twin_id,
    telemetry_payload
)

Vous pouvez également publier un message de télémétrie pour un composant spécifique dans un jumeau numérique. En plus de l’ID et de la charge utile du jumeau numérique, vous devez spécifier l’ID du composant cible.

digita_twin_id = "<DIGITAL TWIN ID>"
component_name = "<COMPONENT_NAME>"
telemetry_payload = '{"Telemetry1": 5}'
service_client.publish_component_telemetry(
    digita_twin_id,
    component_name,
    telemetry_payload
)

Résolution des problèmes

Journalisation

Cette bibliothèque utilise la bibliothèque de journalisation standard pour la journalisation. Les informations de base sur les sessions HTTP (URL, en-têtes, etc.) sont enregistrées au niveau INFO.

La journalisation détaillée au niveau DEBUG, y compris les corps de requête/réponse et les en-têtes non expurgés, peut être activée sur un client avec l’argument de mot clé logging_enable :

Journalisation au niveau du client

import sys
import logging

# Create logger
logger = logging.getLogger('azure')
logger.setLevel(logging.DEBUG)
handler = logging.StreamHandler(stream=sys.stdout)
logger.addHandler(handler)

# Create service client and enable logging for all operations
service_client = DigitalTwinsClient(url, credential, logging_enable=True)

Journalisation au niveau de l’opération

import sys
import logging

# Create logger
logger = logging.getLogger('azure')
logger.setLevel(logging.DEBUG)
handler = logging.StreamHandler(stream=sys.stdout)
logger.addHandler(handler)

# Get model with logging enabled
model = service_client.get_model(model_id, logging_enable=True)

Configuration facultative

Les arguments de mot clé facultatifs peuvent être passés au niveau du client et par opération. La documentation de référence azure-core décrit les configurations disponibles pour les nouvelles tentatives, la journalisation, les protocoles de transport, etc.

Étapes suivantes

Fournir des commentaires

Si vous rencontrez des bogues ou si vous avez des suggestions, signalez un problème.

Contribution

Ce projet accepte les contributions et les suggestions. La plupart des contributions vous demandent d’accepter un contrat de licence de contribution (CLA) déclarant que vous avez le droit de nous accorder, et que vous nous accordez réellement, les droits d’utilisation de votre contribution. Pour plus d’informations, visitez https://cla.microsoft.com.

Quand vous envoyez une demande de tirage (pull request), un bot CLA détermine automatiquement si vous devez fournir un contrat CLA et agrémenter la demande de tirage de façon appropriée (par exemple, avec une étiquette ou un commentaire). Suivez simplement les instructions fournies par le bot. Vous ne devez effectuer cette opération qu’une seule fois sur tous les dépôts utilisant notre contrat CLA.

Ce projet a adopté le Code de conduite Open Source de Microsoft. Pour plus d’informations, consultez les Questions fréquentes (FAQ) sur le code de conduite ou envoyez vos questions ou vos commentaires à opencode@microsoft.com.