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

בדף הזה מוסברות שיטות מומלצות להפעלה ולניהול של פעולות ארוכות טווח (LRO) ב-Cloud Healthcare API. סקירה כללית על פעולות ממושכות ב-Cloud Healthcare API זמינה במאמר ניהול פעולות ממושכות.

מאפייני LRO

הקטעים הבאים רלוונטיים ל-methods שמפורטות בMethods שמחזירות LRO.

השפעה על המכסה

מכסות של LRO לא משותפות עם שיטות ליצירה, לקריאה, לעדכון ולמחיקה (CRUD) של Cloud Healthcare API שצורכות את סוגי המכסות הבאים:

• fhir_read_ops
• fhir_write_ops
• fhir_search_ops
• fhir_store_ops
• dicom_web_ops
• dicom_ops

מכסת ה-LRO מחושבת באמצעות המדדים fhir_store_lro_ops ו-dicom_store_lro_ops.

ב-Cloud Healthcare API יש הגבלה על מספר הפעולות ארוכות הטווח שיכולות לפעול בו-זמנית בפרויקט Google Cloud . מידע נוסף מופיע במאמר בנושא מגבלות על מספר הפעולות ארוכות הטווח.

תפוקת נתונים

בדרך כלל, שיטות LRO משיגות תפוקת נתונים גבוהה יותר משיטות CRUD מקבילות. לדוגמה, ייבוא של מופעי DICOM באמצעות dicomStores.import בדרך כלל עדיף על אחסון המופעים בנפרד באמצעות dicomStores.storeInstances.

הפעלת כמה פעולות LRO בו-זמנית לא בהכרח תגדיל את קצב העברת הנתונים, בגלל המגבלות הבאות, במיוחד כשמעבדים נפחי נתונים גדולים:

• מגבלות מכסה
• התנגשות משאבים
• תעבורה אחרת שהפרויקט שולח אל Cloud Healthcare API בזמן ש-LRO פועל Google Cloud

כדי להשיג את קצב העברת הנתונים המקסימלי כשמריצים פעולות LRO, כדאי לשקול את הנקודות הבאות:

• בדרך כלל, קצב העברת הנתונים של קבוצות קטנות של ייבוא וייצוא נמוך בגלל תקורה.
• פעולות LRO פועלות וצורכות מכסות בנפרד מפעולות אחרות של Cloud Healthcare API.
• לכל פעולת LRO יש תפוקה מקסימלית.
• הפעלת פעולות LRO בו-זמנית באותו משאב עלולה לגרום למאבק על נעילה.
• ב-Cloud Healthcare API יש הגבלה על מספר הפעולות ארוכות הטווח שיכולות לפעול בו-זמנית בפרויקט Google Cloud . מידע נוסף מופיע במאמר בנושא מגבלות על מספר הפעולות ארוכות הטווח.

תכננו את מספר ה-LROs שנדרש לתרחיש לדוגמה שלכם. אם אתם צריכים לחלק מנות גדולות של נתונים לכמה פעולות LRO, כדאי לנסות לצמצם את מספר החלוקות.

תקינות רפרנציאלית של FHIR

השיטה fhirStores.import לא מתייחסת להגדרה disableReferentialIntegrity. כך אפשר לייבא נתונים עם תלות הדדית שרירותית שלא דורשת סידור או קיבוץ, מה שמגדיל את קצב העברת הנתונים. אם נתוני הקלט מכילים הפניות לא תקינות או אם חלק ממשאבי ה-FHIR לא מיובאים, יכול להיות שהמצב של מאגר ה-FHIR לא יעמוד בדרישות של שלמות ההפניות.

כדי להשתמש ב-fhirStores.import, אפליקציית הלקוח צריכה לוודא שההפניות למשאבי FHIR תקפות. לשם כך, צריך לבדוק את הדברים הבאים:

• הנתונים והפורמט של משאב FHIR תקינים
• כל השגיאות שמתרחשות במהלך הייבוא מטופלות

כדי לאכוף את שלמות הקשרים, צריך להשתמש ב-fhir.create או ב-fhir.executeBundle במקום ב-fhirStores.import. מידע נוסף זמין במאמר בנושא ייבוא נתוני FHIR לעומת הפעלת חבילות.

התראות Pub/Sub

חלק מה-methods של Cloud Healthcare API שולחות התראות Pub/Sub על אירועים קליניים, כמו יצירה או מחיקה של משאב בתחום הבריאות. לרשימת השיטות לשליחת התראות Pub/Sub, ראו הגדרת התראות Pub/Sub.

השיטות הבאות לייבוא לא שולחות התראות Pub/Sub:

• dicomStores.import
• fhirStores.import

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

מגבלות על טיפול בשגיאות

יכול להיות שלא כל השגיאות ב-LRO יתועדו ב-Cloud Healthcare API, במיוחד אם ה-LRO מעבד נפחי נתונים גדולים ומפיק הרבה שגיאות. צריך להטמיע דרך למעקב אחרי עיבוד LRO ושגיאות בנפרד. מידע נוסף זמין במאמר בנושא טיפול בשגיאות במשאבים.

נתונים והוספה לאינדקס של חיפושים

יכול להיות שיהיו עיכובים בתוצאות החיפוש בגלל הוספה אסינכרונית לאינדקס של החיפוש. אם LRO יוצר או מעדכן משאב FHIR, יכול להיות שיעבור זמן נוסף עד שהשינויים יהיו זמינים בתוצאות החיפוש.

לדוגמה, חיפוש של משאבי מטופלים במאגר FHIR עשוי שלא להחזיר את כל התוצאות באופן מיידי אחרי פעולת ייבוא של FHIR.

סדר הביצוע

התזמון של LRO מבוסס על Google Cloud זמינות המשאבים. סדר הביצוע והסיום של פעולות LRO לא תמיד זהה לסדר שבו הן נדרשו.

מומלץ להימנע מבקשות ייבוא וייצוא קטנות

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

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

מגבלות על מספר הפעולות ארוכות הטווח (LRO)

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

• סוג ה-LRO.
• כמות המשאבים Google Cloud שהוקצו ל-LRO. ההערכה הזו מבוססת על גודל נתוני הקלט.

אם מריצים יותר מדי פעולות LRO, יכול להיות שיופיעו שגיאות בגלל מגבלות הקצב של Cloud Healthcare API, וקצב העברת הנתונים של פעולות LRO עשוי להיות נמוך יותר. ה-Cloud Healthcare API שומר באופן אוטומטי על משאבים כדי שמספר ה-LROs יישאר במסגרת מגבלות המשאבים. Google Cloud

תהליכי LRO הם תהליכים שפועלים ברקע, ולכן אם העומס מתהליכי LRO מפריע לתהליכים בעדיפות גבוהה יותר, כמו פעולות CRUD, ‏ Cloud Healthcare API יכול להקטין את התפוקה של LRO. כך מוודאים שהתהליכים בעדיפות גבוהה יהיו זמינים.

תקורה של הקצאת משאבים וניקוי

כשמתחיל LRO, ‏ Cloud Healthcare API מקצה משאבים. התהליך הזה יכול להימשך כמה דקות כי Cloud Healthcare API צריך לבצע את הפעולות הבאות:

1. מפעילים תהליך של בקר.
2. הקצאת עובדים ממאגר עובדים.
3. קובעים את גודל נתוני הקלט.
4. מתחילים להקצות עבודה בקנה מידה גדול.

גם עצירה וניקוי של פעולת LRO יכולים להימשך כמה דקות.

בגלל התקורה, פעולת LRO שמעבדת כמות קטנה של נתונים עשויה להקדיש את רוב הזמן להקצאת מאגרי עובדים ולניקוי משאבים.

