APIs e SDKs do Azure Digital Twins
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 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.
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:
DigitalTwinModels- A categoria DigitalTwinModels contém APIs para gerenciar os modelos em uma instância do Azure Digital Twins. As atividades de gerenciamento incluem upload, validação, recuperação e exclusão de modelos criados na DTDL.DigitalTwins- A categoria DigitalTwins contém as APIs que permitem aos desenvolvedores criar, modificar e excluir gêmeos digitais e seus relacionamentos em uma instância do Azure Digital Twins.Query- A categoria Consulta permite que os desenvolvedores encontrem conjuntos de gêmeos digitais no gráfico de gêmeos entre relacionamentos.Event Routes- A categoria Rotas de Eventos contém APIs para rotear dados, através do sistema e para serviços downstream.Import Jobs- A API de Trabalhos de Importação permite gerenciar uma ação assíncrona de longa duração para importar modelos, gêmeos e relacionamentos em massa.Delete Jobs- A API Delete Jobs permite gerenciar uma ação assíncrona de longa duração para excluir todos os modelos, gêmeos e relacionamentos em uma instância.
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.
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.
- Você pode usar uma ferramenta de teste HTTP REST para fazer chamadas diretas para as APIs do Azure Digital Twins. Para obter mais informações sobre esse processo, consulte Chamar as APIs do Azure Digital Twins.
- Atualmente, o Azure Digital Twins não suporta CORS (Cross-Origin Resource Sharing). Para saber mais sobre as estratégias de impacto e resolução, veja Compartilhamento de recursos entre origens (CORS) para 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 Azure Digital Twins é com o comando az account get-access-token CLI. Para obter instruções detalhadas, consulte Adicionar 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
DigitalTwinsClientclasse. O construtor requer credenciais que podem ser obtidas com diferentes tipos de métodos de autenticação noAzure.Identitypacote. Para obter mais informações sobreAzure.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 sobreInteractiveBrowserCredentialo , 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
DigitalTwinsClientclasse. - 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
tryseção e capturar pelo menosRequestFailedExceptions. 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), ondeTé 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 seuValuecampo. - Métodos de serviço com retorno de resultados
Pageable<T>paginados ouAsyncPageable<T>como resultados. Para obter mais informações sobre a classe, consulte sua documentação dePageable<T>referência, para obter mais informações sobreAsyncPageable<T>a , consulte sua documentação de referência. - Você pode iterar sobre resultados paginados usando um
await foreachloop. 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 digitalBasicDigitalTwinComponent: Representa genericamente um componente nasContentspropriedades de umBasicDigitalTwinBasicRelationship: Representa genericamente os dados principais de uma relaçãoDigitalTwinsJsonPropertyName: 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/ouMicrosoft.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:
- Leitor de Dados de Blob de Armazenamento para o contêiner de blob de entrada do Armazenamento do Azure
- Contribuidor 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 Adicionar 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 Adicionar 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:
Ou, pratique o uso do SDK do .NET criando um aplicativo cliente com este tutorial: