Recherche

Article
12/22/2023

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

Partager via