Share via

Wprowadzenie do interfejsów API REST

  • Artykuł

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.

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

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

Napiwek

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ą zostać przerwane.

Azure DevOps Services

W przypadku usługi Azure DevOps Services instance parametr to dev.azure.com/{organization} i collection to DefaultCollection, więc wzorzec wygląda podobnie do poniższego przykładu.

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, musisz najpierw przekonwertować 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());
	}
}

Większość naszych przykładów używa paTs, ponieważ jest to kompaktowy przykład uwierzytelniania w usłudze. Istnieją jednak różne mechanizmy uwierzytelniania dostępne dla usług Azure DevOps Services, w tym biblioteki Microsoft Authentication Library (MSAL), protokołu OAuth i tokenów sesji. Aby uzyskać więcej informacji, zobacz Wskazówki dotyczące uwierzytelniania, aby ułatwić określenie, który z nich najlepiej nadaje się do danego scenariusza.

Azure DevOps Server

W przypadku usługi Azure DevOps Server instance wartość to {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ę między połączeniem 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ą utworzenia tokenu dostępu.

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

Odpowiedź to JSON, czyli ogólnie to, co można odzyskać z interfejsów API REST, chociaż istnieje kilka wyjątków, takich jak obiekty blob usługi 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 Pobieranie zasobu lub listy zasobów
POST Tworzenie zasobu, uzyskiwanie listy zasobów przy użyciu bardziej zaawansowanego zapytania
ODŁÓŻ Utwórz zasób, jeśli nie istnieje lub, jeśli tak, zaktualizuj go
PATCH Aktualizowanie zasobu
DELETE 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ść. 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 polecenie GET lub POST. Możesz przekazać odpowiednie zlecenie (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

Response Uwagi
200 Powodzenie i istnieje treść odpowiedzi.
201 Powodzenie podczas tworzenia 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 nie ma 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 i istnieje już żądanie ściągnięcia dla zatwierdzeń, kod odpowiedzi to 409.

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

Usługa Azure DevOps Services obsługuje mechanizm CORS, który umożliwia obsługę kodu JavaScript z domeny innej niż dev.azure.com/* wykonywanie żądań Ajax do interfejsów API REST usługi Azure DevOps Services. Każde żądanie musi podać poświadczenia (pakiety PAT i tokeny dostępu OAuth są obie obsługiwane opcje). 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 ciąg osobistym tokenem dostępu)

Wersje

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.
  • Określ określoną poprawkę interfejsu API 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.
  • Uaktualnij do wydanej wersji interfejsu API. Po dezaktywowaniu interfejsu API w wersji zapoznawczej żądania określające -preview wersję 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 Obsługa wersji interfejsu API REST, Obsługiwane wersje.