Compartir vía

InvokeRESTAPI@1: invocar tarea de la API REST v1

  • Artículo

Use esta tarea para invocar una API REST como parte de la canalización.

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 conexión
Alias de entrada: connectedServiceNameSelector. string. Obligatorio. Valores permitidos: connectedServiceName (genérico), connectedServiceNameARM (Azure Resource Manager). Valor predeterminado: connectedServiceName.

Especifica el tipo de conexión de servicio que se va a usar para invocar la API REST. Seleccione Azure Resource Manager para invocar una API de administración de Azure o Genérico para las demás API.


serviceConnection - Conexión de servicio genérico
Alias de entrada: connectedServiceName | genericService. string. Necesario cuando connectedServiceNameSelector = connectedServiceName.

Especifica la conexión de servicio genérica que proporciona el valor baseUrl para la llamada y la autorización que se va a usar para la tarea.


serviceConnection - Conexión de servicio genérico
Alias de entrada: connectedServiceName. string. Necesario cuando connectedServiceNameSelector = connectedServiceName.

Especifica la conexión de servicio genérica que proporciona el valor baseUrl para la llamada y la autorización que se va a usar para la tarea.


azureServiceConnection - Suscripción de Azure
Alias de entrada: connectedServiceNameARM | azureSubscription. string. Necesario cuando connectedServiceNameSelector = connectedServiceNameARM.

Especifica la suscripción de Azure Resource Manager que se va a configurar y usar para invocar las API de administración de Azure.


azureServiceConnection - Suscripción de Azure
Alias de entrada: connectedServiceNameARM. string. Necesario cuando connectedServiceNameSelector = connectedServiceNameARM.

Especifica la suscripción de Azure Resource Manager que se va a configurar y usar para invocar las API de administración de Azure.


method - Método
string. Obligatorio. Valores permitidos: OPTIONS, GET, HEAD, POST, DELETEPUT, TRACE. PATCH Valor predeterminado: POST.

Especifica el método HTTP que invoca la API.


headers - Encabezados
string. Valor predeterminado: {\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 el encabezado en formato JSON. El encabezado se adjunta a la solicitud enviada a la API.


body - Cuerpo
string. Opcional. Use cuando method != GET && method != HEAD.

Especifica el cuerpo de la solicitud para la llamada de función en formato JSON.


urlSuffix - Sufijo y parámetros de dirección URL
string.

Especifica la cadena que se va a anexar a baseUrl desde la conexión de servicio genérica mientras realiza la llamada HTTP.

Ejemplo: si la dirección URL de conexión del servicio es https:...TestProj/_apis/Release/releases y el sufijo de dirección URL es /2/environments/1, la dirección URL de conexión del servicio se convierte en https:.../TestProj/_apis/Release/releases/2/environments/1. Si el sufijo de dirección URL es ?definitionId=1&releaseCount=1, la dirección URL de conexión del servicio se convierte en https//...TestProj/_apis/Release/releases?definitionId=1&releaseCount=1.


waitForCompletion - Evento de finalización
string. Obligatorio. Valores permitidos: true (Devolución de llamada), false (ApiResponse). Valor predeterminado: false.

Especifica cómo notifica la finalización de la tarea. Los valores permitidos son:

  • false - Respuesta de LA API: notifica la finalización cuando la función devuelve éxito en un plazo de 20 segundos y los criterios de éxito se evalúan como true.
  • true - Devolución de llamada: notifica la finalización cuando el servicio externo realiza una devolución de llamada para actualizar el registro de escala de tiempo.

successCriteria - Criterios de éxito
string. Opcional. Use cuando waitForCompletion = false.

Especifica los criterios de éxito de la tarea. El contenido de la respuesta no influye en el resultado si no se define ningún criterio. De forma predeterminada, la tarea pasa cuando la llamada devuelve 200 OK.

Ejemplo: para la respuesta {"status" : "successful"}, la expresión puede ser eq(root['status'], 'successful'). Obtenga más información sobre cómo especificar condiciones.


Opciones de control de tareas

Todas las tareas tienen opciones de control además de las entradas de tareas. Para obtener más información, vea Opciones de control y propiedades de tareas comunes.

Variables de salida

Ninguno.

Comentarios

Nota

Esta tarea solo se puede usar en un trabajo sin agente.

Se ejecuta correctamente si la API devuelve éxito y el análisis del cuerpo de la respuesta se realiza correctamente o cuando la API actualiza el registro de escala de tiempo con éxito.

La tarea Invocar API REST no realiza acciones de implementación directamente. En su lugar, permite invocar cualquier API REST HTTP genérica como parte de la canalización automatizada y, opcionalmente, esperar a que se complete.

Configuración de una tarea invocar API REST

Para obtener más información sobre el uso de esta tarea, consulte Información general sobre aprobaciones y validaciones.

¿Qué direcciones URL base se usan al invocar las API de administración de Azure?

Las API de administración de Azure se invocan mediante ResourceManagerEndpoint del entorno seleccionado. Por ejemplo https://management.azure.com , se usa cuando la suscripción está en un entorno de AzureCloud .

¿Dónde debe señalarse la finalización de una tarea cuando se elige Devolución de llamada como evento de finalización?

Para indicar la finalización, el servicio externo debe publicar los datos de finalización en el siguiente punto de conexión REST de las canalizaciones.

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

Consulte esta sencilla aplicación cmdline para obtener información específica.

Además, hay disponible una biblioteca auxiliar de C# para habilitar el registro en directo y administrar el estado de la tarea para las tareas sin agente. Más información

¿Puedo usar el cuerpo de la respuesta como entrada para otra tarea?

No, puesto que esta tarea es una tarea sin agente y usa una httpRequest interna de TFS, que no devuelve el contenido de la solicitud HTTP.

Ejemplo

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

En este ejemplo, la tarea se realiza correctamente cuando la respuesta coincide con : successCriteriaeq(root[''count''], ''1425'')).

Requisitos

Requisito Descripción
Tipos de canalización YAML, compilación clásica, versión clásica
Se ejecuta en Server, ServerGate
Peticiones None
Capabilities Esta tarea no satisface ninguna demanda de tareas posteriores en el trabajo.
Restricciones de comandos Any
Variables que se pueden establecer Any
Versión del agente Todas las versiones de agente compatibles.
Categoría de la tarea: Implementación