Delen via

Aan de slag met de REST API's

  • Artikel

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

Integreer uw app met Azure DevOps met behulp van de REST API's in dit artikel.

De API's volgen een gemeenschappelijk patroon, zoals in het volgende voorbeeld.

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

Tip

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 instance ziet dev.azure.com/{organization} collection DefaultCollectionhet patroon eruit 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());
	}
}

De meeste van onze voorbeelden gebruiken PAW's, omdat ze een compact voorbeeld zijn voor verificatie met de service. Er zijn echter verschillende verificatiemechanismen beschikbaar voor Azure DevOps Services, waaronder Microsoft Authentication Library (MSAL), OAuth en sessietokens. Zie verificatierichtlijnen voor meer informatie om te bepalen welke optie het meest geschikt is voor uw scenario.

Azure DevOps Server

Voor Azure DevOps Server instance is dit {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 voor 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. Hiervoor moet u een PAT maken.

Antwoorden

Als het goed is, krijgt u een antwoord zoals dit.

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

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 kijken naar de specifieke API-gebieden , zoals het bijhouden van werkitems 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-woorden

Term Wordt gebruikt voor...
GET Een resource of lijst met resources ophalen
POSTEN 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
DELETE 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. Voorbeeld:

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 wilt bijvoorbeeld een werkitem (PATCH _apis/wit/workitems/3) bijwerken, 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

Respons Opmerkingen
200 Succes, en er is een antwoordtekst.
201 Succes, bij het maken van resources. 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 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-aanvraag in te dienen en er al een pull-aanvraag voor de doorvoeringen is, is de antwoordcode 409.

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

Azure DevOps Services biedt ondersteuning voor 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 );
        });
    });

(vervangen door myPatToken een persoonlijk toegangstoken)

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 met 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. Nadat een API is uitgebracht, bijvoorbeeld 1.0, wordt 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 versie opgeven -preview 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

Queryparameter:

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

Ondersteunde versies

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