Referensi REST API Azure DevOps Services

Selamat datang di Referensi Azure DevOps Services/Azure DevOps Server 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:

• Komponen dasar dari pasangan permintaan/respons REST API.
• Gambaran umum pembuatan dan pengiriman permintaan REST, dan penanganan respons.

Sebagian besar REST API dapat diakses melalui pustaka klien kami, yang dapat digunakan untuk sangat menyederhanakan kode klien Anda.

Komponen dari pasangan permintaan/respons REST API

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

1. URI permintaan, dalam formulir berikut:VERB https://{instance}[/{team-project}]/_apis[/{area}]/{resource}?api-version={version}

   • instans: Organisasi Azure DevOps Services atau server TFS yang Anda kirimi permintaan. Mereka disusun sebagai berikut:
     • Layanan Azure DevOps: dev.azure.com/{organization}
     • TFS: {server:port}/tfs/{collection} (port default adalah 8080, dan nilai untuk koleksi harus DefaultCollection tetapi dapat menjadi koleksi apa pun)
   • jalur sumber daya: Jalur sumber daya adalah sebagai berikut: _apis/{area}/{resource}. Contoh: _apis/wit/workitems.
   • versi api: Setiap permintaan API harus menyertakan versi api untuk menghindari pemutusan aplikasi atau layanan saat API berevolusi. versi api dalam format berikut: {major}.{minor}[-{stage}[.{resource-version}]], misalnya:
     • api-version=1.0
     • api-version=1.2-preview
     • api-version=2.0-preview.1

   Catatan: area dan proyek tim bersifat opsional, tergantung pada permintaan API. Lihat matriks pemetaan versi TFS ke REST API di bawah ini untuk menemukan versi REST API mana yang berlaku untuk versi TFS Anda.

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 Jenis konten. 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 dapat 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, ketika Anda 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 disertakan.

Membuat permintaan

Mengautentikasi

Ada banyak cara untuk mengautentikasi aplikasi atau layanan Anda dengan Azure DevOps Services atau TFS. Tabel berikut adalah cara terbaik untuk memutuskan metode mana yang terbaik untuk Anda:

Jenis aplikasi	Deskripsi	contoh	Mekanisme autentikasi	Sampel kode
Sisi klien interaktif	Aplikasi klien, yang memungkinkan interaksi pengguna, memanggil REST API Azure DevOps Services	Aplikasi konsol menghitung proyek dalam organisasi	Microsoft Authentication Library (MSAL)	Sampel
JavaScript Interaktif	Aplikasi JavaScript berbasis GUI	Aplikasi satu halaman AngularJS yang menampilkan informasi proyek untuk pengguna	MSAL	Sampel
Sisi klien non-interaktif	Aplikasi sisi klien hanya teks headless	Aplikasi konsol menampilkan semua bug yang ditetapkan untuk pengguna	Profil Perangkat	Sampel
Web interaktif	Aplikasi web berbasis GUI	Dasbor Web Kustom yang menampilkan ringkasan build	OAuth	Sampel
Aplikasi TFS	Aplikasi TFS menggunakan pustaka OM Klien	Ekstensi TFS menampilkan dasbor bug tim	Pustaka Klien	Sampel
Ekstensi Layanan Azure DevOps	Ekstensi Azure DevOps Services	Sampel ekstensi Azure DevOps	VSS Web Extension SDK	panduan sampel

Catatan: Anda dapat menemukan informasi selengkapnya tentang autentikasi di halaman panduan autentikasi kami.

Merakit permintaan

Azure DevOps

Untuk Layanan Azure DevOps, instans adalah dev.azure.com/{organization}, sehingga polanya terlihat seperti ini:

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

Misalnya, berikut cara mendapatkan daftar proyek tim di organisasi Layanan Azure DevOps.

curl -u {username}[:{personalaccesstoken}] https://dev.azure.com/{organization}/_apis/projects?api-version=2.0

