Usa el Explorador de API

En esta guía, se describe cómo usar el Explorador de API para probar los métodos de la API de Cloud Monitoring. El Explorador de API es un widget adjunto a la página de referencia de la API de REST de un método. Aparece como un panel con el título Try this API (Prueba esta API). En la siguiente captura de pantalla, se muestra el panel como aparece para un método con solo un parámetro, name (nombre):

El Explorador de API es una excelente manera de probar los métodos en la API de Monitoring sin tener que escribir ningún código. El widget presenta un formulario que muestra los parámetros para cada método. Completa el formulario, haz clic en el botón Execute (Ejecutar) y observa los resultados.

También puedes ocultar el widget si haces clic en el botón o expandir el widget a pantalla completa con el botón .

Nota: Si expandes el Explorador de API a pantalla completa, puedes ver la solicitud como un comando cURL, como una solicitud HTTP y en JavaScript.

Botones ¡Pruébalo!

En la documentación, es posible que veas los botones Pruébalo, como los siguientes:

Pruébalo

Cuando haces clic en el botón, se abre el Explorador de API en la página de referencia del método. Por lo general, se propagan algunos parámetros adecuados para el ejemplo. Sin embargo, es posible que debas editar algunos de los parámetros para que coincidan con tu proyecto, como el valor de [PROJECT_ID].

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

Accede al Explorador de API

El Explorador de API se adjunta a la página de referencia para cada método de API de 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 se marcan con una barra roja hasta que se completan. Puedes realizar una solicitud después de proporcionar valores para todos los argumentos obligatorios.

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

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

1. Haz clic en ¡Probar!
2. En el parámetro nombre, ingresa el ID del proyecto con el formato projects/[PROJECT_ID]. Asegúrate de reemplazar [PROJECT_ID] por el ID de tu proyecto.
3. Haz clic en Ejecutar. Para ejecutar el comando, el Explorador de API requiere acceso a tu cuenta. Cuando se te solicite, selecciona una cuenta y haz clic en Permitir. El acceso es por un período limitado y está restringido al método de API que ejecutas.

Los resultados de la invocación del método aparecen en un cuadro que tiene un encabezado verde o rojo. Cuando la solicitud se realiza de forma correcta, el cuadro tiene un encabezado verde con el código de estado HTTP 200. Los resultados de la invocación están en el cuadro:

Cuando el encabezado es rojo, 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 Cómo solucionar problemas.

Nota: Después de configurar el Explorador de API y hacer clic en Ejecutar, la URL de la página cambia. Puedes agregar la URL actualizada a favoritos. Cuando desees volver a ejecutar el método, haz clic en el marcador para abrir la página con el formulario ya propagado con tus selecciones anteriores.

Proporcionar parámetros adicionales

La lista de parámetros que ves depende del método al que se adjunta el widget del Explorador de API. Por ejemplo, el método metricDescriptors.list tiene más que el parámetro nombre, pero nombre es el único parámetro obligatorio.

Cuando proporcionas solo el nombre del proyecto, obtienes todos los descriptores de métricas disponibles en tu proyecto y hay muchos de ellos. Para restringir la recuperación a un conjunto más pequeño, usa el parámetro filtro.

Por ejemplo, para ver una lista de solo los tipos de métricas cuyos nombres terminen con utilization, haz lo siguiente:

1. Haz clic en ¡Probar!

2. En el parámetro nombre, ingresa el ID del proyecto con el formato projects/[PROJECT_ID]. Asegúrate de reemplazar [PROJECT_ID] por el ID de tu proyecto.

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

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

Parámetros estándar

De forma predeterminada, el conjunto de parámetros que muestra el Explorador de API corresponde a los parámetros del método asociado. Sin embargo, el widget del Explorador de API también tiene un conjunto de parámetros adicionales que no forman parte del método. 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 el parámetro campos. Este parámetro te permite seleccionar los campos en el resultado que se muestra y que deseas ver.

Por ejemplo, enumerar los descriptores de las métricas que terminan en utilization aún muestra muchos resultados. Si solo deseas conocer el nombre del tipo de métrica y su descripción, puedes especificar esta restricción mediante el parámetro campos.

Para ver el resultado de configurar el parámetro campos, haz lo siguiente:

1. Haz clic en ¡Probar!

2. En el parámetro nombre, ingresa el ID del proyecto con el formato projects/[PROJECT_ID]. Asegúrate de reemplazar [PROJECT_ID] por el ID de tu proyecto.

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

4. Haz clic en Mostrar parámetros estándar y verifica que el parámetro campos tenga el valor metricDescriptors.type,metricDescriptors.description.

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

Cuando se ejecuta esta solicitud, solo se muestra el type (nombre corto) de cada métrica y su description.

Solución de problemas

En esta sección, se describen problemas comunes cuando se usa el Explorador de API.

Para obtener más información sobre el uso de la API de Cloud Monitoring, consulta Soluciona problemas de la API de 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 el Explorador de APIs, pero el Explorador de APIs muestra un mensaje de error.

Lo que debes hacer: Asegúrate de que las strings estén en una sola línea.

"query": "fetch gce_instance::compute.googleapis.com/instance/disk/read_bytes_count | within 5m"

No: Copia y pega caracteres de continuación de línea o de línea nueva.

Por ejemplo, si agregas lo siguiente al método timeSeries.query, el Explorador de APIs mostrará el mensaje de error Select an underlined section to see more details:

"query": "fetch gce_instance::compute.googleapis.com/instance/disk/read_bytes_count
          | within 5m"

Identificador de proyecto no válido

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

Para resolver esta condición, verifica que el texto [PROJECT_ID] se haya reemplazado por el ID de tu proyecto.

Valores de formulario no válidos

Si tu solicitud a la API falla o devuelve valores inesperados, verifica todos los parámetros del formulario.

Los parámetros del Explorador de API requieren un formato específico. Los errores de formato pueden generar errores o ser aceptados, pero se tratan como errores de ortografía en el método de la API:

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

• No uses barras inversas, excepto cuando necesites proteger una substring.

  Por ejemplo, el siguiente es un ejemplo para un método de API en el que ingresas el contenido como JSON, en lugar de completar parámetros de formularios individuales. Debido a que el valor de filter es una string, la substring, k8s_cluster, está protegida por barras invertidas:

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

• Strings de comillas que aparecen dentro de los filtros. Usa comillas dobles (") y no apóstrofos ('). Para ver un ejemplo, consulta Proporciona parámetros adicionales.

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

Se muestran demasiados datos

Para limitar la cantidad de resultados que se muestran, en el parámetro pageSize, ingresa un valor, como 2. El parámetro pageSize define la cantidad máxima de resultados que se muestran y está disponible para la mayoría de los métodos de API.

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

Authentication

Hay una sección Credenciales en la página Explorador de API. Te recomendamos que no modifiques los valores predeterminados de estos campos. El mecanismo de autenticación predeterminado es Google OAuth 2.0.

A fin de averiguar qué alcances de la API son necesarios para el método, haz clic en Mostrar permisos. De forma predeterminada, se otorgan todos los permisos necesarios.

Para obtener más información sobre estos conceptos, consulta Controla el acceso con Identity and Access Management.