使用 Microsoft Graph PowerShell SDK 处理 Microsoft 列表

使用 PowerShell 创建、读取、更新和删除 Microsoft 列表中的项目

Microsoft Lists 是一种流行的应用程序，用于在表中组织个人和共享数据。个人列表存储在 OneDrive for Business 中，而共享列表则保存在 SharePoint Online 网站中。许多 PowerShell 脚本依赖于 CSV 文件等输入。使用列表而不是 CSV 文件的一个主要优点是，用户可以更轻松地使用可用于在列表中格式化和呈现数据的 GUI 元素来维护数据，这就是我选择使用列表来保存坏域详细信息的原因之一垃圾邮件发送者驱动我的租户的电子邮件阻止列表的自动更新。另一个优点是列出支持 Microsoft 365 功能（例如保留策略）。

另一方面，CSV 文件在 PowerShell 中非常容易处理，开发人员非常习惯将数据从 CSV 导入到数组中，处理数据，然后将结果导出回 CSV 文件。熟悉是一个很难克服的障碍。本文尝试扩展社区有关通过 Microsoft Graph PowerShell SDK 使用列表的知识。之后，您可以决定是保留 CSV 文件还是移至列表

定义 Microsoft 列表术语

首先，让我们定义一些术语：

• 列表是 SharePoint Online 网站中的一个对象。文档库是列表的一种特殊形式。在这种情况下，我们指的是用于存储非文档数据的列表。
• 列表由项目的集合组成。
• 一个项目有一组用于存储数据的列（字段）。由于用于创建列表的模板，某些字段会自动添加到列表中。其他由列表所有者定义。
• 除了字段之外，每个项目还有一组属性。
• SharePoint Online 附带了一组用于创建列表的标准模板。如果未指定模板，SharePoint Online 将使用genericList 模板创建具有单个Title 列的列表。列表一旦创建，其模板就无法更改。
• 列包含不同类型的信息，例如布尔值、日期时间、人员、文本、数字、personOrGroup 和 货币。

我通常的方法是通过 GUI 创建新列表，以利用在 SharePoint Online 内置列表中输入和显示数据的功能。使用 GUI 总是比创建代码来创建定制列表更容易。如果我以编程方式创建列表，我总是使用最简单的列表模板 (genericList) 并对其进行自定义。

创建 Microsoft 列表

作为我的示例，我回到 2021 年讨论的一个主题，该主题涉及在新帐户的邮箱中创建组织联系人。这个想法是，加入组织的新人可能不知道如何联系人力资源和服务台等单位，因此在他们加入后，后台工作会在他们的邮箱中为重要单位和人员创建联系人。最初的想法是使用 Exchange Online 自定义属性来标记组织联系人。此迭代使用 SharePoint 列表。

第一件事是确保使用正确的权限连接到图表。有两件事是必要的。首先，登录帐户必须是托管该列表的网站的所有者。其次，连接必须同意使用 Sites.Manage.All 和 Sites.ReadWrite.All 范围：

Connect-MgGraph -NoWelcome -Scopes Sites.Manage.All

现在，我们可以运行 Get-MgSite cmdlet 来检索目标站点的详细信息。 id（标识符）是最重要的信息，因为它会传递给其他 cmdlet 来创建列表、获取项目等：

$Site = Get-MgSite -Search 'Office 365 News and Views'
$Site | Format-Table DisplayName, Name, Id

DisplayName               Name          Id
-----------               ----          --
Office 365 News and Views Office365News office365itpros.sharepoint.com,bf887032-2619-44a2-a8b0-2b9cfb1cf701,e95c0fd7-42a6-4bd8-808f-e4683035ed6e

多个站点可能符合搜索条件，因此可能需要进行一些额外的过滤才能找到正确的目标站点。

确定正确的站点后，下一步是创建列表。 New-MgSiteList cmdlet 使用主体参数结构创建一个列表，其中包含要添加到列表的列的定义和要使用的模板。 联系人模板是一个合适的选择。正如预期的那样，该模板包含许多您想要用来捕获有关联系人的信息的列。我们需要添加的是模板中不存在的自定义字段。

$NewListParameters = @{
	displayName = "Organizational Contacts"
    description = "Contacts to add to User Address Book"
	columns = @(
		@{
		 name = "Building"
            	 description = "Contact's building"
		 text = @{ texttype = "plain | richtext" }
        }
		@{
		 name = "BusinessUnit"
            	 description = "Contact's business unit"
		 text = @{ texttype = "plain | richtext" }
		}
        	@{
		 name = "Description"
            	 description = "Brief description of the contact"
		 text = @{ texttype = "plain | richtext" }
		}
	)
	list = @{
		template = "contacts"
	}
}

Microsoft 文档中的示例使用的语法不起作用，因为它不包含每个字段的列类型定义（例如 text=@{ }）。当省略定义时，New-MgSiteList cmdlet 将失败并显示：

New-MgSiteList -SiteId $Site.Id -BodyParameter $NewListParameters
New-MgSiteList_Create: Unable to determine type of provided column definition

Status: 400 (BadRequest)

解决方法是使用 Invoke-MgGraphRequest 运行请求或包含每列将接受的内容的精确定义。有关列定义，请参阅在线文档。

$Uri = ("https://graph.microsoft.com/v1.0/sites/{0}/Lists" -f $Site.Id)
$NewList = Invoke-MgGraphRequest -Uri $Uri -Method POST -Body $NewListParameters

添加项目需要列表标识符。由于 $NewList 变量接收了 Invoke-MgGraphRequest cmdlet 的输出，因此标识符在 $NewList.Id 中可用。否则，可以使用 Get-MgSiteList cmdlet 获取新的列表元数据。运行下面的代码后，列表标识符在 $List.Id 中可用：

