Métadonnées de package

Article
12/22/2023

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

Partager via

Métadonnées de package

Contrôle de version

RegistrationsBaseUrl

RegistrationsBaseUrl/3.4.0

RegistrationsBaseUrl/3.6.0

URL de base

Méthodes HTTP

Problème inscription.

Pages d’inscription et feuilles

Paramètres de la demande

Response

Objet de page d’inscription

Objet feuille d’inscription dans une page

Entrée de catalogue

Groupe de dépendance de package

Dépendance de package

Dépréciation du package

Package de remplacement

Vulnerabilities

Exemple de requête

Exemple de réponse

Page Inscription

Exemple de requête

Exemple de réponse

Feuille d’inscription

Exemple de requête

Exemple de réponse

Commentaires

Ressources supplémentaires