Snowflake-Kontext mit Snowflake REST APIs angeben

Sie können Aspekte des Snowflake-Kontexts angeben, wenn Sie eine Anforderung an Snowflake REST APIs stellen.

Unter Verwendung von Anforderungsheadern können Sie im Kontext eines REST API-Aufrufs Folgendes angeben:

  • Die Snowflake-Rolle zur Autorisierung der Anforderung mit dem X-Snowflake-Role-Header.

  • Das Snowflake-Warehouse, das zur Ausführung der Anforderung mit X-Snowflake-Warehouse-Header verwendet wird.

Anstatt sich auf die Standardeinstellungen eines Benutzenden zu verlassen, machen diese Header jeden Aufruf explizit, isoliert und überprüfbar. Sie sorgen dafür, dass jede Anforderung die richtige Rolle und das richtige Warehouse verwendet, ohne dass zusätzliche API-Aufrufe benötigt werden, um den Kontext festzulegen.

Durch Angabe des Kontexts bei der Erstellung von REST API-Anforderungen können Sie folgende Aufgaben erledigen:

  • Zustandslose Aufrufe ausführen.

    Stellen Sie sicher, dass ein Aufruf eine bestimmte Rolle verwendet, ohne dass zuerst ein separater API-Aufruf erforderlich ist, um den Sitzungskontext festzulegen.

  • Benutzerwechsel vermeiden.

    Rollen müssen auf sichere Weise pro Anforderung gewechselt werden, sodass nicht ALTER USER … SET DEFAULT_ROLE=… ausgeführt werden muss, was langsam ist und sich auf alle anderen Sitzungen dieses Benutzenden auswirkt.

  • Bedarfsgesteuertes Compute aktivieren.

    Erlauben Sie Benutzenden oder Dienstkonten ohne Standard-Warehouse, Abfragen auszuführen oder Prozeduren zu erstellen, indem einfach der X-Snowflake-Warehouse-Header bereitgestellt wird.

  • Benutzerverwaltung vereinfachen.

    Verwenden Sie einen Dienstbenutzer mit mehreren Rollen, z. B. READER und WRITER. Ihre Anwendung sendet dann den X-Snowflake-Role-Header, um die richtige Berechtigung für die richtige Aufgabe auszuwählen. Auf diese Weise können Sie die Verwaltung mehrerer Einzelrollen-Benutzender vermeiden.

Rangfolge

Wenn ein Header bereitgestellt wird, hat dieser Vorrang vor den Standardeinstellungen der Benutzenden, und zwar in der folgenden Reihenfolge:

  1. Header (falls bereitgestellt) werden verwendet.

  2. Andernfalls wird die Standardrolle oder das Standard-Warehouse der Sitzung verwendet.

  3. Wenn beides bei Bedarf nicht verfügbar ist, schlägt der Aufruf fehl.

Rolle angeben, die bei Autorisierung der Anforderung verwendet werden soll

Sie können die Rolle angeben, die bei der Autorisierung der Anforderung verwendet werden soll, indem Sie den X-Snowflake-Role-Header verwenden.

Anforderungen

  • Die von Ihnen angegebene Rolle muss vorhanden, dem Benutzenden zugewiesen und von der verwendeten Authentifizierungsmethode zugelassen sein.

  • Wenn Sie ein programmgesteuertes Zugriffstoken (Programmatic Access Token, PAT) verwenden, muss sich die angeforderte Rolle innerhalb der ROLE_RESTRICTION des PAT befinden. Wenn Sie eine Rolle angeben, die mehr Berechtigungen hat, als der PAT zulässt, schlägt die Anforderung fehl, auch wenn dem Benutzenden die angegebene Rolle zugewiesen wurde.

Beispiel

Im folgenden Beispiel wird eine Datenbank unter Verwendung der Rolle ACCOUNTADMIN zur Autorisierung erstellt, und zwar unabhängig von der Standardrolle des Benutzenden.

Sie können den Wert des X-Snowflake-Role-Headers entweder in doppelten Anführungszeichen oder ohne Anführungszeichen angeben.

curl -X POST "$API_BASE/database/databases" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Snowflake-Role: ACCOUNTADMIN" \
  -d '{"name": "HDR_DEMO_DB", "comment": "Created via REST with role header"}'
Copy

Geben Sie das Warehouse an, für das eine Anweisung ausgeführt werden soll.

Sie können das Warehouse angeben, das bei der Ausführung von Anweisungen verwendet werden soll, indem Sie den X-Snowflake-Warehouse-Header verwenden. Zu diesen Anweisungen gehören solche, die Prozeduren ausführen, Python-Funktionen erstellen und Abfragen ausführen, die Computeressourcen benötigen.

Anforderungen

  • Die tatsächliche Rolle muss die USAGE-Berechtigung für das Warehouse haben.

  • Wenn kein Standard-Warehouse festgelegt ist und dieser Header weggelassen wird, schlagen Warehouse-abhängige Aufrufe fehl.

Beispiel

Im folgenden Beispiel wird eine Python-Prozedur erstellt, die das Warehouse BUILD_WH verwendet. Die angegebene Rolle muss über die USAGE-Berechtigung für das Warehouse verfügen. Die erstellte PYTHON_WH_TEST-Prozedur gibt den Namen des aktiven Warehouses zurück.

Sie können den Wert des X-Snowflake-Warehouse-Headers entweder in doppelten Anführungszeichen oder ohne Anführungszeichen angeben.

curl -X POST "$API_BASE/procedure/databases/TEST_DB/schemas/TEST_SCHEMA/procedures" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Snowflake-Role: ACCOUNTADMIN" \
  -H "X-Snowflake-Warehouse: BUILD_WH" \
  -d '{
        "name": "PYTHON_WH_TEST",
        "arguments": [],
        "return_type": {"datatype": "VARIANT", "nullable": true},
        "language_config": {
          "python_function": {
            "handler":"main",
            "runtime_version":"3.11",
            "packages":["snowflake-snowpark-python"]
          }
        },
        "body": "def main(session):\n    return {\"warehouse\": session.get_current_warehouse()}"
      }'
Copy
Sprache: Deutsch