Share via

Cara mengirim permintaan ke API Azure Digital Twins menggunakan Postman

  • Artikel

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 mengonfigurasi klien Postman REST untuk berinteraksi dengan API Azure Digital Twins. Informasi ini khusus untuk layanan Azure Digital Twins.

Artikel ini berisi informasi tentang 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.

Menyiapkan 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 Anda menyiapkan instans, catat nama host instans. Anda dapat menemukan nama host di portal Microsoft Azure.

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 CLI untuk masuk ke akun Azure Anda dan mendapatkan token.

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 berikut untuk memilih antara data plane dan API sarana kontrol.

    Untuk mendapatkan token yang akan digunakan dengan API sarana data, gunakan nilai statis berikut untuk konteks token: 0b07f429-9f4b-4714-9392-cc5e8e80c8b0. Nilai 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 Microsoft Entra 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. Nilai ini adalah nilai token yang akan Anda berikan kepada Postman untuk mengotorisasi permintaan Anda.

    Screenshot of the console showing the result of the az account get-access-token command. The accessToken field with its sample value highlighted.

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. Pengaturan umum 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 mengimpor koleksi 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 untuk mulai menggunakan Azure Digital Twins di Postman adalah dengan mengimpor kumpulan permintaan bawaan untuk API. Ikuti langkah-langkah di bawah ini untuk mengimpor kumpulan permintaan API sarana data Azure Digital Twins populer yang berisi data permintaan sampel.

  1. Dari jendela Postman utama, pilih tombol Impor. Screenshot of a newly opened Postman window. The 'Import' button is highlighted.

  2. Di jendela Impor berikut, pilih Tautkan dan masukkan URL berikut: https://raw.githubusercontent.com/microsoft/azure-digital-twins-postman-samples/main/postman_collection.json. Lalu pilih Impor untuk mengonfirmasi.

    Screenshot of Postman's 'Import' window, showing the file to import as a collection and the Import button.

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

Screenshot of the main Postman window. The newly imported collection is highlighted in the 'Collections' tab.

Tip

Untuk mengimpor set lengkap panggilan API untuk versi tertentu dari API Azure Digital Twins (termasuk sarana kontrol atau sarana data), Anda juga dapat mengimpor file Swagger sebagai koleksi. Untuk tautan ke file Swagger untuk SARANA kontrol dan API sarana data, lihat API dan SDK Azure Digital Twins.

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 menampilkan opsi tindakan. Pilih Edit.

Screenshot of Postman. The 'View more actions' icon for the imported collection is highlighted, and 'Edit' is highlighted in the options.

Ikuti langkah-langkah ini untuk menambahkan token pembawa ke koleksi untuk otorisasi. Gunakan nilai token yang Anda kumpulkan di bagian Dapatkan token pembawa untuk menggunakannya untuk semua permintaan API dalam koleksi Anda.

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

    Screenshot of the imported collection's edit dialog in Postman, showing the 'Authorization' tab.

  2. Atur Jenis ke OAuth 2.0 dan tempelkan token akses Anda ke dalam kotak Token Akses. Anda harus menggunakan token yang benar untuk jenis API yang Anda gunakan, karena ada token yang berbeda untuk API sarana data versus API sarana kontrol. Pilih Simpan.

    Screenshot of Postman edit dialog for the imported collection, on the 'Authorization' tab. Type is 'OAuth 2.0', and Access Token box is highlighted.

    Tip

    Anda dapat memilih untuk mengaktifkan berbagi token jika Anda ingin menyimpan token dengan permintaan di cloud Postman, dan berpotensi berbagi token Anda dengan orang lain.

Konfigurasi lainnya

Anda dapat membantu koleksi terhubung dengan mudah ke sumber daya Azure Digital Twins Anda dengan mengatur beberapa variabel 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. Koleksi 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 tabel berikut untuk mengatur nilai variabel dalam koleksi:

    Variabel Set API Deskripsi
    digitaltwins-hostname Pesawat data Nama host instans Azure Digital Twins Anda. Anda dapat menemukan nilai ini di halaman gambaran umum untuk instans Anda di Portal.
    subscriptionId Sarana kontrol ID langganan Azure Anda.
    digitalTwinInstance Sarana kontrol Nama instans Azure Digital Twins Anda.

    Screenshot of the imported collection's edit dialog in Postman, showing the 'Variables' tab. The 'CURRENT VALUE' field is highlighted.

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

  4. Pilih Simpan.

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. Sebagian besar permintaan dalam koleksi sampel telah dikonfigurasi sebelumnya untuk dijalankan tanpa membuat perubahan lebih lanjut.

  3. Cuplikan layar berikut menunjukkan Tambahkan API DigitalTwinModels . Pada tab Isi , Anda dapat melihat payload JSON yang menentukan model baru untuk ditambahkan:

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

    Screenshot of Postman. The collection is expanded to show the body tab of a request.

  5. Untuk menjalankan permintaan, gunakan tombol Kirim .

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

Buat koleksi Anda sendiri

Alih-alih mengimpor koleksi API Azure Digital Twins yang ada, 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.

    Screenshot of the main Postman window. The 'New' button is highlighted.

    Pilih jenis Koleksi.

    Screenshot of the 'Create New' dialog in Postman. The 'Collection' option is highlighted.

  2. Tab terbuka. Isi detail koleksi baru. Pilih ikon Edit di samping nama default koleksi (Koleksi Baru) untuk menggantinya dengan pilihan nama Anda sendiri.

    Screenshot of the new collection's edit dialog in Postman. The Edit icon next to the name 'New Collection' is highlighted.

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. Gunakan nilai token yang Anda kumpulkan di bagian Dapatkan token pembawa untuk menggunakannya untuk semua permintaan API dalam koleksi Anda.

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

    Screenshot of the new collection's edit dialog in Postman, showing the 'Authorization' tab.

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

    Screenshot of the Postman edit dialog for the new collection, on the 'Authorization' tab. Type is 'OAuth 2.0', and Access Token box is highlighted.

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.

Screenshot of the main Postman window. The newly created custom collection is highlighted in the 'Collections' tab.

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.

    Screenshot of the main Postman window. The 'New' button is highlighted.

    Pilih jenis Permintaan.

    Screenshot of the 'Create New' dialog in Postman. The 'Request' option is highlighted.

  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.

Screenshot of 'Save request' window in Postman showing the fields described. The 'Save to Azure Digital Twins collection' button is highlighted.

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

Screenshot of Postman. The Azure Digital Twins collection is expanded to show the request's details.

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 kueri contoh, artikel ini akan menggunakan Api Kueri Azure Digital Twins untuk mengkueri semua kembar digital dalam instans.

  1. Dapatkan URL permintaan dan ketik dari dokumentasi referensi. Untuk API Kueri, ini saat ini 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. Gunakan nama host instans Anda dari bagian Prasyarat.

    Screenshot of the new request's details in Postman. The query URL from the reference documentation has been filled into the request URL box.

  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 isi contoh untuk permintaan ini yang meminta semua kembar digital dalam instans:

    Screenshot of the new request's details in Postman, on the Body tab. It contains a raw JSON body with a query of '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. Screenshot of Postman showing the details of the new request. The Send button is highlighted.

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

Screenshot of the sent request in Postman. Below the request details, the response is shown. Status is 200 OK and body shows query results.

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.