Udostępnij za pośrednictwem

Samouczek: podpisywanie i tworzenie żądań za pomocą narzędzia Postman

  • Artykuł

W tym samouczku skonfigurujemy usługę Postman i użyjemy narzędzia Postman, aby wysłać żądanie do usług Azure Communication Services przy użyciu protokołu HTTP. Po ukończeniu tego samouczka pomyślnie wyślesz wiadomość SMS przy użyciu usług komunikacyjnych i postman. Następnie będzie można używać narzędzia Postman do eksplorowania innych interfejsów API w usługach Azure Communication Services.

W tym samouczku będziemy:

  • Pobieranie narzędzia Postman
  • Konfigurowanie narzędzia Postman do podpisywania żądań HTTP
  • Wysłanie żądania względem interfejsu API sms usług komunikacyjnych w celu wysłania wiadomości.

Wymagania wstępne

  • Konto platformy Azure z aktywną subskrypcją. Aby uzyskać szczegółowe informacje, zobacz Tworzenie bezpłatnego konta. Bezpłatne konto zapewnia środki na korzystanie z platformy Azure w wysokości 200 USD, aby wypróbować dowolną kombinację usług.
  • Aktywny zasób usług komunikacyjnych i parametry połączenia. Dowiedz się, jak utworzyć zasób usług komunikacyjnych.
  • Numer telefonu usług Azure Communication Services, który może wysyłać wiadomości SMS, zobacz nasz numer telefonu, aby go uzyskać.

Pobieranie i instalowanie narzędzia Postman

Postman to aplikacja klasyczna, która może wysyłać żądania interfejsu API względem dowolnego interfejsu API HTTP. Jest on często używany do testowania i eksplorowania interfejsów API. Pobierzemy najnowszą wersję programu Desktop z witryny internetowej Postman. Narzędzie Postman ma wersje dla systemów Windows, Mac i Linux, więc pobierz wersję odpowiednią dla danego systemu operacyjnego. Po pobraniu otwórz aplikację. Zostanie wyświetlony ekran startowy z monitem o zalogowanie się lub utworzenie konta postman. Tworzenie konta jest opcjonalne i można go pominąć, klikając link "Pomiń i przejdź do aplikacji". Utworzenie konta spowoduje zapisanie ustawień żądania interfejsu API w aplikacji Postman, co umożliwi pobranie żądań na innych komputerach.

Ekran startowy narzędzia Postman przedstawiający możliwość utworzenia konta lub pominięcia i przejścia do aplikacji.

Po utworzeniu konta lub pominiętym utworzeniu konta powinno zostać wyświetlone główne okno narzędzia Postman.

Tworzenie i konfigurowanie kolekcji Postman

Narzędzie Postman może organizować żądania na wiele sposobów. Na potrzeby tego samouczka. Utworzymy kolekcję Postman. W tym celu wybierz przycisk kolekcji po lewej stronie aplikacji:

Główny ekran Narzędzia Postman z wyróżnioną kartą Kolekcje.

Po wybraniu kliknij pozycję "Utwórz nową kolekcję", aby rozpocząć proces tworzenia kolekcji. Nowa karta zostanie otwarta w środkowym obszarze narzędzia Postman. Nadaj kolekcji nazwę dowolną. W tym miejscu kolekcja nosi nazwę "Azure Communication Services":

Narzędzie Postman z otwartą kolekcją usług komunikacyjnych i wyróżnioną nazwą kolekcji.

Po utworzeniu i nazwie kolekcji możesz ją skonfigurować.

Dodawanie zmiennych kolekcji

Aby obsługiwać uwierzytelnianie i ułatwić żądania, będziemy określać dwie zmienne kolekcji w nowo utworzonej kolekcji usług komunikacyjnych. Te zmienne są dostępne dla wszystkich żądań w kolekcji usług Komunikacyjnych. Aby rozpocząć tworzenie zmiennych, odwiedź kartę Zmiennej kolekcji.

Postman z kartą Zmienne kolekcji usług komunikacyjnych.

