プロパティ セットの使用

このページは Apigee と Apigee ハイブリッドに適用されます。

Apigee Edge のドキュメントを表示する。

プロパティ セットは、データを格納する Key-Value ペアのカスタム コレクションです。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 または UI を使用してプロパティ セットの作成や編集ができます。API プロキシを UI に保存すると、新しいリビジョンが作成され、変更されたプロパティ セットはそのリビジョンにのみ関連付けられます。
環境	プロパティは、その環境内のすべての API プロキシのすべてのリビジョンで使用できます。他の環境内の API プロキシは、そのプロパティ セットにアクセスできません。	管理者は、環境スコープのプロパティ セットの作成、表示、更新、削除を行うには、/resourcefiles Apigee API を使用する必要があります。これらのプロパティ セットは Apigee UI には表示されないため、Apigee UI では編集できません。

プロパティ セットの上限

上限で説明されているように、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

プロパティ セット ファイルを作成したら、UI または API のいずれかを使用してファイルを Apigee にアップロードします。

UI を使用してプロパティ セットを管理する

他のリソースを管理するのと同じ方法で、UI を使用して API プロキシ リビジョンをスコープとするプロパティ セットを管理します。詳細については、UI を使用してリソースを管理するをご覧ください。

注:

• リビジョンがデプロイされていない場合に限り、その API プロキシ リビジョンをスコープとするプロパティ セットを作成、更新、削除できます。API プロキシ リビジョンがデプロイされた後は変更できません。
• 組織または環境をスコープとするプロパティ セットは、UI では管理できません。詳細については、プロパティ セットのスコープをご覧ください。

API を使用してプロパティ セットを管理する

以降のセクションで説明するように、API を使用して、API プロキシ リビジョンまたは環境をスコープとするプロパティ セットを管理します。

API を使用してプロパティ セットを作成する

ここでは、API を使用して、API プロキシ リビジョンまたは環境をスコープとするプロパティ セットを作成する方法について説明します。

API を使用して API プロキシ リビジョンをスコープとするプロパティ セットを作成する

注: 既存の API プロキシ リビジョンをスコープとするプロパティ セットを追加できるのは、リビジョンがデプロイされていない場合だけです。API プロキシ リビジョンがデプロイされた後は変更できません。

API を使用して API プロキシ リビジョンをスコープとするプロパティ セットを作成するには:

1. プロパティ セットのファイルを作成します。
2. プロパティ セットのファイルを API プロキシ構成バンドルに追加します。
3. Create API proxy API または Update API proxy revision API を使用して、バンドルをアップロードします。

API を使用して環境をスコープとするプロパティ セットを作成する

API を使用して環境をスコープとするプロパティ セットを追加するには、プロパティ セットのファイルを作成し、リソース https://apigee.googleapis.com/v1/organizations/{org}/environments/{env}/resourcefiles に POST リクエストを送信することで組織の環境にアップロードします。

リクエストには次の情報を含めます。

• name クエリ パラメータにプロパティ セットの名前を設定します。
• type クエリ パラメータを properties に設定します。
• プロパティ セットのファイルの内容を application/octet-stream または multipart/form-data として渡します。

注: API を使用してプロパティ セットのファイルをインポートする場合は、開発ツール（curl など）がファイルをアップロードできるように、chmod ファイル権限の使用が必要になる場合があります。

次の例では、MyPropSet という名前のプロパティ セットを /Users/myhome/myprops.properties ファイルからインポートしています。

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

Note: You can update a property set scoped to an API proxy revision only if the revision has not been deployed. After an API proxy revision is deployed, it is immutable.

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

Note: When importing a property set file using the API, you might need to chmod the file's permissions so that your development tool (such as curl) can upload it.

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

Note: You can delete a property set scoped to an API proxy revision if it has not been deployed. After an API proxy revision is deployed, it is immutable.

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.