Referensi AZURE REST API

Selamat datang di dokumentasi referensi Azure REST API.

API Transfer Status Representasional (Representational State Transfer/REST) adalah titik akhir layanan yang mendukung rangkaian operasi (metode) HTTP, yang menyediakan akses membuat, mengambil, memperbarui, atau menghapus sumber daya layanan. Artikel ini memandu Anda:

• Cara memanggil REST API Azure dengan curl
• Komponen dasar dari pasangan permintaan/respons REST API.
• Cara mendaftarkan aplikasi klien Anda dengan Microsoft Entra ID untuk mengamankan permintaan REST Anda.
• Gambaran umum membuat dan mengirim permintaan REST, dan menangani respons.

Tip

Sebagian besar REST API layanan Azure memiliki pustaka klien yang menyediakan antarmuka asli untuk menggunakan layanan Azure:

.BERSIH | Jawa | | Node.jsPython | Pergi | C++

Cara memanggil REST API Azure dengan curl

Proses yang dijelaskan dalam posting blog berikut menunjukkan cara memanggil Azure REST API menggunakan curl. Anda mungkin mempertimbangkan untuk menggunakan curl dalam skrip yang tidak dijaga. Misalnya, dalam skenario otomatisasi DevOps.

Memanggil Azure REST API melalui curl

Komponen permintaan/respon dari REST API

Pasangan permintaan/respons REST API dapat dipisahkan menjadi lima komponen:

1. Permintaan URI, yang terdiri atas: {URI-scheme} :// {URI-host} / {resource-path} ? {query-string}. Meskipun URI permintaan disertakan dalam header pesan permintaan, kami menyebutnya secara terpisah di sini karena sebagian besar bahasa atau kerangka kerja mengharuskan Anda untuk meneruskannya secara terpisah dari pesan permintaan.

   • Skema URI: Menunjukkan protokol yang digunakan untuk mengirimkan permintaan. Misalnya, http atau https.
   • Host URI: menentukan nama domain atau alamat IP server tempat titik akhir layanan REST dihosting, seperti graph.microsoft.com.
   • Jalur sumber daya: menentukan sumber daya atau koleksi sumber daya, yang mungkin menyertakan beberapa segmen yang digunakan oleh layanan dalam menentukan pemilihan sumber daya tersebut. Misalnya: beta/applications/00003f25-7e1f-4278-9488-efc7bac53c4a/owners dapat digunakan untuk mengkueri daftar pemilik aplikasi tertentu dalam koleksi aplikasi.
   • String query (opsional): menyediakan parameter sederhana tambahan, seperti versi API atau kriteria pemilihan sumber daya.

2. Bidang header pesan permintaan HTTP:

   • Metode HTTP yang diperlukan (juga dikenal sebagai operasi atau kata kerja), yang memberi tahu layanan jenis operasi apa yang Anda minta. REST API Azure mendukung metode GET, HEAD, PUT, POST, dan PATCH.
   • Bidang header tambahan opsional, sebagaimana diperlukan oleh metode URI dan HTTP yang ditentukan. Misalnya, header Otorisasi yang menyediakan token pembawa yang berisi informasi otorisasi klien untuk permintaan tersebut.

3. Bidang isi pesan permintaan HTTP opsional, untuk mendukung operasi URI dan HTTP. Misalnya, operasi POST berisi objek yang dikodekan MIME yang diteruskan sebagai parameter kompleks. Untuk operasi POST atau PUT, jenis pengodean MIME untuk isi juga harus ditentukan di header permintaan Content-type juga. Beberapa layanan mengharuskan Anda menggunakan jenis MIME tertentu, seperti application/json.

4. Bidang header pesan respons HTTP:

   • Kode status HTTP, mulai dari 2xx kode keberhasilan hingga 4xx atau 5xx kode kesalahan. Alternatifnya, kode status yang ditentukan layanan dapat dikembalikan, seperti yang ditunjukkan dalam dokumentasi API.
   • Bidang header tambahan opsional, sebagaimana diperlukan untuk mendukung respons permintaan, seperti Content-type header respons.

