Google Cloud Spanner Database 拡張機能

バージョン 1.2.1

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

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

  1. インスタンスの作成と管理の説明に従って Cloud Spanner インスタンスを作成し、データベースを作成します。

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

  3. サービス アカウントに目的のデータベースへのアクセスレベルに対するアクセス権限がある場合、GCP Console でサービス アカウントキーを作成します。この拡張機能を構成するときに、生成されたキー 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 Console で拡張機能を構成する手順については、拡張機能の追加と構成をご覧ください。

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

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

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

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

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

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