Mulai Menggunakan gRPC-Python

1. Pengantar

Dalam codelab ini, Anda akan menggunakan gRPC-Python untuk membuat klien dan server yang membentuk dasar aplikasi pemetaan rute yang ditulis dalam Python.

Di akhir tutorial, Anda akan memiliki klien yang terhubung ke server jarak jauh menggunakan gRPC untuk mendapatkan nama atau alamat pos dari apa yang terletak di koordinat tertentu pada peta. Aplikasi yang berfungsi penuh dapat menggunakan desain klien-server ini untuk menghitung atau meringkas lokasi menarik di sepanjang rute.

Layanan ini ditentukan dalam file Protocol Buffers, yang akan digunakan untuk membuat kode boilerplate bagi klien dan server sehingga keduanya dapat berkomunikasi satu sama lain, sehingga menghemat waktu dan upaya Anda dalam menerapkan fungsi tersebut.

Kode yang dihasilkan ini tidak hanya menangani kompleksitas komunikasi antara server dan klien, tetapi juga serialisasi dan deserialisasi data.

Yang akan Anda pelajari

• Cara menggunakan Protocol Buffers untuk menentukan API layanan.
• Cara membangun klien dan server berbasis gRPC dari definisi Protocol Buffers menggunakan pembuatan kode otomatis.
• Pemahaman tentang komunikasi klien-server dengan gRPC.

Codelab ini ditujukan bagi developer Python yang baru menggunakan gRPC atau ingin mempelajari kembali gRPC, atau siapa pun yang tertarik untuk membangun sistem terdistribusi. Tidak diperlukan pengalaman gRPC sebelumnya.

2. Sebelum memulai

Yang Anda butuhkan

• Python 3.9 atau yang lebih tinggi. Sebaiknya gunakan Python 3.13. Untuk mengetahui petunjuk penginstalan khusus platform, lihat Penyiapan dan Penggunaan Python. Atau, instal Python non-sistem menggunakan alat seperti uv atau pyenv.
• pip untuk menginstal paket Python.
• venv untuk membuat lingkungan virtual Python.

Paket ensurepip dan venv adalah bagian dari Python Standard Library dan biasanya tersedia secara default.

Namun, beberapa distribusi berbasis Debian (termasuk Ubuntu) memilih untuk mengecualikannya saat mendistribusikan ulang Python. Untuk menginstal paket, jalankan:

sudo apt install python3-pip python3-venv

Mendapatkan kode

Untuk menyederhanakan pembelajaran Anda, codelab ini menawarkan struktur kode sumber bawaan untuk membantu Anda memulai. Langkah-langkah berikut akan memandu Anda menyelesaikan aplikasi, termasuk pembuatan kode gRPC menggunakan plugin compiler Protocol Buffer grpc_tools.protoc.

grpc-codelabs

Kode sumber scaffold untuk codelab ini tersedia di direktori codelabs/grpc-python-getting-started/start_here. Jika Anda memilih untuk tidak menerapkan kode sendiri, kode sumber yang sudah selesai tersedia di direktori completed.

Pertama, buat direktori kerja codelab dan cd ke dalamnya:

mkdir grpc-python-getting-started && cd grpc-python-getting-started

Download dan ekstrak codelab:

curl -sL https://github.com/grpc-ecosystem/grpc-codelabs/archive/refs/heads/v1.tar.gz \
  | tar xvz --strip-components=4 \
  grpc-codelabs-1/codelabs/grpc-python-getting-started/start_here

Atau, Anda dapat mendownload file .zip yang hanya berisi direktori codelab dan mengekstraknya secara manual.

Download ZIP

3. Menentukan layanan

Langkah pertama Anda adalah menentukan layanan gRPC aplikasi, metode RPC, serta jenis pesan permintaan dan responsnya menggunakan bahasa definisi antarmuka Protocol Buffers. Layanan Anda akan menyediakan:

• Metode RPC yang disebut GetFeature yang diimplementasikan server dan dipanggil klien.
• Jenis pesan Point dan Feature adalah struktur data yang dipertukarkan antara klien dan server saat menggunakan metode GetFeature. Klien memberikan koordinat peta sebagai Point dalam permintaan GetFeature ke server, dan server membalas dengan Feature yang sesuai yang menjelaskan apa pun yang berada di koordinat tersebut.

Metode RPC ini dan jenis pesannya akan ditentukan dalam file protos/route_guide.proto kode sumber yang diberikan.

Protocol Buffers biasanya dikenal sebagai protobuf. Untuk mengetahui informasi selengkapnya tentang terminologi gRPC, lihat Konsep inti, arsitektur, dan siklus proses gRPC.

Jenis pesan

