Referensi API REST Azure

Selamat datang di Referensi Azure REST API.

API Transfer Status Representasional (REST) adalah titik akhir layanan yang mendukung serangkaian operasi HTTP (metode), yang menyediakan akses buat/ambil/perbarui/hapus ke sumber daya layanan. Bagian-bagian di bawah ini akan memanding Anda melalui:

Komponen dasar dari pasangan permintaan/respons REST API
Cara mendaftarkan aplikasi klien Anda dengan Azure Active Directory (Azure AD) untuk mengamankan permintaan REST Anda
Gambaran umum pembuatan dan pengiriman permintaan REST, dan penanganan respons

Catatan

Sebagian besar REST API layanan Azure memiliki pustaka SDK klien yang sesuai, yang menangani banyak kode klien untuk Anda. Lihat:

Azure .NET SDK
Azure Java SDK
Azure CLI 2.0 SDK

Komponen permintaan/respon dari REST API

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

Permintaan URI, yang terdiri atas: {URI-scheme} :// {URI-host} / {resource-path} ? {query-string}. Perhatikan bahwa kami memanggil ini secara terpisah di sini, karena sebagian besar bahasa/kerangka kerja mengharuskan Anda untuk meneruskannya secara terpisah dari pesan permintaan, tetapi sebenarnya disertakan dalam header pesan permintaan.
- Skema URI: menunjukkan protokol yang digunakan untuk mengirimkan permintaan. Misalnya, http atau https.
- Host URI: nama domain atau alamat IP server tempat titik akhir layanan REST dihosting, seperti graph.microsoft.com
- Jalur sumber daya: menentukan kumpulan sumber daya atau sumber daya, yang mungkin mencakup 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 kueri (opsional): digunakan untuk menyediakan parameter sederhana tambahan, seperti versi API, kriteria pemilihan sumber daya, dll.
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.
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. Jenis pengodean MIME untuk isi harus ditentukan di Content-type header permintaan juga, untuk operasi POST/PUT. Perhatikan bahwa beberapa layanan mengharuskan Anda menggunakan jenis MIME tertentu, seperti application/json.
Bidang header pesan respons HTTP
- Kode status HTTP, mulai dari kode keberhasilan 2xx hingga kode kesalahan 4xx/5xx. 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.
Bidang isi pesan respons HTTP opsional
- Objek respons yang dikodekan MIME dapat dikembalikan dalam isi respons HTTP, seperti respons dari metode GET yang mengembalikan data. Biasanya ini akan dikembalikan dalam format terstruktur sebagai JSON atau XML, seperti yang ditunjukkan Content-type oleh header respons. Misalnya, saat meminta token akses dari Azure AD, token tersebut akan 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 akan disertakan.

Daftarkan aplikasi klien Anda dengan Azure AD

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

Jika Anda menggunakan REST API yang tidak menggunakan autentikasi Azure AD terintegrasi, atau Anda telah mendaftarkan klien, Anda dapat melompat ke bagian Buat permintaan.

Prasyarat

Aplikasi klien Anda harus membuat konfigurasi identitasnya diketahui Azure AD sebelum run-time, dengan mendaftarkannya di penyewa Azure AD. Di bawah ini adalah daftar item yang perlu dipertimbangkan sebelum mendaftarkan klien Anda dengan Azure AD:

Jika Anda belum memiliki penyewa Azure AD, lihat Cara mendapatkan penyewa Azure Active Directory.
Sesuai Kerangka Kerja Otorisasi OAuth2, Azure AD mendukung 2 jenis klien. Memahami masing-masing akan membantu Anda memutuskan mana yang paling tepat untuk skenario Anda:
- klien web/rahasia (berjalan di server web) dapat mengakses sumber daya di bawah identitas mereka sendiri (yaitu: layanan/daemon), atau mendapatkan otorisasi yang didelegasikan untuk mengakses sumber daya di bawah identitas pengguna yang masuk (yaitu: aplikasi web). Hanya klien web yang memiliki kemampuan untuk mempertahankan dan menyajikan kredensialnya sendiri dengan aman selama autentikasi Azure AD untuk memperoleh token akses.
- klien asli/publik (diinstal/dijalankan pada perangkat) hanya dapat mengakses sumber daya di bawah otorisasi yang didelegasikan, menggunakan identitas pengguna yang masuk untuk memperoleh token akses atas nama pengguna.
Proses pendaftaran akan membuat 2 objek terkait di penyewa Azure AD 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, silakan tinjau Aplikasi dan objek perwakilan layanan di Azure Active Directory.

