Tutoriel : développement d’une application avec le Native Apps Framework

Introduction

Ce tutoriel décrit comment utiliser le Native Apps Framework pour créer une application permettant de partager des données et la logique métier associée avec d’autres comptes Snowflake.

Le tutoriel utilise l’interface Web de Snowsight, mais vous pouvez utiliser n’importe quel client Snowflake qui prend en charge l’exécution de SQL, comme SnowSQL.

Ce que vous apprendrez

Dans ce tutoriel, vous apprendrez à :

  • Créer un paquet d’application qui contient les données et la logique d’entreprise de votre application.

  • Partager des données avec un paquet d’application.

  • Ajouter une logique métier à un paquet d’application.

  • Tester l’application localement.

  • Voir et tester l’application dans Snowsight.

  • Publier votre application en créant une annonce privée.

  • Installer l’application à partir d’une annonce privée.

À propos des fournisseurs et des consommateurs

Dans le contexte du Native Apps Framework, les fournisseurs sont les rôles et les organisations qui disposent de données et d’une logique métier qu’ils souhaitent partager avec d’autres utilisateurs de Snowflake, qui sont les consommateurs. Un consommateur peut être un autre compte au sein de votre organisation, une organisation différente au sein de votre entreprise ou un utilisateur de Snowflake dans une autre entreprise.

Dans le cadre de ce tutoriel, la plupart des tâches que vous allez effectuer sont celles généralement réalisées par des fournisseurs, mais elles incluent des tâches qui peuvent être réalisées par plusieurs rôles au sein de votre organisation, notamment les développeurs d’applications et les administrateurs de bases de données.

Dans ce tutoriel, vous effectuerez également des tâches qui imitent les actions réalisées par les consommateurs pour installer une application.

Conditions préalables

  • Vous devez exécuter toutes les commandes SQL dans la même session de commande SQL, car le contexte de la session est nécessaire.

    Pour ce faire dans Snowsight, par exemple, collez tout votre code dans la même feuille de calcul au fur et à mesure. Au fur et à mesure que vous progressez, chaque section s’appuie sur la précédente.

  • Vous devez être en mesure d’utiliser le rôle ACCOUNTADMIN.

    Dans ce tutoriel, vous effectuerez toutes les étapes en utilisant le rôle ACCOUNTADMIN. En règle générale, cependant, vous utiliserez des rôles dont les privilèges sont spécifiquement définis pour l’action que vous effectuez. Par exemple, vous pouvez avoir des rôles distincts pour les développeurs qui créent des UDFs et des procédures stockées, pour les administrateurs de base de données qui gèrent les rôles et les autorisations, et pour les administrateurs qui gèrent les annonces à l’aide de la collaboration Snowflake.

  • Pour installer votre application à partir d’une annonce privée, vous devez avoir accès à un deuxième compte Snowflake. Vous utiliserez ce compte pour imiter la façon dont les consommateurs installeraient une application.

    Note

    Bien que le Native Apps Framework prenne en charge le partage d’applications avec des comptes appartenant à des organisations différentes, pour les besoins de ce tutoriel, les deux comptes doivent appartenir à la même organisation.

  • Vous devez définir un entrepôt courant avant d’effectuer le tutoriel. Un entrepôt virtuel doit être spécifié pour une session et l’entrepôt virtuel doit être en cours d’exécution avant que les instructions et d’autres requêtes DML puissent être exécutées au cours de la session. Reportez-vous à USE WAREHOUSE pour plus de détails.

Créer les fichiers de l’application

Dans cette section, vous allez créer un script d’installation et un fichier manifeste. Ces deux fichiers sont requis par le Native Apps Framework.

Script d’installation

Script SQL qui s’exécute automatiquement lorsqu’un consommateur installe une application dans son compte.

Fichier manifeste

Fichier YAML qui contient des informations de configuration de base sur l’application.

Vous en apprendrez plus sur ces deux fichiers et leur contenu tout au long de ce tutoriel. Vous créerez également un fichier Lisez-moi qui vous sera utile lors de l’affichage et de la publication de votre application dans les sections ultérieures de ce tutoriel.

Créer le script d’installation

Pour créer le script d’installation, procédez comme suit :

  1. Sur votre système de fichiers local, créez un dossier nommé tutorial. Il s’agit du répertoire racine pour les fichiers externes de votre application.

    Note

    Vous ajouterez d’autres fichiers et sous-dossiers à ce dossier dans les sections suivantes.

  2. Dans le dossier tutorial , créez un sous-dossier nommé scripts.

  3. Dans ce dossier, créez un nouveau fichier nommé setup.sql.

    Note

    Ce tutoriel fera référence à cette structure et à ce nom de fichier pour le script d’installation. Cependant, lorsque vous créez votre propre application, vous pouvez choisir votre propre nom et votre propre structure de répertoire pour ce fichier.

  4. Ajoutez l’instruction SQL suivante à ce fichier :

    -- Setup script for the Hello Snowflake! application.
    
    Copy

Vous ajoutez cette ligne en tant qu’espace réservé, car le script d’installation ne peut pas être vide.

Créer un fichier README pour votre application

Un fichier Lisez-moi fournit une description de ce que fait votre application. Vous verrez le fichier Lisez-moi lorsque vous verrez votre application dans Snowsight.

Pour créer le fichier readme.md de votre application :

  1. Dans le dossier tutorial , créez un fichier nommé readme.md.

  2. Ajoutez le contenu suivant à ce fichier :

    This is the readme file for the Hello Snowflake Application!
    
    Copy

