Pengantar
Halaman ini menjelaskan cara menggunakan Service Control API v2 untuk kontrol masuk bagi layanan terkelola yang terintegrasi dengan Infrastruktur Layanan. Fitur ini ditujukan bagi produsen layanan yang ingin mengintegrasikan layanan mereka secara mendalam dengan Google Cloud.
Infrastruktur Layanan adalah platform dasar bagi developer untuk memproduksi, mengelola, mengamankan, dan menggunakan API dan layanan. Model ini menggunakan model penggunaan layanan umum yang sederhana: konsumen menggunakan layanan yang dikelola oleh produsen. Semua Google API dan Google Cloud API menggunakan model ini, karena juga dibuat di atas Infrastruktur Layanan.
Saat klien mengakses layanan, semua entity yang terlibat dalam akses biasanya memerlukan pemeriksaan status dan kebijakan, termasuk konsumen, layanan, produsen, pengguna, aplikasi, jaringan, dan resource. Dengan Infrastruktur Layanan, proses ini disebut kontrol penerimaan, yang mencakup autentikasi, otorisasi, pengauditan, pembatasan kapasitas, dan lainnya.
API Kontrol Layanan v2
Service Control API v2 menyediakan metode services.check
sederhana yang menyediakan kontrol akses masuk ke semua layanan yang terintegrasi dengan Infrastruktur Layanan.
Metode ini memungkinkan Anda melakukan hal berikut dalam satu panggilan metode:
- Pemeriksaan status
- Status penyalahgunaan
- Status penagihan
- Status konsumen
- Status layanan
- Pengaktifan layanan
- Autentikasi
- Token akses Google OAuth
- JWT yang ditandatangani dengan akun layanan Google
- Otorisasi
- Mengaudit
- Cloud Audit Logs. Log audit terkait dengan layanan "externalaudit.googleapis.com".
Saat layanan memanggil Service Control API, produsen juga merupakan
konsumen Service Control API. Oleh karena itu, metode services.check
juga menjalankan kontrol penerimaan pada panggilan ke Service Control API.
Agar layanan dapat memanggil Service Control API, Anda harus mengaktifkan Service Control API di project produsen dan memiliki izin yang tepat pada layanan tersebut. Untuk mengetahui informasi selengkapnya, lihat Memulai Cloud API dan Kontrol Akses Kontrol Layanan.
Atribut permintaan
Saat klien mengakses layanan, layanan tersebut harus memisahkan akses menjadi satu atau beberapa permintaan API yang dapat diperiksa dengan kontrol penerimaan. Pada umumnya, akses tersebut merupakan permintaan API yang sebenarnya. Dalam kasus lain, akses dapat berupa tugas impor data atau kueri SQL yang rumit, dan layanan perlu membuat model akses dalam kaitannya dengan kumpulan permintaan API virtual dan melakukan kontrol penerimaan pada setiap permintaan.
Untuk menjalankan kontrol penerimaan menggunakan Service Control API, layanan perlu
memanggil metode
services.check
dengan atribut permintaan yang diperlukan. Tabel
berikut mencantumkan atribut yang diperlukan untuk kontrol akses masuk.
Untuk spesifikasi lengkapnya, lihat
AttributeContext
.
Atribut | Deskripsi | Contoh |
---|---|---|
origin.ip |
Alamat IP pemanggil. | "1.2.3.4" |
api.service |
Nama layanan API. | "endpointsapis.appspot.com" |
api.operation |
Nama metode API. | "google.example.hello.v1.HelloService.GetHello" |
api.version |
String versi API. | "v1" |
api.protocol |
Nama protokol API. | "https" |
request.id |
ID permintaan unik. | "123e4567-e89b-12d3-a456-426655440000" |
request.time |
Waktu permintaan. | "2019-07-31T05:20:00Z" |
request.method |
Nama metode HTTP. | "POST" |
request.scheme |
Skema URL. | "https" |
request.host |
Header host HTTP. | "endpointsapis.appspot.com" |
request.path |
Jalur URL. | "/v1/halo" |
request.headers |
Header permintaan HTTP. Header yang diperlukan adalah "authorization", "user-agent", "origin", "referer". | |
resource.name |
Nama resource target. | "projects/123/topics/news-feed" |
Atribut resource
Saat klien mengakses layanan, akses tersebut bisa melibatkan satu atau beberapa resource di dalam layanan, seperti membaca objek atau membuat instance VM. Layanan ini dapat menggunakan kontrol penerimaan Infrastruktur Layanan untuk kontrol akses pada resource, yang didukung oleh IAM dan Cloud Audit Logs. Jika layanan Anda tidak memerlukan kontrol akses, Anda dapat melewati bagian ini.
Untuk kontrol akses, layanan harus meneruskan atribut resource ke
metode services.check
bersama dengan atribut permintaan.
Tabel berikut menampilkan atribut resource yang diperlukan untuk kontrol akses.
Atribut | Deskripsi | Contoh |
---|---|---|
name |
Nama resource. | "projects/123/locations/global/instances/instance-1" |
type |
Jenis resource. Formatnya adalah "{service}/{Kind}". | "endpointsapis.appspot.com/Instance" |
permission |
Izin resource. Formatnya adalah "{service}/{jeniss}.{verb}". | "endpointsapis.appspot.com/instances.get" |
Untuk performa dan efisiensi, metode services.check
memungkinkan Anda
memeriksa beberapa izin pada satu resource dalam satu panggilan.
Melakukan kontrol akses masuk
Setelah Anda men-deploy konfigurasi layanan ke Service Management API dan layanan Anda siap melayani permintaan dari klien, Anda dapat mulai memanggil services.check
untuk layanan yang di-deploy. Anda harus
memanggil services.check
untuk melakukan kontrol akses masuk setiap kali layanan
Anda menerima permintaan.
Untuk bereksperimen dengan cepat dengan kontrol akses masuk, Anda dapat menggunakan perintah gcurl
untuk memanggil metode services.check
. Lihat Mulai Menggunakan Service Control API untuk langkah-langkah penyiapan awal.
Contoh berikut menunjukkan cara menggunakan perintah gcurl
untuk memanggil
services.check
melalui HTTP.
gcurl -d '{ "service_config_id": "latest", "attributes": { "origin": { "ip": "1.2.3.4" }, "api": { "service": "endpointsapis.appspot.com", "operation", "google.example.hello.v1.HelloService.GetHello", "version": "v1", "protocol": "https" } }, "request": { "id": "123e4567-e89b-12d3-a456-426655440000", "time": "2019-07-31T05:20:00Z", "scheme": "https", "host": "endpointsapis.appspot.com" "headers": { "authorization": "Bearer xxx", "user-agent": "curl/1.0" } }, "resources": [ ] }' https://servicecontrol.googleapis.com/v2/services/endpointsapis.appspot.com:check { }
Respons dari metode services.check
menunjukkan apakah kontrol
penerimaan telah berlalu. Jika lulus, respons harus kosong. Jika gagal, status
dalam respons akan berisi informasi error yang harus ditampilkan layanan ke klien. Layanan sering kali perlu menerjemahkan informasi
error ke dalam formatnya sendiri. Layanan ini juga dapat menggunakan informasi tersebut untuk tujuan logging dan pemantauan.
Untuk layanan produksi, Anda harus menggunakan salah satu library klien yang disediakan Google untuk memanggil Service Control API. Library tersebut memberikan kegunaan yang sangat baik dan menangani fungsi umum secara otomatis, seperti autentikasi. Untuk informasi selengkapnya, lihat Penjelasan Library Klien.