Na karcie kolekcji utwórz dwie zmienne:

  • key — ta zmienna powinna być jednym z kluczy ze strony klucza usług Azure Communication Services w witrynie Azure Portal. Na przykład oW...A==.
  • endpoint — ta zmienna powinna być punktem końcowym usług Azure Communication Services ze strony klucza. Upewnij się, że usuniesz ukośnik końcowy. Na przykład https://contoso.communication.azure.com.

Wprowadź te wartości w kolumnie "Wartość początkowa" ekranu zmiennych. Po wprowadzeniu naciśnij przycisk "Utrń wszystko" tuż nad tabelą po prawej stronie. Po poprawnym skonfigurowaniu ekranu narzędzia Postman powinien wyglądać mniej więcej tak:

Program Postman ze zmiennymi kolekcji usług komunikacyjnych został poprawnie skonfigurowany.

Więcej informacji na temat zmiennych można znaleźć w dokumentacji narzędzia Postman.

Tworzenie skryptu przed żądaniem

Następnym krokiem jest utworzenie skryptu wstępnego żądania w programie Postman. Skrypt przed żądaniem to skrypt, który jest uruchamiany przed każdym żądaniem w narzędziu Postman i może modyfikować lub zmieniać parametry żądania w Twoim imieniu. Użyjemy tego polecenia, aby podpisać nasze żądania HTTP, aby mogły być autoryzowane przez usługi Azure Communication Services. Aby uzyskać więcej informacji na temat wymagań dotyczących podpisywania, zapoznaj się z naszym przewodnikiem dotyczącym uwierzytelniania.

Utworzymy ten skrypt w kolekcji, tak aby był uruchamiany na dowolnym żądaniu w kolekcji. Aby to zrobić, na karcie kolekcji kliknij kartę podrzędną "Skrypt wstępny".

Narzędzie Postman z wybraną kartą podrzędną skryptu kolekcji usług komunikacyjnych.

Na tej karcie podrzędnej możesz utworzyć skrypt wstępnego żądania, wprowadzając go w obszarze tekstowym poniżej. Może to być łatwiejsze do napisania w pełnym edytorze kodu, takim jak Visual Studio Code , przed wklejeniem go po zakończeniu. W tym samouczku przejdziemy przez każdą część skryptu. Możesz przejść do końca, jeśli chcesz po prostu skopiować go do postman i rozpocząć. Zacznijmy pisać skrypt.

Pisanie skryptu przed żądaniem

Pierwszą rzeczą, którą będziemy robić, jest utworzenie ciągu uniwersalnego czasu koordynowanego (UTC) i dodanie go do nagłówka HTTP "Date". Ten ciąg jest również przechowywany w zmiennej, aby użyć go później podczas podpisywania:

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

Następnie utworzymy skrót treści żądania przy użyciu algorytmu SHA 256 i umieścimy ją w nagłówku x-ms-content-sha256 . Narzędzie Postman zawiera niektóre standardowe biblioteki do tworzenia skrótów i podpisywania globalnie, więc nie musimy ich instalować ani wymagać:

// 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
});

Teraz użyjemy wcześniej określonej zmiennej punktu końcowego, aby rozpoznać wartość nagłówka hosta HTTP. Musimy to zrobić, ponieważ nagłówek hosta nie jest ustawiony do momentu przetworzenia tego skryptu:

// 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://','');

Po utworzeniu tych informacji możemy teraz utworzyć ciąg, który podpiszemy dla żądania HTTP, składa się z kilku wcześniej utworzonych wartości:

// 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;

Na koniec musimy podpisać ten ciąg przy użyciu klucza usług komunikacyjnych, a następnie dodać go do naszego żądania w nagłówku 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
});

Końcowy skrypt przed żądaniem

Końcowy skrypt przed żądaniem powinien wyglądać mniej więcej tak:

// 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
});

Wprowadź lub wklej ten końcowy skrypt w obszarze tekstowym na karcie Skrypt wstępny:

Postman z wprowadzonym skryptem przed żądaniem kolekcji usług Azure Communication Services.

Po wprowadzeniu naciśnij CTRL + S lub naciśnij przycisk zapisz, co spowoduje zapisanie skryptu w kolekcji.

Przycisk Zapisz skrypt wstępny narzędzia Postman.

