Snowpark Container Services: サービスの操作¶

長時間実行サービスの作成¶

CREATE SERVICE を使用して長時間実行サービスを作成します。

• ほとんどの場合、以下のようにインライン仕様を指定してサービスを作成します。

  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:tutorial
         readinessProbe:
           port: 8000
           path: /healthcheck
       endpoints:
       - name: echoendpoint
         port: 8000
         public: true
     $$;
  

  Copy

• Snowflakeステージに格納されているサービス仕様を参照してサービスを作成します。実稼働環境にサービスをデプロイする場合、懸念事項の分離という設計原則を適用し、 CREATE SERVICE コマンドでステージ情報を提供して、以下に示すように、仕様をステージにアップロードすることができます。

  CREATE SERVICE echo_service
    IN COMPUTE POOL tutorial_compute_pool
    FROM @tutorial_stage
    SPECIFICATION_FILE='echo_spec.yaml';
  

  Copy

ジョブサービスの実行¶

EXECUTE JOB SERVICE を使用してジョブサービスを作成します。デフォルトでは、このコマンドは同期的に実行され、ジョブサービスのすべてのコンテナーが終了した後に応答を返します。オプションで ASYNC パラメーターを指定すると、ジョブサービスを非同期に実行できます。

• インライン仕様を使用してジョブサービスを実行します。コマンドは、ジョブの実行が完了するまで待機します。

  EXECUTE JOB SERVICE
     IN COMPUTE POOL tutorial_compute_pool
     FROM SPECIFICATION $$
     spec:
       containers:
       - name: main
         image: /tutorial_db/data_schema/tutorial_repository/my_job_image:latest
         env:
           SNOWFLAKE_WAREHOUSE: tutorial_warehouse
         args:
         - "--query=select current_time() as time,'hello'"
         - "--result_table=results"
     $$;
  

  Copy

  オプションとして、 ASYNC プロパティを使用して、このジョブを非同期に実行することができます。

  EXECUTE JOB SERVICE
     IN COMPUTE POOL tutorial_compute_pool
     NAME = example_job_service
     ASYNC = TRUE
     FROM SPECIFICATION $$
     ...
     $$;
  

  Copy

  非同期ジョブを実行する場合は、このヘルパー関数 <service_name>!SPCS_WAIT_FOR を使用してジョブが完了するまで待機します。

  CALL example_job_service!spcs_wait_for('DONE', 120)
  

  Copy

• ステージ情報を使用してジョブサービスを実行します。

  EXECUTE JOB SERVICE
    IN COMPUTE POOL tutorial_compute_pool
    NAME = example_job_service
    FROM @tutorial_stage
    SPECIFICATION_FILE='my_job_spec.yaml';
  

  Copy

ジョブサービスの複数のレプリカの実行（バッチジョブ）¶

デフォルトでは、EXECUTE JOB SERVICE はジョブを実行するために、コンピューティングプール上で単一のジョブサービスインスタンスを実行します。ただし、コンピューティングプールノード間でワークロードを分散するために、複数のジョブサービスレプリカを実行することを選択することもできます。たとえば、10個のレプリカを使用して1,000万行のデータセットを処理すると、それぞれが100万行を処理することになります。

バッチジョブは、作業を独立したタスクに分割できるシナリオをサポートします。ジョブサービスインスタンス（レプリカとも呼ばれます）ごとに1つずつ、同時に実行できる可能性があります。インスタンスを同時に実行するSnowflakeの能力は、コンピューティングプールのサイズに依存します。

複数のインスタンスでバッチジョブを実行するには、次に示すように EXECUTE JOB SERVICE のオプションの REPLICAS パラメーターを使用します。次の例では、10個のインスタンスでジョブサービスを実行します。

EXECUTE JOB SERVICE
  IN COMPUTE POOL my_pool
  NAME = example_job
  REPLICAS = 10
  FROM SPECIFICATION $$
  spec:
    containers:
    - name: main
      image: my_repo/my_job_image:latest
$$;

REPLICAS パラメーターが EXECUTE JOB SERVICE で指定されている場合、Snowflakeはジョブコンテナで次の2つの環境変数を入力します。

