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.

Remarque : Certains outils de recommandation ne permettent pas d'utiliser l'API REST ou gcloud CLI pour afficher et gérer les recommandations et les insights. Pour en savoir plus sur les outils de recommandation et les clients compatibles, consultez la section Outils de recommandation.

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

• Répertorier les insights pour un projet 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.

Remarque : Si vous utilisez l'en-tête x-goog-user-project ou le paramètre de chaîne de requête userProject dans votre requête, vous devez disposer de l'autorisation serviceusage.services.use pour l'ID de projet que vous spécifiez, en plus des autorisations IAM normales requises pour effectuer la requête.

Répertorier les insights

Comme indiqué dans l'onglet gcloud Beta, vous pouvez répertorier tous les insights de votre projet sans avoir à spécifier d'emplacement ni d'outil de recommandation. Cette fonctionnalité est disponible en version bêta.

La fonctionnalité en disponibilité générale nécessite la spécification d'un projet, d'un emplacement et d'un outil de recommandation. Pour plus d'informations, consultez l'onglet gcloud.

gcloud Beta

Preview

Cette fonctionnalité est soumise aux "Conditions des offres de pré-DG" dans la section "Conditions d'utilisation générales" des Conditions spécifiques au service. Les fonctionnalités pré-DG sont disponibles "en l'état" et peuvent avoir une assistance limitée. Pour en savoir plus, consultez les descriptions des étapes de lancement.

Saisissez ce qui suit :

gcloud beta recommender insights list \
    --project=${PROJECT} \
    --format=FORMAT

où FORMAT correspond au format de sortie Google Cloud CLI accepté, tel que json.

Exemple :

gcloud beta recommender insights list \
    --project=example-project \
    --format=json

Remarque : Contrairement au résultat suivant pour les onglets gcloud et REST, qui est limité aux insights pour un emplacement et l'outil de recommandation, la sortie inclut tous les insights du projet.

gcloud

Saisissez ce qui suit :

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).

Par exemple :

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

REST

Saisissez ce qui suit :

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"

Par 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:[e-mail]",
      "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 insight 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.

Par 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 ce qui suit :

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.

Par 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": "[e-mail]",
  "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.