Google Cloud Spanner 数据库扩展程序

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

版本 2.0.2

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

本文档提供了有关配置和使用此扩展程序的参考信息。在通过 ExtensionCallout 政策从 API 代理中使用扩展程序之前，您必须执行以下操作：

按照创建和管理实例中所述创建 Cloud Spanner 实例，然后创建数据库。
获得实例和数据库后，请向代表扩展程序的 Google Cloud 服务账号授予访问数据库的权限。如需详细了解要使用的角色，请参阅 Cloud Spanner 角色。如需详细了解 Cloud Spanner 访问权限控制，请参阅应用 IAM 角色和 Cloud Spanner 的访问权限控制。
当您拥有一个具有所需数据库访问权限的服务账号后，请使用 Google Cloud 控制台为该服务账号生成密钥。在配置此扩展程序时，请使用生成的密钥 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 的用户的电子邮件地址已更新为新值。已更新 1 行。

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

请求参数

参数	说明	类型	默认值	必需
表格名称	数据库中应更新行的表。	字符串	无。	是。
行	要更新的行数据数组。数组中的每个实体都应包含要更新的行的唯一 ID（例如主键）值。	数组	无。	是。

响应

无。

配置参考文档

在配置和部署此扩展以用于 API 代理时，请使用以下内容。如需了解如何使用 Apigee 控制台配置扩展程序，请参阅添加和配置扩展程序。

常见扩展属性

每个扩展程序都有以下属性。

属性	说明	默认	必需
`name`	您为扩展程序配置此名称。	无	是
`packageName`	Apigee Edge 提供的扩展包的名称。	无	是
`version`	配置扩展程序所用的扩展程序软件包的版本号。	无	是
`configuration`	特定于您要添加的附加信息的配置值。请参阅此扩展程序软件包的属性	无	是

相应扩展程序包的属性

为此扩展程序特有的以下配置属性指定值。

属性	说明	默认	必需
projectId	包含数据库的 Google Cloud 项目的 ID。	无。	是。
instanceId	Google Cloud 项目中 Cloud Spanner 实例的 ID。	无。	是。
databaseId	Cloud Spanner 数据库的 ID。	无。	是。
凭证	在 Apigee Edge 控制台中输入时，这是服务账号密钥文件的内容。如果使用管理 API 发送，则该值是根据服务账号密钥文件生成的 base64 编码值。	无。	是。