Eingehende Anforderungen und ausgehende Antworten transformieren

Erfahren Sie, wie Sie eingehende Anforderungen und ausgehende Antworten ändern können, die mit API Gateway an und von Backend-Services gesendet werden.

Es gibt häufig Situationen, in denen Sie mit einem API-Gateway eingehende Anforderungen ändern möchten, bevor sie an Backend-Services gesendet werden. Ebenso möchten Sie möglicherweise mit einem API-Gateway Antworten ändern, die von Backend-Services zurückgegeben werden. Beispiel:

  • Backend-Services erfordern möglicherweise Anforderungen, die ein bestimmtes HTTP-Headerset enthalten (z.B. Accept-Language und Accept-Encoding). Um diese Implementierungsdetails für API-Consumers und API-Clients auszublenden, können Sie die erforderlichen Header mit dem API-Gateway hinzufügen.
  • Webserver fügen in Antwortheadern häufig die vollständigen Versionsinformationen ein. Aus Sicherheitsgründen möchten Sie möglicherweise verhindern, dass API-Consumers und API-Clients Informationen zum zugrunde liegenden Technologiestack erhalten. Mit dem API-Gateway können Sie Serverheader aus Antworten entfernen.
  • Backend-Services können sensible Informationen in eine Antwort aufnehmen. Mit Ihrem API-Gateway können Sie solche Informationen entfernen.

Mit einem API-Gateway können Sie:

  • Header in Anforderungen und Antworten hinzufügen, entfernen und ändern.
  • Abfrageparameter in Anforderungen hinzufügen, entfernen und ändern.
  • Anforderungs-URLs aus einem öffentlichen Format in ein internes Format umschreiben, beispielsweise um Legacy-Anwendungen und Migrationen zu unterstützen.

Sie verwenden Anforderungs- und Antwort-Policys, um die Header und Abfrageparameter eingehender Anforderungen und die Header ausgehender Antworten zu transformieren (siehe Anforderungs-Policys und Antwort-Policys zu API-Deployment-Spezifikationen hinzufügen).

Sie können kontextabhängige Variablen in Transformationsanforderungs- und Transformationsantwort-Policys für Header und Abfrageparameter aufnehmen. Mit kontextabhängigen Variablen können Sie Header und Abfrageparameter mit den Werten anderer Header, Abfrageparameter, Pfadparameter und Authentifizierungsparameter ändern. Beachten Sie, dass Werte von kontextabhängigen Variablen aus der ursprünglichen Anforderung oder Antwort extrahiert und anschließend nicht aktualisiert werden, da ein API-Gateway eine Transformations-Policy verwendet, um eine Anforderung oder Antwort auszuwerten. Weitere Informationen zu kontextabhängigen Variablen finden Sie unter Kontextabhängige Variablen zu Policys und HTTP-Backend-Definitionen hinzufügen.

Wenn eine Transformationsanforderungs- oder Transformationsantwort-Policy für einen Header oder Abfrageparameter zu einem ungültigen Header oder Abfrageparameter führt, wird die Transformations-Policy ignoriert.

Beachten Sie, dass Sie bestimmte geschützte Anforderungs- und Antwortheader nicht mit Headertransformations-Policys transformieren können. Siehe Geschützte Anforderungsheader und Antwortheader.

Sie können einer API-Deployment-Spezifikation Transformationsanforderungs- und Transformationsantwort-Policys für Header und Abfrageparameter hinzufügen, indem Sie:

  • die Konsole verwenden
  • eine JSON-Datei bearbeiten

Headertransformationsanforderungs-Policys hinzufügen

Sie können Headertransformationsanforderungs-Policys zu API-Deployment-Spezifikationen hinzufügen, indem Sie die Konsole verwenden oder eine JSON-Datei bearbeiten.

Beachten Sie, dass Sie bestimmte geschützte Anforderungsheader nicht mit Headertransformations-Policys transformieren können. Siehe Geschützte Anforderungsheader und Antwortheader.

Headertransformationsanforderungs-Policys mit der Konsole hinzufügen

So fügen Sie mit der Konsole Headertransformationsanforderungs-Policys zu einer API-Deployment-Spezifikation hinzu:

  1. Erstellen oder aktualisieren Sie ein API-Deployment mit der Konsole, wählen Sie die Option Völlig neu aus, und geben Sie auf der Seite Basisinformationen Details ein.

    Weitere Informationen finden Sie unter API durch das Erstellen eines API-Deployment in einem API-Gateway bereitstellen und API-Gateway aktualisieren.

  2. Wählen Sie Weiter aus, und geben Sie Authentifizierungsoptionen auf der Seite Authentifizierung an.

    Weitere Informationen zu Authentifizierungsoptionen finden Sie unter Hinzufügen von Authentifizierung und Autorisierung zu API-Deployments.

  3. Wählen Sie Weiter aus, um Details zu einzelnen Routen im API-Deployment auf der Seite Routen einzugeben.

  4. Wählen Sie auf der Seite Routen die Route aus, für die Sie Headertransformationsanforderungs-Policys angeben möchten.
  5. Wählen Sie Routenanforderungs-Policys einblenden aus.
  6. Wählen Sie neben Headertransformationen die Schaltfläche Hinzufügen aus, um die Header zu aktualisieren, die in einer Anforderung an das API-Gateway für die aktuelle Route enthalten sind.
  7. Um die in einer Anforderung enthaltenen Header zu begrenzen, geben Sie Folgendes an:

    • Aktion: Filtern.
    • Typ: Entweder Blockieren, um die explizit aufgelisteten Header aus der Anforderung zu entfernen, oder Zulassen, um nur die explizit aufgelisteten Header in der Anforderung zuzulassen (alle anderen Header werden aus der Anforderung entfernt).
    • Headernamen: Die Liste der Header, die aus der Anforderung entfernt oder in der Anforderung zugelassen werden sollen (je nach der Einstellung im Feld Typ). Bei den angegebenen Namen muss die Groß-/Kleinschreibung nicht beachtet werden. Außerdem dürfen sie nicht in anderen Transformationsanforderungs-Policys für die Route enthalten sein (mit Ausnahme der Elemente, die Sie als zugelassen filtern). Beispiel: User-Agent.
  8. Um den Namen eines Headers in einer Anforderung (unter Beibehaltung des ursprünglichen Wertes) zu ändern, geben Sie Folgendes an:

    • Aktion: Umbenennen.
    • Von: Der ursprüngliche Name des Headers, den Sie umbenennen möchten. Bei dem angegebenen Namen muss die Groß-/Kleinschreibung nicht beachtet werden. Außerdem darf er nicht in anderen Transformationsanforderungs-Policys für die Route enthalten sein. Beispiel: X-Username.
    • In: Der neue Name des Headers, den Sie umbenennen möchten. Bei dem angegebenen Namen muss die Groß-/Kleinschreibung nicht beachtet werden. Außerdem darf er nicht in anderen Transformationsanforderungs-Policys für die Route enthalten sein (mit Ausnahme der Elemente, die Sie als zugelassen filtern). Beispiel: X-User-ID.
  9. Um einer Anforderung einen neuen Header hinzuzufügen (oder die Werte eines vorhandenen Headers zu ändern oder beizubehalten, der bereits in einer Anforderung enthalten ist), geben Sie Folgendes an:

    • Aktion: Festlegen.
    • Verhalten: Wenn der Header bereits vorhanden ist, geben Sie an, was Sie mit dem vorhandenen Wert des Headers tun möchten:

      • Überschreiben, um den vorhandenen Wert des Headers durch den angegebenen Wert zu ersetzen.
      • Anhängen, um den angegebenen Wert an den vorhandenen Wert des Headers anzuhängen.
      • Überspringen, um den vorhandenen Wert des Headers beizubehalten.
    • Name: Der Name des Headers, der zur Anforderung hinzugefügt (oder dessen Wert geändert) werden soll. Bei dem angegebenen Namen muss die Groß-/Kleinschreibung nicht beachtet werden. Außerdem darf er nicht in anderen Transformationsanforderungs-Policys für die Route enthalten sein (mit Ausnahme der Elemente, die Sie als zugelassen filtern). Beispiel: X-Api-Key.
    • Werte: Der Wert des neuen Headers (oder der Wert, der den Wert eines vorhandenen Headers ersetzen oder daran angehängt werden soll, je nach der Einstellung im Feld Verhalten). Sie können mehrere Werte angeben. Der angegebene Wert kann eine einfache Zeichenfolge sein oder kontextabhängige Variablen (mit Ausnahme von request.body) enthalten, die in Begrenzungszeichen (${...}) eingeschlossen sind. Beispiel: "value": "zyx987wvu654tsu321", "value": "${request.path[region]}", "value": "${request.headers[opc-request-id]}".
  10. Wählen Sie Änderungen speichern und dann Weiter aus, um die Details zu prüfen, die Sie für einzelne Routen eingegeben haben.
  11. Wählen Sie Erstellen oder Änderungen speichern aus, um das API-Deployment zu erstellen oder zu aktualisieren.
  12. (Optional) Bestätigen Sie, dass die API erfolgreich bereitgestellt wurde, indem Sie sie aufrufen (siehe In einem API-Gateway bereitgestellte API aufrufen).

Headertransformationsanforderungs-Policys durch Bearbeiten einer JSON-Datei hinzufügen

So fügen Sie Headertransformationsanforderungs-Policys zu einer API-Deployment-Spezifikation in einer JSON-Datei hinzu:

  1. Bearbeiten Sie mit Ihrem bevorzugten JSON-Editor die vorhandene API-Deployment-Spezifikation, der Sie Headertransformationsanforderungs-Policys hinzufügen möchten, oder erstellen Sie eine neue API-Deployment-Spezifikation (siehe API-Deployment-Spezifikation erstellen).

    Beispiel: Die folgende Basisspezifikation für das API-Deployment definiert eine einfache serverlose Hello World-Funktion in OCI Functions als einzelnes Backend:

    {
      "routes": [
        {
          "path": "/hello",
          "methods": ["GET"],
          "backend": {
            "type": "ORACLE_FUNCTIONS_BACKEND",
            "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
          }
        }
      ]
    }
  2. Fügen Sie einen requestPolicies-Abschnitt nach dem backend-Abschnitt für die Route ein, auf die die Headertransformationsanforderungs-Policy angewendet werden soll. Beispiel:

    {
      "routes": [
        {
          "path": "/hello",
          "methods": ["GET"],
          "backend": {
            "type": "ORACLE_FUNCTIONS_BACKEND",
            "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
          },
          "requestPolicies": {}
        }
      ]
    }
  3. Fügen Sie dem Abschnitt requestPolicies einen headerTransformations-Abschnitt hinzu.

    {
      "routes": [
        {
          "path": "/hello",
          "methods": ["GET"],
          "backend": {
            "type": "ORACLE_FUNCTIONS_BACKEND",
            "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
          },
          "requestPolicies": {
            "headerTransformations":{}
          }
        }
      ]
    }
  4. Um die Header in einer Anforderung zu begrenzen, geben Sie eine Headertransformationsanforderungs-Policy vom Typ filterHeaders an:

    {
      "routes": [
        {
          "path": "/hello",
          "methods": ["GET"],
          "backend": {
            "type": "ORACLE_FUNCTIONS_BACKEND",
            "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
          },
          "requestPolicies": {
            "headerTransformations": {
              "filterHeaders": {
                "type": "<BLOCK|ALLOW>",
                "items": [
                  {
                    "name": "<header-name>"
                  }
                ]
              }
            }
          }
        }
      ]
    }

    Dabei gilt:

    • "type": "<BLOCK|ALLOW>" gibt an, was mit den von "items":[{"name":"<header-name>"}] angegebenen Headern geschehen soll:
      • Verwenden Sie BLOCK, um die explizit aufgelisteten Header aus der Anforderung zu entfernen.
      • Verwenden Sie ALLOW, um in der Anforderung nur die explizit aufgelisteten Header zuzulassen (alle anderen Header werden aus der Anforderung entfernt).
    • "name":"<header-name> ist ein Header, der aus der Anforderung entfernt oder in ihr zugelassen werden soll (je nach der Einstellung unter "type": "<BLOCK|ALLOW>"). Bei dem angegebenen Namen muss die Groß-/Kleinschreibung nicht beachtet werden. Außerdem darf er nicht in anderen Transformationsanforderungs-Policys für die Route enthalten sein (mit Ausnahme der Elemente in ALLOW-Listen). Beispiel: User-Agent.

    Sie können bis zu 50 Header in einer Headertransformationsanforderungs-Policy vom Typ filterHeaders entfernen und zulassen.

    Beispiel:

    {
      "routes": [
        {
          "path": "/hello",
          "methods": ["GET"],
          "backend": {
            "type": "ORACLE_FUNCTIONS_BACKEND",
            "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
          },
          "requestPolicies": {
            "headerTransformations": {
              "filterHeaders": {
                "type": "BLOCK",
                "items": [
                  {
                    "name": "User-Agent"
                  }
                ]
              }
            }
          }
        }
      ]
    }

    In diesem Beispiel entfernt das API-Gateway den Header User-Agent aus allen eingehenden Anforderungen.

  5. Um den Namen eines Headers in einer Anforderung (unter Beibehaltung des ursprünglichen Wertes) zu ändern, geben Sie eine Headertransformationsanforderungs-Policy vom Typ renameHeaders an:

    {
      "routes": [
        {
          "path": "/hello",
          "methods": ["GET"],
          "backend": {
            "type": "ORACLE_FUNCTIONS_BACKEND",
            "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
          },
          "requestPolicies": {
            "headerTransformations": {
              "renameHeaders": {
                "items": [
                  {
                    "from": "<original-name>",
                    "to": "<new-name>"
                  }
                ]
              }
            }
          }
        }
      ]
    }

    Dabei gilt:

    • "from": "<original-name>" ist der ursprüngliche Name des Headers, den Sie umbenennen möchten. Bei dem angegebenen Namen muss die Groß-/Kleinschreibung nicht beachtet werden. Außerdem darf er nicht in anderen Transformationsanforderungs-Policys für die Route enthalten sein. Beispiel: X-Username.
    • "to": "<new-name>" ist der neue Name des Headers, den Sie umbenennen möchten. Bei dem angegebenen Namen muss die Groß-/Kleinschreibung nicht beachtet werden. Außerdem darf er nicht in anderen Transformationsanforderungs-Policys für die Route enthalten sein (mit Ausnahme der Elemente in ALLOW-Listen). Beispiel: X-User-ID.

    Sie können bis zu 20 Header in einer Headertransformationsanforderungs-Policy vom Typ renameHeaders umbenennen.

    Beispiel:

    {
      "routes": [
        {
          "path": "/hello",
          "methods": ["GET"],
          "backend": {
            "type": "ORACLE_FUNCTIONS_BACKEND",
            "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
          },
          "requestPolicies": {
            "headerTransformations": {
              "renameHeaders": {
                "items": [
                  {
                    "from": "X-Username",
                    "to": "X-User-ID"
                  }
                ]
              }
            }
          }
        }
      ]
    }

    In diesem Beispiel benennt das API-Gateway alle X-Username-Header in X-User-ID um, wobei der ursprüngliche Wert des Headers beibehalten wird.

  6. Um einer Anforderung einen neuen Header hinzuzufügen (oder die Werte eines vorhandenen Headers zu ändern oder beizubehalten, der bereits in einer Anforderung enthalten ist), geben Sie eine Headertransformationsanforderungs-Policy vom Typ setHeaders an:

    {
      "routes": [
        {
          "path": "/hello",
          "methods": ["GET"],
          "backend": {
            "type": "ORACLE_FUNCTIONS_BACKEND",
            "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
          },
          "requestPolicies": {
            "headerTransformations": {
              "setHeaders": {
                "items": [
                  {
                    "name": "<header-name>",
                    "values": ["<header-value>"],
                    "ifExists": "<OVERWRITE|APPEND|SKIP>"
                  }
                ]
              }
            }
          }
        }
      ]
    }

    Dabei gilt:

    • "name":"<header-name> ist der Name des Headers, der zur Anforderung hinzugefügt (oder dessen Wert geändert) werden soll. Bei dem angegebenen Namen muss die Groß-/Kleinschreibung nicht beachtet werden. Außerdem darf er nicht in anderen Transformationsanforderungs-Policys für die Route enthalten sein (mit Ausnahme der Elemente in ALLOW-Listen). Beispiel: X-Api-Key.
    • "values": ["<header-value>"] ist der Wert des neuen Headers (oder der Wert, der den Wert eines vorhandenen Headers ersetzen oder daran angehängt werden soll, je nach der Einstellung im Feld "ifExists": "<OVERWRITE|APPEND|SKIP>"). Der Wert, den Sie angeben, kann eine einfache Zeichenfolge sein oder kontextabhängige Variablen (außer request.body) enthalten, die in Begrenzungen vom Typ ${...} eingeschlossen sind. Beispiel: "values": "zyx987wvu654tsu321", "values": "${request.path[region]}", "values": "${request.headers[opc-request-id]}".

      Sie können bis zu 10 Werte angeben. Wenn Sie mehrere Werte angeben, fügt das API-Gateway einen Header für jeden Wert hinzu.

    • "ifExists": "<OVERWRITE|APPEND|SKIP>" gibt an, was mit dem vorhandenen Wert des Headers geschehen soll, wenn der von <header-name> angegebene Header bereits vorhanden ist:

      • Verwenden Sie OVERWRITE, um den vorhandenen Wert des Headers durch den angegebenen Wert zu ersetzen.
      • Verwenden Sie APPEND, um den angegebenen Wert an den vorhandenen Wert des Headers anzuhängen.
      • Verwenden Sie SKIP, um den vorhandenen Wert des Headers beizubehalten.

      Wenn kein Wert angegeben ist, wird standardmäßig OVERWRITE verwendet.

    Sie können bis zu 20 Header in einer Headertransformationsanforderungs-Policy vom Typ setHeaders hinzufügen (oder die Werte der Header ändern).

    Beispiel:

    {
      "routes": [
        {
          "path": "/hello",
          "methods": ["GET"],
          "backend": {
            "type": "ORACLE_FUNCTIONS_BACKEND",
            "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
          },
          "requestPolicies": {
            "headerTransformations": {
              "setHeaders": {
                "items": [
                  {
                    "name": "X-Api-Key",
                    "values": ["zyx987wvu654tsu321"],
                    "ifExists": "OVERWRITE"
                  }
                ]
              }
            }
          }
        }
      ]
    }

    In diesem Beispiel fügt das API-Gateway allen eingehenden Anforderungen den Header X-Api-Key:zyx987wvu654tsu321 hinzu. Wenn für eine eingehende Anforderung bereits ein X-Api-Key-Header auf einen anderen Wert gesetzt ist, ersetzt das API-Gateway den vorhandenen Wert durch zyx987wvu654tsu321.

  7. Speichern Sie die JSON-Datei, die die API-Deployment-Spezifikation enthält.
  8. Verwenden Sie die API-Deployment-Spezifikation, wenn Sie ein API-Deployment wie folgt erstellen oder aktualisieren:

    • Durch Angabe der JSON-Datei in der Konsole bei Auswahl der Option Vorhandene API hochladen
    • Durch Angabe der JSON-Datei in einer Anforderung an die REST-API von API-Gateway

    Weitere Informationen finden Sie unter API durch das Erstellen eines API-Deployment in einem API-Gateway bereitstellen und API-Gateway aktualisieren.

  9. (Optional) Bestätigen Sie, dass die API erfolgreich bereitgestellt wurde, indem Sie sie aufrufen (siehe In einem API-Gateway bereitgestellte API aufrufen).

Abfrageparameter-Transformationsanforderungs-Policys hinzufügen

Sie können Abfrageparameter-Transformationsanforderungs-Policys zu API-Deployment-Spezifikationen hinzufügen, indem Sie die Konsole verwenden oder eine JSON-Datei bearbeiten.

Abfrageparameter-Transformationsanforderungs-Policys mit der Konsole hinzufügen

So fügen Sie mit der Konsole Abfrageparameter-Transformationsanforderungs-Policys zu einer API-Deployment-Spezifikation hinzu:

  1. Erstellen oder aktualisieren Sie ein API-Deployment mit der Konsole, wählen Sie die Option Völlig neu aus, und geben Sie auf der Seite Basisinformationen Details ein.

    Weitere Informationen finden Sie unter API durch das Erstellen eines API-Deployment in einem API-Gateway bereitstellen und API-Gateway aktualisieren.

  2. Wählen Sie Weiter aus, und geben Sie Authentifizierungsoptionen auf der Seite Authentifizierung an.

    Weitere Informationen zu Authentifizierungsoptionen finden Sie unter Hinzufügen von Authentifizierung und Autorisierung zu API-Deployments.

  3. Wählen Sie Weiter aus, um Details zu einzelnen Routen im API-Deployment auf der Seite Routen einzugeben.

  4. Wählen Sie auf der Seite Routen die Route aus, für die Sie Abfrageparameter-Transformationsanforderungs-Policys angeben möchten.
  5. Wählen Sie Routenanforderungs-Policys einblenden aus.
  6. Wählen Sie neben Abfrageparametertransformationen die Schaltfläche Hinzufügen aus, um die Abfrageparameter zu aktualisieren, die in einer Anforderung an das API-Gateway für die aktuelle Route enthalten sind.
  7. Um die in einer Anforderung enthaltenen Abfrageparameter zu begrenzen, geben Sie Folgendes an:

    • Aktion: Filtern.
    • Typ: Entweder Blockieren, um die explizit aufgelisteten Abfrageparameter aus der Anforderung zu entfernen, oder Zulassen, um nur die explizit aufgelisteten Abfrageparameter in der Anforderung zuzulassen (alle anderen Abfrageparameter werden aus der Anforderung entfernt).
    • Abfrageparameternamen: Die Liste der Abfrageparameter, die aus der Anforderung entfernt oder in ihr zugelassen werden sollen (je nach der Einstellung im Feld Typ). Bei den angegebenen Namen muss die Groß-/Kleinschreibung beachtet werden. Außerdem dürfen sie nicht in anderen Transformationsanforderungs-Policys für die Route enthalten sein (mit Ausnahme der Elemente, die Sie als zugelassen filtern). Beispiel: User-Agent.
  8. Um den Namen eines Abfrageparameters in einer Anforderung (unter Beibehaltung des ursprünglichen Wertes) zu ändern, geben Sie Folgendes an:

    • Aktion: Umbenennen.
    • Von: Der ursprüngliche Name des Abfrageparameters, den Sie umbenennen möchten. Bei dem angegebenen Namen muss die Groß-/Kleinschreibung beachtet werden. Außerdem darf er nicht in anderen Transformationsanforderungs-Policys für die Route enthalten sein. Beispiel: X-Username.
    • In: Der neue Name des Abfrageparameters, den Sie umbenennen möchten. Bei dem angegebenen Namen muss die Groß-/Kleinschreibung beachtet werden. Außerdem darf er nicht in anderen Transformationsanforderungs-Policys für die Route enthalten sein (mit Ausnahme der Elemente, die Sie als zugelassen filtern). Beispiel: X-User-ID.
  9. Um einer Anforderung einen neuen Abfrageparameter hinzuzufügen (oder die Werte eines bereits in einer Anforderung enthaltenen Abfrageparameters zu ändern), geben Sie Folgendes an:

    • Aktion: Festlegen.
    • Verhalten: Wenn der Abfrageparameter bereits vorhanden ist, geben Sie an, was Sie mit dem vorhandenen Wert des Abfrageparameters tun möchten:

      • Überschreiben, um den vorhandenen Wert des Abfrageparameters durch den angegebenen Wert zu ersetzen.
      • Anhängen, um den angegebenen Wert an den vorhandenen Wert des Abfrageparameters anzuhängen.
      • Überspringen, um den vorhandenen Wert des Abfrageparameters beizubehalten.
    • Abfrageparametername: Der Name des Abfrageparameters, der der Anforderung hinzugefügt (oder dessen Wert geändert) werden soll. Bei dem angegebenen Namen muss die Groß-/Kleinschreibung beachtet werden. Außerdem darf er nicht in anderen Transformationsanforderungs-Policys für die Route enthalten sein (mit Ausnahme der Elemente, die Sie als zugelassen filtern). Beispiel: X-Api-Key.
    • Werte: Der Wert des neuen Abfrageparameters (oder der Wert, der den Wert eines vorhandenen Abfrageparameters ersetzen oder daran angehängt werden soll, je nach der Einstellung im Feld Verhalten). Der angegebene Wert kann eine einfache Zeichenfolge sein oder kontextabhängige Variablen enthalten, die in Begrenzungszeichen (${...}) eingeschlossen sind. Beispiel: "value": "zyx987wvu654tsu321", "value": "${request.path[region]}", "value": "${request.headers[opc-request-id]}". Sie können mehrere Werte angeben.
  10. Wählen Sie Änderungen speichern und dann Weiter aus, um die Details zu prüfen, die Sie für einzelne Routen eingegeben haben.
  11. Wählen Sie Erstellen oder Änderungen speichern aus, um das API-Deployment zu erstellen oder zu aktualisieren.
  12. (Optional) Bestätigen Sie, dass die API erfolgreich bereitgestellt wurde, indem Sie sie aufrufen (siehe In einem API-Gateway bereitgestellte API aufrufen).

Abfrageparameter-Transformationsanforderungs-Policys durch Bearbeiten einer JSON-Datei hinzufügen

So fügen Sie Abfrageparameter-Transformationsanforderungs-Policys zu einer API-Deployment-Spezifikation in einer JSON-Datei hinzu:

  1. Bearbeiten Sie mit Ihrem bevorzugten JSON-Editor die vorhandene API-Deployment-Spezifikation, der Sie Abfrageparameter-Transformationsanforderungs-Policys hinzufügen möchten, oder erstellen Sie eine neue API-Deployment-Spezifikation (siehe API-Deployment-Spezifikation erstellen).

    Beispiel: Die folgende Basisspezifikation für das API-Deployment definiert eine einfache serverlose Hello World-Funktion in OCI Functions als einzelnes Backend:

    {
      "routes": [
        {
          "path": "/hello",
          "methods": ["GET"],
          "backend": {
            "type": "ORACLE_FUNCTIONS_BACKEND",
            "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
          }
        }
      ]
    }
  2. Fügen Sie einen requestPolicies-Abschnitt nach dem backend-Abschnitt für die Route ein, auf die die Abfrageparameter-Transformationsanforderungs-Policy angewendet werden soll. Beispiel:

    {
      "routes": [
        {
          "path": "/hello",
          "methods": ["GET"],
          "backend": {
            "type": "ORACLE_FUNCTIONS_BACKEND",
            "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
          },
          "requestPolicies": {}
        }
      ]
    }
  3. Fügen Sie dem Abschnitt requestPolicies einen queryParameterTransformations-Abschnitt hinzu.

    {
      "routes": [
        {
          "path": "/hello",
          "methods": ["GET"],
          "backend": {
            "type": "ORACLE_FUNCTIONS_BACKEND",
            "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
          },
          "requestPolicies": {
            "queryParameterTransformations":{}
          }
        }
      ]
    }
  4. Um die Abfrageparameter in einer Anforderung zu begrenzen, geben Sie eine Abfrageparameter-Transformationsanforderungs-Policy vom Typ filterQueryParameters an:

    {
      "routes": [
        {
          "path": "/hello",
          "methods": ["GET"],
          "backend": {
            "type": "ORACLE_FUNCTIONS_BACKEND",
            "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
          },
          "requestPolicies": {
            "queryParameterTransformations": {
              "filterQueryParameters": {
                "type": "<BLOCK|ALLOW>",
                "items": [
                  {
                    "name": "<query-parameter-name>"
                  }
                ]
              }
            }
          }
        }
      ]
    }

    Dabei gilt:

    • "type": "<BLOCK|ALLOW>" gibt an, was mit den von "items":[{"name":"<query-parameter-name>"}] angegebenen Abfrageparametern geschehen soll:
      • Verwenden Sie BLOCK, um die explizit aufgelisteten Abfrageparameter aus der Anforderung zu entfernen.
      • Verwenden Sie ALLOW, um in der Anforderung nur die explizit aufgelisteten Abfrageparameter zuzulassen (alle anderen Abfrageparameter werden aus der Anforderung entfernt).
    • "name":"<query-parameter-name> ist ein Abfrageparameter, der aus der Anforderung entfernt oder in ihr zugelassen werden soll (je nach der Einstellung unter "type": "<BLOCK|ALLOW>"). Bei dem angegebenen Namen muss die Groß-/Kleinschreibung beachtet werden. Außerdem darf er nicht in anderen Transformationsanforderungs-Policys für die Route enthalten sein (mit Ausnahme der Elemente in ALLOW-Listen). Beispiel: User-Agent.

    Sie können bis zu 50 Abfrageparameter in einer Abfrageparameter-Transformationsanforderungs-Policy vom Typ filterQueryParameters entfernen und zulassen.

    Beispiel:

    {
      "routes": [
        {
          "path": "/hello",
          "methods": ["GET"],
          "backend": {
            "type": "ORACLE_FUNCTIONS_BACKEND",
            "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
          },
          "requestPolicies": {
            "queryParameterTransformations": {
              "filterQueryParameters": {
                "type": "BLOCK",
                "items": [
                  {
                    "name": "User-Agent"
                  }
                ]
              }
            }
          }
        }
      ]
    }

    In diesem Beispiel entfernt das API-Gateway den Abfrageparameter User-Agent aus allen eingehenden Anforderungen.

  5. Um den Namen eines Abfrageparameters in einer Anforderung (unter Beibehaltung des ursprünglichen Wertes) zu ändern, geben Sie eine Abfrageparameter-Transformationsanforderungs-Policy vom Typ renameQueryParameters an:

    {
      "routes": [
        {
          "path": "/hello",
          "methods": ["GET"],
          "backend": {
            "type": "ORACLE_FUNCTIONS_BACKEND",
            "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
          },
          "requestPolicies": {
            "queryParameterTransformations": {
              "renameQueryParameters": {
                "items": [
                  {
                    "from": "<original-name>",
                    "to": "<new-name>"
                  }
                ]
              }
            }
          }
        }
      ]
    }

    Dabei gilt:

    • "from": "<original-name>" ist der ursprüngliche Name des Abfrageparameters, den Sie umbenennen möchten. Bei dem angegebenen Namen muss die Groß-/Kleinschreibung beachtet werden. Außerdem darf er nicht in anderen Transformationsanforderungs-Policys für die Route enthalten sein. Beispiel: X-Username.
    • "to": "<new-name>" ist der neue Name des Abfrageparameters, den Sie umbenennen möchten. Bei dem angegebenen Namen muss die Groß-/Kleinschreibung beachtet werden. Außerdem darf er nicht in anderen Transformationsanforderungs-Policys für die Route enthalten sein (mit Ausnahme der Elemente in ALLOW-Listen). Beispiel: X-User-ID.

    Sie können bis zu 20 Abfrageparameter in einer Abfrageparameter-Transformationsanforderungs-Policy vom Typ renameQueryParameters umbenennen.

    Beispiel:

    {
      "routes": [
        {
          "path": "/hello",
          "methods": ["GET"],
          "backend": {
            "type": "ORACLE_FUNCTIONS_BACKEND",
            "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
          },
          "requestPolicies": {
            "queryParameterTransformations": {
              "renameQueryParameters": {
                "items": [
                  {
                    "from": "X-Username",
                    "to": "X-User-ID"
                  }
                ]
              }
            }
          }
        }
      ]
    }

    In diesem Beispiel benennt das API-Gateway alle X-Username-Abfrageparameter in X-User-ID um, wobei der ursprüngliche Wert des Abfrageparameters beibehalten wird.

  6. Um einer Anforderung einen neuen Abfrageparameter hinzuzufügen (oder die Werte eines vorhandenen Abfrageparameters zu ändern oder beizubehalten, der bereits in einer Anforderung enthalten ist), geben Sie eine Abfrageparameter-Transformationsanforderungs-Policy vom Typ setQueryParameters an:

    {
      "routes": [
        {
          "path": "/hello",
          "methods": ["GET"],
          "backend": {
            "type": "ORACLE_FUNCTIONS_BACKEND",
            "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
          },
          "requestPolicies": {
            "queryParameterTransformations": {
              "setQueryParameters": {
                "items": [
                  {
                    "name": "<query-parameter-name>",
                    "values": ["<query-parameter-value>"],
                    "ifExists": "<OVERWRITE|APPEND|SKIP>"
                  }
                ]
              }
            }
          }
        }
      ]
    }

    Dabei gilt:

    • "name": "<query-parameter-name>" ist der Name des Abfrageparameters, der der Anforderung hinzugefügt (oder dessen Wert geändert) werden soll. Bei dem angegebenen Namen muss die Groß-/Kleinschreibung beachtet werden. Außerdem darf er nicht in anderen Transformationsanforderungs-Policys für die Route enthalten sein (mit Ausnahme der Elemente in ALLOW-Listen). Beispiel: X-Api-Key.
    • "values": ["<query-parameter-value>"] ist der Wert des neuen Abfrageparameters (oder der Wert, der den Wert eines vorhandenen Abfrageparameters ersetzen oder daran angehängt werden soll, je nach der Einstellung unter "ifExists": "<OVERWRITE|APPEND|SKIP>"). Der angegebene Wert kann eine einfache Zeichenfolge sein oder kontextabhängige Variablen enthalten, die in Begrenzungszeichen (${...}) eingeschlossen sind. Beispiel: "values": "zyx987wvu654tsu321", "values": "${request.path[region]}", "values": "${request.headers[opc-request-id]}".

      Sie können bis zu 10 Werte angeben. Wenn Sie mehrere Werte angeben, fügt das API-Gateway einen Abfrageparameter für jeden Wert hinzu.

    • "ifExists": "<OVERWRITE|APPEND|SKIP>" gibt an, was mit dem vorhandenen Wert des Abfrageparameters geschehen soll, wenn der von <query-parameter-name> angegebene Abfrageparameter bereits vorhanden ist:

      • Verwenden Sie OVERWRITE, um den vorhandenen Wert des Abfrageparameters durch den angegebenen Wert zu ersetzen.
      • Verwenden Sie APPEND, um den angegebenen Wert an den vorhandenen Wert des Abfrageparameters anzuhängen.
      • Verwenden Sie SKIP, um den vorhandenen Wert des Abfrageparameters beizubehalten.

      Wenn kein Wert angegeben ist, wird standardmäßig OVERWRITE verwendet.

    Sie können bis zu 20 Abfrageparameter in einer Abfrageparameter-Transformationsanforderungs-Policy vom Typ setQueryParameters hinzufügen (oder die Werte der Abfrageparameter ändern).

    Beispiel:

    {
      "routes": [
        {
          "path": "/hello",
          "methods": ["GET"],
          "backend": {
            "type": "ORACLE_FUNCTIONS_BACKEND",
            "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
          },
          "requestPolicies": {
            "queryParameterTransformations": {
              "setQueryParameters": {
                "items": [
                  {
                    "name": "X-Api-Key",
                    "values": ["zyx987wvu654tsu321"],
                    "ifExists": "OVERWRITE"
                  }
                ]
              }
            }
          }
        }
      ]
    }

    In diesem Beispiel fügt das API-Gateway allen eingehenden Anforderungen den Abfrageparameter X-Api-Key:zyx987wvu654tsu321 hinzu. Wenn für eine eingehende Anforderung bereits ein X-Api-Key-Abfrageparameter auf einen anderen Wert gesetzt ist, ersetzt das API-Gateway den vorhandenen Wert durch zyx987wvu654tsu321.

  7. Speichern Sie die JSON-Datei, die die API-Deployment-Spezifikation enthält.
  8. Verwenden Sie die API-Deployment-Spezifikation, wenn Sie ein API-Deployment wie folgt erstellen oder aktualisieren:

    • Durch Angabe der JSON-Datei in der Konsole bei Auswahl der Option Vorhandene API hochladen
    • Durch Angabe der JSON-Datei in einer Anforderung an die REST-API von API-Gateway

    Weitere Informationen finden Sie unter API durch das Erstellen eines API-Deployment in einem API-Gateway bereitstellen und API-Gateway aktualisieren.

  9. (Optional) Bestätigen Sie, dass die API erfolgreich bereitgestellt wurde, indem Sie sie aufrufen (siehe In einem API-Gateway bereitgestellte API aufrufen).

Headertransformationsantwort-Policys hinzufügen

Sie können Headertransformationsantwort-Policys zu API-Deployment-Spezifikationen hinzufügen, indem Sie die Konsole verwenden oder eine JSON-Datei bearbeiten.

Beachten Sie, dass Sie bestimmte geschützte Antwortheader nicht mit Headertransformations-Policys transformieren können. Siehe Geschützte Anforderungsheader und Antwortheader.

Headertransformationsantwort-Policys mit der Konsole hinzufügen

So fügen Sie mit der Konsole Headertransformationsantwort-Policys zu einer API-Deployment-Spezifikation hinzu:

  1. Erstellen oder aktualisieren Sie ein API-Deployment mit der Konsole, wählen Sie die Option Völlig neu aus, und geben Sie auf der Seite Basisinformationen Details ein.

    Weitere Informationen finden Sie unter API durch das Erstellen eines API-Deployment in einem API-Gateway bereitstellen und API-Gateway aktualisieren.

  2. Wählen Sie Weiter aus, und geben Sie Authentifizierungsoptionen auf der Seite Authentifizierung an.

    Weitere Informationen zu Authentifizierungsoptionen finden Sie unter Hinzufügen von Authentifizierung und Autorisierung zu API-Deployments.

  3. Wählen Sie Weiter aus, um Details zu einzelnen Routen im API-Deployment auf der Seite Routen einzugeben.

  4. Wählen Sie auf der Seite Routen die Route aus, für die Sie Headertransformationsantwort-Policys angeben möchten.
  5. Wählen Sie Routenantwort-Policys einblenden aus.
  6. Wählen Sie neben Headertransformationen die Schaltfläche hinzufügen aus, um die Header zu aktualisieren, die in einer Antwort vom API-Gateway für die aktuelle Route enthalten sind.
  7. Um die in einer Antwort enthaltenen Header zu begrenzen, geben Sie Folgendes an:

    • Aktion: Filtern.
    • Typ: Entweder Blockieren, um die explizit aufgelisteten Header aus der Antwort zu entfernen, oder Zulassen, um nur die explizit aufgelisteten Header in der Antwort zuzulassen (alle anderen Header werden aus der Antwort entfernt).
    • Headernamen: Die Liste der Header, die aus der Antwort entfernt oder in ihr zugelassen werden sollen (je nach der Einstellung im Feld Typ). Bei den angegebenen Namen muss die Groß-/Kleinschreibung nicht beachtet werden. Außerdem dürfen sie nicht in anderen Transformationsantwort-Policys für die Route enthalten sein (mit Ausnahme der Elemente, die Sie als zugelassen filtern). Beispiel: User-Agent.
  8. Um den Namen eines Headers in einer Antwort (unter Beibehaltung des ursprünglichen Wertes) zu ändern, geben Sie Folgendes an:

    • Aktion: Umbenennen.
    • Von: Der ursprüngliche Name des Headers, den Sie umbenennen möchten. Bei dem angegebenen Namen muss die Groß-/Kleinschreibung nicht beachtet werden. Außerdem darf er nicht in anderen Transformationsantwort-Policys für die Route enthalten sein. Beispiel: X-Username.
    • In: Der neue Name des Headers, den Sie umbenennen möchten. Bei dem angegebenen Namen muss die Groß-/Kleinschreibung nicht beachtet werden. Außerdem darf er nicht in anderen Transformationsantwort-Policys für die Route enthalten sein (mit Ausnahme der Elemente in ALLOW-Listen). Beispiel: X-User-ID.
  9. Um einer Antwort einen neuen Header hinzuzufügen (oder die Werte eines vorhandenen Headers zu ändern oder beizubehalten, der bereits in einer Antwort enthalten ist), geben Sie Folgendes an:

    • Aktion: Festlegen.
    • Verhalten: Wenn der Header bereits vorhanden ist, geben Sie an, was Sie mit dem vorhandenen Wert des Headers tun möchten:

      • Überschreiben, um den vorhandenen Wert des Headers durch den angegebenen Wert zu ersetzen.
      • Anhängen, um den angegebenen Wert an den vorhandenen Wert des Headers anzuhängen.
      • Überspringen, um den vorhandenen Wert des Headers beizubehalten.
    • Name: Der Name des Headers, der zur Antwort hinzugefügt (oder dessen Wert geändert) werden soll. Bei dem angegebenen Namen muss die Groß-/Kleinschreibung nicht beachtet werden. Außerdem darf er nicht in anderen Transformationsantwort-Policys für die Route enthalten sein (mit Ausnahme der Elemente, die Sie als zugelassen filtern). Beispiel: X-Api-Key.
    • Werte: Der Wert des neuen Headers (oder der Wert, der den Wert eines vorhandenen Headers ersetzen oder daran angehängt werden soll, je nach der Einstellung im Feld Verhalten). Der angegebene Wert kann eine einfache Zeichenfolge sein oder kontextabhängige Variablen enthalten, die in Begrenzungszeichen (${...}) eingeschlossen sind. Beispiel: "value": "zyx987wvu654tsu321". Sie können mehrere Werte angeben.
  10. Wählen Sie Änderungen speichern und dann Weiter aus, um die Details zu prüfen, die Sie für einzelne Routen eingegeben haben.
  11. Wählen Sie Erstellen oder Änderungen speichern aus, um das API-Deployment zu erstellen oder zu aktualisieren.
  12. (Optional) Bestätigen Sie, dass die API erfolgreich bereitgestellt wurde, indem Sie sie aufrufen (siehe In einem API-Gateway bereitgestellte API aufrufen).

Headertransformationsantwort-Policys durch Bearbeiten einer JSON-Datei hinzufügen

So fügen Sie Headertransformationsantwort-Policys zu einer API-Deployment-Spezifikation in einer JSON-Datei hinzu:

  1. Bearbeiten Sie mit Ihrem bevorzugten JSON-Editor die vorhandene API-Deployment-Spezifikation, der Sie Headertransformationsantwort-Policys hinzufügen möchten, oder erstellen Sie eine neue API-Deployment-Spezifikation (siehe API-Deployment-Spezifikation erstellen).

    Beispiel: Die folgende Basisspezifikation für das API-Deployment definiert eine einfache serverlose Hello World-Funktion in OCI Functions als einzelnes Backend:

    {
      "routes": [
        {
          "path": "/hello",
          "methods": ["GET"],
          "backend": {
            "type": "ORACLE_FUNCTIONS_BACKEND",
            "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
          }
        }
      ]
    }
  2. Fügen Sie einen responsePolicies-Abschnitt nach dem backend-Abschnitt für die Route ein, auf die die Headertransformationsantwort-Policy angewendet werden soll. Beispiel:

    {
      "routes": [
        {
          "path": "/hello",
          "methods": ["GET"],
          "backend": {
            "type": "ORACLE_FUNCTIONS_BACKEND",
            "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
          },
          "responsePolicies": {}
        }
      ]
    }
  3. Fügen Sie dem Abschnitt responsePolicies einen headerTransformations-Abschnitt hinzu.

    {
      "routes": [
        {
          "path": "/hello",
          "methods": ["GET"],
          "backend": {
            "type": "ORACLE_FUNCTIONS_BACKEND",
            "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
          },
          "responsePolicies": {
            "headerTransformations":{}
          }
        }
      ]
    }
  4. Um die Header in einer Antwort zu begrenzen, geben Sie eine Headertransformationsantwort-Policy vom Typ filterHeaders an:

    {
      "routes": [
        {
          "path": "/hello",
          "methods": ["GET"],
          "backend": {
            "type": "ORACLE_FUNCTIONS_BACKEND",
            "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
          },
          "responsePolicies": {
            "headerTransformations": {
              "filterHeaders": {
                "type": "<BLOCK|ALLOW>",
                "items": [
                  {
                    "name": "<header-name>"
                  }
                ]
              }
            }
          }
        }
      ]
    }

    Dabei gilt:

    • "type": "<BLOCK|ALLOW>" gibt an, was mit den von "items":[{"name":"<header-name>"}] angegebenen Headern geschehen soll:
      • Verwenden Sie BLOCK, um die explizit aufgelisteten Header aus der Antwort zu entfernen.
      • Verwenden Sie ALLOW, um in der Antwort nur die explizit aufgelisteten Header zuzulassen (alle anderen Header werden aus der Antwort entfernt).
    • "name":"<header-name> ist ein Header, der aus der Antwort entfernt oder in ihr zugelassen werden soll (je nach der Einstellung unter "type": "<BLOCK|ALLOW>"). Bei dem angegebenen Namen muss die Groß-/Kleinschreibung nicht beachtet werden. Außerdem darf er nicht in anderen Transformationsantwort-Policys für die Route enthalten sein (mit Ausnahme der Elemente in ALLOW-Listen). Beispiel: User-Agent.

    Sie können bis zu 20 Header in einer Headertransformationsantwort-Policy vom Typ filterHeaders entfernen und zulassen.

    Beispiel:

    {
      "routes": [
        {
          "path": "/hello",
          "methods": ["GET"],
          "backend": {
            "type": "ORACLE_FUNCTIONS_BACKEND",
            "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
          },
          "responsePolicies": {
            "headerTransformations": {
              "filterHeaders": {
                "type": "BLOCK",
                "items": [
                  {
                    "name": "User-Agent"
                  }
                ]
              }
            }
          }
        }
      ]
    }

    In diesem Beispiel entfernt das API-Gateway den Header User-Agent aus allen ausgehenden Antworten.

  5. Um den Namen eines Headers in einer Antwort (unter Beibehaltung des ursprünglichen Wertes) zu ändern, geben Sie eine Headertransformationsantwort-Policy vom Typ renameHeaders an:

    {
      "routes": [
        {
          "path": "/hello",
          "methods": ["GET"],
          "backend": {
            "type": "ORACLE_FUNCTIONS_BACKEND",
            "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
          },
          "responsePolicies": {
            "headerTransformations": {
              "renameHeaders": {
                "items": [
                  {
                    "from": "<original-name>",
                    "to": "<new-name>"
                  }
                ]
              }
            }
          }
        }
      ]
    }

    Dabei gilt:

    • "from": "<original-name>" ist der ursprüngliche Name des Headers, den Sie umbenennen möchten. Bei dem angegebenen Namen muss die Groß-/Kleinschreibung nicht beachtet werden. Außerdem darf er nicht in anderen Transformationsantwort-Policys für die Route enthalten sein. Beispiel: X-Username.
    • "to": "<new-name>" ist der neue Name des Headers, den Sie umbenennen möchten. Bei dem angegebenen Namen muss die Groß-/Kleinschreibung nicht beachtet werden. Außerdem darf er nicht in anderen Transformationsantwort-Policys für die Route enthalten sein (mit Ausnahme der Elemente in ALLOW-Listen). Beispiel: X-User-ID.

    Sie können bis zu 20 Header in einer Headertransformationsantwort-Policy vom Typ renameHeaders umbenennen.

    Beispiel:

    {
      "routes": [
        {
          "path": "/hello",
          "methods": ["GET"],
          "backend": {
            "type": "ORACLE_FUNCTIONS_BACKEND",
            "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
          },
          "responsePolicies": {
            "headerTransformations": {
              "renameHeaders": {
                "items": [
                  {
                    "from": "X-Username",
                    "to": "X-User-ID"
                  }
                ]
              }
            }
          }
        }
      ]
    }

    In diesem Beispiel benennt das API-Gateway alle X-Username-Header in X-User-ID um, wobei der ursprüngliche Wert des Headers beibehalten wird.

  6. Um einer Antwort einen neuen Header hinzuzufügen (oder die Werte eines vorhandenen Headers zu ändern oder beizubehalten, der bereits in einer Antwort enthalten ist), geben Sie eine Headertransformationsantwort-Policy vom Typ setHeaders an:

    {
      "routes": [
        {
          "path": "/hello",
          "methods": ["GET"],
          "backend": {
            "type": "ORACLE_FUNCTIONS_BACKEND",
            "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
          },
          "responsePolicies": {
            "headerTransformations": {
              "setHeaders": {
                "items": [
                  {
                    "name": "<header-name>",
                    "values": ["<header-value>"],
                    "ifExists": "<OVERWRITE|APPEND|SKIP>"
                  }
                ]
              }
            }
          }
        }
      ]
    }

    Dabei gilt:

    • "name":"<header-name> ist der Name des Headers, der zur Antwort hinzugefügt (oder dessen Wert geändert) werden soll. Bei dem angegebenen Namen muss die Groß-/Kleinschreibung nicht beachtet werden. Außerdem darf er nicht in anderen Transformationsantwort-Policys für die Route enthalten sein (mit Ausnahme der Elemente in ALLOW-Listen). Beispiel: X-Api-Key.
    • "values": ["<header-value>"] ist der Wert des neuen Headers (oder der Wert, der den Wert eines vorhandenen Headers ersetzen oder daran angehängt werden soll, je nach der Einstellung im Feld "ifExists": "<OVERWRITE|APPEND|SKIP>"). Der angegebene Wert kann eine einfache Zeichenfolge sein oder kontextabhängige Variablen enthalten, die in Begrenzungszeichen (${...}) eingeschlossen sind. Beispiel: "values": "zyx987wvu654tsu321".

      Sie können bis zu 10 Werte angeben. Wenn Sie mehrere Werte angeben, fügt das API-Gateway einen Header für jeden Wert hinzu.

    • "ifExists": "<OVERWRITE|APPEND|SKIP>" gibt an, was mit dem vorhandenen Wert des Headers geschehen soll, wenn der von <header-name> angegebene Header bereits vorhanden ist:

      • Verwenden Sie OVERWRITE, um den vorhandenen Wert des Headers durch den angegebenen Wert zu ersetzen.
      • Verwenden Sie APPEND, um den angegebenen Wert an den vorhandenen Wert des Headers anzuhängen.
      • Verwenden Sie SKIP, um den vorhandenen Wert des Headers beizubehalten.

      Wenn kein Wert angegeben ist, wird standardmäßig OVERWRITE verwendet.

    Sie können bis zu 20 Header in einer Headertransformationsantwort-Policy vom Typ setHeaders hinzufügen (oder die Werte der Header ändern).

    Beispiel:

    {
      "routes": [
        {
          "path": "/hello",
          "methods": ["GET"],
          "backend": {
            "type": "ORACLE_FUNCTIONS_BACKEND",
            "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
          },
          "responsePolicies": {
            "headerTransformations": {
              "setHeaders": {
                "items": [
                  {
                    "name": "X-Api-Key",
                    "values": ["zyx987wvu654tsu321"],
                    "ifExists": "OVERWRITE"
                  }
                ]
              }
            }
          }
        }
      ]
    }

    In diesem Beispiel fügt das API-Gateway allen ausgehenden Antworten den Header X-Api-Key:zyx987wvu654tsu321 hinzu. Wenn für eine ausgehende Antwort bereits ein X-Api-Key-Header auf einen anderen Wert gesetzt ist, ersetzt das API-Gateway den vorhandenen Wert durch zyx987wvu654tsu321.

  7. Speichern Sie die JSON-Datei, die die API-Deployment-Spezifikation enthält.
  8. Verwenden Sie die API-Deployment-Spezifikation, wenn Sie ein API-Deployment wie folgt erstellen oder aktualisieren:

    • Durch Angabe der JSON-Datei in der Konsole bei Auswahl der Option Vorhandene API hochladen
    • Durch Angabe der JSON-Datei in einer Anforderung an die REST-API von API-Gateway

    Weitere Informationen finden Sie unter API durch das Erstellen eines API-Deployment in einem API-Gateway bereitstellen und API-Gateway aktualisieren.

  9. (Optional) Bestätigen Sie, dass die API erfolgreich bereitgestellt wurde, indem Sie sie aufrufen (siehe In einem API-Gateway bereitgestellte API aufrufen).

Beispiele

In den Beispielen in diesem Abschnitt wird von der folgenden API-Deployment-Definition und grundlegenden API-Deployment-Spezifikation in einer JSON-Datei ausgegangen:

{
  "displayName": "Marketing Deployment",
  "gatewayId": "ocid1.apigateway.oc1..aaaaaaaab______hga",
  "compartmentId": "ocid1.compartment.oc1..aaaaaaaa7______ysq",
  "pathPrefix": "/marketing",
  "specification": {
    "routes": [
      {
        "path": "/weather",
        "methods": ["GET"],
        "backend": {
          "type": "HTTP_BACKEND",
          "url": "https://api.weather.gov"
        },
        "requestPolicies": {}
      }
    ]
  },
  "freeformTags": {},
  "definedTags": {}
}

Beachten Sie, dass diese Beispiele auch gelten, wenn Sie eine API-Deployment-Spezifikation mit Dialogfeldern in der Konsole definieren.

Beispiel 1: Headerparameter in Abfrageparameter transformieren

In diesem Beispiel wird angenommen, dass ein vorhandenes HTTP-Backend nur Anforderungen mit Abfrageparametern und nicht mit Headerparametern verarbeitet. Sie möchten jedoch, dass das HTTP-Backend auch Anforderungen mit Headerparametern verarbeitet. Um dies zu erreichen, erstellen Sie eine API-Deployment-Spezifikation, die eine Abfrageparameter-Transformationsanforderungs-Policy enthält, um den Wert aus einem Anforderungsheader als Abfrageparameter an das HTTP-Backend zu übergeben.

        "requestPolicies": {
          "queryParameterTransformations":  {
            "setQueryParameters": {
              "items": [
                {
                  "name": "region",
                  "values": ["${request.headers[region]}"],
                  "ifExists": "OVERWRITE"
                }
              ]
            }
          }
        }

In diesem Beispiel wird eine Anforderung wie curl -H "region: west" https://<gateway-hostname>/marketing/weather in https://api.weather.gov?region=west aufgelöst.

Beispiel 2: Einen Header in einen anderen Header transformieren

In diesem Beispiel wird angenommen, dass ein vorhandenes HTTP-Backend nur Anforderungen verarbeitet, die einen bestimmten Header enthalten. Sie möchten jedoch, dass das HTTP-Backend auch Anforderungen mit einem anderen Header verarbeitet. Um dies zu erreichen, erstellen Sie eine API-Deployment-Spezifikation, die eine Headertransformationsanforderungs-Policy enthält, um den Wert aus einem Anforderungsheader als ein anderer Anforderungsheader an das HTTP-Backend zu übergeben.

        "requestPolicies": {
          "headerTransformations": {
            "setHeaders": {
              "items": [
                {
                  "name": "region",
                  "values": ["${request.headers[locale]}"],
                  "ifExists": "OVERWRITE"
                }
              ]
            }
          }
        }

In diesem Beispiel wird eine Anforderung wie curl -H "locale: west" https://<gateway-hostname>/marketing/weather in die Anforderung curl -H "region: west" https://api.weather.gov aufgelöst.

Beispiel 3: Authentifizierungsparameter aus einem JWT als Anforderungsheader hinzufügen

In diesem Beispiel wird angenommen, dass ein vorhandenes HTTP-Backend erfordert, dass der Wert des sub-Claims in einem validierten JSON Web Token (JWT) in einer Anforderung als Header mit dem Namen JWT_SUBJECT enthalten sein muss. Der API Gateway-Service hat den Wert des sub-Claims gespeichert, der im JWT als Authentifizierungsparameter in der Tabelle request.auth enthalten ist.

Um den sub-Wert in einen Header namens JWT_SUBJECT aufzunehmen, erstellen Sie eine API-Deployment-Spezifikation, die eine Headertransformationsanforderungs-Policy enthält. Die Anforderungs-Policy ruft den sub-Wert aus der request.auth-Tabelle ab und übergibt ihn als Wert des JWT_SUBJECT-Headers an das HTTP-Backend.

        "requestPolicies": {
          "headerTransformations": {
            "setHeaders": {
              "items": [
                {
                  "name": "JWT_SUBJECT",
                  "values": ["${request.auth[sub]}"],
                  "ifExists": "OVERWRITE"
                }
              ]
            }
          }
        }

Wenn eine Anforderung erfolgreich validiert wurde, wird in diesem Beispiel der JWT_SUBJECT-Header zu der Anforderung hinzugefügt, die an das HTTP-Backend übergeben wird.

Beispiel 4: Schlüssel aus einer Autorisiererfunktion als Abfrageparameter hinzufügen

In diesem Beispiel wird angenommen, dass ein vorhandenes HTTP-Backend erfordert, dass Anforderungen zu Authentifizierungszwecken einen Abfrageparameter namens access_key enthalten müssen. Sie möchten, dass der Abfrageparameter access_key den Wert eines Schlüssels namens apiKey enthält, der von einer Autorisiererfunktion zurückgegeben wurde, die die Anforderung erfolgreich validiert hat. Der API Gateway-Service hat den Wert apiKey als Authentifizierungsparameter in der Tabelle request.auth gespeichert.

Um den Abfrageparameter access_key in die Anforderung aufzunehmen, erstellen Sie eine API-Deployment-Spezifikation, die eine Abfrageparameter-Transformationsanforderungs-Policy enthält. Die Anforderungs-Policy ruft den apiKey-Wert aus der request.auth-Tabelle ab und übergibt ihn als Wert des access_key-Abfrageparameters an das HTTP-Backend.

        "requestPolicies": {
          "queryParameterTransformations": {
            "setQueryParameters": {
              "items": [
                {
                  "name": "access_key",
                  "values": ["${request.auth[apiKey]}"],
                  "ifExists": "OVERWRITE"
                }
              ]
            }
          }
        }

In diesem Beispiel wird der Abfrageparameter access_key zu der Anforderung hinzugefügt, die an das HTTP-Backend übergeben wird, wobei der apiKey-Wert aus der request.auth-Tabelle verwendet wird. Eine Anforderung wie https://<gateway-hostname>/marketing/weather wird in eine Anforderung wie https://api.weather.gov?access_key=fw5n9abi0ep aufgelöst.

Beispiel 5: Standardwert für einen optionalen Abfrageparameter hinzufügen

In diesem Beispiel wird angenommen, dass ein vorhandenes HTTP-Backend erfordert, dass Anforderungen einen Abfrageparameter namens country enthalten müssen. Der Abfrageparameter country ist jedoch optional und wird von einigen API-Clients, die Anforderungen senden, nicht eingefügt. Wenn eine Anforderung bereits einen country-Abfrageparameter und einen Wert enthält, möchten Sie, dass beide unverändert an das HTTP-Backend übergeben werden. Wenn eine Anforderung jedoch noch keinen country-Abfrageparameter enthält, möchten Sie, dass der country-Abfrageparameter und ein Standardwert zur Anforderung hinzugefügt werden.

Um sicherzustellen, dass jede Anforderung einen country-Abfrageparameter enthält, erstellen Sie eine API-Deployment-Spezifikation, die eine Abfrageparameter-Transformationsanforderungs-Policy enthält. Die Anforderungs-Policy fügt allen Anforderungen, die den Abfrageparameter country noch nicht enthalten, den Abfrageparameter country und einen Standardwert hinzu.

        "requestPolicies": {
          "queryParameterTransformations": {
            "setQueryParameters": {
              "items": [
                {
                  "name": "country",
                  "values": ["usa"],
                  "ifExists": "SKIP"
                }
              ]
            }
          }
        }

In diesem Beispiel wird eine Anforderung wie https://<gateway-hostname>/marketing/weather in https://api.weather.gov?country=usa aufgelöst. Eine Anforderung wie https://<gateway-hostname>/marketing/weather?country=canada wird in https://api.weather.gov?country=canada aufgelöst.

Geschützte Anforderungsheader und Antwortheader

Mit Headertransformations-Policys können Sie bestimmte geschützte Anforderungs- und Antwortheader nicht wie folgt transformieren:

Header Als Anforderungsheader geschützt Als Antwortheader geschützt
access-control-allow-credentials Nicht anwendbar Ja
access-control-allow-headers Nicht anwendbar Ja
access-control-allow-methods Nicht anwendbar Ja
access-control-allow-origin Nicht anwendbar Ja
access-control-expose-headers Nicht anwendbar Ja
access-control-max-age Nicht anwendbar Ja
CDN-Schleife Ja Nicht anwendbar
Verbindung Ja Ja
content-länge Ja Ja
Cookie Ja Nicht anwendbar
ausgenommen Ja Ja
Keepalive Ja Ja
opc-request-id Ja Ja
Ursprung Ja Nicht anwendbar
Proxy-Authentifizierung Nicht anwendbar Ja
Proxyautorisierung Ja Nicht anwendbar
Public-Key-PINs Nicht anwendbar Ja
Wiederholen - danach Nicht anwendbar Ja
Strikte Transportsicherheit Nicht anwendbar Ja
Te Ja Ja
Anhänger Nicht anwendbar Ja
Transfercodierung Ja Ja
Upgrade Ja Ja
x-Inhaltstyp-Optionen Nicht anwendbar Ja
x-forwarded-for Ja Nicht anwendbar
x-Rahmen-Optionen Nicht anwendbar Ja
x-real-ip Ja Nicht anwendbar
x-x-xss-Schutz Nicht anwendbar Ja