データ管理パッケージ REST API

[アーティクル]
03/08/2023

この記事では、データ管理フレームワークのパッケージの Representational State Transfer (REST) のアプリケーションプログラミングインターフェイス (API) について説明します。パッケージ API により、データパッケージを使用して統合できます。 REST API はクラウド展開とオンプレミスの展開で使用できます。

オンプレミスサポートが追加されましたが、API 名は変更されていません。したがって、Microsoft は、クラウド配置とオンプレミス配置の両方に対して単一の API セットを維持することができます。

統合 API の選択

ファイルベースの統合シナリオは、データ管理フレームワークのパッケージ API と定期的な統合 API の 2 つの API によりサポートされます。どちらの API もデータインポートシナリオとデータエクスポートシナリオの両方をサポートしています。次のテーブルでは、使用する API を決定する際に考慮する必要がある主な決定事項について説明します。

決定ポイント	定期統合 API	データ管理フレームワークのパッケージ API
スケジューリング	財務と運用アプリのスケジューリング	財務と運用アプリ外でのスケジューリング
形式	ファイルおよびデータパッケージ	データパッケージのみ
変換	データファイルが XML 形式の場合の Extensible Stylesheet Language Transformations (XSLT) のサポート	システム外部での変換
サポートされているプロトコル	SOAP および REST	REST
サービスタイプ	カスタムサービス	データプロトコル (OData) アクションを開きます

定期的な統合 API がデータ管理フレームワークのパッケージ API よりも要件を満たしていることを決定した場合、定期統合を参照します。この記事の残りの部分では、データ管理フレームワークのパッケージ API について説明します。

認証

データ管理フレームワークのパッケージ API は、アクセスを認可するために OAuth 2.0 を使用します。 API は、有効な OAuth アクセストークンを使用して呼び出す必要があります。 OAuth 2.0 および Microsoft Entra ID の詳細については、OAuth 2.0 と Microsoft Entra ID を使用して Web アプリケーションへのアクセスを承認を参照してください。オンプレミス配置では、Active Directory フェデレーションサービス (AD FS) が承認に使用されます。

メモ

クライアント資格情報の付与フローを使用すると、アプリケーションはアクセス制御リストを保持します。アクセス制御リストは、システム管理>設定>Microsoft Entra アプリケーションを順にクリックして見つけることができます。 Microsoft Entra アプリケーション ページには、承認済クライアント ID と、クライアント資格情報付与フローを使用して API が呼び出されたときに適用する必要があるユーザーセキュリティマッピングが表示されます。

オンプレミス配置については、このリストには AD FS からの有効なクライアント ID が必要です。また、オンプレミスで使用する場合は、接続の確立時に、次の例にて示されている <baseurl> に /namespaces/AXSF を付加する必要があります。

API のインポート

ファイル (データパッケージ) のインポートには、次の API が使用されます。

GetImportStagingErrorFileUrl

GetImportStagingErrorFileUrl API は、エラーファイルのURLを取得します。エラーファイルには単一のエンティティに対するインポートの過程で、ステージング段階で失敗したデータが格納されています。エラーファイルが生成されなかった場合は、空の文字列が返されます。

POST /Data/DataManagementDefinitionGroups/Microsoft.Dynamics.DataEntities.GetImportStagingErrorFileUrl

Body
{
	"executionId":"<string>",
	"entityName":"<string>"
}

Successful Response:

HTTP/1.1 200 OK
{
	"@odata.context":"https://<baseurl>/data/$metadata#Edm.String",
	"value":"<errorfileurl>"
}

入力パラメーター

パラメーター	説明
string executionId	インポート処理の実行ID。これは、UI ではジョブ ID と呼ばれます。
string entityName	エラーファイルの取得対象となるエンティティの名前。

出力パラメーター

パラメーター	説明
string errorkeysfileurl	エラーファイルのURL。エラーファイルが生成されなかった場合は、空の戻り値が返されます。

GenerateImportTargetErrorKeysFile

GenerateImportTargetErrorKeysFile API は、エラーファイルを生成します。エラーファイルには単一のエンティティに対するインポートの過程で、ステージングからターゲットの段階で失敗したインポートレコードのキーが格納されています。

このAPIがtrueを返す場合は、GetImportTargetErrorKeysFileUrl API を使用して、生成されたエラーキーファイルのURLを取得します。

POST /Data/DataManagementDefinitionGroups/Microsoft.Dynamics.DataEntities.GenerateImportTargetErrorKeysFile

Body

{
	"executionId":"<string>",
	"entityName":"<string>"
}

Successful Response:

HTTP/1.1 200 OK
{
	"@odata.context":"https://<baseurl>/data/$metadata#Edm.Boolean",
	"value": <errorsExist>
}

入力パラメーター

パラメーター	説明
string executionId	インポート処理の実行ID。
string entityName	エラーファイルの取得対象となるエンティティの名前。

出力パラメーター

パラメーター	説明
ブール値エラーが発生しています	インポートエラーが発生した場合はtrue、インポートエラーが発生しなかった場合はfalseとします

GetImportTargetErrorKeysFileUrl

GetImportTargetErrorKeysFileUrl API を使用して、単一のエンティティに対するインポートのステージングからターゲットへのステップで失敗したインポートレコードのキーが格納されているエラーファイルの URL を取得します。

エラーファイルが使用可能な場合、この API はその URL を返します。エラーファイルがまだ生成中の場合、またはエラーファイルが存在しない場合は、API は空の文字列を返します。

重要

この API を呼び出す前に、GenerateImportTargetErrorKeysFile API を呼出して、エラーファイルを生成します。 GenerateImportTargetErrorKeysFile API が true を返した場合、空でない文字列が返されるまで、ループでこの API を呼び出します。 GenerateImportTargetErrorKeysFile API が false を返した場合、エラーがないため、この API は空の文字列をかならず返します。

疑似コードの例

errorsExist = GenerateImportTargetErrorKeysFile(executionId, entityName)

if (errorsExist)
{
    errorFileUrl = null

    while (errorFileUrl is not a non-empty string)
    {
        errorFileUrl = GetImportTargetErrorKeysFileUrl(executionId, entityName)
        if (errorFileUrl is not a non-empty string)
        {
            wait for some time before retrying
        }
    }
}

POST
/data/DataManagementDefinitionGroups/Microsoft.Dynamics.DataEntities.GetImportTargetErrorKeysFileUrl

Body
{
    "executionId":"<string>",
    "entityName":"<string>"
}

成功した応答の例を次に示します。

HTTP/1.1 200 OK
{
    "@odata.context":"https://<baseurl>/data/$metadata#Edm.String",
    "value":"<errorkeysfileurl>"
}

入力パラメーター

パラメーター	説明
string executionId	インポートの実行 ID。これは、UI ではジョブ ID と呼ばれます。
string entityName	エラーファイルを取得する対象のエンティティの名前。

出力パラメータ

パラメーター	説明
string errorkeysfileurl	エラーキーファイルが使用可能な場合、そのファイルの URL。エラーファイルがまだ生成中の場合、またはエラーファイルが存在しない場合は、このメソッドは空の文字列を返します。

GetAzureWriteUrl

GetAzureWriteUrl API は、書き込み可能な Blob URL を取得するために使用されます。このメソッドには、URL に埋め込まれた共有アクセス署名 (SAS) トークンが含まれています。この方法を使用すると、Azure Blob Storage コンテナーにデータパッケージをアップロードすることができます。オンプレミス配置の場合、この API はローカルストレージに取り込まれた URL を引き続き返します。

メモ

SAS は有効期限の時間枠中にのみ有効です。ウィンドウが経過した後に発行されるすべての要求はエラーを返します。詳細については、共有アクセス署名 (SA) の使用を参照してください。

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

成功した応答の例を次に示します。

HTTP/1.1 200 OK
{
    "@odata.context":"https://<baseurl>/data/$metadata#Edm.String",
    "value": "{\"BlobId\":\"{<GUID>}\",\"BlobUrl\":\"https://<baseurl_id>.blob.core.windows.net/dmf/<uniqueFileName>?<SAS Token>\"}"
    }
}

入力パラメーター

パラメーター	説明
文字列 uniqueFileName	BLOB ID を追跡するために使用される一意のファイル名。一意のファイル名であることを保証するため、グローバル一意識別子 (GUID) を含めることができます。

出力パラメータ

パラメーター	説明
string BlobId	割り当てられた BLOB コンテナーの BLOB ID。
string BlobUrl	埋め込みの SAS トークンを持つ URL。 URL を使用して Blob ストレージに書き込むことができます。

ImportFromPackage

ImportFromPackage API は、実装に関連付けられている Blob ストレージにアップロードされるデータパッケージからインポートを開始するために使用します。オンプレミス配置の場合、ファイルが以前アップロードされたローカルストレージから、インポートが開始されます。

この API ImportFromPackageAsync の非同期バージョンがあります。仕様は同じです。返された実行 ID をキャプチャし、後者は GetExecutionSummaryStatus API を呼び出して、実行が完了したことを確認する必要があります。

メモ

