Share via

Začínáme s rozhraními REST API

  • Článek

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

Integrujte aplikaci s Azure DevOps pomocí rozhraní REST API uvedených v tomto článku.

Rozhraní API se řídí běžným vzorem, jako je následující příklad.

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

Tip

S vývojem rozhraní API doporučujeme do každého požadavku zahrnout verzi rozhraní API. Tento postup vám pomůže vyhnout se neočekávaným změnám v rozhraní API, které by mohly narušit.

Služby Azure DevOps

Pro Azure DevOps Services je dev.azure.com/{organization} a collection je DefaultCollection, instance takže vzor vypadá jako v následujícím příkladu.

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

Následující příklad ukazuje, jak získat seznam projektů v organizaci.

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

Pokud chcete poskytnout token PAT 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#. Výsledný řetězec je pak možné zadat jako hlavičku HTTP ve formátu.

Authorization: Basic BASE64PATSTRING

Následující příklad ukazuje jazyk C# pomocí třídy 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());
	}
}

Většina našich ukázek používá paty, protože představují kompaktní příklad pro ověřování ve službě. Existují však různé mechanismy ověřování pro Azure DevOps Services, včetně knihovny Microsoft Authentication Library (MSAL), OAuth a tokenů relací. Další informace najdete v doprovodných materiálech k ověřování, které vám pomůžou určit, která z nich je pro váš scénář nejvhodnější.

Azure DevOps Server

Pro Azure DevOps Server instance je {server:port}. Výchozí port pro připojení bez SSL je 8080.

Výchozí kolekce je DefaultCollection, ale můžete použít libovolnou kolekci.

Tady je postup, jak získat seznam projektů z Azure DevOps Serveru pomocí výchozího portu a kolekce napříč protokolem SSL:

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

Pokud chcete získat stejný seznam napříč připojením bez SSL:

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

Tyto příklady používají paty, které vyžadují vytvoření pat.

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

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

Teď se můžete podívat na konkrétní oblasti rozhraní API, jako je sledování pracovních položek nebo Git , a dostat se k potřebným prostředkům. Pokračujte ve čtení a seznamte se s obecnými vzory, které se v těchto rozhraních API používají.

Příkazy HTTP

Verb (Příkaz) Používá se pro...
GET Získání prostředku nebo seznamu prostředků
POST Vytvoření prostředku, získání seznamu prostředků pomocí pokročilejšího dotazu
PUT Vytvořte prostředek, pokud neexistuje nebo pokud ano, aktualizujte ho.
PATCH Aktualizace prostředku
DELETE Odstranění prostředku

Hlavičky požadavků a obsah požadavku

Když zadáte text požadavku (obvykle s příkazy POST, PUT a PATCH), zahrňte hlavičky požadavku, které popisují text. Příklad:

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

Content-Type: application/json

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

Přepsání metody HTTP

Některé webové proxy servery můžou podporovat pouze příkazy HTTP GET a POST, ale ne modernější příkazy HTTP, jako jsou PATCH a DELETE. Pokud vaše volání mohou projít jedním z těchto proxy serverů, můžete odeslat skutečné sloveso pomocí metody POST s hlavičkou, která přepíše metodu. Můžete například chtít aktualizovat pracovní položku (PATCH _apis/wit/workitems/3), ale možná budete muset projít proxy serverem, který povoluje pouze funkci GET nebo POST. Jako parametr hlavičky požadavku HTTP můžete předat správné sloveso (PATCH v tomto případě) a jako skutečnou metodu HTTP použít POST.

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

X-HTTP-Method-Override: PATCH

{
   (PATCH request body)
}

Kódy odpovědí

Response Notes
200 Úspěch a existuje tělo odpovědi.
201 Úspěch při vytváření prostředků Některá rozhraní API při úspěšném vytvoření prostředku vrátí hodnotu 200. Projděte si dokumentaci k rozhraní API, které používáte, abyste měli jistotu.
204 Úspěch a neexistuje žádný text odpovědi. Tato odpověď se například zobrazí při odstranění prostředku.
400 Parametry v adrese URL nebo v textu požadavku nejsou platné.
401 Ověření se nezdařilo. Tato odpověď je často způsobená chybějícím nebo poškozeným hlavičkou autorizace.
403 Ověřený uživatel nemá oprávnění k provedení operace.
404 Prostředek neexistuje nebo ověřený uživatel nemá oprávnění k jeho zobrazení.
409 Došlo ke konfliktu mezi požadavkem a stavem dat na serveru. Pokud se například pokusíte odeslat žádost o přijetí změn a pro potvrzení už existuje žádost o přijetí změn, kód odpovědi je 409.

Sdílení prostředků mezi zdroji (CORS)

Azure DevOps Services podporuje CORS, což umožňuje kód JavaScriptu obsluhované z jiné domény, než dev.azure.com/* provádět požadavky Ajax na rozhraní REST API služby Azure DevOps Services. Každý požadavek musí poskytovat přihlašovací údaje (PAT a přístupové tokeny OAuth jsou podporované obě možnosti). Příklad:

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

(nahrazení myPatToken osobním přístupovým tokenem)

Vytváření verzí

Rozhraní REST API Azure DevOps jsou verze, aby zajistily, že aplikace a služby budou dál fungovat při vývoji rozhraní API.

Pokyny

  • Zadejte verzi rozhraní API s každým požadavkem (povinné).
  • Formátovat verze rozhraní API následujícím způsobem: {major}. {minor}-{stage}. {resource-version}. Například , 1.0, 1.11.2-preview, 2.0.
  • Zadejte konkrétní revizi rozhraní API, když je ve verzi Preview, pomocí následujícího formátu verze: 1.0-preview.1, 1.0-preview.2. Po vydání rozhraní API (například 1.0) je jeho verze Preview (1.0-preview) zastaralá a po 12 týdnech se dá deaktivovat.
  • Upgradujte na vydanou verzi rozhraní API. Jakmile se deaktivuje rozhraní API verze Preview, požadavky, které určují -preview verzi, se zamítnou.

Využití

Zadejte verzi rozhraní API v hlavičce požadavku HTTP nebo jako parametr dotazu adresy URL.

Hlavička požadavku HTTP:

Accept: application/json;api-version=1.0

Parametr dotazu:

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

Podporované verze

Informace o podporovanýchverzích