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

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

Azure DevOps rozhraní REST API poskytují výkonný programový přístup k pracovním položkám, úložištím, buildům, vydaným verzím a dalším funkcím. Ať už vytváříte vlastní integrace, automatizujete pracovní postupy nebo rozšiřujete možnosti Azure DevOps, pochopení základních vzorů a konceptů je nezbytné pro úspěšnou implementaci.

Návod

Jste připravení začít psát kód? Přeskočte na ukázky rozhraní REST API pro kompletní funkční příklady s moderními vzory ověřování.

Tento článek se zabývá základními koncepty a vzory pro Azure DevOps rozhraní REST API. Příklady praktické implementace najdete v ukázkách rozhraní REST API.

Návod

S touto úlohou můžete využít umělou inteligenci dále v tomto článku nebo si můžete projít Povolit asistenci umělé inteligence s Azure DevOps MCP Server začít.

Struktura adresy URL

Rozhraní API se řídí běžným vzorem, jak je znázorněno v následujícím příkladu:

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

Návod

Jak se rozhraní API vyvíjejí, zahrňte do každého požadavku 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 vaši aplikaci.

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

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

Příklad koncového bodu:

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

Autentizace

rozhraní REST API Azure DevOps podporují několik metod ověřování:

  • Microsoft Entra ID – doporučeno pro produkční aplikace
  • Osobní přístupové tokeny (PAT) – jednoduché ověřování pro skripty a testování
  • Instanční objekty a spravované identity – pro automatizované scénáře

Důležité

Zvažte použití bezpečnějších tokenů Microsoft Entra místo vysoce rizikových osobních přístupových tokenů. Další informace najdete v tématu Snížení využití PAT. Projděte si doprovodné materiály k ověřování a zvolte správný mechanismus ověřování pro vaše potřeby.

Formát odpovědi

Azure DevOps rozhraní REST API obvykle vrací odpovědi JSON. Tady je příklad struktury odpovědi:

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

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.

Návod

Kompletní pracovní příklady ukazující, jak tyto odpovědi analyzovat, najdete v ukázkách rozhraní REST API.

Metody a operace HTTP

Azure DevOps rozhraní REST API používají standardní metody HTTP:

Metoda Používá se pro... Příklad
ZÍSKAT Získejte zdroj nebo seznam zdrojů Získejte projekty a pracovní položky
PŘÍSPĚVEK Vytvoření prostředku nebo získání prostředků pomocí pokročilých dotazů Vytváření pracovních položek, dotazování pracovních položek
VLOŽIT Vytvoření nebo úplné nahrazení zdroje Nahradit definici sestavení, aktualizovat zásadu
ZÁPLATA Aktualizace konkrétních polí prostředku Aktualizace polí pracovních položek
VYMAZAT Odstranit prostředek Odstranit pracovní položku

Návod

Praktické příklady jednotlivých metod HTTP s kompletními ukázkami kódu najdete v ukázkách rozhraní REST API.

Hlavičky a obsah požadavku

Když zadáte text požadavku (obvykle s POST, PUT a PATCH), zahrňte odpovídající hlavičky:

Content-Type: application/json

Pro operace PATCH s pracovními položkami použijte:

Content-Type: application/json-patch+json

Přepsání metody HTTP

Některé webové proxy servery podporují pouze příkazy HTTP GET a POST. Nepodporují modernější příkazy HTTP, jako jsou PATCH a DELETE. Pokud vaše volání můžou projít jedním z těchto proxy serverů, odešlete 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í

Vysvětlení kódů odpovědí HTTP pomáhá správně zpracovávat odpovědi rozhraní API:

Odezva Význam Poznámky
200 Úspěch Text odpovědi obsahuje požadovaná data.
201 Vytvořeno Úspěšně vytvořený prostředek
204 Úspěch Bez textu odpovědi (běžné s delete)
400 Nesprávná žádost Neplatné parametry nebo text požadavku
401 Neautorizováno Ověření selhalo nebo chybí
403 Zakázáno Uživatel nemá oprávnění k operaci.
404 Nenalezeno Prostředek neexistuje nebo nemá oprávnění k zobrazení.
409 Konflikt Konflikty požadavků s aktuálním stavem prostředků

Správa verzí rozhraní API

Azure DevOps rozhraní REST API jsou verzována, aby aplikace mohly nadále fungovat, zatímco se rozhraní API vyvíjejí.

Pokyny

  • Vždy zadejte verzi rozhraní API s každým požadavkem (povinné).
  • Formátovat verze rozhraní API jako: {major}.{minor} nebo {major}.{minor}-{stage} (například 7.2, 7.2-preview)
  • Pokud jsou k dispozici, použijte konkrétní revize náhledu: 7.2-preview.17.2-preview.2
  • Upgradujte na vydané verze, když jsou rozhraní API ve verzi preview označené jako zastaralé.

Použití

Zadejte verzi rozhraní API jako parametr dotazu adresy URL:

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

Nebo v hlavičce požadavku:

Accept: application/json;api-version=7.2

Podporované verze najdete v tématu Správa verzí rozhraní REST API.

Další zdroje informací

Praktické pokyny k implementaci a kompletní příklady kódu najdete tady:

Použití AI k sestavení volání rozhraní REST API

Pokud připojíte Azure DevOps MCP Server k agentu AI v režimu agenta, můžete k vygenerování a řešení potíží s voláními rozhraní REST API použít výzvy přirozeného jazyka.

Úkol Příklad výzvy
Vytvoření požadavku GET Show me how to construct a GET request to list all projects in my Azure DevOps organization using the REST API
Vytvořte tělo POST Generate the JSON-patch body for creating a work item using the Azure DevOps REST API
Správa ověřování Write C# code to call the Azure DevOps REST API with a Bearer token from Microsoft Entra ID
Prozkoumání oblastí rozhraní API What Azure DevOps REST API endpoints are available for managing Git pull requests?
Analýza odpovědí rozhraní API Show me how to deserialize an Azure DevOps REST API response into C# objects and handle pagination with continuation tokens
Ladění chyb rozhraní API I'm getting a 400 error when calling the Azure DevOps work item update API — help me understand the correct PATCH format

Poznámka:

Režim agenta a server MCP používají přirozený jazyk, takže tyto výzvy můžete upravit nebo položit následné otázky, abyste výsledky upřesněte.

Další krok

Vyzkoušení ukázek rozhraní REST API

  • Poslední aktualizace v