Anfordern von Referenzen und Berechtigungen auf Objektebene bei Verbrauchern

Unter diesem Thema wird beschrieben, wie Anbieter den Zugriff auf im Verbraucherkonto bestehende Datenbankobjekte anfordern können.

Allgemeine Informationen zu Referenzen

In bestimmten Kontexten muss eine installierte Snowflake Native App auf bestehende Objekte im Verbraucherkonto zugreifen, die außerhalb des APPLICATION-Objekts existieren. Zum Beispiel könnte eine Snowflake Native App auf bestehende Tabellen in einer Verbraucherdatenbank zugreifen müssen.

In diesem Fall reicht es nicht aus, wenn der Verbraucher der Snowflake Native App Zugriff auf ein Objekt gewährt. Die Snowflake Native App kann die Namen der Schemata und Objekte nicht ermitteln, die im Verbraucherkonto vorhanden sind. Weitere Informationen dazu finden Sie unter Auflösung des Objektnamens.

Damit die Snowflake Native App eine Verbindung zu diesen Arten von Objekten herstellen kann, ermöglicht das Snowflake Native App Framework die Verwendung von Referenzen, mit denen der Kunde die Namen der Objekte angeben und die erforderlichen Berechtigungen erteilen kann.

Workflow zum Definieren von Referenzen im Verbraucherkonto

Um eine Berechtigung auf Referenz- und Objektebene anzufordern, führt der Anbieter bei Entwicklung und Veröffentlichung einer Snowflake Native App folgende Schritte aus:

  1. Ermitteln der Objekte, die Referenzen mit den entsprechenden Berechtigungen benötigen

  2. Definieren der Referenzen in der Manifest-Datei

  3. Hinzufügen einer gespeicherten Prozedur in das Setup-Skript, um den Callback für jede in der Manifest-Datei definierte Referenz zu verarbeiten.

Nach der Installation der Snowflake Native App führt der Verbraucher Folgendes aus:

  1. Anzeigen der von der Snowflake Native App benötigten Referenzen.

  2. Erstellen der Referenz durch Aufrufen der Systemfunktion SYSTEM$REFERENCE

  3. Ausführen der gespeicherten Callback-Prozedur mit Übergabe der ID der Referenz

Nachdem der Verbraucher die gespeicherte Callback-Prozedur ausgeführt hat, kann die Snowflake Native App auf das angeforderte Objekt zugreifen.

Dieser Workflow beschreibt den Prozess, bei dem der Verbraucher die Referenz manuell erstellt. Unter Erstellen einer Benutzeroberfläche zum Anfordern von Berechtigungen und Referenzen finden Sie Informationen zum Erstellen einer Benutzeroberfläche, über die die Verbraucher mit Snowsight Referenzen erstellen und Berechtigungen erteilen können.

Objekttypen und Berechtigungen, die eine Referenz enthalten kann

In der folgenden Tabelle sind die Objekttypen aufgeführt, die eine Referenz enthalten können, sowie die Berechtigungen, die für jedes Objekt zulässig sind:

Objekttyp

Zulässige Berechtigungen

TABLE

SELECT, INSERT, UPDATE, DELETE, TRUNCATE, REFERENCES

VIEW

SELECT, REFERENCES

EXTERNAL TABLE

SELECT, REFERENCES

FUNCTION

USAGE

PROCEDURE

USAGE

WAREHOUSE

MODIFY, MONITOR, USAGE, OPERATE

API INTEGRATION

USAGE

Definieren einer Referenz in der Manifest-Datei

Das folgende Beispiel zeigt, wie Sie in der Datei manifest.yml eine Referenz auf eine Tabelle definieren, die außerhalb des APPLICATION-Objekts existiert:

references:
- my_table:
  label: "My table"
  description: "A table that exists outside the Snowflake Native App"
  privileges:
  - SELECT
  object_type: TABLE
  multi_valued: false
  register_callback: config.register_reference
Copy

Im folgenden Beispiel wird eine Referenz namens my_table definiert, die die SELECT-Berechtigung für eine Tabelle benötigt. Die Eigenschaft register_callback gibt eine gespeicherte Prozedur an, die verwendet wird, um das Objekt an die Snowflake Native App zu binden.

Erstellen einer gespeicherten Callback-Prozedur für eine Referenz

Nach dem Definieren einer Referenz in der Datei manifest.yml muss ein Anbieter eine gespeicherte Prozedur in das Setup-Skript einfügen, um den Callback für die Referenz zu registrieren.

Im folgenden Beispiel wird eine gespeicherte Prozedur gezeigt, mit der ein Callback für die unter Definieren einer Referenz in der Manifest-Datei gezeigte Referenz verarbeitet werden kann:

CREATE APPLICATION ROLE app_admin;

CREATE OR ALTER VERSIONED SCHEMA config;
GRANT USAGE ON SCHEMA config TO APPLICATION ROLE app_admin;

