Metadatos de paquete
Es posible capturar metadatos sobre los paquetes disponibles en un origen de paquete mediante la API de NuGet V3. Estos metadatos se pueden capturar mediante el recurso RegistrationsBaseUrl que se encuentra en el índice de servicio.
La colección de los documentos que se encuentran en RegistrationsBaseUrl a menudo se denomina “registros” o “blobs de registro”. El conjunto de documentos en un único RegistrationsBaseUrl se conoce como “subárbol de registro”. Un subárbol de registro contiene metadatos sobre todos los paquetes disponibles en un origen de paquete.
Nota:
El recurso de metadatos del paquete no contiene todos los metadatos de los paquetes. Utiliza el recurso de búsqueda para buscar los propietarios, las descargas o el estado de reserva de prefijo de los paquetes.
Control de versiones
Se usan los siguientes valores @type:
| Valor de @type | Notas |
|---|---|
| RegistrationsBaseUrl | La versión inicial |
| RegistrationsBaseUrl/3.0.0-beta | Alias de RegistrationsBaseUrl |
| RegistrationsBaseUrl/3.0.0-rc | Alias de RegistrationsBaseUrl |
| RegistrationsBaseUrl/3.4.0 | Respuestas en formato GZIP |
| RegistrationsBaseUrl/3.6.0 | Incluye paquetes de SemVer 2.0.0 |
Esto representa tres subárboles de registro distintos disponibles para diversas versiones de cliente.
RegistrationsBaseUrl
Estos registros no están comprimidos, lo que significa que utilizan un valor Content-Encoding: identity implícito. Los paquetes de SemVer 2.0.0 se excluyen de este subárbol.
RegistrationsBaseUrl/3.4.0
Estos registros se comprimen mediante Content-Encoding: gzip. Los paquetes de SemVer 2.0.0 se excluyen de este subárbol.
RegistrationsBaseUrl/3.6.0
Estos registros se comprimen mediante Content-Encoding: gzip. Los paquetes de SemVer 2.0.0 se incluyen en este subárbol.
Para obtener más información sobre SemVer 2.0.0, consulta la compatibilidad con SemVer 2.0.0 para nuget.org.
URL base
La dirección URL base de las siguientes API es el valor de la propiedad @id asociada a uno de los valores @type de los recursos mencionados anteriormente. En el documento siguiente, se usará la dirección URL base del marcador de posición {@id}. La dirección URL base puede cambiar en función de los cambios de implementación o infraestructura dentro del origen del paquete, por lo que el software cliente debe capturarla dinámicamente desde el índice de servicio.
Métodos HTTP
Todas las direcciones URL que se encuentran en el recurso de registro admiten los métodos HTTP GET y HEAD.
Índice de registro
El recurso de registro agrupa los metadatos de los paquetes por id. de paquete. No es posible obtener datos sobre más de un id. de paquete a la vez. Este recurso no proporciona ninguna forma de descubrir id. de paquete. En su lugar, se supone que el cliente ya conoce el id. de paquete deseado. Los metadatos disponibles sobre cada versión del paquete varían según la implementación del servidor. Los blobs de registro de paquetes tienen la siguiente estructura jerárquica:
- Índice: punto de entrada de los metadatos del paquete, compartido por todos los paquetes de un origen con el mismo id. de paquete.
- Página: una agrupación de versiones de paquete. La implementación del servidor define el número de versiones de paquete de una página.
- Hoja: un documento específico de una sola versión de paquete.
La dirección URL del índice de registro es predecible y el cliente puede determinarla por el id. de paquete y el valor @id del recurso de registro que incluye el índice de servicio. Las direcciones URL de las páginas de registro y las hojas se descubren inspeccionando el índice de registro.
Páginas de registro y hojas
Aunque no es estrictamente necesario que una implementación del servidor almacene hojas de registro en documentos de página de registro independientes, se recomienda conservar la memoria del lado cliente. En lugar de insertar todas las hojas de registro en el índice o almacenar inmediatamente las hojas en documentos de página, se recomienda que la implementación del servidor defina cierta heurística para elegir entre los dos enfoques en función del número de versiones del paquete o el tamaño acumulado de hojas de este.
El almacenamiento de todas las versiones de paquete (hojas) en el índice de registro disminuye el número de solicitudes HTTP necesarias para capturar metadatos del paquete, pero obliga a descargar un documento mayor y a asignar más memoria de cliente. Por otro lado, si la implementación del servidor almacena inmediatamente las hojas de registro en documentos de página independientes, el cliente debe realizar más solicitudes HTTP para obtener la información que necesita.
La heurística que nuget.org utiliza es la siguiente: si hay 128 o más versiones de un paquete, el sistema divide las hojas en páginas de tamaño 64. Si hay menos de 128 versiones, inserta todas las hojas en el índice de registro. Ten en cuenta que esto significa que los paquetes con entre 65 y 127 versiones tendrán dos páginas en el índice, pero ambas páginas se insertarán.
GET {@id}/{LOWER_ID}/index.json
Parámetros de solicitud
| Nombre | En | Tipo | Obligatorio | Notas |
|---|---|---|---|---|
| LOWER_ID | Dirección URL | string | sí | Id. del paquete, en minúsculas |
El valor LOWER_ID es el id. de paquete deseado escrito en minúsculas mediante las reglas implementadas por el método System.String.ToLowerInvariant() de .NET.
Respuesta
La respuesta es un documento JSON que tiene un objeto raíz con las siguientes propiedades:
| Nombre | Type | Obligatorio | Notas |
|---|---|---|---|
| count | integer | sí | Número de páginas de registro en el índice |
| items | matriz de objetos | sí | Matriz de páginas de registro |
Cada elemento de la matriz items del objeto del índice es un objeto JSON que representa una página de registro.
Objeto de página de registro
El objeto de página de registro que se encuentra en el índice de registro tiene las siguientes propiedades:
| Nombre | Type | Obligatorio | Notas |
|---|---|---|---|
| @id | string | sí | Dirección URL de la página de registro |
| count | integer | sí | Número de hojas de registro en la página |
| items | matriz de objetos | no | Matriz de hojas de registro y sus metadatos asociados |
| lower | string | sí | Versión más baja de SemVer 2.0.0 de la página (incluida) |
| primario | string | no | Dirección URL del índice de registro |
| upper | string | sí | Versión más alta de SemVer 2.0.0 de la página (incluida) |
Los límites lower y upper del objeto de página resultan útiles cuando se necesitan los metadatos de una versión de página específica.
Estos límites se pueden utilizar para capturar la única página de registro necesaria. Las cadenas de versión cumplen las reglas de versión de NuGet. Las cadenas de versión están normalizadas y no incluyen metadatos de generación. Al igual que ocurre con todas las versiones del ecosistema de NuGet, la comparación de cadenas de versión se implementa mediante las reglas de precedencia de versión de SemVer 2.0.0.
La propiedad parent solo aparecerá si el objeto de página de registro tiene la propiedad items.
Si la propiedad items no está presente en el objeto de página de registro, debe utilizarse la dirección URL especificada en el @id para capturar metadatos sobre versiones de paquete individuales. La matriz items a veces se excluye del objeto de página a modo de optimización. Si el número de versiones de un único id. de paquete es muy grande, el documento del índice de registro será demasiado grande y un desperdicio a la hora de procesar para un cliente al que solo le interesa una versión específica o un pequeño intervalo de versiones.
Ten en cuenta que si la propiedad items está presente, no será necesario utilizar la propiedad @id, puesto que todos los datos de la página ya estarán insertados en la propiedad items.
Cada elemento de la matriz items del objeto de página es un objeto JSON que representa una hoja de registro y sus metadatos asociados.
Objeto de hoja de registro en una página
El objeto de hoja de registro que se incluye en una página de registro tiene las siguientes propiedades:
| Nombre | Type | Obligatorio | Notas |
|---|---|---|---|
| @id | string | sí | Dirección URL de la hoja de registro |
| catalogEntry | object | sí | Entrada de catálogo que contiene los metadatos del paquete |
| packageContent | string | sí | Dirección URL del contenido del paquete (.nupkg) |
Cada objeto de hoja de registro representa los datos asociados a una sola versión del paquete.
Entrada de catálogo
La propiedad catalogEntry del objeto de hoja de registro tiene las siguientes propiedades:
| Nombre | Type | Obligatorio | Notas |
|---|---|---|---|
| @id | string | sí | Dirección URL del documento utilizado para generar este objeto |
| authors | cadena o matriz de cadenas | no | |
| dependencyGroups | matriz de objetos | no | Dependencias del paquete, agrupadas por plataforma de destino |
| deprecation | object | no | Estado de desuso asociado al paquete |
| descripción | string | no | |
| iconUrl | string | no | |
| id | string | sí | Id. del paquete |
| language | string | no | |
| licenseUrl | string | no | |
| licenseExpression | string | no | |
| lista | boolean | no | Debe considerarse como que está en la lista si está ausente |
| minClientVersion | string | no | |
| packageContent | string | no | Duplicado de la misma propiedad en el objeto primario, incluido solo porque es antiguo |
| projectUrl | string | no | |
| published | string | no | Cadena que contiene una marca de tiempo ISO 8601 de cuando se publicó el paquete |
| readmeUrl | string | no | Dirección URL de la vista representada (página web HTML) del archivo LÉAME del paquete |
| requireLicenseAcceptance | boolean | no | |
| summary | string | no | |
| etiquetas | cadena o matriz de cadenas | no | |
| title | string | no | |
| version | string | sí | Cadena de versión completa después de la normalización |
| vulnerabilities | matriz de objetos | no | Vulnerabilidades de seguridad del paquete |
La propiedad version del paquete es la cadena de versión completa después de la normalización. Esto significa que es posible incluir aquí los datos de generación de SemVer 2.0.0.
La propiedad dependencyGroups es una matriz de objetos que representa las dependencias del paquete, agrupadas por plataforma de destino. Si el paquete no tiene dependencias, quiere decir que falta la propiedad dependencyGroups, que la matriz está vacía o que falta la propiedad dependencies de todos los grupos o bien está vacía.
El valor de la propiedad licenseExpression cumple con la sintaxis de expresión de licencia de NuGet.
Nota:
En nuget.org, el valor published se ajusta en el año 1900, cuando el paquete no está en la lista.
Grupo de dependencias de paquete
Cada objeto de grupo de dependencias tiene las siguientes propiedades:
| Nombre | Type | Obligatorio | Notas |
|---|---|---|---|
| targetFramework | string | no | Plataforma de destino a la que se aplican estas dependencias |
| dependencies | matriz de objetos | no |
La cadena targetFramework utiliza el formato implementado por la biblioteca .NET de NuGet NuGet.Frameworks. Si no se especifica ningún valor targetFramework, el grupo de dependencias se aplica a todas las plataformas de destino.
La propiedad dependencies es una matriz de objetos, cada una de las cuales representa una dependencia de paquete del paquete actual.
Dependencia de paquete
Cada dependencia de paquete tiene las propiedades siguientes:
| Nombre | Type | Obligatorio | Notas |
|---|---|---|---|
| id | string | sí | Id. de la dependencia de paquete |
| range | object | no | Intervalo de versiones de la dependencia permitido |
| registro | string | no | Dirección URL del índice de registro para esta dependencia |
Si la propiedad range se excluye o existe una cadena vacía, el cliente debe establecer el intervalo de versiones (, ) como valor predeterminado. Es decir, se permite cualquier versión de la dependencia. El valor de * no está permitido para la propiedad range.
Paquete en desuso
Cada paquete en desuso tiene las propiedades siguientes:
| Nombre | Type | Obligatorio | Notas |
|---|---|---|---|
| motivos | Matriz de cadenas | sí | Razones por las que el paquete está en desuso |
| message | string | no | Detalles adicionales sobre este desuso |
| alternatePackage | object | no | El paquete alternativo que se debe utilizar en su lugar |
La propiedad reasons debe contener al menos una cadena, y solo debe incluir cadenas de la tabla siguiente:
| Motivo | Descripción |
|---|---|
| Heredado | El paquete ya no se mantiene |
| CriticalBugs | El paquete tiene errores que hacen que no sea adecuado para su utilización |
| Otros | El paquete está en desuso debido a un motivo que no está en esta lista |
Si la propiedad reasons contiene cadenas que no proceden del conjunto conocido, se deben omitir. Las cadenas no distinguen mayúsculas de minúsculas, por lo que legacy se debe tratar igual que Legacy. No hay ninguna restricción de ordenación en la matriz, por lo que las cadenas se pueden organizar en orden arbitrario. Además, si la propiedad contiene solo cadenas que no son del conjunto conocido, se debe tratar como si solo contuviera la cadena “Other”.
Paquete alternativo
El objeto de paquete alternativo tiene las siguientes propiedades:
| Nombre | Type | Obligatorio | Notas |
|---|---|---|---|
| id | string | sí | Id. del paquete alternativo |
| range | object | no | Intervalo de versiones permitido o *, si se permite alguna versión |
Vulnerabilidades
Una matriz de objetos vulnerability. Cada vulnerabilidad tiene las siguientes propiedades:
| Nombre | Type | Obligatorio | Notas |
|---|---|---|---|
| advisoryUrl | string | sí | Ubicación del aviso de seguridad para el paquete |
| severity | string | sí | Gravedad de la advertencia: "0" = Baja, "1" = Moderada, "2" = Alta, "3" = Crítica |
Solicitud de muestra
GET https://api.nuget.org/v3/registration-sample/nuget.server.core/index.json
Asegúrate de capturar la dirección URL base (https://api.nuget.org/v3/registration-sample/ en este ejemplo) del índice de servicio, tal y como se indica en la sección de la dirección URL base.
Respuesta de muestra
{
"count": 1,
"items": [
{
"@id": "https://api.nuget.org/v3/registration-sample/nuget.server.core/index.json#page/3.0.0-beta/3.0.0-beta",
"count": 1,
"items": [
{
"@id": "https://api.nuget.org/v3/registration-sample/nuget.server.core/3.0.0-beta.json",
"catalogEntry": {
"@id": "https://api.nuget.org/v3/catalog0/data/2017.10.05.18.41.33/nuget.server.core.3.0.0-beta.json",
"authors": ".NET Foundation",
"dependencyGroups": [
{
"@id": "https://api.nuget.org/v3/catalog0/data/2017.10.05.18.41.33/nuget.server.core.3.0.0-beta.json#dependencygroup",
"dependencies": [
{
"@id": "https://api.nuget.org/v3/catalog0/data/2017.10.05.18.41.33/nuget.server.core.3.0.0-beta.json#dependencygroup/nuget.core",
"id": "NuGet.Core",
"range": "[2.14.0, )",
"registration": "https://api.nuget.org/v3/registration-sample/nuget.core/index.json"
}
]
}
],
"description": "Core library for creating a Web Application used to host a simple NuGet feed",
"iconUrl": "",
"id": "NuGet.Server.Core",
"language": "",
"licenseUrl": "https://raw.githubusercontent.com/NuGet/NuGet.Server/dev/LICENSE.txt",
"listed": true,
"minClientVersion": "2.6",
"packageContent": "https://api.nuget.org/v3-flatcontainer/nuget.server.core/3.0.0-beta/nuget.server.core.3.0.0-beta.nupkg",
"projectUrl": "https://github.com/NuGet/NuGet.Server",
"published": "2017-10-05T18:40:32.43+00:00",
"requireLicenseAcceptance": false,
"summary": "",
"tags": [ "" ],
"title": "",
"version": "3.0.0-beta",
"vulnerabilities": [
{
"advisoryUrl": "https://github.com/advisories/ABCD-1234-5678-9012",
"severity": "2"
}
]
},
"packageContent": "https://api.nuget.org/v3-flatcontainer/nuget.server.core/3.0.0-beta/nuget.server.core.3.0.0-beta.nupkg",
"registration": "https://api.nuget.org/v3/registration-sample/nuget.server.core/index.json"
}
],
"lower": "3.0.0-beta",
"upper": "3.0.0-beta"
}
]
}
En este caso concreto, el índice de registro tiene la página de registro insertada, por lo que no se necesitan solicitudes adicionales para capturar metadatos sobre versiones de paquete individuales.
Página Registro
La página de registro contiene hojas de registro. La dirección URL para capturar una página de registro viene determinada por la propiedad @id del objeto de página de registro mencionado anteriormente. La dirección URL no está pensada para ser predecible y siempre debe descubrirse mediante el documento de índice.
Advertencia
Da la casualidad que, en nuget.org, la dirección URL del documento de página de registro contiene el límite inferior y superior de la página. Sin embargo, un cliente nunca debe realizar esta hipótesis, ya que las implementaciones del servidor pueden cambiar la forma de la dirección URL siempre que el documento de índice tenga un vínculo válido.
Cuando no se indica la matriz items en el índice de registro, una solicitud HTTP GET del valor @id devolverá un documento JSON que tiene un objeto como raíz. El objeto tiene las siguientes propiedades:
| Nombre | Type | Obligatorio | Notas |
|---|---|---|---|
| @id | string | sí | Dirección URL de la página de registro |
| count | integer | sí | Número de hojas de registro en la página |
| items | matriz de objetos | sí | Matriz de hojas de registro y sus metadatos asociados |
| lower | string | sí | Versión más baja de SemVer 2.0.0 de la página (incluida) |
| primario | string | sí | Dirección URL del índice de registro |
| upper | string | sí | Versión más alta de SemVer 2.0.0 de la página (incluida) |
La forma de los objetos de hoja de registro es la misma que en el índice de registro anterior.
Solicitud de muestra
GET https://api.nuget.org/v3/registration-sample/ravendb.client/page/1.0.531/1.0.729-unstable.json
Asegúrate de capturar la dirección URL base (https://api.nuget.org/v3/registration-sample/ en este ejemplo) del índice de servicio, tal y como se indica en la sección de la dirección URL base.
Respuesta de muestra
{
"count": 2,
"lower": "1.0.531",
"parent": "https://api.nuget.org/v3/registration-sample/nuget.protocol.v3.example/index.json",
"upper": "1.0.729-unstable",
"items": [
{
"@id": "https://api.nuget.org/v3/registration-sample/nuget.protocol.v3.example/1.0.531.json",
"@type": "Package",
"commitId": "e0b9ca79-75b5-414f-9e3e-de9534b5cfd1",
"commitTimeStamp": "2017-10-26T14:12:19.3439088Z",
"catalogEntry": {
"@id": "https://api.nuget.org/v3/catalog0/data/2015.02.01.11.38.37/nuget.protocol.v3.example.1.0.531.json",
"@type": "PackageDetails",
"authors": "NuGet.org Team",
"iconUrl": "https://www.nuget.org/Content/gallery/img/default-package-icon.svg",
"id": "NuGet.Protocol.V3.Example",
"licenseUrl": "http://www.opensource.org/licenses/ms-pl",
"listed": false,
"packageContent": "https://api.nuget.org/v3-flatcontainer/nuget.protocol.v3.example/1.0.531/nuget.protocol.v3.example.1.0.531.nupkg",
"projectUrl": "https://github.com/NuGet/NuGetGallery",
"published": "1900-01-01T00:00:00+00:00",
"requireLicenseAcceptance": true,
"title": "NuGet V3 Protocol Example",
"version": "1.0.531"
},
"packageContent": "https://api.nuget.org/v3-flatcontainer/nuget.protocol.v3.example/1.0.531/nuget.protocol.v3.example.1.0.531.nupkg",
"registration": "https://api.nuget.org/v3/registration-sample/nuget.protocol.v3.example/index.json"
},
{
"@id": "https://api.nuget.org/v3/registration-sample/nuget.protocol.v3.example/1.0.729-unstable.json",
"@type": "Package",
"commitId": "e0b9ca79-75b5-414f-9e3e-de9534b5cfd1",
"commitTimeStamp": "2017-10-26T14:12:19.3439088Z",
"catalogEntry": {
"@id": "https://api.nuget.org/v3/catalog0/data/2015.02.01.18.22.05/nuget.protocol.v3.example.1.0.729-unstable.json",
"@type": "PackageDetails",
"authors": "NuGet.org Team",
"deprecation": {
"reasons": [
"CriticalBugs"
],
"message": "This package is unstable and broken!",
"alternatePackage": {
"id": "Newtonsoft.JSON",
"range": "12.0.2"
}
},
"iconUrl": "https://www.nuget.org/Content/gallery/img/default-package-icon.svg",
"id": "NuGet.Protocol.V3.Example",
"licenseUrl": "http://www.opensource.org/licenses/ms-pl",
"listed": false,
"packageContent": "https://api.nuget.org/v3-flatcontainer/nuget.protocol.v3.example/1.0.729-unstable/nuget.protocol.v3.example.1.0.729-unstable.nupkg",
"projectUrl": "https://github.com/NuGet/NuGetGallery",
"published": "1900-01-01T00:00:00+00:00",
"requireLicenseAcceptance": true,
"summary": "This package is an example for the V3 protocol.",
"title": "NuGet V3 Protocol Example",
"version": "1.0.729-Unstable"
},
"packageContent": "https://api.nuget.org/v3-flatcontainer/nuget.protocol.v3.example/1.0.729-unstable/nuget.protocol.v3.example.1.0.729-unstable.nupkg",
"registration": "https://api.nuget.org/v3/registration-sample/nuget.protocol.v3.example/index.json"
}
]
}
Hoja de registro
La hoja de registro contiene información sobre un id. de paquete y una versión específicos. Es posible que los metadatos sobre la versión específica no estén disponibles en este documento. Los metadatos del paquete se deben capturar desde el índice de registro o la página de registro (la cual se descubre por medio del índice de registro).
La dirección URL para capturar una hoja de registro se obtiene de la propiedad @id de un objeto de hoja de registro en un índice de registro o en una página de registro. Al igual que ocurre con el documento de página, la dirección URL no está pensada para ser predecible y siempre debe descubrirse mediante el objeto de página de registro.
Advertencia
Da la casualidad que, en nuget.org, la dirección URL del documento de hoja de registro contiene la versión del paquete. Sin embargo, un cliente nunca debe realizar esta hipótesis, ya que las implementaciones del servidor pueden cambiar la forma de la dirección URL siempre que el documento primario tenga un vínculo válido.
La hoja de registro es un documento JSON con un objeto raíz con las siguientes propiedades:
| Nombre | Type | Obligatorio | Notas |
|---|---|---|---|
| @id | string | sí | Dirección URL de la hoja de registro |
| catalogEntry | string | no | Dirección URL de la entrada de catálogo que generó esta hoja |
| lista | boolean | no | Debe considerarse como que está en la lista si está ausente |
| packageContent | string | no | Dirección URL del contenido del paquete (.nupkg) |
| published | string | no | Cadena que contiene una marca de tiempo ISO 8601 de cuando se publicó el paquete |
| registro | string | no | Dirección URL del índice de registro |
Nota:
En nuget.org, el valor published se ajusta en el año 1900, cuando el paquete no está en la lista.
Solicitud de muestra
GET https://api.nuget.org/v3/registration-sample/nuget.versioning/4.3.0.json
Asegúrate de capturar la dirección URL base (https://api.nuget.org/v3/registration-sample/ en este ejemplo) del índice de servicio, tal y como se indica en la sección de la dirección URL base.
Respuesta de muestra
{
"@id": "https://api.nuget.org/v3/registration-sample/nuget.versioning/4.3.0.json",
"catalogEntry": "https://api.nuget.org/v3/catalog0/data/2017.08.11.18.24.22/nuget.versioning.4.3.0.json",
"listed": true,
"packageContent": "https://api.nuget.org/v3-flatcontainer/nuget.versioning/4.3.0/nuget.versioning.4.3.0.nupkg",
"published": "2017-08-11T18:24:14.36+00:00",
"registration": "https://api.nuget.org/v3/registration-sample/nuget.versioning/index.json"
}
Comentarios
Próximamente: A lo largo de 2024 iremos eliminando gradualmente GitHub Issues como mecanismo de comentarios sobre el contenido y lo sustituiremos por un nuevo sistema de comentarios. Para más información, vea: https://aka.ms/ContentUserFeedback.
Enviar y ver comentarios de