Suche

Artikel
03/14/2024

Es ist möglich, mithilfe der V3-API nach Paketen zu suchen, die in einer Paketquelle verfügbar sind. Die Ressource, die zum Erstellen von AutoVervollständigen-Abfragen verwendet wird, ist die SearchQueryService-Ressource im Dienstindex.

Versionsverwaltung

Die folgenden @type-Werte werden verwendet:

Wert vom Typ @type	Hinweise
SearchQueryService	Erstrelease
SearchQueryService/3.0.0-beta	Alias von `SearchQueryService`
SearchQueryService/3.0.0-rc	Alias von `SearchQueryService`
SearchQueryService/3.5.0	Umfasst Unterstützung für den `packageType`-Abfrageparameter

SearchQueryService/3.5.0

Diese Version führt Unterstützung für den Abfrageparameter packageType und die Antworteigenschaft packageTypes ein, die eine Filterung nach vom Autor definierten Pakettypen ermöglicht. Sie ist vollständig abwärtskompatibel mit Abfragen für SearchQueryService.

Basis-URL

Die Basis-URL für die folgenden APIs ist der Wert der @id-Eigenschaft, die einem der oben genannten @type-Ressourcenwerte zugeordnet ist. Im folgenden Dokument wird die Platzhalter-Basis-URL {@id} verwendet. Die Basis-URL kann sich basierend auf Implementierungs- oder Infrastrukturänderungen innerhalb der Paketquelle ändern, sodass sie dynamisch vom Dienstindex der Clientsoftware abgerufen werden muss.

HTTP-Methoden

Alle URLs in der Registrierungsressource unterstützen die HTTP-Methoden GET und HEAD.

Suche nach Paketen

Die Such-API ermöglicht es einem Client, eine Seite mit Paketen abzufragen, die einer angegebenen Suchabfrage entsprechen. Die Interpretation der Suchabfrage (z. B. die Tokenisierung der Suchbegriffe) wird von der Serverimplementierung bestimmt, aber die allgemeine Erwartung besteht darin, dass die Suchabfrage für übereinstimmende Paket-IDs, Titel, Beschreibungen und Tags verwendet wird. Andere Paketmetadatenfelder können ebenfalls berücksichtigt werden.

Ein nicht aufgelistetes Paket sollte niemals in Suchergebnissen angezeigt werden.

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

Anforderungsparameter

Name	Geben Sie in	Type	Erforderlich	Hinweise
q	URL	Zeichenfolge	Nein	Die Suchbegriffe zum Filtern von Paketen
skip	URL	integer	Nein	Die Anzahl der zu überspringenden Ergebnisse für die Paginierung
take	URL	integer	Nein	Die Anzahl der zurückzugebenden Ergebnisse für die Paginierung
Vorabversion	URL	boolean	Nein	`true` oder `false` zum Festlegen, ob Vorabversionen von Paketen zu berücksichtigen sind
semVerLevel	URL	Zeichenfolge	Nein	Eine SemVer 1.0.0-Versionszeichenfolge
packageType	URL	Zeichenfolge	Nein	Der Pakettyp, der zum Filtern von Paketen verwendet werden soll (hinzugefügt in `SearchQueryService/3.5.0`)

Die Suchabfrage q wird gemäß der Definition in der Serverimplementierung analysiert. nuget.org unterstützt grundlegende Filterung auf eine Vielzahl von Feldern. Wenn keine q bereitgestellt wird, sollten alle Pakete innerhalb der Grenzen zurückgegeben werden, die durch Überspringen und Übernehmen auferlegt werden. Dadurch wird die Registerkarte "Durchsuchen" in der Visual Studio-Benutzeroberfläche von NuGet aktiviert.

Der Parameter skip lautet standardmäßig 0.

Der Parameter take sollte eine ganze Zahl größer null sein. Für die Serverimplementierung gilt möglicherweise ein Höchstwert.

Hinweis

nuget.org beschränkt den skip Parameter auf 3.000 und den take Parameter auf 1.000.

Wenn prerelease nicht angegeben wird, werden Vorabversionspakete ausgeschlossen.

Der semVerLevel-Abfrageparameter wird verwendet, um SemVer 2.0.0-Pakete zu ermöglichen. Wenn dieser Abfrageparameter ausgeschlossen wird, werden nur Paket-IDs mit Versionen zurückgegeben, die mit SemVer 1.0.0 kompatibel sind. (Hierfür gelten die Einschränkungen der NuGet-Standardversionsverwaltung, z. B. Versionszeichenfolgen aus vier ganzzahligen Teilen). Wenn semVerLevel=2.0.0 angegeben wird, werden sowohl mit SemVer 1.0.0 als auch mit SemVer 2.0.0 kompatible Pakete zurückgegeben. Weitere Informationen finden Sie unter SemVer 2.0.0-Unterstützung für nuget.org.

