REST API v4 へのアップグレードの技術概要

バージョン 4.0 の REST API では、以前のバージョン (v2) に比べて多くの機能強化、最適化、改善が行われています。API v4 は v2 と同じアクセス・トークンを使用することで互換性を維持し、既存のトークンを引き続き使用しながらコードを v4に徐々に移行します。特に、API v4 のパス・プレフィックスが「/api/v2」から「/api/v4/」に変更されています。多くの関数は名前とモデルを保持しているため、「v2」から「v4」への単純な移行が保証されていますが、一部の関数は変更されています。このトピックは、API v4 で導入された主な変更点の概要を示すテクニカル・ガイドの役割を果たします。

OData バージョン・アップグレード

API は OData v3 の代わりに OData v4 を利用するようになりました。このアップグレードでは、データの強力な集計のサポートなど、高度なクエリー機能が導入されています。

ユーザーへの影響:

  • ユーザーは、より複雑なクエリーを活用して正確なデータ取得を行うことができます。
  • OData v3 構文に基づく既存のクエリーは、OData v4 標準に合わせて更新する必要があります。
$filter 式での OData v3 と v4 間の変更例をいくつか示します。
  • substringof は使用できなくなりました。v4 では代わりに 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 では、コレクションを返す多くの関数に 2 つのバージョンがあります。1 つはオブジェクトのコレクションを返し、もう 1 つはオブジェクトのページ結果を返します。ページ結果の利点は、$top と $skip を使用して単一のページを取得した場合に、オブジェクトの合計数がデータに含まれるため、カウントの追加要求が不要になることです。

API v4 では、オブジェクトを直接返す関数は省略されます。これらの関数は、常に PageResult 形式でデータを提供します。Count はオプションであり、$count=true がクエリー・オプションに追加された場合にのみ返されます。

例えば、API v2 には 2 つの関数があります。このうち /api/V2/Apps は、通常の形式 (オブジェクトの配列) で結果を返し、/api/V2/Apps/GetAsPage はカウントを含むページ形式で結果を返します。

v4 では、1 つの関数のみがあります。/api/v4/Apps は、結果をページ形式で返し、カウントはオプションです。カウントが不要な場合は、要求しない方が効率的であることに注意してください。

冗長関数の削除

特定のオブジェクトを返す関数は、コレクションを返す関数に特定のオブジェクト ID のフィルターを適用するために削除されました。

この機能は OData v4 ($apply query オプション) を使用して使用できるようになったため、オブジェクトを集約する関数は不要になりました。

例:

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 の 3 つの関数は、すべてのオプションを公開する単一の関数に統合されました。v4 の新機能に必要なモデルは、v2 のモデルと異なることに注意してください。詳しくは、API 資料を参照してください。

次の 3 つの関数があります。

POST /api/v2/Scans/DynamicAnalyzer

POST /api/v2/Scans/DynamicAnalyzerWithFile

POST /api/v2/Scans/DynamicAnalyzerWithFiles

1 つの関数にマージ:

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。