Utiliser l'API – Insights

Cette page explique comment afficher et gérer des Insights dans l'outil de recommandation à l'aide des commandes gcloud ou de l'API REST.

Voici les interactions types avec les insights effectuées à l'aide de l'API Recommender :

Répertorier les insights actuellement disponibles pour un type d'insight spécifique
Marquer l'insight que vous envisagez d'utiliser comme accepté.

Pour en savoir plus sur la modification de l'état des insights dans Google Cloud Console, consultez la documentation du Centre de recommandations ou du type de ressources approprié.

Définir le projet par défaut

Définissez le projet par défaut si vous ne l'avez pas déjà fait :

gcloud config set project PROJECT_ID

où PROJECT_ID correspond à l'ID de votre projet.

Définir des variables d'environnement

Définissez les variables d'environnement pour les interactions avec l'outil de recommandation :

PROJECT=TARGET_PROJECT_ID
LOCATION=LOCATION_ID
INSIGHT_TYPE=INSIGHT_TYPE_ID

où :

TARGET_PROJECT_ID correspond au projet pour lequel vous souhaitez répertorier les insights. Il peut s'agir d'un projet différent de votre projet actuel.
- Pour les commandes gcloud, vous devez utiliser l'ID de projet.
- Pour les requêtes API, vous pouvez utiliser le numéro ou l'ID du projet. Il est recommandé d'utiliser le numéro de projet.
Le numéro de projet est renvoyé dans les réponses des commandes gcloud et de l'API.
LOCATION_ID correspond à l'emplacement Google Cloud dans lequel se trouvent les ressources associées aux insights (par exemple, global ou us-central1-a).
INSIGHT_TYPE_ID correspond à l'ID de type d'insight complet (par exemple, google.iam.policy.Insight).

Consultez la page Types d'insights pour obtenir un tableau de liens vers des informations sur chaque type d'insights, y compris les emplacements acceptés et les ID de types d'insights.

Définir des autorisations

Vous devez disposer des autorisations nécessaires pour accéder aux insights du projet cible.

Pour les demandeurs qui spécifient un projet de facturation dans leur requête : le projet inclus dans la requête doit être en règle, et l'utilisateur doit détenir un rôle contenant l'autorisation serviceusage.services.use pour le projet. Le rôle Consommateur Service Usage comprend l'autorisation requise.
Chaque type d'insight nécessite des autorisations spécifiques. Consultez la page Types d'insights pour obtenir un tableau de liens vers des informations sur chaque type d'insights, y compris les autorisations requises.

Répertorier les insights

Pour répertorier les insights dans le projet cible, procédez comme suit :

gcloud

Saisissez les chaînes suivantes :

gcloud recommender insights list \
    --project=${PROJECT} \
    --location=${LOCATION} \
    --insight-type=${INSIGHT_TYPE} \
    --format=FORMAT

où FORMAT correspond au format de sortie gcloud accepté (par exemple, json).

Exemple :

gcloud recommender insights list \
    --project=example-project \
    --location=global \
    --insight-type=google.iam.policy.Insight \
    --format=json

REST

Saisissez les chaînes suivantes :

curl \
    -H "Authorization: Bearer $(gcloud auth print-access-token)"  \
    -H "x-goog-user-project: ${PROJECT}" \
    "https://recommender.googleapis.com/v1/projects/${PROJECT}/locations/${LOCATION}/insightTypes/${INSIGHT_TYPE}/insights"

Exemple :

curl \
    -H "Authorization: Bearer $(gcloud auth print-access-token)"  \
    -H "x-goog-user-project: example-project" \
    "https://recommender.googleapis.com/v1/projects/example-project/locations/us-central1-a/insightTypes/google.iam.policy.Insight/insights"

Cette opération génère les insights actuels sur la stratégie IAM dans le projet cible en tant que liste d'entités Insight au format spécifié.

Le résultat ressemble à ce qui suit :

[
  {
    "category": "SECURITY",
    "content": {
      "condition": {
        "description": "",
        "expression": "",
        "location": "",
        "title": ""
      },
      "exercisedPermissions": [],
      "inferredPermissions": [],
      "member": "user:my-service-account@example-project.iam.gserviceaccount.com",
      "role": "roles/iam.securityReviewer"
    },
    "description": "0 permission checks were authorized by this policy binding tuple.",
    "etag": "\"45f4e2c63f6952e8\"",
    "insightSubtype": "PERMISSIONS_USAGE",
    "lastRefreshTime": "2020-03-06T08:00:00Z",
    "name": "projects/32428390823/locations/global/insightTypes/google.iam.policy.Insight/insights/a523ff7e-ed03-4143-a3a5-5b396b99cba9",
    "observationPeriod": "7776000s",
    "stateInfo": {
      "state": "ACTIVE",
    },
    "targetResources": [
      "//cloudresourcemanager.googleapis.com/projects/32428390823"
    ],
  }
]

