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:
-
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.
-
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.
-
Wählen Sie Weiter aus, um Details zu einzelnen Routen im API-Deployment auf der Seite Routen einzugeben.
- Wählen Sie auf der Seite Routen die Route aus, für die Sie Headertransformationsanforderungs-Policys angeben möchten.
- Wählen Sie Routenanforderungs-Policys einblenden aus.
- 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.
-
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
.
-
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
.
-
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]}"
.
- Wählen Sie Änderungen speichern und dann Weiter aus, um die Details zu prüfen, die Sie für einzelne Routen eingegeben haben.
- Wählen Sie Erstellen oder Änderungen speichern aus, um das API-Deployment zu erstellen oder zu aktualisieren.
- (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:
-
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" } } ] }
-
Fügen Sie einen
requestPolicies
-Abschnitt nach dembackend
-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": {} } ] }
-
Fügen Sie dem Abschnitt
requestPolicies
einenheaderTransformations
-Abschnitt hinzu.{ "routes": [ { "path": "/hello", "methods": ["GET"], "backend": { "type": "ORACLE_FUNCTIONS_BACKEND", "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq" }, "requestPolicies": { "headerTransformations":{} } } ] }
-
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).
- Verwenden Sie
"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 inALLOW
-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. -
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 inALLOW
-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 inX-User-ID
um, wobei der ursprüngliche Wert des Headers beibehalten wird. -
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 inALLOW
-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ßerrequest.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. - Verwenden Sie
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 einX-Api-Key
-Header auf einen anderen Wert gesetzt ist, ersetzt das API-Gateway den vorhandenen Wert durchzyx987wvu654tsu321
. - Speichern Sie die JSON-Datei, die die API-Deployment-Spezifikation enthält.
-
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.
- (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:
-
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.
-
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.
-
Wählen Sie Weiter aus, um Details zu einzelnen Routen im API-Deployment auf der Seite Routen einzugeben.
- Wählen Sie auf der Seite Routen die Route aus, für die Sie Abfrageparameter-Transformationsanforderungs-Policys angeben möchten.
- Wählen Sie Routenanforderungs-Policys einblenden aus.
- 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.
-
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
.
-
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
.
-
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.
- Wählen Sie Änderungen speichern und dann Weiter aus, um die Details zu prüfen, die Sie für einzelne Routen eingegeben haben.
- Wählen Sie Erstellen oder Änderungen speichern aus, um das API-Deployment zu erstellen oder zu aktualisieren.
- (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:
-
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" } } ] }
-
Fügen Sie einen
requestPolicies
-Abschnitt nach dembackend
-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": {} } ] }
-
Fügen Sie dem Abschnitt
requestPolicies
einenqueryParameterTransformations
-Abschnitt hinzu.{ "routes": [ { "path": "/hello", "methods": ["GET"], "backend": { "type": "ORACLE_FUNCTIONS_BACKEND", "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq" }, "requestPolicies": { "queryParameterTransformations":{} } } ] }
-
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).
- Verwenden Sie
"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 inALLOW
-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. -
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 inALLOW
-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 inX-User-ID
um, wobei der ursprüngliche Wert des Abfrageparameters beibehalten wird. -
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 inALLOW
-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. - Verwenden Sie
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 einX-Api-Key
-Abfrageparameter auf einen anderen Wert gesetzt ist, ersetzt das API-Gateway den vorhandenen Wert durchzyx987wvu654tsu321
. - Speichern Sie die JSON-Datei, die die API-Deployment-Spezifikation enthält.
-
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.
- (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:
-
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.
-
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.
-
Wählen Sie Weiter aus, um Details zu einzelnen Routen im API-Deployment auf der Seite Routen einzugeben.
- Wählen Sie auf der Seite Routen die Route aus, für die Sie Headertransformationsantwort-Policys angeben möchten.
- Wählen Sie Routenantwort-Policys einblenden aus.
- 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.
-
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
.
-
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
.
-
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.
- Wählen Sie Änderungen speichern und dann Weiter aus, um die Details zu prüfen, die Sie für einzelne Routen eingegeben haben.
- Wählen Sie Erstellen oder Änderungen speichern aus, um das API-Deployment zu erstellen oder zu aktualisieren.
- (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:
-
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" } } ] }
-
Fügen Sie einen
responsePolicies
-Abschnitt nach dembackend
-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": {} } ] }
-
Fügen Sie dem Abschnitt
responsePolicies
einenheaderTransformations
-Abschnitt hinzu.{ "routes": [ { "path": "/hello", "methods": ["GET"], "backend": { "type": "ORACLE_FUNCTIONS_BACKEND", "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq" }, "responsePolicies": { "headerTransformations":{} } } ] }
-
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).
- Verwenden Sie
"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 inALLOW
-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. -
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 inALLOW
-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 inX-User-ID
um, wobei der ursprüngliche Wert des Headers beibehalten wird. -
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 inALLOW
-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. - Verwenden Sie
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 einX-Api-Key
-Header auf einen anderen Wert gesetzt ist, ersetzt das API-Gateway den vorhandenen Wert durchzyx987wvu654tsu321
. - Speichern Sie die JSON-Datei, die die API-Deployment-Spezifikation enthält.
-
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.
- (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 |