שליחת בקשות RPC באמצעות Python

גרסת טרום השקה פרטית

השימוש במוצר הזה כפוף לתנאי השימוש במוצרים בגרסת טרום-GA, שמפורטים בחלק "תנאים כלליים לשירות" בתנאים הספציפיים של השירות. השימוש במוצרים בגרסת טרום-GA הוא "כפי שהם" (As is), ויכול להיות שהתמיכה בהם תהיה מוגבלת. מידע נוסף זמין בקטע תיאור שלבי ההשקה.

אתם יכולים לקרוא מידע נוסף על הגישה לגרסה הזו בדף בקשת הגישה.

אפליקציות יכולות ליצור אינטראקציה עם Universal Ledger API באמצעות gRPC ו-Python. גישה זו כוללת יצירה ושימוש בספריות לקוח של Python שנערכו מהגדרות של מאגר אחסון לפרוטוקולים של השירות.

במדריך הזה נסביר למפתחים שרוצים להטמיע לקוח ל-Universal Ledger API איך להגדיר סביבת פיתוח מתאימה, ליצור את הספריות הנדרשות ולבצע קריאת gRPC באמצעות Python.

לפני שמתחילים

כדי להשלים את המדריך הזה, תצטרכו:

• Google Cloud פרויקט שמופעל בו Universal Ledger API.

• תפקיד ב-IAM כמו universalledger.googleapis.com/endpointViewer, כדי שתוכלו לפחות לצפות בנקודות הקצה של Universal Ledger.

• פרטי כניסה לאימות מקומי בחשבון המשתמש. מריצים את הפקודה הבאה כדי להגדיר את פרטי הכניסה האלה:

  gcloud auth application-default login

מידע נוסף על השלבים האלה זמין במדריך בנושא הצטרפות לתצוגה מקדימה פרטית.

מגדירים את הסביבה

ההוראות במדריך הזה מיועדות לסביבה שמופעלת בה Ubuntu 25.04, שכוללת כברירת מחדל את Python 3.13. יכול להיות שתצטרכו לשנות את הפקודות אם אתם משתמשים במערכת הפעלה אחרת.

כדי להגדיר את סביבת הפיתוח, מבצעים את השלבים הבאים. בשלבים הבאים מוסבר איך להתקין את כלי שורת הפקודה הנדרשים. הפעולות האלה כוללות שימוש ב-pipx כדי להתקין את grpcio-tools, שמשמש ליצירת הקישורים של gRPC. כדי לבודד את יחסי התלות של Python בפרויקט הזה, תיצרו ותפעילו גם סביבה וירטואלית של Python, ואז תתקינו בה את ספריות Python הנדרשות באמצעות pip.

1. מתקינים את יחסי התלות הבסיסיים באמצעות הפקודות:

   sudo apt update
   sudo apt install git pipx python3.13-venv

2. משתמשים ב-pipx כדי להתקין את אפליקציית הכלים של gRPC ומוודאים שספריית הקבצים הבינאריים שלה נוספה ל-PATH:

   pipx install grpcio-tools
   pipx ensurepath

   כדי להשלים את ההפעלה של pipx, צריך לסגור את הטרמינל ולפתוח אותו מחדש.

3. יוצרים תיקייה ראשית שתכיל את הקבצים של המדריך הזה.

   mkdir gcul_tutorial
   cd gcul_tutorial

   אלא אם צוין אחרת, צריך להריץ את שאר הפקודות מתוך הספרייה החדשה הזו.

4. יוצרים סביבה וירטואלית של Python ומתקינים את שאר הספריות:

   python3 -m venv example_client
   cd example_client
   source ./bin/activate
   pip3 install google-auth googleapis-common-protos grpcio requests
   cd ..

   הספריות האלה הן:

   • ‫google-auth: לטיפול Google Cloud באימות.
   • ‫googleapis-common-protos: הודעות נפוצות של מאגר אחסון לפרוטוקולים שמשמשות בממשקי Google API.
   • ‫grpcio: ספריית gRPC ל-Python.
   • ‫requests: נדרש על ידי חלק מהתלויות כדי לשלוח בקשות HTTP.

יצירת ספריות של Protocol Buffer

כדי לעבוד עם Universal Ledger API באמצעות gRPC, צריך להדר בספריית הלקוח של אפליקציית Python את ההגדרות של Protocol Buffer ‏(.proto) של השירות. ההגדרות האלה מציינות את השירותים, ה-methods וסוגי ההודעות של ה-API.

בקטע הזה מוסבר איך להוריד את קובצי .proto ממאגר googleapis ולהשתמש ב-grpcio-tools שהותקן כדי ליצור את קוד המקור הדרוש של Python.

1. משכפלים את מאגר googleapis ב-GitHub, שבו מתפרסמות הגדרות של Protocol Buffer לממשקי Google API.

   git clone https://github.com/googleapis/googleapis.git

