Web API ポータルを使用したクエリ データ

  • [アーティクル]

注意

2022 年 10 月 12 日より、Power Apps ポータルは Power Pages となります。 詳細: Microsoft Power Pages の一般提供が開始されました (ブログ)
Power Apps ポータルのドキュメントは、近日中に Power Pages ドキュメントに移行、統合されます。

ポータルで 利用可能な Web API 操作 を使用できます。 Web API 操作は、HTTP リクエストとレスポンスで構成されています。 この記事では、HTTP 要求で使用できるサンプルの読み取り操作、メソッド、URI、サンプル JSON について説明します。

前提条件

  • ポータルのバージョンは 9.4.1.x 以上である必要があります。

  • Web API 操作のテーブルとフィールドを有効にします。 詳細:Web API のサイト設定

  • ポータル Web API は、テーブル レコードにアクセスし、関連した Web ロール からユーザーに与えられたテーブルのアクセス許可に従います。 正しいテーブル アクセス許可を構成していることを確認してください。 詳細: Web ロールを作成する

注意

ポータルの Web API を使用して Dataverse テーブルを参照する場合、EntitySetName を使用する必要があります。例えば、account テーブルにアクセスする場合、コード構文では アカウント の EntitySetName が使用されます。

レコードをクエリする

次の例では、取引先企業レコードをクエリします。

操作 Method URI
テーブル レコードを取得する GET [Portal URI]/_api/accounts

例:
 https://contoso.powerappsportals.com/_api/accounts

サンプル応答

{
"value": [
    {
    "@odata.etag": "W/\"1066412\"",
    "name": "Fourth Coffee (sample)",
    "accountid": "d2e11ba8-92f6-eb11-94ef-000d3a5aa607"
    },
    {
    "@odata.etag": "W/\"1066413\"",
    "name": "Litware, Inc. (sample)",
    "accountid": "d4e11ba8-92f6-eb11-94ef-000d3a5aa607"
    }
]
}

$select と $top システム クエリ オプションを使って、最初の 3 つのアカウントの name プロパティを返します。

操作 Method URI
最初の 3 つのエンティティ レコードを取得する GET [Portal URI]/_api/accounts?$select=name,revenue&$top=3

用例:
https://contoso.powerappsportals.com/_api/accounts?$select=name,revenue&$top=3

取引先企業 ID を使用して取引先企業を取得します。

操作 Method URI
レコードの特定のプロパティを取得する GET [Portal URI]/_api/accounts(e0e11ba8-92f6-eb11-94ef-000d3a5aa607)?$select=name

用例:
https://contoso.powerappsportals.com/_api/accounts(e0e11ba8-92f6-eb11-94ef-000d3a5aa607)?$select=name

サンプル応答

{
    "@odata.etag": "W/\"1066414\"",
    "name": "Adventure Works (sample)",
    "accountid": "d6e11ba8-92f6-eb11-94ef-000d3a5aa607"
}

システム クエリ オプションの適用

エンティティ セットのために URL に追加する各システム クエリ オプションは、クエリ文字列の構文を使用して追加されます。 最初のクエリは [?] の後に追加され、それ以降のクエリ オプションは [&] を使用して分離されます。 すべてのクエリ オプションは、次の例のように大文字と小文字が区別されます。

Method URI
GET [Portal URI]/_api/accounts?$select=name,revenue&$filter=revenue gt 90000&$top=3

用例:
https://contoso.powerappsportals.com/_api/accounts?$select=name,revenue&$filter=revenue gt 90000&$top=3

特定のプロパティの要求

 $select  システム クエリ オプションを使用して、以下の例に示すように、返されるプロパティを制限します。

Method URI
GET [Portal URI]/_api/accounts?$select=name,revenue&$top=3

用例:
https://contoso.powerappsportals.com/_api/accounts?$select=name,revenue&$top=3

重要

これはパフォーマンスのベスト プラクティスです。 プロパティが指定されておらず、Webapi/<table name>/fields サイト設定値を * に構成した場合、すべてのプロパティは $select を使用して返されます。 プロパティが指定されていない場合、エラーが返されます。

結果のフィルター

 $filter  システム クエリ オプションを使用して、行が返される条件を設定します。

標準フィルタ演算子

Web API は、以下の表にリストされる標準 OData フィルター演算子をサポートしています。

