Introduzione alle API REST

  • Articolo

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

Integrare l'app con Azure DevOps usando le API REST fornite in questo articolo.

Le API seguono un modello comune, come nell'esempio seguente.

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

Suggerimento

Man mano che le API si evolvono, è consigliabile includere una versione dell'API in ogni richiesta. Questa procedura consente di evitare modifiche impreviste nell'API che potrebbero interrompersi.

Servizi di Azure DevOps

Per Azure DevOps Services è instance e collection è dev.azure.com/{organization}DefaultCollection, quindi il modello è simile all'esempio seguente.

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

Nell'esempio seguente viene illustrato come ottenere un elenco di progetti in un'organizzazione.

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

Se si vuole fornire il token di accesso personale tramite un'intestazione HTTP, è prima necessario convertirlo in una stringa Base64. L'esempio seguente illustra come eseguire la conversione in Base64 usando C#. La stringa risultante può quindi essere fornita come intestazione HTTP nel formato .

Authorization: Basic BASE64PATSTRING

L'esempio seguente illustra C# usando la classe 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());
	}
}

La maggior parte dei nostri esempi usa le reti AP, poiché sono un esempio compatto per l'autenticazione con il servizio. Esistono tuttavia vari meccanismi di autenticazione disponibili per Azure DevOps Services, tra cui Microsoft Authentication Library (MSAL), OAuth e Token di sessione. Per altre informazioni, vedere Linee guida per l'autenticazione per determinare quale sia la soluzione più adatta per lo scenario in uso.

Azure DevOps Server

Per Azure DevOps Server, instance è {server:port}. La porta predefinita per una connessione non SSL è 8080.

La raccolta predefinita è DefaultCollection, ma è possibile usare qualsiasi raccolta.

Ecco come ottenere un elenco di progetti da Azure DevOps Server usando la porta e la raccolta predefinite in SSL:

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

Per ottenere lo stesso elenco in una connessione non SSL:

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

Questi esempi usano LET, che richiedono la creazione di un token di accesso personale.

Risposte

Si dovrebbe ottenere una risposta simile alla seguente.

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

La risposta è JSON, che è in genere ciò che viene restituito dalle API REST, anche se sono presenti alcune eccezioni, ad esempio i BLOB Git.

A questo punto, è possibile esaminare le aree API specifiche, ad esempio il rilevamento degli elementi di lavoro o Git, e passare alle risorse necessarie. Continuare a leggere per altre informazioni sui modelli generali usati in queste API.

Verbi HTTP

Verbo Usato per...
GET Ottenere una risorsa o un elenco di risorse
POST Creare una risorsa, ottenere un elenco di risorse usando una query più avanzata
PUT Creare una risorsa se non esiste o, in caso affermativo, aggiornarla
PATCH Aggiornare una risorsa
DELETE Eliminare una risorsa

Intestazioni della richiesta e contenuto della richiesta

Quando si specifica il corpo della richiesta (in genere con i verbi POST, PUT e PATCH), includere intestazioni di richiesta che descrivono il corpo. ad esempio:

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

Content-Type: application/json

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

Override del metodo HTTP

Alcuni proxy Web possono supportare solo i verbi HTTP GET e POST, ma non verbi HTTP più moderni, ad esempio PATCH e DELETE. Se le chiamate potrebbero passare attraverso uno di questi proxy, è possibile inviare il verbo effettivo usando un metodo POST, con un'intestazione per eseguire l'override del metodo. Ad esempio, potrebbe essere necessario aggiornare un elemento di lavoro (PATCH _apis/wit/workitems/3), ma potrebbe essere necessario passare attraverso un proxy che consente solo GET o POST. È possibile passare il verbo corretto (PATCH in questo caso) come parametro di intestazione della richiesta HTTP e usare POST come metodo HTTP effettivo.

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

X-HTTP-Method-Override: PATCH

{
   (PATCH request body)
}

Codici di risposta

Response Note
200 Il successo e c'è un corpo della risposta.
201 Operazione riuscita durante la creazione di risorse. Alcune API restituiscono 200 quando si crea correttamente una risorsa. Esaminare la documentazione per l'API usata per assicurarsi.
204 Successo, e non c'è alcun corpo della risposta. Ad esempio, si ottiene questa risposta quando si elimina una risorsa.
400 I parametri nell'URL o nel corpo della richiesta non sono validi.
401 Autenticazione non riuscita. Spesso, questa risposta è dovuta a un'intestazione di autorizzazione mancante o non valida.
403 L'utente autenticato non dispone dell'autorizzazione per eseguire l'operazione.
404 La risorsa non esiste o l'utente autenticato non dispone dell'autorizzazione per verificare che esista.
409 Esiste un conflitto tra la richiesta e lo stato dei dati nel server. Ad esempio, se si tenta di inviare una richiesta pull ed è già presente una richiesta pull per i commit, il codice di risposta è 409.

Condivisione di risorse tra le origini (CORS)

Azure DevOps Services supporta CORS, che consente il codice JavaScript servito da un dominio diverso dev.azure.com/* da quello di effettuare richieste Ajax alle API REST di Azure DevOps Services. Ogni richiesta deve fornire le credenziali (i token di accesso OAuth e I token di accesso OAuth sono entrambe opzioni supportate). Esempio:

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

(sostituire myPatToken con un token di accesso personale)

Controllo delle versioni

Le API REST di Azure DevOps vengono con controllo delle versioni per garantire che le applicazioni e i servizi continuino a funzionare man mano che le API si evolvono.

Linee guida

  • Specificare la versione dell'API con ogni richiesta (obbligatoria).
  • Formattare le versioni dell'API come indicato di seguito: {major}. {minor}-{stage}. {resource-version}. Ad esempio, 1.0, 1.1, 1.2-preview, 2.0.
  • Specificare una revisione particolare dell'API quando è in anteprima usando il formato di versione seguente: 1.0-preview.1, 1.0-preview.2. Dopo il rilascio di un'API, 1.0, ad esempio, la relativa versione di anteprima (1.0-preview) viene deprecata e può essere disattivata dopo 12 settimane.
  • Eseguire l'aggiornamento alla versione rilasciata dell'API. Una volta disattivata un'API di anteprima, le richieste che specificano -preview la versione vengono rifiutate.

Utilizzo

Specificare la versione dell'API nell'intestazione della richiesta HTTP o come parametro di query URL.

Intestazione della richiesta HTTP:

Accept: application/json;api-version=1.0

Parametro di query:

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

Versioni supportate

Per informazioni sulle versioni supportate, vedere Versioni supportate dell'API REST.