安全分数和配置文件 API

本页面适用于 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 文档。

概览

本页面介绍了如何使用 API 来管理风险评估安全得分和安全配置文件（简称“配置文件”）。本页介绍了 API 请求示例。

如需概括了解风险评估功能（包括限制）以及使用界面的说明，请参阅风险评估概览和界面。

Risk Assessment v2 API 示例

v2 API 示例的参数

本部分中的示例可以使用以下参数：

ORG 是您的组织。
ENV 是您要计算得分的环境。
PROFILE_ID 是配置文件的名称。PROFILE_ID 可以是 google-default 或您创建的自定义配置文件的名称。
PROFILE_DESC（可选）是配置文件的说明。这应该是对配置文件的人类可读说明，提供足够的信息以便将其与其他配置文件区分开来。
PROXY_NAME：代理的名称。
RESOURCES 可以是：
- "include_all_resources":{}，用于监控范围内的所有资源。
- "include": { "resources": [{"type": "API_PROXY", "name": "PROXY_NAME"}]}，用于监控一个或多个指定的代理。例如，"include": { "resources": [{"type": "API_PROXY", "name": "my-proxy-1"}]} 用于监控代理 my-proxy-1。
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 管理安全配置文件，但并非详尽无遗。如需了解详情，请参阅 securityProfilesV2 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 可以是 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：值受 computEnvironmentScores API 参考文档中所述的条件的限制。
- filters：请参阅 API 中支持的过滤条件。
- pageSize：单个页面中返回的子组件数上限：100。
不支持对输入使用多个过滤条件。
不支持响应中的“影响”字段。（“影响”字段是此建议对整体得分的潜在影响；这表示此建议对提高得分的重要性。）

如需了解并非特定于通过 API 使用的一般安全得分限制，请参阅安全得分限制 v1。

API 调用示例中的参数

以下部分提供了 API 调用示例，并可使用以下参数：

ORG 是您的组织。
ENV 是您要计算得分的环境。
ENVGROUP 是包含环境的环境组。
PROFILE_ID 是配置文件的名称。PROFILE_ID 可以是 default 或您创建的自定义配置文件的名称。
PROFILE_ID 必须包含 1 到 63 个字符，可以是小写字母、数字 0-9 或连字符。第一个字符必须是小写字母。最后一个字符必须是小写字母或数字。
PROXY_NAME：代理的名称。
$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`
所有代理的得分	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies`
特定代理的得分	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME`
特定代理的政策得分	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME/policies` `/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME/policies/individual`
特定代理的中介政策得分	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME/policies/individual/mediation`
特定代理的安全政策得分	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME/policies/individual/security`
特定代理的身份验证政策得分	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME/policies/individual/security/auth`
特定代理的 CORS 政策得分	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME/policies/individual/security/cors`
特定代理的威胁政策得分	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME/policies/individual/security/threat`
环境中所有代理的政策得分	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies` `/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies/individual`
环境中所有代理的中介政策得分	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies/individual/mediation`
环境中所有代理的安全政策得分	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies/individual/security`
环境中所有代理的身份验证政策得分	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies/individual/security/auth`
环境中所有代理的 CORS 政策得分	`/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies/individual/security/cors`
环境中所有代理的威胁政策得分	`/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"

注意：参数 securityProfileRevisionId 已弃用。如果您在 API 调用中添加此参数，则无论参数值是什么，Advanced API Security 都会使用配置文件的最新修订版本。

获取默认安全配置文件定义

要获取默认安全配置文件的定义，请输入以下命令：

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：要包含在自定义配置文件中的类别列表。这可以是以下安全类别的任意子集：
- abuse
- authorization
- cors
- mtls
- mediation
- threat

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

获取环境中所有代理的得分

如需获取环境中所有代理的得分，请输入如下所示的命令：

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"

获取环境中特定代理的得分

如需获取环境中特定代理的得分，请输入如下所示的命令：

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 是您想要获取其得分的代理。

获取环境中特定目标的得分

如需获取环境中特定目标的得分，请输入如下所示的命令：

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"

安全分数和配置文件 API 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

概览

Risk Assessment v2 API 示例

v2 API 示例的参数

检索批量安全评估结果

管理安全配置文件

获取现有的自定义安全配置文件

创建新的自定义安全配置文件

更新现有的自定义安全配置文件

删除自定义安全配置文件

管理监控条件

创建新的监控条件

列出监控条件

获取现有的监控条件

更新现有的监控条件

删除监控条件

风险评估 v1

使用 API 时的安全得分限制

API 调用示例中的参数

Risk Assessment v1 API 示例

API 中支持的过滤条件

使用默认安全配置文件

将默认安全配置文件附加到环境

获取默认安全配置文件定义

从环境分离默认安全配置文件

使用自定义安全配置文件

在 API 调用正文中定义配置文件

通过将 JSON 文件附加到 API 调用来定义配置文件

获取自定义安全配置文件定义

从环境分离自定义安全配置文件

删除自定义安全配置文件

获取环境的得分

获取环境的所有得分

获取环境的源得分

获取环境的滥用行为得分

获取环境中所有代理的得分

获取环境中特定代理的得分

获取环境中特定目标的得分

安全分数和配置文件 API