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:
| 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 | |
| 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 |
|---|---|---|---|
| name | string | sí | Nombre del tipo de paquete. |
Solicitud de muestra
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"
}
]
}
]
}
Comentaris
Properament: al llarg del 2024 eliminarem gradualment GitHub Issues com a mecanisme de retroalimentació del contingut i el substituirem per un nou sistema de retroalimentació. Per obtenir més informació, consulteu: https://aka.ms/ContentUserFeedback.
Envieu i consulteu els comentaris de