1. スクリプティングSDK

スクリプティングSDKクライアント

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

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

スクリプティングSDKクライアントは、事前定義されたスクリプトと関数を提供することで、サービスまたはプラットフォームとの対話を簡素化できます。これにより、要求と応答の処理が容易になり、スクリプト内でサービスを統合して自動化できます。

Sitecore Content Hubは、次のクライアントを提供します。

財産

Assetsクライアントを使用すると、次の方法でFinalLifeCycleManagerを使用してアセットの最終的なライフサイクルステータスを管理できます。

  • ApproveAsync - アセットをapproved状態に移動します。

  • ArchiveAsync - アセットをarchived状態に移動します。

  • DirectPublishAsync - アセットをapproved状態に移動します。

  • RejectAsync - アセットをrejected状態に移行します (拒否の理由は省略可能です)。

  • RestoreAsync - アセットをapproved状態に移動します。

  • SubmitAsync - アセットをunderreview状態に移動します。

これらの方法では、既存のアセットのIDが必要です。指定されたIDがアセットエンティティのものでない場合、または現在の状態から要求された状態への遷移が許可されていない場合、クライアントはForbiddenExceptionをスローします。

たとえば、IDが1000のアセットを承認するには、次のようにします。

await MClient.Assets.FinalLifeCycleManager.ApproveAsync(1000);

さらに、最終的なライフサイクルステータスエンティティのエンティティIDを取得できます (これはenum定数またはステータス文字列値で機能します)。

long? id = await MClient.Assets.FinalLifeCycleManager.GetFinalLifeCycleStatusIdAsync(FinalLifeCycleStatus.StatusValues.Approved);

コマンド

Commandsクライアントを使用して、Content Hubに公開されているコマンドを実行できます。

Namespace

コマンド名

引数

external.action 

external.action 

new JObject(
    new JProperty("entity_id", <ENTITY_ID>),
    new JProperty("action_id", <ACTION_ID>),
    new JProperty("properties", new JArray()),
    new JProperty("relations", new JArray()),
    new JProperty("action_execution_source", "ExternalAction"),
    new JProperty("extra_data", new JObject())

m.security 

applyuserrole 

new JObject(
        new JProperty("user_id", <USER_ID>),
        new JProperty("role", <ROLE>),
        new JProperty("target_id",  <TARGET_ID>))

m.security

updateuserroles

new JObject(
	new JProperty("role",  <ROLE>),
	new JProperty("target_id", <TARGET_ID>),
	new JProperty("added_users", new JArray()),
	new JProperty("removed_users", new JArray())
	)

m.asset 

setmaster 

new JObject(
        new JProperty("new_master_id", <NEW_MASTER_ID>),
        new JProperty("entity_id", <ENTITY_ID>),
        new JProperty("master_relation", <MASTER_RELATION>))

m.security

removeuserole

using Newtonsoft.Json.Linq;

var args =new JObject(
    new JProperty("user_id", <long>),
    new JProperty("role", <string>),
    new JProperty("target_id", <long>));

await MClient.Commands.ExecuteCommandAsync("m.security", "removeuserrole",<ARGS>);

m.security

applyusergrouprole

using Newtonsoft.Json.Linq;

var args=new JObject(
    new JProperty("usergroup_id", <long>),
    new JProperty("role", <string>),
    new JProperty("target_id", <long>))

await MClient.Commands.ExecuteCommandAsync("m.security", "applyusergrouprole",<ARGS>);

stateflow

assign.stateflow

await MClient.Commands.ExecuteCommandAsync("automation","assign.stateflow", new JObject
{
    new JProperty("state_flow_id", 222),
    new JProperty("target_id", 111),
    new JProperty("initial_state_id", 555)
});

SDKを介して非同期コマンドを実行するには:

await MClient.Commands.ExecuteCommandAsync(<NAMESPACE>, <NAME>, <ARGS>);

文化

Cultureクライアントを使用して、Content Hubからカルチャ関連の情報を取得できます。

デフォルトのカルチャを取得するには:

CultureInfo defaultCulture = await MClient.Cultures.GetDefaultCultureAsync();

登録されているすべてのカルチャを取得するには:

IList CultureInfo cultures = await MClient.Cultures.GetAllCulturesAsync();

データソース

データ ソース クライアントを使用して、データ ソース (オプション リストとも呼ばれます) に対してCRUD操作を実行できます。

データ ソースを取得する

データソースは、次の名前で取得できます。

IDataSource result = await MClient.DataSources.GetAsync(<NAME>);

これはIDataSourceオブジェクトを返します。ただし、次のように正しいデータ ソースの種類にダウンキャストすることをお勧めします。

IHierarchicalDataSource hierachicalDataSource = await MClient.DataSources.GetAsync(name) as IHierarchicalDataSource;

これにより、データ ソースの値を変更できます。

IFlatDataSource flatDataSource = await MClient.DataSources.GetAsync(<NAME>) as IFlatDataSource;
メモ

IDataSourceTypeプロパティは、実行時に正しいデータ ソースの種類を識別します。

データ ソースの作成

階層型データ・ソースを作成するには、ファクトリーを使用してインスタンスを作成し、そのインスタンスをデータ・ソース・クライアントに保存します。

たとえば、メディアの種類に対してこれを行うと、各種類のメディアが複数のサブ値を持つことができます。

この例では、mp4がビデオ メディアの種類のサブタイプとして追加されます。

var dataSource = MClient.DataSourceFactory.CreateHierarchicalDataSource("MediaType");
dataSource.Labels.Add(enUs, "Media type");

var video = new HierarchicalDataSourceValue("Video")
{
  Labels = { { enUs, "Video" } }
};

var mp4 = new HierarchicalDataSourceValue("MP4")
{
  Labels = { { enUs, "mp4" } }
};
video.Values.Add(mp4);

var image = new HierarchicalDataSourceValue("Image")
{
  Labels = { { enUs, "Image" } }
};

dataSource.Values.Add(video);
dataSource.Values.Add(image);

await MClient.DataSources.CreateAsync(dataSource);

データ ソースを更新する

次の例では、フラット カラー データ ソースが赤で拡張されています。

var dataSource = await MClient.DataSources.GetAsync("Colors") as IFlatDataSource;

var red = new FlatDataSourceValue("Red")
{
  Labels = { { enUs, "Red" } }
};
dataSource.Values.Add(red);

await MClient.DataSources.UpdateAsync(dataSource);

データソースの削除

次の例では、MediaTypeデータ ソースが削除されます。

await MClient.DataSources.DeleteAsync("MediaType");

エンティティ

エンティティ クライアントを使用して、エンティティに対してCRUD操作を実行できます。

エンティティを取得する

次のメソッドは、IDでエンティティを取得します。

IEntity entity = await MClient.Entities.GetAsync(<ENTITY_ID>);

エンティティが存在しないか、ユーザーがエンティティを読み取る権限を持っていない場合、メソッドはnullを返します。

手記

エンティティをID、識別子、または定義で 読み込むための多くのオプションがあります 。読み込み設定の詳細については、読み込み設定の節を参照してください。

エンティティの作成

エンティティは、CreateAsyncメソッドでのみ作成できます。

次のコード スニペットでは、Assetエンティティがローカルに作成されます。

IEntity asset = await MClient.EntityFactory.CreateAsync("M.Asset");

次のコード スニペットでは、ローカルに作成されたAssetエンティティがサーバーに送信され、検証および永続化されます。

long id = await MClient.Entities.SaveAsync(asset);

返されるidは、新しく作成されたエンティティのIDです。このIDを使用して、サーバーからエンティティの最新バージョンを取得できます。

エンティティの更新

変更を加えた後、エンティティ クライアントでSaveAsyncメソッドを使用します。

long id = await MClient.Entities.SaveAsync(<ASSET>);

返されるidは、エンティティの同じIDです。このエンティティの最新バージョンを取得するには、IDを使用してサーバーから再度取得します。

エンティティの削除

エンティティは、DeleteAsyncメソッドとエンティティIDを使用して削除できます。

await MClient.Entities.DeleteAsync(<ENTITY_ID>);

エンティティ定義

エンティティ定義クライアントを使用して、エンティティ定義に対してCRUD操作を実行できます。

警告

細心の注意を払ってください。エンティティ定義を追加、削除、または削除すると、重大な結果を招く可能性があります。

エンティティ定義を取得する

エンティティ定義は、名前またはidで取得できます。

IEntityDefinition assetDefinition = await MClient.EntityDefinitions.GetAsync("M.Asset");
IEntityDefinition assetDefinition = await MClient.EntityDefinitions.GetAsync(<ASSET_DEFINITION_ID>);

エンティティ定義が存在しない場合、メソッドはnullを返します。

手記

エンティティ定義を取得するためのオーバーロードは他にも多数あります。名前をIDに、またはその逆に解決することもできます。完全な概要については、APIドキュメント を参照してください。

エンティティ定義の作成

SDKを使用すると、ファクトリを使用せずにエンティティ定義オブジェクトを直接作成できます。非常に単純なエンティティ定義は、次のように作成できます。

IEntityDefinition definition = new EntityDefinition
{
  Name = "M.Demo.Definition",
  DisplayTemplate = "{M.Demo.Definition.Name}"
};

var defaultGroup = new MemberGroup { Name = "Default" };
defaultGroup.MemberDefinitions.Add(new StringPropertyDefinition
{
  Name = "M.Demo.Definition.Name",
  IsUnique = true
});

definition.MemberGroups.Add(<DEFAULT_GROUP>);

long id = await MClient.EntityDefinitions.SaveAsync(<DEFINITION>);

返されるidは、新しく作成されたエンティティ定義のIDです。

手記

EntityDefinitionStylelabs.M.Sdk.Models.Baseからインポートでき、プロパティ メンバー定義はStylelabs.M.Sdk.Models.Base.PropertyDefinitionsからインポートできます。

エンティティ定義の更新

変更を加えた後、エンティティ定義クライアントでsaveメソッドを使用します。

long id = await MClient.EntityDefinitions.SaveAsync(<DEFINITION>);

これにより、更新されたエンティティ定義のIDが返されます。

エンティティ定義の削除

エンティティ定義は、名前またはidで削除できます。

await MClient.EntityDefinitions.DeleteAsync(<DEFINITION_ID>);
await MClient.EntityDefinitions.DeleteAsync("M.Demo.Definition");

レガシージョブクライアント

手記

従来のJobsクライアントは、今後非推奨になります。 エンティティ・クライアントからジョブ・クライアントに切り替え て、ジョブ・クライアントの使用を開始できます。

従来のジョブ クライアントを使用して、さまざまな種類のフェッチ ジョブを作成できます。

使用可能なフェッチ・ジョブ

フェッチ・ジョブ・モデルは、Stylelabs.M.Sdk.Models.Jobsにあります。

利用可能なモデルは次のとおりです。

  • AzureFetchJobRequest - Azure Blob Storageから1つ以上のファイルをフェッチします。

  • FileFetchJobRequest - Webサーバー上のディレクトリから1つ以上のファイルを取得します。

  • WebFetchJobRequest - HTTPまたはHTTPS経由で1つ以上のファイルをフェッチします。

フェッチ・ジョブを作成するときは、常に次の引数が必要です。

  • Description - ジョブの説明。

  • Asset id - フェッチされたファイルをリンクするアセット。

フェッチ ジョブを作成する

フェッチ・ジョブを作成するには、フェッチ・ジョブ・モデルをジョブ・クライアントのCreateFetchJobAsyncメソッドに渡します。これにより、新しく作成されたジョブのIDが返されます。

次の例では、公開URLから画像を取得し、ID 1000のアセットにリンクします。

var webFetchJob = new WebFetchJobRequest("Fetches an example image from the web.", 1000)
{
  Urls = new[] { "https://picsum.photos/200" }
};

long jobId = await MClient.Jobs.CreateFetchJobAsync(webFetchJob);

通知

通知クライアントを使用して、通知を管理および送信できます。

手記

次のコード例のclient変数は、IMClientインスタンスを参照します。Web SDKを使用する場合、変数名は自由に選択できますが、ドキュメントではインスタンス化時にclientとも呼ばれます。

メールテンプレート

電子メール テンプレート エンティティには、電子メールを送信するためのテンプレートが含まれています。変数は実行時に解決できます。

IMailTemplateEntityIEntityのサブタイプです。これは、M.Mailing.Templateエンティティ定義のメンバーにC#プロパティとメソッドを提供します。

これらの電子メール テンプレートを取得するために、クライアントはエンティティ クライアントでは使用できない追加のゲッターを提供します。これにより、メールテンプレートを名前で取得できます。ただし、IEntityに対するすべての操作は、引き続きIMailTemplateEntityに適用されます。 IMailTemplateEntityオブジェクトの保存と削除は、引き続きエンティティクライアントを介して行われます。

メール テンプレートを作成する

単純なhello worldテンプレートは次のようになります。

CultureInfo enUs = CultureInfo.GetCultureInfo("en-US");
var entity = await client.EntityFactory.CreateAsync(Constants.MailTemplate.DefinitionName);
var template = client.TypedEntityFactory.FromEntity <IMailTemplateEntity>(<ENTITY>);
template.Name = "Hello world template";
template.Subject[enUs] = "Hello there!";
template.Description[enUs] = "Hello";
template.Body[enUs] = "Hello {{Username}}!";
template.SetPropertyValue("M.Mailing.TemplateLabel", enUs, "Hello world template");

var templateVariable = new TemplateVariable
{
  Name = "Username",
  VariableType = TemplateVariableType.String
};
template.SetTemplateVariables(new[] { templateVariable });

await client.Entities.SaveAsync(<TEMPLATE>);

メール通知Send email notifications

メールは、ユーザー名、ユーザー ID、またはブロードキャストでユーザーに送信できます。次の入力を持つSendEmailNotificationAsyncには、それぞれ3つのオーバーロードがあります。

  • MailRequestById - IDによるユーザー指定のため

  • MailRequestByUsername - ユーザー名でユーザーを指定するため。

  • MailRequestBroadcast - すべてのユーザーに送信します。

メールブロードキャストは、テンプレートを使用して送信できます。

var request = new MailRequestBroadcast
{
  MailTemplateName = "Hello world template"
};
request.Variables.Add("Username", "world");

await client.Notifications.SendEmailNotificationAsync(<REQUEST>);

これにより、「Hello world!」を含むメールが全員に送信されます。

リアルタイム通知Send

リアルタイム通知は、ユーザー名、ユーザー ID、またはブロードキャストでユーザーに送信できます。次の入力を持つSendRealTimeNotificationAsyncには、それぞれ3つのオーバーロードがあります。

  • RealtimeRequestById - IDによるユーザー指定のため

  • RealtimeRequestByUsername - ユーザー名でユーザーを指定するため。

  • RealtimeRequestBroadcast - すべてのユーザーに送信します。

DemoUserに送信されるリアルタイム通知の例を次に示します。

var request = new RealtimeRequestByUsername()
{
  Title = "Your notification title",
  Link = new System.Uri("https://example.com")
};
request.Recipients.Add("DemoUser");
request.SetBody("Your description");
request.SetIcon("https://example.com/image.png");

await client.Notifications.SendRealTimeNotificationAsync(<REQUEST>);

ユーザーが通知をクリックすると、リンクが開きます。

このリアルタイム要求インターフェイスは、すべての通知情報を含むoptionsオブジェクトを使用する標準通知APIに基づいて構築されています。このオブジェクトは、IRealtimeRequest.Optionsプロパティから直接渡されます。このオプション オブジェクトの構成に役立つヘルパー メソッド (通知の本文やアイコンなど) がいくつか提供されています。

確認メールSend confirm emails

大事な

SendConfirmationEmailAsyncを機能させるには、設定でEnableConfirmationMailtrueに設定する必要があります。

ユーザーへの確認メールの送信は、IDまたはユーザー名を使用して行うことができます。

await client.Notifications.SendConfirmationEmailAsync("DemoUser");

これにより、指定したユーザーに、アカウントをアクティブ化するための安全なリンクが記載されたメールが送信されます。

Policiesクライアントを使用して、ポリシーの読み取りおよび更新操作を提供できます。これらのポリシーは、Content Hub内からのみ作成および削除できます。外部からは、取得または変更することしかできません。

ユーザー ポリシーを取得する

ユーザーのポリシーを取得するには、次のGetUserPolicyAsyncを使用します。

var policy = await MClient.Policies.GetUserPolicyAsync(<USER_ID>);

ユーザーグループポリシーを取得する

ユーザーグループのポリシーを取得するには、次のGetUserGroupPolicyAsyncを使用します。

var policy = await MClient.Policies.GetUserGroupPolicyAsync(<USERGROUP_ID>);

ポリシーの更新

ポリシーに変更を加えた後、次のように更新できます。

await MClient.Policies.UpdateAsync(<POLICY>);

クエリ

クエリクライアントを使用してクエリを実行できます。

警告

複数の項目がクエリに一致する場合は、InvalidOperationExceptionがスローされます。イテレータが設定された結果の最大数を超えると、サーバは例外をスローします。この場合、巻物が必要です。

手記

また、SearchAfterQueryクエリを使用して、Content Hub内の特定のエンティティを検索することもできます。

クエリを作成する

クエリクライアントを使用して クエリを作成し 、次のいずれかのクエリを実行したり、結果を反復処理したりできます。

クエリ結果の表示

クエリを実行すると、IQueryResultが返されます。この結果には、次のプロパティがあります。

  • Items - クエリに一致したエンティティまたはID (合計結果のサブセットにすることができます)。

  • TotalNumberOfResults - Sitecore Content Hubでクエリに一致したアイテムの数 (すべてがItemsにあるわけではない場合でも)。

  • Offset - スキップされた項目の数。

1つのエンティティのクエリ

クエリが1つのエンティティのみに一致することが確実な場合は、SingleAsyncメソッドを使用します。

IEntity entity = await MClient.Querying.SingleAsync(<QUERY>);

1つのエンティティIDのクエリ

クエリが1つのエンティティのみに一致することが確実な場合は、SingleIdAsyncメソッドを使用します。

long? entityId = await MClient.Querying.SingleIdAsync(<QUERY>);

1つ以上のエンティティのクエリ

1つ以上のエンティティをクエリするには:

IEntityQueryResult queryResult = await MClient.Querying.QueryAsync(<QUERY>);

IEntityQueryResult.Itemsには、返されたエンティティが含まれています。

1つ以上のエンティティIDのクエリ

1つ以上のエンティティIDをクエリするには:

IIdQueryResult queryResult = await MClient.Querying.QueryIdsAsync(<QUERY>);

IIdQueryResult.Itemsメソッドには、返されたID (long形式) が含まれます。

クエリ結果エンティティの反復処理

クエリが小規模から中規模の結果を返す場合 (既定の構成は最大10,000件の結果)、反復子を使用してエンティティを簡単にバッチ処理できます。

次のコード スニペットでは、反復子が作成されます。

IEntityIterator iterator = MClient.Querying.CreateEntityIterator(<QUERY>);

次のコード スニペットでは、イテレータを使用してエンティティをバッチ処理しています。

while (await iterator.MoveNextAsync())
{
  var entities = iterator.Current.Items;
  // Do something with the entities
}

whileループは、イテレータがエンティティのすべてのバッチの処理を完了すると自動的に終了します。

クエリ結果エンティティIDの反復処理

クエリが小規模から中規模の結果を返す場合 (既定の構成は最大10,000件の結果)、反復子を使用してエンティティIDを簡単にバッチ処理できます。

次のスニペットでは、反復子が作成されます。

IIdIterator iterator = MClient.Querying.CreateIdIterator(<QUERY>);

次のコード スニペットでは、反復子を使用してエンティティIDをバッチ処理します。

while (await iterator.MoveNextAsync())
{
  var ids = iterator.Current.Items;
  // Do something with the ids
}

whileループは、イテレータがエンティティのすべてのバッチの処理を完了すると自動的に終了します。

警告

イテレータが設定された結果の最大数を超えると、サーバは例外をスローします。その場合は巻物が必要です。

非推奨のメモ

Queryクラスでは、EntityLoadOptionsプロパティとLoadConfigurationプロパティを設定することができます。最初のプロパティは古いWebApiClient SDKで使用され、3.0で非推奨になりました。3.1では、Queryクラスと負荷構成が分離されました。これらのプロパティは使用せず、クエリ オブジェクトを渡すときに負荷構成を追加パラメーターとして渡すことをお勧めします (該当する場合)。

設定

設定クライアントを使用すると、設定を取得するための追加のユーティリティを提供できます。

設定は、クエリクライアントおよびエンティティクライアントで使用できるエンティティです。このクライアントは、手動で記述する必要がある一般的なクエリを提供するため、便利です。

カテゴリIDを取得する

次のスニペットの例は、PortalConfigurationカテゴリのIDを取得します。

long? id = await MClient.Settings.GetCategoryIdAsync("PortalConfiguration");

設定を取得する

次の例では、PortalConfigurationカテゴリからAuthenticationという設定を取得します。

IEntity setting = await MClient.Settings.GetSettingAsync("PortalConfiguration", "Authentication");
手記

エンティティのロード設定をクライアントに渡すことができます。

カテゴリのすべての設定を取得する

カテゴリのすべての設定を取得することもできます。たとえば、次のスニペットは、すべてのレンディション設定を取得します。

IList IEntity renditionSettings = await MClient.Settings.GetSettingsForCategoryAsync("Renditions");
手記

エンティティのロード設定を渡すことができます。

ユーザー

ユーザー・クライアントは、ユーザーおよびユーザー・グループを名前でフェッチするために使用できるほか、一部のパスワード管理操作も特徴としています。

ユーザーとユーザー・グループは、クエリ・クライアントおよびエンティティ・クライアントで使用できるエンティティです。

ユーザーを獲得する

GetUserAsyncメソッドは、ユーザー名でユーザーを取得します。

次の例では、superuserという名前のユーザー エンティティをフェッチします。

IEntity superuser = await MClient.Users.GetUserAsync("superuser");

ユーザーグループを取得する

GetUserGroupAsyncメソッドは、名前でユーザーグループを取得します。

次の例では、superusersという名前のユーザーグループエンティティをフェッチします。

IEntity superusersGroup = await MClient.Users.GetUserGroupAsync("superusers");
この記事を改善するための提案がある場合は、 お知らせください!