| title | description | author | ms.author | ms.date | ms.topic | ms.reviewer | ms.openlocfilehash | ms.sourcegitcommit | ms.translationtype | ms.contentlocale | ms.lasthandoff | ms.locfileid |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
Información general de la API del servidor NuGet |
La API del servidor de NuGet es un conjunto de puntos de conexión HTTP que se pueden usar para descargar paquetes, capturar metadatos, publicar paquetes nuevos, etc. |
joelverhagen |
jver |
10/26/2017 |
reference |
kraigb |
aacf56a5dc5af9abf6f60d42bc7fd530a128d0d8 |
b138bc1d49fbf13b63d975c581a53be4283b7ebf |
MT |
es-ES |
11/03/2020 |
93237814 |
La API de servidor de NuGet es un conjunto de puntos de conexión HTTP que se pueden usar para descargar paquetes, capturar metadatos, publicar paquetes nuevos y realizar la mayoría de las demás operaciones disponibles en los clientes de NuGet oficiales.
Esta API la usa el cliente de NuGet en Visual Studio, nuget.exe y la CLI de .NET para realizar operaciones de NuGet como dotnet restore , buscar en la interfaz de usuario de Visual Studio y nuget.exe push .
Tenga en cuenta que, en algunos casos, nuget.org tiene requisitos adicionales que no exigen otros orígenes de paquetes. Estas diferencias se documentan mediante los protocolos Nuget.org.
Para obtener una enumeración sencilla y descargar las versiones de nuget.exe disponibles, vea el tools.jsen el punto de conexión.
El punto de entrada de la API es un documento JSON en una ubicación bien conocida. Este documento se denomina Índice de servicio . La ubicación del índice de servicio para nuget.org es https://api.nuget.org/v3/index.json .
Este documento JSON contiene una lista de recursos que proporcionan una funcionalidad diferente y cumplen diferentes casos de uso.
Los clientes que admiten la API deben aceptar una o varias de estas direcciones URL de índice de servicio como medio para conectarse a los orígenes de paquetes respectivos.
Para obtener más información sobre el índice de servicio, consulte su referencia de API.
La API es la versión 3 del protocolo HTTP de NuGet. Este protocolo se denomina a veces "API V3". Estos documentos de referencia hará referencia a esta versión del protocolo simplemente como "la API".
La versión del esquema de índice de servicio se indica mediante la version propiedad en el índice de servicio. La API asigna que la cadena de versión tiene un número de versión principal de 3 . A medida que se realizan cambios no importantes en el esquema de índice de servicio, se aumentará la versión secundaria de la cadena de versión.
Los clientes más antiguos (como nuget.exe 2. x) no admiten la API V3 y solo admiten la API V2 anterior, que no se documenta aquí.
La API de NuGet V3 se denomina como tal porque es el sucesor de la API V2, que era el protocolo basado en OData implementado por la versión 2. x del cliente de NuGet oficial. La API V3 se admitía por primera vez en la versión 3,0 del cliente de NuGet oficial y sigue siendo la versión más reciente del protocolo compatible con el cliente de NuGet, 4,0 y on.
Se han realizado cambios de Protocolo no problemáticos en la API desde que se lanzó por primera vez.
El Índice de servicio describe una variedad de recursos. El conjunto actual de recursos admitidos es el siguiente:
| Nombre del recurso | Obligatorio | Descripción |
|---|---|---|
| Catálogo | no | Registro completo de todos los eventos de paquete. |
| PackageBaseAddress | yes | Obtiene el contenido del paquete (. nupkg). |
| PackageDetailsUriTemplate | no | Construya una dirección URL para tener acceso a una página web de detalles del paquete. |
| PackagePublish | yes | Inserte y elimine (o desenumere) paquetes. |
| RegistrationsBaseUrl | yes | Obtiene los metadatos del paquete. |
| ReportAbuseUriTemplate | no | Construya una dirección URL para tener acceso a una página web notificar abuso. |
| RepositorySignatures | no | Obtiene los certificados que se usan para la firma del repositorio. |
| SearchAutocompleteService | no | Detectar ID. de paquete y versiones por subcadena. |
| SearchQueryService | yes | Filtre y busque paquetes por palabra clave. |
| SymbolPackagePublish | no | Paquetes de símbolos de envío. |
En general, todos los datos no binarios devueltos por un recurso de API se serializan mediante JSON. El esquema de respuesta que devuelve cada recurso en el índice de servicio se define individualmente para ese recurso. Para obtener más información acerca de cada recurso, consulte los temas enumerados anteriormente.
En el futuro, a medida que evolucione el protocolo, se pueden agregar nuevas propiedades a las respuestas JSON. Para que el cliente sea una prueba futura, la implementación no debe suponer que el esquema de respuesta es final y no puede incluir datos adicionales. Todas las propiedades que la implementación no entiende deben omitirse.
Note
Cuando un origen no implementa SearchAutocompleteService ningún comportamiento de autocompletar debe deshabilitarse correctamente. Cuando ReportAbuseUriTemplate no se implementa, el cliente de Nuget oficial recurre a la dirección URL de la notificación de abuso de la NuGet/Home#4924organización. Otros clientes pueden optar por no mostrar simplemente la dirección URL de un informe de abuso para el usuario.
El índice de servicio V3 de nuget.org tiene algunos recursos que no se han documentado anteriormente. Hay varias razones para no documentar un recurso.
En primer lugar, no documentamos los recursos usados como un detalle de implementación de nuget.org. SearchGalleryQueryService Entra en esta categoría. NuGetGallery usa este recurso para delegar algunas consultas V2 (OData) en el índice de búsqueda en lugar de usar la base de datos. Este recurso se presentó por motivos de escalabilidad y no está pensado para uso externo.
En segundo lugar, no documentamos recursos que nunca se enviaron en una versión RTM del cliente oficial.
PackageDisplayMetadataUriTemplate y PackageVersionDisplayMetadataUriTemplate entran en esta categoría.
En tercer lugar, no se documentan los recursos estrechamente acoplados con el protocolo v2, que a su vez no se documenta. El LegacyGallery recurso pertenece a esta categoría. Este recurso permite que un índice de servicio V3 señale a una dirección URL de origen de V2 correspondiente. Este recurso es compatible con nuget.exe list .
Si un recurso no se documenta aquí, se recomienda encarecidamente que no tome una dependencia en ellos. Es posible que se quite o cambie el comportamiento de estos recursos no documentados, lo que podría interrumpir la implementación de maneras inesperadas.
Todas las marcas de tiempo devueltas por la API son UTC o, de lo contrario, se especifican mediante la representación ISO 8601 .
| Verbo | Usar |
|---|---|
| GET | Realiza una operación de solo lectura, que normalmente recupera datos. |
| HEAD | Recupera los encabezados de respuesta de la solicitud correspondiente GET . |
| PUT | Crea un recurso que no existe o, si existe, lo actualiza. Es posible que algunos recursos no admitan Update. |
| DELETE | Elimina o elimina la lista de un recurso. |
| Código | Descripción |
|---|---|
| 200 | Success y hay un cuerpo de respuesta. |
| 201 | Correcto y se creó el recurso. |
| 202 | Correcto, se aceptó la solicitud, pero es posible que algún trabajo siga estando incompleto y completado de forma asincrónica. |
| 204 | Correcto, pero no hay ningún cuerpo de respuesta. |
| 301 | Una redirección permanente. |
| 302 | Una redirección temporal. |
| 400 | Los parámetros de la dirección URL o en el cuerpo de la solicitud no son válidos. |
| 401 | Las credenciales proporcionadas no son válidas. |
| 403 | La acción no se permite debido a las credenciales proporcionadas. |
| 404 | El recurso solicitado no existe. |
| 409 | La solicitud entra en conflicto con un recurso existente. |
| 500 | El servicio ha encontrado un error inesperado. |
| 503 | El servicio no está disponible temporalmente. |
Cualquier GET solicitud realizada a un punto de conexión de API puede devolver una redirección http (301 o 302). Los clientes deben controlar correctamente estas redirecciones observando el Location encabezado y emitiendo una siguiente GET . La documentación relacionada con puntos de conexión específicos no llamará explícitamente a donde se pueden usar redirecciones.
En el caso de un código de estado de nivel 500, el cliente puede implementar un mecanismo de reintento razonable. El cliente de NuGet oficial vuelve a intentarlo tres veces cuando se encuentra un código de estado de nivel 500 o un error de TCP/DNS.
| Nombre | Descripción |
|---|---|
| X-NuGet-ApiKey | Necesario para la extracción y la eliminación, consulte PackagePublish recurso |
| X-NuGet-Client-version | En desuso y reemplazado porX-NuGet-Protocol-Version |
| X-NuGet-Protocol-version | Requerido en ciertos casos solo en nuget.org, consulte protocolos Nuget.org |
| X-NuGet-Session-ID | Opcional . Los clientes de NuGet v 4.7 + identifican las solicitudes HTTP que forman parte de la misma sesión de cliente de NuGet. |
X-NuGet-Session-IdTiene un único valor para todas las operaciones relacionadas con una única restauración en PackageReference . En el caso de otros escenarios, como Autocompletar y packages.config restaurar, puede haber varios identificadores de sesión diferentes debido a la forma en que se factoriza el código.
La autenticación se deja hasta la implementación del origen del paquete que se va a definir. En el caso de nuget.org, solo el PackagePublish recurso requiere autenticación a través de un encabezado de clave de API especial. Vea PackagePublish recursos para obtener más información.