Dekorator

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

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

Menentukan API (@endpoints.api)

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

Argumen @endpoints.api Deskripsi Contoh
allowed_client_ids Diperlukan jika API Anda menggunakan autentikasi. Daftar client ID untuk klien yang diizinkan meminta token. Untuk informasi selengkapnya, lihat Client ID dan audiens yang diizinkan. allowed_client_ids=['1-web-apps.apps.googleusercontent.com','2-android-apps.apps.googleusercontent.com', endpoints.API_EXPLORER_CLIENT_ID]
api_key_required Opsional. Digunakan untuk membatasi akses ke permintaan yang menyediakan kunci API. api_key_required=True
audiences Diperlukan jika API Anda memerlukan autentikasi dan jika Anda mendukung klien Android. Untuk token ID Google, ini dapat berupa daftar client ID yang mewakili token yang diminta. Jika token diterbitkan oleh penyedia autentikasi pihak ketiga, seperti Auth0, ini perlu berupa pemetaan kamus dari nama penerbit auth ke daftar audiens. Untuk informasi selengkapnya, lihat Client ID dan audiens yang diizinkan. audiences=['1-web-apps.apps.googleusercontent.com'] atau audiences={"auth0": ["aud-1.auth0.com", "aud-2.auth0.com"]}
base_path Opsional. Digunakan untuk menyalurkan API Anda dari jalur yang ditentukan. Jika menentukan argumen ini, Anda juga harus mengubah bagian handlers dalam file app.yaml Anda. Lihat Menayangkan API dari jalur yang berbeda.
canonical_name Opsional. Digunakan untuk menentukan nama yang berbeda atau lebih mudah dibaca untuk API di library klien. Nama ini digunakan untuk membuat nama di library klien; API backend terus menggunakan nilai yang ditentukan di properti name.

Misalnya, jika API Anda menetapkan name ke dfaanalytics, Anda dapat menggunakan properti ini untuk menentukan nama kanonis DFA Group Analytics; class klien yang dihasilkan kemudian akan berisi nama DfaGroupAnalytics.

Anda harus menyertakan spasi yang relevan di antara nama seperti yang ditunjukkan; ini diganti dengan camel case yang sesuai.		 canonical_name='DFA Analytics'
description Deskripsi singkat tentang API. Bagian ini diekspos dalam layanan discovery untuk mendeskripsikan API Anda, dan dapat digunakan juga untuk membuat dokumentasi seperti yang dijelaskan dalam Membuat library klien. description='Sample API for a simple game'
documentation Opsional. URL tempat pengguna dapat menemukan dokumentasi tentang versi API ini. Hal ini akan muncul di sorotan "Pelajari Lebih Lanjut" API Explorer di bagian atas halaman API Explorer agar pengguna dapat mempelajari layanan Anda. documentation='http://link_to/docs'
hostname Nama host aplikasi App Engine Anda. Alat command line Frameworks Endpoint menggunakan nilai yang Anda tentukan di sini saat membuat dokumen Discovery atau dokumen OpenAPI. Jika tidak menentukan nama host di sini, Anda harus menentukan nama host di kolom application pada file app.yaml atau menentukan project ID saat men-deploy aplikasi App Engine. hostname='your_app_id.appspot.com'
issuers Opsional. Konfigurasi penerbit JWT kustom. Ini harus berupa pemetaan kamus dari nama penerbit ke objek endpoints.Issuer. issuers={"auth0": endpoints.Issuer("https://test.auth0.com", "https://test.auth0.com/.well-known/jwks.json")}
name Wajib. Nama API, yang digunakan sebagai awalan untuk semua metode dan jalur API. Nilai name:
  • Harus dimulai dengan huruf kecil.
  • Harus cocok dengan ekspresi reguler [a-z]+[A-Za-z0-9]; yaitu, sisa nama dapat terdiri dari huruf besar dan huruf kecil atau angka.
Untuk men-deploy beberapa API sebagai bagian dari satu layanan, semua nama API harus cocok dengan ekspresi reguler [a-z][a-z0-9]{0,39} yaitu, nama harus diawali dengan huruf kecil, karakter lainnya harus berupa huruf kecil atau angka, dan panjang maksimum adalah 40 karakter.		 name='yourApi' atau name='yourapi'
limit_definitions Opsional. Digunakan untuk menentukan kuota API Anda. Lihat limit_definitions untuk informasi selengkapnya.
owner_domain Opsional. Nama domain entity yang memiliki API. Digunakan bersama dengan owner_name untuk memberikan petunjuk pemberian nama library klien dengan benar saat dibuat untuk API ini. (Jalur paket adalah kebalikan dari owner_domain dan package_path jika disediakan. Defaultnya adalah menggunakan appid.apppost.com owner_domain='your-company.com'
owner_name Opsional. Nama entity yang memiliki API. Digunakan bersama dengan owner_domain untuk memberikan petunjuk pemberian nama library klien dengan benar saat dibuat untuk API ini. owner_name='Your-Company'
package_path Opsional. Digunakan untuk mencakup lebih lanjut "paket" yang dimiliki API ini, dengan nilai yang dipisahkan dengan / yang menentukan pengelompokan API yang logis.

Misalnya, menentukan cloud/platform menghasilkan jalur library klien yang ditetapkan ke cloud/platform/<ApiName> dan paket library klien ditetapkan ke cloud.plaform.<ApiName>.		 package_path='cloud/platform'
scopes Jika tidak diberikan, defaultnya adalah cakupan email (https://www.googleapis.com/auth/userinfo.email), yang diperlukan untuk OAuth. Anda dapat menggantinya untuk menentukan lebih banyak cakupan OAuth 2.0, jika diinginkan. Anda juga dapat mengganti cakupan yang ditentukan di sini untuk metode API tertentu dengan menentukan cakupan yang berbeda di dekorator @endpoints.method. Namun, jika Anda menentukan lebih dari satu cakupan, perhatikan bahwa pemeriksaan cakupan akan lulus jika token dibuat untuk salah satu cakupan yang ditentukan. Untuk mewajibkan beberapa cakupan, tentukan satu string dengan spasi di antara setiap cakupan. scopes=['ss0', 'ss1 and_ss2']
title Opsional. Teks yang ditampilkan di API Explorer sebagai judul API Anda, serta diekspos dalam penemuan dan layanan direktori. title='My Backend API'
version Wajib. Menentukan versi Cloud Endpoints Anda. Nilai ini muncul di jalur API Anda. Jika Anda menentukan string versi yang kompatibel dengan standar SemVer, hanya nomor versi utama yang muncul di jalur API saat Anda men-deploy API. Misalnya, API bernama echo dengan versi 2.1.0 akan memiliki jalur yang mirip dengan /echo/v2. Jika Anda mengupdate echo API ke versi 2.2.0 dan men-deploy perubahan yang kompatibel dengan versi lama, jalurnya tetap /echo/v2. Dengan begitu, Anda dapat memperbarui nomor versi API saat membuat perubahan yang kompatibel dengan versi lama tanpa merusak jalur yang ada untuk klien Anda. Namun, jika Anda mengupdate echo API ke versi 3.0.0 (karena Anda men-deploy perubahan yang dapat menyebabkan gangguan), jalurnya akan diubah menjadi /echo/v3. version='v1' atau version='2.1.0'

limit_definitions

Untuk menentukan quotas API, Anda menetapkan 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 dekorator metode untuk setiap metode yang ingin Anda terapkan kuotanya.

Lihat artikel Mengonfigurasi kuota untuk mengetahui semua langkah yang diperlukan dalam menyiapkan kuota.

Anda menentukan daftar satu atau beberapa instance LimitDefinition, seperti berikut:

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

Setiap instance LimitDefinition harus memiliki nilai berikut:

Elemen Deskripsi
name Nama untuk penghitung permintaan API. Biasanya, ini adalah jenis permintaan (misalnya, "read-requests" atau "write-requests") yang mengidentifikasi kuota secara unik.
Nama tampilan

Teks yang ditampilkan untuk mengidentifikasi kuota pada tab Quotas di halaman Endpoint > Services. Teks ini juga ditampilkan kepada konsumen API Anda di halaman Quotas di IAM & admin dan API & Services. Nama tampilan harus berisi maksimum 40 karakter.

Agar mudah dibaca, teks “per menit per project” akan otomatis ditambahkan ke nama tampilan di halaman Quotas. Agar konsisten dengan nama tampilan layanan Google yang tercantum di halaman Kuota yang dilihat konsumen API Anda, kami merekomendasikan hal berikut untuk nama tampilan:

  • Gunakan "Permintaan" jika Anda hanya memiliki satu metrik.
  • Jika Anda memiliki beberapa metrik, masing-masing metrik harus menjelaskan jenis permintaan dan berisi kata "permintaan" (misalnya, "Permintaan baca" atau "Permintaan tulis").
  • Gunakan "Unit kuota", bukan "Permintaan" jika biaya untuk kuota ini lebih besar dari 1.

batas Nilai bilangan bulat yang merupakan jumlah maksimum permintaan per menit per project konsumen untuk kuota.

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 ke client ID tertentu, yang berarti client ID ini dapat digunakan untuk membatasi akses ke API Anda. Saat mendaftarkan aplikasi Android di konsol Google Cloud, Anda membuat client ID untuk aplikasi tersebut. Client ID ini adalah ID yang meminta token OAuth2 dari Google untuk tujuan autentikasi. Jika API backend dilindungi oleh autentikasi, token akses OAuth2 akan dikirim dan dibuka oleh Framework Endpoint untuk App Engine, client ID diekstrak dari token, lalu ID tersebut dibandingkan dengan daftar client ID yang dapat diterima yang dideklarasikan backend (daftar allowed_client_ids).

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

Perhatikan bahwa dalam setiap metode API yang ingin diperiksa autentikasinya dengan benar, Anda harus memanggil endpoints.get_current_user(). Baca bagian Mengautentikasi pengguna untuk mengetahui informasi selengkapnya.

Jika Anda menggunakan argumen allowed_client_ids dan ingin menguji panggilan yang diautentikasi ke API dengan menggunakan API Explorer, Anda harus menyediakan 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 tetap dapat ditemukan secara publik dan dapat diakses secara publik di API Explorer.

Tentang audiens

Daftar allowed_client_ids melindungi API backend 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, tempat Anda menentukan client ID dari API backend.

Perlu diperhatikan bahwa saat Anda membuat project konsol Google Cloud, client ID default akan otomatis dibuat dan diberi nama agar dapat digunakan oleh project tersebut. Saat Anda mengupload API backend ke App Engine, API tersebut akan menggunakan client ID tersebut. Ini adalah client ID web yang disebutkan dalam auth API.

Penerbit token autentikasi pihak ketiga

Jika aplikasi Anda menerima token autentikasi yang bukan token ID Google dan diterbitkan oleh penerbit pihak ketiga, Anda harus menetapkan 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 suatu metode, menggunakan @endpoints.method. Jika setelan ini ditetapkan di level API dan level metode, setelan metode akan menggantikannya.

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

Argumen yang tersedia tercantum dalam tabel berikut:

@endpoints.method Argumen Deskripsi Contoh
allowed_client_ids Setelan ini mengganti atribut setara yang ditentukan di @endpoints.api. Untuk informasi selengkapnya, lihat Client ID dan audiens yang diizinkan. ['1-web-apps.apps.googleusercontent.com', '2-android-apps.apps.googleusercontent.com']
api_key_required Opsional. Digunakan untuk membatasi akses ke permintaan yang menyediakan kunci API. api_key_required=True
audiences Mengganti argumen setara yang ditentukan dalam @endpoints.api. Untuk informasi selengkapnya, lihat Client ID dan audiens yang diizinkan. ['1-web-apps.apps.googleusercontent.com']
metric_costs Opsional. Menunjukkan bahwa metode memiliki batas kuota. Ini adalah kamus dengan pasangan nilai kunci berikut:
  • name: Nama yang Anda tentukan dalam argumen limit_definitions ke dekorator API.
  • biaya: Bilangan bulat yang menentukan biaya untuk setiap permintaan. Biaya ini memungkinkan metode untuk menggunakan dengan tarif yang berbeda dari kuota yang sama. Misalnya, jika kuota memiliki batas 1.000 dan biaya 1, aplikasi panggilan dapat membuat 1.000 permintaan per menit sebelum melampaui batas. Dengan biaya 2 untuk kuota yang sama, aplikasi panggilan hanya dapat membuat 500 permintaan per menit sebelum melampaui batas.
 metric_costs={'read-requests': 1}
http_method Metode HTTP yang akan digunakan. Jika Anda tidak menetapkannya, 'POST' akan digunakan secara default. 'GET'
name Nama alternatif untuk metode ini. Nilai name:
  • Harus dimulai dengan huruf kecil.
  • Harus cocok dengan ekspresi reguler [a-z]+[A-Za-z0-9]*.
 'yourApi'
path Jalur URI untuk mengakses metode ini. Jika Anda tidak menyetelnya, nama metode Python akan digunakan. Jika Anda berencana untuk menambahkan pengelolaan API, jangan sertakan garis miring di jalur direktori. 'yourapi/path'
Class Request Message Class Request Message Google Protocol RPC yang akan digunakan di panggilan metode. Atau, Anda dapat memberikan nama class. YourRequestClass
Class Response Message Class Response Message Google Protocol RPC yang akan digunakan di panggilan metode. Atau, Anda dapat memberikan nama class. YourResponseClass

Menggunakan ResourceContainer untuk argumen jalur atau string kueri

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

  1. Tentukan class Message yang memiliki semua argumen yang diteruskan dalam 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 akan disediakan 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 yang diperlukan, permintaan klien harus menyertakannya dalam string kueri (misalnya, yourApi?times=2), atau jalur URL (misalnya, yourApi/2). Namun, agar API Anda menerima nilai argumen dengan menggunakan jalur URL, Anda juga harus menambahkan nama argumen ke jalur API seperti yang ditunjukkan untuk argumen {times} di path='yourApi/{times}.

Langkah selanjutnya