Tworzenie żądania w narzędziu Postman

Teraz, gdy wszystko jest skonfigurowane, możemy utworzyć żądanie usług komunikacyjnych w programie Postman. Aby rozpocząć, kliknij ikonę plus(+) obok kolekcji usług komunikacyjnych:

Przycisk plus postmana.

Spowoduje to utworzenie nowej karty dla naszego żądania w programie Postman. Po utworzeniu musimy go skonfigurować. Wyślemy żądanie dotyczące interfejsu API wysyłania wiadomości SMS, dlatego zapoznaj się z dokumentacją tego interfejsu API, aby uzyskać pomoc. Skonfigurujmy żądanie narzędzia Postman.

Zacznij od ustawienia, typ żądania do POST i wprowadzenie {{endpoint}}/sms?api-version=2021-03-07 do pola adresu URL żądania. Ten adres URL używa wcześniej utworzonej endpoint zmiennej, aby automatycznie wysyłać ją do zasobu usług Communication Services.

Żądanie Postman z typem ustawionym na POST i ustawionym poprawnie adresem URL.

Teraz wybierz kartę Treść żądania, a następnie zmień przycisk radiowy poniżej na "nieprzetworzone". Po prawej stronie znajduje się lista rozwijana z napisem "Text", zmień ją na JSON:

Ustawianie treści żądania na nieprzetworzone i JSON

Spowoduje to skonfigurowanie żądania wysyłania i odbierania informacji w formacie JSON.

W poniższym obszarze tekstowym musisz wprowadzić treść żądania, powinna mieć następujący format:

{
    "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>"
        }
    ]
}

W przypadku wartości "from" należy uzyskać numer telefonu w portalu usług Azure Communication Services, jak wspomniano wcześniej. Wprowadź go bez spacji i prefiksu według kodu kraju. Na przykład: +15555551234. Twoja "wiadomość" może być dowolna, którą chcesz wysłać, ale Hello from Azure Communication Services jest dobrym przykładem. Wartość "do" powinna być telefonem, do którego masz dostęp, który może odbierać wiadomości SMS. Korzystanie z własnych urządzeń przenośnych jest dobrym pomysłem.

Po wprowadzeniu musimy zapisać to żądanie w kolekcji usług komunikacyjnych, która została wcześniej utworzona. Zapewni to, że pobiera zmienne i skrypt przed żądaniem, który wcześniej utworzyliśmy. Aby to zrobić, kliknij przycisk "Zapisz" w prawym górnym rogu obszaru żądania.

Przycisk zapisz dla żądania Postman.

Spowoduje to wyświetlenie okna dialogowego z pytaniem o to, co chcesz wywołać żądanie i gdzie chcesz go zapisać. Możesz nadać mu nazwę dowolnego elementu, ale upewnij się, że w dolnej połowie okna dialogowego wybierzesz kolekcję Usług komunikacyjnych:

Okno dialogowe zapisywania żądania postman z wybraną kolekcją Usług komunikacyjnych.

Wysyłanie żądania

Teraz, gdy wszystko jest skonfigurowane, powinno być możliwe wysłanie żądania i pobranie wiadomości SMS na telefonie. Aby to zrobić, upewnij się, że zostało wybrane utworzone żądanie, a następnie naciśnij przycisk "Wyślij" po prawej stronie:

Żądanie Postman z wyróżnionym przyciskiem Wyślij.

Jeśli wszystko poszło dobrze, powinna zostać wyświetlona odpowiedź z usługi Communication Services, która powinna mieć kod stanu 202:

Żądanie Postman wysłane pomyślnie z kodem stanu 202.

Telefon komórkowy, który jest właścicielem numeru podanego w wartości "do", powinien również otrzymać wiadomość SMS. Masz teraz funkcjonalną konfigurację narzędzia Postman, która może komunikować się z usługami Azure Communication Services i wysyłać wiadomości SMS.

Następne kroki

Zapoznaj się z interfejsamiAPI usług Azure Communication Services Przeczytaj więcej na temat uwierzytelnianiaDowiedz się więcej na temat narzędzia Postman

Możesz również chcieć: