Delen via

Aan de slag met de REST API's

  • Artikel

Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019

Integreer uw toepassing met Azure DevOps met behulp van de REST API's in dit artikel. Met deze API's kunt u programmatisch communiceren met de services, zodat u werkstromen kunt automatiseren, kunt integreren met andere systemen en de mogelijkheden van Azure DevOps kunt uitbreiden.

De API's volgen een gemeenschappelijk patroon, zoals wordt weergegeven in het volgende voorbeeld:

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

Hint

Naarmate API's zich ontwikkelen, raden we u aan een API-versie op te nemen in elke aanvraag. Met deze procedure kunt u onverwachte wijzigingen in de API voorkomen die kunnen worden onderbroken.

Azure DevOps Services

Voor Azure DevOps Services is instancedev.azure.com/{organization} en collection is DefaultCollection, zodat het patroon eruitziet als in het volgende voorbeeld:

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

In het volgende voorbeeld ziet u hoe u een lijst met projecten in een organisatie kunt ophalen:

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

Als u het persoonlijke toegangstoken (PAT) wilt opgeven via een HTTP-header, moet u het eerst converteren naar een Base64-tekenreeks. In het volgende voorbeeld ziet u hoe u met C# converteert naar Base64. De resulterende tekenreeks kan vervolgens worden opgegeven als een HTTP-header in de indeling:

Authorization: Basic BASE64PATSTRING

In het volgende voorbeeld ziet u C# met behulp van de HttpClient-klasse:

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

Belangrijk

Hoewel we persoonlijke toegangstokens (PAT's) gebruiken in veel voorbeelden voor het gemak, raden we u niet aan deze te gebruiken voor productietoepassingen. Overweeg in plaats daarvan veiligere verificatiemechanismen te gebruiken. Zie Richtlijnen voor verificatievoor meer informatie.

Azure DevOps Server

Voor Azure DevOps Server is instance{server:port}. De standaardpoort voor een niet-SSL-verbinding is 8080.

De standaardverzameling is DefaultCollection, maar u kunt elke verzameling gebruiken.

U kunt als volgt een lijst met projecten ophalen van Azure DevOps Server met behulp van de standaardpoort en verzameling via SSL:

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

Dezelfde lijst ophalen via een niet-SSL-verbinding:

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

In deze voorbeelden worden PAT's gebruikt, waarvoor u een PAT-moet maken.

Reacties

U krijgt een antwoord zoals in het volgende voorbeeld:

{
    "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",
            "collection": {
                "id": "00000000-0000-0000-0000-000000000000",
                "name": "DefaultCollection",
                "url": "https: //dev.azure.com/fabrikam-fiber-inc/_apis/projectCollections/00000000-0000-0000-0000-000000000000",
                "collectionUrl": "https: //dev.azure.com/fabrikam-fiber-inc"
            },
            "defaultTeam": {
                "id": "00000000-0000-0000-0000-000000000000",
                "name": "Fabrikam-Fiber-TFVCTeam",
                "url": "https: //dev.azure.com/fabrikam-fiber-inc/_apis/projects/00000000-0000-0000-0000-000000000000/teams/00000000-0000-0000-0000-000000000000"
            }
        },
        {
            "id": "00000000-0000-0000-0000-000000000000",
            "name": "Fabrikam-Fiber-Git",
            "url": "https: //dev.azure.com/fabrikam-fiber-inc/_apis/projects/00000000-0000-0000-0000-000000000000",
            "description": "Gitprojects",
            "collection": {
                "id": "00000000-0000-0000-0000-000000000000",
                "name": "DefaultCollection",
                "url": "https: //dev.azure.com/fabrikam-fiber-inc/_apis/projectCollections/00000000-0000-0000-0000-000000000000",
                "collectionUrl": "https: //dev.azure.com/fabrikam-fiber-inc"
            },
            "defaultTeam": {
                "id": "00000000-0000-0000-0000-000000000000",
                "name": "Fabrikam-Fiber-GitTeam",
                "url": "https: //dev.azure.com/fabrikam-fiber-inc/_apis/projects/00000000-0000-0000-0000-000000000000/teams/00000000-0000-0000-0000-000000000000"
            }
        }
    ],
    "count": 2
}

Het antwoord is JSON-. Dit is over het algemeen wat u terugkrijgt van de REST API's, hoewel er enkele uitzonderingen zijn, zoals Git-blobs.

