Partilhar via


Metadados de pacote

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