Kontrol Penerimaan

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.

Catatan: Untuk terminologi yang digunakan di halaman ini, lihat Glosarium API.

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
  • Identity and Access Management (IAM)
• 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.