Créer le fichier manifeste

Le Native Apps Framework requiert un fichier manifeste pour chaque application. Le fichier manifeste contient les métadonnées et les paramètres de configuration d’une application.

Pour créer le fichier manifeste :

  1. Dans le dossier tutorial , créez un fichier nommé manifest.yml.

    Note

    Ce fichier doit être nommé manifest.yml et doit se trouver à la racine de votre projet. Les chemins vers d’autres fichiers, y compris le script d’installation, sont relatifs à l’emplacement de ce fichier.

  2. Ajoutez le contenu suivant à ce fichier :

    manifest_version: 1
    artifacts:
      setup_script: scripts/setup.sql
      readme: readme.md
    
    Copy

    La propriété setup_script spécifie l’emplacement du script d’installation par rapport à l’emplacement du fichier manifeste. Le chemin et le nom de fichier spécifiés ici doivent être identiques à l’emplacement du script d’installation que vous avez créé ci-dessus.

    Note

    Les propriétés manifest_version, artifacts, et setup_script sont obligatoires. La valeur readme est facultative.

Passez en revue ce que vous avez appris dans cette section

Après avoir effectué les étapes décrites dans cette section, vous devriez avoir une structure de répertoire qui ressemble à ce qui suit :

/tutorial
  manifest.yml
  readme.md
  /scripts/
    setup.sql
Copy

Dans cette section, vous avez appris à créer le script d’installation et les fichiers manifestes requis par le Native Apps Framework. Bien que le contenu que vous avez ajouté à ces deux fichiers soit basique, toutes les applications doivent disposer de ces fichiers.

Vous avez également ajouté un fichier Lisez-moi qui s’affiche lors de l’affichage de votre application dans Snowsight ou lors de la publication de votre application sous forme d’annonce.

Créer un paquet d’application

Dans cette section, vous allez créer un paquet d’application qui servira de conteneur pour les ressources nécessaires à votre application. Vous effectuerez les tâches suivantes :

  • Créer un paquet d’application.

  • Créer une zone de préparation nommée dans le paquet d’application.

Créer un paquet d’application

À la base, un dossier d’application est une base de données Snowflake qui est étendue pour inclure des informations supplémentaires sur une application. En ce sens, il s’agit d’un conteneur pour une application qui comprend :

  • Partage de contenu de données

  • Fichiers d’application

Pour créer un paquet d’application :

  1. Pour attribuer le privilège CREATE APPLICATION PACKAGE à votre rôle, exécutez la commande suivante :

    GRANT CREATE APPLICATION PACKAGE ON ACCOUNT TO ROLE accountadmin;
    
    Copy

    Note

    Bien que le rôle ACCOUNTADMIN dispose de ce privilège par défaut, pour pouvoir créer un paquet d’application, vous devez vous assurer que votre rôle s’est vu attribuer ce privilège.

  2. Pour créer le paquet d’application, exécutez la commande suivante :

    CREATE APPLICATION PACKAGE hello_snowflake_package;
    
    Copy

    Note

    Après l’exécution de cette commande, le contexte actuel devient HELLO_SNOWFLAKE_PACKAGE.

  3. Pour vérifier que le paquet d’application a été créé avec succès, exécutez la commande suivante :

    SHOW APPLICATION PACKAGES;
    
    Copy

    Vous devriez voir HELLO_SNOWFLAKE_PACKAGE dans la colonne name de la sortie. Reportez-vous à SHOW APPLICATION PACKAGES pour de plus amples informations sur cette commande.

Dans cette section, vous avez appris qu’un paquet d’application est un conteneur pour les ressources utilisées par une application. Vous avez également appris à créer un paquet d’application.

Créer une zone de préparation nommée

Dans cette section, vous allez créer une zone de préparation nommée pour stocker les fichiers requis par le Native Apps Framework. Une zone de préparation nommée est également nécessaire pour stocker les fichiers de code externe que vous souhaitez inclure dans votre application. Le chargement en zone de préparation de ces fichiers les rend disponibles lors de la création de votre application.

Pour créer une zone de préparation externe nommée, procédez comme suit :

  1. Pour définir le contexte sur le paquet d’application que vous avez créé dans la section précédente, exécutez la commande suivante :

    USE APPLICATION PACKAGE hello_snowflake_package;
    
    Copy
  2. Pour créer le schéma requis pour la zone de préparation nommée, exécutez la commande suivante :

    CREATE SCHEMA stage_content;
    
    Copy
  3. Pour créer la zone de préparation nommée, exécutez la commande suivante.

    CREATE OR REPLACE STAGE hello_snowflake_package.stage_content.hello_snowflake_stage
      FILE_FORMAT = (TYPE = 'csv' FIELD_DELIMITER = '|' SKIP_HEADER = 1);
    
    Copy

    Cette commande crée la zone de préparation nommée dans la base de données et le schéma que vous avez créés dans les étapes précédentes.

    Note

    Vous devez inclure FILE_FORMAT = (TYPE = 'CSV' FIELD_DELIMITER = '|' SKIP_HEADER = 1); dans cette commande. Ceux-ci ne sont pas facultatifs.

Vous disposez à présent d’une zone de préparation nommée dans le paquet d’application où vous pouvez charger les fichiers que vous utiliserez pour développer votre application.

Note

