Anfordern von Referenzen und Berechtigungen auf Objektebene bei Verbrauchern¶

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.

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:

SELECT * FROM reference('enrichment_table');

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

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

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

COPY INTO reference('the_table') ...

DESCRIBE TABLE reference('the_table')

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

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

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

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

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

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.