Tutoriel 1 : créer un service Snowpark Container Services¶

Introduction¶

Après avoir terminé l’installation commune, vous êtes prêt à créer un service. Dans ce tutoriel, vous créez un service (nommé echo_service) qui renvoie simplement un texte que vous fournissez en entrée. Par exemple, si la chaîne d’entrée est « Hello World », le service renvoie « I said, Hello World ».

Ce tutoriel comporte deux parties :

Partie 1 : créez et testez un service. Vous téléchargez le code fourni pour ce tutoriel et suivez les instructions étape par étape :

1. Téléchargez le code de service pour ce tutoriel.

2. Créez une image Docker pour Snowpark Container Services, et chargez l’image dans un référentiel de votre compte.

3. Créez un service, en fournissant le fichier de spécification de service et le pool de calcul dans lequel le service sera exécuté.

4. Créez une fonction de service pour communiquer avec le service.

5. Utilisez le service. Vous envoyez des demandes echo au service et vérifiez la réponse.

Partie 2 : comprendre le service. Cette section donne une vue d’ensemble du code de service et met en évidence la façon dont les différentes composantes collaborent.

1 : Télécharger le code de service¶

Un code (une application Python) est fourni pour créer le service echo.

1. Téléchargez le fichier zip dans un répertoire.

2. Décompressez le contenu, qui comprend un répertoire pour chaque tutoriel. Le répertoire Tutorial-1 contient les fichiers suivants :

   • Dockerfile

   • echo_service.py

   • templates/basic_ui.html

2 : Construire une image et la charger¶

Construisez une image pour la plateforme linux/amd64 prise en charge par Snowpark Container Services, puis chargez l’image dans le référentiel d’images de votre compte (voir Configuration commune).

Vous aurez besoin d’informations sur le référentiel (l’URL du référentiel et le nom d’hôte du registre) avant de pouvoir construire et charger l’image. Pour plus d’informations, voir Registre et référentiels.

Obtenir des informations sur le référentiel

1. Pour obtenir l’URL du référentiel, exécutez la commande SQL SHOW IMAGE REPOSITORIES.

   SHOW IMAGE REPOSITORIES;
   

   Copy

   • La colonne repository_url de la sortie fournit l’URL. En voici un exemple :

     <orgname>-<acctname>.registry.snowflakecomputing.com/tutorial_db/data_schema/tutorial_repository
     

   • Le nom d’hôte dans l’URL du référentiel est le nom d’hôte du registre. En voici un exemple :

     <orgname>-<acctname>.registry.snowflakecomputing.com
     

Construire l’image et la charger dans le référentiel

1. Ouvrez une fenêtre de terminal et accédez au répertoire contenant les fichiers que vous avez décompressés.

2. Pour créer une image Docker, exécutez la commande docker build suivante à l’aide de la CLI Docker. Notez que la commande spécifie le répertoire de travail actuel (.) comme PATH pour les fichiers à utiliser pour la construction de l’image.

   docker build --rm --platform linux/amd64 -t <repository_url>/<image_name> .
   

   Copy

   • Pour image_name, utilisez my_echo_service_image:latest.

   Exemple

   docker build --rm --platform linux/amd64 -t myorg-myacct.registry.snowflakecomputing.com/tutorial_db/data_schema/tutorial_repository/my_echo_service_image:latest .
   

   Copy

3. Chargez l’image dans le référentiel de votre compte Snowflake. Pour que Docker puisse charger une image en votre nom dans votre référentiel, vous devez d’abord authentifier Docker avec Snowflake.

   1. Pour authentifier Docker auprès du registre Snowflake, exécutez la commande suivante.

      docker login <registry_hostname> -u <username>
      

      Copy

      • Pour username, indiquez votre nom d’utilisateur Snowflake. Docker vous demandera votre mot de passe.

   2. Pour charger l’image, exécutez la commande suivante :

      docker push <repository_url>/<image_name>
      

      Copy

      Exemple

      docker push myorg-myacct.registry.snowflakecomputing.com/tutorial_db/data_schema/tutorial_repository/my_echo_service_image:latest
      

      Copy

3 : Créer un service¶