אם יש לכם הרבה פעולות LRO, יכול להיות שתיתקלו בנפח נתונים נמוך יותר כי יש סיכוי גבוה יותר שתגיעו למגבלות המכסה של הפרויקט שלכם ( Google Cloud).

מגבלות על בקשת מכסת LRO

לפני שמבקשים להגדיל את מכסת ה-LRO, כדאי ליישם את השיטות המומלצות לניהול מכסות. אם אתם עדיין צריכים להגדיל את המכסה, אפשר לפנות אל Google Cloud Customer Care. שיטות מומלצות לשליחת בקשה להגדלת מכסה

יכול להיות שתצטרכו מכסה נוספת אם נתוני הקלט שלכם גדולים, למשל:

• אתם מייבאים מופעי DICOM בגודל של כמה פטה-בייט (PB).
• אתם מייבאים עשרות מיליארדי משאבי FHIR.

סטטוסים של פעולות ארוכות טווח ומצבי כשל

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

• הסתיים בהצלחה ללא שגיאות
• הסתיים בהצלחה עם כמה שגיאות
• הפעולה לא הסתיימה, אבל יכול להיות שהיא הפיקה פלט חלקי לפני שנכשלה

בדוגמה הבאה של JSON מתוארת התגובה שמוחזרת כשפעולת LRO מסתיימת:

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID",
  "metadata": {
    "@type": "METADATA_TYPE",
    "apiMethodName": "API_METHOD_NAME",
    "createTime": "YYYY-MM-DDTHH:MM:SS+ZZ:ZZ",
    "endTime": "YYYY-MM-DDTHH:MM:SS+ZZ:ZZ",
    "logsUrl": "https://console.cloud.google.com/CLOUD_LOGGING_URL"
    "counter": {
      "success": "SUCCESS_COUNT",
      // If there were any failures, they display in the `failure` field.
      "failure": "FAILURE_COUNT"
    }
  },
  "done": true,
  // The `response` field only displays if there were no errors.
  "response": {
    "@type": 
    
  },
  // If there were any errors, an `error` field displays instead of a `response` field.
  // See Troubleshooting long-running operations for a list of response codes.
  "error": {
    "code": ERROR_CODE,
    "message": "DESCRIPTION",
    "details": [
      {
        "@type": "...",
        FIELD1: ...,
        ...
      }
    ]
  }
}

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

ניהול סטטוסים של פעולות ארוכות טווח ומצבי כשל

כדי לנהל את הסטטוס של פעולות LRO ואת מצבי הכשל שלהן, כדאי לפעול לפי השיטות המומלצות הבאות:

• מבצעים שאילתות לגבי פעולות LRO כדי לקבל את הסטטוס שלהן ולוודא שהן הסתיימו. כדי לדגום פעולה ממושכת, צריך להפעיל שוב ושוב את השיטה projects.locations.datasets.operations.get עד שהפעולה מסתיימת. צריך להשתמש בהשהיה מעריכית לפני ניסיון חוזר (exponential backoff) בין כל בקשת בדיקה, למשל 10 שניות. כשהתשובה מכילה את הערך "done": true, הפעולה ארוכת הטווח (LRO) הסתיימה.

• אחרי ש-LRO מסתיים, בודקים אם התשובה מכילה שדה error. אם זה קורה, צריך לקבוע אם לנסות את הפעולה שוב על סמך המידע הבא:

  • קוד השגיאה. במאמר פתרון בעיות שקשורות לפעולות ממושכות (LRO) מפורטים קודי שגיאה ופעולות מומלצות.
  • מספר הניסיונות החוזרים שכבר התרחשו.
  • הזמן שחלף בין תחילת הפעולה ארוכת הטווח לבין השגיאה. לדוגמה, אם פעולה ארוכת טווח שנמשכת בדרך כלל כמה שעות נמשכת כמה ימים ולא מחזירה סטטוס של כשל, יכול להיות שתרצו שבודק אנושי יתערב. מידע נוסף על מקרים שבהם נדרבת התערבות אנושית זמין במאמר תכנון מצבי שגיאה סופיים.

  מידע על ניסיון חוזר של LRO זמין במאמר הוספת LRO לתור.

