Python için Azure Digital Twins Core istemci kitaplığı - sürüm 1.2.0

Makale
04/05/2023

Bu paket, ikizleri, modelleri, ilişkileri vb. yönetmek için Azure Digital Twins hizmetine erişim sağlayan bir Azure Digital Twins API'sini içerir.

Bildirim

Python 2.7 için Azure SDK Python paketleri desteği 01 Ocak 2022'de sona erdi. Daha fazla bilgi ve soru için lütfen https://github.com/Azure/azure-sdk-for-python/issues/20691

Başlarken

Giriş

Azure Digital Twins, iş ortamınızın dijital gösterimlerini bulutta güvenli ve verimli bir şekilde oluşturmanıza, çalıştırmanıza ve yönetmenize olanak tanıyan yeni nesil IoT çözümlerine yönelik bir geliştirici platformudur. Azure Digital Twins ile canlı operasyonel durum gösterimleri oluşturmak hızlı ve uygun maliyetlidir ve dijital gösterimler IoT ve diğer veri kaynaklarından gelen gerçek zamanlı verilerle güncel kalır. Azure Digital Twins'i yeni kullanıyorsanız ve platform hakkında daha fazla bilgi edinmek istiyorsanız lütfen Azure Digital Twins resmi belgeleri sayfasına göz atmayı unutmayın.

Azure Digital Twins hizmetine karşı programlama hakkında giriş için kolay bir adım adım kılavuz için kodlama öğreticisi sayfasını ziyaret edin. Komut satırı istemci uygulaması kullanarak Azure Digital Twin örneğiyle nasıl etkileşim kuracağınızı öğrenmek için bu öğreticiyi ziyaret edin. Son olarak, ortamınızdan alınan canlı veriler tarafından yönetilen uçtan uca bir Azure Digital Twins çözümü oluşturma hakkında hızlı bir kılavuz için bu yararlı kılavuzu gözden geçirin.

Yukarıda bahsedilen kılavuzlar, Azure Digital Twins örnekleri, modelleri, ikiz grafikleri vb. oluşturma gibi Azure Digital Twins'in temel öğelerini kullanmaya başlamanıza yardımcı olabilir. Azure Digital Twins'e karşı programlamanıza yardımcı olan çeşitli API'leri öğrenmek için aşağıdaki örnek kılavuzunu kullanın.

Yükleme

Pip ile [azure-digitaltwins-core][pypi_package_keys] ve azure-identity yükleyin:

pip install azure-digitaltwins-core azure-identity

azure-identity , aşağıda gösterildiği gibi Azure Active Directory kimlik doğrulaması için kullanılır.

Nasıl kullanılır?

Kimlik doğrulaması, izin

Yeni bir digital twins istemcisi oluşturmak için uç noktanın bir Azure Digital Twin örneğine ve kimlik bilgilerine sahip olması gerekir. Aşağıdaki AZURE_URLörnekler için , AZURE_TENANT_ID, AZURE_CLIENT_IDve AZURE_CLIENT_SECRET ortam değişkenleri ayarlanmalıdır. İstemci bir TokenCredential veya ServiceClientCredentials örneği gerektirir. Bu örneklerde, türetilmiş bir sınıfın nasıl kullanılacağını göstereceğiz: DefaultAzureCredentials.

Not: Digital Twins hizmetinin veri düzlemine erişmek için varlığa izinlerin verilmesi gerekir. Bunu yapmak için Azure CLI komutunu kullanın: az dt rbac assign-role --assignee '<user-email | application-id>' --role owner -n '<your-digital-twins-instance>'

DefaultAzureCredential farklı kimlik doğrulama mekanizmalarını destekler ve yürütülmekte olan ortama göre uygun kimlik bilgisi türünü belirler. Çalışan bir kimlik bilgisi bulana kadar bir sırada birden çok kimlik bilgisi türü kullanmaya çalışır.

Örnek kod

# 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)

Önemli kavramlar

