Azure DevOps Services REST-API-Referenz

Willkommen bei der Azure DevOps Services/Azure DevOps Server REST-API-Referenz.

REST-APIs (Representational State Transfer) sind Dienstendpunkte, die verschiedene HTTP-Vorgänge (Methoden) für den Zugriff auf Dienstressourcen zum Erstellen, Abrufen, Aktualisieren oder Löschen unterstützen. In diesem Artikel wird Folgendes beschrieben:

• Die grundlegenden Komponenten eines REST-API-Anforderungs-/Antwortpaars.
• Übersichten über das Erstellen und Senden einer REST-Anforderung und die Behandlung der Antwort.

Auf die meisten REST-APIs kann über unsere Clientbibliotheken zugegriffen werden, die verwendet werden können, um Ihren Clientcode erheblich zu vereinfachen.

Komponenten eines REST-API-Anforderungs-/Antwortpaars

Ein REST-API-Anforderung/Antwort-Paar kann in fünf Komponenten gegliedert werden:

1. Der Anforderungs-URI im folgenden Format: VERB https://{instance}[/{team-project}]/_apis[/{area}]/{resource}?api-version={version}

   • instance: Der Azure DevOps Services organization- oder TFS-Server, an den Sie die Anforderung senden. Sie sind wie folgt strukturiert:
     • Azure DevOps Services:dev.azure.com/{organization}
     • TFS: {server:port}/tfs/{collection} (Der Standardport ist 8080, und der Wert für die Sammlung sollte sein DefaultCollection , kann jedoch eine beliebige Sammlung sein)
   • Ressourcenpfad: Der Ressourcenpfad lautet wie folgt: _apis/{area}/{resource}. Beispiel: _apis/wit/workitems.
   • api-version: Jede API-Anforderung sollte eine API-Version enthalten, um zu vermeiden, dass Ihre App oder Ihr Dienst unterbrochen wird, wenn sich APIs weiterentwickeln. api-versionen haben das folgende Format: {major}.{minor}[-{stage}[.{resource-version}]], z. B.:
     • api-version=1.0
     • api-version=1.2-preview
     • api-version=2.0-preview.1

   Hinweis: Bereich und Teamprojekt sind je nach API-Anforderung optional. Sehen Sie sich unten die Versionszuordnungsmatrix für TFS zu REST-API an, um zu ermitteln, welche REST-API-Versionen für Ihre TFS-Version gelten.

2. Headerfelder für HTTP-Anforderungsnachrichten:

   • eine erforderliche HTTP-Methode (ebenfalls unter den Bezeichnungen „Vorgang“ oder „Verb“ bekannt), über die der Dienst erfährt, welchen Vorgangstyp Sie anfordern; Azure REST-APIs unterstützen GET-, HEAD-, PUT-, POST- und PATCH-Methoden.
   • Zusätzliche optionale Headerfelder, die für den angegebenen URI und HTTP-Methode erforderlich sind. Beispielsweise ein Autorisierungsheader, der ein Bearertoken mit Clientautorisierungsinformationen für die Anforderung bereitstellt.

3. Optionale Nachrichtentextfelder mit HTTP-Antworten zur Unterstützung des URI und des HTTP-Vorgangs. Beispielsweise enthalten POST-Vorgänge MIME-codierte Objekte, die als komplexe Parameter übergeben werden.

   • Bei POST- oder PUT-Vorgängen sollte der MIME-Codierungstyp für den Text auch im Anforderungsheader content-type angegeben werden. Einige Dienste verlangen die Verwendung eines MIME-Typs wie application/json.

4. Nachrichtenheaderfelder mit HTTP-Anworten:

   • Ein HTTP-Statuscode, der zwischen den Erfolgscodes 2xx und den Fehlercodes 4xx oder 5xx liegt. Stattdessen kann auch, wie in der API-Dokumentation angegeben, ein Statuscode zurückgegeben werden, der für einen Dienst definiert ist.
   • Zusätzliche optionale Headerfelder, die zum Unterstützen der Antwort der Anforderung erforderlich sind, z.B. ein Content-type-Antwortheader.

5. Optionale Nachrichtentextfelder mit HTTP-Antworten:

   • MIME-codierte Antwortobjekte können im HTTP-Antworttext zurückgegeben werden, z. B. eine Antwort von einer GET-Methode, die Daten zurückgibt. Für gewöhnlich werden diese Objekte in einem strukturierten Format wie JSON oder XML zurückgegeben, wie im Content-type-Antwortheader angegeben. Wenn Sie beispielsweise ein Zugriffstoken von Azure AD anfordern, wird es im Antworttext als access_token Element zurückgegeben, eines von mehreren Namen-Wert-paaren Objekten in einer Datensammlung. In diesem Beispiel ist auch ein Antwortheader von Content-Type: application/json enthalten.