Notez que les insights renvoyés incluent les champs suivants :

Un champ name au format suivant :

projects/PROJECT_ID/locations/LOCATION/insightTypes/INSIGHT_TYPE_ID/insights/INSIGHT_ID

où INSIGHT_ID identifie de manière unique l'insight.

Un champ etag associé à l'état actuel de l'insight.

Lorsque vous référencez un insight à l'aide des commandes gcloud ou des appels d'API REST ultérieurs, vous référencez à la fois l'ID d'insight et l'eTag. Cela garantit que les opérations ne sont effectuées que si cet insight n'a pas été modifié depuis sa dernière extraction.

Marquer un insight comme accepté

Vous pouvez marquer un insight comme accepté pour indiquer que vous avez effectué ou que vous souhaitez effectuer une action sur une ressource associée en fonction des informations fournies dans cet insight. Lorsqu'un insight est accepté, votre nom d'utilisateur est attribué en tant qu'acteur de cet insight. Dans ce cas, l'outil de recommandation ne met pas à jour l'insight avec du contenu plus récent.

Pour marquer un aperçu comme accepté, procédez comme suit :

gcloud

Saisissez ce qui suit :

gcloud recommender insights mark-accepted \
    INSIGHT_ID \
    --project=${PROJECT} \
    --location=${LOCATION} \
    --insight-type=${INSIGHT_TYPE} \
    --etag=etag \
    --state-metadata=STATE_METADATA
    --format=FORMAT

où :

INSIGHT_ID correspond à l'ID d'un insight récupéré lors d'un précédent appel pour répertorier les insights.
etag correspond à l'ETag renvoyé qui représente l'état de l'insight.
STATE_METADATA correspond à une métadonnée facultative concernant l'opération. Spécifiez les métadonnées sous forme de liste de paires KEY=VALUE séparées par une virgule.

Exemple :

gcloud recommender insights mark-accepted \
    a523ff7e-ed03-4143-a3a5-5b396b99cba9 \
    --project=example-project \
    --location=global \
    --insight-type=google.iam.policy.Insight \
    --etag='"280b34810bba8a1a"' \
    --state-metadata=priority=high,tracking_number=12345
    --format=json

REST

Saisissez les chaînes suivantes :

curl -X POST \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)"  \
    -H "x-goog-user-project: ${PROJECT}" \
    --data-binary @- \
    https://recommender.googleapis.com/v1/projects/${PROJECT}/locations/${LOCATION}/insightTypes/${INSIGHT_TYPE}/insights/INSIGHT_ID:markAccepted \
<< EOM
{
  "etag": "etag",
  "stateMetadata": STATE_METADATA
}
EOM

où :

INSIGHT_ID correspond à l'ID d'un insight récupéré lors d'un précédent appel pour répertorier les insights.
etag correspond à l'ETag renvoyé qui représente l'état de l'insight.
STATE_METADATA est un champ facultatif contenant des métadonnées supplémentaires sur l'opération. Spécifiez les métadonnées sous forme de paires key:value.

Exemple :

curl -X POST \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)"  \
    -H "x-goog-user-project: example-project" \
    --data-binary @- \
    https://recommender.googleapis.com/v1/projects/example-project/locations/global/insightTypes/google.iam.policy.Insight/insights/a523ff7e-ed03-4143-a3a5-5b396b99cba9:markAccepted \
<< EOM
{
  "etag": "\"280b34810bba8a1a\""
  "stateMetadata": {
    "priority" : "high",
    "tracking_number": "12345"
  }
}
EOM

Cette opération renvoie l'entité Insight au format spécifié une fois l'opération terminée.

Le résultat ressemble à ce qui suit :

{
  "category": "SECURITY",
  "content": { ...  },
  "description": "0 permission checks were authorized by this policy binding tuple.",
  "etag": "\"356ae51165729f38\"",
  "insightSubtype": "PERMISSIONS_USAGE",
  "lastModifiedUser": "admin123@example-project.iam.gserviceaccount.com",
  "lastRefreshTime": "2020-03-06T08:00:00Z",
  "name": "projects/32428390823/locations/global/insightTypes/google.iam.policy.Insight/insights/a523ff7e-ed03-4143-a3a5-5b396b99cba9",
  "observationPeriod": "7776000s",
  "stateInfo": {
    "state": "ACCEPTED",
    "stateMetadata": {
      "priority" : "high",
      "tracking_number": "12345"
    }
  },
  "targetResources": [
    "//cloudresourcemanager.googleapis.com/projects/32428390823"
  ],
  "userLastUpdateTime": "2020-03-31T20:57:50.509855Z"
}

Notez que la valeur du champ state est remplacée par ACCEPTED.