Utilizzo dell'API - Suggerimenti

Questa pagina spiega come visualizzare e gestire i suggerimenti nel motore per suggerimenti utilizzando i comandi gcloud o l'API REST.

Una tipica interazione dei suggerimenti con l'API Recommender è:

  • Elenco suggerimenti attualmente disponibili per uno specifico motore per suggerimenti
  • Contrassegna come rivendicato un consiglio che vuoi applicare oppure un consiglio che non intendi applicare come ignorato.
  • Applica il suggerimento utilizzando i comandi gcloud o le chiamate API REST specifiche per il tipo di risorsa (ad esempio, ruoli IAM o istanze VM di Compute Engine)
  • Contrassegnare il consiglio come riuscito o non riuscito

Tieni presente che è possibile interagire solo con i consigli recuperati tramite l'API tramite l'API o BigQuery Export.

Per informazioni sulla modifica dello stato dei suggerimenti nella console Google Cloud, consulta la documentazione dell'hub dei suggerimenti o del recommender 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
RECOMMENDER=RECOMMENDER_ID

dove:

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

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

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

Consulta i motori per suggerimenti per una tabella di link che rimandano alle informazioni su ogni motore per suggerimenti, inclusi le località supportate e gli ID del motore per suggerimenti.

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 contenente l'autorizzazione serviceusage.services.use. Il ruolo Consumer utilizzo dei servizi contiene l'autorizzazione richiesta.
  • Ogni motore per suggerimenti richiede autorizzazioni specifiche. Consulta i motori per suggerimenti per una tabella di link alle informazioni su ogni motore per suggerimenti, incluse le autorizzazioni richieste.

Elenco suggerimenti

Per elencare i suggerimenti nel progetto di destinazione:

gcloud

Inserisci quanto segue:

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

dove FORMAT è un formato di output gcloud 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 genera i suggerimenti attuali per il dimensionamento delle istanze VM nel progetto di destinazione sotto forma di 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 del suggerimento corrente.

Quando fai riferimento a un suggerimento utilizzando i comandi gcloud o le chiamate API REST successive, devi fare riferimento sia all'ID suggerimento che all'etag, il che garantisce che le operazioni vengano eseguite solo se il suggerimento non è stato modificato dall'ultimo recupero.

Contrassegnare un consiglio come rivendicato o ignorato

Puoi contrassegnare un suggerimento 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 il motore per suggerimenti non aggiorna il suggerimento con contenuti più recenti.

Puoi contrassegnare un suggerimento come ignorato per indicare che non intendi applicare le modifiche consigliate alla risorsa associata o che non vuoi continuare a vedere il suggerimento. Quando un consiglio viene ignorato, non verrà più visualizzato come ATTIVO. Il motore per suggerimenti potrebbe continuare ad aggiornare il consiglio con contenuti più recenti.

Per contrassegnare un consiglio come rivendicato o ignorato:

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 è lo stato da contrassegnare come consiglio. I valori validi sono:
    • mark-claimed per contrassegnare il consiglio come rivendicato.
    • mark-dismissed per contrassegnare il consiglio come ignorato.
  • RECOMMENDATION_ID è l'ID di un consiglio recuperato da una chiamata precedente per elencare consigli
  • etag è l'etag restituito che rappresenta lo stato del consiglio
  • STATE_METADATA è un metadati facoltativi relativi all'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-claimed \
    a523ff7e-ed03-4143-a3a5-5b396b99cba9 \
    --project=example-project \
    --location=us-central1-a \
    --recommender=google.compute.instance.MachineTypeRecommender \
    --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}/recommenders/${RECOMMENDER}/recommendations/RECOMMENDATION_ID:STATE_CHANGE \
<< EOM
{
  "etag": "etag",
  "stateMetadata": STATE_METADATA
}
EOM

dove:

  • STATE_CHANGE è lo stato da contrassegnare come consiglio. I valori validi sono:
    • mark-claimed per contrassegnare il consiglio come rivendicato.
    • mark-dismissed per contrassegnare il consiglio come ignorato.
  • RECOMMENDATION_ID è l'ID di un consiglio recuperato da una chiamata precedente per elencare consigli
  • 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 di key:value. Questo campo è disponibile quando contrassegni un suggerimento 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:markClaimed \
<< 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": "\"5e3a63cccf1e0964\"",
  "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": "CLAIMED"
  }
}

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

Applicazione dei consigli in corso...

Dopo aver contrassegnato un suggerimento come rivendicato, puoi applicarlo utilizzando i comandi gcloud o le chiamate API REST specifiche per il tipo di risorsa.

Ad esempio, per modificare le dimensioni di un'istanza VM in risposta a un suggerimento del motore per suggerimenti per il dimensionamento delle istanze VM, puoi utilizzare 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. Il formato di questo campo è il seguente:

//API_NAME/RESOURCE_PATH

Ad esempio:

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

Modifica dello stato di un suggerimento

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

Per contrassegnare un consiglio come riuscito:

gcloud

Inserisci quanto segue:

gcloud recommender recommendations STATE_CHANGE \
    RECOMMENDATION_ID \
    --project=${PROJECT} \
    --location=${LOCATION} \
    --recommender=${RECOMMENDER} \
    --etag=etag \
    --state-metadata=priority=high,tracking_number=12345
    --format=FORMAT

Dove

  • STATE_CHANGE è la modifica che vuoi apportare a un consiglio. I valori validi sono:
    • mark-succeeded per contrassegnare il consiglio come riuscito.
    • mark-failed per contrassegnare il consiglio come non riuscito.
  • STATE_METADATA è un metadati facoltativi relativi all'operazione. Specifica i metadati come un elenco separato da comuni 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 recuperato da una chiamata precedente per elencare consigli
  • STATE_CHANGE è la modifica che vuoi apportare a un consiglio. I valori validi sono:
    • markSucceeded per contrassegnare il consiglio come riuscito.
    • markFailed per contrassegnare il consiglio 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 di key:value. Questo campo è disponibile quando contrassegni un suggerimento 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.