Esercitazione: Firmare e effettuare richieste con Postman

In questa esercitazione verrà configurato e si userà Postman per eseguire una richiesta per Servizi di comunicazione di Azure tramite HTTP. Alla fine di questa esercitazione verrà inviato correttamente un messaggio SMS usando Servizi di comunicazione e Postman. Sarà quindi possibile usare Postman per esplorare altre API all'interno di Servizi di comunicazione di Azure.

Questa esercitazione sarà:

Prerequisiti

• Un account Azure con una sottoscrizione attiva. Per informazioni dettagliate, vedere Creare un account gratuito. L'account gratuito offre $ 200 in crediti di Azure per provare qualsiasi combinazione di servizi.
• Una stringa di connessione e una risorsa attiva di Servizi di comunicazione. Informazioni su come creare una risorsa di Servizi di comunicazione.
• Un numero di telefono Servizi di comunicazione di Azure che può inviare messaggi SMS, vedere Ottenere un numero di telefono per ottenere uno.

Download e installazione di Postman

Postman, è un'applicazione desktop in grado di effettuare richieste API su qualsiasi API HTTP. Viene comunemente usato per il test e l'esplorazione delle API. Verrà scaricata la versione desktop più recente dal sito Web di Postman. Postman ha versioni per Windows, Mac e Linux, quindi scaricare la versione appropriata per il sistema operativo. Dopo aver scaricato l'applicazione. Verrà visualizzata una schermata iniziale, che chiede di accedere o di creare un account Postman. La creazione di un account è facoltativa e può essere ignorata facendo clic sul collegamento "Ignora e vai all'app". La creazione di un account salva le impostazioni della richiesta API a Postman, che consente quindi di raccogliere le richieste in altri computer.

Dopo aver creato un account o ignorato crearne uno, è ora possibile visualizzare la finestra principale di Postman.

Creazione e configurazione di una raccolta Postman

Postman, può organizzare le richieste in molti modi. Ai fini di questa esercitazione. Verrà creata una raccolta Postman. A tale scopo, selezionare il pulsante raccolte sul lato sinistro dell'applicazione:

Dopo aver selezionato, fare clic su "Crea nuova raccolta", per avviare il processo di creazione della raccolta. Verrà aperta una nuova scheda nell'area centrale di Postman. Assegnare un nome alla raccolta qualsiasi cosa desiderata. Qui la raccolta è denominata "Servizi di comunicazione di Azure":

Dopo aver creato e denominato la raccolta, è possibile configurarla.

Aggiunta di variabili di raccolta

Per gestire l'autenticazione e semplificare le richieste, verranno specificate due variabili di raccolta all'interno della raccolta di Servizi di comunicazione appena creata. Queste variabili sono disponibili per tutte le richieste all'interno della raccolta di Servizi di comunicazione. Per iniziare a creare variabili, visitare la scheda Della variabile della raccolta.

Una volta nella scheda raccolta, creare due variabili:

• key: questa variabile deve essere una delle chiavi della pagina chiave del Servizi di comunicazione di Azure all'interno dell'portale di Azure. Ad esempio, oW...A==.
• endpoint: questa variabile deve essere l'endpoint del Servizi di comunicazione di Azure dalla pagina della chiave. Assicurarsi di rimuovere la barra finale. Ad esempio, https://contoso.communication.azure.com.

Immettere questi valori nella colonna "Valore iniziale" della schermata delle variabili. Dopo aver immesso, premere il pulsante "Persistent All" appena sopra la tabella a destra. Se configurata correttamente, la schermata Postman dovrebbe avere un aspetto simile al seguente:

Per altre informazioni sulle variabili, vedere la documentazione di Postman.

Creazione di uno script di pre-richiesta

Il passaggio successivo consiste nel creare uno script pre-richiesta all'interno di Postman. Uno script pre-richiesta è uno script che viene eseguito prima di ogni richiesta in Postman e può modificare o modificare i parametri di richiesta per conto dell'utente. Questa operazione verrà usata per firmare le richieste HTTP in modo che possano essere autorizzate da Servizi di comunicazione di Azure. Per altre informazioni sui requisiti di firma, è possibile leggere la guida sull'autenticazione.

