ステップ2: コンソールでプロキシサービス(Google Cloud API Gateway)を作成する

Snowflakeは、データ(HTTP POST リクエスト)をリモートサービスに直接送信しません。代わりに、Snowflakeは、Snowflakeからのデータをリモートサービス(つまり、GCP Cloud Function)に中継するプロキシサービスにデータを送信し、またプロキシサービスからデータを受信します。

このトピックでは、外部関数のプロキシサービスとして使用するGoogle Cloud API Gatewayを作成および設定する手順について説明します。

このトピックの内容:

API定義を作成する

ローカルファイルシステムで、作成するAPIを指定するYAML形式の構成ファイルを作成してカスタマイズします。ファイルの拡張子は .yaml または .yml である必要があります。

構成ファイルテンプレート:

swagger: '2.0'
info:
  title: API Gateway config for Snowflake external function.
  description: This configuration file connects the API Gateway resource to the remote service (Cloud Function).
  version: 1.0.0
schemes:
  - https
produces:
  - application/json
paths:
  /<PATH>:
    post:
      summary: Echo the input.
      operationId: echo
      x-google-backend:
        address: <HTTP ENDPOINT TO ROUTE REQUEST TO>
        protocol: h2
      responses:
        '200':
          description: <DESCRIPTION>
          schema:
            type: string

次のフィールドを入力または更新します。

  1. <PATH> を一意の名前に置き換えます。これはURLsに組み込まれるため、URLsで有効な文字のみを使用してください。たとえば、 demo-func-resource と入力します。

    この構成ファイルの他のフィールドとは異なり、コロンの後ではなく、コロンの前に <PATH> の値を入力する必要があることに注意してください。たとえば、次は適切です。

    paths:
      /demo-func-resource:
    

    パス名には、 パスパラメーター を含めることはできません。Googleは、 パスをURLに設定するときに、パスパラメーターをサポートします。ただし、Snowflakeは、CREATE EXTERNAL FUNCTIONステートメントで指定された対応するURLのパスパラメーターをサポートしていません。)

  2. すぐ前のステップでのパス(例: demo-func-resource)を追跡ワークシートの「Path Suffix」フィールドにコピーします。

  3. x-google-backend フィールドの下にある address フィールドを見つけ、 <HTTP ENDPOINT TO ROUTE REQUEST TO> を追跡ワークシートの「Cloud Functiont Trigger URL」フィールドの値に置き換えます。結果は次のようになります。

    x-google-backend:
      address: https:// ...
    

    URLを引用符で囲むことはできません。

    URL はGoogleがホストするエンドポイントである必要はありません。任意の HTTP エンドポイントへのパスにすることができます。

    ステップ1: コンソールでリモートサービスを作成する(Google Cloud Function)Require HTTPS を選択した場合は、 address フィールドに入力する URL が https で始まることを確認してください。

  4. オプションで、次のいずれの値も更新することができます。

    • info セクションの title

    • info セクションの description

    • paths セクションの post サブセクションの operationId

    • paths セクションの post サブセクションの summary

  5. サンプル構成ファイルを確認します。次のようになります。

    swagger: '2.0'
    info:
      title: "API Gateway config for Snowflake external function"
      description: "This configuration file connects the API Gateway resource to the remote service (Cloud Function)."
      version: 1.0.0
    schemes:
      - https
    produces:
      - application/json
    paths:
      /demo-func-resource:
        post:
          summary: "echo the input"
          operationId: echo
          x-google-backend:
            address: https://my_dev.cloudfunctions.net/demo-cloud-function-01
            protocol: h2
          responses:
            '200':
              description: echo result
              schema:
                type: string
    

    注釈

    この構成では、このチュートリアルの ステップ5: コンソールでプロキシサービスの GCP セキュリティポリシーを作成する で保護するまで、ゲートウェイは一般に公開されたままになります。

  6. オプションで、それまでの間誰もゲートウェイを使用できないようにするには、このオプションのステップで説明するように、仮の無効なサービスアカウント名(google_service_account)を使用するセキュリティ定義を構成ファイルに追加します。このステップでこのセキュリティ定義を追加すると、 ステップ5: コンソールでプロキシサービスの GCP セキュリティポリシーを作成する でセキュリティの構成が完了するまで、外部関数をテストできなくなります。具体的には、 ステップ4: Snowflakeで GCP 用の外部関数を作成する で外部関数をテストする命令はまだ機能しません。

    1. securityDefinitions セクションを構成ファイルの schemes セクションのすぐ上に、同じインデントレベルで追加します。

      securityDefinitions:
        <security-def-name>:
          authorizationUrl: ""
          flow: "implicit"
          type: "oauth2"
          x-google-issuer: "google_service_account"
          x-google-jwks_uri: "https://www.googleapis.com/robot/v1/metadata/x509/google_service_account"
      
      • <セキュリティ定義名> を一意のセキュリティ定義名(例: snowflakeAccess01)に置き換えます。

      • この名前を追跡ワークシートの「Security Definition Name」フィールドに記録します。

    2. 上記で作成したセキュリティ定義を参照するように、構成ファイルの post: セクションを更新します。 operationId フィールドの下に、次を追加します。

      security:
        - <security-def-name>: []
      
      • operationId フィールドと同じレベルでインデントされていることを確認します。

      • <セキュリティ定義名> を追跡ワークシートの「Security Definition Name」フィールドの値に置き換えます。

      • 上記のように、セキュリティ定義名の前にハイフンと空白を含めるようにします。

      • コロンの後に空の角括弧([])を必ず含めてください。

      例:

      paths:
        /demo-func-resource:
          post:
            summary: "echo the input"
            operationId: echo
            security:
              - snowflakeAccess01: []
            x-google-backend:
              address: https://my_dev.cloudfunctions.net/demo-cloud-function-01
              protocol: h2
      
  7. 構成ファイルを保存します。

  8. 追跡ワークシートの「Configuration File Name」フィールドにファイルのパスと名前を記録します。

