使用属性集

本页面适用于 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 文档。

属性集是存储数据的键/值对的自定义集合。API 代理可以在执行时检索此数据。

为何使用属性集？

通常情况下，您可以使用属性集存储不应在 API 代理逻辑中进行硬编码的不过期数据。您可以访问代理中的任何位置的属性集数据，在该代理中可以访问流变量。

属性集的一个常见用例是提供与一个环境或其他环境相关联的值。您可以使用特定于测试环境中运行的代理的配置值创建环境范围的属性集，并为生产环境创建另一个设置。

例如：

  • prod-env.properties 属性集包含属性 log-level=error
  • test-env.properties 属性集包含属性 log-level=debug

同样，您可以存储特定于环境的路由信息：

  • test-env.properties 属性集包含属性 db-url=mydomain.test.datasource.com
  • prod-env.properties 属性集包含属性 db-url=mydomain.prod.datasource.com

属性集范围

在创建属性集时，您可以将属性集的范围限定为 API 代理修订版本或环境。不能将属性集的范围限定为某个组织。

下表说明了 API 代理和环境范围的属性集的行为和管理方式：

范围 运行时行为 管理
API 代理 属性仅可用于包含属性集资源的 API 代理的修订版本。其他 API 代理或同一代理的其他修订版本无法访问该特定属性集。 管理员可以使用 /resourcefiles Apigee API 或界面来创建和修改属性集。在界面中保存 API 代理会创建一个新修订版本，并且修改后的属性集只会与此修订版本关联。
环境 属性可用于该环境中所有 API 代理的所有修订版本。其他环境中的 API 代理无法访问该属性集。 管理员必须使用 /resourcefiles Apigee API 来创建、查看、更新或删除环境范围的属性集。这些属性集不会显示在 Apigee 界面中，也无法在 Apigee 界面中修改。

属性集限制

Apigee 会对属性集施加限制，如限制中所述。此外，属性集文件必须使用与 Java 属性文件相同的语法，但有一个例外：您不能在属性集文件中使用大括号 {}。

创建属性集文件

通常情况下，您将属性集值以名称/值对的形式存储在文件中。属性集文件是 properties 类型的资源文件。

属性集文件支持与 Java 属性文件相同的语法；例如，它们可以包含 Unicode 值，并且可以使用 # 或 ! 字符作为注释标记。 请注意以下例外：您不能在属性集文件中使用大括号 {}。

您必须向属性文件名添加后缀 .properties。例如，允许使用 myconfig.my_key.properties，但不允许使用 myconfig.my_key。

属性集规范的结构为：property_set_name.property_name.properties 属性集名称和属性名称不能包含英文句点。例如，允许使用 myconfig.my_key.properties，但不允许使用 myconfig.my.key.properties 和 my.config.my_key.properties。

以下示例展示了定义了多个属性的简单属性集文件：

# myProps.properties file
# General properties
foo=bar
baz=biff

# Messages/notes/warnings
message=This is a basic message.
note_message=This is an important message.
error_message=This is an error message.

# Keys
publickey=abc123
privatekey=splitwithsoundman

创建属性集文件后，您可以使用界面或 API 将其上传到 Apigee。

使用界面管理属性集

以与管理其他资源相同的方式使用界面管理 API 代理修订版本范围的属性集。如需了解详情，请参阅使用界面管理资源。

使用 API 管理属性集

使用 API 管理 API 代理修订版本或环境范围的属性集，如以下部分所述。

使用 API 创建属性集

以下部分介绍如何使用 API 创建 API 代理修订版本或环境范围的属性集。

使用 API 创建 API 代理修订版本范围的属性集

要使用 API 创建 API 代理修订版本范围的属性集，请执行以下操作：

  1. 创建属性集文件。
  2. 将属性集文件添加到 API 代理配置软件包。
  3. 使用创建 API 代理或更新 API 代理修订版本 API 上传该软件包。

使用 API 创建环境范围的属性集

要使用 API 添加环境范围的属性集，请创建属性集文件，然后通过向以下资源发出 POST 请求将其上传到您组织的环境中：https://apigee.googleapis.com/v1/organizations/{org}/environments/{env}/resourcefiles

