Verwendung von Anforderungs- und Antwortübersetzern mit Daten für einen Remotedienst¶

Zuweisen einer Übersetzerfunktion zu einer externen Funktion¶

Um anzugeben, welche benutzerdefinierte Funktion als Übersetzer verwendet werden soll, fügen Sie in die CREATE EXTERNAL FUNCTION-Anweisung die Klauseln REQUEST_TRANSLATOR und RESPONSE_TRANSLATOR ein. Jede nimmt den Namen der Übersetzerfunktion an, die zur Laufzeit verwendet werden soll.

Beispiel:

CREATE EXTERNAL FUNCTION f(...)
    RETURNS OBJECT
    ...
    REQUEST_TRANSLATOR = my_request_translator_udf
    RESPONSE_TRANSLATOR = my_response_translator_udf
    ...
    AS <url_of_proxy_and_resource>;

Copy

Im Folgenden ist die Syntax für die Angabe von Übersetzern als Teil einer CREATE EXTERNAL FUNCTION-Anweisung gezeigt:

CREATE EXTERNAL FUNCTION f(...)
    RETURNS OBJECT
    ...
    [ REQUEST_TRANSLATOR = <request_translator_udf_name> ]
    [ RESPONSE_TRANSLATOR = <response_translator_udf_name> ]
    ...

Copy

Wobei:

request_translator_udf_name

Der Name der Anforderungsübersetzerfunktion.

response_translator_udf_name

Der Name der Antwortübersetzerfunktion.

Die Parameter REQUEST_TRANSLATOR und RESPONSE_TRANSLATOR nehmen jeweils einen Parameter vom Typ OBJECT auf.

Sie können auch einen Anforderungs- oder Antwortübersetzer in einem ALTER FUNCTION-Befehl angeben. Folgende Aufgaben können ausgeführt werden:

• Hinzufügen eines Übersetzers, wenn die externe Funktion noch keinen hat

• Ersetzen eines vorhandenen Übersetzer

• Entfernen eines Übersetzers

Verwenden Sie das Schlüsselwort SET, um einen neuen Übersetzer hinzuzufügen oder einen vorhandenen Übersetzer zu ersetzen.

So können Sie einen Übersetzer hinzufügen oder ersetzen:

ALTER FUNCTION ...
    SET [REQUEST_TRANSLATOR | RESPONSE_TRANSLATOR] = <udf_name>;

Copy

Wobei:

udf_name

Der Name einer vorher erstellten JavaScript-UDF.

So können Sie einen Übersetzer entfernen:

ALTER FUNCTION ...
    UNSET [REQUEST_TRANSLATOR | RESPONSE_TRANSLATOR];

Copy

SQL-Anforderungen¶

• Der Name der Übersetzerfunktion in der CREATE EXTERNAL FUNCTION- oder ALTER FUNCTION-Anweisung muss eine der folgenden Anforderungen erfüllen:

  • Der Name muss qualifiziert sein (z. B. MyDatabase.MySchema.MyJavaScriptUDF).

  • Der Name muss in derselben Datenbank und demselben Schema definiert sein wie die externe Funktion, in der er verwendet wird.

• Wenn der Übersetzer in einer CREATE EXTERNAL FUNCTION- oder ALTER FUNCTION-Anweisung angegeben wird, muss die Übersetzer-UDF bereits vorhanden sein. Sie können nicht zuerst den Namen angeben und später die UDF erstellen – auch nicht, wenn Sie die externe Funktion erst aufrufen, wenn Sie die UDF erstellt haben.

• Eine UDF, die als Übersetzer verwendet wird, darf erst gelöscht werden, wenn sie vorher aus allen externen Funktionen entfernt wurde, in denen sie verwendet wird. (Zum Zeitpunkt des Aufrufs der externen Funktion schlägt Snowflake mit einem Fehler fehl, wenn der Übersetzer nicht vorhanden ist).

• Wenn die Übersetzer-UDF mit ALTER FUNCTION geändert wird, muss sie dieselben Schnittstellenanforderungen erfüllen. Wenn die Schnittstellenanforderungen nicht erfüllt werden, wird vor Ausführung der externen Funktion eine Ausnahme ausgelöst.

