Buscar

Artículo
12/22/2023

Es posible buscar paquetes disponibles en un origen de paquete mediante la API V3. El recurso utilizado para realizar búsquedas es el recurso SearchQueryService que se encuentra en el índice de servicio.

Control de versiones

Se usan los siguientes valores @type:

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

SearchQueryService/3.5.0

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

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.

Métodos HTTP

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

Búsqueda de paquetes

La API de búsqueda permite a un cliente consultar una página de paquetes que se corresponda con una consulta de búsqueda especificada. La interpretación de la consulta de búsqueda (por ejemplo, la tokenización de los términos de búsqueda) viene determinada por la implementación del servidor, pero la expectativa general es que la consulta de búsqueda se utilice para buscar id., títulos, descripciones y etiquetas de paquete coincidentes. También se pueden tener en cuenta otros campos de metadatos del paquete.

Un paquete que no aparezca en la lista tampoco debería aparecer nunca en los resultados de la búsqueda.

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	Términos de búsqueda que se utilizan para filtrar paquetes
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 `SearchQueryService/3.5.0`)

La consulta de búsqueda q se analiza de una manera definida por la implementación del servidor. nuget.org admite el filtrado básico en una variedad de campos. Si no se proporciona q, se deben devolver todos los paquetes dentro de los límites impuestos por las acciones “Skip” y “Take”. Esto habilita la pestaña “Examinar” en la experiencia de Visual Studio de NuGet.

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.

Nota:

nuget.org limita el parámetro skip a 3000, y el parámetro take a 1000.

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 paquetes 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 la búsqueda solo en paquetes que tengan al menos un tipo de paquete que se corresponda 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 la búsqueda. Los resultados de la búsqueda se agrupan por id. de paquete.

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 objetos	sí	Resultados de la búsqueda que se corresponden con la solicitud

Resultado de la búsqueda

Cada elemento de la matriz data es un objeto JSON formado por un grupo de versiones de paquete que comparten el mismo id. de paquete. El objeto tiene las siguientes propiedades:

Nombre	Type	Obligatorio	Notas
id	string	sí	Id. del paquete coincidente
version	string	sí	Cadena de versión completa de SemVer 2.0.0 del paquete (podría contener metadatos de generación)
descripción	string	no
versions	matriz de objetos	sí	Todas las versiones del paquete que se correspondan con el parámetro `prerelease`
authors	cadena o matriz de cadenas	no
iconUrl	string	no
licenseUrl	string	no
owners	cadena o matriz de cadenas	no	Una cadena representa el nombre de usuario de un solo propietario.
projectUrl	string	no
registro	string	no	Dirección URL absoluta del índice de registro asociado
summary	string	no
etiquetas	cadena o matriz de cadenas	no
title	string	no
totalDownloads	integer	no	Este valor se puede deducir de la suma de descargas en la matriz `versions`
verificada	boolean	no	Un valor booleano JSON que indica si se ha verificado el paquete
packageTypes	matriz de objetos	sí	Los tipos de paquete definidos por el autor del paquete (agregados en `SearchQueryService/3.5.0`)

En nuget.org, un paquete verificado es uno que tiene un id. de paquete que se corresponde con un prefijo de id. reservado y que pertenece a uno de los propietarios del prefijo reservado. Para más información, consulta la documentación sobre la reserva de prefijos de id.

Los metadatos que contiene el objeto del resultado de búsqueda se toman de la última versión del paquete. Cada elemento de la matriz versions es un objeto JSON que consta de las siguientes propiedades:

Nombre	Type	Obligatorio	Notas
@id	string	sí	Dirección URL absoluta de la hoja de registro asociada
version	string	sí	Cadena de versión completa de SemVer 2.0.0 del paquete (podría contener metadatos de generación)
Descargas	integer	sí	Número de descargas para esta versión de paquete específica

La matriz packageTypes siempre constará de al menos un elemento (1). El tipo de paquete para un id. de paquete determinado se considera que se corresponde con los tipos de paquete definidos por la última versión del paquete con respecto a los demás parámetros de búsqueda. Cada elemento de la matriz packageTypes es un objeto JSON que consta de las siguientes propiedades:

Nombre	Type	Obligatorio	Notas
nombre	string	sí	Nombre del tipo de paquete.

Solicitud de ejemplo

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

Asegúrate de capturar la dirección URL base (https://search-sample.nuget.org/query 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": 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"
        }
      ]
    }
  ]
}

Compartir a través de