Dalam file protos/route_guide.proto kode sumber, tentukan terlebih dahulu jenis pesan Point. Point mewakili pasangan koordinat lintang-bujur di peta. Untuk codelab ini, gunakan bilangan bulat untuk koordinat:

message Point {
  int32 latitude = 1;
  int32 longitude = 2;
}

Angka 1 dan 2 adalah nomor ID unik untuk setiap kolom dalam struktur message.

Selanjutnya, tentukan jenis pesan Feature. Feature menggunakan kolom string untuk nama atau alamat pos sesuatu di lokasi yang ditentukan oleh Point:

message Feature {
  // The name or address of the feature.
  string name = 1;

  // The point where the feature is located.
  Point location = 2;
}

Metode layanan

File route_guide.proto memiliki struktur service bernama RouteGuide yang menentukan satu atau beberapa metode yang disediakan oleh layanan aplikasi.

Tambahkan metode rpc GetFeature di dalam definisi RouteGuide. Seperti yang dijelaskan sebelumnya, metode ini akan mencari nama atau alamat lokasi dari sekumpulan koordinat tertentu, jadi buat GetFeature menampilkan Feature untuk Point tertentu:

service RouteGuide {
  // Definition of the service goes here

  // Obtains the feature at a given position.
  rpc GetFeature(Point) returns (Feature) {}
}

Ini adalah metode RPC unary: RPC sederhana di mana klien mengirim permintaan ke server dan menunggu respons kembali, seperti panggilan fungsi lokal.

4. Buat kode klien dan server

Selanjutnya, buat kode gRPC boilerplate untuk klien dan server dari file .proto menggunakan compiler protocol buffer.

Untuk pembuatan kode gRPC Python, kami membuat grpcio-tools. Ini mencakup:

1. Compiler protoc reguler yang menghasilkan kode Python dari definisi message.
2. Plugin protobuf gRPC yang menghasilkan kode Python (stub klien dan server) dari definisi service.

Kita akan menginstal paket Python grpcio-tools menggunakan pip. Mari buat lingkungan virtual python (venv) baru untuk mengisolasi dependensi project Anda dari paket sistem:

python3 -m venv --upgrade-deps .venv

Untuk mengaktifkan lingkungan virtual di shell bash/zsh:

source .venv/bin/activate

Untuk Windows dan shell non-standar, lihat tabel di https://docs.python.org/3/library/venv.html#how-venvs-work.

Catatan: Anda harus mengaktifkan lingkungan virtual setiap kali Anda membuka shell baru. Skrip activate mengonfigurasi variabel $PATH untuk menggunakan python dan pip dari venv Anda. Untuk menonaktifkan venv, cukup jalankan deactivate.

Selanjutnya, instal grpcio-tools (tindakan ini juga akan menginstal paket grpcio):

pip install grpcio-tools

Gunakan perintah berikut untuk membuat kode boilerplate Python:

python -m grpc_tools.protoc --proto_path=./protos  \
 --python_out=. --pyi_out=. --grpc_python_out=. \
 ./protos/route_guide.proto

Tindakan ini akan menghasilkan file berikut untuk antarmuka yang kita tentukan di route_guide.proto:

1. route_guide_pb2.py berisi kode yang membuat class secara dinamis yang dihasilkan dari definisi message.
2. route_guide_pb2.pyi adalah "file stub" atau "file petunjuk jenis" yang dihasilkan dari definisi message. Hanya berisi tanda tangan tanpa penerapan. File stub dapat digunakan oleh IDE untuk memberikan pelengkapan otomatis dan deteksi error yang lebih baik.
3. route_guide_pb2_grpc.py dihasilkan dari definisi service dan berisi class serta fungsi khusus gRPC.

Fakta: Suffix _pb2 tidak menyiratkan sintaksis proto2. Menunjukkan versi Python Protocol Buffers API. Saat ini, proto2, proto3, dan Editions semuanya menggunakan _pb2.py untuk file yang dihasilkan.

Kode khusus gRPC berisi:

1. RouteGuideStub, yang dapat digunakan oleh klien gRPC untuk memanggil RPC RouteGuide.
2. RouteGuideServicer, yang menentukan antarmuka untuk penerapan layanan RouteGuide.
3. Fungsi add_RouteGuideServicer_to_server yang digunakan untuk mendaftarkan RouteGuideServicer ke server gRPC.

5. Membuat layanan

Pertama, mari kita lihat cara membuat server RouteGuide. Membuat dan menjalankan server RouteGuide dibagi menjadi dua item pekerjaan:

