Dokumentacja interfejsu API REST Azure DevOps Services

  • Artykuł

Witamy w dokumentacji interfejsu API REST Azure DevOps Services/Azure DevOps Server.

Interfejsy API REST (Representational State Transfer) to punkty końcowe usługi obsługujące zestawy operacji (metod) HTTP, które umożliwiają tworzenie, pobieranie, aktualizowanie i usuwanie dostępu do zasobów usługi. Ten artykuł przeprowadzi Cię przez następujące kroki:

  • Podstawowe składniki pary żądań/odpowiedzi interfejsu API REST.
  • Omówienie tworzenia i wysyłania żądania REST oraz obsługi odpowiedzi.

Większość interfejsów API REST jest dostępna za pośrednictwem naszych bibliotek klienckich, których można użyć do znacznego uproszczenia kodu klienta.

Składniki pary żądań/odpowiedzi interfejsu API REST

W parze żądanie/odpowiedź interfejsu API REST można wyróżnić pięć składników:

  1. Identyfikator URI żądania w następującym formularzu: VERB https://{instance}[/{team-project}]/_apis[/{area}]/{resource}?api-version={version}

    • wystąpienie: Azure DevOps Services organizacji lub serwera TFS, do którego wysyłasz żądanie. Są one ustrukturyzowane w następujący sposób:
      • Azure DevOps Services:dev.azure.com/{organization}
      • TFS: {server:port}/tfs/{collection} (port domyślny to 8080, a wartość kolekcji powinna być DefaultCollection ale może być dowolna kolekcja)
    • ścieżka zasobu: Ścieżka zasobu jest następująca: _apis/{area}/{resource}. Na przykład: _apis/wit/workitems.
    • api-version: każde żądanie interfejsu API powinno zawierać wersję interfejsu API, aby uniknąć awarii aplikacji lub usługi w miarę rozwoju interfejsów API. Wersje interfejsu API są w następującym formacie: {major}.{minor}[-{stage}[.{resource-version}]], na przykład:
      • api-version=1.0
      • api-version=1.2-preview
      • api-version=2.0-preview.1

    Uwaga: obszar i projekt zespołowy są opcjonalne w zależności od żądania interfejsu API. Zapoznaj się z macierzą mapowania wersji interfejsu API REST tfS na interfejs API REST poniżej, aby dowiedzieć się, które wersje interfejsu API REST mają zastosowanie do używanej wersji serwera TFS.

  2. Pola nagłówka komunikatu żądania HTTP:

    • Wymagana metoda HTTP (znana także jako operacja lub polecenie), która informuje usługę o żądanym typie operacji. Interfejsy API REST platformy Azure obsługują metody GET, HEAD, PUT, POST i PATCH.
    • Opcjonalne dodatkowe pola nagłówka wymagane przez określony identyfikator URI i metodę HTTP. Na przykład nagłówek autoryzacji zawierający token elementu nośnego zawierający informacje o autoryzacji klienta dla żądania.

  3. Opcjonalne pola treści komunikatu żądania HTTP umożliwiające obsługę identyfikatora URI i działania protokołu HTTP. Na przykład operacje POST zawierają obiekty zakodowane w formacie MIME, które są przekazywane jako parametry złożone.

    • W przypadku operacji POST lub PUT typ kodowania MIME dla treści powinien być również określony w nagłówku żądania typu zawartości. Niektóre usługi wymagają użycia konkretnego typu MIME, takiego jak application/json.

  4. Pola nagłówka komunikatu odpowiedzi HTTP:

    • Kod stanu HTTP — od kodów 2xx oznaczających powodzenie do kodów błędów 4xx lub 5xx. Można także zwracać kod stanu zdefiniowany przez usługę zgodnie z informacjami podanymi w dokumentacji interfejsu API.
    • Opcjonalne dodatkowe pola nagłówka, wymagane do obsługi odpowiedzi na żądanie, takie jak nagłówek odpowiedzi Content-type.

  5. Opcjonalne pola treści komunikatu odpowiedzi HTTP:

    • Obiekty odpowiedzi zakodowane w formacie MIME mogą być zwracane w treści odpowiedzi HTTP, takie jak odpowiedź z metody GET, która zwraca dane. Zazwyczaj te obiekty są zwracane w formacie strukturalnym, takim jak JSON lub XML, zgodnie z nagłówkiem odpowiedzi Content-type. Na przykład, gdy zażądasz tokenu dostępu z Azure AD, zostanie zwrócony w treści odpowiedzi jako access_token element, jeden z kilku obiektów parowanych nazwa/wartość w kolekcji danych. W tym przykładzie dołączono również nagłówek Content-Type: application/json odpowiedzi.