ImportFromPackage API は、複合エンティティをサポートします。ただし、1 つのパッケージで 1 つの複合エンティティのみという制限があります。

POST /data/DataManagementDefinitionGroups/Microsoft.Dynamics.DataEntities.ImportFromPackage
BODY
{
    "packageUrl":"<string>",
    "definitionGroupId":"<string>",
    "executionId":"<string>",
    "execute":<bool>,
    "overwrite":<bool>,
    "legalEntityId":"<string>"
}

成功した応答の例を次に示します。

HTTP/1.1 200 OK
{
    "@odata.context":"https://<baseurl>/data/$metadata#Edm.String",
    "value":"<executionId>"
}

入力パラメーター

パラメーター	説明
string packageUrl	財務と運用アプリに関連付けられている Blob Storage 内のデータパッケージの URL。
string definitionGroupId	インポート用のデータプロジェクトの名前。
string executionId	ジョブに使用する ID。これは、UI ではジョブ ID と呼ばれます。空の ID が割り当てられている場合は、新しい実行 ID が作成されます。
bool execute	このパラメーターを True に設定して対象の手順を実行します。それ以外の場合、False に設定します。
bool overwrite	パッケージ内で複合エンティティを使用する場合は、このパラメーターを常に False に設定する必要があります。それ以外の場合、True に設定します。
string legalEntityId	データインポートの法人。

出力パラメータ

パラメーター	説明
string executionId	データインポートの実行 ID。これは、UI ではジョブ ID と呼ばれます。

メモ

ImportFromPackage() はバッチを使用してインポートを実行します。したがって、並行インポートを実行するために、データ管理で並列処理ルールを使用する必要があります。 ImportFromPackage() を並列スレッドで呼び出すことはできません。それ以外の場合、これは失敗します。

API をエキスポート

ファイル (データパッケージ) のエクスポートには、次の API が使用されます。

ExportToPackagePreview

ExportToPackagePreview API は、大量のレコードを含むデータパッケージのエクスポートをプレビューするために使用されます。この API は、クラウド配置とオンプレミス配置の両方に適用されます。

この API ImportFromPackagePreviewAsync の非同期バージョンがあります。仕様は同じです。返された実行 ID をキャプチャし、後者は GetExecutionSummaryStatus API を呼び出して、実行が完了したことを確認する必要があります。

この API を呼び出す前に、エクスポートデータプロジェクトを作成する必要があります。プロジェクトが存在しない場合、API の呼び出しには、エラーが返されます。
変更履歴がオンの場合は、最後の実行後に更新または作成されたレコードのみがエクスポートされます。 (つまり、デルタのみが返されます。)
count パラメーターを使用すると、返されるレコード数が制限されます。

POST /data/DataManagementDefinitionGroups/Microsoft.Dynamics.DataEntities.ExportToPackagePreview
BODY
{
    "definitionGroupId":"<Data project name>",
    "packageName":"<Name to use for downloaded file.>",
    "executionId":"<Execution Id if it is a rerun>",
    "reExecute":<bool>,
    "legalEntityId":"<Legal entity Id>",
    "count":"<Legal entity Id>"
}

成功した応答の例を次に示します。

HTTP/1.1 200 OK
{
    "@odata.context":"https://<baseurl>/data/$metadata#Edm.String",
    "value":{
        "value":"<executionId>"
    }
}

入力パラメーター

パラメーター	説明
string definitionGroupId	エクスポート用のデータプロジェクトの名前。
string packageName	エクスポートされたデータパッケージの名前。
string executionId	ジョブに使用する ID。これは、UI ではジョブ ID と呼ばれます。空の ID が割り当てられている場合は、新しい実行 ID が作成されます。
bool reExecute	このパラメーターを True に設定して対象の手順を実行します。それ以外の場合、False に設定します。
string legalEntityId	データインポートの法人。
カウント	返すレコードの数。ゼロに設定すると、トップカウント条件は適用されません。

出力パラメーター

パラメーター	Description
string executionId	データエクスポートの実行 ID。これは、UI ではジョブ ID と呼ばれます。

ExportToPackage

ExportToPackage API は、データパッケージのエクスポートを開始するために使用されます。この API は、クラウド配置とオンプレミス配置の両方に適用されます。

この API ExportToPackageAsync の非同期バージョンがあります。仕様は同じです。返された実行 ID をキャプチャし、後者は GetExecutionSummaryStatus API を呼び出して、実行が完了したことを確認する必要があります。

この API を呼び出す前に、エクスポートデータプロジェクトを作成する必要があります。プロジェクトが存在しない場合、API の呼び出しには、エラーが返されます。
変更履歴がオンの場合は、最後の実行後に更新または作成されたレコードのみがエクスポートされます。 (つまり、デルタのみが返されます。)

