Usar el Explorador de APIs

En esta guía se describe cómo usar el Explorador de APIs para probar los métodos de la API de Cloud Monitoring. Explorador de APIs es un widget adjunto a la página de referencia de la API REST de un método. Se muestra como un panel con el título Probar esta API. En la siguiente captura de pantalla se muestra el panel tal como aparece en un método con un solo parámetro, name:

El Explorador de APIs es una forma excelente de probar métodos de la API Cloud Monitoring sin tener que escribir código. El widget muestra un formulario con los parámetros de cada método. Rellena el formulario, haz clic en el botón Ejecutar y consulta los resultados.

También puedes ocultar el widget haciendo clic en el botón o ampliarlo a pantalla completa haciendo clic en el botón .

Nota: Si amplías Explorador de APIs a pantalla completa, podrás ver la solicitud como un comando curl, como una solicitud HTTP y en JavaScript.

Botones Probar

En la documentación, puede que vea botones Pruébalo como el siguiente:

Pruébalo

Cuando haces clic en el botón, se abre el Explorador de APIs en la página de referencia del método. Normalmente, se rellenan algunos parámetros adecuados para el ejemplo, pero es posible que tengas que editar algunos de ellos para que coincidan con tu proyecto, como el valor de [PROJECT_ID].

Para obtener información sobre cómo evitar y corregir errores, consulta la sección Solución de problemas.

Acceder al Explorador de APIs

El Explorador de APIs se adjunta a la página de referencia de cada método de la API REST. Para encontrar el widget, consulta la página de referencia de un método. Por ejemplo, consulta metricDescriptors.list.

Ejecutar una solicitud

La mayoría de los métodos tienen algunos parámetros obligatorios y otros opcionales. Los obligatorios están marcados con una barra roja hasta que se rellenan. Puedes ejecutar una solicitud después de proporcionar valores para todos los argumentos obligatorios.

El método metricDescriptors.list devuelve descriptores de todos los tipos de métricas disponibles en un proyecto. El único parámetro obligatorio es name.

Para ejecutar el método metricDescriptors.list, haz lo siguiente:

1. Haz clic en Probar.
2. En el parámetro name, introduce el ID de tu proyecto con el formato projects/[PROJECT_ID]. Sustituye [PROJECT_ID] por el ID de tu proyecto.
3. Haz clic en la opción para ejecutar. Para ejecutar el comando, Explorador de APIs necesita acceder a su cuenta. Cuando se te solicite, selecciona una cuenta y haz clic en Permitir. El acceso es por un periodo limitado y se restringe al método de la API que estés ejecutando.

Los resultados de la invocación del método aparecen en un cuadro con un encabezado verde o rojo. Si la solicitud se realiza correctamente, el cuadro tiene un encabezado verde con el código de estado HTTP 200. Los resultados de la invocación se muestran en el cuadro:

Si la cabecera es roja, contiene un código de error HTTP y el cuadro contiene el mensaje de error. Para obtener información sobre cómo resolver errores, consulta Solucionar problemas.

Nota: Después de configurar APIs Explorer y hacer clic en Ejecutar, la URL de la página cambia. Puedes añadir a favoritos la URL actualizada. Cuando quieras volver a ejecutar el método, haz clic en la marca para abrir la página con el formulario ya rellenado con tus selecciones anteriores.

Proporcionar parámetros adicionales

La lista de parámetros que ve depende del método al que esté adjunto el widget Explorador de APIs. Por ejemplo, el método metricDescriptors.list tiene más parámetros que name, pero name es el único obligatorio.

Si solo proporcionas el nombre del proyecto, obtendrás todos los descriptores de métricas disponibles en tu proyecto, que son muchos. Para restringir la recuperación a un conjunto más pequeño, usa el parámetro filter.

Por ejemplo, para mostrar solo los tipos de métricas cuyo nombre termine en utilization, haga lo siguiente:

1. Haz clic en Probar.

2. En el parámetro name, introduce el ID de tu proyecto con el formato projects/[PROJECT_ID]. Sustituye [PROJECT_ID] por el ID de tu proyecto.

3. Asegúrate de que el parámetro filter tenga el valor metric.type=ends_with("utilization")

4. Haz clic en Ejecutar y completa los cuadros de diálogo de autorización.

Parámetros estándar

De forma predeterminada, el conjunto de parámetros que muestra APIs Explorer corresponde a los parámetros del método asociado. Sin embargo, el widget Explorador de APIs también tiene un conjunto de parámetros adicionales que no forman parte del método en sí. Para mostrar los parámetros adicionales, haz clic en Mostrar parámetros estándar:

