APIエンドポイントを使用すると、API リクエストはサーバー（リソース）に送信され、それが処理されると、サーバーは、クライアント（LMS365）にレスポンスとして取得した情報、または実行された関数を返送します。

レスポンスでLMS365に返されるデータの量と順序は、Swagger のクエリストリングパラメータセット（システム・クエリ・オプション）でコントロールできます。

ここでは、LMS365 API のシステムクエリオプションのご説明と、これらの使用に関するガイダンスをご提供します。

クエリオプション

概要

API リクエストは、コースやトレーニングプランとその教材の管理、ユーザーとトレーニングに関する統計の取得や 追加、削除、トレーニングへのユーザーの登録と登録解除など、多くのことに使用できます。

テナントのデータ量によってはいくつかの API リクエストでテナントに大きな負荷がかかり、結果としてレポートの生成に時間がかかったり、ページの読み込み時間がかかったり、あるいは読み込みが遅くなることがあります。

こうしたことは、システム・クエリ・オプション・パラメーターを使用して返される レスポンスデータをコントロールすることで防ぐことができます。

システム・クエリ・オプションは、URL で特定されるリソースに対して返されるデータの量と順序を制御する「クエリストリングパラメータ」です。すべてのシステム・クエリ・オプションの名前の先頭にはドル（$）文字が付きます。

システム・クエリ・オプションには、以下のものがあります。

• $expand：対象エンティティに関連するデータの取得
• $filter：検索対象をフィルタします。SQL文の WHERE 相当
• $select：検索結果項目の選択
• $orderby：検索結果を並べ替え。SQL文の ORDER BY 相当
• $top：検索結果上位の何件を取得するか指定
• $skip：検索結果の上位の何件をスキップするか指定
• $count：検索条件に一致する件数の取得。SELECT COUNT(*) 相当

クエリ・オプション・パラメータのデフォルト値には、以下のタイプがあります。

• guid：共有パラメータに関連付けられた一意の ID
• string：何らかの制限のある文字列（文字、数字、記号、句読点など）
• integer：整数
• boolean：真か偽の変数

$expand

$expand システム・クエリ・オプションは、クライアントが関連するエントリーを1つの URL で返すことを許可します。関連するリソースまたはメディアストリームは、取得されたリソースの並びに含まれます。

展開可能なエンティティは、Responses ブロックの下にあるプロパティの Model、または LMS365 API セクションリストの下にある Models で確認できます。

他のプロパティの内部にあるネストされたプロパティも展開できます。

クエリオプションは、括弧で囲んだセミコロン区切りのクエリオプションリストを、ナビゲーションプロパティ名に追加することで、 拡張したナビゲーションプロパティに適用できます。許可されたシステム・クエリ・オプションは、$filter、$select、$orderby、$skip、$top、$count、$search、$expand です。フィルタの指定についての詳細はこちらをご参照ください。

例：

以下は、Courses セクションの「$expand」クエリオプションにクイズを使用したするプロパティの例です。

この場合、テナントの各コースに含まれる各クイズのデータを取得します。
結果は、JSON ファイルフォーマットでローカルデバイスにダウンロードすることができます。

他のプロパティの中にネストされたプロパティを持つリクエストの例として、CoursesセクションからのGET /odata/v2/Courses リクエスト（Model 内の Courseプロパティを展開＞ Courseプロパティ内の Quizzes プロパティを展開＞Sharing. ）を使用することができます。

$expand の値は「Quizzes($expand=Sharing)」となります。

この場合、レスポンスは、テナントの各コースの各クイズの共有設定に関連するデータを取得します。結果は、JSON ファイルフォーマットでローカルデバイスにダウンロードすることができます。

$filter

$filter システム・クエリ・オプションを使用すると、クライアントはリクエストURLで指定されたリソースのコレクションをフィルタリングし、条件を満たす項目だけを含むレスポンスを返します。
また、別のプロパティの中に入れ子になっているプロパティでフィルタリングすることもできます。
フィルタの指定についての詳細はこちらをご参照ください。

フィルターに使用できない、選択不可およびフィルター不可の API プロパティのセットは、「フィルタリング不可、選択不可のAPIプロパティ」で確認できます。

例：

ネストされた $filter の例として、Courses セクションの GET /odata/v2/Courses リクエストを使用することができます。

$filter の値に「IsPublished eq true」と設定します。

IsPublished はフィルタリングするパラメータ、eq は等号演算子、true はフィルタリング値を示します。

この場合、レスポンスにはテナントの公開されたコースに関するデータのみが含まれます。

関連するセクションの Model から取得したプロパティを展開してフィルタを追加することも可能です。先に $expand でフィルタを適用する Model のパートを指定し、次に $filter でフィルタリングパラメータを設定します。

例えば、Enrollments セクションの GET /odata/v2/Enrollments リクエストに対して、レスポンスにコースとトレーニングプランに関するデータを追加するために、$expand に Course を設定します。

次に、$filter のフィルタリングパラメータを「Course/CourseType eq 'TrainingPlan'」と設定します。
CourseType はフィルタリングするパラメータ、eq は等号演算子、選択した 'TrainingPlan'はフィルタリング値です。

レスポンスは、テナントのすべてのコースカタログからトレーニングプランのみを表示するために、トレーニングタイプによってフィルタリングされます。

$select

$select システム・クエリ・オプションを使用して、レスポンスに含める具体的なプロパティ（各エンティティまたは複合型） を指定します。

$select システム・クエリ・オプションは、"$expand "システム・クエリ・オプションと組み合わせて使用されることが多く、返すリソース・グラフの範囲を定義し ($expand)、次にグラフ内の各リソースのプロパティのサブセットを指定します ($select)。

