Ajax および JScript Web リソースで OData エンドポイントを使用する

[アーティクル]
07/06/2017

公開日: 2016年11月

対象: Dynamics CRM 2015

OData エンドポイントでは、JavaScript ライブラリを使用して Microsoft Dynamics CRM 2015 および Microsoft Dynamics CRM Online 2015 更新プログラムデータを操作できます。JavaScript ライブラリを定義するファイルを使用して、スクリプト Web リソースを作成します。次に、ライブラリ内の関数を、フォームイベントまたはフィールドイベントのハンドラー、あるいはリボンコマンドアクションに関連付けます。 Web ページ (HTML) の Web リソース内の他の JavaScript ライブラリと同じようにこれらを使用できます。

このトピックの内容

Ajax

POST によるメソッドトンネリング

サーバー URL にアクセスする

XmlHttpRequest の使用

JQuery の使用

日付に関する作業

Ajax

AJAX (Asynchronous JavaScript and XML) は、対話型の Web アプリケーションの作成に使用される Web 開発手法です。サーバー要求は、XmlHttpRequest オブジェクトを使用して、ブラウザーからバックグラウンドで行われます。同期要求も送信できますが、非同期要求の送信を推奨します。非同期要求では、2 つの JScript 関数が必要です。1 つは要求を送信する関数で、もう 1 つは応答を処理する "コールバック" 関数です。

JSON

JSON (JavaScript Object Notation) 形式は、構造化されたデータをシリアル化および転送するために使用し、通常、XML とほぼ同じように使用されます。XML と同様、この形式はテキストベースであり、人が読めるように設計されています。標準の JavaScript オブジェクトを JSON 形式に変換するには、JSON.stringify メソッドを使用します。 JSON 内のテキストは JavaScript オブジェクトを定義しているため、eval メソッドを使用してテキストを JavaScript オブジェクトに変換できます。ただし、この操作を行うと、セキュリティの脆弱性が生じます。JSON.parse メソッドを使用する方が適切です。

XmlHttpRequest

XmlHttpRequest (XHR とも呼ばれます) は、要求を構成および送信し、要求が非同期の場合はコールバック関数を定義する機能を提供します。サーバーからの HTTP 応答には、要求が成功したかどうかを示すステータスコードが含まれます。 200 番台の HTTP ステータスコード値は、成功と見なされます。

XmlHttpRequest は、応答に含まれるデータの形式に関する指示をサーバーに提供します。ODATA エンドポイントは ATOM と JSON の両形式をサポートするため、ユーザーはデータを XMLATOM 形式で返すことを要求できます。ただし、JavaScript で簡単に使用できるため、JavaScript コードの場合、予期される一般的な要求では JSON を使用します。

POST によるメソッドトンネリング

OData プロトコルで使用される PUT および DELETE という HTTP 動詞はあまり一般的ではなく、MERGE という新しい動詞も定義されています。使用するサポートライブラリによっては、これらの動詞を使用するときに問題が発生する可能性があります。この問題に対処するには、POST 動詞を使用し、X-HTTP-MethodHTTP ヘッダーと目的のアクションを指定します。XmlHttpRequest で指定されるアクションを上書きするには、setRequestHeader メソッドを使用します。

サーバー URL にアクセスする

ODATA エンドポイントの使用を JavaScript で開始する場合は、まず組織のルート URL に URL を確立します。コンテキストオブジェクトから getClientUrl 関数を使用します。

スクリプトが、フォームイベントまたはフィールドイベントのコンテキスト、あるいは、リボンコマンドの <JavaScriptFunction> (RibbonDiffXml) で動作するように設計されている場合は、Xrm.Page.context オブジェクトを使用して getClientUrl を呼び出すことができます。
スクリプトが Web ページ (HTML) の Web リソースのコンテキスト内で実行される場合は、HTML Web リソース内の ClientGlobalContext.js.aspx ページへの参照を含めることで、GetGlobalContext 関数を使用できます。

