מעקב אחר פעולות ממושכות

בדף הזה מוסבר איך לנהל את מחזור החיים של פעולה ממושכת (LRO) ב-Gemini Enterprise.

אובייקט של פעולה ממושכת מוחזר כשקריאה לשיטה עשויה להימשך זמן רב. לדוגמה, Gemini Enterprise API יוצר פעולה ממושכת כשמפעילים את documents.import דרך ה-API או ספריות הלקוח. הפעולה עוקבת אחרי הסטטוס של משימת העיבוד.

אתם יכולים להשתמש ב-methods של פעולות ממושכות ש-Gemini Enterprise API מספק כדי לבדוק את הסטטוס של הפעולות. אפשר גם להציג רשימה של פעולות או לבצע דגימה של פעולות.

תיעוד של פעולה נשמר למשך כ-30 ימים אחרי שהפעולה מסתיימת, כלומר אי אפשר להציג או לפרט פעולה אחרי פרק הזמן הזה.

הצגת רשימה של פעולות ממושכות

בדוגמאות הבאות אפשר לראות איך מציגים את רשימת הפעולות של משאב Google Cloud.

REST

כדי לכלול ברשימה את הפעולות ארוכות הטווח של משאב Google Cloud , פועלים לפי השלב הבא:

  • מבצעים קריאה ל-operations.list:

    curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/dataStores/DATA_STORE_ID/operations"

    ‫DATA_STORE_ID: המזהה של מאגר הנתונים של Gemini Enterprise שנוצר באמצעות המנוע. בכתובת ה-URL של מסוף Google Cloud , מזהה מאגר הנתונים מופיע אחרי engines/ ולפני /data.

Python

לפני שמנסים את הדוגמה הזו, צריך לפעול לפי Pythonההוראות להגדרה במאמר תחילת העבודה עם Gemini Enterprise באמצעות ספריות לקוח. מידע נוסף מופיע במאמרי העזרה של Gemini Enterprise Python API.

כדי לבצע אימות ב-Gemini Enterprise, צריך להגדיר את Application Default Credentials. מידע נוסף זמין במאמר הגדרת אימות לסביבת פיתוח מקומית. 

from typing import Optional

from google.cloud import discoveryengine
from google.longrunning import operations_pb2

# TODO(developer): Uncomment these variables before running the sample.
# project_id = "YOUR_PROJECT_ID"
# location = "YOUR_PROCESSOR_LOCATION"  # Options: "global"
# search_engine_id = "YOUR_SEARCH_ENGINE_ID"

# Create filter in https://google.aip.dev/160 syntax
# operations_filter = "YOUR_FILTER"


def list_operations_sample(
    project_id: str,
    location: str,
    search_engine_id: str,
    operations_filter: Optional[str] = None,
) -> operations_pb2.ListOperationsResponse:
    # Create a client
    client = discoveryengine.DocumentServiceClient()

    # The full resource name of the search engine branch.
    name = f"projects/{project_id}/locations/{location}/collections/default_collection/dataStores/{search_engine_id}"

    # Make ListOperations request
    request = operations_pb2.ListOperationsRequest(
        name=name,
        filter=operations_filter,
    )

    # Make ListOperations request
    response = client.list_operations(request=request)

    # Print the Operation Information
    for operation in response.operations:
        print(operation)

    return response

איך מקבלים פרטים על פעולה ממושכת

בדוגמאות הבאות מוסבר איך לקבל פרטים על פעולה.

REST

