[[["容易理解","easyToUnderstand","thumb-up"],["確實解決了我的問題","solvedMyProblem","thumb-up"],["其他","otherUp","thumb-up"]],[["難以理解","hardToUnderstand","thumb-down"],["資訊或程式碼範例有誤","incorrectInformationOrSampleCode","thumb-down"],["缺少我需要的資訊/範例","missingTheInformationSamplesINeed","thumb-down"],["翻譯問題","translationIssue","thumb-down"],["其他","otherDown","thumb-down"]],["上次更新時間：2025-09-04 (世界標準時間)。"],[[["\u003cp\u003eThis page details how the Cloud Healthcare API handles FHIR resource references, which are directional links between a source and a target resource, enabling the connection of different FHIR resources.\u003c/p\u003e\n"],["\u003cp\u003eThe Cloud Healthcare API supports several formats for \u003ccode\u003eReference.reference\u003c/code\u003e, including local resource references, URIs beginning with \u003ccode\u003eurn:uuid\u003c/code\u003e or \u003ccode\u003eurn:oid\u003c/code\u003e, full external URLs, and fragment references to contained resources.\u003c/p\u003e\n"],["\u003cp\u003eLocal resource references can include the full FHIR store name and support versioned references to specific historical versions of resources, with an optional referential integrity check.\u003c/p\u003e\n"],["\u003cp\u003eConditional references, using search queries, are supported for resolving the target resource ID at request time within the \u003ccode\u003eexecuteBundle\u003c/code\u003e method, provided they uniquely identify a single target resource.\u003c/p\u003e\n"],["\u003cp\u003eFragment references allow linking to contained resources within a parent resource using \u003ccode\u003e#[INLINE_RESOURCE_ID]\u003c/code\u003e, with the constraint that these contained resources can only be referenced by their container or other contained resources within the same container.\u003c/p\u003e\n"]]],[],null,["# FHIR resource references\n\nThis page explains how the Cloud Healthcare API supports\n[FHIR resource references](https://www.hl7.org/fhir/references.html).\n\nOverview\n--------\n\nFHIR resource references are directional links from a source resource to a\ntarget resource. FHIR resource references can be used to connect resources. For\nexample, the FHIR resource type `Observation` has a `subject` field of\n[Reference](https://www.hl7.org/fhir/references-definitions.html) type, which\ncan be used to link to a `Patient` resource as the subject of the observation.\n\nFHIR resource references can also be circular. For example, the FHIR resource\ntype `CarePlan` has a `replaces` field that can point to another `CarePlan`.\n\nThe most important element in the FHIR reference structure is\n[reference](https://www.hl7.org/fhir/references-definitions.html#Reference.reference).\nThe other elements, such as `display` and `identifier` are persisted as they are\nin the Cloud Healthcare API.\n\nThe supported formats of `Reference.reference` in the Cloud Healthcare API\ninclude:\n\n- [Local resource reference](#local_resource_reference)\n- [URI beginning with `urn:uuid` or `urn:oid`](#uri_beginning_with_urn:uuid_or_urn:oid)\n- [Full external URL](#full_external_url)\n- [Fragment reference](#fragment_reference)\n\nLocal resource reference\n------------------------\n\nResource references are defined as\n\u003cvar translate=\"no\"\u003eRESOURCE_TYPE\u003c/var\u003e`/`\u003cvar translate=\"no\"\u003eRESOURCE_ID\u003c/var\u003e.\nThe Cloud Healthcare API also supports prepending the full FHIR store name\nin front of \u003cvar translate=\"no\"\u003eRESOURCE_TYPE\u003c/var\u003e`/`\u003cvar translate=\"no\"\u003eRESOURCE_ID\u003c/var\u003e. For\nexample,\n\u003cvar translate=\"no\"\u003eFHIR_STORE_NAME\u003c/var\u003e`/`\u003cvar translate=\"no\"\u003eRESOURCE_TYPE\u003c/var\u003e`/`\u003cvar translate=\"no\"\u003eRESOURCE_ID\u003c/var\u003e.\nIf you use this format, the store name must match the FHIR store of the request.\nOtherwise, the request is rejected due to non-local references.\n\nThe store configuration option\n[`FhirStore.disableReferentialIntegrity`](/healthcare-api/docs/reference/rest/v1/projects.locations.datasets.fhirStores#FhirStore)\ncontrols the referential integrity check for local reference validation, which\nis enabled by default. For more information on the referential integrity check,\nsee\n[FHIR referential integrity](/healthcare-api/docs/concepts/fhir-referential-integrity).\n\n### Versioned references\n\nCloud Healthcare API supports references to a specific version of the target\nresource. To link to a specific version of the target resource, use the format\nafter the \u003cvar translate=\"no\"\u003eRESOURCE_ID\u003c/var\u003e`/_history/`\u003cvar translate=\"no\"\u003eVERSION_ID\u003c/var\u003e\\] in\nthe local reference.\n\nWhen the referential integrity check is enabled, the server verifies that the\nhistorical version exists in the FHIR store. The\n[`Resource-purge`](/healthcare-api/docs/reference/rest/v1/projects.locations.datasets.fhirStores.fhir/Resource-purge)\nmethod removes historical versions regardless of whether they are referenced.\n\n### Conditional references\n\nAs an alternative to explicitly specifying the target resource ID,\n[`executeBundle`](/healthcare-api/docs/reference/rest/v1/projects.locations.datasets.fhirStores.fhir/executeBundle)\naccepts a [conditional reference](https://www.hl7.org/fhir/http.html#trules)\nsearch query for the target resource that resolves to the target resource ID at\nrequest time. For example, `Patient?identifier=abc`.\n\nIf the search query does not resolve to a target resource or resolves to more\nthan one target resource, the server rejects the request regardless of whether\nreferential integrity checking is enabled.\n\nURI beginning with `urn:uuid` or `urn:oid`\n------------------------------------------\n\nWhen using the\n[`executeBundle`](/healthcare-api/docs/reference/rest/v1/projects.locations.datasets.fhirStores.fhir/executeBundle)\nmethod with a transaction bundle, universally unique identifier (UUID) or object\nidentifier(OID) references can be used to resolve references to other resources\nbeing created or updated in the same bundle. For more information, see the\n[Managing FHIR bundles guide](/healthcare-api/docs/how-tos/fhir-bundles).\n\nFull external URL\n-----------------\n\nFull external URLs such as `http://www.example.com/abc` are stored unmodified\nin the reference field. The Cloud Healthcare API does not resolve the URL or\ntry to verify its validity.\n\nWhen the full external URL matches the full URL of the FHIR store of the\nrequest, the reference is treated as a local resource reference.\n\nFragment reference\n------------------\n\nA fragment reference points to a\n[contained resource](https://www.hl7.org/fhir/references.html#contained)\ninlined in a resource. For example, if an Observation record mentions a\ngeneral practitioner but there is no controlled practitioner directory, a full\nPractitioner resource can't be created. The general practitioner is a contained\nresource in the Observation record. The Reference fields on a resource can point\nto the inlined resources using the form of `#[INLINE_RESOURCE_ID]`.\n\nIn the following FHIR R4 sample, `p1` and `p2` are inline resource IDs that are\nreferenced as `#p1` and `#p2`: \n\n {\n \"resourceType\": \"Observation\",\n \"contained\": [\n {\n \"resourceType\":\"Patient\",\n \"id\": \"p1\",\n \"generalPractitioner\": {\"reference\": \"#p2\"}\n },\n {\n \"resourceType\":\"Practitioner\",\n \"id\": \"p2\"\n }\n ],\n \"status\": \"final\",\n \"subject\": {\"reference\": \"#p1\"},\n \"performer\": [{\"reference\": \"#p2\"}]\n }\n\nThe `[INLINE_RESOURCE_ID]` must exist as a contained resource inside the\nresource, otherwise the server rejects the request. The contained resource can\nonly be referenced by its container or other contained resources inside the same\ncontainer."]]
