Cara menggunakan Postman untuk mengirim permintaan ke API Azure Digital Twins

  • Artikel
  • 11 menit untuk membaca

Postman adalah alat pengujian REST yang menyediakan fungsi permintaan HTTP utama di GUI berbasis desktop dan plugin. Anda dapat menggunakannya untuk membuat permintaan HTTP dan mengirimkannya ke REST API Azure Digital Twins.

Artikel ini menjelaskan cara mengonfigurasikan klien Postman REST untuk berinteraksi dengan API Azure Digital Twins, melalui langkah-langkah berikut:

  1. Gunakan Azure CLI untuk mendapatkan token pembawa yang akan Anda gunakan untuk membuat permintaan API di Postman.
  2. Siapkan koleksi Postman dan konfigurasikan klien Postman REST untuk menggunakan token pembawa Anda untuk mengautentikasi. Saat menyiapkan koleksi, Anda dapat memilih salah satu opsi ini:
    1. Impor kumpulan permintaan API Azure Digital Twins yang telah dibuat sebelumnya.
    2. Buat kumpulan Anda sendiri dari awal.
  3. Tambahkan permintaan ke kumpulan Anda yang dikonfigurasi dan kirimkan ke API Azure Digital Twins.

Azure Digital Twins memiliki dua set API yang dapat Anda kerjakan: pesawat data dansarana kontrol. Untuk selengkapnya tentang perbedaan antara kumpulan API ini, lihat API dan SDK Azure Digital Twins. Artikel ini berisi informasi untuk kedua set API.

Prasyarat

Untuk melanjutkan penggunaan Postman untuk mengakses API Azure Digital Twins, Anda perlu menyiapkan instans Azure Digital Twins dan mengunduh Postman. Bagian lain ini memandu Anda melalui langkah-langkah ini.

Siapkan Instans Azure Digital Twins

Untuk bekerja dengan Azure Digital Twins dalam artikel ini, Anda memerlukan instans Azure Digital Twins dan izin yang diperlukan untuk menggunakannya. Jika Anda sudah menyiapkan instans Azure Digital Twins, Anda dapat menggunakan instans tersebut dan melompat ke bagian berikutnya.

Jika tidak, ikuti instruksi dalam Menyiapkan instans dan autentikasi. Instruksi berisi informasi untuk membantu Anda memverifikasi bahwa Anda telah menyelesaikan setiap langkah dengan sukses.

Setelah Menyiapkan instans, catat nilai berikut. Anda akan memerlukan nilai-nilai ini untuk menyambungkan ke instans nanti:

Mengunduh Postman

Selanjutnya, unduh klien Postman versi desktop.

Dapatkan token pembawa

Setelah menyiapkan Postman dan instans Azure Digital Twins, Anda harus mendapatkan token pembawa yang dapat digunakan oleh Postman untuk mengotorisasi terhadap API Azure Digital Twins.

Ada beberapa cara yang mungkin untuk mendapatkan token ini. Artikel ini menggunakan Azure CLIuntuk masuk ke akun Azure Anda dan mendapatkan token seperti itu.

Jika Anda memiliki Azure CLI yang terpasang secara lokal, Anda dapat memulai prompt perintah pada komputer Anda untuk menjalankan perintah berikut. Jika tidak, Anda dapat membuka jendela Azure Cloud Shell di browser Anda dan menjalankan perintah di sana.

  1. Pertama, pastikan Anda masuk ke Azure dengan info masuk yang sesuai, dengan menjalankan perintah ini:

    az login

  2. Selanjutnya, gunakan perintahaz account get-access-token untuk mendapatkan token pembawa dengan akses ke layanan Azure Digital Twins. Dalam perintah ini, Anda akan meneruskan ID sumber daya untuk titik akhir layanan Azure Digital Twins, untuk mendapatkan token akses yang dapat mengakses sumber daya Azure Digital Twins.

    Konteks yang diperlukan untuk token bergantung pada kumpulan API mana yang Anda gunakan, jadi gunakan tab di bawah ini untuk memilih antara pesawat data dan APIsarana kontrol.

    Untuk mendapatkan token yang digunakan dengan API pesawat data, gunakan nilai statis berikut untuk konteks token: 0b07f429-9f4b-4714-9392-cc5e8e80c8b0. Ini adalah ID sumber daya untuk titik akhir layanan Azure Digital Twins.

    az account get-access-token --resource 0b07f429-9f4b-4714-9392-cc5e8e80c8b0

    Catatan

    Jika Anda perlu mengakses instans Azure Digital Twins menggunakan perwakilan layanan atau akun pengguna milik penyewa Azure Active Directory yang berbeda dari instans, Anda harus meminta token dari penyewa “rumah” instans Azure Digital Twins. Untuk informasi selengkapnya tentang proses ini, lihat Menulis kode autentikasi aplikasi.

  3. Salin nilai accessToken hasilnya, dan simpan untuk digunakan di bagian berikutnya. Ini adalah nilai token Anda yang akan Anda berikan kepada Postman untuk mengotorisasi permintaan Anda.

    Cuplikan layar konsol yang menunjukkan hasil perintah get-access-token akun az. Bidang accessToken dan nilai sampelnya disorot.

