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 v3 ではなく OData v4 を使用するようになりました。このアップグレードでは、強力なデータの集計のサポートなど、高度なクエリ機能が導入されました。
ユーザーへの影響:
- ユーザーは、より複雑なクエリを使用して、正確なデータを取得することができます。
- OData v3 構文に基づく既存のクエリは、OData 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 を使用して 1 つのページを取得した場合、オブジェクトの合計カウントがデータに含まれ、カウントの追加要求が保存されることです。
API v4 では、オブジェクトを直接返す関数は省略されています。これらの関数は、一貫して PageResult 形式でデータを提供します。Count はオプションで、$count = true がクエリ・オプションに追加された場合にのみ返されます。
たとえば、API v2 には、結果を通常の形式 (オブジェクトの配列) で返す関数 /api/V2/Apps
と、結果をページ形式でカウントと共に返す /api/V2/Apps/GetAsPage
関数の 2 つがあります。
v4 では、ページ形式で結果を返す 1 つの /api/v4/Apps
関数しかなく、カウントはオプションです。カウントが不要な場合は、カウントを要求しない方が効率的です。
冗長な機能の削除
特定のオブジェクトを返す関数が削除され、コレクションを返す関数に特定のオブジェクト ID のフィルターを適用できるようになりました。
この機能は、OData v4 ($apply query option) を使用して使用できるようになったため、オブジェクトを集計する関数は不要になりました。
例:
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
スキャン・テクノロジの変化
- DynamicAnalyzer ⇒ Dast
- StaticAnalyzer ⇒ Sast
- IASTAnalyzer ⇒ Iast
- ScaAnalyzer ⇒ Sca
これらの変更は、Scans セクションの以下の 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 つの関数がすべてのオプションを公開する 1 つの関数に統合されました。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。