5. Bidang isi pesan respons HTTP opsional:

   • Objek respons yang dikodekan MIME dikembalikan dalam isi respons HTTP, seperti respons dari metode GET yang mengembalikan data. Biasanya, objek ini dikembalikan dalam format terstruktur seperti JSON atau XML, seperti yang ditunjukkan oleh Content-type header respons. Misalnya, saat Anda meminta token akses dari Microsoft Entra ID, token tersebut dikembalikan dalam isi respons sebagai access_token elemen , salah satu dari beberapa objek berpasangan nama/nilai dalam pengumpulan data. Dalam contoh ini, header Content-Type: application/json respons juga disertakan.

Daftarkan aplikasi klien Anda dengan Microsoft Entra ID

Sebagian besar layanan Azure (seperti penyedia Azure Resource Manager dan model penyebaran klasik) mengharuskan kode klien Anda untuk mengautentikasi dengan kredensial yang valid sebelum Anda dapat memanggil API layanan. Autentikasi dikoordinasikan antara berbagai aktor dengan Microsoft Entra ID, dan memberi klien Anda token akses sebagai bukti autentikasi. Token kemudian dikirim ke layanan Azure di header Otorisasi HTTP dari permintaan REST API berikutnya. Klaim token juga memberikan informasi kepada layanan, memungkinkannya untuk memvalidasi klien dan melakukan otorisasi yang diperlukan.

Jika Anda menggunakan REST API yang tidak menggunakan autentikasi Microsoft Entra terintegrasi, atau Anda telah mendaftarkan klien Anda, lewati ke bagian Buat permintaan.

Prasyarat

Aplikasi klien Anda harus membuat konfigurasi identitasnya diketahui Microsoft Entra ID sebelum run-time dengan mendaftarkannya di penyewa Microsoft Entra. Sebelum Anda mendaftarkan klien Anda dengan Microsoft Entra ID, pertimbangkan prasyarat berikut:

• Jika Anda belum memiliki penyewa Microsoft Entra, lihat Menyiapkan penyewa Microsoft Entra.

• Sesuai dengan Kerangka Kerja Otorisasi OAuth2, Microsoft Entra ID mendukung dua jenis klien. Memahami setiap membantu Anda memutuskan mana yang paling tepat untuk skenario Anda:

  • klien web/rahasia berjalan di server web dan dapat mengakses sumber daya dengan identitas mereka sendiri (misalnya, layanan atau daemon), atau mendapatkan otorisasi yang didelegasikan untuk mengakses sumber daya di bawah identitas pengguna yang masuk (misalnya, aplikasi web). Hanya klien web yang dapat mempertahankan dan menyajikan kredensialnya sendiri dengan aman selama autentikasi Microsoft Entra untuk memperoleh token akses.
  • klien asli/publik diinstal dan dijalankan pada perangkat. Mereka hanya dapat mengakses sumber daya berdasarkan otorisasi yang didelegasikan, menggunakan identitas pengguna yang masuk untuk memperoleh token akses atas nama pengguna.

• Proses pendaftaran membuat dua objek terkait di penyewa Microsoft Entra tempat aplikasi terdaftar: objek aplikasi dan objek perwakilan layanan. Untuk latar belakang lebih lanjut tentang komponen-komponen ini dan bagaimana mereka digunakan pada run-time, lihat Aplikasi dan objek perwakilan layanan di Microsoft Entra ID.

Anda sekarang siap untuk mendaftarkan aplikasi klien Anda dengan Microsoft Entra ID.

Registrasi klien

Untuk mendaftarkan klien yang mengakses Azure Resource Manager REST API, lihat Menggunakan portal untuk membuat aplikasi dan perwakilan layanan Microsoft Entra yang dapat mengakses sumber daya. Artikel (juga tersedia di versi PowerShell dan CLI untuk mengotomatiskan pendaftaran) menunjukkan cara:

• Daftarkan aplikasi klien dengan Microsoft Entra ID.
• Atur permintaan izin untuk memungkinkan klien mengakses Azure Resource Manager API.
• Konfigurasikan pengaturan Azure Resource Manager Role-Based Access Control (RBAC) untuk mengotorisasi klien.

