Zugangsentscheidungen treffen

Auf dieser Seite wird beschrieben, wie Sie mithilfe der Consent Management API Zugriffsentscheidungen festlegen.

Anwendungen können von der Consent Management API Zugriffsentscheidungen für ein bestimmtes Datenelement, für alle einem Nutzer zugeordneten Datenelemente, oder für ganze Datenspeicher anfordern. Für ihre Zugriffsentscheidung bewertet die Consent Management API jeweils folgende Informationen im Licht der Informationen in der Zugriffsanfrage:

  • Die Nutzereinwilligung, z. B. die Werte der Attribute REQUEST.
  • Die Zuordnungen von Nutzerdaten, z. B. die Werte von RESOURCE-Attributen.

Standardmäßig werden bei der Auswahl der Zugriffsentscheidung nur ACTIVE-Zustimmungen ausgewertet. Um DRAFT-Genehmigungen in eine Zugriffsentscheidung einzubeziehen, müssen diese in der Anfrage zur Zugriffsentscheidung angeben werden.

Bei Anfragen zur Zugriffsentscheidungen werden Einwilligungen, die abgelaufen sind, widerrufen oder abgelehnt wurden, immer ignoriert.

Mit der Methode projects.locations.datasets.consentStores.checkDataAccess können Sie eine Zugriffsentscheidung für ein bestimmtes Datenelement anfordern. Diese Methode gibt eine Meldung zurück, die angibt, ob die angegebene UserDataMapping für die vorgeschlagene Verwendung eine gültige Einwilligung hat.

Wenn Sie eine Zugriffsentscheidung für ein bestimmtes Datenelement anfordern möchten, stellen Sie eine POST-Anfrage und geben Sie die folgenden Informationen in der Anfrage an:

  • Der Name des übergeordneten Einwilligungsspeichers.
  • Eine Datenressourcen-ID, also eine Beschreibung des Datenelements, z. B. der REST-Pfad zu einer Ressource.
  • Eine Reihe von Schlüssel/Wert-Paaren, die den Anfragenden in Bezug auf die relevanten REQUEST-Attribute und deren Werte darstellen. Beispiel: requesterIdentity == external-researcher
  • Ein optionales Flag, das angibt, ob detaillierte Zugriffsentscheidungen zurückgegeben werden sollen. Wenn dieses Flag auf FULL gesetzt ist, gibt die Methode Ergebnisse für jede ausgewertete Einwilligung zurück. Wenn dieses Flag auf BASIC gesetzt oder nicht definiert ist, gibt die Methode nur zurück, ob der Zugriff auf die angegebenen Daten durch die ausgewerteten Einwilligungen zulässig ist. Diese optionale Funktion wird verwendet, wenn Ihre Anwendung prüfen muss, wie eine Einwilligungsentscheidung getroffen wurde.
  • Eine optionale Liste an ACTIVE- oder DRAFT-Einwilligungen für die zu berücksichtigende Methode. Sind keine Einwilligungen angegeben, wertet die Methode alle ACTIVE-Einwilligungen aus. Mit dieser optionalen Funktion können Sie das Verhalten neuer oder bestimmter Einwilligungen testen.
  • Ein Zugriffstoken

curl

Das folgende Beispiel zeigt eine POST-Anfrage mit 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"

Wenn die Anfrage erfolgreich ist, gibt der Server eine Antwort wie folgende im JSON-Format zurück. Stimmen keine Nutzerdaten mit dem angegebenen Datenzugriff überein, so wird ein leerer Antworttext zurückgegeben. In der Beispielantwort wird FULL als responseView verwendet.

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

EVALUATION_RESULT ist entweder NOT_APPLICABLE, NO_MATCHING_POLICY, NO_SATISFIED_POLICY oder HAS_SATISFIED_POLICY.

PowerShell

Das folgende Beispiel zeigt eine POST-Anfrage mit 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

