日時属性の動作と形式

 

公開日: 2017年1月

対象: Dynamics 365 (online)、Dynamics 365 (on-premises)、Dynamics CRM 2016、Dynamics CRM Online

世界中にユーザーと事務所がある場合、複数のタイム ゾーンで日付と時刻の値を適切に表現することが重要です。DateTimeAttributeMetadata クラスを使用して、Dynamics 365 で DateTime 属性の種類を定義および管理します。DateTimeAttributeMetadata.DateTimeBehavior プロパティを使用して、日付と時刻の値をタイムゾーン情報を付けて格納するか、付けないで格納するかを定義し、DateTimeAttributeMetadata.Format プロパティを使用してこれらの属性の表示形式を指定します。

また、Dynamics 365 のカスタマイズ領域を使用して、日時属性の動作と形式を定義します。詳細:TechNet: 日時フィールドの動作と形式

注意

DateTimeAttributeMetadata。DateTimeBehaviorプロパティは、Microsoft Dynamics CRM Online 2015 更新プログラム 1 または Microsoft Dynamics 365 (設置型) を使用している場合にのみ、使用可能です。 また、CRM Online 2015 更新プログラム 1 および Dynamics 365 のすべての日時属性は、現在は、1/1/1753 12:00 AM という早期の値もサポートします。

CRM Online 2015 更新プログラム 1 および Dynamics 365 (設置型) より前の Dynamics 365 バージョンの場合は、日時値の動作を定義できません。 既定では、日時値は、このトピックで後述されるように、UserLocal の動作として保存されます。

このトピックの内容

日時属性の動作の指定

日時属性の形式の指定

[日付のみ] の動作でサポートされない日付および時刻のクエリ演算子

日時属性の動作の変更

データベース内の既存の日時値の動作の変換

日時属性の動作の指定

DateTimeBehavior クラスを使用して、DateTimeAttributeMetadata.DateTimeBehavior プロパティの値を指定できます。DateTimeBehavior クラスには次のメンバーが含まれます; 各メンバーは、メンバー名と同じ値の文字列を返します:

メンバーの名前および値	説明
UserLocal	日時値を UTC 値としてシステムに格納します。 取得操作によって UTC 値が返されます。 更新操作は UTC 値を現在のユーザーのタイム ゾーン値に変換し、更新に対して指定された値の種類 (DateTimeKind) 基づいて、更新された値をそのまま、あるいは同等の UTC 値として格納します。 指定された値の種類が UTC の場合は、そのまま格納されます。 そうでない場合は、UTC 相当値が格納されます。 書式設定された値を取得すると、UTC から、ユーザーのタイム ゾーンとロケールの設定に基づいて、ユーザーの現在のタイム ゾーンを変換されます。 OData エンドポイントの場合、属性は DateTimeOffset として公開されます。 この動作は、CreatedOn および ModifiedOn のようなシステム属性に対して使用され、変更することはできません。 日時値をタイム ゾーン情報を付けて格納するユーザー定義属性の動作に対して、これを使用します。
DateOnly	実際値の日付の値を、時刻値 12:00 AM (00:00:00) で、システムに格納します。 取得と更新操作の場合は、タイム ゾーンの変換は行われず、時刻値はつねに 12 AM (00:00:00) となります。 書式設定された値を取得すると、タイム ゾーンの変換なしで、日付値が表示されます。 OData エンドポイントの場合、属性は DateTimeOffset として公開されます。 この動作は、時刻情報が必要とされない生年月日や記念日を格納する、ユーザー定義属性に対して使用します。
TimeZoneIndependent	ユーザーのタイムゾーンに関係なく、実際の日時値をシステムに格納します。 取得および更新操作の場合、タイム ゾーンの変換は行われません、実際の日付と時刻の値が返されて、ユーザーのタイム ゾーンに関係なく、システム内でそれぞれ更新されます。 書式設定された値を取得すると、現在のユーザーのタイム ゾーンとロケールの設定で指定された形式に基づいて、日付と時刻の値が (タイム ゾーンの変換なしで) 表示されます。 OData エンドポイントの場合、属性は DateTimeOffset として公開されます。 この動作は、ホテルのチェックインおよびチェック アウトの時間などの情報を格納する属性に対して使用されます。

