Pesquisar

Artigo
03/14/2024

É possível pesquisar pacotes disponíveis em uma origem de pacote usando a API V3. O recurso usado para pesquisa é o recurso SearchQueryService encontrado no índice de serviço.

Controle de versão

Os seguintes valores de @type são usados:

@type valor	Observações
SearchQueryService	O lançamento inicial
SearchQueryService/3.0.0-beta	Alias de `SearchQueryService`
SearchQueryService/3.0.0-rc	Alias de `SearchQueryService`
SearchQueryService/3.5.0	Inclui suporte para parâmetro de consulta `packageType`

SearchQueryService/3.5.0

Esta versão introduz suporte para o parâmetro de consulta packageType e a propriedade de resposta packageTypes, permitindo a filtragem por tipos de pacote definidos pelo autor. É totalmente compatível com versões anteriores de consultas ao SearchQueryService.

URL base

A URL base para a API a seguir é o valor da propriedade @id associada a um dos valores de recurso @type 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.

Pesquisar pacotes

A API de pesquisa permite que um cliente consulte uma página de pacotes correspondentes a uma consulta de pesquisa especificada. A interpretação da consulta de pesquisa (por exemplo, a tokenização dos termos de pesquisa) é determinada pela implementação do servidor, mas a expectativa geral é que a consulta de pesquisa seja usada para corresponder IDs de pacote, títulos, descrições e tags. Outros campos de metadados do pacote também podem ser considerados.

Um pacote não listado nunca deve aparecer nos resultados da busca.

GET {@id}?q={QUERY}&skip={SKIP}&take={TAKE}&prerelease={PRERELEASE}&semVerLevel={SEMVERLEVEL}&packageType={PACKAGETYPE}

Parâmetros da solicitação

Nome	Em	Tipo	Obrigatória	Observações
q	URL	string	não	Os termos da pesquisa a serem usados para filtrar pacotes
skip	URL	Número inteiro	não	O número de resultados a serem ignorados, para paginação
take	URL	Número inteiro	não	O número de resultados a serem retornados, para paginação
pré-lançamento	URL	boolean	não	`true` ou `false` determina se os pacotes de pré-lançamento devem ser incluídos
semVerLevel	URL	string	não	Uma cadeia de caracteres da versão 1.0.0 do SemVer
packageType	URL	string	não	O tipo de pacote a ser usado para filtrar pacotes (adicionado em `SearchQueryService/3.5.0`)

A consulta de pesquisa q é analisada de uma maneira definida pela implementação do servidor. nuget.org oferece suporte à filtragem básica em uma variedade de campos. Se q não for fornecido, todos os pacotes devem ser retornados, dentro dos limites impostos por ignorar e pegar. Isso habilita a guia “Navegar” na experiência do Visual Studio do NuGet.

O parâmetro skip assume 0 como padrão.

O parâmetro take deve ser um inteiro maior que zero. A implementação do servidor pode impor um valor máximo.

Observação

nuget.org limita o parâmetro skip a 3.000 e o parâmetro take a 1.000.

Se prerelease não for fornecido, os pacotes de pré-lançamento serão excluídos.

O parâmetro de consulta semVerLevel é usado para aceitar pacotes do SemVer 2.0.0. Se esse parâmetro de consulta for excluído, somente pacotes com versões compatíveis com o SemVer 1.0.0 serão retornados (com as advertências de controle de versão padrão do NuGet, como cadeias de caracteres de versão com 4 partes inteiras). Se semVerLevel=2.0.0 for fornecido, os pacotes compatíveis com SemVer 1.0.0 e SemVer 2.0.0 serão retornados. Consulte o suporte do SemVer 2.0.0 para nuget.org para obter mais informações.

O parâmetro packageType é usado para filtrar ainda mais os resultados da busca para somente pacotes que tenham pelo menos um tipo de pacote correspondente ao nome do tipo de pacote. Se o tipo de pacote fornecido não for um tipo de pacote válido, conforme definido pelo Documento tipo de pacote, um resultado vazio será retornado. Se o tipo de pacote fornecido estiver vazio, nenhum filtro será aplicado. Em outras palavras, não passar um valor para o parâmetro packageType será como se o parâmetro não tivesse sido passado.

Resposta

A resposta é um documento JSON contendo até os resultados da busca take. Os resultados da busca são agrupados por ID do pacote.

O objeto JSON raiz tem as seguintes propriedades:

Nome	Digitar	Obrigatória	Observações
totalHits	Número inteiro	sim	O número total de correspondências, desconsiderando `skip` e `take`
data	matriz de objetos	sim	Os resultados da busca correspondem à solicitação

Resultado da pesquisa

Cada item na matriz data é um objeto JSON composto por um grupo de versões de pacote que compartilham a mesma ID de pacote. O objeto tem as seguintes propriedades:

