LINE WORKS API 2.0 を PowerShell で叩いてみる (その7:グループと組織のメンバーの管理) #LINEWORKS

前回から間が空いてしまいましたが、久しぶりに PowerShell で LINE WORKS API 2.0 を触ってみようと思います。
今回は、ユーザーをまとめる単位である、グループと組織について触ってみます。

作業の前に、TLS とか

作業に入る前に、ちょっと注意点を。
2022年1２月より、LINE WORKS API は TLS 1.0/1.1 によるアクセスができないようになりました。
TLS 1.2 が有効化されていない PowerShell 環境から LINE WORKS API にアクセスしよとすると、エラーとなります。PowerShell スクリプトの冒頭で以下を実行するなどして、TLS 1.2 を有効化してください。

[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12

グループと組織

LINE WORKS には、複数のユーザーをまとめて管理する方法として、グループや組織がありますが、この２つは、メンバーシップの管理方法が大きく異なります。

グループは、グループを作成し、グループに対してメンバー（ユーザー）を登録することで、メンバーシップを管理します。

一方、組織は、組織を作成後、ユーザーに対して、どの組織に所属するのかを指定することで、メンバーシップを管理します。
職級や利用権限タイプも、組織と同様に、ユーザーを起点に割り当てる管理方法が取られています。

グループの作成とユーザーの追加

それでは、グループを利用したメンバーの管理方法から確認していきましょう。
グループの操作には、directory または group scope が必要になります。
この後に実施する、組織やユーザーの操作でも利用できるよう、以前の記事を参考に、scope に directory を指定して Access Token を取得し、$Header を準備しておきます。

最初に、グループを作成（登録）します。グループ作成時には、少なくとも domainId、groupName、administrators、members を指定する必要があります。必要に応じて、ノートやカレンダーなどの機能の利用有無や、メールアドレス等も指定できます。
まずは、グループマスターをメンバーとしても登録し、グループを作成しましょう。

$GroupMaster = "admin@yourdomain"
$PostGroupURL = 'https://www.worksapis.com/v1.0/groups'

[HashTable]$NewGroup = @{
    domainId = １２３４５６７８
    groupName = "LINE WORKS API を使う会"
    administrators = @(
        @{
        userId = $GroupMaster 
        }
    )
    members = @(
        @{
            id = $GroupMaster 
            type = "USER"
        }
    )
}

$NewGroupBody = $NewGroup | ConvertTo-Json -depth 10
$NewGroupBody = [System.Text.Encoding]::UTF8.GetBytes($NewGroupBody)
$group = Invoke-RestMethod -Method POST -Uri $PostGroupURL -Headers $Header -body $NewGroupBody

次に、作成したグループに、メンバーを追加します。
メンバーの追加は、グループの部分更新で、members にメンバーを列挙することで可能です。
今回は、グループのメンバーとしてユーザーを追加しましたが、組織や他のグループを追加することも可能です。

$PatchGroupURL = 'https://www.worksapis.com/v1.0/groups/' + $group.groupId

[HashTable]$PatchGroup = @{
    members = @(
        @{
            id = "user01@yourdomain"
            type = "USER"
        }
        @{
            id = "user02@yourdomain"
            type = "USER"
        }
    )
}
# 人数が多い場合には、一人ずつ順番に追加したほうが、わかりやすいですね。
$PatchGroup.members += @{
    id = "user001@yourdomain"
    type = "USER"
}
$group = Invoke-RestMethod -Method PATCH -Uri $PatchGroupURL -Headers $Header -body (ConvertTo-Json  $PatchGroup -depth 10)

組織の作成とユーザーの追加

組織の操作には、directory または orgunit scope が、ユーザーの操作には directory または user scope が必要になります。先程のグループの操作で directory scope に対する Token を取得し $Headers を準備していますので、そのまま$Headersを使うことにして作業を進めましょう。

組織の場合にもグループと同様、まずは組織の作成(登録)からはじめます。
組織を作成する際の必須パラメータは、domainId、orgUnitName、displayOrder です。グループ同様、必要に応じて、ノートやカレンダーなどの機能の利用有無や、メールアドレス等を指定する他、組織階層を構成することも可能です。

$PostOrgunitURL = 'https://www.worksapis.com/v1.0/orgunits'
[HashTable]$NewOrgUnit = @{
    domainId = 12345678
    orgUnitName = "LINE WORKS 活用しよう課"
    displayOrder = 1
}
$NewOrgUnitBody = $NewOrgUnit | ConvertTo-Json -depth 10
$NewOrgUnitBody = [System.Text.Encoding]::UTF8.GetBytes($NewOrgUnitBody)
$OrgUnit = Invoke-RestMethod -Method POST -Uri $PostOrgunitURL -Headers $Header -body $NewOrgUnitBody

組織が作成できたら、ユーザーの所属組織を変更します。
ユーザーは必要に応じて複数の組織に所属することもできますので、その場合にはグループの例を参考に変更してみてください。

$userId = "user01@yourdomain"
$urlEncodedUserId =  [System.Web.HttpUtility]::UrlEncode($userId)
$patchUserURL = 'https://www.worksapis.com/v1.0/users/' + $urlEncodedUserId
[HashTable]$patchUser = @{
    organizations = @(
        @{
            domainId = $OrgUnit.domainId
            primary  = $true
            orgUnits = @(
                @{
                    orgUnitId = $OrgUnit.orgUnitId
                    primary   = $true
                }
            )
        }
    )
}
$user = Invoke-RestMethod -Method PATCH -Uri $patchUserURL -Headers $Header -body (ConvertTo-Json  $patchUser -depth 10)