Compartilhar via


Pesquisar

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