• Mengimplementasikan antarmuka layanan yang dihasilkan dari definisi layanan dengan fungsi yang melakukan "tugas" layanan yang sebenarnya.
• Menjalankan server gRPC di port tertentu untuk memproses permintaan dari klien dan mengirimkan respons.

Anda dapat menemukan server RouteGuide awal di start_here/route_guide_server.py.

Mengimplementasikan RouteGuide

route_guide_server.py memiliki class RouteGuideServicer yang merupakan subclass dari class route_guide_pb2_grpc.RouteGuideServicer yang dihasilkan:

# RouteGuideServicer provides an implementation
# of the methods of the RouteGuide service.
class RouteGuideServicer(route_guide_pb2_grpc.RouteGuideServicer):

RouteGuideServicer mengimplementasikan semua metode layanan RouteGuide.

Mari kita pelajari implementasi RPC sederhana secara mendetail. Metode GetFeature mendapatkan Point dari klien dan menampilkan informasi fitur yang sesuai dari databasenya dalam Feature.

def GetFeature(self, request, context):
    feature = get_feature(self.db, request)
    if feature is None:
        return route_guide_pb2.Feature(name="", location=request)
    else:
        return feature

Metode ini meneruskan permintaan route_guide_pb2.Point untuk RPC, dan objek grpc.ServicerContext yang memberikan informasi khusus RPC seperti batas waktu. API ini menampilkan respons route_guide_pb2.Feature.

Memulai server

Setelah Anda menerapkan semua metode RouteGuide, langkah berikutnya adalah memulai server gRPC agar klien dapat benar-benar menggunakan layanan Anda:

def serve():
    server = grpc.server(futures.ThreadPoolExecutor(max_workers=10))
    route_guide_pb2_grpc.add_RouteGuideServicer_to_server(
        RouteGuideServicer(),
        server,
    )
    listen_addr = "localhost:50051"
    server.add_insecure_port(listen_addr)
    print(f"Starting server on {listen_addr}")
    server.start()
    server.wait_for_termination()

Metode start() server tidak memblokir. Thread baru akan di-instansiasi untuk menangani permintaan. Thread yang memanggil server.start() sering kali tidak memiliki tugas lain yang harus dilakukan pada saat yang sama. Dalam hal ini, Anda dapat memanggil server.wait_for_termination() untuk memblokir thread panggilan secara bersih hingga server berhenti.

6. Buat klien

Di bagian ini, kita akan melihat cara membuat klien untuk layanan RouteGuide. Anda dapat melihat kode klien awal di start_here/route_guide_client.py.

Membuat stub

Untuk memanggil metode layanan, kita harus membuat stub terlebih dahulu.

Kita membuat instance class RouteGuideStub dari modul route_guide_pb2_grpc, yang dihasilkan dari .proto kita di dalam file route_guide_client.py.

channel = grpc.insecure_channel("localhost:50051")
stub = route_guide_pb2_grpc.RouteGuideStub(channel)

Memanggil metode layanan

Untuk metode RPC yang menampilkan satu respons–yang dikenal sebagai metode response-unary–gRPC Python mendukung semantik alur kontrol sinkron (pemblokiran) dan asinkron (non-pemblokiran).

RPC Sederhana

Pertama, mari kita tentukan Point untuk memanggil layanan. Hal ini sesederhana membuat instance objek dari paket route_guide_pb2 dengan beberapa properti:

point = route_guide_pb2.Point(latitude=412346009, longitude=-744026814)

Panggilan sinkron ke RPC GetFeature sederhana hampir sama mudahnya dengan memanggil metode lokal. Panggilan RPC menunggu server merespons, dan akan menampilkan respons atau mengajukan pengecualian. Kita dapat memanggil metode dan melihat respons seperti ini:

feature = stub.GetFeature(point)
print(feature)

Anda dapat memeriksa kolom objek Fitur dan menampilkan hasil permintaan:

if feature.name:
    print(f"Feature called '{feature.name}' at {format_point(feature.location)}")
else:
    print(f"Found no feature at at {format_point(feature.location)}")

7. Cobalah

Jalankan server:

python route_guide_server.py

Dari terminal lain, aktifkan kembali lingkungan virtual, lalu jalankan klien:

python route_guide_client.py

Anda akan melihat output seperti ini, dengan stempel waktu yang dihilangkan agar lebih jelas:

name: "16 Old Brook Lane, Warwick, NY 10990, USA"
location {
  latitude: 412346009
  longitude: -744026814
}

Feature called '16 Old Brook Lane, Warwick, NY 10990, USA' at latitude: 412346009, longitude: -744026814

8. Langkah berikutnya

• Pelajari cara kerja gRPC di Pengantar gRPC dan Konsep inti
• Pelajari tutorial Dasar-Dasar.
• Pelajari referensi Python API