Directory API: หน่วยขององค์กร

จัดการหน่วยขององค์กร

โครงสร้างองค์กรของบัญชี Google Workspace ประกอบด้วยหน่วยขององค์กรที่ช่วยให้คุณจัดการผู้ใช้ในแบบโครงสร้างตามลำดับชั้นและเชิงตรรกะ ฟังก์ชันนี้จะคล้ายกับฟังก์ชันที่พบใน "องค์กรและผู้ใช้" ของคอนโซลผู้ดูแลระบบ ลำดับชั้นหน่วยขององค์กรของลูกค้ามีความลึกได้สูงสุด 35 ระดับ โปรดดูข้อมูลเพิ่มเติมที่ศูนย์ช่วยเหลือสำหรับผู้ดูแลระบบ

  • บัญชี Google Workspace มีโครงสร้างขององค์กรเพียง 1 รายการเท่านั้น เมื่อมีการกำหนดค่าบัญชีนี้ในตอนแรก บัญชีจะมีหน่วยขององค์กรที่ระดับบัญชี นี่คือองค์กรที่เชื่อมโยงกับโดเมนหลัก สำหรับข้อมูลเพิ่มเติมเกี่ยวกับโดเมนหลัก โปรดดูที่ข้อมูลขีดจำกัดของ API
  • ชื่อเส้นทางของหน่วยขององค์กรไม่ซ้ำกัน ชื่อหน่วยขององค์กรอาจไม่เหมือนกันในลำดับชั้นขององค์กร แต่ชื่อหน่วยจะไม่ซ้ำกันในแต่ละหน่วยระดับเดียวกัน และระบบจะไม่คำนึงถึงตัวพิมพ์เล็กและตัวพิมพ์ใหญ่ในชื่อหน่วยขององค์กร
  • หน่วยขององค์กรจะรับนโยบายมาจากลำดับชั้นขององค์กร องค์กรใดก็ได้ หน่วยสามารถบล็อกเชนการสืบทอดค่าระดับบนนี้ด้วยการลบล้างนโยบายที่รับช่วงมา ลำดับความสำคัญของนโยบายหนึ่งมากกว่าอีกนโยบายหนึ่งจะกำหนดโดยหน่วยขององค์กรที่ใกล้ที่สุด ซึ่งหมายความว่านโยบายของหน่วยขององค์กรระดับล่างจะมีความสำคัญเหนือกว่านโยบายของหน่วยขององค์กร หน่วยหลักที่สูงขึ้น การตั้งค่า blockInheritance อนุญาตการรับการตั้งค่าการบล็อกเป็น หน่วยขององค์กรและองค์กรย่อย blockInheritance เลิกใช้งานแล้ว ระบบไม่รองรับการตั้งค่าเป็น "จริง" อีกต่อไปและอาจทำให้เกิดผลกระทบโดยไม่เจตนา สำหรับ ข้อมูลเพิ่มเติมเกี่ยวกับการสืบทอดค่าและผู้ใช้ในโครงสร้างองค์กร โปรดดู ศูนย์ช่วยเหลือการดูแลระบบ
  • คุณสามารถย้ายหน่วยขององค์กรขึ้นหรือลงในโครงสร้างแบบต้นไม้ และสามารถย้ายผู้ใช้ที่เชื่อมโยงขององค์กรเป็นรายบุคคลหรือเป็นกลุ่มเมื่อเพิ่มผู้ใช้ไปยังองค์กรใหม่หรือย้ายผู้ใช้บางส่วนจากหน่วยขององค์กรหนึ่งไปยังอีกหน่วยหนึ่งได้
  • ข้อมูลที่เก็บไว้ในพร็อพเพอร์ตี้หน่วยขององค์กรอาจเปลี่ยนแปลงได้ตลอดเวลา เมื่อส่งคำขอ พร็อพเพอร์ตี้ที่ส่งคืนสำหรับเอนทิตีหนึ่งๆ จะได้รับการรับประกันว่าจะสอดคล้องกัน ณ เวลาที่มีการดึงข้อมูลเอนทิตี กล่าวคือคุณจะไม่เห็น "บางส่วน" อัปเดต หากการดำเนินการดึงข้อมูลแสดงผลเอนทิตีมากกว่า 1 รายการ จะไม่มีการรับประกันความสอดคล้องในเอนทิตีต่างๆ โดยเฉพาะอย่างยิ่งเมื่อคำตอบครอบคลุมหลายหน้าในการใส่เลขหน้า

สร้างหน่วยขององค์กร