XmlHttpRequest の使用

jQuery は多様な使い方ができる優れたライブラリですが、Microsoft Dynamics 365 で ODATA エンドポイントを使用する操作を実行するのに jQuery の使用が必須というわけではありません。jQuery をアプリケーションページで実行するフォームスクリプトまたはコマンドスクリプトで使用せず、XmlHttpRequest で直接実行して、jQuery ライブラリを読み込まないようにすることをお勧めします。jQuery**$.ajax** はブラウザーで使用できる XmlHttpRequest を使用します。このオブジェクトの直接使用は、$.ajax の使用とは少し異なります。XMLHttpRequest の使用に精通している場合は、引き続きこれを使用してください。通常 jQuery を使用している場合は、XMLHttpRequest を直接使用することを検討してください。詳細:XMLHttpRequest Object (XMLHttpRequest オブジェクト)」を参照してください。

XmlHttpRequest では、onreadystatechange イベント用のイベントハンドラーを作成し、要求が完了したタイミングを検出します。イベントハンドラーでは、返されたステータスコードを確認して、要求が成功したかどうかを判別します。最後に、open と send メソッドを使用します。次の例は、XmlHttpRequest を使用した新規の取引先企業レコードの作成方法を示しています。

var account = {};
    account.Name = "Sample Account";
    var jsonAccount = JSON.stringify(account);

    var createAccountReq = new XMLHttpRequest();
    createAccountReq.open("POST", Xrm.Page.context.getClientUrl() + "/XRMServices/2011/OrganizationData.svc/AccountSet", true);
    createAccountReq.setRequestHeader("Accept", "application/json");
    createAccountReq.setRequestHeader("Content-Type", "application/json; charset=utf-8");
    createAccountReq.onreadystatechange = function () {
        createAccountReqCallBack(this);
    };
    createAccountReq.send(jsonAccount);

function createAccountReqCallBack(createAccountReq) {
    if (createAccountReq.readyState == 4 /* complete */) {
        createAccountReq.onreadystatechange = null; //avoids memory leaks
        if (createAccountReq.status == 201) {
            //Success
            var newAccount = JSON.parse(createAccountReq.responseText).d;
        }
        else {
            //Failure
            errorHandler(createAccountReq);
        }
    }
};

この他の XMLHttpRequest の使用例については、「サンプル: OData エンドポイントと JavaScript を使用した作成、取得、更新、および削除」を参照してください。

JQuery の使用

jQuery は JavaScript 内の Web アプリケーションプロジェクトに含まれている、一般的な Microsoft Visual Studio ライブラリです。jQuery によって、オブジェクトと関数の多機能なフレームワークが提供され、これによって、HTML を使用して JavaScript ページのクエリと操作を行うことができます。XMLHttpRequestを使用するために、jQuery には jQuery.ajax メソッドがあります。

注意

フォームスクリプトまたはコメントで jQuery を使用することはお勧めしません。詳細:jQuery の使用。

jQuery オブジェクトは $ 文字を使用して参照されるため、jQuery.ajax の短い形式は $.ajax です。ajax メソッドは、通常、命令構文で使用され、オブジェクトがインスタンス化されると同時に要求が送信されます。次の例は、新規の取引先企業レコードの作成方法を示しています。

var account = {};
account.Name = "Sample Account";
var jsonAccount = window.JSON.stringify(account);
$.ajax({
    type: "POST",
    contentType: "application/json; charset=utf-8",
    datatype: "json",
    url: Xrm.Page.context.getClientUrl() + "/XRMServices/2011/OrganizationData.svc/AccountSet",
    data: jsonAccount,
    beforeSend: function (XMLHttpRequest) {
        //Specifying this header ensures that the results will be returned as JSON.
        XMLHttpRequest.setRequestHeader("Accept", "application/json");
    },
    success: function (data, textStatus, XmlHttpRequest) {
        account = data.d;
    },
    error: function (XMLHttpRequest, textStatus, errorThrown) {
        errorHandler(XMLHttpRequest, textStatus, errorThrown);
    }
});

