Utilizzo dell'API - Approfondimenti

Questa pagina spiega come visualizzare e gestire gli approfondimenti nel motore per suggerimenti utilizzando i comandi gcloud o l'API REST.

Un'interazione statistica tipica con l'API motore per suggerimenti è:

Per informazioni sulla modifica dello stato degli insight nella Google Cloud Console, consulta la documentazione dell'hub dei suggerimenti o del tipo di insight appropriato.

Imposta il progetto predefinito

Imposta il progetto predefinito se non l'hai già fatto:

gcloud config set project PROJECT_ID

dove PROJECT_ID è l'ID del tuo progetto.

Imposta le variabili di ambiente

Imposta le variabili di ambiente per le interazioni del motore per suggerimenti:

PROJECT=TARGET_PROJECT_ID
LOCATION=LOCATION_ID
INSIGHT_TYPE=INSIGHT_TYPE_ID

dove:

  • TARGET_PROJECT_ID è il progetto di cui vuoi mostrare gli insight. Può essere un progetto diverso da quello attuale.

    • Per i comandi gcloud, devi utilizzare l'ID progetto
    • Per le richieste API, puoi utilizzare il numero o l'ID del progetto. Il numero di progetto è consigliato.

    Il numero del progetto viene restituito nelle risposte sia dall'API che dai comandi gcloud.

  • LOCATION_ID è la località di Google Cloud in cui si trovano le risorse associate agli insight (ad esempio global o us-central1-a).

  • INSIGHT_TYPE_ID è l'ID completo del tipo di approfondimento (ad es. google.iam.policy.Insight).

Consulta Tipi di approfondimenti per visualizzare una tabella di link alle informazioni su ciascun tipo di approfondimento, incluse le località supportate e gli ID dei tipi di approfondimenti.

Imposta le autorizzazioni

Devi disporre delle autorizzazioni per accedere agli insight nel progetto di destinazione.

  • Per i richiedenti che includono un progetto di fatturazione nella richiesta. Il progetto utilizzato nella richiesta deve essere in regola e l'utente deve avere un ruolo nel progetto che contiene l'autorizzazione serviceusage.services.use. Il ruolo Consumatore di servizi contiene l'autorizzazione richiesta.
  • Ogni tipo di approfondimento richiede autorizzazioni specifiche. Consulta Tipi di approfondimenti per una tabella di link alle informazioni relative a ogni tipo di approfondimento, tra cui le autorizzazioni richieste.

Elenco insight

Per elencare gli insight nel progetto di destinazione:

gcloud

Inserisci quanto segue:

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

dove FORMAT è un gcloudformato di output supportato (ad esempio json).

Ad esempio:

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

REST

Inserisci quanto segue:

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"

Ad esempio:

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"

Questa operazione restituisce gli insight sui criteri IAM correnti nel progetto di destinazione sotto forma di elenco di entità Insight nel formato specificato.

L'output è simile al seguente:

[
  {
    "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"
    ],
  }
]

Tieni presente che gli approfondimenti restituiti includono i seguenti campi:

  • Un campo name nel seguente formato:

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

    dove INSIGHT_ID identifica in modo univoco l'approfondimento

  • Un campo etag associato allo stato insight corrente.

Quando fai riferimento a un approfondimento utilizzando i comandi gcloud successivi o le chiamate API REST, fai riferimento sia all'ID insight sia all'etag, che garantisce che le operazioni vengano eseguite solo se l'approfondimento non è stato modificato dall'ultima volta che lo hai recuperato.

Contrassegna un approfondimento come accettato

Puoi contrassegnare un approfondimento come accettato per indicare che intendi intraprendere o eseguire un'azione su una risorsa associata in base alle informazioni fornite nell'approfondimento. Quando viene accettato, il tuo nome utente viene assegnato come attore di tale approfondimento e il motore per suggerimenti non aggiorna l'approfondimento con contenuti più recenti.

Per contrassegnare un approfondimento come accettato:

gcloud

Inserisci quanto segue:

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

dove:

  • INSIGHT_ID è l'ID di un approfondimento recuperato da una chiamata precedente per elencare gli insight
  • etag è l'etag restituito che rappresenta lo stato dell'approfondimento
  • STATE_METADATA è un metadati facoltativo relativo all'operazione. Specifica i metadati come elenco separato da virgole di KEY=VALUE coppie.

Ad esempio:

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

Inserisci quanto segue:

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

dove:

  • INSIGHT_ID è l'ID di un approfondimento recuperato da una chiamata precedente per elencare gli insight
  • etag è l'etag restituito che rappresenta lo stato dell'approfondimento
  • STATE_METADATA è un campo facoltativo con metadati aggiuntivi sull'operazione. Specifica i metadati come coppie key:value.

Ad esempio:

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

Questa operazione restituisce l'entità Insight nel formato specificato dopo l'operazione.

L'output è simile al seguente:

{
  "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"
}

Tieni presente che il valore del campo state è stato modificato in ACCEPTED.