Bien que ce tutoriel utilise une zone de préparation nommée dans le paquet d’application, ce n’est pas une obligation. Vous pouvez également utiliser une zone de préparation nommée qui existe dans une base de données et un schéma extérieurs au paquet d’application.

Charger les fichiers d’application vers une zone de préparation nommée

Dans la section précédente, vous avez créé un paquet d’application qui servira de conteneur pour votre application. Vous avez également créé une zone de préparation nommée dans le paquet d’application qui contient les fichiers d’application requis.

Dans cette section, vous allez charger ces fichiers vers la zone de préparation nommée.

Pour charger des fichiers d’application, procédez de l’une des manières suivantes :

  • Chargez les fichiers d’application à l’aide de Snowsight comme décrit dans la section Mise des fichiers en zone de préparation à l’aide de Snowsight

  • Chargez les fichiers d’application à l’aide de SnowSQL en exécutant les commandes suivantes :

    PUT file:///<path_to_your_root_folder>/tutorial/manifest.yml @hello_snowflake_package.stage_content.hello_snowflake_stage overwrite=true auto_compress=false;
    PUT file:///<path_to_your_root_folder>/tutorial/scripts/setup.sql @hello_snowflake_package.stage_content.hello_snowflake_stage/scripts overwrite=true auto_compress=false;
    PUT file:///<path_to_your_root_folder>/tutorial/readme.md @hello_snowflake_package.stage_content.hello_snowflake_stage overwrite=true auto_compress=false;
    
    Copy

    Note

    Modifiez le chemin dans les exemples ci-dessus pour refléter le chemin du dossier racine de votre projet.

Dans votre feuille de calcul, exécutez la commande suivante pour vérifier que le chargement du fichier a réussi :

LIST @hello_snowflake_package.stage_content.hello_snowflake_stage;
Copy

Après avoir exécuté cette commande, vous devriez voir chacun des fichiers répertorié comme indiqué dans la sortie suivante :

+----------------------------------------+------+----------------------------------+-------------------------------+
| name                                   | size | md5                              | last_modified                 |
|----------------------------------------+------+----------------------------------+-------------------------------|
| hello_snowflake_stage/manifest.yml      |   80 | 9acab2ba718eebfa5f98f4e95c822db6 | Mon, 29 May 2023 22:51:04 GMT |
| hello_snowflake_stage/readme.md         |   64 | 1bc95f95109dc60a09b478dd95c31808 | Mon, 29 May 2023 22:51:05 GMT |
| hello_snowflake_stage/scripts/setup.sql |   64 | 7807ee1f2f27312799fc83c66ba775cf | Mon, 29 May 2023 22:51:04 GMT |
+----------------------------------------+------+----------------------------------+-------------------------------+
Copy

Dans cette section, vous avez chargé vers une zone de préparation les fichiers d’application. Ces fichiers sont maintenant disponibles pour le paquet d’application au fur et à mesure que vous continuez à développer votre application. Dans les sections suivantes, lorsque vous ajouterez des fonctions à votre application, vous reviendrez à cette section pour charger des versions révisées de ces fichiers et de nouveaux fichiers.

Ajouter la logique de l’application et installer votre première application

Dans cette section, vous allez ajouter du code et installer votre première application. Pour ce faire, vous effectuerez les tâches suivantes :

  • Ajoutez une procédure stockée au script d’installation.

  • Ajoutez une version à l’application.

  • Installez et testez l’application.

Ajouter une procédure stockée au script d’installation

Dans la section précédente, vous avez créé un paquet d’application. Toutefois, le paquet d’application ne contient pas encore de contenu de données ni de fichiers de données.

Dans cette section, vous allez ajouter une procédure stockée à l’application en ajoutant le code de la procédure stockée au script d’installation sur votre système de fichiers local.

Pour ajouter une procédure stockée au script d’installation :

  1. Ajoutez les instructions SQL suivantes à la fin du fichier setup.sql que vous avez créé dans une section précédente :

    CREATE APPLICATION ROLE app_public;
    CREATE SCHEMA IF NOT EXISTS core;
    GRANT USAGE ON SCHEMA core TO APPLICATION ROLE app_public;
    
    Copy

    Lorsque le script d’installation est exécuté pendant l’installation, ces instructions créent un rôle d’application nommé app_public. Les rôles d’application sont similaires aux rôles de base de données, mais ils ne peuvent être utilisés que dans le contexte d’une application. Ils sont utilisés pour accorder l’accès à des objets au sein de l’application.

    Cet exemple crée également un schéma pour contenir la procédure stockée et accorde le privilège USAGE sur le schéma au rôle d’application. La création d’un rôle d’application et l’attribution de privilèges sur un objet, par exemple un schéma, au rôle d’application sont un schéma courant dans le script d’installation.

  2. Ajoutez le code de la procédure stockée à la fin du fichier setup.sql :

    CREATE OR REPLACE PROCEDURE CORE.HELLO()
      RETURNS STRING
      LANGUAGE SQL
      EXECUTE AS OWNER
      AS
      BEGIN
        RETURN 'Hello Snowflake!';
      END;
    
    Copy

    Cet exemple crée une procédure stockée qui produit la chaîne « Hello Snowflake ! ».

  3. Ajoutez l’instruction suivante à la fin du fichier setup.sql :

    GRANT USAGE ON PROCEDURE core.hello() TO APPLICATION ROLE app_public;
    
    Copy

    Cet exemple attribue au rôle d’application le privilège USAGE sur la procédure stockée.

  4. Chargez le script d’installation révisé dans la zone de préparation nommée.

    Reportez-vous à la section précédente Charger les fichiers d’application vers une zone de préparation nommée pour charger le script d’installation révisé, puis revenez ici pour poursuivre le tutoriel.