Implementieren eines Anforderungsübersetzers¶

Implementieren eines Antwortübersetzers¶

Anforderungen an die Übersetzerfunktion¶

Jede Übersetzer-UDF muss die folgenden Anforderungen erfüllen:

• Muss eine JavaScript-UDF sein.

• Muss genau einen Parameter vom Typ OBJECT enthalten, der einen Batch von Zeilen repräsentiert.

• Muss genau einen Wert vom Typ OBJECT zurückgeben, der ebenfalls einen Batch von Zeilen repräsentiert.

• Die UDF muss skalar sein, d. h. sie gibt für jede übergebene Zeile (OBJECT) genau eine Zeile zurück.

  Bemerkung

  Obwohl der Übersetzer skalar ist, kann der an den Übersetzer übergebene OBJECT-Wert mehrere in den JSON-Code von OBJECT eingebettete Zeilen enthalten (und tut dies normalerweise auch).

• Anzahl und Reihenfolge der von der Antwortübersetzer-UDF zurückgegebenen Zeilen (innerhalb des OBJECT-Werts) müssen mit Anzahl und Reihenfolge der an die Anforderungsübersetzer-UDF übergebenen Zeilen (innerhalb der OBJECT-Werts) übereinstimmen.

Setup¶

Richten Sie eine Datenbank für die Demodaten ein.

Wählen Sie eine Rolle, die über die Berechtigung zum Erstellen externer Funktionen verfügt:

USE ROLE ACCOUNTADMIN;

Geben Sie an, welches Warehouse, welche Datenbank und welches Schema verwendet werden sollen:

USE WAREHOUSE w;
USE DATABASE a;
USE SCHEMA b;

Erstellen Sie eine Tabelle, die Ihre Testsätze enthält:

CREATE TABLE demo(vc varchar);
INSERT INTO demo VALUES('Today is a good day'),('I am feeling mopey');

Anforderungstext vor der Übersetzung¶

Diese externe Funktion hat weder einen Anforderungsübersetzer noch einen Antwortübersetzer:

CREATE OR REPLACE EXTERNAL FUNCTION ComprehendSentiment(thought varchar)
RETURNS VARIANT
API_INTEGRATION = aws_comprehend_gateway
AS 'https://<MY_GATEWAY>.execute-api.us-east-1.amazonaws.com/test/comprehend_proxy';

Rufen Sie die externe Funktion mit Ihren Testdaten aus der Demo-Tabelle auf:

SELECT ComprehendSentiment(vc), vc FROM demo;

Der generierte Anforderungstext verwendet das Snowflake-Datenformat für externe Funktionen:

{"body":{"data:" [[0, "Today is a good day"],[1,"I am feeling mopey"]]}}

Der externe Stimmungsanalyse-Dienst erwartet jedoch ein anderes Format, das die Sprache und ein Array von Zeichenfolgen angibt:

{"body": { Language: "en", TextList: [ "Today is a good day", "I am feeling mopey"]}}

Im nächsten Abschnitt wird beschrieben, wie Sie einen Anforderungsübersetzer hinzufügen können, um den Anforderungstext in das gewünschte Format zu ändern.

Anforderungstext konvertieren¶

Mithilfe eines Anforderungsübersetzers können Sie die oben beschriebene Standardeingabe (im Snowflake-Datenformat) in das Format umwandeln, das der externe Dienst benötigt.

Mit folgender SQL wird eine awscomprehendrequest_translator-Übersetzerfunktion erstellt.

CREATE OR REPLACE FUNCTION AWSComprehendrequest_translator(EVENT OBJECT)
RETURNS OBJECT
LANGUAGE JAVASCRIPT AS
'
var textlist = []
for(i = 0; i < EVENT.body.data.length; i++) {
   let row = EVENT.body.data[i];
   // row[0] is the row number and row[1] is the input text.
   textlist.push(row[1]); //put text into the textlist
}
// create the request for the service. Also pass the input request as part of the output.
return { "body": { "LanguageCode": "en", "TextList" : textlist }, "translatorData": EVENT.body }
';