• SNOWFLAKE_JOBS_COUNT:EXECUTE JOB SERVICE で指定された REPLICAS プロパティの値。

• SNOWFLAKE_JOB_INDEX:0から始まる、そのジョブサービスインスタンスの ID。レプリカが3つある場合は、インスタンス IDs は0、1、2になります。

これらの環境変数が提供されることで、ジョブコンテナは入力を分割し、各インスタンスに処理するための特定のパーティションを割り当てることができます。たとえば、10個のジョブレプリカで1,000万行を処理する場合、ジョブインデックス0のインスタンスは1から100万の行を処理し、ジョブインデックス1のインスタンスは100万から200万の行を処理するという具合になります。

SHOW SERVICE INSTANCES IN SERVICE コマンドを使用して、各ジョブサービスインスタンスのステータスを検索します。

DESCRIBE SERVICE コマンドを使用して、ジョブサービスの全体的なステータスを取得します。Snowflakeはジョブサービスの全体なステータスを次のように計算します。

• いずれかのインスタンスが失敗すると、ジョブのステータスは FAILED になります。

• すべてのインスタンスが正常に完了すると、ジョブのステータスは DONE になります。

• 現在実行中のインスタンスがある場合、ジョブのステータスは RUNNING になります。

• それ以外の場合、ジョブサービスのステータスは PENDING です。

仕様テンプレートの使用¶

同じ仕様で複数のサービスを作成したいが、構成が異なる場合があります。たとえば、サービス仕様で 環境変数 を定義し、同じ仕様で環境変数の値が異なる複数のサービスを作成したいとします。

仕様テンプレートのサポートにより、仕様内でフィールド値の変数を定義することができます。サービスを作成するときに、これらの変数に値を指定します。

仕様テンプレートでは、さまざまな仕様フィールドの値として変数を指定します。これらの変数を指定するには、 {{ variable_name }} 構文を使用します。次に、 CREATE SERVICE コマンドで、 USING パラメーターを指定して、これらの変数の値をセットします。

例えば、次の CREATE SERVICE コマンドのインライン仕様テンプレートでは、イメージタグ名に tag_name という変数を使っています。この変数を使って、サービスごとに異なるイメージタグを指定することができます。この例では、 USING パラメーターは、 tag_name 変数を値 latest にセットします。

CREATE SERVICE echo_service
  IN COMPUTE POOL tutorial_compute_pool
  FROM SPECIFICATION $$
  spec:
    containers:
    - name: echo
      image: myorg-myacct.registry.snowflakecomputing.com/tutorial_db/data_schema/tutorial_repository/my_echo_service_image:{{ tag_name }}
        ...
    endpoints:
    - name: ...
      ...
  $$
  USING (tag_name=>'latest');

仕様テンプレートをアカウント内のSnowflakeステージに保存することを選択した場合、 CREATE SERVICE コマンドでテンプレートの場所を指定できます。

CREATE SERVICE echo_service
    IN COMPUTE POOL tutorial_compute_pool
    FROM @STAGE SPECIFICATION_TEMPLATE_FILE='echo.yaml'
    USING (tag_name=>'latest');

USING( var_name=>var_value, [var_name=>var_value, ... ] );

例¶

次の例は、仕様テンプレートを使用してサービスを作成する方法を示しています。これらの例の CREATE SERVICE コマンドはインライン仕様を使っています。

CREATE SERVICE echo_service
   IN COMPUTE POOL tutorial_compute_pool
   MIN_INSTANCES=1
   MAX_INSTANCES=1
   FROM SPECIFICATION_TEMPLATE $$
      spec:
         containers:
         - name: echo
           image: {{ image_url }}
           env:
             SERVER_PORT: {{SERVER_PORT}}
             CHARACTER_NAME: Bob
           readinessProbe:
             port: {{SERVER_PORT}}
             path: /healthcheck
         endpoints:
         - name: echoendpoint
           port: {{SERVER_PORT}}
           public: true
         $$
      USING (image_url=>' "/tutorial_db/data_schema/tutorial_repository/my_echo_service_image:latest" ', SERVER_PORT=>8000 );

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

spec:
 containers:
 - name: echo
   image: /tutorial_db/data_schema/tutorial_repository/my_echo_service_image:latest
   env:
     SERVER_PORT: 8000
     CHARACTER_NAME: Bob
   …

