プログラミング知識0が挑むLINE WORKS API2.0 part3（組織作成編）

今回のテーマ

前回の計画に基づいて、今回は組織を作成します。

構想では以下のような組織構成を作成予定です！

部	課
営業部	1課 2課
開発部	A課 B課
総務部	-
情報システム部	-

組織の登録 APIについて

まず、LINE WORKSドキュメントの組織の登録APIを参照してみました。

最低限の情報

ドキュメントのRequest Bodyの内容を見ていきます。
前回と同様にまず最小限の情報で登録してみようと思うので、requiredと記載されているパラメータはどれかなっと。

• domainId
• orgUnitName

この二つだけのようです。シンプルですね！

OrgUnitI18nNameという箇所の「language」や「name」、
OrgUnitAllowedMemberという箇所にも「userId」にもrequiredが記載されていますが、
これはそれぞれを使用する場合のみ、必須となると思っていただければOKです！

とりあえず組織を作ってみる

最初に「営業部」という組織を作成してみましょう！

• メソッドはPOST
• Bodyはraw(JSON)を設定
• 記載の内容はrequiredとされていた2項目のみ！

domainIdの部分は、前回の最後にEnvironmentsにDOMAIN_IDという項目を作成して設定しました。なので、書き方は {{DOMAIN_ID}} と記載してください！

Environmentsは環境変数というものらしく、ここに記載されたものは設定した変数名で記述すればOKということのようです。
賢さが1上がりました。

結果ですが、あ..あれ？

400 Bad Requestとして登録に失敗しました。
英語苦手なんだよなぁと思いつつ、descriptionを読んでみると、「displayOrderは必須です。」ということみたいですね。

組織を登録する場合のみ必須

displayOrderのパラメータの説明に書いてありました。。。orz

では気を取り直して、displayOrderを追加して再度実行してみましょう。

201 Createdということで組織が作成されました。

実行結果

{
    "domainId": xxxxxxx,
    "orgUnitExternalKey": null,
    "orgUnitName": "営業部",
    "i18nNames": [],
    "email": "[e-mail]",
    "description": null,
    "visible": true,
    "parentOrgUnitId": null,
    "displayOrder": 1,
    "aliasEmails": [],
    "canReceiveExternalMail": false,
    "useMessage": false,
    "useNote": false,
    "useCalendar": false,
    "useTask": false,
    "useFolder": false,
    "useServiceNotification": false,
    "membersAllowedToUseOrgUnitEmailAsRecipient": [],
    "membersAllowedToUseOrgUnitEmailAsSender": [],
    "orgUnitId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
    "parentExternalKey": null,
    "displayLevel": 1
}

これで、一応「営業部」という組織が出来上がりました。
ブラウザの管理画面でも「営業部」が表示されています。

実行結果（Response）をよく見てみる

組織名しか付与していないのでその通りで作成されるのはそりゃそうですね。
では、指定していないパラメータがどのようにResponseされているのか、という点も踏まえて、改めてResponseの内容とドキュメントを見ようと思います。

書いてみて思ったんですが、長かったので折り畳みにしておきます。

responseの各項目

"orgUnitExternalKey": null,
"orgUnitId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",

orgUnitExternalKeyとorgUnitIdはどちらも組織を識別するための情報です。

• ExternalKeyは自分が指定して設定する識別情報
• orgUnitIdはシステムが払い出す識別情報

みたいな感じで理解しました！

今回は自分で識別情報を設定するつもりは無いので、orgUnitExternalKeyはnullでOKです。
今後、組織を指定して何らかの作業をする場合はorgUnitIdを使用します。

"i18nNames": [],
"description": null,

i18nNamesは多国語設定する場合に使用するパラメータになりますが、今回は省略します。
descriptionは部署の説明を入力するところですが、ここも一旦省略します。

"visible": true