Jika Anda ingin memberikan token akses pribadi melalui header HTTP, Anda harus terlebih dahulu mengonversinya menjadi string Base64 (contoh berikut menunjukkan cara mengonversi ke Base64 menggunakan C#). (Alat tertentu seperti Postman menerapkan pengodean Base64 secara default. Jika Anda mencoba API melalui alat tersebut, pengodean Base64 dari PAT tidak diperlukan) String yang dihasilkan kemudian dapat disediakan sebagai header HTTP dalam format:

Authorization: Basic BASE64PATSTRING

Berikut di C# menggunakan [kelas HttpClient](/previous-versions/visualstudio/hh193681(v=vs.118).

public static async void GetProjects()
{
	try
	{
		var personalaccesstoken = "PAT_FROM_WEBSITE";

		using (HttpClient client = new HttpClient())
		{
			client.DefaultRequestHeaders.Accept.Add(
				new System.Net.Http.Headers.MediaTypeWithQualityHeaderValue("application/json"));

			client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic",
				Convert.ToBase64String(
					System.Text.ASCIIEncoding.ASCII.GetBytes(
						string.Format("{0}:{1}", "", personalaccesstoken))));

			using (HttpResponseMessage response = await client.GetAsync(
						"https://dev.azure.com/{organization}/_apis/projects"))
			{
				response.EnsureSuccessStatusCode();
				string responseBody = await response.Content.ReadAsStringAsync();
				Console.WriteLine(responseBody);
			}
		}
	}
	catch (Exception ex)
	{
		Console.WriteLine(ex.ToString());
	}
}

Sebagian besar sampel di situs ini menggunakan Token Akses Pribadi karena merupakan contoh ringkas untuk mengautentikasi dengan layanan. Namun, ada berbagai mekanisme autentikasi yang tersedia untuk Layanan Azure DevOps termasuk MSAL, OAuth, dan Token Sesi. Lihat bagian Autentikasi untuk panduan mana yang paling cocok untuk skenario Anda.

TFS

Untuk TFS, instance adalah {server:port}/tfs/{collection} dan secara default port adalah 8080. Koleksi defaultnya adalah DefaultCollection, tetapi dapat berupa koleksi apa pun.

Berikut cara mendapatkan daftar proyek tim dari TFS menggunakan port dan koleksi default.

curl -u {username}[:{personalaccesstoken}] https://{server}:8080/tfs/DefaultCollection/_apis/projects?api-version=2.0

Contoh di atas menggunakan token akses pribadi, yang mengharuskan Anda membuat token akses pribadi.

Memproses respons

Anda harus mendapatkan respons seperti ini.

{
    "value": [
        {
            "id": "eb6e4656-77fc-42a1-9181-4c6d8e9da5d1",
            "name": "Fabrikam-Fiber-TFVC",
            "url": "https://dev.azure.com/fabrikam-fiber-inc/_apis/projects/eb6e4656-77fc-42a1-9181-4c6d8e9da5d1",
            "description": "TeamFoundationVersionControlprojects",
            "collection": {
                "id": "d81542e4-cdfa-4333-b082-1ae2d6c3ad16",
                "name": "DefaultCollection",
                "url": "https: //dev.azure.com/fabrikam-fiber-inc/_apis/projectCollections/d81542e4-cdfa-4333-b082-1ae2d6c3ad16",
                "collectionUrl": "https: //dev.azure.com/fabrikam-fiber-inc/DefaultCollection"
            },
            "defaultTeam": {
                "id": "66df9be7-3586-467b-9c5f-425b29afedfd",
                "name": "Fabrikam-Fiber-TFVCTeam",
                "url": "https://dev.azure.com/fabrikam-fiber-inc/_apis/projects/eb6e4656-77fc-42a1-9181-4c6d8e9da5d1/teams/66df9be7-3586-467b-9c5f-425b29afedfd"
            }
        },
        {
            "id": "6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c",
            "name": "Fabrikam-Fiber-Git",
            "url": "https://dev.azure.com/fabrikam-fiber-inc/_apis/projects/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c",
            "description": "Gitprojects",
            "collection": {
                "id": "d81542e4-cdfa-4333-b082-1ae2d6c3ad16",
                "name": "DefaultCollection",
                "url": "https://dev.azure.com/fabrikam-fiber-inc/_apis/projectCollections/d81542e4-cdfa-4333-b082-1ae2d6c3ad16",
                "collectionUrl": "https://dev.azure.com/fabrikam-fiber-inc/DefaultCollection"
            },
            "defaultTeam": {
                "id": "8bd35c5e-30bb-4834-a0c4-d576ce1b8df7",
                "name": "Fabrikam-Fiber-GitTeam",
                "url": "https://dev.azure.com/fabrikam-fiber-inc/_apis/projects/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/teams/8bd35c5e-30bb-4834-a0c4-d576ce1b8df7"
            }
        }
    ],
    "count": 2
}

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

