控管 Cloud Healthcare API 中 FHIR 資源的存取權

本頁面說明如何使用 FHIR Consent 資源，判斷 Cloud Healthcare API 中 FHIR 儲存庫的資料存取權。

如要設定強制執行同意聲明的 FHIR 儲存庫，請完成下列步驟：

  1. 如果沒有 FHIR 儲存庫，請建立一個。

  2. 設定下列 FHIR 儲存庫的 ConsentConfig 參數，啟用同意聲明強制執行功能：

    • version：指定 FHIR 存放區使用的同意聲明強制執行版本。這個值只能由 CreateFhirStore 或 UpdateFhirStore 設定一次。設定完成後，您必須呼叫 ApplyConsents 或 ApplyAdminConsents 才能變更版本。

    • access_enforced：如果設為 true，存取 FHIR 資源時，系統會根據消費者提供的同意聲明指令，驗證提供的同意聲明標頭。

    • consent_header_handling： 如果設為 PERMIT_EMPTY_SCOPE (預設值)，伺服器會允許沒有 (或空白) X-Consent-Scope 標頭的要求。如果設為 REQUIRED_ON_READ 且 access_enforced = true，伺服器會拒絕所有沒有 (或空白) X-Consent-Scope 標頭的要求。

使用 ConsentConfig 設定新的 FHIR 儲存庫

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: application/json" \
    --data "{
      'version': 'R4',
      'enableUpdateCreate': true,
      'consentConfig': {
        'version': 'V1',
        'accessEnforced': true
      }
    }" "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores?fhirStoreId=FHIR_STORE_ID"

您應該會收到類似以下的 JSON 回應：

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID",
  "version": "R4",
  "enableUpdateCreate": true,
  "consentConfig": {
    "version": "V1"
  }
}

如果您已有商店，請使用 UpdateFhirStore 將 ConsentConfig 的同意聲明強制執行設定 version 設為 V1 ，並將 accessEnforced 設為 true。

curl -X PATCH \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: application/json" \
    --data "{
      'consentConfig': {
        'version': 'V1',
        'accessEnforced': true
      }
    }" "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID?update_mask=consentConfig"

政策以同意聲明資源表示。如要瞭解資源欄位的用途和用法，請參閱資料模型文件。

以下是這個特定範例可建立的所有資源範例。

建立 FHIR 資源

以下範例說明如何執行 [FHIR 組合](/healthcare-api/docs/how-tos/fhir-bundles)，以填入下列資源：

  • 名稱為「Jeffrey Brown」的從業人員資源
  • 名稱為「Darcy Smith」的 Patient 資源
  • 顯示 Darcy 血紅素測量結果的 Observation 資源 (LOINC718-7)，由 Happy Hospital 收集
  • 顯示 Darcy 血糖測量結果的 Observation 資源 (LOINC15074-8)。
  • Darcy 同意授權 Jeffrey Brown 使用應用程式 App/123 存取 Happy Hospital 收集的資料
  • Darcy 同意授權 Jeffrey Brown 存取她的所有資料，以進行緊急治療 (ETREAT)
  • Happy Hospital 的同意聲明，允許 Jeffrey Brown 在進行生物醫學研究時存取所有資料 (BIORCH)，應用程式為 App/golden

cat > bundle.json << 'EOF'
{
  "resourceType": "Bundle",
  "type": "transaction",
  "entry": [
    {
      "request": {"method": "PUT", "url": "Practitioner/12942879-f89f-41ae-aa80-0b911b649833"},
      "resource": {
        "active": true,
        "birthDate": "1970-05-23",
        "gender": "male",
        "id": "12942879-f89f-41ae-aa80-0b911b649833",
        "name": [{
            "family": "Brown",
            "given": ["Jeffrey"],
            "use": "official"
        }],
        "resourceType": "Practitioner"
      }
    },
    {
      "request": {"method": "PUT", "url": "Patient/3c6aa096-c054-4c22-b2b4-1e4a4d203de2"},
      "resource": {
        "active": true,
        "birthDate": "1990-01-01",
        "gender": "female",
        "id": "3c6aa096-c054-4c22-b2b4-1e4a4d203de2",
        "name": [{
            "family": "Smith",
            "given": ["Darcy"],
            "use": "official"
        }],
        "meta": {
          "tag": [{
            "system": "http://terminology.hl7.org/CodeSystem/common-tags",
            "code": "employee"
          }]
        },
        "resourceType": "Patient"
      }
    },
    {
      "request": {"method": "PUT", "url": "Observation/7473784b-46a8-470c-b9a6-fe38a01025aa"},
      "resource": {
        "id": "7473784b-46a8-470c-b9a6-fe38a01025aa",
        "meta": {"source": "http://example.com/HappyHospital"},
        "code": {
          "coding": [{
            "code": "718-7",
            "system": "http://loinc.org",
            "display": "Hemoglobin [Mass/volume] in Blood"
          }]
        },
        "effectivePeriod": {"start": "2021-12-10T05:30:10+01:00"},
        "issued": "2021-12-10T13:30:10+01:00",
        "resourceType": "Observation",
        "status": "final",
        "subject": {"reference": "Patient/3c6aa096-c054-4c22-b2b4-1e4a4d203de2"},
        "valueQuantity": {
          "code": "g/dL",
          "system": "http://unitsofmeasure.org",
          "unit": "g/dl",
          "value": 7.2
        }
      }
    },
    {
      "request": {"method": "PUT", "url": "Observation/68583624-9921-4158-8754-2a306c689abd"},
      "resource": {
        "id": "68583624-9921-4158-8754-2a306c689abd",
        "code": {
          "coding": [{
            "code": "15074-8",
            "system": "http://loinc.org",
            "display": "Glucose [Moles/volume] in Blood"
          }]
        },
        "effectivePeriod": {"start": "2021-12-01T05:30:10+01:00"},
        "issued": "2021-12-01T13:30:10+01:00",
        "resourceType": "Observation",
        "status": "final",
        "subject": {"reference": "Patient/3c6aa096-c054-4c22-b2b4-1e4a4d203de2"},
        "valueQuantity": {
          "code": "mmol/L",
          "system": "http://unitsofmeasure.org",
          "unit": "mmol/l",
          "value": 6.3
        }
      }
    },
    {
      "request": {"method": "PUT", "url": "Consent/10998b60-a252-405f-aa47-0702554ddc8e"},
      "resource": {
        "category": [{
          "coding": [{
            "code": "59284-0",
            "system": "http://terminology.hl7.org/CodeSystem/consentcategorycodes"
          }]
        }],
        "id": "10998b60-a252-405f-aa47-0702554ddc8e",
        "patient": {"reference": "Patient/3c6aa096-c054-4c22-b2b4-1e4a4d203de2"},
        "policyRule": {
          "coding": [{
            "code": "OPTIN",
            "system": "http://terminology.hl7.org/CodeSystem/v3-ActCode"
          }]
        },
        "provision": {
          "actor": [
            {
              "reference": {"reference": "Practitioner/12942879-f89f-41ae-aa80-0b911b649833"},
              "role": {
                "coding": [{
                  "code": "GRANTEE",
                  "system": "http://terminology.hl7.org/CodeSystem/v3-RoleCode"
                }]
              }
            }
          ],
          "extension": [
            {
              "url": "https://g.co/fhir/medicalrecords/Environment",
              "valueCodeableConcept": {
                "coding": [{
                  "code": "123",
                  "system": "App"
                }]
              }
            },
            {
              "url": "https://g.co/fhir/medicalrecords/DataSource",
              "valueUri": "http://example.com/HappyHospital"
            }
          ],
          "type": "permit"
        },
        "resourceType": "Consent",
        "scope": {
          "coding": [{
            "code": "patient-privacy",
            "system": "http://terminology.hl7.org/CodeSystem/consentscope"
          }]
        },
        "status": "active"
      }
    },
    {
      "request": {"method": "PUT", "url": "Consent/73c54e8d-2789-403b-9dee-13085c5d5e34"},
      "resource": {
        "category": [{
          "coding": [{
            "code": "59284-0",
            "system": "http://terminology.hl7.org/CodeSystem/consentcategorycodes"
          }]
        }],
        "id": "73c54e8d-2789-403b-9dee-13085c5d5e34",
        "patient": {"reference": "Patient/3c6aa096-c054-4c22-b2b4-1e4a4d203de2"},
        "policyRule": {
          "coding": [{
            "code": "OPTIN",
            "system": "http://terminology.hl7.org/CodeSystem/v3-ActCode"
          }]
        },
        "provision": {
          "actor": [
            {
              "reference": {"reference": "Practitioner/12942879-f89f-41ae-aa80-0b911b649833"},
              "role": {
                "coding": [{
                  "code": "GRANTEE",
                  "system": "http://terminology.hl7.org/CodeSystem/v3-RoleCode"
                }]
              }
            }
          ],
          "purpose": [{
            "code": "ETREAT",
            "system": "http://terminology.hl7.org/CodeSystem/v3-ActReason"
          }],
          "type": "permit"
        },
        "resourceType": "Consent",
        "scope": {
          "coding": [{
            "code": "patient-privacy",
            "system": "http://terminology.hl7.org/CodeSystem/consentscope"
          }]
        },
        "status": "active"
      }
    },
    {
      "request": {"method": "PUT", "url": "Consent/5c8e3f8a-9fd5-480d-a08e-f29b89feccde"},
      "resource": {
        "category": [{
          "coding": [{
            "code": "57017-6",
            "system": "http://loinc.org"
          }]
        }],
        "id": "5c8e3f8a-9fd5-480d-a08e-f29b89feccde",
        "patient": {},
        "extension": [{
          "url": "https://g.co/fhir/medicalrecords/ConsentAdminPolicy"
        }],
        "policyRule": {
          "coding": [{
            "code": "OPTIN",
            "system": "http://terminology.hl7.org/CodeSystem/v3-ActCode"
          }]
        },
        "provision": {
          "actor": [
            {
              "reference": {"reference": "Practitioner/12942879-f89f-41ae-aa80-0b911b649833"},
              "role": {
                "coding": [{
                  "code": "GRANTEE",
                  "system": "http://terminology.hl7.org/CodeSystem/v3-RoleCode"
                }]
              }
            }
          ],
          "purpose": [{
            "code": "BIORCH",
            "system": "http://terminology.hl7.org/CodeSystem/v3-ActReason"
          }],
          "extension": [
            {
              "url": "https://g.co/fhir/medicalrecords/Environment",
              "valueCodeableConcept": {
                "coding": [{
                  "code": "golden",
                  "system": "App"
                }]
              }
            }
          ],
          "type": "permit"
        },
        "resourceType": "Consent",
        "scope": {},
        "status": "active"
      }
    }
  ]
}
EOF
curl -X POST \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: application/fhir+json; charset=utf-8" \
    --data @bundle.json \
    "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir"

