Cloud Support API V2 ユーザーガイド

概要

Cloud Support API を使用する理由とその目的については、Cloud Support API の概要をご覧ください。このページでは、Cloud Support API バージョン 2 の使用を開始する方法について説明します。v2beta バージョンも用意されていますが、2 つの違いはほとんどありません。v2beta では v2 より前の変更と機能の一部を使用できますが、v2 API がほとんどのユースケースにより適しています。

次に、v2 API を設定する方法について説明します。

Getting Started

Cloud Support API を使用する前に、次のことを行います。

  1. Google Cloud コンソールで Cloud Support API のページにアクセスし、[有効にする] をクリックして、Cloud Support API を有効にします。

  2. サービス アカウントの作成の手順に沿ってサービス アカウントをプロビジョニングします。サービス アカウントの詳細については、サービス アカウントの概要をご覧ください。

  3. Google Cloud コンソールの [IAM] タブで、サービス アカウントに Organization Viewer ロールを付与するか、resourcemanager.organizations.get 権限を付与するその他のロールを付与します。

    また、gcloud organizations add-iam-policy-binding コマンドの使用も可能です。

    gcloud organizations add-iam-policy-binding \\
organizations/ORG_ID \\
--role roles/resourcemanager.organizationViewer \\
--member SERVICE_ACCOUNT

    「ORG_ID」の正しい値を確認する方法については、組織 ID を取得するをご覧ください。

  4. サービス アカウントにテクニカル サポート編集者またはテクニカル サポート閲覧者のロールを付与します。これを行うには、次のコマンドを実行します。

    gcloud organizations add-iam-policy-binding \\
organizations/ORG_ID \\
--role roles/cloudsupport.techSupportEditor \\
--member SERVICE_ACCOUNT

  5. JIRA などのサードパーティ統合を使用する場合は、サードパーティ アプリケーションにサービス アカウントへのアクセス権を付与します。認証の詳細については、認証の概要をご覧ください。

認証に OAuth 2.0 を使用する場合:

  1. Google での認証に OAuth2 をまだ使用していない場合は、OAuth 2.0 を使用した Google API へのアクセスに従って設定します。特に、増分承認に関するセクションに注意してください。

  2. アプリケーションで使用される OAuth2 クライアント ID に、次の 2 つのスコープが追加されていることを確認します。

    • 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 ロールを使用してケースへのアクセスを制御します。これらの IAM ロールを使用することも、目的の権限を持つカスタムロールを独自に作成することもできます。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

Cloud Support API の呼び出しに使用するライブラリの決定

API を呼び出すための一般的なパスは 3 つあります。

  1. 使用する言語の Cloud Support API Cloud クライアント ライブラリを使用します。さまざまな言語で利用できますが、添付ファイルのアップロードやダウンロードはサポートされていません。このタイプのライブラリの詳細については、Cloud クライアント ライブラリをご覧ください。

  2. Python Google API ライブラリを使用して、Cloud Support API を呼び出すスタブを作成します。 これは、API を呼び出すための以前のアプローチです。添付ファイルをアップロードまたはダウンロードすることもできます。 このタイプのライブラリの詳細については、Google API クライアント ライブラリをご覧ください。

  3. cURL を使用するか、API を直接呼び出します。これには完全にカスタマイズできるという利点がありますが、すべてを自分で構成する必要があります。

添付ファイルを使用する必要がない場合は、Cloud クライアント ライブラリを使用することをおすすめします。それ以外の場合は、Python Google API ライブラリの使用をおすすめします。

Cloud クライアント ライブラリの使用

Cloud Support API には、次の Cloud クライアント ライブラリが用意されています。

使用を開始するには、そのページに移動して、指示に従うだけです。

Python Google API ライブラリの使用

Python Google API ライブラリを使用する手順は次のとおりです。

  1. Google 調査パッケージを pip でインストールします。

    pip install google-api-python-client

  2. コード内でスタブを作成します。

    import googleapiclient.discovery

api_version = "v2"
supportApiService = googleapiclient.discovery.build(
    serviceName="cloudsupport",
    version=api_version,
    discoveryServiceUrl=f"https://cloudsupport.googleapis.com/$discovery/rest?version={api_version}",
)

  3. 目的のエンドポイントを呼び出します。これは、Cloud Support API の各エンドポイントに対する例を示しています。たとえば、cases.list をご覧ください。

Python Google API ライブラリを使用して API を呼び出すと、プログラムが実行されている環境のデフォルトの認証情報が使用されます。環境のサービス アカウントに、スタートガイド セクションに記載されている権限があることを確認します。

cURL の使用

cURL 呼び出しの認証方法は主に 2 つあります。サービス アカウントを使用することも、アプリケーションのデフォルト認証情報を使用することもできます。アプリケーションのデフォルト認証情報の詳細については、アプリケーションのデフォルト認証情報の仕組みをご覧ください。

サービス アカウントによる認証

  1. Google Cloud CLI を使用して認証します。

    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. Google Cloud CLI を使用して認証します。

    gcloud auth application-default login

  2. リクエストを送信します。 必ず x-goog-user-project ヘッダーを含めてください。これは、アプリケーションのデフォルト認証情報を使用して Cloud Support API を呼び出すときに必要です。

    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