$member-add HealthLake 的 操作 - AWS HealthLake
操作端點Parameters請求範例回應格式商業規則身分驗證與授權操作行為限制

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

$member-add HealthLake 的 操作

FHIR $member-add操作會將成員 （病患） 新增至群組資源，特別是成員屬性清單。此操作是 DaVinci 成員屬性實作指南的一部分，並支援管理成員屬性的調校程序。

操作端點

POST [base]/datastore/{datastoreId}/r4/Group/{groupId}/$member-add
Content-Type: application/json

Parameters

操作接受具有下列參數組合的 FHIR 參數資源：

參數選項

您可以使用下列其中一個參數組合：

選項 1：成員 ID + 供應商 NPI

memberId + providerNpi

memberId + providerNpi + attributionPeriod

選項 2：病患參考 + 提供者參考

patientReference + providerReference

patientReference + providerReference + attributionPeriod

參數詳細資訊

memberId （選用）

要新增至群組之成員的識別符。

類型：Identifier

系統：病患識別符系統

{
  "name": "memberId",
  "valueIdentifier": {
    "system": "http://example.org/patient-id",
    "value": "patient-new"
  }
}
providerNpi （選用）

屬性提供者的國家提供者識別符 (NPI)。

類型：Identifier

系統：https：//http://terminology.hl7.org/CodeSystem/NPI

{
  "name": "providerNpi",
  "valueIdentifier": {
    "system": "http://terminology.hl7.org/CodeSystem/NPI",
    "value": "1234567890"
  }
}
patientReference （選用）

要新增之病患資源的直接參考。

類型：參考

{
  "name": "patientReference",
  "valueReference": {
    "reference": "Patient/patient-123"
  }
}
providerReference （選用）

直接參考提供者資源。

類型：參考

{
  "name": "providerReference",
  "valueReference": {
    "reference": "Practitioner/provider-456"
  }
}
attributionPeriod（選用）

病患歸因於提供者的期間。

類型：期間

{
  "name": "attributionPeriod",
  "valuePeriod": {
    "start": "2024-07-15",
    "end": "2025-07-14"
  }
}

請求範例

使用成員 ID 和提供者 NPI

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "memberId",
      "valueIdentifier": {
        "system": "http://example.org/patient-id",
        "value": "patient-new"
      }
    },
    {
      "name": "providerNpi",
      "valueIdentifier": {
        "system": "http://terminology.hl7.org/CodeSystem/NPI",
        "value": "1234567890"
      }
    },
    {
      "name": "attributionPeriod",
      "valuePeriod": {
        "start": "2024-07-15",
        "end": "2025-07-14"
      }
    }
  ]
}

使用病患和提供者參考

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "patientReference",
      "valueReference": {
        "reference": "Patient/patient-123"
      }
    },
    {
      "name": "providerReference",
      "valueReference": {
        "reference": "Practitioner/provider-456"
      }
    },
    {
      "name": "attributionPeriod",
      "valuePeriod": {
        "start": "2024-07-15",
        "end": "2025-07-14"
      }
    }
  ]
}

回應格式

成功的新增回應

HTTP Status: 200 OK
Content-Type: application/fhir+json

{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "success",
      "code": "informational",
      "details": {
        "text": "Member Patient/patient-new successfully added to the Member Attribution List."
      }
    }
  ]
}

錯誤回應

無效的請求語法

HTTP 狀態：400 錯誤的請求

{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "invalid",
      "details": {
        "text": "Invalid parameter combination provided"
      }
    }
  ]
}
找不到資源

HTTP 狀態：找不到 404

{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "not-found",
      "details": {
        "text": "Resource not found."
      }
    }
  ]
}
版本衝突

HTTP 狀態：409 衝突

{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "conflict",
      "details": {
        "text": "Resource version conflict detected"
      }
    }
  ]
}
無效的屬性狀態

HTTP 狀態：422 無法處理的實體

{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "business-rule",
      "details": {
        "text": "Cannot add member to Attribution List with status 'final'. Status must be 'draft' or 'open'."
      }
    }
  ]
}

商業規則

屬性狀態驗證

只有在群組的屬性狀態為：

  • draft

  • open

當狀態為 時，不允許操作final。

防止重複成員

系統會根據以下項目的唯一組合來防止新增重複的成員：

  • 成員識別符

  • 付款人識別符

  • 涵蓋範圍識別符

涵蓋期間驗證

提供 attributionPeriod 時，必須落在成員涵蓋期間的界限內。系統會：

  • 搜尋成員的涵蓋範圍資源

  • 如果存在多個 ，請使用最新的涵蓋範圍 （最高 versionId)

  • 驗證歸因期間未超過涵蓋期間

參考驗證

當同時為相同的資源 （病患或提供者） 提供 ID 和參考時，系統會驗證它們是否對應至相同的資源。

當同時為相同的資源 （病患或提供者） 提供 ID 和 reference.identifier 欄位時，會擲回錯誤。

身分驗證與授權

此操作需要對下列項目進行 FHIR 上的 SMART 授權：

  • 讀取許可 - 驗證患者、提供者和群組資源

  • 搜尋許可 - 依識別符尋找資源

  • 更新許可 - 修改群組資源

操作行為

資源更新

  • 更新群組資源版本 ID

  • 在操作之前建立具有原始資源狀態的歷史記錄項目

  • 使用 新增成員資訊至 Group.member 陣列：

    • entity.reference 中的病患參考

    • 以期間為單位的屬性期間

    • 延伸欄位中的涵蓋範圍和提供者資訊

驗證步驟

  • 參數驗證 - 確保有效的參數組合

  • 資源存在 - 驗證存在的患者、提供者和群組資源

  • 屬性狀態 - 確認群組狀態允許修改

  • 重複檢查 - 防止新增現有成員

  • 涵蓋範圍驗證 - 確保歸因期間在涵蓋範圍內

限制

  • 所有參考的資源都必須存在於相同的資料存放區中

  • 操作僅適用於成員屬性清單群組資源

  • 屬性期間必須在涵蓋範圍內

  • 無法修改具有「最終」狀態的群組