U kunt nu de specifieke API-gebieden bekijken, zoals werkitems bijhouden of Git- en toegang krijgen tot de resources die u nodig hebt. Lees verder voor meer informatie over de algemene patronen die worden gebruikt in deze API's.

HTTP-werkwoorden

Werkwoord Wordt gebruikt voor...
GET Een bron of lijst met bronnen ophalen
BERICHT Een resource maken, een lijst met resources ophalen met behulp van een geavanceerdere query
PUT Een resource maken als deze niet bestaat of, als dat het geval is, deze bijwerken
PATCH Een resource bijwerken
Verwijderen Een resource verwijderen

Aanvraagheaders en aanvraaginhoud

Wanneer u de aanvraagtekst opgeeft (meestal met de werkwoorden POST, PUT en PATCH), neemt u aanvraagheaders op die de hoofdtekst beschrijven. Bijvoorbeeld

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

Content-Type: application/json

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

HTTP-methode overschrijven

Sommige webproxy's ondersteunen mogelijk alleen de HTTP-woorden GET en POST, maar niet meer moderne HTTP-woorden, zoals PATCH en DELETE. Als uw aanroepen een van deze proxy's kunnen passeren, kunt u het werkelijke werkwoord verzenden met behulp van een POST-methode, met een header om de methode te overschrijven. U kunt bijvoorbeeld een werkitem bijwerken (PATCH _apis/wit/workitems/3), maar mogelijk moet u een proxy doorlopen die alleen GET of POST toestaat. U kunt het juiste werkwoord (PATCH in dit geval) doorgeven als een http-aanvraagheaderparameter en POST gebruiken als de werkelijke HTTP-methode.

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

X-HTTP-Method-Override: PATCH

{
   (PATCH request body)
}

Antwoordcodes

Reactie Opmerkingen
200 Succes, en er is een antwoordtekst.
201 Succes bij het creëren van middelen. Sommige API's retourneren 200 bij het maken van een resource. Bekijk de documenten voor de API die u gebruikt om er zeker van te zijn.
204 Succes, en er is geen antwoordtekst. U krijgt bijvoorbeeld dit antwoord wanneer u een resource verwijdert.
400 De parameters in de URL of in de aanvraagbody zijn niet geldig.
401 Verificatie is mislukt. Dit antwoord komt vaak door een ontbrekende of onjuiste autorisatieheader.
403 De geverifieerde gebruiker is niet gemachtigd om de bewerking uit te voeren.
404 De resource bestaat niet of de geverifieerde gebruiker heeft geen machtiging om te zien dat deze bestaat.
409 Er is een conflict tussen de aanvraag en de status van de gegevens op de server. Als u bijvoorbeeld probeert een pull request in te dienen en er al een pull request voor de commits is, is de antwoordcode 409.

CORS (Cross-Origin Resource Sharing, cross-origin-resource delen)

Azure DevOps Services ondersteunt CORS, waardoor JavaScript-code die wordt geleverd vanuit een ander domein dan dev.azure.com/* Ajax-aanvragen kan indienen bij Azure DevOps Services REST API's. Elke aanvraag moet referenties opgeven (PAW's en OAuth-toegangstokens zijn beide ondersteunde opties). Voorbeeld:

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

Vervang myPatToken door een PAT.

Versiebeheer

Azure DevOps REST API's zijn geversied om ervoor te zorgen dat toepassingen en services blijven werken naarmate API's zich ontwikkelen.

Richtlijnen

  • Geef de API-versie op bij elke aanvraag (vereist).
  • Maak API-versies als volgt op: {major}.{minor}-{stage}.{resource-version}. Bijvoorbeeld 1.0, 1.1, 1.2-preview, 2.0.
  • Geef een bepaalde revisie van de API op wanneer deze in preview is, met behulp van de volgende versie-indeling: 1.0-preview.1, 1.0-preview.2. Zodra een API is uitgebracht (bijvoorbeeld 1.0), is de preview-versie (1.0-preview) afgeschaft en kan deze na 12 weken worden gedeactiveerd.
  • Voer een upgrade uit naar de uitgebrachte versie van de API. Zodra een preview-API is gedeactiveerd, worden aanvragen die -preview versie opgeven geweigerd.

Gebruik

Geef de API-versie op in de header van de HTTP-aanvraag of als een URL-queryparameter.

HTTP-aanvraagheader:

Accept: application/json;api-version=1.0

Query-parameter

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

Ondersteunde versies

Zie REST API-versiebeheer, ondersteunde versiesvoor meer informatie over ondersteunde versies.