InvokeRESTAPI@1 – Rest-API v1-Aufgabe aufrufen

Artikel
03/24/2025

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.

Eingänge

connectionType - Verbindungstyp
Eingabealias: connectedServiceNameSelector. string. Erforderlich. Zulässige Werte: connectedServiceName (Generic), 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 generische für alle anderen APIs.

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

Gibt die generische Dienstverbindung an, die baseUrl für den Aufruf und die Autorisierung für die Aufgabe bereitstellt.

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

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

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

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

headers - Kopfzeilen
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 - Body-
string. Wahlfrei. Wird verwendet, 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 an die baseUrl von der generischen Dienstverbindung angefügt werden soll, während der HTTP-Aufruf ausgeführt wird.

Beispiel: Wenn die Dienstverbindungs-URL https:...TestProj/_apis/Release/releases ist und das URL-Suffix /2/environments/1ist, wird die Dienstverbindungs-URL https:.../TestProj/_apis/Release/releases/2/environments/1. Wenn das URL-Suffix ?definitionId=1&releaseCount=1ist, wird die Dienstverbindungs-URL 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 der Abschluss der Aufgabenberichte abgeschlossen wird. Die zulässigen Werte sind:

false - API-Antwort: meldet den Abschluss, wenn die Funktion den Erfolg innerhalb von 20 Sekunden zurückgibt, und die Erfolgskriterien werden als "true" ausgewertet.
true - Rückruf: meldet den Abschluss, wenn der externe Dienst einen Rückruf zum Aktualisieren des Zeitachsendatensatzes vorfertigt.

successCriteria - Erfolgskriterien
string. Wahlfrei. Wird verwendet, wenn waitForCompletion = false.

Gibt die Kriterien des Vorgangs für den Erfolg an. Der Antwortinhalt beeinflusst das Ergebnis nicht, wenn keine Kriterien definiert sind. Standardmäßig wird die Aufgabe übergeben, wenn der Aufruf 200 OKzurückgibt.

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

Aufgabensteuerungsoptionen

Alle Aufgaben verfügen zusätzlich zu ihren Aufgabeneingaben über Steuerungsoptionen. Weitere Informationen finden Sie unter Steuerelementoptionen und allgemeinen Aufgabeneigenschaften.

Ausgabevariablen

Keiner.

Bemerkungen

Hinweis

Diese Aufgabe kann nur in einem agentenlosen Jobverwendet werden.

Erfolgreich, wenn die API Erfolg zurückgibt und die Analyse des Antworttexts erfolgreich ist oder wenn die API den Zeitachsendatensatz erfolgreich aktualisiert.

Die AUFRUFEN der REST-API-Aufgabe führt keine Bereitstellungsaktionen direkt aus. Stattdessen können Sie eine 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 Übersicht über Genehmigungen und Gates.

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

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

Wo sollte ein Aufgabensignal abgeschlossen werden, wenn Callback- 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" }

Weitere Informationen finden Sie in dieser einfachen cmdline-Anwendung.

Darüber hinaus ist eine C#-Hilfsbibliothek verfügbar, um die Liveprotokollierung und das Verwalten des Aufgabenstatus für agentlose Aufgaben zu ermöglichen. Weitere Informationen

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

Nein, da es sich bei dieser Aufgabe um eine agentlose Aufgabe handelt und die interne HttpRequest von TFS verwendet, 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 wählen Sie dann Hinzufügen eines agentlosen Auftragsaus.
Wählen Sie in Ihrem neuen agentlosen Auftrag das + Signieren aus, um eine neue Aufgabe hinzuzufügen.
Suchen Sie nach der aufgabe Aufrufen der REST-API. Wählen Sie Hinzufügen von aus, um sie Ihrem agentlosen Job hinzuzufügen.
Wählen Sie ihren Verbindungstyp und Ihre Dienstverbindungaus. Wählen Sie die HTTP-Methode aus, die Sie verwenden möchten, und wählen Sie dann ein Completion-Ereignisaus. Sie können auch einen Erfolg definieren, um die Aufgabe zu bestehen.
Wählen Sie & Warteschlange speichern aus, wenn Sie fertig sind.