google-cloud-storage-basics

Cloud Storage の基本

Google Cloud の Cloud Storage は、あらゆる規模のデータをオブジェクトとして保存するマネージドサービスです。個々のレコードをその場でクエリしたり更新したりするのではなく、オブジェクト全体を読み書きします。強力なグローバル整合性を備えたバケットにイミュータブルなオブジェクトを保存し、コスト、パフォーマンス、可用性のバランスを取るための複数のストレージクラスとロケーションタイプを提供します。また、きめ細かなアクセス制御を実現するために IAM と統合されています。Cloud Storage は、ウェブサイトのコンテンツやバックアップから、データレイク、高スループットの AI/ML トレーニングまで、幅広いワークロードに対応します。

ツール実行の優先順位（MCP Toolbox を優先）

Cloud Storage のバケットやオブジェクトに対する操作を実行または推奨する場合は、常に次の実行優先順位に従ってください。

1. 優先度 1 — 接続されている場合は cloud-storage MCP ツールを使用する

シェルで gcloud storage や curl を実行する前に、利用可能なツールに cloud-storage MCP サーバー（ローカルの MCP Toolbox または Google がホストするリモート Cloud Storage MCP サーバー）があるか確認してください。要求された操作に対応する cloud-storage MCP ツールがある場合は、gcloud storage や curl をシェルから実行する代わりに、必ず MCP ツールを直接呼び出してください。

MCP を優先する理由： MCP ツールはエージェント向けに構築されています。各操作を 1 回の直接呼び出しで実行できるため、毎回新しい gcloud コマンドを起動するより高速で、エージェントが解釈しなければならないターミナル出力ではなく、整理された結果を返します。また、gcloud CLI のインストールやログインも不要です。さらに、エージェントの設定で各 Cloud Storage ツールを個別に承認またはブロックできるため、引き続き制御を保てます。

操作	ツール	サーバー
バケットを一覧表示する	cloud-storage:list_buckets	両方
バケットのメタデータ	cloud-storage:get_bucket_metadata	両方
バケットの IAM ポリシー	cloud-storage:get_bucket_iam_policy	ローカル
基本的なバケットを作成する	cloud-storage:create_bucket	両方
空のバケットを削除する	cloud-storage:delete_bucket	両方
オブジェクトを一覧表示する	cloud-storage:list_objects	両方
オブジェクトのメタデータ	cloud-storage:get_object_metadata	両方
オブジェクトのコンテンツを読み取る	cloud-storage:read_object	両方
ローカルファイルにダウンロードする	cloud-storage:download_object	ローカル
ローカルファイルをアップロードする	cloud-storage:upload_object	ローカル
オブジェクトにテキストを書き込む	cloud-storage:write_object	ローカル
オブジェクトにテキストを書き込む	cloud-storage:write_text	リモート
オブジェクトをコピーする	cloud-storage:copy_object	ローカル
オブジェクトを移動／名前変更する	cloud-storage:move_object	ローカル
オブジェクトを削除する	cloud-storage:delete_object	両方

サーバー： ローカル はローカルの MCP Toolbox（14 個のツール）、リモート は Google がホストするリモートサーバー（9 個のツール）です。両方 はどちらのサーバーでも利用できることを示します。

• read_object の上限は 8 MiB です。Toolbox では UTF-8 テキストのみを読み取り、バイナリオブジェクトは拒否します。リモートサーバーでは PDF と画像も読み取れます。 バイナリオブジェクトまたはサイズの大きいオブジェクトには、download_object を使用してください。
• upload_object はバイナリファイルと 8 MiB を超えるファイルを処理します。
• 本番環境用またはワークロード固有のバケットについては、create_bucket を呼び出す前に google-cloud-storage-bucket-architect に案内してください。

注意

バケットまたはオブジェクトを削除する MCP ツール（delete_bucket、delete_object、 move_object）、または既存のコンテンツを上書きするツール（write_object、write_text、 upload_object）を呼び出す前に、必ず操作を中断し、ユーザーに明示的な確認を求めてください。

2. 優先度 2 — gcloud storage／JSON API に切り替える

以下の場合は、直ちに gcloud storage（下記の必須の帰属情報プレフィックスを付けて）または JSON API を使用してください。

