Dekorator

Decorator Cloud Endpoints Frameworks untuk Python menjelaskan konfigurasi API, metode, parameter, dan detail penting lainnya yang menentukan properti dan perilaku Endpoint.

Halaman ini menjelaskan decorator yang tersedia secara mendetail. Untuk mengetahui informasi tentang cara menggunakan dekorator untuk membuat API, lihat artikel berikut:

• Membuat API
• Membuat API yang diimplementasikan dengan beberapa kelas

Menentukan API (@endpoints.api)

Anda dapat memberikan beberapa argumen ke @endpoints.api untuk menentukan API Anda. Tabel berikut menjelaskan argumen yang tersedia:

limit_definitions

Untuk menentukan kuota untuk API, Anda menentukan argumen limit_definitions opsional ke @endpoints.api. Untuk mengonfigurasi kuota, Anda juga harus:

• Instal library Endpoints Frameworks versi 2.4.5 atau yang lebih baru.
• Tambahkan argumen metric_costs ke decorator metode untuk setiap metode yang ingin Anda terapkan kuotanya.

Lihat Mengonfigurasi kuota untuk semua langkah yang diperlukan untuk menyiapkan kuota.

Anda menentukan daftar satu atau beberapa instance LimitDefinition, mirip dengan berikut:

quota_limits = [
              endpoints.LimitDefinition(
                "name",
                "Display name",
                limit)
]

Setiap instance LimitDefinition harus memiliki nilai berikut:

Contoh

quota_limits = [
  endpoints.LimitDefinition('read-requests', 'Read Requests', 1000),
  endpoints.LimitDefinition('list-requests', 'List Requests', 100),
  endpoints.LimitDefinition('write-requests', 'Write Requests', 50)
]

@endpoints.api(name='bookstore',
               version='v1',
               limit_definitions=quota_limits)

Client ID dan audiens yang diizinkan

Untuk autentikasi OAuth2, token OAuth2 dikeluarkan untuk client ID tertentu, yang berarti bahwa client ID ini dapat digunakan untuk membatasi akses ke API Anda. Saat mendaftarkan aplikasi Android di konsol Google Cloud , Anda akan membuat ID klien untuk aplikasi tersebut. ID klien ini adalah ID yang meminta token OAuth2 dari Google untuk tujuan autentikasi. Saat API backend dilindungi oleh autentikasi, token akses OAuth2 akan dikirim dan dibuka oleh Endpoints Frameworks untuk App Engine, ID klien akan diekstrak dari token, lalu ID tersebut akan dibandingkan dengan daftar ID klien yang dapat diterima yang dideklarasikan backend (daftar allowed_client_ids).

Daftar allowed_client_ids harus terdiri dari semua ID klien yang telah Anda peroleh melalui Google Cloud console untuk web, Android, dan aplikasi klien lainnya. Artinya, klien harus diketahui pada waktu pembuatan API. Jika Anda menentukan daftar kosong, tidak ada klien yang dapat mengakses API.

Perhatikan bahwa di setiap metode API tempat Anda ingin memeriksa autentikasi yang tepat, Anda harus memanggil endpoints.get_current_user(). Lihat Mengautentikasi pengguna untuk mengetahui informasi selengkapnya.

Jika menggunakan argumen allowed_client_ids dan ingin menguji panggilan yang diautentikasi ke API menggunakan API Explorer, Anda harus memberikan client ID-nya dalam daftar allowed_client_ids dengan menentukan konstanta endpoints.API_EXPLORER_CLIENT_ID. Perhatikan bahwa jika allowed_client_ids hanya berisi endpoints.API_EXPLORER_CLIENT_ID, dan Anda men-deploy API, API Anda masih dapat ditemukan dan diakses secara publik di API Explorer.

Tentang audiens

Daftar allowed_client_ids melindungi backend API dari klien yang tidak sah. Namun, perlindungan lebih lanjut diperlukan untuk melindungi klien, sehingga token autentikasi mereka hanya berfungsi untuk API backend yang dimaksud. Untuk klien Android, mekanisme ini adalah argumen audiences, yang digunakan untuk menentukan client ID backend API.

Perhatikan bahwa saat Anda membuat project konsol Google Cloud , ID klien default akan dibuat dan diberi nama secara otomatis untuk digunakan oleh project. Saat Anda mengupload backend API ke App Engine, API tersebut menggunakan client ID tersebut. Ini adalah client ID web yang disebutkan dalam autentikasi API.

