Cloud Support API V2 사용자 가이드

개요

이 페이지에서는 cloudsupport.googleapis.com API 버전 2, 특히 v2 엔드포인트를 시작하는 방법을 설명합니다.

Cloud Support API를 통합하면 사용자 조직의 고객 관계 관리(CRM) 시스템과 함께 Cloud Customer Care를 사용할 수 있습니다. Cloud Support API를 사용하면 사용자가 CRM에서 다음을 포함하여 다양한 지원 작업을 직접 완료할 수 있습니다.

지원 기록 작성 및 관리
케이스의 첨부파일 나열, 만들기, 다운로드
케이스 의견 나열 및 만들기

다음 섹션에서는 시작하는 방법과 지원 API와 관련된 다양한 요소를 둘러싼 주요 개념에 대하여 살펴보겠습니다.

시작하기

이 섹션에서는 Cloud Support API를 시작하기 위한 프로세스를 간략하게 설명합니다.

Google Cloud 콘솔에서 Cloud Support API 페이지로 이동하고 사용 설정을 클릭하여 Cloud Support API를 사용 설정합니다.

Cloud Support API 페이지로 이동
서비스 계정 이해의 지침에 따라 서비스 계정을 하나 이상 프로비저닝합니다.

사용자 인증 정보 관리 도구가 이미 있으면 Google Cloud 서비스 계정에 동일한 도구를 활용하는 것이 좋습니다.
Google Cloud 콘솔의 IAM 탭 아래에서 서비스 계정에 Organization Viewer 역할을 부여하거나 resourcemanager.organizations.get 권한을 부여하는 다른 역할을 부여하세요.

프로그래매틱 방식으로 처리할 수도 있습니다.
```
  gcloud organizations add-iam-policy-binding \
  organizations/ORG_ID \
  --role roles/resourcemanager.organizationViewer \
  --member SERVICE_ACCOUNT
```

서비스 계정에 기술 지원 편집자 또는 기술 지원 뷰어 역할을 부여합니다. 프로그래매틱 방식으로 이 작업을 수행할 수 있습니다.
```
  gcloud organizations add-iam-policy-binding \
  organizations/ORG_ID \
  --role roles/cloudsupport.techSupportEditor \
  --member SERVICE_ACCOUNT
```
JIRA와 같은 타사 통합을 사용하는 경우 사용자 인증 정보를 공유하여 타사 애플리케이션에 서비스 계정에 대한 액세스 권한을 부여합니다. 자세한 단계는 인증 개요를 참조하세요.
고객의 애플리케이션은 최종 사용자 인증 정보 대신 서비스 계정 사용자 인증 정보를 사용하여 최종 사용자 API와 마찬가지로 정기적인 API 호출을 수행합니다.

OAuth 2.0 인증을 원하는 경우:

OAuth2를 사용하여 Google 인증하지 않는 경우 Google API에 액세스하기 위한 OAuth 2.0 가이드에 따라 설정합니다. 증분 승인 섹션을 주의 깊게 살펴보세요.
애플리케이션에서 사용하는 OAuth2 클라이언트 ID에 다음 두 범위가 추가되어 있는지 확인합니다.
- Google Cloud 일반 액세스: https://www.googleapis.com/auth/cloud-platform 또는 https://www.googleapis.com/auth/cloud-platform.read-only
- 지원 티켓 및 기타 지원 관련 데이터를 검색하거나 생성할 수 있는 권한: https://www.googleapis.com/auth/cloudsupport

액세스 제어 및 IAM 역할

프리미엄 지원에서는 다음 IAM 역할을 사용하여 케이스에 대한 액세스를 제어합니다. 자세한 내용은 액세스 제어 문서를 참조하세요.

역할	권한
`Tech Support Viewer`	cloudsupport.techCases.get cloudsupport.techCases.list cloudsupport.techCaseAttachments.list cloudsupport.techCaseAttachments.download cloudsupport.techCaseComments.list cloudsupport.techCaseUpdates.list
`Tech Support Editor`	기술 지원 뷰어 권한 cloudsupport.techCases.create cloudsupport.techCases.update cloudsupport.techCases.escalate cloudsupport.techCases.close cloudsupport.techCaseAttachments.create cloudsupport.techCaseComments.create

로컬에서 클라이언트 라이브러리 생성

API 정의는 Google Cloud 검색 문서로 제공됩니다. 자세한 내용은 Google API 검색 서비스를 참조하세요.

다음 명령어를 사용하여 정의 파일을 생성합니다.curl 'https://cloudsupport.googleapis.com/$discovery/rest?version=v2' > /tmp/cloudsupport.v2.json
다음으로 Google API 클라이언트 생성기를 클론합니다.cd /tmp/; git clone https://github.com/google/apis-client-generator.git;
Python이 설치되어 있는지 확인합니다.sudo apt-get install python
PIP가 설치되어 있는지 확인합니다.sudo apt-get install python-pip
종속 항목 설치pip install google-apis-client-generator
클라이언트 라이브러리 생성: 이 명령어는 WARNING:root:object without properties로 시작하는 1~2개의 경고를 생성합니다. 무시해도 괜찮습니다. 클라이언트 라이브러리는 계속 생성됩니다../generate.sh --input=/tmp/cloudsupport.v2.json --output_dir=/tmp/cloudsupport_generated --language=java

클라이언트 라이브러리(Python)를 통한 Cloud Support API 사용

이 예시에서 사용자는 코드 몇 줄만 사용하여 Python의 클라이언트 라이브러리를 사용할 수 있습니다. 이렇게 하면 App Engine 또는 Compute Engine과 같은 다양한 Google Cloud 제품에 간편하게 통합할 수 있습니다.