Wenn die Anfrage erfolgreich ist, gibt der Server eine Antwort wie folgende im JSON-Format zurück. Stimmen keine Nutzerdaten mit dem angegebenen Datenzugriff überein, so wird ein leerer Antworttext zurückgegeben. In der Beispielantwort wird FULL als responseView verwendet.

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

EVALUATION_RESULT ist entweder NOT_APPLICABLE, NO_MATCHING_POLICY, NO_SATISFIED_POLICY oder HAS_SATISFIED_POLICY.

Zugriffsentscheidungen für alle Einwilligungen eines Nutzers treffen

Mit der Methode projects.locations.datasets.consentStores.evaluateUserConsents können Sie eine Zugriffsentscheidung für alle einem Nutzer zugeordneten Datenelemente anfordern. Diese Methode gibt alle mit einem bestimmten Nutzer verknüpften Datenelemente zurück, die eine gültige Einwilligung für die vorgeschlagene Verwendung haben.

Um eine Zugriffsentscheidung für alle Datenelemente anzufordern, die einem Nutzer zugeordnet sind, führen Sie eine POST-Anfrage aus und geben folgende Informationen in der Anfrage an:

  • Der Name des übergeordneten Einwilligungsspeichers.
  • Eine Nutzer-ID, die die Datenelemente und festzulegenden Einwilligungen definiert.
  • Ein optionaler Satz an Schlüssel/Wert-Paaren, die die RESOURCE-Attribute der auszuwertenden Datenelemente definieren. Beispiel: dataIdentifiable == de-identified. Wenn Sie keinen RESOURCE-Attributsatz definieren, werden alle Datenelemente ausgewertet.
  • Eine Reihe Schlüssel/Wert-Paare, die die relevanten REQUEST-Attribute und deren Werte definieren. Beispiel: requesterIdentity == external-researcher.
  • Ein optionales Flag, das angibt, ob detaillierte Zugriffsentscheidungen zurückgegeben werden sollen. Wenn dieses Flag auf FULL gesetzt ist, gibt die Methode Ergebnisse für jede ausgewertete Einwilligung zurück. Wenn dieses Flag auf BASIC gesetzt oder nicht definiert ist, gibt die Methode nur zurück, ob der Zugriff auf die angegebenen Daten durch die ausgewerteten Einwilligungen zulässig ist. Diese optionale Funktion wird verwendet, wenn Ihre Anwendung prüfen muss, wie eine Einwilligungsentscheidung getroffen wurde.
  • Eine optionale Liste an ACTIVE- oder DRAFT-Einwilligungen für die zu berücksichtigende Methode. Sind keine Einwilligungen angegeben, wertet die Methode alle ACTIVE-Einwilligungen aus. Mit dieser optionalen Funktion können Sie das Verhalten neuer oder bestimmter Einwilligungen testen.
  • Ein Zugriffstoken

curl

Das folgende Beispiel zeigt eine POST-Anfrage mit 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"

Wenn die Anfrage erfolgreich ist, gibt der Server eine Antwort wie folgende im JSON-Format zurück. Stimmen keine Nutzerdaten mit dem angegebenen Datenzugriff überein, so wird ein leerer Antworttext zurückgegeben. In der Beispielantwort wird FULL als responseView verwendet.

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

PowerShell

Das folgende Beispiel zeigt eine POST-Anfrage mit 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

Wenn die Anfrage erfolgreich ist, gibt der Server eine Antwort wie folgende im JSON-Format zurück. Stimmen keine Nutzerdaten mit dem angegebenen Datenzugriff überein, so wird ein leerer Antworttext zurückgegeben. In der Beispielantwort wird FULL als responseView verwendet.

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

Mit der Methode projects.locations.datasets.consentStores.queryAccessibleData können Sie eine Zugriffsentscheidung für einen gesamten Einwilligungsspeicher anfragen. Diese Methode gibt alle Datenelemente innerhalb eines Einwilligungsspeichers mit gültiger Einwilligung zurück.