כדי לראות את הסטטוס של פעולה ממושכת ואת הפרטים שלה, פועלים לפי השלבים הבאים:

  1. אפשר למצוא את שם הפעולה באחת משתי דרכים:

    • אחרי שמפעילים שיטה שמחזירה פעולה ממושכת, בודקים את התשובה.

      לדוגמה, אם קוראים ל-documents.import, תחילת התגובה תיראה בערך כך:

      {
  "operations": [
    {
      "name": "projects/12345/locations/global/collections/default_collection/dataStores/my-datastore_4321/branches/0/operations/import-documents-56789",
      "metadata": {
        "@type": "type.googleapis.com/google.cloud.discoveryengine.v1.ImportDocumentsMetadata",
      }
    }
  ]
}

      הערך name בתגובה מספק את שם הפעולה, שאפשר להשתמש בו כדי לשלוח שאילתה לגבי סטטוס הפעולה. כשמעתיקים את שם הפעולה, לא כוללים את המירכאות.

    • אפשר לקבל את שם הפעולה על ידי הצגת רשימה של פעולות ממושכות.

  2. מבצעים קריאה לשיטה operations.get במשאב שיצר את הפעולה:

    curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://discoveryengine.googleapis.com/v1/OPERATION_NAME"

    ‫OPERATION_NAME: צריך לציין את שם הפעולה שרוצים לקבל עליה מידע. אפשר למצוא את שם הפעולה על ידי רישום של פעולות ממושכות.

    השורות הראשונות של התגובה מהפקודה GET נראות בערך כך:

    {
      "name": "projects/12345/locations/global/collections/default_collection/dataStores/my-datastore_4321/branches/0/operations/import-documents-56789",
      "metadata": {
        "@type": "type.googleapis.com/google.cloud.discoveryengine.v1.ImportDocumentsMetadata"
      }
    }

Python

לפני שמנסים את הדוגמה הזו, צריך לפעול לפי Pythonההוראות להגדרה במאמר תחילת העבודה עם Gemini Enterprise באמצעות ספריות לקוח. מידע נוסף מופיע במאמרי העזרה של Gemini Enterprise Python API.

כדי לבצע אימות ב-Gemini Enterprise, צריך להגדיר את Application Default Credentials. מידע נוסף זמין במאמר הגדרת אימות לסביבת פיתוח מקומית. 

from google.cloud import discoveryengine
from google.longrunning import operations_pb2

# TODO(developer): Uncomment these variables before running the sample.
# Example: `projects/{project}/locations/{location}/collections/{default_collection}/dataStores/{search_engine_id}/branches/{0}/operations/{operation_id}`
# operation_name = "YOUR_OPERATION_NAME"


def get_operation_sample(operation_name: str) -> operations_pb2.Operation:
    # Create a client
    client = discoveryengine.DocumentServiceClient()

    # Make GetOperation request
    request = operations_pb2.GetOperationRequest(name=operation_name)
    operation = client.get_operation(request=request)

    # Print the Operation Information
    print(operation)

    return operation

דגימה של פעולה ממושכת

בדוגמאות הבאות אפשר לראות איך שולחים שאילתה כדי לבדוק את הסטטוס של פעולה.

REST

כדי לבדוק את הפעולה ארוכת הטווח עד שהיא מסתיימת, פועלים לפי השלבים הבאים:

  1. מריצים את הפקודה הבאה, שמפעילה שוב ושוב את השיטה operations.get, עם השהיה מומלצת לפני ניסיון חוזר (backoff) של 10 שניות בין כל בקשה:

    while true; \
    do curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://discoveryengine.googleapis.com/v1/OPERATION_NAME"; \
    sleep 10; \
    done

    ‫OPERATION_NAME: מציינים את שם הפעולה שרוצים לבדוק את הסטטוס שלה. אפשר למצוא את שם הפעולה על ידי רישום של פעולות ממושכות. לדוגמה, projects/12345/locations/global/collections/default_collection/dataStores/my-datastore_4321/branches/0/operations/import-documents-56789.

  2. מפסיקים את עבודת הסקר (Control+Z) אחרי שהסטטוס משתנה ל-"done": true.

Python

לפני שמנסים את הדוגמה הזו, צריך לפעול לפי Pythonההוראות להגדרה במאמר תחילת העבודה עם Gemini Enterprise באמצעות ספריות לקוח. מידע נוסף מופיע במאמרי העזרה של Gemini Enterprise Python API.

כדי לבצע אימות ב-Gemini Enterprise, צריך להגדיר את Application Default Credentials. מידע נוסף זמין במאמר הגדרת אימות לסביבת פיתוח מקומית. 

