此页面由 Cloud Translation API 翻译。

安全分数和配置文件 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"