CREATE SERVICE echo_service
  IN COMPUTE POOL tutorial_compute_pool
  MIN_INSTANCES=1
  MAX_INSTANCES=1
  FROM SPECIFICATION_TEMPLATE $$
     spec:
       containers:
       - name: echo
         image: /tutorial_db/data_schema/tutorial_repository/my_echo_service_image:latest
         env: {{env_values}}
         readinessProbe:
           port: {{SERVER_PORT}}    #this and next tell SF to connect to port 8000
           path: /healthcheck
       endpoints:
       - name: echoendpoint
         port: {{SERVER_PORT}}
         public: true
        $$
     USING (env_values=>'{"SERVER_PORT": 8000, "CHARACTER_NAME": "Bob"}' );

spec:
  container:
  - name: main
    image: /tutorial_db/data_schema/tutorial_repository/my_job_image:latest
    env:
      SNOWFLAKE_WAREHOUSE: tutorial_warehouse
    args:
    - "--query=select current_time() as time,'hello'"
    - "--result_table=results"

spec:
  container:
  - name: main
    image: /tutorial_db/data_schema/tutorial_repository/my_job_image:latest
    env:
      SNOWFLAKE_WAREHOUSE: tutorial_warehouse
    args: {{ARGS}}
  $$
  USING (ARGS=>$$["--query=select current_time() as time,'hello'", "--result_table=results"]$$ );

オートスケールの有効化¶

実行中のサービスインスタンス数を自動スケールするようにSnowflakeを構成するには、 CREATE SERVICE コマンドの MIN_INSTANCES および MAX_INSTANCES パラメーターを設定します。また、 ALTER SERVICE を使用してこれらの値を変更することもできます。オートスケーリングは、指定された MAX_INSTANCES が MIN_INSTANCES より大きい場合に発生します。

Snowflakeは、指定されたコンピューティングプール上に最小数のサービスインスタンスを作成することから開始します。その後、Snowflakeは80% CPU のリソースリクエストに基づいて、サービスインスタンス数をスケールアップまたはスケールダウンします。Snowflakeは、現在実行中のすべてのサービスインスタンスの使用データを集約し、コンピュートプール内の CPU 使用率を継続的に監視します。

Snowflakeは、（すべてのサービスインスタンスを合計した） CPU の使用率が80%を超えると、コンピュートプール内に追加のサービスインスタンスをデプロイします。CPU の使用率が 80% を下回ると、Snowflake は実行中のサービスインスタンスを削除してスケールダウンします。Snowflakeは5分間の安定化ウィンドウを使用して、頻繁なスケーリングを防止します。target_instances サービスプロパティは、Snowflakeがスケールしているサービスインスタンスのターゲット数を報告します。

以下のスケーリング動作に注意してください。

• サービスインスタンスのスケーリングは、サービス用に構成された MIN_INSTANCES と MAX_INSTANCES パラメーターによって制約されます。

• スケールアップが必要で、コンピューティングプールノードが別のサービスインスタンスを起動するために必要なリソース容量が不足している場合は、コンピューティングプールの自動スケールをトリガーできます。詳細については、 コンピューティングプールノードの自動スケーリング をご参照ください。

• サービスの作成時に MAX_INSTANCES と MIN_INSTANCES パラメーターを指定しても、サービス仕様ファイルでサービスインスタンスのメモリと CPU 要件を指定しない場合は、自動スケーリングは実行されません。Snowflakeは MIN_INSTANCES パラメーターで指定されたインスタンスの数で開始され、数は自動スケーリングされません。

サービスの中断¶

長時間稼働しているサービスは、コンピューティングプールのリソースを消費し、コストを発生させますが、意味のある作業を行っていない場合には、サービスを中断することができます。どのコンピューティングプールノードでもサービスやジョブがアクティブでない場合、Snowflakeのコンピューティングプール自動中断メカニズムがプールを中断し、コストを削減します。

サービスを中断するには、 ALTER SERVICE ... SUSPEND を明示的に呼び出してサービスを中断するか、 CREATE SERVICE または ALTER SERVICE を使用して AUTO_SUSPEND_SECS プロパティをセットし、Snowflakeが自動的にサービスを中断するまでのアイドル時間を定義します。