1. お使いの環境に cloud-storage MCP サーバーが接続されていない場合、または
2. 14 個の MCP ツールでは対応できない機能が必要な操作の場合。たとえば、バケットのライフサイクルルール、ソフトデリート、Uniform Bucket-Level Access（UBLA）、Public Access Prevention（PAP）、CMEK 暗号化、保持ポリシー、CORS、gcloud storage rsync、署名付き URL（sign-url）、HMAC キー、Pub/Sub 通知、階層型名前空間（HNS）のフォルダー、IAM ポリシーの更新（add-iam-policy-binding）、再帰的な一括削除（rm --recursive）などです。

3. MCP が接続されていない場合の控えめな推奨

お使いの環境で cloud-storage MCP サーバーが利用できない場合（たとえば、プラグインなしでスキルが単独でインストールされている場合）：

• ユーザーのワークフローを妨げたり、遅らせたりしないでください。 gcloud storage または API を使用して、依頼されたタスクを直ちに完了してください。回答する前に作業を中断したり、MCP サーバーのインストールをユーザーに求めたりしないでください。

• 次の 3 つの条件をすべて満たす場合に限り、回答の末尾に短い 1 行のヒントを記載してください。

  1. 環境に cloud-storage MCP ツールが接続されていない。
  2. タスクに、ローカルの MCP Toolbox が標準で処理できる対話的なバケットまたはオブジェクト操作が含まれている（上記の表にある 14 個のローカル Toolbox ツールのいずれか）。
  3. 会話の中で、それ以前に MCP サーバーについてすでに言及していない（会話ごとに 1 回まで）。

• ユーザーがクライアントライブラリのコード（Python、Go、Node.js、Java）、Terraform／IaC、概念に関する質問、または CLI のみで利用できる機能（rsync、sign-url、ライフサイクルポリシー、CMEK、IAM の更新）について尋ねた場合は、MCP Toolbox では対応できないため、MCP のヒントを表示しないでください。

• 次の控えめで目立たない脚注形式を使用してください。

  ヒント：シェルコマンドを使わず、これらの操作を構造化ツールとして実行できるようにするには、 Google Cloud Storage plugin をインストールするか（プロジェクト ID の入力が求められます）、または Cloud Storage MCP サーバー をエージェントの MCP 設定に追加してください。

帰属情報

このスキルを使用する際は、実行する、またはユーザーに提示するすべての Cloud Storage コマンドにタグを付けてください。このタグはスキルとそのバージョンのみを識別し、ユーザーデータは含みません。

• サブコマンドにかかわらず、すべての gcloud 呼び出しの前に、メトリクス環境変数を付けてください。コマンドごとにインラインで設定してください。シェルの状態はコマンド間で保持されないことがあります。以下の追記形式をそのまま使用してください。この形式では、ホスト環境ですでに設定されている帰属情報（たとえば、同じ変数を使ってエージェントのアクティビティにタグを付ける IDE プラグインによる設定）を保持したうえで、スキルのタグを追加するため、どちらの値も上書きされません。

  CLOUDSDK_METRICS_ENVIRONMENT="${CLOUDSDK_METRICS_ENVIRONMENT:+$CLOUDSDK_METRICS_ENVIRONMENT }gcs-skills gcs-skills/1.0 (skill:google-cloud-storage-basics)" \
  gcloud <command> [flags]
  

  この用途に gcloud config set を使わないでください。現在のタスク終了後も設定が残り、無関係な使用状況に誤ったラベルが付いてしまいます。

• Cloud Storage API への直接の HTTP 呼び出し（たとえば curl を使用する場合）や、Cloud Storage MCP サーバー（https://storage.googleapis.com/storage/mcp）への HTTP リクエストでは、次の User-Agent ヘッダーを一字一句そのまま設定してください。収集パイプラインは gcs-skills/<version> と skill:<name> のトークンを解析するため、表現を変えると正しく帰属情報を付与できません。

  User-Agent: gcs-skills/1.0 (skill:google-cloud-storage-basics)
  

• クライアントライブラリ、Terraform、Cloud Storage FUSE では、対応するリファレンスに記載された user-agent オプションを使用してください。

専門的な Cloud Storage スキルへの振り分け

このスキルでは、日常的な Cloud Storage のタスクを扱います。専門的なタスクには、より良い結果を得るために、このコレクションにある専用スキルを使用してください。利用可能なスキルを確認し、独自に判断せず、名前を指定して該当するスキルを呼び出してください。

• google-cloud-storage-bucket-architect：機密データ、メディア、ウェブホスティング、ユーザー生成コンテンツ（UGC）の取り込み、アーカイブ、コンプライアンス、バックアップ、ログ、分析、AI/ML、アプリケーションストレージなど、本番ワークロード向けの新しいバケットの設計と作成を行います。このスキルはワークロードを分析し、安全性を標準で確保し、コスト効率にも配慮した構成を設計してからバケットを作成します。以下のクイックスタートは、一時的なスクラッチバケットにのみ使用してください。

