HealthLake 的 FHIR $questionnaire-package操作

$questionnaire-package 操作會擷取完整的套件，其中包含 FHIR 問卷及其轉譯和處理問卷所需的所有相依性。此操作會實作 Da Vinci 文件範本和規則 (DTR) 實作指南，針對醫療工作流程中的文件需求啟用動態表單轉譯。

運作方式

使用案例

API 端點

POST /datastore/{datastoreId}/r4/Questionnaire/$questionnaire-package  
Content-Type: application/fhir+json

請求參數

輸入參數

請求內文必須包含具有下列參數的 FHIR 參數資源：

參數驗證規則

至少必須提供下列其中一項 （除了必要的 之外coverage)：

有效的請求組合：

範例請求

POST /datastore/example-datastore/r4/Questionnaire/$questionnaire-package  
Content-Type: application/fhir+json  
Authorization: Bearer <your-token>  
  
{  
  "resourceType": "Parameters",  
  "parameter": [  
    {  
      "name": "coverage",  
      "resource": {  
        "resourceType": "Coverage",  
        "id": "example-coverage",  
        "status": "active",  
        "beneficiary": {  
          "reference": "Patient/example-patient"  
        },  
        "payor": [{  
          "reference": "Organization/example-payer"  
        }],  
        "class": [{  
          "type": {  
            "coding": [{  
              "system": "http://terminology.hl7.org/CodeSystem/coverage-class",  
              "code": "group"  
            }]  
          },  
          "value": "12345"  
        }]  
      }  
    },  
    {  
      "name": "questionnaire",  
      "valueCanonical": "http://example.org/fhir/Questionnaire/home-oxygen-therapy|2.0"  
    },  
    {  
      "name": "order",  
      "resource": {  
        "resourceType": "ServiceRequest",  
        "id": "example-service-request",  
        "status": "active",  
        "intent": "order",  
        "code": {  
          "coding": [{  
            "system": "http://www.ama-assn.org/go/cpt",  
            "code": "94660",  
            "display": "Continuous positive airway pressure ventilation (CPAP)"  
          }]  
        },  
        "subject": {  
          "reference": "Patient/example-patient"  
        }  
      }  
    },  
    {  
      "name": "changedSince",  
      "valueDateTime": "2024-01-01T00:00:00Z"  
    }  
  ]  
}

回應格式

成功回應 (200 OK)

操作會傳回包含一或多個套件套件的 FHIR 參數資源。每個套件套件都包含：

