Erste Schritte mit den REST-APIs

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

Azure DevOps-REST-APIs bieten leistungsstarken programmgesteuerten Zugriff auf Arbeitsaufgaben, Repositorys, Builds, Versionen und vieles mehr. Ganz gleich, ob Sie benutzerdefinierte Integrationen erstellen, Workflows automatisieren oder Azure DevOps-Funktionen erweitern - das Verständnis der grundlegenden Muster und Konzepte ist entscheidend für eine erfolgreiche Implementierung.

In diesem Artikel werden die grundlegenden Konzepte und Muster für Azure DevOps-REST-APIs behandelt. Praktische Implementierungsbeispiele finden Sie unter REST-API-Beispiele.

URL-Struktur

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

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

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}

Beispiel-Endpunkt:

GET https://dev.azure.com/{organization}/_apis/projects?api-version=7.2

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.

Beispiele:

• SSL: https://{server}/DefaultCollection/_apis/projects?api-version=7.2
• Nicht-SSL: http://{server}:8080/DefaultCollection/_apis/projects?api-version=7.2

Authentifizierung

Azure DevOps-REST-APIs unterstützen mehrere Authentifizierungsmethoden:

• Microsoft Entra-ID – Empfohlen für Produktionsanwendungen
• Persönliche Zugriffstoken (PATs) – Einfache Authentifizierung für Skripts und Tests
• OAuth 2.0 – Für Nicht-Microsoft-Anwendungen
• Service Principals – Für automatisierte Szenarien

Antwortformat

Azure DevOps-REST-APIs geben in der Regel JSON-Antworten zurück. Hier ist eine Beispielantwortstruktur:

{
    "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"
        }
    ],
    "count": 1
}

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

HTTP-Methoden und -Vorgänge

Azure DevOps-REST-APIs verwenden standardmäßige HTTP-Methoden:

Header und Inhalt von Anfragen

Wenn Sie einen Anforderungstext (in der Regel mit POST, PUT und PATCH) bereitstellen, fügen Sie entsprechende Header ein:

Content-Type: application/json

Verwenden Sie für PATCH-Operationen bei Arbeitselementen Folgendes:

Content-Type: application/json-patch+json

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

Das Verständnis von HTTP-Antwortcodes hilft Ihnen bei der richtigen Behandlung von API-Antworten:

API-Versionsverwaltung

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

Leitlinien

• Geben Sie immer die API-Version mit jeder Anforderung an (erforderlich)
• Formatieren von API-Versionen als: {major}.{minor} oder {major}.{minor}-{stage} (z. B 7.2. , 7.2-preview)
• Verwenden Sie bestimmte Vorschaurevisionen, wenn verfügbar: 7.2-preview.1, 7.2-preview.2
• Upgrade auf veröffentlichte Versionen, wenn Vorschau-APIs veraltet sind

Verwendung

Geben Sie die API-Version als URL-Abfrageparameter an:

GET https://dev.azure.com/{organization}/_apis/projects?api-version=7.2

Oder im Header der Anfrage:

Accept: application/json;api-version=7.2

Unterstützte Versionen finden Sie unter REST-API-Versionsverwaltung.

Weitere Ressourcen

Praktische Implementierungsanleitungen und vollständige Codebeispiele finden Sie unter:

• REST-API-Beispiele – Vollständige Beispiele mit der Microsoft Entra ID-Authentifizierung
• Authentifizierungsleitfaden – Detaillierte Authentifizierungsoptionen
• REST-API-Versionsverwaltung – API-Lebenszyklusinformationen
• OAuth 2.0 – Details zur OAuth-Implementierung

Nächste Schritte