Erstellen der Anforderung

Authenticate

Es gibt viele Möglichkeiten, Ihre Anwendung oder Ihren Dienst mit Azure DevOps Services oder TFS zu authentifizieren. Die folgende Tabelle ist eine hervorragende Möglichkeit, um zu entscheiden, welche Methode für Sie am besten geeignet ist:

Hinweis: Weitere Informationen zur Authentifizierung finden Sie auf unserer Authentifizierungsleitfadenseite.

Zusammenstellen der Anforderung

Azure DevOps Services

Für Azure DevOps Services ist dev.azure.com/{organization}instance , sodass das Muster wie folgt aussieht:

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

Hier erfahren Sie beispielsweise, wie Sie eine Liste von Teamprojekten in einem Azure DevOps Services organization abrufen.

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

Wenn Sie das persönliche Zugriffstoken über einen HTTP-Header bereitstellen möchten, müssen Sie es zuerst in eine Base64-Zeichenfolge konvertieren (das folgende Beispiel zeigt, wie Sie mithilfe von C# in Base64 konvertieren). (Bestimmte Tools wie Postman wendet standardmäßig eine Base64-Codierung an. Wenn Sie die API mit solchen Tools versuchen, ist keine Base64-Codierung des PAT erforderlich. Die resultierende Zeichenfolge kann dann als HTTP-Header im Format bereitgestellt werden:

Authorization: Basic BASE64PATSTRING

Hier befindet er sich in C# mit der [HttpClient-Klasse](/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());
	}
}

Die meisten Beispiele auf dieser Website verwenden persönliche Zugriffstoken, da sie ein kompaktes Beispiel für die Authentifizierung beim Dienst sind. Es gibt jedoch eine Vielzahl von Authentifizierungsmechanismen für Azure DevOps Services einschließlich MSAL, OAuth und Sitzungstoken. Im Abschnitt Authentifizierung finden Sie eine Anleitung, welche für Ihr Szenario am besten geeignet ist.

TFS

Für TFS instance ist {server:port}/tfs/{collection} , und standardmäßig ist der Port 8080. Die Standardauflistung ist DefaultCollection, kann jedoch eine beliebige Sammlung sein.

Hier erfahren Sie, wie Sie mithilfe des Standardports und der Standardsammlung eine Liste von Teamprojekten aus TFS abrufen.

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

In den obigen Beispielen werden persönliche Zugriffstoken verwendet, sodass Sie ein persönliches Zugriffstoken erstellen müssen.

Verarbeiten der Antwort

Sie sollten eine Antwort wie diese erhalten.

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

Die Antwort lautet JSON. Dies ist im Allgemeinen, was Sie von den REST-APIs erhalten, obwohl es einige Ausnahmen gibt, z. B. Git-Blobs.

Jetzt sollten Sie sich in den spezifischen API-Bereichen wie Arbeitselementnachverfolgung oder Git umsehen und die benötigten Ressourcen abrufen können. Lesen Sie weiter, um mehr über die allgemeinen Muster zu erfahren, die in diesen APIs verwendet werden.

API- und TFS-Versionszuordnung

Nachfolgend finden Sie eine schnelle Zuordnung der REST-API-Versionen und der entsprechenden TFS-Versionen. Alle API-Versionen funktionieren sowohl auf der erwähnten Serverversion als auch in späteren Versionen.

Verwandte Inhalte

Sehen Sie sich die Dokumentation zur Integration von REST-API-Beispielen und Anwendungsfällen an.

• Leitfaden zur Authentifizierung
• Beispiele

Clientbibliotheken

Ermitteln Sie die Clientbibliotheken für diese REST-APIs.

• Konzeptionelle .NET-Dokumentation und .NET-Referenzdokumentation
• Go
• Node.js
• Python
• Swagger 2.0
• Weberweiterungs-SDK

Wo befinden sich die früheren Versionen von REST-APIs? (Vor 4.1)

Wir haben kürzlich eine Änderung an unserem Entwicklungssystem- und Dokumentationsprozess vorgenommen; wir haben diese Änderung vorgenommen, um eine klarere, ausführlichere und genauere Dokumentation für alle Benutzer bereitzustellen, die versuchen, diese REST-APIs zu verwenden. Aufgrund technischer Einschränkungen können wir die API-Version 4.1 und höher nur mit dieser Methode dokumentieren. Wir glauben, dass die Dokumentation für API-Version 4.1 und höher aufgrund dieser Änderung einfacher zu verwenden ist.

Wenn Sie in TFS arbeiten oder nach den älteren Versionen von REST-APIs suchen, können Sie sich die ÜBERSICHT ÜBER DIE REST-API für TFS 2015, 2017 und 2018 ansehen.