Sitecore.Services.クライアント

JavaScriptからItemServiceを使用する

Version:

日本語翻訳に関する免責事項

このページの翻訳はAIによって自動的に行われました。可能な限り正確な翻訳を心掛けていますが、原文と異なる表現や解釈が含まれる場合があります。正確で公式な情報については、必ず英語の原文をご参照ください。

ItemServiceは、Sitecoreアイテムを作成、フェッチ、保存、および削除するためのスタンドアロンのXHR (XMLHttpRequest) ライブラリです。フロントエンドとバックエンド間のデータトランザクションを支援するための多くの組み込みユーティリティとヘルパーがあります。ライブラリは /sitecore/shell/client/Services/Assets/lib/itemService.jsです。

メモ

多くの例では、Unit.jsの機能を使用しています。例をリテラルで実行する場合は、コードにUnit.jsへの参照を追加する必要があります。

このトピックでは、次の内容について説明します。

アイテムの作成

アイテムを作成するには、オブジェクトと、サーバーにアイテムを作成させるSitecoreツリー内のパスを渡してから、executeメソッドを呼び出します。

var peopleService = new ItemService( {
  url: "/sitecore/api/ssc/people"
} );
var aNewGuy = {
  name: "David",
  isActive: true,
  gender: "male"
};
peopleService.create( aNewGuy ).path( "/sitecore/content/home" ).execute().then( function ( david ) {
  david.should.be.an.instanceOf( ItemService.Item );
  david.name.should.eql( "David" );
  david.isActive.should.eql( true );
  david.gender.should.eql( "male" );
  done();
} ).fail( done );

ダーティアイテムを作成するには、executeメソッドを呼び出さないでください。

var peopleService = new ItemService( {
  url: "/sitecore/api/ssc/people"
} );
peopleService.create().then( function () {
  done();
} ).fail( done );

アイテムの取得

ItemIDでアイテムをフェッチするには、fetchItem() メソッドを使用します。

var peopleService = new ItemService( {
  url: "/sitecore/api/ssc/people"
} );
peopleService.fetchItem( "d4119c4f-31e9-4fd0-9fc4-6af1d6e36c8e" ).execute().then( function ( melton ) {
  melton.should.be.an.instanceOf( ItemService.Item );
  done();
} ).fail( done );

アイテムの子の取得

アイテムの子を取得するには、fetchChildren() メソッドを使用します。

var peopleService = new ItemService( {
  url: "/sitecore/api/ssc/people"
} );
peopleService.fetchItem( "d4119c4f-31e9-4fd0-9fc4-6af1d6e36c8e" ).execute().then( function ( melton ) {
  melton.should.be.an.instanceOf( ItemService.Item );
  melton.fetchChildren().execute().then( function ( meltonsChildren ) {
    meltonsChildren.should.be.an.Array.and.have.a.lengthOf( 3 );
    meltonsChildren[ 0 ].should.be.an.instanceOf( ItemService.Item );
    meltonsChildren[ 1 ].should.be.an.instanceOf( ItemService.Item );
    meltonsChildren[ 2 ].should.be.an.instanceOf( ItemService.Item );
    done();
  } ).fail( done );
} ).fail( done );

アイテムの保存

アイテムを保存する前に、アイテムをフェッチまたは作成する必要があります。

var peopleService = new ItemService( {
  url: "/sitecore/api/ssc/people"
} );
peopleService.fetchItem( "d4119c4f-31e9-4fd0-9fc4-6af1d6e36c8e" ).execute().then( function ( melton ) {
  melton.should.be.an.instanceOf( ItemService.Item );
  melton.name = "Melton the Magnificent";
  melton.save().execute().then( function ( savedMelton ) {
    savedMelton.name.should.eql( "Melton the Magnificent" );
    done();
  } ).fail( done );
} ).fail( done );

アイテムの破壊

アイテムを破棄する前に、アイテムをフェッチまたは作成する必要があります。

var peopleService = new ItemService( {
  url: "/sitecore/api/ssc/people"
} );
peopleService.fetchItem( "d4119c4f-31e9-4fd0-9fc4-6af1d6e36c8e" ).execute().then( function ( melton ) {
  melton.should.be.an.instanceOf( ItemService.Item );
  melton.destroy().execute().then( function () {
    done();
  } ).fail( done );
} ).fail( done );

