Rozpocznij pracę z interfejsami API REST

Artykuł
03/26/2025

Azure DevOps Services | Azure DevOps Server 2022 — Azure DevOps Server 2019

Zintegruj aplikację z usługą Azure DevOps przy użyciu interfejsów API REST podanych w tym artykule. Te interfejsy API umożliwiają programową interakcję z usługami, umożliwiając automatyzowanie przepływów pracy, integrację z innymi systemami i rozszerzanie możliwości usługi Azure DevOps.

Interfejsy API są zgodne ze wspólnym wzorcem, jak pokazano w poniższym przykładzie:

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

Wskazówka

W miarę rozwoju interfejsów API zalecamy uwzględnienie wersji interfejsu API w każdym żądaniu. Takie rozwiązanie może pomóc uniknąć nieoczekiwanych zmian w interfejsie API, które mogłyby spowodować problemy.

Azure DevOps Services

W przypadku usług Azure DevOps Services instance jest dev.azure.com/{organization}, a collection jest DefaultCollection, więc wzorzec wygląda następująco:

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

W poniższym przykładzie pokazano, jak uzyskać listę projektów w organizacji:

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

Jeśli chcesz podać osobisty token dostępu (PAT) za pośrednictwem nagłówka HTTP, najpierw przekonwertuj go na ciąg Base64. W poniższym przykładzie pokazano, jak przekonwertować na base64 przy użyciu języka C#. Wynikowy ciąg można następnie podać jako nagłówek HTTP w formacie:

Authorization: Basic BASE64PATSTRING

W poniższym przykładzie pokazano język C# przy użyciu klasy 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());
    }
}

Ważne

Chociaż używamy osobistych tokenów dostępu (PATs) w wielu przykładach dla uproszczenia, nie zalecamy ponownego używania ich w przypadku aplikacji produkcyjnych. Zamiast tego rozważ użycie bezpieczniejszych mechanizmów uwierzytelniania. Aby uzyskać więcej informacji, zobacz wskazówki dotyczące uwierzytelniania .

Azure DevOps Server

W przypadku usługi Azure DevOps Server instance jest {server:port}. Domyślnym portem połączenia bez protokołu SSL jest 8080.

Domyślna kolekcja to DefaultCollection, ale można użyć dowolnej kolekcji.

Poniżej przedstawiono sposób uzyskiwania listy projektów z usługi Azure DevOps Server przy użyciu domyślnego portu i kolekcji w protokole SSL:

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

Aby uzyskać tę samą listę przez połączenie bez protokołu SSL:

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

W tych przykładach są używane usługi PAT, które wymagają utworzeniapat .

Odpowiedzi

Powinna zostać wyświetlona odpowiedź podobna do poniższego przykładu:

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

Odpowiedź to JSON, co jest typową odpowiedzią z interfejsów API REST, chociaż istnieje kilka wyjątków, takich jak bloby Git.

Teraz możesz przyjrzeć się konkretnym obszarom interfejsu API , takim jak śledzenie elementów roboczych lub Git , i uzyskać dostęp do potrzebnych zasobów. Czytaj dalej, aby dowiedzieć się więcej na temat ogólnych wzorców używanych w tych interfejsach API.

Czasowniki HTTP

Czasownik	Służy do...
GET	Pobierz zasób lub listę zasobów
Bez znajomości kontekstu, w którym "POST" jest używany, nie mogę zaproponować dokładnego tłumaczenia. Jeżeli dotyczy HTTP, pozostaw jako "POST".	Tworzenie zasobu, uzyskiwanie listy zasobów przy użyciu bardziej zaawansowanego zapytania
POŁÓŻ	Utwórz zasób, jeśli nie istnieje lub, jeśli tak, zaktualizuj go
Poprawka	Aktualizowanie zasobu
USUŃ	Usuwanie zasobu

Nagłówki żądań i zawartość żądania

Po podaniu treści żądania (zwykle z czasownikami POST, PUT i PATCH) dołącz nagłówki żądań opisujące treść. Na przykład

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

Content-Type: application/json

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

Zastępowanie metody HTTP

