エンティティ レコードにクエリを実行

エンティティ レコードにクエリを実行します。

API エンドポイント

POST BaseURL/EntityService/<Entity>/query

• 使用しているクラウド プラットフォームに応じて、関連付けられた ベース URL を使用します。

要求ヘッダー

ヘッダー	値 (Value)
認可	Bearer <access_token>
Content-Type	application/json

注:

角括弧で囲まれた値 <...> をすべて、対応するユース ケース値に置き換えます。

<access_token> は、外部アプリケーションの認証時に受け取ったトークンです。このトークンは 1 時間利用可能です。1 時間経ったら、新しいトークンを生成するか、更新トークンを要求する必要があります。

クエリ パラメーター

クエリ パラメーター	データ型	説明	既定値
expansionLevel (任意)	int32	取得する関連レコードの深さを指定します。このパラメーターには 1、2、または 3 のいずれかの値を指定できます。	2

要求本文 (必須)

{
  "selectedFields": [
    "string"
  ],
  "filterGroup": {
    "logicalOperator": 0,
    "queryFilters": [
      {
        "fieldName": "string",
        "operator": "string",
        "value": "string"
      }
    ],
    "filterGroups": [
    ]
  },
  "start": 0,
  "limit": 0,
  "sortOptions": [
    {
      "fieldName": "string",
      "isDescending": true
    }
  ]
}

要求本文のスキーマ

query エンドポイントの要求本文は、以下のコンポーネントから成ります。

selectedFields

これは、string 型の任意のコンポーネントです。クエリの各レコードに対して返されるフィールドのリストを指定します。何も指定しない場合、またはクエリ リストが空の場合は、すべてのレコード フィールドが返されます。既定値は null です。

filterGroup

これは、クエリのフィルター処理プロパティを設定するのに役立つ、必須のコンポーネントです。以下のプロパティを組み合わせます。

• logicalOperator - これは、int32型の任意の filterGroup プロパティです。すべてのフィルターとフィルター グループをクエリに適用するかどうかを指定します。0 を使用して、すべてのフィルターおよびフィルター グループを適用します。1 を使用して、任意のフィルターおよびフィルター グループを適用します。既定値は 0です。

• queryFilter - フィルター処理の式を定義するのに役立つ、filterGroup の必須のプロパティです。以下のプロパティがあります。

  queryFilter のプロパティ	データ型	説明
  fieldName	string	フィルター処理するフィールドの名前を指定します。
  operator	string	フィルター演算子を指定します。サポートされる contains、 not contains、 startswith、 endswith、 =、 !=、 >、 <、>=、 <=、 in、 not in。対応するフィールドの種類に対して適切な演算子を使用します。
  value	string	フィルター値を指定します。

• filterGroups - これは filterGroup の任意のプロパティです。クエリに別のフィルター オプションを設定する必要がある場合に指定します。上記の filterGroup のプロパティがすべて含まれます。

開始

これは、int32 型の任意のコンポーネントです。クエリからレコードを取得する前にスキップするレコードの数を指定します。limit プロパティと併用してページネーションを実装できます。レコードは ID の昇順に並べられます。並べ替えの順序を変更するには、sortOptions プロパティを使用します。既定値は 0 です。

limit

これは、 int32型の任意のコンポーネントです。エンティティから読み取るレコードの最大数を指定します。start プロパティと一緒に使用して、ページネーションを実装できます。既定値は [ 100] で、最大値は [ 1000] です。

sortOptions

これは任意のコンポーネントであり、クエリが実行されたレコードをフィールドのリストで並べ替える際に役立ちます。空のままにすると、レコードは ID の昇順に並べ替えられます。以下のプロパティを組み合わせます。

• fieldName - これは、string型の必須の sortOptions プロパティです。レコードの並べ替えに使用するフィールドの名前を指定します。この名前は有効なフィールドに対応している必要があり、大文字と小文字が区別されます。
• isDescending - オプションの sortOptions プロパティで、 boolean型です。レコードを降順に並べ替える場合は、 true に設定します。既定値は [ falseです。

応答

200 OK

{
  "TotalRecordCount": 0,
  "Value": [
    {
      "ClosingDate": "2021-03-04",
      "CreatedBy": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "CreateTime": "2021-03-04T10:21:22.771Z",
      "Id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "Logo": {
        "Name": "string",
        "Path": "string",
        "Size": 0,
        "Type": "string"
      },
      "Name": "string",
      "Nations": 0,
      "OlymipcsVersion": 0,
      "OpeningDate": "2021-03-04",
      "UpdatedBy": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "UpdateTime": "2021-03-04T10:21:22.771Z"
    }
  ]
}

