Panduan Pengguna Cloud Support API V2

Ringkasan

Untuk mempelajari lebih lanjut alasan Anda ingin menggunakan Cloud Support API beserta kegunaannya, lihat Ringkasan Cloud Support API. Halaman ini menunjukkan cara memulai Cloud Support API versi 2. Tersedia juga versi v2beta, tetapi ada beberapa perbedaan di antara keduanya. Beberapa perubahan dan fitur mungkin tersedia dalam v2beta sebelum v2, tetapi API v2 mungkin lebih cocok untuk sebagian besar kasus penggunaan.

Sekarang kita akan membahas cara menyiapkan API v2.

Memulai

Sebelum Anda dapat menggunakan Cloud Support API, lakukan hal berikut:

Aktifkan Cloud Support API dengan mengunjungi halaman Cloud Support API di Konsol Google Cloud dan mengklik AKTIFKAN.
Sediakan akun layanan dengan mengikuti petunjuk di Membuat akun layanan. Untuk mempelajari akun layanan lebih lanjut, lihat Ringkasan akun layanan.
Gunakan tab IAM di Google Cloud Console untuk memberikan peran Organization Viewer atau beberapa peran lain yang memberikan izin resourcemanager.organizations.get kepada akun layanan.

Anda juga dapat menggunakan perintah gcloud organizations add-iam-policy-binding:
```
gcloud organizations add-iam-policy-binding \\
organizations/ORG_ID \\
--role roles/resourcemanager.organizationViewer \\
--member SERVICE_ACCOUNT
```
Guna mempelajari cara menemukan nilai yang benar untuk 'ORG_ID', lihat Mengambil ID organisasi Anda.

Memberikan peran Tech Support Editor atau Tech Support Viewer kepada akun layanan. Untuk melakukannya, jalankan:

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

Jika Anda menggunakan integrasi pihak ketiga seperti JIRA, beri aplikasi pihak ketiga tersebut akses ke akun layanan. Untuk mempelajari autentikasi lebih lanjut, lihat Ringkasan autentikasi.

Jika Anda ingin menggunakan OAuth 2.0 untuk autentikasi:

Jika Anda belum menggunakan OAuth2 untuk melakukan autentikasi dengan Google, siapkan dengan mengikuti petunjuk OAuth 2.0 untuk Mengakses Google API. Harap perhatikan bagian tentang otorisasi inkremental.
Pastikan dua cakupan berikut ditambahkan ke client ID OAuth2 yang digunakan oleh aplikasi Anda:
- Untuk akses umum ke Google Cloud: https://www.googleapis.com/auth/cloud-platform atau https://www.googleapis.com/auth/cloud-platform.read-only
- Untuk akses guna mengambil atau membuat kasus dukungan dan data terkait dukungan lainnya: https://www.googleapis.com/auth/cloudsupport

Kontrol Akses dan Peran IAM

Layanan Pelanggan menggunakan Peran IAM berikut untuk mengontrol akses ke kasus. Anda dapat menggunakannya atau membuat peran khusus sendiri dengan izin apa pun yang Anda inginkan. Untuk mempelajari IAM lebih lanjut, lihat Kontrol akses dengan IAM.

Role	Izin
`Tech Support Viewer`	cloudsupport.techCases.get cloudsupport.techCases.list cloudsupport.techCaseAttachs.list cloudsupport.techCaseAttachs.download cloudsupport.techCaseComment.list cloudsupport.techCaseUpdates.list
`Tech Support Editor`	Izin Viewer Dukungan Teknis cloudsupport.techCases.create cloudsupport.techCases.update cloudsupport.techCases.escalate cloudsupport.techCases.close cloudsupport.techCase pengaruhs.create cloudsupport.techCaseAgreement.create

Menentukan library yang akan digunakan untuk memanggil Cloud Support API

Ada tiga jalur umum untuk memanggil API.

Gunakan Library Klien Cloud Cloud Support API untuk bahasa yang ingin Anda gunakan. Library ini tersedia untuk berbagai bahasa, tetapi tidak mendukung upload atau download lampiran. Untuk mempelajari jenis library ini lebih lanjut, lihat Library Klien Cloud
Gunakan Library Google API Python untuk membuat stub untuk memanggil Cloud Support API. Ini adalah pendekatan lama untuk memanggil API. Anda dapat mengupload atau mendownload lampiran dengan file tersebut. Untuk mempelajari jenis library ini lebih lanjut, lihat Library Klien Google API.
Gunakan cURL atau langsung panggil API. Hal ini memiliki keuntungan karena dapat disesuaikan sepenuhnya, tetapi Anda harus mengonfigurasi semuanya sendiri.

Jika Anda tidak perlu menggunakan lampiran, sebaiknya gunakan Library Klien Cloud. Jika tidak, sebaiknya gunakan Library Google API Python.

Menggunakan Library Klien Cloud

Cloud Support API menyediakan Library Klien Cloud untuk:

Untuk memulainya, cukup buka halaman web tersebut dan ikuti petunjuk dari sana.

Menggunakan library Google API Python

Untuk mulai menggunakan library Google API Python, lakukan hal berikut:

Instal paket Google Discovery dengan pip.
```
pip install google-api-python-client
```

Buat stub dalam kode Anda.

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}",
)

Panggil endpoint yang Anda inginkan. Kami telah menyediakan contoh cara melakukannya untuk setiap endpoint di Cloud Support API. Misalnya, lihat cases.list.

Saat Anda melakukan panggilan ke API dengan library Google API Python, kredensial default akan digunakan untuk lingkungan tempat program Anda berjalan. Pastikan akun layanan di lingkungan tersebut memiliki izin yang disebutkan di bagian Memulai.

Menggunakan cURL

Ada dua cara utama untuk mengautentikasi panggilan cURL Anda. Anda dapat menggunakan akun layanan, atau menggunakan kredensial default aplikasi. Untuk mempelajari lebih lanjut kredensial default aplikasi, lihat Cara kerja Kredensial Default Aplikasi.

Mengautentikasi dengan Akun Layanan

Lakukan autentikasi menggunakan Google Cloud CLI.

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

Kirim permintaan.

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

Mengautentikasi dengan Kredensial Default Aplikasi

Lakukan autentikasi menggunakan Google Cloud CLI.
```
gcloud auth application-default login
```

Kirim permintaan. Pastikan untuk menyertakan header x-goog-user-project, yang diperlukan saat Anda memanggil Cloud Support API dengan kredensial default aplikasi.

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