Protocolos de nuget.org

  • Artículo

Para interactuar con nuget.org, los clientes deben seguir determinados protocolos. Dado que estos protocolos siguen evolucionando, los clientes deben identificar la versión del protocolo que usan al llamar a API específicas de nuget.org. Esto permite que nuget.org haga los cambios de forma no disruptiva para los clientes antiguos.

Nota:

Las API documentadas en esta página son específicas de nuget.org y no se espera que otras implementaciones del servidor NuGet introduzcan estas API.

Para obtener información sobre la API NuGet implementada ampliamente en el ecosistema de NuGet, consulte la información general de la API.

En este tema se enumeran varios protocolos a medida que van surgiendo.

Versión 4.1.0 del protocolo NuGet

El protocolo 4.1.0 especifica el uso de claves de verificación para interactuar con servicios distintos de nuget.org, para validar un paquete con una cuenta de nuget.org. Tenga en cuenta que el número de versión 4.1.0 es una cadena opaca, pero coincide con la primera versión del cliente NuGet oficial que admitió este protocolo.

La validación garantiza que las claves de API creadas por el usuario se utilicen únicamente con nuget.org, y que cualquier otra verificación o validación de un servicio de terceros se realice a través de unas claves de verificación de un solo uso. Estas claves de verificación se pueden usar para validar que el paquete pertenece a un usuario (cuenta) en particular en nuget.org.

Requisito del cliente

Los clientes deben pasar el siguiente encabezado cuando realicen llamadas a la API para insertar paquetes en nuget.org:

X-NuGet-Protocol-Version: 4.1.0

Tenga en cuenta que el encabezado X-NuGet-Client-Version tiene una semántica similar, pero está reservado para que solo lo utilice el cliente NuGet oficial. Los clientes de terceros deben utilizar el encabezado y el valor X-NuGet-Protocol-Version.

El propio protocolo de inserción se describe en la documentación del recurso PackagePublish.

Si un cliente interactúa con servicios externos y necesita validar si un paquete pertenece a un usuario (cuenta) en particular, debe usar el siguiente protocolo y las claves de verificación y no las claves de API de nuget.org.

API para solicitar una clave de verificación

Esta API se usa para obtener una clave de verificación para que un autor de nuget.org pueda validar un paquete que le pertenece.

POST api/v2/package/create-verification-key/{ID}/{VERSION}

Parámetros de solicitud

Nombre En Tipo Obligatorio Notas
ID Dirección URL string sí El identificador del paquete para el que se solicita la clave de verificación.
VERSION Dirección URL string no La versión del paquete.
X-NuGet-ApiKey Encabezado string sí Por ejemplo: X-NuGet-ApiKey: {USER_API_KEY}

Respuesta

{
    "Key": "{Verify scope key from nuget.org}",
    "Expires": "{Date}"
}

La API para comprobar la clave de verificación.

Esta API se usa para validar una clave de verificación para el paquete que pertenece al autor de nuget.org.

GET api/v2/verifykey/{ID}/{VERSION}

Parámetros de solicitud

Nombre En Tipo Obligatorio Notas
ID Dirección URL string sí El identificador del paquete para el que se solicita la clave de verificación.
VERSION Dirección URL string no La versión del paquete.
X-NuGet-ApiKey Encabezado string sí Por ejemplo: X-NuGet-ApiKey: {VERIFY_SCOPE_KEY}

Nota:

Esto comprueba que la clave de API de verificación expira en un día o en el primer uso, lo que ocurra primero.

Respuesta

Código de estado Significado
200 La clave de API es válida.
403 La clave de API no es válida o no está autorizada para insertarla en el paquete.
404 El paquete al que hacen referencia ID y VERSION (opcional) no existe.