วิธีใช้ Invivo-MgGraphRequest กับ PowerShell

Invivo-MgGraphRequest เป็น cmdlet อเนกประสงค์ที่ช่วยให้คุณทำการเรียก Microsoft Graph API ได้เกือบทุกครั้ง โดยไม่จำเป็นต้องใช้ cmdlet หรือโมดูล Microsoft Graph เพิ่มเติม สิ่งนี้มีประโยชน์เนื่องจากคุณอาจไม่ต้องการพึ่งพาโมดูล Microsoft Graph PowerShell อื่นๆ แต่ยังต้องการใช้โมดูลการรับรองความถูกต้องเพื่อความเรียบง่าย

ในบทช่วยสอนนี้ ฉันจะแสดงให้คุณเห็นถึงวิธีการใช้ Invoke-MgGraphRequest cmdlet ใน Microsoft Graph PowerShell SDK เพื่อสร้างคำขอ REST API ไปยัง Microsoft Graph เพื่อให้คุณสามารถดู แก้ไข และสร้างทรัพยากรใน Microsoft 365 และ Azure

Invivo-MgGraphRequest ทำงานอย่างไร

Invoke-MgGraphRequest cmdlet ทำงานโดยส่งคำขอ REST API ไปยัง Microsoft Graph ซึ่งคุณสามารถทำได้โดยการระบุเส้นทาง REST URI เนื้อหาคำขอ และพารามิเตอร์วิธีการร้องขอในคำสั่งของคุณ

ตามหลักการแล้ว เมื่อทำงานกับ Microsoft Graph PowerShell คุณอาจควบคุมได้ดีขึ้นและสามารถใช้ตรรกะได้ดีขึ้นเมื่อใช้ cmdlets ที่เทียบเท่ากันเพื่อสร้าง ลบ และอัปเดตทรัพยากร อย่างไรก็ตาม ไม่ใช่ทุกงานที่มี cmdlet ที่เกี่ยวข้อง ดังนั้นการใช้ Invoid-MgGraphRequest cmdlet จึงมีประโยชน์อย่างยิ่งในการสร้างทรัพยากรที่ไม่รองรับ cmdlet

การแบ่งย่อยพารามิเตอร์ทั้งหมดที่คุณสามารถใช้กับ Invivo-MgGraphRequest ได้มีดังต่อไปนี้:

Invoke-MgGraphRequest [[-Method] {GET | POST | PUT | PATCH | DELETE}] 
[-Uri] <uri> 
[[-Body] <Object>] 
[[-Headers] <IDictionary>] 
[[-OutputFilePath] <string>]
[[-InferOutputFileName]]
[[-InputFilePath] <string>] 
[[-PassThru]] [[-Token] <securestring>] 
[[-SkipHeaderValidation]]
[[-ContentType] <string>]
[[-Authentication] {Default | UserProvidedToken}]
[[-SessionVariable] <string>]
[[-ResponseHeadersVariable] <string>] 
[[-StatusCodeVariable] <string>] 
[[-SkipHttpErrorCheck]] 
[[-GraphRequestSession] <GraphRequestSession>]
[[-UserAgent] <string>] 
[[-OutputType] {HashTable | PSObject | HttpResponseMessage | Json}] 
[-Break] [<CommonParameters>]

REST URI คืออะไร

ข้อมูลส่วนแรกที่คุณต้องระบุในคำสั่งของคุณเมื่อใช้ Invoke-MgGraphRequest cmdlet คือพาธ REST URI URI (หรือ Universal Resource Identifier) ระบุตำแหน่งที่ทรัพยากรเฉพาะสามารถพบได้ในกรณีของเราใน Microsoft Graph API

เรามาตรวจสอบว่าเส้นทาง REST URI ถูกสร้างขึ้นอย่างไร ตัวอย่างเช่น เส้นทาง URI ที่เหลือสำหรับอุปกรณ์เฉพาะที่ลงทะเบียนกับ Microsoft Entra ID จะเป็น https://graph.microsoft.com/v1.0/devices/{id} หากต้องการทำลายสิ่งนั้น:

https://graph.microsoft.com/v1.0/อุปกรณ์/{id}

https://graph.microsoft.com - นี่คือชื่อโฮสต์ (หรือจุดสิ้นสุด) ของบริการ Microsoft Graph

v1.0/ - นี่คือเวอร์ชันโปรไฟล์ Microsoft Graph

อุปกรณ์/ - คือเส้นทางไปยังทรัพยากร

{id} - นี่คือรหัสทรัพยากรที่ไม่ซ้ำกัน

