[[["容易理解","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-05 (世界標準時間)。"],[],[],null,["# Locational endpoints\n\nThis page describes how to use locational endpoints to access\nCloud Storage. When you use locational endpoints, you can make sure\nyour at-rest data stays within jurisdiction to meet [data residency](/assured-workloads/docs/data-residency)\nrequirements.\n| **Note:** To run your workloads in a manner that's complaint with [International Traffic in Arms Regulations (ITAR)](https://www.pmddtc.state.gov/ddtc_public?id=ddtc_kb_article_page&sys_id=24d528fddbfc930044f9ff621f961987), use [regional endpoints](/storage/docs/regional-endpoints). For information about restrictions when using Cloud Storage in a manner that's compliant with ITAR, see [Restrictions and limitations for ITAR](/assured-workloads/docs/control-packages/itar#storage).\n\nOverview\n--------\n\nLocational endpoints are [request endpoints](/storage/docs/request-endpoints) that only allow requests to\nproceed if the affected resource exists in the [location](#supported-regions) specified by\nthe endpoint. For example, when you use the endpoint\n`https://us-central1-storage.googleapis.com` in a delete bucket request, the\nrequest only proceeds if the bucket is located in `US-CENTRAL1`.\n\nUnlike global endpoints, where requests can be processed in a\ndifferent location from where the resource resides, locational endpoints\nguarantee that your requests are processed only within\nthe location specified by the endpoint, where the resource resides.\n| **Note:** Cloud Load Balancing uses [global request endpoints](/storage/docs/request-endpoints) when routing requests to Cloud Storage buckets. You cannot configure Cloud Load Balancing to use locational endpoints.\n\nUsing locational endpoints guarantees that:\n\n- Your data stored in Cloud Storage does not leave the specified\n location.\n\n- Your data is TLS terminated in the region specified by the endpoint when\n transiting from on-premises to Google Cloud.\n\nWhen using locational endpoints, you assume the following responsibilities:\n\n- In order to get data residency guarantees, requests made to a locational\n endpoint must originate from the same location that's specified by the\n endpoint. For example, if you're using a Compute Engine virtual machine to\n perform a request to a bucket residing in `US-CENTRAL1` via the\n `us-central1-storage.googleapis.com` endpoint, the virtual machine must also\n reside in `US-CENTRAL1`.\n\n- Locational endpoints must only be used when performing [supported operations](#supported-operations).\n Performing unsupported operations result in an error.\n\nLocational endpoints support traffic between on-premises to Google Cloud via\nInterconnect or VPN, and traffic between Google Cloud services (for example,\nfrom BigQuery to Cloud Storage). Internet traffic is not\nsupported.\n\nSupported operations\n--------------------\n\nThe following table summarizes the operations that can and cannot be performed\nwith locational endpoints. In general, intra-location operations can be\nperformed with locational endpoints, while cross-location operations cannot.\n\nIf you attempt to perform an unsupported operation using a locational endpoint,\nCloud Storage returns a 400 HTTP error code with the message: \"This\nendpoint does not implement this operation. Please use the global endpoint.\"\n\n^1^ To perform this operation using locational endpoints, the bucket\ncontaining the affected object must exist in the location specified by the\nendpoint. For example: an object delete request to\n`us-central1-storage.googleapis.com` can only be used to delete objects in\nbuckets that reside in the `US-CENTRAL1` region. If you try to delete an object\nin a location that's not `US-CENTRAL1`, the operation returns a `NOT_FOUND`\nerror.\n\n^2^ To perform this operation using locational endpoints, the bucket\nmust exist in the location specified by the endpoint. For example: a bucket\ncreate request to `us-central1-storage.googleapis.com` can only be used to\ncreate a bucket in the `US-CENTRAL1` region. If you try to create the bucket in\na location that's not `US-CENTRAL1`, the operation returns an `INVALID_ARGUMENT`\nerror.\n\n^3^ To perform this operation using locational endpoints, the bucket\nmust exist in the location specified by the endpoint. For example: a bucket\ndelete request to `us-central1-storage.googleapis.com` can only be used to delete a\nbucket in the `US-CENTRAL1` region. If you try to delete a bucket in a location\nthat's not `US-CENTRAL1`, the operation returns a `NOT_FOUND` error.\n\n^4^ To perform this operation using locational endpoints, the source\nand destination buckets must both exist in the location specified by the\nendpoint. For example: you can use locational endpoints to copy an object from\none bucket to another if both buckets exist in the same location. However, you\ncannot use locational endpoints to copy an object from one bucket to another if\nthe buckets exist in different locations. If the source or destination bucket\nexists in a different location than the location specified by the endpoint, the\noperation returns a `NOT_FOUND` error.\n\nSupported regions\n-----------------\n\nLocational endpoints are supported for all US regions, the `US` multi-region,\nand the `NAM4` predefined dual-region. For more information about what regions\ncan be specified, see [Bucket locations](/storage/docs/locations).\n\nMaking requests\n---------------\n\n### Console\n\nSee [Restrictions and limitations for ITAR](/assured-workloads/docs/control-packages/itar#storage) for information about how to\nperform operations using the Google Cloud console in a manner that's ITAR\ncompliant.\n\n### Command line\n\nTo configure the Google Cloud CLI for use with locational endpoints:\n\n1. Set the `api_endpoint_overrides/storage` property to the locational\n endpoint you want to use:\n\n ```\n gcloud config set api_endpoint_overrides/storage https://LOCATION-storage.googleapis.com/\n ```\n\nOnce this property is set, you can use gcloud CLI commands as you\nnormally would.\n\nAlternatively, you can use locational endpoints for individual commands by\nsetting the `CLOUDSDK_API_ENDPOINT_OVERRIDES_STORAGE` environment variable\nin each command. For example: \n\n```\nCLOUDSDK_API_ENDPOINT_OVERRIDES_STORAGE=https://LOCATION-storage.googleapis.com/ gcloud ls gs://my-bucket\n```\n\n### Client libraries\n\nCloud Storage client libraries manage request endpoints\nautomatically, but you can manually set locational endpoints. To learn how\nto set locational endpoints, see the\n[client library code samples using request endpoints](/storage/docs/request-endpoints#client-libraries).\n\n### REST APIs\n\n### JSON API\n\nWhen making requests to locational endpoints, use the following URIs:\n\n- For general JSON API requests, excluding object uploads, use the\n following endpoint:\n\n ```\n https://LOCATION-storage.googleapis.com\n ```\n\n Replace \u003cvar translate=\"no\"\u003eLOCATION\u003c/var\u003e with a supported [bucket location](#supported-regions). For\n example, `us-central1`.\n- For JSON API object uploads, use the following endpoint:\n\n ```\n https://LOCATION-storage.googleapis.com/upload/storage/v1/b/BUCKET_NAME/o\n ```\n\n Replace:\n - \u003cvar translate=\"no\"\u003eLOCATION\u003c/var\u003e with a supported [bucket location](#supported-regions). For\n example, `us-central1`.\n\n - \u003cvar translate=\"no\"\u003eBUCKET_NAME\u003c/var\u003e with the name of the bucket to which you want\n to upload an object. For example, `my-example-bucket`.\n\n- For JSON API object downloads, use the following endpoint:\n\n ```\n https://LOCATION-storage.googleapis.com/download/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME?alt=media\n ```\n\n Replace:\n - \u003cvar translate=\"no\"\u003eLOCATION\u003c/var\u003e with a supported [bucket location](#supported-regions). For\n example, `us-central1`.\n\n - \u003cvar translate=\"no\"\u003eBUCKET_NAME\u003c/var\u003e with the name of the bucket that\n contains the object you want to download. For example,\n `my-example-bucket`.\n\n - \u003cvar translate=\"no\"\u003eOBJECT_NAME\u003c/var\u003e with the name of the object you want\n to download. For example, `waterfall.png`.\n\nNote that the JSON API endpoints only support HTTPS requests.\n\n### XML API\n\nWhen using the XML API to make requests to locational endpoints, you can\nuse a virtual hosted style endpoint or a path-style endpoint:\n\n- Virtual hosted style endpoint:\n\n ```\n https://BUCKET_NAME.LOCATION-storage.googleapis.com\n ```\n- Path-style endpoint:\n\n ```\n https://LOCATION-storage.googleapis.com/BUCKET_NAME\n ```\n\nFor both endpoint types, replace:\n\n- \u003cvar translate=\"no\"\u003eLOCATION\u003c/var\u003e with a supported [bucket location](#supported-regions). For\n example, `us-central1`.\n\n- \u003cvar translate=\"no\"\u003eBUCKET_NAME\u003c/var\u003e with a valid bucket name. For example,\n `my-example-bucket`.\n\n| **Note:** Virtual hosted-style endpoints cannot be used to access domain-named buckets. Use either path-style endpoints or a redirect instead.\n\nThe XML API endpoints support secure sockets layer (SSL) encryption,\nwhich means you can use either HTTP or HTTPS. Using HTTPS is\nrecommended, especially if you authenticate to Cloud Storage\nusing OAuth 2.0.\n\n### Properly format requests\n\nTo ensure that your requests are compatible across Cloud Storage tools:\n\n- Ensure that you [properly encode special characters](/storage/docs/request-endpoints#encoding) that appear in the\n object name or query string of a request URI.\n\n- Familiarize yourself with [bucket naming](/storage/docs/buckets#naming) and\n [object naming considerations](/storage/docs/objects#naming).\n\nKnown constraints\n-----------------\n\nThere is no support for [mTLS endpoints](/storage/docs/request-endpoints#mtls).\n\nRestricting global API endpoint usage\n-------------------------------------\n\nTo help enforce the use of locational endpoints, you can use the\n`constraints/gcp.restrictEndpointUsage` organization policy constraint to block\nrequests to the global API endpoint. For more information, see the\n[Restrict Endpoint Usage](/assured-workloads/docs/restrict-endpoint-usage) documentation."]]
