Crea una investigación de Cloud Assist

En esta página, se muestra cómo crear y revisar investigaciones de Gemini Cloud Assist.

Antes de comenzar

  1. Verifica que tu proyecto tenga habilitadas las siguientes APIs:

    • cloudaicompanion.googleapis.com
    • cloudasset.googleapis.com
    • cloudresourcemanager.googleapis.com
    • geminicloudassist.googleapis.com
    • (Recomendado) logging.googleapis.com
    • (Recomendado) monitoring.googelapis.com

    Consulta Cómo habilitar e inhabilitar servicios para obtener instrucciones sobre cómo habilitar las APIs.

  2. Para obtener los permisos necesarios para crear una investigación, pídele a tu administrador que te otorgue el rol de IAM Creador de investigaciones (roles/geminicloudassist.investigationCreator) en el proyecto.

    Este rol predefinido contiene el permiso necesario para crear una investigación en tu proyecto. Cuando creas una investigación, se te otorga el rol de IAM de Propietario de la investigación (roles/geminicloudassist.investigationOwner) en esa investigación, lo que te permite revisar los resultados.

  3. Tener acceso al producto que se investiga

    Cuando realizas una investigación, Gemini Cloud Assist usa tus credenciales para acceder a las APIs y la información. Esto significa que el acceso de la investigación se limita al acceso que tienes.

  4. Si planeas realizar una investigación sobre una aplicación, esta debe estar contenida en una carpeta habilitada para aplicaciones.

Cómo crear una investigación

Console

  1. Para crear una investigación nueva, haz clic en el botón Investigar asociado a tu punto de entrada. Un punto de entrada típico para crear una investigación es la página Investigaciones de Cloud Assist.

    Ir a Investigaciones de Cloud Assist

  2. (Opcional) Ingresa un nombre para tu investigación.

    El nombre que elijas identificará esta investigación en tu historial de investigaciones. Si omites este paso, se generará automáticamente un nombre para la investigación.

  3. Describe el problema que tienes.

    Puedes copiar y pegar el mensaje de error exacto que recibiste, usar lenguaje natural para explicar el problema que tienes o incluir ambas opciones.

  4. Selecciona la Fecha y hora de inicio del problema que estás investigando.

  5. (Opcional) Selecciona la Hora de finalización del problema que estás investigando.

  6. Si tu punto de entrada admite investigaciones de aplicaciones, usa el campo Aplicación para elegir una aplicación que se investigará.

    • En el caso de los puntos de entrada que no admiten investigaciones de aplicaciones, tu proyecto actual aparece como el proyecto objetivo y no se puede cambiar.

  7. (Opcional) Haz clic en + Agregar recurso para seleccionar los recursos afectados por el problema que estás experimentando.

    Puedes agregar recursos con el selector de recursos o ingresarlos manualmente. Cuando ingreses recursos de forma manual, debes consultar la documentación de referencia del recurso para asegurarte de usar el formato correcto.

    No puedes continuar con una investigación si incluyes alguno de los siguientes elementos:

    • Son los recursos que se encuentran en un proyecto o una aplicación que está fuera del alcance de la investigación.
    • Recursos que no se admiten
    • Son los recursos que no se reconocen.

  8. Haz clic en Crear para comenzar la investigación.

La investigación puede tardar varios minutos en completarse. Para comprobar el estado de la investigación, haz clic en el botón Notificaciones ().