Dans cette section, vous avez ajouté une procédure stockée au script d’installation. Vous avez également créé un rôle d’application et attribué des privilèges USAGE à ce rôle. Cela permet au script d’installation de créer la procédure stockée lors de la création de l’application. Il autorise également l’application à exécuter la procédure stockée.

Installer l’application

Dans la section précédente, vous avez modifié le script d’installation pour y inclure une procédure stockée.

Dans cette section, vous installerez l’application et exécuterez la procédure stockée à l’aide de Snowsight.

Pour installer une application, procédez comme suit :

  1. Pour créer l’application, exécutez la commande suivante :

    CREATE APPLICATION HELLO_SNOWFLAKE_APP
      FROM APPLICATION PACKAGE HELLO_SNOWFLAKE_PACKAGE
      USING '@hello_snowflake_package.stage_content.hello_snowflake_stage';
    
    Copy
  2. Pour vérifier que l’application a été créée avec succès, exécutez la commande suivante :

    SHOW APPLICATIONS;
    
    Copy

    Vous devriez voir HELLO_SNOWFLAKE_APP apparaître dans la colonne name du résultat.

  3. Pour exécuter la procédure stockée HELLO que vous avez ajoutée à setup.sql dans une section précédente, exécutez la commande suivante :

    CALL core.hello();
    
    Copy

    Regardez la sortie suivante après avoir exécuté cette commande :

    +------------------+
    | HELLO            |
    |------------------|
    | HELLO SNOWFLAKE! |
    +------------------+
    
    Copy

Passez en revue ce que vous avez appris dans cette section

Félicitations ! Vous avez créé, installé et testé votre première application en utilisant le Native Apps Framework ! Bien que l’application n’ait qu’une fonctionnalité de base, les composants que vous avez utilisés pour développer l’application sont les mêmes pour des applications plus complexes.

Dans cette section, vous avez complété les éléments suivants :

  • Ajout d’une procédure stockée au script d’installation. Le script d’installation spécifie comment votre application est installée dans le compte consommateur. Dans les sections suivantes, vous ajouterez du contenu de données et d’autres types de logique d’application à votre application.

  • Installez et testez votre application en exécutant la procédure stockée. Dans les sections suivantes, vous découvrirez d’autres façons d’afficher et de tester votre application.

Ajouter du contenu de données à votre application

Dans la section précédente, vous avez créé une application contenant une procédure stockée qui montre comment vous pouvez ajouter une logique d’application à une application.

Dans cette section, vous allez inclure du contenu de données dans votre application en créant une base de données dans le paquet d’application HELLO_SNOWFLAKE_PACAKAGE et en accordant des privilèges pour partager cette base de données avec l’application.

Créer une base de données à partager avec une application

Dans cette section, vous apprendrez à partager des données avec une application. Plus précisément, vous partagerez une table dans le paquet d’application avec.

Pour créer une table et insérer les données d’exemple dans le paquet d’application :

  1. Pour définir le contexte sur le paquet d’application, exécutez la commande suivante :

    USE APPLICATION PACKAGE hello_snowflake_package;
    
    Copy
  2. Pour créer une table et ajouter le contenu des données partagées, exécutez les commandes suivantes :

    CREATE SCHEMA IF NOT EXISTS shared_data;
    CREATE TABLE IF NOT EXISTS accounts (ID INT, NAME VARCHAR, VALUE VARCHAR);
    INSERT INTO accounts VALUES
      (1, 'Nihar', 'Snowflake'),
      (2, 'Frank', 'Snowflake'),
      (3, 'Benoit', 'Snowflake'),
      (4, 'Steven', 'Acme');
    
    Copy
  3. Pour vérifier que le contenu des données a été correctement inséré dans la table, exécutez la commande suivante :

    SELECT * FROM accounts;
    
    Copy

    Dans le résultat de cette commande, vous devriez voir trois colonnes nommées ID, NAME, et VALUE. Vous devriez également voir les données pour chaque ligne, comme le montre l’exemple de sortie suivant :

    +----+----------+-----------+
    | ID | NAME     | VALUE     |
    |----+----------+-----------|
    |  1 | Nihar    | Snowflake |
    |  2 | Frank    | Snowflake |
    |  3 | Benoit   | Snowflake |
    |  4 | Steven   | Acme      |
    +----+----------+-----------+
    
    Copy
  4. Pour autoriser l’utilisation de la table ACCOUNTS exécutez les commandes suivantes :

    GRANT USAGE ON SCHEMA shared_data TO SHARE IN APPLICATION PACKAGE hello_snowflake_package;
    GRANT SELECT ON TABLE accounts TO SHARE IN APPLICATION PACKAGE hello_snowflake_package;
    
    Copy

    L’attribution de ces privilèges sur les objets du paquet d’application met la table accounts à la disposition de toutes les applications installées à partir du paquet d’application.

    Note

    Vous devez accorder le privilège USAGE à chaque objet d’un paquet d’application que vous souhaitez partager avec un consommateur dans une application.

Ajouter une vue pour accéder au contenu des données

Dans cette section, vous allez mettre à jour le script d’installation pour ajouter une vue qui permet à l’application d’accéder aux données de la table ACCOUNTS que vous avez créée dans la sous-section précédente.

