Tutorial: Menandatangani dan membuat permintaan dengan Postman

Dalam tutorial ini, Anda menyiapkan dan menggunakan Postman untuk membuat permintaan terhadap Azure Communication Services dengan menggunakan HTTP. Pada akhir tutorial ini, Anda berhasil mengirim pesan Short Message Service (SMS) dengan menggunakan Communication Services dan Postman. Anda kemudian dapat menggunakan Postman untuk menjelajahi API lain di Communication Services.

Dalam tutorial ini, Anda mempelajari cara:

Unduh Postman.
Siapkan Postman untuk menandatangani permintaan HTTP.
Buat permintaan ke Communication Services SMS API untuk mengirim pesan.

Prerequisites

Akun Azure dengan langganan aktif. Jika Anda tidak memiliki langganan Azure, Anda dapat membuat akun secara gratis. Akun gratis memberi Anda kredit Azure $ 200 untuk mencoba kombinasi layanan apa pun.
Sumber daya Communication Services aktif dan string koneksi. Jika Anda tidak memiliki sumber daya, lihat Membuat sumber daya Layanan Komunikasi.
Nomor telepon Communication Services yang dapat mengirim pesan SMS. Untuk mendapatkan nomor telepon, lihat Mendapatkan nomor telepon.

Mengunduh dan menginstal Postman

Postman adalah aplikasi desktop yang mampu membuat permintaan API terhadap API HTTP apa pun. Postman umumnya digunakan untuk menguji dan menjelajahi API. Dalam tutorial ini, Anda mengunduh versi desktop terbaru dari situs web Postman. Postman memiliki versi untuk Windows, Mac, dan Linux, jadi unduh versi yang sesuai untuk sistem operasi Anda.

Setelah pengunduhan selesai, buka aplikasi. Layar mulai meminta Anda untuk masuk atau membuat akun Postman. Membuat akun bersifat opsional, dan Anda dapat melewatinya dengan memilih Lewati dan buka aplikasi. Membuat akun menyimpan pengaturan permintaan API Anda ke Postman. Anda kemudian dapat mengambil permintaan Anda pada komputer lain.

Cuplikan layar yang memperlihatkan layar mulai Postman tempat Anda dapat membuat akun atau langsung masuk ke aplikasi.

Setelah Anda membuat akun atau melewati langkah ini, Anda akan melihat layar utama Postman.

Membuat dan mengonfigurasi koleksi Postman

Postman dapat mengatur permintaan dengan berbagai cara. Untuk tujuan tutorial ini, Anda membuat koleksi Postman. Untuk melakukan tugas ini, di sisi kiri aplikasi, pilih Koleksi.

Cuplikan layar yang memperlihatkan layar utama Postman dengan tab Koleksi disorot.

Pilih Buat Koleksi baru untuk memulai proses pembuatan koleksi. Tab baru terbuka di area tengah Postman tempat Anda memberi nama koleksi. Di sini, koleksi diberi nama Azure Communication Services.

Cuplikan layar yang memperlihatkan Postman dengan koleksi Communication Services yang terbuka dan nama koleksi disorot.

Setelah membuat dan memberi nama koleksi, Anda siap untuk mengonfigurasinya.

Menambahkan variabel koleksi

Untuk menangani autentikasi dan mempermudah permintaan, Anda menentukan dua variabel koleksi dalam koleksi Communication Services yang baru dibuat. Variabel ini tersedia untuk semua permintaan dalam koleksi Anda. Untuk mulai membuat variabel, pilih tab Variabel .

Cuplikan layar yang memperlihatkan Postman dengan tab Variabel Communication Services.

Pada tab Koleksi , buat dua variabel:

kunci: Variabel ini harus menjadi salah satu kunci Anda dari halaman Kunci Communication Services Anda di portal Microsoft Azure. Contohnya adalah oW...A==.
titik akhir: Variabel ini harus menjadi titik akhir Communication Services Anda dari halaman Kunci . Pastikan Anda menghapus garis miring di akhir. Contohnya adalah https://contoso.communication.azure.com.

Pada tab Variabel , masukkan nilai ini di kolom Nilai Awal . Pilih Pertahankan Semua di sudut kanan atas. Saat dikonfigurasi dengan benar, panel Postman Anda akan terlihat seperti gambar berikut.

Cuplikan layar yang memperlihatkan Postman dengan variabel koleksi Communication Services disiapkan dengan benar.

Untuk mempelajari selengkapnya tentang variabel, lihat dokumentasi Postman.

Membuat skrip pendahuluan permintaan

Langkah selanjutnya adalah membuat skrip prapermintaan di Postman. Skrip prapermintaan berjalan sebelum setiap permintaan di Postman. Ini dapat memodifikasi atau mengubah parameter permintaan untuk Anda. Anda menggunakan skrip ini untuk menandatangani permintaan HTTP Anda sehingga Communication Services dapat mengotorisasinya. Untuk informasi selengkapnya tentang persyaratan penandatanganan, lihat panduan kami tentang autentikasi.

Anda membuat skrip ini dalam koleksi sehingga dijalankan pada setiap permintaan dalam koleksi. Untuk melakukan langkah ini, pada tab Koleksi , pilih Skrip pra-permintaan.

Cuplikan layar yang memperlihatkan Postman dengan tab Skrip Pra-permintaan untuk Koleksi Communication Services.

