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

綁定 FHIR 資源

FHIR Bundle是 中 FHIR 資源集合的容器 AWS HealthLake。 AWS HealthLake 支援兩種具有不同處理行為的套件類型。

Batch 套件會獨立處理每個資源。如果某個資源失敗，剩餘的資源仍然可以成功。每個操作都會個別處理，即使某些操作失敗，也會繼續處理。將批次套件用於可接受部分成功的大量操作，例如上傳多個不相關的病患記錄。

Transaction 套件會以原子方式將所有資源處理為單一單位。所有資源操作都會成功，或不會 AWS HealthLake 遞交任何操作。當您需要相關資源的保證參考完整性時，請使用交易套件，例如建立具有相關觀察和條件的患者，其中所有資料必須一起記錄。

您可以綁定相同或不同類型的 FHIR 資源，它們可以包含 FHIR 操作的混合，例如 create、read、update、 delete和 patch。如需詳細資訊，請參閱 FHIR R4 文件中的資源套件。

以下是每個套件類型的範例使用案例。

下列範例顯示具有多種資源類型和操作的交易套件。

{
  "resourceType": "Bundle",
  "type": "transaction",
  "entry": [
    {
      "fullUrl": "urn:uuid:4f6a30fb-cd3c-4ab6-8757-532101f72065",
      "resource": {
        "resourceType": "Patient",
        "id": "new-patient",
        "active": true,
        "name": [
          {
            "family": "Johnson",
            "given": [
              "Sarah"
            ]
          }
        ],
        "gender": "female",
        "birthDate": "1985-08-12",
        "telecom": [
          {
            "system": "phone",
            "value": "555-123-4567",
            "use": "home"
          }
        ]
      },
      "request": {
        "method": "POST",
        "url": "Patient"
      }
    },
    {
      "fullUrl": "urn:uuid:7f83f473-d8cc-4a8d-86d3-9d9876a3248b",
      "resource": {
        "resourceType": "Observation",
        "id": "blood-pressure",
        "status": "final",
        "code": {
          "coding": [
            {
              "system": "http://loinc.org",
              "code": "85354-9",
              "display": "Blood pressure panel"
            }
          ],
          "text": "Blood pressure panel"
        },
        "subject": {
          "reference": "urn:uuid:4f6a30fb-cd3c-4ab6-8757-532101f72065"
        },
        "effectiveDateTime": "2023-10-15T09:30:00Z",
        "component": [
          {
            "code": {
              "coding": [
                {
                  "system": "http://loinc.org",
                  "code": "8480-6",
                  "display": "Systolic blood pressure"
                }
              ]
            },
            "valueQuantity": {
              "value": 120,
              "unit": "mmHg",
              "system": "http://unitsofmeasure.org",
              "code": "mm[Hg]"
            }
          },
          {
            "code": {
              "coding": [
                {
                  "system": "http://loinc.org",
                  "code": "8462-4",
                  "display": "Diastolic blood pressure"
                }
              ]
            },
            "valueQuantity": {
              "value": 80,
              "unit": "mmHg",
              "system": "http://unitsofmeasure.org",
              "code": "mm[Hg]"
            }
          }
        ]
      },
      "request": {
        "method": "POST",
        "url": "Observation"
      }
    },
    {
      "resource": {
        "resourceType": "Appointment",
        "id": "appointment-123",
        "status": "booked",
        "description": "Annual physical examination",
        "start": "2023-11-15T09:00:00Z",
        "end": "2023-11-15T09:30:00Z",
        "participant": [
          {
            "actor": {
              "reference": "urn:uuid:4f6a30fb-cd3c-4ab6-8757-532101f72065"
            },
            "status": "accepted"
          }
        ]
      },
      "request": {
        "method": "PUT",
        "url": "Appointment/appointment-123"
      }
    },
    {
      "request": {
        "method": "DELETE",
        "url": "MedicationRequest/med-request-456"
      }
    }
  ]
}

將 FHIR 資源綁定為獨立實體

將 FHIR 資源綁定為獨立實體

套件中的條件式 PUTs

AWS HealthLake 支援使用下列查詢參數在套件內進行條件式更新：

當您在套件中使用條件式 PUTs 時， 會根據現有資源 AWS HealthLake 評估查詢參數，並根據相符結果採取動作。

在具有條件式更新的下列範例套件中，只有在符合條件時，具有 FHIR ID _lastUpdated=lt2025-04-20 Patient的資源才會476更新。

