REST API 升级到 v4 技术概述

REST API v4.0 与旧版本 (v2) 相比，已实现大幅度增强、优化和改进。API v4 使用与 v2 相同的访问令牌来保持兼容性，可在继续使用现有令牌的同时，促使代码逐步迁移到 v4。另请注意，API v4 的路径前缀已从“/api/v2”更改为“/api/v4/”。虽然许多函数可以保留其名称和模型，以确保从“v2”轻松过渡到“v4”，但部分函数已有所修改。本主题用作技术指南，概述 API v4 中引入的主要更改。

OData 版本升级

API 现已使用 OData v4，而非 OData v3。此升级引入了高级查询功能，包括支持强大的数据聚合。

对用户的影响：

  • 用户可以利用更复杂的查询进行精确的数据检索。
  • 为满足 OData v4 标准，需要更新基于 OData v3 语法的现有查询。
以下是 $filter 表达式中 OData v3 与 v4 之间的一些更改示例：
  • substringof 不再可用；在 v4 中，应改用 contains。
  • Guid 文字已更改： guid’971314e0-b891-4d2e-b672-0dc37885bb0a’ ⇒ 971314e0-b891-4d2e-b672-0dc37885bb0a
  • 日期时间文字已更改： DateTime'2024-07-31T07:30:00' ⇒ 2024-07-31T07:30:00z

集合函数的页面结果

返回集合的函数现可提供分页结果，其中包括可选的总计数。

响应将遵循以下格式：

{
                "Items": [
                {
                Item1 ... 
                },
                {
                Item2 ... 
                }
                ],
                "Count": 2 //Optional - appears only if query option $count=true was provided 
                }

在 API v2 中，返回集合的许多函数有两个版本：一个版本返回对象的集合，另一个版本返回对象的页面结果。页面结果的优点在于，如果使用 $top 和 $skip 检索单个页面，则对象的总计数将包括在数据中，从而无需额外请求该计数。

在 API v4 中，直接返回对象的函数将被省略。这些函数始终以 PageResult 格式提供数据。计数为可选，仅当将 $count=true 添加到查询选项时才返回。

例如，API v2 包含两个函数，即以常规格式（对象数组）返回结果的 /api/V2/Apps 函数，以及以带有计数的页面格式返回结果的 /api/V2/Apps/GetAsPage 函数。

v4 只有一个函数，即以页面格式返回结果且计数可选的 /api/v4/Apps 函数。请注意，如果不需要计数，不请求计数即可提高效率。

移除冗余函数

已移除返回特定对象的函数，以便将特定对象标识的过滤器应用到返回集合的函数。

不再需要聚合对象的函数，因为此功能现已在 OData v4（$apply 查询选项）中可用。

示例：

未将 GET /api/v2/Scans/CountByUser 添加到 v4。

通过以下 URL 可以实现相同的功能：

GET /api/v4/Scans?$apply=groupby((CreatedBy/Id,CreatedBy/UserName,CreatedBy/FirstName,CreatedBy/LastName,CreatedBy/Email), aggregate($count as Count))

出于相同原因未添加到 v4 的其他类似函数：

/api/v2/Scans/CountByStatus

/api/v2/Scans/CountByTechnology

/api/V2/Users/Count

/api/v2/Issues/CountBySeverity/{scope}/{scopeId}

/api/v2/Issues/CountByStatus/{scope}/{scopeId}

/api/V2/AssetGroups/Count

扫描技术的术语更改

API v4 更改了用于扫描技术的术语：
  • DynamicAnalyzer ⇒ Dast
  • StaticAnalyzer ⇒ Sast
  • IASTAnalyzer ⇒ Iast
  • ScaAnalyzer ⇒ Sca

这些更改影响了“扫描”部分下方的以下 API 函数：

  • GET /api/v2/Scans/DynamicAnalyzer/{scanId} ⇒ /api/v4/Scans/Dast/{scanId}
  • GET /api/v2/Scans/StaticAnalyzer/{scanId} ⇒ /api/v4/Scans/Sast/{scanId}
  • GET /api/v2/Scans/ScaAnalyzer/{scanId} ⇒ /api/v4/Scans/Sca/{scanId}
  • GET /api/v2/Scans/StaticAnalyzerExecution/{executionId} ⇒ /api/v4/Scans/SastExecution/{executionId}
  • GET /api/v2/Scans/DynamicAnalyzerExecution/{executionId} ⇒ /api/v4/Scans/DastExecution/{executionId}
  • GET /api/v2/Scans/DynamicAnalyzerScanFile/{executionId} ⇒ /api/v4/Scans/DastScanFile/{executionId}
  • POST /api/v2/Scans/StaticAnalyzer ⇒ /api/v4/Scans/Sast
  • POST /api/v2/Scans/DynamicAnalyzerUploadedResultsFromFile ⇒ /api/v4/Scans/DastScanResults
  • POST /api/v2/Scans/IASTAnalyzer ⇒ /api/v4/Scans/Iast

为创建 DAST 扫描，已将 API v2 中的三个函数合并为一个公开所有选项的函数。请注意，v4 中新函数所需的模型与 v2 中的模型不同。有关详细信息，请参阅 API 文档。

以下三个函数：

POST /api/v2/Scans/DynamicAnalyzer

POST /api/v2/Scans/DynamicAnalyzerWithFile

POST /api/v2/Scans/DynamicAnalyzerWithFiles

已合并为一个函数：

POST /api/v4/Scans/Dast

问题模型的更改

对问题模型进行了少量更改（从 GET /api/v4/Issues/{scope}/{scopeId} 返回）：
  • “Id”和“ApplicationId”的类型已从字符串更改为 guid。此项调整规模虽小，但会影响 OData 过滤器的格式。
  • 已从模型中移除以下过时属性：AvailabilityImpact、Classification、ConfidentialityImpact、Authentication、AccessComplexity、AccessVector、ProjectName、Protocol、RemediationLevel、ReportConfidence、NessusPluginId、FixRecommendation、IntegrityImpact、Summary、WhiteHatSecVulnId、StepsToReproduce、Description、Exploitability、ApplicationName、FriendlyId。