AUTO_SUSPEND_SECS プロパティがセットされている場合、Snowflakeはサービスがまだ中断されておらず、アイドル状態が AUTO_SUSPEND_SECS 秒以上続くと、自動的にサービスを中断します。以下の両方が当てはまる場合、サービスはアイドル状態になります。

• 現在、そのサービスへの サービス関数 呼び出しを含むクエリは実行されていません。

• サービスステータスは RUNNING です。

Snowflakeがサービスを中断すると、コンピューティングプール上のすべてのサービスインスタンスがシャットダウンされます。コンピューティングプール上で他のサービスが実行されておらず、コンピューティングプールに対して自動中断が構成されている場合、Snowflakeはコンピューティングプールノードも中断します。そのため、非アクティブなコンピューティングプールのために費用を支払う必要がなくなります。

また、次のことにも注意してください。

• ジョブサービスの自動中断はサポートされていません。

• Snowflakeは現在、サービスのアイドル状態を判断する際に、サービス関数のトラフィックのみを追跡し、イングレスのトラフィックは追跡しないため、パブリックエンドポイントを持つサービスでは自動中断はサポートされません。

サービスの終了¶

サービスを一時停止 (ALTERSERVICE... SUSPEND) またはサービスを停止 (DROP SERVICE) すると、Snowflake はすべてのサービスインスタンスを終了します。同様に、サービスコードをアップグレードする場合（ALTER SERVICE...<fromSpecification> ）、Snowflake は、一度に 1 つのサービスインスタンスを終了して再デプロイすることで、 ローリングアップグレード を適用します。

サービスインスタンスを終了する際、Snowflakeはまず各サービスコンテナに SIGTERM シグナルを送信します。コンテナーには、シグナルを処理し、30秒のウィンドウで優雅にシャットダウンするオプションがあります。そうでない場合は、猶予期間の後、Snowflake はコンテナー内のすべてのプロセスを終了します。

サービスコードの更新とサービスの更新¶

サービス作成後、 ALTER SERVICE...<fromSpecification> コマンドを使用してサービスコードを更新し、サービスを再デプロイします。

まず、変更したアプリケーションコードをイメージリポジトリにアップロードします。次に、 ALTER SERVICE コマンドを実行し、サービス仕様をインラインで提供するか、Snowflakeステージ内の仕様ファイルへのパスを指定します。例:

ALTER SERVICE echo_service
FROM SPECIFICATION $$
spec:
  …
  …
$$;

リクエストを受信すると、Snowflakeは新しいコードを使用してサービスを再展開します。

あなたがサービス・オーナーである場合、 DESCRIBE SERVICE コマンドの出力にはサービス仕様が含まれ、下図のようにイメージ・ダイジェスト（仕様の sha256 フィールドの値）が含まれます。

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

ALTER SERVICE は、サービスとの通信（ サービスの使用 を参照）に影響を与える可能性があります。

• ALTER SERVICE...<fromSpecification> でエンドポイントが削除されたり、エンドポイントを使用するために必要な関連するパーミッションが削除されたりした場合（仕様リファレンスの serviceRoles を参照）、サービスへのアクセスは失敗します。詳しくは、 Using Service をご参照ください。

• アップグレード中は、新しい接続が新しいバージョンにルーティングされる可能性があります。新しいサービス・バージョンに後方互換性がない場合、有効なサービス利用は中断されます。例えば、サービス・ファンクションを使った継続的なクエリは失敗するかもしれません。

サービスの実行に必要な権限（サービス所有者ロール）¶

サービスを作成するロールは サービスの所有者ロール です。サービスはこのロールのコンテキスト内のすべての SQL を実行します。詳細については、 Snowflakeが提供するサービスユーザー認証情報の使用 をご参照ください。

サービスが権限を必要とする場合（例えば、データベースオブジェクトにアクセスしたり、操作を実行したりする場合）、所有者ロールにその権限を付与する必要があります。

サービス間通信では、所有者ロールは宛先サービス上のどのエンドポイントがアクセス可能かを決定します（サービスロール を参照してください）。

