Kom igång med REST-API:erna

  • Artikel

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

Integrera din app med Azure DevOps med hjälp av REST-API:erna i den här artikeln.

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

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

Dricks

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å ser mönstret ut som i följande exempel.

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

I följande exempel visas hur du hämtar en lista över projekt i en organisation.

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

Om du vill ange en personlig åtkomsttoken (PAT) via ett HTTP-huvud måste du först konvertera den till en Base64-sträng. I följande exempel visas hur du konverterar till Base64 med C#. Den resulterande strängen kan sedan anges som en HTTP-rubrik i formatet.

Authorization: Basic BASE64PATSTRING

I följande exempel visas C# med klassen HttpClient.

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

De flesta av våra exempel använder PAT eftersom de är ett kompakt exempel för autentisering med tjänsten. Det finns dock olika autentiseringsmekanismer för Azure DevOps Services, inklusive Microsoft Authentication Library (MSAL), OAuth och Sessionstoken. Mer information finns i Autentiseringsvägledning som hjälper dig att avgöra vilken som passar bäst för ditt scenario.

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.

Så här hämtar du en lista över projekt från Azure DevOps Server med standardporten och samlingen i SSL:

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

Så här hämtar du samma lista över en icke-SSL-anslutning:

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

I de här exemplen används PAT:er, vilket kräver att du skapar en PAT.

Svar

Du bör få ett svar som det här.

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

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.

Nu kan du titta runt de specifika API-områdena som spårning av arbetsobjekt eller Git och komma till de resurser som du behöver. Fortsätt läsa om du vill veta mer om de allmänna mönster som används i dessa API:er.

HTTP-verb

Verb Används för...
GET Hämta en resurs eller lista över resurser
POST Skapa en resurs, Hämta en lista över resurser med hjälp av en mer avancerad fråga
PUT Skapa en resurs om den inte finns eller, om den gör det, uppdatera den
PATCH Uppdatera en resurs
DELETE Ta bort en resurs

Begära rubriker och begära innehåll

När du anger begärandetext (vanligtvis med POST-, PUT- och PATCH-verben) inkluderar du begäranderubriker som beskriver brödtexten. Exempel:

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

Content-Type: application/json

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

Å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

Response Kommentar
200 Framgång, och det finns en svarstext.
201 Lyckades när du skapade resurser. Vissa API:er returnerar 200 när en resurs skapas. Titta på dokumenten för api:et som du använder för att vara säker.
204 Lyckades och det finns ingen svarstext. Du får till exempel det här svaret när du tar bort en resurs.
400 Parametrarna i URL:en eller i begärandetexten är inte giltiga.
401 Autentiseringen misslyckades. Ofta beror det här svaret på ett saknat eller felaktigt auktoriseringshuvud.
403 Den autentiserade användaren har inte behörighet att utföra åtgärden.
404 Resursen finns inte eller så har den autentiserade användaren inte behörighet att se att den finns.
409 Det finns en konflikt mellan begäran och tillståndet för data på servern. Om du till exempel försöker skicka en pull-begäran och det redan finns en pull-begäran för incheckningarna är svarskoden 409.

Resursdelning för korsande ursprung (CORS)

Azure DevOps Services stöder CORS, som gör det möjligt för JavaScript-kod som hanteras från en annan domän än dev.azure.com/* att göra Ajax-begäranden till Rest-API:er för Azure DevOps Services. Varje begäran måste ange autentiseringsuppgifter (PAT och OAuth-åtkomsttoken stöds båda alternativen). Exempel:

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

(ersätt myPatToken med en personlig åtkomsttoken)

Versionshantering

Azure DevOps REST-API:er är versionshanterade för att säkerställa att program och tjänster fortsätter att fungera när API:er utvecklas.

Riktlinjer

  • Ange API-versionen med varje begäran (krävs).
  • Formatera API-versioner på följande sätt: {major}. {minor}-{stage}. {resource-version}. Till exempel 1.0, 1.1, 1.2-preview, 2.0.
  • Ange en viss revision av API:et när det är i förhandsversion med hjälp av följande versionsformat: 1.0-preview.1, 1.0-preview.2. När ett API har släppts (till exempel 1.0), blir dess förhandsversion (1.0-förhandsversion) inaktuell och kan inaktiveras efter 12 veckor.
  • Uppgradera till den utgivna versionen av API:et. När ett förhandsversions-API har inaktiverats avvisas begäranden som anger -preview version.

Användning

Ange API-versionen i rubriken för HTTP-begäran eller som en URL-frågeparameter.

HTTP-begärandehuvud:

Accept: application/json;api-version=1.0

Frågeparameter:

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

Versioner som stöds

Information om versioner som stöds finns i REST API-versionshantering, versioner som stöds.