定期統合

  • [アーティクル]

移行を繰り返し行うと以下の処理が行われます:

  • これは、データ エンティティとデータ管理フレームワークで構築されます。

  • 財務と運用とあらゆるサード パーティ製アプリケーションやサービス間で、ドキュメントまたはファイルの交換を可能にします。

  • 複数のドキュメント形式、ソース マッピング、XSLT (Extensible Stylesheet Language Transformations)、およびフィルターをサポートします。

    複数の文書形式のドキュメントまたはファイルを交換。

  • セキュリティで保護された REST のアプリケーション プログラミング インターフェイス (API) と認証メカニズムを使用して、統合システムからデータを受信し、データを送り返します。

    繰り返し実行される統合を設定します。

REST API 統合の承認

REST API の統合は、その他の サービス エンドポイント と同じ OAuth 2.0 認証モデルを使用しています。 統合クライアント アプリケーションがこのエンドポイントを使用する前に、Microsoft Entra ID (Azure AD) にアプリケーション ID を作成し、アプリケーションに適切なアクセス許可を付与する必要があります。 定期的なジョブを作成して有効にするとき、その定期的なジョブとやり取りする Azure AD アプリケーション ID を入力するように求められます。 したがって、アプリケーション ID をメモしておいてください。

メモ

この機能は Dynamics 365 Finance + Operations (on-premises) でサポートされていません。

データ プロジェクトと定期的なデータ ジョブを設定

データ プロジェクトの作成

  1. 主要なダッシュ ボードで、データ管理タイルを選択しデータ管理ワークスペースを開きます。

  2. インポートまたはエクスポート タイルを選択し、新しいデータ プロジェクトを作成します。

    メモ

    既存のデータ プロジェクトを使用する場合は、データ プロジェクト タブにあるデータ プロジェクトのカードでプロジェクトを読み込むを選択します。

  3. 有効なジョブ名、データ ソース、およびエンティティ名を入力します。

  4. 1 つ以上のエンティティのデータ ファイルをアップロードします。 各エンティティが追加されており、エラーが発生していないことを確認します。

    メモ

    フィールド マップを設定、レビュー、または修正し、受信データに適用する必要がある XSLT ベースの変換を設定するため、各エンティティ データ カードを選択することができます。 データ プロジェクトのエクスポートについては、エンティティ カードはフィルター リンクも表示し、フィルター データにフィルターを設定できるようにします。 現在、データ プロジェクトのすべての定期的なデータ ジョブは、同じフィルターを使用します。

  5. 保存 を選択します。

定期的なデータ ジョブの作成

  1. データ プロジェクトページで、定期的なデータ ジョブの作成を選択します。

  2. 定期的なデータ ジョブの有効な名前と説明を入力します。

  3. 承認ポリシーの設定タブに、アプリケーションが生成されているアプリケーション ID を入力し、それを有効になっているとしてマークします。

  4. 詳細オプションタブを展開し、ファイルまたはデータ パッケージのどちらかを指定します。

    • ファイル – 外部統合によって個々のファイルがプッシュされ、この定期的なデータジョブによって処理されます。 この場合、予想されるファイルの形式は、エンティティがデータ プロジェクトに追加されたときに指定された形式と同じです。
    • データ パッケージ - 処理のためのデータ パッケージ ファイルのみをプッシュできます。 データ パッケージは、統合ジョブで使用できる 1 つの単位として複数のデータ ファイルを送信できる新しい形式です。
    • 順に処理されるメッセージ – このオプションを有効にすると、インポート シナリオで受信ファイルを強制的に処理することができます。 このオプションはファイルにのみ適用され、データ パッケージには適用されません。

  5. 処理の繰り返しを設定 を選択し、定期的なアイテムの定義 ダイアログ ボックスで、データ ジョブの有効な繰り返しを設定します。

  6. オプション: 定期的なアイテムの監視を設定 を選択し、定期的なアイテムの監視を設定します。

    メモ

    現在のところ、監視の繰り返しは、定期的なデータ ジョブのキューでのみ負荷監視を有効にします。 このサービスを使用してサポートされる追加のポリシーはありません。 この機能を使用すると、積荷需要が必要な場合に処理の繰り返しを微調整することができます。

  7. OK を選択し、確認メッセージ ボックスで はい を選択します。