次のサンプル コードは、新しい日時属性の UserLocal 動作の設定方法を示しています。

// Create a date time attribute for the Account entity
// with the UserLocal behavior
dtAttribute = new DateTimeAttributeMetadata
{                             
    SchemaName = "new_SampleDateTimeAttribute",
    DisplayName = new Label("Sample Date Time Attribute", _languageCode),
    RequiredLevel = new AttributeRequiredLevelManagedProperty(AttributeRequiredLevel.None),                
    Description = new Label("Created by SDK Sample", _languageCode),                
    DateTimeBehavior = DateTimeBehavior.UserLocal,
    Format = DateTimeFormat.DateAndTime,
    ImeMode = ImeMode.Disabled
};

CreateAttributeRequest createAttributeRequest = new CreateAttributeRequest
{
    EntityName = Account.EntityLogicalName,
    Attribute = dtAttribute
};
_serviceProxy.Execute(createAttributeRequest);
Console.WriteLine("Created attribute '{0}' with UserLocal behavior\nfor the Account entity.\n", 
                            dtAttribute.SchemaName);

このサンプル コードでは、文字列値 DateTimeBehavior = "UserLocal" を直接指定することによって、 DateTimeBehavior プロパティの値を設定することもできます。

日時属性の作成時に、動作を指定しない場合、既定で、属性は UserLocal 動作で作成されます。 完全なサンプル コードについては、「サンプル: 日時の動作の変換」を参照してください。

重要

• 動作を DateOnly または TimeZoneIndependent に設定した状態で、日時属性を作成すると、属性の動作は変更できません。詳細:日時属性の動作の変更

• 動作が DateOnly または TimeZoneIndependent の日時属性は、Outlook 用 Dynamics 365 の以前のバージョンでオフライン モードで編集すると、UserLocal 動作を使用しているかのように処理されます。 これは、このクライアントが新しい動作を認識せず、その動作を UserLocal (CRM Online 2015 更新プログラム 1 または Dynamics 365 (設置型) より前の Dynamics 365 バージョンでの既存の動作) と区別して処理しないことによります。 日時属性はアップグレードで新しい動作に変換されません。したがって、ベスト プラクティスは、カスタマイザーが新しい動作のいずれかを採用する前に、すべての Outlook 用 Dynamics 365 クライアントを最新のリリースにアップグレードすることです。 オンライン時には、フィールドのデータを新しい行動で編集しても問題なく動作します。

  Outlook 用 Dynamics 365 の旧クライアントも、1900 年 1 月 1 日 (CRM Online 2015 更新プログラム 1 と Dynamics 365 (設置型) よりも前のバージョンの Dynamics 365 で、日時の種類に対してサポートされる最早値) よりも前の日付を認識しません。 オフライン時には、1900 年 1 月 1 日よりも古い日付のレコードを、ユーザーは開くことはできません。 ただし、オンライン時には、すべてがうまく機能します。 オフライン モードでも、1753 年 1 月 1 日午前 12:00 まで古い日付の属性を操作する場合は、最新の Outlook 用 Dynamics 365 クライアントのバージョンにアップグレードする必要があります。

• ユーザー定義コードを使用して Dynamics 365 インスタンスに日時の動作を実装する場合、そのコードは、CRM Online 2015 更新プログラム 1 および Dynamics 365 (設置型) では、新しい動作機能が原因で、期待どおりに機能しないことがあります。

日時属性の形式の指定

DateTimeAttributeMetadata.Format プロパティを使用して、属性がシステムにどのように保存されているかに関係なく、属性の日付/時刻の表示形式を指定します。DateTimeFormat 列挙体を使用して、DateAndTime または DateOnly のいずれかの表示形式を指定できます。