Operator 内容 例
比較演算子
eq 等しい $filter=revenue eq 100000
ne 等しくない $filter=revenue ne 100000
gt より大きい $filter=revenue gt 100000
ge 以上 $filter=revenue ge 100000
lt より小さい $filter=revenue lt 100000
le 以下 $filter=revenue le 100000
論理演算子
and 論理積 $filter=revenue lt 100000 and revenue gt 2000
or 論理和 $filter=contains(name,'(sample)') or contains(name,'test')
not 論理否定 $filter=not contains(name,'sample')
グループ化演算子
( ) 優先順位によるグループ化 (contains(name,'sample') or contains(name,'test')) and revenue gt 5000

標準クエリ機能

Web API では、以下の標準 OData 文字列クエリ機能がサポートされています。

関数 例
が次の値を含む $filter=contains(name,'(sample)')
指定の値で終わる $filter=endswith(name,'Inc.')
指定の値で始まる $filter=startswith(name,'a')

Dataverse クエリ関数

Web API は、結果をフィルタリングする Dataverse クエリ関数をサポートします。 詳細については、Web API クエリ関数参照 を参照してください。

結果を並べ替える

項目が返される順番を、 $orderby  システム クエリ オプションを使用して指定します。  asc  または  desc  サフィックスを使用して、それぞれ昇順または降順を指定します。 接尾辞が適用されない場合、既定は昇順です。 以下の例では、取引先企業の名前および売り上げプロパティを、売り上げを昇順で、名前を降順で取得します。

Method URI
GET [Portal URI]/_api/accounts?$select=name,revenue&$orderby=name asc,revenue desc&$filter=revenue gt 90000

用例:
https://contoso.powerappsportals.com/_api/accounts?$select=name,revenue&$orderby=name asc,revenue desc&$filter=revenue gt 90000

結果の集計およびグループ化

 $apply,  を使用することにより、次の例に示すように、データを動的に集約およびグループ化できます。

