如何有效地使用 Active Directory cmdlet 上的“-Filter"参数?

Get-ADUser -Filter "memberOf -recursivematch 'CN=test_group,CN=Users,DC=exampledomain,DC=net'"memberOf 是专有名称的array，如果左侧的数组，-recursivematch返回真包含右侧的值.您也可以在这种情况下完全避免使用 Get-ADUser 并使用 Get-ADGroup 从中检索成员:( Get-ADGroup group_name -Properties Members ).Members虽然上面的 Get-ADGroup 示例较短，但是当您有多个时，使用 Get-ADUser 过滤 memberOf条件和需要返回用户，但不一定需要返回本地处理.它可能在交互上不方便，但在与 Active Directory 集成的任何自动化过程中都是一项有价值的技术，并且在您拥有非常大的组的情况下可能变得必要.一个例子是在一个非常大的域中枚举域用户.您可能想重新考虑从 ( Get-ADGroup ).Members 返回 32,000 个用户，然后必须应用额外的过滤.注意:大多数用户实际上会将域用户设置为他们的PrimaryGroup.这是默认设置，大多数情况下不需要更改.但是，您必须在 PrimaryGroup 上使用 -Filter，因为 PrimaryGroup 不存储在 MemberOf 下作为 >ADUser.它也是一个单一的值，而不是一个集合，所以使用 -eq:Get-ADUser -Filter "PrimaryGroup -eq 'PRIMARY_GROUP_DN'";如果查询词包含引号怎么办?在大多数情况下，查询词中的引号会影响您的查询.考虑搜索名称中带有 O'Niel 的用户的示例.这可能会破坏查询或脚本逻辑，具体取决于所使用的引用技术:# 我们的英雄搜索词$term = 奥尼尔"# 龙比比皆是(导致查询解析错误)Get-ADUser -Filter "Name -like '*${term}*'";# 你的公主在另一个城堡里($term 没有展开# 而是搜索文字字符串 ${term})Get-ADUser -Filter 'Name -like "*${term}*"'在这种情况下，您将不得不在两个地方都使用双引号字符串，但幸运的是，转义地狱还不算太糟糕.使用与以前相同的 $term 值:# 你的任务已经结束(这会按预期工作并返回名为 O'Niel 的用户)Get-ADUser -Filter "Name -like ""*${term}*"""";# 反引号很难看，但这也有效Get-ADUser -Filter "Name -like `"*${term}*`""注意:如果您的查询查找包含单引号和双引号的字段值，我不确定在使用-Filter 参数.但是，-LDAPFilter 应该能够促进这一点，因为括号 () 而不是引号用于内部查询边界.请参阅过滤器示例"nofollow noreferrer">about_ActiveDirectory_Filter 和 LDAP 过滤器 部分directory-characters-to-escape.aspx#LDAP_Filters" rel="nofollow noreferrer">this AD Escape Characters 帖子以获取更多信息，因为 -LDAPFilter 超出了本答案的范围.匹配多个属性匹配多个属性没有太大区别，但最好将每个条件用括号括起来().这是一个示例，让我们查找没有关联电子邮件地址的非域管理员帐户(假设我们通过用户名命名法*-da 知道这一点).Get-ADUser -Filter "(samaccountname -notlike '*-da') -and (EmailAddress -notlike '*')";这个有点棘手，因为我们不能在 -Filter 中为条件的右侧传入一个空值，就像 EmailAddress.但是 '*' 匹配任何非空值，因此我们可以利用 -notlike 比较运算符利用该行为来查找 EmailAddress 的空值.要分解过滤器，请确保任何以 -da 结尾的帐户都不会被过滤器匹配，然后也只匹配没有 的帐户>EmailAddress 值.要避免的事情不要尝试使用 { ScriptBlock } 作为过滤器参数.是的，我们更愿意编写 ScriptBlock，而不是担心构建 string 并确保它正确转义.使用它们绝对有吸引力.我已经看到很多使用 ScriptBlock 作为 -Filter 参数的答案，或者有问题的人(包括我自己)试图做这样的事情，而且很惊喜！！！什么都没有返回:导入-Csv C:userInfoWithEmails.csv |Foreach-对象{Get-ADUser -Filter { EmailAddress -eq $_.Email }}-Filter 不支持 ScriptBlocks，但它们Kind of Work Some™ 因为当它们被呈现为文字字符串时，-Filter 使用的 PowerShell 表达式引擎能够在运行查询之前呈现您的变量.正因为如此，如果你使用像 $_ 或 $emailAddress 这样的简单变量扩展，它们在技术上是可行的，但它最终会让你头疼，特别是如果你试图访问一个对象属性(如上)，因为它根本不起作用.此外，对于这些变量的扩展方式，您会获得大量未记录(或难以找到信息)的行为，因为它们并不总是 ToString'd 如您所愿.弄清楚它变成了一个反复试验的事情.诚然，某些属性通过这种方式更容易获得，但是在编程时使用您不理解且几乎没有文档的技术是一个冒险的举动.因此，我不依赖于 AD cmdlet 使用文字字符串或 ScriptBlock 时发生的 cmdlet 内部变量扩展.每次都使用字符串过滤器，如果需要使用变量值或对象属性作为过滤器的一部分，请使用 变量替换 或 命令替换.如果您只关心要过滤的属性，则无需指定额外的 -Properties.AD cmdlet 可以评估 -Filter 参数中的所有属性，而无需将它们传递到管道中.虽然我在做，但永远不要使用 -Properties *，除非您出于某种原因检查返回对象的所有属性，例如在脚本期间开发，或者交互式地您不太确定您在寻找什么(请注意并非所有属性都默认返回).仅指定AD对象返回后需要处理的属性.这是有原因的 - 某些属性获取值的成本特别高.最佳做法是仅转发您需要在管道中处理的属性.您不能使用 -Filter 参数来过滤 构造属性 使用-Filter 或-LDAPFilter.这是因为根据定义，构造的属性是动态计算的(或构造的")，而不是实际存储在 Active Directory 中的值.我想这是因为许多计算属性的计算成本很高，必须在每个相关的 ADObject 上执行以从 AD 端对其进行过滤.如果你需要过滤构造属性，你需要首先返回一组ADObjects，用-Properties指定计算属性>，然后使用 Where-Object 或其他一些技术进一步过滤.通配符 * 不适用于返回 DistinguishedName 类型的字段，例如 DistinguishedName、manager、PrimaryGroup 等.此外，DistinguishedNames 带有它们的 自己的一套转义规则.某些 AD 属性作为适当的 DateTime 返回，以便在 PowerShell 中进行更轻松的处理，但上面举例说明的基本时间比较需要将基础 ADAttribute 定义为Interval 类型.一些基于时间的属性，例如 whenCreated 被定义为 Generalized-Time 字符串，它们是 UTC 时区，格式为 yyyMMddHHmmss.Z.此外，msDS-UserPasswordExpiryTimeComputed 等一些属性采用文件时间格式(并通过 AD cmdlet 返回).将用于过滤的目标 DateTime 转换为 Generalized-Time string 格式，如下所示:( Get-Date ).ToUniversalTime().ToString('yyyMMddHHmmss.z').请注意，此字符串不能直接转换回 DateTime.将返回的 file-time 转换为 DateTime 像这样(以上述属性为例):[DateTime]::FromFileTime($adUser.'msDS-UserPasswordExpiryTimeComputed')总结将 -Filter 参数与 AD cmdlet 一起使用的这些技术将在迭代大型 AD 环境时为您节省成本高昂的处理时间，并且应该会提高 Powershell AD 操作的性能.我希望这有助于解释 AD cmdlet 的 -Filter 参数的一些难以捉摸的行为.其他资源了解您正在使用的 AD 属性是一个好主意，以下是一些 Microsoft 资源，可帮助您识别和了解不同属性在 AD 架构中的定义和功能，以及了解有关 -Filter 语法:OpenSpecsAD 架构about_ActiveDirectory_Filter虽然已过时，但此文档帮助仍然准确.由于存在错误，此后一直未更新2013. 直到修复此错误并且文档已更新，上面的链接就足够了.All too often I see the following type of code on this site, specific to the AD cmdlets:Get-ADUser -Filter * | Where-Object { $_.EmailAddress -eq $email }The problem is that you are returning every single user object in Active Directory, and then processing it a second time. How can we improve upon this, not only to reduce the time it takes to run the script, but to also take the unnecessary load off of Active Directory, and possibly the network? 解决方案 What is so bad about -Filter *?You are effectively selecting and returning every object that exists in AD, based on the cmdlet you are using (e.g. Get-ADUser, Get-ADComputer, Get-ADGroup, the generic Get-ADObject, etc.). This is an expensive thing to do, especially in larger AD environments. It is fine to do this if you legitimately need to operate on every possible object, but in most cases you do not need to return everything. On top of this, your script will end up processing far more data than it needs to, increasing execution time and used processing time when it just isn't necessary.The -Filter parameter can do more than just match on everything, which is effectively what -Filter * does. The -Filter string is very much like Powershell syntax (not quite, but most of the way there). You can use most of the same logical operators that Powershell supports, and they work much in the same way that Powershell operators do. This answer aims to clarify this and explain how to use this elusive parameter. These examples will use the Get-ADUser cmdlets but this also extends to the other Get-ADObject cmdlets which use filters as well.SyntaxThe syntax for the -Filter string is "PropertyName -comparisonoperator 'somevalue'", though you can string multiple conditions together with logical operators such as -and and -or. Note that there are no regex matching operators, so you will have to make do with -like and -notlike globbing.Comparison OperatorsMS calls these FilterOperators but they are used in the same way asPowerShell's comparison operators are (ignoring the fact that technically -bor and -band are arithmetic operators). These are used for comparing values:-eq, -le, -ge, -ne, -lt, -gt, -approx, -bor, -band, -recursivematch, -like, -notlikeThe only ones which are unique to the -Filter query syntax are -approx and -recursivematch. Don't worry about -approx, it is functionally equivalent to -eq in Active Directory.Despite its name, -recursivematch is not a regex matching operator, it works like PowerShell's-contains operator in that it will return $true if the collection contains the target value.Logical OperatorsMS calls these JoinOperators but they fill the same role as their PowerShell logical operator equivalent. These are used to join multiple conditions together in a single query:-and, -orStrangely enough, MS gives negation to a special operator type called NotOperator, which consists of a single operator:-notMatching on a propertyTo use the example in the question, let's find a user matching an email address, but without piping to Where-Object (crazy right???):$email = '[e-mail]'Get-ADUser -Filter "EmailAddress -eq '${email}'"Done. Get-ADUser will return any accounts where the EmailAddress property equals whatever the $email variable is.What if we want to find all user accounts that haven't been logged onto in the last 30 days? But a date string is more complex than an email! Who cares, still pretty simple!# Get the date from 30 days ago$notUsedSince = ( Get-Date ).AddDays( -30 )Get-ADUser -Filter "LastLogonDate -lt '${notUsedSince}'"This returns all users who have not logged on in the last 30 days.Getting users who are members of a groupIf you want to get all ADUsers who are members of a certain group, we can make use of the-recursivematch operator for this:Get-ADUser -Filter "memberOf -recursivematch 'CN=test_group,CN=Users,DC=exampledomain,DC=net'"memberOf is an array of Distinguished Names, -recursivematch returns true if the array on the lefthand side contains the value on the righthand side.You can alternatively avoid the use of Get-ADUser at all in this scenario and use Get-ADGroup to retrieve the members from that:( Get-ADGroup group_name -Properties Members ).MembersWhile the Get-ADGroup example above is shorter to type, filtering on memberOf with Get-ADUser can be effective when you have multiple conditions and need to return users that , but not necessarily need to return it for local processing. It may be interactively inconvenient but it is a worthy technique in any automated process integrating with Active Directory and may become necessary in cases where you have extremely large groups.One example is when enumerating Domain Users in a very large domain. You might want to rethink returning 32,000 users from ( Get-ADGroup ).Members to then have to apply additional filtering.What if the query term contains a quote?Quotes in the query term will throw a wrench in your query in most cases. Consider the example of searching for users with O'Niel in the name. This can break either the query or your script logic depending on the quoting technique used:# Our heroic search term$term = "O'Niel"# Dragons abound (results in a query parsing error)Get-ADUser -Filter "Name -like '*${term}*'"# Your princess is in another castle ($term is not expanded# and the literal string ${term} is instead searched for) Get-ADUser -Filter 'Name -like "*${term}*"'In this case you will have to use double-quoted strings in both places, but fortunately the escape-hell isn't too bad. Using the same value for $term as before:# Your quest is over (this works as intended and returns users named O'Niel)Get-ADUser -Filter "Name -like ""*${term}*"""# Backticks are ugly but this also worksGet-ADUser -Filter "Name -like `"*${term}*`""Matching on multiple propertiesMatching on multiple properties is not much different, but it's best to wrap each condition in parentheses (). Here's an example, let's find non-domain admin accounts (assuming we know this by the username nomenclature *-da) that don't have an email address associated with them.Get-ADUser -Filter "(samaccountname -notlike '*-da') -and (EmailAddress -notlike '*')"This one is a little trickier, because we can't pass in an empty value for the right side of a condition in the -Filter, as in the case for EmailAddress. But '*' matches any non-empty value, so we can leverage that behavior with the -notlike comparison operator to find empty values for EmailAddress. To break down the filter, make sure that any accounts ending in -da aren't matched by the filter, and then also only match accounts that do not have an EmailAddress value.Things to avoidDon't try to use a { ScriptBlock } for your filter parameters. Yes, we are all more comfortable with writing a ScriptBlock than worrying about building a string and making sure it's escaped properly. There is definitely an attraction to using them. I've seen so many answers using a ScriptBlock as a -Filter argument, or people having problems (myself included) trying to do something like this, and SURPRISE!!! Nothing gets returned:Import-Csv C:userInfoWithEmails.csv | Foreach-Object { Get-ADUser -Filter { EmailAddress -eq $_.Email }}-Filter doesn't support ScriptBlocks, but they Kind of Work Sometimes™ because while they get rendered as a literal string, the PowerShell Expression Engine used by -Filter is capable of rendering your variables before running the query. Because of this, they will technically work if you use simple variable expansion like $_ or $emailAddress, but it will eventually cause you a headache, especially if you try to access an object property (like above) because it simply won't work.In addition, you get largely undocumented (or difficult to locate info) behavior for how these variables are expanded, because they are not always ToString'd like you would expect. Figuring it out becomes a trial-and-error affair. Some attributes are admittedly easier to obtain this way, but using techniques you don't understand and which have little documentation is a risky move when programming. Because of this, I don't relying on the cmdlet-internal variable expansion that occurs whether you use a literal string or a ScriptBlock with the AD cmdlets.Use a string filter every time, and if you need to use a variable value or object property as a portion of the filter, use Variable Substitution or Command Substitution.You do not need to specify additional -Properties if you only care about a property to filter on it. The AD cmdlets can evaluate all properties within the -Filter parameter without needing to pass them down the pipeline.And while I'm at it, don't ever use -Properties *, excepting maybe if you are inspecting all properties on a returned object for some reason, such as during script development, or interactively you're not quite sure what you're looking for (note that not all attributes are returned by default).Only specify the properties you need to process after the AD object has been returned. There is a reason for this - some properties are particularly expensive to get the values for. Best practice is to only forward the properties you need to process down the pipeline.You cannot use the -Filter parameter to filter on Constructed Attributes using either-Filter or -LDAPFilter. This is because constructed attributes are, by definition, computed (or "constructed") on the fly, and are not actually stored values within Active Directory. I imagine it's because many Computed Attributes are expensive to compute, which would have to be performed on every relevant ADObject to filter on it from the AD side.If you need to filter on Constructed Attributes, you will need to first return a set of ADObjects, specifying the Computed Attribute with -Properties, then further filter with Where-Object or some other technique.Wildcards * do not work for fields that return a DistinguishedName type, such as DistinguishedName, manager, PrimaryGroup, etc. In addition, DistinguishedNames carry their own set of escaping rules.Some AD attributes are returned as a proper DateTime for easier processing in PowerShell, but the basic time comparison exemplified above requires the underlying ADAttribute to be defined as the Interval type. Some time-based properties, such as whenCreated are defined as Generalized-Time strings, which are UTC timezone and formatted as yyyMMddHHmmss.Z. Additionally, some properties like msDS-UserPasswordExpiryTimeComputed are in file-time format (and is returned as such with the AD cmdlets).Convert a target DateTime for filtering to the Generalized-Time string format like so:( Get-Date ).ToUniversalTime().ToString('yyyMMddHHmmss.z').Note that this string is not directly convertible back to a DateTime.Convert a returned file-time to a DateTime like so (using the aforementioned property as an example):[DateTime]::FromFileTime($adUser.'msDS-UserPasswordExpiryTimeComputed')In summariumThese techniques using the -Filter parameter with the AD cmdlets will save you costly processing time when iterating over large AD environments, and should improve the performance of your Powershell AD operations. I hope this helps explain some of the elusive behaviors of the AD cmdlets' -Filter parameter.Additional ResourcesAs it is a good idea to understand the AD attributes you are working with, below are some Microsoft resources to help you identify and understand how different attributes are defined and function within the AD schema, as well as learn more about the -Filter syntax:OpenSpecsAD Schemaabout_ActiveDirectory_FilterWhile outdated, this document help is still accurate. Due to a bug it has not been updated since 2013. Until this bug is fixed and the documentation has been updated, the above link will have to suffice. 这篇关于如何有效地使用 Active Directory cmdlet 上的“-Filter"参数?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持！