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"
}
Comentários
Brevemente: Ao longo de 2024, vamos descontinuar progressivamente o GitHub Issues como mecanismo de feedback para conteúdos e substituí-lo por um novo sistema de feedback. Para obter mais informações, veja: https://aka.ms/ContentUserFeedback.
Submeter e ver comentários