Bagikan melalui

Mulai menggunakan REST API

Layanan Azure DevOps | Azure DevOps Server | Azure DevOps Server 2022

Azure DevOps REST API menyediakan akses terprogram yang kuat ke item kerja, repositori, build, rilis, dan banyak lagi. Baik Anda membangun integrasi kustom, mengotomatiskan alur kerja, atau memperluas kemampuan Azure DevOps, memahami pola dan konsep dasar sangat penting untuk keberhasilan implementasi.

Petunjuk / Saran

Siap untuk memulai pengkodan? Lewati ke sampel REST API untuk contoh kerja lengkap dengan pola autentikasi modern.

Artikel ini membahas konsep dan pola mendasar untuk AZURE DEVOPS REST API. Untuk contoh implementasi praktis, lihat sampel REST API.

Petunjuk / Saran

Anda dapat menggunakan AI untuk membantu tugas ini nanti dalam artikel ini, atau lihat Mengaktifkan bantuan AI dengan Azure DevOps MCP Server untuk memulai.

Struktur URL

API mengikuti pola umum, seperti yang ditunjukkan dalam contoh berikut:

VERB https://{instance}/{collection}/{team-project}/_apis/{area}/{resource}?api-version={version}

Petunjuk / Saran

Seiring berkembangnya API, sertakan versi API di setiap permintaan. Praktik ini membantu Anda menghindari perubahan tak terduga dalam API yang dapat merusak aplikasi Anda.

Untuk Azure DevOps Services, instancedev.azure.com/{organization} dan collectionDefaultCollection, sehingga polanya terlihat seperti contoh berikut:

VERB https://dev.azure.com/{organization}/_apis/{area}/{resource}?api-version={version}

Contoh titik akhir:

GET https://dev.azure.com/{organization}/_apis/projects?api-version=7.2

Otentikasi

Azure DevOps REST API mendukung beberapa metode autentikasi:

  • Microsoft Entra ID - Direkomendasikan untuk aplikasi produksi
  • Token Akses Pribadi (PATs) - Autentikasi sederhana untuk skrip dan pengujian
  • Principal layanan dan identitas terkelola - Untuk skenario otomatis

Penting

Pertimbangkan untuk menggunakan token Microsoft Entra yang lebih aman daripada token akses personal yang berisiko lebih tinggi. Untuk informasi selengkapnya, lihat Mengurangi penggunaan PAT. Tinjau panduan autentikasi untuk memilih mekanisme autentikasi yang tepat untuk kebutuhan Anda.

Format Tanggapan

Azure DevOps REST API biasanya mengembalikan respons JSON. Berikut adalah contoh struktur respons:

{
    "value": [
        {
            "id": "00000000-0000-0000-0000-000000000000",
            "name": "Fabrikam-Fiber-TFVC",
            "url": "https://dev.azure.com/fabrikam-fiber-inc/_apis/projects/00000000-0000-0000-0000-000000000000",
            "description": "Team Foundation Version Control projects"
        }
    ],
    "count": 1
}

Responsnya adalah JSON, yang umumnya anda dapatkan kembali dari REST API, meskipun ada beberapa pengecualian, seperti blob Git.

Petunjuk / Saran

Untuk contoh kerja lengkap yang menunjukkan cara mengurai respons ini, lihat sampel REST API.

Metode dan operasi HTTP

Azure DevOps REST API menggunakan metode HTTP standar:

Metode Digunakan untuk... Contoh
DAPATKAN Dapatkan sumber daya atau daftar sumber daya Mendapatkan proyek, item kerja
PENGUMUMAN Membuat sumber daya, atau mendapatkan sumber daya menggunakan kueri tingkat lanjut Membuat item kerja, menanyakan item kerja
MELETAKKAN Membuat atau mengganti sumber daya sepenuhnya Mengganti definisi build, memperbarui kebijakan
Patch Memperbarui bidang sumber daya tertentu Memperbarui kolom item kerja
MENGHAPUS Menghapus sumber daya Menghapus item kerja

Petunjuk / Saran

Untuk contoh praktis setiap metode HTTP dengan sampel kode lengkap, lihat sampel REST API.

Meminta header dan konten

