nuget.org プロトコル

  • [アーティクル]

Nuget.org と対話するには、クライアントは特定のプロトコルに従う必要があります。 これらのプロトコルは進化し続けるため、クライアントは、特定の nuget.org API を呼び出すときに使用するプロトコルのバージョンを識別する必要があります。 これにより、nuget.org は古いクライアントに対して中断のない方法で変更を加えることができます。

Note

このページに記載されている API は nuget.org に固有のものであり、他の NuGet サーバーの実装でこれらの API を導入することは想定されていません。

NuGet エコシステム全体で広く実装されている NuGet API の詳細については、API の概要に関するトピックを参照してください。

このトピックでは、各種のプロトコルの出現時点でのそれぞれのプロトコルを示します。

NuGet プロトコル バージョン 4.1.0

4.1.0 プロトコルは、nuget.org 以外のサービスと対話するための検証スコープ キーの使用法を指定し、nuget.org アカウントに対してパッケージを検証します。 4.1.0 バージョン番号は不明瞭な文字列ですが、このプロトコルをサポートしている公式 NuGet クライアントの最初のバージョンと期しくも一致しています。

検証によって、ユーザーが作成した API キーは nuget.org でのみ使用され、サードパーティのサービスからのその他の検査や検証は、1 回限りの使用検証スコープ キーによって処理されます。 これらの検証スコープ キーを使用して、パッケージが nuget.org の特定のユーザー (アカウント) に属していることを検証できます。

クライアントの要件

クライアントが nuget.org にパッケージをプッシュするために API 呼び出しを行うときには、クライアントは以下のヘッダーを渡す必要があります。

X-NuGet-Protocol-Version: 4.1.0

なお、X-NuGet-Client-Version ヘッダーのセマンティクスは似ていますが、公式 NuGet クライアントによってのみ使用されるように予約されています。 サード パーティのクライアントは X-NuGet-Protocol-Version ヘッダーおよび値を使用する必要があります。

push プロトコル自体の説明は、PackagePublish リソースのドキュメントに記載されています。

クライアントが外部サービスとやり取りし、パッケージが特定のユーザー (アカウント) に属しているかどうかを検証する必要がある場合、次のプロトコルを使用し、nuget.org からの API キーではなく、検証スコープ キーを使用する必要があります。

検証スコープ キーを要求するための API

この API は、nuget.org の作成者が所有しているパッケージを検証するための検証スコープ キーを取得するために使用されます。

POST api/v2/package/create-verification-key/{ID}/{VERSION}

要求パラメーター

名前 / タイプ 必須 メモ
ID URL string はい 検証スコープ キーが要求されているパッケージの識別子
VERSION URL string いいえ パッケージのバージョン
X-NuGet-ApiKey ヘッダー string はい たとえば、X-NuGet-ApiKey: {USER_API_KEY} のように指定します。

回答

{
    "Key": "{Verify scope key from nuget.org}",
    "Expires": "{Date}"
}

検証スコープ キーを検証するための API

この API は、nuget.org の作成者が所有するパッケージの検証スコープ キーを検証するために使用されます。

GET api/v2/verifykey/{ID}/{VERSION}

要求パラメーター

名前 / タイプ 必須 メモ
ID URL string はい 検証スコープ キーが要求されているパッケージの識別子
VERSION URL string いいえ パッケージのバージョン
X-NuGet-ApiKey ヘッダー string はい たとえば、X-NuGet-ApiKey: {VERIFY_SCOPE_KEY} のように指定します。

Note

この検証スコープ API キーは、1 日のある時刻に有効期限が切れるか、最初の使用時の、いずれか早い方で期限切れになります。

回答

状態コード 意味
200 API キーが有効です
403 API キーが無効であるか、パッケージに対するプッシュが許可されていません
404 ID および VERSION (オプション) によって参照されているパッケージが存在しません