Para ocultar los parámetros adicionales, haz clic en Ocultar parámetros estándar.

El parámetro estándar más útil es fields. Este parámetro te permite seleccionar los campos del resultado devuelto que quieras ver.

Por ejemplo, si se enumeran los descriptores de las métricas que terminan en utilization, se siguen devolviendo muchos resultados. Si solo quiere saber el nombre del tipo de métrica y su descripción, puede especificar esta restricción mediante el parámetro fields.

Para ver el resultado de configurar el parámetro fields, haga lo siguiente:

1. Haz clic en Probar.

2. En el parámetro name, introduce el ID de tu proyecto con el formato projects/[PROJECT_ID]. Sustituye [PROJECT_ID] por el ID de tu proyecto.

3. Asegúrate de que el parámetro filter tenga el valor metric.type=ends_with("utilization")

4. Haga clic en Mostrar parámetros estándar y compruebe que el parámetro fields tiene el valor metricDescriptors.type,metricDescriptors.description.

5. Haz clic en Ejecutar y completa los cuadros de diálogo de autorización.

Al ejecutar esta solicitud, solo se devuelve el type (nombre corto) de cada métrica y su description.

Solucionar problemas

En esta sección se describen los problemas habituales que se producen al usar el Explorador de APIs.

Para obtener más información sobre cómo usar la API Cloud Monitoring, consulta el artículo Solucionar problemas de la API Cloud Monitoring.

Sintaxis de filtro no válida

Copias una expresión de varias líneas y la pegas en un campo que se muestra en APIs Explorer, pero APIs Explorer muestra un mensaje de error.

Sí: asegúrate de que las cadenas estén en una sola línea.

"query": "sum by (instance_name) (rate({\"compute.googleapis.com/instance/disk/read_bytes_count\", monitored_resource=\"gce_instance\"}[5m]))"

No copies ni pegues caracteres de continuación de línea o de salto de línea.

Por ejemplo, si añade lo siguiente al método timeSeries.query, APIs Explorer muestra el mensaje de error Select an underlined section to see more details:

"query": "sum by (instance_name) (
                   rate(
                      {\"compute.googleapis.com/instance/disk/read_bytes_count\",
                          monitored_resource=\"gce_instance\"
                     }[5m]
                  )
               )"

Identificador de proyecto no válido

Si el identificador del proyecto no es válido, la solicitud de la API falla y devuelve un error HTTP 400.

Para solucionar este problema, comprueba que el texto [PROJECT_ID] se ha sustituido por el ID de tu proyecto.

Valores de formulario no válidos

Si tu solicitud de API falla o devuelve valores inesperados, comprueba todos los parámetros del formulario.

Los parámetros de APIs Explorer requieren un formato específico. Los errores de formato pueden provocar errores o aceptarse, pero se tratarán como errores ortográficos en el método de la API:

• No uses comillas en los valores de los parámetros de ningún tipo.

• No uses barras invertidas, salvo cuando necesites proteger una subcadena.

  Por ejemplo, la siguiente muestra corresponde a un método de API en el que se introduce el contenido como JSON, en lugar de rellenar parámetros de formulario individuales. Como el valor de filter es una cadena, la subcadena k8s_cluster está protegida por barras invertidas:

    {
      "resourceNames": [...],
      "filter": "resource.type = \"k8s_cluster\""
    }

• Cadenas entre comillas que aparecen en los filtros. Usa comillas dobles (") y no apóstrofos ('). Para ver un ejemplo, consulta Proporcionar parámetros adicionales.

• No utilice la codificación de URLs en el formulario. Si un método de API requiere codificación de URL, el widget realiza la conversión cuando ejecutas el método.

Se devuelven demasiados datos

Para limitar el número de resultados devueltos, en el parámetro pageSize, introduzca un valor, como 2. El parámetro pageSize define el número máximo de resultados que se devuelven y está disponible en la mayoría de los métodos de la API.

Para seleccionar campos específicos que se van a devolver, usa el parámetro fields. Para obtener más información, consulta Parámetros estándar.

Autenticación

En la página Explorador de APIs, hay una sección Credenciales. Te recomendamos que dejes los valores predeterminados en estos campos. El mecanismo de autenticación predeterminado es Google OAuth 2.0.

Para saber qué permisos de API se necesitan para el método, haz clic en Mostrar permisos. De forma predeterminada, se conceden todos los permisos necesarios.

Para obtener más información sobre estos conceptos, consulta Controlar el acceso con Gestión de Identidades y Accesos.