在请求中提供以下信息：

  • 将 name 查询参数设置为属性集的名称
  • 将 type 查询参数设置为 properties
  • 将属性集文件的内容作为 application/octet-stream 或 multipart/form-data 传递

以下示例从 /Users/myhome/myprops.properties 文件导入名为 MyPropSet 的属性集：

curl -X POST "https://apigee.googleapis.com/v1/organizations/my-organization/environments/test/resourcefiles?name=MyPropSet&type=properties"
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-type: multipart/form-data" \
  -F file=@/Users/myhome/myprops.properties

$TOKEN 设置为您的 OAuth 2.0 访问令牌，如获取 OAuth 2.0 访问令牌中所述。如需了解此示例中使用的 curl 选项，请参阅使用 curl。

以下提供了一个响应示例。 

{
  "name": "MyPropSet",
  "type": "properties"
}

如需了解详情，请参阅创建资源文件 API。

使用 API 查看属性集

以下部分介绍如何使用 API 查看环境范围的属性集。

使用 API 查看范围限定至某个环境的所有属性集

要使用 API 查看范围限定至某个环境的所有属性集，请向以下资源发出 GET 请求：https://apigee.googleapis.com/v1/organizations/{org}/environments/{env}/resourcefiles/properties

以下示例列出了测试环境中的所有属性集：

curl -X GET "https://apigee.googleapis.com/v1/organizations/my-organization/environments/test/resourcefiles/properties" \
  -H "Authorization: Bearer $TOKEN"

$TOKEN 设置为您的 OAuth 2.0 访问令牌，如获取 OAuth 2.0 访问令牌中所述。如需了解此示例中使用的 curl 选项，请参阅使用 curl。

以下提供了一个响应示例。 

{
  "resourceFile": [
    {
      "name": "MyPropSet",
      "type": "properties"
    }
  ]
}

如需了解详情，请参阅列出环境资源文件 API。

使用 API 查看环境范围的属性集的内容

要使用 API 查看环境范围的属性集的内容，请向以下资源发出 GET 请求：https://apigee.googleapis.com/v1/organizations/{org}/environments/{env}/resourcefiles/properties/name

以下示例显示了测试环境中的 MyPropSet 属性集的内容：

curl -X GET "https://apigee.googleapis.com/v1/organizations/my-organization/environments/test/resourcefiles/properties/MyPropSet" \
  -H "Authorization: Bearer $TOKEN"

$TOKEN 设置为您的 OAuth 2.0 访问令牌，如获取 OAuth 2.0 访问令牌中所述。如需了解此示例中使用的 curl 选项，请参阅使用 curl。

以下提供了一个响应示例。 

# myProps.properties file
# General properties
foo=bar
baz=biff

# Messages/notes/warnings
message=This is a basic message.
note_message=This is an important message.
error_message=This is an error message.

# Keys
publickey=abc123
privatekey=splitwithsoundman

如需了解详情，请参阅列出环境资源文件 API。

使用 API 更新属性集

以下部分介绍如何使用 API 更新 API 代理修订版本或环境范围的属性集。

使用 API 更新 API 代理修订版本范围的属性集

要使用 API 更新 API 代理修订版本范围的属性集，请执行以下操作：

  1. 更新属性集文件。
  2. 使用获取 API 代理修订版本 API 并将各选项设置如下，以下载 API 代理配置软件包：
    • 将 format 查询参数设置为 bundle
    • 将 Accept 标头设置为 application/zip
  3. 将属性集文件添加到 API 代理配置软件包。
  4. 使用更新 API 代理修订版本 API 上传 API 代理配置软件包。

使用 API 更新环境范围的属性集

要使用 API 更新环境范围的属性集，请更新属性集文件，然后通过向以下资源发出 PUT 请求将其上传到您组织的环境中：https://apigee.googleapis.com/v1/organizations/{org}/environments/{env}/resourcefiles/{type}/{name}

在请求中提供以下信息：

  • 将 {type} 设置为 properties
  • 将 {name} 设置为要更新的属性集的名称
  • 将属性集文件的内容作为 application/octet-stream 或 multipart/form-data 传递

