Google Cloud Spanner 資料庫擴充功能

您目前查看的是 Apigee Edge 說明文件。
前往 Apigee X 說明文件。 info

2.0.2 版

對 Cloud Spanner 資料庫執行插入、查詢和更新作業。

這項內容提供設定及使用此擴充功能的參考資料。使用 ExtensionCallout 政策從 API Proxy 使用擴充功能之前，請務必完成下列步驟：

如「建立及管理執行個體」一文所述，建立 Cloud Spanner 執行個體，並建立資料庫。
建立執行個體和資料庫後，請授予權限，讓代表擴充功能的 Google Cloud 服務帳戶存取資料庫。如要進一步瞭解要使用的角色，請參閱「Cloud Spanner 角色」。如要進一步瞭解 Cloud Spanner 存取權控管，請參閱「套用 IAM 角色」和「Cloud Spanner 的存取權控管」。
如果服務帳戶具備您想要的資料庫存取權層級，請使用 Google Cloud 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 政策會指派 postal.code.value 變數，供查詢 WHERE 子句使用。舉例來說，您的政策可能會根據用戶端要求參數設定值。

<?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 動作會將新使用者新增至使用者資料表。系統會新增一列。

<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>

要求參數

參數	說明	類型	預設	必填
表格名稱	資料庫中要插入資料列的資料表。	字串	無。	是。
列	要插入的資料列，以 `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 的使用者電子郵件地址，已更新一列。

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

要求參數

參數	說明	類型	預設	必填
表格名稱	資料庫中的資料表，其中應更新資料列。	字串	無。	是。
列	要更新的資料列資料陣列。陣列中的每個實體都應包含要更新的資料列專屬 ID (例如主鍵) 值。	陣列	無。	是。

回應

無。

設定參考資料

設定及部署這個擴充功能，以便在 API Proxy 中使用時，請參考下列資訊。如要瞭解如何使用 Apigee 控制台設定擴充功能，請參閱「新增及設定擴充功能」。

常見的擴充功能屬性

每個擴充功能都有下列屬性。

屬性	說明	預設	必要
`name`	您要為這項擴充功能設定的名稱。	無	相容
`packageName`	Apigee Edge 指定的擴充功能套件名稱。	無	相容
`version`	擴充功能的擴充功能套件版本號碼。	無	相容
`configuration`	您要新增的擴充功能專屬的設定值。請參閱「這個擴充功能套件的屬性」一文	無	相容

這個擴充套件的屬性

指定下列設定屬性的值，這些屬性專屬於這個擴充功能。

屬性	說明	預設	必填
projectId	包含資料庫的 Google Cloud 專案 ID。	無。	是。
instanceId	Google Cloud 專案中的 Cloud Spanner 執行個體 ID。	無。	是。
databaseId	Cloud Spanner 資料庫的 ID。	無。	是。
憑證	在 Apigee Edge 控制台中輸入時，這是服務帳戶金鑰檔案的內容。透過 Management API 傳送時，這是從服務帳戶金鑰檔案產生的 base64 編碼值。	無。	是。