Compartilhar via

Como enviar solicitações às APIs dos Gêmeos Digitais do Azure usando o Visual Studio

  • Artigo

O Visual Studio 2022 tem suporte para arquivos .http, que podem ser usados para estruturar, armazenar e enviar diretamente solicitações HTTP a partir do aplicativo. Usar essa funcionalidade do Visual Studio é uma maneira de criar solicitações HTTP e enviá-las para as APIs REST dos Gêmeos Digitais do Azure. Este artigo descreve como configurar um arquivo .http no Visual Studio que pode interagir com as APIs dos Gêmeos Digitais do Azure.

Este artigo contém informações sobre as seguintes etapas:

  1. Configure um projeto do Visual Studio e um arquivo .http, com variáveis que representam sua instância dos Gêmeos Digitais do Azure.
  2. Use a CLI do Azure para obter um token de portador que será usado para fazer solicitações de API no Visual Studio.
  3. Use a documentação da API REST dos Gêmeos Digitais do Azure como um recurso para criar solicitações no arquivo .http e enviá-las para as APIs dos Gêmeos Digitais do Azure.

Os Gêmeos Digitais do Azure têm dois conjuntos de APIs com os quais você pode trabalhar: plano de dados e plano de controle. Para saber mais sobre a diferença entre esses conjuntos de APIs, confira APIs e SDKs dos Gêmeos Digitais do Azure. Este artigo contém instruções para ambos os conjuntos de APIs.

Para obter mais informações sobre o suporte para arquivos .http no Visual Studio, consulte Usar arquivos .http no Visual Studio 2022.

Pré-requisitos

Para fazer solicitações para as APIs dos Gêmeos Digitais do Azure usando o Visual Studio, você precisa configurar uma instância dos Gêmeos Digitais do Azure e baixar o Visual Studio 2022. Esta seção é para essas etapas.

Configurar instância dos Gêmeos Digitais do Azure

Para trabalhar com os Gêmeos Digitais do Azure neste artigo, você precisará ter uma instância dos Gêmeos Digitais do Azure e as permissões necessárias para usá-la. Se você já tiver uma instância dos Gêmeos Digitais do Azure configurada, use essa instância e vá direto para a próxima seção. Caso contrário, siga as instruções descritas em Configurar uma instância e uma autenticação. As instruções contêm informações que ajudarão você a verificar se cada etapa foi concluída com êxito.

Após configurar a instância, anote o nome do host da instância. Encontre o nome do host no portal do Azure.

Baixar o Visual Studio 2022

Em seguida, baixe o Visual Studio 2022. Inclua a carga de trabalho ASP.NET e de desenvolvimento para a Web em sua instalação.

Configurar um projeto do Visual Studio

Nesta seção, você configurará o projeto no Visual Studio que será usado para criar solicitações HTTP.

Abra o Visual Studio em seu computador e crie um novo projeto. Use o modelo de projeto ASP.NET Core Vazio.

Captura de tela de um modelo de projeto do ASP.NET Core Vazio no Visual Studio.

Siga as instruções em Criar um arquivo .http para criar um novo arquivo .http em seu projeto.

Adicionar variáveis

Em seguida, adicione algumas variáveis na parte superior do arquivo .http que serão usadas para se conectar ao recurso dos Gêmeos Digitais do Azure.

O conjunto de variáveis necessárias depende de qual conjunto de APIs você está usando, portanto, use as guias abaixo para selecionar entre as APIs de plano de dados e de painel de controle.

Adicione as variáveis a seguir para solicitações de plano de dados. Há um espaço reservado para o nome do host da sua instância dos Gêmeos Digitais do Azure (ele termina em digitaltwins.azure.net).

@hostName=<host-name-of-your-Azure-Digital-Twins-instance>
@DPversion=2023-10-31

Adicionar o token de portador

Agora que você configurou sua instância dos Gêmeos Digitais do Azure e seu projeto do Visual Studio, você precisa obter um token de portador que pode ser usado pelas solicitações HTTP para autorizar nas APIs dos Gêmeos Digitais do Azure.

Há várias maneiras de obter esse token. Este artigo usa a CLI do Azure para entrar em sua conta do Azure e obter um token.

Caso tenha uma CLI do Azure instalada localmente, será possível iniciar um prompt de comando em seu computador para executar os comandos a seguir. Caso contrário, você pode abrir uma janela de Azure Cloud Shell no navegador e executar os comandos por ali.

  1. Primeiro, verifique se você está conectado ao Azure com as credenciais apropriadas, executando este comando:

    az login

  2. Em seguida, use o comando az account get-access-token para obter um token de portador com acesso ao serviço dos Gêmeos Digitais do Azure. Nesse comando, você passará a ID do recurso para o ponto de extremidade de serviço dos Gêmeos Digitais para obter um token de acesso que possa acessar os recursos dos Gêmeos Digitais do Azure.

    O contexto necessário para o token depende de qual conjunto de APIs você está usando, portanto, use as guias abaixo para selecionar entre as APIs de plano de dados e painel de controle.

    Para obter um token a ser usado com as APIs do plano de dados, use o seguinte valor estático para o contexto do token: 0b07f429-9f4b-4714-9392-cc5e8e80c8b0. Esse valor é a ID de recurso para o ponto de extremidade de serviço dos Gêmeos Digitais do Azure.

    az account get-access-token --resource 0b07f429-9f4b-4714-9392-cc5e8e80c8b0

    Observação

    Caso precise acessar sua instância dos Gêmeos Digitais do Azure usando uma entidade de serviço ou uma conta de usuário que pertença a um locatário do Microsoft Entra diferente da instância, será preciso solicitar um token do locatário da "página inicial" da instância dos Gêmeos Digitais do Azure. Para obter mais informações sobre esse processo, confira Escrever um código de autenticação de aplicativo.

  3. Copie o valor de accessToken no resultado. Esse valor é o valor do token que você colará no Visual Studio para autorizar suas solicitações.

    Captura de tela do console mostrando o resultado do comando az account get-access-token. O campo accessToken com um valor de exemplo realçado.

