現在、Apigee Edge のドキュメントを表示しています。
Apigee X のドキュメントをご確認ください。 情報
バージョン 1.4.2
Cloud Spanner データベースに対して挿入、クエリ、更新の各オペレーションを実行します。
ここでは、この拡張機能の構成と使用について説明します。ExtensionCallout ポリシーで API プロキシから拡張機能を使用する前に、次のことを行う必要があります。
インスタンスの作成と管理の説明に沿って Cloud Spanner インスタンスを作成し、データベースを作成します。
インスタンスとデータベースを取得したら、拡張機能を表す GCP サービス アカウントにデータベースにアクセスするための権限を付与します。使用するロールの詳細については、Cloud Spanner のロールをご覧ください。Cloud Spanner のアクセス制御について詳しくは、IAM ロールの適用と Cloud Spanner のアクセス制御をご覧ください。
必要なデータベースへのアクセスレベルの権限を持つサービス アカウントがある場合は、GCP Console を使用してサービス アカウント キーを生成します。この拡張機能を構成する場合は、生成されたキー 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>
アクション
挿入
指定された行をデータベースに挿入します。
構文
<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 | 行の挿入先となるデータベース内のテーブル。 | 文字列 | なし。 | はい、できます。 |
行 | 挿入する行。rows JSON オブジェクトで配列として表します。 |
配列 | なし。 | はい、できます。 |
レスポンス
なし。
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 パラメータのキーに対応している必要があります。 |
文字列 | なし。 | はい、できます。 |
params | キーと値が、SQL クエリで使用されるパラメータ名と値であるオブジェクト。ここに複数のパラメータを記載できます。 | オブジェクト | なし。 | 違います |
レスポンス
クエリによって返された列名と値のペアの配列を含む rows
オブジェクト。例:
{
"rows": [
{
"username": "freewill444",
"email": "freewill@example.com"
}
]
}
update
指定したデータでデータベースの行を更新します。
構文
<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 | 行を更新するデータベース内のテーブル。 | 文字列 | なし。 | はい、できます。 |
行 | 更新する行データの配列。配列内の各エンティティには、更新する行の一意の ID(主キーなど)の値が含まれている必要があります。 | 配列 | なし。 | はい、できます。 |
レスポンス
なし。
構成リファレンス
API プロキシで使用するためにこの拡張機能を構成およびデプロイする場合は、以下を使用します。Apigee コンソールを使用して拡張機能を構成する手順については、拡張機能の追加と構成をご覧ください。
共通の拡張プロパティ
すべての拡張機能には次のプロパティがあります。
プロパティ | 説明 | デフォルト | 必須 |
---|---|---|---|
name |
この拡張機能に付ける名前。 | なし | ○ |
packageName |
Apigee Edge から提供された拡張機能パッケージの名前。 | なし | ○ |
version |
拡張機能を構成する拡張機能パッケージのバージョン番号。 | なし | ○ |
configuration |
追加する拡張機能に固有の構成値。この拡張機能パッケージのプロパティをご覧ください。 | なし | ○ |
この拡張機能パッケージのプロパティ
この拡張機能に固有の次の構成プロパティの値を指定します。
プロパティ | 説明 | デフォルト | 必須 |
---|---|---|---|
projectId | データベースを含む GCP プロジェクトの ID。 | なし。 | はい、できます。 |
instanceId | GCP プロジェクト内の Cloud Spanner インスタンスの ID。 | なし。 | はい、できます。 |
databaseId | Cloud Spanner データベースの ID。 | なし。 | はい、できます。 |
証明書 | これは、Apigee Edge コンソールで入力する場合、サービス アカウント キー ファイルの内容です。Management API 経由で送信される場合は、サービス アカウント キー ファイルから生成された、Base64 エンコードの値です。 | なし。 | はい、できます。 |