Questa pagina è stata tradotta dall'API Cloud Translation.

Utilizzare l'API - Approfondimenti

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

Una tipica interazione con gli approfondimenti dell'API Recommender è:

Elenca gli approfondimenti per un progetto specifico
Contrassegna come accettata un'intuizione in base alla quale intendi intervenire.

Per informazioni su come modificare lo stato degli approfondimenti nella console Google Cloud, consulta la documentazione dell'hub di consigli 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 con il 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ò 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 progetto. È consigliabile utilizzare il numero del 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 approfondimenti (ad esempio global o us-central1-a).
INSIGHT_TYPE_ID è l'ID tipo di approfondimento completo (ad es.google.iam.policy.Insight).

Consulta la sezione Tipi di insight per una tabella di link alle informazioni su ciascun tipo di insight, incluse le località supportate e gli ID tipo 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 avere un ruolo nel progetto che contenga l'autorizzazione serviceusage.services.use. Il ruolo Consumatore di utilizzo del servizio contiene l'autorizzazione richiesta.
Ogni tipo di informazione 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.

Elenco approfondimenti

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

La funzionalità GA richiede di specificare un progetto, una località e un consigliere. Per informazioni dettagliate, 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 genera gli approfondimenti 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 le informazioni restituite 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'intuizione

Un campo etag associato allo stato attuale dell'informazione.

Quando fai riferimento a un'intuizione utilizzando comandi gcloud o chiamate API REST successivi, fai riferimento sia all'ID dell'intuizione sia all'etag, il che garantisce che eventuali operazioni vengano eseguite solo se l'intuizione non è stata modificata dall'ultima volta che l'hai recuperata.

Contrassegnare un insight come accettato

Puoi contrassegnare un'intuizione come accettata per indicare che intendi intraprendere o hai intrapreso un'azione su una risorsa associata in base alle informazioni fornite nell'intuizione. Quando un'intuizione viene accettata, il tuo nome utente viene assegnato come agente per l'intuizione e Recommender non aggiorna l'intuizione 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'informazione recuperata da una chiamata precedente per elencare le informazioni
etag è l'etag restituito che rappresenta lo stato dell'insight
STATE_METADATA è un metadato facoltativo 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'informazione recuperata da una chiamata precedente per elencare le informazioni
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'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 è diventato ACCEPTED.