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 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 Pageable<T> paginados ou AsyncPageable<T> como resultados. Para obter mais informações sobre a classe, consulte sua documentação de Pageable<T> referência, para obter mais informações sobre AsyncPageable<T>a , consulte sua documentação de 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.

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}

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.

À 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:

• Chamar as APIs do Azure Digital Twins

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

• Codifique um aplicativo cliente