搜尋

發行項
05/22/2024

您可以使用 V3 API 來搜尋套件來源上可用的套件。用來搜尋的資源是在SearchQueryService服務索引中找到的資源。

版本控制

使用下列 @type 值：

@type 值	備註
SearchQueryService	初始版本
SearchQueryService/3.0.0-beta	的別名 `SearchQueryService`
SearchQueryService/3.0.0-rc	的別名 `SearchQueryService`
SearchQueryService/3.5.0	包含查詢參數的支援`packageType`

SearchQueryService/3.5.0

此版本引進查詢參數和packageTypes響應屬性的支援packageType，允許作者定義的封裝類型進行篩選。它與查詢完全回溯相容。SearchQueryService

基礎 URL

下列 API 的基底 URL 是 @id 與上述其中一個資源 @type 值相關聯的屬性值。在下列檔中，將會使用佔位元基底 URL {@id} 。基底 URL 可能會根據套件來源內的實作或基礎結構變更而變更，因此用戶端軟體必須以動態方式從服務索引擷取。

HTTP 方法

註冊資源中找到的所有 URL 都支援 HTTP 方法和 GETHEAD。

搜尋套件

搜尋 API 可讓客戶端查詢符合指定搜尋查詢的套件頁面。搜尋查詢的解譯（例如搜尋字詞的標記化）是由伺服器實作所決定，但一般預期是搜尋查詢用於比對套件標識碼、標題、描述和標記。您也可以考慮其他套件元數據欄位。

未列出的套件不應該出現在搜尋結果中。

GET {@id}?q={QUERY}&skip={SKIP}&take={TAKE}&prerelease={PRERELEASE}&semVerLevel={SEMVERLEVEL}&packageType={PACKAGETYPE}

要求參數

名稱	位於	類型	必要	備註
q	URL	字串	否	用來篩選套件的搜尋字詞
skip	URL	整數	否	要略過的分頁結果數目
take	URL	整數	否	要傳回的結果數目，用於分頁
發行前版本	URL	boolean	否	`true` 或 `false` 判斷是否要包含發行前版本套件
semVerLevel	URL	字串	否	SemVer 1.0.0 版本字串
PackageType	URL	字串	否	用來篩選封裝的封裝類型（已新增至 `SearchQueryService/3.5.0`中）

搜尋查詢 q 是以伺服器實作所定義的方式剖析。 nuget.org 支援各種欄位的基本篩選。 q如果未提供，則應該傳回所有套件，並包含在略過和採用所強加的界限內。這會啟用 NuGet Visual Studio 體驗中的 [瀏覽] 索引標籤。

參數 skip 預設為 0。

參數 take 應該是大於零的整數。伺服器實作可能會施加最大值。

注意

nuget.org 將 skip 參數限制為 3,000，並將 take 參數限制為 1,000。

如果未 prerelease 提供，則會排除發行前版本套件。

查詢 semVerLevel 參數是用來選擇加入 SemVer 2.0.0 套件。如果排除此查詢參數，則只會傳回 SemVer 1.0.0 相容版本的套件（使用標準 NuGet 版本設定注意事項，例如具有 4 個整數片段的版本字串）。如果 semVerLevel=2.0.0 提供，則會傳回 SemVer 1.0.0 和 SemVer 2.0.0 相容套件。如需詳細資訊，請參閱 SemVer 2.0.0 支援 nuget.org。

packageType參數可用來進一步篩選搜尋結果，只篩選至少一個符合封裝類型名稱的套件。如果提供的套件類型不是封裝類型檔所定義的有效封裝類型，則會傳回空的結果。如果提供的套件類型是空的，則不會套用任何篩選。換句話說，不傳遞任何值給 packageType 參數的行為會如同未傳遞參數一樣。

回應

回應是包含最多搜尋結果的 take JSON 檔。搜尋結果會依套件標識碼分組。

根 JSON 物件具有下列屬性：

名稱	類型	必要	備註
totalHits	整數	是	相符項目總數，忽略 `skip` 和 `take`
資料	物件陣列	是	要求相符的搜尋結果

搜尋結果

數位中的每個 data 專案都是由共用相同套件識別碼的套件版本群組所組成的 JSON 物件。物件具有下列屬性：

