APIs e SDKs do Azure Digital Twins

  • Artigo

Este artigo fornece uma visão geral das APIs do Azure Digital Twins disponíveis e os métodos para interagir com elas. Você pode usar as APIs REST diretamente com seus Swaggers associados (por meio de uma ferramenta como o Postman) ou por meio de um SDK.

Os Gêmeos Digitais do Azure vêm equipados com APIs de plano de controle, APIs de plano de dados e SDKs para gerenciar sua instância e seus elementos.

  • As APIs do plano de controle são APIs do Azure Resource Manager (ARM) e abrangem operações de gerenciamento de recursos, como a criação e a exclusão de sua instância.
  • As APIs do plano de dados são APIs do Azure Digital Twins e são usadas para operações de gerenciamento de dados, como gerenciar modelos, gêmeos e o gráfico.
  • Os SDKs aproveitam as APIs existentes para permitir a facilidade de desenvolvimento de aplicativos personalizados que usam os Gêmeos Digitais do Azure.

APIs do plano de controle

As APIs do plano de controle são APIs ARM usadas para gerenciar sua instância do Azure Digital Twins como um todo, portanto, abrangem operações como criar ou excluir toda a instância. Você também usará essas APIs para criar e excluir pontos de extremidade.

Para chamar as APIs diretamente, consulte a pasta Swagger mais recente no repositório Swagger do plano de controle. Esta pasta também inclui uma pasta de exemplos que mostram o uso.

Aqui estão os SDKs atualmente disponíveis para as APIs do plano de controle do Azure Digital Twins.

