疑難排解

本頁說明使用 Cloud Storage 時可能遇到的常見錯誤，以及相關的疑難排解方法。

如要瞭解影響 Cloud Storage 等 Trusted Cloud by S3NS 服務的事件，請參閱Trusted Cloud by S3NS 服務健康狀態資訊主頁。

記錄原始要求

使用 gcloud 或 Cloud Storage 用戶端程式庫等工具時，工具會處理大部分的請求和回應資訊。不過，有時查看詳細資料有助於排解問題，或在 Stack Overflow 等論壇中提問。請按照下列操作說明，為工具傳回要求和回應標頭：

gcloud storage ls gs://my-bucket/my-object --log-http --verbosity=debug

import logging
import http.client

logging.basicConfig(level=logging.DEBUG)
http.client.HTTPConnection.debuglevel=5

ruby
Google::Apis.logger.level = Logger::DEBUG

新增自訂標頭

在要求中新增自訂標頭是常見的偵錯工具，例如啟用偵錯標頭或追蹤要求。下列範例說明如何為不同的 Cloud Storage 工具設定要求標頭：

gcloud storage objects describe gs://my-bucket/my-object --additional-headers=HEADER_NAME=HEADER_VALUE

namespace gcs = google::cloud::storage;
gcs::Client client = ...;
client.AnyFunction(... args ..., gcs::CustomHeader("header-name", "value"));

using Google.Cloud.Storage.V1;

var client = StorageClient.Create();
client.Service.HttpClient.DefaultRequestHeaders.Add("custom-header", "custom-value");

var buckets = client.ListBuckets("my-project-id");
foreach (var bucket in buckets)

{
  Console.WriteLine(bucket.Name);
}

package main

import (
  "context"

  "cloud.google.com/go/storage"
  "github.com/googleapis/gax-go/v2/callctx"
)

func main() {
  ctx := context.Background()

  client, err := storage.NewClient(ctx)
  if err != nil {
    // Handle error.
  }
  ctx = callctx.SetHeaders(ctx, "X-Custom-Header", "value")

  // Use client as usual with the context and the additional headers will be sent.
  _, err = client.Bucket("my-bucket").Attrs(ctx)
  if err != nil {
    // Handle error.
  }
}

import com.google.api.gax.rpc.FixedHeaderProvider;
import com.google.api.gax.rpc.HeaderProvider;
import com.google.cloud.WriteChannel;
import com.google.cloud.storage.BlobInfo;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;

import java.io.IOException;
import java.nio.ByteBuffer;
import static java.nio.charset.StandardCharsets.UTF_8;

public class Example {

  public void main(String args[]) throws IOException {
    HeaderProvider headerProvider =
            FixedHeaderProvider.create("custom-header", "custom-value");
    Storage storage = StorageOptions.getDefaultInstance()
            .toBuilder()
            .setHeaderProvider(headerProvider)
            .build().getService();
    String bucketName = "example-bucket";
    String blobName = "test-custom-header";

    // Use client with custom header
    BlobInfo blob = BlobInfo.newBuilder(bucketName, blobName).build();
    byte[] stringBytes;
    try (WriteChannel writer = storage.writer(blob)) {
      stringBytes = "hello world".getBytes(UTF_8);
      writer.write(ByteBuffer.wrap(stringBytes));
    }
  }
}

const storage = new Storage();

storage.interceptors.push({
  request: requestConfig => {
    Object.assign(requestConfig.headers, {
      'X-Custom-Header': 'value',
      });
    return requestConfig;
  },
});

use Google\Cloud\Storage\StorageClient;

$client = new StorageClient([
   'restOptions' => [
       'headers' => [
           'x-foo' => 'bat'
       ]
   ]
]);

$bucket = $client->bucket('my-bucket');

$bucket->info([
   'restOptions' => [
       'headers' => [
           'x-foo' => 'bar'
       ]
   ]
]);

from google.cloud import storage