フィルタの指定についての詳細はこちらをご参照ください。

フィルターに使用できない、選択不可およびフィルター不可の API プロパティのセットは、「フィルタリング不可、選択不可のAPIプロパティ」で確認できます。

例：

Competencies（skills）セクションの GET /odata/v2/Competencies (skills) の $select システム・クエリ・オプションに「Title」を使用した場合、レスポンスにはこのパラメータに一致する結果（テナント全体のスキルのタイトル）だけが含まれます。

$select と $expand の組み合わせの例としては、以下のようなリクエストがあります。

Competencies (skills)セクションの GET /odata/v2/Competencies (skills) で、$select に「Title」、$expand に「Course」を設定します。

この場合、レスポンスにはスキルのタイトルと、このスキルが付与されたコースに関するデータが含まれます。

$orderby

$orderby システム・クエリ・オプションを使用すると、クライアントは指定した順序にしたがってリソースをリクエストすることができます。
フィルタの指定についての詳細はこちらをご参照ください。

$expand 句に $orderby を指定することで、関連するエンティティを並べ替えることができます。

例：

例えば、Enrollments セクションの GET /odata/v2/Enrollments リクエストで、$orderby に「RegistrationDate desc」を設定すると、テナントからのすべてのコースの登録日を新しい順に並べたレスポンスを取得することができます。

$orderby と $expand の組み合わせの例として、同じ GET /odata/v2/Enrollments リクエストで $expand に「Course」、$orderby に「Course/CEU desc」を指定します。

この場合、レスポンスは付与されたCEU数の降順でコースが表示されます。

また $count は、コレクション値プロパティ内の関連エンティティ、またはアイテムの正確なカウントに従って返されたアイテムを順序付けるために、$orderby 式の中でかなり頻繁に使用されます。

例：

Enrollments セクションの GET /odata/v2/Enrollments リクエストで $count と $orderby の両方を使用します。

$orderby に「RegistrationDate desc」を設定し、$count で「true」を選択します。

この結果、付与された CEU 数の多い順にトレーニングが表示されるだけでなく、CEU が付与されたコースやトレーニングプランの数もカウントされ、レスポンスの冒頭に表示されます。

$top

$top システム・クエリ・オプションを使用すると、返された結果のうち最初の n 件だけを含むレスポンスを取得することができます。

フィールドに整数を入力すると、それに応じた数の件数がレスポンスに含まれます。

また、$top は $orderby オプションと一緒に使うと非常に便利です。

フィルタの指定についての詳細はこちらをご参照ください。

例：

CourseCatalogs セクションの GET /odata/v2/CourseCatalogs リクエストで、$top に「15」と設定します。このリクエストでは、テナントの最初の15個のコースカタログを表示します。

$top と $orderby の組み合わせの例として、Enrollments セクションの GET /odata/v2/Enrollments リクエストで $orderby に「Title」、$top に「10」を指定します。

この場合、レスポンスにはテナントの最初の10個のコースカタログがタイトル順に表示されます。

また、$top と $skip を組み合わせることによって、特定の項目のページをリクエストすることができます。

$skip

$skip システム・クエリ・オプションを使用すると、先頭から x 個の結果を飛ばしたレスポンスを取得できます。フィールドに整数を入力すると、それに応じた数を取り除いたレスポンスを返します。

フィルタの指定についての詳細はこちらをご参照ください。

例：

CourseCatalogs セクションの GET /odata/v2/CourseCatalogs リクエストで、$skip に「20」と設定します。

この場合、レスポンスにはテナントの最初の20個を取り除いたのコースカタログを表示します。

$skip は、$orderby と $top の両方、またはいずれか一方と組み合わせて使用すると特に便利なオプションです。

例：

$orderby に「Course/CEU desc」、$top に「15」、$skip に「20」を設定すると、レスポンスは最初の20件を取り除いた、上位15件の CEU を降順で表示します。

$count

$count システム・クエリ・オプションを使用すると、レスポンスに含まれているリソースのうち、条件に一致するリソースの数を取得することができます。

$count には、Boolean値「true」または「false」を設定します。

レスポンスは、一致した結果の数を「count:」として表示します。

"@odata.count"： 50

フィルタの指定についての詳細はこちらをご参照ください。

クエリーオプションの使い方

ここでは、Enrollments セクションからの LMS365 API リクエストを例に、システム・クエリ・オプションの使用方法をご説明します。

Swagger にアクセスし、認証します。

LMS365 Cloud API ブロックまでスクロールダウンし、該当するセクションとメソッドを見つけます。

ここでは、Enrollments セクションの GET request /odata/v2/Enrollments with the Returns the list of current user's active Enrollments を選択します。

続けて右上の「Try it out」ボタンを選択し、クエリパラメータを入力します。

$expand：Course, User
$filter：RegistrationStatus eq 'Active'
$select：UserId, RegistrationDate, RegistrationStatus
$orderby：RegistrationDate desc
$top：15
$skip：20
$count：true

今回の例では、ユーザのID、登録日、および登録ステータスを含む、アクティブなコースの内、最初の20個を除く上位15のコースを表示し、それらをユーザーの登録日の降順で表示します。

パラメータの入力が完了したら「Execute」ボタンを選択してリクエストを実行します。

スクロールしてResponsesブロックに移動し、結果を確認します。

• Codeの下にある2xx（たとえば200）は、リクエストが正しく動作したことを示しています。
• Responses body フィールドには、設定されたプロパティに応じたデータが表示されます。
  Ctrl+Fで検索して、関連データを見つけることができます。