[[["易于理解","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-09-05。"],[[["\u003cp\u003eThis document details the integration of third-party medical imaging viewers with the Cloud Healthcare API, including authentication, authorization, and DICOMweb access.\u003c/p\u003e\n"],["\u003cp\u003eMedical viewers can authenticate with the Cloud Healthcare API either through the Google Identity Services OAuth 2.0 flow, or using a service account, each with distinct benefits and complexities.\u003c/p\u003e\n"],["\u003cp\u003eUsers require specific roles, such as \u003ccode\u003eroles/healthcare.dicomViewer\u003c/code\u003e and \u003ccode\u003eroles/healthcare.dicomEditor\u003c/code\u003e, to properly interact with DICOM resources in the viewer.\u003c/p\u003e\n"],["\u003cp\u003eThe viewer accesses DICOM data via DICOMweb endpoints, utilizing the Search Transaction to display studies and the Retrieve Transaction to access raw pixel bytes and DICOM metadata.\u003c/p\u003e\n"],["\u003cp\u003eTo maximize performance when downloading multiple instances, such as in a CT scan, it is advised to fetch instances in parallel, using a high number of concurrent requests.\u003c/p\u003e\n"]]],[],null,["# Integrating with a DICOM medical viewer\n\nThis page explains concepts and best practices for integrating a third-party medical imaging viewer\nwith the Cloud Healthcare API. The Cloud Healthcare API is integrated with\nmultiple viewers, including the [Open Health Imaging Foundation (OHIF) viewer](https://docs.ohif.org/deployment/google-cloud-healthcare/)\nand the [Weasis viewer](https://github.com/GoogleCloudPlatform/weasis-chcapi-extension).\n\nBefore you begin\n----------------\n\nIf you haven't stored any DICOM images to use in your viewer, see\n[Store DICOM data](/healthcare-api/docs/how-tos/dicomweb#store-dicom)\nand [Importing and exporting DICOM data using Cloud Storage](/healthcare-api/docs/how-tos/dicom-import-export)\nto get started.\n\nAuthorizing and authenticating requests using OAuth 2.0\n-------------------------------------------------------\n\nGoogle Cloud APIs support the [OAuth 2.0 protocol](https://developers.google.com/identity/protocols/OAuth2)\nfor both authentication and authorization.\n\nA medical viewer needs to handle authentication and authorization to access DICOM data stored in\nthe Cloud Healthcare API. You can grant these permissions in two ways.\nEach method has its own costs and benefits:\n\n**[Using Google Identity Services OAuth 2.0 flow](#authorizing_using_google_sign-in_oauth_20_flow)**\n\n- End users authenticate themselves through the medical viewer to the Cloud Healthcare API.\n- The medical viewer accesses the Cloud Healthcare API on behalf of the end user.\n- Permissions are managed at the level of the user and the user's actions are logged to [Cloud Audit Logs](/healthcare-api/docs/how-tos/audit-logging) with the user's unique identifier.\n- Using the Google Identity Services flow is more complex than using a [service account](#authorizing_using_a_service_account). For example, your application needs to handle callbacks to store the authorization token, which can add unnecessary complexity to a simple application.\n\n**[Using a service account](#authorizing_using_a_service_account)**\n\n- You configure the medical viewer to use its own method of authorization and access control to determine whether an end user can view a given Cloud Healthcare API resource. Using a service account is helpful if you already have a viewer that performs its own user management and authentication checks.\n- Actions performed in the viewer are logged to [Cloud Audit Logs](/healthcare-api/docs/how-tos/audit-logging), but you cannot see logs at the level of individual end users.\n- Authentication using a service account is simpler than using the Google Identity Services flow. For example, there is no need to prompt a user to log in, and therefore there is no need to store an access token.\n\n### Authorizing using Google Identity Services OAuth 2.0 flow\n\nYou can authorize a medical viewer to access DICOM data stored in the Cloud Healthcare API\non a user's behalf by using the [Google Identity Services OAuth 2.0 flow](https://developers.google.com/identity/oauth2/web/guides/overview).\nDepending on your application, there are flows available for the following applications:\n\n- [Web server applications](https://developers.google.com/identity/protocols/OAuth2WebServer)\n- [Mobile and desktop applications](https://developers.google.com/identity/protocols/OAuth2InstalledApp)\n- [JavaScript web applications](https://developers.google.com/identity/oauth2/web/guides/use-token-model)\n\nThe following description for the sign-in flow assumes that the user\naccessing the viewer has [created a DICOM store](/healthcare-api/docs/how-tos/dicom)\nand [stored DICOM instances in the store](/healthcare-api/docs/how-tos/dicomweb#store-dicom):\n\n1. A user opens your medical viewer application. The viewer displays a consent window from Google that shows the name of your application and the Google API services that it is requesting permission to access with the user's authorization credentials. The user can then consent or refuse to grant access to your application.\n2. The user is sent to a Google Identity Services page. If the user grants your application the requested access, then your application gains permission to access the user's data.\n\nDo not store refresh tokens in the viewer. The access tokens granted to the\nviewer by the user should be short-lived and only exchanged when the tokens\nexpire.\n\nRefresh tokens are also unnecessary for the following reasons:\n\n- The user is always present when using the viewer.\n- Using refresh tokens requires extra work to store the token securely.\n\n| **Note:** When configuring the viewer's scopes, the sign-in request should only need to contain the https://www.googleapis.com/auth/cloud-healthcare scope.\n\n### Authorizing using a service account\n\nYou can manage authentication and authorization at the level of the medical viewer,\nrather than at the level of an end user, by using OAuth 2.0 with a [service account](https://developers.google.com/identity/protocols/OAuth2ServiceAccount).\n\nFor instructions on how to use a service account to authenticate a medical viewer to the\nCloud Healthcare API, see [Authenticating to the API](/healthcare-api/docs/how-tos/authentication).\n\n### Required roles\n\nFor the viewer to function properly, a user must have the following\n[roles](/healthcare-api/docs/access-control#roles):\n\n- `roles/healthcare.dicomViewer`: for viewing DICOM resources\n- `roles/healthcare.dicomEditor`: for viewing, editing, and creating DICOM resources\n\nIn the sign-in flow, it is expected that the user has already configured these roles, and the\nviewer does not need to do anything else. When using a service account,\nthe roles must be set in the service account. The viewer should return\nappropriate `PERMISSION_DENIED` errors to users who do not have the\nrequired permissions for accessing their DICOM stores.\n\nAccessing DICOMweb endpoints\n----------------------------\n\nAfter the user authenticates to the viewer, the viewer can make requests to DICOMweb endpoints.\nEach DICOM store exposes a single DICOMweb endpoint.\n\nWhen the user is in the viewer, they must specify which projects and DICOM\nstores they want to access. The simplest process is to ask the user\nto provide the IDs for the project, dataset, and DICOM store they want to\naccess. However, providing each individual value might take the user a long time.\n\nAs an alternative, you can provide a combination of user input and\nauto-completion in the viewer. For example, you might have the user enter a\nproject ID, and then the viewer would automatically populate a list of\nthe datasets and DICOM stores within that project. Or, you could provide a\nsingle input field that automatically populates the projects, datasets,\nand DICOM stores that the user has access to. The following API methods might\nbe helpful when setting up either of these alternatives:\n\n- [`projects.list`](/resource-manager/reference/rest/v1/projects/list): Lists projects that are visible to the user and that satisfy a specified filter.\n- [`projects.locations.list`](/healthcare-api/docs/reference/rest/v1/projects.locations/list): Lists information about the supported locations for the Cloud Healthcare API.\n- [`projects.locations.datasets.list`](/healthcare-api/docs/reference/rest/v1/projects.locations.datasets/list): Lists the Cloud Healthcare API datasets in a project.\n- [`projects.locations.datasets.dicomStores.list`](/healthcare-api/docs/reference/rest/v1/projects.locations.datasets.dicomStores/list): Lists the DICOM stores in a dataset.\n\nYou might also consider pre-populating a list of a user's resources. However, if a\nuser has hundreds or thousands of DICOM stores or datasets, pre-populating and\ndisplaying the list might be infeasible.\n\nAccessing resources in the viewer using DICOMweb\n------------------------------------------------\n\nThe Cloud Healthcare API supports the [DICOMweb standard](/healthcare-api/docs/how-tos/dicomweb).\nTo let users access their data, the viewer must implement the DICOMweb\nRESTful HTTP methods instead of the legacy [DIMSE](http://dicom.nema.org/dicom/2013/output/chtml/part07/sect_3.10.html) protocols.\n\nThere are two main components to any viewer:\n\n- The worklist provider\n- The image viewer\n\nYou can use the DICOMweb standard with both components.\n\n### Viewing the worklist provider\n\nTypically, the first thing a user sees when they open a viewer is a list of all\navailable studies in each DICOM store. The viewer can retrieve these studies\nusing the [Search Transaction](http://dicom.nema.org/medical/dicom/current/output/html/part18.html#sect_10.6).\n\nSee the Cloud Healthcare API [DICOM conformance statement](/healthcare-api/docs/dicom#search_transaction)\nfor specifics on how the Search Transaction is implemented in the Cloud Healthcare API.\n\n### Viewing instances\n\nAfter the user is in the worklist provider, they will typically select a\nstudy for viewing. To render the study, the viewer must access the study's raw\npixel bytes and the DICOM metadata. The viewer can retrieve this\ninformation using the [Retrieve Transaction](https://dicom.nema.org/medical/dicom/current/output/html/part18.html#sect_10.4)\nset of methods. The Retrieve Transaction methods let you retrieve an entire raw\nDICOM file or the file's raw pixel data. The Retrieve Transaction methods also support transcoding\nbetween different transfer syntaxes.\n\nSee the Cloud Healthcare API [DICOM conformance statement](/healthcare-api/docs/dicom#search_transaction)\nfor specifics on how the Search and Retrieve Transaction methods are implemented in the Cloud Healthcare API.\n| To minimize latency, use `transfer-syntax=*` in the Accept request HTTP header. Doing so avoids transcoding on the server side.\n\n### Maximizing network throughput\n\nSometimes, such as when rendering a CT scan, a viewer might need to\ndownload many instances at once to render the image. For best results, fetch\neach instance in parallel using a high number of concurrent requests (such as\n50 or more). The exact number depends on your application and network\nbandwidth."]]