Dans cette section, vous créez un service et une fonction de service pour communiquer avec le service.

Pour créer un service, vous devez disposer des éléments suivants :

• Un pool de calcul. Snowflake exécute votre service dans le pool de calcul spécifié. Vous avez créé un pool de calcul dans le cadre de la configuration commune.

• Une spécification de service. Cette spécification fournit à Snowflake les informations nécessaires pour configurer et exécuter votre service. Pour plus d’informations, voir Snowpark Container Services : utilisation des tâches. Dans ce tutoriel, vous fournissez la spécification en ligne, dans la commande CREATE SERVICE. Vous pouvez également enregistrer la spécification dans un fichier de votre zone de préparation Snowflake et fournir des informations sur le fichier dans la commande CREATE SERVICE, comme le montre le tutoriel 2.

Une fonction de service est l’une des méthodes disponibles pour communiquer avec votre service. Une fonction de service est une fonction définie par l’utilisateur (UDF) que vous associez au point de terminaison de service. Lorsque la fonction de service est exécutée, elle envoie une requête au point de terminaison de service et reçoit une réponse.

1. Vérifiez que le pool de calcul est prêt et que vous êtes dans le bon contexte pour créer le service.

   1. Auparavant, vous avez défini le contexte dans l’étape Configuration commune. Pour vous assurer que vous êtes dans le bon contexte pour les instructions SQL dans cette étape, exécutez ce qui suit :

   USE ROLE test_role;
   USE DATABASE tutorial_db;
   USE SCHEMA data_schema;
   USE WAREHOUSE tutorial_warehouse;
   

   Copy

   1. Pour s’assurer que le pool de calcul que vous avez créé dans la configuration commune est prêt, exécutez DESCRIBE COMPUTE POOL, et vérifiez que state est ACTIVE ou IDLE. Si le state est STARTING, vous devez attendre que le state devienne ACTIVE ou IDLE.

   DESCRIBE COMPUTE POOL tutorial_compute_pool;
   

   Copy

2. Pour créer le service, exécutez la commande suivante en utilisant test_role :

   CREATE SERVICE echo_service
     IN COMPUTE POOL tutorial_compute_pool
     FROM SPECIFICATION $$
       spec:
         containers:
         - name: echo
           image: /tutorial_db/data_schema/tutorial_repository/my_echo_service_image:latest
           env:
             SERVER_PORT: 8000
             CHARACTER_NAME: Bob
           readinessProbe:
             port: 8000
             path: /healthcheck
         endpoints:
         - name: echoendpoint
           port: 8000
           public: true
         $$
      MIN_INSTANCES=1
      MAX_INSTANCES=1;
   

   Copy

   Note

   Si un service portant ce nom existe déjà, utilisez la commande DROP SERVICE pour supprimer le service précédemment créé, puis créez ce service.

3. Exécutez les commandes SQL suivantes pour obtenir des informations détaillées sur le service que vous venez de créer. Pour plus d’informations, voir Snowpark Container Services : utilisation des tâches.

   • Pour dresser la liste des services de votre compte, exécutez la commande SHOW SERVICES :

     SHOW SERVICES;
     

     Copy

   • Pour connaître le statut de votre service, appelez la fonction système SYSTEM$GET_SERVICE_STATUS :

     SELECT SYSTEM$GET_SERVICE_STATUS('echo_service');
     

     Copy

   • Pour obtenir des informations sur votre service, exécutez la commande DESCRIBE SERVICE :

     DESCRIBE SERVICE echo_service;
     

     Copy

4. Pour créer une fonction de service, exécutez la commande suivante :

   CREATE FUNCTION my_echo_udf (InputText varchar)
     RETURNS varchar
     SERVICE=echo_service
     ENDPOINT=echoendpoint
     AS '/echo';
   

   Copy

   Remarques :

   • La propriété SERVICE associe l’UDF au service echo_service.

   • La propriété ENDPOINT associe l’UDF au point de terminaison echoendpoint au sein du service.

   • AS “/echo” indique le chemin d’accès HTTP au serveur echo. Vous trouverez ce chemin dans le code de service (echo_service.py).

4 : Utiliser le service¶

