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.
Una tipica interazione degli insight con l'API Recommender è:
- Elenchi di approfondimenti attualmente disponibili per un tipo di approfondimento specifico
- Contrassegna come accettato un approfondimento per il quale vuoi intraprendere un'azione
Per informazioni sulla modifica dello stato degli insight nella console Google Cloud, consulta la documentazione dell'hub dei suggerimenti o del tipo di approfondimento appropriato.
Imposta il progetto predefinito
Se non lo hai già fatto, imposta il progetto predefinito:
gcloud config set project PROJECT_ID
dove PROJECT_ID è l'ID del 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 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. È consigliato il numero di progetto.
Il numero del progetto viene restituito nelle risposte dei comandi API e
gcloud
.- Per i comandi
LOCATION_ID è la località Google Cloud in cui si trovano le risorse associate agli insight (ad esempio,
global
ous-central1-a
).INSIGHT_TYPE_ID è l'ID tipo di approfondimento completo (ad esempio
google.iam.policy.Insight
).
Consulta Tipi di insight per una tabella dei link alle informazioni su ciascun tipo di insight, inclusi 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 dei servizi contiene l'autorizzazione richiesta. - Ogni tipo di approfondimento richiede autorizzazioni specifiche. Vedi Tipi di insight per una tabella dei link alle informazioni su ciascun tipo di insight, incluse 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 formato di output gcloud
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 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 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 attuale dell'approfondimento.
Quando fai riferimento a un approfondimento utilizzando i comandi gcloud
o le chiamate API REST successive, devi fare riferimento sia all'ID insight che all'etag, il che garantisce che le operazioni vengano eseguite solo se l'insight non è stato modificato dall'ultimo recupero.
Contrassegna un approfondimento come accettato
Puoi contrassegnare un insight come accettato per indicare che intendi eseguire 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 aggiorna l'insight 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 facoltativi relativi 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'approfondimento
- STATE_METADATA è un campo facoltativo con metadati aggiuntivi
sull'operazione. Specifica i metadati come 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": "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
.