Für die Anforderungsübersetzerfunktion wird folgender Code verwendet:

• Durchläuft jede Eingabezeilen in einer Schleife. Für jede Zeile wird die Zeichenfolge, die sich in row[1] befindet, dem Array textlist hinzugefügt. Der Wert in row[0] ist die Zeilennummer, die ignoriert werden kann.

• Gibt JSON-Text zurück, der den Sprachcode und die Textliste enthält, die mit den Anforderungen des externen Dienstes übereinstimmen.

• Gibt Daten über das Feld translatorData zurück. Dieses wird vom Antwortübersetzer verwendet. In diesem Beispiel senden Sie die ursprünglichen Eingabedaten. Anhand der Länge der Eingabedaten im Antwortübersetzer können Sie feststellen, wie viele Eingabeanforderungen es gab.

Sie können den Anforderungsübersetzer testen, indem Sie ihn direkt aufrufen.

SELECT AWSComprehendrequest_translator(parse_json('{"body":{"data": [[0, "I am so happy we got a sunny day for my birthday."], [1, "$$$$$."], [2, "Today is my last day in the old house."]]}}'));

Der Anforderungsübersetzer bringt den Text in die Form, die der externe Dienst erwartet.

{"body":{
   "LanguageCode": "en",
   "TextList": [
      "I am so happy we got a sunny day for my birthday.",
      "$$$$$.",
      "Today is my last day in the old house."
               ]
         },
   "translatorData": {
      "data": [[0, "I am so happy we got a sunny day for my birthday."],
               [1, "$$$$$."],
               [2, "Today is my last day in the old house."]]
                     }
}

Antworttext vor dem Hinzufügen eines Antwortübersetzers¶

Ein Antworttext des externen Dienstes sieht etwa wie folgt aus.

{"body":{
   "ErrorList": [ { "ErrorCode": 57, "ErrorMessage": "Language unknown", "Index": 1} ],
   "ResultList":[ { "Index": 0, "Sentiment": "POSITIVE",
                    "SentimentScore": { "Mixed": 25, "Negative": 5, "Neutral": 1, "Positive": 90 }},
                  { "Index": 2, "Sentiment": "NEGATIVE",
                    "SentimentScore": { "Mixed": 25, "Negative": 75, "Neutral": 30, "Positive": 20 }}
                ]
         }
}

Antworttext konvertieren¶

Der Antwortübersetzer verarbeitet die Ergebnisse, die Sie vom externen Dienst zurückerhalten. Die Ergebnisse enthalten eine Kombination aus Fehlern im ErrorList-Objekt und Ergebnissen im ResultList-Objekt.

Der Code des Antwortübersetzers kombiniert diese Ergebnisse zu einem vollständigen Set, das mit der Reihenfolge der Zeilen übereinstimmt, die an den externen Dienst übergeben wurden. Der Antwortübersetzer gibt die Ergebnisse im Snowflake-Format zurück.

Mit folgender SQL wird eine awscomprehendresponse_translator-Übersetzerfunktion erstellt.

CREATE OR REPLACE FUNCTION AWSComprehendresponse_translator(EVENT OBJECT)
RETURNS OBJECT
LANGUAGE JAVASCRIPT AS
'
// Combine the scored results and the errors into a single list.
var responses = new Array(EVENT.translatorData.data.length);
// output format: array of {
// "Sentiment": (POSITIVE, NEUTRAL, MIXED, NEGATIVE, or ERROR),
// "SentimentScore": <score>, "ErrorMessage": ErrorMessage }.
// If error, set ErrorMessage; otherwise, set SentimentScore.
// Insert good results into proper position.
for(i = 0; i < EVENT.body.ResultList.length; i++) {
   let row = EVENT.body.ResultList[i];
   let result = [row.Index, {"Sentiment": row.Sentiment, "SentimentScore": row.SentimentScore}]
   responses[row.Index] = result
}
// Insert errors.
for(i = 0; i < EVENT.body.ErrorList.length; i++) {
   let row = EVENT.body.ErrorList[i];
   let result = [row.Index, {"Sentiment": "Error", "ErrorMessage": row.ErrorMessage}]
   responses[row.Index] = result
}
return { "body": { "data" : responses } };
';