Dica

Esse token é válido por um tempo mínimo de cinco minutos e um tempo máximo 60 de minutos. Se acabar o tempo alocado para o token atual, você pode repetir as etapas nesta seção para obter um novo.

Adicionar token ao arquivo .http

Em seu arquivo .http no Visual Studio, adicione outra variável que contém o valor do seu token.

@token=<paste-data-plane-token>

Suas variáveis agora devem ser semelhantes ao seguinte:

Captura de tela das variáveis do plano de dados, incluindo um token.

Adicionar solicitações

Agora que o arquivo .http está configurado, você pode adicionar solicitações às APIs do Gêmeo Digital do Azure.

Comece abrindo a referência da API REST dos Gêmeos Digitais do Azure. Esta documentação contém detalhes de todas as operações executadas pelas APIs. Navegue até a página de referência da solicitação que você deseja executar.

Este artigo usará a API de Atualização DigitalTwins do plano de dados como exemplo.

  1. Adicionar modelo de solicitação: copie a solicitação HTTP mostrada na documentação de referência.

    Captura de tela da solicitação HTTP na documentação da API dos Gêmeos Digitais.

    No Visual Studio, cole a solicitação em uma nova linha abaixo das variáveis em seu arquivo .http.

  2. Adicionar parâmetros: examine a seção Parâmetros de URI da documentação de referência para ver quais valores de parâmetro são necessários para a solicitação. Você pode substituir algumas pelas variáveis criadas anteriormente e preencher outros valores de parâmetro conforme apropriado. Para fazer referência a uma variável, coloque o nome da variável em chaves duplas, como {{variable}}. Para obter mais detalhes, consulte Variáveis.

    Observação

    Para solicitações de plano de dados, digitaltwins-hostname também é um parâmetro. Substitua isso por {{hostName}} para usar o valor da variável de nome do host.

    Veja a aparência desta etapa em uma solicitação de exemplo:

    Captura de tela da solicitação com parâmetros no Visual Studio.

  3. Adicionar autorização: adicione a seguinte linha (exatamente como escrito) diretamente abaixo da solicitação, para especificar a autenticação com sua variável de token de portador.

    Authorization: Bearer {{token}}

    Veja a aparência desta etapa em uma solicitação de exemplo:

    Captura de tela da solicitação com a linha de autorização no Visual Studio.

  4. Adicionar cabeçalhos adicionais: examine a seção Cabeçalho da Solicitação da documentação de referência para ver quais valores de cabeçalho podem acompanhar a solicitação. Talvez você também queira incluir cabeçalhos HTTP tradicionais como Content-Type. Adicione cada cabeçalho em sua própria linha no formato HeaderName: Value. Para obter mais detalhes, consulte Cabeçalhos de solicitação.

    Veja a aparência desta etapa em uma solicitação de exemplo:

    Captura de tela da solicitação com outro cabeçalho no Visual Studio.

  5. Adicionar corpo: examine a seção Corpo da Solicitação da documentação de referência para ver quais informações do corpo podem ser necessárias para a solicitação. Adicione o corpo da solicitação após uma linha em branco. Para obter mais detalhes, consulte Corpo da solicitação.

    Veja a aparência desta etapa em uma solicitação de exemplo: Captura de tela da solicitação com um corpo no Visual Studio.

  6. Quando a solicitação estiver pronta, selecione Enviar solicitação acima da solicitação para enviá-la.

    Captura de tela de Enviar solicitação no Visual Studio.

O Visual Studio abre um painel com os detalhes da resposta. Examine a seção Respostas da documentação de referência para interpretar o código de status e quaisquer dados no corpo da resposta.

Captura de tela da resposta no Visual Studio.

Adicionar solicitações adicionais

Para adicionar mais solicitações ao arquivo .http, separe-as com ### como um delimitador.

Captura de tela de várias solicitações em um arquivo no Visual Studio.

Próximas etapas

Para obter mais detalhes sobre como enviar solicitações com arquivos .http no Visual Studio, incluindo detalhes de sintaxe e cenários avançados, consulte Usar arquivos .http no Visual Studio 2022.

Para saber mais sobre as APIs dos Gêmeos Digitais, leia o artigo APIs e SDKs dos Gêmeos Digitais do Azure ou veja a documentação de referência das APIs REST.