Idioma do SDK Link do pacote Documentação de referência Código fonte
.NET (C#) Azure.ResourceManager.DigitalTwins no NuGet Referência para o SDK do Azure DigitalTwins para .NET Biblioteca de cliente de gerenciamento do Microsoft Azure Digital Twins para .NET no GitHub
Java azure-resourcemanager-digitaltwins no Maven Referência para Gestão de Recursos - Digital Twins Biblioteca de cliente AzureDigitalTwins do Azure Resource Manager para Java no GitHub
JavaScript Biblioteca de cliente AzureDigitalTwinsManagement para JavaScript no npm Biblioteca de cliente AzureDigitalTwinsManagement para JavaScript no GitHub
Python azure-mgmt-digitaltwins no PyPI SDK do Microsoft Azure para Python no GitHub
Go azure-sdk-for-go/services/digitaltwins/mgmt SDK do Azure para Go no GitHub

Você também pode exercer as APIs do plano de controle interagindo com os Gêmeos Digitais do Azure por meio do portal do Azure e da CLI.

APIs de plano de dados

As APIs do plano de dados são as APIs do Azure Digital Twins usadas para gerenciar os elementos em sua instância do Azure Digital Twins. Eles incluem operações como criar rotas, carregar modelos, criar relacionamentos e gerenciar gêmeos, e podem ser divididos nas seguintes categorias:

Para chamar as APIs diretamente, faça referência à pasta Swagger mais recente no repositório Swagger do plano de dados. Esta pasta também inclui uma pasta de exemplos que mostram o uso. Você também pode visualizar a documentação de referência da API do plano de dados.

Aqui estão os SDKs atualmente disponíveis para as APIs do plano de dados do Azure Digital Twins.

Idioma do SDK Link do pacote Documentação de referência Código fonte
.NET (C#) Azure.DigitalTwins.Core no NuGet Referência para a biblioteca de cliente do Azure IoT Digital Twins para .NET Biblioteca de cliente do Azure IoT Digital Twins para .NET no GitHub
Java com.azure:azure-digitaltwins-core no Maven Referência para o SDK do Azure Digital Twins para Java Biblioteca de cliente do Azure IoT Digital Twins para Java no GitHub
JavaScript Biblioteca de cliente do Azure Azure Digital Twins Core para JavaScript no npm Reference for @azure/digital-twins-core Biblioteca de cliente do Azure Azure Digital Twins Core para JavaScript no GitHub
Python Biblioteca de cliente do Azure Azure Digital Twins Core para Python no PyPI Referência para azure-digitaltwins-core Biblioteca de cliente do Azure Azure Digital Twins Core para Python no GitHub

Você também pode exercitar as APIs do plano de dados interagindo com os Gêmeos Digitais do Azure por meio da CLI.

Notas de uso e autenticação

Esta seção contém informações mais detalhadas sobre como usar as APIs e SDKs.

Notas da API

Aqui estão algumas informações gerais para chamar as APIs dos Gêmeos Digitais do Azure diretamente.

Aqui estão mais algumas informações sobre autenticação para solicitações de API.

  • Uma maneira de gerar um token de portador para solicitações de API do Azure Digital Twins é com o comando az account get-access-token CLI. Para obter instruções detalhadas, consulte Obter token de portador.
  • As solicitações para as APIs do Azure Digital Twins exigem um usuário ou entidade de serviço que faça parte do mesmo locatário do Microsoft Entra ID onde a instância do Azure Digital Twins existe. Para evitar a verificação mal-intencionada dos pontos de extremidade do Azure Digital Twins, as solicitações com tokens de acesso de fora do locatário de origem retornarão uma mensagem de erro "Subdomínio 404 não encontrado". Este erro será devolvido mesmo que o utilizador ou entidade de serviço tenha recebido uma função de Proprietário de Dados dos Gêmeos Digitais do Azure ou de Leitor de Dados dos Gêmeos Digitais do Azure por meio da colaboração B2B do Microsoft Entra. Para obter informações sobre como obter acesso entre vários locatários, consulte Escrever código de autenticação de aplicativo.

Notas do SDK

O SDK subjacente para Gêmeos Digitais do Azure é Azure.Core. Consulte a documentação do namespace do Azure para referência sobre a infraestrutura e os tipos do SDK.

Aqui estão mais algumas informações sobre autenticação com os SDKs.

  • Comece instanciando a DigitalTwinsClient classe. O construtor requer credenciais que podem ser obtidas com diferentes tipos de métodos de autenticação no Azure.Identity pacote. Para obter mais informações sobre Azure.Identityo , consulte a documentação do namespace.
  • Você pode achar o InteractiveBrowserCredential útil ao começar, mas há várias outras opções, incluindo credenciais para identidade gerenciada, que você provavelmente usará para autenticar funções do Azure configuradas com MSI em Gêmeos Digitais do Azure. Para obter mais informações sobre InteractiveBrowserCredentialo , consulte a documentação da classe.

Aqui estão mais algumas informações sobre funções e dados retornados.

  • Todas as chamadas de API de serviço são expostas como funções de membro na DigitalTwinsClient classe.
  • Todas as funções de serviço existem em versões síncronas e assíncronas.
  • Todas as funções de serviço lançam uma exceção para qualquer status de retorno de 400 ou superior. Certifique-se de envolver as chamadas em uma try seção e capturar pelo menos RequestFailedExceptions. Para obter mais informações sobre esse tipo de exceção, consulte a documentação de referência.
  • A maioria dos métodos de serviço retorna Response<T> ou (Task<Response<T>> para as chamadas assíncronas), onde T é a classe de objeto de retorno para a chamada de serviço. A classe Response encapsula o retorno de serviço e apresenta valores de retorno em seu Value campo.
  • Métodos de serviço com retorno de resultados paginados ou AsyncPageable<T> como resultadosPageable<T>. Para obter mais informações sobre a classe, consulte sua documentação de referência, para obter mais informações sobre AsyncPageable<T>a , consulte sua documentação de Pageable<T> referência.
  • Você pode iterar sobre resultados paginados usando um await foreach loop. Para obter mais informações sobre esse processo, consulte Iterando com enumeráveis assíncronos em C# 8.
  • Os métodos de serviço retornam objetos fortemente tipados sempre que possível. No entanto, como o Azure Digital Twins é baseado em modelos configurados pelo usuário em tempo de execução (por meio de modelos DTDL carregados no serviço), muitas APIs de serviço usam e retornam dados gêmeos no formato JSON.

Auxiliares de serialização no SDK do .NET (C#)

Os auxiliares de serialização são funções auxiliares disponíveis no SDK do .NET (C#) para criar ou desserializar rapidamente dados gêmeos para acesso a informações básicas . Como os principais métodos SDK retornam dados gêmeos como JSON por padrão, pode ser útil usar essas classes auxiliares para decompor ainda mais os dados gêmeos.

As classes auxiliares disponíveis são:

  • BasicDigitalTwin: Representa genericamente os dados principais de um gêmeo digital
  • BasicDigitalTwinComponent: Representa genericamente um componente nas Contents propriedades de um BasicDigitalTwin
  • BasicRelationship: Representa genericamente os dados principais de uma relação
  • DigitalTwinsJsonPropertyName: Contém as constantes de cadeia de caracteres para uso na serialização e desserialização JSON para tipos de gêmeos digitais personalizados

Importação em massa com a API de trabalhos de importação

A API de Trabalhos de Importação é uma API de plano de dados que permite importar um conjunto de modelos, gêmeos e/ou relacionamentos em uma única chamada de API . As operações da API de Trabalhos de Importação também estão incluídas nos comandos da CLI e nos SDKs do plano de dados. O uso da API de Trabalhos de Importação requer o uso do Armazenamento de Blobs do Azure.

Verificar permissões

Para usar a API de Importação de Trabalhos, você precisará habilitar as configurações de permissão descritas nesta seção.

Primeiro, você precisará de uma identidade gerenciada atribuída ao sistema para sua instância do Azure Digital Twins. Para obter instruções sobre como configurar uma identidade gerenciada pelo sistema para a instância, consulte Habilitar/desabilitar a identidade gerenciada para a instância.

Você precisará ter permissões de gravação em sua instância do Azure Digital Twins para as seguintes categorias de ação de dados:

  • Microsoft.DigitalTwins/jobs/*
  • Todos os elementos gráficos que você deseja incluir na chamada Trabalhos. Isso pode incluir Microsoft.DigitalTwins/models/*, Microsoft.DigitalTwins/digitaltwins/*e/ou Microsoft.DigitalTwins/digitaltwins/relationships/*.

A função interna que fornece todas essas permissões é o Proprietário de Dados do Azure Digital Twins. Você também pode usar uma função personalizada para conceder acesso granular apenas aos tipos de dados necessários. Para obter mais informações sobre funções em Gêmeos Digitais do Azure, consulte Segurança para soluções de Gêmeos Digitais do Azure.

Nota

Se você tentar uma chamada da API Importar Trabalhos e não tiver permissões de gravação para um dos tipos de elementos gráficos que está tentando importar, o trabalho ignorará esse tipo e importará os outros. Por exemplo, se você tiver acesso de gravação a modelos e gêmeos, mas não a relacionamentos, uma tentativa de importar em massa todos os três tipos de elemento só terá êxito na importação dos modelos e gêmeos. O status do trabalho refletirá uma falha e a mensagem indicará quais permissões estão faltando.

Você também precisará conceder as seguintes permissões RBAC à identidade gerenciada atribuída pelo sistema de sua instância do Azure Digital Twins para que ela possa acessar arquivos de entrada e saída no contêiner de Armazenamento de Blob do Azure:

Finalmente, gere um token de portador que pode ser usado em suas solicitações para a API de trabalhos. Para obter instruções, consulte Obter token de portador.

Formatar dados

A API aceita a entrada de informações de gráfico de um arquivo NDJSON, que deve ser carregado em um contêiner de armazenamento de blob do Azure. O arquivo começa com uma Header seção, seguida pelas seções Modelsopcionais , Twinse Relationships. Não é necessário incluir os três tipos de dados gráficos no arquivo, mas todas as seções presentes devem seguir essa ordem. Gêmeos e relacionamentos criados com essa API podem, opcionalmente, incluir a inicialização de suas propriedades.

Aqui está um arquivo de dados de entrada de exemplo para a API de importação:

{"Section": "Header"}
{"fileVersion": "1.0.0", "author": "foobar", "organization": "contoso"}
{"Section": "Models"}
{"@id":"dtmi:com:microsoft:azure:iot:model0;1","@type":"Interface","contents":[{"@type":"Property","name":"property00","schema":"integer"},{"@type":"Property","name":"property01","schema":{"@type":"Map","mapKey":{"name":"subPropertyName","schema":"string"},"mapValue":{"name":"subPropertyValue","schema":"string"}}},{"@type":"Relationship","name":"has","target":"dtmi:com:microsoft:azure:iot:model1;1","properties":[{"@type":"Property","name":"relationshipproperty1","schema":"string"},{"@type":"Property","name":"relationshipproperty2","schema":"integer"}]}],"description":{"en":"This is the description of model"},"displayName":{"en":"This is the display name"},"@context":"dtmi:dtdl:context;2"}
{"@id":"dtmi:com:microsoft:azure:iot:model1;1","@type":"Interface","contents":[{"@type":"Property","name":"property10","schema":"string"},{"@type":"Property","name":"property11","schema":{"@type":"Map","mapKey":{"name":"subPropertyName","schema":"string"},"mapValue":{"name":"subPropertyValue","schema":"string"}}}],"description":{"en":"This is the description of model"},"displayName":{"en":"This is the display name"},"@context":"dtmi:dtdl:context;2"}
{"Section": "Twins"}
{"$dtId":"twin0","$metadata":{"$model":"dtmi:com:microsoft:azure:iot:model0;1"},"property00":10,"property01":{"subProperty1":"subProperty1Value","subProperty2":"subProperty2Value"}}
{"$dtId":"twin1","$metadata":{"$model":"dtmi:com:microsoft:azure:iot:model1;1"},"property10":"propertyValue1","property11":{"subProperty1":"subProperty1Value","subProperty2":"subProperty2Value"}}
{"Section": "Relationships"}
{"$dtId":"twin0","$relationshipId":"relationship","$targetId":"twin1","$relationshipName":"has","relationshipProperty1":"propertyValue1","relationshipProperty2":10}

Gorjeta

Para obter um projeto de exemplo que converte modelos, gêmeos e relacionamentos no NDJSON suportado pela API de importação, consulte Azure Digital Twins Bulk Import NDJSON Generator. O projeto de exemplo é escrito para .NET e pode ser baixado ou adaptado para ajudá-lo a criar seus próprios arquivos de importação.

Depois que o arquivo tiver sido criado, carregue-o em um blob de bloco no Armazenamento de Blobs do Azure usando seu método de carregamento preferido (algumas opções são o comando AzCopy, a CLI do Azure ou o portal do Azure). Você usará a URL de armazenamento de blob do arquivo NDJSON no corpo da chamada da API Import Jobs.

Executar o trabalho de importação

Agora você pode continuar chamando a API de Importação de Trabalhos. Para obter instruções detalhadas sobre como importar um gráfico completo em uma chamada de API, consulte Carregar modelos, gêmeos e relacionamentos em massa com a API de trabalhos de importação. Você também pode usar a API de Trabalhos de Importação para importar cada tipo de recurso independentemente. Para obter mais informações sobre como usar a API de Importação de Trabalhos com tipos de recursos individuais, consulte Instruções da API de Importação de Trabalhos para modelos, gêmeos e relacionamentos.

No corpo da chamada de API, você fornecerá a URL de armazenamento de blob do arquivo de entrada NDJSON. Você também fornecerá uma nova URL de armazenamento de blob para indicar onde deseja que o log de saída seja armazenado assim que o serviço o criar.

Importante

Verifique se a identidade gerenciada atribuída ao sistema da sua instância do Azure Digital Twins tem as permissões RBAC do blob de armazenamento descritas na seção Verificar permissões.

À medida que o trabalho de importação é executado, um log de saída estruturado é gerado pelo serviço e armazenado como um novo blob de acréscimo em seu contêiner de blob, no local de URL especificado para o blob de saída na solicitação. Aqui está um exemplo de log de saída para um trabalho bem-sucedido importando modelos, gêmeos e relacionamentos:

{"timestamp":"2022-12-30T19:50:34.5540455Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"status":"Started"}}
{"timestamp":"2022-12-30T19:50:37.2406748Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"section":"Models","status":"Started"}}
{"timestamp":"2022-12-30T19:50:38.1445612Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"section":"Models","status":"Succeeded"}}
{"timestamp":"2022-12-30T19:50:38.5475921Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"section":"Twins","status":"Started"}}
{"timestamp":"2022-12-30T19:50:39.2744802Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"section":"Twins","status":"Succeeded"}}
{"timestamp":"2022-12-30T19:50:39.7494663Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"section":"Relationships","status":"Started"}}
{"timestamp":"2022-12-30T19:50:40.4480645Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"section":"Relationships","status":"Succeeded"}}
{"timestamp":"2022-12-30T19:50:41.3043264Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"status":"Succeeded"}}

Quando o trabalho estiver concluído, você poderá ver o número total de entidades ingeridas usando a métrica BulkOperationEntityCount.

Também é possível cancelar um trabalho de importação em execução com a operação Cancelar da API Importar trabalhos. Depois que o trabalho for cancelado e não estiver mais em execução, você poderá excluí-lo.

Limites e considerações

Tenha em mente as seguintes considerações ao trabalhar com a API de Importação de Trabalhos:

  • Import Jobs não são operações atômicas. Não há reversão em caso de falha, conclusão parcial do trabalho ou uso da operação Cancelar.
  • Apenas um trabalho em massa é suportado de cada vez em uma instância do Azure Digital Twins. Você pode exibir essas informações e outros limites numéricos das APIs de Trabalhos nos limites dos Gêmeos Digitais do Azure.

Excluir em massa com a API Excluir trabalhos

A API Excluir Trabalhos é uma API de plano de dados que permite excluir todos os modelos, gêmeos e relacionamentos em uma instância com uma única chamada de API . As operações da API Delete Jobs também estão disponíveis como comandos da CLI. Visite a documentação da API para ver os detalhes da solicitação para criar um trabalho de exclusão e verificar seu status.

Para garantir que todos os elementos sejam excluídos, siga estas recomendações ao usar a API Excluir trabalhos:

  • Para obter instruções sobre como gerar um token de portador para autenticar solicitações de API, consulte Obter token de portador.
  • Se você importou recentemente um grande número de entidades para o gráfico, aguarde algum tempo e verifique se todos os elementos estão sincronizados no gráfico antes de iniciar o trabalho de exclusão.
  • Pare todas as operações na instância, especialmente as operações de upload, até que o trabalho de exclusão seja concluído.

Dependendo do tamanho do gráfico que está sendo excluído, um trabalho de exclusão pode levar de alguns minutos a várias horas.

O período de tempo limite padrão para um trabalho de exclusão é de 12 horas, que pode ser ajustado para qualquer valor entre 15 minutos e 24 horas usando um parâmetro de consulta na API. Essa é a quantidade de tempo que o trabalho de exclusão será executado antes de atingir o tempo limite, momento em que o serviço tentará parar o trabalho se ele ainda não tiver sido concluído.

Limites e outras considerações

Tenha em mente as seguintes considerações ao trabalhar com a API Excluir trabalhos:

  • Excluir trabalhos não são operações atômicas. Não há reversão em caso de falha, conclusão parcial do trabalho ou tempo limite do trabalho.
  • Apenas um trabalho em massa é suportado de cada vez em uma instância do Azure Digital Twins. Você pode exibir essas informações e outros limites numéricos das APIs de Trabalhos nos limites dos Gêmeos Digitais do Azure.

Monitorar métricas da API

As métricas de API, como solicitações, latência e taxa de falha, podem ser exibidas no portal do Azure.

Para obter informações sobre como exibir e gerenciar métricas do Azure Digital Twins, consulte Monitorar sua instância. Para obter uma lista completa das métricas de API disponíveis para os Gêmeos Digitais do Azure, consulte Métricas de solicitação de API do Azure Digital Twins.

Próximos passos

Veja como fazer solicitações diretas para as APIs do Azure Digital Twins usando o Postman:

Ou, pratique o uso do SDK do .NET criando um aplicativo cliente com este tutorial: