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
.- Per i comandi
LOCATION_ID è la località di Google Cloud in cui si trovano le risorse associate agli insight (ad esempio
global
ous-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 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 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
.