Bagikan melalui

Mulai menggunakan REST API

  • Artikel

Layanan Azure DevOps | Azure DevOps Server 2022 - Azure DevOps Server 2019

Integrasikan aplikasi Anda dengan Azure DevOps menggunakan REST API yang disediakan dalam artikel ini.

API mengikuti pola umum, seperti contoh berikut.

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

Tip

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.

Azure DevOps Services

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 berikut menunjukkan cara mendapatkan daftar proyek dalam organisasi.

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

Jika Anda ingin memberikan token akses pribadi (PAT) melalui header HTTP, Anda harus terlebih dahulu mengonversinya menjadi string Base64. Contoh berikut menunjukkan cara mengonversi ke Base64 menggunakan C#. String yang dihasilkan kemudian dapat disediakan sebagai header HTTP dalam format .

Authorization: Basic BASE64PATSTRING

Contoh berikut menunjukkan C# menggunakan kelas HttpClient.

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 = client.GetAsync(
						"https://dev.azure.com/{organization}/_apis/projects").Result)
			{
				response.EnsureSuccessStatusCode();
				string responseBody = await response.Content.ReadAsStringAsync();
				Console.WriteLine(responseBody);
			}
		}
	}
	catch (Exception ex)
	{
		Console.WriteLine(ex.ToString());
	}
}

Sebagian besar sampel kami menggunakan PATS, karena merupakan contoh yang ringkas untuk mengautentikasi dengan layanan. Namun, ada berbagai mekanisme autentikasi yang tersedia untuk Azure DevOps Services termasuk Microsoft Authentication Library (MSAL), OAuth, dan Session Tokens. Untuk informasi selengkapnya, lihat Panduan autentikasi, untuk membantu Anda menentukan mana yang paling cocok untuk skenario Anda.

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.

Berikut cara mendapatkan daftar proyek dari Azure DevOps Server menggunakan port dan koleksi default di seluruh SSL:

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

Untuk mendapatkan daftar yang sama di seluruh koneksi non-SSL:

curl -u {username}:{personalaccesstoken} http://{server}:8080/DefaultCollection/_apis/projects?api-version=2.0

Contoh-contoh ini menggunakan PATS, yang mengharuskan Anda membuat PAT.

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"
            },
            "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"
            },
            "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, yang umumnya anda dapatkan kembali dari REST API, meskipun ada beberapa pengecualian, seperti blob Git.

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

Kata kerja HTTP

Kata kerja Digunakan untuk...
GET Mendapatkan sumber daya atau daftar sumber daya
POST Membuat sumber daya, Mendapatkan daftar sumber daya menggunakan kueri yang lebih canggih
TARUH Buat sumber daya jika tidak ada atau, jika tidak, perbarui
PATCH Memperbarui sumber daya
DELETE Menghapus sumber daya

Meminta header dan meminta konten

Saat Anda menyediakan isi permintaan (biasanya dengan kata kerja POST, PUT, dan PATCH), sertakan header permintaan yang menjelaskan isinya. Contohnya,

POST https://dev.azure.com/fabrikam-fiber-inc/_apis/build-release/requests

Content-Type: application/json

{
   "definition": {
      "id": 3
   },
   "reason": "Manual",
   "priority": "Normal"
}

Penimpaan 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 aktual.

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

X-HTTP-Method-Override: PATCH

{
   (PATCH request body)
}

Kode respons

Respons Catatan
200 Sukses, dan ada isi respons.
201 Berhasil, saat membuat sumber daya. Beberapa API mengembalikan 200 saat berhasil membuat sumber daya. Lihat dokumen untuk API yang Anda gunakan untuk memastikannya.
204 Sukses, dan tidak ada isi respons. Misalnya, Anda mendapatkan respons ini saat menghapus sumber daya.
400 Parameter dalam URL atau di isi permintaan tidak valid.
401 Autentikasi gagal. Seringkali, respons ini karena header Otorisasi yang hilang atau salah bentuk.
403 Pengguna yang diautentikasi tidak memiliki izin untuk melakukan operasi.
404 Sumber daya tidak ada, atau pengguna yang diautentikasi tidak memiliki izin untuk melihat bahwa sumber daya tersebut ada.
409 Ada konflik antara permintaan dan status data di server. Misalnya, jika Anda mencoba mengirimkan permintaan pull dan sudah ada permintaan pull untuk penerapan, kode respons adalah 409.

Berbagi sumber daya lintas asal (CORS)

Layanan Azure DevOps mendukung CORS, yang memungkinkan kode JavaScript dilayani dari domain selain dev.azure.com/* membuat permintaan Ajax ke REST API Azure DevOps Services. Setiap permintaan harus memberikan kredensial (PAT dan token akses OAuth adalah opsi yang didukung). Contoh:

    $( document ).ready(function() {
        $.ajax({
            url: 'https://dev.azure.com/fabrikam/_apis/projects?api-version=1.0',
            dataType: 'json',
            headers: {
                'Authorization': 'Basic ' + btoa("" + ":" + myPatToken)
            }
        }).done(function( results ) {
            console.log( results.value[0].id + " " + results.value[0].name );
        });
    });

(ganti myPatToken dengan token akses pribadi)

Penerapan versi

REST API Azure DevOps di-versi untuk memastikan aplikasi dan layanan terus berfungsi seiring berkembangnya API.

Panduan

  • Tentukan versi API dengan setiap permintaan (diperlukan).
  • Format versi API sebagai berikut: {major}. {minor}-{stage}. {resource-version}. Misalnya, 1.0, 1.1, 1.2-preview, 2.0.
  • Tentukan revisi API tertentu saat dalam pratinjau, dengan menggunakan format versi berikut: 1.0-preview.1, 1.0-preview.2. Setelah API dirilis (1.0, misalnya), versi pratinjaunya (pratinjau 1.0) tidak digunakan lagi dan dapat dinonaktifkan setelah 12 minggu.
  • Tingkatkan ke versi API yang dirilis. Setelah API pratinjau dinonaktifkan, permintaan yang menentukan -preview versi ditolak.

Penggunaan

Tentukan versi API di header permintaan HTTP atau sebagai parameter kueri URL.

Header permintaan HTTP:

Accept: application/json;api-version=1.0

Parameter kueri:

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

Versi yang didukung

Untuk informasi tentang versi yang didukung, lihat Penerapan versi REST API, Versi yang didukung.