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

Articolo
03/24/2025

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.

Ingressi dati

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

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

serviceConnection - di 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à.

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

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

metodo method -
string. Obbligatorio. Valori consentiti: OPTIONS, GET, HEAD, POST, 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. Opzionale. 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 Completion
string. Obbligatorio. Valori consentiti: true (callback), false (ApiResponse). Valore predefinito: false

Specifica il modo in cui l'attività segnala il completamento. I valori consentiti sono:

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 esegue un callback per aggiornare il record della sequenza temporale.

successCriteria - criteri di esito positivo
string. Opzionale. 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 su 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à Invoke REST API 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 Approvazioni e 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 callback viene scelto 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. Ulteriori informazioni

È 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 al successCriteria: 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à.
Cercare l'attività Richiamare l'API REST. Selezionare Aggiungi per aggiungerlo al processo senza agente.
Selezionare il tipo di connessione e la connessione al servizio . Selezionare la metodo HTTP che si vuole usare e quindi selezionare un evento Completamento. È anche possibile definire un criterio di esito positivo per passare l'attività.
Selezionare Salva & coda al termine.