Google Cloud Spanner Database 拡張機能

バージョン 1.2.1

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

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

インスタンスの作成と管理の説明に従って Cloud Spanner インスタンスを作成し、データベースを作成します。
インスタンスとデータベースを作成したら、拡張機能を表す GCP サービスアカウントにデータベースにアクセスするための権限を付与します。使用するロールの詳細については、Cloud Spanner のロールをご覧ください。Cloud Spanner のアクセス制御の詳細については、IAM ロールの適用と Cloud Spanner のアクセス制御をご覧ください。
サービスアカウントに目的のデータベースへのアクセスレベルに対するアクセス権限がある場合、GCP Console でサービスアカウントキーを作成します。この拡張機能を構成するときに、生成されたキー JSON ファイルのコンテンツを使用します。
拡張機能の追加と構成を行うときに、構成リファレンスを使用して、生成されたキーの 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 Console で拡張機能を構成する手順については、拡張機能の追加と構成をご覧ください。

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

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

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

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

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

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

Google Cloud Spanner Database 拡張機能

Cloud Spanner について

例

データの追加

データの取得

データの更新

アクション

insert

構文

例

リクエスト パラメータ

レスポンス

querySQL

構文

例

リクエスト パラメータ

レスポンス

更新

構文

例

リクエスト パラメータ

レスポンス

構成リファレンス

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

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

リクエストパラメータ

リクエストパラメータ

リクエストパラメータ