Pour ajouter une vue permettant d’accéder au contenu des données :

  1. Pour créer un schéma pour la vue, ajoutez ce qui suit au script d’installation :

    CREATE OR ALTER VERSIONED SCHEMA code_schema;
    GRANT USAGE ON SCHEMA code_schema TO APPLICATION ROLE app_public;
    
    Copy

    Ces instructions créent un schéma versionné pour contenir la vue et attribuent le privilège USAGE sur le schéma. Le Native Apps Framework utilise un schéma versionné pour gérer les différentes versions des procédures et fonctions stockées.

  2. Pour créer la vue, ajoutez ce qui suit au script d’installation :

    CREATE VIEW IF NOT EXISTS code_schema.accounts_view
      AS SELECT ID, NAME, VALUE
      FROM shared_data.accounts;
    GRANT SELECT ON VIEW code_schema.accounts_view TO APPLICATION ROLE app_public;
    
    Copy

    Ces instructions créent la vue dans le schéma code_schema et accordent le privilège requis sur la vue au rôle d’application.

  3. Chargez le script d’installation révisé dans la zone de préparation nommée.

    Reportez-vous à la section précédente Charger les fichiers d’application vers une zone de préparation nommée pour charger les fichiers que vous avez mis à jour dans cette section, puis revenez ici pour poursuivre le tutoriel.

Tester l’application mise à jour

Dans cette sous-section, vous réinstallerez l’application et interrogerez la table d’exemple à l’aide de la vue au sein de l’application installée.

Pour tester l’application mise à jour, procédez comme suit :

  1. Pour supprimer l’application existante, exécutez la commande suivante :

    DROP APPLICATION hello_snowflake_app;
    
    Copy
  2. Pour créer une nouvelle version de l’application, exécutez les commandes suivantes :

    CREATE APPLICATION hello_snowflake_app
      FROM APPLICATION PACKAGE hello_snowflake_package
      USING '@hello_snowflake_package.stage_content.hello_snowflake_stage';
    
    Copy
  3. Pour vérifier que la vue fonctionne correctement, exécutez la commande suivante :

    SELECT * FROM code_schema.accounts_view;
    
    Copy

    La sortie de cette commande est identique à la commande SELECT que vous avez exécutée lors de la mise en place des données d’exemple :

    +----+----------+-----------+
    | ID | NAME     | VALUE     |
    |----+----------+-----------|
    |  1 | Nihar    | Snowflake |
    |  2 | Frank    | Snowflake |
    |  3 | Benoit   | Snowflake |
    |  4 | Steven   | Acme      |
    +----+----------+-----------+
    
    Copy

Passez en revue ce que vous avez appris dans cette section

Dans cette section, vous avez appris à inclure du contenu de données partagées dans votre application en effectuant les tâches suivantes :

  • Créer la table ACCOUNTS dans le paquet d’application et insérer des données dans la table.

  • Attribuer au paquet d’application l’utilisation de la référence sur la table ACCOUNTS.

  • Créer un schéma et une vue qui font référence à la table ACCOUNTS dans le paquet d’application.

  • Accorder l’utilisation du schéma au rôle d’application.

  • Accorder la sélection de la vue au rôle d’application.

Vous avez également mis à jour le script d’installation pour effectuer les opérations suivantes lors de l’installation de l’application :

  • Créer un schéma et une vue que l’application utilise pour accéder aux données d’exemple.

  • Accorder l’utilisation du schéma au rôle d’application.

  • Accorder la sélection de la vue au rôle d’application.

Notez que les commandes que vous avez exécutées pour configurer la base de données HELLO_SNOWFLAKE_DATA ont des parallèles dans le script d’installation.

Ajouter du code Python à votre application

Dans cette section, vous allez étendre la fonctionnalité de votre application en ajoutant du code Python pour améliorer la logique de l’application. Dans cette section, vous inclurez le code Python suivant :

  • Une UDF Python en ligne qui est une fonction autonome dans le script d’installation.

  • Une UDF Python qui fait référence à un fichier Python en dehors du script d’installation.

Note

Bien que cette section présente des exemples utilisant Python, les mêmes techniques sont applicables à Java et JavaScript.

Ajouter une fonction Python en ligne en tant que fonction définie par l’utilisateur (UDF)

Dans cette section, vous ajouterez une fonction Python en tant qu’UDF.

Pour inclure une UDF Python dans votre application, ajoutez le code suivant à votre fichier d’installation.

CREATE OR REPLACE FUNCTION code_schema.addone(i int)
RETURNS INT
LANGUAGE PYTHON
RUNTIME_VERSION = '3.8'
HANDLER = 'addone_py'
AS
$$
def addone_py(i):
  return i+1
$$;

GRANT USAGE ON FUNCTION code_schema.addone(int) TO APPLICATION ROLE app_public;
Copy

Ces commandes exécutent les tâches suivantes lors de l’installation de l’application :

  • Créez un schéma versionné nommé code_schema.

  • Accordez le privilège d’utilisation du schéma au rôle d’application APP_PUBLIC.

  • Créez l’UDF ADDONE() dans le schéma code_schema.

  • Accordez le privilège d’utilisation de la fonction au rôle d’application APP_PUBLIC.

Notez que le schéma créé dans l’exemple de code ci-dessus est un schéma versionné. Les fonctions définies par l’utilisateur et les procédures stockées doivent être définies dans un schéma versionné au lieu d’un schéma normal.

