InvokeRESTAPI@1 - Invocar a tarefa da API REST v1

Artigo
07/02/2024

Utilize esta tarefa para invocar uma API REST como parte do pipeline.

Syntax

# 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.

Entradas

connectionType - Tipo de ligação
Alias de entrada: connectedServiceNameSelector. string. Obrigatório. Valores permitidos: connectedServiceName (Genérico), connectedServiceNameARM (Resource Manager do Azure). Valor predefinido: connectedServiceName.

Especifica o tipo de ligação de serviço a utilizar para invocar a API REST. Selecione Azure Resource Manager para invocar uma API de gestão do Azure ou Genérico para todas as outras APIs.

serviceConnection - Ligação de serviço genérica
Alias de entrada: connectedServiceName | genericService. string. Necessário quando connectedServiceNameSelector = connectedServiceName.

Especifica a ligação de serviço genérica que fornece o baseUrl para a chamada e a autorização a utilizar para a tarefa.

serviceConnection - Ligação de serviço genérica
Alias de entrada: connectedServiceName. string. Necessário quando connectedServiceNameSelector = connectedServiceName.

Especifica a ligação de serviço genérica que fornece o baseUrl para a chamada e a autorização a utilizar para a tarefa.

azureServiceConnection - Subscrição do Azure
Alias de entrada: connectedServiceNameARM | azureSubscription. string. Necessário quando connectedServiceNameSelector = connectedServiceNameARM.

Especifica a subscrição do Azure Resource Manager para configurar e utilizar para invocar APIs de gestão do Azure.

azureServiceConnection - Subscrição do Azure
Alias de entrada: connectedServiceNameARM. string. Necessário quando connectedServiceNameSelector = connectedServiceNameARM.

Especifica a subscrição do Azure Resource Manager para configurar e utilizar para invocar APIs de gestão do Azure.

method - Método
string. Obrigatório. Valores permitidos: OPTIONS, , GET, POSTHEAD, PUT, DELETE, , . PATCHTRACE Valor predefinido: POST.

Especifica o método HTTP que invoca a API.

headers - Cabeçalhos
string. Valor predefinido: {\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}.

Define o cabeçalho no formato JSON. O cabeçalho é anexado com o pedido enviado para a API.

body - Corpo
string. Opcional. Utilize quando method != GET && method != HEAD.

Especifica o corpo do pedido para a chamada de função no formato JSON.

urlSuffix - Sufixo de URL e parâmetros
string.

Especifica a cadeia a acrescentar ao baseUrl a partir da ligação de serviço genérica ao efetuar a chamada HTTP.

Exemplo: se o URL da ligação do serviço for https:...TestProj/_apis/Release/releases e o sufixo do URL for /2/environments/1, o URL da ligação do serviço torna-se https:.../TestProj/_apis/Release/releases/2/environments/1. Se o sufixo do URL for ?definitionId=1&releaseCount=1, o URL da ligação do serviço torna-se https//...TestProj/_apis/Release/releases?definitionId=1&releaseCount=1.

waitForCompletion - Evento de conclusão
string. Obrigatório. Valores permitidos: true (Chamada de Retorno), false (ApiResponse). Valor predefinido: false.

Especifica como a tarefa comunica a conclusão. Os valores permitidos são:

false - Resposta da API: comunica a conclusão quando a função devolve êxito dentro de 20 segundos e os critérios de êxito são avaliados como verdadeiros.
true - Chamada de retorno: comunica a conclusão quando o serviço externo faz uma chamada de retorno para atualizar o registo da linha cronológica.

successCriteria - Critérios de êxito
string. Opcional. Utilize quando waitForCompletion = false.

Especifica os critérios de êxito da tarefa. O conteúdo da resposta não influencia o resultado se não forem definidos critérios. Por predefinição, a tarefa passa quando a chamada devolve 200 OK.

Exemplo: para resposta {"status" : "successful"}, a expressão pode ser eq(root['status'], 'successful'). Saiba mais sobre como especificar condições.

Opções de controlo de tarefas

Todas as tarefas têm opções de controlo para além das entradas de tarefas. Para obter mais informações, veja Opções de controlo e propriedades de tarefas comuns.

Variáveis de saída

Nenhum.

Observações

Nota

Esta tarefa só pode ser utilizada numa tarefa sem agente.

É bem-sucedida se a API devolver êxito e a análise do corpo da resposta for bem-sucedida ou quando a API atualizar o registo da linha cronológica com êxito.

A tarefa Invocar API REST não realiza ações de implementação diretamente. Em vez disso, permite-lhe invocar qualquer API REST DE HTTP genérica como parte do pipeline automatizado e, opcionalmente, aguardar que seja concluída.

Configurar uma tarefa invocar a API REST

Para obter mais informações sobre como utilizar esta tarefa, veja Approvals and gates overview (Descrição geral das aprovações e portas).

Que URLs base são utilizados ao invocar as APIs de Gestão do Azure?

As APIs de gestão do Azure são invocadas com ResourceManagerEndpoint do ambiente selecionado. Por exemplo https://management.azure.com , é utilizado quando a subscrição está num ambiente do AzureCloud .

Onde deve um sinal de tarefa ser concluído quando a Chamada de Retorno é escolhida como o evento de conclusão?

Para assinalar a conclusão, o serviço externo deve publicar os dados de conclusão para o ponto final REST dos pipelines seguintes.

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

Veja esta aplicação de cmdline simples para obter detalhes.

Além disso, está disponível uma biblioteca auxiliar de C# para ativar o registo em direto e gerir o estado da tarefa para tarefas sem agente. Saiba mais

Posso utilizar o corpo da resposta como entrada para outra tarefa?

Não, uma vez que esta tarefa é uma tarefa sem agente e utiliza o HttpRequest interno do TFS, que não devolve o conteúdo do pedido HTTP.

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

Neste exemplo, a tarefa é bem-sucedida quando a resposta corresponde ao nosso successCriteria: eq(root[''count''], ''1425'').

Na definição do pipeline, selecione o botão de reticências (...) e, em seguida, selecione Adicionar uma tarefa sem agente.
Na nova tarefa sem agente, selecione o + sinal para adicionar uma nova tarefa.
Pesquisa para a tarefa Invocar API REST. Selecione Adicionar para adicioná-lo à sua tarefa sem agente.
Selecione o Tipo de ligação e a ligação de Serviço. Selecione o Método HTTP que pretende utilizar e, em seguida, selecione um evento de Conclusão. Também pode definir um critério de êxito para transmitir a tarefa.
Selecione Guardar & fila quando terminar.