REST API 升级到 v4 的技术概述

与先前的版本 (v2) 相比，REST API v4.0 进行了多项功能增强、优化和改进。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。