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 è:

Approfondimenti sull'elenco attualmente disponibili per un tipo di approfondimento specifico
Contrassegna come desiderato un approfondimento che vuoi accettato

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.