API構成ファイルの詳細については、次のGCPドキュメントをご参照ください。

API Gatewayを作成する

API Gatewayを作成するには:

  1. GCPAPIを作成します。

  2. API Configを作成します。

  3. API ConfigでGatewayを作成します。

GCPAPIを作成する

このステップでは、 GCP API を作成します。これは、1つ以上のAPI Gatewayと1つ以上の構成ファイルを含むことができるコンテナーです。

  1. まだそうしていない場合は、GCPメニューをクリックして API Gateway を選択し、 Google Cloud API Gateway 画面に移動します。

  2. CREATE GATEWAY をクリックします。

  3. Display NameAPI ID を入力します(例: demo-api-display-name-for-external-function1demo-api-id-for-external-function1)。

    外部関数の作成では後でこれらを入力する必要がないため、追跡ワークシートにこれらの値を記録する必要はありません。ただし、API IDを記録して、使い終わったら削除できるようにすることもできます。

API Configを作成する

構成ファイルをコンソールにアップロードすると、 API Config が作成されます。

  1. 画面の API Config セクションまでスクロールします。

  2. Upload an API Spec を含むフィールドを検索します。

    BROWSE をクリックして、構成ファイルを選択します。構成ファイルの名前は、追跡ワークシートの「Configuration File Name」フィールドに記録されています。

  3. Display Name を含むフィールドに表示名を入力します。

  4. サービスアカウントを選択します。

    サンプル関数を作成した場合は、 Select a Service Account を含むフィールドで App Engine default service account を選択します。

    (サンプルとしてではなく)実稼働環境で使用する関数を作成している場合は、別のサービスアカウントを選択することもできます。

    選択したサービスアカウントには、Cloud Functionを呼び出す権限など、適切な権限が必要です。

API ConfigでGatewayを作成する

  1. 画面の Gateway details セクションまでスクロールします。

  2. 新しい API Gatewayの Display Name を入力します。

  3. Location フィールドをクリックして、適切なリージョン(例: us-central1)を選択します。

  4. CREATE GATEWAY をクリックします。

    これにより、 APIs 画面が表示され、 APIs のリストが表示されます。

    新しいAPIがすぐに表示されない場合は、数分待ってから Refresh ボタンをクリックします。

  5. APIの Managed Service の値を追跡ワークシートの「Managed Service Identifier」フィールドにコピーします。

  6. この時点で、APIsのリストが表示されます。API の名前をクリックします。

    OVERVIEWDETAILSCONFIGS、および GATEWAYS のタブ4つが表示されます。

  7. GATEWAYS タブをクリックします。

  8. Gateway URL をワークシートの「Gateway Base URL」フィールドにコピーします。