詳細については、財務と運用でデータ パッケージを処理および消費する を参照してください。

定期的なデータ ジョブの管理

  1. システム管理ワークスペース (システム管理モジュールではない) で、データ管理 IT ワークスペースを選択します。

  2. ワークスペースの定期的なデータ ジョブ タブで、定期的なジョブを選択して詳細を表示します。 スケジュールされたデータ ジョブを管理 ページには、キューに待機しているすべてのメッセージを一覧表示するグリッドが含まれています。 したがって、メッセージと処理ステータスを監視できます。

    スケジュール済みデータ ジョブを管理します。

定期的なデータ ジョブにデータを送信

統合 REST エンドポイントを使用して、クライアントと統合、ドキュメントの送信 (インポート)、またはダウンロードに使用可能なドキュメントのプル (エクスポート) を実行することができます。 これらのエンドポイントは OAuth をサポートします。

REST API の統合

次の API セットは、統合クライアントとアプリケーション間でデータを交換するために使用されます。

インポート (エンキュー) の API

次の URL に対して HTTP POST 呼び出しを行います。

https://<base URL>/api/connector/enqueue/<activity ID>?entity=<entity name>

メッセージ本文では、データをメモリ ストリームとして渡せます。

例

POST https://usncax1aos.cloud.onebox.dynamics.com/api/connector/enqueue/%7B6D31E09F-0249-459F-94F0-Microsoft Entra ID9C2C47B64%7D?entity=Customer%20Groups

アクティビティ ID を取得するには、スケジュールされたデータ ジョブの管理 ページの ID フィールドで、グローバルで一意の識別子 (GUID) をコピーします。

スケジュール済みデータ ジョブ ページの管理での GUID。

エクスポート (デキュー) のAPI

データ プロジェクトで定義されたすべてのデータ エンティティを含むデータ パッケージを返し、クライアント アプリケーションで解凍して使用できるようにするには、次の構造を使用します。

https://<base URL>/api/connector/dequeue/<activity ID>

例

GET https://usncax1aos.cloud.onebox.dynamics.com/en/api/connector/dequeue/%7BC03BB937-09ED-46DE-86EE-4520D7D7E373%7D

クライアントがデータをダウンロードした後、データを受領したものとしてマークすることができるように、受信確認はアプリケーションに送り返す必要があります。

blob にアップロードされたファイルがない場合、デキュー API はそのことを示す応答を返します。

確認の API

次 の API を使用します。

メモ

/dequeue の要求本文は、 /ack POST 要求の本文で送信する必要があります。

https://<base URL>/api/connector/ack/<activity ID>

例

POST https://usncax1aos.cloud.onebox.dynamics.com/en/api/connector/ack/%7BC03BB937-09ED-46DE-86EE-4520D7D7E373%7D

メモ

メッセージの受信確認が成功するまで、同じメッセージが 30 分ごとにキューから削除できるようになります。 メッセージが複数回キューから削除されている場合、デキューの応答は、最後にデキューされた日時を送信します。 これはメッセージの最初のデキューに対して、空白になります。 メッセージの受信確認をして、同じメッセージを繰り返しダウンロードされないようにすることが重要です。 確認に失敗した場合に、失敗を確認できるよう再試行ロジックを導入することをお勧めします。

メッセージ状態を取得中の API

メッセージのステータスを取得する API は、Platform update 12 の修正プログラム KB4058074 として入手できます。 この API は、インポートシナリオでメッセージが正常に処理されたかどうかを判断する場合に特に便利です。 このメッセージは、エンキュープロセス の完了時に作成されます。 メッセージから障害状況が返される場合、統合アプリを設定し再実行するか、別のアクションを実行できます。

例

POST /data/DataManagementDefinitionGroups/Microsoft.Dynamics.DataEntities.GetMessageStatus
BODY
{
    "messageId":"<string>"
}

次のテーブルに、使用可能なステータス値を示します。

