API 사용 - 권장사항

이 페이지에서는 gcloud 명령어 또는 REST API를 사용하여 추천자에서 권장사항을 보고 관리하는 방법을 설명합니다.

Recommender API와의 일반적인 권장사항 상호작용은 다음과 같습니다.

  • 특정 프로젝트에 대한 권장사항 나열합니다.
  • 적용하려는 권장사항을 사용함으로 표시하거나 적용하지 않을 권장사항을 닫음으로 표시합니다.
  • 리소스 유형(예: IAM 역할 또는 Compute Engine VM 인스턴스)에 대한 gcloud 명령어 또는 REST API 호출을 사용하여 권장사항을 적용합니다.
  • 권장사항을 성공 또는 실패로 표시합니다.

API를 통해 가져온 권장사항만 API 또는 BigQuery Export를 통해 상호작용할 수 있습니다.

Google Cloud 콘솔에서 권장사항 상태를 변경하는 방법에 대한 자세한 내용은 권장사항 허브 또는 적절한 recommender 문서를 참조하세요.

기본 프로젝트 설정

기본 프로젝트를 아직 설정하지 않았으면 설정합니다.

gcloud config set project PROJECT_ID

여기서 PROJECT_ID는 프로젝트 ID입니다.

환경 변수 설정

추천자 상호작용을 위한 환경 변수를 설정합니다.

PROJECT=TARGET_PROJECT_ID
LOCATION=LOCATION_ID
RECOMMENDER=RECOMMENDER_ID

각 항목의 의미는 다음과 같습니다.

  • TARGET_PROJECT_ID는 권장사항을 나열할 프로젝트입니다. 이 프로젝트는 현재 프로젝트와 다른 프로젝트일 수 있습니다.

    • gcloud 명령어의 경우 프로젝트 ID를 사용해야 합니다.
    • API 요청에 프로젝트 번호 또는 프로젝트 ID를 사용할 수 있습니다. 프로젝트 번호를 사용하는 것이 좋습니다.

    프로젝트 번호는 API 및 gcloud 명령어의 응답으로 반환됩니다.

  • LOCATION_ID는 권장사항과 관련된 리소스가 있는 Google Cloud 위치입니다(예: global 또는 us-central1-a).

  • RECOMMENDER_ID는 정규화된 추천자 ID입니다(예: google.compute.instance.MachineTypeRecommender).

지원되는 위치 및 추천자 ID를 포함하여 각 추천자에 대한 정보로 연결되는 링크 표는 추천자를 참조하세요.

권한 설정

대상 프로젝트의 권장사항에 액세스할 수 있는 권한이 있어야 합니다.

  • 요청에 결제 프로젝트를 포함한 요청자. 요청에 사용된 프로젝트는 양호한 상태여야 하며 사용자는 프로젝트에 serviceusage.services.use 권한이 포함된 역할을 보유해야 합니다. 서비스 사용량 소비자 역할에 필요한 권한이 있습니다.
  • 각 추천자에는 특정 권한이 필요합니다. 필수 권한을 포함하여 각 추천자에 대한 정보에 연결되는 표는 추천자를 참조하세요.

권장사항 나열

gcloud Beta 탭에 표시된 것처럼 위치와 추천자를 지정하지 않아도 프로젝트의 모든 권장사항을 나열할 수 있습니다. 이 기능은 미리보기 기능입니다.

정식 버전의 기능을 사용하려면 프로젝트, 위치, 추천자를 지정해야 합니다. 자세한 내용은 gcloud 탭을 참조하세요.

gcloud Beta

다음을 입력합니다.

gcloud beta recommender recommendations list \
    --project=${PROJECT} \
    --format=FORMAT

여기서 FORMAT은 지원되는 gcloud 출력 형식입니다(예: json).

예를 들면 다음과 같습니다.

gcloud beta recommender recommendations list \
    --project=example-project \
    --format=json

gcloud

다음을 입력합니다.

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

여기서 FORMAT은 지원되는 gcloud 출력 형식입니다(예: json).

예를 들면 다음과 같습니다.

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

REST

다음을 입력합니다.

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"

예를 들면 다음과 같습니다.

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"

이 작업은 대상 프로젝트의 현재 VM 인스턴스 크기 권장사항을 지정된 형식의 Recommendation 항목 목록으로 출력합니다.

결과는 다음과 비슷합니다.

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

반환된 권장사항에는 다음 필드가 포함됩니다.

  • name 필드 형식은 다음과 같습니다.

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

    여기서 RECOMMENDATION_ID가 권장사항을 고유하게 식별합니다.

  • 현재 권장사항 상태와 연결된 etag 필드입니다.

후속 Google Cloud CLI 명령어 또는 REST API 호출을 사용하여 권장사항을 참조할 때는 권장사항 ID와 ETag를 모두 참조하므로 마지막으로 검색한 이후 권장사항을 수정하지 않은 경우에만 작업이 수행됩니다.

권장사항을 사용함 또는 닫음으로 표시

권장사항을 사용함으로 표시하여 권장 변경사항을 관련 리소스에 적용할 것임을 나타낼 수 있습니다. 권장사항을 사용하면 사용자 이름이 권장사항의 작업 수행자로 할당되며 추천자는 최신 콘텐츠로 권장사항을 업데이트하지 않습니다.

