Aracılığıyla paylaş

REST API'leri kullanmaya başlama

  • Makale

Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019

Bu makalede sağlanan REST API'lerini kullanarak uygulamanızı Azure DevOps ile tümleştirin.

API'ler aşağıdaki örnekte olduğu gibi ortak bir desen izler.

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

İpucu

API'ler geliştikçe, her isteğe bir API sürümü eklemenizi öneririz. Bu uygulama, API'de bozulabilecek beklenmeyen değişiklikleri önlemenize yardımcı olabilir.

Azure DevOps Services

Azure DevOps Services instance için , dev.azure.com/{organization} ve collection şeklindedir DefaultCollection, bu nedenle desen aşağıdaki örneğe benzer.

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

Aşağıdaki örnekte, bir kuruluştaki projelerin listesinin nasıl alın aldığı gösterilmektedir.

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

Kişisel erişim belirtecini (PAT) bir HTTP üst bilgisi aracılığıyla sağlamak istiyorsanız, önce base64 dizesine dönüştürmeniz gerekir. Aşağıdaki örnekte C# kullanarak Base64'e nasıl dönüştürüldüğü gösterilmektedir. Sonuçta elde edilen dize, biçiminde bir HTTP üst bilgisi olarak sağlanabilir.

Authorization: Basic BASE64PATSTRING

Aşağıdaki örnekte HttpClient sınıfını kullanan C# gösterilmektedir.

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());
	}
}

Örneklerimizin çoğu, hizmette kimlik doğrulaması için küçük bir örnek olduğundan, PAT'leri kullanır. Ancak Azure DevOps Services için Microsoft Kimlik Doğrulama Kitaplığı (MSAL), OAuth ve Oturum Belirteçleri gibi çeşitli kimlik doğrulama mekanizmaları vardır. Daha fazla bilgi için bkz . Senaryonuz için en uygun olanı belirlemenize yardımcı olacak kimlik doğrulama kılavuzu.

Azure DevOps Server

Azure DevOps Server için , instance şeklindedir {server:port}. SSL olmayan bir bağlantı için varsayılan bağlantı noktası 8080'dir.

Varsayılan koleksiyon şeklindedir DefaultCollection, ancak herhangi bir koleksiyonu kullanabilirsiniz.

SSL genelinde varsayılan bağlantı noktasını ve koleksiyonu kullanarak Azure DevOps Server'dan projelerin listesini şu şekilde alabilirsiniz:

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

SSL olmayan bir bağlantıda aynı listeyi almak için:

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

Bu örneklerde, PAT oluşturmanızı gerektiren PAT'ler kullanılır.

Yanıtlar

Bunun gibi bir yanıt almalısınız.

{
    "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
}

Yanıt JSON'dur. Bu genellikle REST API'lerinden elde ettiğiniz yanıttır, ancak Git blobları gibi birkaç özel durum vardır.

Artık iş öğesi izleme veya Git gibi belirli API alanlarına göz atabilir ve ihtiyacınız olan kaynaklara ulaşabilirsiniz. Bu API'lerde kullanılan genel desenler hakkında daha fazla bilgi edinmek için okumaya devam edin.

HTTP fiilleri

Fiil Için kullanılır...
GET Kaynak veya kaynak listesi alma
POST Kaynak oluşturma, Daha gelişmiş bir sorgu kullanarak kaynakların listesini alma
PUT Yoksa bir kaynak oluşturun veya varsa güncelleştirin
PATCH Kaynak güncelleştirme
SİL Kaynak silme

İstek üst bilgileri ve istek içeriği

İstek gövdesini sağladığınızda (genellikle POST, PUT ve PATCH fiilleriyle), gövdeyi açıklayan istek üst bilgilerini ekleyin. Örneğin,

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

Content-Type: application/json

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

HTTP yöntemini geçersiz kılma

