Udostępnij za pośrednictwem

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

  • Artykuł

W tym samouczku skonfigurujemy program Postman i użyjemy go do wykonania żądania względem Azure Communication Services przy użyciu protokołu HTTP. Po ukończeniu tego samouczka pomyślnie wysłano wiadomość SMS przy użyciu usług Communication Services i Postman. Następnie będzie można użyć narzędzia Postman do eksplorowania innych interfejsów API w ramach Azure Communication Services.

W tym samouczku wykonamy następujące elementy:

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

Wymagania wstępne

  • Konto platformy Azure z aktywną subskrypcją. Aby uzyskać szczegółowe informacje, zobacz Tworzenie konta bezpłatnie. 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.
  • Azure Communication Services numer telefonu, 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 umożliwia wykonywanie żądań interfejsu API względem dowolnego interfejsu API HTTP. Jest on często używany do testowania i eksplorowania interfejsów API. Pobierzemy najnowszą wersję klasyczną z witryny internetowej Postmana. Aplikacja 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 prośbą o zalogowanie się lub utworzenie konta narzędzia Postman. Tworzenie konta jest opcjonalne i można je pominąć, klikając link "Pomiń i przejdź do aplikacji". Utworzenie konta spowoduje zapisanie ustawień żądania interfejsu API w programie Postman, co umożliwia następnie odbieranie żą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ęciu tworzenia konta powinno zostać wyświetlone okno główne narzędzia Postman.

Tworzenie i konfigurowanie kolekcji Postman

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":

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łużyć uwierzytelnianie i ułatwić obsługę żądań, będziemy określać dwie zmienne kolekcji w nowo utworzonej kolekcji usługi Communication Services. 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 Azure Communication Services w Azure Portal. Na przykład oW...A==.
  • endpoint — ta zmienna powinna być punktem końcowym Azure Communication Services ze strony klucza. Upewnij się, że usunięto 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 "Utrwali wszystko" tuż nad tabelą po prawej stronie. Po poprawnym skonfigurowaniu ekranu narzędzia Postman powinien wyglądać mniej więcej tak:

Postman ze zmiennymi kolekcji usług komunikacyjnych poprawnie skonfigurowanymi.

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 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 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 przed żądaniem".

Postman z skryptem wstępnego żądania kolekcji usług komunikacyjnych Sub-Tab wybrany.

Na tej karcie podrzędnej możesz utworzyć skrypt wstępnego żądania, wprowadzając go do poniższego obszaru tekstowego. Łatwiej jest to napisać 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 narzędzia Postman i rozpocząć pracę. 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". Przechowujemy również ten ciąg 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ć ich:

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

Ostateczny skrypt przed żądaniem

Ostateczny 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 przed żądaniem:

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

Po wprowadzeniu naciśnij klawisze CTRL + S lub naciśnij przycisk zapisywania, który spowoduje zapisanie skryptu w kolekcji.

Przycisk Zapisz skrypt przed żądaniem 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 do interfejsu API wysyłania wiadomości SMS, więc 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 naszej wcześniej utworzonej endpoint zmiennej do automatycznego wysyłania jej do zasobu usług Communication Services.

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

Teraz wybierz kartę Treść żądania, a następnie zmień przycisk radiowy poniżej na "raw". 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 być w następującym formacie:

{
    "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 "od" musisz uzyskać numer telefonu w portalu Azure Communication Services, jak wspomniano wcześniej. Wprowadź go bez spacji i prefiksu według kodu kraju. Na przykład: +15555551234. "Wiadomość" może być niezależnie od tego, co 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 utworzony wcześniej. 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, co chcesz wywołać żądanie i gdzie chcesz go zapisać. Możesz nazwać wszystko, co chcesz, ale upewnij się, że w dolnej połowie okna dialogowego wybierzesz kolekcję Usług komunikacyjnych:

Okno dialogowe Zapisywanie żą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 utworzono żądanie jest zaznaczone, 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 Azure Communication Services i wysyłać wiadomości SMS.

Następne kroki

Zapoznaj się z interfejsami API Azure Communication ServicesDowiedz się więcej o uwierzytelnianiuDowiedz się więcej o usłudze Postman

Możesz również chcieć: