Oracle Cloud Infrastructure - Dokumentation

CORS-Support zu API-Deployments hinzufügen

Erfahren Sie, wie Sie mit einer Anforderungs-Policy CORS-Support zu API-Deployments mit API-Gateway hinzufügen.

Webbrowser implementieren in der Regel eine "Same Origin Policy", um zu verhindern, dass Code Anforderungen an einen anderen Ursprung stellt als an den, von dem er bedient wurde. Die Same Origin Policy soll Schutz vor schädlichen Websites bieten. Die Same Origin Policy kann jedoch auch legitime Interaktionen zwischen einem Server und Clients eines bekannten und vertrauenswürdigen Ursprungs verhindern.

Cross-Origin Resource Sharing (CORS) ist ein ursprungsübergreifender Sharing-Standard zur Lockerung der Same Origin Policy, indem Code auf einer Webseite eine REST-API konsumieren darf, die von einem anderen Ursprung bedient wird. Der CORS-Standard verwendet zusätzliche HTTP-Anforderungsheader und -Antwortheader, um die Ursprünge anzugeben, auf die zugegriffen werden kann.

Der CORS-Standard erfordert außerdem, dass die Anforderung bei bestimmten HTTP-Anforderungsmethoden einer "Preflight"-Prüfung unterzogen werden muss. Bevor die tatsächliche Anforderung gesendet wird, sendet der Webbrowser eine Preflight-Anforderung an den Server, um zu ermitteln, ob die Methoden in der tatsächlichen Anforderung unterstützt werden. Der Server antwortet mit den Methoden, die er in einer tatsächlichen Anforderung zulässt. Der Webbrowser sendet die tatsächliche Anforderung nur dann, wenn in der vom Server gesendeten Antwort angegeben ist, dass die Methoden in der tatsächlichen Anforderung zulässig sind. Der CORS-Standard ermöglicht es den Servern auch, Clients darüber zu benachrichtigen, ob Anforderungen Zugangsdaten (Cookies, Autorisierungsheader oder TLS-Clientzertifikate) enthalten dürfen.

Weitere Informationen zu CORS finden Sie in den online verfügbaren Ressourcen, einschließlich derer aus W3C und Mozilla.

Mit dem API-Gateway-Service können Sie CORS-Support in den APIs aktivieren, die Sie in API-Gateways bereitstellen. Wenn Sie CORS-Unterstützung in einem API-Deployment aktivieren, geben HTTP-Preflight-Anforderungen und tatsächliche Anforderungen an das API-Deployment mindestens einen CORS-Antwortheader an den API-Client zurück. Sie legen die CORS-Antwortheaderwerte in der API-Deployment-Spezifikation fest.

Sie verwenden Anforderungs-Policys, um CORS-Support zu APIs hinzuzufügen (siehe Anforderungs-Policys und Antwort-Policys zu API-Deployment-Spezifikationen hinzufügen). Sie können eine CORS-Anforderungs-Policy global auf alle Routen in einer API-Deployment-Spezifikation oder nur auf bestimmte Routen anwenden.

Sie können eine CORS-Anforderungs-Policy zu einer API-Deployment-Spezifikation hinzufügen, indem Sie:

  • die Konsole verwenden
  • eine JSON-Datei bearbeiten

CORS-Anforderungs-Policys mit der Konsole hinzufügen

So fügen Sie mit der Konsole eine CORS-Anforderungs-Policy 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 auf der Seite Basisinformationen im Abschnitt API-Anforderungs-Policys neben CORS die Schaltfläche Hinzufügen aus, und geben Sie:

    • Zulässige Ursprünge: Einen Ursprung, der zum Zugriff auf das API-Deployment berechtigt ist. Beispiel: https://oracle.com. Wählen Sie + Weiterer Ursprung aus, um einen zweiten Ursprung sowie weitere Ursprünge einzugeben.
    • Zulässige Methoden: Eine oder mehrere Methoden, die in der tatsächlichen Anforderung an das API-Deployment zulässig sind. Beispiel: GET, PUT.
    • Zulässige Header: Optional ein HTTP-Header, der in der tatsächlichen Anforderung an das API-Deployment zulässig ist. Beispiel: opc-request-id oder If-Match. Wählen Sie + Weiterer Header aus, um einen zweiten Header sowie weitere Header einzugeben.
    • Angezeigte Header: Optional ein HTTP-Header, auf den API-Clients in der Antwort des API-Deployments auf eine tatsächliche Anforderung zugreifen können. Beispiel: ETag oder opc-request-id. Wählen Sie + Weiterer Header aus, um einen zweiten Header sowie weitere Header einzugeben.
    • Max. Alter in Sekunden: Optional ein ganzzahliger Wert, der angibt, wie lange (in Deltasekunden) die Ergebnisse einer Preflight-Anforderung von einem Browser gecacht werden können. Wenn Sie keinen Wert angeben, wird standardmäßig 0 verwendet.
    • Zulassen von Zugangsdaten aktivieren: Ob die tatsächliche Anforderung an das API-Deployment mit Zugangsdaten (Cookies, Autorisierungsheader oder TLS-Clientzertifikate) gestellt werden kann. Standardmäßig ist diese Option nicht ausgewählt.

    Unter So wird eine CORS-Anforderungs-Policy einer CORS-Antwort zugeordnet wird beschrieben, wie die unterschiedlichen Felder in der CORS-Anforderungs-Policy unterschiedlichen CORS-Antwortheadern zugeordnet werden.

  3. Wählen Sie Änderungen anwenden aus.

  4. Wählen Sie Weiter aus, um Authentifizierungsoptionen auf der Seite Authentifizierung anzugeben.

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

  5. Wählen Sie Weiter aus, um Details zu einzelnen Routen im API-Deployment auf der Seite Routen einzugeben. Um CORS-Anforderungs-Policys anzugeben, die für eine einzelne Route gelten sollen, wählen Sie Routenanforderungs-Policys einblenden und dann die Schaltfläche Hinzufügen neben CORS aus, und geben Sie:

    • Zulässige Ursprünge: Ein Ursprung, der zum Zugriff auf die Route berechtigt ist. Beispiel: https://oracle.com. Wählen Sie + Weiterer Ursprung aus, um einen zweiten Ursprung sowie weitere Ursprünge einzugeben.
    • Zulässige Methoden: Eine oder mehrere Methoden, die in der tatsächlichen Anforderung an die Route zulässig sind. Beispiel: GET, PUT.
    • Zulässige Header: Optional ein HTTP-Header, der in der tatsächlichen Anforderung an die Route zulässig ist. Beispiel: opc-request-id oder If-Match. Wählen Sie + Weiterer Header aus, um einen zweiten Header sowie weitere Header einzugeben.
    • Angezeigte Header: Optional ein HTTP-Header, auf den API-Clients in der Antwort des API-Deployments auf eine tatsächliche Anforderung zugreifen können. Beispiel: ETag oder opc-request-id. Wählen Sie + Weiterer Header aus, um einen zweiten Header sowie weitere Header einzugeben.
    • Max. Alter in Sekunden: Optional ein ganzzahliger Wert, der angibt, wie lange (in Deltasekunden) die Ergebnisse einer Preflight-Anforderung von einem Browser gecacht werden können. Wenn Sie keinen Wert angeben, wird standardmäßig 0 verwendet.
    • Zulassen von Zugangsdaten aktivieren: Ob die tatsächliche Anforderung an die Route mit Zugangsdaten (Cookies, Autorisierungsheader oder TLS-Clientzertifikate) gestellt werden kann. Standardmäßig ist diese Option nicht ausgewählt.

    Unter So wird eine CORS-Anforderungs-Policy einer CORS-Antwort zugeordnet wird beschrieben, wie die unterschiedlichen Felder in der CORS-Anforderungs-Policy unterschiedlichen CORS-Antwortheadern zugeordnet werden.

  6. Wählen Sie Änderungen anwenden und dann Weiter aus, um die Details zu prüfen, die Sie für das API-Deployment und die einzelnen Routen eingegeben haben.
  7. Wählen Sie Erstellen oder Änderungen speichern aus, um das API-Deployment zu erstellen oder zu aktualisieren.
  8. (Optional) Bestätigen Sie, dass die API erfolgreich bereitgestellt wurde, indem Sie sie aufrufen (siehe In einem API-Gateway bereitgestellte API aufrufen).

JSON-Datei zum Hinzufügen von CORS-Anforderungs-Policys bearbeiten

So fügen Sie eine CORS-Anforderungs-Policy 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 CORS-Support 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. So geben Sie eine CORS-Anforderungs-Policy an, die global für alle Routen in einem API-Deployment gilt:

    1. Fügen Sie, falls noch nicht vorhanden, einen requestPolicies-Abschnitt vor dem routes-Abschnitt ein. Beispiel:

      {
  "requestPolicies": {},
  "routes": [
    {
      "path": "/hello",
      "methods": ["GET"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      }
    }
  ]
}

    2. Fügen Sie die folgende cors-Policy zum neuen requestPolicies-Abschnitt hinzu, um sie global auf alle Routen in einem API-Deployment anzuwenden:

      {
  "requestPolicies": {
    "cors":{
      "allowedOrigins": [<list-of-origins>],
      "allowedMethods": [<list-of-methods>],
      "allowedHeaders": [<list-of-implicit-headers>],
      "exposedHeaders": [<list-of-exposed-headers>],
      "isAllowCredentialsEnabled": <true|false>,
      "maxAgeInSeconds": <seconds>
    }
  },
  "routes": [
    {
      "path": "/hello",
      "methods": ["GET"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      }
    }
  ]
}

      Dabei gilt:

      • "allowedOrigins": [<list-of-origins>] ist eine erforderliche kommagetrennte Liste von Ursprüngen, die zum Zugriff auf das API-Deployment berechtigt sind. Beispiel: , "allowedOrigins": ["*", "https://oracle.com"]
      • "allowedMethods": [<list-of-methods>] ist eine optionale kommagetrennte Liste von HTTP-Methoden, die in der tatsächlichen Anforderung an das API-Deployment zulässig sind. Beispiel "allowedMethods": ["*", "GET"]
      • "allowedHeaders": [<list-of-implicit-headers>] ist eine optionale kommagetrennte Liste von HTTP-Headern, die in der tatsächlichen Anforderung an das API-Deployment zulässig sind. Beispiel: "allowedHeaders": ["opc-request-id", "If-Match"]
      • "exposedHeaders": [<list-of-exposed-headers>] ist eine optionale durch Komma getrennte Liste mit HTTP-Headern, auf die API-Clients in der Antwort des API-Deployments auf eine tatsächliche Anforderung zugreifen können. Beispiel "exposedHeaders": ["ETag", "opc-request-id"]
      • "isAllowCredentialsEnabled": <true|false> ist entweder true oder false und gibt an, ob die tatsächliche Anforderung an das API-Deployment mit Zugangsdaten (Cookies, Autorisierungsheader oder TLS-Clientzertifikate) gestellt werden kann. Wenn keine Angabe gemacht wird, wird standardmäßig false verwendet.
      • "maxAgeInSeconds": <seconds> ist ein ganzzahliger Wert, der angibt, wie lange (in Deltasekunden) die Ergebnisse einer Preflight-Anforderung von einem Browser gecacht werden können. Wenn keine Angabe gemacht wird, wird standardmäßig 0 verwendet.

      Beispiel:

      {
  "requestPolicies": {
    "cors":{
      "allowedOrigins": ["*", "https://oracle.com"],
      "allowedMethods": ["*", "GET"],
      "allowedHeaders": [],
      "exposedHeaders": [],
      "isAllowCredentialsEnabled": false,
      "maxAgeInSeconds": 3000
    }
  },
  "routes": [
    {
      "path": "/hello",
      "methods": ["GET"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      }
    }
  ]
}

      Unter So wird eine CORS-Anforderungs-Policy einer CORS-Antwort zugeordnet wird beschrieben, wie die unterschiedlichen Felder in der CORS-Anforderungs-Policy unterschiedlichen CORS-Antwortheadern zugeordnet werden.

  3. So geben Sie eine CORS-Anforderungs-Policy an, die für eine einzelne Route gelten soll:

    1. Fügen Sie nach dem Backend-Abschnitt einen requestPolicies-Abschnitt für die Route ein, für die die Policy gelten soll. Beispiel:

      {
  "routes": [
    {
      "path": "/hello",
      "methods": ["GET"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      },
      "requestPolicies": {}
    }
  ]
}
    2. Fügen Sie die folgende cors-Policy zum neuen requestPolicies-Abschnitt hinzu, um sie nur auf diese bestimmte Route anzuwenden:
      {
  "routes": [
    {
      "path": "/hello",
      "methods": ["GET"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      },
      "requestPolicies": {
        "cors":{
           "allowedOrigins": [<list-of-origins>],
           "allowedMethods": [<list-of-methods>],
           "allowedHeaders": [<list-of-implicit-headers>],
           "exposedHeaders": [<list-of-exposed-headers>],
           "isAllowCredentialsEnabled": <true|false>,
           "maxAgeInSeconds": <seconds>
        }
      }
    }
  ]
}

      Dabei gilt:

      • "allowedOrigins": [<list-of-origins>] ist eine erforderliche kommagetrennte Liste von Ursprüngen, die zum Zugriff auf das API-Deployment berechtigt sind. Beispiel: , "allowedOrigins": ["*", "https://oracle.com"]
      • "allowedMethods": [<list-of-methods>] ist eine optionale kommagetrennte Liste von HTTP-Methoden, die in der tatsächlichen Anforderung an das API-Deployment zulässig sind. Beispiel "allowedMethods": ["*", "GET"]
      • "allowedHeaders": [<list-of-implicit-headers>] ist eine optionale kommagetrennte Liste von HTTP-Headern, die in der tatsächlichen Anforderung an das API-Deployment zulässig sind. Beispiel: "allowedHeaders": ["opc-request-id", "If-Match"]
      • "exposedHeaders": [<list-of-exposed-headers>] ist eine optionale durch Komma getrennte Liste mit HTTP-Headern, auf die API-Clients in der Antwort des API-Deployments auf eine tatsächliche Anforderung zugreifen können. Beispiel "exposedHeaders": ["ETag", "opc-request-id"]
      • "isAllowCredentialsEnabled": <true|false> ist entweder true oder false und gibt an, ob die tatsächliche Anforderung an das API-Deployment mit Zugangsdaten (Cookies, Autorisierungsheader oder TLS-Clientzertifikate) gestellt werden kann. Wenn keine Angabe gemacht wird, wird standardmäßig false verwendet.
      • "maxAgeInSeconds": <seconds> ist ein ganzzahliger Wert, der angibt, wie lange (in Deltasekunden) die Ergebnisse einer Preflight-Anforderung von einem Browser gecacht werden können. Wenn keine Angabe gemacht wird, wird standardmäßig 0 verwendet.

      Beispiel:

      {
  "routes": [
    {
      "path": "/hello",
      "methods": ["GET"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      },
      "requestPolicies": {
        "cors":{
           "allowedOrigins": ["*", "https://oracle.com"],
           "allowedMethods": ["*", "GET"],
           "allowedHeaders": [],
           "exposedHeaders": [],
           "isAllowCredentialsEnabled": false,
           "maxAgeInSeconds": 3000
        }
      }
    }
  ]
}

      Unter So wird eine CORS-Anforderungs-Policy einer CORS-Antwort zugeordnet wird beschrieben, wie die unterschiedlichen Felder in der CORS-Anforderungs-Policy unterschiedlichen CORS-Antwortheadern zugeordnet werden.

  4. Speichern Sie die JSON-Datei, die die API-Deployment-Spezifikation enthält.

  5. 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.

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

So wird eine CORS-Anforderungs-Policy einer CORS-Antwort zugeordnet

Die unterschiedlichen Felder in einer CORS-Anforderungs-Policy werden, wie in der Tabelle gezeigt, unterschiedlichen CORS-Antwortheadern zugeordnet:

Feld Zuordnung zu CORS-Antwortheader In Antwort auf Preflight-Anforderung enthalten In Antwort auf tatsächliche Anforderung enthalten Hinweise
allowed Origins Access-Control-Allow-Origin Ja Ja

Erforderlich?: Ja

Datentyp: Zeichenfolge[]

Standard: n/v

Wird verwendet, um eine kommagetrennte Liste von Ursprüngen zurückzugeben, die zum Zugriff auf das API-Deployment berechtigt sind.

Die CORS-Spezifikation lässt nur einen Ursprung zu. Im Falle mehrerer Ursprünge muss der Clientursprung dynamisch anhand der Liste mit den zulässigen Werten geprüft werden. Die Werte "*" und "null" sind zulässig.
allowed Methods Access-Control-Allow-Methods Ja Nein

Erforderlich?: Nein

Datentyp: Zeichenfolge[]

Standard: Leere Liste

Wird verwendet, um eine kommagetrennte Liste von HTTP-Methoden zurückzugeben, die in der tatsächlichen Anforderung an das API-Deployment zulässig sind.

Access-Control-Allow-Methods lassen standardmäßig alle einfachen Methoden zu, selbst bei Preflight-Anforderungen.
allowed Headers Access-Control-Allow-Headers Ja Nein

Erforderlich?: Nein

Datentyp: Zeichenfolge[]

Standard: Leere Liste

Wird verwendet, um eine kommagetrennte Liste von HTTP-Headern zurückzugeben, die in der tatsächlichen Anforderung an das API-Deployment zulässig sind.

exposed Headers Access-Control-Expose-Headers Nein Ja

Erforderlich?: Nein

Datentyp: Zeichenfolge[]

Standard: Leere Liste

Wird verwendet, um eine kommagetrennte Liste von HTTP-Headern zurückzugeben, auf die Clients in der Antwort des API-Deployments auf eine tatsächliche Anforderung zugreifen können. Diese Liste von HTTP-Headern wird zusätzlich zu den CORS-sicheren Antwortheadern aufgeführt.
isAllow Credentials Enabled Access-Control-Allow-Credentials Ja Ja

Erforderlich?: Nein

Datentyp: Boolescher Wert

Standard: false

Wird verwendet, um true oder false zurückzugeben, und gibt an, ob die tatsächliche Anforderung an das API-Deployment mit Zugangsdaten (Cookies, Autorisierungsheader oder TLS-Clientzertifikate) gestellt werden kann.

Damit Anforderungen mit Zugangsdaten gestellt werden können, setzen Sie isAllowCredentialsEnabled auf true.
maxAge InSeconds Access-Control-Max-Age Ja Nein Erforderlich?: Nein

Datentyp: Ganzzahl

Standardwert: 0

Wird verwendet, um anzugeben, wie lange (in Deltasekunden) die Ergebnisse einer Preflight-Anforderung von einem Browser gecacht werden können Wird ignoriert, wenn auf 0 gesetzt.