InvokeRESTAPI@1 - Richiamare l'attività API REST v1

Articolo
07/02/2024

Usare questa attività per richiamare un'API REST come parte della pipeline.

Sintassi

# Invoke REST API v1
# Invoke a REST API as a part of your pipeline.
- task: InvokeRESTAPI@1
  inputs:
    connectionType: 'connectedServiceName' # 'connectedServiceName' | 'connectedServiceNameARM'. Alias: connectedServiceNameSelector. Required. Connection type. Default: connectedServiceName.
    serviceConnection: # string. Alias: connectedServiceName | genericService. Required when connectedServiceNameSelector = connectedServiceName. Generic service connection. 
    #azureServiceConnection: # string. Alias: connectedServiceNameARM | azureSubscription. Required when connectedServiceNameSelector = connectedServiceNameARM. Azure subscription. 
    method: 'POST' # 'OPTIONS' | 'GET' | 'HEAD' | 'POST' | 'PUT' | 'DELETE' | 'TRACE' | 'PATCH'. Required. Method. Default: POST.
    #headers: # string. Headers. 
    #body: # string. Optional. Use when method != GET && method != HEAD. Body. 
    #urlSuffix: # string. URL suffix and parameters. 
  # Advanced
    waitForCompletion: 'false' # 'true' | 'false'. Required. Completion event. Default: false.
    #successCriteria: # string. Optional. Use when waitForCompletion = false. Success criteria.

# Invoke REST API v1
# Invoke a REST API as a part of your pipeline.
- task: InvokeRESTAPI@1
  inputs:
    connectionType: 'connectedServiceName' # 'connectedServiceName' | 'connectedServiceNameARM'. Alias: connectedServiceNameSelector. Required. Connection type. Default: connectedServiceName.
    serviceConnection: # string. Alias: connectedServiceName. Required when connectedServiceNameSelector = connectedServiceName. Generic service connection. 
    #azureServiceConnection: # string. Alias: connectedServiceNameARM. Required when connectedServiceNameSelector = connectedServiceNameARM. Azure subscription. 
    method: 'POST' # 'OPTIONS' | 'GET' | 'HEAD' | 'POST' | 'PUT' | 'DELETE' | 'TRACE' | 'PATCH'. Required. Method. Default: POST.
    #headers: # string. Headers. 
    #body: # string. Optional. Use when method != GET && method != HEAD. Body. 
    #urlSuffix: # string. URL suffix and parameters. 
  # Advanced
    waitForCompletion: 'false' # 'true' | 'false'. Required. Completion event. Default: false.
    #successCriteria: # string. Optional. Use when waitForCompletion = false. Success criteria.

Input

connectionType - Tipo di connessione
Alias di input: connectedServiceNameSelector. string. Obbligatorio. Valori consentiti: connectedServiceName (Generic), connectedServiceNameARM (Azure Resource Manager). Valore predefinito: connectedServiceName.

Specifica il tipo di connessione del servizio da usare per richiamare l'API REST. Selezionare Azure Resource Manager per richiamare un'API di gestione di Azure o Generica per tutte le altre API.

serviceConnection - Connessione al servizio generico
Alias di input: connectedServiceName | genericService. string. Obbligatorio quando connectedServiceNameSelector = connectedServiceName.

Specifica la connessione al servizio generico che fornisce baseUrl per la chiamata e l'autorizzazione da usare per l'attività.

serviceConnection - Connessione al servizio generico
Alias di input: connectedServiceName. string. Obbligatorio quando connectedServiceNameSelector = connectedServiceName.

Specifica la connessione al servizio generico che fornisce baseUrl per la chiamata e l'autorizzazione da usare per l'attività.

azureServiceConnection - Sottoscrizione di Azure
Alias di input: connectedServiceNameARM | azureSubscription. string. Obbligatorio quando connectedServiceNameSelector = connectedServiceNameARM.

Specifica la sottoscrizione di Azure Resource Manager per configurare e usare per richiamare le API di gestione di Azure.

azureServiceConnection - Sottoscrizione di Azure
Alias di input: connectedServiceNameARM. string. Obbligatorio quando connectedServiceNameSelector = connectedServiceNameARM.

Specifica la sottoscrizione di Azure Resource Manager per configurare e usare per richiamare le API di gestione di Azure.

method - Metodo
string. Obbligatorio. Valori consentiti: OPTIONS, GET, POSTHEAD, PUT, DELETE, , TRACE, PATCH. Valore predefinito: POST.

Specifica il metodo HTTP che richiama l'API.

headers - Intestazioni
string. Valore predefinito: {\n"Content-Type":"application/json", \n"PlanUrl": "$(system.CollectionUri)", \n"ProjectId": "$(system.TeamProjectId)", \n"HubName": "$(system.HostType)", \n"PlanId": "$(system.PlanId)", \n"JobId": "$(system.JobId)", \n"TimelineId": "$(system.TimelineId)", \n"TaskInstanceId": "$(system.TaskInstanceId)", \n"AuthToken": "$(system.AccessToken)"\n}.

