您正在查看的是 Apigee Edge 文档。
转到 Apigee X 文档。 信息
版本 1.4.1
对 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 政策会分配一个 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>
Action
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 | 数据库中应插入行的表。 | 字符串 | 无。 | 有。 |
行 | 要插入的行在 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 编码值。 | 无。 | 有。 |