Tip

Token ini berlaku setidaknya selama lima menit dan maksimal 60 menit. Jika Anda kehabisan waktu yang dialokasikan untuk token saat ini, Anda dapat mengulangi langkah-langkah di bagian ini untuk mendapatkan yang baru.

Selanjutnya, Anda akan menyiapkan Postman untuk menggunakan token ini untuk membuat permintaan API ke Azure Digital Twins.

Tentang koleksi Postman

Permintaan di Postman disimpan dalam koleksi (grup permintaan). Saat membuat koleksi untuk mengelompokkan permintaan, Anda dapat menerapkan pengaturan umum ke banyak permintaan sekaligus. Ini dapat sangat menyederhanakan otorisasi jika Anda berencana untuk membuat lebih dari satu permintaan terhadap API Azure Digital Twins, karena Anda hanya perlu mengonfigurasi detail ini sekali untuk seluruh koleksi.

Saat bekerja dengan Azure Digital Twins, Anda bisa memulai dengan mengimpor koleksi bawaan semua permintaan Azure Digital Twins. Anda mungkin ingin melakukan ini jika Anda menjelajahi API dan ingin menyiapkan proyek dengan cepat dengan contoh permintaan.

Atau, Anda juga dapat memilih untuk memulai dari awal, dengan membuat koleksi kosong Anda sendiri dan mengisinya dengan permintaan individu yang hanya memanggil API yang Anda butuhkan.

Bagian berikut menjelaskan kedua proses ini. Artikel lainnya berlangsung di aplikasi Postman lokal Anda, jadi lanjutkan dan buka aplikasi Postman di komputer Anda sekarang.

Mengimpor koleksi API Azure Digital Twins

Cara cepat memulai Azure Digital Twins di Postman adalah dengan mengimpor koleksi permintaan bawaan untuk API Azure Digital Twins.

Unduh file koleksi

Langkah pertama dalam mengimpor set API adalah mengunduh koleksi. Pilih tab di bawah ini untuk pilihan pesawat data atau sarana kontrol untuk melihat opsi pengumpulan bawaan.

Saat ini ada dua koleksi pesawat data Azure Digital Twins yang tersedia untuk Anda pilih:

  • Koleksi Azure Digital Twins Postman: Koleksi ini memberikan pengalaman memulai yang sederhana untuk Azure Digital Twins di Postman. Permintaan menyertakan data sampel, sehingga Anda dapat menjalankannya dengan pengeditan minimal yang diperlukan. Pilih koleksi ini jika Anda menginginkan serangkaian permintaan API utama yang dapat dicerna yang berisi informasi sampel.
    • Untuk menemukan koleksi, navigasikan ke tautan repositori dan buka file bernamapostman_collection.jspada.
  • Swagger sarana data Azure Digital Twins: Repositori ini berisi file Swagger lengkap untuk set API Azure Digital Twins, yang dapat diunduh dan diimpor ke Postman sebagai koleksi. Ini akan memberikan kumpulan lengkap setiap permintaan API, tetapi dengan badan data kosong, bukan data sampel. Pilih koleksi ini jika Anda ingin memiliki akses ke setiap panggilan API dan isi semua data sendiri. Anda juga harus menggunakan koleksi ini jika Anda memerlukan versi API tertentu (seperti yang mendukung fitur pratinjau).
    • Untuk menemukan koleksi, navigasikan ke tautan repositori dan pilih folder untuk versi spesifikasi pilihan Anda. Dari sini, buka file bernama digitaltwins.jspada.