シナリオ 例
クエリ内の一意のステータスのリスト accounts?$apply=groupby((statuscode))
予想値合計の集計 opportunities?$apply=aggregate(estimatedvalue with sum as total)
予想値およびステータスに基づく取引の平均サイズ opportunities?$apply=groupby((statuscode),aggregate(estimatedvalue with average as averagevalue)
ステータスに基づく予測値の合計 opportunities?$apply=groupby((statuscode),aggregate(estimatedvalue with sum as total))
アカウント名ごとの営業案件の売上合計 opportunities?$apply=groupby((parentaccountid/name),aggregate(estimatedvalue with sum as total))
「WA」 の取引先企業の取引先責任者名 accounts?$apply=filter(address1_stateorprovince eq 'WA')/groupby((primarycontactid/fullname))
最後に作成されたレコードの日時 accounts?$apply=aggregate(createdon with max as lastCreate)
最初に作成されたレコードの日時 accounts?$apply=aggregate(createdon with min as firstCreate)

行数の取得

 $count  システム クエリ オプションを True の値と共に使用して、フィルター条件と一致するエンティティ数を最大 5000 含めます。

Method URI
GET [Portal URI/_api/accounts?$select=name&$filter=contains(name,'sample')&$count=true

用例:
https://contoso.powerappsportals.com/_api/accounts?$select=name&$filter=contains(name,'sample')&$count=true

サンプル応答

{
"@odata.count": 10,
"value": [
    {
    "@odata.etag": "W/\"1066412\"",
    "name": "Fourth Coffee (sample)",
    "accountid": "d2e11ba8-92f6-eb11-94ef-000d3a5aa607"
    },
    {
    "@odata.etag": "W/\"1066413\"",
    "name": "Litware, Inc. (sample)",
    "accountid": "d4e11ba8-92f6-eb11-94ef-000d3a5aa607"
    },
    {
    "@odata.etag": "W/\"1066414\"",
    "name": "Adventure Works (sample)",
    "accountid": "d6e11ba8-92f6-eb11-94ef-000d3a5aa607"
    }
]
}

カウント以外のデータを返さないようにするには、 $count  を任意のコレクションに適用して、値のみを取得します。

Method URI
GET [Portal URI/_api/accounts/$count

用例:
https://contoso.powerappsportals.com/_api/accounts/$count

サンプル応答

3

列の比較

次の例は、Web API を使用して列を比較する方法を示しています。

Method URI
取得 [Portal URI]/_api/contacts?$select=firstname&$filter=firstname eq lastname

用例:
https://contoso.powerappsportals.com/_api/contacts?$select=firstname&$filter=firstname eq lastname

クエリで関連テーブル レコードを取得する

ナビゲーション プロパティの  $expand  システム クエリ オプションを使用して、関連エンティティからどのデータが返されるかをコントロールします。

関連付けられたナビゲーション プロパティの参照

$expand クエリ オプションを使用するときのルックアップ属性として、Microsoft.Dynamics.CRM.associatednavigationproperty を使用する必要があります。

属性の Microsoft.Dynamics.CRM.associatednavigationproperty を判断するには、命名規則 _name_value を使用して、列に対して次の http GET 要求を行うことができます。

次の例では、リクエスト (_primarycontactid_value) で名前をフォーマットすることで列名 primarycontactid を指定して、取引先企業テーブルの取引先責任者列の関連付けられているナビゲーション プロパティを判断できます。

Method URI
取得 [Portal URI]/_api/accounts?$select=_primarycontactid_value

例
https://contoso.powerappsportals.com/_api/accounts?$select=_primarycontactid_value

サンプル応答

{
"value": [
    {
        "@odata.etag": "W/\"2465216\"",
        "_primarycontactid_value@OData.Community.Display.V1.FormattedValue": "Yvonne McKay (sample)",
        "_primarycontactid_value@Microsoft.Dynamics.CRM.associatednavigationproperty": "primarycontactid",
        "_primarycontactid_value@Microsoft.Dynamics.CRM.lookuplogicalname": "contact",
        "_primarycontactid_value": "417319b5-cd18-ed11-b83c-000d3af4d812",
        "accountid": "2d7319b5-cd18-ed11-b83c-000d3af4d812"
    }
]
}

応答から、関連するナビゲーション プロパティが primarycontactid であることがわかります。 関連するナビゲーション プロパティは、テーブルの作成方法に応じて、ルックアップ列の論理名またはスキーマ名 になります。

詳細については、検索プロパティに関するデータの取得 を参照してください。

単一値のナビゲーション プロパティの拡張による関連テーブル レコードの取得

以下の例は、すべての取引先企業レコードの取引先担当者を取得する方法を示しています。 関連する取引先担当者レコードの場合、contactid および fullname のみを取得します。

Method URI
取得 [Portal URI]/_api/accounts?$select=name&$expand=primarycontactid($select=contactid,fullname)

用例:
https://contoso.powerappsportals.com/_api/accounts?$select=name&$expand=primarycontactid($select=contactid,fullname)

サンプル応答

{
"value": [
    {
    "@odata.etag": "W/\"1066412\"",
    "name": "Fourth Coffee (sample)",
    "accountid": "d2e11ba8-92f6-eb11-94ef-000d3a5aa607",
        "primarycontactid": {
        "contactid": "e6e11ba8-92f6-eb11-94ef-000d3a5aa607",
        "fullname": "Yvonne McKay (sample)"
        }
    },
    {
    "@odata.etag": "W/\"1066413\"",
    "name": "Litware, Inc. (sample)",
    "accountid": "d4e11ba8-92f6-eb11-94ef-000d3a5aa607",
        "primarycontactid": {
        "contactid": "e8e11ba8-92f6-eb11-94ef-000d3a5aa607",
        "fullname": "Susanna Stubberod (sample)"
        }
    }
]
}

コレクション値ナビゲーション プロパティの拡張による関連テーブルの取得

コレクション値ナビゲーション パラメーターを拡張してエンティティ セットの関連テーブルを取得すると、データがある場合、1 レベルの深さのみ返されます。 それ以外の場合、コレクションは空の配列を返します。

Method URI
GET [Portal URI]/_api/accounts?$top=5&$select=name&$expand=Account_Tasks($select=subject,scheduledstart)

用例:
https://contoso.powerappsportals.com/_api/accounts?$top=5&$select=name&$expand=Account_Tasks($select=subject,scheduledstart)

単一値とコレクション値の両方のナビゲーション プロパティを拡張して、関連テーブルを取得します

次の例では、単一値とコレクション値の両方のナビゲーション プロパティを使用して、エンティティセットの関連エンティティを拡張する方法を示します。 コードの構文で、テーブル関係名 を指定する必要があります。

Method URI
GET [Portal URI]/_api/accounts?$top=5&$select=name&$expand=primarycontactid($select=contactid,fullname),Account_Tasks($select=subject,scheduledstart)

用例:
https://contoso.powerappsportals.com/_api/accounts?$top=5&$select=name&$expand=primarycontactid($select=contactid,fullname),Account_Tasks($select=subject,scheduledstart)

次の手順

ポータルは、Web API を使用して操作を書き込み、更新、および削除します

参照

ポータル Web API の概要
チュートリアル: ポータル Web API を使用する
列のアクセス許可を構成する

注意

ドキュメントの言語設定についてお聞かせください。 簡単な調査を行います。 (この調査は英語です)

この調査には約 7 分かかります。 個人データは収集されません (プライバシー ステートメント)。