Google Cloud Spanner Database 拡張機能

Cloud Spanner データベースで挿入、クエリ、更新操作を行います。

ここでは、この拡張機能を構成して使用する場合のリファレンスを提供します。ExtensionCallout ポリシーで API プロキシ経由で拡張機能を使用する前に、次のことを行う必要があります。

  1. Cloud Spanner インスタンスを作成して、データベースを作成します。詳細については、インスタンスの作成と管理をご覧ください。

  2. データベースにインスタンスを作成したら、拡張機能を表す GCP サービス アカウントにデータベースへのアクセス権限を付与します。使用する役割の詳細については、Cloud Spanner の役割をご覧ください。Cloud Spanner のアクセス制御の詳細については、IAM 役割の適用と Cloud Spanner のアクセス制御をご覧ください。

  3. 必要なデータベースにアクセスできる権限のあるサービス アカウントを持っている場合は、このサービス アカウントにキーを生成します。この拡張機能を構成するときに、生成されたキー JSON ファイルのコンテンツを使用します。

  4. 拡張機能の追加と構成を行うときに、構成リファレンスを使用して、生成されたキーの JSON ファイルのコンテンツを使用します。

Cloud Spanner について

Cloud Spanner は、高可用性、強整合性、およびトランザクション型の読み取りと書き込みを必要とするリレーショナル データや構造化データ、半構造化データに最適です。

Cloud Spanner をこれからお使いになる方には、Cloud Spanner ドキュメントのクイックスタートを最初にご覧になることをおすすめします。

サンプル

次の例は、ExtensionCallout ポリシーを使用して Cloud Spanner 拡張機能アクションのサポートを構成する方法を示しています。

データの追加

次の例では、拡張機能の insert アクションで新しいユーザーをユーザー テーブルに追加しています。

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <ConnectorCallout async="false" continueOnError="true" enabled="true" name="Insert-New-User">
        <DisplayName>Insert New User</DisplayName>
        <Connector>spanner-users-products</Connector>
        <Action>insert</Action>
        <Input><![CDATA[{
            "tableName" : "user",
            "rows" : [{
              "username": "jonesy42",
              "firstName": "Floyd",
              "lastName": "Jones",
              "address": "3695 Auctor Street",
              "city": "Gresham",
              "region": "OR",
              "postalCode": "12693",
              "email": "floydster@example.com"
          }]
      }]]></Input>
    </ConnectorCallout>

データの取得

この例では、クエリで user テーブルからユーザー名とメールアドレスを取得しています。

まず、AssignMessage ポリシーがクエリの WHERE 句で使用する postal.code.value 変数を割り当てています。これはサンプルです。実際のポリシーでは、クライアント リクエストのパラメータに基づいて値を設定するでしょう。

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <AssignMessage async="false" continueOnError="false" enabled="true" name="Assign-Postal-Code">
        <AssignTo createNew="true" transport="http" type="request"/>
        <AssignVariable>
            <Name>postal.code</Name>
            <Value>86519</Value>
        </AssignVariable>
        <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    </AssignMessage>

次の ExtensionCallout ポリシーは、WHERE 句の postal.code.value 変数のコンテンツを使用して、データベースにクエリを実行しています。

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <ConnectorCallout async="false" continueOnError="true" enabled="true" name="Get-User-Data">
        <DisplayName>Get User Data</DisplayName>
        <Connector>spanner-users-products</Connector>
        <Action>querySQL</Action>
        <Input><![CDATA[{
          "sql" : "SELECT username, email FROM user WHERE postalCode = @postalCode",
          "params" : {
            "postalCode" : "{postal.code.value}"
          }
        }]]></Input>
      <Output>spanner.userdata.retrieved</Output>
    </ConnectorCallout>

次の AssignMessage ポリシーでは、クライアントに返すレスポンスとして、spanner.userdata.retrieved 変数に保存された拡張機能のレスポンスを使用しています。

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <AssignMessage async="false" continueOnError="false" enabled="true" name="Get-Query-Response-Data">
        <DisplayName>Get Query Response Data</DisplayName>
        <AssignTo type="response" createNew="false"/>
        <Set>
            <Payload contentType="application/json">{spanner.userdata.retrieved}</Payload>
        </Set>
    </AssignMessage>

この例では、レスポンス データが次のような JSON として返されます。

{
      "rows": [
        {
          "username": "freewill444",
          "email": "freewill@example.com"
        }
      ]
    }

データの更新

この例では、<Input> 要素に username（テーブルの主キー）が含まれ、email 列に新しい値が設定されています。

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <ConnectorCallout async="false" continueOnError="true" enabled="true" name="Update-User-Data">
        <DisplayName>Update User Data</DisplayName>
        <Connector>spanner-users-products</Connector>
        <Action>update</Action>
        <Input><![CDATA[{
            "tableName" : "user",
            "rows": [{
                "username":"Liz456",
                "email":"lizzard@example.com"
            }]
        }]]></Input>
    </ConnectorCallout>

