前回に引き続き、今回は Web API を使うサンプルを解説します。

Common Data Service (CDS) Web API

まずは CDS Web　API について紹介します。CDS Web API は、データの操作を中心に、CDS に関わる機能を実行することができる開発者向け API です。内容は Dynamics CE Web API と同じです。
参照: Common Data Service Web API の使用

エンティティのメタデータ提供
レコードの CRUD 操作
データのクエリ
レコードの関連付けなどユーザー関数の実行
重複検出などのシステム関数の実行

PowerApps Component Framework (PCF) でもこの CDS Web API をコンテキストから取得して利用することができ、内部的にレコード操作など様々なアクションが実行できるようになっています。

FetchXML

サンプルにも出てますが、CDS/Dynamics CE のレコードをクエリする際、REST/OData クエリの他に、独自実装であるFetxhML というクエリが利用できます。これはクエリを XML 形式で記述するもので、集計クエリを書いたりもできます。

FetchXML の使用によるクエリの作成

サンプルの概要

今回のサンプルは特定のフィールドの値を操作するものではなく、各種ボタンをクリックした際にレコードの作成や削除など、Web API で出来ることを実行するコントロールです。

プロジェクトの作成

今回も既に作成した SampleSolution に追加するように開発していきます。

1. 前回まで作ってきた PCFControls フォルダに移動して、フィールド用のコントロールを作成。

mkdir WebAPIControl
cd WebAPIControl

2. 以下のコマンドを実行してプロジェクトを作成。

名前空間とプロジェクト名の指定
template 引数は field を指定

pac pcf init --namespace SampleNamespace --name TSWebAPI --template field

3. npm パッケージをリストアして任意の IDE でフォルダを開く。ここでは Visual Studio Code を利用。

npm install
code .

コントロールマニフェストの編集とリソースの追加

これまで同様にまずはマニフェストから編集します。

1. ControlManifest.Input.xml を以下の様に編集。

文字列フィールドにバインド
resources に ts と css、既定の画像を指定
uses-feature で WebAPI を指定

ControlManifest.Input.xml

<?xml version="1.0" encoding="utf-8" ?>
<manifest>
    <control namespace="SampleNamespace" constructor="TSWebAPI" 
    version="1.0.0" 
    display-name-key="Web API Sample Control" 
    description-key="Web API Sample Control" 
    control-type="standard">
        <property name="stringProperty" 
      display-name-key="Text Field to bind the control" 
      description-key="Text Field to bind the control" 
      of-type="SingleLine.Text" usage="bound" required="true" />
        <resources>
            <code path="index.ts" order="1" />
            <css path="css/TS_WebAPI.css" order="2" />
        </resources>
        <feature-usage>
            <uses-feature name="WebAPI" required="true" />
        </feature-usage>
    </control>
</manifest>

2. ファイルの作成から css フォルダパスを含めて TS_WebAPI.css を作成。中身を以下に差し替え。

TS_WebAPI.css

.SampleNamespace\.TSWebAPI
{
    font-family: 'SegoeUI-Semibold', 'Segoe UI Semibold', 'Segoe UI Regular', 'Segoe UI';
    color: #1160B7;
}

.SampleNamespace\.TSWebAPI .TSWebAPI_Container
{
    overflow-x: auto;
}

.SampleNamespace\.TSWebAPI .SampleControl_WebAPI_Header
{
    color: rgb(51, 51, 51);
    font-size: 1rem;
    padding-top: 20px;
}

.SampleNamespace\.TSWebAPI .result_container
{
    padding-bottom: 20px;
}

.SampleNamespace\.TSWebAPI .SampleControl_WebAPI_ButtonClass
{
    text-decoration: none;
    display: inline-block;
    font-size: 14px;
    cursor: pointer;
    color: #1160B7;
    background-color: #FFFFFF;
    border: 1px solid black;
    padding: 5px;
    text-align: center;
    min-width: 300px;
    margin-top: 10px;
    margin-bottom: 5px;
    display: block;
}

3. ターミナルより以下コマンドでビルドを実行。

npm run build

index.ts の編集

1. まずは import の追加と定数の定義。