วิธีค้นหา REST URI ที่คุณต้องการ

เมื่อใดก็ตามที่คุณส่งคำขอไปยัง Microsoft Graph คุณจะต้องระบุเส้นทาง URI ด้วยเหตุนี้ คุณจะต้องทราบเส้นทางไปยังทรัพยากรที่คุณต้องการเปลี่ยนแปลงอย่างแน่นอน นี่เป็นหนึ่งในความซับซ้อนที่เพิ่มเข้ามาเมื่อคุณไม่ได้ใช้ cmdlets เฉพาะอันใดอันหนึ่ง

มีวิธีการต่างๆ มากมายที่คุณสามารถใช้เพื่อระบุเส้นทางไปยังทรัพยากรเฉพาะที่คุณต้องการ

ตัวเลือกที่ 1 คือการใช้ไซต์ Microsoft Graph Explorer คุณสามารถเข้าถึง Graph Explorer ได้ที่: https://developer.microsoft.com/en-us/graph/graph-explorer

เริ่มต้นด้วยการค้นหาทรัพยากรที่คุณต้องการภายใต้หัวข้อทรัพยากร จากนั้นเลือกทรัพยากรของคุณจากรายการ คุณจะเห็น URI ปรากฏในกล่องข้อความที่ไฮไลต์ด้านล่าง

ตัวเลือก 2 เป็นวิธีที่ฉันชอบ คุณสามารถใช้เครื่องมือสำหรับนักพัฒนา (หรือคุณสมบัติ 'ตรวจสอบ') ในเว็บเบราว์เซอร์ของคุณเพื่อดูส่วนหัวของคำขอเมื่อสร้างทรัพยากร สมมติว่าคุณต้องการเปลี่ยนหมวดหมู่ของอุปกรณ์ใน Intune เริ่มต้นด้วยการเปิดคุณสมบัติของอุปกรณ์ จากนั้นเปลี่ยนข้อมูลที่คุณต้องการ แต่ก่อนที่คุณจะคลิกบันทึก ให้คลิกขวาที่หน้าเว็บแล้วคลิก ตรวจสอบ

ตอนนี้เลือกแท็บ เครือข่าย ตามที่ฉันได้เน้นไว้ด้านล่าง:

เมื่อคุณเลือกแท็บเครือข่ายแล้ว คุณสามารถกลับมาและคลิก บันทึก ในหน้าคุณสมบัติของอุปกรณ์ บนแท็บเครือข่าย คุณจะเห็นคำขอปรากฏใต้หัวข้อชื่อ

เลือกคำขอจากรายการที่ตรงกับการกระทำของคุณ ชื่อต่างๆ มักจะมีความหมายมากกว่าด้านล่างนี้:

ตอนนี้คุณสามารถดูเส้นทาง URI แบบเต็มที่ตรงกับการกระทำที่คุณต้องการดำเนินการบนแท็บส่วนหัวทางด้านขวา แม้ว่าคุณจะดำเนินการในพอร์ทัลแล้ว แต่คุณสามารถใช้ข้อมูลใหม่นี้เพื่อใช้การเปลี่ยนแปลงนี้ทางโปรแกรมในอนาคตหรือกับอุปกรณ์หลายเครื่องพร้อมกันได้ ผลลัพธ์ทั้งหมดของข้างต้นอยู่ด้านล่าง:

https://graph.microsoft.com/beta/deviceManagement/managedDevices('956a2c3b-bd8d-4339-9f26-3d1b034748f6')/deviceCategory/$ref

นอกจากนี้ ให้จดบันทึกวิธีการร้องขอ (ในกรณีนี้คือ PUT) เนื่องจากเราจะใช้วิธีนี้ในภายหลังเมื่อสร้างคำขอของเรา

วิธีสร้างเนื้อหาคำขอ

เนื้อหาคำขอหรือที่เรียกว่าเพย์โหลดคือข้อมูลที่ส่งกลับไปยัง Microsoft Graph (จุดสิ้นสุด API) ซึ่งมีข้อมูลทั้งหมดเกี่ยวกับคำขอ เนื้อความของคำขอจะถูกส่งไปยัง Microsoft Graph ในรูปแบบ JSON รูปแบบนี้ใช้กันอย่างแพร่หลายโดยไคลเอ็นต์ API และโดยปกติจะมีข้อมูลสำหรับสร้างหรืออัปเดตทรัพยากรที่มีอยู่