{
    "resourceType": "Bundle",
    "id": "bundle-batch",
    "meta": {
        "lastUpdated": "2014-08-18T01:43:30Z"
    },
    "type": "batch",
    "entry": [
        {
            "resource": {
                "resourceType": "Patient",
                "id": "476",
                "meta": {
                    "lastUpdated": "2022-06-03T17:53:36.724Z"
                },
                "active": true,
                "name": [
                    {
                        "use": "official",
                        "family": "Jackson",
                        "given": [
                            "Mateo",
                            "James"
                        ]
                    }
                ],
                "gender": "male",
                "birthDate": "1974-12-25"
            },
            "request": {
                "method": "PUT",
                "url": "Patient?_id=476&_lastUpdated=lt2025-04-20"
            }
        },
        {
            "resource": {
                "resourceType": "Medication",
                "id": "med0310",
                "contained": [
                    {
                        "resourceType": "Substance",
                        "id": "sub03",
                        "code": {
                            "coding": [
                                {
                                    "system": "http://snomed.info/sct",
                                    "code": "55452001",
                                    "display": "Oxycodone (substance)"
                                }
                            ]
                        }
                    }
                ],
                "code": {
                    "coding": [
                        {
                            "system": "http://snomed.info/sct",
                            "code": "430127000",
                            "display": "Oral Form Oxycodone (product)"
                        }
                    ]
                },
                "form": {
                    "coding": [
                        {
                            "system": "http://snomed.info/sct",
                            "code": "385055001",
                            "display": "Tablet dose form (qualifier value)"
                        }
                    ]
                },
                "ingredient": [
                    {
                        "itemReference": {
                            "reference": "#sub03"
                        },
                        "strength": {
                            "numerator": {
                                "value": 5,
                                "system": "http://unitsofmeasure.org",
                                "code": "mg"
                            },
                            "denominator": {
                                "value": 1,
                                "system": "http://terminology.hl7.org/CodeSystem/v3-orderableDrugForm",
                                "code": "TAB"
                            }
                        }
                    }
                ]
            },
            "request": {
                "method": "POST",
                "url": "Medication"
            }
        }
    ]
}

將 FHIR 資源綁定為單一實體

將 FHIR 資源綁定為單一實體

設定套件的驗證層級

綁定 FHIR 資源時，您可以選擇指定 x-amzn-healthlake-fhir-validation-level HTTP 標頭來設定資源的驗證層級。此驗證層級將針對 bundle 內的所有建立和更新請求設定。 AWS HealthLake 目前支援下列驗證層級：

與最低驗證層級綁定的資源可能會擷取至資料存放區，即使搜尋索引所需的驗證失敗。在此情況下，資源將更新為包含 Healthlake 特定的延伸，以記錄上述失敗，而套件回應中的項目將包含 OperationOutcome 資源，如下所示：

{
    "resourceType": "Bundle",
    "type": "batch-response",
    "timestamp": "2025-08-25T22:58:48.846287342Z",
    "entry": [
        {
            "response": {
                "status": "201",
                "location": "Patient/195abc49-ba8e-4c8b-95c2-abc88fef7544/_history/1",
                "etag": "W/\"1\"",
                "lastModified": "2025-08-25T22:58:48.801245445Z",
                "outcome": {
                    "resourceType": "OperationOutcome",
                    "issue": [
                        {
                            "severity": "error",
                            "code": "processing",
                            "details": {
                                "text": "FHIR resource in payload failed FHIR validation rules."
                            },
                            "diagnostics": "FHIR resource in payload failed FHIR validation rules."
                        }
                    ]
                }
            }
        }
    ]
}

此外，以下 HTTP 回應標頭會包含在「true」的值中：

x-amzn-healthlake-validation-issues : true

對 Bundle 類型 "message" 的有限支援

HealthLake message 透過內部轉換程序提供 FHIR Bundle 類型的有限支援。此支援適用於訊息套件無法在來源重新格式化的情況，例如從舊版醫院系統擷取 ADT (Admission、Discharge、Transfer) 饋送。

與標準訊息處理的主要差異

重要限制

訊息套件結構範例

{
              "resourceType": "Bundle",
              "type": "message",
              "entry": [
                {
                  "resource": {
                    "resourceType": "MessageHeader",
                    "eventCoding": {
                      "system": "http://hl7.org/fhir/us/davinci-alerts/CodeSystem/notification-event",
                      "code": "notification-admit"
                    },
                    "focus": [{"reference": "Encounter/example-id"}]
                  }
                },
                {
                  "resource": {"resourceType": "Patient", "id": "example-id"}
                },
                {
                  "resource": {"resourceType": "Encounter", "id": "example-id"}
                }
              ]
            }
            