import {IInputs, IOutputs} from "./generated/ManifestTypes";

2. クラスとプロパティの定義。

export class TSWebAPI implements ComponentFramework.StandardControl<IInputs, IOutputs>
{
    // コンテキスト
    private _context: ComponentFramework.Context<IInputs>;
    // コントロールをホストするコンテナ
    private _container: HTMLDivElement;
    // Web API で操作するエンティティの論理名
    private static _entityName:string = "account";
    // Web API で作成するエンティティの名前フィールド
    private static _requiredAttributeName: string = "name";
    // Web API で作成するエンティティの名前フィールドの値
    private static _requiredAttributeValue: string = "Web API Custom Control (Sample)";
    // Web API で作成するエンティティの Revenue フィールド
    private static _currencyAttributeName: string = "revenue";
    // コントロール描写完了フラグ
    private _controlViewRendered: Boolean;
    // 各種ボタン
    private _createEntity1Button: HTMLButtonElement;
    private _createEntity2Button: HTMLButtonElement;
    private _createEntity3Button: HTMLButtonElement;
    private _deleteRecordButton: HTMLButtonElement;
    private _fetchXmlRefreshButton: HTMLButtonElement;
    private _oDataRefreshButton: HTMLButtonElement;
    // 結果を保持するエレメント
    private _odataStatusContainerDiv: HTMLDivElement;
    private _resultContainerDiv: HTMLDivElement;
}

3. init 初期化メソッドを追加。

/**
* init メソッド
* @param context : 各種オブジェクトや API へのアクセスを提供するコンテキスト
* @param notifyOutputChanged : 出力変更通知のコールバック
* @param state : 前回保存したステート
* @param container : UI コントロールを保持するコンテナ
*/
public init(context: ComponentFramework.Context<IInputs>, notifyOutputChanged: () => void, state: ComponentFramework.Dictionary, container:HTMLDivElement)
{
    this._context = context;
    this._controlViewRendered = false;
    this._container = document.createElement("div");
    this._container.classList.add("TSWebAPI_Container");
    container.appendChild(this._container);
}

4. PCF からの変更通知を処理する updateView メソッドを追加。

public updateView(context: ComponentFramework.Context<IInputs>): void
{
    if (!this._controlViewRendered)
    {       
        // 各種ボタンの追加
        this.renderCreateExample();
        this.renderDeleteExample();
        this.renderFetchXmlRetrieveMultipleExample();
        this.renderODataRetrieveMultipleExample();
        // Web API の結果を表示
        this.renderResultsDiv();
        this._controlViewRendered = true;
    }
}

5.　各種ボタンの描写メソッドである renderCreateExample、renderDeleteExample、renderFetchXmlRetrieveMultipleExample、renderODataRetrieveMultipleExample、renderResultsDiv を追加。

private renderCreateExample() : void
{
    // ヘッダーを追加
    let headerDiv: HTMLDivElement = this.createHTMLDivElement("create_container", true, 
        "クリックして取引先企業レコードを作成");
    this._container.appendChild(headerDiv);
    // Revenue 100 でレコード作成するボタン 1 の作成
    let value1:string = "100";
    this._createEntity1Button = this.createHTMLButtonElement(
        this.getCreateRecordButtonLabel(value1),
        this.getCreateButtonId(value1),
        value1,
        this.createButtonOnClickHandler.bind(this));
    // Revenue 200 でレコード作成するボタン 2 の作成
    let value2:string = "200";
    this._createEntity2Button = this.createHTMLButtonElement(
        this.getCreateRecordButtonLabel(value2),
        this.getCreateButtonId(value2),
        value2,
        this.createButtonOnClickHandler.bind(this));
    // Revenue 300 でレコード作成するボタン 3 の作成
    let value3:string = "300";
    this._createEntity3Button = this.createHTMLButtonElement(
        this.getCreateRecordButtonLabel(value3),
        this.getCreateButtonId(value3),
        value3,
        this.createButtonOnClickHandler.bind(this));
    this._container.appendChild(this._createEntity1Button);
    this._container.appendChild(this._createEntity2Button);
    this._container.appendChild(this._createEntity3Button);
}

