Utilizzo dell'API - Suggerimenti
In questa pagina viene spiegato come visualizzare e gestire
recommendations nel motore per suggerimenti utilizzando
gcloud
o
API REST.
Un'interazione tipica con l'API Recommender è la seguente:
- Elenca i consigli per una progetto specifico.
- Contrassegnare un consiglio che intendi applicare come rivendicato o un consiglio che non intendi applicare come ignorato.
- 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). - 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 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 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
.- Per i comandi
LOCATION_ID è Google Cloud località in cui le risorse associate consigli (ad es.
global
ous-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 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.
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 progetto, località e motore per suggerimenti. 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
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
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
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 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 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 applicare le modifiche consigliate 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 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 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 coppie KEY=VALUE. Questo è disponibile quando contrassegni un consiglio come rivendicati, con esito positivo 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 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 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
è stato modificato in CLAIMED
.
Applicazione dei consigli
Dopo aver contrassegnato un consiglio come rivendicato, puoi applicarlo utilizzando i comandi gcloud
o le chiamate all'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, identifichi la risorsa di destinazione utilizzando
del campo resource
nell'array OperationsGroup
nell'array restituito
Recommendation
. 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 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 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 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 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 sotto forma di coppie di
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
.