Ajouter un module Python externe

Pour ajouter un module python externe à votre application :

  1. Ajoutez la fonction Python suivante à votre script d’installation :

    CREATE or REPLACE FUNCTION code_schema.multiply(num1 float, num2 float)
      RETURNS float
      LANGUAGE PYTHON
      RUNTIME_VERSION=3.8
      IMPORTS = ('/python/hello_python.py')
      HANDLER='hello_python.multiply';
    
    GRANT USAGE ON FUNCTION code_schema.multiply(FLOAT, FLOAT) TO APPLICATION ROLE app_public;
    
    Copy

    Comme dans l’exemple précédent, ces instructions créent une UDF Python dans un schéma et attribuent des privilèges sur la fonction au rôle d’application. Cependant, cet exemple contient une clause IMPORTS qui fait référence à un fichier Python externe que vous allez créer.

  2. Dans le dossier tutorial , créez un sous-dossier nommé python.

  3. Dans le sous-dossier python , créez un fichier nommé hello_python.py.

  4. Ajoutez ce qui suit au fichier hello_python.py :

    def multiply(num1, num2):
      return num1*num2
    
    Copy

    La fonction définie dans ce fichier externe correspond à la fonction en ligne définie dans le script d’installation.

Dans cette section, vous avez ajouté une UDF Python à votre application. Cette UDF fait référence à un module Python externe qui peut être référencé par votre paquet d’application.

Installer et tester l’application mise à jour

  1. Chargez les fichiers nouveaux et révisés dans la zone de préparation nommée.

    Reportez-vous à la section Charger les fichiers d’application vers une zone de préparation nommée pour charger le fichier Python externe, puis revenez ici pour continuer le tutoriel.

    Si vous utilisez SnowSQL pour charger le fichier, exécutez les commandes suivantes :

    PUT file:///<path_to_your_root_folder>/tutorial/scripts/setup.sql @hello_snowflake_package.stage_content.hello_snowflake_stage/scripts overwrite=true auto_compress=false;
    PUT file:///<path_to_your_root_folder>/tutorial/python/hello_python.py @hello_snowflake_package.stage_content.hello_snowflake_stage/python overwrite=true auto_compress=false;
    
    Copy
  2. Pour supprimer l’application existante, exécutez la commande suivante :

    DROP APPLICATION hello_snowflake_app;
    
    Copy
  3. Pour créer une nouvelle version de l’application, exécutez les commandes suivantes :

    CREATE APPLICATION hello_snowflake_app
      FROM APPLICATION PACKAGE hello_snowflake_package
      USING '@hello_snowflake_package.stage_content.hello_snowflake_stage';
    
    Copy
  4. Pour tester la procédure stockée Python, exécutez la commande suivante :

    SELECT code_schema.addone(1);
    
    Copy
  5. Pour tester la fonction Python référencée, exécutez la commande suivante :

    SELECT code_schema.multiply(1,2);
    
    Copy

Passez en revue ce que vous avez appris dans cette section

Dans cette section, vous avez ajouté les nouvelles fonctionnalités suivantes à votre application :

  • Une fonction Python définie comme une UDF ligne.

  • Une fonction Python définie comme une UDF qui fait référence à du code externe.

Vous avez également testé chacun de ces exemples en installant une version mise à jour de votre application et en exécutant chacune des fonctions.

Ajouter une application Streamlit à votre application

Dans cette section, vous compléterez votre application en ajoutant une application Streamlit. Streamlit est un framework Python libre, utilisé pour le développement d’applications de science des données et de machine learning. Vous pouvez inclure des applications Streamlit au sein d’une application native pour ajouter de l’interaction avec l’utilisateur et de la visualisation de données.

Créer le fichier d’application Streamlit

Pour créer une application Streamlit, procédez comme suit :

  1. Dans le dossier tutorial , créez un sous-dossier nommé streamlit.

  2. Dans le dossier streamlit , créez un fichier nommé hello_snowflake.py.

  3. Ajoutez le code suivant à ce fichier :

    # Import python packages
    import streamlit as st
    from snowflake.snowpark.context import get_active_session
    
    # Write directly to the app
    st.title("Hello Snowflake - Streamlit Edition")
    st.write(
       """The following data is from the accounts table in the application package.
          However, the Streamlit app queries this data from a view called
          code_schema.accounts_view.
       """
    )
    
    # Get the current credentials
    session = get_active_session()
    
    #  Create an example data frame
    data_frame = session.sql("SELECT * FROM code_schema.accounts_view;")
    
    # Execute the query and convert it into a Pandas data frame
    queried_data = data_frame.to_pandas()
    
    # Display the Pandas data frame as a Streamlit data frame.
    st.dataframe(queried_data, use_container_width=True)
    
    Copy

Ajouter l’objet Streamlit au script d’installation

