Utilizzare l'API - Suggerimenti

In questa pagina viene spiegato come visualizzare e gestire recommendations nel motore per suggerimenti utilizzando gcloud o API REST.

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

  • Elenca i consigli per una progetto specifico.
  • Contrassegna come consiglio un consiglio che intendi applicare claim o contrassegnare come e il consiglio che non intendi applicare ignorata.
  • Applica il consiglio utilizzando gcloud o chiamate API REST specifiche per il tipo di risorsa (ad esempio ruoli IAM o istanze VM di Compute Engine).
  • Contrassegna il consiglio come riusciti o non riusciti.

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 nel nella console Google Cloud, consulta la documentazione Hub dei suggerimenti 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 il motore per suggerimenti:

PROJECT=TARGET_PROJECT_ID
LOCATION=LOCATION_ID
RECOMMENDER=RECOMMENDER_ID

dove:

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

    Il numero del progetto viene restituito nelle risposte dell'API e di gcloud tramite comandi SQL.

  • LOCATION_ID è Google Cloud località in cui le risorse associate consigli (ad es. global o us-central1-a).

  • RECOMMENDER_ID ha ottenuto la qualificazione ID motore per suggerimenti (ad esempio, google.compute.instance.MachineTypeRecommender).

Consulta la pagina Motori per suggerimenti per visualizzare una tabella di link alle informazioni su ogni motore per suggerimenti, incluse località supportate e ID 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 utilizzata nella richiesta deve essere in regola e l'utente deve avere un ruolo il progetto che contiene l'autorizzazione serviceusage.services.use. La Il ruolo Consumatore utilizzo servizi contiene l'autorizzazione richiesta.
  • Ogni motore per suggerimenti richiede autorizzazioni specifiche. Consulta i motori per suggerimenti per visualizzare una tabella di link alle informazioni su ciascun motore per suggerimenti, tra cui le autorizzazioni necessarie.
di Gemini Advanced.

Elenco suggerimenti

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

La funzionalità GA richiede di specificare progetto, località e 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 gcloud supportato formato di output, come 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 supportato formato di output (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 Recommendation entità nel 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 consiglio utilizzando i comandi Google Cloud CLI successivi o per le chiamate API REST, fai riferimento sia all'ID suggerimento che all'etag. In questo modo, che tutte le operazioni vengano eseguite solo se il suggerimento non ha modificata dall'ultima volta che l'hai recuperata.

Contrassegnare un consiglio come rivendicato o ignorato

Puoi contrassegnare un consiglio come rivendicato per indicare che intendi applicarlo le modifiche suggerite alla risorsa associata. Quando un consiglio viene rivendicato, il tuo nome utente viene assegnato come attore del suggerimento Il motore per suggerimenti non lo aggiorna 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 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 che hai recuperato da una chiamata precedente 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 KEY=VALUE coppie. Questo è disponibile quando contrassegni un consiglio come rivendicati, completati o non riusciti.

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 che hai recuperato da una chiamata precedente per elencare i suggerimenti
  • etag è l'etag restituito che rappresenta il consiglio stato
  • STATE_METADATA è un campo facoltativo con metadati aggiuntivi sull'operazione. Specifica i metadati sotto forma di coppie di key:value. Questo è disponibile quando contrassegni un consiglio come rivendicati, completati o non riusciti.

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 Entità Recommendation nel 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 consiglio come rivendicato, puoi applicare suggerimento 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 dal motore per suggerimenti per il dimensionamento delle istanze VM, utilizzerai Compute Engine gcloud o chiamate al API REST di Compute Engine.

Quando esegui queste operazioni, identifichi la risorsa di destinazione utilizzando del campo resource nell'array OperationsGroup nell'array restituito Recommendation. Questo 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 KEY=VALUE coppie. Questo è disponibile quando contrassegni un consiglio come rivendicati, completati o non riusciti.

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 chiamata precedente 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 è disponibile quando contrassegni un consiglio come rivendicati, completati o non riusciti.

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 Entità Recommendation nel 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.