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 Zugriffsbestimmungen auf zurückgegeben werden. 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 nur zurück, ob der Zugriff auf die angegebenen Daten vom Einwilligungen ausgewertet. Diese optionale Funktion wird verwendet, wenn Ihre Anwendung prüfen muss, wie eine Einwilligungsentscheidung getroffen wurde.
  • Eine optionale Liste von ACTIVE- oder DRAFT-Einwilligungen für die zu berücksichtigende Methode. Wenn keine Einwilligungen angegeben sind, werden alle ACTIVE-Einwilligungen mit der Methode ausgewertet. Dieses optionale Funktion kann verwendet werden, um das Verhalten neuer oder bestimmter Einwilligungen zu 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"

Ist die Anfrage erfolgreich, gibt der Server eine Antwort wie die folgende im JSON-Format oder einen leeren Antworttext zurück, falls keine Nutzerdaten mit dem angegebenen Datenzugriff übereinstimmen. 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

Ist die Anfrage erfolgreich, gibt der Server eine Antwort wie die folgende im JSON-Format oder einen leeren Antworttext zurück, falls keine Nutzerdaten mit dem angegebenen Datenzugriff übereinstimmen. 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.

Zugriffsbestimmungen für alle Einwilligungen eines Nutzers ermitteln

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 Zugriffsbestimmungen zurückgegeben werden sollen. Wenn dieses Flag auf FULL gesetzt ist, gibt die Methode Ergebnisse für wird jede Einwilligung ausgewertet. Wenn dieses Flag auf BASIC gesetzt oder nicht definiert ist, gibt nur zurück, ob der Zugriff auf die angegebenen Daten vom Einwilligungen ausgewertet. Diese optionale Funktion wird verwendet, wenn Ihre Anwendung prüfen muss, wie die Einwilligungserklärung getroffen wurde.
  • Eine optionale Liste von ACTIVE- oder DRAFT-Einwilligungen für die zu berücksichtigende Methode. Wenn keine Einwilligungen angegeben sind, werden alle ACTIVE-Einwilligungen mit der Methode ausgewertet. Dieses optionale Funktion kann verwendet werden, um das Verhalten neuer oder bestimmter Einwilligungen zu 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"

Ist die Anfrage erfolgreich, gibt der Server eine Antwort wie die folgende im JSON-Format oder einen leeren Antworttext zurück, falls keine Nutzerdaten mit dem angegebenen Datenzugriff übereinstimmen. In der Beispielantwort wird FULL als 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

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

Ist die Anfrage erfolgreich, gibt der Server eine Antwort wie die folgende im JSON-Format oder einen leeren Antworttext zurück, falls keine Nutzerdaten mit dem angegebenen Datenzugriff übereinstimmen. 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, an dem die Ergebnisliste gespeichert wird. Die Cloud Healthcare API-Dienstkonto muss die roles/storage.objectAdmin IAM-Rolle für dieses Ziel. 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

Sind Auditlogs zum Datenzugriff aktiviert, schreibt die Consent Management API Anfragen, die mit einer der Methoden checkDataAccess, evaluateUserConsents oder queryAccessibleData ausgeführt wurden. In diesen Logs werden die in der Anfrage enthaltenen Informationen aufgezeichnet, z. B. die Ziel-UserDataMapping oder die angegebenen RESOURCE- oder REQUEST-Attribute. Logs enthalten auch die API-Antwort, die das Ergebnis der Zugriffsbestimmung 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.