API 사용 - 통계

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

Recommender API와의 일반적인 통계 상호작용은 다음과 같습니다.

현재 특정 통계 유형에 사용할 수 있는 목록 통계
조치를 취하려는 통계를 수락됨으로 표시

Google Cloud Console에서 통계 상태 변경에 대한 자세한 내용은 Recommendation Hub 또는 적절한 통계 유형 문서를 참조하세요.

기본 프로젝트 설정

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

gcloud config set project PROJECT_ID

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

환경 변수 설정

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

PROJECT=TARGET_PROJECT_ID
LOCATION=LOCATION_ID
INSIGHT_TYPE=INSIGHT_TYPE_ID

각 매개변수는 다음과 같습니다.

TARGET_PROJECT_ID는 통계를 나열하려는 프로젝트입니다. 이 프로젝트는 현재 프로젝트와 다른 프로젝트일 수 있습니다.
- gcloud 명령어의 경우 프로젝트 ID를 사용해야 합니다.
- API 요청에 프로젝트 번호 또는 프로젝트 ID를 사용할 수 있습니다. 프로젝트 번호를 사용하는 것이 좋습니다.
프로젝트 번호는 API 및 gcloud 명령어의 응답으로 반환됩니다.
LOCATION_ID는 통계와 연결된 리소스가 있는 Google Cloud 위치입니다(예: global 또는 us-central1-a).
INSIGHT_TYPE_ID는 정규화된 통계 유형 ID입니다(예: google.iam.policy.Insight).

지원되는 위치 및 통계 유형 ID를 포함한 각 통계 유형 정보에 대한 링크 표는 통계 유형을 참조하세요.

권한 설정

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

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

통계 나열

대상 프로젝트의 통계를 나열하는 방법은 다음과 같습니다.

gcloud

다음을 입력합니다.

gcloud recommender insights list \
    --project=${PROJECT} \
    --location=${LOCATION} \
    --insight-type=${INSIGHT_TYPE} \
    --format=FORMAT

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

예:

gcloud recommender insights list \
    --project=example-project \
    --location=global \
    --insight-type=google.iam.policy.Insight \
    --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}/insightTypes/${INSIGHT_TYPE}/insights"

예:

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/insightTypes/google.iam.policy.Insight/insights"

이 작업은 대상 프로젝트의 현재 IAM 정책 통계를 지정된 형식의 Insight 항목 목록으로 출력합니다.

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

[
  {
    "category": "SECURITY",
    "content": {
      "condition": {
        "description": "",
        "expression": "",
        "location": "",
        "title": ""
      },
      "exercisedPermissions": [],
      "inferredPermissions": [],
      "member": "user:my-service-account@example-project.iam.gserviceaccount.com",
      "role": "roles/iam.securityReviewer"
    },
    "description": "0 permission checks were authorized by this policy binding tuple.",
    "etag": "\"45f4e2c63f6952e8\"",
    "insightSubtype": "PERMISSIONS_USAGE",
    "lastRefreshTime": "2020-03-06T08:00:00Z",
    "name": "projects/32428390823/locations/global/insightTypes/google.iam.policy.Insight/insights/a523ff7e-ed03-4143-a3a5-5b396b99cba9",
    "observationPeriod": "7776000s",
    "stateInfo": {
      "state": "ACTIVE",
    },
    "targetResources": [
      "//cloudresourcemanager.googleapis.com/projects/32428390823"
    ],
  }
]

반환된 통계에는 다음 필드가 포함됩니다.

name 필드 형식은 다음과 같습니다.
```
projects/PROJECT_ID/locations/LOCATION/insightTypes/INSIGHT_TYPE_ID/insights/INSIGHT_ID
```
여기서 INSIGHT_ID는 통계를 고유하게 식별합니다.
현재 통계 상태와 연결된 etag 필드입니다.

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

통계를 수락됨으로 표시

통계를 수락됨으로 표시하면 통계에 제공된 정보를 바탕으로 관련 리소스에 조치를 취할 의도를 나타내거나 조치를 취했음을 나타낼 수 있습니다. 통계가 수락되면 사용자 이름이 통계의 작업 수행자로 할당되며 추천자는 최신 콘텐츠로 통계를 업데이트하지 않습니다.

통계를 수락됨으로 표시하려면 다음 안내를 따르세요.

gcloud

다음을 입력합니다.

gcloud recommender insights mark-accepted \
    INSIGHT_ID \
    --project=${PROJECT} \
    --location=${LOCATION} \
    --insight-type=${INSIGHT_TYPE} \
    --etag=etag \
    --state-metadata=STATE_METADATA
    --format=FORMAT

각 매개변수는 다음과 같습니다.

INSIGHT_ID는 통계를 나열하기 위해 이전 호출에서 검색한 통계의 ID입니다.
etag는 통계 상태를 나타내는 반환된 etag입니다.
STATE_METADATA는 작업에 대한 선택적 메타데이터입니다. 메타데이터를 쉼표로 구분된 KEY=VALUE 쌍의 목록으로 지정합니다.

예:

gcloud recommender insights mark-accepted \
    a523ff7e-ed03-4143-a3a5-5b396b99cba9 \
    --project=example-project \
    --location=global \
    --insight-type=google.iam.policy.Insight \
    --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}/insightTypes/${INSIGHT_TYPE}/insights/INSIGHT_ID:markAccepted \
<< EOM
{
  "etag": "etag",
  "stateMetadata": STATE_METADATA
}
EOM

각 매개변수는 다음과 같습니다.

INSIGHT_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/global/insightTypes/google.iam.policy.Insight/insights/a523ff7e-ed03-4143-a3a5-5b396b99cba9:markAccepted \
<< EOM
{
  "etag": "\"280b34810bba8a1a\""
  "stateMetadata": {
    "priority" : "high",
    "tracking_number": "12345"
  }
}
EOM

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

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

{
  "category": "SECURITY",
  "content": { ...  },
  "description": "0 permission checks were authorized by this policy binding tuple.",
  "etag": "\"356ae51165729f38\"",
  "insightSubtype": "PERMISSIONS_USAGE",
  "lastModifiedUser": "admin123@example-project.iam.gserviceaccount.com",
  "lastRefreshTime": "2020-03-06T08:00:00Z",
  "name": "projects/32428390823/locations/global/insightTypes/google.iam.policy.Insight/insights/a523ff7e-ed03-4143-a3a5-5b396b99cba9",
  "observationPeriod": "7776000s",
  "stateInfo": {
    "state": "ACCEPTED",
    "stateMetadata": {
      "priority" : "high",
      "tracking_number": "12345"
    }
  },
  "targetResources": [
    "//cloudresourcemanager.googleapis.com/projects/32428390823"
  ],
  "userLastUpdateTime": "2020-03-31T20:57:50.509855Z"
}

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