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

前回から間が空いてしまいましたが、久しぶりに 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 を有効化してください。
```powershell
[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12  
```

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

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

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


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

最初に、[グループを作成（登録）](https://developers.worksmobile.com/jp/reference/group-create?lang=ja)します。グループ作成時には、少なくとも `domainId`、`groupName`、`administrators`、`members` を指定する必要があります。必要に応じて、ノートやカレンダーなどの機能の利用有無や、メールアドレス等も指定できます。
まずは、グループマスターをメンバーとしても登録し、グループを作成しましょう。

```powershell
$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
```


次に、作成したグループに、メンバーを追加します。
メンバーの追加は、[グループの部分更新](https://developers.worksmobile.com/jp/reference/group-update-patch?lang=ja)で、`members` にメンバーを列挙することで可能です。
今回は、グループのメンバーとしてユーザーを追加しましたが、組織や他のグループを追加することも可能です。
```powershell
$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`を使うことにして作業を進めましょう。

組織の場合にもグループと同様、まずは[組織の作成(登録)](https://developers.worksmobile.com/jp/reference/orgunit-create?lang=ja)からはじめます。
組織を作成する際の必須パラメータは、`domainId`、`orgUnitName`、`displayOrder` です。グループ同様、必要に応じて、ノートやカレンダーなどの機能の利用有無や、メールアドレス等を指定する他、組織階層を構成することも可能です。

```powershell
$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 
```

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