Tworzenie żądania

Uwierzytelnianie

Istnieje wiele sposobów uwierzytelniania aplikacji lub usługi za pomocą Azure DevOps Services lub TFS. Poniższa tabela to doskonały sposób, aby zdecydować, która metoda jest najlepsza dla Ciebie:

Typ aplikacji Opis przykład Mechanizm uwierzytelniania Przykłady kodu
Interaktywna strona klienta Aplikacja kliencka, która umożliwia interakcję użytkownika, wywoływanie interfejsów API REST Azure DevOps Services Aplikacja konsolowa wyliczająca projekty w organizacji Biblioteka uwierzytelniania firmy Microsoft (MSAL) Przykładowe
Interaktywny kod JavaScript Aplikacja JavaScript oparta na graficznym interfejsie użytkownika Aplikacja jednostronicowa AngularJS wyświetlającą informacje o projekcie dla użytkownika BIBLIOTEKA MSAL Przykładowe
Strona klienta nieinterakcyjnego Bezgłowy tekst tylko po stronie aplikacji klienckiej Aplikacja konsolowa z wyświetlonymi wszystkimi usterkami przypisanymi do użytkownika Profil urządzenia Przykładowe
Interaktywna sieć Web Aplikacja internetowa oparta na graficznym interfejsie użytkownika Niestandardowy pulpit nawigacyjny sieci Web wyświetlający podsumowania kompilacji OAuth Przykładowe
Aplikacja TFS Aplikacja TFS korzystająca z biblioteki OM klienta Rozszerzenie TFS wyświetlające pulpity nawigacyjne błędów zespołu Biblioteki klienta Przykładowe
rozszerzenie Azure DevOps Services rozszerzenie Azure DevOps Services Przykłady rozszerzeń usługi Azure DevOps Zestaw SDK rozszerzenia sieci Web usługi VSS przewodnik po przykładzie

Uwaga: Więcej informacji na temat uwierzytelniania można znaleźć na naszej stronie wskazówek dotyczących uwierzytelniania.

Skompletuj żądanie

Usługa Azure DevOps Services

W przypadku Azure DevOps Services wystąpienie to dev.azure.com/{organization}, więc wzorzec wygląda następująco:

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

Na przykład poniżej przedstawiono sposób uzyskiwania listy projektów zespołowych w organizacji Azure DevOps Services.

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

