מניעת התנגשויות במשאבי FHIR באמצעות תגי ETags

בדף הזה מוסבר איך להשתמש בתגי ישות (ETags) לניהול מקביליות עם משאבי FHIR ב-Cloud Healthcare API. תגי ETag עוזרים למנוע אובדן נתונים ולשפר את ביצועי האפליקציה על ידי הפעלה של בקרת בו-זמניות אופטימית ושל שמירת נתונים במטמון בצד הלקוח.

הסבר על ETags

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

אפשר להשתמש ב-ETags כדי לוודא תקינות נתונים ולבצע אופטימיזציה של הביצועים במצבים הבאים:

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

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

    • ‫If-Match: הבקשה מצליחה רק אם ה-ETag שסופק תואם ל-ETag הנוכחי בשרת. כך תוכלו לוודא שאתם מעדכנים את הגרסה הצפויה של משאב ה-FHIR.
    • ‫If-None-Match: הבקשה מצליחה רק אם ה-ETag שסופק לא תואם ל-ETag הנוכחי בשרת. כך תוכלו לדעת אם הגרסה של משאב ששמורה במטמון המקומי עדיין עדכנית, ולצמצם את הצורך באחזור המשאב המלא מהשרת בכל פעם. השיטה הזו נפוצה לשימוש יעיל במטמון.

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

קבלת ETag

בדוגמאות הבאות אפשר לראות איך מקבלים את ה-ETag של משאב FHIR.

תג ה-ETag נכלל בכותרת תגובת ה-HTTP המלאה כשמקבלים את התוכן של משאב FHIR. ה-ETag תואם ל-Meta.versionId במשאב FHIR.

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

  • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud
  • ‫LOCATION: המיקום של מערך הנתונים
  • ‫DATASET_ID: מערך הנתונים הראשי של מאגר FHIR
  • ‫FHIR_STORE_ID: מזהה מאגר ה-FHIR
  • ‫FHIR_RESOURCE_TYPE: סוג משאב FHIR
  • ‫FHIR_RESOURCE_ID: מזהה משאב FHIR

curl

משתמשים בשיטה fhir.read. הדגל -verbose מחזיר את כותרות ה-HTTP בתגובה, שמכילות את ה-ETag.

curl -X GET \
    -verbose \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/FHIR_RESOURCE_TYPE/FHIR_RESOURCE_ID"

התשובה מכילה את הפרטים הבאים:

< etag: W/"ETAG_VALUE"

PowerShell

משתמשים בשיטה fhir.read. הדגל -Headers מחזיר את כותרות ה-HTTP בתגובה, שמכילות את ה-ETag.

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

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/FHIR_RESOURCE_TYPE/FHIR_RESOURCE_ID" | Select-Object -Expand Headers

התשובה מכילה את הפרטים הבאים:

ETag                   {W/"ETAG_VALUE"}

ניהול של פעולות מקבילות בעדכון משאב FHIR

בדוגמאות הבאות אפשר לראות איך לכלול ETag כשמעדכנים משאב FHIR.

בדוגמאות נעשה שימוש ב-If-Match, עם ההתנהגות הבאה:

  • אם ה-ETag תואם ל-ETag הנוכחי של משאב ה-FHIR בשרת, העדכון מצליח והשרת יוצר ETag חדש למשאב המעודכן. כך תוכלו לוודא שאתם מעדכנים את הגרסה הצפויה של משאב ה-FHIR.

  • אם ערך ה-ETag לא תואם, העדכון נכשל ומופיעה השגיאה 412 Precondition Failed, שמעידה על כך שלקוח אחר שינה את המשאב מאז שערך ה-ETag המקורי אוחזר. כך נמנע אובדן נתונים כתוצאה משכתוב בטעות.

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

  • ‫ETAG_VALUE: ערך ה-ETag של משאב ה-FHIR
  • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud
  • ‫LOCATION: המיקום של מערך הנתונים
  • ‫DATASET_ID: מערך הנתונים הראשי של מאגר FHIR
  • ‫FHIR_STORE_ID: מזהה מאגר ה-FHIR
  • ‫FHIR_RESOURCE_TYPE: סוג משאב FHIR
  • ‫FHIR_RESOURCE_ID: מזהה משאב FHIR

curl

משתמשים בשיטה fhir.update.

curl -X PUT \
    -H "If-Match: W/\"ETAG_VALUE\"" \
    -H "Content-Type: application/json; charset=utf-8" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -d @request.json \
    "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/FHIR_RESOURCE_TYPE/FHIR_RESOURCE_ID"

התשובה מכילה את משאב ה-FHIR המעודכן.

PowerShell

משתמשים בשיטה fhir.update.

$cred = gcloud auth print-access-token
$etag = W/\"ETAG_VALUE\""
$headers = @{
  "Authorization" = "Bearer $cred"
  "If-Match"      = "$etag"}

Invoke-WebRequest `
    -Method PUT `
    -Headers $headers `
    -InFile request.json `
    -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/FHIR_RESOURCE_TYPE/FHIR_RESOURCE_ID" | Select-Object -Expand Content

התשובה מכילה את משאב ה-FHIR המעודכן.

הטמעה של שמירת נתונים במטמון בצד הלקוח

אתם יכולים להשתמש ב-ETags כדי להטמיע שמירת נתונים במטמון בצד הלקוח. כך תוכלו להאיץ את אחזור הנתונים ולשפר את חוויית המשתמש.

כדי לאחזר משאב FHIR ששמור במטמון, אפשר לכלול את ה-ETag ששמור במטמון בכותרת If-None-Match, שפועלת באופן הבא:

  • אם ערכי ה-ETag זהים, השרת משיב עם 304 Not Modified, והלקוח משתמש בעותק שנשמר במטמון. כך נחסך רוחב פס והעומס על השרת יפחת.

  • אם ערכי ה-ETag לא זהים, השרת שולח את משאב ה-FHIR המעודכן ואת ה-ETag החדש שלו, וכך הלקוח יכול לרענן את המטמון שלו.

בדוגמאות הבאות אפשר לראות איך מקבלים את התוכן של משאב FHIR באמצעות ETag שתואם ל-ETag בשרת.

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

  • ‫ETAG_VALUE: ערך ה-ETag של משאב ה-FHIR
  • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud
  • ‫LOCATION: המיקום של מערך הנתונים
  • ‫DATASET_ID: מערך הנתונים הראשי של מאגר FHIR
  • ‫FHIR_STORE_ID: מזהה מאגר ה-FHIR
  • ‫FHIR_RESOURCE_TYPE: סוג משאב FHIR
  • ‫FHIR_RESOURCE_ID: מזהה משאב FHIR

curl

משתמשים בשיטה fhir.read. הדגל -verbose מחזיר את כותרות ה-HTTP בתגובה, אחרת לא מוחזרת תגובה.

curl -X GET \
    -H "If-None-Match: W/\"ETAG_VALUE\"" \
    -v \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/FHIR_RESOURCE_TYPE/FHIR_RESOURCE_ID"

התשובה מכילה קוד סטטוס 304 Not Modified.

PowerShell

משתמשים בשיטה fhir.read. הדגל -Headers מחזיר את כותרות ה-HTTP בתגובה, אחרת לא מוחזרת תגובה.

$cred = gcloud auth print-access-token
$etag = W/\"ETAG_VALUE\""
$headers = @{
"Authorization" = "Bearer $cred"
  "If-None-Match"      = "$etag"}

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/FHIR_RESOURCE_TYPE/FHIR_RESOURCE_ID" | Select-Object -Expand Headers

התשובה מכילה קוד סטטוס 304 Not Modified.