範圍篩選條件

數個 Cloud Directory 清單 API 可讓您指定範圍形式的篩選條件。這些篩選條件可讓您有效率地選取已連接到指定節點的部分連結。

一般提供對應範圍 (鍵/值對陣列)，其金鑰是屬性識別符且其值為對應的範圍。這可篩選由一或多個屬性構成身分的連結。例如，為建立角色關係模型以決定許可而設定的 TypedLink，可能同時擁有 RoleType 和 Authorizer 屬性。然後，ListOutgoingTypedLinks 呼叫可以指定範圍來篩選 RoleType:”Admin” 和 Authorizer:”Julia” 的結果。用來篩選單一清單請求的對應範圍必須只包含定義連結身分的屬性 (索引的 OrderedIndexedAttributeList 或 TypedLink 的 IdentityAttributeOrder)，但不需要包含它們所有的範圍。缺漏的範圍會自動填入跨所有可能值的範圍 (從 FIRST 到 LAST)。

如果您將每個屬性想像成定義這些值的獨立一般網域，範圍結構會在該網域中定義兩個邏輯點，起點和終點，範圍即是這些點之間所有符合可能的點。範圍結構的 StartValue 和 EndValue 使用「模式」定義這兩個點的基礎，並進一步細化到指出各點本身是包含在範圍內或排除在範圍外。在上述 RoleType:”Admin” 範例中，RoleType 屬性的兩個值都是 “Admin”，兩種模式也都是 “INCLUSIVE” (寫作 [“Admin” to “Admin”])。在 User 面向的 LastName 中定義索引之 ListIndex 呼叫的篩選條件，可能使用 StartValue=”D”、StartMode=INCLUSIVE、EndValue:”G”、EndMode:EXCLUSIVE 將清單縮小至開頭為 D、E 或 F 的名稱。

範圍的起點必須一律先於或等於終點。如果 EndValue 先於 StartValue，Cloud Directory 就會傳回錯誤。這些值也必須和它們篩選的屬性是同一個基本類型，String 屬性是字串值、Integer 屬性是整數，以此類推。例如，StartValue=“D”、StartMode=EXCLUSIVE、EndValue=“D”、EndMode=INCLUSIVE 無效，因為起點在終點所包含值的後面。

起點或終點有三種特殊模式可用。下列模式不需要指定對應的值欄位，因為它們自行暗示位置。

• FIRST - 先於網域中所有可能的值。用於起點時，這符合從網域最開始到終點的所有可能值。用於終點時，網域內沒有任何值符合此範圍。

• LAST - 接續在網域中所有可能值的後面。用於終點時，這符合接續在起點後所有可能的值，包括缺漏值。用於起點時，網域內沒有任何值符合此範圍。

• LAST_BEFORE_MISSING_VALUES - 此模式只對可省略值的選用屬性有用 (請參閱「缺少的值」)。它對應到缺漏值和實際網域值之間的點。用於終點時，這符合接續在起點後所有非缺漏網域的值。用於起點時，它會排除所有非缺漏網域值。如為必要屬性，此模式等同於 LAST，因為不會有任何缺漏值。

多範圍限制

Cloud Directory 限制有多個屬性的模式，以保證有效率、低延遲的請求處理。每個有多識別屬性的連結會依定義良好的順序指定它們。例如，上述的角色範例定義 RoleType 屬性為最重要，而 Authorizer 屬性最不重要。List 請求只能指定不可為 1) 單一值或 2) 跨所有可能值的單一「合格」範圍 (可能有多個範圍符合這兩項請求)。重要屬性多過合格範圍屬性的任何範圍都必須指定單一值，而不重要範圍的任何範圍則必須跨所有可能的值。在角色範例中，篩選條件集 (RoleType:”Admin”、Authorizer:[“J” to “L”]) (單一值 + 合格範圍)、(RoleType:[”Admin” to “User”]) (合格範圍 + 隱含跨越範圍) 和 (RoleType:[FIRST to LAST]) (兩個跨越範圍、一個隱含) 都是有效的篩選條件集範例。(RoleType:[FIRST to LAST]、Authorizer:”Julia”) 不是有效的集合，因為跨越範圍比單一值範圍更重要。

填寫範圍結構的一些實用模式包括：

比對單一值

指定 StartValue 和 EndValue 的值，並將這兩種模式設為 “INCLUSIVE”。

範例: StartValue=“Admin”, StartMode=INCLUSIVE, EndValue=“Admin”, EndMode=INCLUSIVE

比對字首

指定字首為使用 INCLUSIVE 模式的 StartValue，前綴後第一個值為使用 EXCLUSIVE 模式的 EndValue。

範例: StartValue=“Jo”, StartMode=INCLUSIVE, EndValue=“Jp”, EndMode=EXCLUSIVE (“p” is the next character value after “o”)

大於某值的篩選條件

指定使用 EXCLUSIVE 模式的 StartValue 值，以及 LAST 做為 EndMode (或 LAST_BEFORE_MISSING_VALUES 排除遺漏的值，如果適用)。

範例: StartValue=127, StartMode=EXCLUSIVE, EndValue=null, EndMode=LAST

小於或等於某值的篩選條件

指定使用 INCLUSIVE 模式的 EndValue 值，且 FIRST 做為 StartMode。

缺少的值

當屬性在結構描述中標示為選用時，它的值可能會「缺漏」，因為連接面向時不需要提供它，或可能在後來刪除了屬性。如果有缺漏值的物件連接到索引，索引連結仍然存在，但會移至連結集的結尾處。ListIndex 呼叫會先傳回顯示所有已建立索引之屬性的任何連結，再傳回缺漏一或多個屬性的連結。這大概類似關聯式資料庫的 NULL 值，但這些值會排列在非 NULL 值的後面。您可以選擇 LAST 或 LAST_BEFORE_MISSING_VALUES 模式，指定某個範圍是否包含這些缺漏值。例如，您向 ListIndex 呼叫提供篩選條件，篩選範圍為 [LAST_BEFORE_MISSING_VALUES to LAST]，只傳回索引中的缺漏值。