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:
Ermitteln der Objekte, die Referenzen mit den entsprechenden Berechtigungen benötigen
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:
Anzeigen der von der Snowflake Native App benötigten Referenzen.
Erstellen der Referenz durch Aufrufen der Systemfunktion SYSTEM$REFERENCE
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
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;
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;
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');
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);
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);
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');
SELECT reference('encrypt_func')(t.c1) FROM my_table t;
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');
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 INTO reference('the_table') ...
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')
Verwenden von Referenzen in einer Aufgabe¶
CREATE TASK app_task
WAREHOUSE = reference('consumer_warehouse')
...;
ALTER TASK app_task SET WAREHOUSE = reference('consumer_warehouse');
Verwenden von Referenzen in einer Ansichtsdefinition¶
CREATE VIEW app_view
AS SELECT reference('function')(T.C1) FROM reference('table') AS T;
Verwenden von Referenzen im Textteil einer Funktion¶
CREATE FUNCTION app.func(x INT)
RETURNS STRING
AS $$ select reference('consumer_func')(x) $$;
Verwenden von Referenzen in einer externen Funktion¶
CREATE EXTERNAL FUNCTION app.func(x INT)
RETURNS STRING
...
API_INTEGRATION = reference('app_integration');
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
);
Unterstützte Referenzfunktionen¶
Das Snowflake Native App Framework unterstützt die folgenden Funktionen, um verschiedene Operationen im Zusammenhang mit Referenzen auszuführen.
Systemfunktion |
Beschreibung |
---|---|
|
|
|
|
remove_reference |
|
|
|
|
|
|
|