פעולות ממושכות

ה-API לשליחת בקשות הוא אסינכרוני ומחזיר פעולה ממושכת. יכול להיות שהפעולה לא תושלם כשהשיטה מחזירה תגובה.

קבלת סטטוס של פעולה

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

מבצעים קריאה לשיטה GET עבור סוג הפעולות.

לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הנתונים הבאים:

  • ‫project-number: מספר הפרויקט ב-Google Cloud
  • ‫operation-id: מזהה הפעולה

ה-method של ה-HTTP וכתובת ה-URL: 

GET https://webrisk.googleapis.com/v1/projects/project-number/operations/operation-id

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

curl

מריצים את הפקודה הבאה: 

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://webrisk.googleapis.com/v1/projects/project-number/operations/operation-id"

PowerShell

מריצים את הפקודה הבאה: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://webrisk.googleapis.com/v1/projects/project-number/operations/operation-id" | Select-Object -Expand Content

אתם אמורים לקבל תגובת JSON שדומה לזו:

{
  "name": "projects/project-number/operations/operation-id",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.webrisk.v1.SubmitUriMetadata",
    "state": "RUNNING"
  }
  "done": false,
  ...
}

הסבר על סטטוס הפעילות

השדה metadata.state בתגובה מציין את הסטטוס הנוכחי של השליחה. כשהפעולה מסתיימת, השדה state ב-SubmitUriMetadata מתעדכן. אלו המצבים האפשריים:

  • ‫SUCCEEDED: מציין שכתובת ה-URL שנשלחה נוספה לרשימת החסימה של הגלישה הבטוחה.
  • ‫CLOSED: מציין שכתובת ה-URL שנשלחה לא נוספה לרשימת החסימה של הגלישה הבטוחה כי לא נמצא שהיא מפרה את מדיניות הגלישה הבטוחה.
  • ‫RUNNING: מציין שהשליחה עדיין בתהליך עיבוד.

הסבר על הסיבות לסגירת הזדמנויות

כשהמצב של הפעולה הוא CLOSED, יכול להיות שהשדה SubmitUriMetadata יכלול את השדה closed_reason. בשדה הזה מופיע הקשר נוסף שמסביר למה הבקשה נסגרה בלי שכתובת ה-URL נוספה לרשימת החסימה.

הערכים האפשריים של closed_reason הם:

  • ‫CLOSED_REASON_UNSPECIFIED: הסיבה לא צוינה.
  • NO_THREAT_DETECTED:
    • תיאור: כתובת ה-URL שנשלחה נותחה בהצלחה ולא נמצא בה תוכן זדוני. המשמעות היא שעל סמך הניתוח שלנו, כתובת ה-URL לא עומדת בקריטריונים להוספה לרשימת חסימה.
    • הפעולה המומלצת מצד המשתמש: בדרך כלל לא נדרשת פעולה נוספת לגבי כתובת ה-URL הזו, כי לא נמצא שהיא מהווה איום. אל תשלחו את הפנייה שוב ושוב, אלא אם התוכן השתנה ויש הוכחות חדשות לפעילות זדונית.
  • HOST_UNRESOLVABLE:
    • תיאור: לא הצלחנו להשלים את הניתוח כי לא הצלחנו לפענח את שם המארח של כתובת ה-URL באמצעות DNS. לרוב זה אומר שהאתר לא פעיל, שהדומיין כבר לא קיים או שהייתה בעיה זמנית ב-DNS. אנחנו לא יכולים להוסיף לרשימת החסומים כתובות URL לא פעילות או כתובות URL של placeholder.
    • הפעולה המומלצת למשתמש:
      • אימות כתובת ה-URL: מוודאים ששם המארח נכון ושהאתר פעיל ונגיש לכולם.
      • שליחה מחדש: אפשר לשלוח מחדש את כתובת האתר מאוחר יותר אם מאשרים שהאתר פעיל.
  • CONTENT_UNREACHABLE:
    • תיאור: לא ניתן להשלים את הניתוח כי לא הייתה גישה לתוכן באתר. יכולות להיות לכך כמה סיבות, כמו:
      • דף האינטרנט כבר לא קיים (זו שגיאה מסוג 404 Not Found).
      • השרת של האתר נתקל בשגיאה (זוהי שגיאת שרת מסוג 5xx).
      • יכול להיות שהאתר מציג למערכת הניתוח שלנו תוכן שונה מזה שמוצג למבקר רגיל (הסתרה), ולכן לא ניתן לבצע הערכה מלאה.
    • הפעולה המומלצת למשתמש:
      • בדיקת הנגישות: מוודאים שאפשר להגיע לתוכן הזדוני. שימו לב: יכול להיות שחלק מהאתרים יציגו תוכן זדוני רק בתנאים ספציפיים (במיקומים גיאוגרפיים מסוימים, במכשירים מסוימים או בדפדפנים מסוימים).
      • הוספת הקשר: אם אפשר לגשת לכתובת ה-URL בתנאים מסוימים, צריך לשלוח אותה מחדש. משתמשים בשדות ThreatDiscovery ב-SubmitUriRequest כדי לספק פרטים נוספים, כמו האזור והפלטפורמה שבהם נצפה האיום. המידע הזה יכול להגדיל את הסיכויים לניתוח מוצלח.