Google Cloud Spanner 数据库扩展程序

<ph type="x-smartling-placeholder"></ph> 您正在查看 Apigee Edge 文档。
转到 Apigee X 文档
信息

<ph type="x-smartling-placeholder">

版本 1.4.1

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

本文提供了配置和使用此扩展程序的参考信息。 在使用 ExtensionCallout 政策,您必须:

  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>

操作

<ph type="x-smartling-placeholder">

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 表中检索 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 的用户的电子邮件地址更新了新值。已更新一行。

<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。 无。 是。
数据库 ID Cloud Spanner 数据库的 ID。 无。 是。
凭据 在 Apigee Edge 控制台中输入时,这是服务账号密钥文件的内容。通过 Management API 发送时,此值为根据服务账号密钥文件生成的 base64 编码值。 无。 是。