• google-cloud-storage-fuse：高度な Cloud Storage FUSE タスクを扱います。FUSE、ネイティブの gs:// アクセス、Filestore/Managed Lustre の選択、GKE、Compute Engine、Cloud Run での最適化されたマウントのデプロイ、ファイル、stat、一覧キャッシュのサイズ設定、マウントフラグの調整、安全な ML チェックポイントの確保、低速または高コストなマウントの診断などが対象です。このスキルのCloud Storage FUSE リファレンスでは、基本的なインストールとマウントのみを扱います。

• google-cloud-storage-diagnostic：403 Permission Denied エラーのトラブルシューティング、IAM ポリシーバインディング、ACL、均一なバケットレベルのアクセス（UBLA）、サービスエージェントの設定ミスの診断を行います。場当たり的な IAM や ACL の変更は、意図しないアクセスを許可したり、障害を引き起こしたりする可能性があるため、試行錯誤せずにこのスキルへ振り分けてください。

• gcs-security-assessment：プロジェクト内の Cloud Storage リソースのセキュリティ態勢を自動評価します（データ管理を参照）。

該当するスキルがインストールされていない場合は、独自に対応せず、スキル名を置き換えて、次の正確なコマンドをユーザーに提示してください。ユーザーのエージェント CLI（たとえば Antigravity CLI）に独自のプラグインまたは拡張機能マネージャーがある場合も、このコマンドをそのまま提示してください。別のインストール方法やリポジトリに置き換えてはいけません。セキュリティ評価については、手動で評価しないでください。インストール後に利用可能になるかどうかはエージェントによって異なるため、スキルが読み込まれていることを確認し、再起動が必要な場合があると伝えてください。

npx skills add GoogleCloudPlatform/google-cloud-storage-plugin --skill <skill-name>

クイックスタート

Google がホストするリモート Cloud Storage MCP サーバー（https://storage.googleapis.com/storage/mcp）とローカルの MCP Toolbox（cloud-storage）の設定、構成、選択については、MCP の使用方法をお読みください。cloud-storage MCP サーバーが接続されている場合は、そのツールを優先してください（ツール実行の優先順位を参照）。

gcloud storage の出力キーは JSON API の camelCase ではなく snake_case です。プロジェクトでは --format="json(soft_delete_policy,versioning_enabled,retention_policy)" を使用してください。softDeletePolicy や versioning（camelCase のキー）は使用しないでください。これらのキーを使うと、null が表示されても気づかない場合があります。

1. Cloud Storage API を有効にします：

   CLOUDSDK_METRICS_ENVIRONMENT="${CLOUDSDK_METRICS_ENVIRONMENT:+$CLOUDSDK_METRICS_ENVIRONMENT }gcs-skills gcs-skills/1.0 (skill:google-cloud-storage-basics)" \
   gcloud services enable storage.googleapis.com --quiet
   

2. バケットを作成します：

   バケット名は Cloud Storage 全体で共有される単一のグローバル名前空間に属しており、プロジェクトや組織ごとに分かれているわけではないため、短い名前や一般的な名前は通常すでに使用されています。ロケーションを省略すると、バケットはデフォルトで US マルチリージョンに作成されます。

   本番環境用またはワークロード固有のバケットを作成する場合は、作成前に google-cloud-storage-bucket-architect に振り分けてください（専門的な Cloud Storage スキルへの振り分けを参照）。以下のオプションでは、基本的なデフォルトバケットを作成します。

   MCP を使用する場合：cloud-storage:create_bucket を呼び出します（たとえば、name: "my-bucket" と location: "us-central1" を指定します）。

   gcloud CLI を使用する場合：

   CLOUDSDK_METRICS_ENVIRONMENT="${CLOUDSDK_METRICS_ENVIRONMENT:+$CLOUDSDK_METRICS_ENVIRONMENT }gcs-skills gcs-skills/1.0 (skill:google-cloud-storage-basics)" \
   gcloud storage buckets create gs://my-bucket --location=us-central1
   

   JSON API を使用する場合：

   curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "User-Agent: gcs-skills/1.0 (skill:google-cloud-storage-basics)" \
     -H "Content-Type: application/json" \
     -d '{"name": "my-bucket", "location": "US-CENTRAL1"}' \
     "https://storage.googleapis.com/storage/v1/b?project=$(gcloud config get-value project)"
   