アイテムの検索

アイテムを検索するには、検索を使用する方法とクエリを使用する方法の2つがあります。

search() の使用

項目を検索するには、検索語を渡してからexecuteメソッドを呼び出します。

var peopleService = new ItemService( {
  url: "/sitecore/api/ssc/people"
} );
peopleService.search( "melton" ).execute().then( function ( queryResults ) {
  queryResults.should.have.a.property( "Links" ).and.be.an.Array;
  queryResults.should.have.a.property( "Results" ).and.be.an.Array;
  queryResults.should.have.a.property( "TotalCount" ).and.be.a.Number;
  queryResults.should.have.a.property( "TotalPage" ).and.be.a.Number;
  queryResults.Results[ 0 ].should.be.an.instanceOf( ItemService.Item );
  queryResults.Results[ 0 ].name.should.eql( "Banks Melton" );
  done();
} ).fail( done );

query() の使用

アイテムをクエリするには、クエリ項目を渡してからexecuteメソッドを呼び出します。

var peopleService = new ItemService( {
  url: "/sitecore/api/ssc/people"
} );
peopleService.query(( "xxxx-xxxx-xxxx-xxxx" ).execute().then( function ( queryResults ) {
  queryResults.should.have.a.property( "Links" ).and.be.an.Array;
  queryResults.should.have.a.property( "Results" ).and.be.an.Array;
  queryResults.should.have.a.property( "TotalCount" ).and.be.a.Number;
  queryResults.should.have.a.property( "TotalPage" ).and.be.a.Number;
  queryResults.Results[ 0 ].should.be.an.instanceOf( ItemService.Item );
  done();
} ).fail( done );

「xxxx-xxxx-xxxx-xxxx」は、クエリアイテムのSitecore IDです。

ダーティアイテムの作成

ダーティアイテムとは、ブラウザのメモリにのみ存在し、サーバーに保存されていないアイテムです。これは、アプリケーションがユーザー入力を待つ必要がある場合に便利です。次のコードを使用して、ダーティアイテムを作成します。

var peopleService = new ItemService( {  
    url: "/sitecore/api/ssc/people"
} );
peopleService.create().then( function ( aNewDirtyItem ) {
  /* At this point `aNewDirtyItem` has not been saved */
  aNewDirtyItem.should.be.an.instanceOf( ItemService.Item );
  aNewDirtyItem.name = "Melton";
  /* After modifying the dirty item, now we save it */
  aNewDirtyItem.save().execute().then( function () {
    done();
  } ).fail( done );
} ).fail( done );

アイテムが汚れていないか確認する

アイテムが保存されていないかどうか (「ダーティアイテム」である) は、isNewプロパティで確認できます。

var peopleService = new ItemService( {
  url: "/sitecore/api/ssc/people"
} );
peopleService.create().then( function ( guy ) {
  guy.isNew.should.be.true;
  done();
} ).fail( done );

アイテムがサーバーから来るとき、isNewは常にfalseです。

var peopleService = new ItemService( {
  url: "/sitecore/api/ssc/people"
} );
peopleService.create( {
  name: "guy"
} ).execute().then( function ( guy ) {
  guy.isNew.should.be.false;
  done();
} ).fail( done );

アイテムを生のJSONとして取得する

アイテムのデータを生のJSONとして取得する必要がある場合があります(追加のメソッドとプロパティをすべて使用しないでください)。次のコードを使用して、アイテムを生のJSONとして取得します。

var peopleService = new ItemService( {
  url: "/sitecore/api/ssc/people"
} );
peopleService.fetchItem( "d4119c4f-31e9-4fd0-9fc4-6af1d6e36c8e" ).execute().then( function ( melton ) {
  var meltonAsJSON = melton.json();
  melton.should.be.an.instanceOf( ItemService.Item );
  meltonAsJSON.should.be.an.instanceOf( Object );
  meltonAsJSON.should.not.be.an.instanceOf( ItemService.Item );
  done();
} ).fail( done );

追跡アイテム

アイテムに追跡を追加できます。これにより、次の機能を追加できます。

アイテムは、プロパティが変更されたときに自動的に保存できます。
hasChanged() を呼び出して、アイテムが変更されたかどうかを確認できます。
revertChanges() を呼び出して、プロパティ値を元に戻すことができます。

追跡可能なオプションをtrueに設定して、アイテムに追跡を追加します。

var peopleService = new ItemService( {
  url: "/sitecore/api/ssc/people"
} );
peopleService.fetchItem( "d4119c4f-31e9-4fd0-9fc4-6af1d6e36c8e" ).option( "trackable", true ).execute().then( function ( melton ) {
  melton.option( "trackable" ).should.be.true;
  done();
} ).fail( done );

アイテムの自動保存

Sitecore.Services.Clientがアイテムへの変更を自動的に保存するように指定できます。 trackableをtrueに設定すると、この機能がオンになります。保存イベントは、エミッタの「on」または「once」を使用してリッスンできます。

var peopleService = new ItemService( {
  url: "/sitecore/api/ssc/people"
} );
peopleService.fetchItem( "d4119c4f-31e9-4fd0-9fc4-6af1d6e36c8e" ).option( "trackable", true ).execute().then( function ( melton ) {
  /* Listening to the `save` event `once`. You can also use `on` here to continuously listen to the `save` event. */
  melton.once( "save", function ( error ) {
    done();
  } );
  melton.name = "Melton the Magnificent";
} ).fail( done );

hasChanged() メソッド

ItemServiceでhasChanged() メソッドを追加するように指定するには、trackableをtrueに設定します。hasChanged()メソッドを使用して、アイテムが変更されたかどうかを確認します。

var peopleService = new ItemService( {
  url: "/sitecore/api/ssc/people"
} );
peopleService.fetchItem( "d4119c4f-31e9-4fd0-9fc4-6af1d6e36c8e" ).option( "trackable", true ).execute().then( function ( melton ) {
  melton.hasChanged().should.be.false;
  melton.name = "Melton the Magnificent";
  melton.hasChanged().should.be.true;
  done();
} ).fail( done );

hasChangedメソッドは、値がnull、undefined、および '' (空の文字列) の間で変更された場合、trueを返しません。

var peopleService = new ItemService( {
  url: "/sitecore/api/ssc/people"
} );
peopleService.fetchItem( "d4119c4f-31e9-4fd0-9fc4-6af1d6e36c8e" ).option( "trackable", true ).execute().then( function ( melton ) {
  melton.hasChanged().should.be.false;
  melton.subscribed = "";
  melton.hasChanged().should.be.false;
  melton.subscribed = null;
  melton.hasChanged().should.be.false;
  melton.subscribed = undefined;
  melton.hasChanged().should.be.false;
  done();
} ).fail( done );

revertChanges() メソッド

ItemServiceがtrack ableをtrueに設定することで、revertChanges()メソッドを追加するように指定できます。revertChanges()メソッドを使用して、アイテムの変更を元に戻します。

var peopleService = new ItemService( {
  url: "/sitecore/api/ssc/people"
} );
peopleService.fetchItem( "d4119c4f-31e9-4fd0-9fc4-6af1d6e36c8e" ).option( "trackable", true ).execute().then( function ( melton ) {
  melton.name.should.eql( "Banks Melton" );
  melton.name = "Melton the Magnificent";
  melton.name.should.eql( "Melton the Magnificent" );
  melton.hasChanged().should.be.true;
  melton.revertChanges();
  melton.hasChanged().should.be.false;
  melton.name.should.eql( "Banks Melton" );
  done();
} ).fail( done );

Queryオブジェクト

各ItemServiceメソッドはクエリオブジェクトを返します。

var peopleService = new ItemService( {
  url: "/sitecore/api/ssc/people"
} );
peopleService.create( {} ).should.be.an.instanceOf( ItemService.Query );
peopleService.fetchItem( "d4119c4f-31e9-4fd0-9fc4-6af1d6e36c8e" ).should.be.an.instanceOf( ItemService.Query );
peopleService.query( "/sitecore" ).should.be.an.instanceOf( ItemService.Query );
peopleService.search( "sitecore" ).should.be.an.instanceOf( ItemService.Query );
The query object has chainable helper methods. These methods add the given value to the query string of the request:
var peopleService = new ItemService( {
  url: "/sitecore/api/ssc/people"
} );
peopleService.create( {} )
  .database( "master" )
  .facet( "a facet" )
  .fields( "ItemName" )
  .includeMetadata( true )
  .includeStandardTemplateFields( true )
  .language( "en" )
  .page( 2 )
  .path( "/sitecore/content/home" )
  .sort( "aItemName" )
  .take( 5 )
  .version( "latest" )
  .should.be.an.instanceOf( ItemService.Query );
You call the execute() method to run the query. The execute() method returns a promise:
var peopleService = new ItemService( {
  url: "/sitecore/api/ssc/people"
} );
peopleService.fetchItem( "d4119c4f-31e9-4fd0-9fc4-6af1d6e36c8e" ).execute().then( function ( melton ) {
  melton.should.be.an.instanceOf( ItemService.Item );
  done();
} ).fail( done );

promiseの処理

ほとんどすべての非同期呼び出しはpromiseを返します。具体的には、execute() メソッドはpromiseを返します。 ItemServiceはqモジュールを使用してこれを処理します。

var peopleService = new ItemService( {
  url: "/sitecore/api/ssc/people"
} );
var fetchQuery = peopleService.fetchItem( "d4119c4f-31e9-4fd0-9fc4-6af1d6e36c8e" );
var fetchQueryPromise = fetchQuery.execute();
fetchQueryPromise.should.have.a.property( "then" );
fetchQueryPromise.should.have.a.property( "fail" );

ミドルウェアの操作

このItemServiceは、sc-useifyモジュールを使用してミドルウェア機能を提供します。

ItemService.use( function ( data, next ) {
  data.timestamp = new Date().getTime();
  next( null, data );
} );

ミドルウェアを統合した場合、次にサーバーからデータを受信するときに、このデータにはタイムスタンププロパティがあります。

var peopleService = new ItemService( {
  url: "/sitecore/api/ssc/people"
} );
peopleService.fetchItem( "d4119c4f-31e9-4fd0-9fc4-6af1d6e36c8e" ).execute().then( function ( melton ) {
  melton.should.have.a.property( "timestamp" );
  done();
} ).fail( done );

すべてのミドルウェアワーカーをクリアできます(またはキーでクリアできます)。

ItemService.useify.clear();

すべてのミドルウェアをクリアしたため、次にサーバーからデータを受信したときには、データにタイムスタンププロパティがありません。

var peopleService = new ItemService( {
  url: "/sitecore/api/ssc/people"
} );
peopleService.fetchItem( "d4119c4f-31e9-4fd0-9fc4-6af1d6e36c8e" ).execute().then( function ( melton ) {
  melton.should.have.not.a.property( "timestamp" );
  done();
} ).fail( done );

イベントエミッターの操作

イベントエミッターを使用してアイテムを拡張できます。

var peopleService = new ItemService( {
  url: "/sitecore/api/ssc/people"
} );
peopleService.fetchItem( "d4119c4f-31e9-4fd0-9fc4-6af1d6e36c8e" ).execute().then( function ( melton ) {
  melton.on( "save", function ( error ) {
    done();
  } );
  melton.age = 40;
  melton.save().execute();
} ).fail( done );

ItemServiceと検証

ItemServiceでは、クライアント側の検証は提供されません。次の例では、アイテムのIDを無効なGUIDに変更し、保存をトリガーします。クライアントは、検証が行われないため、保存の実行を許可します。ただし、サーバーが無効なデータを含むリクエストを受け取った場合、リクエストは解決されず、promiseは失敗します。

var peopleService = new ItemService( {
  url: "/sitecore/api/ssc/people"
} );
peopleService.fetchItem( "d4119c4f-31e9-4fd0-9fc4-6af1d6e36c8e" ).execute().then( function ( melton ) {
  melton.ItemID = "invalid guid";
  melton.save().execute().then( function ( badMelton ) {
    should( badMelton ).not.exist;
  } ).fail( function ( error ) {
    error.should.be.an.instanceOf( Error );
    done();
  } );
} ).fail( done );

この記事を改善するための提案がある場合は、お知らせください!