Search

Artykuł
12/14/2023

Istnieje możliwość wyszukiwania pakietów dostępnych w źródle pakietu przy użyciu interfejsu API w wersji 3. Zasób używany do wyszukiwania to zasób znaleziony SearchQueryService w indeksie usługi.

Wersje

Używane są następujące @type wartości:

@type Wartość	Uwagi
SearchQueryService	Wersja początkowa
SearchQueryService/3.0.0-beta	Alias of `SearchQueryService`
SearchQueryService/3.0.0-rc	Alias of `SearchQueryService`
SearchQueryService/3.5.0	Obejmuje obsługę parametru `packageType` zapytania

SearchQueryService/3.5.0

Ta wersja wprowadza obsługę parametru packageType zapytania i packageTypes właściwości odpowiedzi, umożliwiając filtrowanie według zdefiniowanych typów pakietów autorów. Jest ona w pełni zgodna z poprzednimi wersjami zapytań do SearchQueryService.

Podstawowy adres URL

Podstawowy adres URL następującego interfejsu API to wartość @id właściwości skojarzonej z jedną z wyżej wymienionych wartości zasobów @type . W poniższym dokumencie zostanie użyty podstawowy adres URL {@id} symbolu zastępczego. Podstawowy adres URL może ulec zmianie na podstawie implementacji lub zmian infrastruktury w źródle pakietu, dlatego musi być dynamicznie pobierany z indeksu usługi przez oprogramowanie klienckie.

Metody HTTP

Wszystkie adresy URL znalezione w zasobie rejestracji obsługują metody GET HTTP i HEAD.

Wyszukiwanie pakietów

Interfejs API wyszukiwania umożliwia klientowi wykonywanie zapytań dotyczących strony pakietów pasujących do określonego zapytania wyszukiwania. Interpretacja zapytania wyszukiwania (np. tokenizacja terminów wyszukiwania) jest określana przez implementację serwera, ale ogólne oczekiwania polegają na tym, że zapytanie wyszukiwania jest używane do dopasowywania identyfikatorów pakietów, tytułów, opisów i tagów. Można również rozważyć inne pola metadanych pakietu.

Pakiet nie wymieniony nigdy nie powinien być wyświetlany w wynikach wyszukiwania.

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

Parametry żądania

Nazwisko	W	Typ	Wymagania	Uwagi
q	URL	string	nie	Terminy wyszukiwania używane do filtrowania pakietów
skip	URL	integer	nie	Liczba wyników do pominięcia w przypadku stronicowania
take	URL	integer	nie	Liczba wyników do zwrócenia w przypadku stronicowania
wersja wstępna	URL	boolean	nie	`true` lub `false` określenie, czy należy uwzględnić pakiety wersji wstępnej
semVerLevel	URL	string	nie	Ciąg wersji SemVer 1.0.0
packageType	URL	string	nie	Typ pakietu używany do filtrowania pakietów (dodany w `SearchQueryService/3.5.0`pliku )

Zapytanie q wyszukiwania jest analizowane w sposób zdefiniowany przez implementację serwera. nuget.org obsługuje podstawowe filtrowanie w różnych polach. Jeśli nie q zostanie podany, należy zwrócić wszystkie pakiety w granicach narzuconych przez pomijanie i przejmowanie. Spowoduje to włączenie karty "Przeglądaj" w środowisku programu Visual Studio NuGet.

Wartość domyślna parametru skip to 0.

Parametr take powinien być liczbą całkowitą większą niż zero. Implementacja serwera może narzucić maksymalną wartość.

Uwaga

nuget.org ogranicza skip parametr do 3000, a take parametr do 1000.

Jeśli prerelease nie zostanie podana, pakiety wersji wstępnej zostaną wykluczone.

Parametr semVerLevel zapytania służy do wyrażenia zgody na pakiety SemVer 2.0.0. Jeśli ten parametr zapytania zostanie wykluczony, zostaną zwrócone tylko pakiety z zgodnymi wersjami SemVer 1.0.0 (ze standardowymi zastrzeżeniami obsługi wersji NuGet, takimi jak ciągi wersji z 4 liczbami całkowitymi). Jeśli semVerLevel=2.0.0 zostanie podana wartość, zostaną zwrócone pakiety zgodne z standardem SemVer 1.0.0 i SemVer 2.0.0. Aby uzyskać więcej informacji, zobacz obsługę programu SemVer 2.0.0 w celu uzyskania nuget.org.