Sekarang kami siap untuk mendaftarkan aplikasi klien Anda dengan Azure AD.

Registrasi klien

Untuk mendaftarkan klien yang akan mengakses Azure Resource Manager REST API, lihat Menggunakan portal untuk membuat aplikasi Direktori Aktif dan perwakilan layanan yang dapat mengakses sumber daya untuk instruksi pendaftaran langkah demi langkah. Artikel ini (juga tersedia dalam versi PowerShell dan CLI untuk mengotomatiskan pendaftaran) akan menunjukkan kepada Anda cara:

daftarkan aplikasi klien dengan Azure AD
atur permintaan izin untuk memungkinkan klien mengakses Azure Resource Manager API
mengonfigurasi pengaturan Access Control Berbasis Peran (RBAC) Azure Resource Manager untuk mengotorisasi klien

Untuk semua klien lainnya, lihat Mengintegrasikan aplikasi dengan Azure Active Directory. Artikel ini akan menunjukkan cara:

daftarkan aplikasi klien dengan Azure AD, di bagian "Menambahkan aplikasi"
buat kunci rahasia (jika Anda mendaftarkan klien web), di bagian "Memperbarui aplikasi"
tambahkan permintaan izin sebagaimana diperlukan oleh API, di bagian "Memperbarui aplikasi"

Sekarang setelah Anda menyelesaikan pendaftaran aplikasi klien Anda, kami dapat pindah ke kode klien Anda, di mana Anda akan membuat permintaan REST dan menangani respons.

Membuat permintaan

Bagian ini mencakup 3 dari 5 komponen pertama yang kita bahas sebelumnya. Pertama, kita perlu memperoleh token akses dari Azure AD, yang akan kita gunakan dalam merakit header pesan permintaan kita.

Memperoleh token akses

Setelah Anda memiliki pendaftaran klien yang valid, pada dasarnya ada 2 cara mengintegrasikan dengan Azure AD untuk memperoleh token akses:

Azure AD titik akhir layanan OAuth2 platform/language-netral, yang akan kami gunakan. Sama seperti titik akhir Azure REST API yang Anda gunakan, instruksi yang diberikan di bagian ini tidak membuat asumsi tentang platform atau bahasa/skrip klien Anda saat menggunakan titik akhir Azure AD; hanya saja dapat mengirim/menerima permintaan HTTPS ke/dari Azure AD, dan mengurai pesan respons.
Pustaka Autentikasi Microsoft (MSAL) khusus platform/bahasa. Pustaka menyediakan pembungkus asinkron untuk permintaan titik akhir OAuth2, dan fitur penanganan token yang kuat seperti penembolokan dan manajemen token refresh. Untuk detail selengkapnya, termasuk dokumentasi referensi, unduhan pustaka, dan kode sampel, silakan lihat Pustaka Autentikasi Microsoft.

2 titik akhir Azure AD yang akan Anda gunakan untuk mengautentikasi klien Anda dan memperoleh token akses disebut sebagai OAuth2 /authorize dan /token titik akhir. Cara Anda menggunakannya akan 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 akan berasumsi bahwa klien Anda akan menggunakan salah satu alur pemberian otorisasi berikut: kode otorisasi atau kredensial klien. Ikuti instruksi untuk yang paling sesuai dengan skenario Anda, untuk memperoleh token akses yang akan Anda gunakan di bagian yang tersisa.

Pemberian kode otorisasi (klien interaktif)

