Erste Schritte mit den REST-APIs

  • Artikel

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

Integrieren Sie Ihre App mit Azure DevOps mithilfe der REST-APIs, die in diesem Artikel bereitgestellt werden.

Die APIs folgen einem allgemeinen Muster, z. B. dem folgenden Beispiel.

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

Tipp

Während sich APIs entwickeln, empfehlen wir, eine API-Version in jede Anforderung aufzunehmen. Diese Übung kann Ihnen helfen, unerwartete Änderungen in der API zu vermeiden, die nicht mehr ausgeführt werden können.

Azure DevOps Services

Für Azure DevOps Services instance lautet dev.azure.com/{organization} und collection ist DefaultCollectiondas Muster wie im folgenden Beispiel dargestellt.

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

Das folgende Beispiel zeigt, wie Sie eine Liste von Projekten in einer Organisation abrufen.

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

Wenn Sie das persönliche Zugriffstoken (PAT) über einen HTTP-Header bereitstellen möchten, müssen Sie es zuerst in eine Base64-Zeichenfolge konvertieren. Das folgende Beispiel zeigt, wie Sie mit C# in Base64 konvertieren. Die resultierende Zeichenfolge kann dann als HTTP-Header im Format bereitgestellt werden.

Authorization: Basic BASE64PATSTRING

Das folgende Beispiel zeigt C# mit der HttpClient-Klasse.

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

Die meisten unserer Beispiele verwenden PATs, da sie ein kompaktes Beispiel für die Authentifizierung mit dem Dienst sind. Es gibt jedoch verschiedene Authentifizierungsmechanismen für Azure DevOps Services, einschließlich Microsoft Authentication Library (MSAL), OAuth und Sitzungstoken. Weitere Informationen finden Sie unter Authentifizierungsleitfaden, um zu ermitteln, welcher für Ihr Szenario am besten geeignet ist.

Azure DevOps Server

Für Azure DevOps Server instance ist {server:port}. Der Standardport für eine nicht-SSL-Verbindung ist 8080.

Die Standardauflistung ist DefaultCollection, Aber Sie können jede Sammlung verwenden.

Hier erfahren Sie, wie Sie eine Liste von Projekten von Azure DevOps Server mithilfe des Standardports und der Sammlung über SSL abrufen:

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

So rufen Sie dieselbe Liste über eine nicht-SSL-Verbindung hinweg ab:

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

In diesen Beispielen werden PATs verwendet, die erfordern, dass Sie einen PAT erstellen.

Antworten

Sie sollten eine Antwort wie folgt 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"
            },
            "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
}

Die Antwort ist JSON, was sie in der Regel von den REST-APIs zurückholen, obwohl es einige Ausnahmen gibt, wie Git-Blobs.

Jetzt können Sie sich die spezifischen API-Bereiche wie die Nachverfolgung von Arbeitsaufgaben oder Git ansehen und zu den benötigten Ressourcen gelangen. Lesen Sie weiter, um mehr über die allgemeinen Muster zu erfahren, die in diesen APIs verwendet werden.

HTTP-Verben

Verb Wird für...
GET Abrufen einer Ressource oder Liste von Ressourcen
NACHRICHT Erstellen einer Ressource, Abrufen einer Liste von Ressourcen mithilfe einer erweiterten Abfrage
PUT Erstellen Sie eine Ressource, wenn sie nicht vorhanden ist, oder aktualisieren Sie sie, falls dies der Fall ist.
PATCH Aktualisieren einer Ressource
DELETE Eine Ressource löschen

Anforderungsheader und Anforderungsinhalte

Wenn Sie Den Anforderungstext (in der Regel mit den Verben POST, PUT und PATCH) bereitstellen, schließen Sie Anforderungsheader ein, die den Textkörper beschreiben. Beispiel:

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

Content-Type: application/json

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

Außerkraftsetzung der HTTP-Methode

