Utilizzo dell'API - Approfondimenti
In questa pagina viene spiegato come visualizzare e gestire gli
approfondimenti nel motore per suggerimenti utilizzando i
comandi gcloud
o
l'API REST.
Ecco un'interazione tipica con l'API motore per suggerimenti:
- Approfondimenti sull'elenco attualmente disponibili per un tipo di approfondimento specifico
- Contrassegna come accettato un approfondimento per cui vuoi intervenire
Per informazioni sulla modifica dello stato degli insight in Google Cloud Console, consulta la documentazione relativa al Recommendation Hub o al tipo di insight appropriato.
Imposta il progetto predefinito
Imposta il progetto predefinito se non l'hai ancora 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 per il quale vuoi elencare. Può essere un progetto diverso dal progetto 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 sia dai comandi dell'API che da
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 del tipo di approfondimento completo (ad esempio
google.iam.policy.Insight
).
Consulta la sezione 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. Queste autorizzazioni variano in base al tipo di approfondimento. Consulta la pagina Tipi di insight per una tabella di link alle informazioni su ogni tipo di approfondimento, comprese le autorizzazioni richieste.
Elenco approfondimenti
Per elencare le informazioni 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 genera gli insight sui criteri IAM correnti nel progetto di destinazione come 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 insight utilizzando i comandi gcloud
successivi o le chiamate API REST, fai riferimento sia all'ID insight sia all'etichetta, per assicurare che tutte le operazioni vengano eseguite solo se l'approfondimento non è stato modificato dall'ultimo recupero.
Contrassegna un approfondimento come accettato
Puoi contrassegnare un insight come accettato per indicare che intendi intraprendere un'azione su una risorsa associata o che hai intrapreso un'azione in base alle informazioni fornite in tale insight. Quando un approfondimento viene accettato, il tuo nome utente viene assegnato come attore dell'insight e il motore per suggerimenti non lo aggiornerà 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 all'elenco di insight
- etag è l'etag restituito che rappresenta lo stato dell'approfondimento
- STATE_METADATA è un metadati facoltativo sull'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 all'elenco di 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 che è stata eseguita 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
.