{  
  "resourceType": "Parameters",  
  "parameter": [  
    {  
      "name": "PackageBundle",  
      "resource": {  
        "resourceType": "Bundle",  
        "id": "questionnaire-package-example",  
        "meta": {  
          "profile": ["http://hl7.org/fhir/us/davinci-dtr/StructureDefinition/DTR-QPackageBundle"]  
        },  
        "type": "collection",  
        "timestamp": "2024-03-15T10:30:00Z",  
        "entry": [  
          {  
            "fullUrl": "http://example.org/fhir/Questionnaire/home-oxygen-therapy",  
            "resource": {  
              "resourceType": "Questionnaire",  
              "id": "home-oxygen-therapy",  
              "url": "http://example.org/fhir/Questionnaire/home-oxygen-therapy",  
              "version": "2.0",  
              "status": "active",  
              "title": "Home Oxygen Therapy Documentation",  
              "item": [  
                {  
                  "linkId": "1",  
                  "text": "Patient diagnosis",  
                  "type": "choice",  
                  "answerValueSet": "http://example.org/fhir/ValueSet/oxygen-diagnoses"  
                }  
              ]  
            }  
          },  
          {  
            "fullUrl": "http://example.org/fhir/Library/oxygen-prepopulation",  
            "resource": {  
              "resourceType": "Library",  
              "id": "oxygen-prepopulation",  
              "url": "http://example.org/fhir/Library/oxygen-prepopulation",  
              "version": "1.0",  
              "type": {  
                "coding": [{  
                  "system": "http://terminology.hl7.org/CodeSystem/library-type",  
                  "code": "logic-library"  
                }]  
              },  
              "content": [{  
                "contentType": "text/cql",  
                "data": "bGlicmFyeSBPeHlnZW5QcmVwb3B1bGF0aW9u..."  
              }]  
            }  
          },  
          {  
            "fullUrl": "http://example.org/fhir/ValueSet/oxygen-diagnoses",  
            "resource": {  
              "resourceType": "ValueSet",  
              "id": "oxygen-diagnoses",  
              "url": "http://example.org/fhir/ValueSet/oxygen-diagnoses",  
              "status": "active",  
              "expansion": {  
                "timestamp": "2024-03-15T10:30:00Z",  
                "contains": [  
                  {  
                    "system": "http://hl7.org/fhir/sid/icd-10",  
                    "code": "J44.0",  
                    "display": "COPD with acute lower respiratory infection"  
                  },  
                  {  
                    "system": "http://hl7.org/fhir/sid/icd-10",  
                    "code": "J96.01",  
                    "display": "Acute respiratory failure with hypoxia"  
                  }  
                ]  
              }  
            }  
          },  
          {  
            "fullUrl": "http://example.org/fhir/QuestionnaireResponse/example-prepopulated",  
            "resource": {  
              "resourceType": "QuestionnaireResponse",  
              "id": "example-prepopulated",  
              "questionnaire": "http://example.org/fhir/Questionnaire/home-oxygen-therapy|2.0",  
              "status": "in-progress",  
              "subject": {  
                "reference": "Patient/example-patient"  
              },  
              "basedOn": [{  
                "reference": "ServiceRequest/example-service-request"  
              }],  
              "item": [  
                {  
                  "linkId": "1",  
                  "text": "Patient diagnosis",  
                  "answer": [{  
                    "valueCoding": {  
                      "system": "http://hl7.org/fhir/sid/icd-10",  
                      "code": "J44.0",  
                      "display": "COPD with acute lower respiratory infection"  
                    }  
                  }]  
                }  
              ]  
            }  
          }  
        ]  
      }  
    },  
    {  
      "name": "Outcome",  
      "resource": {  
        "resourceType": "OperationOutcome",  
        "issue": [{  
          "severity": "information",  
          "code": "informational",  
          "details": {  
            "text": "Successfully retrieved questionnaire package"  
          }  
        }]  
      }  
    }  
  ]  
}

操作工作流程

HealthLake 如何處理您的請求

當您呼叫 時$questionnaire-package，HealthLake 會執行下列步驟：

結果：準備進行轉譯的完整、獨立套件。

錯誤回應

400 錯誤的請求

請求驗證失敗時傳回。

{  
  "resourceType": "OperationOutcome",  
  "issue": [{  
    "severity": "error",  
    "code": "required",  
    "details": {  
      "text": "At least one of 'questionnaire' or 'order' must be provided along with 'coverage'"  
    }  
  }]  
}

424 失敗相依性

當無法擷取相依資源時傳回。

{  
  "resourceType": "OperationOutcome",  
  "issue": [{  
    "severity": "warning",  
    "code": "not-found",  
    "details": {  
      "text": "Referenced Library 'http://example.org/fhir/Library/missing-library' could not be retrieved"  
    }  
  }]  
}

401 (未經授權)

當身分驗證憑證遺失或無效時傳回。

403 禁止

當已驗證的使用者缺少存取所請求資源的許可時傳回。

406 無法接受

當無法提供請求的內容類型時傳回。

409 衝突

發生版本或並行衝突時傳回。

410 Gone

當請求的資源永久刪除時傳回。

429 太多請求

超過速率限制時傳回。

500 內部伺服器錯誤

發生非預期的伺服器錯誤時傳回。

501 未實作

請求的操作尚未實作時傳回。

驗證規則

輸入驗證

QuestionnaireResponse驗證

資源重複資料刪除

效能規格

所需的許可

若要使用 $questionnaire-package操作，請確定您的 IAM 角色具有：

FHIR 範圍上的 SMART

所需範圍下限：

重要實作備註

資源擷取策略

問卷識別優先順序：

相依性解析

CQL 程式庫：

ValueSets：

QuestionnaireResponse預先填入

下列情況下，操作可能會傳回具有預先填入資料的 QuestionnaireResponse：

QuestionnaireResponse的搜尋條件：

變更資源篩選

提供 changedSince 參數時：

