Migrationsoptionen für DataPower-API-Gateway konfigurieren

Wenn Sie APIs für das DataPower-API-Gateway konvertieren, können Sie die Standardkonfiguration für die Migration akzeptieren oder Konfigurationsparameter angeben.

Sie können Konfigurationsparameter für die Migration entweder über eine YAML-Konfigurationsdatei oder über die Befehlszeile angeben, aber nicht beides. Die Datei config.yml muss sich im gleichen Verzeichnis befinden wie das Migrationsdienstprogramm. Sie können angeben, dass diese Datei verwendet werden soll, wenn das Migrationsdienstprogramm mit dem Befehl apicm mit der Option port-to-apigw aufgerufen wird, wie im folgenden Beispiel gezeigt.
 ./apicm archive:port-to-apigw <path> --use-config-file=true
Ist die Verwendung der Konfigurationsdatei nicht angegeben, verwendet das Migrationsdienstprogramm Parameter, die über die Befehlszeile angegeben wurden. Wurden keine Parameter angegeben, werden die Standardparameter verwendet.

Einige dieser port-to-apigw-Konfigurationsparameter hängen von einer bestimmten DataPower-Implementierung ab, damit sie funktionieren. Weitere Informationen finden Sie in der folgenden Tabelle; mit diesen Informationen können Sie sicherstellen, dass Sie über die richtige Version von DataPower für die Parameter verfügen, die Sie verwenden möchten.

Tabelle 1. Konfigurationsoptionen für die Migration
Parameter Gültige Werte Erforderliche DataPower-Version Beschreibung
activity-log-policy activity-log_1.5.0, set-variable_2.0.0 DP 10.0.4.0+ Definiert, wie die v5 -Aktivitätenprotokollrichtlinie verarbeitet werden soll, wenn das Migrationsdienstprogramm die API-Assembly neu schreibt. Der Standardwert ist activity-log_1.5.0, wodurch die Aktivitätenprotokollversion in 1.5.0geändert wird. Wenn der Wert auf set-variable_2.0.0gesetzt wird, legt das Migrationsdienstprogramm Kontextvariablen auf der Basis des Werts der Konfigurationswerte für den Inhalt des Aktivitätenprotokolls und den Fehlerinhalt fest.
chunked-uploads true / false

Der Standardwert ist false.

Für invoke_1.5.0: 10.0.1.1+, 10.0.2.0+

Für invoke_2.0.0: 10.0.0.0+

Wenn eine invoke_1.5.0- oder proxy_1.5.0-Richtlinie in einer Assembly in der API vorhanden ist, setzen Sie chunked-uploads auf true, um die Codierung "chunked" für HTTP 1.1-Anforderungen an den Zielserver zu aktivieren.

Wenn eine invoke_2.0.0-Richtlinie in einer Assembly nach der Migration vorhanden ist, setzen Sie chunked-uploads explizit für die Richtlinie auf false, da der Standardwert für chunked-uploads im API-Gateway true ist.
client-id-header-override Zeichenfolge. Die Zeichenfolge darf keine Leerzeichen enthalten. Befolgen Sie die Richtlinien für apiKey name:.

Kein Standardwert.

 10.0.0.0+

Überschreiben Sie den vorhandenen Wert für X-IBM-Client_Id mit dem neuen Wert. In API-Gateway ermöglicht x-key-type die Definition von angepassten Namen für client_id und client_secret.

Beispiel:
--client-id-header-override="acme-foo"
In diesem Beispiel wird die Eigenschaft securityDefinitions geändert von:
foo:
    type: apiKey
    name: X-IBM-Client-Id
    in: header
In den folgenden Code:
foo:
    type: apiKey
    name: acme-foo
    in: header
    x-key-type: client_id
Aufrufe an diese API müssen acme-foo: <client-id> anstelle des ursprünglichen X-IBM-Client-Id: <client-id>im Anforderungsheader bereitstellen.
client-id-query-override Zeichenfolge. Die Zeichenfolge darf keine Leerzeichen enthalten. Befolgen Sie die Richtlinien für apiKey name:.

Kein Standardwert.

 10.0.0.0+

Überschreiben Sie den vorhandenen Wert für client_id mit dem neuen Wert. In API-Gateway ermöglicht x-key-type die Definition von angepassten Namen für client_id und client_secret.

Beispiel:
--client-id-query-override="acme-foo"
In diesem Beispiel wird die Eigenschaft securityDefinitions geändert von:
foo:
    type: apiKey
    name: client_id
    in: query
In den folgenden Code:
foo:
    type: apiKey
    name: acme-foo
    in: query
    x-key-type: client_id
Aufrufe an diese API müssen ?acme-foo=<client-id> im Abfrageparameter anstelle des ursprünglichen ?client_id=<client-id>angeben.
client-secret-header-override Zeichenfolge. Die Zeichenfolge darf keine Leerzeichen enthalten. Befolgen Sie die Richtlinien für apiKey name:.

Kein Standardwert.

 10.0.0.0+

Überschreiben Sie den vorhandenen Wert für X-IBM-Client-Secret mit dem neuen Wert. In API-Gateway ermöglicht x-key-type die Definition von angepassten Namen für client_id und client_secret.

Beispiel:
--client-secret-header-override="acme-foo"
In diesem Beispiel wird die Eigenschaft securityDefinitions geändert von:
foo:
    type: apiKey
    name: X-IBM-Client-Secret
    in: header
In den folgenden Code:
 foo:
    type: apiKey
    name: acme-foo
    in: header
    x-key-type: client_secret
Aufrufe an diese API müssen acme-foo: <client-secret> anstelle des ursprünglichen X-IBM-Client-Secret: <client-secret>im Anforderungsheader bereitstellen.
client-secret-query-override Zeichenfolge. Die Zeichenfolge darf keine Leerzeichen enthalten. Befolgen Sie die Richtlinien für apiKey name:.

Kein Standardwert.

 10.0.0.0+

Überschreiben Sie den vorhandenen Wert für client_secret mit dem neuen Wert. In API-Gateway ermöglicht x-key-type die Definition von angepassten Namen für client_id und client_secret.

Beispiel:
--client-secret-query-override="acme-foo"
In diesem Beispiel wird die Eigenschaft securityDefinitions geändert von:
foo:
    type: apiKey
    name: client_secret
    in: query
In den folgenden Code:
foo:
    type: apiKey
    name: acme-foo
    in: query
    x-key-type: client_secret
Aufrufe an diese API müssen ?acme-foo=<client-secret> im Abfrageparameter anstelle des ursprünglichen ?client_secret=<client-secret>angeben.
copy-id-headers-to-message true / false

Der Standardwert ist false.

 10.0.1.1+, 10.0.2.0+

Wenn diese Option auf true gesetzt ist, wird der client-id-Header von request.headers in message.headers kopiert, um an den Back-End-Server übergeben zu werden. Setzen Sie diesen Parameter auf true, wenn Ihre invoke-Back-End-Services erwarten, dass die client-id übergeben wird.
custom-policies-scope catalog / global

Der Standardwert ist catalog.

 10.0.0.0+

Wenn diese Option auf catalog gesetzt ist, wird der ursprüngliche v5-Katalog oder v5-kompatible Katalog, der die angepasste Richtlinie enthält, für die Weitergabe an den Zielkatalog und die Organisation im API-Gateway bereitgestellt.

Wenn diese Option auf global gesetzt ist, wird die angepasste Richtlinie für die Weitergabe an das API-Gateway bereitgestellt und für alle Organisationen und Kataloge innerhalb dieses Gateways sichtbar.

archive:port-to-apigw konfiguriert die angepassten Richtlinien für die Weitergabe an das API-Gateway, führt die Weitergabe aber nicht durch. Wenn der Bereich global verwendet wird, gibt archive:push der Verwaltungsorganisation alle angepassten Richtlinien weiter, die den konfigurierten Gateways zugeordnet sind. Wenn der Bereich catalog verwendet wird, initialisiert archive:push der Verwaltungsorganisation die angepassten Richtlinien auf dem Gateway. Ein nachfolgendes archive:push der Providerorganisation ist erforderlich,um die angepassten Richtlinien in den Katalogen zugänglich zu machen, die in den Providerorganisationen enthalten sind.

Hinweis: Mögliche Konflikte zwischen angepassten Richtlinien mit demselben Namen und derselben Version werden gemäß den folgenden Regeln aufgelöst:
  • Wenn die Option auf global gesetzt ist und zwei Richtlinien unter demselben Gateway-Service denselben Namen, dieselbe Version und denselben md5-Hashwert haben, werden die Duplikate gelöscht und eine Nachricht wird generiert.
  • Wenn der Wert auf global gesetzt ist und zwei Richtlinien unter demselben Gateway-Service denselben Namen, dieselbe Version und einen anderen md5-Hashwert haben, kann der globale Bereich nicht angewendet werden. Der Katalogbereich wird verwendet und eine Warnung wird generiert.
  • Wenn catalogfestgelegt ist, wird <orgname>_<catname>_ an den ZIP-Dateinamen angehängt, um die Eindeutigkeit zu erhalten.
deploy-policies Beliebige Kombination der folgenden Werte: gatewayscript_1.0.0,if_1.5.0, invoke_1.5.0, proxy_1.5.0,redact_1.5.0, switch_1.5.0, validate-usernametoken_1.0.0, xslt_1.0.0

Die Standardwerte lauten wie folgt: if_1.5.0, invoke_1.5.0, proxy_1.5.0, redact_1.5.0, switch_1.5.0, validate-usernametoken_1.0.0, xslt_1.0.0

Für invoke_1.5.0, proxy_1.5.0, gatewayscript_1.0.0und xslt_1.0.0: 10.0.0.0+

Für if_1.5.0 und switch_1.5.0: 10.0.1.1+, 10.0.2.0+

Für redact_1.5.0: 10.0.3.0+

validate-usernametoken_1.0.0: 10.0.1.3+, 10.0.2.0+

Definiert, welche rückwärtskompatiblen Richtlinien von DataPower für API Manager zugänglich gemacht werden sollten.

Hinweis: Alle traditionellen Richtlinien, die in der Datei config.yml oder mit dem Befehl apicm angegeben werden, müssen ebenfalls mit deploy-policiesangegeben werden. Werden diese Richtlinien nicht durch die Verwendung von deploy-policies angegeben, wird ein Fehler zurückgegeben.
emulate-v4-plan-rate-limit true / false

Der Standardwert ist false.

 10.0.1.2+, 10.0.2.0+

Bestimmt, ob alle APIs die v4-Planratenbegrenzung emulieren. Wenn diese Option auf true gesetzt ist, teilen die API-Operationen die Ratenbegrenzung nicht. Diese Einstellung stimmt mit dem Verhalten der v5-Option x-ibm-gateway-emulate-v4-plan-rate-limit überein.
enable-api-logging true / false

Der Standardwert ist true.

 10.0.0.0+

Protokollieren Sie alle Änderungen, die das Migrationsdienstprogramm vornimmt, wenn Sie APIs umschreiben. Diese Änderungen werden als Kommentare in der API-YAML-Datei protokolliert.
enforce-required-params true / false

Der Standardwert ist false.

 10.0.1.1+, 10.0.2.0+

Wenn diese Option auf true gesetzt ist, werden die erforderlichen Parameter erzwungen. Dies ist das Standardverhalten im API-Gateway. Wenn diese Option auf false gesetzt ist, werden die erforderlichen Parameter nicht erzwungen, auch wenn das erforderliche Parameter-Kontrollkästchen ausgewählt ist.
gatewayscript-policy Einer der folgenden Werte: gatewayscript_1.0.0, gatewayscript_2.0.0

Der Standardwert ist gatewayscript_2.0.0.

 10.0.0.0+

Definiert, welche gatewayscript-Richtlinie das Migrationsdienstprogramm verwendet, wenn die API-Assembly neu geschrieben wird.

gatewayscript_1.0.0: Eine benutzerdefinierte Richtlinie, die vom Migrationsdienstprogramm erstellt wurde. Diese Richtlinie verwendet die v5-MPGW-Verarbeitungsregel. Verwenden Sie gatewayscript_1.0.0, wenn die gatewayscript-Richtlinie von v5-MPGW-Funktionen abhängt, wie z. B. Lastausgleichsgruppen oder XML-Manager-Einstellungen.

gatewayscript_2.0.0: Das Migrationsdienstprogramm schreibt die vorhandene API auf gatewayscript 2.0.0 neu. Diese Richtlinie unterstützt das Modul header-metadata für die Kompatibilität mit DataPower® Gateway (v5 compatible).

Die Angabe von gatewayscript_2.0.0 kann zu Migrationsfehlern oder Laufzeitfehlern führen. Verwenden Sie gatewayscript_2.0.0, wenn Sie alle vom Migrationsdienstprogramm vorgenommenen Änderungen in der API-YAML-Datei prüfen und verifizieren können.
if-policy Einer der folgenden Werte: if_1.5.0, switch_2.0.0

Der Standardwert ist if_1.5.0.

Für if_1.5.0: 10.0.1.1+, 10.0.2.0+

Für switch_2.0.0: 10.0.0.0+

Definiert, welche if-Richtlinie das Migrationsdienstprogramm verwendet, wenn die API-Assembly neu geschrieben wird.

if_1.5.0: Das Migrationsdienstprogramm schreibt die vorhandene API in if 1.5.0 neu.

switch_2.0.0: Das Migrationsdienstprogramm schreibt die vorhandene API in switch 2.0.0 neu. Die Angabe von switch_2.0.0 kann zu Migrationsfehlern oder Laufzeitfehlern führen. Verwenden Sie switch_2.0.0, wenn Sie alle vom Migrationsdienstprogramm vorgenommenen Änderungen in der API-YAML-Datei prüfen und verifizieren können.
invoke-policy Einer der folgenden Werte: invoke_1.5.0, invoke_2.0.0

Der Standardwert ist invoke_1.5.0.

 10.0.0.0+

Definiert, welche invoke-Richtlinie das Migrationsdienstprogramm verwendet, wenn die API-Assembly neu geschrieben wird.

invoke_1.5.0: Das Migrationsdienstprogramm schreibt die vorhandene API auf invoke 1.5.0 neu.

invoke_2.0.0: Das Migrationsdienstprogramm schreibt die vorhandene API auf invoke 2.0.0 neu. Die Angabe von invoke_2.0.0 kann zu Migrationsfehlern oder Laufzeitfehlern führen. Verwenden Sie invoke_2.0.0, wenn Sie alle vom Migrationsdienstprogramm vorgenommenen Änderungen in der API-YAML-Datei prüfen und verifizieren können.
no-rename true / false

Der Standardwert ist false.

 10.0.0.0+

Legt fest, ob das Suffix " -apigw an Artefaktdateinamen oder innerhalb von Artefakten angehängt werden soll. Bei der Einstellung " false werden die Dateien mit dem Suffix " -apigw umbenannt und die ursprünglich entpackten v5c werden ebenfalls mit den portierten API Gateway überschrieben.

Bei Verwendung dieser Option wird eine y/n -Eingabeaufforderung angezeigt. Verwenden Sie die Option --accept-no-rename-deletion , um diese Eingabeaufforderung zu umgehen.
no-retitle true / false

Der Standardwert ist false.

 10.0.0.0+

Definiert, ob das Suffix -apigw an den title der migrierten API, des Produkts oder des OAuth-Providers angehängt werden soll. Setzen Sie diese Option auf true, wenn der title der migrierten API, des Produkts oder des OAuth-Providers dem ursprünglichen title in der v5-kompatiblen YAML-Datei entsprechen soll.

Beachten Sie, dass der x-ibm-name von API-Gateway-APIs und -Produkten immer das Suffix -apigw enthält. Die Option no-retitle gilt nur für den title.
optimize-gws true / false

Der Standardwert ist false.

 10.0.0.0+

Wenn diese Option auf true gesetzt ist, werden die gatewayscript-Richtlinien so geändert, dass v5-Funktionen API-Gateway-Funktionen zugeordnet werden.

Das Setzen von optimize-gws auf true ist nur für die gatewayscript_2.0.0-Richtlinie gültig. Ist der Wert für gatewayscript_1.0.0 auf true gesetzt, wird ein Fehler generiert.

Hinweis: Wenn Sie optimize-gws auf true setzen, können Leistungsverbesserungen auftreten. Die Änderungen an gatewayscript-Richtlinien durch das Migrationsdienstprogramm können jedoch Probleme verursachen. Wenn Sie diese Einstellung verwenden, überprüfen Sie nach der Migration alle Änderungen an den gatewayscript-Richtlinien.
proxy-policy Einer der folgenden Werte: proxy_1.5.0, invoke_2.0.0

Der Standardwert ist proxy_1.5.0.

 10.0.0.0+

Definiert, welche proxy-Richtlinie das Migrationsdienstprogramm verwendet, wenn die API-Assembly neu geschrieben wird.

proxy_1.5.0: Das Migrationsdienstprogramm schreibt die vorhandene API auf proxy 1.5.0 neu.

invoke_2.0.0: Das Migrationsdienstprogramm konvertiert die proxy-Richtlinie in invoke 2.0.0. Die Angabe von invoke_2.0.0 kann zu Migrationsfehlern oder Laufzeitfehlern führen. Verwenden Sie invoke_2.0.0, wenn Sie alle vom Migrationsdienstprogramm vorgenommenen Änderungen in der API-YAML-Datei prüfen und verifizieren können.
redact-policy Einer der folgenden Werte: redact_1.5.0, redact_2.0.0

Der Standardwert ist redact_1.5.0.

 10.0.3.0+

Definiert, welche Schwärzungsrichtlinie das Migrationsdienstprogramm beim Umschreiben der API-Assembly verwendet.

redact_1.5.0: Das Migrationsdienstprogramm schreibt die vorhandene API auf redact 1.5.0 neu.

redact_2.0.0: Das Migrationsdienstprogramm schreibt die vorhandene API auf redact 2.0.0 neu. Die Angabe von redact_2.0.0 kann Migrationsfehler oder Laufzeitfehler verursachen, einschließlich Änderungen an Neubearbeitungen, insbesondere bei Neubearbeitungen für JSON-Nutzdaten. Verwenden Sie redact_2.0.0 , wenn Sie alle vom Migrationsdienstprogramm in der API-YAML-Datei vorgenommenen Änderungen überprüfen und überprüfen können.
repair-wsdl-apis true / false

Der Standardwert ist true.

 10.0.1.1+, 10.0.2.0+

Wenn eine aus V5 portierte API aus WSDL erstellt wird, wird die WSDL gelesen und auf Richtigkeit geprüft. Wenn repair-wsdl-apis auf truegesetzt ist, werden die API und WSDL automatisch repariert. Wenn die WSDL-ZIP-Datei beispielsweise nicht benötigte Dateien enthält, werden sie automatisch entfernt, wenn repair-wsdl-apis auf truegesetzt ist.
return-v5-responses true / false

Der Standardwert ist false.

 10.0.1.1+, 10.0.2.0+

Wenn diese Option auf true gesetzt ist, werden OAuth-bezogene Nachrichten im v5-Antwortformat ausgegeben. Wenn diese Option auf false gesetzt ist, werden OAuth-bezogene Antwortnachrichten im API-Gateway-Antwortformat ausgegeben.
switch-policy switch_1.5.0, switch_2.0.0

Der Standardwert ist switch_1.5.0.

Für switch_1.5.0: 10.0.1.1+, 10.0.2.0+

Für switch_2.0.0: 10.0.0.0+

Definiert, welche Switch-Richtlinie das Migrationsdienstprogramm beim Umschreiben der API-Assembly verwendet.

switch_1.5.0: Das Migrationsdienstprogramm schreibt die vorhandene API in switch 1.5.0 neu.

switch_2.0.0: Das Migrationsdienstprogramm schreibt die vorhandene API in switch 2.0.0 neu. Die Angabe von switch_2.0.0 kann zu Migrationsfehlern oder Laufzeitfehlern führen. Verwenden Sie switch_2.0.0, wenn Sie alle vom Migrationsdienstprogramm vorgenommenen Änderungen in der API-YAML-Datei prüfen und verifizieren können.
use-config-file true / false

Der Standardwert ist false.

 10.0.0.0+

Verwenden Sie die Datei config.yml, die sich in demselben Verzeichnis befindet wie die Binärdatei apicm, die ausgeführt wird. Wird diese Datei verwendet, können Konfigurationsoptionen nicht über die Befehlszeile festgelegt werden. Der Zweck der Konfigurationsdatei ist die Angabe der Befehlseingaben auf dieser Seite in einem übersichtlichen Dateiformat (YAML).
v5-request-headers true / false

Der Standardwert ist true.

 10.0.1.2+, 10.0.2.0+

Bei truewerden die folgenden v5-compatible Anforderungsheader festgelegt: Via, X-Global-Transaction-ID, X-Client-IP. Bei der Einstellung falsewerden diese Anforderungsheader nicht festgelegt.
validate-usernametoken-policy validate-usernametoken_1.0.0

Der Standardwert ist leer.

 10.0.1.3+, 10.0.2.0+

Definiert, ob die Emulationsrichtlinie validate-usernametoken v5 verwendet werden soll, wenn das Migrationsdienstprogramm die API-Assembly neu schreibt. Wenn leer, führt das Migrationsdienstprogramm keine Aktion für die Richtlinie aus.
xslt-policy Einer der folgenden Werte: xslt_1.0.0, xslt_2.0.0

Der Standardwert ist xslt_1.0.0.

 10.0.0.0+

Definiert, welche gatewayscript-Richtlinie das Migrationsdienstprogramm verwendet, wenn die API-Assembly neu geschrieben wird.

xslt_1.0.0: Eine benutzerdefinierte Richtlinie, die vom Migrationsdienstprogramm erstellt wurde. Diese Richtlinie verwendet die v5-MPGW-Verarbeitungsregel. Verwenden Sie xslt_1.0.0, wenn die xslt-Richtlinie von v5-MPGW-Funktionen abhängt, wie z. B. Lastausgleichsgruppen oder XML-Manager-Einstellungen.

xslt_2.0.0: Das Migrationsdienstprogramm schreibt die vorhandene API auf xslt 2.0.0 neu. Die Angabe von xslt_2.0.0 kann zu Migrationsfehlern oder Laufzeitfehlern führen. Verwenden Sie xslt_2.0.0, wenn Sie alle vom Migrationsdienstprogramm vorgenommenen Änderungen in der API-YAML-Datei prüfen und verifizieren können.

Beispiel für Migrationskonfigurationen

In den folgenden Beispielen werden Konfigurationsoptionen mit der config.yml-Datei oder dem Befehl apicm gezeigt.

  • Im folgenden Beispiel wird die Datei config.yml zur Angabe der Migrationskonfiguration verwendet.
    
custom-policies-scope: global
emulate-v4-plan-rate-limit: false
deploy-policies:
  - proxy_1.5.0
  - redact_1.5.0
  - invoke_1.5.0
  - gatewayscript_1.0.0
rewrite-apis:
  enable-api-logging: false
  proxy-policy: proxy_1.5.0
  redact-policy: redact_1.5.0 
  invoke-policy: invoke_1.5.0
  xslt-policy: xslt_2.0.0
  gatewayscript-policy: gatewayscript_1.0.0
  if-policy: switch_2.0.0
  switch-policy: switch_2.0.0
  optimize-gws: false
  no-retitle: true

    Verwenden Sie den Parameter use-config-file, wenn Sie den Befehl apicm ausführen, um anzugeben, dass die Datei config.yml für Migrationskonfigurationswerte verwendet wird.

    ./apicm archive:port-to-apigw <path> --use-config-file=true
  • Im folgenden Beispiel wird der Befehl apicm verwendet, um dieselben Einstellungen wie im vorherigen Beispiel anzugeben.
    ./apicm archive:port-to-apigw <path> --custom-policies-scope: global --emulate-v4-plan-rate-limit: false --deploy-policies="proxy_1.5.0,redact_1.5.0,invoke_1.5.0,xslt_2.0.0,gatewayscript_1.0.0,switch_2.0.0" --enable-api-logging=false --proxy-policy="proxy_1.5.0" --redact-policy="redact_1.5.0" --invoke-policy="invoke_1.5.0" --xslt-policy="xslt_2.0.0" --gatewayscript-policy="gatewayscript_1.0.0" --if-policy="switch_2.0.0" --switch-policy="switch_2.0.0" --optimize-gws=true --no-retitle=true
  • Im folgenden Beispiel wird der Befehl apicm verwendet, um anzugeben, dass die Standardkonfigurationswerte für die Migration verwendet werden.
    ./apicm archive:port-to-apigw <path>