Anhand des packageType-Parameters werden die Suchergebnisse weiter nach Paketen gefiltert, die mindestens einen Pakettyp aufweisen, der mit dem Pakettypnamen übereinstimmt. Wenn der angegebene Pakettyp kein gültiger Pakettyp im Sinne der Definition im Dokument zu Pakettypen ist, wird ein leeres Ergebnis zurückgegeben. Wenn der angegebene Pakettyp leer ist, wird kein Filter angewendet. Mit anderen Worten, wenn dem packageType-Parameter kein Wert übergeben wird, verhält er sich so, als wäre der Parameter nicht übergeben worden.

Antwort

Die Antwort ist ein JSON-Dokument, das bis zu take AutoVervollständigen-Ergebnisse enthält. Suchergebnisse werden nach Paket-ID gruppiert.

Das JSON-Stammobjekt weist die folgenden Eigenschaften auf:

Name	Type	Erforderlich	Hinweise
totalHits	integer	ja	Die Gesamtanzahl der Übereinstimmungen ohne Berücksichtigung von `skip` und `take`
data	Array von Objekten	ja	Die Suchergebnisse, die von der Anforderung abgeglichen werden

Suchergebnis

Jeder Artikel im data Array ist ein JSON-Objekt, das aus einer Gruppe von Paketversionen besteht, die dieselbe Paket-ID gemeinsam nutzen. Das -Objekt weist die folgenden Eigenschaften auf:

Name	Type	Erforderlich	Hinweise
id	Zeichenfolge	ja	Die ID des übereinstimmenen Pakets
version	Zeichenfolge	ja	Die vollständige SemVer 2.0.0-Versionszeichenfolge des Pakets (kann Buildmetadaten enthalten)
Beschreibung	Zeichenfolge	Nein
versions	Array von Objekten	ja	Alle Versionen des Pakets, die dem `prerelease` Parameter entsprechen
authors	Zeichenfolge oder Array von Zeichenfolgen	Nein
iconUrl	Zeichenfolge	Nein
licenseUrl	Zeichenfolge	Nein
Besitzer	Zeichenfolge oder Array von Zeichenfolgen	Nein	Eine Zeichenkette stellt den Nutzernamen eines einzelnen Besitzers dar.
projectUrl	Zeichenfolge	Nein
Registrierung	Zeichenfolge	Nein	Die absolute URL zum zugeordneten Registrierungsindex
Zusammenfassung	Zeichenfolge	Nein
Tags	Zeichenfolge oder Array von Zeichenfolgen	Nein
title	Zeichenfolge	Nein
totalDownloads	integer	Nein	Dieser Wert kann durch die Summe der Downloads im `versions` Array abgeleitet werden
überprüft	boolean	Nein	Ein boole'scher JSON-Wert, der angibt, ob das Paket verifiziert ist
packageTypes	Array von Objekten	ja	Die vom Paketautor definierten Pakettypen (hinzugefügt in `SearchQueryService/3.5.0`)

Bei nuget.org ist ein überprüftes Paket ein Paket mit einer Paket-ID, die einem reservierten ID-Präfix entspricht und einem der Besitzer des reservierten Präfixes gehört. Weitere Informationen zu Tags finden Sie in der Dokumentation zum Anwenden von Tags auf Ressourcen.

Die im Suchergebnisobjekt enthaltenen Metadaten stammen aus der neuesten Paketversion. Jeder Artikel im Array versions ist ein JSON-Objekt mit den folgenden Eigenschaften:

Name	Type	Erforderlich	Hinweise
@id	Zeichenfolge	ja	Die absolute URL zum zugeordneten Registrierungsblatt
version	Zeichenfolge	ja	Die vollständige SemVer 2.0.0-Versionszeichenfolge des Pakets (kann Buildmetadaten enthalten)
Downloads	integer	ja	Die Anzahl der Downloads für diese bestimmte Paketversion

Das packageTypes Array besteht immer aus mindestens einem (1) Artikel. Der Pakettyp für eine bestimmte Paket-ID gilt als die Pakettypen, die von der neuesten Version des Pakets in Bezug auf die anderen Suchparameter definiert werden. Jeder Artikel im Array packageTypes ist ein JSON-Objekt mit den folgenden Eigenschaften:

Name	Type	Erforderlich	Hinweise
name	Zeichenfolge	ja	Der Name des Pakettyps.

Beispielanforderung

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

Stellen Sie sicher, dass Sie die Basis-URL (https://search-sample.nuget.org/query in diesem Beispiel) aus dem Dienstindex abrufen, wie im Basis-URL-Abschnitt Erwähnung.

Beispielantwort

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

Freigeben über