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 è:
- Elenca i suggerimenti per un progetto specifico.
- Contrassegna un consiglio che intendi applicare come rivendicato o contrassegna un consiglio che non intendi applicare come rifiutato.
- Applica il suggerimento utilizzando i comandi
gcloud
o chiamate API REST specifiche per il tipo di risorsa (ad esempio, ruoli IAM o istanze VM di Compute Engine). - Contrassegna il suggerimento come riuscito o non riuscito.
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
.- Per i comandi
LOCATION_ID è la località Google Cloud in cui si trovano le risorse associate ai suggerimenti (ad esempio
global
ous-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 gcloud
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 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
.