Partager via


Recherche

Il est possible de rechercher des packages disponibles sur une source de package à l’aide de l’API V3. La ressource utilisée pour la recherche est la ressource SearchQueryService trouvée dans l’index de service.

Contrôle de version

Les valeurs @type suivantes sont utilisées :

Valeur @type Notes
SearchQueryService La version initiale
SearchQueryService/3.0.0-beta Alias de SearchQueryService
SearchQueryService/3.0.0-rc Alias de SearchQueryService
SearchQueryService/3.5.0 Inclut la prise en charge du paramètre de requête packageType

SearchQueryService/3.5.0

Cette version introduit la prise en charge du paramètre de requête packageType et de la propriété de réponse packageTypes, ce qui autorise le filtrage par types de package définis par l’auteur. Il est entièrement rétrocompatible avec les requêtes à SearchQueryService.

URL de base

L’URL de base de l’API suivante est la valeur de la propriété @id associée à l’une des valeurs de ressource @type mentionnées ci-dessus. Dans le document suivant, l’URL {@id} de base de l’espace réservé sera utilisée. L’URL de base peut changer en fonction de l’implémentation ou des modifications d’infrastructure dans la source du package. Elle doit donc être récupérée dynamiquement de l’index de service par le logiciel client.

Méthodes HTTP

Toutes les URL trouvées dans la ressource d’inscription prennent en charge les méthodes HTTP GET et HEAD.

Recherche de packages

L’API de recherche permet à un client d’interroger une page de packages correspondant à une requête de recherche spécifiée. L’interprétation de la requête de recherche (par ex. la jetonisation des termes de recherche) est déterminée par l’implémentation du serveur, mais l’attente générale est que la requête de recherche est utilisée pour les ID de package correspondants, les titres, les descriptions et les balises. D’autres champs de métadonnées de package peuvent également être pris en compte.

Un package non répertorié ne doit jamais apparaître dans les résultats de recherche.

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

Paramètres de la demande

Nom Dans Type Requise Notes
q URL string non Termes de recherche à utiliser pour filtrer les packages
skip URL entier non Nombre de résultats à ignorer, pour la pagination
take URL entier non Le nombre de résultats à renvoyer, pour la pagination
version préliminaire URL booléen non true ou false déterminer s’il faut inclure des packages de préversion
semVerLevel URL string non Chaîne de version SemVer 1.0.0
packageType URL string non Le type de package à utiliser pour filtrer les packages (ajoutés dans SearchQueryService/3.5.0)

La requête de recherche q est analysée de manière définie par l’implémentation du serveur. nuget.org prend en charge le filtrage de base sur une grande variété de champs. S’il n’est pas q fourni, tous les packages doivent être retournés, dans les limites imposées par ignorer et prendre. Cela active l’onglet « Parcourir » dans l’expérience NuGet Visual Studio.

La valeur par défaut du paramètre skip est 0.

Le paramètre take doit être un entier supérieur à zéro. L’implémentation du serveur peut imposer une valeur maximale.

Remarque

nuget.org limite le paramètre skip à 3,000 et le paramètre take à 1,000.

Si prerelease n’est pas fourni, les packages en préversion sont exclus.

Le paramètre de requête semVerLevel est utilisé pour opter pour les packages SemVer 2.0.0. Si ce paramètre de requête est exclu, seuls les packages avec les versions compatibles semVer 1.0.0 sont retournés (avec les mises en garde du contrôle de version NuGet standard, telles que les chaînes de version avec 4 éléments entiers). Si semVerLevel=2.0.0 est fourni, les packages compatibles SemVer 1.0.0 et SemVer 2.0.0 sont retournés. Pour plus d’informations, consultez le support de SemVer 2.0.0 pour nuget.org.

Le paramètre packageType est utilisé pour filtrer davantage les résultats de la recherche sur uniquement les packages qui ont au moins un type de package correspondant au nom du type de package. Si le type de package fourni n’est pas un type de package valide tel que défini par le document Type de package, un résultat vide est retourné. Si le type de package fourni est vide, aucun filtre n’est appliqué. En d’autres termes, la transmission d’aucune valeur au paramètre packageType se comporte comme si le paramètre n’a pas été transféré.

Response

La réponse est un document JSON contenant jusqu’à take résultats de recherche. Les résultats de la recherche sont regroupés par ID de package.

L’objet racine JSON dispose des propriétés suivantes :

Nom Type Requise Notes
totalHits entier Oui Le nombre total de correspondances, sans tenir compte de skip ni de take
données tableau d'objets Oui Résultats de la recherche mis en correspondance par la requête

Résultat de la recherche

Chaque article du data tableau est un objet JSON composé d’un groupe de versions de package partageant le même ID de package. L’objet dispose des propriétés suivantes :

Nom Type Requise Notes
id string Oui ID du package correspondant
version chaîne Oui La chaîne de version semVer 2.0.0 complète du package (peut contenir des métadonnées de version)
description string non
versions tableau d'objets Oui Toutes les versions du package correspondant au paramètre prerelease
authors chaîne ou tableau de chaînes non
iconUrl string non
licenseUrl string non
owners chaîne ou tableau de chaînes non Une chaîne représente le nom d’utilisateur d’un seul propriétaire
projectUrl string non
webappoidc string non L’URL absolue de l’index d’inscription associé
résumé string non
tags chaîne ou tableau de chaînes non
title string non
totalDownloads entier non Cette valeur peut être déduite par la somme des téléchargements dans le tableau versions
vérifié booléen non Un booléen JSON indiquant si le package est vérifié
packageTypes tableau d'objets Oui Types de package définis par l’auteur du package (ajouté dans SearchQueryService/3.5.0)

Sur nuget.org, un package vérifié est un package qui a un ID de package correspondant à un préfixe d’ID réservé et appartenant à l’un des propriétaires du préfixe réservé. Pour plus d’informations, consultez la documentation sur la réservation du préfixe d’ID.

Les métadonnées contenues dans l’objet de résultat de recherche sont extraites de la dernière version du package. Chaque article du tableau versions est un objet JSON avec les propriétés suivantes :

Nom Type Requise Notes
@id string Oui L’URL absolue de la feuille d’inscription associée
version chaîne Oui La chaîne de version semVer 2.0.0 complète du package (peut contenir des métadonnées de version)
téléchargements entier Oui Nombre de téléchargements pour cette version de package spécifique

Le tableau packageTypes se compose toujours d’au moins un (1) article. Le type de package pour un ID de package donné est considéré comme les types de package définis par la dernière version du package par rapport aux autres paramètres de recherche. Chaque article du tableau packageTypes est un objet JSON avec les propriétés suivantes :

Nom Type Requise Notes
name string Oui Le nom du type de package.

Exemple de requête

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

Veillez à récupérer l’URL de base (https://search-sample.nuget.org/query dans cet exemple) à partir de l’index de service, comme indiqué dans la section URL de base.

Exemple de réponse

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