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:

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

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.

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:

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:

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:

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:

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