Condividi tramite

Introduzione alle API REST

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

Integrare l'applicazione con Azure DevOps usando le API REST fornite in questo articolo. Queste API consentono di interagire con i servizi a livello di codice, consentendo di automatizzare i flussi di lavoro, integrarsi con altri sistemi ed estendere le funzionalità di Azure DevOps.

Le API seguono un modello comune, come illustrato 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.

Azure DevOps Services

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

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

L'esempio seguente illustra 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 desidera fornire il token di accesso personale (PAT) tramite un'intestazione HTTP, anteporre due punti al PAT. Convertire quindi la concatenazione dei due punti e del PAT in una stringa in formato 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 BASE64COLONANDPATSTRING

Annotazioni

Includere i due punti prima del pat per evitare errori di autenticazione.

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

Importante

Anche se si usano token di accesso personali in molti esempi per semplicità, non è consigliabile usarli per le applicazioni di produzione. Prendere invece in considerazione l'uso di meccanismi di autenticazione più sicuri. Per altre informazioni, vedere Indicazioni sull'autenticazione.

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 PAT, che richiedono di creare un PAT.

Risposte

Si dovrebbe ottenere una risposta simile all'esempio seguente:

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

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

Ora, è possibile esaminare aree API specifiche, come il tracciamento degli elementi di lavoro o Git, e accedere 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
INSERIRE Creare una risorsa se non esiste o, in caso affermativo, aggiornarla
Cerotto Aggiornare una risorsa
ELIMINA Eliminare una risorsa

Intestazioni della richiesta e contenuto della richiesta

Quando fornisci il corpo della richiesta (in genere con i verbi POST, PUT e PATCH), includi le intestazioni di richiesta che descrivono il contenuto. 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 consenta 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

Risposta Note
200 Il successo, e c'è un corpo di risposta.
201 Successo nella creazione delle risorse. Alcune API restituiscono 200 quando si crea correttamente una risorsa. Esaminare la documentazione per l'API usata per assicurarsi.
204 Operazione riuscita, e non c'è alcun messaggio di 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 al codice JavaScript gestito da un dominio diverso da dev.azure.com/* di effettuare richieste Ajax alle API REST di Azure DevOps Services. Ogni richiesta deve fornire le credenziali (i PAT 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 PAT.

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.

Istruzioni

  • Specificare la versione dell'API con ogni richiesta (necessario).
  • 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 versione vengono rifiutate.

Uso

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 controllo delle versioni dell'API REST, Versioni supportate.