속성 세트 사용

이 페이지는 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 또는 UI를 사용하여 속성 집합을 만들고 수정할 수 있습니다. API 프록시를 UI에 저장하면 새 버전이 생성되고 수정된 속성 집합은 해당 버전에만 연결됩니다.
환경	해당 환경 내 모든 API 프록시의 모든 버전에서 속성을 사용할 수 있습니다. 다른 환경의 API 프록시는 해당 속성 집합에 액세스할 수 없습니다.	관리자는 /resourcefiles Apigee API를 사용하여 환경 범위의 속성 집합을 생성, 보기, 업데이트 또는 삭제해야 합니다. 이러한 속성 집합은 표시되지 않으며 Apigee UI에서 수정할 수 없습니다.

속성 집합 한도

Apigee는 제한에 설명된 대로 속성 세트에 제한을 둡니다. 또한 속성 집합 파일은 Java 속성 파일과 동일한 구문을 사용해야 합니다. 단, 속성 집합 파일에서는 중괄호 {}를 사용할 수 없습니다.

속성 집합 파일 만들기

일반적으로 속성 집합 값을 파일에 이름/값 쌍으로 저장합니다. 속성 집합 파일은 properties 유형의 리소스 파일입니다.

속성 집합 파일은 자바 속성 파일과 동일한 구문을 지원합니다. 예를 들어 유니코드 값을 포함할 수 있으며 # 또는 ! 문자를 주석 마커로 사용할 수 있습니다. 단, 속성 집합 파일에서는 중괄호 {}를 사용할 수 없습니다.

속성 파일 이름에 서픽스 .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. 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로 전달합니다.

참고 API를 사용하여 속성 집합 파일을 가져올 때 chmod 개발 도구(예: curl)가 파일을 업로드할 수 있도록 파일의 권한을 변경해야 합니다.

다음 예시는 /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

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.