Dekorator

Dekorator Cloud Endpoints Frameworks untuk 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 untuk membuat API, lihat hal berikut:

Menentukan API (@endpoints.api)

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

Argumen @endpoints.api Deskripsi Contoh
allowed_client_ids Wajib jika API Anda menggunakan autentikasi. Daftar client ID untuk klien yang diizinkan meminta token. Untuk mengetahui 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 Wajib jika API Anda memerlukan autentikasi dan jika Anda mendukung klien Android. Untuk token ID Google, ini dapat berupa daftar client ID yang tokennya diminta. Jika token dikeluarkan oleh penyedia autentikasi pihak ketiga, seperti Auth0, ini harus berupa kamus yang memetakan dari nama penerbit autentikasi ke daftar audiens. Untuk mengetahui 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 menayangkan API Anda dari jalur yang ditentukan. Jika Anda menentukan argumen ini, Anda juga harus mengubah bagian handlers di file app.yaml. 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 dalam properti name.

Misalnya, jika API Anda memiliki name yang ditetapkan ke dfaanalytics, Anda dapat menggunakan properti ini untuk menentukan nama kanonis DFA Group Analytics; class klien yang dibuat kemudian akan berisi nama DfaGroupAnalytics.{1!}{1!}Anda harus menyertakan spasi yang relevan di antara nama seperti yang ditunjukkan; spasi ini diganti dengan camel casing atau garis bawah yang sesuai.

 canonical_name='DFA Analytics'
