Azure DevOps Services REST API Başvurusu

  • Makale

Azure DevOps Services/Azure DevOps Server REST API Başvurusu'na hoş geldiniz.

Temsili Durum Aktarımı (REST) API'leri; hizmet kaynaklarına oluşturma, alma, güncelleştirme veya silme erişimi sağlayan HTTP işlem kümelerini (yöntemler) destekleyen hizmet uç noktalarıdır. Bu makalede size yol gösterilir:

  • REST API istek/yanıt çiftinin temel bileşenleri.
  • REST isteği oluşturma ve gönderme ve yanıtı işlemeye genel bakış.

REST API'lerin çoğuna istemci kitaplıklarımız aracılığıyla erişilebilir ve bu kitaplıklar istemci kodunuzu büyük ölçüde basitleştirmek için kullanılabilir.

REST API istek/yanıt çiftinin bileşenleri

REST API istek/yanıt çifti beş bileşene ayrılabilir:

  1. İstek URI'sini aşağıdaki biçimde kullanın:VERB https://{instance}[/{team-project}]/_apis[/{area}]/{resource}?api-version={version}

    • örnek: İsteği gönderdiğiniz Azure DevOps Services kuruluş veya TFS sunucusu. Bunlar aşağıdaki gibi yapılandırılmıştır:
      • Azure DevOps Services:dev.azure.com/{organization}
      • TFS: {server:port}/tfs/{collection} (varsayılan bağlantı noktası 8080'dir ve koleksiyon değeri herhangi bir koleksiyon DefaultCollection olabilir)
    • kaynak yolu: Kaynak yolu aşağıdaki gibidir: _apis/{area}/{resource}. Örneğin, _apis/wit/workitems.
    • api-version: API'ler geliştikçe uygulamanızın veya hizmetinizin bozulmasından kaçınmak için her API isteğinde bir api sürümü bulunmalıdır. api sürümleri şu biçimdedir: {major}.{minor}[-{stage}[.{resource-version}]], örneğin:
      • api-version=1.0
      • api-version=1.2-preview
      • api-version=2.0-preview.1

    Not: alan ve takım projesi , API isteğine bağlı olarak isteğe bağlıdır. TFS sürümünüz için hangi REST API sürümlerinin geçerli olduğunu bulmak için aşağıdaki TFS'den REST API sürümüne eşleme matrisine göz atın.

  2. HTTP isteği ileti üst bilgisi alanları:

    • Hizmete istediğiniz işlem türünü belirten bir HTTP yöntemi (işlem veya eylem olarak da bilinir). Azure REST API'leri GET, HEAD, PUT, POST ve PATCH yöntemlerini destekler.
    • Belirtilen URI ve HTTP yöntemi için gerekli olan isteğe bağlı üst bilgi alanları. Örneğin, istek için istemci yetkilendirme bilgilerini içeren taşıyıcı belirteci sağlayan bir Yetkilendirme üst bilgisi.

  3. URI ve HTTP işlemini destekleyecek isteğe bağlı HTTP istek iletisi gövdesi alanları. Örneğin POST işlemleri, karmaşık parametreler olarak iletilen MIME kodlamalı nesneler içerir.

    • POST veya PUT işlemleri için, gövde için MIME kodlama türü İçerik türü istek üst bilgisinde de belirtilmelidir. Bazı hizmetlerde application/json gibi belirli bir MIME türü kullanılması gerekir.

  4. HTTP yanıt iletisi üst bilgi alanları:

    • 2xx başarı kodlarından 4xx veya 5xx hata kodlarına kadar değişebilen bir HTTP durum kodu. Alternatif olarak API belgelerinde belirtildiği şekilde hizmet tarafından tanımlanan bir durum kodu da döndürülebilir.
    • İsteğin yanıtını desteklemek için Content-type yanıt üst bilgisi gibi isteğe bağlı ek üst bilgi alanları.

  5. İsteğe bağlı HTTP yanıt iletisi gövdesi alanları:

    • MIME ile kodlanmış yanıt nesneleri HTTP yanıt gövdesinde döndürülebilir; örneğin, veri döndüren bir GET yönteminden gelen yanıt. Bu nesneler genellikle JSON veya XML gibi yapılandırılmış biçimde döndürülür ve bu durum Content-type yanıt üst bilgisi ile belirtilir. Örneğin, Azure AD erişim belirteci istediğinizde, yanıt gövdesinde bir veri koleksiyonundaki çeşitli ad/değer eşleştirilmiş nesnelerden biri olan öğesi olarak access_token döndürülür. Bu örnekte, yanıt üst bilgisi Content-Type: application/json de eklenmiştir.

İsteği oluşturma

Kimlik doğrulaması

Uygulamanızın veya hizmetinizin kimliğini Azure DevOps Services veya TFS ile doğrulamanın birçok yolu vardır. Aşağıdaki tablo, hangi yöntemin sizin için en iyi olduğuna karar vermenin mükemmel bir yoludur:

Uygulama türü Description örnek Kimlik doğrulaması mekanizması Kod örnekleri
Etkileşimli istemci tarafı kullanıcı etkileşimlerine izin veren, Azure DevOps Services REST API'lerini çağıran istemci uygulaması Bir kuruluştaki projeleri numaralandıran konsol uygulaması Microsoft Authentication Library (MSAL) Örnek
Etkileşimli JavaScript GUI tabanlı JavaScript uygulaması Kullanıcının proje bilgilerini görüntüleyen AngularJS tek sayfalı uygulaması MSAL Örnek
Etkileşimli olmayan istemci tarafı Başsız metin yalnızca istemci tarafı uygulaması Kullanıcıya atanan tüm hataları görüntüleyen konsol uygulaması Cihaz Profili Örnek
Etkileşimli web GUI tabanlı web uygulaması Derleme özetlerini görüntüleyen özel Web panosu OAuth Örnek
TFS uygulaması İstemci OM kitaplığını kullanan TFS uygulaması Ekip hata panolarını görüntüleyen TFS uzantısı İstemci Kitaplıkları Örnek
Azure DevOps Services Uzantısı uzantıyı Azure DevOps Services Azure DevOps uzantısı örnekleri VSS Web Uzantısı SDK'sı örnek izlenecek yol

Not: Kimlik doğrulaması hakkında daha fazla bilgiyi kimlik doğrulama kılavuzu sayfamızda bulabilirsiniz.

İsteği derleme

Azure DevOps Services

Azure DevOps Services için örnek şeklindedirdev.azure.com/{organization}, bu nedenle desen şöyle görünür:

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

Örneğin, bir Azure DevOps Services kuruluştaki ekip projelerinin listesini alma burada verilmiştır.

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

Kişisel erişim belirtecini bir HTTP üst bilgisi aracılığıyla sağlamak istiyorsanız, önce bunu bir Base64 dizesine dönüştürmeniz gerekir (aşağıdaki örnekte C# kullanarak Base64'e nasıl dönüştürüldüğü gösterilmektedir). (Postman gibi bazı araçlar varsayılan olarak Base64 kodlaması uygular. API'yi bu tür araçlar aracılığıyla deniyorsanız, PAT'nin Base64 kodlaması gerekli değildir) Sonuçta elde edilen dize, biçiminde bir HTTP üst bilgisi olarak sağlanabilir:

Authorization: Basic BASE64PATSTRING

Burada , [HttpClient sınıfı](/previous-versions/visualstudio/hh193681(v=vs.118) kullanılarak C# dilindedir.

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

Bu sitedeki örneklerin çoğu, hizmetle kimlik doğrulaması için küçük bir örnek olduğundan Kişisel Erişim Belirteçlerini kullanır. Ancak Azure DevOps Services için MSAL, OAuth ve Oturum Belirteçleri gibi çeşitli kimlik doğrulama mekanizmaları vardır. Senaryonuz için en uygun olan kimlik doğrulama bölümüne bakın.

TFS

TFS için ve instance{server:port}/tfs/{collection} varsayılan olarak bağlantı noktası 8080'dir. Varsayılan koleksiyon şeklindedir DefaultCollection, ancak herhangi bir koleksiyon olabilir.

Varsayılan bağlantı noktasını ve koleksiyonu kullanarak TFS'den ekip projelerinin listesini alma burada anlatılır.

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

Yukarıdaki örneklerde, kişisel erişim belirteci oluşturmanızı gerektiren kişisel erişim belirteçleri kullanılır.

Yanıtı işleme

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/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
}

Yanıt JSON'dır. Git blobları gibi birkaç özel durum olsa da REST API'lerinden genellikle bunu alırsınız.

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

API ve TFS sürüm eşlemesi

Aşağıda REST API sürümlerinin ve karşılık gelen TFS sürümlerinin hızlı bir eşlemesini bulabilirsiniz. Tüm API sürümleri hem belirtilen sunucu sürümünde hem de sonraki sürümlerde çalışır.

TFS Sürümü REST API Sürümü Yapım Sürümü
Azure DevOps Server vNext 7.1
Azure DevOps Server 2022 7.0 versions >= 19.205.33122.1
Azure DevOps Server 2020 6.0 versions >= 18.170.30525.1
Azure DevOps Server 2019 5.0 versions >= 17.143.28621.4
TFS 2018 Güncelleştirme 3 4.1 versions >= 16.131.28106.2
TFS 2018 Güncelleştirme 2 4.1 versions >= 16.131.27701.1
TFS 2018 Güncelleştirme 1 4.0 versions >= 16.122.27409.2
TFS 2018 RTW 4.0 versions >= 16.122.27102.1
TFS 2017 Güncelleştirme 2 3.2 versions >= 15.117.26714.0
TFS 2017 Güncelleştirme 1 3,1 versions >= 15.112.26301.0
TFS 2017 RTW 3.0 versions >= 15.105.25910.0
TFS 2015 Güncelleştirme 4 2.3 versions >= 14.114.26403.0
TFS 2015 Güncelleştirme 3 2.3 versions >= 14.102.25423.0
TFS 2015 Güncelleştirme 2 2,2 versions >= 14.95.25122.0
TFS 2015 Güncelleştirme 1 2.1 versions >= 14.0.24712.0
TFS 2015 RTW 2.0 versions >= 14.0.23128.0

İlgili İçerik

REST API örnekleri ve kullanım örnekleri için tümleştirme belgelerine göz atın.

İstemci Kitaplıkları

Bu REST API'leri için istemci kitaplıklarını keşfedin.

REST API'lerin önceki sürümleri nerede? (4.1'in öncesinde)

Yakın zamanda mühendislik sistemimizde ve belge oluşturma sürecimizde bir değişiklik yaptık; bu REST API'lerini kullanmaya çalışan herkes için daha net, daha ayrıntılı ve daha doğru belgeler sağlamak için bu değişikliği yaptık. Teknik kısıtlamalar nedeniyle, bu yöntemi kullanarak yalnızca API Sürüm 4.1 ve daha yeni sürümleri belgeleyebiliyoruz. Bu değişiklik nedeniyle API Sürüm 4.1 ve daha yeni sürümlerin belgelerinin daha kolay kullanılacağına inanıyoruz.

TFS'de çalışıyorsanız veya REST API'lerin eski sürümlerini arıyorsanız, TFS 2015, 2017 ve 2018 için REST API'ye Genel Bakış'a göz atabilirsiniz.