Utilizzare l'API - Suggerimenti

In questa pagina viene spiegato come visualizzare e gestire i suggerimenti nel motore per suggerimenti utilizzando i comandi gcloud o l'API REST.

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

Tieni presente che è possibile interagire solo con i suggerimenti 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 per l'hub dei suggerimenti o per il recommender 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 il 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. Il numero di progetto è consigliato.

    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 consigliato completo (ad esempio, google.compute.instance.MachineTypeRecommender).

Consulta la pagina Motori per suggerimenti, dove troverai una tabella di link alle informazioni su ciascun strumento per suggerimenti, tra cui le località supportate e gli ID motore.

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 servizi contiene l'autorizzazione richiesta.
  • Ogni motore per suggerimenti richiede autorizzazioni specifiche. Consulta Motori per suggerimenti per una tabella di link alle informazioni su ciascun motore per suggerimenti, incluse le autorizzazioni richieste.

Elenco suggerimenti

Come mostrato nella scheda gcloud Beta, puoi elencare tutti i suggerimenti del progetto senza dover specificare una località e un motore per suggerimenti. Questa funzionalità è in anteprima.

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

gcloud beta

Inserisci quanto segue:

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

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

Ad esempio:

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

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 suggerimenti sul dimensionamento delle istanze VM attuali 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 comandi Google Cloud CLI successivi o chiamate API REST, fai riferimento sia all'ID suggerimento sia all'etag, per garantire che tutte le operazioni vengano eseguite solo se il suggerimento non è stato modificato dall'ultima volta che lo hai recuperato.

Contrassegnare un consiglio come rivendicato o ignorato

Puoi contrassegnare un suggerimento come rivendicato per indicare che intendi applicare le modifiche suggerite alla risorsa associata. Quando viene rivendicato un suggerimento, il tuo nome utente viene assegnato come attore del suggerimento e il motore per suggerimenti non lo aggiorna con i 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 consiglio ATTIVO. Il motore per suggerimenti può continuare ad aggiornarlo 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 per un 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 precedente chiamata per elencare i suggerimenti
  • etag è l'etag restituito che rappresenta lo stato del consiglio
  • STATE_METADATA è un metadato facoltativo relativo 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 per un 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 precedente chiamata per elencare i suggerimenti
  • etag è l'etag restituito che rappresenta lo stato del suggerimento
  • STATE_METADATA è un campo facoltativo con metadati aggiuntivi sull'operazione. Specifica i metadati sotto forma di 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

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 sulle dimensioni 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 dell'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"

Modificare lo stato di un suggerimento

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

Per contrassegnare un consiglio come completato:

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 superato.
  • STATE_METADATA sono metadati facoltativi relativi all'operazione. Specifica i metadati come elenco separato 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 recuperato da una precedente chiamata per elencare i suggerimenti
  • 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 superato.
  • etag è l'etag restituito che rappresenta lo stato del consiglio
  • STATE_METADATA è un campo facoltativo con metadati aggiuntivi sull'operazione. Specifica i metadati sotto forma di 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.