มาดูเนื้อหาตัวอย่างจากตัวอย่างด้านบนในตัวเลือกที่ 2 ด้านบนเราได้เปลี่ยนหมวดหมู่ของอุปกรณ์ใน Intune และวิเคราะห์ส่วนหัวของคำขอโดยใช้เครื่องมือตรวจสอบในเบราว์เซอร์ของเรา เพื่อให้ได้เนื้อหาคำขอ เราจะทำสิ่งเดียวกัน

ทำตามขั้นตอนเดียวกันกับข้างต้นในตัวเลือก 2 เพื่อดูคำขอ แต่คราวนี้เลือกแท็บ เพย์โหลด จากนั้นเลือก ดูแหล่งที่มา

ตอนนี้คุณจะเห็นเพย์โหลดคำขอในรูปแบบ Raw JSON:

จากนั้นเราสามารถวางโค้ดนี้ลงใน Microsoft Graph Explorer หรือ IDE ที่คุณเลือกเพื่อจัดรูปแบบได้อย่างถูกต้อง มีเครื่องมือออนไลน์มากมายที่จะจัดรูปแบบโค้ด JSON ของคุณโดยอัตโนมัติเพื่อปรับปรุงให้อ่านง่ายขึ้น

{
"@odata.id":"https://graph.microsoft.com/beta/deviceManagement/deviceCategories/3725a237-e0e4-4b0b-aab0-3868e12c8ba9"
}

ทดสอบ URI และเพย์โหลดของเรา

ก่อนที่เราจะเริ่มการพัฒนาสคริปต์ใดๆ เป็นความคิดที่ดีที่จะทดสอบ URI และเพย์โหลดของเราเพื่อให้แน่ใจว่าทำงานได้ตามที่คาดหวัง ฉันขอแนะนำให้คุณทำเช่นนี้โดยใช้เครื่องมือเว็บ Microsoft Graph Explorer ที่ Microsoft มอบให้

ทำตามขั้นตอนด้านล่างเพื่อทดสอบ: (ฉันจะใช้ตัวอย่าง URI และ Payload ที่เราใช้ด้านบน)

1. เริ่มต้นด้วยการเข้าสู่ระบบ Microsoft Graph Explorer โดยไปที่นี่ และเลือกไอคอนโปรไฟล์ที่ด้านบนขวา

2. เมื่อเข้าสู่ระบบแล้ว ให้วาง URI ลงในกล่องข้อความ URL (ทางด้านซ้ายของปุ่ม 'เรียกใช้แบบสอบถาม') จากนั้นวางเพย์โหลดลงในเนื้อหาคำขอ ดังนี้:

3. ก่อนที่คุณจะเรียกใช้การสืบค้น ตรวจสอบให้แน่ใจว่าคุณกลับเข้าสู่พอร์ทัลเพื่อคืนค่าการเปลี่ยนแปลงที่คุณทำไว้ในตอนแรกเพื่อรวบรวมข้อมูลที่จำเป็น เมื่อเราเรียกใช้คำขอในเครื่องมือ Graph Explorer เราจะสามารถตรวจสอบได้ว่าคำขอนั้นได้รับการอัปเดตอีกครั้งในพอร์ทัลเพื่อยืนยันว่าคำขอนั้นใช้งานได้

4. สุดท้าย เปลี่ยนวิธีการร้องขอเป็น PUT และคลิก เรียกใช้การค้นหา ในกรณีของคำขอนี้ ดำเนินการสำเร็จ แต่การตอบกลับกลับว่างเปล่า แต่ถ้าเราตรวจสอบคุณสมบัติของอุปกรณ์จากพอร์ทัล Intune คุณสมบัติเหล่านั้นจะได้รับการอัปเดตตามที่คาดไว้

วิธีค้นหาสิทธิ์ที่จำเป็นโดยใช้ Graph Explorer

สิ่งหนึ่งที่คุณไม่สามารถรวบรวมจากการแตกส่วนหัวของคำขอและเพย์โหลดสำหรับคำขอของคุณโดยใช้เครื่องมือตรวจสอบคือการอนุญาตที่จำเป็นในการดำเนินการที่คุณต้องการ

มีสองวิธีที่สะดวกในการระบุสิทธิ์ที่จำเป็น...

ตัวเลือกที่ง่ายที่สุดคือการใช้แท็บ Microsoft Graph Explorer Modify Permissions ซึ่งจะบอกคุณอย่างชัดเจนว่าสิทธิ์ใดบ้างที่จำเป็นในการเรียกใช้แบบสอบถามของคุณ ในกรณีของเพย์โหลดทดสอบของฉัน คุณสามารถดูได้ว่าสิทธิ์ใดบ้างที่จำเป็นด้านล่าง

