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, es ist entscheidend, die grundlegenden Muster und Konzepte zu verstehen, die für eine erfolgreiche Implementierung unerlässlich sind.

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}

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

GET https://dev.azure.com/{organization}/_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": "Team Foundation Version Control projects"
        }
    ],
    "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 versionsgesichert, 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 Microsoft Entra ID Authentifizierung
• Authentifizierungsleitfaden – Detaillierte Authentifizierungsoptionen
• REST-API-Versionsverwaltung – API-Lebenszyklusinformationen
• OAuth 2.0 – Details zur OAuth-Implementierung

Verwenden von KI zum Erstellen von REST-API-Aufrufen

Wenn Sie den Azure DevOps MCP Server mit Ihrem KI-Agent im Agentmodus verbunden haben, können Sie Anweisungen in natürlicher Sprache verwenden, um REST-API-Aufrufe zu generieren und zu beheben.

Nächste Schritte