API NuGetNuGet API

La API de NuGet es un conjunto de puntos de conexión HTTP que puede usarse para descargar los paquetes, capturar metadatos, publicar nuevos paquetes y realizar otras operaciones disponibles en los clientes de NuGet oficiales.The NuGet 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.

Esta API se usa por el cliente de NuGet en Visual Studio, nuget.exe y la CLI de .NET para realizar operaciones de NuGet como dotnet restore , búsqueda en la IU de Visual Studio, y nuget.exe push .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.

Tenga en cuenta que en algunos casos, nuget.org tiene requisitos adicionales que no se aplican por otros orígenes de paquetes.Note in some cases, nuget.org has additional requirements that are not enforced by other package sources. Estas diferencias se documentan por la protocolos de nuget.org.These differences are documented by the nuget.org Protocols.

Para una enumeración sencilla y descarga de versiones de nuget.exe disponibles, consulte el tools.json punto de conexión.For a simple enumeration and download of available nuget.exe versions, see the tools.json endpoint.

Índice de servicioService index

El punto de entrada para la API es un documento JSON en una ubicación conocida.The entry point for the API is a JSON document in a well known location. Se llama a este documento el índice de servicio.This document is called the service index. La ubicación del índice de servicio de nuget.org es https://api.nuget.org/v3/index.json.The location of the service index for nuget.org is https://api.nuget.org/v3/index.json.

Este documento JSON que contiene una lista de recursos que ofrecen una funcionalidad diferente y satisfacer los distintos casos de uso.This JSON document contains a list of resources which provide different functionality and fulfill different use cases.

Los clientes compatibles con la API deben aceptar una o varias de estas direcciones URL de índice de servicio como la forma de conectarse a los orígenes del paquete correspondiente.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.

Para obtener más información sobre el índice de servicio, consulte su referencia de API.For more information about the service index, see its API reference.

Control de versionesVersioning

La API es la versión 3 del protocolo HTTP de NuGet.The API is version 3 of NuGet's HTTP protocol. Este protocolo se conoce a veces como "la API de V3".This protocol is sometimes referred to as "the V3 API." Estos documentos de referencia se hará referencia a esta versión del protocolo simplemente como "la API".These reference documents will refer to this version of the protocol simply as "the API."

La versión de esquema de índice de servicio se indica mediante el version propiedad en el índice de servicio.The service index schema version is indicated by the version property in the service index. La API exige que la cadena de versión tiene un número de versión principal 3.The API mandates that the version string has a major version number of 3. Cuando se realizan cambios no importantes en el esquema de índice de servicio, aumentará la versión secundaria de la cadena de versión.As non-breaking changes are made to the service index schema, the version string's minor version will be increased.

Los clientes más antiguos (por ejemplo, nuget.exe 2.x) no admiten la API de V3 y solo admiten la API V2 anterior, que no se documenta aquí.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.

La API de NuGet V3 se denomina así porque es el sucesor de la API V2, que era el protocolo basado en OData, implementado por la versión 2.x del cliente NuGet oficial.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. La API de V3 primero era compatible con la versión 3.0 del cliente NuGet oficial y es todavía la versión de protocolo principal más reciente compatible con el cliente de NuGet 4.0 y en.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.

Se realizaron cambios en los protocolos que no son importantes a la API porque era el primer lanzamiento.Non-breaking protocol changes have been made to the API since it was first release.

Los recursos y el esquemaResources and schema

El índice de servicio describe una variedad de recursos.The service index describes a variety of resources. El conjunto actual de los recursos admitidos son los siguientes:The current set of supported resources are as follows:

Nombre del recursoResource name ObligatorioRequired DescripciónDescription
PackagePublish yes Insertar y eliminar (o quitar de la lista) paquetes.Push and delete (or unlist) packages.
SearchQueryService yes Filtrar y buscar paquetes mediante la palabra clave.Filter and search for packages by keyword.
RegistrationsBaseUrl yes Obtener metadatos del paquete.Get package metadata.
PackageBaseAddress yes Obtener contenido del paquete (archivo .nupkg).Get package content (.nupkg).
SearchAutocompleteService Nono Detectar el Id. de paquete y las versiones por la subcadena.Discover package IDs and versions by substring.
ReportAbuseUriTemplate Nono Construir una dirección URL para tener acceso a una página web de "Notificar abuso".Construct a URL to access a "report abuse" web page.
RepositorySignatures Nono Obtener certificados usados para firmar el repositorio.Get certificates used for repository signing.
Catalog Nono Registro completo de todos los eventos de paquete.Full record of all package events.
SymbolPackagePublish Nono Insertar paquetes de símbolos.Push symbol packages.

En general, todos los datos no binarios devueltos por un recurso de API se serializan mediante JSON.In general, all non-binary data returned by a API resource are serialized using JSON. El esquema de respuesta devuelto por cada recurso en el índice de servicio se define por separado para ese recurso.The response schema returned by each resource in the service index is defined individually for that resource. Para obtener más información acerca de cada recurso, vea los temas enumerados anteriormente.For more information about each resource, see the topics listed above.

Nota

Cuando un origen no implementa SearchAutocompleteService cualquier comportamiento de Autocompletar debe deshabilitarse de forma correcta.When a source does not implement SearchAutocompleteService any autocomplete behavior should be disabled gracefully. Cuando ReportAbuseUriTemplate no está implementado, la vuelve de cliente de NuGet oficial de nuget.org a la dirección URL de abuso de informes (sometidas a seguimiento por NuGet/Home #4924).When ReportAbuseUriTemplate is not implemented, the official NuGet client falls back to nuget.org's report abuse URL (tracked by NuGet/Home#4924). Pueden optar por otros clientes simplemente no se muestra una dirección URL de abuso de informe al usuario.Other clients may opt to simply not show a report abuse URL to the user.

Marcas de tiempoTimestamps

Todas las marcas de tiempo devueltos por la API son UTC o si no se especifican utilizando ISO 8601 representación.All timestamps returned by the API are UTC or are otherwise specified using ISO 8601 representation.

Métodos HTTPHTTP methods

VerboVerb UsarUse
GETGET Realiza una operación de solo lectura, normalmente, recuperación de datos.Performs a read-only operation, typically retrieving data.
HEADHEAD Obtiene los encabezados de respuesta correspondiente GET solicitud.Fetches the response headers for the corresponding GET request.
PUTPUT Crea un recurso que no existe o, si existe, lo actualiza.Creates a resource that doesn't exist or, if it does exist, updates it. Algunos recursos pueden no admitir la actualización.Some resources may not support update.
SUPRIMIRDELETE Elimina o quita un recurso de la lista.Deletes or unlists a resource.

Códigos de estado HTTPHTTP status codes

CódigoCode DescripciónDescription
200200 Caso de éxito, y hay un cuerpo de respuesta.Success, and there is a response body.
201201 Se creó correctamente y el recurso.Success, and the resource was created.
202202 Caso de éxito, la solicitud se ha aceptado pero algún trabajo pueden incompleta y completados asincrónicamente.Success, the request has been accepted but some work may still be incomplete and completed asynchronously.
204204 Correcto, pero no hay ningún cuerpo de respuesta.Success, but there is no response body.
301301 Una redirección permanente.A permanent redirect.
302302 Una redirección temporal.A temporary redirect.
400400 Los parámetros en la dirección URL o en el cuerpo de solicitud no son válidos.The parameters in the URL or in the request body aren't valid.
401401 Las credenciales proporcionadas no son válidas.The provided credentials are invalid.
403403 No se permite la acción dada las credenciales proporcionadas.The action is not allowed given the provided credentials.
404404 El recurso solicitado no existe.The requested resource doesn't exist.
409409 La solicitud entra en conflicto con un recurso existente.The request conflicts with an existing resource.
500500 El servicio ha encontrado un error inesperado.The service has encountered an unexpected error.
503503 El servicio no está disponible temporalmente.The service is temporarily unavailable.

Cualquier GET solicitud realizada a un punto de conexión de API puede devolver una redirección de HTTP (301 o 302).Any GET request made to a API endpoint may return an HTTP redirect (301 or 302). Los clientes deben controlar correctamente estas redirecciones observando el Location encabezado y emitir un posteriores GET.Clients should gracefully handle such redirects by observing the Location header and issuing a subsequent GET. Documentación relativa a los puntos de conexión concretos no llamará a explícitamente horizontal donde se pueden utilizar las redirecciones.Documentation concerning specific endpoints will not explicitly call out where redirects may be used.

En el caso de un código de estado de nivel 500, el cliente puede implementar un mecanismo de reintento razonable.In the case of a 500-level status code, the client can implement a reasonable retry mechanism. El oficial NuGet cliente lo intenta tres veces al encontrar cualquier código de estado del nivel 500 o error DNS o TCP.The official NuGet client retries three times when encountering any 500-level status code or TCP/DNS error.

Encabezados de solicitud HTTPHTTP request headers

nombreName DescripciónDescription
X-NuGet-ApiKeyX-NuGet-ApiKey Es necesario para la inserción y eliminación, consulte PackagePublish recursosRequired for push and delete, see PackagePublish resource
X-NuGet-Client-VersionX-NuGet-Client-Version En desuso y reemplazado por X-NuGet-Protocol-VersionDeprecated and replaced by X-NuGet-Protocol-Version
X-NuGet-Protocol-VersionX-NuGet-Protocol-Version Necesario en algunos casos solo en nuget.org, vea protocolos de nuget.orgRequired in certain cases only on nuget.org, see nuget.org protocols
X-NuGet-Id. de sesiónX-NuGet-Session-Id Opcional.Optional. NuGet clientes v4.7 + identificar las solicitudes HTTP que forman parte de la misma sesión de cliente de NuGet.NuGet clients v4.7+ identify HTTP requests that are part of the same NuGet client session. Para PackageReference hay operaciones de restauración es un identificador de sesión único, para otros escenarios como Autocompletar, y packages.config restauración puede haber varios diferentes Id. de sesión debido a cómo el código se divide.For PackageReference restore operations there is a single session id, for other scenarios such as auto complete, and packages.config restore there may be several different session id's due to how the code is factored.

AutenticaciónAuthentication

La autenticación se deja a la implementación de origen del paquete para definir.Authentication is left up to the package source implementation to define. Para nuget.org, sólo el PackagePublish recurso requiere autenticación a través de un encabezado especial de clave de API.For nuget.org, only the PackagePublish resource requires authentication via a special API key header. Consulte PackagePublish recursos para obtener más información.See PackagePublish resource for details.