本頁面由 Cloud Translation API 翻譯而成。

Google Cloud Spanner 資料庫擴充功能

您正在查看 Apigee Edge 說明文件。
前往 Apigee X 說明文件。 info

2.0.0 版

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

這篇文章提供設定和使用此擴充功能的參考資訊。使用 ExtensionCallout 政策中的 API proxy 擴充功能前，您必須：

按照「建立及管理執行個體」一節的說明建立 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 政策會指派 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>

要求參數

參數	說明	類型	預設	必填
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` 參數中的鍵。	字串	無。	是。
參數	物件，其鍵和值是 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>

要求參數

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

回應

無。

設定參考資料

如要設定及部署此擴充功能，以便在 API 代理程式中使用，請使用下列說明。如要瞭解如何使用 Apigee 控制台設定擴充功能，請參閱「新增及設定擴充功能」。

常見的擴充功能屬性

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

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

這個擴充功能套件的屬性

請為下列專屬於此擴充功能的設定屬性指定值。

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