リモートサービスに対するデータのあるリクエストトランスレーターおよび応答トランスレーターの使用¶

トランスレーター関数の外部関数への割り当て¶

トランスレーターとして使用するユーザー定義関数を指定するには、 CREATE EXTERNAL FUNCTION ステートメントに REQUEST_TRANSLATOR 句と RESPONSE_TRANSLATOR 句を含めます。それぞれが、実行時に使用するトランスレーター関数の名前を取得します。

例:

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

CREATE EXTERNAL FUNCTION ステートメントの一部としてトランスレーターを指定するための構文を以下に示します。

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

Copy

条件:

request_translator_udf_name

リクエストトランスレーター関数の名前。

response_translator_udf_name

応答トランスレーター関数の名前。

REQUEST_TRANSLATOR および RESPONSE_TRANSLATOR パラメーターは、それぞれが型 OBJECT の1つのパラメーターを取ります。

ALTER FUNCTION コマンドでリクエストトランスレーターまたは応答トランスレーターを指定することもできます。できること:

• 外部関数にトランスレーターがない場合に、トランスレーターを追加します。

• 既存のトランスレーターを置換します。

• トランスレーターを削除します。

SET キーワードを使用して、新しいトランスレーターを追加するか、既存のトランスレーターを置換します。

トランスレーターを追加または置換するには、

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

Copy

条件

udf_name

以前に作成した JavaScript UDF の名前。

トランスレーターを削除するには、

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

Copy

SQL の要件¶

• CREATE EXTERNAL FUNCTION または ALTER FUNCTION ステートメントのトランスレーター関数の名前は次のいずれかである必要があります。

  • 修飾名（例: MyDatabase.MySchema.MyJavaScriptUDF）。

  • それらを使用する外部関数と同じデータベースおよびスキーマで定義されます。

• トランスレーターが CREATE EXTERNAL FUNCTION または ALTER FUNCTION ステートメントで指定されている場合、トランスレーター UDF はすでに存在している必要があります。（UDF を作成する前に外部関数を呼び出さない場合でも、最初に名前を指定して、後で UDF を作成することはできません。）

• トランスレーターで使用されるリクエストトランスレーター UDF または応答トランスレーターは、それを使用するすべての外部関数から最初に削除することなくドロップしないでください。（外部関数が呼び出されたときに、リクエストトランスレーターまたは応答トランスレーターが存在しない場合、Snowflakeはエラーを発生して失敗します。）

• リクエストトランスレーターまたは応答トランスレーター UDF が（ALTER FUNCTION を介して）変更された場合は、同じインターフェイス要件を保持する必要があります。インターフェイス要件が保持されていない場合は、外部関数を実行する前に例外が発生します。

リクエストトランスレーターの実装¶

応答トランスレーターの実装¶

トランスレーター関数の要件¶

各トランスレーター UDF は、次の要件を満たしている必要があります。

• JavaScript UDF である必要があります。

• 行のバッチを表す型 OBJECT のパラメーターを1つだけ取る必要があります。

• 型 OBJECT の値を1つ返す必要があります。これは、行のバッチも表します。

• スカラー UDF である必要があります（渡された行（OBJECT）ごとに1行を返す）。

  注釈

  トランスレーターはスカラーですが、トランスレーターに渡される OBJECT では、 OBJECT の JSON 内に（通常は）複数の行を埋め込むことができます。

• 応答トランスレーター UDF によって返される行の数と順序（OBJECT 内）は、リクエストトランスレーター UDF に渡される行の数と順序（OBJECT 内）と同じである必要があります。

設定¶

デモデータを保持するデータベースを設定します。

外部関数を作成する権限を持つロールを選択します。

USE ROLE ACCOUNTADMIN;

使用するウェアハウス、データベース、およびスキーマを指定します。

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

テスト文を保持するテーブルを作成します。

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

翻訳前に本文をリクエストする¶

この外部関数には、リクエストトランスレーターまたは応答トランスレーターがありません。

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

デモテーブルのテストデータを使用して外部関数を呼び出すことができます。

SELECT ComprehendSentiment(vc), vc FROM demo;

生成されたリクエスト本文は、Snowflake外部関数データ形式を使用します。

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

ただし、外部感情分析サービスは、言語と文字列の配列を指定する別の形式を想定しています。

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

次のセクションでは、リクエストトランスレーターを追加して、リクエスト本文を必要な形式に変更する方法について説明します。

リクエスト本文を変換する¶

リクエストトランスレーターを使用すると、上記のデフォルトの入力（Snowflakeデータ形式）を外部サービスが必要とする形式に変換できます。

次の SQL は、 awscomprehendrequest_translator トランスレーター関数を作成します。

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

リクエストトランスレーター関数のコードは、

• 各入力行を介してループします。行ごとに、 row[1] にある文字列を textlist 配列に追加します。 row[0] の値は行番号であり、無視できます。

• 外部サービスの要件に一致する言語コードとテキストリストを持つ JSON 本文を返します。

• translatorData フィールドを介してデータを返します。これは応答トランスレーターによって使用されます。この例では、元の入力データを送信しています。応答トランスレーターの入力データの長さを使用して、入力リクエストがいくつあったかを確認します。

リクエストトランスレーターを直接呼び出すことでテストできます。

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."]]}}'));

リクエストトランスレーターは、ボディを外部サービスが期待する形状にします。

{"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."]]
                     }
}

応答トランスレーターを追加する前の応答本文¶

外部サービスからの応答本文は次のようになります。

{"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 }}
                ]
         }
}

応答本文を変換する¶

応答トランスレーターは、外部サービスから返される結果を処理します。結果には、 ErrorList のエラーと ResultList の結果の組み合わせが含まれます。

応答トランスレーターコードは、これらの結果を組み合わせて、外部サービスに渡された行の順序に一致する完全なセットを作成します。応答トランスレーターは、結果をSnowflake形式で返します。

次の SQL は、 awscomprehendresponse_translator トランスレーター関数を作成します。

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

応答トランスレーター関数のコードは、

• translatorData 配列の長さからの入力サイズで responses という配列を初期化します。テスト文字列の元のリストを渡すために、リクエストトランスレーターから応答トランスレーターに translatorData を送信しました。

• エラー以外の各結果をループして、結果リストに入れます。

• エラー結果をループして結果リストに入れます。結果リストには、それがどのエントリであるかを示すインデックス位置があります。生成される結果の順序は、入力の順序と一致する必要があります。結果リストには、感情情報も含まれています。

すべての応答が収集された後、Snowflakeが期待する形式で JSON 本文に返されます。

次の直接テストでは、正しい形式の JSON 本文が返されます。

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 }
                            }
                          ]
            },
        }'
    )
);

トランスレーターを外部関数に割り当て¶

外部関数に、関数名を値として request_translator および response_translator パラメーターに割り当てて、リクエストトランスレーターと応答トランスレーターの関数を追加します。この方法で、これらは外部関数の実行時に自動的に呼び出されます。

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

関数を記述して、それに関する情報を取得できます。

DESCRIBE FUNCTION ComprehendSentiment(VARCHAR);

外部関数を呼び出す¶

外部関数を単一の文で呼び出してテストします。

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

感情分析の結果が表示されます。

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

外部関数を複数の文で呼び出してテストします。以前に作成したものと同じ demo テーブルを使用します。

SELECT ComprehendSentiment(vc), vc FROM demo;

感情分析の結果が表示されます。

外部関数が呼び出されると、リクエストトランスレーターはデータを外部サービスが必要とする形式に自動で変換しました。次に、応答トランスレーターは、外部サービスからの応答をSnowflakeが必要とする形式に自動で変換し直しました。