Hledání

Článek
12/14/2023

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	Řetězec představuje uživatelské jméno jednoho vlastníka.
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"
        }
      ]
    }
  ]
}

Sdílet prostřednictvím