Referenzen und Berechtigungen auf Objektebene von Verbrauchern anfordern¶

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.

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

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.

Verwenden Sie multi_valued, um mehrere Verbraucherobjekte an dieselbe Referenz zu binden. Wenn diese Eigenschaft angegeben ist, werden die gleichen Operationen an Objekten mit einer einzigen Wertreferenz durchgeführt. Die Eigenschaft kann auch für Objekte mit mehrwertigen Referenzen verwendet werden. Siehe Unterstützte Referenzfunktionen, um mehr über Snowflake Native App Framework-Referenzoperationen zu erfahren.

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, :ref_or_alias);
        WHEN 'CLEAR' THEN
          SELECT SYSTEM$REMOVE_ALL_REFERENCES(: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;

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.

Gespeicherte Callback-Prozedur zum Anfordern der Objektkonfiguration erstellen¶

Für einige Objekttypen muss ein Anbieter dem Setup-Skript eine gespeicherte Prozedur hinzufügen, um zusätzliche Konfigurationen zu ermöglichen. Dieser Callback wird verwendet, wenn Verbraucher Referenzen über Snowsight zulassen.

Das folgende Beispiel zeigt, wie Sie eine gespeicherte Konfigurations-Callback-Prozedur für die unter Referenz in der Manifest-Datei definieren gezeigte Referenz definieren:

CREATE OR REPLACE CONFIG.GET_CONFIGURATION_FOR_REFERENCE(ref_name STRING)
  RETURNS STRING
  LANGUAGE SQL
  AS
  $$
  BEGIN
    CASE (ref_name)
      WHEN 'CONSUMER_EXTERNAL_ACCESS' THEN
        RETURN '{
          "type": "CONFIGURATION",
          "payload":{
            "host_ports":["google.com"],
            "allowed_secrets" : "LIST",
            "secret_references":["CONSUMER_SECRET"]}}';
      WHEN 'CONSUMER_SECRET' THEN
        RETURN '{
          "type": "CONFIGURATION",
          "payload":{
            "type" : "OAUTH2",
            "security_integration": {
              "oauth_scopes": ["https://www.googleapis.com/auth/analytics.readonly"],
              "oauth_token_endpoint": "https://oauth2.googleapis.com/token",
              "oauth_authorization_endpoint":
                "https://accounts.google.com/o/oauth2/auth"}}}';
     END CASE;
     RETURN '';
   END;
   $$;

GRANT USAGE ON PROCEDURE CONFIG.GET_CONFIGURATION_FOR_REFERENCE(STRING)
  TO APPLICATION ROLE app_admin;

In diesem Beispiel wird eine gespeicherte Prozedur mit dem Namen GET_CONFIGURATION_FOR_REFERENCE erstellt, die eine JSON-formatierte Konfiguration zurückgibt, die verwendet wird, um eine Referenz vom Typ EXTERNAL ACCESS INTEGRATION oder SECRET zu erstellen. Die Einträge in der Umschaltanweisung sollten den Referenznamen in der Datei manifest.yml entsprechen.

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;

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');

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'));

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);

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.

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('consumer_table');

SELECT reference('encrypt_func')(t.c1) FROM consumer_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 FUNCTION app.func(x INT)
  RETURNS STRING
  ...
  EXTERNAL_ACCESS_INTEGRATIONS = (reference('consumer_external_access_integration'), ...);
  SECRETS = ('cred1' = reference('consumer_secret'), ...);

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
      );

JSON-Format für die Konfigurations-Callback-Antwort¶

Die Konfigurations-Callback-Funktion gibt eine Antwort im JSON-Format zurück. Das zurückgegebene JSON-Format ist bei Referenzen für die Integration für den externen Zugriff und das Geheimnis unterschiedlich.

{
  "type": "CONFIGURATION",
  "payload": {
    "host_ports": ["host_port_1", ...],
    "allowed_secrets": "NONE|ALL|LIST",
    "secret_references": ["ref_name_1", ...]
  }
}

{
  "type": "CONFIGURATION",
    "payload": {
            "type": "OAUTH2",
            "security_integration": {
                    "oauth_scopes": ["scope_1", "scope_2"],
                    "oauth_token_endpoint" : "token_endpoint",
                    "oauth_authorization_endpoint" : "auth_endpoint"
            }
    }
}

 {
   "type": "ERROR",
   "payload":{
     "message": "The reference is not available for configuration ..."
  }
}

Unterstützte Referenzfunktionen¶

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