API du serveur NuGetNuGet Server API

L’API serveur NuGet est un ensemble de points de terminaison HTTP qui peuvent être utilisés pour télécharger des packages, récupérer des métadonnées, publier de nouveaux packages et effectuer la plupart des autres opérations disponibles dans les clients NuGet officiels.The NuGet Server API is a set of HTTP endpoints that can be used to download packages, fetch metadata, publish new packages, and perform most other operations available in the official NuGet clients.

Cette API est utilisée par le client NuGet dans Visual Studio, NuGet. exe et l’interface CLI .net pour effectuer des opérations NuGet telles dotnet restoreque, effectuer une recherche dans l’interface utilisateur nuget.exe pushde Visual Studio, et.This API is used by the NuGet client in Visual Studio, nuget.exe, and the .NET CLI to perform NuGet operations such as dotnet restore, search in the Visual Studio UI, and nuget.exe push.

Remarque dans certains cas, nuget.org a des exigences supplémentaires qui ne sont pas appliquées par d’autres sources de package.Note in some cases, nuget.org has additional requirements that are not enforced by other package sources. Ces différences sont documentées par les protocoles NuGet.org.These differences are documented by the nuget.org Protocols.

Pour une énumération simple et le téléchargement des versions de NuGet. exe disponibles, consultez le point de terminaison Tools. JSON .For a simple enumeration and download of available nuget.exe versions, see the tools.json endpoint.

Index de serviceService index

Le point d’entrée de l’API est un document JSON dans un emplacement bien connu.The entry point for the API is a JSON document in a well known location. Ce document est appelé « index de service».This document is called the service index. L’emplacement de l’index de service pour nuget.org https://api.nuget.org/v3/index.jsonest.The location of the service index for nuget.org is https://api.nuget.org/v3/index.json.

Ce document JSON contient une liste de ressources qui fournissent différentes fonctionnalités et remplissent différents cas d’usage.This JSON document contains a list of resources which provide different functionality and fulfill different use cases.

Les clients qui prennent en charge l’API doivent accepter une ou plusieurs de ces URL d’index de service comme moyen de se connecter aux sources de package respectives.Clients that support the API should accept one or more of these service index URL as the means of connecting to the respective package sources.

Pour plus d’informations sur l’index de service, consultez la référence de son API.For more information about the service index, see its API reference.

Gestion de versionVersioning

L’API est la version 3 du protocole HTTP de NuGet.The API is version 3 of NuGet's HTTP protocol. Ce protocole est parfois appelé «API V3».This protocol is sometimes referred to as "the V3 API". Ces documents de référence feront référence à cette version du protocole simplement comme «l’API».These reference documents will refer to this version of the protocol simply as "the API."

La version du schéma d’index de service est version indiquée par la propriété dans l’index de service.The service index schema version is indicated by the version property in the service index. L’API impose que la chaîne de version ait un numéro de version principale 3de.The API mandates that the version string has a major version number of 3. À mesure que des modifications sans rupture sont apportées au schéma d’index de service, la version mineure de la chaîne de version est augmentée.As non-breaking changes are made to the service index schema, the version string's minor version will be increased.

Les clients plus anciens (tels que NuGet. exe 2. x) ne prennent pas en charge l’API V3 et ne prennent en charge que l’ancienne API v2, qui n’est pas documentée ici.Older clients (such as nuget.exe 2.x) do not support the V3 API and only support the older V2 API, which is not documented here.

L’API NuGet v3 est nommée comme telle, car il s’agit du successeur de l’API v2, qui était le protocole OData implémenté par la version 2. x du client officiel NuGet.The NuGet V3 API is named as such because it's the successor of the V2 API, which was the OData-based protocol implemented by the 2.x version of the official NuGet client. L’API V3 était d’abord prise en charge par la version 3,0 du client officiel NuGet. il s’agit toujours de la dernière version de protocole prise en charge par le client NuGet, 4,0 et on.The V3 API was first supported by the 3.0 version of the official NuGet client and is still the latest major protocol version supported by the NuGet client, 4.0 and on.

Des modifications de protocole sans rupture ont été apportées à l’API depuis sa première publication.Non-breaking protocol changes have been made to the API since it was first released.

Ressources et schémaResources and schema

L' index de service décrit une variété de ressources.The service index describes a variety of resources. L’ensemble actuel des ressources prises en charge est le suivant:The current set of supported resources are as follows:

Nom de la ressourceResource name ObligatoireRequired DescriptionDescription
CatalogueCatalog Nonno Enregistrement complet de tous les événements de package.Full record of all package events.
PackageBaseAddressPackageBaseAddress ouiyes Obtient le contenu du package (. nupkg).Get package content (.nupkg).
PackageDetailsUriTemplatePackageDetailsUriTemplate Nonno Construisez une URL pour accéder à une page Web Détails du package.Construct a URL to access a package details web page.
PackagePublishPackagePublish ouiyes Packages push et Delete (ou annulation de la liste).Push and delete (or unlist) packages.
RegistrationsBaseUrlRegistrationsBaseUrl ouiyes Obtient les métadonnées du package.Get package metadata.
ReportAbuseUriTemplateReportAbuseUriTemplate Nonno Construisez une URL pour accéder à une page Web de rapport abus.Construct a URL to access a report abuse web page.
RepositorySignaturesRepositorySignatures Nonno Obtenir les certificats utilisés pour la signature du dépôt.Get certificates used for repository signing.
SearchAutocompleteServiceSearchAutocompleteService Nonno Détection des ID de package et des versions par sous-chaîne.Discover package IDs and versions by substring.
SearchQueryServiceSearchQueryService ouiyes Filtrez et recherchez des packages par mot clé.Filter and search for packages by keyword.
SymbolPackagePublishSymbolPackagePublish Nonno Envoyer des packages de symboles.Push symbol packages.

En général, toutes les données non binaires retournées par une ressource d’API sont sérialisées à l’aide de JSON.In general, all non-binary data returned by a API resource are serialized using JSON. Le schéma de réponse retourné par chaque ressource dans l’index de service est défini individuellement pour cette ressource.The response schema returned by each resource in the service index is defined individually for that resource. Pour plus d’informations sur chaque ressource, consultez les rubriques indiquées ci-dessus.For more information about each resource, see the topics listed above.

À l’avenir, à mesure que le protocole évolue, de nouvelles propriétés peuvent être ajoutées aux réponses JSON.In the future, as the protocol evolves, new properties may be added to JSON responses. Pour que le client soit à l’avenir, l’implémentation ne doit pas supposer que le schéma de réponse est final et ne peut pas inclure de données supplémentaires.For the client to be future-proof, the implementation should not assume that the response schema is final and cannot include extra data. Toutes les propriétés que l’implémentation ne comprend pas doivent être ignorées.All properties that the implementation does not understand should be ignored.

Notes

Lorsqu’une source n’implémente SearchAutocompleteService aucun comportement de saisie semi-automatique doit être désactivée normalement.When a source does not implement SearchAutocompleteService any autocomplete behavior should be disabled gracefully. Lorsque ReportAbuseUriTemplate n’est pas implémenté, le client NuGet officiel revient à l’URL d’abus des rapports de NuGet. org (suivie par NuGet/4924).When ReportAbuseUriTemplate is not implemented, the official NuGet client falls back to nuget.org's report abuse URL (tracked by NuGet/Home#4924). D’autres clients peuvent choisir de ne pas afficher une URL d’abus de rapport à l’utilisateur.Other clients may opt to simply not show a report abuse URL to the user.

Ressources non documentées sur nuget.orgUndocumented resources on nuget.org

L’index du service v3 sur nuget.org contient des ressources qui ne sont pas documentées ci-dessus.The V3 service index on nuget.org has some resources that are not documented above. Il existe plusieurs raisons pour lesquelles il n’est pas possible de documenter une ressource.There are a few reasons for not documenting a resource.

Tout d’abord, nous ne documentons pas les ressources utilisées en tant que détail d’implémentation de nuget.org. Le SearchGalleryQueryService se trouve dans cette catégorie.First, we don't document resources used as an implementation detail of nuget.org. The SearchGalleryQueryService falls into this category. NuGetGallery utilise cette ressource pour déléguer certaines requêtes v2 (OData) à notre index de recherche au lieu d’utiliser la base de données.NuGetGallery uses this resource to delegate some V2 (OData) queries to our search index instead of using the database. Cette ressource a été introduite pour des raisons d’évolutivité et n’est pas destinée à un usage externe.This resource was introduced for scalability reasons and is not intended for external use.

Deuxièmement, nous ne documentons pas les ressources qui ne sont jamais fournies dans une version RTM du client officiel.Second, we don't document resources that never shipped in an RTM version of the official client. PackageDisplayMetadataUriTemplateet PackageVersionDisplayMetadataUriTemplate appartiennent à cette catégorie.PackageDisplayMetadataUriTemplate and PackageVersionDisplayMetadataUriTemplate fall into this category.

Troisièmement, nous ne documentons pas les ressources qui sont étroitement couplées avec le protocole v2, qui lui-même est intentionnellement non documenté.Thirdly, we don't document resources that are tightly coupled with the V2 protocol, which itself is intentionally undocumented. La LegacyGallery ressource appartient à cette catégorie.The LegacyGallery resource falls into this category. Cette ressource permet à un index de service v3 de pointer vers une URL source v2 correspondante.This resource allows a V3 service index to point to a corresponding V2 source URL. Cette ressource prend en nuget.exe listcharge.This resource supports the nuget.exe list.

Si une ressource n’est pas documentée ici , nous vous recommandons vivement de ne pas dépendre de celle-ci.If a resource is not documented here, we strongly recommend that you do not take a dependency on them. Nous pouvons supprimer ou modifier le comportement de ces ressources non documentées, ce qui pourrait perturber votre implémentation de manière inattendue.We may remove or change the behavior of these undocumented resources which could break your implementation in unexpected ways.

HorodatagesTimestamps

Tous les horodateurs retournés par l’API sont au format UTC ou sont spécifiés à l’aide d’une représentation ISO 8601 .All timestamps returned by the API are UTC or are otherwise specified using ISO 8601 representation.

Méthodes HTTPHTTP methods

DoVerbVerb UtilisezUse
GETGET Effectue une opération en lecture seule, en général la récupération des données.Performs a read-only operation, typically retrieving data.
HEADHEAD Récupère les en-têtes de réponse pour la GET requête correspondante.Fetches the response headers for the corresponding GET request.
PUTPUT Crée une ressource qui n’existe pas ou, si elle existe, la met à jour.Creates a resource that doesn't exist or, if it does exist, updates it. Certaines ressources peuvent ne pas prendre en charge la mise à jour.Some resources may not support update.
SuppressionDELETE Supprime ou déliste une ressource.Deletes or unlists a resource.

Codes d’état HTTPHTTP status codes

CodeCode DescriptionDescription
200200 La réussite est un corps de réponse.Success, and there is a response body.
201201 Réussite, et la ressource a été créée.Success, and the resource was created.
202202 Réussite, la demande a été acceptée, mais un travail peut encore être incomplet et terminé de façon asynchrone.Success, the request has been accepted but some work may still be incomplete and completed asynchronously.
204204 Opération réussie, mais il n’existe pas de corps de réponse.Success, but there is no response body.
301301 Redirection permanente.A permanent redirect.
302302 Une redirection temporaire.A temporary redirect.
400400 Les paramètres dans l’URL ou dans le corps de la demande ne sont pas valides.The parameters in the URL or in the request body aren't valid.
401401 Les informations d’identification fournies ne sont pas valides.The provided credentials are invalid.
403403 L’action n’est pas autorisée étant donné les informations d’identification fournies.The action is not allowed given the provided credentials.
404404 La ressource demandée n’existe pas.The requested resource doesn't exist.
409409 La demande est en conflit avec une ressource existante.The request conflicts with an existing resource.
500500 Le service a rencontré une erreur inattendue.The service has encountered an unexpected error.
503503 Le service est temporairement indisponible.The service is temporarily unavailable.

Toutes GET les demandes adressées à un point de terminaison d’API peuvent retourner une redirection http (301 ou 302).Any GET request made to a API endpoint may return an HTTP redirect (301 or 302). Les clients doivent gérer correctement ces redirections en observant Location l’en-tête et GETen émettant une suivante.Clients should gracefully handle such redirects by observing the Location header and issuing a subsequent GET. La documentation relative à des points de terminaison spécifiques n’appellera pas explicitement l’endroit où les redirections peuvent être utilisées.Documentation concerning specific endpoints will not explicitly call out where redirects may be used.

Dans le cas d’un code d’état de niveau 500, le client peut implémenter un mécanisme de nouvelle tentative raisonnable.In the case of a 500-level status code, the client can implement a reasonable retry mechanism. Le client NuGet officiel effectue une nouvelle tentative trois fois lorsqu’il rencontre un code d’état de niveau 500 ou une erreur TCP/DNS.The official NuGet client retries three times when encountering any 500-level status code or TCP/DNS error.

En-têtes de requête HTTPHTTP request headers

NomName DescriptionDescription
X-NuGet-ApiKeyX-NuGet-ApiKey Requis pour l’envoi et la suppression, consultez PackagePublish la ressourceRequired for push and delete, see PackagePublish resource
X-NuGet-Client-VersionX-NuGet-Client-Version Déconseillé et remplacé parX-NuGet-Protocol-VersionDeprecated and replaced by X-NuGet-Protocol-Version
X-NuGet-Protocol-VersionX-NuGet-Protocol-Version Obligatoire dans certains cas uniquement sur nuget.org, consultez protocoles NuGet.orgRequired in certain cases only on nuget.org, see nuget.org protocols
X-NuGet-Session-IdX-NuGet-Session-Id Facultative.Optional. Les clients NuGet v 4.7 + identifient les requêtes HTTP qui font partie de la même session cliente NuGet.NuGet clients v4.7+ identify HTTP requests that are part of the same NuGet client session.

Le X-NuGet-Session-Id n’a qu’une seule valeur pour toutes les opérations liées à une PackageReferencerestauration unique dans.The X-NuGet-Session-Id has a single value for all operations related to a single restore in PackageReference. Pour d’autres scénarios tels que la saisie packages.config semi-automatique et la restauration, il peut y avoir plusieurs ID de session différents en raison de la façon dont le code est pondéré.For other scenarios such as autocomplete and packages.config restore there may be several different session ID's due to how the code is factored.

AuthenticationAuthentication

L’authentification est laissée à l’implémentation de la source du package à définir.Authentication is left up to the package source implementation to define. Pour NuGet.org, seule la PackagePublish ressource requiert une authentification via un en-tête de clé API spécial.For nuget.org, only the PackagePublish resource requires authentication via a special API key header. Pour PackagePublish plus d’informations, consultez la ressource.See PackagePublish resource for details.