Halaman ini menunjukkan cara mengonfigurasi, men-deploy, dan mengirim permintaan ke API contoh menggunakan Framework Cloud Endpoints untuk Python. Framework Endpoint untuk Python terintegrasi dengan lingkungan runtime Python 2.7 standar App Engine. Framework Endpoint terdiri dari alat, library, dan kemampuan yang memungkinkan Anda membuat API dan library klien dari aplikasi App Engine.
Tujuan
Gunakan daftar tugas tingkat tinggi berikut saat Anda mengerjakan tutorial. Semua tugas diperlukan agar berhasil mengirim permintaan ke API.
- Menyiapkan project Google Cloud. Lihat Sebelum memulai.
- Instal software yang diperlukan dan buat aplikasi App Engine. Lihat Menginstal dan mengonfigurasi software yang diperlukan.
- Download kode contoh. Lihat Mendapatkan kode contoh.
- Buat dokumen OpenAPI. Lihat Mengonfigurasi Endpoint.
- Deploy konfigurasi Endpoint untuk membuat layanan Endpoint. Lihat Men-deploy konfigurasi Endpoint.
- Jalankan contoh di komputer. Lihat Menjalankan sampel secara lokal.
- Membuat backend untuk menyalurkan API dan men-deploy API. Lihat Men-deploy backend API.
- Mengirim permintaan ke API. Lihat Mengirim permintaan ke API.
- Melacak aktivitas API. Lihat Aktivitas API pelacakan.
- Menghindari timbulnya tagihan ke akun Google Cloud Anda. Lihat Pembersihan.
Biaya
Dalam dokumen ini, Anda menggunakan komponen Google Cloud yang dapat ditagih berikut:
Untuk membuat perkiraan biaya berdasarkan proyeksi penggunaan Anda,
gunakan kalkulator harga.
Setelah menyelesaikan tugas yang dijelaskan dalam dokumen ini, Anda dapat menghindari penagihan berkelanjutan dengan menghapus resource yang Anda buat. Untuk mengetahui informasi selengkapnya, lihat Pembersihan.
Sebelum memulai
- Login ke akun Google Cloud Anda. Jika Anda baru menggunakan Google Cloud, buat akun untuk mengevaluasi performa produk kami dalam skenario dunia nyata. Pelanggan baru juga mendapatkan kredit gratis senilai $300 untuk menjalankan, menguji, dan men-deploy workload.
-
Di konsol Google Cloud, pada halaman pemilih project, pilih atau buat project Google Cloud.
-
Pastikan penagihan telah diaktifkan untuk project Google Cloud Anda.
-
Di konsol Google Cloud, pada halaman pemilih project, pilih atau buat project Google Cloud.
-
Pastikan penagihan telah diaktifkan untuk project Google Cloud Anda.
- Catat ID project Google Cloud karena akan diperlukan nanti.
Menginstal dan mengonfigurasi software yang diperlukan
- Ikuti petunjuk dalam artikel Menginstal Google Cloud CLI untuk Python untuk menyiapkan lingkungan pengembangan standar App Engine. Pastikan Anda menginstal komponen
gcloud
app-engine-python
danapp-engine-python-extras
. - Jalankan perintah berikut:
-
Mengupdate gcloud CLI.
gcloud components update
-
Pastikan Google Cloud CLI (
gcloud
) diberi otorisasi untuk mengakses data dan layanan Anda di Google Cloud:gcloud auth login
- Di tab browser baru yang terbuka, pilih akun.
-
Tetapkan project default ke project ID Anda.
gcloud config set project [YOUR_PROJECT_ID]
Ganti
[YOUR_PROJECT_ID]
dengan project ID Google Cloud Anda. Jika Anda memiliki project Google Cloud lain, dan ingin menggunakangcloud
untuk mengelolanya, lihat Mengelola konfigurasi gcloud CLI.
-
Mengupdate gcloud CLI.
-
Anda memerlukan aplikasi untuk mengirim permintaan ke API contoh.
- Pengguna Linux dan macOS: Tutorial ini memberikan contoh penggunaan
curl
, yang biasanya telah diinstal sebelumnya di sistem operasi Anda. Jika tidak memilikicurl
, Anda dapat mendownloadnya daricurl
Halaman rilis dan download. - Pengguna Windows: Tutorial ini memberikan contoh menggunakan
Invoke-WebRequest
, yang didukung di PowerShell 3.0 dan yang lebih baru.
- Pengguna Linux dan macOS: Tutorial ini memberikan contoh penggunaan
- Pastikan lingkungan pengembangan Python Anda menyertakan pip.
- Pastikan Anda dapat mengompilasi ekstensi C untuk Python.
- Windows: Perlu Microsoft Visual C++ 9.0 atau yang lebih baru. Anda dapat mendownload Microsoft Visual C++ Compiler untuk Python 2.7 dari Pusat Download Microsoft .
- Sistem operasi lain: Bergantung pada sistem operasi Anda, Anda mungkin perlu
menginstal alat compiler (terkadang dalam paket yang disebut
build-essential
) atau header pengembangan Python (terkadang dalam paket yang disebutpython-dev
).
-
Untuk Linux, tetapkan variabel lingkungan
ENDPOINTS_GAE_SDK
ke jalur folder App Engine SDK Anda:[Path-to-Google-Cloud-SDK]/platform/google_appengine
.Ganti
[Path-to-Google-Cloud-SDK]
dengan output perintah berikut:gcloud info --format="value(installation.sdk_root)"
- Buat aplikasi App Engine:
- Pilih region tempat Anda ingin membuat aplikasi App Engine. Jalankan perintah berikut untuk mendapatkan daftar region:
gcloud app regions list
- Buat aplikasi App Engine menggunakan perintah berikut.
Ganti
[YOUR_PROJECT_ID]
dengan project ID Google Cloud Anda dan[YOUR_REGION]
dengan region tempat Anda ingin membuat aplikasi App Engine.gcloud app create \ --project=[YOUR_PROJECT_ID] \ --region=[YOUR_REGION]
Contoh:
gcloud app create --project=example-project-12345 --region=us-central
- Pilih region tempat Anda ingin membuat aplikasi App Engine. Jalankan perintah berikut untuk mendapatkan daftar region:
Mendapatkan kode contoh
Untuk meng-clone API contoh dari GitHub:
Clone repositori contoh ke komputer lokal Anda:
git clone https://github.com/GoogleCloudPlatform/python-docs-samples
Ubah ke direktori yang berisi kode contoh:
cd python-docs-samples/appengine/standard/endpoints-frameworks-v2/echo
Mengonfigurasi Endpoint
Untuk mengonfigurasi Endpoint, Anda harus menginstal library Python Endpoint Frameworks terlebih dahulu. Selanjutnya, Anda akan menggunakan alat dari library Framework Endpoint untuk membuat dokumen OpenAPI untuk contoh API. Anda memerlukan library Endpoints Frameworks dan dokumen OpenAPI agar Endpoint dapat mengelola API. Untuk mengetahui informasi selengkapnya, lihat Menambahkan pengelolaan API.
Menginstal library Endpoints Frameworks
Bagian ini akan memandu Anda menggunakan pip
Python untuk menambahkan library Framework Endpoint ke direktori project API contoh.
Untuk menambahkan library Endpoints Frameworks ke contoh:
Pastikan Anda berada di direktori utama API contoh,
python-docs-samples/appengine/standard/endpoints-frameworks-v2/echo
.Buat subdirektori
/lib
dalam project:mkdir lib
Dari contoh direktori utama
python-docs-samples/appengine/standard/endpoints-frameworks-v2/echo
, jalankan perintah instal:pip install --target lib --requirement requirements.txt --ignore-installed
Perhatikan hal-hal berikut:
Perintah
pip
ini dapat menggunakan GNU Compiler Collection (GCC) untuk mengompilasi modul ekstensi. Jika menggunakan macOS dan ini adalah pertama kalinya Anda menjalankan GCC di sistem, Anda mungkin harus menerima lisensi XCode Apple. Untuk melakukannya, jalankansudo xcodebuild -license
.Jika Anda memiliki beberapa versi Python yang terinstal di komputer, pastikan Anda menggunakan versi
pip
yang sesuai dengan versi Python yang Anda gunakan dalam tutorial ini. Ketidakcocokan versi (misalnyapip
dari Python 3.4 saat menggunakanpython
dari Python 2.7) dapat menyebabkan error yang mungkin sulit dipahami. Jika perlu, Anda dapat menjalankan pip sebagai modul Python: gantipip
dalam perintah sebelumnya denganpython -m pip
.Jika
pip
tidak dapat menemukan paket yang sesuai saat menjalankan perintah, coba upgrade dengan menjalankanpip install --upgrade pip
. Setelah upgrade selesai, coba perintah penginstalan lagi.Pada beberapa rilis Debian dan Ubuntu,
pip
mungkin gagal dengan DistutilsOptionError. Jika Anda melihat {i>error<i} tersebut, tambahkan flag --system.
Setelah berhasil, direktori lib
akan diisi dengan file yang diperlukan untuk mem-build aplikasi Framework Endpoint.
Membuat dokumen OpenAPI
Anda dapat menggunakan alat dari library Endpoints Frameworks untuk membuat dokumen yang menjelaskan REST API kode contoh.
Untuk membuat dokumen OpenAPI:
Pastikan Anda berada di direktori utama contoh:
python-docs-samples/appengine/standard/endpoints-frameworks-v2/echo
Buat dokumen OpenAPI:
python lib/endpoints/endpointscfg.py get_openapi_spec main.EchoApi --hostname [YOUR_PROJECT_ID].appspot.com
Ganti
[YOUR_PROJECT_ID]
dengan ID project Google Cloud Anda. Abaikan peringatan yang ditampilkan. Alat Endpoint menghasilkan dokumen OpenAPI yang disebutechov1openapi.json
di direktori saat ini. Alat Endpoint memberi nama file berdasarkan nama dan versi layanan yang ditentukan di dekorator@endpoints.api
. Lihat Membuat API untuk informasi selengkapnya.Endpoint menggunakan teks yang ditentukan dalam argumen
hostname
sebagai nama layanan. Format namaYOUR_PROJECT_ID.appspot.com
cocok dengan entri DNS yang dibuat secara otomatis saat Anda men-deploy API ke backend App Engine. Jadi, dalam hal ini, nama layanan Endpoint dan nama domain yang sepenuhnya memenuhi syarat (FQDN) adalah sama.
Setelah berhasil diselesaikan, pesan berikut akan ditampilkan:
OpenAPI spec written to ./echov1openapi.json
Men-deploy konfigurasi Endpoint
Untuk men-deploy konfigurasi Endpoint, gunakan Infrastruktur Layanan, platform layanan dasar Google, yang digunakan oleh Endpoint dan layanan lainnya untuk membuat serta mengelola API dan layanan.
Untuk men-deploy file konfigurasi:
- Pastikan Anda berada di direktori utama contoh:
python-docs-samples/appengine/standard/endpoints-frameworks-v2/echo
- Deploy dokumen OpenAPI yang telah dihasilkan di bagian sebelumnya dengan menjalankan perintah berikut:
gcloud endpoints services deploy echov1openapi.json
Tindakan ini akan membuat layanan Endpoint baru dengan nama yang Anda tentukan dalam argumen
hostname
saat menjalankan alat Endpoint untuk membuat dokumen OpenAPI. Apa pun nama layanan Endpoints, saat Anda men-deploy API di App Engine, data DNS akan dibuat menggunakan format namaYOUR_PROJECT_ID.appspot.com
, yaitu FQDN yang Anda gunakan saat mengirim permintaan ke API.Saat membuat dan mengonfigurasi layanan, Pengelolaan Layanan menghasilkan banyak informasi ke terminal. Anda dapat mengabaikan peringatan tentang jalur di
echov1openapi.json
yang tidak memerlukan kunci API dengan aman. Setelah deployment selesai, akan muncul pesan yang mirip dengan yang berikut ini:Service Configuration [2017-02-13r2] uploaded for service [example-project-12345.appspot.com]
Pada contoh sebelumnya,
2017-02-13-r2
adalah ID konfigurasi layanan danexample-project-12345.appspot.com
adalah nama layanan.Lihat
gcloud endpoints services deploy
dalam dokumentasi referensigcloud
untuk informasi selengkapnya.
Memeriksa layanan yang diperlukan
Untuk menyediakan pengelolaan API, Framework Endpoint memerlukan layanan berikut:Nama | Judul |
---|---|
servicemanagement.googleapis.com |
Service Management API |
servicecontrol.googleapis.com |
Service Control API |
endpoints.googleapis.com |
Endpoint Google Cloud |
Dalam sebagian besar kasus, perintah gcloud endpoints services deploy
akan mengaktifkan
layanan yang diperlukan ini. Namun, perintah gcloud
berhasil diselesaikan, tetapi
tidak mengaktifkan layanan yang diperlukan dalam keadaan berikut:
Jika Anda menggunakan aplikasi pihak ketiga seperti Terraform, dan Anda tidak menyertakan layanan ini.
Anda telah men-deploy konfigurasi Endpoint ke project Google Cloud yang ada, tempat layanan ini dinonaktifkan secara eksplisit.
Gunakan perintah berikut untuk mengonfirmasi bahwa layanan yang diperlukan telah diaktifkan:
gcloud services list
Jika Anda tidak melihat layanan yang diperlukan tercantum, aktifkan layanan tersebut:
gcloud services enable servicemanagement.googleapis.comgcloud services enable servicecontrol.googleapis.com
gcloud services enable endpoints.googleapis.com
Aktifkan juga layanan Endpoint Anda:
gcloud services enable ENDPOINTS_SERVICE_NAME
Untuk menentukan ENDPOINTS_SERVICE_NAME, Anda dapat:
Setelah men-deploy konfigurasi Endpoint, buka halaman Endpoint di Konsol Cloud. Daftar kemungkinan ENDPOINTS_SERVICE_NAME ditampilkan di bawah kolom Nama layanan.
Untuk OpenAPI, ENDPOINTS_SERVICE_NAME adalah nilai yang Anda tentukan dalam kolom
host
pada spesifikasi OpenAPI. Untuk gRPC, ENDPOINTS_SERVICE_NAME adalah nilai yang Anda tentukan di kolomname
pada konfigurasi Endpoint gRPC Anda.
Untuk mengetahui informasi selengkapnya tentang perintah gcloud
, lihat
layanan gcloud
.
Menjalankan contoh secara lokal
Setelah men-deploy konfigurasi Endpoint, Anda dapat menjalankan contoh secara lokal menggunakan Server pengembangan lokal.
Pastikan Anda berada di direktori utama contoh:
python-docs-samples/appengine/standard/endpoints-frameworks-v2/echo
Mulai server pengembangan lokal:
dev_appserver.py ./app.yaml
Secara default, server pengembangan memproses
http://localhost:8080
, seperti yang ditunjukkan dalam log Konsol Google Cloud yang dicetak olehdev_appserver.py
:INFO 2018-01-01 [...] Starting module "default" running at: http://localhost:8080
Kirim permintaan ke server pengembangan lokal:
Linux atau Mac OS
curl \
--request POST \
--header "Content-Type: application/json" \
--data '{"message":"hello world"}' \
http://localhost:8080/_ah/api/echo/v1/echo
Dalam curl
sebelumnya:
- Opsi
--data
menentukan data yang akan diposting ke API. - Opsi
--header
menentukan bahwa data dalam format JSON.
PowerShell
(Invoke-WebRequest -Method POST -Body '{"message": "hello world"}' `
-Headers @{"content-type"="application/json"} `
-URI "http://localhost:8080/_ah/api/echo/v1/echo").Content
Pada contoh sebelumnya, dua baris pertama diakhiri dengan {i>backtick<i}. Saat Anda menempelkan contoh ke PowerShell, pastikan tidak ada spasi setelah tanda kutip terbalik. Untuk informasi tentang opsi yang digunakan dalam contoh permintaan, lihat Invoke-WebRequest dalam dokumentasi Microsoft.
API akan menggemakan kembali pesan yang Anda kirimkan, dan merespons dengan hal berikut:
{
"message": "hello world"
}
Men-deploy backend API
Sejauh ini Anda telah men-deploy dokumen OpenAPI ke Pengelolaan Layanan, tetapi belum men-deploy kode yang menayangkan backend API. Bagian ini akan memandu Anda dalam men-deploy contoh API ke App Engine.
Untuk men-deploy backend API:
- Tampilkan ID konfigurasi layanan dengan menjalankan perintah berikut:
gcloud endpoints configs list --service=[YOUR_PROJECT_ID].appspot.com
Ganti
[YOUR_PROJECT_ID]
dengan project ID Anda. Contoh:gcloud endpoints configs list --service=example-project-12345.appspot.com
- Buka file
app.yaml
di direktoripython-docs-samples/appengine/standard/endpoints-frameworks-v2/echo
. - Buat perubahan berikut di bagian
env_variables
:- Di kolom
ENDPOINTS_SERVICE_NAME
, gantiYOUR-PROJECT-ID
dengan project ID Google Cloud Anda. - Di kolom
ENDPOINTS_SERVICE_VERSION
, ganti teks dengan ID konfigurasi layanan. Contoh:
ENDPOINTS_SERVICE_NAME: example-project-12345.appspot.com ENDPOINTS_SERVICE_VERSION: 2017-02-13r2
- Di kolom
- Jalankan perintah berikut:
gcloud app deploy
- Ikuti petunjuk di layar. Tunggu beberapa saat sampai deployment berhasil, abaikan pesan peringatan. Setelah deployment selesai, akan muncul pesan yang mirip dengan berikut ini:
File upload done. Updating service [default]...done.
Jika Anda mendapatkan pesan error, lihat bagian Pemecahan masalah di dokumentasi App Engine untuk mendapatkan informasinya.
Sebaiknya tunggu beberapa menit sebelum mengirim permintaan ke API Anda selagi App Engine melakukan inisialisasi sepenuhnya.
Mengirim permintaan ke API contoh
Linux atau Mac OS
Kirim permintaan HTTP menggunakan curl
. Ganti [YOUR_PROJECT_ID]
dengan project ID Google Cloud Anda:
curl \
--request POST \
--header "Content-Type: application/json" \
--data '{"message":"hello world"}' \
https://[YOUR_PROJECT_ID].appspot.com/_ah/api/echo/v1/echo
Dalam curl
sebelumnya:
- Opsi
--data
menentukan data yang akan diposting ke API. - Opsi
--header
menentukan bahwa data dalam format JSON.
PowerShell
Kirim permintaan HTTP menggunakan Invoke-WebRequest
. Ganti [YOUR_PROJECT_ID]
dengan project ID Google Cloud Anda:
(Invoke-WebRequest -Method POST -Body '{"message": "hello world"}' `
-Headers @{"content-type"="application/json"} -URI `
"https://[YOUR_PROJECT_ID].appspot.com/_ah/api/echo/v1/echo").Content
Pada contoh sebelumnya, dua baris pertama diakhiri dengan {i>backtick<i}. Saat Anda menempelkan contoh ke PowerShell, pastikan tidak ada spasi setelah tanda kutip terbalik. Untuk informasi tentang opsi yang digunakan dalam contoh permintaan, lihat Invoke-WebRequest dalam dokumentasi Microsoft.
Aplikasi pihak ketiga
Anda dapat menggunakan aplikasi pihak ketiga seperti ekstensi browser Chrome Postman untuk mengirim permintaan:
- Pilih
POST
sebagai kata kerja HTTP. - Untuk header, pilih kunci
content-type
dan nilaiapplication/json
. - Untuk isi, masukkan informasi berikut:
{"message":"hello world"}
-
Masukkan URL ke aplikasi contoh. Contoh:
https://example-project-12345.appspot.com/_ah/api/echo/v1/echo
API akan menggemakan kembali pesan yang Anda kirimkan, dan merespons dengan hal berikut:
{
"message": "hello world"
}
Jika Anda tidak mendapatkan respons yang berhasil, lihat Memecahkan masalah error respons.
Aktivitas API pelacakan
Lihat grafik aktivitas untuk API Anda di Konsol Google Cloud di halaman Endpoint > Service.
Mungkin perlu waktu beberapa saat agar permintaan tersebut ditampilkan dalam grafik.
Lihat log permintaan untuk API Anda di halaman Logs Explorer.
Membuat portal developer untuk API
Anda dapat menggunakan Portal Cloud Endpoints untuk membuat portal developer, yaitu situs yang dapat digunakan untuk berinteraksi dengan contoh API. Untuk mempelajari lebih lanjut, lihat Ringkasan Portal Cloud Endpoints.
Pembersihan
Agar tidak perlu membayar biaya pada akun Google Cloud Anda untuk resource yang digunakan dalam tutorial ini, hapus project yang berisi resource tersebut, atau simpan project dan hapus setiap resource.
- Di konsol Google Cloud, buka halaman Manage resource.
- Pada daftar project, pilih project yang ingin Anda hapus, lalu klik Delete.
- Pada dialog, ketik project ID, lalu klik Shut down untuk menghapus project.
Langkah selanjutnya
- Pelajari arsitektur Endpoints Framework.
- Pelajari cara membuat API.
- Pelajari cara membuat server web untuk menyalurkan API Anda.
- Pelajari cara menayangkan API dari jalur yang berbeda.
- Pelajari cara memantau API Anda.
- Pelajari cara membatasi akses dengan kunci API.
- Pelajari cara mengonfigurasi nama domain kustom.
- Pelajari cara menangani pembuatan versi API.
- Pelajari opsi dukungan.