권장사항을 닫음으로 표시하여 권장 변경사항을 관련 리소스에 적용할 의도가 없거나 계속 권장사항을 보지 않을 것을 나타낼 수 있습니다. 권장사항을 닫으면 더 이상 활성 권장사항으로 표시되지 않습니다. 추천자는 최신 콘텐츠로 권장사항을 계속 업데이트할 수 있습니다.

권장사항을 사용함 또는 닫음으로 표시하려면 다음 안내를 따르세요.

gcloud

다음을 입력합니다.

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

각 항목의 의미는 다음과 같습니다.

  • STATE_CHANGE는 권장사항에 표시할 상태입니다. 유효한 값은 다음과 같습니다.
    • mark-claimed는 권장사항을 사용함으로 표시합니다.
    • mark-dismissed는 권장사항을 닫음으로 표시합니다.
  • RECOMMENDATION_ID는 권장사항을 나열하기 위해 이전 호출에서 검색한 권장사항의 ID입니다.
  • etag는 권장사항 상태를 나타내는 반환된 etag입니다.
  • STATE_METADATA는 작업에 대한 선택적 메타데이터입니다. 메타데이터를 쉼표로 구분된 KEY=VALUE 쌍의 목록으로 지정합니다. 이 옵션은 권장사항을 사용함, 성공 또는 실패로 표시할 때 사용할 수 있습니다.

예를 들면 다음과 같습니다.

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

다음을 입력합니다.

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

각 항목의 의미는 다음과 같습니다.

  • STATE_CHANGE는 권장사항에 표시할 상태입니다. 유효한 값은 다음과 같습니다.
    • mark-claimed는 권장사항을 사용함으로 표시합니다.
    • mark-dismissed는 권장사항을 닫음으로 표시합니다.
  • RECOMMENDATION_ID는 권장사항을 나열하기 위해 이전 호출에서 검색한 권장사항의 ID입니다.
  • etag는 권장사항 상태를 나타내는 반환된 etag입니다.
  • STATE_METADATA는 작업에 대한 추가 메타데이터가 포함된 선택적 필드입니다. 메타데이터를 key:value 쌍으로 지정합니다. 이 필드는 권장사항을 사용함, 성공 또는 실패로 표시할 때 사용할 수 있습니다.

예를 들면 다음과 같습니다.

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

이 작업은 작업이 수행된 후 지정된 형식으로 Recommendation 항목을 반환합니다.

결과는 다음과 비슷합니다.

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

state 필드 값이 CLAIMED로 변경되었습니다.

권장사항 적용

권장사항을 사용함으로 표시한 후에는 리소스 유형과 관련된 gcloud 명령어 또는 REST API 호출을 사용하여 권장사항을 적용할 수 있습니다.

예를 들어 VM 인스턴스 크기 추천자의 권장사항에 대한 응답으로 VM 인스턴스 크기를 변경하려면 Compute Engine gcloud 명령어 또는 Compute Engine REST API에 대한 호출을 사용합니다.

이러한 작업을 수행할 때 반환된 Recommendation 항목의 OperationsGroup 배열에 있는 resource 필드 값을 사용하여 대상 리소스를 식별합니다. 이 필드의 형식은 다음과 같습니다.

//API_NAME/RESOURCE_PATH

예를 들면 다음과 같습니다.

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

권장사항 상태 변경

권장사항을 적용한 후 성공 또는 실패로 표시할 수 있습니다.

권장사항을 성공으로 표시하려면 다음 단계를 따르세요.

gcloud

다음을 입력합니다.

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

장소

  • STATE_CHANGE는 권장사항에 적용할 변경사항입니다. 유효한 값은 다음과 같습니다.
    • mark-succeeded는 권장사항을 성공으로 표시합니다.
    • mark-failed는 권장사항을 실패로 표시합니다.
  • STATE_METADATA는 작업에 대한 선택적 메타데이터입니다. 메타데이터를 쉼표로 구분된 KEY=VALUE 쌍의 목록으로 지정합니다. 이 옵션은 권장사항을 사용함, 성공 또는 실패로 표시할 때 사용할 수 있습니다.

예를 들면 다음과 같습니다.

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

다음을 입력합니다.

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

각 항목의 의미는 다음과 같습니다.

  • RECOMMENDATION_ID는 권장사항을 나열하기 위해 이전 호출에서 검색한 권장사항의 ID입니다.
  • STATE_CHANGE는 권장사항에 적용할 변경사항입니다. 유효한 값은 다음과 같습니다.
    • markSucceeded는 권장사항을 성공으로 표시합니다.
    • markFailed는 권장사항을 실패로 표시합니다.
  • etag는 권장사항 상태를 나타내는 반환된 etag입니다.
  • STATE_METADATA는 작업에 대한 추가 메타데이터가 포함된 선택적 필드입니다. 메타데이터를 key:value 쌍으로 지정합니다. 이 필드는 권장사항을 사용함, 성공 또는 실패로 표시할 때 사용할 수 있습니다.

예를 들면 다음과 같습니다.

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

이 작업은 작업이 수행된 후 지정된 형식으로 Recommendation 항목을 반환합니다.

결과는 다음과 비슷합니다.

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

state 필드 값이 SUCCEEDED로 변경되었습니다.