Referenční informace k rozhraní AZURE DEVOPS SERVICES REST API

Vítá vás referenční informace k rozhraní REST API Azure DevOps Services/Azure DevOps Server.

Rozhraní REST (Representational State Transfer) API jsou koncové body služby, které podporují sady operací (metod) HTTP, které poskytují přístup k prostředkům služby za účelem jejich vytvoření, načtení, aktualizace nebo odstranění. Tento článek vás provede:

• Základní komponenty dvojice požadavků a odpovědí rozhraní REST API
• Přehled vytvoření a odeslání požadavku REST a zpracování odpovědi

Většina rozhraní REST API je přístupná prostřednictvím našich klientských knihoven, které se dají výrazně zjednodušit klientský kód.

Komponenty dvojice požadavků a odpovědí rozhraní REST API

Dvojici žádost-odpověď rozhraní REST API je možné rozdělit na pět součástí:

1. Identifikátor URI požadavku v následující podobě: VERB https://{instance}[/{team-project}]/_apis[/{area}]/{resource}?api-version={version}

   • instance: Azure DevOps Services organizace nebo server TFS, na který požadavek odesíláte. Jsou strukturovány takto:
     • Azure DevOps Services:dev.azure.com/{organization}
     • TFS: {server:port}/tfs/{collection} (výchozí port je 8080 a hodnota kolekce by měla být DefaultCollection , ale může to být libovolná kolekce)
   • cesta k prostředku: Cesta k prostředku je následující: _apis/{area}/{resource}. Příklad: _apis/wit/workitems.
   • api-version: Každý požadavek rozhraní API by měl obsahovat verzi rozhraní API, aby se při vývoji rozhraní API zabránilo přerušení vaší aplikace nebo služby. api-versions jsou v následujícím formátu: {major}.{minor}[-{stage}[.{resource-version}]], například:
     • api-version=1.0
     • api-version=1.2-preview
     • api-version=2.0-preview.1

   Poznámka: Oblast a týmový projekt jsou volitelné v závislosti na požadavku rozhraní API. Podívejte se na následující matici mapování verzí rozhraní TFS na rozhraní REST API a zjistěte, které verze rozhraní REST API platí pro vaši verzi TFS.

2. Pole hlaviček zprávy požadavku HTTP:

   • Povinná metoda HTTP (také se jí říká operace), která službě řekne, který typ operace požadujete. Rozhraní Azure REST API podporují metody GET, HEAD, PUT, POST a PATCH.
   • Volitelná další pole hlavičky podle toho, jak je požaduje zadaný identifikátor URI a metoda HTTP. Například autorizační hlavička, která poskytuje nosný token obsahující informace o autorizaci klienta pro požadavek.

3. Volitelná pole hlavní části žádosti HTTP pro podporu identifikátoru URI a operace HTTP. Operace POST například obsahují objekty kódované pomocí MIME, které se předávají jako složité parametry.

   • U operací POST nebo PUT by měl být v hlavičce požadavku content-type také zadán typ kódování MIME pro text. Některé služby vyžadují, abyste použili konkrétní typ MIME, například application/json.

4. Pole hlavičky odpovědi HTTP:

   • Kód stavu HTTP v rozsahu od kódů úspěchu 2xx po chybové kódy 4xx a 5xx. Může se také vrátit kód stavu definovaný službou, jak je uvedeno v dokumentaci k rozhraní API.
   • Volitelná další pole hlavičky, která jsou potřeba pro podporu odpovědi na žádosti, například hlavička odpovědi Content-type.

5. Volitelná pole hlavní části odpovědi HTTP:

   • Objekty odpovědi kódované MIME mohou být vráceny v textu odpovědi HTTP, například odpověď z metody GET, která vrací data. Tyto objekty se obvykle vrací ve strukturovaném formátu, jako je JSON nebo XML, jak uvádí hlavička odpovědi Content-type. Když například požádáte o přístupový token od Azure AD, vrátí se v textu odpovědi jako access_token element, jeden z několika objektů spárovaných název/hodnota v kolekci dat. V tomto příkladu je zahrnuta také hlavička Content-Type: application/json odpovědi.

Vytvoření požadavku

Ověření

Existuje mnoho způsobů, jak ověřit aplikaci nebo službu pomocí Azure DevOps Services nebo TFS. Následující tabulka představuje vynikající způsob, jak se rozhodnout, která metoda je pro vás nejvhodnější:

Typ aplikace	Description	příklad	Mechanismus ověřování	Ukázky kódů
Interaktivní na straně klienta	Klientská aplikace, která umožňuje interakci uživatele, volání Azure DevOps Services rozhraní REST API	Konzolová aplikace s výčtem projektů v organizaci	Microsoft Authentication Library (MSAL)	Ukázka
Interaktivní JavaScript	JavaScriptová aplikace založená na grafickém uživatelském rozhraní	Jednostránková aplikace AngularJS zobrazující informace o projektu pro uživatele	MSAL	Ukázka
Neinteraktivní na straně klienta	Aplikace na straně klienta pouze pro bezobsávný text	Konzolová aplikace zobrazující všechny chyby přiřazené uživateli	Profil zařízení	Ukázka
Interaktivní web	Webová aplikace založená na grafickém uživatelském rozhraní	Vlastní webový řídicí panel zobrazující souhrny sestavení	OAuth	Ukázka
Aplikace TFS	Aplikace TFS s využitím klientské knihovny OM	Rozšíření TFS zobrazující řídicí panely chyb týmu	Klientské knihovny	Ukázka
rozšíření Azure DevOps Services	Azure DevOps Services rozšíření	Ukázky rozšíření Azure DevOps	VSS Web Extension SDK	Ukázkový názorný postup