client = storage.Client(
    extra_headers={
        "x-custom-header": "value"
    }
)

require "google/cloud/storage"

storage = Google::Cloud::Storage.new

storage.add_custom_headers { 'X-Custom-Header'=> 'value' }

存取具有 CORS 設定的值區

如果您已在值區中設定 CORS，但發現來自用戶端瀏覽器的傳入要求失敗，請嘗試下列疑難排解步驟：

1. 查看目標值區的 CORS 設定。如果有多個 CORS 設定項目，請確保用於疑難排解的要求值對應至單一 CORS 設定項目中的值。

2. 測試發出 CORS 要求時，請確認您並未對 storage.cloud.google.com 端點提出要求，因為該端點不允許 CORS 要求。如要進一步瞭解 CORS 支援的端點，請參閱「Cloud Storage CORS 支援」。

3. 使用選擇的工具檢查要求及回應。在 Chrome 瀏覽器中，您可以使用標準開發人員工具來查看此資訊：

   1. 按一下瀏覽器工具列中的 Chrome 選單 (more_vert)。
   2. 依序選取「更多工具」 >「開發人員工具」。
   3. 按一下 [Network] (網路) 分頁標籤。
   4. 從您的應用程式或指令列傳送要求。
   5. 在顯示網路活動的窗格中，找出要求。
   6. 在 [Name] 欄中，按一下與要求對應的名稱。
   7. 按一下 [Headers] 分頁標籤查看回應標頭，或按一下 [Response] 分頁標籤查看回應內容。

   如果沒有看到要求和回應，可能是瀏覽器快取了之前失敗的預檢要求嘗試。清除瀏覽器的快取應該會一併清除預檢快取。如果沒有清除，請將 CORS 設定中的 MaxAgeSec 值設為低於預設值 1800 (30 分鐘)，等待舊 MaxAgeSec 設定的時間截止，然後重試要求。這會執行新的預檢要求，進而擷取新的 CORS 設定並清除快取項目。完成問題除錯後，請將 MaxAgeSec 改回較高的值，以降低值區的預檢流量。

4. 請確定要求含有 Origin 標頭，且該標頭值至少符合值區 CORS 設定中的一個 Origins 值。請注意，這些值的通訊協定、主機和通訊埠必須完全相符。以下是一些可接受的相符範例：

   • http://origin.example.com 與 http://origin.example.com:80 相符 (因為 80 是預設的 HTTP 通訊埠)，但與 https://origin.example.com、http://origin.example.com:8080、http://origin.example.com:5151 或 http://sub.origin.example.com 不相符。

   • https://example.com:443 與 https://example.com 相符，但與 http://example.com 或 http://example.com:443 不相符。

   • http://localhost:8080 只與 http://localhost:8080 完全相符，但與 http://localhost:5555 或 http://localhost.example.com:8080 不相符。

5. 如果是簡易要求，請確定要求的 HTTP 方法至少符合值區 CORS 設定中的一個 Methods 值。如果是預檢要求，請確認 Access-Control-Request-Method 中指定的方法至少符合一個 Methods 值。

6. 如果是預檢要求，請檢查是否含有一或多個 Access-Control-Request-Header 標頭。如果是，請確定每個 Access-Control-Request-Header 值都符合值區 CORS 設定中的 ResponseHeader 值。所有在 Access-Control-Request-Header 中指名的標頭都必須納入 CORS 設定，預檢要求才會成功，並在回應中納入 CORS 標頭。

錯誤代碼

以下是您可能會遇到的常見 HTTP 狀態碼。

400：要求無效

問題：執行可續傳的上傳作業時，我收到這項錯誤和訊息 Failed to parse Content-Range header.

解決方案：您在 Content-Range 標題中使用的值無效。舉例來說，Content-Range: */* 無效，應指定為 Content-Range: bytes */*。如果收到這則錯誤訊息，表示目前的續傳上傳作業已失效，您必須開始新的續傳上傳作業。