Wenn Sie eine Zugriffsentscheidung für einen gesamten Consent-Speicher anfragen möchten, stellen Sie eine POST-Anfrage und geben Sie die folgenden Informationen in der Anfrage an:

  • Der Name des übergeordneten Einwilligungsspeichers
  • Eine Reihe Schlüssel/Wert-Paare, die die relevanten REQUEST-Attribute und deren Werte definieren. Beispiel: requesterIdentity == external-researcher.
  • Ein optionaler Satz an Schlüssel/Wert-Paaren, die die RESOURCE-Attribute der auszuwertenden Datenelemente definieren. Beispiel: dataIdentifiable == de-identified. Wenn Sie keinen RESOURCE-Attributsatz definieren, werden alle Datenelemente ausgewertet.
  • Ein Cloud Storage-Ziel, in dem die Ergebnisliste gespeichert wird. Das Cloud Healthcare API-Dienstkonto muss an diesem Ziel die IAM-Rolle roles/storage.objectAdmin haben. Weitere Informationen finden Sie unter Cloud Storage-Berechtigungen für Einwilligungsspeicher.
  • Ein Zugriffstoken

curl

Das folgende Beispiel zeigt eine POST-Anfrage mit 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"

Wenn die Anfrage erfolgreich ist, gibt der Server eine Antwort wie die folgende im JSON-Format zurück:

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

Die Antwort enthält einen Vorgangsnamen. Mit der Methode Operation get können Sie den Status des Vorgangs verfolgen:

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"

Wenn die Anfrage erfolgreich ist, gibt der Server eine Antwort mit dem Status des Vorgangs im JSON-Format zurück:

{
  "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"
  }
}

Nachdem der Vorgang mit langer Ausführungszeit abgeschlossen wurde, werden die Ergebnisse in einer Textdatei im angegebenen Ordner angezeigt. Weitere Informationen zu Vorgängen mit langer Ausführungszeit finden Sie unter Vorgänge mit langer Ausführungszeit verwalten.

PowerShell

Das folgende Beispiel zeigt eine POST-Anfrage mit 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

Wenn die Anfrage erfolgreich ist, gibt der Server eine Antwort wie die folgende im JSON-Format zurück:

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

Die Antwort enthält einen Vorgangsnamen. Mit der Methode Operation get können Sie den Status des Vorgangs verfolgen:

$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

Wenn die Anfrage erfolgreich ist, gibt der Server eine Antwort mit dem Status des Vorgangs im JSON-Format zurück:

{
  "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"
  }
}

Nachdem der Vorgang mit langer Ausführungszeit abgeschlossen wurde, werden die Ergebnisse in einer Textdatei im angegebenen Ordner angezeigt. Weitere Informationen zu Vorgängen mit langer Ausführungszeit finden Sie unter Vorgänge mit langer Ausführungszeit verwalten.

Logging der Anfragen und Antworten für die Zugriffsermittlung

Falls Auditlogs zum Datenzugriff aktiviert sind, protokolliert die Consent Management API Anfragen, die mit den Methoden checkDataAccess, evaluateUserConsents und queryAccessibleData gemacht wurden. In diesen Logs werden die in der Anfrage enthaltenen Informationen aufgezeichnet, z. B. der Ziel-UserDataMapping oder die angegebenen RESOURCE- oder REQUEST-Attribute. Logs enthalten auch die API-Antwort, die das Ergebnis der Zugriffsentscheidung der Consent Management API enthält. Jedes Log enthält die Identität des Google Cloud-Tools, von dem die Anfrage stammt.

Weitere Informationen zum Aktivieren von Audit-Logs zum Datenzugriff finden Sie unter Audit-Logs zum Datenzugriff konfigurieren. Weitere Informationen zum Audit-Logging in der Cloud Healthcare API finden Sie unter Cloud-Audit-Logs ansehen.