description Deskripsi singkat API. Deskripsi ini ditampilkan di layanan penemuan untuk menjelaskan API Anda, dan mungkin juga digunakan secara opsional 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. URL ini ditampilkan di API Explorer "Learn More" di bagian atas halaman API Explorer untuk memungkinkan pengguna mempelajari layanan Anda. documentation='http://link_to/docs'
hostname Nama host aplikasi App Engine Anda. Alat command line Endpoints Frameworks menggunakan nilai yang Anda tentukan di sini saat membuat dokumen discovery atau dokumen OpenAPI. Jika Anda tidak menentukan nama host di sini, Anda harus menentukan nama host di kolom application pada file app.yaml atau menentukan project ID saat Anda men-deploy aplikasi App Engine. hostname='your_app_id.appspot.com'
issuers Opsional. Konfigurasi penerbit JWT kustom. Ini harus berupa kamus yang memetakan 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 diisi. 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, bagian nama lainnya dapat terdiri dari huruf besar dan 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 dimulai dengan huruf kecil, karakter lainnya harus berupa huruf kecil atau angka, dan panjang maksimumnya adalah 40 karakter.		 name='yourApi' atau name='yourapi'
limit_definitions Opsional. Digunakan untuk menentukan kuota untuk API Anda. Lihat limit_definitions untuk mengetahui informasi selengkapnya.
owner_domain Opsional. Nama domain entitas yang memiliki API. Digunakan bersama dengan owner_name untuk memberikan petunjuk guna memberi nama library klien dengan benar saat dibuat untuk API ini. (Jalur paket adalah kebalikan dari owner_domain dan package_path jika disediakan. Setelan defaultnya adalah menggunakan appid.apppost.com owner_domain='your-company.com'
owner_name Opsional. Nama entitas yang memiliki API. Digunakan bersama dengan owner_domain untuk memberikan petunjuk guna memberi nama library klien dengan benar saat dibuat untuk API ini. owner_name='Your-Company'
package_path Opsional. Digunakan untuk menentukan cakupan lebih lanjut "paket" yang dimiliki API ini, dengan nilai yang dipisahkan oleh / yang menentukan pengelompokan logis API.

Misalnya, menentukan cloud/platform akan menghasilkan jalur library klien yang ditetapkan ke cloud/platform/<ApiName> dan paket library klien yang ditetapkan ke cloud.plaform.<ApiName>.		 package_path='cloud/platform'
scopes Jika tidak disediakan, setelan defaultnya adalah cakupan email (https://www.googleapis.com/auth/userinfo.email), yang diperlukan untuk OAuth. Anda dapat mengganti setelan ini untuk menentukan lebih banyak cakupan OAuth 2.0 jika Anda mau. 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, dan ditampilkan di layanan penemuan dan direktori. title='My Backend API'
version Wajib diisi. 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 akan muncul di jalur API Anda saat Anda men-deploy API. Misalnya, API yang disebut 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, jalur akan tetap /echo/v2. Hal ini memungkinkan Anda memperbarui nomor versi API saat Anda 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), jalur akan diubah menjadi /echo/v3. version='v1' atau version='2.1.0'

limit_definitions

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

  • Menginstal library Endpoints Frameworks versi 2.4.5 atau yang lebih baru.
  • Menambahkan argumen metric_costs ke dekorator metode untuk setiap metode yang ingin Anda terapkan kuotanya.

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

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

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

Setiap instance LimitDefinition harus memiliki nilai berikut:

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

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

Untuk tujuan keterbacaan, teks “per minute per project” secara otomatis ditambahkan ke nama tampilan di halaman Quotas. Untuk mempertahankan konsistensi dengan nama tampilan layanan Google yang tercantum di halaman Quotas yang dilihat oleh konsumen API Anda, sebaiknya gunakan hal berikut untuk nama tampilan:

  • Gunakan "Requests" jika Anda hanya memiliki satu metrik.
  • Jika Anda memiliki beberapa metrik, setiap metrik harus menjelaskan jenis permintaan dan berisi kata “requests” (misalnya, “Read requests” atau “Write requests”).
  • Gunakan "Quota units", bukan "Requests" jika salah satu 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 Anda mendaftarkan aplikasi Android di Google Cloud konsol, Anda akan membuat client ID untuk aplikasi tersebut. Client ID ini adalah client 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, client ID akan diekstrak dari token, lalu ID akan 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 aplikasi web, Android, dan klien lainnya. Artinya, klien harus diketahui pada waktu build 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 Anda menggunakan argumen allowed_client_ids dan ingin menguji panggilan yang diautentikasi ke API Anda 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 secara publik dan dapat diakses secara publik di API Explorer.

Tentang audiens

Daftar allowed_client_ids melindungi API backend dari klien yang tidak diotorisasi. 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 API backend.

Perhatikan bahwa saat Anda membuat Google Cloud project konsol, client ID default akan otomatis dibuat dan diberi nama untuk digunakan oleh project. Saat Anda mengupload API backend ke App Engine, API tersebut akan menggunakan client ID tersebut. Ini adalah web client ID 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 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 metode, menggunakan @endpoints.method. Jika setelan ini ditentukan di tingkat API dan metode, setelan metode akan menggantikannya.

Untuk membuat metode di API Anda, beri dekorasi 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:

Argumen @endpoints.method Deskripsi Contoh
allowed_client_ids Setelan ini menggantikan atribut yang setara yang ditentukan di @endpoints.api. Untuk mengetahui 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 Menggantikan argumen yang setara yang ditentukan di @endpoints.api. Untuk mengetahui 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.
  • cost: Bilangan bulat yang menentukan biaya untuk setiap permintaan. Biaya memungkinkan metode menggunakan kuota yang sama dengan tarif yang berbeda. Misalnya, jika kuota memiliki batas 1.000 dan biaya 1, aplikasi panggilan dapat membuat 1.000 permintaan per menit sebelum melebihi batas. Dengan biaya 2 untuk kuota yang sama, aplikasi panggilan hanya dapat membuat 500 permintaan per menit sebelum melebihi batas.
 metric_costs={'read-requests': 1}
http_method Metode HTTP yang akan digunakan. Jika Anda tidak menetapkan metode HTTP, '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 menetapkan jalur URI, nama metode Python akan digunakan. Jika Anda berencana untuk menambahkan pengelolaan API, jangan sertakan garis miring di akhir jalur. 'yourapi/path'
Class Request Message Class Google Protocol RPC Request Message yang akan digunakan dalam panggilan metode. Atau, Anda dapat memberikan nama class. YourRequestClass
Class Response Message Class Google Protocol RPC Response Message yang akan digunakan dalam 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 sederhana Message seperti yang dijelaskan dalam Membuat API. Sebagai gantinya, Anda harus menggunakan class ResourceContainer, sebagai 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.) Contoh:

    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 di 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 diberikan di lokasi tersebut. Cuplikan ini menunjukkan 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 menggunakan jalur URL, Anda juga harus menambahkan nama argumen ke jalur API seperti yang ditunjukkan untuk argumen {times} di path='yourApi/{times}.

Langkah berikutnya