Parametr packageType służy do dalszego filtrowania wyników wyszukiwania tylko do pakietów, które mają co najmniej jeden typ pakietu pasujący do nazwy typu pakietu. Jeśli podany typ pakietu nie jest prawidłowym typem pakietu zdefiniowanym przez dokument Typ pakietu, zostanie zwrócony pusty wynik. Jeśli podany typ pakietu jest pusty, nie zostanie zastosowany żaden filtr. Innymi słowy przekazywanie żadnej wartości do parametru packageType będzie zachowywać się tak, jakby parametr nie został przekazany.

Response

Odpowiedź to dokument JSON zawierający take wyniki wyszukiwania. Wyniki wyszukiwania są grupowane według identyfikatora pakietu.

Główny obiekt JSON ma następujące właściwości:

Nazwisko	Type	Wymagania	Uwagi
totalHits	integer	tak	Łączna liczba dopasowań, lekceważenie `skip` i `take`
dane	tablica obiektów	tak	Wyniki wyszukiwania dopasowane przez żądanie

Wynik wyszukiwania

Każdy element w tablicy data jest obiektem JSON składającym się z grupy wersji pakietów współużytkujących ten sam identyfikator pakietu. Obiekt ma następujące właściwości:

Nazwisko	Type	Wymagania	Uwagi
identyfikator	string	tak	Identyfikator dopasowanego pakietu
version	string	tak	Pełny ciąg wersji SemVer 2.0.0 pakietu (może zawierać metadane kompilacji)
opis	string	nie
versions	tablica obiektów	tak	Wszystkie wersje pakietu pasujące do parametru `prerelease`
Autorów	ciąg lub tablica ciągów	nie
iconUrl	string	nie
licenseUrl	string	nie
Właścicieli	ciąg lub tablica ciągów	nie
projectUrl	string	nie
rejestracja	string	nie	Bezwzględny adres URL skojarzonego indeksu rejestracji
Podsumowanie	string	nie
tags	ciąg lub tablica ciągów	nie
title	string	nie
totalDownloads	integer	nie	Tę wartość można wywnioskować sumą pobrań w tablicy `versions`
Sprawdzonych	boolean	nie	Wartość logiczna JSON wskazująca, czy pakiet został zweryfikowany
packageTypes	tablica obiektów	tak	Typy pakietów zdefiniowane przez autora pakietu (dodane w `SearchQueryService/3.5.0`pliku )

W nuget.org zweryfikowany pakiet jest pakietem, który ma identyfikator pakietu pasujący do prefiksu identyfikatora zarezerwowanego i należący do jednego z właścicieli prefiksu zarezerwowanego. Aby uzyskać więcej informacji, zobacz dokumentację dotyczącą rezerwacji prefiksów identyfikatorów.

Metadane zawarte w obiekcie wyników wyszukiwania są pobierane z najnowszej wersji pakietu. Każdy element w tablicy versions jest obiektem JSON o następujących właściwościach:

Nazwisko	Type	Wymagania	Uwagi
@id	string	tak	Bezwzględny adres URL skojarzonego liścia rejestracji
version	string	tak	Pełny ciąg wersji SemVer 2.0.0 pakietu (może zawierać metadane kompilacji)
pobrane	integer	tak	Liczba pobrań dla tej konkretnej wersji pakietu

Tablica packageTypes zawsze będzie składać się z co najmniej jednego (1) elementu. Typ pakietu dla danego identyfikatora pakietu jest uważany za typy pakietów zdefiniowane przez najnowszą wersję pakietu w odniesieniu do innych parametrów wyszukiwania. Każdy element w tablicy packageTypes jest obiektem JSON o następujących właściwościach:

Nazwisko	Type	Wymagania	Uwagi
nazwa	string	tak	Nazwa typu pakietu.

Przykładowe żądanie

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

Pamiętaj, aby pobrać podstawowy adres URL (https://search-sample.nuget.org/query w tym przykładzie) z indeksu usługi, jak wspomniano w sekcji podstawowego adresu URL .

Przykładowa odpowiedź

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