private renderDeleteExample() : void
{
    // ヘッダーを追加
    let headerDiv: HTMLDivElement = this.createHTMLDivElement("delete_container", true, 
        "クリックして取引先企業を削除");  
    this._container.appendChild(headerDiv);
    // 削除ボタンの追加
    this._deleteRecordButton = this.createHTMLButtonElement(
        "削除するレコードを選択",
        "delete_button",
        null,
        this.deleteButtonOnClickHandler.bind(this));
    this._container.appendChild(this._deleteRecordButton);
}

private renderODataRetrieveMultipleExample() : void
{
    // ヘッダーを追加
    let containerClassName: string = "odata_status_container";
    let statusDivHeader: HTMLDivElement = this.createHTMLDivElement(containerClassName, true, 
        "リストの更新");  
    this._container.appendChild(statusDivHeader);
    // 結果コンテナの追加
    this._odataStatusContainerDiv = this.createHTMLDivElement(containerClassName, false, undefined);    
    this._container.appendChild(this._odataStatusContainerDiv);
    // RetrieveMultiple 実行ボタンの作成
    this._fetchXmlRefreshButton = this.createHTMLButtonElement(
        "レコード数の更新",
        "odata_refresh",
        null,
        this.refreshRecordCountButtonOnClickHandler.bind(this));
    this._container.appendChild(this._fetchXmlRefreshButton);
}

private renderFetchXmlRetrieveMultipleExample() : void
{
    // ヘッダーを追加
    let containerName: string = "fetchxml_status_container";
    let statusDivHeader: HTMLDivElement = this.createHTMLDivElement(containerName, true, 
        "クリックして Revenue の平均を取得");   
    this._container.appendChild(statusDivHeader);
    let statusDiv: HTMLDivElement = this.createHTMLDivElement(containerName, false, undefined); 
    this._container.appendChild(statusDiv);
    // RetrieveMultiple 実行ボタンの作成
    this._oDataRefreshButton = this.createHTMLButtonElement(
        "Revenue の平均を計算",
        "odata_refresh",
        null,
        this.calculateAverageButtonOnClickHandler.bind(this));
    this._container.appendChild(this._oDataRefreshButton);
}

private renderResultsDiv()
{
    // ヘッダーを追加
    let resultDivHeader: HTMLDivElement = this.createHTMLDivElement("result_container", true, 
        "結果");
    this._container.appendChild(resultDivHeader);
    // 結果用ラベルの追加
    this._resultContainerDiv = this.createHTMLDivElement("result_container", false, undefined);
    this._container.appendChild(this._resultContainerDiv);
    // 結果ラベルの更新
    this.updateResultContainerText("準備完了");
}

6. レコード作成処理である createButtonOnClickHandler メソッドを追加。

context.webAPI より各種アクションの実行

private createButtonOnClickHandler(event: Event): void
{
    // ボタンのラベルより Revenue の値を取得
    let currencyAttributeValue:Number = parseInt(
        (event.srcElement! as Element)!.attributes.getNamedItem("buttonvalue")!.value
    );

    // 名前がユニークになるように日付を追加
    let recordName: string = TSWebAPI._requiredAttributeValue + "_" + Date.now();
    // レコードのフィールドと値を追加
    var data: any = {};
    data[TSWebAPI._requiredAttributeName] = recordName;
    data[TSWebAPI._currencyAttributeName] = currencyAttributeValue;
    // コールバック内で利用するため this を一時的に格納
    var thisRef = this;
    // Web API でレコードを作成
    this._context.webAPI.createRecord(TSWebAPI._entityName, data).then
    (
        function (response: ComponentFramework.EntityReference) 
        {
            //　作成されたレコードをの結果を作成
            let id: string = response.id;
            let resultHtml: string = TSWebAPI._entityName + " レコードが以下の値で作成されました。"
            resultHtml += "<br />";
            resultHtml += "<br />";
            resultHtml += "id: " + id;
            resultHtml += "<br />";
            resultHtml += "<br />";
            resultHtml += TSWebAPI._requiredAttributeName + ": " + recordName;
            resultHtml += "<br />";
            resultHtml += "<br />";
            resultHtml += TSWebAPI._currencyAttributeName + ": " + currencyAttributeValue;
            thisRef.updateResultContainerText(resultHtml);
        },
        function (errorResponse: any) 
        {
            // エラーのハンドル
            thisRef.updateResultContainerTextWithErrorResponse(errorResponse);
        }
    );
}

