การทำงานกับรายการ Microsoft โดยใช้ Microsoft Graph PowerShell SDK

สร้าง อ่าน อัปเดต และลบรายการในรายการ Microsoft ด้วย PowerShell

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 คอลัมน์เดียว เมื่อสร้างรายการแล้ว จะไม่สามารถเปลี่ยนแปลงเทมเพลตได้
• คอลัมน์เก็บข้อมูลประเภทต่างๆ เช่น บูลีน, dateTime, บุคคล, ข้อความ, หมายเลข, 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 เพื่อดึงรายละเอียดของไซต์เป้าหมายได้ รหัส (ตัวระบุ) เป็นข้อมูลที่สำคัญที่สุด เนื่องจากข้อมูลนี้จะถูกส่งไปยัง cmdlets อื่นเพื่อสร้างรายการ ดึงข้อมูลรายการ และอื่นๆ:

$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=@{ }) เมื่อละเว้นคำจำกัดความ cmdlet New-MgSiteList จะล้มเหลวด้วย:

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

Status: 400 (BadRequest)

วิธีแก้ปัญหาคือใช้ Inrigger-MgGraphRequest เพื่อเรียกใช้คำขอหรือรวมคำจำกัดความที่ชัดเจนของสิ่งที่แต่ละคอลัมน์จะยอมรับ ดูเอกสารออนไลน์สำหรับคำจำกัดความของคอลัมน์

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

จำเป็นต้องมีตัวระบุรายการเพื่อเพิ่มรายการ เนื่องจากตัวแปร $NewList ได้รับเอาต์พุตของ Inrigger-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          = 'Employee.Payroll@Office365itpros.com'
        WorkCity       = 'Dallas'
        }
}

เพื่อหลีกเลี่ยงข้อผิดพลาดในตารางแฮช การแยกชื่อของคอลัมน์ที่จะตรวจสอบจะเป็นประโยชน์ ทำได้ง่ายๆ โดยใช้ Get-MgSiteList cmdlet ตัวอย่างเช่น:

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

ด้วยค่าในตารางแฮชที่เติมไว้ cmdlet New-MgSiteListItem สามารถเพิ่มรายการลงในรายการเป้าหมายในไซต์เป้าหมาย:

$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       : Employee.Payroll@Office365itpros.com
City        : Dallas
Description : Employee Payroll Queries

การลบรายการออกจากรายการ Microsoft

แต่ละรายการมีตัวระบุรายการเริ่มต้นจาก 1 และเพิ่มขึ้นทีละ 1 เมื่อผู้ใช้เพิ่มรายการใหม่ลงในรายการ หากคุณทราบตัวระบุสำหรับรายการ คุณสามารถลบออกได้โดยการเรียกใช้ cmdlet Remove-MgSiteListItem ตัวอย่างนี้จะลบรายการที่มีตัวระบุ 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
}

บางครั้งการลบรายการทั้งหมดแล้วเริ่มต้นใหม่อาจง่ายกว่า ซึ่งสามารถทำได้โดยการเรียกใช้ cmdlet Remove-MgSiteList:

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

การลบรายการจะทำให้รายการนั้นอยู่ในถังรีไซเคิลของไซต์ SharePoint Online จะไม่เอารายการออกถ้านโยบายการเก็บรักษาหรือป้ายชื่อห้ามไม่ให้มีการลบ

ทางเลือก PnP

โมดูล SharePoint PnP ยังสามารถใช้เพื่อสร้างและดูแลรักษารายการ SharePoint Online ได้อีกด้วย เนื่องจากความสัมพันธ์ที่แน่นแฟ้นระหว่าง PnP และ SharePoint จึงง่ายต่อการทำงานกับ PnP cmdlets (นี่คือตัวอย่างการสร้างรายชื่อทีม) ข้อเสียคือ PnP กลายเป็นโมดูลพิเศษสำหรับการบำรุงรักษาสคริปต์ ซึ่งจะไม่เป็นปัญหาหากคุณใช้ PnP เพื่อวัตถุประสงค์อื่น

ขั้นตอนต่อไปคือการเขียนโค้ดจริงบางส่วน

หลังจากนั้น จะต้องถึงเวลาที่จะใช้รายการที่ติดต่อขององค์กรเพื่อสร้างที่ติดต่อในกล่องจดหมาย Exchange Online การอธิบายวิธีการดังกล่าวต้องใช้พื้นที่มากกว่าที่ฉันมีอยู่ ดังนั้นฉันจะกล่าวถึงหัวข้อนี้ในบทความอื่น