Berikut ini cara mengunduh koleksi pilihan Anda ke mesin Anda sehingga Anda dapat mengimpornya ke Postman.

  1. Gunakan tautan di atas untuk membuka file koleksi di GitHub di browser Anda.
  2. Pilih tombol Raw untuk membuka teks mentah file. Cuplikan layar pesawat data digitaltwins.jspada file di GitHub. Ada sorotan di sekitar tombol Raw.
  3. Salin teks dari jendela, dan tempel ke file baru di mesin Anda.
  4. Simpan file dengan ekstensi .json (nama file bisa apa saja yang Anda inginkan, selama Anda dapat mengingatnya untuk menemukan file nanti).

Mengimpor koleksi

Selanjutnya, impor koleksi ke Postman.

  1. Dari jendela Postman utama, pilih tombol Impor. Cuplikan layar jendela Postman yang baru dibuka. Tombol 'Impor' disorot.

  2. Di jendela Impor yang mengikuti, pilih Unggah File dan navigasikan ke file koleksi di komputer yang Anda buat sebelumnya. Pilih Buka.

  3. Pilih tombol Impor untuk mengonfirmasi.

    Cuplikan layar jendela 'Impor' Postman, memperlihatkan file untuk diimpor sebagai koleksi dan tombol Impor.

Koleksi yang baru diimpor sekarang dapat dilihat dari tampilan Postman utama Anda, di tab Koleksi.

Cuplikan layar jendela Postman utama. Koleksi yang baru diimpor disorot di tab 'Koleksi'.

Selanjutnya, lanjutkan ke bagian berikutnya untuk menambahkan token pembawa ke koleksi untuk otorisasi dan menghubungkannya ke instans kembar Azure Digital Anda.

Konfigurasikan otorisasi

Selanjutnya, edit koleksi yang telah Anda buat untuk mengonfigurasikan beberapa detail akses. Sorot koleksi yang telah Anda buat dan pilih ikon Tampilkan tindakan lainnya untuk membuka menu. Pilih Edit.

Cuplikan Layar Postman. Ikon 'Lihat tindakan lainnya' untuk koleksi yang diimpor disorot, dan 'Edit' disorot dalam opsi.

Ikuti langkah-langkah ini untuk menambahkan token pembawa ke koleksi untuk otorisasi. Di sinilah Anda akan menggunakannilai tokenyang Anda kumpulkan di bagian Dapatkan token pembawa untuk menggunakannya untuk semua permintaan API di koleksi Anda.

  1. Dalam dialog edit untuk koleksi Anda, pastikan Anda berada di tabOtorisasi.

    Cuplikan layar dialog edit koleksi yang diimpor di Postman, memperlihatkan tab 'Otorisasi'.

  2. Atur Jenis ke OAuth 2.0, tempelkan token akses Anda ke dalam kotak Token Akses, dan pilih Simpan.

    Cuplikan layar dialog edit Postman untuk koleksi yang diimpor, pada tab 'Otorisasi'. Jenisnya adalah 'OAuth 2.0', dan kotak Token Akses disorot.

Konfigurasi tambahan

Jika Anda membuat pengumpulan pesawat data, bantu koleksi tersambung dengan mudah ke sumber daya Azure Digital Twins Anda dengan mengatur beberapavariabel yang disediakan dengan koleksi. Ketika banyak permintaan dalam koleksi memerlukan nilai yang sama (seperti nama host instans Azure Digital Twins Anda), Anda dapat menyimpan nilai dalam variabel yang berlaku untuk setiap permintaan dalam koleksi. Kedua koleksi yang dapat diunduh untuk Azure Digital Twins dilengkapi dengan variabel yang telah dibuat sebelumnya yang dapat Anda atur di tingkat koleksi.

  1. Masih dalam dialog edit untuk koleksi Anda, pindah ke tabVariabel.

  2. Gunakan nama host instans Anda dari bagian Prasyarat untuk mengatur bidang CURRENT VALUE dari variabel yang relevan. Pilih Simpan.

    Cuplikan layar dialog edit koleksi yang diimpor di Postman, memperlihatkan tab 'Variabel'. Bidang 'CURRENT VALUE' disorot.

  3. Jika koleksi Anda memiliki variabel tambahan, isi dan simpan nilai tersebut juga.

Setelah selesai dengan langkah-langkah di atas, Anda selesai mengonfigurasikan koleksi. Anda bisa menutup tab pengeditan untuk koleksi jika mau.

Jelajahi permintaan