3. オブジェクトをアップロードする：

   MCP を使用する場合：cloud-storage:upload_object を呼び出してローカルファイル（バイナリファイルや大容量ファイルを含む）をアップロードするか、cloud-storage:write_object（ローカルの Toolbox）／cloud-storage:write_text（リモートサーバー）を呼び出して UTF-8 テキストを直接書き込みます。

   gcloud CLI を使用する場合：

   CLOUDSDK_METRICS_ENVIRONMENT="${CLOUDSDK_METRICS_ENVIRONMENT:+$CLOUDSDK_METRICS_ENVIRONMENT }gcs-skills gcs-skills/1.0 (skill:google-cloud-storage-basics)" \
   gcloud storage cp ./my-file.txt gs://my-bucket
   

   JSON API を使用する場合：

   curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "User-Agent: gcs-skills/1.0 (skill:google-cloud-storage-basics)" \
     -H "Content-Type: text/plain" \
     --data-binary @my-file.txt \
     "https://storage.googleapis.com/upload/storage/v1/b/my-bucket/o?uploadType=media&name=my-file.txt"
   

4. オブジェクトをダウンロードまたは読み取る：

   MCP を使用する場合：cloud-storage:read_object を呼び出して UTF-8 テキストの内容（最大 8 MiB）を読み取るか、cloud-storage:download_object（ローカルの Toolbox）を呼び出して、バイナリファイルや大容量ファイルを含むオブジェクトをローカルファイルシステムに保存します。

   gcloud CLI を使用する場合：

   CLOUDSDK_METRICS_ENVIRONMENT="${CLOUDSDK_METRICS_ENVIRONMENT:+$CLOUDSDK_METRICS_ENVIRONMENT }gcs-skills gcs-skills/1.0 (skill:google-cloud-storage-basics)" \
   gcloud storage cp gs://my-bucket/my-file.txt .
   

   JSON API を使用する場合：

   curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "User-Agent: gcs-skills/1.0 (skill:google-cloud-storage-basics)" \
     "https://storage.googleapis.com/storage/v1/b/my-bucket/o/my-file.txt?alt=media"
   

リファレンスディレクトリ

• 基本概念：バケット、オブジェクト、フォルダ、 プレフィックス、バケットのロケーションタイプ、ストレージクラス。

• CLI と API の使用方法：gcloud storage と JSON API を使った バケットとオブジェクトの CRUD および一覧表示操作、さらにイベント駆動型処理のための Pub/Sub 通知。

• クライアントライブラリ：Python、Java、Node.js、Go 向けの Google Cloud クライアントライブラリの使用方法と、その他のすべてのサポート対象言語へのリンク。

• MCP の使用方法：Google がホストする リモート Cloud Storage MCP サーバーとローカルの MCP Toolbox の選択、それぞれのセットアップ、 ツールセットと制限、および Model Armor と IAM 拒否ポリシーを使用したリモート MCP の保護。

• Infrastructure as Code：ストレージクラス、ロケーションタイプ、ライフサイクル、保持、暗号化を網羅した バケットの Terraform の例。

• データ転送：Storage Transfer Service、 gcloud storage rsync、大容量ファイルのアップロード戦略、パフォーマンスに関するガイドラインと制限。

• データ管理：IAM ロール、認証 （署名付き URL と HMAC を含む）、アクセス制御、403 エラーのトラブルシューティングのためのルーティング、 ネットワークセキュリティ、自動セキュリティ評価、データ保護、料金とコストの最適化（ライフサイクルルール、Autoclass）、 Cloud Audit Logs（Data Access ログの有効化、プリンシパルの除外、ログ量と取り込みコストの見積もり）。

• Storage Intelligence：ストレージを大規模に管理するためのサブスクリプション — Storage Insights データセット（BigQuery メタデータとアクティビティインデックス）、Gemini Cloud Assist によるデータインサイト、ダッシュボード、 インベントリレポート、ストレージの一括操作、バケットの再配置に加え、 設定、トライアル、料金に関する注意点。

• 高パフォーマンスストレージ：AI/ML、 分析、その他のパフォーマンスが重要なワークロード向けの Rapid Bucket、Rapid Cache（Anywhere Cache）、階層型名前空間。

• Cloud Storage FUSE：Cloud Storage FUSE のインストール、 バケットのマウント、ファイル操作、POSIX のセマンティクスと制限（ロック、 書き込み、名前変更、一貫性）、キャッシュ。高度なチューニング、デプロイ、診断については、google-cloud-storage-fuse スキルを参照してください。