Udostępnij przez

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

W tym samouczku skonfigurujesz Postman i użyjesz go, aby wysłać żądanie do usług Azure Communication Services za pomocą protokołu HTTP. Po zakończeniu tego samouczka, pomyślnie wyślesz wiadomość SMS, korzystając z usług komunikacyjnych i Postman. Następnie możesz użyć narzędzia Postman do eksplorowania innych interfejsów API w usługach komunikacyjnych.

Z tego samouczka dowiesz się, jak wykonywać następujące działania:

  • Pobierz narzędzie Postman.
  • Skonfiguruj narzędzie Postman do podpisywania żądań HTTP.
  • Wyślij żądanie do SMS API Communication Services w celu wysłania wiadomości.

Prerequisites

Pobieranie i instalowanie narzędzia Postman

Postman to aplikacja desktopowa, która może wykonywać żądania API względem dowolnego interfejsu API HTTP. Narzędzie Postman jest często używane do testowania i eksplorowania interfejsów API. W tym samouczku pobierzesz najnowszą wersję na komputery stacjonarne z witryny internetowej Postman. Narzędzie Postman ma wersje dla systemów Windows, Mac i Linux, więc pobierz wersję odpowiednią dla systemu operacyjnego.

Po zakończeniu pobierania otwórz aplikację. Na ekranie startowym zostanie wyświetlony monit o zalogowanie się lub utworzenie konta postman. Tworzenie konta jest opcjonalne i możesz go pominąć, wybierając pozycję Pomiń i przejdź do aplikacji. Utworzenie konta umożliwia zapisanie ustawień żądania interfejsu API w aplikacji Postman. Następnie możesz uzyskać dostęp do swoich żądań na innych komputerach.

Zrzut ekranu pokazujący ekran startowy Postman, gdzie można utworzyć konto lub przejść bezpośrednio do aplikacji.

Po utworzeniu konta lub pominięcia kroku zostanie wyświetlony ekran główny narzędzia Postman.

Tworzenie i konfigurowanie kolekcji Postman

Postman może organizować żądania na wiele sposobów. Na potrzeby tego samouczka utworzysz kolekcję Postman. Aby wykonać to zadanie, po lewej stronie aplikacji wybierz pozycję Kolekcje.

Zrzut ekranu przedstawiający główny ekran Postman z wyróżnioną kartą Kolekcje.

Wybierz pozycję Utwórz nową kolekcję , aby rozpocząć proces tworzenia kolekcji. Zostanie otwarta nowa karta w środkowym obszarze narzędzia Postman, w której nadasz kolekcji nazwę. W tym miejscu kolekcja nosi nazwę Azure Communication Services.

Zrzut ekranu przedstawiający narzędzie Postman z otwartą kolekcją usług Communication Services i wyróżnioną nazwą kolekcji.

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

Dodawanie zmiennych kolekcji

Aby obsługiwać uwierzytelnianie i ułatwić obsługę żądań, należy określić dwie zmienne kolekcji w nowo utworzonej kolekcji usług Komunikacyjnych. Te zmienne są dostępne dla wszystkich żądań w kolekcji. Aby rozpocząć tworzenie zmiennych, wybierz kartę Zmienne .

Zrzut ekranu przedstawiający narzędzie Postman z kartą Zmienne usług komunikacyjnych.

Na karcie Kolekcje utwórz dwie zmienne:

  • key: ta zmienna powinna być jednym z kluczy znajdujących się na stronie Usług Komunikacyjnych w portalu Azure. Przykładem jest oW...A==.
  • endpoint: ta zmienna powinna być twoim punktem końcowym usług komunikacyjnych ze strony Klucz. Upewnij się, że usuniesz ukośnik końcowy. Przykładem jest https://contoso.communication.azure.com.

Na karcie Zmienne wprowadź te wartości w kolumnie Wartość początkowa . Wybierz Zachowaj wszystko w prawym górnym rogu. Po poprawnym skonfigurowaniu okienko Postman powinno wyglądać mniej więcej tak jak na poniższej ilustracji.

Zrzut ekranu przedstawiający program Postman z poprawnie skonfigurowanymi zmiennymi kolekcji usług Communication Services.

Aby dowiedzieć się więcej na temat zmiennych, zobacz dokumentację narzędzia Postman.

Tworzenie skryptu prerequest

Następnym krokiem jest utworzenie skryptu prerequest w narzędziu Postman. Skrypt prerequest jest uruchamiany przed każdym żądaniem w narzędziu Postman. Może modyfikować lub zmieniać parametry żądania. Ten skrypt służy do podpisywania żądań HTTP, aby usługi Komunikacyjne mogły je autoryzować. Aby uzyskać więcej informacji na temat wymagań dotyczących podpisywania, zobacz nasz przewodnik dotyczący uwierzytelniania.

Tworzysz ten skrypt w kolekcji, tak aby był uruchamiany na dowolnym żądaniu w kolekcji. Aby wykonać ten krok, na karcie Kolekcje wybierz pozycję Skrypt wstępny żądania.

Zrzut ekranu przedstawiający Postmana z kartą Skryptu przed zapytaniem w Kolekcjach Usług Komunikacyjnych.

Teraz utworzysz skrypt prerequest, wprowadzając go w obszarze tekstowym. Ten krok może być łatwiejszy, jeśli napiszesz go w pełnym edytorze kodu, takim jak Visual Studio Code , zanim go wkleisz. Ten samouczek przeprowadzi Cię przez każdą część procesu skryptu. Przejdź do końca, jeśli chcesz skopiować skrypt do narzędzia Postman i rozpocząć pracę. Zacznijmy pisać skrypt.

