Tutorial 1: Snowpark Container Services-Dienst erstellen¶

Einführung¶

Nachdem Sie die grundlegende Einrichtung abgeschlossen haben, können Sie nun einen Dienst erstellen. In diesem Tutorial erstellen Sie einen Dienst (mit dem Namen echo_service), der einfach den von Ihnen eingegebenen Text als Echo wieder zurückgibt. Wenn die Eingabezeichenfolge beispielsweise „Hello World“ ist, gibt der Dienst „I said, Hello World“ zurück.

Dieses Tutorial besteht aus zwei Teilen:

Teil 1: Dienst erstellen und testen. Sie laden den für dieses Tutorial bereitgestellten Code herunter und befolgen die schrittweise Anleitung:

1. Dienstcode für dieses Tutorial herunterladen

2. Docker-Image für Snowpark Container Services erstellen und Image in Repository im eigenen Konto hochladen

3. Dienst erstellen, indem die Dienstspezifikationsdatei und der Computepool für die Ausführung des Dienstes bereitgestellt werden

4. Dienstfunktion für die Kommunikation mit dem Dienst bereitstellen

5. Dienst einsetzen. Dazu wird eine Echo-Anforderung an den Dienst gesendet und die Antwort überprüft.

Teil 2: Erläuterungen zum Dienst. Dieser Abschnitt bietet eine Übersicht zum Dienstcode und zeigt auf, wie die verschiedenen Komponenten zusammenarbeiten.

1: Dienstcode herunterladen¶

Zum Erstellen des Echo-Dienstes wird ein Code (eine Python-Anwendung) bereitgestellt.

1. Laden Sie die ZIP-Datei in ein Verzeichnis herunter.

2. Entpacken Sie den Inhalt, der ein Verzeichnis für jedes Tutorial enthält. Das Verzeichnis Tutorial-1 enthält die folgenden Dateien:

   • Dockerfile

   • echo_service.py

   • templates/basic_ui.html

2: Image erstellen und hochladen¶

Erstellen Sie ein Image für die linux/amd64-Plattform, die von Snowpark Container Services unterstützt wird, und laden Sie das Image dann in das Image-Repository in Ihrem Konto hoch (siehe Grundlegende Einrichtung).

Sie benötigen Informationen zum Repository (die Repository-URL und den Hostnamen der Registry), bevor Sie das Image erstellen und hochladen können. Weitere Informationen dazu finden Sie unter Registry und Repositorys.

Informationen zum Repository abrufen

1. Um die Repository-URL zu erhalten, führen Sie den SQL-Befehl SHOW IMAGE REPOSITORIES aus.

   SHOW IMAGE REPOSITORIES;
   

   Copy

   • Die URL ist in der Spalte repository_url der Ausgabe enthalten. Siehe folgendes Beispiel:

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

   • Der Hostname in der Repository-URL ist der Name des Registry-Hosts. Siehe folgendes Beispiel:

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

Image erstellen und in das Repository hochladen

1. Öffnen Sie ein Terminalfenster, und wechseln Sie in das Verzeichnis, das die entpackten Dateien enthält.

2. Um ein Docker-Image zu erstellen, führen Sie den folgenden Befehl docker build mithilfe der Docker-CLI aus. Beachten Sie, dass der Befehl das aktuelle Arbeitsverzeichnis (.) als PATH für die Dateien angibt, die für das Erstellen des Images verwendet werden sollen.

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

   Copy

   • Für image_name verwenden Sie my_echo_service_image:latest:

   Beispiel

   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. Laden Sie das Image in das Repository in Ihrem Snowflake-Konto hoch. Damit Docker ein Image in Ihrem Namen in Ihr Repository hochladen kann, müssen Sie Docker zunächst mit Snowflake authentifizieren.

   1. Um Docker bei der Snowflake-Registrierung zu authentifizieren, führen Sie den folgenden Befehl aus.

      docker login <registry_hostname> -u <username>
      

      Copy

      • Geben Sie dabei für username Ihren Snowflake-Benutzernamen an. Docker fordert Sie zur Eingabe Ihres Kennworts auf.

   2. Führen Sie den folgenden Befehl aus, um das Image hochzuladen:

      docker push <repository_url>/<image_name>
      

      Copy

      Beispiel

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

      Copy

3: Dienst erstellen¶

In diesem Abschnitt erstellen Sie einen Dienst und dann eine Dienstfunktion, die mit dem Dienst kommuniziert.

Um einen Dienst zu erstellen, benötigen Sie Folgendes:

