Manage property sets

Understand and manage property sets, as described in the following sections.

About property sets

In Apigee hybrid, a property set is a custom collection of key/value pairs that store data. API proxies can retrieve this data when they execute.

Property sets, like other runtime data, are deployed to the cluster by hybrid using the following procedure:

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

Why use property sets?

Typically, you use property sets to store non-expiring data that shouldn't be hard-coded in your API proxy logic. You can access property set data anywhere in a proxy where you can access flow variables.

A common use case for property sets is to provide values that are associated with one environment or another. For example, you can create an environment-scoped property set with values that are specific to proxies running in your test environment, and another set for your production environment.

For example:

  • The prod-env.properties property set contains the property log-level=error
  • The test-env.properties property set contains the property log-level=debug

Similarly, you might store environment-specific routing information:

  • The test-env.properties property set contains the property db-url=mydomain.test.datasource.com
  • The prod-env.properties property set contains the property db-url=mydomain.prod.datasource.com

Property sets vs. KVMs

In hybrid, you can use property sets for some of the same use cases as the key value map (KVM) feature.

Key differences between property sets and KVMs include:

  • You create and update property sets on the management plane using the UI or API. Data is synchronized with the runtime plane.
  • You can only create environment-scoped KVM maps in the hybrid UI or API. You cannot add, update, or view entries to a KVM in the UI or API.
  • You cannot encrypt property set data.
  • You can only add or update KVM entries and access KVMs using the KVM policies (at proxy runtime).

Property set scopes

You can scope a property set to an API proxy revision or environment. You cannot scope a property set to an organization.

  • API proxy-scoped property sets: Properties are available only to that API proxy revision. No other API proxy revision can access that property set.
  • Environment-scoped property sets: Properties are available to all API proxies within that environment. API proxies within other environments cannot access that property set.

You specify the scope when you create a property set, but which scope you can specify depends on whether you create a property set using the UI or API.

The following table shows the different scopes and which method(s) you can use to create, update, and delete property sets for each scope:

Scope Create Update Delete
API UI API UI API UI
API proxy revision
Environment
Organization

Property set limits

Apigee hybrid imposes limits on property sets, as described in Limits. In addition, property set files must use the same syntax as Java properties files.

Create property set files

Typically, you store property set values as name/value pairs in a file. Property set files are resource files of type properties.

Property set files support the same syntax as Java properties files; for example, they can contain Unicode values and can use # or ! characters as comment markers.

The following example shows a simple property set file that defines several 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

After you create a property set file, you upload it to hybrid using either the UI or API.

Manage property sets using the UI

Manage property sets scoped to an API proxy revision using the UI in the same way you manage other resources. For more information, see Manage resources using the UI.

Manage property sets using the API

Manage property sets scoped to an API proxy revision or environment using the API, as described in the following sections.

Create property sets using the API

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

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

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

  1. Create the property set file.
  2. Add the property set file to an API proxy configuration bundle.
  3. Upload the bundle using the Create API proxy or Update API proxy revision API.

Create property sets scoped to an environment using the API

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

Include the following information with your request:

  • Set the name query parameter to the name of the property set
  • Set the type query parameter to properties
  • Pass the contents of the property set file as application/octet-stream or multipart/form-data

The following example imports a property set named MyPropSet from the /Users/myhome/myprops.properties file:

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 Obtain an OAuth 2.0 access token. For information about the curl options used in this example, see Use 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 Obtain an OAuth 2.0 access token. For information about the curl options used in this example, see Use 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 Obtain an OAuth 2.0 access token. For information about the curl options used in this example, see Use 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 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 Obtain an OAuth 2.0 access token. For information about the curl options used in this example, see Use 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 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 Obtain an OAuth 2.0 access token. For information about the curl options used in this example, see Use 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);

If you created the property set with the UI, be sure to include the ".properties" part of the name. For example:

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

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

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