Informazioni di riferimento sulle API REST Azure DevOps Services

  • Articolo

Informazioni di riferimento sull'API REST Azure DevOps Services/Azure DevOps Server.

Le API di trasferimento di stato rappresentativo (REST) sono endpoint di servizio che supportano un set di operazioni (metodi) HTTP che offrono l'accesso con diritti di creazione, recupero, aggiornamento o eliminazione per le risorse del servizio. In questo articolo viene descritto:

  • Componenti di base di una coppia di richiesta/risposta dell'API REST.
  • Panoramica della creazione e dell'invio di una richiesta REST e della gestione della risposta.

La maggior parte delle API REST è accessibile tramite le librerie client, che possono essere usate per semplificare notevolmente il codice client.

Componenti di una coppia di richiesta/risposta dell'API REST

La coppia richiesta-risposta di un'API REST può essere suddivisa in cinque componenti:

  1. URI della richiesta, nel formato seguente:VERB https://{instance}[/{team-project}]/_apis[/{area}]/{resource}?api-version={version}

    • instance: l'organizzazione Azure DevOps Services o il server TFS a cui si sta inviando la richiesta. Sono strutturati come segue:
      • Azure DevOps Services:dev.azure.com/{organization}
      • TFS: {server:port}/tfs/{collection} (la porta predefinita è 8080 e il valore per la raccolta deve essere DefaultCollection ma può essere qualsiasi raccolta)
    • percorso risorsa: il percorso della risorsa è il seguente: _apis/{area}/{resource}. Ad esempio _apis/wit/workitems.
    • api-version: ogni richiesta API deve includere una versione api per evitare l'interruzione dell'app o del servizio man mano che le API si evolvono. Le versioni api sono nel formato seguente: {major}.{minor}[-{stage}[.{resource-version}]], ad esempio:
      • api-version=1.0
      • api-version=1.2-preview
      • api-version=2.0-preview.1

    Nota: l'area e il progetto team sono facoltativi, a seconda della richiesta API. Per trovare le versioni dell'API REST applicabili alla versione di TFS, vedere la matrice di mapping della versione dell'API REST riportata di seguito.

  2. Campi di intestazione del messaggio di richiesta HTTP:

    • Un metodo HTTP necessario (noto anche come operazione o verbo) che indica al servizio il tipo di operazione richiesto. Le API REST di Azure supportano i metodi GET, HEAD, PUT, POST e PATCH.
    • Campi di intestazione aggiuntivi facoltativi, come richiesto dall'URI e dal metodo HTTP specificati. Ad esempio, un'intestazione authorization che fornisce un token di connessione contenente informazioni di autorizzazione client per la richiesta.

  3. Campi facoltativi del corpo del messaggio di richiesta HTTP per supportare l'operazione URI e HTTP. Le operazioni POST contengono ad esempio oggetti con codifica MIME che vengono passati come parametri complessi.

    • Per le operazioni POST o PUT, è necessario specificare anche il tipo di codifica MIME per il corpo nell'intestazione della richiesta Content-type. Alcuni servizi richiedono l'uso di un tipo MIME specifico, ad esempio application/json.

  4. Campi di intestazione del messaggio di risposta HTTP:

    • Un codice di stato HTTP, compreso tra codici di riuscita 2xx e codici di errore 4xx o 5xx. In alternativa, può essere restituito un codice di stato definito dal servizio, come indicato nella documentazione dell'API.
    • Campi di intestazione aggiuntivi facoltativi eventualmente necessari per supportare la risposta della richiesta, ad esempio un'intestazione della risposta Content-type.

  5. Campi facoltativi del corpo del messaggio di risposta HTTP:

    • Gli oggetti risposta con codifica MIME possono essere restituiti nel corpo della risposta HTTP, ad esempio una risposta da un metodo GET che restituisce dati. In genere, questi oggetti vengono restituiti in un formato strutturato, ad esempio JSON o XML, come indicato dall'intestazione della risposta Content-type. Ad esempio, quando si richiede un token di accesso da Azure AD, il token verrà restituito nel corpo della risposta come access_token elemento, uno dei diversi oggetti associati nome/valore in una raccolta dati. In questo esempio è inclusa anche un'intestazione di risposta di Content-Type: application/json .

Creare la richiesta

Authenticate

Esistono molti modi per autenticare l'applicazione o il servizio con Azure DevOps Services o TFS. La tabella seguente è un ottimo modo per decidere quale metodo è il migliore per te:

Tipo di applicazione Descrizione esempio Meccanismo di autenticazione Esempi di codice
Lato client interattivo Applicazione client, che consente l'interazione dell'utente, chiamando Azure DevOps Services API REST Applicazione console che enumera i progetti in un'organizzazione Microsoft Authentication Library (MSAL) Esempio
JavaScript interattivo Applicazione JavaScript basata su GUI App a pagina singola AngularJS che visualizza informazioni sul progetto per un utente MSAL Esempio
Lato client non interattivo Applicazione lato client solo testo headless App console che visualizza tutti i bug assegnati a un utente Profilo dispositivo Esempio
Web interattivo Applicazione Web basata su GUI Dashboard Web personalizzato che visualizza riepiloghi di compilazione OAuth Esempio
Applicazione TFS App TFS con la libreria CLIENT OM Estensione TFS che visualizza i dashboard di bug del team Librerie client Esempio
estensione Azure DevOps Services estensione Azure DevOps Services Esempi di estensione Azure DevOps VSS Web Extension SDK procedura dettagliata di esempio

