Partager via


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