アクション

insert

指定した行をデータベースに挿入します。

構文

<Action>insert</Action>
    <Input><![CDATA[{
      "tableName" : "table-to-insert-into",
      "rows" : "rows-to-insert"
    }]]></Input>

例

次の例では、拡張機能の insert アクションで新しいユーザーをユーザー テーブルに追加しています。1 行が追加されています。

<Action>insert</Action>
    <Input><![CDATA[{
        "tableName" : "user",
        "rows" : [{
          "username": "jonesy42",
          "firstName": "Floyd",
          "lastName": "Jones",
          "address": "3695 Auctor Street",
          "city": "Gresham",
          "region": "OR",
          "postalCode": "12693",
          "email": "floydster@example.com"
      }]
    }]]></Input>

リクエスト パラメータ

パラメータ 説明 型 デフォルト 必須
tableName データベースで行を挿入するテーブル String なし ○
rows 挿入される行。rows JSON オブジェクトの配列で表します。 Array なし ○

レスポンス

なし

querySQL

指定したパラメータを含む SQL 文を使用して、データベースにクエリを実行します。SQL 文のパラメータは名前が @ で始まります。パラメータの値は、このアクションの params パラメータに指定されています。

Cloud Spanner のクエリ構文については、クエリ構文をご覧ください。

構文

<Action>querySQL</Action>
    <Input><![CDATA[{
      "sql" : "sql-query-statement",
      "params" : {
        "param1" : "columnValue"
      }
    }]]></Input>

例

この例では、クエリで user テーブルから username 列と email 列の値を取得しています。SQL 文には、フロー変数 postal.code.value から設定された postalCode パラメータを指定します。

<Action>querySQL</Action>
    <Input><![CDATA[{
      "sql" : "SELECT username, email FROM user WHERE postalCode = @postalCode",
      "params" : {
        "postalCode" : "{postal.code.value}"
      }
    }]]></Input>

リクエスト パラメータ

パラメータ 説明 型 デフォルト 必須
SQL 実行する SQL クエリ。先頭に @ が付いたパラメータ名でパラメータを指定します。これらのパラメータ名は、このアクションの params パラメータのキーに対応している必要があります。 String なし ○
params キーと値が、SQL クエリで使用されるパラメータ名と値になるオブジェクト。複数のパラメータを設定できます。 Object なし ×

レスポンス

クエリで返された列名と値のペアから構成される配列を格納する rows オブジェクト。例:

{
      "rows": [
        {
          "username": "freewill444",
          "email": "freewill@example.com"
        }
      ]
    }

更新

指定されたデータでデータベース内の行を更新します。

構文

<Input><![CDATA[{
      "tableName" : "table-with-rows-to-update",
      "rows" : "rows-to-update"
    }]]></Input>

例

この例では、username が Liz456 のメールアドレスを新しい値で更新しています。1 行が更新されています。

<Action>update</Action>
    <Input><![CDATA[{
      "tableName" : "user",
      "rows": [{
          "username":"Liz456",
          "email":"lizzard@example.com"
      }]
    }]]></Input>

リクエスト パラメータ

パラメータ 説明 型 デフォルト 必須
tableName データベースで行を更新するテーブル String なし ○
rows 更新する行データの配列。配列の各エンティティには、更新する行の一意の ID（主キーなど）が含まれます。 Array なし ○

レスポンス

なし

構成リファレンス

この拡張機能を API プロキシで使用するように構成してデプロイする場合は、次の項目を使用します。Apigee コンソールで拡張機能を構成する手順については、拡張機能の追加と構成をご覧ください。

共通の拡張機能プロパティ

すべての拡張機能には次のプロパティがあります。

プロパティ 説明 デフォルト 必須
name この拡張機能に付ける名前。 なし ○
packageName Apigee Edge から提供された拡張機能パッケージの名前。 なし ○
version 拡張機能を構成する拡張機能パッケージのバージョン番号。 なし ○
configuration 追加する拡張機能に固有の構成値。この拡張機能パッケージのプロパティをご覧ください。 なし ○

この拡張機能パッケージのプロパティ

この拡張機能に固有の次の構成プロパティに値を指定します。

プロパティ 説明 デフォルト 必須
projectId データベースを含む GCP プロジェクトの ID なし ○
instanceId GCP プロジェクトの Cloud Spanner インスタンスの ID なし ○
databaseId Cloud Spanner データベースの ID なし ○
credentials Apigee Edge コンソールで入力する場合は、サービス アカウントのキーファイルの内容です。管理 API で設定する場合は、サービス アカウントのキーファイルから生成された base64 エンコードの値です。 なし ○