Pour créer l’objet Streamlit dans l’application, procédez comme suit :

  1. Ajoutez l’instruction suivante à la fin du fichier setup.sql pour créer l’objet Streamlit :

    CREATE STREAMLIT code_schema.hello_snowflake_streamlit
      FROM '/streamlit'
      MAIN_FILE = '/hello_snowflake.py'
    ;
    
    Copy

    Cette instruction crée un objet STREAMLIT dans le schéma principal.

  2. Ajoutez l’instruction suivante à la fin du fichier setup.sql pour permettre au rôle APP_PUBLIC d’accéder à l’objet Streamlit :

    GRANT USAGE ON STREAMLIT code_schema.hello_snowflake_streamlit TO APPLICATION ROLE app_public;
    
    Copy
  3. Chargez les nouveaux fichiers d’application et ceux qui ont été mis à jour dans la zone de préparation nommée :

    Reportez-vous à la section précédente Charger les fichiers d’application vers une zone de préparation nommée pour charger le fichier Streamlit que vous venez de créer, puis revenez ici pour poursuivre le tutoriel.

    Si vous utilisez SnowSQL pour charger le fichier, exécutez la commande suivante :

    PUT file:///<path_to_your_root_folder>/tutorial/scripts/setup.sql @hello_snowflake_package.stage_content.hello_snowflake_stage/scripts overwrite=true auto_compress=false;
    PUT file:///<path_to_your_root_folder>/tutorial/streamlit/hello_snowflake.py @hello_snowflake_package.stage_content.hello_snowflake_stage/streamlit overwrite=true auto_compress=false;
    
    Copy

Installer l’application mise à jour

  1. Chargez le script d’installation révisé dans la zone de préparation nommée.

    Reportez-vous à la section précédente Charger les fichiers d’application vers une zone de préparation nommée pour charger le script d’installation révisé, puis revenez ici pour poursuivre le tutoriel.

  2. Pour supprimer l’application précédente, exécutez la commande suivante :

    DROP APPLICATION hello_snowflake_app;
    
    Copy
  3. Pour créer une nouvelle version de l’application, exécutez la commande suivante :

    CREATE APPLICATION hello_snowflake_app
      FROM APPLICATION PACKAGE hello_snowflake_package
      USING '@hello_snowflake_package.stage_content.hello_snowflake_stage';
    
    Copy

Passez en revue ce que vous avez appris dans cette section

Dans cette section, vous avez ajouté une application Streamlit à votre application en procédant comme suit :

  • Créez une application Streamlit.

Ajouter une version à votre application

Dans cette section, vous ajouterez une version à votre application qui comprendra toutes les fonctionnalités que vous avez ajoutées dans ce tutoriel. Pour ce faire, vous utiliserez la commande ALTER APPLICATION PACKAGE pour mettre à jour le paquet d’application que vous avez créé précédemment.

Pour ajouter une version à votre application :

  1. Pour ajouter une version au paquet d’application HELLO_SNOWFLAKE_PACKAGE , exécutez la commande suivante :

    ALTER APPLICATION PACKAGE hello_snowflake_package
      ADD VERSION v1_0 USING '@hello_snowflake_package.stage_content.hello_snowflake_stage';
    
    Copy

    Dans cette commande, vous avez modifié votre paquet d’application pour ajouter une version basée sur les fichiers d’application que vous avez chargés dans la zone de préparation nommée dans une section précédente.

    Note

    La valeur spécifiée pour VERSION est une balise, et non une valeur numérique ou une chaîne. Reportez-vous à ALTER APPLICATION PACKAGE pour plus d’informations.

    Note

    Le numéro de correctif de la nouvelle version que vous avez ajoutée est automatiquement créé à l’adresse 0. Au fur et à mesure que vous ajoutez des correctifs supplémentaires pour une version, ceux-ci sont automatiquement incrémentés. Toutefois, lorsque vous créez une nouvelle version, par exemple V1_1, le numéro de correctif de cette version est réinitialisé à 0.

  2. Pour vérifier que la version a été ajoutée au paquet de l’application, exécutez la commande suivante :

    SHOW VERSIONS IN APPLICATION PACKAGE hello_snowflake_package;
    
    Copy

    Cette commande affiche des informations supplémentaires sur la version, comme le montre la sortie suivante :

    +---------+-------+-------+---------+-------------------------------+------------+-----------+-------------+-------+---------------+
    | version | patch | label | comment | created_on                    | dropped_on | log_level | trace_level | state | review_status |
    |---------+-------+-------+---------+-------------------------------+------------+-----------+-------------+-------+---------------|
    | V1_0    |     0 | NULL  | NULL    | 2023-05-30 10:33:39.768 -0700 | NULL       | OFF       | OFF         | READY | NOT_REVIEWED  |
    +---------+-------+-------+---------+-------------------------------+------------+-----------+-------------+-------+---------------+
    
    Copy

    Reportez-vous à SHOW VERSIONS pour plus d’informations.

  3. Pour installer l’application en fonction d’une version, exécutez la commande suivante :

    DROP APPLICATION hello_snowflake_app;
    CREATE APPLICATION hello_snowflake_app
      FROM APPLICATION PACKAGE hello_snowflake_package
      USING VERSION V1_0;
    
    Copy

Dans cette section, vous avez modifié le paquet d’application pour y inclure une version de votre application.

Voir votre application dans Snowsight

Dans cette section, vous verrez votre application dans Snowsight. Dans les sections précédentes, vous avez utilisé des instructions SQL pour tester ou trouver des informations sur votre application. Toutefois, vous pouvez également consulter les informations relatives à votre application dans Snowsight. Vous pouvez également voir votre application Streamlit déployée.

