Suche

Es ist möglich, mithilfe der V3-API nach Paketen zu suchen, die in einer Paketquelle verfügbar sind. Die ressource, die für die Suche verwendet wird, ist die Ressource, die SearchQueryService im Dienstindex gefunden wird.

Versioning

Die folgenden @type Werte werden verwendet:

SearchQueryService/3.5.0

In dieser Version wird die Unterstützung für den packageType Abfrageparameter und die packageTypes Antworteigenschaft eingeführt, wodurch das Filtern nach definierten Pakettypen durch Autor ermöglicht wird. Es ist vollständig abwärtskompatibel mit Abfragen zu SearchQueryService.

Basis-URL

Die Basis-URL für die folgende API ist der Wert der Eigenschaft, die @id einem der oben genannten Ressourcenwerte @type zugeordnet ist. Im folgenden Dokument wird die Platzhalterbasis-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, die in der Registrierungsressource gefunden werden, unterstützen die HTTP-Methoden GET und HEAD.

Nach Paketen suchen

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

Die Suchabfrage q wird auf eine Weise analysiert, die von der Serverimplementierung definiert wird. nuget.org unterstützt grundlegende Filterung für 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 NuGet-Visual Studio-Oberfläche aktiviert.

Der skip Parameter ist standardmäßig auf 0 festgelegt.

Der take Parameter sollte eine ganze Zahl größer als Null sein. Die Serverimplementierung kann einen Maximalwert erzwingen.

Falls prerelease nicht angegeben, werden Vorabpakete ausgeschlossen.

Der semVerLevel Abfrageparameter wird verwendet, um SemVer 2.0.0-Pakete zu aktivieren. Wenn dieser Abfrageparameter ausgeschlossen ist, werden nur Pakete mit semVer 1.0.0 kompatiblen Versionen zurückgegeben (mit den standardmäßigen Einschränkungen für die NuGet-Versionsverwaltung , z. B. Versionszeichenfolgen mit 4 ganzzahligen Teilen). Falls semVerLevel=2.0.0 angegeben, werden sowohl semVer 1.0.0- als auch SemVer 2.0.0-kompatible Pakete zurückgegeben. Weitere Informationen finden Sie in der SemVer 2.0.0-Unterstützung für nuget.org .

Der packageType Parameter wird verwendet, um die Suchergebnisse weiter auf Pakete zu filtern, die mindestens einen Pakettyp aufweisen, der dem Pakettypnamen entspricht. Wenn der angegebene Pakettyp kein gültiger Pakettyp ist, der durch das Dokument "Pakettyp" definiert ist, wird ein leeres Ergebnis zurückgegeben. Wenn der angegebene Pakettyp leer ist, wird kein Filter angewendet. Anders ausgedrückt verhält sich das Übergeben eines Werts an den packageType-Parameter so, als ob der Parameter nicht übergeben wurde.

Antwort

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

Das JSON-Stammobjekt weist die folgenden Eigenschaften auf:

Suchergebnis

Jedes Element 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:

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 finden Sie in der Dokumentation zur Reservierung von ID-Präfixen.

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

Paketdeprecation

Das deprecation-Objekt weist die folgenden Eigenschaften auf:

Das reasons Array enthält mindestens einen der Werte, die in der Paketdeprecation dokumentiert sind.

Das alternatePackage-Objekt weist die folgenden Eigenschaften auf:

Schwachstellen

Jedes Element im vulnerabilities Array ist ein JSON-Objekt mit den folgenden Eigenschaften:

Das Array ist leer, wenn die neueste Paketversion keine bekannten Sicherheitsrisiken aufweist.

Das packageTypes Array besteht immer aus mindestens einem (1) Element. 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. Jedes Element im packageTypes Array ist ein JSON-Objekt mit den folgenden Eigenschaften:

Musteranforderung

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 Abschnitt "Basis-URL " erwähnt.

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,
      "vulnerabilities": [],
      "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,
      "vulnerabilities": [],
      "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"
        }
      ]
    }
  ]
}