Partilhar via

Como enviar solicitações para as APIs do Azure Digital Twins usando o Visual Studio

  • Artigo

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

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

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

O Azure Digital Twins tem dois conjuntos de APIs com os quais você pode trabalhar: plano de dados e plano de controle. Para obter mais informações sobre a diferença entre esses conjuntos de APIs, consulte APIs e SDKs do Azure Digital Twins. Este artigo contém instruções para ambos os conjuntos de API.

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

Pré-requisitos

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

Configurar a instância do Azure Digital Twins

Para trabalhar com Gêmeos Digitais do Azure neste artigo, você precisará de uma instância de Gêmeos Digitais do Azure e as permissões necessárias para usá-la. Se você já tiver uma instância do Azure Digital Twins configurada, poderá usar essa instância e pular para a próxima seção. Caso contrário, siga as instruções em Configurar uma instância e autenticação. As instruções contêm informações para ajudá-lo a verificar se você concluiu cada etapa com êxito.

Depois de configurar sua instância, anote o nome do host da instância. Você pode encontrar o nome do host no portal do Azure.

Baixar Visual Studio 2022

Em seguida, baixe o Visual Studio 2022. Certifique-se de incluir a carga de trabalho de ASP.NET e desenvolvimento da Web em sua instalação.

Configurar o projeto do Visual Studio

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

Abra o Visual Studio em sua máquina e crie um novo projeto. Use o modelo de projeto ASP.NET Core Empty .

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

Siga as instruções em Criar um arquivo .http para criar um novo .http arquivo 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 do Azure Digital Twins.

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

Adicione as seguintes variáveis para solicitações de plano de dados. Há um espaço reservado para o nome do host da sua instância do Azure Digital Twins (ele termina em digitaltwins.azure.net).

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

Adicionar token ao portador

Agora que você configurou sua instância do Azure Digital Twins e o projeto do Visual Studio, você precisa obter um token de portador que as solicitações HTTP possam usar para autorizar nas APIs do Azure Digital Twins.

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 dessa maneira.

Se você tiver uma CLI do Azure instalada localmente, poderá iniciar um prompt de comando em sua máquina para executar os seguintes comandos. Caso contrário, você pode abrir uma janela do Azure Cloud Shell em seu navegador e executar os comandos lá.

  1. Primeiro, certifique-se de que tem sessão iniciada no Azure com as credenciais certas, 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 Gêmeos Digitais do Azure. Neste comando, você passa a ID do recurso para o ponto de extremidade do serviço Gêmeos Digitais do Azure, 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 APIs de plano de dados e de plano de controle.

    Para obter um token para usar 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 do recurso para o ponto de extremidade do serviço Gêmeos Digitais do Azure.

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

    Nota

    Se você precisar acessar sua instância do Azure Digital Twins usando uma entidade de serviço ou conta de usuário que pertença a um locatário diferente do Microsoft Entra da instância, precisará solicitar um token do locatário "home" da instância do Azure Digital Twins. Para obter mais informações sobre esse processo, consulte Escrever 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.

Gorjeta

Este token é válido por pelo menos cinco minutos e no máximo 60 minutos. Se você ficar sem tempo alocado para o token atual, poderá repetir as etapas nesta seção para obter um novo.

Adicionar token ao .http arquivo

Em seu .http arquivo 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 ter esta aparência:

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

Adicionar pedidos

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

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

Este artigo usará a API de atualização do 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 do Digital Twins.

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

  2. Adicionar parâmetros: Consulte a seção Parâmetros de URI da documentação de referência para ver quais valores de parâmetros 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.

    Nota

    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 como essa etapa aparece 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 escrita) diretamente abaixo da solicitação, para especificar a autenticação com sua variável de token de portador.

    Authorization: Bearer {{token}}

    Veja como essa etapa aparece em uma solicitação de exemplo:

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

  4. Adicionar cabeçalhos adicionais: Consulte 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. Você também pode querer 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 como essa etapa aparece em uma solicitação de exemplo:

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

  5. Adicionar corpo: Consulte 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 como essa etapa aparece 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 exibe um painel com os detalhes da resposta. Consulte a secção Respostas da documentação de referência para interpretar o código de estado e quaisquer dados no corpo da resposta.

Captura de tela da resposta no Visual Studio.

Adicionar pedidos adicionais

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

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

Próximos passos

Para obter mais detalhes sobre como enviar solicitações com .http arquivos 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 do Digital Twins, leia APIs e SDKs do Azure Digital Twins ou veja a documentação de referência para as APIs REST.