2. ליצור את ההגדרות של Protocol Buffer ואת הקישורים של gRPC ל-Universal Ledger API.

   python-grpc-tools-protoc --proto_path=googleapis/ \
       --python_out=example_client \
       --pyi_out=example_client \
       --grpc_python_out=example_client \
       google/cloud/universalledger/v1/universalledger.proto
   python-grpc-tools-protoc --proto_path=googleapis/ \
       --python_out=example_client \
       --pyi_out=example_client \
       google/cloud/universalledger/v1/query.proto
   python-grpc-tools-protoc --proto_path=googleapis/ \
       --python_out=example_client \
       --pyi_out=example_client \
       google/cloud/universalledger/v1/accounts.proto
   python-grpc-tools-protoc --proto_path=googleapis/ \
       --python_out=example_client \
       --pyi_out=example_client \
       google/cloud/universalledger/v1/common.proto
   python-grpc-tools-protoc --proto_path=googleapis/ \
       --python_out=example_client \
       --pyi_out=example_client \
       google/cloud/universalledger/v1/transactions.proto
   python-grpc-tools-protoc --proto_path=googleapis/ \
       --python_out=example_client \
       --pyi_out=example_client \
       google/cloud/universalledger/v1/types.proto
   python-grpc-tools-protoc --proto_path=googleapis/ \
       --python_out=example_client \
       --pyi_out=example_client \
       google/cloud/universalledger/v1/status_event.proto

   אחרי ההפעלה אמורים להיווצר כמה קבצים בספרייה example_client/google/cloud/universalledger/v1.

   accounts_pb2.py
   accounts_pb2.pyi
   common_pb2.py
   common_pb2.pyi
   query_pb2.py
   query_pb2.pyi
   status_event_pb2.py
   status_event_pb2.pyi
   transactions_pb2.py
   transactions_pb2.pyi
   types_pb2.py
   types_pb2.pyi
   universalledger_pb2.py
   universalledger_pb2.pyi
   universalledger_pb2_grpc.py
   

קריאה ל-Universal Ledger API

לבסוף, יוצרים סקריפט Python כדי לקרוא ל-Universal Ledger API באמצעות הספריות שנוצרו. שומרים את הקוד הבא בשם example_client/endpoints.py.

בקוד, מחליפים את הערכים הזמניים לשמירת מקום (placeholder) הבאים:

• ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud . לדוגמה: my-project.
• ‫REGION: Google Cloud האזור שבו נמצאת נקודת הקצה של Universal Ledger, לדוגמה us-east5.

"""Example calling the Universal Ledger API."""

import sys

import google.auth
import google.auth.transport.grpc
import google.auth.transport.requests
from google.cloud.universalledger.v1 import universalledger_pb2
from google.cloud.universalledger.v1 import universalledger_pb2_grpc
import grpc

API_ENDPOINT = "universalledger.googleapis.com"
PROJECT = "PROJECT_ID"
REGION = "REGION"
SCOPES = ["https://www.googleapis.com/auth/cloud-platform"]


def main() -> str | None:
  # Get the application default credentials.
  credentials, _ = google.auth.default(scopes=SCOPES)

  # Get an HTTP request function to refresh credentials.
  refresh_request = google.auth.transport.requests.Request()

  # Create a secure channel to the API endpoint.
  with google.auth.transport.grpc.secure_authorized_channel(
      credentials, refresh_request, API_ENDPOINT
  ) as channel:
    # Create the client stub using the generated code.
    stub = universalledger_pb2_grpc.UniversalLedgerStub(channel)

    # Parent location for GCUL network endpoints.
    parent = f"projects/{PROJECT}/locations/{REGION}"

    # Build the request message.
    request = universalledger_pb2.ListEndpointsRequest(parent=parent)

    # Make the gRPC call.
    try:
      metadata = [("x-goog-request-params", f"parent={parent}")]
      response = stub.ListEndpoints(request, metadata=metadata)
    except grpc.RpcError as exc:
      return f"{exc.code().name}: {exc.details()}"

    if not response.endpoints:
      return f"No endpoints found under: {parent}"

    print("Found the following endpoints:")
    for endpoint in response.endpoints:
      print("-", endpoint.name)


if __name__ == "__main__":
  sys.exit(main())

כדי להריץ את הסקריפט, עוברים לספרייה example_client. הסביבה הווירטואלית אמורה להיות עדיין פעילה מהשלבים של ההגדרה.

1. עוברים לספריית הסקריפט:

   cd example_client
   

   שורת הפקודה של המעטפת צריכה לאשר שהסביבה הווירטואלית פעילה (לדוגמה, מופיע לפני השורה הקידומת (example_client)).

2. מריצים את סקריפט Python:

   python3 endpoints.py
   

הפלט אמור להיראות כך:

Found the following endpoints:
- projects/my-project/locations/us-east5/endpoint/gcul-pilot-testing
- projects/my-project/locations/us-east5/endpoint/gcul-user-testing

המאמרים הבאים

• כל השיטות ב-Universal Ledger API
• מידע נוסף על תמיכה ב-gRPC בשפות אחרות
• הגדרות של מאגרי פרוטוקולים של Universal Ledger API