Utilizzo dell'API - Approfondimenti

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

Una tipica interazione di approfondimento con l'API Recommender è:

• Elenca gli approfondimenti per un progetto specifico
• Contrassegna come accettato un approfondimento su cui intendi intervenire

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 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ò 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 di progetto.

  Il numero di progetto viene restituito nelle risposte sia dell'API sia dei comandi gcloud.

• LOCATION_ID è la Google Cloud località in cui si trovano le risorse associate agli approfondimenti (ad esempio, global o us-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 una tabella di link alle informazioni su ogni tipo di approfondimento, incluse le località supportate e gli ID dei tipi di approfondimento.

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 contiene l'autorizzazione serviceusage.services.use. Il ruolo Consumer di utilizzo del servizio contiene l'autorizzazione richiesta.
• Ogni tipo di approfondimento richiede autorizzazioni specifiche. Consulta la sezione Tipi di approfondimenti per una tabella di link alle informazioni su ogni tipo di approfondimento, incluse le autorizzazioni richieste.

Nota: se utilizzi l'x-goog-user-project o il userProject nella richiesta, devi disporre dell' serviceusage.services.use per l'ID progetto specificato, oltre alle normali autorizzazioni IAM richieste per effettuare la richiesta.

Elenca gli approfondimenti

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

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

gcloud Beta

Anteprima

Questa funzionalità è soggetta ai "Termini dell'offerta pre-GA" nella sezione dei Termini di servizio generali dei Termini specifici dei servizi. Le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per ulteriori informazioni, consulta le descrizioni della fase di lancio.

Inserisci quanto segue:

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

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

Ad esempio:

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

Nota: a differenza dell'output seguente per le schede gcloud e REST, che è limitato agli insight per una località e un motore per suggerimenti, l'output includerà tutti gli insight per il progetto.

gcloud

Inserisci quanto segue:

gcloud recommender insights list \
    --project=${PROJECT} \
    --location=${LOCATION} \
    --insight-type=${INSIGHT_TYPE} \
    --format=FORMAT

dove FORMAT è un formato di gcloud 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 del criterio IAM corrente nel progetto di destinazione come un elenco di Insight entità nel formato specificato.

L'output è simile al seguente:

[
  {
    "category": "SECURITY",
    "content": {
      "condition": {
        "description": "",
        "expression": "",
        "location": "",
        "title": ""
      },
      "exercisedPermissions": [],
      "inferredPermissions": [],
      "member": "user:[e-mail]",
      "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 o le chiamate API REST successive, 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.

Contrassegna un approfondimento 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 per l'approfondimento e Recommender non aggiornerà 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 approfondimenti
• etag è l'etag restituito che rappresenta lo stato dell'approfondimento
• STATE_METADATA sono metadati facoltativi sull'operazione. Specifica i metadati come un 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 approfondimenti
• 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 l'operazione è stata eseguita.

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": "[e-mail]",
  "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 è cambiato in ACCEPTED.