• Einen Computepool. Snowflake führt Ihren Dienst in dem angegebenen Computepool aus. Sie haben einen Computepool als Teil der grundlegenden Einrichtung erstellt.

• Eine Dienstspezifikation. Diese Spezifikation liefert Snowflake die Informationen, die zur Konfiguration und Ausführung Ihres Dienstes erforderlich sind. Weitere Informationen dazu finden Sie unter Snowpark Container Services: Verwenden von Diensten. In diesem Tutorial geben Sie die Spezifikation inline im Befehl CREATE SERVICE an. Sie können die Spezifikation auch in einer Datei in Ihrem Snowflake-Stagingbereich speichern und die Dateiinformationen im Befehl CREATE SERVICE bereitstellen, wie in Tutorial 2 gezeigt.

Eine Dienstfunktion ist eine der verfügbaren Methoden zur Kommunikation mit Ihrem Dienst. Eine Dienstfunktion ist eine benutzerdefinierte Funktion (UDF), die Sie mit dem Dienstendpunkt verknüpfen. Wenn die Dienstfunktion ausgeführt wird, sendet sie eine Anforderung an den Dienstendpunkt und erhält eine Antwort.

1. Überprüfen Sie, ob der Computepool bereit ist und ob Sie sich im korrekten Kontext befinden, um den Dienst zu erstellen.

   1. Zuvor haben Sie den Kontext im Schritt Grundlegende Einrichtung festgelegt. Um sicherzustellen, dass Sie sich in diesem Schritt im korrekten Kontext für die SQL-Anweisungen befinden, führen Sie Folgendes aus:

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

   Copy

   1. Um sicherzustellen, dass der unter Grundlegende Einrichtung erstellte Computepool bereit ist, führen Sie DESCRIBE COMPUTE POOL aus, und überprüfen Sie dann, ob state den Wert ACTIVE oder IDLE hat. Wenn die state den Wert STARTING hat, müssen Sie warten, bis state entweder ACTIVE oder IDLE ist.

   DESCRIBE COMPUTE POOL tutorial_compute_pool;
   

   Copy

2. Um den Dienst zu erstellen, führen Sie mit der Rolle test_role den folgenden Befehl aus:

   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

   Bemerkung

   Wenn bereits ein Dienst mit diesem Namen existiert, verwenden Sie den Befehl DROP SERVICE, um den zuvor erstellten Dienst zu löschen, und erstellen Sie dann diesen Dienst.

3. Führen Sie die folgenden SQL-Befehle aus, um detaillierte Informationen zu dem gerade erstellten Dienst zu erhalten. Weitere Informationen dazu finden Sie unter Snowpark Container Services: Verwenden von Diensten.

   • Um die Dienste in Ihrem Konto aufzulisten, führen Sie den Befehl SHOW SERVICES aus:

     SHOW SERVICES;
     

     Copy

   • Um den Status Ihres Dienstes zu erfahren, rufen Sie die Systemfunktion SYSTEM$GET_SERVICE_STATUS auf:

     SELECT SYSTEM$GET_SERVICE_STATUS('echo_service');
     

     Copy

   • Um Informationen zu Ihrem Dienst zu erhalten, führen Sie den Befehl DESCRIBE SERVICE aus:

     DESCRIBE SERVICE echo_service;
     

     Copy

4. Um eine Dienstfunktion zu erstellen, führen Sie den folgenden Befehl aus:

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

   Copy

   Beachten Sie Folgendes:

   • Die Eigenschaft SERVICE verknüpft die UDF mit dem Dienst echo_service.

   • Die Eigenschaft ENDPOINT verknüpft die UDF mit dem Endpunkt echoendpoint innerhalb des Dienstes.

   • „AS ‚/echo‘“ gibt den HTTP-Pfad zum Echo-Server an. Sie finden diesen Pfad im Dienstcode (echo_service.py).

4: Dienst einsetzen¶

Richten Sie zunächst den Kontext für die SQL-Anweisungen in diesem Abschnitt ein, indem Sie Folgendes ausführen:

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

Jetzt können Sie mit dem Echo-Dienst kommunizieren.

