Metadatos de paquete

Artículo
12/22/2023

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"
}

Compartir a través de

Metadatos de paquete

Control de versiones

RegistrationsBaseUrl

RegistrationsBaseUrl/3.4.0

RegistrationsBaseUrl/3.6.0

URL base

Métodos HTTP

Índice de registro

Páginas de registro y hojas

Parámetros de solicitud

Respuesta

Objeto de página de registro

Objeto de hoja de registro en una página

Entrada de catálogo

Grupo de dependencias de paquete

Dependencia de paquete

Paquete en desuso

Paquete alternativo

Vulnerabilidades

Solicitud de muestra

Respuesta de muestra

Página Registro

Solicitud de muestra

Respuesta de muestra

Hoja de registro

Solicitud de muestra

Respuesta de muestra

Comentarios

Recursos adicionales