此页面由 Cloud Translation API 翻译。

Google Cloud Spanner 数据库扩展程序

您正在查看 Apigee Edge 文档。
前往 Apigee X 文档。信息

版本 2.0.0

对 Cloud Spanner 数据库执行插入、查询和更新操作。

本文档提供了有关配置和使用此扩展程序的参考信息。在使用 ExtensionCallout 政策从 API 代理使用扩展程序之前，您必须满足以下条件：

创建一个 Cloud Spanner 实例（如创建和管理实例中所述），然后创建一个数据库。
创建实例和数据库后，向代表您的扩展程序的 GCP 服务账号授予访问数据库的权限。如需详细了解要使用的角色，请参阅 Cloud Spanner 角色。如需详细了解 Cloud Spanner 访问权限控制，请参阅应用 IAM 角色和 Cloud Spanner 的访问权限控制。
当您拥有一个对所需数据库具有所需访问权限级别的服务账号后，请使用 GCP 控制台为该服务账号生成密钥。在配置此扩展程序时，请使用生成的密钥 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` 参数中的键相对应。	字符串	无。	是。
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 编码值。	无。	是。