POST /data/DataManagementDefinitionGroups/Microsoft.Dynamics.DataEntities.ExportToPackage
BODY
{
    "definitionGroupId":"<Data project name>",
    "packageName":"<Name to use for downloaded file.>",
    "executionId":"<Execution Id if it is a rerun>",
    "reExecute":<bool>,
    "legalEntityId":"<Legal entity Id>"
}

成功した応答の例を次に示します。

HTTP/1.1 200 OK
{
    "@odata.context":"https://<baseurl>/data/$metadata#Edm.String",
    "value":{
        "value":"<executionId>"
    }
}

入力パラメーター

パラメーター	説明
string definitionGroupId	エクスポート用のデータプロジェクトの名前。
string packageName	エクスポートされたデータパッケージの名前。
string executionId	ジョブに使用する ID。これは、UI ではジョブ ID と呼ばれます。空の ID が割り当てられている場合は、新しい実行 ID が作成されます。
bool reExecute	このパラメーターを True に設定して対象の手順を実行します。それ以外の場合、False に設定します。
string legalEntityId	データインポートの法人。

出力パラメータ

パラメーター	説明
string executionId	データエクスポートの実行 ID。これは、UI ではジョブ ID と呼ばれます。

GetExportedPackageUrl

GetExportedPackageUrl API は、ExportToPackage を呼び出すことでエクスポートされたデータパッケージの URL を取得するために使用されます。この API は、クラウド配置とオンプレミス配置の両方に適用されます。

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

成功した応答の例を次に示します。

HTTP/1.1 200 OK
{
    "@odata.context":"https://<baseurl>/data/$metadata#Edm.String",
    "value":{
        "value":"https://<baseurl_id>.blob.core.windows.net/dmf/<uniqueFileName>?<SAS Token>"
    }
}

入力パラメーター

パラメーター	説明
string executionId	データプロジェクト実行の実行 ID。これは、UI ではジョブ ID と呼ばれます。

出力パラメーター

パラメーター	説明
string BlobUrl	埋め込みの SAS トークンを持つ blob URL。 URL を使用して、エクスポートしたデータパッケージをダウンロードできます。

ステータスチェック API

状態を確認するには、次の API を使用します。これらは、インポートフローとエクスポートフローの両方で使用されます。

GetExecutionSummaryStatus

GetExecutionSummaryStatus API は、インポートジョブとエクスポートジョブの両方に使用されます。これは、データプロジェクト実行ジョブのステータスの確認に使用されます。この API は、クラウド配置とオンプレミス配置の両方に適用されます。

メモ

API が、成功など、最終実行ステータスを返すよう、パッケージを作成する必要があります。

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

成功した応答の例を次に示します。

HTTP/1.1 200 OK
{
    "@odata.context":"https://<baseurl>/data/$metadata#Edm.String",
    "value":"<executionStatus>"
}

入力パラメーター

パラメーター	説明
string executionId	データプロジェクト実行の実行 ID。これは、UI ではジョブ ID と呼ばれます。

出力パラメーター

パラメーター	説明
DMFExecutionSummaryStatus executionStatus	実行のステータス。以下に使用可能な値を示します。不明 NotRun 実行中成功 PartiallySucceeded 失敗キャンセル済み

メモ

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

エラーの一覧を取得する

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

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

プロセスのインポートとエクスポート

次の図は、データ管理パッケージメソッドを使用してデータパッケージをインポートする方法を示しています。

データ管理パッケージメソッドを使用するデータパッケージファイルをインポートします。

次の図は、データ管理パッケージメソッドを使用してデータパッケージをエクスポートする方法を示しています。

データ管理パッケージメソッドを使用するデータパッケージファイルをエクスポートします。

データのインポートとデータのエクスポートのメソッドを紹介するサンプルのコンソールアプリケーションは、 GitHub から入手できます。詳細については、「https://github.com/Microsoft/Dynamics-AX-Integration/tree/master/FileBasedIntegrationSamples/ConsoleAppSamples」に移動してください。

データ管理パッケージ REST API

統合 API の選択

認証

API のインポート

GetImportStagingErrorFileUrl

GenerateImportTargetErrorKeysFile

GetImportTargetErrorKeysFileUrl

GetAzureWriteUrl

ImportFromPackage

API をエキスポート

ExportToPackagePreview

ExportToPackage

GetExportedPackageUrl

ステータス チェック API

GetExecutionSummaryStatus

エラーの一覧を取得する

プロセスのインポートとエクスポート

その他のリソース

ステータスチェック API