Aracılığıyla paylaş

REST API'leri kullanmaya başlama

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. Bu API'ler hizmetlerle program aracılığıyla etkileşim kurmanıza olanak tanıyarak iş akışlarını otomatikleştirmenize, diğer sistemlerle tümleştirmenize ve Azure DevOps'un özelliklerini genişletmenize olanak tanır.

API'ler, aşağıdaki örnekte gösterildiği gibi ortak bir desen izler:

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

Tavsiye

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 için instancedev.azure.com/{organization} ve collectionDefaultCollectionolduğundan 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 PAT'ye iki nokta üst üste ekleyin. Ardından, iki nokta üst üste ve PAT birleştirmesini Base64 dizesine dönüştürün. Aşağıdaki örnekte C# kullanarak Base64'e nasıl dönüştürüldüğü gösterilmektedir. Sonuçta elde edilen dize şu biçimde bir HTTP üst bilgisi olarak sağlanabilir:

Authorization: Basic BASE64COLONANDPATSTRING

Uyarı

Kimlik doğrulama hatalarını önlemek için PAT'nin önüne iki nokta üst üste ekleyin.

Aşağıdaki örnekte HttpClient sınıfı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());
    }
}

Önemli

Kolaylık sağlamak için birçok örnekte kişisel erişim belirteçleri (PAT) kullansak da, bunları üretim uygulamaları için kullanmayacağız. Bunun yerine daha güvenli kimlik doğrulama mekanizmaları kullanmayı göz önünde bulundurun. Daha fazla bilgi için bkz. Kimlik doğrulama kılavuzu.

Azure DevOps Server

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

Varsayılan koleksiyon 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'ler kullandıkları için bir PAT oluşturmanızgerekir.

Yanıt

Aşağıdaki örneğe benzer bir yanıt almanız gerekir:

{
    "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",
            "collection": {
                "id": "00000000-0000-0000-0000-000000000000",
                "name": "DefaultCollection",
                "url": "https: //dev.azure.com/fabrikam-fiber-inc/_apis/projectCollections/00000000-0000-0000-0000-000000000000",
                "collectionUrl": "https: //dev.azure.com/fabrikam-fiber-inc"
            },
            "defaultTeam": {
                "id": "00000000-0000-0000-0000-000000000000",
                "name": "Fabrikam-Fiber-TFVCTeam",
                "url": "https: //dev.azure.com/fabrikam-fiber-inc/_apis/projects/00000000-0000-0000-0000-000000000000/teams/00000000-0000-0000-0000-000000000000"
            }
        },
        {
            "id": "00000000-0000-0000-0000-000000000000",
            "name": "Fabrikam-Fiber-Git",
            "url": "https: //dev.azure.com/fabrikam-fiber-inc/_apis/projects/00000000-0000-0000-0000-000000000000",
            "description": "Gitprojects",
            "collection": {
                "id": "00000000-0000-0000-0000-000000000000",
                "name": "DefaultCollection",
                "url": "https: //dev.azure.com/fabrikam-fiber-inc/_apis/projectCollections/00000000-0000-0000-0000-000000000000",
                "collectionUrl": "https: //dev.azure.com/fabrikam-fiber-inc"
            },
            "defaultTeam": {
                "id": "00000000-0000-0000-0000-000000000000",
                "name": "Fabrikam-Fiber-GitTeam",
                "url": "https: //dev.azure.com/fabrikam-fiber-inc/_apis/projects/00000000-0000-0000-0000-000000000000/teams/00000000-0000-0000-0000-000000000000"
            }
        }
    ],
    "count": 2
}

Yanıt JSONşeklindedir. 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ını arayabilir 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 yöntemleri

Fiil İçin kullanılır...
GET Kaynak veya kaynak listesi alma
PAYLAŞ Kaynak oluşturma, Daha gelişmiş bir sorgu kullanarak kaynakların listesini alma
YERLEŞTİRMEK Kaynak yoksa oluşturun, varsa güncelleyin.
YAMA Kaynak güncelleştirme
SİLMEK Kaynak silme

İstek başlıkları 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 bir üst bilgi ile yöntemi geçersiz kılacak şekilde POST yöntemini kullanarak gönderebilirsiniz. Örneğin, bir iş öğesini 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ı

Yanıt Notlar
200 Başarı ve bir yanıt gövdesi var.
201 Kaynak yaratırken başarı. 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ı, ancak 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.
401 Kimlik doğrulaması başarısız oldu. Bu yanıt genellikle eksik veya hatalı biçimlendirilmiş yetkilendirme üst bilgilerinden kaynaklanır.
403 Kimliği doğrulanmış kullanıcının işlemi yapma izni yok.
404 Kaynak mevcut değil veya kimliği doğrulanmış kullanıcının bu kaynağın mevcut olduğunu görme izni yok.
409 İstek ile sunucudaki verilerin durumu arasında bir çakışma vardır. Örneğin, bir çekme talebi göndermeye çalışırsanız ve değişiklikler için zaten bir çekme talebi varsa, yanıt kodu 409'dur.

Farklı kaynaklar arası paylaşım (CORS)

Azure DevOps Services, Azure DevOps Services REST API'lerine Ajax isteklerinde bulunmak için dev.azure.com/* dışında 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 );
        });
    });

myPatToken yerine bir PAT ile değiştirin.

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 belirtin (gerekli).
  • API sürümlerini şu şekilde biçimlendirin: {major}.{minor}-{stage}.{resource-version}. Örneğin, , 1.01.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, -preview sürümü belirten 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.