次の表は、Microsoft Dynamics 365 で ODATA エンドポイントを使用した HTTP 要求および応答の処理について理解する必要がある、プロパティの一覧です。

プロパティ名	種類	コメント
type	string	データを取得する場合は GET を使用し、他のすべての操作の場合は POST を使用します。詳細:要求ヘッダーを異なる HTTP アクションに対して明示的に設定する
contentType	string	サーバーに送信するコンテンツの種類を指定します。データを JSON 形式で送信する場合は application/json; charset=utf-8 を使用します。
dataType	string	サーバーから返されることが予期されるデータの種類。jsonの使用注意このプロパティの設定だけでは十分でない場合があります。詳細:要求ヘッダーを明示的に設定して JSON を許可する
data	object	作成操作または更新操作の場合は、これを JSON オブジェクトの値に設定します。
url	string	実行しているアクションに適した ODATA エンドポイント URL。
beforeSend	function	送信前に XMLHttpRequest オブジェクトを変更できるようにする関数。
success	function	要求が成功した場合のコールバック関数。詳細:処理結果
error	function	要求が失敗した場合に呼び出される関数。詳細:エラーを処理する

詳細については、「サンプル: OData エンドポイントと JavaScript および jQuery を使用した作成、取得、更新、および削除」を参照してください。

要求ヘッダーを明示的に設定して JSON を許可する

JSON 形式の結果を期待する場合、dataType プロパティを設定しただけでは正しく動作しない可能性があります。beforeSend プロパティを使用すると、データを JSON として返すように、XMLHttpRequest のヘッダーを明示的に設定できます。これは、通常、次の例に示すように匿名関数を使用して実行されます。

beforeSend: function (XMLHttpRequest) {
   //Specifying this header ensures that the results will be returned as JSON.
   XMLHttpRequest.setRequestHeader("Accept", "application/json");}

指定されると、XMLHttpRequest.responseText 内のエラーが、XML ではなく JSON で書式設定されます。

ヒント

データが返されることを想定しない場合であっても、結果が常に JSON を使用して返されることを指定することで、エラー処理が簡単になります。詳細:エラーを処理する

要求ヘッダーを異なる HTTP アクションに対して明示的に設定する

「POST によるメソッドトンネリング」で説明したように、POST または GET 以外の HTTP アクションを必要とするアクションを実行する場合は、POST と beforeSend プロパティを使用して、XMLHttpRequest のヘッダーを明示的に設定して、異なるアクションを実行します。これは、通常、次の例に示すように匿名関数を使用して実行されます。

beforeSend: function (XMLHttpRequest) {
   //Specify the HTTP method DELETE to perform a delete operation.
   XMLHttpRequest.setRequestHeader("X-HTTP-Method", "DELETE");
}

エラーを処理する

要求が成功しなかった場合、$.ajax は、error プロパティで設定される関数に次の 3 つの引数を渡します。

XMLHttpRequest
XMLHttpRequest オブジェクト。
textStatus
発生したエラーの種類を表す文字列。次のいずれかの値です。
- null
- timeout
- error
- notmodified
- parsererror
errorThrown
オプションの例外オブジェクト。

次のサンプルは、エラーを管理する中心的機能にこれらの引数を渡す方法を示しています。

error: function (XMLHttpRequest, textStatus, errorThrown) {
   errorHandler(XMLHttpRequest, textStatus, errorThrown);
}

次のサンプルは、showMessage関数を使用してエラーメッセージを取得し、結果を表示する簡単な関数を示しています。

注意

この関数は、エラーの詳細が JSON 形式で返されることを予期しています。JSON を使用して結果を返すように $.ajax メソッドが構成されていない場合、XMLHttpRequest.responseText は XML になります。