Tout d’abord, pour définir le contexte des instructions SQL de cette section, exécutez ce qui suit :

USE ROLE test_role;
USE DATABASE tutorial_db;
USE SCHEMA data_schema;
USE WAREHOUSE tutorial_warehouse;

Vous pouvez maintenant communiquer avec le service echo.

1. Utilisation d’une fonction de service : vous pouvez appeler la fonction de service dans une requête. La fonction de service de l’exemple (my_echo_udf) peut prendre en entrée une seule chaîne ou une liste de chaînes.

   Exemple 1.1 : transmettre une seule chaîne

   • Pour appeler la fonction de service my_echo_udf , exécutez l’instruction SELECT suivante, en transmettant une chaîne d’entrée ('hello') :

     SELECT my_echo_udf('hello!');
     

     Copy

     Snowflake envoie une requête POST au point de terminaison de service (echoendpoint). À la réception de la requête, le service répercute la chaîne d’entrée dans la réponse.

     +--------------------------+
     | **MY_ECHO_UDF('HELLO!')**|
     |------------------------- |
     | Bob said hello!          |
     +--------------------------+
     

   Exemple 1.2 : transmettre une liste de chaînes

   Lorsque vous transmettez une liste de chaînes à la fonction de service, Snowflake regroupe ces chaînes d’entrée et envoie une série de requêtes POST au service. Une fois que le service a traité toutes les chaînes, Snowflake combine les résultats et les renvoie.

   L’exemple suivant transmet une colonne de table à la fonction de service.

   1. Créez une table avec plusieurs chaînes :

      CREATE TABLE messages (message_text VARCHAR)
        AS (SELECT * FROM (VALUES ('Thank you'), ('Hello'), ('Hello World')));
      

      Copy

   2. Pour vérifier que la table a été créée :

      SELECT * FROM messages;
      

      Copy

   3. Pour appeler la fonction de service, exécutez l’instruction SELECT suivante, en transmettant les lignes de la table en entrée :

      SELECT my_echo_udf(message_text) FROM messages;
      

      Copy

      Sortie :

      +---------------------------+
      | MY_ECHO_UDF(MESSAGE_TEXT) |
      |---------------------------|
      | Bob said Thank you        |
      | Bob said Hello            |
      | Bob said Hello World      |
      +---------------------------+
      

2. En utilisant un navigateur Web : le service expose le point de terminaison publiquement (voir la spécification en ligne fournie dans la commande CREATE SERVICE). Par conséquent, vous pouvez vous connecter à une UI Web que le service expose à Internet, puis envoyer des requêtes au service à partir d’un navigateur Web.

   1. Trouvez l’URL du point de terminaison public auquel le service est exposé :

      SHOW ENDPOINTS IN SERVICE echo_service;
      

      Copy

      La colonne ingress_url de la réponse fournit l’URL.

      Exemple

      p6bye-myorg-myacct.snowflakecomputing.app
      

   2. Ajoutez /ui à l’URL du point de terminaison et collez-la dans le navigateur Web. Le service exécute alors la fonction ui() (voir echo_service.py).

      Notez que la première fois que vous accédez à l’URL du point de terminaison, il vous sera demandé de vous connecter à Snowflake. Pour ce test, utilisez le même utilisateur que celui que vous avez utilisé pour créer le service afin de vous assurer qu’il dispose des privilèges nécessaires.

      

   3. Saisissez la chaîne « Hello » dans la case Entrée et appuyez sur Retour.

      

   Note

   Vous pouvez accéder au point de terminaison d’entrée de manière programmatique. Pour un exemple de code, voir Accès et authentification des points de terminaison publics. Notez que vous devrez ajouter /ui à l’URL du point de terminaison dans le code afin que Snowflake puisse acheminer la demande vers la fonction ui() dans le code de service.

5 : Nettoyage¶

Si vous ne prévoyez pas de poursuivre le tutoriel 2 ou le tutoriel 3, vous devez supprimer les ressources facturables que vous avez créées. Pour plus d’informations, voir l’étape 5 dans le tutoriel 3.

6 : Vérification du code de service¶

Cette section couvre les sujets suivants :