Poznámka: Další informace o ověřování najdete na naší stránce s pokyny k ověřování.

Sestavení požadavku

Azure DevOps Services

Pro Azure DevOps Services je dev.azure.com/{organization}instance , takže vzor vypadá takto:

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

Tady je například postup, jak získat seznam týmových projektů v Azure DevOps Services organizaci.

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

Pokud chcete poskytnout token pro osobní přístup prostřednictvím hlavičky HTTP, musíte ho nejprve převést na řetězec Base64 (následující příklad ukazuje, jak převést na Base64 pomocí jazyka C#). (Některé nástroje, jako je Postman, ve výchozím nastavení použijí kódování Base64. Pokud zkoušíte rozhraní API prostřednictvím takových nástrojů, kódování PAT base64 není povinné). Výsledný řetězec pak může být poskytnut jako hlavička HTTP ve formátu:

Authorization: Basic BASE64PATSTRING

Tady je v jazyce C# pomocí třídy [HttpClient](/previous-versions/visualstudio/hh193681(v=vs.118).

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 = await client.GetAsync(
						"https://dev.azure.com/{organization}/_apis/projects"))
			{
				response.EnsureSuccessStatusCode();
				string responseBody = await response.Content.ReadAsStringAsync();
				Console.WriteLine(responseBody);
			}
		}
	}
	catch (Exception ex)
	{
		Console.WriteLine(ex.ToString());
	}
}

Většina ukázek na tomto webu používá osobní přístupové tokeny, protože představují kompaktní příklad ověřování ve službě. Pro Azure DevOps Services jsou však k dispozici různé mechanismy ověřování, včetně msal, OAuth a tokenů relací. Pokyny k tomu, které ověřování je pro váš scénář nejvhodnější, najdete v části Ověřování .

TFS

Pro TFS instance je {server:port}/tfs/{collection} a ve výchozím nastavení je port 8080. Výchozí kolekce je DefaultCollection, ale může to být libovolná kolekce.

Tady je postup, jak získat seznam týmových projektů z TFS pomocí výchozího portu a kolekce.

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

Výše uvedené příklady používají osobní přístupové tokeny, které vyžadují , abyste vytvořili token osobního přístupu.

Zpracování odpovědi

Měla by se zobrazit podobná odpověď.

{
    "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/DefaultCollection"
            },
            "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/DefaultCollection"
            },
            "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
}

Odpověď je JSON. To je obecně to, co získáte z rozhraní REST API, i když existuje několik výjimek, jako jsou objekty blob Git.

Teď byste se měli podívat na konkrétní oblasti rozhraní API, jako je sledování pracovních položek nebo Git , a dostat se k prostředkům, které potřebujete. Pokračujte ve čtení a získejte další informace o obecných vzorech používaných v těchto rozhraních API.

Mapování verzí rozhraní API a TFS

Níže najdete rychlé mapování verzí rozhraní REST API a jejich odpovídajících verzí TFS. Všechny verze rozhraní API budou fungovat na uvedené i novější verzi serveru.

Verze TFS	Verze rozhraní REST API	Verze sestavení
Azure DevOps Server vNext	7.1
Azure DevOps Server 2022	7,0	versions >= 19.205.33122.1
Azure DevOps Server 2020	6.0	versions >= 18.170.30525.1
Azure DevOps Server 2019	5.0	versions >= 17.143.28621.4
TFS 2018 Update 3	4.1	versions >= 16.131.28106.2
TFS 2018 Update 2	4.1	versions >= 16.131.27701.1
TFS 2018 Update 1	4,0	versions >= 16.122.27409.2
TFS 2018 RTW	4,0	versions >= 16.122.27102.1
TFS 2017 Update 2	3.2	versions >= 15.117.26714.0
TFS 2017 Update 1	3.1	versions >= 15.112.26301.0
TFS 2017 RTW	3.0	versions >= 15.105.25910.0
TFS 2015 Update 4	2.3	versions >= 14.114.26403.0
TFS 2015 Update 3	2.3	versions >= 14.102.25423.0
TFS 2015 Update 2	2,2	versions >= 14.95.25122.0
TFS 2015 Update 1	2.1	versions >= 14.0.24712.0
TFS 2015 RTW	2.0	versions >= 14.0.23128.0

Související obsah

Projděte si dokumentaci k integraci s ukázkami a případy použití rozhraní REST API.

• Doprovodné materiály k ověřování
• ukázky

Klientské knihovny

Zjistěte klientské knihovny pro tato rozhraní REST API.

• Koncepční dokumentace k .NET a referenční dokumentace k .NET
• Přejít
• Node.js
• Python
• Swagger 2.0
• Web Extensions SDK

Kde jsou starší verze rozhraní REST API? (Před 4.1)

Nedávno jsme provedli změnu našeho technického systému a procesu generování dokumentace. Tuto změnu jsme provedli, abychom všem uživatelům, kteří se snaží tato rozhraní REST API používat, poskytli jasnější, podrobnější a přesnější dokumentaci. Z důvodu technických omezení můžeme pomocí této metody dokumentovat pouze rozhraní API verze 4.1 a novější . Věříme, že dokumentace k rozhraní API verze 4.1 a novější bude díky této změně jednodušší.

Pokud pracujete v TFS nebo hledáte starší verze rozhraní REST API, můžete se podívat na přehled rozhraní REST API pro TFS 2015, 2017 a 2018.