Delen via

Aan de slag met de REST API's

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

Azure DevOps REST API's bieden krachtige programmatische toegang tot werkitems, opslagplaatsen, builds, releases en meer. Of u nu aangepaste integraties bouwt, werkstromen automatiseert of azure DevOps-mogelijkheden uitbreidt, het begrijpen van de fundamentele patronen en concepten is essentieel voor een succesvolle implementatie.

Hint

Klaar om te beginnen met coderen? Ga verder met REST API-voorbeelden voor volledige werkvoorbeelden met moderne verificatiepatronen.

In dit artikel worden de basisconcepten en patronen voor Azure DevOps REST API's behandeld. Zie REST API-voorbeelden voor praktische implementatievoorbeelden.

URL-structuur

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}

Voorbeeldeindpunt:

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

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.

Voorbeelden:

  • SSL: https://{server}/DefaultCollection/_apis/projects?api-version=7.2
  • Niet-SSL: http://{server}:8080/DefaultCollection/_apis/projects?api-version=7.2

Authenticatie

Azure DevOps REST API's ondersteunen verschillende verificatiemethoden:

  • Microsoft Entra-id - Aanbevolen voor productietoepassingen
  • Persoonlijke toegangstokens (PAT's) - Eenvoudige verificatie voor scripts en testen
  • OAuth 2.0 - Voor niet-Microsoft-toepassingen
  • Serviceprincipals - voor geautomatiseerde scenario's

Belangrijk

Microsoft Entra ID-verificatie is de aanbevolen benadering voor productietoepassingen. Zie REST API-voorbeelden en verificatierichtlijnen voor implementatievoorbeelden en volledige verificatierichtlijnen.

Antwoordindeling

Azure DevOps REST API's retourneren doorgaans JSON-antwoorden. Hier volgt een voorbeeld van een antwoordstructuur:

{
    "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"
        }
    ],
    "count": 1
}

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.

Hint

Zie REST API-voorbeelden voor volledige werkvoorbeelden die laten zien hoe u deze antwoorden kunt parseren.

HTTP-methoden en -bewerkingen

Azure DevOps REST API's maken gebruik van standaard HTTP-methoden:

Methode Wordt gebruikt voor... Voorbeeld
GET Een bron of lijst met bronnen ophalen Projecten en werkitems ophalen
BERICHT Een resource maken of resources ophalen met behulp van geavanceerde query's Werkitems maken, werkitems opvragen
PUT Een resource maken of volledig vervangen Werkitem maken/bijwerken
PATCH Specifieke velden van een resource bijwerken Werkitemvelden bijwerken
Verwijderen Een resource verwijderen Werkitem verwijderen

Hint

Zie REST API-voorbeelden voor praktische voorbeelden van elke HTTP-methode met volledige codevoorbeelden.

Aanvraagheaders en -inhoud

Wanneer u een aanvraagtekst opgeeft (meestal met POST, PUT en PATCH), neemt u de juiste headers op:

Content-Type: application/json

Voor PATCH-bewerkingen voor werkitems gebruikt u:

Content-Type: application/json-patch+json

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

Inzicht in HTTP-antwoordcodes helpt u api-antwoorden op de juiste wijze te verwerken:

Reactie Betekenis Opmerkingen
200 Geslaagd Antwoordtekst bevat aangevraagde gegevens
201 Gecreëerd Resource is succesvol aangemaakt
204 Geslaagd Geen antwoordtekst (gemeenschappelijk met DELETE)
400 Onjuiste aanvraag Ongeldige parameters of aanvraaginhoud
401 Niet geautoriseerd Verificatie is mislukt of ontbreekt
403 Verboden Gebruiker heeft geen machtigingen voor bewerkingen
404 Niet gevonden Bron bestaat niet of er is geen toestemming om te bekijken
409 Conflict Aanvraagconflicten met de huidige resourcestatus

API-versiebeheer

Azure DevOps REST API's worden geversied om ervoor te zorgen dat toepassingen blijven werken wanneer API's zich ontwikkelen.

Richtlijnen

  • Geef altijd de API-versie op met elke aanvraag (vereist)
  • API-versies opmaken als: {major}.{minor} of {major}.{minor}-{stage} (bijvoorbeeld 7.2, 7.2-preview)
  • Specifieke preview-revisies gebruiken indien beschikbaar: 7.2-preview.1, 7.2-preview.2
  • Upgraden naar uitgebrachte versies wanneer preview-API's zijn afgeschaft

Gebruik

Geef de API-versie op als een URL-queryparameter:

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

Of in de verzoekheader:

Accept: application/json;api-version=7.2

Zie REST API-versiebeheer voor ondersteunde versies.

Meer middelen

Zie voor praktische implementatierichtlijnen en volledige codevoorbeelden:

Volgende stappen

REST API-voorbeelden proberen

  • Last updated on