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 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 de plano de controle dos Gêmeos Digitais do Azure.
Você também pode usar as APIs do painel 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 execução prolongada para importar modelos, gêmeos e relações em massa.Delete Jobs– A API de Exclusão de Trabalhos permite gerenciar uma ação assíncrona de execução prolongada para excluir todos os modelos, gêmeos e relações 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 de plano de dados dos Gêmeos Digitais do Azure.
Você também pode usar 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
Veja algumas informações gerais para chamar as APIs dos Gêmeos Digitais do Azure diretamente.
- Você pode usar uma ferramenta de testes de HTTP REST 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.
- 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.
Veja mais informações sobre autenticação para solicitações de API.
- Uma maneira de gerar um token de portador para solicitações de API dos Gêmeos Digitais do Azure é com o comando da CLI az account get-access-token. Para obter instruções detalhadas, confira Adicionar token de portador.
- As solicitações às APIs dos Gêmeos Digitais do Azure exigem um usuário ou uma entidade de serviço que faça parte do mesmo locatário do Microsoft Entra ID em que existe a instância dos Gêmeos Digitais do Azure. 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 que o usuário ou a 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 acessar vários locatários, confira Escrever código de autenticação do aplicativo.
Notas do SDK
O SDK subjacente para os Gêmeos Digitais do Azure é o Azure.Core. Confira a documentação do namespace do Azure para obter a referência sobre os tipos e a infraestrutura do SDK.
Veja mais algumas informações sobre autenticação com os SDKs.
- Comece criando uma instância da classe
DigitalTwinsClient. 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.
Veja mais 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
Importar 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 relações 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 de 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 Trabalhos de Importação, você precisará habilitar as configurações de permissão descritas nessa seção.
Primeiro, você precisará de uma identidade gerenciada atribuída pelo sistema para sua instância dos Gêmeos Digitais do Azure. Para obter instruções sobre como configurar uma identidade gerenciada pelo sistema para a instância, confira Habilitar/desabilitar a identidade gerenciada para a instância.
Você precisará ter permissões de gravação na instância dos Gêmeos Digitais do Azure para as seguintes categorias de ação de dados:
Microsoft.DigitalTwins/jobs/*- Todos os elementos de grafo que você quer incluir na chamada Trabalhos. Isso pode incluir
Microsoft.DigitalTwins/models/*,Microsoft.DigitalTwins/digitaltwins/*e/ouMicrosoft.DigitalTwins/digitaltwins/relationships/*.
A função interna que fornece todas essas permissões é a de 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 as funções nos Gêmeos Digitais do Azure, confira Segurança para soluções dos Gêmeos Digitais do Azure.
Observação
Se você tentar uma chamada à API de Trabalhos de Importação e estiver faltando permissões de gravação para um dos tipos de elemento de grafo 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 relações, uma tentativa de importar em massa todos os três tipos de elementos só conseguirá importar os modelos e gêmeos. O status do trabalho refletirá uma falha e a mensagem indicará quais permissões estão ausentes.
Você também precisará conceder as seguintes permissões RBAC à identidade gerenciada atribuída pelo sistema da instância dos Gêmeos Digitais do Azure para que ela possa acessar arquivos de entrada e saída no contêiner do Armazenamento de Blobs do Azure:
- Leitor de Dados de Blobs de Armazenamento para o contêiner de blob de entrada do Armazenamento do Azure
- Colaborador de Dados de Blobs de Armazenamento para o contêiner de blob de saída do Armazenamento do Azure
Por fim, gere um token de portador que pode ser usado em suas solicitações para a API de Trabalhos. Para obter instruções, confira Adicionar token de portador.
Formatar dados
A API aceita a entrada de informações de grafo de um arquivo NDJSON, que deve ser carregado em um contêiner de armazenamento de blobs do Azure. O arquivo começa com uma seção Header, seguida pelas seções opcionais Models, Twins e Relationships. Você não precisa incluir todos os três tipos de dados de grafo no arquivo, mas todas as seções presentes devem seguir essa ordem. Os gêmeos e as relações criados com essa API podem incluir opcionalmente a inicialização de suas propriedades.
Veja 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 relações no NDJSON com suporte para a API de importação, confira Gerador NDJSON de Importação em Massa dos Gêmeos Digitais do Azure. O projeto de exemplo é escrito para .NET e pode ser baixado ou adaptado para lhe ajudá a criar seus próprios arquivos de importação.
Depois que o arquivo for criado, carregue-o em um blob de blocos 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 blobs do arquivo NDJSON no corpo da chamada à 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 grafo completo em uma chamada à API, confira Carregar modelos, gêmeos e relações 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 de forma independente. Para obter mais informações sobre como usar a API de Trabalhos de Importação com tipos de recursos individuais, confira as instruções da API de Trabalhos de Importação para modelos, gêmeos e relações.
No corpo da chamada à API, você fornecerá a URL de armazenamento de blobs do arquivo de entrada NDJSON. Você também fornecerá uma nova URL de armazenamento de blobs para indicar onde quer que o log de saída seja armazenado depois que o serviço o criar.
Importante
Verifique se a identidade gerenciada atribuída pelo sistema da instância dos Gêmeos Digitais do Azure tem as permissões RBAC do blob de armazenamento descritas na seção Verificar permissões.
Conforme 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. Veja um exemplo de log de saída para um trabalho bem-sucedido importando modelos, gêmeos e relações:
{"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 for concluído, você poderá ver o número total de entidades ingeridas usando a métrica BulkOperationEntityCount.
Também é possível cancelar uma importação de trabalho em execução com a operação Cancelar da API de Trabalhos de Importação. Depois que o trabalho tiver sido cancelado e não estiver mais em execução, você poderá excluí-lo.
Limites e considerações
Tenha as seguintes considerações em mente 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 no caso de falha, conclusão parcial do trabalho ou uso da operação Cancelar.
- Há suporte para apenas um trabalho em massa por vez em uma instância dos Gêmeos Digitais do Azure. Você pode exibir essas informações e outros limites numéricos das APIs de Trabalhos em limites dos Gêmeos Digitais do Azure.
Exclusão em massa com a API de Trabalhos de Exclusão
A API de Trabalhos de Exclusão é uma API de plano de dados que permite excluir todos os modelos, gêmeos e/ou relações em uma única chamada de API. As operações da API de Trabalhos de Exclusão 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 de Trabalhos de Exclusão:
- Para obter instruções sobre como gerar um token de portador para autenticar solicitações de API, confira Adicionar token de portador.
- Se você importou recentemente um grande número de entidades para o grafo, aguarde algum tempo e verifique se todos os elementos estão sincronizados no gráfico antes de iniciar o trabalho de exclusão.
- Interrompa 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 grafo que está sendo excluído, um trabalho de exclusão poderá 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. Esse é o tempo em que o trabalho de exclusão será executado antes de atingir o tempo limite; nesse momento, o serviço tentará interromper 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 de Trabalhos de Exclusão:
- Trabalhos de Exclusão 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.
- Há suporte para apenas um trabalho em massa por vez em uma instância dos Gêmeos Digitais do Azure. Você pode exibir essas informações e outros limites numéricos das APIs de Trabalhos em 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 as métricas dos Gêmeos Digitais do Azure, confira 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:
Ou pratique o uso do SDK do .NET criando um aplicativo cliente com este tutorial: