Metadados de pacote

Artigo
12/22/2023

É possível buscar metadados sobre os pacotes disponíveis em uma origem de pacote usando a API do NuGet V3. Esses metadados podem ser obtidos usando o recurso RegistrationsBaseUrl encontrado no índice de serviço.

A coleção dos documentos encontrados em RegistrationsBaseUrl são muitas vezes chamados de “registros” ou “blobs de registro”. O conjunto de documentos sob um único RegistrationsBaseUrl é chamado de “hive de registro”. Um hive de registro contém metadados sobre cada pacote disponível em uma origem do pacote.

Observação

O recurso de metadados do pacote não contém todos os metadados para pacotes. Use o recurso de pesquisa para localizar proprietários, downloads ou status de reserva de prefixo de pacotes.

Controle de versão

Os seguintes valores de @type são usados:

@type valor	Observações
RegistrationsBaseUrl	O lançamento inicial
RegistrationsBaseUrl/3.0.0-beta	Alias de `RegistrationsBaseUrl`
RegistrationsBaseUrl/3.0.0-rc	Alias de `RegistrationsBaseUrl`
RegistrationsBaseUrl/3.4.0	Respostas do gzip
RegistrationsBaseUrl/3.6.0	Inclui pacotes do SemVer 2.0.0

Isso representa três hives de registro distintos disponíveis para várias versões de clientes.

RegistrationsBaseUrl

Esses registros não são compactados (o que significa que eles usam um Content-Encoding: identity implícito). Os pacotes do SemVer 2.0.0 estão excluídos deste hive.

RegistrationsBaseUrl/3.4.0

Esses registros são compactados usando Content-Encoding: gzip. Os pacotes do SemVer 2.0.0 estão excluídos deste hive.

RegistrationsBaseUrl/3.6.0

Esses registros são compactados usando Content-Encoding: gzip. Os pacotes SemVer 2.0.0 estão incluídos neste hive. Para obter mais informações sobre o SemVer 2.0.0, consulte Suporte do SemVer 2.0.0 para nuget.org.

URL base

A URL base para as APIs a seguir é o valor da propriedade @id associada aos valores de @type de recurso mencionados anteriormente. No documento a seguir, a URL base {@id} do espaço reservado será usada. A URL base pode ser alterada com base na implementação ou nas alterações de infraestrutura dentro da origem do pacote, portanto, ela deve ser buscada dinamicamente no índice de serviço pelo software cliente.

Métodos HTTP

Todos os URLs encontrados no recurso de registro são compatíveis com os métodos HTTP GET e HEAD.

Índice de registro

Os grupos de recursos de registro empacotam metadados por ID do pacote. Não é possível obter dados sobre mais de uma ID de pacote ao mesmo tempo. Esse recurso não fornece nenhuma maneira de descobrir IDs de pacote. Em vez disso, presume-se que o cliente já saiba a ID do pacote desejado. Os metadados disponíveis sobre cada versão do pacote variam de acordo com a implementação do servidor. Os blobs de registro de pacote têm a seguinte estrutura hierárquica:

Índice: o ponto de entrada para os metadados do pacote, compartilhado por todos os pacotes em uma origem com a mesma ID de pacote.
Página: um agrupamento de versões de pacotes. O número de versões de pacote em uma página é definido pela implementação do servidor.
Folha: um documento específico para uma única versão do pacote.

A URL do índice de registro é previsível e pode ser determinada pelo cliente que recebe uma ID de pacote e o valor de @id do recurso de registro do índice de serviço. As URLs das páginas e folhas de registro são descobertas inspecionando o índice de registro.

Páginas e folhas de registro

Embora não seja estritamente necessário para uma implementação de servidor armazenar folhas de registro em documentos de página de registro separados, é uma prática recomendada para conservar a memória do lado do cliente. Em vez de embutir todas as folhas de registro no índice ou armazenar imediatamente as folhas em documentos de página, é recomendável que a implementação do servidor defina alguma heurística para escolher entre as duas abordagens com base no número de versões de pacote ou no tamanho cumulativo de folhas de pacote.

Armazenar todas as versões do pacote (folhas) no índice de registro gera economia no número de solicitações HTTP necessárias para buscar metadados do pacote, mas significa que um documento maior deve ser baixado e mais memória do cliente deve ser alocada. Por outro lado, se a implementação do servidor armazena imediatamente folhas de registro em documentos de página separados, o cliente deve executar mais solicitações HTTP para obter as informações necessárias.

A heurística que o nuget.org usa é a seguinte: se houver 128 ou mais versões de um pacote, quebre as folhas em páginas de tamanho 64. Se houver menos de 128 versões, insira todas as folhas no índice de registro. Observe que isso significa que pacotes de 65 a 127 versões terão duas páginas no índice, mas ambas as páginas serão embutidas.

GET {@id}/{LOWER_ID}/index.json

Parâmetros da solicitação

Nome	Em	Tipo	Obrigatória	Observações
LOWER_ID	URL	string	sim	A ID do pacote, em minúsculas

O valor LOWER_ID é a ID do pacote desejado em minúsculas usando as regras implementadas pelo método System.String.ToLowerInvariant() da .NET.

Resposta

A resposta é um documento JSON que tem um objeto raiz com as seguintes propriedades:

Nome	Digitar	Obrigatória	Observações
contagem	inteiro	sim	O número de páginas de registro no índice
itens	matriz de objetos	sim	A matriz de páginas de registro

Cada item na matriz items do objeto de índice é um objeto JSON que representa uma página de registro.

Objeto da página de registro

O objeto da página de registro encontrado no índice de registro tem as seguintes propriedades:

Nome	Digitar	Obrigatória	Observações
@id	string	sim	A URL para a página de registro
contagem	inteiro	sim	O número de folhas de registro na página
itens	matriz de objetos	não	A matriz de folhas de registro e seus metadados associados
lower	string	sim	A versão mais antiga do SemVer 2.0.0 na página (inclusive)
primário	string	não	A URL para o índice de registro
upper	string	sim	A versão mais alta do SemVer 2.0.0 na página (inclusive)

Os limites lower e upper do objeto de página são úteis quando os metadados para uma versão de página específica são necessários. Esses limites podem ser usados para buscar a única página de registro necessária. As cadeias de caracteres de versão seguem as regras de versão do NuGet. As cadeias de caracteres de versão são normalizadas e não incluem metadados de compilação. Como acontece com todas as versões no ecossistema do NuGet, a comparação de cadeias de caracteres da versão é implementada usando as regras de precedência de versão do SemVer 2.0.0.

A propriedade parent só aparecerá se o objeto de página de registro tiver a propriedade items.

Se a propriedade items não estiver presente no objeto de página de registro, a URL especificada em @id deve ser usada para buscar metadados sobre versões de pacotes individuais. Às vezes, a matriz items é excluída do objeto de página como uma otimização. Se o número de versões de uma única ID de pacote for muito grande, o documento de índice de registro será enorme e desperdiçado para processar para um cliente que só se preocupa com uma versão específica ou um pequeno intervalo de versões.

Observe que, se a propriedade items estiver presente, a propriedade @id não precisará ser usada, pois todos os dados da página já estão embutidos na propriedade items.

Cada item na matriz items do objeto de página é um objeto JSON que representa uma folha de registro e seus metadados associados.

Objeto folha de registro em uma página

O objeto folha de registro encontrado em uma página de registro tem as seguintes propriedades:

Nome	Digitar	Obrigatória	Observações
@id	string	sim	A URL para a folha de registro
catalogEntry	objeto	sim	A entrada de catálogo que contém os metadados do pacote
packageContent	string	sim	A URL para o conteúdo do pacote (.nupkg)

Cada objeto folha de registro representa dados associados a uma única versão do pacote.

Entrada do catálogo

A propriedade catalogEntry no objeto folha de registro tem as seguintes propriedades:

Nome	Digitar	Obrigatória	Observações
@id	string	sim	A URL do documento usado para produzir esse objeto
authors	cadeia de caracteres ou matriz de cadeias de caracteres	não
dependencyGroups	matriz de objetos	não	As dependências do pacote, agrupadas por estrutura de destino
depreciação	objeto	não	A depreciação associada ao pacote
descrição	string	não
iconUrl	string	não
ID	cadeia de caracteres	sim	A ID do pacote
linguagem	string	não
licenseUrl	string	não
licenseExpression	string	não
listados	boolean	não	Deve ser considerado como listado se ausente
minClientVersion	string	não
packageContent	string	não	Duplicata da mesma propriedade no objeto pai, incluída apenas por ser herdada
projectUrl	string	não
published	string	não	Uma cadeia de caracteres que contém um carimbo de data/hora ISO 8601 de quando o pacote foi publicado
readmeUrl	string	não	Uma URL para a exibição renderizada (página da Web HTML) do pacote README
requireLicenseAcceptance	boolean	não
summary	string	não
marcas	cadeia de caracteres ou matriz de cadeias de caracteres	não
title	string	não
version	string	sim	A cadeia de caracteres da versão completa após a normalização
vulnerabilities	matriz de objetos	não	As vulnerabilidades de segurança do pacote

A propriedade version do pacote é a cadeia de caracteres de versão completa após a normalização. Isso significa que os dados de compilação do SemVer 2.0.0 podem ser incluídos aqui.

A propriedade dependencyGroups é uma matriz de objetos que representa as dependências do pacote, agrupadas por estrutura de destino. Se o pacote não tiver dependências, a propriedade dependencyGroups está ausente, uma matriz vazia ou a propriedade dependencies de todos os grupos está vazia ou ausente.

O valor da propriedade licenseExpression está em conformidade com a sintaxe da expressão de licença do NuGet.

Observação

Em nuget.org, o valor de published é definido como ano 1900 quando o pacote não está listado.

Grupo de dependência de pacote

Cada objeto de grupo de dependência tem as seguintes propriedades:

Nome	Digitar	Obrigatória	Observações
targetFramework	string	não	A estrutura de destino à qual essas dependências são aplicáveis
dependencies	matriz de objetos	não

A cadeia de caracteres targetFramework usa o formato implementado pela biblioteca do .NET NuGet.Frameworks do NuGet. Se nenhum targetFramework for especificado, o grupo de dependência se aplicará a todas as estruturas de destino.

A propriedade dependencies é uma matriz de objetos, cada um representando uma dependência de pacote do pacote atual.

Dependência de pacote

Cada dependência de pacote tem as seguintes propriedades:

Nome	Digitar	Obrigatória	Observações
ID	cadeia de caracteres	sim	A ID da dependência de pacote
range	objeto	não	O intervalo de versão permitido da dependência
registro	string	não	A URL para o índice de registro para essa dependência

Se a propriedade range for excluída ou uma cadeia de caracteres vazia, o cliente deverá usar como padrão o intervalo de versão (, ). Ou seja, qualquer versão da dependência é permitida. O valor de * não é permitido para a propriedade range.

Reprovação de pacote

Cada depreciação de pacote tem as seguintes propriedades:

Nome	Digitar	Obrigatória	Observações
Motivos	matriz de cadeias de caracteres	sim	As razões pelas quais o pacote foi preterido
message	string	não	Os detalhes adicionais sobre essa depreciação
alternatePackage	objeto	não	O pacote alternativo que deve ser usado em vez disso

A propriedade reasons deve conter pelo menos uma cadeia de caracteres e deve conter apenas cadeias de caracteres da tabela a seguir:

Motivo	Descrição
Herdada	O pacote não recebe mais manutenção
CriticalBugs	O pacote tem bugs que o tornam inadequado para uso
Outro	O pacote foi preterido devido a um motivo que não está nesta lista

Se a propriedade reasons contiver cadeias de caracteres que não são do conjunto conhecido, elas deverão ser ignoradas. As cadeias de caracteres não diferenciam maiúsculas de minúsculas, portanto legacy devem ser tratado da mesma forma que Legacy. Não há restrição de ordenação na matriz, portanto, as cadeias de caracteres podem ser organizadas em qualquer ordem arbitrária. Além disso, se a propriedade contiver apenas cadeias de caracteres que não são do conjunto conhecido, ela deverá ser tratada como se contivesse apenas a cadeia de caracteres “Outra”.

Pacote alternativo

O objeto do pacote alternativo tem as seguintes propriedades:

Nome	Digitar	Obrigatória	Observações
ID	cadeia de caracteres	sim	A ID do pacote alternativo
range	objeto	não	O intervalo de versões permitido, ou `*`, se qualquer versão for permitida

Vulnerabilidades

Uma matriz de objetos vulnerability. Cada vulnerabilidade tem as seguintes propriedades:

Nome	Digitar	Obrigatória	Observações
advisoryUrl	string	sim	Localização do aviso de segurança para o pacote
severidade	string	sim	Gravidade do aviso: “0” = Baixa, “1” = Moderada, “2” = Alta, “3” = Crítica

Solicitação de exemplo

GET https://api.nuget.org/v3/registration-sample/nuget.server.core/index.json

Efetue fetch do URL base (https://api.nuget.org/v3/registration-sample/ neste exemplo) do índice de serviço, conforme mencionado na seção URL base.

Resposta de exemplo

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

Nesse caso específico, o índice de registro tem a página de registro embutida para que nenhuma solicitação extra seja necessária para buscar metadados sobre versões de pacotes individuais.

Página de registro

A página de registro contém folhas de registro. A URL para buscar uma página de registro é determinada pela propriedade @id no objeto da página de registro mencionado acima. A URL não deve ser previsível e sempre deve ser descoberta por meio do documento de índice.

Aviso

Em nuget.org, a URL do documento da página de registro contém coincidentemente o limite inferior e superior da página. No entanto, essa pressuposição nunca deve ser feita por um cliente, uma vez que as implementações de servidor são livres para alterar a forma da URL, desde que o documento de índice tenha um link válido.

Quando a matriz items não é fornecida no índice de registro, uma solicitação HTTP GET do valor @id retornará um documento JSON que tem um objeto como raiz. O objeto tem as seguintes propriedades:

Nome	Digitar	Obrigatória	Observações
@id	string	sim	A URL para a página de registro
contagem	inteiro	sim	O número de folhas de registro na página
itens	matriz de objetos	sim	A matriz de folhas de registro e seus metadados associados
lower	string	sim	A versão mais antiga do SemVer 2.0.0 na página (inclusive)
primário	string	sim	A URL para o índice de registro
upper	string	sim	A versão mais alta do SemVer 2.0.0 na página (inclusive)

A forma dos objetos da folha de registro é a mesma do índice de registro acima.

Solicitação de exemplo

GET https://api.nuget.org/v3/registration-sample/ravendb.client/page/1.0.531/1.0.729-unstable.json

Efetue fetch do URL base (https://api.nuget.org/v3/registration-sample/ neste exemplo) do índice de serviço, conforme mencionado na seção URL base.

Resposta de exemplo

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

Folha de registro

A folha de registro contém informações sobre uma ID e versão de pacote específicas. Os metadados sobre a versão específica podem não estar disponíveis neste documento. Os metadados do pacote devem ser obtidos no índice de registro ou na página de registro (que é descoberta usando o índice de registro).

A URL para buscar uma folha de registro é obtida da propriedade @id de um objeto de folha de registro em um índice de registro ou página de registro. Tal como acontece com o documento de página. a URL não deve ser previsível e deve sempre ser descoberta por meio do objeto da página de registro.

Aviso

Em nuget.org, a URL do documento de folha de registro coincidentemente contém a versão do pacote. No entanto, essa pressuposição nunca deve ser feita por um cliente, uma vez que as implementações de servidor são livres para alterar a forma da URL, desde que o documento pai tenha um link válido.

A folha de registro é um documento JSON com um objeto raiz com as seguintes propriedades:

Nome	Digitar	Obrigatória	Observações
@id	string	sim	A URL para a folha de registro
catalogEntry	string	não	A URL para a entrada de catálogo que produziu essas folhas
listados	boolean	não	Deve ser considerado como listado se ausente
packageContent	string	não	A URL para o conteúdo do pacote (.nupkg)
published	string	não	Uma cadeia de caracteres que contém um carimbo de data/hora ISO 8601 de quando o pacote foi publicado
registro	string	não	A URL para o índice de registro

Observação

Em nuget.org, o valor de published é definido como ano 1900 quando o pacote não está listado.

Solicitação de exemplo

GET https://api.nuget.org/v3/registration-sample/nuget.versioning/4.3.0.json

Efetue fetch do URL base (https://api.nuget.org/v3/registration-sample/ neste exemplo) do índice de serviço, conforme mencionado na seção URL base.

Resposta de exemplo

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

Compartilhar via

Metadados de pacote

Controle de versão

RegistrationsBaseUrl

RegistrationsBaseUrl/3.4.0

RegistrationsBaseUrl/3.6.0

URL base

Métodos HTTP

Índice de registro

Páginas e folhas de registro

Parâmetros da solicitação

Resposta

Objeto da página de registro

Objeto folha de registro em uma página

Entrada do catálogo

Grupo de dependência de pacote

Dependência de pacote

Reprovação de pacote

Pacote alternativo

Vulnerabilidades

Solicitação de exemplo

Resposta de exemplo

Página de registro

Solicitação de exemplo

Resposta de exemplo

Folha de registro

Solicitação de exemplo

Resposta de exemplo

Comentários

Recursos adicionais