サービスの操作に必要な権限¶

あるロールがサービスに対してある操作（例えば、サービスの中断）を実行する必要がある場合、そのロールにはその操作を実行する権限が付与されていなければなりません。

以下のリストは、サービスに対する操作を実行するためにロールに付与できる権限を示しています。

• USAGE ： この権限により、ロールはサービスの SHOW SERVICES および DESCRIBE SERVICE をリストすることができます。この権限はサービスエンドポイントへのアクセスを許可しません。詳細については、 サービスエンドポイントへのアクセスに必要な権限（サービスロール） をご参照ください。

• MONITOR ： この権限により、ロールは、ログやコンテナランタイムステータス情報のような、 サービステレメトリー を調べることができます。詳細については、 SHOW SERVICE CONTAINERS IN SERVICE をご参照ください。

• OPERATE ： この権限により、ロールはサービスを操作することができます。たとえば、長時間実行中のサービスを一時停止、再開、アップグレードしたり、ジョブサービスをキャンセルしたりすることができます。これらの操作の詳細については、 ALTER SERVICE をご参照ください。

• OWNERSHIP ： この権限は、ロールに前述のすべての権限を付与します。また、サービスプロパティを変更し、サービス仕様を調べるためのロール権限も付与されます。DESCRIBE SERVICE の出力には、ロールが OWNERSHIP 権限を持っている場合にのみサービス仕様が含まれます。

各 SQL コマンドリファレンスには、コマンドのアクセス制御要件が記載されています。詳細については、 SHOW SERVICES、 ALTER SERVICE および DROP SERVICE をご参照ください。

サービスにおける将来の付与には、以下のルールが適用されます。

• 作成されていないサービスで、ロールに将来の付与を定義できます。たとえば、以下のコマンドは、ロール（service_admin_role）に将来のサービス（myservice）の MONITOR 権限を付与します。

  GRANT MONITOR ON FUTURE SERVICES IN SCHEMA myschema TO ROLE service_admin_role
  

  Copy

  唯一の例外は、 OWNERSHIP 権限です。将来のサービスに OWNERSHIP 権限を付与することはできません。将来の付与と関連する必要な権限の詳細については、 データベースまたはスキーマオブジェクトに対する将来の許可 を参照してください。

• サービス所有権の移転（ GRANT OWNERSHIP ON FUTURE SERVICES を使用した将来の所有権移転を含む）はサポートされていません。

サービスエンドポイントへのアクセスに必要な権限（サービスロール）¶

サービスは、クライアントがリクエストを送ることでアクセスする1つ以上のエンドポイントを公開することができます。サービスの所有者ロールは、サービスとそのエンドポイントにフルアクセスできます。他のロールがエンドポイントにアクセスできるようにするには、適切な権限を付与する必要があります。Snowflakeは、公開されたエンドポイントへのアクセスを管理するために、サービス仕様で「サービスロール」を定義することをサポートしています。

ロールがサービスロールを必要とする例には、以下のようなものがあります。

• サービス関数 の所有者ロールは、サービス関数が参照するエンドポイントへのアクセスを付与するサービスロールが必要です。そうでなければ、サービス関数を作成することはできません。サービス関数の作成後に、サービス関数の所有者ロールがサービスロールの権限を失った場合、そのサービス関数を使用したクエリは権限エラーで失敗します。

• サービス間通信 では、サービスの所有者ロールは、他のサービスのエンドポイントへのアクセスを付与するサービスロールが、そのエンドポイントを呼び出す必要があります。

• Snowflakeの外部から、サービスによって公開されたパブリックエンドポイントに対して イングレスリクエスト を行うユーザーには、そのエンドポイントへのアクセスを許可するためのサービスロールが付与されているロールを付与する必要があります。

あるロール（some_role とします）がサービスエンドポイントにアクセスできるようにするには、次のようにします。

1. サービスを作成するデータベースとスキーマに USAGE 権限を付与します。これらの権限により、スキーマ内のオブジェクトの名前を解決することができます。この場合、オブジェクトはサービスです。

   例えば、以下のコマンドはロール（some_role）にこれらの USAGE 権限を付与します。

   GRANT USAGE ON DATABASE my_db TO ROLE some_role;
   GRANT USAGE ON SCHEMA my_schema TO ROLE some_role;
   

   Copy

