Blog

APIの設計は、残りのコードの記述方法を劇的に形作ります。 Content Management APIを使用すると、既存のコンテンツなどをインポートできます。このAPIの設計がコードにどのように影響するかを見てみましょう。

開発者の観点からAPIを評価することは、トレッキングシューズを選ぶようなものです。彼らはかなり長い間立ち往生するので、彼らは快適であるほうがよいです、またはあなたはいくつかのひどい水ぶくれを求めています。 Kentico Cloudを使用している場合は、コンテンツをアプリにプルするために使用されるDeliveryAPIに精通している可能性があります。一方、コンテンツ管理API（または略してCM API）は、Kentico Cloudのソースデータを配信するだけでなく、直接変更することができます。現在、コンテンツの自動更新や2つのシステム間でのコンテンツの移行など、CMAPIを使用する必要がある場合が多くあります。今日は、古いCMSからKenticoCloudに既存のコンテンツをインポートすることに焦点を当てます。既存のコンテンツを移行すると、コンテンツの制作フローに不要な摩擦が生じ、プロジェクト全体が遅れる可能性があります。既存のコンテンツをインポートするときに優位に立つ方法については、以前のブログ投稿でビジネス面の詳細を読むことができます。

コンテンツの移行に関するいくつかの言葉

巨大なプロジェクトのために既存のコンテンツを移行していると想像してみてください。コンテンツアイテムやアセットはたくさんあり、すべてが密に相互に関連しています。一般的に、コンテンツの移行は次の4つの高レベルのステップに分けることができます。

• 新しいCMSでのコンテンツモデルの定義
• 利用可能なコンテンツの収集と改訂
• 新しいコンテンツモデルに従って古いコンテンツを再構築する
• コンテンツの移行

さて、割るのが最も難しいのはモデルの再組み立てです。コンテンツを新しいモデルに変換するときは、インポート後にすべてのリンクが正しく機能することを確認する必要があります。コンテンツは大規模に相互リンクでき、リンクはリッチテキスト内および構造化コンテンツ内に表示できます。

この問題の核心に迫り、解決策を見つけましょう。リンクを正常にインポートするには、注意が必要なことが2つあります。まず、後で参照として使用するために、リンクされたコンテンツまたはアセットのIDを知る必要があります。さらに、ほとんどのシステムはオブジェクトの存在に依存しています。したがって、2番目の問題は、オブジェクトをインポートする順序に影響します。リンク付きのコンテンツをインポートするときは、参照されているオブジェクトが以前にインポートされていることを確認する必要があります。

この記事の残りの部分では、CM APIを使用して、インポートプロセスを最適化し、上記の問題を解決する方法を説明します。 CM APIは、この短い記事で紹介できる以上のものを提供するため、開発者ハブにアクセスして、 CMAPIリファレンスで詳細情報を見つけることができます。

移行前の関係の再構築

それでは、一つ一つ問題に取り組んでいきましょう。最初の課題は、リンクを新しいモデルに変換するときにIDを把握することです。実際、ほとんどのシステムはIDがどのように見えるかを制御することに依存しているためです。これらのシステムは、IDの一意性と内部形状を保証する必要があります。移行する前に、古いシステムIDを知っています。それでも、モデル変換中に、すべての関係を組み立てるために新しいシステムIDを知る必要があります。当然、システムがIDの作成を制御できない場合、これは困難です。

今、私が見たほとんどの移行ツールは、IDマッピング辞書でこの問題を補っています。それらはオブジェクトIDのペアを格納し、古いシステムIDを新しいシステムIDにマッピングしました。ただし、APIでIDの作成をより細かく制御できる場合は、よりエレガントで実用的なソリューションがあります。

CM APIの最も優れた機能の1つは、外部ID（古いCMS-IDなど）を使用してコンテンツアイテムとアセットを作成および更新できることです。 Kentico Cloudは引き続き新しいIDを自動的に作成しますが、外部IDを使用してコンテンツを取得、リンク、または変更することができます。

それでは、CMAPIの動作を見てみましょう。次のリクエストは、KenticoCloudにコンテンツアイテムを作成します。ただし、外部IDを明示的に指定します。リクエストを再度実行すると、Kentico Cloudは指定された外部IDを持つコンテンツアイテムを見つけて更新します。したがって、コンテンツグラフをKentico Cloudモデルに再アセンブルするときに、追加のマッピングテーブルを保存する必要はありません。

 curl --request PUT \ --url https://manage.kenticocloud.com/projects/0aa7de3e-6e10-47fc-879e-1b70471cd8df/items/external-id/59713 \ --header 'Authorization: Bearer ' \ --header 'Content-type: application/json' \ --data '{ 'name': 'Using CM API is so straightforward', 'type': { 'codename': 'article' }, 'sitemap_locations': []}'

インポートされたコンテンツの注文