400：Storage Intelligence 專屬錯誤

下列各節說明您在設定或管理資源的 Storage Intelligence 時，可能會遇到的常見錯誤。

400：值區名稱無效

問題：設定或管理資源的儲存空間智慧功能時，您可能會收到這項錯誤和訊息 The specific bucket is not valid.

解決方法：您在要求中使用的網址無效。網址必須符合下列規定：

• 儲存空間智慧功能僅支援 locations/global。系統不支援使用其他位置。
• Storage Intelligence，而非複數。

以下是有效網址的範例：

curl -X PATCH -H "Content-Type: application/json" -d
    '{"edition_config": "STANDARD" }'
    -H "Authorization: Bearer $(gcloud auth print-access-token)" "https://storage.s3nsapis.fr/v2/projects/my-project/locations/global/storageIntelligence?updateMask=edition_config"

400：引數無效 - 更新遮罩空白

問題：設定或管理資源的儲存空間智慧功能時，您可能會收到這項錯誤和訊息 Empty UPDATE_MASK in the request.

解決方案：UPDATE_MASK 是以半形逗號分隔的欄位名稱清單，當中列出要求更新的欄位。欄位名稱採用 FieldMask 格式，屬於 StorageIntelligence 資源。如要更新資源的 Storage Intelligence 設定，請在要求中使用有效的 UPDATE_MASK。不支援空白值。

400：更新遮罩路徑無效

問題：設定或管理資源的儲存空間智慧功能時，您可能會收到這項錯誤和訊息 Invalid UPDATE_MASK paths.

解決方法：如果在 UPDATE_MASK 中使用無效的欄位名稱，系統會顯示錯誤訊息。UPDATE_MASK 是以半形逗號分隔的欄位名稱清單，要求會更新這些欄位。欄位名稱採用 FieldMask 格式，屬於 IntelligenceConfig 資源。如要更新資源的儲存空間智慧設定，請確保 UPDATE_MASK 中列出的每個欄位名稱都是 IntelligenceConfig 資源內的有效欄位。

400：欄位無法編輯

問題：設定或管理資源的儲存空間智慧功能時，您可能會收到這項錯誤和訊息 Invalid UPDATE_MASK: UPDATE_TIME field is not editable.

解決方案：UPDATE_MASK 是以半形逗號分隔的欄位名稱清單，當中列出要求更新的欄位。欄位名稱採用 FieldMask 格式，且屬於 IntelligenceConfig 資源。如果您嘗試更新無法編輯的欄位，系統會顯示錯誤訊息。請從 Update_Mask 中移除無法編輯的欄位，然後再試一次。

400：無效值

問題：設定或管理資源的儲存空間智慧功能時，您可能會收到這項錯誤和訊息 Invalid value at storage_intelligence.edition_config.

解決方法：如果您嘗試為 edition_config 欄位使用無效值，就會收到錯誤訊息。可以使用的值為 INHERIT、STANDARD 和 DISABLED。請檢查值，然後再試一次。

400：篩選器不得為空

問題：更新資源的 Storage Intelligence 設定時，您可能會收到這則錯誤訊息和 Non-empty filter cannot be specified for INHERIT or DISABLED edition configuration.

解決方案：將 Storage Intelligence edition_config 更新為 INHERIT 或 DISABLED 時，您無法在要求中使用任何bucket 篩選器。請從要求中移除篩選器，然後再試一次。

400：篩選器中的位置或值區值為空

問題：更新資源的 Storage Intelligence 設定時，您可能會收到這則錯誤訊息和 Empty location or bucket values in filter.

解決方法：更新 Storage Intelligence 設定並在要求中使用 bucket 篩選器時，如果 location 或 bucket 的值為空字串，就會發生錯誤。請為 location 或 bucket 提供有效值，然後再試一次。

401：未經授權

問題：直接對公開值區提出的要求失敗，並傳回 HTTP 401: Unauthorized 和 Authentication Required 回應。