7. レコードの削除処理を追加。

context.utils.lookupObjects : 指定したエンティティの検索

private deleteButtonOnClickHandler() : void
{
    // Lookpu を起動して削除するレコードを選択
    var lookUpOptions: any =
    {
        entityTypes: [TSWebAPI._entityName]
    };
    // コールバック内で利用するため this を一時的に格納
    var thisRef = this;
    // context.util.lookupObjects でレコード参照を起動
    var lookUpPromise: any = this._context.utils.lookupObjects(lookUpOptions);
    lookUpPromise.then
    (
        // Lookup の結果
        (data: ComponentFramework.EntityReference[]) =>
        {
            if (data && data[0])
            {
                // 選択されたレコードの Id とエンティティタイプを取得
                let id: string = data[0].id;
                let entityType: string = data[0].entityType!;
                // Web API でレコードの削除
                this._context.webAPI.deleteRecord(entityType, id).then
                (
                    function (response: ComponentFramework.EntityReference) 
                    {
                        // 削除成功のメッセージを表示
                        let responseId: string = response.id;   
                        let responseEntityType: string = response.entityType!;
                        // Generate HTML to inject into the result div to showcase the deleted record 
                        thisRef.updateResultContainerText("エンティティ:" + responseEntityType + " ID: " + responseId + "のレコードを削除しました。");
                    },
                    function (errorResponse: any) 
                    {
                        // Error handling code here
                        thisRef.updateResultContainerTextWithErrorResponse(errorResponse);
                    }
                );
            }
        },
        (error: any) =>
        {
            // エラーのハンドル
            thisRef.updateResultContainerTextWithErrorResponse(error);
        }
    );
}

8. FetchXML の実行を行う calculateAverageButtonOnClickHandler メソッドを追加。

retrieveMultipleRecords に fetchXml パラメーター指定

private calculateAverageButtonOnClickHandler() : void
{
    // 集計 FetchXML を作成
    let fetchXML: string = "<fetch distinct='false' mapping='logical' aggregate='true'>";
    fetchXML += "<entity name='" + TSWebAPI._entityName + "'>";
    fetchXML += "<attribute name='" + TSWebAPI._currencyAttributeName + "' aggregate='avg' alias='average_val' />";
    fetchXML += "<filter>";
    fetchXML += "<condition attribute='" + TSWebAPI._currencyAttributeName + "' operator='not-null' />";
    fetchXML += "</filter>";
    fetchXML += "</entity>";
    fetchXML += "</fetch>";
    // コールバック内で利用するため this を一時的に格納
    var thisRef = this;
    // Web API で RetrieveMultipleRecords を実行
    this._context.webAPI.retrieveMultipleRecords(TSWebAPI._entityName, "?fetchXml=" + fetchXML).then
    (
        function (response: ComponentFramework.WebApi.RetrieveMultipleResponse) 
        {
            // 結果を取得して画面に表示 
            let averageVal:Number = response.entities[0].average_val;
            // Generate HTML to inject into the result div to showcase the result of the RetrieveMultiple Web API call
            let resultHTML: string = "取得した取引先企業の Revenue 平均は " + averageVal;
            thisRef.updateResultContainerText(resultHTML);
        },
        function (errorResponse: any) 
        {
            // エラーのハンドル
            thisRef.updateResultContainerTextWithErrorResponse(errorResponse);
        }
    );
}

9. REST エンドポイントを実行する refreshRecordCountButtonOnClickHandler メソッドを追加。

