Utilizzare l'API - Suggerimenti

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

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

1. Elenca i consigli per un progetto specifico.

2. Contrassegna un suggerimento che intendi applicare come claimed oppure contrassegna un suggerimento che non intendi applicare come dismissed.

3. Applica il consiglio. Puoi farlo automaticamente utilizzando Active Assist nella console Google Cloud o manualmente utilizzando i comandi Google Cloud CLI, le chiamate API REST o altri strumenti.

   Quando applichi manualmente il suggerimento, i comandi o le chiamate che utilizzi sono specifici per il tipo di risorsa. Ad esempio, per modificare le dimensioni di un'istanza VM in risposta a un suggerimento del recommender per il dimensionamento delle istanze VM, utilizzi i comandi gcloud di Compute Engine o le chiamate all'API REST di Compute Engine.

   Quando esegui queste operazioni, identifichi la risorsa di destinazione utilizzando il valore del campo resource nell'array OperationsGroup nell'entità Recommendation restituita. Questo campo ha il seguente formato:

   //API_NAME/RESOURCE_PATH

   Ad esempio:

   //compute.googleapis.com/projects/example-project/zones/us-central1-a/instances/instance-1

4. Contrassegna il suggerimento come succeeded o failed.

Tieni presente che solo i suggerimenti recuperati tramite l'API possono essere utilizzati tramite l'API o l'esportazione in BigQuery.

Per informazioni sulla modifica dello stato dei suggerimenti nella consoleGoogle Cloud , consulta la documentazione di Active Assist o del motore per suggerimenti appropriato.

Avviso:

Prima di applicare i consigli nella console Google Cloud o utilizzando l'API, assicurati che gli impatti vengano valutati da un revisore all'interno della tua organizzazione. Il revisore deve avere le conoscenze necessarie per valutare gli impatti identificati nei consigli, nonché gli impatti specifici per la tua infrastruttura e la tua attività. L'applicazione dei consigli senza una valutazione adeguata potrebbe comportare modifiche impreviste, ad esempio problemi di prestazioni del sistema, scarsa affidabilità o perdita delle autorizzazioni richieste. Se scegli di applicare i consigli senza revisione umana, assicurati di aver configurato una procedura di rollback prima di apportare modifiche.

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
RECOMMENDER=RECOMMENDER_ID

dove:

• TARGET_PROJECT_ID è il progetto di cui vuoi elencare i suggerimenti. 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 che dei comandi gcloud.

• LOCATION_ID è la Google Cloud posizione in cui si trovano le risorse associate ai consigli (ad esempio global o us-central1-a).

• RECOMMENDER_ID è l'ID motore per suggerimenti completo (ad esempio, google.compute.instance.MachineTypeRecommender).

Consulta la sezione Consigli per una tabella di link alle informazioni su ciascun consiglio, incluse le località supportate e gli ID dei consigli.

Imposta autorizzazioni

Devi disporre delle autorizzazioni per accedere ai suggerimenti 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 Consumer utilizzo servizi contiene l'autorizzazione richiesta.
• Ogni sistema di raccomandazione richiede autorizzazioni specifiche. Consulta la sezione Recommender per una tabella di link a informazioni su ciascun recommender, incluse le autorizzazioni richieste.

Nota: se utilizzi l'intestazione x-goog-user-project o il parametro della stringa di query userProject nella richiesta, devi disporre dell'autorizzazione serviceusage.services.use per l'ID progetto specificato, oltre alle normali autorizzazioni IAM necessarie per effettuare la richiesta.

Elenco di consigli

Come mostrato nella scheda gcloud Beta, puoi elencare tutti i consigli 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 suggerimenti. Per maggiori dettagli, consulta la scheda gcloud.

gcloud Beta

Anteprima

Questa funzionalità è soggetta ai "Termini delle Offerte pre-GA" nella sezione 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 saperne di più, consulta le descrizioni della fase di lancio.

Inserisci quanto segue:

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

dove FORMAT è un gcloud formato di output supportato, ad esempio json.

Ad esempio:

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

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

gcloud

Inserisci quanto segue:

gcloud recommender recommendations list \
    --project=${PROJECT} \
    --location=${LOCATION} \
    --recommender=${RECOMMENDER} \
    --format=FORMAT

dove FORMAT è un gcloud formato di output supportato (ad esempio, json).

Ad esempio:

gcloud recommender recommendations list \
    --project=example-project \
    --location=us-central1-a \
    --recommender=google.compute.instance.MachineTypeRecommender \
    --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}/recommenders/${RECOMMENDER}/recommendations"

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/recommenders/google.compute.instance.MachineTypeRecommender/recommendations"

Questa operazione restituisce i consigli di dimensionamento dell'istanza VM corrente nel progetto di destinazione come elenco di entità Recommendation nel formato specificato.

L'output è simile al seguente:

[
  {
    "content": {
      "operationGroups": [
        {
          "operations": [
            {
              "action": "test",
              "path": "/machineType",
              "resource": "//compute.googleapis.com/projects/example-project/zones/us-central1-a/instances/instance-1",
              "resourceType": "compute.googleapis.com/Instance",
              "valueMatcher": {
                "matchesPattern": ".*zones/us-central1-a/machineTypes/n1-standard-4"
              }
            },
            {
              "action": "replace",
              "path": "/machineType",
              "resource": "//compute.googleapis.com/projects/example-project/zones/us-central1-a/instances/instance-1",
              "resourceType": "compute.googleapis.com/Instance",
              "value": "zones/us-central1-a/machineTypes/custom-2-5120"
            }
          ]
        }
      ]
    },
    "description": "Save cost by changing machine type from n1-standard-4 to custom-2-5120.",
    "etag": "\"280b34810bba8a1a\"",
    "lastRefreshTime": "2019-06-28T06:49:21Z",
    "name": "projects/32428390823/locations/us-central1-a/recommenders/google.compute.instance.MachineTypeRecommender/recommendations/a523ff7e-ed03-4143-a3a5-5b396b99cba9",
    "primaryImpact": { ... },
    "stateInfo": {
      "state": "ACTIVE"
    },
    "recommenderSubtype": "CHANGE_MACHINE_TYPE"
  }
]