Verrà creato questo script all'interno della raccolta in modo che venga eseguito in qualsiasi richiesta all'interno della raccolta. A tale scopo, nella scheda raccolta fare clic sulla sotto-scheda "Script pre-richiesta".

In questa scheda secondaria è possibile creare uno script di pre-richiesta immettendolo nell'area di testo seguente. Può essere più facile scrivere questo, all'interno di un editor di codice completo, ad esempio Visual Studio Code prima di incollarlo al termine. Verrà illustrata ogni parte dello script in questa esercitazione. Se vuoi copiarlo in Postman e iniziare, puoi solo copiarlo. Iniziamo a scrivere lo script.

Scrittura dello script pre-richiesta

La prima cosa che verrà eseguita consiste nel creare una stringa UTC (Coordinated Universal Time) e aggiungerlo all'intestazione HTTP "Date". Questa stringa viene archiviata anche in una variabile da usare più avanti quando si firma:

// Set the Date header to our Date as a UTC String.
const dateStr = new Date().toUTCString();
pm.request.headers.upsert({key:'Date', value: dateStr});

Verrà quindi eseguito l'hash del corpo della richiesta usando SHA 256 e inserirlo nell'intestazione x-ms-content-sha256 . Postman include alcune librerie standard per l'hashing e la firma a livello globale, quindi non è necessario installarle o richiederle:

// Hash the request body using SHA256 and encode it as Base64
const hashedBodyStr = CryptoJS.SHA256(pm.request.body.raw).toString(CryptoJS.enc.Base64)
// And add that to the header x-ms-content-sha256
pm.request.headers.upsert({
    key:'x-ms-content-sha256',
    value: hashedBodyStr
});

A questo punto, verrà usata la variabile di endpoint specificata in precedenza per distinguere il valore per l'intestazione host HTTP. È necessario eseguire questa operazione perché l'intestazione host non viene impostata finché non viene elaborato questo script:

// Get our previously specified endpoint variable
const endpoint = pm.variables.get('endpoint')
// Remove the https, prefix to create a suitable "Host" value
const hostStr = endpoint.replace('https://','');

Con queste informazioni create, è ora possibile creare la stringa, che verrà eseguita la firma per la richiesta HTTP, costituita da diversi valori creati in precedenza:

// This gets the part of our URL that is after the endpoint, for example in https://contoso.communication.azure.com/sms, it will get '/sms'
const url = pm.request.url.toString().replace('{{endpoint}}','');

// Construct our string which we'll sign, using various previously created values.
const stringToSign = pm.request.method + '\n' + url + '\n' + dateStr + ';' + hostStr + ';' + hashedBodyStr;

Infine, è necessario firmare questa stringa usando la chiave di Servizi di comunicazione e quindi aggiungerla alla richiesta nell'intestazione Authorization :

// Decode our access key from previously created variables, into bytes from base64.
const key = CryptoJS.enc.Base64.parse(pm.variables.get('key'));
// Sign our previously calculated string with HMAC 256 and our key. Convert it to Base64.
const signature = CryptoJS.HmacSHA256(stringToSign, key).toString(CryptoJS.enc.Base64);

// Add our final signature in Base64 to the authorization header of the request.
pm.request.headers.upsert({
    key:'Authorization',
    value: "HMAC-SHA256 SignedHeaders=date;host;x-ms-content-sha256&Signature=" + signature
});

Script di pre-richiesta finale

Lo script di pre-richiesta finale dovrebbe essere simile al seguente:

// Set the Date header to our Date as a UTC String.
const dateStr = new Date().toUTCString();
pm.request.headers.upsert({key:'Date', value: dateStr});

// Hash the request body using SHA256 and encode it as Base64
const hashedBodyStr = CryptoJS.SHA256(pm.request.body.raw).toString(CryptoJS.enc.Base64)
// And add that to the header x-ms-content-sha256
pm.request.headers.upsert({
    key:'x-ms-content-sha256',
    value: hashedBodyStr
});

// Get our previously specified endpoint variable
const endpoint = pm.variables.get('endpoint')
// Remove the https, prefix to create a suitable "Host" value
const hostStr = endpoint.replace('https://','');

// This gets the part of our URL that is after the endpoint, for example in https://contoso.communication.azure.com/sms, it will get '/sms'
const url = pm.request.url.toString().replace('{{endpoint}}','');