Jika klien Anda mengakses API selain Azure Resource Manager API, lihat:

• Mendaftarkan aplikasi dengan platform identitas Microsoft
  • Daftarkan aplikasi klien dengan Microsoft Entra ID, di bagian "Daftarkan aplikasi".
  • Buat kunci rahasia (jika Anda mendaftarkan klien web), di bagian "Tambahkan kredensial".
• Mengonfigurasi aplikasi untuk mengekspos API web
  • Menambahkan izin ke API web Anda, mengeksposnya sebagai cakupan
• Mengonfigurasi aplikasi klien untuk mengakses API web
  • Tambahkan permintaan izin sebagaimana diperlukan oleh cakupan yang ditentukan untuk API, di bagian "Tambahkan izin untuk mengakses API web Anda".

Sekarang setelah Anda menyelesaikan pendaftaran aplikasi klien Anda, lanjutkan ke kode klien tempat Anda membuat permintaan REST dan menangani respons.

Membuat permintaan

Bagian ini mencakup tiga dari lima komponen pertama yang kami bahas sebelumnya. Anda harus terlebih dahulu memperoleh token akses dari Microsoft Entra ID, yang Anda gunakan untuk merakit header pesan permintaan Anda.

Memperoleh token akses

Setelah Anda memiliki pendaftaran klien yang valid, Anda memiliki dua cara untuk berintegrasi dengan Microsoft Entra ID untuk memperoleh token akses:

• Titik akhir layanan OAuth2 platform dan netral bahasa, yang kami gunakan dalam artikel ini. Instruksi yang diberikan di bagian ini tidak mengasumsikan apa pun tentang platform atau bahasa/skrip klien Anda saat Anda menggunakan titik akhir OAuth Microsoft Entra. Satu-satunya persyaratan adalah Anda dapat mengirim/menerima permintaan HTTPS ke/dari Microsoft Entra ID, dan mengurai pesan respons.
• Microsoft Authentication Libraries (MSAL) khusus platform dan bahasa, yang berada di luar cakupan artikel ini. Pustaka menyediakan pembungkus asinkron untuk permintaan titik akhir OAuth2, dan fitur penanganan token yang kuat seperti penembolokan dan manajemen token refresh. Untuk informasi selengkapnya, lihat Gambaran Umum Microsoft Authentication Library (MSAL).

Dua titik akhir Microsoft Entra yang Anda gunakan untuk mengautentikasi klien Anda dan memperoleh token akses disebut sebagai OAuth2 /authorize dan /token titik akhir. Cara Anda menggunakannya tergantung pada pendaftaran aplikasi Anda dan jenis alur pemberian otorisasi OAuth2 yang Anda butuhkan untuk mendukung aplikasi Anda pada run-time. Untuk tujuan artikel ini, kami berasumsi bahwa klien Anda menggunakan salah satu alur pemberian otorisasi berikut: kode otorisasi atau kredensial klien. Untuk memperoleh token akses yang digunakan di bagian yang tersisa, ikuti instruksi untuk alur yang paling sesuai dengan skenario Anda.

Pemberian kode otorisasi (klien interaktif)

Pemberian ini digunakan oleh klien web dan asli, yang memerlukan kredensial dari pengguna yang masuk untuk mendelegasikan akses sumber daya ke aplikasi klien. Ini menggunakan /authorize titik akhir untuk mendapatkan kode otorisasi (sebagai respons terhadap rincian masuk/persetujuan pengguna), diikuti oleh /token titik akhir untuk menukar kode otorisasi dengan token akses.