หากต้องการสร้างหน่วยขององค์กร ให้ใช้คำขอ POST ต่อไปนี้และรวมการให้สิทธิ์ที่อธิบายไว้ในส่วนให้สิทธิ์คำขอ

หากคุณเป็นผู้ดูแลระบบที่สร้างหน่วยขององค์กร ให้ใช้ my_customer

POST https://admin.googleapis.com/admin/directory/v1/customer/my_customer/orgunits

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

POST https://admin.googleapis.com/admin/directory/v1/customer/customerId/orgunits

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

คำขอ JSON

ตัวอย่างตัวแทนจำหน่าย JSON ต่อไปนี้แสดงเนื้อหาคำขอตัวอย่างที่สร้างหน่วยขององค์กร sales_support ต้องระบุ name และ parentOrgUnitPath: 

POST https://admin.googleapis.com/admin/directory/v1/customer/C03az79cb/orgunits

{
    "name": "sales_support",
    "description": "The sales support team",
    "parentOrgUnitPath": "/corp/support",
    "blockInheritance": false
}

การตอบสนองของ JSON

การตอบกลับที่สำเร็จจะแสดงรหัสสถานะ HTTP 201 นอกจากรหัสสถานะแล้ว การตอบกลับจะแสดงพร็อพเพอร์ตี้สำหรับกลุ่มใหม่: 

{
    "kind": "directory#orgUnit",
    "name": "sales_support",
    "description": "The sales support team",
    "orgUnitPath": "/corp/support/sales_support",
    "parentOrgUnitPath": "/corp/support",
    "blockInheritance": false
  }

อัปเดตหน่วยขององค์กร

หากต้องการอัปเดตหน่วยขององค์กร ให้ใช้คำขอ PUT ต่อไปนี้และรวมการให้สิทธิ์ที่อธิบายไว้ในคำขอให้สิทธิ์ สำหรับพร็อพเพอร์ตี้คำขอและการตอบกลับ โปรดดูเอกสารอ้างอิง API

หากคุณเป็นผู้ดูแลระบบที่อัปเดตหน่วยขององค์กร ให้ใช้ my_customer

 PUT https://admin.googleapis.com/admin/directory/v1/customer/my_customer/orgunits/orgUnitPath

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

PUT https://admin.googleapis.com/admin/directory/v1/customer/customerId/orgunits/orgUnitPath

คำขอ JSON

ในตัวอย่างด้านล่าง เราได้อัปเดตคำอธิบายหน่วยขององค์กรแล้ว 

PUT https://admin.googleapis.com/admin/directory/v1/customer/my_customer/orgunits/corp/support/sales_support

{
    "description": "The BEST sales support team"
}

หมายเหตุสำหรับคำขออัปเดต

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

การตอบสนองของ JSON

การตอบกลับที่สำเร็จจะแสดงรหัสสถานะ HTTP 201 นอกจากรหัสสถานะแล้ว การตอบกลับจะแสดงพร็อพเพอร์ตี้สำหรับหน่วยขององค์กรที่อัปเดต 

{
    "kind": "directory#orgUnit",
    "name": "sales_support",
    "description": "The BEST sales support team",
    "orgUnitPath": "/corp/support/sales_support",
    "parentOrgUnitPath": "/corp/support",
    "blockInheritance": false
}

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

ดึงข้อมูลหน่วยขององค์กร

หากต้องการเรียกข้อมูลหน่วยขององค์กร ให้ใช้คำขอ GET ต่อไปนี้และรวมการให้สิทธิ์ที่อธิบายไว้ในคำขอสิทธิ์ สตริงการค้นหา orgUnitPath คือเส้นทางแบบเต็มสำหรับหน่วยขององค์กรนี้ สำหรับพร็อพเพอร์ตี้คำขอและการตอบกลับ โปรดดูเอกสารอ้างอิง API

หากคุณเป็นผู้ดูแลระบบที่ดึงข้อมูลหน่วยขององค์กร ให้ใช้ my_customer

GET https://admin.googleapis.com/admin/directory/v1/customer/my_customer/orgunits/orgUnitPath

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

GET https://admin.googleapis.com/admin/directory/v1/customer/customerId/orgunits/orgUnitPath

การตอบสนองของ JSON

ในตัวอย่างด้านล่าง "การขายระดับแนวหน้า" เรียกข้อมูลหน่วยขององค์กรแล้ว อย่าลืมพิจารณา "frontline+sales" การเข้ารหัส HTTP ใน URI ของคำขอ: 

GET https://admin.googleapis.com/admin/directory/v1/customer/my_customer/orgunits/corp/sales/frontline+sales

