Referenzen und Berechtigungen auf Objektebene von Verbrauchern anfordern

Unter diesem Thema wird beschrieben, wie Anbieter eine Snowflake Native App so konfigurieren können, dass diese Zugriff auf Objekte im Verbraucherkonto anfordert, die außerhalb des APPLICATION-Objekts existieren.

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. Eine App benötigt beispielsweise Zugriff auf bestehende Tabellen in einer Verbraucherdatenbank.

In diesem Kontext reicht es nicht aus, wenn der Verbraucher dem APPLICATION-Objekt Zugriff auf ein Objekt gewährt, da die App den Namen des Schemas und des Objekts im Verbraucherkonto nicht ermitteln kann.

Damit die Snowflake Native App auf bestehende Objekte außerhalb des APPLICATION-Objekts zugreifen kann, bietet das Snowflake Native App Framework Referenzen, die es dem Kunden ermöglichen, den Namen und das Schema eines Objekts anzugeben und den Zugriff auf das Objekt zu ermöglichen.

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 Benutzeroberfläche zum Anfordern von Berechtigungen und Referenzen erstellen 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

Referenz in der Manifest-Datei definieren

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

references:
- consumer_table:
  label: "Consumer table"
  description: "A table in the consumer account that exists outside the APPLICATION object."
  privileges:
  - INSERT
  - SELECT
  object_type: TABLE
  multi_valued: false
  register_callback: config.register_single_reference
Copy

In diesem Beispiel wird eine Referenz mit dem Namen consumer_table definiert, die die Berechtigungen INSERT und SELECT für eine Tabelle im Verbraucherkonto benötigt. Die Eigenschaft register_callback gibt eine gespeicherte Prozedur an, die verwendet wird, um eine Verbrauchertabelle an diese Referenzdefinition zu binden.

Referenzdefinition entfernen

Bemerkung

Snowflake rät davon ab, in einer neuen Version einer App eine Referenzdefinition aus der Manifest-Datei zu entfernen. Wenn Sie eine definierte Referenz entfernen müssen, aktualisieren Sie jeglichen Code innerhalb einer Versionsfreigabe, der die entfernte Referenz verwendet, und informieren Sie den Verbraucher in der Datei README darüber.

Wenn eine App eine Referenz definiert und später die Referenzdefinition in einer späteren Version der App löscht, führt der Aufruf einer Funktion oder Prozedur, die die gelöschte Referenz noch verwendet, beim Verbraucher zu einem Fehler. Beispiel: Die Manifest-Datei für Version V1 der Anwendung my_app enthält eine Referenzdefinition für REF_TO_TABLE und eine gespeicherte Prozedur CREATE_VIEW_FROM_TABLE, die die Tabellenreferenz REF_TO_TABLE verwendet, um eine Ansicht VIEW_SELECT_FROM_DEFINED_REF zu erstellen.

In Version V2 von my_app wird die Referenzdefinition für REF_TO_TABLE aus der Manifest-Datei entfernt. Wenn ein Verbraucher seine installierte my_app-App auf Version V2 aktualisiert, führt der Aufruf der Prozedur CREATE_VIEW_FROM_TABLE zu folgendem Fehler:

Reference definition '<REF_DEF_NAME>' cannot be found in the current version of the application '<APP_NAME>'

Gespeicherte Callback-Prozedur für eine Referenz erstellen

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 Referenz in der Manifest-Datei definieren 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_REFERENCE(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_REFERENCE(STRING, STRING, STRING)
  TO APPLICATION ROLE app_admin;
Copy

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

Bemerkung

Da die gespeicherte Prozedur die Systemfunktion SYSTEM$SET_REFERENCE verwendet, funktioniert die gespeicherte Prozedur nur für eine Referenz mit einem einzigen Wert in der Beschreibung. Um eine Referenz mit mehreren Werten zu verknüpfen, verwenden Sie die Systemfunktion SYSTEM$ADD_REFERENCE.

Die in einer Anwendung definierten Referenzen anzeigen

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

Objekt an die Anwendung binden

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

SELECT SYSTEM$REFERENCE('table', 'db1.schema1.table1', '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_reference(
  'consumer_table' , 'ADD', SYSTEM$REFERENCE('TABLE', 'db1.schema1.table1', 'PERSISTENT', 'SELECT', 'INSERT'));
Copy

In diesem Beispiel ist consumer_table der Name der in der Datei manifest.yml definierten Referenz. Nachdem der Verbraucher die gespeicherte Prozedur ausgeführt hat, mit der die Referenz verknüpft wird, 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:

Bemerkung

Die reference()-Funktionen in den folgenden Beispielen können nur in einer gespeicherten Prozedur im APPLICATION-Objekt aufgerufen werden.

Abfragen unter Verwendung einer Referenz ausführen

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

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

Gespeicherte Prozedur über eine Referenz aufrufen

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

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

DML-Befehle unter Verwendung einer Referenz ausführen

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

DESCRIBE-Befehl unter Verwendung einer Referenz ausführen

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

DESCRIBE TABLE reference('the_table')
Copy

Referenzen in einer Aufgabe verwenden

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

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

Referenzen in einer Ansichtsdefinition verwenden

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

Referenzen im Textteil (Body) einer Funktion verwenden

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

Referenzen in einer externen Funktion verwenden

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

Referenzen in einer Richtlinie verwenden

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