Azure Digital Twins, fiziksel ortamların kapsamlı modellerini oluşturan bir Azure IoT hizmetidir. İnsanlar, alanlar ve cihazlar arasındaki ilişkileri ve etkileşimleri modellemek için uzamsal zeka grafikleri oluşturabilir. Azure Digital Twins Belgeleri'ne giderek Azure Digital Twins hakkında daha fazla bilgi edinebilirsiniz.

Örnekler

Örnek projesini kullanarak dijital ikiz API'lerini (istemci kitaplığını kullanarak) keşfedebilirsiniz.

Örnek projesi aşağıdakileri gösterir:

İstemciyi başlatma
Model oluşturma, alma ve kullanımdan kaldırma
Dijital ikiz oluşturma, sorgulama ve silme
Dijital ikiz için bileşenleri alma ve güncelleştirme
Dijital ikizler arasında ilişki oluşturma, alma ve silme
Dijital ikiz için olay yolları oluşturma, alma ve silme
Telemetri iletilerini dijital ikiz ve dijital ikiz bileşeninde yayımlama

Modelleri oluşturma, listeleme, kullanımdan kaldırma ve silme

Model oluşturma

Şimdi aşağıdaki kodu kullanarak modeller oluşturalım. Modellerin listesini içeren bir dizi geçirmeniz gerekir.

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)

Modelleri listeleme

Oluşturulan tüm modelleri almak için kullanma list_models

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

Modeli alma

Belirli bir modeli almak için modelin benzersiz tanımlayıcısıyla kullanın get_model .

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

Kullanımdan çıkarma modeli

Bir modelin komutlarını çözmek için, decommision uygulamak istediğiniz modelin model kimliğini geçirin.

# Decommission a model
service_client.decommission_model(model_id)

Modeli silme

Modeli silmek için silmek istediğiniz modelin model kimliğini geçirin.

# Delete a model
service_client.delete_model(model_id)

Dijital ikizleri oluşturma ve silme

Dijital ikizleri oluşturma

İkiz Oluşturma için, daha önce oluşturulan modele göre ve gibi bir dijital ikizin my_twin kimliğini ve application/json dijital ikizini sağlamanız gerekir. Örnek uygulamaya/json dosyasına buradan bakabilirsiniz.

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)

Dijital ikiz edinme

Dijital ikiz almak son derece kolaydır.

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

Dijital ikizleri sorgulama

Azure Digital Twins Sorgu Deposu lanaguage'ını kullanarak dijital ikizler için Azure Digital Twins örneğini sorgulayın. Sorgu çağrıları sayfalandırmayı destekler. Aşağıda dijital ikizleri sorgulama ve sonuçlar üzerinde yineleme gibi bir örnek verilmiştir.

Örneğinizdeki değişikliklerin sorgulara yansıtılması arasında bir gecikme olabileceğini unutmayın. Sorgu sınırlamaları hakkında daha fazla ayrıntı için bkz. (/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)

Dijital ikizleri silme

Aşağıdaki gibi bir dijital ikizin kimliğini sağlayarak dijital ikizleri silin.

service_client.delete_digital_twin(digital_twin_id)

Dijital ikiz bileşenlerini alma ve güncelleştirme

Dijital ikiz bileşenlerini güncelleştirme

Bir bileşeni güncelleştirmek veya başka bir deyişle Digital Twin içindeki bir bileşen özelliğini veya alt özelliğini değiştirmek, kaldırmak ve/veya eklemek için, belirtilen dijital ikizin bileşeninde gerçekleştirilecek dijital ikiz kimliği, bileşen adı ve uygulama/json-patch+json işlemleri gerekir. Bunun nasıl yapılacağını gösteren örnek kod aşağıda verilmiştir.

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

Dijital ikiz bileşenlerini alma

Bir bileşenin adını ve ait olduğu dijital ikizin kimliğini sağlayarak bir bileşen alın.

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

Dijital ikiz ilişkilerini oluşturma ve listeleme

Dijital ikiz ilişkileri oluşturma

upsert_relationship dijital ikiz kimliği, "contains" gibi ilişki adı, "FloorContainsRoom" gibi bir ilişkinin kimliği ve oluşturulacak bir uygulama/json ilişkisi ile sağlanan bir dijital ikiz üzerinde ilişki oluşturur. İlişkinin hedefini belirtmek için "$targetId" anahtarına sahip bir özellik içermelidir. İlişkiler için örnek yükleri burada bulabilirsiniz.

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
    )

