Utilizzo dell'API - Suggerimenti

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

Ecco una tipica interazione di suggerimento con l'API motore per suggerimenti:

  • Elenco dei consigli attualmente disponibile per un motore per suggerimenti specifico
  • Contrassegna un consiglio che vuoi applicare come rivendicato o contrassegna quello che non intendi applicare come ignorato.
  • Applica il consiglio 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)
  • Contrassegna il consiglio come riuscito o non riuscito.

Per informazioni sulla modifica dello stato dei suggerimenti nella console Google Cloud, consulta la documentazione per Recommendation Hub o per il consigliatore appropriato.

Imposta il progetto predefinito

Imposta il progetto predefinito se non lo 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 con motore per suggerimenti:

PROJECT=TARGET_PROJECT_ID
LOCATION=LOCATION_ID
RECOMMENDER=RECOMMENDER_ID

dove:

  • TARGET_PROJECT_ID è il progetto di cui vuoi elencare i consigli. 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. Il numero di progetto è consigliato.

    Il numero del progetto viene restituito nelle risposte dei comandi API e gcloud.

  • LOCATION_ID è la località di 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 la sezione Consigliatori per visualizzare una tabella di link alle informazioni su ogni motore per suggerimenti, comprese le località e gli ID motore per suggerimenti supportati.

Imposta autorizzazioni

Devi avere le 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 contiene l'autorizzazione serviceusage.services.use. Il ruolo Consumatore del servizio Service contiene l'autorizzazione richiesta.
  • Ogni motore per suggerimenti richiede autorizzazioni specifiche. Consulta la sezione Consigliatori per visualizzare una tabella dei link alle informazioni su ogni motore per suggerimenti, incluse le autorizzazioni richieste.

Elenco consigli

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 gcloudformato 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 genera l'attuale istanza di VM mediante suggerimenti di dimensionamento 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 consigli 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 all'attuale stato del consiglio.

Quando fai riferimento a un consiglio utilizzando i comandi gcloud successivi o le chiamate API REST, fai riferimento sia all'ID suggerimento che all'etag, per garantire che le operazioni vengano eseguite solo se il consiglio 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 consiglio viene rivendicato, il tuo nome utente viene assegnato come attore per il consiglio e il motore per suggerimenti non aggiorna il consiglio 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 visualizzare il consiglio. Quando un consiglio viene ignorato, non comparirà più come consiglio 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 che vuoi contrassegnare come consigliato. 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 che hai recuperato da una precedente chiamata a un elenco di consigli
  • etag è l'tag restituito che rappresenta lo stato del consiglio
  • STATE_METADATA è un metadati facoltativo dell'operazione. Specifica i metadati come elenco separato da virgole di KEY=VALUE coppie. 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 che vuoi contrassegnare come consigliato. 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 che hai recuperato da una precedente chiamata a un elenco di 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 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 che l'operazione è stata eseguita.

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

Dopo aver contrassegnato un consiglio come rivendicato, puoi applicare il consiglio 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 consiglio del motore per suggerimenti sul 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, individui la risorsa di destinazione utilizzando il valore del campo resource nell'array OperationsGroup nell'entità Recommendation restituita. Questo campo è nel seguente formato:

//API_NAME/RESOURCE_PATH

Ad esempio:

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

Modificare lo stato di un consiglio

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

Per contrassegnare un consiglio come completato correttamente:

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 completato.
    • mark-failed per contrassegnare il consiglio come non riuscito.
  • STATE_METADATA è un metadati facoltativo dell'operazione. Specifica i metadati come elenco comune 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 a un elenco di consigli
  • STATE_CHANGE è la modifica che vuoi apportare a un consiglio. I valori validi sono:
    • markSucceeded per contrassegnare il consiglio come completato.
    • markFailed per contrassegnare il consiglio come non riuscito.
  • etag è l'tag 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 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 che l'operazione è stata eseguita.

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.