Pour voir votre application dans Snowsight, procédez comme suit :

  1. Connectez-vous à Snowsight.

  2. Passez au rôle ACCOUNTADMIN.

  3. Sélectionnez Data Products » Apps.

  4. Sélectionnez HELLO_SNOWFLAKE_APP.

    L’onglet Read Me affiche le contenu que vous avez ajouté au fichier readme.md dans une section précédente.

  5. Pour voir votre application Streamlit, sélectionnez HELLOSNOWFLAKE_STREAMLIT.

    Le contenu de la base de données HELLO_SNOWFLAKE_DATA s’affiche dans un cadre de données Streamlit.

  6. Sélectionnez Projects » Worksheets pour ouvrir l’application dans une feuille de calcul Snowflake.

  7. Sélectionnez HELLO_SNOWFLAKE_APP, puis choisissez un schéma dans la liste.

    La liste des schémas correspond au schéma que vous avez ajouté à votre application pendant le tutoriel.

À partir de la feuille de calcul Snowflake, vous pouvez tester votre application à l’aide de commandes SQL. Par exemple, vous pouvez réexécuter les commandes que vous avez exécutées dans les sections précédentes pour tester les fonctions que vous avez ajoutées à votre application :

LIST @hello_snowflake_package.stage_content.hello_snowflake_stage;
CALL core.hello();
SELECT * FROM code_schema.accounts_view;
SELECT code_schema.addone(10);
SELECT code_schema.multiply(2,3);
Copy

Note

Toutes les instructions SQL que vous ajoutez à cette feuille de calcul sont perdues lorsque vous naviguez vers une autre page de Snowsight.

Publier et installer votre application

Dans cette section, vous allez publier votre application en créant une annonce privée qui utilise le paquet d’application comme contenu de données. Après avoir créé l’annonce, vous vous connecterez à un autre compte pour installer l’annonce.

Définir la directive de version par défaut

Avant de pouvoir créer une annonce pour votre paquet d’application, vous devez définir une directive de version. Une directive de version spécifie quelle version de votre application est disponible pour les consommateurs.

Dans ce tutoriel, vous allez définir la directive de version par défaut en utilisant la version que vous avez ajoutée dans une section précédente.

Pour définir la directive de version par défaut pour votre paquet d’application, procédez comme suit :

  1. Pour voir les versions et les correctifs définis pour votre paquet d’application, exécutez la commande suivante :

    SHOW VERSIONS IN APPLICATION PACKAGE hello_snowflake_package;
    
    Copy

    Cette commande affiche les versions et les correctifs définis pour le paquet d’application.

  2. Pour définir la directive de version par défaut sur la version v1_0 et le correctif 0, exécutez la commande suivante :

    ALTER APPLICATION PACKAGE hello_snowflake_package
      SET DEFAULT RELEASE DIRECTIVE
      VERSION = v1_0
      PATCH = 0;
    
    Copy

    La sortie de cette commande est présentée dans l’exemple suivant :

    +-----------------------------------------------------------+
    | status                                                    |
    |-----------------------------------------------------------|
    | Default release directive set to version 'V1_0', patch 0. |
    +-----------------------------------------------------------+
    
    Copy

Dans cette section, vous avez vérifié quelles versions et quels correctifs existent dans votre paquet d’application. À l’aide de ces informations, vous avez défini la directive de version par défaut pour le paquet d’application.

Créez une annonce pour votre application

Maintenant que vous avez spécifié une directive de version pour votre paquet d’application, vous allez créer une annonce et ajouter le paquet d’application comme contenu de données de l’annonce. Cela vous permet de partager votre application avec d’autres utilisateurs de Snowflake et leur permet d’installer et d’utiliser l’application dans leur compte.

Pour créer une annonce pour votre application :

  1. Connectez-vous à Snowsight.

  2. Dans le menu de navigation, sélectionnez Data Products » Provider Studio.

  3. Sélectionnez + Listing. La fenêtre Créer une annonce s’ouvre.

  4. Saisissez un nom pour votre annonce.

  5. Dans la section In the Who can discover the listing, sélectionnez Only specified consumers pour partager en privé l’annonce avec des comptes spécifiques.

  6. Cliquez sur + Select pour sélectionner le paquet d’application de l’annonce.

  7. Saisissez une description de votre annonce.

  8. Dans la section Add consumer accounts , ajoutez l’identificateur du compte que vous utilisez pour tester l’installation de l’application à partir d’une annonce.

Dans cette section, vous avez créé une annonce privée contenant votre paquet d’application comme contenu de données partagées.

Installer l’application

Dans cette section, vous installerez l’application associée à l’annonce que vous avez créée dans la section précédente. Vous installerez l’annonce dans un compte différent qui imitera la façon dont un consommateur installerait l’application dans son compte.

Pour installer votre application à partir de l’annonce, procédez comme suit :

  1. Connectez-vous à Snowsight.

  2. Dans le menu de navigation, sélectionnez Data Products » Apps.

  3. Sélectionnez la vignette pour l’annonce sous Recently shared with you.

  4. Sélectionnez Get.

  5. Saisissez un nom orienté client pour l’application. Pour ce tutoriel, utilisez « Hello Snowflake App ».

  6. Sélectionnez l’entrepôt où vous souhaitez installer l’application.

  7. Sélectionnez Get.

  8. Sélectionnez Open pour voir votre annonce ou Done pour terminer.

Dans cette section, vous avez appris à publier et à installer une annonce qui vous permet de partager votre application avec d’autres utilisateurs de Snowflake.

En savoir plus

Félicitations ! Non seulement vous avez terminé ce tutoriel, mais vous avez travaillé sur le cycle de vie du développement et de la publication d’une application en utilisant le Native Apps Framework.

Vous avez :