Web API を使用してテーブルの行を取得する
GET 要求を使用して、一意の識別子を持つリソースとして指定されたレコードのデータを取得します。 テーブルの行 (エンティティ レコード) を取得するときに、特定のプロパティを要求し、ナビゲーション プロパティを展開して、異なるテーブルの関連レコードからプロパティを返すこともできます。
注意
テーブル定義の取得については、Web API を使用してテーブル定義をクエリする を参照してください。
基本的な取得
次の例では、主キーの値が 00000000-0000-0000-0000-000000000001 である取引先企業エンティティ レコードのデータが返されます。
GET [Organization URI]/api/data/v9.2/accounts(00000000-0000-0000-0000-000000000001)
この例では、取引先企業レコードのすべてのプロパティが返されますが、これはパフォーマンスのベスト プラクティスではありません。 データを取得する際に返されるプロパティを制限するためには、$select システム クエリ オプションを使用する必要があります。 これは、複数行のデータを取得する場合に特に重要です。 詳細: Web API を使用するクエリ データ
特定のプロパティの取得
GET 要求を使用してデータを取得する場合に返されるプロパティを制限するには、プロパティ名のコンマ区切りリストで $select システム クエリ オプションを使用します。 必要なプロパティのみを要求することは、重要なパフォーマンスのベスト プラクティスです。 返すプロパティを指定しない場合は、すべてのプロパティが返されます。
次の例では、00000000-0000-0000-0000-000000000001 に等しい主キーの値を含むアカウント エンティティの name および revenue プロパティを取得します。
要求:
GET [Organization URI]/api/data/v9.2/accounts(00000000-0000-0000-0000-000000000001)?$select=name,revenue HTTP/1.1
Accept: application/json
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0
応答:
HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
{
"@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts(name,revenue)/$entity",
"@odata.etag": "W/\"502186\"",
"name": "A. Datum Corporation (sample)",
"revenue": 10000,
"accountid": "00000000-0000-0000-0000-000000000001",
"_transactioncurrencyid_value":"b2a6b689-9a39-e611-80d2-00155db44581"
}
特定の種類のプロパティを要求すると、さらに追加の読み取り専用プロパティが自動的に返されることを予期できます。
金額値を要求した場合、_transactioncurrencyid_value 検索プロパティ が返されます。 このプロパティには取引通貨の GUID 値のみが含まれますので、その値を使用することにより、transactioncurrency EntityType を使用して通貨に関する情報を取得できます。 または、コメントを要求することにより、同じ要求のその他のデータも取得できます。
アドレスの複合属性の一部のプロパティを要求する場合は、複合プロパティも取得します。 たとえば、クエリ要求が、取引先担当者の address1_line1 プロパティの場合は、address1_composite プロパティも返されます。
代替キーを使用してレコードを取得する
エンティティで代替キーを定義している場合、一意の識別子の代わりにその代替キーを使用して、エンティティを取得、更新、または削除できます。 既定では、エンティティに対して代替キーは構成されていません。 代替キーは、組織またはソリューションがそれらを追加する場合にのみ使用できます。
次の文字 /、<、>、*、%、&、:、\\、?、+ を含む代替キーバリューは、現在サポートされていません。
たとえば、Contact エンティティに firstname と emailaddress1 のプロパティの両方を含む代替キーの定義がある場合、それらのキーに対して用意されているデータを含むクエリを使用して取引先担当者を取得できます。
GET [Organization URI]/api/data/v9.2/contacts(firstname='Joe',emailaddress1='abc@example.com')
代替キー定義に検索タイプ フィールドが含まれている場合 (たとえば、account エンティティの primarycontactid のプロパティ)、検索プロパティ を使用して account を取得することができます。
GET [Organization URI]/api/data/v9.2/accounts(_primarycontactid_value=00000000-0000-0000-0000-000000000001)
ストレージのパーティション内のドキュメントを取得する
パーティションに保存されているエラスティック テーブルのレコードを取得する 場合は、必ずパーティション キーを指定してください。
単一のプロパティ値の取得
単一のプロパティび値のみを取得する必要がある場合、プロパティの名前をエンティティ URI に追加することができます。 返されるデータの量を減らすことが、パフォーマンスのベスト プラクティスです。
次の例では、account エンティティの name プロパティの値のみ返します。
要求:
GET [Organization URI]/api/data/v9.2/accounts(00000000-0000-0000-0000-000000000001)/name HTTP/1.1
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
応答:
HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
{
"@odata.context":"[Organization URI]/api/data/v9.2/$metadata#accounts(00000000-0000-0000-0000-000000000001)/name",
"value":"Adventure Works (sample)"
}
プロパティの生値を取得する
JSON ではなくプリミティブ プロパティの生の値を取得するには、URL に /$value を追加します。 たとえば:
要求:
GET [Organization URI]/api/data/v9.2/accounts(00000000-0000-0000-0000-000000000001)/name/$value HTTP/1.1
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
応答:
HTTP/1.1 200 OK
Content-Type: text/plain
OData-Version: 4.0
Adventure Works (sample)
ファイルまたは画像データを操作する場合を除き、生の値を使用するのは一般的ではありません。 詳細: Web API を使用して 1 つのリクエストでファイルをダウンロード します。
ナビゲーション プロパティ値の取得
個々のエンティティの URI にナビゲーション プロパティ名を追加することによって、ナビゲーション プロパティまたは検索フィールドの値にもアクセスできます。
次の例では、primarycontactid 単一値ナビゲーション プロパティを使用して account の主 contact の fullname を返します。
要求:
GET [Organization URI]/api/data/v9.2/accounts(00000000-0000-0000-0000-000000000001)/primarycontactid?$select=fullname HTTP/1.1
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
応答:
HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
{
"@odata.context": "[Organization URI]/api/data/v9.2/$metadata#contacts(fullname)/$entity",
"@odata.etag": "W/\"500128\"",
"fullname": "Rene Valdes (sample)",
"contactid": "ff390c24-9c72-e511-80d4-00155d2a68d1"
}
コレクション値ナビゲーション プロパティでは、関連するエンティティに対する参照だけまたは関連エンティティの数のみを返すことをリクエストできます。
次の例では、/$refを要求に追加することによって、特定の取引先企業に関連したタスクへの参照を返します。
要求:
GET [Organization URI]/api/data/v9.2/accounts(00000000-0000-0000-0000-000000000001)/AccountTasks/$ref HTTP/1.1
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
応答:
HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
{
"@odata.context": "[Organization URI]/api/data/v9.2/$metadata#Collection($ref)",
"value":
[
{ "@odata.id": "[Organization URI]/api/data/v9.2/tasks(6b5941dd-d175-e511-80d4-00155d2a68d1)" },
{ "@odata.id": "[Organization URI]/api/data/v9.2/tasks(fcbb60ed-d175-e511-80d4-00155d2a68d1)" }
]
}
次の例では、/$count が追加された Account_Tasks コレクション値ナビゲーション プロパティを使用して特定の取引先企業と関連するタスクの数を返します。
要求:
GET [Organization URI]/api/data/v9.2/accounts(00000000-0000-0000-0000-000000000001)/Account_Tasks/$count HTTP/1.1
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
応答:
2
注意
戻る値には、これが UTF-8 ドキュメントであることを示す、UTF-8 バイトのオーダー マーク (BOM) 文字 () が含まれています。
ナビゲーション プロパティの拡張による関連レコードの取得
$expand システム クエリ オプションを使用して、関連エンティティからどのデータが返されるかをコントロールします。 詳細情報: テーブルの結合
レコードが取得されてから変更されたかどうかを検出する
パフォーマンスのベスト プラクティスとして、必要なデータのみを使用する必要があります。 以前にエンティティ レコードを取得した場合、以前に取得したレコードに関連する ETag を使用して、そのレコードを条件を付けて検索できます。 詳細: 条件付き検索。
書式設定された値の取得
エンティティ セットをクエリするのと同じ方法で、個々のレコードを取得するために書式設定された値 を要求します。
参照
Web API を使用して演算を実行する
HTTP 要求の作成とエラーの処理
Web API を使用したデータのクエリ
注意
ドキュメントの言語設定についてお聞かせください。 簡単な調査を行います。 (この調査は英語です)
この調査には約 7 分かかります。 個人データは収集されません (プライバシー ステートメント)。
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示