이 페이지에서는 Artifact Analysis 전역 및 리전 서비스 엔드포인트와 사용 방법을 설명합니다.
서비스 엔드포인트는 API 서비스의 네트워크 주소를 지정하는 기준 URL입니다. Artifact Analysis에는 전역 및 리전 엔드포인트가 모두 있습니다.
전역 엔드포인트: 기본적으로 Artifact Analysis는 전역 엔드포인트 containeranalysis.googleapis.com에 API 요청을 전송합니다. 전역 엔드포인트는 전송 중인 데이터가 특정 위치에 유지된다고 보장하지 않으며 지원되는 모든 리전에서 아티팩트 분석 데이터를 가져올 수 있습니다. 데이터가 저장된 리전 외부에서 처리될 수 있습니다.
리전 엔드포인트: 데이터가 특정 리전에 저장, 전송, 처리되도록 리전 제한을 적용하는 서비스 엔드포인트입니다. 리전 엔드포인트는 영향을 받는 리소스가 엔드포인트에서 지정된 위치에 있는 경우에만 요청 처리를 허용합니다. 리전 엔드포인트는 다음 형식을 사용합니다.
containeranalysis.region.rep.googleapis.com개
다음과 같은 상황에서는 리전 엔드포인트를 사용하는 것이 좋습니다.
데이터에 액세스해야 하는 애플리케이션이 데이터가 저장된 리전과 지리적으로 가깝지 않습니다.
여러 위치에 데이터를 저장하고 지연 시간, 안정성, 가용성을 최적화하려고 합니다.
데이터가 저장된 위치와 동일한 위치에서 데이터를 처리해야 하는 데이터 현지화 정책 또는 규정을 준수해야 합니다.
증명 및 빌드 출처 데이터는 전역 엔드포인트에 저장됩니다.
취약점 스캔 결과와 SBOM 데이터는 리전 및 멀티 리전 엔드포인트에 저장됩니다.
리전 엔드포인트를 지원하는 위치
Artifact Analysis에서 지원하는 대부분의 리전에 리전 엔드포인트를 사용할 수 있습니다.
멀티 리전 및 일부 리전의 경우 Artifact Analysis는 전역 엔드포인트만 지원합니다.
지원되는 리전 및 각 리전에서 지원되는 서비스 엔드포인트 목록은 메타데이터 스토리지 위치를 참고하세요.
Google Cloud CLI 명령어
gcloud CLI를 사용하는 경우 리전 엔드포인트에 요청을 보내는 방법은 두 가지입니다.
--location 플래그를 사용합니다.
아티팩트 분석 명령어에 사용할 기본 리전 엔드포인트를 설정합니다.
--location 플래그 사용
다음 명령어 중 하나와 함께 --location 플래그를 사용하여 요청을 적절한 서비스 엔드포인트로 전달할 수 있습니다.
[[["이해하기 쉬움","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-09(UTC)"],[[["\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."]]