อีกทางเลือกหนึ่งคือใช้ Find-MgGraphPermission cmdlet ซึ่งจะแสดงรายการสิทธิ์ที่มีอยู่ทั้งหมดสำหรับ Microsoft Graph

การเรียกใช้ cmdlet เพียงอย่างเดียวจะทำให้เกิดข้อมูลจำนวนมาก และเพื่อให้เข้าใจสิทธิ์แต่ละรายการ คุณจะต้องอ่านคำอธิบาย หากต้องการจำกัดขอบเขตให้แคบลง คุณสามารถกรองผลลัพธ์ของคุณได้

Find-MgGraphPermission | Where-Object {$_.Name -match "Device"}

ผลลัพธ์ของคุณจะมีลักษณะดังนี้:

สร้างสคริปต์ของเราโดยใช้ Invoke-MgGraphRequest cmdlet

หากคุณได้ทำตามขั้นตอนก่อนหน้านี้ ตอนนี้คุณควรมี (หรือรู้วิธีรับ) ข้อมูลทั้งหมดที่เราต้องการในการสร้างสคริปต์ PowerShell เพื่อให้เราสามารถปรับใช้หรือแก้ไขทรัพยากรของเราโดยทางโปรแกรม ฉันจะใช้ตัวอย่างเดียวกันกับที่เราทดสอบข้างต้นใน Graph Explorer อีกครั้ง

นี่คือสคริปต์ตัวอย่างแบบเต็มของเรา: (เลื่อนไปเรื่อย ๆ เพื่อดูรายละเอียด)

#Connect to Microsoft Graph
Connect-MgGraph -Scopes DeviceManagementManagedDevices.ReadWrite.All

#Define the URI
$uri = @'
https://graph.microsoft.com/beta/deviceManagement/managedDevices('956a2c3b-bd8d-4339-9f26-3d1b034748f6')/deviceCategory/$ref
'@

#Define policy parameters
$json = @'
{
"@odata.id":"https://graph.microsoft.com/beta/deviceManagement/deviceCategories/3725a237-e0e4-4b0b-aab0-3868e12c8ba9"
}
'@

#Create policy
Invoke-MgGraphRequest -Uri $uri -Body $json -Method PUT -ContentType "application/json"

เพื่อแยกย่อยสคริปต์ให้เข้าใจ ผมจะพยายามอธิบายแต่ละส่วน

ประการแรก ฉันจะเชื่อมต่อกับ Microsoft Graph โดยใช้สิทธิ์จำนวนน้อยที่สุดที่จำเป็นในการรันงานของเรา

Connect-MgGraph -Scopes DeviceManagementManagedDevices.ReadWrite.All

ที่นี่ฉันกำลังจัดเก็บเส้นทาง URI ไว้ในตัวแปร $uri สังเกตว่าฉันใช้ @' และ '@ ล้อมรอบ URI ของฉันอย่างไร ซึ่งเรียกว่า 'Here Strings' ในที่นี้มีการใช้สตริงเพื่อให้แน่ใจว่าข้อความระหว่างข้อความเหล่านั้นถูกใช้ตามตัวอักษร หากไม่มี "สตริงที่นี่" $ref ที่ส่วนท้ายของ URI จะถือเป็นตัวแปรว่าง

$uri = @'
https://graph.microsoft.com/beta/deviceManagement/managedDevices('956a2c3b-bd8d-4339-9f26-3d1b034748f6')/deviceCategory/$ref
'@

เราได้ทำสิ่งที่คล้ายกันข้างต้นด้วยเพย์โหลด JSON ของเรา:

$json = @'
{
"@odata.id":"https://graph.microsoft.com/beta/deviceManagement/deviceCategories/3725a237-e0e4-4b0b-aab0-3868e12c8ba9"
}
'@

สุดท้ายนี้ เราจะดำเนินการคำสั่งของเราและทำการเปลี่ยนแปลง:

Invoke-MgGraphRequest -Uri $uri -Body $json -Method PUT -ContentType "application/json"

วิธีการใช้วิธีต่างๆ รับ โพสต์ วาง แพทช์ ลบ

มี 5 วิธีในการดึงและส่งข้อมูลไปยัง Microsoft Graph ฉันจะแจกแจงความหมายของแต่ละวิธีด้านล่าง

วิธีการ GET