Niektóre internetowe serwery proxy mogą obsługiwać tylko czasowniki HTTP GET i POST, ale nie bardziej nowoczesne czasowniki HTTP, takie jak PATCH i DELETE. Jeśli wywołania mogą przechodzić przez jeden z tych serwerów proxy, możesz wysłać rzeczywiste zlecenie przy użyciu metody POST z nagłówkiem, aby zastąpić metodę . Na przykład możesz zaktualizować element roboczy (PATCH _apis/wit/workitems/3), ale może być konieczne przejście przez serwer proxy, który zezwala tylko na metody GET lub POST. Możesz przekazać odpowiedni czasownik (PATCH w tym przypadku) jako parametr nagłówka żądania HTTP i użyć POST jako rzeczywistej metody HTTP.

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

X-HTTP-Method-Override: PATCH

{
   (PATCH request body)
}

Kody odpowiedzi

Odpowiedź	Notatki
200	Powodzenie i istnieje treść odpowiedzi.
201	Sukces w tworzeniu zasobów. Niektóre interfejsy API zwracają wartość 200 podczas pomyślnego tworzenia zasobu. Zapoznaj się z dokumentami dotyczącymi interfejsu API, którego używasz, aby mieć pewność.
204	Powodzenie, i brak treści odpowiedzi. Na przykład otrzymasz tę odpowiedź po usunięciu zasobu.
400	Parametry w adresie URL lub w treści żądania są nieprawidłowe.
401	Uwierzytelnianie nie powiodło się. Często ta odpowiedź jest spowodowana brakiem lub źle sformułowanym nagłówkiem autoryzacji.
403	Uwierzytelniony użytkownik nie ma uprawnień do wykonania operacji.
404	Zasób nie istnieje lub uwierzytelniony użytkownik nie ma uprawnień, aby zobaczyć, że istnieje.
409	Występuje konflikt między żądaniem a stanem danych na serwerze. Jeśli na przykład próbujesz przesłać żądanie ściągnięcia (ang. pull request) i istnieje już żądanie ściągnięcia dla commitów, kod odpowiedzi to 409.

Usługa Azure DevOps Services obsługuje mechanizm CORS, który umożliwia obsługę kodu JavaScript z domeny innej niż dev.azure.com/*, aby wysyłać żądania Ajax do interfejsów API REST usługi Azure DevOps Services. Każde żądanie musi zawierać poświadczenia (tokeny PAT i tokeny dostępu OAuth są obsługiwanymi opcjami). Przykład:

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

Zastąp myPatToken PAT.

Wersjonowanie

Interfejsy API REST usługi Azure DevOps są wersjonowane, aby zapewnić, że aplikacje i usługi będą nadal działać w miarę rozwoju interfejsów API.

Wytyczne

Określ wersję interfejsu API z każdym żądaniem (wymagane).
Formatuj wersje interfejsu API w następujący sposób: {major}.{minor}-{stage}.{resource-version}. Na przykład , 1.0, 1.1, 1.2-preview, 2.0.
Wskaż określoną wersję interfejsu API, gdy jest on w wersji zapoznawczej, używając następującego formatu wersji: 1.0-preview.1, 1.0-preview.2. Po wydaniu interfejsu API (np. w wersji 1.0) jego wersja zapoznawcza (1.0-preview) jest wycofywana i może zostać zdezaktywowana po upływie 12 tygodni.
Zaktualizuj do opublikowanej wersji interfejsu API. Po dezaktywacji interfejsu API w wersji zapoznawczej, żądania określające wersję -preview są odrzucane.

Użycie

Określ wersję interfejsu API w nagłówku żądania HTTP lub jako parametr zapytania adresu URL.

Nagłówek żądania HTTP:

Accept: application/json;api-version=1.0

Parametr zapytania:

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

Obsługiwane wersje

Aby uzyskać informacje na temat obsługiwanych wersji, zobacz wersjonowanie interfejsu API REST, Obsługiwane wersje.

Udostępnij za pośrednictwem

Rozpocznij pracę z interfejsami API REST

Azure DevOps Services

Azure DevOps Server

Odpowiedzi

Czasowniki HTTP

Nagłówki żądań i zawartość żądania

Zastępowanie metody HTTP

Kody odpowiedzi

Wersjonowanie

Wytyczne

Użycie

Obsługiwane wersje

Opinia

Dodatkowe zasoby

Udostępnij za pośrednictwem

Rozpocznij pracę z interfejsami API REST

Azure DevOps Services

Azure DevOps Server

Odpowiedzi

Czasowniki HTTP

Nagłówki żądań i zawartość żądania

Zastępowanie metody HTTP

Kody odpowiedzi

Współużytkowanie zasobów między źródłami (CORS)

Wersjonowanie

Wytyczne

Użycie

Obsługiwane wersje

Opinia

Dodatkowe zasoby