Planner でオーダー ヒントを使用する
名前空間: microsoft.graph
重要
Microsoft Graph の /beta バージョンの API は変更される可能性があります。 実稼働アプリケーションでこれらの API を使用することは、サポートされていません。 v1.0 で API を使用できるかどうかを確認するには、Version セレクターを使用します。
オーダー ヒントによって、Planner 内のオブジェクトの並べ替え順序を特定します。 オーダー ヒントの値は文字列です。 クライアントは項目の順序を特定するため、文字の序数値に基づいて文字列を並べ替えることができます。 文字の序数値に違いが発生するまで、または文字列の終わりまで、文字列の先頭から文字を比較します。後者の場合、短い方の文字列を長い文字列より前に並べ替えます。 値には、32 (スペース) から 126 (~) の序数のうち、どの文字でも含めることができます
一例として、オーダー ヒント a (序数値 97) を持つ項目は、オーダー ヒント z (序数値 122) を持つ別の項目より前に配置されます。 オーダー ヒント abc (序数値 97、98、99) を持つ項目は、オーダー ヒント abd (序数値 97、98、100) を持つ別の項目より前に配置されます。 オーダー ヒント a を持つ項目は、オーダー ヒント ab を持つ別の項目より前に配置されますが、これはすべての既存の文字が同じであり、a の方が短いためです。
このサービスにより、すべてのオーダー ヒントの値を計算します。 クライアントは、2 つの項目間を移動した項目のオーダー ヒントを指定することによって、項目を並べ替えることができます。オーダー ヒントを次の値に設定します。<previous order hint> <next order hint>!、ここでは新しく要求した場所の前に来る項目のオーダー ヒントによって <previous order hint> が置き換えられ、新しく要求した場所の後に来る項目のオーダー ヒントによって <next order hint> が置き換えられます。 これらのオーダー ヒントの値の間には空白文字があり、値全体の後に ! が付きます。 いずれの項目も存在しない場合は、代わりに空の文字列を使用する必要があります。 この値は以前の計算で構成することもでき、オーダー ヒントを返したサービスと全く同じように項目を並べ替えるためにクライアントで使用することもできます。 更新プログラムでクライアントがこれらの値を送信したら、このサービスは要求された場所で並べ替えを行う短い値を計算します。
手記： 次の例では、実際の注文ヒント値はわかりやすくするために単一引用符文字 (
') で囲まれていますが、これらはデータの一部ではなく、サービスに送信しないでください。
たとえば、以下のオーダー ヒントの並べ替えのリストについて検討します。
- 項目 1 (オーダー ヒント:
'5637') - 項目 2 (オーダー ヒント:
'adhg')
項目 3 を項目 1 の前に配置し、次に項目 4 を項目 1 と項目 2 の間に配置します。次いで項目 5 を項目 2 の後に配置すれば、クライアント上で以下のオーダー ヒントが作成されます。
- 項目 3 (オーダー ヒント:
' 5637!') - 項目 1 (オーダー ヒント:
'5637') - 項目 4 (オーダー ヒント:
'5637 adhg!') - 項目 2 (オーダー ヒント:
'adhg') - 項目 5 (オーダー ヒント:
'adhg !')
次に、項目 1 をリストの末尾に移動すると、次のオーダー ヒントが生成されます。
- 項目 3 (オーダー ヒント:
' 5637!') - 項目 4 (オーダー ヒント:
'5637 adhg!') - 項目 2 (オーダー ヒント:
'adhg') - 項目 5 (オーダー ヒント:
'adhg !') - 項目 1 (オーダー ヒント:
'adhg ! !')
最後に、項目 5 を項目 3 と項目 4 の間に移動すると、次のオーダー ヒントが生成されます。
- 項目 3 (オーダー ヒント:
' 5637!') - 項目 5 (オーダー ヒント:
' 5637! 5637 adhg!!') - 項目 4 (オーダー ヒント:
'5637 adhg!') - 項目 2 (オーダー ヒント:
'adhg') - 項目 1 (オーダー ヒント:
'adhg ! !')
注文ヒント値に対するこれらの変更がパッチ要求でサービスに送信されると、サービスはクライアントが意図した順序を維持する適切な値を計算します。 クライアントは、PATCH要求でPrefer: return=representation基本設定ヘッダーが指定されている場合、すぐに値を取得できます。 上記の場合の値は、次のように表示されます (実際の値は異なる場合があります)。
- 項目 3 (オーダー ヒント:
'432b') - 項目 5 (オーダー ヒント:
'6F"#') - 項目 4 (オーダー ヒント:
'7A$6') - 項目 2 (オーダー ヒント:
'adhg') - 項目 1 (オーダー ヒント:
'de5%')
リストの最初の項目を作成する場合、前または次の項目がいずれも存在しないため、オーダー ヒントを ! として指定することができます。ただし、項目の作成時にオーダー ヒントの値が指定されない場合、そうする必要はありません。これは、サービスが項目のすべてのオーダー ヒントの値を自動生成するためです。 次の例は、以前に空白だったリストに項目を配置する場合、オーダー ヒントを使用する必要があることを示しています。
最初の項目を追加します。
- 項目 1 (オーダー ヒント:
' !')
2 番目の項目を先頭に追加します。
- 項目 2 (オーダー ヒント:
' !!') - 項目 1 (オーダー ヒント:
' !')
3 番目の項目を一番下に追加します。
- 項目 2 (オーダー ヒント:
' !!') - 項目 1 (オーダー ヒント:
' !') - 項目 3 (オーダー ヒント:
' ! !')