Questa pagina è stata tradotta dall'API Cloud Translation.

Utilizzare l'API - Approfondimenti

Questa pagina spiega come visualizzare e gestire gli insight in Recommender utilizzando i comandi gcloud o l'API REST.

Una tipica interazione con l'API Recommender è:

Elencare gli approfondimenti per un progetto specifico
Contrassegna un insight su cui intendi intervenire come accettato

Per informazioni sulla modifica dello stato degli approfondimenti nella console Google Cloud , consulta la documentazione di Recommendation Hub o del tipo di approfondimento appropriato.

Impostare 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 di Recommender:

PROJECT=TARGET_PROJECT_ID
LOCATION=LOCATION_ID
INSIGHT_TYPE=INSIGHT_TYPE_ID

dove:

TARGET_PROJECT_ID è il progetto di cui vuoi elencare gli approfondimenti. Può trattarsi di 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 progetto. È consigliabile il numero di progetto.
Il numero del progetto viene restituito nelle risposte sia dell'API sia dei comandi gcloud.
LOCATION_ID è la Google Cloud posizione in cui si trovano le risorse associate agli insight (ad esempio global o us-central1-a).
INSIGHT_TYPE_ID è l'ID tipo di insight completamente qualificato (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 approfondimenti 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 disporre di un ruolo nel progetto che contenga l'autorizzazione serviceusage.services.use. Il ruolo Consumer utilizzo servizi contiene l'autorizzazione richiesta.
Ogni tipo di insight richiede autorizzazioni specifiche. Consulta la sezione Tipi di approfondimenti per una tabella di link alle informazioni su ciascun tipo di approfondimento, incluse le autorizzazioni richieste.

Approfondimenti sugli elenchi

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

La funzionalità GA richiede di specificare un progetto, una posizione e un sistema di raccomandazione. Per maggiori dettagli, consulta la scheda gcloud.

gcloud Beta

Inserisci quanto segue:

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

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

Ad esempio:

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

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 approfondimenti sui criteri IAM correnti nel progetto di destinazione come un 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 attuale dell'approfondimento.

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

Contrassegnare un insight come accettato

Puoi contrassegnare un approfondimento come accettato per indicare che intendi intraprendere o hai intrapreso un'azione su una risorsa associata in base alle informazioni fornite nell'approfondimento. Quando un approfondimento viene accettato, il tuo nome utente viene assegnato come attore dell'approfondimento e Recommender non aggiornerà l'approfondimento con contenuti più recenti.

Per contrassegnare un insight 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 insight recuperato da una precedente chiamata per elencare gli insight
etag è l'etag restituito che rappresenta lo stato dell'insight
STATE_METADATA sono metadati facoltativi sull'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 insight recuperato da una precedente chiamata 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 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.