การตอบกลับที่สำเร็จจะแสดงรหัสสถานะ HTTP 200 นอกจากรหัสสถานะแล้ว การตอบกลับจะแสดงการตั้งค่าของหน่วยขององค์กรดังนี้ 

{
    "kind": "directory#orgUnit",
    "name": "frontline sales",
    "description": "The frontline sales team",
    "orgUnitPath": "/corp/sales/frontline sales",
    "parentOrgUnitPath": "/corp/sales",
    "blockInheritance": false
}

เรียกข้อมูลหน่วยขององค์กร

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

หากคุณเป็นผู้ดูแลระบบบัญชีที่เรียกดูหน่วยขององค์กรย่อยทั้งหมด ให้ใช้ my_customer ตัวอย่างนี้ใช้การขึ้นบรรทัดใหม่เพื่อให้อ่านง่ายขึ้น 

GET https://admin.googleapis.com/admin/directory/v1/customer/my_customer
/orgunits?orgUnitPath=full org unit path&type=all or children or all_including_parent

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

GET https://admin.googleapis.com/admin/directory/v1/customer/customerId
/orgunits?orgUnitPath=full org unit path&type=all or children or all_including_parent

สตริงการค้นหา get จะแสดงผลหน่วยขององค์กรย่อย all หน่วยภายใต้ orgUnitPath, children ที่อยู่ติดกันของ orgUnitPath หรือหน่วยขององค์กรย่อยทั้งหมด และ orgUnitPath ที่ระบุสำหรับ all_including_parent โดยมีค่าเริ่มต้นเป็น type=children

การตอบสนองของ JSON

เช่น คำขอนี้จะแสดงผลหน่วยขององค์กรทั้งหมดโดยเริ่มจากหน่วยขององค์กร /corp วันที่

GET https://admin.googleapis.com/admin/directory/v1/customer/my_customer/orgunits?orgUnitPath=/corp&type=all

การตอบกลับที่สำเร็จจะแสดงรหัสสถานะ HTTP 200 นอกจากรหัสสถานะแล้ว การตอบกลับจะแสดงหน่วยขององค์กรของบัญชีดังนี้ 

{
"kind": "directory#orgUnits",
    "organizationUnits": [
     {
    "kind": "directory#orgUnit",
    "name": "sales",
    "description": "The corporate sales team",
    "orgUnitPath": "/corp/sales",
    "parentOrgUnitPath": "/corp",
    "blockInheritance": false
     },
     {
    "kind": "directory#orgUnit",
    "name": "frontline sales",
    "description": "The frontline sales team",
    "orgUnitPath": "/corp/sales/frontline sales",
    "parentOrgUnitPath": "/corp/sales",
    "blockInheritance": false
     },
     {
    "kind": "directory#orgUnit",
    "name": "support",
    "description": "The corporate support team",
    "orgUnitPath": "/corp/support",
    "parentOrgUnitPath": "/corp",
    "blockInheritance": false
     },
     {
    "kind": "directory#orgUnit",
    "name": "sales_support",
    "description": "The BEST support team",
    "orgUnitPath": "/corp/support/sales_support",
    "parentOrgUnitPath": "/corp/support",
    "blockInheritance": false
     }
  ]
  }

ลบหน่วยขององค์กร

หากต้องการลบหน่วยขององค์กร ให้ใช้คำขอ DELETE ต่อไปนี้และรวมการให้สิทธิ์ที่อธิบายไว้ในส่วนให้สิทธิ์คำขอ หากต้องการเรียกข้อมูล customerId ให้ใช้การดำเนินการเรียกข้อมูลผู้ใช้ สำหรับพร็อพเพอร์ตี้คำขอและการตอบกลับ โปรดดูเอกสารอ้างอิง API

หากคุณเป็นผู้ดูแลระบบบัญชีที่จะลบหน่วยขององค์กร โปรดใช้ my_customer 

DELETE https://admin.googleapis.com/admin/directory/v1/customer/my_customer/orgunits/orgUnitPath

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

DELETE https://admin.googleapis.com/admin/directory/v1/customer/customerId/orgunits/orgUnitPath
ตัวอย่างเช่น คำขอ DELETE ของผู้ดูแลระบบของตัวแทนจำหน่ายนี้จะลบ "backend_tests" หน่วยขององค์กร: 
DELETE https://admin.googleapis.com/admin/directory/v1/customer/C03az79cb/orgunits/corp/sales/backend_tests

การตอบกลับที่สำเร็จจะแสดงรหัสสถานะ HTTP 200

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