invoke

Verwenden Sie die invoke -Richtlinie, um eine API aufzurufen.

Gateway-Unterstützung

Einschränkung: Es ist nicht möglich, eine Anforderung zwischenzuspeichern, die den Anforderungsheader Authorization enthält.

Tabelle 1. Tabelle, aus der hervorgeht, welche Gateways diese Richtlinie unterstützen, sowie die entsprechende Richtlinienversion
Gateway	Richtlinienversion
DataPower® Gateway (v5 compatible)	1.0.0
DataPower API Gateway	2.0.0 2.1.0 (DataPower API Gateway Version 10.0.1.1 oder höher) 2.2.0 (DataPower API Gateway Version 10.0.2.0 oder höher) 2.3.0 ( DataPower API Gateway Version 10.0.3.0 oder höher)

In diesem Thema wird beschrieben, wie Sie die Richtlinie in Ihrer „ OpenAPI “-Quelle konfigurieren; Einzelheiten zur Konfiguration der Richtlinie in der Benutzeroberfläche der Assembly finden Sie unter „Invoke “.

Produktinfo

Die Richtlinie invoke hat das folgende Format:

- invoke:
  version: version
  title: title
  description: description
  target-url: URL_of_target_API
  backend-type: how_payload_is_sent_to_backend
  tls-profile: TLS_profile_to_be_used
  verb: method_type
  timeout: timeout_value_in_seconds
  compression: is_data_to_be_compressed
  username: username_if_authentication_required
  password: password_if_authentication_required
  output: location_of_the_invoke_result
  cache-key: unique_identifier_of_the_document_cache_entry
  cache-response: cache_behavior
  cache-putpost-response: response_caching_behavior
  cache-ttl: cache_time_to_live
  inject-proxy-headers: are_proxy_headers_sent_to_target_url
  decode-request-params: are_request_parameters_decoded
  encode-plus-char: are_plus_characters_encoded
  keep-payload: is_payload_sent_on_delete
  use-http-10: are_transactions_restricted_to_http_1.0
  chunked-uploads: are_chunked_encoded_documents_sent_to_the_server
  persistent-connection: are_persistent_connections_enabled
  header-control:
        .
        .
        .
    headers_to_copy_to_target_url
        .
        .
        .
  parameter-control:
        .
        .
        .
    parameters_to_copy_to_target_url
        .
        .
        .
  follow-redirects: url_redirection_behavior
  stop-on-error: errors_that_stop_the_flow

Eigenschaften

In der folgenden Tabelle werden die Eigenschaften der invoke-Richtlinie beschrieben:

Tabelle 2. Rufe die Eigenschaften der Richtlinie auf
Eigenschaft	Erforderlich	Beschreibung	Datentyp
version	Ja	Die Versionsnummer der Richtlinie	Zeichenfolge
title	Nein	Ein Titel für die Richtlinie.	Zeichenfolge
description	Nein	Eine Richtlinienbeschreibung.	Zeichenfolge
target-url	Ja	Die URL der Ziel-API. Hinweis: Fügen Sie keine Pfad- oder Abfrageparameter manuell an das Feld target-url in der Aufforderungsrichtlinie an. Wenn diese Parameter in der API-Operation definiert sind, injiziert API Connect sie zur Laufzeit in das Ziel URL. Vermeiden Sie das manuelle Hinzufügen von Werten wie `$(request.search)` oder Pfadsegmenten, da dies zu doppelten oder missgebildeten URLs führen kann. Verwenden Sie die `parameter-control` Richtlinie, um die Einbindung von Abfrageparametern zu verwalten.	Zeichenfolge
backend-type	Nein	Geben Sie einen der folgenden Werte an, um zu bestimmen, wie die Nutzdaten an das Back-End gesendet werden: `detect`: Den Nachrichtentyp erkennen und die Nutzdaten entsprechend an das Back-End senden. `xml`: Packen Sie die Nutzdaten als XML und senden Sie sie. Wenn der Nachrichtentyp nicht XML ist, schlägt die Operation fehl. `json`: Packen Sie die Nutzdaten als JSON und senden Sie sie. Wenn der Nachrichtentyp nicht JSON ist, schlägt die Operation fehl. `binary`: Die Nutzdaten als Binärdaten packen und senden, unabhängig vom Nachrichtentyp. `graphql`: Packen Sie die Nutzdaten als GraphQL und senden Sie sie. Wenn der Nachrichtentyp nicht GraphQL ist, schlägt die Operation fehl. Der Standardwert ist `detect`.	Zeichenfolge
graphql-send-type(Richtlinienversion 2.2.0 und höher)	Ja, wenn backend-type auf `graphql` oder `detect`und verb auf `POST` oder `keep`gesetzt ist.	Geben Sie einen der folgenden Werte an, um zu bestimmen, wie die GraphQL-Nutzdaten an das Back-End gesendet werden: `detect`: Erkennen Sie den Nachrichtentyp und senden Sie die Nutzdaten entsprechend an das Back-End. `graphql`: Packen Sie die Nutzdaten als GraphQL und senden Sie sie. Wenn der Nachrichtentyp nicht GraphQL ist, schlägt die Operation fehl. `json`: Packen Sie die Nutzdaten als JSON und senden Sie sie. Wenn der Nachrichtentyp nicht GraphQL ist, schlägt die Operation fehl. Hinweis: graphql-send-type wird nur unterstützt, wenn backend-type auf `graphql` oder `detect`und verb auf `POST` oder `keep`gesetzt ist.	Zeichenfolge
tls-profile	Nein	Gibt ein TLS-Profil für die sichere Übertragung von Daten an. Hinweis: Wenn Sie die API in der Quellenansicht bearbeiten wollen, stellen Sie sicher, dass der Wert tls-profile das folgende Format hat: name:version. Sie sollte beispielsweise wie folgt aussehen: nameofmytlsclientprofile:1.0.0.	Zeichenfolge
verb	Nein	Der Typ der Operationsmethode. Die gültigen Werte sind im Folgenden aufgelistet: ERLANGEN VERÖFFENTLICHEN EINREIHEN LÖSCHEN PATCH KOPF OPTIONEN Der Standardwert ist `GET`. Wenn jedoch die Eigenschaft aus der Quelle ausgelassen wird, wird die HTTP-Methode aus der eingehenden Anforderung verwendet.	Zeichenfolge
timeout	Nein	Die Zeit, die vor einer Rückantwort vom Endpunkt gewartet werden soll (in Sekunden). Der Standardwert ist `60`.	ganze Zahl
http-version (Richtlinienversion 2.1.0 und höher)	Ja	Die HTTP-Version, die beim Herstellen der Verbindung zum Back-End-Server verwendet wird. Die gültigen Werte sind im Folgenden aufgelistet: `HTTP/1.0` `HTTP/1.1` `HTTP/2`	Zeichenfolge
http2-required (Richtlinienversion 2.1.0 und höher)	Nein	Setzen Sie diese Eigenschaft auf `true` , damit der Server bei einer Verbindung über TLS die Option „ HTTP/2 “ auswählt; andernfalls lehnt der Server die DataPower API Gateway Verbindung ab und die Anfrage schlägt fehl. Für eine Nicht-TLS-Verbindung wird eine Warnung protokolliert, die besagt, dass die Anforderung nicht erzwungen werden kann. Diese Einstellung gilt nur, wenn http-version auf `HTTP/2` gesetzt ist.	boolesch
compression	Nein	Gibt an, ob Daten vor dem Hochladen mithilfe von compress komprimiert werden müssen. Der Standardwert ist `false`.	boolesch
username	Nein	Der Benutzername für die HTTP-Basisauthentifizierung.	Zeichenfolge
password	Nein	Das Kennwort für die HTTP-Basisauthentifizierung.	Zeichenfolge
output	Nein	Der Name einer Variable, die zum Speichern der Antwortdaten von der Anforderung verwendet wird. Standardmäßig wird die Antwort von invoke, d. h. der Hauptteil, die Header, statusCode und statusMessage, in der Variablen `message` gespeichert. Verwenden Sie diese Eigenschaft, um eine alternative Position zum Speichern der invoke-Antwort anzugeben. Auf diese Variable kann dann in anderen Aktionen, wie beispielsweise „map“, verwiesen werden. Hinweis: Wenn die Antwort in `message`gespeichert werden soll, lassen Sie die Eigenschaft output leer und geben Sie nicht den Wert `message`an.	Zeichenfolge
cache-key	Nein	Gibt die eindeutige ID des Dokumentcacheeintrags an.	Zeichenfolge
websocket-upgrade (Richtlinienversion 2.1.0 und höher)	Nein	Setzen Sie diese Eigenschaft auf `true` , um eine HTTP - oder HTTPS -Verbindung auf das WebSocket -Protokoll zu aktualisieren, wenn die vom entsprechenden HTTP - oder HTTPS -Handler auf dem DataPower API Gateway empfangene Anfrage WebSocket (ws) oder WebSocket Secure (wss) verwendet. Hinweis: Diese Eigenschaft ist nur für GraphQL-APIs verfügbar. Die Eigenschaft `websocket-upgrade` wird nicht weiter unterstützt. Um WebSocket-Upgradeanforderungen zu ermöglichen, die API-Verarbeitungsdaten verwalten können, definieren Sie eine Assembly-WebSocket-Upgraderichtlinie. Weitere Informationen finden Sie unter websocket-upgrade.	boolesch
cache-response	Nein	Der Typ der Cacheantwort. Die gültigen Werte sind im Folgenden aufgelistet: `protocol`: Das Cacheverhalten wird über die Cache-Control-Header in der Anforderung und in der Antwort definiert. `no-cache`: Gibt an, dass es kein Caching gibt. Wenn sich das Dokument jedoch bereits im Cache befindet, wird es aus dem Cache abgerufen. `time-to-live`: Gibt an, dass die Antwort für die Dauer der angegebenen Zeit im Cache verbleibt. Der Standardwert ist `protocol`.	Zeichenfolge
cache-putpost-response	Nein	Gibt an, ob die Antwort von POST- und PUT-Anforderungen in den Cache gestellt werden soll. Das Caching der Antwort auf POST- und PUT-Anforderungen kann die Serverauslastung verringern und die Latenzzeit bei der Antwort auf die Clientanforderung reduzieren. Der Standardwert ist `false`.	boolesch
cache-ttl	Nein	Gibt an, wie viele Sekunden die Antwort im Cache verbleibt. Gilt nur, wenn für die Eigenschaft cache-response der Wert `time-to-live` festgelegt ist. Geben Sie einen Wert im Bereich 5 - 31708800 ein. Der Standardwert ist `900`. Hinweis: Wenn sich Benutzer über den Toolkit-Anmeldepfad anmelden (ein URL, der enthält `?from=TOOLKIT`), hat der generierte API-Schlüssel eine feste Gültigkeitsdauer (TTL) von 5 Minuten.	ganze Zahl
inject-proxy-headers	Nein	Wenn diese Option auf "true" gesetzt ist, fügt die `invoke`-Richtlinie die `X-Forwarded-For`-, `X-Forwarded-To`-, `X-Forwarded-Host`- und `X-Forwarded-Proto`-Header in die Anforderung ein, die an die `target-url` gesendet wird. Der Standardwert ist `false`.	boolesch
decode-request-params	Nein	Wenn der Wert "true" festgelegt wird, werden alle Anforderungsparameter, auf die von einer Variablendefinition in der `target-url` der invoke-Richtlinie verwiesen wird, URL-entschlüsselt. Der Standardwert ist `false`.	boolesch
encode-plus-char	Nein	Wenn der Wert "true" festgelegt wird, werden alle "+"-Zeichen in den Abfrageparameterwerden der `target-url` als "%2F" verschlüsselt. Der Standardwert ist `false`.	boolesch
keep-payload	Nein	Wenn diese Eigenschaft auf "true" gesetzt ist, sendet die invoke-Richtlinie Nutzdaten in einer `HTTP DELETE` -Methode. Der Standardwert ist `false`.	boolesch
use-http-10 (gilt nur für die Versicherungsversion „ 2.0.0 “)	Nein	Wenn diese Option auf "true" gesetzt ist, sind HTTP-Transaktionen auf Version 1.0 beschränkt. Der Standardwert ist `false`.	boolesch
chunked-uploads	Nein	Wenn Sie diese Eigenschaft auf `true` setzen, werden "gestückelt" codierte (Chunked-Codierung) Dokumente an den Server gesendet. Wenn das HTTP 1.1-Protokoll verwendet wird, kann der Hauptteil des Dokuments entweder durch `Content-Length` oder durch eine Chunked-Codierung begrenzt werden. Während alle Server `Content-Length` interpretieren können, können viele Anwendungen chunked-codierte Dokumente nicht interpretieren. Aus diesem Grund ist `Content-Length` die Standardmethode. Die Verwendung von `Content-Length` beeinträchtigt die Fähigkeit des DataPower Gateway , vollständig zu streamen. Wenn Sie vollständige Dokumente auf den Zielserver streamen müssen, aktivieren Sie diese Eigenschaft. Bei Aktivierung muss der Server mit RFC 2616 kompatibel sein. Im Gegensatz zu allen anderen HTTP 1.1-Funktionen, die zur Laufzeit ausgehandelt werden können, müssen Sie vorher wissen, dass der Zielserver mit RFC 2616 kompatibel ist. Der Standardwert ist `true`. Hinweis : Die Chunked-Encoding-Methode wird vom HTTP 1.0 -Protokoll nicht unterstützt.	boolesch
persistent-connection (Richtlinienversion 2.3.0 und höher)	Nein	Setzen Sie diese Eigenschaft auf `true` , um dauerhafte Verbindungen für HTTP zu aktivieren, sodass Verbindungen wiederverwendet werden können. Der Standardwert ist `true`.	boolesch
`header-control: type values`	Nein	Gibt die Header in `message.headers` an, die in die Ziel-URL kopiert werden sollen. Wenn die Eigenschaft `type` auf `blocklist` gesetzt ist, listet die Eigenschaft `values` die Header auf, die nicht kopiert werden sollen. Ist die Eigenschaft `values` leer, werden alle Header kopiert. Wenn die Eigenschaft `type` auf `allowlist` gesetzt ist, listet die Eigenschaft `values` die Header auf, die kopiert werden sollen. Die in der Eigenschaft `values` aufgelisteten Elemente haben das Format eines regulären Ausdrucks. Bei den Werten muss die Groß-/Kleinschreibung nicht beachtet werden. Der Standardwert der Eigenschaft `header-control` ist `header-control: type: blocklist values: []` Siehe Beispiele für Headersteuerung .	Objekt
`parameter-control: type values`	Nein	Gibt die Parameter in der eingehenden Anforderung an, die in die Ziel-URL kopiert werden sollen. Wenn die Eigenschaft `type` auf `blocklist` gesetzt ist, listet die Eigenschaft `values` die Parameter auf, die nicht kopiert werden sollen. Wenn die Eigenschaft `type` auf `allowlist` gesetzt ist, listet die Eigenschaft `values` die Parameter auf, die kopiert werden sollen. Ist die Eigenschaft `values` leer, werden keine Parameter kopiert. Die in der Eigenschaft `values` aufgelisteten Elemente haben das Format eines regulären Ausdrucks. Bei den Werten muss die Groß-/Kleinschreibung nicht beachtet werden. Der Standardwert der Eigenschaft `parameter-control` ist `parameter-control: type: allowlist values: []` Siehe Beispiele für Parametersteuerung .	Objekt
follow-redirect	Nein	Gibt das Verhalten an, wenn der Back-End-Server den HTTP -Statuscode `301 Moved Permanently` zurückgibt. Wenn diese Eigenschaft auf `true` gesetzt ist, folgt die `invoke`-Richtlinie der URL-Umleitung, indem sie einen weiteren Aufruf an die URL, die im `Location`-Header der Antwort angegeben ist, ausführt. Wenn diese Eigenschaft auf `false` gesetzt ist, speichert `invoke` den `301`-Statuscode und der API-Aufruf wird als vollständig angesehen. Hinweis Die Eigenschaft `follow-redirect` wird nur vom DataPower API Gatewayunterstützt. Wenn Sie den verwenden DataPower Gateway (v5 compatible), folgt dieser `invoke` immer der Weiterleitung „ URL “; die `proxy` Richtlinie (die vom nicht unterstützt wird DataPower API Gateway) speichert den `301` Statuscode und schließt den API-Aufruf ab, ohne der Weiterleitung „ URL “ zu folgen.	boolesch
stop-on-error	Nein	Listet die Fehler auf, die den Ablauf stoppen, wenn sie während der Richtlinienausführung ausgelöst werden. Wenn für den Fehler ein `catch`-Ablauf konfiguriert ist, wird dieser ausgelöst, um den ausgelösten Fehler abzuwickeln. Wenn ein Fehler ausgelöst wird und keine Fehler für die Eigenschaft Stop on error angegeben sind oder wenn der ausgelöste Fehler keiner der angegebenen Fehler ist, ist der Abschluss der Richtlinienausführung zulässig und der Assembly-Ablauf wird fortgesetzt.	Zeichenfolge

Beispiel

- invoke:
    version: 2.0.0
    title: get the account status
    target-url: https://example.com/accounts/{id}?status={status}
    cache-response: time-to-live
    cache-putpost-response: true
    tls-profile: MyTLSProfile:1.0.0
    verb: POST
    timeout: 60
    compression: false 
    username: MyUser
    password: MyPassword
    stop-on-error:
      - ConnectionError
      - OperationError

`header-control` Beispiele

# copy all headers to the target URL

- invoke:
    target-url: http://myhost/mypath
    header-control:
      type: blocklist
      values: []

# copy all headers except X-Client-ID and Content-Type

- invoke:
    target-url: http://myhost/mypath
    header-control:
      type: blocklist
      values:
        - ^X-Client-ID$
        - ^Content-Type$

# copy no headers

- invoke:
    target-url: http://myhost/mypath
    header-control:
      type: allowlist
      values: []

# copy only the Content-Type header

- invoke:
    target-url: http://myhost/mypath
    header-control:
      type: allowlist
      values:
        - ^Content-Type$

`parameter-control` Beispiele

# copy no request parameters to the target URL

- invoke:
    target-url: http://myhost/path?storeid=3
    parameter-control:
      type: allowlist
      values: []

# append the petid parameter to the target URL
# if the incoming request is http://apigw/org/sandbox/petstore/base?petid=100&display=detailed, 
# the target URL at runtime will be http://myhost/mypath?storeid=3&petid=100

- invoke:
    target-url: http://myhost/path?storeid=3
    parameter-control:
      type: allowlist
      values:
        - ^petid$

# The API definition includes a query parameter petid.
# Incoming request: https://apigw/org/sandbox/pets?petid=123
# API Connect will automatically forward petid to the target URL at runtime.

- invoke:
    target-url: https://myhost/pets
    parameter-control:
      type: allowlist
      values:
        - ^petid$