Freigeben über

Erste Schritte mit den REST-APIs

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

Integrieren Sie Ihre Anwendung mit Azure DevOps mithilfe der REST-APIs, die in diesem Artikel bereitgestellt werden. Diese APIs ermöglichen Es Ihnen, programmgesteuert mit den Diensten zu interagieren, sodass Sie Workflows automatisieren, in andere Systeme integrieren und die Funktionen von Azure DevOps erweitern können.

Die APIs folgen einem allgemeinen Muster, wie im folgenden Beispiel gezeigt:

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 zu Ausfällen führen könnten.

Azure DevOps Services

Bei Azure DevOps Services ist instancedev.azure.com/{organization} und collection ist DefaultCollection, sodass das Muster wie im folgenden Beispiel aussieht:

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 über einen HTTP-Header bereitstellen möchten, stellen Sie dem Token zuerst einen Doppelpunkt voran. Konvertieren Sie dann die Verkettung des Doppelpunkts und des PAT in eine Base64-Zeichenfolge. 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 BASE64COLONANDPATSTRING

Hinweis

Stellen Sie den Doppelpunkt vor das PAT, um Fehler bei der Authentifizierung zu vermeiden.

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

Wichtig

Während wir persönliche Zugriffstoken (PATs) in vielen Beispielen aus Gründen der Einfachheit verwenden, empfehlen wir nicht, sie in Produktionsanwendungen zu verwenden. Erwägen Sie stattdessen die Verwendung sichererer Authentifizierungsmechanismen. Weitere Informationen finden Sie unter Authentifizierungsleitfaden.

Azure DevOps Server

Wenn Sie Azure DevOps Server verwenden, ist instance {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

Es sollte eine Antwort ähnlich wie im folgenden Beispiel angezeigt werden:

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

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 Verwendet für ...
GET Abrufen einer Ressource oder Liste von Ressourcen
POST 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
Löschen Eine Ressource löschen

Header der Anfrage und Inhalt der Anfrage

Wenn Sie den Inhalt einer Anfrage bereitstellen (in der Regel mit den Verben POST, PUT und PATCH), fügen Sie die Header der Anfrage hinzu, die den Inhalt 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"
}

HTTP-Methode überschreiben

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 Antwort-Inhalt.
201 Erfolgreich, wenn Sie Ressourcen erstellen. 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 Erfolgreich, und es gibt keinen Antwort-Inhalt. Sie erhalten diese Antwort beispielsweise, wenn Sie eine Ressource löschen.
400 Die Parameter in der URL oder im Anforderungstext sind ungültig.
401 Fehler bei der Authentifizierung: 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 anderen Domäne als dev.azure.com/* bereitgestellt wird, Ajax-Anfragen an die REST-APIs von Azure DevOps Services durchführen kann. 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 Sie myPatToken durch einen PAT.

Versionsverwaltung

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

Leitlinien

  • 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 ist, werden Anforderungen, die eine Version vom Typ -preview angeben, abgelehnt.

Verwendung

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.