Tieni presente che i suggerimenti restituiti includono i seguenti campi:

• Un campo name nel seguente formato:

  projects/PROJECT_ID/locations/LOCATION/recommenders/RECOMMENDER_ID/recommendations/RECOMMENDATION_ID

  dove RECOMMENDATION_ID identifica in modo univoco il consiglio

• Un campo etag associato allo stato attuale del suggerimento.

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

Modificare lo stato di un suggerimento

Puoi contrassegnare un consiglio come rivendicato per indicare che intendi applicare le modifiche consigliate alla risorsa associata. Quando un suggerimento viene rivendicato, il tuo nome utente viene assegnato come attore del suggerimento e Recommender non aggiorna il suggerimento con contenuti più recenti.

Puoi contrassegnare un consiglio come ignorato per indicare che non intendi applicare le modifiche consigliate alla risorsa associata o che non vuoi continuare a visualizzare il consiglio. Quando un consiglio viene ignorato, non viene più visualizzato come consiglio ATTIVO. Il sistema di raccomandazione potrebbe continuare ad aggiornare il consiglio con contenuti più recenti.

Dopo aver applicato un suggerimento, puoi contrassegnarlo come riuscito o non riuscito.

Per modificare lo stato di un consiglio, completa i seguenti passaggi:

gcloud

Inserisci quanto segue:

gcloud recommender recommendations STATE_CHANGE \
    RECOMMENDATION_ID \
    --project=${PROJECT} \
    --location=${LOCATION} \
    --recommender=${RECOMMENDER} \
    --etag=ETAG \
    --state-metadata=STATE_METADATA \
    --format=FORMAT

Dove

• STATE_CHANGE è la modifica che vuoi apportare a un consiglio. I valori validi sono:
  • mark-claimed per contrassegnare il suggerimento come rivendicato.
  • mark-dismissed per contrassegnare il suggerimento come ignorato.
  • mark-succeeded per contrassegnare il suggerimento come riuscito.
  • mark-failed per contrassegnare il suggerimento come non riuscito.
• RECOMMENDATION_ID è l'ID di un consiglio che hai recuperato da una precedente chiamata per elencare i consigli.
• ETAG è l'etag restituito che rappresenta lo stato del consiglio
• STATE_METADATA sono metadati facoltativi sull'operazione. Specifica i metadati come elenco separato da virgole di coppie KEY=VALUE. Questa opzione è disponibile quando contrassegni un suggerimento come rivendicato, riuscito o non riuscito.

Ad esempio:

gcloud recommender recommendations mark-succeeded \
    a523ff7e-ed03-4143-a3a5-5b396b99cba9 \
    --project=example-project \
    --location=us-central1-a \
    --recommender=google.compute.instance.MachineTypeRecommender \
    --etag='"5e3a63cccf1e0964"' \
    --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}/recommenders/${RECOMMENDER}/recommendations/RECOMMENDATION_ID:STATE_CHANGE \
<< EOM
{
  "etag": "ETAG"
  "stateMetadata": STATE_METADATA
}
EOM

dove:

• RECOMMENDATION_ID è l'ID di un consiglio che hai recuperato da una precedente chiamata per elencare i consigli.
• STATE_CHANGE è la modifica che vuoi apportare a un consiglio. I valori validi sono:
  • markClaimed per contrassegnare il suggerimento come rivendicato.
  • markDismissed per contrassegnare il suggerimento come ignorato.
  • markSucceeded per contrassegnare il suggerimento come riuscito.
  • markFailed per contrassegnare il suggerimento come non riuscito.
• ETAG è l'etag restituito che rappresenta lo stato del consiglio
• STATE_METADATA è un campo facoltativo con metadati aggiuntivi sull'operazione. Specifica i metadati come coppie key:value. Questo campo è disponibile quando contrassegni un consiglio come rivendicato, riuscito o non riuscito.

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/us-central1-a/recommenders/google.compute.instance.MachineTypeRecommender/recommendations/8f20d509-83d2-45d2-8152-1b8d5d7d5831:markSucceeded \
<< EOM
{
  "etag": "\"280b34810bba8a1a\""
  "stateMetadata": {
    "priority" : "high",
    "tracking_number": "12345"
  }
}
EOM

Questa operazione restituisce l'entità Recommendation nel formato specificato dopo l'esecuzione dell'operazione.

L'output è simile al seguente:

{
  "content": {
    "operationGroups": [ ... ]
  },
  "description": "Save cost by changing machine type from n1-standard-4 to custom-2-5120.",
  "etag": "\"5e3a63cccf1e053c\"",
  "lastRefreshTime": "2019-06-28T06:49:21Z",
  "name": "projects/32428390823/locations/us-central1-a/recommenders/google.compute.instance.MachineTypeRecommender/recommendations/a523ff7e-ed03-4143-a3a5-5b396b99cba9",
  "primaryImpact": { ... },
  "stateInfo": {
    "state": "SUCCEEDED",
    "stateMetadata": {
      "priority" : "high",
      "tracking_number": "12345"
    }
  }
}

Tieni presente che il valore del campo state è stato modificato in SUCCEEDED.