展開

Version 22.0.8500

展開

Version 22.0.8500

API Server はOData $expand 機能をサポートしています。これにより、単一リクエストでレコードおよび関連エンティティからのデータを提供できます。この機能を有効にするには、エンティティ間のリレーションシップをAPI Server リソースで定義する必要があります。

リレーションシップ

OData $expand 機能を使用する前に、API Server でリソース間のリレーションシップを定義する必要があります。エンティティ間のリレーションシップを定義する方法はいくつかあります。以下の例では、Product/Category リレーションシップを使用します。

スキーマエディタの使用

リレーションシップを定義するカラムに’relationships’ XML 属性を追加することによって、スキーマエディタでリレーションイップを手動で定義できます。属性は次の形式にする必要があります： relationshipName(ResourceName.ColumnName)。複数のリレーションシップは、| 記号で区切ることができます。リレーションシップ定義の書式設定は、カーディナリティによって異なります。

一対多リレーションシップ

親オブジェクトのスキーマ内の主キーに対応するスキーマエントリに一対多のリレーションシップを定義できます。リレーションシップの名前は、カーディナリティを示す* で始まることに注意してください。

<attr name="CategoryID" key="true" type="int" columnsize="11" 
      isNullable="false" readonly="false" relationships="*Products(Product.CategoryID)" 
      desc="" />

多対一リレーションシップ

子オブジェクトのスキーマ内の外部キーに対応する行に多対一のリレーションシップを定義できます。

<attr name="CategoryID" key="false" type="int" columnsize="11" 
      isNullable="true" readonly="false" relationships="ProductsCategory(Category.CategoryID)" 
      desc="" />

パートナー属性

リレーションシップの名前に@ という接頭辞を付けると、パートナー属性を追加することができます。以下に例を示します。

一対多のリレーションシップで\ 記号を含む場合：

relationships="*@Products(Product.CategoryID)"

多対一のリレーションシップの場合：

relationships="@ProductsCategory(Category.CategoryID)"

アプリケーションではパートナー属性の検証は行われません。そのためこの機能を使用する場合、次の条件を満たしていることを確認する必要があります。

逆リレーションシップがパートナー属性で定義およびマークされる。
逆リレーションシップの名前が複数形の有無を含めて、現在の項目の名前と全く同じである。

OData 展開構文

関連エンティティ間のリレーションシップが定義されると、$expand キーワードを使用して、単一の要求で関連オブジェクトのセットだけでなく、レコードプロパティも選択できます。$expand クエリ構文の詳細については、OData ドキュメントを参照してください。

一対多リレーションシップ

各基底レコードに対して、すべての関連オブジェクトを取得します。

http://MyServer:MyPort/api.rsc/Categories(1)?$expand=Products

Response：

{
    "@odata.context": "http://localhost:8153/api.rsc/$metadata#Categories",
    "value": [
        {
            "CategoryID": "1",
            "CategoryName": "Books",
            "Products": [
                {
                    "ProductID": "101",
                    "Price": "45",
                    "Name": "Astronomy 101",
                    "Supplierid": "1",
                    "CompanyId": "1",
                    "CategoryId": "1"
                },
                {
                    "ProductID": "102",
                    "Price": "50",
                    "Name": "Physics 101",
                    "Supplierid": "2",
                    "CompanyId": "1",
                    "CategoryId": "1"
                },
                {
                    "ProductID": "103",
                    "Price": "65",
                    "Name": "Chemistry 101",
                    "Supplierid": "3",
                    "CompanyId": "1",
                    "CategoryId": "1"
                }
            ]
        }
    ]
}

多対一リレーションシップ

各レコードに対して、関連する親レコードを取得します。

http://MyServer:MyPort/api.rsc/Products?$expand=ProductsCategory&$filter=price lt 60&$orderby=price desc

Response：

{
    "@odata.context": "http://localhost:8153/api.rsc/$metadata#Products",
    "value": [
        {
            "ProductId": 102,
            "Name": "Physics 101",
            "Price": "50",
            "CategoryId": "1",
            "ProductsCategory": [
                {
                    "CategoryName": "Books",
                    "CategoryId": "1"
                }
            ]
        },
        {
            "ProductId": 101,
            "Name": "Astronomy 101",
            "Price": "45",
            "CategoryId": "1",
            "ProductsCategory": [
                {
                    "CategoryName": "Books",
                    "CategoryId": "1"
                }
            ]
        }
    ]
}

複数の展開

$expand パラメータは、多対一と一対多リレーションシップを組み合わせたカンマ区切りリストの値をとることができます。

http://MyServer:MyPort/api.rsc/Products(102)?$expand=Supplier,ProductReviews

Response：

{
    "@odata.context": "http://localhost:8153/api.rsc/$metadata#Products",
    "value": [
        {
            "ProductId": 102,
            "Name": "Physics 101",
            "Price": "50",
            "ProductReviews": [
                {
                    "ProductReviewID": "1001",
                    "ProductId": "102",
                    "Rating": "4.5",
                    "Description": "Easy to read, good illustrations."
                },
                    {
                    "ProductReviewID": "1002",
                    "ProductId": "102",
                    "Rating": "1.5",
                    "Description": "Boring!"
                }
            ],
            "Supplier": [
                {
                    "SupplierId": "1",
                    "SupplierName": "New Science Publishing"
                }
            ]
        }
    ]
}

展開オプション

OData API の呼び出しでは、expand オプションを使用して、返す関連エンティティをより詳細に定義することができます。拡張オプションはセミコロンで区切られたリストで関連エンティティにカッコを付けて指定します。

Select

$select オプションは、関連するエンティティのどのカラムを返すかを定義します。指定がない場合は、利用可能なすべての値が返されます。次に例を示します。

http://MyServer:MyPort/api.rsc/Products(102)?$expand=ProductReviews($select=Description),Supplier($select=SupplierName)

Filter

$filter オプションを使用すると、関連する結果に適用する基準を定義することができます。この基準に適合しない関連エンティティは応答から除外されます。次に例を示します。

http://MyServer:MyPort/api.rsc/Products(102)?$expand=ProductReviews($select=Rating;$filter=Rating ge 4)