Selanjutnya, jelajahi permintaan di dalam koleksi Azure Digital Twins API. Anda dapat memperluas koleksi untuk melihat permintaan yang telah dibuat sebelumnya (diurutkan menurut kategori operasi).

Permintaan yang berbeda memerlukan informasi yang berbeda tentang instans Anda dan datanya. Untuk melihat semua informasi yang diperlukan untuk membuat permintaan tertentu, cari detail permintaan di dokumentasi referensi Azure Digital Twins REST API.

Anda dapat mengedit detail permintaan di koleksi Postman menggunakan langkah-langkah berikut:

  1. Pilih dari daftar untuk menarik detail yang dapat diedit.

  2. Isi nilai untuk variabel yang tercantum di tab Params di bawah Variabel Jalur.

    Cuplikan layar Postman. Koleksi diperluas untuk menampilkan permintaan. Bagian 'Variabel Jalur' disorot dalam detail permintaan.

  3. Berikan detail Header atau Body yang diperlukan di tab masing-masing.

Setelah semua detail yang diperlukan disediakan, Anda dapat menjalankan permintaan dengan tombol Kirim.

Anda juga dapat menambahkan permintaan Anda sendiri ke koleksi, menggunakan proses yang dijelaskan di bagian Tambahkan permintaan individudi bawah ini.

Buat koleksi Anda sendiri

Alih-alih mengimpor koleksi yang ada dari semua API Azure Digital Twins, Anda juga dapat membuat koleksi Anda sendiri dari awal. Anda kemudian dapat mengisinya dengan permintaan individu menggunakan dokumentasi referensiAzure Digital Twins REST API.

Buat koleksi Postman

  1. Untuk membuat koleksi, pilih tombol Baru di jendela postman utama.

    Cuplikan layar jendela Postman utama. Tombol 'Baru' disorot.

    Pilih jenis Koleksi.

    Cuplikan layar dialog 'Buat Baru' di Postman. Opsi 'Koleksi' disorot.

  2. Ini akan membuka tab untuk mengisi detail koleksi baru. Pilih ikon Edit di samping nama default koleksi (Koleksi Baru) untuk menggantinya dengan pilihan nama Anda sendiri.

    Cuplikan layar dialog edit koleksi baru di Postman. Ikon Edit di samping nama 'Koleksi Baru' disorot.

Selanjutnya, lanjutkan ke bagian berikutnya untuk menambahkan token pembawa ke koleksi untuk otorisasi.

Konfigurasikan otorisasi

Ikuti langkah-langkah ini untuk menambahkan token pembawa ke koleksi untuk otorisasi. Di sinilah Anda akan menggunakannilai tokenyang Anda kumpulkan di bagian Dapatkan token pembawa untuk menggunakannya untuk semua permintaan API di koleksi Anda.

  1. Masih dalam dialog edit untuk koleksi baru Anda, pindah ke tab Otorisasi.

    Cuplikan layar dialog edit koleksi yang diimpor di Postman, memperlihatkan tab 'Otorisasi'.

  2. Atur Jenis ke OAuth 2.0, tempelkan token akses Anda ke dalam kotak Token Akses, dan pilih Simpan.

    Cuplikan layar dialog edit Postman untuk koleksi yang diimpor, pada tab 'Otorisasi'. Jenisnya adalah 'OAuth 2.0', dan kotak Token Akses disorot.

Setelah selesai dengan langkah-langkah di atas, Anda selesai mengonfigurasikan koleksi. Anda bisa menutup tab pengeditan untuk koleksi jika mau.

Koleksi yang baru diimpor sekarang dapat dilihat dari tampilan Postman utama Anda, di tab Koleksi.

Cuplikan layar jendela Postman utama. Koleksi yang baru diimpor disorot di tab 'Koleksi'.

Menambahkan permintaan individu

Setelah koleksi Anda disiapkan, Anda dapat menambahkan permintaan Anda sendiri ke API Azure Digital Twin.

  1. Untuk membuat permintaan, gunakan lagi tombol Baru.

    Cuplikan layar jendela Postman utama. Tombol 'Baru' disorot.

    Pilih jenis Permintaan.

    Cuplikan layar dialog 'Buat Baru' di Postman. Opsi 'Koleksi' disorot.

  2. Tindakan ini membuka jendela SAVE REQUEST, tempat Anda dapat memasukkan nama untuk permintaan Anda, memberikan deskripsi opsional, dan memilih koleksi tempatnya menjadi bagiannya. Isi detail dan simpan permintaan ke koleksi yang Anda buat sebelumnya.

    Cuplikan layar jendela 'Simpan permintaan' di Postman memperlihatkan bidang yang dijelaskan. Tombol 'Simpan ke koleksi Azure Digital Twins' disorot.

