首次在Google Cloud 项目中启用 Cloud Healthcare API 时，您可能会遇到权限错误，指出您无权为项目启用 Google CloudAPI。
如需了解如何启用 API（包括 Cloud Healthcare API），请参阅启用和停用 API。 Google Cloud
无法向 Cloud Healthcare API 进行身份验证
调用 Cloud Healthcare API 时，您可能会收到一条错误消息，表明您的“应用默认凭据”不可用。
如需了解如何配置应用默认凭据或如何将身份验证凭据手动传递到应用或命令，请参阅向 API 进行身份验证。
缺少 Cloud Healthcare API 服务账号或 Healthcare Service Agent 角色
启用 Cloud Healthcare API 并创建您的第一个数据集后，系统会自动创建 Cloud Healthcare Service Agent 服务账号。这是 Google 管理的服务账号。您无法完全删除该服务账号，但在某些情况下，该服务账号可能不会显示在“身份和访问权限管理”页面中，且您可能会遇到 Cloud Healthcare API 问题。
为使 Cloud Healthcare API 正常运行并完成从 Pub/Sub 发布和接收消息或向 Cloud Logging 写入指标等任务，Cloud Healthcare Service Agent 服务账号必须存在，且必须具有 Healthcare Service Agent IAM 角色。
如果遇到以下任何问题，您可以重新创建 Cloud Healthcare Service Agent 服务账号或向其授予 Healthcare Service Agent IAM 角色：
您无法在身份和访问权限管理页面中找到 Cloud Healthcare Service Agent 服务账号。
可以找到 Cloud Healthcare Service Agent 服务账号，但它不具有包含 Healthcare Service Agent 角色。
使用 Google Cloud CLI 和 Cloud Healthcare Service Agent 服务账号的标识符（格式为 service-PROJECT_NUMBER@gcp-sa-healthcare.iam.gserviceaccount.com），将 healthcare.serviceAgent 角色添加到该服务账号。
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"]],["最后更新时间 (UTC)：2025-08-14。"],[[["\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."]]
