Autocompletar

  • Artículo

Es posible compilar una experiencia de autocompletar el identificador del paquete y la versión utilizando la API V3. El recurso usado para realizar consultas de autocompletar es el recurso SearchAutocompleteService que se encuentra en el índice de servicio.

Control de versiones

Se usan los siguientes valores @type:

Valor de @type Notas
SearchAutocompleteService La versión inicial
SearchAutocompleteService/3.0.0-beta Alias de SearchAutocompleteService
SearchAutocompleteService/3.0.0-rc Alias de SearchAutocompleteService
SearchAutocompleteService/3.5.0 Incluye compatibilidad con los parámetros de consulta packageType

SearchAutocompleteService/3.5.0

Esta versión presenta compatibilidad con el parámetro de consulta packageType, lo que permite el filtrado por tipos de paquetes definidos por el autor. Es totalmente compatible con las consultas a SearchAutocompleteService.

URL base

La dirección URL base de las siguientes API es el valor de la propiedad @id asociada a uno de los valores @type de los recursos mencionados anteriormente. En el documento siguiente, se usará la dirección URL base del marcador de posición {@id}. La dirección URL base puede cambiar en función de los cambios de implementación o infraestructura dentro del origen del paquete, por lo que el software cliente debe capturarla dinámicamente desde el índice de servicio.

HTTP Methods

Todas las direcciones URL que se encuentran en el recurso de registro admiten los métodos HTTP GET y HEAD.

Búsqueda de los identificadores de paquete

La primera API de autocompletar admite la búsqueda de parte de una cadena de identificador de paquete. Esto es excelente cuando se desea proporcionar una característica de escritura anticipada de paquete en una interfaz de usuario integrada con un origen de paquete NuGet.

Un paquete que solo tenga versiones que no aparezcan en la lista no aparecerá en los resultados.

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

Parámetros de solicitud

Nombre En Tipo Obligatorio Notas
q Dirección URL string no Cadena que se comparará con los identificadores del paquete
skip URL integer no Número de resultados que se van a omitir, para la paginación
take URL integer no Número de resultados que se van a devolver, para la paginación
versión preliminar URL boolean no true o false que determina si se deben incluir los paquetes de versión preliminar
semVerLevel Dirección URL string no Cadena de versión de SemVer 1.0.0.
packageType Dirección URL string no Tipo de paquete que se usará para filtrar paquetes (agregado en SearchAutocompleteService/3.5.0)

La consulta de autocompletar q se analiza de una manera definida por la implementación del servidor. nuget.org permite consultar el prefijo de los tokens de identificador de paquete, que son partes del identificador generado al dividir el original por caracteres de símbolo y grafía Camel.

El parámetro skip se establece de forma predeterminada en 0.

El parámetro take debería ser un entero mayor que cero. La implementación del servidor puede imponer un valor máximo.

Si no se proporciona prerelease, se excluyen los paquetes de versión preliminar.

El parámetro de consulta semVerLevel se usa para participar en los paquetes de SemVer 2.0.0. Si se excluye este parámetro de consulta, solo se devolverán los identificadores de paquete con versiones compatibles con SemVer 1.0.0 (con las advertencias del control de versiones estándar de NuGet, como las cadenas de versión con 4 partes enteras). Si se proporciona semVerLevel=2.0.0, se devolverán los paquetes compatibles con SemVer 1.0.0 y SemVer 2.0.0. Consulte el artículo sobre la compatibilidad con SemVer 2.0.0 para nuget.org para obtener más información.

El parámetro packageType se usa para filtrar aún más los resultados de autocompletar solo en paquetes que tengan al menos un tipo de paquete que coincida con el nombre del tipo de paquete. Si el tipo de paquete proporcionado no es un tipo de paquete válido tal como se define en el documento de tipo de paquete, se devolverá un resultado vacío. Si el tipo de paquete proporcionado está vacío, no se aplicará ningún filtro. En otras palabras, el hecho de no pasar ningún valor al parámetro packageType será como si no se hubiera pasado el parámetro.

Respuesta

La respuesta es un documento JSON que contiene hasta take resultados de autocompletar.

El objeto JSON raíz tiene las siguientes propiedades:

Nombre Type Obligatorio Notas
totalHits integer sí Número total de coincidencias, sin tener en cuenta skip y take
data Matriz de cadenas sí Identificadores de paquete coincidentes con la solicitud

Solicitud de muestra

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

Asegúrate de capturar la dirección URL base (https://search-sample.nuget.org/autocomplete en este ejemplo) del índice de servicio, tal y como se indica en la sección de la dirección URL base.

Respuesta de muestra

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

Enumeración de versiones de paquetes

Una vez que se detecta un identificador de paquete mediante la API anterior, un cliente puede usar la API de autocompletar para enumerar las versiones del paquete para un identificador de paquete proporcionado.

Una versión del paquete que no esté en la lista no aparecerá en los resultados.

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

Parámetros de solicitud

Nombre En Tipo Obligatorio Notas
id Dirección URL string sí El identificador de paquete para el que se capturarán las versiones
versión preliminar URL boolean no true o false que determina si se deben incluir los paquetes de versión preliminar
semVerLevel Dirección URL string no Cadena de versión de SemVer 2.0.0.

Si no se proporciona prerelease, se excluyen los paquetes de versión preliminar.

El parámetro de consulta semVerLevel se usa para participar en los paquetes de SemVer 2.0.0. Si se excluye este parámetro de consulta, solo se devolverán las versiones de SemVer 1.0.0. Si se proporciona semVerLevel=2.0.0, se devolverán las versiones SemVer 1.0.0 y SemVer 2.0.0. Consulte el artículo sobre la compatibilidad con SemVer 2.0.0 para nuget.org para obtener más información.

Respuesta

La respuesta es un documento JSON que contiene todas las versiones de paquete del identificador de paquete proporcionado, filtrando por los parámetros de consulta especificados.

El objeto JSON raíz tiene la siguiente propiedad:

Nombre Type Obligatorio Notas
data Matriz de cadenas sí Las versiones del paquete coincidentes con la solicitud

Las versiones de paquete de la matriz data pueden contener metadatos de compilación de SemVer 2.0.0 (por ejemplo, 1.0.0+metadata) si se proporciona semVerLevel=2.0.0 en la cadena de consulta.

Solicitud de ejemplo

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

Respuesta de muestra

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