応答本文のスキーマ

query エンドポイントの応答本文は、以下のコンポーネントから成ります。

• totalRecordCount - 指定したクエリ フィルターに一致するレコードの総数です。
• value - limit プロパティにより制限される、指定したクエリ フィルターに一致するエンティティ レコードの配列です。

401 未承認

Data Fabric / Data Service へのアクセスが認証されていません。Assistant または Robot がアカウント内のモダン フォルダーに接続されていることを確認します。

403 Forbidden

エンティティ、フィールド、またはレコードにアクセスする権限がありません。または、サポートされていない種類のロボットを使用しています。必要な権限について管理者にお問い合わせください。

集計関数

要求本文に aggregates プロパティと groupBy プロパティを追加することで、単一のエンティティに対して集計計算を実行できます。集計は、計算値 (合計や平均値など) を、それ自体で、またはグループ化されたフィールド値とともに返します。

要求本文

{
  "selectedFields": [
    "Department"
  ],
  "aggregates": [
    {
      "function": "COUNT",
      "field": "Id",
      "alias": "EmployeeCount"
    }
  ],
  "groupBy": [
    "Department"
  ],
  "filterGroup": {
    "logicalOperator": 0,
    "queryFilters": [
      {
        "fieldName": "Status",
        "operator": "=",
        "value": "Active"
      }
    ]
  },
  "sortOptions": [
    {
      "fieldName": "EmployeeCount",
      "isDescending": true
    }
  ],
  "start": 0,
  "limit": 100
}

要求コンポーネントを集約する

集計クエリでは、基本クエリのプロパティに加えて、次のコンポーネントが使用されます。

集計

これはオプションのコンポーネントで、配列型です。適用する集計関数を指定します。クエリごとに最大 5 つの集計を含めることができます。各項目には、次のプロパティがあります。

Aggregates プロパティ	データ型	Required	説明
関数	string	はい	適用する集計関数です。サポートされている値: [ COUNT]、[ SUM]、[ AVG]、[ MIN]、[ MAX]大文字と小文字を区別しません。
フィールド	string	はい	集計するフィールドです。クエリされるエンティティのフィールドである必要があります。
エイリアス	string	いいえ	結果列の名前です。省略した場合は、 {FUNCTION}_{FIELD} として自動生成されます (例: COUNT_Id)。エイリアスは、クエリ内で一意であり (大文字と小文字を区別しません)、文字で始まり、文字、数字、アンダースコアのみを含める必要があります。

グループ化

これは、 stringの配列型の任意のコンポーネントです。結果をグループ化するフィールドを指定します。最大 5 つのフィールドを含めることができます。

aggregatesと空でないselectedFieldsの両方を指定する場合、groupBy が必須であり、selectedFields内のすべてのフィールドも groupByに表示される必要があります。

注:

集計クエリを並べ替える場合は、 sortOptions.fieldName 集計 aliasまたは selectedFields/groupByの一部であるフィールドに設定します。

フィールドの種類のサポート

機能	サポートされているフィールドの種類
カウント、 最小値、 最大値	添付ファイル フィールドと複数行のテキスト フィールド (標準 MULTILINE と大 MULTILINE_MAX) を除く、任意の種類のフィールド。
合計、 AVG	数値フィールドのみ: INT、BIGINT、DECIMAL、FLOAT、REAL

制限と制約事項

• クエリごとに最大 5 つの集計関数と 5 つの groupBy フィールド。
• 集計は展開 (expansionLevel) と組み合わせることはできません。
• 集計は、標準 (テーブルベース) エンティティでのみサポートされています。仮想エンティティ (外部データ ソース)、チョイス セット、またはシステム エンティティではサポートされません。
• 集計は、添付ファイル フィールドまたは複数行のテキスト フィールド (標準 MULTILINE と大きな MULTILINE_MAXの両方) には適用できません。これは、 COUNTを含むすべての関数に適用されます。
• レコード レベル (行レベル) のアクセス許可フィルターは集計結果には適用されません: 集計値は、呼び出し元が個別に読み取ることができないレコードを含む、エンティティ内のすべてのレコードにわたって計算されます。エンティティ レベルおよびフィールド レベルの読み取り権限は引き続き適用されます。読み取り権限のないフィールドで集計またはグループ化することはできません。

例: フィールドでグループ化した数

部署ごとに従業員をカウントします。カウントの降順で並べ替えます。

要求:

POST BaseURL/EntityService/Employees/query

