Puntos de conexión de la API de REST para búsquedas

Acerca de la búsqueda

Puedes usar la API REST para buscar el elemento específico que quieras encontrar. Por ejemplo, puedes buscar un usuario o un archivo específico en el repositorio. Tómalo como el simil de realizar una búsqueda en Google. Se diseñó para ayudarte a encontrar el resultado exacto que estás buscando (o tal vez algunos de los resultados que buscas). Tal como la búsqueda en Google, a veces quieres ver algunas páginas de los resultados de búsqueda para que puedas encontrar el elemento que mejor satisfaga tus necesidades. Para satisfacer esta necesidad, la API REST de GitHub proporciona hasta 1000 resultados por búsqueda.

Puedes delimitar tu búsqueda utilizando consultas. Para más información sobre la sintaxis de las consultas de búsqueda, consulta "Puntos de conexión de la API de REST para búsquedas".

Clasificar los resultados de la búsqueda

A menos de que se proporcione algún otro tipo de opción como parámetro de consulta, los resultados se clasificarán de acuerdo a la exactitud de la coincidencia en orden descendente. Varios factores se combinan para impulsar el elemento más relevante hasta arriba de la lista de resultados.

Límite de frecuencia

La API REST tiene un límite de frecuencia personalizado para la búsqueda. En el caso de las solicitudes autenticadas, puede realizar hasta 30 solicitudes por minuto para todos los puntos de conexión de búsqueda, excepto para el punto de conexión de "Código de búsqueda". El punto de conexión de "Código de búsqueda" requiere que se autentique y tiene un límite de 10 solicitudes por minuto. En el caso de las solicitudes sin autenticación, el límite de frecuencia le permite hacer hasta 10 solicitudes por minuto.

Para obtener información sobre cómo determinar el estado actual del límite de velocidad, consulta "Límite de velocidad".

Construir una consulta de búsqueda

Cada punto de conexión de la búsqueda usa parámetros de consulta para realizar búsquedas en GitHub. Consulta los puntos de conexión individuales para obtener ejemplos que incluyen el punto de conexión y los parámetros de consulta.

Una consulta puede contener cualquier combinación de calificadores de búsqueda que sea compatible con GitHub. El formato de esta consulta de búsqueda es:

SEARCH_KEYWORD_1 SEARCH_KEYWORD_N QUALIFIER_1 QUALIFIER_N

Por ejemplo, si quiere buscar todos los repositorios que pertenecen a defunkt y contienen las palabras GitHub y Octocat en el archivo Léame, puede usar la consulta siguiente con el punto de conexión de búsqueda en repositorios:

GitHub Octocat in:readme user:defunkt

Nota: Asegúrese de usar el codificador HTML preferido de su lenguaje de programación para construir las cadenas de consulta. Por ejemplo:

// JavaScript
const queryString = 'q=' + encodeURIComponent('GitHub Octocat in:readme user:defunkt');

Consulta "Buscar en GitHub" para obtener una lista completa de los calificadores disponibles, su formato y un ejemplo de cómo usarlos. Para obtener información sobre cómo usar los operadores para comparar cantidades y fechas específicas, o para que excluyan resultados, consulta "Entender la sintaxis de búsqueda".

Limitaciones sobre la longitud de la consulta

No puedes usar consultas que:

• sean mayores a 256 caracteres (sin incluir los operadores o calificativos).
• Tienen más de cinco operadores AND, OR o NOT.

Estas consultas de búsqueda devolverán un mensaje de error de "Validation failed".

Límites del ámbito de búsqueda

A fin de mantener la velocidad de la API REST para todos los usuarios, se limita el número de repositorios en los que se buscará una consulta. La API REST encontrará hasta 4000 repositorios que coincidan con los filtros y devolverá resultados de esos repositorios.

Tiempos excedidos y resultados incompletos

Para que la API REST sea rápida para todos, se limita el tiempo que se puede ejecutar una consulta individual. Para las consultas que superan el límite de tiempo, la API devuelve las coincidencias que se han encontrado antes de que se cumpla el tiempo de espera y la respuesta tiene la propiedad incomplete_results establecida en true.

Llegar a una interrupción no necesariamente significa que los resultados de búsqueda estén incompletos. Puede que se hayan encontrado más resultados, pero también puede que no.

Errores de acceso o resultados de búsqueda faltantes

Necesita autenticarse correctamente y tener acceso a los repositorios en sus consultas de búsqueda, de otro modo, verá un error 422 Unprocessable Entry con el mensaje "Validation Failed". Por ejemplo, se producirá un error en la búsqueda si su consulta incluye calificadores repo:, user: o org: que solicitan recursos a los cuales no tiene acceso cuando inicia sesión en GitHub.

