Introduzione alle API REST

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

Le API REST di Azure DevOps offrono un potente accesso a livello di codice agli elementi di lavoro, ai repository, alle compilazioni, alle versioni e altro ancora. Indipendentemente dal fatto che si stia creando integrazioni personalizzate, automatizzando i flussi di lavoro o estendendo le funzionalità di Azure DevOps, è essenziale comprendere i modelli e i concetti fondamentali per una corretta implementazione.

Questo articolo illustra i concetti e i modelli fondamentali per le API REST di Azure DevOps. Per esempi pratici di implementazione, vedere Esempi di API REST.

Struttura URL

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

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

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}

Endpoint di esempio:

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

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.

Esempi:

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

Autenticazione

Le API REST di Azure DevOps supportano diversi metodi di autenticazione:

• Microsoft Entra ID - Consigliato per le applicazioni di produzione
• Token di accesso personale (PAT) - Autenticazione semplice per script e test
• OAuth 2.0 - Per applicazioni non Microsoft
• Principali di servizio - Per scenari automatizzati

Formato della risposta

Le API REST di Azure DevOps restituiscono in genere risposte JSON. Ecco una struttura di risposta di esempio:

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

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

Metodi e operazioni HTTP

Le API REST di Azure DevOps usano metodi HTTP standard:

Intestazioni e contenuto della richiesta

Quando si fornisce un corpo della richiesta (in genere con POST, PUT e PATCH), includere le intestazioni appropriate:

Content-Type: application/json

Per le operazioni PATCH sugli elementi di lavoro, utilizzare:

Content-Type: application/json-patch+json

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

Comprendere i codici di risposta HTTP consente di gestire le risposte API in modo appropriato:

Controllo delle versioni delle API

Le API REST di Azure DevOps sono versionate per garantire che le applicazioni continuino a funzionare mentre le API si evolvono.

Istruzioni

• Specificare sempre la versione dell'API con ogni richiesta (richiesta)
• Formattare le versioni dell'API come: {major}.{minor} o {major}.{minor}-{stage} (ad esempio, 7.2, 7.2-preview)
• Usare revisioni di anteprima specifiche quando disponibili: 7.2-preview.1, 7.2-preview.2
• Eseguire l'aggiornamento alle versioni rilasciate quando le API di anteprima sono deprecate

Uso

Specificare la versione dell'API come parametro di query URL:

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

Oppure nell'intestazione della richiesta:

Accept: application/json;api-version=7.2

Per le versioni supportate, vedere Controllo delle versioni dell'API REST.

Altre risorse

Per indicazioni pratiche sull'implementazione e esempi di codice completi, vedere:

• Esempi di API REST - Esempi completi con l'autenticazione di Microsoft Entra ID
• Linee guida per l'autenticazione - Opzioni di autenticazione dettagliate
• Controllo delle versioni dell'API REST - Informazioni sul ciclo di vita dell'API
• OAuth 2.0 - Dettagli sull'implementazione OAuth

Passaggi successivi