Für die Antwortübersetzerfunktion wird folgender Code verwendet:

• Initialisiert ein Array namens responses mit der Größe der Eingabe aus der Länge des Arrays translatorData. Sie haben translatorData vom Anforderungsübersetzer an den Antwortübersetzer gesendet, um die ursprüngliche Liste der Testzeichenfolgen zu übergeben.

• Durchläuft alle Ergebnisse, die keine Fehler sind, in einer Schleife, und trägt diese in die Ergebnisliste ein.

• Durchläuft die Fehlerergebnisse in einer Schleife, und trägt diese in die Ergebnisliste ein. Die Ergebnisliste hat eine Indexposition, die darüber informiert, um welchen Eintrag es sich handelt. Die Reihenfolge der erstellten Ergebnisse muss mit der Eingabereihenfolge übereinstimmen. Die Ergebnisliste enthält auch die Stimmungsinformationen.

Nachdem alle Antworten gesammelt wurden, werden sie in einem JSON-Text in dem von Snowflake erwarteten Format zurückgegeben.

Der folgende direkte Test liefert einen JSON-Textkörper mit dem korrekten Format.

SELECT AWSComprehendresponse_translator(
    parse_json('{
        "translatorData": {
            "data": [[0, "I am so happy we got a sunny day for my birthday."],
                    [1, "$$$$$."],
                    [2, "Today is my last day in the old house."]]
                          }
        "body": {
            "ErrorList":  [ { "ErrorCode": 57,  "ErrorMessage": "Language unknown",  "Index": 1 } ],
            "ResultList": [
                            { "Index": 0,  "Sentiment": "POSITIVE",
                              "SentimentScore": { "Mixed": 25,  "Negative": 5,  "Neutral": 1,  "Positive": 90 }
                            },
                            { "Index": 2, "Sentiment": "NEGATIVE",
                              "SentimentScore": { "Mixed": 25,  "Negative": 75,  "Neutral": 30,  "Positive": 20 }
                            }
                          ]
            },
        }'
    )
);

Übersetzer der externen Funktion zuweisen¶

Fügen Sie der externen Funktion die Anforderungs- und Antwortübersetzerfunktionen hinzu, indem Sie den Parametern request_translator und response_translator die Funktionsnamen als Werte zuweisen. Auf diese Weise werden sie automatisch aufgerufen, wenn die externe Funktion ausgeführt wird.

CREATE OR REPLACE EXTERNAL FUNCTION ComprehendSentiment(thought varchar)
RETURNS VARIANT
API_INTEGRATION = aws_comprehend_gateway
request_translator = db_name.schema_name.AWSComprehendrequest_translator
response_translator = db_name.schema_name.AWSComprehendresponse_translator
AS 'https://<MY_GATEWAY>.execute-api.us-east-1.amazonaws.com/test/comprehend_proxy';

Sie können die Funktion beschreiben, um Informationen über sie zu erhalten.

DESCRIBE FUNCTION ComprehendSentiment(VARCHAR);

Externe Funktion aufrufen¶

Testen Sie die externe Funktion, indem Sie sie mit einem einzelnen Satz aufrufen.

SELECT ComprehendSentiment('Today is a good day');

Sie sehen die Ergebnisse der Stimmungsanalyse.

{"Sentiment": "POSITIVE",
 "SentimentScore":{"Mixed":0.002436627633869648,
                   "Negative":0.0014803812373429537,
                   "Neutral":0.015923455357551575,
                   "Positive": 0.9801595211029053}}

Testen Sie die externe Funktion, indem Sie sie mit mehreren Sätzen aufrufen. Verwenden Sie dieselbe Tabelle demo, die Sie zuvor erstellt haben.

SELECT ComprehendSentiment(vc), vc FROM demo;

Die Ergebnisse der Stimmungsanalyse werden angezeigt.

Beim Aufruf der externen Funktion konvertierte der Anforderungsübersetzer die Daten automatisch in das für den externen Dienst erforderliche Format. Anschließend konvertierte der Antwortübersetzer die Antwort des externen Dienstes automatisch zurück in das von Snowflake benötigte Format.