インポートスクリプトは古いシステムをスキャンし、すべてのコンテンツをスクレイプして新しいシステムに配置すると言うことができます。一方、後でインポートされるコンテンツを実行中にリンクしようとすると、状況が発生する可能性があります。実際、ほとんどのシステムは、リンクなど、操作しようとしたときに存在するコンテンツとアセットに依存しています。それでも、コンテンツをインポートする特定の順序を理解しようとする場合があります。ただし、コンテンツに循環参照が含まれている可能性があるため、存在しないオブジェクトを接続することはほとんど避けられません。関連記事では、この状況はあまりにも典型的です。

存在しないコンテンツのリンクを解決する1つの方法は、複数のフェーズでインポートを実行することです。まず、関係のないすべてのコンテンツとアセットをインポートします。次に、既存のすべてのコンテンツを読み直し、今回は関係を再構築します。

幸いなことに、システムがインポート中にオブジェクトの存在を必要としない場合、インポートはより簡単になります。さて、CMAPIはそれをカバーしました。コンテンツアイテムとアセットは、リンクとしてインポートする前に存在している必要はありません。代わりに、Kentico Cloudは、存在しないコンテンツまたはアセットへのリンクを作成します。これらは、すべての依存関係をインポートした後に自動的に機能します。したがって、既存のコンテンツを任意の順序でインポートできますが、最終的にはすべての関係とリンクが機能します。

記事を使ってデモンストレーションしましょう。リンクされたコンテンツの外部IDをリッチテキストおよびモジュラーコンテンツで指定することにより、記事とその中のすべてのリンクをインポートする方法は次のとおりです。

 curl --request PUT \ --url https://manage.kenticocloud.com/projects/0aa7de3e-6e10-47fc-879e-1b70471cd8df/items/external-id/5116/variants/00000000-0000-0000-0000-000000000000 \ --header 'Authorization: Bearer ' \ --header 'Content-type: application/json' \ --data '{ 'elements': { 'body': '
You can import related article in one go.
', 'related_articles': [ { 'external_id': '8723' } ] }}'

間違いの余地を残さない

私がすでにCMAPIについて書いたことから、KenticoCloudがどのように機能するかをよく知っている管理者と開発者のためのツールであるようです。これまで見てきたように、存在しないコンテンツへの参照を作成することもできます。ただし、自信を持っておく方法があります。インポート後にエラーをチェックできます。実際、CM APIは、プロジェクトの有効性をテストするための詳細なエラーメッセージとエンドポイントを提供します。

 { 'request_id': '8000549e-0002-af00-b63f-84710c7967bb', 'error_code': 5, 'message': 'The provided request body is invalid. See the 'validation_errors' attribute for more information and specify a valid JSON object.', 'validation_errors': [ { 'message': 'Invalid rich text value. Expected an opening tag of one of the supported elements, but got a text. Please see https://developer.kenticocloud.com/reference#content-management-api-rich-text-element.', 'path': 'elements.body', 'line': 1, 'position': 1 } ]}

検証エンドポイントを呼び出すと、プロジェクト内のすべてのコンテンツタイプ、コンテンツアイテム、およびアセットがスキャンされ、考えられるすべてのエラーが返されます。最も重要なことは、存在しないオブジェクトへのすべての参照を報告するだけでなく、モジュラーコンテンツ要素で許可されているコンテンツタイプなど、コンテンツタイプの制限を満たさないコンテンツアイテムについても警告します。

{ 'project': { 'id': '0aa7de3e-6e10-47fc-879e-1b70471cd8df', 'name': 'Sandbox' }, 'variant_issues': [ { 'item': { 'id': 'b48284b4-705e-5370-b30a-f7b7a240e00b', 'name': 'Using CM API is so straightforward', 'codename': 'using_cm_api_is_so_straightforward' }, 'language': { 'id': '00000000-0000-0000-0000-000000000000', 'name': 'English', 'codename': 'default' }, 'issues': [ { 'element': { 'id': '1b78fa7a-08b4-4ef7-abd7-79da5c47864e', 'name': 'Body', 'codename': 'body' }, 'messages': [ 'Element 'Body' contains a content link referencing a non-existent content item 7abbcbb8-2ac2-509d-b028-49cf8e299793.' ] }, { 'element': { 'id': 'defbf810-72d1-4b3a-837c-5d3f161e11c2', 'name': 'Related articles', 'codename': 'related_articles' }, 'messages': [ 'Element 'Related articles' references a non-existent content item 7abbcbb8-2ac2-509d-b028-49cf8e299793.' ] } ] } ]}

Kentico Cloudは、プロジェクト内のコンテンツとアセットを操作するための強力なコンテンツ管理APIを提供します。これは、コンテンツの関係を再構築したり、オブジェクトがインポートされる順序を指定したりするなど、開発者がインポートを作成する際に抱える一般的な問題を軽減するように設計されています。幸いなことに、CM APIは進化し続けており、コンテンツやアセットのインポート以上のことができるようになる、今後の機能にご期待ください。では、 今日サインインして試してみませんか？