• אם לא מנסים שוב את הפעולה ארוכת הטווח, אפשר להציג את השדה metadata.counter.failure כדי לראות אם התרחשו שגיאות במשאבים ספציפיים. יכול להיות שאפשר לעבד את המשאבים בנפרד. מידע נוסף זמין במאמר בנושא טיפול בשגיאות שקשורות למשאבים.

טיפול בשגיאות משאבים

פעולת LRO יכולה להסתיים עם שגיאות. שגיאות בתגובת LRO פועלות לפי מודל השגיאות שלGoogle Cloud . התגובה של LRO כוללת קישור ל-Cloud Logging למידע נוסף.

פרטי שגיאה של LRO

לשגיאות LRO ב-Cloud Logging יש את המאפיינים הבאים:

• יומן השגיאות של Cloud Logging לא מכיל את מזהה ה-LRO. משתמשים בשדות operation.id ו-operation.producer כדי למצוא את הסטטוס והשגיאות של ה-LRO. לדוגמה, הפעלות של LRO שמתבצעות מהמתודה projects.locations.datasets.fhirStores.import מכילות את הערך import_fhir בשדה operation.producer.

  אם לכמה פעולות LRO יש את אותם ערכים של operation.id ו-operation.producer, אפשר להשתמש בחותמות הזמן createTime ו-endTime כדי לזהות את פעולת ה-LRO הנכונה.

• לא כל השגיאות של LRO זמינות ב-Cloud Logging. יכול להיות שהערך בשדה metadata.counter.failure יהיה גדול ממספר השגיאות בפועל שנרשמו ביומן, בגלל הסיבות הבאות:

  • מגבלות המכסה של Cloud Logging
  • זמינות השירות של Cloud Logging
  • מגבלות על יומני LRO

  לדוגמה, אם פעולה ארוכת טווח מייבאת 10 מיליון משאבי FHIR, ול-50% מהם יש שגיאות עיצוב, יכול להיות שרק כמה מאות או כמה אלפי שגיאות יתועדו ביומן בגלל הגבלת קצב הבקשות ומכסות של Cloud Logging.

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

ההשלכות של ניסיון חוזר להפעיל LRO

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

נניח ש-fhirStores.import LRO מסתיים עם שגיאות כי חלק ממשאבי ה-FHIR שהוא ניסה לייבא לא היו תקינים. ניסיון חוזר אוטומטי לייבא את אותם נתונים עלול ליצור הרבה שגיאות 409 ALREADY_EXISTS כי חלק ממשאבי FHIR יובאו בפעולה המקורית. אם מבצעים שאילתה על LRO ומגלים שפעולת יצירה נכשלה, לא מנסים שוב באופן אוטומטי. בודק אנושי צריך לבדוק את השגיאות.409 ALREADY_EXISTS

אם הניסיון החוזר מצליח, השדה metadata.counter.failure לא כולל שגיאות מפעולות קודמות. יכול להיות שזה יגרום לספירת שגיאות לא נכונה כי התגובה מהניסיון החוזר המוצלח לא כוללת שגיאות מניסיונות קודמים.

ניסיון חוזר של פעולת LRO

אם יש לכם צינור עיבוד נתונים בצד הלקוח שמזהה שגיאות LRO, אל תשתמשו ב-Cloud Logging. כפי שמוצג בפרטי השגיאה של פעולות ממושכות (LRO), יומני השגיאות של Cloud Logging עבור פעולות ממושכות לא אמינים ולא מלאים. במקום זאת, אפשר להשתמש בטכניקות שמתוארות בקטעים הבאים.

ניסיון חוזר של פעולות ייבוא

כדי לזהות נתונים שלא יובאו, משווים את הנתונים שיובאו ב-Cloud Healthcare API לנתוני המקור שלהם ב-Cloud Storage. אפשר לייבא נתונים באמצעות השיטות הבאות:

• projects.locations.datasets.fhirStores.import
• projects.locations.datasets.dicomStores.import
• projects.locations.datasets.hl7V2Stores.import

כדי להשוות את הנתונים, צריך להשתמש במזהה ייחודי, כמו מספר רשומה רפואית (MRN) עבור משאב FHIR Patient.

במאמר ההשפעות של ניסיון חוזר של LRO מפורטים השלבים שצריך לבצע כשמנסים שוב לבצע פעולת ייבוא.

אם מריצים ייבוא מחדש, יכול להיות שייווצרו מחדש משאבים שמחקתם בעבר. לדוגמה, נבחן את התרחיש הבא:

1. אתם מנסים לייבא מיליון משאבי FHIR. ‫50,000 משאבים נכשלו בגלל שגיאות בפורמט.
2. אתם משקיעים כמה ימים בתיקון שגיאות העיצוב. במהלך התקופה הזו, מטופל מבקש שתסירו את הרשומות שלו.
3. אם תפעילו מחדש את הייבוא, יכול להיות שתיצרו מחדש את נתוני המטופל שמחקתם.

ניסיון חוזר של פעולות ייצוא

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

אפשר לייצא נתונים ל-BigQuery באמצעות השיטות הבאות:

• projects.locations.datasets.fhirStores.export
• projects.locations.datasets.dicomStores.export
• projects.locations.datasets.hl7V2Stores.export

הוספה לתור וניהול של פעולות LRO

אם אתם מריצים פעולות LRO שמעבדות נפחי נתונים גדולים לצורך צירוף או לפי לוח זמנים קבוע, כדאי להטמיע את הטכניקות הבאות להוספת פעולות LRO לתור:

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

• לפתור באופן אוטומטי את השגיאות בטיפול בשגיאות במשאבים כשזה אפשרי.

  • כדאי להבין את תרחיש השימוש של ייבוא FHIR כדי להחליט אם להתעלם משגיאות 409 ALREADY_EXISTS או לבצע פעולות CRUD נפרדות כדי לפתור את השגיאות. כפי שמוצג בפרטי שגיאה של פעולות ממושכות (LRO), יכול להיות שחלק מהשגיאות מסוג 409 ALREADY_EXISTS לא יתועדו ב-Cloud Logging. אם האפליקציה שלכם מסתמכת על יומני שגיאות, כדאי להשתמש באחת מהטכניקות שמוסברות במאמר בנושא ניסיון חוזר של פעולת LRO.

  • כדי לפתור כמה שגיאות, אפשר להוסיף לתור פעולת LRO קטנה יותר עבור הנתונים שבהם נתגלו השגיאות, או לבצע פעולות CRUD נפרדות.

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

• זיהוי אוטומטי של הצורך בהתערבות אנושית כדי לטפל בשגיאות. צריכים להיות לכם כלים ומדריכים לתפעול לאדמינים של המערכת. דוגמאות למשימות לטיפול בשגיאות:

  • קביעת מועד חדש לפעולת LRO.
  • לתזמן מחדש קבוצת משנה של נתונים מ-LRO קודם.
  • בודקים את השגיאות ופותרים בעיות שקשורות לרכיבי נתונים ספציפיים. אפשר לבצע את המשימה הזו רק אם אפשר לקבוע שכל השגיאות ב-LRO נרשמו ביומן.

• קביעת לוחות זמנים של LRO. יכול להיות שתתזמנו פעולות LRO כדי להימנע מהרצה בשעות השיא שבהן פועלות הרבה פעולות CRUD. איך מנהלים את המכסות כדי למקסם את קצב העברת הנתונים

מעקב וקבלת התראות

יצירה ותחזוקה של נהלים למעקב אחרי פעולות LRO ולפתרון התראות. ההתראות נובעות בעיקר מסטטוסים של פעולות LRO ומבעיות בהוספה לתור. הנה כמה מצבים שצריך להתייחס אליהם בנוהלים:

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