Documentação de referência do Swagger de Gêmeos Digitais do Azure
Importante
Uma nova versão do serviço dos Gêmeos Digitais do Azure foi lançada. À luz dos recursos expandidos do novo serviço, o serviço original dos Gêmeos Digitais do Azure (descrito neste conjunto de documentação) foi desativado.
Para exibir a documentação do novo serviço, visite a documentação ativa dos Gêmeos Digitais do Azure.
Cada instância de Gêmeos Digitais do Azure provisionada inclui sua própria documentação de referência do Swagger gerada automaticamente.
O Swagger, ou OpenAPI, une informações complexas da API em um recurso de referência interativo e independente de linguagem. O Swagger fornece material de referência crítico sobre quais cargas úteis, métodos HTTP e pontos de extremidade específicos do JSON devem ser usados para executar operações em uma API.
Resumo do Swagger
O Swagger fornece um resumo interativo da sua API, que inclui:
- API e informações do modelo de objeto.
- Endpoints da API REST que especificam os payloads, cabeçalhos, parâmetros, caminhos de contexto e métodos HTTP necessários para solicitações.
- Teste das funcionalidades de API.
- Exemplo de informações de resposta usadas para validar e confirmar respostas HTTP.
- Informações de código de erro.
O Swagger é uma ferramenta conveniente para auxiliar no desenvolvimento e teste de chamadas feitas às APIs de Gerenciamento de Gêmeos Digitais do Azure.
Dica
Uma versão prévia do Swagger é fornecida para demonstrar o conjunto de recursos da API. Ele está hospedado no docs.westcentralus.azuresmartspaces.net/management/swagger.
Você pode acessar sua própria documentação de Swagger da API de gerenciamento gerada em:
https://YOUR_INSTANCE_NAME.YOUR_LOCATION.azuresmartspaces.net/management/swagger
| Nome | Substitua por |
|---|---|
| NOME_DA_SUA_INSTÂNCIA | O nome da sua instância de Gêmeos Digitais do Azure |
| SUA_LOCALIZAÇÃO | Em qual região do servidor de sua instância está hospedada |
Material de referência
O material de referência do Swagger gerado automaticamente fornece uma visão geral rápida de conceitos importantes, pontos de extremidade de API de Gerenciamento disponíveis e uma descrição de cada modelo de objeto para auxiliar o desenvolvimento e teste.
Um resumo descreve a API.
Os modelos de objeto da API de Gerenciamento também são listados.
Você pode selecionar cada modelo de objeto listados para um resumo detalhado dos atributos de chave.
Os modelos de objeto do Swagger gerados são convenientes para ler todos os objetos e APIs dos Gêmeos Digitais do Azure disponíveis. Os desenvolvedores podem usar esse recurso ao criarem soluções nos Gêmeos Digitais do Azure.
Resumo de ponto de extremidade
O Swagger também fornece uma visão geral completa de todos os pontos de extremidade que compõem as APIs de Gerenciamento.
Cada terminal listado também inclui as informações de solicitação necessárias, como:
- Parâmetros obrigatórios.
- Tipos de dados de parâmetro necessários.
- Método HTTP para acessar o recurso.
Selecione cada recurso para exibir seu conteúdo adicional para obter uma visão geral mais detalhada.
Use Swagger para testar endpoints
Uma das funcionalidades poderosas que o Swagger oferece é a capacidade de testar um endpoint da API diretamente através da interface do usuário da documentação.
Depois de selecionar um ponto de extremidade específico, o botão Experimentar será exibido.
Expanda essa seção para exibir os campos de entrada para cada parâmetro obrigatório e opcional. Insira os valores corretos e selecione Executar.
Depois de executar o teste, você pode validar os dados de resposta.
Dados de resposta do Swagger
Cada ponto de extremidade listado também inclui dados de corpo de resposta para validar seu desenvolvimento e testes. Esses exemplos incluem os códigos de status e JSON para solicitações HTTP bem-sucedidas.
Os exemplos também incluem os códigos de erro para ajudar a depurar ou melhorar os testes com falha.
Autorização OAuth 2.0 do Swagger
Observação
- A entidade de usuário que criou o recurso dos Gêmeos Digitais do Azure terá uma atribuição de função de Administrador de Espaço e poderá criar atribuições de função adicionais para outros usuários. Esses usuários e suas funções podem ser autorizados a chamar as APIs.
Siga as etapas no Início Rápido para criar e configurar um aplicativo do Azure Active Directory. Como alternativa, você pode reutilizar um registro de aplicativo existente.
Adicione o seguinte URI de Redirecionamento ao registro de aplicativo do Azure Active Directory:
https://YOUR_SWAGGER_URL/ui/oauth2-redirect-htmlNome Substitua por Exemplo YOUR_SWAGGER_URL A URL de documentação da API REST de Gerenciamento encontrada no portal https://yourDigitalTwinsName.yourLocation.azuresmartspaces.net/management/swaggerMarque a caixa de seleçãode tokens de concessão> implícita do Access para permitir que o fluxo de concessão implícita OAuth 2.0 seja usado. Selecione Configurar e, em seguida, Salvar.
Copie a ID do cliente do aplicativo do Azure Active Directory.
Depois de concluir o registro do Azure Active Directory:
Selecione o botão Autorizar na página do Swagger.
Cole a ID do aplicativo no campo client_id .
Em seguida, você será redirecionado para o modal de sucesso a seguir.
Para saber mais sobre solicitações de teste interativo protegidas pelo OAuth 2.0, leia a documentação oficial.
Próximas etapas
Para ler mais sobre os modelos de objetos dos Gêmeos Digitais do Azure e o gráfico de inteligência espacial, leia Entender os modelos de objetos do Azure Digital Twins.
Para saber como se autenticar com sua API de gerenciamento, leia Autenticar com APIs.