2. エンドポイントへのアクセス許可を持つサービスロールを付与します（GRANT SERVICE ROLE を参照してください）。

   以下のようなオプションがあります。

   • Snowflakeがすべてのサービスに対して作成する定義済みのサービスロールである all_endpoints_usage サービスロールを使用して、サービスが公開するすべてのエンドポイントへのアクセスを付与します。サービスロール名はこの構文を使用します: service-name!service-role。

     GRANT SERVICE ROLE my_service!all_endpoints_usage TO ROLE some_role;
     

     Copy

   • サービスが公開する特定のエンドポイントへのアクセスを付与します。このため、特定のエンドポイントへの権限を持つ1つまたは複数のサービスロールを仕様で定義する必要があります。次に、これらのサービスロールを付与して、きめ細かなエンドポイントアクセスを管理します。

     以下の CREATE SERVICE コマンドでは、インライン仕様で、2つのエンドポイント（ep1とep2）と、ep1エンドポイントのみへのアクセスを付与されるサービスロール（ep1_role）を定義しています。

     USE DATABASE my_db;
     USE SCHEMA my_schema;
     
     
     CREATE SERVICE my_service
     IN COMPUTE POOL tutorial_pool
     FROM SPECIFICATION $$
     spec:
       containers:
       - name: echo
         image: /tutorial_db/data_schema/tutorial_repository/my_echo_service_image:latest
       endpoints:
       - name: ep1
         port: 8000
         public: true
       - name: ep2
         port: 8082
         public: true
     serviceRoles:
     - name: ep1_role
       endpoints:
       - ep1
     $$
     

     Copy

     ep1 エンドポイントへの some_role アクセスを付与するには、 ep1_role サービスロールを以下のように付与します。

     GRANT SERVICE ROLE my_service!ep1_role TO ROLE some_role;
     

     Copy

サービス関数: SQL クエリからのサービスの使用¶

サービス関数とは、 CREATE FUNCTION （Snowpark Container Services） を使用して作成するユーザー定義関数（UDF）のことです。しかし、 UDF のコードを直接記述する代わりに、 UDF をサービスエンドポイントに関連付けます。サービス関数は、 HTTP プロトコルをサポートするサービスエンドポイントにのみ関連付けることができることに注意してください（spec.endpoints フィールド（オプション） を参照してください）。

たとえば、 チュートリアル1 では、サービス仕様で定義された1つのエンドポイント（echoendoint）を公開する echo_service という名前のサービスを作成します。

spec:
…
  endpoints:
  - name: echoendpoint
    port: 8080

echoendpoint は、対応するポート（8080）を表す分かりやすいエンドポイント名です。このサービスエンドポイントと通信するには、次に示すように SERVICE と ENDPOINT パラメーターを指定してサービス関数を作成します。

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

AS パラメーターは、サービスコードへの HTTP パスを提供します。このパス値はサービスコードから取得します（例: チュートリアル 1 のservice.pyを参照）。例えば、以下のコード行は チュートリアル 1 の service.py にあります。

@app.post("/echo")
def echo():
...

次のような SELECT ステートメントでサービス関数を呼び出します。

SELECT service_function_name(<parameter-list>);

Snowflakeはリクエストを関連するサービスエンドポイントとパスに誘導します。

"Alex", "2014-01-01 16:00:00"
"Steve", "2015-01-01 16:00:00"
…

SELECT service_func(col1, col2) FROM input_table;

{
   "data":[
      [
         0,
         "Alex",
         "2014-01-01 16:00:00"
      ],
      [
         1,
         "Steve",
         "2015-01-01 16:00:00"
      ],
      …
      [
         <row_index>,
         "<column1>",
         "<column2>"
      ],
   ]
}

{
   "data":[
      [0, "a"],
      [1, "b"],
      …
      [ row_index,  output_column1]
   ]
}

ALTER FUNCTION my_echo_udf(VARCHAR) SET
   MAX_BATCH_ROWS = 15
   MAX_BATCH_RETRIES = 5;