이 메서드를 사용할 때 API는 코드가 실행되는 환경의 기본 사용자 인증 정보를 사용하려 합니다(따라서 사용 중인 서비스 계정에 시작하기 섹션에 언급된 적절한 권한이 있는지 확인하세요.)

import googleapiclient.discovery

SERVICE_NAME = "cloudsupport"
API_VERSION = "v2"
API_DEFINITION_URL = "https://cloudsupport.googleapis.com/$discovery/rest?version=" + API_VERSION
PARENT = "organizations/" + ORGANIZATION_ID

supportApiService = googleapiclient.discovery.build(
    serviceName=SERVICE_NAME,
    version=API_VERSION,
    discoveryServiceUrl=API_DEFINITION_URL)

case_list = supportApiService.cases().list(parent=PARENT).execute()

cURL을 통한 Cloud Support API 사용

gcloud CLI가 설치되면 간단하게 Support API를 호출하고 적절한 사용자 인증 정보를 전달하여 인증합니다. 다음 예시에서는 조직 상위 요소에서 사용할 수 있는 케이스를 나열하는 API 호출에 이 작업을 수행하는 방법을 보여줍니다.

서비스 계정으로 인증

1단계: 인증

gcloud auth activate-service-account SERVICE_ACCOUNT_EMAIL \
  --key-file=/path/key.json \
  --project=PROJECT_ID

2단계: 요청 보내기

curl \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  https://cloudsupport.googleapis.com/v2/organizations/ORGANIZATION_ID/cases

애플리케이션 기본 사용자 인증 정보로 인증

1단계: 인증

gcloud auth application-default login

2단계: 요청 보내기

참고: 애플리케이션 기본 사용자 인증 정보를 사용하여 Cloud Support API를 호출할 때는 추가 헤더(x-goog-user-project)가 필요합니다.

curl \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "x-goog-user-project: $(gcloud config get-value project)" \
  https://cloudsupport.googleapis.com/v2/organizations/ORGANIZATION_ID/cases

주요 개념

Cloud Support API를 성공적으로 사용하려면 몇 가지 주요 개념을 깊이 있게 이해해야 합니다. 다음에서 이러한 주요 개념 중 몇 가지를 살펴보겠습니다.

케이스

케이스 객체는 Google 지원팀에서 처리하는 특정 지원 케이스와 관련된 세부정보가 포함된 항목입니다. 여기에는 케이스 생성 타임스탬프, 우선순위, 케이스 분류, 지원 케이스 관련 설명과 같은 필드가 포함됩니다. 또한 모든 지원 케이스에는 지원 케이스 전체 기간 동안 추가되는 관련 의견과 첨부파일도 있습니다.

케이스 분류

케이스 분류는 지원 케이스에 대한 주제를 식별합니다. 여기에는 일반적으로 'Cloud Storage' 또는 'Compute Engine'과 같은 특정 제품과 '권한' 또는 '지연 시간'과 같은 일반적인 문제 유형이 포함됩니다.

v2의 경우 케이스 분류 객체에는 전체 분류의 고유 식별자인 id와 사람이 읽을 수 있는 설명인 displayName이 포함됩니다. 이는 v2alpha에서 변경된 주요 사항 중 하나입니다.

지원 케이스를 만들 때 유효한 케이스 분류 ID는 필수 필드입니다. 케이스를 전문가로 라우팅하는 데 사용되므로 정확한 분류가 중요합니다.

케이스 의견

케이스 의견은 Google 지원팀에서 지원 케이스에 대한 업데이트를 전달하는 주요 방법입니다. 사용자가 Google 지원에 회신할 때 사용자의 회신 내용도 케이스 의견으로 표시됩니다.

케이스 첨부파일

케이스 첨부파일에는 사용자 또는 Google 지원에서 지원 케이스에 업로드한 파일에 대한 세부정보가 포함됩니다. UI를 사용할 때 첨부파일이 Cloud Console에서 의견과 동시에 업로드될 수 있지만 첨부파일은 '의견' 수준이 아닌 '케이스' 수준에서 연결됩니다.

행위자 객체

행위자 객체는 주어진 작업을 수행한 항목을 지정합니다. 예를 들어 행위자는 지원 케이스에 의견을 작성한 사용자, 첨부파일을 업로드한 사용자, 또는 지원 케이스를 생성한 서비스 계정(Support API 컨텍스트에서 이는 서비스 계정의 이메일 주소에 해당함)이 될 수 있습니다.

케이스 리소스 구조

Cloud Support API V2에서 지원 케이스는 Google Cloud 조직 또는 프로젝트의 상위 요소가 될 수 있습니다. 'parent' 식별자는 '/cases/' 이전의 경로 두 개를 나타냅니다.

조직은 숫자로 식별되므로 조직의 상위 케이스 이름은 다음과 같이 표시됩니다.

organizations/ORGANIZATION_ID/cases/CASE_NUMBER

프로젝트에는 ID와 번호의 두 가지 고유 식별자가 있으므로 프로젝트가 상위 요소로 간주되는 경우에는 다음 중 하나를 통해 식별할 수 있습니다.

projects/PROJECT_ID/cases/CASE_NUMBER

projects/PROJECT_NUMBER/cases/CASE_NUMBER

사용자는 API를 호출할 때 이러한 식별자 중 하나를 구현할 수 있지만 API는 프로젝트 번호를 사용하여 응답만 반환합니다.

IAM 권한은 리소스의 상위 항목을 기준으로 상속되므로 프로젝트는 프로젝트가 속한 조직의 권한을 상속합니다. 자세한 내용은 리소스 계층 구조에 대한 문서를 참조하세요.