| title | description | author | ms.author | ms.date | ms.topic | ms.reviewer | ms.openlocfilehash | ms.sourcegitcommit | ms.translationtype | ms.contentlocale | ms.lasthandoff | ms.locfileid |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
Ressource catalogue, API NuGet v3 |
Le catalogue est un index de tous les packages créés et supprimés sur nuget.org. |
joelverhagen |
jver |
10/30/2017 |
reference |
kraigb |
6c04453fec9beb7b0998953384ec60694e1213c1 |
af059dc776cfdcbad20baab2919b5d6dc1e9022d |
MT |
fr-FR |
02/09/2021 |
99990145 |
Le catalogue est une ressource qui enregistre toutes les opérations de package sur une source de package, telles que les créations et les suppressions. La ressource de catalogue a le Catalog type dans l' index de service. Vous pouvez utiliser cette ressource pour Rechercher tous les packages publiés.
Note
Étant donné que le catalogue n’est pas utilisé par le client NuGet officiel, toutes les sources de package n’implémentent pas le catalogue.
Note
Actuellement, le catalogue nuget.org n’est pas disponible en Chine. Pour plus d’informations, consultez NuGet/NuGetGallery # 4949.
La @type valeur suivante est utilisée :
| Valeur @type | Notes |
|---|---|
| Catalogue/3.0.0 | La version initiale |
L’URL du point d’entrée pour les API suivantes est la valeur de la @id propriété associée aux valeurs de ressource mentionnées ci-dessus @type . Cette rubrique utilise l’URL de l’espace réservé {@id} .
Toutes les URL trouvées dans la ressource de catalogue prennent uniquement en charge les méthodes HTTP GET et HEAD .
L’index de catalogue est un document dans un emplacement connu qui contient une liste d’éléments de catalogue, classés par ordre chronologique. Il s’agit du point d’entrée de la ressource de catalogue.
L’index est constitué de pages de catalogue. Chaque page de catalogue contient des éléments de catalogue. Chaque élément de catalogue représente un événement concernant un package unique à un moment donné. Un élément de catalogue peut représenter un package qui a été créé, supprimé de la liste, rerépertorié ou supprimé de la source du package. En traitant les éléments de catalogue par ordre chronologique, le client peut créer une vue à jour de chaque package existant sur la source du package v3.
En bref, les objets BLOB de catalogue ont la structure hiérarchique suivante :
- Index: point d’entrée du catalogue.
- Page: regroupement d’éléments de catalogue.
- Feuille: document représentant un élément de catalogue, qui est un instantané de l’état d’un package unique.
Chaque objet Catalogue a une propriété appelée commitTimeStamp qui représente le moment où l’élément a été ajouté au catalogue. Les éléments de catalogue sont ajoutés à une page de catalogue par lots appelés validations. Tous les éléments de catalogue dans la même validation ont le même horodatage de validation ( commitTimeStamp ) et l’ID de validation ( commitId ). Les éléments de catalogue placés dans la même validation représentent des événements qui se sont produits à peu près au même point dans le temps de la source du package. Il n’y a aucun classement dans une validation de catalogue.
Étant donné que chaque ID de package et version est unique, il n’y aura jamais plus d’un élément de catalogue dans une validation. Cela permet de s’assurer que les éléments du catalogue d’un package unique peuvent toujours être triés sans ambiguïté par rapport au datage de validation.
Il n’y a jamais plus d’une validation dans le catalogue par commitTimeStamp . En d’autres termes, le commitId est redondant avec le commitTimeStamp .
Contrairement à la ressource de métadonnées du package, qui est indexée par ID de package, le catalogue est indexé (et peut être interrogé) uniquement par heure.
Les éléments de catalogue sont toujours ajoutés au catalogue dans un ordre chronologique croissant. Cela signifie que si une validation de catalogue est ajoutée à l’heure X, aucune validation de catalogue ne sera jamais ajoutée avec une heure inférieure ou égale à X.
La requête suivante extrait l’index du catalogue.
GET {@id}
L’index de catalogue est un document JSON qui contient un objet avec les propriétés suivantes :
| Nom | Type | Obligatoire | Notes |
|---|---|---|---|
| commitId | string | Oui | ID unique associé à la validation la plus récente |
| commitTimeStamp | string | Oui | Horodateur de la validation la plus récente |
| count | entier | Oui | Nombre de pages dans l’index |
| items | tableau d’objets | Oui | Tableau d’objets, chaque objet représentant une page |
Chaque élément du items tableau est un objet avec des détails minimes sur chaque page. Ces objets de page ne contiennent pas les feuilles de catalogue (éléments). L’ordre des éléments dans ce tableau n’est pas défini. Les pages peuvent être triées par le client en mémoire à l’aide de leur commitTimeStamp propriété.
À mesure que de nouvelles pages sont introduites, l' count est incrémenté et de nouveaux objets s’affichent dans le items tableau.
Au fur et à mesure que des éléments sont ajoutés au catalogue, l’index est commitId modifié et l' commitTimeStamp opération augmente. Ces deux propriétés sont essentiellement un résumé de toutes les pages commitId et commitTimeStamp valeurs du items tableau.
Les objets de page de catalogue trouvés dans la propriété de l’index de catalogue items ont les propriétés suivantes :
| Nom | Type | Obligatoire | Notes |
|---|---|---|---|
| @id | string | Oui | URL de récupération de la page de catalogue |
| commitId | string | Oui | ID unique associé à la validation la plus récente dans cette page |
| commitTimeStamp | string | Oui | Horodateur de la dernière validation dans cette page |
| count | entier | Oui | Nombre d’éléments dans la page de catalogue |
Contrairement à la ressource de métadonnées de package , qui, dans certains cas, insère des feuilles dans l’index, les feuilles de catalogue ne sont jamais inline dans l’index et doivent toujours être extraites à l’aide de l’URL de la page @id .
GET https://api.nuget.org/v3/catalog0/index.json
[!code-JSON catalog-index.json]
La page catalogue est une collection d’éléments de catalogue. Il s’agit d’un document extrait à l’aide de l’une des @id valeurs figurant dans l’index du catalogue. L’URL d’une page de catalogue n’est pas destinée à être prévisible et doit être découverte à l’aide de l’index de catalogue uniquement.
Les nouveaux éléments de catalogue sont ajoutés à la page dans l’index de catalogue uniquement avec l’horodateur de validation le plus élevé ou vers une nouvelle page. Une fois qu’une page avec un horodateur de validation plus élevé est ajoutée au catalogue, les anciennes pages ne sont jamais ajoutées ou modifiées.
Le document de page de catalogue est un objet JSON avec les propriétés suivantes :
| Nom | Type | Obligatoire | Notes |
|---|---|---|---|
| commitId | string | Oui | ID unique associé à la validation la plus récente dans cette page |
| commitTimeStamp | string | Oui | Horodateur de la dernière validation dans cette page |
| count | entier | Oui | Nombre d’éléments dans la page |
| items | tableau d’objets | Oui | Éléments du catalogue dans cette page |
| parent | string | Oui | URL de l’index du catalogue |
Chaque élément du items tableau est un objet avec des détails minimes sur l’élément du catalogue. Ces objets d’élément ne contiennent pas toutes les données de l’élément de catalogue. L’ordre des éléments dans le tableau de la page items n’est pas défini. Les éléments peuvent être triés par le client en mémoire à l’aide de leur commitTimeStamp propriété.
Le nombre d’éléments de catalogue dans une page est défini par l’implémentation du serveur. Pour nuget.org, il y a au plus 550 éléments dans chaque page, bien que le nombre réel puisse être plus petit pour certaines pages en fonction de la taille du lot de validation suivant à un moment donné.
À mesure que de nouveaux éléments sont introduits, le count est incrémenté et les nouveaux objets d’élément de catalogue apparaissent dans le items tableau.
À mesure que des éléments sont ajoutés à la page, les commitId modifications et commitTimeStamp augmentent. Ces deux propriétés sont essentiellement un résumé de toutes commitId les commitTimeStamp valeurs et dans le items tableau.
Les objets d’élément de catalogue trouvés dans la propriété de la page du catalogue items ont les propriétés suivantes :
| Nom | Type | Obligatoire | Notes |
|---|---|---|---|
| @id | string | Oui | URL permettant de récupérer l’élément de catalogue |
| @type | string | Oui | Type de l’élément de catalogue |
| commitId | string | Oui | ID de validation associé à cet élément de catalogue |
| commitTimeStamp | string | Oui | Horodatage de validation de cet élément de catalogue |
| NuGet : ID | string | Oui | ID de package associé à ce nœud terminal |
| NuGet : version | string | Oui | Version du package à laquelle cette feuille est associée |
La @type valeur sera l’une des deux valeurs suivantes :
nuget:PackageDetails: correspond auPackageDetailstype dans le document feuille du catalogue.nuget:PackageDelete: correspond auPackageDeletetype dans le document feuille du catalogue.
Pour plus d’informations sur la signification de chaque type, consultez le type d’élément correspondant ci-dessous.
GET https://api.nuget.org/v3/catalog0/page2926.json
[!code-JSON catalog-page.json]
Le catalogue feuille contient des métadonnées sur un ID de package et une version spécifiques à un moment donné. Il s’agit d’un document extrait à l’aide de la @id valeur trouvée dans une page de catalogue. L’URL d’une feuille de catalogue n’est pas destinée à être prévisible et doit être découverte à l’aide d’une page de catalogue uniquement.
Le document feuille du catalogue est un objet JSON avec les propriétés suivantes :
| Nom | Type | Obligatoire | Notes |
|---|---|---|---|
| @type | chaîne ou tableau de chaînes | Oui | Type (s) de l’élément de catalogue |
| Catalogue : commitId | string | Oui | ID de validation associé à cet élément de catalogue |
| Catalogue : commitTimeStamp | string | Oui | Horodatage de validation de cet élément de catalogue |
| id | string | Oui | ID de package de l’élément de catalogue |
| published | string | Oui | Date de publication de l’élément du catalogue de packages |
| version | string | Oui | Version du package de l’élément de catalogue |
La @type propriété est une chaîne ou un tableau de chaînes. Pour plus de commodité, si la @type valeur est une chaîne, elle doit être traitée comme n’importe quel tableau de taille 1. Toutes les valeurs possibles pour @type ne sont pas documentées. Toutefois, chaque élément de catalogue a exactement une des deux valeurs de type chaîne suivantes :
PackageDetails: représente un instantané des métadonnées du packagePackageDelete: représente un package qui a été supprimé.
Les éléments de catalogue avec le type PackageDetails contiennent un instantané des métadonnées du package pour un package spécifique (combinaison ID-version). Un élément de catalogue Détails du package est généré quand une source de package rencontre l’un des scénarios suivants :
- Un package fait l’objet d’un Push.
- Un package est listé.
- Un package n’est pas répertorié.
- Un package est redistribué.
Un redistribution de package est un geste administratif qui génère essentiellement un faux push d’un package existant sans modification du package lui-même. Sur nuget.org, un redistribution est utilisé après avoir corrigé un bogue dans l’une des tâches en arrière-plan qui consomment le catalogue.
Les clients qui utilisent les éléments du catalogue ne doivent pas tenter de déterminer lequel de ces scénarios a produit l’élément de catalogue. Au lieu de cela, le client doit simplement mettre à jour toute vue ou tout index géré avec les métadonnées contenues dans l’élément du catalogue. En outre, les éléments de catalogue dupliqués ou redondants doivent être gérés normalement (manière idempotente).
Détails du package les éléments du catalogue ont les propriétés suivantes en plus de celles incluses dans tous les feuilles de catalogue.
| Nom | Type | Obligatoire | Notes |
|---|---|---|---|
| authors | string | non | |
| created | string | non | Horodateur du moment où le package a été créé pour la première fois. Propriété de secours : published . |
| dependencyGroups | tableau d’objets | non | Les dépendances du package, regroupées par version cible du .NET Framework (même format que la ressource de métadonnées du package) |
| désapprobation | object | non | La désapprobation associée au package (même format que la ressource de métadonnées du package) |
| description | string | non | |
| iconUrl | string | non | |
| isPrerelease | boolean | non | Indique si la version du package est préliminaire. Peut être détecté à partir de version . |
| langage | string | non | |
| licenseUrl | string | non | |
| liste | boolean | non | Indique si le package est ou non listé |
| minClientVersion | string | non | |
| packageHash | string | Oui | Hachage du package, encodage à l’aide de la base standard 64 |
| packageHashAlgorithm | string | Oui | |
| empaqueter | entier | Oui | Taille du package. nupkg en octets |
| packageTypes | tableau d’objets | non | Types de packages spécifiés par l’auteur. |
| projectUrl | string | non | |
| releaseNotes | string | non | |
| requireLicenseAgreement | boolean | non | Supposer false si exclu |
| Récapitulatif | string | non | |
| tags | tableau de chaînes | non | |
| title | string | non | |
| verbatimVersion | string | non | Chaîne de version telle qu’elle est trouvée à l’origine dans le. NuSpec |
| vulnérabilités | tableau d’objets | non | Les failles de sécurité du package |
La propriété de package version est la chaîne de version complète après la normalisation. Cela signifie que les données de build SemVer 2.0.0 peuvent être incluses ici.
L' created horodateur est le moment où le package a été reçu pour la première fois par la source du package, ce qui correspond généralement à une brève période avant l’horodatage de validation de l’élément de catalogue.
packageHashAlgorithmEst une chaîne définie par l’implémentation de serveur qui représente l’algorithme de hachage utilisé pour produire le packageHash . nuget.org a toujours utilisé la packageHashAlgorithm valeur de SHA512 .
La packageTypes propriété est présente uniquement si un type de package a été spécifié par l’auteur. S’il est présent, il aura toujours au moins une entrée (1). Chaque élément du packageTypes tableau est un objet JSON avec les propriétés suivantes :
| Nom | Type | Obligatoire | Notes |
|---|---|---|---|
| name | string | Oui | Nom du type de package. |
| version | string | non | Version du type de package. Présent uniquement si l’auteur a spécifié explicitement une version dans le NuSpec. |
L' published horodateur est l’heure de la dernière liste du package.
Note
Sur nuget.org, la published valeur est définie sur l’année 1900 lorsque le package est non répertorié.
Tableau d'objets vulnerability. Chaque vulnérabilité a les propriétés suivantes :
| Nom | Type | Obligatoire | 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 |
Si la severity propriété contient des valeurs autres que celles répertoriées ici, la gravité de l’avis doit être considérée comme faible.
GET https://api.nuget.org/v3/catalog0/data/2015.02.01.11.18.40/windowsazure.storage.1.0.0.json
[!code-JSON catalog-package-details.json]
Les éléments de catalogue avec le type PackageDelete contiennent un ensemble minimal d’informations indiquant aux clients du catalogue qu’un package a été supprimé de la source du package et qu’il n’est plus disponible pour les opérations de package (telles que la restauration).
Note
Il est possible de supprimer un package et de le republier ultérieurement à l’aide du même ID de package et de la même version. Sur nuget.org, il s’agit d’un cas très rare, car il arrête l’hypothèse du client officiel qu’un ID de package et une version impliquent un contenu de package spécifique. Pour plus d’informations sur la suppression de packages sur nuget.org, consultez notre stratégie.
Les éléments du catalogue de suppression de package n’ont pas de propriétés supplémentaires en plus de celles incluses dans tous les feuilles de catalogue.
La version propriété est la chaîne de version d’origine trouvée dans le package. nuspec.
La published propriété est l’heure à laquelle le package a été supprimé, ce qui correspond généralement à une heure très brève avant l’horodateur de validation de l’élément de catalogue.
GET https://api.nuget.org/v3/catalog0/data/2017.11.02.00.40.00/netstandard1.4_lib.1.0.0-test.json
[!code-JSON catalog-package-delete.json]
Cette section décrit un concept client qui, bien qu’il ne soit pas obligatoirement obligatoire par le protocole, doit faire partie de toute implémentation de client de catalogue pratique.
Étant donné que le catalogue est une structure de données d’ajout uniquement indexée par heure, le client doit stocker un curseur localement, ce qui indique jusqu’à quel point dans le temps le client a traité les éléments du catalogue. Notez que cette valeur de curseur ne doit jamais être générée à l’aide de l’horloge de l’ordinateur du client. Au lieu de cela, la valeur doit provenir de la valeur d’un objet catalogue commitTimestamp .
Chaque fois que le client souhaite traiter de nouveaux événements sur la source du package, il doit uniquement interroger le catalogue pour tous les éléments du catalogue dont l’horodateur de validation est supérieur à celui de son curseur stocké. Une fois que le client a traité tous les nouveaux éléments de catalogue, il enregistre le dernier horodatage de validation des éléments de catalogue qui vient d’être traité comme sa nouvelle valeur de curseur.
À l’aide de cette approche, le client peut s’assurer de ne jamais manquer les événements de package qui se sont produits sur la source du package. En outre, le client n’a jamais à retraiter les anciens événements avant l’horodateur de validation enregistré du curseur.
Ce concept puissant de curseurs est utilisé pour de nombreuses tâches en arrière-plan nuget.org et est utilisé pour maintenir à jour l’API V3.
Quand le client de catalogue démarre pour la première fois (et qu’il n’a donc pas de valeur de curseur), il doit utiliser une valeur de curseur par défaut de. Le réseau System.DateTimeOffset.MinValue ou une certaine notion analogue de l’horodateur minimal représentable.
Pour interroger l’ensemble suivant d’éléments de catalogue à traiter, le client doit :
- Extrait la valeur de curseur enregistrée à partir d’un magasin local.
- Téléchargez et désérialisez l’index du catalogue.
- Recherche toutes les pages du catalogue dont l’horodateur de validation est supérieur au curseur.
- Déclarez une liste vide d’éléments de catalogue à traiter.
- Pour chaque page de catalogue correspondante à l’étape 3 :
- Téléchargez et désérialisez la page catalogue.
- Recherche tous les éléments du catalogue dont l’horodateur de validation est supérieur au curseur.
- Ajoutez tous les éléments de catalogue correspondants à la liste déclarée à l’étape 4.
- Trie la liste d’éléments de catalogue par horodatage de validation.
- Traiter chaque élément de catalogue dans l’ordre :
- Télécharger et désérialiser l’élément de catalogue.
- Réagissez en fonction du type de l’élément de catalogue.
- Traitez le document d’élément de catalogue de manière spécifique au client.
- Enregistrez le dernier horodatage de validation de l’élément de catalogue en tant que nouvelle valeur de curseur.
Avec cet algorithme de base, l’implémentation cliente peut générer une vue complète de tous les packages disponibles sur la source du package. Le client doit uniquement exécuter régulièrement cet algorithme pour connaître toujours les dernières modifications apportées à la source du package.
Note
Il s’agit de l’algorithme utilisé par nuget.org pour conserver les métadonnées du package, le contenu du package, la recherche et la saisie semi-automatique des ressources à jour.
Supposons que deux clients de catalogue possèdent une dépendance inhérente où la sortie d’un client dépend de la sortie d’un autre client.
Par exemple, sur nuget.org, un package qui vient d’être publié ne doit pas apparaître dans la ressource de recherche avant d’apparaître dans la ressource de métadonnées du package. Cela est dû au fait que l’opération de « restauration » effectuée par le client NuGet officiel utilise la ressource de métadonnées du package. Si un client Découvre un package à l’aide du service de recherche, il doit être en mesure de restaurer ce package à l’aide de la ressource de métadonnées du package. En d’autres termes, la ressource de recherche dépend de la ressource de métadonnées du package. Chaque ressource a une tâche en arrière-plan du client du catalogue qui met à jour cette ressource. Chaque client possède son propre curseur.
Étant donné que les deux ressources sont créées à partir du catalogue, le curseur du client de catalogue qui met à jour la ressource de recherche ne doit pas dépasser le curseur du client du catalogue de métadonnées du package.
Pour implémenter cette restriction, il vous suffit de modifier l’algorithme ci-dessus pour qu’il soit :
- Extrait la valeur de curseur enregistrée à partir d’un magasin local.
- Téléchargez et désérialisez l’index du catalogue.
- Recherche toutes les pages du catalogue dont l’horodateur de validation est supérieur au curseur inférieur ou égal au curseur de la dépendance.
- Déclarez une liste vide d’éléments de catalogue à traiter.
- Pour chaque page de catalogue correspondante à l’étape 3 :
- Téléchargez et désérialisez la page catalogue.
- Recherche tous les éléments du catalogue dont l’horodateur de validation est supérieur ou égal au curseur de la dépendance.
- Ajoutez tous les éléments de catalogue correspondants à la liste déclarée à l’étape 4.
- Trie la liste d’éléments de catalogue par horodatage de validation.
- Traiter chaque élément de catalogue dans l’ordre :
- Télécharger et désérialiser l’élément de catalogue.
- Réagissez en fonction du type de l’élément de catalogue.
- Traitez le document d’élément de catalogue de manière spécifique au client.
- Enregistrez le dernier horodatage de validation de l’élément de catalogue en tant que nouvelle valeur de curseur.
À l’aide de cet algorithme modifié, vous pouvez créer un système de clients de catalogue dépendants qui produisent tous leurs propres index, artefacts, etc.