Nota
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare ad accedere o modificare le directory.
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare a modificare le directory.
In questa esercitazione si configura e si usa Postman per effettuare una richiesta a Servizi di comunicazione di Azure usando HTTP. Al termine di questa esercitazione, si invia un messaggio SMS (Short Message Service) usando Servizi di comunicazione e Postman. È quindi possibile usare Postman per esplorare altre API in Servizi di comunicazione.
In questa esercitazione si apprenderà come:
- Scarica Postman.
- Configurare Postman per firmare le richieste HTTP.
- Effettuare una richiesta all'API SMS dei Servizi di Comunicazione per inviare un messaggio.
Prerequisites
- Un account Azure con una sottoscrizione attiva. Se non si ha una sottoscrizione di Azure, è possibile creare un account gratuitamente. L'account gratuito offre 200$ in crediti Azure per provare qualsiasi combinazione di servizi.
- Una risorsa di Servizi di comunicazione attiva e una stringa di connessione. Se non si ha una risorsa, vedere Creare una risorsa di Servizi di comunicazione.
- Numero di telefono di Servizi di comunicazione che può inviare messaggi SMS. Per ottenere un numero di telefono, vedere Ottenere un numero di telefono.
Scaricare e installare Postman
Postman è un'applicazione desktop in grado di effettuare richieste API su qualsiasi API HTTP. Postman viene comunemente usato per testare ed esplorare le API. In questa esercitazione si scarica la versione desktop più recente dal sito Web Postman. Postman ha versioni per Windows, Mac e Linux, quindi scaricare la versione appropriata per il sistema operativo.
Al termine del download, aprire l'applicazione. La schermata start chiede di accedere o creare un account Postman. La creazione di un account è facoltativa ed è possibile ignorarla selezionando Ignora e passa all'app. La creazione di un account salva le impostazioni della richiesta API in Postman. È quindi possibile raccogliere le richieste su altri computer.
Dopo aver creato un account o aver ignorato il passaggio, viene visualizzata la schermata principale di Postman.
Creare e configurare una raccolta Postman
Postman può organizzare le richieste in molti modi. Ai fini di questa esercitazione, si crea una raccolta Postman. Per eseguire questa attività, sul lato sinistro dell'applicazione selezionare Raccolte.
Selezionare Crea una nuova raccolta per avviare il processo di creazione di una raccolta. Viene visualizzata una nuova scheda nell'area centrale di Postman in cui si assegna un nome alla raccolta. In questo caso, la raccolta è denominata Servizi di comunicazione di Azure.
Dopo aver creato e assegnare un nome alla raccolta, è possibile configurarla.
Aggiungere variabili di raccolta
Per gestire l'autenticazione e semplificare le richieste, specificare due variabili di raccolta all'interno della raccolta di Servizi di comunicazione appena creata. Queste variabili sono disponibili per tutte le richieste nella raccolta. Per iniziare a creare variabili, selezionare la scheda Variabili .
Nella scheda Raccolte creare due variabili:
-
key: questa variabile deve essere una delle chiavi della pagina Chiave di Servizi di comunicazione nel portale di Azure. Un esempio è
oW...A==. -
endpoint: questa variabile deve essere gli endpoint di Servizi di comunicazione dalla pagina Chiave. Assicurarsi di rimuovere la barra finale. Un esempio è
https://contoso.communication.azure.com.
Nella scheda Variabili immettere questi valori nella colonna Valore iniziale . Selezionare Mantieni tutto nell'angolo superiore destro. Se configurata correttamente, il riquadro Postman dovrebbe essere simile all'immagine seguente.
Per altre informazioni sulle variabili, vedere la documentazione di Postman.
Creare uno script di prerequisito
Il passaggio successivo consiste nel creare uno script di pre-richiesta in Postman. Uno script di pre-richiesta viene eseguito prima di ogni richiesta in Postman. Può modificare o alterare i parametri della richiesta. Questo script viene usato per firmare le richieste HTTP in modo che Servizi di comunicazione possa autorizzarle. Per altre informazioni sui requisiti di firma, vedere la guida sull'autenticazione.
Questo script viene creato nella raccolta in modo che venga eseguito su qualsiasi richiesta nella raccolta. A tale scopo, nella scheda Raccolte selezionare Script pre-richiesta.
Ora si crea uno script di richiesta preliminare immettendolo nell'area di testo. Questo passaggio potrebbe essere più semplice se lo si scrive in un editor di codice completo come Visual Studio Code prima di incollarlo. Questa esercitazione illustra ogni parte del processo di scripting. Vai alla fine se vuoi copiare lo script in Postman e cominciare. Iniziamo a scrivere lo script.
Scrivere lo script di pre-richiesta
Il primo passaggio consiste nel creare una stringa UTC (Coordinated Universal Time) e aggiungerla all'intestazione Date HTTP. Archiviare questa stringa in una variabile per usarla in un secondo momento 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});
Eseguire quindi l'hashing 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 by 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
});
Usare la variabile di endpoint specificata in precedenza per determinare il valore per l'intestazione Host HTTP. L'intestazione Host viene impostata solo dopo che questo script è stato elaborato.
// 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, è ora possibile creare la stringa da firmare per la richiesta HTTP. La stringa è 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, by using various previously created values.
const stringToSign = pm.request.method + '\n' + url + '\n' + dateStr + ';' + hostStr + ';' + hashedBodyStr;
Infine, si firma questa stringa usando la chiave di Servizi di comunicazione. Aggiungere quindi tale chiave 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 all'esempio 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 by 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, by 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 della scheda Pre-request Script.
Dopo averlo immesso, selezionare CTRL+S o selezionare Salva per salvare lo script nella raccolta.
Creare una richiesta in Postman
Ora che tutto è configurato, è possibile creare una richiesta di Servizi di comunicazione in Postman. Per iniziare, selezionare il segno più (+) accanto alla raccolta servizi di comunicazione.
Screenshot che mostra il simbolo del più (+) nell'applicazione Postman.
È stata creata una nuova scheda per la richiesta in Postman e ora è necessario configurarla. Si effettua una richiesta per l'API di invio SMS, quindi assicurarsi di fare riferimento alla documentazione per questa API per assistenza. Configuriamo la richiesta Postman.
Per iniziare, impostare il tipo di richiesta su POST e immettere {{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.
Nella scheda Corpo della richiesta selezionare raw. Nell'elenco a discesa a destra selezionare JSON.
È stata configurata la richiesta per inviare e ricevere informazioni in un formato JSON.
Nell'area di testo 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 from valore, è necessario ottenere un numero di telefono nel portale di Servizi di comunicazione, come indicato in precedenza. Immettilo senza spazi e con il prefisso del tuo codice paese. Un esempio è +15555551234. Il tuo message può essere quello che vuoi inviare, ma Hello from Azure Communication Services è un buon esempio. Il to valore deve essere un telefono a cui si ha accesso in modo da poter ricevere messaggi SMS. L'uso del proprio telefono cellulare è una buona idea.
Salvare questa richiesta nella raccolta servizi di comunicazione creata in precedenza. Questo passaggio garantisce che rilevi le variabili e lo script di pre-richiesta creati in precedenza. Selezionare Salva in alto a destra nell'area della richiesta.
La finestra di dialogo visualizzata chiede cosa si desidera chiamare la richiesta e dove salvarla. È possibile denominarlo qualsiasi elemento desiderato, ma assicurarsi di selezionare la raccolta di Servizi di comunicazione nella metà inferiore della finestra di dialogo.
Inviare una richiesta
Ora che tutto è configurato, è possibile inviare la richiesta e ricevere un messaggio SMS sul telefono. A tale scopo, assicurarsi che la richiesta sia selezionata e quindi selezionare Invia.
Se tutto è andato bene, viene visualizzata la risposta di Servizi di comunicazione, ovvero un codice di stato 202.
Il telefono cellulare proprietario del numero specificato nel to valore ha ricevuto anche un messaggio SMS. È ora disponibile una configurazione funzionale di Postman che può comunicare con Servizi di comunicazione e inviare messaggi SMS.