本頁內容適用於 Apigee 和 Apigee Hybrid。
查看
Apigee Edge 說明文件。
總覽
本頁面說明如何使用 API 管理風險評估安全分數和安全設定檔 (簡稱「設定檔」)。本頁面提供 API 要求範例。
如需風險評估功能總覽 (包括限制),以及使用 UI 的操作說明,請參閱風險評估總覽和 UI。
風險評估 v2 API 範例
v2 API 範例的參數
本節範例可使用下列參數:
- ORG 是貴機構。
- ENV 是您要計算分數的環境。
- PROFILE_ID 是設定檔名稱。PROFILE_ID 可以是
google-default,也可以是您建立的自訂設定檔名稱。 - PROFILE_DESC (選用) 是設定檔的說明。這應該是使用者可讀的設定檔說明,提供足夠資訊來區分設定檔與其他設定檔。
- PROXY_NAME:Proxy 的名稱。
- RESOURCES 可以是:
"include_all_resources":{},監控範圍內的所有資源。"include": { "resources": [{"type": "API_PROXY", "name": "PROXY_NAME"}]}監控一或多個指定的 Proxy。舉例來說,"include": { "resources": [{"type": "API_PROXY", "name": "my-proxy-1"}]}可監控名為my-proxy-1的 Proxy。
- SECURITY_MONITORING_CONDITION_ID:安全監控條件的專屬 ID。如未提供 ID,系統會自動產生 UUID。
$TOKEN是 OAuth 存取權杖的環境變數。
擷取批次安全評估結果
具有 Security Admin 或 Security Viewer 角色的使用者有權執行臨時風險評估計算。您需要指定安全性設定檔、範圍 (Apigee 環境) 和要評估的資源。資源可以是範圍內的所有資源,也可以只有少數資源。include_all_resources: true如要進一步瞭解這項功能,請參閱 Apigee Management API 參考說明文件中的 securityAssessmentResults.batchCompute。
curl "https://apigee.googleapis.com/v1/organizations/ORG/securityAssessmentResults:batchCompute" \
-X POST \
-H "Authorization: Bearer $TOKEN" \
-H 'Content-type: application/json' \
-d '{
"profile": "PROFILE_ID",
"scope": "ENV",
RESOURCES
}'以下是這項要求的可能回應:
{
"securityAssessmentResults": [
{
"resource": {
"type": "API_PROXY",
"name": "my-proxy-1",
"resourceRevisionId": "1"
},
"createTime": "2023-11-22T04:49:29.418166Z",
"scoringResult": {
"severity": "HIGH",
"failedAssessmentPerWeight": {
"MINOR": 1
},
"assessmentRecommendations": {
"cors-policies-check": {
"displayName": "CORS policies check",
"weight": "MAJOR",
"recommendations": [
{
"description": "Check whether a CORS policy or CORS header in AssignMessage policy are present.",
"link": {
"text": "Learn more",
"uri": "https://cloud.google.com/apigee/docs/api-platform/reference/policies/reference-overview-policy"
}
}
],
"verdict": "FAIL",
"scoreImpact": 100
}
},
"dataUpdateTime": "2023-11-22T04:49:29.418166Z"
}
}
],
"assessmentTime": "2023-11-22T04:49:29.418166Z"
}管理安全性設定檔
本節提供使用 API 管理安全性設定檔的範例,但並未詳盡列出所有情況。詳情請參閱安全設定檔 V2 API 參考文件。
取得現有的自訂安全性設定檔
這個指令會擷取專案中所有安全設定檔的資訊:
curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfilesV2" \
-H "Authorization: Bearer $TOKEN"這項指令會擷取特定安全設定檔的中繼資料,可用於擷取 google-default 設定檔和自訂設定檔的資訊:
curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfilesV2/PROFILE_ID" \
-H "Authorization: Bearer $TOKEN"建立新的自訂安全性設定檔
如要建立新的自訂安全性設定檔,請使用類似下列的指令:
curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfilesV2?security_profile_v2_id=PROFILE_ID" \
-X POST \
-H "Authorization: Bearer $TOKEN" \
-H 'Content-type: application/json' \
-d '{
"description": "PROFILE_DESC",
"profile_assessment_configs": {
"auth-policies-check": {"weight": "MINOR"},
"threat-policies-check": {"weight": "MODERATE"}
}
}'更新現有自訂安全性設定檔
如要更新現有設定檔,請使用類似下列的指令:
curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfilesV2/PROFILE_ID?update_mask=UPDATE_MASK" \
-X PATCH \
-H "Authorization: Bearer $TOKEN" \
-H 'Content-type: application/json' \
-d '{"description": "PROFILE_DESC"}'其中 UPDATE_MASK 可以是下列任一值 (如有):description、profile_assessment_configs、description,profile_assessment_configs 或 * (所有項目)。如果指定 * 更新遮罩,要求會更新所有欄位,如果要求中未包含某些值,這些值可能會遭到移除。
如果省略 update_mask,系統只會更新更新要求中提供的欄位。
刪除自訂安全性設定檔
如要刪除自訂安全性設定檔,請按照下列步驟操作:
curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfilesV2/PROFILE_ID" \
-X DELETE \
-H "Authorization: Bearer $TOKEN"管理監控條件
本節提供使用 API 管理監控條件的範例,但並未涵蓋所有情況。如要進一步瞭解如何透過 API 管理監控條件,請參閱監控條件 API 參考資料文件。
建立新的監控條件
如要建立新的監控條件,請使用類似下列的指令:
curl "https://apigee.googleapis.com/v1/organizations/ORG/securityMonitoringConditions?security_monitoring_condition_id=MONITORING_CONDITION_ID" \
-X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{
"profile": "PROFILE_ID",
"scope": "ENV",
RESOURCES
}'回覆內容可能如下所示:
{
"name": "organizations/my-org/securityMonitoringConditions/my-condition",
"createTime": "2025-11-22T05:02:16.089469Z",
"updateTime": "2023-11-22T05:02:16.089469Z",
"profile": "google-default",
"scope": "test",
"totalMonitoredResources": 4,
"totalDeployedResources": 4,
"includeAllResources": {}
}列出監控條件
如要取得貴機構的監控條件清單,請使用類似下列的指令:
curl -H "Authorization: Bearer $TOKEN" \
"https://apigee.googleapis.com/v1/organizations/ORG/securityMonitoringConditions"回覆格式如下:
{
"securityMonitoringConditions": [
{
"name": "organizations/my-org/securityMonitoringConditions/my-condition",
"createTime": "2023-11-22T05:02:16.089469Z",
"updateTime": "2025-11-22T05:02:16.089469Z",
"profile": "google-default",
"scope": "test",
"totalMonitoredResources": 4,
"totalDeployedResources": 4,
"includeAllResources": {}
}
]
}您也可以使用這個語法,依範圍或安全性設定檔限制傳回的結果:
curl -H "Authorization: Bearer $TOKEN" \
"https://apigee.googleapis.com/v1/organizations/ORG/securityMonitoringConditions?filter=scope=ENV%20AND%20profile=PROFILE_ID"取得現有的監控條件
如要取得現有監控條件的資訊,請使用類似下列的指令:
curl -H "Authorization: Bearer $TOKEN" \
"https://apigee.googleapis.com/v1/organizations/ORG/securityMonitoringConditions/MONITORING_CONDITION_ID"回覆格式如下:
{
"name": "organizations/my-org/securityMonitoringConditions/my-condition",
"createTime": "2023-11-22T05:02:16.089469Z",
"updateTime": "2025-11-22T05:02:16.089469Z",
"profile": "google-default",
"scope": "test",
"totalMonitoredResources": 4,
"totalDeployedResources": 4,
"includeAllResources": {}
}更新現有監控條件
這個指令會更新現有監控條件的設定檔:
curl -H "Authorization: Bearer $TOKEN" \
"https://apigee.googleapis.com/v1/organizations/ORG/securityMonitoringConditions/MONITORING_CONDITION_ID?update_mask=CONDITION_UPDATE_MASK" -X PATCH -H "Content-Type: application/json" \
-d '{
RESOURCES
}'其中 update_mask 為選填欄位。如果包含 CONDITION_UPDATE_MASK,則 CONDITION_UPDATE_MASK 可以是 include 或 include_all_resources。如果省略 update_mask,系統只會更新更新要求中提供的欄位。
回應可能如下所示:
{ "name": "test-condition", "createTime": "2023-11-22T03:04:05Z", "updateTime": "2023-11-22T03:04:05Z", "profile": "google-default", "scope": "test", "include": { "resources": [{ "type": "API_PROXY", "name": "PROXY_NAME" }] } }
刪除監控條件
這項指令會刪除現有的監控條件:
curl -H "Authorization: Bearer $TOKEN" \
"https://apigee.googleapis.com/v1/organizations/ORG/securityMonitoringConditions/MONITORING_CONDITION_ID" \
-X DELETE風險評估 v1
本節提供 Risk Assessment v1 API 的相關資訊和範例。
使用 API 時的安全分數限制
透過安全性分數和設定檔 API 使用安全性分數時,有下列限制:
- JSON 支援的輸入欄位:
timeRange:值會受到計算環境分數 API 參考資料中描述的條件限制。filters: 請參閱「API 支援的篩選器」。pageSize:單一頁面中傳回的子元件數量上限:100 個。
- 不支援多個輸入篩選器。
- 系統不支援回覆中的影響欄位。(「影響」欄位是指這項建議對整體分數的潛在影響。這表示這項建議對提高分數有多重要。)
如要瞭解一般安全分數限制 (不限於透過 API 使用),請參閱「安全分數第 1 版的限制」。
範例 API 呼叫中的參數
以下各節提供 API 呼叫範例,並可使用下列參數:
- ORG 是貴機構。
- ENV 是您要計算分數的環境。
- ENVGROUP 是包含環境的環境群組。
- PROFILE_ID 是設定檔名稱。PROFILE_ID 可以是
default, 也可以是您建立的自訂設定檔名稱。PROFILE_ID 必須包含 1 到 63 個字元,可以是小寫英文字母、數字 0 到 9 或連字號。開頭須為小寫英文字母,最後一個字元須為小寫英文字母或數字。
- PROXY_NAME:Proxy 的名稱。
$TOKEN是 OAuth 存取權杖的環境變數。timeRange是分數的時間範圍。
Risk Assessment v1 API 範例
API 支援的篩選器
下表列出 API 支援的篩選器,以及這些篩選器的元件路徑。
| 篩選器 | 元件路徑 |
|---|---|
| 環境分數 | /org@ORG/envgroup@ENVGROUP/env@ENV |
| 來源會為所有基礎元件評分 | /org@ORG/envgroup@ENVGROUP/env@ENV/source |
| 濫用分數 | /org@ORG/envgroup@ENVGROUP/env@ENV/source/abuse |
| 所有 Proxy 的分數 | /org@ORG/envgroup@ENVGROUP/env@ENV/proxies |
| 特定 Proxy 的分數 | /org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME |
| 特定 Proxy 的政策分數 |
|
| 特定 Proxy 的中介服務政策分數 | /org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME/policies/individual/mediation |
| 特定 Proxy 的安全性政策分數 | /org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME/policies/individual/security |
| 特定 Proxy 的驗證政策分數 | /org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME/policies/individual/security/auth |
| 特定 Proxy 的 CORS 政策分數 | /org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME/policies/individual/security/cors |
| 特定 Proxy 的威脅政策分數 | /org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME/policies/individual/security/threat |
| 環境中所有 Proxy 的政策分數 |
|
| 環境中所有 Proxy 的中介服務政策分數 | /org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies/individual/mediation |
| 環境中所有 Proxy 的安全性政策分數 | /org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies/individual/security |
| 環境中所有 Proxy 的驗證政策分數 | /org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies/individual/security/auth |
| 環境中所有 Proxy 的 CORS 政策分數 | /org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies/individual/security/cors |
| 環境中所有 Proxy 的威脅政策分數 | /org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies/individual/security/threat |
使用預設安全性設定檔
以下範例說明如何使用預設安全性設定檔。如需範例中使用的參數,請參閱「範例 API 呼叫中的參數」。
將預設安全性設定檔附加至環境
如要查看安全性分數,請將設定檔連結至要評估安全性的環境。如要將預設安全性設定檔附加至環境,請使用下列指令:
curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles/default/environments" \
-X POST \
-d '{"name": "ENV"}' \
-H 'Content-type: application/json' \
-H "Authorization: Bearer $TOKEN"取得預設安全性設定檔定義
如要取得預設安全設定檔的定義,請輸入下列指令:
curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles/default" \
-H 'Content-type: application/json' \
-H "Authorization: Bearer $TOKEN"從環境中取消連結預設安全性設定檔
如要從環境中分離預設設定檔,請按照下列步驟操作:
curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles/default/environments/ENV" \
-X DELETE
-H 'Content-type: application/json' \
-H "Authorization: Bearer $TOKEN"使用自訂安全性設定檔
您可以透過下列任一方式,使用 API 呼叫建立 自訂安全性設定檔:
- 在呼叫主體中明確定義設定檔。
- 將內含設定檔定義的 JSON 檔案附加至呼叫。
以下各節提供這兩種方法的範例。 如需範例中使用的參數,請參閱「範例 API 呼叫中的參數」。
下列範例 API 呼叫中的欄位會指定自訂設定檔:
description:自訂設定檔的說明。profileConfig:要納入自訂設定檔的類別清單。可以是下列安全性類別的任何子集:abuseauthorizationcorsmtlsmediationthreat
在 API 呼叫主體中定義設定檔
如要在 API 呼叫的主體中定義自訂設定檔,請輸入類似下列的指令:
curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles?security_profile_id=PROFILE_ID" \
-X POST \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"description":"test custom profile",
"profileConfig" : {
"categories":[
{"cors":{}},
{"threat":{}}
]
}
}'這樣會建立自訂設定檔,其中包含 cors 和 threat 類別,並傳回類似以下的回應:
{
"name": "PROFILE_ID",
"revisionId": "1",
"revisionCreateTime": "2023-07-17T18:47:08Z",
"revisionUpdateTime": "2023-07-17T18:47:08Z",
"scoringConfigs": [
{
"title": "json",
"scorePath": "/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies/individual/security/threat/json",
"description": "Check if JSONThreatProtection policy is configured."
},
{
"title": "xml",
"scorePath": "/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies/individual/security/threat/xml",
"description": "Check if XMLThreatProtection policy is configured."
},
{
"title": "cors",
"scorePath": "/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies/individual/security/cors",
"description": "Check if CORS policy is configured."
}
],
"maxScore": 1200,
"minScore": 200,
"profileConfig": {
"categories": [
{
"cors": {}
},
{
"threat": {}
}
]
},
"description": "test custom profile"
}將 JSON 檔案附加至 API 呼叫,定義設定檔
您也可以附加定義設定檔的 JSON 檔案至 API 呼叫,藉此定義自訂安全性設定檔。舉例來說,請先建立下列 JSON 檔案:
{
"description": "test custom profile",
"profileConfig" : {
"categories":[
{"cors":{}},
{"threat" :{}},
]
}
}這會定義具有 cors 和 threat 類別的設定檔。接著,您可以根據這些類別建立設定檔,步驟如下:
curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles?security_profile_id=PROFILE_ID" \
-X POST \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d @create_profile.json其中 create_profile.json 是上述 JSON 檔案的名稱。
取得自訂安全性設定檔定義
如要取得自訂安全設定檔的定義,請輸入類似下列的指令:
curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles/PROFILE_ID" \
-X GET \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json"從環境中分離自訂安全性設定檔
如要從環境中分離自訂安全性設定檔,請輸入類似下列的指令:
curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles/PROFILE_ID/environments/ENV" \
-X DELETE \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json"刪除自訂安全性設定檔
如要刪除自訂安全性設定檔,請輸入類似下列的指令:
curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles/PROFILE_ID" \
-X DELETE \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json"取得環境的分數
以下各節提供取得環境分數的範例。如需範例中使用的參數,請參閱「範例 API 呼叫中的參數」。
取得環境的所有分數
如要取得環境的所有分數,請輸入類似下列的指令:
curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles/PROFILE_ID/environments/ENV:computeEnvironmentScores" \
-X POST \
-d '{"timeRange":
{
"startTime": "YYYY-MM-DDT00:00:00Z",
"endTime": "YYYY-MM-DDT00:00:00Z"
}
}' \
-H 'Content-type: application/json' \
-H "Authorization: Bearer $TOKEN"如需要求和回應的說明,請參閱
computeEnvironmentScores參考頁面。
取得環境的來源分數
如要取得環境的來源分數,請輸入類似下列的指令:
curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles/PROFILE_ID/environments/ENV:computeEnvironmentScores" \
-X POST \
-d '{"timeRange":
{
"startTime": "YYYY-MM-DDT00:00:00Z",
"endTime": "YYYY-MM-DDT00:00:00Z"
},
"filters": [{"scorePath": "/org@ORG/envgroup@ENVGROUP/env@ENV/source"}]
}' \
-H 'Content-type: application/json' \
-H "Authorization: Bearer $TOKEN"取得環境的來源濫用分數
如要取得環境中來源的濫用分數,請輸入類似下列的指令:
curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles/PROFILE_ID/environments/ENV:computeEnvironmentScores" \
-X POST \
-d '{"timeRange":
{
"startTime": "YYYY-MM-DDT00:00:00Z",
"endTime": "YYYY-MM-DDT00:00:00Z"
},
"filters": [{"scorePath": "/org@ORG/envgroup@ENVGROUP/env@ENV/source/abuse"}]
}' \
-H 'Content-type: application/json' \
-H "Authorization: Bearer $TOKEN"取得環境中所有 Proxy 的分數
如要取得環境中所有 Proxy 的分數,請輸入類似下列的指令:
curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles/PROFILE_ID/environments/ENV:computeEnvironmentScores" \
-X POST \
-d '{"timeRange":
{
"startTime": "YYYY-MM-DDT00:00:00Z",
"endTime": "YYYY-MM-DDT00:00:00Z"
},
"filters": [{"scorePath": "/org@ORG/envgroup@ENVGROUP/env@ENV/proxies"}]
}' \
-H 'Content-type: application/json' \
-H "Authorization: Bearer $TOKEN"取得環境中特定 Proxy 的分數
如要取得環境中特定 Proxy 的分數,請輸入類似下列的指令:
curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles/PROFILE_ID/environments/ENV:computeEnvironmentScores" \
-X POST \
-d '{"timeRange":
{
"startTime": "YYYY-MM-DDT00:00:00Z",
"endTime": "YYYY-MM-DDT00:00:00Z"
},
"filters": [{"scorePath": "/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY"}]
}' \
-H 'Content-type: application/json' \
-H "Authorization: Bearer $TOKEN"其中 PROXY 是您要取得分數的 Proxy。
取得環境中特定目標的分數
如要取得環境中特定目標的分數,請輸入類似下列的指令:
curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles/PROFILE_ID/environments/ENV:computeEnvironmentScores" \
-X POST \
-d '{"timeRange":
{
"startTime": "YYYY-MM-DDT00:00:00Z",
"endTime": "YYYY-MM-DDT00:00:00Z"
},
"filters": [{"scorePath": "/org@ORG/envgroup@ENVGROUP/env@ENV/target@TARGET"}]
}' \
-H 'Content-type: application/json' \
-H "Authorization: Bearer $TOKEN"