Napisać skrypt prerequest

Pierwszym krokiem jest utworzenie ciągu uniwersalnego czasu koordynowanego (UTC) i dodanie go do nagłówka Date HTTP. Zapisz 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});

Najpierw zahaszuj treść żądania przy użyciu algorytmu SHA 256 i umieść go 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 trzeba ich instalować ani wymagać.

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

Użyj wcześniej określonej zmiennej punktu końcowego, aby określić wartość nagłówka HTTP Host. Nagłówek Host nie jest ustawiony przed zakończeniem przetwarzania 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://','');

Dzięki tym informacjom możesz teraz utworzyć ciąg, który podpiszesz dla żądania HTTP. Ciąg 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, by using various previously created values.
const stringToSign = pm.request.method + '\n' + url + '\n' + dateStr + ';' + hostStr + ';' + hashedBodyStr;

Na koniec podpiszesz ten ciąg przy użyciu klucza usług komunikacyjnych. Następnie dodaj ten klucz do żą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 prerequest

Końcowy skrypt prerequest 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 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
});

Wprowadź lub wklej ten końcowy skrypt w polu tekstowym na karcie Pre-request Script.

Zrzut ekranu przedstawiający narzędzie Postman z wprowadzonym skryptem predyskrywania kolekcji usług Communication Services.

Po jego wprowadzeniu wybierz Ctrl+S lub wybierz pozycję Zapisz , aby zapisać skrypt w kolekcji.

Zrzut ekranu przedstawiający przycisk Zapisz skrypt wstępnego żądania w narzędziu Postman.

Tworzenie żądania w narzędziu Postman

Teraz, gdy wszystko jest skonfigurowane, możesz utworzyć żądanie usług komunikacyjnych w narzędziu Postman. Aby rozpocząć, wybierz znak plus (+) obok kolekcji Usług komunikacyjnych.

Zrzut ekranu pokazujący znak plus (+) w Postman.

Utworzyłeś nową kartę dla swojego żądania w Postmanie, a teraz musisz ją skonfigurować. Wyślij żądanie do interfejsu API wysyłania wiadomości SMS, a następnie zapoznaj się z dokumentacją tego interfejsu API, aby uzyskać pomoc. Skonfigurujmy żądanie w programie Postman.

Aby rozpocząć, ustaw typ żądania na POST i wprowadź {{endpoint}}/sms?api-version=2021-03-07 w polu adres URL żądania. Ten adres URL używa wcześniej utworzonej zmiennej endpoint, aby automatycznie wysłać ją do zasobu Communication Services.

Zrzut ekranu przedstawiający żądanie Postman z typem ustawionym na POST i ustawionym poprawnie adresem URL.

Na karcie Treść żądania wybierz raw. Z listy rozwijanej po prawej stronie wybierz pozycję JSON.

Zrzut ekranu przedstawiający ustawianie treści żądania na nieprzetworzone i JSON.

Skonfigurowano żądanie wysyłania i odbierania informacji w formacie JSON.

W obszarze tekstowym wprowadź treść żądania 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>"
        }
    ]
}

Aby uzyskać from wartość, musisz uzyskać numer telefonu w portalu usług komunikacyjnych, jak wspomniano wcześniej. Wprowadź go bez spacji i prefiksu kodu kraju. Przykładem jest +15555551234. Może message to być dowolny element, który chcesz wysłać, ale Hello from Azure Communication Services jest dobrym przykładem. Wartość to powinna być numerem telefonu, do którego masz dostęp, aby można było otrzymywać wiadomości SMS. Korzystanie z własnego telefonu komórkowego jest dobrym pomysłem.

Zapisz to żądanie w utworzonej wcześniej kolekcji Usług komunikacyjnych. Ten krok gwarantuje, że pobiera zmienne i skrypt prerequest, który został wcześniej utworzony. Wybierz pozycję Zapisz w prawym górnym rogu obszaru żądania.

Zrzut ekranu przedstawiający przycisk Zapisz dla żądania Postman.

Zostanie wyświetlone okno dialogowe z pytaniem, jak chcesz nazwać żądanie i gdzie chcesz je zapisać. Możesz nazwać wszystko, co chcesz, ale upewnij się, że w dolnej połowie okna dialogowego wybierzesz kolekcję Usług komunikacyjnych.

Zrzut ekranu przedstawiający okno dialogowe Zapisywanie żądania Postman z wybraną kolekcją Usług komunikacyjnych.

Wysyłanie żądania

Teraz, gdy wszystko jest skonfigurowane, możesz wysłać żądanie i uzyskać wiadomość SMS na telefonie. Aby wykonać ten krok, upewnij się, że żądanie zostało wybrane, a następnie wybierz pozycję Wyślij.

Zrzut ekranu przedstawiający żądanie Postman z wyróżnionym przyciskiem Wyślij.

Jeśli wszystko poszło dobrze, zobaczysz odpowiedź z usługi Communication Services, która jest kodem stanu 202.

Zrzut ekranu przedstawiający żądanie postman, które zostało pomyślnie wysłane z kodem stanu 202.

Telefon komórkowy, którego numer podałeś w polu to, również otrzymał wiadomość SMS. Masz teraz funkcjonalną konfigurację narzędzia Postman, która może komunikować się z usługami Communication Services i wysyłać wiadomości SMS.

Treści powiązane

  • Last updated on