您應該會收到類似以下的 JSON 回應：

{
  "entry": [
    {
      "response": {
        "etag": "W/\"VERSION_ID\"",
        "lastModified": "2022-09-01T17:31:40.423469+00:00",
        "location": "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Practitioner/12942879-f89f-41ae-aa80-0b911b649833/_history/VERSION_ID",
        "status": "201 Created"
      }
    },
    {
      "response": {
        "etag": "W/\"VERSION_ID\"",
        "lastModified": "2022-09-01T17:31:40.423469+00:00",
        "location": "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Patient/3c6aa096-c054-4c22-b2b4-1e4a4d203de2/_history/VERSION_ID",
        "status": "201 Created"
      }
    },
    {
      "response": {
        "etag": "W/\"VERSION_ID\"",
        "lastModified": "2022-09-01T17:31:40.423469+00:00",
        "location": "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Observation/7473784b-46a8-470c-b9a6-fe38a01025aa/_history/VERSION_ID",
        "status": "201 Created"
      }
    },
    {
      "response": {
        "etag": "W/\"VERSION_ID\"",
        "lastModified": "2022-09-01T17:31:40.423469+00:00",
        "location": "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Observation/68583624-9921-4158-8754-2a306c689abd/_history/VERSION_ID",
        "status": "201 Created"
      }
    },
    {
      "response": {
        "etag": "W/\"VERSION_ID\"",
        "lastModified": "2022-09-01T17:31:40.423469+00:00",
        "location": "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Consent/10998b60-a252-405f-aa47-0702554ddc8e/_history/VERSION_ID",
        "status": "201 Created"
      }
    },
    {
      "response": {
        "etag": "W/\"VERSION_ID\"",
        "lastModified": "2022-09-01T17:31:40.423469+00:00",
        "location": "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Consent/73c54e8d-2789-403b-9dee-13085c5d5e34/_history/VERSION_ID",
        "status": "201 Created"
      }
    },
    {
      "response": {
        "etag": "W/\"VERSION_ID\"",
        "lastModified": "2022-09-01T17:31:40.423469+00:00",
        "location": "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Consent/5c8e3f8a-9fd5-480d-a08e-f29b89feccde/_history/VERSION_ID",
        "status": "201 Created"
      }
    }
  ],
  "resourceType": "Bundle",
  "type": "transaction-response"
}

以下列舉更多 R4 Consent 資源範例，說明如何表示複雜的政策。

{
  "resourceType": "Consent",
  "id": "patient-consent-example",
  "patient": {
    "reference": "Patient/f001"
  },
  "category": [
    {
      "coding": [
        {
          "system": "http://loinc.org",
          "code": "59284-0"
        }
      ]
    }
  ],
  "scope": {
    "coding": [
      {
        "system": "http://terminology.hl7.org/CodeSystem/consentscope",
        "code": "patient-privacy"
      }
    ]
  },
  "policyRule": {
    "coding": [
      {
        "system": "http://terminology.hl7.org/CodeSystem/v3-ActCode",
        "code": "OPTIN"
      }
    ]
  },
  "status": "active",
  "provision": {
    "type": "permit",
    "actor": [
      {
        "reference": {
          "reference": "Practitioner/f002"
        },
        "role": {
          "coding": [
            {
              "system": "http://terminology.hl7.org/CodeSystem/v3-RoleCode",
              "code": "GRANTEE"
            }
          ]
        }
      }
    ],
    "purpose": [
      {
        "system": "http://terminology.hl7.org/CodeSystem/v3-ActReason",
        "code": "TREAT"
      }
    ],
    "class": [
      {
        "system": "http://hl7.org/fhir/resource-types",
        "code": "Encounter"
      }
    ],
    "data": [
      {
        "meaning": "instance",
        "reference": {
          "reference": "Encounter/e001"
        }
      }
    ],
    "extension": [
      {
        "url": "https://g.co/fhir/medicalrecords/Environment",
        "valueCodeableConcept": {
          "coding": [
            {
              "system": "iso3166-1",
              "code": "CA"
            }
          ]
        }
      },
      {
        "url": "https://g.co/fhir/medicalrecords/DataTag",
        "valueCoding": {
          "system": "http://terminology.hl7.org/CodeSystem/common-tags",
          "code": "actionable"
        }
      },
      {
        "url": "https://g.co/fhir/medicalrecords/DataTag",
        "extension": [
          {
            "url": "https://g.co/fhir/medicalrecords/DataTag",
            "valueCoding": {
              "system": "http://example.com/custom-tags",
              "code": "archived"
            }
          },
          {
            "url": "https://g.co/fhir/medicalrecords/DataTag",
            "valueCoding": {
              "system": "http://example.com/custom-tags",
              "code": "insensitive"
            }
          }
        ]
      },
      {
        "url": "https://g.co/fhir/medicalrecords/DataSource",
        "valueUri": "http://somesystem.example.org/foo"
      }
    ],
    "securityLabel": [
      {
        "system": "http://terminology.hl7.org/CodeSystem/v3-Confidentiality",
        "code": "R"
      },
      {
        "system": "http://terminology.hl7.org/CodeSystem/v3-ActCode",
        "code": "PSY"
      }
    ]
  }
}

上述範例代表病患同意聲明資源，其中病患 f001 授權給醫療人員 f002，目的是提供以 TREAT 代表的定期治療。執業人員來自地理位置 iso3166-1/CA。如果資料符合所有下列條件，這項同意聲明資源可允許醫護人員存取病患資料。

  • 這是 ID 為 Encounter/e001 的 Encounter 類型。
  • 來源為 http://somesystem.example.org/foo。
  • 符合標記的至少一項條件 (可透過設定 Meta.tags 的 system 和 code 欄位標記資源)：
    • 具有標記 (system = http://terminology.hl7.org/CodeSystem/common-tags 且 code = actionable)
    • 同時有兩個標記 (system = http://example.com/custom-tags 和 code = archived) 和 (system = http://example.com/custom-tags 和 code = insensitive)
  • 至少具有下列其中一個安全標籤
    • system = http://terminology.hl7.org/CodeSystem/v3-Confidentiality 且 code 是 R、N、M、L、U 其中之一。
    • system = http://terminology.hl7.org/CodeSystem/v3-ActCode 且 code = PSY。

管理員政策指令範例

{
  "resourceType": "Consent",
  "id": "admin-policy-example",
  "patient": {},
  "extension": [{
    "url": "https://g.co/fhir/medicalrecords/ConsentAdminPolicy"
  }],
  "category": [
    {
      "coding": [
        {
          "system": "http://loinc.org",
          "code": "57017-6"
        }
      ]
    }
  ],
  "scope": {},
  "policyRule": {
    "coding": [
      {
        "system": "http://terminology.hl7.org/CodeSystem/v3-ActCode",
        "code": "OPTIN"
      }
    ]
  },
  "status": "active",
  "provision": {
    "type": "permit",
    "actor": [
      {
        "reference": {
          "reference": "Practitioner/f002"
        },
        "role": {
          "coding": [
            {
              "system": "http://terminology.hl7.org/CodeSystem/v3-RoleCode",
              "code": "GRANTEE"
            }
          ]
        }
      }
    ],
    "purpose": [
      {
        "system": "http://terminology.hl7.org/CodeSystem/v3-ActReason",
        "code": "TREAT"
      }
    ],
    "class": [
      {
        "system": "http://hl7.org/fhir/resource-types",
        "code": "Encounter"
      }
    ],
    "data": [
      {
        "meaning": "instance",
        "reference": {
          "reference": "Encounter/e001"
        }
      }
    ],
    "extension": [
      {
        "url": "https://g.co/fhir/medicalrecords/Environment",
        "valueCodeableConcept": {
          "coding": [
            {
              "system": "iso3166-1",
              "code": "CA"
            }
          ]
        }
      },
      {
        "url": "https://g.co/fhir/medicalrecords/DataTag",
        "valueCoding": {
          "system": "http://terminology.hl7.org/CodeSystem/common-tags",
          "code": "actionable"
        }
      },
      {
        "url": "https://g.co/fhir/medicalrecords/DataTag",
        "extension": [
          {
            "url": "https://g.co/fhir/medicalrecords/DataTag",
            "valueCoding": {
              "system": "http://example.com/custom-tags",
              "code": "archived"
            }
          },
          {
            "url": "https://g.co/fhir/medicalrecords/DataTag",
            "valueCoding": {
              "system": "http://example.com/custom-tags",
              "code": "insensitive"
            }
          }
        ]
      },
      {
        "url": "https://g.co/fhir/medicalrecords/DataSource",
        "valueUri": "http://somesystem.example.org/foo"
      }
    ],
    "securityLabel": [
      {
        "system": "http://terminology.hl7.org/CodeSystem/v3-Confidentiality",
        "code": "R"
      },
      {
        "system": "http://terminology.hl7.org/CodeSystem/v3-ActCode",
        "code": "PSY"
      }
    ]
  }
}

上述範例代表管理員政策「同意聲明」資源，可授權給醫療人員 f002，以便提供以 TREAT 代表的定期治療。執業者來自地理位置 iso3166-1/CA。如果資料符合所有下列條件，醫療人員就能透過這項同意聲明資源存取病患資料：

  • 這是 ID 為 Encounter/e001 的 Encounter 類型。
  • 來源為 http://somesystem.example.org/foo。
  • 至少符合下列其中一項標記條件：
    • 具有標記 (system = http://terminology.hl7.org/CodeSystem/common-tags 且 code = actionable)
    • 同時有兩個標記 (system = http://example.com/custom-tags 和 code = archived) 和 (system = http://example.com/custom-tags 和 code = insensitive)
  • 至少具有下列其中一個安全標籤
    • system = http://terminology.hl7.org/CodeSystem/v3-Confidentiality 且 code 是 R、N、M、L、U 其中之一。
    • system = http://terminology.hl7.org/CodeSystem/v3-ActCode 且 code = PSY。

管理員連鎖政策指令範例

{
  "resourceType": "Consent",
  "id": "admin-cascading-policy-example",
  "patient": {},
  "extension": [
    { "url": "https://g.co/fhir/medicalrecords/ConsentAdminPolicy" },
    { "url": "https://g.co/fhir/medicalrecords/CascadingPolicy" }
  ],
  "category": [
    {
      "coding": [
        {
          "system": "http://loinc.org",
          "code": "57017-6"
        }
      ]
    }
  ],
  "scope": {},
  "policyRule": {
    "coding": [
      {
        "system": "http://terminology.hl7.org/CodeSystem/v3-ActCode",
        "code": "OPTIN"
      }
    ]
  },
  "status": "active",
  "provision": {
    "type": "permit",
    "actor": [
      {
        "reference": {
          "reference": "Practitioner/f002"
        },
        "role": {
          "coding": [
            {
              "system": "http://terminology.hl7.org/CodeSystem/v3-RoleCode",
              "code": "GRANTEE"
            }
          ]
        }
      }
    ],
    "purpose": [
      {
        "system": "http://terminology.hl7.org/CodeSystem/v3-ActReason",
        "code": "TREAT"
      }
    ],
    "class": [
      {
        "system": "http://hl7.org/fhir/resource-types",
        "code": "Patient"
      }
    ],
    "extension": [
      {
        "url": "https://g.co/fhir/medicalrecords/Environment",
        "valueCodeableConcept": {
          "coding": [
            {
              "system": "iso3166-1",
              "code": "CA"
            }
          ]
        }
      },
      {
        "url": "https://g.co/fhir/medicalrecords/DataTag",
        "valueCoding": {
          "system": "http://terminology.hl7.org/CodeSystem/common-tags",
          "code": "employee"
        }
      }
    ]
  }
}

上述範例代表管理員層疊政策的同意聲明資源，可授權給醫療人員 f002，以便提供以 TREAT 代表的常規治療。專業執業人員來自地理位置 iso3166-1/CA。這項同意聲明資源可讓醫護人員存取標記為 employee 的病患區間資料。所有資源條件僅適用於區間基本資源，也就是 Patient 資源，因為這項資源會控管要從哪些資源層疊。

強制執行病患同意聲明或管理員政策

透過ApplyConsents強制執行病患同意聲明

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: application/json" \
    --data "{'validateOnly': false}" \
    "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID:applyConsents"

您應該會收到類似以下的 JSON 回應：

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

回應會包含作業名稱。如要追蹤作業狀態，可以使用 [作業 `get` 方法](/healthcare-api/docs/reference/rest/v1/projects.locations.datasets.operations/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.v1.OperationMetadata",
    "apiMethodName": "google.cloud.healthcare.v1.fhir.FhirStoreService.ApplyConsents",
    "createTime": "CREATE_TIME",
    "endTime": "END_TIME",
    "logsUrl": "https://console.cloud.google.com/logs/query/CLOUD_LOGGING_URL",
    "counter": {
      "success": "2",
      "secondarySuccess": "5"
    }
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.cloud.healthcare.v1.fhir.ApplyConsentsResponse",
    "consentApplySuccess": "2",
    "affectedResources": "5"
  }
}

這項回應表示伺服器已成功處理 2 項同意聲明，並更新 5 項資源的同意存取權 (1 位病患、2 項同意聲明、2 項觀察)。

透過 ApplyAdminConsents 強制執行管理員政策

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: application/json" \
    --data "{
      'validateOnly': false,
      'newConsentsList': {
        'names': ['projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Consent/5c8e3f8a-9fd5-480d-a08e-f29b89feccde/_history/VERSION_ID']
      }
    }" \
    "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID:applyAdminConsents"

您應該會收到類似以下的 JSON 回應：

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

回應會包含作業名稱。如要追蹤作業狀態，可以使用 [作業 `get` 方法](/healthcare-api/docs/reference/rest/v1/projects.locations.datasets.operations/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.v1.OperationMetadata",
    "apiMethodName": "google.cloud.healthcare.v1.fhir.FhirStoreService.ApplyAdminConsents",
    "createTime": "CREATE_TIME",
    "endTime": "END_TIME",
    "logsUrl": "https://console.cloud.google.com/logs/query/CLOUD_LOGGING_URL",
    "counter": {
      "success": "1",
      "secondarySuccess": "7"
    }
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.cloud.healthcare.v1.fhir.ApplyAdminConsentsResponse",
    "consentApplySuccess": "1",
    "affectedResources": "7"
  }
}

這項回應表示伺服器已成功處理 1 項管理員政策，並更新 7 項資源的同意存取權 (1 位醫護人員、1 位病患、2 項觀察結果、2 項病患同意聲明和 1 項管理員政策)。

系統不會強制執行 FHIR 存放區中儲存的同意聲明，直到呼叫 ApplyConsents (適用於病患同意聲明) 或 ApplyAdminConsents (適用於管理員政策和管理員連鎖政策) 並成功完成為止。如果您在執行 ApplyConsents 或 ApplyAdminConsents 後新增、修改或移除同意聲明，則必須再次執行，這些同意聲明才會納入強制執行模式。

FHIR 資源會以非同步方式建立索引，因此 ApplyConsents 或 ApplyAdminConsents 完成後，搜尋結果可能不會立即反映強制執行模型。搜尋要求才會出現這種延遲。

如果您是第一次在 FHIR 存放區中設定同意聲明強制執行功能，請等待 ApplyConsents 或 ApplyAdminConsents 長時間執行的作業完成，再提出同意聲明相關要求。

如要對部分病患呼叫 ApplyConsents，可以使用下列篩選條件：

  • PatientScope： 針對最多 10,000 名病患的病患 ID 清單執行 ApplyConsents

  • TimeRange： 在特定時間範圍內更新同意聲明資源的病患資源 ID 清單上執行 ApplyConsent

如要呼叫 ApplyAdminConsents，您必須提供要套用的「所有」政策完整清單 (而非增量清單)。因此，如果清單為空白，商店將不會強制執行任何管理員政策。如果 FHIR 存放區採用版本控管，每項政策都必須是資源版本名稱，否則必須是資源名稱。

您可以使用 operations.get 擷取作業的 ProgressCounter。完成後，Operation.response 中會包含 ApplyConsentsResponse。下表說明 ProgressCounter 和 ApplyConsentsResponse 或 ApplyAdminConsentsResponse 中的計數器。

ProgressCounter ApplyConsentsResponse或ApplyAdminConsentsResponse 說明
success consentApplySuccess 作業成功處理的 Consent 資源數量。
failure consentApplyFailure 無效或不受支援的同意聲明資源數量。您可以在 Cloud Logging 中查看錯誤記錄，或在 validateOnly 為 false 時，使用 CheckConsentEnforcementStatus 或 CheckPatientConsentEnforcementStatus 擷取錯誤詳細資料，檢查同意聲明強制執行狀態。
secondarySuccess affectedResources 當 validateOnly 為 false 時，表示因同意聲明變更而成功重新建立索引的 FHIR 資源數量。
secondaryFailure failedResources 當 validateOnly 為 false 時，代表可能已變更同意聲明但重新建立索引失敗的 FHIR 資源數量。這可能會影響同意聲明情境下的搜尋，但不會影響其他方法。如要查看錯誤詳細資料，請查看 Cloud Logging 中的錯誤記錄檔。

處理 FHIR 同意聲明資源時，您可以使用下列 API 檢查單一同意聲明或病患所有同意聲明的強制執行狀態：

如果是管理員政策，CheckConsentEnforcementStatus 只能用於檢查單一同意聲明管理員政策的強制執行狀態。或者，你也可以使用 fhirStores.get 查看套用至商店的所有有效管理員政策。

consent-enforcement-status 可設為下列任一值：

  • OFF：代表從未處理的新同意聲明資源的預設強制執行狀態。

  • ENFORCEABLE：同意聲明資源已成功處理的狀態。

  • INACTIVE：處於非使用中狀態，系統會忽略 Consent 資源。

  • UNSUPPORTED：同意聲明資源的狀態，可能符合 FHIR 規格，但無法強制執行。這是因為目前的功能支援程度有限，無法全面實施 FHIR 同意聲明強制執行措施。

  • ENFORCEMENT_LIMIT_EXCEEDED：FHIR 同意聲明資源格式和資源支援層級皆無錯誤，但符合下列一或多項條件：

    • 病患有大量同意聲明資源。

    • 所有有效同意聲明中的同意聲明指令大小，大於 FHIR 伺服器強制執行同意聲明指令的大小上限。

Cloud Healthcare API 支援在指定 FHIR 儲存庫中搜尋 FHIR 資源，並以 actor、purpose 和 environment 做為查詢參數。回應只會包含已同意的資源。

  1. 執業人員 Jeffrey Brown (以 Practitioner/12942879-f89f-41ae-aa80-0b911b649833 識別) 使用信任的應用程式 App/123 搜尋所有「觀測」status=final。
    2. curl -X GET \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "X-Consent-Scope: actor/Practitioner/12942879-f89f-41ae-aa80-0b911b649833 env/App/123" \
    "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Observation?status=final"

    您應該會收到類似以下的 JSON 回應：

    {
  "entry": [
    {
      "fullUrl": "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Observation/7473784b-46a8-470c-b9a6-fe38a01025aa",
      "resource": {
        "code": {
          "coding": [
            {
              "code": "718-7",
              "display": "Hemoglobin [Mass/volume] in Blood",
              "system": "http://loinc.org"
            }
          ]
        },
        "effectivePeriod": {
          "start": "2021-12-10T05:30:10+01:00"
        },
        "id": "7473784b-46a8-470c-b9a6-fe38a01025aa",
        "issued": "2021-12-10T13:30:10+01:00",
        "meta": {
          "lastUpdated": "2022-09-01T17:31:40.423469+00:00",
          "source": "http://example.com/HappyHospital",
          "versionId": "VERSION_ID"
        },
        "resourceType": "Observation",
        "status": "final",
        "subject": {
          "reference": "Patient/3c6aa096-c054-4c22-b2b4-1e4a4d203de2"
        },
        "valueQuantity": {
          "code": "g/dL",
          "system": "http://unitsofmeasure.org",
          "unit": "g/dl",
          "value": 7.2
        }
      },
      "search": {
        "mode": "match"
      }
    }
  ],
  "link": [
    {
      "relation": "search",
      "url": "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Observation/?status=final"
    },
    {
      "relation": "first",
      "url": "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Observation/?status=final"
    },
    {
      "relation": "self",
      "url": "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Observation/?status=final"
    }
  ],
  "resourceType": "Bundle",
  "total": 1,
  "type": "searchset"
}
  2. 執業人員 Jeffrey Brown (以 Practitioner/12942879-f89f-41ae-aa80-0b911b649833 識別) 使用應用程式 App/123 搜尋 Patient Darcy 的所有觀察結果。
    3. curl -X GET \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "X-Consent-Scope: actor/Practitioner/12942879-f89f-41ae-aa80-0b911b649833 env/App/123" \
    "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Observation?subject:Patient.name=Darcy"

    您應該會收到類似以下的 JSON 回應：

    {
  "link": [
    {
      "relation": "search",
      "url": "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Observation/?subject%3APatient.name=Darcy"
    },
    {
      "relation": "first",
      "url": "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Observation/?subject%3APatient.name=Darcy"
    },
    {
      "relation": "self",
      "url": "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Observation/?subject%3APatient.name=Darcy"
    }
  ],
  "resourceType": "Bundle",
  "total": 0,
  "type": "searchset"
}

    上述查詢是串聯搜尋。由於同意聲明情境actor/Practitioner/12942879-f89f-41ae-aa80-0b911b649833 env/App/123拒絕存取病患 Darcy 資源 (由 Patient/3c6aa096-c054-4c22-b2b4-1e4a4d203de2 識別)，因此 FHIR 伺服器不會傳回病患的任何觀察結果，彷彿病患不存在。

  3. 執業人員 Jeffrey Brown (以 Practitioner/12942879-f89f-41ae-aa80-0b911b649833 識別) 使用應用程式 App/123 搜尋 Patient Darcy 的所有觀察結果，以進行緊急治療。
    4. curl -X GET \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "X-Consent-Scope: actor/Practitioner/12942879-f89f-41ae-aa80-0b911b649833 purp/v3/ETREAT env/App/123" \
    "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Observation?subject:Patient.name=Darcy"

    您應該會收到類似以下的 JSON 回應：

    {
  "entry": [
    {
      "fullUrl": "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Observation/68583624-9921-4158-8754-2a306c689abd",
      "resource": {
        "code": {
          "coding": [
            {
              "code": "15074-8",
              "display": "Glucose [Moles/volume] in Blood",
              "system": "http://loinc.org"
            }
          ]
        },
        "effectivePeriod": {
          "start": "2021-12-01T05:30:10+01:00"
        },
        "id": "68583624-9921-4158-8754-2a306c689abd",
        "issued": "2021-12-01T13:30:10+01:00",
        "meta": {
          "lastUpdated": "2022-09-01T17:31:40.423469+00:00",
          "versionId": "VERSION_ID"
        },
        "resourceType": "Observation",
        "status": "final",
        "subject": {
          "reference": "Patient/3c6aa096-c054-4c22-b2b4-1e4a4d203de2"
        },
        "valueQuantity": {
          "code": "mmol/L",
          "system": "http://unitsofmeasure.org",
          "unit": "mmol/l",
          "value": 6.3
        }
      },
      "search": {
        "mode": "match"
      }
    },
    {
      "fullUrl": "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Observation/7473784b-46a8-470c-b9a6-fe38a01025aa",
      "resource": {
        "code": {
          "coding": [
            {
              "code": "718-7",
              "display": "Hemoglobin [Mass/volume] in Blood",
              "system": "http://loinc.org"
            }
          ]
        },
        "effectivePeriod": {
          "start": "2021-12-10T05:30:10+01:00"
        },
        "id": "7473784b-46a8-470c-b9a6-fe38a01025aa",
        "issued": "2021-12-10T13:30:10+01:00",
        "meta": {
          "lastUpdated": "2022-09-01T17:31:40.423469+00:00",
          "source": "http://example.com/HappyHospital",
          "versionId": "VERSION_ID"
        },
        "resourceType": "Observation",
        "status": "final",
        "subject": {
          "reference": "Patient/3c6aa096-c054-4c22-b2b4-1e4a4d203de2"
        },
        "valueQuantity": {
          "code": "g/dL",
          "system": "http://unitsofmeasure.org",
          "unit": "g/dl",
          "value": 7.2
        }
      },
      "search": {
        "mode": "match"
      }
    }
  ],
  "link": [
    {
      "relation": "search",
      "url": "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Observation/?subject:Patient.name=Darcy"
    },
    {
      "relation": "first",
      "url": "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Observation/?subject:Patient.name=Darcy"
    },
    {
      "relation": "self",
      "url": "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Observation/?subject:Patient.name=Darcy"
    }
  ],
  "resourceType": "Bundle",
  "total": 2,
  "type": "searchset"
}
  4. 執業人員 Jeffrey Brown (以 Practitioner/12942879-f89f-41ae-aa80-0b911b649833 識別) 搜尋「觀察」status=final，目的是為了治療和研究
    5. curl -X GET \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "X-Consent-Scope: actor/Practitioner/12942879-f89f-41ae-aa80-0b911b649833 purp/v3/TREAT purp/v3/HRESCH" \
    "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Observation?status=final"

    您應該會收到類似以下的 JSON 回應：

    {
  "issue": [
    {
      "code": "security",
      "details": {
        "text": "permission_denied"
      },
      "diagnostics": "the maximum number of allowed consent purpose scopes is 1, got 2",
      "severity": "error"
    }
  ],
  "resourceType": "OperationOutcome"
}

    在這種情況下，執業人員 Jeffrey Brown 應從要求中的 `X-Consent-Scope` 移除不必要的用途。

  5. 醫院 IT 管理員使用 bypass 搜尋醫院的所有執業人員。
    6. curl -X GET \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "X-Consent-Scope: bypass actor/Admin/ef0592c9-6724-467e-878d-f879e537cd15 env/net/HappyNet" \
    "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Practitioner?"

    由於已提供 bypass，因此系統略過了同意聲明檢查。您應該會收到類似如下的 JSON 回應：

    {
  "entry": [
    {
      "fullUrl": "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Practitioner/12942879-f89f-41ae-aa80-0b911b649833",
      "resource": {
        "active": true,
        "birthDate": "1970-05-23",
        "gender": "male",
        "id": "12942879-f89f-41ae-aa80-0b911b649833",
        "meta": {
          "lastUpdated": "2022-09-01T17:31:40.423469+00:00",
          "versionId": "VERSION_ID"
        },
        "name": [
          {
            "family": "Brown",
            "given": [
              "Jeffrey"
            ],
            "use": "official"
          }
        ],
        "resourceType": "Practitioner"
      },
      "search": {
        "mode": "match"
      }
    }
  ],
  "link": [
    {
      "relation": "search",
      "url": "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Practitioner/?"
    },
    {
      "relation": "first",
      "url": "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Practitioner/?"
    },
    {
      "relation": "self",
      "url": "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Practitioner/?"
    }
  ],
  "resourceType": "Bundle",
  "total": 1,
  "type": "searchset"
}

Cloud Healthcare API 支援在指定 FHIR 儲存庫中取得 FHIR 資源，並以 actor、purpose 和 environment 做為查詢參數。回應只會包含已同意的資源。

  1. 執業人員 Jeffrey Brown (以 Practitioner/12942879-f89f-41ae-aa80-0b911b649833 識別) 使用應用程式 App/123 讀取病患 (本例為 Observation/7473784b-46a8-470c-b9a6-fe38a01025aa) 的血紅素測量結果。
    2. curl -X GET \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "X-Consent-Scope: actor/Practitioner/12942879-f89f-41ae-aa80-0b911b649833 env/App/123" \
    "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Observation/7473784b-46a8-470c-b9a6-fe38a01025aa"

    由於要求者已獲得同意，因此回應是 Observation 資源的內容。

    {
  "code": {
    "coding": [
      {
        "code": "718-7",
        "display": "Hemoglobin [Mass/volume] in Blood",
        "system": "http://loinc.org"
      }
    ]
  },
  "effectivePeriod": {
    "start": "2021-12-10T05:30:10+01:00"
  },
  "id": "7473784b-46a8-470c-b9a6-fe38a01025aa",
  "issued": "2021-12-10T13:30:10+01:00",
  "meta": {
    "lastUpdated": "2022-09-01T17:31:40.423469+00:00",
    "source": "http://example.com/HappyHospital",
    "versionId": "VERSION_ID"
  },
  "resourceType": "Observation",
  "status": "final",
  "subject": {
    "reference": "Patient/3c6aa096-c054-4c22-b2b4-1e4a4d203de2"
  },
  "valueQuantity": {
    "code": "g/dL",
    "system": "http://unitsofmeasure.org",
    "unit": "g/dl",
    "value": 7.2
  }
}
  2. 執業人員 Jeffrey Brown (以 Practitioner/12942879-f89f-41ae-aa80-0b911b649833 識別) 使用不明應用程式 App/unknown 讀取病患 (在本例中為 Observation/7473784b-46a8-470c-b9a6-fe38a01025aa) 的血紅素測量值。
    3. curl -X GET \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "X-Consent-Scope: actor/Practitioner/12942879-f89f-41ae-aa80-0b911b649833 env/App/unknown" \
  "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Observation/7473784b-46a8-470c-b9a6-fe38a01025aa"

    由於病患同意聲明不允許要求者 (`App/unknown`) 的邊界存取權，因此要求遭到拒絕。 

    {
  "issue": [
    {
      "code": "security",
      "details": {
        "text": "permission_denied"
      },
      "diagnostics": "Consent access denied or the resource being accessed does not exist",
      "severity": "error"
    }
  ],
  "resourceType": "OperationOutcome"
}
  3. 從事生物醫學研究的執業人員 Jeffrey Brown (以 Practitioner/12942879-f89f-41ae-aa80-0b911b649833 識別) 使用應用程式 App/golden 讀取 Darcy 的出生日期 (在本範例中為 Patient/3c6aa096-c054-4c22-b2b4-1e4a4d203de2)。
    4. curl -X GET \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "X-Consent-Scope: actor/Practitioner/12942879-f89f-41ae-aa80-0b911b649833 purp/v3/BIORCH env/App/golden" \
  "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Patient/3c6aa096-c054-4c22-b2b4-1e4a4d203de2"

    由於要求者已取得同意聲明，因此回應內容為 Patient 資源。

    {
  "active": true,
  "birthDate": "1990-01-01",
  "gender": "female",
  "id": "3c6aa096-c054-4c22-b2b4-1e4a4d203de2",
  "meta": {
    "lastUpdated": "2022-09-01T17:31:40.423469+00:00",
    "versionId": "VERSION_ID",
    "tag": [{
      "system": "http://terminology.hl7.org/CodeSystem/common-tags",
      "code": "employee"
    }]
  },
  "name": [
    {
      "family": "Smith",
      "given": [
        "Darcy"
      ],
      "use": "official"
    }
  ],
  "resourceType": "Patient"
}
  4. 執業人員 Jeffrey Brown (識別碼：Practitioner/12942879-f89f-41ae-aa80-0b911b649833) 透過「break-the-glass」通訊協定，要求緊急未經授權存取病患記錄。(在本範例中為 Observation/7473784b-46a8-470c-b9a6-fe38a01025aa)。
    5. curl -X GET \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "X-Consent-Scope: btg actor/Practitioner/12942879-f89f-41ae-aa80-0b911b649833" \
  "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Observation/7473784b-46a8-470c-b9a6-fe38a01025aa"

    由於同意聲明的授權方法是 btg，伺服器會略過同意聲明檢查。回應是 Observation 資源的內容。 

    {
  "code": {
    "coding": [
      {
        "code": "718-7",
        "display": "Hemoglobin [Mass/volume] in Blood",
        "system": "http://loinc.org"
      }
    ]
  },
  "effectivePeriod": {
    "start": "2021-12-10T05:30:10+01:00"
  },
  "id": "7473784b-46a8-470c-b9a6-fe38a01025aa",
  "issued": "2021-12-10T13:30:10+01:00",
  "meta": {
    "lastUpdated": "2022-09-01T17:31:40.423469+00:00",
    "source": "http://example.com/HappyHospital",
    "versionId": "VERSION_ID"
  },
  "resourceType": "Observation",
  "status": "final",
  "subject": {
    "reference": "Patient/3c6aa096-c054-4c22-b2b4-1e4a4d203de2"
  },
  "valueQuantity": {
    "code": "g/dL",
    "system": "http://unitsofmeasure.org",
    "unit": "g/dl",
    "value": 7.2
  }
}

以下各節說明 Cloud Healthcare API 支援的同意聲明強制執行方法，以及您發出同意聲明感知要求時，資源存取權的強制執行方式。

提出要求時，授權伺服器會負責產生具有相關同意範圍的存取權杖。

設定 HTTP 標頭

同意範圍會透過 X-Consent-Scope HTTP 標頭傳遞至 Cloud Healthcare API。Cloud Healthcare API 會使用這個標頭，對 FHIR 儲存庫中的資料強制執行以同意聲明為依據的存取控制。

FHIR 要求支援的同意事項項目範圍數量有限。在特定 FHIR 要求中，最多可包含三項 actor 項目、一項 purp 項目和一項 env 項目。

如果是特殊範圍，FHIR 要求可以支援 btg 或 bypass。

為信任的應用程式設定 HTTP 標頭

如果您使用客戶控管的授權伺服器，才需要填寫這個部分。在這種情況下，您也必須使用 SMARTproxy 或類似的 Proxy。

部分受信任的應用程式可能會使用指定 HTTP 標頭中的同意範圍，直接呼叫 Cloud Healthcare API。這樣一來，系統就能直接強制執行同意聲明，不必使用 SMARTproxy 或其他 Proxy 在外部授權伺服器和 Google Cloud之間轉換。

舉例來說，您的應用程式可能已註冊部分範圍，例如應用程式 environment 範圍，或者應用程式可能會顯示選取小工具，設定某些範圍項目，例如存取者的 purpose。

信任的使用者或應用程式也可以使用btg 或 bypass 範圍項目，但須接受稽核後審查。

Cloud Healthcare API 內建 FHIR 同意聲明支援功能，可根據輸入的同意聲明範圍強制執行。FHIR 儲存庫管理員負責在 Cloud Healthcare API 外部建立及設定授權伺服器，授予同意範圍。

存取權杖範例

下列範例顯示以 Base64 編碼的存取權杖：

eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzM4NCJ9.eyJpc3MiOiJjb25zZW50LnRva2VuLm9yZyIsImlhdCI6MTYxMjg4NDA4NSwiZXhwIjoxNjQ0NDIwMDg1LCJhdWQiOiJ3d3cuZXhhbXBsZS5jb20iLCJzdWIiOiJkb2N0b3IuZ2FicmllbGFAZXhhbXBsZS5jb20iLCJzY29wZSI6Im9pZGMgYWN0b3IvUHJhY3RpdGlvbmVyLzEyMyBhY3Rvci9Hcm91cC85OTkgcHVycC92My9UUkVBVCBlbnYvQXBwL2FiYyJ9.fC7ljkVUUx8fwUOrJuONcrqA-WKC-k_Bclzlgds0Cq6H_gEe3nUjPlSOCTQsIdYB

解碼存取權杖後，您會發現權杖包含下列酬載：

{
  "iss": "consent.token.org",
  "iat": 1612884085,
  "exp": 1644420085,
  "aud": "www.example.com",
  "sub": "doctor.gabriela@example.com",
  "scope": "oidc actor/Practitioner/123 actor/Group/999 purp/v3/TREAT env/App/abc"
}

設定 SMARTProxy

SMARTProxy 是 Google 的開放原始碼 Proxy，提供下列功能：

  • 允許 Cloud Healthcare API FHIR 伺服器接受及驗證同意聲明感知存取權杖。

  • 允許 Cloud Healthcare API 中的 FHIR 實作項目將同意聲明感知存取權杖納入 Cloud Healthcare API 管理和權限模型。

  • 也支援 SMART on FHIR 的權杖功能。

透過 SMARTProxy 要求從 Cloud Healthcare API 擷取資料時，會發生下列情況：

  1. SMARTProxy 會接受用戶端傳送的要求，其中包含同意聲明感知權杖。

  2. SMARTProxy 會透過您擁有的 JWT 授權伺服器，驗證同意聲明感知權杖。

  3. SMARTProxy 會從同意聲明感知權杖讀取範圍，並透過 HTTP 標頭將範圍傳遞至 Cloud Healthcare API。

  4. Cloud Healthcare API 會接收並驗證標頭，以對要求強制執行同意聲明指令。接著，Cloud Healthcare API 會透過 SMARTProxy 將回應傳回給用戶端。

設定 Google Cloud 服務帳戶

Proxy 只能有一個 Google Cloud 服務帳戶。如果多個用戶端使用相同的 Proxy，這些用戶端就會使用相同的服務帳戶。基於下列原因，請謹慎與多位客戶共用服務帳戶：

舉例來說，如果您使用 Google 帳戶進行驗證，直接呼叫 Cloud Healthcare API，Cloud Audit Logs 會將您的電子郵件地址記錄為主體電子郵件地址。使用 Proxy 呼叫 Cloud Healthcare API 時，Proxy 會使用自己的服務帳戶，主體電子郵件地址為服務帳戶的電子郵件地址，且未定義原始帳戶。

稽核記錄

當有存取要求或資源的存取權強制執行設定變更時，系統就會產生稽核記錄。

存取稽核記錄

如果 FHIR 儲存區啟用稽核記錄，Cloud Logging 提供的稽核記錄就會包含 consentMode 中繼資料欄位。consentMode 可能會包含下列其中一個值：

  • off：FHIR 儲存庫設定已設為 consentConfig.accessEnforced，且不允許同意聲明感知要求。falseconsentConfig.accessEnforced

  • emptyScope：FHIR 儲存庫已將 consentConfig.accessEnforced 設為 true，但未納入同意聲明範圍標頭。因此系統不會強制執行同意聲明。

  • enforced：FHIR 儲存庫已將 consentConfig.accessEnforced 設為 true，且同意聲明範圍標頭存在。因此，系統會評估並強制執行要求中的同意聲明。

  • btg：FHIR 要求在同意範圍標頭中提供 btg。因此系統略過了同意聲明檢查。這項要求僅適用於緊急情況，且須接受事後稽核審查。

  • bypass：FHIR 要求只在同意範圍標頭中提供 bypass。因此系統略過了同意聲明檢查。這項要求適用於受信任的工作流程 (例如管理員或受信任的應用程式，而非一般使用者)，因此這份稽核記錄檔與用於資料控管檢查的 btg 不同。

您可以選擇將 access_determination_log_config 設為 VERBOSE，記錄更多要求獲准或遭拒的原因。

存取強制執行變更稽核記錄

當區間基本資源變更時 (例如移除病患的 employee 標記)：由於管理員連鎖政策，變更後的資源及其區間的存取權控管可能會變更。這會觸發所有區間資源的重新建立索引作業。您可以在 Cloud Logging 中使用 jsonPayload.@type="type.googleapis.com/google.cloud.healthcare.logging.FhirConsentCascadeLogEntry" 篩選器，追蹤每個區間基本資源更新的重新索引進度。

連鎖重新建立索引進度記錄範例

{
  "insertId": "tz2gtza8",
  "jsonPayload": {
    "@type": "type.googleapis.com/google.cloud.healthcare.logging.FhirConsentCascadeLogEntry",
    "state": "STATE_FINISHED",
    "affectedResources": "2",
    "lastUpdated": "YYYY-MM-DDTHH:MM:SS+ZZ:ZZ",
    "compartmentBaseResourceName": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Patient/PATIENT_RESOURCE_ID/_history/PATIENT_RESOURCE_VERSION"
  },
  "resource": {
    "type": "healthcare_fhir_store",
    "labels": {
      "location": "LOCATION",
      "dataset_id": "DATASET_ID",
      "fhir_store_id": "FHIR_STORE_ID",
      "project_id": "PROJECT_ID"
    }
  },
  "timestamp": "YYYY-MM-DDTHH:MM:SS+ZZ:ZZ",
  "severity": "INFO",
  "logName": "projects/PROJECT_ID/logs/healthcare.googleapis.com%2Fconsent_cascading_fhir",
  "receiveTimestamp": "YYYY-MM-DDTHH:MM:SS+ZZ:ZZ"
}

jsonPayload.state 是重新建立索引作業的狀態，jsonPayload.affectedResources 是重新建立索引的區間資源數量，jsonPayload.lastUpdated 則是病患資源更新的時間戳記。如果作業才剛開始，就不會出現 jsonPayload.state="STATE_STARTED" 和 jsonPayload.affectedResources。

限制

本節說明 FHIR R4 的限制，但這些限制也適用於 FHIR STU3。

類型 限制與上限
Single Consent 資源
  • 系統僅支援單一 Consent.provision，不支援多個佈建或巢狀佈建。
  • 至少 1 個Consent.provision.actor，最多 25 個：
    • Consent.provision.actor.role 必須為 http://terminology.hl7.org/CodeSystem/v3-RoleCode。
    • 「Consent.provision.actor.code」必須為 GRANTEE 或 HPOWATT。
  • 最多 1 個 Consent.provision.purpose：
    • Consent.provision.purpose.system 必須為 http://terminology.hl7.org/CodeSystem/v3-ActReason。
    • Consent.provision.purpose.code 不得為空，且長度最多為 13 個字元。
  • 最多 1 個 environment：
    • Consent.provision.extension.url 必須為 https://g.co/fhir/medicalrecords/Environment。
    • 系統和代碼的總長度不得超過 15 個字元。
  • 如要依資源類型篩選，Consent.provision.class.system 必須為 http://hl7.org/fhir/resource-types。
  • 如要依資料來源篩選，Consent.provision.extension.url 必須為 https://g.co/fhir/medicalrecords/DataSource。
  • 如要依資料標記篩選，Consent.provision.extension.url 必須是 https://g.co/fhir/medicalrecords/DataTag。
    • 資料標記可以是複雜的擴充功能，最多可巢狀結構化一層，用來描述與所有指定標記相符的資源政策 (以連詞解讀)。
    • 最多支援 5 個巢狀標記。
  • 除非此列另有說明，否則所有重複屬性的值最多為 100 個。
強制執行模式
  • 每位病患一次最多可有 200 項強制執行的active同意聲明資源。
  • 每個商店一次最多可強制執行 200 項 active 管理員政策。
  • 針對特定病患的所有有效同意聲明，整組同意聲明指令的特殊精簡格式不得超過大小門檻；通常有足夠容量可編碼數千個同意聲明指令，除非資源字串特別長。例如：
    • 數百個同意聲明 (針對不重複的資料來源和資料代碼，每個同意聲明都很長) 會耗用大量空間。
    • 如果單一病患在多個有效同意聲明中，各有 3000 個不重複的 Consent.provision.data.reference 資源 ID 項目，且每個項目都指定不重複的 Consent.provision.actor，則會比未指定任何資料參照限制，或包含許多相同參與者參照字串的佈建，更積極地使用空間。
  • 每項資源最多可有 1000 個同意聲明指令，這些指令來自適用於該資源的所有同意聲明。
X-Consent-Scope
  • 最少一項，最多三項 actor 項目。
  • 最多一個 purp 項目：
    • 每個 purp 項目的格式都必須為 system/code (v3 是 http://terminology.hl7.org/CodeSystem/v3-ActReason 的註冊系統)。
    • 代碼長度不得超過 13 個字元。
  • 最多一個 env 項目：
    • 每個 env 項目都必須採用 system/code 格式。
    • 系統和代碼的總長度不得超過 15 個字元。
  • btg 至少需要一個 actor 項目。
  • bypass 至少需要一個 actor 項目和一個 env 項目。
支援的方法
成效
  • ApplyConsents 和 ApplyAdminConsents 的擴充幅度與 ImportResources 相似或更勝一籌。
  • 關於同意聲明感知要求：
    • 我們的同意聲明模型已針對 CRUD 作業的強制執行效能進行最佳化，包括大規模搜尋多項資源和多位病患。
    • 讀取個別資源可能會稍微影響要求延遲時間，但搜尋成效會因基本查詢和同意範圍數量而異，導致搜尋期間有更多存取者條件處於啟用狀態。
    • 建議您針對各種代表性 FHIR 請求參數執行自己的效能測試，根據資料特性 (例如 FHIR 存放區中特定搜尋資源類型的資源數量)，判斷使用案例的效能特徵。
    • 我們的解決方案會持續擷取及更新所有資源 (包括同意聲明資源)，且不會耗用大量資源，因此擷取期間及其他形式的寫入流量可繼續進行，影響極小。

最佳做法

以下各節說明使用 FHIR 存取權控管的最佳做法。

常見的最佳做法

  • 請勿匯入 FHIR 資源，並同時呼叫 ApplyConsents 或 ApplyAdminConsents。建議您先匯入 FHIR 資源，然後呼叫 ApplyConsents 或 ApplyAdminConsents。不過，如果匯入的資源不含任何 Patient 或 Consent 資源，則強制執行模式不會受到影響，也不必處理同意聲明或管理政策。

  • 請勿建立自訂搜尋並同時呼叫 ApplyConsents。建議您依序執行。

  • 如果工作流程需要對不相連的 PatientScope 呼叫多個 ApplyConsents，可以平行呼叫。

  • ApplyAdminConsents 可以與任意數量的 ApplyConsents 並行執行，但不能與另一個 ApplyAdminConsents 並行執行。

  • 設定 Proxy 時，請限制 IAM 服務帳戶的唯讀權限，避免將某位病患的資料寫入另一位病患的記錄。

  • 建立或更新記錄時，請勿使用同意聲明 Proxy。

  • 驗證所有寫入要求，避免跨病患資料遭到意外修改。

  • 強制執行同意聲明層疊時，必須先匯入區隔基本資源，再匯入其餘區隔資源。或者，您也可以將所有區間資源包裝在單一套件中，並使用 fhir.executeBundle 擷取。

刪除 Patient 資源

刪除 Patient 資源時，如果也想移除該病患的同意聲明強制執行設定 (特別是當 FhirStore.disableReferentialIntegrity 為 true 時)，建議按照下列順序操作：

  1. 刪除 Patient 資源的所有 Consent 資源。

  2. 使用 PatientScope 篩選器呼叫 ApplyConsents。

如要為現有商店設定同意聲明存取權，請完成下列步驟：

  1. 使用 UpdateFhirStore 將 ConsentConfig 的同意聲明強制執行狀態設為 version，如 V1 ，並將 accessEnforced 設為 true。

    curl -X PATCH \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: application/json" \
    --data "{
      'consentConfig': {
        'version': 'V1',
        'accessEnforced': true
      }
    }" "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID?update_mask=consentConfig"

  2. 處理病患同意聲明或管理員政策

    1. ApplyConsents，瞭解病患同意聲明
    curl -X POST \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: application/json" \
    --data "{'validateOnly': false}" \
    "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID:applyConsents"
    1. ApplyAdminConsents，適用於管理員政策和管理員連鎖政策。
    curl -X POST \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: application/json" \
    --data "{
      'newConsentsList': {
          'names': [
          'projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Consent/RESOURCE_ID_1/_history/VERSION_ID_1',
          ...
          'projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Consent/RESOURCE_ID_N/_history/VERSION_ID_N'
          ]
      },
      'validateOnly': false
    }" \
    "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID:applyAdminConsents"

執行 ApplyConsents 或 ApplyAdminConsents 的頻率

  • 未設定 ConsentConfig 欄位：首次建立 FHIR 儲存庫時，以及清除 ConsentConfig 欄位時，ConsentConfig 欄位都會處於未設定狀態。取消設定 ConsentConfig 欄位後，您必須重複設定商店的同意聲明存取權，才能提出同意聲明相關要求，避免評估過時的同意聲明強制執行政策。

  • 強制執行模式變更：建立、更新或刪除 Consent 資源時，強制執行模式會變更。在這種情況下，您必須呼叫 ApplyConsents 或 ApplyAdminConsents，這些變更才會生效。

    • 如果可以追蹤「已同意的病患」變更，建議使用 PatientScope 篩選器，避免重新處理整個商店。這個篩選器可立即重新強制執行一小部分病患的設定。

    • 您也可以使用 TimeRange 篩選器定期執行 ApplyConsents。如果不需要立即重新整理，就很適合使用這個篩選器。舉例來說，下列要求會重新執行 2022 年 9 月 20 日世界標準時間凌晨 0 點到 2022 年 9 月 21 日世界標準時間凌晨 0 點之間的同意聲明變更。

      curl -X POST \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json" \
  --data "{
     'validateOnly': false,
     'timeRange': {
       'start': '2022-09-20T00:00:00Z',
       'end': '2022-09-21T00:00:00Z',
     }
    }" \
  "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID:applyConsents"

FHIR Consent Viewer 會顯示存取權控管政策。這份表格包含同意聲明範圍，代表 FHIR 存取權控管規則。

使用 FHIR Consent Viewer 前，請確認下列事項：

如要查看 FHIR 同意聲明檢視器，請完成下列步驟：

後續步驟