REST API 升級至 v4 的技術概觀

REST API 4.0 版提供許多比先前版本 (v2) 更好的增強、最佳化和改善。API v4 使用與 v2 相同的存取記號來維持相容性，有助於將程式碼逐步移轉至 v4，同時仍能繼續使用現有記號。值得注意的是，API v4 的路徑字首已從 "/api/v2" 變更為"/api/v4/"。雖然許多函數的名稱與模型都沒有變動，以確保能從「v2」直接轉換為「v4」，但部分函數已有所修改。本主題為技術指南，概述 API v4 導入的主要變更。

OData 版本升級

API 現在使用 OData v4，而非 OData v3。這項升級導入進階查詢功能，包括支援強大的資料聚集。

對使用者的影響：

  • 使用者可以利用更複雜的查詢來精確擷取資料。
  • 必須更新以 OData v3 語法為基礎的現有查詢，以符合 OData v4 標準。
以下是一些 $filter 運算式中從 OData v3 到 v4 之變更的範例：
  • 已無法在 v4 中使用 substringof，應使用 contains。
  • GUID 文字已變更： guid’971314e0-b891-4d2e-b672-0dc37885bb0a’ ⇒ 971314e0-b891-4d2e-b672-0dc37885bb0a
  • DateTime 文字已變更： 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 會傳回頁面格式的結果，且計數為選用。請注意，如果不需要計數，則不要求該項目會更有效率。

移除重複函數

我們移除了傳回特定物件的函數，以將特定物件 ID 的篩選套用至傳回集合的函數。

此外也不再需要聚集物件的函數，因為現在可使用 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。