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

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

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

ユーザーへの影響:

コレクション関数のページ結果

コレクションを返す関数は、オプションの合計カウントを含むページ化された結果を提供するようになりました。

応答は次の形式に従います。

{
                "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

スキャン・テクノロジの変化

これらの変更は、Scans セクションの以下の API 関数に影響します。

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

問題モデルの変更