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 | |
| 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"
}
]
}
]
}
Commentaires
Bientôt disponible : Tout au long de 2024, nous allons supprimer progressivement GitHub Issues comme mécanisme de commentaires pour le contenu et le remplacer par un nouveau système de commentaires. Pour plus d’informations, consultez https://aka.ms/ContentUserFeedback.
Envoyer et afficher des commentaires pour