Sekarang Anda dapat melihat permintaan Anda di bawah koleksi, dan memilihnya untuk menarik detail yang dapat diedit.

Cuplikan layar Postman. Koleksi Azure Digital Twins diperluas untuk menampilkan detail permintaan.

Mengatur detail permintaan

Untuk membuat permintaan Postman ke salah satu API Azure Digital Twins, Anda memerlukan URL API dan informasi tentang detail apa yang diperlukan. Anda dapat menemukan informasi ini di dokumentasi referensiAzure Digital Twins REST API.

Untuk melanjutkan dengan contoh kueri, artikel ini akan menggunakan API Kueri (dan dokumentasi referensinya)untuk meng-kueri semua kembar digital dalam suatu instans.

  1. Dapatkan URL permintaan dan ketik dari dokumentasi referensi. Untuk API Kueri, saat ini adalah POSThttps://digitaltwins-host-name/query?api-version=2020-10-31.

  2. Di Postman, atur jenis permintaan dan masukkan URL permintaan, mengisi tempat penampung di URL sebagaimana diperlukan. Di sinilah Anda akan menggunakan nama host instans Anda dari Bagian prasyarat.

    Cuplikan layar detail permintaan baru di Postman. URL kueri dari dokumentasi referensi telah diisi ke dalam kotak URL permintaan.

  3. Periksa apakah parameter yang ditampilkan untuk permintaan di tab Paramcocok dengan yang dijelaskan dalam dokumentasi referensi. Untuk permintaan ini di Postman, api-version parameter secara otomatis diisi ketika URL permintaan dimasukkan pada langkah sebelumnya. Untuk Kuery API, ini adalah satu-satunya parameter yang diperlukan, jadi langkah ini dilakukan.

  4. Di tab Otorisasi, atur Jenis ke Warisi otorisasi dari induk. Ini menunjukkan bahwa permintaan ini akan menggunakan otorisasi yang Anda siapkan sebelumnya untuk seluruh koleksi.

  5. Periksa apakah header yang ditampilkan untuk permintaan di tab Headercocok dengan yang dijelaskan dalam dokumentasi referensi. Untuk permintaan ini, beberapa header telah diisi secara otomatis. Untuk API Kueri, tidak ada opsi header yang diperlukan, jadi langkah ini dilakukan.

  6. Periksa apakah isi yang ditampilkan untuk permintaan di tab Isi cocok dengan kebutuhan yang dijelaskan dalam dokumentasi referensi. Untuk API Kueri, badan JSON diperlukan untuk memberikan teks kueri. Berikut adalah contoh badan untuk permintaan ini yang meminta semua kembar digital dalam contoh:

    Cuplikan layar detail permintaan baru di Postman, pada tab Body. Ini berisi isi JSON mentah dengan kueri 'SELECT * FROM DIGITALTWINS'.

    Untuk informasi selengkapnya tentang menyusun kueri Azure Digital Twins, lihat Mengkueri grafik kembar.

  7. Periksa dokumentasi referensi untuk bidang lain yang mungkin diperlukan untuk jenis permintaan Anda. Untuk Query API, semua persyaratan sekarang telah dipenuhi dalam permintaan Postman, jadi langkah ini dilakukan.

  8. Gunakan tombol Kirim untuk mengirim permintaan Anda yang telah selesai. Cuplikan layar Postman memperlihatkan detail permintaan baru. Tombol Kirim disorot.

Setelah mengirim permintaan, detail respons akan muncul di jendela Postman di bawah permintaan. Anda dapat melihat kode status respons dan teks isi apa pun.

Cuplikan layar permintaan yang dikirim di Postman. Di bawah detail permintaan, respons ditampilkan. Status adalah 200 OK dan isi memperlihatkan hasil kueri.

Anda juga dapat membandingkan respons dengan data respons yang diharapkan yang diberikan dalam dokumentasi referensi, untuk memverifikasi hasilnya atau mempelajari selengkapnya tentang kesalahan yang muncul.

Langkah berikutnya

Untuk mempelajari selengkapnya tentang API Digital Twins, baca API dan SDK Azure Digital Twins, atau lihat dokumentasi referensi untuk REST API.