Pemberian ini dapat digunakan oleh klien web dan asli, dan 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 masuk/persetujuan pengguna), diikuti oleh /token titik akhir untuk menukar kode otorisasi dengan token akses.

Pertama, klien Anda harus meminta kode otorisasi dari Azure AD. Lihat Meminta kode otorisasi untuk detail tentang format permintaan HTTPS GET ke /authorize titik akhir, dan contoh pesan permintaan/respons. URI akan berisi parameter string kueri, termasuk yang berikut ini khusus untuk aplikasi klien Anda:
- client_id - juga dikenal sebagai ID aplikasi, ini adalah GUID yang ditetapkan ke aplikasi klien Anda ketika Anda mendaftar di bagian di atas
- redirect_uri - versi [salah satu] URI balasan/pengalihan yang dikodekan URL yang ditentukan selama pendaftaran aplikasi klien Anda. Perhatikan bahwa nilai yang Anda lewati harus sama persis dengan 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:
  - Penggunaan API penyedia Azure Resource Manager (dan Manajemen Layanan klasik)https://management.core.windows.net/
  - Untuk sumber daya lainnya, lihat dokumentasi API atau konfigurasi aplikasi sumber daya di portal Azure. Lihat juga identifierUris properti objek aplikasi Azure AD untuk detail selengkapnya.
Permintaan ke /authorize titik akhir akan terlebih dahulu memicu permintaan masuk untuk mengautentikasi pengguna akhir. Respons yang Anda dapatkan kembali akan dikirimkan sebagai pengalihan (302) ke URI yang Anda tentukan di redirect_uri. Pesan header respons akan berisi location bidang, yang berisi URI pengalihan diikuti oleh code parameter kueri, yang berisi kode otorisasi yang Anda perlukan untuk langkah #2.
Selanjutnya, klien Anda harus menukarkan kode otorisasi untuk token akses. Lihat Menggunakan kode otorisasi untuk meminta token akses untuk detail tentang format permintaan HTTPS POST ke /token titik akhir, dan contoh pesan permintaan/respons. Karena ini adalah permintaan POST, kali ini Anda akan mengemas parameter khusus aplikasi Anda di isi permintaan. Selain beberapa yang disebutkan di atas (bersama dengan yang baru lainnya), Anda akan lulus :
- code - ini adalah parameter kueri yang akan berisi kode otorisasi yang Anda peroleh di langkah #1.
- client_secret - Anda hanya akan memerlukan parameter ini 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 dapat digunakan oleh klien web, memungkinkan aplikasi untuk mengakses sumber daya secara langsung (tidak ada delegasi pengguna) menggunakan kredensial klien sendiri, yang disediakan pada waktu pendaftaran. Ini biasanya digunakan oleh klien non-interaktif (tanpa UI) yang berjalan sebagai daemon/layanan, dan hanya /token memerlukan titik akhir untuk memperoleh token akses.

Interaksi klien/sumber daya untuk hibah ini sangat mirip dengan langkah #2 dari pemberian kode otorisasi. Silakan lihat bagian "Minta Token Akses" di Layanan ke panggilan layanan menggunakan kredensial klien untuk detail tentang format permintaan HTTPS POST ke /token titik akhir, dan contoh pesan permintaan/respons.

Merakit pesan permintaan

Perhatikan bahwa sebagian besar bahasa/kerangka kerja pemrograman dan lingkungan pembuatan skrip memudahkan untuk merakit dan mengirim pesan permintaan. Mereka biasanya menyediakan kelas web/HTTP atau API yang mengabstraksi pembuatan/pemformatan permintaan, sehingga lebih mudah untuk menulis kode klien (misalnya: kelas HttpWebRequest di .NET Framework, misalnya). Untuk keringkasan, kami hanya akan membahas elemen penting dari permintaan, mengingat bahwa sebagian besar hal ini akan ditangani untuk Anda.

Meminta URI

