Partilhar via

Preenchimento automático

  • Artigo

É possível criar uma experiência de preenchimento automático de versão e ID de pacote usando a API V3. O recurso usado para fazer consultas de preenchimento automático é o recurso SearchAutocompleteService encontrado no índice de serviço.

Controle de versão

Os seguintes valores de @type são usados:

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

SearchAutocompleteService/3.5.0

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

URL base

A URL base para as APIs 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 IDs de pacotes

A primeira API de preenchimento automático oferece suporte à pesquisa de parte de uma cadeia de caracteres de ID de pacote. Isso é ótimo quando você deseja fornecer um recurso de digitação antecipada de pacote em uma interface de usuário integrada a uma fonte de pacotes do NuGet.

Um pacote com apenas versões não listadas não aparecerá nos resultados.

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 A cadeia de caracteres a ser comparada com IDs de 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 SearchAutocompleteService/3.5.0)

A consulta de preenchimento automático q é analisada de uma maneira definida pela implementação do servidor. o nuget.org oferece suporte à consulta do prefixo dos tokens de ID do pacote, que são partes da ID produzidas dividindo o original por maiúsculas e minúsculas e caracteres de símbolo.

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 IDs de pacote com versões compatíveis com o SemVer 1.0.0 serão retornadas (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 do preenchimento automático 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é take resultados de preenchimento automático.

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 cadeias de caracteres sim As IDs de pacote correspondidas pela solicitação

Solicitação de exemplo

GET https://search-sample.nuget.org/autocomplete?q=storage&prerelease=true

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

Resposta de exemplo

{
  "totalHits": 571,
  "data": [
    "WindowsAzure.Storage",
    "Storage.Net",
    "CK.Storage",
    "NCL.Storage",
    "DK.Storage",
    "Nine.Storage.Test",
    "Touch.Storage.Aws",
    "StorageAPIClient",
    "StorageAccess",
    "Storage.Net.Microsoft.Azure.Storage",
    "UnofficialAzure.StorageClient",
    "StorageAccess12",
    "AWSSDK.StorageGateway",
    "StorageExtensions",
    "Cloud.Storage",
    "lighthouse.storage",
    "ZU.Storage.Redis",
    "Magicodes.Storage",
    "Masticore.Storage",
    "hq.storage"
  ]
}

Enumerar versões do pacote

Depois que uma ID de pacote é descoberto usando a API anterior, um cliente pode usar a API de preenchimento automático para enumerar versões de pacote para um ID de pacote fornecido.

Uma versão do pacote que não está listada não aparecerá nos resultados.

GET {@id}?id={ID}&prerelease={PRERELEASE}&semVerLevel={SEMVERLEVEL}

Parâmetros da solicitação

Nome Em Tipo Obrigatória Observações
ID URL string sim A ID do pacote para buscar versões
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 2.0.0 do SemVer

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

O parâmetro de pesquisa semVerLevel é usado para aceitar pacotes do SemVer 2.0.0. Se esse parâmetro de consulta for excluído, somente as versões do SemVer 1.0.0 serão retornadas. Se semVerLevel=2.0.0 for fornecido, as versões SemVer 1.0.0 e SemVer 2.0.0 serão retornadas. Consulte o suporte do SemVer 2.0.0 para nuget.org para obter mais informações.

Resposta

A resposta é um documento JSON que contém todas as versões de pacote da ID do pacote fornecida, filtrando pelos parâmetros de consulta fornecidos.

O objeto JSON raiz tem a seguinte propriedade:

Nome Digitar Obrigatória Observações
data matriz de cadeias de caracteres sim As versões do pacote correspondidas pela solicitação

As versões do pacote na matriz data podem conter metadados de compilação do SemVer 2.0.0 (por exemplo, 1.0.0+metadata) se semVerLevel=2.0.0 for fornecido na cadeia de caracteres de consulta.

Solicitação de exemplo

GET https://api-v2v3search-0.nuget.org/autocomplete?id=nuget.protocol&prerelease=true

Resposta de exemplo

{
  "data": [
    "4.3.0-preview3-4168",
    "4.3.0-preview4",
    "4.3.0-rtm-4324",
    "4.3.0",
    "4.4.0-preview3-4475",
    "4.4.0"
  ]
}