composer-docs/fhir-dev-guide.md at 4ff10f24e32e29c16a4af25b6de6c696cc69a834

16 KiB

Raw Blame History

1.7.1 开发者指南

FHIR (Fast Health Interoperability Resources)旨在数据交换，能够支撑医疗领域的多种流程。该标准基于Restful的最佳实践，能够实现跨团队的医疗系统的集成。

FHIR 所支持的范围很广泛，包括人、兽医、临床、公共卫生、临床试验、管理和财务等方面。全球通用且支持多种架构和场景。

1.7.1.1 框架

FHIR 是基于 资源这一通用组件. 每个资源都有如下通用特征:

用URL来标识
通用的元数据
供人可读的XHTML概述
通用的数据元集合
扩展的框架以支持医疗中的多样性

资源要么是 XML ，要么是 JSON格式的. 目前已经定义了99种资源类型

1.7.1.2 Patient实例

如何用JSON来表示patient。标准中也定义了XML的表达方式。



{
  "resourceType": "Patient",
  "id" : "23434",
  "meta" : {
    "versionId" : "12",
    "lastUpdated" : "2014-08-18T01:43:30Z"
  }
  "text": {
    "status": "generated",
    "div": "<!-- Snipped for Brevity -->"
  },
  "extension": [
    {
      "url": "http://example.org/consent#trials",
      "valueCode": "renal"
    }
  ],
  "identifier": [
    {
      "use": "usual",
      "label": "MRN",
      "system": "http://www.goodhealth.org/identifiers/mrn",
      "value": "123456"
    }
  ],
  "name": [
    {
      "family": [
        "Levin"
      ],
      "given": [
        "Henry"
      ],
      "suffix": [
        "The 7th"
      ]
    }
  ],
  "gender": {
    "text": "Male"
  },
  "birthDate": "1932-09-24",
  "active": true
}

每个资源包括如下内容:

resourceType (line 2) - 必须要有: FHIR 中定义了多种资源类型，详细列表请查看the full index
id (line 3) - 资源自身的id(而非资源中数据的ID 相当于资源在数据库中的主键). 一般而言都是要有的，除了在新建时之外。
meta (lines 4 - 7) - 通常要由 : 所有资源都会有的属性(这里和其他地方对元数据的定义略有偏差，参考https://github.com/memect/hao/issues/296)受基础架构控制. 如果没有元数据可以为空
text (lines 12 - 17) - 推荐使用: XHTML 包含了资源中供人可读的部分
extension (lines 12 - 17) - 可选: Extensions由扩展框架所定义
data (lines 18 - 43) - 可选: 每种资源所定义的数据项。

备注尽管标准中总是以所定义的顺序来显示JSON中数据的顺序，但很多JSON库有其他排序标准。

1.7.1.3 交互

为了操作数据，FHIR 定义了REST API:

Create = POST https://example.com/path/{resourceType}
Read = GET https://example.com/path/{resourceType}/{id}
Update = PUT https://example.com/path/{resourceType}/{id}
Delete = DELETE https://example.com/path/{resourceType}/{id}
Search = GET https://example.com/path/{resourceType}?search parameters...
History = GET https://example.com/path/{resourceType}/{id}/_history
Transaction = POST https://example.com/path/
Operation = GET https://example.com/path/{resourceType}/{id}/${opname}

除了RESTful API之外,FHIR 中还定义了其他的数据交换方式，包括文档, 消息和其他类型的服务.

1.7.1.4 对多样性的管理

医疗行业的一大特点就是不同地区和细分行业都存在很大的差异性,并不存在一个集中式的权威机构来定义通用的行业规范。鉴于此, FHIR 中定义了通用扩展框架和管理多样性的框架.

1.7.1.5 新增资源

为了新增资源, 需要发送一个 HTTP 的 POST 请求到某个资源节点(也就是某个URL).如下所示

  POST https://example.com/path/{resourceType}

POST {some base path}/Patient HTTP/1.1
Authorization: Bearer 37CC0B0E-C15B-4578-9AC1-D83DCED2B2F9
Accept: application/json+fhir
Content-Type: application/json+fhir
Content-Length: 1198

{
  "resourceType": "Patient",
  ...
}

向服务器提交一条患者记录, 服务器可以根据自己的情况分配ID来存储该患者记录。备注：

/Patient (line 1) - 处理所有患者的节点- 这里使用资源类型的名称
Authorization (line 2) - 参考 Security for FHIR
Accept, Content-Type (lines 3-4) - 如果资源的数据是JSON格式，content type需要设置成这样application/json+fhir (XML的话设置成 application/xml+fhir). 数据的编码始终是UTF-8
id (line 9) - 待新建的记录中并没有id，由服务器来分配
Resource Content, lines 8+ - 这时候也没有任何元数据。资源的其他部分同上述示例

1.7.1.6 新增资源的响应

响应中包含HTTP 201，表示服务器已经成功新建该条记录。location header 属性中包含了访问该资源的URL。响应中亦可包含OperationOutcome 资源来表达处理的一些细节,并不做硬性要求。

HTTP/1.1 201 Created
Content-Length: 161
Content-Type: application/json+fhir
Date: Mon, 18 Aug 2014 01:43:30 GMT
ETag: "1"
Location: http://example.com/Patient/347

{
  "resourceType": "OperationOutcome",
  "text": {
    "status": "generated",
    "div": "<div xmlns=\"http://www.w3.org/1999/xhtml\">The operation was successful</div>"
  }
}

Notes:

HTTP/1.1 201 (line 1) - 操作成功. Note that HTTP/1.1 is strongly recommended but not required
ETag (line 5) - used in the version aware update pattern
Location (line 6) - the id the server assigned to the resource. The id in the url must match the id in the resource when it is subsequently returned
operationOutcome (line 9) - OperationOutcome resources in this context have no id or meta element (they have no managed identity)

1.7.1.6.1 Error response

出于多种原因，服务器会返回一个错误信息，FHIR 内容相关的一些错误信息以HTTP 状态码加一个OperationOutcome来表达. 如下是一个不满足服务器端业务规则时的返回信息:

HTTP/1.1 422 Unprocessable Entity
Content-Length: 161
Content-Type: application/json+fhir
Date: Mon, 18 Aug 2014 01:43:30 GMT

{
  "resourceType": "OperationOutcome",
  "text": {
    "status": "generated",
    "div": "<div xmlns=\"http://www.w3.org/1999/xhtml\">MRN conflict
   - the MRN 123456 is already assigned to a different patient</div>"
  },
}

Notes:

服务器可通过OperationOutcome来表达更为详细的错误信息

1.7.1.7 Read Request

读取资源内容是通过HTTP GET请求来实现的.

  GET https://example.com/path/{resourceType}/{id}

GET /Patient/347?_format=xml HTTP/1.1
Host: example.com
Accept: application/xml+fhir
Cache-Control: no-cache

Notes:

347 (line 1) - 要访问资源的id
_format=xml (line 1) - 希望返回的数据格式，这种方式适合于客户端无法访问HTTP 头信息的情况，例如XSLT转换时，也可以通过HTTP 头中的accept字段来指定(see Mime Types
cache control (line 4) - 如何控制并发是很重要的，但FHIR中并未做出规定,更多信息请参考http://www.w3.org/Protocols/rfc2616/rfc2616-sec13.html 或者 https://www.mnot.net/cache_docs/

1.7.1.8 Read Response

读取单个资源内容GET请求的响应是单独的一个资源.

HTTP/1.1 200 OK
Content-Length: 729
Content-Type: application/xml+fhir
Last-Modified: Sun, 17 Aug 2014 15:43:30 GMT
ETag: "1"

<?xml version="1.0" encoding="UTF-8"?>
<Patient xmlns="http://hl7.org/fhir">
  <id value="347"/>
  <meta>
    <versionId value="1"/>
    <lastUpdated value="2014-08-18T01:43:30Z"/>
  </meta>
  <!-- content as shown above for patient -->
</Patient>

Notes:

id (line 8) - 资源的id，与请求中的id一致
versionId (line 11) - 该资源的最新版本. 最佳实践中要求该值与 ETag值匹配 (see version aware update), 对于客户端而言，不能认为二者总是匹配的. 一部分服务器并不记录资源的版本信息。
尽管建议服务器能够保留版本信息，但不做强制性要求
lastUpdated (line 12) - 如果存在该字段，字段值应与HTTP header中的值保持一致

1.7.1.9 Search Request

除了读取单个资源内容之外，也可以通过查询参数和变量查询资源内容，形式一般如下:

  GET https://example.com/path/{resourceType}?criteria

The criteria is a set of http parameters that specify which resources to return. The search operation

https://example.com/base/MedicationPrescription?patient=347

会返回该患者的所有处方信息.

1.7.1.10 Search Response

查询请求返回的对象是一个bundle: 如未明确要求，只返回满足查询参数要求的资源元数据:

{
  "resourceType": "Bundle",
  "id" : "eceb4882-5c7e-4ca4-af62-995dfb8cef01"
  "meta" : {
    "lastUpdated" : "2014-08-19T15:43:30Z"
  },
  "base": "http://example.com/base",
  "total": "3",
  "link": [
    {
      "relation" : "next",
      "url" : "https://example.com/base/MedicationPrescription?patient=347&searchId=ff15fd40-ff71-4b48-b366-09c706bed9d0&page=2"
    }, {
      "relation" : "self",
      "url" : "https://example.com/base/MedicationPrescription?patient=347"
    }
  ],
  "entry": [
    {
      "resource" : {
        "resourceType": "MedicationPrescription",
        "id" : "3123",
        "meta" : {
          "versionId" : "1",
          "lastUpdated" : "2014-08-16T05:31:17Z"
        },
        ... content of resource ...
      },
    },
    ... 2 additional resources ....
  ]
}

Notes:

resourceType (line 7) - "SearchResults" is the name for a bundle returned from a search
id (line 3) -服务器为该次查询响应bundle的唯一标识. 有些情况下要求该id满足全球唯一
meta.lastUpdated (line 10) - This should match the HTTP header, and should be the date the search was executed, or more recent, depending on how the server handles ongoing updates. The lastUpdated data SHALL be the same or more recent than the most recent resource in the results
base (line 12) - 返回的内容中所有资源引用相对地址的根地址。
total (line 13) - 满足查询条件的记录数量. 这里的数量指的是总数，而非仅该bundle中所包含的数量，详情查看可以对结果进行分页查询
link (line 14) - A set of named links that give related contexts to this bundle. Names defined in this specification: first, prev, next, last, self
item (line 23) - 用来表达满足查询条件的实际资源的元数据信息
如果加上include标签，可以强制要求服务器在返回结果中包含资源的内容，详情请参阅return additional related resources

1.7.1.11 Update Request

客户端用新版本的资源记录替换服务器中的老版本.

  PUT https://example.com/path/{resourceType}/{id}

Note that there does not need to be a resource already existing at {id} - the server may elect to automatically create the resource at the specified address. Here is an example of updating a patient:

PUT /Patient/347 HTTP/1.1
Host: example.com
Content-Type: application/json+fhir
Content-Length: 1435
Accept: application/json+fhir
If-Match: 1

{
  "resourceType": "Patient",
  "id" : "347",
  "meta" : {
    "versionId" : "1",
    "lastUpdated" : "2014-08-18T01:43:30Z"
  },
  ...
}

Notes:

resourceType (line 1) - "Patient" URL请求中的资源类型必须与提交的数据中的资源类型保持一致 (line 9)
resource id (line 1, "347") - URL中的资源id必须与提交的数据中id值保持一致(line 9)
If-Match (line 6) - 如果存在该字段，必须与资源内容中的meta.versionId值保持一致 (line 12), 服务器必须核实版本的完整性，如果不支持版本则返回412状态码
meta.lastUpdated (line 10) - This value is ignored, and will be updated by the server
resource content (line 14) - 这里省略了资源内容

1.7.1.12 Update Response

更新请求的响应包括了元数据、状态和OperationOutcome(可选):

HTTP/1.1 200 OK
Content-Length: 161
Content-Type: application/json+fhir
Date: Mon, 18 Aug 2014 01:43:30 GMT
ETag: "2"

{
  "resourceType": "OperationOutcome",
  "text": {
    "status": "generated",
    "div": "<div xmlns=\"http://www.w3.org/1999/xhtml\">The operation was successful</div>"
  }
}

Notes:

ETag (line 5) - This is the versionId of the new version

1.7.1.13 Base Resource Content

所有资源都会包含的基础信息:

{
  "resourceType" : "X",
  "id" : "12",
  "meta" : {
    "versionId" : "12",
    "lastUpdated" : "2014-08-18T01:43:30Z",
    "profile" : ["http://example-consortium.org/fhir/profile/patient"],
    "security" : [{
      "system" : "http://hl7.org/fhir/v3/ActCode",
      "code" : "EMP"
    }],
    "tag" : [{
      "system" : "http://example.com/codes/workflow",
      "code" : "needs-review"
    }]
  },
  "implicitRules" : "http://example-consortium.org/fhir/ehr-plugins",
  "language" : "X"
}

Implementers notes:

resourceType (line 2) - 每个资源都会资源类型的字段. XML的话也就是根节点
id (line 3) - 在资源新建之时分配后不再变化.只有在初次创建该资源时才没有该字段
meta.versionId (line 5) - 当资源内容(除了meta.security、meta.profile、meta.tag三个之外)发生变更时该值随之变化
meta.lastUpdated (line 6) - 随versionId的变化而变化. 如果服务器不维护版本信息，则不用记录该字段
meta.profile (line 7) - 表示资源的内容是否遵循某个规范(比方说满足阿里健康的开放API的要求或者说满足卫计委共享文档中的要求). 更多信息请参考 Extending and Restricting Resources. 当规范、值集本身发生变动时可以更改该字段的值
meta.security (lines 8 - 11) - 安全类标签. 该标签将资源与某些安全策略、基础架构策略联系起来。该字段的值可随资源内容的变动而变动,或者随安全体系的控制。
meta.tag (lines 12 - 16) - 其他类型的标签. 如需将资源与特定的工作流程关联起来可以使用此类标签.在解读资源内容时无需考虑此类标签的值。对此类标签值的更新不会影响资源内容版本的变化 updated (这里好像是说可以不变更资源的版本就修改tag标签的值还是说tag值的修改压根就不影响资源版本其他的security和profile tag三个字段是否都适用呢？待考证)
implicitRules (lines 17) - 如何准确安全的处理资源内容而在发送接收双方达成的协议. 由于使用了该字段就意味着其他系统要使用其中的数据可能会出现解读错误的情况，限制了数据的重复利用，故不推荐适用该字段
language (lines 18) - 资源内容所采用的表达语言. 当前，资源内容中亦可包含其他语言的内容; 该字段表示的是资源的主要语言。

16 KiB Raw Blame History Unescape Escape

1.7.1 开发者指南

1.7.1.1 框架

1.7.1.2 Patient实例

1.7.1.3 交互

1.7.1.4 对多样性的管理

1.7.1.5 新增资源

1.7.1.6 新增资源的响应

1.7.1.6.1 Error response

1.7.1.7 Read Request

1.7.1.8 Read Response

1.7.1.9 Search Request

1.7.1.10 Search Response

1.7.1.11 Update Request

1.7.1.12 Update Response

1.7.1.13 Base Resource Content

16 KiB

Raw Blame History