visibleは組織を公開にするか、非公開にするかを設定するパラメータです。
これは何も指定しないと、「true(公開する）」ということになります。

"parentOrgUnitId": null,

階層化された組織構造で、下位組織として作成する場合、parentOrgUnitIdに親組織のorgUnitIdを指定して組織を作成することになります。

今回の「営業部」は階層化された組織構造の上位組織になるので、ここはnullですが、 下位組織となる「1課」「2課」を作成するときは、営業部のorgUnitIdを指定して組織を作らないといけない！ ということになりますね。

"email": "[e-mail]"
"aliasEmails": [],
"canReceiveExternalMail": false,
"membersAllowedToUseOrgUnitEmailAsRecipient": [],
"membersAllowedToUseOrgUnitEmailAsSender": [],

• emailは部署のメンバーが含まれるメーリングリストになります
• canReceiveExternalMailは、外部のドメインからのメールを受信するかどうか、(デフォルトはfalse（受信しない）ですね)
• membersAllowedToUseOrgUnitEmailAsRecipientはメーリングリスト宛のメールを受信するのは誰か
• membersAllowedToUseOrgUnitEmailAsSenderはメーリングリストのアドレスを送信元アドレスとして使用するのは誰か

を設定する箇所ですが、一旦は何も設定せず、省略します。

"useMessage": false,
"useNote": false,
"useCalendar": false,
"useTask": false,
"useFolder": false,

• useMessageはチームトークルーム
• useNoteはチーム/グループノート
• useCalendarはチーム/グループ予定
• useTaskはチーム/グループタスク
• useFolderはチーム/グループフォルダ

うーん。。。ここが全部false（使用しない）は使い勝手が悪そうですね。
このままでは組織に参加したは良いけど、組織メンバー全員で話し合いたいことがあっても別トークルームをつくらなきゃいけなかったり、作成した資料を共有することもできない。。。。

ここは後で修正しましょう。

"parentExternalKey": null,

これはRequest Bodyに無いパラメータですね。
上位組織にorgUnitExternalKeyが設定されていた場合はResponseされるんだと思いますが、orgUnitExternalKeyは使用しない予定なので割愛。

"displayLevel": 1

これは管理者画面の表示順を表すようです。

作成した組織を修正する

さて、では先ほど作成した営業部でトークルームなどが使えるように修正します。

修正には二つのAPIが使用できるみたいですね。。。

組織の更新
組織の部分更新

うーん。。。名前が似てて、何が違うのか分かりません。

PUTとPATCH

組織の更新はメソッドがPUTでした。
組織の部分更新はPATCHでした。

PUT と PATCHって？
これはWebで検索すると沢山情報がありますね~

ざっくりとして理解としては、 「PUT=置換」「PATCH=部分的な変更」 と理解しました！
（間違ってたらすみません。。。）

今回は「営業部」自体を別の物に置き換えたいということではなく、チーム/グループトークルームなどの機能を使えるように修正したいだけなので、PATCH(組織の部分更新API)で修正することにします！

組織の部分更新APIを見てみる

組織の部分更新APIのドキュメントのRequest Bodyを見てみます。

なるほど。部分更新だから自分が修正したい情報だけ送れば良いんだから、 requiredの項目は無いんですね！

では組織の部分修正を実行です！
{orgUnitId}には修正対象の組織のorgUnitIdを入力します。

200 OKとResponseされ、正常に完了しました！

実行結果

{
    "domainId": xxxxxxx,
    "orgUnitExternalKey": null,
    "orgUnitName": "営業部",
    "i18nNames": [],
    "email": "[e-mail]",
    "description": null,
    "visible": true,
    "parentOrgUnitId": null,
    "displayOrder": 1,
    "aliasEmails": [],
    "canReceiveExternalMail": false,
    "useMessage": true,
    "useNote": true,
    "useCalendar": true,
    "useTask": false,
    "useFolder": true,
    "useServiceNotification": false,
    "membersAllowedToUseOrgUnitEmailAsRecipient": [],
    "membersAllowedToUseOrgUnitEmailAsSender": [],
    "orgUnitId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
    "parentExternalKey": null,
    "displayLevel": 1
}

あ、、、、やらかした。。。。。

"useTask": false

タスク機能も使えるようにしたかったんですが、Bodyに入れていませんでした｡･ﾟ･(ﾉД`)･ﾟ･｡
もう一回タスク機能も使用できるように部分修正を実行！

200 OKでResponseされましたね~一応結果見てみますか~

実行結果

{
    "domainId": xxxxxxx,
    "orgUnitExternalKey": null,
    "orgUnitName": "営業部",
    "i18nNames": [],
    "email": "[e-mail]",
    "description": null,
    "visible": true,
    "parentOrgUnitId": null,
    "displayOrder": 1,
    "aliasEmails": [],
    "canReceiveExternalMail": false,
    "useMessage": true,
    "useNote": true,
    "useCalendar": true,
    "useTask": false,
    "useFolder": true,
    "useServiceNotification": false,
    "membersAllowedToUseOrgUnitEmailAsRecipient": [],
    "membersAllowedToUseOrgUnitEmailAsSender": [],
    "orgUnitId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
    "parentExternalKey": null,
    "displayLevel": 1
}

"useTask": false

......は？（#＾ω＾）

あ、あれ？なんでなんで？タスクがtrueにならないじゃないですか！？
なにが200 OKなんだよ！何にもOKじゃないよ！？(°ㅂ°ꐦ)

。。。。。パラメータの名称が間違っとる....orz
大文字か小文字かの違いだけじゃねぇか。。。

誤：usertask
正：userTask

多分この違いを「だけ」って思うのは、私のプログラミング知識0が故なんでしょうね。
存在しないパラメータは「存在しないですよ」とResponseしてくれるのではなく、無視されて他の処理で問題無ければOKとなるということですね。

ではパラメータを修正して再度実行！！

実行結果

{
    "domainId": xxxxxxx,
    "orgUnitExternalKey": null,
    "orgUnitName": "営業部",
    "i18nNames": [],
    "email": "[e-mail]",
    "description": null,
    "visible": true,
    "parentOrgUnitId": null,
    "displayOrder": 1,
    "aliasEmails": [],
    "canReceiveExternalMail": false,
    "useMessage": true,
    "useNote": true,
    "useCalendar": true,
    "useTask": true,
    "useFolder": true,
    "useServiceNotification": false,
    "membersAllowedToUseOrgUnitEmailAsRecipient": [],
    "membersAllowedToUseOrgUnitEmailAsSender": [],
    "orgUnitId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
    "parentExternalKey": null,
    "displayLevel": 1
}

今度はちゃんとtrueになりました！

よし、これで記念すべき最初の組織作成が完了しました。

下位組織を作ろう

営業部の下位組織として「1課」「2課」を作成します。
それぞれの課は営業部と同じく、トークなどの機能は使えることにして作成します。

parentOrgUnitIdに営業部のorgUnitIdを入力するのを忘れません！

よし！今回はスムーズに組織が作成できました。(´∀｀*)

実行結果

{
    "domainId": xxxxxxx,
    "orgUnitExternalKey": null,
    "orgUnitName": "1課",
    "i18nNames": [],
    "email": "[e-mail]",
    "description": null,
    "visible": true,
    "parentOrgUnitId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
    "displayOrder": 1,
    "aliasEmails": [],
    "canReceiveExternalMail": false,
    "useMessage": true,
    "useNote": true,
    "useCalendar": true,
    "useTask": true,
    "useFolder": true,
    "useServiceNotification": false,
    "membersAllowedToUseOrgUnitEmailAsRecipient": [],
    "membersAllowedToUseOrgUnitEmailAsSender": [],
    "orgUnitId": "ffffffff-gggg-hhhh-iiii-jjjjjjjjjjjj",
    "parentExternalKey": null,
    "displayLevel": 1
}

一旦現在の状態を確認してみる

組織の状態を確認する。これにも二つのAPIがありました。

組織リストの取得
組織の取得

「組織リストの取得」は全組織の情報を取得する事ができて、「組織の取得」は指定した組織の情報が取得できると言う事ですね！
それぞれのResponse Exampleを見ましたが、取得できる情報は同じでした。

組織リストを取得してみる

組織リストの取得はチョー簡単！！！

メソッドはGETで、URLを入力するだけです。
Bodyに何かを記述する必要は無いので、私でも間違えることがありません！

200 OKでResponseされました。
ちゃんと「1課」のparentOrgUnitIdに「営業部」のorgUnitIdが表示されています。

実行結果

{
    "responseMetaData": {
        "nextCursor": null
    },
    "orgUnits": [
        {
            "domainId": xxxxxxx,
            "orgUnitExternalKey": null,
            "orgUnitName": "営業部",
            "i18nNames": [],
            "email": "[e-mail]",
            "description": null,
            "visible": true,
            "parentOrgUnitId": null,
            "displayOrder": 1,
            "aliasEmails": [],
            "canReceiveExternalMail": false,
            "useMessage": true,
            "useNote": true,
            "useCalendar": true,
            "useTask": true,
            "useFolder": true,
            "useServiceNotification": false,
            "membersAllowedToUseOrgUnitEmailAsRecipient": [],
            "membersAllowedToUseOrgUnitEmailAsSender": [],
            "orgUnitId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
            "parentExternalKey": null,
            "displayLevel": 1
        },
        {
            "domainId": xxxxxxx,
            "orgUnitExternalKey": null,
            "orgUnitName": "1課",
            "i18nNames": [],
            "email": "[e-mail]",
            "description": null,
            "visible": true,
            "parentOrgUnitId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
            "displayOrder": 1,
            "aliasEmails": [],
            "canReceiveExternalMail": false,
            "useMessage": true,
            "useNote": true,
            "useCalendar": true,
            "useTask": true,
            "useFolder": true,
            "useServiceNotification": false,
            "membersAllowedToUseOrgUnitEmailAsRecipient": [],
            "membersAllowedToUseOrgUnitEmailAsSender": [],
            "orgUnitId": "ffffffff-gggg-hhhh-iiii-jjjjjjjjjjjj",
            "parentExternalKey": null,
            "displayLevel": 2
        }
    ]
}

ブラウザの管理画面ではこんな感じです。

よしよし。ではこのまま他の組織も作っちゃいます！

出来上がったものがこちらです

3分クッキングのごとく省略しますが、全組織を作りました！

実行結果

{
    "responseMetaData": {
        "nextCursor": null
    },
    "orgUnits": [
        {
            "domainId": xxxxxxx,
            "orgUnitExternalKey": null,
            "orgUnitName": "情報システム部",
            "i18nNames": [],
            "email": "[e-mail]",
            "description": null,
            "visible": true,
            "parentOrgUnitId": null,
            "displayOrder": 1,
            "aliasEmails": [],
            "canReceiveExternalMail": false,
            "useMessage": true,
            "useNote": true,
            "useCalendar": true,
            "useTask": true,
            "useFolder": true,
            "useServiceNotification": false,
            "membersAllowedToUseOrgUnitEmailAsRecipient": [],
            "membersAllowedToUseOrgUnitEmailAsSender": [],
            "orgUnitId": "eeeeeeee-ffff-gggg-hhhh-iiiiiiiiiiii",
            "parentExternalKey": null,
            "displayLevel": 1
        },
        {
            "domainId": xxxxxxx,
            "orgUnitExternalKey": null,
            "orgUnitName": "総務部",
            "i18nNames": [],
            "email": "[e-mail]",
            "description": null,
            "visible": true,
            "parentOrgUnitId": null,
            "displayOrder": 2,
            "aliasEmails": [],
            "canReceiveExternalMail": false,
            "useMessage": true,
            "useNote": true,
            "useCalendar": true,
            "useTask": true,
            "useFolder": true,
            "useServiceNotification": false,
            "membersAllowedToUseOrgUnitEmailAsRecipient": [],
            "membersAllowedToUseOrgUnitEmailAsSender": [],
            "orgUnitId": "jjjjjjjj-kkkk-llll-mmmm-nnnnnnnnnnnn",
            "parentExternalKey": null,
            "displayLevel": 1
        },
        {
            "domainId": xxxxxxx,
            "orgUnitExternalKey": null,
            "orgUnitName": "営業部",
            "i18nNames": [],
            "email": "[e-mail]",
            "description": null,
            "visible": true,
            "parentOrgUnitId": null,
            "displayOrder": 3,
            "aliasEmails": [],
            "canReceiveExternalMail": false,
            "useMessage": true,
            "useNote": true,
            "useCalendar": true,
            "useTask": true,
            "useFolder": true,
            "useServiceNotification": false,
            "membersAllowedToUseOrgUnitEmailAsRecipient": [],
            "membersAllowedToUseOrgUnitEmailAsSender": [],
            "orgUnitId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
            "parentExternalKey": null,
            "displayLevel": 1
        },
        {
            "domainId": xxxxxxx,
            "orgUnitExternalKey": null,
            "orgUnitName": "1課",
            "i18nNames": [],
            "email": "[e-mail]",
            "description": null,
            "visible": true,
            "parentOrgUnitId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
            "displayOrder": 1,
            "aliasEmails": [],
            "canReceiveExternalMail": false,
            "useMessage": true,
            "useNote": true,
            "useCalendar": true,
            "useTask": true,
            "useFolder": true,
            "useServiceNotification": false,
            "membersAllowedToUseOrgUnitEmailAsRecipient": [],
            "membersAllowedToUseOrgUnitEmailAsSender": [],
            "orgUnitId": "ffffffff-gggg-hhhh-iiii-jjjjjjjjjjjj",
            "parentExternalKey": null,
            "displayLevel": 2
        },
        {
            "domainId": xxxxxxx,
            "orgUnitExternalKey": null,
            "orgUnitName": "2課",
            "i18nNames": [],
            "email": "[e-mail]",
            "description": null,
            "visible": true,
            "parentOrgUnitId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
            "displayOrder": 2,
            "aliasEmails": [],
            "canReceiveExternalMail": false,
            "useMessage": true,
            "useNote": true,
            "useCalendar": true,
            "useTask": true,
            "useFolder": true,
            "useServiceNotification": false,
            "membersAllowedToUseOrgUnitEmailAsRecipient": [],
            "membersAllowedToUseOrgUnitEmailAsSender": [],
            "orgUnitId": "kkkkkkkk-llll-mmmm-nnnn-oooooooooooo",
            "parentExternalKey": null,
            "displayLevel": 2
        },
        {
            "domainId": xxxxxxx,
            "orgUnitExternalKey": null,
            "orgUnitName": "開発部",
            "i18nNames": [],
            "email": "[e-mail]",
            "description": null,
            "visible": true,
            "parentOrgUnitId": null,
            "displayOrder": 4,
            "aliasEmails": [],
            "canReceiveExternalMail": false,
            "useMessage": true,
            "useNote": true,
            "useCalendar": true,
            "useTask": true,
            "useFolder": true,
            "useServiceNotification": false,
            "membersAllowedToUseOrgUnitEmailAsRecipient": [],
            "membersAllowedToUseOrgUnitEmailAsSender": [],
            "orgUnitId": "pppppppp-qqqq-rrrr-ssss-tttttttttttt",
            "parentExternalKey": null,
            "displayLevel": 1
        },
        {
            "domainId": xxxxxxx,
            "orgUnitExternalKey": null,
            "orgUnitName": "A課",
            "i18nNames": [],
            "email": "[e-mail]",
            "description": null,
            "visible": true,
            "parentOrgUnitId": "pppppppp-qqqq-rrrr-ssss-tttttttttttt",
            "displayOrder": 1,
            "aliasEmails": [],
            "canReceiveExternalMail": false,
            "useMessage": true,
            "useNote": true,
            "useCalendar": true,
            "useTask": true,
            "useFolder": true,
            "useServiceNotification": false,
            "membersAllowedToUseOrgUnitEmailAsRecipient": [],
            "membersAllowedToUseOrgUnitEmailAsSender": [],
            "orgUnitId": "uuuuuuuu-vvvv-wwww-xxxx-yyyyyyyyyyyy",
            "parentExternalKey": null,
            "displayLevel": 2
        },
        {
            "domainId": xxxxxxx,
            "orgUnitExternalKey": null,
            "orgUnitName": "B課",
            "i18nNames": [],
            "email": "[e-mail]",
            "description": null,
            "visible": true,
            "parentOrgUnitId": "pppppppp-qqqq-rrrr-ssss-tttttttttttt",
            "displayOrder": 2,
            "aliasEmails": [],
            "canReceiveExternalMail": false,
            "useMessage": true,
            "useNote": true,
            "useCalendar": true,
            "useTask": true,
            "useFolder": true,
            "useServiceNotification": false,
            "membersAllowedToUseOrgUnitEmailAsRecipient": [],
            "membersAllowedToUseOrgUnitEmailAsSender": [],
            "orgUnitId": "zzzzzzzz-aaaa-bbbb-cccc-dddddddddddd",
            "parentExternalKey": null,
            "displayLevel": 2
        }
    ]
}

管理画面上ではこのように表示されています。

まとめ

• パラメータ名の入力誤りには要注意（大文字・小文字も間違えないこと！）
• LINE WORKSドキュメントの以下を参照しました。
  組織リストの取得
  組織の登録
  組織の取得
  組織の更新
  組織の部分更新