以下示例使用 /Users/myhome/myprops-revised.properties 文件的内容更新 MyPropSet 属性集：

curl -X PUT "https://apigee.googleapis.com/v1/organizations/my-organization/environments/test/resourcefiles/properties/MyPropSet"
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-type: multipart/form-data" \
  -F file=@/Users/myhome/myprops-revised.properties

$TOKEN 设置为您的 OAuth 2.0 访问令牌，如获取 OAuth 2.0 访问令牌中所述。如需了解此示例中使用的 curl 选项，请参阅使用 curl。

以下提供了一个响应示例。 

{
  "name": "MyPropSet",
  "type": "properties"
}

如需了解详情，请参阅更新资源文件 API。

使用 API 删除属性集

以下部分介绍如何使用 API 删除 API 代理修订版本或环境范围的属性集。

使用 API 删除 API 代理修订版本范围的属性集

要使用 API 删除 API 代理修订版本范围的属性集，请执行以下操作：

  1. 使用获取 API 代理修订版本 API 并将各选项设置如下，以下载 API 代理配置软件包：
    • 将 format 查询参数设置为 bundle
    • 将 Accept 标头设置为 application/zip
  2. 从 API 代理配置软件包中删除属性集文件。
  3. 使用更新 API 代理修订版本 API 上传 API 代理配置软件包。

使用 API 删除环境范围的属性集

要使用 API 删除环境范围的属性集，请向以下资源发出 DELETE 请求：https://apigee.googleapis.com/v1/organizations/{org}/environments/{env}/resourcefiles/{type}/{name}

在请求中传递以下信息：

  • 将 {type} 设置为 properties
  • 将 {name} 设置为要删除的属性集的名称

以下示例将删除 MyPropSet 属性集：

curl -X DELETE https://apigee.googleapis.com/v1/organizations/my-organization/environments/test/resourcefiles/properties/MyPropSet \
  -H "Authorization: Bearer $TOKEN"

$TOKEN 设置为您的 OAuth 2.0 访问令牌，如获取 OAuth 2.0 访问令牌中所述。如需了解此示例中使用的 curl 选项，请参阅使用 curl。

以下提供了一个响应示例。 

{
  "name": "MyPropSet",
  "type": "properties"
}

如需了解详情，请参阅删除资源文件 API。

访问属性集值

您可以在 API 代理中任何您可以访问流变量的位置访问属性集数据，包括政策、流、JavaScript 代码等。

要访问属性集中的值，请使用以下语法：

propertyset.[property_set_name].[property_name]

其中：

  • property_set_name 是您定义的文件名（如果使用界面）或 name 查询参数的值（如果使用 API）。
  • property_name 是属性的名称。例如，如果您的属性集包含 foo=bar，则 foo 是属性的名称，bar 是值。

例如，在 JavaScript 政策中，使用 getVariable() 方法从属性集获取值：

context.getVariable('propertyset.property_set_name.property_name);

以下示例会获取名为“MyPropSet”的属性集中的 foo 属性的值：

context.getVariable('propertyset.MyPropSet.foo);

您还可以使用 ExtractVariables 政策从属性集获取属性的值，并将其分配给另一个变量，如以下示例所示：

<ExtractVariables name="ExtractVariables-1">
   <DisplayName>Extract a portion of the url path</DisplayName>
   <Source>request</Source>
   <Variable name="propertyset.MyPropSet.foo">
      <Pattern>{myVar}</Pattern>
   </Variable>
   <VariablePrefix>foobar</VariablePrefix>
   <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</ExtractVariables>

在本例中，该政策从 name 特性中读取变量，并将值分配给 Pattern 元素中的变量。

使用分配消息政策动态分配属性集键的值

您可以使用“Assign Message”政策将属性集键的值动态地分配到流变量。如需了解详情，请参阅分配消息政策参考中的 PropertySetRef 说明。

Apigee Hybrid 用户

如果您使用的是 Apigee Hybrid，请注意以下事项：

  1. Hybrid 管理层面验证属性集；如果有效，则属性将存储在管理层面中。
  2. 同步器检索属性集数据并将其本地存储在运行时层面上。
  3. 消息处理器加载下载的属性集，并提供给执行代理。