이 페이지에서는 Cloud Healthcare API가 FHIR 리소스 참조를 지원하는 방법을 설명합니다.
개요
FHIR 리소스 참조는 소스 리소스에서 대상 리소스로의 방향 연결입니다. FHIR 리소스 참조를 사용하여 리소스를 연결할 수 있습니다. 예를 들어 FHIR 리소스 유형 Observation에는 참조 유형의 subject 필드가 있으며 관찰 대상으로 Patient 리소스에 연결하는 데 사용할 수 있습니다.
FHIR 리소스 참조도 순환될 수 있습니다. 예를 들어 FHIR 리소스 유형 CarePlan에는 다른 CarePlan을 가리킬 수 있는 replaces 필드가 있습니다.
FHIR 참조 구조의 가장 중요한 요소는 참조입니다.
display 및 identifier과 같은 다른 요소는 Cloud Healthcare API에 있는 것처럼 유지됩니다.
Cloud Healthcare API에서 지원되는 Reference.reference 형식은 다음과 같습니다.
리소스 참조는 RESOURCE_TYPE/RESOURCE_ID로 정의됩니다.
또한 Cloud Healthcare API는 전체 FHIR 저장소 이름을 RESOURCE_TYPE/RESOURCE_ID 앞에 추가하는 것을 지원합니다. 예를 들면 FHIR_STORE_NAME/RESOURCE_TYPE/RESOURCE_ID입니다.
이 형식을 사용하는 경우 매장 이름은 요청의 FHIR 저장소와 일치해야 합니다.
그렇지 않은 경우 로컬이 아닌 참조로 인해 요청이 거부됩니다.
Cloud Healthcare API는 대상 리소스의 특정 버전에 대한 참조를 지원합니다. 대상 리소스의 특정 버전으로 연결하려면 로컬 참조에서 RESOURCE_ID/_history/VERSION_ID] 형식을 사용합니다.
참조 무결성 검사가 사용 설정되면 서버는 FHIR 저장소에 이전 버전이 있는지 확인합니다. Resource-purge 메서드는 참조 여부와 상관없이 이전 버전을 삭제합니다.
조건부 참조
대상 리소스 ID를 명시적으로 지정하는 대신 executeBundle은 요청 시 대상 리소스 ID로 확인되는 대상 리소스의 조건부 참조 검색어를 허용합니다. 예를 들면 Patient?identifier=abc입니다.
검색어가 대상 리소스로 확인되지 않거나 두 개 이상의 대상 리소스로 확인되는 경우 참조 무결성 검사가 사용 설정되었는지 여부와 관계없이 서버가 요청을 거부합니다.
urn:uuid 또는 urn:oid로 시작하는 URI
트랜잭션 번들과 함께 executeBundle 메서드를 사용하는 경우 범용 고유 식별자(UUID) 또는 객체 식별자(OID) 참조를 사용하여 동일한 번들에서 생성되거나 업데이트되는 다른 리소스에 대한 참조를 확인할 수 있습니다. 자세한 내용은 FHIR 번들 관리 가이드를 참조하세요.
전체 외부 URL
http://www.example.com/abc와 같은 전체 외부 URL은 참조 필드에 수정되지 않은 상태로 저장됩니다. Cloud Healthcare API는 URL을 확인하지 않거나 유효성 검사를 시도하지 않습니다.
전체 외부 URL이 요청의 FHIR 저장소 전체 URL과 일치하면 참조는 로컬 리소스 참조로 간주됩니다.
프래그먼트 참조
프래그먼트 참조는 리소스에서 인라인 처리된 포함된 리소스를 가리킵니다. 예를 들어 관찰 레코드에 일반 실무자가 언급되지만 관리된 실무자 디렉터리가 없는 경우 전체 실무자 리소스를 만들 수 없습니다. 일반 실무자는 관찰 레코드에 포함된 리소스입니다. 리소스의 참조 필드는 #[INLINE_RESOURCE_ID] 형식을 사용하는 인라인 처리된 리소스를 가리킬 수 있습니다.
다음 FHIR R4 샘플에서 p1 및 p2는 #p1 및 #p2로 참조되는 인라인 리소스 ID입니다.
[[["이해하기 쉬움","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(UTC)"],[[["\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."]]