DateTimeBehavior プロパティが DateOnly に設定されている場合、Format プロパティの値を DateAndTime に設定または変更することはできません。

[日付のみ] の動作でサポートされない日付および時刻のクエリ演算子

時刻関連のクエリ演算子は、DateOnly 動作に対してはサポートされません。 ここに表示されている時間固有のクエリ演算子を除いて、すべてのクエリ演算子がサポートされます。

• が X 分よりも古い

• が X 時間よりも古い

• が過去 X 時間

• が今後 X 時間

詳細:FetchXML の会計日クエリ演算子および "older than" 日付/時刻クエリ演算子

日時属性の動作の変更

Dynamics 365 インスタンスでシステム カスタマイザー ロールを所有していて、日時属性の CanChangeDateTimeBehavior 管理プロパティが True に設定されている場合、日時属性を更新してその動作を変更できます。

注意事項

日時属性の動作を変更するには、その前に、業務ルール、ワークフロー、計算フィールド、またはロールアップ属性などの属性のすべての依存性を検討して、動作の変更によって問題が発生しないことを確認する必要があります。 システム カスタマイザは、CanChangeDateTimeBehavior マネージド プロパティを使用して、既存の日時属性の動作の変更を制限できます。

少なくとも、日時属性の動作を変更した後、変更した日時属性に依存する、業務ルール、ワークフロー、計算属性、およびロールアップ属性の各レコードを開いて、情報を確認し、そのレコードを保存して、最新の属性の動作と値が使用されることを確認する必要があります。

計算属性またはロールアップ属性の日時動作の変更後、計算フィールドまたはロールアップ フィールドの定義エディターを開いて、そのフィールド定義を保存して、動作の変更後、それらの属性が引き続き有効であることを確認します。 システム カスタマイザでは、Dynamics 365 のカスタマイズ領域の [フィールドの種類] の横にある [編集] をクリックして、計算属性またはロールアップ属性に対するフィールド定義エディターを開くことができます。詳細:計算フィールドの定義 および ロールアップ フィールドの定義

• 標準のエンティティとユーザー定義エンティティの CreatedOn および ModifiedOn 属性の動作は、既定では、UserLocal に設定され、CanChangeDateTimeBehavior 管理プロパティは False に設定されます。このことは、これらの属性の動作は変更できないことを意味します。 ユーザー定義エンティティのこれらの属性の CanChangeDateTimeBehavior 管理プロパティの値を変更することはできますが、属性の動作は変更できません。

• 新しいユーザー定義の日時属性の場合は、CanChangeDateTimeBehavior 管理プロパティが True に設定されています。 このことは、ユーザー定義の日時属性の動作を、UserLocal から DateOnly または TimeZoneIndependent のいずれかに変更できることを意味しています。他の動作の移行は使用できません。

  CRM Online 2016 更新プログラム または Dynamics 365 (設置型) にアップグレードされた Dynamics 365 組織の一部であるユーザー定義の日時属性の場合は、その属性または上位エンティティがカスタマイズ可能でなければ、CanChangeDateTimeBehavior 管理プロパティは True に設定されます。

  注意

  属性の DateTimeBehavior プロパティを UserLocal から DateOnly に更新するときは、Format プロパティもかならず DateAndTime から DateOnly に変更してください。 そうしなければ、例外が発生します。

• CRM Online 2015 更新プログラム 1 および Dynamics 365 (設置型) の次の標準の日時属性は、既定では、DateOnly に設定され、これらの属性の CanChangeDateTimeBehavior 管理プロパティは False に設定されます。このことは、これらの属性の動作は変更できないことを意味します。

  日付と時間の属性です。	上位エンティティ
  anniversary	Contact
  birthdate	Contact
  duedate	Invoice
  estimatedclosedate	Lead
  actualclosedate	Opportunity
  estimatedclosedate	Opportunity
  finaldecisiondate	Opportunity
  validfromdate	Product
  validtodate	Product
  closedon	Quote
  expireson	Quote

  ただし、これらの標準の日付と時間の属性が Microsoft Dynamics CRM Online 2016 更新プログラム または Dynamics 365 (設置型) にアップグレードされた組織に属している場合、アップグレード済みの組織では、これらの属性の動作は UserLocal に設定され、CanChangeDateTimeBehavior 管理プロパティは True に設定されます。これらの属性の動作は DateOnly にのみ変更できます。 他の動作の移行は使用できません。