解決方案：確認您的用戶端或任何中繼 Proxy，未將 Authorization 標頭新增至對 Cloud Storage 的要求。即使 Authorization 標頭為空白，系統也會將任何含有該標頭的要求視為驗證嘗試。

403：Account Disabled (帳戶已停用)

問題：我嘗試建立值區，但收到 403 Account Disabled 錯誤訊息。

解決方案：這個錯誤訊息表示您尚未啟用相關專案的計費功能。如需啟用計費功能的步驟，請參閱「啟用專案的計費功能」。

403：禁止

問題：我應該有權存取特定值區或物件，但嘗試存取時卻收到 403 - Forbidden 錯誤，並顯示類似以下內容的訊息：example@email.com does not have storage.objects.get access to the Google Cloud Storage object。

解決方法：您缺少完成要求所需的 bucket 或物件 IAM 權限。如果您認為自己符合要求，但無法提出要求，請執行下列檢查：

1. 錯誤訊息中提及的受讓人是否為您預期的對象？如果錯誤訊息提及非預期的電子郵件地址或「匿名來電者」，表示要求並未使用您預期的憑證。這可能是因為您用來提出要求的工具是使用其他別名或實體的憑證設定，也可能是因為要求是由服務帳戶代表您提出。

2. 錯誤訊息中提及的權限是否為您認為需要的權限？如果權限要求出乎意料，可能是因為您使用的工具需要額外存取權，才能完成要求。舉例來說，如要大量刪除值區中的物件，gcloud 必須先建構要刪除的值區物件清單。大量刪除作業的這部分需要 storage.objects.list 權限，這可能令人意外，因為目標是刪除物件，通常只需要 storage.objects.delete 權限。如果這是導致錯誤訊息的原因，請確認您已獲派具有額外必要權限的 IAM 角色。

3. 您是否已在目標資源或父項資源中獲派 IAM 角色？舉例來說，如果您獲授專案的 Storage Object Viewer 角色，並嘗試下載物件，請確認物件位於專案中的值區；您可能無意間獲得其他專案的 Storage Object Viewer 權限。

4. 您是否透過便利值取得特定值區或物件的存取權？移除授予便利值的存取權，可能會導致先前已啟用的主體失去資源存取權。

   舉例來說，假設 jane@example.com 擁有專案 my-example-project 的擁有者 (roles/owner) 基本角色，而專案的 IAM 政策將儲存空間物件建立者 (roles/storage.objectCreator) 角色授予便利值 projectOwner:my-example-project。也就是說，jane@example.com 具有 my-example-project 內值區的儲存空間物件建立者角色相關聯權限。如果移除這項授權，jane@example.com 就會失去與 Storage 物件建立者角色相關聯的權限。

   在這種情況下，您可以授予自己執行所需動作的必要值區或物件層級權限，重新取得值區或物件的存取權。

5. 是否有身分與存取權管理拒絕政策禁止您使用特定權限？請與貴機構管理員聯絡，確認是否已啟用 IAM 拒絕政策。

403：權限遭拒

問題：設定或管理資源的 Storage Intelligence 設定時，發生權限遭拒錯誤。

解決方法：如果您在設定及管理資源的 Storage Intelligence 時，收到類似 permission storage.intelligenceConfigs.update 的權限遭拒錯誤訊息，請參閱您要執行的作業的權限部分。如要解決這個問題，請授予適當的權限。您可以透過下列任一方式授予權限：

• 在啟用 Storage Intelligence 的Trusted Cloud by S3NS 資源階層資源中，授予 IAM 權限。
• 請確認資源階層中較高的資源會將權限傳遞給子項資源。 Trusted Cloud by S3NS

409：Conflict (衝突)

問題：我在嘗試建立值區時收到以下錯誤訊息：

409 Conflict. Sorry, that name is not available. Please try a different one.

