Merge pull request #61 from microcmsio/auto-update-docs-20250901T031342

ドキュメントの更新を同期

Author: himaratsu

docs/manual/Amazon S3連携.md

@@ -0,0 +1,352 @@
+---
+contentId: amazon-s3-integration
+directory: manual
+---
+
+# Amazon S3連携
+
+Amazon S3連携とは、microCMSの管理画面からアップロードされた画像や動画といったメディアの保存先を、microCMSのデフォルトのストレージから、お客様が独自に用意したAmazon S3のバケットに切り替えられる機能です。  
+これにより、自社のポリシーに基づいたセキュリティ設定で適用できるようになるため、セキュリティ要件の高いプロジェクトでも安心してお使いいただけます。
+
+類似の機能に「[メディアのカスタムドメイン設定](/manual/custom-domain)」があります。この機能と今回ご説明する機能は、目的が異なりますのでご注意ください。  
+  
+**メディアのカスタムドメイン設定**
+
+*   アップロードしたメディアの**URL**に独自ドメインを設定する機能です。
+*   メディアの保存先はmicroCMS管理のストレージのままです。
+
+  
+**本機能（メディア保存先の切り替え）**
+
+*   メディアの**保存先そのもの**を、お客様が契約する外部ストレージなどに変更する機能です。
+
+Amazon S3連携は、Enterpriseプランのお客様にご利用いただける機能です。この機能は初期設定では無効になっていますので、ご希望される場合はお問い合わせください。  
+プランごとに利用できる機能については、[料金プランページ](https://microcms.io/pricing)をご覧ください。
+
+ご利用前の確認事項
+=========
+
+Amazon S3連携機能をご利用いただくにあたって、以下の条件が前提となります。**いずれも重要な内容になりますので、必ずご確認をお願いします。**  
+
+*   連携できるパブリッククラウドのストレージは、[**Amazon S3**](https://aws.amazon.com/jp/s3/)**のみ**となります。
+*   本機能を有効にすると、**画像の配信仕様が変更されるため、**[**画像API**](/image-api/introduction)**は使用できなくなります**。URLパラメータによる画像の最適化（リサイズや形式変換など）が必要な場合は、お客様ご自身でimgix等の外部サービスをご利用ください。
+*   本機能の設定は管理画面のみの操作で完結できません。事前に、**弊社と連携の上、お客様に関連するリソースをご用意いただく必要**があります。設定の詳細につきましては、まずはお問い合わせください。
+
+機能の詳細
+=====
+
+通常、管理画面にアップロードしたメディア（ファイル含む）はmicroCMSが管理するストレージに保管されます。Amazon S3連携機能によって、お客様が事前に用意したS3バケットに直接保存することができます。  
+そのため、アップロード後に割り当てられるメディアのURLも、お客様の事前の定義に従ったドメインとなります。  
+なお、本機能は画像以外のメディア（PDFなど）も保存の対象となります。
+
+### 設定前のURLの例
+
+#### 画像
+
+`https://images.microcms-assets.io/assets/xxxx/yyyy/image.png`
+
+#### ファイル
+
+`https://files.microcms-assets.io/assets/xxxx/yyyy/sample.pdf`  
+
+### 設定後のURLの例
+
+#### 画像
+
+`https://{バケット名}.s3.{リージョン名}.amazonaws.com/media/image.png`
+
+#### ファイル
+
+`https://{バケット名}.s3.{リージョン名}.amazonaws.com/media/sample.pdf`  
+  
+※お客様が自身で設定したバケット名やリージョン名が配信URLに含まれます。  
+※上記はカスタムドメイン設定を利用しない場合の例です。カスタムドメイン設定について、下記の「[microCMS管理画面での設定](/manual/amazon-s3-integration#ha62f8dfa73)」をご確認ください。
+
+microCMSのストレージでは、[メディアの形式によって配信されるドメインが異なり](/manual/media-management#h83761c8b1c)ますが、**本機能を有効にした後はドメインは統一されます。**
+
+アップロード時の挙動
+----------
+
+本機能が有効になっている場合、メディアのアップロード先は指定したお客様管理のS3バケットになります。  
+  
+なお、アップロード先のパスは `対象バケット/{URLプレフィクス}/{ファイル名}` となります。ファイル管理の目的で、メディアには以下のメタ情報も付与します。  
+
+*   `x-amz-meta-upload-source`: `"microcms"`
+*   `x-amz-meta-microcms-service`: `{内部サービスID（例: SERVICE#xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx）}`
+*   `x-amz-meta-microcms-version`: `{タイムスタンプ形式のバージョン（例: 20250812154922）}`
+*   `x-amz-meta-microcms-status`: `"public"`
+
+S3バケットにアップロードされたオブジェクト（メディア）には、Cache-Controlヘッダーが付与されないため、キャッシュはされません。  
+  
+配信されるメディアでキャッシュを利用したい場合は、CloudFront等のCDNとの連携をご検討ください。  
+なお、「[S3とCloudFront等のCDNを連携する場合の注意事項](/manual/amazon-s3-integration#h5430147a53)」もあわせてご確認ください。
+
+メディアのURL
+--------
+
+本機能有効後にアップロードされたメディアには、以下のURLでアクセスできるようになります。  
+`{カスタムドメイン}/{URLプレフィクス}/{ファイル名}`
+
+microCMSからデフォルトで配信される[メディアのURL](/manual/media-management#h83761c8b1c)は、ランダムな文字列が含まれているため、推測が困難で高いセキュリティを確保しています。
+
+しかし、本機能を有効にした後にアップロードされたメディアのURLには、**ランダムな文字列が追加されず、推測されやすい状態**となります。したがって、機密性の高いファイルを扱う際には、ファイル名に推測不可能な文字列を含めるなど、ご留意ください。
+
+メディアに対して可能な操作
+-------------
+
+本機能有効後にアップロードされたメディアについては、下記の操作が可能です。
+
+*   メディアの削除
+*   メディア名のリネーム（「URLの固定化」がOFFの場合のみ）
+*   メディアの再アップロード（「URLの固定化」がOFFの場合のみ）
+
+設定方法
+====
+
+設定の流れ
+-----
+
+大まかに、以下のような流れで設定を行います。  
+
+1.  設定に必要な各種リソースを準備する（S3バケット、IAMロールなど）
+2.  管理画面の「設定」>「外部連携」>「Amazon S3連携」にアクセスし、必要な設定項目を入力する
+3.  接続テストを実施する
+4.  接続テストに問題がなければ設定を反映する
+
+事前準備
+----
+
+下記に示す、AWS関連のリソースをご準備ください。
+
+各種リソースの設定について、ご不明点がございましたら弊社サポートまでお問い合わせください。
+
+### 1\. S3バケット（必須）
+
+メディアの保存先となるS3バケットを1つご準備ください。  
+なお、作成したバケットに対して、S3への操作権限を付与したバケットポリシーを設定してください。  
+
+#### バケットポリシーの例
+
+  
+**CloudFrontとS3を連携しない場合**
+
+    {
+        "Version": "2012-10-17",
+        "Statement": [
+            {
+                "Sid": "<任意>",
+                "Effect": "Allow",
+                "Principal": "*",
+                "Action": "s3:GetObject",
+                "Resource": "arn:aws:s3:::<バケット名>/<ディレクトリ名>/*"
+            }
+        ]
+    }
+
+  
+**CloudFrontをS3と連携する場合**
+
+    {
+        "Version": "2012-10-17",
+        "Statement": [
+            {
+                "Sid": "<任意>",
+                "Effect": "Allow",
+                "Principal": {
+                    "Service": "cloudfront.amazonaws.com"
+                },
+                "Action": "s3:GetObject",
+                "Resource": "arn:aws:s3:::<バケット名>/<ディレクトリ名>/*",
+                "Condition": {
+                    "ArnLike": {
+                        "AWS:SourceArn": "arn:aws:cloudfront::<アカウントID（12桁の数字）>:distribution/<CloudFrontのディストリビューションID>"
+                    }
+                }
+            }
+        ]
+    }
+
+  
+
+#### 注意事項
+
+*   「バケットタイプ」は「**汎用**」を選択してください。
+*   「オブジェクト所有者」は「**ACL無効**」を選択してください。
+
+  
+
+### 2\. IAMポリシー（必須）
+
+S3のバケットに対する各種操作の権限を付与したIAMポリシーを1つご準備ください。  
+
+#### IAMポリシーの例
+
+    {
+        "Version": "2012-10-17",
+        "Statement": [
+            {
+                "Sid": "<任意>",
+                "Effect": "Allow",
+                "Action": [
+                    "s3:GetBucketLocation",
+                    "s3:ListBucket"
+                ],
+                "Resource": "arn:aws:s3:::<バケット名>"
+            },
+            {
+                "Sid": "<任意>",
+                "Effect": "Allow",
+                "Action": [
+                    "s3:GetObject",
+                    "s3:PutObject",
+                    "s3:DeleteObject"
+                ],
+                "Resource": "arn:aws:s3:::<バケット名>/<ディレクトリ名>/*"
+            }
+        ]
+    }
+
+  
+
+### 3\. IAMロール（必須）
+
+microCMSからS3オブジェクト（メディア）を作成／変更／削除する際に割り当てるIAMロールを1つご準備ください。  
+作成したIAMロールに対し、上記で作成したIAMポリシーを付与してください。  
+
+#### 注意事項
+
+*   「信頼されたエンティティタイプ」は「**AWSアカウント**」を選択してください。
+*   「AWSアカウント」は「**別のAWSアカウント**」を選択してください。**「アカウントID」については、設定作業時にお客様に個別にご案内いたします。**
+*   オプションにて、**「外部IDを要求する」にチェックを入れ、任意の外部IDを設定してください。**
+
+  
+
+### 4\. CloudFrontディストリビューション（任意）
+
+S3バケット内のオブジェクトの配信にCloudFrontをご利用される場合、CloudFrontディストリビューションを1つご準備ください。  
+
+#### 注意事項
+
+*   ディストリビューション作成後、デプロイに時間がかかる場合があるので、完了したことを確認した後に、microCMS側の設定を行ってください。
+
+microCMS管理画面での設定
+----------------
+
+下記に示す設定値を入力してください。
+
+本機能を設定できるのは「管理者」権限を持つメンバーのみです。
+
+設定項目 （\*）は必須
+
+説明
+
+設定値の例
+
+**バケット名(\*)**
+
+アップロード先となるS3バケット名を入力してください。
+
+`alpha-prod-assets`
+
+**リージョン(\*)**
+
+バケットが存在するリージョンを選択してください。
+
+`ap-northeast-1`
+
+**IAMロールARN (\*)**
+
+事前に準備したIAMロールを入力してください。なお、AWSサービス内で一意に識別するための文字列で入力してください。
+
+`arn:aws:iam::123456789012:role/SampleRole`
+
+**外部ID (\*)**
+
+Assume Roleにあたって必要な条件キーを入力してください。
+
+（2~1224 文字、空白のない英数字。一部、記号も利用可）
+
+URLプレフィックス
+
+アップロード先となるディレクトリを入力してください。複数階層の指定が可能です。  
+設定しない場合はS3のルートにメディアが保存されます。
+
+`media`, `media/path`
+
+カスタムドメイン
+
+配信の際に使いたいドメインを入力してください。 設定しない場合は `{バケット名}.s3.{リージョン}.amazonaws.com` が配信時のドメインとして採用されます。
+
+`https://my-media.example.com`
+
+メディアのファイル名を固定する
+
+オンにした場合は同じファイル名でのみ再アップロードが可能となり、ファイル名の変更もできなくなります。
+
+OFF / ON
+
+メモ
+
+接続設定に関するメモを自由に入力することができます。
+
+（自由入力）
+
+制限／注意事項
+=======
+
+S3の設定やデータ管理に関する注意事項
+-------------------
+
+連携先S3の設定、およびバケット内のデータの管理・運用は、お客様の責任範囲となります。  
+**microCMSの管理画面やAPIを経由せずに行われたデータや設定の変更は、サポート対象外**となりますので、あらかじめご了承ください。
+
+**データ整合性に関するご注意**
+
+microCMSの管理画面やAPIを介さずにお客様が直接S3上のデータを操作（追加・変更・削除）されると、microCMS側の情報との間に不整合が生じ、メディアが正しく表示されないなどの予期せぬエラーの原因となる可能性があります。
+
+S3とCloudFront等のCDNを連携する場合の注意事項
+------------------------------
+
+S3とCloudFront等のCDNを連携し、キャッシュを利用されるケースにおいて、**microCMS管理画面内でメディアを削除しても、キャッシュデータが残り続けてしまう**場合があります。  
+  
+上記の対策としては、以下のような方法をご検討ください。
+
+1.  [メディアのWebhook](/manual/medium-webhook-setting)等を利用してメディアの削除を検知し、キャッシュを明示的に削除する
+2.  キャッシュのTTLを短く設定する
+
+1のケースについて、利用用途によっては画像のURLにパラメータが付与された状態でキャッシュされている場合があります。そのため、**キャッシュを削除する際はパスの末尾にワイルドカードを指定**していただきますようお願いいたします。
+
+すでにメディアが存在する場合の対応
+-----------------
+
+すでにメディアが存在する場合、**本機能が有効となった後にお客様管理の外部S3バケットにメディアが保存される**ようになります。  
+  
+なお、**お客様管理****の外部S3バケットにアップロードしたメディアが存在する場合、S3連携機能の設定変更および設定の削除はできません**。
+
+WRITE APIへの対応
+-------------
+
+### コンテンツAPI
+
+[POST](/content-api/post-content) / [PUT](/content-api/put-content) / [PATCH](/content-api/patch-content) リクエストにおける、URL指定によるメディアの登録には対応しています。
+
+### マネジメントAPI
+
+メディアの[POST](/management-api/post-media)および[DELETE](/management-api/delete-media-v2)リクエストには対応していません。
+
+複数環境での取り扱い
+----------
+
+[複数環境](/manual/environments)作成時、本機能の設定内容も初期設定としてコピーされます。  
+また、アップロード時の基本的な挙動との違いとして、アップロード先のパスは `対象バケット/{URLプレフィクス}/{複数環境のサービスIDを元にした固有の値}/{ファイル名}` となります。  
+  
+その他の仕様は以下の通りとなります。
+
+*   環境作成時、上記のディレクトリにメディアがコピーされます。
+*   環境削除時、上記のディレクトリのメディアがすべて削除されます。
+*   本番環境のS3連携設定と、複数環境（開発・ステージング）のS3連携設定は、どちらかの環境で設定を変更しても相互に影響することはありません。
+
+その他の注意点
+-------
+
+*   メディアの保存先がお客様管理の外部S3バケットとなるので、メディアデータの転送量やストレージ保存にかかる料金はお客様の負担となります（ただし、microCMSでのデータ転送量はかかりません）。