from time import sleep

from google.cloud import discoveryengine
from google.longrunning import operations_pb2

# TODO(developer): Uncomment these variables before running the sample.
# Example: `projects/{project}/locations/{location}/collections/{default_collection}/dataStores/{search_engine_id}/branches/{0}/operations/{operation_id}`
# operation_name = "YOUR_OPERATION_NAME"


def poll_operation_sample(
    operation_name: str, limit: int = 10
) -> operations_pb2.Operation:
    # Create a client
    client = discoveryengine.DocumentServiceClient()

    # Make GetOperation request
    request = operations_pb2.GetOperationRequest(name=operation_name)

    for _ in range(limit):
        operation = client.get_operation(request=request)
        # Print the Operation Information
        print(operation)

        # Stop polling when Operation is no longer running
        if operation.done:
            break

        # Wait 10 seconds before polling again
        sleep(10)

    return operation

ביטול פעולה ממושכת

בדוגמה הבאה אפשר לראות איך מבטלים פעולה:

REST

כדי לבטל פעולה ממושכת, בצע את השלבים הבאים:

  • מבצעים קריאה ל-operations.cancel:

    curl -X post \
   -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   "https://discoveryengine.googleapis.com/v1/OPERATION_NAME":cancel

    ‫OPERATION_NAME: מציינים את שם הפעולה שרוצים לבטל. אפשר למצוא את שם הפעולה על ידי רישום של פעולות ממושכות. לדוגמה, projects/12345/locations/global/collections/default_collection/dataStores/my-datastore_4321/branches/0/operations/import-documents-56789.

    אחרי שמתבצעת קריאה ל-API, השרת מנסה לבטל את הפעולה. אלה התוצאות שיוצגו והפעולות שאפשר לבצע:

    • שגיאה בפונקציות "code": 400 ו-"status": "FAILED_PRECONDITION" מציינת שלא ניתן לבטל את הבקשה.

    • אם הביטול יבוצע בהצלחה, יוחזר אובייקט JSON ריק. כדי לאמת את הביטול:

      • משתמשים בשיטה operations.get.

      • אם הפעולה בוטלה בהצלחה, התשובה מ-method‏ operations.get כוללת את השגיאה "code": 1, שמייצגת את קוד הסטטוס CANCELLED.

        לדוגמה:

        {
  "name": "projects/12345/locations/global/collections/default_collection/dataStores/my-datastore_4321/branches/0/operations/import-documents-56789",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.discoveryengine.v1alpha.ImportDocumentsMetadata",
    "createTime": "2025-04-28T21:29:21.199190Z",
    "updateTime": "2025-04-28T21:31:29.076865Z"
  },
  "done": true,
  "error": {
    "code": 1,
    "message": "Operation projects/12345/locations/global/collections/default_collection/dataStores/my-datastore_4321/branches/0/operations/import-documents-56789 is cancelled."
  }
}

Python

לפני שמנסים את הדוגמה הזו, צריך לפעול לפי Pythonההוראות להגדרה במאמר תחילת העבודה עם Gemini Enterprise באמצעות ספריות לקוח. מידע נוסף מופיע במאמרי העזרה של Gemini Enterprise Python API.

כדי לבצע אימות ב-Gemini Enterprise, צריך להגדיר את Application Default Credentials. מידע נוסף זמין במאמר הגדרת אימות לסביבת פיתוח מקומית. 

from google.cloud import discoveryengine
from google.longrunning import operations_pb2

# TODO(developer): Uncomment these variables before running the sample.
# Example: `projects/{project}/locations/{location}/collections/{default_collection}/dataStores/{search_engine_id}/branches/{0}/operations/{operation_id}`
# operation_name = "YOUR_OPERATION_NAME"


def cancel_operation_sample(operation_name: str) -> None:
    # Create a client
    client = discoveryengine.DocumentServiceClient()

    # Make CancelOperation request
    request = operations_pb2.CancelOperationRequest(name=operation_name)
    client.cancel_operation(request=request)

    return