// Construct our string which we'll sign, using various previously created values.
const stringToSign = pm.request.method + '\n' + url + '\n' + dateStr + ';' + hostStr + ';' + hashedBodyStr;

// Decode our access key from previously created variables, into bytes from base64.
const key = CryptoJS.enc.Base64.parse(pm.variables.get('key'));
// Sign our previously calculated string with HMAC 256 and our key. Convert it to Base64.
const signature = CryptoJS.HmacSHA256(stringToSign, key).toString(CryptoJS.enc.Base64);

// Add our final signature in Base64 to the authorization header of the request.
pm.request.headers.upsert({
    key:'Authorization',
    value: "HMAC-SHA256 SignedHeaders=date;host;x-ms-content-sha256&Signature=" + signature
});

Immettere o incollare questo script finale nell'area di testo all'interno della scheda Script pre-richiesta:

Dopo aver immesso, premere CTRL + S o premere il pulsante salva in modo da salvare lo script nella raccolta.

Creazione di una richiesta in Postman

Ora che tutto è configurato, è possibile creare una richiesta di Servizi di comunicazione all'interno di Postman. Per iniziare, fare clic sull'icona plus(+) accanto alla raccolta servizi di comunicazione:

Verrà creata una nuova scheda per la richiesta all'interno di Postman. Con la creazione è necessario configurarla. Verrà eseguita una richiesta con l'API Invia SMS, quindi assicurarsi di fare riferimento alla documentazione per questa API per assistenza. Configurare la richiesta di Postman.

Iniziare impostando il tipo di richiesta su POST e immettendo {{endpoint}}/sms?api-version=2021-03-07 nel campo URL della richiesta. Questo URL usa la variabile creata endpoint in precedenza per inviarla automaticamente alla risorsa di Servizi di comunicazione.

Selezionare ora la scheda Corpo della richiesta e quindi modificare il pulsante di opzione sotto "raw". A destra è presente un elenco a discesa che indica "Testo", modificarlo in JSON:

Verrà configurata la richiesta di invio e ricezione di informazioni in un formato JSON.

Nell'area di testo seguente è necessario immettere un corpo della richiesta nel formato seguente:

{
    "from":"<Your Azure Communication Services Telephone Number>",
    "message":"<The message you'd like to send>",
    "smsRecipients": [
        {
            "to":"<The number you'd like to send the message to>"
        }
    ]
}

Per il valore "from", è necessario ottenere un numero di telefono nel portale di Servizi di comunicazione di Azure come indicato in precedenza. Immetterlo senza spazi e anteporre il prefisso al codice paese. Ad esempio: +15555551234. Il tuo "messaggio" può essere quello che vuoi inviare, ma Hello from Azure Communication Services è un buon esempio. Il valore "to" deve essere un telefono a cui si ha accesso che può ricevere messaggi SMS. L'uso del proprio cellulare è una buona idea.

Dopo aver immesso, è necessario salvare questa richiesta nella raccolta di Servizi di comunicazione creata in precedenza. In questo modo si garantisce che selezioni le variabili e lo script di pre-richiesta creato in precedenza. A tale scopo, fare clic sul pulsante "Salva" in alto a destra nell'area della richiesta.

Verrà visualizzata una finestra di dialogo che chiede, cosa si vuole chiamare la richiesta e dove salvarla. È possibile denominare qualsiasi elemento desiderato, ma assicurarsi di selezionare la raccolta di Servizi di comunicazione nella metà inferiore della finestra di dialogo:

Invio di una richiesta

Ora che tutto è configurato, dovrebbe essere possibile inviare la richiesta e ricevere un messaggio SMS sul telefono. A tale scopo, verificare che la richiesta creata sia selezionata e quindi premere il pulsante "Invia" a destra:

Se tutto è andato bene, dovrebbe essere visualizzata la risposta di Servizi di comunicazione, che dovrebbe essere 202 Codice di stato:

Il telefono cellulare, proprietario del numero specificato nel valore "a", deve anche ricevere un messaggio SMS. È ora disponibile una configurazione funzionale di Postman in grado di comunicare con Servizi di comunicazione di Azure e inviare messaggi SMS.

Passaggi successivi

È anche possibile:

• Aggiungere una chat all'app
• Creare token di accesso utente
• Informazioni sull'architettura client e server
• Informazioni sull'autenticazione