Cuando su consulta de búsqueda solicita recursos múltiples, la respuesta solo contendrá aquellos a los que tenga acceso y no proporcionará un mensaje de error que liste los recursos que no se han devuelto.

Por ejemplo, si la consulta de búsqueda busca en los repositorios octocat/test y codertocat/test, pero solo tiene acceso a octocat/test, la respuesta mostrará los resultados de la búsqueda para octocat/test y no mostrará nada para codertocat/test. Este comportamiento simula cómo funciona la búsqueda en GitHub.

Metadatos en el texto coincidente

En GitHub, puedes usar el contexto que proporcionan los fragmentos de código y los puntos destacados en los resultados de búsqueda. Los puntos de conexión de búsqueda devuelven metadatos adicionales que te permiten resaltar los términos de búsqueda coincidentes cuando se muestran los resultados de la búsqueda.

Las solicitudes pueden decidir recibir esos fragmentos de texto en la respuesta, y cada fragmento se acompaña de intervalos numéricos que identifican la ubicación exacta de cada término de búsqueda coincidente.

Para obtener estos metadatos en los resultados de búsqueda, especifique el tipo de medio text-match en el encabezado Accept.

application/vnd.github.text-match+json

Al proporcionar el tipo de medio text-match, recibirá una clave extra en la carga de JSON llamada text_matches, la cual proporciona información sobre la posición de sus términos de búsqueda dentro del texto y la propiedad (property) que incluye dicho término de búsqueda. Dentro de la matriz text_matches, cada objeto incluye los siguientes atributos:

Nombre	Descripción
object_url	La URL del recurso que contiene una propiedad de secuencia que empata con uno de los términos de búsqueda.
object_type	El nombre del tipo de recurso que existe en el atributo object_url especificado.
property	El nombre de la propiedad del recurso que existe en object_url. Esa propiedad es una secuencia que empata con uno de los términos de la búsqueda. (En el código JSON que se devuelve de object_url, el contenido completo del objeto fragment se encontrará en la propiedad con este nombre).
fragment	Un subconjunto del valor de property. Este es el fragmento de texto que empata con uno o más de los términos de búsqueda.
matches	Una matriz de uno o más términos de búsqueda presentes en el objeto fragment. Los índices (es decir, "intervalos") son relativos al fragmento. (No son relativos al contenido completo del objeto property).

Ejemplo

Con un comando curl y el ejemplo de búsqueda de incidencias anterior, nuestra solicitud de API tendría este aspecto:

curl -H 'Accept: application/vnd.github.text-match+json' \
'https://api.github.com/search/issues?q=windows+label:bug \
+language:python+state:open&sort=created&order=asc'

La respuesta incluirá una matriz text_matches para cada resultado de búsqueda. En el código JSON siguiente, tenemos dos objetos en la matriz text_matches.

La primera coincidencia de texto se produjo en la propiedad body de la incidencia. Aquí vemos un fragmento de texto del cuerpo del informe de problemas. El término de búsqueda (windows) aparece dos veces en ese fragmento, y tenemos los índices de cada aparición.

La segunda coincidencia de texto se produjo en la propiedad body de uno de los comentarios de la incidencia. Tenemos la URL para el comentario del informe de problemas. Y, por supuesto, vemos un fragmento de texto del cuerpo del comentario. El término de búsqueda (windows) aparece una vez en ese fragmento.

{
  "text_matches": [
    {
      "object_url": "https://api.github.com/repositories/215335/issues/132",
      "object_type": "Issue",
      "property": "body",
      "fragment": "comprehensive windows font I know of).\n\nIf we can find a commonly
      distributed windows font that supports them then no problem (we can use html
      font tags) but otherwise the '(21)' style is probably better.\n",
      "matches": [
        {
          "text": "windows",
          "indices": [
            14,
            21
          ]
        },
        {
          "text": "windows",
          "indices": [
            78,
            85
          ]
        }
      ]
    },
    {
      "object_url": "https://api.github.com/repositories/215335/issues/comments/25688",
      "object_type": "IssueComment",
      "property": "body",
      "fragment": " right after that are a bit broken IMHO :). I suppose we could
      have some hack that maxes out at whatever the font does...\n\nI'll check
      what the state of play is on Windows.\n",
      "matches": [
        {
          "text": "Windows",
          "indices": [
            163,
            170
          ]
        }
      ]
    }
  ]
}