注意:此产品的某些方面处于 Beta 版阶段。Hybrid 安装选项是 GA。要加入 Beta 版计划,请与您的 Apigee 代表联系。

使用属性集

属性集是存储数据的键/值对的自定义集合。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 值,并且可以使用 #! 字符作为注释标记。

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

# 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-streammultipart/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
  

按照获取 OAuth 2.0 访问令牌中的说明,将 $TOKEN 设置为您的 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"
  

按照获取 OAuth 2.0 访问令牌中的说明,将 $TOKEN 设置为您的 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"
  

按照获取 OAuth 2.0 访问令牌中的说明,将 $TOKEN 设置为您的 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-streammultipart/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
  

按照获取 OAuth 2.0 访问令牌中的说明,将 $TOKEN 设置为您的 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"
  

按照获取 OAuth 2.0 访问令牌中的说明,将 $TOKEN 设置为您的 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);
名称。例如:

context.getVariable('propertyset.myprops.properties.foo);

您还可以使用 ExtractVariables 政策从属性集获取属性的值,如以下示例所示:

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

使用分配消息政策动态创建属性集

您可以使用分配消息政策动态创建属性集。如需了解详情,请参阅分配消息政策参考中的 PropertySetRef 说明。

Apigee Hybrid 用户

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

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