使用属性集

本页面适用于 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 is set to your OAuth 2.0 access token, as described in Obtaining an OAuth 2.0 access token. For information about the curl options used in this example, see Using curl.

The following provides an example of the response. 

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

For more information, see Create resource file API.

View property sets using the API

The following sections describe how to view property sets scoped to an environment using the API.

View all property sets scoped to an environment using the API

To view all property sets scoped to an environment using the API, issue a GET request to the following resource: https://apigee.googleapis.com/v1/organizations/{org}/environments/{env}/resourcefiles/properties

The following example lists all property sets in the test environment:

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

$TOKEN is set to your OAuth 2.0 access token, as described in Obtaining an OAuth 2.0 access token. For information about the curl options used in this example, see Using curl.

The following provides an example of the response. 

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

For more information, see List environment resource files API.

View the contents of a property set scoped to an environment using the API

To view the contents of a property set scoped to an environment using the API, issue a GET request to the following resource: https://apigee.googleapis.com/v1/organizations/{org}/environments/{env}/resourcefiles/properties/name

The following example displays the contents of the MyPropSet property set in the test environment:

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

$TOKEN is set to your OAuth 2.0 access token, as described in Obtaining an OAuth 2.0 access token. For information about the curl options used in this example, see Using curl.

The following provides an example of the response. 

# 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

For more information, see List environment resource files API.

Update property sets using the API

The following sections describe how to update property sets scoped to an API proxy revision or environment using the API.

Update property sets scoped to an API proxy revision using the API

To update a property set that is scoped to an API proxy revision using the API:

  1. Update the property set file.
  2. Download the API proxy configuration bundle using the Get API proxy revision API with the following options:
    • Set the format query parameter to bundle
    • Set the Accept header to application/zip
  3. Add the property set file to the API proxy configuration bundle.
  4. Upload the API proxy configuration bundle using the Update API proxy revision API.

Update property sets scoped to an environment using the API

To update a property set that is scoped to an environment using the API, update the property set file and then upload it to an environment in your organization by issuing a PUT request to the following resource: https://apigee.googleapis.com/v1/organizations/{org}/environments/{env}/resourcefiles/{type}/{name}

Include the following information with your request:

  • Set {type} to properties
  • Set {name} to the name of the property set that you want to update
  • Pass the contents of the property set file as application/octet-stream or multipart/form-data

The following example updates the MyPropSet property set using the contents of the /Users/myhome/myprops-revised.properties file: 

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 is set to your OAuth 2.0 access token, as described in Obtaining an OAuth 2.0 access token. For information about the curl options used in this example, see Using curl.

The following provides an example of the response. 

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

For more information, see Update resource file API.

Delete property sets using the API

The following sections describe how to delete property sets scoped to an API proxy revision or environment using the API.

Delete property sets scoped to an API proxy revision using the API

To delete a property set that is scoped to an API proxy revision using the API:

  1. Download the API proxy configuration bundle using the Get API proxy revision API with the following options:
    • Set the format query parameter to bundle
    • Set the Accept header to application/zip
  2. Delete the property set file from the API proxy configuration bundle.
  3. Upload the API proxy configuration bundle using the Update API proxy revision API.

Delete property sets scoped to an environment using the API

To delete a property set scoped to an environment using the API, issue a DELETE request to the following resource: https://apigee.googleapis.com/v1/organizations/{org}/environments/{env}/resourcefiles/{type}/{name}

Pass the following information with your request:

  • Set {type} to properties
  • Set {name} to the name of the property set that you want to delete

The following example deletes the MyPropSet property set:

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

$TOKEN is set to your OAuth 2.0 access token, as described in Obtaining an OAuth 2.0 access token. For information about the curl options used in this example, see Using curl.

The following provides an example of the response. 

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

For more information, see Delete resource file API.

Access property set values

Access property set values anywhere in an API proxy where you can access flow variables: in policies, flows, JavaScript code, and so on.

To access values in a property set, use the following syntax:

propertyset.[property_set_name].[property_name]

Where:

  • property_set_name is the filename that you defined (if you used the UI) or the value of the name query parameter (if you used the API).
  • property_name is the name of the property. For example, if your property set contains foo=bar, foo is the name of the property and bar is the value.

For example, in a JavaScript policy, use the getVariable() method to get a value from a property set:

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

The following example gets the value of the foo property in the property set named "MyPropSet":

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

You can also use the ExtractVariables policy to get the value of a property from a property set and assign it to another variable, as the following example shows:

<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>

In this example, the policy reads the variable from the attribute name, and assigns the value to the variable in the Pattern element.

Assign the value of a property set key dynamically using the Assign Message policy

You can use the Assign Message policy to assign the value of property set key to a flow variable dynamically. For details, see the PropertySetRef description in the Assign Message policy reference.

For Apigee hybrid users

If you are using Apigee hybrid, note the following:

  1. The hybrid management plane validates the property set; if valid, the properties are stored in the management plane.
  2. The Synchronizer retrieves the property set data and stores it locally on the runtime plane.
  3. The Message Processor loads the downloaded property set and makes it available to executing proxies.