Utilizzo dell'API - Suggerimenti

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

In genere, un'interazione con l'API motore per suggerimenti è:

Per informazioni sulla modifica dello stato dei suggerimenti in Google Cloud Console, consulta la documentazione relativa a Recommendation Hub o al consigliatore appropriato.

Imposta 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 del motore per suggerimenti:

PROJECT=TARGET_PROJECT_ID
LOCATION=LOCATION_ID
RECOMMENDER=RECOMMENDER_ID

dove:

  • TARGET_PROJECT_ID è il progetto per cui vuoi elencare i consigli. Può essere un progetto diverso dal progetto 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 sia dai comandi dell'API che da 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).

Visita la pagina Consigliatori per visualizzare una tabella di link alle informazioni su ogni motore per suggerimenti, incluse le località e gli ID dei suggerimenti supportati.

Imposta le autorizzazioni

Devi disporre delle autorizzazioni per accedere ai suggerimenti nel progetto di destinazione. Queste autorizzazioni variano in base al motore per suggerimenti. Consulta la sezione Consigliatori per visualizzare 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 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 l'attuale istanza di dimensionamento delle VM nel progetto di destinazione sotto forma di elenco di entità di 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 di consiglio corrente.

Quando fai riferimento a un consiglio tramite i comandi gcloud successivi o le chiamate API REST, fai riferimento sia all'ID consiglio sia all'etag, per assicurare che le operazioni vengano eseguite solo se il consiglio non è stato modificato dall'ultimo recupero.

Contrassegnare un consiglio come rivendicato

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 per il consiglio e il motore per suggerimenti non lo aggiorna con contenuti più recenti.

Per contrassegnare un consiglio come rivendicato:

gcloud

Inserisci quanto segue:

gcloud recommender recommendations mark-claimed \
    RECOMMENDATION_ID \
    --project=${PROJECT} \
    --location=${LOCATION} \
    --recommender=${RECOMMENDER} \
    --etag=etag \
    --state-metadata=STATE_METADATA
    --format=FORMAT

dove:

  • 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 metadati facoltativo sull'operazione. Specifica i metadati come elenco separato da virgole di KEY=VALUE coppie. 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:markClaimed \
<< EOM
{
  "etag": "etag",
  "stateMetadata": STATE_METADATA
}
EOM

dove:

  • 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 che è stata eseguita l'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 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 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. 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 completato 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.
  • STATE_METADATA è un metadati facoltativo sull'operazione. Specifica i metadati come elenco separato da comune di KEY=VALUE coppie. Questa opzione è disponibile quando contrassegni un consiglio come rivendicato, riuscito o non riuscito.

I valori validi sono:

  • mark-succeeded per contrassegnare il consiglio come completato.
  • mark-failed per contrassegnare il consiglio come 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:markSucceeded \
<< 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 consiglio come completato.
    • 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 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 che è stata eseguita l'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.