1. Pertama, klien Anda perlu meminta kode otorisasi dari Microsoft Entra ID. Untuk detail tentang format permintaan HTTPS GET ke /authorize titik akhir, dan contoh pesan permintaan/respons, lihat Meminta kode otorisasi. URI berisi parameter string kueri berikut, yang khusus untuk aplikasi klien Anda:

   • client_id: GUID yang ditetapkan ke aplikasi klien Anda selama pendaftaran, juga dikenal sebagai ID aplikasi.

   • redirect_uri: Versi url yang dikodekan dari salah satu URI balasan/pengalihan, yang ditentukan selama pendaftaran aplikasi klien Anda. Nilai yang Anda lewati harus sama persis dengan nilai pendaftaran Anda.

   • resource: URI pengidentifikasi berkode URL yang ditentukan oleh REST API yang Anda panggil. API Web/REST (juga dikenal sebagai aplikasi sumber daya) dapat mengekspos satu atau beberapa URI ID aplikasi dalam konfigurasinya. Contohnya:

     • API penyedia Azure Resource Manager (dan model penyebaran klasik) menggunakan https://management.core.windows.net/.
     • Untuk sumber daya lainnya, lihat dokumentasi API atau konfigurasi aplikasi sumber daya di portal Azure. Untuk informasi selengkapnya, lihat identifierUris properti objek aplikasi Microsoft Graph API.

   Permintaan ke /authorize titik akhir terlebih dahulu memicu permintaan masuk untuk mengautentikasi pengguna. Respons yang Anda dapatkan kembali dikirimkan sebagai pengalihan (302) ke URI yang Anda tentukan di redirect_uri. Pesan header respons berisi location bidang, yang berisi URI pengalihan diikuti oleh code parameter kueri. Parameter code berisi kode otorisasi yang Anda butuhkan untuk langkah 2.

2. Selanjutnya, klien Anda perlu menukarkan kode otorisasi untuk token akses. Untuk detail tentang format permintaan HTTPS POST ke /token titik akhir dan contoh permintaan/respons, lihat Meminta token akses. Karena ini adalah permintaan POST, Anda mengemas parameter khusus aplikasi Anda di isi permintaan. Selain beberapa parameter yang disebutkan sebelumnya (bersama dengan parameter baru lainnya), Anda akan meneruskan:

   • code: Parameter kueri ini berisi kode otorisasi yang Anda peroleh di langkah 1.

   • client_secret: Anda memerlukan parameter ini hanya jika klien Anda dikonfigurasi sebagai aplikasi web. Ini adalah nilai rahasia/kunci yang sama dengan yang Anda buat sebelumnya, dalam pendaftaran klien.

Pemberian kredensial klien (klien non-interaktif)

Pemberian ini hanya digunakan oleh klien web, memungkinkan aplikasi untuk mengakses sumber daya secara langsung (tidak ada delegasi pengguna) menggunakan kredensial klien, yang disediakan pada waktu pendaftaran. Pemberian biasanya digunakan oleh klien non-interaktif (tanpa UI) yang berjalan sebagai layanan atau daemon. Ini hanya /token memerlukan titik akhir untuk memperoleh token akses.

Interaksi klien/sumber daya untuk hibah ini mirip dengan langkah 2 dari pemberian kode otorisasi. Untuk detail tentang format permintaan HTTPS POST ke /token titik akhir dan contoh permintaan/respons, lihat bagian "Dapatkan token" di platform identitas Microsoft dan alur kredensial klien OAuth 2.0.

Merakit pesan permintaan

Sebagian besar bahasa pemrograman atau kerangka kerja dan lingkungan pembuatan skrip memudahkan untuk merakit dan mengirim pesan permintaan. Mereka biasanya menyediakan kelas web/HTTP atau API yang mengabstraksi pembuatan atau pemformatan permintaan, sehingga lebih mudah untuk menulis kode klien (HttpWebRequestkelas di .NET Framework, misalnya). Untuk keringkasan, dan karena sebagian besar tugas ditangani untuk Anda, bagian ini hanya mencakup elemen penting dari permintaan.

Meminta URI

Karena informasi sensitif sedang dikirimkan dan diterima, semua permintaan REST memerlukan protokol HTTPS untuk skema URI, memberikan permintaan dan menanggapi saluran yang aman. Informasi (yaitu, kode otorisasi Microsoft Entra, token akses/pembawa, dan data permintaan/respons sensitif) dienkripsi oleh lapisan transportasi yang lebih rendah, memastikan privasi pesan.

Sisa URI permintaan layanan Anda (host, jalur sumber daya, dan parameter string kueri yang diperlukan) ditentukan oleh spesifikasi REST API terkait. Misalnya, API penyedia Azure Resource Manager menggunakan https://management.azure.com/, dan model penyebaran klasik Azure menggunakan https://management.core.windows.net/. Keduanya memerlukan api-version parameter query-string.

