InvokeRESTAPI@1 : Aufrufen der REST-API v1-Aufgabe

Artikel
07/02/2024

Verwenden Sie diese Aufgabe, um eine REST-API als Teil Ihrer Pipeline aufzurufen.

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.

Eingaben

connectionType - Verbindungstyp
Eingabealias: connectedServiceNameSelector. string. Erforderlich. Zulässige Werte: connectedServiceName (Generisch), connectedServiceNameARM (Azure Resource Manager). Standardwert. connectedServiceName.

Gibt den Dienstverbindungstyp an, der zum Aufrufen der REST-API verwendet werden soll. Wählen Sie Azure Resource Manager aus, um eine Azure-Verwaltungs-API aufzurufen, oder Generisch für alle anderen APIs.

serviceConnection - Generische Dienstverbindung
Eingabealias: connectedServiceName | genericService. string. Erforderlich, wenn connectedServiceNameSelector = connectedServiceName.

Gibt die generische Dienstverbindung an, die die baseUrl für den Aufruf und die Autorisierung bereitstellt, die für den Task verwendet werden soll.

serviceConnection - Generische Dienstverbindung
Eingabealias: connectedServiceName. string. Erforderlich, wenn connectedServiceNameSelector = connectedServiceName.

Gibt die generische Dienstverbindung an, die die baseUrl für den Aufruf und die Autorisierung bereitstellt, die für den Task verwendet werden soll.

azureServiceConnection - Azure-Abonnement
Eingabealias: connectedServiceNameARM | azureSubscription. string. Erforderlich, wenn connectedServiceNameSelector = connectedServiceNameARM.

Gibt das Azure Resource Manager-Abonnement an, das konfiguriert und zum Aufrufen von Azure-Verwaltungs-APIs verwendet werden soll.

azureServiceConnection - Azure-Abonnement
Eingabealias: connectedServiceNameARM. string. Erforderlich, wenn connectedServiceNameSelector = connectedServiceNameARM.

Gibt das Azure Resource Manager-Abonnement an, das konfiguriert und zum Aufrufen von Azure-Verwaltungs-APIs verwendet werden soll.

method - Methode
string. Erforderlich. Zulässige Werte: OPTIONS, GET, HEAD, PUTPOST, DELETE, TRACE, , PATCH. Standardwert. POST.

Gibt die HTTP-Methode an, die die API aufruft.

headers - Header
string. Standardwert. {\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}.

Definiert den Header im JSON-Format. Der Header wird mit der an die API gesendeten Anforderung angefügt.

body - Körper
string. Optional. Verwenden Sie , wenn method != GET && method != HEAD.

Gibt den Anforderungstext für den Funktionsaufruf im JSON-Format an.

urlSuffix - URL-Suffix und -Parameter
string.

Gibt die Zeichenfolge an, die während des HTTP-Aufrufs von der generischen Dienstverbindung an die baseUrl angefügt werden soll.

Beispiel: Wenn die Dienstverbindungs-URL https:...TestProj/_apis/Release/releases und das URL-Suffix lautet, wird /2/environments/1die Dienstverbindungs-URL zu https:.../TestProj/_apis/Release/releases/2/environments/1. Wenn das URL-Suffix lautet ?definitionId=1&releaseCount=1, wird die Dienstverbindungs-URL zu https//...TestProj/_apis/Release/releases?definitionId=1&releaseCount=1.

waitForCompletion - Abschlussereignis
string. Erforderlich. Zulässige Werte: true (Rückruf), false (ApiResponse). Standardwert. false.

Gibt an, wie die Aufgabe den Abschluss meldet. Zulässige Werte sind:

false - API-Antwort: Meldet den Abschluss, wenn die Funktion innerhalb von 20 Sekunden den Erfolg zurückgibt und die Erfolgskriterien als "true" ausgewertet werden.
true - Rückruf: Meldet den Abschluss, wenn der externe Dienst einen Rückruf vornimmt, um den Zeitleiste Datensatz zu aktualisieren.