$List = Get-MgSiteList -SiteId $Site.Id -Filter "displayName eq 'Organizational Contacts'"

现在可以编辑该列表以最终确定列。例如，附件列是由联系人模板添加的。我不需要这个专栏，所以我把它隐藏了。同样，我不需要传真号码或家庭电话。我还移动了一些列。图 1 显示了添加了一些项目的新列表。

将项目添加到 Microsoft 列表

New-MgSiteListItem cmdlet 将新项目添加到列表中。新项目的有效负载在哈希表中传递，其中嵌入的哈希表包含列名称和值。这里重要的是列的名称必须与列表中定义的名称的拼写和大小写相匹配。

$NewItemParameters = @{
	fields = @{
	Title          = 'Payroll'
        FullName       = 'Employee Payroll'
        FirstName      = 'Employee' 
        Description    = 'Employee Payroll Queries'
        WorkPhone      = '877-0012'
        Company        = 'Office 365 for IT Pros'
        Email          = '[email protected]'
        WorkCity       = 'Dallas'
        }
}

为了避免哈希表中出现错误，提取要检查的列的名称会很有帮助。使用Get-MgSiteList cmdlet 可以轻松完成此操作。例如：

$Fields = Get-MgSiteList -SiteId $Site.Id -ListId $List.Id -ExpandProperty Columns | Select-Object -ExpandProperty Columns | Select-Object DisplayName, Name

填充哈希表中的值后，New-MgSiteListItem cmdlet 可以将项目添加到目标站点的目标列表中：

$NewItem = New-MgSiteListItem -SiteId $site.Id -ListId $List.Id -BodyParameter $NewItemParameters

从 Microsoft 列表中检索项目

如果 Get-MgSiteListItem cmdlet 能够轻松检索项目，那就太好了，但由于字段以键值对形式存储信息，因此调用必须扩展字段属性并指定（选择）项目的名称。要使用的字段。在此示例中，您将了解如何在 Get-MgSiteListItem 检索列表中的所有项目时指定字段。为了使字段更易于操作，它们的值被写入 PowerShell 列表中。

[array]$ListItems = Get-MgSiteListItem -ListId $List.Id -SiteId $Site.Id -ExpandProperty "fields(`$select=id,title,fullname,firstname,workphone,email,workcity,description)" -PageSize 999 -All

$ItemData = [System.Collections.Generic.List[Object]]::new()
ForEach ($Item in $ListItems.fields) { 
    $FullName = ($Item.AdditionalProperties.FullName)
    $ReportLine = [PSCustomObject] @{ 
        Id          = $Item.Id
        FullName    = $FullName
        FirstName   = $Item.AdditionalProperties.FirstName
        LastName    = $Item.AdditionalProperties.Title
        PhoneNumber = $Item.AdditionalProperties.WorkPhone
        Email       = $Item.AdditionalProperties.Email
        City        = $Item.AdditionalProperties.WorkCity
        Description = $Item.AdditionalProperties.Description
    }
    $ItemData.Add($ReportLine)
}

列表中单个项目的详细信息如下所示：

Id          : 4
FullName    : Employee Payroll
FirstName   : Employee
LastName    : Payroll
PhoneNumber : 877-0012
Email       : [email protected]
City        : Dallas
Description : Employee Payroll Queries

从 Microsoft 列表中删除项目

每个项目都有一个从 1 开始的项目标识符，并随着用户向列表添加新项目而递增 1。如果您知道某个项目的标识符，则可以通过运行 Remove-MgSiteListItem cmdlet 将其删除。此示例删除标识符为 2 的项目：

Remove-MgSiteListItem -SiteId $Site.Id -ListId $List.Id -ListItemId 2

请注意，从列表中删除项目不需要确认。这意味着删除项目的代码必须小心删除正确的项目。

在字段中查找具有特定值的项目需要一个中间步骤，将有关项目的数据提取到数组中，然后根据数组进行过滤以找到正确的项目。例如，获取项目的代码创建了一个名为 $ItemData 的数组（列表）。要查找并删除城市属性中值为“Dallas”的任何项目，我们可以这样做：

[array]$ItemsToDelete = $ItemData | Where-Object {$_.City -eq "Dallas"}
ForEach ($Id in $ItemsToDelete.Id) {
  Write-Host ("Removing item {0}…" -f $Id)
  Remove-MgSiteListItem -SiteId $Site.Id -ListId $List.Id -ListItemId $Id
}

要从列表中删除所有项目，请获取项目，然后循环遍历集合以删除每个项目：

[array]$ListItems = Get-MgSiteListItem -ListId $List.Id -SiteId $Site.Id -All -PageSize 999
ForEach ($Id in $ListItems.Id) {
  Write-Host ("Removing item {0}…" -f $Id)
  Remove-MgSiteListItem -SiteId $Site.Id -ListId $List.Id -ListItemId $Id
}

有时删除整个列表并重新开始会更容易。这可以通过运行 Remove-MgSiteList cmdlet 来完成：

Remove-MgSiteList -SiteId $Site.Id -ListId $List.Id

删除列表会将其放入站点回收站。如果保留策略或标签禁止删除列表，SharePoint Online 将不会删除该列表。

PnP 替代方案

SharePoint PnP 模块还可用于创建和维护 SharePoint Online 列表。由于 PnP 和 SharePoint 之间的紧密关联，因此使用 PnP cmdlet 更容易（以下是创建团队列表的示例）。缺点是 PnP 成为脚本维护的额外模块，如果您将 PnP 用于其他目的，这不会成为问题。

下一步是编写一些真实的代码

毕竟，是时候使用组织联系人列表在 Exchange Online 邮箱中创建联系人了。描述如何做到这一点需要更多的空间，因此我将在另一篇文章中介绍该主题。