Nota: Per altre informazioni sull'autenticazione, vedere la pagina delle linee guida per l'autenticazione.

Assemblare la richiesta

Azure DevOps Services

Per Azure DevOps Services, l'istanza è dev.azure.com/{organization}, quindi il modello è simile al seguente:

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

Ecco ad esempio come ottenere un elenco di progetti team in un'organizzazione Azure DevOps Services.

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#). Alcuni strumenti come Postman applicano per impostazione predefinita una codifica Base64. Se si sta provando l'API tramite tali strumenti, la codifica Base64 del pat non è necessaria) La stringa risultante può quindi essere fornita come intestazione HTTP nel formato:

Authorization: Basic BASE64PATSTRING

Qui si trova in C# usando la [classe HttpClient](/previous-versions/visualstudio/hh193681(v=vs.118).

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 = await client.GetAsync(
						"https://dev.azure.com/{organization}/_apis/projects"))
			{
				response.EnsureSuccessStatusCode();
				string responseBody = await response.Content.ReadAsStringAsync();
				Console.WriteLine(responseBody);
			}
		}
	}
	catch (Exception ex)
	{
		Console.WriteLine(ex.ToString());
	}
}

La maggior parte degli esempi in questo sito usa i token di accesso personale perché sono un esempio compatto per l'autenticazione con il servizio. Esistono tuttavia diversi meccanismi di autenticazione disponibili per Azure DevOps Services inclusi MSAL, OAuth e Token di sessione. Per indicazioni su quale scenario è più adatto per lo scenario, vedere la sezione Autenticazione .

TFS

Per TFS, instance è {server:port}/tfs/{collection} e per impostazione predefinita la porta è 8080. La raccolta predefinita è DefaultCollection, ma può essere qualsiasi raccolta.

Ecco come ottenere un elenco di progetti team da TFS usando la porta e la raccolta predefinite.

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

Gli esempi precedenti usano token di accesso personale, che richiedono la creazione di un token di accesso personale.

Elaborare la risposta

Dovrebbe essere visualizzata 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/DefaultCollection"
            },
            "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/DefaultCollection"
            },
            "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. Questo è in genere ciò che si otterrà dalle API REST, anche se esistono alcune eccezioni, ad esempio i BLOB Git.

A questo punto dovrebbe essere 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.

Mapping delle versioni di API e TFS

Di seguito è riportato un mapping rapido delle versioni dell'API REST e delle versioni corrispondenti di TFS. Tutte le versioni dell'API funzioneranno nella versione del server menzionata e nelle versioni successive.

Versione di TFS Versione dell'API REST Versione build
Azure DevOps Server vNext 7.1
Azure DevOps Server 2022 7.0 versions >= 19.205.33122.1
Azure DevOps Server 2020 6,0 versions >= 18.170.30525.1
Azure DevOps Server 2019 5.0 versions >= 17.143.28621.4
TFS 2018 Update 3 4.1 versions >= 16.131.28106.2
TFS 2018 Update 2 4.1 versions >= 16.131.27701.1
TFS 2018 Update 1 4,0 versions >= 16.122.27409.2
TFS 2018 RTW 4,0 versions >= 16.122.27102.1
TFS 2017 Update 2 3.2 versions >= 15.117.26714.0
TFS 2017 Update 1 3.1 versions >= 15.112.26301.0
TFS 2017 RTW 3.0 versions >= 15.105.25910.0
TFS 2015 Update 4 2.3 versions >= 14.114.26403.0
TFS 2015 Update 3 2.3 versions >= 14.102.25423.0
TFS 2015 Update 2 2.2 versions >= 14.95.25122.0
TFS 2015 Update 1 2.1 versions >= 14.0.24712.0
TFS 2015 RTW 2.0 versions >= 14.0.23128.0

Contenuto correlato

Vedere la documentazione di Integrazione per esempi di API REST e casi d'uso.

Librerie client

Individuare le librerie client per queste API REST.

Dove sono le versioni precedenti delle API REST? (Prima della 4.1)

Recentemente abbiamo apportato una modifica al nostro processo di generazione del sistema di progettazione e della documentazione; Questa modifica è stata apportata per fornire documentazione più chiara, più approfondita e più accurata per tutti i tentativi di usare queste API REST. A causa dei vincoli tecnici, è possibile documentare solo l'API versione 4.1 e successive usando questo metodo. La documentazione per l'API versione 4.1 e successive sarà più semplice da usare a causa di questa modifica.

Se si lavora in TFS o si cercano le versioni precedenti delle API REST, è possibile esaminare la panoramica dell'API REST per TFS 2015, 2017 e 2018.