Einige Webproxys unterstützen möglicherweise nur die HTTP-Verben GET und POST, aber nicht modernere HTTP-Verben wie PATCH und DELETE. Wenn Ihre Aufrufe möglicherweise eine dieser Proxys durchlaufen, können Sie das tatsächliche Verb mithilfe einer POST-Methode senden, mit einem Header, um die Methode außer Kraft zu setzen. Sie können z. B. eine Arbeitsaufgabe aktualisieren (PATCH _apis/wit/workitems/3), aber Möglicherweise müssen Sie einen Proxy durchlaufen, der nur GET oder POST zulässt. Sie können das richtige Verb (PATCH in diesem Fall) als HTTP-Anforderungsheaderparameter übergeben und POST als tatsächliche HTTP-Methode verwenden.

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

X-HTTP-Method-Override: PATCH

{
   (PATCH request body)
}

Antwortcodes

Antwort Hinweise
200 Erfolg, und es gibt einen Antworttext.
201 Erfolg beim Erstellen von Ressourcen. Einige APIs geben beim erfolgreichen Erstellen einer Ressource 200 zurück. Sehen Sie sich die Dokumente für die API an, die Sie verwenden, um sicher zu sein.
204 Erfolg, und es gibt keinen Antworttext. Sie erhalten diese Antwort beispielsweise, wenn Sie eine Ressource löschen.
400 Die Parameter in der URL oder im Anforderungstext sind ungültig.
401 Die Authentifizierung ist fehlgeschlagen. Häufig liegt diese Antwort an einem fehlenden oder falsch formatierten Autorisierungsheader.
403 Der authentifizierte Benutzer verfügt nicht über die Berechtigung zum Ausführen des Vorgangs.
404 Die Ressource ist nicht vorhanden, oder der authentifizierte Benutzer verfügt nicht über die Berechtigung, zu sehen, dass sie vorhanden ist.
409 Es gibt einen Konflikt zwischen der Anforderung und dem Status der Daten auf dem Server. Wenn Sie beispielsweise versuchen, eine Pull-Anforderung zu senden und bereits eine Pullanforderung für die Commits vorhanden ist, lautet der Antwortcode 409.

Ressourcenfreigabe zwischen verschiedenen Ursprüngen (Cross-Origin Resource Sharing, CORS)

Azure DevOps Services unterstützt CORS, wodurch JavaScript-Code, der von einer Do bereitgestellt wird Standard außer dev.azure.com/* Ajax-Anforderungen an Azure DevOps Services-REST-APIs zu senden. Jede Anforderung muss Anmeldeinformationen bereitstellen (PATs und OAuth-Zugriffstoken sind beide unterstützten Optionen). Beispiel:

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

(Ersetzen myPatToken durch ein persönliches Zugriffstoken)

Versionsverwaltung

Azure DevOps-REST-APIs sind versionsiert, um sicherzustellen, dass Anwendungen und Dienste weiterhin funktionieren, während APIs weiterentwickelt werden.

Richtlinien

  • Geben Sie die API-Version mit jeder Anforderung an (erforderlich).
  • Formatieren Sie API-Versionen wie folgt: {major}. {minor}-{stage}. {resource-version}. Beispiel: 1.0, 1.1, 1.2-preview, 2.0.
  • Geben Sie eine bestimmte Überarbeitung der API an, wenn sie sich in der Vorschau befindet, mithilfe des folgenden Versionsformats: 1.0-preview.1, 1.0-preview.2. Sobald eine API veröffentlicht wurde (z. B. 1.0), ist die Vorschauversion (1.0-preview) veraltet und kann nach 12 Wochen deaktiviert werden.
  • Führen Sie ein Upgrade auf die veröffentlichte Version der API durch. Sobald eine Vorschau-API deaktiviert wurde, werden Anforderungen, die version angeben -preview , abgelehnt.

Verbrauch

Geben Sie die API-Version im Header der HTTP-Anforderung oder als URL-Abfrageparameter an.

HTTP-Anforderungsheader:

Accept: application/json;api-version=1.0

Abfrageparameter:

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

Unterstützte Versionen

Informationen zu unterstützten Versionen finden Sie unter REST-API-Versionsverwaltung, Unterstützte Versionen.