InvokeRESTAPI@1 – Invocar tarefa da API REST v1

  • Artigo

Use essa 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 conexão
Alias de entrada: connectedServiceNameSelector. string. Obrigatórios. Valores permitidos: connectedServiceName (Genérico), connectedServiceNameARM (Azure Resource Manager). Valor padrão: connectedServiceName.

Especifica o tipo de conexão de serviço a ser usado para invocar a API REST. Selecione Azure Resource Manager para invocar uma API de gerenciamento do Azure ou Genérico para todas as outras APIs.


serviceConnection - Conexão de serviço genérica
Alias de entrada: connectedServiceName | genericService. string. Obrigatório quando connectedServiceNameSelector = connectedServiceName.

Especifica a conexão de serviço genérica que fornece o baseUrl para a chamada e a autorização a ser usada para a tarefa.


serviceConnection - Conexão de serviço genérica
Alias de entrada: connectedServiceName. string. Obrigatório quando connectedServiceNameSelector = connectedServiceName.

Especifica a conexão de serviço genérica que fornece o baseUrl para a chamada e a autorização a ser usada para a tarefa.


azureServiceConnection - Assinatura do Azure
Alias de entrada: connectedServiceNameARM | azureSubscription. string. Obrigatório quando connectedServiceNameSelector = connectedServiceNameARM.

Especifica a assinatura de Resource Manager do Azure a ser configurada e usada para invocar APIs de gerenciamento do Azure.


azureServiceConnection - Assinatura do Azure
Alias de entrada: connectedServiceNameARM. string. Obrigatório quando connectedServiceNameSelector = connectedServiceNameARM.

Especifica a assinatura de Resource Manager do Azure a ser configurada e usada para invocar APIs de gerenciamento do Azure.


method - Método
string. Obrigatórios. Valores permitidos: OPTIONS, , GET, HEAD, POST, PUT, DELETE, TRACE, PATCH. Valor padrão: POST.

Especifica o método HTTP que invoca a API.


headers - Cabeçalhos
string. Valor padrão: {\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 a solicitação enviada à API.


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

Especifica o corpo da solicitação para a chamada de função no formato JSON.


urlSuffix - Sufixo e parâmetros de URL
string.

Especifica a cadeia de caracteres a ser acrescentada ao baseUrl da conexão de serviço genérica ao fazer a chamada HTTP.

Exemplo: se a URL de conexão de serviço for https:...TestProj/_apis/Release/releases e o sufixo de URL for /2/environments/1, a URL de conexão de serviço se tornará https:.../TestProj/_apis/Release/releases/2/environments/1. Se o sufixo de URL for ?definitionId=1&releaseCount=1, a URL de conexão de serviço se tornará https//...TestProj/_apis/Release/releases?definitionId=1&releaseCount=1.


waitForCompletion - Evento de conclusão
string. Obrigatórios. Valores permitidos: true (Retorno de chamada) false (ApiResponse). Valor padrão: false.

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

  • false - Resposta da API: relata a conclusão quando a função retorna êxito dentro de 20 segundos e os critérios de êxito são avaliados como verdadeiros.
  • true - Retorno de chamada: relata a conclusão quando o serviço externo faz um retorno de chamada para atualizar o registro linha do tempo.

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

Especifica os critérios da tarefa para êxito. O conteúdo da resposta não influenciará o resultado se nenhum critério for definido. Por padrão, a tarefa é passada quando a chamada retorna 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 controle da tarefa

Todas as tarefas têm opções de controle além de suas entradas de tarefa. Para obter mais informações, consulte Opções de controle e propriedades comuns da tarefa.

Variáveis de saída

Nenhum.

Comentários

Observação

Essa tarefa só pode ser usada em um trabalho sem agente.

Terá êxito se a API retornar êxito e a análise do corpo da resposta for bem-sucedida ou quando a API atualizar o registro linha do tempo com êxito.

A tarefa Invocar API REST não executa ações de implantação diretamente. Em vez disso, ele permite que você invoque qualquer API REST HTTP genérica como parte do pipeline automatizado e, opcionalmente, aguarde até que ela seja concluída.

Configurando uma tarefa invocar a API REST

Para obter mais informações sobre como usar essa tarefa, confira Visão geral de aprovações e portas.

Quais URLs base são usadas ao invocar APIs de Gerenciamento do Azure?

As APIs de gerenciamento do Azure são invocadas usando ResourceManagerEndpoint do ambiente selecionado. Por exemplo https://management.azure.com , é usado quando a assinatura está em um ambiente do AzureCloud .

Em que uma tarefa deve sinalizar a conclusão quando o Retorno de Chamada é escolhido como o evento de conclusão?

Para sinalizar a conclusão, o serviço externo deve fazer POST dos dados de conclusão para o ponto de extremidade REST de pipelines a seguir.

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

Confira este aplicativo cmdline simples para obter detalhes.

Além disso, uma biblioteca auxiliar do C# está disponível para habilitar o registro em log dinâmico e gerenciar status de tarefas para tarefas sem agente. Saiba mais

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

Não, essa tarefa é uma tarefa sem agente e usa HttpRequest interno do TFS, que não retorna o conteúdo da solicitação HTTP.

Exemplo

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 correspondeu ao nosso successCriteria: eq(root[''count'], ''1425'').

Requisitos

Requisito Descrição
Tipos de pipeline YAML, build clássico, versão clássica
Executa em Server, ServerGate
Demandas Nenhum
Funcionalidades Essa tarefa não atende a nenhuma demanda para tarefas subsequentes no trabalho.
Restrições de comando Qualquer
Variáveis configuráveis Qualquer
Versão do agente Todas as versões do agente com suporte.
Categoria da tarefa Implantar