API verwenden – Empfehlungen

Auf dieser Seite erfahren Sie, wie Sie Empfehlungen in Recommender mit gcloud-Befehlen oder der REST-API anzeigen und verwalten.

Eine typische empfohlene Interaktion mit der Recommender API ist:

Informationen zum Ändern des Status von Empfehlungen in der Google Cloud Console finden Sie in der Dokumentation zu Recommendation Hub oder für den entsprechenden Recommender.

Standardprojekt festlegen

Legen Sie das Standardprojekt fest, falls Sie dies noch nicht getan haben:

gcloud config set project PROJECT_ID

Dabei entspricht PROJECT_ID der ID des Projekts.

Umgebungsvariablen festlegen

Legen Sie Umgebungsvariablen für Recommender-Interaktionen fest:

PROJECT=TARGET_PROJECT_ID
LOCATION=LOCATION_ID
RECOMMENDER=RECOMMENDER_ID

wobei

  • TARGET_PROJECT_ID ist das Projekt, dessen Empfehlungen Sie auflisten möchten. Dies kann ein anderes Projekt als Ihr aktuelles Projekt sein.

    • Für gcloud-Befehle müssen Sie die Projekt-ID verwenden
    • Für API-Anfragen können Sie die Projektnummer oder Projekt-ID verwenden. Projektnummer wird empfohlen.

    Die Projektnummer wird in Antworten der API und der gcloud-Befehle zurückgegeben.

  • LOCATION_ID der Google Cloud-Standort ist, an dem sich die Ressourcen für Empfehlungen befinden (z. B. global oder us-central1-a).

  • RECOMMENDER_ID die vollständig qualifizierte Empfehlungs-ID ist (z. B. google.compute.instance.MachineTypeRecommender).

Unter Empfehlungen finden Sie eine Tabelle mit verlinkten Informationen zu den einzelnen Empfehlungen, einschließlich unterstützter Standorte und Empfehlungs-IDs.

Berechtigungen festlegen

Sie müssen über die erforderlichen Berechtigungen verfügen, um auf Empfehlungen im Zielprojekt zuzugreifen. Diese Berechtigungen variieren je nach Recommender. Unter Recommender finden Sie eine Tabelle mit verlinkten Informationen über die einzelnen Recommender, einschließlich der erforderlichen Berechtigungen.

Empfehlungen auflisten

So listen Sie Empfehlungen im Zielprojekt auf:

gcloud

Passende Sucheingabe

gcloud recommender recommendations list \
    --project=${PROJECT} \
    --location=${LOCATION} \
    --recommender=${RECOMMENDER} \
    --format=FORMAT

Dabei ist FORMAT ein unterstütztes gcloud-Ausgabeformat (z. B. json).

Beispiel:

gcloud recommender recommendations list \
    --project=example-project \
    --location=us-central1-a \
    --recommender=google.compute.instance.MachineTypeRecommender \
    --format=json

REST

Passende Sucheingabe

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"

Beispiel:

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"

Dieser Vorgang gibt die Größenempfehlungen für die aktuelle VM-Instanz im Zielprojekt als Liste von Recommendation-Entitäten im angegebenen Format aus.

Die Ausgabe sieht etwa so aus:

[
  {
    "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"
  }
]

Die zurückgegebenen Empfehlungen umfassen die folgenden Felder:

  • Ein name-Feld im folgenden Format:

    projects/PROJECT_ID/locations/LOCATION/recommenders/RECOMMENDER_ID/recommendations/RECOMMENDATION_ID

    Dabei identifiziert RECOMMENDATION_ID die Empfehlung eindeutig

  • Ein etag-Feld, das dem aktuellen Empfehlungsstatus zugeordnet ist.

Wenn Sie mit nachfolgenden gcloud-Befehlen oder REST API-Aufrufen auf eine Empfehlung verweisen, verweisen Sie sowohl auf die Empfehlungs-ID als auch auf das etag. Dadurch werden alle Vorgänge nur dann ausgeführt, wenn die Empfehlung seit dem letzten Aufruf nicht geändert wurde.

Empfehlung als beansprucht markieren

Sie können eine Empfehlung als beansprucht markieren, um anzugeben, dass Sie die empfohlenen Änderungen auf die zugehörige Ressource anwenden möchten. Wenn eine Empfehlung angefordert wird, wird Ihr Nutzername als der Ersteller für die Empfehlung zugewiesen und Recommender aktualisiert die Empfehlung nicht mit neueren Inhalten.

So markieren Sie eine Empfehlung als "Beansprucht":

gcloud

Passende Sucheingabe

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