function errorHandler(XMLHttpRequest, textStatus, errorThrown)
{ showMessage("Error : " + textStatus + ": " + JSON.parse(XMLHttpRequest.responseText).error.message.value); }

処理結果

POST 操作または GET 操作を行う場合、データが返されることを予期できます。結果が JSON 形式で返されることを指定した場合、結果は、返されるデータオブジェクトの d プロパティにあります。一意の識別子を使用してレコードを作成または取得するとき、d はレコードのデータを表します。他のすべての場合、d は配列になります。

次のサンプルは、複数の取引先企業レコードを返すクエリの結果の処理を示しています。

success: function (data, textStatus, XmlHttpRequest) {
   var accounts = data.d;
   for (var i in accounts) {   showMessage(accounts[i].Name);
   }}

日付に関する作業

実行が必要な場合がある、日付に関連するタスクは次の 4 つです。

取得済みデータの解析
日付値の表示
日付値の更新
日付をクエリ内のフィルターで条件として設定する

取得済みデータの解析

ODATA エンドポイントを使用してレコードを取得すると、日付値が "\/Date(<ticks>)\/" という形式の文字列として返されます。<ticks> は、1970 年 1 月 1 日の真夜中からのミリ秒数です。例: "\/Date(1311170400000)\/"。Microsoft Dynamics 365 から返されるすべての値は協定世界時間 (UTC) の値を表すため、オフセット情報は含まれていません。

ODATA エンドポイントを使用して返されたレコードの日付を解析するために使用可能な方法は次の 2 つです。

JSON.parse メソッドで reviver 関数を使用する
String.replace を使用して文字列から日付値を生成する

JSON.parse メソッドで reviver 関数を使用する

JSON.parse メソッドは、MSDN の JSON.parse メソッドに関するドキュメントで説明されているように、オプションの reviver 引数をサポートしています。正規表現で定義されたパターンに一致する文字列値を Date オブジェクトに変換する例を次に示します。

var jsontext = '{ "hiredate": "\/Date(1311170400000)\/", "birthdate": "\/Date(-158342400000)\/" }';
var dates = JSON.parse(jsontext, dateReviver);
var string = dates.hiredate.toUTCString();
// The value of string is "Wed, 20 Jul 2011 14:00:00 UTC"

function dateReviver(key, value) {
 var a;
 if (typeof value === 'string') {
  a = /Date\(([-+]?\d+)\)/.exec(value);
  if (a) {
   return new Date(parseInt(value.replace("/Date(", "").replace(")/", ""), 10));
  }
 }
 return value;
};

注意

このコードは、日付値が常に UTC データ値であり、オフセット情報を含まないことを前提としています。

String.replace を使用して文字列から日付値を生成する

JSON.parse メソッドで reviver 引数を使用しない場合、文字列から Date 値を生成する方法を次の例に示します。

var dateValue = new Date(parseInt(stringDateValue.replace("/Date(", "").replace(")/", ""), 10));

日付値の表示

文字列の日付値を Date オブジェクトに変換した後、各種 JavaScript メソッドを使用、または自分で作成して、ユーザーインターフェイスに表示可能な文字列として日付を表示できます。JavaScriptDate オブジェクトは UTC を認識するため、toString または toLocaleString などのメソッドを使用してユーザーインターフェイスに表示される日付は、ユーザーのオペレーティングシステムのタイムゾーン設定を反映します。

ただし、アプリケーションの値は、Microsoft Dynamics 365 に表示される同じ値とは異なる場合があります。この値は、ユーザーのオペレーティングシステムのタイムゾーン設定に依存しません。ユーザーの現在のオペレーティングシステムのタイムゾーン設定が、Microsoft Dynamics 365 に保存されているタイムゾーン設定と一致しない場合、これらの値は異なります。Microsoft Dynamics 365 では、toString など標準の JavaScript 日付関数の使用によって適用されない、個人用プレゼンテーションオプションも設定できます。

