Box APIを使用したSlackチャンネルとBoxフォルダ間の統合マッピングの管理
Box Enterpriseユーザーは、Microsoft Teams、Salesforce、Zoom、Slackなど、1500以上の統合を利用できます。人気の高い統合の中にBox for Slackがあります。このアプリケーションには、共有ファイルに対する権限をすばやく選択および共有する機能、Slack内で直接Box通知を受信する機能、Slackでのすべての会話に単一の安全なコンテンツレイヤーを提供する機能など、便利な機能が用意されています。
SlackのコンテンツレイヤーとしてBoxが有効になっている場合は、チャンネルごとにBoxフォルダが作成され、そのフォルダにファイルがアップロードされます。チャンネルメンバーは、作成されたフォルダの編集可能なコラボレータになり、チャンネルではブックマークを使用して簡単にコンテンツにアクセスできるようになります。
Box統合マッピングAPIが必要な理由
企業内の各チームの作業方法は似ている傾向にあり、1つのSlackチャンネルに加えて、戦略 (セールストークや採用プロセスなど) ごとに1つのBoxフォルダまたは複数のフォルダを使用しています。これまで、企業内でSlackのコンテンツレイヤーとしてBoxを使用するBox for Slackユーザーは、デフォルトのチャンネルとフォルダ間のマッピングを使用する必要がありました。統合マッピングAPIを使用すると、Box管理者は、Box Enterprise内の任意のフォルダをアップロード先に指定することで、チーム固有のニーズに合わせてアップロードフォルダをカスタマイズできます。
目標と前提条件
この記事では、統合マッピングAPIを使用して、BoxフォルダとSlackチャンネルの間のカスタムマッピングを管理 (作成、更新、削除) する方法について説明します。
開始する前に、以下の前提条件がすべて満たされていることを確認してください。
- 使用するBox Enterpriseアカウントに管理者ロールまたは共同管理者ロールが割り当てられている。
- 関連するSlackワークスペースまたはオーガナイゼーションにBox for Slackがインストールされている (リンク)。
- SlackのコンテンツレイヤーとしてBoxが有効になっている (リンク)。
Slack側のチャンネル確認のために、統合マッピングAPIでSlack APIを呼び出すことに注意してください。
Box統合マッピングAPIで提供される機能
開発者向けドキュメントで説明されているように、このAPIには、マッピングを管理するための標準的なCRUDエンドポイントが用意されています。
GET— マッピングの取得およびフィルタ (管理者が手動で作成したマッピングと統合で自動的に作成されたマッピングの両方)。
curl --location --request GET 'https://api.box.com/2.0/integration_mappings/slack?partner_item_id=C987654321&box_item_id=123456789' \
--header 'Authorization: Bearer {{token}}' \POST — 新しいマッピングの作成。Boxフォルダを参照するbox_itemとSlackチャンネルを参照するpartner_itemを指定する必要があります。オプションを指定すると、作成されるマッピングのデフォルトの設定が上書きされます。例えば、is_access_management_disabledオプションを指定すると、管理者自身がアクセスを処理するという想定で、Boxフォルダでのコラボレーションの作成が無効になります。
curl --location --request POST 'https://api.box.com/2.0/integration_mappings/slack' \
--header 'Authorization: Bearer {{token}}' \
--header 'Content-Type: application/json' \
--data-raw '{
"partner_item": {
"id": "C987654321",
"type": "channel",
"slack_workspace_id": "T5555555"
},
"box_item": {
"id": "123456789",
"type": "folder"
}
}'PUT— マッピングまたはターゲットBoxフォルダのオプションの更新 (例: is_access_management_disabled)。
curl --location --request PUT 'https://api.box.com/2.0/integration_mappings/slack/512521' \
--header 'Authorization: Bearer {{token}}' \
--header 'Content-Type: application/json' \
--data-raw '{
"options": {
"is_access_management_disabled": true
}
}'DELETE— マッピングの削除。チャンネルのマッピングを削除すると、次のファイルがアップロードされたときに新しいデフォルトのチャンネルフォルダが作成されます。マッピングが削除されても、BoxフォルダとSlackチャンネルはどちらも削除されません。
curl --location --request DELETE 'https://api.box.com/2.0/integration_mappings/slack/512521' \
--header 'Authorization: Bearer {{token}}' \
--data-raw ''承認
統合マッピングAPIを呼び出せるように、管理者はBox開発者コンソールでカスタムアプリを作成する必要があります。このチュートリアルでは、認証方法として [ユーザー認証 (OAuth 2.0)] を使用しますが、[サーバー認証] を選択することもできます。
アプリケーションを作成したら、管理者は [構成] > [アプリケーションスコープ] セクションで、[Enterpriseのプロパティを管理する] チェックボックスをオンにし、変更を保存する必要があります。このAPIを呼び出すにはこのスコープが必要です。
次に、最も簡単な承認方法として、開発者トークンを生成し、各統合マッピングAPIリクエストのHTTPヘッダーに追加します: Authorization: Bearer {developer_token}
トークンの有効期間は60分で、その時間が経過したら再生成する必要があります。もちろん、管理者はアクセストークンを取得するためにOAuth 2.0フローを実行することもできます (Box開発者向けドキュメントを参照)。
マッピングの作成
PostmanとBox UI
このセクションでは、PostmanとBox UIを使用して、SlackチャンネルとBoxフォルダのマッピングを作成します。Postmanは、APIの開発およびテストツールです。詳細については、Postmanのドキュメントを参照してください。
BoxのフォルダとSlackのチャンネルがすでに存在し、そのチャンネルのアップロード先がそのフォルダになるようにすることを想定します。
マッピングを作成するために、POSTリクエストを送信します。APIリファレンスに示されているように、ペイロードでpartner_itemとbox_itemを指定する必要があります。
Slackアプリケーションは、単一のワークスペースにインストールすることも、組織全体でインストールすることもできます (ドキュメントを参照)。Box for Slackをワークスペースにインストールする場合、partner_itemの入力データは、SlackチャンネルのURL app.slack.com/client/{slack_workspace_id}/{channel_id}で簡単に確認できます。
また、channel_idを確認するには、チャンネル名をダブルクリックして、[View channel details (チャンネルの詳細を表示)] を選択し、表示されるモーダルの下部からコピーできます。
組織全体でインストールした場合も、channel_idは上記と同じ方法で確認できます。また、slack_org_idは、Slackオーガナイゼーションの管理ページのURL app.slack.com/manage/{slack_org_id}で確認できます (このスクリーンショットの場合)。
同様に、box_itemはBoxフォルダのURL app.box.com/folder/{folder_id}で確認できます。
さらに、作成されるマッピングのデフォルトの設定を上書きする場合は、optionsを指定できます。
リクエストを送信すると、ほとんどの場合、次のようなエラーレスポンスが表示されます。
SlackのコンテンツレイヤーとしてBoxを使用する場合は、チャンネルフォルダ内のコンテンツとコラボレータを管理するためにサービスアカウントを使用します。マッピングを作成する前に、このサービスアカウントは、マッピングされるフォルダで共同所有者ロールのコラボレーションを行う必要があります。コラボレーションを作成するには、context_infoのservice_account_email (AutomationUser_...) をコピーし、Box UI ([ユーザーを招待]) を使用する方法が最も簡単です。
リクエストを再送信すると、マッピングを作成できるようになります (そうならない場合は、「トラブルシューティング」セクションを参照してください)。Box APIから、201 Createdに加えて、統合マッピングオブジェクト全体が返されます。
管理者は、マッピングされたチャンネルのchannel_idと同じpartner_item_idを指定してGETリクエストを送信することで、マッピングが作成されたことを確認できます。
ここで、Slackへのアップロードを実行して、すべてが機能していることを確認しましょう。
BoxとSlack両方のスクリーンショットに表示されているように、Boxへのアップロードにはカスタムフォルダが使用されています。ブックマークはそのフォルダを指しており、コラボレータはSlackのチャンネルメンバーと同期されています。SlackチャンネルとBoxフォルダを正常に接続できました。
Box SDK
管理者は、プロセス全体を自動化するためにBox SDKを使用できます。まず、Boxアプリケーションの構成で [Boxに格納されているすべてのファイルとフォルダへの書き込み] チェックボックスをオンにして、コラボレーションを作成できるようにします。
変更を保存すると、管理者は次のスクリプトを使用して、フォルダとSlackチャンネル (Boxフォルダマッピング) にサービスアカウントの共同所有者のコラボレーションを自動的に作成できるようになります (サービスアカウント情報は「手動による」方法と同様にエラーメッセージから抽出されます)。
const BoxSDK = require('box-node-sdk');
const axios = require('axios');
const integrationMappingsApiUrl = 'https://api.box.com/2.0/integration_mappings/slack'
const boxFolderId = 'PASTE YOUR FOLDER ID HERE';
const slackChannelId = 'PASTE YOUR CHANNEL ID HERE';
const slackOrgId = 'PASTE YOUR SLACK ORG ID HERE (CHANGE TO WORKSPACE ID IF NECESSARY)';
const developerToken = 'PASTE YOUR DEVELOPER TOKEN HERE';
let serviceAccountId = '<PLACEHOLDER>';
const client = BoxSDK.getBasicClient(developerToken);
async function postIntegrationMappingSlack(){
return axios.post(integrationMappingsApiUrl, {
partner_item: {
id: slackChannelId,
slack_org_id: slackOrgId, // change slack_org_id to slack_workspace_id if Box for Slack is installed on the workspace level
type: "channel"
},
box_item: {
id: boxFolderId,
type: "folder"
}
}, {
headers: {
'Authorization': `Bearer ${developerToken}`
}
});
}
function isPlaceholder(str){
return str === '<PLACEHOLDER>';
}
async function addCoowner(serviceAccountId, folderId){
try {
await client.collaborations.createWithUserID(serviceAccountId, folderId, 'co-owner')
} catch (error){
if(error.response.body.code === 'user_already_collaborator'){
console.log('Service account already collaborated in the co-owner role.')
} else {
throw error;
}
}
}
async function logServiceAccountId() {
try {
await postIntegrationMappingSlack();
} catch (error) {
console.log(`Replace the value of serviceAccountId with: ${error.response.data.context_info.service_account_id} and re-run the script.`)
}
}
async function createSlackIntegrationMapping() {
if(isPlaceholder(serviceAccountId)){
await logServiceAccountId();
} else {
await addCoowner(serviceAccountId, boxFolderId);
await postIntegrationMappingSlack();
}
}
module.exports = { createSlackIntegrationMapping }Postmanの例と同じように、Box for Slackがワークスペースごとに導入されている場合は、slack_org_idをslack_workspace_idに置き換える必要があります。
このスクリプトを初めて実行すると、コンソールにはserviceAccountIdが表示されます。忘れずに<PLACEHOLDER>をこの値に置き換えてください。この値は企業ごとに一定になります。
トラブルシューティング
統合マッピングAPIは、マッピングの正確性を確保するためにさまざまな種類の検証を実行します。ここでは、これらの検証エラーについて説明し、考えられる解決策を示します。
サービスアカウントがフォルダの共同所有者ではない
コラボレーションおよびアップロードを管理するために、Box for Slackサービスアカウントをフォルダの共同所有者または所有者として追加する必要があります。
このエラーを解決するには、Box UIまたはBox SDKを使用して、フォルダの共同所有者または所有者としてサービスアカウントを追加します (エラーメッセージに表示されているIDまたはメールアドレスを使用できます)。
チャンネルがすでにBoxのフォルダにマッピングされている
Boxフォルダがすでにマッピングされているチャンネルに対してユーザーがマッピングを作成しようとすると、APIから次のエラーが返されます。
新しいフォルダの使用を開始することが目的の場合は、GETを使用してマッピングのIDを取得した後、UPDATEメソッドを使用してターゲットのBoxフォルダを更新してください。
チャンネルが見つからない
統合に関連付けられているSlackボットでチャンネルに関する情報を取得できない場合は、APIから次のエラーが返されます。
partner_itemが正しいことを確認します (組織でのインストールの場合はslack_org_id、ワークスペースでのインストールの場合はslack_workspace_idを指定していることを確認します)。チャンネルがプライベートの場合は、チャンネルにSlackボットが追加されていることを確認します。
チャンネルがカスタムファイルストレージ (CFS) に適していない
Slackコネクトチャンネル (企業間チャンネル) は、現在、SlackのコンテンツレイヤーとしてBoxを使用する場合にサポートされていません。
Boxフォルダが外部で所有されている
マッピングに選択したBoxフォルダは、管理者が所属する企業で所有している必要があります。
カスタムファイルストレージ (CFS) が無効になっている
Box for Slackがインストールされているものの、SlackのコンテンツレイヤーとしてBoxが有効になっていない企業に対してマッピングを作成しようとすると、APIからこのエラーが返されます。SlackのコンテンツレイヤーとしてBoxを有効にする方法の詳細については、こちらの記事を参照してください。
Box Enterpriseの不一致
管理者のEnterpriseとBox for Slackの構成が一致しない場合、APIからこのエラーが返されます。Box for Slackを有効にする方法については、こちらの記事を参照してください。
まとめ
管理者は、統合マッピングAPIを使用すると、自社のSlackチャンネルとBoxフォルダのマッピングを簡単に管理できます。これにより柔軟性が向上するため、チームは、Box for Slackによって作成されるデフォルトのフォルダ構造以外の構造も使用できるようになります。管理者はいつでもマッピングを変更して、チャンネルに合わせてBoxフォルダやアクセスの管理オプションを変更できます。マッピングを削除してファイルをアップロードするだけで、簡単にデフォルトの動作に戻すこともできます。
この記事をお読みいただきありがとうございました。お探しの回答がすべて見つかったのであれば幸いです。
フィードバックがある場合は、Box Pulseに英語で投稿してください。また、TwitterでBox Developersプロフィールをフォローすると、最新情報を入手できます。
