[[["容易理解","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-03 (世界標準時間)。"],[[["\u003cp\u003eArtifact Analysis utilizes both global (\u003ccode\u003econtaineranalysis.googleapis.com\u003c/code\u003e) and regional service endpoints to manage API requests and data storage.\u003c/p\u003e\n"],["\u003cp\u003eGlobal endpoints can retrieve data from any supported region but do not guarantee in-transit data remains in a specific location, while regional endpoints enforce data storage, transmission, and processing within a designated region.\u003c/p\u003e\n"],["\u003cp\u003eRegional endpoints are recommended for applications with latency, reliability, or data locality requirements, as well as compliance with data regulations.\u003c/p\u003e\n"],["\u003cp\u003eThe gcloud CLI allows directing requests to regional endpoints by using the \u003ccode\u003e--location\u003c/code\u003e flag or by setting a default regional endpoint for Artifact Analysis commands.\u003c/p\u003e\n"],["\u003cp\u003eData such as vulnerability scan results and SBOM data are stored in regional and multi-regional endpoints, whereas attestations and build provenance data are stored in the global endpoint.\u003c/p\u003e\n"]]],[],null,["# Configure data locality by using regional endpoints\n\nThis page describes Artifact Analysis global and regional service endpoints and\nhow to use them.\n\nA **service endpoint** is a base URL that specifies the network address of an\nAPI service. Artifact Analysis has both global and regional endpoints.\n\n- **Global endpoint** : By default, Artifact Analysis sends API requests to\n the global endpoint, `containeranalysis.googleapis.com`. Global endpoints\n don't guarantee that in-transit data remains in a particular location and\n can retrieve Artifact Analysis data from any supported region. Your data\n might be processed outside the region where it is stored.\n\n- **Regional endpoint**: A service endpoint that enforces regional restrictions,\n ensuring that data is stored, transmitted, and processed in a specified\n region. A regional endpoint only allows requests to proceed if the affected\n resource exists in the location specified by the endpoint. Regional endpoints\n use the following format:\n\n `containeranalysis.`\u003cvar translate=\"no\"\u003eregion\u003c/var\u003e`.rep.googleapis.com`.\n\n Consider using regional endpoints in the following situations:\n - The application that needs to access your data is not geographically close\n to the region where your data is stored.\n\n - You are storing data in multiple locations and want to optimize latency,\n reliability, and availability.\n\n - You need to comply with data locality policies or regulations that require\n you to process your data in the same location where the data is stored.\n\nAttestations and build provenance data are stored in the global endpoint.\nVulnerability scan results and SBOM data are stored in regional and\nmulti-regional endpoints.\n\nLocations that support regional endpoints\n-----------------------------------------\n\nYou can use regional endpoints for most regions that Artifact Analysis\nsupports.\n\nFor multi-regions and some regions, Artifact Analysis only supports\nthe global endpoint.\n\nFor a list of supported regions and the service endpoints that are supported\nfor each region, see [Metadata storage locations](/artifact-analysis/docs/locations).\n\nGoogle Cloud CLI commands\n-------------------------\n\nWhen you use the gcloud CLI, there are two ways to send requests to\nthe regional endpoint:\n\n- Use the `--location` flag.\n- Set the default regional endpoint that you want to use for Artifact Analysis commands.\n\n### Use the `--location` flag\n\nYou can use the `--location` flag with one of the following commands to direct\nthe request to the appropriate service endpoint:\n\n- [gcloud artifacts sbom export](/sdk/gcloud/reference/artifacts/sbom/export)\n- [gcloud artifacts sbom list](/sdk/gcloud/reference/artifacts/sbom/list)\n- [gcloud artifacts sbom load](/sdk/gcloud/reference/artifacts/sbom/load)\n- [gcloud artifacts version describe](/sdk/gcloud/reference/artifacts/versions/describe)\n- [gcloud artifacts vulnerabilities list](/sdk/gcloud/reference/artifacts/vulnerabilities/list)\n- [gcloud artifacts vulnerabilities load-vex](/sdk/gcloud/reference/artifacts/vulnerabilities/load-vex)\n\nTo successfully process the request with a regional endpoint, the specified\nlocation must meet the following requirements:\n\n- The location [supports a regional endpoint](/artifact-analysis/docs/locations).\n- The location matches the region where the artifact metadata is stored.\n\nIf you omit the `--location` flag or specify a location that does not support\na regional endpoint, the command uses the global endpoint.\n\nFor example, the following command lists vulnerabilities for an image stored in\n`us-east1`: \n\n gcloud artifacts vulnerabilities list --location=us-east1 us-east1-docker.pkg.dev/my-project/my-repo/my-image@sha256:49765698074d6d7baa82f\n\n### Set a default endpoint for commands\n\nBy default, the gcloud CLI commands use the global endpoint. You can\nset a default regional endpoint for Artifact Analysis commands so that\nyou don't need to specify the location in individual commands.\n\nMake sure you're using the gcloud CLI 402.0.0 or newer.\n\n\nBefore using any of the command data below,\nmake the following replacements:\n\n- \u003cvar class=\"edit\" scope=\"LOCATION\" translate=\"no\"\u003eLOCATION\u003c/var\u003e: the [region](/artifact-analysis/docs/locations) where your metadata is stored.\n\n\nExecute the\n\nfollowing\n\ncommand:\n\n#### Linux, macOS, or Cloud Shell\n\n**Note:** Ensure you have initialized the Google Cloud CLI with authentication and a project by running either [gcloud init](/sdk/gcloud/reference/init); or [gcloud auth login](/sdk/gcloud/reference/auth/login) and [gcloud config set project](/sdk/gcloud/reference/config/set). \n\n```bash\ngcloud config set api_endpoint_overrides/containeranalysis https://containeranalysis.LOCATION.rep.googleapis.com\n```\n\n#### Windows (PowerShell)\n\n**Note:** Ensure you have initialized the Google Cloud CLI with authentication and a project by running either [gcloud init](/sdk/gcloud/reference/init); or [gcloud auth login](/sdk/gcloud/reference/auth/login) and [gcloud config set project](/sdk/gcloud/reference/config/set). \n\n```bash\ngcloud config set api_endpoint_overrides/containeranalysis https://containeranalysis.LOCATION.rep.googleapis.com\n```\n\n#### Windows (cmd.exe)\n\n**Note:** Ensure you have initialized the Google Cloud CLI with authentication and a project by running either [gcloud init](/sdk/gcloud/reference/init); or [gcloud auth login](/sdk/gcloud/reference/auth/login) and [gcloud config set project](/sdk/gcloud/reference/config/set). \n\n```bash\ngcloud config set api_endpoint_overrides/containeranalysis https://containeranalysis.LOCATION.rep.googleapis.com\n```\n\nUse a regional endpoint for API methods\n---------------------------------------\n\nSpecify the regional endpoint instead of the global endpoint. For example,\nthe following example lists occurrences in the specified region.\n\n\nBefore using any of the request data,\nmake the following replacements:\n\n- \u003cvar class=\"edit\" scope=\"LOCATION\" translate=\"no\"\u003eLOCATION\u003c/var\u003e: the [region](/artifact-analysis/docs/locations) where your metadata is stored.\n- \u003cvar class=\"edit\" scope=\"PROJECT_ID\" translate=\"no\"\u003ePROJECT_ID\u003c/var\u003e: the project ID of your Google Cloud project.\n\n\nHTTP method and URL:\n\n```\nGET https://containeranalysis.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/occurrences\n```\n\nTo send your request, expand one of these options:\n\n#### curl (Linux, macOS, or Cloud Shell)\n\n| **Note:** The following command assumes that you have logged in to the `gcloud` CLI with your user account by running [`gcloud init`](/sdk/gcloud/reference/init) or [`gcloud auth login`](/sdk/gcloud/reference/auth/login) , or by using [Cloud Shell](/shell/docs), which automatically logs you into the `gcloud` CLI . You can check the currently active account by running [`gcloud auth list`](/sdk/gcloud/reference/auth/list).\n\n\nExecute the following command:\n\n```\ncurl -X GET \\\n -H \"Authorization: Bearer $(gcloud auth print-access-token)\" \\\n \"https://containeranalysis.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/occurrences\"\n```\n\n#### PowerShell (Windows)\n\n| **Note:** The following command assumes that you have logged in to the `gcloud` CLI with your user account by running [`gcloud init`](/sdk/gcloud/reference/init) or [`gcloud auth login`](/sdk/gcloud/reference/auth/login) . You can check the currently active account by running [`gcloud auth list`](/sdk/gcloud/reference/auth/list).\n\n\nExecute the following command:\n\n```\n$cred = gcloud auth print-access-token\n$headers = @{ \"Authorization\" = \"Bearer $cred\" }\n\nInvoke-WebRequest `\n -Method GET `\n -Headers $headers `\n -Uri \"https://containeranalysis.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/occurrences\" | Select-Object -Expand Content\n```\n\nYou should receive a JSON response similar to the following:\n\n```\noccurrences: [\n {\n name: \"projects/my-project/locations/us-east1/occurrences/030b7805-eca4-4739-9a43-ec65ed98c61f\"\n resource_uri: \"https://us-east1-docker.pkg.dev/my-project/my-repo/my-image@sha256:b487c4da45ce363eef69d9c066fa26f6666e4f3c9c414d98d1e27bfcc949e544\"\n note_name: \"projects/goog-vulnz/locations/us-east1/notes/CVE-2018-1272\"\n kind: VULNERABILITY\n ...\n }\n```\n\nBefore the transition to regional metadata storage, occurrences and notes did\nnot include a location name in their identifiers. As newer scans store metadata\nin regions, API requests using either global or regional endpoints return\nresults that include location identifiers.\n\nAn occurrence identifier before the transition looked like this example: \n\n name: \"projects/my-project/occurrences/030b7805-eca4-4739-9a43-ec65ed98c61f\"\n\nThe same occurrence stored in `us-east1` looks like this: \n\n name: \"projects/my-project/locations/us-east1/occurrences/030b7805-eca4-4739-9a43-ec65ed98c61f\"\n\nRestrict global API endpoint usage\n----------------------------------\n\nTo help enforce the use of regional endpoints, use the\n`constraints/gcp.restrictEndpointUsage` organization policy constraint to block\nrequests to the global API endpoint. For more information, see\n[Restricting endpoint usage](/assured-workloads/docs/restrict-endpoint-usage).\n\nWhat's next\n-----------\n\n- View [metadata storage locations](/artifact-analysis/docs/locations) and supported service endpoints for each location."]]
