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

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

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

אתם יכולים להשתמש בשיטות של פעולות ממושכות ש-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. יש שתי דרכים למצוא את שם הפעולה:

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

      לדוגמה, אם קוראים ל-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 ריק. כדי לוודא שהביטול בוצע:

      • משתמשים ב-method‏ 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