Esistono due tipi di intestazioni HTTP personalizzate che puoi specificare nelle richieste dell'API Cloud Healthcare
e visualizzare nei log di controllo. Puoi utilizzare ogni tipo esclusivamente o combinarli.
Registrazione dell'ID personalizzato. Puoi specificare l'intestazione HTTP personalizzata X-Request-Id
per assegnare a ogni richiesta un ID personalizzato e poi cercare nei log di controllo
una richiesta contenente l'ID. Per fornire un ID personalizzato, specifica l'intestazione
HTTP personalizzata nel seguente formato:
X-Request-Id: REQUEST_ID
Specifica un valore univoco per REQUEST_ID in ogni richiesta.
La maggior parte dei linguaggi di programmazione consente di generare ID casuali che puoi utilizzare per creare l'ID richiesta. Ad esempio, il modulo Python
uuid ha
una funzione uuid.uuid4()
che puoi utilizzare per generare automaticamente ID per ogni richiesta.
L'API Cloud Healthcare non genera ID richiesta.
Registrazione dei metadati. Puoi includere informazioni aggiuntive sui metadati nelle intestazioni HTTP personalizzate utilizzando l'intestazione X-Goog-Healthcare-Audit-IDENTIFIER. L'intestazione identifica in modo univoco il tipo di informazioni sui metadati.
I metadati vengono archiviati nel log di controllo per ogni richiesta. Per
fornire informazioni sui metadati, specifica una o più intestazioni HTTP personalizzate nel
seguente formato:
X-Goog-Healthcare-Audit-IDENTIFIER: VALUE
Sostituisci IDENTIFIER con un identificatore leggibile.
Sostituisci VALUE con un valore per i metadati.
Puoi specificare più valori in un elenco separato da virgole utilizzando la seguente sintassi:
L'esempio seguente mostra uno scenario in cui specifichi intestazioni HTTP personalizzate in una richiesta fhir.create.
Supponiamo che tu stia conducendo uno studio e che tu abbia un'applicazione mobile
per i pazienti chiamata PatientApp. I pazienti dello studio sono suddivisi in
due coorti: Cohort1 e Cohort2. Per identificare ogni richiesta
da Cohort1 con un ID univoco e il nome dell'applicazione mobile,
specifica le seguenti intestazioni HTTP personalizzate in ogni richiesta:
Le intestazioni HTTP personalizzate vengono visualizzate nel campo metadata del log di controllo di ogni richiesta
in Cloud Audit Logs.
L'esempio seguente mostra come utilizzare curl per creare una nuova risorsa Patient in un archivio FHIR. La richiesta contiene le seguenti intestazioni HTTP personalizzate:
X-Request-Id: 123
X-Goog-Healthcare-Audit-AppName: PatientApp
X-Goog-Healthcare-Audit-CohortName: Cohort1
Prima di inviare la richiesta, sostituisci quanto segue:
PROJECT_ID: l'ID del tuo Google Cloud progetto
LOCATION: la posizione del set di dati
DATASET_ID: il set di dati padre dell'archivio FHIR
[[["Facile da capire","easyToUnderstand","thumb-up"],["Il problema è stato risolto","solvedMyProblem","thumb-up"],["Altra","otherUp","thumb-up"]],[["Difficile da capire","hardToUnderstand","thumb-down"],["Informazioni o codice di esempio errati","incorrectInformationOrSampleCode","thumb-down"],["Mancano le informazioni o gli esempi di cui ho bisogno","missingTheInformationSamplesINeed","thumb-down"],["Problema di traduzione","translationIssue","thumb-down"],["Altra","otherDown","thumb-down"]],["Ultimo aggiornamento 2025-09-05 UTC."],[[["\u003cp\u003eThis guide outlines how to configure custom HTTP headers in requests to the Cloud Healthcare API for tracking and debugging purposes.\u003c/p\u003e\n"],["\u003cp\u003eYou can utilize either \u003ccode\u003eX-Request-Id\u003c/code\u003e for unique request identification or \u003ccode\u003eX-Goog-Healthcare-Audit-IDENTIFIER\u003c/code\u003e for additional metadata, or a combination of both, within your requests.\u003c/p\u003e\n"],["\u003cp\u003eCustom HTTP header information is viewable in Cloud Audit Logs, which is helpful for identifying who sent a request, when it was sent, and determining which request caused an error.\u003c/p\u003e\n"],["\u003cp\u003eWhile custom HTTP header data is stored in Cloud Audit Logs, it is suggested that you avoid including any protected health information (PHI) in them due to visibility constraints and retention periods, which by default are 30 days.\u003c/p\u003e\n"],["\u003cp\u003eCustom HTTP headers can be configured across various REST resources within the Cloud Healthcare API, including locations, datasets, DICOM stores, FHIR stores, and HL7v2 stores.\u003c/p\u003e\n"]]],[],null,["# Configure custom HTTP headers for audit logs\n\nThis page explains how to complete the following tasks:\n\n1. Configure custom HTTP headers in requests to the Cloud Healthcare API.\n2. Use Cloud Audit Logs to search for requests and their matching custom\n HTTP headers to do the following:\n\n - See who sent a request and when.\n - Simplify deployment and debugging by finding out which request caused a particular error.\n\n| **Caution:** As shown in [Logs retention periods](/logging/quotas#logs_retention_periods), information in custom HTTP headers is retained in Cloud Audit Logs by default for 30 days. You can modify the retention period by [configuring a custom retention period](/logging/docs/buckets#custom-retention). The minimum retention period is 7 days. Anyone who has permission to view Cloud Audit Logs logs can view the information in the custom HTTP headers. Therefore, we recommend that you don't include protected health information (PHI) in the custom HTTP headers.\n\nFor more information\non using Cloud Audit Logs in the Cloud Healthcare API, see\n[Viewing Cloud Audit Logs](/healthcare-api/docs/how-tos/audit-logging).\n\nConfigurable methods\n--------------------\n\nYou can configure custom HTTP headers for the Cloud Healthcare API methods in\nthe following REST resources:\n\n- [`projects.locations`](/healthcare-api/docs/reference/rest/v1/projects.locations#methods)\n- [`projects.locations.datasets`](/healthcare-api/docs/reference/rest/v1/projects.locations.datasets#methods)\n- [`projects.locations.dicomStores`](/healthcare-api/docs/reference/rest/v1/projects.locations.datasets.dicomStores#methods)\n- [`projects.locations.dicomStores.studies`](/healthcare-api/docs/reference/rest/v1/projects.locations.datasets.dicomStores.studies#methods)\n- [`projects.locations.dicomStores.studies.series`](/healthcare-api/docs/reference/rest/v1/projects.locations.datasets.dicomStores.studies.series#methods)\n- [`projects.locations.dicomStores.studies.series.instances`](/healthcare-api/docs/reference/rest/v1/projects.locations.datasets.dicomStores.studies.series.instances#methods)\n- [`projects.locations.dicomStores.studies.series.instances.frames`](/healthcare-api/docs/reference/rest/v1/projects.locations.datasets.dicomStores.studies.series.instances.frames#methods)\n- [`projects.locations.datasets.fhirStores`](/healthcare-api/docs/reference/rest/v1/projects.locations.datasets.fhirStores#methods)\n- [`projects.locations.datasets.fhirStores.fhir`](/healthcare-api/docs/reference/rest/v1/projects.locations.datasets.fhirStores.fhir#methods)\n- [`projects.locations.datasets.hl7V2Stores`](/healthcare-api/docs/reference/rest/v1/projects.locations.datasets.hl7V2Stores#methods)\n- [`projects.locations.datasets.hl7V2Stores.messages`](/healthcare-api/docs/reference/rest/v1/projects.locations.datasets.hl7V2Stores.messages#methods)\n- [`projects.locations.datasets.operations`](/healthcare-api/docs/reference/rest/v1/projects.locations.datasets.operations#methods)\n\nConfigure custom HTTP headers\n-----------------------------\n\n| **Caution:** Using custom HTTP headers in a web browser triggers a CORS preflight security check. The Cloud Healthcare API might not approve your custom header during this check, which will cause the browser to block your request.\n\nThere are two types of custom HTTP headers that you can specify on Cloud Healthcare API\nrequests and view in audit logs. You can use each type exclusively or combine them.\n\n- **Custom ID logging.** You can specify the `X-Request-Id` custom HTTP header\n to give each request its own custom ID, and then search through audit logs\n for a request containing the ID. To supply a custom ID, specify the custom\n HTTP header in the following format:\n\n ```none\n X-Request-Id: REQUEST_ID\n ```\n\n Specify a unique value for \u003cvar translate=\"no\"\u003eREQUEST_ID\u003c/var\u003e in each request.\n\n Most programming\n languages have a way to generate random IDs that you can use to\n create the request ID. For example, the Python\n [`uuid`](https://docs.python.org/3/library/uuid.html) module has\n a [`uuid.uuid4()`](https://docs.python.org/3/library/uuid.html#uuid.uuid4)\n function that you can use to generate IDs automatically for each request.\n The Cloud Healthcare API doesn't generate request IDs.\n- **Metadata logging.** You can include additional metadata information in custom HTTP\n headers using the `X-Goog-Healthcare-Audit-`\u003cvar translate=\"no\"\u003eIDENTIFIER\u003c/var\u003e\n header. The header uniquely identifies the type of metadata information.\n\n The metadata is stored in the audit log for each request. To\n supply metadata information, specify one or more custom HTTP headers in\n the following format: \n\n ```none\n X-Goog-Healthcare-Audit-IDENTIFIER: VALUE\n ```\n\n Replace \u003cvar translate=\"no\"\u003eIDENTIFIER\u003c/var\u003e with a human-readable identifier.\n Replace \u003cvar translate=\"no\"\u003eVALUE \u003c/var\u003e with a value for the metadata.\n You can specify multiple values in a comma-separated list using the following syntax: \n\n ```none\n X-Goog-Healthcare-Audit-IDENTIFIER: VALUE_1, VALUE_2, VALUE_n ...\n ```\n\n For example: \n\n ```none\n X-Goog-Healthcare-Audit-MyIdentifier: Value1, Value2, Value3\n ```\n\n You can also specify multiple custom HTTP headers with their own unique values: \n\n ```none\n X-Goog-Healthcare-Audit-MyIdentifier1: Value1, Value2\n X-Goog-Healthcare-Audit-MyIdentifier2: Value3\n ```\n\nView the audit logs in Cloud Audit Logs\n---------------------------------------\n\nSee [View logs](/healthcare-api/docs/how-tos/audit-logging#viewing_logs).\n\nExample\n-------\n\nThe following example demonstrates a scenario where you specify custom HTTP\nheaders in a\n[`fhir.create`](/healthcare-api/docs/reference/rest/v1/projects.locations.datasets.fhirStores.fhir/create)\nrequest.\n\nSuppose that you're running a study and you have a mobile application\nfor patients named `PatientApp`. The patients in the study are divided into\ntwo cohorts: `Cohort1` and `Cohort2`. To identify each request\nfrom `Cohort1` with a unique ID and the name of the mobile application,\nspecify the following custom HTTP headers in each request: \n\n```none\nX-Request-Id: REQUEST_ID\nX-Goog-Healthcare-Audit-AppName: PatientApp\nX-Goog-Healthcare-Audit-CohortName: Cohort1\n```\n\nThe custom HTTP headers display in the `metadata` field of each request's audit log\nin Cloud Audit Logs.\n\nThe following sample shows how to use `curl` to create a new Patient resource in a FHIR\nstore. The request contains the following custom HTTP headers:\n\n- `X-Request-Id: 123`\n- `X-Goog-Healthcare-Audit-AppName: PatientApp`\n- `X-Goog-Healthcare-Audit-CohortName: Cohort1`\n\nBefore sending the request, replace the following:\n\n- \u003cvar class=\"edit\" scope=\"PROJECT_ID\" translate=\"no\"\u003ePROJECT_ID\u003c/var\u003e: the ID of your Google Cloud project\n- \u003cvar class=\"edit\" scope=\"LOCATION\" translate=\"no\"\u003eLOCATION\u003c/var\u003e: the dataset location\n- \u003cvar class=\"edit\" scope=\"DATASET_ID\" translate=\"no\"\u003eDATASET_ID\u003c/var\u003e: the FHIR store's parent dataset\n- \u003cvar class=\"edit\" scope=\"FHIR_STORE_ID\" translate=\"no\"\u003eFHIR_STORE_ID\u003c/var\u003e: the FHIR store ID\n\n```bash\ncurl -X POST \\\n -H \"Authorization: Bearer $(gcloud auth application-default print-access-token)\" \\\n -H \"Content-Type: application/json; charset=utf-8\" \\\n -H \"X-Request-Id: 123\" \\\n -H \"X-Goog-Healthcare-Audit-AppName: PatientApp\" \\\n -H \"X-Goog-Healthcare-Audit-CohortName: Cohort1\" \\\n --data '{\n \"name\": [\n {\n \"use\": \"official\",\n \"family\": \"Smith\",\n \"given\": [\n \"Darcy\"\n ]\n }\n ],\n \"gender\": \"female\",\n \"birthDate\": \"1970-01-01\",\n \"resourceType\": \"Patient\"\n }' \"https://healthcare.googleapis.com/v1/projects/\u003cvar translate=\"no\"\u003ePROJECT_ID\u003c/var\u003e/locations/\u003cvar translate=\"no\"\u003eLOCATION\u003c/var\u003e/datasets/\u003cvar translate=\"no\"\u003eDATASET_ID\u003c/var\u003e/fhirStores/\u003cvar translate=\"no\"\u003eFHIR_STORE_ID\u003c/var\u003e/fhir/Patient\"\n```\n\nThe output is the following: \n\n```\n{\n \"birthDate\": \"1970-01-01\",\n \"gender\": \"female\",\n \"id\": \"PATIENT_ID\",\n \"meta\": {\n \"lastUpdated\": \"YYYY-MM-DDTHH:MM:SS+ZZ:ZZ\",\n \"versionId\": \"VERSION_ID\"\n },\n \"name\": [\n {\n \"family\": \"Smith\",\n \"given\": [\n \"Darcy\"\n ],\n \"use\": \"official\"\n }\n ],\n \"resourceType\": \"Patient\"\n}\n```\n\nIf you search for the request in Cloud Audit Logs, the audit log\nlooks like the following: \n\n```json\n{\n logName: \"projects/PROJECT_ID/logs/cloudaudit.googleapis.com%2Fdata_write\"\n protoPayload: {\n @type: \"type.googleapis.com/google.cloud.audit.AuditLog\"\n metadata: {\n X-Request-Id: [123]\n X-Goog-Healthcare-Audit-AppName: [\"PatientApp\"]\n X-Goog-Healthcare-Audit-CohortName: [\"Cohort1\"]\n }\n ...\n }\n ...\n}\n```"]]