Semua permintaan REST aman memerlukan protokol HTTPS untuk skema URI, memberikan permintaan dan respons dengan saluran aman, karena fakta bahwa informasi sensitif dikirimkan/diterima. Informasi ini (yaitu: kode otorisasi Azure AD, token akses/pembawa, 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) akan ditentukan oleh spesifikasi REST API terkait. Misalnya, API penyedia Azure Resource Manager menggunakan https://management.azure.com/, API Manajemen Layanan Azure klasik menggunakan https://management.core.windows.net/, keduanya memerlukan api-version parameter string kueri, dll.

Meminta kop

URI permintaan akan dibundel di header pesan permintaan, bersama dengan bidang tambahan seperti yang ditentukan oleh spesifikasi REST API layanan Anda dan spesifikasi HTTP. Berikut adalah beberapa bidang header umum yang mungkin Anda butuhkan dalam permintaan Anda:

Authorization: berisi token pembawa OAuth2 untuk mengamankan permintaan, seperti yang diperoleh sebelumnya dari Azure AD
Content-Type: biasanya diatur ke "application/json" (pasangan nama/nilai dalam format JSON), dan menentukan jenis MIME dari isi permintaan.
Host: ini adalah 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 akan menentukan pengodean dan format.

Isi permintaan dipisahkan dari header dengan baris kosong, harus diformat per 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/isi pesan permintaan terkait, Anda siap untuk mengirim permintaan ke titik akhir layanan REST.

Misalnya, metode permintaan HTTPS GET untuk penyedia Azure Resource Manager mungkin dikirim menggunakan bidang header permintaan yang mirip dengan yang berikut ini, tetapi perhatikan 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 metode permintaan HTTPS PUT untuk penyedia Azure Resource Manager mungkin dikirim menggunakan bidang header permintaan DAN isi yang mirip dengan yang berikut ini:

PUT /subscriptions/03f09293-ce69-483a-a092-d06ea46dfb8c/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 akan dikembalikan.

Memproses pesan respons

Sekarang kita akan selesai dengan 2 terakhir dari 5 komponen.

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

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

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

{
    "value":[
        {
        "id":"/subscriptions/04f09293-ce69-583a-a091-z06ea46dfb8c",
        "subscriptionId":"04f09293-ce69-583a-a091-z06ea46dfb8c",
        "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, kita harus menerima header respons yang mirip dengan yang berikut ini, mengonfirmasi bahwa operasi PUT kami untuk menambahkan "ExampleResourceGroup" berhasil :

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

dan isi respons, mengonfirmasi konten grup sumber daya kami yang baru ditambahkan yang dikodekan dalam format JSON, mirip dengan:

{
    "id":"/subscriptions/03f09293-ce69-483a-a092-d06ea46dfb8c/resourceGroups/ExampleResourceGroup",
    "name":"ExampleResourceGroup",
    "location":"westus",
    "properties":
        {
        "provisioningState":"Succeeded"
        }
}

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

Itu saja! Setelah Anda mendaftarkan aplikasi Azure AD Anda, dan teknik komponen untuk memperoleh token akses dan membuat dan memproses permintaan HTTP, cukup mudah untuk mereplikasi kode Anda untuk memanfaatkan REST API baru.

Lihat platform identitas Microsoft (Azure Active Directory untuk pengembang) untuk informasi selengkapnya tentang pendaftaran aplikasi dan model pemrograman Azure AD, termasuk indeks komprehensif artikel HowTo dan QuickStart, dan kode sampel.
Untuk menguji permintaan/respons HTTP, lihat
- Fiddler. Fiddler adalah proksi penelusuran kesalahan web gratis yang dapat mencegat permintaan REST Anda, sehingga mudah untuk mendiagnosis permintaan HTTP dan pesan respons.
- JWT Decoder dan JWT.io, yang membuatnya cepat dan mudah untuk mencadangkan klaim dalam token pembawa Anda sehingga Anda dapat memvalidasi kontennya.

Silakan gunakan bagian komentar LiveFyre yang mengikuti artikel ini untuk memberikan umpan balik dan membantu kami memperbaiki dan membentuk konten kami.

Last updated on 2023-07-19

Bagikan melalui