非同步套件交易

AWS HealthLake 支援非同步Bundle類型transaction，可讓您提交最多 500 個資源的交易。當您提交非同步交易時，HealthLake 會將其排入佇列進行處理，並立即傳回輪詢 URL。您可以使用此 URL 來檢查狀態並擷取回應。這遵循 FHIR 非同步套件模式。

何時使用非同步交易

提交非同步交易

若要提交非同步交易，請使用 Prefer: respond-async標頭傳送POST請求至資料存放區端點。套件必須具有類型 transaction。非同步套件處理batch不支援 類型的套件。

HealthLake 會在提交時對套件進行初始驗證。如果驗證成功，HealthLake 會傳回 HTTP 202 已接受，其中包含輪詢 URL 的content-location回應標頭。

提交非同步Bundle類型 transaction

輪詢交易狀態

提交非同步交易之後，請使用content-location回應標頭中的輪詢 URL 來檢查交易狀態。將GET請求傳送至輪詢 URL。

將GET請求傳送至輪詢 URL。下列範例使用 curl命令列工具。

SigV4

SigV4 授權

curl --request GET \
  'https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Transaction/transactionId' \
  --aws-sigv4 'aws:amz:region:healthlake' \
  --user "$AWS_ACCESS_KEY_ID:$AWS_SECRET_ACCESS_KEY" \
  --header "x-amz-security-token:$AWS_SESSION_TOKEN" \
  --header 'Accept: application/json'

SMART on FHIR

FHIR 授權上的 SMART。授權字符必須包含Transaction資源類型的read許可。

curl --request GET \
  'https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Transaction/transactionId' \
  --header 'Authorization: Bearer $SMART_ACCESS_TOKEN' \
  --header 'Accept: application/json'

下表說明可能的回應。

下列範例顯示每個回應類型。

已排入佇列的交易 (202)

{
    "resourceType": "OperationOutcome",
    "id": "transactionId",
    "issue": [
        {
            "severity": "information",
            "code": "informational",
            "diagnostics": "SUBMITTED"
        }
    ]
}

交易處理 (202)

{
    "resourceType": "OperationOutcome",
    "id": "transactionId",
    "issue": [
        {
            "severity": "information",
            "code": "informational",
            "diagnostics": "IN_PROGRESS"
        }
    ]
}

交易已完成 (200)

{
    "resourceType": "Bundle",
    "type": "transaction-response",
    "entry": [
        {
            "response": {
                "status": "201",
                "location": "Patient/example-id/_history/1",
                "etag": "W/\"1\"",
                "lastModified": "2024-01-15T10:30:00.000Z"
            }
        },
        {
            "response": {
                "status": "201",
                "location": "Observation/example-id/_history/1",
                "etag": "W/\"1\"",
                "lastModified": "2024-01-15T10:30:00.000Z"
            }
        }
    ]
}

交易失敗 (4xx/5xx)

{
    "resourceType": "OperationOutcome",
    "issue": [
        {
            "severity": "error",
            "code": "exception",
            "diagnostics": "Transaction failed: conflict detected on resource Patient/example-id"
        }
    ]
}

處理順序

類型的非同步套件transaction會排入佇列，但不會以嚴格的提交順序處理。HealthLake 會根據可用容量和系統負載來最佳化處理。

配額和限流

下列配額和速率限制適用於非同步交易。

錯誤處理

對於「交易」套件，套件中包含的所有 FHIR 資源都會處理為原子操作。操作中的所有資源都必須成功，否則套件中不會處理任何操作。

錯誤分為兩個類別：HealthLake 同步傳回的提交錯誤，以及處理您透過輪詢擷取的錯誤。

提交錯誤

HealthLake 會在提交時驗證套件，並在交易排入佇列之前同步傳回錯誤。提交錯誤包括無效的 FHIR 資源驗證錯誤、不支援的資源類型、超過 500 個操作限制，以及搭配批次套件使用 Prefer: respond-async標頭。如果已達到資料存放區的待處理交易限制，HealthLake 會傳回 ThrottlingException。發生提交錯誤時，交易將不會排入佇列。

處理錯誤

處理錯誤會在交易排入佇列後發生，並透過輪詢 URL 傳回。這些包括交易衝突，其中另一個操作修改了屬於交易一部分的資源，以及在處理期間發生伺服器錯誤。發生處理錯誤時，交易中的資源不會進行任何資源變動。輪詢 URL 將傳回OperationOutcome具有錯誤詳細資訊的 。