การใช้ GET จะดึงข้อมูลจากเซิร์ฟเวอร์เกี่ยวกับทรัพยากรเฉพาะหรือหลายรายการ ขึ้นอยู่กับ URI ที่คุณระบุ มีความเสี่ยงเล็กน้อยในการใช้วิธี GET เนื่องจากไม่มีการเปลี่ยนแปลงเกิดขึ้น ตัวอย่างเช่น หากเราต้องการดูนโยบายการเข้าถึงแบบมีเงื่อนไขทั้งหมดในผู้เช่าของเรา เราสามารถใช้สิ่งต่อไปนี้:

#Define the URI
$uri = "https://graph.microsoft.com/beta/policies/conditionalAccessPolicies"

#Create policy
$policies = Invoke-MgGraphRequest -Uri $uri -Method GET

#Expand values
$policies.Values.values

วิธีการ POST

คำขอ POST ถูกใช้เพื่อสร้างทรัพยากรใหม่ ตัวอย่างเช่น หากคุณต้องการสร้างนโยบายการปฏิบัติตามข้อบังคับใหม่ใน Microsoft Intune คุณสามารถใช้ตัวอย่างด้านล่าง:

$uri = "https://graph.microsoft.com/beta/deviceManagement/deviceCompliancePolicies"

$json = @'
{
"id":"00000000-0000-0000-0000-000000000000",
"displayName":"Temp1",
"roleScopeTagIds":["0"],
"@odata.type":"#microsoft.graph.windows10CompliancePolicy",
"scheduledActionsForRule":[
    {
    "ruleName":"PasswordRequired",
    "scheduledActionConfigurations":[
        {
        "actionType":"block",
        "gracePeriodHours":0,
        "notificationTemplateId":"",
        "notificationMessageCCList":[]
        }]
    }],
"deviceThreatProtectionRequiredSecurityLevel":"unavailable",
"passwordRequiredType":"deviceDefault",
"bitLockerEnabled":true,
"deviceThreatProtectionEnabled":false
}
'@

Invoke-MgGraphRequest -uri $uri -body $json -method POST -ContentType "application/json"

วิธีการ PUT

คำขอ PUT มีไว้สำหรับการอัปเดตทรัพยากร เช่น หากคุณต้องการเปลี่ยนคุณสมบัติบนอุปกรณ์ใน Intune คุณจะใช้คำขอ PUT เลื่อนขึ้นเพื่อดูตัวอย่างที่ฉันให้ไว้เมื่อสร้างสคริปต์ของเราโดยใช้ Invoke-MgGraphRequest

วิธีการ PATCH

วิธีการ PATCH นั้นคล้ายคลึงกับ PUT แต่จะใช้การอัพเดตเฉพาะกับทรัพยากรเท่านั้น ตัวอย่างเช่น หากเราต้องการอัปเดตนโยบายการปฏิบัติตามที่เราสร้างด้วยวิธี POST เราสามารถใช้สคริปต์ต่อไปนี้:

$uri = "https://graph.microsoft.com/beta/deviceManagement/deviceCompliancePolicies/f048f8f0-5370-4ea6-979b-5dabc4f5329c"

$json = @'
{
"id":"f048f8f0-5370-4ea6-979b-5dabc4f5329c",
"displayName":"Temp1",
"description":null,
"roleScopeTagIds":["0"],
"@odata.type":"#microsoft.graph.windows10CompliancePolicy",
"bitLockerEnabled":true,
"codeIntegrityEnabled":true,
"tpmRequired":false,"validOperatingSystemBuildRanges":[],
"[email ":"https://graph.microsoft.com/beta/$metadata#deviceManagement/deviceCompliancePolicies('f048f8f0-5370-4ea6-979b-5dabc4f5329c')/microsoft.graph.windows10CompliancePolicy/assignments",
"[email ":"https://graph.microsoft.com/beta/$metadata#deviceManagement/deviceCompliancePolicies('f048f8f0-5370-4ea6-979b-5dabc4f5329c')/microsoft.graph.windows10CompliancePolicy/scheduledActionsForRule(scheduledActionConfigurations())"
}
'@

Invoke-MgGraphRequest -uri $uri -body $json -method PATCH -ContentType "application/json"

วิธีการลบ

วิธีการ DELETE ดังที่คุณอาจเดาได้ ช่วยให้คุณสามารถลบทรัพยากรเฉพาะได้ ตัวอย่างเช่น เราสามารถใช้คำสั่งด้านล่างเพื่อลบนโยบายการปฏิบัติตามที่เราสร้างและแก้ไขด้านบน:

$uri = "https://graph.microsoft.com/beta/deviceManagement/deviceCompliancePolicies/a7be0c3d-dd89-49c7-a464-f371e72b30d7"

Invoke-MgGraphRequest -uri $uri -method DELETE