wobei

  • RECOMMENDATION_ID ist die ID einer Empfehlung, die Sie von einem vorherigen Aufruf abgerufen haben, um Empfehlungen für Listen abzurufen
  • etag ist das zurückgegebene etag, das den Empfehlungsstatus darstellt.
  • STATE_METADATA sind optionale Metadaten zum Vorgang. Geben Sie die Metadaten als kommagetrennte Liste von KEY=VALUE-Paaren an. Diese Option ist verfügbar, wenn Sie eine Empfehlung als beansprucht, erfolgreich oder fehlgeschlagen markieren.

Beispiel:

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

Passende Sucheingabe

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

wobei

  • RECOMMENDATION_ID ist die ID einer Empfehlung, die Sie von einem vorherigen Aufruf abgerufen haben, um Empfehlungen für Listen abzurufen
  • etag ist das zurückgegebene etag, das den Empfehlungsstatus darstellt.
  • STATE_METADATA ist ein optionales Feld mit zusätzlichen Metadaten zum Vorgang. Geben Sie die Metadaten als key:value-Paare an. Dieses Feld ist verfügbar, wenn Sie eine Empfehlung als beansprucht, erfolgreich oder fehlgeschlagen markieren.

Beispiel:

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

Dieser Vorgang gibt die Entität Recommendation im angegebenen Format zurück, nachdem der Vorgang abgeschlossen wurde.

Die Ausgabe sieht etwa so aus:

{
  "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"
  }
}

Beachten Sie, dass sich der Wert des Felds state in CLAIMED geändert hat.

Empfehlungen anwenden

Nachdem Sie eine Empfehlung als beansprucht markiert haben, können Sie die Empfehlung mit gcloud-Befehlen oder REST API-Aufrufen anwenden, die für den Ressourcentyp spezifisch sind.

Wenn Sie beispielsweise die Größe einer VM-Instanz als Reaktion auf eine Empfehlung des Größen-Recommenders für die VM-Instanz ändern möchten, verwenden Sie Compute Engine-gcloud-Befehle oder Aufrufe der Compute Engine REST API.

Wenn Sie diese Vorgänge ausführen, identifizieren Sie die Zielressource mithilfe des Werts des Feldes resource im Array OperationsGroup der zurückgegebenen Recommendation-Entität. Dieses Feld hat folgendes Format:

//API_NAME/RESOURCE_PATH

Beispiel:

//compute.googleapis.com/projects/example-project/zones/us-central1-a/instances/instance-1"

Status einer Empfehlung ändern

Nachdem Sie eine Empfehlung übernommen haben, können Sie sie als erfolgreich oder fehlgeschlagen markieren.

So markieren Sie eine Empfehlung als erfolgreich:

gcloud

Passende Sucheingabe

gcloud recommender recommendations STATE_CHANGE \
    RECOMMENDATION_ID \
    --project=${PROJECT} \
    --location=${LOCATION} \
    --recommender=${RECOMMENDER} \
    --etag=etag \
    --state-metadata=priority=high,tracking_number=12345
    --format=FORMAT

Wo

  • STATE_CHANGE ist die Änderung, die Sie an einer Empfehlung vornehmen möchten.
  • STATE_METADATA sind optionale Metadaten zum Vorgang. Geben Sie die Metadaten als eine durch Kommas getrennte Liste von KEY=VALUE - Paaren an. Diese Option ist verfügbar, wenn Sie eine Empfehlung als beansprucht, erfolgreich oder fehlgeschlagen markieren.

Gültige Werte sind:

  • mark-succeeded, um die Empfehlung als erfolgreich zu markieren.
  • mark-failed, um die Empfehlung als fehlgeschlagen zu markieren.

Beispiel:

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

Geben Sie Folgendes ein:

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

wobei

  • RECOMMENDATION_ID ist die ID einer Empfehlung, die Sie von einem vorherigen Aufruf abgerufen haben, um Empfehlungen für Listen abzurufen
  • STATE_CHANGE ist die Änderung, die Sie an einer Empfehlung vornehmen möchten. Gültige Werte sind:
    • markSucceeded, um die Empfehlung als erfolgreich zu markieren.
    • markFailed, um die Empfehlung als fehlgeschlagen zu markieren.
  • etag ist das zurückgegebene etag, das den Empfehlungsstatus darstellt.
  • STATE_METADATA ist ein optionales Feld mit zusätzlichen Metadaten zum Vorgang. Geben Sie die Metadaten als key:value-Paare an. Dieses Feld ist verfügbar, wenn Sie eine Empfehlung als beansprucht, erfolgreich oder fehlgeschlagen markieren.

Beispiel:

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

Dieser Vorgang gibt die Entität Recommendation im angegebenen Format zurück, nachdem der Vorgang abgeschlossen wurde.

Die Ausgabe sieht etwa so aus:

{
  "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"
    }
  }
}

Beachten Sie, dass sich der Wert des Felds state in SUCCEEDED geändert hat.