Utilizzo dell'API - Suggerimenti

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

Un'interazione tipica con l'API Recommender è la seguente:

  • Elenca i consigli per un progetto specifico.
  • Contrassegnare un consiglio che intendi applicare come rivendicato o un consiglio che non intendi applicare come ignorato.
  • Applica il consiglio utilizzando i comandi gcloud o le chiamate all'API REST specifiche per il tipo di risorsa (ad esempio, i ruoli IAM o le istanze VM di Compute Engine).
  • Contrassegnare il suggerimento come riuscito o non riuscito.

Tieni presente che solo i consigli recuperati tramite l'API possono essere utilizzati tramite l'API o BigQuery Export.

Per informazioni su come modificare lo stato dei consigli nella console Google Cloud, consulta la documentazione relativa a Recommendation Hub o al consigliere appropriato.

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 con il Recommender:

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 o l'ID progetto. È consigliabile utilizzare il numero del progetto.

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

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

  • RECOMMENDER_ID è l'ID del recommender completo (ad es.google.compute.instance.MachineTypeRecommender).

Consulta la sezione Consigliatori per una tabella di link alle informazioni su ciascun consigliere, incluse le località supportate e gli ID consigliere.

Imposta autorizzazioni

Devi disporre delle autorizzazioni per accedere ai consigli 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 Consumatore di utilizzo del servizio contiene l'autorizzazione richiesta.
  • Ogni consigliatore richiede autorizzazioni specifiche. Consulta la sezione Consigliatori per una tabella di link alle informazioni su ciascun consigliere, incluse le autorizzazioni richieste.

Consigli per gli elenchi

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

La funzionalità GA richiede di specificare un progetto, una località e un consigliere. Per informazioni dettagliate, consulta la scheda gcloud.

gcloud Beta

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

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 genera i suggerimenti di dimensionamento delle istanze VM correnti 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 allo stato attuale del consiglio.

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

Contrassegnare un consiglio come rivendicato o ignorato

Puoi contrassegnare un consiglio 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 del consiglio e Recommender non lo aggiorna 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 consigliatore 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 per un consiglio. I valori validi sono:
    • mark-claimed per contrassegnare il suggerimento come rivendicato.
    • mark-dismissed per contrassegnare il suggerimento come ignorato.
  • RECOMMENDATION_ID è l'ID di un consiglio recuperato da una chiamata precedente per elencare i consigli
  • etag è l'etag restituito che rappresenta lo stato del consiglio
  • STATE_METADATA è un metadato facoltativo sull'operazione. Specifica i metadati come elenco separato da virgole di coppie KEY=VALUE. Questa opzione è disponibile quando contrassegni un consiglio 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 per un consiglio. I valori validi sono:
    • mark-claimed per contrassegnare il suggerimento come rivendicato.
    • mark-dismissed per contrassegnare il suggerimento come ignorato.
  • RECOMMENDATION_ID è l'ID di un consiglio recuperato da una chiamata precedente per elencare i 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 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: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 è diventato CLAIMED.

Applicazione dei consigli

Dopo aver contrassegnato un consiglio come rivendicato, puoi applicarlo utilizzando comandi gcloud o 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 Recommender per il dimensionamento delle istanze VM, utilizza i comandi gcloud di Compute Engine o le chiamate all'API REST di Compute Engine.

Quando esegui queste operazioni, identifica 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"

Modificare lo stato di un consiglio

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 suggerimento come riuscito.
    • mark-failed per contrassegnare il suggerimento come non riuscito.
  • STATE_METADATA sono metadati facoltativi sull'operazione. Specifica i metadati come elenco separato da un carattere comune di coppie KEY=VALUE. Questa opzione è disponibile quando contrassegni un consiglio 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 i consigli
  • STATE_CHANGE è la modifica che vuoi apportare a un consiglio. I valori validi sono:
    • 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 è diventato SUCCEEDED.