当前位置：交换- 操作
当前位置：交换工作组: FHIR Infrastructure  | 成熟度: Normative | 标准状态: Normative |
RESTful API定义了一组通用的交互动作（读取，更新，搜索等）可以操作储存库中已知类型的资源。 这些交互遵循RESTful范式，通过对一组已定义资源的Create/Read/Update/Delete 动作来管理状态。 虽然这种方法解决了许多用例，但是使用类似RPC的范式可以使用输入和输出（Execute）执行命令操作来更有效地满足某些功能。
在以下情况适合于用“操作”：
该规范描述了一个轻量级的操作框架，可以无缝扩展RESTful API。 该框架涵盖了如何执行本页涉及的操作以及如何 定义操作。
操作具有以下通用属性：
用从FHIR终结点派生的URL来执行操作，在操作的名称之前以“美元符号”（“$”字符）为前缀。例如：
POST http://fhir.someserver.org/fhir/Patient/1/$everything
当一个操作的affectsState=false，并且参数都是不带扩展名的基本数据类型（如上例所示）时，也可以使用“GET”动作来调用。 （注意：也可以使用HEAD头来请求-参见HEAD头的支持）。
可以在三类FHIR终结点上使用“操作”：
请求的body消息体包含一个参数资源(Parameters)的特殊基础资源，
参数资源是一个用
请求完成后，该操作返回另一个 参数资源(Parameters) ，其中包含一个或多个输出参数。这意味着FHIR操作可以接收一组零到多个 输入 参数，并返回一组零到多个输出参数。POST的body消息体和返回的结果通常都是一个资源。
当同时满足下列条件时，可以使用GET动作并以HTTP URL参数作为入参来调用操作：
如果只返回了一个名为“return”的输出参数，那么响应的可能是一个不带 参数资源(Parameters) 的返回值。此类用法将在后面进一步讨论。
如果返回的是一个资源捆束(Bundle)，其 Bundle.type 应该是“ collection ”，除非它具有 搜索语义 ，例如匹配的资源计数和 页面链接（“下一页”等） 。
执行操作时不带任何参数是一种特例。对于不会导致任何状态更改的操作，可以直接调用：
GET [base]/Composition/example/$document
如果调用的操作会引起状态变更，则必须用POST来调用。当不传参数资源时，POST的body消息体留空即可:
POST [base]/Claim/example/$submit Content-Length: 0
请参见 已定义的操作清单.
除了本规范定义的操作之外，实现者可自定义操作。 不同实现者定义的操作名称冲突问题，可以使用服务器的能力声明来解决。
此外，如果寻址方案不与本规范发生冲突，这些操作的定义或附加的运行时操作的定义并不会对那些不依赖RESTful API、没有与RESTful API集成的其他类型的操作造成影响。
Each Operation is defined by:
For each parameter, the following information is needed:
Parameters may be nested into multi-part parameters. Each part has the same information as a parameter, except for use, which is taken from the parameter it is part of.
The resource Operation Definition is used to provide a computable definition of the Operation.
Implementations are able to extend an operation by defining new named parameters. Implementations can publish their own extended definitions using the Operation Definition resource, and this variant definition can use OperationDefinition.base to refer to the underlying definition.
Note that the FHIR specification will never define any parameter names starting with "x-".
Operations are typically executed synchronously: a client sends a request to a server that includes the operation's in parameters and the server replies with the operation's out parameters.
The URL for an operation end-point depends on its context:
An operation is generally invoked by performing an HTTP POST to the operation's end-point. The submitted content is the special Parameters format (the "in" parameters) - a list of named parameters. For an example, see the value set expansion request example. Note that when parameters have a search type, the search modifiers are available and are used on the parameter name in the Parameters resource (e.g. "code:in").
Note that the same arrangement as for the RESTful interface applies with respect to content types.
If all the parameters for the operation are primitive types and the operation
has affectsState = false,
the operation may be invoked by performing an HTTP GET operation where all of the values of the parameters are appended
to the URL in the search portion of the URL (e.g. after the '?' character). Servers SHALL support this method of invocation.
E.g.
GET [base]/ValueSet/$expand?url=http://hl7.org/fhir/ValueSet/body-site&filter=abdo
When using the HTTP GET operation, if there is a repeating parameter for the extended operation the values for that parameter are repeated by repeating the named parameter. E.g. Observation $stats statistic parameter
GET [base]/Observation/$stats?subject=Patient/123&code=55284-4&system=http://loinc.org&duration=1&statistic=average&statistic=min&statistic=max&statistic=count
If, when invoking the operation, there is exactly one input parameter of type Resource (irrespective of whether other possible parameters are defined), that the operation can also be executed by a POST with that resource as the body of the request (and no parameters on the url).
Servers MAY choose to support submission of the parameters represented in multi-part/form-data format as well,
which can be useful when testing an operation using HTML forms.
If an operation succeeds, an HTTP Status success code is returned. This will usually be a 2xx code, though it may also be a 303 See Other. Other kinds of 3xx codes should be understood to indicate that the operation did not proceed, and the client will need to re-issue the operation if it can perform the redirection (e.g. may get redirected to an authentication step). User agents should note that servers may issue redirects, etc. to authenticate the client in response to an operation request. An HTTP status code of 4xx or 5xx indicates an error, and an OperationOutcome SHOULD be returned with details.
In general, an operation response uses the same Parameters format whether there is only one or there are multiple named out parameters.
If there is only one out parameter, which is a Resource with the parameter name "return" then the parameter format is not used, and the response is simply the resource itself.
The result of an operation is subject to content negotiation like any other interaction. Specifically, if the returned resource is a Binary, the response SHALL behave in the same manner as if a 'read' operation had been performed on the resource. I.e. The content will be returned as either a FHIR resourse with base64-encoded content or as a raw binary, depending on the Accept header specified when invoking the operation (see Serving Binary Resources using the RESTful API ).
The resources that are returned by the operation may be
retained and made available in the resource repository
on the operation server. In that case, the server will
provide the identity of the resource in the returned resources. When
resources that are not persisted are returned in the response,
they will have no id property.
Use the standard RESTful API Asynchronous pattern to execute operations asynchronously.