Sekarang Anda harus dapat melihat sekitar area API tertentu seperti pelacakan item kerja atau Git dan sampai ke sumber daya yang Anda butuhkan. Terus baca untuk mempelajari lebih lanjut tentang pola umum yang digunakan dalam API ini.

Pemetaan versi API dan TFS

Di bawah ini Anda akan menemukan pemetaan cepat versi REST API dan rilis TFS yang sesuai. Semua versi API akan berfungsi pada versi server yang disebutkan serta versi yang lebih baru.

Versi TFS	Versi REST API	Versi Build
Azure DevOps Server vNext	7.1
Azure DevOps Server 2022	7.0	>versi =19.205.33122.1
Azure DevOps Server 2020	6.0	>versi =18.170.30525.1
Azure DevOps Server 2019	5.0	>versi =17.143.28621.4
Pembaruan 3 TFS 2018	4,1	>versi =16.131.28106.2
Pembaruan 2 TFS 2018	4,1	>versi =16.131.27701.1
Pembaruan 1 TFS 2018	4,0	>versi =16.122.27409.2
TFS 2018 RTW	4,0	>versi =16.122.27102.1
Pembaruan 2 TFS 2017	3,2	>versi =15.117.26714.0
TFS 2017 Pembaruan 1	3.1	>versi =15.112.26301.0
TFS 2017 RTW	3.0	>versi =15.105.25910.0
Pembaruan 4 TFS 2015	2,3	>versi =14.114.26403.0
TFS 2015 Pembaruan 3	2,3	>versi =14.102.25423.0
Pembaruan 2 TFS 2015	2.2	>versi =14.95.25122.0
Pembaruan 1 TFS 2015	2.1	>versi =14.0.24712.0
TFS 2015 RTW	2.0	>versi =14.0.23128.0

Konten terkait

Lihat dokumentasi Integrasikan untuk sampel REST API dan kasus penggunaan.

• Panduan autentikasi
• Sampel

Pustaka Klien

Temukan pustaka klien untuk REST API ini.

• Dokumentasi konseptual .NET dan dokumentasi referensi .NET
• Go
• Node.js
• Python
• Swagger 2.0
• SDK Ekstensi Web

Di mana versi REST API sebelumnya? (Sebelum 4.1)

Kami baru-baru ini membuat perubahan pada sistem teknik dan proses pembuatan dokumentasi kami; kami membuat perubahan ini untuk memberikan dokumentasi yang lebih jelas, lebih mendalam, dan lebih akurat bagi semua orang yang mencoba menggunakan REST API ini. Karena kendala teknis, kami hanya dapat mendokumen API Versi 4.1 dan yang lebih baru menggunakan metode ini. Kami percaya dokumentasi untuk API Versi 4.1 dan yang lebih baru akan lebih mudah digunakan karena perubahan ini.

Jika Anda bekerja di TFS atau mencari versi REST API yang lebih lama, Anda dapat melihat Gambaran Umum REST API untuk TFS 2015, 2017, dan 2018.