Google Cloud Spanner 数据库扩展程序

您正在查看的是 Apigee Edge 文档。
转到 Apigee X 文档
信息

版本 1.4.1

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

本文内容提供了有关配置和使用此扩展程序的参考信息。在采用 ExtensionCallout 政策通过 API 代理使用扩展程序之前,您必须完成以下操作:

  1. 按照创建和管理实例中的说明创建一个 Cloud Spanner 实例,并创建数据库。

  2. 拥有实例和数据库后,向代表您的扩展程序的 GCP 服务账号授予访问数据库的权限。如需详细了解要使用的角色,请参阅 Cloud Spanner 角色。如需详细了解 Cloud Spanner 访问权限控制,请参阅应用 IAM 角色Cloud Spanner 访问权限控制

  3. 如果您有一个服务帐号拥有所需数据库访问权限级别的权限,请使用 GCP Console 为该服务帐号生成密钥。配置此扩展程序时,请使用所生成的密钥 JSON 文件的内容。

  4. 在通过配置参考添加和配置扩展程序时,使用所得到的 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 表中检索 usernameemail 列值。此 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 编码值。 无。 有。