SharePoint Online：如何在 PowerShell 中使用 CAML 查询？

要求：在 SharePoint Online 中将 CAML 查询与 PowerShell 结合使用。

CAML 是一种基于 XML 的查询语言，代表协作应用程序标记语言，用于查询 SharePoint 列表和库中的项目。这篇文章将教您在 PowerShell 中使用 CAML 查询的基础知识。我们将向您展示如何使用 CAML 查询来筛选和排序 SharePoint 数据，并且我们还将提供一些示例来帮助您入门。

CAML 查询元素和运算符：

以下是 CAML 查询中常用的元素和运算符：

等于

不等于

比...更棒

大于或等于

少于

小于或等于

包含

无效的

不为空

以文字开头

任何给定值的值

值不在任何给定值中

与 Eq 相同 - 在多选查找列中，检查给定值是否存在。

只是与“包含”相反 - 与多个值中的 Not Eq 相同

指定排序顺序

对数据应用过滤器

要检索的字段

要检索的行数

CAML 查询使用字段的内部名称。因此，字段名称中的所有字符都将被解码（例如，“空格”将替换为“_x0020_”，因此“项目名称”字段名称将替换为“Project_x0020_Name”）。您可以阅读 SharePoint 列名称中的显示名称与内部名称来了解更多信息

SharePoint Online：使用 PowerShell 的 CAML 查询示例

以下是用于检索 SharePoint 列表项的 CAML 查询。让我们从“项目”列表中获取所有列表项，其中“项目名称”字段等于“创新指标”。

#Load SharePoint CSOM Assemblies
Add-Type -Path "C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\ISAPI\Microsoft.SharePoint.Client.dll"
Add-Type -Path "C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\ISAPI\Microsoft.SharePoint.Client.Runtime.dll"
 
#Set parameter values
$SiteURL="https://crescent.sharepoint.com/"
$ListName="Projects"
 
#Get Credentials to connect
$Cred= Get-Credential
  
#Setup the context
$Ctx = New-Object Microsoft.SharePoint.Client.ClientContext($SiteURL)
$Ctx.Credentials = New-Object Microsoft.SharePoint.Client.SharePointOnlineCredentials($Cred.Username, $Cred.Password)
 
#Get the List
$List = $Ctx.Web.lists.GetByTitle($ListName)

#Define the CAML Query
$Query = New-Object Microsoft.SharePoint.Client.CamlQuery
$Query.ViewXml = "@
<View>
    <Query>
        <Where>
            <Eq>
                <FieldRef Name='ProjectName' /><Value Type='Text'>Innovation Metrics</Value>
            </Eq>
        </Where>
    </Query>
</View>"

#Get All List Items matching the query
$ListItems = $List.GetItems($Query)
$Ctx.Load($ListItems)
$Ctx.ExecuteQuery()

Write-host "Total Number of Items:"$ListItems.count

#Loop through each List Item
ForEach($Item in $ListItems)
{ 
    Write-host $Item.id
}

SharePoint Online：PnP PowerShell 使用 CAML 获取列表项

使用“Query”参数在 PnP PowerShell cmdlet Get-PnPListItem 中应用 CAML 查询

#Config Variables
$SiteURL = "https://Crescent.sharepoint.com"
$ListName = "Project Tasks"
 
#Connect to PnP Online
Connect-PnPOnline -Url $SiteURL -Credentials (Get-Credential)
 
#CAML Query to Filter List Items
$Query = "<View><Query><Where><Eq><FieldRef Name='ProjectStatus' /><Value Type='Choice'>Completed</Value></Eq></Where></Query></View>"
 
#Get All List Items matching given query
$ListItems = Get-PnPListItem -List $ListName -Query $Query
 
#Loop through each Item
Write-host -f Green "Number of List Items Found:"$ListItems.Count
ForEach($ListItem in $ListItems)
{  
    Write-Host "Id :" $ListItem["ID"] 
    Write-Host "Title :" $ListItem["Title"]
}

SharePoint Online 中的 CAML 查询可按升序或降序排序

以下是用于对结果进行排序的 CAML 查询 PowerShell CSOM。

#Set parameter values
$SiteURL="https://crescent.sharepoint.com/"
$ListName="Projects"
 
#Get Credentials to connect
$Cred= Get-Credential
  
#Setup the context
$Ctx = New-Object Microsoft.SharePoint.Client.ClientContext($SiteURL)
$Ctx.Credentials = New-Object Microsoft.SharePoint.Client.SharePointOnlineCredentials($Cred.Username, $Cred.Password)
 
#Get the List
$List = $Ctx.Web.lists.GetByTitle($ListName)

#Define the CAML Query
$Query = New-Object Microsoft.SharePoint.Client.CamlQuery
$Query.ViewXml = "@
<View>
    <Query> 
        <OrderBy><FieldRef Name='Title' /></OrderBy> 
    </Query> 
</View>"

#Get All List Items matching the query
$ListItems = $List.GetItems($Query)
$Ctx.Load($ListItems)
$Ctx.ExecuteQuery()

Write-host "Total Number of Items:"$ListItems.count

#Loop through each List Item
ForEach($Item in $ListItems)
{ 
    #Do Something
    Write-host $Item.id
    Write-host $Item["Title"]
}  

按降序排序：