Bazı web proxy'leri yalnızca GET ve POST HTTP fiillerini desteklese de PATCH ve DELETE gibi daha modern HTTP fiillerini desteklemeyebilir. Çağrılarınız bu proxy'lerden birinden geçebiliyorsa, gerçek fiili post yöntemini kullanarak ve yöntemini geçersiz kılmak için üst bilgiyle gönderebilirsiniz. Örneğin, bir iş öğesini ()PATCH _apis/wit/workitems/3 güncelleştirmek isteyebilirsiniz, ancak yalnızca GET veya POST'a izin veren bir ara sunucu üzerinden geçmeniz gerekebilir. Uygun fiili (bu örnekte PATCH) bir HTTP isteği üst bilgisi parametresi olarak geçirebilir ve gerçek HTTP yöntemi olarak POST kullanabilirsiniz.

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

X-HTTP-Method-Override: PATCH

{
   (PATCH request body)
}

Yanıt kodları

Response Notlar
200 Başarılı ve bir yanıt gövdesi var.
201 Başarılı, kaynak oluştururken. Bazı API'ler, kaynak başarıyla oluşturulduğunda 200 döndürür. Emin olmak için kullandığınız API'nin belgelerine bakın.
204 Başarılı ve yanıt gövdesi yok. Örneğin, bir kaynağı sildiğinizde bu yanıtı alırsınız.
400 URL'deki veya istek gövdesindeki parametreler geçerli değil.
Kategori 401 Kimlik doğrulaması gerçekleştirilemedi. Bu yanıt genellikle eksik veya hatalı biçimlendirilmiş yetkilendirme üst bilgilerinden kaynaklanır.
Kategori 403 Kimliği doğrulanmış kullanıcının işlemi yapma izni yok.
404 Kaynak yok veya kimliği doğrulanmış kullanıcının var olduğunu görme izni yok.
409 İstek ile sunucudaki verilerin durumu arasında bir çakışma vardır. Örneğin, bir çekme isteği göndermeye çalışırsanız ve işlemeler için zaten bir çekme isteği varsa yanıt kodu 409 olur.

Çıkış noktaları arası kaynak paylaşımı (CORS)

Azure DevOps Services, Azure DevOps Services REST API'lerine Ajax istekleri göndermek dışında dev.azure.com/* bir etki alanından sunulan JavaScript kodunu etkinleştiren CORS'yi destekler. Her istek kimlik bilgileri sağlamalıdır (PAT'ler ve OAuth erişim belirteçleri her ikisi de desteklenen seçeneklerdir). Örnek:

    $( 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 );
        });
    });

(yerine kişisel erişim belirteci koy myPatToken )

Sürüm oluşturma

Azure DevOps REST API'leri, API'ler geliştikçe uygulamaların ve hizmetlerin çalışmaya devam etmesini sağlamak için sürümü oluşturulur.

Yönergeler

  • Api sürümünü her istekle (gerekli) belirtin.
  • API sürümlerini şu şekilde biçimlendirin: {major}. {minor}-{stage}. {resource-version}. Örneğin, 1.0, 1.1, 1.2-preview, 2.0.
  • Aşağıdaki sürüm biçimini kullanarak API'nin önizleme aşamasındayken belirli bir düzeltmesini belirtin: 1.0-preview.1, 1.0-preview.2. API yayımlandıktan sonra (örneğin 1.0 sürümü), önizleme sürümü (1.0-önizleme) kullanım dışı bırakılır ve 12 hafta sonra ise devre dışı bırakılabilir.
  • API'nin yayımlanan sürümüne yükseltin. Önizleme API'si devre dışı bırakıldıktan sonra, sürümü belirten -preview istekler reddedilir.

Kullanım

HTTP isteğinin üst bilgisinde veya URL sorgu parametresi olarak API sürümünü belirtin.

HTTP isteği üst bilgisi:

Accept: application/json;api-version=1.0

Sorgu parametresi:

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

Desteklenen sürümler

Desteklenen sürümler hakkında bilgi için bkz . REST API sürümü oluşturma, Desteklenen sürümler.