使用屬性組合

本頁適用於 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 說明文件。

屬性集是一組用於儲存資料的鍵/值組合自訂集合。API Proxy 可在執行時擷取這項資料。

為何要使用屬性組合？

通常，您會使用屬性集合來儲存不會過期的資料，這些資料不應在 API 代理程式邏輯中硬式編碼。您可以在任何可存取流程變數的 Proxy 中存取資源集資料。

屬性集合的常見用途是提供與某個環境相關聯的值。舉例來說，您可以建立環境範圍的資源集合，其中包含在測試環境中執行的 Proxy 專屬設定值，以及另一個實際工作環境的集合。

例如：

  • 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 Proxy 修訂版本或環境。您無法將資源集的範圍設為機構。

下表說明使用 API 代理程式和機構範圍的資源集合行為和管理方式：

範圍 執行階段行為 管理
API Proxy 屬性僅適用於包含屬性集資源的 API 代理程式修訂版本。其他 API Proxy 或同一個 Proxy 的修訂版本都無法存取該特定屬性集合。 系統管理員可以使用 /resourcefiles Apigee API 或 UI 建立及編輯資源集。在 UI 中儲存 API Proxy 會建立新的修訂版本，且修改過的屬性集合只會與該修訂版本建立關聯。
環境 屬性適用於該環境中所有 API 代理程式的所有修訂版本。其他環境中的 API 代理程式無法存取該資源集。 管理員必須使用 /resourcefiles Apigee API 建立、查看、更新或刪除環境範圍的屬性集。這些屬性集不會顯示，也無法在 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 Proxy 修訂版本，就像管理其他資源一樣。詳情請參閱「使用 UI 管理資源」。

使用 API 管理資源集

使用 API 管理屬性集合，將其範圍限定為 API 代理程式修訂版本或環境，詳情請參閱下列各節。

使用 API 建立資源集

以下各節將說明如何使用 API 建立範圍限定為 API 代理程式修訂版本或環境的屬性集。

使用 API 建立範圍限定為 API Proxy 修訂版本的屬性集

如要使用 API 建立範圍限定為 API Proxy 修訂版本的屬性集合，請按照下列步驟操作：

  1. 建立資源集檔案。
  2. 將屬性集合檔案新增至 API Proxy 設定套件。
  3. 使用「Create API proxy」或「Update API proxy revision」 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 會設為您的 OAuth 2.0 存取憑證，如取得 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"

$TOKEN 會設為您的 OAuth 2.0 存取憑證，如取得 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"

$TOKEN 會設為您的 OAuth 2.0 存取憑證，如取得 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 Proxy 修訂版本

如要使用 API 更新屬性集合，並將其範圍限定為 API Proxy 修訂版本，請按照下列步驟操作：

  1. 更新屬性集合檔案。
  2. 使用 Get API proxy revision API 下載 API Proxy 設定套件，並使用下列選項：
    • 將 format 查詢參數設為 bundle
    • 將 Accept 頁首設為 application/zip
  3. 將屬性集合檔案新增至 API Proxy 設定套件。
  4. 使用 Update API proxy revision API 上傳 API Proxy 設定套件。

使用 API 更新屬性集合，將其範圍限定為特定環境

如要使用 API 更新範圍限定為環境的屬性集合，請更新屬性集合檔案，然後透過向下列資源發出 PUT 要求，將其上傳至貴機構的環境：https://apigee.googleapis.com/v1/organizations/{org}/environments/{env}/resourcefiles/{type}/{name}

請在提出要求時，一併提供下列資訊：

  • 將 {type} 設為 properties
  • 將 {name} 設為要更新的資源集合名稱
  • 將屬性集合檔案的內容以 application/octet-stream 或 multipart/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

$TOKEN 會設為您的 OAuth 2.0 存取憑證，如取得 OAuth 2.0 存取憑證一文所述。如要瞭解本範例中使用的 curl 選項，請參閱「使用 curl」。

以下提供回應範例。

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

詳情請參閱「更新資源檔案 API」。

使用 API 刪除資源集

以下各節將說明如何使用 API 刪除範圍限定為 API 代理程修訂版本或環境的屬性集。

使用 API 刪除範圍限定為 API Proxy 修訂版本的屬性集

如要使用 API 刪除範圍限定為 API Proxy 修訂版本的屬性集合，請按照下列步驟操作：

  1. 使用 Get API proxy revision API 下載 API Proxy 設定套件，並使用下列選項：
    • 將 format 查詢參數設為 bundle
    • 將 Accept 頁首設為 application/zip
  2. 從 API Proxy 設定套件中刪除屬性集合檔案。
  3. 使用 Update API proxy revision API 上傳 API Proxy 設定套件。

使用 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"

$TOKEN 會設為您的 OAuth 2.0 存取憑證，如取得 OAuth 2.0 存取憑證一文所述。如要瞭解本範例中使用的 curl 選項，請參閱「使用 curl」。

以下提供回應範例。

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

詳情請參閱「Delete resource file API」。

存取資源集值

存取 API Proxy 中任何可存取流程變數的屬性集合值，例如政策、流程、JavaScript 程式碼等。

如要存取屬性集合中的值，請使用下列語法：

propertyset.[property_set_name].[property_name]

其中：

  • property_set_name 是您定義的檔案名稱 (如果您使用的是 UI)，或是 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);

您也可以使用ExtractVariables 政策，從屬性集合取得屬性的值，並將該值指派給其他變數，如以下範例所示：

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

在這個範例中，政策會從屬性 name 讀取變數，並將值指派給 Pattern 元素中的變數。

使用「指派訊息」政策，動態指派屬性集區鍵的值

您可以使用「指派訊息」政策，將屬性集合鍵的值動態指派給資料流變數。詳情請參閱「指派訊息」政策參考資料中的 PropertySetRef 說明。

Apigee Hybrid 使用者

如果您使用的是 Apigee hybrid，請注意下列事項：

  1. 混合式管理層會驗證屬性集，如果屬性有效，則會儲存在管理層。
  2. Synchronizer 會擷取屬性集資料，並將其儲存在本機的執行階段平面。
  3. 訊息處理工具會載入下載的屬性集，並提供給執行 Proxy。