Esercitazione: Firmare ed effettuare richieste con Postman

In questa esercitazione verrà configurato e usato Postman per effettuare una richiesta per Servizi di comunicazione di Azure usando HTTP. Al termine di questa esercitazione, verrà inviato 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.

In questa esercitazione verrà illustrato quanto segue:

• Download di Postman
• Configurazione di Postman per la firma delle richieste HTTP
• Effettuare una richiesta all'API SMS di Servizi di comunicazione per inviare un messaggio.

Prerequisiti

• Un account Azure con una sottoscrizione attiva. Per informazioni dettagliate vedere Creare un account gratuito. L'account gratuito offre $ 200 in crediti 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 Servizi di comunicazione di Azure numero di telefono che può inviare messaggi SMS, vedi il nostro Ottenere un numero di telefono per ottenerlo.

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. La versione desktop più recente verrà scaricata 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, aprire l'applicazione. Verrà visualizzata una schermata start 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 passa all'app". La creazione di un account salverà le impostazioni della richiesta API in Postman, che può quindi consentire di raccogliere le richieste in altri computer.

Dopo aver creato un account o aver ignorato quello creato, verrà visualizzata 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 alla raccolta il nome desiderato. 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 della chiave del Servizi di comunicazione di Azure all'interno del 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. Una volta immesso, premere il pulsante "Persist 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 di pre-richiesta all'interno di Postman. Uno script di pre-richiesta è uno script che viene eseguito prima di ogni richiesta in Postman e può modificare o modificare i parametri della richiesta per conto dell'utente. Verrà usato per firmare le richieste HTTP in modo che possano essere autorizzate da Servizi di comunicazione di Azure. Per altre informazioni sui requisiti di firma, vedere la guida sull'autenticazione.

Questo script verrà creato all'interno della raccolta in modo che venga eseguito su qualsiasi richiesta all'interno della raccolta. A tale scopo, nella scheda raccolta fare clic sulla sotto-scheda "Pre-request Script".

In questa scheda secondaria è possibile creare uno script di pre-richiesta immettendolo nell'area di testo seguente. Potrebbe essere più semplice scrivere questo codice, all'interno di un editor di codice completo, ad esempio Visual Studio Code , prima di incollarlo al termine. In questa esercitazione verrà illustrata ogni parte dello script. È possibile passare alla fine se si vuole semplicemente copiarlo in Postman e iniziare. Iniziamo a scrivere lo script.

Scrittura dello script di pre-richiesta

La prima cosa che verrà eseguita consiste nel creare una stringa UTC (Coordinated Universal Time) e aggiungerla all'intestazione HTTP "Date". Questa stringa viene archiviata anche in una variabile per usarla in un secondo momento durante la 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});

Successivamente, si esegue l'hashing del corpo della richiesta usando SHA 256 e lo si inserisce 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, si userà la variabile endpoint specificata in precedenza per distinguere il valore per l'intestazione host HTTP. È necessario eseguire questa operazione perché l'intestazione Host non viene impostata fino a quando 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à firmata 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 avrà un aspetto 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:

Una volta immesso, premere CTRL+S o premere il pulsante Salva per 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 del segno più (+) accanto alla raccolta di Servizi di comunicazione:

Verrà creata una nuova scheda per la richiesta all'interno di Postman. Dopo averlo creato, è necessario configurarlo. Verrà inviata una richiesta all'API di invio 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 per l'invio e la 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 preceduto dal 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.

Una volta immessa, è necessario salvare questa richiesta nella raccolta di Servizi di comunicazione creata in precedenza. In questo modo si assicurerà che rilevi 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 vuoi chiamare la richiesta e dove vuoi 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 da Servizi di comunicazione, che dovrebbe essere 202 Codice di stato:

Il telefono cellulare, proprietario del numero specificato nel valore "a", dovrebbe anche aver ricevuto un messaggio SMS. È ora disponibile una configurazione funzionale di Postman che può comunicare con Servizi di comunicazione di Azure e inviare messaggi SMS.

Passaggi successivi

Esplorare Servizi di comunicazione di Azure APIAltre informazioni sull'autenticazioneAltre informazioni su Postman

È anche possibile:

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