属性の動作の更新後、変更が有効になるには、そのカスタマイズを公開する必要があります。 日時属性の動作を更新することによって、属性の動作の変更後に入力または更新されたすべての値が、新しい動作でシステムに格納されるようになります。 これは、データベースにすでに格納されている値には影響を与えず、それらは引き続き UTC 値として保存されます。 ただし、既存の値を SDK を使用して取得したり、UI でそれを表示するときは、既存の値はその属性の新しい動作にしたがって表示されます。 たとえば、取引先企業エンティティに関するユーザー定義の属性の動作を、UserLocal から DateOnly に変更し、SDK を使用して既存の取引先企業レコードを取り出した場合、日付と時刻は、<Date> の後に 12 AM (00:00:00) が続く形式で表示されます。 同様に、UserLocal から TimeZoneIndependent への動作の変更の場合、データベースにある実際の値は、タイム ゾーンの変換なしに、そのまま表示されます。

次のサンプル コードは、新しい日時属性動作の更新方法を示しています。

// Retrieve the attribute to update its behavior and format
RetrieveAttributeRequest attributeRequest = new RetrieveAttributeRequest
{
    EntityLogicalName = Account.EntityLogicalName,
    LogicalName = "new_sampledatetimeattribute",
    RetrieveAsIfPublished = false
};
// Execute the request
RetrieveAttributeResponse attributeResponse =
                (RetrieveAttributeResponse)_serviceProxy.Execute(attributeRequest);

Console.WriteLine("Retrieved the attribute '{0}'.",
                attributeResponse.AttributeMetadata.SchemaName);

// Modify the values of the retrieved attribute
DateTimeAttributeMetadata retrievedAttributeMetadata =
                (DateTimeAttributeMetadata)attributeResponse.AttributeMetadata;
retrievedAttributeMetadata.DateTimeBehavior = DateTimeBehavior.DateOnly;
retrievedAttributeMetadata.Format = DateTimeFormat.DateOnly;

// Update the attribute with the modified value
UpdateAttributeRequest updateRequest = new UpdateAttributeRequest
{
    Attribute = retrievedAttributeMetadata,
    EntityName = Account.EntityLogicalName,
    MergeLabels = false
};
_serviceProxy.Execute(updateRequest);
Console.WriteLine("Updated the behavior and format of '{0}' to DateOnly.",
    retrievedAttributeMetadata.SchemaName);

// Publish customizations to the account entity
PublishXmlRequest pxReq = new PublishXmlRequest
{
    ParameterXml = String.Format("<importexportxml><entities><entity>account</entity></entities></importexportxml>")
};
_serviceProxy.Execute(pxReq);
Console.WriteLine("Published customizations to the Account entity.\n");

完全なサンプル コードについては、「サンプル: 日時の動作の変換」を参照してください。

データベース内の既存の日時値の動作の変換

日時属性を更新して、属性の動作を UserLocal から DateOnly または TimeZoneIndependent に変更する場合、データベース内の既存の属性値は自動的に変換されません。 この属性の変更は、その属性の変更後に、属性に入力または属性内で更新された値にのみ影響します。 システム内の既存の日付および時刻の値は引き続き UTC 形式であり、前のセクションで説明したとおり、SDK を使用して、または UI で取得されたときに、新しい動作に応じて Dynamics 365 により表示されます。UserLocal から DateOnly に行動が変更された属性の場合、ConvertDateAndTimeBehaviorRequest メッセージを使用して、データベース内の既存の UTC 値を適切な DateOnly 値に変換して、データのアノマリを回避することができます。