多個套件套件

下列情況下，操作可能會傳回多個套件套件：

每個套件套件都與所有必要的相依性獨立。

常用案例

使用案例 1：預先授權文件

案例：提供者需要收集家庭供氧治療預先授權的文件。

{  
  "resourceType": "Parameters",  
  "parameter": [  
    {  
      "name": "coverage",  
      "resource": { /* Patient's insurance coverage */ }  
    },  
    {  
      "name": "order",  
      "resource": {  
        "resourceType": "ServiceRequest",  
        "code": {  
          "coding": [{  
            "system": "http://www.ama-assn.org/go/cpt",  
            "code": "94660"  
          }]  
        }  
      }  
    }  
  ]  
}

結果：傳回包含氧氣治療問卷的套件，預先填入來自 EHR 的患者生命值和診斷碼。

使用案例 2：擷取特定問卷版本

案例：供應商需要特定版本的問卷才能合規。

{  
  "resourceType": "Parameters",  
  "parameter": [  
    {  
      "name": "coverage",  
      "resource": { /* Coverage resource */ }  
    },  
    {  
      "name": "questionnaire",  
      "valueCanonical": "http://example.org/fhir/Questionnaire/dme-request|3.1.0"  
    }  
  ]  
}

結果：傳回含所有相依性的確切版本 3.1.0 的 DME 請求問卷。

使用案例 3：檢查更新

案例：供應商想要檢查自上次擷取以來是否有任何問卷資源已更新。

{  
  "resourceType": "Parameters",  
  "parameter": [  
    {  
      "name": "coverage",  
      "resource": { /* Coverage resource */ }  
    },  
    {  
      "name": "questionnaire",  
      "valueCanonical": "http://example.org/fhir/Questionnaire/medication-request"  
    },  
    {  
      "name": "changedSince",  
      "valueDateTime": "2024-03-01T00:00:00Z"  
    }  
  ]  
}

結果：僅傳回在 2024 年 3 月 1 日之後修改的資源，如果沒有變更，則傳回空白套件。

使用案例 4：多個訂單

案例：供應商提交多個可能需要不同問卷的服務請求。

{  
  "resourceType": "Parameters",  
  "parameter": [  
    {  
      "name": "coverage",  
      "resource": { /* Coverage resource */ }  
    },  
    {  
      "name": "order",  
      "resource": { /* ServiceRequest for imaging */ }  
    },  
    {  
      "name": "order",  
      "resource": { /* ServiceRequest for DME */ }  
    }  
  ]  
}

結果：傳回多個套件套件，每個適用的問卷各一個。

與其他 Da Vinci IGs整合

涵蓋範圍需求探索 (CRD)

工作流程整合：

預先授權支援 (PAS)

工作流程整合：

臨床資料交換 (CDex)

工作流程整合：

故障診斷指南

問題：未傳回問卷

可能的原因：

解決方案：

問題：套件中缺少相依性

可能的原因：

解決方案：

問題：含 changedSince 的空套件

可能的原因：

解決方案：

問題：未預先填入 QuestionnaireResponse

可能的原因：

解決方案：

最佳實務

1. 搭配版本使用正式 URLs

請求特定問卷時，請務必指定版本編號：

{  
  "name": "questionnaire",  
  "valueCanonical": "http://example.org/fhir/Questionnaire/dme|2.1.0"  
}

原因：確保一致性，並防止更新問卷時的意外變更。

2. 利用 changedSince for Performance

對於經常存取的問卷，請使用 changedSince 將資料傳輸降至最低：

{  
  "name": "changedSince",  
  "valueDateTime": "2024-03-10T15:30:00Z"  
}

原因：僅擷取更新的資源，以減少延遲和頻寬使用量。

3. 包含完整涵蓋範圍資訊

提供全面的涵蓋範圍詳細資訊，以確保正確的問卷選擇：

{  
  "name": "coverage",  
  "resource": {  
    "resourceType": "Coverage",  
    "beneficiary": { "reference": "Patient/123" },  
    "payor": [{ "reference": "Organization/payer-abc" }],  
    "class": [{ /* Group/plan information */ }]  
  }  
}

原因：協助 HealthLake 識別付款人特定的問卷和要求。

相關的 操作