APIs e SDKs dos Gêmeos Digitais do Azure
Este artigo fornece uma visão geral das APIs Gêmeos Digitais do Azure disponíveis e os métodos para interagir com elas. Você pode usar as APIs REST diretamente com os Swaggers associados a elas (por meio de uma ferramenta como o Postman) ou por meio de um SDK.
Os Gêmeos Digitais do Azure contam com APIs de painel de controle, APIs de plano de dados e SDKs para gerenciar sua instância e os elementos dela.
- As APIs do painel de controle são APIs do ARM (Azure Resource Manager) e englobam operações de gerenciamento de recursos, por exemplo, criar e excluir a instância.
- As APIs de plano de dados são APIs dos Gêmeos Digitais do Azure e são usadas para operações de gerenciamento de dados, por exemplo, gerenciar modelos, gêmeos e o grafo.
- Os SDKs aproveitam as APIs existentes para permitir a facilidade de desenvolvimento de aplicativos personalizados que usam Gêmeos Digitais do Azure.
APIs do painel de controle
As APIs de painel de controle são APIs do ARM usadas para gerenciar sua instância dos Gêmeos Digitais do Azure como um todo, de modo que englobam operações como criar e excluir toda a sua instância. Você também usará essas APIs para criar e excluir pontos de extremidade.
Para chamar as APIs diretamente, referencie a pasta mais recente do Swagger no repositório Swagger do painel de controle. Essa pasta também inclui outra pasta de exemplos de uso.
Aqui estão os SDKs atualmente disponíveis para as APIs do plano de controle do Azure Digital Twins.
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 do plano de dados
As APIs de plano de dados são as APIs dos Gêmeos Digitais do Azure usadas para gerenciar os elementos dentro de sua instância dos Gêmeos Digitais do Azure. Elas incluem operações como criar rotas, carregar modelos, criar relações e gerenciar gêmeos e podem ser amplamente divididas nas seguintes categorias:
DigitalTwinModels– a categoria DigitalTwinModels contém APIs para gerenciar os modelos em uma instância dos Gêmeos Digitais do Azure. As atividades de gerenciamento incluem carregamento, validação, recuperação e exclusão de modelos criados na DTDL.DigitalTwins– a categoria DigitalTwins contém as APIs que permitem que os desenvolvedores criem, modifiquem e excluam gêmeos digitais e as relações deles em uma instância dos Gêmeos Digitais do Azure.Query– a categoria Consulta permite que os desenvolvedores encontrem conjuntos de gêmeos digitais no grafo de gêmeos entre diferentes relações.Event Routes– a categoria Rotas de Eventos contém APIs para rotear dados pelo sistema e para serviços downstream.Import Jobs- A API de Importação de Trabalhos permite gerenciar uma ação assíncrona de longa execução para importar modelos, gêmeos e relacionamentos em massa.Delete Jobs- A API Excluir Trabalhos permite gerenciar uma ação assíncrona de longa execução para excluir todos os modelos, gêmeos e relacionamentos em uma instância.
Para chamar as APIs diretamente, referencie a pasta mais recente do Swagger no repositório Swagger do plano de dados. Essa pasta também inclui outra pasta de exemplos de uso. Você também pode exibir 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.
Você também pode exercer 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 os SDKs.
Notas da API
Aqui estão algumas informações gerais para chamar as APIs do Gêmeos Digitais do Azure diretamente.
- Você pode usar uma ferramenta de testes de HTTP REST, como o Postman, para fazer chamadas diretas para as APIs dos Gêmeos Digitais do Azure. Para obter mais informações sobre esse processo, confira Chamar as APIs dos Gêmeos Digitais do Azure com o Postman.
- Atualmente, os Gêmeos Digitais do Azure não dão suporte ao CORS (compartilhamento de recursos entre origens) . Para obter mais informações sobre o impacto e as estratégias de resolução, consulte CORS (compartilhamento de recursos entre origens) para os Gêmeos Digitais do Azure.
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 Gêmeos Digitais do Azure é 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 Gêmeos Digitais do Azure exigem um usuário ou entidade de serviço que faça parte do mesmo locatário da ID do Microsoft Entra em que a instância do Gêmeo Digital do Azure existe. Para impedir a verificação mal-intencionada de pontos de extremidade dos Gêmeos Digitais do Azure, as solicitações com tokens de acesso de fora do locatário de origem retornarão uma mensagem de erro "404 Sub-Domain não encontrado". Esse erro será retornado mesmo se o usuário ou a entidade de serviço tiver recebido uma função de Proprietário de Dados dos Gêmeos Digitais do Azure ou Leitor de Dados dos Gêmeos Digitais do Azure por meio da colaboração B2B do Microsoft Entra. Para obter informações sobre como acessar vários locatários, confira Escrever código de autenticação do aplicativo.
Notas do SDK
O SDK subjacente para Gêmeos Digitais do Azure é Azure.Core. Confira a documentação do namespace do Azure para obter a referência sobre os tipos e a infraestrutura do SDK.
Aqui estão mais algumas informações sobre autenticação com os SDKs.
- Comece instanciando a
DigitalTwinsClientclasse. O construtor requer credenciais que podem ser obtidas com tipos diferentes de métodos de autenticação no pacoteAzure.Identity. Para saber mais sobreAzure.Identity, confira a documentação do namespace. - Você pode considerar o
InteractiveBrowserCredentialútil para começar, mas há várias outras opções, incluindo credenciais para identidade gerenciada, que você provavelmente usará para autenticar as funções do Azure configuradas com o MSI nos Gêmeos Digitais do Azure. Para saber mais sobreInteractiveBrowserCredential, confira a documentação da classe.
Aqui estão mais algumas informações sobre funções e dados retornados.
- Todas as chamadas à API de serviço são expostas como funções de membro na classe
DigitalTwinsClient. - Todas as funções de serviço existem em versões síncronas e assíncronas.
- Todas as funções de serviço geram uma exceção para qualquer status retornado como 400 ou acima. Encapsule as chamadas em uma seção
trye capture pelo menosRequestFailedExceptions. Para saber mais sobre o tipo de exceção, confira a respectiva 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), em queTé a classe do objeto retornado para a chamada de serviço. A classe Resposta encapsula o retorno do serviço e apresenta valores de retorno no respectivo campoValue. - Métodos de serviço com resultados paginados retornam
Pageable<T>ouAsyncPageable<T>como resultados. Para saber mais sobre a classePageable<T>, confira a respectiva documentação de referência. Para obter mais informações sobreAsyncPageable<T>, confira a respectiva documentação de referência. - Você pode iterar em resultados paginados usando um loop
await foreach. Para obter mais informações sobre esse processo, consulte Iterando com enumeráveis assíncronos no C# 8. - Os métodos de serviço retornam objetos fortemente tipados sempre que possível. No entanto, como os Gêmeos Digitais do Azure se baseiam em modelos configurados de maneira personalizada pelo usuário no runtime (por meio de modelos de DTDL carregados para o serviço), muitas APIs de serviço usam e retornam dados de gêmeos no formato JSON.
Auxiliares de serialização no SDK do .NET (C#)
Auxiliares de serialização são funções auxiliares disponíveis no .NET (C#) SDK para criar ou desserializar rapidamente dados de gêmeos para ter acesso a informações básicas. Como os métodos principais do SDK retornam dados de gêmeos como JSON por padrão, pode ser útil usar essas classes auxiliares para dividir mais esses dados.
As classes auxiliares disponíveis são:
BasicDigitalTwin: representa genericamente os dados principais de um gêmeo digitalBasicDigitalTwinComponent: representa genericamente um componente nas propriedadesContentsde umBasicDigitalTwinBasicRelationship: representa genericamente os dados principais de uma relaçãoDigitalTwinsJsonPropertyName: contém as constantes de cadeia de caracteres para uso na serialização e na 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 Importação de Trabalhos é 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 pelo sistema para sua instância do Gêmeos Digitais do Azure. 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 de Gêmeos Digitais do Azure para as seguintes categorias de ação de dados:
Microsoft.DigitalTwins/jobs/*- Quaisquer elementos de gráfico que você deseja incluir na chamada Jobs. Isso pode incluir
Microsoft.DigitalTwins/models/*,Microsoft.DigitalTwins/digitaltwins/*e/ouMicrosoft.DigitalTwins/digitaltwins/relationships/*.
A função interna que fornece todas essas permissões é Proprietário de Dados dos Gêmeos Digitais do Azure. Você também pode usar uma função personalizada para conceder acesso granular somente 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.
Observação
Se você tentar uma chamada de API de Importação de Trabalhos e não tiver permissões de gravação para um dos tipos de elemento gráfico 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 Blobs do Azure:
- Leitor de Dados de Blob de Armazenamento para o contêiner de blob de entrada do Armazenamento do Azure
- Colaborador de Dados de Blob de Armazenamento para o contêiner de blob de saída do Armazenamento 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 blobs do Azure. O arquivo começa com uma Header seção, seguida pelas seções Modelsopcionais , Twinse Relationships. Você não precisa incluir todos os três tipos de dados de gráfico 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}
Dica
Para obter um projeto de exemplo que converte modelos, gêmeos e relacionamentos no NDJSON com suporte na API de importação, consulte Gerador de NDJSON de importação em massa de gêmeos digitais do Azure. 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 de Trabalhos de Importação.
Executar o trabalho de importação
Agora você pode continuar chamando a API de Trabalhos de Importação. 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 Importar Trabalhos. Você também pode usar a API Importar Trabalhos 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 criá-lo.
Importante
Verifique se a identidade gerenciada atribuída pelo sistema de sua instância do Gêmeos Digitais do Azure tem as permissões RBAC de 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 no contêiner de blob, no local da 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 de Importação de Trabalhos. Depois que o trabalho tiver sido cancelado e não estiver mais em execução, você poderá excluí-lo.
Limites e considerações
Lembre-se das seguintes considerações ao trabalhar com a API de Trabalhos de Importação:
- Trabalhos de importação 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 por 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.
Exclusão 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 Excluir Trabalhos 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 carregamento, 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á interromper o trabalho se ele ainda não tiver sido concluído.
Limites e outras considerações
Lembre-se das 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 no caso de falha, conclusão parcial do trabalho ou tempo limite do trabalho.
- Apenas um trabalho em massa é suportado por 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 da 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 Gêmeos Digitais do Azure, consulte Monitorar sua instância. Para uma lista completa das métricas de API disponíveis para os Gêmeos Digitais do Azure, confira Métricas de solicitação de API dos Gêmeos Digitais do Azure.
Próximas etapas
Veja como fazer solicitações diretas às APIs dos Gêmeos Digitais do Azure usando o Postman:
Ou pratique o uso do SDK do .NET criando um aplicativo cliente com este tutorial: