Come inviare richieste alle API di Gemelli digitali di Azure con Visual Studio

Visual Studio 2022 include il supporto per .http i file, che possono essere usati per strutturare, archiviare e inviare direttamente richieste HTTP dall'applicazione. L'uso di questa funzionalità di Visual Studio è un modo per creare richieste HTTP e inviarle alle API REST di Gemelli digitali di Azure. Questo articolo descrive come configurare un .http file in Visual Studio in grado di interfacciarsi con le API di Gemelli digitali di Azure.

In questo articolo vengono riportate informazioni sui passaggi seguenti:

1. Configurare un progetto e .http un file di Visual Studio, con variabili che rappresentano l'istanza di Gemelli digitali di Azure.
2. Usare l'interfaccia della riga di comando di Azure per ottenere un token di connessione che è possibile usare per effettuare richieste API in Visual Studio.
3. Usare la documentazione dell'API REST di Gemelli digitali di Azure come risorsa per creare richieste nel .http file e inviarle alle API di Gemelli digitali di Azure.

Gemelli digitali di Azure include due set di API che è possibile usare: piano dati e piano di controllo. Per altre informazioni sulla differenza tra questi set di API, vedere API e SDK di Gemelli digitali di Azure. Questo articolo contiene istruzioni per entrambi i set di API.

Per altre informazioni sul .http supporto dei file in Visual Studio, vedere Usare file .http in Visual Studio 2022.

Prerequisiti

Per effettuare richieste alle API di Gemelli digitali di Azure usando Visual Studio, è necessario configurare un'istanza di Gemelli digitali di Azure e scaricare Visual Studio 2022. Questa sezione è per questi passaggi.

Configurare l'istanza di Gemelli digitali di Azure

Per usare Gemelli digitali di Azure come descritto in questo articolo, è necessaria un'istanza di Gemelli digitali di Azure e le autorizzazioni necessarie per l'utilizzo. Se in precedenza è stata già configurata un'istanza di Gemelli digitali di Azure, è possibile usare tale istanza e passare alla sezione successiva. In caso contrario, seguire le istruzioni riportate in Configurare un'istanza e l'autenticazione. Le istruzioni contengono informazioni che consentono di verificare che ogni passaggio sia stato completato correttamente.

Dopo aver configurato l'istanza, prendere nota del nome host dell'istanza. È possibile trovare il nome host nel portale di Azure.

Scarica Visual Studio 2022

Scaricare quindi Visual Studio 2022. Assicurarsi di includere il carico di lavoro ASP.NET e sviluppo Web nell'installazione.

Configurare il progetto di Visual Studio

In questa sezione viene configurato il progetto in Visual Studio che verrà usato per creare richieste HTTP.

Aprire Visual Studio nel computer e creare un nuovo progetto. Usare il modello di progetto core vuoto ASP.NET.

Seguire le istruzioni in Creare un file con estensione http per creare un nuovo .http file nel progetto.

Aggiungi variabili

Aggiungere quindi alcune variabili all'inizio del .http file che verranno usate per connettersi alla risorsa di Gemelli digitali di Azure.

Il set di variabili necessarie dipende dal set di API in uso, quindi usare le schede seguenti per selezionare tra le API del piano dati e del piano di controllo.

Piano dati

Aggiungere le variabili seguenti per le richieste del piano dati. Esiste un segnaposto per il nome host dell'istanza di Gemelli digitali di Azure (termina in digitaltwins.azure.net).

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

Piano di controllo

Aggiungere le variabili seguenti per le richieste del piano di controllo. Contengono segnaposto per i valori delle risorse.

@instance=<name-of-your-Azure-Digital-Twins-instance>
@subscription=<ID-of-your-Azure-subscription>
@resourceGroup=<resource-group>
@CPversion=2023-01-31

Aggiungere il token di connessione

Dopo aver configurato l'istanza di Gemelli digitali di Azure e il progetto di Visual Studio, è necessario ottenere un token di connessione che le richieste HTTP possono usare per autorizzare le API di Gemelli digitali di Azure.

Esistono diversi modi per ottenere questo token. Questo articolo usa l'interfaccia della riga di comando di Azure per accedere all'account Azure e ottenere un token in questo modo.

Se è installata l’interfaccia della riga di comando di Azure in locale, è possibile avviare un prompt dei comandi nel computer per eseguire i comandi seguenti. In caso contrario, è possibile aprire una finestra di Azure Cloud Shell nel browser ed eseguire i comandi in questa posizione.

1. Prima di tutto, assicurarsi di aver eseguito l'accesso ad Azure con le credenziali corrette, eseguendo questo comando:

   az login
   

2. Usare quindi il comando az account get-access-token per ottenere un token di connessione con accesso al servizio Gemelli digitali di Azure. In questo comando si passa l'ID risorsa per l'endpoint del servizio Gemelli digitali di Azure per ottenere un token di accesso che può accedere alle risorse di Gemelli digitali di Azure.

   Il contesto necessario per il token dipende dal set di API in uso, quindi usare le schede seguenti per selezionare tra le API del piano dati e del piano di controllo.

   Piano dati

   Per ottenere un token da usare con le API del piano dati, usare il valore statico seguente per il contesto del token: 0b07f429-9f4b-4714-9392-cc5e8e80c8b0. Questo valore è l'ID risorsa per l'endpoint del servizio Gemelli digitali di Azure.

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

   Piano di controllo

   Per ottenere un token da usare con le API del piano di controllo, usare il seguente valore per il contesto del token: https://management.azure.com/.

   az account get-access-token --resource https://management.azure.com/
   

   Nota

   Se è necessario accedere all'istanza di Gemelli digitali di Azure usando un'entità servizio o un account utente appartenente a un tenant Microsoft Entra diverso dall'istanza di , è necessario richiedere un token dal tenant "home" dell'istanza di Gemelli digitali di Azure. Per altre informazioni su questo processo, vedere Scrivere codice di autenticazione dell'app.

3. Copiare il valore di accessToken nel risultato. Questo valore è il valore del token che verrà incollato in Visual Studio per autorizzare le richieste.

   

Suggerimento

Questo token è valido per almeno cinque minuti e un massimo di 60 minuti. Se si esaurisce il tempo assegnato per il token corrente, è possibile ripetere i passaggi descritti in questa sezione per ottenerne uno nuovo.

Aggiungere un token al .http file

.http Nel file in Visual Studio aggiungere un'altra variabile che contiene il valore del token.

Piano dati

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

Le variabili dovrebbero ora avere un aspetto simile al seguente:

Piano di controllo

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

Le variabili dovrebbero ora avere un aspetto simile al seguente:

Aggiungere richieste

Ora che il .http file è configurato, è possibile aggiungere richieste alle API di Gemelli digitali di Azure.

Per iniziare, aprire le informazioni di riferimento sull'API REST di Gemelli digitali di Azure. Questa documentazione contiene i dettagli di tutte le operazioni coperte dalle API. Passare alla pagina di riferimento della richiesta da eseguire.

Questo articolo userà l'API DigitalTwins Update dal piano dati come esempio.

1. Aggiungere un modello di richiesta: copiare la richiesta HTTP illustrata nella documentazione di riferimento.

   

   In Visual Studio incollare la richiesta in una nuova riga sotto le variabili nel .http file.

2. Aggiungere parametri: esaminare la sezione Parametri URI della documentazione di riferimento per vedere quali valori dei parametri sono necessari per la richiesta. È possibile sostituire alcuni con le variabili create in precedenza e inserire altri valori di parametro in base alle esigenze. Per fare riferimento a una variabile, inserire il nome della variabile tra parentesi graffe doppie, ad esempio {{variable}}. Per altri dettagli, vedere Variabili.

   Nota

   Per le richieste del piano dati, digitaltwins-hostname è anche un parametro . Sostituire con per {{hostName}} usare il valore della variabile del nome host.

   Ecco come appare questo passaggio in una richiesta di esempio:

   

3. Aggiungi autorizzazione: aggiungere la riga seguente (esattamente come scritta) direttamente sotto la richiesta, per specificare l'autenticazione con la variabile del token di connessione.

   Authorization: Bearer {{token}}
   

   Ecco come appare questo passaggio in una richiesta di esempio:

   

4. Aggiungere altre intestazioni: esaminare la sezione Intestazione richiesta della documentazione di riferimento per vedere quali valori di intestazione possono accompagnare la richiesta. È anche possibile includere intestazioni HTTP tradizionali come Content-Type. Aggiungere ogni intestazione sulla propria riga nel formato HeaderName: Value. Per altri dettagli, vedere Intestazioni della richiesta.

   Ecco come appare questo passaggio in una richiesta di esempio:

   

5. Aggiungi corpo: esaminare la sezione Corpo della richiesta della documentazione di riferimento per vedere quali informazioni sul corpo potrebbero essere necessarie per la richiesta. Aggiungere il corpo della richiesta dopo una riga vuota. Per altri dettagli, vedere Corpo della richiesta.

   Ecco come appare questo passaggio in una richiesta di esempio:

6. Quando la richiesta è pronta, selezionare Invia richiesta sopra la richiesta per inviarla.

   

Visual Studio visualizza un riquadro con i dettagli della risposta. Esaminare la sezione Risposte della documentazione di riferimento per interpretare il codice di stato e i dati nel corpo della risposta.

Aggiungere altre richieste

Per aggiungere altre richieste al .http file, separarle con ### come delimitatore.

Passaggi successivi

Per altre informazioni sull'invio di richieste con .http file in Visual Studio, inclusi i dettagli della sintassi e gli scenari avanzati, vedere Usare file .http in Visual Studio 2022.

Per altre informazioni sulle API di Gemelli digitali, vedere API e SDK di Gemelli digitali di Azure oppure visualizzare la documentazione di riferimento per le API REST.