解決方案：您嘗試使用的值區名稱 (例如 gs://cats 或 gs://dogs) 已經受到使用。Cloud Storage 採用全域命名空間，因此您無法使用與現有值區相同的名稱為值區命名。請選擇尚未使用的名稱。

412：違反自訂限制

問題：我的要求遭到拒絕，並顯示 412 orgpolicy 錯誤。

問題：我的要求遭到拒絕，並出現 412 Multiple constraints were violated 錯誤。

解決方法：請洽詢安全管理員團隊，確認您傳送要求的 bucket 是否受到使用自訂限制的機構政策影響。如果不同的機構政策彼此衝突，也可能會影響儲存空間。舉例來說，一項政策規定值區必須採用 Standard 儲存空間級別，另一項政策則規定值區必須採用 Coldline 儲存空間級別。

429：要求數量過多

問題：我的要求遭到拒絕，並顯示 429 Too Many Requests 錯誤。

解決方案：您已達到 Cloud Storage 允許特定資源發出的要求數量上限。如要瞭解 Cloud Storage 的限制，請參閱「Cloud Storage 配額」。

• 如果工作負載包含每秒對儲存空間發出的數千個要求，請參閱「要求率和存取分配指南」，瞭解最佳做法，包括逐步增加工作負載，以及避免使用連續檔名。

• 如果工作負載可能使用 50 Gbps 以上的網路輸出至特定位置，請檢查頻寬用量，確保您未遇到頻寬配額。

診斷 Trusted Cloud 控制台錯誤

問題：使用 Trusted Cloud 控制台執行作業時，系統會顯示一般錯誤訊息。舉例來說，我嘗試刪除 bucket 時看到錯誤訊息，但沒有看到作業失敗的詳細原因。

解決方法：使用 Trusted Cloud 控制台通知查看作業失敗的詳細資訊：

1. 按一下 Trusted Cloud 控制台標題中的「通知」按鈕 (notifications)。

   下拉式選單會顯示控制台最近執行的作業。Trusted Cloud

2. 按一下要進一步瞭解的項目。

   系統會開啟頁面，顯示作業的詳細資訊。

3. 按一下各資料列，即可展開詳細錯誤資訊。

問題：使用 Trusted Cloud 控制台時，我沒有看到顯示特定資料欄。

解決方法：如要在 Trusted Cloud 控制台中顯示特定資料欄，請按一下「資料欄顯示選項」圖示 (view_column)，然後選取要顯示的資料欄。

模擬資料夾和代管資料夾

問題：我刪除了值區中的某些物件，現在包含這些物件的資料夾不會顯示在 Trusted Cloud 控制台中。

解決方案：雖然 Trusted Cloud 控制台會顯示 bucket 的內容，彷彿有目錄結構，但資料夾在 Cloud Storage 中並不存在。因此，從值區中移除具有相同前置字元的所有物件後，代表該物件群組的資料夾圖示就不會再顯示在 Trusted Cloud 控制台中。

問題：我無法建立代管資料夾。

解決方法：如要建立代管資料夾，請確認符合下列規定：

• 您擁有包含 storage.managedfolders.create 權限的 IAM 角色，例如「儲存空間物件管理員」(roles/storage.objectAdmin) 角色。如需授予角色的操作說明，請參閱「使用 IAM 權限」。

• 在要建立代管資料夾的值區中啟用統一值區層級存取權。

• 值區或專案沒有使用值區資源類型 (storage.googleapis.com/Bucket) 或物件資源類型 (storage.googleapis.com/Object) 的 IAM 條件。如果專案中的任何值區有使用這兩種資源類型的 IAM 條件，即使之後移除條件，專案中所有值區都無法建立受管理資料夾。

問題：我無法停用統一值區層級存取權，因為值區中有受管理資料夾。

解決方案：如果值區中有代管資料夾，就無法停用統一值區層級存取權。如要停用統一值區層級存取權，請先刪除值區中的所有受管理資料夾。

公開您的資料

問題：我嘗試將資料設為公開，但收到機構政策錯誤訊息。

解決方法：部分機構政策限制會禁止您公開資料。舉例來說，「網域限定共用」限制 (constraints/iam.allowedPolicyMemberDomains) 會根據機構的網域限制資源共用。如果機構政策失敗，請聯絡管理員，授予您專案或 bucket 層級的權限，編輯機構、資料夾或專案資源的機構政策，允許資源共用。如果覆寫機構政策後仍看到這則錯誤訊息，請稍候幾分鐘，等待變更生效。

問題：我嘗試公開資料時，收到權限錯誤訊息。

解決方案：請確認您具備 storage.buckets.setIamPolicy 權限或 storage.objects.setIamPolicy 權限。舉例來說，這些權限是在「Storage 管理員」角色 (roles/storage.admin) 中授予。如果您擁有 storage.buckets.setIamPolicy 權限或 storage.objects.setIamPolicy 權限，但仍收到錯誤訊息，則您的值區可能受到禁止公開存取政策限制，因此無法存取 allUsers 或 allAuthenticatedUsers。限制公開存取可能是直接在值區上設定，也可能是透過較高層級設定的機構政策強制執行。

延遲時間

以下是您可能會遇到的常見延遲問題。此外，Trusted Cloud by S3NS 服務健康狀態資訊主頁會提供影響 Trusted Cloud by S3NS 服務 (例如 Cloud Storage) 的事件資訊。

上傳或下載延遲

問題：上傳或下載時延遲時間變長。

解決方案：請考慮下列上傳和下載延遲的常見原因：

• CPU 或記憶體限制：受影響環境的作業系統應具備工具，可測量 CPU 使用率和記憶體使用率等本機資源耗用量。

• 磁碟 IO 限制：本機磁碟 IO 可能會影響效能。

CLI 或用戶端程式庫延遲時間

問題：使用 Google Cloud CLI 或其中一個用戶端程式庫存取 Cloud Storage 時，延遲時間變長。

解決方案：gcloud CLI 和用戶端程式庫會在適當情況下自動重試要求，但這項行為可能會有效增加使用者看到的延遲時間。使用 Cloud Monitoring 指標 storage.googleapis.com/api/request_count，查看 Cloud Storage 是否持續提供可重試的回應碼，例如 429 或 5xx。

Proxy 伺服器

問題：我使用 Proxy 伺服器來進行連線，我需要做些什麼？

解決方案：如要透過 Proxy 伺服器存取 Cloud Storage，您必須允許存取下列網域：

• accounts.google.com，用於建立 OAuth2 驗證權杖
• oauth2.googleapis.com，用於執行 OAuth2 權杖交換作業
• *.googleapis.com 儲存空間要求

如果您的 Proxy 伺服器或安全性政策不支援依網域加入許可清單，而是只支援依 IP 網路封鎖加入許可清單，那麼我們強烈建議您為所有的 Google IP 位址範圍設定 Proxy 伺服器。您可以在 ARIN 查詢 WHOIS 資料來尋找位址範圍。最佳做法是定期查看 Proxy 設定，確保與 Google 的 IP 位址相符。

我們不建議您使用對 oauth2.googleapis.com 和 storage.s3nsapis.fr 進行一次性查詢所取得的個人 IP 位址來設定您的 Proxy。由於 Google 服務是透過 DNS 名稱公開，而 DNS 名稱會對應到隨時間變化的大量 IP 位址，因此按照一次性查詢所設定的 Proxy 可能會無法連線至 Cloud Storage。

如果您透過 Proxy 轉送要求，建議您向網路管理員確認含有憑證的 Authorization 標頭不會遭到 Proxy 移除。如果沒有 Authorization 標頭，您的要求將會遭到拒絕，而您會收到 MissingSecurityHeader 錯誤訊息。

後續步驟

• 在 Cloud Storage 常見問題中尋找其他問題的答案。