使用屬性組合

本頁內容適用於 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 說明文件。

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

為什麼要使用屬性組合？

一般來說，您會使用屬性集儲存不應在 API Proxy 邏輯中硬式編碼的非到期資料。您可以在 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 代理程式修訂版本或環境。您無法將資源集範圍設為機構。

下表說明 API 代理和機構範圍的屬性集行為和管理方式：

範圍	執行階段行為	管理
API Proxy	屬性只能用於包含屬性集資源的 API Proxy 修訂版本。其他 API Proxy 或相同 Proxy 的修訂版本都無法存取該特定屬性集。	管理員可以使用 /resourcefiles Apigee API 或 UI 建立及編輯屬性集。在使用者介面中儲存 API Proxy 時，系統會建立新的修訂版本，且修改後的屬性集只會與該修訂版本建立關聯。
環境	環境中的所有 API Proxy 修訂版本都可使用屬性。 其他環境中的 API Proxy 無法存取該屬性集。	管理員必須使用 /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 Proxy 修訂版本尚未部署時，您才能建立、更新或刪除該版本範圍內的屬性集。API Proxy 修訂版本部署後就無法變更。
• 您無法使用 UI 管理範圍限定於機構或環境的屬性集。詳情請參閱「屬性集範圍」。

。

使用 API 管理資源集

如要管理 API Proxy 修訂版本或環境範圍的屬性集，請使用 API，詳情請參閱下列各節。

使用 API 建立資源集

以下各節說明如何使用 API，建立以 API Proxy 修訂版本或環境為範圍的屬性集。

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

注意： 只有在現有 API 代理程式修訂版本尚未部署時，您才能新增範圍限定於該版本的屬性集。API Proxy 修訂版本部署後即無法變更。

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

1. 建立屬性集檔案。
2. 將屬性集檔案新增至 API Proxy 設定套件。
3. 使用「建立 API Proxy」或「更新 API Proxy 修訂版本」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 設為 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 Proxy 修訂版本或環境為範圍的屬性集。

使用 API 更新 API Proxy 修訂版本範圍的屬性集

注意： 只有在 API Proxy 修訂版本尚未部署時，您才能更新該版本範圍內的屬性集。API Proxy 修訂版本部署後即無法變更。

如要使用 API 更新 API Proxy 修訂版本範圍內的屬性集，請按照下列步驟操作：

1. 更新屬性集檔案。
2. 使用 Get API proxy revision API 下載 API Proxy 設定套件，並使用下列選項：
   • 將 format 查詢參數設為 bundle
   • 將 Accept 標頭設為 application/zip
3. 將屬性集檔案新增至 API Proxy 設定套件。
4. 使用「更新 API Proxy 修訂版本」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 傳遞

注意：使用 API 匯入屬性集檔案時，您可能需要chmod檔案的權限，開發工具 (例如 curl) 才能上傳檔案。

以下範例會使用 /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 Proxy 修訂版本或環境為範圍的屬性集。

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

注意： 如果屬性集尚未部署，您可以刪除範圍限定為 API Proxy 修訂版本的屬性集。API Proxy 修訂版本部署後即無法變更。

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

1. 使用 Get API proxy revision API 下載 API Proxy 設定套件，並使用下列選項：
   • 將 format 查詢參數設為 bundle
   • 將 Accept 標頭設為 application/zip
2. 從 API Proxy 設定套件中刪除屬性集檔案。
3. 使用「更新 API Proxy 修訂版本」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"
}

詳情請參閱「刪除資源檔案 API」。

存取屬性集值

在 API Proxy 中，只要能存取流程變數，就能存取屬性集值：在政策、流程、JavaScript 程式碼等位置。

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

propertyset.[property_set_name].[property_name]

其中：

• property_set_name 是您定義的檔案名稱 (如果您使用使用者介面)，或是 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. 同步器會擷取屬性集資料，並將其儲存在執行階段平面上。
3. 訊息處理工具會載入下載的屬性集，並提供給執行的 Proxy。