Dijital ikiz ilişkilerini listeleme

list_relationships ve list_incoming_relationships bir dijital ikizin sırasıyla tüm ilişkilerini ve tüm gelen ilişkileri listeler.

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)

Dijital ikizlerin olay yollarını oluşturma, listeleme ve silme

Olay yolları oluşturma

Olay yolu oluşturmak için, "myEventRouteId" gibi bir olay yolunun kimliğini ve uç noktayı içeren olay yolu verilerini ve aşağıda gösterilen örneğe benzer isteğe bağlı filtreyi sağlayın.

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)

Olay yolu filtre dili hakkında daha fazla bilgi için "yolları yönetme" filtre olayları belgelerine bakın.

Olay yollarını listeleme

Belirli bir olay rotası verilen olay yolu kimliğini veya ile tüm olay yolları ayar seçeneklerini listeleyin list_event_routes.

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

Olay yollarını silme

Verilen olay yolu kimliğini sil.

service_client.delete_event_route(event_route_id)

Dijital ikiz için telemetri iletilerini yayımlama

Bir dijital ikiz için telemetri iletisi yayımlamak için, dijital ikiz kimliğini ve güncelleştirmeye ihtiyaç duyan telemetri verilerinin yükünü sağlamanız gerekir.

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

Ayrıca, dijital ikizdeki belirli bir bileşen için telemetri iletisi yayımlayabilirsiniz. Dijital ikiz kimliğine ve yüküne ek olarak hedef bileşen kimliğini belirtmeniz gerekir.

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
)

Sorun giderme

Günlüğe Kaydetme

Bu kitaplık, günlüğe kaydetme için standart günlük kitaplığını kullanır. HTTP oturumları (URL'ler, üst bilgiler vb.) hakkındaki temel bilgiler BİlGİ düzeyinde günlüğe kaydedilir.

İstek/yanıt gövdeleri ve kaydedilmemiş üst bilgiler de dahil olmak üzere ayrıntılı HATA AYıKLAMA düzeyi günlüğü, bir istemcide logging_enable anahtar sözcük bağımsız değişkeniyle etkinleştirilebilir:

İstemci düzeyinde günlüğe kaydetme

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)

İşlem düzeyinde günlüğe kaydetme

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)

İsteğe Bağlı Yapılandırma

İsteğe bağlı anahtar sözcük bağımsız değişkenleri istemci ve işlem başına düzeyinde geçirilebilir. Azure-core başvuru belgelerinde yeniden denemeler, günlüğe kaydetme, aktarım protokolleri ve daha fazlası için kullanılabilir yapılandırmalar açıklanmaktadır.

Sonraki adımlar

Geri Bildirim Sağlama

Hatalarla karşılaşırsanız veya önerileriniz varsa lütfen bir sorun açın.

Katkıda bulunma

Bu proje, katkı ve önerilere açıktır. Çoğu durumda, sağladığınız katkıyı kullanmamız için bize hak tanıma hakkına sahip olduğunuzu ve bu hakkı bize tanıdığınızı bildiren bir Katkıda Bulunan Lisans Sözleşmesi’ni (CLA) kabul etmeniz gerekir. Ayrıntılar için bkz. https://cla.microsoft.com.

Bir çekme isteği gönderdiğinizde, CLA robotu bir CLA sağlamanız gerekip gerekmediğini otomatik olarak belirler ve çekme isteğini uygun şekilde donatır (örn. etiket, açıklama). Robot tarafından sağlanan yönergeleri izlemeniz yeterlidir. Bu işlemi, CLA’mızı kullanarak tüm depolarda yalnızca bir kere yapmanız gerekir.

Bu proje Microsoft Open Source Code of Conduct (Microsoft Açık Kaynak Kullanım Kuralları) belgesinde listelenen kurallara uygundur. Daha fazla bilgi için Kullanım Kuralları SSS bölümüne bakın veya ek sorularınız veya yorumlarınızla iletişime geçin opencode@microsoft.com .

Aracılığıyla paylaş