検索

Learn365 API クエリ オプションの概要と使い方

  • 更新

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

レスポンスで Learn365 に返されるデータの量と順序は、Swagger のクエリ文字列パラメータ（システムクエリオプション）セットで制御することができます。

この記事では、Learn365 APIのシステムクエリオプションと、これらの使用方法について説明します。

クエリオプション

概要

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

テナントのデータ量によっては、API リクエストによってテナントに大きな負荷がかかり、レポートの生成に時間がかかったり、ページのロード時間が長くなったり、ロードが重くなったりすることがあります。

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

システム クエリー オプションは、URL で特定されるリソースに対して返されるデータの量と順序を制御するための クエリー 文字列 パラメーターです。すべてのシステム クエリ オプションの名称には先頭にドル ($) 文字が付きます。

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

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

Query options1.png

 

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

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

 

$expand

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

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

別のプロパティ内にネストされているプロパティを展開できます。クエリオプションを展開したナビゲーションプロパティに適用するには、ナビゲーションプロパティ名にセミコロンで区切られたクエリオプションのリストをかっこで囲んで追加します。

可能なシステムクエリオプションは、$filter、$select、$orderby、$skip、$top、$count、$search、および $expand です。フィルター仕様については、こちらを参照してください。

 

Query options2.png

 

例：

Courses セクションの「$expand」クエリ オプションに使用できるプロパティに「Quizzes」があります。

 

Query options3.png

 

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

 

Query options4.png

 

例えば、Courses セクションからの「GET/odata/v2/Courses」リクエストから、別のプロパティにネストされたプロパティをリクエストします。

Model内の Course プロパティを展開し、Courseプロパティ内の Quizzes プロパティを展開して、「Sharing」を選択します。つまり、$expandの値は次のようになります。：Quizzes($expand=Sharing)

 

Query options5.png

 

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

 

Query options6.png

 

$filter

filter システム クエリー オプションを使用すると、クライアントはリクエストURLで指定されたリソースのコレクションをフィルタリングし、条件を満たす項目のみでレスポンスを返すことができます。

また、別のプロパティのネストされたプロパティでフィルタリングすることもできます。フィルター仕様については、こちらを参照してください。

non-selectable と non-filterable API プロパティのセットは、こちらを参照してください。

 

例：

Coursesセクションの「GET/odata/v2/Courses」リクエストで、ネストされた $filter 指定します。

$filter に「IsPublished eq true」と入力します。

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

 

Query options7.png

 

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

 

Query options8.png

 

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

 

例：

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

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

レスポンスの結果に、テナントのすべてのコースカタログからトレーニング プランだけが表示されるように、トレーニングタイプによってフィルターしています。

 

Query options9.png

 

$select

$select クエリ オプションを使用して、レスポンスに含めるプロパティ (各エンティティまたはコンプレックス型) を正確に指定します。

$select クエリ オプションは、よく $expand システム クエリ オプションと併せて使用され、$expand でリソースグラフを返す範囲を定義し  、$select でグラフ内の各リソースのプロパティサブセットを指定します  。フィルター仕様については、こちらを参照してください。

$select で使用できない non-selectable と non-filterable API プロパティのセットは、こちらを参照してください。

 

例：

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

 

 

Query options10.png

 

$selectと$expandを組み合わせた例として、Competencies (skills)セクションの「GET /odata/v2/Competencies (skills) 」で、$select に「Title」、$expand に「Course」を設定します。

 

Query options11.png

 

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

 

Query options12.png

 

$orderby

$orderby システム クエリ オプションは、リソースの並び替えをリクエストすることができます。フィルター仕様については、こちらを参照してください。

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

 

例：

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

 

Query options13.png

 

同じ「GET /odata/v2/Enrollments」リクエストで、$orderby と $expand を組み合わせることもできます。$expand にCourse、$orderby に Course/CEU desc を設定します。

この場合、レスポンスには付与するCEU数の多い順にコースが表示されます。

 

Query options14.png

 

また、$count は、コレクション値プロパティ内の関連エンティティまたは項目の正確な数に従って、返された項目を並べ替えるために、$orderby 式内でよく使用されます。

 

例：

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

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

 

Query options15.png

 

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

 

Query options16.png

 

$top

$top システム クエリ オプションは、結果の先頭からn件までレスポンスに取得することができます。フィールドに整数を入力すると、それに応じた件数の結果をレスポンスに取得します。

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

フィルター仕様については、こちらを参照してください。

 

例：

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

このリクエストの場合、テナントの先頭から15個のコースカタログを表示します。

 

Query options17.png

 

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

このリクエストの場合、テナントの先頭から10個のコースカタログがタイトル順に表示されます。

 

Query options18.png

 

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

 

$skip

$skip システム クエリ オプションは、先頭から x 個の結果を飛ばしたレスポンスを取得します。フィールドに整数を入力すると、それに応じた数を取り除いたレスポンスを返します。フィルター仕様については、こちらを参照してください。

 

例：

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

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

 

Query options19.png

 

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

 

例：

Enrollments セクションの「GET /odata/v2/Enrollments」リクエストで、$orderby に「Course/CEU desc」、$top に「15」、$skip に「20」を設定します。

レスポンスには先頭から20件を取り除いた、上から15件の CEU数の降順で表示します。

 

Query options20.png

 

$count

$count システム クエリ オプションは、レスポンスに含まれるたリソースと共に、一致したリソースの 数をリクエストします。

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

 

Query options21.png

 

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

"@odata.count"： 50

フィルター仕様については、こちらを参照してください。

 

Any and all

単一の値ではなくコレクションを返すプロパティに対してexpandを使用する場合は、any/all 演算子を使用してコレクションフィールドをフィルター処理する必要があります。

どちらも、コレクションを識別するナビゲーションパスを先頭に付ける必要があります。

  • any 演算子はコレクションの各メンバーに Boolean 値を適用し、その値がコレクションのどのメンバーに対しても true である場合にのみ true を返し、そうでない場合は false を返します。
    このことから、any演算子は空のコレクションに対しては常に false を返すことがわかります。
    any 演算子は引数を指定せずに使用することもできます。

  • all 演算子は、コレクションの各メンバーに Boolean 値を適用し、その値がコレクションのすべてのメンバーに対して true の場合は true を返し、そうでない場合は false を返します。
    このことから、all 演算子は空のコレクションに対して常に true を返すことになります。
    all 演算子は、引数を指定せずに使用することはできません。

詳細は、こちらを参照してください。

 

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

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

 

注記：

  • システムクエリオプションを実行するには、Swagger で認証する必要があります。
  • システムクエリオプションは、Enrollmentsセクションの Learn365 API エンドポイントを例に説明します。

 

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

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

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

 

Query options22.png

 

続けて右上の「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」ボタンを選択してリクエストを実行します。

 

Query options23.png

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

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

Query options24.png