USE ROLE service_owner;
GRANT USAGE ON DATABASE service_db TO ROLE func_owner;
GRANT USAGE ON SCHEMA my_schema TO ROLE func_owner;
GRANT SERVICE ROLE ON service service_db.my_schema.my_service!all_endpoints_usage TO ROLE func_owner;
USE ROLE func_owner;
CREATE OR REPLACE test_udf(v VARCHAR)
  RETURNS VARCHAR
  SERVICE=service_db.my_schema.my_service
  ENDPOINT=endpointname1
  AS '/run';

SELECT test_udf(col1) FROM some_table;

ALTER FUNCTION test_udf(VARCHAR) SET
  SERVICE = service_db.other_schema.other_service
  ENDPOINT=anotherendpoint;

GRANT USAGE ON DATABASE service_db TO ROLE func_user;
GRANT USAGE ON SCHEMA my_schema TO ROLE func_user;
GRANT USAGE ON FUNCTION test_udf(varchar) TO ROLE func_user;
USE ROLE func_user;
SELECT my_test_udf('abcd');

イングレス:Snowflake外部からのサービスの使用¶

サービス仕様の中で1つ以上のエンドポイントをパブリックとして宣言することで、ユーザーがパブリックからサービスを利用できるようになります。ユーザーは、サービスを作成したのと同じSnowflakeアカウントのSnowflakeユーザーでなければならないことに注意してください。

spec:
  ...
  endpoints:
  - name: <endpoint name>
    port: <port number>
    public: true

イングレスは HTTP エンドポイントでのみ許可されていることに注意してください（spec.endpoints フィールド（オプション） を参照してください）。

サービス間通信¶

サービスインスタンスは、 TCP （HTTP を含む）を介して相互に直接通信することができます。これは、同じサービスに属するインスタンスにも、異なるサービスに属するインスタンスにも当てはまります。

インスタンスは、サービス仕様で宣言された エンドポイント でのみ通信（リクエスト）を受信できます。クライアント（リクエストを送信するサービス）は、そのエンドポイントに接続するために必要なロールと付与を持っていなければなりません（サービスエンドポイントへのアクセスに必要な権限（サービスロール） を参照してください）。

• デフォルトでは、サービスインスタンスは宣言されたエンドポイントで同じサービスの他のインスタンスに接続できます。広い意味では、サービスの 所有者ロール は、同じオーナーロールを持つサービスのエンドポイントに接続する権限を持っています。

• クライアントサービスが異なる所有者ロールを持つサービスのエンドポイントに接続するには、クライアントサービスの所有者ロールが、そのエンドポイントを呼び出すために、別のサービスのエンドポイントへのアクセスを付与する サービスロール が必要です。詳細については、 サービスエンドポイントへのアクセスに必要な権限（サービスロール） をご参照ください。

• サービス同士が通信できないようにする場合（セキュリティなどの理由により）は、異なるSnowflakeロールを使用してこれらのサービスを作成します。

サービス・インスタンスには、サービス・アドレス（IP）またはサービス・インスタンス・アドレス（IP）のいずれかを使用してアクセスできます。

• サービス IP アドレスを使ったリクエストはロードバランサーにルーティングされ、ロードバランサーはランダムに選ばれたサービスインスタンスにリクエストをルーティングします。

• サービスインスタンス IP アドレスを使用したリクエストは、特定のサービスインスタンスに直接ルーティングされます。portRange フィールドを使用して定義されたエンドポイントに接続する場合は、サービスインスタンス IP を使用する必要があります（ spec.endpoints フィールド（オプション） を参照）。

どちらの IP アドレスも、Snowflake が各サービスに自動的に割り当てる DNS 名を使用して検出可能です。なお、 DNS を使って特定のインスタンスに接続することはできません。例えば、サービスインスタンス DNS 名を使用して URL を構築することは意味がありません。なぜなら、サービスインスタンス DNS 名を使用して特定のサービスインスタンスをリファレンスする方法がないからです。

2025_01 動作変更バンドル が有効な場合、 SHOW SERVICE INSTANCES IN SERVICE コマンドの出力にサービスインスタンス IP アドレスが表示されます。

サービス間通信の例については、 チュートリアル4 をご参照ください。