Meminta kop

URI permintaan dibundel di header pesan permintaan, bersama dengan bidang tambahan apa pun yang diperlukan oleh spesifikasi REST API layanan Anda dan spesifikasi HTTP. Permintaan Anda mungkin memerlukan bidang header umum berikut:

• Authorization: Berisi token pembawa OAuth2 untuk mengamankan permintaan, seperti yang diperoleh sebelumnya dari Microsoft Entra ID.
• Content-Type: Biasanya diatur ke "application/json" (pasangan nama/nilai dalam format JSON), dan menentukan jenis MIME isi permintaan.
• Host: Nama domain atau alamat IP server tempat titik akhir layanan REST dihosting.

Isi permintaan

Seperti disebutkan sebelumnya, isi pesan permintaan bersifat opsional, tergantung pada operasi tertentu yang Anda minta dan persyaratan parameternya. Jika diperlukan, spesifikasi API untuk layanan yang Anda minta juga menentukan pengodean dan format.

Isi permintaan dipisahkan dari header dengan baris kosong, diformat sesuai dengan Content-Type bidang header. Contoh isi berformat "application/json" akan muncul sebagai berikut:

{
  "<name>": "<value>"
}

Mengirim permintaan

Sekarang setelah Anda memiliki URI permintaan layanan dan telah membuat header dan isi pesan permintaan terkait, Anda siap untuk mengirim permintaan ke titik akhir layanan REST.

Misalnya, Anda dapat mengirim metode permintaan HTTPS GET untuk penyedia Azure Resource Manager dengan menggunakan bidang header permintaan yang mirip dengan yang berikut ini (perhatikan bahwa isi permintaan kosong):

GET /subscriptions?api-version=2014-04-01-preview HTTP/1.1
Authorization: Bearer <bearer-token>
Host: management.azure.com

<no body>

Dan Anda dapat mengirim metode permintaan HTTPS PUT untuk penyedia Azure Resource Manager, dengan menggunakan bidang header permintaan dan isi yang mirip dengan contoh berikut:

PUT /subscriptions/.../resourcegroups/ExampleResourceGroup?api-version=2016-02-01  HTTP/1.1
Authorization: Bearer <bearer-token>
Content-Length: 29
Content-Type: application/json
Host: management.azure.com

{
  "location": "West US"
}

Setelah Anda membuat permintaan, header pesan respons dan isi opsional dikembalikan.

Memproses pesan respons

Proses ini menyimpulkan dengan dua terakhir dari lima komponen.

Untuk memproses respons, uraikan header respons dan, secara opsional, isi respons (tergantung pada permintaan). Dalam contoh HTTPS GET yang disediakan di bagian sebelumnya, Anda menggunakan titik akhir /subscriptions untuk mengambil daftar langganan untuk pengguna. Dengan asumsi bahwa respons berhasil, Anda harus menerima bidang header respons yang mirip dengan contoh berikut:

HTTP/1.1 200 OK
Content-Length: 303
Content-Type: application/json;

Dan Anda harus menerima isi respons yang berisi daftar langganan Azure dan properti individualnya yang dikodekan dalam format JSON, mirip dengan:

{
    "value":[
        {
        "id":"/subscriptions/...",
        "subscriptionId":"...",
        "displayName":"My Azure Subscription",
        "state":"Enabled",

"subscriptionPolicies":{
            "locationPlacementId":"Public_2015-09-01",
            "quotaId":"MSDN_2014-05-01",
            "spendingLimit":"On"}
        }
    ]
}

Demikian pula, untuk contoh HTTPS PUT, Anda harus menerima header respons yang mirip dengan yang berikut ini, mengonfirmasi bahwa operasi PUT Anda untuk menambahkan "ExampleResourceGroup" berhasil:

HTTP/1.1 200 OK
Content-Length: 193
Content-Type: application/json;

Dan Anda harus menerima isi respons yang mengonfirmasi konten grup sumber daya yang baru ditambahkan yang dikodekan dalam format JSON, mirip dengan:

{
    "id":"/subscriptions/.../resourceGroups/ExampleResourceGroup",
    "name":"ExampleResourceGroup",
    "location":"westus",
    "properties":
        {
        "provisioningState":"Succeeded"
        }
}

Seperti halnya permintaan, sebagian besar bahasa dan kerangka kerja pemrograman memudahkan untuk memproses pesan respons. Mereka biasanya mengembalikan informasi ini ke aplikasi Anda dengan mengikuti permintaan, memungkinkan Anda memprosesnya dalam format yang ditik/terstruktur. Terutama, Anda tertarik untuk mengonfirmasi kode status HTTP di header respons, dan mengurai isi respons sesuai dengan spesifikasi API (atau Content-Type bidang header respons dan Content-Length ).

Operasi asinkron, pembatasan, dan paging

Pola Buat/Kirim/Respons Proses yang dibahas dalam artikel ini sinkron dan berlaku untuk semua pesan REST. Namun, beberapa layanan juga mendukung pola asinkron, yang memerlukan pemrosesan header respons tambahan untuk memantau atau menyelesaikan permintaan asinkron. Untuk informasi selengkapnya, lihat Melacak operasi Azure asinkron.

Resource Manager menerapkan batas jumlah permintaan baca dan tulis per jam untuk mencegah aplikasi mengirim terlalu banyak permintaan. Jika aplikasi Anda melebihi batas tersebut, permintaan akan dibatasi. Header respons menyertakan jumlah permintaan yang tersisa untuk cakupan Anda. Untuk informasi selengkapnya, harap lihat Pembatasan permintaan Azure Resource Manager.

Beberapa operasi daftar mengembalikan properti yang disebut nextLink dalam isi respons. Anda melihat properti ini ketika hasilnya terlalu besar untuk dikembalikan dalam satu respons. Biasanya, respons menyertakan properti nextLink saat operasi daftar mengembalikan lebih dari 1.000 item. Ketika nextLink tidak ada dalam hasil, hasil yang dikembalikan selesai. Saat nextLink berisi URL, hasil yang dikembalikan hanyalah bagian dari total tataan hasil.

Responsnya dalam format:

{
  "value": [
    <returned-items>
  ],
  "nextLink": "https://management.azure.com/{operation}?api-version={version}&%24skiptoken={token}"
}

Untuk mendapatkan halaman hasil berikutnya, kirim permintaan GET ke URL di properti nextLink. URL menyertakan token kelanjutan untuk menunjukkan di mana Anda berada dalam hasilnya. Lanjutkan mengirim permintaan ke URL NextLink hingga tidak lagi berisi URL dalam hasil yang dikembalikan.

Ketahanan Api Azure

REST API Azure dirancang untuk ketahanan dan ketersediaan berkelanjutan. Operasi sarana kontrol (permintaan yang dikirim ke management.azure.com) di REST API adalah:

• Didistribusikan di seluruh wilayah. Beberapa layanan bersifat regional.

• Didistribusikan di seluruh Zona Ketersediaan (serta wilayah) di lokasi yang memiliki beberapa Zona Ketersediaan.

• Tidak tergantung pada satu pusat data logis.

• Tidak pernah diturunkan untuk kegiatan pemeliharaan.

Konten terkait

Itu saja. Setelah Anda mendaftarkan aplikasi Microsoft Entra Anda dan memiliki teknik modular untuk memperoleh token akses dan menangani permintaan HTTP, cukup mudah untuk mereplikasi kode Anda untuk memanfaatkan REST API baru. Untuk informasi selengkapnya tentang pendaftaran aplikasi dan model pemrograman Microsoft Entra, lihat dokumentasi platform identitas Microsoft.

Untuk informasi tentang menguji permintaan/respons HTTP, lihat:

• Fiddler. Fiddler adalah proksi penelusuran kesalahan web gratis yang dapat mencegat permintaan REST Anda, sehingga mudah untuk mendiagnosis pesan permintaan/respons HTTP.
• JWT.ms, yang membuatnya cepat dan mudah untuk membuang klaim dalam token pembawa Anda sehingga Anda dapat memvalidasi kontennya.