Saat Anda menyediakan isi permintaan (biasanya dengan POST, PUT, dan PATCH), sertakan header yang sesuai:

Content-Type: application/json

Untuk operasi PATCH pada item kerja, gunakan:

Content-Type: application/json-patch+json

Penggantian metode HTTP

Beberapa proksi web hanya mendukung kata kerja HTTP GET dan POST. Mereka tidak mendukung kata kerja HTTP yang lebih modern seperti PATCH dan DELETE. Jika panggilan Anda mungkin melewati salah satu proksi ini, kirim kata kerja aktual dengan menggunakan metode POST dengan header untuk mengambil alih metode . Misalnya, Anda mungkin ingin memperbarui item kerja (PATCH _apis/wit/workitems/3), tetapi Anda mungkin harus melalui proksi yang hanya mengizinkan GET atau POST. Anda dapat meneruskan kata kerja yang tepat (PATCH dalam hal ini) sebagai parameter header permintaan HTTP dan menggunakan POST sebagai metode HTTP yang digunakan.

POST https://dev.azure.com/fabrikam-fiber-inc/_apis/wit/workitems/3

X-HTTP-Method-Override: PATCH

{
   (PATCH request body)
}

Kode respons

Memahami kode respons HTTP membantu Anda menangani respons API dengan tepat:

Tanggapan Makna Catatan
200 Keberhasilan Isi respons berisi data yang diminta
201 Telah dibuat Sumber daya berhasil dibuat
204 Keberhasilan Tidak ada isi respons (umum dengan DELETE)
400 Permintaan Tidak Valid Parameter atau isi permintaan tidak valid
401 Tidak diizinkan Autentikasi gagal atau hilang
403 Dilarang Pengguna tidak memiliki izin untuk operasi
404 Tidak Ditemukan Sumber daya tidak ada atau tidak ada izin untuk melihat
409 Konflik Permintaan bertentangan dengan keadaan sumber daya saat ini

Pemversionan API

Azure DevOps REST API diberi versi untuk memastikan aplikasi terus berfungsi seiring berkembangnya API.

Panduan

  • Selalu tentukan versi API dengan setiap permintaan (diperlukan)
  • Format versi API sebagai: {major}.{minor} atau (misalnya, , {major}.{minor}-{stage}7.2)7.2-preview
  • Gunakan revisi pratinjau tertentu jika tersedia: 7.2-preview.1, 7.2-preview.2
  • Tingkatkan ke versi yang dirilis saat API pratinjau tidak digunakan lagi

Penggunaan

Tentukan versi API sebagai parameter kueri URL:

GET https://dev.azure.com/{organization}/_apis/projects?api-version=7.2

Atau di header permintaan:

Accept: application/json;api-version=7.2

Untuk versi yang didukung, lihat Penerapan versi REST API.

Sumber daya lainnya

Untuk panduan implementasi praktis dan contoh kode lengkap, lihat:

Menggunakan AI untuk membangun panggilan REST API

Jika Anda menyambungkan Azure DevOps MCP Server ke agen AI dalam mode agen, Anda dapat menggunakan perintah bahasa alami untuk menghasilkan dan memecahkan masalah panggilan REST API.

Tugas Contoh tanggapan
Membuat permintaan GET Show me how to construct a GET request to list all projects in my Azure DevOps organization using the REST API
Membuat badan POST Generate the JSON-patch body for creating a work item using the Azure DevOps REST API
Menangani autentikasi Write C# code to call the Azure DevOps REST API with a Bearer token from Microsoft Entra ID
Menjelajahi area API What Azure DevOps REST API endpoints are available for managing Git pull requests?
Mengurai respons API Show me how to deserialize an Azure DevOps REST API response into C# objects and handle pagination with continuation tokens
Kesalahan API debug I'm getting a 400 error when calling the Azure DevOps work item update API — help me understand the correct PATCH format

Nota

Mode agen dan Server MCP menggunakan bahasa alami, sehingga Anda dapat menyesuaikan perintah ini atau mengajukan pertanyaan tindak lanjut untuk memperbaiki hasilnya.

Langkah selanjutnya

Coba sampel REST API

  • Last updated on