サービス間の通信を可能にするためだけにサービスエンドポイントを作成する場合は、 TCP プロトコルを使用する必要があることに注意してください（spec.endpoints フィールド（オプション） を参照）。

<service-name>.<hash>.svc.spcs.internal

instances.<service-name>.<hash>.svc.spcs.internal

Snowflakeのシークレットを指定する¶

Snowflakeのシークレットを名前または参照で指定します（参照はNative Applicationシナリオでのみ適用可能です）。

• Snowflake のシークレットを名前で渡す: snowflakeSecret フィールドの値としてシークレット名を渡すことができます。

  ...
  secrets:
  - snowflakeSecret:
      objectName: '<secret-name>'
    <other info about where in the container to copy the secret>
    ...
  

  Copy

  なお、 snowflakeSecret の値として、 <secret-name> を直接指定することもできます。

• Snowflakeシークレットをリファレンスで渡す: Snowpark Container Services を使用してNative App（コンテナー付きアプリ）を作成する場合、アプリのプロデューサーとコンシューマーは異なる Snowflake アカウントを使用します。場合によっては、インストールされた Snowflake Native Appは、 APPLICATION オブジェクトの外部に存在するコンシューマーカウントの既存のオブジェクトにアクセスする必要があります。この場合、開発者は「secrets by reference（参照によるシークレット）」指定構文を使用して、図のように認証情報を扱うことができます。

  containers:
  - name: main
    image: <url>
    secrets:
    - snowflakeSecret:
        objectReference: '<reference-name>'
      <other info about where in the container to copy the secret>
  

  Copy

  この仕様では、シークレットの参照名を提供するために、 objectName の代わりに objectReference を使用していることに注意してください。

コンテナー内のシークレットの配置を指定する¶

Snowflakeには、シークレットを環境変数としてコンテナーに配置するか、ローカルコンテナーファイルに書き込むように指示することができます。

containers:
- name: main
  image: <url>
  secrets:
  - snowflakeSecret: <secret-name>
    secretKeyRef: username | password | secret_string |  'access_token'
    envVarName: '<env-variable-name>'

CREATE SECRET testdb.testschema.my_secret_object
  TYPE = password
  USERNAME = 'snowman'
  PASSWORD = '1234abc';

containers:
- name: main
  image: <url>
  secrets:
  - snowflakeSecret: testdb.testschema.my_secret_object
    secretKeyRef: username
    envVarName: LOGIN_USER
  - snowflakeSecret: testdb.testschema.my_secret_object
    secretKeyRef: password
    envVarName: LOGIN_PASSWORD

CREATE SECRET testdb.testschema.my_secret
  TYPE=generic_string
  SECRET_STRING='
       some_magic: config
  ';

containers:
- name: main
  image: <url>
  secrets:
  - snowflakeSecret: testdb.testschema.my_secret
    secretKeyRef: secret_string
    envVarName: GENERIC_SECRET

containers:
- name: <name>
  image: <url>
  ...
  secrets:
  - snowflakeSecret: <snowflake-secret-name>
    directoryPath: '<local directory path in the container>'

CREATE SECRET testdb.testschema.my_secret_object
  TYPE = password
  USERNAME = 'snowman'
  PASSWORD = '1234abc';

containers:
- name: main
  image: <url>
  secrets:
  - snowflakeSecret: testdb.testschema.my_secret_object
    directoryPath: '/usr/local/creds'

CREATE SECRET testdb.testschema.my_secret
  TYPE=generic_string
  SECRET_STRING='
       some_magic: config
  ';

containers:
- name: main
  image: <url>
  secrets:
  - snowflakeSecret: testdb.testschema.my_secret
    directoryPath: '/usr/local/creds'

CREATE SECRET testdb.testschema.oauth_secret
  TYPE = OAUTH2
  OAUTH_REFRESH_TOKEN = '34n;vods4nQsdg09wee4qnfvadH'
  OAUTH_REFRESH_TOKEN_EXPIRY_TIME = '2023-12-31 20:00:00'
  API_AUTHENTICATION = my_integration;

containers:
- name: main
  image: <url>
  secrets:
  - snowflakeSecret: testdb.testschema.oauth_secret
    directoryPath: '/usr/local/creds'