{
  "selectedFields": ["Department"],
  "aggregates": [
    { "function": "COUNT", "field": "Id", "alias": "EmployeeCount" }
  ],
  "groupBy": ["Department"],
  "sortOptions": [
    { "fieldName": "EmployeeCount", "isDescending": true }
  ]
}

応答:

{
  "TotalRecordCount": 3,
  "Value": [
    { "Department": "Engineering", "EmployeeCount": 150 },
    { "Department": "Sales", "EmployeeCount": 80 },
    { "Department": "HR", "EmployeeCount": 20 }
  ]
}

マルチエンティティ クエリ (結合)

要求本文に joins プロパティを追加することで、関連エンティティのレコードを 1 つのクエリに結合できます。結合は、単独で使用することも、集計や groupByと一緒に使用することもできます。

メイン (左) のエンティティは、要求 URL (<Entity>) のエンティティです。結合するたびに、クエリに別のエンティティが追加されます。

要求本文

{
  "selectedFields": [
    "Employees.Name",
    "Departments.Name"
  ],
  "joins": [
    {
      "type": "INNER",
      "entity": "Departments",
      "on": {
        "left": "Employees.DepartmentId",
        "right": "Departments.Id"
      }
    }
  ],
  "sortOptions": [
    {
      "fieldName": "Employees.Name",
      "isDescending": false
    }
  ],
  "start": 0,
  "limit": 100
}

フィールド予選

クエリが複数のエンティティにまたがる場合は、フィールドを EntityName.fieldNameと呼びます。非修飾 fieldName は、クエリ内のすべてのエンティティで一意である場合にのみ使用できます。それ以外の場合は、あいまいなものとして拒否されます。エンティティ名では大文字と小文字が区別されません。

これは、 selectedFields、 groupBy、 sortOptions.fieldName、 filterGroup フィルター、 aggregates.field、および結合 on.left/on.right の値に適用されます。応答では、フィールドは常に EntityName.fieldNameとして修飾されて返されます。

結合要求コンポーネント

結合

これはオプションのコンポーネントで、配列型です。結合するエンティティを指定します。最大 3 つの結合を含めることができます。各項目には、次のプロパティがあります。

Joins プロパティ	データ型	Required	説明
type	string	はい	結合の種類です。サポートされている値: INNER、 LEFTです。大文字と小文字を区別しません。1 つのクエリ内のすべての結合は、同じ型である必要があります。 INNER と LEFT の混在はサポートされていません。
エンティティ	string	はい	結合するエンティティの名前です。各エンティティは一度だけ出現でき、メイン エンティティにすることはできません (自己結合はサポートされていません)。
有効	object	はい	結合条件。leftとrightが含まれます。
左に	string	はい	左側の結合フィールド ( fieldName (曖昧でない場合) または [ EntityName.fieldName] ) です。
右上	string	はい	右側の結合フィールド (明確な場合は fieldName または EntityName.fieldName) です。

制限と制約事項

• クエリごとに最大 3 つの結合で、すべて同じ種類 (INNER または LEFT) です。
• 両側の結合キーには、互換性のある型 (数値と数値、テキストとテキスト、日付と日付) が必要です。
• システム生成フィールド、暗号化されたフィールド、大きい (複数行が最大) テキスト フィールド、チョイス セットまたは複数のチョイス セット フィールド、ファイル (添付ファイル) フィールドでは結合できません。リレーションシップ フィールドは結合キーとして使用できます。
• HAVING 句はサポートされていません。
• 結合と集計を組み合わせる場合は、「集計関数」セクションで説明されている集計ルールとgroupByルールも適用されます。

例: アグリゲートによる左結合

注文されていない顧客を含む、注文数のある顧客を一覧表示します。

要求:

POST BaseURL/EntityService/Customers/query

{
  "selectedFields": ["Customers.Id", "Customers.Name"],
  "aggregates": [
    { "function": "COUNT", "field": "Orders.Id", "alias": "OrderCount" }
  ],
  "joins": [
    {
      "type": "LEFT",
      "entity": "Orders",
      "on": { "left": "Customers.Id", "right": "Orders.CustomerId" }
    }
  ],
  "groupBy": ["Customers.Id", "Customers.Name"],
  "sortOptions": [
    { "fieldName": "OrderCount", "isDescending": true }
  ]
}

応答:

{
  "TotalRecordCount": 3,
  "Value": [
    { "Customers.Id": "C-001", "Customers.Name": "Acme Corp", "OrderCount": 12 },
    { "Customers.Id": "C-002", "Customers.Name": "Globex", "OrderCount": 3 },
    { "Customers.Id": "C-003", "Customers.Name": "Initech", "OrderCount": 0 }
  ]
}