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 分かかります。 個人データは収集されません (プライバシー ステートメント)。
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示