Hledání

Pomocí rozhraní API V3 je možné vyhledat balíčky dostupné ve zdroji balíčku. Prostředek použitý k vyhledávání je SearchQueryService prostředek nalezený v indexu služby.

Vytváření verzí

Používají se následující @type hodnoty:

@type Hodnotu Notes
SearchQueryService Počáteční verze
SearchQueryService/3.0.0-beta Alias of SearchQueryService
SearchQueryService/3.0.0-rc Alias of SearchQueryService
SearchQueryService/3.5.0 Zahrnuje podporu parametru packageType dotazu.

SearchQueryService/3.5.0

Tato verze zavádí podporu parametru packageType dotazu a packageTypes vlastnosti odpovědi, což umožňuje filtrování podle typů balíčků definovaných autorem. Je plně zpětně kompatibilní s dotazy na SearchQueryService.

Základní adresa URL

Základní adresa URL pro následující rozhraní API je hodnota @id vlastnosti přidružené k jedné z výše uvedených hodnot prostředků @type . V následujícím dokumentu se použije zástupná základní adresa URL {@id} . Základní adresa URL se může změnit na základě změn implementace nebo infrastruktury ve zdroji balíčku, takže se musí dynamicky načítat z indexu služby klientským softwarem.

Metody HTTP

Všechny adresy URL nalezené v prostředku registrace podporují metody GET HTTP a HEAD.

Hledání balíčků

Rozhraní API vyhledávání umožňuje klientovi zadat dotaz na stránku balíčků odpovídající zadanému vyhledávacímu dotazu. Interpretace vyhledávacího dotazu (např. tokenizace hledaných termínů) je určená implementací serveru, ale obecně se očekává, že se vyhledávací dotaz používá pro odpovídající ID balíčků, názvy, popisy a značky. Mohou se také zvážit další pole metadat balíčku.

Vevýsledcíchch

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

Parametry požadavku

Název V Typ Požaduje se Notes
q URL string ne Hledané termíny použité k filtrování balíčků
skip Adresa URL integer ne Počet výsledků, které se mají přeskočit pro stránkování
take Adresa URL integer ne Počet vrácených výsledků pro stránkování
předběžná verze Adresa URL boolean ne true nebo false určení, zda zahrnout předběžné verze balíčků
semVerLevel URL string ne Řetězec verze SemVer 1.0.0
packageType URL string ne Typ balíčku, který se má použít k filtrování balíčků (přidáno do SearchQueryService/3.5.0)

Vyhledávací dotaz q se analyzuje způsobem, který je definován implementací serveru. nuget.org podporuje základní filtrování v různých polích. q Pokud není k dispozici, měly by se vrátit všechny balíčky v rámci hranic stanovených přeskočením a převzetím. Tím se v prostředí Sady Visual Studio NuGet povolí karta Procházet.

Výchozí skip hodnota parametru je 0.

Parametr take by měl být celé číslo větší než nula. Implementace serveru může mít maximální hodnotu.

Poznámka:

nuget.org omezuje skip parametr na 3 000 a take parametr na 1 000.

Pokud prerelease není k dispozici, předem vydané balíčky jsou vyloučeny.

Parametr semVerLevel dotazu se používá k vyjádření souhlasu s balíčky SemVer 2.0.0. Pokud je tento parametr dotazu vyloučený, vrátí se pouze balíčky s kompatibilními verzemi SemVer 1.0.0 (se standardními upozorněními na správu verzí NuGet, jako jsou řetězce verzí se 4 celými čísly). Pokud semVerLevel=2.0.0 je k dispozici, vrátí se oba balíčky kompatibilní s SemVer 1.0.0 a SemVer 2.0.0. Další informace najdete v podpoře semVer 2.0.0 pro nuget.org .

Tento packageType parametr slouží k dalšímu filtrování výsledků hledání pouze na balíčky, které mají alespoň jeden typ balíčku odpovídající názvu typu balíčku. Pokud zadaný typ balíčku není platným typem balíčku definovaným dokumentem Typ balíčku, vrátí se prázdný výsledek. Pokud je zadaný typ balíčku prázdný, nepoužije se žádný filtr. Jinými slovy, předání žádné hodnoty parametru packageType se bude chovat, jako by parametr nebyl předán.

Response

Odpověď je dokument JSON obsahující až výsledky take hledání. Výsledky hledání jsou seskupené podle ID balíčku.

Kořenový objekt JSON má následující vlastnosti:

Name Type Požaduje se Notes
totalHits integer ano Celkový počet shod, ignorování skip a take
data pole objektů ano Výsledky hledání, které odpovídají žádosti

Výsledek hledání

Každá položka v data poli je objekt JSON, který se skládá ze skupiny verzí balíčků, která sdílí stejné ID balíčku. Objekt má následující vlastnosti:

Name Type Požaduje se Notes
ID string ano ID odpovídajícího balíčku
version string ano Úplný řetězec verze SemVer 2.0.0 balíčku (může obsahovat metadata sestavení)
description string ne
versions pole objektů ano Všechny verze balíčku odpovídající parametru prerelease
Autoři řetězec nebo pole řetězců ne
iconUrl string ne
licenseUrl string ne
Majitelé řetězec nebo pole řetězců ne
projectUrl string ne
registrace string ne Absolutní adresa URL přidruženého indexu registrace
Souhrn string ne
značky řetězec nebo pole řetězců ne
title string ne
totalDownloads integer ne Tuto hodnotu lze odvodit součtem stahování v versions poli.
Ověřené boolean ne Logická hodnota JSON označující, jestli je balíček ověřený
packageTypes pole objektů ano Typy balíčků definované autorem balíčku (přidáno do SearchQueryService/3.5.0)

Na nuget.org je ověřený balíček, který má ID balíčku odpovídající předponě rezervovaného ID a vlastní jeden z vlastníků rezervované předpony. Další informace najdete v dokumentaci k rezervaci předpon ID.

Metadata obsažená v objektu výsledků hledání jsou převzata z nejnovější verze balíčku. Každá položka v versions poli je objekt JSON s následujícími vlastnostmi:

Name Type Požaduje se Notes
@id string ano Absolutní adresa URL přidruženého registračního listu
version string ano Úplný řetězec verze SemVer 2.0.0 balíčku (může obsahovat metadata sestavení)
ke stažení integer ano Počet stažení pro tuto konkrétní verzi balíčku

Pole packageTypes se vždy skládá z nejméně jedné (1) položky. Typ balíčku pro dané ID balíčku se považuje za typy balíčků definované nejnovější verzí balíčku s ohledem na ostatní parametry hledání. Každá položka v packageTypes poli je objekt JSON s následujícími vlastnostmi:

Name Type Požaduje se Notes
name string ano Název typu balíčku.

Ukázkový požadavek

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

Nezapomeňte načíst základní adresu URL (https://search-sample.nuget.org/query v této ukázce) z indexu služby, jak je uvedeno v části základní adresy URL .

Ukázková odpověď

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