Updated IAM policy for project [PROJECT_ID].
bindings:
...
- members:
- serviceAccount:service-PROJECT_NUMBER@gcp-sa-healthcare.iam.gserviceaccount.com
role: roles/healthcare.serviceAgent
...
etag: VALUE
version: VALUE
執行交易套件時，可建立的鎖定爭用量沒有限制。舉例來說，如果您建構一組套裝組合，其中每個套裝組合都會更新單一常見的病患資源，並建立一些其他非常見資源，然後平行執行這些套裝組合，則由於每個套裝組合都必須在整個交易期間保留該常見病患的鎖定，因此所需時間會迅速增加。因此會開始逾時。當 Cloud Healthcare API 偵測到交易套件逾時時，會暫時拒絕所有交易套件，並顯示這則錯誤訊息，嘗試清除爭用情形。
[[["容易理解","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 (世界標準時間)。"],[[["\u003cp\u003eThis guide covers troubleshooting common issues encountered when using the Cloud Healthcare API, including permissions errors during API enablement and authentication problems.\u003c/p\u003e\n"],["\u003cp\u003eThe Cloud Healthcare Service Agent service account is essential for API functionality, and steps are provided to resolve issues if it's missing or lacks the required Healthcare Service Agent role.\u003c/p\u003e\n"],["\u003cp\u003eInstructions are included to add the \u003ccode\u003ehealthcare.serviceAgent\u003c/code\u003e role to the Cloud Healthcare Service Agent account using the Google Cloud CLI, if this is necessary.\u003c/p\u003e\n"],["\u003cp\u003eIf FHIR transactional bundles fail due to heavy load, suggestions include using batch bundles, reducing parallel updates on common resources, or implementing client-side rate limiting.\u003c/p\u003e\n"]]],[],null,["# Troubleshooting\n\nLearn about troubleshooting steps that you might find helpful\nif you run into problems using the Cloud Healthcare API.\n\nCannot enable the Cloud Healthcare API\n--------------------------------------\n\nWhen enabling the Cloud Healthcare API for the first time in your\nGoogle Cloud project, you might encounter a permissions error indicating\nthat you don't have permission to enable Google Cloud\nAPIs for your project.\n\nSee [Enabling and disabling APIs](/apis/docs/enable-disable-apis) for information\non how to enable Google Cloud APIs, including the Cloud Healthcare API.\n\nCannot authenticate to the Cloud Healthcare API\n-----------------------------------------------\n\nWhen calling the Cloud Healthcare API, you might receive an error message\nindicating that your \"Application Default Credentials\" are unavailable.\n\nSee [Authenticating to the API](/healthcare-api/docs/how-tos/authentication) for\ninformation on how to configure Application Default Credentials or how to\npass in authentication credentials manually to an application or command.\n\nMissing the Cloud Healthcare API service account or Healthcare Service Agent role\n---------------------------------------------------------------------------------\n\nThe **Cloud Healthcare Service Agent** service account is automatically created\nwhen you enable the Cloud Healthcare API and [create your first dataset](/healthcare-api/docs/datasets). This is a [Google-managed service account](/iam/docs/service-account-types#google-managed_service_accounts).\nYou cannot delete the service account entirely, but under certain circumstances\nit might not appear in the [Identity and Access Management page](https://console.cloud.google.com/iam-admin/iam)\nand you might encounter issues with the Cloud Healthcare API.\n\nFor the Cloud Healthcare API to function correctly and complete tasks like\npublishing and receiving messages from Pub/Sub or writing metrics to\nCloud Logging, the **Cloud Healthcare Service Agent** service account must\nexist and must have the **Healthcare Service Agent** IAM\nrole.\n\nYou can recreate the **Cloud Healthcare Service Agent** service account or\ngrant it the **Healthcare Service Agent** IAM\nrole if you encounter any of the following issues:\n\n- You cannot find the **Cloud Healthcare Service Agent** service account in the [Identity and Access Management page](https://console.cloud.google.com/iam-admin/iam).\n- You can find the **Cloud Healthcare Service Agent** service account, but it does not contain the **Healthcare Service Agent** role.\n\nUse the [Google Cloud CLI](/sdk/gcloud/reference/projects/add-iam-policy-binding)\nto add the `healthcare.serviceAgent` role to the\n**Cloud Healthcare Service Agent** service account using the\nservice account's identifier, which uses the format\n`service-`\u003cvar translate=\"no\"\u003ePROJECT_NUMBER\u003c/var\u003e`@gcp-sa-healthcare.iam.gserviceaccount.com`.\n\nTo recreate the service account or grant it the **Healthcare Service Agent** IAM\nrole, run the [`gcloud projects add-iam-policy-binding`](/sdk/gcloud/reference/projects/add-iam-policy-binding)\ncommand. To find the \u003cvar translate=\"no\"\u003ePROJECT_ID\u003c/var\u003e and \u003cvar translate=\"no\"\u003ePROJECT_NUMBER\u003c/var\u003e,\nsee [Identifying projects](/resource-manager/docs/creating-managing-projects#identifying_projects). \n\n```bash\ngcloud projects add-iam-policy-binding PROJECT_ID \\\n --member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-healthcare.iam.gserviceaccount.com \\\n --role=roles/healthcare.serviceAgent\n```\n\nIf the request is successful, the command prompt displays a message similar to\nthe following sample: \n\n```\nUpdated IAM policy for project [PROJECT_ID].\nbindings:\n...\n- members:\n - serviceAccount:service-PROJECT_NUMBER@gcp-sa-healthcare.iam.gserviceaccount.com\n role: roles/healthcare.serviceAgent\n...\netag: VALUE\nversion: VALUE\n```\n\nReturn to the [Identity and Access Management page](https://console.cloud.google.com/iam-admin/iam)\nagain and verify the following:\n\n- The **Member** column contains a service account identifier in the format `service-`\u003cvar translate=\"no\"\u003ePROJECT_NUMBER\u003c/var\u003e`@gcp-sa-healthcare.iam.gserviceaccount`.\n- In the same row as the **Member** column, the **Name** column contains **Cloud Healthcare Service Agent**.\n- In the same row as the **Member** column, the **Role** column contains **Healthcare Service Agent**.\n\nFHIR transactional bundle aborted due to cumulative heavy load\n--------------------------------------------------------------\n\nWhen executing a FHIR transactional bundle, you might receive an error message\nindicating that the request is \"aborted due to cumulative heavy load for\nexecuting transactional bundle\".\n\nWhen you execute transactional bundles there is no bound on how much\nlock contention you can create. For example, if you construct a set of bundles\nwhere each bundle updates a single common Patient resource and also creates some\nother resources that are not common, and execute these in parallel, the time\nthey take will rapidly increase as every bundle has to hold the lock on that\ncommon Patient for the entire transaction. As a result, they will start to\ntime out. When the Cloud Healthcare API detects transactional bundles\ntiming out, it temporarily rejects all transactional bundles with this\nerror message to try to let the contention clear up.\n\nTo avoid this issue, you can try one of the following:\n\n- Use batch bundles if you do not need transaction semantics. Batch bundles avoid this problem entirely because they are not atomic. However, this reduces referential integrity enforcement.\n- If you can identify what resource is being updated in parallel, determine if those updates can be factored out or avoided. In FHIR, this happens if you are creating a new resource such as Observation and also updating the associated Patient (or Organization, Location, Device, etc.) that already exists and isn't changing.\n- Rate limiting on the client side; if your transactional bundles are taking a long time to execute, reduce the ingestion rate before the requests start timing out."]]
