Bagikan melalui

Mulai menggunakan REST API

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

REST API Azure DevOps 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 implementasi yang sukses.

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 dasar untuk REST API Azure DevOps. Untuk contoh implementasi praktis, lihat sampel REST API.

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, kami sarankan Anda menyertakan versi API di setiap permintaan. Praktik ini dapat membantu Anda menghindari perubahan tak terduga dalam API yang dapat rusak.

Layanan Azure DevOps

Untuk Layanan Azure DevOps, instance adalah dev.azure.com/{organization} dan collection adalah DefaultCollection, 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

Azure DevOps Server

Untuk Azure DevOps Server, instance adalah {server:port}. Port default untuk koneksi non-SSL adalah 8080.

Koleksi defaultnya adalah DefaultCollection, tetapi Anda dapat menggunakan koleksi apa pun.

Contoh:

  • SSL: https://{server}/DefaultCollection/_apis/projects?api-version=7.2
  • Protokol Non-SSL: http://{server}:8080/DefaultCollection/_apis/projects?api-version=7.2

Otentikasi

REST API Azure DevOps mendukung beberapa metode autentikasi:

  • ID Microsoft Entra - Direkomendasikan untuk aplikasi produksi
  • Token Akses Pribadi (PATs) - Autentikasi sederhana untuk skrip dan pengujian
  • OAuth 2.0 - Untuk aplikasi non-Microsoft
  • Prinsipal Layanan - Untuk skenario otomatis

Penting

Autentikasi ID Microsoft Entra adalah pendekatan yang direkomendasikan untuk aplikasi produksi. Untuk contoh implementasi dan panduan autentikasi lengkap, lihat sampel REST API dan Panduan autentikasi.

Format Tanggapan

REST API Azure DevOps 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": "TeamFoundationVersionControlprojects"
        }
    ],
    "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

REST API Azure DevOps 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 Membuat/memperbarui item kerja
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 mungkin hanya mendukung kata kerja HTTP GET dan POST, tetapi bukan kata kerja HTTP yang lebih modern seperti PATCH dan DELETE. Jika panggilan Anda mungkin melewati salah satu proksi ini, Anda dapat mengirim kata kerja aktual 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

REST API Azure DevOps di-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:

Langkah selanjutnya

Coba sampel REST API

  • Last updated on