API

  1. Crea un archivo JSON que contenga la siguiente información:

    {
"title": "INVESTIGATION_NAME",
"observations": {
  "user.project": {
    "id": "user.project",
    "observationType": "OBSERVATION_TYPE_STRUCTURED_INPUT",
    "observerType": "OBSERVER_TYPE_USER",
    "text": "PROJECT_NAME"
  },
  "user.input.text": {
    "id": "user.input.text",
    "observationType": "OBSERVATION_TYPE_TEXT_DESCRIPTION",
    "observerType": "OBSERVER_TYPE_USER",
    "timeIntervals": [
      {
        "startTime": "ISSUE_START_TIME"
      }
    ],
    "text": "ISSUE_DESCRIPTION",
    "relevantResources": [
      "AFFECTED_RESOURCE"
    ],
  },
}

    Reemplaza lo siguiente:

    • INVESTIGATION_NAME: Ingresa un nombre para la investigación. Por ejemplo, Missing Cloud Storage bucket.

    • PROJECT_NAME: Ingresa el nombre del proyecto en el que se creará la investigación. Por ejemplo, my-project

    • ISSUE_START_TIME: Ingresa la fecha y la hora en que comenzó el problema que estás investigando. Por ejemplo, 2025-07-08T17:23:00Z

    • ISSUE_DESCRIPTION: Ingresa una descripción del problema que tienes. Puedes incluir el mensaje de error exacto que recibiste, usar lenguaje natural para explicar el problema que tienes o incluir ambos.

    • AFFECTED_RESOURCE: Ingresa el nombre del recurso involucrado en el problema que tienes. Por ejemplo, //storage.googleapis.com/my-bucket Para asegurarte de usar el formato correcto para un recurso, debes consultar la documentación de referencia del recurso.

    Para obtener una representación completa de un recurso de investigación, consulta la especificación del recurso.

  2. Obtén un token de acceso:

    TOKEN=$(gcloud auth print-access-token)

  3. Usa el método investigations.create para crear la investigación:

    curl -X POST --data-binary @JSON_FILE_NAME \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  "https://geminicloudassist.googleapis.com/v1alpha/projects/PROJECT_NAME/locations/global/investigations"

    Reemplaza lo siguiente:

    • JSON_FILE_NAME: Ingresa la ruta de acceso al archivo JSON que creaste anteriormente. Por ejemplo, Desktop/my-investigation.json

    • PROJECT_NAME: Ingresa el mismo nombre del proyecto que incluiste en la observación user.project.

  4. En la respuesta, copia el valor del parámetro revision.

  5. Usa el método investigations.revisions.run para ejecutar la investigación:

    curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  "https://geminicloudassist.googleapis.com/v1alpha/projects/REVISION_RESOURCE:run"

    Reemplaza REVISION_RESOURCE por el valor que copiaste del parámetro revision.

La investigación puede tardar varios minutos en completarse. Para verificar el estado de la investigación, copia el valor del parámetro name que se devolvió en la respuesta investigations.revisions.run y usa ese valor en el parámetro name de una solicitud operations.get.

Revisa una investigación

Una vez que se complete la investigación, podrás ver sus detalles desde el punto de entrada en el que la iniciaste o desde el historial de investigaciones de tu proyecto.

Una investigación contiene las siguientes secciones:

  1. El problema

    En esta sección, se incluye la información de entrada que se usó para generar los resultados de la investigación, como la descripción del problema, las marcas de tiempo y las listas de recursos pertinentes. Existen tres tipos de listas de recursos que se pueden asociar con la investigación:

    • Recursos proporcionados por el usuario: Son los recursos que proporciona el usuario o que se recuperan del error inicial.
    • Recursos descubiertos: Son los recursos adicionales que Gemini considera mientras realiza la investigación.
    • Recursos pertinentes: Son los recursos que Gemini considera pertinentes para la hipótesis de la causa raíz, que siempre incluye los recursos proporcionados por el usuario.

  2. Las observaciones

    En esta sección, se incluyen las observaciones que generó la investigación. Las observaciones se basan en las revisiones de los manuales de procedimientos, los registros, los mensajes de interrupción y las alertas. A partir de estas observaciones, Gemini genera hipótesis sobre la causa raíz del problema que estás investigando.

  3. Las hipótesis

    En esta sección, se incluyen una o más hipótesis basadas en los datos recopilados durante la investigación y las observaciones realizadas. Una hipótesis contiene una visión general de cuál podría ser el problema y correcciones recomendadas, que son acciones que te ayudan a corregir el problema o que te brindan pasos adicionales para solucionar el problema y confirmar o refutar la hipótesis.

Puedes revisar la entrada de tu investigación con el botón Editar, que te permite volver a ejecutar la investigación con información actualizada. Cuando una investigación tiene varias ejecuciones asociadas, puedes revisar los resultados de las ejecuciones anteriores con el selector desplegable Revisión.

¿Qué sigue?