表示される日付と時刻の値が Microsoft Dynamics 365 に表示される値に一致するよう調整する場合は、UserSettings エンティティや、TimeZoneDefinition および TimeZoneRule などのエンティティに保存されているデータを照会して、ユーザーの設定に一致した日付を表示する関数を作成できます。Microsoft Dynamics 365 には、このような操作を実行する関数は用意されていません。

日付値の更新

setMinutes や setHours など、標準セットのメソッドを使用して JavaScript の日付の値を変更するとき、そのような変更はユーザーのローカル時間で行われます。レコードを保存すると、実際の UTC 値がシリアル化され、Microsoft Dynamics 365 に保存されます。日付を UTC 値に変換するための操作は必要ありません。

Date がシリアル化された場合、その形式は日付の取得時に使用された形式と異なります。「取得済みデータの解析」で説明したように、日付は "\/Date(1311179400000)\/" という形式を使用した文字列として取得されます。サーバーに返される日付値に対する JSON.stringify の結果を調べると、形式は "2013-07-20T16:30:00Z". となっています。

日付をクエリ内のフィルターで条件として設定する

$filter システムクエリオプションで日付値を使用する場合は、UTC 日付を使用する必要があります。JavaScriptDate オブジェクトをフィルターに適した形式に変換するには、次の例のような関数を使用して日付を処理する必要があります。結果は、datetime'2010-09-28T18:21:46:594Z' の形式に一致する文字列です。

function getODataUTCDateFilter(date) {

 var monthString;
 var rawMonth = (date.getUTCMonth()+1).toString();
 if (rawMonth.length == 1) {
  monthString = "0" + rawMonth;
 }
 else
 { monthString = rawMonth; }

 var dateString;
 var rawDate = date.getUTCDate().toString();
 if (rawDate.length == 1) {
  dateString = "0" + rawDate;
 }
 else
 { dateString = rawDate; }


 var DateFilter = "datetime\'";
 DateFilter += date.getUTCFullYear() + "-";
 DateFilter += monthString + "-";
 DateFilter += dateString;
 DateFilter += "T" + date.getUTCHours() + ":";
 DateFilter += date.getUTCMinutes() + ":";
 DateFilter += date.getUTCSeconds() + ":";
 DateFilter += date.getUTCMilliseconds();
 DateFilter += "Z\'";
 return DateFilter;
}

次の方法で共有

Ajax および JScript Web リソースで OData エンドポイントを使用する

このトピックの内容

Ajax

JSON

XmlHttpRequest

POST によるメソッドトンネリング

サーバー URL にアクセスする

XmlHttpRequest の使用

JQuery の使用

要求ヘッダーを明示的に設定して JSON を許可する

要求ヘッダーを異なる HTTP アクションに対して明示的に設定する

エラーを処理する

処理結果

日付に関する作業

取得済みデータの解析

JSON.parse メソッドで reviver 関数を使用する

String.replace を使用して文字列から日付値を生成する

日付値の表示

日付値の更新

日付をクエリ内のフィルターで条件として設定する

関連項目

その他のリソース

次の方法で共有

Ajax および JScript Web リソースで OData エンドポイントを使用する

このトピックの内容

Ajax

JSON

XmlHttpRequest

POST によるメソッド トンネリング

サーバー URL にアクセスする

XmlHttpRequest の使用

JQuery の使用

要求ヘッダーを明示的に設定して JSON を許可する

要求ヘッダーを異なる HTTP アクションに対して明示的に設定する

エラーを処理する

処理結果

日付に関する作業

取得済みデータの解析

JSON.parse メソッドで reviver 関数を使用する

String.replace を使用して文字列から日付値を生成する

日付値の表示

日付値の更新

日付をクエリ内のフィルターで条件として設定する

関連項目

その他のリソース

POST によるメソッドトンネリング