קביעת גישה

בדף הזה מוסבר איך לקבוע את הגישה באמצעות Consent Management API.

אפליקציות יכולות לבקש קביעת גישה מ-Consent Management API (ממשק API לניהול הסכמה) לרכיב נתונים ספציפי, לכל רכיבי הנתונים שמשויכים למשתמש או למאגרי נתונים שלמים. בכל מקרה, Consent Management API קובע אם לאשר גישה על סמך הערכת המידע הבא בהשוואה למידע שכלול בבקשת הגישה:

  • הסכמת המשתמש, כמו הערכים של מאפייני REQUEST
  • מיפויי נתוני המשתמשים, כמו הערכים של מאפייני RESOURCE.

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

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

אפשר לבקש קביעת גישה לרכיב נתונים ספציפי באמצעות השיטה projects.locations.datasets.consentStores.checkDataAccess. השיטה הזו מחזירה הודעה שמציינת אם למשתמש UserDataMapping שצוין יש הסכמה תקפה לשימוש המוצע.

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

  • השם של מאגר הסכמת ההורה.
  • מזהה של מקור נתונים, שהוא תיאור של רכיב הנתונים, כמו נתיב REST למשאב.
  • קבוצה של צמדי מפתח/ערך שמייצגים את השולח במונחים של מאפייני REQUEST רלוונטיים והערכים שלהם. לדוגמה, requesterIdentity == external-researcher.
  • סימון אופציונלי שמציין אם צריך להחזיר קביעות גישה מפורטות. אם הדגל הזה מוגדר לערך FULL, הפונקציה מחזירה תוצאות לכל הסכמה שנבדקה. אם הדגל הזה מוגדר לערך BASIC או לא מוגדר, השיטה מחזירה רק את המידע אם הגישה לנתונים שצוינו מותרת על ידי ההסכמות שנבדקו. התכונה האופציונלית הזו משמשת כשהאפליקציה צריכה לבדוק איך נקבע סטטוס ההסכמה.
  • רשימה אופציונלית של הסכמות מסוג ACTIVE או DRAFT שהשיטה צריכה להתייחס אליהן. אם לא מציינים הסכמות, השיטה מעריכה את כל ההסכמות מסוג ACTIVE. אפשר להשתמש בתכונה האופציונלית הזו כדי לבדוק את ההתנהגות של הסכמות חדשות או ספציפיות.
  • טוקן גישה

curl

בדוגמה הבאה מוצגת בקשת POST באמצעות curl:

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: application/consent+json; charset=utf-8" \
    --data "{
       'dataId' : 'DATA_ID',
       'requestAttributes': {
         'requesterIdentity': 'external-researcher'},
       'consentList':{
         'consents':[
           'projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID/consents/CONSENT_NAME'
         ]
       },
       'responseView': 'DETAILED_ACCESS_LEVEL'
    }" \
"https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID:checkDataAccess"

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

{
  "consentDetails": {                                                                                                                         "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID/consents/CONSENT_ID": {
      "evaluationResult": "EVALUATION_RESULT"
    }
  }
}

‫EVALUATION_RESULT הוא אחד מהערכים הבאים: NOT_APPLICABLE, ‏NO_MATCHING_POLICY, ‏NO_SATISFIED_POLICY או HAS_SATISFIED_POLICY.

PowerShell

בדוגמה הבאה מוצגת בקשת POST באמצעות Windows PowerShell:

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

Invoke-WebRequest `
  -Method Post `
  -Headers $headers `
  -ContentType: "application/consent+json; charset=utf-8" `
  -Body "{
       'dataId' : 'DATA_ID',
       'requestAttributes': {
         'requesterIdentity': 'external-researcher'
       },
       'consentList': {
         'consents':[
           'projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID/consents/CONSENT_ID'
         ]
       },
       'responseView': 'DETAILED_ACCESS_LEVEL'
    }" `
  -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID:checkDataAccess" | Select-Object -Expand Content

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

{
  "consentDetails": {                                                                                                                         "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID/consents/CONSENT_ID": {
      "evaluationResult": "EVALUATION_RESULT"
    }
  }
}

‫EVALUATION_RESULT הוא אחד מהערכים הבאים: NOT_APPLICABLE, ‏NO_MATCHING_POLICY, ‏NO_SATISFIED_POLICY או HAS_SATISFIED_POLICY.

קביעת גישה לכל ההסכמות של משתמש