先頭値 意味
エンキュー化 ファイルは blob ストレージのキューに正常に追加されました
キューから削除 ファイルは blob ストレージのキューから正常に削除されました
Acked エクスポートされたファイルは、外部アプリケーションによってダウンロードされることが確認されています
前処理中 インポート/エクスポート操作は要求を前処理しています
処理中 インポート/エクスポート操作が処理中です
処理済 インポート/エクスポート操作は正常に完了しました
PreProcessingError インポート/エクスポート操作はポスト前処理ステージで失敗しました
ProcessedWithErrors インポート/エクスポート操作は完了しましたが、エラーが発生しました
PostProcessingFailed インポート/エクスポート操作はポスト処理中に失敗しました

メモ

BLOB ストレージ内のファイルは、ストレージに 7 日間残ります。その後、自動的に削除されます。

実行エラーの一覧を取得する API

GetExecutionErrors は、ジョブ実行のエラーのリストを取得するために使用できます。 API は、Execution ID をパラメーターとして取り、JSON リストでエラー メッセージのセットを返します。

POST /data/DataManagementDefinitionGroups/Microsoft.Dynamics.DataEntities.GetExecutionErrors
BODY
{"executionId":"<executionId>"}

ヒントや秘訣

データ管理ワークスペースからの定期的な統合バッチ ジョブのステータスの表示

定期的な統合データ ジョブは、バッチ モードで実行されます。 繰り返しジョブが失敗した場合は、トラブルシューティング プロセスの一環としてバッチ ジョブのインスタンスを調査する必要があります。 これを簡単に調べるには、メッセージの管理 をクリックして 定期データ ジョブのプロセス状態 ページに進ます。そうすると、バッチ ジョブの状態が表示されます。

バッチ ジョブの状態は、指定した繰り返しデータ ジョブのバッチ フレームワークから非同期で取得されます。 最新のバッチ ジョブの状態を表示するには、バッチの状態を表示する を選択し、ページを更新します。

メモ

バッチ履歴のレコードが削除された場合、定期的なデータ ジョブの処理ステータス ページにあるバッチ ジョブのステータスは空白になります。

バッチ ジョブの状態。

レコードがない場合は、アップロードを禁止する

定期的なエクスポートを使用するとき、そのファイルまたはパッケージ内の合計のレコード数が 0 (ゼロ) である場合、生成されるファイルまたはパッケージをアップロードしないように選択できます。

レコード数が 0 の場合にアップロードしない オプションは、定期的なエクスポート ジョブを構成するとき、またはジョブが作成済みのいずれかの場合に設定することができます。 このオプションは、データ ソースとしてファイルまたはパッケージを使用する場合にのみ使用できます。

レコード数が 0 の場合にはアップロードしません。

実装に、ファイルまたはパッケージをアップロードした、定期的なジョブの実行が含まれている可能性があります。 ご使用の実装には、アップロードするものがないため、ファイルまたはパッケージがアップロードされなかった実行が含まれていることがあります。 アップロードする必要のあるファイルがアップロードされていない、またはアップロードする必要がないファイルがアップロードされていた場合は、定期的なエクスポート ジョブに対してメッセージの管理ページを使用して、デバッグ プロセスを支援することができます。

メモ

これらの機能は、Microsoft Dynamics 365 の財務と運用、Enterprise Edition プラットフォーム更新プログラム 12 に追加されました。 プラットフォーム更新 12 にアップグレードする前に実行されたジョブは、次の列に値を持ちません。

エクスポートされたレコードの合計 列には、エクスポートされたレコードの合計数が表示されます。 0 (ゼロ) の値は、ファイルにエクスポートされたまたはパッケージに含まれていたレコードがないことを示します。

ファイルが正常にアップロードされました 列には、ファイルまたはパッケージが正常にアップロードされた場合にチェック マークが含まれます。 エラーが発生したまたはレコードがないことが原因でファイルがアップロードされなかった場合、列は空白になります。

Http 対 Https

デキュー API は、HTTPS ではなく HTTP を返します。 この動作は、運用環境などのロード バランサーを使用するアプリケーション環境で確認できます。 (1 つのボックス環境で動作を表示ことはできません)。 アプリケーションからキューから削除しようとするミドルウェア アプリケーションで、URI スキームを HTTPS に変更することをお勧めします。

バッチ ジョブの状態。