Nome	Digitar	Obrigatória	Observações
ID	cadeia de caracteres	sim	A ID do pacote correspondente
version	string	sim	A cadeia de caracteres de versão completa do SemVer 2.0.0 do pacote (pode conter metadados de compilação)
descrição	string	não
versões	matriz de objetos	sim	Todas as versões do pacote que correspondem ao parâmetro `prerelease`
authors	cadeia de caracteres ou matriz de cadeias de caracteres	não
iconUrl	string	não
licenseUrl	string	não
owners	cadeia de caracteres ou matriz de cadeias de caracteres	não	Uma sequência representa o nome de usuário de um único proprietário
projectUrl	string	não
registro	string	não	A URL absoluta para o índice de registro associado
summary	string	não
tags	cadeia de caracteres ou matriz de cadeias de caracteres	não
title	string	não
totalDownloads	Número inteiro	não	Esse valor pode ser inferido pela soma dos downloads na matriz `versions`
verificada	boolean	não	Um booliano JSON indicando se o pacote é verificado
packageTypes	matriz de objetos	sim	Os tipos de pacote definidos pelo autor do pacote (adicionado em `SearchQueryService/3.5.0`)

Em nuget.org, um pacote verificado é aquele que tem uma ID de pacote correspondente a um prefixo de ID reservado e de propriedade de um dos proprietários do prefixo reservado. Para obter mais informações, confira a documentação sobre reserva de prefixos de ID.

Os metadados contidos no objeto de resultado da busca são retirados da versão mais recente do pacote. Cada item da matriz versions é um objeto JSON com as seguintes propriedades:

Nome	Digitar	Obrigatória	Observações
@id	string	sim	A URL absoluta para a folha de registro associada
version	string	sim	A cadeia de caracteres de versão completa do SemVer 2.0.0 do pacote (pode conter metadados de compilação)
downloads	Número inteiro	sim	O número de downloads para esta versão específica do pacote

A matriz packageTypes sempre consistirá em pelo menos um (1) item. O tipo de pacote para uma determinada ID de pacote é considerado como os tipos de pacote definidos pela última versão do pacote em relação aos outros parâmetros de pesquisa. Cada item da matriz packageTypes é um objeto JSON com as seguintes propriedades:

Nome	Digitar	Obrigatória	Observações
name	string	sim	O nome do tipo de pacote.

Solicitação de exemplo

GET https://search-sample.nuget.org/query?q=NuGet.Versioning&prerelease=false&semVerLevel=2.0.0

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

Resposta de exemplo

{
  "totalHits": 2,
  "data": [
    {
      "registration": "https://api.nuget.org/v3/registration-sample/nuget.versioning/index.json",
      "id": "NuGet.Versioning",
      "version": "4.4.0",
      "description": "NuGet's implementation of Semantic Versioning.",
      "summary": "",
      "title": "NuGet.Versioning",
      "licenseUrl": "https://raw.githubusercontent.com/NuGet/NuGet.Client/dev/LICENSE.txt",
      "tags": [ "semver", "semantic", "versioning" ],
      "authors": [ "NuGet" ],
      "totalDownloads": 141896,
      "verified": true,
      "packageTypes": [
        {
          "name": "Dependency"
        }
      ],
      "versions": [
        {
          "version": "3.3.0",
          "downloads": 50343,
          "@id": "https://api.nuget.org/v3/registration-sample/nuget.versioning/3.3.0.json"
        },
        {
          "version": "3.4.3",
          "downloads": 27932,
          "@id": "https://api.nuget.org/v3/registration-sample/nuget.versioning/3.4.3.json"
        },
        {
          "version": "4.0.0",
          "downloads": 63004,
          "@id": "https://api.nuget.org/v3/registration-sample/nuget.versioning/4.0.0.json"
        },
        {
          "version": "4.4.0",
          "downloads": 617,
          "@id": "https://api.nuget.org/v3/registration-sample/nuget.versioning/4.4.0.json"
        }
      ]
    },
    {
      "@id": "https://api.nuget.org/v3/registration-sample/nerdbank.gitversioning/index.json",
      "@type": "Package",
      "registration": "https://api.nuget.org/v3/registration-sample/nerdbank.gitversioning/index.json",
      "id": "Nerdbank.GitVersioning",
      "version": "2.0.41",
      "description": "Stamps your assemblies with semver 2.0 compliant git commit specific version information and provides NuGet versioning information as well.",
      "summary": "Stamps your assemblies with semver 2.0 compliant git commit specific version information and provides NuGet versioning information as well.",
      "title": "Nerdbank.GitVersioning",
      "licenseUrl": "https://raw.githubusercontent.com/AArnott/Nerdbank.GitVersioning/ed547462f7/LICENSE.txt",
      "projectUrl": "http://github.com/aarnott/Nerdbank.GitVersioning",
      "tags": [ "git", "commit", "versioning", "version", "assemblyinfo" ],
      "authors": [ "Andrew Arnott" ],
      "totalDownloads": 11906,
      "verified": false,
      "versions": [
        {
          "version": "1.6.35",
          "downloads": 10229,
          "@id": "https://api.nuget.org/v3/registration-sample/nerdbank.gitversioning/1.6.35.json"
        },
        {
          "version": "2.0.41",
          "downloads": 1677,
          "@id": "https://api.nuget.org/v3/registration-sample/nerdbank.gitversioning/2.0.41.json"
        }
      ]
    }
  ]
}

Compartilhar via