אפשר לבקש קביעת גישה לכל רכיבי הנתונים שמשויכים למשתמש באמצעות השיטה projects.locations.datasets.consentStores.evaluateUserConsents. השיטה הזו מחזירה את כל רכיבי הנתונים שמשויכים למשתמש ספציפי, שיש לגביהם הסכמה תקפה לשימוש המוצע.

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

  • השם של מאגר הסכמת ההורה.
  • מזהה משתמש שמגדיר את רכיבי הנתונים ואת ההסכמות שצריך להעריך.
  • קבוצה אופציונלית של צמדי מפתח/ערך שמגדירים את מאפייני RESOURCE של רכיבי הנתונים להערכה. לדוגמה, dataIdentifiable == de-identified. אם לא מגדירים קבוצה של מאפייני RESOURCE, כל רכיבי הנתונים מוערכים.
  • קבוצה של צמדי מפתח/ערך שמגדירים את REQUEST המאפיינים הרלוונטיים ואת הערכים שלהם. לדוגמה, requesterIdentity == external-researcher.
  • סימון אופציונלי שמציין אם צריך להחזיר קביעות גישה מפורטות. אם הדגל הזה מוגדר לערך FULL, הפונקציה מחזירה תוצאות לכל הסכמה שנבדקה. אם הדגל הזה מוגדר לערך BASIC או לא מוגדר, השיטה מחזירה רק את המידע אם הגישה לנתונים שצוינו מותרת על ידי ההסכמות שנבדקו. התכונה האופציונלית הזו משמשת כשהאפליקציה צריכה לבדוק איך נקבע סטטוס ההסכמה.
  • רשימה אופציונלית של הסכמות מסוג ACTIVE או DRAFT שהשיטה צריכה להתייחס אליהן. אם לא מציינים הסכמות, השיטה מעריכה את כל ההסכמות מסוג ACTIVE. אפשר להשתמש בתכונה האופציונלית הזו כדי לבדוק את ההתנהגות של הסכמות חדשות או ספציפיות.
  • טוקן גישה

curl

בדוגמה הבאה מוצגת בקשת POST באמצעות curl:

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: application/consent+json; charset=utf-8" \
    --data "{
       'userId' :
         'USER_ID',
       'consentList':{
         'consents':[
           'projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID/consents/CONSENT_ID'
         ]
       },
       'resourceAttributes': {
         'dataIdentifiable': 'de-identified'
       },
       'requestAttributes': {
         'requesterIdentity': 'external-researcher'
       },
       'responseView': 'DETAILED_ACCESS_LEVEL'
    }" \
"https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID:evaluateUserConsents"

אם הבקשה מצליחה, השרת מחזיר תגובה שדומה לדוגמה הבאה בפורמט JSON, או גוף תגובה ריק אם אין נתוני משתמש שתואמים לגישה לנתונים שצוינה. בדוגמה לתשובה נעשה שימוש ב-FULL בתור responseView.

{
  "results": [
    {
      "dataId": "DATA_ID",
      "consentDetails": {
       "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID/consents/CONSENT_ID": {
       "evaluationResult": "EVALUATION_RESULT"
        }
      }
    }
  ]
}

PowerShell

בדוגמה הבאה מוצגת בקשת POST באמצעות Windows PowerShell:

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

Invoke-WebRequest `
  -Method Post `
  -Headers $headers `
  -ContentType: "application/consent+json; charset=utf-8" `
  -Body "{
       'userId' : 'USER_ID',
       'consentList':{
         'consents':[
           'projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID/consents/CONSENT_NAME'
         ]
       },
       'resourceAttributes': { 'dataIdentifiable': 'de-identified'},
       'requestAttributes': { 'requesterIdentity': 'external-researcher'},
       'responseView': 'DETAILED_ACCESS_LEVEL'
    }" `
  -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID:evaluateUserConsents" | Select-Object -Expand Content

אם הבקשה מצליחה, השרת מחזיר תגובה שדומה לדוגמה הבאה בפורמט JSON, או גוף תגובה ריק אם אין נתוני משתמש שתואמים לגישה לנתונים שצוינה. בדוגמה לתשובה נעשה שימוש ב-FULL בתור responseView.

{
  "results": [
    {
      "dataId": "DATA_ID",
      "consentDetails": {
       "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID/consents/CONSENT_ID": {
       "evaluationResult": "EVALUATION_RESULT"
        }
      }
    }
  ]
}