Definisce l'intestazione in formato JSON. L'intestazione è collegata alla richiesta inviata all'API.

body - Corpo
string. facoltativo. Usare quando method != GET && method != HEAD.

Specifica il corpo della richiesta per la chiamata di funzione in formato JSON.

urlSuffix - Suffisso URL e parametri
string.

Specifica la stringa da aggiungere all'oggetto baseUrl dalla connessione al servizio generico durante l'esecuzione della chiamata HTTP.

Esempio: se l'URL di connessione del servizio è https:...TestProj/_apis/Release/releases e il suffisso URL è /2/environments/1, l'URL di connessione del servizio diventa https:.../TestProj/_apis/Release/releases/2/environments/1. Se il suffisso URL è ?definitionId=1&releaseCount=1, l'URL di connessione del servizio diventa https//...TestProj/_apis/Release/releases?definitionId=1&releaseCount=1.

waitForCompletion - Evento di completamento
string. Obbligatorio. Valori consentiti: true (Callback), false (ApiResponse). Valore predefinito: false.

Specifica il modo in cui l'attività segnala il completamento. Di seguito sono elencati i valori consentiti:

false - Risposta API: segnala il completamento quando la funzione restituisce l'esito positivo entro 20 secondi e i criteri di esito positivo restituiscono true.
true - Callback: segnala il completamento quando il servizio esterno effettua un callback per aggiornare il record della sequenza temporale.

successCriteria - Criteri di esito positivo
string. facoltativo. Usare quando waitForCompletion = false.

Specifica i criteri dell'attività per l'esito positivo. Il contenuto della risposta non influisce sul risultato se non viene definito alcun criterio. Per impostazione predefinita, l'attività passa quando la chiamata restituisce 200 OK.

Esempio: per la risposta {"status" : "successful"}, l'espressione può essere eq(root['status'], 'successful'). Altre informazioni sulla specifica delle condizioni.

Opzioni di controllo delle attività

Tutte le attività dispongono di opzioni di controllo oltre ai relativi input attività. Per altre informazioni, vedere Opzioni di controllo e proprietà comuni delle attività.

Variabili di output

Nessuno.

Osservazioni

Nota

Questa attività può essere usata solo in un processo senza agente.

Ha esito positivo se l'API restituisce esito positivo e l'analisi del corpo della risposta ha esito positivo o quando l'API aggiorna il record della sequenza temporale con esito positivo.

L'attività Richiama API REST non esegue direttamente le azioni di distribuzione. Consente invece di richiamare qualsiasi API REST HTTP generica come parte della pipeline automatizzata e, facoltativamente, attendere il completamento.

Configurazione di un'attività Richiama API REST

Per altre informazioni sull'uso di questa attività, vedere Panoramica delle approvazioni e dei controlli.

Quali URL di base vengono usati quando si richiamano le API di gestione di Azure?

Le API di gestione di Azure vengono richiamate usando ResourceManagerEndpoint dell'ambiente selezionato. Ad esempio https://management.azure.com , viene usato quando la sottoscrizione si trova in un ambiente AzureCloud .

Dove deve essere completato un segnale di attività quando viene scelto callback come evento di completamento?

Per segnalare il completamento, il servizio esterno deve inviare i dati di completamento POST all'endpoint REST delle pipeline seguente.

{planUri}/{projectId}/_apis/distributedtask/hubs/{hubName}/plans/{planId}/events?api-version=2.0-preview.1

**Request Body**
 { "name": "TaskCompleted", "taskId": "taskInstanceId", "jobId": "jobId", "result": "succeeded" }

Per informazioni specifiche, vedere questa semplice applicazione cmdline .

Inoltre, è disponibile una libreria helper C# per abilitare la registrazione in tempo reale e gestire lo stato delle attività per le attività senza agente. Scopri di più

È possibile usare il corpo della risposta come input per un'altra attività?

No, poiché questa attività è un'attività senza agente e usa httpRequest interna di TFS, che non restituisce il contenuto della richiesta HTTP.

steps:
- task: InvokeRESTAPI@1
  displayName: 'Invoke REST API: GET'
  inputs:
    serviceConnection: 'generic_demo'
    method: GET
    successCriteria: 'eq(root[''count''], ''1425'')'

In questo esempio l'attività ha esito positivo quando la risposta corrisponde successCriteriaa : eq(root[''count''], ''1425'')).

Nella definizione della pipeline selezionare il pulsante con i puntini di sospensione (...), quindi selezionare Aggiungi un processo senza agente.
Nel nuovo processo senza agente selezionare il + segno per aggiungere una nuova attività.
Search per l'attività Richiama API REST. Selezionare Aggiungi per aggiungerlo al processo senza agente.
Selezionare il tipo di connessione e la connessione al servizio. Selezionare il metodo HTTP che si vuole usare e quindi selezionare un evento Completion. È anche possibile definire un criterio di esito positivo per passare l'attività.
Al termine, selezionare Salva & coda .