사용 여부를 결정할 때는 fhirStores.import 메서드의 다음 속성을 고려하세요. 애플리케이션에 fhirStores.import가 적합하지 않은 경우 fhir.executeBundle 메서드를 사용하여 데이터를 로드해 보세요. fhir.executeBundle 호출 방법은 FHIR 번들을 사용하여 FHIR 리소스 관리를 참조하세요.
fhirStores.import 메서드는 fhir.executeBundle의 50MB 제한보다 큰 번들을 허용합니다.
하지만 번들 내 각 개별 리소스의 크기는 10MB로 제한됩니다.
fhirStores.import를 사용하면 다음과 같이 대규모 FHIR 번들을 실행하는 복잡성이 없습니다.
FHIR 번들을 작은 번들로 분할
여러 번들 일정 관리
리소스 또는 번들 수준에서 재시도할 수 있는 일시적인 오류 관리
이러한 이점이 번들 사용 이점보다 큰 경우가 많습니다.
입력의 각 리소스에는 클라이언트 제공 ID가 포함되어야 합니다. 각 리소스는 FHIR 저장소의 enableUpdateCreate 설정과 관계없이 제공된 ID를 사용하여 저장됩니다.
가져오기 프로세스는 FHIR 저장소의 disableReferentialIntegrity 설정에 관계없이 참조 무결성을 적용하지 않습니다. 참조 무결성을 적용하지 않으면 그룹화 또는 정렬을 고려하지 않고 임의의 상호 의존성으로 리소스를 가져올 수 있습니다. 입력 데이터에 잘못된 참조가 있거나 일부 리소스를 가져오지 못한 경우 FHIR 저장소의 상태가 참조 무결성을 위반할 수 있습니다.
지정된 ID를 가진 리소스가 이미 저장소에 있는 경우 새 버전의 리소스를 만들지 않고 리소스의 최신 버전을 덮어씁니다. FHIR 저장소의 disableResourceVersioning 설정에 관계없이 덮어쓰기가 수행됩니다. 가져오기 중에 일시적인 오류가 발생하면 성공적으로 가져온 리소스를 두 번 이상 덮어쓸 수 있습니다.
가져오기 작업은 입력 데이터에 ID가 같지만 콘텐츠가 다른 여러 유효한 리소스가 포함되지 않는 한 멱등성을 갖습니다. 이 경우 가져오기가 완료된 후에는 저장소에 각 ID와 정확히 하나의 리소스가 포함되지만 중복 항목에는 모든 버전의 콘텐츠가 포함될 수 있습니다. 예를 들어 ID가 동일한 백만 개의 리소스를 가져오면 하나의 리소스만 저장소에 작성됩니다.
작업 결과 카운터는 중복 ID를 오류로 간주하지 않습니다. 입력에 있는 각 리소스는 성공 1회로 계산됩니다. 이로 인해 성공 횟수가 FHIR 저장소의 리소스 수보다 클 수 있습니다. 이는 주로 Patient-everything에 의해 생성된 번들에 구성된 데이터를 가져올 때 발생합니다. 여기서 각 번들에는 Practitioner와 같이 다수의 환자 리소스가 참조할 수 있는 자체 리소스 사본이 포함되어 있습니다.
파싱 오류로 인해 일부 리소스를 가져오지 못하면 성공적으로 가져온 리소스가 롤백되지 않습니다. 예를 들어 리소스 100개 중 5개를 가져오지 못하면 나머지 95개 리소스를 FHIR 저장소로 가져옵니다.
BUNDLE 형식을 사용할 때 가져오기 메서드는 Bundle.type이 history인 번들을 거부합니다. 가져오기 메서드는 배치 또는 트랜잭션 번들에 번들 처리 시맨틱스를 적용하지 않습니다.
fhir.executeBundle과 달리 트랜잭션 번들은 단일 트랜잭션으로 실행되지 않으며 번들 내부 참조는 다시 작성되지 않습니다. 번들은 Bundle.entry.request를 무시하고 Bundle.entry.resource에 제공된 대로 작성되는 리소스 모음으로 취급됩니다. 예를 들어 FHIR 검색 또는 Patient-everything 작업으로 생성된 searchset 번들을 가져올 수 있습니다.
FHIR 리소스 저장을 위해 사용 여부를 결정할 때는 fhir.executeBundle 메서드 사용에 대한 다음 특성과 이점을 고려하세요.
청구 비용 또는 네트워크 대역폭 측면에서 Cloud Storage에 데이터를 저장하는 파이프라인을 빌드하는 비용이 너무 높으면 fhirStores.import를 사용해서 데이터를 가져오고 fhir.executeBundle을 사용합니다.
번들을 실행할 때 트랜잭션 무결성을 적용할 수 있습니다.
번들을 실행할 때 FHIR 프로필 검증을 적용할 수 있습니다.
FHIR에서 만들기, 업데이트, 삭제 작업이 수행될 때 Pub/Sub 알림을 전송해야 하는 경우 fhir.executeBundle을 사용합니다.
fhirStores.import를 사용해서 FHIR 리소스를 가져올 때는 Pub/Sub 알림이 전송되지 않습니다.
특정 FHIR 리소스를 처리해야 하는 시간이 초 또는 분 단위이면 fhir.executeBundle를 사용합니다. 특정 FHIR 리소스를 처리해야 하는 시간이 시간 또는 일 단위이면 fhirStores.import를 사용합니다.
프로젝트에 다른 태스크를 실행하는 기존의 장기 실행 작업 (LRO)이 많으면 fhirStores.import보다 fhir.executeBundle에서 성능이 더 높을 수 있습니다. Google Cloud
fhirStores.import 작업을 관리하는 애플리케이션에 다음에 대한 적합한 전략이 없으면 fhir.executeBundle을 사용합니다.
일괄 오류 처리
FHIR 리소스의 하위 집합 또는 전체 배치의 오류 해결
FHIR 번들을 사용하지 않아야 하는 경우
FHIR 리소스 저장을 위해 사용 여부를 결정할 때는 fhir.executeBundle의 다음 제한 사항을 고려하세요.
번들에는 번들 외부에서 작업이 실행된 것처럼 번들 내분의 작업에 동일한 할당량 및 청구가 적용됩니다. 예를 들어 번들에 10개의 POST 작업, 5개의 GET 작업, 1개의 DELETE 작업이 포함된 경우, 이러한 작업이 독립적으로 실행된 것처럼 번들에 적용되는 할당량 및 청구가 동일합니다.
따라서 할당량 제한과 FHIR 작업 비용 낮추기는 fhirStores.import 대신 번들을 사용하는 이유가 되지 않습니다.
[[["이해하기 쉬움","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-05(UTC)"],[[["\u003cp\u003eThis page outlines two primary methods for storing large amounts of FHIR data in the Cloud Healthcare API: using \u003ccode\u003efhirStores.import\u003c/code\u003e or \u003ccode\u003efhir.executeBundle\u003c/code\u003e.\u003c/p\u003e\n"],["\u003cp\u003eThe \u003ccode\u003efhirStores.import\u003c/code\u003e method is ideal for loading data from Cloud Storage into an empty FHIR store, accepting bundles larger than 50MB but with individual resource size limits of 10MB.\u003c/p\u003e\n"],["\u003cp\u003eUsing \u003ccode\u003efhirStores.import\u003c/code\u003e simplifies managing large FHIR data sets by removing the need to break down bundles, manage schedules, and handle transient errors, however, it does not enforce referential integrity or resource versioning.\u003c/p\u003e\n"],["\u003cp\u003eThe \u003ccode\u003efhir.executeBundle\u003c/code\u003e method is best when real-time processing of resources is necessary, such as when Pub/Sub notifications or FHIR profile validation is needed, and is preferable for applications with many long-running operations.\u003c/p\u003e\n"],["\u003cp\u003e\u003ccode\u003efhir.executeBundle\u003c/code\u003e provides transactional integrity, but batch bundles lack transactional consistency, and large bundles may have data contention, impacting data throughput.\u003c/p\u003e\n"]]],[],null,["# FHIR import options\n\nThis page describes options for storing large batches of FHIR data in the\nCloud Healthcare API.\n| **Tip:** If you're importing data from an external bulk FHIR server, consider using the Google open source [Bulk FHIR Tools](https://github.com/google/bulk_fhir_tools) to load data directly into the Cloud Healthcare API.\n\nImport FHIR resources\n---------------------\n\nUse the\n[`fhirStores.import`](/healthcare-api/docs/reference/rest/v1/projects.locations.datasets.fhirStores/import)\nmethod to load FHIR resources from Cloud Storage into the Cloud Healthcare API.\nThe method performs best when loading data into an empty FHIR store without interference\nfrom other applications.\n\nTo call `fhirStores.import`, see\n[Importing and exporting FHIR resources using Cloud Storage](/healthcare-api/docs/how-tos/fhir-import-export).\n\nConsider the following properties of `fhirStores.import`\nmethod when deciding whether to use it. If `fhirStores.import` isn't suitable\nfor your application, consider using the\n[`fhir.executeBundle`](/healthcare-api/docs/reference/rest/v1/projects.locations.datasets.fhirStores.fhir/executeBundle)\nmethod to load data. For information about how to call `fhir.executeBundle`, see\n[Managing FHIR resources using FHIR bundles](/healthcare-api/docs/how-tos/fhir-bundles).\n\n- The `fhirStores.import` method accepts bundles larger than the [50 MB limit](/healthcare-api/quotas#resource_limits) on `fhir.executeBundle`. However, the size of each individual resource within the bundle is limited to [10 MB](/healthcare-api/quotas#resource_limits).\n- Using `fhirStores.import` removes the complexities of executing\n large FHIR bundles, such as the following:\n\n - Breaking up FHIR bundles into smaller bundles\n - Managing multiple bundle schedules\n - Managing transient errors that can be retried at the resource or bundle level\n\n Often, these advantages outweigh the advantages from using bundles.\n- Each resource in the input must contain a client-supplied ID. Each resource is\n stored using the provided ID regardless of the\n [`enableUpdateCreate`](/healthcare-api/docs/reference/rest/v1/projects.locations.datasets.fhirStores#FhirStore.FIELDS.enable_update_create)\n setting on the FHIR store.\n\n- The import process doesn't enforce referential integrity, regardless of the\n [`disableReferentialIntegrity`](/healthcare-api/docs/reference/rest/v1/projects.locations.datasets.fhirStores#FhirStore.FIELDS.disable_referential_integrity)\n setting on the FHIR store. Not enforcing referential integrity lets you\n import resources with arbitrary interdependencies without considering grouping\n or ordering. If the input data contains invalid references or if some\n resources fail to import, the state of the FHIR store might violate\n referential integrity.\n\n- If a resource with a given ID already exists in the store, the most recent\n version of the resource is overwritten without creating a new historical\n version. The overwriting occurs regardless of the\n [`disableResourceVersioning`](/healthcare-api/docs/reference/rest/v1/projects.locations.datasets.fhirStores#FhirStore.FIELDS.disable_resource_versioning)\n setting on the FHIR store. If transient failures occur during the import, a\n successfully imported resource could be overwritten more than once.\n\n- The import operation is idempotent unless the input data contains multiple\n valid resources with the same ID but different contents. In that case, after\n the import completes, the store contains exactly one resource with each ID,\n but the duplicate entries could contain any version of the contents. For\n example, importing a million resources with the same ID writes only one\n resource to the store.\n\n- The operation result counters don't count duplicate IDs as an error. Each\n resource in the input counts as one success. This could result\n in a success count larger than the number of resources in the FHIR store. This\n often occurs when importing data organized in bundles produced by\n `Patient-everything` where each bundle contains its own copy of a resource,\n such as `Practitioner`, that might be referenced by many Patient resources.\n\n- If some resources fail to import, such as due to parsing errors,\n successfully imported resources aren't rolled back. For example, if 5 of 100\n resources fail to import, the remaining 95 resources are imported into the\n FHIR store.\n\n- When using the `BUNDLE` format, the import method rejects bundles with\n `Bundle.type` of `history`. The import method doesn't apply the bundle\n processing semantics for batch or transaction bundles.\n Unlike in `fhir.executeBundle`, transaction bundles aren't executed as a\n single transaction and bundle-internal references aren't rewritten. The\n bundle is treated as a collection of resources to be written as provided in\n `Bundle.entry.resource`, ignoring `Bundle.entry.request`. For example, this\n allows the import of searchset bundles produced by a FHIR search or\n `Patient-everything` operation.\n\nUse FHIR bundles\n----------------\n\nSee [FHIR bundles](/healthcare-api/docs/how-tos/fhir-bundles#fhir_bundles) for\nan overview of FHIR bundles.\n\n### When to use FHIR bundles\n\nConsider the following characteristics and advantages of using the `fhir.executeBundle`\nmethod when deciding whether to use it to store FHIR resources:\n\n- If it is too costly, either in terms of billing costs or network bandwidth, to build a pipeline that stores data in Cloud Storage and then imports the data using `fhirStores.import`, use `fhir.executeBundle`.\n- When executing bundles, transaction integrity can be enforced.\n- When executing bundles, FHIR profile validation can be enforced.\n- If you need to send [Pub/Sub notifications](/healthcare-api/docs/how-tos/pubsub) when FHIR create, update, or delete operations occur, use `fhir.executeBundle`. Pub/Sub notifications are not sent when FHIR resources are imported using `fhirStores.import`.\n- If the time at which a particular FHIR resource must be processed is in in seconds or minutes, use `fhir.executeBundle`. If the time at which a particular FHIR resource must be processed is in hours or days, use `fhirStores.import`.\n- If your Google Cloud project has many existing long-running operations (LRO) performing other tasks, you might see better performance with `fhir.executeBundle` over `fhirStores.import`.\n- If the application managing the `fhirStores.import` operation doesn't\n have a good strategy for the following, use `fhir.executeBundle`:\n\n - Handling bulk errors\n - Addressing failures on a subset of FHIR resources or entire batches\n\n### When not to use FHIR bundles\n\nConsider the following limitations of `fhir.executeBundle` when determining\nwhether to use it to store FHIR resources:\n\n- Bundles have the equivalent quota and billing applied to the operations inside\n the bundle as if the operations were executed outside of the bundle. For example,\n if a bundle has 10 `POST` operations, 5 `GET` operations, and 1 `DELETE` operation,\n the quota and billing applied to the bundle is the same as if those operations\n were executed independently.\n\n As a result, aiming to lower quota limits and FHIR operation costs are not reasons to use\n bundles instead of `fhirStores.import`.\n- Large transaction bundles might be more likely to have transaction conflicts\n which leads to data contention and failed operations. For information on\n how these issues can occur, and how to resolve them, see [Prevent `429 Resource Exhausted operation_too_costly` errors](/healthcare-api/docs/best-practices-data-throughput#prevent-429).\n\n- You can achieve and maintain high data throughput using batch bundles, which\n helps you to avoid data contention. However, batch bundles do not\n have transactional consistency\n capabilities, such as [referential integrity](/healthcare-api/docs/concepts/fhir-referential-integrity)\n\n- If a bundle is large, even if it's a batch bundle, you might see reduced\n data throughput. For more information, see [Avoid large transaction bundles](/healthcare-api/docs/best-practices-data-throughput#avoid-large)."]]