אפשר לבקש קביעת גישה למאגר הסכמה שלם באמצעות השיטה projects.locations.datasets.consentStores.queryAccessibleData. ה-method הזה מחזיר את כל רכיבי הנתונים במאגר ההסכמות שיש להם הסכמה תקפה.

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

  • השם של מאגר הסכמת ההורה
  • קבוצה של צמדי מפתח/ערך שמגדירים את REQUEST המאפיינים הרלוונטיים ואת הערכים שלהם. לדוגמה, requesterIdentity == external-researcher.
  • קבוצה אופציונלית של צמדי מפתח/ערך שמגדירים את מאפייני RESOURCE של רכיבי הנתונים להערכה. לדוגמה, dataIdentifiable == de-identified. אם לא מגדירים קבוצה של מאפייני RESOURCE, כל רכיבי הנתונים נבדקים
  • יעד ב-Cloud Storage שבו נשמרת רשימת התוצאות. לחשבון השירות של Cloud Healthcare API צריך להיות התפקיד roles/storage.objectAdmin ב-IAM ביעד הזה. מידע נוסף זמין במאמר הרשאות Cloud Storage למאגר הסכמה.
  • טוקן גישה

curl

בדוגמה הבאה מוצגת בקשת POST באמצעות curl:

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: application/consent+json; charset=utf-8" \
    --data "{
       'gcsDestination': {
         'uriPrefix': 'gs://BUCKET/DIRECTORY'
       },
       'resourceAttributes': {
         'dataIdentifiable': 'de-identified'
       },
       'requestAttributes': {
         'requesterIdentity': 'external-researcher'
       }
    }" \
"https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID:queryAccessibleData"

אם הבקשה מצליחה, השרת מחזיר תגובה שדומה לדוגמה הבאה בפורמט JSON:

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID"
}

התשובה מכילה שם פעולה. כדי לעקוב אחרי סטטוס הפעולה, אפשר להשתמש ב-method‏ Operation get:

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID"

אם הבקשה מצליחה, השרת מחזיר תגובה עם סטטוס הפעולה בפורמט JSON:

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.healthcare.v1beta1.OperationMetadata",
    "apiMethodName": "google.cloud.healthcare.v1beta1.consent.consentService.queryAccessibleData",
    "createTime": "CREATE_TIME",
    "endTime": "END_TIME"
    "logsUrl": "LOGS_URL",
    "counter": {
      "success": "SUCCESS_COUNT"
    }
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.protobuf.Empty"
  }
}

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

PowerShell

בדוגמה הבאה מוצגת בקשת POST באמצעות Windows PowerShell:

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

Invoke-WebRequest `
  -Method Post `
  -Headers $headers `
  -ContentType: "application/consent+json; charset=utf-8" `
  -Body "{
       'gcsDestination': {
         'uriPrefix': 'gs://BUCKET/DIRECTORY'
       },
       'resourceAttributes': {
         'dataIdentifiable': 'de-identified'
       },
       'requestAttributes': {
         'requesterIdentity': 'external-researcher'
       }
    }" `
  -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/consentStores/CONSENT_STORE_ID:queryAccessibleData" | Select-Object -Expand Content

אם הבקשה מצליחה, השרת מחזיר תגובה שדומה לדוגמה הבאה בפורמט JSON:

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID"
}

התשובה מכילה שם פעולה. כדי לעקוב אחרי סטטוס הפעולה, אפשר להשתמש ב-method‏ Operation get:

$cred = gcloud auth application-default 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/operations/OPERATION_ID" | Select-Object -Expand Content

אם הבקשה מצליחה, השרת מחזיר תגובה עם סטטוס הפעולה בפורמט JSON:

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.healthcare.v1beta1.OperationMetadata",
    "apiMethodName": "google.cloud.healthcare.v1beta1.consent.consentService.queryAccessibleData",
    "createTime": "CREATE_TIME",
    "endTime": "END_TIME"
    "logsUrl": "LOGS_URL",
    "counter": {
      "success": "SUCCESS_COUNT"
    }
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.protobuf.Empty"
  }
}

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

רישום של בקשות לקביעת גישה ותשובות

כשמופעלים יומני ביקורת של גישה לנתונים, Consent Management API מתעד בקשות שמתבצעות באמצעות ה-methods‏ checkDataAccess‏, evaluateUserConsents ו-queryAccessibleData. היומנים האלה מתעדים את המידע שכלול בבקשה, כמו מאפיין היעד UserDataMapping או המאפיינים שצוינו RESOURCE או REQUEST. היומנים יכללו גם את התגובה של ה-API, שכוללת את התוצאה של קביעת הגישה ל-Consent Management API. כל יומן כולל את הזהות של כלי Google Cloud ששולח את הבקשה.

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