CREATE PROCEDURE CONFIG.REGISTER_SINGLE_CALLBACK(ref_name STRING, operation STRING, ref_or_alias STRING)
  RETURNS STRING
  LANGUAGE SQL
  AS $$
    BEGIN
      CASE (operation)
        WHEN 'ADD' THEN
          SELECT SYSTEM$SET_REFERENCE(:ref_name, :ref_or_alias);
        WHEN 'REMOVE' THEN
          SELECT SYSTEM$REMOVE_REFERENCE(:ref_name);
        WHEN 'CLEAR' THEN
          SELECT SYSTEM$REMOVE_REFERENCE(ref_name);
      ELSE
        RETURN 'unknown operation: ' || operation;
      END CASE;
      RETURN NULL;
    END;
  $$;

GRANT USAGE ON PROCEDURE CONFIG.REGISTER_SINGLE_CALLBACK(STRING, STRING, STRING)
  TO APPLICATION ROLE app_admin;
Copy

In diesem Beispiel wird eine gespeicherte Prozedur namens REGISTER_SINGLE_CALLBACK erstellt, die eine Systemfunktion aufruft, um eine bestimmte Operation auf einer Referenz auszuführen, die als Argument an die gespeicherte Prozedur übergeben wird.

Anzeigen der in einer Anwendung definierten Referenzen

Wenn ein Anbieter Referenzen in der Datei manifest.yml definiert hat, werden diese als Teil der installierten Snowflake Native App.

Um die für eine Snowflake Native App definierten Referenzen anzuzeigen, führen Sie den Befehl SHOW REFERENCES aus, wie im folgenden Beispiel gezeigt:

SHOW REFERENCES IN APPLICATION hello_snowflake_app;
Copy

Binden eines Objekts an die Anwendung

Nachdem der Verbraucher die Referenzdefinition für eine Snowflake Native App angezeigt hat, ermittelt der Verbraucher den Bezeichner der Referenz durch Ausführen der Systemfunktion SYSTEM$REFERENCE wie im folgenden Beispiel gezeigt:

SELECT SYSTEM$REFERENCE('table', 'db1.schema1.tab1', 'persistent', 'select', 'insert');
Copy

Dieser Befehl gibt einen Bezeichner für die Referenz zurück. Der Verbraucher kann den Bezeichner an die gespeicherte Callback-Prozedur für die Referenz übergeben, wie im folgenden Beispiel gezeigt:

CALL app.config.register_single_callback(
 SYSTEM$REFERENCE('TABLE', 'db1.schema1.tab1', 'PERSISTENT', 'SELECT', 'INSERT'), 'ADD', null);
Copy

Nachdem der Verbraucher die gespeicherte Callback-Prozedur ausgeführt hat, kann die Snowflake Native App auf die Tabelle im Verbraucherkonto zugreifen.

Die gespeicherte Callback-Prozedur aus dem vorherigen Abschnitt ruft die Systemfunktion SYSTEM$SET_REFERENCE auf, wie im folgenden Beispiel gezeigt:

SELECT SYSTEM$SET_REFERENCE(:ref_name, :ref_or_alias);
Copy

Weitere Systemfunktionen in Bezug zu Referenzen finden Sie unter Unterstützte Referenzfunktionen.

Hinweise zur Verwendung von Referenzen

Snowflake empfiehlt, dass Sie Referenzdefinitionen nicht versionsübergreifend ändern. Um eine Referenzdefinition in einer neuen Version zu aktualisieren, um z. B. die Berechtigungen auf SELECT, INSERT von SELECT zu ändern, müssen Sie eine neue Referenzdefinition mit einem anderen Namen definieren. Die aktualisierte Snowflake Native App kann diese neue Referenz in der neuen Version der App verwenden.

Um eine Referenz in ein anderes Objekt einzubetten, z. B. um eine Referenz einer Variablen zuzuweisen, muss die Referenz bereits an ein Objekt des Verbraucherkontos gebunden sein. Sie können z. B. eine Aufgabe erst dann erstellen, wenn die Referenz vorher an das Verbraucher-Warehouse gebunden wurde.

Referenzen funktionieren nicht in einem APPLICATION-Objekt, das im Entwicklungsmodus installiert wurde und Dateien in einem benannten Stagingbereich verwendet. Referenzen funktionieren nur in einem APPLICATION-Objekt, das eine Version hat, oder in einer Snowflake Native App, die in einem anderen Konto aus einem Angebot installiert wurde.

Beispiel für Verwendung von Referenzen in einer Snowflake Native App.

Die folgenden Abschnitte enthalten Beispiele für die Verwendung von Referenzen in unterschiedlichen Kontexten:

Ausführen von Abfragen unter Verwendung einer Referenz

Die folgenden Beispiele zeigen, wie Sie Abfragen unter Verwendung von Referenzen ausführen können:

SELECT * FROM reference('enrichment_table');
Copy
SELECT reference('encrypt_func')(t.c1) FROM my_table t;
Copy

Aufrufen einer gespeicherten Prozedur über eine Referenz

Im folgenden Beispiel wird gezeigt, wie Sie eine gespeicherte Prozedur unter Verwendung einer Referenz aufrufen:

CALL reference('consumer_proc')(11, 'hello world');
Copy

Ausführen von DML-Befehlen unter Verwendung einer Referenz

Die folgenden Beispiele zeigen, wie Sie Daten in einer Tabelle unter Verwendung von Referenzen ändern können:

INSERT INTO reference('data_export')(C1, C2)
  SELECT T.C1, T.C2 FROM reference('other_table')
Copy
COPY INTO reference('the_table') ...
Copy

Ausführen des Befehls DESCRIBE unter Verwendung einer Referenz

Das folgende Beispiel zeigt, wie Sie die Operation DESCRIBE unter Verwendung einer Referenz ausführen:

DESCRIBE TABLE reference('the_table')
Copy

Verwenden von Referenzen in einer Aufgabe

CREATE TASK app_task
  WAREHOUSE = reference('consumer_warehouse')
  ...;

ALTER TASK app_task SET WAREHOUSE = reference('consumer_warehouse');
Copy

Verwenden von Referenzen in einer Ansichtsdefinition

CREATE VIEW app_view
  AS SELECT reference('function')(T.C1) FROM reference('table') AS T;
Copy

Verwenden von Referenzen im Textteil einer Funktion

CREATE FUNCTION app.func(x INT)
  RETURNS STRING
  AS $$ select reference('consumer_func')(x) $$;
Copy

Verwenden von Referenzen in einer externen Funktion

CREATE EXTERNAL FUNCTION app.func(x INT)
  RETURNS STRING
  ...
  API_INTEGRATION = reference('app_integration');
Copy

Verwenden von Referenzen in einer Richtlinie

CREATE ROW ACCESS POLICY app_policy
  AS (sales_region varchar) RETURNS BOOLEAN ->
  'sales_executive_role' = reference('get_sales_team')
    or exists (
      select 1 from reference('sales_table')
        where sales_manager = reference('get_sales_team')()
        and region = sales_region
      );
Copy

Unterstützte Referenzfunktionen

Das Snowflake Native App Framework unterstützt die folgenden Funktionen, um verschiedene Operationen im Zusammenhang mit Referenzen auszuführen.

Systemfunktion

Beschreibung

set_reference

SYSTEM$SET_REFERENCE('<Name_der_Referenz>', '<Zeichenfolge_der_Referenz>')

  • Unterstützt nur eine einzige Referenz. Wenn bereits eine Referenz mit demselben Namen erstellt wurde, wird die vorhandene Referenz überschrieben.

  • Gibt einen eindeutigen, vom System generierten Alias für die Referenz zurück.

add_reference

SYSTEM$ADD_REFERENCE('<Name_der_Referenz>', '<Zeichenfolge_der_Referenz>')

  • Unterstützt sowohl Referenzen mit einem einzelnen Wert als auch Referenzen mit mehreren Werten. Bei einwertigen Referenzen gibt die Funktion einen Fehler zurück, wenn bereits eine Referenz mit demselben Wert erstellt wurde, der durch <Name_der_Referenz> angegeben wurde.

  • Gibt einen eindeutigen, vom System generierten Alias für die Referenz zurück.

remove_reference

SYSTEM$REMOVE_REFERENCE('<Name_der_Referenz>'[, '<Alias>'])

  • Unterstützt sowohl Referenzen mit einem einzelnen Wert als auch Referenzen mit mehreren Werten. Ein <Alias> ist erforderlich, um mehrwertige Referenzen zu entfernen.

  • Entfernt eine Zuordnung zu einer mehrwertigen Referenz.

remove_all_references

SYSTEM$REMOVE_ALL_REFERENCES('<Name_der_Referenz>')

  • Entfernt alle Zuordnungen zu der Referenz.

get_all_references

SYSTEM$GET_ALL_REFERENCES('<Name_der_Referenz>')

  • Gibt ein Array mit vom System generierten Aliassen von Entitäten zurück, die einem Referenznamen zugeordnet sind:

    • Leere Liste, wenn der Referenzname nicht an eine Entität gebunden ist

    • Alle Zuordnungen bei mehrwertigen Referenzen

    • 1 oder 0 Zuordnung für einwertige Referenzen

    • Der zurückgegebene Wert enthält nicht den Objektnamen des Verbrauchers

  • Wird verwendet, um in einer Schleife durch alle Zuordnungen einer mehrwertigen Referenz zu iterieren.

get_referenced_object_id_hash

SYSTEM$GET_REFERENCED_OBJECT_ID_HASH('<Name_der_Referenz>'[, '<Alias>'])

  • Verwendet für eine mehrwertige Referenz einen vom System generierten Alias.

  • Gibt den Hash-Wert der Entity-ID des gebundenen Objekts zurück. Dies ist der Bezeichner der Entität, die ursprünglich beim Erstellen einer Referenz aufgelöst wurde.

  • Diese Funktion ist für die Snowflake Native App nützlich, um festzustellen, ob das an eine Referenz gebundene Objekt geändert wurde. Die Snowflake Native App kann den Wert speichern und dann den aktuellen Wert mit dem zuvor bekannten Wert vergleichen.