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

[アーティクル]
12/26/2024

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

前提条件

Web サイトのバージョンは 9.4.1.x 以上である必要があります。
Web API 操作のテーブルとフィールドを有効にします。詳細:Web API のサイト設定
ポータル Web API は、テーブルレコードにアクセスし、関連した Web ロールからユーザーに与えられたテーブルのアクセス許可に従います。正しいテーブルアクセス許可を構成していることを確認してください。詳細: Web ロールを作成する

注意

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

レコードをクエリする

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

操作	Method	URI
テーブルレコードを取得する	取得	`[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 つのエンティティレコードを取得する	取得	`[Portal URI]/_api/accounts?$select=name,revenue&$top=3` 例: `https://contoso.powerappsportals.com/_api/accounts?$select=name,revenue&$top=3`

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

操作	Method	URI
レコードの特定のプロパティを取得する	取得	`[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
取得	`[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
取得	`[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
取得	`[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
取得	`[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
取得	`[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 システムクエリオプションを使用して、関連エンティティからどのデータが返されるかをコントロールします。

クエリオプションを使用する場合は、検索属性として Microsoft.Dynamics.CRM.associatednavigationproperty $expand クエリを使用する必要があります。

属性の 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
取得	`[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
取得	`[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)`

FetchXml を使用してレコードをクエリする

FetchXml クエリパラメーターを使用して、FetchXml クエリを URL エンコードされた文字列値としてエンティティセットコレクションに渡します。

たとえば、アカウントエンティティセットからデータを取得するには、エンティティ要素名パラメーターをアカウントに設定する FetchXml クエリを作成します。

<fetch top='2'>
  <entity name='account'>
      <attribute name='name' />
  </entity>
</fetch>

前のクエリの URL エンコードされた文字列は次のとおりです。

%3Cfetch%20top%3D%275%27%3E%0D%0A%3Centity%20name%3D%27account%27%3E%0D%0A%3Cattribute%20name%3D%27name%27%2F%3E%0D%0A%3C%2Fentity%3E%0D%0A%3C%2Ffetch%3E

Method	URI
取得	`[Portal URI]/_api/accounts?fetchxml` 例: `https://contoso.powerappsportals.com/_api/accounts?fetchXml=%3Cfetch%20top%3D%275%27%3E%0D%0A%3Centity%20name%3D%27account%27%3E%0D%0A%3Cattribute%20name%3D%27name%27%2F%3E%0D%0A%3C%2Fentity%3E%0D%0A%3C%2Ffetch%3E`

サンプル応答

{
  "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)"
      }
    }
  ]
}

次の手順

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

次の方法で共有

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

前提条件

レコードをクエリする

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

特定のプロパティの要求

結果のフィルター

標準フィルタ演算子

標準クエリ機能

Dataverse クエリ関数

結果を並べ替える

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

行数の取得

列の比較

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

FetchXml を使用してレコードをクエリする

次の手順

参照

フィードバック

その他のリソース

次の方法で共有

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

前提条件

レコードをクエリする

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

特定のプロパティの要求

結果のフィルター

標準フィルタ演算子

標準クエリ機能

Dataverse クエリ関数

結果を並べ替える

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

行数の取得

列の比較

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

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

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

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

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

FetchXml を使用してレコードをクエリする

次の手順

参照

フィードバック

その他のリソース

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

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

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

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

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

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

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