private refreshRecordCountButtonOnClickHandler() : void
{
    // OData クエリの咲く絵師
    let queryString: string = "?$select=" + TSWebAPI._currencyAttributeName + "&$filter=contains(" + TSWebAPI._requiredAttributeName + 
        ",'" + TSWebAPI._requiredAttributeValue + "')";
    // コールバック内で利用するため this を一時的に格納
    var thisRef = this;
    // レコードの取得
    this._context.webAPI.retrieveMultipleRecords(TSWebAPI._entityName, queryString).then
    (
        function (response: any) 
        {
            let count1: number = 0;
            let count2: number = 0;
            let count3: number = 0;
            // 取得したレコードを順次処理して集計
            for (let entity of response.entities)
            {
                // 取得したレコードの Revenue 列の値
                let value:Number = entity[TSWebAPI._currencyAttributeName];
                // 同じ値のレコード数をカウント
                if (value == 100)
                {
                    count1++;
                }
                else if (value == 200)
                {
                    count2++;
                }
                else if (value == 300)
                {
                    count3++;
                }
            }
            // 結果を HTML で表現
            let innerHtml: string = "Use above buttons to create or delete a record to see count update";
            innerHtml += "<br />";
            innerHtml += "<br />";
            innerHtml += "値が 100 のレコードは" + count1 + "件";
            innerHtml += "<br />";
            innerHtml += "値が 200 のレコードは" + count2 + "件";
            innerHtml += "<br />";
            innerHtml += "値が 300 のレコードは" + count3 + "件";
            // 結果をコントロールに追加
            if (thisRef._odataStatusContainerDiv)
            {
                thisRef._odataStatusContainerDiv.innerHTML = innerHtml;
            }
            thisRef.updateResultContainerText("レコードカウントの更新完了");
        },
        function (errorResponse: any) 
        {
            // エラーのハンドル
            thisRef.updateResultContainerTextWithErrorResponse(errorResponse);
        }
    );
}

10. その他の画面描写用プライベートメソッドの追加。

private updateResultContainerText(statusHTML: string) : void
{   
    if (this._resultContainerDiv)
    {
        this._resultContainerDiv.innerHTML = statusHTML;
    }
}

private updateResultContainerTextWithErrorResponse(errorResponse: any) : void
{
    if (this._resultContainerDiv)
    {
        // Retrieve the error message from the errorResponse and inject into the result div
        let errorHTML: string = "Web API call でエラー:";
        errorHTML += "<br />"
        errorHTML += errorResponse.message;
        this._resultContainerDiv.innerHTML = errorHTML;
    }
}

private getCreateRecordButtonLabel(entityNumber: string): string
{
    return "値" + entityNumber + "でレコードを作成";
}

private getCreateButtonId(entityNumber: string): string
{
    return "create_button_" + entityNumber;
}

private createHTMLButtonElement(buttonLabel: string, buttonId: string, buttonValue: string | null, onClickHandler: (event?: any) => void): HTMLButtonElement
{
    let button: HTMLButtonElement = document.createElement("button");
    button.innerHTML = buttonLabel;
    if (buttonValue)
    {
        button.setAttribute("buttonvalue", buttonValue);
    }
    button.id = buttonId;
    button.classList.add("SampleControl_WebAPI_ButtonClass");
    button.addEventListener("click", onClickHandler);
    return button;
}

private createHTMLDivElement(elementClassName: string, isHeader: boolean, innerText?: string): HTMLDivElement
{
    let div: HTMLDivElement = document.createElement("div");
    if(isHeader)
    {
        div.classList.add("SampleControl_WebAPI_Header");
        elementClassName += "_header";
    }
    if (innerText)
    {
        div.innerText = innerText.toUpperCase();
    }
    div.classList.add(elementClassName);
    return div;
}

11. 必須である getOutputs と destroy メソッドを追加。

public getOutputs(): IOutputs
{
    return {};
}

public destroy()
{
}

コントロールのパッケージ化と配布

これまでと同じ方法でパッケージ化と配布を実行。

1. SampleSolution フォルダに移動し、以下のコマンドを実行。

pac solution add-reference --path ../WebAPIControl

2. SampleSolution\Other\Solution.xml でバージョン情報を更新。

3. 以下コマンドでパッケージをビルド。

msbuild /restore
msbuild /p:configuration=Release

4. https://make.powerapps.com に接続。管理者権限でログイン。すでに SampleSolution を入れた環境で Solutions を選択し、Import をクリック。コンパイルした zip をインポート。インポート時にパッケージが更新される旨が表示されるので、そのまま次へ。