successCriteria - Erfolgskriterien
string. Optional. Verwenden Sie , wenn waitForCompletion = false.

Gibt die Erfolgskriterien der Aufgabe an. Der Antwortinhalt hat keinen Einfluss auf das Ergebnis, wenn keine Kriterien definiert sind. Standardmäßig wird der Task übergeben, wenn der Aufruf zurückgibt 200 OK.

Beispiel: Für die Antwort {"status" : "successful"}kann der Ausdruck sein eq(root['status'], 'successful'). Erfahren Sie mehr über das Angeben von Bedingungen.

Optionen für die Vorgangskontrolle

Alle Vorgänge verfügen zusätzlich zu ihren Eingaben über Steuerungsoptionen. Weitere Informationen finden Sie unter Steuerungsoptionen und allgemeine Aufgabeneigenschaften.

Ausgabevariablen

Keine.

Hinweise

Hinweis

Diese Aufgabe kann nur in einem Auftrag ohne Agent verwendet werden.

Ist erfolgreich, wenn die API eine Erfolgsmeldung zurückgibt und das Parsen des Antworttexts erfolgreich war oder wenn die API den Zeitachsendatensatz erfolgreich aktualisiert.

Die Aufgabe „REST-API aufrufen“ führt keine direkten Bereitstellungsaktionen aus. Stattdessen können Sie eine beliebige generische HTTP-REST-API als Teil der automatisierten Pipeline aufrufen und optional warten, bis sie abgeschlossen ist.

Konfigurieren einer Aufruf-REST-API-Aufgabe

Weitere Informationen zur Verwendung dieser Aufgabe finden Sie unter Übersicht über Genehmigungen und Gates.

Welche Basis-URLs werden beim Aufrufen von Azure-Verwaltungs-APIs verwendet?

Azure-Verwaltungs-APIs werden mithilfe von ResourceManagerEndpoint der ausgewählten Umgebung aufgerufen. Wird beispielsweise https://management.azure.com verwendet, wenn sich das Abonnement in einer AzureCloud-Umgebung befindet.

Wo sollte eine Aufgabe den Abschluss signalisieren, wenn Rückruf als Abschlussereignis ausgewählt wird?

Um den Abschluss zu signalisieren, sollte der externe Dienst POST-Abschlussdaten an den folgenden Pipelines-REST-Endpunkt senden.

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

Einzelheiten finden Sie in dieser einfachen Cmdline-Anwendung.

Darüber hinaus ist eine C#-Hilfsbibliothek verfügbar, um die Liveprotokollierung und -verwaltung des Aufgabenstatus für Aufgaben ohne Agent zu aktivieren. Weitere Informationen

Kann ich den Antworttext als Eingabe für eine andere Aufgabe verwenden?

Nein, da es sich bei dieser Aufgabe um eine Aufgabe ohne Agent handelt und die interne HTTP-Anforderung von TFS verwendet wird, die den Inhalt der HTTP-Anforderung nicht zurückgibt.

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

In diesem Beispiel ist die Aufgabe erfolgreich, wenn die Antwort mit unserem successCriteriaübereinstimmt: eq(root[''count''], ''1425'')..

Wählen Sie in Ihrer Pipelinedefinition die Schaltfläche mit den Auslassungspunkten (...) und dann Auftrag ohne Agent hinzufügen aus.
Wählen Sie in Ihrem neuen Auftrag ohne Agent das Pluszeichen (+) aus, um eine neue Aufgabe hinzuzufügen.
Suchen Sie nach der Aufgabe REST-API aufrufen. Wählen Sie Hinzufügen aus, um sie Ihrem Auftrag ohne Agent hinzuzufügen.
Wählen Sie Ihren Verbindungstyp und Ihre Dienstverbindung aus. Wählen Sie unter Methode die HTTP-Methode aus, die Sie verwenden möchten, und wählen Sie anschließend ein Abschlussereignis aus. Sie können auch ein Erfolgskriterium für die Aufgabe definieren.
Wählen Sie speichern & Warteschlange aus, wenn Sie fertig sind.