• Examen du code du tutoriel 1 : examinez les fichiers de code qui mettent en œuvre le service echo.

• Comprendre la fonction de service : cette section explique comment la fonction de service de ce tutoriel est liée au service.

• Construire et tester une image localement. Cette section explique comment vous pouvez tester localement l’image Docker avant de la charger vers un référentiel dans votre compte Snowflake.

from flask import Flask
from flask import request
from flask import make_response
from flask import render_template
import logging
import os
import sys

SERVICE_HOST = os.getenv('SERVER_HOST', '0.0.0.0')
SERVER_PORT = os.getenv('SERVER_PORT', 8080)
CHARACTER_NAME = os.getenv('CHARACTER_NAME', 'I')


def get_logger(logger_name):
  logger = logging.getLogger(logger_name)
  logger.setLevel(logging.DEBUG)
  handler = logging.StreamHandler(sys.stdout)
  handler.setLevel(logging.DEBUG)
  handler.setFormatter(
    logging.Formatter(
      '%(name)s [%(asctime)s] [%(levelname)s] %(message)s'))
  logger.addHandler(handler)
  return logger


logger = get_logger('echo-service')

app = Flask(__name__)


@app.get("/healthcheck")
def readiness_probe():
  return "I'm ready!"


@app.post("/echo")
def echo():
  '''
  Main handler for input data sent by Snowflake.
  '''
  message = request.json
  logger.debug(f'Received request: {message}')

  if message is None or not message['data']:
    logger.info('Received empty message')
    return {}

  # input format:
  #   {"data": [
  #     [row_index, column_1_value, column_2_value, ...],
  #     ...
  #   ]}
  input_rows = message['data']
  logger.info(f'Received {len(input_rows)} rows')

  # output format:
  #   {"data": [
  #     [row_index, column_1_value, column_2_value, ...}],
  #     ...
  #   ]}
  output_rows = [[row[0], get_echo_response(row[1])] for row in input_rows]
  logger.info(f'Produced {len(output_rows)} rows')

  response = make_response({"data": output_rows})
  response.headers['Content-type'] = 'application/json'
  logger.debug(f'Sending response: {response.json}')
  return response


@app.route("/ui", methods=["GET", "POST"])
def ui():
  '''
  Main handler for providing a web UI.
  '''
  if request.method == "POST":
    # getting input in HTML form
    input_text = request.form.get("input")
    # display input and output
    return render_template("basic_ui.html",
      echo_input=input_text,
      echo_reponse=get_echo_response(input_text))
  return render_template("basic_ui.html")


def get_echo_response(input):
  return f'{CHARACTER_NAME} said {input}'

if __name__ == '__main__':
  app.run(host=SERVICE_HOST, port=SERVER_PORT)

ARG BASE_IMAGE=python:3.10-slim-buster
FROM $BASE_IMAGE
COPY echo_service.py ./
COPY templates/ ./templates/
RUN pip install --upgrade pip && \\
pip install flask
CMD ["python", "echo_service.py"]

<!DOCTYPE html>
<html lang="en">
  <head>
    <title>Welcome to echo service!</title>
  </head>
  <body>
    <h1>Welcome to echo service!</h1>
    <form action="{{ url_for("ui") }}" method="post">
      <label for="input">Input:<label><br>
      <input type="text" id="input" name="input"><br>
    </form>
    <h2>Input:</h2>
    {{ echo_input }}
    <h2>Output:</h2>
    {{ echo_reponse }}
  </body>
</html>

spec:
  containers:
  - name: echo
    image: /tutorial_db/data_schema/tutorial_repository/my_echo_service_image:latest
    env:
      SERVER_PORT: 8000
      CHARACTER_NAME: Bob
    readinessProbe:
      port: 8000
      path: /healthcheck
  endpoints:
  - name: echoendpoint
    port: 8000
    public: true

CREATE FUNCTION my_echo_udf (InputText VARCHAR)
  RETURNS VARCHAR
  SERVICE=echo_service
  ENDPOINT=echoendpoint
  AS '/echo';

Quelle est la prochaine étape ?¶

Vous pouvez maintenant tester le tutoriel 2 qui exécute une tâche.