<OrderBy><FieldRef Name='Title' Ascending='FALSE' /></OrderBy>

货币字段中的大于、大于或等于、小于、小于或等于运算符：
让我们获取“总投资”值大于或等于 5000 的所有项目

<View>
    <Query>
        <Where>
            <Geq>
                <FieldRef Name='TotalInvestment' /><Value Type='Currency'>5000</Value>
            </Geq>
        </Where>
    </Query>
</View>

在PowerShell CAML查询中组合多个AND和OR运算符：
让我们组合多个AND和OR运算符来获取“总投资”值在5000到10000之间的所有项目，项目部门是“销售”或“营销”。

<View>
    <Query>
        <Where>
            <And>
                <And>
                    <Geq>
                        <FieldRef Name='TotalInvestment' /><Value Type='Currency'>5000</Value>
                    </Geq>
                    <Leq>
                        <FieldRef Name='TotalInvestment' /><Value Type='Currency'>10000</Value>
                    </Leq>
                </And>
                <Or>
                    <Eq>
                        <FieldRef Name='ProjectDepartment' /><Value Type='Choice'>Sales</Value>
                    </Eq>
                    <Eq>
                        <FieldRef Name='ProjectDepartment' /><Value Type='Choice'>Marketing</Value>
                    </Eq>
                </Or>
            </And>
        </Where> 
    </Query>
</View>"

当 CAML 查询中有多个“And”运算符时，验证从上到下开始。

PowerShell 中的 SharePoint Online CAML 查询：“IN”运算符
“In”运算符可替代多个“OR”条件。它验证项目是否在任何给定值中（与 SQL Server“in”运算符相同）。以下是 CAML 查询中“IN”运算符的示例：这将获取“项目名称”列值位于 In 运算符下的任何列出选项中的所有列表项：

<View>
    <Query>
        <Where>
            <In>
                <FieldRef Name='ProjectName' />
                <Values>
                    <Value Type='Text'>Address Book</Value>
                    <Value Type='Text'>Announcements</Value>
                    <Value Type='Text'>Birthday</Value>
                    <Value Type='Text'>Invitation</Value>
                </Values>
            </In>
        </Where>
    </Query>
</View>

获取文本字段包含特定值的列表项：
让我们获取项目名称中包含“Inv”文本的所有列表项，例如“发票”、“年度发票”、“每月库存”等。

<View>
    <Query>
        <Where>
            <Contains>
                <FieldRef Name='ProjectName' /><Value Type='Text'>Inv</Value>
            </Contains>
        </Where>
    </Query>
</View>

获取特定字段不为空的所有列表项的 CAML 查询示例：
让我们获取项目描述具有某个值（不为空）的所有项目

<View>
    <Query>
        <Where>
            <IsNotNull><FieldRef Name='ProjectDescription' /></IsNotNull>
        </Where>
    </Query>
</View>

PowerShell 中的 CAML 查询 ViewFields
CAML 中的“ViewFields”节点定义要从列表中检索哪些字段。例如，您只想从列表中获取“ProjectName”、“Department”和“City”字段。

<View>
    <ViewFields>
        <FieldRef Name='ProjectName'/>
        <FieldRef Name='Department' />
        <FieldRef Name='City' />
    </ViewFields> 
</View>"

SharePoint Online CAML 查询中的“查看范围”

默认情况下（如果您没有为范围参数指定任何内容），列表或库的根文件夹中的所有文件和文件夹都被视为范围。

深入获取所有级别的所有文件和文件夹

<View Scope='RecursiveAll'>  
</View>

从根文件夹获取所有文件：

<View>  
      <Query> 
            <Where>
                 <Eq>
                     <FieldRef Name='FSObjType' /><Value Type='Integer'>0</Value>
                </Eq>
           </Where> 
       </Query> 
</View>

从列表的根文件夹中获取所有文件夹：

<FieldRef Name='FSObjType' /><Value Type='Integer'>1</Value>

从列表的所有文件夹中获取所有文件：

<View Scope='RecursiveAll'>  
            <Query> 
               <Where>
                     <Eq>
                           <FieldRef Name='FSObjType' /><Value Type='Integer'>0</Value>
                     </Eq>
               </Where> 
            </Query> 
</View>

SharePoint Online CAML 查询从列表的所有文件夹中获取所有文件夹：

<View Scope='RecursiveAll'>  
            <Query> 
               <Where>
                     <Eq>
                           <FieldRef Name='FSObjType' /><Value Type='Integer'>1</Value>
                     </Eq>
               </Where> 
            </Query> 
</View>

从列表的特定子文件夹中获取所有项目：

请参阅：SharePoint Online：使用 PowerShell 从子文件夹中获取所有列表项

SharePoint CAML 查询生成器工具

有一些工具可用于生成 CAML 查询。我最喜欢的 SharePoint Online CAML 查询生成器是 U2U CAML 查询生成器和 CAML 设计器，它们可与 SharePoint 本地和 SharePoint Online 配合使用。

常见错误和解决方案：
错误：“一个或多个字段类型未正确安装。进入列表设置页面删除这些字段。”

解决方案：字段在 CAML 查询中通过其内部名称引用！确保引用的字段名称有效。

错误：无法完成此操作

解决方案： CAML 查询的格式不正确！例如，您可能有一个没有结束符“”的 标签。