Sekarang Anda membuat skrip prapermintaan dengan memasukkannya ke dalam area teks. Langkah ini mungkin lebih mudah jika Anda menulisnya di editor kode lengkap seperti Visual Studio Code sebelum Anda menempelkannya. Tutorial ini membimbing Anda melalui setiap bagian dari proses skrip. Lewati ke akhir jika Anda ingin menyalin skrip ke Postman dan memulai. Mari mulai menulis skrip.

Menulis skrip pra-kueri

Langkah pertama adalah membuat string Waktu Universal Terkoordinasi (UTC) dan menambahkannya ke Date header HTTP. Simpan string ini dalam variabel untuk menggunakannya nanti saat Anda menandatangani.

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

Selanjutnya, hash isi permintaan dengan menggunakan SHA 256 dan letakkan di x-ms-content-sha256 header. Postman menyertakan beberapa pustaka standar untuk hashing dan penandatanganan secara global, sehingga Anda tidak perlu menginstalnya atau mewajibkannya.

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

Gunakan variabel titik akhir yang ditentukan sebelumnya untuk menentukan nilai untuk HTTP Host header. Header Host tidak akan diatur sampai skrip ini selesai diproses.

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

Dengan informasi ini, Anda sekarang dapat membuat string, yang Anda tanda tangani untuk permintaan HTTP. String terdiri dari beberapa nilai yang dibuat sebelumnya.

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

Terakhir, Anda menandatangani string ini dengan menggunakan kunci Communication Services Anda. Kemudian tambahkan kunci tersebut ke permintaan Anda di Authorization header.

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

Skrip prapermintaan akhir

Skrip prapermintaan akhir harus terlihat seperti contoh ini:

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

Masukkan atau tempel skrip akhir ini di area teks pada tab Skrip pra-permintaan .

Cuplikan layar yang memperlihatkan Postman dengan skrip prapermintaan koleksi Communication Services yang dimasukkan.

Setelah Anda memasukkannya, pilih Ctrl+S atau pilih Simpan untuk menyimpan skrip ke koleksi.

Cuplikan layar yang memperlihatkan tombol Simpan skrip pra-permintaan Postman.

Membuat permintaan di Postman

Setelah semuanya disiapkan, Anda siap untuk membuat permintaan Communication Services di Postman. Untuk memulai, pilih tanda plus (+) di samping koleksi Communication Services.

Cuplikan layar yang memperlihatkan tanda postman plus (+).

Anda membuat tab baru untuk permintaan Anda di Postman, dan sekarang Anda perlu mengonfigurasinya. Anda membuat permintaan terhadap SMS Send API, jadi pastikan untuk merujuk ke dokumentasi untuk API ini untuk mendapatkan bantuan. Mari kita konfigurasikan permintaan Postman.

Untuk memulai, atur jenis permintaan ke POST dan masukkan {{endpoint}}/sms?api-version=2021-03-07 di bidang URL permintaan. URL ini menggunakan variabel yang Anda buat endpoint sebelumnya untuk mengirimkannya secara otomatis ke sumber daya Communication Services Anda.

Cuplikan layar yang memperlihatkan permintaan Postman dengan jenis yang diatur ke POST dan URL diatur dengan benar.

Pada tab Body permintaan, pilih raw. Di daftar dropdown di sebelah kanan, pilih JSON.

Cuplikan layar yang memperlihatkan pengaturan isi permintaan ke mentah dan JSON.

Anda mengonfigurasi permintaan untuk mengirim dan menerima informasi dalam format JSON.

Di area teks, masukkan isi permintaan dalam format berikut:

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

Untuk nilai from, Anda perlu mendapatkan nomor telepon di portal Layanan Komunikasi, seperti yang telah disebutkan sebelumnya. Masukkan tanpa spasi dan awalan kode negara Anda. Contohnya adalah +15555551234. message Anda bisa menjadi apa pun yang ingin Anda kirim, tetapi Hello from Azure Communication Services adalah contoh yang baik. Nilainya to harus berupa telepon yang dapat Anda akses sehingga Anda dapat menerima pesan SMS. Menggunakan ponsel Anda sendiri adalah ide yang baik.

Simpan permintaan ini ke dalam kumpulan Communication Services yang sebelumnya Anda buat. Langkah ini memastikan bahwa proses ini mengambil variabel dan skrip prapermintaan yang sebelumnya Anda buat. Pilih Simpan di kanan atas area permintaan.

Cuplikan layar yang memperlihatkan tombol Simpan untuk permintaan Postman.

Dialog yang muncul menanyakan kepada Anda apa yang ingin Anda panggil permintaan dan di mana Anda ingin menyimpannya. Anda dapat menamainya apa pun yang Anda inginkan, tetapi memastikan bahwa Anda memilih koleksi Communication Services Anda di bagian bawah dialog.

Cuplikan layar yang menampilkan dialog Simpan Permintaan Postman dengan koleksi Communication Services yang dipilih.

Mengirim permintaan

Setelah semuanya disiapkan, Anda dapat mengirim permintaan dan mendapatkan pesan SMS di ponsel Anda. Untuk melakukan langkah ini, pastikan bahwa permintaan Anda dipilih lalu pilih Kirim.

Cuplikan layar yang memperlihatkan permintaan Postman dengan tombol Kirim disorot.

Jika semuanya berjalan dengan baik, Anda akan melihat respons dari Communication Services, yang merupakan kode status 202.

Cuplikan layar yang memperlihatkan permintaan Postman yang berhasil dikirim dengan kode status 202.

Ponsel yang memiliki nomor yang Anda berikan dalam to nilai juga menerima pesan SMS. Anda sekarang memiliki konfigurasi Postman fungsional yang dapat berbicara dengan Communication Services dan mengirim pesan SMS.

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2025-10-08