Penerbit token autentikasi pihak ketiga

Jika aplikasi Anda menerima token autentikasi yang bukan token ID Google dan dikeluarkan oleh penerbit pihak ketiga, Anda harus menyetel argumen audiences dan issuers dengan benar di @endpoints.api untuk memberikan informasi tentang penerbit pihak ketiga. Contoh:

@endpoints.api(
        audiences={'auth0': ['aud-1.auth0.com', 'aud-2.auth0.com']},
        issuers={'auth0': endpoints.Issuer('https://test.auth0.com',
                                           'https://test.auth0.com/.well-known/jwks.json')})
class GreetingApi(remote.Service):

Menentukan metode API (@endpoints.method)

Anda dapat menetapkan setelan audiences, scopes, dan allowed_client_ids untuk seluruh API menggunakan @endpoints.api, atau untuk metode, menggunakan @endpoints.method. Jika setelan ini ditentukan di tingkat API dan metode, setelan metode akan menggantikan.

Untuk membuat metode di API, hiasi metode Python yang sesuai dengan @endpoints.method, dengan memberikan argumen untuk mengonfigurasi penggunaan metode. Misalnya, Anda menentukan class Message permintaan dan respons yang akan digunakan.

Argumen yang tersedia tercantum dalam tabel berikut:

Menggunakan ResourceContainer untuk argumen string kueri atau jalur

Jika permintaan berisi argumen string kueri atau jalur, Anda tidak dapat menggunakan class Message sederhana seperti yang dijelaskan dalam Buat API. Sebagai gantinya, Anda harus menggunakan class ResourceContainer, seperti berikut:

1. Tentukan class Message yang memiliki semua argumen yang diteruskan di isi permintaan. Jika tidak ada argumen dalam isi permintaan, Anda tidak perlu menentukan class Message: cukup gunakan message_types.VoidMessage.) Misalnya:

   class Greeting(messages.Message):
       """Greeting that stores a message."""
   
       message = messages.StringField(1)

2. Tentukan ResourceContainer dengan class Message yang Anda tentukan di langkah sebelumnya sebagai parameter pertama. Tentukan argumen jalur dan string kueri dalam parameter berikutnya. Contoh:

   MULTIPLY_RESOURCE = endpoints.ResourceContainer(
       Greeting,
       times=messages.IntegerField(2, variant=messages.Variant.INT32, required=True),

   dengan argumen pertama adalah class Message untuk data dalam isi permintaan dan times adalah angka yang diharapkan dalam jalur atau string kueri yang menyertai permintaan.

3. Berikan ResourceContainer ke metode yang menangani permintaan, di parameter pertama yang menggantikan class Message permintaan yang seharusnya diberikan di lokasi tersebut. Cuplikan ini menampilkan ResourceContainer dan endpoints.method:

   # This ResourceContainer is similar to the one used for get_greeting, but
   # this one also contains a request body in the form of a Greeting message.
   MULTIPLY_RESOURCE = endpoints.ResourceContainer(
       Greeting,
       times=messages.IntegerField(2, variant=messages.Variant.INT32, required=True),
   )
   
   @endpoints.method(
       # This method accepts a request body containing a Greeting message
       # and a URL parameter specifying how many times to multiply the
       # message.
       MULTIPLY_RESOURCE,
       # This method returns a Greeting message.
       Greeting,
       path="greetings/multiply/{times}",
       http_method="POST",
       name="greetings.multiply",
   )
   def multiply_greeting(self, request):
       return Greeting(message=request.message * request.times)
   

4. Tambahkan parameter path seperti yang ditunjukkan, untuk menyertakan API Anda.

5. Jika ResourceContainer Anda memiliki argumen wajib, permintaan klien harus menyertakannya dalam string kueri (misalnya, yourApi?times=2), atau jalur URL (misalnya, yourApi/2). Namun, agar API Anda menerima nilai argumen menggunakan jalur URL, Anda juga harus menambahkan nama argumen ke jalur API seperti yang ditunjukkan untuk argumen {times} di path='yourApi/{times}.

Langkah berikutnya

• Membuat API
• Membuat API yang diimplementasikan dengan beberapa kelas