Buscar

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:

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

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.

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:

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:

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:

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:

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