このメッセージを使用すると、UTC から DateOnly への値の変換に使用するタイム ゾーンを選択するための変換ルール (ConversionRule) を指定できます。 次のいずれかの変換ルールを指定できます。

• SpecificTimeZone: 指定された Dynamics 365 タイム ゾーンに従い、UTC 値を DateOnly 値に変換します。 この場合、TimeZoneCode パラメーターの値を指定する必要もあります。

• CreatedByTimeZone: UTC 値を、レコードを作成したユーザーの UI に表示される DateOnly 値に変換します。

• OwnerTimeZone: UTC 値を、レコードを所有するユーザーの UI に表示される DateOnly 値に変換します。

• LastUpdatedByTimeZone: UTC 値を、レコードを最後に更新したユーザーの UI に表示する DateOnly 値に変換します。

DateTimeBehaviorConversionRule クラスの 4 つのメンバーのいずれかを使用して、ConversionRule パラメーターの有効な値を指定できます。

注意

• ConvertDateAndTimeBehaviorRequest メッセージは、CRM Online 2015 更新プログラム 1 または Dynamics 365 (設置型) を使用している場合にのみ、使用可能です。 Dynamics 365 の以前のバージョンでは使用できません。

• ConvertDateAndTimeBehaviorRequest メッセージを実行するには、Dynamics 365 インスタンスのシステム管理者ロールが必要です。

ConvertDateAndTimeBehaviorRequest メッセージを実行するとき、システム ジョブ (非同期処理) が作成されて、変換要求が実行されます。 メッセージ応答の ConvertDateAndTimeBehaviorResponse.JobId 属性には、変換の結果として作成されたシステム ジョブの ID が表示されます。 システム ジョブが完了したら、ジョブの詳細 (AsyncOperation.Message) をチェックして、変換の詳細またはエラーを必要に応じて表示します。

注意

複数の属性の変換を 1 つの変換ジョブにまとめて、1 つのジョブを一度に実行することを推奨します。これにより、変換時に競合がなくなり、また最適なシステム パフォーマンスが得られます。

ConvertDateAndTimeBehaviorRequest メッセージを使用する際に、以下のいくつかの考慮を必要とする重要な点があります。

• ソリューションのインポート、または属性や上位エンティティの削除などのメッセージの実行中は、Dynamics 365 内のソリューションの大きな変更は避ける必要があります。 これを行うと、予期しない動作が発生することがあります。ただし、データの損失は発生しません。

• メッセージの実行結果としてシステムで行われる更新では、ワークフローとプラグインは実行されません。

• メッセージの実行結果としてシステムで行われる更新では、属性の "最終修正日" の値は変更されませんが、更新の監査が行われて、管理者が属性の変換の時刻および元の値と変更後の値を確認するのを支援します。

次のサンプル コードは、 メッセージの使用方法を示しています。

ConvertDateAndTimeBehaviorRequest request = new ConvertDateAndTimeBehaviorRequest()
{
    Attributes = new EntityAttributeCollection() 
            { 
                new KeyValuePair<string, StringCollection>("account", new StringCollection() 
                { "new_sampledatetimeattribute" }) 
            },
    ConversionRule = DateTimeBehaviorConversionRule.SpecificTimeZone.Value,
    TimeZoneCode = 190, // Time zone code for India Standard Time (IST) in CRM
    AutoConvert = false // Conversion must be done using ConversionRule
};

// Execute the request
ConvertDateAndTimeBehaviorResponse response = (ConvertDateAndTimeBehaviorResponse)_serviceProxy.Execute(request);

完全なサンプル コードについては、「サンプル: 日時の動作の変換」を参照してください。

関連項目

サンプル: 日時の動作の変換
TechNet: 日時フィールドの動作と形式
エンティティ属性メタデータのカスタマイズ

Microsoft Dynamics 365

© 2017 Microsoft. All rights reserved. 著作権