Utilizza l'API - Approfondimenti

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

Nota: alcuni motori per suggerimenti non supportano l'utilizzo dell'API REST o di gcloud CLI per visualizzare e gestire i suggerimenti e gli insight. Per maggiori dettagli sui motori per suggerimenti e sui client supportati, consulta Motori per suggerimenti.

Una tipica interazione di insight con l'API Recommender è:

• Elenca gli insight per un progetto specifico
• Contrassegna un insight su cui intendi intervenire come accettato

Per informazioni sulla modifica dello stato degli insight nella console Google Cloud, consulta la documentazione per l'hub dei suggerimenti o per il tipo di insight appropriato.

Imposta il progetto predefinito

Imposta il progetto predefinito se non lo 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 con il motore per suggerimenti:

PROJECT=TARGET_PROJECT_ID
LOCATION=LOCATION_ID
INSIGHT_TYPE=INSIGHT_TYPE_ID

dove:

• TARGET_PROJECT_ID è il progetto di cui vuoi elencare 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 di progetto o l'ID progetto. Il numero di progetto è consigliato.

  Il numero del progetto viene restituito nelle risposte dei comandi API e gcloud.

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

• INSIGHT_TYPE_ID è l'ID del tipo di informazioni completo (ad esempio, google.iam.policy.Insight).

Consulta la sezione Tipi di insight per una tabella di link alle informazioni su ogni tipo di insight, incluse le località supportate e gli ID dei tipi di insight.

Imposta 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 contenente l'autorizzazione serviceusage.services.use. Il ruolo consumer utilizzo servizi contiene l'autorizzazione richiesta.
• Ogni tipo di insight richiede autorizzazioni specifiche. Consulta Tipi di insight per una tabella di link alle informazioni su ciascun tipo di insight, incluse le autorizzazioni richieste.

Nota: se utilizzi l'intestazione x-goog-user-project o il userProject parametro della stringa di query, devi disporre dell'autorizzazione serviceusage.services.use per l'ID progetto specificato, oltre alle normali autorizzazioni IAM necessarie per effettuare la richiesta.

Insight elenco

Come mostrato nella scheda gcloud Beta, puoi elencare tutti gli insight del progetto senza dover specificare una località e un motore per suggerimenti. Questa funzionalità è in anteprima.

La funzionalità GA richiede di specificare un progetto, una località e un motore per suggerimenti. Per maggiori dettagli, consulta la scheda gcloud.

gcloud beta

Anteprima

Questa funzionalità è soggetta ai "Termini delle Offerte pre-GA" nella sezione Termini generali del servizio dei Termini specifici dei servizi. Le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per saperne di più, consulta le descrizioni della fase di lancio.

Inserisci quanto segue:

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

dove FORMAT è un formato di output Google Cloud CLIsupportato, ad esempio json.

Ad esempio:

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

Nota: a differenza del seguente output per le schede gcloud e REST, che è limitato agli insight per una località e un motore per suggerimenti, l'output includerà tutti gli insight relativi al progetto.

gcloud

Inserisci quanto segue:

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

dove FORMAT è un gcloud formato 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 attuali 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:[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"
    ],
  }
]

Tieni presente che gli insight 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'insight

• Un campo etag associato allo stato degli insight correnti.

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

Contrassegnare un insight come accettato

Puoi contrassegnare un insight come accettato per indicare che intendi intraprendere o hai eseguito un'azione su una risorsa associata in base alle informazioni fornite nell'insight. Quando un insight viene accettato, il tuo nome utente viene assegnato come attore dell'insight e il motore per suggerimenti non lo aggiorna con i 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'insight
• STATE_METADATA è un metadato facoltativo relativo all'operazione. Specifica i metadati come elenco separato da virgole di coppie KEY=VALUE.

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'insight
• STATE_METADATA è un campo facoltativo con metadati aggiuntivi sull'operazione. Specifica i metadati sotto forma di coppie di 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'esecuzione dell'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": "[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"
}

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