Dekorator

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

Halaman ini menjelaskan dekorator yang tersedia secara mendetail. Untuk informasi tentang penggunaan 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, token ini harus berupa pemetaan kamus 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 menentukan argumen ini, Anda juga harus mengubah bagian handlers dalam 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 akan 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 dihasilkan kemudian akan berisi nama DfaGroupAnalytics.

Anda harus menyertakan spasi yang relevan di antara nama seperti yang ditunjukkan; spasi ini akan diganti dengan casing camel atau garis bawah yang sesuai.		 canonical_name='DFA Analytics'
description Deskripsi singkat API. Hal ini ditampilkan di layanan penemuan untuk mendeskripsikan API Anda, dan secara opsional juga dapat digunakan 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 ditampilkan di sorotan "Pelajari Lebih Lanjut" API Explorer 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 tidak menentukan nama host di sini, Anda harus menentukan nama host di kolom application file app.yaml atau menentukan ID project 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 diawali dengan huruf kecil.
  • Harus cocok dengan ekspresi reguler [a-z]+[A-Za-z0-9]; yaitu, 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 diawali 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 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. 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 "paket" yang menjadi bagian dari API ini, dengan nilai yang dipisahkan oleh / yang menentukan pengelompokan API yang logis.

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 diberikan, default-nya 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 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. 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 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 sebelumnya, jalurnya tetap /echo/v2. Hal ini memungkinkan Anda 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 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 mengetahui 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:

Elemen Deskripsi
nama Nama untuk penghitung permintaan API. Biasanya, ini adalah jenis permintaan (misalnya, “permintaan baca” atau “permintaan tulis”) yang mengidentifikasi kuota secara unik.
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 Kuota di IAM & admin serta API & Layanan. Nama tampilan harus berisi maksimal 40 karakter.

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

  • Gunakan "Permintaan" jika Anda hanya memiliki satu metrik.
  • Jika Anda memiliki beberapa metrik, setiap metrik harus menjelaskan jenis permintaan dan berisi kata “permintaan” (misalnya “Permintaan baca” atau “Permintaan tulis”).
  • Gunakan "Unit kuota", bukan "Permintaan" 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 mendaftarkan aplikasi Android di konsol Google Cloud, Anda akan membuat client ID untuk aplikasi tersebut. Client ID ini adalah yang meminta token OAuth2 dari Google untuk tujuan autentikasi. Saat API backend dilindungi oleh autentikasi, token akses OAuth2 dikirim dan dibuka oleh Framework Endpoints untuk App Engine, client ID diekstrak dari token, lalu ID 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 telah Anda peroleh melalui konsol Google Cloud 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 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 secara publik dan dapat diakses secara publik di API Explorer.

Tentang audiens

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

Perhatikan bahwa saat Anda membuat project konsol Google Cloud, 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 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 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 metode, menggunakan @endpoints.method. Jika setelan ini ditentukan di API dan level metode, setelan metode akan menggantikannya.

Untuk membuat metode di API, hiasi 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:

Argumen @endpoints.method Deskripsi Contoh
allowed_client_ids Setelan ini mengganti 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 Mengganti argumen yang setara yang ditentukan dalam @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 ini memungkinkan metode 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 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 menetapkannya, 'POST' akan digunakan secara default. 'GET'
name Nama alternatif untuk metode ini. Nilai name:
  • Harus diawali 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 menetapkannya, 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 Request Message RPC Protokol Google yang akan digunakan dalam panggilan metode. Atau, Anda dapat memberikan nama class. YourRequestClass
Class Response Message Class Response Message RPC Protokol Google yang akan digunakan dalam panggilan metode. Atau, Anda dapat memberikan nama class. YourResponseClass

Menggunakan ResourceContainer untuk argumen string kueri atau jalur

Jika permintaan berisi argumen string jalur atau kueri, Anda tidak dapat menggunakan class Message sederhana 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.) 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 string kueri dan jalur 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, dalam 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 ditampilkan, 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 selanjutnya