Métadonnées de package
Il est possible de récupérer des métadonnées sur les packages disponibles sur une source de package à l’aide de l’API NuGet V3. Ces métadonnées peuvent être récupérées à l’aide de la ressource RegistrationsBaseUrl trouvée dans l’index de service.
La collection des documents trouvés sous RegistrationsBaseUrl sont souvent appelées « inscriptions » ou « objets blob d’inscription ». L’ensemble de documents sous un seul RegistrationsBaseUrl nom est appelé « hive d’inscription ». Une hive d’inscription contient des métadonnées sur chaque package disponible sur une source de package.
Remarque
La ressource de métadonnées de package ne contient pas toutes les métadonnées pour les packages. Utilisez la ressource de recherche pour rechercher les propriétaires, les téléchargements ou le statut de réservation de préfixe des packages.
Contrôle de version
Les valeurs @type suivantes sont utilisées :
| Valeur @type | Notes |
|---|---|
| RegistrationsBaseUrl | La version initiale |
| RegistrationsBaseUrl/3.0.0-beta | Alias de RegistrationsBaseUrl |
| RegistrationsBaseUrl/3.0.0-rc | Alias de RegistrationsBaseUrl |
| RegistrationsBaseUrl/3.4.0 | Réponses gzippées |
| RegistrationsBaseUrl/3.6.0 | Inclut les packages SemVer 2.0.0 |
Cela représente trois hives d’inscription distinctes disponibles pour différentes versions du client.
RegistrationsBaseUrl
Ces inscriptions ne sont pas compressées (ce qui signifie qu’elles utilisent un implicite Content-Encoding: identity). Les packages SemVer 2.0.0 sont exclus de ce hive.
RegistrationsBaseUrl/3.4.0
Ces inscriptions sont compressées à l’aide de Content-Encoding: gzip. Les packages SemVer 2.0.0 sont exclus de ce hive.
RegistrationsBaseUrl/3.6.0
Ces inscriptions sont compressées à l’aide de Content-Encoding: gzip. Les packages SemVer 2.0.0 sont inclus dans ce hive.
Pour plus d’informations sur SemVer 2.0.0, consultez la prise en charge de SemVer 2.0.0 pour nuget.org.
URL de base
L’URL de base pour les 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.
Problème inscription.
Métadonnées du package de groupes de ressources d’inscription par ID de package. Il n’est pas possible d’obtenir des données sur plusieurs ID de package à la fois. Cette ressource ne permet pas de découvrir les ID de package. Au lieu de cela, le client est supposé connaître déjà l’ID de package souhaité. Les métadonnées disponibles sur chaque version de package varient en fonction de l’implémentation du serveur. Les objets blob d’inscription de package ont la structure hiérarchique suivante :
- Index : point d’entrée pour les métadonnées du package, partagé par tous les packages sur une source avec le même ID de package.
- Page : regroupement de versions de package. Le nombre de versions de package d’une page est défini par l’implémentation du serveur.
- Feuille : document spécifique à une version de package unique.
L’URL de l’index d’inscription est prévisible et peut être déterminée par le client en fonction d’un ID de package et de la valeur @id de la ressource d’inscription à partir de l’index de service. Les URL des pages d’inscription et des feuilles sont découvertes en inspectant l’index d’inscription.
Pages d’inscription et feuilles
Bien qu’il ne soit pas strictement nécessaire pour une implémentation de serveur de stocker les feuilles d’inscription dans des documents de page d’inscription distincts, il est recommandé de conserver la mémoire côté client. Au lieu d’inclure toutes les feuilles d’inscription dans l’index ou de stocker immédiatement les feuilles dans les documents de page, il est recommandé que l’implémentation du serveur définisse une certaine heuristique pour choisir entre les deux approches en fonction du nombre de versions de package ou de la taille cumulative des feuilles de package.
Le stockage de toutes les versions de package (feuilles) dans l’index d’inscription enregistre le nombre de demandes HTTP nécessaires pour récupérer les métadonnées du package, mais signifie qu’un document plus volumineux doit être téléchargé et que la mémoire du client doit être allouée. En revanche, si l’implémentation du serveur stocke immédiatement les feuilles d’inscription dans des documents de page distincts, le client doit effectuer davantage de demandes HTTP pour obtenir les informations dont il a besoin.
L’heuristique que nuget.org utilise est la suivante : s’il existe 128 versions ou plus d’un package, divisez les feuilles en pages de taille 64. S’il existe moins de 128 versions, incluez toutes les feuilles dans l’index d’inscription. Notez que cela signifie que les packages avec des versions 65 à 127 auront deux pages dans l’index, mais les deux pages seront incluses.
GET {@id}/{LOWER_ID}/index.json
Paramètres de la demande
| Nom | Dans | Type | Requise | Notes |
|---|---|---|---|---|
| LOWER_ID | URL | string | Oui | L’ID du package, en minuscules |
La valeur LOWER_ID est l’ID de package souhaité en minuscules à l’aide des règles implémentées par la méthode de NET System.String.ToLowerInvariant().
Response
La réponse est un document JSON qui a un objet racine avec les propriétés suivantes :
| Nom | Type | Requise | Notes |
|---|---|---|---|
| count | entier | Oui | Le nombre de page d’inscription dans l’index |
| items | tableau d'objets | Oui | Le tableau de pages d’inscription |
Chaque article du tableau de l’objet items d’index est un objet JSON représentant une page d’inscription.
Objet de page d’inscription
L’objet de page d’inscription trouvé dans l’index d’inscription a les propriétés suivantes :
| Nom | Type | Requise | Notes |
|---|---|---|---|
| @id | string | Oui | L'URL de la page d'inscription |
| count | entier | Oui | Le nombre de feuilles d’inscription dans la page |
| items | tableau d'objets | non | Le tableau de feuilles d’inscription et leurs métadonnées associées |
| lower | string | Oui | La version la plus inférieure de SemVer 2.0.0 dans la page (inclusive) |
| parent | string | non | L’URL de l’index d’inscription |
| upper | string | Oui | La version semVer 2.0.0 la plus supérieure dans la page (inclusive) |
Les limites lower et upper de l’objet de page sont utiles lorsque les métadonnées d’une version de page spécifique sont nécessaires.
Ces limites peuvent être utilisées pour récupérer la seule page d’inscription nécessaire. Les chaînes de version respectent les règles de version de NuGet. Les chaînes de version sont normalisées et n’incluent pas les métadonnées de version. Comme pour toutes les versions de l’écosystème NuGet, la comparaison des chaînes de version est implémentée à l’aide des règles de précédence de version de SemVer 2.0.0.
La propriété parent s’affiche uniquement si l’objet de page d’inscription a la propriété items.
Si la propriété items n’est pas présente dans l’objet de page d’inscription, l’URL spécifiée dans le fichier @id doit être utilisée pour récupérer des métadonnées sur les versions de package individuelles. Le tableau items est parfois exclu de l’objet de page comme optimisation. Si le nombre de versions d’un ID de package unique est très volumineux, le document d’index d’inscription sera massif et gaspille à traiter pour un client qui se soucie uniquement d’une version spécifique ou d’une petite plage de versions.
Notez que si la propriété items est présente, la propriété @id n’a pas besoin d’être utilisée, car toutes les données de page sont déjà incluses dans la propriété items.
Chaque article du tableau items de l’objet de page est un objet JSON représentant une feuille d’inscription et ses métadonnées associées.
Objet feuille d’inscription dans une page
L’objet feuille d’inscription trouvé dans une page d’inscription a les propriétés suivantes :
| Nom | Type | Requise | Notes |
|---|---|---|---|
| @id | string | Oui | L’URL de la feuille d’inscription |
| catalogEntry | object | Oui | Entrée de catalogue contenant les métadonnées du package |
| packageContent | string | Oui | L’URL du contenu du package (.nupkg) |
Chaque objet feuille d’inscription représente les données associées à une version de package unique.
Entrée de catalogue
La propriété catalogEntry de l’objet feuille d’inscription a les propriétés suivantes :
| Nom | Type | Requise | Notes |
|---|---|---|---|
| @id | string | Oui | URL du document utilisé pour produire cet objet |
| authors | chaîne ou tableau de chaînes | non | |
| dependencyGroups | tableau d'objets | non | Dépendances du package, regroupées par version cible de .Net Framework |
| abandon | object | non | L’abandon associé au package |
| description | string | non | |
| iconUrl | string | non | |
| id | string | Oui | L’ID du package |
| langue | string | non | |
| licenseUrl | string | non | |
| licenseExpression | string | non | |
| liste | booléen | non | Doit être considéré comme étant répertorié s’il est absent |
| minClientVersion | string | non | |
| packageContent | string | non | Dupliquez la même propriété dans l’objet parent, incluse uniquement pour des raisons héritées |
| projectUrl | string | non | |
| published | string | non | Une chaîne contenant un horodatage ISO 8601 de la publication du package |
| readmeUrl | string | non | URL de la vue de rendu (page web HTML) du package README |
| requireLicenseAcceptance | booléen | non | |
| résumé | string | non | |
| tags | chaîne ou tableau de chaînes | non | |
| title | string | non | |
| version | chaîne | Oui | Chaîne de version complète après la normalisation |
| vulnerabilities | tableau d'objets | non | Les vulnérabilités de sécurité du package |
La propriété du package version est la chaîne de version complète après la normalisation. Cela signifie que les données de version SemVer 2.0.0 peuvent être incluses ici.
La propriété dependencyGroups est un tableau d’objets représentant les dépendances du package, regroupés par version cible de .Net Framework. Si le package n’a aucune dépendance, la propriété dependencyGroups est manquante, un tableau vide ou la propriété dependencies de tous les groupes est vide ou manquante.
La valeur de la propriété licenseExpression est conforme à la syntaxe de l’expression de licence NuGet.
Remarque
Sur nuget.org, la valeur published est définie sur l’année 1900 lorsque le package n’est pas répertorié.
Groupe de dépendance de package
Chaque objet de groupe de dépendances a les propriétés suivantes :
| Nom | Type | Requise | Notes |
|---|---|---|---|
| targetFramework | string | non | Version cible de .Net Frameworkcible à laquelle ces dépendances s’appliquent |
| dependencies | tableau d'objets | non |
La chaîne targetFramework utilise le format implémenté par la bibliothèque .NET nuGet.Frameworks de NuGet. Si aucune targetFramework n’est spécifiée, le groupe de dépendances s’applique à toutes les versions cibles de .Net Framework.
La propriété dependencies est un tableau d’objets, chacun représentant une dépendance de package du package actuel.
Dépendance de package
Chaque dépendance de package a les propriétés suivantes.
| Nom | Type | Requise | Notes |
|---|---|---|---|
| id | string | Oui | L’ID de dépendance de package |
| range | object | non | Plage de version autorisée de la dépendance |
| webappoidc | string | non | L’URL de l’index d’inscription pour cette dépendance |
Si la propriété range est exclue ou une chaîne vide, le client doit être défini par défaut sur la plage de versions (, ). Autrement dit, toute version de la dépendance est autorisée. La valeur de * n'est pas autorisée pour la propriété range.
Dépréciation du package
Chaque abandon de package a les propriétés suivantes :
| Nom | Type | Requise | Notes |
|---|---|---|---|
| motifs | tableau de chaînes | Oui | Les raisons pour lesquelles le package a été déconseillé |
| message | string | non | Détails supplémentaires sur cette abandon |
| alternatePackage | object | non | Le package de remplacement qui doit être utilisé à la place |
La propriété reasons doit contenir au moins une chaîne et ne doit contenir que des chaînes du tableau suivant :
| Motif | Description |
|---|---|
| Ancien | Le package n’est plus maintenu |
| CriticalBugs | Le package comporte des bogues qui le rendent inadapté à l’utilisation |
| Autres | Le package est déconseillé en raison d’une raison qui ne figure pas dans cette liste |
Si la propriété reasons contient des chaînes qui ne proviennent pas du jeu connu, elles doivent être ignorées. Les chaînes ne respectent pas la casse. Par conséquent, legacy doivent être traitées de la même façon que Legacy. Il n’existe aucune restriction d’ordre sur le tableau, de sorte que les chaînes peuvent être organisées dans n’importe quel ordre arbitraire. En outre, si la propriété contient uniquement des chaînes qui ne proviennent pas de l’ensemble connu, elle doit être traitée comme si elle contenait uniquement la chaîne « Other ».
Package de remplacement
L’objet de package de remplacement comporte les propriétés suivantes :
| Nom | Type | Requise | Notes |
|---|---|---|---|
| id | string | Oui | L’ID du package de remplacement |
| range | object | non | Plage de versions autorisée, ou * si une version est autorisée |
Vulnerabilities
Tableau d'objets vulnerability. Chaque vulnérabilité contient les propriétés suivantes :
| Nom | Type | Requise | Notes |
|---|---|---|---|
| advisoryUrl | string | Oui | Emplacement de l’avis de sécurité pour le package |
| severity | string | Oui | Gravité de l’avis : « 0 » = Faible, « 1 » = Modéré, « 2 » = Élevé, « 3 » = Critique |
Exemple de requête
GET https://api.nuget.org/v3/registration-sample/nuget.server.core/index.json
Veillez à récupérer l’URL de base (https://api.nuget.org/v3/registration-sample/ dans cet exemple) à partir de l’index de service, comme indiqué dans la section URL de base.
Exemple de réponse
{
"count": 1,
"items": [
{
"@id": "https://api.nuget.org/v3/registration-sample/nuget.server.core/index.json#page/3.0.0-beta/3.0.0-beta",
"count": 1,
"items": [
{
"@id": "https://api.nuget.org/v3/registration-sample/nuget.server.core/3.0.0-beta.json",
"catalogEntry": {
"@id": "https://api.nuget.org/v3/catalog0/data/2017.10.05.18.41.33/nuget.server.core.3.0.0-beta.json",
"authors": ".NET Foundation",
"dependencyGroups": [
{
"@id": "https://api.nuget.org/v3/catalog0/data/2017.10.05.18.41.33/nuget.server.core.3.0.0-beta.json#dependencygroup",
"dependencies": [
{
"@id": "https://api.nuget.org/v3/catalog0/data/2017.10.05.18.41.33/nuget.server.core.3.0.0-beta.json#dependencygroup/nuget.core",
"id": "NuGet.Core",
"range": "[2.14.0, )",
"registration": "https://api.nuget.org/v3/registration-sample/nuget.core/index.json"
}
]
}
],
"description": "Core library for creating a Web Application used to host a simple NuGet feed",
"iconUrl": "",
"id": "NuGet.Server.Core",
"language": "",
"licenseUrl": "https://raw.githubusercontent.com/NuGet/NuGet.Server/dev/LICENSE.txt",
"listed": true,
"minClientVersion": "2.6",
"packageContent": "https://api.nuget.org/v3-flatcontainer/nuget.server.core/3.0.0-beta/nuget.server.core.3.0.0-beta.nupkg",
"projectUrl": "https://github.com/NuGet/NuGet.Server",
"published": "2017-10-05T18:40:32.43+00:00",
"requireLicenseAcceptance": false,
"summary": "",
"tags": [ "" ],
"title": "",
"version": "3.0.0-beta",
"vulnerabilities": [
{
"advisoryUrl": "https://github.com/advisories/ABCD-1234-5678-9012",
"severity": "2"
}
]
},
"packageContent": "https://api.nuget.org/v3-flatcontainer/nuget.server.core/3.0.0-beta/nuget.server.core.3.0.0-beta.nupkg",
"registration": "https://api.nuget.org/v3/registration-sample/nuget.server.core/index.json"
}
],
"lower": "3.0.0-beta",
"upper": "3.0.0-beta"
}
]
}
Dans ce cas particulier, l’index d’inscription a la page d’inscription incluse afin qu’aucune demande supplémentaire ne soit nécessaire pour extraire des métadonnées sur les versions de package individuelles.
Page Inscription
La page d’inscription contient des feuilles d’inscription. L’URL permettant de récupérer une page d’inscription est déterminée par la propriété @idde l’objet de page d’inscription mentionné ci-dessus. L’URL n’est pas destinée à être prévisible et doit toujours être découverte par le biais du document d’index.
Avertissement
Sur nuget.org, l’URL du document de page d’inscription contient par coïncidence la limite inférieure et supérieure de la page. Toutefois, cette hypothèse ne doit jamais être effectuée par un client car les implémentations de serveur sont libres de modifier la forme de l’URL tant que le document d’index a un lien valide.
Lorsque le tableau items n’est pas fourni dans l’index d’inscription, une requête HTTP GET de la valeur @id retourne un document JSON qui a un objet comme racine. L’objet dispose des propriétés suivantes :
| Nom | Type | Requise | Notes |
|---|---|---|---|
| @id | string | Oui | L'URL de la page d'inscription |
| count | entier | Oui | Le nombre de feuilles d’inscription dans la page |
| items | tableau d'objets | Oui | Le tableau de feuilles d’inscription et leurs métadonnées associées |
| lower | string | Oui | La version la plus inférieure de SemVer 2.0.0 dans la page (inclusive) |
| parent | string | Oui | L’URL de l’index d’inscription |
| upper | string | Oui | La version semVer 2.0.0 la plus supérieure dans la page (inclusive) |
La forme des objets de la feuille d’inscription est la même que dans l’index d’inscription ci-dessus.
Exemple de requête
GET https://api.nuget.org/v3/registration-sample/ravendb.client/page/1.0.531/1.0.729-unstable.json
Veillez à récupérer l’URL de base (https://api.nuget.org/v3/registration-sample/ dans cet exemple) à partir de l’index de service, comme indiqué dans la section URL de base.
Exemple de réponse
{
"count": 2,
"lower": "1.0.531",
"parent": "https://api.nuget.org/v3/registration-sample/nuget.protocol.v3.example/index.json",
"upper": "1.0.729-unstable",
"items": [
{
"@id": "https://api.nuget.org/v3/registration-sample/nuget.protocol.v3.example/1.0.531.json",
"@type": "Package",
"commitId": "e0b9ca79-75b5-414f-9e3e-de9534b5cfd1",
"commitTimeStamp": "2017-10-26T14:12:19.3439088Z",
"catalogEntry": {
"@id": "https://api.nuget.org/v3/catalog0/data/2015.02.01.11.38.37/nuget.protocol.v3.example.1.0.531.json",
"@type": "PackageDetails",
"authors": "NuGet.org Team",
"iconUrl": "https://www.nuget.org/Content/gallery/img/default-package-icon.svg",
"id": "NuGet.Protocol.V3.Example",
"licenseUrl": "http://www.opensource.org/licenses/ms-pl",
"listed": false,
"packageContent": "https://api.nuget.org/v3-flatcontainer/nuget.protocol.v3.example/1.0.531/nuget.protocol.v3.example.1.0.531.nupkg",
"projectUrl": "https://github.com/NuGet/NuGetGallery",
"published": "1900-01-01T00:00:00+00:00",
"requireLicenseAcceptance": true,
"title": "NuGet V3 Protocol Example",
"version": "1.0.531"
},
"packageContent": "https://api.nuget.org/v3-flatcontainer/nuget.protocol.v3.example/1.0.531/nuget.protocol.v3.example.1.0.531.nupkg",
"registration": "https://api.nuget.org/v3/registration-sample/nuget.protocol.v3.example/index.json"
},
{
"@id": "https://api.nuget.org/v3/registration-sample/nuget.protocol.v3.example/1.0.729-unstable.json",
"@type": "Package",
"commitId": "e0b9ca79-75b5-414f-9e3e-de9534b5cfd1",
"commitTimeStamp": "2017-10-26T14:12:19.3439088Z",
"catalogEntry": {
"@id": "https://api.nuget.org/v3/catalog0/data/2015.02.01.18.22.05/nuget.protocol.v3.example.1.0.729-unstable.json",
"@type": "PackageDetails",
"authors": "NuGet.org Team",
"deprecation": {
"reasons": [
"CriticalBugs"
],
"message": "This package is unstable and broken!",
"alternatePackage": {
"id": "Newtonsoft.JSON",
"range": "12.0.2"
}
},
"iconUrl": "https://www.nuget.org/Content/gallery/img/default-package-icon.svg",
"id": "NuGet.Protocol.V3.Example",
"licenseUrl": "http://www.opensource.org/licenses/ms-pl",
"listed": false,
"packageContent": "https://api.nuget.org/v3-flatcontainer/nuget.protocol.v3.example/1.0.729-unstable/nuget.protocol.v3.example.1.0.729-unstable.nupkg",
"projectUrl": "https://github.com/NuGet/NuGetGallery",
"published": "1900-01-01T00:00:00+00:00",
"requireLicenseAcceptance": true,
"summary": "This package is an example for the V3 protocol.",
"title": "NuGet V3 Protocol Example",
"version": "1.0.729-Unstable"
},
"packageContent": "https://api.nuget.org/v3-flatcontainer/nuget.protocol.v3.example/1.0.729-unstable/nuget.protocol.v3.example.1.0.729-unstable.nupkg",
"registration": "https://api.nuget.org/v3/registration-sample/nuget.protocol.v3.example/index.json"
}
]
}
Feuille d’inscription
La feuille d’inscription contient des informations sur un ID de package et une version spécifiques. Les métadonnées relatives à la version spécifique peuvent ne pas être disponibles dans ce document. Les métadonnées du package doivent être récupérées dans l’index d’inscription ou de la page d’inscription (découverte à l’aide de l’index d’inscription).
L’URL permettant de récupérer une feuille d’inscription est obtenue à partir de la propriété @id d’un objet feuille d’inscription dans un index d’inscription ou une page d’inscription. Comme avec le document de page. l’URL n’est pas destinée à être prévisible et doit toujours être découverte par le biais de l’objet de page d’inscription.
Avertissement
Sur nuget.org, l’URL du document feuille d’inscription contient par coïncidence la version du package. Toutefois, cette hypothèse ne doit jamais être effectuée par un client car les implémentations de serveur sont libres de modifier la forme de l’URL tant que le document parent a un lien valide.
La feuille d’inscription est un document JSON avec un objet racine avec les propriétés suivantes :
| Nom | Type | Requise | Notes |
|---|---|---|---|
| @id | string | Oui | L’URL de la feuille d’inscription |
| catalogEntry | string | non | URL de l’entrée de catalogue qui a produit ces feuilles |
| liste | booléen | non | Doit être considéré comme étant répertorié s’il est absent |
| packageContent | string | non | L’URL du contenu du package (.nupkg) |
| published | string | non | Une chaîne contenant un horodatage ISO 8601 de la publication du package |
| webappoidc | string | non | L’URL de l’index d’inscription |
Remarque
Sur nuget.org, la valeur published est définie sur l’année 1900 lorsque le package n’est pas répertorié.
Exemple de requête
GET https://api.nuget.org/v3/registration-sample/nuget.versioning/4.3.0.json
Veillez à récupérer l’URL de base (https://api.nuget.org/v3/registration-sample/ dans cet exemple) à partir de l’index de service, comme indiqué dans la section URL de base.
Exemple de réponse
{
"@id": "https://api.nuget.org/v3/registration-sample/nuget.versioning/4.3.0.json",
"catalogEntry": "https://api.nuget.org/v3/catalog0/data/2017.08.11.18.24.22/nuget.versioning.4.3.0.json",
"listed": true,
"packageContent": "https://api.nuget.org/v3-flatcontainer/nuget.versioning/4.3.0/nuget.versioning.4.3.0.nupkg",
"published": "2017-08-11T18:24:14.36+00:00",
"registration": "https://api.nuget.org/v3/registration-sample/nuget.versioning/index.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