Jeśli chcesz podać osobisty token dostępu za pośrednictwem nagłówka HTTP, musisz najpierw przekonwertować go na ciąg Base64 (w poniższym przykładzie pokazano, jak przekonwertować na base64 przy użyciu języka C#). (Niektóre narzędzia, takie jak Postman, domyślnie stosują kodowanie Base64. Jeśli próbujesz interfejsu API za pomocą takich narzędzi, kodowanie base64 pat nie jest wymagane) Wynikowy ciąg może zostać podany jako nagłówek HTTP w formacie:

Authorization: Basic BASE64PATSTRING

W tym miejscu znajduje się on w języku C# przy użyciu klasy [HttpClient](/previous-versions/visualstudio/hh193681(v=vs.118).

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

Większość przykładów w tej witrynie używa osobistych tokenów dostępu, ponieważ jest to kompaktowy przykład uwierzytelniania za pomocą usługi. Istnieją jednak różne mechanizmy uwierzytelniania dostępne dla Azure DevOps Services, w tym msAL, OAuth i tokeny sesji. Zapoznaj się z sekcją Uwierzytelnianie , aby uzyskać wskazówki, które najlepiej nadają się do danego scenariusza.

TFS

W przypadku serwera TFS port instance jest {server:port}/tfs/{collection} domyślnie portem 8080. Domyślna kolekcja to DefaultCollection, ale może być dowolną kolekcją.

Poniżej przedstawiono sposób uzyskiwania listy projektów zespołowych z serwera TFS przy użyciu domyślnego portu i kolekcji.

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

W powyższych przykładach są używane osobiste tokeny dostępu, które wymagają utworzenia osobistego tokenu dostępu.

Przetwarzanie odpowiedzi

Powinna zostać wyświetlona odpowiedź podobna do tej.

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

Odpowiedź to JSON. Ogólnie rzecz biorąc, możesz wrócić z interfejsów API REST, chociaż istnieje kilka wyjątków, takich jak obiekty blob usługi Git.

Teraz powinno być możliwe zapoznanie się z określonymi obszarami interfejsu API, takimi jak śledzenie elementów roboczych lub git , i uzyskiwanie potrzebnych zasobów. Przeczytaj, aby dowiedzieć się więcej na temat ogólnych wzorców używanych w tych interfejsach API.

Mapowanie wersji interfejsu API i serwera TFS

Poniżej znajdziesz szybkie mapowanie wersji interfejsu API REST i odpowiednich wersji serwera TFS. Wszystkie wersje interfejsu API będą działać na wymienionej wersji serwera, a także w nowszych wersjach.

Wersja serwera TFS Wersja interfejsu API REST Wersja kompilacji
Azure DevOps Server vNext 7.1
Azure DevOps Server 2022 r. 7.0 versions >= 19.205.33122.1
Azure DevOps Server 2020 r. 6.0 versions >= 18.170.30525.1
Azure DevOps Server 2019 r. 5.0 versions >= 17.143.28621.4
TFS 2018 Update 3 4.1 versions >= 16.131.28106.2
TFS 2018 Update 2 4.1 versions >= 16.131.27701.1
TFS 2018 Update 1 4,0 versions >= 16.122.27409.2
TFS 2018 RTW 4,0 versions >= 16.122.27102.1
TFS 2017 Update 2 3.2 versions >= 15.117.26714.0
TFS 2017 Update 1 3,1 versions >= 15.112.26301.0
TFS 2017 RTW 3.0 versions >= 15.105.25910.0
TFS 2015 Update 4 2.3 versions >= 14.114.26403.0
TFS 2015 Update 3 2.3 versions >= 14.102.25423.0
TFS 2015 Update 2 2,2 versions >= 14.95.25122.0
TFS 2015 Update 1 2.1 versions >= 14.0.24712.0
TFS 2015 RTW 2.0 versions >= 14.0.23128.0

Powiązana zawartość

Zapoznaj się z dokumentacją integrowania przykładów i przypadków użycia interfejsu API REST.

Biblioteki klienta

Odnajdź biblioteki klienta dla tych interfejsów API REST.

Gdzie znajdują się wcześniejsze wersje interfejsów API REST? (Przed 4.1)

Niedawno wprowadziliśmy zmianę naszego systemu inżynieryjnego i procesu generowania dokumentacji; Wprowadziliśmy tę zmianę, aby zapewnić jaśniejszą, bardziej szczegółową i dokładniejszą dokumentację dla wszystkich próbujących korzystać z tych interfejsów API REST. Ze względu na ograniczenia techniczne możemy dokumentować interfejs API w wersji 4.1 i nowszej przy użyciu tej metody. Uważamy, że dokumentacja interfejsu API w wersji 4.1 i nowszej będzie łatwiejsza w użyciu z powodu tej zmiany.

Jeśli pracujesz w programie TFS lub szukasz starszych wersji interfejsów API REST, możesz zapoznać się z omówieniem interfejsu API REST dla serwera TFS 2015, 2017 i 2018.