1. Verwenden einer Dienstfunktion: Sie können die Dienstfunktion in einer Abfrage aufrufen. Die Beispiel-Dienstfunktion (my_echo_udf) kann als Eingabe entweder eine einzelne Zeichenfolge oder eine Liste von Zeichenfolgen als Eingabe annehmen.

   Beispiel 1.1: Einzelne Zeichenfolge übergeben

   • Um die Dienstfunktion my_echo_udf aufzurufen, führen Sie die folgende SELECT-Anweisung aus und übergeben genau eine Eingabezeichenfolge ('hello'):

     SELECT my_echo_udf('hello!');
     

     Copy

     Snowflake sendet eine POST-Anforderung an den Dienstendpunkt (echoendpoint). Nach Erhalt der Anforderung gibt der Dienst die Eingabezeichenfolge als Echo in der Antwort zurück.

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

   Beispiel 1.2: Liste von Zeichenfolge übergeben

   Wenn Sie eine Liste von Zeichenfolgen an die Dienstfunktion übergeben, fasst Snowflake diese Eingabezeichenfolgen in einem Batch zusammen und sendet eine Serie von POST-Anforderungen an den Dienst. Nachdem der Dienst alle Zeichenfolgen verarbeitet hat, kombiniert Snowflake die Ergebnisse und gibt sie zurück.

   Im folgenden Beispiel wird eine Tabellenspalte als Eingabe an die Dienstfunktion übergeben.

   1. Erstellen Sie eine Tabelle mit mehreren Zeichenfolgen:

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

      Copy

   2. Überprüfen Sie, ob die Tabelle erstellt wurde, indem Sie folgende Anweisung ausführen:

      SELECT * FROM messages;
      

      Copy

   3. Um die Dienstfunktion aufzurufen, führen Sie die folgende SELECT-Anweisung aus und übergeben dabei Tabellenzeilen als Eingabe:

      SELECT my_echo_udf(message_text) FROM messages;
      

      Copy

      Ausgabe:

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

2. Webbrowser verwenden: Der Dienst stellt den Endpunkt öffentlich zur Verfügung (siehe Inline-Spezifikation im Befehl CREATE SERVICE). Daher können Sie sich bei einer Web-UI anmelden, die der Dienst im Internet bereitstellt, und dann von einem Webbrowser aus Anforderungen an den Dienst senden.

   1. Ermitteln Sie die URL des öffentlichen Endpunkts, den der Dienst bereitstellt:

      SHOW ENDPOINTS IN SERVICE echo_service;
      

      Copy

      Die Spalte ingress_url in der Antwort enthält die URL.

      Beispiel

      p6bye-myorg-myacct.snowflakecomputing.app
      

   2. Hängen Sie /ui an die Endpunkt-URL an, und geben Sie diese Zeichenfolge in den Webbrowser ein. Dies veranlasst den Dienst, die Funktion ui() auszuführen (siehe echo_service.py).

      Beachten Sie, dass Sie beim ersten Zugriff auf die Endpunkt-URL aufgefordert werden, sich bei Snowflake anzumelden. Verwenden Sie für diesen Test denselben Benutzer, mit dem Sie den Dienst erstellt haben, um sicherzustellen, dass der Benutzer über die erforderlichen Berechtigungen verfügt.

      

   3. Geben Sie in das Feld Input die Zeichenfolge „Hello“ ein, und drücken Sie die Eingabetaste.

      

   Bemerkung

   Sie können auf den Eingangsendpunkt programmgesteuert zugreifen. Ein Beispielcode ist unter Zugriff auf öffentliche Endpunkte und Authentifizierung zu finden. Beachten Sie, dass Sie im Code an die Endpunkt-URL die Pfadangabe /ui anhängen müssen, damit Snowflake die Anfrage an die ui()-Funktion im Dienstcode weiterleiten kann.

5: Bereinigen¶

Wenn Sie nicht vorhaben, mit Tutorial 2 oder Tutorial 3 fortzufahren, sollten Sie die von Ihnen erstellten abrechenbaren Ressourcen wieder entfernen. Weitere Informationen dazu finden Sie in Schritt 5 von Tutorial 3.

6: Erläuterungen zum Dienstcode¶

In diesem Abschnitt werden die folgenden Themen behandelt:

• Code von Tutorial 1 überprüfen: Überprüfen Sie die Codedateien, die den Echo-Dienst implementieren.

• Erläuterungen zur Dienstfunktion: In diesem Abschnitt wird erklärt, wie in diesem Tutorial die Dienstfunktion mit dem Dienst verknüpft ist.

• Lokales Erstellen und Testen eines Images. In diesem Abschnitt wird erläutert, wie Sie das Docker-Image lokal testen können, bevor Sie es in ein Repository in Ihrem Snowflake-Konto hochladen.

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

Nächste Schritte¶

Sie können nun mit Tutorial 2 fortfahren, in dem ein Job ausgeführt wird.