Documentação de referência do Swagger de Gêmeos Digitais do Azure

Importante

Uma nova versão do serviço de gêmeos digital do Azure foi lançada. Na luz dos recursos expandidos do novo serviço, o serviço original do Azure gêmeos (descrito neste conjunto de documentação) foi desativado.

Para exibir a documentação do novo serviço, visite a documentação Active gêmeos digital 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 de API complexas 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.

Resumo do Swagger e informações de visão geral da API

Os modelos de objeto da API de Gerenciamento também são listados.

Modelos do Swagger listados na parte inferior da interface do usuário do Swagger

Você pode selecionar cada modelo de objeto listados para um resumo detalhado dos atributos de chave.

Modelos do Swagger expandidos para ler o conteúdo dos modelos

Os modelos de objeto do Swagger gerados são convenientes para ler todos os objetos e APIsdo Azure digital gêmeos 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.

Pontos de extremidade do Swagger exibidos na interface do usuário do Swagger

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.

Botão Experimente o Swagger

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.

Exemplo de resultado de teste do Swagger

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 o JSON para solicitações HTTP bem-sucedidas.

Exemplo de resposta de JSON do Swagger

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 de gêmeos digital 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.
  1. Siga as etapas no guia de início rápido para criar e configurar um aplicativo Azure Active Directory. Como alternativa, você pode reutilizar um registro de aplicativo existente.

  2. Adicione o seguinte URI de redirecionamento ao registro do aplicativo Azure Active Directory:

    Registrar a URL de redirecionamento do Swagger no AAD

    https://YOUR_SWAGGER_URL/ui/oauth2-redirect-html
    
    Name Substitua por Exemplo
    YOUR_SWAGGER_URL A URL da documentação da API REST de gerenciamento encontrada no portal https://yourDigitalTwinsName.yourLocation.azuresmartspaces.net/management/swagger
  3. Marque a caixa de seleção implícita conceder > acesso a tokens para permitir que o fluxo de concessão implícita do OAuth 2,0 seja usado. Selecione Configurare salvar.

  4. Copie a ID do cliente do seu aplicativo Azure Active Directory.

Depois de concluir o registro de Azure Active Directory:

  1. Selecione o botão autorizar na sua página do Swagger.

    Selecione o botão autorizar do Swagger

  2. Cole a ID do aplicativo no campo client_id .

    Campo de client_id do Swagger

  3. Em seguida, você será redirecionado para o seguinte modal com êxito.

    Modal de redirecionamento do Swagger

Para saber mais sobre as solicitações de teste interativamente protegidas pelo OAuth 2,0, leia a documentação oficial.

Próximas etapas