Content Transfer APIとItem Transfer APIを用いてSitecoreAI環境間でコンテンツを移行できます
このページの翻訳はAIによって自動的に行われました。可能な限り正確な翻訳を心掛けていますが、原文と異なる表現や解釈が含まれる場合があります。正確で公式な情報については、必ず英語の原文をご参照ください。
このウォークスルーでは、Content Transfer APIおよびItem Transfer APIを使って、あるSitecoreAI環境から別の環境へ コンテンツを移行 する方法を説明します。手順は移行を完了するために必要なすべてのステップをカバーしています:
同じ指示は、コンテンツ転送APIのMigrating contentセクションやアイテム転送API仕様書にも提供されています。これにより、OpenAPI仕様を直接消費するAIコーディングアシスタントやエージェントツールが、開発環境を離れることなく移行ワークフローを案内できます。
!注始める前に
- Organization AdminSitecore Cloud Portalでの役割やOrganization Owner役割を持っていることを確認してください。両方のAPIはこの役割を必要とします。
- SitecoreAI プロジェクト > > プロジェクト > 環境のオーサリング環境 > ホスト名 プロジェクトを デプロイ> プロジェクト 環境 ホスト 名 > で見つけてください。各APIリクエストの ベースURL を作成する際にホスト名を使用します。
- 両方の環境で自動化クライアントの認証情報を作成し、それぞれにJWTを生成します。命令については 、Content Transfer API および Item Transfer API の仕様を参照してください。
転送を作成する
ソース環境で以下のAPIリクエストを行います:
POST /sitecore/api/content/transfer/v1/transfers
選んだユニークなTransferId UUIDと、DataTreesに1つ以上のエントリを指定します。転送したいアイテムパスごとに1つのエントリーを使いましょう。各エントリーについて、次のように設定します:
- ItemPath - アイテムのSitecoreコンテンツパス。
- Scope - SingleItem を選択してアイテムのみを移す。 ItemAndDescendants を選択してアイテムとそのサブツリー全体を転送します。アイテムの親チェーンが宛先環境に存在し、同じアイテムIDを持つことを確認してください。もしそうでなければ、アイテムは正常に転送されますが、コンテンツツリーには表示されません。これを避けるために、共通の祖先から ItemAndDescendantsを使って譲渡するか、すべての親項目を先に譲渡してください。
- MergeStrategy - 宛先に既に存在するアイテムとの競合の処理方法。選択肢は以下の通りです:
- OverrideExistingItem - 既存のアイテムを移管されたバージョンに置き換える。
- KeepExistingItem - 既存のアイテムは変更せずに残すこと。
- OverrideExistingTree - 項目とそのすべての子孫を宛先から削除し、その後転送からすべての項目を書き込む。これは既存のアイテムを削除できる唯一のマージ戦略です。使用には注意してください。
例のリクエスト本文:
{ "TransferId": "12345678-1234-1234-1234-123456789abc", "Configuration": { "DataTrees": { "ItemPath": "/sitecore/content/Home", "Scope": "ItemAndDescendants", "MergeStrategy": "OverrideExistingItem" } , "Database": "master" } }
成功したリクエストは202 Accepted。
転送ができるまで待ちましょう
前の手順のTransferIdを使ってソース環境で以下のAPIリクエストを行ってください:
GET /sitecore/api/content/transfer/v1/transfers/{transferId}/status
このエンドポイントをCompletedStateまで調査します。StateがFailedされた場合、転送は成功せず、続行できません。この場合は新しい移転を作成します。応答にはChunkSetsMetadata配列が含まれています。各チャンクセットごとに、以下を記録します:
- ChunkSetId - チャンクセットの一意識別子で、以降のリクエストでパスパラメータとして使用されます。
- ChunkCount - 取得すべきチャンク数。チャンクは 0 から ChunkCount - 1まで番号付けされています。
チャンク転送
各チャンクごとに 、回収 と 保存 の手順を繰り返します。セット内のすべてのチャンクが保存されたら、チャン クセットを一度だけ完成 させます。
ソース環境からチャンクを取得する
ソース環境で以下のAPIリクエストを行います:
GET /sitecore/api/content/transfer/v1/transfers/{transferId}/chunksets/{chunksetId}/chunks/{chunkId}
チャンクごとに1つのリクエストを、chunkId値0ChunkCount - 1。応答体はバイナリストリームです。Content-DispositionレスポンスヘッダーのIsMedia値を覚えておいてください。次のステップで使います。
複数のチャンクを並列で取得できます。
チャンクを宛先環境に保存してください
宛先環境で以下のAPIリクエストを行ってください:
PUT /sitecore/api/content/transfer/v1/transfers/{transferId}/chunksets/{chunksetId}/chunks/{chunkId}
- セット Content-Type: application/octet-stream。
- isMediaクエリパラメータを前のステップのIsMedia値に設定します。
- 受信したままのバイナリストリームを転送します。データの解凍、復号、改変は避けてください。
成功したリクエストは201 Created。
チャンクは回収と並行して保存できますが、そのチャンクセットを完成させる前にセット内のすべてのチャンクを保存しなければなりません。
宛先環境でチャンクセットを完成させます
セット内のすべてのチャンクが保存された後、宛先環境で以下のAPIリクエストを行います。
POST /sitecore/api/content/transfer/v1/transfers/{transferId}/chunksets/{chunksetId}/complete
これにより宛先に .raifファイルが生成され、その名前が返されます:
{ "ContentTransferFileName": "content-transfer-12345678-1234-1234-1234-123456789abc.raif" }
このファイル名は後で使うので記録してください。
送信元の環境で転送を削除してください
ソース環境で以下のAPIリクエストを行います:
DELETE /sitecore/api/content/transfer/v1/transfers/{transferId}
これにより転送操作と関連するすべてのリソースがクリーンになります。ソース環境からすべてのチャンクをダウンロードした後、すぐにこれを行うことができます。
コンテンツを宛先データベースに読み込みます
移行を完了するには、宛先環境の アイテム転送APIを使って .raifファイルをデータベースに組み込みます。
ブロブが利用可能かどうか確認してください
.raifファイルを消費する前に、Azure Blob Storageで利用可能なかどうか、宛先環境で以下のAPIリクエストを行ってください。
GET /sources/blobs
レスポンスには利用可能なブロブソースとその状態が一覧化されています。前のステップで記録した .raifファイルはBlobStateのUploadedで表示されるはずで、これはファイルが消費可能であることを示しています。
ブロブを食べ始めろ
宛先環境で以下のAPIリクエストを行ってください:
POST /transfers/databases/{databaseName}/sources?blobName={ContentTransferFileName}
location応答ヘッダーにはURLが含まれています。このURLの最後のパスセグメントは、その後のリクエストで使用される転送IDです。
転送されたアイテムは、システムがバックグラウンドでデータベースへの同期を完了する間、宛先環境で即座に利用可能です。
転送を監視してください
アイテムはすぐに利用可能であっても、転送状態をポーリングして失敗を検出してください。もしバックグラウンド同期が完了する前に失敗した場合、まだ同期されていないアイテムは利用できなくなり、転送をやり直す必要があります。
宛先環境で以下のAPIリクエストを行い、FinishedTransferStateされるまでポーリングしてください:
GET /transfers/{transferId}
TransferStateがFailedなら、次のエンドポイントで転送を再試行します。
PUT /transfers/databases/{databaseName}/sources/{sourceName}
目的地の環境をきれいにする
転送が完了した後、宛先環境で以下のAPIリクエストを行います:
DELETE /sources/blobs/{blobName}
これにより .raifファイルが削除され、もはや不要になります。
転送されたアイテムは通常の出版ワークフローに従っています。
トラブルシューティング
TransferredWithErrorsの状態
BlobStateがTransferredWithErrorsなら、これは部分的な成功を示す終端状態です。調査するには、譲渡の詳細を取得してValidationErrorsリストを確認してください:
GET /transfers/{transferId}
コンテンツツリーには表示されないアイテムが転送されています
転送されたアイテムが宛先コンテンツツリーに現れない場合、最も可能性が高いのは、同じアイテムIDを持つ親チェーンが宛先環境に存在しないことです。これを解決するには、共通の祖先からScope: ItemAndDescendantsを使って転送するか、親項目を先に移してから子項目を移す方法があります。