名稱	類型	必要	備註
id	string	是	相符套件的標識碼
version	字串	是	套件的完整 SemVer 2.0.0 版本字串（可能包含組建元資料）
description	字串	否
版本	物件陣列	是	符合 `prerelease` 參數的所有套件版本
作者	字串或字串陣列	否
iconUrl	字串	否
licenseUrl	字串	否
擁有者	字串或字串陣列	否	字串代表單一擁有者的用戶名稱
projectUrl	字串	否
註冊	字串	否	相關聯註冊索引的絕對 URL
摘要	字串	否
標記	字串或字串陣列	否
title	字串	否
totalDownloads	整數	否	此值可由數位中的 `versions` 下載總和推斷
驗證	boolean	否	JSON 布爾值，指出是否已驗證套件
packageTypes	物件陣列	是	套件作者所定義的套件型態（已在中 `SearchQueryService/3.5.0`新增）

在 nuget.org 上，已驗證的套件具有符合保留標識符前置詞且由其中一個保留前綴擁有者的套件標識符。如需詳細資訊，請參閱標識符前置詞保留的相關文件。

搜尋結果物件中包含的元數據取自最新的套件版本。陣列中的每個 versions 專案都是具有下列屬性的 JSON 物件：

名稱	類型	必要	備註
@id	字串	是	相關聯註冊分葉的絕對 URL
version	字串	是	套件的完整 SemVer 2.0.0 版本字串（可能包含組建元資料）
下載	整數	是	此特定套件版本的下載次數

陣列 packageTypes 一律包含至少一個（1）個專案。指定套件識別碼的套件類型會被視為套件最新版本針對其他搜尋參數所定義的套件類型。陣列中的每個 packageTypes 專案都是具有下列屬性的 JSON 物件：

名稱	類型	必要	注意
NAME	字串	是	封裝類型的名稱。

範例要求

GET https://search-sample.nuget.org/query?q=NuGet.Versioning&prerelease=false&semVerLevel=2.0.0

請務必從服務索引擷取基底 URL （https://search-sample.nuget.org/query在此範例中），如基底 URL 一節中所述。

範例回覆

{
  "totalHits": 2,
  "data": [
    {
      "registration": "https://api.nuget.org/v3/registration-sample/nuget.versioning/index.json",
      "id": "NuGet.Versioning",
      "version": "4.4.0",
      "description": "NuGet's implementation of Semantic Versioning.",
      "summary": "",
      "title": "NuGet.Versioning",
      "licenseUrl": "https://raw.githubusercontent.com/NuGet/NuGet.Client/dev/LICENSE.txt",
      "tags": [ "semver", "semantic", "versioning" ],
      "authors": [ "NuGet" ],
      "totalDownloads": 141896,
      "verified": true,
      "packageTypes": [
        {
          "name": "Dependency"
        }
      ],
      "versions": [
        {
          "version": "3.3.0",
          "downloads": 50343,
          "@id": "https://api.nuget.org/v3/registration-sample/nuget.versioning/3.3.0.json"
        },
        {
          "version": "3.4.3",
          "downloads": 27932,
          "@id": "https://api.nuget.org/v3/registration-sample/nuget.versioning/3.4.3.json"
        },
        {
          "version": "4.0.0",
          "downloads": 63004,
          "@id": "https://api.nuget.org/v3/registration-sample/nuget.versioning/4.0.0.json"
        },
        {
          "version": "4.4.0",
          "downloads": 617,
          "@id": "https://api.nuget.org/v3/registration-sample/nuget.versioning/4.4.0.json"
        }
      ]
    },
    {
      "@id": "https://api.nuget.org/v3/registration-sample/nerdbank.gitversioning/index.json",
      "@type": "Package",
      "registration": "https://api.nuget.org/v3/registration-sample/nerdbank.gitversioning/index.json",
      "id": "Nerdbank.GitVersioning",
      "version": "2.0.41",
      "description": "Stamps your assemblies with semver 2.0 compliant git commit specific version information and provides NuGet versioning information as well.",
      "summary": "Stamps your assemblies with semver 2.0 compliant git commit specific version information and provides NuGet versioning information as well.",
      "title": "Nerdbank.GitVersioning",
      "licenseUrl": "https://raw.githubusercontent.com/AArnott/Nerdbank.GitVersioning/ed547462f7/LICENSE.txt",
      "projectUrl": "http://github.com/aarnott/Nerdbank.GitVersioning",
      "tags": [ "git", "commit", "versioning", "version", "assemblyinfo" ],
      "authors": [ "Andrew Arnott" ],
      "totalDownloads": 11906,
      "verified": false,
      "versions": [
        {
          "version": "1.6.35",
          "downloads": 10229,
          "@id": "https://api.nuget.org/v3/registration-sample/nerdbank.gitversioning/1.6.35.json"
        },
        {
          "version": "2.0.41",
          "downloads": 1677,
          "@id": "https://api.nuget.org/v3/registration-sample/nerdbank.gitversioning/2.0.41.json"
        }
      ]
    }
  ]
}

共用方式為

搜尋