Dela via

Kom igång med REST-API:erna

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

Azure DevOps REST-API:er ger kraftfull programmatisk åtkomst till arbetsobjekt, lagringsplatser, byggen, versioner med mera. Oavsett om du skapar anpassade integreringar, automatiserar arbetsflöden eller utökar Azure DevOps-funktioner är det viktigt att förstå de grundläggande mönstren och begreppen för en lyckad implementering.

Tips/Råd

Är du redo att börja koda? Hoppa till REST API-exempel för fullständiga arbetsexempel med moderna autentiseringsmönster.

Den här artikeln beskriver de grundläggande begreppen och mönstren för Rest-API:er för Azure DevOps. Praktiska implementeringsexempel finns i REST API-exempel.

URL-struktur

API:erna följer ett vanligt mönster, som du ser i följande exempel:

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

Tips/Råd

När API:erna utvecklas rekommenderar vi att du inkluderar en API-version i varje begäran. Den här metoden kan hjälpa dig att undvika oväntade ändringar i API:et som kan brytas.

Azure DevOps Services

För Azure DevOps Services instance är dev.azure.com/{organization} och collection är DefaultCollection, så mönstret ser ut som i följande exempel:

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

Exempelslutpunkt:

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

Azure DevOps Server

För Azure DevOps Server instance är {server:port}. Standardporten för en icke-SSL-anslutning är 8080.

Standardsamlingen är DefaultCollection, men du kan använda valfri samling.

Exempel:

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

Autentisering

Azure DevOps REST-API:er stöder flera autentiseringsmetoder:

  • Microsoft Entra-ID – rekommenderas för produktionsprogram
  • Personliga åtkomsttoken (PAT) – Enkel autentisering för skript och testning
  • OAuth 2.0 – För program som inte kommer från Microsoft
  • Tjänstens huvudnamn – För automatiserade scenarier

Viktigt!

Microsoft Entra ID-autentisering är den rekommenderade metoden för produktionsprogram. Implementeringsexempel och fullständig autentiseringsvägledning finns i REST API-exempel och autentiseringsvägledning.

Svarsformat

Azure DevOps REST-API:er returnerar vanligtvis JSON-svar. Här är ett exempel på svarsstruktur:

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

Svaret är JSON, vilket vanligtvis är vad du får tillbaka från REST-API:erna, även om det finns några undantag, till exempel Git-blobar.

Tips/Råd

Fullständiga arbetsexempel som visar hur du parsar dessa svar finns i REST API-exempel.

HTTP-metoder och -åtgärder

Azure DevOps REST-API:er använder http-standardmetoder:

Metod Används för... Exempel
GET Hämta en resurs eller lista över resurser Hämta projekt, arbetsobjekt
Posten Skapa en resurs eller hämta resurser med hjälp av avancerade frågor Skapa arbetsobjekt, fråga efter arbetsobjekt
LÄGG Skapa eller helt ersätta en resurs Skapa/uppdatera arbetsobjekt
Patch Uppdatera specifika fält för en resurs Uppdatera arbetsobjektfält
TA BORT Ta bort en resurs Ta bort arbetsobjekt

Tips/Råd

Praktiska exempel på varje HTTP-metod med fullständiga kodexempel finns i REST API-exempel.

Begäranhuvuden och innehåll

När du anger en begärandetext (vanligtvis med POST, PUT och PATCH) innehåller du lämpliga rubriker:

Content-Type: application/json

För PATCH-åtgärder för arbetsobjekt använder du:

Content-Type: application/json-patch+json

Åsidosättning av HTTP-metod

Vissa webbproxyservrar kanske bara stöder HTTP-verben GET och POST, men inte modernare HTTP-verb som PATCH och DELETE. Om dina anrop kan passera genom någon av dessa proxyservrar kan du skicka det faktiska verbet med hjälp av en POST-metod med en rubrik för att åsidosätta metoden. Du kanske till exempel vill uppdatera ett arbetsobjekt (PATCH _apis/wit/workitems/3), men du kan behöva gå igenom en proxy som endast tillåter GET eller POST. Du kan skicka rätt verb (PATCH i det här fallet) som en HTTP-begärandehuvudparameter och använda POST som den faktiska HTTP-metoden.

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

X-HTTP-Method-Override: PATCH

{
   (PATCH request body)
}

Svarskoder

Genom att förstå HTTP-svarskoder kan du hantera API-svar på rätt sätt:

Svar Innebörd Noteringar
200 Framgång Svarstexten innehåller begärda data
201 Skapades Resursen har skapats
204 Framgång Inget svarstext (vanligt med DELETE)
400 Felaktig förfrågan Ogiltiga parametrar eller begärandetext
401 Otillåten Autentiseringen misslyckades eller saknas
403 Ej tillåtet Användaren saknar behörighet för åtgärd
404 Hittades inte Resursen finns inte eller ingen behörighet att visa
409 Konflikt Begäran står i konflikt med aktuellt resurstillstånd

API-versionshantering

Azure DevOps REST-API:er är versionshanterade för att säkerställa att programmen fortsätter att fungera när API:erna utvecklas.

Riktlinjer

  • Ange alltid API-versionen med varje begäran (krävs)
  • Formatera API-versioner som: {major}.{minor} eller {major}.{minor}-{stage} (till exempel 7.2, 7.2-preview)
  • Använd specifika förhandsversioner när det är tillgängligt: 7.2-preview.1, 7.2-preview.2
  • Uppgradera till utgivna versioner när förhandsversions-API:er är inaktuella

Användning

Ange API-versionen som en URL-frågeparameter:

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

Eller i begärandehuvudet:

Accept: application/json;api-version=7.2

För versioner som stöds, se REST API-versionshantering.

Fler resurser

Praktisk implementeringsvägledning och fullständiga kodexempel finns i:

Nästa steg

Prova REST API-exempel