# Box Developer Documentation > Complete documentation for Box Platform APIs, SDKs, and developer tools. This file contains the full concatenated content of all individual markdown files for comprehensive LLM consumption. --- ## Box Platform ### Box Platformについて **Type:** page | **Category:** Box Platformについて | **Section:** Box Platform Box Platformについて Boxを初めて使用する場合は、ここから始めてください。以降のページでは、アプリケーションをより短時間で作成できるようにBox Platform… # Box Platformについて Boxを初めて使用する場合は、**ここから始めてください**。以降のページでは、アプリケーションをより短時間で作成できるようにBox Platformのすべての概念とコンポーネントがどのように連携しているかを学べます。 ## 詳細セクション 以下のページでは、各トピックについてさらに詳しく説明します。1つ1つ確認して、Box Platformのエキスパートを目指しましょう。 - [Box Platformの基礎](page://platform/box-platform-101) - [ユースケース](page://platform/use-cases) - [ユーザータイプ](page://platform/user-types) - [アプリケーションの種類](page://platform/application-types) - [認証方法](page://platform/authentication-methods) - [サポート](page://platform/support) - [ツール](page://platform/tools) 開始する **Source:** [https://ja.developer.box.com/platform/](https://ja.developer.box.com/platform/) --- ### Box Platformの基礎 **Type:** page | **Category:** Box Platformについて | **Section:** Box Platform Box Platformの基礎 Boxとは Box… # Box Platformの基礎 ## Boxとは [Box](https://www.box.com)とは、個人や企業がどこからでもドキュメントやファイルの保存、アクセス、コラボレーションを実行できるようにする、クラウドベースのコンテンツ管理およびファイル共有のプラットフォームです。安全なファイルストレージ、リアルタイムのコラボレーション、各種生産性ツールとの統合といった機能を提供し、チームの効率性やデータのアクセス性を向上させます。セキュリティと使い勝手の良いインターフェースに重点を置いていることで知られるBoxは、デジタル資産の管理や組織内のコラボレーションの促進に広く利用されています。 ## Box Platformとは [Box Platform](https://www.box.com/platform)は、Boxが提供する一連のツールとAPIです。開発者はこれを使用して、Boxのクラウドコンテンツ管理システムの機能を独自のアプリケーションやサービスに統合し、カスタマイズすることができます。企業や開発者は、データとアクセス権限の制御を維持しながらファイルストレージ、共有、コラボレーションなどの機能を利用して、安全かつ拡張性の高いコンテンツ中心のアプリケーションを構築できます。Box Platformを使用することで、開発者は、生産性の向上とコンテンツ管理ワークフローの効率化を実現する独自のソリューションを作成できます。 ## アプリケーションの作成方法 [Box API](page://reference)を使用するには、まずBoxでアプリケーションを作成する必要があります。このアプリケーションは、プラットフォームに対して実行されるAPIコールのゲートウェイとして機能します。このタスクを実行するには、Box DeveloperドキュメントポータルとBox開発者コンソールという2つのウェブサイトを使用できます。これらについて、もう少し詳しく見てみましょう。 ### Box Developerドキュメントポータル Box Developerドキュメントポータルとは、現在ご覧になっているこのウェブサイトです。これは、Box上にソリューションを作成する開発者向けの総合的なリソースで、アプリケーションを作成したりAPIコールを実行したりする際に開発者コンソールと一緒に使用する必要があります。多くのガイド、OpenAPIの詳細な仕様、クイックスタート、サンプルコードなどがこのページ内に掲載されています。 このサイトは頻繁に更新され、最新の更新情報は[変更ログ](page://changelog)に掲載されています。 ### Box開発者コンソール [Box開発者コンソール](https://app.box.com/developers/console)は、開発者がBoxと統合された独自のアプリケーションを管理するためのツールやリソースが用意されているインタラクティブなインターフェースです。ここでは、アプリの作成、構成、監視が可能となり、これらのアプリとBox Platformの関係についてインサイトと制御が示されます。 コンソールで初めてアプリケーションを作成すると、メインのBoxウェブアプリの左下にボタンが表示されるようになります。これ以降は、このボタンを使ってコンソールにアクセスできます。 ## Box Platformの概念 以降の詳細セクションでは、さまざまなトピックについてさらに詳しく説明します。ただし、いくつかの用語と概念を大まかに知っておく必要があります。 ### ユーザータイプ Box Platformで開発を行う際に注意すべき[ユーザータイプ](https://support.box.com/hc/ja/articles/4636533822483-Box-User-Types)がいくつかあります。ユーザータイプには、管理者権限を持つユーザー (管理者ユーザーや共同管理者ユーザーなど) と管理者権限を持たないユーザー (管理対象ユーザーまたは外部ユーザー) があります。さらに、サービスアカウントとApp Userに分類される、Platform専用のユーザーもあります。各ユーザータイプには、Box環境内での特定のロールとアクセスレベルが割り当てられており、アプリケーションやコンテンツの操作方法に影響します。基本的には、メインのBoxウェブアプリからコンテンツにアクセスできるユーザーは、APIを使用してコンテンツにアクセスすることもできます。 ### アプリケーションの種類 開発者コンソールで作成できるアプリケーションには、主に、Platformアプリ、アクセス制限付きアプリ、Box Custom Skillの3種類があります。また、サードパーティの統合やウェブアプリ統合も作成できます。 ### 認証方法 選択したアプリケーションの種類に応じて、[アクセストークン](g://authentication/tokens)を取得するために使用できる5種類の認証方法のいずれかを使用できます。アクセストークンは、アプリケーションであるゲートウェイを通過してBoxに対するAPIコールを成功させるための鍵となります。 次の手順 **Source:** [https://ja.developer.box.com/platform/box-platform-101/](https://ja.developer.box.com/platform/box-platform-101/) --- ### Box Platformの用語集 **Type:** page | **Category:** Box Platformについて | **Section:** Box Platform Box Platformの用語集 この用語集には、Box Platformで使用される用語と定義がまとめられています。用語の意味を調べる必要がある場合は、このページをご利用ください。 Box… # Box Platformの用語集 この用語集には、Box Platformで使用される用語と定義がまとめられています。用語の意味を調べる必要がある場合は、このページをご利用ください。 | Boxリソースの種類/用語 | 別名 | 説明 | | --- | --- | --- | | 管理者 | スーパーユーザー、スーパーバイザー | Enterpriseアカウントのメイン管理者。管理者は、ユーザーとグループの管理、組織のすべてのファイルとフォルダの表示と編集、組織内のさまざまなユーザーのアカウントへのログイン、組織の設定の編集、レポートの実行とアクセスが可能です。Box管理者は主要アカウント管理者です。 | | 管理コンソール | | 特定の企業を管理するためのダッシュボード領域。管理者、グループ管理者、共同管理者がアクセスできます。 | | 匿名ユーザー | | ログインしていないユーザー。 | | App User | | Box App Userは、Boxと統合されるアプリケーションまたはサービスに関連付けられている、Box Platform内の特定の種類のユーザーです。App Userは、API経由でしかアクセスできません (つまり、ログイン資格情報を持っていません)。これは、サービスアカウントによって作成できるため、サーバー間認証を利用するアプリケーションのみに適用できます。App Userは、その作成に使用されたアプリケーションに関連付けられているため、そのユーザー自体を別のアプリケーションに移動することはできません。ただし、そのアプリケーション外でのコンテンツのコラボレーションは可能です。 | | ブックマーク/ウェブリンク | シンボリックリンク、シムリンク、ソフトリンク、参照、関係 | コンテンツの構造内で外部ウェブサイトや特定の場所に簡単にアクセスできるようにする、クリック可能な参照。 | | Box統合 | アプリストア | Boxユーザーが、Boxと組み合わせて使用できるアプリケーションについて最初に調べる場所。 | | Boxコマンドラインインターフェース | Box CLI | 開発者でも開発者以外のユーザーでもBox APIを利用してルーチンや一括操作を実行できる、使い勝手の良いコマンドラインツール。 | | Box Custom Skill | カスタムスキル、Box Skill | Boxにアップロードされたファイルに対してカスタマイズした処理を実行するアプリケーションの種類。Skillsは、サードパーティの機械学習サービスを使用して、Boxにアップロードされたファイルから情報を自動的に抽出できるように設計されています。 | | Box Embed | | サードパーティ製アプリケーション内の任意の場所にBoxウェブアプリの機能を埋め込めるようにする、HTMLベースのフレームワーク。Box Embedを使用すると、ファイルのアップロード、検索、コメント付け、共有、タグ付けに加え、Box Editを使用したファイルの編集も可能になります。 | | Box Platform | | Platformアプリケーションを作成したり、ワークフローを統合したり、安全なドキュメントの保存、アクセスの制御、バージョン管理、メタデータ管理、リアルタイムコラボレーションのための強力な機能を活用したりするためのツールやインフラストラクチャを開発者に提供する、API駆動型のクラウドコンテンツ管理およびコラボレーションのプラットフォーム。 | | Boxサンプルコードカタログ | | 開発者と管理者は、さまざまなプログラミング言語のツール、自動化スクリプト、自習型ワークショップ、デモアプリのコードリポジトリを検索できます。このカタログには、80を超えるオープンソースリポジトリやガイドが用意されています。 | | Box Shield | | Boxが提供するセキュリティソリューションで、自動分類と先を見越した監視により、機密データの保護、不正アクセスの防止、潜在的な脅威の検出に役立ちます。 | | Box Skills | | Box Skillsは、コンテンツから自動的にインサイトとメタデータを抽出してBoxの機能を強化する、AIを活用した機能です。 | | Box Relay | | Box Relayを使用すると、コンテンツ中心のビジネスプロセスを自動化してスピードアップするためにワークフロー自動化を作成し、構成できます。 | | Box Verified Enterprise | BVE | Box Verified Enterpriseは、組織のコンテンツ管理システムのセキュリティとコンプライアンスを確保する認定プログラムです。 | | Box UI Elements | | 開発者がメインのBoxウェブアプリの要素を独自のアプリケーションに追加できるようにする、組み込みのUIコンポーネント。これを使用すると、Boxに保存されているコンテンツを参照、アップロード、プレビュー、選択することができます。また、これは、Reactコンポーネントとしても、フレームワークに依存しないJavaScriptライブラリとしても使用できます。 | | カスケードポリシー | | Boxでは、メタデータインスタンスをフォルダに追加し、それを自動的にフォルダのコンテンツにカスケードできるため、個別にインスタンスを追加する必要がありません。メタデータのカスケードを使用すると、一度で複数のファイルやサブフォルダにメタデータをすばやく追加できます。 | | 分類 | | ファイルまたはフォルダに適用される分類を含む、分類メタデータテンプレートのインスタンス。 | | コラボレーション | | ファイルまたはフォルダでの共同作業。 | | コラボレーション | 権限、ロールベースのアクセス制御 (RBAC)、アクセス制御リスト (ACL)、権限のマッピング | アクセス制御リストと同様に、コラボレーションではファイルとフォルダに対するユーザーおよびグループのアクセス権限が定義されます。コラボレーションオブジェクトは、特定のロールによって定義される権限を含んだファイルまたはフォルダへのアクセス権限をユーザーまたはグループに付与します。 | | コラボレータ | | ファイルまたはフォルダへのアクセス権限を共有するユーザー。 | | コラボレーションフォルダ | 共有フォルダ | 社内のユーザーが所有する共有フォルダ。 | | コラボレーションロール | 権限レベル、アクセスレベル | コラボレーションロールでは、特定のファイルまたはフォルダに対するユーザーの権限レベルが定義されます。Boxのコラボレーションロールには、所有者、共同所有者、編集者、ビューアー/アップローダー、プレビューアー/アップローダー、ビューアーがあります。Boxのコラボレーションレベルは、各ユーザーが招待されたフォルダおよびその下のサブフォルダのみにアクセスできる「ウォーターフォール」設計に従います。また、ユーザーを個々のファイルに招待することもできます。 | | コレクション | | ファイルやフォルダなどの項目の集合。コレクションのコンテンツは、フォルダのコンテンツと同じ方法で調べることができます。 | | コンテンツマネージャ | | 管理コンソールの機能で、次の操作を実行できます: 組織内のファイルやフォルダを検索およびダウンロードする、ユーザーごとにアクセス可能なファイルとフォルダを表示する、フォルダ間でファイルを移動する、コラボレータをフォルダに招待する、共有リンクを取得してアクセスレベルを変更する、ユーザーのごみ箱からファイルやフォルダを削除する。 | | 共同管理者 | | 一部の管理者権限を持っている、メイン管理者以外のユーザー。共同管理者は、組織の管理者と同じ操作を実行できますが、管理者の権限または他の共同管理者の権限を変更することはできません。共同管理者のデフォルトのアクセスレベルで可能なのはユーザーとグループの管理のみですが、このアクセスレベルはユーザーごとに変更できます。 | | Platformアプリ | | 他のツールやシステムとの統合により、Boxの機能が拡張されている独自のアプリケーション。ワークフローの効率化やコラボレーションの強化に使用されます。これは、開発者コンソールで作成でき、いくつかの認証方法を使用できます。 | | 開発者 | プログラマ | ソフトウェアアプリケーションやシステムの設計、構築、保守を担当し、開発者コンソールへのアクセス権限を持っている、技術を有する専門家。Boxでは、開発者に管理者ロールを割り当てることができます。 | | 開発者コンソール | | コードの実行とシステムのパフォーマンスに関するインサイトをリアルタイムに提供することで、開発者がアプリケーションを作成、デバッグ、テスト、監視できるようにするポータル。 | | Enterprise | リポジトリ、コンテンツストア、ファイルキャビネット、ドックベース、保管庫 | BoxのEnterpriseとは、Boxが大規模な組織向けに提供するツールとサービスの包括的なスイートであり、安全なファイルストレージ、コラボレーション機能、アクセス制御、ワークフローの自動化、コンプライアンスの適用、分析を実現します。効率的なドキュメント管理とチームワークを可能にしながら、企業の設定におけるデータのセキュリティを確保します。 | | 情報バリア | Information barriers | 利益相反につながり、結果として倫理的または法的に問題のあるビジネス活動につながる可能性があるやり取りまたは通信を防ぐメカニズム。 | | イベント | | ユーザーによって実行された操作の結果。Using the Enterprise Event Stream (英語) を参照してください。 | | 外部コラボレータ | 外部ユーザー | 企業に属していないコラボレータ。 | | 外部コラボレーションフォルダ | | 社外のユーザーが所有するフォルダ。 | | ファイル | ドキュメント、非構造化データ | 構造化されたフォーマットで情報やデータを保管するデジタルコンテナ。 | | フォルダ | ディレクトリ、コンテナ | ファイルが含まれているディレクトリ。 | | グループ管理者 | | グループ管理者は、担当グループへの既存ユーザーの追加、グループに割り当てる新規ユーザーの作成、グループへのフォルダアクセスの割り当てが可能です。また、グループに関するレポートも実行できます。 | | グループ | チーム | ユーザーがファイルを共有したり、ドキュメントでコラボレーションしたり、互いにコミュニケーションを取ったりできるコラボレーションワークスペース。 | | 項目 | オブジェクト、Boxオブジェクト、コンテンツ | ファイル、フォルダ、またはウェブリンクを表すことができます。 | | アクセス制限付きアプリ | | 特定のユーザーがBox Platform内の指定されたコンテンツにアクセスして操作できるように、開発者コンソールで作成された安全かつ制限されているアプリケーション。 | | 管理対象ユーザー | | 組織の管理者によって一元的に制御および管理されているユーザーアカウント。 | | メタデータテンプレート | ドキュメントクラス、ドキュメントタイプ、コンテンツタイプ、インデックス | ドキュメントまたはファイルに関する重要な情報を取得して整理する事前定義済みの構造。 | | メタデータ属性 | プロパティ、フィールド、キーワード、インデックス値 | メタデータ属性は、データの種類、形式、ソースなど、データの詳細をわかりやすく提供する情報です。 | | 個人用フォルダ | | 個人ユーザーが所有するフォルダ。 | | レポート | | 特定のデータセットが含まれているファイル。管理コンソールの [レポート] タブを使用して、使用状況のログ、ファイル/ユーザーの統計情報、セキュリティ監査など、アカウント全体のさまざまなレポートを実行できます。 | | サンドボックス | テスト環境 | 開発者向けに管理されている、追跡可能なテスト環境。実稼働環境ではありません。 | | サービスアカウント | | サービスアカウントにより、開発者は、サーバー側のBoxとの統合にプログラムによる認証メカニズムを使用できます。つまり、アプリケーションはBoxに対してサービスとして認証を受けることができ、これがサービスアカウントユーザーで表されます。その後、サービスアカウントを使用して、App Userと呼ばれるアプリケーション固有のユーザーを他に作成できます。 | | 共有リンク | | 社内外の同僚や友人と共有できる、Boxに保存されているコンテンツへのハイパーリンク。ファイルまたはフォルダへの共有リンクをユーザーに送信すると、共有コンテンツを使ってそのユーザーと共同作業することができます。カスタマイズ可能な権限レベル、有効期限、オプションのパスワード保護により、Boxの共有リンクは、重要なコンテンツを共有するための安全かつシンプルな手段となります。 | | ソフトウェア開発者向けツール | SDK | 開発者が特定のプラットフォームまたはフレームワーク用のソフトウェアアプリケーションを作成するのに役立つツール、ライブラリ、ドキュメントの集合。 | | タスク | 動作 | ドキュメントの共同作成エディタ内で完了する必要がある特定の操作または作業。 | | ユーザー | ID、人、権限を持つ人 | ドキュメントの共同作成エディタを使用して、ドキュメントの作成や編集、他のユーザーとのドキュメントの共有を行う個人。 | | 管理対象外ユーザー | | 組織によって一元管理されておらず、Box内のコンテンツに対するアクセスと制御が制限されているユーザーアカウント。また、管理対象外ユーザーは、必ずしも外部ユーザーであるとは限りません。 | | バージョン管理 | | すべてのユーザーが最新バージョンで作業できるように、異なるバージョンのドキュメントを管理して追跡すること。 | | Webhook | | Webhookは、アプリケーションがHTTP POSTリクエストを送信することによって、別のアプリケーションにリアルタイムのデータや通知を提供するための手段です。 | | ワークフロー | | Box内のワークフローは、ドキュメント中心のプロセスの効率化と進捗の追跡を支援する、自動化されたタスクのシーケンスであり、効率的なコラボレーションとタイムリーな完了を保証します。 | 次の手順 **Source:** [https://ja.developer.box.com/platform/box-glossary/](https://ja.developer.box.com/platform/box-glossary/) --- ### アーキテクチャパターン **Type:** page | **Category:** Box Platformについて | **Section:** Box Platform … # アーキテクチャパターン コードを書く前に、アプリケーションの視覚的なレプリゼンテーションを作成することをお勧めします。以下に示すアーキテクチャパターンは汎用的なものであり、すべての可能性を網羅しているわけではありません。 アプリケーションアーキテクチャに関するサポートをご希望の場合は、Box Consultingサービスの購入について、お客様のアカウントチームにお問い合わせください。 ## 管理タスク コンポーネント: - PowerShellスクリプトを実行しているサーバーまたはローカルマシン - ユーザープロビジョニング/プロビジョニング解除サービスがあるIDプロバイダ - 各ユーザーの個人用フォルダが含まれている、[サービスアカウント](page://platform/user-types/#service-account)の所有フォルダ - [イベントストリーム](e://resources/event)を監視し、個人用フォルダで各ユーザーを作成/コラボレーションする、時間に基づくPowerShellスクリプト ## 保管庫ポータル コンポーネント: - ユーザーがBox以外のブランド設定された環境でコラボレーションできるようにするカスタムポータル - ポータルが導入されているウェブサーバーにユーザーを分散させるロードバランサ - ユーザーは、IDプロバイダで管理されている資格情報を使ってログイン可能。その後、この資格情報は、データサーバー内のBoxからの[App User](page://platform/user-types/#app-user)情報にマッピングされます。 - 他のサイトデータはデータサーバーに保存 ## Box Skill この例では、外部ユーザーが[ファイルリクエスト](https://support.box.com/hc/ja/articles/360045304813-%E3%83%95%E3%82%A1%E3%82%A4%E3%83%AB%E3%83%AA%E3%82%AF%E3%82%A8%E3%82%B9%E3%83%88%E3%82%92%E4%BD%BF%E7%94%A8%E3%81%97%E3%81%A6%E3%82%B3%E3%83%B3%E3%83%86%E3%83%B3%E3%83%84%E3%82%92%E5%8F%96%E5%BE%97%E3%81%99%E3%82%8B)を介して履歴書をアップロードします。 [Box Skill](g://applications/app-types/custom-skills)は、特定のフォルダでのアップロード/移動/コピー操作を監視するように設定されています。イベントが発生すると、ファイルは、任意の機械学習サービスで処理するためにクラウドプロバイダに送信されます。処理が済むと、情報は[メタデータとしてファイルに再度保存](e://post-files-id-metadata-global-boxSkillsCards)されます。このメタデータは、その後、別のプロセスで使用したり、後で参照したりすることができます。 **Source:** [https://ja.developer.box.com/platform/appendix/architecture-patterns/](https://ja.developer.box.com/platform/appendix/architecture-patterns/) --- ### アプリケーションの種類 **Type:** page | **Category:** Box Platformについて | **Section:** Box Platform アプリケーションの種類 Boxには、アプリケーション開発におけるさまざまなニーズやユースケースに対応するために各種アプリケーションが用意されています。アプリケーションの種類ごとに機能や認証方法のオプションは異なります。 Platformアプリ Platform… # アプリケーションの種類 Boxには、アプリケーション開発におけるさまざまなニーズやユースケースに対応するために各種アプリケーションが用意されています。アプリケーションの種類ごとに機能や認証方法のオプションは異なります。 ## Platformアプリ [Platformアプリ](g://applications/app-types/platform-apps)は汎用性があるため、ほとんどのユースケースに対応可能です。開発者はカスタムアプリを使用することで、Boxの機能をカスタムインターフェース内に表示できます。Boxでは、コンテンツの閲覧、検索、プレビューなどのタスク向けにカスタマイズ可能なUI Elementsを提供しています。これらのアプリでは、認証用にOAuth 2.0、JWT、クライアント資格情報許可をサポートしています。Platformアプリは、自分のファイルと他のユーザーのファイル両方へのアクセス、ファイルのアップロードとダウンロード、Box統合への掲載が必要なアプリケーションに最適です。 ## アクセス制限付きアプリ [アクセス制限付きアプリ](g://applications/app-types/limited-access-apps)は、Box Viewを利用したり、別のアプリケーション内でBoxコンテンツをプレビューしたりするために特別に設計されたアプリです。アクセスできるエンドポイントの数は限られており、アプリトークン認証のみがサポートされています。このようなアプリは、ウェブサイトでプロのクリエイターの作品集を紹介する、サポートサイトでユーザーマニュアルを提供する、電子書籍や間取り図用のカスタムドキュメントビューアーを作成するなどのユースケースに適しています。 ## Box Skills [Box Skills](g://applications/app-types/custom-skills) (カスタムスキル) は、Boxにアップロードされたファイルに対してカスタマイズした処理を実行するアプリケーションです。サードパーティの機械学習サービスを使用してファイルから情報を抽出し、それをメタデータとして適用します。このようなスキルはBox管理者がフォルダに対して有効にするので、ファイルがアップロードされるたびにアプリケーションサーバーにイベントが送信されます。カスタムスキルは、ファイルにメタデータを追加したり、認証を処理することなく機械学習サービスと統合したりする場合に最適です。 ## ウェブアプリ統合 [ウェブアプリ統合](g://applications/web-app-integrations)を使用すると、サードパーティ製アプリケーションはBoxのユーザーエクスペリエンスとシームレスに統合できます。これにより、ユーザーはサードパーティ製アプリケーションを使用して、Boxに保存されているコンテンツを編集、共有、変更することができます。このような統合は、Boxユーザーに新機能を追加したり、Boxプレビューの [推奨ウェブ統合] に追加したりできるため、さまざまなコンテンツタイプやファイル拡張子と統合され、ユーザーエクスペリエンスが向上します。 ## 統合での公開 [Box統合](g://applications/integrations/)は、BoxユーザーがBoxと連携して使用できるアプリケーションを見つけるためのプラットフォームです。開発者にとって、統合へのアプリケーションの掲載は、特に他の企業での使用に適したアプリケーションの場合、新規ユーザーにリーチを広げるのに効果的な手段となります。統合での公開プロセスでは、アプリケーションが本番環境に対応していることとOAuth 2.0認証を利用していることを確認し、開発者コンソールから承認を得るためにそのアプリケーションを送信する必要があります。承認されると、アプリケーションは統合の [おすすめ]、[人気]、[新着] セクションに分類されます。また、必要に応じて公開を取り消すこともできます。 次の手順 **Source:** [https://ja.developer.box.com/platform/application-types/](https://ja.developer.box.com/platform/application-types/) --- ### サポート **Type:** page | **Category:** Box Platformについて | **Section:** Box Platform サポート Box Developer Relationsチームは、できる限り開発者の皆様をサポートしたいと考えています。開発者への定期的な聞き取り調査以外に、以下のようなBoxへの問い合わせ方法も用意しています。 Developer Forum (英語のみ) Boxは最近、Box… # サポート Box Developer Relationsチームは、できる限り開発者の皆様をサポートしたいと考えています。開発者への定期的な聞き取り調査以外に、以下のようなBoxへの問い合わせ方法も用意しています。 ## Developer Forum (英語のみ) Boxは最近、Box Developer Communityをリニューアルしました。開発者同士がつながり、開発の問題について質問することがさらに容易になりました。また、ご自身の成功体験も共有していただけます。[今すぐご参加ください](https://community.box.com/)。 ## Mediumブログ Boxと一部のパートナー企業は、定期的にBoxの[Mediumブログ](https://medium.com/box-developer-japan-blog)でチュートリアルやお知らせを公開しています。通常は毎週火曜日にコンテンツをリリースしますが、それより頻度が高くなることもあります。コンテンツのご要望がありましたら、ぜひDeveloper Forumまで英語でお寄せください。 ## Box PlatformのTwitter Developerドキュメントの変更ログと同様に、Box Platformの更新情報や新規ブログを投稿しています。[Box Platform](https://twitter.com/BoxPlatform)でフォローできます。 次の手順 **Source:** [https://ja.developer.box.com/platform/support/](https://ja.developer.box.com/platform/support/) --- ### ツール **Type:** page | **Category:** Box Platformについて | **Section:** Box Platform ツール Boxには、開発をスムーズに開始できるようにするツールがいくつか用意されています。以下をご確認ください。 サンプルコードカタログ サンプルコードカタログは、当社がBox Developer… # ツール Boxには、開発をスムーズに開始できるようにする[ツール](g://tooling)がいくつか用意されています。以下をご確認ください。 ## サンプルコードカタログ [サンプルコードカタログ](https://ja.developer.box.com/sample-code/)は、当社がBox Developerドキュメントポータルでリリースした最新のツールです。これは、複数の場所からコードサンプルリポジトリを集めて、1か所で閲覧できるように統合したものです。ここでは、言語やタスクでフィルタをかけることができます。リストは定期的に更新しているため、最新のコードを入手できます。 ## Box CLI Boxコマンドラインインターフェース (CLI) は、ターミナルウィンドウまたはコマンドプロンプトからBox APIに対してリクエストを行うためのツールです。設定には5分もかからず、APIに直接アクセスできます。Boxでは、管理の自動化タスクを短時間で開始するための一連の[サンプルスクリプト](g://cli/scripts)も提供しています。 ## SDK Boxは、[SDKライブラリ](page://sdks-and-tools)で複数のプログラミング言語をサポートしています。認証や再試行ロジックなどがライブラリによって自動的に処理されるため、ソリューションを作成する際はSDKを使用することを強くお勧めします。さらに、APIリファレンスのページには、サイト内のすべての言語のサンプルが直接掲載されていますが、各GitHubリポジトリにも、その言語のサンプルがすべて掲載されたドキュメントセクションがあります。 ## Postmanコレクション ソフトウェア開発の業界標準であるPostmanは、リアルタイムテストとコードサンプルを提供して、開発者が短期間でAPIを習得できるようサポートしています。BoxのPostmanコレクションについては、[Postmanのウェブサイト](https://www.postman.com/boxdev)を参照してください。また、下のYouTube動画もご確認ください。 次の手順 **Source:** [https://ja.developer.box.com/platform/tools/](https://ja.developer.box.com/platform/tools/) --- ### ブランディングガイドライン **Type:** page | **Category:** Box Platformについて | **Section:** Box Platform ブランディングガイドライン Box Platformをご利用いただき、誠にありがとうございます。ぜひ、お客様のBoxのご利用体験を世界に向けて発信してください。ただし、お客様のアプリケーションとBox… # ブランディングガイドライン Box Platformをご利用いただき、誠にありがとうございます。ぜひ、お客様のBoxのご利用体験を世界に向けて発信してください。ただし、お客様のアプリケーションとBox公式アプリケーションが混同されないようにすることは非常に重要です。そのため、当社の名称とロゴの使用に関するガイドラインをご用意しました。 ## 承認済みのロゴ 承認済みのBoxロゴは、[このBoxフォルダ](https://cloud.app.box.com/v/BoxCorporateLogo)で確認できます。 ## お願いしたいこと ### ユーザーへの周知 Boxに接続していることをユーザー自身が認識できるようにしてください。 多くのアプリには、「クラウドサービスに接続」のようなメニューがあります。この場合は、ユーザーにわかるように当社の名称とロゴをご自由にお使いいただけます。 ### 当社へのお問い合わせ 判断に迷う場合はご相談ください。お客様のアプリが当社のガイドラインに沿って動作するようお手伝いします。[ご不明な点があればこちらからお問い合わせください](https://support.box.com/hc/ja/requests/new)。 ## ご遠慮いただきたいこと ### Boxと間違われないようにする お客様のアプリケーションに、Box公式アプリケーションと間違えられる可能性のある名前を付けないでください。 つまり、Boxの公式なものでないことが明白な場合を除き、「Box」という単語は使わないようにしてください。たとえば、「Unofficial Box Client」は公式なものでないことが明らかですが、「Box App for Android」は不明確です。 お客様のブランド名を含める場合 (たとえば「<会社名> Box Client」) は、おそらく問題ないと考えられます。ただし、これはブランディングガイドラインとしては非常に不明瞭なため、ご不明な点がある場合は[お問い合わせください](https://support.box.com/hc/ja/requests/new)。迅速に対応いたします。 まとめると、次のようになります。 - 当社のロゴ、類似のロゴ、または当社のロゴの一部をお客様のアプリケーションのアイコンとして使用しないでください。 - お客様のアプリケーション内で当社の名称またはロゴを、そのアプリケーションがBox公式アプリケーションに見えるような形で使用しないでください。 ### Boxのロゴを改変しない お客様のアプリケーションで「Box」のロゴを使用する場合は、どのような方法であってもそのロゴを改変しないでください。 ### 古い名称を使用しない 当社について言及する場合に、`Box.net`または`Boxnet`を使用しないでください。当社は「Box」としてのみ認知されています。 **Source:** [https://ja.developer.box.com/platform/appendix/branding-guidelines/](https://ja.developer.box.com/platform/appendix/branding-guidelines/) --- ### ユーザータイプ **Type:** page | **Category:** Box Platformについて | **Section:** Box Platform ユーザータイプ アプリケーションの計画と開発で重要なのは、関与するユーザーのタイプを把握することです。ユーザーのタイプには、主に、管理対象ユーザー (内部および外部)、管理者、サービスアカウント、App Userの… # ユーザータイプ アプリケーションの計画と開発で重要なのは、関与するユーザーのタイプを把握することです。ユーザーのタイプには、主に、管理対象ユーザー (内部および外部)、管理者、サービスアカウント、App Userの4つがあります。それぞれの違いを詳しく見ていきましょう。 # 自分のアプリケーションで使用するユーザーのタイプ アプリケーションがどのタイプのユーザーとして認証されるかは、作成したアプリケーションの種類と、アクセストークンの作成で使用した認証の種類によって決まります。 ## 管理者または共同管理者ユーザー Box管理者とは、主要なBoxアカウント管理者です。管理者は、管理者権限が同等かより厳しく制限されている共同管理者を追加することができます。管理者と共同管理者は、管理コンソールで直接、セキュリティ設定を編集、削除、適用したり、ユーザーに対してレポートを実行したりできます。 ## 管理対象ユーザー 各Box Enterpriseには、一意のEnterprise IDが割り当てられます。管理対象ユーザーとは、1つのEnterprise IDに属しているすべてのユーザーのことです。管理対象ユーザーは、標準のBoxライセンスを購入しており、例外もありますがほとんどの場合に同じメールドメインを共有します。 # 管理者ユーザーとしてログイン アプリケーションの中には、正しく動作するために管理者だけが持つ権限を必要とし、管理者にログインを要求するものがあります。 この一例として、Enterprise Eventを監視し、不審なイベントに対して措置を講じるセキュリティアプリケーションがあります。イベントエンドポイントを使用できるのは、レポートへのアクセス権限を持つ管理者または共同管理者のみです。 ## 外部ユーザー 外部で管理されているユーザー (外部ユーザー) とは、別のEnterprise IDに属している管理対象ユーザーです。外部ユーザーによく遭遇するのは、外部ユーザーが、アプリケーションの企業の管理対象ユーザーが所有するコンテンツでコラボレーションしている場合や、OAuth 2.0アプリケーションを承認する場合です。外部ユーザーは各自Boxアカウントを所有していますが、管理コンソールで管理することができません。 ## サービスアカウント サービスアカウントにより、開発者は、サーバー側のBoxとの統合にプログラムによる認証メカニズムを使用できます。つまり、アプリケーションはBoxに対してサービスとして認証を受けることができ、これがサービスアカウントユーザーで表されます。サービスアカウントは、API経由でしかアクセスできません (つまり、ログイン資格情報を持っていません)。 その後、サービスアカウントを使用して、App Userと呼ばれるアプリケーション固有のユーザーを他に作成できます。App Userについては、以下で詳しく説明します。 ### 作成 サーバー認証を利用するアプリケーションが管理コンソールで[承認](g://authorization/custom-app-approval)されるとすぐに、一意のBoxサービスアカウントが自動的に生成されます。その時点から、そのサービスアカウントはBox Enterprise内のアプリケーションを表します。すべてのBoxアカウントにはメールアドレスが必要なため、Boxによって割り当てられます。これは常に`AutomationUser_AppServiceID_RandomString@boxdevedition.com`形式になります (例: `AutomationUser_123456_6jCo6Pqwo@boxdevedition.com`)。サービスアカウントが自動化ユーザーと呼ばれることがあるのはこのためです。 アンダースコアで囲まれた数字もアプリケーションに固有であり、サービスIDと呼ばれます。[開発者コンソール](https://app.box.com/developers/console)でサービスIDを見つけるには、アプリケーションのタイルをクリックし、URLを確認します。たとえば、`https://example.app.box.com/developers/console/app/123456`というURLの場合、このアプリケーションは、上記の例で示したサービスアカウントに対応していることがわかります。 デフォルトでは、ほとんどのサービスアカウントに10 GBのストレージが割り当てられます。これは、サービスアカウントが管理コンソールの [**ユーザー設定**] タブにある [**新規ユーザーの初期設定**] で設定されたストレージ割り当てに従うためです。この容量は、企業がこの設定を更新したかどうかによって異なる場合があります。サービスアカウントに割り当てられているストレージの容量をアカウント作成後に更新するには、[ユーザーを更新](e://put-users-id)エンドポイントに対するAPIコールを実行し、`space_amount`本文パラメータを使用して目的の値 (バイト単位) を渡します。 サービスアカウントが生成されると、[開発者コンソール](https://app.box.com/developers/console)の [一般設定] タブにセクションが自動的に追加され、メールアドレスが表示されます。 アプリケーションが管理コンソールで承認される前に、ユーザーがサービスアカウントアクセストークンを使用してAPIコールを実行しようとすると、次のエラーメッセージが表示されます: `"error": "unauthorized_client"` `"error_description": "This app is not authorized by the enterprise"` ### ユースケース - *ディストリビューションの公開*: 認証されているかどうかに関係なく、ファイルをアップロードし、多数のユーザーと共有します。 - *オンプレミスのシステムとデバイス*: オンプレミスシステムや接続されたデバイスからプログラムによってコンテンツを取り込みます。 - *コンテンツの移行と監視*: コンテンツをオンプレミスからクラウドへ移動したり、クラウドプロバイダ間で移動したりします。 - *イベント監視*: 社内のイベントを監視して、アクションに基づいてコンプライアンス順守を確保したり、ワークフローをトリガーしたりします。 - *コンテンツのアーカイブ*: 最低限しかアクセスされないコンテンツを格納します。 ### 権限 サービスアカウントアクセストークンで問題なく操作できるエンドポイントは、[開発者コンソール](https://app.box.com/developers/console)で構成されたアプリケーション[スコープ](g://api-calls/permissions-and-errors/scopes)によって決まります。付与されているスコープによっては、サービスアカウントが管理者アクションを実行できる場合があります。 # 管理者の承認 適切な[スコープ](g://api-calls/permissions-and-errors/scopes)が有効になっている場合、サービスアカウントは多くの管理者アクションを実行できます。そのため、JWTアプリケーションを社内で使用できるようにするには、事前に明示的な[管理者による承認](g://authorization/custom-app-approval)が必要です。 ### UIでのアクセス 管理コンソールの[コンテンツマネージャ](https://support.box.com/hc/ja/articles/360044197333-%E3%82%B3%E3%83%B3%E3%83%86%E3%83%B3%E3%83%84%E3%83%9E%E3%83%8D%E3%83%BC%E3%82%B8%E3%83%A3%E3%81%AE%E4%BD%BF%E7%94%A8)からサービスアカウントとしてログインできるのは、プライマリ管理者のみです。これには、コンテンツマネージャの検索バーを使用してアプリケーションの名前を見つけ、その名前を右クリックして [ユーザーのアカウントにログイン] を選択します。 サービスアカウントは、Boxの共同管理者の権限を持っていると考えることができます。共同管理者がお互いを管理できないのと同じように、共同管理者がサービスアカウントユーザーとしてログインすることはできません。 サービスアカウントは、現在、管理コンソールの [ユーザーとグループ] タブに表示されていません。 ### フォルダツリーとコラボレーション サービスアカウントは、アプリケーションをEnterprise内のユーザーとして表すため、独自のフォルダツリーとコンテンツ所有権の機能が用意されています。最初は、所有するコンテンツやコラボレーションするコンテンツがないため、このフォルダツリーはデフォルトで空になっています。これは、新しくプロビジョニングしたBoxアカウントの [すべてのファイル] ページに最初にアクセスしたときと似ています。 既存のコンテンツでのコラボレーションにサービスアカウントを追加するには、他のユーザーの場合と同様、割り当てられたメールアドレスを使用してサービスアカウントを招待します。[APIを使用して](e://post-collaborations)コラボレーションを追加する場合は、すでにコンテンツへのアクセス権があり、コラボレータを招待するための適切なコラボレーション権限を持っているユーザーのアクセストークンを使用する必要があります。また、サービスアカウントのユーザーIDも使用します。このユーザーIDは、サービスアカウントのアクセストークンを使用して[現在のユーザーを取得エンドポイント](e://get-users-me)を呼び出したときに返されます。 コラボレーションを追加する際に覚えやすくなるよう、サービスアカウントにメールエイリアスを割り当てることができます。 ### Box View サービスアカウントは、[開発者コンソール](https://app.box.com/developers/console)でアクセス制限付きアプリを作成したときにも自動的に生成されます。このサービスアカウントには、Platformアプリに関連付けられたサービスアカウントにはない追加の制限がいくつかあります。 - アクセス制限付きアプリ内で使用されるコンテンツはすべて、このサービスアカウントがアップロードおよび所有する必要がある - このサービスアカウントは、他のユーザーの情報やコンテンツにアクセスできない - このサービスアカウントは、タイプを問わず新しいユーザーを作成することも管理することもできない - このサービスアカウントは、コンテンツのプレビューに関連するAPIのサブセットにしかアクセスできない ## App User App Userは、API経由でしかアクセスできません (つまり、ログイン資格情報を持っていません)。これは、サービスアカウントによって作成できるため、サーバー間認証を利用するアプリケーションのみに適用できます。App Userは、その作成に使用されたアプリケーションに関連付けられています。また、そのアプリケーション以外でのコンテンツのコラボレーションは可能ですが、このユーザー自体を別のアプリケーション下に移動することはできません。 ### 作成 App Userを作成するには、サービスアカウントアクセストークンを使用して、[ユーザーを作成エンドポイント](e://post-users)を呼び出します。`is_platform_access_only`本文パラメータはtrueに設定する必要があります。そうしないと、代わりに管理対象ユーザーが作成されます。 すべてのBoxアカウントにはメールアドレスが必要なため、Boxによって割り当てられます。これは常に`AppUser_AppServiceID_RandomString@boxdevedition.com`形式になります (例: `AppUser_1234567_LOCqkWI79A@boxdevedition.com`)。 アンダースコアで囲まれた数字もアプリケーションに固有であり、サービスIDと呼ばれます。[開発者コンソール](https://app.box.com/developers/console)でサービスIDを見つけるには、アプリケーションのタイルをクリックし、URLを確認します。たとえば、`https://exampl.app.box.com/developers/console/app/1234567`というURLの場合、このアプリケーションは、上記の例のApp Userに対応していることがわかります。 ### ユースケース App Userは、既存のBoxアカウントを持っているかどうかに関係なく、BoxのPlatformの機能を、任意のユーザーにサービスを提供するアプリケーションに拡張します。App Userは、独自のユーザー認証を管理しつつもデータを一意のBoxユーザーアカウントに保存しようとするアプリケーションでよく使用されます。 - *顧客ポータル*: 顧客や患者がログインして、企業の従業員が提供する情報にアクセスしたり、自分の機密文書を保存および取得したりできるウェブサイトまたはアプリケーション。 - *ベンダーポータル*: 企業がマーケティング用販促品、価格表、製品情報、販売契約書、その他のドキュメントを含む資料をベンダーに提供するためのコンテンツ配布サイト。Boxのグループと権限モデルにより、企業はパートナーの基準や層に基づいてパートナー向けのコンテンツを編成できます。 - *ブランドの顧客向けアプリケーション*: エンドユーザーに代わってApp Userを作成できるため、企業は、権限、監査、レポートなどのシームレスな顧客向け機能を構築できます。これは、金融サービスや医療などの規制産業にとって特に有用です。さらに、Boxの[レポート機能](e://get-events)によって取得したユーザーベースのデータにより、開発者は分析ツールを活用して、ユーザーの行動についてより理解を深めることができます。 ### 権限 App Userは、コラボレータとして明示的に追加されない限り、サービスアカウントのフォルダツリー内のコンテンツを表示することも操作することもできません。また、App Userはログイン資格情報を持っていないため、Platformアプリケーション以外でコンテンツにアクセスすることはできません。 ### UIでのアクセス App Userには、管理コンソールの [[ユーザーとグループ] タブ](https://support.box.com/hc/ja/articles/360043695714-%E7%AE%A1%E7%90%86%E3%82%B3%E3%83%B3%E3%82%BD%E3%83%BC%E3%83%AB%E3%82%AC%E3%82%A4%E3%83%89)からアクセスできます。これらのユーザーにフィルタをかけるには、表示オプションボタン > [ロール] > [App User] を使用します。 管理コンソールの[コンテンツマネージャ](https://support.box.com/hc/ja/articles/360044197333-%E3%82%B3%E3%83%B3%E3%83%86%E3%83%B3%E3%83%84%E3%83%9E%E3%83%8D%E3%83%BC%E3%82%B8%E3%83%A3%E3%81%AE%E4%BD%BF%E7%94%A8)からもApp Userにアクセスできます。 ### フォルダツリーとコラボレーション 各App Userには、独自のフォルダツリーとコンテンツ所有権の機能があります。最初は、所有するコンテンツやコラボレーションしているコンテンツがないため、このフォルダツリーはデフォルトで空になっています。これは、新しくプロビジョニングしたBoxアカウントの [すべてのファイル] ページに初めてアクセスしたときと似ています。 既存のコンテンツでのコラボレーションにApp Userを追加するには、他のユーザーの場合と同様、割り当てられたメールアドレスを使用してApp Userを招待します。[APIを使用して](e://post-collaborations)コラボレーションを追加する場合は、すでにコンテンツへのアクセス権があり、コラボレータを招待するための適切なコラボレーション権限を持っているユーザーのアクセストークンを使用する必要があります。 ## As-User アプリケーションの認証方法としてOAuth 2.0、JWT、またはCCGを使用している場合、`as-user`コールを行うことができます。つまり、Box APIへの最初の接続を自分自身またはサービスアカウントとして作成した場合でも、それ以降のコールを別のユーザーの代理として行うことができます。これは、フォルダの再編成や従業員のプロビジョニングなどの管理タスクを自動化する場合に便利です。`as-user`コールを行うには、開発者コンソールでアプリケーションを作成する際に適切なスコープを追加する必要があります。たとえば、OAuth 2.0 Platformアプリでは、次の切り替えをオンにする必要があります。 次の手順 **Source:** [https://ja.developer.box.com/platform/user-types/](https://ja.developer.box.com/platform/user-types/) --- ### ユーザーモデル **Type:** page | **Category:** Box Platformについて | **Section:** Box Platform ユーザーモデル ユースケースがBox Platform… # ユーザーモデル [ユースケース](page://platform/use-cases)がBox Platformに適していることを確認し、関与する[ユーザーのタイプ](page://platform/user-types)をしっかりと理解したら、[アプリケーションアーキテクチャ](page://platform/appendix/architecture-patterns)を開始するためのユーザーモデルを選択できます。 ## 従来型 このモデルでは、アプリケーションに内部ユーザーと外部ユーザーが存在します。外部ユーザーは、Boxウェブアプリを使用する内部ユーザーとコンテンツの共有やコラボレーションを行います。 - **内部ユーザーのタイプ**: [管理対象ユーザー](page://platform/user-types/#managed-users) - **外部ユーザーのタイプ**: [App User](page://platform/user-types/#app-user) - **コンテンツの所有者**: アプリケーション[サービスアカウント](page://platform/user-types/#service-account)または[管理対象ユーザー](page://platform/user-types/#managed-users) - **例**: 保管庫ポータル、ドキュメント提出、フィールドワーカーアプリケーション このユーザーモデルのメリット: 1. 内部ユーザーのために追加の機能を開発する必要がない 2. App Userを独自のIDシステム (`Auth0`など) にマッピングできる 3. セキュリティおよびコンプライアンスの要件を満たすために、すべての処理のレポートを作成できる ## App User このモデルでは、アプリケーションに内部ユーザーと外部ユーザーが存在し、全員が同じカスタムUIを利用しています。 - **内部ユーザーのタイプ**: [App User](page://platform/user-types/#app-user) - **外部ユーザーのタイプ**: [App User](page://platform/user-types/#app-user) - **コンテンツの所有者**: [App User](page://platform/user-types/#app-user) - **例**: 保管庫ポータル、ドキュメント提出、フィールドワーカーアプリケーション このユーザーモデルのメリット: 1. 内部ユーザーと外部ユーザーにカスタムエクスペリエンスを提供できる 2. 管理対象ユーザーが個別のApp Userアカウントを所有できるようにすることで、管理対象ユーザーとアプリケーションコンテンツが切り離される 3. App Userを独自のIDシステム (`Auth0`など) にマッピングできる 4. セキュリティおよびコンプライアンスの要件を満たすためにすべての処理のレポートを作成したり、他のシステムで追跡したりできる ## サービスアカウント このモデルでは、アプリケーションに内部ユーザーと外部ユーザーが存在しますが、ユーザーオブジェクトがすでに存在します。このモデルは、ユーザーが一時的なユーザーでもコンテンツは保持する必要がある場合にもうまく機能します。 - **内部ユーザーのタイプ**: [管理対象ユーザー](page://platform/user-types/#managed-users) - **外部ユーザーのタイプ**: 顧客のアプリケーションによって管理されている - **コンテンツの所有者**: アプリケーション[サービスアカウント](page://platform/user-types/#service-account) - **例**: 資産管理ポータル、保険金請求ワークフロー このユーザーモデルのメリット: 1. App Userモデルを使用すると既存のアプリケーションによる処理が複雑になる場合に便利 2. エンドユーザーとApp Userが1対1でマッピングされていない場合 (ユーザーがグループとしてマッピングされている場合など) に便利 3. サービスアカウントがすべてのコンテンツを所有するため、権限を管理しやすい 4. サービスアカウントへのアクセス範囲を制限するように、トークン交換を実装できる ## システム対システム このモデルでは、通常、ユーザーコンテンツを処理する必要がありません。 - **外部ユーザーのタイプ**: 該当なし - **内部ユーザーのタイプ**: 該当なし - **コンテンツの所有者**: アプリケーション[サービスアカウント](page://platform/user-types/#service-account) - **例**: バックオフィスアプリケーション、統合、ユーザープロビジョニング、フォルダの自動作成 このユーザーモデルのメリット: 1. ユーザーを作成する必要がない場合に便利 (たとえば、個々のユーザーではなく、部門や会社がコンテンツを所有する場合) 2. サービスアカウントの権限を昇格させることができるため、バックエンドサービスに対する権限の割り当てを徹底的に制御できる **Source:** [https://ja.developer.box.com/platform/appendix/user-models/](https://ja.developer.box.com/platform/appendix/user-models/) --- ### ユースケース **Type:** page | **Category:** Box Platformについて | **Section:** Box Platform ユースケース アプリケーションの開発を始める前に、自分のユースケースがBox Platform… # ユースケース アプリケーションの開発を始める前に、自分のユースケースがBox Platformに適しているかどうか評価することをお勧めします。一般的には、コンテンツ中心のプロセスでパフォーマンスを最も発揮できます。 ユースケースを評価する際の質問の例を以下に示します。 - コンテンツは常にプロセスに関与していますか。 - プロセスにはコンテンツの移動が伴いますか。 - ワークフローは[ウォーターフォール型の権限](https://support.box.com/hc/ja/articles/360043697254-%E3%83%95%E3%82%A9%E3%83%AB%E3%83%80%E3%81%AE%E6%A8%A9%E9%99%90%E3%81%AB%E3%81%A4%E3%81%84%E3%81%A6)に準拠できますか。 - プロセスには、自動化できる管理タスクが含まれていますか。 上記の質問に対する答えが**はい**である場合は、Box Platformに適したユースケースである可能性が高くなります。 お客様向けの一般的なソリューションには、以下のようなものがあります。 - マーケティング資産の管理 - ドキュメントの安全な保管庫 - 資産管理ポータル - ユーザープロビジョニングに基づくフォルダの自動作成 - 機械学習を使用した関連メタデータの追加 - 組み込みの承認/拒否フローによるクレームレビュー - セキュリティと監査のためのイベント監視 適切なユースケースかどうかをまだ判断できない場合は、Boxアカウントチームまでお問い合わせください。 次の手順 **Source:** [https://ja.developer.box.com/platform/use-cases/](https://ja.developer.box.com/platform/use-cases/) --- ### 一般的な値の確認 **Type:** page | **Category:** Box Platformについて | **Section:** Box Platform 一般的な値の確認 ユーザーID 開発者の場合 Boxウェブアプリで自分のユーザーIDを確認するには、[すべてのファイル] ページに移動し、右上隅の円をクリックして、ドロップダウンメニューから [アカウント設定] を選択します。ユーザーID… # 一般的な値の確認 ## ユーザーID ### 開発者の場合 Boxウェブアプリで自分のユーザーIDを確認するには、[**すべてのファイル**] ページに移動し、右上隅の円をクリックして、ドロップダウンメニューから [**アカウント設定**] を選択します。ユーザーIDは、[**アカウント**] タブの [**アカウントの詳細**] セクションに表示されている [**アカウントID**] の値です。 APIを使用してユーザーIDを確認するには、開発者コンソールに移動し、[開発者トークン](g://authentication/tokens/developer-tokens)を生成するか、自分で[アクセストークン](g://authentication/tokens/access-tokens)を取得します。このトークンを[現在のユーザーを取得エンドポイント](e://get-users-me)で使用すると、`id`フィールドにユーザーIDが返されます。 ### 管理者の場合 自分のアカウントの種類で[コンテンツマネージャ](https://support.box.com/hc/ja/articles/360044197333-%E3%82%B3%E3%83%B3%E3%83%86%E3%83%B3%E3%83%84%E3%83%9E%E3%83%8D%E3%83%BC%E3%82%B8%E3%83%A3%E3%81%AE%E4%BD%BF%E7%94%A8)にアクセスできる場合は、ユーザーリストで当該ユーザーをクリックします。URLでユーザーIDが示されます。たとえば、`https://.app.box.com/master/content/2267862105/0/0`の場合、ユーザーIDは`2267862105`です。 APIを使用してユーザーIDを確認するには、開発者コンソールに移動し、[開発者トークン](g://authentication/tokens/developer-tokens)を生成するか、自分で[アクセストークン](g://authentication/tokens/access-tokens)を取得します。その後、[企業ユーザーのリストを取得](e://get-users)エンドポイントに対してAPIコールを実行します。これにより、企業内のすべてのユーザーのリストが返されます。 ## Enterprise ID ### 開発者の場合 APIを使用してEnterprise IDを取得するには、開発者コンソールに移動し、[開発者トークン](g://authentication/tokens/developer-tokens)を生成するか、自分で[アクセストークン](g://authentication/tokens/access-tokens)を取得します。このトークンを[現在のユーザーを取得エンドポイント](e://get-users-me)で使用し、`enterprise`フィールドをリクエストします。 ### 管理者の場合 **管理コンソール**で、[**アカウントと請求**] タブに移動します。Enterprise IDは、[**アカウント情報**] セクションにあります。 ## コンテンツID ### 開発者の場合 BoxウェブアプリでファイルIDを確認するには、ブラウザでファイルのプレビューに移動し、URLを確認します。たとえば、`https://app.box.com/file/1234567890`のファイルIDは`1234567890`です。 BoxウェブアプリでフォルダIDを確認するには、フォルダに移動し、URLを確認します。たとえば、`https://app.box.com/folder/9876543210`のフォルダIDは`9876543210`です。 APIを使用してコンテンツIDを確認するには、まず、[フォルダ内の項目のリストを取得](e://get-folders-id-items)エンドポイントの`folder_id`として`0`を渡すことで、[すべてのファイル] レベルの全項目のリストを取得します。 ### 管理者の場合 [コンテンツマネージャ](https://support.box.com/hc/ja/articles/360044197333-%E3%82%B3%E3%83%B3%E3%83%86%E3%83%B3%E3%83%84%E3%83%9E%E3%83%8D%E3%83%BC%E3%82%B8%E3%83%A3%E3%81%AE%E4%BD%BF%E7%94%A8)にアクセスできる場合は、ユーザーリストで当該ユーザーをクリックしてから、コンテンツに移動します。URLにフォルダ/ファイルIDが示されます。たとえば、`https://app.box.com/master/content/1987212562/88560510648/0/532181212706`の場合、ユーザーIDは`1987212562`、フォルダIDは`88560510648`、そのフォルダ内のファイルIDは`532181212706`です。 **Source:** [https://ja.developer.box.com/platform/appendix/locating-values/](https://ja.developer.box.com/platform/appendix/locating-values/) --- ### 付録 **Type:** page | **Category:** Box Platformについて | **Section:** Box Platform … # 付録 このセクションでは、入門者向けのその他の資料を紹介します。最初から知っておかなければならないというわけではありませんが、問題が発生した場合に解決策を特定するのに役立ちます。 - [ユーザーモデル](page://platform/appendix//user-models): このページでは、このシリーズで前述したユーザータイプの使用方法について説明します。 - [アーキテクチャパターン](page://platform/appendix/architecture-patterns): このページでは、よく目にするインフラストラクチャのパターンについて説明します。 - [一般的な値の確認](page://platform/appendix/locating-values): このページでは、ユーザーIDなどの情報を確認する方法について説明します。 - [ブランディングガイドライン](page://platform/appendix/branding-guidelines/): このページでは、プロジェクトにBoxブランドを使用する予定の場合のさまざまな注意事項を示しています。 **Source:** [https://ja.developer.box.com/platform/appendix/](https://ja.developer.box.com/platform/appendix/) --- ### 認証方法 **Type:** page | **Category:** Box Platformについて | **Section:** Box Platform 認証方法 Boxには、アプリケーション開発のためのさまざまな認証方法が用意されており、それぞれが異なるユースケースやアプリケーションの種類に対応しています。使用する認証方法に関係なく、基本的な原則が適用されます。ユーザーは、メインのBox… # 認証方法 Boxには、アプリケーション開発のためのさまざまな認証方法が用意されており、それぞれが異なるユースケースやアプリケーションの種類に対応しています。使用する認証方法に関係なく、基本的な原則が適用されます。ユーザーは、メインのBoxウェブアプリのフロントエンドでコンテンツにアクセスできない場合、別のユーザーになりすまさない限り、APIを使用してコンテンツにアクセスすることはできません。APIエンドポイントの中には、イベントなど、管理者レベルの権限が必要なものもあります。 各種Boxアプリケーションでは、以下の承認方法を使用できます。 | Boxアプリケーションの種類 | OAuth 2.0をサポートしますか? | JWTは? | クライアント資格情報は? | アプリトークンは? | | --- | --- | --- | --- | --- | | Platformアプリ | はい | はい | はい | いいえ | | アクセス制限付きアプリ | いいえ | はい | いいえ | はい | | カスタムスキル | いいえ | いいえ | いいえ | いいえ | ## OAuth 2.0 [OAuth 2.0](g://authentication/oauth2)はクライアント側の認証方法で、そのシンプルさからBox APIに対するユーザーの承認で広く使われています。これはオープンスタンダードであり、ユーザーはアプリケーションに対して他のアプリケーション内の自分のデータへのアクセスを許可できるようになります。Boxのクライアント側認証では、Twitter、Facebook、Googleを使用してウェブサイトにログインする仕組みと同様に、ユーザーはアプリからBoxウェブアプリにリダイレクトされるので、そこでログインしてアプリに自分のデータへのアクセスを許可します。たとえば、Boxではコミュニティフォーラムにログインするユーザーに対してこの認証タイプを使用します。 # OAuth 2.0はいつ使用すべきですか? クライアント側認証は、以下に当てはまるアプリに最適な認証方法です。 - 既存のBoxアカウントを持っているユーザーと連携する - ユーザーがBoxを使用していることを認識できるように、ID管理にBoxを使用する - アプリケーションのサービスアカウントではなく各ユーザーアカウント内にデータを保存する Python OAuth 2.0に関する有用なチュートリアルについては、[GitHub](https://github.com/box-community/box-python-oauth-template)を参照してください。 ## JSONウェブトークン (JWT) JSONウェブトークン (JWT) は、Box APIの最も一般的なサーバー側認証方法です。[JWT](g://authentication/jwt)はオープンスタンダードであり、堅牢なサーバー間認証を実現します。この方法は、Platformアプリのみに限定されており、エンドユーザーによる操作は必要ありません。適切な権限が付与されているアプリは、企業内の任意のユーザーの代理として操作できるため、強力でシームレスな統合が促進されます。管理者が承認すると、JWTアプリケーションには、デフォルトで、APIコールを行うサービスアカウントが割り当てられます。 # JWTはいつ使用すべきですか? JWTを使用するサーバー側認証は、以下に当てはまるアプリに最適な認証方法です。 - Boxアカウントを持たないユーザーと連携する - 独自のIDシステムを使用する - Boxを使用していることをユーザーに認識させたくない - ユーザーのアカウントではなくアプリケーションのサービスアカウント内にデータを保存する - 公開キーと秘密キーのペアを管理したい Node JWTに関する有用なチュートリアルについては、[Medium](https://medium.com/box-developer-japan-blog/jwt%E3%82%92%E4%BD%BF%E7%94%A8%E3%81%97%E3%81%9Fbox-node-js-sdk%E3%81%AE%E8%AA%8D%E8%A8%BC-e3496d610f59)を参照してください。 ## クライアント資格情報許可 (CCG) [クライアント資格情報許可](g://authentication/client-credentials)のアプローチは、サーバー認証に使用され、クライアントIDとシークレットを使用してアプリケーションのIDを検証します。これは、アクセストークンを取得する際にアプリケーションを識別するための安全な方法です。この方法は、ユーザーの関与なしにサーバー間でやり取りする必要があるシナリオで特に便利です。アプリケーションの構成に応じて、アプリケーションのサービスアカウントまたは管理対象ユーザーとして認証できます。管理者が承認すると、CCGアプリケーションには、デフォルトで、APIコールを行うサービスアカウントが割り当てられます。 # CCGを使用する場合 JWTを使用するサーバー側認証は、以下に当てはまるアプリに最適な認証方法です。 - Boxアカウントを持たないユーザーと連携する - 独自のIDシステムを使用する - Boxを使用していることをユーザーに認識させたくない - ユーザーのアカウントではなくアプリケーションのサービスアカウント内にデータを保存する - 公開キーと秘密キーのペアを管理したくない Python CCGに関する有用なチュートリアルについては、[Medium](https://medium.com/box-developer-japan-blog/box-python%E3%81%AE%E6%AC%A1%E4%B8%96%E4%BB%A3sdk-ccg%E3%81%AE%E4%BD%BF%E7%94%A8-1c7cff13c24d)を参照してください。 ## アプリトークン認証 [アプリトークン認証](g://authentication/app-token)はもう1つのサーバー側認証オプションで、アプリケーションのサービスアカウントに制限されている、有効期間の長い固定のアクセストークンを使用します。この方法は、Box Viewを利用しているアプリケーションに最適で、アプリにそれ自体のアカウントに対するデータの読み取りと書き込みのアクセス権限だけを必要とするシナリオ向けに設計されています。アプリトークン認証を使用すると、アプリケーションは関連付けられているサービスアカウントとして自動的に認証されるため、エンドユーザーによる承認は必要ありません。また、これはAPI[エンドポイント](g://authentication/app-token/endpoints)のサブセットに制限されます。 # アプリトークン認証を使用する場合 アプリトークンを使用するサーバー側認証は、以下に当てはまるアプリに最適な認証方法です。 - ユーザーモデルがない環境、またはBoxアカウントを持たないユーザーがいる環境で使用する - 独自のID管理システムを使用する - Boxを使用していることをユーザーに認識させたくない - ユーザーのアカウントではなくアプリケーションのサービスアカウント内にデータを保存する ## Box Skills [Box Skills](g://skills/handle/payload/#access-tokens)は、Boxにアップロードされたファイルのカスタマイズした処理に使用される独自の種類のアプリケーションです。サードパーティの機械学習サービスを使用してファイルから情報を抽出し、それをメタデータとして適用します。カスタムスキルの認証は、各スキルイベントに備わっている事前承認済みのAPI資格情報によって簡素化されていますが、APIアクセスには制限があります。カスタムスキルでは特定の認証タイプを選択する必要がなく、シンプルさとBoxの機能との直接統合に重点が置かれています。 # Box Skillsを使用する場合 Box Skillsを使用するWebhookベースの認証は、以下に当てはまるアプリに最適な認証方法です。 - サードパーティの機械学習環境で使用する - Boxを使用していることをできるだけユーザーに認識させたい - 他のプロセスと連携して最終目標を達成する - Box Skillをトリガーするファイルだけを処理する Box Skillsに関する有用なチュートリアル (英語) については、[Medium](https://medium.com/box-developer-blog/box-skills-ibm-watson-speech-to-text-tutorial-b7e3b3c0a8c7)を参照してください。 ## スコープ 開発者コンソールでアプリケーションが作成されると、ユーザーはアプリケーションのスコープを設定する必要があります。ユーザーにBox内のファイルやフォルダへのアクセス権限が付与されるしくみと同様、アプリケーションにも、BoxユーザーやBoxを使用する企業に代わって特定のアクションを実行するための独自の権限が付与されます。アプリケーションに対する権限セットの名前を「スコープ」と言います。つまり、アプリケーションのスコープにより、アプリケーションから呼び出すことのできる[エンドポイント](page://reference)が決まります。また、このスコープは、アプリケーションの[アクセストークン](g://authentication/tokens)が提供するアクセス権限に反映されます。 ### ユーザー権限とスコープ アクションを実行するための適切なスコープがアプリケーションに設定されている場合でも、アクセストークンと関連付けられた、呼び出しを実行するユーザーにはそのアクションを実行するための権限が必要であり、逆の場合も同様であることを理解することが重要です。 たとえば、ファイルを読み取るようにアプリケーションが設定されている場合、アクセスしようとするファイルの読み取り権限が認証済みユーザーにも必要です。 スコープ、トークンの権限、ユーザー権限がどのように連携しているかの詳細については、Boxの[セキュリティガイド](g://security)を参照してください。 次の手順 **Source:** [https://ja.developer.box.com/platform/authentication-methods/](https://ja.developer.box.com/platform/authentication-methods/) --- ### 開発の開始 **Type:** page | **Category:** Box Platformについて | **Section:** Box Platform 開発の開始 ここまでBox Platformのさまざまな構成要素について詳しく学んできました。これでいよいよ開発を開始できます。Box… # 開発の開始 ここまでBox Platformのさまざまな構成要素について詳しく学んできました。これでいよいよ開発を開始できます。[Box開発者コンソール](https://cloud.app.box.com/developers/console)にアクセスして着手しましょう。 その他のトピックをお探しの場合は、ぜひ以下を確認してください。 - [アーキテクチャパターン](page://platform/appendix/architecture-patterns): このページでは、よく目にするインフラストラクチャのパターンについて説明します。 - [ユーザーモデル](page://platform/appendix//user-models): このページでは、このシリーズで前述したユーザータイプの使用方法について説明します。 - [一般的な値の確認](page://platform/appendix/locating-values): このページでは、ユーザーIDなどの情報を確認する方法について説明します。 - [エラー](g://api-calls/permissions-and-errors/common-errors): このページでは、表示される可能性のあるすべてのエラーコードを列挙しています。 **Source:** [https://ja.developer.box.com/platform/start-creating/](https://ja.developer.box.com/platform/start-creating/) --- ## Developer Guides ### .NET SDK (Generated) のインストール **Type:** guide | **Category:** ツール | **Section:** Developer Guides .NET SDK (Generated) のインストール .NETプロジェクトでは、Box .NET SDKを使用してBox APIを呼び出すことができます。 このSDKは、.NET Framework 4.5以上および.NET Core 1.0以上の両方で利用できます。SDK… # .NET SDK (Generated) のインストール .NETプロジェクトでは、Box .NET SDKを使用してBox APIを呼び出すことができます。 このSDKは、.NET Framework 4.5以上および.NET Core 1.0以上の両方で利用できます。SDKのインストール方法は、使用しているフレームワークによって異なります。 GitHubで.NET SDKの詳細を確認する .NET Frameworkに.NET SDKをインストールするには、[Nuget](https://www.nuget.org/)パッケージマネージャを使用して以下のコマンドを実行します。 ``` PM> Install-Package Box.Sdk.Gen ``` **Source:** [https://ja.developer.box.com/guides/tooling/sdks/dotnet-gen/](https://ja.developer.box.com/guides/tooling/sdks/dotnet-gen/) --- ### .NET SDK (公式サポート終了) のインストール **Type:** guide | **Category:** ツール | **Section:** Developer Guides .NET SDK (公式サポート終了) のインストール .NETプロジェクトでは、Box .NET SDKを使用してBox APIを呼び出すことができます。 .NET SDK… # .NET SDK (公式サポート終了) のインストール .NETプロジェクトでは、Box .NET SDKを使用してBox APIを呼び出すことができます。 [.NET SDK](https://github.com/box/box-windows-sdk-v2)は、現在メンテナンスモードであり、まもなく公式サポートが終了する予定です。つまり、実装されるのは重要なセキュリティ更新プログラムとバグ修正のみになります。[自動生成された.NET SDK](https://github.com/box/box-dotnet-sdk-gen)を使用することをお勧めします。 このSDKは、.NET Framework 4.5以上および.NET Core 1.0以上の両方で利用できます。SDKのインストール方法は、使用しているフレームワークによって異なります。 GitHubで.NET SDKの詳細を確認する ## .NET Framework .NET Frameworkに.NET SDKをインストールするには、[Nuget](https://www.nuget.org/)パッケージマネージャを使用して以下のコマンドを実行します。 ``` PM> Install-Package Box.V2 ``` ## .NET Core .NET Coreフレームワークに.NET SDKをインストールするには、[Nuget](https://www.nuget.org/)パッケージマネージャを使用して以下のコマンドを実行します。 ``` PM> Install-Package Box.V2.Core ``` **Source:** [https://ja.developer.box.com/guides/tooling/sdks/dotnet/](https://ja.developer.box.com/guides/tooling/sdks/dotnet/) --- ### AI Studioエージェント **Type:** guide | **Category:** Box AI Studio | **Section:** Developer Guides AI Studioエージェント Box AI Studioは、Enterprise Advancedアカウントでのみ使用できます。 カスタムAIエージェントの作成、リスト取得、更新、削除を行います。 # AI Studioエージェント Box AI Studioは、Enterprise Advancedアカウントでのみ使用できます。 カスタムAIエージェントの作成、リスト取得、更新、削除を行います。 **Source:** [https://ja.developer.box.com/guides/ai-studio/ai-studio-agents/](https://ja.developer.box.com/guides/ai-studio/ai-studio-agents/) --- ### AI Studioの使い方 **Type:** guide | **Category:** Box AI Studio | **Section:** Developer Guides AI Studioの使い方 Box AI Studioは、Enterprise Advancedアカウントでのみ使用できます。 AI StudioでカスタムAIエージェントの作成を開始するには、Box AIスコープが有効になっているPlatform… # AI Studioの使い方 Box AI Studioは、Enterprise Advancedアカウントでのみ使用できます。 AI StudioでカスタムAIエージェントの作成を開始するには、Box AIスコープが有効になっているPlatformアプリケーションと、コールを認証するための開発者トークンが必要です。 ## Platformアプリケーションの作成 まず、コールの実行に使用するPlatformアプリケーションを作成する必要があります。アプリケーションを作成するには、[Platformアプリの作成](g://applications/app-types/platform-apps)に関するガイドに従ってください。 ## Box AI Studioの有効化 Box AI Studioを使用するには、Box管理者が管理コンソールで有効にしていることを確認してください。Box管理者は、[Box AI Studioの有効化とエージェントの管理](https://support.box.com/hc/en-us/articles/37228079461267-Enabling-Box-AI-Studio-and-Managing-Agents/#h_01JH9HAMP43YYN6VWM51QCK413)で必要な情報を確認できます。 Box AI APIを操作するには、アプリケーションに`ai.readwrite`[スコープ](g://api-calls/permissions-and-errors/scopes)を追加する必要があります。このスコープを追加する前に、Box管理者からBox AI APIへのアクセス権限が付与されていることを確認してください。アプリの構成設定で [**AIを管理する**] オプションが表示されていない場合は、管理者までお問い合わせください。 スコープを追加するには、以下の手順を実行します。 開発者コンソールで、目的のアプリケーションを開きます。 [**構成**] > [**必須のアクセススコープ**] > [**コンテンツ操作**] に移動します。 [**AIを管理する**] スコープを選択します。Box Platformでは、コールを実行すると自動的にこのスコープが含まれます。あるアプリのコラボレータとして追加されているのにBox AI APIにアクセスできない場合は、[**AIを管理する**] スコープのチェックボックスがオンになった状態で、グレー表示になっています。つまり、アプリの所有者のAIのスコープは有効になっていますが、この設定を変更することはできません。 [承認または有効化](g://authorization)のためにアプリを送信します。既存のアプリケーションに対してBox AI APIを有効にする場合は、アプリケーションを[再承認](g://authorization/custom-app-approval#re-authorization-on-changes)する必要があります。 ## 開発者トークンの生成 リクエストの送信時にアプリを認証するには、開発者トークンが必要です。 トークンを生成するには、以下の手順を実行します。 1. [**開発者コンソール**] > [**Platformアプリ**] に移動します。 2. 右側の**オプションメニュー**ボタン ([…]) をクリックします。 3. [**開発者トークンを生成**] を選択します。トークンが自動的に生成され、クリップボードに保存されます。 アプリを開いて、[**構成**] > [**開発者トークン**] に移動してトークンを生成することもできます。 開発者トークンの有効期限は1時間のみです。 詳細については、[開発者トークン](g://authentication/tokens/developer-tokens)を参照してください。トークンを生成したら、cURLや他のクライアント ([Postman](g://tooling/postman)など) で使用してコールを実行できます。 **Source:** [https://ja.developer.box.com/guides/ai-studio/getting-started-ai-studio/](https://ja.developer.box.com/guides/ai-studio/getting-started-ai-studio/) --- ### AIエージェントのデフォルト構成を取得する **Type:** guide | **Category:** Box AI | **Section:** Developer Guides AIエージェントのデフォルト構成を取得する GET /2.0/ai_agent_defaultエンドポイントを使用すると、AIサービスのデフォルト構成を取得できます。構成の詳細を取得したら、ai_agent… # AIエージェントのデフォルト構成を取得する `GET /2.0/ai_agent_default`エンドポイントを使用すると、AIサービスのデフォルト構成を取得できます。構成の詳細を取得したら、[`ai_agent`](g://box-ai/ai-agents/ai-agent-overrides)パラメータを使用して構成を上書きできます。 ## リクエストの送信 リクエストを送信するには、`GET /2.0/ai_agent_default`エンドポイントを使用します。 アプリを承認するための開発者トークンを生成済みであることを確認します。詳細については、[Box AIの使い方](g://box-ai/ai-tutorials/prerequisites)を参照してください。 ### パラメータ コールを実行するには、以下のパラメータを渡す必要があります。必須のパラメータは**太字**で示されています。 | パラメータ | 説明 | 例 | | --- | --- | --- | | language | 返されるエージェントの構成の言語コード。その言語がサポートされていない場合は、デフォルト構成が返されます。 | ja-JP | | mode | エージェントの構成にフィルタをかけるためのモード。値は、取得したい結果に応じて、ask、text_gen、extract、またはextract_structuredにします。 | ask | | model | 構成を取得する対象となるモデル。選択したモデルがサポートされていることを確認するには、モデルのリストを参照してください。 | azure__openai__gpt_4o_mini | ## レスポンス コールに対するレスポンスは、選択した`mode`パラメータ値によって異なる場合があります。 `mode`パラメータを`ask`に設定すると、レスポンスは次のようになります。 ``` { "type": "ai_agent_ask", "basic_text": { "model": "azure__openai__gpt_4o_mini", "system_message": "", "prompt_template": "prompt_template": "{user_question}Write it in an informal way.{content}" }, "num_tokens_for_completion": 6000, "llm_endpoint_params": { "temperature": 0, "top_p": 1, "frequency_penalty": 0, "presence_penalty": 1.5, "stop": "<|im_end|>", "type": "openai_params" } }, "long_text": { "model": "azure__openai__gpt_4o_mini", "system_message": "", "prompt_template": "prompt_template": "{user_question}Write it in an informal way.{content}" }, "num_tokens_for_completion": 6000, "llm_endpoint_params": { "temperature": 0, "top_p": 1, "frequency_penalty": 0, "presence_penalty": 1.5, "stop": "<|im_end|>", "type": "openai_params" }, "embeddings": { "model": "azure__openai__text_embedding_ada_002", "strategy": { "id": "basic", "num_tokens_per_chunk": 64 } } }, "basic_text_multi": { "model": "azure__openai__gpt_4o_mini", "system_message": "", "prompt_template": "Current date: {current_date}\n\nTEXT FROM DOCUMENTS STARTS\n{content}\nTEXT FROM DOCUMENTS ENDS\n\nHere is how I need help from you: {user_question}\n.", "num_tokens_for_completion": 6000, "llm_endpoint_params": { "temperature": 0, "top_p": 1, "frequency_penalty": 0, "presence_penalty": 1.5, "stop": "<|im_end|>", "type": "openai_params" } }, "long_text_multi": { "model": "azure__openai__gpt_4o_mini", "system_message": "Role and Goal: You are an assistant designed to analyze and answer a question based on provided snippets from multiple documents, which can include business-oriented documents like docs, presentations, PDFs, etc. The assistant will respond concisely, using only the information from the provided documents.\n\nConstraints: The assistant should avoid engaging in chatty or extensive conversational interactions and focus on providing direct answers. It should also avoid making assumptions or inferences not supported by the provided document snippets.\n\nGuidelines: When answering, the assistant should consider the file's name and path to assess relevance to the question. In cases of conflicting information from multiple documents, it should list the different answers with citations. For summarization or comparison tasks, it should concisely answer with the key points. It should also consider the current date to be the date given.\n\nPersonalization: The assistant's tone should be formal and to-the-point, suitable for handling business-related documents and queries.\n", "prompt_template": "Current date: {current_date}\n\nTEXT FROM DOCUMENTS STARTS\n{content}\nTEXT FROM DOCUMENTS ENDS\n\nHere is how I need help from you: {user_question}\n.", "num_tokens_for_completion": 6000, "llm_endpoint_params": { "temperature": 0, "top_p": 1, "frequency_penalty": 0, "presence_penalty": 1.5, "stop": "<|im_end|>", "type": "openai_params" }, "embeddings": { "model": "azure__openai__text_embedding_ada_002", "strategy": { "id": "basic", "num_tokens_per_chunk": 64 } } } } ``` `mode`パラメータを`text_gen`に設定すると、レスポンスは次のようになります。 ``` { "type": "ai_agent_text_gen", "basic_gen": { "model": "azure__openai__gpt_4o_mini", "system_message": "\nIf you need to know today's date to respond, it is {current_date}.\nThe user is working in a collaborative document creation editor called Box Notes.\nAssume that you are helping a business user create documents or to help the user revise existing text.\nYou can help the user in creating templates to be reused or update existing documents, you can respond with text that the user can use to place in the document that the user is editing.\nIf the user simply asks to \"improve\" the text, then simplify the language and remove jargon, unless the user specifies otherwise.\nDo not open with a preamble to the response, just respond.\n", "prompt_template": "{user_question}", "num_tokens_for_completion": 12000, "llm_endpoint_params": { "temperature": 0.1, "top_p": 1, "frequency_penalty": 0.75, "presence_penalty": 0.75, "stop": "<|im_end|>", "type": "openai_params" }, "embeddings": { "model": "azure__openai__text_embedding_ada_002", "strategy": { "id": "basic", "num_tokens_per_chunk": 64 } }, "content_template": "`````{content}`````" } } ``` `mode`パラメータを`extract`に設定すると、レスポンスは次のようになります。 ``` { "type": "ai_agent_extract", "basic_text": { "model": "google__gemini_1_5_flash_001", "system_message": "Respond only in valid json. You are extracting metadata that is name, value pairs from a document. Only output the metadata in valid json form, as {\"name1\":\"value1\",\"name2\":\"value2\"} and nothing else. You will be given the document data and the schema for the metadata, that defines the name, description and type of each of the fields you will be extracting. Schema is of the form {\"fields\": [{\"key\": \"key_name\", \"displayName\": \"key display name\", \"type\": \"string\", \"description\": \"key description\"}]}. Leverage key description and key display name to identify where the key and value pairs are in the document. In certain cases, key description can also indicate the instructions to perform on the document to obtain the value. Prompt will be in the form of Schema is ``schema`` \n document is````document````", "prompt_template": "If you need to know today's date to respond, it is {current_date}. Schema is ``{user_question}`` \n document is````{content}````", "num_tokens_for_completion": 4096, "llm_endpoint_params": { "temperature": 0, "top_p": 1, "top_k": null, "type": "google_params" } }, "long_text": { "model": "google__gemini_1_5_flash_001", "system_message": "Respond only in valid json. You are extracting metadata that is name, value pairs from a document. Only output the metadata in valid json form, as {\"name1\":\"value1\",\"name2\":\"value2\"} and nothing else. You will be given the document data and the schema for the metadata, that defines the name, description and type of each of the fields you will be extracting. Schema is of the form {\"fields\": [{\"key\": \"key_name\", \"displayName\": \"key display name\", \"type\": \"string\", \"description\": \"key description\"}]}. Leverage key description and key display name to identify where the key and value pairs are in the document. In certain cases, key description can also indicate the instructions to perform on the document to obtain the value. Prompt will be in the form of Schema is ``schema`` \n document is````document````", "prompt_template": "If you need to know today's date to respond, it is {current_date}. Schema is ``{user_question}`` \n document is````{content}````", "num_tokens_for_completion": 4096, "llm_endpoint_params": { "temperature": 0, "top_p": 1, "top_k": null, "type": "google_params" }, "embeddings": { "model": "azure__openai__text_embedding_ada_002", "strategy": { "id": "basic", "num_tokens_per_chunk": 64 } } } } ``` `mode`パラメータを`extract_structured`に設定すると、レスポンスは次のようになります。 ``` { "type": "ai_agent_extract_structured", "basic_text": { "model": "google__gemini_1_5_flash_001", "system_message": "Respond only in valid json. You are extracting metadata that is name, value pairs from a document. Only output the metadata in valid json form, as {\"name1\":\"value1\",\"name2\":\"value2\"} and nothing else. You will be given the document data and the schema for the metadata, that defines the name, description and type of each of the fields you will be extracting. Schema is of the form {\"fields\": [{\"key\": \"key_name\", \"prompt\": \"prompt to extract the value\", \"type\": \"date\"}]}. Leverage prompt for each key to identify where the key and value pairs are in the document. In certain cases, prompt can also indicate the instructions to perform on the document to obtain the value. Prompt will be in the form of Schema is ``schema`` \n document is````document````", "prompt_template": "If you need to know today's date to respond, it is {current_date}. Schema is ``{user_question}`` \n document is````{content}````", "num_tokens_for_completion": 4096, "llm_endpoint_params": { "temperature": 0, "top_p": 1, "top_k": null, "type": "google_params" } }, "long_text": { "model": "google__gemini_1_5_flash_001", "system_message": "Respond only in valid json. You are extracting metadata that is name, value pairs from a document. Only output the metadata in valid json form, as {\"name1\":\"value1\",\"name2\":\"value2\"} and nothing else. You will be given the document data and the schema for the metadata, that defines the name, description and type of each of the fields you will be extracting. Schema is of the form {\"fields\": [{\"key\": \"key_name\", \"prompt\": \"prompt to extract the value\", \"type\": \"date\"}]}. Leverage prompt for each key to identify where the key and value pairs are in the document. In certain cases, prompt can also indicate the instructions to perform on the document to obtain the value. Prompt will be in the form of Schema is ``schema`` \n document is````document````", "prompt_template": "If you need to know today's date to respond, it is {current_date}. Schema is ``{user_question}`` \n document is````{content}````", "num_tokens_for_completion": 4096, "llm_endpoint_params": { "temperature": 0, "top_p": 1, "top_k": null, "type": "google_params" }, "embeddings": { "model": "google__textembedding_gecko_003", "strategy": { "id": "basic", "num_tokens_per_chunk": 64 } } } } ``` **Source:** [https://ja.developer.box.com/guides/box-ai/ai-agents/get-agent-default-config/](https://ja.developer.box.com/guides/box-ai/ai-agents/get-agent-default-config/) --- ### AIエージェントの削除 **Type:** guide | **Category:** Box AI Studio | **Section:** Developer Guides AIエージェントの削除 DELETE /2.0/ai_agents/{id}エンドポイントを使用すると、IDに基づいてカスタムAIエージェントを削除できます。 リクエストの送信 リクエストを送信するには、DELETE /2.0/ai_agents/{id… # AIエージェントの削除 `DELETE /2.0/ai_agents/{id}`エンドポイントを使用すると、IDに基づいてカスタムAIエージェントを削除できます。 ## リクエストの送信 リクエストを送信するには、`DELETE /2.0/ai_agents/{id}`エンドポイントを使用します。 ### パラメータ コールを実行するには、以下のパラメータを渡す必要があります。必須のパラメータは**太字**で示されています。 | パラメータ | 説明 | 例 | | --- | --- | --- | | agent_id | 削除するエージェントのID。 | 1234 | **Source:** [https://ja.developer.box.com/guides/ai-studio/ai-studio-agents/delete-agents/](https://ja.developer.box.com/guides/ai-studio/ai-studio-agents/delete-agents/) --- ### AIエージェントの更新 **Type:** guide | **Category:** Box AI Studio | **Section:** Developer Guides AIエージェントの更新 PUT /2.0/ai_agents/{id}エンドポイントを使用すると、IDに基づいてカスタムAIエージェントを更新できます。 リクエストの送信 リクエストを送信するには、PUT /2.0/ai_agents/{id… # AIエージェントの更新 `PUT /2.0/ai_agents/{id}`エンドポイントを使用すると、IDに基づいてカスタムAIエージェントを更新できます。 ## リクエストの送信 リクエストを送信するには、`PUT /2.0/ai_agents/{id}`エンドポイントを使用します。 ### パラメータ コールを実行するには、以下のパラメータを渡す必要があります。必須のパラメータは**太字**で示されています。 | パラメータ | 説明 | 例 | | --- | --- | --- | | type | クエリの処理に使用されるエージェントのタイプ。 | ```` | | name | AIエージェントの名前。 | マイAIエージェント | | access_state | AIエージェントの状態。値はenabled、disabledのいずれかです。 | enabled | | icon_reference | AIエージェントのアイコン参照。これは、URL https://cdn01.boxcdn.net/app-assets/aistudio/avatars/<file_name>の形式で指定する必要があります。この場合、file_nameに使用可能な値はlogo_boxAi.png、logo_stamp.png、logo_legal.png、logo_finance.png、logo_config.png、logo_handshake.png、logo_analytics.png、logo_classification.pngです。 | https://cdn01.boxcdn.net/app-assets/aistudio/avatars/logo_analytics.svg | | allowed_entities | 許可するユーザーまたはグループのリスト。 | | | ask | 質問に使用されるAIエージェント。 | ask | | extract | 抽出に使用されるAIエージェント。 | | | text_gen | テキストの生成に使用されるAIエージェント。 | | **Source:** [https://ja.developer.box.com/guides/ai-studio/ai-studio-agents/update-agents/](https://ja.developer.box.com/guides/ai-studio/ai-studio-agents/update-agents/) --- ### AIエージェントの構成のバージョン管理 **Type:** guide | **Category:** Box AI | **Section:** Developer Guides AIエージェントの構成のバージョン管理 Boxでは、常に最先端のオプションに対応するため、定期的にデフォルトモデルをエンドポイント全体で更新しています。デフォルトモデルが更新されると、開発者向け変更ログに掲載されます。 AIエージェントの構成のバージョン管理により、開発者はAI… # AIエージェントの構成のバージョン管理 Boxでは、常に最先端のオプションに対応するため、定期的にデフォルトモデルをエンドポイント全体で更新しています。デフォルトモデルが更新されると、開発者向け変更ログに掲載されます。 AIエージェントの構成のバージョン管理により、開発者はAIエージェントのバージョン管理をより詳細に制御できるようになり、レスポンスの一貫性が確保されます。 AIエージェントの構成のバージョン管理には、以下の原則が採用されています。 - 各AIエージェントのスナップショットは、Box側では制御できない要因がない限り、少なくとも12か月間サポートされます。この要因には、大規模言語モデル (LLM) の廃止などがあります。 - AIエージェントのスナップショットは、安定したエージェントバージョンが新しくリリースされない限り、使用できます。 - 新しいスナップショットをテストして移行するために、6か月の猶予期間が設けられています。 ## AIエージェントの構成の履歴 LLMゲートウェイで使用される[デフォルトのエージェント構成](g://box-ai/ai-agents/get-agent-default-config)の値は、可能な限り高品質の回答を得られるように変更されることがよくあります。 使用中の構成への悪影響を避けるために、以下に示すAIエージェントの構成の履歴を使用して[デフォルト構成を上書きする](g://box-ai/ai-agents/ai-agent-overrides)ことができます。 ``` { "ask": { "type": "ai_agent_ask", "longText": { "model": "azure__openai__gpt_4o_mini", "systemMessage": "", "promptTemplate": "Reply as if it's {current_date}.\nI will ask you for help and provide subsections of one document delimited by five backticks (`````) at the beginning and at the end.\nIf I make a reference to \"this\", I am referring to the document I provided between the five backticks. I may ask you a question where the answer is contained within the document. In that case, do your best to answer using only the document, but if you cannot, feel free to mention that you couldn't find an answer in the document, but you have some answer from your general knowledge.\nI may ask you to perform some kind of computation or symbol manipulation such as filtering a list, counting something, summing, averaging, and other aggregation/grouping functions or some combination of them. In these cases, first list the plan of how you plan to perform such a computation, then follow that plan step by step, keeping track of intermediate results, and at the end tell me the final answer.\nI may ask you to enumerate or somehow list people, places, characters, or other important things from the document, if I do so, please only use the document provided to list them.\nTEXT FROM DOCUMENT STARTS\n`````\n{content}\n `````\nTEXT FROM DOCUMENT ENDS\nNever mention five backticks in your response. Unless you are told otherwise, a one paragraph response is sufficient for any requested summarization tasks.\nHere is how I need help from you: {user_question}", "numTokensForCompletion": 6000, "llmEndpointParams": { "type": "openai_params", "temperature": 0.0, "topP": 1.0, "frequencyPenalty": 0.0, "presencePenalty": 1.5, "stop": "<|im_end|> " }, "embeddings": { "model": "azure__openai__text_embedding_ada_002", "strategy": { "id": "basic", "numTokensPerChunk": 64 } } }, "basicText": { "model": "azure__openai__gpt_4o_mini", "systemMessage": "", "promptTemplate": "Reply as if it's {current_date}.\nI will ask you for help and provide the entire text of one document delimited by five backticks (`````) at the beginning and at the end.\nIf I make a reference to \"this\", I am referring to the document I provided between the five backticks. I may ask you a question where the answer is contained within the document. In that case, do your best to answer using only the document, but if you cannot, feel free to mention that you couldn't find an answer in the document, but you have some answer from your general knowledge.\nI may ask you to perform some kind of computation or symbol manipulation such as filtering a list, counting something, summing, averaging, and other aggregation/grouping functions or some combination of them. In these cases, first list the plan of how you plan to perform such a computation, then follow that plan step by step, keeping track of intermediate results, and at the end tell me the final answer.\nI may ask you to enumerate or somehow list people, places, characters, or other important things from the document, if I do so, please only use the document provided to list them.\nTEXT FROM DOCUMENT STARTS\n `````\n{content}\n`````\nTEXT FROM DOCUMENT ENDS\nNever mention five backticks in your response. Unless you are told otherwise, a one paragraph response is sufficient for any requested summarization tasks.\nHere is how I need help from you: {user_question}", "numTokensForCompletion": 6000, "llmEndpointParams": { "type": "openai_params", "temperature": 0.0, "topP": 1.0, "frequencyPenalty": 0.0, "presencePenalty": 1.5, "stop": "<|im_end|>" } }, "longTextMulti": { "model": "azure__openai__gpt_4o_mini", "systemMessage": "Role and Goal: You are an assistant designed to analyze and answer a question based on provided snippets from multiple documents, which can include business-oriented documents like docs, presentations, PDFs, etc. The assistant will respond concisely, using only the information from the provided documents.\n\nConstraints: The assistant should avoid engaging in chatty or extensive conversational interactions and focus on providing direct answers. It should also avoid making assumptions or inferences not supported by the provided document snippets.\n\nGuidelines: When answering, the assistant should consider the file's name and path to assess relevance to the question. In cases of conflicting information from multiple documents, it should list the different answers with citations. For summarization or comparison tasks, it should concisely answer with the key points. It should also consider the current date to be the date given.\n\nPersonalization: The assistant's tone should be formal and to-the-point, suitable for handling business-related documents and queries.\n", "promptTemplate": "Current date: {current_date}\n\nTEXT FROM DOCUMENTS STARTS\n{content}\nTEXT FROM DOCUMENTS ENDS\n\nHere is how I need help from you: {user_question}\n.", "numTokensForCompletion": 6000, "llmEndpointParams": { "type": "openai_params", "temperature": 0.0, "topP": 1.0, "frequencyPenalty": 0.0, "presencePenalty": 1.5, "stop": "<|im_end|>" }, "embeddings": { "model": "azure__openai__text_embedding_ada_002", "strategy": { "id": "basic", "numTokensPerChunk": 64 } } }, "basicTextMulti": { "model": "azure__openai__gpt_4o_mini", "systemMessage": "", "promptTemplate": "Current date: {current_date}\n\nTEXT FROM DOCUMENTS STARTS\n{content}\nTEXT FROM DOCUMENTS ENDS\n\nHere is how I need help from you: {user_question}\n.", "numTokensForCompletion": 6000, "llmEndpointParams": { "type": "openai_params", "temperature": 0.0, "topP": 1.0, "frequencyPenalty": 0.0, "presencePenalty": 1.5, "stop": "<|im_end|>" } }, }, "extract": { "type": "ai_agent_extract", "longText": { "model": "google__gemini_1_5_flash_001", "systemMessage": "Respond only in valid json. You are extracting metadata that is name, value pairs from a document. Only output the metadata in valid json form, as {\"name1\":\"value1\",\"name2\":\"value2\"} and nothing else. You will be given the document data and the schema for the metadata, that defines the name, description and type of each of the fields you will be extracting. Schema is of the form {\"fields\": [{\"key\": \"key_name\", \"displayName\": \"key display name\", \"type\": \"string\", \"description\": \"key description\"}]}. Leverage key description and key display name to identify where the key and value pairs are in the document. In certain cases, key description can also indicate the instructions to perform on the document to obtain the value. Prompt will be in the form of Schema is ``schema`` \n document is````document````", "promptTemplate": "If you need to know today's date to respond, it is {current_date}. Schema is ``{user_question}`` \n document is````{content}````", "numTokensForCompletion": 4096, "llmEndpointParams": { "type": "google_params", "temperature": 0.0, "topP": 1.0, "frequencyPenalty": 0.0, "presencePenalty": 0.0 }, "embeddings": { "model": "azure__openai__text_embedding_ada_002", "strategy": { "id": "basic", "numTokensPerChunk": 64 } } }, "basicText": { "model": "google__gemini_1_5_flash_001", "systemMessage": "Respond only in valid json. You are extracting metadata that is name, value pairs from a document. Only output the metadata in valid json form, as {\"name1\":\"value1\",\"name2\":\"value2\"} and nothing else. You will be given the document data and the schema for the metadata, that defines the name, description and type of each of the fields you will be extracting. Schema is of the form {\"fields\": [{\"key\": \"key_name\", \"displayName\": \"key display name\", \"type\": \"string\", \"description\": \"key description\"}]}. Leverage key description and key display name to identify where the key and value pairs are in the document. In certain cases, key description can also indicate the instructions to perform on the document to obtain the value. Prompt will be in the form of Schema is ``schema`` \n document is````document````", "promptTemplate": "If you need to know today's date to respond, it is {current_date}. Schema is ``{user_question}`` \n document is````{content}````", "numTokensForCompletion": 4096, "llmEndpointParams": { "type": "google_params", "temperature": 0.0, "topP": 1.0, "frequencyPenalty": 0.0, "presencePenalty": 0.0 } } }, "textGen": { "type": "ai_agent_text_gen", "basicGen": { "model": "azure__openai__gpt_4o_mini", "systemMessage": "\nIf you need to know today's date to respond, it is {current_date}.\nThe user is working in a collaborative document creation editor called Box Notes.\nAssume that you are helping a business user create documents or to help the user revise existing text.\nYou can help the user in creating templates to be reused or update existing documents, you can respond with text that the user can use to place in the document that the user is editing.\nIf the user simply asks to \"improve\" the text, then simplify the language and remove jargon, unless the user specifies otherwise.\nDo not open with a preamble to the response, just respond.\n", "promptTemplate": "{user_question}", "numTokensForCompletion": 12000, "llmEndpointParams": { "type": "openai_params", "temperature": 0.1, "topP": 1.0, "frequencyPenalty": 0.75, "presencePenalty": 0.75, "stop": "<|im_end|>" }, "embeddings": { "model": "azure__openai__text_embedding_ada_002", "strategy": { "id": "basic", "numTokensPerChunk": 64 } }, "contentTemplate": "`````{content}`````" } }, "extractStructured": { "type": "ai_agent_extract_structured", "longText": { "model": "google__gemini_1_5_flash_001", "systemMessage": "Respond only in valid json. You are extracting metadata that is name, value pairs from a document. Only output the metadata in valid json form, as {\"name1\":\"value1\",\"name2\":\"value2\"} and nothing else. You will be given the document data and the schema for the metadata, that defines the name, description and type of each of the fields you will be extracting. Schema is of the form {\"fields\": [{\"key\": \"key_name\", \"prompt\": \"prompt to extract the value\", \"type\": \"date\"}]}. Leverage prompt for each key to identify where the key and value pairs are in the document. In certain cases, prompt can also indicate the instructions to perform on the document to obtain the value. Prompt will be in the form of Schema is ``schema`` \n document is````document````", "promptTemplate": "If you need to know today's date to respond, it is {current_date}. Schema is ``{user_question}`` \n document is````{content}````", "numTokensForCompletion": 4096, "llmEndpointParams": { "type": "google_params", "temperature": 0.0, "topP": 1.0, "frequencyPenalty": 0.0, "presencePenalty": 0.0 }, "embeddings": { "model": "google__textembedding_gecko_003", "strategy": { "id": "basic", "numTokensPerChunk": 64 } } }, "basicText": { "model": "google__gemini_1_5_flash_001", "systemMessage": "Respond only in valid json. You are extracting metadata that is name, value pairs from a document. Only output the metadata in valid json form, as {\"name1\":\"value1\",\"name2\":\"value2\"} and nothing else. You will be given the document data and the schema for the metadata, that defines the name, description and type of each of the fields you will be extracting. Schema is of the form {\"fields\": [{\"key\": \"key_name\", \"prompt\": \"prompt to extract the value\", \"type\": \"date\"}]}. Leverage prompt for each key to identify where the key and value pairs are in the document. In certain cases, prompt can also indicate the instructions to perform on the document to obtain the value. Prompt will be in the form of Schema is ``schema`` \n document is````document````", "promptTemplate": "If you need to know today's date to respond, it is {current_date}. Schema is ``{user_question}`` \n document is````{content}````", "numTokensForCompletion": 4096, "llmEndpointParams": { "type": "google_params", "temperature": 0.0, "topP": 1.0, "frequencyPenalty": 0.0, "presencePenalty": 0.0 } } } } ``` **Source:** [https://ja.developer.box.com/guides/box-ai/ai-agents/ai-agent-versioning/](https://ja.developer.box.com/guides/box-ai/ai-agents/ai-agent-versioning/) --- ### AIモデルの上書き **Type:** guide | **Category:** Box AI | **Section:** Developer Guides AIモデルの上書き Boxでは、常に最先端のオプションに対応するため、定期的にデフォルトモデルをエンドポイント全体で更新しています。 Box AI… # AIモデルの上書き Boxでは、常に最先端のオプションに対応するため、定期的にデフォルトモデルをエンドポイント全体で更新しています。 Box AIに基づいた実装の場合、新しいデフォルトモデルによって、ダウンストリームプロセスを中断または変更するように結果が変更される可能性があります。特定のバージョンに切り替えることで、問題の発生を防止できる場合があります。 また、特定のモデルを選択すると、ユースケースに対してより適切な結果が得られる場合もあります。このような理由で、[サポートされているモデル](g://box-ai/ai-models)のリストに含まれる任意のモデルに切り替えることが可能です。 モデルの切り替えとは別に、オプションを渡すことで、Box AIの実装で使用されるエージェントをさらにカスタマイズし、ユースケースに合ったレスポンスを取得することもできます。 具体的なユースケースを確認するには、[上書きに関するチュートリアル](g://box-ai/ai-agents/ai-agent-overrides)を参照してください。 **Source:** [https://ja.developer.box.com/guides/box-ai/ai-agents/](https://ja.developer.box.com/guides/box-ai/ai-agents/) --- ### AIモデルの構成の上書き **Type:** guide | **Category:** Box AI | **Section:** Developer Guides AIモデルの構成の上書き 開始する前に Platformアプリを作成して認証するには、Box AI… # AIモデルの構成の上書き ## 開始する前に Platformアプリを作成して認証するには、[Box AIの使い方](g://box-ai/ai-tutorials/prerequisites)に記載されている手順に従っていることを確認してください。さらにコンテキストを取得するには、[エージェントの上書き](g://box-ai/ai-agents/ai-agent-overrides)を参照してください。 ## 上書き用のプロンプト この例では、`prompt_template`パラメータを使用してクエリの結果を変更する方法を示します。最初の手順として、Box AIに対し、Box AI for Documentsに関するドキュメントの要約を依頼します。指定されているドキュメントは1つだけなので、`mode`パラメータは`single_item_qa`に設定されています。 ``` curl -i -L POST "https://api.box.com/2.0/ai/ask" \ -H "content-type: application/json" \ -H "authorization: <Bearer TOKEN>" \ -d '{ "mode": "single_item_qa", "prompt": "Summarize this article about Box AI for Documents", "items": [ { "type": "file", "id": "123467890" } ] }' ``` 次のようなレスポンスが返されます。 ``` { "answer": "Box AI for Documents is a tool that enhances document analysis by allowing users to summarize content, identify key points, and draft outlines directly from files in Box. It supports various file types, including text documents, spreadsheets, and presentation slides. Users can initiate interactions with Box AI through the web app, where they can select suggestions or type specific questions. Responses are generated in real time, and users have options to save or clear chat history. The document also provides guidelines for effective inquiries and troubleshooting tips for potential issues with using Box AI.", "created_at": "2024-10-08T00:29:07.283-07:00", "completion_reason": "done" } ``` 結果をさらに改善するには、`prompt_template`パラメータを使用して、Box AIに対する指示をさらに追加できます。この例では、レスポンスの語調を変更しましょう。 ``` { "prompt": "Summarize this article about Box AI for Documents", "mode": "single_item_qa", "items": [ { "id": "123467890", "type": "file" } ], "ai_agent": { "type": "ai_agent_ask", "basic_text": { "prompt_template": "prompt_template": "{user_question} Write the summary in an informal way.{content}" }, } } } ``` レスポンスは若干砕けた表現になります。 ``` { "answer": "Box AI for Documents is a tool that helps you analyze and gain insights from your documents in Box. You can use it to summarize content, identify key points, and draft outlines, making it easier to handle meeting notes, reports, and marketing materials. To get started, just open a file in the Box web app and click the Box AI button. It offers quick suggestions like summarizing the document or checking for next steps. Responses are generated in real time, and you can save them or clear chat history as needed. Just remember, Box AI only pulls info from the document you're viewing, so be specific with your questions!", "created_at": "2024-10-08T00:38:01.767-07:00", "completion_reason": "done" } ``` ## AIモデルの上書き (テキスト生成) この例では、`ai_agent`のオプションでAIモデルを変更した場合にテキストの生成方法にどのような影響があるかを示します。 最初に、`POST ai/text_gen`エンドポイントを使用してテキストを生成しましょう。このエンドポイントは、デフォルトで、OpenAI 3.5 turboモデルを使用しています。 ``` curl -i -L POST "https://api.box.com/2.0/ai/text_gen" \ -H "content-type: application/json" \ -H "authorization: Bearer TOKEN" \ -d '{ "prompt": "Write a short post about Box AI for documents.Make it highlight the benefits of the solution. You can add some emoticons.", "items": [ { "id": "123467890", "type": "file" } ] } ``` レスポンスは次のようになります。 ``` { "answer": "🌟 Exciting News! 🌟\n\nIntroducing Box AI for documents - your new best friend in creating smarter, more efficient content! 🤖💡\n\n🔹 Say goodbye to manual searching and organizing - Box AI does it all for you!\n🔹 Enjoy lightning-fast document analysis and categorization.\n🔹 Boost productivity with automated suggestions and smart recommendations.\n🔹 Collaborate seamlessly with real-time insights and intelligent tagging.\n\nExperience the future of document creation with Box AI - making work easier, faster, and more fun! 🚀💻 #BoxAI #SmartDocuments", "created_at": "2024-10-08T01:19:06.22-07:00", "completion_reason": "done" } ``` `ai_agent`構成を使用してモデルを変更しましょう。 ``` curl -i -L POST "https://api.box.com/2.0/ai/text_gen" \ -H "content-type: application/json" \ -H "authorization: Bearer TOKEN" \ -d '{ "prompt": "Write a short post about Box AI for documents.Make it highlight the benefits of the solution. You can add some emoticons.", "items": [ { "id": "123467890", "type": "file" } ], "ai_agent": { "type": "ai_agent_text_gen", "basic_gen": { "model": "openai__gpt_4o_2024_05_13" } } } ``` モデルを切り替えた後は、レスポンスが若干異なります。 ``` { "answer": "🚀 **Boost Your Productivity with Box AI for Documents!** 📄✨\n\nSay goodbye to tedious document creation and editing! With Box AI, you can streamline your workflow and focus on what truly matters. Here’s why you’ll love it:\n\n1. **Smart Suggestions** 🤖: Get real-time recommendations to enhance your content.\n2. **Automated Formatting** 📝: Ensure consistency across all your documents effortlessly.\n3. **Collaboration Made Easy** 👥: Work seamlessly with your team, no matter where they are.\n4. **Time-Saving Templates** ⏳: Use pre-built templates to speed up document creation.\n5. **Enhanced Accuracy** ✅: Reduce errors with intelligent proofreading.\n\nTransform the way you work with documents and experience a new level of efficiency with Box AI! 🌟", "created_at": "2024-10-08T01:28:36.777-07:00", "completion_reason": "done" } ``` ご覧のとおり、ある程度異なったレスポンスになったことがわかります。モデルの切り替えにより、Box AIに対する操作を最適化し、ニーズに最適なモデルを選択できます。 ## AIモデルの上書き (メタデータ抽出) モデルを切り替えると、メタデータ抽出の結果も異なる場合があります。契約書のサンプルを使用して、メタデータを抽出しましょう。この例で使用されているモデルはGoogle Geminiです。 ``` curl -i -L 'https://api.box.com/2.0/ai/extract' \ -H 'content-type: application/json' \ -H 'authorization: Bearer TOKEN' \ -d '{ "prompt": "Extract any data that would be good metadata to save for future contracts.", "items": [ { "type": "file", "id": "123456789" } ] }' ``` レスポンスは一連のメタデータになります。 ``` { "answer": "{\"Buyer Legal Entity Name\": \"Acme Retail Corp.\", \"Supplier Legal Entity Name\": \"Acme Manufacturing Inc.\", \"Buyer Contact Person\": \"Jane Doe\", \"Supplier Contact Person\": \"Eva Smith\", \"Payment Term\": \"payment in full before pickup of goods\", \"Invoice Currency\": \"Euro\", \"Incoterm\": \"FCA Amsterdam\", \"Governing Law\": \"laws state jurisdiction in which supplier is located\", \"Effective Date\": \"March 27, 2024\", \"Buyer Signature Date\": \"March 28th, 2024\", \"Supplier Signature Date\": \"March 28th, 2024\"}", "created_at": "2024-10-08T01:53:14.993-07:00", "completion_reason": "done" } ``` モデルを最新のOpenAIオプションに変更しましょう。 ``` curl -i -L 'https://api.box.com/2.0/ai/extract' \ -H 'content-type: application/json' \ -H 'authorization: Bearer TOKEN' \ -d '{ "prompt": "Extract any data that would be good metadata to save for future contracts.", "items": [ { "type": "file", "id": "123456789" } ], "ai_agent": { "type": "ai_agent_extract", "basic_text": { "model": "openai__gpt_4o_2024_05_13" } } }' ``` このモデルを使用すると、結果として、レスポンスにはさらに多くのメタデータエントリが列挙されます。 ``` { "answer": "{\"Effective Date\": \"March 27, 2024\", \"Supplier Legal Entity Name\": \"Acme Manufacturing Inc.\", \"Supplier Registered Office Address\": \"123 Main Street\", \"Supplier Contact Person(s)\": \"Eva Smith\", \"Buyer Legal Entity Name\": \"Acme Retail Corp.\", \"Buyer Registered Office Address\": \"456 Market Avenue\", \"Buyer Contact Person(s)\": \"Jane Doe\", \"Incoterm\": \"FCA Amsterdam\", \"Payment Term\": \"payment in full before pickup of goods\", \"Invoice Currency\": \"Euro\", \"Buyer Printed Name\": \"Jane Doe\", \"Buyer Date\": \"March 28th, 2024\", \"Buyer Title / Position\": \"CEO\", \"Seller Printed Name\": \"Eve Smith\", \"Seller Date\": \"March 28th, 2024\", \"Seller Title / Position\": \"Sales Manager\"}", "created_at": "2024-10-08T01:54:28.099-07:00", "completion_reason": "done" } ``` **Source:** [https://ja.developer.box.com/guides/box-ai/ai-tutorials/default-agent-overrides/](https://ja.developer.box.com/guides/box-ai/ai-tutorials/default-agent-overrides/) --- ### AIモデルの構成の上書き **Type:** guide | **Category:** Box AI | **Section:** Developer Guides AIモデルの構成の上書き ai_agent構成を使用すると、デフォルトのAIモデルの構成を上書きできます。これは、以下のエンドポイントで使用できます。 POST ai/ask POST ai/text_gen POST ai/extract POST ai/extract… # AIモデルの構成の上書き `ai_agent`構成を使用すると、デフォルトのAIモデルの構成を上書きできます。これは、以下のエンドポイントで使用できます。 - [`POST ai/ask`](e://post_ai_ask#param_ai_agent) - [`POST ai/text_gen`](e://post_ai_text_gen#param_ai_agent) - [`POST ai/extract`](e://post_ai_extract#param_ai_agent) - [`POST ai/extract_structured`](e://post_ai_extract_structured#param_ai_agent) デフォルト構成を取得するには、[`GET ai_agent_default`](e://get_ai_agent_default)エンドポイントを使用してください。 上書きの例を以下に示します。 - 組織のニーズに基づいて、デフォルトのAIモデルをカスタムのAIモデルに置き換える。 - ベースとなる`prompt`を微調整し、よりカスタマイズされたユーザーエクスペリエンスを実現する。 - `temperature`などのパラメータを変更して、結果の創造性を調整する。 ## 構成のサンプル `ai/ask`の場合の構成全体は以下のとおりです。 ``` { "type": "ai_agent_ask", "basic_text": { "llm_endpoint_params": { "type": "openai_params", "frequency_penalty": 1.5, "presence_penalty": 1.5, "stop": "<|im_end|>", "temperature": 0, "top_p": 1 }, "model": "azure__openai__gpt_4o_mini", "num_tokens_for_completion": 8400, "prompt_template": "It is `{current_date}`, consider these travel options `{content}` and answer the `{user_question}`.", "system_message": "You are a helpful travel assistant specialized in budget travel" }, "basic_text_multi": { "llm_endpoint_params": { "type": "openai_params", "frequency_penalty": 1.5, "presence_penalty": 1.5, "stop": "<|im_end|>", "temperature": 0, "top_p": 1 }, "model": "azure__openai__gpt_4o_mini", "num_tokens_for_completion": 8400, "prompt_template": "It is `{current_date}`, consider these travel options `{content}` and answer the `{user_question}`.", "system_message": "You are a helpful travel assistant specialized in budget travel" }, "long_text": { "embeddings": { "model": "openai__text_embedding_ada_002", "strategy": { "id": "basic", "num_tokens_per_chunk": 64 } }, "llm_endpoint_params": { "type": "openai_params", "frequency_penalty": 1.5, "presence_penalty": 1.5, "stop": "<|im_end|>", "temperature": 0, "top_p": 1 }, "model": "azure__openai__gpt_4o_mini", "num_tokens_for_completion": 8400, "prompt_template": "It is `{current_date}`, consider these travel options `{content}` and answer the `{user_question}`.", "system_message": "You are a helpful travel assistant specialized in budget travel" }, "long_text_multi": { "embeddings": { "model": "openai__text_embedding_ada_002", "strategy": { "id": "basic", "num_tokens_per_chunk": 64 } }, "llm_endpoint_params": { "type": "openai_params", "frequency_penalty": 1.5, "presence_penalty": 1.5, "stop": "<|im_end|>", "temperature": 0, "top_p": 1 }, "model": "azure__openai__gpt_4o_mini", "num_tokens_for_completion": 8400, "prompt_template": "It is `{current_date}`, consider these travel options `{content}` and answer the `{user_question}`.", "system_message": "You are a helpful travel assistant specialized in budget travel" } } ``` ### パラメータセットの相違点 `ask`、`text_gen`、`extract`、`extract_structured`に使用できるパラメータのセットは、APIコールに応じて若干異なります。 `ask`エンドポイントのエージェント構成には、`basic_text`、`basic_text_multi`、`long_text`、`long_text_multi`パラメータが含まれます。これは、リクエストの対象となる項目を単一にするか複数にするかを指定するために使用する`mode`パラメータが原因です。`mode`として`multiple_item_qa`を選択した場合は、上書き用に`multi`パラメータも使用できます。 `text_gen`のエージェント構成には、テキストの生成に使用される`basic_gen`パラメータが含まれます。 ### LLMエンドポイントパラメータ `llm_endpoint_params`構成のオプションは、全体的なAIモデルが[Google](r://ai-llm-endpoint-params-google)ベースか、[OpenAI](r://ai-llm-endpoint-params-openai)ベースか、[AWS](r://ai-llm-endpoint-params-aws)ベースかによって異なります。 たとえば、どちらの`llm_endpoint_params`オブジェクトも`temperature`パラメータを受け入れますが、モデルによって結果が異なります。 GoogleモデルとAWSモデルの場合、[`temperature`](https://ai.google.dev/gemini-api/docs/models/generative-models#model-parameters)はレスポンス生成時のサンプリングに使用されます。レスポンス生成は`top-P`と`top-K`が適用された場合に発生します。temperatureは、トークン選択におけるランダム性の程度を制御します。 OpenAIモデルの場合、[`temperature`](https://community.openai.com/t/temperature-top-p-and-top-k-for-chatbot-responses/295542)は、値が0～2の間のサンプリングtemperatureとなります。0.8のような高い値を指定すると、出力がよりランダムになるのに対し、0.2のような低い値を指定すると、出力はより焦点を絞った、決定的なものになります。独自の構成を導入する場合は、`temperature`と`top_p`の両方ではなく、いずれかを使用してください。 ### システムメッセージ `system_message`パラメータの目的は、LLMがその役割と実行するべき内容を理解するのを支援することです。たとえば、旅行日程を処理するソリューションの場合は、次のようなシステムメッセージを追加できます。 ``` You are a travel agent aid. You are going to help support staff process large amounts of schedules, tickets, etc. ``` このメッセージは、送信するコンテンツとは別ですが、結果を改善できます。 ### 完了に必要なトークンの数 `num_tokens_for_completion`パラメータは、Box AIが返すことのできる[トークン](https://help.openai.com/en/articles/4936856-what-are-tokens-and-how-to-count-them)の数を表します。この数値は、使用されるモデルによって異なる場合があります。 **Source:** [https://ja.developer.box.com/guides/box-ai/ai-agents/ai-agent-overrides/](https://ja.developer.box.com/guides/box-ai/ai-agents/ai-agent-overrides/) --- ### Android **Type:** guide | **Category:** モバイル | **Section:** Developer Guides Android Box Android SDKは、Androidプロジェクト内からBox APIへのネイティブアクセスを提供します。 日本時間2023年6月1日をもって、Android SDKのサポートは終了しました。既存のAndroid SDK… # Android [Box Android SDK](https://github.com/box/box-android-sdk)は、Androidプロジェクト内からBox APIへのネイティブアクセスを提供します。 日本時間2023年6月1日をもって、Android SDKのサポートは終了しました。既存のAndroid SDKアプリケーションは影響なく引き続きご利用いただけますが、新機能、更新、バグ修正は提供されなくなります。 最新のAndroid機能を引き続きご利用いただくために、Java SDKを使用してAndroid版アプリを作成することをお勧めします。詳細については、[こちら](https://github.com/box/box-java-sdk/blob/main/doc/android.md)のドキュメントを参照してください。 **Source:** [https://ja.developer.box.com/guides/mobile/android/](https://ja.developer.box.com/guides/mobile/android/) --- ### Android SDKのインストール **Type:** guide | **Category:** モバイル | **Section:** Developer Guides Android SDKのインストール 日本時間2023年6月1日をもって、Android SDKのサポートは終了しました。既存のAndroid SDKアプリケーションは影響なく引き続きご利用いただけますが、新機能、更新、バグ修正は提供されなくなります。 最新のAndroid… # Android SDKのインストール 日本時間2023年6月1日をもって、Android SDKのサポートは終了しました。既存のAndroid SDKアプリケーションは影響なく引き続きご利用いただけますが、新機能、更新、バグ修正は提供されなくなります。 最新のAndroid機能を引き続きご利用いただくために、Java SDKを使用してAndroid版アプリを作成することをお勧めします。詳細については、[こちら](https://github.com/box/box-java-sdk/blob/main/doc/android.md)のドキュメントを参照してください。 Android SDKは、次のように、いくつかの方法で入手できます。 - MavenまたはGradle依存関係として追加する - ソースをプロジェクトに複製する - プリコンパイル済みJARの1つをダウンロードする ## Maven依存関係として追加 以下のMaven依存関係を追加します。 ``` <dependency> <groupId>com.box</groupId> <artifactId>box-android-sdk</artifactId> </dependency> ``` ## Gradle依存関係として追加 `build.gradle`ファイルに以下を追加します。 ``` dependencies { implementation 'com.box:box-android-sdk:4.2.3' } ``` ## ソースの複製 Box Android SDKのソースコードは、[GitHubにあるプロジェクト](https://github.com/box/box-android-sdk/tree/master/box-content-sdk)を複製またはダウンロードすることで入手できます。 ## プリコンパイル済みJARのダウンロード Android SDK用のプリコンパイル済みJARは、GitHubプロジェクトの[リリースに関するページ](https://github.com/box/box-android-sdk/releases)から入手できます。 プリコンパイル済みJARのいずれかが使用されている場合、Android SDKでは依存関係`minimal-json v0.9.1` (Mavenの場合は`com.eclipsesource.minimal-json:minimal-json:0.9.1`) も必要になります。 **Source:** [https://ja.developer.box.com/guides/mobile/android/install/](https://ja.developer.box.com/guides/mobile/android/install/) --- ### APIコール **Type:** guide | **Category:** APIコール | **Section:** Developer Guides APIコール Box APIは、可能であれば共通のHTTP標準に準拠するRESTful APIです。以下のガイドでは、開発者がこれらのAPIを使用する際に利用できる便利な機能と直面するよくある間違いに注目します。 API… # APIコール Box APIは、可能であれば共通のHTTP標準に準拠するRESTful APIです。以下のガイドでは、開発者がこれらのAPIを使用する際に利用できる便利な機能と直面するよくある間違いに注目します。 ## APIコールのインサイト 管理者と共同管理者は、アプリケーションごとにAPIコールの合計数に関する情報が表示される、Platformインサイトのダッシュボードにアクセスできます。 詳細については、[Platformインサイト](https://support.box.com/hc/en-us/articles/20738406915219-Platform-Insights)と[アプリケーション](g://applications)を参照してください。 **Source:** [https://ja.developer.box.com/guides/api-calls/](https://ja.developer.box.com/guides/api-calls/) --- ### APIコールの実行 **Type:** guide | **Category:** ツール | **Section:** Developer Guides APIコールの実行 Box PostmanコレクションがPostmanアプリに読み込まれたら、Postmanアプリがログインユーザーに代わってBox APIへのAPIコールを実行できるようになります。 APIコールを実行するには、Box Postman… # APIコールの実行 **Box Postmanコレクション**が**Postmanアプリ**に読み込まれたら、Postmanアプリがログインユーザーに代わって**Box API**へのAPIコールを実行できるようになります。 APIコールを実行するには、Box Postmanコレクションに有効な`access_token`環境変数が必要です。有効なアクセストークンを使用してPostmanアプリが設定されるように、[クイックスタート](g://tooling/postman/quick-start)ガイドに従うことをお勧めします。 ## APIリクエストの実行 APIリクエストを実行するには、Box Postmanコレクションから**リクエスト**を選択します。この例では、[**Folders (フォルダ)**] フォルダにある [**Get items in folder (フォルダ内の項目を取得)**] APIを使用します。 デフォルトでは、このAPIエンドポイントの`folder_id`は、すべてのユーザーのルートフォルダを表す`0`に設定されています。この値は、そのまま使用することも、調べたいフォルダのフォルダIDに設定することもできます。 次に、右上にある [**Send (送信)**] ボタンをクリックしてAPIリクエストを送信します。 このAPIコールはすぐに制御が戻り、画面の下半分にあるレスポンスの [**Body (本文)**] タブにフォルダ内の項目のリストが表示されます。 # 認証エラー この時点で、Postmanがリストではなくエラーを返す場合があります。これは多くの場合、**アクセストークン**の有効期限が切れていることを意味します。詳細については、[Postmanでのアクセストークンの更新](g://tooling/postman/refresh)に関するガイドを参照してください。 **Source:** [https://ja.developer.box.com/guides/tooling/postman/make-api-call/](https://ja.developer.box.com/guides/tooling/postman/make-api-call/) --- ### APIコールの実行 **Type:** quick-start | **Category:** モバイル | **Section:** Developer Guides APIコールの実行 BoxアプリケーションとiOSアプリケーションがBox iOS SDKを使用して作成、設定されたら、初めてのBox APIコールを実行できるようになります。 空のiOS… # APIコールの実行 BoxアプリケーションとiOSアプリケーションが**Box iOS SDK**を使用して作成、設定されたら、初めてのBox APIコールを実行できるようになります。 空のiOSアプリケーションを使用して、現在認証されているユーザーの名前を取得するためのリクエストをBoxに対してトリガーするボタンを作成します。 これらの例で使用されているブロックアクションを使用した場合、処理は遅くなります。本番アプリでは、これらのブロックアクションを適切なタスク委任アクションやブロック以外のアクションに置き換える必要があります。 ## ボタンの作成 XcodeのSwiftアプリケーション内で、`ContentView.swift`を読み込みます。ファイルの先頭に`ContentView`の`struct`が表示されます。その中には、アプリをエミュレータで実行した場合にiOSアプリケーションに出力される基本の文字列があります。 ``` import SwiftUI struct ContentView: View { var body: some View { Text("Hello, World!") } } ``` 最初に、現在のユーザーを取得するための呼び出しをトリガーできるように、`Text`の出力行をボタンに置き換えます。その行を以下のボタンに置き換えます。 ``` Button(action: { // Perform some action }) { Text("Click to get current user") } .padding(10) .cornerRadius(20) .foregroundColor(.white) .background(Color.blue) ``` 次の手順では、Boxからユーザーの詳細を取得するアクションをボタンに追加します。 ## APIコールのボタンアクションの追加 ユーザーがボタンをクリックしたときに、ユーザーの詳細が取得されるようにします。そのためには、**Box iOS SDK**のインポートを追加することと呼び出しを実行するボタンアクションを追加することという2つの処理が必要です。 `ContentView.swift`ファイルの先頭に、他のimportステートメントとともに`import BoxSDK`を追加します。 次に、現在はコメントのプレースホルダがあるボタンアクション内に、現在のユーザーを取得するためのiOS SDKへの呼び出しを追加します。APIコールが完了すると、開発者コンソールに認証メッセージが出力されます。実装を容易にするため、処理をブロックする`sleep(5)`コールを配置しています。これは、リクエストが完了するのに十分な時間をとることで、Box iOS SDKから呼び出しを実行できるかどうかをテストするためです。 `{{YOUR DEVELOPER TOKEN}}`を実際の開発者トークンに置き換えます。 ``` let client = BoxSDK.getClient(token: "{{YOUR DEVELOPER TOKEN}}") client.users.getCurrent(fields:["name", "login"]) { (result: Result<User, BoxSDKError>) in guard case let .success(user) = result else { print("Error getting user information") return } print("Authenticated as \(user.name)") } sleep(5) ``` iOSエミュレータでサンプルアプリケーションをビルドして実行します。 最後の手順で開発者トークンを作成してから1時間以上後にこのコードを実行する場合、開発者トークンは60分間しか保持されないため、[前の手順](g://mobile/ios/quick-start/configure-box-app)と同じ方法を使用して、開発者トークンを取り消して新たに生成する必要があります。 アプリケーションがエミュレータに読み込まれると、作成したボタンが表示されます。そのボタンをクリックしてAPIリクエストを開始します。 Xcodeの開発者コンソール内にAPIリクエストとレスポンスが表示されます。最後の行には、指定したユーザーのprintステートメントが表示されています。 ``` ◁ Status code: 200: no error ◁ Headers: ◁ Cache-Control, Value: no-cache, no-store ◁ BOX-REQUEST-ID, Value: 1c55151238444132eca16b4c2346d005 ◁ Transfer-Encoding, Value: Identity ◁ content-type, Value: application/json ◁ Connection, Value: keep-alive ◁ Strict-Transport-Security, Value: max-age=31536000 ◁ Body: {"type":"user","id":"123456789","name":"Test User","login":"testuser@test.com"} Authenticated as Optional("Test User") ``` Xcodeの開発者コンソールが表示されない場合は、メニューから [**View (表示)**] -> [**Debug Area (デバッグ領域)**] -> [**Activate Console (コンソールをアクティブ化)**] をクリックします。 これで、**Box iOS SDK**の設定が完了し、Box APIへの最初の呼び出しを実行できました。 ## まとめ - 空のiOSアプリケーションにボタンを追加しました。 - iOS SDKを使用して現在のユーザーを取得するリクエストを追加しました。 APIコールが完了しました **Source:** [https://ja.developer.box.com/guides/mobile/ios/quick-start/make-api-call/](https://ja.developer.box.com/guides/mobile/ios/quick-start/make-api-call/) --- ### APIコールの実行 **Type:** quick-start | **Category:** ツール | **Section:** Developer Guides APIコールの実行 Box PostmanコレクションがPostmanアプリにフォークされたため、Postmanアプリがログインユーザーに代わってBox APIへのAPIコールを実行できるようになりました。 はじめに: ブラウザのストレージをリセットする Box API… # APIコールの実行 **Box Postmanコレクション**が**Postmanアプリ**にフォークされたため、Postmanアプリがログインユーザーに代わって**Box API**へのAPIコールを実行できるようになりました。 ## はじめに: ブラウザのストレージをリセットする Box API資格情報をPostmanにインポートしたので、これらの資格情報をブラウザのストレージから削除することをお勧めします。 資格情報をクリア API資格情報をブラウザのストレージから削除すると、**クライアントID**、**クライアントシークレット**、**アクセストークン**、または**更新トークン**を他のスクリプトから読み取ることができなくなります。 ## 環境の選択 APIコールを実行する前に、APIコール時に使用する適切な**Postman環境**を選択することが重要です。 **Box Postmanコレクション**のインポート時には、使用すべき`Box` Postman環境も自動的にインポートされました。このコレクションは、この環境内の変数を自動的に認識してAPIコールに使用します。 Box Postman環境を選択するには、Postmanの右上にあるドロップダウンから [**Box**] を選択します。 ドロップダウンの右にある**目**のアイコンをクリックすると、その環境の詳細を確認できます。 ## APIリクエストの実行 APIリクエストを実行するには、Box Postmanコレクションから**リクエスト**を選択します。この例では、[**Folders (フォルダ)**] フォルダにある [**Get items in folder (フォルダ内の項目を取得)**] APIを使用します。 デフォルトでは、このAPIエンドポイントの`folder_id`は、すべてのユーザーのルートフォルダを表す`0`に設定されています。この値は、そのまま使用することも、調べたいフォルダのフォルダIDに設定することもできます。 次に、右上にある [**Send (送信)**] ボタンをクリックしてAPIリクエストを送信します。 このAPIコールはすぐに制御が戻り、画面の下半分にあるレスポンスの [**Body (本文)**] タブにフォルダ内の項目のリストが表示されます。 # 認証エラー この時点で、Postmanがリストではなくエラーを返す場合があります。これは多くの場合、**アクセストークン**の有効期限が切れていることを意味します。詳細については、[Postmanでのアクセストークンの更新](g://tooling/postman/refresh)に関するガイドを参照してください。 ## まとめ - BoxへのAPIコールに使用するPostman環境を選択しました - Boxへの最初のAPIコールを実行し、ユーザーのルートフォルダのフォルダ項目をリクエストしました APIコールが完了しました **Source:** [https://ja.developer.box.com/guides/tooling/postman/quick-start/make-api-call/](https://ja.developer.box.com/guides/tooling/postman/quick-start/make-api-call/) --- ### APIのバージョン戦略 **Type:** guide | **Category:** APIコール | **Section:** Developer Guides APIのバージョン戦略 Boxでは、特定のAPIエンドポイントに対してバージョン管理機能を提供しています。このバージョン管理システムにより、Boxがエンドポイントのバージョンを新しく導入した場合でも、既存のエンドポイントのバージョンに対してシームレスな機能が保証されます。 API… # APIのバージョン戦略 Boxでは、特定のAPIエンドポイントに対してバージョン管理機能を提供しています。このバージョン管理システムにより、Boxがエンドポイントのバージョンを新しく導入した場合でも、既存のエンドポイントのバージョンに対してシームレスな機能が保証されます。 APIのバージョン管理により、Boxは、自社のプラットフォームを継続的に強化できると同時に、機能の更新や廃止のための信頼できる手段をサードパーティの開発者に提供することもできます。 今後予定されているAPIの変更について常に最新情報を把握できるように、[変更ログ](page://changelog)を注視し、開発者コンソールの [アプリ情報] セクションで最新のメールアドレスを指定しておいてください。 2024年に、BoxではAPIの年ベースのバージョン管理を導入しました。 2024年の年末に利用できたすべてのエンドポイントには、バージョン`2024.0`が割り当てられました。 **APIユーザーが引き続きBox APIを使用するために必要な操作はありません。** バージョンを指定してAPIコールを行うには、値`2024.0`を設定した`box-version`ヘッダーをリクエストに含めてください。 ## Box APIのバージョン管理の仕組み Box APIは、`header`でのバージョン管理をサポートしています。どのバージョンを使用するかを決定するには、APIリファレンスとそこに記載されているサンプルリクエストを参照してください。 ### headerにおけるバージョン管理 Box APIでは、有効なバージョン名を含む`box-version`ヘッダーを処理します。たとえば、クライアントがバージョン`2025.0`を使用してすべての署名リクエストのリストを取得する場合、リクエストは次のようになります。 ``` curl --location 'https://api.box.com/2.0/sign_requests' \ --header 'box-version: 2025.0' \ --header 'Authorization: Bearer … ``` 指定したバージョンが正しく、エンドポイントでサポートされている場合、レスポンスがクライアントに送信されます。エンドポイントが複数のバージョンで使用可能な場合、レスポンスには`box-version`ヘッダーが含まれ、リクエストの処理に使用されるバージョンを示します。2024年以降に導入されたエンドポイントは、バージョンが正しくない場合にエラーコード`400`を返すことがあります。バージョン管理のエラーの詳細については、[こちら](g://api-calls/permissions-and-errors/versioning-errors)を参照してください。 リクエストにバージョンが含まれていない場合、APIはデフォルトで、最初のBox APIバージョン`2024.0` (年ベースのバージョン管理が導入される前のエンドポイントのバージョン) になります。ただし、非推奨の変更を適用する際にこの動作を利用することはお勧めしません。一貫性を確保するために、リクエストごとに必ずAPIバージョンを指定してください。アプリケーションにバージョンを認識させることで、アプリケーションを特定の機能セットに固定し、サポートされている期間中は一貫した動作が保証されます。 ## リリーススケジュールと命名規則 Boxでは、**1年に1回**、特定のエンドポイントに新しく重大な変更を行う場合があります。これにより、APIのバージョンが新しくなります。署名リクエストエンドポイントの新しいバージョンを導入すると、エンドポイントの**すべてのパスとHTTPメソッド**でそのバージョンがサポートされるようになります。 たとえば、署名リクエストのエンドポイントが新しいバージョンを受け取ると、そのバージョンは、次の表に示すすべてのエンドポイントに適用されます。 | メソッド | リクエストURL | 説明 | | --- | --- | --- | | GET | https://api.box.com/2.0/sign_requests/:id | 特定の署名リクエストの詳細を取得します。 | | GET | https://api.box.com/2.0/sign_requests/ | すべての署名リクエストを取得します。 | | POST | https://api.box.com/2.0/sign_requests/ | 新しい署名リクエストを作成します。 | | POST | https://api.box.com/2.0/sign_requests/:id/resend | 特定の署名リクエストを再度送信します。 | | POST | https://api.box.com/2.0/sign_requests/:id/cancel | 特定の署名リクエストをキャンセルします。 | ### 命名規則 APIの新しいバージョンは、リリースされた暦年に従ってラベルが付けられます。 **例**: 署名リクエストのエンドポイントの新しいバージョンが2025年にリリースされた場合、その名前は`2025.0`となります。 Boxは、1年に**1回**、APIエンドポイントに新しく重大な変更を行う場合がありますが、セキュリティやプライバシーに関する懸念に対処するためにさらに重大な変更をリリースする権利を留保します。このような場合、新しいバージョンではサフィックスが1ずつ増加します。 **例**: 以前にリリースされた署名リクエストのバージョン`2025.0`でセキュリティの問題に対処する必要がある場合、新しいバージョンには`2025.1`というラベルが付きます。 安定した各バージョンは最低12か月間サポートされます。つまり、新しいバージョンがリリースされると、以前のバージョンは非推奨となり、使用することはできますが、新機能が追加されなくなります。また、12か月経たずに新しいバージョンがリリースされることはありません。 アプリを更新して最新の安定したAPIバージョンにリクエストを実行することを強くお勧めします。ただし、アプリで使用している安定したバージョンがサポートされなくなると、HTTPエラーコード`400 - Bad Request`を含むレスポンスが返されます。詳細については、[バージョン管理のエラー](g://api-calls/permissions-and-errors/versioning-errors)を参照してください。 ### エンドポイントのバージョン管理に関する表示 APIの現在の状態が常にわかるようにし、バージョン管理されているAPIリファレンスが読みやすくなるよう、影響を受けるエンドポイントには`x-stability-level`タグまたは`deprecated`属性に基づいた長円形アイコンが表示されます。 | スキーマ要素 | 長円形アイコンの名前 | 説明 | | --- | --- | --- | | x-stability-level: beta | ベータ | ベータと表示されているエンドポイントは、BoxのMain Beta Agreementに従い提供されているため、利用可能な機能が変更される可能性があります。ベータ版のエンドポイントが安定すると、ベータという表示が削除されます。 | | x-stability-level: stable、またはx-stability-levelタグなし | 最新バージョン | 最新バージョンとは、エンドポイントの最新の安定したバージョンを示します。 | | deprecated: true | 廃止 | エンドポイントは非推奨です。つまり、このエンドポイントは引き続き使用できますが、新機能が追加されなくなります。このようなエンドポイントには、deprecated属性をtrueに設定した状態で注釈が付けられています。 | ## バージョン管理のエラー 呼び出しなど、バージョン管理されているAPIのアクションを利用する際、ヘッダーに誤ったAPIバージョンや非推奨のバージョンが指定されていると、エラーが発生する可能性があります。 発生する可能性があるエラーの詳細については、[バージョン管理のエラー](g://api-calls/permissions-and-errors/versioning-errors)を参照してください。 ## Box SDKのバージョン管理の仕組み このバージョン戦略は、[次世代のSDK](page://sdks-and-tools/#next-generation-sdks)にのみ適用されます。 Box SDKは、**すべてのバージョンに対応**というSDKのアプローチをサポートしています。つまり、SDKの各リリースでは、現在サポートされている任意のバージョンのすべてのエンドポイントにアクセスできます。生成されたすべてのSDKはマネージャのアプローチを使用します。このアプローチでは、同じドメインを使用するすべてのエンドポイントを1つのマネージャにグループ化します。 たとえば、`FolderManager`には`create_folder`、`get_folder_by_id`、`update_folder_by_id`、`delete_folder_by_id`、`get_folder_items`、`copy_folder`のメソッドが含まれます。この分割は`x-box-tag`フィールドの値に基づいて行われます (このフィールドは公開APIサービスの仕様で各メソッドに割り当てられています)。ほとんどの場合、これはエンドポイントURLのルートに対応していますが、必ずしもそうとは限りません。たとえば、`FolderManager`には`https://api.box.com/2.0/folders`というルートURLを使用するメソッドが含まれますが、同じベースURLは`SharedLinkFoldersManager`のいくつかのメソッドでも使用されています。すべてのマネージャへの参照は、1つのBoxクライアントオブジェクトの下に保存されます。 エンドポイントのライフサイクルの例を見てみましょう。 1. 初期状態 (使用できるバージョンは1つのみ)。 ``` class FilesManager { async updateFileById( fileId: string, requestBody: UpdateFileByIdRequestBody, queryParams: UpdateFileByIdQueryParams, headers: UpdateFileByIdHeaders ): Promise < FileFull > {} } ``` エンドポイントの新しい`v2025_0`バージョンが導入されます (以前のバージョンは非推奨になります)。 SDKでは、エンドポイントの新しいバージョンごとに新しいメソッドが導入されます。これらのメソッドは古いメソッドと同じマネージャに保存されますが、その名前と対応するクラスの末尾にはバージョン番号が追加されます。古いメソッドは非推奨となり、最小限のメンテナンスが行われる日付が通知されます。これは、エンドポイントの公式サポートが終了した状態と見なされる日付です。 ``` class FilesManager { /** * @deprecated This endpoint will be EOL'ed after 05-2026. */ async updateFileById( fileId: string, requestBody: UpdateFileByIdRequestBody, queryParams: UpdateFileByIdQueryParams, headers: UpdateFileByIdHeaders ): Promise<FileFull> {} async updateFileById_2025_0( fileId: string, requestBody: UpdateFileByIdRequestBody_2025_0, queryParams: UpdateFileByIdQueryParams_2025_0, headers: UpdateFileByIdHeaders_2025_0 ): Promise<FileFull_2025_0> {} } ``` APIエンドポイントが公式サポート終了 (EOL) としてマークされます。 SDKは、公式サポート終了 (EOL) のエンドポイントの削除を伴う重大な変更をリリースします。SDKの新しいメジャーバージョンを何度もリリースするのを避けるために、すべてのエンドポイントの公式サポート終了日を四半期ごとに特定の日にまとめるのが理想的です。 ``` class FilesManager { async updateFileById_2025_0( fileId: string, requestBody: UpdateFileByIdRequestBody_2025_0, queryParams: UpdateFileByIdQueryParams_2025_0, headers: UpdateFileByIdHeaders_2025_0 ): Promise < FileFull_2025_0 > {} } ``` ## 重大な変更と重大ではない変更 Box APIにおける重大な変更は、バージョン管理されたリリースの中で行われ、通常は新しいメジャーAPIバージョンを伴います。既存の機能を損なわない程度の微調整であれば、既存のAPIバージョンに統合できます。次の表では、重大な変更と重大ではない変更の例を示します。 | APIの変更 | 重大な変更 | | --- | --- | | 新しいエンドポイント | いいえ | | リクエストの新しい読み取り専用フィールドまたは省略可能なフィールド | いいえ | | リクエストの新しい必須フィールド | はい | | リクエストの新しい文字列定数 | はい | | 非推奨 | いいえ | | 廃止/公式サポート終了となったエンドポイント | はい | | フィールド、データ型、文字列定数の名前変更/再構築 | はい | | フィールド検証の制限を強化する変更 | はい | | フィールド検証の制限を緩和する変更 | いいえ | | 操作によって返されるHTTPステータスコードの変更 | はい | | 宣言済みプロパティの削除 | はい | | APIまたはAPIパラメータの削除または名前変更 | はい | | 必須のリクエストヘッダーの追加 | はい | | エラーコードの追加 | いいえ | | エラーコードの削除または変更 | はい | | 列挙へのメンバーの追加 | はい | [oasdiff](https://github.com/Tufin/oasdiff/blob/main/BREAKING-CHANGES-EXAMPLES.md)ツールを使用すると、重大と思われる変更の大半を検出できます。 ## AIエージェントの構成のバージョン管理 [AIエージェント](g://box-ai/ai-agents)のバージョン管理により、開発者はモデルのバージョン管理をより詳細に制御できるようになり、レスポンスの一貫性が確保されます。詳細については、[AIエージェントの構成のバージョン管理ガイド](g://box-ai/ai-agents/ai-agent-versioning)を参照してください。 ## サポートポリシーと非推奨情報 Box APIとBox SDKの新しいバージョンがリリースされると、それより前のバージョンは廃止されます。Boxでは、バージョンを廃止する少なくとも24か月前に、そのバージョンを`deprecated`とマークします。つまり、非推奨バージョンの公式サポートが24か月経たずに終了することはありません。同様に、正式リリース (GA) されている個々のAPIについても、GAバージョンから削除する少なくとも24か月前にそのAPIを`deprecated`として宣言します。 Boxは、APIのメジャーバージョンを上げる際 (`2025.0`から`2026.0`など)、現在のバージョン (この例では`2025.0`) が即座に非推奨となることを発表し、その発表から24か月後にサポートを終了します。サービスのセキュリティや状態の信頼性に問題がある場合は、このポリシーに例外を認めることがあります。 APIが非推奨としてマークされている場合は、できるだけ早く最新バージョンに移行することを強くお勧めします。場合によっては、元のAPIが非推奨になってしばらくしてから、新しいアプリケーションで新しいAPIの使用を開始する必要があることを案内することもあります。 お客様が非推奨のAPIエンドポイントを呼び出すと、レスポンスには以下のようなヘッダーが含まれます。 ``` Deprecation: date="Fri, 11 Nov 2026 23:59:59 GMT" Box-API-Deprecated-Reason: https://developer.box.com/reference/deprecated ``` この日付は、いつこのバージョンが非推奨としてマークされたかをクライアントに示しています。 ## バージョン管理に関する考慮事項 リクエストの作成時には、以下の点を考慮してください。 - バージョン`2024.0`のエンドポイントは、`box-version`ヘッダーでバージョンを指定しなくても呼び出し可能です。バージョンが指定されておらず、呼び出したエンドポイントの`2024.0`バージョンが存在しない場合、レスポンスではHTTPエラーコード`400 - Bad Request`が返されます。 - `box-version`バージョンヘッダーが指定されていても、リクエストされたバージョンが存在しない場合、レスポンスではHTTPエラーコード`400 - Bad Request`が返されます。 詳細については、[バージョン管理のエラー](g://api-calls/permissions-and-errors/versioning-errors)を参照してください。 APIに含まれるリソースまたはリソースのプロパティが非推奨になると、その変更は以下の1つ以上の方法で伝えられます。 - 非推奨の動作を伴う呼び出しにより、レスポンスヘッダー`Box-API-Deprecated-Reason`と、詳細を確認するためのリンクが返されます。 ``` box-version: 2025.0 Deprecation: version="version", date="date" Box-API-Deprecated-Reason: https://developer.box.com/reference/deprecated ``` - 非推奨に関するお知らせが開発者向け変更ログに掲載されます。 - 影響を受けるリソースと必要な対応を特定できるように、APIリファレンスが更新されます。影響を受けるエンドポイントには**非推奨**の長円形アイコンが表示されます。 - アプリに影響する後方互換性のない変更が差し迫っている場合は、その非推奨についてアプリの連絡先メールアドレスに問い合わせることがあります。 ## その他のリソース - [APIリファレンス](page://reference) **Source:** [https://ja.developer.box.com/guides/api-calls/api-versioning-strategy/](https://ja.developer.box.com/guides/api-calls/api-versioning-strategy/) --- ### App Diagnosticsレポート **Type:** guide | **Category:** APIコール | **Section:** Developer Guides App Diagnosticsレポート App Diagnosticsレポートでは、指定した期間に特定のアプリケーションで実行された各APIコールの詳細を示したスプレッドシートが表示されます。このレポートでは、API Request ID… # App Diagnosticsレポート App Diagnosticsレポートでは、指定した期間に特定のアプリケーションで実行された各APIコールの詳細を示したスプレッドシートが表示されます。このレポートでは、`API Request ID`を確認できます。これは、トラブルシューティングのためにBoxサポートに提出することができます。 このレポートには、以下の項目は含まれません。 - 過去48時間以内に実行されたAPIコール - 承認およびトークンに関するAPIコール Boxでは、上記の項目を追加し、それによって、レポートが将来的にリアルタイムのトラブルシューティングに適したものになるよう取り組んでいます。 ## 1. [App Diagnostics] タブをクリックする App Diagnosticsレポートを実行するには、[開発者コンソール](https://app.box.com/developers/console)でアプリケーションの構成セクションの上部にある [**App Diagnostics**] オプションをクリックします。 ## 2. [App Diagnosticsレポートを実行] をクリックしてレポートを構成する [**App Diagnosticsレポートを実行**] をクリックすると、レポートのフィルタおよびパラメータを選択するためのポップアップが表示されます。 ## 3. レポートのパラメータを選択して [実行] をクリックする 現在から48時間前を基準に過去2週間以内の日付を選択できます。レポートは、合計24時間までを対象に実行できます。[**実行**] をクリックすると、レポートが生成されます。 ## 4. Box Reportsフォルダにアクセスする [[すべてのファイル](https://app.box.com/folder/0)] に移動し、Box Reportsフォルダを見つけます。今回初めてレポートを実行する場合は、このフォルダが自動的に生成されます。管理者の場合、これは、[管理コンソールのレポート](https://support.box.com/hc/ja/articles/360043696534-%E3%83%AC%E3%83%9D%E3%83%BC%E3%83%88%E3%81%AE%E5%AE%9F%E8%A1%8C)にアクセスした場合と同じフォルダです。このフォルダを開きます。 ## 5. 最新のPlatform App Diagnosticsレポートフォルダを探して開く 実行したレポートはすべて、Box Reportsフォルダに表示されます。最新のPlatform App Diagnostics実行のフォルダを探して開きます。 ## 6. ステータスを確認する レポートが完了するまで時間がかかります。ステータスは、フォルダの上部にあるボックスで確認できます。 ## 7. レポートが完了する 完了すると、ステータスが変更され、フォルダ内に`.csv`ファイルが表示されます。 ## 8. レポートを開く ファイルは、ウェブブラウザで開くことも、ローカルで表示するためにダウンロードすることもできます。[Boxサポート](https://support.box.com/hc/en-us/requests/new)によるサポートが必要な場合は、ダウンロードしたコピーを添付するか共有リンクを使用して、チケットとともにレポートを送信することができます。 このレポートには列が9個あります。 | 列 | 説明 | | | --- | --- | --- | | アプリ名 | アプリケーションの名前 | | | クライアントID | アプリケーションのクライアントID | | | HTTPステータスコード | Boxから返されたレスポンスコード | | | APIリクエスト期間 (ミリ秒) | APIコールからレスポンスまでの時間 | | | APIリクエストID | Boxサポートが使用できる一意の識別子 | | | リソース | APIコールでアクセスされたプライマリリソース | | | サブリソース | APIコールでアクセスされたセカンダリリソース | | | HTTPメソッド | APIコールで使用されたHTTPメソッドの種類 | | | APIリクエストタイムスタンプ | APIコールのタイムスタンプ | | **Source:** [https://ja.developer.box.com/guides/api-calls/permissions-and-errors/app-diagnostics-report/](https://ja.developer.box.com/guides/api-calls/permissions-and-errors/app-diagnostics-report/) --- ### App Userの作成 **Type:** guide | **Category:** ユーザー | **Section:** Developer Guides App Userの作成 App Userは、JWT認証を使用しているアプリによってのみ作成されるプログラム上のユーザーアカウントです。ユーザーがログインするためのBox… # App Userの作成 App Userは、[JWT認証](g://authentication/jwt/jwt-setup)を使用しているアプリによってのみ作成されるプログラム上のユーザーアカウントです。ユーザーがログインするためのBoxアカウントを持っていなくても、ユーザー、グループ、またはプロセスをアプリケーションの背後で表せるようにすることを目的としています。 App Userは、BoxアプリケーションがAPIを介してのみアクセスでき、`box.com`に直接ログインするための資格情報を持っていません。 ## 一般的なApp Userのパターン 一般的なApp Userは以下のようなパターンを目的に作成されます。 - `box.com`アカウントを持たない単一のアプリケーションユーザーまたはユーザーグループを表すため。 - App Userに会社内のすべてのイベントを監視させるなどの、アプリケーションプロセスを表すため。 - コンテンツが`box.com`ウェブアプリによって変更される可能性を排除し、ユーザーアカウントのファイルおよびフォルダ構造を完全に制御する機能をアプリケーションに提供するため。 ## 新しいApp Userの作成 新しいApp Userを生成するには、最低でもApp Userの名前が必要になります。 App Userの作成時に設定できるすべての使用可能なオプションパラメータを確認するには、[ユーザーを作成](endpoint://post-users)エンドポイントを参照してください。 新しく作成したアカウントを変更できるようにするには、受信した確認メールにあるリンクをクリックする必要があります。 App Userが作成されると、ユーザーオブジェクトが返されます。ユーザーオブジェクト内には、App UserのIDがあります。これは、ユーザーを変更するAPIリクエストを実行するために今後使用される可能性があります。 **Source:** [https://ja.developer.box.com/guides/users/create-app-user/](https://ja.developer.box.com/guides/users/create-app-user/) --- ### App UserへのSSO IDの関連付け **Type:** guide | **Category:** SSOとApp User | **Section:** Developer Guides App UserへのSSO IDの関連付け SSOサービスでは、社内でこのサービスを利用する各ユーザーに一意のユーザーレコードが作成されます。このSSOサービスを介してBoxアプリケーションにアクセスする際、SSOユーザーごとにBoxユーザーを作成している場合は、SSO… # App UserへのSSO IDの関連付け SSOサービスでは、社内でこのサービスを利用する各ユーザーに一意のユーザーレコードが作成されます。このSSOサービスを介してBoxアプリケーションにアクセスする際、SSOユーザーごとにBoxユーザーを作成している場合は、SSOユーザーとBoxユーザーレコードの間に関連付けを作成する必要があります。 ユーザーがSSOサービスを介してBoxにログインすると、Boxはまず関連付けを使用してユーザーを検索します。Boxユーザーレコードが見つかれば、そのユーザーとしてBox APIに対する呼び出しを開始することができます。Boxユーザーが見つからない場合は、一意のSSOユーザーアカウントに関連付けられた新しいBoxユーザーが作成されます。 Boxユーザーオブジェクトの最上位を探索すると、SSOサービスのユーザーオブジェクトからBox[ユーザーオブジェクト](r://user)に一意の識別子を追加して双方を関連付けるために使用できるオプションがわかります。 ``` { "address": "900 Jefferson Ave, Redwood City, CA 94063", "avatar_url": "https://www.box.com/api/avatar/large/181216415", "can_see_managed_users": true, "created_at": "2012-12-12T10:53:43-08:00", "enterprise": { .. }, "external_app_user_id": "my-user-1234", "hostname": "https://example.app.box.com/", "id": 11446498, "is_exempt_from_device_limits": true, "is_exempt_from_login_verification": true, "is_external_collab_restricted": true, "is_platform_access_only": true, "is_sync_enabled": true, "job_title": "CEO", "language": "en", "login": "ceo@example.com", "max_upload_size": 2147483648, "modified_at": "2012-12-12T10:53:43-08:00", "my_tags": [ .. ], "name": "Aaron Levie", "notification_email": { ... }, "phone": 6509241374, "role": "admin", "space_amount": 11345156112, "space_used": 1237009912, "status": "active", "timezone": "Africa/Bujumbura", "tracking_codes": [{ .. }], "type": "user" } ``` SSOサービス内の一意のユーザーとBoxユーザーの関連付けを作成するには、2つの方法が推奨されています。Boxユーザーの`external_app_user_id`フィールド内に一意のSSOユーザーIDを設定するか、一意のSSOメールアドレスを新しいユーザーのログインメールとして使用してください。 ## external_app_user_idの使用 (推奨方法) `external_app_user_id`フィールドは、SSOプロバイダのユーザーレコードなどの外部サービスとBoxユーザーレコードを関連付ける、文字列識別子を保持するよう設計されています。 特定のアプリケーションのApp Userを取得できるのは、そのApp Userを作成したのがこのアプリケーションである場合のみです。あるアプリケーションを使用して、別のアプリケーションで作成されたユーザーを検索した場合、データは返されません。 一意のSSOユーザーアカウントとBoxユーザーアカウントの関連付けに`external_app_user_id`フィールドを使用することは、この2つのアカウントを関連付ける方法としてメールよりも推奨されています。これには、以下のように複数の理由があります。 - メールアドレスによる関連付けを実行できるのは[管理対象ユーザー](page://platform/user-types/#managed-users)のみです。[App User](page://platform/user-types/#app-user)にはBoxによって自動的にメールアドレスが割り当てられるため、`login`をSSOサービスのメールアドレスになるよう割り当てることはできません。 - メールアドレスはBoxにおいて一意でなければなりません。つまり、SSOサービスユーザーが (Boxを使用する社内に存在しない) 同じメールアドレスを使用してBoxにサインアップした場合は、そのアドレスでユーザーを作成することも、既存のSSOサービスユーザーに接続することもできなくなります。 - `external_app_user_id`フィールドはこのために設計されています。 ## loginの使用 (代替方法) ユーザーオブジェクトの`login`フィールドを使用してアカウントの関連付けを作成する方法は、以下の限られた状況において使用可能です。 - [App User](page://platform/user-types/#app-user)ではなく[管理対象ユーザー](page://platform/user-types/#managed-users)タイプのみが使用されている。 - メールアドレスとBoxアカウントの作成リクエストがすべて会社によって管理されている。つまり、ユーザーは自身のメールアドレスで独自にBoxアカウントを作成することができません。 `login`フィールドで、Boxのユーザーに使用されるメールアドレスは一意である必要があります。すでに別のアカウント用に存在するメールアドレスを使用してユーザーを作成するようリクエストすると、`user_login_already_used`という`409 Conflict`エラーが発生します。 **Source:** [https://ja.developer.box.com/guides/sso-identities-and-app-users/connect-identities/](https://ja.developer.box.com/guides/sso-identities-and-app-users/connect-identities/) --- ### as-userヘッダー **Type:** guide | **Category:** 認証 | **Section:** Developer Guides as-userヘッダー as-userヘッダーを利用すると、JWTアプリケーションは別のユーザーの代理になることができます。 この場合、ユーザーIDはユーザーのBox識別子です。どのユーザーでも、ユーザーIDは、管理者だけが利用可能なGET /users… # as-userヘッダー `as-user`ヘッダーを利用すると、JWTアプリケーションは別のユーザーの代理になることができます。 ``` curl https://api.box.com/2.0/folders/0 \ -H "as-user: [USER_ID]" -H "authorization: Bearer [ACCESS_TOKEN]" ``` この場合、ユーザーIDはユーザーのBox識別子です。どのユーザーでも、ユーザーIDは、管理者だけが利用可能な`GET /users`エンドポイントを介して確認できます。また、認証済みのユーザーセッションで`GET /users/me`エンドポイントを呼び出して確認することもできます。 ## 前提条件 アプリケーションは、[開発者コンソール](https://app.box.com/developers/console)で、ユーザーとして操作を実行するように構成する必要があります。 さらに、認証済みユーザーは、管理者権限を持つユーザー、つまり、管理者または共同管理者である必要があります。詳細については、[ユーザータイプ](page://platform/user-types)のガイドを参照してください。 as-userヘッダーでは[サービスアカウント](page://platform/user-types/#service-account)の`user_id`を使用できません。 ## as-userを使用できるSDK すべての[Box公式SDK](g://tooling/sdks)では、`as-user`ヘッダーを使用してユーザーの代わりに処理を実行することがサポートされています。 ``` var user_client = new BoxClient(config, session, asUser: '[USER_ID]'); ``` ``` client.asUser([USER_ID]"); // client.asSelf(); ``` ``` user_to_impersonate = client.user(user_id='[USER_ID]') user_client = client.as_user(user_to_impersonate) ``` ``` client.asUser('[USER_ID]'); // client.asSelf(); ``` SDKには、他のユーザーに対して新しいクライアントを作成するものもあれば、既存のクライアントを変更して、そのクライアントが元のユーザーに対して認証される状態に戻せるようにするものもあることに注意してください。 **Source:** [https://ja.developer.box.com/guides/authentication/jwt/as-user/](https://ja.developer.box.com/guides/authentication/jwt/as-user/) --- ### as-userヘッダー **Type:** guide | **Category:** 認証 | **Section:** Developer Guides as-userヘッダー as-userヘッダーを使用すると、OAuth 2.0アプリケーションは別のユーザーの代理になることができます。 この場合、ユーザーIDはユーザーのBox識別子です。どのユーザーでも、ユーザーIDは、管理者だけが利用可能なGET /users… # as-userヘッダー `as-user`ヘッダーを使用すると、OAuth 2.0アプリケーションは別のユーザーの代理になることができます。 ``` curl https://api.box.com/2.0/folders/0 \ -H "as-user: [USER_ID]" -H "authorization: Bearer [ACCESS_TOKEN]" ``` この場合、ユーザーIDはユーザーのBox識別子です。どのユーザーでも、ユーザーIDは、管理者だけが利用可能な`GET /users`エンドポイントを介して確認できます。また、認証済みのユーザーセッションで`GET /users/me`エンドポイントを呼び出して確認することもできます。 ## 前提条件 `as-user`ヘッダーを使用するには、いくつかの要件があります。最初に、アプリケーションは、[開発者コンソール](https://app.box.com/developers/console)で、ユーザーとして操作を行うよう構成する必要があります。 さらに、認証済みユーザーは、管理者権限を持つユーザー、つまり、管理者、共同管理者、またはサービスアカウントのいずれかである必要があります。共同管理者にも、「ユーザーを管理する」権限のスコープが必要です。詳細については、[ユーザータイプ](page://platform/user-types)のガイドを参照してください。 ## as-userを使用できるSDK ``` var user_client = new BoxClient(config, session, asUser: '[USER_ID]'); ``` ``` client.asUser([USER_ID]"); // client.asSelf(); ``` ``` user_to_impersonate = client.user(user_id='[USER_ID]') user_client = client.as_user(user_to_impersonate) ``` ``` client.asUser('[USER_ID]'); // client.asSelf(); ``` SDKには、他のユーザーに対して新しいクライアントを作成するものもあれば、既存のクライアントを変更して、そのクライアントが元のユーザーに対して認証される状態に戻せるようにするものもあることに注意してください。 **Source:** [https://ja.developer.box.com/guides/authentication/oauth2/as-user/](https://ja.developer.box.com/guides/authentication/oauth2/as-user/) --- ### AWS Claude 3 Haiku **Type:** guide | **Category:** Box AI | **Section:** Developer Guides AWS Claude 3 Haiku 概要 AWS Claude 3 Haikuモデルは、創造性豊かな文章作成AIや対話型AIなど、さまざまな言語タスク向けにカスタマイズされています。 モデルの詳細 項目 値 説明 モデル名 AWS Claude 3 Haiku… # AWS Claude 3 Haiku ## 概要 **AWS Claude 3 Haiku**モデルは、創造性豊かな文章作成AIや対話型AIなど、さまざまな言語タスク向けにカスタマイズされています。 ## モデルの詳細 | 項目 | 値 | 説明 | | --- | --- | --- | | モデル名 | AWS Claude 3 Haiku | モデルの名前。 | | モデルのカテゴリ | 標準 | モデルのカテゴリ - 標準またはプレミアム。 | | APIモデル名 | aws__claude_3_haiku | Box AI APIでのモデルの上書きに使用されるモデルの名前。APIを動作させるには、ユーザーがこの名前を正確に指定する必要があります。 | | ホスティングレイヤー | Amazon Web Services (AWS) | LLMを安全にホストする、信頼できる組織。 | | モデルプロバイダ | Anthropic | このモデルを提供する組織。 | | リリース日 | 2024年3月13日 | モデルのリリース日。 | | ナレッジカットオフ日 | 2023年8月 | モデルが情報の更新を取得しなくなった日付。 | | 入力コンテキストウィンドウ | 200,000トークン | 入力コンテキストウィンドウでサポートされるトークン数。 | | 出力トークンの最大数 | 4,000トークン | 1回のリクエストでモデルが生成できるトークン数。 | | 経験に基づいたスループット | 117 | モデルが1秒あたりに生成できるトークン数。 | | オープンソース | いいえ | モデルのコードを一般公開するかどうかを指定します。 | ## その他のドキュメント 詳細については、[AWS Claude 3 Haikuの公式ドキュメント](https://aws.amazon.com/bedrock/claude/)を参照してください。 **Source:** [https://ja.developer.box.com/guides/box-ai/ai-models/aws-claude-3-haiku-model-card/](https://ja.developer.box.com/guides/box-ai/ai-models/aws-claude-3-haiku-model-card/) --- ### AWS Claude 3 Sonnet **Type:** guide | **Category:** Box AI | **Section:** Developer Guides AWS Claude 3 Sonnet AWS Claude 3 Sonnetモデルは、高度な言語タスク向けに設計されており、理解とコンテキスト処理に重点が置かれています。 モデルの詳細 項目 値 説明 モデル名 AWS Claude 3 Sonnet… # AWS Claude 3 Sonnet **AWS Claude 3 Sonnet**モデルは、高度な言語タスク向けに設計されており、理解とコンテキスト処理に重点が置かれています。 ## モデルの詳細 | 項目 | 値 | 説明 | | --- | --- | --- | | モデル名 | AWS Claude 3 Sonnet | モデルの名前。 | | モデルのカテゴリ | プレミアム | モデルのカテゴリ - 標準またはプレミアム。 | | APIモデル名 | aws__claude_3_sonnet | Box AI APIでのモデルの上書きに使用されるモデルの名前。APIを動作させるには、ユーザーがこの名前を正確に指定する必要があります。 | | ホスティングレイヤー | Amazon Web Services (AWS) | LLMを安全にホストする、信頼できる組織。 | | モデルプロバイダ | Anthropic | このモデルを提供する組織。 | | リリース日 | 2024年3月4日 | モデルのリリース日。 | | ナレッジカットオフ日 | 2023年8月 | モデルが情報の更新を取得しなくなった日付。 | | 入力コンテキストウィンドウ | 200,000トークン | 入力コンテキストウィンドウでサポートされるトークン数。 | | 出力トークンの最大数 | 4,000トークン | 1回のリクエストでモデルが生成できるトークン数。 | | 経験に基づいたスループット | 49.8 | モデルが1秒あたりに生成できるトークン数。 | | オープンソース | いいえ | モデルのコードを一般公開するかどうかを指定します。 | ## その他のドキュメント 詳細については、[AWS Claude 3 Sonnetの公式ドキュメント](https://aws.amazon.com/bedrock/claude/)を参照してください。 **Source:** [https://ja.developer.box.com/guides/box-ai/ai-models/aws-claude-3-sonnet-model-card/](https://ja.developer.box.com/guides/box-ai/ai-models/aws-claude-3-sonnet-model-card/) --- ### AWS Claude 3.5 Sonnet **Type:** guide | **Category:** Box AI | **Section:** Developer Guides AWS Claude 3.5 Sonnet 概要 AWS Claude 3.5 Sonnetモデルは、言語の理解と生成のタスクを強化するよう設計されています。 モデルの詳細 項目 値 説明 モデル名 AWS Claude 3.5 Sonnet… # AWS Claude 3.5 Sonnet ## 概要 **AWS Claude 3.5 Sonnet**モデルは、言語の理解と生成のタスクを強化するよう設計されています。 ## モデルの詳細 | 項目 | 値 | 説明 | | --- | --- | --- | | モデル名 | AWS Claude 3.5 Sonnet | モデルの名前。 | | モデルのカテゴリ | プレミアム | モデルのカテゴリ - 標準またはプレミアム。 | | APIモデル名 | aws__claude_3_5_sonnet | Box AI APIでのモデルの上書きに使用されるモデルの名前。APIを動作させるには、ユーザーがこの名前を正確に指定する必要があります。 | | ホスティングレイヤー | Amazon Web Services (AWS) | LLMを安全にホストする、信頼できる組織。 | | モデルプロバイダ | Anthropic | このモデルを提供する組織。 | | リリース日 | 2024年6月20日 | モデルのリリース日。 | | ナレッジカットオフ日 | 2024年4月 | モデルが情報の更新を取得しなくなった日付。 | | 入力コンテキストウィンドウ | 200,000トークン | 入力コンテキストウィンドウでサポートされるトークン数。 | | 出力トークンの最大数 | 8,000トークン | 1回のリクエストでモデルが生成できるトークン数。 | | 経験に基づいたスループット | 指定なし | モデルが1秒あたりに生成できるトークン数。 | | オープンソース | いいえ | モデルのコードを一般公開するかどうかを指定します。 | ## その他のドキュメント 詳細については、[AWS Claude 3.5 Sonnetの公式ドキュメント](https://aws.amazon.com/bedrock/claude/)を参照してください。 **Source:** [https://ja.developer.box.com/guides/box-ai/ai-models/aws-claude-3-5-sonnet-model-card/](https://ja.developer.box.com/guides/box-ai/ai-models/aws-claude-3-5-sonnet-model-card/) --- ### AWS Claude 3.7 Sonnet **Type:** guide | **Category:** Box AI | **Section:** Developer Guides AWS Claude 3.7 Sonnet 概要 AWS Claude 3.7 Sonnetモデルは、言語の理解と生成のタスクを強化するよう設計されています。 モデルの詳細 項目 値 説明 モデル名 AWS Claude 3.7 Sonnet… # AWS Claude 3.7 Sonnet ## 概要 **AWS Claude 3.7 Sonnet**モデルは、言語の理解と生成のタスクを強化するよう設計されています。 ## モデルの詳細 | 項目 | 値 | 説明 | | --- | --- | --- | | モデル名 | AWS Claude 3.7 Sonnet | モデルの名前。 | | モデルのカテゴリ | プレミアム | モデルのカテゴリ - 標準またはプレミアム。 | | APIモデル名 | aws__claude_3_7_sonnet | Box AI APIでのモデルの上書きに使用されるモデルの名前。APIを動作させるには、ユーザーがこの名前を正確に指定する必要があります。 | | ホスティングレイヤー | Amazon Web Services (AWS) | LLMを安全にホストする、信頼できる組織。 | | モデルプロバイダ | Anthropic | このモデルを提供する組織。 | | リリース日 | 2025年2月24日 | モデルのリリース日。 | | ナレッジカットオフ日 | 2024年10月 | モデルが情報の更新を取得しなくなった日付。 | | 入力コンテキストウィンドウ | 200,000トークン | 入力コンテキストウィンドウでサポートされるトークン数。 | | 出力トークンの最大数 | 8,000トークン | 1回のリクエストでモデルが生成できるトークン数。 | | 経験に基づいたスループット | 42 | モデルが1秒あたりに生成できるトークン数。 | | オープンソース | いいえ | モデルのコードを一般公開するかどうかを指定します。 | ## その他のドキュメント 詳細については、[AWS Claudeの公式ドキュメント](https://aws.amazon.com/bedrock/claude/)を参照してください。 **Source:** [https://ja.developer.box.com/guides/box-ai/ai-models/aws-claude-3-7-sonnet-model-card/](https://ja.developer.box.com/guides/box-ai/ai-models/aws-claude-3-7-sonnet-model-card/) --- ### AWS Claude 4 Opus **Type:** guide | **Category:** Box AI | **Section:** Developer Guides AWS Claude 4 Opus AWS Claude 4 Opusモデルは、コーディングや複雑な問題解決に優れており、最先端のエージェント製品を支えています。バックグラウンドでのClaude Codeの実行が可能なため、開発者は、Opus… # AWS Claude 4 Opus **AWS Claude 4 Opus**モデルは、コーディングや複雑な問題解決に優れており、最先端のエージェント製品を支えています。バックグラウンドでのClaude Codeの実行が可能なため、開発者は、Opusが個別に処理する長時間のコーディングタスクを割り当てることができます。 ## モデルの詳細 | 項目 | 値 | 説明 | | --- | --- | --- | | モデル名 | AWS Claude 4 Opus | モデルの名前。 | | モデルのカテゴリ | プレミアム | モデルのカテゴリ - 標準またはプレミアム。 | | APIモデル名 | aws__claude_4_opus | Box AI APIでのモデルの上書きに使用されるモデルの名前。APIを動作させるには、ユーザーがこの名前を正確に指定する必要があります。 | | ホスティングレイヤー | Amazon Web Services (AWS) | LLMを安全にホストする、信頼できる組織。 | | モデルプロバイダ | Anthropic | このモデルを提供する組織。 | | リリース日 | 2024年3月4日 | モデルのリリース日。 | | ナレッジカットオフ日 | 2023年8月 | モデルが情報の更新を取得しなくなった日付。 | | 入力コンテキストウィンドウ | 200,000トークン | 入力コンテキストウィンドウでサポートされるトークン数。 | | 出力トークンの最大数 | 32,000トークン | 1回のリクエストでモデルが生成できるトークン数。 | | 経験に基づいたスループット | 指定なし | モデルが1秒あたりに生成できるトークン数。 | | オープンソース | いいえ | モデルのコードを一般公開するかどうかを指定します。 | ## その他のドキュメント 詳細については、[AWS Claude 4 Opusの公式ドキュメント](https://aws.amazon.com/bedrock/claude/)を参照してください。 **Source:** [https://ja.developer.box.com/guides/box-ai/ai-models/aws-claude-4-opus-model-card/](https://ja.developer.box.com/guides/box-ai/ai-models/aws-claude-4-opus-model-card/) --- ### AWS Claude 4 Sonnet **Type:** guide | **Category:** Box AI | **Section:** Developer Guides AWS Claude 4 Sonnet AWS Claude 4 Sonnetモデルは、優れたコーディングと推論能力を備えながら、指示に対してより正確に応答し、日常的なユースケースに最先端のパフォーマンスをもたらします。 モデルの詳細 項目 値 説明 モデル名 AWS… # AWS Claude 4 Sonnet **AWS Claude 4 Sonnet**モデルは、優れたコーディングと推論能力を備えながら、指示に対してより正確に応答し、日常的なユースケースに最先端のパフォーマンスをもたらします。 ## モデルの詳細 | 項目 | 値 | 説明 | | --- | --- | --- | | モデル名 | AWS Claude 4 Sonnet | モデルの名前。 | | モデル名 | AWS Titan Text Lite | モデルの名前 - 標準またはプレミアム。 | | APIモデル名 | aws__claude_4_sonnet | Box AI APIでのモデルの上書きに使用されるモデルの名前。APIを動作させるには、ユーザーがこの名前を正確に指定する必要があります。 | | ホスティングレイヤー | Amazon Web Services (AWS) | LLMを安全にホストする、信頼できる組織。 | | モデルプロバイダ | Anthropic | このモデルを提供する組織。 | | リリース日 | 2025年5月22日 | モデルのリリース日。 | | ナレッジカットオフ日 | 2024年11月 | モデルが情報の更新を取得しなくなった日付。 | | 入力コンテキストウィンドウ | 200,000トークン | 入力コンテキストウィンドウでサポートされるトークン数。 | | 出力トークンの最大数 | 64,000トークン | 1回のリクエストでモデルが生成できるトークン数。 | | 経験に基づいたスループット | 指定なし | モデルが1秒あたりに生成できるトークン数。 | | オープンソース | いいえ | モデルのコードを一般公開するかどうかを指定します。 | ## その他のドキュメント 詳細については、[AWS Claude 4 Sonnetの公式ドキュメント](https://aws.amazon.com/bedrock/claude/)を参照してください。 **Source:** [https://ja.developer.box.com/guides/box-ai/ai-models/aws-claude-4-sonnet-model-card/](https://ja.developer.box.com/guides/box-ai/ai-models/aws-claude-4-sonnet-model-card/) --- ### AWS Titan Text Lite **Type:** guide | **Category:** Box AI | **Section:** Developer Guides AWS Titan Text Lite AWS Titan Text Liteモデルは、高度な言語処理用に設計されており、モデル自体は軽量ですが、幅広いコンテキストを処理できるため、複雑なタスクに適しています。 モデルの詳細 項目 値 説明 モデル名 AWS Titan Text… # AWS Titan Text Lite **AWS Titan Text Lite**モデルは、高度な言語処理用に設計されており、モデル自体は軽量ですが、幅広いコンテキストを処理できるため、複雑なタスクに適しています。 ## モデルの詳細 | 項目 | 値 | 説明 | | --- | --- | --- | | モデル名 | AWS Titan Text Lite | モデルの名前。 | | モデルのカテゴリ | 標準 | モデルのカテゴリ - 標準またはプレミアム。 | | APIモデル名 | aws__titan_text_lite | Box AI APIでのモデルの上書きに使用されるモデルの名前。APIを動作させるには、ユーザーがこの名前を正確に指定する必要があります。 | | ホスティングレイヤー | Amazon Web Services (AWS) | LLMを安全にホストする、信頼できる組織。 | | モデルプロバイダ | Anthropic | このモデルを提供する組織。 | | リリース日 | 2024年9月 | モデルのリリース日。 | | ナレッジカットオフ日 | 指定なし | モデルが情報の更新を取得しなくなった日付。 | | 入力コンテキストウィンドウ | 128,000トークン | 入力コンテキストウィンドウでサポートされるトークン数。 | | 出力トークンの最大数 | 4,000トークン | 1回のリクエストでモデルが生成できるトークン数。 | | 経験に基づいたスループット | 指定なし | モデルが1秒あたりに生成できるトークン数。 | | オープンソース | いいえ | モデルのコードを一般公開するかどうかを指定します。 | ## その他のドキュメント 詳細については、[AWS Titanの公式ドキュメント](https://aws.amazon.com/bedrock/titan/)を参照してください。 **Source:** [https://ja.developer.box.com/guides/box-ai/ai-models/aws-titan-text-lite-model-card/](https://ja.developer.box.com/guides/box-ai/ai-models/aws-titan-text-lite-model-card/) --- ### Azure OpenAI GPT-4.1 **Type:** guide | **Category:** Box AI | **Section:** Developer Guides Azure OpenAI GPT-4.1 Azure OpenAI GPT-4.1は、複雑なマルチステップタスクの処理で非常に効率的なマルチモーダルモデルです。 モデルの詳細 項目 値 説明 モデル名 GPT-4.… # Azure OpenAI GPT-4.1 **Azure OpenAI GPT-4.1**は、複雑なマルチステップタスクの処理で非常に効率的なマルチモーダルモデルです。 ## モデルの詳細 | 項目 | 値 | 説明 | | --- | --- | --- | | モデル名 | GPT-4.1 | モデルの名前。 | | モデルのカテゴリ | プレミアム | モデルのカテゴリ - 標準またはプレミアム。 | | APIモデル名 | azure__openai__gpt_4_1 | Box AI APIでのモデルの上書きに使用されるモデルの名前。APIを動作させるには、ユーザーがこの名前を正確に指定する必要があります。 | | ホスティングレイヤー | Microsoft Azure | LLMを安全にホストする、信頼できる組織。 | | モデルプロバイダ | Microsoft Azure | このモデルを提供する組織。 | | リリース日 | 2025年4月14日 | モデルのリリース日。 | | ナレッジカットオフ日 | 2024年5月 | モデルが情報の更新を取得しなくなった日付。 | | 入力コンテキストウィンドウ | 100万トークン | 入力コンテキストウィンドウでサポートされるトークン数。 | | 出力トークンの最大数 | 32,000トークン | 1回のリクエストでモデルが生成できるトークン数。 | | 経験に基づいたスループット | 87.5 | モデルが1秒あたりに生成できるトークン数。 | | オープンソース | いいえ | モデルのコードを一般公開するかどうかを指定します。 | ## その他のドキュメント 詳細については、[Azure OpenAI GPT-4oの公式ドキュメント](https://learn.microsoft.com/en-us/azure/ai-services/openai/concepts/models?tabs=python-secure#gpt-4o-and-gpt-4-turbo)を参照してください。 **Source:** [https://ja.developer.box.com/guides/box-ai/ai-models/azure-openai-gpt-4-1-model-card/](https://ja.developer.box.com/guides/box-ai/ai-models/azure-openai-gpt-4-1-model-card/) --- ### Azure OpenAI GPT-4.1 Mini **Type:** guide | **Category:** Box AI | **Section:** Developer Guides Azure OpenAI GPT-4.1 Mini Azure OpenAI GPT-4.1 Miniは、軽量のタスクを処理するように設計されたマルチモーダルモデルです。 モデルの詳細 項目 値 説明 モデル名 GPT-4.1 mini… # Azure OpenAI GPT-4.1 Mini **Azure OpenAI GPT-4.1 Mini**は、軽量のタスクを処理するように設計されたマルチモーダルモデルです。 ## モデルの詳細 | 項目 | 値 | 説明 | | --- | --- | --- | | モデル名 | GPT-4.1 mini | モデルの名前。 | | モデルのカテゴリ | 標準 | モデルのカテゴリ - 標準またはプレミアム。 | | APIモデル名 | azure__openai__gpt_4.1_mini | Box AI APIでのモデルの上書きに使用されるモデルの名前。APIを動作させるには、ユーザーがこの名前を正確に指定する必要があります。 | | ホスティングレイヤー | Microsoft Azure | LLMを安全にホストする、信頼できる組織。 | | モデルプロバイダ | Microsoft Azure | このモデルを提供する組織。 | | リリース日 | 2025年4月14日 | モデルのリリース日。 | | ナレッジカットオフ日 | 2024年5月 | モデルが情報の更新を取得しなくなった日付。 | | 入力コンテキストウィンドウ | 100万トークン | 入力コンテキストウィンドウでサポートされるトークン数。 | | 出力トークンの最大数 | 32,000トークン | 1回のリクエストでモデルが生成できるトークン数。 | | 経験に基づいたスループット | 87.5 | モデルが1秒あたりに生成できるトークン数。 | | オープンソース | いいえ | モデルのコードを一般公開するかどうかを指定します。 | ## その他のドキュメント 詳細については、[Azure OpenAI GPT-4oの公式ドキュメント](https://learn.microsoft.com/en-us/azure/ai-services/openai/concepts/models?tabs=python-secure#gpt-4o-and-gpt-4-turbo)を参照してください。 **Source:** [https://ja.developer.box.com/guides/box-ai/ai-models/azure-openai-gpt-4-1-mini-model-card/](https://ja.developer.box.com/guides/box-ai/ai-models/azure-openai-gpt-4-1-mini-model-card/) --- ### Azure OpenAI GPT-4o **Type:** guide | **Category:** Box AI | **Section:** Developer Guides Azure OpenAI GPT-4o Azure OpenAI GPT-4oは、軽量のタスクを処理するように設計されたマルチモーダルモデルです。 モデルの詳細 項目 値 説明 モデル名 GPT-4o… # Azure OpenAI GPT-4o **Azure OpenAI GPT-4o**は、軽量のタスクを処理するように設計されたマルチモーダルモデルです。 ## モデルの詳細 | 項目 | 値 | 説明 | | --- | --- | --- | | モデル名 | GPT-4o | モデルの名前。 | | モデルのカテゴリ | プレミアム | モデルのカテゴリ - 標準またはプレミアム。 | | APIモデル名 | azure__openai__gpt_4o | Box AI APIでのモデルの上書きに使用されるモデルの名前。APIを動作させるには、ユーザーがこの名前を正確に指定する必要があります。 | | ホスティングレイヤー | Microsoft Azure | LLMを安全にホストする、信頼できる組織。 | | モデルプロバイダ | Microsoft Azure | このモデルを提供する組織。 | | リリース日 | 2024年5月13日 | モデルのリリース日。 | | ナレッジカットオフ日 | 2023年9月 | モデルが情報の更新を取得しなくなった日付。 | | 入力コンテキストウィンドウ | 128,000トークン | 入力コンテキストウィンドウでサポートされるトークン数。 | | 出力トークンの最大数 | 2,000トークン | 1回のリクエストでモデルが生成できるトークン数。 | | 経験に基づいたスループット | 87.5 | モデルが1秒あたりに生成できるトークン数。 | | オープンソース | いいえ | モデルのコードを一般公開するかどうかを指定します。 | ## その他のドキュメント 詳細については、[Azure OpenAI GPT-4oの公式ドキュメント](https://learn.microsoft.com/en-us/azure/ai-services/openai/concepts/models?tabs=python-secure#gpt-4o-and-gpt-4-turbo)を参照してください。 **Source:** [https://ja.developer.box.com/guides/box-ai/ai-models/azure-openai-gpt-4o-model-card/](https://ja.developer.box.com/guides/box-ai/ai-models/azure-openai-gpt-4o-model-card/) --- ### Azure OpenAI GPT-4o Mini **Type:** guide | **Category:** Box AI | **Section:** Developer Guides Azure OpenAI GPT-4o Mini Azure OpenAI GPT-4o Miniは、軽量のタスクを処理するように設計されたマルチモーダルモデルです。 モデルの詳細 項目 値 説明 モデル名 GPT-4o Mini… # Azure OpenAI GPT-4o Mini **Azure OpenAI GPT-4o Mini**は、軽量のタスクを処理するように設計されたマルチモーダルモデルです。 ## モデルの詳細 | 項目 | 値 | 説明 | | --- | --- | --- | | モデル名 | GPT-4o Mini | モデルの名前。 | | モデルのカテゴリ | 標準 | モデルのカテゴリ - 標準またはプレミアム。 | | APIモデル名 | azure__openai__gpt_4o_mini | Box AI APIでのモデルの上書きに使用されるモデルの名前。APIを動作させるには、ユーザーがこの名前を正確に指定する必要があります。 | | ホスティングレイヤー | Microsoft Azure | LLMを安全にホストする、信頼できる組織。 | | モデルプロバイダ | Microsoft Azure | このモデルを提供する組織。 | | リリース日 | 2024年7月18日 | モデルのリリース日。 | | ナレッジカットオフ日 | 2023年10月 | モデルが情報の更新を取得しなくなった日付。 | | 入力コンテキストウィンドウ | 128,000トークン | 入力コンテキストウィンドウでサポートされるトークン数。 | | 出力トークンの最大数 | 16,000トークン | 1回のリクエストでモデルが生成できるトークン数。 | | 経験に基づいたスループット | 85.4 | モデルが1秒あたりに生成できるトークン数。 | | オープンソース | いいえ | モデルのコードを一般公開するかどうかを指定します。 | ## 使用方法 Boxウェブアプリでは、以下のユースケースに対応するためにこのモデルを使用します。 - コンテンツの作成 - コンテンツの編集 - 要約の作成 - 単一ドキュメントのテキストに関するQ&A Box AI APIでは、以下のユースケースに対応するためにこのモデルを使用します。 - コンテンツの作成 - コンテンツの編集 - 要約の作成 - 単一ドキュメントのテキストに関するQ&A - メタデータの抽出 ## その他のドキュメント 詳細については、[Azure OpenAI GPT-4o Miniの公式ドキュメント](https://learn.microsoft.com/en-us/azure/ai-services/openai/concepts/models?tabs=python-secure#gpt-4o-and-gpt-4-turbo)を参照してください。 **Source:** [https://ja.developer.box.com/guides/box-ai/ai-models/azure-openai-gpt-4o-mini-model-card/](https://ja.developer.box.com/guides/box-ai/ai-models/azure-openai-gpt-4o-mini-model-card/) --- ### Azure text-embedding-ada-002 **Type:** guide | **Category:** Box AI | **Section:** Developer Guides Azure text-embedding-ada-002 Azure text-embedding-ada-002は、軽量のタスクを処理するように設計されたマルチモーダルモデルです。 モデルの詳細 項目 値 説明 モデル名 text-embedding-ada-00… # Azure text-embedding-ada-002 **Azure text-embedding-ada-002**は、軽量のタスクを処理するように設計されたマルチモーダルモデルです。 ## モデルの詳細 | 項目 | 値 | 説明 | | --- | --- | --- | | モデル名 | text-embedding-ada-002 | モデルの名前。 | | モデルのカテゴリ | 標準 | モデルのカテゴリ - 標準またはプレミアム。 | | APIモデル名 | azure__openai__text_embedding_ada_002 | Box AI APIでのモデルの上書きに使用されるモデルの名前。APIを動作させるには、ユーザーがこの名前を正確に指定する必要があります。 | | ホスティングレイヤー | Microsoft Azure | LLMを安全にホストする、信頼できる組織。 | | モデルプロバイダ | Microsoft Azure | このモデルを提供する組織。 | | リリース日 | 2022年12月 | モデルのリリース日。 | | ナレッジカットオフ日 | 2021年9月 | モデルが情報の更新を取得しなくなった日付。 | | 入力コンテキストウィンドウ | 8,000トークン | 入力コンテキストウィンドウでサポートされるトークン数。 | | 出力トークンの最大数 | 該当なし | 1回のリクエストでモデルが生成できるトークン数。 | | 経験に基づいたスループット | 1,000 | モデルが1秒あたりに生成できるトークン数。 | | オープンソース | いいえ | モデルのコードを一般公開するかどうかを指定します。 | ## その他のドキュメント 詳細については、[Azure Embeddingsモデルの公式ドキュメント](https://learn.microsoft.com/en-us/azure/ai-services/openai/concepts/models#embeddings)を参照してください。 **Source:** [https://ja.developer.box.com/guides/box-ai/ai-models/azure-text-embedding-ada-002-model-card/](https://ja.developer.box.com/guides/box-ai/ai-models/azure-text-embedding-ada-002-model-card/) --- ### Box AI **Type:** guide | **Category:** Box AI | **Section:** Developer Guides Box AI Box AI APIを使用すると、Platformアプリケーション内でBox AI機能を利用できます。たとえば、Box AIの質疑応答機能をサードパーティ製アプリケーションに実装したり、自社製品のコンテンツエディタ内で直接コンテンツを生成したりできます。 Box… # Box AI Box AI APIを使用すると、Platformアプリケーション内でBox AI機能を利用できます。たとえば、Box AIの質疑応答機能をサードパーティ製アプリケーションに実装したり、自社製品のコンテンツエディタ内で直接コンテンツを生成したりできます。 ## Box AI APIの機能 Box AI APIには、アプリケーションのワークフローで大規模言語モデル (LLM) を利用できるように設計された多数の機能が用意されています。 現在は、Box AIに対して、ユーザーの質問への回答、ドキュメントの内容の要約、ドキュメントで使用できるテキストの生成を求めることができます。また、Box AIを使用して、スキーマやメタデータテンプレートなど、指定した入力データからメタデータを抽出することもできます。 [Box AI for UI Elements](g://embed/ui-elements/preview#box-ai-ui-element)機能を使用すると、アプリにBox AIを組み込むことができます。 ### Box AIに質問する Boxに保存しているドキュメントで作業している間など、Box AI APIを使用して、そのコンテンツについて質問することができます。 Box AIは、指定されたファイルに基づいて、コンテンツに関する質問に回答したり、要約を生成したりできます。 ユーザーがドキュメントでの作業中にBox AIを操作する方法の例については、[Box AI for Documents](https://support.box.com/hc/en-us/articles/22158484213267-Box-AI-for-Documents)を参照してください。 ### Box AIを使用してテキストを生成する Box AI APIを使用すると、テキストをゼロから生成したり、Box Note内の既存のテキストから生成したり、プレビュー内の特定のドキュメントに基づいて生成したりすることができます。たとえば、プレビュー表示している記事に基づいてテンプレートやアジェンダを作成するようBox AIに求めることができます。 また、もう1つの例として、Box Notesでは、テキストの生成や既存メモのコンテンツのリファインにBox AIを使用します。詳細については、[Box AI for Notes](https://support.box.com/hc/en-us/articles/22198577315347-Box-AI-for-Notes)を参照してください。 ### メタデータの抽出 [`POST /2.0/ai/extract`](e://post_ai_extract)および[`POST /2.0/ai/extract_structured`](e://post_ai_extract_structured)エンドポイントを使用すると、指定した入力からデータを抽出し、キー/値ペアの形式で返すことができます。 - `extract_structured`エンドポイントは、メタデータテンプレートから取得したあらかじめ定義された構造、または一連のフィールドに従ってデータを抽出する場合に使用します。 - `extract`エンドポイントは、プロンプトを使用してファイルからデータを抽出する場合に使用します。プロンプトには、JSONやXMLなどの形式の文字列化バージョン、またはプレーンテキストを含めることができます。 ### 構成の上書き デフォルトのエージェント構成を上書きし、独自のカスタム設定を導入するには、Box AI APIリクエストで利用可能な`ai_agent`パラメータを使用できます。 詳細については、[AIエージェントのデフォルト構成](g://box-ai/ai-agents/get-agent-default-config)を参照してください。 ### Box AI for UI Elements Box AI for UI Elementsはコンテンツプレビューで利用可能で、これにより、Platformアプリケーション内で直接ドキュメントについて質問することができます。[Box AI for UI Elements](g://embed/ui-elements/preview#box-ai-ui-element)を使用してプロジェクトにBox AI機能を埋め込む方法をご確認ください。 ## サポートされている言語 Box AIは、英語、日本語、フランス語、スペイン語など、多くの言語で使用できます。ただし、基になるモデルは、主に英語のドキュメントでトレーニングされています。つまり、他の言語のプロンプトで返される回答は、英語の場合よりも低品質になる可能性があります。テストでは、要約、文法やつづりの確認、質問への回答について満足のいく結果が示されていますが、結果は英語の場合と異なる可能性があることに留意してください。 言語を日本語に切り替えると、より適切な結果が得られます。 ## [ユーザーアクティビティ] レポート (UAR) でのBox AI API [[ユーザーアクティビティ] レポート](https://support.box.com/hc/en-us/articles/4415012490387-User-Activity-Report)には、ユーザーがBoxで実行している操作の概要が示されます。Box管理者は、このレポートを使用して、所定の期間内にユーザーが行った操作を確認できますが、これにはBox AIに対する操作も含まれます。レポートには、Box管理者がBox AIの詳細を取得するために選択できる以下の操作が用意されています。 - **AIクエリ**: ユーザーがBox AIに対してクエリを実行し、レスポンスを受け取りました。 - **AIクエリの失敗**: ユーザーがBox AIに対してクエリを実行したが、レスポンスがありませんでした。 **Source:** [https://ja.developer.box.com/guides/box-ai/](https://ja.developer.box.com/guides/box-ai/) --- ### Box AI Studio **Type:** guide | **Category:** Box AI Studio | **Section:** Developer Guides Box AI Studio Box AI Studioは、Enterprise Advancedアカウントでのみ使用できます。 Box AI Studioを使用すると、ビジネスニーズに最適なカスタムAI… # Box AI Studio Box AI Studioは、Enterprise Advancedアカウントでのみ使用できます。 [Box AI Studio](https://support.box.com/hc/en-us/articles/37228079461267-Enabling-Box-AI-Studio-and-Managing-Agents)を使用すると、ビジネスニーズに最適なカスタムAIエージェントを作成して管理できます。たとえば、コンプライアンスコンサルタントとして機能し、FedRAMP Moderateへの準拠を念頭に置いて顧客のドキュメントに関する質問に回答するAIエージェントを作成できます。 ## Box AI Studioの機能 現在、Box AIエージェントは、ユーザーの質問に回答したり、ドキュメントで使用できるテキストを生成したりするよう構成できます。 ## サポートされている言語 Box AI Studioは、英語、日本語、フランス語、スペイン語など、多くの言語で使用できます。ただし、基になるモデルは、主に英語のドキュメントでトレーニングされています。つまり、他の言語のプロンプトで返される回答は、英語の場合よりも低品質になる可能性があります。テストでは、要約、文法やつづりの確認、質問への回答について満足のいく結果が示されていますが、結果は英語の場合と異なる可能性があることに留意してください。 言語を日本語に切り替えると、より適切な結果が得られます。 **Source:** [https://ja.developer.box.com/guides/ai-studio/](https://ja.developer.box.com/guides/ai-studio/) --- ### Box AIに質問する **Type:** guide | **Category:** Box AI | **Section:** Developer Guides Box AIに質問する Box AI APIは、Enterprise PlusおよびEnterprise Advancedをご利用のすべてのお客様が利用できます。 Box AI APIを使用すると、指定した… # Box AIに質問する Box AI APIは、Enterprise PlusおよびEnterprise Advancedをご利用のすべてのお客様が利用できます。 Box AI APIを使用すると、指定した1ファイルまたは一連のファイルについて質問し、そのコンテンツに基づいた応答を得ることができます。たとえば、Boxでドキュメントを表示している場合に、Box AIに対して、コンテンツの要約を求めることができます。 ## 開始する前に Platformアプリを作成して認証するには、[Box AIの使い方](g://box-ai/ai-tutorials/prerequisites)に記載されている手順に従っていることを確認してください。 ## リクエストの送信 質問を含むリクエストを送信するには、`POST /2.0/ai/ask`エンドポイントを使用し、必須のパラメータを指定します。 ### パラメータ コールを実行するには、以下のパラメータを渡す必要があります。必須のパラメータは**太字**で示されています。 | パラメータ | 説明 | 使用可能な値 | 例 | | --- | --- | --- | --- | | mode | リクエストのタイプ。単一のファイルと一連のファイルのどちらに関する質問かを指定できます。単一のテキストファイルの場合、Box AI APIは、最大1 MBのテキストレプリゼンテーションをサポートします。ファイルサイズが1 MBを超える場合は、テキストレプリゼンテーションの最初の1 MBが処理されます。複数のファイルを対象とする場合、上限は25ファイルです。Box AIは、解像度が1024 x 1024ピクセルの画像ドキュメントを処理し、最大5つの画像か、複数ページの画像の場合は5ページを処理します。画像数または画像ページ数が5を超える場合は、最初の5つの画像または5ページが処理されます。モードをsingle_item_qaに設定した場合、items配列に列挙できる要素は1つのみです。現在、Box AIでは、マルチモーダルリクエストがサポートされていません。画像とテキストの両方が送信された場合、Box AIで処理されるのはテキストのみです。 | single_item_qa, multiple_item_qa | single_item_qa | | prompt | ドキュメントまたはコンテンツに関する質問。プロンプトの長さは10000文字以内にする必要があります。 | | What is this document about? | | dialogue_history.prompt | 以前にクライアントによって提供され、大規模言語モデル (LLM) が回答したプロンプト。 | Make my email about public APIs sound more professional | | | dialogue_history.answer | 以前にLLMから提供された回答。 | Here is a draft of your professional email about public APIs. | | | dialogue_history.created_at | プロンプトに対する前回の回答が作成された時点のISO日付形式のタイムスタンプ。 | 2012-12-12T10:53:43-08:00 | | | include_citations | 回答で引用情報を返すかどうかを指定します。 | true, false | true | | items.id | 入力データとして指定するBoxファイルID。 | | 112233445566 | | items.type | 指定した入力データのタイプ。現在は、単一のファイルまたは複数のファイルを指定できます。 | file | file | | items.content | 項目のコンテンツ。通常はテキストレプリゼンテーションです。 | | An application programming interface (API) is a way for two or more computer programs or components to communicate with each other. It is a type of software interface... | | ai_agent | デフォルトのエージェント構成を上書きするために使用されるAIエージェント。このパラメータを使用すると、短いテキストや長いテキストを表すmodelパラメータを使用してデフォルトのLLMをカスタムのLLMに置き換えたり、よりカスタマイズされたユーザーエクスペリエンスを実現できるようにベースとなるpromptを微調整したり、temperatureなどのLLMパラメータを変更して結果の創造性を調整したりすることができます。ai_agentパラメータを使用する前に、GET 2.0/ai_agent_defaultリクエストを使用してデフォルト構成を取得できます。具体的なユースケースについては、AIモデルの上書きに関するチュートリアルを参照してください。 | | | ## ユースケース ## 項目について質問する この例では、`POST ask/ai` APIを使用して1つ以上の項目について質問する方法を示します。このエンドポイントを使用する際は、指定する項目の数に応じて、忘れずに`mode`パラメータを指定してください。 ``` curl -i -L POST "https://api.box.com/2.0/ai/ask" \ -H "content-type: application/json" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -d '{ "mode": "single_item_qa", "items": [ { "id": "12345678", "type": "file" } ], "prompt": "List the guidelines on creating questions in Box AI for Documents" }' ``` レスポンスは次のようになります。 ``` { "answer": "The guidelines for working with questions in Box AI for Documents are as follows:\n\n1. Box AI pulls information only from the document loaded in preview.\n2. If questions fall outside the scope of the document, Box AI will inform you that it cannot answer.\n3. Be specific when asking questions; use parameters like numbered lists, brevity, tables, and central themes or key points.\n4. Aim to stay within the scope of the document.\n5. Focus on text-based responses only.", "created_at": "2024-11-04T02:30:09.557-08:00", "completion_reason": "done" } ``` ## contentパラメータを使用して質問する Box AIへの入力のソースとして`content`パラメータを使用すると、それがプライマリソースとして使用されます。 ``` curl -i -L POST "https://api.box.com/2.0/ai/ask" \ -H "content-type: application/json" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -d '{ "mode": "single_item_qa", "items": [ { "id": "12345678", "type": "file", "content": "This is a document about Box AI For documents. It consists of the functionality summary and guidelines on how to work with Box AI. Additionally, it provides a set of best practices for creating questions." } ], "prompt": "List the guidelines on creating questions in Box AI for Documents" }' ``` このリクエストに対するレスポンスは、ファイルのコンテンツではなく`content`パラメータに基づきます。 ``` { "answer": "The document does not provide specific guidelines on working with questions in Box AI for Documents. It only mentions that it includes a set of best practices for creating questions, but the details of those guidelines are not included in the text provided. If you have more information or another document, I can help further!", "created_at": "2024-11-04T02:31:51.125-08:00", "completion_reason": "done" } ``` ## citationsパラメータを使用して質問する `citations`パラメータを`true`に設定すると、レスポンスには、ソースファイルまたはBox AIが回答をまとめるのに使用したファイルからの抜粋が含まれます。 ``` curl -i -L POST "https://api.box.com/2.0/ai/ask" \ -H "content-type: application/json" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -d '{ "mode": "multiple_item_qa", "include_citations": true, "items": [ { "id": "12345678", "type": "file" } ], "prompt": "List the guidelines on working with responses in Box AI for Documents" }' ``` その結果の回答には、ソースファイルとコンテンツの直接引用が含まれます。 ``` { "answer": "The guidelines for working with questions in Box AI for Documents are as follows:\n\n1. Box AI pulls information only from the document loaded in preview, and cannot answer questions outside its scope.\n2. Be specific when asking questions; use parameters like numbered lists, brevity, tables, and central themes or key points.\n3. Examples of better phrasing include asking for a numbered list of key points instead of just \"list key points,\" and requesting a succinct outline of important points rather than a general inquiry about the document's purpose.\n4. Stay within the scope of the document and focus on text-based responses only.", "created_at": "2024-11-04T02:35:00.578-08:00", "completion_reason": "done", "citations": [ { "type": "file", "id": "12345678", "name": "Box AI for Documents.docx", "content": "Guidelines for Box AI questions\nBox AI pulls information only from the document you loaded in preview." }, { "type": "file", "id": "12345678", "name": "Box AI for Documents.docx", "content": "If you ask any questions outside of the scope of the document, Box AI informs you that it cannot answer the question with the information provided." }, { "type": "file", "id": "12345678", "name": "Box AI for Documents.docx", "content": "As you ask Box AI to analyze your document, consider these suggestions:\n· Be as specific as possible." }, { "type": "file", "id": "12345678", "name": "Box AI for Documents.docx", "content": "Box AI for Documents\n\nWhen viewing a document in Box, you can ask Box AI to summarize document content, search key points, and write outline drafts based on your document files." } ] } ``` **Source:** [https://ja.developer.box.com/guides/box-ai/ai-tutorials/ask-questions/](https://ja.developer.box.com/guides/box-ai/ai-tutorials/ask-questions/) --- ### Box AIのチュートリアル **Type:** guide | **Category:** Box AI | **Section:** Developer Guides Box AIのチュートリアル 掲載されているチュートリアルには、Q&Aとテキスト生成、メタデータ抽出、AIモデルの構成の上書きに関する概要とユースケースが示されています。 # Box AIのチュートリアル 掲載されているチュートリアルには、Q&Aとテキスト生成、メタデータ抽出、AIモデルの構成の上書きに関する概要とユースケースが示されています。 **Source:** [https://ja.developer.box.com/guides/box-ai/ai-tutorials/](https://ja.developer.box.com/guides/box-ai/ai-tutorials/) --- ### Box AIの使い方 **Type:** guide | **Category:** Box AI | **Section:** Developer Guides Box AIの使い方 ソリューションにBox AI APIを実装するには、その機能にアクセスできることを確認する必要があります。また、Box AIスコープが有効になっているPlatformアプリケーションと、コールを認証するための開発者トークンも必要です。 Box AI API… # Box AIの使い方 ソリューションにBox AI APIを実装するには、その機能にアクセスできることを確認する必要があります。また、Box AIスコープが有効になっているPlatformアプリケーションと、コールを認証するための開発者トークンも必要です。 Box AI APIを使用するには、管理者が管理コンソールでこのAPIを有効にしていることを確認してください。サンドボックスでBox AI APIを使用したい場合は、[こちらのフォーム](https://forms.gle/Nsh3TwM3W8qg4U35A)を使用してBox AIチームにアクセス権限をリクエストしてください。 ## Platformアプリケーションの作成 まず、コールの実行に使用するPlatformアプリケーションを作成する必要があります。アプリケーションを作成するには、[Platformアプリの作成](g://applications/app-types/platform-apps)に関するガイドに従ってください。 ## Box AI APIへのアクセスの有効化 Box AI APIを操作するには、アプリケーションに`ai.readwrite`[スコープ](g://api-calls/permissions-and-errors/scopes)を追加する必要があります。このスコープを追加する前に、Box管理者からBox AI APIへのアクセス権限が付与されていることを確認してください。アプリの構成設定で [**AIを管理する**] オプションが表示されていない場合は、管理者までお問い合わせください。 スコープを追加するには、以下の手順を実行します。 開発者コンソールで、目的のアプリケーションを開きます。 [**構成**] > [**必須のアクセススコープ**] > [**コンテンツ操作**] に移動します。 [**AIを管理する**] スコープを選択します。Box Platformでは、コールを実行すると自動的にこのスコープが含まれます。あるアプリのコラボレータとして追加されているのにBox AI APIにアクセスできない場合は、[**AIを管理する**] スコープのチェックボックスがオンになった状態で、グレー表示になっています。つまり、アプリの所有者のAIのスコープは有効になっていますが、この設定を変更することはできません。 [承認または有効化](g://authorization)のためにアプリを送信します。既存のアプリケーションに対してBox AI APIを有効にする場合は、アプリケーションを[再承認](g://authorization/custom-app-approval#re-authorization-on-changes)する必要があります。 ## 開発者トークンの生成 リクエストの送信時にアプリを認証するには、開発者トークンが必要です。 トークンを生成するには、以下の手順を実行します。 1. [**開発者コンソール**] > [**Platformアプリ**] に移動します。 2. 右側の**オプションメニュー**ボタン ([…]) をクリックします。 3. [**開発者トークンを生成**] を選択します。トークンが自動的に生成され、クリップボードに保存されます。 アプリを開いて、[**構成**] > [**開発者トークン**] に移動してトークンを生成することもできます。 開発者トークンの有効期限は1時間のみです。 詳細については、[開発者トークン](g://authentication/tokens/developer-tokens)を参照してください。トークンを生成したら、cURLや他のクライアント ([Postman](g://tooling/postman)など) で使用してコールを実行できます。 **Source:** [https://ja.developer.box.com/guides/box-ai/ai-tutorials/prerequisites/](https://ja.developer.box.com/guides/box-ai/ai-tutorials/prerequisites/) --- ### Box AIを使用してテキストを生成する **Type:** guide | **Category:** Box AI | **Section:** Developer Guides Box AIを使用してテキストを生成する Box AI APIは、Enterprise PlusおよびEnterprise Advancedをご利用のすべてのお客様が利用できます。 Box AIを使用すると、提供されたコンテンツに基づいてテキストを生成できます。たとえば、Box… # Box AIを使用してテキストを生成する Box AI APIは、Enterprise PlusおよびEnterprise Advancedをご利用のすべてのお客様が利用できます。 Box AIを使用すると、提供されたコンテンツに基づいてテキストを生成できます。たとえば、Box Notesで参照または作成したコンテンツに基づいてテンプレートを生成するようBox AIに求めることができます。その後、生成されたテキストを直接ドキュメントに埋め込むことができます。 ## 開始する前に Platformアプリを作成して認証するには、[Box AIの使い方](g://box-ai/ai-tutorials/prerequisites)に記載されている手順に従っていることを確認してください。 ## リクエストの送信 リクエストを送信するには、`POST /2.0/ai/text_gen`エンドポイントを使用します。 ### パラメータ コールを実行するには、以下のパラメータを渡す必要があります。必須のパラメータは**太字**で示されています。 **注**: `items`配列に含めることができる要素は1つだけです。 | パラメータ | 説明 | 例 | | --- | --- | --- | | prompt | Box AIに対するテキストの生成またはリファインのリクエスト。プロンプトの長さは10000文字以内にする必要があります。 | 週1回の営業会議のアジェンダを作成してください。 | | items.id | ドキュメントのBoxファイルID。 | 1233039227512 | | items.type | 指定した入力データのタイプ。 | file | | items.content | 項目のコンテンツ (多くの場合はテキストレプリゼンテーション)。 | This article is about Box AI. | | dialogue_history.prompt | 以前にクライアントによって提供され、大規模言語モデル (LLM) が回答したプロンプト。 | Make my email about public APIs sound more professional | | dialogue_history.answer | 以前にLLMから提供された回答。 | Here is a draft of your professional email about public APIs. | | dialogue_history.created_at | プロンプトに対する前回の回答が作成された時点のISO日付形式のタイムスタンプ。 | 2012-12-12T10:53:43-08:00 | | ai_agent | デフォルトのエージェント構成を上書きするために使用されるAIエージェント。このパラメータを使用すると、たとえば、modelパラメータを使用してデフォルトのLLMをカスタムのLLMに置き換えたり、よりカスタマイズされたユーザーエクスペリエンスを実現できるようにベースとなるpromptを微調整したり、temperatureなどのLLMパラメータを変更して結果の創造性を調整したりすることができます。ai_agentパラメータを使用する前に、GET 2.0/ai_agent_defaultリクエストを使用してデフォルト構成を取得できます。具体的なユースケースについては、AIモデルの上書きに関するチュートリアルを参照してください。 | | ## ユースケース 指定されたファイルコンテンツとプロンプトに基づいてテキストを生成します。 ``` curl -i -L POST "https://api.box.com/2.0/ai/text_gen" \ -H "content-type: application/json" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -d '{ "items": [ { "id": "12345678", "type": "file" } ], "prompt": "Create a short blog post that provides information on Box AI for Documents and focuses on best practices for asking questions. You can add emoticons, but not too many." }' ``` 結果は次のようになります。 ``` { "answer": "📝 **Box AI for Documents: Best Practices for Asking Questions** 🤔\n\n---\n\nWelcome to our blog post on Box AI for Documents! 🎉 Today, we're going to dive into some best practices when it comes to asking questions within this innovative platform.\n\n1. **Be Clear and Concise**: When formulating a question in Box Notes, make sure your query is clear and to the point. This helps Box AI understand exactly what you're looking for.\n\n2. **Provide Context**: Giving context around your question can significantly improve the accuracy of the response generated by Box AI. Include relevant details or background information.\n\n3. **Use Keywords**: Utilize keywords related to your query within the question itself. This can help Box AI better identify the main topic of your inquiry.\n\n4. **Avoid Ambiguity**: Try to avoid vague or ambiguous questions that could lead to misunderstandings. The more precise you are, the better Box AI can assist you.\n\n5. **Review Suggestions Carefully**: After receiving suggestions from Box AI, take the time to review them carefully before incorporating them into your document. Ensure they align with your intended message.\n\nBy following these best practices, you can maximize the effectiveness of Box AI for Documents and streamline your workflow like never before! 💼✨\n\nStay tuned for more tips and tricks on leveraging technology for enhanced productivity! 👩‍💻🚀", "created_at": "2024-11-04T02:46:23.459-08:00", "completion_reason": "done" } ``` **Source:** [https://ja.developer.box.com/guides/box-ai/ai-tutorials/generate-text/](https://ja.developer.box.com/guides/box-ai/ai-tutorials/generate-text/) --- ### Box APIとSSO **Type:** guide | **Category:** 認証 | **Section:** Developer Guides Box APIとSSO 多くのBox Enterpriseでは、シングルサインオン (SSO) を使用して、Boxにログインしている管理対象ユーザーを認証します。Box Platformに作成されたアプリケーションとSSO… # Box APIとSSO 多くのBox Enterpriseでは、**シングルサインオン** (SSO) を使用して、Boxにログインしている[管理対象ユーザー](page://platform/user-types/#managed-users)を認証します。Box Platformに作成されたアプリケーションとSSOプロバイダの対話方法は、作成されるアプリケーションの種類によって異なります。 ## クライアント側認証を使用するPlatformアプリ [OAuth 2.0](g://authentication/oauth2)を使用するよう構成された[Platformアプリ](g://applications/app-types/platform-apps)でユーザーが認証されると、Boxは、企業でSSOを使用するよう構成されているかどうかを検出します。SSOを使用するよう構成されている場合、ユーザーはブラウザにリダイレクトされ、企業の構成済みのSSOログイン画面が表示されます。 ### SSOの有効化とSSO必須モード 企業は、**SSO必須モード**と**SSOの有効化**の2つの方法のいずれかで、SSOを構成できます。 SSOが有効化されていても必須ではない場合、管理対象ユーザーは次のいずれかを選択できます。 - Boxのユーザー名とパスワードを使用してログインする - SSOプロバイダを使用してログインする SSOが有効化され、必須になっている場合、すべての管理対象ユーザーは、企業の構成済みSSOプロバイダでログインするよう強制されます。この場合、ログインを試みるユーザーは、SAMLを介して渡されるメールアドレスと一致するBoxアカウントを持っているだけでなく、SSO側で構成されている必要があります。 SSOが必須モードに設定されている企業では、SSOからユーザーを除外することはできません。これは、プラットフォームのユースケースのみで使用されている場合でも当てはまります。 ## サーバー側認証を使用するPlatformアプリ [JWT](g://authentication/jwt)または[クライアント資格情報許可](g:///authentication/client-credentials)を使用する[Platformアプリ](g://applications/app-types/platform-apps)および[アプリトークン](g://authentication/app-token)認証を使用する[アクセス制限付きアプリ](guide://applications/web-app-integrations)では、Boxでの認証にSSOは使用されません。 サーバー側認証を使用するPlatformアプリは、Boxとの通信にサーバー間のAPIコールのみを使用します。このシナリオでのエンドユーザーの認証方法は、Boxではなくアプリケーションが決定します。 つまり、アプリケーションによるエンドユーザーの認証はそのアプリケーションによって決まりますが、アプリケーションによるBoxの承認とはまったく異なります。 これらのユースケースでは、アプリケーションは通常の管理対象ユーザーとしてではなく、サービスアカウントまたはApp Userとして認証します。このようなユーザータイプには、デフォルトでは管理対象ユーザーのデータへのアクセス権限がありません。これらのアプリケーションから他の管理対象ユーザーのデータにアクセスできるようにするには、明示的な[管理者の承認](g://authorization/custom-app-approval)が必要です。 ## カスタムスキル [カスタムスキル](g://applications/app-types/custom-skills)は、独自の方法で認証されます。この方法では、スキルイベントごとに固有のアクセストークンセットがアプリケーションに提供されます。 この場合、アプリケーションはユーザーと直接やり取りしないため、SSOは関与しません。 Skillsを使用した場合でも、スキルイベントをトリガーする可能性があるフォルダにファイルをアップロードするユーザーは、ウェブアプリまたはモバイルアプリにログインする必要があります。このログインでは、必要に応じてSSOの使用が求められます。 **Source:** [https://ja.developer.box.com/guides/authentication/sso/](https://ja.developer.box.com/guides/authentication/sso/) --- ### Box App Userの検索または作成 **Type:** quick-start | **Category:** SSOとApp User | **Section:** Developer Guides Box App Userの検索または作成 この時点で、アプリケーションコードが作成されています。このコードでは、ユーザーアクセスからのトラフィックを処理し、これらをログインのためにOktaに転送して、Oktaのユーザー情報を提供した後、最終的にはBox… # Box App Userの検索または作成 この時点で、アプリケーションコードが作成されています。このコードでは、ユーザーアクセスからのトラフィックを処理し、これらをログインのためにOktaに転送して、Oktaのユーザー情報を提供した後、最終的にはBoxのハンドラ (現時点で未作成) に渡します。 このセクションでは、以下のようにBoxの最終的なコンポーネントを取り上げます。 - Oktaユーザーに、関連付けられたBox App Userアカウントがあるかどうかを検証します。 - (関連付けられているアカウントがない場合は) 関連付けられているOktaレコードに新しいApp Userを作成します。 - Boxユーザーのトークンを取得してユーザー固有のAPIコールを実行します。 ## Platform App Userの作成 ユーザーを検証する前に、関連付けられたBoxユーザーアカウントがOktaユーザーにない場合のために、そのアカウントを作成する方法が必要です。 ローカルアプリケーションディレクトリで、手順1で作成した`server.js`ファイルを読み込みます。 次の`box`オブジェクトをファイルに追加し、保存します。 ``` const box = (() => { const configJSON = JSON.parse(fs.readFileSync(path.resolve(__dirname, './config.json'))); const sdk = boxSDK.getPreconfiguredInstance(configJSON); const client = sdk.getAppAuthClient('enterprise'); let oktaRecord = {}; let userId = ''; let userClient; function validateUser(userInfo, res) { // TODO: VALIDATE USER } function createUser(res) { // TODO: CREATE USER } return { validateUser, createUser }; })(); ``` このオブジェクトはいくつかの項目を定義します: - 構成: Box Node SDKの新しいインスタンスがインスタンス化され、多数の変数とともにオブジェクト関数で使用可能になります。 - `validateUser`関数: 関連付けられたOktaユーザーにBoxユーザーが存在するかどうかを検証するためのコードを保持します。 - `createUser`関数: 関連付けられたOktaユーザーIDにバインドされる新しいBoxユーザーを作成します。 この構造を定義したら、`// TODO: CREATE USER`セクションを以下のコードに置き換えます。 ``` const spaceAmount = 1073741824; // ~ 1gb client.enterprise.addAppUser( this.oktaRecord.name, { space_amount: spaceAmount, external_app_user_id: this.oktaRecord.sub } ).then(appUser => { res.send(`New user created: ${appUser.name}`); }); ``` このコードにより、新しいBox App Userが作成され、ユーザーオブジェクトの`external_app_user_id`パラメータが一意のOktaユーザーIDに設定されます。これで、2つのユーザーレコード間のバインドが定義されます。 ローカルアプリケーションディレクトリで、手順1で作成した`/src/main/java/com/box/sample/Application.java`ファイルを読み込みます。別のアプリケーション名を使用している場合は、同等のディレクトリを読み込みます。 `public class Application`の定義内に、以下のメソッドを追加します。 ``` static String validateUser(OidcUser user) throws IOException { // TODO: VALIDATE USER } static String createUser(OidcUser user) { // TODO: CREATE USER } ``` これらのメソッドはBoxユーザーの検証と作成を処理します。各メソッドの詳細は以下のとおりです。 - `validateUser`: 関連付けられたOktaユーザーにBoxユーザーが存在するかどうかを検証するためのコードを保持します。 - `createUser`: 関連付けられたOktaユーザーIDにバインドされる新しいBoxユーザーを作成します。 これらのメソッドを定義したら、`# TODO: CREATE USER`を以下のコードに置き換えます。 ``` String oktaName = (String) user.getAttributes().get("name"); Object oktaSub = user.getAttributes().get("sub"); CreateUserParams params = new CreateUserParams(); params.setExternalAppUserId((String) oktaSub); BoxUser.Info createdUserInfo = BoxUser.createAppUser(api, oktaName, params); return "New User Created: " + createdUserInfo.getName(); ``` このコードにより、新しいBox App Userが作成され、ユーザーオブジェクトの`external_app_user_id`パラメータが一意のOktaユーザーIDに設定されます。これで、2つのユーザーレコード間のバインドが定義されます。 ローカルアプリケーションディレクトリで、手順1で作成した`server.py`ファイルを読み込みます。 1. 既存のコードのルート定義の下に、以下の`Box`クラスオブジェクトを追加します。 ``` # Box user class class Box(object): def __init__(self): # Instantiate Box Client instance auth = JWTAuth.from_settings_file('../config.json') self.box_client = Client(auth) # Validate if Box user exists def validateUser(self, g): # TODO: VALIDATE USER # Create new Box user def createUser(self, ouser): # TODO: CREATE USER ``` このクラスで定義する内容は以下のとおりです。 - `init`: 初期化時に、Box Python SDKの新しいインスタンスがインスタンス化され、オブジェクトのメソッドで使用可能になります。 - `validateUser`メソッド: ユーザーオブジェクトを入力として受け取り、関連付けられたOktaユーザーにBoxユーザーが存在するかどうかを検証するためのコードを保持します。 - `createUser`メソッド: ユーザーオブジェクトを入力として受け取り、関連付けられたOktaユーザーIDにバインドされる新しいBoxユーザーを作成します。 このクラスを定義したら、`# TODO: CREATE USER`セクションを以下のコードに置き換えます。 ``` user_name = f'{ouser.profile.firstName} {ouser.profile.lastName}' uid = ouser.id space = 1073741824 user = self.box_client.create_user(user_name, None, space_amount=space, external_app_user_id=uid) return f'New user created: {user_name}' ``` このコードにより、新しいBox App Userが作成され、ユーザーオブジェクトの`external_app_user_id`パラメータが一意のOktaユーザーIDに設定されます。これで、2つのユーザーレコード間のバインドが定義されます。 `Controllers` > `AccountController.cs`ファイル内で、関連付けられた`AccountController`クラスの中に以下のメソッドを追加します。 ``` static async Task validateUser(string name, string sub) { // Configure Box SDK instance var reader = new StreamReader("config.json"); var json = reader.ReadToEnd(); var config = BoxConfig.CreateFromJsonString(json); var sdk = new BoxJWTAuth(config); var token = sdk.AdminToken(); BoxClient client = sdk.AdminClient(token); // Search for matching Box app user for Okta ID BoxCollection<BoxUser> users = await client.UsersManager.GetEnterpriseUsersAsync(externalAppUserId:sub); System.Diagnostics.Debug.WriteLine(users.TotalCount); if (users.TotalCount > 0) { // TODO: VALIDATE USER } else { // TODO: CREATE USER } } ``` このコードブロック内では、手順2でダウンロードした`config.json`ファイルを使用して新しいBox .NET SDKクライアントが作成されます。このコードサンプルの場合、その`config.json`ファイルはローカルアプリケーションディレクトリのルートに格納されます。 その後、Oktaの一意のID `sub`が`externalAppUserId`検索パラメータとして渡され、クライアントを使用して、Boxに登録されている会社内のすべてのユーザーが検索されます。その後、返されるユーザーの数を確認すると、有効なユーザーが検出されたかどうかがわかります。 この構造を定義したら、// TODO: CREATE USERセクションを以下のコードに置き換えます。 ``` var userRequest = new BoxUserRequest() { Name = name, ExternalAppUserId = sub, IsPlatformAccessOnly = true }; var user = await client.UsersManager.CreateEnterpriseUserAsync(userRequest); System.Diagnostics.Debug.WriteLine("New user created: " + user.Name); ``` このコードにより、新しいBox App Userが作成され、ユーザーオブジェクトの`external_app_user_id`パラメータが一意のOktaユーザーIDに設定されます。これで、2つのユーザーレコード間のバインドが定義されます。 その後、新しいユーザーが作成されたことを示す診断メッセージが書き戻されます。 # 前の手順が完了していません 最初に、手順1でお好みの言語/フレームワークを選択してください。 ## Oktaユーザーの検証 ここまで、ユーザーを作成する機能を定義してきました。次に定義するコードでは、Boxを使用する会社の全ユーザーを検索して関連付けられた`external_app_user_id`を探すことで、Oktaユーザーレコードに関連付けられたBoxユーザーレコードが存在するかどうかを検証します。 `// TODO: VALIDATE USER`コメントを以下の内容に置き換えます。 ``` this.oktaRecord = userInfo client.enterprise.getUsers({ "external_app_user_id": this.oktaRecord.sub }) .then((result) => { if (result.total_count > 0) { // TODO: MAKE AUTHENTICATED USER CALL } else { // User not found - create user this.createUser(); } }); ``` Box Node SDKを使用した場合、`enterprise.getUsers`を呼び出して会社の全ユーザーを検索し、一意のOktaユーザーIDを`external_app_user_id`値として渡すことで、そのユーザーに特化した検索を行います。 見つかった場合 (つまり、レコードの数が1以上だった場合) は、そのユーザーレコードを使用して、Box APIに対して認証済みの呼び出しを実行できます。これは次のセクションで定義します。 見つからなかった場合は、1つ前のセクションで定義した`createUser`関数を呼び出して、その`external_app_user_id`と関連付けられた新しいBoxユーザーを作成します。 `// TODO: VALIDATE USER`コメントを以下の内容に置き換えます。 ``` // Set up Box enterprise client Reader reader = new FileReader("config.json"); BoxConfig config = BoxConfig.readFrom(reader); api = BoxDeveloperEditionAPIConnection.getAppEnterpriseConnection(config); // Get Okta user sub for unique ID attachment to Box user Object oktaSub = user.getAttributes().get("sub"); // Check enterprise users for matching external_app_user_id against Okta sub URL url = new URL("https://api.box.com/2.0/users?external_app_user_id=" + oktaSub); BoxAPIRequest request = new BoxAPIRequest(api, url, "GET"); BoxJSONResponse jsonResponse = (BoxJSONResponse) request.send(); JsonObject jsonObj = jsonResponse.getJsonObject(); JsonValue totalCount = jsonObj.get("total_count"); // Set return string String outputString = ""; if (totalCount.asInt() > 0) { // TODO: MAKE AUTHENTICATED USER CALL } else { outputString = createUser(user); } return outputString; ``` Box Java SDKの汎用リクエストメソッドを使用した場合、`https://api.box.com/2.0/users`エンドポイントを直接呼び出して会社のユーザーを検索し、一意のOktaユーザーIDを`external_app_user_id`値として渡すことで、そのユーザーに特化した検索を行います。 見つかった場合 (つまり、レコードの数が1以上だった場合) は、そのユーザーレコードを使用して、Box APIに対して認証済みの呼び出しを実行できます。これは次のセクションで定義します。 見つからなかった場合は、1つ前のセクションで定義した`createUser`関数を呼び出して、その`external_app_user_id`と関連付けられた新しいBoxユーザーを作成します。 `# TODO: VALIDATE USER`コメントを以下の内容に置き換えます。 ``` # Fetch Okta user ID uid = g.user.id # Validate is user exists url = f'https://api.box.com/2.0/users?external_app_user_id={uid}' response = self.box_client.make_request('GET', url) user_info = response.json() # If user not found, create user, otherwise fetch user token if (user_info['total_count'] == 0): self.createUser(g.user) else: # TODO: MAKE AUTHENTICATED USER CALL ``` Box Python SDKの汎用リクエストメソッドを使用した場合、`https://api.box.com/2.0/users`エンドポイントを直接呼び出して会社のユーザーを検索し、一意のOktaユーザーIDを`external_app_user_id`値として渡すことで、そのユーザーに特化した検索を行います。 見つかった場合 (つまり、レコードの数が1以上だった場合) は、そのユーザーレコードを使用して、Box APIに対して認証済みの呼び出しを実行できます。これは次のセクションで定義します。 見つからなかった場合は、1つ前のセクションで定義した`createUser`関数を呼び出して、その`external_app_user_id`と関連付けられた新しいBoxユーザーを作成します。 `// TODO: VALIDATE USER`コメントを以下の内容に置き換えます。 ``` var userId = users.Entries[0].Id; var userToken = sdk.UserToken(userId); BoxClient userClient = sdk.UserClient(userToken, userId); // TODO: MAKE AUTHENTICATED USER CALL ``` 有効なユーザーが見つかった場合、Box IDが抽出されます。このIDは、アプリケーションではなく明確にそのユーザーのスコープに設定されたBox SDKクライアントの生成に使用されます。 # 前の手順が完了していません 最初に、手順1でお好みの言語/フレームワークを選択してください。 ## 認証済みのBoxユーザーの呼び出し Oktaユーザーの関連付けられたBoxユーザーが検出されたら、明確に[そのユーザーのスコープに設定された](g://authentication/jwt/user-access-tokens)アクセストークンを生成してBox APIコールを実行します。その後、現在のユーザーを取得するための呼び出しを実行して、すべてが機能していることと有効なユーザーアクセストークンがあることを確認します。 1つ前のセクションの`// TODO: MAKE AUTHENTICATED USER CALL`を次の内容に置き換えます。 ``` this.userId = result.entries[0].id; this.userClient = sdk.getAppAuthClient('user', this.userId); this.userClient.users.get(this.userClient.CURRENT_USER_ID) .then(currentUser => { res.send(`Hello ${currentUser.name}`); }); ``` 見つかったユーザーのBoxユーザーIDをキャプチャし、そのユーザーのスコープに設定されたユーザークライアントオブジェクトを生成します。最後に、このユーザークライアントオブジェクトを使用して現在のユーザーを取得する呼び出しを実行すると、Oktaに関連付けられたBox App Userのユーザープロフィール情報が返されます。 1つ前のセクションの`// TODO: MAKE AUTHENTICATED USER CALL`を次の内容に置き換えます。 ``` // User found, authenticate as user // Fetch user ID JsonArray entries = (JsonArray) jsonObj.get("entries"); JsonObject userRecord = (JsonObject) entries.get(0); JsonValue userId = userRecord.get("id"); // Get user scoped access token and fetch current user with it BoxDeveloperEditionAPIConnection userApi = BoxDeveloperEditionAPIConnection.getAppUserConnection(userId.asString(), config); BoxUser currentUser = BoxUser.getCurrentUser(userApi); BoxUser.Info currentUserInfo = currentUser.getInfo(); outputString = "Hello " + currentUserInfo.getName(); ``` 見つかったユーザーのBoxユーザーIDをキャプチャし、そのユーザーのスコープに設定されたユーザークライアントオブジェクトを生成します。最後に、このユーザークライアントオブジェクトを使用して現在のユーザーを取得する呼び出しを実行すると、Oktaに関連付けられたBox App Userのユーザープロフィール情報が返されます。 1つ前のセクションの`# TODO: MAKE AUTHENTICATED USER CALL`を次の内容に置き換えます。 ``` # Create user client based on discovered user user = user_info['entries'][0] user_to_impersonate = self.box_client.user(user_id=user['id']) user_client = self.box_client.as_user(user_to_impersonate) # Get current user current_user = user_client.user().get() return f'Hello {current_user.name}' ``` 見つかったユーザーのBoxユーザーIDをキャプチャし、そのユーザーのスコープに設定されたユーザークライアントオブジェクトを生成します。最後に、このユーザークライアントオブジェクトを使用して現在のユーザーを取得する呼び出しを実行すると、Oktaに関連付けられたBox App Userのユーザープロフィール情報が返されます。 1つ前のセクションの`// TODO: MAKE AUTHENTICATED USER CALL`を次の内容に置き換えます。 ``` BoxUser currentUser = await userClient.UsersManager.GetCurrentUserInformationAsync(); System.Diagnostics.Debug.WriteLine("Current user name: " + currentUser.Name); ``` このユーザーのスコープに設定されたクライアントを使用すると、Boxから現在のユーザーレコードが抽出され、現在のユーザー名を含む診断メッセージが書き戻されます。 # 前の手順が完了していません 最初に、手順1でお好みの言語/フレームワークを選択してください。 ## まとめ - OktaユーザーがBoxユーザーとして存在するかどうかを検証しました。 - 存在しない場合は新しいApp Userを作成しました。 - 既存のBoxユーザーに対してBox APIコールを実行しました。 Boxユーザーの検証と作成を設定しました **Source:** [https://ja.developer.box.com/guides/sso-identities-and-app-users/connect-okta-to-app-users/find-or-create-box-users/](https://ja.developer.box.com/guides/sso-identities-and-app-users/connect-okta-to-app-users/find-or-create-box-users/) --- ### Box Archive **Type:** guide | **Category:** Box Archive | **Section:** Developer Guides Box Archive Box Archiveは、Enterprise Advancedアカウントでのみ使用できます。 Box Archive… # Box Archive Box Archiveは、Enterprise Advancedアカウントでのみ使用できます。 Box Archiveを使用すると、アーカイブを作成および管理できます。アーカイブとは、冗長なコンテンツ、古くなったコンテンツ、または重要でないコンテンツの保存専用のフォルダです。アーカイブ内のコンテンツは、企業が所有しており、以前の所有者やコラボレータがアクセスすることはできません。 ## アーカイブはフォルダ アーカイブは、特別な種類のフォルダです。Box Archive APIを使用すると、アーカイブの作成、リスト取得、削除を実行できます。ただし、アーカイブまたはアーカイブ内のコンテンツを操作する他のAPIも存在します。サポートされているAPIの詳細なリストについては、[サポートされているAPI](g://archives/supported-apis)ガイドを参照してください。 ## 必須のスコープ Box Archive APIのいずれかを使用する前に、[管理コンソール内のBox Archive](https://support.box.com/hc/en-us/p/Product_Page_2023?section-id=40168863437843)にアクセスできることを確認してください。Box Platformアプリでは、`GCM`および`Read and write all files and folders`[スコープ](https://developer.box.com/guides/api-calls/permissions-and-errors/scopes/)が有効になっている必要があります。アーカイブを表示するだけで、変更しない予定の場合は、`Read and write all files and folders`スコープではなく`Read all files and folders`スコープを使用してください。 `GCM`スコープは、開発者コンソールでは使用できないため、カスタマーサポートに連絡して有効にする必要があります。 **Source:** [https://ja.developer.box.com/guides/archives/](https://ja.developer.box.com/guides/archives/) --- ### Box Archiveからのコンテンツの復元 **Type:** guide | **Category:** Box Archive | **Section:** Developer Guides Box Archiveからのコンテンツの復元 このガイドでは、誤ってアーカイブしたコンテンツを復元する方法について説明します。 アーカイブからのファイルまたはフォルダの復元 PUT /files/:id APIエンドポイントを使用してアーカイブからファイルを復元するか、PUT… # Box Archiveからのコンテンツの復元 このガイドでは、誤ってアーカイブしたコンテンツを復元する方法について説明します。 ## アーカイブからのファイルまたはフォルダの復元 [`PUT /files/:id`](e://put-files-id) APIエンドポイントを使用してアーカイブからファイルを復元するか、[`PUT /folders/:id`](e://put-folders-id)エンドポイントを使用してアーカイブからフォルダを復元します。`id`パラメータは、アーカイブから復元するファイル/フォルダのIDです。復元先を指定するには、リクエスト本文内で`parent.id`[パラメータ](https://developer.box.com/reference/put-folders-id/#param-parent-id)を使用します。これは、ファイル/フォルダの復元先となるフォルダ (任意のユーザーが所有している可能性があります) のIDです。 ファイル/フォルダをユーザーのルートフォルダに復元するには、`parent.id`の値として`0`を使用します。さらに、リクエスト本文で`parent.user_id`[パラメータ](https://developer.box.com/reference/put-folders-id/#param-parent-user_id)にユーザーのIDを渡します。 **Source:** [https://ja.developer.box.com/guides/archives/restore-content/](https://ja.developer.box.com/guides/archives/restore-content/) --- ### Box ArchiveでサポートされているAPI **Type:** guide | **Category:** Box Archive | **Section:** Developer Guides Box ArchiveでサポートされているAPI 基本的なBox Archive APIを使用すると、アーカイブの作成、リスト取得、削除を実行できますが、他のAPIを使用してアーカイブやそのコンテンツを操作することもできます。このようなAPI… # Box ArchiveでサポートされているAPI 基本的なBox Archive APIを使用すると、アーカイブの作成、リスト取得、削除を実行できますが、他のAPIを使用してアーカイブやそのコンテンツを操作することもできます。このようなAPIの詳細なリストについては、以下の表を参照してください。 これらのAPIを使用するには、アプリケーションで[`GCM`スコープ](https://developer.box.com/guides/api-calls/permissions-and-errors/scopes/#global-content-manager-gcm)を有効にする必要があります。このスコープは、開発者コンソールでは使用できないため、カスタマーサポートに連絡して有効にする必要があります。 さらに、以下のAPIの中には、Box Archiveを適切に使用するために、カスタマーサポートに連絡して有効にする必要があるものもあります。カスタマーサポートに連絡する際は、これらのAPIを使用する予定のユーザーIDを明記してください。 | APIエンドポイント | 説明 | | --- | --- | | POST /archives | アーカイブを作成します。 | | GET /archives | すべてのアーカイブのリストを取得します。 | | DELETE /archives/:id | アーカイブを削除します。 | | PUT /files/:id | ファイルをアーカイブに追加したり、アーカイブから復元したり、アーカイブ内またはアーカイブ間で移動したりします。ファイルに対するその他の更新は許可されていません。有効にするには、カスタマーサポートに連絡する必要があります。 | | PUT /folders/:id | フォルダをアーカイブに追加したり、アーカイブから復元したり、アーカイブ内またはアーカイブ間で移動したりします。フォルダに対するその他の更新は許可されていません。有効にするには、カスタマーサポートに連絡する必要があります。 | | POST /files/content | ファイルをアーカイブまたはアーカイブ内のフォルダにアップロードします。有効にするには、カスタマーサポートに連絡する必要があります。 | | GET /files/:id/content | ファイルをアーカイブまたはアーカイブ内のフォルダからダウンロードします。 | | POST /zip_downloads | アーカイブまたはアーカイブ内のフォルダのzipファイルをダウンロードします。 | | POST /folders | アーカイブ内にフォルダを作成します。有効にするには、カスタマーサポートに連絡する必要があります。 | | GET /files/:id | アーカイブ内のファイルの詳細を取得します。 | | GET /folders/:id | アーカイブまたはアーカイブ内のフォルダの詳細を取得します。 | | GET /folders/:id/items | アーカイブまたはアーカイブ内のフォルダ内にある項目のリストを取得します。 | | POST /files/:id/copy | アーカイブ内のファイルを別のアーカイブにコピーします。 | | POST /folders/:id/copy | アーカイブ内のフォルダを別のアーカイブにコピーします。 | | POST /files/:id/metadata/:scope/:template_key | アーカイブ内のファイルにメタデータインスタンスを作成します。 | | GET /files/:id/metadata/:scope/:template_key | アーカイブ内のファイルのメタデータインスタンスを表示します。 | | GET /files/:id/metadata | アーカイブ内のファイルのすべてのメタデータインスタンスのリストを取得します。 | | PUT /files/:id/metadata/:scope/:template_key | アーカイブ内のファイルのメタデータインスタンスを更新します。 | | DELETE /files/:id/metadata/:scope/:template_key | アーカイブ内のファイルのメタデータインスタンスを削除します。 | | POST securityClassification | アーカイブ内のファイルに分類ラベルを作成します。 | | GET securityClassification | アーカイブ内のファイルの分類ラベルを表示します。 | | PUT securityClassification | アーカイブ内のファイルの分類ラベルを更新します。 | | DELETE securityClassification | アーカイブ内のファイルの分類ラベルを削除します。 | **Source:** [https://ja.developer.box.com/guides/archives/supported-apis/](https://ja.developer.box.com/guides/archives/supported-apis/) --- ### Box Archiveへのコンテンツの追加 **Type:** guide | **Category:** Box Archive | **Section:** Developer Guides Box Archiveへのコンテンツの追加 アーカイブにコンテンツを追加するには、まず、アーカイブを作成する必要があります。まだ作成していない場合は、アーカイブを作成エンドポイントを使用します。 アーカイブへのファイルまたはフォルダの追加 PUT /files/:id API… # Box Archiveへのコンテンツの追加 アーカイブにコンテンツを追加するには、まず、アーカイブを作成する必要があります。まだ作成していない場合は、[アーカイブを作成](https://developer.box.com/reference/v2025.0/post-archives/)エンドポイントを使用します。 ## アーカイブへのファイルまたはフォルダの追加 [`PUT /files/:id`](e://put-files-id) APIエンドポイントを使用してアーカイブにファイルを追加するか、[`PUT /folders/:id`](e://put-folders-id)エンドポイントを使用してフォルダを追加します。`id`パラメータは、アーカイブに追加するファイル/フォルダのIDです。追加先を指定するには、リクエスト本文内で`parent.id`[パラメータ](https://developer.box.com/reference/put-folders-id/#param-parent-id)を使用します。これには、アーカイブのID、またはアーカイブ内にあるフォルダのIDを指定できます。 **Source:** [https://ja.developer.box.com/guides/archives/add-content/](https://ja.developer.box.com/guides/archives/add-content/) --- ### Box CLIでのPowerShellスクリプトの使用 **Type:** quick-start | **Category:** CLI | **Section:** Developer Guides Box CLIでのPowerShellスクリプトの使用 CLIはそれ自体がすでに強力ですが、PowerShellスクリプトと併用すると、反復タスクをさらに短時間で完了することができます。Boxでは、開発をすぐに開始できるように、BoxのCLI GitHub… # Box CLIでのPowerShellスクリプトの使用 CLIはそれ自体がすでに強力ですが、PowerShellスクリプトと併用すると、反復タスクをさらに短時間で完了することができます。Boxでは、開発をすぐに開始できるように、BoxのCLI GitHubリポジトリ内にサンプル[スクリプト](https://github.com/box/boxcli/tree/main/examples)フォルダを作成しました。 CLIスクリプトのしくみを説明するため、ユーザーのプロビジョニングと作成を行う[スクリプト](https://github.com/box/boxcli/tree/main/examples/User%20Creation%20&%20Provisioning)テンプレートを使用します。 このスクリプトでは、Box CLIを使用して、個人用フォルダ構造の作成と管理対象ユーザーの一括作成を実行し、新しく作成したフォルダ構造に新しいユーザーをビューアー/アップローダーのロールを持つコラボレータとして追加することでそのユーザーのプロビジョニングを行います。 クイックスタートのこの手順は、管理者権限を持つサービスアカウントとユーザーのみを対象としています。Box管理者以外のユーザーの場合、またはサービスアカウントを使用していない場合は、この手順をスキップしてください。 ## ユースケース ユーザーとフォルダ構造を自動的に作成するために、スクリプトによって以下の手順が実行されます。 1. `.csv`ファイルを使用して従業員データを一括で読み込みます。 2. JSONファイルを使用してフォルダ構造を定義するか、ユーザーのローカルディレクトリから構造をアップロードします。 3. 新しい管理対象ユーザーごとに、あらかじめ決められた個人用フォルダ構造を作成します。 ## 前提条件 ### Windows [.NET Core](https://dotnet.microsoft.com/download)の最新バージョンのインストール ### macOSおよびLinux [PowerShell](https://docs.microsoft.com/en-us/powershell/scripting/install/installing-powershell?view=powershell-7.2)のインストール 問題が発生する場合は、[.NET Core](https://dotnet.microsoft.com/download)と[PowerShell](https://docs.microsoft.com/en-us/powershell/scripting/install/installing-powershell?view=powershell-7.2)の両方をインストールしたかどうか確認してください ### Box CLI スクリプトを使用するには、Box CLIをインストールし、構成する必要があります。まだの場合は、このクイックスタートガイドの[手順1](g://cli/quick-start/create-oauth-app)を参照してください。または、[開発者コンソール](https://app.box.com/developers/console)に移動し、[OAuth 2.0を使用した設定](g://authentication/oauth2/oauth2-setup)ガイドに従ってください。 ### 個人用フォルダの親フォルダの作成 このスクリプトは、作成される各ユーザーにフォルダ構造を作成することで動作します。そのためには、すべての個人用フォルダが格納される親フォルダを作成する必要があります。そうしないと、すべてのフォルダは、CLIの設定に使用したユーザーのルートに格納されます。このフォルダは、好きな場所に名前を付けて配置できますが、CLIの設定に使用したユーザーにそのフォルダへのアクセス権限を付与する必要があります。 スクリプト実行後の構造の例を次に示します。 ## スクリプトのダウンロード 任意のディレクトリにスクリプトを複製し、そのディレクトリに移動します。 ``` git clone https://github.com/box/boxcli.git box-cli cd box-cli/examples/User\ Creation\ \&\ Provisioning/ ``` ## スクリプト設定の構成 自分の環境で実行できるようにスクリプトを調整します。この例では、スクリプトに用意されているサンプルデータを使用します。 ### パラメータの指定 スクリプトを実行する前に指定する必要があるパラメータがいくつかあります。 - `EmployeeList`: `Employee List` CSVのパス。 - `PersonalFolderParentID`: 入力にJSONファイルを使用してフォルダ構造を作成するかローカルの構造をアップロードするときに、すべての個人用フォルダが作成される宛先フォルダID。このフォルダは、初めてスクリプトを実行する前に作成する必要があります。この値を`0`にすることはお勧めしません。この値に設定した場合、CLIの設定に使用したアカウントのルートに個々の個人用フォルダが作成されるためです。 - `FolderStructureJSONPath`: 所有するフォルダ構造のJSONパス。 - `PersonalFolderSlug`: 個人用フォルダの親として作成されるフォルダ名の末尾に使用される文字列。デフォルトでは`Personal Folder`に設定されていますが、必要に応じて自由に設定できます。ユーザー名にこの値を連結して、各ユーザーの個人用フォルダの名前が作成されます (例: `rsmith2's Personal Folder`)。 - `LocalUploadPath`: フォルダ構造を直接アップロードするためのローカルディレクトリ。 ローカルのアップロードパスまたはフォルダ構造のJSONファイルを指定してください。両方は指定できません。 ### ユーザーリストの更新 ユーザーを読み込むには、サンプルファイル`Employees_1.csv`、`Employees_5.csv`、`Employees_10.csv`を使用できます。それぞれのファイルでは、新しいユーザーが1人、5人、10人読み込まれます。 これらのファイルをテスト実行用にカスタマイズします。たとえば、`Employees_1.csv`を次のデータで更新します。 ``` firstName,lastName,email,username Isaac,Newton,abc@abc.local,INewton23 ``` `EmployeeList`パラメータを使用して、データを読み込む`.csv`ファイルを指定します。 メールアドレスは、Box全体で一意である必要があります。また、ユーザー名は特定のBoxインスタンスで一意である必要があります。そうでない場合は、スクリプトを実行したときにエラーがスローされます。 ### フォルダ構造の作成 フォルダ構造は、JSONファイルから作成するか、ローカルドライブからアップロードすることができます。 #### JSONファイルを使用する `Folder_Structure.json`ファイルは、作成するフォルダ構造を含んでいます。たとえば、`Market Research`フォルダと`Sales Plays`フォルダを作成し、それぞれにサブフォルダ`Statistics`と`Big Pharma`を作成するとします。このスクリプトは、このフォルダ構造を、指定した親フォルダ内にある当該ユーザーの`Personal Folder`フォルダの下に配置します。 `FolderStructureJSONPath`パラメータを使用して、`Folder_Structure.json`ファイルの場所を指定します。 #### ローカルドライブからアップロードする フォルダ構造をローカルファイルシステムから直接アップロードすることもできます。`LocalUploadPath`パラメータを使用して、アップロードするローカルフォルダのパスを指定します。このフォルダは、名前はそのままで、JSONファイルを使用した方法と同様にアップロードされます。 ### パラメータの更新 スクリプトを実行する前にパラメータを渡す方法は3つあります。 スクリプトで静的な値を使用する 実行する前に、スクリプト内のすべての必須パラメータを忘れずに更新してください。 ``` # Set Employee List CSV Path # firstname, lastname, email, username $EmployeeList = "" # Personal Folder Structure: Set either path build off JSON or directly upload # a local folder $FolderStructureJSONPath = "" $LocalUploadPath = "" # Ending slug of folder that will be used in creating personal folders for new # users. Value will get concatenated with username # If username is RSMITH, the personal folder name would be # RSMITH's Personal Folder $PersonalFolderSlug = "" # ID of parent folder for created personal folders to be created in # This folder should be created before running the script the first time. # It is not advised to make this value 0, as this will create individual # Personal folders in root of the account you set up the cli with $PersonalFolderParentID = "" ``` パラメータを指定してスクリプトを実行する スクリプトの実行中にパラメータを指定できます。以下に例を示します。 ``` PS > ./Users_Create_Provision.ps1 -EmployeeList ./Employees_1.csv ` -LocalUploadPath ./PersonalLocalUpload ` -PersonalFolderSlug "Personal Folder" ` -PersonalFolderParentID 123456789 Starting User Creation & Provisioning script... ``` 求められたときにパラメータを指定する 実行時に指定されていないパラメータがある場合は、スクリプトにより、指定するよう求められます。 ``` PS > ./Users_Create_Provision.ps1 Please enter the path to the employee list CSV file: ./Employees_1.csv Please enter the path to the folder structure JSON file or the local upload path: Folder_Structure.json Folder structure JSON path set to: Folder_Structure.json Please enter the ID of the folder where you would like to create the personal folders: 0 Starting User Creation & Provisioning script... ``` ## スクリプトの実行 1. ディレクトリを、スクリプトが格納されているフォルダに変更します。この例では、`User Creation & Provisioning`フォルダになります。 ``` pwsh ``` 1. スクリプトを実行します: ``` PS /home/rvb/box-cli/examples/User Creation & Provisioning> ./Users_Create_Provision.ps1 ``` ``` The response will be similar to the following: ``` ``` Starting User Creation & Provisioning script... firstName lastName email --------- -------- ----- Isaac Newton abc@abc.local Extracting folder structure Found current User ID: 18622116055 Created a user owned Onboarding folder with id: 164734146745 Created subfolder Market Research under Onboarding folder with id: 164735375585 Created subfolder under Statistics folder with id: 164734956242 Created subfolder Sales Plays under Onboarding folder with id: 164735683001 Created subfolder under Big Pharma folder with id: 164736160637 Creating employee Managed User account with first name: Isaac, last name: Newton, email: abc@abc.local, and Created Managed user with id: 19605663027 Type: collaboration ID: '37250833128' Created By: Type: user ID: '18622116055' Name: Rui Barbosa Login: barduinor@gmail.com Created At: '2022-06-07T13:58:05-07:00' Modified At: '2022-06-07T13:58:05-07:00' Expires At: null Status: accepted Accessible By: Type: user ID: '19605663027' Name: Isaac Newton Login: abc@abc.local Invite Email: null Role: viewer uploader Acknowledged At: '2022-06-07T13:58:05-07:00' Item: Type: folder ID: '164734146745' Sequence ID: '0' ETag: '0' Name: Onboarding Collaborated Managed User Isaac Newton to current users Onboarding folder for provisioning ``` ## 新規ユーザーに対するスクリプトの再実行 会社で新しい従業員を雇用するたび、このスクリプトを定期的に実行することは一般的です。単に`.csv`ファイルを編集し、前の行のユーザーを削除して新規ユーザーの情報を追加するだけです。その後、スクリプトを再度実行できます。 ## まとめ Box CLIとともにPowerShellスクリプトを使用した、ユーザーのプロビジョニングと最初のフォルダ構造の作成の自動化について確認しました。 その他のユースケースについては、他の[サンプルスクリプト](g://cli/scripts)を確認してください。 サンプルスクリプトを使用して繰り返し発生するタスクを自動化する方法を理解しました **Source:** [https://ja.developer.box.com/guides/cli/quick-start/powershell-script-templates/](https://ja.developer.box.com/guides/cli/quick-start/powershell-script-templates/) --- ### Box Doc Gen **Type:** guide | **Category:** Box Doc Gen | **Section:** Developer Guides Box Doc Gen Box Doc Genを使用すると、採用通知書、売買契約書、請求書、契約書などのビジネスドキュメントを生成できます。BoxにアップロードされたBox Doc Genテンプレートに基づいた、Box Doc Gen API… # Box Doc Gen Box Doc Genを使用すると、採用通知書、売買契約書、請求書、契約書などのビジネスドキュメントを生成できます。BoxにアップロードされたBox Doc Genテンプレートに基づいた、Box Doc Gen APIを使用して動的に入力できるデータフィールドを含むドキュメントを生成できます。 Box Doc Genでは、Box Doc Genテンプレートの使用時に英語のテンプレートタグを利用する機能のみがサポートされています。お客様には、Box Doc Genがご希望の言語の要件をサポートしているかどうかをテストおよび確認することをお勧めします。 ## 前提条件 - Microsoft Wordへのアクセス権限 Box Doc Genを使用するには、ドキュメントテンプレートの作成に必要になるため、Microsoft Wordへのアクセス権限が必要です。Box Doc Genアドインを利用してコード不要のエクスペリエンスを実現するか、Word内でタグ付きスクリプトを適用してドキュメントを準備することができます。 Box Doc Genは、ビジネスドキュメントの動的な生成を容易にすることを目的としていますが、Boxでは、ユーザーのMicrosoft Wordに対するアクセス権限を制御していないことに注意してください。ユーザーは、ドキュメントテンプレートを効果的に作成するために必要なMicrosoft Wordに対する権限やアクセス権限があることを確認する必要があります。 ## Box Doc Gen APIの機能 Box Doc Gen APIを使用すると、以下のことが可能です。 - ドキュメントをBox Doc Genテンプレートとして設定する。 - Boxに保存したBox Doc Genテンプレートに基づいてドキュメントを生成する。 - Box Doc Genテンプレートやドキュメント生成ジョブの詳細を調査する。 ## Box Doc Gen APIバージョン Box Doc Gen APIはBox APIバージョン`2025.0`でリリースされました。Box Doc Gen APIのエンドポイントに対するすべてのAPIリクエストでは、`box-version`ヘッダーを`2025.0`に設定して、有効なAPIバージョンを指定する必要があります。 詳細については、[APIのバージョン戦略](g://api-calls/api-versioning-strategy)を参照してください。 ## Box Doc Genのワークフロー 1. Box Doc Genテンプレートを作成します。 - [Microsoft Word用Doc Genアドイン](https://support.box.com/hc/en-us/articles/36587535449747-Installing-Box-Doc-Gen-Add-in)を使用して、コードを使用せずにテンプレートを作成する。 - [Doc Genのタグ付きスクリプト](https://support.box.com/hc/en-us/articles/36149723736723-Template-tags-reference)を利用してテンプレートを作成することも可能。 1. Box Doc Gen UIを使用して[Boxにテンプレートを追加](https://support.box.com/hc/en-us/articles/36587432368275-Managing-Box-Doc-Gen-Templates-in-Relay)します。この時点では、以下のことが可能です。 - Box内の既存のファイルをDoc Genテンプレートとして設定する。 - ドキュメントを作成またはアップロードして、Box Doc Genテンプレートとして設定する。 1. Box Doc Gen APIを使用して[ドキュメントを生成](g://docgen/generate-document)する。 **Source:** [https://ja.developer.box.com/guides/docgen/](https://ja.developer.box.com/guides/docgen/) --- ### Box Doc Genジョブ **Type:** guide | **Category:** Box Doc Gen | **Section:** Developer Guides Box Doc Genジョブ Box Doc Genジョブは、ドキュメントを生成するリクエストを行うと実行されます。POSTリクエスト内のdocument_generation_dataパラメータは、ドキュメントを生成するためのBox Doc Gen… # Box Doc Genジョブ Box Doc Genジョブは、ドキュメントを生成するリクエストを行うと実行されます。`POST`リクエスト内の`document_generation_data`パラメータは、ドキュメントを生成するためのBox Doc Genジョブの実行を表すエントリの配列です。 Box Doc Gen APIを使用すると、Box Doc Genジョブに関する情報を取得できます。 ## 前提条件 Box Doc Gen APIの使用を開始する前に、[Box Doc Genの使い方](g://docgen/docgen-getting-started)ガイドに記載されている手順に従って、PlatformアプリとBox Doc Genテンプレートを作成してください。 ## すべてのBox Doc Genジョブのリストを取得 実行されたすべてのBox Doc Genジョブのリストを取得するには、`GET /2.0/docgen_jobs`エンドポイントを使用します。追加のパラメータを指定する必要はありません。 ## IDを指定してBox Doc Genジョブを取得 特定のBox Doc Genジョブを取得するには、`GET /2.0/docgen_jobs_id`エンドポイントを使用して、`job_id`を指定します。 ## 特定のIDを使用してバッチ内のGet Box Doc Genジョブを取得 単一のリクエストで複数のドキュメントを生成できます。このような場合、個別の生成ジョブが各ドキュメントに対して実行され、これらすべてのジョブが1つの「バッチ」(つまり、1つのリクエスト) に含まれます。1つのリクエスト内で実行されたすべてのジョブを取得するには、`GET /2.0/docgen_batch_jobs_id`エンドポイントを使用し、`batch_id`を指定します。 **Source:** [https://ja.developer.box.com/guides/docgen/docgen-jobs/](https://ja.developer.box.com/guides/docgen/docgen-jobs/) --- ### Box Doc Genテンプレート **Type:** guide | **Category:** Box Doc Gen | **Section:** Developer Guides Box Doc Genテンプレート Box Doc Gen APIを使用すると、Box Doc Genテンプレートに関連した情報を取得できます。 前提条件 Box Doc Gen APIの使用を開始する前に、Box Doc Gen… # Box Doc Genテンプレート Box Doc Gen APIを使用すると、Box Doc Genテンプレートに関連した情報を取得できます。 ## 前提条件 Box Doc Gen APIの使用を開始する前に、[Box Doc Genの使い方](g://docgen/docgen-getting-started)ガイドに記載されている手順に従って、PlatformアプリとBox Doc Genテンプレートを作成してください。 ## Box Doc Genテンプレートのリストを取得 作成されたすべてのBox Doc Genテンプレートのリストを取得するには、`GET /2.0/docgen_templates`エンドポイントを使用します。追加のパラメータを指定する必要はありません。 レスポンスには、すでに作成済みのBox Doc Genテンプレートを列挙する`entries`配列が含まれます。 ## IDを指定してBox Doc Genテンプレートを取得 特定のBox Doc Genテンプレートを取得するには、`GET /2.0/docgen_templates_id`エンドポイントを使用し、`template_id`を指定します。 レスポンスには、Box Doc Genテンプレートとして使用されたファイルの詳細が含まれます。 ## テンプレートのすべてのドキュメント生成ジョブのリストを取得 作成済みのすべてのBox Doc Genテンプレートのリストを取得するには、`GET /2.0/docgen_template_jobs_id`エンドポイントを使用し、`template_id`を指定します。 レスポンスには、ドキュメントを生成するために実行されたBox Doc Genジョブのリストが含まれます。 **Source:** [https://ja.developer.box.com/guides/docgen/docgen-templates/](https://ja.developer.box.com/guides/docgen/docgen-templates/) --- ### Box Doc Genの使い方 **Type:** guide | **Category:** Box Doc Gen | **Section:** Developer Guides Box Doc Genの使い方 Box Doc Gen APIを使用したドキュメントの生成を開始するには、Platformアプリケーションと、コールを認証するための開発者トークンが必要です。また、ドキュメントの入力ソースとして機能するDoc Genテンプレートも必要です。 Box… # Box Doc Genの使い方 Box Doc Gen APIを使用したドキュメントの生成を開始するには、Platformアプリケーションと、コールを認証するための開発者トークンが必要です。また、ドキュメントの入力ソースとして機能するDoc Genテンプレートも必要です。 ## Box Doc Genの有効化 Box Doc Genを使用するには、管理者が管理コンソールで有効にしていることを確認してください。Box管理者の場合、[Enterprise設定: [コンテンツと共有] タブ](https://support.box.com/hc/en-us/articles/4404822772755-Enterprise-Settings-Content-Sharing-Tab#h_01FYQGK5RW42T07GV985MQ9E9A)のドキュメントで必要な情報を確認できます。 ## Box Doc Genテンプレートの作成とアップロード Box Doc Gen APIを使用してドキュメントを生成するには、Box Doc GenテンプレートがすでにBox内に存在する必要があります。テンプレートを作成するには、以下のオプションがあります。 - [Microsoft Word用Box Doc Gen Template Creatorアドイン](https://support.box.com/hc/en-us/articles/36587535449747-Installing-Box-Doc-Gen-Add-in)をインストールする。 - [JSONファイルを使用](https://support.box.com/hc/en-us/articles/36148012877843-Creating-a-Box-Doc-Gen-Template-using-JSON-data)してBox Doc Genテンプレートを作成するか、手動で[テンプレートタグ](https://support.box.com/hc/en-us/articles/36151895655059-Creating-A-Box-Doc-Gen-Template-Manually)を作成する。 ## Platformアプリケーションの作成 まず、コールの実行に使用するPlatformアプリケーションを作成する必要があります。アプリケーションを作成するには、[Platformアプリの作成](g://applications/app-types/platform-apps)に関するガイドに従ってください。 ## 開発者トークンの生成 リクエストの送信時にアプリを認証するには、開発者トークンが必要です。 トークンを生成するには、以下の手順を実行します。 1. [**開発者コンソール**] > [**Platformアプリ**] に移動します。 2. 右側の**オプションメニュー**ボタン ([…]) をクリックします。 3. [**開発者トークンを生成**] を選択します。トークンが自動的に生成され、クリップボードに保存されます。 アプリを開いて、[**構成**] > [**開発者トークン**] に移動してトークンを生成することもできます。 開発者トークンの有効期限は1時間のみです。 詳細については、[開発者トークン](g://authentication/tokens/developer-tokens)を参照してください。トークンを生成したら、cURLや他のクライアント ([Postman](g://tooling/postman)など) で使用してコールを実行できます。 ## Webhookの使用 Webhookを作成して、Doc Genイベントを監視したり、ビジネスプロセスやワークフローを自動化したりできます。 [Webhookの追加](g://webhooks/v2/create-v2/)手順に従います。コンテンツタイプは、Doc Genテンプレートファイルまたはフォルダです。 サポートされている[イベント](g://webhooks/triggers)は以下のとおりです。 - `DOCGEN_DOCUMENT_GENERATION_STARTED` - `DOCGEN_DOCUMENT_GENERATION_SUCCEEDED` - `DOCGEN_DOCUMENT_GENERATION_FAILED` 通知に掲載される情報は以下のとおりです。 - トリガー名 - Webhookトリガーのタイムスタンプ - テンプレートファイルID - テンプレートファイルバージョンID - テンプレートファイル名 - 保存先フォルダ - 生成されたファイルのID (ドキュメント生成プロセスが成功した場合) - 出力タイプ (DOCXまたはPDF) - 理由 (ドキュメント生成プロセスが失敗した場合) **Source:** [https://ja.developer.box.com/guides/docgen/docgen-getting-started/](https://ja.developer.box.com/guides/docgen/docgen-getting-started/) --- ### Box Editのカスタムドメイン **Type:** guide | **Category:** Boxの埋め込み | **Section:** Developer Guides Box Editのカスタムドメイン サードパーティ製ウェブアプリとBox Toolsを統合するには、アプリケーションのURLを明示的に追加する必要があります。Windowsでは、そのためにレジストリキーを追加します。macOS… # Box Editのカスタムドメイン サードパーティ製ウェブアプリとBox Toolsを統合するには、アプリケーションのURLを明示的に追加する必要があります。Windowsでは、そのためにレジストリキーを追加します。macOSでは、ターミナルコマンドをいくつか実行してドメインの追加と削除を実行する必要があります。 セーフリストへのドメインの追加機能は、**Box Toolsバージョン4.5.0**で追加されました。 ## セーフリストへの追加 (Windowsの場合) セーフリストへのドメインの追加を開始する前に、[こちら](https://cloud.box.com/s/kvc9cysgq1y2yldpvciwlpt7093ho78l)で提供されている`.rar`から必要なスクリプトをダウンロードしてください。 ### ユーザーごとの設定 テキストエディタで`Add_OpenWith_WhiteListed_Domain.reg`を開きます。 エントリを追加する際は、改行して追加します。 ファイルを閉じて (変更を保存して)、管理者権限でコマンドプロンプトを開き、.regファイルに移動して次のコマンドを入力します。 ``` reg import "Add_OpenWith_WhiteListed_Domain.reg" ``` ### マシンごとの設定 テキストエディタで次のファイルを開きます。 - `x64`: `Per Machine\64 bit\Add_OpenWith_WhiteListed_Domain.reg` - `x86`: `Per Machine\32 bit\Add_OpenWith_WhiteListed_Domain.reg` プレースホルダのドメインを、許可したいドメインに置き換えます。 エントリを追加する際は、改行して追加します。 ファイルを閉じて (変更を保存して)、管理者権限でコマンドプロンプトを開き、.regファイルに移動して次のコマンドを入力します。 ``` reg import "Add_OpenWith_WhiteListed_Domain.reg" ``` 以下のいずれかの方法を使用して、Windowsサービスである**Box Local Com Service** (`Box Edit.exe`) を再起動します。 #### コマンドプロンプトを使用する場合 コマンドプロンプトで、以下のコマンドを入力します。 - `net stop "Box Local Com Service"` - `net start "Box Local Com Service"` #### UIを使用する場合 `Windows + R`を押して、`services.msc`を入力します。 システムトレイで`Box Edit`を見つけて`Box Edit.exe`を再起動します。 右クリックして [**終了**] を選択します。 `%programfiles%\Box\Box Edit`を開いて、`Box Edit.exe`を実行します。 ### 削除 - すべてのドメインを一度に削除するには、`Remove_ALL_OpenWith_WhiteListed_Domain.reg`を実行します。 - 特定のドメインを削除するには、`Remove_OpenWith_WhiteListed_Domain.reg`を実行します。上記の手順に従ってこの.regにドメインに追加すると、ドメインが削除されます。 ## セーフリストへの追加 (macOSの場合) ### 手順 [こちら](https://cloud.box.com/s/z5qhc7rts6mzrhzfx6cpxeb5ed4ve5u6)からbashスクリプトをダウンロードします。 ターミナルを開いて、bashスクリプトをダウンロードしたフォルダに移動し、次のコマンドを実行して適切な権限を追加します。 ``` chmod u+rx OpenWith.sh ``` ドメインを**追加**するには、ターミナルで次のコマンドを実行します。 ``` ./OpenWith.sh -a domain1 domain2 ... ``` ドメインを**削除**するには、ターミナルで次のコマンドを実行します。 ``` ./OpenWith.sh -r domain1 domain2 ... ``` ドメインを**すべてクリア**するには、ターミナルで次のコマンドを実行します。 ``` ./OpenWith.sh -c ``` すべてのドメインの**リストを取得**するには、ターミナルで次のコマンドを実行します。 ``` ./OpenWith.sh -l ``` ### メモ - セーフリストにドメインを追加する際は、必ず、HTTPプロトコル (`https://`など) または末尾のパス (`yourdomain.com/page/3`など) を付けずにドメインを入力してください。 - すべてのリクエストは、主にHTTPS経由のセキュアなオリジンから送信されます。 - ワイルドカード`*`がサポートされているため、セーフリストにサブドメインとポートを追加できます。たとえば、リストに`*.yourdomain.com`を追加することで、すべてのサブドメインをセーフリストに追加できます。 ## アンインストール Box Toolsをアンインストールすると、すべてのドメインが削除されます。 **Source:** [https://ja.developer.box.com/guides/embed/ui-elements/custom-domains/](https://ja.developer.box.com/guides/embed/ui-elements/custom-domains/) --- ### Box Embed **Type:** guide | **Category:** Boxの埋め込み | **Section:** Developer Guides Box Embed Box EmbedはHTMLベースのフレームワークで、これにより、独自に作成したアプリケーションにBoxウェブアプリの機能全体を埋め込むことができます。Box Embedを使用すると、ファイルのアップロード、検索、コメント付け、共有、タグ付けに加え、Box… # Box Embed Box EmbedはHTMLベースのフレームワークで、これにより、独自に作成したアプリケーションにBoxウェブアプリの機能全体を埋め込むことができます。Box Embedを使用すると、ファイルのアップロード、検索、コメント付け、共有、タグ付けに加え、Box Editを使用したファイルの編集も可能になります。 ## 開始する前に ウィジェットを作成するには、以下のことが必要です。 - 共有用の埋め込み可能な要素 (**フォルダ**、**ファイル**、**Hub**、**メモ**、**アプリ**など) を設定する。 - **ビューアー**以上の[権限](https://support.box.com/hc/ja/articles/360044196413-%E3%82%B3%E3%83%A9%E3%83%9C%E3%83%AC%E3%83%BC%E3%82%BF%E3%81%AE%E6%A8%A9%E9%99%90%E3%83%AC%E3%83%99%E3%83%AB%E3%81%AB%E3%81%A4%E3%81%84%E3%81%A6)がある。 ## ウェブアプリの使用 BoxウェブアプリからBox埋め込みウィジェットのコードを取得するには、以下の手順を実行します。 ### ファイルとフォルダ 1. 選択したファイルまたはフォルダに移動します。 2. そのフォルダの横にある省略記号をクリックします。 3. [**その他の操作**] > [**埋め込みウィジェット**] に移動します。 ### Hub 1. 選択したHubに移動します。 2. 右上にある省略記号メニューをクリックします。 3. [**Hubを埋め込む**] をクリックします。 ### メモ 1. 選択したBox Noteに移動します。 2. 省略記号メニューをクリックします。 3. [**埋め込みウィジェット**] をクリックします。 ### アプリ 1. 選択したBoxアプリまたはBoxアプリビューに移動します。 2. 省略記号メニューをクリックします。 3. [**埋め込む**] をクリックします。 次の手順では、埋め込み可能な要素のパラメータを構成します。 | ファイル | フォルダ | Hub | メモ | アプリ | | --- | --- | --- | --- | --- | | ウィジェットのサイズ | ウィジェットのサイズ、フォルダ内のファイルの並べ替え、ナビゲーションパスとサイドバーの非表示。 | ウィジェットのサイズ、親のナビゲーションパスとサイドバーの非表示 | ウィジェットのサイズ、クラウド (雲) ゲームのスキップ (その結果、メモは読み取り専用モードになります)、メモのナビゲーションの非表示。 | ウィジェットのサイズ | 埋め込みウィジェットのカスタマイズが完了したら、埋め込みコードをコピーして自分のサイトまたはウェブアプリに貼り付けます。 ## プログラムを使用して構成 Box Embedをさらにカスタマイズする場合は、プログラムを使用して実行できます。埋め込みのスニペットの形式は次のとおりです。 ``` <iframe src="https://{custom_domain}.app.box.com/embed/s/{shared link value}?view={list or icon}&sortColumn={name, date, or size}&sortDirection=ASC" width="{pixels}" height="{pixels}" frameborder="0" allowfullscreen webkitallowfullscreen msallowfullscreen ></iframe> ``` ### 共有リンクの値の検索 プログラムを使用して埋め込み`iframe`を構築するには、まず、共有リンクの値を生成または検索します。この値を検索する1つの方法として、Boxウェブアプリを使用します。 また、[`PUT /files/:file_id`](e://put-files-id--add-shared-link)または[`PUT /files/:file_id`](e://put-folders-id--add-shared-link)を使用して、APIで共有リンクを作成する方法もあります。 その後、[`GET /files/:id`](e://get-files-id)または[`GET /folders/:id`](e://get-folders-id)エンドポイントを使用してクエリパラメータ`fields=shared_link`を渡すことにより、この共有リンクの値を検索できます。 ``` curl https://api.box.com/2.0/folders/12345?fields=shared_link \ -H "authorization: Bearer ACCESS_TOKEN" ``` ``` "shared_link": { "url": "https://app.box.com/s/dsbJFzdO7qZxdfOHFzdO7qZxdfOH", "download_url": null, "vanity_url": null, ... } ``` ページをルートフォルダ/[すべてのファイル] ページに設定することもできます。URLを共有リンク`<iframe src=“https://app.box.com/embed/folder/0”….></iframe>`ではなく`/folder/0`に設定してください。 ### パラメータ 次に、表示のカスタマイズオプションを選択します。構成可能なパラメータ (省略可) のリストを以下に示します。 | | | | --- | --- | | hideHubsGallery | Hubsギャラリーに戻るためのナビゲーションの山括弧ボタンを非表示または表示します。trueまたはfalse (デフォルト) を指定できます。 | | hideNavigationControls | Box Notesのナビゲーションコントロールを非表示または表示します。 | | showItemFeedActions | ファイルのコメントまたはタスクを非表示または表示します。true (デフォルト) またはfalseを指定できます。 | | showParentPath | フレームのヘッダーにフォルダパスを非表示または表示します。trueまたはfalse (デフォルト) を指定できます。 | | sortColumn | ファイルまたはフォルダを並べ替える順番。name、date (デフォルト)、または、sizeを指定できます。 | | sortDirection | ファイルまたはフォルダの並べ替えの方向。ASC (デフォルト) またはDESCを指定できます。 | | view | ファイルまたはフォルダの表示方法の種類。list (デフォルト) またはiconを指定できます。ログインユーザーの場合は、ユーザー設定の表示方法が優先されます。 | | uxLite | クラウド (雲) ゲームを使用せず、制限付きコンテンツプレビュー (Preview Light) を表示します。共有ファイルおよびBox Notesのみに有効です。 | Box Notesで`uxLite`を使用すると、`hideNavigationControls`の設定に関わらず、ナビゲーションコントロールは表示されません。 Boxが提供するアプリのURLにあるカスタム検索パラメータはすべて、埋め込みウィジェットウィンドウとコンテンツプレビューに渡されます。 ### 全画面表示機能 Box Embedスニペットの全画面表示機能を有効にするために、オブジェクトを全画面に表示可能にする場合は、以下のパラメータの1つ以上を`<iframe>`に含めてください。 - `allowfullscreen` - `webkitallowfullscreen` - `mozallowfullscreen` - `oallowfullscreen` - `msallowfullscreen` ## 有効期限付き埋め込みリンク ファイルの場合、[`GET /files/:id`](e://get-files-id)を呼び出し、`fields`クエリパラメータを使用して`expiring_embed_link`をリクエストすることもできます。 ``` curl https://api.box.com/2.0/files/12345?fields=expiring_embed_link \ -H "authorization: Bearer ACCESS_TOKEN" ``` ``` { "etag": "1", "expiring_embed_link": { "token": { "access_token": "1!rFppcinUwwwDmB4G60nah7z...", "expires_in": 3646, "restricted_to": [ { "object": { "etag": "1", "file_version": { "id": "34567", "sha1": "1b8cda4e52cb7b58b354d8da0068908ecfa4bd00", "type": "file_version" }, "id": "12345", "name": "Image.png", "sequence_id": "1", "sha1": "1b8cda4e52cb7b58b354d8da0068908ecfa4bd00", "type": "file" }, "scope": "base_preview" }, ... ], "token_type": "bearer" }, "url": "https://cloud.app.box.com/preview/expiring_embed/...." }, "id": "12345", "type": "file" } ``` `url`属性を`<iframe>`内で使用すると、自動で期限切れになるBox Embedインターフェースを埋め込むことができます。 ``` <iframe src="YOUR-GENERATED-BOX-EMBED-LINK" width="{pixels}" height="{pixels}" frameborder="0" allowfullscreen webkitallowfullscreen msallowfullscreen /> ``` ### パラメータ UIをカスタマイズするために、このURLにさらにパラメータを追加することもできます。そのためには、以下のパラメータをクエリパラメータとして`url`に追加します。最終的なURLは、次のようになります。 ``` https://app.box.com/preview/expiring_embed/[HASH]?[parameterName]=true ``` | | | | --- | --- | | showDownload | ファイルをダウンロードするための権限がビューアーにある場合は、埋め込まれたヘッダーバーにダウンロードボタンが表示されます。また、印刷とダウンロードが同じ権限で管理されているため、ドキュメントのファイルタイプには印刷ボタンも表示されます。デフォルトではfalseになります。 | | showAnnotations | プレビュー以上の権限を持つユーザーは、ドキュメントと画像のプレビューに注釈を付けることができます。また、すでにドキュメントに付けられている注釈も表示されます。注釈が利用可能なファイルタイプおよび注釈の種類の詳細については、注釈ページを参照してください。現在、注釈はウェブブラウザでのみ使用できます。モバイルブラウザでは、ユーザーは注釈を表示できますが、新しい注釈を作成することはできません。 | ## クラウド (雲) ゲーム クラウド (雲) ゲームとは、[クリックジャッキング](https://support.box.com/hc/ja/articles/360043691034-Box%E3%81%AF%E3%81%A9%E3%81%AE%E3%82%88%E3%81%86%E3%81%AB%E3%81%97%E3%81%A6%E3%82%AF%E3%83%AA%E3%83%83%E3%82%AF%E3%82%B8%E3%83%A3%E3%83%83%E3%82%AD%E3%83%B3%E3%82%B0%E3%82%92%E9%98%B2%E6%AD%A2%E3%81%97%E3%81%A6%E3%81%84%E3%81%BE%E3%81%99%E3%81%8B)を防ぐために作成されたウィジェットです。これは、パートナー統合ではない埋め込みサイトに表示されます。クラウド (雲) ゲームでは、ユーザーは、操作の許可を得るためにクラウド (雲) を適切な場所にドラッグする必要があります。このゲームでは、クラウド (雲) の位置とそのドラッグ先がランダムに生成されるため、クリックジャッキングが難しくなります。 `postMessage()`は、埋め込みと`showCloudGame`両方のステータスを取得するためにiframeで使用されます。埋め込まれている場合、`document.hasStorageAccess()`は、BoxからCookieにアクセスできるかどうかを示します。アクセスでき、ユーザーがログイン済みの場合、クラウド (雲) ゲームが表示されます。`showCloudGame`のステータスが`false`の場合、ユーザーはログインページに誘導されます。 ## カスタムロゴ 有料のBoxをお使いの場合は、ファイルのプレビューに表示されるBoxのロゴを削除できます。削除するには、**管理コンソール**の [**Enterprise設定**]、[**カスタム設定**] に移動し、[**埋め込みウィジェットのカスタマイズ**] をオフに切り替えてBoxのロゴを非表示にします。 ## 制限 Box Embedは、モバイルブラウザ向けには最適化されていないため、モバイルデバイス用に設計されたウェブエクスペリエンスでは使用しないでください。多くのUI Element (**ダウンロード**オプションや**印刷**オプションなど) はモバイルブラウザに表示されない可能性があります。 **Source:** [https://ja.developer.box.com/guides/embed/box-embed/](https://ja.developer.box.com/guides/embed/box-embed/) --- ### Box for Agentforce拡張パッケージ **Type:** guide | **Category:** ツール | **Section:** Developer Guides Box for Agentforce拡張パッケージ Box for Agentforce拡張パッケージは、Box for Salesforce管理パッケージの拡張機能です。この拡張機能は、Salesforce… # Box for Agentforce拡張パッケージ [Box for Agentforce拡張パッケージ](https://support.box.com/hc/en-us/articles/40370228349331-Installing-Box-for-Agentforce)は、Box for Salesforce管理パッケージの拡張機能です。この拡張機能は、Salesforce内でワークフローを自動化したり、インテリジェントなエージェントベースのプロセスを強化したりするのに役立つ、再利用可能なAgentforce[アクション](g://tooling/salesforce-toolkit/flow-actions)を提供します。これは、Box for Salesforceパッケージのコア機能を基に作成されており、グローバルで呼び出し可能なApexメソッドを使用して機能性を高めます。Box for Agentforce拡張パッケージでは、Agentforceアクション内でBoxの名前空間を使用することでメソッドを参照します。 ## Agentforceフローのメソッド 以下のリストには、Agentforceで呼び出し可能な[メソッド](g://tooling/salesforce-toolkit/methods)の例を示しています。 ### フォルダとファイルの管理 - フォルダの作成 - フォルダの関連付けを作成 - レコードID用のフォルダを作成 - テンプレートからレコードID用のフォルダを作成 - フォルダIDでフォルダのコンテンツを取得 - レコードIDでフォルダIDを取得 - フォルダURLを取得 - フォルダの移動 - レコードIDでオブジェクトフォルダを取得 - フォルダIDでレコードIDを取得 - フォルダ用URLを取得 ### メタデータの管理 - ファイルIDでBoxメタデータを作成 - フォルダIDでBoxメタデータを作成 - ファイルIDでBoxメタデータを削除 - フォルダIDでBoxメタデータを削除 - フォルダIDでBoxメタデータを更新 - ファイルIDでBoxメタデータを取得 - フォルダIDでBoxメタデータを取得 ### コラボレーション - コラボレーションを作成 - レコードにコラボレーションを作成 - コラボレーションを編集 - コラボレーションを削除 ### その他のアクション - 添付ファイルからファイルを作成 - Doc Genのバッチを取得 - SalesforceレコードIDでフォルダの関連付けを取得 - フォルダIDでメタデータカスケードポリシーを取得 - IDでメタデータカスケードポリシーを取得 - メタデータカスケードポリシーを作成 - メタデータカスケードポリシーを削除 - Slackチャンネルマッピングを作成 - Slackチャンネルアクセス管理を無効に設定 **Source:** [https://ja.developer.box.com/guides/tooling/salesforce-toolkit/box-agentforce-package/](https://ja.developer.box.com/guides/tooling/salesforce-toolkit/box-agentforce-package/) --- ### Box MCPサーバー **Type:** guide | **Category:** Box MCPサーバー | **Section:** Developer Guides Box MCPサーバー Model Context Protocol (MCP) は、アプリケーションがLLMにコンテキストを提供する方法を標準化するオープンプロトコルです。MCPサーバーにより、高度な統合をよりシンプルかつ時間をかけずに構築できるようになります。 Box MCP… # Box MCPサーバー Model Context Protocol ([MCP](https://modelcontextprotocol.io/introduction)) は、アプリケーションがLLMにコンテキストを提供する方法を標準化するオープンプロトコルです。MCPサーバーにより、高度な統合をよりシンプルかつ時間をかけずに構築できるようになります。 Box MCPサーバーを使用すると、Copilot Studio、Cursor、Claude for Desktopなどのプラットフォームが提供するサードパーティ製AIエージェントは、Boxのコンテンツにシームレスにアクセスできるようになります。これは、Boxに保存されているコンテンツに関連した操作を実行できるようにすることで、エージェントの機能を拡張します。 Box MCPサーバーには2種類あります。 リモートBox MCPサーバー: Box管理コンソールで作成または有効化でき、Boxで直接ホストされています。 セルフホストBox MCPサーバー: このバージョンはオープンソースのBox Developer Communityプロジェクトであるため、ローカルマシンで複製してホストできます。 実装されるツールのレベルが異なるため、2種類のBox MCPサーバーに関する詳細なガイドを参照し、Box MCPサーバーを有効化する方法を確認してください。 管理コンソールでリモートBox MCPサーバーを有効にします。これはBoxで直接ホストされています。 ベータ オープンソースのBox Developer Communityプロジェクト。このBox MCPサーバーを複製し、ローカルマシンでホストすることができます。 オープンソース Box CTOのBen Kusとのインタビューを視聴し、MCPによってAIエージェントがどのようにプラットフォーム間で動的に動作し、開発の手間を軽減しているかをご覧ください。 **Source:** [https://ja.developer.box.com/guides/box-mcp/](https://ja.developer.box.com/guides/box-mcp/) --- ### Box Platformアプリの設定 **Type:** quick-start | **Category:** モバイル | **Section:** Developer Guides Box Platformアプリの設定 Box iOS SDKを使用してBox APIに対する認証済みAPIコールを開始するには、アクセストークンが必要になります。有効なトークンを生成するには、新しいBox Platform… # Box Platformアプリの設定 **Box iOS SDK**を使用してBox APIに対する認証済みAPIコールを開始するには、**アクセストークン**が必要になります。有効なトークンを生成するには、新しい**Box Platformアプリ**を生成し、有効期間が短い開発者トークンを手動で生成するのが最も簡単な方法です。 開発者トークンは、開発者コンソールのUIを介して生成されます。有効期間は1時間で、その後は手動で更新する必要があります。 ## Boxアプリのセットアップ # 新しいBoxアプリを作成する 開発者トークンの生成に使用する新しいBox JWTアプリケーションを作成して構成します。 # 既存のアプリを使用する Box開発者コンソールから既存のBox JWTアプリケーションのいずれかを使用します。 # 新しいBoxアプリを作成する 開発者トークンの生成に使用できる新しいBoxアプリケーションを作成するには、以下の手順に従います。 1. [[開発者コンソール](https://cloud.app.box.com/developers/console)] > [**Platformアプリ**] に移動します。 2. [**Platformアプリの作成**] を選択します。 3. 作成するアプリケーションの種類として [**Platformアプリ**] を選択し、[**次へ**] をクリックします。 4. [**アプリ名**] に加え、必要に応じてアプリの [**説明**] および [**目的**] を入力し、[**次へ**] で確定します。 5. 認証方法として [**ユーザー認証 (OAuth 2.0)**] を選択し、[**アプリの作成**] をクリックします。 6. 必要に応じて、同じ画面の [**アプリケーションスコープ**] セクションまでスクロールし、このアプリケーションに対して有効にする必要がある追加の権限を選択します。 7. ページ上部にある [**変更を保存**] ボタンをクリックします。 # 既存のJWT Boxアプリケーションを使用する [開発者コンソール](https://cloud.app.box.com/developers/console)に、使用したい既存のJWTベースのBoxアプリケーションがある場合は、以下の手順に従います。 ## 開発者トークンの生成 アプリケーションが使用可能になったら、開発者トークンを作成する必要があります。開発者トークンは、Box iOS SDKを認証してBox APIに対する呼び出しを開始するために使用できます。 1. [開発者コンソール](https://cloud.app.box.com/developers/console)に移動します。 2. 使用するアプリケーションを読み込みます。 3. 左のナビゲーションメニューで [**構成**] をクリックします。 4. [**開発者トークン**] で、[**開発者トークンを生成**] ボタンをクリックします。 5. 次の手順でAPIコールを行うためにトークンをコピーします。 ## まとめ - 新しいBoxアプリを作成、または既存のBoxアプリを使用しました。 - 開発者トークンを生成してコピーしました。 開発者トークンを用意できました **Source:** [https://ja.developer.box.com/guides/mobile/ios/quick-start/configure-box-app/](https://ja.developer.box.com/guides/mobile/ios/quick-start/configure-box-app/) --- ### Box Platformのサンドボックス **Type:** guide | **Category:** はじめに | **Section:** Developer Guides Box Platformのサンドボックス BoxのDeveloper… # Box Platformのサンドボックス BoxのDeveloperサンドボックスでは、制御された安全な環境を提供しています。この環境で、開発者は、企業の実際のデータに影響を及ぼすことなく、アプリケーションの作成、テスト、コラボレーションを行うことができます。このようなサンドボックスは、Box APIの実験、設定のテスト、新しい統合の試用、外部パートナーとの連携を行うための安全な領域を提供します。 ## Developerサンドボックスとは Developerサンドボックスとは、実稼働 (ライブ) Enterpriseの設定から隔離された環境であり、開発アクティビティを実際のビジネスデータから切り離しておくことができます。 ## サンドボックスを使用する理由 サンドボックスを使用すると、以下のことが可能です。 - 無料のスタンドアロンアカウントではなく、Enterpriseにリンクされている環境内で安全にアプリを開発する。 - 社内チームとも外部コラボレータとも安全にコラボレーションする。請負業者、パートナー、その他の外部ユーザーは、実際のシステムにアクセスしてセキュリティを危険にさらすことなく、サンドボックスに参加できます。 - サンドボックスは作成時に企業のプランやアドオンを継承するため、現実的なテスト条件下でアプリをテストする。プランやアドオンに変更があった場合は、Enterprise管理者が[手動で同期](https://support.box.com/hc/en-us/articles/360043697274-Managing-developer-sandboxes-for-Box-admins#:~:text=in%20a%20sandbox.-,Synchronizing,-sandbox%20with%20production)することができます。 ## サンドボックスへのアクセス Box内のサンドボックスは、Enterprise管理者によって作成されます。サンドボックスの作成方法については、[こちらのドキュメント](https://support.box.com/hc/en-us/articles/360043697274-Managing-developer-sandboxes-for-Box-admins)を参照してください。サンドボックスのプライマリ管理者に指定されると、サンドボックスのユーザーIDが記載されたログインメールがBoxから届きます。 サンドボックス環境内で[開発者コンソール](https://cloud.app.box.com/developers/console)にアクセスしてパスワードを設定するには、メールに記載されているリンクをクリックします。また、[developer.box.com](https://developer.box.com)でサンドボックスの資格情報を使用してログインすることで、サンドボックスにアクセスすることもできます。 サンドボックスのプライマリ管理者は、個々のサンドボックスアカウントを作成し、親のBox Enterpriseのプランに一致する新しいBox環境へのアクセス権限を開発者に付与することができます。 ### 複数のサンドボックスへのアクセス プライマリ管理者は、複数のサンドボックスにログインできます。既存のサンドボックスにこの機能を使用する場合は、一意のメールアドレスを削除し、システムで生成されたメールアドレスを取得します。 **Source:** [https://ja.developer.box.com/guides/getting-started/sandbox/](https://ja.developer.box.com/guides/getting-started/sandbox/) --- ### Box Relay **Type:** guide | **Category:** Box Relay | **Section:** Developer Guides Box Relay Box Relayはワークフロー自動化アプリケーションです。これを使用すると、Boxのパワーユーザーは、コンテンツが中心のビジネスプロセスを自動化してスピードアップすることができます。現在、開発者が使用できるAPI エンドポイントは… # Box Relay [Box Relay](https://support.box.com/hc/ja/articles/360044196213-Box-Relay%E3%81%AE%E6%A6%82%E8%A6%81)はワークフロー自動化アプリケーションです。これを使用すると、Boxのパワーユーザーは、コンテンツが中心のビジネスプロセスを自動化してスピードアップすることができます。現在、開発者が使用できるAPI [エンドポイント](resource://workflow)は2つありますが、ほかにも今後リリースが予定されているものがあります。2つとも[手動開始フロー](https://support.box.com/hc/ja/articles/360044628853-%E6%89%8B%E5%8B%95%E3%81%A7%E9%96%8B%E5%A7%8B%E3%81%99%E3%82%8B%E3%83%AF%E3%83%BC%E3%82%AF%E3%83%95%E3%83%AD%E3%83%BC%E3%81%AE%E4%BD%9C%E6%88%90%E3%81%A8%E5%AE%9F%E8%A1%8C)に直接動作するよう作成されました。 これらのエンドポイントの使用方法の詳細については、Boxの[ブログ](https://medium.com/@Box_Developers/%E6%89%8B%E5%8B%95%E9%96%8B%E5%A7%8B%E3%83%AF%E3%83%BC%E3%82%AF%E3%83%95%E3%83%AD%E3%83%BCapi%E3%81%A8box-relay-64f9136f1682)記事を参照してください。 ## 必須のスコープ Box Relayのエンドポイントを使用する前に、アプリケーションで以下の[スコープ](g://api-calls/permissions-and-errors/scopes)を有効にする必要があります。 - [Boxに格納されているすべてのファイルとフォルダの読み取り](g://api-calls/permissions-and-errors/scopes/#read-all-files-and-folders) - [Boxに格納されているすべてのファイルとフォルダの書き込み](g://api-calls/permissions-and-errors/scopes/#read-and-write-all-files-and-folders) - [Box Relayを管理する](g://api-calls/permissions-and-errors/scopes/#manage-box-relay) 選択した認証方法や企業の設定によっては、新たに選択したスコープを使用する前に、アプリケーションで管理者の承認または再承認が必要になる場合があります。 ## レート制限 詳細については、[レート制限ガイド](g://api-calls/permissions-and-errors/rate-limits/#per-api-rate-limits)を参照してください。 ## テスト 機能は同等であるため、APIを利用する前に、[BoxウェブアプリでBox Relay機能](https://support.box.com/hc/ja/articles/360044628853-%E6%89%8B%E5%8B%95%E3%81%A7%E9%96%8B%E5%A7%8B%E3%81%99%E3%82%8B%E3%83%AF%E3%83%BC%E3%82%AF%E3%83%95%E3%83%AD%E3%83%BC%E3%81%AE%E4%BD%9C%E6%88%90%E3%81%A8%E5%AE%9F%E8%A1%8C)に慣れておくと役に立つ可能性があります。さまざまなAPIエンドポイントと同様、実稼働環境のコンテンツに影響を及ぼすリスクを排除するために[Developerサンドボックス環境](https://support.box.com/hc/ja/articles/360043697274)でテストすることをお勧めします。 **Source:** [https://ja.developer.box.com/guides/box-relay/](https://ja.developer.box.com/guides/box-relay/) --- ### Box Sign **Type:** guide | **Category:** Box Sign | **Section:** Developer Guides Box Sign 署名リクエストの作成、リスト取得、再送信、キャンセルを実行するBox SignのAPIエンドポイントを使用することで、Box Signウェブアプリの全機能をプログラムによって利用できます。 有効化 Box Sign APIを使用したリクエストは、Business… # Box Sign 署名リクエストの作成、リスト取得、再送信、キャンセルを実行するBox SignのAPIエンドポイントを使用することで、Box Signウェブアプリの全機能をプログラムによって利用できます。 ## 有効化 Box Sign APIを使用したリクエストは、Business、Business Plus、Enterprise、Enterprise Suites、Enterprise Plus、Enterprise Advancedのアカウントでサポートされています。アカウントの種類を確認するには、[**アカウント設定**] に移動し、[**アカウント**] タブの [**アカウントの詳細**] セクションまで下にスクロールします。管理者向けのアクセス制限の詳細については、[サポート記事](https://support.box.com/hc/ja/articles/4404076971155-Box-Sign%E3%81%AE%E6%9C%89%E5%8A%B9%E5%8C%96)を参照してください。 ## 必須のスコープ Box Signのエンドポイントを使用する前に、アプリケーションで以下の[スコープ](g://api-calls/permissions-and-errors/scopes)を有効にする必要があります。 - [Boxに格納されているすべてのファイルとフォルダの読み取り](g://api-calls/permissions-and-errors/scopes/#read-all-files-and-folders) - [Boxに格納されているすべてのファイルとフォルダの書き込み](g://api-calls/permissions-and-errors/scopes/#read-and-write-all-files-and-folders) - [署名リクエストを管理する](g://api-calls/permissions-and-errors/scopes/#manage-signature-requests) 選択した認証方法や企業の設定によっては、新たに選択したスコープを使用する前に、アプリケーションで管理者の承認または再承認が必要になる場合があります。 ## イベント 詳細については、[イベントガイド](g://events/event-triggers/sign-events)を参照してください。 ## Webhook 詳細については、[Webhookガイド](g://webhooks/triggers)を参照してください。 ## レート制限 詳細については、[レート制限ガイド](g://api-calls/permissions-and-errors/rate-limits/#per-api-rate-limits)を参照してください。 ## テスト 機能が同等であるため、APIを利用する前に、[Boxウェブアプリを使用してBox Signの機能](https://support.box.com/hc/ja/articles/4404105810195-%E7%BD%B2%E5%90%8D%E7%94%A8%E3%83%89%E3%82%AD%E3%83%A5%E3%83%A1%E3%83%B3%E3%83%88%E3%81%AE%E9%80%81%E4%BF%A1)をよく理解しておくと役に立つかもしれません。すべてのAPIエンドポイントと同様に、実稼働環境のコンテンツに影響を及ぼすリスクを取り除くため、[Developerサンドボックス環境](https://support.box.com/hc/ja/articles/360043697274)でテストすることをお勧めします。 **Source:** [https://ja.developer.box.com/guides/box-sign/](https://ja.developer.box.com/guides/box-sign/) --- ### Box Signのリクエストのキャンセル **Type:** guide | **Category:** Box Sign | **Section:** Developer Guides Box Signのリクエストのキャンセル Box Signのリクエストは、まだ署名も拒否もされていない場合、Box Sign… # Box Signのリクエストのキャンセル Box Signのリクエストは、まだ署名も拒否もされていない場合、[Box Signのリクエストをキャンセルエンドポイント](e://post-sign-requests-id-cancel)を使用してキャンセルできます。未署名の署名者は、ドキュメントに署名できなくなります。 リクエストをキャンセルできるのは、そのリクエストを作成したユーザー (リクエスト送信者) のみです。リクエストは、拒否された場合、全員が署名済みの場合、ドキュメントがまだ変換中の場合は、キャンセルできません。 **Source:** [https://ja.developer.box.com/guides/box-sign/cancel-sign-request/](https://ja.developer.box.com/guides/box-sign/cancel-sign-request/) --- ### Box Signのリクエストのリスト取得 **Type:** guide | **Category:** Box Sign | **Section:** Developer Guides Box Signのリクエストのリスト取得 すべて 署名リクエストを取得エンドポイントを使用すると、渡されたアクセストークンに関連付けられたユーザーが作成したBox Signのすべてのリクエストのリストを表示できます。 IDの指定 ID… # Box Signのリクエストのリスト取得 ## すべて [署名リクエストを取得エンドポイント](e://get-sign-requests)を使用すると、渡されたアクセストークンに関連付けられたユーザーが作成したBox Signのすべてのリクエストのリストを表示できます。 ## IDの指定 [IDを指定して署名リクエストを取得エンドポイント](e://get-sign-requests-id)を使用すると、Box Signの特定のリクエストに関する情報を表示できます。このエンドポイントには、署名リクエストのIDが必要です。このIDは、[Box Signのすべてのリクエストを取得エンドポイント](e://get-sign-requests)を使用して取得するか、[Box Signのリクエストを作成](e://post-sign-requests)する際にレスポンスで取得することができます。 **Source:** [https://ja.developer.box.com/guides/box-sign/list-sign-requests/](https://ja.developer.box.com/guides/box-sign/list-sign-requests/) --- ### Box Signのリクエストの作成 **Type:** guide | **Category:** Box Sign | **Section:** Developer Guides Box Signのリクエストの作成 Box Signのリクエストを作成するには、少なくとも、署名が必要なファイル、署名済みドキュメント/署名ログの保存先フォルダ、署名者が必要です。 公開APIを使用したCFR Part 1… # Box Signのリクエストの作成 [Box Signのリクエストを作成する](e://post-sign-requests)には、少なくとも、署名が必要なファイル、署名済みドキュメント/[署名ログ](https://support.box.com/hc/ja/articles/4404095202579-%E7%BD%B2%E5%90%8D%E3%83%AD%E3%82%B0%E3%81%AE%E7%A2%BA%E8%AA%8D)の保存先フォルダ、署名者が必要です。 公開APIを使用したCFR Part 11の署名リクエストの作成はサポートされていません。詳細については、[21 CFR Part 11コンプライアンスのサポート](https://support.box.com/hc/en-us/articles/24169443030163)を参照してください。 ## ドキュメントの準備 Box Signのリクエストを送信する前にドキュメントを準備することで、開発者は署名者のために日付、テキスト、チェックボックス、署名のプレースホルダを追加できます。これを行うには、UIを使用するか、ドキュメント内で直接[タグ](https://support.box.com/hc/ja/articles/4404085855251-%E3%82%BF%E3%82%B0%E3%82%92%E4%BD%BF%E7%94%A8%E3%81%97%E3%81%9F%E3%83%86%E3%83%B3%E3%83%97%E3%83%AC%E3%83%BC%E3%83%88%E3%81%AE%E4%BD%9C%E6%88%90)を使用します。準備を行わなかった場合、署名者には準備が完了していないドキュメントが送信されるため、署名者の判断で署名やフィールドを配置できます。ただし、開発者は、準備が完了していないドキュメントの機能をオンまたはオフにするためのコントロールをリクエスト内で利用できます。 `is_document_preparation_needed`を`true`に設定すると、レスポンスで`prepare_url`が返されます。ブラウザでこのリンクにアクセスすると、ドキュメントの準備を完了し、UI上でリクエストを送信できます。 ドキュメントのタグの詳細については、[サポート記事](https://support.box.com/hc/ja/articles/4404085855251-%E3%82%BF%E3%82%B0%E3%82%92%E4%BD%BF%E7%94%A8%E3%81%97%E3%81%9F%E3%83%86%E3%83%B3%E3%83%97%E3%83%AC%E3%83%BC%E3%83%88%E3%81%AE%E4%BD%9C%E6%88%90)を参照してください。 Boxウェブアプリを使用してテンプレートに作成された事前入力タグには、APIからアクセスできません。 ## ファイル Box Signの各リクエストは、署名が必要なファイルから始まります。そのファイルがまだBoxに存在しない場合は、リクエストを作成する前に、別のAPIコールでファイルを[アップロードする](e://post-files-content)必要があります。1つのリクエストで複数のファイルに署名できます。リクエストに含まれる最初のファイルのファイルIDを`source_files`本文パラメータで指定します。 リクエスト送信者は、Box内のファイルに対してダウンロード権限を持っている必要があります。この要件を満たしているかどうかを確認するには、[コラボレーションレベル](https://support.box.com/hc/ja/articles/360044196413-%E3%82%B3%E3%83%A9%E3%83%9C%E3%83%AC%E3%83%BC%E3%82%BF%E3%81%AE%E6%A8%A9%E9%99%90%E3%83%AC%E3%83%99%E3%83%AB%E3%81%AB%E3%81%A4%E3%81%84%E3%81%A6)を確認します。 サポートされているファイルタイプは以下のとおりです。 - すべての[ドキュメント](g://representations/supported-file-types/#documents) - すべての[プレゼンテーション](g://representations/supported-file-types/#presentations) - 画像: `png`、`jpg`、`jpeg`、`tiff`のみ - テキストベースのファイル: `.csv`、`.txt`のみ すべてのファイルタイプは、署名の処理のために`.pdf`に変換されます。この変換後のドキュメントは、リクエストの送信が成功した場合に`parent_folder`で見つかります。つまり、元のファイルタイプに関係なく、最終的な署名済みドキュメントは`.pdf`になります。各署名者がリクエストを完了すると、Box Signにより新しいファイルバージョンが自動的に追加されます。 ファイルサイズの上限は、アカウントの種類によって決まります。詳細については、[アップロードガイド](g://uploads/direct)を参照してください。 ## 親フォルダ `parent_folder`本文パラメータで指定されたフォルダIDによって、最終的な署名済みドキュメントと[署名ログ](https://support.box.com/hc/ja/articles/4404095202579-%E7%BD%B2%E5%90%8D%E3%83%AD%E3%82%B0%E3%81%AE%E7%A2%BA%E8%AA%8D)の保存先が決まります。このフォルダには、フォルダID `0`で表される [すべてのファイル] やルートレベルを指定することができません。 ## 署名者 各署名者には、[役割](https://support.box.com/hc/ja/articles/4404105660947-%E7%BD%B2%E5%90%8D%E8%80%85%E3%81%AE%E5%BD%B9%E5%89%B2)として、`signer`、`approver`、または`final copy_reader`を割り当てる必要があります。 リクエスト送信者に役割が指定されていない場合は、`final_copy_reader`という役割の署名者が自動的に作成されます。つまり、最終的な署名済みドキュメントと[署名ログ](https://support.box.com/hc/ja/articles/4404095202579-%E7%BD%B2%E5%90%8D%E3%83%AD%E3%82%B0%E3%81%AE%E7%A2%BA%E8%AA%8D)のコピーを受信するだけです。 署名者は、ドキュメントに署名するために、既存のBoxアカウントを持っている必要も、アカウントを作成する必要もありません。他のAPIエンドポイントとは異なり、署名者はBox `user_id`ではなくメールアドレスを使用して招待されます。 必要に応じて、署名者は、リクエストに署名する前にBoxにログインできます。その場合は、署名者の`login_required`パラメータを`true`に設定します。署名者が既存のアカウントを所有していない場合は、無料Boxアカウントを作成するオプションもあります。 Box Signは、リクエストで指定された署名者のメールアドレスに署名用メールを送信しようとするだけです。Boxユーザーの場合、指定しない限り、メールエイリアスは含まれません。指定された署名者のメールアドレスすべてが有効であることを再確認してください。 ### 入力 `inputs`パラメータは、ユーザーが操作できるプレースホルダを表します。`document_tag_id`パラメータには、署名リクエストの作成時に渡すデータを設定できます。 ## テンプレート 署名リクエストは、テンプレートを使用して作成できます。そのためには、`template_id`パラメータを指定する必要があります。署名リクエスト作成時のテンプレートの使用の詳細については、[こちらのガイド](g://box-sign/sign-templates)を参照してください。 ## リダイレクト `redirect_url`および`declined_redirect_url`で指定したURLにより、署名するか署名リクエストを拒否した署名者をカスタムランディングページにリダイレクトすることができます。たとえば、アプリケーションをBox Signと統合した場合は、署名者をアプリケーションにリダイレクトすることもカスタムランディングページにリダイレクトすることもできます。リダイレクトURLは、すべての署名者を対象にグローバルに設定することも、特定の署名者のみを対象に設定することもできます。つまり、Box Signでは、選択した署名者に特定のURLを使用し、残りの署名者にグローバルな設定を使用します。リダイレクトURLを設定しなかった場合、Box Signでは署名者がデフォルトのページにリダイレクトされます。 デフォルトのページには「すべての関係者がドキュメントでの作業を完了すると、期限が設定された最終版へのリンクがメールで届きます。また、Boxアカウントをお持ちの場合は、アカウントにコピーが保存されます。」と表示されます。署名者を別のページにリダイレクトする場合、この情報は署名者に表示されなくなります。 ## 複数の署名者と署名の順序 署名の順序は、指定された`order`の数値を小さいものから大きいものへ順序付けすることで決まります。2つの数値が同じ場合、署名者には同時にリクエストが届きます。 最初は、割り当てられた`order`の数値が最も小さい署名者だけに、Box Signのリクエストメールが送信されます。その署名者が署名すると、次のユーザーにメールが送信される、というように進んでいきます。Box Signでは、ユーザーが署名するたびに、ドキュメントの新しいバージョンが`parent_folder`に自動的に追加されます。 いずれかの署名者が拒否した場合、残りの署名者にBox Signのリクエストメールが送信されません。リクエスト全体が拒否されます。 ## リクエストのステータス - `converting`: 署名リクエストが送信された後、ファイルが署名プロセスのために`.pdf`に変換されている。 - `error_converting`: ファイルを`.pdf`に変換している間に問題が発生した。 - `created`: `document_preparation_is_needed`が`true`に設定されているが、`prepare_url`がまだアクセスされていない。 - `sent`: リクエストが正常に送信されたが、どの署名者も対応していない。 - `error_sending`: リクエストを送信中に問題が発生した。 - `viewed`: 最初 (または唯一) の署名者が署名用メールの [**ドキュメントをレビュー**] をクリックするか、署名用URLにアクセスした。 - `downloaded`: 署名者が署名用ドキュメントをダウンロードした。 - `signed`: すべての署名者がリクエストの処理を完了した。 - `signed and downloaded`: 署名者が署名用ドキュメントに署名してダウンロードした。 - `declined`: いずれかの署名者がリクエストを拒否した。 - `cancelled`: リクエストがUIまたはAPIを介してキャンセルされた。 - `expired`: 署名が未完了、不十分のまま、有効期限が過ぎた。 - `finalizing`: すべての署名者がリクエストに署名済みでも、署名された最終的なドキュメントと署名ログがまだ生成されていない。 - `error_finalizing`: `finalizing`フェーズが正常に完了しなかった。 エラーステータスになった場合、再試行するには、新しい署名リクエストを作成する必要があります。 **Source:** [https://ja.developer.box.com/guides/box-sign/create-sign-request/](https://ja.developer.box.com/guides/box-sign/create-sign-request/) --- ### Box Signのリクエストの再送信 **Type:** guide | **Category:** Box Sign | **Section:** Developer Guides Box Signのリクエストの再送信 Box Signのリクエストを再送信エンドポイントを使用すると、残りの署名者全員にリクエストのメールを再送信できます。 ステータスがsigned、cancelled、declined、expired、error_sending… # Box Signのリクエストの再送信 [Box Signのリクエストを再送信エンドポイント](e://post-sign-requests-id-resend)を使用すると、残りの署名者全員にリクエストのメールを再送信できます。 [ステータス](g://box-sign/create-sign-request/#request-status)が`signed`、`cancelled`、`declined`、`expired`、`error_sending`、または`error_converting`の場合は、Box Signのリクエストを再送信できません。 Box Signのリクエストが最近送信された場合は、再送信する前に10分間待つ必要があります。この時間が経過する前に再送信しようとすると、400エラーが返されます。 リクエストを再送信せずに済むように、Box Signのリクエスト作成時にリマインダメールを有効にすることができます。 **Source:** [https://ja.developer.box.com/guides/box-sign/resend-sign-request/](https://ja.developer.box.com/guides/box-sign/resend-sign-request/) --- ### Box Skills **Type:** guide | **Category:** Box Skills | **Section:** Developer Guides Box Skills Box Skillsは、ファイルの基盤となるメタデータを強化することを目的として、Box… # Box Skills Box Skillsは、ファイルの基盤となるメタデータを強化することを目的として、Boxにアップロードされたファイルのカスタム処理を可能にします。このシステムの利点は、さまざまなファイルの豊富な情報を保存しておき、自動化されたタスクや将来のプロセスに使用できることです。 Skillsアプリケーションのエンドツーエンドプロセスは以下のとおりです。 1. [アプリのセットアップ](guide://skills/handle/setup) - 会社全体または1つ以上のフォルダ内でアップロードされるファイルをリッスンする**カスタムスキル**Boxアプリケーションを作成します。 2. [`invocation_url`の構成](guide://skills/invocation-url) - **カスタムスキル**アプリを作成したら、`invocation_url`を構成する必要があります。このURLは、Boxに新しいファイルがアップロードされるたびに呼び出されます。 3. [イベントペイロードの解析](guide://skills/handle/payload) - Box Skillがリッスンするフォルダにファイルがアップロード、コピー、または移動されると、`invocation_url`にイベントペイロードが送信されます。このペイロードには、2つの**アクセストークン**が含まれています。これらのアクセストークンを使用すると、Boxにアップロードされたファイルにアクセスし、ファイルにメタデータを保存することができます。 4. [主な署名の検証](guide://webhooks/v2/signatures-v2) - Skillペイロードを処理するサービスは、他の処理を行う前に、`invocation_url`がBoxによって呼び出されたことを検証する必要があります。この検証を手動またはSDKを使用して行う例については、リンクを確認してください。 5. [処理するファイルの送信](https://github.com/box-community/Box-Custom-Skills-Starter) - Skillペイロードを処理するサービスは、ファイルのURLまたはコンテンツを処理するために外部サービスに送信します。このサービスは、サードパーティの機械学習システムでも、社内サービスでもかまいません。 6. [ファイルにメタデータを保存](guide://skills/handle/metadata) - 処理サービスによってファイルのメタデータが抽出されたら、これらのインサイトをアップロードされたファイルにカスタムメタデータとして再保存できます。 Box Skillsとの統合を簡素化するため、上記の手順の複雑さを減らした[Skills Kit](guide://skills/kit)が提供されています。Skills Kitは現在、Nodeでのみ入手可能です。 **Source:** [https://ja.developer.box.com/guides/skills/](https://ja.developer.box.com/guides/skills/) --- ### Box Skills Kit **Type:** guide | **Category:** Box Skills | **Section:** Developer Guides Box Skills Kit Box Skills Kitは、Box Skills開発プロセスでよく必要とされる複雑な操作の多くを抽象化するために設計されたノードラッパーです。 GitHub上のSkills Kitにアクセスする # Box Skills Kit Box Skills Kitは、Box Skills開発プロセスでよく必要とされる複雑な操作の多くを抽象化するために設計されたノードラッパーです。 GitHub上のSkills Kitにアクセスする **Source:** [https://ja.developer.box.com/guides/skills/kit/](https://ja.developer.box.com/guides/skills/kit/) --- ### Box Skillsペイロード **Type:** guide | **Category:** Box Skills | **Section:** Developer Guides Box Skillsペイロード Skillsアプリが監視するフォルダに新しいファイルがアップロード、コピー、または移動されると、アプリケーションの設定および認証中に指定された呼び出しURLに、Box… # Box Skillsペイロード Skillsアプリが監視するフォルダに新しいファイルがアップロード、コピー、または移動されると、アプリケーションの設定および認証中に指定された呼び出しURLに、Boxからイベントペイロードが送られます。 このイベントペイロードには、アップロードされたファイルのコンテンツを読み込んで機械学習システムなどの処理システムに送信し、処理システムの完了後にファイルにメタデータを書き戻すために必要な情報がすべて含まれています。 ペイロードの例とリファレンス ## アクセストークン 各Skillsペイロードには、イベントをトリガーしたファイルへのアクセスに使用できる一連のアクセストークンが含まれています。 ``` { ... "token": { "write": { "access_token": "c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ", "expires_in": 1540924150, "restricted_to": ..., "token_type": "bearer" }, "read": { "access_token": "Z3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQc3FIOG9vSGV4VHo4QzAyg5T1JvNnJo", "expires_in": 1540924150, "restricted_to": ..., "token_type": "bearer" } }, ... } ``` `token.write.access_token`を使用すると、ファイルにメタデータを書き込むことができるのに対し、`token.read.access_token`はファイルコンテンツの読み取りのみに使用できます。読み取り専用トークンは、後で他のサービスと共有できるファイルのダウンロードURLを作成する際に役立ちます。 ## ダウンロード可能ファイルのURL 多くの機械学習サービスでは、ファイルのURLを処理するためにそのサービスに直接渡すことがサポートされています。BoxファイルのダウンロードURLを作成するには、イベントペイロードの`token.read.access_token`および`source.id`を解析する必要があります。 ``` { ... "source": { "type": "file", "id": 12345, }, "token": { ... "read": { "access_token": "Z3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQc3FIOG9vSGV4VHo4QzAyg5T1JvNnJo", "expires_in": 1540924150, "restricted_to": ..., "token_type": "bearer" } }, ... } ``` ファイルのダウンロードURLは、次のように作成できます。 ``` https://api.box.com/2.0/files/{source.id}/content?access_token={token.read.access_token} ``` この例では、このURLは次のようになります。 ``` https://api.box.com/2.0/files/12345/content?access_token=Z3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQc3FIOG9vSGV4VHo4QzAyg5T1JvNnJo ``` **Source:** [https://ja.developer.box.com/guides/skills/handle/payload/](https://ja.developer.box.com/guides/skills/handle/payload/) --- ### Box UI Elementsのテーマとスタイルの設定 **Type:** guide | **Category:** Boxの埋め込み | **Section:** Developer Guides Box UI Elementsのテーマとスタイルの設定 Box UI Elementsのテーマとスタイルの設定により、企業の要件に合わせて、埋め込まれたBox… # Box UI Elementsのテーマとスタイルの設定 Box UI Elementsのテーマとスタイルの設定により、企業の要件に合わせて、埋め込まれたBoxコンポーネントの外観をカスタマイズできます。 現時点では、[テーマとスタイルの設定](https://medium.com/@stefaniuk.olga/b4a86518d5ca)は、コンテンツエクスプローラとコンテンツアップローダーで使用可能です。 ## 開始方法 選択したBoxコンポーネントをアプリケーションに追加します。デフォルトのBoxのテーマが適用されます。 ## カスタマイズ Boxでは、カスタマイズの目的で[デザイントークン](g://embed/ui-elements/ui-elements-design-tokens)を使用します。 デザイントークンとは、色、間隔、タイポグラフィ、スケールなど、特定の視覚的な属性を格納する名前付きのエンティティです。これは、プラットフォーム、ツール、コンポーネント間でのデザインプロパティの共有を容易にするために、ハードコードされた値の代わりに使用されます。 埋め込まれたBoxコンポーネントでは、以下の要素を変更できます。 ### 色 以下をカスタマイズできます。 グローバルカラーパレット - プライマリカラー、セカンダリカラー、アクセントカラーを選択します。 状態の色 - カーソルを合わせたとき、フォーカスしたとき、アクティブな場合、無効な場合など、状態を表す色を選択します。 コンポーネント固有の色 - たとえば、ボタンには、種類に応じて異なる色を選択できます。 グラデーション - 背景やその他のコンポーネントとしてグラデーションを選択して調整します。 不透明度 - Boxのウィンドウやサイドパネルのオーバーレイ効果の不透明度を調整します。 ### タイポグラフィ 以下をカスタマイズできます。 - テキストの装飾 - 下線、取り消し線、文字間隔 - 行の高さ、段落の間隔 ### 境界線、半径 以下を選択できます。 - 境界線のスタイル - 幅、スタイル、色 - 角丸 ### 間隔 以下を選択できます。 - 全体的な間隔 - コンポーネント固有の間隔 - コンポーネント固有の位置と分布 (例: justify-content) ### 影と高さ 以下を定義できます。 - 影のプリセット - カスタマイズした影 ### インタラクティブな状態 以下をカスタマイズできます。 - カーソルを合わせた状態、アクティブな状態、フォーカスした状態、無効な状態、エラー状態 - 背景色の変更などの視覚効果 - 遷移およびアニメーション ### コンポーネントレベルの上書き テキスト入力、ドロップダウン、チェックボックスを独自の色でカスタマイズできます。 ### アイコン ボタンやドロップダウンなどのインタラクティブなアイコンのスタイルを設定します。 ファイルアイコンやフォルダアイコンなどの非インタラクティブなアイコンをカスタムアイコンに置き換えるには、CSSでインラインSVGを使用します。非インタラクティブなアイコンの色、高さ、幅を変更するには、CSSを使用します。 CodePenでカスタムアイコンの実装例を確認してください。 ### その他 スタイル: - ヘルプテキストとラベル - ツールチップ ## デモ **Source:** [https://ja.developer.box.com/guides/embed/ui-elements/theming-styling/](https://ja.developer.box.com/guides/embed/ui-elements/theming-styling/) --- ### Box View **Type:** guide | **Category:** Boxの埋め込み | **Section:** Developer Guides Box View Box Viewは、開発者が自分のウェブアプリやモバイルアプリで、忠実度の高いインタラクティブなファイルビューアーを使用してファイルをアップロード、変換、および表示できるようにする、埋め込み可能なサービスです。 機能 任意のファイルの表示 標準の`を使用して、ドキュメント、画像、動画、360度動画および画像、3Dモデル、その他の多くのファイルを任意のウェブアプリまたはモバイルアプリに埋め込みます。 ### 使いやすさ セキュアなAPIを介してBoxにファイルをアップロードすると、アプリケーションのUIに埋め込み可能なHTML5スニペットが配置されます。 ### 状況に応じたコラボレーション エンドユーザーが注釈を使用して、ドキュメント、プレゼンテーション、および画像のコラボレーションやマークアップを実行できるようにします。ユーザーは、テキストをハイライトしたり、ファイルレンダリングの特定の領域にコメントを付けたりできます。 ## Box Viewのしくみ 1. [セキュアなアップロードAPI](e://post-files-content)を使用してBoxにファイルをアップロードします。コンテンツはすべて、ウイルススキャンと256ビット暗号化を備えたBoxのセキュアなクラウドストレージインフラストラクチャに保存されます。 2. アップロード時に、ファイルはHTML5互換のアセットに変換されます。これらのアセットは、明瞭にすばやくレンダリングするよう作られています。 3. ファイルレンダリングにアクセスするために埋め込み可能なURLがリクエストされます。プレビューは、`<iframe>` URLを使用してアプリケーションに直接埋め込むことができます。 ## Box Content Previewによる操作のカスタマイズ [Box Content Preview](g://embed/ui-elements/preview)を使用すると、変換されたファイルに対するクライアント側の操作をカスタマイズできます。 ## ユースケース - 求人アプリケーションで履歴書PDFを変換して表示する - 学生用ポータルで、ドキュメント、動画、PDFなどの教材を変換して表示する - メディアルームでHD動画を変換して表示する - 現場の営業支援アプリケーションで、ドキュメント、動画、PDF、3Dモデルなどの営業資料を変換して表示する **Source:** [https://ja.developer.box.com/guides/embed/box-view/](https://ja.developer.box.com/guides/embed/box-view/) --- ### Boxアプリの設定 **Type:** quick-start | **Category:** CLI | **Section:** Developer Guides Boxアプリの設定 Box CLIを使用するには、Boxアプリを作成する必要があります。Boxアプリは、APIコールの実行に使用できるアプリケーションです。Box CLIを使用する際は、独自のBoxアプリを設定するか、あらかじめ設定されているBox… # Boxアプリの設定 **Box CLI**を使用するには、**Boxアプリ**を作成する必要があります。Boxアプリは、APIコールの実行に使用できるアプリケーションです。Box CLIを使用する際は、独自のBoxアプリを設定するか、あらかじめ設定されているBoxアプリを使用するかを選択できます。独自のBoxアプリを設定した場合の主な利点として、1時間ごとにログインする必要はなくなりますが、設定にいくつか追加手順が必要になります。 ## 使用するBoxアプリの選択 # 新しいBoxアプリを作成する ここからBoxアプリを設定できます。数回クリックするだけで準備できます。 # 既存のBoxアプリを使用する 使用したいBoxアプリをすでに作成済みの場合は、そのアプリケーションの資格情報を使用できます。 # Boxアプリの作成 独自の**Boxアプリ**を使用するには、**Box開発者コンソール**で新しいBoxアプリを作成する必要があります。下のボタンをクリックすると、アプリが設定されます。最後に、**クライアントID**と**クライアントシークレット**を取得できます。 アプリの作成 これらの資格情報は、次の手順でBox CLIの認証に使用します。 # 既存のBoxアプリを使用する 事前にBoxアプリをすでに作成済みの場合は、そのアプリも使用できます。そのアプリを使用するには、いくつかの設定が必要です。 1. [開発者コンソール](https://cloud.app.box.com/developers/console)に移動します。 2. アプリケーションを選択します。 3. アプリケーションの [**構成**] セクションに移動します。 4. アプリケーションが認証方法として**標準OAuth 2.0**を使用することを確認します。 5. [**OAuth 2.0リダイレクトURI**] の設定まで下にスクロールし、[**リダイレクトURI**] に値`http://localhost:3000/callback`を設定します。 6. [**アプリケーションスコープ**] セクションまでスクロールし、目的の[権限](g://api-calls/permissions-and-errors/scopes)を選択します。**アプリケーションには、****次のスコープの1つ以上が必要です:** Boxに格納されているすべてのファイルとフォルダの読み取り、Boxに格納されているすべてのファイルとフォルダの読み取りと書き込み 7. ページ上部にある [**変更を保存**] ボタンをクリックします。 次に、クライアントIDとクライアントシークレットの値を以下の2つのフィールドにコピーします。 クライアントID クライアントシークレット これらの資格情報は、次の手順でBox CLIの認証に使用します。 # セキュリティに関する注意 API資格情報は、ブラウザキャッシュに保存されています。このガイドで後から出てくる**リセット**ボタンをクリックして、この情報を消去することを強くお勧めします。 ## まとめ 新しい**Boxアプリ**の作成を選択しました。 - Developerアカウントにサインアップ (必要な場合) - **OAuth 2.0**認証を使用する**Platformアプリ**を作成 - アプリケーションの**リダイレクトURL**を設定 または、**既存のBoxアプリ**の使用を選択しました。 Boxアプリの設定が完了しました **Source:** [https://ja.developer.box.com/guides/cli/quick-start/create-oauth-app/](https://ja.developer.box.com/guides/cli/quick-start/create-oauth-app/) --- ### Boxアプリの設定 **Type:** quick-start | **Category:** ツール | **Section:** Developer Guides Boxアプリの設定 Postmanコレクションを使用するために、Postmanアプリケーションはアクセストークンを使用してBox APIから認証を受ける必要があります。アクセストークンを取得するには、Boxアプリを使用してBoxにログインする方法が最も簡単です。 Box… # Boxアプリの設定 **Postmanコレクション**を使用するために、Postmanアプリケーションは**アクセストークン**を使用してBox APIから認証を受ける必要があります。アクセストークンを取得するには、**Boxアプリ**を使用してBoxにログインする方法が最も簡単です。 **Boxアプリ**は、APIコールの実行に使用できるアプリケーションです。**Postmanコレクション**を使用する際は、独自のBoxアプリを設定するか、あらかじめ設定されているBoxアプリを使用するかを選択できます。独自のBoxアプリを設定した場合の主な利点は、1時間ごとにログインする必要がなくなることです。ただし、設定にいくつか追加手順が必要になります。 ## 使用するBoxアプリの選択 # 新しいBoxアプリを作成する ここからBoxアプリをセットアップできます。数回クリックするだけで準備できます。 # 既存のアプリを使用する 使用したいBoxアプリをすでに作成済みの場合は、そのアプリケーションの資格情報を使用できます。 # Boxアプリの作成 独自の**Boxアプリ**を使用するには、**Box開発者コンソール**で新しいBoxアプリを作成する必要があります。下のボタンをクリックすると、アプリが設定されます。最後に、**クライアントID**と**クライアントシークレット**を取得できます。 アプリの作成 これらの資格情報は、次の手順でアプリケーションの認証に使用します。 # 既存のアプリを使用する 事前にBoxアプリをすでに作成済みの場合は、そのアプリも使用できます。そのアプリを使用するには、いくつかの設定が必要です。 1. [開発者コンソール](https://cloud.app.box.com/developers/console)に移動します。 2. アプリケーションを選択します。 3. アプリの構成セクションに移動します。 4. アプリケーションが認証方法として**標準OAuth 2.0**を使用することを確認します。 5. [**OAuth 2.0リダイレクトURI**] の設定まで下にスクロールし、[**リダイレクトURI**] に値`https://developer.box.com/auth/callback`を設定します。([https://ja.developer.box.com/で操作する場合は、ドメインをhttps://ja.developer.box.com/に変更してください。](https://ja.developer.box.com/%E3%81%A7%E6%93%8D%E4%BD%9C%E3%81%99%E3%82%8B%E5%A0%B4%E5%90%88%E3%81%AF%E3%80%81%E3%83%89%E3%83%A1%E3%82%A4%E3%83%B3%E3%82%92https://ja.developer.box.com/%E3%81%AB%E5%A4%89%E6%9B%B4%E3%81%97%E3%81%A6%E3%81%8F%E3%81%A0%E3%81%95%E3%81%84%E3%80%82)) `box.dev`でこのチュートリアルにアクセスした場合は [**リダイレクトURI**] が`https://box.dev/auth/callback`になることに注意してください。 6. [**アプリケーションスコープ**] セクションまでスクロールし、目的の[権限](g://api-calls/permissions-and-errors/scopes)を選択します。**アプリケーションには、** **次のスコープの1つ以上が必要です:** ユーザーを管理する、Boxに格納されているすべてのファイルとフォルダの読み取り、Boxに格納されているすべてのファイルとフォルダの読み取りと書き込み 7. ページ上部にある [**変更を保存**] ボタンをクリックします。 次に、クライアントIDとクライアントシークレットの値を以下の2つのフィールドにコピーします。 クライアントID クライアントシークレット これらの資格情報は、次の手順でアプリケーションの認証に使用します。 # セキュリティに関する注意 API資格情報は、ブラウザキャッシュに保存されています。このガイドで後から出てくる**リセット**ボタンをクリックして、この情報を消去することを強くお勧めします。 ## まとめ 新しい**Boxアプリ**の作成を選択しました。 - Developerアカウントにサインアップ (必要な場合) - **OAuth 2.0**認証を使用する**Platformアプリ**を作成 - アプリケーションの**リダイレクトURL**を設定 または、**既存のBoxアプリ**の使用を選択しました。 Boxアプリの設定が完了しました **Source:** [https://ja.developer.box.com/guides/tooling/postman/quick-start/configure-box-app/](https://ja.developer.box.com/guides/tooling/postman/quick-start/configure-box-app/) --- ### BoxグループコラボレーションへのSlackの接続 **Type:** quick-start | **Category:** コラボレーション | **Section:** Developer Guides BoxグループコラボレーションへのSlackの接続 Slackは、よく使われているコミュニケーションおよび生産性向上ツールで、会社の内外の個人またはグループと作業する際にリアルタイムでの調整が可能になります。 カスタムBoxアプリケーションに接続すると、Slack… # BoxグループコラボレーションへのSlackの接続 Slackは、よく使われているコミュニケーションおよび生産性向上ツールで、会社の内外の個人またはグループと作業する際にリアルタイムでの調整が可能になります。 カスタムBoxアプリケーションに接続すると、Slackチャンネルの構造を[スラッシュコマンド](https://api.slack.com/apps/A0155185TT3/slash-commands)や[イベントAPI](https://api.slack.com/events-api)システムとともに使用して、Boxのファイルやフォルダを論理的にグループ化およびコラボレーションできるようになります。 ## 概要 このクイックスタートガイドでは、BoxユーザーをSlackワークスペースで属しているチャンネルに基づいてグループ化し、Slackのスラッシュコマンドを使用して、そのSlackチャンネル内のユーザーがBoxのファイルやフォルダをそのグループと共有できるようにするのに必要な手順すべてを説明します。 このチュートリアルが終了すると、ワークスペースのチャンネルにSlackボットが展開されます。このボットは、そのチャンネルに存在するすべてのユーザーが含まれるBoxグループを作成し、チャンネルで`/boxadd`コマンドをリッスンします。その後、そのコマンドを解析し、自動的にチャンネルのユーザーグループ全体とBoxのファイルやフォルダでコラボレーションします。 このガイドでは、以下の手順を説明します。 1. イベント通知とスラッシュコマンドの構造を処理するよう[Slackアプリのセットアップと構成](g://collaborations/connect-slack-to-group-collabs/configure-slack)を行います。 2. ウェブアプリケーションをBoxに接続するよう[Boxアプリケーションのセットアップと構成](g://collaborations/connect-slack-to-group-collabs/configure-box)を行います。 3. ユーザーがチャンネルに参加したりチャンネルから退出したりするとき、またはBoxのファイルやフォルダをグループと共有するときに[Slackイベントおよびコマンドをリッスン](g://collaborations/connect-slack-to-group-collabs/scaffold-application-code)します。 4. Slackイベントまたはスラッシュコマンドに基づいて、[Boxグループおよびファイル/フォルダのコラボレーションを構造化](g://collaborations/connect-slack-to-group-collabs/handle-slack-events)します。 5. [最後に、アプリケーションをワークスペースに展開](g://collaborations/connect-slack-to-group-collabs/connect-box-functions)し、Slackアプリのボットをチャンネルに招待してイベントのリッスンを開始します。 ## 要件 先に進む前に、このクイックスタートガイドには注目すべき2つの要件があります。 1. **ユーザーのメールアドレスがBoxとSlackで一致している必要がある**: SlackユーザーアカウントをBoxユーザーアカウントに関連付ける際に、Slackユーザーのメールアドレスを比較します。そのため、一致するBoxユーザーアカウントが同一のメールアドレスを使用し、Box Enterpriseに存在する必要があります。 2. **一般公開されているサーバーが必要である**: Slackはイベントおよびコマンド通知データをアプリケーションの公開URLに送信する必要があります。このガイドでは、`https://mysite.com/`など、アプリケーションコードをホストする公開された場所があることを想定しています。公開されているホスト用の場所にアクセスできない場合は、[Heroku](https://heroku.com/)などのアプリケーションプラットフォームや[AWS Lambda](https://aws.amazon.com/lambda/)などのサーバーレスオプションの使用または[ngrok](https://ngrok.com/)のようなサービスによるlocalhostの公開を検討してください。 開始する準備ができました **Source:** [https://ja.developer.box.com/guides/collaborations/connect-slack-to-group-collabs/](https://ja.developer.box.com/guides/collaborations/connect-slack-to-group-collabs/) --- ### Boxの埋め込み **Type:** guide | **Category:** Boxの埋め込み | **Section:** Developer Guides Boxの埋め込み Boxでは、フロントエンドアプリケーションに直接ファイルやフォルダを埋め込むためのいくつかの方法をサポートしています。 # Boxの埋め込み Boxでは、フロントエンドアプリケーションに直接ファイルやフォルダを埋め込むためのいくつかの方法をサポートしています。 **Source:** [https://ja.developer.box.com/guides/embed/](https://ja.developer.box.com/guides/embed/) --- ### Boxの構成 **Type:** quick-start | **Category:** コラボレーション | **Section:** Developer Guides Boxの構成 Boxグループの管理とBox内のファイルやフォルダへのコラボレータの追加を行うためにBoxアプリケーションを設定する必要があります。 Boxアプリのセットアップ 新しいBoxアプリを作成する この統合に使用する新しいBox JWT… # Boxの構成 Boxグループの管理とBox内のファイルやフォルダへのコラボレータの追加を行うためにBoxアプリケーションを設定する必要があります。 ## Boxアプリのセットアップ # 新しいBoxアプリを作成する この統合に使用する新しいBox JWTアプリケーションを作成して構成します。 # 承認済みの既存のアプリを使用する Box開発者コンソールから、管理者が承認した既存のBox JWTアプリケーションのいずれかを使用します。 # 新しいBoxアプリを作成する Box APIの呼び出しに使用できる新しいBoxアプリケーションを作成するには、以下の手順に従います。 1. [開発者コンソール](https://cloud.app.box.com/developers/console)に移動します。 2. [**アプリの新規作成**] を選択します。 3. 作成するアプリケーションの種類として [**Platformアプリ**] を選択し、[**次へ**] をクリックします。 4. 認証方法として [**JWTを使用したOAuth 2.0**] を選択し、[**次へ**] をクリックします。 5. Boxアプリに一意の名前を付け、[**アプリの作成**] をクリックします。 6. [**アプリの表示**] をクリックしてアプリの設定に移動します。 7. [**アプリケーションアクセス**] まで下にスクロールし、[**Enterprise**] が選択されていることを確認します。 8. 同じ画面の [**アプリケーションスコープ**] セクションまでスクロールし、少なくとも [**Boxに格納されているすべてのファイルとフォルダの読み取りと書き込み**]、[**ユーザーを管理する**]、[**グループを管理する**] スコープが有効になっていることを確認します。 9. [**高度な機能**] で、Boxユーザーの代わりに操作を行うために [**ユーザーとして操作を実行**] が有効になっていることを確認します。 10. ページ上部にある [**変更を保存**] ボタンをクリックします。 # アプリの承認 アプリケーションの作成後も、Box APIの呼び出しを行うには会社の管理者による承認が必要です。 アプリケーションを社内で承認してもらうには、[このガイド](g://authorization/custom-app-approval)に従ってください。 # 既存のJWT Boxアプリケーションを使用する [開発者コンソール](https://cloud.app.box.com/developers/console)に、使用したい既存のJWTベースのBoxアプリケーションがある場合は、アプリケーションの [**構成**] セクションで以下のオプションが設定されていることを確認してください。 [認証方法]: [JWTを使用したOAuth 2.0 (サーバー認証)] に設定します。 [アプリケーションスコープ]: 少なくとも以下のスコープを設定します。 - Boxに格納されているすべてのファイルとフォルダの読み取りと書き込み - ユーザーを管理する - グループを管理する [高度な機能]: ユーザーとして操作を実行するオプションとユーザーアクセストークンを生成するオプションの両方を有効にします。 # アプリの承認 アプリケーションは更新後、会社の管理者による再承認が必要になります。再承認後、新しい権限のいずれかを必要とする任意のBox APIを呼び出すことができます。 アプリケーションを社内で承認してもらうには、[このガイド](g://authorization/custom-app-approval)に従ってください。 ## アプリの構成のダウンロード このチュートリアルで使用されているBox SDKの使用を開始するには、アプリケーションの [**構成**] ページにあるアプリケーション構成ファイルが必要です。この中には、アプリケーションを検証して、Box SDKを使用してAPIリクエストを開始するために必要なすべての情報が含まれます。 [**構成**] ページの [**公開キーの追加と管理**] セクションで、[**公開/秘密キーペアを生成**] をクリックします。これにより、アプリケーションの構成ファイルをダウンロードする前に2要素認証が行われます。 そのファイルを`boxConfig.json`として、アプリケーションがアクセス可能な場所に保存します。 ## まとめ - 会社の管理者によって承認されている、新しいBoxアプリを作成しました。または、会社の管理者によって承認されている既存のBoxアプリを使用しています。 - アプリケーション構成ファイルをダウンロードして、アプリケーションがアクセス可能な場所に保存しました。 アプリケーション構成ファイルをダウンロードしました **Source:** [https://ja.developer.box.com/guides/collaborations/connect-slack-to-group-collabs/configure-box/](https://ja.developer.box.com/guides/collaborations/connect-slack-to-group-collabs/configure-box/) --- ### Boxの構成 **Type:** quick-start | **Category:** SSOとApp User | **Section:** Developer Guides Boxの構成 Oktaでのログインエクスペリエンスを作成したので、次は、Oktaのユーザーアカウントに関連付けられているユーザーをBox APIを使用して検索、作成できるBoxアプリケーションを作成する必要があります。 Boxアプリのセットアップ 新しいBox… # Boxの構成 Oktaでのログインエクスペリエンスを作成したので、次は、Oktaのユーザーアカウントに関連付けられているユーザーをBox APIを使用して検索、作成できるBoxアプリケーションを作成する必要があります。 ## Boxアプリのセットアップ # 新しいBoxアプリを作成する 新しいBox JWTアプリケーションを作成および構成して、空のユーザーリストから開始します。 # 承認済みの既存のアプリを使用する Box開発者コンソールから、管理者が承認した既存のBox JWTアプリケーションのいずれかを使用します。 # 新しいBoxアプリを作成する Box APIの呼び出しに使用できる新しいBoxアプリケーションを作成するには、以下の手順に従います。 1. [開発者コンソール](https://cloud.app.box.com/developers/console)に移動します。 2. [**Platformアプリの作成**] を選択します。 3. 作成するアプリケーションの種類として [**Platformアプリ**] を選択し、[**次へ**] をクリックします。 4. 認証方法として [**JWTを使用したOAuth 2.0**] を選択し、[**次へ**] をクリックします。 5. Boxアプリに一意の名前を付け、[**アプリの作成**] をクリックします。 6. [**アプリの表示**] をクリックしてアプリの設定に移動します。 同じ画面の [**必須のアクセススコープ**] セクションまでスクロールし、少なくとも以下のスコープが有効になっていることを確認します。 - Boxに格納されているすべてのファイルとフォルダの読み取りと書き込み - ユーザーを管理する 7. [**高度な機能**] で、ユーザーとして操作を実行するオプションとユーザーアクセストークンを生成するオプションの両方が有効になっていることを確認します。 8. ページ上部にある [**変更を保存**] ボタンをクリックします。 アプリケーションの作成後も、Box APIの呼び出しを行うには会社の管理者による承認が必要です。 アプリケーションを社内で承認してもらうには、[このガイド](g://authorization/custom-app-approval)に従ってください。 # 既存のJWT Boxアプリケーションを使用する [開発者コンソール](https://cloud.app.box.com/developers/console)に、使用したい既存のJWTベースのBoxアプリケーションがある場合は、アプリケーションの [**構成**] セクションで以下のオプションが設定されていることを確認してください。 - [認証方法]: [JWTを使用したOAuth 2.0 (サーバー認証)] に設定します。 [アプリケーションスコープ]: 少なくとも以下のスコープを設定します。 - Boxに格納されているすべてのファイルとフォルダの読み取りと書き込み - ユーザーを管理する [高度な機能]: ユーザーとして操作を実行するオプションとユーザーアクセストークンを生成するオプションの両方を有効にします。 ## 必要なデータのダウンロード このチュートリアルで使用されているBox SDKの使用を開始するには、アプリケーションの [**構成**] ページにあるアプリケーション構成ファイルが必要です。この中には、アプリケーションを検証して、Box SDKを使用してAPIリクエストを開始するために必要なすべての情報が含まれます。 [**構成**] ページの [**公開キーの追加と管理**] セクションで、[**公開/秘密キーペアを生成**] をクリックします。これにより、アプリケーションの構成ファイルをダウンロードする前に2要素認証が行われます。 そのファイルを`config.json`として、アプリケーションがアクセス可能な場所に保存します。 ## まとめ - 会社の管理者によって承認されている、新しいBoxアプリを作成しました。または、会社の管理者によって承認されている既存のBoxアプリを使用しています。 - アプリケーション構成ファイルをダウンロードして、アプリケーションがアクセス可能な場所に保存しました。 アプリケーション構成ファイルをダウンロードしました **Source:** [https://ja.developer.box.com/guides/sso-identities-and-app-users/connect-okta-to-app-users/configure-box/](https://ja.developer.box.com/guides/sso-identities-and-app-users/connect-okta-to-app-users/configure-box/) --- ### Boxへのボットの接続 **Type:** quick-start | **Category:** コラボレーション | **Section:** Developer Guides Boxへのボットの接続 ここでは、Slackから送信されるイベントを処理し、Boxのユーザーやグループとの接続に必要なすべての情報を取得します。その機能をBoxの関数に関連付ける必要があります。 この手順では、直前の手順で説明した関数をいくつか拡張し、新しいBox… # Boxへのボットの接続 ここでは、Slackから送信されるイベントを処理し、Boxのユーザーやグループとの接続に必要なすべての情報を取得します。その機能をBoxの関数に関連付ける必要があります。 この手順では、直前の手順で説明した関数をいくつか拡張し、新しいBox機能を組み込みます。 - Boxクライアントをインスタンス化する - BoxグループにBoxユーザーを追加する - BoxグループからBoxユーザーを削除する - グループ名からBoxグループIDを取得する - グループと共有するコンテンツを追加する ## Boxクライアントのインスタンス化 Box APIを呼び出すには、最初にBoxクライアントを設定する必要があります。 `process.js`で、先頭にある`// INSTANTIATE BOX CLIENT`コメントを次の内容に置き換えます。 ``` const boxConfig = require("./boxConfig.json"); const sdk = box.getPreconfiguredInstance(boxConfig); const client = sdk.getAppAuthClient("enterprise"); ``` `boxConfig`の代入行では、[手順2](g://collaborations/connect-slack-to-group-collabs/configure-box)の最後でBoxアプリからダウンロードした`boxConfig.json`ファイルを使用します。上記のサンプルでは、ファイルを`process.js`と同じフォルダに保存していることを前提としています。そうではない場合は、`boxConfig.json`ファイルの場所を指すパスとファイル名に変更してください。 最後の`client`の代入行では、APIコールに使用できるBoxクライアントオブジェクトを作成します。この時点では、その対象範囲は特定のユーザーではなく、アプリケーションの[サービスアカウント](page://platform/user-types/#service-account/)に設定されています。 `Application.java`で、`processEvent`メソッド内の`// INSTANTIATE BOX CLIENT`コメントを次の内容に置き換えます。 ``` this.fileReader = new FileReader("boxConfig.json"); this.boxConfig = BoxConfig.readFrom(fileReader); this.boxAPI = BoxDeveloperEditionAPIConnection.getAppEnterpriseConnection(boxConfig); ``` `boxConfig`の代入行では、[手順2](g://collaborations/connect-slack-to-group-collabs/configure-box)の最後でBoxアプリからダウンロードした`boxConfig.json`ファイルを使用します。上記のサンプルでは、ファイルをJavaプロジェクトのルートに保存していることを前提としています。そうではない場合は、`fileReader`の代入行のパスを、`boxConfig.json`ファイルの場所を指すパスとファイル名に変更してください。 最後の`boxAPI`の代入行では、APIコールに使用できるBoxクライアントオブジェクトを作成します。この時点では、その対象範囲は特定のユーザーではなく、アプリケーションの[サービスアカウント](page://platform/user-types/#service-account/)に設定されています。 # 前の手順が完了していません 最初に、手順1でお好みの言語/フレームワークを選択してください。 ## グループへのBoxユーザーの追加 グループにBoxユーザーを追加する関数を追加します。ボットがチャンネルに追加され、チャンネルのすべてのユーザーを含むBoxグループの作成が必要になった場合、またはその操作の後に1人のユーザーがチャンネルに参加した場合に、この関数によってそのタスクが実行されます。 `addGroupUser`関数を次の内容に置き換えます。 ``` function addGroupUser(groupId, email) { client.enterprise.getUsers({ filter_term: email }).then((users) => { if (users.entries.length > 0) { const userId = users.entries[0].id; const groupRole = client.groups.userRoles.MEMBER; client.groups .addUser(groupId, userId, { role: groupRole }) .then((membership) => { if (membership.id) { console.log(`Member added with membership ID: ${membership.id}`); } else { console.log(`Member not added`); } }) .catch(function (err) { console.log(err.response.body); }); } else { console.log("No Box user found to add to group"); } }); } ``` `addGroupUser`メソッドを次の内容に置き換えます。 ``` public void addGroupUser(String groupId, String userEmail) { Iterable<BoxUser.Info> users = BoxUser.getAllEnterpriseUsers(this.boxAPI, userEmail); for (BoxUser.Info user : users) { if (user.getLogin().toUpperCase().equals(userEmail.toUpperCase())) { try { BoxGroup group = new BoxGroup(boxAPI, groupId); BoxUser boxUser = new BoxUser(this.boxAPI, user.getID()); BoxGroupMembership.Info groupMembershipInfo = group.addMembership(boxUser); } catch (Exception ex) { System.err.println("User already present"); } } } } ``` # 前の手順が完了していません 最初に、手順1でお好みの言語/フレームワークを選択してください。 メールアドレスを使用してSlackユーザーをBoxユーザーと照合しているため、最初に、Slackのプロフィールのメールアドレスを使用して一致するBoxユーザーを検索します。見つかると、そのユーザーをチャンネルのグループに追加するための呼び出しが行われます。このグループは、ボットが最初に追加されたときに作成されています。 Boxの[ユーザーを取得](endpoint://get-users-id)エンドポイントでは、ユーザーIDによるユーザー検索のみ許可されています。メールアドレスでユーザーを検索するには、[会社ユーザーのリストを取得](endpoint://get-users)エンドポイントを使用し、`filter_term`オプションを検索対象のメールアドレスに設定します。 ## グループからのBoxユーザーの削除 Slackチャンネルから退出したユーザーや削除されたユーザーは、共有グループコンテンツにアクセスできなくなるようにBoxグループから削除することもできます。 `removeGroupUser`関数を次の内容に置き換えます。 ``` function removeGroupUser(groupId, email) { client.groups.getMemberships(groupId).then(memberships => { for (let i = 0; i < memberships.entries.length; i++) { if (memberships.entries[i].user.login === email) { client.groups .removeMembership(memberships.entries[i].id) .then(() => { console.log('Group user removed') }); break; } } }); } ``` `removeGroupUser`メソッドを次の内容に置き換えます。 ``` public void removeGroupUser(String groupId, String userEmail) { BoxGroup boxGroup = new BoxGroup(this.boxAPI, groupId); Iterable<BoxGroupMembership.Info> memberships = boxGroup.getAllMemberships(); for (BoxGroupMembership.Info membershipInfo : memberships) { if (membershipInfo.getUser().getLogin().toUpperCase().equals(userEmail.toUpperCase())) { BoxGroupMembership membership = new BoxGroupMembership(this.boxAPI, membershipInfo.getID()); membership.delete(); } } } ``` # 前の手順が完了していません 最初に、手順1でお好みの言語/フレームワークを選択してください。 このコードでは、SlackのチャンネルIDとなるグループIDを取得し、グループの全メンバーを取得します。メールアドレスに基づいて、Slackチャンネルを退出したユーザーに一致するメンバーが見つかると、そのユーザーはそのメンバーシップIDを使用してグループから削除されます。 # データストアによるパフォーマンスの向上 グループメンバーシップを検索してメンバーシップIDを取得すると、ローカルのデータストア (データベースなど) にメンバーシップIDを保存する必要はなくなりますが、ユーザーレコードとともにBoxメンバーシップIDを保存するデータストアがあれば、このコードがより効率的なものになります。 ローカルのデータストアを使用すると、メンバーシップIDは、そのデータストアから取得できます。Box APIを繰り返し呼び出してメンバーシップIDを検索する必要はありません。 ## グループ名に対応したBoxグループIDの取得 次に必要なBox関数には、主に2つの目的があります。 - 既存グループのBoxグループIDを返します。 - グループが存在しない場合、Boxグループを作成してそのIDを返します。 `getGroupId`関数を次の内容に置き換えます。 ``` function getGroupId(groupName, callback) { client.groups.getAll().then((groups) => { const group = groups.entries.filter((g) => g.name === groupName)[0]; if (!group) { client.groups .create(groupName, { description: "Slack channel collaboration group", invitability_level: "all_managed_users", }) .then((group) => { callback(group.id); }); } else { callback(group.id); } }); } ``` `getGroupId`メソッドを次の内容に置き換えます。 ``` public String getGroupId(String groupName) { String groupId = new String(); Iterable<BoxGroup.Info> groups = BoxGroup.getAllGroups(this.boxAPI); for (BoxGroup.Info groupInfo : groups) { if (groupInfo.getName().toUpperCase().equals(groupName)) { groupId = groupInfo.getID(); } } if (groupId.isEmpty()) { BoxGroup.Info groupInfo = BoxGroup.createGroup(boxAPI, groupName); groupId = groupInfo.getID(); } return groupId; } ``` # 前の手順が完了していません 最初に、手順1でお好みの言語/フレームワークを選択してください。 このコードでは、社内のすべてのグループを取得し、SlackチャンネルIDとグループ名の照合を試みます。いずれかのグループが一致すると、そのグループIDが返されます。 一致するものがない場合は、新しいBoxグループが作成され、そのグループのIDが返されます。グループの名前はSlackチャンネルIDに基づいて付けられます。これはスラッシュコマンドとUser Eventの両方で返される定数であり、追加の関数がなくても簡単に検索できるようにするためです。 ## グループへの共有コンテンツの追加 最終的に、このアプリケーション全体の主な目的は、ユーザーが自分のBoxアカウントにあるファイルやフォルダをグループ内の他のユーザー全員と共有できるようにすることです。 ここまでのすべての機能を基に、次の関数でそのタスクを実行します。 `processContent`関数を次の内容に置き換えます。 ``` function processContent(user, channel, itemType, itemId) { getGroupId(channel, function (groupId) { const email = user.profile.email; client.enterprise.getUsers({ filter_term: email }).then((users) => { if (users.entries.length > 0) { client.asUser(users.entries[0].id); const collabRole = client.collaborationRoles.VIEWER; const collabOptions = { type: itemType }; client.collaborations .createWithGroupID(groupId, itemId, collabRole, collabOptions) .then((collaboration) => { console.log( `Content added with collaboration ID ${collaboration.id}` ); }) .catch(function (err) { console.log( util.inspect(err.response.body, { showHidden: false, depth: null, }) ); }); } }); }); } ``` `processContent`メソッドを次の内容に置き換えます。 ``` public void processContent(JSONObject userResponse, String channel, String fType, String fId) { String groupId = getGroupId(channel); JSONObject userObj = (JSONObject) userResponse.get("user"); JSONObject userProfile = (JSONObject) userObj.get("profile"); String userEmail = (String) userProfile.get("email"); Iterable<BoxUser.Info> users = BoxUser.getAllEnterpriseUsers(this.boxAPI, userEmail); for (BoxUser.Info user : users) { if (user.getLogin().toUpperCase().equals(userEmail.toUpperCase())) { String uid = user.getID(); boxAPI.asUser(uid); BoxCollaborator collabGroup = new BoxGroup(boxAPI, groupId); try { if (fType.equals("file")) { BoxFile file = new BoxFile(boxAPI, fId); file.collaborate(collabGroup, BoxCollaboration.Role.VIEWER, false, false); } else if (fType.equals("folder")) { BoxFolder folder = new BoxFolder(boxAPI, fId); folder.collaborate(collabGroup, BoxCollaboration.Role.VIEWER); } } catch (Exception ex) { System.err.println("Collaboration failed"); } boxAPI.asSelf(); } } } ``` # 前の手順が完了していません 最初に、手順1でお好みの言語/フレームワークを選択してください。 このコードでは、最初に、コンテンツの共有先となるSlackチャンネル用にBoxグループIDを取得します。 スラッシュコマンドを送信したユーザーのBoxアカウントからファイルやフォルダを共有するため、次に、そのユーザーのBoxユーザープロフィールをメールアドレスに基づいて取得します。 最後に、グループIDを使用して、コンテンツでグループとコラボレーションするための呼び出しを行います。 ## まとめ - Boxクライアントをインスタンス化しました。 - Boxグループユーザーを追加および削除するための関数を作成しました。 - コンテンツをグループと共有するための関数を作成しました。 Boxの関数を設定しました **Source:** [https://ja.developer.box.com/guides/collaborations/connect-slack-to-group-collabs/connect-box-functions/](https://ja.developer.box.com/guides/collaborations/connect-slack-to-group-collabs/connect-box-functions/) --- ### Boxへのログイン **Type:** quick-start | **Category:** ツール | **Section:** Developer Guides Boxへのログイン この手順では、前の手順のクライアントIDとクライアントシークレットを使用してログインし、ユーザー用にアクセストークンを作成します。 ログインする理由 現時点では、以下の情報が提示されています。 クライアントID… # Boxへのログイン この手順では、前の手順の**クライアントID**と**クライアントシークレット**を使用してログインし、ユーザー用に**アクセストークン**を作成します。 ## ログインする理由 現時点では、以下の情報が提示されています。 クライアントID クライアントシークレット 任意のプログラムやコードは、これらの**資格情報**を使用することで、**Box API**から認証を受けることができます。これは、作成した**Boxアプリ**を表しますが、**ユーザー**に関する情報をAPIに伝えることはありません。 ユーザー自身が認証を受けるには、ブラウザでBoxのログイン画面を開き、自分の**ユーザー**アカウントへのアクセスを**Boxアプリ**に承認する必要があります。 このフローの設定は難しい場合があるため、簡単に行えるように下のボタンを用意しました。 ## Boxアプリへのログイン ## ログインしました ブラウザで[Boxの承認](e://get-authorize)画面が開かれ、そこで、アプリケーションに自分のユーザーアカウントへのアクセスを許可しました。アクセスを許可した後、ブラウザは`code`によりこのサイトにリダイレクトされました。 その後、この有効期間が短い`code`が有効期間が長い**アクセストークン**と**更新トークン**に[交換されました](e://post-oauth2-token)。これらのトークンは**ユーザー**を表します。 名前 アクセストークン 更新トークン # セキュリティに関する注意 API資格情報は、ブラウザキャッシュに保存されています。このガイドで後から出てくる**リセット**ボタンをクリックして、この情報を消去することを強くお勧めします。 # 前の手順が完了していません 前の手順を完了し、使用する**Boxアプリ**をセットアップしてください。 ## まとめ - 独自の**Boxアプリ**またはあらかじめ設定されているアプリを使用して**Boxアカウント**にログインしました - **Boxアプリ**にユーザーアカウントへのアクセスを許可しました - このページでユーザーアカウントの**アクセストークン**と**更新トークン**を参照できるようになりました Boxへのログインが完了しました **Source:** [https://ja.developer.box.com/guides/tooling/postman/quick-start/log-in-to-box/](https://ja.developer.box.com/guides/tooling/postman/quick-start/log-in-to-box/) --- ### CLI **Type:** guide | **Category:** CLI | **Section:** Developer Guides CLI Box Command Line Interface (CLI) は、ターミナルウィンドウまたはコマンドプロンプトからBox APIにリクエストを行うためのツールです。 クイックスタート OAuth 2.0を使用したBox CLIの使用を開始する。 CLI… # CLI Box Command Line Interface (CLI) は、ターミナルウィンドウまたはコマンドプロンプトからBox APIにリクエストを行うためのツールです。 ## クイックスタート [OAuth 2.0を使用したBox CLIの使用を開始する](g://cli/quick-start)。 ## CLIの設定と使用 - [サーバー認証](g://authentication/jwt)方法を使用するには、[こちら](g://cli/cli-docs/jwt-cli)のガイドを参照してください。 - [CCG認証](g://authentication/client-credentials)方法を使用するには、[こちら](https://github.com/box/boxcli/tree/main/docs/configure.md#box-configureenvironmentsadd-path)のガイドを参照してください。 - CLIコマンドを使用して一括操作を行うには、[こちら](https://github.com/box/boxcli/blob/main/docs/Bulk%20actions/README.md)のガイドを参照してください。 ## サンプルスクリプト Box CLIの使用自体が役に立ちますが、PowerShellスクリプトと組み合わせるとさらに強力になります。反復タスクの自動化を開始できるように、スクリプトテンプレートの[ライブラリ](https://github.com/box/boxcli/tree/main/examples)を作成しました。 - [サンプルスクリプトを探す](g://cli/scripts/index) ## 高度な機能 このGitHubページには、上級CLIユーザーの参考となりそうなその他のガイドも用意されています。 - [オートコンプリートの設定](https://github.com/box/boxcli/blob/main/docs/autocomplete.md) - [別のアプリの構成](https://github.com/box/boxcli/blob/main/docs/configure.md#box-configureenvironmentsadd-path) - [アカウントの切り替え](https://github.com/box/boxcli/blob/main/docs/configure.md#box-configureenvironmentsswitch-user-userid) - [トークンのキャッシュ](https://github.com/box/boxcli/blob/main/docs/configure.md#box-configureenvironmentsupdate-name) **Source:** [https://ja.developer.box.com/guides/cli/](https://ja.developer.box.com/guides/cli/) --- ### CLIガイド **Type:** guide | **Category:** CLI | **Section:** Developer Guides CLIガイド Box CLIの機能の使用方法のガイドを以下に示します。 JWT認証を使用したBox CLIを設定してテストする。 Box CLI一括コマンドを設定してテストする。 # CLIガイド Box CLIの機能の使用方法のガイドを以下に示します。 - [JWT認証を使用したBox CLI](g://cli/cli-docs/jwt-cli)を設定してテストする。 - [Box CLI一括コマンド](g://cli/cli-docs/bulk-commands)を設定してテストする。 **Source:** [https://ja.developer.box.com/guides/cli/cli-docs/](https://ja.developer.box.com/guides/cli/cli-docs/) --- ### CLIサンプルスクリプト **Type:** guide | **Category:** CLI | **Section:** Developer Guides CLIサンプルスクリプト Box CLIのスクリプトは、タスクの自動化に役立つよう設計されています。現在、ユーザーが使用、カスタマイズできるいくつかのPowerShellスクリプトがサンプルスクリプトライブラリで提供されています。これらのスクリプトを実行するには、Box CLI… # CLIサンプルスクリプト Box CLIのスクリプトは、タスクの自動化に役立つよう設計されています。現在、ユーザーが使用、カスタマイズできるいくつかのPowerShellスクリプトがサンプルスクリプトライブラリで提供されています。これらのスクリプトを実行するには、Box CLIをインストールし、構成しておく必要があります。これは、[クイックスタートガイド](g://cli/quick-start/create-oauth-app)に従って実行することができます。 以下のスクリプトのほとんどでは、コマンドの実行に使用するユーザーにBoxの[管理者権限](https://support.box.com/hc/en-us/articles/360043694174-Understanding-Administrator-and-Co-Administrator-Permissions)が必要です。 ## PowerShellスクリプト - [ユーザーとフォルダのプロビジョニング](g://cli/quick-start/powershell-script-templates) - [ユーザーのプロビジョニング解除とフォルダのアーカイブ](g://cli/scripts/deprovision-users) - [グループとコラボレーションの管理](g://cli/scripts/manage-groups-collaborations) - [非アクティブなユーザーのレポート](g://cli/scripts/report-inactive-users) - [メタデータの抽出](g://cli/scripts/metadata-extraction) - [ユーザーのゾーンの更新](g://cli/scripts/user-zones-mass-update) - [Slack統合フォルダマッピングの管理](g://cli/scripts/slack-integration-mappings) **Source:** [https://ja.developer.box.com/guides/cli/scripts/](https://ja.developer.box.com/guides/cli/scripts/) --- ### CLIのインストールと構成 **Type:** quick-start | **Category:** CLI | **Section:** Developer Guides CLIのインストールと構成 Windows用およびmacOS用のインストーラが提供されていますが、その他の環境でCLIを構築する場合はRawソースコードを利用できます。 Windows用およびmacOS用インストーラ お使いのマシンに最新のCLI… # CLIのインストールと構成 Windows用およびmacOS用のインストーラが提供されていますが、その他の環境でCLIを構築する場合はRawソースコードを利用できます。 ## Windows用およびmacOS用インストーラ お使いのマシンに最新のCLIをインストールするには、最新リリースに対応する最新の`.exe` (Windowsの場合) または`.pkg` (macOSの場合) をダウンロードします。 最新のCLIインストーラをダウンロード ## LinuxとNodeのインストール さらに、CLIは、任意のプラットフォーム (Linuxなど) にNodeパッケージとしてインストールすることができます。このためには、[Node JS](https://nodejs.org/)をマシンにインストールしておく必要があります。 ``` npm install --global @box/cli ``` ## ソースコード CLIのソースコードは、[GitHub](https://github.com/box/boxcli)で提供されています。 ## 構成コマンドの実行 ここで、BoxアプリにログインしてCLIを構成する必要があります。 この手順では、前の手順の**クライアントID**と**クライアントシークレット**を使用してログインし、ユーザー用に**アクセストークン**を作成します。 ## ログインする理由 現時点では、以下の情報が提示されています。 クライアントID クライアントシークレット ターミナルまたはコマンドラインを開き、`box login -n example_name`コマンドを実行します。 求められたら、ターミナルウィンドウにクライアントIDとクライアントシークレットをコピーします。 ブラウザウィンドウに表示された [**Boxへのアクセスを許可**] ボタンをクリックします。 成功すると、成功を示す次のメッセージが表示されます。 ## 構成の確認 うまく構成されているか確認するには、`box users:get me`コマンドを入力して、Box CLIで最初のBox APIコールを実行します。 成功を示すレスポンスには、ユーザーアカウントの詳細が示されます。 ``` Type: user ID: ''0123456789'' Name: Aaron Levie Login: example@box.com Created At: '2020-01-01T09:45:01-07:00' Modified At: '2021-03-01T09:30:05-07:00' Language: en Timezone: America/Los_Angeles Space Amount: 999999999999999 Space Used: 6291500 Max Upload Size: 16106127360 Status: active Job Title: '' Phone: '' Address: example+user@box.com Avatar URL: '' Notification Email: [] ``` ## まとめ - CLIをインストールしました。 - 前に作成したOAuth 2.0アプリケーションを使用するようCLIを構成しました。 - **Box CLIの最初のBox APIコールを実行**し、アクセストークンに関連付けられたユーザーを確認しました。 CLIをインストールして構成しました # 前の手順が完了していません 前の手順を完了し、使用する**Boxアプリ**をセットアップしてください。 **Source:** [https://ja.developer.box.com/guides/cli/quick-start/install-and-configure/](https://ja.developer.box.com/guides/cli/quick-start/install-and-configure/) --- ### CLIの一括コマンド **Type:** guide | **Category:** CLI | **Section:** Developer Guides CLIの一括コマンド Box CLIの一括コマンドを使用すると、反復タスクを自動化できます。コマンドに--bulk-file-pathフラグを追加すると、多数の項目に対して操作を一度に実行できます。 たとえば、次のコマンドは、CSVファイルを使用してフォルダの名前 (Name… # CLIの一括コマンド Box CLIの一括コマンドを使用すると、反復タスクを自動化できます。コマンドに`--bulk-file-path`フラグを追加すると、多数の項目に対して操作を一度に実行できます。 たとえば、次のコマンドは、CSVファイルを使用してフォルダの名前 (`Name`)、説明 (`Description`)、親フォルダの`ParentId`を指定し、複数のフォルダを作成します。 ``` box folders:create --bulk-file-path <PATH_TO_CSV>/folders-create.csv ``` ## CSVテンプレート あらかじめ定義されたCSVテンプレートを使用すると、一括で管理したいデータを構造化できます。テンプレートは[`Bulk actions`](https://github.com/box/boxcli/tree/main/docs/Bulk%20actions)ディレクトリにあり、複数のフォルダに分類されています。現在利用できるテンプレートは、以下の表に示すとおりです。 | テンプレート | 説明 | | --- | --- | | box collaborations | コラボレーションを作成、削除、更新します。 | | box files | ファイルをダウンロード、更新、アップロードします。 | | box folders | フォルダの作成と更新、フォルダへのメタデータの追加を行います。 | | box groups | グループの作成とメンバーシップの追加を行います。 | | box metadata-templates | メタデータテンプレートと、フォルダのメタデータカスケードポリシーを作成します。 | | box shared-links | 共有リンクを削除します。 | | box users | ユーザーの作成と更新、あるユーザーから別のユーザーへのコンテンツの移動を行います。 | | box webhooks | Webhookを削除します。 | ## 前提条件 一括コマンドを使用するには、OAuth 2.0認証を使用するBoxアプリケーションが必要です。該当するアプリケーションがない場合は、[開発者コンソール](https://app.box.com/developers/console)に移動して、[OAuth 2.0を使用した設定](g://authentication/oauth2/oauth2-setup)ガイドに従ってください。 ## 一括コマンドの設定と使用 1. `boxcli` GitHubリポジトリを複製するか、[`Bulk actions`](https://github.com/box/boxcli/tree/main/docs/Bulk%20actions)ディレクトリからファイルをダウンロードします。 ``` git clone https://github.com/box/boxcli.git ``` 必要に応じて`.csv`テンプレートを調整します。たとえば、複数のフォルダを作成する場合は、出発点として[`folders-create.csv`](https://github.com/box/boxcli/blob/main/docs/Bulk%20actions/folders/folders-create.csv)テンプレートを使用できます。 コマンドを実行します。 ``` box users:create --bulk-file-path <PATH_TO_CSV>/folders-create.csv ``` **Source:** [https://ja.developer.box.com/guides/cli/cli-docs/bulk-commands/](https://ja.developer.box.com/guides/cli/cli-docs/bulk-commands/) --- ### Content Open With **Type:** guide | **Category:** Boxの埋め込み | **Section:** Developer Guides Content Open With 日本時間2021年12月22日をもって、新規のお客様に対するOpenWith UI Elementのサポートは終了しました。 Box Content Open With UI Elementを使用すると、開発者は、Box… # Content Open With 日本時間2021年12月22日をもって、新規のお客様に対する`OpenWith` UI Elementのサポートは終了しました。 Box Content Open With UI Elementを使用すると、開発者は、Boxに保存されているコンテンツをパートナーアプリケーションまたはローカルのデスクトップで開くためのドロップダウンを埋め込むことができます。 このElementは、有効化された統合に関する情報をBox APIを使用して取得し、パートナーのサービスを呼び出します。その後、ユーザーはこれらのサービスで操作を行うと、編集したコンテンツはBoxに自動的に保存されます。 Open With Elementに含まれる統合には、Google SuiteおよびBox Editがあります。Google Suiteの統合の詳細については、[Boxコミュニティサイト](https://support.box.com/hc/ja/articles/360043696994-Box-for-Google-Workspace%E3%81%AB%E3%81%A4%E3%81%84%E3%81%A6)を参照してください。 現在、この要素では、認証用に[App User](page://platform/user-types)のみがサポートされています。 ## インストール NPMまたはBox CDN経由でBox UI Elementsをインストールする方法は、[こちら](g://embed/ui-elements/installation)を参照してください。 ## Box Edit Box Editでは、カスタムアプリケーションに統合するために追加の設定が必要です。Box Editでは、コンテンツをローカルで開くためにデスクトップアプリケーションの[Box Tools](https://support.box.com/hc/ja/categories/360003188014-Box-Tools)を使用します。 - リクエストでは (`https`ドメインからの) セキュアな接続を使用する必要があります。 - アプリケーションのドメインは、Box Toolsで許可する必要があります。手順については、[こちら](g://embed/ui-elements/custom-domains)を参照してください。理想的なワークフローでは、Box Toolsもインストールされるインストーラにこれらの手順をバンドルします。 - Safariでは、Box Toolsに接続するためにブラウザの機能拡張が必要です。詳細については、[こちら](https://support.box.com/hc/ja/articles/360043697334-Box-Tools%E3%81%AE%E3%82%A4%E3%83%B3%E3%82%B9%E3%83%88%E3%83%BC%E3%83%AB)を参照してください。 ## G Suite Box for G Suiteの統合を使用するには、有効なG Suiteアカウントが必要です。ユーザーのG SuiteとBoxアカウントを接続するには、App Userの`external_app_user_id`を、ユーザーのG Suiteアカウントに関連付けられたメールアドレスに更新する必要があります。 App Userの`external_app_user_id`は、[`PUT /users/:id`](e://put-users-id)エンドポイントを介して更新できます。 ## 設定 Open With UI Elementを使用する前に、アプリケーションを許可し、Box APIエンドポイントを使用してApp Userのために統合を有効にしておく必要があります。 ### アプリケーションのアクティブ化 「Open With」UI Elementは、Box Platformを使用して構築するすべての開発者が使用できます。インスタンスに対してこの要素をアクティブ化するには、開発者コンソールでアプリケーションに [統合を有効化] スコープを追加します。 アプリケーションは、APIコールに対してアクティブ化されたら、会社での再認証が必要になります。この操作を実行する手順については、[こちら](g://authorization/custom-app-approval)を参照してください。 ## 使用可能な統合のリストの取得 アプリ統合をユーザーに割り当てるには、まず、使用可能な統合のリストを取得します。この`GET`リクエストは、次の`cURL`リクエストを使用して実行できます。 ``` curl -X GET https://api.box.com/2.0/app_integrations \ -H 'Authorization: Bearer [ACCESS_TOKEN]' ``` ``` { "next_marker": null, "entries": [ { "type": "app_integration", "id": "10897" }, { "type": "app_integration", "id": "1338" }, { "type": "app_integration", "id": "13418" }, { "type": "app_integration", "id": "3282" } ], "limit": 100 } ``` アプリ統合IDを使用して、指定したユーザーに統合を割り当てます。 ## 特定の統合の取得 IDに基づいて、特定の統合に関する追加情報を取得するには、次のGETリクエストを実行できます。 ``` curl -X GET \ https://api.box.com/2.0/app_integrations/[APP_INTEGRATION_ID] \ -H 'Authorization: Bearer [ACCESS_TOKEN]' ``` ``` { "type": "app_integration", "id": "10897", "app": { "type": "app", "id": "336417" }, "name": "Edit with G Suite", "description": "Securely manage your Google Docs, Sheets and Slides in Box", "executable_item_types": [ "file" ], "restricted_extensions": [ "docx", "gdoc", "xlsx", "gsheet", "pptx", "gslides", "gslide" ], "scoped_to": "parent" } ``` ## ユーザーへの統合の追加 有効なApp Userにアプリ統合を追加するには、以下の3つの情報が必要です。 - 有効な[サービスアカウント](page://platform/user-types/#service-account)アクセストークン - 統合を割り当てるApp UserのID - ユーザーに割り当てるアプリ統合のID アプリ統合に関する情報を取得するための前述の2つのリクエストは、有効な開発者トークンなど、任意の有効なトークンを使用して実行できますが、アプリ統合を追加および削除するには、有効なサービスアカウントのアクセストークンが必要です。開発者トークンを使用すると`404 Not Found`エラーが発生します。 アプリ統合をApp Userに割り当てるには、次の`POST`リクエストを実行できます。 ``` curl -X POST https://api.box.com/2.0/app_integration_assignments \ -H 'Authorization: Bearer [SERVICE_ACCOUNT_TOKEN]' \ -d '{ "assignee": { "type": "user", "id": "[APP_USER_ID]" }, "app_integration": { "type": "app_integration", "id": "[APP_INTEGRATION_ID]" } }' ``` ``` { "type": "app_integration_assignment", "id": "72048301", "assignee": { "type": "user", "id": "6084519920" }, "app_integration": { "type": "app_integration", "id": "3282" } } ``` JSONレスポンスに含まれるIDは、割り当て後にアプリ統合を管理するために使用できるため、アプリケーションで保存する必要があります。 ## ユーザーからの統合の削除 App Userからアプリ統合を削除するには、有効なサービスのアクセストークンと、前の手順で取得したアプリ統合割り当てIDを使用して次のリクエストを実行できます。 ``` curl -X DELETE https://api.box.com/2.0/app_integration_assignments/[APP_INTEGRATION_ASSIGNMENT_ID] \ -H 'Authorization: Bearer [SERVICE_ACCOUNT_TOKEN]' ``` ``` 204 No Content ``` ## サンプルHTML ``` <!DOCTYPE html> <html lang="en-US"> <head> <meta charset="utf-8" /> <title>Box Content Open With Demo</title> <!-- Latest version of the open with css for your locale --> <link rel="stylesheet" href="https://cdn01.boxcdn.net/platform/elements/{VERSION}/en-US/openwith.css" /> </head> <body> <div class="container" style="height:600px"></div> <!-- Latest version of the open with js for your locale --> <script src="https://cdn01.boxcdn.net/platform/elements/{VERSION}/en-US/openwith.js"></script> <script> var fileId = "123"; var accessToken = "abc"; var contentOpenWith = new Box.ContentOpenWith(); contentOpenWith.show(fileId, accessToken, { container: ".container" }); </script> </body> </html> ``` ## デモ ### Open Withの例 ### コンテンツエクスプローラとOpen Withの例 # アクセストークン 上記のデモは、デモの [JS] タブで有効なアクセストークンを指定しなければ、十分に機能しない可能性があります。Open With Elementの場合は、有効な[サービスアカウント](page://platform/user-types/#service-account)アクセストークンを指定する必要があります。 ## 認証 UI Elementは認証に依存しない方法で設計されているため、Boxアカウントを持つユーザー (管理対象ユーザー) とBox以外のアカウントを持つユーザー (App User) のどちらにUI Elementを使用するかどうかに関係なく、UI Elementを使用するのに特別な設定は必要ありません。その理由は、UI Elementは認証のために「トークン」を受け取ることのみを予期しており、Boxにはトークンの生成方法としてOAuthとJWTの2つがあるからです。 認証方法の選択について確認する ## スコープ ダウンスコープされたトークンを使用して統合を実行するには、`item_execute_integration`スコープに加えて、使用する特定の統合で必要となるスコープを含める必要があります。 - **Google**: 親フォルダに対する`item_readwrite` - **Adobe**: `root_readwrite` - **Box Edit**: 親フォルダに対する`item_readwrite` - **Box Edit単一ファイルコラボレーション**: ファイルに対する`item_readwrite` スコープの詳細については、[こちら](guide://api-calls/permissions-and-errors/scopes)を参照してください。 ## API ``` const { ContentOpenWith } = Box; const contentOpenWith = new ContentOpenWith(); /** * Shows the content open with element. * * @param {string} fileId - The root file id * @param {string} accessToken - Box API access token * @param {Object} [options] - Options * @return {void} */ contentOpenWith.show(fileId, accessToken, options); /** * Hides the content open with element, removes all event listeners, * and clears out the * HTML. * * @return {void} */ openWith.hide(); /** * Adds an event listener to the content open with element. Listeners should be added * before calling show() so no events are missed. * * @param {string} eventName - Name of the event * @param {Function} listener - Callback function * @return {void} */ contentOpenWith.addListener(eventName, listener); /** * Removes an event listener from the content open with element. * * @param {string} eventName - Name of the event * @param {Function} listener - Callback function * @return {void} */ contentOpenWith.removeListener(eventName, listener); /** * Removes all event listeners from the content open with element. * * @return {void} */ contentOpenWith.removeAllListeners(); ``` ### パラメータ | パラメータ | 型 | 説明 | | --- | --- | --- | | fileId | String | BoxファイルID。統合の実行対象となるファイルのIDです。 | | accessToken | String | 使用するBox APIアクセストークン。このトークンには、上記のフォルダに対する読み取り/書き込みアクセス権限が必要です。このトークンのために渡される値は、エクスプローラの表示中は有効期限切れにならないことが前提となっています。 | | options | Object | 省略可能なオプション。詳細は以下を参照してください。たとえば、contentExplorer.show(FOLDER_ID, TOKEN, {canDelete: false})を使用すると、削除オプションが非表示になります。 | ### オプション | パラメータ | 型 | 説明 | | | --- | --- | --- | --- | | dropdownAlignment | `left | right` | [開く] ボタンに対するドロップダウンの位置を決定します。デフォルトはrightです。 | | boxToolsName | String | この文字列は、「このファイルをデスクトップで開くにはBox Toolsをインストールしてください」というメッセージ内のBox Toolsの名前に置き換わります。 | | | boxToolsInstallUrl | String | このURLは、「このファイルをデスクトップで開くにはBox Toolsをインストールしてください」というメッセージ内でリンクされている、デフォルトのBoxインストール手順の代わりに使用されます。 | | | onExecute | Function | 統合の呼び出しが試行されたときに実行されるコールバック。 | | | onError | Function | エラーが発生したときに実行されるコールバック。 | | | requestInterceptor | Function | リクエストをインターセプトする関数。例については、このCodePenを参照してください。基盤となるXHRライブラリはaxios.jsで、インターセプタでは同様のアプローチに従っています。 | | | responseInterceptor | Function | レスポンスをインターセプトする関数。例については、このCodePenを参照してください。基盤となるXHRライブラリはaxios.jsで、インターセプタでは同様のアプローチに従っています。 | | 現在、`onError`イベントと`onExecute`イベントは、既知のバグの影響を受けています。一時的な回避策として`openWith.addListener('execute', callback)`および`openWith.addListener('error', callback)`を使用することをお勧めします。 ### イベント | イベント名 | イベントデータ | 説明 | | --- | --- | --- | | execute | 統合ID | 統合の呼び出しが実行されたときに発生します。 | | error | エラー | エラーが発生したときに発生します。 | **Source:** [https://ja.developer.box.com/guides/embed/ui-elements/open-with/](https://ja.developer.box.com/guides/embed/ui-elements/open-with/) --- ### Content Picker **Type:** guide | **Category:** Boxの埋め込み | **Section:** Developer Guides Content Picker Box Content Picker UI Elementを使用すると、開発者は、デスクトップまたはモバイルウェブアプリでBoxからファイルやフォルダを選択するためのサポートを追加できます。ライブラリは、指定されたフォルダに関する情報をBox API… # Content Picker Box Content Picker UI Elementを使用すると、開発者は、デスクトップまたはモバイルウェブアプリでBoxからファイルやフォルダを選択するためのサポートを追加できます。ライブラリは、指定されたフォルダに関する情報をBox APIを介して取得し、そのコンテンツをフォルダビューにレンダリングします。ユーザーはファイルまたはフォルダを選択でき、その後、このコンテンツ情報がアプリケーションの別の部分に渡されます。 ## インストール NPMまたはBox CDN経由でBox UI Elementsをインストールする方法は、[こちら](g://embed/ui-elements/installation)を参照してください。 ## 認証 UI Elementは認証に依存しない方法で設計されているため、Boxアカウントを持つユーザー (管理対象ユーザー) とBox以外のアカウントを持つユーザー (App User) のどちらにUI Elementを使用するかどうかに関係なく、UI Elementを使用するのに特別な設定は必要ありません。その理由は、UI Elementは認証のために「トークン」を受け取ることのみを予期しており、Boxにはトークンの生成方法としてOAuthとJWTの2つがあるからです。 認証方法の選択について確認する ## サンプルHTML ``` <!DOCTYPE html> <html lang="en-US"> <head> <meta charset="utf-8" /> <title>Box File Selection</title> <!-- Latest version of the picker css for your locale --> <link rel="stylesheet" href="https://cdn01.boxcdn.net/platform/elements/{VERSION}/en-US/picker.css" /> </head> <body> <div class="container" style="height:600px"></div> <!-- Latest version of the picker js for your locale --> <script src="https://cdn01.boxcdn.net/platform/elements/{VERSION}/en-US/picker.js"></script> <script> var folderId = "123"; var accessToken = "abc"; var filePicker = new Box.FilePicker(); filePicker.show(folderId, accessToken, { container: ".container" }); </script> </body> </html> ``` ## デモ ### ファイル選択のデモ ### フォルダ選択のデモ ### ファイル選択とプレビューのデモ ### ポップアップ形式でのファイル選択 # アクセストークン 上記のデモは、有効なアクセストークンを指定しなければ、完全に動作しない可能性があります。テスト目的の場合は、一時的な開発者トークンを使用できます。このトークンは、デモにある [JS] タブで更新する必要があります。 ## API ``` const { FilePicker } = Box; const filePicker = new FilePicker(); /** * Shows the file selection. * * @public * @param {String} folderId - The root folder id. * @param {String} accessToken - The API access token. * @param {Object|void} [options] - Optional options. * @return {void} */ filePicker.show(folderId, accessToken, options); /** * Hides the file picker, removes all event listeners, and clears out the HTML. * * @public * @return {void} */ filePicker.hide(); /** * Clears out the internal in-memory cache for the file picker. This forces * items to be reloaded from the API. * * @public * @return {void} */ filePicker.clearCache(); /** * Adds an event listener to the file picker. Listeners should be added before * calling show() so no events are missed. * * @public * @param {String} eventName - Name of the event. * @param {Function} listener - Callback function. * @return {void} */ filePicker.addListener(eventName, listener); /** * Removes an event listener from the file picker. * * @public * @param {String} eventName - Name of the event. * @param {Function} listener - Callback function. * @return {void} */ filePicker.removeListener(eventName, listener); /** * Removes all event listeners from the file picker. * * @public * @return {void} */ filePicker.removeAllListeners(); ``` ### パラメータ | パラメータ | 型 | 説明 | | --- | --- | --- | | folderId | String | BoxフォルダのID。選択しようとしているコンテンツが含まれるフォルダのIDです。Boxの [すべてのファイル] フォルダを使用する場合は、folderIdとして0を使用します。 | | accessToken | String | 使用するBox APIアクセストークン。このトークンには、上記のフォルダに対する読み取り/書き込みアクセス権限が必要です。このトークンのために渡される値は、エクスプローラの表示中は有効期限切れにならないことが前提となっています。 | | options | Object | 省略可能なオプション。詳細は以下を参照してください。たとえば、contentExplorer.show(FOLDER_ID, TOKEN, {canDelete: false})を使用すると、削除オプションが非表示になります。 | ### オプション | パラメータ | 型 | デフォルト | 説明 | | | --- | --- | --- | --- | --- | | container | String | document.body | Content Pickerが配置されるコンテナのCSSセレクタ。hide() を呼び出すと、このコンテナは空になります。 | | | sortBy | String | name | コンテンツリストの最初の並べ替え基準オプション。値は名前またはdateになります。 | | | sortDirection | String | ASC | コンテンツリストの最初の並べ替え方向オプション。値はASCまたはDESCになります。 | | | logoUrl | String | | ヘッダーに表示するカスタムロゴのURL。この値が「box」という文字列の場合は、Boxのロゴが表示されます。 | | | extensions | Array<string> | [] | 選択対象として許可するファイル拡張子の配列 (例: ['doc', 'ppt'])。ファイル選択機能のみに適用され、フォルダ選択機能には適用されません。拡張子が指定されている場合は、その拡張子のみを選択できます。空の配列の場合は、すべてのファイル拡張子が選択対象として許可されることを示します。 | | | maxSelectable | Number | Infinity | 選択可能なファイルまたはフォルダの数。ファイルまたはフォルダが1つだけ選択されるようにする場合は1を指定します。 | | | canUpload | Boolean | true | これをfalseに設定すると、アップロードオプションが非表示になります。このオプションを非表示にするだけではアップロードを防ぐことはできず、現在のフォルダに対する権限でもcan_uploadをfalseに設定する必要があります。フォルダに対する権限can_uploadがfalseに設定されている場合、このオプションによる効果はありません。 | | | canSetShareAccess | Boolean | true | falseに設定すると、共有ドロップダウン選択が非表示になります。この選択のドロップダウンを非表示にするだけでは共有権限の変更を防ぐことはできず、フォルダ項目に対する権限でもcan_set_share_accessをfalseに設定する必要があります。フォルダ項目に対する権限can_set_share_accessがfalseに設定されている場合、このオプションによる効果はありません。 | | | canCreateNewFolder | Boolean | true | フォルダの新規作成オプションが非表示になります。このオプションを非表示にするだけではフォルダの新規作成を防ぐことはできず、フォルダ項目に対する権限でもcan_uploadをfalseに設定する必要があります。フォルダ項目に対する権限can_uploadがfalseに設定されている場合、このオプションによる効果はありません。 | | | sharedLink | String | | 共有リンクのURL。フォルダが共有されており、アクセストークンがファイルの所有者またはコラボレータに属していない場合は必須です。 | | | sharedLinkPassword | String | | 共有リンクのパスワード。共有リンクにパスワードが設定されている場合は必須です。 | | | modal | Object | | ウィンドウ属性を指定すると、Content Pickerは所定の位置に作成されません。代わりに、コンテナ内にボタンが作成され、そのボタンをクリックすると、ウィンドウポップアップでContent Pickerが起動します。 | | | size | String | undefined | Content Pickerが、幅がsmallまたはlargeのコンテナに合わせて表示されるように示します。値には空白か、smallまたはlargeを指定できます。空白にした場合、UI Elementはそのコンテナに合わせて調整され、自動でsmallの幅とlargeの幅が切り替わります。 | | | isTouch | Boolean | デフォルトでは、ブラウザとデバイスのデフォルトのタッチサポートが設定されます。 | コンテンツエクスプローラがタッチ対応デバイスにレンダリングされることを示します。 | | | autoFocus | Boolean | false | trueに設定すると、初回読み込み時に項目グリッドに焦点が当てられます。 | | | defaultView | String | files | 値はfilesまたはrecentsになります。recentsに設定すると、デフォルトで、通常のファイル/フォルダ構造ではなく最近使用した項目が表示されます。 | | | chooseButtonLabel | String | | [選択] ボタンのラベルに置き換わる文字列 | | | cancelButtonLabel | String | | [キャンセル] ボタンのラベルに置き換わる文字列 | | | requestInterceptor | Function | | リクエストをインターセプトする関数。例については、このCodePenを参照してください。基盤となるXHRライブラリはaxios.jsで、インターセプタでは同様のアプローチに従っています。 | | | responseInterceptor | Function | | レスポンスをインターセプトする関数。例については、このCodePenを参照してください。基盤となるXHRライブラリはaxios.jsで、インターセプタでは同様のアプローチに従っています。 | | ### ウィンドウオプション | パラメータ | 型 | デフォルト | 説明 | | --- | --- | --- | --- | | buttonLabel | String | | ボタンのラベル | | buttonClassName | String | Boxの青いボタン | ボタンを装飾するためのCSSクラス | | modalClassName | String | | ウィンドウポップアップコンテンツを装飾するためのCSSクラス | | overlayClassName | String | | ウィンドウポップアップオーバーレイを装飾するためのCSSクラス | ### イベント | イベント名 | イベントデータ | 説明 | | --- | --- | --- | | choose | Array<File | Web Link | Folder> | [選択] ボタンが押されたときに発生します。イベントデータは、ファイルの選択とフォルダの選択のどちらであるかに応じて、フォルダオブジェクト、ファイルオブジェクト、またはウェブリンクオブジェクトの配列になります。 | | cancel | | [キャンセル] ボタンが押されたときに発生します。 | ## キーボードショートカット クリックによって手動で、またはJavaScriptや上記の`autoFocus`プロパティによってプログラムで項目グリッドがフォーカスされていると、以下のキーボードショットカットが機能します (対応する操作が適切で許可されている場合)。 | キー | 動作 | | --- | --- | | Arrow Up | 前の項目行 | | Arrow Down | 次の項目行 | | Ctrl/Cmd + Arrow Up | 最初の項目行 | | Ctrl/Cmd + Arrow Down | 最後の項目行 | | / | 検索 | | Shift + X | 項目行を選択 | | Enter | 選択した項目を開く | | g then f | ルートフォルダに移動 | | g then u | 現在のフォルダにアップロード | | g then b | ルートフォルダの階層リンクをフォーカス | | g then s | 選択した項目を表示 | | g then x | キャンセル | | g then c | 選択 | | g then r | 最近使用した項目 | ## スコープ アプリケーションで、エンドユーザーがContent Picker機能のサブセットのみにアクセスできるようにする必要がある場合は、[ダウンスコープ](guide://authentication/tokens/downscope)を使用して、アクセストークンを適切にダウンスコープして必要な権限のセットを含むトークンを生成し、Content Pickerを初期化するエンドユーザークライアントに安全に渡すことができます。 以下は、ダウンスコープと一緒に使用する、UI Element固有の新しいスコープのセットです。こうしたスコープにより、開発者は、ダウンスコープされたトークンに適切なスコープを構成して、Content PickerのUIコントロールを有効/無効にすることができます。詳細については、[Box UI Elementsの専用スコープ](guide://api-calls/permissions-and-errors/scopes)を参照してください。 | スコープ名 | 付与される権限 | | --- | --- | | base_picker | ユーザー/ファイル/トークンの権限に基づいて、フォルダツリー内のコンテンツへのアクセスを許可します。 | ### 機能のスコープ | スコープ名 | 付与される権限 | | --- | --- | | item_share | トークン交換リクエストの「resource」で指定されたリソースの共有を許可します。 | | item_upload | Content Pickerでのアップロードを許可します。 | ### サンプルのシナリオ | シナリオ | スコープ | | --- | --- | | ユーザーが単にフォルダ構造内を移動してファイル/フォルダを選択する | base_picker | | ユーザーがフォルダ構造内を移動して、ファイル/フォルダを選択し、アクセスレベルも設定する | base_picker + item_share | | ユーザーがフォルダ構造内を移動して、ファイル/フォルダを選択し、ファイル/フォルダもアップロードする | base_picker + item_upload | | ユーザーがフォルダ構造内を移動して、ファイル/フォルダを選択し、ファイル/フォルダをアップロードして、ファイル/フォルダのアクセスレベルも設定する | base_picker + item_share + item_upload | ## カスタム操作 コンテンツエクスプローラとContent Pickerでは、ファイルやフォルダの [**その他のオプション**] メニューの操作を拡張できます。カスタムオプションは、ユーザーが省略記号ボタンをクリックすると表示されます。 [**その他のオプション**] メニューをカスタマイズするには、カスタム操作の配列を`itemActions`に渡します。 ``` contentExplorer.show(configData.FOLDER_ID, configData.ACCESS_TOKEN, { container: ".container", itemActions: customActions, }); ``` この配列には、複数の操作を含めることができます。操作オブジェクトには、`label`、`onAction`コールバック関数を含める必要があります。`file`または`folder`の値を渡すことで、特定の項目の`type`のみに表示されるようカスタム操作にフィルタをかけることができます。`filter`値は、特定のファイル拡張子など、高度なフィルタに使用します。 ``` const customActions = [ { label: "Preview in New Window", onAction: (item) => alert('action ' + item), type: 'file', }, { label: "Open in Box.com", onAction: (item) => window.open("https://app.box.com"), }, { label: "Export", onAction: (item) => console.log('action ' + item), filter: (item) => item.extension?.toLowerCase() === 'pdf', }, ]; ``` CodePenで実装例を確認してください。 **Source:** [https://ja.developer.box.com/guides/embed/ui-elements/picker/](https://ja.developer.box.com/guides/embed/ui-elements/picker/) --- ### Content Sidebar **Type:** guide | **Category:** Boxの埋め込み | **Section:** Developer Guides Content Sidebar Box Content Sidebar UI Elementを使用すると、開発者は、ファイル関連のメタデータ (Box Skills… # Content Sidebar Box Content Sidebar UI Elementを使用すると、開発者は、ファイル関連のメタデータ (Box Skillsを含む) とアクティビティフィード (バージョン、コメント、タスクを含む) を表示するためのサポートをデスクトップまたはモバイルウェブアプリで追加できます。 ## インストール NPMまたはBox CDN経由でBox UI Elementsをインストールする方法は、[こちら](g://embed/ui-elements/installation)を参照してください。 ## 認証 UI Elementは認証に依存しない方法で設計されているため、Boxアカウントを持つユーザー (管理対象ユーザー) とBox以外のアカウントを持つユーザー (App User) のどちらにUI Elementを使用するかどうかに関係なく、UI Elementを使用するのに特別な設定は必要ありません。その理由は、UI Elementは認証のために「トークン」を受け取ることのみを予期しており、Boxにはトークンの生成方法としてOAuthとJWTの2つがあるからです。 認証方法の選択について確認する ## サンプルHTML ``` <!DOCTYPE html> <html lang="en-US"> <head> <meta charset="utf-8" /> <title>Box Content Sidebar</title> <!-- Latest version of the sidebar css for your locale --> <link rel="stylesheet" href="https://cdn01.boxcdn.net/platform/elements/{VERSION}/en-US/sidebar.css" /> </head> <body> <div class="container" style="height:600px"></div> <!-- Latest version of the sidebar js for your locale --> <script src="https://cdn01.boxcdn.net/platform/elements/{VERSION}/en-US/sidebar.js"></script> <script> var fileId = "123"; var accessToken = "abc"; // At least one of the sub-sidebars (details, activity feed, skills, metadata) need to be turned on for something to render. Details is iteself further divided into notices, properties, access stats and versions, one of which need to be enabled for the details sidebar to render. var sidebar = new Box.ContentSidebar(); sidebar.show(fileId, accessToken, { container: ".container", detailsSidebarProps: { hasNotices: true, hasProperties: true, hasAccessStats: true, hasVersions: true }, hasActivityFeed: true, hasSkills: true, hasMetadata: true }); </script> </body> </html> ``` ## デモ ### スタンドアロンサイドバー ### コンテンツプレビューを使用したサイドバー ### コンテンツエクスプローラを使用したサイドバー ## API ``` const { ContentSidebar } = Box; const sidebar = new ContentSidebar(); /** * Shows the file selection. * * @public * @param {String} fileId - The file id. * @param {String} token - The API access token. * @param {Object|void} [options] - Optional options. * @return {void} */ sidebar.show(fileId, token, options); /** * Hides the sidebar, removes all event listeners, and clears out the HTML. * * @public * @return {void} */ sidebar.hide(); /** * Clears out the internal in-memory cache for the sidebar. This forces * items to be reloaded from the API. * * @public * @return {void} */ sidebar.clearCache(); /** * Adds an event listener to the sidebar. Listeners should be added before * calling show() so no events are missed. * * @public * @param {String} eventName - Name of the event. * @param {Function} listener - Callback function. * @return {void} */ sidebar.addListener(eventName, listener); /** * Removes an event listener from the sidebar. * * @public * @param {String} eventName - Name of the event. * @param {Function} listener - Callback function. * @return {void} */ sidebar.removeListener(eventName, listener); /** * Removes all event listeners from the sidebar. * * @public * @return {void} */ sidebar.removeAllListeners(); ``` ### パラメータ | パラメータ | 型 | 説明 | | --- | --- | --- | | fileId | String | BoxファイルID。サイドバーが必要なファイルのIDです。 | | token | String | 使用するBox APIアクセストークン。このトークンには、上記のファイルに対する読み取り/書き込みアクセス権限を指定できます。このトークンのために渡される値は、サイドバーの表示中は有効期限切れにならないことが前提となっています。 | | options | Object | 追加のオプション。たとえば、sidebar.show(FILE_ID, TOKEN, {hasProperties: true})を使用すると、サイドバーにファイルのプロパティが表示されます。 | ### オプション | パラメータ | 型 | デフォルト | 説明 | | --- | --- | --- | --- | | container | String | document.body | Content Sidebarが配置されるコンテナのCSSセレクタ。hide()を呼び出すと、このコンテナは空になります。 | | hasActivityFeed | Boolean | false | trueに設定すると、バージョン、コメント、およびタスクを含むアクティビティフィードが表示されます。 | | hasMetadata | Boolean | false | trueに設定すると、ファイルのBoxメタデータが表示されます。 | | hasSkills | Boolean | false | trueに設定すると、ファイルのスキルデータが表示されます。 | | detailsSidebarProps | Object | {} | 以下のセクションを参照してください。 | | requestInterceptor | Function | | リクエストをインターセプトする関数。例については、このCodePenを参照してください。基盤となるXHRライブラリはaxios.jsで、インターセプタでは同様のアプローチに従っています。 | | responseInterceptor | Function | | レスポンスをインターセプトする関数。例については、このCodePenを参照してください。基盤となるXHRライブラリはaxios.jsで、インターセプタでは同様のアプローチに従っています。 | ### detailsSidebarProps | パラメータ | 型 | デフォルト | 説明 | | --- | --- | --- | --- | | hasProperties | Boolean | false | trueに設定すると、詳細サイドバーにファイルのプロパティが表示されます。 | | hasAccessStats | Boolean | false | trueに設定すると、詳細サイドバーにファイルのアクセス統計情報が表示されます。 | | hasVersions | Boolean | false | trueに設定すると、詳細サイドバーにファイルのバージョンが表示されます。 | | hasNotices | Boolean | false | trueに設定すると、詳細サイドバーにファイル関連の通知が表示されます。 | ## スコープ アプリケーションで、エンドユーザーがContent Sidebar機能のサブセットのみにアクセスできるようにする必要がある場合は、[ダウンスコープ](guide://authentication/tokens/downscope)を使用して、アクセストークンを適切にダウンスコープして必要な権限のセットを含むトークンを生成し、Content Sidebarを初期化するエンドユーザークライアントに安全に渡すことができます。 以下は、ダウンスコープと一緒に使用する、UI Element固有の新しいスコープのセットです。こうしたスコープにより、開発者は、ダウンスコープされたトークンに適切なスコープを構成して、Content SidebarのUIコントロールを有効/無効にすることができます。詳細については、[Box UI Elementsの専用スコープ](guide://api-calls/permissions-and-errors/scopes)を参照してください。 ### 基本スコープ | スコープ名 | 付与される権限 | | --- | --- | | base_sidebar | サイドバーに必要なファイルの基本情報の取得をユーザーに許可します。 | ### 機能のスコープ | スコープ名 | 付与される権限 | | --- | --- | | item_comment | コメントの追加と編集を許可します。 | | item_rename | ファイルの説明の編集を許可します。 | | item_upload | ファイルのメタデータの編集を許可します。 | | item_task | タスクの作成と解決を許可します。 | **Source:** [https://ja.developer.box.com/guides/embed/ui-elements/sidebar/](https://ja.developer.box.com/guides/embed/ui-elements/sidebar/) --- ### Device Pinner **Type:** guide | **Category:** セキュリティ | **Section:** Developer Guides Device Pinner デバイスの管理と呼ばれる、モバイルデバイスまたはデスクトップデバイスからBoxにアクセスする際のセキュリティを強化するデバイス管理機能を追加しました。これは、ユーザーがBoxへのアクセスに使用するデバイス数の上限を管理者が設定できるようにし、そのBox… # Device Pinner デバイスの管理と呼ばれる、モバイルデバイスまたはデスクトップデバイスからBoxにアクセスする際のセキュリティを強化するデバイス管理機能を追加しました。これは、ユーザーがBoxへのアクセスに使用するデバイス数の上限を管理者が設定できるようにし、そのBoxアカウントへのアクセスに新しいデバイスが使用されるたびに管理者とユーザーにアラートを送信するログイン追跡機能に基づいています。 デバイスの管理の詳細については、Boxの[コミュニティのドキュメント](https://support.box.com/hc/ja/articles/360043693814-%E3%83%87%E3%83%90%E3%82%A4%E3%82%B9%E3%81%AE%E7%AE%A1%E7%90%86%E3%81%AE%E8%A8%AD%E5%AE%9A)を参照してください。 ## API Box APIを使用すると、デバイスピンを検査したり削除したりすることができます。 - [`GET /enterprise/:id/device_pinners`](e://get-enterprises-id-device-pinners): 会社内のすべてのデバイスピンを取得します。 - [`GET /device_pinners/:id`](e://get-device-pinners-id): 個々のデバイスピンに関する情報を取得します。 - [`DELETE /device_pinners/:id`](e://delete-device-pinners-id): 個々のデバイスピンを削除します。 **Source:** [https://ja.developer.box.com/guides/security/device-pinners/](https://ja.developer.box.com/guides/security/device-pinners/) --- ### Enterprise Event **Type:** guide | **Category:** イベント | **Section:** Developer Guides Enterprise Event Enterprise Eventは、企業のBoxインスタンスにあるすべてのユーザーとコンテンツのイベントフィードを提供します。stream_type… # Enterprise Event Enterprise Eventは、企業のBoxインスタンスにあるすべてのユーザーとコンテンツのイベントフィードを提供します。`stream_type`に応じて、アプリケーションは、ライブイベントを登録するかイベントの履歴を照会することができます。これらのストリームタイプへのアクセスは、**新規レポートの実行および既存レポートへのアクセスを行う**ための管理者権限を持つユーザーに制限されます。 **Source:** [https://ja.developer.box.com/guides/events/enterprise-events/](https://ja.developer.box.com/guides/events/enterprise-events/) --- ### Enterprise Eventの取得 **Type:** guide | **Category:** イベント | **Section:** Developer Guides Enterprise Eventの取得 Enterprise Eventを取得するには、stream_typeをadmin_logsまたはadmin_logs_streamingに設定してGET /events APIを呼び出します。 このAPI… # Enterprise Eventの取得 Enterprise Eventを取得するには、`stream_type`を`admin_logs`または`admin_logs_streaming`に設定して[`GET /events`](e://get_events) APIを呼び出します。 このAPIを使用するには、ユーザーが企業の管理者または**新規レポートの実行および既存レポートへのアクセスを行う**のための権限を持つ共同管理者である必要があります。 ## ストリームタイプ | ストリームタイプ | | | --- | --- | | admin_logs | イベントの履歴を最大1年分照会できるようにします | | admin_logs_streaming | ほぼリアルタイムでライブイベントにサブスクライブできるようにします | ## ライブで監視 Box内で生成された最近のイベントをEnterprise全体で監視するには、`stream_type`を`admin_logs_streaming`に設定します。これは、Enterprise Event Stream APIとも呼ばれます。 このフィードでは、時系列の正確さよりもレイテンシの低さを重視しています。つまり、Boxでは、イベントが複数回、時系列に関係なく返される場合があります。イベントは、Boxで処理されるとほぼリアルタイムでAPIを介して返されます。少しの遅延やバッファが発生すると、新しいイベントがカーソル位置の後に書き込まれなくなります。この`stream_type`で取得できるイベントは、2週間分だけです。 ## 履歴の照会 Enterprise全体のイベント履歴を最大1年分照会するには、`stream_type`を`admin_logs`に設定します。これは、 Enterprise Event History APIとも呼ばれます。 このフィードでは、レイテンシよりも完全性を重視しています。つまり、Boxでは、管理イベントが重複することなく時系列で配信されますが、レイテンシはユーザーまたは`admin_logs_streaming`のフィードよりも高くなります。イベントは、フィルタをかけている期間より後に到着する可能性があるため、ほぼリアルタイムで使用すると見逃される場合があります。 ## 匿名ユーザー 場合によっては、イベントフィードには、IDが`2`のユーザーが表示される可能性があります。これは、匿名ユーザーを表すBoxの内部識別子です。 匿名ユーザーは、ログインしていないユーザーです。この状況は、ユーザーがコンテンツを操作し、最初にログインを求められない場合にいつでも発生する可能性があります。たとえば、ユーザーが、公開共有リンクを使用してファイルをダウンロードするときなどです。 ## 制限 Enterprise Eventフィードでは、Long pollingがサポートされません。 Boxでのイベントの保存は無期限ではありません。`stream_type`を`admin_logs_streaming`に設定した場合は2週間分のEnterprise Event、`stream_type`を`admin_logs`に設定した場合は1年分のEnterprise Eventを取得できます。また、Box管理コンソールで[エクスポートされるレポート](https://support.box.com/hc/en-us/articles/360043696534-Running-Reports)では、7年分のEnterprise Eventを取得できます。 `admin_logs_streaming`フィードでは、すべての結果を迅速に返すことを重視しています。つまり、Boxでは、イベントが順不同で複数回返される可能性があります。重複するイベントは、イベントIDによって識別できます。 ## イベントタイプによるフィルタ Enterprise Eventフィードでは、イベントタイプによるフィルタがサポートされています。 イベントタイプの完全なリストについては、以下を参照してください。 ## イベントタイプ Enterpriseに対して、以下のイベントがトリガーされます。このリストですべてを網羅しているわけではないため、記載されていないイベントが表示される可能性もあります。 | イベント名 | 説明 | | --- | --- | | ACCESS_GRANTED | Boxサポートに対する自分のアカウントへのアクセス権限の付与 | | ACCESS_REVOKED | Boxサポートに付与した自分のアカウントへのアクセス権限の取り消し | | ADD_DEVICE_ASSOCIATION | デバイスの関連付けの追加 | | ADD_LOGIN_ACTIVITY_DEVICE | 未確認のデバイスからのログイン | | ADMIN_LOGIN | 管理コンソールを使用した管理対象ユーザーアカウントへのログイン | | ANNOTATIONV2_CREATE | 注釈の作成 | | ANNOTATIONV2_DELETE | 注釈の削除 | | ANNOTATIONV2_EDIT | 注釈の編集 | | APPLICATION_CREATED | 開発者コンソールでの新しいアプリケーションの作成 | | APPLICATION_PUBLIC_KEY_ADDED | アプリケーションへの公開キーの追加 | | APPLICATION_PUBLIC_KEY_DELETED | アプリケーションからの公開キーの削除 | | BOX_AI_USER_REQUEST | ユーザーからBox AIに対する質問またはリクエストの送信 | | BOX_AI_USER_FAILED_REQUEST | 質問またはリクエストでのエラー | | CHANGE_ADMIN_ROLE | 管理者の役割の変更 | | CHANGE_FOLDER_PERMISSION | フォルダの権限の変更 | | COLLABORATION_ACCEPT | 招待の承諾 | | COLLABORATION_EXPIRATION | コラボレータへの有効期限の設定 | | COLLABORATION_INVITE | 招待 | | COLLABORATION_REMOVE | コラボレータの削除 | | COLLABORATION_ROLE_CHANGE | ユーザーロールの変更 | | COLLECTION_CREATE | コレクションの作成 | | COLLECTION_DELETE | コレクションの削除 | | COLLECTION_UPDATE | コレクションの更新 | | COLLECTION_ITEM_CREATE | コレクションへの項目の追加 | | COLLECTION_ITEM_DELETE | コレクションからの項目の削除 | | COLLECTION_ITEM_UPDATE | コレクションの項目の更新 | | COMMENT_CREATE | ファイル上でのコメントの作成 | | COMMENT_DELETE | ファイル上のコメントの削除 | | CONTENT_ACCESS | 承認されたエンドユーザーまたはBoxアプリケーションでのプログラムによるファイルへのアクセス | | CONTENT_RECOVERY_REPORT_CREATE | コンテンツリカバリレポートの作成 | | CONTENT_RECOVERY_REPORT_DELETE | コンテンツリカバリレポートの削除 | | CONTENT_RECOVERY_REPORT_INITIATE | コンテンツリカバリレポートの実行 | | CONTENT_WORKFLOW_ABNORMAL_DOWNLOAD_ACTIVITY | 管理コンソールで設定されたポリシーのトリガー | | CONTENT_WORKFLOW_AUTOMATION_ADD | 自動化の追加 | | CONTENT_WORKFLOW_AUTOMATION_DELETE | 自動化の削除 | | CONTENT_WORKFLOW_POLICY_ADD | コンテンツポリシーの追加 | | CONTENT_WORKFLOW_SHARING_POLICY_VIOLATION | 共有ポリシーの違反 | | CONTENT_WORKFLOW_UPLOAD_POLICY_VIOLATION | 管理者が設定したアップロードポリシーの違反 | | COPY | コピー | | DATA_RETENTION_CREATE_RETENTION | リテンションの作成 | | DATA_RETENTION_REMOVE_RETENTION | リテンションの削除 | | DELETE | 削除 | | DELETE_USER | ユーザーの削除 | | DEVICE_TRUST_CHECK_FAILED | デバイストラストチェックの失敗 | | DISABLE_MULTI_FACTOR_AUTH | 多要素認証の無効化 | | DOWNLOAD | ダウンロード | | EDIT | 編集 | | EDIT_USER | ユーザーの編集 | | EDR_CROWDSTRIKE_DEVICE_DETECTED | CrowdStrike Falconプラットフォームによるデバイスの検出 | | EDR_CROWDSTRIKE_NO_BOX_TOOLS | CrowdStrike FalconプラットフォームをサポートするデバイスでのBox Toolsパッケージの未検出 | | EDR_CROWDSTRIKE_BOX_TOOLS_OUTDATED | CrowdStrike FalconプラットフォームをサポートするデバイスでのBox Toolsパッケージの期限切れ | | EDR_CROWDSTRIKE_DRIVE_OUTDATED | CrowdStrike FalconプラットフォームをサポートするデバイスでのBox Driveアプリケーションの期限切れ | | EDR_CROWDSTRIKE_ACCESS_ALLOWED_NO_CROWDSTRIKE_DEVICE | CrowdStrike Falconプラットフォームで識別されていないデバイスへのアクセスの許可 | | EDR_CROWDSTRIKE_ACCESS_REVOKED | CrowdStrike Falconプラットフォームで識別されたデバイスへのアクセスの取り消し | | EMAIL_ALIAS_CONFIRM | ユーザーのメールエイリアスの確認 | | EMAIL_ALIAS_REMOVE | ユーザーのメールエイリアスの削除 | | ENABLE_MULTI_FACTOR_AUTH | 多要素認証の有効化 | | ENTERPRISE_APP_AUTHORIZATION_UPDATE | JWTアプリケーションの承認または再承認 | | EXTERNAL_COLLAB_SECURITY_SETTINGS | 外部コラボレーション用セキュリティ設定の変更 | | FAILED_LOGIN | ログインの失敗 | | FILE_MARKED_MALICIOUS | ファイルでのウイルスの検出。イベントは、通知を希望した企業にのみ送信されます。 | | FILE_WATERMARKED_DOWNLOAD | 電子すかし付きファイルのダウンロード | | GROUP_ADD_ITEM | グループへの項目の追加 | | GROUP_ADD_USER | グループへのユーザーの追加 | | GROUP_ADMIN_CREATED | グループ管理者の追加 | | GROUP_ADMIN_DELETED | グループ管理者の削除 | | GROUP_ADMIN_PERMISSIONS_UPDATED | グループ管理者権限の更新 | | GROUP_CREATION | 新規グループの作成 | | GROUP_DELETION | グループの削除 | | GROUP_EDITED | グループの編集 | | GROUP_REMOVE_ITEM | 管理コンソールを使用したグループからのフォルダの削除 | | GROUP_REMOVE_USER | グループからのユーザーの削除 | | ITEM_EMAIL_SEND | コラボレータへの項目に関するメールの送信 | | ITEM_MODIFY | 変更した項目 | | ITEM_OPEN | 開いた項目 | | ITEM_SHARED_UPDATE | 共有リンク設定の更新 | | ITEM_SYNC | フォルダの同期 | | ITEM_UNSYNC | フォルダの同期の解除 | | LEGAL_HOLD_ASSIGNMENT_CREATE | リーガルホールド割り当ての作成 | | LEGAL_HOLD_ASSIGNMENT_DELETE | リーガルホールド割り当ての削除 | | LEGAL_HOLD_POLICY_CREATE | リーガルホールドポリシーの作成 | | LEGAL_HOLD_POLICY_DELETE | リーガルホールドポリシーの削除 | | LEGAL_HOLD_POLICY_UPDATE | リーガルホールドポリシーの更新 | | LOCK | ロック | | LOGIN | ログイン | | METADATA_INSTANCE_CREATE | メタデータインスタンスの作成 | | METADATA_INSTANCE_DELETE | メタデータインスタンスの削除 | | METADATA_INSTANCE_UPDATE | メタデータインスタンスの更新 | | METADATA_TEMPLATE_CREATE | メタデータテンプレートの作成 | | METADATA_TEMPLATE_UPDATE | メタデータテンプレートの更新 | | METADATA_TEMPLATE_DELETE | メタデータテンプレートの削除 | | MOVE | 移動 | | NEW_USER | ユーザーの作成 | | OAUTH2_ACCESS_TOKEN_REVOKE | OAuth 2.0アクセストークンの取り消し | | PREVIEW | プレビュー | | REMOVE_DEVICE_ASSOCIATION | デバイスの関連付けの削除 | | REMOVE_LOGIN_ACTIVITY_DEVICE | アプリに関連付けられたユーザーセッションの無効化 | | RENAME | ファイルまたはフォルダの名前や説明の変更 | | RETENTION_POLICY_ASSIGNMENT_ADD | リテンションポリシー割り当ての追加 | | SHARE | 共有リンクの有効化 | | SHARE_EXPIRATION | 共有リンクの有効期限の設定 | | SHARED_LINK_SEND | 共有リンクとメッセージ (省略可) を含むメールの送信 | | SHARED_LINK_REDIRECT_OUT_OF_SHARED_CONTEXT | 共有リンクによって発生するリダイレクト | | SHIELD_ALERT | 企業のShieldルールに基づいた、Shieldによる異常なダウンロード、セッション、場所、悪意のあるコンテンツの検出。詳細については、Shieldアラートイベントを参照してください。 | | SHIELD_DOWNLOAD_BLOCKED | Shieldアクセスポリシーに基づいた、エンドユーザーによるファイルのダウンロードのブロック | | SHIELD_EXTERNAL_COLLAB_ACCESS_BLOCKED | 外部コラボレーションへのアクセスのブロック | | SHIELD_EXTERNAL_COLLAB_ACCESS_BLOCKED_MISSING_JUSTIFICATION | 正当な理由がない場合の外部コラボレーションへのアクセスのブロック | | SHIELD_EXTERNAL_COLLAB_INVITE_BLOCKED | 外部コラボレーションへの招待のブロック | | SHIELD_EXTERNAL_COLLAB_INVITE_BLOCKED_MISSING_JUSTIFICATION | 正当な理由がない場合の外部コラボレーションへの招待のブロック | | SHIELD_EXTERNAL_COLLAB_INVITE_JUSTIFIED | 外部コラボレーションへの招待の承認 | | SHIELD_JUSTIFICATION_APPROVAL | Shieldの正当な理由の承認 | | SHIELD_SHARED_LINK_ACCESS_BLOCKED | 共有リンクへのアクセスのブロック | | SHIELD_SHARED_LINK_STATUS_RESTRICTED_ON_CREATE | 共有リンクの作成と、コンテンツへのアクセスの制限 | | SHIELD_SHARED_LINK_STATUS_RESTRICTED_ON_UPDATE | 共有リンクの更新と、コンテンツへのアクセスの制限 | | SHIELD_INFORMATION_BARRIER_ENABLED | Shield情報バリアの有効化 | | SHIELD_INFORMATION_BARRIER_DISABLED | Shield情報バリアの非アクティブ化 | | SHIELD_INFORMATION_BARRIER_PENDING | アクティブ化前のShield情報バリア | | SHIELD_INFORMATION_BARRIER_GROUP_ADD_USER_BLOCKED | 情報バリアの制限による、ユーザーの追加のブロック | | SHIELD_INFORMATION_BARRIER_COLLAB_BLOCKED | 情報バリアの制限による、ユーザーに対するコラボレーション作成のブロック | | SHIELD_INFORMATION_BARRIER_SHARED_ITEM_ACCESS_BLOCKED | 情報バリアの制限による、ユーザーの共有項目へのアクセスのブロック | | SHIELD_INFORMATION_BARRIER_ITEM_MOVE_BLOCKED | 情報バリアの制限による、項目の移動のブロック | | SHIELD_INFORMATION_BARRIER_ITEM_COPY_BLOCKED | 情報バリアの制限による、項目のコピーのブロック | | SHIELD_INFORMATION_BARRIER_ITEM_OWNER_TRANSFER_BLOCKED | 情報バリアの制限による、項目の転送のブロック | | SIGN_DOCUMENT_ASSIGNED | 署名者への署名リクエストの送信 | | SIGN_DOCUMENT_CANCELLED | APIまたはUIでの署名リクエストのキャンセル | | SIGN_DOCUMENT_COMPLETED | 全署名者による署名リクエストへの署名 | | SIGN_DOCUMENT_CONVERTED | 署名用.pdfへの署名リクエストの変換 | | SIGN_DOCUMENT_CREATED | APIまたはUIでの署名リクエストの作成。ドキュメントはまだ署名者に送信されていません。 | | SIGN_DOCUMENT_DECLINED | 署名者による署名リクエストの拒否 | | SIGN_DOCUMENT_EXPIRED | 署名リクエストの期限切れ (署名は未完了) | | SIGN_DOCUMENT_SIGNED | 署名者による署名リクエストへの署名 | | SIGN_DOCUMENT_VIEWED_BY_SIGNER | 署名者による署名用メールの [ドキュメントをレビュー] のクリックまたは署名用URLへのアクセス | | SIGNER_DOWNLOADED | 署名者による署名用ドキュメントのダウンロード | | SIGNER_FORWARDED | 署名者による署名用ドキュメントの転送 | | STORAGE_EXPIRATION | ファイルの自動削除の設定 | | TASK_ASSIGNMENT_UPDATE | タスク割り当ての更新 | | TASK_ASSIGNMENT_CREATE | タスク割り当ての作成 | | TASK_ASSIGNMENT_DELETE | タスク割り当ての削除 | | TASK_CREATE | タスクの作成 | | TASK_UPDATE | タスクのコメントの編集 | | TERMS_OF_SERVICE_ACCEPT | 利用規約の承諾 | | TERMS_OF_SERVICE_REJECT | 利用規約の拒否 | | UNDELETE | 削除の取り消し | | UNLOCK | ロックの解除 | | UNSHARE | 共有リンクの削除 | | UPDATE_COLLABORATION_EXPIRATION | コラボレータの有効期限の延長 | | UPDATE_SHARE_EXPIRATION | 共有リンクの有効期限の延長 | | UPLOAD | アップロード | | USER_AUTHENTICATE_OAUTH2_ACCESS_TOKEN_CREATE | OAuth 2.0アクセストークンの作成 | | WATERMARK_LABEL_CREATE | ファイルへの電子すかしの追加 | | WATERMARK_LABEL_DELETE | ファイルからの電子すかしの削除 | **Source:** [https://ja.developer.box.com/guides/events/enterprise-events/for-enterprise/](https://ja.developer.box.com/guides/events/enterprise-events/for-enterprise/) --- ### FedRAMP **Type:** guide | **Category:** セキュリティ | **Section:** Developer Guides FedRAMP 概要 FedRAMPとは、連邦政府機関が政府または行政機関の安全性/機密性が高まりつつあるデータにクラウドプロバイダを使用できるようにする認証プログラムです。 FedRAMPでは、セキュリティのレベルについて、Low (低)、Moderate (中)、High… # FedRAMP ## 概要 FedRAMPとは、連邦政府機関が政府または行政機関の安全性/機密性が高まりつつあるデータにクラウドプロバイダを使用できるようにする認証プログラムです。 FedRAMPでは、セキュリティのレベルについて、Low (低)、Moderate (中)、High (高) という3つのカテゴリを定義しています。 セキュリティレベルが高いほど、適用される制限が多くなります。 現在、Boxは[FedRAMP High](https://marketplace.fedramp.gov/products/F1212191840A)として認定されています。 ## 留意事項 FedRAMPに準拠するため、管理者は非常に特殊な方法でBoxを設定する必要があり、Boxの機能へのアクセスをさらに制限している可能性があります。 APIの使用に影響する可能性があるセキュリティの制限を特定するには、管理者に相談してください。 ## FedRAMPでのAPIの使用 FedRAMPに準拠するには、APIエントリポイントに以下のURLを使用できます。 | FedRAMP | | --- | | account.box.com | | api.box.com | | upload.box.com | | dl.boxcloud.com | | realtime.services.box.net | **Source:** [https://ja.developer.box.com/guides/security/fedramp/](https://ja.developer.box.com/guides/security/fedramp/) --- ### Google Gemini 1.5 Flash **Type:** guide | **Category:** Box AI | **Section:** Developer Guides Google Gemini 1.5 Flash Google Gemini 1.5 Flash… # Google Gemini 1.5 Flash **Google Gemini 1.5 Flash**は、軽量のタスクを処理するように設計されたマルチモーダルモデルです。これは、大量の低レイテンシタスク向けに設計されており、要約、マルチモーダル処理、分類のような大規模なユースケースに非常に効果的です。 ## モデルの詳細 | 項目 | 値 | 説明 | | --- | --- | --- | | モデル名 | Google Gemini 1.5 Flash | モデルの名前。 | | APIモデル名 | google__gemini_1_5_flash_001 | Box AI APIでのモデルの上書きに使用されるモデルの名前。APIを動作させるには、ユーザーがこの名前を正確に指定する必要があります。 | | ホスティングレイヤー | Google | LLMを安全にホストする、信頼できる組織。 | | モデルプロバイダ | Google | このモデルを提供する組織。 | | リリース日 | 2024年5月14日 | モデルのリリース日。 | | ナレッジカットオフ日 | 2023年11月 | モデルが情報の更新を取得しなくなった日付。 | | 入力コンテキストウィンドウ | 100万トークン | 入力コンテキストウィンドウでサポートされるトークン数。 | | 出力トークンの最大数 | 8,000トークン | 1回のリクエストでモデルが生成できるトークン数。 | | 経験に基づいたスループット | 176 | モデルが1秒あたりに生成できるトークン数。 | | オープンソース | いいえ | モデルのコードを一般公開するかどうかを指定します。 | ## その他のドキュメント 詳細については、[Google Gemini 1.5 Flashの公式ドキュメント](https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models#gemini-models)を参照してください。 **Source:** [https://ja.developer.box.com/guides/box-ai/ai-models/google-gemini-1-5-flash-001-model-card/](https://ja.developer.box.com/guides/box-ai/ai-models/google-gemini-1-5-flash-001-model-card/) --- ### Google Gemini 1.5 Pro 001 **Type:** guide | **Category:** Box AI | **Section:** Developer Guides Google Gemini 1.5 Pro 001 Google Gemini 1.5 Pro 00… # Google Gemini 1.5 Pro 001 **Google Gemini 1.5 Pro 001**は、軽量のタスクを処理するように設計されたマルチモーダルモデルです。長時間の動画や音声、大量のデータセット、複雑な推論タスクなど、広範な入力を処理できる中型のマルチモーダルモデルです。 ## モデルの詳細 | 項目 | 値 | 説明 | | --- | --- | --- | | モデル名 | Google Gemini 1.5 Pro 001 | モデルの名前。 | | APIモデル名 | google__gemini_1_5_pro_001 | Box AI APIでのモデルの上書きに使用されるモデルの名前。APIを動作させるには、ユーザーがこの名前を正確に指定する必要があります。 | | ホスティングレイヤー | Google | LLMを安全にホストする、信頼できる組織。 | | モデルプロバイダ | Google | このモデルを提供する組織。 | | リリース日 | 2024年2月15日 | モデルのリリース日。 | | ナレッジカットオフ日 | 2023年11月 | モデルが情報の更新を取得しなくなった日付。 | | 入力コンテキストウィンドウ | 100万トークン | 入力コンテキストウィンドウでサポートされるトークン数。 | | 出力トークンの最大数 | 8,000トークン | 1回のリクエストでモデルが生成できるトークン数。 | | 経験に基づいたスループット | 45.5 | モデルが1秒あたりに生成できるトークン数。 | | オープンソース | いいえ | モデルのコードを一般公開するかどうかを指定します。 | ## その他のドキュメント 詳細については、[Google Gemini 1.5 Proの公式ドキュメント](https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models#gemini-models)を参照してください。 **Source:** [https://ja.developer.box.com/guides/box-ai/ai-models/google-gemini-1-5-pro-001-model-card/](https://ja.developer.box.com/guides/box-ai/ai-models/google-gemini-1-5-pro-001-model-card/) --- ### Google Gemini 2.0 Flash **Type:** guide | **Category:** Box AI | **Section:** Developer Guides Google Gemini 2.0 Flash Google Gemini 2.0 Flashは、大規模で大量かつ高頻度のタスクに最適になるよう設計されたマルチモーダルモデルです。マルチモーダルの推論が可能であり、10… # Google Gemini 2.0 Flash **Google Gemini 2.0 Flash**は、大規模で大量かつ高頻度のタスクに最適になるよう設計されたマルチモーダルモデルです。マルチモーダルの推論が可能であり、100万トークンのコンテキストウィンドウが備わっています。 ## モデルの詳細 | 項目 | 値 | 説明 | | --- | --- | --- | | モデル名 | Google Gemini 2.0 Flash | モデルの名前。 | | モデル名 | Google Gemini 2.0 Flash | モデルの名前。 | | モデルのカテゴリ | 標準 | モデルのカテゴリ - 標準またはプレミアム。 | | APIモデル名 | google__gemini_2_0_flash_001 | Box AI APIでのモデルの上書きに使用されるモデルの名前。APIを動作させるには、ユーザーがこの名前を正確に指定する必要があります。 | | ホスティングレイヤー | Google | LLMを安全にホストする、信頼できる組織。 | | モデルプロバイダ | Google | このモデルを提供する組織。 | | リリース日 | 2025年2月5日 | モデルのリリース日。 | | ナレッジカットオフ日 | 2024年6月 | モデルが情報の更新を取得しなくなった日付。 | | 入力コンテキストウィンドウ | 100万トークン | 入力コンテキストウィンドウでサポートされるトークン数。 | | 出力トークンの最大数 | 8,000トークン | 1回のリクエストでモデルが生成できるトークン数。 | | 経験に基づいたスループット | 168 | モデルが1秒あたりに生成できるトークン数。 | | オープンソース | いいえ | モデルのコードを一般公開するかどうかを指定します。 | ## その他のドキュメント 詳細については、[Google Gemini 2.0 Flashの公式ドキュメント](https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models#gemini-models)を参照してください。 **Source:** [https://ja.developer.box.com/guides/box-ai/ai-models/google-gemini-2-0-flash-001-model-card/](https://ja.developer.box.com/guides/box-ai/ai-models/google-gemini-2-0-flash-001-model-card/) --- ### Google Gemini 2.0 Flash Lite **Type:** guide | **Category:** Box AI | **Section:** Developer Guides Google Gemini 2.0 Flash Lite Google Gemini 2.0 Flash Lite… # Google Gemini 2.0 Flash Lite **Google Gemini 2.0 Flash Lite**は、軽量のタスクを処理するように設計されたマルチモーダルモデルです。大量の低レイテンシタスク向けに設計されており、要約、マルチモーダル処理、分類のような大規模なユースケースに非常に効果的で、品質はGemini 1.5 Flashよりも高くなります。 ## モデルの詳細 | 項目 | 値 | 説明 | | --- | --- | --- | | モデル名 | Google Gemini 2.0 Flash Lite | モデルの名前。 | | モデルのカテゴリ | 標準 | モデルのカテゴリ - 標準またはプレミアム。 | | APIモデル名 | google__gemini_2_0_flash_lite_preview | Box AI APIでのモデルの上書きに使用されるモデルの名前。APIを動作させるには、ユーザーがこの名前を正確に指定する必要があります。 | | ホスティングレイヤー | Google | LLMを安全にホストする、信頼できる組織。 | | モデルプロバイダ | Google | このモデルを提供する組織。 | | リリース日 | 2025年2月5日 | モデルのリリース日。 | | ナレッジカットオフ日 | 2024年6月 | モデルが情報の更新を取得しなくなった日付。 | | 入力コンテキストウィンドウ | 100万トークン | 入力コンテキストウィンドウでサポートされるトークン数。 | | 出力トークンの最大数 | 8,000トークン | 1回のリクエストでモデルが生成できるトークン数。 | | 経験に基づいたスループット | 168 | モデルが1秒あたりに生成できるトークン数。 | | オープンソース | いいえ | モデルのコードを一般公開するかどうかを指定します。 | ## その他のドキュメント 詳細については、[Gemini 2.0 Flash Liteの公式ドキュメント](https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models#gemini-models)を参照してください。 **Source:** [https://ja.developer.box.com/guides/box-ai/ai-models/google-gemini-2-0-flash-lite-preview-02-05/](https://ja.developer.box.com/guides/box-ai/ai-models/google-gemini-2-0-flash-lite-preview-02-05/) --- ### Google Gemini 2.5 Pro **Type:** guide | **Category:** Box AI | **Section:** Developer Guides Google Gemini 2.5 Pro Google Gemini 2.5 Pro… # Google Gemini 2.5 Pro **Google Gemini 2.5 Pro**は、複雑な問題を解決できるマルチモーダルモデルです。このモデルは、テキスト、音声、画像、動画、さらにはコードリポジトリ全体を含むさまざまな情報源から、膨大なデータセットや困難な問題を理解できます。 ## モデルの詳細 | 項目 | 値 | 説明 | | --- | --- | --- | | モデル名 | Google Gemini 2.5 Pro | モデルの名前。 | | モデルのカテゴリ | プレミアム | モデルのカテゴリ: 標準またはプレミアム。 | | APIモデル名 | google__gemini_2_5_pro | Box AI APIでのモデルの上書きに使用されるモデルの名前。APIを動作させるには、ユーザーがこの名前を正確に指定する必要があります。 | | ホスティングレイヤー | Google | LLMを安全にホストする、信頼できる組織。 | | モデルプロバイダ | Google | このモデルを提供する組織。 | | リリース日 | 2025年6月17日 | モデルのリリース日。 | | ナレッジカットオフ日 | 2025年1月 | モデルが情報の更新を取得しなくなった日付。 | | 入力コンテキストウィンドウ | 100万トークン | 入力コンテキストウィンドウでサポートされるトークン数。 | | 出力トークンの最大数 | 65,000トークン | 1回のリクエストでモデルが生成できるトークン数。 | | 経験に基づいたスループット | 指定なし | モデルが1秒あたりに生成できるトークン数。 | | オープンソース | いいえ | モデルのコードを一般公開するかどうかを指定します。 | ## その他のドキュメント 詳細については、[Google Gemini 2.5 Proの公式ドキュメント](https://cloud.google.com/vertex-ai/generative-ai/docs/models/gemini/2-5-pro)を参照してください。 **Source:** [https://ja.developer.box.com/guides/box-ai/ai-models/google-gemini-2-5-pro-model-card/](https://ja.developer.box.com/guides/box-ai/ai-models/google-gemini-2-5-pro-model-card/) --- ### IBM Llama 3.2 Vision Instruct **Type:** guide | **Category:** Box AI | **Section:** Developer Guides IBM Llama 3.2 Vision Instruct IBM Llama 3.2 Vision Instruct… # IBM Llama 3.2 Vision Instruct **IBM Llama 3.2 Vision Instruct**は、ドキュメントレベルの理解、図表やグラフの解釈、画像の見出し作成など、画像入力とテキスト出力のユースケース向けに構築されたモデルです。 ## モデルの詳細 | 項目 | 値 | 説明 | | --- | --- | --- | | モデル名 | IBM Llama 3.2 Vision Instruct | モデルの名前。 | | モデルのカテゴリ | 標準 | モデルのカテゴリ - 標準またはプレミアム。 | | APIモデル名 | ibm__llama__3_2_90b_vision_instruct | Box AI APIでのモデルの上書きに使用されるモデルの名前。APIを動作させるには、ユーザーがこの名前を正確に指定する必要があります。 | | ホスティングレイヤー | IBM | LLMを安全にホストする、信頼できる組織。 | | モデルプロバイダ | Meta | このモデルを提供する組織。 | | リリース日 | 2024年9月25日 | モデルのリリース日。 | | ナレッジカットオフ日 | 2023年12月 | モデルが情報の更新を取得しなくなった日付。 | | 入力コンテキストウィンドウ | 128,000 | 入力コンテキストウィンドウでサポートされるトークン数。 | | 出力トークンの最大数 | 指定なし | 1回のリクエストでモデルが生成できるトークン数。 | | 経験に基づいたスループット | 指定なし | モデルが1秒あたりに生成できるトークン数。 | | オープンソース | はい | モデルのコードを一般公開するかどうかを指定します。 | | 知的財産侵害からの保護 | いいえ | このモデルの使用には、Boxによる知的財産権の保証または保護は伴いません。このモデルの出力を使用することで発生する可能性もある知的財産の問題を考慮してください。 | ## その他のドキュメント 詳細については、[IBM Llama 3.2 Vision Instructの公式ドキュメント](https://www.ibm.com/docs/en/watsonx/w-and-w/2.1.0?topic=models-third-party-foundation#llama-3-2-vision)を参照してください。 **Source:** [https://ja.developer.box.com/guides/box-ai/ai-models/ibm-llama-3-2-90b-vision-instruct-model-card/](https://ja.developer.box.com/guides/box-ai/ai-models/ibm-llama-3-2-90b-vision-instruct-model-card/) --- ### IBM Llama 4 Scout **Type:** guide | **Category:** Box AI | **Section:** Developer Guides IBM Llama 4 Scout IBM Llama 4 Scoutは、混合専門家 (MoE) アーキテクチャを使用し、ネイティブのマルチモダリティのために早期融合を組み込んだ、自己回帰型言語モデルです。 モデルの詳細 項目 値 説明 モデル名 IBM Llama… # IBM Llama 4 Scout **IBM Llama 4 Scout**は、混合専門家 (MoE) アーキテクチャを使用し、ネイティブのマルチモダリティのために早期融合を組み込んだ、自己回帰型言語モデルです。 ## モデルの詳細 | 項目 | 値 | 説明 | | --- | --- | --- | | モデル名 | IBM Llama 4 Scout | モデルの名前。 | | モデルのカテゴリ | 標準 | モデルのカテゴリ - 標準またはプレミアム。 | | APIモデル名 | ibm__llama_4_scout | Box AI APIでのモデルの上書きに使用されるモデルの名前。APIを動作させるには、ユーザーがこの名前を正確に指定する必要があります。 | | ホスティングレイヤー | IBM | LLMを安全にホストする、信頼できる組織。 | | モデルプロバイダ | Meta | このモデルを提供する組織。 | | リリース日 | 2025年4月5日 | モデルのリリース日。 | | ナレッジカットオフ日 | 2024年8月 | モデルが情報の更新を取得しなくなった日付。 | | 入力コンテキストウィンドウ | 1,000万 | 入力コンテキストウィンドウでサポートされるトークン数。 | | 出力トークンの最大数 | 指定なし | 1回のリクエストでモデルが生成できるトークン数。 | | 経験に基づいたスループット | 指定なし | モデルが1秒あたりに生成できるトークン数。 | | オープンソース | はい | モデルのコードを一般公開するかどうかを指定します。 | | 知的財産侵害からの保護 | いいえ | このモデルの使用には、Boxによる知的財産権の保証または保護は伴いません。このモデルの出力を使用することで発生する可能性もある知的財産の問題を考慮してください。 | ## その他のドキュメント 詳細については、[IBM Llama 4 Scoutの公式ドキュメント](https://www.ibm.com/docs/en/watsonx/w-and-w/2.1.0?topic=models-third-party-foundation)を参照してください。 **Source:** [https://ja.developer.box.com/guides/box-ai/ai-models/ibm-llama-4-scout-model-card/](https://ja.developer.box.com/guides/box-ai/ai-models/ibm-llama-4-scout-model-card/) --- ### IDを指定してAIエージェントを取得 **Type:** guide | **Category:** Box AI Studio | **Section:** Developer Guides IDを指定してAIエージェントを取得 GET /2.0/ai_agents/{id}エンドポイントを使用すると、agent_idパラメータを使用して特定のAIエージェントのリストを取得できます。 リクエストの送信 リクエストを送信するには、GET /2.0/ai_agents… # IDを指定してAIエージェントを取得 `GET /2.0/ai_agents/{id}`エンドポイントを使用すると、`agent_id`パラメータを使用して特定のAIエージェントのリストを取得できます。 ## リクエストの送信 リクエストを送信するには、`GET /2.0/ai_agents/{id}`エンドポイントを使用します。 ### パラメータ コールを実行するには、以下のパラメータを渡す必要があります。必須のパラメータは**太字**で示されています。 | パラメータ | 説明 | 例 | | --- | --- | --- | | agent_id | 取得するエージェントID。 | 1234 | | fields | レスポンスで返されるフィールド。 | ask | **Source:** [https://ja.developer.box.com/guides/ai-studio/ai-studio-agents/get-agent-id/](https://ja.developer.box.com/guides/ai-studio/ai-studio-agents/get-agent-id/) --- ### iOS **Type:** guide | **Category:** モバイル | **Section:** Developer Guides iOS Box iOS SDKは、iOSプロジェクト内からBox APIへのネイティブアクセスを提供します。 # iOS [Box iOS SDK](https://github.com/box/box-ios-sdk)は、iOSプロジェクト内からBox APIへのネイティブアクセスを提供します。 **Source:** [https://ja.developer.box.com/guides/mobile/ios/](https://ja.developer.box.com/guides/mobile/ios/) --- ### iOS SDKのインストール **Type:** quick-start | **Category:** モバイル | **Section:** Developer Guides iOS SDKのインストール iOSアプリケーションを設定したら、使用可能なパッケージマネージャオプションのいずれかを使用して、必要なBox iOS SDK依存関係をプロジェクトにインポートする必要があります。 使用するパッケージマネージャの選択 Carthage… # iOS SDKのインストール iOSアプリケーションを設定したら、使用可能なパッケージマネージャオプションのいずれかを使用して、必要な**Box iOS SDK**依存関係をプロジェクトにインポートする必要があります。 ## 使用するパッケージマネージャの選択 # Carthage Carthageは、SwiftプロジェクトおよびObjective-C Cocoaプロジェクト向けの分散型の依存関係マネージャです。これは、オープンソースで、Swiftで構築されています。 # CocoaPods CocoaPodsは、SwiftプロジェクトおよびObjective-C Cocoaプロジェクト向けの集中型の依存関係マネージャです。これは、オープンソースで、Rubyで構築されています。 # Swift Package Manager Swift Package Managerは、ソースコードの配布を管理するためのツールで、自作のコードの共有や他の人のコードの再利用を容易にします。 # Carthageを使用してiOS SDKをインストールする 1. ターミナルウィンドウから`brew install carthage`を実行して、Carthageをインストールします。他のインストール方法については、[Carthageのドキュメント](https://github.com/Carthage/Carthage#installing-carthage)を参照してください。 2. `{APPNAME}.xcodeproj`がある、iOSアプリケーションフォルダのルートに、`Cartfile`という名前の新しいファイルを拡張子なしで作成します。 3. `Cartfile`を開き、`git "https://github.com/box/box-ios-sdk.git" ~> 3.0`を使用して**Box iOS SDK**の依存関係を追加した後、ファイルを保存して閉じます。 4. ターミナルから、`Cartfile`が存在するフォルダで、`carthage update --platform iOS`を実行してすべての依存関係を更新します。このディレクトリに`Cartfile.resolved`ファイルと`Carthage`ディレクトリが作成されます。 5. Finderまたはエクスプローラウィンドウで、**Carthage** -> **Build** -> **iOS**ディレクトリを読み込みます。ここには、`BoxSDK.framework`という名前のフレームワークファイルがあります。このウィンドウは、次の手順でこのフレームワークをプロジェクトに追加する際に使用するため、開いたままにしておきます。 6. Xcodeプロジェクトで、左側のプロジェクトナビゲータの上部にあるアプリケーションの名前をクリックします。表示されるコンテンツで、[**TARGETS (ターゲット)**] オプションの下にあるプロジェクトの名前をクリックします。[**Frameworks, Libraries, and Embedded Content (フレームワーク、ライブラリ、埋め込みコンテンツ)**] まで下にスクロールします。 7. Finderウィンドウから`BoxSDK.framework`をフレームワークセクション上にドラッグします。 # CocoaPodsを使用してiOS SDKをインストールする 1. ターミナルウィンドウから`sudo gem install cocoapods`を実行して、CocoaPodsをインストールします。 2. `APPNAME.xcodeproj`がある、iOSアプリケーションフォルダのルートで、`pod init`を実行して、スマートデフォルトで新しい`Podfile`を作成します。 3. `Podfile`を読み込み、`pod 'BoxSDK', '~> 3.0'`を実行して`# Pods for {APPNAME}`の下に**Box iOS SDK**の依存関係を追加した後、保存して閉じます。 4. ターミナルから、`Podfile`が存在するフォルダで、`pod install`を実行してすべての依存関係をダウンロードします。 5. `open {APPNAME}.xcworkspace`を実行して`.xcworkspace`をXcodeで開き、プロジェクトをビルドします。 # Swift Package Managerを使用してiOS SDKをインストールする 1. Xcodeプロジェクトで、左側のプロジェクトナビゲータの上部にあるアプリケーションの名前をクリックします。表示されるコンテンツで、[**PROJECT (プロジェクト)**] オプションの下にあるプロジェクトの名前をクリックします。 2. [**Swift Packages (Swiftパッケージ)**] をクリックし、`+`をクリックしてパッケージを追加します。 3. リポジトリのURL `https://github.com/box/box-ios-sdk.git`を入力し、[Next (次へ)] をクリックします。 4. デフォルト設定のままにし、[Next (次へ)] をクリックしてインポートを終了します。 ## まとめ Carthageを使用したiOS依存関係のインストールを選択しました。 - Carthageをインストールしました。 - Box iOS SDKの依存関係を持つ`Cartfile`を作成しました。 - iOS SDKの依存関係をインストールしました。 - 構築した依存関係をXcodeプロジェクトのフレームワークリストに手動でインポートしました。 **CocoaPods**の使用を選択しました。 - CocoaPodsをインストールしました。 - Box iOS SDKの依存関係を持つ新しい`Podfile`を作成しました。 - iOS SDKの依存関係をインストールしました。 - Xcodeでプロジェクトをビルドしました。 **Swift Package Manager**の使用を選択しました。 - SwiftパッケージにiOS SDKの`.git`リポジトリをインポートしました。 Box iOS SDKの依存関係をインストールしました **Source:** [https://ja.developer.box.com/guides/mobile/ios/quick-start/install-ios-sdk/](https://ja.developer.box.com/guides/mobile/ios/quick-start/install-ios-sdk/) --- ### iOS SDKの使い方 **Type:** quick-start | **Category:** モバイル | **Section:** Developer Guides iOS SDKの使い方 Box iOS SDKは、iOSプロジェクトにBox APIを追加するためのSwift言語ラッパーです。 要件 Box iOS SDKとこのクイックスタートの使用を開始するには、以下のものが必要です。 iOS 11.0以降/Mac OS X 10.1… # iOS SDKの使い方 Box iOS SDKは、iOSプロジェクトにBox APIを追加するための[Swift言語](https://developer.apple.com/swift/)ラッパーです。 ## 要件 Box iOS SDKとこのクイックスタートの使用を開始するには、以下のものが必要です。 - iOS 11.0以降/Mac OS X 10.13以降 - Xcode 10.0以降 ## 概要 このガイドでは、以下の手順を説明します。 1. Xcodeで[新しいiOSアプリを作成](g://mobile/ios/quick-start/create-ios-app)します。 2. プロジェクトに[iOS SDKをインストール](g://mobile/ios/quick-start/install-ios-sdk)します。 3. iOS SDKからBox APIにアクセスできるように[Boxアプリを設定](g://mobile/ios/quick-start/configure-box-app)します。 4. iOS SDKを使用してBox APIに対する[APIコールを実行](g://mobile/ios/quick-start/make-api-call)します。 開始する準備ができました **Source:** [https://ja.developer.box.com/guides/mobile/ios/quick-start/](https://ja.developer.box.com/guides/mobile/ios/quick-start/) --- ### iOSアプリの作成 **Type:** quick-start | **Category:** モバイル | **Section:** Developer Guides iOSアプリの作成 Box iOS SDKをインストールする前に、依存関係を追加できるiOSアプリケーションを用意しておく必要があります。ここでは、新しい空のアプリケーションを作成します。 iOSアプリのセットアップ このクイックスタートガイドでは、iOS… # iOSアプリの作成 Box iOS SDKをインストールする前に、依存関係を追加できるiOSアプリケーションを用意しておく必要があります。ここでは、新しい空のアプリケーションを作成します。 ## iOSアプリのセットアップ このクイックスタートガイドでは、iOSアプリケーションの作成と編集にXcodeというツールを使用します。Xcodeをお持ちでない場合は、[Appleの開発者向けサイト](https://developer.apple.com/xcode/)からダウンロードしてください。 今回Xcodeでのアプリケーションの作成が初めてである場合も、すでにアプリケーション開発の経験がある場合も、Box iOS SDKと新しい空のアプリケーションの統合から開始します。 1. Xcodeを起動します。 2. 上部のメニューから、[**File (ファイル)**] -> [**New (新規)**] -> [**Project... (プロジェクト...)**] を選択します。 [**Single View App (単一ビューアプリ)**] のオプションを選択します。 `Product Name`、`Organization Identifier`、`Organization Name`など、アプリケーションの設定情報を入力します。 1. アプリケーション用のローカルの保存場所を選択し、[**Create (作成)**] をクリックします。 ## まとめ - Xcodeで新しい空のiOSアプリケーションを作成しました。 空のiOSアプリケーションを作成しました **Source:** [https://ja.developer.box.com/guides/mobile/ios/quick-start/create-ios-app/](https://ja.developer.box.com/guides/mobile/ios/quick-start/create-ios-app/) --- ### Java SDKのインストール **Type:** guide | **Category:** ツール | **Section:** Developer Guides Java SDKのインストール Javaプロジェクトでは、Box Java SDKを使用してBox APIを呼び出すことができます。 Java SDKをインストールするには、Gradle依存関係またはMaven… # Java SDKのインストール Javaプロジェクトでは、Box Java SDKを使用してBox APIを呼び出すことができます。 Java SDKをインストールするには、Gradle依存関係またはMaven依存関係を追加するか、ソースをプロジェクトに複製します。また、GitHubのリリースページからプリコンパイル済みJARのいずれかをダウンロードすることもできます。 GitHubでJava SDKの詳細を確認する ## Gradle `build.gradle`ファイルに以下の依存関係を追加します。 ``` compile 'com.box:box-java-sdk:2.32.0' ``` Java SDKの最新のバージョン番号については、[Java SDKのオープンソースに関するページ](http://opensource.box.com/box-java-sdk/)を参照してください。 ## Maven 以下のMaven依存関係を追加します。 ``` <dependency> <groupId>com.box</groupId> <artifactId>box-java-sdk</artifactId> <version>2.32.0</version> </dependency> ``` Java SDKの最新のバージョン番号については、[Java SDKのオープンソースに関するページ](http://opensource.box.com/box-java-sdk/)を参照してください。 ## ソースからのインストール [Java SDK GitHubリポジトリ](https://github.com/box/box-java-sdk/tree/master/src/main/java/com/box/sdk)からSDKソースをダウンロードしてプロジェクトに追加します。 ## プリコンパイル済みJAR GitHubの[リリースに関するページ](https://github.com/box/box-java-sdk/releases)からJava SDK用のプリコンパイル済みJARをダウンロードします。 プリコンパイル済みJARを使用する際は、以下の依存関係をプロジェクトに追加することが重要です。 | 依存関係 | | --- | | minimal-json v0.9.1 | | jose4j v0.4.4 | | bouncycastle bcprov-jdk15on v1.52 | | bouncycastle bcpkix-jdk15on v1.52 | | Java Cryptography Extension (JCE) | **Source:** [https://ja.developer.box.com/guides/tooling/sdks/java/](https://ja.developer.box.com/guides/tooling/sdks/java/) --- ### JWTを使用した設定 **Type:** guide | **Category:** 認証 | **Section:** Developer Guides JWTを使用した設定 Platformアプリは、JWTによるサーバー側認証を使用するよう設定できます。 JWT認証のしくみを確認する 前提条件 サーバー側認証を使用してPlatformアプリを設定するには、Box Enterprise… # JWTを使用した設定 Platformアプリは、[JWT](g://authentication/jwt)によるサーバー側認証を使用するよう設定できます。 JWT認証のしくみを確認する ## 前提条件 サーバー側認証を使用してPlatformアプリを設定するには、Box Enterpriseアカウントから[開発者コンソール](https://app.box.com/developers/console)にアクセスできることを確認する必要があります。または、[Developerアカウント](https://account.box.com/signup/n/developer)にサインアップすることもできます。 ## アプリの作成手順 ### 開発者コンソールへの移動 Boxにログインし、[開発者コンソール](https://app.box.com/developers/console)に移動して、[**Platformアプリの作成**] を選択します。 ### アプリケーションの種類の選択 アプリケーションの種類のリストから [**Platformアプリ**] を選択します。次の手順を促すウィンドウが表示されます。 ### アプリケーションの基本情報の指定 アプリを説明するために、アプリの名前と説明を指定します。アプリの目的を選択するには、ドロップダウンリストを使用します。選択したオプションに応じて、さらに詳細を指定することが必要になる場合があります。 | 目的 | 詳細 | | --- | --- | | [自動化]、[カスタムポータル] | アプリの作成者 (お客様またはパートナー) を指定します。 | | 統合 | 統合のカテゴリ、外部システム名のほか、アプリの作成者 (お客様またはパートナー) を指定します。 | | [その他] | アプリの目的と、アプリの作成者 (お客様またはパートナー) を指定します。 | ### アプリケーションの認証の選択 [キーペアを使用して](g://authentication/jwt/without-sdk/#public-and-private-key-pair)アプリケーションIDを確認する場合は [**サーバー認証 (JWT使用)**] を選択し、[**Platformアプリの作成**] で確定します。 選択すると、新しいアプリケーションを作成しない限り、別の認証方法に変更できません。 ## 公開キーと秘密キーのペア このセクションは、認証方法として [サーバー認証 (クライアント資格情報許可)] を選択した場合はスキップできます。 [サーバー認証 (JWT使用)] を利用してPlatformアプリを作成すると、[開発者コンソール](https://app.box.com/developers/console)の [構成] タブでキーペアを生成できます。また、独自のキーペアを生成して、その公開キーをBoxに提供することもできます。選択する方法に関係なく、セキュリティの目的で、Boxアカウントでは[2要素認証](https://support.box.com/hc/ja/articles/360043697154-%E3%82%A2%E3%82%AB%E3%82%A6%E3%83%B3%E3%83%88%E3%81%AE%E5%A4%9A%E8%A6%81%E7%B4%A0%E8%AA%8D%E8%A8%BC%E3%81%AE%E8%A8%AD%E5%AE%9A)を有効にしておく必要があります。 ### キーペアの生成 (推奨) Boxで生成されたキーペアを使用する場合は、[開発者コンソール](https://app.box.com/developers/console)に移動し、そこで構成ファイルを生成できます。このファイルには、公開/秘密キーペアのほか、認証に必要なその他さまざまなアプリケーションの詳細が含まれています。 このファイルを生成するには、[開発者コンソール](https://app.box.com/developers/console)の [**構成**] タブに移動し、[**公開キーの追加と管理**] セクションまで下にスクロールします。 [ **公開/秘密キーペアを生成**] ボタンをクリックすると、Boxによってキーペアが生成されます。これにより、アプリケーションコードに移すことができるJSON構成ファイルのダウンロードが開始されます。 セキュリティ上の理由により、Boxには秘密キーが保存されません。秘密キーを紛失した場合は、キーペア全体のリセットが必要になります。 ### 手動によるキーペアの追加 代わりに、独自のキーペアを生成し、その公開キーを[開発者コンソール](https://app.box.com/developers/console)にアップロードすることもできます。 OpenSSLを使用してキーペアを作成するには、ターミナルウィンドウを開き、以下のコマンドを実行します。 ``` openssl genrsa -des3 -out private.pem 2048 openssl rsa -in private.pem -outform PEM -pubout -out public.pem ``` # Windowsシステムの場合 Windowsユーザーは、[Cygwin](http://www.cygwin.com/)パッケージをインストールして使用することで、OpenSSLを実行できます。 その後、[開発者コンソール](https://app.box.com/developers/console)でアプリケーションの [構成] タブに移動し、[**公開キーの追加と管理**] セクションまで下にスクロールします。 [**公開キーを追加**] ボタンをクリックし、上記の手順で生成された公開キーを入力して、[**確認して保存**] をクリックします。 ## アプリ承認 アプリケーションを使用するには、Box管理者がBox管理コンソールでそのアプリケーションを承認しておく必要があります。 [開発者コンソール](https://app.box.com/developers/console)で、目的のアプリケーションの [**承認**] タブに移動します。 [**確認して送信**] をクリックして、承認を得るためにBox Enterprise管理者にメールを送信します。このプロセスの詳細については、[アプリの承認に関するサポート記事](https://support.box.com/hc/ja/articles/360043697014-Box%E3%81%AE%E3%82%A2%E3%83%97%E3%83%AA%E6%89%BF%E8%AA%8D%E3%83%97%E3%83%AD%E3%82%BB%E3%82%B9%E3%81%A7%E3%81%AE%E3%82%A2%E3%83%97%E3%83%AA%E3%81%AE%E6%89%BF%E8%AA%8D)を参照してください。 Platformアプリケーションの承認方法を確認する ## 基本的な構成 ### アプリケーションアクセス アプリケーションのアクセスレベルにより、アプリからアクセスできるユーザーおよびコンテンツが決まります。デフォルトでは、アプリケーションで問題なく操作できるのは、その[サービスアカウント](page://platform/user-types/#service-account)とすべての[App User](page://platform/user-types)のコンテンツのみです。企業の既存の管理対象ユーザーや、アプリ自体が作成していないグループにアクセスするには、[開発者コンソール](https://app.box.com/developers/console)の [**構成**] タブにある [**アプリアクセスレベル**] に移動し、[**アプリ + Enterpriseアクセス**] に設定します。そうしないと、このような管理対象ユーザーとグループへのアクセスはブロックされます。 ### アプリケーションスコープ アプリケーションのスコープにより、アプリケーションが呼び出すことができるエンドポイントとリソースが決まります。各オプションの詳細については、[スコープのガイド](g://api-calls/permissions-and-errors/scopes)を参照してください。 ### CORSドメイン アプリケーションがJavaScriptでフロントエンドのブラウザコードからAPIコールを実行する場合は、[クロスオリジンリソース共有](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing) (CORS) のために、これらの呼び出しの実行元となるドメインを許可リストに追加する必要があります。すべてのリクエストがサーバー側のコードから発行される場合は、このセクションをスキップできます。 許可リストに完全なURIを追加するには、[開発者コンソール](https://app.box.com/developers/console)の [**構成**] タブの下部にある [**CORSドメイン**] セクションに移動します。 **Source:** [https://ja.developer.box.com/guides/authentication/jwt/jwt-setup/](https://ja.developer.box.com/guides/authentication/jwt/jwt-setup/) --- ### JWT認証 **Type:** guide | **Category:** 認証 | **Section:** Developer Guides JWT認証 JSONウェブトークン (JWT) を使用するサーバー側の認証は、Box APIで認証するための最も一般的な方法です。JWTは、効果的にサーバー間認証を実現するよう設計されたオープンスタンダードです。 JWTを使用するサーバー側認証は、アプリの種類がPlatform… # JWT認証 JSONウェブトークン (JWT) を使用するサーバー側の認証は、Box APIで認証するための最も一般的な方法です。JWTは、効果的にサーバー間認証を実現するよう設計された[オープンスタンダード](https://jwt.io/)です。 JWTを使用するサーバー側認証は、[アプリの種類](g://applications/app-types/select)がPlatformアプリケーションの場合のみ使用できます。この認証方法ではエンドユーザーによる操作が必要ありません。また、適切な権限が付与されていれば、この認証方法を使用して、社内の任意のユーザーの代理で操作することができます。 アプリケーションの権限を確認する方法は2つあります。 - 公開キーと秘密キーのペアを使用する - クライアントIDとクライアントシークレット ([クライアント資格情報許可](g://authentication/client-credentials)) を使用する これらのオプションの詳細については、[SDKを使用しないJWT](g://authentication/jwt/without-sdk)の使用に関するガイドを参照してください。 Box管理コンソールでJWTアプリケーションを承認すると、[サービスアカウント](page://platform/user-types/#service-account)が自動的に生成され、認証時に使用されるデフォルトのアクセストークンになります。これは、管理者に似たユーザーであり、JWTを利用するアプリケーションを使用する前にBox管理者による明示的な承認が必要となる理由です。 ## JWTを使用する場合 JWTを使用するサーバー側認証は、以下に当てはまるアプリに最適な認証方法です。 - Boxアカウントを持たないユーザーを使用する - 独自のIDシステムを使用する - ユーザーにBoxを使用していることを認識させたくない - アプリケーションのBoxアカウントにデータを保存し、ユーザーのBoxアカウントには保存しない **Source:** [https://ja.developer.box.com/guides/authentication/jwt/](https://ja.developer.box.com/guides/authentication/jwt/) --- ### JWT認証を使用したBox CLI **Type:** guide | **Category:** CLI | **Section:** Developer Guides JWT認証を使用したBox CLI これまで、Box CLIのクイックスタートガイドでは、JWTアプリケーションまたはサーバー認証アプリケーションの設定フローについて説明してきましたが、新しくOAuth 2.0バージョンのBox CLI… # JWT認証を使用したBox CLI これまで、[Box CLIのクイックスタートガイド](g://cli/quick-start)では、JWTアプリケーションまたはサーバー認証アプリケーションの設定フローについて説明してきましたが、新しくOAuth 2.0バージョンのBox CLIをリリースしたため、新機能の使用についてガイドを更新しました。当初のJWTの設定手順については、引き続きサーバー認証アプリケーションを使用したい方のために、こちらに移動しました。 ## JWTアプリケーションの設定 サーバー認証を使用したCLIを使用するには、まず、[開発者コンソール](https://account.box.com/developers/console)でBoxアプリケーションを作成します。CLIはAPIコールを実行する際にバックグラウンドでこのアプリケーションを使用できます。CLIを既存のJWTアプリケーションに関連付ける場合は、この手順を省略できます。ただし、少なくとも、以下のスコープがアプリケーションの [**構成**] タブで設定されていることを確認してください。 - Boxに格納されているすべてのファイルとフォルダの読み取り - Boxに格納されているすべてのファイルとフォルダへの書き込み [すべてのファイル] ページの左側にあるナビゲーションパネルから、[開発者コンソール](https://account.box.com/developers/console)を開きます。今回Box APIを使用するのが初めてで、このオプションがまだ使用できない場合は、[こちら](https://account.box.com/developers/console)をクリックするとこのオプションをアカウントに追加できます。 [**Platformアプリの作成**] > [**Platformアプリ**] > [**サーバー認証 (JWT使用)**] の順にクリックし、アプリケーションに名前を付けて、[**アプリの作成**] をクリックします。 サーバー認証 (JWT使用) は、使用する前に必ず管理者の承認が必要になります。 ## アプリケーションの構成 これにより、アプリケーションの設定ページが表示され、そこで、そのアクセスや権限を選択する必要があります。アプリケーションの認証タイプが原因で、管理者の承認が必要になることにもう一度注意してください。 少なくとも、以下の[スコープ](g://api-calls/permissions-and-errors/scopes)が必要です。 - Boxに格納されているすべてのファイルとフォルダの読み取り - Boxに格納されているすべてのファイルとフォルダへの書き込み [アプリケーションアクセス](g://authentication/jwt/jwt-setup/#application-access)として、[アプリアクセスのみ] または [アプリ + Enterpriseアクセス] のいずれかを選択できます。 ## アプリケーションの承認 APIコールを正常に実行する前に、サーバー認証を利用するすべてのアプリケーションを管理コンソールで承認する必要があります。これは、すべてのJWTアプリケーションには[サービスアカウント](page://platform/user-types/#service-account)があるためです。サービスアカウントは、アプリケーションの[スコープ](g://api-calls/permissions-and-errors/scopes)に基づいて管理者アクションを実行できます。 開発者と管理者向けの手順については、Boxの[承認ガイド](g://authorization/custom-app-approval)を参照してください。 スコープ、アプリケーションアクセス、トークン、権限がどのように連携しているかの詳細については、[Boxのセキュリティメカニズム](https://medium.com/box-developer-japan-blog/box-api-understanding-security-ja-b95725d8aaf0)に関する記事を参照してください。 設定の変更がこのアプリケーションに対して行われた場合は、その変更を有効にするためにこのアプリケーションを再承認する必要があります。 アプリケーションが使用できる状態になっているかどうかを確認するには、[開発者コンソール](https://account.box.com/developers/console)の [承認] タブを表示します。状態とステータスはそれぞれ、[有効] と [承認済み] になっているはずです。 ## 必要なデータのダウンロード CLIでは、APIコールを実行するために、ローカルに保存されている構成ファイルが必要です。 構成ファイルをダウンロードするには、[開発者コンソール](https://account.box.com/developers/console)の [**構成**] タブにアクセスし、[**公開/秘密キーペアを生成**] をクリックします。これにより、アプリケーションの構成ファイルを自動的にダウンロードする前に2要素認証が行われます。詳細については、Boxの[ガイド](g://authentication/jwt/jwt-setup/#public-and-private-key-pair)を参照してください。 セキュリティ上の理由により、公開/秘密キーペアを生成するには、Boxアカウントで2要素認証を有効にする必要があります。 `EnterpriseID_publicKeyID_config.json`という形式のデフォルトの名前が付いているダウンロード済みファイルをコンピュータ上で探します。この名前をそのまま使用しても、変更してもかまいません。このガイドでは、ファイルの名前を`config.json`に変更することを想定しています。 誤って削除または移動されることがない場所にファイルを配置することが重要です。ファイルが削除または移動された場合は、手順2を繰り返してCLIを再構成する必要があります。 ## CLIのインストールと構成 Windows用およびmacOS用のインストーラが提供されていますが、その他の環境でCLIを構築する場合はRawソースコードを利用できます。 ## Windows用およびmacOS用インストーラ お使いのマシンに最新のCLIをインストールするには、最新リリースに対応する最新の`.exe` (Windowsの場合) または`.pkg` (macOSの場合) をダウンロードします。 最新のCLIインストーラをダウンロード ## LinuxとNodeのインストール さらに、CLIは、任意のプラットフォーム (Linuxなど) にNodeパッケージとしてインストールすることができます。このためには、[Node JS](https://nodejs.org/)をマシンにインストールしておく必要があります。 ``` npm install --global @box/cli ``` ## ソースコード CLIのソースコードは、[GitHub](https://github.com/box/boxcli)で提供されています。 ## 構成コマンドの実行 ここで、手順1でダウンロードした構成ファイルを指すよう、CLIを構成する必要があります。 ターミナルまたはコマンドラインを開き、`box configure:environments:add PathToConfigFileHere`コマンドを実行します。ここでは、`PathToConfigHere`を`config.json`ファイルのパスに置き換えます。 例: `box configure:environments:add /Users/ExampleUser/Documents/CLI/config.json` Finder/エクスプローラからターミナル/コマンドラインウィンドウにcsvファイルをドラッグすると、パスを自動で入力できます。 ## 構成の確認 うまく構成されているか確認するには、コマンド`box users:get`を使用します。 次のように、成功を示すレスポンスには、[アクセストークン](g://authentication/tokens)に関連付けられた[サービスアカウント](page://platform/user-types/#service-account)ユーザーの詳細が示されます。 ``` Type: user ID: ''0123456789'' Name: Box CLI - Quickstart Example Login: AutomationUser_123456_8jSo6Lqvko@boxdevedition.com Created At: '2020-01-01T09:45:01-07:00' Modified At: '2021-03-01T09:30:05-07:00' Language: en Timezone: America/Los_Angeles Space Amount: 999999999999999 Space Used: 6291500 Max Upload Size: 16106127360 Status: active Job Title: '' Phone: '' Address: example+user@box.com Avatar URL: '' Notification Email: [] ``` デフォルトでは、JWTアプリケーションはサービスアカウントのアクセストークンを自動的に取得します。デフォルトユーザーの変更は可能ですが、このガイドでは変更しないことを想定しています。 ## 次の手順 - コード例をGitHubの[コマンド](https://github.com/box/boxcli#command-topics)ページで確認できます。 - [OAuth 2.0のクイックスタート](g://cli/quick-start/build-commands-help)の2番目の手順に進み、コマンドの使用方法のチュートリアルを確認することもできます。 **Source:** [https://ja.developer.box.com/guides/cli/cli-docs/jwt-cli/](https://ja.developer.box.com/guides/cli/cli-docs/jwt-cli/) --- ### Long pollingイベント **Type:** guide | **Category:** イベント | **Section:** Developer Guides Long pollingイベント Boxアカウントでアクティビティのリアルタイム通知を取得するために、OPTIONS /events APIのLong polling機能を使用できます。 Long pollingはUser Eventにのみ使用できます。Enterprise… # Long pollingイベント Boxアカウントでアクティビティのリアルタイム通知を取得するために、[`OPTIONS /events`](e://options_events) APIのLong polling機能を使用できます。 Long pollingはUser Eventにのみ使用できます。Enterprise EventではLong pollingがサポートされません。 ## Long polling Long pollingでは、HTTPリクエストを開き、サーバーがレスポンスを送信するまでそのリクエストを開いたままにして、そのプロセスを何度も繰り返して更新されたレスポンスを受信します。 SDKには、新しいイベントに対するLong pollingにより、イベントフィードをイベントストリームに変換するためのサポートが組み込まれています。 ### Long polling URL Long pollingを使用するには、まず、リクエストを[`OPTIONS /events`](e://options_events) APIに送信し、Long polling URLを取得します。 ``` curl -X OPTIONS https://api.box.com/2.0/events \ -H "authorization: Bearer ACCESS_TOKEN" ``` ``` { "chunk_size": 1, "entries": [ { "type": "realtime_server", "url": "http://2.realtime.services.box.net/subscribe?channel=cc807c9c4869ffb1c81a&stream_type=all", "ttl": 10, "max_retries": 10, "retry_timeout": 610 } ] } ``` ### リアルタイムサーバー 次に、指定されたURLに`GET`リクエストを実行してイベントのリッスンを開始します。監視対象のアカウントでイベントが発生すると、`new_change`という値を持つレスポンスが送信されます。レスポンスにはその他の詳細は含まれていません。 この単一のレスポンスは、最新の既知の`stream_position`を使用して`GET /events`エンドポイントにリクエストを送信するなど、後続の処理を促すことを目的としています。 ### 切断と再接続 サーバーは、このレスポンスを送信した後に接続を閉じます。この時点でアプリケーションがイベントのリッスンを再開するには、Long pollingのプロセスを繰り返す必要があります。 アプリケーションがリアルタイムサーバーに接続してもその後しばらくイベントが発生しないと、接続が閉じられ、`reconnect`という値が返されます。この状況になると、アプリケーションはプロセスを再開するために`OPTIONS /events`に対する新しい呼び出しを実行する必要があります。 ### タイムアウトと再試行 `retry_timeout`で指定した秒数以内にアプリケーションがイベントを受け取らなければ、アプリケーションはリアルタイムサーバーに再接続できます。これは、ネットワークエラーが発生すると必要になる場合があります。 アプリケーションがリアルタイムサーバーに対して`GET`リクエストを送信したときに`max_retries`エラーが返された場合は、`/events` APIに対して`OPTIONS`呼び出しを実行してプロセスを再開する必要があります。 **Source:** [https://ja.developer.box.com/guides/events/user-events/polling/](https://ja.developer.box.com/guides/events/user-events/polling/) --- ### Node SDK (公式サポート終了) のインストール **Type:** guide | **Category:** ツール | **Section:** Developer Guides Node SDK (公式サポート終了) のインストール Nodeプロジェクトでは、Box Node SDKを使用してBox APIを呼び出すことができます。 Node SDK… # Node SDK (公式サポート終了) のインストール Nodeプロジェクトでは、Box Node SDKを使用してBox APIを呼び出すことができます。 [Node SDK](https://github.com/box/box-node-sdk)は、現在メンテナンスモードであり、まもなく公式サポートが終了する予定です。つまり、実装されるのは重要なセキュリティ更新プログラムとバグ修正のみになります。[自動生成されたTypeScript SDK](g://tooling/sdks/typescript-gen)を使用することをお勧めします。 GitHubでNode SDKの詳細を確認する ## NPMのインストール Node SDKをインストールするには、[Nodeパッケージマネージャ](https://www.npmjs.com/)を使用してターミナルウィンドウまたはコマンドプロンプトから以下のコマンドを実行します。 ``` npm install box-node-sdk --save ``` ## Yarnインストール 同様に、[Yarnパッケージ](https://yarnpkg.com/)マネージャを使用してSDKをインストールすることもできます。 ``` yarn add box-node-sdk ``` **Source:** [https://ja.developer.box.com/guides/tooling/sdks/node/](https://ja.developer.box.com/guides/tooling/sdks/node/) --- ### OAuth 2.0を使用したBox CLIの使用 **Type:** quick-start | **Category:** CLI | **Section:** Developer Guides OAuth 2.0を使用したBox CLIの使用 Box CLIは、使い勝手の良いコマンドラインツールです。これにより、開発者でも開発者以外のユーザーでもBox API… # OAuth 2.0を使用したBox CLIの使用 Box CLIは、使い勝手の良いコマンドラインツールです。これにより、開発者でも開発者以外のユーザーでもBox APIを利用してルーチンや一括操作を実行できるようになります。コードを書く必要はありません。これらの操作は、一連の[コマンド](https://github.com/box/boxcli#command-topics)によって実行されます。 ## 概要 このガイドでは、以下の手順を説明します。 1. Boxアプリケーションを[作成して設定する](g://cli/quick-start/create-oauth-app) 2. CLIを[インストールして構成する](g://cli/quick-start/install-and-configure) 3. CLIを使用して[コマンドを実行する](g://cli/quick-start/build-commands-help) 4. [オプションや一括コマンド](g://cli/quick-start/options-and-bulk-commands)を使用する 5. [CLIでのPowerShellスクリプト](g://cli/quick-start/powershell-script-templates)の使用方法を確認する 6. [次の手順](g://cli/quick-start/next-steps) 開始する準備ができました **Source:** [https://ja.developer.box.com/guides/cli/quick-start/](https://ja.developer.box.com/guides/cli/quick-start/) --- ### OAuth 2.0を使用した設定 **Type:** guide | **Category:** 認証 | **Section:** Developer Guides OAuth 2.0を使用した設定 Platformアプリは、クライアント側のOAuth 2.0認証を使用するよう設定できます。 OAuth 2.0認証のしくみを確認する 前提条件 OAuth 2.0認証を使用してPlatformアプリを設定するには、Box Enterprise… # OAuth 2.0を使用した設定 Platformアプリは、クライアント側の[OAuth 2.0](g://authentication/oauth2)認証を使用するよう設定できます。 OAuth 2.0認証のしくみを確認する ## 前提条件 OAuth 2.0認証を使用してPlatformアプリを設定するには、Box Enterpriseアカウントから[開発者コンソール](https://app.box.com/developers/console)にアクセスできることを確認する必要があります。または、[Developerアカウント](https://account.box.com/signup/n/developer)にサインアップすることもできます。 ## アプリの作成手順 ### 開発者コンソールへの移動 Boxにログインし、[開発者コンソール](https://app.box.com/developers/console)に移動して、[**Platformアプリの作成**] を選択します。 ### アプリケーションの種類の選択 アプリケーションの種類のリストから [**Platformアプリ**] を選択します。次の手順を促すウィンドウが表示されます。 ### アプリケーションの基本情報の指定 アプリを説明するために、アプリの名前と説明を指定します。アプリの目的を選択するには、ドロップダウンリストを使用します。選択したオプションに応じて、さらに詳細を指定することが必要になる場合があります。 | 目的 | 詳細 | | --- | --- | | [自動化]、[カスタムポータル] | アプリの作成者 (お客様またはパートナー) を指定します。 | | 統合 | 統合のカテゴリ、外部システム名のほか、アプリの作成者 (お客様またはパートナー) を指定します。 | | [その他] | アプリの目的と、アプリの作成者 (お客様またはパートナー) を指定します。 | ### アプリケーションの認証の選択 [**ユーザー認証 (OAuth 2.0)**] を選択し、[**アプリの作成**] で確定します。 選択すると、新しいアプリケーションを作成しない限り、別の認証方法に変更できません。 ## 基本的な構成 アプリケーションを使用するには、事前にいくつかの追加構成が必要になります。 ### リダイレクトURI OAuth 2.0フローの間、ユーザーは、認証のためにブラウザにリダイレクトされた後、アプリケーションが自分の代わりにアクションを実行することを承認します。 Boxでは、ユーザーをリダイレクトする前に、[承認URL](e://get-authorize/#param-redirect_uri)に渡された`redirect_uri`パラメータが、アプリケーションに構成されたリダイレクトURIのいずれかと一致することを確認します。完全に一致しているかどうかがチェックされるため、URIはまったく同じである必要があります。localhostおよびループバックアドレスのリダイレクトURIは、どのポートへのリダイレクトも許可されますが、スキーム、ドメイン、パス、およびクエリパラメータは、構成されているURIのいずれかと一致する必要があります。 これらのURIは、開発者コンソールの [構成] ページにある [OAuth 2.0リダイレクトURI] セクションで設定できます。有効なHTTPS URIまたは安全性の低いHTTP URI (localhostまたはループバックアドレスの場合) である必要があります。重複するURIの保存は許可されていません。 日本時間2021年11月30日以降、OAuth 2.0を使用する新規のアプリケーションでは、開発者コンソールの [構成] タブで設定されたURIとリダイレクト時に使用されるURIが厳密に一致する必要があります。また、そのため新規のアプリケーションと既存のアプリケーションの両方で、複数のリダイレクトURIを追加できるようになります。 アプリケーション用にリダイレクトURIを複数設定した場合、承認URLには、開発者コンソールで設定したURIのいずれかと一致する`redirect_uri`パラメータを含める必要があります。このパラメータが指定されていない場合、ユーザーがアプリケーションにアクセス権限を付与すると、`redirect_uri_missing`エラーが表示され、アプリにリダイレクトされません。 既存のアプリケーションでは、サービスの中断を回避するために、日本時間2022年5月14日までにこのURLを変更する必要があります。 ### アプリケーションスコープ スコープを使用して、アプリケーションがデータにアクセスするために必要な権限を定義します。各オプションの詳細については、[スコープのガイド](g://api-calls/permissions-and-errors/scopes)を参照してください。 ### CORSドメイン アプリケーションがJavaScriptでフロントエンドのブラウザコードからAPIコールを実行する場合は、[クロスオリジンリソース共有](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing) (CORS) のために、これらの呼び出しの実行元となるドメインを許可リストに追加する必要があります。すべてのリクエストがサーバー側のコードから発行される場合は、このセクションをスキップできます。 許可リストにすべてのURIを追加するには、[開発者コンソール](https://app.box.com/developers/console)の [**構成**] タブの下部にある [**CORSドメイン**] セクションに移動します。 **Source:** [https://ja.developer.box.com/guides/authentication/oauth2/oauth2-setup/](https://ja.developer.box.com/guides/authentication/oauth2/oauth2-setup/) --- ### OAuth 2.0認証 **Type:** guide | **Category:** 認証 | **Section:** Developer Guides OAuth 2.0認証 クライアント側OAuth 2.0は、Box APIに対してユーザーを認証する最も簡単な方法の… # OAuth 2.0認証 クライアント側OAuth 2.0は、Box APIに対してユーザーを認証する最も簡単な方法の1つです。これは、ユーザーがアプリケーションから他のアプリケーションにある自分のデータにアクセスできるようにすることを目的とした[オープンスタンダード](https://oauth.net/2/)です。 Twitter、Facebook、またはGoogleを使用してウェブサイトにログインしたことがあれば、OAuth 2.0を使用したことがあると考えられます。 Boxでのクライアント側認証にも同様のフローがあります。このフローでは、ユーザーは、アプリケーションからBoxウェブアプリにリダイレクトされて、ログインするように求められ、アプリケーションに対してユーザーのデータへのアクセス権限を付与します。 ## OAuth 2.0を使用する場合 クライアント側認証は、以下に当てはまるアプリに最適な認証方法です。 - 既存のBoxアカウントを持っているユーザーを使用する - ユーザーにBoxを使用していることを知らせる必要がある - ユーザーのBoxアカウントにデータを保存し、アプリケーションのBoxアカウントには保存しない **Source:** [https://ja.developer.box.com/guides/authentication/oauth2/](https://ja.developer.box.com/guides/authentication/oauth2/) --- ### Oktaによるアプリへのログイン **Type:** quick-start | **Category:** SSOとApp User | **Section:** Developer Guides Oktaによるアプリへのログイン Okta、Box、基本のアプリケーションを設定したら、次は、アプリケーションコードフローにおける最初のステップ、Oktaログインに目を向けます。 Oktaログインでは、ログインのためにユーザーをOkta… # Oktaによるアプリへのログイン Okta、Box、基本のアプリケーションを設定したら、次は、アプリケーションコードフローにおける最初のステップ、Oktaログインに目を向けます。 Oktaログインでは、ログインのためにユーザーをOktaにリダイレクトする際に使用される言語のOpenID Connect (OIDC) フレームワークを使用して、Oktaのユーザー情報をアプリケーションに返します。こうしたOktaのユーザー情報は、次の手順でBoxユーザーの検証と作成に使用されます。 このセクションでは、以下の操作について説明します。 - アプリケーション構成のスケルトンを設定します。 - ユーザートラフィックを処理するために選択したフレームワークのルートを定義します。 - Oktaのユーザー情報を、Boxユーザーを検証する次の手順に渡します。 ## スケルトンの設定 ローカルアプリケーションディレクトリで、手順1で作成した`server.js`ファイルを読み込みます。 まず、以下のパッケージ定義と構成情報をファイルにコピーします。 ``` const session = require('express-session'); const { ExpressOIDC } = require('@okta/oidc-middleware'); const bodyParser = require('body-parser'); const boxSDK = require('box-node-sdk'); const config = require('./config.js'); const express = require('express')(); const http = require('http'); const path = require('path'); const fs = require('fs'); express.use(session({ secret: 'this should be secure', resave: true, saveUninitialized: false })); const oidc = new ExpressOIDC({ issuer: `https://${config.oktaOrgUrl}/oauth2/default`, client_id: config.oktaClientId, client_secret: config.oktaClientSecret, appBaseUrl: config.oktaBaseUrl, loginRedirectUri: `${config.oktaBaseUrl}${config.oktaRedirect}`, scope: 'openid profile' }); express.use(oidc.router); express.use(bodyParser.json()); express.use(bodyParser.urlencoded({ extended: true })); ``` これにより、Express構成とOkta OIDCコネクタの情報が設定されます。ExpressはOIDCコネクタを使用するよう設定され、このクイックスタートガイドの手順2で保存したOktaの情報はOkta統合のコネクタの構成に使用されます。 次に、ルーティングの詳細を追加します。 ``` // Redirect to Okta login express.get('/', (req, res) => { // TODO: HANDLE ROUTE }); ``` これにより、アプリケーションのエントリルートが定義されます。ユーザーがアプリケーションのルート (`/`) にアクセスを試みると、このルート内のコードが実行されます。 最後に、Expressサーバーの初期化を追加してトラフィックをリッスンします。 ``` // Create server const port = process.env.PORT || 3000; http.createServer(express).listen(port, () => { console.log(`Server started: Listening on port ${port}`); }); ``` ローカルアプリケーションディレクトリで、手順1で作成した`/src/main/java/com/box/sample/Application.java`ファイルを読み込みます。別のアプリケーション名を使用している場合は、同等のディレクトリを読み込みます。 以下の基本的なアプリケーション構造をファイルにコピーします。 ``` package com.box.okta.sample; import java.io.FileReader; import java.io.IOException; import java.io.Reader; import java.net.URL; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.EnableAutoConfiguration; import org.springframework.security.core.annotation.AuthenticationPrincipal; import org.springframework.security.oauth2.core.oidc.user.OidcUser; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RestController; import com.box.sdk.BoxAPIRequest; import com.box.sdk.BoxConfig; import com.box.sdk.BoxDeveloperEditionAPIConnection; import com.box.sdk.BoxJSONResponse; import com.box.sdk.BoxUser; import com.box.sdk.CreateUserParams; import com.eclipsesource.json.JsonArray; import com.eclipsesource.json.JsonObject; import com.eclipsesource.json.JsonValue; @RestController @EnableAutoConfiguration public class Application { static BoxDeveloperEditionAPIConnection api; // TODO: SET ROUTE // TODO: INITIALIZE SERVER } ``` これにより、必要なimport、`Application`クラス、標準的な共有Box APIの接続属性が設定されます。これらは次の手順で定義します。 `// TODO: SET ROUTE`を以下の内容に置き換えます。 ``` @RequestMapping("/") String home(@AuthenticationPrincipal OidcUser user) throws IOException { // TODO: HANDLE ROUTE } ``` このルートマッピングではアプリケーションのエントリルートを定義します。ユーザーがログアウトした状態でアプリケーションのルート (`/`) にアクセスを試みると、OIDCコネクタによってユーザーは自動的にOktaログインにプッシュされるため、リダイレクトを設定する必要がありません。ユーザーがログイン状態の場合は、このルート内のコードが実行されます。 `// TODO: INITIALIZE SERVER`を以下の内容に置き換えて、Spring Bootサーバーを初期化してトラフィックをリッスンします。 ``` public static void main(String[] args) { SpringApplication.run(Application.class, args); } ``` ローカルアプリケーションディレクトリで、手順1で作成した`server.py`ファイルを読み込みます。 以下の基本的なアプリケーション構造をファイルにコピーします。 ``` from flask import Flask, redirect, g, url_for from flask_oidc import OpenIDConnect from okta import UsersClient from boxsdk import Client from boxsdk import JWTAuth import requests import config import json app = Flask(__name__) app.config.update({ 'SECRET_KEY': config.okta_client_secret, 'OIDC_CLIENT_SECRETS': './client_secrets.json', 'OIDC_DEBUG': True, 'OIDC_ID_TOKEN_COOKIE_SECURE': False, 'OIDC_SCOPES': ["openid", "profile"], 'OIDC_CALLBACK_ROUTE': config.okta_callback_route }) oidc = OpenIDConnect(app) okta_client = UsersClient(config.okta_org_url, config.okta_auth_token) ``` これにより、Flask構成、Oktaクライアント、Okta OIDCコネクタの情報が設定されます。FlaskはOIDCコネクタを使用するよう設定され、このクイックスタートガイドの手順2で保存したOktaの情報はOkta統合のコネクタの構成に使用されます。 次に、ルート処理が行われる前に実行する`before_request`定義を追加します。ここでは、この定義を使用してOktaのユーザー情報 (存在する場合) をキャプチャします。 ``` # Fetch Okta user record if logged in @app.before_request def before_request(): # TODO: HANDLE BEFORE REQUEST ``` 最後に、アプリケーションのエントリルートと`box_auth`ルートを定義します。 ``` # Main application route @app.route('/') def start(): # TODO: HANDLE MAIN ROUTE # Box user verification @app.route("/box_auth") @oidc.require_login def box_auth(): # TODO: HANDLE BOX AUTH ROUTE return 'Complete' ``` ユーザーがアプリケーションのルート (`/`) にアクセスを試みると、このルート内のコードが実行されます。Oktaユーザーを検証する際は、`box_auth`ルート内のコードが実行されます。 ローカルアプリケーションで、`Views` > `Shared` > `Layout.cshtml`を読み込みます。これは、ASP.NETアプリケーションが読み込まれるとレンダリングされるビジュアルコンポーネントになります。ページの先頭に以下のコードを挿入します。 ``` @using System.Security.Claims; @if (User.Identity.IsAuthenticated) { <p class="navbar-text">Hello, @User.Identity.Name</p> } else { <a asp-controller="Account" asp-action="SignIn">Sign In</a> } ``` Oktaにログインしているユーザーがアクセスすると、Helloというメッセージが表示されます。ログインしていない場合は、サインインリンクが表示されます。 `<a asp-controller="Account" asp-action="SignIn">Sign In</a>`という行に含まれる`asp-controller="Account"`は、作成予定のAccountコントローラでリクエストを処理することを意味します。また、`asp-action="SignIn"`は、このコントローラの`SignIn`メソッドが実行されることを意味します。このファイルを保存して閉じます。 `Controllers`ディレクトリ内に、`AccountController.cs`という新しいファイルを作成します。これは、サインインリンクがクリックされたときに実行されるコントローラになります。 以下の基本的なアプリケーション構造をファイルにコピーします。 ``` using System.IO; using System.Linq; using System.Threading.Tasks; using Microsoft.AspNetCore.Mvc; using Microsoft.AspNetCore.Authorization; using Okta.AspNetCore; using Box.V2; using Box.V2.Config; using Box.V2.JWTAuth; using Box.V2.Models; public class AccountController : Controller { public IActionResult SignIn() { if (!HttpContext.User.Identity.IsAuthenticated) { return Challenge(OktaDefaults.MvcAuthenticationScheme); } return RedirectToAction("Profile", "Account"); } [Authorize] [Route("~/profile")] public IActionResult Profile() { // TODO: HANDLE ROUTE } } ``` ユーザーがサインインリンクをクリックすると、このコントローラの`SignIn`メソッドが実行されます。ユーザーがまだ認証されていない場合は`Challenge`に送信され、ユーザーはログインするためにOktaにリダイレクトされます。この機能はルーティングフレームワークによって処理されるため、追加で実行するコードは必要ありません。ユーザーが認証済みの場合は`Profile`ルーティングメソッドにリダイレクトされます。 # 前の手順が完了していません 最初に、手順1でお好みの言語/フレームワークを選択してください。 ## アプリケーションルートの設定 今度は、メインのルート (`/`) に入ったときに実行されるコードを定義する必要があります。 メインのルート内の`// TODO: HANDLE ROUTE`を以下のコードに置き換えます。 ``` if (req.userContext && req.userContext.userinfo) { const tokenSet = req.userContext.tokens; const userInfo = req.userContext.userinfo; // If Okta ID is present, pass to Box user validation if (userInfo.sub) { box.validateUser(userInfo, res); } else { console.log('No Okta ID identified'); } } else { res.redirect('/login'); } ``` 上記のコードでは、まず、OIDCコネクタから入手できるOktaのユーザー情報があるかどうかを確認しています。ユーザーがログインすると、このコネクタにより、Oktaのユーザーと構成の情報が`req.userContext`内のルートで使用できるようになります。 ユーザー情報が存在する場合、つまりユーザーがOktaにログインしている場合は、ユーザー情報をExpressのレスポンスオブジェクトとともに`box.validateUser`に渡して、関連付けられたBoxユーザーが存在するかどうかを確認します。これは次の手順で定義します。 ユーザー情報が存在しない場合、ユーザーは`/login`にリダイレクトされます。OIDCコネクタは自動的にこのルートを処理し、そのユーザーにOktaログインを強制します。 メインのルート内の`// TODO: HANDLE MAIN ROUTE`を以下のコードに置き換えます。 ``` // Validate OIDC user against Box return validateUser(user); ``` Java OIDCコネクタは、手間のかかる部分のほとんどを代わりに処理してくれます。ログアウトしたユーザーがこのルートにアクセスすると、自動的にOktaログインにプッシュされます。ログインすると、OIDCユーザーオブジェクトがこのルートに使用できるようになります。そのユーザーオブジェクトは、次の手順で定義する`validateUser`関数に渡します。 メインのルート内の`// TODO: HANDLE BEFORE REQUEST`を以下のコードに置き換えます。 ``` if oidc.user_loggedin: g.user = okta_client.get_user(oidc.user_getfield('sub')) else: g.user = None ``` これにより、OIDCユーザーが存在するかどうか、つまりユーザーがすでにOktaにログインしているかどうかが確認されます。存在する場合は、Oktaクライアントオブジェクトを使用してユーザーオブジェクトを設定し、存在しない場合はユーザーオブジェクトを`None`に設定します。 次に、メインのルート内の`// TODO: HANDLE ROUTE`を以下のコードに置き換えます。 ``` return redirect(url_for(".box_auth")) ``` このコードに入ると、ユーザーはOktaにログインしていない場合に、ログインするためにOIDCコネクタによってOktaにリダイレクトされます。ログイン後 (またはユーザーがすでにログインしている場合) は、`box_auth`ルートコードに転送されます。 最後に、`box_auth`ルート内の`// TODO: HANDLE BOX AUTH ROUTE`を以下のコードに置き換えます。 ``` box = Box() return box.validateUser(g) ``` これにより、Oktaユーザーオブジェクトが渡されることで、Boxクラスの新しいインスタンスが作成され、`validateUser`メソッドが呼び出されます。このクラスとメソッドは次の手順で定義します。 メインのルート内の`// TODO: HANDLE ROUTE`を以下のコードに置き換えます。 ``` var subClaim = HttpContext.User.Claims.First(c => c.Type == "sub"); var sub = subClaim.Value; var nameClaim = HttpContext.User.Claims.First(c => c.Type == "name"); var name = nameClaim.Value; Task userSearch = validateUser(name, sub); Task.WaitAll(userSearch); return Content(name); ``` このブロックでは、Oktaユーザーアカウントのsub (一意のID) とnameをキャプチャし、次の手順で作成する`validateUser`メソッドにそのデータを送信して、一致するBoxユーザーを検出します。 # 前の手順が完了していません 最初に、手順1でお好みの言語/フレームワークを選択してください。 ## まとめ - Oktaのスケルトンルートと構成を設定しました。 - Boxユーザーの確認に渡すメインのルートハンドラを設定しました。 Oktaログインを設定しました **Source:** [https://ja.developer.box.com/guides/sso-identities-and-app-users/connect-okta-to-app-users/logging-into-app/](https://ja.developer.box.com/guides/sso-identities-and-app-users/connect-okta-to-app-users/logging-into-app/) --- ### Oktaの構成 **Type:** quick-start | **Category:** SSOとApp User | **Section:** Developer Guides Oktaの構成 OktaとBoxの統合における次の手順では、Oktaアプリケーションとユーザーを作成して構成した後、アプリケーション内でOkta… # Oktaの構成 OktaとBoxの統合における次の手順では、Oktaアプリケーションとユーザーを作成して構成した後、アプリケーション内でOktaに接続するために必要となるいくつかの情報を抽出します。 このチュートリアルでは、空のアプリケーションとユーザーダッシュボードから開始します。これは、準備が整っている可能性のある既存のインストールへの悪影響を避け、インスタンスへの管理者権限を確保するためです。 ## Oktaアプリケーションの作成 まず[Oktaの開発者向けサイト](https://developer.okta.com/)で、新しいDeveloperアカウントにサインアップします。すでにアカウントを持っている場合は個人アカウントでログインします。 既存のアカウントでログインした場合は、Oktaのダッシュボードが表示されるので、右上の [**Admin (管理)**] ボタンをクリックします。 新しいDeveloperアカウントを作成した場合は、管理ダッシュボードにリダイレクトされます。 管理パネルが表示されたら、上部の [**Applications (アプリケーション)**] オプションをクリックします。 アプリケーションページで [**Add Application (アプリケーションの追加)**] ボタンをクリックします。アプリケーションの種類として [**Web (ウェブ)**] を選択し、[**Next (次へ)**] ボタンをクリックします。 Oktaは、アプリケーションの承認とユーザーの認証それぞれに、[OAuth 2](https://oauth.net/2/)と[OpenID Connect](https://openid.net/) (OIDC) の両方を使用します。OpenID Connectの統合では、多数の一般的な言語フレームワーク内で組み込みのOIDCコネクタを使用でき、コールバックルートの処理、ログインおよびログアウト方法の提供、アプリケーションへのルートの保護によってアプリケーションとユーザーの管理が簡略化されます。 この初回の統合を簡略化するために、言語とフレームワークのOIDCコネクタにデフォルトのコールバックルートと設定を使用します。どの統合の種類を選択するかによって、構成設定が若干変わります。 以下の構成設定を使用して、アプリケーションの詳細を入力します。 - 名前: 任意 - 基本URI: `http://localhost:3000/` - ログインリダイレクトURI: `http://localhost:3000/authorization-code/callback` - ログアウトリダイレクトURI: `http://localhost:3000/logout` - 使用できる許可タイプ: [**Authorization Code (承認コード)**] のみを選択 - 名前: 任意 - 基本URI: `http://localhost:8080/` - ログインリダイレクトURI: `http://localhost:8080/authorization-code/callback` - ログアウトリダイレクトURI: `http://localhost:8080/logout` - 使用できる許可タイプ: [**Authorization Code (承認コード)**] のみを選択 - 名前: 任意 - 基本URI: `http://127.0.0.1:5000/` - ログインリダイレクトURI: `http://127.0.0.1:5000/oidc/callback` - ログアウトリダイレクトURI: `http://127.0.0.1:5000/logout` - 使用できる許可タイプ: [**Authorization Code (承認コード)**] のみを選択 - 名前: 任意 - 基本URI: `https://localhost:5001/` - ログインリダイレクトURI: `https://localhost:5001/authorization-code/callback` - ログアウトリダイレクトURI: `https://localhost:5001/logout` - 使用できる許可タイプ: [**Authorization Code (承認コード)**] のみを選択 # 前の手順が完了していません 最初に、手順1でお好みの言語/フレームワークを選択してください。 [**Done (完了)**] ボタンをクリックしてアプリケーションを作成し、アプリケーションの一般設定に移動します。 ## アプリケーション資格情報のコピー 次に、1つ前の手順で設定した構成ファイルを使用して、ファイル内にOktaのアプリケーション組織とアプリの詳細を追加します。 Oktaアプリケーションの情報はほとんどが一般設定ページにありますが、Okta組織を後方参照するために構成URIで使用されている`Org URL`は例外です。`Org URL`を取得するには、Okta管理コンソールのダッシュボードに移動します。`Org URL`は画面の右上隅に表示されます。 前の手順で選択した言語とフレームワークに応じて、適切な構成ファイルを設定します。 - 任意のエディタで、ローカルアプリケーションディレクトリ内の`config.json`を開きます。 以下の行項目を、Oktaの構成情報で適宜更新します。 - `oktaClientId`: アプリケーションの一般設定の [**Client Credentials (クライアント資格情報)**] セクションから取得。 - `oktaClientSecret`: アプリケーションの一般設定の [**Client Credentials (クライアント資格情報)**] セクションから取得。 - `oktaOrgUrl`: 管理ダッシュボードのメインページで右上から取得。 ファイルを保存します。 `config.json`ファイルは次のようになります。 ``` const oktaClientId = exports.oktaClientId = '0oa48567frkg5KW4x6'; const oktaClientSecret = exports.oktaClientSecret = 'cugDJy2ERfIQHDXv-j2134DfTTes-Sa3'; const oktaOrgUrl = exports.oktaOrgUrl = 'YOURDOMAIN.okta.com'; const oktaBaseUrl = exports.oktaBaseUrl = 'http://localhost:3000'; const oktaRedirect = exports.oktaRedirect = '/authorization-code/callback'; ``` `/src/main/resources/application.properties`ファイルを開き、以下の行を更新します。 - `okta.oauth2.issuer`: 管理ダッシュボードのメインページの右上から取得したOrg URLの後に`/oauth2/default`を付けたもの。たとえばOrg URLが`https://dev-123456.okta.com`の場合、この発行者文字列は`https://dev-123456.okta.com/oauth2/default`になります。 - `okta.oauth2.clientId`: アプリケーションの一般設定の [**Client Credentials (クライアント資格情報)**] セクションから取得。 - `okta.oauth2.clientSecret`: アプリケーションの一般設定の [**Client Credentials (クライアント資格情報)**] セクションから取得。 ファイルを保存します。 `/src/main/resources/application.properties`ファイルは次のようになります。 ``` okta.oauth2.redirect-uri=/authorization-code/callback okta.oauth2.issuer=https://YOURDOMAIN.okta.com/oauth2/default okta.oauth2.clientId=0oa48567frkg5KW4x6 okta.oauth2.clientSecret=cugDJy2ERfIQHDXv-j2134DfTTes-Sa3 security.oauth2.sso.loginPath=/authorization-code/callback ``` Python/Flaskの統合では、組織とアプリの標準的な構成情報に加え、追加の認証トークンが必要です。 認証トークンを作成するには、次の手順に従います。 - Oktaの管理ダッシュボードの [**API**] -> [**Token (トークン)**] セクションに移動します。 - [**Create Token (トークンの作成)**] ボタンをクリックします。 - トークンの名前を入力し、[**Create (作成)**] をクリックします。 - 生成されたトークンをコピーします。 次に、ローカルのアプリケーション構成ファイルを更新します。 - 任意のエディタで、ローカルアプリケーションディレクトリ内の`config.py`を開きます。 以下の行項目を、Oktaの構成情報で適宜更新します。 - `okta_client_secret`: アプリケーションの一般設定の [**Client Credentials (クライアント資格情報)**] セクションから取得。 - `okta_org_url`: 管理ダッシュボードのメインページで右上から取得。 - `okta_auth_token`: 上記で作成したトークン。 ファイルを保存します。 `config.py`ファイルは次のようになります。 ``` okta_client_id = '0oa48567frkg5KW4x6' okta_client_secret = 'cugDJy2ERfIQHDXv-j2134DfTTes-Sa3' okta_org_url = 'http://YOURDOMAIN.okta.com' okta_auth_token = '01KkTQTRfs1yKLr4Ojy26iqoIjK_4fHyq132Dr5T' okta_callback_route = '/oidc/callback' ``` 最後に、Flask構成ファイルを更新します。 - 任意のエディタで、ローカルアプリケーションディレクトリ内の`client_secrets.json`を開きます。 以下の行項目を、Oktaの構成情報で適宜更新します。 - `client_id`: アプリケーションの一般設定の [**Client Credentials (クライアント資格情報)**] セクションから取得。 - `client_secret`: アプリケーションの一般設定の [**Client Credentials (クライアント資格情報)**] セクションから取得。 - `auth_uri`: 管理ダッシュボードのメインページの右上から取得したOrg URLの後に`/oauth2/default/v1/authorize`を付けたもの。たとえばOrg URLが`https://dev-123456.okta.com`の場合、この発行者文字列は`https://dev-123456.okta.com/oauth2/default/v1/authorize`になります。 - `token_uri`: 管理ダッシュボードのメインページの右上から取得したOrg URLの後に`/oauth2/default/v1/token`を付けたもの。たとえばOrg URLが`https://dev-123456.okta.com`の場合、この発行者文字列は`https://dev-123456.okta.com/oauth2/default/v1/token`になります。 - `issuer`: 管理ダッシュボードのメインページの右上から取得したOrg URLの後に`/oauth2/default`を付けたもの。たとえばOrg URLが`https://dev-123456.okta.com`の場合、この発行者文字列は`https://dev-123456.okta.com/oauth2/default`になります。 - `userinfo_uri`: 管理ダッシュボードのメインページの右上から取得したOrg URLの後に`/oauth2/default/userinfo`を付けたもの。たとえばOrg URLが`https://dev-123456.okta.com`の場合、この発行者文字列は`https://dev-123456.okta.com/oauth2/default/userinfo`になります。 ファイルを保存します。 `client_secrets.json`ファイルは次のようになります。 ``` { "web": { "client_id": "0oa48567frkg5KW4x6", "client_secret": "cugDJy2ERfIQHDXv-j2134DfTTes-Sa3", "auth_uri": "https://YOURDOMAIN.okta.com/oauth2/default/v1/authorize", "token_uri": "https://YOURDOMAIN.okta.com/oauth2/default/v1/token", "issuer": "https://YOURDOMAIN.okta.com/oauth2/default", "userinfo_uri": "https://YOURDOMAIN.okta.com/oauth2/default/userinfo", "redirect_uris": [ "http://127.0.0.1:5000/oidc/callback" ] } } ``` - 任意のエディタで、ローカルアプリケーションディレクトリ内の`Startup.cs`を開きます。 `ConfigureServices`メソッド内の以下の行項目を、Oktaの構成情報で適宜更新します。 - `OktaDomain`: 管理ダッシュボードのメインページで右上から取得。 - `ClientId`: アプリケーションの一般設定の [**Client Credentials (クライアント資格情報)**] セクションから取得。 - `ClientSecret`: アプリケーションの一般設定の [**Client Credentials (クライアント資格情報)**] セクションから取得。 ファイルを保存します。 `ConfigureServices`メソッドは次のようになります。 ``` services.AddControllersWithViews(); services.AddAuthentication(options => { options.DefaultAuthenticateScheme = CookieAuthenticationDefaults.AuthenticationScheme; options.DefaultSignInScheme = CookieAuthenticationDefaults.AuthenticationScheme; options.DefaultChallengeScheme = OktaDefaults.MvcAuthenticationScheme; }) .AddCookie() .AddOktaMvc(new OktaMvcOptions { OktaDomain = "https://YOURDOMAIN.okta.com", ClientId = "0oa48567frkg5KW4x6", ClientSecret = "cugDJy2ERfIQHDXv-j2134DfTTes-Sa3" }); ``` # 前の手順が完了していません 最初に、手順1でお好みの言語/フレームワークを選択してください。 ## ユーザーの作成 Oktaの設定における最後の手順では、アプリケーションへのログインに使用するテストユーザーを作成します。 1. Oktaの管理ダッシュボードの [**Users (ユーザー)**] セクションに移動します。 2. [**Add Person (ユーザーの追加)**] ボタンをクリックします。 3. 適切なユーザー情報をすべて入力します。パスワードには [**Set by admin (管理者が設定)**] を選択し、ユーザーのパスワードを入力します。また、[**User must change password on first login (ユーザーは初回ログイン時にパスワードの変更が必要)**] オプションの選択を解除します。ログインにはユーザー名とパスワードを使用します。これらの設定はテスト目的のみで使用されるため、ユーザーの作成とセキュリティのベストプラクティスではありません。 4. [**Save (保存)**] ボタンをクリックしてユーザーを作成します。 ## まとめ - Oktaアプリケーションを作成しました。 - ローカルアプリケーションでOktaの構成情報を更新しました。 - Oktaのテストユーザーを作成しました。 Oktaアプリを作成し、ユーザー/ローカル構成を設定しました **Source:** [https://ja.developer.box.com/guides/sso-identities-and-app-users/connect-okta-to-app-users/configure-okta/](https://ja.developer.box.com/guides/sso-identities-and-app-users/connect-okta-to-app-users/configure-okta/) --- ### OpenAI GPT o3 **Type:** guide | **Category:** Box AI | **Section:** Developer Guides OpenAI GPT o3 OpenAI GPT o… # OpenAI GPT o3 **OpenAI GPT o3**は、推論や問題解決のタスクに集中力や能力を高めて取り組むよう特化して設計されています。ユーザーのリクエストの処理と理解により多くの時間を費やすため、科学、コーディング、数学などの分野で、以前の反復処理に比べて非常に強力になっています。 ## モデルの詳細 | 項目 | 値 | 説明 | | --- | --- | --- | | モデル名 | GPT o3 | モデルの名前。 | | モデルのカテゴリ | プレミアム | モデルのカテゴリ - 標準またはプレミアム。 | | APIモデル名 | openai__gpt_o3 | Box AI APIでのモデルの上書きに使用されるモデルの名前。APIを動作させるには、ユーザーがこの名前を正確に指定する必要があります。 | | ホスティングレイヤー | OpenAI | LLMを安全にホストする、信頼できる組織。 | | モデルプロバイダ | OpenAI | このモデルを提供する組織。 | | リリース日 | 2025年4月16日 | モデルのリリース日。 | | ナレッジカットオフ日 | 2024年5月 | モデルが情報の更新を取得しなくなった日付。 | | 入力コンテキストウィンドウ | 200,000トークン | 入力コンテキストウィンドウでサポートされるトークン数。 | | 出力トークンの最大数 | 100,000トークン | 1回のリクエストでモデルが生成できるトークン数。 | | 経験に基づいたスループット | 指定なし | モデルが1秒あたりに生成できるトークン数。 | | オープンソース | いいえ | モデルのコードを一般公開するかどうかを指定します。 | ## その他のドキュメント 詳細については、[OpenAI GPT o3の公式ドキュメント](https://openai.com/index/introducing-o3-and-o4-mini/)を参照してください。 **Source:** [https://ja.developer.box.com/guides/box-ai/ai-models/openai-gpt-o3-model-card/](https://ja.developer.box.com/guides/box-ai/ai-models/openai-gpt-o3-model-card/) --- ### OpenAI GPT-5 **Type:** guide | **Category:** Box AI | **Section:** Developer Guides OpenAI GPT-5 OpenAI GPT-5 is a multimodal model with advanced reasoning and long-context understanding. モデルの詳細 項目 値 説明 モデル名 GPT-… # OpenAI GPT-5 **OpenAI GPT-5** is a multimodal model with advanced reasoning and long-context understanding. ## モデルの詳細 | 項目 | 値 | 説明 | | --- | --- | --- | | モデル名 | GPT-5 | モデルの名前。 | | モデルのカテゴリ | プレミアム | モデルのカテゴリ: 標準またはプレミアム。 | | APIモデル名 | openai__gpt_5_reasoning_alpha | Box AI APIでのモデルの上書きに使用されるモデルの名前。APIを動作させるには、ユーザーがこの名前を正確に指定する必要があります。 | | ホスティングレイヤー | OpenAI | LLMを安全にホストする、信頼できる組織。 | | モデルプロバイダ | OpenAI | このモデルを提供する組織。 | | リリース日 | TBD | モデルのリリース日。 | | ナレッジカットオフ日 | 2024年10月 | モデルが情報の更新を取得しなくなった日付。 | | 入力コンテキストウィンドウ | 100万トークン | 入力コンテキストウィンドウでサポートされるトークン数。 | | 出力トークンの最大数 | 100,000トークン | 1回のリクエストでモデルが生成できるトークン数。 | | 経験に基づいたスループット | 指定なし | モデルが1秒あたりに生成できるトークン数。 | | オープンソース | いいえ | モデルのコードを一般公開するかどうかを指定します。 | ## その他のドキュメント For additional information, see [official OpenAI GPT-5 documentation](https://openai.com/index/introducing-gpt-4-5/). **Source:** [https://ja.developer.box.com/guides/box-ai/ai-models/openai-gpt-5-reasoning-alpha-model-card/](https://ja.developer.box.com/guides/box-ai/ai-models/openai-gpt-5-reasoning-alpha-model-card/) --- ### PDFレプリゼンテーションの取得 **Type:** guide | **Category:** レプリゼンテーション | **Section:** Developer Guides PDFレプリゼンテーションの取得 PDFレプリゼンテーションでは、予測しやすい方法でモバイルアプリとウェブアプリにドキュメントを埋め込むことができます。PDFレプリゼンテーションでは、元のファイルに電子すかしが適用されている場合に電子すかしがサポートされます。 PDF… # PDFレプリゼンテーションの取得 PDFレプリゼンテーションでは、予測しやすい方法でモバイルアプリとウェブアプリにドキュメントを埋め込むことができます。PDFレプリゼンテーションでは、元のファイルに電子すかしが適用されている場合に電子すかしがサポートされます。 PDFレプリゼンテーションは、元のファイルをBoxにアップロードしたときに生成されますが、電子すかし付きPDFは、電子すかし付きファイルを初めて取得したときに生成されます。 ## 手順 PDFレプリゼンテーションを取得するには、以下の手順に従います。 - [すべてのレプリゼンテーションのリストを取得する](guide://representations/list-all-representations) - 目的のファイルタイプ`[pdf]`を表す`x-rep-hints`ヘッダーを渡して、[PDFをリクエスト](guide://representations/request-a-representation)する - `url_template`を呼び出して[PDFをダウンロード](guide://representations/download-a-representation)する。その際、`{+asset_path}`は、リクエストするPDFのページ (`1.pdf`など) に置き換えます。 ## 電子すかし付きPDF 電子すかし付きPDFを取得するには、Boxで元のファイル自体に電子すかしを適用する必要があります。ファイルに電子すかしを適用するには、Boxウェブアプリまたは[`PUT /files/:id/watermark/`](endpoint://put-files-id-watermark) APIを使用します。 電子すかしが適用されると、そのファイルの電子すかし付きPDFレプリゼンテーションが生成されます。 **Source:** [https://ja.developer.box.com/guides/representations/pdf/](https://ja.developer.box.com/guides/representations/pdf/) --- ### Platformアプリ **Type:** guide | **Category:** アプリケーション | **Section:** Developer Guides Platformアプリ Platformアプリはほとんどのユースケースに対応しており、最も柔軟なアプリケーションの種類です。 Platformアプリケーションは、通常、カスタムインターフェース内でBox機能をユーザーに表示します。Box… # Platformアプリ Platformアプリはほとんどのユースケースに対応しており、最も柔軟なアプリケーションの種類です。 Platformアプリケーションは、通常、カスタムインターフェース内でBox機能をユーザーに表示します。Boxには、コンテンツの閲覧、検索、プレビューなどの機能のために、[UI Elements](g://embed/ui-elements)と呼ばれる、組み込みのカスタマイズ可能なユーザーインターフェースコンポーネントが用意されています。 ## 認証方法 Platformアプリでは、[OAuth 2.0](g://authentication/oauth2)、[JWT](g://authentication/jwt)、および[クライアント資格情報許可](g://authentication/client-credentials)がサポートされています。 認証方法の詳細を確認する ## 使用するタイミング アプリケーションが以下のような場合に、Platformアプリを使用すると最も効果的です。 - 認証に[OAuth 2.0](g://authentication/oauth2)、[JWT](g://authentication/jwt)、または[クライアント資格情報許可](g://authentication/client-credentials)を使用する - ファイルをアップロードおよびダウンロードする - 自分が所有するファイルにも、[管理対象ユーザーまたは外部ユーザー](g;//getting-started/user-types/#managed-users/)が所有するファイルにも自由にアクセスしたい - Box統合にアプリケーションを掲載する - Boxウェブアプリとの統合を可能にする ## ユースケース 以下は、Platformアプリのユースケースの例です。 アプリケーション内のファイル保存場所。これにより、エンドユーザーが自分と共有されているファイルにアクセスできると同時に、従業員にもBoxウェブアプリを介して同じファイルへのアクセス権限が提供されます。 この一例として、ファイナンシャルアドバイザは、Platformアプリケーション内で閲覧またはコメントが可能な取引明細書や投資目論見書を投資家と共有します。 アプリケーションのファイルアップロード機能。これにより、エンドユーザーは、独自に構築したアプリケーション内からBoxにファイルを送信したりアップロードしたりできます。その後、これらのアップロードにより、Boxウェブアプリを使用したビジネスプロセスが開始されます。 この一例として、志願者が採用ポータルに送信した経歴書のPDFは、審査のため適切な従業員に転送されます。 ## 承認 Platformアプリは、使用前に承認が必要になる場合があります。 Platformアプリの承認方法を確認する **Source:** [https://ja.developer.box.com/guides/applications/app-types/platform-apps/](https://ja.developer.box.com/guides/applications/app-types/platform-apps/) --- ### Platformアプリの承認 **Type:** guide | **Category:** 承認 | **Section:** Developer Guides Platformアプリの承認 JWTまたはクライアント資格情報許可を使用するサーバー認証アプリケーションは、使用前にBox管理者が承認する必要があります。 OAuth 2.0認証を使用する未公開アプリケーションは、デフォルトで非アクティブになっている場合、Box… # Platformアプリの承認 [JWT](g://authentication/jwt)または[クライアント資格情報許可](g://authentication/client-credentials)を使用するサーバー認証アプリケーションは、使用前にBox管理者が承認する必要があります。 [OAuth 2.0](g://authentication/oauth2)認証を使用する未公開アプリケーションは、[デフォルトで非アクティブ](g://security/#enterprise-settings-and-authorization)になっている場合、Box管理者による有効化が必要になることがあります。 Box管理者は、管理コンソールでアプリケーションを適切に承認または有効化するために、そのクライアントIDが必要になります。 [[統合](g://applications)] ビューを使用すると、アプリケーションの承認ステータスと有効化ステータスをすばやく確認できます。 ## 承認の通知 アプリの承認を送信するための半自動プロセスは、開発者コンソールですべての種類のPlatformアプリケーションに使用できます。 ### サーバー認証アプリ [開発者コンソール](https://app.box.com/developers/console)で、目的のアプリケーションの [**承認**] タブに移動します。 ### ユーザー認証アプリ [開発者コンソール](https://app.box.com/developers/console)で、目的のアプリケーションの [**有効化**] タブに移動します。 承認を得るためにアプリケーションを送信すると、企業のプライマリ管理者宛てにアプリケーションを承認するようメールが送信されます。Box管理者がリクエストを承認または拒否すると、その決定が記載されたメールが届きます。このプロセスの詳細については、[アプリ承認に関するサポート記事](https://support.box.com/hc/ja/articles/360043697014-Box%E3%81%AE%E3%82%A2%E3%83%97%E3%83%AA%E6%89%BF%E8%AA%8D%E3%83%97%E3%83%AD%E3%82%BB%E3%82%B9%E3%81%A7%E3%81%AE%E3%82%A2%E3%83%97%E3%83%AA%E3%81%AE%E6%89%BF%E8%AA%8D)を参照してください。 ## 手動による承認 以下の手順では、手動でアプリケーションを承認する方法について説明します。 ### 開発者の場合 1. [開発者コンソール](https://app.box.com/developers/console)で、目的のアプリケーションの [**構成**] タブに移動します。 2. [OAuth 2.0資格情報] セクションまで下にスクロールし、Box管理者に提出する [**クライアントID**] の値をコピーします。 また、[[Platformアプリ](g://applications)] ビューでアプリケーションにカーソルを合わせて**クライアントID**を調べ、`copy`ボタンを使用してそのIDをコピーすることもできます。 # Box管理者の確認方法 自分の会社の管理者がわからない場合は、Boxの [[アカウント設定](https://app.box.com/account)] ページに移動し、一番下までスクロールしてください。管理者の連絡先が設定されている場合は、[**管理者の連絡先**] の下に連絡先情報が表示されます。 ### 管理者の場合 1. [管理コンソール](https://app.box.com/master/settings/custom)に移動し、左側のナビゲーションパネルで [**統合**] タブ (1) を選択します。 2. 画面上部にある [**Platformアプリマネージャ**] タブ (2) をクリックします。 3. [サーバー認証アプリ] 画面と [ユーザー認証アプリ] 画面のどちらでも、右上にある [**Platformアプリの追加**] ボタン (3) をクリックして新しいアプリを追加します。 4. または、[Platformアプリマネージャ] の表メニュー (4) を使用してアプリを承認および有効化することもできます。 #### サーバー認証アプリ #### ユーザー認証アプリ 表示されたポップアップで、開発者が[開発者コンソール](https://app.box.com/developers/console)の [**構成**] タブから収集した、アプリケーションのクライアントIDを入力します。 ## 変更の再承認 アプリケーションのスコープまたはアクセスレベルが変更された場合は、アプリケーションを再承認する必要があります。新しい変更を有効にするには、上記のプロセスを繰り返して新しいアクセストークンをリクエストしてください。 管理者は、アプリケーションが最初に承認されたのと同じセクションで、そのアプリケーションを再承認できます。再承認するには、アプリケーション名の右側にある省略記号をクリックし、[**アプリを再承認**] を選択します。 **Source:** [https://ja.developer.box.com/guides/authorization/custom-app-approval/](https://ja.developer.box.com/guides/authorization/custom-app-approval/) --- ### Platformアプリの承認 **Type:** guide | **Category:** 承認 | **Section:** Developer Guides Platformアプリの承認 JWTまたはクライアント資格情報許可を使用するサーバー認証アプリケーションは、使用前にBox管理者が承認する必要があります。 OAuth 2.0認証を使用する未公開アプリケーションは、デフォルトで非アクティブになっている場合、Box… # Platformアプリの承認 [JWT](g://authentication/jwt)または[クライアント資格情報許可](g://authentication/client-credentials)を使用するサーバー認証アプリケーションは、使用前にBox管理者が承認する必要があります。 [OAuth 2.0](g://authentication/oauth2)認証を使用する未公開アプリケーションは、[デフォルトで非アクティブ](g://security/#enterprise-settings-and-authorization)になっている場合、Box管理者による有効化が必要になることがあります。 Box管理者は、管理コンソールでアプリケーションを適切に承認または有効化するために、そのクライアントIDが必要になります。 [[Platformアプリ](g://applications)] ビューを使用すると、アプリケーションの承認ステータスと有効化ステータスをすばやく確認できます。 ## 承認の通知 アプリの承認を送信するための半自動プロセスは、開発者コンソールですべての種類のPlatformアプリケーションに使用できます。 ### サーバー認証アプリ [開発者コンソール](https://app.box.com/developers/console)で、目的のアプリケーションの [**承認**] タブに移動します。 ### ユーザー認証アプリ [開発者コンソール](https://app.box.com/developers/console)で、目的のアプリケーションの [**有効化**] タブに移動します。 承認を得るためにアプリケーションを送信すると、企業のプライマリ管理者宛てにアプリケーションを承認するようメールが送信されます。Box管理者がリクエストを承認または拒否すると、その決定が記載されたメールが届きます。このプロセスの詳細については、[アプリ承認に関するサポート記事](https://support.box.com/hc/ja/articles/360043697014-Box%E3%81%AE%E3%82%A2%E3%83%97%E3%83%AA%E6%89%BF%E8%AA%8D%E3%83%97%E3%83%AD%E3%82%BB%E3%82%B9%E3%81%A7%E3%81%AE%E3%82%A2%E3%83%97%E3%83%AA%E3%81%AE%E6%89%BF%E8%AA%8D)を参照してください。 ## 手動による承認 以下の手順では、手動でアプリケーションを承認する方法について説明します。 ### 開発者の場合 1. [開発者コンソール](https://app.box.com/developers/console)で、目的のアプリケーションの [**構成**] タブに移動します。 2. [OAuth 2.0資格情報] セクションまで下にスクロールし、Box管理者に提出する [**クライアントID**] の値をコピーします。 また、[[Platformアプリ](g://applications)] ビューでアプリケーションにカーソルを合わせて**クライアントID**を調べ、`copy`ボタンを使用してそのIDをコピーすることもできます。 # Box管理者の確認方法 自分の会社の管理者がわからない場合は、Boxの [[アカウント設定](https://app.box.com/account)] ページに移動し、一番下までスクロールしてください。管理者の連絡先が設定されている場合は、[管理者の連絡先] の下に連絡先情報が表示されます。 ### 管理者の場合 1. [管理コンソール](https://app.box.com/master/settings/custom)に移動し、左側のナビゲーションパネルで [**アプリ**] タブ (1) を選択します。 2. 画面上部にある [**Platformアプリマネージャ**] タブ (2) をクリックします。 3. [サーバー認証アプリ] 画面と [ユーザー認証アプリ] 画面のどちらでも、右上にある [**アプリの追加**] ボタン (3) をクリックして新しいアプリを追加します。 4. または、[Platformアプリマネージャ] の表メニュー (4) を使用してアプリを承認および有効化することもできます。 #### サーバー認証アプリ #### ユーザー認証アプリ 表示されたポップアップで、開発者が[開発者コンソール](https://app.box.com/developers/console)の [**構成**] タブから収集した、アプリケーションのクライアントIDを入力します。 ## 変更の再承認 アプリケーションのスコープまたはアクセスレベルが変更された場合は、アプリケーションを再承認する必要があります。新しい変更を有効にするには、上記のプロセスを繰り返して新しいアクセストークンをリクエストしてください。 管理者は、アプリケーションが最初に承認されたのと同じセクションで、そのアプリケーションを再承認できます。再承認するには、アプリケーション名の右側にある省略記号をクリックし、[**アプリを再承認**] を選択します。 **Source:** [https://ja.developer.box.com/guides/authorization/platform-app-approval/](https://ja.developer.box.com/guides/authorization/platform-app-approval/) --- ### Postmanコレクション **Type:** guide | **Category:** ツール | **Section:** Developer Guides Postmanコレクション Postmanは、完全な開発環境を構成しなくても、使いやすいインターフェースでHTTPリクエストを作成およびテストできるツールです。Box Postman… # Postmanコレクション [Postman](https://postman.com)は、完全な開発環境を構成しなくても、使いやすいインターフェースでHTTPリクエストを作成およびテストできるツールです。**Box Postmanコレクション**は事前設定済みのリクエストをまとめたもので、これにより、リクエストを手動で設定しなくても、Box APIを利用できるようになります。 Postmanの使用を開始するには、Postmanクイックスタートガイドを使用するのが最も簡単な方法です。 Box Postmanコレクションの使い方 ## 最新のコレクション 下のボタンをクリックすると、最新のPostmanコレクションがフォークされます。これは、すべてのAPIエンドポイントをカバーするPostmanコレクションであり、Boxの[OpenAPIの仕様](https://github.com/box/box-openapi)から自動生成されます。認証を簡単にする更新を含む、より多くの更新が追加される予定です。 **Source:** [https://ja.developer.box.com/guides/tooling/postman/](https://ja.developer.box.com/guides/tooling/postman/) --- ### Postmanとコレクションのインストール **Type:** guide | **Category:** ツール | **Section:** Developer Guides Postmanとコレクションのインストール Box Postmanコレクションを使用するには、デバイスにPostmanがインストールされている必要があります。PostmanはWindows、Mac、およびLinux… # Postmanとコレクションのインストール **Box Postmanコレクション**を使用するには、デバイスに[Postman](https://getpostman.com)がインストールされている必要があります。PostmanはWindows、Mac、およびLinux環境で利用できます。 [お使いのオペレーティングシステムに適切なバージョンのダウンロード](https://www.postman.com/downloads/) 次に、お使いのマシンにPostmanをインストールし、[アカウントを作成してサインインします](https://identity.getpostman.com/signup)。 ## コレクションと環境の読み込み Postmanアプリがインストールされていれば、そのアプリに**Box Postmanコレクション**を読み込むことができます。下のボタンをクリックすると、Postmanに**Box Postmanコレクション**が読み込まれます。 **Source:** [https://ja.developer.box.com/guides/tooling/postman/install/](https://ja.developer.box.com/guides/tooling/postman/install/) --- ### Postmanのインストール **Type:** quick-start | **Category:** ツール | **Section:** Developer Guides Postmanのインストール Box Postmanコレクションを使用するには、デバイスにPostmanアプリがインストールされている必要があります。PostmanはWindows、Mac、およびLinux… # Postmanのインストール **Box Postmanコレクション**を使用するには、デバイスに[Postman](https://getpostman.com)アプリがインストールされている必要があります。PostmanはWindows、Mac、およびLinux環境で利用できます。 [お使いのオペレーティングシステムに適切なバージョンのダウンロード](https://www.postman.com/downloads/) 次に、お使いのマシンにPostmanをインストールし、(必要に応じて) [Postmanアカウントを登録してログインします](https://identity.getpostman.com/signup)。 ## まとめ - Postmanのインストールが完了しました - Postmanアカウントを作成しました (必要な場合) - Postmanアカウントを使用してPostmanアプリケーションにログインしました。 Postmanのインストールが完了しました **Source:** [https://ja.developer.box.com/guides/tooling/postman/quick-start/install-postman/](https://ja.developer.box.com/guides/tooling/postman/quick-start/install-postman/) --- ### Postmanを使用したAPIコール **Type:** quick-start | **Category:** ツール | **Section:** Developer Guides Postmanを使用したAPIコール Postmanは、完全な開発環境を構成しなくても、使いやすいインターフェースでHTTPリクエストを作成およびテストできるツールです。Box Postman… # Postmanを使用したAPIコール [Postman](https://getpostman.com)は、完全な開発環境を構成しなくても、使いやすいインターフェースでHTTPリクエストを作成およびテストできるツールです。Box Postmanコレクションは事前設定済みのリクエストをまとめたもので、これにより、リクエストを手動で設定しなくても、PostmanでBox APIを利用できるようになります。 ## 概要 このガイドでは、以下の手順を説明します。 1. デバイスに[Postmanをインストール](g://tooling/postman/quick-start/install-postman)する。 2. PostmanからBox APIにアクセスできるように[Boxアプリを設定](g://tooling/postman/quick-start/configure-box-app)する。 3. Boxアプリに[ログイン](g://tooling/postman/quick-start/log-in-to-box)して適切なAPI資格情報を取得する。 4. Postmanに[BoxのPostmanコレクションをフォーク](g://tooling/postman/quick-start/load-postman-collection)する。 5. Postmanを使用してBox APIへの[最初のAPIコールを実行](g://tooling/postman/quick-start/make-api-call)する。 開始する準備ができました **Source:** [https://ja.developer.box.com/guides/tooling/postman/quick-start/](https://ja.developer.box.com/guides/tooling/postman/quick-start/) --- ### Python SDK (Generated) のインストール **Type:** guide | **Category:** ツール | **Section:** Developer Guides Python SDK (Generated) のインストール Pythonプロジェクトでは、自動生成されたBox Python SDKを使用してBox APIを呼び出すことができます。この次世代のSDKには、開発者エクスペリエンスを向上させ、Box… # Python SDK (Generated) のインストール Pythonプロジェクトでは、**自動生成された**Box Python SDKを使用してBox APIを呼び出すことができます。この[次世代のSDK](g://tooling/sdks#next-generation-sdks)には、開発者エクスペリエンスを向上させ、Boxコンテンツクラウドとの統合を効率化することを目的とした新機能が備わっています。 GitHubで自動生成されたPython SDKの詳細を確認する ## インストール 自動生成されたPython SDKをインストールするには、[pip](https://pypi.org/project/pip/)を使用してターミナルウィンドウまたはコマンドプロンプトから以下のコマンドを実行します。 ``` pip install box-sdk-gen ``` ## JWTアプリケーション サーバー側[JWT認証](g://authentication/jwt)を使用するBoxアプリを使用する場合、次の追加モジュールをインストールします。 ``` pip install "box-sdk-gen[jwt]" ``` **Source:** [https://ja.developer.box.com/guides/tooling/sdks/python-gen/](https://ja.developer.box.com/guides/tooling/sdks/python-gen/) --- ### Python SDK (公式サポート終了) のインストール **Type:** guide | **Category:** ツール | **Section:** Developer Guides Python SDK (公式サポート終了) のインストール Pythonプロジェクトでは、Box Python SDKを使用してBox APIを呼び出すことができます。 Python SDK… # Python SDK (公式サポート終了) のインストール Pythonプロジェクトでは、Box Python SDKを使用してBox APIを呼び出すことができます。 [Python SDK](https://github.com/box/box-python-sdk)は、現在メンテナンスモードであり、まもなく公式サポートが終了する予定です。つまり、実装されるのは重要なセキュリティ更新プログラムとバグ修正のみになります。[自動生成されたPython SDK](g://tooling/sdks/python-gen)を使用することをお勧めします。 GitHubでPython SDKの詳細を確認する ## インストール Python SDKをインストールするには、[pip](https://pypi.org/project/pip/)を使用してターミナルウィンドウまたはコマンドプロンプトから以下のコマンドを実行します。 ``` pip install boxsdk ``` ## JWTアプリケーション サーバー側[JWT認証](g://authentication/jwt)を使用するBoxアプリを使用する場合、次の追加モジュールをインストールします。 ``` pip install "boxsdk[jwt]" ``` **Source:** [https://ja.developer.box.com/guides/tooling/sdks/python/](https://ja.developer.box.com/guides/tooling/sdks/python/) --- ### Salesforce Developer Toolkit **Type:** guide | **Category:** ツール | **Section:** Developer Guides Salesforce Developer Toolkit Salesforce Developer Toolkitを使用すると、Box for Salesforce統合の動作をプログラムによりカスタマイズできます。このツールキットに含まれる複数のグローバルAPEX… # Salesforce Developer Toolkit Salesforce Developer Toolkitを使用すると、Box for Salesforce統合の動作をプログラムによりカスタマイズできます。このツールキットに含まれる複数のグローバルAPEXメソッドを使用して、デフォルトの動作をトリガーしたり、拡張したりできます。このグローバルメソッドにより、内部のSalesforceレコードとBoxフォルダのマッピングを更新し、権限の管理を処理できます。 この機能は最新のBox for [Salesforceパッケージ](https://support.box.com/hc/ja/articles/360044195713-Box-for-Salesforce%E3%81%AE%E3%82%A4%E3%83%B3%E3%82%B9%E3%83%88%E3%83%BC%E3%83%AB%E3%81%A8%E8%A8%AD%E5%AE%9A)に含まれています。 # このツールキットに含まれない機能 このツールキットは、BOX Content API用のフル機能を備えたAPEXラッパーではありません。このようなラッパーをお求めの場合は、[Box SDK for Salesforce](https://github.com/box/box-salesforce-sdk)を参照してください。 ## 認証 認証を行うには、APIコールでのサービスアカウント資格情報の使用を許可するという方法があります。 この場合、Salesforce管理者がツールキットのグローバルAPEXクラスへのアクセスを制限する必要があります。このような方法を使用することで、Boxのコンテンツとコラボレーションを直接変更できるため、Salesforce管理者はグローバルなツールキットAPEXクラスへのアクセスを制限して、適切な措置を講じる必要があります。 `accessToken`をパラメータとして取得するツールキットメソッドでは、`accessToken`の値として`null`を送信することによって、サービスアカウント資格情報を使用できます。 `accessToken`に値が渡された場合、BoxへのAPIコールは送信されたアクセストークンを使用して行われます。渡されるトークンが有効であるかどうか、およびトークンに関連付けられているユーザーにリクエストされた操作を実行する権限があるかどうかは、開発者が確認する必要があります。 **Source:** [https://ja.developer.box.com/guides/tooling/salesforce-toolkit/](https://ja.developer.box.com/guides/tooling/salesforce-toolkit/) --- ### Salesforce SDKのインストール **Type:** guide | **Category:** ツール | **Section:** Developer Guides Salesforce SDKのインストール Salesforce SDKは、Deploy to Salesforce機能を使用して、サンドボックスまたは開発者組織に直接展開できます。 「Deploy to Salesforce」機能はBox… # Salesforce SDKのインストール Salesforce SDKは、Deploy to Salesforce機能を使用して、サンドボックスまたは開発者組織に直接展開できます。 「Deploy to Salesforce」機能はBoxが所有または管理する機能ではありません。 このSDKは、以下の非管理型パッケージとしても配布されています。 - [実稼働環境/開発者パッケージ](https://cloud.box.com/Box-Apex-SDK) - [サンドボックスパッケージ](https://cloud.box.com/Box-Apex-SDK-Sandbox) 非管理型パッケージは、Salesforce組織にインストールするとアップグレードできなくなります。そのため、以後のアップグレードは、リポジトリをローカルで複製してIDEからクラスを更新することにより適用する必要があります。 **Source:** [https://ja.developer.box.com/guides/tooling/sdks/salesforce/](https://ja.developer.box.com/guides/tooling/sdks/salesforce/) --- ### SalesforceのUI Elements **Type:** guide | **Category:** ツール | **Section:** Developer Guides SalesforceのUI Elements Box for Salesforce管理パッケージでは、Content Picker、エクスプローラ、プレビュー、アップローダーのUI ElementsがLightningコンポーネントとして提供されます。これらのUI… # SalesforceのUI Elements Box for Salesforce管理パッケージでは、[Content Picker](g://embed/ui-elements/picker)、[エクスプローラ](g://embed/ui-elements/explorer)、[プレビュー](g://embed/ui-elements/preview)、[アップローダー](g://embed/ui-elements/uploader)の[UI Elements](g://embed/ui-elements)がLightningコンポーネントとして提供されます。これらのUI ElementsはLightningページまたはLightningフローで使用できます。 ## Content Picker Box for SalesforceのPickerで使用できる[オプション](g://embed/ui-elements/picker/#options)は以下のとおりです。 - `folderId` - Lightningコンポーネントがレコードページにある場合は、デフォルトでレコードフォルダになります - `chooseButtonLabel` - `cancelButtonLabel` - `canSetShareAccess` - `canCreateNewFolder` - `canUpload` - `maxSelectable` ## コンテンツエクスプローラ Box for Salesforceのエクスプローラで使用できる[オプション](g://embed/ui-elements/explorer/#options)は以下のとおりです。 - `folderId` - Lightningコンポーネントがレコードページにある場合は、デフォルトでレコードフォルダになります - `canSetShareAccess` - `canCreateNewFolder` - `canUpload` - `canPreview` - `canDownload` - `canDelete` - `canRename` - `canShare` ## コンテンツプレビュー Box for Salesforceのプレビューで使用できる[オプション](g://embed/ui-elements/preview/#options)は以下のとおりです。 - `fileId` ([ファイルIDの確認](g://files/get)) - **ファイルIDのAPIフィールド名** - Salesforce固有。レコードページでは、表示するファイルIDを保持するAPIフィールド名を使用できます ## コンテンツアップローダー Box for Salesforceのアップローダーで使用できる[オプション](g://embed/ui-elements/uploader/#options)は以下のとおりです。 - `folderId` - Lightningコンポーネントがレコードページにある場合は、デフォルトでレコードフォルダになります - `fileLimit` **Source:** [https://ja.developer.box.com/guides/tooling/salesforce-toolkit/ui-elements/](https://ja.developer.box.com/guides/tooling/salesforce-toolkit/ui-elements/) --- ### SDK **Type:** guide | **Category:** ツール | **Section:** Developer Guides SDK Boxには、アプリケーションの作成に使用できる一連のSDKが用意されています。次世代の.NET SDKもここに新しく追加されました。これはまだベータ機能ですが、試しに使用して、備わっているすべての機能を確認することができます。 下の表には、SDK… # SDK Boxには、アプリケーションの作成に使用できる一連のSDKが用意されています。次世代の.NET SDKもここに新しく追加されました。これはまだベータ機能ですが、試しに使用して、備わっているすべての機能を確認することができます。 下の表には、SDKが、プロジェクトがメンテナンスされるかどうかとAPIパリティが備わっているかどうかを示す追加情報とともに記載されています。 **メンテナンス**: Boxでは、完全にメンテナンスされるプロジェクトを積極的に開発しています。このようなプロジェクトには最新のセキュリティ更新プログラムや新機能が提供されます。このようなプロジェクトのサポートについては、GitHubまたは[Developer Forum](https://support.box.com/hc/ja/community/topics/360001932973-Platform-and-Developer-Forum)を参照してください。 **APIパリティ**: 完全なAPIパリティを持つプロジェクトは、Box Platformで利用可能になった時点で、すべてのプラットフォーム機能が積極的に更新されます。部分的なAPIパリティを持つプロジェクトには一部の機能が欠けていますが、Boxではそのようなプロジェクトを完全なパリティに移行する取り組みを進めています。 ## 次世代のSDK 最新世代のBox Python SDK、Box TypeScript SDK、.NET SDK、Swift SDKは、開発者エクスペリエンスを向上させ、Boxコンテンツクラウドとの統合を効率化することを目的としています。 Swift SDKはパブリックベータ段階です。 新しいSDKに実装予定の機能を以下に示します。 - **APIの全面的なサポート**: 新しいBox SDKにより、開発者はBox APIエコシステム全体をカバーできるようになります。Boxが提供する最新機能をすべて利用して、機能豊富なアプリケーションを作成できます。 - **迅速なAPIの更新**: 自動生成による新しい開発アプローチにより、SDKへのBox APIの追加がさらに速いペースで (数日中に) 可能になります。これは、最新の機能をすぐにアプリケーションで利用できるようになることを意味します。 - **ドキュメントへの埋め込み**: 必要な情報すべてが1か所に保存されるように、すべてのオブジェクトおよびパラメータはSDKのソースコードに直接記述されます。 - **便利なメソッドの強化**: 新しく導入された便利なメソッドは、認証、分割アップロード、指数バックオフ、自動再試行、型チェック (変数を正しく使用しているかどうかの確認に役立ちます) など、さまざまな側面をカバーします。 任意のプログラミング言語の**Box Platform** SDKをダウンロードして開始します。 | プラットフォーム | メンテナンスの有無 | APIパリティ | | --- | --- | --- | | Pythonの次世代SDK | はい | Full | | TypeScriptの次世代SDK | はい | Full | | .NETの次世代SDK | はい | Full | | Swiftの次世代SDK (ベータ) | はい | Full | | Javaの次世代SDK (ベータ) | はい | Full | ## 従来のSDK 次の表に、アプリケーションの作成時に使用できる従来のBox SDKを示します。最新のAPIサポートや機能には、次世代のSDKを使用してください。 | プラットフォーム | メンテナンスの有無 | APIパリティ | | --- | --- | --- | | Java SDK | はい | Full | | iOS Content SDK | はい | Full | | Android Content SDK | いいえ | 部分的 | | .NET SDK | 公式サポート終了。重要なセキュリティ更新プログラムとバグ修正のみ実装されます。 | Full | | Python SDK | 公式サポート終了。重要なセキュリティ更新プログラムとバグ修正のみ実装されます。 | Full | | Node SDK | 公式サポート終了。重要なセキュリティ更新プログラムとバグ修正のみ実装されます。 | Full | 日本時間2023年6月1日をもって、Android SDKのサポートは終了しました。既存のAndroid SDKアプリケーションは影響なく引き続きご利用いただけますが、新機能、更新、バグ修正は提供されなくなります。 最新のAndroid機能を引き続き利用するには、Java SDKを使用してAndroid版アプリを作成してください。詳細については、[こちら](https://github.com/box/box-java-sdk/blob/main/doc/android.md)のドキュメントを参照してください。 **Source:** [https://ja.developer.box.com/guides/tooling/sdks/](https://ja.developer.box.com/guides/tooling/sdks/) --- ### SDKでの使用 **Type:** guide | **Category:** 認証 | **Section:** Developer Guides SDKでの使用 SDKではJWTおよびOAuth 2.0認証を直接サポートしていますが、場合によっては、アプリケーションがSDKに直接アクセストークンを提供しなければならないこともあります。 開発者トークン 開発者トークンも同様に、追加のSDK構成を必要することなく、直接SDK… # SDKでの使用 SDKではJWTおよびOAuth 2.0認証を直接サポートしていますが、場合によっては、アプリケーションがSDKに直接アクセストークンを提供しなければならないこともあります。 ## 開発者トークン 開発者トークンも同様に、追加のSDK構成を必要することなく、直接SDKで使用できます。 ## アプリトークン アプリトークン認証を使用すると、アプリトークンを直接SDKに渡すことができます。 **Source:** [https://ja.developer.box.com/guides/authentication/tokens/sdks/](https://ja.developer.box.com/guides/authentication/tokens/sdks/) --- ### SDKによる分割アップロード **Type:** guide | **Category:** アップロード | **Section:** Developer Guides SDKによる分割アップロード Box SDKにより、組み込みメソッドを使用して分割アップロードを実行できるようになります。 また、同様の方法によるファイルの新しいバージョンのアップロードもサポートされます。 # SDKによる分割アップロード Box SDKにより、組み込みメソッドを使用して分割アップロードを実行できるようになります。 また、同様の方法によるファイルの新しいバージョンのアップロードもサポートされます。 **Source:** [https://ja.developer.box.com/guides/uploads/chunked/with-sdks/](https://ja.developer.box.com/guides/uploads/chunked/with-sdks/) --- ### SDKを使用したJWT **Type:** guide | **Category:** 認証 | **Section:** Developer Guides SDKを使用したJWT Box公式SDKには、JWT認証のサポートが組み込まれています。 このガイドでは、Box SDKを使用したJWTによるユーザー認証について説明します。JWT認証はBox API… # SDKを使用したJWT Box公式SDKには、JWT認証のサポートが組み込まれています。 このガイドでは、Box SDKを使用したJWTによるユーザー認証について説明します。JWT認証はBox APIを直接操作するよう設計されており、ユーザーがアプリケーションを承認するためにBoxを介してリダイレクトする必要はありません。 ## 概要 JWT承認を完了するには、以下の手順を完了する必要があります。 1. 構成ファイルを読み取る 2. SDKクライアントを初期化する このフローが終了すると、アプリケーションには、アプリケーションの代わりにAPIコールを実行するために使用できるBox SDKクライアントが用意されます。 JWTを使用したデフォルトの認証方法は、もともとアプリケーションのサービスアカウントに関連付けられています。このトークンを使用して実行されるAPIコールはどれも、このアプリケーションから実行されているように見えますが、明示的なアクセス権がなければ他のユーザーのファイルやフォルダにはアクセスできません。 ## 前提条件 開始する前に、以下の手順を完了しておく必要があります。 - 開発者コンソール内でBoxアプリケーションを作成する - アプリケーション用に秘密キーの構成ファイルを作成してダウンロードし、`config.json`として保存する - 社内で使用するためにBoxアプリケーションが承認されていることを確認する ## 1. JSON構成を読み取る Boxアプリケーションを作成すると、アプリケーションの秘密キーとその他の詳細を含む`config.json`ファイルも作成されます。以下に、その例を示します。 ``` { "boxAppSettings": { "clientID": "abc...123", "clientSecret": "def...234", "appAuth": { "publicKeyID": "abcd1234", "privateKey": "-----BEGIN ENCRYPTED PRIVATE KEY-----\n....\n-----END ENCRYPTED PRIVATE KEY-----\n", "passphrase": "ghi...345" } }, "enterpriseID": "1234567" } ``` このオブジェクトをアプリケーションで使用するには、ファイルから読み取る必要があります。 ``` var reader = new StreamReader("path/to/config.json"); var json = reader.ReadToEnd(); var config = BoxConfig.CreateFromJsonString(json); ``` ``` Reader reader = new FileReader("path/to/config.json"); BoxConfig config = BoxConfig.readFrom(reader); ``` ``` from boxsdk import JWTAuth config = JWTAuth.from_settings_file('path/to/config.json') ``` ``` var config = require("path/to/config.json"); ``` # JSONの解析 プログラミング言語によっては、ファイルからJSONを読み取って解析する方法が複数ある場合があります。エラー処理など、さらに詳細な説明については、使用するプログラミング言語のガイドを参照してください。 ## 2. SDKクライアントを初期化する 次の手順では、作成した構成を使用してBox SDKを構成し、アプリケーションとして接続するためにクライアントを初期化します。 ``` var sdk = new BoxJWTAuth(config); var token = sdk.AdminToken(); BoxClient client = sdk.AdminClient(token); ``` ``` BoxDeveloperEditionAPIConnection api = BoxDeveloperEditionAPIConnection.getAppEnterpriseConnection(config); ``` ``` client = Client(config) ``` ``` var sdk = BoxSDK.getPreconfiguredInstance(config); var client = sdk.getAppAuthClient("enterprise"); ``` # サービスアカウント この時点では、アプリケーションは、管理対象ユーザーまたはApp Userとしてではなく、アプリケーションユーザーとして認証されます。各種ユーザーの詳細については、[ユーザータイプ](page://platform/user-types)に関するガイドをご覧ください。 ## まとめ 以下の手順に従うことで、アプリケーションはBox公式SDKのいずれかにより、JWTを使用したアプリケーションの承認を実行できるようになりました。 1. 構成ファイルを読み取る 2. SDKクライアントを初期化する このクライアントの使用方法を確認するには、[APIコールの実行](g://api-calls)に関するガイドをご覧ください。 ## SDKとJSONウェブトークンの使用 各SDKのJWTの詳細については、以下を参照してください。 [.Net](https://github.com/box/box-windows-sdk-v2/blob/main/docs/authentication.md#server-auth-with-jwt) [Java](https://github.com/box/box-java-sdk/blob/main/doc/authentication.md#server-authentication-with-jwt) [Python](https://github.com/box/box-python-sdk/blob/main/docs/usage/authentication.md#server-auth-with-jwt) [Node](https://github.com/box/box-node-sdk/blob/main/docs/authentication.md#server-auth-with-jwt) [IOS](https://github.com/box/box-ios-sdk/blob/main/docs/usage/authentication.md#server-auth-with-jwt) **Source:** [https://ja.developer.box.com/guides/authentication/jwt/with-sdk/](https://ja.developer.box.com/guides/authentication/jwt/with-sdk/) --- ### SDKを使用したOAuth 2.0 **Type:** guide | **Category:** 認証 | **Section:** Developer Guides SDKを使用したOAuth 2.0 Box SDKには、クライアント側OAuth 2.0のサポートが組み込まれています。 このプロセスでは、ユーザーはブラウザでBox… # SDKを使用したOAuth 2.0 Box SDKには、クライアント側OAuth 2.0のサポートが組み込まれています。 このプロセスでは、ユーザーはブラウザでBoxウェブアプリにリダイレクトされます。そこで、ユーザーはログインし、アプリケーションによる自分のデータへのアクセスを承認すると、アプリケーションの`redirect_url`に再度リダイレクトされます。この最後の手順では、ユーザーがアクセス可能な場所にあるウェブサーバー上でアプリケーションが実行されている必要があります。 ## 概要 OAuth 2.0フローを完了するには、以下の手順を完了する必要があります。 1. Box SDKを構成する 2. ユーザーをBoxウェブサイトにリダイレクトする 3. ユーザーがアプリケーションにアクセス権限を付与する 4. 承認コードをアクセストークンと交換する このフローが終了すると、アプリケーションには、このユーザーの代わりにAPIコールを実行するために使用できるアクセストークンが用意されます。 OAuth 2.0を介して取得したアクセストークンは、もともとアプリケーションを承認したユーザーに関連付けられています。このトークンを使用して実行されるAPIコールはどれも、このアプリケーションから実行されているように見えるため、ユーザーには、アプリケーションがこのトークンを使用してアクセスしようとするファイルやフォルダへのアクセス権限が必要です。 ## パラメータ | パラメータ | 説明 | | --- | --- | | CLIENT_ID | アプリケーションのクライアントIDまたはAPIキー | | CLIENT_SECRET | アプリケーションのクライアントシークレットまたはAPIシークレット | | REDIRECT_URI | ユーザーがアプリケーションを承認した後に送信されるアプリケーションのリダイレクトURL。これは開発者コンソールで構成できます。 | ## 1. SDKを構成する 最初の手順として、選択したSDKを使用して環境が準備されていることを確認します。 ``` var redirectUrl = "[REDIRECT_URI]"; var config = new BoxConfig("[CLIENT_ID]", "[CLIENT_SECRET]", new Uri(redirectUrl)); var sdk = new BoxClient(config); ``` ``` import com.box.sdk.BoxAPIConnection; String authorizationUrl = "https://account.box.com/api/oauth2/authorize?client_id=[CLIENT_ID]&response_type=code"; ``` ``` from boxsdk import OAuth2, Client auth = OAuth2( client_id='[CLIENT_ID]', client_secret='[CLIENT_SECRET]' ) ``` ``` var BoxSDK = require("box-node-sdk"); var sdk = new BoxSDK({ clientID: "[CLIENT_ID]", clientSecret: "[CLIENT_SECRET]", }); ``` ご利用の環境に合わせたSDKのインストールの詳細を確認する ## 2. ユーザーをリダイレクトする 次に、承認URLにユーザーをリダイレクトします。ほとんどのSDKでは、SDKクライアントの承認URLを取得する方法をサポートしています。 アプリケーション用にリダイレクトURIを複数設定した場合、承認URLには、開発者コンソールで設定したURIのいずれかと一致する`redirect_uri`パラメータを含める必要があります。このパラメータが指定されていない場合、ユーザーがアプリケーションにアクセス権限を付与すると、`redirect_uri_missing`エラーが表示され、アプリにリダイレクトされません。 ``` var authorizationUrl = "https://account.box.com/api/oauth2/authorize?client_id=[CLIENT_ID]&response_type=code"; // redirectTo(authorizationUrl); ``` ``` String authorizationUrl = "https://account.box.com/api/oauth2/authorize?client_id=[CLIENT_ID]&response_type=code"; // response.redirect(authorizationUrl); ``` ``` auth_url, csrf_token = auth.get_authorization_url('[REDIRECT_URL]') // redirect(auth_url, code=302) ``` ``` var authorize_url = sdk.getAuthorizeURL({ response_type: "code", }); // res.redirect(authorize_url) ``` ユーザーがURLにリダイレクトされる方法は、使用されるアプリケーションフレームワークによって異なります。このトピックの詳細については、ほとんどのフレームワークのドキュメントで説明されています。 [承認URL](endpoint://get-authorize)は、以下のように手動でも作成できます。 ``` https://account.box.com/api/oauth2/authorize?client_id=[CLIENT_ID]&redirect_uri=[REDIRECT_URI]&response_type=code ``` スコープを制限したり追加の状態を渡したりするためにユーザーをリダイレクトするときに、追加のクエリパラメータを渡すことができます。詳細については、[リファレンスドキュメント](endpoint://get-authorize)を参照してください。 Boxインスタンスの[Box Verified Enterprise](https://support.box.com/hc/ja/articles/360043693554-Box-Verified-Enterprise%E3%81%A8%E3%82%B5%E3%83%9D%E3%83%BC%E3%83%88%E5%AF%BE%E8%B1%A1%E3%81%AE%E3%82%A2%E3%83%97%E3%83%AA)が有効になっている場合、標準的な`account.box.com`というベースURLを使用する際に問題が発生することがあります。`account.box.com`の代わりに`ent.box.com`を使用してください。 ## 3. ユーザーがアプリケーションにアクセス権限を付与する ユーザーはBoxウェブアプリにリダイレクトされると、ログインする必要があります。ログイン後、ユーザーにはアプリケーションを承認するための画面が表示されます。 ユーザーがこのリクエストを承認し、ボタンをクリックすると、ブラウザは、開発者コンソールで構成されたとおりにアプリケーションのリダイレクトURLにリダイレクトされます。 ## 4. コードを交換する ユーザーは、有効期間の短い承認コードを含むクエリパラメータが指定されたアプリケーションのリダイレクトURLにリダイレクトされます。 ``` https://your.domain.com/path?code=1234567 ``` このコードは[アクセストークン](g://authentication/tokens/access-tokens)ではなく、有効期間はほんの数秒です。SDKを使用すると、このコードを実際のアクセストークンと交換できます。 ``` var session = await sdk.Auth.AuthenticateAsync("[CODE]"); var client = new BoxClient(config, session); ``` ``` BoxAPIConnection client = new BoxAPIConnection( "[CLIENT_ID]", "[CLIENT_SECRET]", "[CODE]" ); ``` ``` auth.authenticate('[CODE]') client = Client(auth) ``` ``` var code = "..."; sdk.getTokensAuthorizationCodeGrant("[CODE]", null, function (err, tokenInfo) { var client = sdk.getPersistentClient(tokenInfo); }); ``` このフローが終了すると、アプリケーションには、このユーザーの代わりにAPIコールを実行するために使用できるアクセストークンが用意されます。 ## SDKとOAuth 2.0の使用 各SDKのOAuth 2.0認証の詳細については、以下を参照してください。 [.Net](https://github.com/box/box-windows-sdk-v2/blob/main/docs/authentication.md#traditional-3-legged-oauth2) [Java](https://github.com/box/box-java-sdk/blob/main/doc/authentication.md#standard-3-legged-oauth-20) [Python](https://github.com/box/box-python-sdk/blob/main/docs/usage/authentication.md#traditional-3-legged-oauth2) [Node](https://github.com/box/box-node-sdk/blob/main/docs/authentication.md#traditional-3-legged-oauth2) [IOS](https://github.com/box/box-ios-sdk/blob/main/docs/usage/authentication.md#traditional-3-legged-oauth2) **Source:** [https://ja.developer.box.com/guides/authentication/oauth2/with-sdk/](https://ja.developer.box.com/guides/authentication/oauth2/with-sdk/) --- ### SDKを使用したアプリトークン **Type:** guide | **Category:** 認証 | **Section:** Developer Guides SDKを使用したアプリトークン Box公式SDKには、アプリトークン認証のサポートが組み込まれています。 アプリトークン認証は、Box APIを直接操作するよう設計されており、ユーザーがアプリケーションを承認するためにBox… # SDKを使用したアプリトークン Box公式SDKには、アプリトークン認証のサポートが組み込まれています。 アプリトークン認証は、Box APIを直接操作するよう設計されており、ユーザーがアプリケーションを承認するためにBoxを介してリダイレクトする必要はありません。ただし、この認証はアプリケーションのデータのみに制限されています。 JWTを使用した認証方法は、もともとアプリケーションのサービスアカウントに関連付けられています。このトークンを使用して実行されるAPIコールはどれも、このアプリケーションから実行されているように見えますが、明示的なアクセス権がなければ他のユーザーのファイルやフォルダにはアクセスできません。 ## 前提条件 開始する前に、以下の手順を完了しておく必要があります。 - 開発者コンソール内でBoxアプリケーションを作成する - アプリケーションがアプリトークン認証を使用するよう構成されていることを確認する - アプリケーションのプライマリアプリトークンとセカンダリアプリトークンを生成し、コード内のどこかにこれらのトークンを保存する ## SDKクライアントの初期化 アプリトークン認証のためにSDKクライアントを初期化するには、SDKがインストールされていることを確認してから、以下のようにSDKを構成します。 ``` var config = new BoxConfig("[CLIENT_ID]", "", new Uri("http://localhost")); var session = new OAuthSession("[APP_TOKEN]", "N/A", 3600, "bearer"); var client = new BoxClient(config, session); ``` ``` BoxTransactionalAPIConnection api = new BoxTransactionalAPIConnection("[APP_TOKEN]"); ``` ``` from boxsdk import Client, OAuth2 auth = OAuth2(access_token='[APP_TOKEN]') client = Client(auth) ``` ``` var BoxSDK = require('box-node-sdk'); var sdk = new BoxSDK({ clientID: '[CLIENT_ID]', clientSecret: '' }); var client = sdk.getBasicClient('[APP_TOKEN]'); ``` これを使用すると、アプリケーションは、アプリトークン認証に対して有効になっている[エンドポイント](g://authentication/app-token/endpoints)のいずれかにAPIコールを実行できます。 ## SDKとアプリケーショントークンの使用 各SDKのアプリケーショントークンの詳細については、以下を参照してください。 [.Net](https://github.com/box/box-windows-sdk-v2/blob/main/docs/authentication.md#box-view-authentication-with-app-tokens) [Java](https://github.com/box/box-java-sdk/blob/main/doc/authentication.md#box-view-authentication-with-app-token) [Python](https://github.com/box/box-python-sdk/blob/main/docs/usage/authentication.md#box-view-authentication-with-app-tokens) [Node](https://github.com/box/box-node-sdk/blob/main/docs/authentication.md#box-view-authentication-with-app-tokens) **Source:** [https://ja.developer.box.com/guides/authentication/app-token/with-sdk/](https://ja.developer.box.com/guides/authentication/app-token/with-sdk/) --- ### SDKを使用したフォルダ内のすべてのファイルのダウンロード **Type:** guide | **Category:** ダウンロード | **Section:** Developer Guides SDKを使用したフォルダ内のすべてのファイルのダウンロード アプリケーションによっては、1つのフォルダのすべてのファイルをダウンロードできる場合もあります。SDKとCLI… # SDKを使用したフォルダ内のすべてのファイルのダウンロード アプリケーションによっては、1つのフォルダのすべてのファイルをダウンロードできる場合もあります。SDKとCLIを使用してこの処理を実行するには、フォルダツリー内を移動してすべてのファイルを探し、そのファイルをダウンロードする必要があります。 ZIPアーカイブをダウンロードするには、[こちら](g://downloads/zip-archive)のガイドに従ってください。 ``` using System; using System.Collections.Generic; using System.IO; using System.Linq; using System.Threading.Tasks; using Box.V2.Config; using Box.V2.JWTAuth; namespace BoxDownloadAllFiles { class Program { static void Main (string[] args) { ExecuteMainAsync ().Wait (); } private static async Task ExecuteMainAsync () { using (FileStream fs = new FileStream ($"./config.json", FileMode.Open)) { var session = new BoxJWTAuth (BoxConfig.CreateFromJsonFile (fs)); var client = session.AdminClient (session.AdminToken ()); var folderId = "987654321"; var folder = await client.FoldersManager.GetInformationAsync (folderId); var folderName = folder.Name; var localFolderPath = Path.Combine (Directory.GetCurrentDirectory (), folderName); ResetLocalFolder (localFolderPath); var items = await client.FoldersManager.GetFolderItemsAsync (folderId, 1000, autoPaginate : true); var fileDownloadTasks = new List<Task> (); var files = items.Entries.Where (i => i.Type == "file"); foreach (var file in files) { fileDownloadTasks.Add (client.FilesManager.DownloadStreamAsync (file.Id).ContinueWith ((t) => { var localFile = File.Create (Path.Combine (localFolderPath, file.Name)); return t.Result.CopyToAsync (localFile); })); } await Task.WhenAll (fileDownloadTasks); } } private static void ResetLocalFolder (string localFolderPath) { if (!Directory.Exists (localFolderPath)) { Directory.CreateDirectory (localFolderPath); } else { foreach (var file in Directory.EnumerateFiles (localFolderPath)) { File.Delete (Path.Combine (localFolderPath, file)); } Directory.Delete (localFolderPath); Directory.CreateDirectory (localFolderPath); } } } } ``` ``` package com.box; import com.box.sdk.BoxConfig; import com.box.sdk.BoxDeveloperEditionAPIConnection; import com.box.sdk.BoxFile; import com.box.sdk.BoxFolder; import com.box.sdk.BoxItem; import java.io.BufferedReader; import java.io.FileOutputStream; import java.io.IOException; import java.nio.charset.Charset; import java.nio.file.Files; import java.nio.file.Path; import java.nio.file.Paths; public class Playground { public static void main(String[] args) throws Exception { Path configPath = Paths.get("config.json"); Path currentDir = Paths.get("").toAbsolutePath(); try (BufferedReader reader = Files.newBufferedReader(configPath, Charset.forName("UTF-8"))) { BoxConfig boxConfig = BoxConfig.readFrom(reader); BoxDeveloperEditionAPIConnection client = BoxDeveloperEditionAPIConnection.getAppEnterpriseConnection(boxConfig); String folderId = "987654321"; BoxFolder folder = new BoxFolder(client, folderId); String folderName = folder.getInfo().getName(); Path localFolderPath = currentDir.resolve(Paths.get(folderName)); if (!Files.exists(localFolderPath)) { localFolderPath = Files.createDirectory(localFolderPath); } else { localFolderPath = resetLocalFolder(localFolderPath); } for (BoxItem.Info itemInfo: folder) { if (itemInfo instanceof BoxFile.Info) { BoxFile.Info fileInfo = (BoxFile.Info) itemInfo; BoxFile file = new BoxFile(client, fileInfo.getID()); String localFilePath = localFolderPath.resolve(Paths.get(fileInfo.getName())).toAbsolutePath().toString(); FileOutputStream stream = new FileOutputStream(localFilePath); file.download(stream); stream.close(); } } } } static Path resetLocalFolder(Path localFolderPath) throws IOException { Files.list(localFolderPath).forEach(file -> { System.out.println(file.getFileName()); try { Files.delete(file.toAbsolutePath()); } catch (IOException e) {} }); Files.delete(localFolderPath); localFolderPath = Files.createDirectory(localFolderPath); return localFolderPath; } } ``` ``` "use strict"; const box = require("box-node-sdk"); const fs = require("fs"); const util = require("util"); const path = require("path"); let configFile = fs.readFileSync("config.json"); configFile = JSON.parse(configFile); let session = box.getPreconfiguredInstance(configFile); let client = session.getAppAuthClient("enterprise"); client._useIterators = true; let folderId = "987654321"; let folderName; let localFolderPath; client.folders .get(folderId, null) .then(folderInfo => { folderName = folderInfo.name; return client.folders.getItems(folderId, { limit: 1000 }); }) .then(folderItemsIterator => { return autoPage(folderItemsIterator); }) .then(folderItems => { console.log(folderName); console.log(folderItems.length); let files = folderItems.filter(item => { return item.type === "file"; }); console.log(files); localFolderPath = createLocalFolder(folderName); let downloadPromises = []; files.forEach(file => { downloadPromises.push( client.files.getReadStream(file.id, null).then(stream => { let output = fs.createWriteStream( path.join(localFolderPath, file.name) ); stream.pipe(output); }) ); }); return Promise.all(downloadPromises); }) .then(() => { console.log("Downloaded all files..."); console.log(fs.readdirSync(localFolderPath)); }); function createLocalFolder(folderName) { let localFolderName = path.join(__dirname, folderName); try { fs.mkdirSync(localFolderName); } catch (e) { if (e.code === "EEXIST") { resetLocalFolder(localFolderName); fs.mkdirSync(localFolderName); } else { throw e; } } return localFolderName; } function resetLocalFolder(localFolderName) { if (fs.existsSync(localFolderName)) { fs.readdirSync(localFolderName).forEach(localFileName => { console.log(localFileName); fs.unlinkSync(path.join(localFolderName, localFileName)); }); fs.rmdirSync(localFolderName); } } function autoPage(iterator) { let collection = []; let moveToNextItem = () => { return iterator.next().then(item => { if (item.value) { collection.push(item.value); } if (item.done !== true) { return moveToNextItem(); } else { return collection; } }); }; return moveToNextItem(); } ``` アプリケーションには、当該ファイルおよびフォルダにアクセスしてダウンロードするための権限が必要であることに注意してください。認証済みユーザーがいずれのファイルおよびフォルダにもアクセスできない場合は、`HTTP 404 Not Found`エラーが発生します。 認証に関するガイドにある[ユーザータイプ](page://platform/user-types)の詳細をご覧ください。 **Source:** [https://ja.developer.box.com/guides/downloads/folder/](https://ja.developer.box.com/guides/downloads/folder/) --- ### SDKを使用しないJWT **Type:** guide | **Category:** 認証 | **Section:** Developer Guides SDKを使用しないJWT このガイドでは、Box SDKを使用しないJWT認証について説明します。JWTはエンドユーザーによる操作を必要とせず、Box APIで直接認証するよう設計されています。 このトークンの使用方法を確認するには、API… # SDKを使用しないJWT このガイドでは、Box SDKを使用しないJWT認証について説明します。JWTはエンドユーザーによる操作を必要とせず、Box APIで直接認証するよう設計されています。 このトークンの使用方法を確認するには、[APIコールの実行](g://api-calls)に関するガイドを参照してください。 デフォルトでは、JWTを使用して取得したアクセストークンは、アプリケーションのサービスアカウントに関連付けられています。このトークンを使用して実行されるAPIコールはすべて、このアプリケーションから実行されます。アプリケーションのサービスアカウントがコラボレータとして追加されるまで、このアカウントでは、既存のファイルやフォルダにアクセスできません。 `as-user`ヘッダーを使用するか[ユーザーアクセストークン](g://authentication/jwt/user-access-tokens)をリクエストして、[別のユーザーとして処理を実行](g://authentication/oauth2/as-user)できます。 ## キーペアの使用 公開キーと秘密キーのペアを使用してアプリケーションのIDを確認する場合は、以下の手順に従います。 ### 前提条件 - [開発者コンソール](https://app.box.com/developers/console)でJWT認証を使用するPlatformアプリケーション - `config.json`という名前の秘密キー構成ファイル ([開発者コンソール](https://app.box.com/developers/console)の [構成] タブからダウンロード可能) - Box管理コンソールでアプリケーションが[承認](g://authorization)されていること ### 1. JSON構成を読み取る `config.json`ファイルには、アプリケーションの秘密キーと、認証に必要なその他の詳細が含まれています。このファイルの例を以下に示します。 ``` { "boxAppSettings": { "clientID": "abc...123", "clientSecret": "def...234", "appAuth": { "publicKeyID": "abcd1234", "privateKey": "-----BEGIN ENCRYPTED PRIVATE KEY-----\n....\n-----END ENCRYPTED PRIVATE KEY-----\n", "passphrase": "ghi...345" } }, "enterpriseID": "1234567" } ``` このオブジェクトをアプリケーションで使用するには、ファイルから読み取る必要があります。 ``` using System; using System.IO; using Newtonsoft.Json; class Config { public class BoxAppSettings { public class AppAuth { public string privateKey { get; set; } public string passphrase { get; set; } public string publicKeyID { get; set; } } public string clientID { get; set; } public string clientSecret { get; set; } public AppAuth appAuth { get; set; } } public string enterpriseID { get; set; } public BoxAppSettings boxAppSettings { get; set; } } var reader = new StreamReader("config.json"); var json = reader.ReadToEnd(); var config = JsonConvert.DeserializeObject<Config>(json); ``` ``` import java.io.FileReader; import com.google.gson.Gson; import com.google.gson.GsonBuilder; class Config { class BoxAppSettings { class AppAuth { String privateKey; String passphrase; String publicKeyID; } String clientID; String clientSecret; AppAuth appAuth; } BoxAppSettings boxAppSettings; String enterpriseID; } FileReader reader = new FileReader("config.json"); Gson gson = new GsonBuilder().create(); Config config = (Config) gson.fromJson(reader, Config.class); ``` ``` import json import os config = json.load(open('config.json')) ``` ``` const fs = require("fs"); const config = JSON.parse(fs.readFileSync("config.json")); ``` ``` require 'json' config = JSON.parse( File.read('config.json') ) ``` ``` $json = file_get_contents('config.json'); $config = json_decode($json); ``` # JSONの解析 プログラミング言語によっては、ファイルからJSONを読み取って解析する方法が複数ある場合があります。エラー処理など、さらに詳細な説明については、使用するプログラミング言語のガイドを参照してください。 ### 2. 秘密キーを復号化する JWTアサーションを作成するために、アプリケーションでは構成オブジェクトにある秘密キーが必要になります。この秘密キーは暗号化されており、ロックを解除するにはパスコードが必要です。暗号化されたキーとパスコードは両方とも、構成オブジェクトで指定されています。 ``` using System.Security.Cryptography; using Org.BouncyCastle.OpenSsl; using Org.BouncyCastle.Crypto.Parameters; using Org.BouncyCastle.Math; // https://www.bouncycastle.org/csharp/index.html class PasswordFinder : IPasswordFinder { private string password; public PasswordFinder(string _password) { password = _password; } public char[] GetPassword() { return password.ToCharArray(); } } var appAuth = config.boxAppSettings.appAuth; var stringReader = new StringReader(appAuth.privateKey); var passwordFinder = new PasswordFinder(appAuth.passphrase); var pemReader = new PemReader(stringReader, passwordFinder); var keyParams = (RsaPrivateCrtKeyParameters) pemReader.ReadObject(); public RSA CreateRSAProvider(RSAParameters rp) { var rsaCsp = RSA.Create(); rsaCsp.ImportParameters(rp); return rsaCsp; } public RSAParameters ToRSAParameters(RsaPrivateCrtKeyParameters privKey) { RSAParameters rp = new RSAParameters(); rp.Modulus = privKey.Modulus.ToByteArrayUnsigned(); rp.Exponent = privKey.PublicExponent.ToByteArrayUnsigned(); rp.P = privKey.P.ToByteArrayUnsigned(); rp.Q = privKey.Q.ToByteArrayUnsigned(); rp.D = ConvertRSAParametersField(privKey.Exponent, rp.Modulus.Length); rp.DP = ConvertRSAParametersField(privKey.DP, rp.P.Length); rp.DQ = ConvertRSAParametersField(privKey.DQ, rp.Q.Length); rp.InverseQ = ConvertRSAParametersField(privKey.QInv, rp.Q.Length); return rp; } public byte[] ConvertRSAParametersField(BigInteger n, int size) { byte[] bs = n.ToByteArrayUnsigned(); if (bs.Length == size) return bs; if (bs.Length > size) throw new ArgumentException("Specified size too small", "size"); byte[] padded = new byte[size]; Array.Copy(bs, 0, padded, size - bs.Length, bs.Length); return padded; } var key = CreateRSAProvider(ToRSAParameters(keyParams)); ``` ``` import java.io.StringReader; import java.security.PrivateKey; import java.security.Security; import org.bouncycastle.asn1.pkcs.PrivateKeyInfo; import org.bouncycastle.jce.provider.BouncyCastleProvider; import org.bouncycastle.openssl.PEMParser; import org.bouncycastle.openssl.jcajce.JcaPEMKeyConverter; import org.bouncycastle.openssl.jcajce.JceOpenSSLPKCS8DecryptorProviderBuilder; import org.bouncycastle.operator.InputDecryptorProvider; import org.bouncycastle.pkcs.PKCS8EncryptedPrivateKeyInfo; // https://www.bouncycastle.org/java.html Security.addProvider(new BouncyCastleProvider()); PEMParser pemParser = new PEMParser( new StringReader(config.boxAppSettings.appAuth.privateKey) ); Object keyPair = pemParser.readObject(); pemParser.close(); char[] passphrase = config.boxAppSettings.appAuth.passphrase.toCharArray(); JceOpenSSLPKCS8DecryptorProviderBuilder decryptBuilder = new JceOpenSSLPKCS8DecryptorProviderBuilder().setProvider("BC"); InputDecryptorProvider decryptProvider = decryptBuilder.build(passphrase); PrivateKeyInfo keyInfo = ((PKCS8EncryptedPrivateKeyInfo) keyPair).decryptPrivateKeyInfo(decryptProvider); PrivateKey key = (new JcaPEMKeyConverter()).getPrivateKey(keyInfo); ``` ``` from cryptography.hazmat.backends import default_backend from cryptography.hazmat.primitives.serialization import load_pem_private_key appAuth = config["boxAppSettings"]["appAuth"] privateKey = appAuth["privateKey"] passphrase = appAuth["passphrase"] # https://cryptography.io/en/latest/ key = load_pem_private_key( data=privateKey.encode('utf8'), password=passphrase.encode('utf8'), backend=default_backend(), ) ``` ``` let key = { key: config.boxAppSettings.appAuth.privateKey, passphrase: config.boxAppSettings.appAuth.passphrase, }; ``` ``` require "openssl" appAuth = config['boxAppSettings']['appAuth'] key = OpenSSL::PKey::RSA.new( appAuth['privateKey'], appAuth['passphrase'] ) ``` ``` $private_key = $config->boxAppSettings->appAuth->privateKey; $passphrase = $config->boxAppSettings->appAuth->passphrase; $key = openssl_pkey_get_private($private_key, $passphrase); ``` # ファイルから秘密キーを読み込むための代替方法 アプリケーションでは、秘密キーとパスワードの両方をディスクに保存しておきたくない場合があります。代替方法として、パスワードを環境変数として渡し、秘密キーを、秘密キーのロックを解除するためのトークンと分けておくこともできます。 ### 3. JWTアサーションを作成する Box APIで認証するために、アプリケーションは、アクセストークンと交換できる署名済みのJWTアサーションを作成する必要があります。 JWTアサーションは、暗号化されたJSONオブジェクトで、`header`、`claims`、および`signature`で構成されます。最初に`claims`を作成します。これは、`payload`とも呼ばれる場合もあります。 ``` using System.IdentityModel.Tokens.Jwt; using System.Security.Claims; using System.Collections.Generic; byte[] randomNumber = new byte[64]; RandomNumberGenerator.Create().GetBytes(randomNumber); var jti = Convert.ToBase64String(randomNumber); DateTime expirationTime = DateTime.UtcNow.AddSeconds(45); var claims = new List<Claim>{ new Claim("sub", config.enterpriseID), new Claim("box_sub_type", "enterprise"), new Claim("jti", jti), }; ``` ``` import org.jose4j.jwt.JwtClaims; String authenticationUrl = "https://api.box.com/oauth2/token"; JwtClaims claims = new JwtClaims(); claims.setIssuer(config.boxAppSettings.clientID); claims.setAudience(authenticationUrl); claims.setSubject(config.enterpriseID); claims.setClaim("box_sub_type", "enterprise"); claims.setGeneratedJwtId(64); claims.setExpirationTimeMinutesInTheFuture(0.75f); ``` ``` import time import secrets authentication_url = 'https://api.box.com/oauth2/token' claims = { 'iss': config['boxAppSettings']['clientID'], 'sub': config['enterpriseID'], 'box_sub_type': 'enterprise', 'aud': authentication_url, 'jti': secrets.token_hex(64), 'exp': round(time.time()) + 45 } ``` ``` const crypto = require("crypto"); const authenticationUrl = "https://api.box.com/oauth2/token"; let claims = { iss: config.boxAppSettings.clientID, sub: config.enterpriseID, box_sub_type: "enterprise", aud: authenticationUrl, jti: crypto.randomBytes(64).toString("hex"), exp: Math.floor(Date.now() / 1000) + 45, }; ``` ``` require 'securerandom' authentication_url = 'https://api.box.com/oauth2/token' claims = { iss: config['boxAppSettings']['clientID'], sub: config['enterpriseID'], box_sub_type: 'enterprise', aud: authentication_url, jti: SecureRandom.hex(64), exp: Time.now.to_i + 45 } ``` ``` $authenticationUrl = 'https://api.box.com/oauth2/token'; $claims = [ 'iss' => $config->boxAppSettings->clientID, 'sub' => $config->enterpriseID, 'box_sub_type' => 'enterprise', 'aud' => $authenticationUrl, 'jti' => base64_encode(random_bytes(64)), 'exp' => time() + 45, 'kid' => $config->boxAppSettings->appAuth->publicKeyID ]; ``` | パラメータ | 型 | 説明 | | --- | --- | --- | | iss (必須) | String | BoxアプリケーションのOAuthクライアントID | | sub (必須) | String | Box Enterprise ID (このアプリがそのアプリケーションのサービスアカウントの代わりになる場合) またはユーザーID (このアプリが別のユーザーの代わりになる場合)。 | | box_sub_type (必須) | String | enterpriseまたはuser (subクレームでリクエストされているトークンの種類に応じて決定) | | aud (必須) | String | 常にhttps://api.box.com/oauth2/token | | jti (必須) | String | このJWTに対してアプリケーションで指定されたUUID (Universally Unique Identifier)。16文字以上128文字以下の一意の文字列です。 | | exp (必須) | Integer | このJWTが期限切れとなるUnix時間。設定できる最大値は、発行時刻から60秒後です。許容される最大値よりも小さい値を設定することをお勧めします。 | | iat (省略可) | Integer | 発行時刻。トークンは、この時刻より前に使用することはできません。 | | nbf (省略可) | Integer | 開始時刻。トークンの有効期間の開始時刻を指定します。 | 次に、秘密キーを使用してこれらのクレームに署名する必要があります。使用する言語とライブラリに応じて、クレームの署名に使用する暗号化アルゴリズムと公開キーのIDを定義することで、JWTの`header`が構成されます。 ``` using Microsoft.IdentityModel.Tokens; String authenticationUrl = "https://api.box.com/oauth2/token"; var payload = new JwtPayload( config.boxAppSettings.clientID, authenticationUrl, claims, null, expirationTime ); var credentials = new SigningCredentials( new RsaSecurityKey(key), SecurityAlgorithms.RsaSha512 ); var header = new JwtHeader(signingCredentials: credentials); var jst = new JwtSecurityToken(header, payload); var tokenHandler = new JwtSecurityTokenHandler(); string assertion = tokenHandler.WriteToken(jst); ``` ``` import org.jose4j.jws.AlgorithmIdentifiers; import org.jose4j.jws.JsonWebSignature; JsonWebSignature jws = new JsonWebSignature(); jws.setPayload(claims.toJson()); jws.setKey(key); jws.setAlgorithmHeaderValue(AlgorithmIdentifiers.RSA_USING_SHA512); jws.setHeader("typ", "JWT"); jws.setHeader("kid", config.boxAppSettings.appAuth.publicKeyID); String assertion = jws.getCompactSerialization(); ``` ``` import jwt keyId = config['boxAppSettings']['appAuth']['publicKeyID'] assertion = jwt.encode( claims, key, algorithm='RS512', headers={ 'kid': keyId } ) ``` ``` const jwt = require("jsonwebtoken"); let keyId = config.boxAppSettings.appAuth.publicKeyID; let headers = { algorithm: "RS512", keyid: keyId, }; let assertion = jwt.sign(claims, key, headers); ``` ``` require 'jwt' keyId = appAuth['publicKeyID'] assertion = JWT.encode(claims, key, 'RS512', { kid: keyId }) ``` ``` use \Firebase\JWT\JWT; $assertion = JWT::encode($claims, $key, 'RS512'); ``` ヘッダーでは、以下のパラメータがサポートされます。 | パラメータ | 型 | 説明 | | --- | --- | --- | | algorithm (必須) | String | JWTクレームへの署名に使用する暗号化アルゴリズム。RS256、RS384、RS512のいずれかを指定できます。 | | keyid (必須) | String | JWTへの署名に使用する公開キーのID。必須ではありませんが、アプリケーションに対して複数のキーペアが定義される場合は必須です。 | JWTライブラリの使用 独自のJWTへの署名は、複雑で手間のかかる処理になる可能性があります。そのようなことがないよう、事前にこの処理を済ませたライブラリがほぼすべての言語で用意されています。概要については、[JWT.io](https://jwt.io/)をご覧ください。 ### 4. アクセストークンをリクエストする 最後の手順として、有効期間の短いJWTアサーションを、より有効期間の長いアクセストークンと交換します。これには、アサーションをパラメータに指定してトークンエンドポイントを呼び出します。 ``` using System.Net; using System.Net.Http; var content = new FormUrlEncodedContent(new[] { new KeyValuePair<string, string>( "grant_type", "urn:ietf:params:oauth:grant-type:jwt-bearer"), new KeyValuePair<string, string>( "assertion", assertion), new KeyValuePair<string, string>( "client_id", config.boxAppSettings.clientID), new KeyValuePair<string, string>( "client_secret", config.boxAppSettings.clientSecret) }); var client = new HttpClient(); var response = client.PostAsync(authenticationUrl, content).Result; class Token { public string access_token { get; set; } } var data = response.Content.ReadAsStringAsync().Result; var token = JsonConvert.DeserializeObject<Token>(data); var accessToken = token.access_token; ``` ``` import java.util.ArrayList; import java.util.List; import org.apache.http.HttpEntity; import org.apache.http.NameValuePair; import org.apache.http.client.entity.UrlEncodedFormEntity; import org.apache.http.client.methods.CloseableHttpResponse; import org.apache.http.client.methods.HttpPost; import org.apache.http.impl.client.CloseableHttpClient; import org.apache.http.impl.client.HttpClientBuilder; import org.apache.http.message.BasicNameValuePair; import org.apache.http.util.EntityUtils; List<NameValuePair> params = new ArrayList<NameValuePair>(); params.add(new BasicNameValuePair( "grant_type", "urn:ietf:params:oauth:grant-type:jwt-bearer")); params.add(new BasicNameValuePair( "assertion", assertion)); params.add(new BasicNameValuePair( "client_id", config.boxAppSettings.clientID)); params.add(new BasicNameValuePair( "client_secret", config.boxAppSettings.clientSecret)); CloseableHttpClient httpClient = HttpClientBuilder.create().disableCookieManagement().build(); HttpPost request = new HttpPost(authenticationUrl); request.setEntity(new UrlEncodedFormEntity(params)); CloseableHttpResponse httpResponse = httpClient.execute(request); HttpEntity entity = httpResponse.getEntity(); String response = EntityUtils.toString(entity); httpClient.close(); class Token { String access_token; } Token token = (Token) gson.fromJson(response, Token.class); String accessToken = token.access_token; ``` ``` import json import requests params = { 'grant_type': 'urn:ietf:params:oauth:grant-type:jwt-bearer', 'assertion': assertion, 'client_id': config['boxAppSettings']['clientID'], 'client_secret': config['boxAppSettings']['clientSecret'] } response = requests.post(authentication_url, params) access_token = response.json()['access_token'] ``` ``` const axios = require("axios"); const querystring = require("querystring"); let accessToken = await axios .post( authenticationUrl, querystring.stringify({ grant_type: "urn:ietf:params:oauth:grant-type:jwt-bearer", assertion: assertion, client_id: config.boxAppSettings.clientID, client_secret: config.boxAppSettings.clientSecret, }) ) .then((response) => response.data.access_token); ``` ``` require 'json' require 'uri' require 'net/https' params = URI.encode_www_form({ grant_type: 'urn:ietf:params:oauth:grant-type:jwt-bearer', assertion: assertion, client_id: config['boxAppSettings']['clientID'], client_secret: config['boxAppSettings']['clientSecret'] }) uri = URI.parse(authentication_url) http = Net::HTTP.start(uri.host, uri.port, use_ssl: true) request = Net::HTTP::Post.new(uri.request_uri) request.body = params response = http.request(request) access_token = JSON.parse(response.body)['access_token'] ``` ``` use GuzzleHttp\Client; $params = [ 'grant_type' => 'urn:ietf:params:oauth:grant-type:jwt-bearer', 'assertion' => $assertion, 'client_id' => $config->boxAppSettings->clientID, 'client_secret' => $config->boxAppSettings->clientSecret ]; $client = new Client(); $response = $client->request('POST', $authenticationUrl, [ 'form_params' => $params ]); $data = $response->getBody()->getContents(); $access_token = json_decode($data)->access_token; ``` ## コードサンプル このガイドに記載されているコードは、[GitHub](https://github.com/box-community/samples-docs-authenticate-with-jwt-api)で入手できます。 **Source:** [https://ja.developer.box.com/guides/authentication/jwt/without-sdk/](https://ja.developer.box.com/guides/authentication/jwt/without-sdk/) --- ### SDKを使用しないOAuth 2.0 **Type:** guide | **Category:** 認証 | **Section:** Developer Guides SDKを使用しないOAuth 2.0 概要 Box公式SDKを利用すると、一般的な認証のハードルはなくなりますが、Box APIは、Box公式SDKがなくても使用できます。このガイドでは、OAuth 2.0のフローを手動で完成させるための手順を説明します。 承認URL… # SDKを使用しないOAuth 2.0 ## 概要 Box公式SDKを利用すると、一般的な認証のハードルはなくなりますが、Box APIは、Box公式SDKがなくても使用できます。このガイドでは、OAuth 2.0のフローを手動で完成させるための手順を説明します。 1. 承認URLを作成する 2. ユーザーを承認URLにリダイレクトする 3. ユーザーが自分の代わりにアクションを実行するためのアクセス権限をアプリケーションに付与する (成功した場合は承認コードが提供される) 4. ユーザーを再度アプリケーションにリダイレクトする 5. 承認コードをアクセストークンと交換する このフローが終了すると、アプリケーションには[アクセストークン](g://authentication/tokens/access-tokens)が付与されます。これを使用すると、ユーザーの代わりにAPIコールを実行できます。 OAuth 2.0フローを介して取得したアクセストークンは、もともとアプリケーションを承認したユーザーに関連付けられています。 `as-user`ヘッダーを使用して、[別のユーザーとして処理を実行](g://authentication/oauth2/as-user)できます。 ## 前提条件 続行する前に、以下の手順を完了しておく必要があります。 - Box開発者コンソールで、OAuth 2.0認証方法を利用するPlatformアプリを作成する。 - アプリケーションの [構成] タブに移動して、`client_id`と`client_secret`の値をコピーする。 - アプリケーションの [構成] タブで、少なくとも1つのリダイレクトURIが構成されていることを確認する。 ## 1. 承認URLを作成する [承認URL](e://get-authorize)は、以下のパラメータで構成されています。 | パラメータ | ステータス | 説明 | | --- | --- | --- | | CLIENT_ID | 必須 | 開発者コンソールの [構成] タブから取得します。 | | REDIRECT_URI | 省略可 | 開発者コンソールで構成します。アプリケーションにアクセスを許可すると、ユーザーがリダイレクトされます。 | | RESPONSE_TYPE | 必須 | 常にcodeに設定します。 | | STATE | 推奨 | クロスサイトリクエスト偽造から保護します。 | アプリケーション用にリダイレクトURIを複数設定した場合、承認URLには、開発者コンソールで設定したURIのいずれかと一致する`redirect_uri`パラメータを含める必要があります。このパラメータが指定されていない場合、ユーザーには`redirect_uri_missing`エラーが表示され、アプリにリダイレクトされません。 少なくとも、このURLは常に次の形式を使用します。 `https://account.box.com/api/oauth2/authorize`?`client_id=CLIENTIDHERE`&`response_type=code` ``` var baseUrl = "https://account.box.com/api/oauth2/authorize"; var clientId = "[CLIENT_ID]"; var authorizationUrl = $"{baseUrl}?client_id={clientId}&response_type=code"; ``` ``` String baseUrl = "https://account.box.com/api/oauth2/authorize"; String clientId = "[CLIENT_ID]"; String authorizationUrl = String.format("%s?client_id=%s&response_type=code", baseUrl, clientId); ``` ``` base_url = 'https://account.box.com/api/oauth2/authorize' client_id = '[CLIENT_ID]' authorizationUrl = f'{base_url}?client_id=${client_id}&response_type=code' ``` ``` var baseUrl = "https://account.box.com/api/oauth2/authorize"; var clientId = "[CLIENT_ID]"; var authorizationUrl = `${baseUrl}?client_id=${clientId}&response_type=code`; ``` 承認URLの詳細を確認する Boxインスタンスの[Box Verified Enterprise](https://support.box.com/hc/ja/articles/360043693554-Box-Verified-Enterprise%E3%81%A8%E3%82%B5%E3%83%9D%E3%83%BC%E3%83%88%E5%AF%BE%E8%B1%A1%E3%81%AE%E3%82%A2%E3%83%97%E3%83%AA)が有効になっている場合、標準的な`account.box.com`というベースURLを使用する際に問題が発生することがあります。`account.box.com`の代わりに`ent.box.com`を使用してください。 ## 2. ユーザーをリダイレクトする 次に、ユーザーを承認URLにリダイレクトします。その方法は、アプリケーションフレームワークによって異なります。このトピックの詳細については、ほとんどのフレームワークのドキュメントで説明されています。 指定されたアプリに対して承認URLが無効な場合、ユーザーには、アクセスの許可画面ではなくエラーページが表示されます。たとえば、承認URLに含まれる`redirect_uri`パラメータが、アプリ用に構成されたURIのいずれとも一致しない場合、ユーザーには`redirect_uri_mismatch`エラーが表示されます。 ``` var authorizationUrl = $"{baseUrl}?client_id={clientId}&response_type=code"; // redirectTo(authorizationUrl); ``` ``` String authorizationUrl = String.format("%s?client_id=%s&response_type=code", baseUrl, clientId); // response.redirect(authorizationUrl); ``` ``` auth_url = f'{base_url}?client_id=${client_id}&response_type=code' // redirect(auth_url, code=302) ``` ``` var authorizationUrl = `${baseUrl}?client_id=${clientId}&response_type=code`; // res.redirect(authorize_url) ``` スコープを制限したり追加の状態を渡したりするために、ユーザーをリダイレクトする際に追加のクエリパラメータを渡すことができます。詳細については、承認のリファレンスドキュメントを参照してください。 ## 3. ユーザーがアプリケーションにアクセス権限を付与する ユーザーは、Box UIを使用して自分のアカウントにログインするために、ブラウザにリダイレクトされます。その後、リクエストされているスコープのリストと、ユーザーに代わって処理を行うアプリケーションを承認するためのオプションが表示されます。 ユーザーが [**Boxへのアクセスを許可**] をクリックしてこのリクエストを承認すると、ブラウザは、クエリパラメータに有効期間の短い承認コードが指定されている構成済みのリダイレクトURLにリダイレクトされます。 アプリケーション用にリダイレクトURIを複数設定した場合、承認URLには、開発者コンソールで設定したURIのいずれかと一致する`redirect_uri`パラメータを含める必要があります。このパラメータが指定されていない場合、ユーザーには`redirect_uri_missing`エラーが表示され、アプリにリダイレクトされません。 ``` https://your.domain.com/path?code=1234567 ``` ## 4. コードを交換する 提供される承認コードは、[有効期間が30秒](g://api-calls/permissions-and-errors/expiration)のため、有効期限が切れる前に[アクセストークン](e://post-oauth2-token)に交換する必要があります。 ``` using System.Net; using System.Net.Http; using Newtonsoft.Json; String authenticationUrl = "https://api.box.com/oauth2/token"; var client = new HttpClient(); var content = new FormUrlEncodedContent(new[] { new KeyValuePair<string, string>("grant_type", "authorization_code"), new KeyValuePair<string, string>("code", "[CODE]"), new KeyValuePair<string, string>("client_id", "[CLIENT_ID]"), new KeyValuePair<string, string>("client_secret", "[CLIENT_SECRET]") }); var response = client.PostAsync(authenticationUrl, content).Result; class Token { public string access_token { get; set; } } var data = response.Content.ReadAsStringAsync().Result; var token = JsonConvert.DeserializeObject<Token>(data); var accessToken = token.access_token; ``` ``` String authenticationUrl = "https://api.box.com/oauth2/token"; List<NameValuePair> params = new ArrayList<NameValuePair>(); params.add(new BasicNameValuePair("grant_type", "authorization_code")); params.add(new BasicNameValuePair("code", "[CODE]")); params.add(new BasicNameValuePair("client_id", "[CLIENT_ID]")); params.add(new BasicNameValuePair("client_secret", "[CLIENT_SECRET]")); CloseableHttpClient httpClient = HttpClientBuilder.create().disableCookieManagement().build(); HttpPost request = new HttpPost(authenticationUrl); request.setEntity(new UrlEncodedFormEntity(params)); CloseableHttpResponse httpResponse = httpClient.execute(request); HttpEntity entity = httpResponse.getEntity(); String response = EntityUtils.toString(entity); httpClient.close(); class Token { String access_token; } Token token = (Token) gson.fromJson(response, Token.class); String accessToken = token.access_token; ``` ``` authentication_url = "https://api.box.com/oauth2/token"; params = urlencode({ 'grant_type': 'authorization_code', 'code': '[CODE]', 'client_id': '[CLIENT_ID]', 'client_secret': '[CLIENT_SECRET]' }).encode() request = Request(authentication_url, params) response = urlopen(request).read() access_token = json.loads(response)['access_token'] ``` ``` const authenticationUrl = "https://api.box.com/oauth2/token"; let accessToken = await axios .post( authenticationUrl, querystring.stringify({ grant_type: "authorization_code", code: "[CODE]", client_id: "[CLIENT_ID]", client_secret: "[CLIENT_SECRET]", }) ) .then((response) => response.data.access_token); ``` アクセストークンの使用方法を確認するには、[APIコールの実行](g://api-calls)に関するガイドを参照してください。 **Source:** [https://ja.developer.box.com/guides/authentication/oauth2/without-sdk/](https://ja.developer.box.com/guides/authentication/oauth2/without-sdk/) --- ### SDKを使用しないアプリトークン **Type:** guide | **Category:** 認証 | **Section:** Developer Guides SDKを使用しないアプリトークン Box公式SDKのいずれも使用できるようになっていない場合や選択した言語のSDKがない場合は、SDKがなくてもBox APIを使用できます。 アプリトークン認証は、Box API… # SDKを使用しないアプリトークン Box公式SDKのいずれも使用できるようになっていない場合や選択した言語のSDKがない場合は、SDKがなくてもBox APIを使用できます。 アプリトークン認証は、Box APIを直接操作するよう設計されており、ユーザーがアプリケーションを承認するためにBoxを介してリダイレクトする必要はありません。ただし、この認証はアプリケーションのデータのみに制限されています。 JWTを使用した認証方法は、もともとアプリケーションのサービスアカウントに関連付けられています。このトークンを使用して実行されるAPIコールはどれも、このアプリケーションから実行されているように見えますが、明示的なアクセス権がなければ他のユーザーのファイルやフォルダにはアクセスできません。 ## 前提条件 開始する前に、以下の手順を完了しておく必要があります。 - 開発者コンソール内でBoxアプリケーションを作成する - アプリケーションがアプリトークン認証を使用するよう構成されていることを確認する - アプリケーションのプライマリアプリトークンとセカンダリアプリトークンを生成し、コード内のどこかにこれらのトークンを保存する ## APIコールの実行 アプリトークンを直接使用するには、任意のアクセストークンを使用する場合と同じように、アプリケーションでアプリトークンを使用できます。 ``` curl https://api.box.com/2.0/users/me \ -H "authorization: Bearer EGmDmRVfhfHsqesn5yVYHAqUkD0dyDfk" ``` **Source:** [https://ja.developer.box.com/guides/authentication/app-token/without-sdk/](https://ja.developer.box.com/guides/authentication/app-token/without-sdk/) --- ### Shieldアラートイベント **Type:** guide | **Category:** イベント | **Section:** Developer Guides Shieldアラートイベント 以下で説明する高度なセキュリティ機能を活用するには、Box Shieldを購入し、Box Enterpriseで有効にする必要があります。 脅威検出アラート Shield… # Shieldアラートイベント 以下で説明する高度なセキュリティ機能を活用するには、[Box Shield](https://www.box.com/ja-jp/shield)を購入し、Box Enterpriseで有効にする必要があります。 ## 脅威検出アラート Shieldの[脅威検出](https://support.box.com/hc/ja/articles/360044196113-%E8%84%85%E5%A8%81%E6%A4%9C%E5%87%BA%E3%81%AE%E4%BD%BF%E7%94%A8)では、ユーザーの異常な動作に基づいて、潜在的な脅威 (アカウントの侵害やデータの盗難など) に関する詳細なアラートが表示されます。 Shieldによって生成される可能性があるアラートは以下のとおりです。 1. 不審な場所 2. 不審なセッション 3. 異常なダウンロード 4. 悪意のあるコンテンツ Shieldの脅威検出アラートイベントはすべて、[Enterprise Event](g://events/enterprise-events/for-enterprise) Stream内で生成されます。これらのイベントは標準のイベントオブジェクトスキーマに従い、`event_type`値は`SHIELD_ALERT`に設定されます。 ``` { "source": null, "created_by": { "type": "user", "id": "2", "name": "Unknown User", "login": "" }, "action_by": null, "created_at": "2019-12-20T11:38:56-08:00", "event_id": "97f1b31f-f143-4777-81f8-1b557b39ca33", "event_type": "SHIELD_ALERT", "ip_address": "10.1.2.3", "type": "event", "session_id": null, "additional_details": { "..." } } ``` `additional_details`オブジェクトは、イベントをトリガーした特定の種類のShieldアラートに関する情報を提供します。 ### 不審な場所に関するアラート 不審な場所に関するアラートは、通常とは異なる場所や「ホスト」IPアドレス、または除外対象に指定されている場所や「ホスト」IPアドレスからコンテンツにアクセスしているユーザーがShieldによって検出されたときに生成されます。これは、`additional_details.shield_alert.rule_category`内の`Suspicious Locations`値によって識別できます。 `additional_details`ペイロードは以下の詳細を示します。 ``` "additional_details": { "shield_alert": { "rule_category": "Suspicious Locations", "rule_id": 123, "rule_name": "Suspicious Location", "rule_response_action": { "restrict_user": true }, "risk_score": 60, "alert_summary": { "alert_activities": [ { "occurred_at": "2019-12-20T11:37:05-08:00", "event_type": "Download", "item_name": "xyz.txt", "item_type": "file", "item_id": "127", "item_path": "ABC/DEF", "ip_info": { "ip": "1.2.3.4", "latitude": "37.5555", "longitude": "-120.6789", "registrant": "Microsoft Corporation", "country_code": "US", "city_name": "San Jose", "region_name": "California" }, "service_name": "Box Excel Online Previewer" } ] }, "alert_id": 2398, "priority": "medium", "user": { "id": 2320, "name": "Some name", "email": "some@email.com" }, "link": "https://app.box.com/master/shield/alerts/2398", "created_at": "2019-12-20T11:37:15-08:00" } } ``` ### 不審なセッションに関するアラート 不審なセッションに関するアラートは、ユーザーエージェント文字列の異常、ユーザーIDの異常、アプリケーションの種類が一般的ではない、IPアドレスが新しい、ログイン場所が考えられないほど高速に変化しているなどの特徴があるセッションでコンテンツにアクセスしているユーザーがShieldによって検出されたときに生成されます。これは、`additional_details.shield_alert.rule_category`内の`Suspicious Sessions`値によって識別できます。 `additional_details`ペイロードは以下の詳細を示します。 ``` "additional_details": { "shield_alert": { "rule_category": "Suspicious Sessions", "rule_id": 123, "rule_name": "Suspicious Session", "rule_response_action": null, "risk_score": 77, "alert_summary": { "description": "First time in prior month user connected from ip 2.3.4.5 First time user agent Some User Agent (Some UA 4.5.6) appeared for user within prior month Apparent distance 9580.0 km between events 59 seconds apart is faster than possible", "sessions": [ { "session_type": "suspicious", "activities": [ { "occurred_at": "2019-12-19T11:37:00-08:00", "event_type": "Set shared link expiration", "item_name": "xyz.txt", "item_type": "file", "item_id": "123456", "item_path": "ABC/DEF", "ip_info": { "ip": "2.3.4.5", "latitude": "37.5555", "longitude": "-120.6789", "registrant": "Microsoft Corporation", "country_code": "US", "city_name": "San Jose", "region_name": "California" }, "service_name": "ServiceName" } ] }, { "session_type": "typical", "activities": [ { "occurred_at": "2019-12-19T11:37:59-08:00", "event_type": "Item Modified", "item_name": "abc.boxnote", "item_type": "file", "item_id": "123123", "item_path": "folder/sub folder", "ip_info": { "ip": "4.5.6.7", "latitude": "37.5555", "longitude": "-20.6789", "country_code": "US", "city_name": "Some City", "region_name": "XYZ" }, "service_name": "Box Notes" } ] } ] }, "alert_id": 500, "priority": "medium", "user": { "id": 50500, "name": "A b c", "email": "a@b.c" }, "link": "https://cloud.app.box.com/master/shield/alerts/500", "created_at": "2019-12-20T11:38:16-08:00" } } ``` ### 異常なダウンロードに関するアラート 異常なダウンロードに関するアラートは、機密コンテンツを盗んでいる可能性のあるアカウント所有者がShieldによって検出されたときに生成されます。これは、`additional_details.shield_alert.rule_category`内の`Anomalous Download`値によって識別できます。 `additional_details`ペイロードは以下の詳細を示します。 ``` "additional_details": { "shield_alert": { "rule_category": "Anomalous Download", "rule_id": 123, "rule_name": "Anomalous Download Rule", "rule_response_action": null, "risk_score": 77, "alert_summary": { "description": "Significant increase in download content week over week, 9200% (25.04 MB) more than last week 12 additional files downloaded week over week)", "download_delta_size": "25 Mb", "download_delta_percent": 9200, "historical_period": { "date_range": { "start_date": "2019-12-01T01:01:00-08:00", "end_date": "2019-12-08T01:01:00-08:00" }, "download_size": "0 Mb", "downloaded_files_count": 1 }, "anomaly_period": { "date_range": { "start_date": "2019-12-08T01:01:00-08:00", "end_date": "2019-12-15T01:01:00-08:00" }, "download_size": "25 Mb", "downloaded_files_count": 13 }, "download_ips": [ { "ip": "1.2.3.4" } ] }, "alert_id": 444, "priority": "medium", "user": { "id": 567, "name": "Some user", "email": "some@user.com" }, "link": "https://cloud.app.box.com/master/shield/alerts/444", "created_at": "2019-12-20T11:38:16-08:00" } } ``` ### 悪意のあるコンテンツに関するアラート 悪意のあるコンテンツに関するアラートは、アカウントにアップロードされるコンテンツの潜在的なマルウェアがShieldによって検出されたときに生成されます。これは、`additional_details.shield_alert.rule_category`内の`Malicious Content`値によって識別できます。 `additional_details`ペイロードは以下の詳細を示します。 ``` "additional_details": { "shield_alert": { "rule_category": "Malicious Content", "rule_id": 123, "rule_name": "Viruses and stuff", "rule_response_action": null, "risk_score": 100, "alert_summary": { "upload_activity": { "occurred_at": "2019-12-20T11:37:05-08:00", "event_type": "Upload", "item_name": "virus.exe", "item_type": "file", "item_id": "127", "item_path": "ABC/DEF", "sha1_hash": "", "ip_info": { "ip": "1.2.3.4", "latitude": "37.5555", "longitude": "-120.6789", "registrant": "Microsoft Corporation", "country_code": "US", "city_name": "San Jose", "region_name": "California" }, "service_name": "Service name" } }, "malware_info": { "file_id": 127, "file_name": "malware.exe", "file_version": 4239023, "file_created": "2019-12-20T11:37:05-08:00", "file_created_by": { "id": 1010, "name": "Bob", "email": "bob@enterprise.com" }, "file_hash": "d869db7fe62fb07c25a0403ecaea55031744b5fb", "file_hash_type": "SHA-1", "file_size_bytes": 51345, "file_version_uploaded": "2019-12-20T11:37:05-08:00", "file_version_uploaded_by": { "id": 1011, "name": "Jane", "email": "jane@enterprise.com" }, "status": "Malicious", "categories": [ "Adware", "SpyWare" ], "tags": [ "FILE_MALICIOUS_EXECUTION", "FILE_OTHER_TAG" ], "description": "This is a really bad file", "detail_link": "https://some.link/xyz", "malware_name": "BadMalware", "first_seen": "2019-12-19T11:37:05-08:00", "last_seen": "2019-12-20T11:37:05-08:00", "family": "MalwareBot4000" }, "alert_id": 2398, "priority": "medium", "user": { "id": 2320, "name": "Some Name", "email": "some@email.com" }, "link": "https://app.box.com/master/shield/alerts/2398", "created_at": "2019-12-20T11:37:15-08:00" } } ``` **Source:** [https://ja.developer.box.com/guides/events/event-triggers/shield-alert-events/](https://ja.developer.box.com/guides/events/event-triggers/shield-alert-events/) --- ### Shieldスマートアクセスイベント **Type:** guide | **Category:** イベント | **Section:** Developer Guides Shieldスマートアクセスイベント Box… # Shieldスマートアクセスイベント Box管理者は、[スマートアクセス](https://support.box.com/hc/ja/articles/7711416297747-%E3%82%B9%E3%83%9E%E3%83%BC%E3%83%88%E3%82%A2%E3%82%AF%E3%82%BB%E3%82%B9%E3%81%AB%E3%81%A4%E3%81%84%E3%81%A6)を使用すると、分類ベースのアクセスポリシーを定義、適用してアクセスを制御し、機密コンテンツの意図しない漏えいを防止できます。 スマートアクセスポリシーは、[適用モードまたは監視モード](https://support.box.com/hc/ja/articles/14596333776403-Shield%E3%82%A2%E3%82%AF%E3%82%BB%E3%82%B9%E3%83%9D%E3%83%AA%E3%82%B7%E3%83%BC%E3%81%AE%E8%A8%AD%E5%AE%9A)で構成できます。すべてのイベントタイプで、ポリシーが`enforced`モードと`monitoring`モードのどちらであるかを示す、`controlMode`という名前のフィールドが表示されます。 ## ダウンロードと印刷の制限 ダウンロードまたは印刷の制限を適用するShieldアクセスポリシーを管理者が作成し、エンドユーザーがファイルをダウンロードまたは印刷できないようブロックされると、[Enterprise Event](g://events/enterprise-events/for-enterprise) Stream内でイベントが生成されます。ダウンロードと印刷の違反の可能性を監視するようアクセスポリシーを設定した場合は、ユーザーがダウンロードまたは印刷が制限されたファイルを含むフォルダを表示したとき、ダウンロードまたは印刷が制限されたファイルをプレビューで表示したとき、ダウンロードまたは印刷が制限されたファイルをAPI経由でダウンロードすることをリクエストしたときにもイベントが生成されます。これらのイベントは標準のイベントオブジェクトスキーマに従い、`event_type`値は`SHIELD_DOWNLOAD_BLOCKED`に設定されます。 ダウンロードがブロックされている場合、`SHIELD_DOWNLOAD_BLOCKED`イベントの`additional-details`ペイロードには以下の詳細が示されます。 Boxウェブアプリの場合、`additional_details`ペイロードは以下の詳細を示します。 ``` "additional_details": { "shield_download_enforcement": { "item": { "type": "file", "id": 987654321, "name": "testFile.docx", "file_version_id": 38495726173, "size": 370, "sha1": "db0a61e73b5e6985d190134e0a4b9982c716afeb" }, "access_user": { "type": "user", "id": 123456789, "name": "Some Name", "login": "somename@box.com" }, "service": null, "additional_info": "", "created_at": "2022-02-22T10:35:08-08:00", "classification": "Confidential", "controlMode": "enforced" } } ``` Boxデスクトップアプリの場合、`additional_details`ペイロードは以下の詳細を示します。 ``` "additional_details": { "shield_download_enforcement": { "item": { "type": "file", "id": 123456789, "name": "testFile.docx", "file_version_id": 987654321, "size": 11640, "sha1": "368acd076a89ce82e62cac004fa27ea9ce3019d7" }, "access_user": { "type": "user", "id": 123456789, "name": "Some Name", "login": "somename@box.com" }, "service": { "service": 254429, "name": "Box Drive" }, "additional_info": "", "created_at": "2022-02-22T10:38:58-08:00", "classification": "Confidential", "controlMode": "enforced" }, "service_id": "254429", "service_name": "Box Drive" } ``` Box Mobileアプリの場合、`additional_details`ペイロードは以下の詳細を示します。 ``` "additional_details": { "shield_download_enforcement": { "item": { "type": "file", "id": 987654321, "name": "testFile.docx", "file_version_id": 38495726173, "size": 11640, "sha1": "368acd076a89ce82e62cac004fa27ea9ce3019d7" }, "access_user": { "type": "user", "id": 123456789, "name": "Some Name", "login": "somename@box.com" }, "service": { "service": 4715, "name": "Box for Android" }, "additional_info": "", "created_at": "2022-01-18T14:51:37-08:00", "classification": "Confidential", "controlMode": "monitoring" }, "service_id": "4715", "service_name": "Box for Android" } ``` ## 外部コラボレーションの制限 外部コラボレーションの招待が制限されている場合、イベントは[Enterprise Event](g://events/enterprise-events/for-enterprise) Stream内で生成されます。これらのイベントは、`event_type`値が次のいずれかに設定されている、標準のイベントオブジェクトスキーマに従います: `SHIELD_EXTERNAL_COLLAB_INVITE_BLOCKED_MISSING_JUSTIFICATION`、`SHIELD_EXTERNAL_COLLAB_INVITE_JUSTIFIED`、`SHIELD_EXTERNAL_COLLAB_INVITE_BLOCKED`、`SHIELD_EXTERNAL_COLLAB_ACCESS_BLOCKED_MISSING_JUSTIFICATION`、`SHIELD_EXTERNAL_COLLAB_ACCESS_BLOCKED`。 外部コラボレーションの招待がブロックされている場合、`SHIELD_EXTERNAL_COLLAB_INVITE_BLOCKED`または`SHIELD_EXTERNAL_COLLAB_INVITE_BLOCKED_MISSING_JUSTIFICATION`イベントの`additional-details`ペイロードによって以下の詳細が示されます。 ``` "additional_details": { "shield_external_collab_enforcement": { "item": { "type": "file", "id": 987654321, "name": "testFile.docx", "file_version_id": 987654321, "size": 11640, "sha1": "368acd076a89ce82e62cac004fa27ea9ce3019d7" }, "inviter": { "type": "user", "id": 123456789, "name": "Some Name", "login": "somename@box.com" }, "invitee": { "type": "user", "id": 123456789, "name": "Some Name", "login": "somename@box.com" }, "accessUser": null, "service": null, "additionalInfo": "", "createdAt": null, "justification": null, "classification": "Confidential", "controlMode": "enforced" } } ``` 外部コラボレーションの招待が正当な理由で認められている場合、`SHIELD_EXTERNAL_COLLAB_INVITE_JUSTIFIED`イベントの`additional_details`ペイロードによって以下の詳細が示されます。 ``` "additional_details": { "shield_external_collab_enforcement": { "item": { "type": "file", "id": 123456789, "name": "testFile.docx", "file_version_id": 123456789, "size": 11640, "sha1": "368acd076a89ce82e62cac004fa27ea9ce3019d7" }, "inviter": { "type": "user", "id": 123456789, "name": "Some Name", "login": "somename@box.com" }, "invitee": { "type": "user", "id": 123456789, "name": "Some Name", "login": "somename@box.com" }, "accessUser": null, "service": null, "additionalInfo": "", "createdAt": null, "justification": { "justification_id": "17786127", "request_at": 1644874023, "requested_by": { "type": "user", "id": 123456789, "name": "Some Name", "login": "somename@box.com" }, "request_type": "EXTERNAL_COLLAB", "item": { "type": "file", "id": 987654321, "name": "testFile.docx", "file_version_id": 941051265322, "size": 11640, "sha1": "368acd076a89ce82e62cac004fa27ea9ce3019d7" }, "user": { "type": "user", "id": 123456789, "name": "Some Name", "login": "somename@box.com" }, "title": "Approved", "description": "", "additional_info": null, "approved_by": { "type": "user", "id": 123456789, "name": "Some Name", "login": "somename@box.com" }, "action": "APPROVED", "action_at": 1644874023, "details": null }, "classification": "Confidential", "controlMode": "enforced" } } ``` 外部コラボレーションのアクセスがブロックされている場合、`SHIELD_EXTERNAL_COLLAB_ACCESS_BLOCKED`または`SHIELD_EXTERNAL_COLLAB_ACCESS_BLOCKED_MISSING_JUSTIFICATION`イベントの`additional_details`ペイロードによって以下の詳細が示されます。 ``` "additional_details": { "shield_external_collab_enforcement": { "item": { "type": "file", "id": 987654321, "name": "testFile.docx", "file_version_id": 987654321, "size": 11640, "sha1": "368acd076a89ce82e62cac004fa27ea9ce3019d7" }, "inviter": { "type": "user", "id": 123456789, "name": "Some Name", "login": "somename@box.com" }, "invitee": { "type": "user", "id": 123456789, "name": "Some Name", "login": "somename@box.com" }, "accessUser": null, "service": null, "additionalInfo": "", "createdAt": null, "justification": null, "classification": "Confidential", "controlMode": "enforced" } } ``` Shieldの正当な理由が承認されると、イベントが[Enterprise Event](g://events/enterprise-events/for-enterprise) Stream内で生成されます。これらのイベントは、標準のイベントオブジェクトスキーマと、`SHIELD_JUSTIFICATION_APPROVAL`に設定された`event_type`値に従います。 `additional_details`ペイロードは以下の詳細を示します。 ``` "additional_details": { "shield_justification": { "justification_id": "18428718", "request_at": 1645556286, "requested_by": { "type": "user", "id": 123456789, "name": "Some Name", "login": "somename@box.com" }, "request_type": "EXTERNAL_COLLAB", "item": { "type": "file", "id": 987654321, "name": "testFile.docx", "file_version_id": 987654321, "size": 11640, "sha1": "368acd076a89ce82e62cac004fa27ea9ce3019d7" }, "user": { "type": "user", "id": 123456789, "name": "Some Name", "login": "somename@box.com" }, "title": "Partner Project", "description": "", "additional_info": null, "approved_by": { "type": "user", "id": 123456789, "name": "Some Name", "login": "somename@box.com" }, "action": "APPROVED", "action_at": 1645556286, "details": null } } ``` 管理者は、共有ウィンドウから正当な理由が選択されたときに1つではなく2つのEnterprise Eventが表示される可能性があることに注意してください。たとえば、`SHIELD_EXTERNAL_COLLAB_INVITE_BLOCKED_MISSING_JUSTIFICATION`イベントと`SHIELD_EXTERNAL_COLLAB_INVITE_JUSTIFIED`イベントが1つずつ表示されます。 ## 統合の制限 サードパーティ製アプリケーション (組織と統合されている公開Platformアプリケーションなど) がファイルまたはフォルダのダウンロードを制限されている場合は、[Enterprise Event](g://events/enterprise-events/for-enterprise) Stream内でイベントが生成されます。これらのイベントは標準のイベントオブジェクトスキーマに従い、`event_type`値は`SHIELD_DOWNLOAD_BLOCKED`に設定されます。 サードパーティ製アプリケーションの場合、`additional_details`ペイロードは以下の詳細を示します。 ``` "additional_details": { "shield_download_enforcement": { "item": { "type": "file", "id": 875644956551, "name": "blaha.docx", "file_version_id": 941051265322, "size": 11640, "sha1": "368acd076a89ce82e62cac004fa27ea9ce3019d7" }, "access_user": { "type": "user", "id": 11754686560, "name": "Ming Feng", "login": "mfeng+demo@boxdemo.com" }, "service": "docusign", "additional_info": "", "created_at": "2022-01-18T14:53:53-08:00", "classification": "Confidential", "controlMode": "enforced" } ``` Platformアプリケーションの場合、`additional_details`ペイロードは以下の詳細を示します。 ``` "additional_details": { "shield_download_enforcement": { "item": { "type": "file", "id": 123456789, "name": "testFile.docx", "file_version_id": 987654321, "size": 11640, "sha1": "368acd076a89ce82e62cac004fa27ea9ce3019d7" }, "access_user": { "type": "user", "id": 123456789, "name": "Some Name", "login": "somename@box.com" }, "service": { "service": 123456, "name": "CustomApp" }, "additional_info": "", "created_at": "2022-01-18T13:31:25-08:00", "classification": "Confidential", "controlMode": "enforced" }, "service_id": "123456", "service_name": "CustomApp" } ``` ## FTPの制限 FTPプロトコルを介したファイルまたはフォルダのダウンロードが制限されている場合は、[Enterprise Event](g://events/enterprise-events/for-enterprise) Stream内でイベントが生成されます。これらのイベントは標準のイベントオブジェクトスキーマに従い、`event_type`値は`SHIELD_DOWNLOAD_BLOCKED`に設定されます。 `additional_details`ペイロードは以下の詳細を示します。 ``` "additional_details": { "shield_download_enforcement": { "item": { "type": "file", "id": 123456789, "name": "textFile.txt", "file_version_id": 987654321, "size": 3606, "sha1": "ab7a79ff8e2a6b576e1c62d850290a09312fb387" }, "access_user": { "type": "user", "id": 123456789, "name": "Some Name", "login": "somename@box.com" }, "service": { "service": 4082, "name": "Box FTP Server" }, "additional_info": "", "created_at": "2022-01-18T14:19:51-08:00", "classification": null, "controlMode": "enforced" }, "service_id": "4082", "service_name": "Box FTP Server" } ``` **Source:** [https://ja.developer.box.com/guides/events/event-triggers/shield-smart-access-events/](https://ja.developer.box.com/guides/events/event-triggers/shield-smart-access-events/) --- ### Shield情報バリアイベント **Type:** guide | **Category:** イベント | **Section:** Developer Guides Shield… # Shield情報バリアイベント 情報バリアは、利益相反または潜在的な法的問題につながる可能性のあるやり取りやコミュニケーションを防止します。たとえば、管理者は情報バリアを使用して、プロジェクトに基づいてチームを分け、特定のグループに制限されたコンテンツでのコラボレーションを防ぐことができます。 ## 情報バリアの設定時にトリガーされるイベント 情報バリアを設定すると、[Enterprise Event](g://events/enterprise-events/for-enterprise/) Streamにイベントが作成されます。たとえば、バリアをアクティブ化または非アクティブ化すると、イベントがトリガーされます。 これらのイベントは、`event_type`値が次のいずれかに設定されている、標準的なイベントオブジェクトスキーマに従います。 - `SHIELD_INFORMATION_BARRIER_ENABLED` - `SHIELD_INFORMATION_BARRIER_PENDING` - `SHIELD_INFORMATION_BARRIER_DISABLED` ### Shield情報バリアの有効化 `SHIELD_INFORMATION_BARRIER_ENABLED`イベントは、ファイルまたはフォルダに対して情報バリアを有効化するとトリガーされます。以下に例を示します。 ``` { "chunk_size": 1, "next_stream_position": "1152923169537420243", "entries": [ { "source": { "barrier_id": 123456, "barrier_status": "ENABLED", "barrier_segments": [ { "name": "8", "member_count": 1 }, { "name": "9", "member_count": 1 } ] }, "created_by": { "type": "user", "id": "12345667", "name": "Unknown User", "login": "user@email.com" }, "action_by": null, "created_at": "2022-10-04T17:42:53-07:00", "event_id": "f82c3ba03e41f7e8a7608363cc6c0390183c3f83", "event_type": "SHIELD_INFORMATION_BARRIER_ENABLED", "ip_address": "Unknown IP", "type": "event", "session_id": null, "additional_details": null } ] } ``` ### Shield情報バリアが保留中 `SHIELD_INFORMATION_BARRIER_PENDING`イベントは、特定のファイルまたはフォルダに対して情報バリアがまだ有効になっていないときにトリガーされます。アクティブ化のプロセスはトリガーされたものの、情報バリアがまだ設定されていません。以下に例を示します。 ``` { "chunk_size": 1, "next_stream_position": "1152923169531664551", "entries": [ { "source": { "barrier_id": 123456, "barrier_status": "PENDING", "barrier_segments": [ { "name": "8", "member_count": 1 }, { "name": "9", "member_count": 1 } ] }, "created_by": { "type": "user", "id": "12345667", "name": "Unknown User", "login": "user@email.com" }, "action_by": null, "created_at": "2022-10-04T16:06:57-07:00", "event_id": "f82c3ba03e41f7e8a7608363cc6c0390183c3f83", "event_type": "SHIELD_INFORMATION_BARRIER_PENDING", "ip_address": "Unknown IP", "type": "event", "session_id": null, "additional_details": null } ] } ``` ### Shield情報バリアの非アクティブ化 `SHIELD_INFORMATION_BARRIER_DISABLED`イベントは、特定のファイルまたはフォルダに対して情報バリアを非アクティブにするとトリガーされます。以下に例を示します。 ``` { "chunk_size": 1, "next_stream_position": "1152923169767928414", "entries": [ { "source": { "barrier_id": 1234567, "barrier_status": "DISABLED", "barrier_segments": [ { "name": "8", "member_count": 1 }, { "name": "9", "member_count": 1 } ] }, "created_by": { "type": "user", "id": "123435567", "name": "Unknown User", "login": "user@email.com" }, "action_by": null, "created_at": "2022-10-07T09:44:41-07:00", "event_id": "f82c3ba03e41f7e8a7608363cc6c0390183c3f83", "event_type": "SHIELD_INFORMATION_BARRIER_DISABLED", "ip_address": "Unknown IP", "type": "event", "session_id": null, "additional_details": null } ] } ``` ## 制限されたアクションによってトリガーされるイベント 情報バリアが設定されているときに、各ユーザーが制限されたアクションの実行や制限されたデータへのアクセスを試みた場合もイベントが発生します。これらのイベントは、`event_type`値が次のいずれかに設定されている、標準的なイベントオブジェクトスキーマに従います。 - `SHIELD_INFORMATION_BARRIER_GROUP_ADD_USER_BLOCKED` - `SHIELD_INFORMATION_BARRIER_COLLAB_BLOCKED` - `SHIELD_INFORMATION_BARRIER_ITEM_OWNER_TRANSFER_BLOCKED` - `SHIELD_INFORMATION_BARRIER_SHARED_ITEM_ACCESS_BLOCKED` - `SHIELD_INFORMATION_BARRIER_ITEM_MOVE_BLOCKED` - `SHIELD_INFORMATION_BARRIER_ITEM_COPY_BLOCKED` ### ユーザーの追加のブロック `SHIELD_INFORMATION_BARRIER_GROUP_ADD_USER_BLOCKED`イベントは、情報バリアによって、特定のグループへのユーザーの追加が禁止された場合にトリガーされます。 `additional_details`ペイロードでは、制限されたグループの詳細が提供されます。 ``` { "source": { "type": "user", "id": "123456677", "name": "Unknown User", "login": "user@email.com" }, "created_by": { "type": "user", "id": "12345666", "name": "Unknown User", "login": "user@email.com" }, "action_by": null, "created_at": "2022-10-07T09:26:50-07:00", "event_id": "f82c3ba03e41f7e8a7608363cc6c0390183c3f83", "event_type": "SHIELD_INFORMATION_BARRIER_GROUP_ADD_USER_BLOCKED", "ip_address": "10.1.2.3", "type": "event", "session_id": null, "additional_details": { "group_id": "12345678", "group_name": "Support" } } ``` ### コラボレーションのブロック `SHIELD_INFORMATION_BARRIER_COLLAB_BLOCKED`イベントは、情報バリアによって、ファイルまたはフォルダへのアクセスが制限されているユーザーのコラボレーションの追加が禁止された場合にトリガーされます。 `additional_details`ペイロードでは、制限されたコラボレーションの詳細が提供されます。 ``` { "source": { "folder_id": "12334556", "folder_name": "Contracts", "user_id": "1234567", "user_name": "Unknown User", "parent": { "type": "folder", "name": "All Files", "id": "0" }, "owned_by": { "type": "user", "id": "12345678", "name": "Unknown User", "login": "user@email.com" } }, "created_by": { "type": "user", "id": "16335351460", "name": "Unknown User", "login": "user@email.com" }, "action_by": null, "created_at": "2022-10-05T14:15:14-07:00", "event_id": "f82c3ba03e41f7e8a7608363cc6c0390183c3f83", "event_type": "SHIELD_INFORMATION_BARRIER_COLLAB_BLOCKED", "ip_address": "Unknown IP", "type": "event", "session_id": null, "additional_details": { "type": "box://event/additional_details/collaboration", "collab_id": "0", "is_performed_by_admin": false } } ``` ### 共有項目へのアクセスのブロック `SHIELD_INFORMATION_BARRIER_SHARED_ITEM_ACCESS_BLOCKED`イベントは、情報バリアによって、共有リンクを使用したファイルまたはフォルダへのアクセスが禁止された場合にトリガーされます。 `additional_details`ペイロードでは、共有リンクとその他のセキュリティに関する情報の詳細が提供されます。 ``` { "source": { "item_type": "folder", "item_id": "123456789", "item_name": "Contracts", "parent": { "type": "folder", "name": "All Files", "id": "0" }, "owned_by": { "type": "user", "id": "123456789", "name": "Unknown User", "login": "user@email.com" } }, "created_by": { "type": "user", "id": "123456789", "name": "Unknown User", "login": "user@email.com" }, "action_by": null, "created_at": "2022-10-06T13:27:58-07:00", "event_id": "f82c3ba03e41f7e8a7608363cc6c0390183c3f83", "event_type": "SHIELD_INFORMATION_BARRIER_SHARED_ITEM_ACCESS_BLOCKED", "ip_address": "Unknown IP", "type": "event", "session_id": null, "additional_details": { "shared_link_id": "abcdefghijklm", "security_information": { "accessFromSharedObject": { "sharedId": 123456789, "sharedName": "abcdefghijklmnop", "passwordSet": false, "accessLevel": "open", "createdAt": "2022-10-06T13:27:21-07:00" } } } } ``` ### 項目の移動のブロック `SHIELD_INFORMATION_BARRIER_ITEM_MOVE_BLOCKED`イベントは、情報バリアによって、ユーザーがアクセスできないフォルダへの項目 (ファイルまたはフォルダ) の移動が禁止された場合にトリガーされます。 `additional_details`ペイロードでは、フォルダの詳細が提供されます。 ``` { "source": { "item_type": "folder", "item_id": "123456789", "item_name": "Contracts", "parent": { "type": "folder", "name": "All Files", "id": "0" }, "owned_by": { "type": "user", "id": "123456789", "name": "Unknown User", "login": "user@email.com" } }, "created_by": { "type": "user", "id": "123456789", "name": "Unknown User", "login": "user@email.com" }, "action_by": null, "created_at": "2022-10-06T13:26:58-07:00", "event_id": "f82c3ba03e41f7e8a7608363cc6c0390183c3f83", "event_type": "SHIELD_INFORMATION_BARRIER_ITEM_MOVE_BLOCKED", "ip_address": "Unknown IP", "type": "event", "session_id": null, "additional_details": { "destination_folder": { "item_type": "folder", "item_id": "123456789", "item_name": "Contracts Signed" } } } ``` ### 項目のコピーのブロック `SHIELD_INFORMATION_BARRIER_ITEM_COPY_BLOCKED`イベントは、情報バリアによって、ユーザーがアクセスできないフォルダへの項目 (ファイルまたはフォルダ) のコピーが禁止された場合にトリガーされます。 `additional_details`ペイロードでは、宛先フォルダの詳細が提供されます。 ``` { "source": { "item_type": "folder", "item_id": "123456789", "item_name": "Contracts", "parent": { "type": "folder", "name": "All Files", "id": "0" }, "owned_by": { "type": "user", "id": "123456789", "name": "Unknown User", "login": "user@email.com" } }, "created_by": { "type": "user", "id": "123456789", "name": "Unknown User", "login": "user@email.com" }, "action_by": null, "created_at": "2022-10-05T14:25:15-07:00", "event_id": "f82c3ba03e41f7e8a7608363cc6c0390183c3f83", "event_type": "SHIELD_INFORMATION_BARRIER_ITEM_COPY_BLOCKED", "ip_address": "Unknown IP", "type": "event", "session_id": null, "additional_details": { "destination_folder": { "item_type": "folder", "item_id": "123456789", "item_name": "Contracts Signed" } } } ``` ### 項目の所有権の移管のブロック `SHIELD_INFORMATION_BARRIER_ITEM_OWNER_TRANSFER_BLOCKED`イベントは、情報バリアによって、制限の対象となっているユーザーへの項目の所有権の移管が禁止された場合にトリガーされます。 `additional_details`ペイロードでは、新しい所有者として設定できないユーザーの詳細が提供されます。 ``` { "source": { "item_type": "folder", "item_id": "", "item_name": "All Files", "parent": { "type": "folder", "name": "", "id": "" }, "owned_by": { "type": "user", "id": "123456789", "name": "Unknown User", "login": "user@email.com" } }, "created_by": { "type": "user", "id": "123456789", "name": "Unknown User", "login": "user@email.com" }, "action_by": null, "created_at": "2022-10-07T09:29:20-07:00", "event_id": "f82c3ba03e41f7e8a7608363cc6c0390183c3f83", "event_type": "SHIELD_INFORMATION_BARRIER_ITEM_OWNER_TRANSFER_BLOCKED", "ip_address": "10.1.2.3", "type": "event", "session_id": null, "additional_details": { "restricted_user": { "type": "user", "id": "123456789", "name": "Unknown User", "login": "user@email.com" }, "service_id": "123456789", "service_name": "App" } } ``` **Source:** [https://ja.developer.box.com/guides/events/event-triggers/shield-information-barrier-events/](https://ja.developer.box.com/guides/events/event-triggers/shield-information-barrier-events/) --- ### Signイベント **Type:** guide | **Category:** イベント | **Section:** Developer Guides Signイベント Box Signイベントの監査には、Enterprise Event Streamを使用します。Box Signの詳細については、ガイドを参照してください。 以下に示す各additional_details… # Signイベント Box Signイベントの監査には、Enterprise Event Streamを使用します。Box Signの詳細については、[ガイド](g://box-sign)を参照してください。 以下に示す各`additional_details`ペイロードのステータスは、具体的な署名リクエストの詳細に基づいた例とは異なる場合があります。たとえば、リクエスト送信者が唯一の署名者の場合は、`SIGN_DOCUMENT_CREATED`イベントのステータスがすぐに`viewed`になります。 ## ドキュメントイベント ### 作成 APIまたはUIを使用して署名リクエストが作成されると、`SIGN_DOCUMENT_CREATED` `event_type`が生成されます。この段階ではまだ署名リクエストは署名者に送信されません。 `additional_details`ペイロードは以下の詳細を示します。 ``` "additional_details": { "sign_request": { "sign_request_id": "123e4567-e89b-12d3-a456-426614174000", "sign_request_short_id": "426614174000", "status": "sent", "signer_ip_address": null, "requestor_ip_address": "", "files": [ { "id": "1234567890", "type": "file", "name": "example_doc.pdf", "parent": { "id": "987654321", "type": "folder" } } ], "requestor": { "id": "13579246", "type": "user", "name": "John Doe", "login": "johndoe@box.com" }, "signer": null, "template": { "id": "987abC5423", "template_type": "Signing", "name": "Work Contact" }, "batch_send": { "id": "W23YVL46" }, "redirection": { "redirect_url": "https://www.google.com", "declined_redirect_url": "https://www.googledecline.com" }, "sender_message": { "subject": "Can you please sign this document?", "message": "This document shows the terms agreed to on the phone." }, "forward": null } } ``` ### 変換 署名リクエストが署名用の`.pdf`に変換されると、`SIGN_DOCUMENT_CONVERTED` `event_type`が生成されます。 `additional_details`ペイロードは以下の詳細を示します。 ``` "additional_details": { "sign_request": { "sign_request_id": "123e4567-e89b-12d3-a456-426614174000", "sign_request_short_id": "426614174000", "status": "created", "signer_ip_address": null, "requestor_ip_address": "", "files": [ { "id": "1234567890", "type": "file", "name": "example_doc.pdf", "parent": { "id": "987654321", "type": "folder" } } ], "expires": null, "requestor": { "id": "13579246", "type": "user", "name": "John Doe", "login": "johndoe@box.com" }, "signer": null, "template": null, "batch_send": null, "redirection": { "redirect_url": "https://www.google.com", "declined_redirect_url": "https://www.googledecline.com" }, "sender_message": { "subject": "", "message": "" }, "forward": null } } ``` ### 完了 署名者全員がドキュメントへの署名を正常に完了すると、`SIGN_DOCUMENT_COMPLETED` `event_type`が生成されます。 `additional_details`ペイロードは以下の詳細を示します。 ``` "additional_details": { "sign_request": { "sign_request_id": "123e4567-e89b-12d3-a456-426614174000", "sign_request_short_id": "426614174000", "status": "signed", "signer_ip_address": null, "requestor_ip_address": "", "files": [ { "id": "1234567890", "type": "file", "name": "example_doc.pdf", "parent": { "id": "987654321", "type": "folder" } } ], "expires": null, "requestor": { "id": "13579246", "type": "user", "name": "John Doe", "login": "johndoe@box.com" }, "signer": null, "template": null, "batch_send": null, "redirection": { "redirect_url": "https://www.google.com", "declined_redirect_url": "https://www.googledecline.com" }, "sender_message": { "subject": "", "message": "" }, "forward": null } } ``` ### キャンセル リクエスト送信者がAPIまたはUIで署名リクエストをキャンセルすると、`SIGN_DOCUMENT_CANCELLED` `event_type`が生成されます。 `additional_details`ペイロードは以下の詳細を示します。 ``` "additional_details": { "sign_request": { "sign_request_id": "123e4567-e89b-12d3-a456-426614174000", "sign_request_short_id": "426614174000", "status": "cancelled", "signer_ip_address": null, "requestor_ip_address": "", "files": [ { "id": "1234567890", "type": "file", "name": "example_doc.pdf", "parent": { "id": "987654321", "type": "folder" } } ], "expires": null, "requestor": { "id": "13579246", "type": "user", "name": "John Doe", "login": "johndoe@box.com" }, "signer": null, "template": null, "batch_send": null, "redirection": { "redirect_url": "https://www.google.com", "declined_redirect_url": "https://www.googledecline.com" }, "sender_message": { "subject": "", "message": "" }, "forward": null } } ``` ### 期限切れ 署名が完了しないまま署名リクエストが期限切れになると、`SIGN_DOCUMENT_EXPIRED` `event_type`が生成されます。 `additional_details`ペイロードは以下の詳細を示します。 ``` "additional_details": { "sign_request": { "sign_request_id": "123e4567-e89b-12d3-a456-426614174000", "sign_request_short_id": "426614174000", "status": "expired", "signer_ip_address": null, "requestor_ip_address": "", "files": [ { "id": "1234567890", "type": "file", "name": "example_doc.pdf", "parent": { "id": "987654321", "type": "folder" } } ], "expires": null, "requestor": { "id": "13579246", "type": "user", "name": "John Doe", "login": "johndoe@box.com" }, "signer": null, "template": null, "batch_send": null, "redirection": { "redirect_url": "https://www.google.com", "declined_redirect_url": "https://www.googledecline.com" }, "sender_message": { "subject": "", "message": "" }, "forward": null } } ``` ## 署名者イベント ### 割り当て 署名リクエストが問題なく署名者に送信されると、`SIGN_DOCUMENT_ASSIGNED` `event_type`が生成されます。 `additional_details`ペイロードは以下の詳細を示します。 ``` "additional_details": { "sign_request": { "sign_request_id": "123e4567-e89b-12d3-a456-426614174000", "sign_request_short_id": "426614174000", "status": "sent", "signer_ip_address": "", "requestor_ip_address": "", "files": [ { "id": "1234567890", "type": "file", "name": "example_doc.pdf", "parent": { "id": "987654321", "type": "folder" } } ], "expires": null, "requestor": { "id": "13579246", "type": "user", "name": "John Doe", "login": "johndoe@box.com" }, "signer": { "id": "246813579", "type": "user", "name": "Jane Doe", "login": "janedoe@example.com" }, "template": null, "batch_send": null, "redirection": { "redirect_url": "https://www.google.com", "declined_redirect_url": "https://www.googledecline.com" }, "ready_sign_link": { "id": "aaae45bb-e89b-12d3-a456-426614174000" }, "sender_message": { "subject": "", "message": "" }, "forward": null } } ``` ### 署名者による表示 署名リクエストの署名者が署名用メールの [**ドキュメントをレビュー**] をクリックするか、署名用URLにアクセスすると、`SIGN_DOCUMENT_VIEWED_BY_SIGNER` `event_type`が生成されます。 `additional_details`ペイロードは以下の詳細を示します。 ``` "additional_details": { "sign_request": { "sign_request_id": "123e4567-e89b-12d3-a456-426614174000", "sign_request_short_id": "426614174000", "status": "viewed", "signer_ip_address": "", "requestor_ip_address": "", "files": [ { "id": "1234567890", "type": "file", "name": "example_doc.pdf", "parent": { "id": "987654321", "type": "folder" } } ], "expires": null, "requestor": { "id": "13579246", "type": "user", "name": "John Doe", "login": "johndoe@box.com" }, "signer": { "id": "246813579", "type": "user", "name": "Jane Doe", "login": "janedoe@example.com" }, "template": null, "batch_send": null, "redirection": { "redirect_url": "https://www.google.com", "declined_redirect_url": "https://www.googledecline.com" }, "ready_sign_link": { "id": "aaae45bb-e89b-12d3-a456-426614174000" }, "sender_message": { "subject": "", "message": "" }, "forward": null } } ``` ### ダウンロード 署名者が署名用ドキュメントをダウンロードすると、`SIGNER_DOWNLOADED` `event_type`が生成されます。 ``` "additional_details": { "sign_request": { "sign_request_id": "123e4567-e89b-12d3-a456-426614174000", "sign_request_short_id": "426614174000", "status": "viewed", "signer_ip_address": "", "requestor_ip_address": "", "files": [ { "id": "1234567890", "type": "file", "name": "example_doc.pdf", "parent": { "id": "987654321", "type": "folder" } } ], "expires": null, "requestor": { "id": "13579246", "type": "user", "name": "John Doe", "login": "johndoe@box.com" }, "signer": { "id": "246813579", "type": "user", "name": "Jane Doe", "login": "janedoe@example.com" }, "template": null, "batch_send": null, "redirection": { "redirect_url": "https://www.google.com", "declined_redirect_url": "https://www.googledecline.com" }, "ready_sign_link": { "id": "aaae45bb-e89b-12d3-a456-426614174000" }, "sender_message": { "subject": "", "message": "" }, "forward": { "forwarded_to_email": "janedoe@box.com", "forwarded_reason": "Please sign", "forwarded_at": "2022-03-03T12:04:20-10:00" } } } ``` ### 転送 署名者が署名用ドキュメントをダウンロードすると、`SIGNER_FORWARDED` `event_type`が生成されます。 ``` "additional_details": { "sign_request": { "sign_request_id": "123e4567-e89b-12d3-a456-426614174000", "sign_request_short_id": "426614174000", "status": "viewed", "signer_ip_address": "", "requestor_ip_address": "", "files": [ { "id": "1234567890", "type": "file", "name": "example_doc.pdf", "parent": { "id": "987654321", "type": "folder" } } ], "expires": null, "requestor": { "id": "13579246", "type": "user", "name": "John Doe", "login": "johndoe@box.com" }, "signer": { "id": "246813579", "type": "user", "name": "Jane Doe", "login": "janedoe@example.com" }, "template": null, "batch_send": null, "redirection": { "redirect_url": "https://www.google.com", "declined_redirect_url": "https://www.googledecline.com" }, "ready_sign_link": { "id": "aaae45bb-e89b-12d3-a456-426614174000" }, "sender_message": { "subject": "Can you please sign this document?", "message": "This document shows the terms agreed to on the phone." }, "forward": { "forwarded_to_email": "somename@box.com", "forwarded_reason": "I need to forward to my business partner.", "forwarded_at": "2022-02-03T10:04:52-08:00", }, } } ``` ### 署名 署名者が署名リクエストを完了すると、`SIGN_DOCUMENT_SIGNED` `event_type`が生成されます。 `additional_details`ペイロードは以下の詳細を示します。 ``` "additional_details": { "sign_request": { "sign_request_id": "123e4567-e89b-12d3-a456-426614174000", "sign_request_short_id": "426614174000", "status": "signed", "signer_ip_address": "", "requestor_ip_address": "", "files": [ { "id": "1234567890", "type": "file", "name": "example_doc.pdf", "parent": { "id": "987654321", "type": "folder" } } ], "expires": null, "requestor": { "id": "13579246", "type": "user", "name": "John Doe", "login": "johndoe@box.com" }, "signer": { "id": "246813579", "type": "user", "name": "Jane Doe", "login": "janedoe@example.com" }, "template": null, "batch_send": null, "redirection": { "redirect_url": "https://www.google.com", "declined_redirect_url": "https://www.googledecline.com" }, "ready_sign_link": { "id": "aaae45bb-e89b-12d3-a456-426614174000" }, "sender_message": { "subject": "Can you please sign this document?", "message": "This document shows the terms agreed to on the phone." }, "forward": null } } ``` ### 拒否 署名リクエストの署名者がリクエストを拒否すると、`SIGN_DOCUMENT_DECLINED` `event_type`が生成されます。 `additional_details`ペイロードは以下の詳細を示します。 ``` "additional_details": { "sign_request": { "sign_request_id": "123e4567-e89b-12d3-a456-426614174000", "sign_request_short_id": "426614174000", "status": "declined", "signer_ip_address": "", "requestor_ip_address": "", "files": [ { "id": "1234567890", "type": "file", "name": "example_doc.pdf", "parent": { "id": "987654321", "type": "folder" } } ], "expires": null, "requestor": { "id": "13579246", "type": "user", "name": "John Doe", "login": "johndoe@box.com" }, "signer": { "id": "246813579", "type": "user", "name": "Jane Doe", "login": "janedoe@example.com" }, "template": null, "batch_send": null, "redirection": { "redirect_url": "https://www.google.com", "declined_redirect_url": "https://www.googledecline.com" }, "ready_sign_link": { "id": "aaae45bb-e89b-12d3-a456-426614174000" }, "sender_message": { "subject": "", "message": "" }, "forward": null } } ``` **Source:** [https://ja.developer.box.com/guides/events/event-triggers/sign-events/](https://ja.developer.box.com/guides/events/event-triggers/sign-events/) --- ### Signクライアントの埋め込み機能 **Type:** guide | **Category:** Box Sign | **Section:** Developer Guides Signクライアントの埋め込み機能 Box Embedを使用すると、ウェブサイトにBox Signの機能を埋め込むことができます。これにより、ユーザーはウェブサイトを離れ、Box Sign… # Signクライアントの埋め込み機能 [Box Embed](g://embed/box-embed)を使用すると、ウェブサイトにBox Signの機能を埋め込むことができます。これにより、ユーザーはウェブサイトを離れ、Box Signにアクセスしてドキュメントに署名し、プロセスを完了するために戻る必要がなくなります。代わりに、Box Embedを使用すると、外部のウェブサイト内で署名プロセスを完了できます。 Box Signのエクスペリエンスをウェブサイトに統合するには、HTMLの`iframe`タグ内のドキュメントへの署名を許可するために設計された`iframable_embed_url`パラメータが必要です。 `iframable_embed_url`のサンプルは次のようになります。 ``` https://app.box.com/embed/sign/document/f14d7098-a331-494b-808b-79bc7f3992a3/f14d7098-a331-494b-808b-79bc7f3992a4 ``` `iframeable_embed_url`を取得するには、[署名リクエストを作成](e://post-sign-requests)エンドポイントを呼び出す際に各署名者の[`embed_url_external_user_id`](e://post-sign-requests#param-signers-embed_url_external_user_id)パラメータを渡します。返されるレスポンスには、その署名者の一意の`iframeable_embed_url`が含まれます。 Signの機能を埋め込み、ユーザーが使用できるようにするには、`iframe`タグ内でURLを使用します。 ``` <iframe src="https://app.box.com/embed/sign/document/f14d7098-a331-494b-808b-79bc7f3992a3/f14d7098-a331-494b-808b-79bc7f3992a4" width="{pixels}" height="{pixels}" frameborder="0" allowfullscreen webkitallowfullscreen msallowfullscreen ></iframe> ``` Box Embedの使用の詳細については、[こちらのガイド](g://embed/box-embed#programmatically)を参照してください。 Box Embedでは、クリックジャッキングを防ぐために[クラウド (雲) ゲーム](g://embed/box-embed#cloud-game)ウィジェットを使用します。この場合、ユーザーはドキュメントに署名する際に、このウィジェットを操作し、クラウド (雲) を適切な位置にドラッグしてから、ドキュメントへの署名に進む必要があります。 **Source:** [https://ja.developer.box.com/guides/box-sign/embedded-sign-client/](https://ja.developer.box.com/guides/box-sign/embedded-sign-client/) --- ### Signテンプレートを使用した署名リクエストの作成 **Type:** guide | **Category:** Box Sign | **Section:** Developer Guides Signテンプレートを使用した署名リクエストの作成 署名リクエストAPIを使用すると、署名リクエストの作成時に、あらかじめ定義されたBox Sign… # Signテンプレートを使用した署名リクエストの作成 署名リクエストAPIを使用すると、署名リクエストの作成時に、あらかじめ定義されたBox Signテンプレートを使用できます。このテンプレートには、リクエストの作成時にデータが自動的に設定されるプレースホルダが含まれています。 ## テンプレートの作成 まず、リクエストに必要となる`text`、`date`、`signature`フィールドを含むBox Signテンプレートを作成します。 詳細な手順については、[テンプレートに関するガイド](https://support.box.com/hc/en-us/articles/4404094944915-Creating-templates)を参照してください。 ## テンプレートIDの取得 署名リクエストを送信するには、使用するテンプレートのIDを渡す必要があります。`template_id`を確認するには、テンプレートのリストを取得します。 レスポンスは以下のようになります (説明のため省略されています)。レスポンス全体の例については、[Box SignテンプレートAPI](e://get-sign-templates#response-example)を参照してください。 また、具体的なパラメータの詳細については、[署名リクエストを作成](e://post-sign-requests)ガイドで確認できます。 ``` "entries": [ { "id": "6ae28666-03c4-4ac1-80db-06a90d3b1361", "name": "Contract.pdf", "parent_folder": { "id": "157064745449", "etag": "0", "type": "folder", "sequence_id": "0", "name": "My Sign Requests" }, "source_files": [ { "id": "1216382236853", "etag": "0", "type": "file", "sequence_id": "0", "sha1": "ca9c75cda0d5e3c3c9b0a1e6d42cb5e29a211ab6", "file_version": { "id": "1327286673653", "type": "file_version", "sha1": "ca9c75cda0d5e3c3c9b0a1e6d42cb5e29a211ab6" } } ], "signers": [ { "email": "", "label": "reader", "public_id": "4Z8QZZV4", "role": "final_copy_reader", "is_in_person": false, "order": 1, "inputs": [...] }, { "email": "", "label": "signer1", "public_id": "4Z8QZZV4", "role": "signer", "is_in_person": false, "order": 1, "inputs": [...] }, { "email": "", "label": "signer2", "public_id": "13VK8794", "role": "signer", "is_in_person": false, "order": 1, "inputs": [ { "document_tag_id": "signer2_full_name", "id": "da431975-55c5-4629-86ae-3fb12dda1386", "type": "text", "text_value": null, "is_required": true, "content_type": "full_name", ... }, { "document_tag_id": null, "id": "b5a76a22-8d48-456e-a012-22a12fc91eb7", "type": "signature", ... }, { "document_tag_id": null, "id": "7e0cc4ee-b878-4739-afde-acbf69b117b2", "type": "date", "date_value": null, ... } ], } ] ... } ] ``` ## 署名リクエストの作成 テンプレートを使用して[署名リクエストを作成](e://post-sign-requests)するには、以下の手順に従います。 1. リクエスト本文で、`template_id`を指定します。 ``` { "template_id": "6ae28666-03c4-4ac1-80db-06a90d3b1361", "parent_folder": { "id": "123456789", "etag": "0", "type": "folder", "sequence_id": "0", "name": "My Sign Requests" }, ... } ``` 1. 署名者のメールアドレスと役割を追加します。 ``` { "template_id": "6ae28666-03c4-4ac1-80db-06a90d3b1361", "parent_folder": { "id": "157064745449", "etag": "0", "type": "folder", "sequence_id": "0", "name": "My Sign Requests" }, "signers": [ { "email": "signer1@sample.com", "role": "signer" }, { "email": "signer2@sample.com", "role": "signer" } ] } ``` `prefill_tags`を追加してフィールドにデータを設定します。 署名者の順序がテンプレートに表示されている順序と同じであることを確認してください。テンプレートで最初に`signer1`、次に`signer2`がある場合、`POST`リクエストでは、適切な署名者を割り当てるために同じにする必要があります。 ``` { "template_id": "6ae28666-03c4-4ac1-80db-06a90d3b1361", "parent_folder": { "id": "123456789000", "etag": "0", "type": "folder", "sequence_id": "0", "name": "My Sign Requests" }, "signers": [ { "email": "signer1@sample.com", "role": "signer" }, { "email": "signer2@sample.com", "role": "signer" } ], "prefill_tags": [ { "document_tag_id": "signer1_full_name", "text_value": "Aaron Levie" }, { "document_tag_id": "signer2_full_name", "text_value": "Albert Einstein" } ] } ``` 1. `POST`リクエストを送信します。レスポンスは以下のようになります。 ``` { "is_document_preparation_needed": false, ... "signers": [ { "email": "reader@sample.com", "role": "final_copy_reader", }, { "email": "signer1@sample.com", "role": "signer", }, { "email": "signer2@sample.com", "role": "signer", } ], "id": "d02fefd2-15fa-431f-a127-2b4525616ae6", "prefill_tags": [ { "document_tag_id": "signer1_full_name", "text_value": "Aaron Levie", }, { "document_tag_id": "signer2_full_name", "text_value": "Albert Einstein", } ], "source_files": [], "parent_folder": { "id": "123456789000", "type": "folder", "name": "My Sign Requests" }, "name": "Contract.pdf", "type": "sign-request", "status": "created", "sign_files": { "files": [ { "id": "123456789", "type": "file", "name": "Contract.pdf", } ], "is_ready_for_download": true }, "template_id": "6ae28666-03c4-4ac1-80db-06a90d3b1361" } ``` **Source:** [https://ja.developer.box.com/guides/box-sign/sign-templates/](https://ja.developer.box.com/guides/box-sign/sign-templates/) --- ### Skillsカードのメタデータ **Type:** guide | **Category:** Box Skills | **Section:** Developer Guides Skillsカードのメタデータ 処理サービスによってファイルのメタデータが特定されたら、アプリケーションはそのデータをBox… # Skillsカードのメタデータ 処理サービスによってファイルのメタデータが特定されたら、アプリケーションはそのデータをBoxに保存されているファイルにメタデータとして書き戻すことができます。 このプロセスには、以下の手順が含まれます。 1. スキルカードのメタデータの準備 2. ファイルへのメタデータの書き込み ## スキルカードのメタデータの準備 Skillsメタデータは、グローバルに利用可能な`boxSkillsCards`という名前のメタデータテンプレートを使用します。このテンプレートは、関連ファイルに保存されるJSON構造の特定の形式に従います。 Boxでは現在、4種類のカードがサポートされています。 | | | | | --- | --- | --- | | キーワード | ファイルの横にキーワードのリストを表示します。 | | | タイムライン | 一連のテキスト/画像を表示します。それらの画像がタイムラインに表示される時刻は、クリックすると表示されます。 | | | トランスクリプト | トランスクリプトと、それに対応するタイムスタンプを表示します。 | | | ステータス | ユーザーにステータスを表示します。これは、ファイルの処理中にスキルのステータスをユーザーに通知するために使用できます。 | | ## ファイルへのメタデータカードの書き込み ファイルに1つ以上のカードを書き込むには、[`POST /files/:id/metadata/global/boxSkillsCards`](e://post_files_id_metadata_global_boxSkillsCards) APIを使用して、Box Skill `cards`のリストを渡します。 ``` curl -X POST https://api.box.com/2.0/files/12345/metadata/global/boxSkillsCards \ -H 'Authorization: Bearer <ACCESS_TOKEN>' \ -H 'Content-Type: application/json' \ -d '{ "cards": [{ "type": "skill_card", "skill_card_type": "keyword", "skill_card_title": { "code": "license-plates", "message": "Licence Plates" }, "skill": { "type": "service" "id": "license-plates-service" }, "invocation": { "type": "skill_invocation" "id": "license-plates-service-123" }, "entries": { { "text": "DD-26-YT" }, { "text": "DN86 BOX" } } }], }' ``` ``` const metadata = { cards: [{ "type": "skill_card", "skill_card_type": "keyword", "skill_card_title": { "code": "license-plates", "message": "Licence Plates" }, "skill": { "type": "service" "id": "license-plates-service" }, "invocation": { "type": "skill_invocation" "id": "license-plates-service-123" }, "entries": { { "text": "DD-26-YT" }, { "text": "DN86 BOX" } } }] } client.files.addMetadata('12345', 'global', 'boxSkillsCards', metadata) .then(metadata => { // ... }) ``` ``` metadata = { cards: [{ "type": "skill_card", "skill_card_type": "keyword", "skill_card_title": { "code": "license-plates", "message": "Licence Plates" }, "skill": { "type": "service" "id": "license-plates-service" }, "invocation": { "type": "skill_invocation" "id": "license-plates-service-123" }, "entries": { { "text": "DD-26-YT" }, { "text": "DN86 BOX" } } }] } client.file(file_id='12345').metadata(scope='global', template='boxSkillsCards').create(metadata) ``` ``` BoxFile file = new BoxFile(api, "12345"); Metadata metadata = new Metadata() file.createMetadata("global", "boxSkillsCards", metadata); ``` ``` var metadataValues = new Dictionary<string, object>() { cards: [{ "type": "skill_card", "skill_card_type": "keyword", "skill_card_title": { "code": "license-plates", "message": "Licence Plates" }, "skill": { "type": "service" "id": "license-plates-service" }, "invocation": { "type": "skill_invocation" "id": "license-plates-service-123" }, "entries": { { "text": "DD-26-YT" }, { "text": "DN86 BOX" } } }] }; Dictionary<string, object> metadata = await client.MetadataManager .CreateFileMetadataAsync(fileId: "12345", metadataValues, "global", "boxSkillsCards"); ``` Box Skillカードがすでにこのファイルに適用されている場合は、このAPIコールによって、HTTPステータスコード`409`とともにエラーが返されます。 ## ファイルのメタデータカードの更新 Box Skillカードがすでにファイルに適用されている場合、[`PUT /files/:id/metadata/global/boxSkillsCards`](e://put_files_id_metadata_global_boxSkillsCards) APIを使用して更新することができます。このAPIは、実行する多数の操作 (`op`) を受け取り、各操作を使用すると、特定の位置 (`path`) のカードを置き換えることができます。 ``` curl -X PUT https://api.box.com/2.0/files/12345/metadata/global/boxSkillsCards \ -H 'Authorization: Bearer <ACCESS_TOKEN>' \ -H 'Content-Type: application/json-patch+json' \ -d '[ "op": "replace", "path": "/cards/0", "value": { "type": "skill_card", "skill_card_type": "keyword", "skill_card_title": { "code": "license-plates", "message": "Licence Plates" }, "skill": { "type": "service" "id": "license-plates-service" }, "invocation": { "type": "skill_invocation" "id": "license-plates-service-123" }, "entries": { { "text": "DD-26-YT" }, { "text": "DN86 BOX" } } } ]' ``` ``` const updates = [ { 'op': 'replace', 'path': '/cards/0', 'value': { "type": "skill_card", "skill_card_type": "keyword", "skill_card_title": { "code": "license-plates", "message": "Licence Plates" }, "skill": { "type": "service" "id": "license-plates-service" }, "invocation": { "type": "skill_invocation" "id": "license-plates-service-123" }, "entries": { { "text": "DD-26-YT" }, { "text": "DN86 BOX" } } } } ] client.files.updateMetadata('12345', 'global', 'boxSkillsCards', updates) .then(metadata => { // ... }) ``` ``` file_metadata = client.file(file_id='12345').metadata(scope='global', template='boxSkillsCards') card = { "type": "skill_card", "skill_card_type": "keyword", "skill_card_title": { "code": "license-plates", "message": "Licence Plates" }, "skill": { "type": "service" "id": "license-plates-service" }, "invocation": { "type": "skill_invocation" "id": "license-plates-service-123" }, "entries": { { "text": "DD-26-YT" }, { "text": "DN86 BOX" } } } updates = file_metadata.start_update() updates.replace('/cards/0', card) file_metadata.update(updates) ``` ``` BoxFile file = new BoxFile(api, "12345"); Metadata metadata = new Metadata() file.updateMetadata("global", "boxSkillsCards", metadata); ``` ``` var card = new Dictionary<string, object>() { "type": "skill_card", "skill_card_type": "keyword", "skill_card_title": { "code": "license-plates", "message": "Licence Plates" }, "skill": { "type": "service" "id": "license-plates-service" }, "invocation": { "type": "skill_invocation" "id": "license-plates-service-123" }, "entries": { { "text": "DD-26-YT" }, { "text": "DN86 BOX" } } }; var updates = new List<BoxMetadataUpdate>() { new BoxMetadataUpdate() { Op = MetadataUpdateOp.replace, Path = "/cards/0", Value = card } }; Dictionary<string, object> updatedMetadata = await client.MetadataManager .UpdateFileMetadataAsync("12345", updates, "global", "boxSkillsCards"); ``` **Source:** [https://ja.developer.box.com/guides/skills/handle/metadata/](https://ja.developer.box.com/guides/skills/handle/metadata/) --- ### Skillsペイロードの処理 **Type:** guide | **Category:** Box Skills | **Section:** Developer Guides Skillsペイロードの処理 呼び出しURLとして設定されているアプリケーションまたはサイト内では、一般に以下の2つのタスクを行う必要があります。 Skillペイロードを処理する - Box Skills… # Skillsペイロードの処理 [呼び出しURL](guide://skills/invocation-url)として設定されているアプリケーションまたはサイト内では、一般に以下の2つのタスクを行う必要があります。 - [Skillペイロードを処理する](guide://skills/handle/payload) - Box Skillsは、新しいファイルがフォルダにアップロード、コピー、または移動されたことを検出するたびに、呼び出しURLにJSON通知を送信します。このURLは解析する必要があります。 - [ファイルにスキルカードを適用する](guide://skills/handle/metadata) - 処理サービスから返されたメタデータを、イベントをトリガーしたファイルにメタデータとして保存する必要があります。 **Source:** [https://ja.developer.box.com/guides/skills/handle/](https://ja.developer.box.com/guides/skills/handle/) --- ### Slackイベントの処理 **Type:** quick-start | **Category:** コラボレーション | **Section:** Developer Guides Slackイベントの処理 アプリケーションのスキャフォールドを設定したら、次に、User Eventの処理機能と、Slackから送信されるスラッシュコマンドの処理機能を構築します。最終的に、これらの機能はそれぞれBox API… # Slackイベントの処理 アプリケーションのスキャフォールドを設定したら、次に、User Eventの処理機能と、Slackから送信されるスラッシュコマンドの処理機能を構築します。最終的に、これらの機能はそれぞれBox APIエンドポイントに渡されて、グループおよびコンテンツのコラボレーションタスクを実行します。 この手順では、直前の手順で作成した空の関数を拡張します。これらの関数では、以下のタスクを実行します。 - Slackからの新しいイベントとスラッシュコマンドをリッスンする - これらのイベントとコマンドを処理して適切な関数に送る - ボットが初めてチャンネルに追加されたときにBoxグループに追加されるようにチャンネル内のすべてのSlackユーザーを処理する - Slackユーザーのプロフィール情報を取得してそのメールアドレスを取得する ## Slackイベントのリッスン Slackアプリケーションを構成したときに、3つのイベントのアプリケーションコードにイベントを送信するようSlackアプリケーションに指示しました。 - ユーザーがチャンネルに参加したとき。 - ユーザーがチャンネルから退出したとき。 - ユーザーが`/boxadd`スラッシュコマンドを入力したとき。 このアプリケーションには、Slackからのこれらのメッセージをリッスンする公開ルートが必要です。このメッセージのペイロードは、次のようになります。 ``` { "token": "cF1PwB1eIMcRHZWwFHJR1tgs", "team_id": "T932DQSV12P", "team_domain": "slacktest", "channel_id": "C078N43MFHU", "channel_name": "bottest", "user_id": "U016JCDPN56", "user_name": "testuser", "command": "/boxadd", "text": "file 123456", "response_url": "https://hooks.slack.com/commands/T541DQSV12P/3977594927231/ankvsRb42WKnKPRp002FeyTx", "trigger_id": "1189442196855.1183332180295.cca20c3ca1ea193dab432ad8e9e95431" } ``` ``` { "token": "cF1PwB1eIMcRHZWwFHJR1tgs", "team_id": "T932DQSV12P", "api_app_id": "A321V573PQT", "event": { "type": "member_joined_channel", "user": "U0431JM4RLZ", "channel": "C078N43MFHU", "channel_type": "C", "team": "T932DQSV12P", "inviter": "U016JCDPN56", "event_ts": "1592858788.000700" }, "type": "event_callback", "event_id": "Ev032NRJYASJ", "event_time": 1592858788, "authed_users": [ "U0431JM4RLZ" ] } ``` ``` { "token": "cF1PwB1eIMcRHZWwFHJR1tgs", "team_id": "T932DQSV12P", "api_app_id": "A321V573PQT", "event": { "type": "member_left_channel", "user": "U0431JM4RLZ", "channel": "C078N43MFHU", "channel_type": "C", "team": "T932DQSV12P", "event_ts": "1593033236.000600" }, "type": "event_callback", "event_id": "Ev032NRJYASJ", "event_time": 1593033236, "authed_users": [ "U0431JM4RLZ" ] } ``` これらのイベントの処理を開始するには、任意のエディタに`process.js`を読み込み、`app.post("/event" ...`リスナーを次の内容に置き換えます。 ``` app.post("/event", (req, res) => { if (req.body.token !== slackConfig.verificationToken) { res.send("Slack Verification Failed"); } handler.process(res, req.body); }); ``` イベントが成功すると、リスナーではSlackアプリケーションからの確認トークンを使用して、メッセージがSlackから届いたことを確認します。メッセージが有効なリクエストであれば、イベントペイロードがイベント処理関数に送信されます。 任意のエディタに`Application.java`を読み込み、`@PostMapping("/event")`ブロックを次の内容に置き換えます。 ``` @PostMapping("/event") @ResponseBody public void handleEvent(@RequestBody String data, @RequestHeader("Content-Type") String contentType, HttpServletResponse response) throws Exception { int code = HttpServletResponse.SC_OK; java.io.PrintWriter wr = response.getWriter(); response.setStatus(code); if (contentType.startsWith(MediaType.APPLICATION_JSON_VALUE)) { wr.write("Adding content to group"); } else { wr.print(response); } wr.flush(); wr.close(); if (! contentType.startsWith(MediaType.APPLICATION_JSON_VALUE)) { JSONObject returnJSON = new JSONObject(); String[] inputParts = data.split("&"); for (String part: inputParts) { String[] keyval = part.split("="); try { keyval[1] = java.net.URLDecoder.decode(keyval[1], StandardCharsets.UTF_8.name()); } catch (UnsupportedEncodingException e) { System.err.println(e); } returnJSON.put(keyval[0], keyval[1]); } data = returnJSON.toString(); } processEvent(data); } ``` イベントが成功すると、ハンドラは、コードを処理する前に、直ちにHTTP200レスポンスを返します。スラッシュコマンドはURLでエンコードされた文字列として送信されるのに対し、メンバーの参加/退出イベントはJSONとして送信されます。スラッシュコマンドが検出されると、処理中のメッセージで応答します。それ以外の場合は、`HttpServletResponse`レスポンスを送信します。 この例では、イベントがすべて処理される前に`HTTP 200`レスポンスが送信されます。その理由は、Slackではイベントの送信後3秒以内にレスポンスを必要とするためです。コードの実行時間が3秒を超える場合は、重複したイベントがSlackによって送信されます。 イベント処理を容易にするには、すべてのイベントオブジェクトをJSONに標準化します。コンテンツタイプがJSONでない場合は、URLでエンコードされた文字列になります。それが検出されると、その文字列は、JSONオブジェクトに変換されてから`processEvent`に送信されます。 `processEvent`を以下の内容に置き換えます。 ``` @Async public void processEvent(String data) throws Exception { Object dataObj = new JSONParser().parse(data); JSONObject inputJSON = (JSONObject) dataObj; String token = (String) inputJSON.get("token"); if (token.equals(slackConfig.verificationToken)) { // INSTANTIATE BOX CLIENT process(inputJSON); } else { System.err.println("Invalid event source"); } } ``` このメソッドは、JSONイベント文字列をJSONオブジェクトに変換した後、確認トークンを比較して、イベントがSlackから送信されたかどうかを確認します。有効な場合は、イベントが`process`に転送されます。 # 前の手順が完了していません 最初に、手順1でお好みの言語/フレームワークを選択してください。 ## Slackイベントの処理 次に、受信したイベントを判定し、アプリケーションの適切な機能にそのイベントを渡します。 `process`関数を次の内容に置き換えます。 ``` function process(res, data) { if (data.type && data.type === "event_callback") { const eventType = data.event.type; const channel = data.event.channel; const userId = data.event.user; getSlackUser(userId, function (user) { processUser(user, eventType, channel); }); res.send(); } else if (data.command && data.command === "/boxadd") { const [itemType, itemId] = data.text.split(" "); if (["file", "folder"].includes(itemType) && !isNaN(itemId)) { const userId = data.user_id; getSlackUser(userId, function (user) { processContent(user, data.channel_id, itemType, itemId); }); res.send("Adding content"); } else { res.send("Invalid input. Example usage: /boxadd file 123456"); } } else { res.send("Invalid action"); } } ``` この関数の目的は、SlackからのペイロードがUser Eventとスラッシュコマンドのどちらであるかを判断し、必要な情報をすべて取得して、結果を処理するために適切な関数に転送することです。 ペイロードがUser Eventの場合 (`event_callback`に設定されている`data.type`によって示されます)、いくつかの情報を抽出します。 - `eventType`: ユーザーがチャンネルから退出する (`member_left_channel`) かチャンネルに参加する (`member_joined_channel`) かを決定するイベントのタイプ。 - `channel`: チャンネルID。Boxグループ名として使用されます。 - `userId`: ユーザーのID。同じメールアドレスを使用するBoxのユーザープロフィールにバインドされるプロフィールのメールアドレスを検索するためのものです。 その後、process関数は`getSlackUser`を呼び出してユーザーのプロフィールを取得します。取得したユーザープロフィールは`processUser`関数に送信され、Boxグループでユーザーが追加または削除されます。 ペイロードがスラッシュコマンドの場合 (`/boxadd`に設定されている`data.command`によって示されます)、`file 1234`のように、Box IDとファイルかフォルダかを表すコマンドのコンテンツは抽出され、個々の値を取得するために分割されます。これらの値は、適切なコンテンツであるかどうかが検証されます。 検証後、Slackユーザーのプロフィールは、メールアドレスを取得するために取得されます。その後、このユーザープロフィールは、BoxグループとBoxコンテンツでコラボレーションするために`processContent`に送信され、すべてのユーザーにアクセス権限が付与されます。 この手順でSlackユーザーのメールアドレスを取得する理由は、ファイルまたはフォルダの所有者がアプリケーションのサービスアカウントではなくユーザーであるためです。(コラボレーションの作成によって) コンテンツを共有する際は、そのファイルまたはフォルダに対して共有権限を持つユーザーが操作を行う必要があります。そのため、Slackユーザーの代理でコラボレーションを作成できるように、SlackユーザーのメールアドレスをBoxユーザーのメールアドレスと照合する必要があります。 `process`メソッドを次の内容に置き換えます。 ``` public void process(JSONObject inputJSON) throws Exception { if (inputJSON.containsKey("event")) { JSONObject event = (JSONObject) inputJSON.get("event"); String eventType = (String) event.get("type"); String eventUserId = (String) event.get("user"); String eventChannel = (String) event.get("channel"); processUser(getSlackUser(eventUserId), eventType, eventChannel); } else if (inputJSON.containsKey("command")) { String eventCommand = (String) inputJSON.get("command"); if (eventCommand.equals("/boxadd")) { String eventChannelId = (String) inputJSON.get("channel_id"); String eventUserId = (String) inputJSON.get("user_id"); String cInput = (String) inputJSON.get("text"); String[] cInputParts = cInput.split(" "); if (cInputParts[0].matches("file|folder")) { processContent(getSlackUser(eventUserId), eventChannelId, cInputParts[0], cInputParts[1]); } } } else { System.err.println("Invalid event action"); } } ``` このメソッドの目的は、SlackからのペイロードがUser Eventとスラッシュコマンドのどちらであるかを判断し、必要な情報をすべて取得して、結果を処理するために適切なメソッドに転送することです。 ペイロードがUser Eventの場合 (JSONペイロードに存在するイベントノードによって示されます)、いくつかの情報を抽出します。 - `eventType`: ユーザーがチャンネルから退出する (`member_left_channel`) かチャンネルに参加する (`member_joined_channel`) かを決定するイベントのタイプ。 - `eventUserId`: ユーザーのID。同じメールアドレスを使用するBoxのユーザープロフィールにバインドされるプロフィールのメールアドレスを検索するためのものです。 - `eventChannel`: チャンネルID。Boxグループ名として使用されます。 その後、`processUser`に転送し、`getSlackUser`メソッドからの戻り値 (ユーザーオブジェクト)、イベントのタイプ、チャンネルを渡します。 ペイロードがスラッシュコマンドの場合 (JSONペイロードに存在する`command`ノードによって示されます)、いくつかの情報を抽出します。 - `eventChannelId`: Boxグループ名として使用するSlackチャンネルID。 - `eventUserId`: コマンドを発行したユーザーのID。 - `cInputParts`: `file 1234`などの文字列からのコマンド入力のタイプとID。 その後、`processContent`に転送し、`getSlackUser`メソッドからの戻り値 (ユーザーオブジェクト)、チャンネルID、コンテンツタイプ (ファイルまたはフォルダ)、およびBoxに保存されているファイルまたはフォルダのコンテンツIDを渡します。 # 前の手順が完了していません 最初に、手順1でお好みの言語/フレームワークを選択してください。 ## Slackユーザーの処理 次に、User Eventの処理方法を定義する必要があります。ここで説明すべきイベントは以下の3つです。 - ボットがチャンネルに追加された。 - 通常のユーザーがチャンネルに参加した。 - 通常のユーザーがチャンネルから退出した。 `processUser`関数を次の内容に置き換えます。 ``` function processUser(user, event, channel) { getGroupId(channel, function (groupId) { // if bot was added, add all channel users if (user.is_bot) { processSlackChannel(channel, groupId); } else if ( user.profile && user.profile.email && event === "member_joined_channel" ) { addGroupUser(groupId, user.profile.email); } else if ( user.profile && user.profile.email && event === "member_left_channel" ) { removeGroupUser(groupId, user.profile.email); } }); } ``` `processUser`メソッドを次の内容に置き換えます。 ``` public void processUser(JSONObject userResponse, String event, String channel) throws Exception { String groupId = getGroupId(channel); JSONObject userObj = (JSONObject) userResponse.get("user"); Boolean isBot = (Boolean) userObj.get("is_bot"); JSONObject userProfile = (JSONObject) userObj.get("profile"); String userEmail = (String) userProfile.get("email"); if (isBot) { processSlackChannel(channel, groupId); } else if (event.equals("member_joined_channel")) { addGroupUser(groupId, userEmail); } else if (event.equals("member_left_channel")) { removeGroupUser(groupId, userEmail); } } ``` # 前の手順が完了していません 最初に、手順1でお好みの言語/フレームワークを選択してください。 このコードでは、最初に、この次の手順で定義するチャンネルのBoxグループIDを取得します。取得後、以下のようにユーザーが処理されます。 - ユーザーがボットの場合は、Boxグループを初期化し、チャンネルの現在のユーザーをすべてBoxユーザーとしてグループに追加する必要があります。これは、既存のチャンネルに追加されるボットを構成するためです。この処理は、以前ユーザーが存在していたチャンネルにボットが再度追加される場合には無視されます。 - ユーザーがチャンネルに参加した場合は、グループにユーザーを追加する必要があります。 - ユーザーがチャンネルから退出した場合は、グループからユーザーを削除する必要があります。 ## Slackチャンネルユーザーの処理 ボットは、初めてチャンネルに追加されたときに、現在チャンネルに含まれている全ユーザーのリストを取得し、そのユーザーを含むBoxグループを作成してチャンネルの基礎を作成する必要があります。 `processSlackChannel`関数を次の内容に置き換えます。 ``` function processSlackChannel(channel, groupId) { const limit = 100; const channelUsersPath = `https://slack.com/api/conversations.members?token=${slackConfig.botToken}&channel=${channel}&limit=${limit}`; axios.get(channelUsersPath).then((response) => { response.data.members.forEach((uid) => { getSlackUser(uid, function (user) { if (user.profile.email && !user.is_bot) { addGroupUser(groupId, user.profile.email); } }); }); }); } ``` `processSlackChannel`メソッドを次の内容に置き換えます。 ``` public void processSlackChannel(String channel, String groupId) throws Exception { String limit = "100"; String channelUsersPath = String.format("%s/conversations.members?token=%s&channel=%s&limit=%s", slackConfig.slackApiUrl, slackConfig.botToken, channel, limit); JSONObject channelUserList = sendGETRequest(channelUsersPath); JSONArray channelUserIds = (JSONArray) channelUserList.get("members"); @SuppressWarnings("rawtypes") Iterator i = channelUserIds.iterator(); while(i.hasNext()) { String uid = (String)i.next(); JSONObject userResponse = (JSONObject) getSlackUser(uid.toString()); JSONObject userObj = (JSONObject) userResponse.get("user"); JSONObject userProfile = (JSONObject) userObj.get("profile"); Boolean isBot = (Boolean) userObj.get("is_bot"); String userEmail = new String(); if (!isBot) { userEmail = (String) userProfile.get("email"); } if (!userEmail.isEmpty() && !isBot) { addGroupUser(groupId, userEmail); } } } ``` # 前の手順が完了していません 最初に、手順1でお好みの言語/フレームワークを選択してください。 このコードは、複数の処理を順番に実行します。 - 最初に、Slack APIを呼び出し、チャンネルのすべてのメンバーを取得します。 - `limit`を調整して、チャネルのユーザーをさらに収集できます。 - 見つかったユーザーごとに、`getSlackUser`を呼び出してそのユーザーのプロフィールを取得し、メールアドレスをBoxユーザーのメールアドレスにマップできます。 - 各ユーザーは`addGroupUser`に送信され、グループに追加されます。 ## Slackユーザープロフィールの取得 Slackに関連した最後の関数は、他の関数によって使用されるユーティリティメカニズムです。この関数は、Slack APIを呼び出して、Slackイベント/コマンドが提供するユーザーIDまたはチャンネルユーザーのリストを取得したときに提供されるユーザーIDが指定されたユーザープロフィールを取得します。メールアドレスを使用してSlackユーザーをBoxユーザーと照合しているため、ユーザープロフィールの検索では、メールアドレスのフィールドに注意します。 Boxのメールアドレスは一意であり、複数のアカウントに使用することはできません。つまり、ユーザーアカウントの検索に使用すると効果的です。 `getSlackUser`関数を次の内容に置き換えます。 ``` function getSlackUser(userId, callback) { const userPath = `https://slack.com/api/users.info?token=${slackConfig.botToken}&user=${userId}`; axios.get(userPath).then((response) => { if (response.data.user && response.data.user.profile) { callback(response.data.user); } else { console.log("No user data found"); } }); } ``` この関数では、Slackユーザープロフィールエンドポイントを呼び出した後、指定したコールバックにユーザープロフィール情報 (有効な場合) を送信します。 `getSlackUser`メソッドを次の内容に置き換えます。 ``` public JSONObject getSlackUser(String userId) throws Exception { String usersPath = String.format("%s/users.info?token=%s&user=%s", slackConfig.slackApiUrl, slackConfig.botToken, userId); return sendGETRequest(usersPath); } ``` このメソッドでは、ユーザープロフィールを取得するようSlackにリクエストを送信した後、そのリクエストのレスポンスを返します。このレスポンスはユーザープロフィールJSONオブジェクトになります。 # 前の手順が完了していません 最初に、手順1でお好みの言語/フレームワークを選択してください。 ## まとめ - 受信イベントを確認し、処理するために転送しました。 - イベントを処理し、適切な関数に転送しました。 - チャンネル内のすべてのユーザーを処理する関数と1人のユーザーのSlackプロフィールを取得する関数を実装しました。 Slackの関数を設定しました **Source:** [https://ja.developer.box.com/guides/collaborations/connect-slack-to-group-collabs/handle-slack-events/](https://ja.developer.box.com/guides/collaborations/connect-slack-to-group-collabs/handle-slack-events/) --- ### Slackの構成 **Type:** quick-start | **Category:** コラボレーション | **Section:** Developer Guides Slackの構成 このガイドの最初の手順では、Slackアプリケーションを作成して構成します。このSlackアプリケーションは、SlackチャンネルでUser Event… # Slackの構成 このガイドの最初の手順では、Slackアプリケーションを作成して構成します。このSlackアプリケーションは、SlackチャンネルでUser Eventをリッスンするボットとして機能し、そのチャンネルでユーザーが入力した**スラッシュコマンド**に応答します。これにより、ユーザーはBox上のファイルやフォルダをグループと共有できます。 このセクションでは、以下の手順を説明します。 - Slack APIダッシュボード内で最小限のSlackアプリケーションを作成します。 - ユーザーがチャンネルに参加したりチャンネルから退出したりするたびにBoxのアプリケーションに通知が送信されるようSlackアプリケーションを構成し、BoxのコードでBoxグループを更新できるようにします。 - Boxのファイルやフォルダをチャンネル内のすべてのユーザーと共有できるようにする`/boxadd`**スラッシュコマンド**を構成します。 ## 最小限のSlackアプリの作成 **[Slackアプリのページ](https://api.slack.com/apps)**に移動し、[**Create an App (アプリの作成)**] をクリックします。[**App Name (アプリ名)**] を追加し、ボットの展開先となる [**Development Slack Workspace (開発Slackワークスペース)**] をドロップダウンリストから選択し、[**Create App (アプリの作成)**] をクリックします。 作成後、アプリケーションの基本情報セクションにリダイレクトされます。下部の [**Display Information (情報の表示)**] セクションで、作成したアプリのアイコンと説明を調整して、ワークスペースでアプリケーションをカスタマイズできます。 ## Slackアプリのイベントリスナーの構成 Slackアプリ用のイベントリスナーを設定すると、チャンネル内のイベントを監視できます。このボットでは、Box内で操作を実行するために、3つの[Slackイベント](https://api.slack.com/events)を監視します。 - [`bot_added`](https://api.slack.com/events/bot_added): ボットは、最初にチャンネルに追加されたときに、チャンネル内の全ユーザーのリストを取得し、取得したユーザーのBoxグループを作成します。このグループは、**スラッシュコマンド**で共有される任意のコンテンツにそのグループを追加するために後で使用できます。 - [`member_joined_channel`](https://api.slack.com/events/member_joined_channel): 新しいユーザーは、Slackチャンネルに参加したときにBoxグループに追加されます。 - [`member_left_channel`](https://api.slack.com/events/member_left_channel): ユーザーはSlackチャンネルから退出したときや削除されたときに、Boxグループから削除されます。 このようなSlackのイベントペイロードの送信先となる通知URLを設定するために、Slackでは確認手順が必要になります。ボットアプリケーションコードのイベントリスナーURLを設定すると、Slackは即座にそのURLにチャレンジを送信し、そのURLが有効かどうかを確認します。これは、次のようなペイロードを含むHTTP POSTです。 ``` { "token": "Jhj5dZrVaK7ZwHHjRyZWjbDl", "challenge": "3eZbrw1aBm2rZgRNFdxV2595E9CY3gmdALWMmHkvFXO7tYXAYM8P", "type": "url_verification" } ``` イベントリスナーのURLを設定するには、この手順の間に、設定するURLが、チャレンジ値を含む確認用ペイロードを使用してSlackに応答する必要があります。ペイロードは次のようになります。 ``` HTTP 200 OK Content-type: application/json {"challenge":"3eZbrw1aBm2rZgRNFdxV2595E9CY3gmdALWMmHkvFXO7tYXAYM8P"} ``` このためには、チャレンジイベントに応答する少量のコードを展開します。最初に、以下の中からお好みの言語/フレームワークを選択してください。 # Node (Expressフレームワーク) # Java (Spring Bootフレームワーク) プロジェクトディレクトリ内で`npm install express --save`を実行してExpressの依存関係をインストールし、次のコードを適切なNodeモジュールとともに公開エンドポイントに展開します。 ``` const express = require('express'); const app = express(); const port = process.env.PORT || 3000; app.use(express.urlencoded({ extended: true })); app.use(express.json()); app.post('/event', (req, res) => { if ( req.body && req.body.challenge && req.body.type === 'url_verification' ) { res.send({ challenge: req.body.challenge }); } else { res.status(400).send({ error: "Unrecognized request" }); } }); app.listen(port, function(err) { console.log("Server listening on PORT", port); }); ``` [`Spring Initializr`](https://start.spring.io/)は、すべての依存関係が定義された状態の新しいSpring Bootアプリケーションを自動生成するのに便利なサービスです。これは、空のJavaアプリケーションを作成する代わりに使用できます。 - Eclipseで新しいプロジェクトを作成します。求められたら、Gradleプロジェクトを選択します。 - プロジェクトの一意の名前を入力します。このガイドでは`slack.box`という名前を使用しています。 - `build.gradle`ファイルを開いて以下を追加します。アプリケーションに使用したグループとこのグループが一致することを確認します。保存したら、Gradleプロジェクトを更新します。 ``` plugins { id 'org.springframework.boot' version '2.3.1.RELEASE' id 'io.spring.dependency-management' version '1.0.9.RELEASE' id 'java' } group = 'com.box' version = '0.0.1-SNAPSHOT' sourceCompatibility = '1.8' repositories { mavenCentral() } dependencies { implementation 'org.springframework.boot:spring-boot-starter-web' testImplementation('org.springframework.boot:spring-boot-starter-test') { exclude group: 'org.junit.vintage', module: 'junit-vintage-engine' } compile 'com.box:box-java-sdk:2.44.1' } test { useJUnitPlatform() } ``` - `src/main/java`パスに、`Application.java`という名前の新しいJavaクラスファイルを作成します。 - このファイルを開き、次のコードを追加して保存します。 ``` package com.box.slack.box; import org.jose4j.json.internal.json_simple.JSONObject; import org.jose4j.json.internal.json_simple.parser.JSONParser; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.EnableAutoConfiguration; import org.springframework.web.bind.annotation.PostMapping; import org.springframework.web.bind.annotation.RequestBody; import org.springframework.web.bind.annotation.RestController; @RestController @EnableAutoConfiguration public class Application { @PostMapping("/event") public JSONObject challenge(@RequestBody String data) throws Exception { JSONObject returnJSON = new JSONObject(); Object dataObj = new JSONParser().parse(data); JSONObject inputJSON = (JSONObject) dataObj; String challenge = (String) inputJSON.get("challenge"); String type = (String) inputJSON.get("type"); if (type.equals("url_verification")) { returnJSON.put("challenge", challenge); } else { System.err.println("Invalid input"); } return returnJSON; } public static void main(String[] args) { SpringApplication.run(Application.class, args); } } ``` # 前の手順が完了していません 最初に、上記の中からお好みの言語/フレームワークを選択してください。 これで、イベントURLの追加時にSlackチャレンジに応答するコードを準備できたので、これをSlackアプリケーション内で構成できます。 Slackアプリケーションの [**Basic Information (基本情報)**] タブの [**Add features and functionality (機能の追加)**] で、[**Event Subscriptions (イベントサブスクリプション)**] というタイトルのボタンをクリックし、以下の操作を行います。 - [**Enable Events (イベントの有効化)**] を [**On (オン)**] に切り替えます。 - [**Request URL (リクエストURL)**] で、上記のコードを展開した公開URLを追加し、`{YOUR_APP_DOMAIN}/event` (`https://myapp.com/event`など) でリッスンしていることに注意します。URLを追加し、フィールドの外をクリックすると、Slackはすぐに、上記でコードをホストしていたURLにチャレンジを送信します。コードが正しく応答した場合は、[**Request URL (リクエストURL)**] ヘッダーの横に緑色で確認済みであることが表示されます。 - [**Subscribe to bot events (Bot Eventの購読)**] セクションを展開し、[**Add Bot User Event (Bot User Eventの追加)**] ボタンをクリックします。 - ボットが登録されているイベントに`member_joined_channel`と`member_left_channel`を追加します。これらは、新しいユーザーがチャンネルに追加されたときにイベントを送信します。 - ページの下部にある [**Save Changes (変更を保存)**] ボタンをクリックします。 ## Slackアプリのスラッシュコマンドの構成 Slackチャンネルの各ユーザーにBox内のファイルやフォルダへのアクセス権限を付与するために、Slackの**「スラッシュコマンド」**を使用できます。スラッシュコマンドにより、チャンネル内のどのユーザーも、Box内に所有しているコンテンツをチャンネルの他のユーザーと共有できます。 このコマンドを使用すると、チャンネルのメンバーはチャネルに`/boxadd [file / folder] [id]` (`boxadd file 1459732312`など) を入力してファイル/フォルダをそのチャンネルのすべてのユーザーと共有できます。そのために、ファイルはそのチャンネル内に存在するBoxグループのユーザーと自動的にコラボレーションされます。 作成したアプリケーションの [**Basic Information (基本情報)**] タブの [**Add features and functionality (機能の追加)**] で [**Slash Commands (スラッシュコマンド)**] というタイトルのボタンをクリックします。 表示されるページで、[**Create New Command (新しいコマンドの作成)**] をクリックして、以下の項目を入力します。 - **Command (コマンド)**: チャンネルユーザーがBoxのファイル/フォルダIDをチャンネルと共有するために使用するコマンドです。このクイックスタートでは、`/boxadd`を使用します。 - **Request URL (リクエストURL)**: Slackボットでスラッシュコマンドをリッスンし、そのコマンドに応答するURL。このクイックスタートでは、前述のアプリのイベントリスナーのセクションで使用したのと同じイベントURLを使用します。 - **Short Description (簡単な説明)**: スラッシュコマンドで実行する処理の説明。 - **Usage Hint (使用方法のヒント)**: このコマンドに渡すことができる追加のパラメータ。この例では、Boxのファイル/フォルダIDとコンテンツのタイプを使用します。 [**Save (保存)**] をクリックして、このコマンドをSlackアプリに追加します。 ## その他のスコープの追加 Slackからアプリケーションに送信されるスラッシュコマンドまたは通知には、操作を行ったユーザーまたは操作の影響を受けたユーザーに関連するSlackユーザーIDが含まれます。そのIDをBoxユーザーに変換するには、Slackユーザーのメールアドレスを取得する必要があります。取得したメールアドレスを使用して、そのSlackユーザーを対応するBoxユーザーに関連付けることができます。この操作を行うには、Slackアプリケーションの構成で2つのスコープを追加する必要があります。 Slackアプリケーションの構成で、左側のメニューにある [**OAuth & Permissions (OAuthと権限)**] をクリックし、以下の操作を行います。 - [**Scopes (スコープ)**] セクションまで下にスクロールします。 - [**Bot Token Scopes (ボットトークンのスコープ)**] で [**Add an OAuth Scope (OAuthスコープの追加)**] ボタンをクリックします。 - `users:read`と`users:read.email`を検索して追加します。 ## Slackワークスペースへのボットの展開 最後に、Slackワークスペースにこのアプリケーションをインストールします。アプリの [**Basic Information (基本情報)**] ページで、[**Install your app to your workspace (ワークスペースに自分のアプリをインストール)**] セクションを展開します。 [**Install App to Workspace (ワークスペースにアプリをインストール)**] ボタンをクリックします。 [**Allow (許可)**] ボタンをクリックすると、成功を示すメッセージが表示されます。これでワークスペース内にボットがインストールされました。 ## まとめ - Slackアプリケーションを作成しました。 - User Event通知、スラッシュコマンド、追加のスコープを構成しました。 - Slackボットをワークスペースに展開しました。 ローカルアプリケーションの設定が完了しました **Source:** [https://ja.developer.box.com/guides/collaborations/connect-slack-to-group-collabs/configure-slack/](https://ja.developer.box.com/guides/collaborations/connect-slack-to-group-collabs/configure-slack/) --- ### Slack統合フォルダマッピングの管理 **Type:** guide | **Category:** CLI | **Section:** Developer Guides Slack統合フォルダマッピングの管理 このスクリプトは、BoxをSlackのコンテンツストアとして使用している場合に、SlackとBox間のフォルダマッピングの管理に役立ちます。現在のSlackチャンネルとBoxフォルダのマッピングのリストが作成されるため、入力用のcsv… # Slack統合フォルダマッピングの管理 このスクリプトは、BoxをSlackのコンテンツストアとして使用している場合に、SlackとBox間のフォルダマッピングの管理に役立ちます。現在のSlackチャンネルとBoxフォルダのマッピングのリストが作成されるため、入力用のcsvに基づいてマッピングを作成または更新できます。このスクリプトではすべての権限が維持されます。 詳細については、[GitHubリポジトリ](https://github.com/box/boxcli/tree/main/examples/Integration%20Mappings)で確認できます。 ## 前提条件 ### スクリプトの複製 このGitHubリポジトリを複製するか、`/examples`ディレクトリからファイルをダウンロードします ``` git clone https://github.com/box/boxcli.git ``` ### Windows [.NET Core](https://dotnet.microsoft.com/download)の最新バージョンのインストール ### macOSおよびLinux [PowerShell](https://docs.microsoft.com/en-us/powershell/scripting/install/installing-powershell?view=powershell-7.2)をインストールします。`pwsh`コマンドを実行して、インストール結果をテストします。 ``` pwsh ``` どのディレクトリでこのコマンドを実行するかに応じて、出力が異なる場合があります。以下に例を示します。 ``` PowerShell 7.2.5 Copyright (c) Microsoft Corporation. https://aka.ms/powershell Type 'help' to get help. PS /Users/user/repos/boxcli/examples> ``` 問題が発生する場合は、[.NET Core](https://dotnet.microsoft.com/download)と[PowerShell](https://docs.microsoft.com/en-us/powershell/scripting/install/installing-powershell?view=powershell-7.2)の両方をインストールしたかどうか確認してください。 ### Box CLIのインストール OAuth [CLIの設定クイックスタート](g://cli/quick-start)を使用して、Box CLIを構成してインストールします。使用しているユーザーが管理者または共同管理者であることを確認してください。 ### Enterprise構成 - 適切なSlackワークスペースやオーガナイゼーションで[Box for Slackを構成してインストール](https://support.box.com/hc/en-us/articles/360044195313-Installing-and-Using-the-Box-for-Slack-Integration)します - [Slackのコンテンツレイヤー](https://support.box.com/hc/en-us/articles/4415585987859-Box-as-the-Content-Layer-for-Slack)としてのBoxが有効になっています ## スクリプトの実行 ディレクトリを、スクリプトが格納されているフォルダに変更します。この例では、`Integration Mappings`フォルダになります。 ``` rvb@lab:~/box-cli/examples/Integration Mappings$ pwsh PowerShell 7.2.4 Copyright (c) Microsoft Corporation. https://aka.ms/powershell Type 'help' to get help. PS /home/rvb/box-cli/examples/Integration Mappings> ``` EXTRACTを指定してスクリプトを実行すると、現在のマッピングが抽出されます: ``` ./integration-mappings.ps1 -Action EXTRACT ``` または UPDATEを指定してスクリプトを実行すると、現在のマッピングが更新されます: ``` ./integration-mappings.ps1 -Action UPDATE ``` または CREATEを指定してスクリプトを実行すると、新しいマッピングが作成されます: ``` ./integration-mappings.ps1 -Action CREATE -MappingPath ./mapping_create_example.csv ``` デフォルトでは、csvファイルが./mappings.csvに保存され、./mappings.csvから読み込まれます。この場所を変更する場合は、次のように新しいパスを渡します: ``` ./integration-mappings.ps1 -Action EXTRACT -MappingPath ./mappings_new_location.csv ``` パラメータを指定しなかった場合は、スクリプトによって、パラメータを入力するよう求められます。 スクリプトの実行が完了すると、以下のような出力が表示されます。 新しいチャンネルにマッピングを作成する際は、BoxフォルダID、SlackチャンネルID、およびSlackオーガナイゼーションIDを入力する必要があります。オーガナイゼーションIDの代わりにSlackワークスペースIDを使用できます。その場合は、csvの列見出し`SlackOrgId`を`SlackWorkspaceId`に置き換えます。 ``` Starting Process Applying new mappings Output [...] All bulk input entries processed successfully. ``` ## ログ ログは、メインフォルダ内の`logs`フォルダに格納されます。以下のログファイルにアクセスできます。 - `Integration-mappings_all.txt`: すべてのログエントリが含まれています。 - `Integration-mappings_errors.txt`: エラーのみが含まれています。 ## 免責 このプロジェクトは、オープンソースの例を集めたものであるため、公式にサポートされている製品として扱わないでください。Box CLIの使用方法は、自己責任の下、例の情報源として利用してください。 **Source:** [https://ja.developer.box.com/guides/cli/scripts/slack-integration-mappings/](https://ja.developer.box.com/guides/cli/scripts/slack-integration-mappings/) --- ### Slack統合マッピング **Type:** guide | **Category:** 統合マッピング | **Section:** Developer Guides Slack統合マッピング コンテンツレイヤーとしてBoxを有効にすると、各チャンネル用にBoxフォルダが作成され、そのチャンネルにアップロードされたすべてのファイルがこのフォルダに保存されます。統合マッピングAPIを使用すると、Box Enterprise管理者 (EA… # Slack統合マッピング [コンテンツレイヤーとしてBox](https://support.box.com/hc/en-us/articles/4415585987859-Box-as-the-Content-Layer-for-Slack)を有効にすると、各チャンネル用にBoxフォルダが作成され、そのチャンネルにアップロードされたすべてのファイルがこのフォルダに保存されます。[統合マッピングAPI](r://integration-mapping)を使用すると、Box Enterprise管理者 (EA) は、Slackチャンネルのアップロードフォルダをカスタマイズして、デフォルトのフォルダを使用する代わりに企業内の任意のフォルダに変更できます。 **Source:** [https://ja.developer.box.com/guides/integration-mappings/slack-mappings/](https://ja.developer.box.com/guides/integration-mappings/slack-mappings/) --- ### Slack統合マッピングのトラブルシューティング **Type:** guide | **Category:** 統合マッピング | **Section:** Developer Guides Slack統合マッピングのトラブルシューティング 統合マッピングAPI… # Slack統合マッピングのトラブルシューティング 統合マッピングAPIはさまざまな種類の検証を実行するため、いくつかのエラーが発生する場合があります。このような一般的なエラーの説明と解決策については、以下を参照してください。 ## サービスアカウントがフォルダの共同所有者ではない [SlackのコンテンツレイヤーとしてBoxを使用する](https://support.box.com/hc/en-us/articles/4415585987859-Box-as-the-Content-Layer-for-Slack)サービスアカウントは、コラボレーションとアップロードを管理するためにフォルダの所有者または共同所有者として追加する必要があります。 ``` Box as File Storage for Slack (user id: 123, user email: user@example.com) must be a collaborator in role co-owner or owner of the folder example123, before it can be mapped to the channel example123. Please create a collaboration or ensure the ownership for Box as File Storage for Slack and retry.` ``` このエラーを解決するには、レスポンスのデータを使用して、マッピングを実行するための必要なロールがサービスアカウントにあることを確認してください。 ``` "context_info": { "service_account_id": "12345678", "service_account_email": "AutomationUser_12345678_gdueygwe@boxdevedition.com", } ``` 以下の手順を実行します。 1. `context_info`から`service_account_email`をコピーします。 2. フォルダ設定で、`Invite People`オプションを使用して共同所有者としてサービスアカウントを招待します。 ## チャンネルがすでにBoxのフォルダにマッピングされている Boxフォルダがすでにマッピングされているチャンネルに対してマッピングを作成しようとすると、APIから次のエラーが返されます。 ``` Channel: example123 is already mapped to a folder in Box. ``` 新しいフォルダの使用を開始したい場合は、`GET`を使用してマッピングの`id`を取得した後、`UPDATE`メソッドを使用してターゲットのBoxフォルダを更新してください。 ## チャンネルが見つからない 統合に関連付けられているSlackボットでチャンネルに関する情報を取得できない場合は、APIから次のエラーが返されます。 ``` Channel: example123 was not found. If it is a private channel, ensure that Box has been added to the channel. ``` `partner_item`が正しいことを確認します。オーガナイゼーションでのインストールの場合は`slack_org_id`、ワークスペースでのインストールの場合は`slack_workspace_id`を指定していることを確認してください。チャンネルがプライベートの場合は、Slackボットがそのチャンネルに追加されていることを確認します。 ## チャンネルがカスタムファイルストレージ (CFS) に適していない ``` Channel: example123 is not suitable for CFS. Slack Connect channels with a pending Connect status can not be mapped to Box folders. ``` Slackコネクトチャンネル (企業間チャンネル) は、現在、SlackのコンテンツレイヤーとしてBoxを使用する場合にサポートされていません。 ## Boxフォルダが外部で所有されている マッピングに選択したBoxフォルダは、管理者が所属する企業で所有している必要があります。 ``` Box folder: example123 cannot be mapped, because it is externally owned. Mapped folder must belong to the enterprise: example_enterprise. ``` ## カスタムファイルストレージ (CFS) が無効になっている Box for Slackがインストールされているものの、[SlackのコンテンツレイヤーとしてBox](https://support.box.com/hc/en-us/articles/4415585987859-Box-as-the-Content-Layer-for-Slack)が有効になっていない企業に対してマッピングを作成しようとすると、APIからこのエラーが返されます。 ## Box Enterpriseの不一致 管理者のEnterpriseとBox for Slackの構成が一致しない場合、APIからこのエラーが返されます。Box for Slackを有効にする方法については、[Box for Slackのインストールと構成](https://support.box.com/hc/en-us/articles/360044195313-Installing-and-Using-the-Box-for-Slack-Integration)を参照してください。 **Source:** [https://ja.developer.box.com/guides/integration-mappings/slack-mappings/troubleshooting/](https://ja.developer.box.com/guides/integration-mappings/slack-mappings/troubleshooting/) --- ### Slack統合マッピングのリスト取得 **Type:** guide | **Category:** 統合マッピング | **Section:** Developer Guides Slack統合マッピングのリスト取得 GET /integration_mappings/slack呼び出しを使用すると、マッピングを取得してフィルタをかけることができます。管理者が手動で作成したマッピングも、統合によって自動的に作成されたマッピングも対象になります。 # Slack統合マッピングのリスト取得 `GET /integration_mappings/slack`呼び出しを使用すると、マッピングを取得してフィルタをかけることができます。管理者が手動で作成したマッピングも、統合によって自動的に作成されたマッピングも対象になります。 **Source:** [https://ja.developer.box.com/guides/integration-mappings/slack-mappings/list-mappings/](https://ja.developer.box.com/guides/integration-mappings/slack-mappings/list-mappings/) --- ### Slack統合マッピングの作成 **Type:** guide | **Category:** 統合マッピング | **Section:** Developer Guides Slack統合マッピングの作成 POST integration_mappings/slack/:integration_mapping_id呼び出しを使用してマッピングを作成します。この呼び出しを動作させるには、box_itemパラメータとpartner_item… # Slack統合マッピングの作成 `POST integration_mappings/slack/:integration_mapping_id`呼び出しを使用してマッピングを作成します。この呼び出しを動作させるには、`box_item`パラメータと`partner_item`パラメータが必要です。これらのパラメータはそれぞれ、BoxフォルダとSlackチャンネルを示します。 マッピングを作成するには、このサービスアカウントを、マッピングされるフォルダの共同所有者のロールとして設定しておく必要があることに注意してください。エラーが発生した場合は、[トラブルシューティングガイド](g://integration-mappings/slack-mappings/troubleshooting)を参照してください。 作成されたマッピングのデフォルト設定を変更するオプションを指定できます。たとえば、`is_access_management_disabled`を`true`に設定すると、コラボレーションの管理が無効になります。Slackのチャンネルメンバーはチャンネルフォルダのコラボレータにならず、1000人以上のメンバーがいるチャンネルに共有リンクは作成されません。 ## Box SDKによるSlack統合マッピングの作成 Box SDKを使用すると、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 } ``` `PLACEHOLDER`をログに記録された`serviceAccountId`の値に必ず置き換えてください。 **Source:** [https://ja.developer.box.com/guides/integration-mappings/slack-mappings/create-mapping/](https://ja.developer.box.com/guides/integration-mappings/slack-mappings/create-mapping/) --- ### Slack統合マッピングの削除 **Type:** guide | **Category:** 統合マッピング | **Section:** Developer Guides Slack統合マッピングの削除 DELETE integration_mappings/slack/:integration_mapping_id… # Slack統合マッピングの削除 `DELETE integration_mappings/slack/:integration_mapping_id`呼び出しを使用して、チャンネルとフォルダ間のマッピングを削除します。次のファイルがチャンネルにアップロードされると、デフォルトのフォルダ構造で新しいマッピングと新しいフォルダが作成されます。マッピングを削除しても、BoxフォルダもSlackチャンネルも削除されません。 **Source:** [https://ja.developer.box.com/guides/integration-mappings/slack-mappings/delete-mapping/](https://ja.developer.box.com/guides/integration-mappings/slack-mappings/delete-mapping/) --- ### Slack統合マッピングの更新 **Type:** guide | **Category:** 統合マッピング | **Section:** Developer Guides Slack統合マッピングの更新 PUT integration_mappings/slack/:integration_mapping_id呼び出しを使用して、既存のマッピングまたはターゲットのBoxフォルダを更新します。 # Slack統合マッピングの更新 `PUT integration_mappings/slack/:integration_mapping_id`呼び出しを使用して、既存のマッピングまたはターゲットのBoxフォルダを更新します。 **Source:** [https://ja.developer.box.com/guides/integration-mappings/slack-mappings/update-mapping/](https://ja.developer.box.com/guides/integration-mappings/slack-mappings/update-mapping/) --- ### Slack統合マッピングの設定 **Type:** guide | **Category:** 統合マッピング | **Section:** Developer Guides Slack統合マッピングの設定 統合マッピングAPIの使用を開始する前に、以下の手順を実行します。 ロール 管理者または共同管理者のロールが割り当てられていることを確認します。 Box for Slackのインストールと構成 適切なSlack… # Slack統合マッピングの設定 統合マッピングAPIの使用を開始する前に、以下の手順を実行します。 ## ロール 管理者または共同管理者のロールが割り当てられていることを確認します。 ## Box for Slackのインストールと構成 1. 適切なSlackワークスペースまたはオーガナイゼーションに[Box for Slack](https://support.box.com/hc/en-us/articles/360044195313-Installing-and-Using-the-Box-for-Slack-Integration)をインストールします。 2. [SlackのコンテンツレイヤーとしてのBoxの使用](https://support.box.com/hc/en-us/articles/4415585987859-Box-as-the-Content-Layer-for-Slack)を有効にします。 3. 使用しているサービスアカウントが、マッピングされるフォルダのコラボレータであることを確認します。そのためには、`Invite People`フォルダオプションを使用して、サービスアカウントをコラボレータとして招待します。 エラーが発生した場合は、[トラブルシューティングガイド](g://integration-mappings/slack-mappings/troubleshooting)を参照してください。 ## Boxアプリケーションの作成 1. [Box開発者コンソール](https://app.box.com/developers/console)で、[OAuth認証を使用するPlatformアプリ](g://authentication/oauth2/oauth2-setup)を作成します。 2. アプリケーションを開き、[**構成**] > [**必須のアクセススコープ**] で [**Enterpriseのプロパティを管理する**] アプリケーションスコープを有効にします。 Slack側のチャンネル確認のために、[統合マッピングAPI](e://get-integration-mappings-slack)でSlack APIを呼び出します。 ## 承認 統合マッピングリクエストを承認するには、以下の手順を実行します。 1. 前提条件の1つとして作成した[Platformアプリ](g://applications/app-types/platform-apps)に移動します。 2. [開発者トークン](g://authentication/tokens/developer-tokens)を生成し、次のように各リクエストのHTTPヘッダーに追加します。 ``` Authorization: Bearer {developer_token} ``` 開発者トークンの有効期限は60分です。その時間が経過した後は、再度生成する必要があります。 **Source:** [https://ja.developer.box.com/guides/integration-mappings/slack-mappings/setup/](https://ja.developer.box.com/guides/integration-mappings/slack-mappings/setup/) --- ### SSO IDとApp Userの関連付け **Type:** guide | **Category:** SSOとApp User | **Section:** Developer Guides SSO IDとApp Userの関連付け ユーザーがSSOプロバイダの資格情報を使用してカスタムのBoxアプリケーションに初めてサインインするときに、新しいBoxユーザーを作成し、ユーザーのSSOユーザーレコードと関連付ける必要があります。その際、このSSO… # SSO IDとApp Userの関連付け ユーザーがSSOプロバイダの資格情報を使用してカスタムのBoxアプリケーションに初めてサインインするときに、新しいBoxユーザーを作成し、ユーザーのSSOユーザーレコードと関連付ける必要があります。その際、このSSOユーザーレコードの一意の情報の一部を使用します。通常、この2つのアカウントの関連付けに使用されるデータは、一意のIDとメールアドレスのいずれかです。 この関連付けを行うためにBoxアカウントを作成する方法がいくつかあります。 - Boxユーザーの`external_app_user_id`フィールドを使用して、SSOプロバイダの一意のIDを格納します。 - Boxユーザーの`login`フィールドを使用して、SSOプロバイダの一意のメールアドレスを格納します (管理対象ユーザーのみ)。 ## external_app_user_idによる関連付け Boxユーザーレコードの`external_app_user_id`フィールドを使用する方法は、App Userと管理対象ユーザーの両方に使用可能なオプションで、SSOプロバイダのユーザーレコードをBoxユーザーアカウントに関連付ける際に推奨される方法です。 ### App User `external_app_user_id`によってSSOユーザーレコードに関連付けられた新しいBox App Userを作成するには、SSOプロバイダから以下の2つの情報が必要になります。 - UID (必須): SSOユーザーレコードの一意の識別子です。 - 名前 (省略可): レコードの一貫性を保つために、Boxユーザーレコードと関連付けるSSOユーザー名を抽出します。 取得したら、ユーザーパラメータでオプションの`external_app_user_id`定義を指定して、新しいApp Userを作成するリクエストを実行します。 ``` const ssoName = 'SSO User Name'; const ssoUID = 'SSO User Unique ID'; const spaceAmount = 1073741824; // Create app user client.enterprise.addAppUser( ssoName, { space_amount: spaceAmount, external_app_user_id: ssoUID } ).then(appUser => { console.log(`New user created: ${appUser.name}`); }); ``` ``` String ssoName = "SSO User Name"; String ssoUID = "SSO User Unique ID"; // Create app user CreateUserParams params = new CreateUserParams(); params.setExternalAppUserId(ssoUID); BoxUser.Info createdUserInfo = BoxUser.createAppUser(client, ssoName, params); outputString = "New user created: " + createdUserInfo.getName(); ``` ``` sso_name = 'SSO User Name' sso_uid = 'SSO User Unique ID' space = 1073741824 # Create app user user = box_client.create_user(sso_name, None, space_amount=space, external_app_user_id=sso_uid) print('New user created: {name}') ``` ### 管理対象ユーザー `external_app_user_id`によってSSOユーザーレコードに関連付けられた新しい管理対象ユーザーを作成するには、SSOプロバイダから以下の2つの情報が必要になります。 - メールアドレス (必須): SSOユーザーレコードの一意のメールアドレスです。 - 名前 (省略可): レコードの一貫性を保つために、Boxユーザーレコードと関連付けるSSOユーザーを抽出します。 取得したら、ログイン用のSSOユーザーレコードのメールアドレスを指定して、新しい管理対象ユーザーを作成するリクエストを実行します。 ``` const ssoName = 'SSO User Name'; const ssoEmail = 'ssouser@email.com'; const spaceAmount = 1073741824; // Create app user client.enterprise.addUser( ssoEmail, ssoName, { space_amount: spaceAmount } ).then(managedUser => { console.log(`New user created: ${managedUser.name}`); }); ``` ``` String ssoName = "SSO User Name"; String ssoEmail = "ssouser@email.com"; // Create managed user BoxUser.Info createdUserInfo = BoxUser.createEnterpriseUser(client, ssoEmail, ssoName); outputString = "New user created: " + createdUserInfo.getName(); ``` ``` sso_name = 'SSO User Name' sso_email = 'ssouser@email.com' space = 1073741824 # Create managed user user = box_client.create_user(sso_name, sso_email, space_amount=space) print('New user created: {name}') ``` ## メールアドレスによる関連付け SSOユーザーのメールアドレスによって関連付けられている新しい[管理対象ユーザー](page://platform/user-types/#managed-users)の作成は、標準的な管理対象ユーザーの作成プロセスと同じです。 ユーザーは、SSOプロバイダを介してログインした後、まだBoxユーザーとして存在しない場合に、SSOユーザーレコードからメールアドレスを抽出して、新しいBox管理対象ユーザーを作成するリクエストを実行します。 **Source:** [https://ja.developer.box.com/guides/sso-identities-and-app-users/create-app-user/](https://ja.developer.box.com/guides/sso-identities-and-app-users/create-app-user/) --- ### SSO IDのApp Userの検索 **Type:** guide | **Category:** SSOとApp User | **Section:** Developer Guides SSO IDのApp Userの検索 ユーザーがSSOプロバイダを使用してBox Platformアプリケーションにログインする際、まず必要なのは、Boxユーザーレコードが作成された前回のログイン試行から、そのユーザーがすでに存在するかどうかを確認することです。 Box… # SSO IDのApp Userの検索 ユーザーがSSOプロバイダを使用してBox Platformアプリケーションにログインする際、まず必要なのは、Boxユーザーレコードが作成された前回のログイン試行から、そのユーザーがすでに存在するかどうかを確認することです。 Boxユーザーが検出されたら、そのユーザーとしてBox APIにアクセスするために、[ユーザーアクセストークンを作成](guide://authentication/jwt/user-access-tokens)するか[as-user呼び出し](guide://authentication/jwt/as-user)を実行する必要があります。 Boxユーザーが検出されない場合は、そのSSOユーザーレコードに関連付けられた新しいユーザーを作成する必要があります。 既存のユーザーの検索には、[会社ユーザーのリストを取得](e://get-users)エンドポイントを使用できます。`external_app_user_id`と`login`のどちらのメソッドを使用しているかによって、クエリは若干異なります。 ## external_app_user_idを使用したユーザーの検索 格納されている`external_app_user_id`値を使用して会社ユーザーを検索するには、SSOプロバイダの次の情報が必要になります。 - UID (必須): SSOユーザーレコードの一意の識別子です。 取得したら、パラメータで`external_app_user_id`定義を指定して、会社ユーザーのリストを取得エンドポイントにリクエストを実行します。 特定のアプリケーションのApp Userを取得できるのは、そのApp Userを作成したのがこのアプリケーションである場合のみです。あるアプリケーションを使用して、別のアプリケーションで作成されたユーザーを検索した場合、データは返されません。 ``` const ssoUID = 'SSO User Unique ID'; // Check enterprise users for matching external_app_user_id against SSO UID client.enterprise.getUsers({ "external_app_user_id": ssoUID }) .then((users) => { if (users.total_count > 0) { // User found, fetch user ID const userId = users.entries[0].id; } else { // User not found - create new user record } }); ``` ``` String ssoUID = "SSO User Unique ID"; // Check enterprise users for matching external_app_user_id against SSO UID URL url = new URL("https://api.box.com/2.0/users?external_app_user_id=" + ssoUID); BoxAPIRequest request = new BoxAPIRequest(client, url, "GET"); BoxJSONResponse jsonResponse = (BoxJSONResponse) request.send(); JsonObject jsonObj = jsonResponse.getJsonObject(); JsonValue totalCount = jsonObj.get("total_count"); if (totalCount.asInt() > 0) { // User found, fetch // Fetch user ID JsonArray entries = (JsonArray) jsonObj.get("entries"); JsonObject userRecord = (JsonObject) entries.get(0); JsonValue userId = userRecord.get("id"); } else { // User not found - create new user record } ``` ``` sso_uid = 'SSO User Unique ID' # Validate is user exists url = f'https://api.box.com/2.0/users?external_app_user_id={sso_uid}' headers = {'Authorization': 'Bearer ' + access_token} response = requests.get(url, headers=headers) user_info = response.json() if (user_info['total_count'] == 0): # User not found - create new user record else: # User found, fetch user ID user = user_info['entries'][0] user_id = user['id'] ``` ## メールアドレスを使用したユーザーの検索 `login`のメールアドレスを使用して会社ユーザーを検索するには、SSOプロバイダの次の情報が必要になります。 - メールアドレス (必須): SSOユーザーレコードの一意のメールアドレスです。 取得したら、`filter_term`としてメールアドレスを指定して、会社ユーザーのリストを取得エンドポイントにリクエストを実行します。これは、メールアドレスまたは名前を使用した検索に使用できるようになります。 ``` const ssoEmail = 'ssouser@email.com'; client.enterprise.getUsers({filter_term: ssoEmail}) .then(users => { if (users.total_count > 0) { // User found, fetch user ID const userId = users.entries[0].id; } else { // User not found - create new user record } }); ``` ``` String ssoEmail = "ssouser@email.com"; Iterable<BoxUser.Info> users = BoxUser.getAllEnterpriseUsers(client, ssoEmail); ``` ``` sso_email = 'ssouser@email.com' users = client.users(user_type='all', filter_term=ssoEmail) if (users['total_count'] == 0): # User not found - create new user record else: # User found, fetch user ID user = users['entries'][0] user_id = user['id'] ``` **Source:** [https://ja.developer.box.com/guides/sso-identities-and-app-users/find-app-user/](https://ja.developer.box.com/guides/sso-identities-and-app-users/find-app-user/) --- ### SSOとApp User **Type:** guide | **Category:** SSOとApp User | **Section:** Developer Guides SSOとApp User シングルサインオン (SSO) サービスは、会社のIdentity and Access Management (IAM) ソリューションの一環として使用されることがよくあります。SSOサービスが展開されると、ユーザーは、… # SSOとApp User シングルサインオン (SSO) サービスは、会社の**Identity and Access Management (IAM)** ソリューションの一環として使用されることがよくあります。SSOサービスが展開されると、ユーザーは、1つの資格情報セット (ユーザー名とパスワード) だけを使用して1回ログインすれば、複数のアプリケーションの認証を安全に行うことができます。 Boxは、会社のSSOサービスに接続可能なアプリケーションの1つです。こうしたアプリケーションをPlatformアプリに統合すれば、いずれのエンドユーザーに対しても即座にBoxユーザーがプロビジョニングされます。その際、このエンドユーザーにBoxアカウントが用意されたことは知らされません。 一般的なSSOサービスには`Okta`、`Auth0`、`Microsoft Azure AD`、`OneLogin`、`G Suite`、`Ping Identity`などがありますが、これ以外にも展開可能なサービスは多数あります。 ## SSOをアプリに接続する プログラムによってSSOサービスをBoxアプリケーションに統合する際のフローは以下のとおりです。 1. ユーザーはログアウトした状態でウェブアプリケーションやモバイルアプリケーションにアクセスします。 2. ユーザーは、通常`OAuth 2`や`OpenID Connect`を介して、ログインのためにSSOプロバイダにリダイレクトされます。 3. ログイン後、ユーザーはSSO ID資格情報とともにアプリケーションに再度リダイレクトされます。 4. アプリケーションでは、このユーザーに関連付けられたBoxアカウントがすでに存在するかどうかを確認します。 5. このユーザーに既存のBoxアカウントがある場合、アプリケーションはSSO IDを使用して、Boxでそのユーザーに代わってAPIコールを実行します。 6. このユーザーに関連付けられたBoxアカウントがまだない場合は、SSO IDに基づいて新しいBoxユーザーアカウントが作成されます。SSOサービスの一意のユーザーIDが新しいBoxユーザーにリンクされ、2つのアカウントの間に関連付けが作成されます。その後、この新しいBoxユーザーがBoxでそのユーザーに代わってAPIコールを実行します。 # BoxウェブアプリとSSO SSOサービスをBoxアプリケーションではなくBoxウェブサイトに接続したい方のために、Boxでは、SAML 2.0を通じて[Boxウェブアプリケーション](https://www.box.com)のSSO統合をサポートするための[統合オプション](https://support.box.com/hc/ja/articles/360043696514-Enterprise%E3%81%A7%E3%81%AE%E3%82%B7%E3%83%B3%E3%82%B0%E3%83%AB%E3%82%B5%E3%82%A4%E3%83%B3%E3%82%AA%E3%83%B3-SSO-%E3%81%AE%E8%A8%AD%E5%AE%9A)を多数用意しています。 **Source:** [https://ja.developer.box.com/guides/sso-identities-and-app-users/](https://ja.developer.box.com/guides/sso-identities-and-app-users/) --- ### Swift SDK (Generated) のインストール **Type:** guide | **Category:** ツール | **Section:** Developer Guides Swift SDK (Generated) のインストール Swiftプロジェクトでは、Box Swift SDKを使用してBox APIを呼び出すことができます。 Swift SDKはパブリックベータ段階です。 GitHubでSwift SDKの詳細を確認する Swift… # Swift SDK (Generated) のインストール Swiftプロジェクトでは、Box Swift SDKを使用してBox APIを呼び出すことができます。 Swift SDKはパブリックベータ段階です。 GitHubでSwift SDKの詳細を確認する ## Swift Package Manager [Swift Package Manager](https://www.swift.org/documentation/package-manager/)は、Swiftコードの配布を管理するためのツールです。これは、依存関係のダウンロード、コンパイル、リンクのプロセスを自動化するためにSwiftのビルドシステムと統合されています。 Xcodeプロジェクトに依存関係を追加するには: 1. Xcodeプロジェクトで、[**File (ファイル)**]、[**Add Package Dependency (パッケージの依存関係を追加)**] の順に選択します。 2. **プラス**アイコン、[**Add Package Collection (パッケージコレクションの追加)**] の順にクリックします。 3. リポジトリのURL `https://github.com/box/box-swift-sdk-gen.git`を入力し、[**Load (読み込む)**] をクリックします。 または、`Package.swift`の依存関係の値に依存関係を追加することもできます。 詳細な手順については、[Swift Package Manager](https://www.swift.org/documentation/package-manager/)の公式ドキュメントや[Xcodeのドキュメント](https://developer.apple.com/documentation/xcode/adding-package-dependencies-to-your-app)を参照してください。 ## Carthage Carthageは、依存関係を構築し、バイナリフレームワークを提供する分散型の依存関係マネージャです。 `BoxSdkGen`に依存関係を追加するには: 1. `Cartfile`に次の行を追加します。 ``` git "https://github.com/box/box-swift-sdk-gen.git" ``` 1. 以下を実行します。 ``` carthage bootstrap --use-xcframeworks ``` 1. ビルドされた`xcframework`を**Carthage/Build**からプロジェクトにドラッグします。 詳細な手順については、[Carthageの公式ドキュメント](https://github.com/Carthage/Carthage#adding-frameworks-to-an-application)を参照してください。 **Source:** [https://ja.developer.box.com/guides/tooling/sdks/swift-gen/](https://ja.developer.box.com/guides/tooling/sdks/swift-gen/) --- ### Teams統合マッピング **Type:** guide | **Category:** 統合マッピング | **Section:** Developer Guides Teams統合マッピング Teams統合マッピングAPIの使用を開始する前に、以下の手順を実行してください。 前提条件 管理者または共同管理者のロール Box for Microsoft Teams統合がインストールされていること Boxアプリケーションの作成 Box… # Teams統合マッピング [Teams](https://support.box.com/hc/en-us/articles/360044667034-Introducing-Box-for-Microsoft-Teams)統合マッピングAPIの使用を開始する前に、以下の手順を実行してください。 ## 前提条件 - 管理者または共同管理者のロール - [Box for Microsoft Teams](https://support.box.com/hc/en-us/articles/360050737154-Assigning-a-Default-Box-Folder-to-a-Teams-Channel-or-Chat)統合がインストールされていること ## Boxアプリケーションの作成 1. [Box開発者コンソール](https://app.box.com/developers/console)で、[OAuth認証を使用するPlatformアプリ](g://authentication/oauth2/oauth2-setup)を作成します。 2. アプリケーションを開き、[**構成**] > [**必須のアクセススコープ**] で [**Enterpriseのプロパティを管理する**] アプリケーションスコープを有効にします。 ## 統合マッピングリクエストの承認 1. 前提条件の1つとして作成した[Platformアプリ](g://applications/app-types/platform-apps)に移動します。 2. [開発者トークン](g://authentication/tokens/developer-tokens)を生成し、次のように各リクエストのHTTPヘッダーに追加します。 ``` Authorization: Bearer {developer_token} ``` 開発者トークンの有効期限は60分です。その時間が経過した後は、再度生成する必要があります。 **Source:** [https://ja.developer.box.com/guides/integration-mappings/teams-mappings/](https://ja.developer.box.com/guides/integration-mappings/teams-mappings/) --- ### Teams統合マッピングのリスト取得 **Type:** guide | **Category:** 統合マッピング | **Section:** Developer Guides Teams統合マッピングのリスト取得 GET /integration_mappings/teams呼び出しを使用すると、マッピングを取得してフィルタをかけることができます。管理者が手動で作成したマッピングも、統合によって自動的に作成されたマッピングも対象になります。 # Teams統合マッピングのリスト取得 `GET /integration_mappings/teams`呼び出しを使用すると、マッピングを取得してフィルタをかけることができます。管理者が手動で作成したマッピングも、統合によって自動的に作成されたマッピングも対象になります。 **Source:** [https://ja.developer.box.com/guides/integration-mappings/teams-mappings/list-mappings/](https://ja.developer.box.com/guides/integration-mappings/teams-mappings/list-mappings/) --- ### Teams統合マッピングの作成 **Type:** guide | **Category:** 統合マッピング | **Section:** Developer Guides Teams統合マッピングの作成 POST integration_mappings_teams呼び出しを使用してマッピングを作成します。この呼び出しを動作させるには、box_itemパラメータとpartner_itemパラメータが必要です。これらのパラメータはそれぞれ、Box… # Teams統合マッピングの作成 `POST integration_mappings_teams`呼び出しを使用してマッピングを作成します。この呼び出しを動作させるには、`box_item`パラメータと`partner_item`パラメータが必要です。これらのパラメータはそれぞれ、BoxフォルダとTeamsチャネルを示します。 **Source:** [https://ja.developer.box.com/guides/integration-mappings/teams-mappings/create-mappings/](https://ja.developer.box.com/guides/integration-mappings/teams-mappings/create-mappings/) --- ### Teams統合マッピングの削除 **Type:** guide | **Category:** 統合マッピング | **Section:** Developer Guides Teams統合マッピングの削除 DELETE integration_mappings_teams_id… # Teams統合マッピングの削除 `DELETE integration_mappings_teams_id`呼び出しを使用して、チャネルとフォルダ間のマッピングを削除します。次のファイルがチャネルにアップロードされると、デフォルトのフォルダ構造で新しいマッピングと新しいフォルダが作成されます。マッピングを削除しても、BoxフォルダもTeamsチャネルも削除されません。 **Source:** [https://ja.developer.box.com/guides/integration-mappings/teams-mappings/delete-mappings/](https://ja.developer.box.com/guides/integration-mappings/teams-mappings/delete-mappings/) --- ### Teams統合マッピングの更新 **Type:** guide | **Category:** 統合マッピング | **Section:** Developer Guides Teams統合マッピングの更新 PUT integration_mappings_teams_id呼び出しを使用して、ターゲットのBoxフォルダの既存のマッピングを更新します。 # Teams統合マッピングの更新 `PUT integration_mappings_teams_id`呼び出しを使用して、ターゲットのBoxフォルダの既存のマッピングを更新します。 **Source:** [https://ja.developer.box.com/guides/integration-mappings/teams-mappings/update-mappings/](https://ja.developer.box.com/guides/integration-mappings/teams-mappings/update-mappings/) --- ### Typescript SDK (Generated) のインストール **Type:** guide | **Category:** ツール | **Section:** Developer Guides Typescript SDK (Generated) のインストール TypeScriptプロジェクトでは、自動生成されたBox TypeScript SDKを使用してBox APIを呼び出すことができます。この次世代のSDKには、開発者エクスペリエンスを向上させ、Box… # Typescript SDK (Generated) のインストール TypeScriptプロジェクトでは、**自動生成された**Box TypeScript SDKを使用してBox APIを呼び出すことができます。この[次世代のSDK](g://tooling/sdks#next-generation-sdks)には、開発者エクスペリエンスを向上させ、Boxコンテンツクラウドとの統合を効率化することを目的とした新機能が備わっています。 GitHubで自動生成されたTypeScript SDKの詳細を確認する ## NPMのインストール TypeScript SDKをインストールするには、[Nodeパッケージマネージャ](https://www.npmjs.com/)を使用してターミナルウィンドウまたはコマンドプロンプトから以下のコマンドを実行します。 ``` npm install box-typescript-sdk-gen ``` ## Yarnインストール 同様に、[Yarnパッケージ](https://yarnpkg.com/)マネージャを使用してSDKをインストールすることもできます。 ``` yarn add box-typescript-sdk-gen ``` **Source:** [https://ja.developer.box.com/guides/tooling/sdks/typescript-gen/](https://ja.developer.box.com/guides/tooling/sdks/typescript-gen/) --- ### UI Element **Type:** guide | **Category:** Boxの埋め込み | **Section:** Developer Guides UI Element Box UI Elementsは、開発者がメインのBoxウェブアプリの要素を独自のアプリケーションに追加できるようにする、組み込みのUIコンポーネントです。これを使用すると、Box… # UI Element Box UI Elementsは、開発者がメインのBoxウェブアプリの要素を独自のアプリケーションに追加できるようにする、組み込みのUIコンポーネントです。これを使用すると、Boxに保存されているコンテンツを参照、アップロード、プレビュー、選択することができます。また、これは、Reactコンポーネントとしても、フレームワークに依存しないJavaScriptライブラリとしても使用できます。 ## 利用可能なElement Boxには、アプリケーションでファイルやフォルダに共通するユーザーエクスペリエンスを実現するためにUI Elementがいくつか用意されています。 使用可能なUI Elementは以下のとおりです。 - [コンテンツエクスプローラ](g://embed/ui-elements/explorer) - ユーザーがファイルやフォルダを検索および参照できるようにします。 - [Content Open With](g://embed/ui-elements/open-with) - ユーザーが埋め込みのドロップダウンを使用して、Boxに保存されているコンテンツをパートナーアプリケーションで開けるようにします。 日本時間2021年12月22日をもって、新規のお客様に対する`OpenWith` UI Elementのサポートは終了しました。 - [Content Picker](g://embed/ui-elements/picker) - ユーザーがBoxアカウントからファイルやフォルダを選択できるようにします。 - [コンテンツプレビュー](g://embed/ui-elements/preview) - ドキュメント、画像、音声、動画などに使用するインタラクティブなビューアーを表示します。 - [Content Sidebar](g://embed/ui-elements/sidebar) - ファイルメタデータとアクティビティフィード情報用のサイドバーを表示します。 - [コンテンツアップローダー](g://embed/ui-elements/uploader) - ユーザーがファイルを選択するかドラッグアンドドロップしてアップロードできるようにします。 UI Elementは、単独で使用することも、ファイルをアップロードしてから表示するように、組み合わせてコンテンツに関する共通のユーザーフローを構築することもできます。 **Source:** [https://ja.developer.box.com/guides/embed/ui-elements/](https://ja.developer.box.com/guides/embed/ui-elements/) --- ### UI Elementsのデザイントークン **Type:** guide | **Category:** Boxの埋め込み | **Section:** Developer Guides UI Elements… # UI Elementsのデザイントークン [テーマとスタイルの設定](g://embed/ui-elements/theming-styling)のために使用できるすべてのデザイントークンを表に示します。実装のためのわかりやすい指針となる、デフォルト値と説明も記載されています。 ## トークンの構造 コンテンツエクスプローラでテーマオブジェクトにトークンを指定する方法として、トークンのフルネームを使用したフラットな構造と、短縮した名前を使用した入れ子構造の2つがあります。後者を使用すると、トークンをグループ化できるため、カスタマイズがわかりやすくなりますが、どちらも結果は同じです。 ### 例 フラットな構造: ``` const theme = { tokens: { "body-default-font-size": "14px", "body-default-font-weight": "400" "body-default-text-decoration": "none", "body-default-bold-line-height": "20px", } }; ``` 入れ子構造: ``` const theme = { tokens: { Body: { Default: { "font-size": "14px", "font-weight": "400", "text-decoration": "none", } "Default Bold": { "line-height": "20px", } } } }; ``` ## 境界線の色 16進カラー、RGB、特定のブラウザに依存しないカラー名など、任意のCSSカラー値を渡すことができます。 | トークン | デフォルト値 | 説明 | | --- | --- | --- | | border-checkbox-border | #6f6f6f | チェックボックスのデフォルトの境界線の色。 | | border-checkbox-border-hover | #4e4e4e | チェックボックスにカーソルを合わせたときの境界線の色。 | | border-checkbox-border-selected | #0061d5 | オンにしたチェックボックスの境界線の色。 | | border-checkbox-border-selected-hover | #2079e3 | オンにしたチェックボックスにカーソルを合わせたときの境界線の色。 | | border-cta-border-outline | #000000 | 背景が透明のセカンダリボタンの境界線。 | | border-cta-border-outline-disabled | #646464 | 無効なアウトラインボタンの境界線。 | | border-cta-border-outline-hover | #000000 | カーソルを合わせたときのアウトラインボタンの境界線。 | | border-cta-border-outline-pressed | #000000 | 押したときのアウトラインボタンの境界線。 | | border-cta-border-secondary | #bcbcbc | セカンダリボタンの境界線。 | | border-cta-border-secondary-disabled | #e8e8e8 | 無効なセカンダリボタンの境界線。 | | border-cta-border-secondary-hover | #bcbcbc | カーソルを合わせたときのセカンダリボタンの境界線。 | | border-cta-border-secondary-pressed | #bcbcbc | 押したときのセカンダリボタンの境界線。 | | border-divider-border | #e8e8e8 | 水平方向の行区切り記号。 | | border-dropdown-border | #bcbcbc | ドロップダウンメニューの境界線。 | | border-gridthumbnail-border | #e8e8e8 | グリッドビューにおける項目 (ファイル/フォルダ) のサムネイルの境界線。 | | border-input-border | #909090 | テキスト入力の境界線。 | | border-input-border-error | #ed3757 | エラーが発生しているテキスト入力の境界線。 | | border-input-border-focus | #2486fc | フォーカスされたテキスト入力の境界線。 | | border-input-border-hover | #6f6f6f | カーソルを合わせたときのテキスト入力の境界線。 | | border-search-border | #f4f4f4 | 検索入力の境界線。 | | border-search-border-hover | #6f6f6f | カーソルを合わせたときの検索入力の境界線。 | | border-switch-border | #bcbcbc | 切り替えスイッチの境界線。 | | border-switch-border-hover | #bcbcbc | カーソルを合わせたときの切り替えスイッチの境界線。 | | border-tooltip-border-error | #f69bab | エラーのツールチップの境界線。 | ## アイコンの色 ボタンやドロップダウンなどのインタラクティブなアイコンのスタイルのみを設定できます。 | トークン | デフォルト値 | 説明 | | --- | --- | --- | | icon-cta-icon | #6f6f6f | ボタンのアイコンのデフォルトの色。 | | icon-cta-icon-hover | #222222 | カーソルを合わせたときのボタンのアイコンの色。 | | icon-cta-icon-pressed | #222222 | 押したときのボタンのアイコンの色。 | ## アウトラインの色 | トークン | デフォルト値 | 説明 | | --- | --- | --- | | outline-focus-on-dark | #ffffff | 背景が暗い場合のフォーカスアウトラインの色。 | | outline-focus-on-light | #2486fc | 背景が明るい場合のフォーカスアウトラインの色。 | ## 表面色 | トークン | デフォルト値 | 説明 | | --- | --- | --- | | surface-checkbox-surface | #ffffff | チェックボックスの背景色。 | | surface-checkbox-surface-hover | #ffffff | カーソルを合わせたときのチェックボックスの背景色。 | | surface-checkbox-surface-selected | #0061d5 | オンにしたチェックボックスの背景色。 | | surface-checkbox-surface-selected-hover | #2079e3 | カーソルを合わせたときのオンにしたチェックボックスの背景色。 | | surface-cta-surface-icon | rgba(0, 0, 0, 0) | アイコンボタンの背景。 | | surface-cta-surface-icon-disabled | rgba(0, 0, 0, 0) | 無効なアイコンボタンの背景。 | | surface-cta-surface-icon-hover | rgba(0, 0, 0, 0.04) | カーソルを合わせたときのアイコンボタンの背景。 | | surface-cta-surface-icon-pressed | rgba(0, 0, 0, 0.08) | 押したときのアイコンボタンの背景。 | | surface-cta-surface-outline | rgba(0, 0, 0, 0) | 背景が透明のセカンダリボタンの背景。 | | surface-cta-surface-outline-hover | rgba(0, 0, 0, 0.04) | カーソルを合わせたときのアウトラインボタンの背景。 | | surface-cta-surface-outline-pressed | rgba(0, 0, 0, 0.08) | 押したときのアウトラインボタンの背景。 | | surface-cta-surface-secondary | #ffffff | セカンダリボタンの背景。 | | surface-cta-surface-secondary-hover | #f4f4f4 | カーソルを合わせたときのセカンダリボタンの背景。 | | surface-cta-surface-secondary-pressed | #e8e8e8 | 押したときのセカンダリボタンの背景。 | | surface-cta-surface-tertiary | #ffffff | リンク形式のボタンの背景。 | | surface-cta-surface-tertiary-hover | #f4f4f4 | カーソルを合わせたときのリンク形式のボタンの背景。 | | surface-cta-surface-tertiary-pressed | #e8e8e8 | 押したときのリンク形式のボタンの背景。 | | surface-dropdown-surface | #ffffff | ドロップダウンメニューの背景。 | | surface-dropdown-surface-error | #ffffff | エラーが発生しているドロップダウンメニューの背景。 | | surface-dropdown-surface-focus | #ffffff | フォーカスされたドロップダウンメニューの背景。 | | surface-dropdown-surface-hover | #ffffff | カーソルを合わせたときのドロップダウンメニューの背景。 | | surface-illustration-surface-box-neutral | #0061d5 | イラスト (詳細なアイコン) の色。 | | surface-input-surface | #ffffff | テキスト入力の背景。 | | surface-input-surface-error | #ffffff | エラーが発生しているテキスト入力の背景。 | | surface-input-surface-focus | #ffffff | フォーカスされたテキスト入力の背景。 | | surface-input-surface-hover | #ffffff | カーソルを合わせたときのテキスト入力の背景。 | | surface-menu-surface | #ffffff | ドロップダウンメニューオプションの背景。 | | surface-menu-surface-focus | #f4f4f4 | フォーカスしたメニュー項目の背景。 | | surface-menu-surface-hover | #f4f4f4 | カーソルを合わせたときのメニュー項目の背景。 | | surface-search-surface | #f4f4f4 | 検索入力の背景。 | | surface-search-surface-focused | #ffffff | フォーカスされた検索入力の背景。 | | surface-search-surface-hover | #fbfbfb | カーソルを合わせたときの検索入力の背景。 | | surface-sliderthumb-surface | #0061d5 | 範囲スライダのつまみの色。 | | surface-sliderthumb-surface-hover | #2486fc | カーソルを合わせたときの範囲スライダのつまみの色。 | | slidertrack-surface | #6f6f6f | 範囲スライダのトラックの色。 | | surface-surface | #ffffff | 一般的な背景色。 | | surface-surface-brand | #0061d5 | プライマリボタンの背景。 | | surface-surface-brand-disabled | #0061d5 | 無効なプライマリボタンの背景。 | | surface-surface-brand-hover | #006ae9 | カーソルを合わせたときのプライマリボタンの背景。 | | surface-surface-brand-pressed | #004eac | 押したときのプライマリボタンの背景。 | | surface-switch-surface | #ffffff | 切り替えスイッチの背景。 | | surface-switch-surface-off | #d3d3d3 | オフの状態の切り替えスイッチの背景。 | | surface-switch-surface-on | #0061d5 | オンの状態の切り替えスイッチの背景。 | | surface-tooltip-surface | #4e4e4e | ツールチップの背景。 | | surface-tooltip-surface-error | #fdebee | エラーのツールチップの背景。 | ## テキストの色 | トークン | デフォルト値 | 説明 | | --- | --- | --- | | text-cta-link | #0061d5 | ハイパーリンクの色。 | | text-cta-link-disabled | #b2cff2 | 無効なハイパーリンクの色。 | | text-cta-link-hover | #1d6bca | カーソルを合わせたときのハイパーリンクの色。 | | text-cta-link-pressed | #2486fc | 押したときのハイパーリンクの色。 | | text-text-error-on-light | #d5324e | 背景が明るい場合のエラーテキストの色。 | | text-text-on-dark | #ffffff | 背景が暗い場合のテキストの色。 | | text-text-on-light | #222222 | 背景が明るい場合のプライマリテキストの色。 | | text-text-on-light-secondary | #6f6f6f | 背景が明るい場合のセカンダリテキストの色。 | | text-text-on-light-secondary-hover | #4e4e4e | カーソルを合わせたときのセカンダリテキストの色。 | ## タイポグラフィのトークン 表内のコメントは、ルートフォントサイズの16ピクセルに基づいて計算されたピクセル数を示しています。 | トークン | デフォルト値 | 説明 | | --- | --- | --- | | body-default-font-family | Lato, "Helvetica Neue", sans-serif | 本文テキストのフォントファミリ。 | | body-default-font-size | 0.875rem | 本文テキストのフォントサイズ。 | | body-default-font-weight | 400 | 本文テキストのフォントの太さ。 | | body-default-letter-spacing | 0.01875rem | 本文テキストの文字間隔。 | | body-default-line-height | 1.25rem | 本文テキストの行の高さ。 | | body-default-text-decoration | none | 本文テキストの装飾。 | | body-default-bold-font-family | Lato, "Helvetica Neue", sans-serif | 本文テキスト (太字) のフォントファミリ。 | | body-default-bold-font-size | 0.875rem | 本文テキスト (太字) のフォントサイズ。 | | body-default-bold-font-weight | 700 | 本文テキスト (太字) のフォントの太さ。 | | body-default-bold-letter-spacing | 0.01875rem | 本文テキスト (太字) の文字間隔。 | | body-default-bold-line-height | 1.25rem | 本文テキスト (太字) の行の高さ。 | | body-default-bold-text-decoration | none | 本文テキスト (太字) の装飾。 | | body-default-semibold-font-family | Lato, "Helvetica Neue", sans-serif | 本文テキスト (半太字) のフォントファミリ。 | | body-default-semibold-font-size | 0.875rem | 本文テキスト (半太字) のフォントサイズ。 | | body-default-semibold-font-weight | 600 | 本文テキスト (半太字) のフォントの太さ。 | | body-default-semibold-letter-spacing | 0.01875rem | 本文テキスト (半太字) の文字間隔。 | | body-default-semibold-line-height | 1.25rem | 本文テキスト (半太字) の行の高さ。 | | body-default-semibold-text-decoration | none | 本文テキスト (半太字) の装飾。 | | body-large-font-family | Lato, "Helvetica Neue", sans-serif | 本文テキスト (大) のフォントファミリ。 | | body-large-font-size | 1rem | 本文テキスト (大) のフォントサイズ。 | | body-large-font-weight | 400 | 本文テキスト (大) のフォントの太さ。 | | body-large-letter-spacing | 0.01875rem | 本文テキスト (大) の文字間隔。 | | body-large-line-height | 1.5rem | 本文テキスト (大) の行の高さ。 | | body-large-text-decoration | none | 本文テキスト (大) の装飾。 | | body-large-bold-font-family | Lato, "Helvetica Neue", sans-serif | 本文テキスト (大、太字) のフォントファミリ。 | | body-large-bold-font-size | 1rem | 本文テキスト (大、太字) のフォントサイズ。 | | body-large-bold-font-weight | 700 | 本文テキスト (大、太字) のフォントの太さ。 | | body-large-bold-letter-spacing | 0.01875rem | 本文テキスト (大、太字) の文字間隔。 | | body-large-bold-line-height | 1.5rem | 本文テキスト (大、太字) の行の高さ。 | | body-large-bold-text-decoration | none | 本文テキスト (大、太字) の装飾。 | | caption-bold-font-family | Lato, "Helvetica Neue", sans-serif | キャプション (太字) のフォントファミリ。 | | caption-bold-font-size | 0.75rem | キャプション (太字) のフォントサイズ。 | | caption-bold-font-weight | 700 | キャプション (太字) のフォントの太さ。 | | caption-bold-letter-spacing | 0.01875rem | キャプション (太字) の文字間隔。 | | caption-bold-line-height | 0.875rem | キャプション (太字) の行の高さ。 | | caption-bold-text-decoration | none | キャプション (太字) のテキストの装飾。 | | caption-default-font-family | Lato, "Helvetica Neue", sans-serif | キャプションのフォントファミリ。 | | caption-default-font-size | 0.75rem | キャプションのフォントサイズ。 | | caption-default-font-weight | 400 | キャプションのフォントの太さ。 | | caption-default-letter-spacing | 0.01875rem | キャプションの文字間隔。 | | caption-default-line-height | 0.875rem | キャプションの行の高さ。 | | caption-default-text-decoration | none | キャプションのテキストの装飾。 | | label-bold-font-family | Lato, "Helvetica Neue", sans-serif | ラベル (太字) のフォントファミリ。 | | label-bold-font-size | 0.625rem | ラベル (太字) のフォントサイズ。 | | label-bold-font-weight | 700 | ラベル (太字) のフォントの太さ。 | | label-bold-letter-spacing | 0.0375rem | ラベル (太字) の文字間隔。 | | label-bold-line-height | 1rem | ラベル (太字) の行の高さ。 | | label-bold-text-decoration | none | ラベル (太字) のテキストの装飾。 | | label-default-font-family | Lato, "Helvetica Neue", sans-serif | ラベルのフォントファミリ。 | | label-default-font-size | 0.625rem | ラベルのフォントサイズ。 | | label-default-font-weight | 400 | ラベルのフォントの太さ。 | | label-default-letter-spacing | 0.0375rem | ラベルの文字間隔。 | | label-default-line-height | 1rem | ラベルの行の高さ。 | | label-default-text-decoration | none | ラベルのテキストの装飾。 | | link-default-font-family | Lato, "Helvetica Neue", sans-serif | ハイパーリンクのフォントファミリ。 | | link-default-font-size | 0.875rem | ハイパーリンクのフォントサイズ。 | | link-default-font-weight | 400 | ハイパーリンクのフォントの太さ。 | | link-default-letter-spacing | 0.01875rem | ハイパーリンクの文字間隔。 | | link-default-line-height | 1.25rem | ハイパーリンクの行の高さ。 | | link-default-text-decoration | underline | ハイパーリンクのテキストの装飾。 | | notification-default-font-family | Lato, "Helvetica Neue", sans-serif | 通知のフォントファミリ。 | | notification-default-font-size | 0.5625rem | 通知のフォントサイズ。 | | notification-default-font-weight | 700 | 通知のフォントの太さ。 | | notification-default-letter-spacing | 0.01875rem | 通知の文字間隔。 | | notification-default-line-height | 0.75rem | 通知の行の高さ。 | | notification-default-text-decoration | none | 通知のテキストの装飾。 | | title-large-font-family | Lato, "Helvetica Neue", sans-serif | タイトル (大) のフォントファミリ。 | | title-large-font-size | 1.125rem | タイトル (大) のフォントサイズ。 | | title-large-font-weight | 700 | タイトル (大) のフォントの太さ。 | | title-large-letter-spacing | 0.01875rem | タイトル (大) の文字間隔。 | | title-large-line-height | 1.5rem | タイトル (大) の行の高さ。 | | title-large-text-decoration | none | タイトル (大) のテキストの装飾。 | | title-medium-font-family | Lato, "Helvetica Neue", sans-serif | タイトル (中) のフォントファミリ。 | | title-medium-font-size | 1rem | タイトル (中) のフォントサイズ。 | | title-medium-font-weight | 700 | タイトル (中) のフォントの太さ。 | | title-medium-letter-spacing | 0.01875rem | タイトル (中) の文字間隔。 | | title-medium-line-height | 1.5rem | タイトル (中) の行の高さ。 | | title-medium-text-decoration | none | タイトル (中) のテキストの装飾。 | | title-small-font-family | Lato, "Helvetica Neue", sans-serif | タイトル (小) のフォントファミリ。 | | title-small-font-size | 0.9375rem | タイトル (小) のフォントサイズ。 | | title-small-font-weight | 700 | タイトル (小) のフォントの太さ。 | | title-small-letter-spacing | 0.01875rem | タイトル (小) の文字間隔。 | | title-small-line-height | 1.25rem | タイトル (小) の行の高さ。 | | title-small-text-decoration | none | タイトル (小) のテキストの装飾。 | | title-subtitle-font-family | Lato, "Helvetica Neue", sans-serif | サブタイトルのフォントファミリ。 | | title-subtitle-font-size | 0.875rem | サブタイトルのフォントサイズ。 | | title-subtitle-font-weight | 700 | サブタイトルのフォントの太さ。 | | title-subtitle-letter-spacing | 0.01875rem | サブタイトルの文字間隔。 | | title-subtitle-line-height | 1.25rem | サブタイトルの行の高さ。 | | title-subtitle-text-decoration | none | サブタイトルのテキストの装飾。 | | title-x-large-font-family | Lato, "Helvetica Neue", sans-serif | タイトル (特大) のフォントファミリ。 | | title-x-large-font-size | 1.3125rem | タイトル (特大) のフォントサイズ。 | | title-x-large-font-weight | 700 | タイトル (特大) のフォントの太さ。 | | title-x-large-letter-spacing | 0.01875rem | タイトル (特大) の文字間隔。 | | title-x-large-line-height | 2rem | タイトル (特大) の行の高さ。 | | title-x-large-text-decoration | none | タイトル (特大) のテキストの装飾。 | ## 間隔、サイズ、形状のトークン 表内のコメントは、ルートフォントサイズの16ピクセルに基づいて計算されたピクセル数を示しています。 | トークン | デフォルト値 | 説明 | | --- | --- | --- | | border-1 | 0.0625rem | 境界線の幅 (1ピクセルに相当)。 | | border-2 | 0.125rem | 境界線の幅 (2ピクセルに相当)。 | | border-3 | 0.1875rem | 境界線の幅 (3ピクセルに相当)。 | | border-4 | 0.25rem | 境界線の幅 (4ピクセルに相当)。 | | border-6 | 0.375rem | 境界線の幅 (6ピクセルに相当)。 | | border-8 | 0.5rem | 境界線の幅 (8ピクセルに相当)。 | | dropshadow-1 | 0 0 0.5rem 0 rgba(0, 0, 0, 0.05) | 微妙なシャドウ効果。 | | dropshadow-2 | 0 0.0625rem 0.25rem 0 rgba(0, 0, 0, 0.1) | 中程度のシャドウ効果。 | | dropshadow-3 | 0 0.25rem 0.75rem 0 rgba(0, 0, 0, 0.1) | 顕著なシャドウ効果。 | | radius-05 | 0.125rem | 境界線の半径 (2ピクセルに相当)。 | | radius-1 | 0.25rem | 境界線の半径 (4ピクセルに相当)。 | | radius-2 | 0.375rem | 境界線の半径 (6ピクセルに相当)。 | | radius-3 | 0.5rem | 境界線の半径 (8ピクセルに相当)。 | | radius-4 | 0.75rem | 境界線の半径 (12ピクセルに相当)。 | | radius-5 | 1rem | 境界線の半径 (16ピクセルに相当)。 | | radius-6 | 1.25rem | 境界線の半径 (20ピクセルに相当)。 | | radius-7 | 1.5rem | 境界線の半径 (24ピクセルに相当)。 | | radius-8 | 1.75rem | 境界線の半径 (28ピクセルに相当)。 | | radius-half | 2rem | 境界線の半径 (32ピクセルに相当)。 | | size-05 | 0.125rem | サイズ指定 (2ピクセルに相当)。 | | size-1 | 0.25rem | サイズ指定 (4ピクセルに相当)。 | | size-2 | 0.5rem | サイズ指定 (8ピクセルに相当)。 | | size-3 | 0.75rem | サイズ指定 (12ピクセルに相当)。 | | size-4 | 1rem | サイズ指定 (16ピクセルに相当)。 | | size-5 | 1.25rem | サイズ指定 (20ピクセルに相当)。 | | size-6 | 1.5rem | サイズ指定 (24ピクセルに相当)。 | | size-7 | 1.75rem | サイズ指定 (28ピクセルに相当)。 | | size-8 | 2rem | サイズ指定 (32ピクセルに相当)。 | | size-9 | 2.25rem | サイズ指定 (36ピクセルに相当)。 | | size-10 | 2.5rem | サイズ指定 (40ピクセルに相当)。 | | size-11 | 2.75rem | サイズ指定 (44ピクセルに相当)。 | | size-12 | 3rem | サイズ指定 (48ピクセルに相当)。 | | size-14 | 3.5rem | サイズ指定 (56ピクセルに相当)。 | | size-15 | 3.75rem | サイズ指定 (60ピクセルに相当)。 | | size-16 | 4rem | サイズ指定 (64ピクセルに相当)。 | | size-18 | 4.5rem | サイズ指定 (72ピクセルに相当)。 | | size-20 | 5rem | サイズ指定 (80ピクセルに相当)。 | | space-05 | 0.125rem | 間隔指定 (2ピクセルに相当)。 | | space-1 | 0.25rem | 間隔指定 (4ピクセルに相当)。 | | space-2 | 0.5rem | 間隔指定 (8ピクセルに相当)。 | | space-3 | 0.75rem | 間隔指定 (12ピクセルに相当)。 | | space-4 | 1rem | 間隔指定 (16ピクセルに相当)。 | | space-5 | 1.25rem | 間隔指定 (20ピクセルに相当)。 | | space-6 | 1.5rem | 間隔指定 (24ピクセルに相当)。 | | space-7 | 1.75rem | 間隔指定 (28ピクセルに相当)。 | | space-8 | 2rem | 間隔指定 (32ピクセルに相当)。 | | space-9 | 2.25rem | 間隔指定 (36ピクセルに相当)。 | | space-10 | 2.5rem | 間隔指定 (40ピクセルに相当)。 | | space-11 | 2.75rem | 間隔指定 (44ピクセルに相当)。 | | space-12 | 3rem | 間隔指定 (48ピクセルに相当)。 | | space-14 | 3.5rem | 間隔指定 (56ピクセルに相当)。 | | space-15 | 3.75rem | 間隔指定 (60ピクセルに相当)。 | | space-16 | 4rem | 間隔指定 (64ピクセルに相当)。 | | space-18 | 4.5rem | 間隔指定 (72ピクセルに相当)。 | | space-20 | 5rem | 間隔指定 (80ピクセルに相当)。 | **Source:** [https://ja.developer.box.com/guides/embed/ui-elements/ui-elements-design-tokens/](https://ja.developer.box.com/guides/embed/ui-elements/ui-elements-design-tokens/) --- ### User Event **Type:** guide | **Category:** イベント | **Section:** Developer Guides User Event User Eventは、現在認証されているユーザーに関連する、低レイテンシのイベントストリームを提供します。このイベントストリームにより、Box Driveは常に最新の状態で維持されますが、このイベントストリームは開発者向けにも提供されています。 # User Event User Eventは、現在認証されているユーザーに関連する、低レイテンシのイベントストリームを提供します。このイベントストリームにより、Box Driveは常に最新の状態で維持されますが、このイベントストリームは開発者向けにも提供されています。 **Source:** [https://ja.developer.box.com/guides/events/user-events/](https://ja.developer.box.com/guides/events/user-events/) --- ### User Eventの取得 **Type:** guide | **Category:** イベント | **Section:** Developer Guides User Eventの取得 User Eventを取得するには、任意のユーザーとして認証し、GET /events APIを呼び出します。 返されるイベントは、API… # User Eventの取得 User Eventを取得するには、任意のユーザーとして認証し、[`GET /events`](e://get_events) APIを呼び出します。 返されるイベントは、APIの作成に使用したアクセストークンを所有するユーザーのみを対象とします。別のユーザーのイベントフィードを取得するには、`as-user`ヘッダーか、そのユーザーの実際のアクセストークンを使用します。 ## ストリームタイプ User Event Streamでは、3つのタイプのストリームがサポートされます。 | ストリームタイプ | | | --- | --- | | all | ユーザーに関するすべてのイベントを返します (デフォルト)。 | | changes | ファイルの更新やコラボレーションなど、ファイルツリーを変更する可能性があるイベントを返します。 | | sync | 変更に似ていますが、同期対象フォルダにのみ適用されます。 | ## 匿名ユーザー 場合によっては、イベントフィードには、IDが`2`のユーザーが表示される可能性があります。これは、匿名ユーザーを表すBoxの内部識別子です。 匿名ユーザーは、ログインしていないユーザーです。この状況は、ユーザーがコンテンツを操作し、最初にログインを求められない場合にいつでも発生する可能性があります。たとえば、ユーザーが、公開共有リンクを使用してファイルをダウンロードするときなどです。 ## 制限 Boxでのイベントの保存は無期限ではありません。 User Eventは2週間から2か月間保存され、その後、保存されたUser Eventは削除されます。Enterprise Eventには、APIを介した場合は1年間、Box管理コンソールのエクスポートされたレポート経由の場合は7年間アクセスできます。 このフィードでは、完全な結果を迅速に返すことを重視しています。つまり、Boxではイベントを複数回または異なる順序で返す可能性があります。重複するイベントは、イベントIDによって識別できます。 ## Long polling User Event Streamでは、[`OPTIONS /events` APIを介して](g://events/user-events/polling)Long pollingがサポートされます。 ## イベントタイプ ユーザーに対して、以下のイベントがトリガーされます。このリストですべてを網羅しているわけではないため、記載されていないイベントが表示される可能性もあります。 以下のイベントは、すべてのフィードで使用できます。 | イベント名 | 説明 | | --- | --- | | ITEM_CREATE | フォルダまたはファイルが作成されました。 | | ITEM_UPLOAD | フォルダまたはファイルがアップロードされました。 | | ITEM_MOVE | ファイルまたはフォルダが移動されました。 | | ITEM_COPY | ファイルまたはフォルダがコピーされました。 | | LOCK_CREATE | ファイルがロックされました。 | | LOCK_DESTROY | ファイルがロック解除されました。ロックされたファイルが削除されると、ソースファイルはnullになります。 | | ITEM_TRASH | ファイルまたはフォルダが削除済みとしてマークされました。 | | ITEM_UNDELETE_VIA_TRASH | ファイルまたはフォルダがごみ箱から戻されました。 | | COLLAB_ADD_COLLABORATOR | コラボレータがフォルダに追加されました。 | | COLLAB_ROLE_CHANGE | コラボレータの役割が変更されました。 | | COLLAB_INVITE_COLLABORATOR | コラボレータがフォルダに招待されました。 | | COLLAB_REMOVE_COLLABORATOR | コラボレータがフォルダから削除されました。 | | ITEM_SYNC | フォルダが同期対象としてマークされました。 | | ITEM_UNSYNC | フォルダの同期対象のマークが解除されました。 | | ITEM_RENAME | ファイルまたはフォルダの名前が変更されました。 | | ITEM_MAKE_CURRENT_VERSION | 前のバージョンのファイルが現在のバージョンに昇格されました。 | | GROUP_ADD_USER | グループへのユーザーの追加 | | GROUP_REMOVE_USER | グループからのユーザーの削除 | 以下のイベントは、`all`フィードでのみ使用できます。 | イベント名 | 説明 | | --- | --- | | COMMENT_CREATE | フォルダ、ファイル、または他のコメントに対するコメントが作成されました。 | | COMMENT_DELETE | フォルダ、ファイル、または他のコメントに対するコメントが削除されました。 | | ITEM_DOWNLOAD | ファイルまたはフォルダがダウンロードされました。 | | ITEM_PREVIEW | ファイルがプレビューされました。 | | TASK_ASSIGNMENT_CREATE | タスクが割り当てられました。 | | TASK_CREATE | タスクが作成されました。 | | ITEM_SHARED_CREATE | ファイルまたはフォルダの共有が有効化されました。 | | ITEM_SHARED_UNSHARE | ファイルまたはフォルダの共有が無効化されました。 | | ITEM_SHARED | フォルダが共有されました。 | | TAG_ITEM_CREATE | タグがファイルまたはフォルダに追加されました。 | | ENABLE_TWO_FACTOR_AUTH | ユーザーによって2要素認証が有効化されました。 | | MASTER_INVITE_ACCEPT | 管理対象ユーザーになるための招待が無料ユーザーによって承認されました。 | | MASTER_INVITE_REJECT | 管理対象ユーザーになるための招待が無料ユーザーによって拒否されました。 | | ACCESS_GRANTED | アカウントに対するBoxのアクセス権限が付与されました。 | | ACCESS_REVOKED | アカウントに対するBoxのアクセス権限が取り消されました。 | ## イベント通知 イベントストリームのノイズを低減し、イベントの利用を最適化するために、表に示されているイベントタイプでは、トリガーする通知の数が制限されています。 | イベントタイプ | 通知の動作 | | --- | --- | | COLLAB_ADD_COLLABORATOR, COLLAB_REMOVE_COLLABORATOR, COLLAB_INVITE_COLLABORATOR, COLLAB_ROLE_CHANGE | これらのイベントが発生すると、changesイベントストリームのコンテンツ所有者に通知が送信されます。コラボレータには、allストリーム上に表示されるイベントと一致する追加のイベントが表示されます。 | | ITEM_DOWNLOAD | 項目がダウンロードされると、コンテンツ所有者だけが通知を受信します。コラボレータには通知されません。 | | ITEM_PREVIEW | 項目がプレビューされると、コンテンツ所有者だけが通知を受信します。コラボレータには通知されません。 | **Source:** [https://ja.developer.box.com/guides/events/user-events/for-user/](https://ja.developer.box.com/guides/events/user-events/for-user/) --- ### V1 Webhook **Type:** guide | **Category:** Webhook | **Section:** Developer Guides V1 Webhook 開発者コンソールを使用して作成されたWebhookは、ユーザーのアカウント内のすべてのファイルとフォルダに対する変更を監視します。このようなWebhookを作成する際は、Webhook… # V1 Webhook [開発者コンソール](https://app.box.com/developers/console)を使用して作成されたWebhookは、ユーザーのアカウント内のすべてのファイルとフォルダに対する変更を監視します。このようなWebhookを作成する際は、Webhookのバインド先として特定のオブジェクトを指定することはできません。特定のファイルまたはフォルダ用にWebhookを作成するには、[V2 Webhook](g://webhooks/v2)を使用する必要があります。 このプロセスで作成されたWebhookは、APIコールでユーザーのすべてのWebhookのリストを取得しても表示されません。すべてのV1 Webhookは、[開発者コンソール](https://app.box.com/developers/console)の [**Webhook**] タブに表示されます。 **Source:** [https://ja.developer.box.com/guides/webhooks/v1/](https://ja.developer.box.com/guides/webhooks/v1/) --- ### V2 Webhook **Type:** guide | **Category:** Webhook | **Section:** Developer Guides V2 Webhook フロー イベントによってファイルまたはフォルダのWebhookがトリガーされると、Webhookの作成時に指定したaddressに対してHTTP呼び出しが実行されます。この呼び出しのペイロードには、いくつかのリクエストヘッダーとJSON… # V2 Webhook ## フロー イベントによってファイルまたはフォルダのWebhookがトリガーされると、Webhookの作成時に指定した`address`に対してHTTP呼び出しが実行されます。この呼び出しのペイロードには、いくつかのリクエストヘッダーとJSON本文が含まれます。 ## ペイロードヘッダー Webhookによって送信されたペイロードには、以下のBox固有のヘッダーが含まれます。 | ヘッダー | 説明 | | --- | --- | | BOX-DELIVERY-ID | 配信されたWebhookペイロードを識別する、Boxによって割り当てられた一意のID。BoxがWebhookを再試行すると、このIDは変わりますが、ペイロード本文のIDは変わりません。 | | BOX-DELIVERY-TIMESTAMP | ペイロードの送信日時を識別するRFC-3339タイムスタンプ。 | | BOX-SIGNATURE-PRIMARY | このWebhook用に設定されたプライマリ署名キーを使用して作成された署名。 | | BOX-SIGNATURE-SECONDARY | このWebhook用に設定されたセカンダリ署名キーを使用して作成された署名。 | | BOX-SIGNATURE-VERSION | 値は常に1。 | | BOX-SIGNATURE-ALGORITHM | 値は常にHmacSHA256。 | 例: ``` BOX-DELIVERY-ID: 673a081b-bb4b-4d45-b4f1-4131a29c1d07 BOX-DELIVERY-TIMESTAMP: 2016-07-11T10:10:33-07:00 BOX-SIGNATURE-PRIMARY: isCeDp7mLR41/MjcSEFLag9bWmpJkgmN80Je4VIESdo= BOX-SIGNATURE-SECONDARY: 1UbiiKS7/2o5vNIlyMh7e5QGCHq8lflWFgEF+YWBugI= BOX-SIGNATURE-VERSION: 1 BOX-SIGNATURE-ALGORITHM: HmacSHA256 USER-AGENT: Box-WH-Client/0.1 ``` Webhookペイロードの[設定](g://webhooks/v2/signatures-v2)と[署名の検証](g://webhooks/v2/signatures-v2)を行うことをお勧めします。 HTTPヘッダー名では大文字と小文字が区別されません。クライアントでは、すべてのヘッダーの名前を標準化された小文字または大文字の形式に変換してから、ヘッダーの値を確認する必要があります。 ## ペイロード本文 Webhookペイロードの本文は、Webhookをトリガーしたファイルまたはフォルダ (ターゲット)、およびトリガーされたイベントを記述するJSONオブジェクトです。 | フィールド | 説明 | | --- | --- | | type | 値は常にwebhook_event。 | | id | イベントを識別する、Boxによって割り当てられた一意のID。BoxがWebhookを再試行しても、このIDは変わりませんが、ヘッダーのIDは呼び出しのたびに変わります。 | | created_at | イベントがトリガーされた日時。 | | trigger | イベントをトリガーしたアクションの名前 (例: FILE.UPLOADED)。 | | webhook | イベントがトリガーされたWebhook ID。 | | created_by | イベントをトリガーしたユーザー。 | | source | イベントをトリガーした項目 (例: ターゲットフォルダにアップロードされたファイル)。 | 例: ``` { "type": "webhook_event", "id": "eb0c4e06-751f-442c-86f8-fd5bb404dbec", "created_at": "2016-07-11T10:10:32-07:00", "trigger": "FILE.UPLOADED", "webhook": { "id": "53", "type": "webhook" }, "created_by": { "type": "user", "id": "226067247", "name": "John Q. Developer", "login": "johnq@dev.name" }, "source": { "id": "73835521473", "type": "file", "file_version": { "type": "file_version", "id": "78096737033", "sha1": "2c61623e86bee78e6ab444af456bccc7a1164095" }, "sequence_id": "0", "etag": "0", "sha1": "2c61623e86bee78e6ab444af456bccc7a1164095", "name": "Test-Image-3.png", "description": "", "size": 26458, "path_collection": { "total_count": 4, "entries": [ { "type": "folder", "id": "0", "sequence_id": null, "etag": null, "name": "All Files" }, { "type": "folder", "id": "2614853901", "sequence_id": "4", "etag": "4", "name": "Testing" }, { "type": "folder", "id": "8290186265", "sequence_id": "0", "etag": "0", "name": "Webhooks Base" }, { "type": "folder", "id": "8290188973", "sequence_id": "0", "etag": "0", "name": "Webhooks" } ] }, "created_at": "2016-07-11T10:10:32-07:00", "modified_at": "2016-07-11T10:10:32-07:00", "trashed_at": null, "purged_at": null, "content_created_at": "2016-06-08T11:14:04-07:00", "content_modified_at": "2016-06-08T11:14:04-07:00", "created_by": { "type": "user", "id": "226067247", "name": "John Q. Developer", "login": "johnq@dev.name" }, "modified_by": { "type": "user", "id": "226067247", "name": "John Q. Developer", "login": "johnq@dev.name" }, "owned_by": { "type": "user", "id": "226067247", "name": "John Q. Developer", "login": "johnq@dev.name" }, "shared_link": null, "parent": { "type": "folder", "id": "8290188973", "sequence_id": "0", "etag": "0", "name": "Webhooks" }, "item_status": "active" }, "additional_info": [] } ``` ## 再試行 Boxがペイロードを送信してから30秒以内に、`200`から`299`の範囲のHTTPステータスコードを含むレスポンスが表示されない場合、Webhookペイロードの配信は失敗します。 Boxは2時間でWebhook配信を最大12回再試行します。この回数と期間は今後変更される可能性があります。 **Source:** [https://ja.developer.box.com/guides/webhooks/v2/](https://ja.developer.box.com/guides/webhooks/v2/) --- ### Webhook **Type:** guide | **Category:** Webhook | **Section:** Developer Guides Webhook Webhookを使用すると、Boxコンテンツのイベントを監視し、イベントの発生時に任意のURLへの通知を受け取ることができます。たとえば、ワークフローには、共有リンクを削除するためのファイルダウンロードの待機が含まれる場合があります。このファイルにWebhook… # Webhook Webhookを使用すると、Boxコンテンツのイベントを監視し、イベントの発生時に任意のURLへの通知を受け取ることができます。たとえば、ワークフローには、共有リンクを削除するためのファイルダウンロードの待機が含まれる場合があります。このファイルにWebhookを設定すれば、ダウンロードイベントが通知されたときに、スクリプトが起動し、共有リンクを削除するためのAPIコールを実行できます。 ## バージョン WebhookにはV1とV2の2種類があります。この2つの比較を以下に示します。 使いやすさ、セキュリティの強さ、選択できるイベントトリガーの多さ、自動的に再試行されるという観点から、V2 Webhookを使用することをお勧めします。 | V1 | V2 | | --- | --- | | 開発者コンソールで作成。 | 開発者コンソールまたはAPIコールで作成。 | | ルートレベルに設定。 | 特定のファイル/フォルダに設定 (ただしルートには設定不可)。 | | 14のイベントトリガーから選択。 | 30以上のイベントトリガーから選択。 | | 選択したコールバックパラメータを提供。 | ペイロードに、オブジェクトレスポンスと追加のコンテキスト情報がすべて含まれる。 | | 通知配信の失敗後の再試行メカニズムなし。 | 通知配信の失敗後、10回まで再試行可能。 | | ペイロード検証をサポートしない。 | ペイロード検証をサポート。 | | 通知URLはHTTPまたはHTTPSを指定可。 | 通知URLはHTTPSのみ指定可。 | | 拡張性が低い。 | 拡張性に優れ、信頼性が高い。 | **Source:** [https://ja.developer.box.com/guides/webhooks/](https://ja.developer.box.com/guides/webhooks/) --- ### Webhookイベントトリガー **Type:** guide | **Category:** Webhook | **Section:** Developer Guides Webhookイベントトリガー V2 ファイルとフォルダ 以下は、V2 Webhook… # Webhookイベントトリガー ## V2 ### ファイルとフォルダ 以下は、V2 Webhookをトリガーするよう構成できるイベントのリストです。ファイルに対してのみ使用できるイベントや、フォルダに対してのみ使用できるイベントもあります。 | イベント | トリガー | ファイルに使用可能か | フォルダに使用可能か | | --- | --- | --- | --- | | COLLABORATION.CREATED | コラボレーションが作成される。 | いいえ | はい | | COLLABORATION.ACCEPTED | コラボレーションが承認される。 | いいえ | はい | | COLLABORATION.REJECTED | コラボレーションが拒否される。 | いいえ | はい | | COLLABORATION.REMOVED | コラボレーションが削除される。 | いいえ | はい | | COLLABORATION.UPDATED | コラボレーションが更新される。 | いいえ | はい | | COMMENT.CREATED | コメントオブジェクトが作成される。 | はい | はい | | COMMENT.UPDATED | コメントオブジェクトが編集される。 | はい | はい | | COMMENT.DELETED | コメントオブジェクトが削除される。 | はい | はい | | DOCGEN_DOCUMENT_GENERATION_FAILED | Doc Genがドキュメントの生成に失敗しました。 | はい | いいえ | | DOCGEN_DOCUMENT_GENERATION_STARTED | Doc Genがドキュメントの作成を開始しました。 | はい | いいえ | | DOCGEN_DOCUMENT_GENERATION_SUCCEEDED | Doc Genがドキュメントの作成に成功しました。 | はい | いいえ | | FILE.UPLOADED | ファイルがこのフォルダにアップロードまたは移動される。 | いいえ | はい | | FILE.PREVIEWED | ファイルがプレビューされる。 | はい | はい | | FILE.DOWNLOADED | ファイルがダウンロードされる。 | はい | はい | | FILE.TRASHED | ファイルがごみ箱に移動される。 | はい | はい | | FILE.DELETED | ファイルが完全に削除される。 | はい | はい | | FILE.RESTORED | ファイルがごみ箱から復元される。 | はい | はい | | FILE.COPIED | ファイルがコピーされる。 | はい | はい | | FILE.MOVED | ファイルが別のフォルダに移動される。 | はい | はい | | FILE.LOCKED | ファイルがロックされる。 | はい | はい | | FILE.UNLOCKED | ファイルのロックが解除される。 | はい | はい | | FILE.RENAMED | ファイル名が変更される。 | はい | はい | | FOLDER.CREATED | フォルダが作成される | いいえ | はい | | FOLDER.RENAMED | フォルダ名が変更される。 | いいえ | はい | | FOLDER.DOWNLOADED | フォルダがダウンロードされる。 | いいえ | はい | | FOLDER.RESTORED | フォルダがごみ箱から復元される。 | いいえ | はい | | FOLDER.DELETED | フォルダが完全に削除される。 | いいえ | はい | | FOLDER.COPIED | フォルダがコピーされる。 | いいえ | はい | | FOLDER.MOVED | フォルダが別のフォルダに移動される。 | いいえ | はい | | FOLDER.TRASHED | フォルダがごみ箱に移動される。 | いいえ | はい | | METADATA_INSTANCE.CREATED | ファイルまたはフォルダに新しいメタデータテンプレートインスタンスが関連付けられる。 | はい | はい | | METADATA_INSTANCE.UPDATED | ファイルまたはフォルダに関連付けられている既存のメタデータテンプレートインスタンスの属性 (値) が更新/削除される。 | はい | はい | | METADATA_INSTANCE.DELETED | ファイルまたはフォルダに関連付けられている既存のメタデータテンプレートインスタンスが削除される。 | はい | はい | | SHARED_LINK.DELETED | 共有リンクが削除される。 | はい | はい | | SHARED_LINK.CREATED | 共有リンクが作成される。 | はい | はい | | SHARED_LINK.UPDATED | 共有リンクが更新される。 | はい | はい | | TASK_ASSIGNMENT.CREATED | タスクの作成 | はい | はい | | TASK_ASSIGNMENT.UPDATED | タスク割り当てが変更される。 | はい | はい | | SIGN_REQUEST.COMPLETED | 署名リクエストが完了する。 | はい | はい | | SIGN_REQUEST.DECLINED | 署名リクエストが拒否される。 | はい | はい | | SIGN_REQUEST.EXPIRED | 署名リクエストの有効期限が切れる。 | はい | はい | | SIGN_REQUEST.SIGNER_EMAIL_BOUNCED | 署名者のメールが差し戻される。 | はい | はい | | WEBHOOK.DELETED | Webhookが削除される。 | いいえ | いいえ | ## V1 V1 Webhookをトリガーするよう構成できるイベントを以下に示します。 - Sent - Created - Uploaded - Commented - Downloaded - Previewed - Moved - Copied - Task assigned - Responded to task - Locked - Unlocked - Deleted - Collaborator added **Source:** [https://ja.developer.box.com/guides/webhooks/triggers/](https://ja.developer.box.com/guides/webhooks/triggers/) --- ### Webhookの作成 **Type:** guide | **Category:** Webhook | **Section:** Developer Guides Webhookの作成 V1 Webhookを作成するには、開発者コンソールで以下の手順に従います。 開発者コンソールで、目的のアプリケーションに移動します。 [Webhook] タブを選択します。 [新規Webhook… # Webhookの作成 V1 Webhookを作成するには、[開発者コンソール](https://app.box.com/developers/console)で以下の手順に従います。 1. [開発者コンソール](https://app.box.com/developers/console)で、目的のアプリケーションに移動します。 2. [**Webhook**] タブを選択します。 3. [**新規Webhookの作成**] ボタンをクリックします。 4. イベントトリガー、エンドポイントURL、1つ以上のコールバックパラメータなどをフォームに入力します。 5. [**Webhookの保存**] をクリックします。 # コールバックパラメータ V2 Webhookとは異なり、これらの手動によるWebhookにはデータを構成する必要があります。このデータは、本文のクエリ文字列として、または`name=Contract.pdf&type=file`のようなクエリパラメータとして送信されます。 ## 開発者モード デフォルトでは、V1 Webhookは、開発者コンソールの [**一般設定**] タブにアプリケーションコラボレータとして表示されているユーザーに対してのみ機能します。Webhookをすべてのユーザーに対して有効にするには、[サポートにお問い合わせください](https://support.box.com)。 ## Webhookの有効化 Webhookを作成した後、使用を開始するには、アプリケーションをユーザーのアカウントに追加する必要があります。 アプリを追加するためのURLを取得するには、OAuth 2.0認証アプリで以下の手順に従います。 1. [開発者コンソール](https://app.box.com/developers/console)で、目的のアプリケーションの [**統合**] タブに移動します。 2. [**アプリを送信**] をクリックします。心配しないでください。送信プロセスは完了しません。 3. ページ下部で [**プレビュー**] をクリックします。 4. [**追加**] をクリックします。 その他すべての認証タイプの場合、このURLを取得するには、サポートに問い合わせる必要があります。 これでWebhookは、ユーザーのアカウントで発生する構成済みのイベントに対してトリガーされるようになりました。 **Source:** [https://ja.developer.box.com/guides/webhooks/v1/create-v1/](https://ja.developer.box.com/guides/webhooks/v1/create-v1/) --- ### Webhookの作成 **Type:** guide | **Category:** Webhook | **Section:** Developer Guides Webhookの作成 V2 Webhookは、特定のファイルまたはフォルダを監視でき、開発者コンソールでもAPIでも作成できます。 開発者コンソール V2 Webhookを作成できるのは、[Webhook… # Webhookの作成 V2 Webhookは、特定のファイルまたはフォルダを監視でき、[開発者コンソール](https://app.box.com/developers/console)でもAPIでも作成できます。 ## 開発者コンソール V2 Webhookを作成できるのは、[**Webhookを管理する**] というスコープが選択され、アプリケーションが承認されている場合のみです。[必須のアクセススコープ](g://applications)と[承認](g://authorization)の詳細を参照してください。 Webhookを作成するには、以下の手順に従います。 1. [開発者コンソール](https://app.box.com/developers/console)で、目的のアプリケーションに移動します。 2. [**Webhook**] タブを選択します。 3. [**Webhookを作成**] ボタンをクリックします。 4. ドロップダウンリストで [**V2**] を選択します。 5. フォームに入力します。 6. [**Webhookを作成**] ボタンをクリックして変更を保存します。 ### 必須フィールド | フィールド名 | 説明 | 必須 | | --- | --- | --- | | URLアドレス | Webhookによって通知されるURLアドレス。 | はい | | コンテンツタイプ | Webhookが構成されているコンテンツのタイプ (ファイル/フォルダ)。 | はい | | トリガー | Webhookをアクティブ化するさまざまなトリガー。 | はい | ## API このAPIを使用するには、アプリケーションの [**Webhookを管理する**] スコープが有効になっている必要があります。 ファイルにWebhookを追加するには、`file`の種類、ファイルのID、Webhook通知の送信先URL、および[トリガー](g://webhooks/triggers)のリストを指定して[Webhookを作成](e://post_webhooks)エンドポイントを呼び出します。 フォルダにWebhookを追加するには、`folder`の種類、フォルダのID、Webhook通知の送信先URL、および[トリガー](g://webhooks/triggers)のリストを指定して[Webhookを作成](e://post_webhooks)エンドポイントを呼び出します。 Webhookはカスケードで適用されるため、Webhookを親フォルダに設定すると、サブフォルダでも選択されたトリガーが監視されます。 ## 所有権 コンテンツにアクセスできなくなることでWebhookの配信に生じる可能性のある問題を回避するために、[サービスアカウント](page://platform/user-types/#service-account) (つまり削除されることのないユーザー) を使用してWebhookを作成することを強くお勧めします。 ファイルやフォルダと同様、Webhookを所有するのはユーザーです。Webhookを所有するユーザーが削除されると、以前アクセスできていたすべてのファイルとフォルダにアクセスできなくなります。ユーザーのWebhookでは検証が失敗するようになりますが、Webhookサービスは引き続きイベントを送信し、再試行を要求します。 ## Webhookアドレス `address`パラメータで指定する通知URLは、Webhookの作成時に指定した有効なURLである必要があります。このURLは、いずれかのトリガーがアクティブになるたびに呼び出されます。 通知URLは標準ポート`443`を使用する必要があり、Webhookペイロードの受信から30秒以内に`200`～`299`の範囲のHTTPステータスを返す必要があります。 ## Webhookトリガー トリガーのリストでは、Webhookによって発生するイベントを表す文字列を指定します。たとえば、ユーザーがファイルをアップロードしたときにWebhookをトリガーするには`FILE.UPLOADED`を使用します。 使用可能なトリガーのリストは、[こちらのガイド](g://webhooks/triggers)を参照してください。 **Source:** [https://ja.developer.box.com/guides/webhooks/v2/create-v2/](https://ja.developer.box.com/guides/webhooks/v2/create-v2/) --- ### Webhookの削除 **Type:** guide | **Category:** Webhook | **Section:** Developer Guides Webhookの削除 V1 Webhookを完全に削除することはできません。その代わり、サポートにWebhookを開発者モードに戻してもらうことができます。また、開発者は、有効化URL… # Webhookの削除 V1 Webhookを完全に削除することはできません。その代わり、[サポート](https://support.box.com/hc/ja/requests/new)にWebhookを開発者モードに戻してもらうことができます。また、開発者は、有効化URLに再度アクセスして [**削除**] をクリックすることで、自分のアカウントからアプリケーションを削除することもできます。 **Source:** [https://ja.developer.box.com/guides/webhooks/v1/delete-v1/](https://ja.developer.box.com/guides/webhooks/v1/delete-v1/) --- ### Webhookの削除 **Type:** guide | **Category:** Webhook | **Section:** Developer Guides Webhookの削除 Webhookは、開発者コンソールまたはAPIを使用して削除できます。 開発者コンソール Webhookを削除するには、以下の手順に従います。 開発者コンソールで、[Webhook] タブに移動します。 WebhookのID… # Webhookの削除 Webhookは、[開発者コンソール](https://app.box.com/developers/console)またはAPIを使用して削除できます。 ## 開発者コンソール Webhookを削除するには、以下の手順に従います。 1. [開発者コンソール](https://app.box.com/developers/console)で、[**Webhook**] タブに移動します。 2. WebhookのIDをクリックして、削除するWebhookを選択します。 3. [**削除**] ボタンをクリックします。 4. 警告メッセージの下に表示される [**削除**] をクリックして、操作を確定します。 ## API ファイルやフォルダからWebhookを削除するには、WebhookのIDを指定して[Webhookを削除](e://delete-webhooks-id)エンドポイントを使用する必要があります。この値は、[すべてのWebhookのリストを取得](e://get-webhooks)エンドポイントを使用して取得できます。 ## Webhookの自動削除 [この](e://delete-webhooks-id)エンドポイントを使用していなくても、Webhookが削除される場合があります。 Webhookは以下の理由で削除される可能性があります。 Boxアプリケーションを削除すると、そのアプリケーションに関連付けられているすべてのWebhookが自動的に削除されます。 Webhookに関連付けられているアクティブなアクセストークンをすべて削除すると、そのWebhookが自動的に削除されます。これには、開発者トークンとパスワードが含まれます。 最後に成功した通知が設定したURLに配信されてから30日が経過し、最後に通知の配信が成功した日からユーザーが最後にイベントをトリガーした日までの期間が14日を超えた場合。 ユーザーがファイルをダウンロードするシナリオを見てみましょう。この操作により、Webhookがトリガーされ、設定したURLを使用して共有リンクを削除します。次の図では、このシナリオを表し、Webhookが削除されるタイミングを示しています。 - **ユーザーイベントトリガー**: ユーザーがイベント (例: ファイルのダウンロード) を開始したタイミング。 - **通知トリガー**: ファイルがダウンロードされたことを示す通知がWebhookに送信されたタイミング。 - **最終の通知配信**: Webhookが特定のURLにメッセージ (共有リンクの削除など) を送信したタイミング。 これらのすべてのケースで、Boxは`WEBHOOK.DELETED`というイベント名を含むWebhookペイロードを通知URLに送信します。ペイロードの本文には以下の追加情報が含まれます。 ``` "additional_info": { "reason": "auto_cleanup" } ``` **Source:** [https://ja.developer.box.com/guides/webhooks/v2/delete-v2/](https://ja.developer.box.com/guides/webhooks/v2/delete-v2/) --- ### Webhookの更新 **Type:** guide | **Category:** Webhook | **Section:** Developer Guides Webhookの更新 Webhookは、開発者コンソールまたはAPIを使用して更新できます。 開発者コンソール 開発者コンソールでWebhookを更新するには、以下の手順に従います。 開発者コンソールの [Webhook] タブに移動し、すべてのWebhook… # Webhookの更新 Webhookは、[開発者コンソール](https://app.box.com/developers/console)またはAPIを使用して更新できます。 ## 開発者コンソール [開発者コンソール](https://app.box.com/developers/console)でWebhookを更新するには、以下の手順に従います。 1. [開発者コンソール](https://app.box.com/developers/console)の [**Webhook**] タブに移動し、すべてのWebhookを表示します。 2. WebhookのIDをクリックして、更新するWebhookを選択します。 3. [**Webhookを編集**] ボタンをクリックします。 4. 更新するデータを入力します。 5. [**更新**] ボタンをクリックして変更を保存します。 Webhookのリストには、[**ID**]、[**アドレス**]、[**コンテンツ**]、[**作成者**]、[**作成日**] フィールドがあります。 ## API Webhookを更新するには、[Webhookを更新](e://put-webhooks-id)エンドポイントを使用します。それにはWebhook IDが必要です。WebhookのIDを調べるには、[すべてのWebhookのリストを取得](g://webhooks/v2/list-v2)エンドポイントを使用します。 **Source:** [https://ja.developer.box.com/guides/webhooks/v2/update-v2/](https://ja.developer.box.com/guides/webhooks/v2/update-v2/) --- ### xAI Grok 3 Beta **Type:** guide | **Category:** Box AI | **Section:** Developer Guides xAI Grok 3 Beta xAI Grok 3 Betaは、データの抽出、コーディング、テキストの要約など、企業のユースケースに優れているモデルです。金融、医療、法律、科学の深い専門知識を有しています。 モデルの詳細 項目 値 説明 モデル名 xAI Grok 3 Beta… # xAI Grok 3 Beta **xAI Grok 3 Beta**は、データの抽出、コーディング、テキストの要約など、企業のユースケースに優れているモデルです。金融、医療、法律、科学の深い専門知識を有しています。 ## モデルの詳細 | 項目 | 値 | 説明 | | --- | --- | --- | | モデル名 | xAI Grok 3 Beta | モデルの名前。 | | モデルのカテゴリ | プレミアム | モデルのカテゴリ - 標準またはプレミアム。 | | APIモデル名 | xai__grok_3_beta | Box AI APIでのモデルの上書きに使用されるモデルの名前。APIを動作させるには、ユーザーがこの名前を正確に指定する必要があります。 | | ホスティングレイヤー | xAI | LLMを安全にホストする、信頼できる組織。 | | モデルプロバイダ | xAI | このモデルを提供する組織。 | | リリース日 | 2025年4月17日 | モデルのリリース日。 | | ナレッジカットオフ日 | 2025年1月 | モデルが情報の更新を取得しなくなった日付。 | | 入力コンテキストウィンドウ | 100万トークン | 入力コンテキストウィンドウでサポートされるトークン数。 | | 出力トークンの最大数 | 131,000トークン | 1回のリクエストでモデルが生成できるトークン数。 | | 経験に基づいたスループット | 指定なし | モデルが1秒あたりに生成できるトークン数。 | | オープンソース | いいえ | モデルのコードを一般公開するかどうかを指定します。 | | 知的財産侵害からの保護 | いいえ | このモデルの使用には、Boxによる知的財産権の保証または保護は伴いません。このモデルの出力を使用することで発生する可能性もある知的財産の問題を考慮してください。 | ## その他のドキュメント 詳細については、[xAI Grok 3 Mini Betaの公式ドキュメント](https://docs.x.ai/docs/models)を参照してください。 **Source:** [https://ja.developer.box.com/guides/box-ai/ai-models/xai-grok-3-beta-model-card/](https://ja.developer.box.com/guides/box-ai/ai-models/xai-grok-3-beta-model-card/) --- ### xAI Grok 3 Mini Reasoning Beta **Type:** guide | **Category:** Box AI | **Section:** Developer Guides xAI Grok 3 Mini Reasoning Beta xAI Grok 3 Mini Reasoning Beta… # xAI Grok 3 Mini Reasoning Beta **xAI Grok 3 Mini Reasoning Beta**は、応答する前に思考する軽量モデルです。処理が速くスマートで、深い専門知識を必要としない、論理ベースのタスクに適しています。未加工の思考トレースにアクセスできます。 ## モデルの詳細 | 項目 | 値 | 説明 | | --- | --- | --- | | モデル名 | xAI Grok 3 Mini Reasoning Beta | モデルの名前。 | | モデルのカテゴリ | 標準 | モデルのカテゴリ - 標準またはプレミアム。 | | APIモデル名 | xai__grok_3_mini_reasoning_beta | Box AI APIでのモデルの上書きに使用されるモデルの名前。APIを動作させるには、ユーザーがこの名前を正確に指定する必要があります。 | | ホスティングレイヤー | xAI | LLMを安全にホストする、信頼できる組織。 | | モデルプロバイダ | xAI | このモデルを提供する組織。 | | リリース日 | 2025年4月9日 | モデルのリリース日。 | | ナレッジカットオフ日 | 不明 | モデルが情報の更新を取得しなくなった日付。 | | 入力コンテキストウィンドウ | 131,000トークン | 入力コンテキストウィンドウでサポートされるトークン数。 | | 出力トークンの最大数 | 131,000トークン | 1回のリクエストでモデルが生成できるトークン数。 | | 経験に基づいたスループット | 指定なし | モデルが1秒あたりに生成できるトークン数。 | | オープンソース | いいえ | モデルのコードを一般公開するかどうかを指定します。 | | 知的財産侵害からの保護 | いいえ | このモデルの使用には、Boxによる知的財産権の保証または保護は伴いません。このモデルの出力を使用することで発生する可能性もある知的財産の問題を考慮してください。 | ## その他のドキュメント 詳細については、[xAI Grok 3 Mini Betaの公式ドキュメント](https://docs.x.ai/docs/models)を参照してください。 **Source:** [https://ja.developer.box.com/guides/box-ai/ai-models/xai-grok-3-mini-beta-model-card/](https://ja.developer.box.com/guides/box-ai/ai-models/xai-grok-3-mini-beta-model-card/) --- ### ZIPアーカイブのダウンロード **Type:** guide | **Category:** ダウンロード | **Section:** Developer Guides ZIPアーカイブのダウンロード フォルダ内のすべてのファイル、またはフォルダ構造全体をダウンロードするには、ZIPアーカイブを作成してダウンロードする必要があります。 ZIPアーカイブの作成 最初に、ファイルまたはフォルダ構造を含むZIP… # ZIPアーカイブのダウンロード フォルダ内のすべてのファイル、またはフォルダ構造全体をダウンロードするには、ZIPアーカイブを作成してダウンロードする必要があります。 ## ZIPアーカイブの作成 最初に、ファイルまたはフォルダ構造を含むZIPアーカイブを作成する必要があります。アカウントのアップロード上限に達しない限り、最大10,000のファイルまたはフォルダIDを含めることができます。 レスポンスは以下のようになります。 ``` { "download_url": "https://dl.boxcloud.com/2.0/zip_downloads/25gvaXcIE4QJlinNiw2oHAQ==ZFs3Q2Xpd7pKBz7OyzXNrUaoW3aJxQRN5znAvyM-KpdEEPdWcQDKU-Dl85Ew/content", "status_url": "https://api.box.com/2.0/zip_downloads/25gvaXcIE4QJlinNiw2oHAQ==ZFs3Q2Xpd7pKBz7OyzXNrUaoW3aJxQRN5znAvyM-KpdEEPdWcQDKU-Dl85Ew/status", "expires_at": "2023-02-28T10:23:54Z", "name_conflicts": [] } ``` ## ZIPダウンロードIDの抽出 ZIPアーカイブをダウンロードするには、ZIPダウンロードIDが必要です。これは、アーカイブの作成時に返されたレスポンスで確認できます。 `status_url`に移動し、`zip_downloads`と`content`の間にあるIDをコピーします。 ``` 25gvaXcIE4QJlinNiw2oHAQ==ZFs3Q2Xpd7pKBz7OyzXNrUaoW3aJxQRN5znAvyM-KpdEEPdWcQDKU-Dl85Ew ``` ダウンロードURLは、`expires_at`パラメータで指定された日時まで有効です。 ## ファイルのダウンロード 以下のサンプルのように、ファイルの場所のURLにダウンロードIDを配置して、適切なファイルを指します。 ダウンロードに時間がかかる場合は、[ステータスのエンドポイント](e://get-zip-downloads-id-status)を使用してダウンロードのステータスを監視できます。これにより、ダウンロードの進行状況のほか、スキップされた可能性のある項目の数を確認できます。 SDKを使用してフォルダのコンテンツをダウンロードする場合は、[こちら](g://downloads/folder)のガイドに従ってください。 **Source:** [https://ja.developer.box.com/guides/downloads/zip-archive/](https://ja.developer.box.com/guides/downloads/zip-archive/) --- ### アーキテクチャスケルトンの作成 **Type:** guide | **Category:** ユーザー | **Section:** Developer Guides アーキテクチャスケルトンの作成 最初の要件は、アカウントの作成時に一般的なファイルとフォルダを個々のユーザーのルートフォルダにコピーすることです。この問題は、標準のLinuxディストリビューション内の/etc/skel… # アーキテクチャスケルトンの作成 最初の要件は、アカウントの作成時に一般的なファイルとフォルダを個々のユーザーのルートフォルダにコピーすることです。この問題は、標準のLinuxディストリビューション内の`/etc/skel`と呼ばれるディレクトリを介して解決されています。このディレクトリは、Box固有のソリューションによってエミュレートされます。Linuxで新しいユーザーを追加すると、`/etc/skel`内のファイルとフォルダが新しいユーザーのホームディレクトリにコピーされます。 [JWTベースのBoxアプリケーション](g://authentication/jwt/jwt-setup)を作成すると、Box Enterprise内に[サービスアカウント](page://platform/user-types/#service-account)が作成されます。サービスアカウントはBox Enterpriseの共同管理者に似た機能を持っており、このユースケースに最も有用で、ファイルおよびフォルダに対し、所有、コピー、および他のユーザーとのコラボレーションを行うことができます。さらに重要な点は、サービスアカウントは厳密にユーザー向けのPlatformアプリケーションの開発のみに使用する必要がなく、自動化処理の用途でも使用できるということです。 # Box Platformアプリケーションの要件 この手順のためにJWTベースのカスタムBoxアプリケーションを作成する場合、**ユーザーを管理する**、**グループを管理する**、**ユーザーとして操作を実行**、および**ユーザーアクセストークンを生成**スコープを有効にする必要があります。 JWTベースのBoxアプリケーションとBoxアプリケーションのスコープの作成の詳細については、[JWTアプリケーションの設定](g://authentication/jwt/jwt-setup)を参照してください。 初めに、`etc`フォルダと`skel`フォルダを作成し、サービスアカウントにフォルダの所有権を付与します。 ``` { "name": "etc", "parent": { "id": "0" }, "children": [ { "name": "skel", "children": [] } ] } ``` ``` [ { "name": "Market Research", "parent": { "id": "44884797174" }, "children": [ { "name": "Statistics", "children": [ { "name": "Computed", "children": [] } ] } ] }, { "name": "Sales Plays", "parent": { "id": "44884797174" }, "children": [ { "name": "Big Pharma", "children": [] } ] } ] ``` このコードを再利用して、上のJSONオブジェクトが示すフォーマットのフォルダ構造を構築することもできます。 ``` "use strict"; const fs = require("fs"); const box = require("box-node-sdk"); class BoxFolderTreeCreator { constructor(boxClient, options) { options = options || {}; if (options.boxClient) { throw new Error("Must include a boxClient field."); } options.boxFolderTreeName = options.boxFolderTreeName || "tree.json"; this.boxClient = boxClient; this.boxFolderTree = JSON.parse(fs.readFileSync(options.boxFolderTreeName)); this.createdBoxFolders = []; } async createFolderTree(branch = null, parentFolderId = "0") { this.createdBoxFolders = []; if (Array.isArray(this.boxFolderTree)) { let folderTasks = []; this.boxFolderTree.forEach(folder => { folderTasks.push(this._createFolder(folder, "")); }); await Promise.all(folderTasks); return this.createdBoxFolders; } else if (typeof this.boxFolderTree === "object") { console.log("Is object"); await this._createFolders(this.boxFolderTree, ""); return this.createdBoxFolders; } else { throw new Error("Incorrectly formatted JSON folder tree."); } } async _createFolders(branch, parentFolderId = "0") { if (branch.parent != null && branch.parent.id != null) { parentFolderId = branch.parent.id; } let folder; try { folder = await this.boxClient.folders.create(parentFolderId, branch.name); } catch (e) { let existingFolderId = BoxFolderTreeCreator.handleFolderConflictError(e); folder = await this.boxClient.folders.get(existingFolderId); } this.createdBoxFolders.push(folder); if (branch.children.length <= 0) { console.log("No more folders to create..."); return; } else { let createFolderTasks = []; branch.children.forEach(child => { console.log("Creating folder..."); console.log(child.name); createFolderTasks.push(this._createFolders(child, folder.id)); }); return await Promise.all(createFolderTasks); } } static handleFolderConflictError(e) { if (e && e.response && e.response.body) { let errorBody = e.response.body; if (errorBody.status === 409) { if ( errorBody.context_info && errorBody.context_info.conflicts && errorBody.context_info.conflicts.length > 0 ) { let conflict = errorBody.context_info.conflicts[0]; if (conflict && conflict.id) { return conflict.id; } } } } } } let configFile = fs.readFileSync("config.json"); configFile = JSON.parse(configFile); let session = box.getPreconfiguredInstance(configFile); let serviceAccountClient = session.getAppAuthClient("enterprise"); let treeCreator = new BoxFolderTreeCreator(serviceAccountClient); (async () => { let createdFolders = await treeCreator.createFolderTree(); console.log(createdFolders); })(); ``` ``` package com.box; import java.io.BufferedReader; import java.io.IOException; import java.nio.charset.Charset; import java.nio.file.Files; import java.nio.file.Path; import java.nio.file.Paths; import java.util.ArrayList; import java.util.regex.Matcher; import java.util.regex.Pattern; import com.box.sdk.BoxAPIException; import com.box.sdk.BoxConfig; import com.box.sdk.BoxDeveloperEditionAPIConnection; import com.box.sdk.BoxFolder; import com.eclipsesource.json.JsonObject; import com.eclipsesource.json.JsonValue; public class BoxFolderTreeCreator { private BoxDeveloperEditionAPIConnection _boxClient; private JsonValue _boxFolderTree; private ArrayList<BoxFolder.Info > _createdFolders; public BoxFolderTreeCreator(BoxDeveloperEditionAPIConnection boxClient) throws IOException { this(boxClient, "tree.json"); } public BoxFolderTreeCreator(BoxDeveloperEditionAPIConnection boxClient, String folderTreeFileName) throws IOException { this._boxClient = boxClient; try (BufferedReader tree = Files.newBufferedReader(Paths.get(folderTreeFileName))) { this._boxFolderTree = JsonValue.readFrom(tree); } this._createdFolders = new ArrayList<>(); } public ArrayList<BoxFolder.Info > createFolderTree() { if (this._boxFolderTree.isArray()) { for (JsonValue folder: this._boxFolderTree.asArray()) { System.out.println("Processing this folder: " + folder); _createFolders(folder.asObject(), null); } return this._createdFolders; } else { _createFolders(this._boxFolderTree.asObject(), null); return this._createdFolders; } } private void _createFolders(JsonObject branch, String parentFolderID) { if (parentFolderID == null && branch.get("parent") != null && branch.get("parent").asObject().get("id") != null) { System.out.println("Looking for parent folder id..."); System.out.println(branch.get("parent").asObject().get("id").asString()); parentFolderID = branch.get("parent").asObject().get("id").asString(); } System.out.println("Folder name:"); System.out.println(branch.get("name")); System.out.println("Parent Folder ID:"); System.out.println(parentFolderID); BoxFolder.Info createdFolder; try { BoxFolder parent = new BoxFolder(this._boxClient, parentFolderID); createdFolder = parent.createFolder(branch.get("name").asString()); } catch (BoxAPIException e) { if (e.getResponseCode() == 409) { // Use the ID returned from the conflict error to continue String conflictId = getIdFromConflict(e.getResponse()); createdFolder = new BoxFolder(this._boxClient, conflictId).getInfo(); } else { throw e; } } this._createdFolders.add(createdFolder); if (!branch.get("children").asArray().isEmpty()) { for (JsonValue child: branch.get("children").asArray()) { _createFolders(child.asObject(), createdFolder.getID()); } } else { return; } } private static String getIdFromConflict(String message) { String id = ""; Pattern p = Pattern.compile("\"id\":\"[0-9]+\""); Pattern p2 = Pattern.compile("[0-9]+"); Matcher m = p.matcher(message); if (m.find()) { String sub = m.group(); Matcher m2 = p2.matcher(sub); if (m2.find()) { id = m2.group(); } } return id; } public static void main(String[] args) throws Exception { Path configPath = Paths.get("config.json"); try (BufferedReader reader = Files.newBufferedReader(configPath, Charset.forName("UTF-8"))) { BoxConfig boxConfig = BoxConfig.readFrom(reader); BoxDeveloperEditionAPIConnection serviceAccountClient = BoxDeveloperEditionAPIConnection .getAppEnterpriseConnection(boxConfig); BoxFolderTreeCreator treeBuilder = new BoxFolderTreeCreator(serviceAccountClient, "etc_skel.json"); ArrayList<BoxFolder.Info > folders = treeBuilder.createFolderTree(); for (BoxFolder.Info folder: folders) { System.out.println(folder.getID()); } } } } ``` ``` using System; using System.Collections; using System.Collections.Generic; using System.IO; using System.Linq; using System.Threading.Tasks; using Box.V2; using Box.V2.Config; using Box.V2.Exceptions; using Box.V2.JWTAuth; using Box.V2.Models; using Newtonsoft.Json.Linq; namespace BoxPlayground { public class Program { static void Main(string[] args) { ExecuteMainAsync().Wait(); } private static async Task ExecuteMainAsync() { using(FileStream fs = new FileStream("./config.json", FileMode.Open)) { var session = new BoxJWTAuth(BoxConfig.CreateFromJsonFile(fs)); var client = session.AdminClient(session.AdminToken()); var treeCreator = new BoxFolderTreeCreator(client, "etc_skel.json"); var createdFolders = await treeCreator.CreateFolderTree(); foreach(var folder in createdFolders) { System.Console.WriteLine(folder.Name); System.Console.WriteLine(folder.Id); } } } public class BoxFolderTreeCreator { public BoxClient BoxClient { get; set; } public JToken BoxFolderTree { get; set; } public List < BoxFolder > CreatedBoxFolders { get; set; } public BoxFolderTreeCreator(BoxClient boxClient, string boxFolderTreeFileName = "tree.json") { this.BoxClient = boxClient; this.BoxFolderTree = JToken.Parse(File.ReadAllText(boxFolderTreeFileName)); this.CreatedBoxFolders = new List < BoxFolder > (); } public async Task < List < BoxFolder >> CreateFolderTree(dynamic branch = null, string parentFolderId = "0") { this.CreatedBoxFolders = new List < BoxFolder > (); if (this.BoxFolderTree is JArray) { var folderTasks = new List < Task > (); foreach(JObject folder in this.BoxFolderTree) { folderTasks.Add(_createFolder(folder, String.Empty)); } await Task.WhenAll(folderTasks); return this.CreatedBoxFolders; } else if (this.BoxFolderTree is JObject) { System.Console.WriteLine("Is object"); await _createFolder(this.BoxFolderTree as JObject, String.Empty); return this.CreatedBoxFolders; } else { throw new Exception("Incorrectly formatted JSON folder tree."); } } private async Task _createFolder(dynamic branch, string parentFolderId = "0") { if (branch.parent != null && branch.parent.id != null) { parentFolderId = branch.parent.id; } BoxFolder createdFolder; try { createdFolder = await this.BoxClient.FoldersManager.CreateAsync( new BoxFolderRequest { Parent = new BoxRequestEntity { Id = parentFolderId }, Name = branch.name }); } catch(BoxConflictException < BoxFolder > e) { createdFolder = await this.BoxClient.FoldersManager.GetInformationAsync(e.ConflictingItems.FirstOrDefault().Id); } this.CreatedBoxFolders.Add(createdFolder); if (branch.children.Count <= 0) { System.Console.WriteLine("No more folders to create..."); return; } else { var createFolderTasks = new List < Task > (); foreach(var child in branch.children) { System.Console.WriteLine("Creating folder..."); System.Console.WriteLine(child.name); createFolderTasks.Add(_createFolder(child as JObject, createdFolder.Id)); } await Task.WhenAll(createFolderTasks); } } } } } ``` **Source:** [https://ja.developer.box.com/guides/users/provision/architecture/](https://ja.developer.box.com/guides/users/provision/architecture/) --- ### アクセストークン **Type:** guide | **Category:** 認証 | **Section:** Developer Guides アクセストークン アクセストークンは、Boxサーバーに対して認証済みユーザーを表すために、ユーザー名とパスワードの代わりに使用される資格情報です。 トークンオブジェクト OAuth 2.0認証 OAuth 2.… # アクセストークン アクセストークンは、Boxサーバーに対して認証済みユーザーを表すために、ユーザー名とパスワードの代わりに使用される資格情報です。 ## トークンオブジェクト ### OAuth 2.0認証 OAuth 2.0を使用してアクセストークンをリクエストすると、アクセストークンと更新トークンのペアが返されます。 ``` curl -X POST https://api.box.com/oauth2/token \ -H "content-type: application/x-www-form-urlencoded" \ -d '...' ``` ``` { "access_token": "c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ", "expires_in": 3600, "token_type": "bearer", "refresh_token": "c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ", "issued_token_type": "urn:ietf:params:oauth:token-type:access_token" } ``` このオブジェクト内には、トークン文字列 (`access_token`) のほか、現在のトークンの有効期限が切れたとき (`expires_in`) に新しいアクセストークンのリクエストに使用できる更新トークン (`refresh_token`) があります。 ### サーバー認証 JWTまたはクライアント資格情報許可を使用してアクセストークンをリクエストすると、アクセストークンのみが返されます。 ``` curl --location --request POST 'https://api.box.com/oauth2/token' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode '...' ``` ``` { "access_token": "DkXZmsjUKizvL2z0WiaLvMBeQ756XCGGf", "expires_in": 4123, "restricted_to": [], "issued_token_type": "bearer" } ``` このオブジェクト内には、トークン文字列 (`access_token`) があります。更新トークンは返されないため、アクセストークンの有効期限が切れたとき (`expires_in`) には、[トークンエンドポイント](e://post-oauth2-token)を使用して、新しいトークンをリクエストする必要があります。 **Source:** [https://ja.developer.box.com/guides/authentication/tokens/access-tokens/](https://ja.developer.box.com/guides/authentication/tokens/access-tokens/) --- ### アクセストークンの取得 **Type:** guide | **Category:** ツール | **Section:** Developer Guides アクセストークンの取得 すべてのAPIコールでは、認証済みユーザーの本人確認のためにアクセストークンが要求されます。セキュリティ上の理由により、アクセストークンは60分後に期限切れになります。OAuth 2.… # アクセストークンの取得 すべてのAPIコールでは、認証済みユーザーの本人確認のために**アクセストークン**が要求されます。セキュリティ上の理由により、アクセストークンは60分後に期限切れになります。[OAuth 2.0](g://authentication/oauth2)を使用している場合は、提供された[更新トークン](g://authentication/tokens/refresh/)を使用して、新しいアクセストークンを取得してください。サーバー認証、[JWT](g://authentication/jwt)、または[クライアント資格情報許可](g://authentication/client-credentials)を使用している場合は、[トークンエンドポイント](e://post-oauth2-token)に対してAPIコールを実行して、新しいアクセストークンをリクエストしてください。 ## OAuth 2.0 アプリケーションが認証に[OAuth 2.0](g://authentication/oauth2)を利用している場合は、以下の手順に従って[Postman](g://tooling/postman/install)を使用してトークンのペアを取得できます。 - `grant_type`は常に`authorization_code`です。 - `client_id`と`client_secret`の値は、[開発者コンソール](https://app.box.com/developers/console)でアプリケーションの [**構成**] タブから取得できます。 `code`の値を取得するには、ブラウザで[承認URL](g://authentication/oauth2/without-sdk)を作成してアクセスします。OAuth 2.0のフローを完了し、構成済みのリダイレクトURLにリダイレクトすると、そのURLの末尾に承認コードがあります。この承認コードの有効期間は30秒間のみであることに注意してください。つまり、有効期限が切れる前に、Postmanの指定フィールドに承認コードを入力し、[**Send (送信)**] をクリックする必要があります。そのため、コードを取得したらすぐにAPIコールを送信できるように、他の値を入力しておくことをお勧めします。 **Source:** [https://ja.developer.box.com/guides/tooling/postman/access-token/](https://ja.developer.box.com/guides/tooling/postman/access-token/) --- ### アクセストークンの更新 **Type:** guide | **Category:** ツール | **Section:** Developer Guides アクセストークンの更新 Box APIから認証を受けるために、Postmanコレクションはアクセストークンを使用してAPIに対してユーザーの本人確認を行います。アクセストークンは1時間で有効期限が切れるため、1時間ごとに更新する必要があります。 更新トークンの使用 Postman… # アクセストークンの更新 Box APIから認証を受けるために、Postmanコレクションは**アクセストークン**を使用してAPIに対して**ユーザー**の本人確認を行います。アクセストークンは1時間で有効期限が切れるため、1時間ごとに更新する必要があります。 ## 更新トークンの使用 **Postmanクイックスタート**ガイドの[手順2](g://tooling/postman/quick-start/configure-box-app)で独自の**Boxアプリ**を設定した場合、PostmanのBox環境には有効な`client_id`と`client_secret`を用意する必要があります。これらのクライアント資格情報と`refresh_token`を使用すると、`access_token`の新しい値を作成できます。 アクセストークンを更新するには、Postmanコレクションの [**Authorization (承認)**] フォルダ内で [**Refresh access token (アクセストークンを更新)**] APIコールを選択します。 次に、[**Send (送信)**] ボタンをクリックして新しい`access_token`をリクエストします。 このAPIコールが終了すると、環境に`access_token`と`refresh_token`の新しい値が作成され、その他のAPIコールを実行できるようになります。 更新トークンは1回のみ有効で、60日以内に使用する必要があります。60日以内に使用すれば、新しい更新トークンが新しいアクセストークンとともに作成され、そこから再び60日の有効期間が始まります。 更新トークンは60日以内に使用されなければ期限切れになります。その後は、[クイックスタート](g://tooling/postman/quick-start)ガイドの手順を再度実行して、新しい更新トークンとアクセストークンをリクエストする必要があります。 ## アクセストークンの自動更新 Postmanコレクションは自動的に期限切れの`access_token`値を検出し、`refresh_token`を使用して新しい値をリクエストできます。この機能は、デフォルトで有効になっていますが、`enable_auto_refresh_access_token` Postman環境変数を`false`に設定することで無効にできます。 この値を設定するには、Box Postman環境変数の右上にある編集ボタンをクリックします。 テーブルで`enable_auto_refresh_access_token`変数の行を見つけて、[**Current Value (現在の値)**] を`true`に設定します。次に、[**Update (更新)**] をクリックして変更を保存します。 その後、APIコールを実行するたびに、**Postmanコレクション**は`access_token`の有効期限が切れているかどうかを確認し、目的のAPIコールを行う前に自動的に更新しようとします。 ## Postmanコレクションの再認証 [クイックスタート](g://tooling/postman/quick-start)ガイドの手順を再び実行することで、Postmanコレクションの再認証が必要になる場合があります。そのよくある理由として、Postmanコレクションを使用しないまま60日が経過し、`refresh_token`の有効期限が切れたことが挙げられます。 再認証するためには、まず古い**Box Postman環境**を削除します。これには、右上の小さな**歯車**アイコンをクリックし、リストからその環境を選択します。 [**Delete (削除)**] を選択して環境を削除します。その後、Postman[クイックスタート](g://tooling/postman/quick-start)ガイドの手順を再び最初から実行します。 **Box Postmanコレクション**の2回目のインポート時には、Postmanアプリで、新しいコレクションをコピーとしてインポートするか、古いコレクションを置き換えるかを確認される場合があります。APIに対してこれまでに行ったカスタム設定を保持するため、コピーとしてインポートすることをお勧めします。 **Source:** [https://ja.developer.box.com/guides/tooling/postman/refresh/](https://ja.developer.box.com/guides/tooling/postman/refresh/) --- ### アクセスのカスタマイズ **Type:** guide | **Category:** Boxの埋め込み | **Section:** Developer Guides アクセスのカスタマイズ 動機 Box UI Elementsは、クライアントで初期化され、Boxに対して直接APIコールを実行します。したがって、すべてのBox API… # アクセスのカスタマイズ ## 動機 Box UI Elementsは、クライアントで初期化され、Boxに対して直接APIコールを実行します。したがって、すべてのBox APIリクエストが認証されなければならないため、有効なアクセストークンがクライアントにある必要があります。 [トークン交換](g://authentication/tokens/downscope)とは、「親トークン」(管理対象ユーザー、App User、サービスアカウント、またはアプリケーションのトークン) を「子トークン」に交換するためのメカニズムです。「子トークン」は、クライアントの権限を引き上げることなく安全にクライアントに送信できるように、必要最小限の権限のセットにダウンスコープしたものです。 Box UI Elementsは、トークンの権限に対応するよう設計されています。そのため、Box UI Elementsとともにトークン交換を使用すると、クライアントトークンに対する適切な権限セットがあれば、フロントエンドの開発者が手動でUIコントロールのオン/オフを切り替える必要はないという別のメリットがもたらされます。この動作は、Boxアプリケーションでの動作にも似ています。たとえば、フォルダに対して「プレビューのみ」の権限を持つユーザーの場合、UIに [ダウンロード] ボタンは表示されません。 次の設計図では、アプリケーションでUI Elementとともにトークン交換を使用する方法と、ユースケースの例を示しています。 - **クライアントからのAPIコールのセキュリティ強化:** 一般的なセキュリティ対策として、ユーザーによってアクションが実行されるたびにダウンスコープされたトークンを生成して送信し、クライアントができるだけ危険にさらされないようにすることをお勧めします。たとえば、ユーザーがファイルに対するプレビューおよび共有権限を必要とする場合でも、クライアントにユーザートークンを送信してユーザーに完全なユーザーレベルのアクセス権限を付与するのではなく、トークン交換を使用してトークンをダウンスコープし、ユーザーがファイルをプレビューしたい場合は「プレビューのみ」のトークンを、ファイルを共有したい場合は「共有」トークンを送信することをお勧めします。 - **カスタム権限モデルの作成:** UI Elementを使用してアプリケーションを構築していて、デフォルトのBoxアクセスレベルが実際の権限モデルに合わない場合は、すべてのユーザーに対する完全なスコープのトークンから始め、適宜トークン交換を使用して、独自の権限モデルに対応するようダウンスコープしていくことができます。 - **Boxサービスをトランザクションで使用 (Boxユーザーアカウントがない場合):** Boxにユーザーを作成しないでBoxサービスをトランザクションで使用している場合、ユーザーレベルのトークンにはアクセスできません。このような場合は、トークン交換を使用してサービスアカウントトークンを適切なスコープのトークンにダウンスコープできます。 - **別のユーザーのコンテンツへのアクセス権限を付与することのみを目的としたユーザーの作成:** エンドユーザーに別のアプリ/管理対象ユーザーのコンテンツへの「1回限り」のアクセス権限を与える必要がある場合は、トークン交換を使用すると、アプリ/管理対象ユーザーのトークンを、エンドユーザーにアクセスを許可したい特定の権限とファイル/フォルダにダウンスコープし、そのトークンをUI Elementに渡してエンドユーザーがそのコンテンツにアクセスできるようにすることができます。たとえば、トークン交換を使用した場合、ユーザートークンを、コンテンツに対するアクセス権限が読み取り専用になるようダウンスコープし、そのトークンを別のユーザーに渡すことができます。 ## 実装 上記のすべてに対する解決策として、トークン交換を使用して親トークンをダウンスコープされたトークンに交換し、そのトークンを使用してUI Elementを初期化します。 トークン交換では、「親トークン」、「スコープのリスト」、およびファイル/フォルダID (省略可) を入力引数として受け取り、これらの厳密なスコープのセットとそれぞれのファイル/フォルダID (入力引数に指定されている場合) にダウンスコープされたトークンが返されます。 # UI Element向けに設計された専用スコープ Boxでは、UI Elementとシームレスに連動する一連のスコープを設計しました。トークン交換はすべてのBoxスコープで動作しますが、設計したスコープには、基本機能に必要な権限セットに加えて、追加機能のための増分の権限も含まれているため、UI Elementと一緒にこれらのスコープを使用することをお勧めします。 ## 開発者のフロー さまざまなスコープについて説明したので、ここからはUI Elementでトークン交換を使用するシナリオを見ていきましょう。 **シナリオ:** Box Content Explorer UI Elementを使用してユーザーがフォルダツリーを閲覧できるようにして、ユーザーによるファイルのプレビューとダウンロードを許可します。共有は無効にする必要があります。 **手順:** ユースケースに応じて、管理対象ユーザー、App User、またはサービスアカウントを作成します。このユーザーまたはアプリケーションのトークンをトークン交換の親トークンとして使用します。ユーザートークンを生成するには、以下に従います。 - 管理対象ユーザーを作成する場合は、OAuthを使用した認証のガイド - App Userまたはサービスアカウントを作成する場合は、JWTを使用した認証のガイド 以下に示すようにコラボレータの作成APIを使用して、上で作成したユーザーをコラボレータとしてコンテンツに追加します。この手順では、ユーザーアカウントでユーザーにコンテンツに対するアクセス権限が与えられていない場合は、アクセス権限が与えられます。このユーザーのアカウントでファイル/フォルダが作成されている場合は、ユーザーはデフォルトでフォルダに対する「所有者」アクセス権限を持っているため、このコラボレーションの手順をスキップしてかまいません。 ``` curl https://api.box.com/2.0/collaborations \ -H "authorization: Bearer [ACCESS_TOKEN]" \ -d '{"item": { "id": "123456", "type": "folder"}, "accessible_by": { "id": "USER_ID", "type": "user" }, "role": "editor"}' \ -X POST ``` # Boxでのアクセスレベル BoxユーザーがBox内のファイル/フォルダでコラボレーションする場合に[7種類のアクセスレベル](https://community.box.com/t5/How-To-Guides-for-Sharing/What-Are-The-Different-Access-Levels-For-Collaborators/ta-p/144)を使用できます。このユーザーのアカウントでファイル/フォルダが作成されている場合は、ユーザーはデフォルトでフォルダに対する「所有者」アクセス権限を持っているため、このコラボレーションの手順をスキップしてかまいません。 - トークン交換APIを使用して親トークンを、コンテンツエクスプローラの基本スコープ (`base_explorer`) と特定の`folder_id` `123456`に有効な`item_download`および`item_preview`スコープを含む子トークンに交換します。この手順はアプリケーションサーバー上で実行することを強くお勧めします。 ### リクエスト ``` curl https://api.box.com/oauth2/token \ -d 'subject_token=ACCESS_TOKEN' \ -d 'subject_token_type=urn:ietf:params:oauth:token-type:access_token' \ -d 'scope=item_upload item_preview base_explorer' \ -d 'resource=https://api.box.com/2.0/folders/123456' \ -d 'grant_type=urn:ietf:params:oauth:grant-type:token-exchange' \ -X POST ``` ### レスポンス ``` { "access_token": "CHILD_TOKEN", "expires_in": 4247, "token_type": "bearer", "restricted_to": [ { "scope": "base_explorer", "object": { "type": "folder", "id": "123456", "sequence_id": "0", "etag": "0", "name": "FOLDER_NAME" } }, { "scope": "item_download", "object": { "type": "folder", "id": "123456", "sequence_id": "0", "etag": "0", "name": "FOLDER_NAME" } }, { "scope": "item_preview", "object": { "type": "folder", "id": "123456", "sequence_id": "0", "etag": "0", "name": "FOLDER_NAME" } } ], "issued_token_type": "urn:ietf:params:oauth:token-type:access_token" } ``` 上で取得した`CHILD_TOKEN`はダウンスコープされ、フォルダID`123456`とその子に対するダウンロードおよびプレビューの権限のみが含まれています。 この`CHILD_TOKEN`をコンテンツエクスプローラUI Elementで使用します。簡単なデモを確認するには、[コンテンツエクスプローラUI Element CodePenのサンプル](https://codepen.io/box-platform/pen/wdWWdN)を使用して、[JS] タブでアクセストークンの値とフォルダIDの値を置き換えてください。 [実行] をクリックします。指定したフォルダでコンテンツエクスプローラが初期化されることがわかります。また、コンテンツエクスプローラには、親 (ユーザー) トークンの使用時に表示される [共有] ボタンが表示されなくなることに注意してください。 ## トークン交換を使用すべきでない場合 **Box内のユーザーまたはグループを置き換えない:** Boxにユーザーを作成する代わりにトークン交換を使用することはお勧めしません。Boxユーザーを作成する必要があるかどうかを判断するには、アプリケーションのすべてのエンドユーザーが自身のコンテンツのコピーを保持することが妥当かどうかを評価します。以下に、Boxにユーザーレベルのアカウントを維持することで得られるメリットを示します。トークン交換だけでは、これらのメリットを得ることはできません。 - **コンテンツの分離とセキュリティ:** ユーザーレベルのアカウントの使用がより適しているのは、親トークンが誤って漏えいした場合でも、会社の全ユーザーではなく、1人のユーザーのコンテンツのセキュリティが侵害されるだけで済むからです。 - **パフォーマンス:** Boxにユーザーやグループを作成すると、アプリケーションでコンテンツにアクセスするときに適切な権限を決定する必要がなくなるので便利です。適切な権限を決定する処理は、アプリケーションのパフォーマンスに影響を及ぼす可能性が高くなります。 - **ユーザーレベルの追跡と監査:** 監査、アクセス統計情報、リテンションなど、いくつかのBox機能では、Boxのユーザーモデルが利用されます。これらの機能の使用が必須の場合は、ユーザーレベルのアカウントを作成する必要があります。 **Boxでのコラボレーションを置き換えない:** コラボレーションは、コンテンツに対するアクセス権限をBoxユーザーに提供するためのより標準的で拡張しやすい方法です。また、Boxでコラボレーションを使用してコンテンツへのアクセス権限を管理する場合、アプリケーションでは、どのユーザーにどのコンテンツへのアクセス権限が必要かについて、管理が必要なコードやデータの量が少なくなります。コラボレーションの代わりにトークン交換を使用すると、各ユーザーから、各ユーザーがアクセスできるすべてのファイルやフォルダへのマッピングを維持する必要があり、すべてのファイルやフォルダはすぐに制御できなくなる可能性があります。 **ダウンスコープされたトークンのキャッシュ:** アプリケーションにとってパフォーマンスが重要な場合は、ダウンスコープされたトークンをサーバー側で事前にキャッシュする必要があります。トークンを事前にキャッシュする場合は、トークンが1時間以内に期限切れになるため、再試行を実装することをお勧めします。 # トークンの寿命 親トークンおよび子トークンの寿命は互いに依存していません。たとえば、子トークンを生成しても親トークンが非アクティブになることはありません。同様に、子トークンをさらに生成しても、以前の子トークンにはまったく影響しません。 ## シナリオの例 ### シナリオ1: クライアントのAPIコールのセキュリティ強化 ある株式投資会社は、従業員が公開する情報を投資家に配信する目的 (表示のみのアクセス権限を使用) で、パートナーおよび投資家向けポータルを構築しています。 この会社は外部の顧客それぞれにApp Userを作成し、従業員はコンテンツの公開に使用したBoxアカウントをプロビジョニングしました。すべてのApp Userは、公開されたコンテンツでビューアー/アップローダーとしてコラボレーションしているため、必要に応じて自分のアカウントでコンテンツのプレビューとアップロードの両方を実行することができます。投資家やパートナーはサインインすると、情報を表示およびアップロードできるポータルが表示されます。 プレビューとアップロードの両方では、「ビューアー/アップローダー」トークンを渡す代わりに、クライアントを介してAPIコールを実行する必要があるため、アプリケーションではトークン交換を使用して、ユーザーが実行しようとしている処理に応じて適宜トークンをダウンスコープします。これにより、トークンのセキュリティが侵害された場合に、データ漏えいは最小限に抑えられ、アプリケーションの全体的なセキュリティ対策が強化されます。 ### シナリオ2: カスタム権限モデル ある大規模なフィンテック企業では、クライアントへの投資を管理するために、クライアントのセキュアな格納庫を構築しています。また、Box UI Elementsを使用してアプリケーションのコンテンツ管理フロントエンドも構築しています。 この会社では、通常どおりクライアントとアプリアドバイザごとにApp Userを作成します。App User間でコンテンツを共有する場合は、App Userを「編集者」ロール (Boxのロール) としてコラボレーションさせます。こうすることで、各App Userは自分以外のすべてのユーザーのコンテンツすべてにアクセスできるようになります。 ユーザーがUI Elementを介してコンテンツにアクセスできるように、アプリケーションがクライアントに直接App Userトークンを提供することはありません。これは、App Userが他のユーザーのコンテンツで「編集者」としてコラボレーションしている (強い権限を持っている) 可能性があるためです。代わりに、App Userトークンを使用したトークン交換により、ダウンスコープされたトークンが生成され、以下が制限されます。 - トークンの使用目的を示すスコープ (表示、アップロード、ダウンロード、閲覧、共有など) - ユーザーがアクセスできる特定のファイル ### シナリオ3: プロセスフロー ある非営利の信用組合では、ローン処理アプリケーションを開発しています。このアプリケーションでは、Boxのセキュアなコンテンツレイヤーを使用して、ローン申請者と社内ユーザー (ローン事務担当者とローン引受人) の間のドキュメントの共有を容易にします。基本的なプロセスは以下のとおりです。 - 顧客はローンを申請する際、申請手続きの一環として、独自に構築されたウェブポータルからドキュメント (収入証明や身分証明など) を提出します。 - Boxは、ドキュメントの送受信を仲介する機能として使用されます。 - 社内の従業員は、顧客に代わってファイルをアップロードする必要があります。 - 社内の従業員は、カスタムのウェブポータルとBoxウェブアプリからドキュメントにアクセスできます。 アプリケーション開発者は、UI Elementとともにトークン交換を使用して、ローン処理管理ソリューションを構築しました。このソリューションで、アプリケーションサーバーは、ローン申請のApp Userトークンを、クライアントが実行する必要のある処理に基づいてダウンスコープし、そのダウンスコープされたトークンをクライアント (顧客とローン担当者) に渡します。このようにダウンスコープされたトークンを使用すると、UI Elementは適切なコントロールやボタンを表示し、ユーザーに対して実行可能な操作を示すことができます (例: ダウンスコープされて渡されたトークンにアップロード権限が含まれていない場合、コンテンツエクスプローラUI Elementではアップロードボタンがグレー表示になります)。 ### シナリオ4: トランザクションフロー ある学習管理システムプロバイダは、Box Platformを使用して自社のアプリケーションのプレビュー機能を強化しています。すべてのユーザーおよび関連付けられている権限は、Box以外のアプリケーションで管理されています。Boxから見ると、そのアプリケーションからのAPIコールはすべて、(個々のユーザーではなく) そのアプリケーションのためのもので、保存およびプレビューされるコンテンツはすべて、個々のユーザーではなくアプリケーションに属しています。この場合、アプリケーション開発者は、Box全体の機能のうち一部 (プレビューなど) をトランザクションで使用していますが、その他のセキュアなコンテンツ共有機能やコラボレーション機能は使用していません。実際に、これは多くの顧客にとって重要なユースケースです。 このアプリケーションの簡単なユースケースを考えてください。エンドユーザーはファイルをアップロードした後、アプリケーション自体でプレビューする必要があるとします。そのために、アプリケーションではコンテンツアップローダーUI ElementとコンテンツプレビューUI Elementをそれぞれ使用しています。プレビューとアップロードはどちらも帯域幅を大量に消費する処理であるため、アプリケーションは、トラフィックをプロキシするのではなく、クライアントがこれらの処理を直接Boxに対して実行できるようにする必要があります。Boxに対して呼び出しを実行するために、すべてのUI Elementは、有効なアクセストークンをクライアント上で使用できる必要があります。ただし、アプリケーションは、権限のある「サービスアカウント」トークンをクライアントに渡さないようにしてください。渡した場合、クライアントは、アプリケーションを介してアップロードされたすべてのコンテンツにアクセスできるようになるためです。代わりに、アプリケーションではトークン交換を使用して、そのサービスアカウントトークンをアップロードのみのトークンにダウンスコープし、クライアントがアップロードUI Elementを使用してファイルをアップロードできるようにします。さらに、別途プレビューのみのトークンにダウンスコープし、クライアントがプレビューUI Elementを使用してプレビューできるようにします。 ## アンチパターン 以下に示すアンチパターンは、アプリ開発をさらに難しいものにしたり、アプリケーションのセキュリティやパフォーマンスを低下させたりするため推奨されないパターンをお客様が識別するのに役立ちます。アプリにこれらのパターンの実装が確認された場合は、Boxサポートに連絡して支援を求めてください。 ### 権限のあるトークンをクライアントに渡す これは絶対に行わないでください。お客様のBox Enterpriseでのコンテンツのセキュリティが侵害される可能性があります。必ずトークン交換を使用して、正確な権限セットをエンドユーザーに提供してください。 ### APIレスポンスをプロキシ/フィルタリングする BoxからのAPIレスポンスをプロキシ/フィルタリングして、クライアントへのデータやコンテンツの公開を制限するだけの場合は、トークン交換を使用することで公開を制限できるかどうかを確認してみてください。特に、プレビュー、ダウンロード、アップロードなどの帯域幅を集中的に使用する、高帯域幅の処理に当てはまります。そのため、Boxでは、クライアントがBoxを使用してこれらの処理を直接実行することをお勧めします。 **Source:** [https://ja.developer.box.com/guides/embed/ui-elements/access/](https://ja.developer.box.com/guides/embed/ui-elements/access/) --- ### アクセス制限付きアプリ **Type:** guide | **Category:** アプリケーション | **Section:** Developer Guides アクセス制限付きアプリ アクセス制限付きアプリは、Box Viewを利用したり、別のアプリケーション内でBox… # アクセス制限付きアプリ アクセス制限付きアプリは、[Box View](g://embed/box-view)を利用したり、別のアプリケーション内でBoxコンテンツをプレビューしたりする場合に使用されます。この種類のアプリケーションで操作できる[エンドポイントの数は限られています](g://authentication/app-token/endpoints)。 ## 認証方法 アクセス制限付きアプリでサポートされているのは、アプリトークン認証のみです。 アプリトークンの詳細を確認する ## 使用するタイミング アプリケーションが以下のような場合に、アクセス制限付きアプリを使用すると最も効果的です。 - Box ViewまたはBoxのプレビューサービスだけを使用する - [限られた数のエンドポイント](g://authentication/app-token/endpoints)だけにアクセスする必要がある ## ユースケース - プロのクリエイターの作品集をウェブサイトで紹介する - サポートサイトでユーザーマニュアルや製品仕様ドキュメントを提供する - カスタムドキュメントビューアーで電子書籍を表示したり間取り図に注釈を付けたりする ## 承認 アクセス制限付きアプリは、使用前に承認が必要になる場合があります。 アクセス制限付きアプリの承認方法を確認する **Source:** [https://ja.developer.box.com/guides/applications/app-types/limited-access-apps/](https://ja.developer.box.com/guides/applications/app-types/limited-access-apps/) --- ### アクセス制限付きアプリの承認 **Type:** guide | **Category:** 承認 | **Section:** Developer Guides アクセス制限付きアプリの承認 アクセス制限付き統合は、作成時に企業での使用について自動的に承認されます。 ただし、Enterprise… # アクセス制限付きアプリの承認 アクセス制限付き統合は、作成時に企業での使用について自動的に承認されます。 ただし、Enterprise設定の [**アクセス制限付きアプリの場合に管理者の承認を要求する**] が有効になっている場合、管理者は追加の手順を行う必要があります。 ## 承認の通知 アプリの承認を送信するための半自動プロセスは、開発者コンソールで利用できます。 [開発者コンソール](https://app.box.com/developers/console)で、目的のアプリケーションの [**承認**] タブに移動します。 承認を得るためにアプリケーションを送信すると、企業のプライマリ管理者宛てにアプリケーションを承認するようメールが送信されます。このプロセスの詳細については、[アプリ承認に関するサポート記事](https://support.box.com/hc/ja/articles/360043697014-Box%E3%81%AE%E3%82%A2%E3%83%97%E3%83%AA%E6%89%BF%E8%AA%8D%E3%83%97%E3%83%AD%E3%82%BB%E3%82%B9%E3%81%A7%E3%81%AE%E3%82%A2%E3%83%97%E3%83%AA%E3%81%AE%E6%89%BF%E8%AA%8D)を参照してください。 ## 手動による承認 以下の手順では、手動でアプリケーションを承認する方法について説明します。 ### 開発者の場合 1. [開発者コンソール](https://app.box.com/developers/console)で、目的のアプリケーションの [**構成**] タブに移動します。 2. [OAuth 2.0資格情報] セクションまで下にスクロールし、Box管理者に提出する [**クライアントID**] の値をコピーします。 また、[[Platformアプリ](g://applications)] ビューでアプリケーションにカーソルを合わせて**クライアントID**を調べ、`copy`ボタンを使用してそのIDをコピーすることもできます。 # Box管理者の確認方法 自分の会社の管理者がわからない場合は、Boxの [[アカウント設定](https://app.box.com/account)] ページに移動し、一番下までスクロールしてください。管理者の連絡先が設定されている場合は、[**管理者の連絡先**] の下に連絡先情報が表示されます。 ### 管理者の場合 Box管理者は、[管理コンソール](https://app.box.com/master/settings/custom)に移動し、[**統合**] > [**Platformアプリマネージャ**] > [**Platformアプリの追加**] を選択します。 表示されたポップアップで、開発者が開発者コンソールの [**構成**] タブから収集した、アプリケーションのクライアントIDを入力します。 ## 変更の再承認 アプリケーションのスコープまたはアクセスレベルが変更された場合は、アプリケーションを再承認する必要があります。新しい変更を有効にするには、上記のプロセスを繰り返して新しいアクセストークンをリクエストしてください。 管理者は、アプリケーションが最初に承認されたのと同じセクションで、そのアプリケーションを再承認できます。再承認するには、アプリケーション名の右側にある省略記号をクリックし、[**アプリを再承認**] を選択します。 **Source:** [https://ja.developer.box.com/guides/authorization/limited-access-approval/](https://ja.developer.box.com/guides/authorization/limited-access-approval/) --- ### アップロード **Type:** guide | **Category:** アップロード | **Section:** Developer Guides アップロード Box APIは、2つのファイルアップロード方法をサポートしています。直接ファイルアップロードAPIは最大50 MBのファイルをサポートしており、1回のAPIリクエストですべてのバイナリデータをBox APIに送信します。 分割アップロードAPIは20 MB… # アップロード Box APIは、2つのファイルアップロード方法をサポートしています。[直接ファイルアップロードAPI](g://uploads/direct)は最大50 MBのファイルをサポートしており、1回のAPIリクエストですべてのバイナリデータをBox APIに送信します。 [分割アップロードAPI](g://uploads/chunked)は20 MB以上のファイルをサポートしており、アプリケーションではファイルを複数のパーツに分割してアップロードすることで、エラーのキャッチと個別のパーツの再送信を詳細に制御できます。 アーカイブフォルダにファイルをアップロードするには、最初に、開発者コンソールで[グローバルコンテンツマネージャ](g://api-calls/permissions-and-errors/scopes) (GCM) スコープを有効にする必要があります。 ## アップロードの制限 アップロードの上限は、認証済みユーザーのアカウントの種類によって決まります。詳細については、このトピックに関する[Boxコミュニティの記事](https://support.box.com/hc/ja/articles/360043697314-Box%E3%81%AB%E3%82%A2%E3%83%83%E3%83%97%E3%83%AD%E3%83%BC%E3%83%89%E3%81%A7%E3%81%8D%E3%82%8B%E6%9C%80%E5%A4%A7%E3%83%95%E3%82%A1%E3%82%A4%E3%83%AB%E3%82%B5%E3%82%A4%E3%82%BA)を参照してください。 ## 事前チェック 事前チェックAPIを使用すると、アプリケーションでアップロードを開始する前にそのファイルがBoxに受け入れられるかどうかを確認できます。このAPIは、新しいファイルにも、既存ファイルの新しいバージョンのアップロードにも使用できます。 事前チェックの詳細を確認する ## アップロードドメイン Boxへのアップロードは、通常のAPIコールとは異なるドメイン (`upload.box.com`) を介して行われます。アップロードコードを作成するときは、この点に注意する必要があります。すべてのBox SDKで、APIコールに適切なドメインが選択されます。 **Source:** [https://ja.developer.box.com/guides/uploads/](https://ja.developer.box.com/guides/uploads/) --- ### アップロードセッションのコミット **Type:** guide | **Category:** アップロード | **Section:** Developer Guides アップロードセッションのコミット 分割アップロードの最後の手順はセッションのコミットです。 ファイルアップロードセッションをコミットするには、コミットするアップロード済みパーツのリストを指定してPOST /files/upload_sessions/:id/commit… # アップロードセッションのコミット 分割アップロードの最後の手順はセッションのコミットです。 ファイルアップロードセッションをコミットするには、コミットするアップロード済みパーツのリストを指定して[`POST /files/upload_sessions/:id/commit`](e://post_files_upload_sessions_id_commit)を呼び出します。 加えて、ファイルの`attributes`を`parts`とともに渡すことで、ファイルに情報を追加できます。詳細については、[`POST /files/content`](e://post_files_content) APIを参照してください。 ## レスポンス 成功すると、APIはHTTP `201 Created`ステータスコードと[`File`](r://file)オブジェクトを返します。 場合によっては、パーツの作成がまだ準備できておらず、代わりに`202 Accepted`ステータスコードが返されることがあります。この場合、アプリケーションは`retry-after`ヘッダーを確認し、指定された秒数後にコミットを再試行する必要があります。 **Source:** [https://ja.developer.box.com/guides/uploads/chunked/commit-session/](https://ja.developer.box.com/guides/uploads/chunked/commit-session/) --- ### アップロードセッションの作成 **Type:** guide | **Category:** アップロード | **Section:** Developer Guides アップロードセッションの作成 アップロードセッションを作成するには、目的のfile_nameとそのファイルを配置するfolder_id、およびアップロードするファイルのfile_sizeを指定してPOST /files/upload_sessions API… # アップロードセッションの作成 アップロードセッションを作成するには、目的の`file_name`とそのファイルを配置する`folder_id`、およびアップロードするファイルの`file_size`を指定して[`POST /files/upload_sessions`](e://post_files_upload_sessions) APIを呼び出します。 既存ファイルの新しいバージョン用のセッションを作成するには、代わりに[`POST /files/:id/upload_sessions`](e://post_files_id_upload_sessions) APIを呼び出します。この場合、`file_name`と`folder_id`は、プロセスでファイルの名前変更または移動を行う場合にのみ必要となります。 ## 事前チェック アップロードセッションの作成によって[事前チェック](g://uploads/check)も実行されるため、分割アップロードを行う際に個別に行う必要はありません。 ## レスポンス セッションが正常に作成されると、レスポンスには、セッションID、パーツ数、パーツサイズ、および使用する関連する次のAPIエンドポイントへのリンクを含む[アップロードセッション](r://upload_session)が含まれます。 ``` { "id": "F971964745A5CD0C001BBE4E58196BFD", "type": "upload_session", "session_expires_at": "2012-12-12T10:53:43-08:00", "part_size": 1024, "total_parts": 1000, "num_parts_processed": 455, "session_endpoints": { "upload_part": "https://upload.box.com/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD", "commit": "https://upload.box.com/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD/commit", "abort": "https://upload.box.com/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD", "list_parts": "https://upload.box.com/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD/parts", "status": "https://upload.box.com/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD", "log_event": "https://upload.box.com/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD/log" } } ``` アップロードセッションは、個々のパーツをアップロードするときに使用するパーツのサイズを定義します。 **Source:** [https://ja.developer.box.com/guides/uploads/chunked/create-session/](https://ja.developer.box.com/guides/uploads/chunked/create-session/) --- ### アプリケーション **Type:** guide | **Category:** アプリケーション | **Section:** Developer Guides アプリケーション Box開発者コンソールでは、後でBoxとの統合に使用できるアプリケーションを作成できます。[Platform… # アプリケーション Box開発者コンソールでは、後でBoxとの統合に使用できるアプリケーションを作成できます。[**Platformアプリ**] ビューには、すでに作成済みのアプリケーションのリストが表示されるので、ここから構成の詳細にすばやくアクセスできます。そのため、毎回アプリを開かなくても、開発者トークンを生成したり、クライアントIDをコピーしたり、レポートを生成したりできます。 ## 機能 [**Platformアプリ**] ページでは、以下の操作を行うことができます。 - 作成済みのアプリのリストを検索する。 - [**有効化ステータス**] および [**認証タイプ**] でアプリにフィルタをかける。 - [新しいアプリ](g://applications/app-types/select)を作成する。 - アプリの[クライアントID](g://authentication/client-credentials)をコピーする。 - アプリの名前を変更し、1回のクリックでその詳細にアクセスする。 - アプリケーションの[有効化](g://authorization/custom-app-approval#user-authentication-apps)ステータスと[承認](g://authorization)ステータスを確認する。統合に公開されたアプリには、統合でのステータスが表示されます。 各エントリに用意されている**オプションメニュー**を使用すると、以下の操作を行うことができます。 - アプリケーションの構成の詳細にアクセスする。 - [開発者トークン](g://authentication/tokens/developer-tokens)を生成する。 - アプリケーションにコラボレータを追加する。 - [Platform App Diagnosticsレポート](g://api-calls/permissions-and-errors/app-diagnostics-report)を実行する。 ## Platformアプリインサイト 管理者と共同管理者は、組織におけるプラットフォームの利用状況を集約した、Platformインサイトのダッシュボードにアクセスできます。これには、以下のような、アプリ関連のデータが含まれます。 - アプリケーションごとのAPIコールの合計数 - 企業内の上位アプリケーションのリスト - 承認を保留中のアプリケーションのリスト - 有効化待ちのアプリケーションのリスト 詳細については、[Platformインサイト](https://support.box.com/hc/en-us/articles20738406915219-Platform-Insights)を参照してください。 Platformインサイトにアクセスして表示するには、以下の権限が必要です。 - 会社の設定とアプリを表示する - 会社の設定とアプリを編集する - 新規レポートの実行および既存レポートへのアクセスを行う **Source:** [https://ja.developer.box.com/guides/applications/](https://ja.developer.box.com/guides/applications/) --- ### アプリケーションコードのスキャフォールディング **Type:** quick-start | **Category:** コラボレーション | **Section:** Developer Guides アプリケーションコードのスキャフォールディング SlackおよびBoxアプリケーションを構成したら、Slackから送信されるスラッシュコマンドやイベントをリッスンするアプリケーションのコードを作成できます。 このアプリケーションは、以下の… # アプリケーションコードのスキャフォールディング SlackおよびBoxアプリケーションを構成したら、Slackから送信されるスラッシュコマンドやイベントをリッスンするアプリケーションのコードを作成できます。 このアプリケーションは、以下の3つの機能に分割されます。 - 最初のアプリケーションスケルトンと構成情報を設定する - Slackイベントとスラッシュコマンドのハンドラを設定する - このハンドラをBoxの必要な関数に関連付ける ## 依存関係とスキャフォールドコードの追加 最初に、アプリケーションの実行に必要なファイルと最小限のコードのスキャフォールディングを行います。 - アプリケーション用に新しいローカルディレクトリを作成するか、[手順1](g://collaborations/connect-slack-to-group-collabs/configure-slack)のSlackイベントURLチャレンジ用に作成した既存のコードを読み込みます。 - ローカルディレクトリ内で新しい`package.json`ファイルを作成するか既存のファイルを更新します。任意のエディタでそのファイルを開き、以下の内容をコピーして貼り付け、ファイルを保存して終了します。 ``` { "name": "box-slack", "version": "1.0.0", "description": "Box Slack integration", "main": "process.js", "scripts": { "test": "echo \"Error: no test specified\" && exit 1", "start": "node process.js" }, "author": "Box", "license": "ISC", "dependencies": { "axios": "^0.19.2", "body-parser": "^1.19.0", "box-node-sdk": "^1.33.0", "express": "^4.17.1" } } ``` - ターミナル/コンソールから`npm install`を実行し、依存関係をインストールします。 - ローカルディレクトリに2つのファイル (`process.js`および`slackConfig.json`) を作成します。 - `slackConfig.json`を開いて、以下のデフォルト構成を保存します。 ``` { "verificationToken": "TOKEN", "botToken": "TOKEN" } ``` 上記の2つの値は、Slackアプリケーションから取得した詳細情報に置き換える必要があります。`TOKEN`文字列を適切な値に置き換えてください。 - `verificationToken`: Slackアプリケーションの構成ページを読み込みます。[**Basic Information (基本情報)**] ページで、[**App Credentials (アプリの資格情報)**] セクションまで下にスクロールし、[**Verification Token (確認トークン)**] の文字列を使用できます。 - `botToken`: Slackアプリケーションで、[**OAuth & Permissions (OAuthと権限)**] ページに移動し、上部にある [**Bot User OAuth Access Token (ボットユーザーOAuthアクセストークン)**] の文字列を使用できます。この文字列は、ボットがSlackワークスペースに追加されたときに自動入力されています。 空の`process.js`ファイルを開き、次のコードをコピーして貼り付け、ファイルを保存します。 ``` const box = require("box-node-sdk"); const slackConfig = require("./slackConfig.json"); const boxConfig = require("./boxConfig.json"); const express = require("express"); const app = express(); const axios = require("axios"); const util = require("util"); app.use(express.urlencoded({ extended: true })); app.use(express.json()); // INSTANTIATE BOX CLIENT app.post('/event', (req, res) => { //HANDLE INCOMING EVENTS }); const handler = (() => { function process(res, data) { // PROCESS EVENTS } function processUser(user, event, channel) { // PROCESS USER ADD / REMOVE REQUEST } function addGroupUser(groupId, email) { // ADD USER TO BOX GROUP } function removeGroupUser(groupId, email) { // REMOVE USER FROM BOX GROUP } function processContent(user, channel, type, fid) { // COLLABORATE CONTENT WITH GROUP } function processSlackChannel(channel, gid) { // ADD ALL SLACK CHANNEL USERS TO GROUP } function getSlackUser(userId, _callback) { // GET SLACK USER PROFILE } function getGroupId(groupName, _callback) { // GET AND CREATE BOX GROUP } return { process }; })(); const port = process.env.PORT || 3000; app.listen(port, function(err) { console.log("Server listening on PORT", port); }); ``` このコードには、SlackとBox間の通信を処理するのに必要となる主要な関数がすべて含まれています。これらの関数について、上から順に説明します。 - `/event`ハンドラ: 入ってくるSlackトラフィックをすべて取得し、内容を確認して、`process`関数に転送します。 - `process`: Slackイベントを解析し、Boxグループの処理 (ユーザーチャンネルイベント) またはグループへのBoxコンテンツの追加 (スラッシュコマンド) のいずれかにそのイベントを転送します。 - `processUser`: 適切な関数に転送することでBoxグループのユーザーを追加または削除して、User Eventを処理します。 - `addGroupUser`: Boxグループにユーザーを追加します。 - `removeGroupUser`: Boxグループからユーザーを削除します。 - `processContent`: BoxグループとBoxコンテンツのコラボレーションを行います。 - `processSlackChannel`: すべてのSlackチャンネルユーザーをBoxグループに追加します。 - `getSlackUser`: SlackユーザーのプロフィールをSlackユーザーIDから取得します (ユーティリティ関数)。 - `getGroupId`: Boxグループ名からBoxグループIDを取得します (ユーティリティ関数)。 Slackの資格情報とURLを保持するための構成ファイルを作成する必要があります。 - `Application.java`ファイルが配置されている`src/main/java`パスに、`slackConfig.java`という名前の新しいJavaクラスファイルを作成します。 - ファイルを開き、次の内容を保存します。 ``` package com.box.slack.box; public class slackConfig { public static String verificationToken = "TOKEN"; public static String botToken = "TOKEN"; public static String slackApiUrl = "https://slack.com/api"; } ``` 上記の2つの値は、Slackアプリケーションから取得した詳細情報に置き換える必要があります。`TOKEN`文字列を適切な値に置き換えてください。 - `verificationToken`: Slackアプリケーションの構成ページを読み込みます。[**Basic Information (基本情報)**] ページで、[**App Credentials (アプリの資格情報)**] セクションまで下にスクロールし、[**Verification Token (確認トークン)**] の文字列を使用できます。 - `botToken`: Slackアプリケーションで、[**OAuth & Permissions (OAuthと権限)**] ページに移動し、上部にある [**Bot User OAuth Access Token (ボットユーザーOAuthアクセストークン)**] の文字列を使用できます。この文字列は、ボットがSlackワークスペースに追加されたときに自動入力されています。 以前のSlackイベントチャレンジの設定で作成した`Application.java`ファイルを開き、ファイルの内容を次の内容に置き換えます。 ``` package com.box.slack.box; import java.io.BufferedReader; import java.io.FileReader; import java.io.InputStreamReader; import java.io.Reader; import java.io.UnsupportedEncodingException; import java.net.HttpURLConnection; import java.net.URL; import java.nio.charset.StandardCharsets; import java.util.Iterator; import javax.servlet.http.HttpServletResponse; import org.jose4j.json.internal.json_simple.JSONArray; import org.jose4j.json.internal.json_simple.JSONObject; import org.jose4j.json.internal.json_simple.parser.JSONParser; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.EnableAutoConfiguration; import org.springframework.http.MediaType; import org.springframework.scheduling.annotation.Async; import org.springframework.web.bind.annotation.PostMapping; import org.springframework.web.bind.annotation.RequestBody; import org.springframework.web.bind.annotation.RequestHeader; import org.springframework.web.bind.annotation.ResponseBody; import org.springframework.web.bind.annotation.RestController; import com.box.sdk.BoxAPIConnection; import com.box.sdk.BoxCollaborator; import com.box.sdk.BoxCollaboration; import com.box.sdk.BoxConfig; import com.box.sdk.BoxDeveloperEditionAPIConnection; import com.box.sdk.BoxFile; import com.box.sdk.BoxFolder; import com.box.sdk.BoxGroup; import com.box.sdk.BoxGroupMembership; import com.box.sdk.BoxUser; @RestController @EnableAutoConfiguration public class Application extends slackConfig { private Reader fileReader; private BoxConfig boxConfig; private BoxAPIConnection boxAPI; @PostMapping("/event") @ResponseBody public void handleEvent(@RequestBody String data, @RequestHeader("Content-Type") String contentType, HttpServletResponse response) throws Exception { // HANDLE EVENTS } @Async public void processEvent(String data) throws Exception { // VERIFY EVENTS } public void process(JSONObject inputJSON) throws Exception { // PROCESS EVENTS } public void processUser(JSONObject userResponse, String event, String channel) throws Exception { // PROCESS USER ADD / REMOVE REQUEST } public void addGroupUser(String groupId, String userEmail) { // ADD USER TO BOX GROUP } public void removeGroupUser(String groupId, String userEmail) { // REMOVE USER FROM BOX GROUP } public void processContent(JSONObject userResponse, String channel, String fType, String fId) { // COLLABORATE CONTENT WITH GROUP } public void processSlackChannel(String channel, String groupId) throws Exception { // ADD ALL SLACK CHANNEL USERS TO GROUP } public JSONObject getSlackUser(String userId) throws Exception { // GET SLACK USER PROFILE } public String getGroupId(String groupName) { // GET AND CREATE BOX GROUP } public JSONObject sendGETRequest(String reqURL) throws Exception { StringBuffer response = new StringBuffer(); URL obj = new URL(reqURL); HttpURLConnection httpURLConnection = (HttpURLConnection) obj.openConnection(); httpURLConnection.setRequestMethod("GET"); int responseCode = httpURLConnection.getResponseCode(); if (responseCode == HttpURLConnection.HTTP_OK) { BufferedReader in = new BufferedReader(new InputStreamReader(httpURLConnection.getInputStream())); String inputLine; while ((inputLine = in .readLine()) != null) { response.append(inputLine); } in .close(); } else { System.err.println("GET request failed"); } Object dataObj = new JSONParser().parse(response.toString()); JSONObject outputJSON = (JSONObject) dataObj; return outputJSON; } public static void main(String[] args) { SpringApplication.run(Application.class, args); } } ``` このコードには、SlackとBox間の通信を処理するのに必要となる主要な関数がすべて含まれています。これらの関数について、上から順に説明します。 - `handleEvent`: 入ってくるSlackトラフィックをすべて取得し、HTTP 200レスポンスで応答して、イベントが受信されたことをSlackに通知します。スラッシュコマンドにより、ペイロードが`application/json`ではなく`application/x-www-form-urlencoded`として送信されるため、そのペイロードをJSONオブジェクトに変換して入力を標準化します。 - `processEvent`: イベントがSlackから送信されたかどうかを確認し、Boxクライアントをインスタンス化して、処理のために転送します。 - `process`: Slackイベントを解析し、Boxグループの処理 (ユーザーチャンネルイベント) またはグループへのBoxコンテンツの追加 (スラッシュコマンド) のいずれかに転送します。 - `processUser`: 適切な関数に転送することで、Boxグループのユーザーを追加または削除するためのUser Eventの要件を処理します。 - `addGroupUser`: Boxグループにユーザーを追加します。 - `removeGroupUser`: Boxグループからユーザーを削除します。 - `processContent`: BoxグループとBoxコンテンツのコラボレーションを行います。 - `processSlackChannel`: すべてのSlackチャンネルユーザーをBoxグループに追加します。 - `getSlackUser`: SlackユーザープロフィールをSlackユーザーIDから取得するユーティリティ関数。 - `getGroupId`: Boxグループ名からBoxグループIDを取得します (ユーティリティ関数)。 - `sendGETRequest`: HTTP GETリクエストを送信するユーティリティ関数。 # 前の手順が完了していません 最初に、手順1でお好みの言語/フレームワークを選択してください。 ## まとめ - 最小限のアプリケーションスキャフォールドを作成し、基本的な構成の詳細を指定しました。 - プロジェクトの依存関係をすべてインストールしました。 ローカルアプリケーションの設定が完了しました **Source:** [https://ja.developer.box.com/guides/collaborations/connect-slack-to-group-collabs/scaffold-application-code/](https://ja.developer.box.com/guides/collaborations/connect-slack-to-group-collabs/scaffold-application-code/) --- ### アプリケーションコードのスキャフォールディング **Type:** quick-start | **Category:** SSOとApp User | **Section:** Developer Guides アプリケーションコードのスキャフォールディング このガイドではまず、必要となるOktaとBox… # アプリケーションコードのスキャフォールディング このガイドではまず、必要となるOktaとBoxのアプリケーションを作成するにあたり、コードと構成データを格納するローカルアプリケーションを作成します。 言語/フレームワークの設定に応じて、空のアプリケーションを作成し、必要な依存関係のほか、すべての構成ファイルとプログラムファイルをインストールします。 まずは、以下からお好みの言語/フレームワークを選択してください。 # Node Express.jsフレームワークを使用します。 # Java Spring Bootフレームワークを使用します。 # Python Flaskフレームワークを使用します。 # .NET ASP.NET Coreフレームワークを使用します。 - アプリケーション用にローカルディレクトリを作成します。 - そのローカルディレクトリの中に`package.json`ファイルを作成し、お好みのエディタで開いたら、以下の内容をコピーして貼り付け、ファイルを保存して閉じます。 ``` { "name": "okta-box", "version": "1.0.0", "description": "Box / Okta sample integration", "main": "server.js", "scripts": { "test": "echo \"Error: no test specified\" && exit 1", "start": "node server.js" }, "author": "Box", "license": "ISC", "dependencies": { "@okta/oidc-middleware": "^4.0.0", "@okta/okta-sdk-nodejs": "^3.2.0", "box-node-sdk": "^1.31.0", "express-session": "^1.17.0" } } ``` - ターミナル/コンソールから`npm init`を実行して依存関係をインストールします。 - ローカルディレクトリに2つのファイル (`server.js`および`config.js`) を作成します。 - `config.js`を開いて、以下のデフォルト構成を保存します。 ``` const oktaClientId = exports.oktaClientId = ''; const oktaClientSecret = exports.oktaClientSecret = ''; const oktaOrgUrl = exports.oktaOrgUrl = ''; const oktaBaseUrl = exports.oktaBaseUrl = 'http://localhost:3000'; const oktaRedirect = exports.oktaRedirect = '/authorization-code/callback'; ``` - Eclipseで新しいプロジェクトを作成します。求められたら、Gradleプロジェクトを選択します。 - プロジェクトの一意の名前を入力します。このガイドでは`okta.sample`という名前を使用しています。 - `build.gradle`ファイルを開いて以下の依存関係を追加します。保存したら、Gradleプロジェクトを更新します。 ``` dependencies { implementation 'org.springframework.boot:spring-boot-starter-security' implementation 'org.springframework.boot:spring-boot-starter-web' implementation 'com.okta.spring:okta-spring-boot-starter:1.4.0' testImplementation('org.springframework.boot:spring-boot-starter-test') { exclude group: 'org.junit.vintage', module: 'junit-vintage-engine' } testImplementation 'org.springframework.security:spring-security-test' compile 'com.box:box-java-sdk:2.44.1' } ``` - `/src/main/resources/application.properties`ファイルを開いて以下のデフォルトを保存します。 ``` okta.oauth2.redirect-uri=/authorization-code/callback okta.oauth2.issuer= okta.oauth2.clientId= okta.oauth2.clientSecret= security.oauth2.sso.loginPath=/authorization-code/callback ``` - アプリケーション用にローカルディレクトリを作成します。 - ターミナル/コマンドプロンプトで`pip`コマンド (`pip install flask flask_oidc okta boxsdk config`) を使用して、必要な依存関係をインストールします。 - ローカルディレクトリに3つのファイル (`client_secrets.json`、`config.py`、`server.py`) を作成します。 - `config.py`を開いて以下の内容を保存します。これは、必要となるOktaアプリの構成情報の一部です。残りの情報については、次の手順で設定します。 ``` okta_client_secret = 'YOUR OKTA CLIENT SECRET' okta_org_url = 'YOUR OKTA ORG URL' okta_auth_token = 'YOUR OKTA APP TOKEN' okta_callback_route = '/oidc/callback' ``` - `client_secrets.json`を開いて以下の内容を保存します。これは、構成時にFlask OpenID Connect統合で使用される標準のオブジェクトです。残りの情報については、次の手順で設定します。 ``` { "web": { "client_id": "OKTA CLIENT ID", "client_secret": "OKTA CLIENT SECRET", "auth_uri": "OKTA AUTHORIZE URI", "token_uri": "OKTA TOKEN URI", "issuer": "OKTA APP DEFAULT", "userinfo_uri": "OKTA APP USER INFO URI", "redirect_uris": [ "http://127.0.0.1:5000/oidc/callbac" ] } } ``` - アプリケーション用にローカルディレクトリを作成します。 - コマンドプロンプト/ターミナルウィンドウを開いて、ローカルアプリケーションディレクトリに移動します。[.NET Core CLI](https://docs.microsoft.com/en-us/dotnet/core/tools/)を使用して、`dotnet new mvc`と入力してEnterキーを押します。これにより、ASP.NET Core MVC (Model-View-Controller) ウェブアプリに主要なスキャフォールディングが作成されます。または、[Visual Studioから直接](https://docs.microsoft.com/en-us/visualstudio/ide/quickstart-aspnet-core)このアプリケーションを作成することもできます。 - コマンドプロンプト/ターミナルウィンドウで、ローカルアプリケーションディレクトリに`dotnet add package Okta.AspNetCore`と入力してOkta ASP.NET Coreの依存関係を追加し、`dotnet add package Box.V2.Core`と入力してBoxの依存関係を追加します。 - Visual Studioまたはお好みのエディタに新しいアプリケーションを読み込みます。 - プロジェクトのルート内で`Startup.cs`を開きます。 - ファイルの先頭に以下のパッケージ宣言を追加します。 ``` using Microsoft.AspNetCore.Authentication.Cookies; using Okta.AspNetCore; ``` - `ConfigureServices`メソッドの内容を以下の内容に置き換えます。具体的なOktaアプリケーションの値は次の手順で設定します。 ``` services.AddControllersWithViews(); services.AddAuthentication(options => { options.DefaultAuthenticateScheme = CookieAuthenticationDefaults.AuthenticationScheme; options.DefaultSignInScheme = CookieAuthenticationDefaults.AuthenticationScheme; options.DefaultChallengeScheme = OktaDefaults.MvcAuthenticationScheme; }) .AddCookie() .AddOktaMvc(new OktaMvcOptions { // Replace these values with your Okta configuration OktaDomain = "", ClientId = "", ClientSecret = "" }); ``` 次の行を`Configure`メソッドの**先頭**に追加します。 ``` app.UseAuthentication(); ``` # 前の手順が完了していません 開始するには、お好みの言語/フレームワークを選択してください。 ## まとめ - 新しいローカルアプリケーション、ファイル、基本的な構成の詳細を作成しました。 - プロジェクトの依存関係をすべてインストールしました。 ローカルアプリケーションの設定が完了しました **Source:** [https://ja.developer.box.com/guides/sso-identities-and-app-users/connect-okta-to-app-users/scaffold-application-code/](https://ja.developer.box.com/guides/sso-identities-and-app-users/connect-okta-to-app-users/scaffold-application-code/) --- ### アプリケーションの実行 **Type:** quick-start | **Category:** SSOとApp User | **Section:** Developer Guides アプリケーションの実行 サンプルの構成コンポーネントがすべて設定できたら、プログラムを実行してすべてが正常に動作していることを確認します。 ターミナル/コマンドプロンプトで、ローカルアプリケーションディレクトリにnode server.jsと入力してEnter… # アプリケーションの実行 サンプルの構成コンポーネントがすべて設定できたら、プログラムを実行してすべてが正常に動作していることを確認します。 ターミナル/コマンドプロンプトで、ローカルアプリケーションディレクトリに`node server.js`と入力してEnterキーを押します。サーバーが起動し、`Server started: Listening on port 3000`と出力されます。 ブラウザで`http://localhost:3000/`にアクセスします。ユーザーのサインインフローを試すのは今回が初めてなので、Oktaログインが表示されます。 [手順2](g://sso-identities-and-app-users/connect-okta-to-app-users/configure-okta)の最後のセクションで作成したOktaユーザーの資格情報を使用してサインインします。 サインインしたら、`New user created: {{USERNAME}}`というメッセージがブラウザに出力されます。 その後このユーザーでログインを試みると、ブラウザに`Hello {{USERNAME}}`と出力されるようになります。 Eclipse (またはお好みのエディタ) で、クリックしてアプリケーションを実行します。Spring Bootアプリケーションがポート8080で実行されていることを示すコンソール出力が表示されます。 ブラウザで`http://localhost:8080/`にアクセスします。ユーザーのサインインフローを試すのは今回が初めてなので、Oktaログインが表示されます。 [手順2](g://sso-identities-and-app-users/connect-okta-to-app-users/configure-okta)の最後のセクションで作成したOktaユーザーの資格情報を使用してサインインします。 サインインしたら、`New User Created: {{USERNAME}}`というメッセージがブラウザに出力されます。 その後このユーザーでログインを試みると、ブラウザに`Hello {{USERNAME}}`と出力されるようになります。 ターミナル/コマンドプロンプトで、ローカルアプリケーションディレクトリに`env FLASK_APP=server.py flask run`と入力してEnterキーを押します。サーバーが起動し、`Running on http://127.0.0.1:5000/`と出力されます。 ブラウザで`http://127.0.0.1:5000/`にアクセスします。ユーザーのサインインフローを試すのは今回が初めてなので、Oktaログインが表示されます。 [手順2](g://sso-identities-and-app-users/connect-okta-to-app-users/configure-okta)の最後のセクションで作成したOktaユーザーの資格情報を使用してサインインします。 サインインしたら、`New user created: {{USERNAME}}`というメッセージがブラウザに出力されます。 その後このユーザーでログインを試みると、ブラウザに`Hello {{USERNAME}}`と出力されるようになります。 Visual Studio Code (またはお好みのエディタ) で、メニューから [`Run`] -> [`Start Debugging`] をクリックします。アプリケーションが読み込まれるとデバッグコンソール出力が表示され、その後、ブラウザウィンドウでは、`https://localhost:5001/`でアプリケーションが表示されます。 アプリケーションをテストするのは今回が初めてなので、サインインリンクが表示されます。クリックすると、Oktaログインが自動的に読み込まれます。 [手順2](g://sso-identities-and-app-users/connect-okta-to-app-users/configure-okta)の最後のセクションで作成したOktaユーザーの資格情報を使用してサインインします。 サインインしたら、デバッグコンソールの`New user created: {{USERNAME}}`というメッセージがブラウザに出力されます。 その後このユーザーでログインを試みると、ブラウザに`Current user name: {{USERNAME}}`と出力されるようになります。 # 前の手順が完了していません 最初に、手順1でお好みの言語/フレームワークを選択してください。 ## まとめ このクイックスタートガイドが完了しました。ここまで、以下の手順を実行しました。 1. [ウェブアプリケーションのスキャフォールディングを作成しました](g://sso-identities-and-app-users/connect-okta-to-app-users/scaffold-application-code)。 2. [Oktaアプリケーションを設定および構成](g://sso-identities-and-app-users/connect-okta-to-app-users/configure-okta)して、ウェブアプリへのログインに使用できる1人目のユーザーを作成しました。 3. [Boxアプリケーションを設定および構成](g://sso-identities-and-app-users/connect-okta-to-app-users/configure-box)して、ウェブアプリからBoxに接続できるようにしました。 4. [ウェブアプリケーションのログインフローを作成](g://sso-identities-and-app-users/connect-okta-to-app-users/logging-into-app)して、Oktaユーザーがログインできるようにしました。 5. Oktaユーザーが初めてウェブアプリケーションにログインするときに、[既存のBoxユーザーを検索し、必要に応じてBoxユーザーを作成するためのチェックを追加](g://sso-identities-and-app-users/connect-okta-to-app-users/find-or-create-box-users)しました。 6. [最後にアプリケーションを実行](g://sso-identities-and-app-users/connect-okta-to-app-users/run-the-app)して、フロー全体の動作を確認しました。 ## 次の手順 ユーザーの作成とアクセスのプロセスに関連したより高度な機能について詳しく知りたい方には、以下のリソースをお勧めします。 - ユーザーフォルダのアーキテクチャの詳細な設定に関する、[ユーザープロビジョニング](g://users/provision)のベストプラクティス。 - 非アクティブなユーザーの削除と別のアカウントへのユーザーコンテンツの転送に関する、[ユーザーのプロビジョニング解除](g://users/deprovision)のベストプラクティス。 - 事前チェックや大容量ファイルの (分割) アップロードなど、Boxへの[コンテンツのアップロード](g://uploads)。 **Source:** [https://ja.developer.box.com/guides/sso-identities-and-app-users/connect-okta-to-app-users/run-the-app/](https://ja.developer.box.com/guides/sso-identities-and-app-users/connect-okta-to-app-users/run-the-app/) --- ### アプリケーションの種類 **Type:** guide | **Category:** アプリケーション | **Section:** Developer Guides アプリケーションの種類 以下に、作成できるさまざまなBoxアプリケーションの種類の概要を示します。 アプリケーションの種類 認証方法 Platformアプリ OAuth 2.0、JWT… # アプリケーションの種類 以下に、作成できるさまざまなBoxアプリケーションの種類の概要を示します。 | アプリケーションの種類 | 認証方法 | | --- | --- | | Platformアプリ | OAuth 2.0、JWT、またはクライアント資格情報許可 | | アクセス制限付きアプリ | アプリトークン | | カスタムスキル | 選択不要 | アプリケーションの種類の選択方法を確認する **Source:** [https://ja.developer.box.com/guides/applications/app-types/](https://ja.developer.box.com/guides/applications/app-types/) --- ### アプリケーションフロー **Type:** guide | **Category:** セキュリティ | **Section:** Developer Guides アプリケーションフロー 一般的に、アプリケーションでは以下のようにサービス利用規約を使用します。 ユーザーとして認証されたアプリケーションが、関連するサービス利用規約にユーザーが同意している必要があるBox内の項目にアクセスしようとすると、TERMS_OF_SERVICE… # アプリケーションフロー 一般的に、アプリケーションでは以下のようにサービス利用規約を使用します。 ユーザーとして認証されたアプリケーションが、関連するサービス利用規約にユーザーが同意している必要があるBox内の項目にアクセスしようとすると、`TERMS_OF_SERVICE_REQUIRED`エラーが返されます。 ``` { "type": "error", "status": 400, "code": "terms_of_service_required", "context_info": { "tos_id": 261346614, "tos_user_status_id": 4562456 }, "help_url": "https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/", "message": "User must accept custom terms of service before action can be taken", "request_id": "ADF7722DD" } ``` アプリケーションは、[`GET /terms_of_services/:id`](e://get_terms_of_services_id)を呼び出してサービス利用規約の情報をリクエストします。 ``` { "id": 261346614, "type": "terms_of_service", "status": "enabled", "enterprise": { "id": 11446498, "type": "enterprise", "name": "Acme Inc." }, "tos_type": "managed", "text": "By using this service, you agree to ...", "created_at": "2012-12-12T10:53:43-08:00", "modified_at": "2012-12-12T10:53:43-08:00" } ``` その後、アプリケーションはサービス利用規約のテキストをユーザーに表示できます。 ユーザーが利用規約を同意または拒否すると、最初のエラーによってレスポンスで`tos_user_status_id`が返されたかどうかに応じて、[`PUT /terms_of_service_user_statuses/:id`](e://put_terms_of_service_user_statuses_id)または[`POST /terms_of_service_user_statuses`](e://post_terms_of_service_user_statuses)が呼び出されます。 **Source:** [https://ja.developer.box.com/guides/security/terms-of-service/flow/](https://ja.developer.box.com/guides/security/terms-of-service/flow/) --- ### アプリトークンの循環 **Type:** guide | **Category:** 認証 | **Section:** Developer Guides アプリトークンの循環 アプリケーションのアプリトークンを… # アプリトークンの循環 アプリケーションのアプリトークンを1つずつ更新することで、アプリケーションではトークンの循環が可能となり、競合が発生することはありません。 ## トークンを循環させる理由 一定の間隔でアプリトークンを循環させる理由はいくつかあります。 1. 有効期限が自動的に切れるよう構成されているトークンを交換するため 2. セキュリティ侵害を受けたトークンによる影響を抑えるため どちらの場合も、Boxでは、いつでも2つのアクティブなアプリトークンがサポートされているため、古いトークンから新しいトークンへのシームレスな循環が可能です。 ## 循環の手順 以下の手順では、すでにプライマリアプリトークンとセカンダリアプリトークンを作成済みで、いずれか一方を置き換える準備が整っていることを前提としています。 以下の手順に従うと、2つの新しいトークンを使用して、問題なくアプリケーションを構成できます。 1. アプリケーションでプライマリアプリトークンを使用していることを前提に、[開発者コンソール](https://app.box.com/developers/console)アプリケーションに移動します。アプリケーションの [構成] セクションに移動し、セカンダリアプリトークンの [キーを生成] ボタンを選択します。 2. セカンダリアプリトークンを使用してアプリケーションを更新します。次の手順に進む前に、この新しいトークンでアプリケーションが完全に構成されていることを確認します。 3. プライマリアプリトークンが使用されていないことを確信したら、[開発者コンソール](https://app.box.com/developers/console)に移動して、プライマリアプリトークンの [取り消し] ボタンをクリックします。 セカンダリアプリトークンからプライマリアプリトークンにロールバックするには、トークンが交換された状態で同じ手順を繰り返します。 **Source:** [https://ja.developer.box.com/guides/authentication/app-token/rollover/](https://ja.developer.box.com/guides/authentication/app-token/rollover/) --- ### アプリトークン認証 **Type:** guide | **Category:** 認証 | **Section:** Developer Guides アプリトークン認証 アプリトークンを使用するサーバー側認証は、Box APIに対する代替の認証方法で、アプリケーションのサービスアカウントに制限されている、有効期間の長い固定のアクセストークンを使用します。アプリトークン認証は、Box View… # アプリトークン認証 アプリトークンを使用するサーバー側認証は、Box APIに対する代替の認証方法で、アプリケーションの[サービスアカウント](page://platform/user-types/#service-account)に制限されている、有効期間の長い固定のアクセストークンを使用します。アプリトークン認証は、[Box View](g://embed/box-view)を利用するアプリケーションによる使用を目的としています。 ## アプリトークンの制限 サーバー側アプリトークンは、アプリケーションに、それ自体のアカウントのデータに対する読み取りと書き込みのアクセス権限だけがある認証方法です。この認証方法を使用すると、アプリケーションはそのアプリケーションに属しているサービスアカウントとして自動的に認証されるため、ユーザーを承認する必要がありません。 ## アプリトークンを使用する場合 アプリトークンを使用するサーバー側認証は、以下に当てはまるアプリに最適な認証方法です。 - [Box View](g://embed/box-view)を介してBoxのプレビューサービスを利用する - ユーザーモデルがない環境、またはBoxアカウントを持たないユーザーがいる環境で使用する - 独自のIDシステムを使用する - ユーザーにBoxを使用していることを認識させたくない - ユーザーのアカウントではなく、アプリケーションのサービスアカウントにデータを保存する **Source:** [https://ja.developer.box.com/guides/authentication/app-token/](https://ja.developer.box.com/guides/authentication/app-token/) --- ### アプリトークン認証を使用した設定 **Type:** guide | **Category:** 認証 | **Section:** Developer Guides アプリトークン認証を使用した設定 アクセス制限付きアプリは、認証にサーバー側のアプリトークンを使用するよう設定できます。 アプリトークン認証のしくみを確認する 前提条件 サーバー側認証を使用してPlatformアプリを設定するには、Box Enterprise… # アプリトークン認証を使用した設定 アクセス制限付きアプリは、認証にサーバー側の[アプリトークン](g://authentication/app-token)を使用するよう設定できます。 アプリトークン認証のしくみを確認する ## 前提条件 サーバー側認証を使用してPlatformアプリを設定するには、Box Enterpriseアカウントから[開発者コンソール](https://app.box.com/developers/console)にアクセスできることを確認する必要があります。または、[Developerアカウント](https://account.box.com/signup/n/developer)にサインアップすることもできます。 ## アプリの作成手順 ### 1. 開発者コンソールにログインする Boxにログインし、[開発者コンソール](https://app.box.com/developers/console)に移動して、[**Platformアプリの作成**] を選択します。 ### 2. Platformアプリを作成する アプリケーションの種類のリストから [**アクセス制限付きアプリ**] を選択します。次の手順を促すウィンドウが表示されます。 ### 3. アプリ名を選択する 最後に、アプリケーションの一意の名前を選択し、[**アプリの作成**] をクリックします。 ## アプリ承認 キーペアがアプリケーションに正常に追加されたら、Box Enterprise管理者はBox管理コンソール内でこのアプリケーションを承認する必要があります。 [開発者コンソール](https://app.box.com/developers/console)内でアプリケーションの [**一般設定**] タブに移動し、[**アプリ承認**] セクションまで下にスクロールします。 [**確認して送信**] をクリックして、承認を得るためにBox Enterprise管理者にメールを送信します。このプロセスの詳細については、[承認ガイド](g://authorization)を参照してください。 ## 基本的な構成 アプリケーションを使用するには、事前にいくつかの基本的な追加構成が必要になる場合があります。 ### プライマリおよびセカンダリアプリトークン アクセス制限付きアプリでの認証は、あらかじめ構成された[アプリトークン](g://authentication/app-token)を使用して行われます。アプリトークンを構成するには、[開発者コンソール](https://app.box.com/developers/console)内でアプリケーションの [**構成**] タブに移動します。 [**プライマリアクセストークン**] セクションまで下にスクロールし、[**キーを生成**] ボタンをクリックします。 アプリトークンは、自動的に期限切れになるよう構成することも、有効期限なしで構成することもできます。作成後は、このキーを使用して[APIコール](g://api-calls)を実行できます。 # アプリ承認 アプリトークンは、Box管理コンソール内でアプリケーションの承認が成功するまで生成できません。 ### CORSドメイン アプリケーションがJavaScriptでフロントエンドのブラウザコードからAPIコールを実行する場合は、[クロスオリジンリソース共有](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing) (CORS) のために、これらの呼び出しの実行元となるドメインを許可リストに追加する必要があります。すべてのリクエストがサーバー側のコードから発行される場合は、このセクションをスキップできます。 許可リストにすべてのURIを追加するには、[開発者コンソール](https://app.box.com/developers/console)の [**構成**] タブの下部にある [**CORSドメイン**] セクションに移動します。 **Source:** [https://ja.developer.box.com/guides/authentication/app-token/app-token-setup/](https://ja.developer.box.com/guides/authentication/app-token/app-token-setup/) --- ### アプリの公開 **Type:** guide | **Category:** はじめに | **Section:** Developer Guides アプリの公開 Platformアプリの構成とテストが完了したら、Box統合でアプリを公開できます。公開すると、お客様がアプリを見つけて、自分のBoxアカウントに追加できるようになります。 公開オプションが組み込まれるのは、OAuth 2.… # アプリの公開 Platformアプリの構成とテストが完了したら、[Box統合](https://cloud.app.box.com/integrations)でアプリを公開できます。公開すると、お客様がアプリを見つけて、自分のBoxアカウントに追加できるようになります。 公開オプションが組み込まれるのは、OAuth 2.0認証を使用するアプリのみです。統合に別の種類の認証を使用する場合も、[**統合**] でマーケティングリストとして機能し、お客様を開発元のウェブサイトにリダイレクトするOAuth 2.0のPlatformアプリを作成して公開できます。 Platformアプリを公開するには、以下の手順に従います。 **開発者コンソール**を開きます。 公開するPlatformアプリを選択します。 [**公開**] タブに移動します。 送信チェックリストをひととおり読み、アプリがすべての要件を満たしているかどうかを確認するチェックボックスをオンにします。 次の手順として、アプリのマーケティングセクションで、アプリに関する以下の情報を追加する必要があります。 - [**一般情報**] - 統合で見つけやすくするために、アプリに適したカテゴリとプラットフォームを選択します。 [**説明**] - お客様の役に立つと思われる、アプリに関するすべての情報を必ず含めます。 - [**簡単な説明**] は、アプリのロゴの横にアプリ名と一緒に表示されます。 - [**詳しい説明**] は、ユーザーがアプリを選択してその詳細を表示すると表示される内容です。詳しい説明へのクリック可能なリンクを追加できます。 1. [**スクリーンショット**] および [**アイコン**] - ユーザーがアプリの外観やBoxとの統合方法を確認できるようにスクリーンショットを指定します。アイコンは、統合のリストでアプリを表すために必要になります。 2. [**サポートリソース**] - ユーザーがアプリを操作するのに役立つリンクと補足情報のリスト。 アプリを送信する前に、アプリをプレビューして、必要な情報がすべて含まれているかどうかを確認します。 承認を得るためにアプリを送信します。Boxがアプリをレビューし、[**統合**] で公開します。 ご不明な点や問題がある場合は、**パートナー**チーム ([`integrate@box.com`](mailto:integrate@box.com)) まで英語でお問い合わせください。 **Source:** [https://ja.developer.box.com/guides/getting-started/publish-app/](https://ja.developer.box.com/guides/getting-started/publish-app/) --- ### アプリの種類の選択 **Type:** guide | **Category:** アプリケーション | **Section:** Developer Guides アプリの種類の選択 開発者コンソールで新しいBox… # アプリの種類の選択 [開発者コンソール](https://app.box.com/developers/console)で新しいBoxアプリケーションを作成する際は、まず、次のアプリケーションの種類のいずれかを選択する必要があります。選択するアプリケーションの種類は、プロジェクトのユースケースによって決まり、アプリケーションの構成時に使用できる認証方法のみに影響します。この選択を後で変更することはできません。 ## Platformアプリ | | | | --- | --- | | 認証方法 | OAuth 2.0、JWT、またはクライアント資格情報認証 | | 注目すべき機能 | Webhook、統合、ウェブアプリ統合 | Platformアプリはほとんどのユースケースに対応しており、最も柔軟なオプションです。このアプリケーションの種類では、Boxの150を超えるエンドポイントを操作できます。たとえば、メタデータのダウンロード/アップロード、検索、適用などが可能です。 Platformアプリの詳細を確認する ## アクセス制限付きアプリ | | | | --- | --- | | 認証方法 | アプリトークン | | 注目すべき機能 | 制限されたAPIアクセス | アクセス制限付きアプリは、[Box View](g://embed/box-view)を利用したり、別のアプリケーション内でBoxコンテンツをプレビューしたりする場合に最適です。この種類のアプリケーションで操作できるエンドポイントの数は限られています。 アクセス制限付きアプリの詳細を確認する ## カスタムスキル | | | | --- | --- | | 認証方法 | スキルイベントにおけるアクセストークン | | 注目すべき機能 | 制限されたAPIアクセス | カスタムスキル (Box Skill) とは、Boxにアップロードされたファイルに対してカスタマイズした処理を実行する一種のアプリケーションです。スキルは、サードパーティの機械学習サービスを使用して、Boxにアップロードされたファイルから情報を自動的に抽出できるようにすることを目的としています。 カスタムスキルの詳細を確認する **Source:** [https://ja.developer.box.com/guides/applications/app-types/select/](https://ja.developer.box.com/guides/applications/app-types/select/) --- ### イベント **Type:** guide | **Category:** イベント | **Section:** Developer Guides イベント アプリケーションはイベントフィードを使用して、Enterprise内の任意のユーザー (複数可) またはサービスが実行する操作をすべて登録できます。 User EventとEnterprise Event GET /events APIを使用すると、stream… # イベント アプリケーションはイベントフィードを使用して、Enterprise内の任意のユーザー (複数可) またはサービスが実行する操作をすべて登録できます。 ## User EventとEnterprise Event [`GET /events`](e://get_events) APIを使用すると、`stream_type`に応じて、Enterprise全体または特定のユーザーのライブイベントにサブスクライブするか、Enterprise全体のイベントの履歴を照会することができます。 ### User Event User Eventは、現在認証されているユーザーに関連する、低レイテンシのイベントストリームを提供します。このイベントストリームにより、[Box Drive](https://www.box.com/drive)は常に最新の状態で維持されますが、このイベントストリームは開発者向けにも提供されています。 このフィードでは、すべての結果を迅速に返すことを重視しています。つまり、Boxでは、イベントが複数回または時系列に関係なく返される可能性があります。重複するイベントは、イベントIDによって識別できます。 Enterprise Event Streamとは異なり、User Event Streamは、特定のイベントのフィルタをサポートしません。User Eventの3つのstream_typeで返されるUser Eventデータセットのサブセットは、目的に応じて若干異なります。 | ストリームタイプ | | | --- | --- | | all | ユーザーに関するすべてのイベントを返します (デフォルト)。 | | changes | ファイルの更新やコラボレーションなど、ファイルツリーを変更する可能性があるイベントを返します | | sync | 変更に似ていますが、同期対象フォルダにのみ適用されます。 | ### Enterprise Event Enterprise Eventは、企業のBoxインスタンスにあるすべてのユーザーとコンテンツのイベントフィードを提供します。`stream_type`に応じて、アプリケーションは、ライブイベントを登録するかイベントの履歴を照会することができます。これらのストリームタイプへのアクセスは、**新規レポートの実行および既存レポートへのアクセスを行う**ための管理者権限を持つユーザーに制限されます。 User Event Streamとは異なり、Enterprise Event Streamは、イベントタイプに基づくフィルタをサポートしますが、Long pollingをサポートしません。2つのストリームタイプでのデータセットはまったく同じです。イベントIDを使用すると、2つのストリームタイプでのイベントの重複を排除できます。 | ストリームタイプ | | | --- | --- | | admin_logs | イベントの履歴を最大1年分照会できるようにします | | admin_logs_streaming | ほぼリアルタイムでライブイベントにサブスクライブできるようにします | #### ライブで監視 Box内で生成された最近のイベントをEnterprise全体で監視するには、`stream_type`を`admin_logs_streaming`に設定します。これは、Enterprise Event Stream APIとも呼ばれます。 このフィードでは、時系列の正確さよりもレイテンシの低さを重視しています。つまり、Boxでは、イベントが複数回、時系列に関係なく返される場合があります。イベントは、Boxで処理されるとほぼリアルタイムでAPIを介して返されます。少しの遅延やバッファが発生すると、新しいイベントがカーソル位置の後に書き込まれなくなります。この`stream_type`で取得できるイベントは、2週間分だけです。 #### 履歴の照会 Enterprise全体のイベント履歴を最大1年分照会するには、`stream_type`を`admin_logs`に設定します。これは、 Enterprise Event History APIとも呼ばれます。 このフィードでは、レイテンシよりも完全性を重視しています。つまり、Boxでは、管理イベントが重複することなく時系列で配信されますが、レイテンシはユーザーまたは`admin_logs_streaming`のフィードよりも高くなります。イベントは、フィルタをかけている期間より後に到着する可能性があるため、ほぼリアルタイムで使用すると見逃される場合があります。 **Source:** [https://ja.developer.box.com/guides/events/](https://ja.developer.box.com/guides/events/) --- ### イベントストリームのパラメータ **Type:** guide | **Category:** イベント | **Section:** Developer Guides イベントストリームのパラメータ GET /eventsエンドポイントには、いくつかのパラメータを使用できます。stream_typeおよびstream_positionについては、このセクションのガイドで詳しく説明します。 # イベントストリームのパラメータ [`GET /events`](e://get_events)エンドポイントには、いくつかのパラメータを使用できます。`stream_type`および`stream_position`については、このセクションのガイドで詳しく説明します。 **Source:** [https://ja.developer.box.com/guides/events/parameters/](https://ja.developer.box.com/guides/events/parameters/) --- ### イベントソース **Type:** guide | **Category:** イベント | **Section:** Developer Guides イベントソース ユーザーまたは項目によってイベントがトリガーされると、GET /events… # イベントソース ユーザーまたは項目によってイベントがトリガーされると、[`GET /events`](e://get_events)エンドポイントのレスポンスにはイベントソースオブジェクトが含まれます。 ## ユーザーソースオブジェクト ユーザーがイベントをトリガーした場合、ソースオブジェクトは[ユーザーリソース](e://resources/user)の標準レプリゼンテーションになります。 ``` { "source": { "id": 11446498, "type": "user", "address": "900 Jefferson Ave, Redwood City, CA 94063", "avatar_url": "https://www.box.com/api/avatar/large/181216415", "created_at": "2012-12-12T10:53:43-08:00", "job_title": "CEO", "language": "en", "login": "ceo@example.com", "max_upload_size": 2147483648, "modified_at": "2012-12-12T10:53:43-08:00", "name": "Aaron Levie", "notification_email": { "email": "notifications@example.com", "is_confirmed": true }, "phone": 6509241374, "space_amount": 11345156112, "space_used": 1237009912, "status": "active", "timezone": "Africa/Bujumbura" } } ``` ## 項目ソースオブジェクト 項目がイベントをトリガーした場合、ソースオブジェクトは[イベントソースリソース](e://resources/event-source)になります。 以下の例には`classification`オブジェクトが含まれています。これは、項目に分類が設定されていない場合は表示されません。また、一部のイベントタイプでは表示されません。 ``` { "source": { "item_type": "file", "item_id": "8903212345", "item_name": "example.docx", "parent": { "type": "folder", "name": "All Files", "id": "0" }, "owned_by": { "type": "user", "id": "11446498", "name": "Aaron Levie", "login": "notifications@example.com" }, "classification": { "name": "Top Secret" } } } ``` **Source:** [https://ja.developer.box.com/guides/events/event-triggers/event-source/](https://ja.developer.box.com/guides/events/event-triggers/event-source/) --- ### イベントトリガー **Type:** guide | **Category:** イベント | **Section:** Developer Guides イベントトリガー イベントは、ユーザー、項目、またはその他のリソースによってコミットされたアクションに基づいてイベントストリームに表示されます。GET /eventsエンドポイントのレスポンスは、イベントをトリガーしたイベントによって変わります。 # イベントトリガー イベントは、ユーザー、項目、またはその他のリソースによってコミットされたアクションに基づいてイベントストリームに表示されます。[`GET /events`](e://get_events)エンドポイントのレスポンスは、イベントをトリガーしたイベントによって変わります。 **Source:** [https://ja.developer.box.com/guides/events/event-triggers/](https://ja.developer.box.com/guides/events/event-triggers/) --- ### インストール **Type:** guide | **Category:** Boxの埋め込み | **Section:** Developer Guides インストール UI Elementを使用するには、Box CDNから直接JavaScriptライブラリをダウンロードするか、NPMパッケージをインストールします。すべてのUI Elementは、正しくレンダリングするために対応するCSSスタイルシートが必要です。 前提条件 Box… # インストール UI Elementを使用するには、Box CDNから直接JavaScriptライブラリをダウンロードするか、[NPMパッケージ](https://www.npmjs.com/package/box-ui-elements)をインストールします。すべてのUI Elementは、正しくレンダリングするために対応するCSSスタイルシートが必要です。 ## 前提条件 Box UI Elementsを使用するには、NodeおよびReactの以下のバージョンが必要です。 - Nodeのバージョン: `>=18.18.2 <20.11.0` - Reactのバージョン: `>=18.0.0` UI Elementsの利用可能なバージョンは、[手動によるインストール](#manual-installation)セクションに記載されています。 ### React 18への移行 React 17以下をベースとした既存のプロジェクトの場合は、[React 18の移行ガイド](https://react.dev/blog/2022/03/08/react-18-upgrade-guide)を参照してください。 プロジェクトでReactをアップグレードしたら、`npm`または`yarn`で`box-ui-elements`パッケージを更新します。 ``` npm install box-ui-elements --legacy-peer-deps yarn add box-ui-elements ``` これにより、`package.json`ファイルのバージョンが更新されます。 ``` "box-ui-elements": "^23.0.0" ``` コードでは、Box UI Elementsに関連した追加の変更は必要ありません。 詳細については、UI ElementsのためのReact 18へのアップグレードに関するブログ記事を参照してください。 ## NPMのインストール Reactベースのアプリを構築し、構築時にアプリに直接コンポーネントをインポートする場合は、この方法を使用します。 **注** ライブラリの依存関係が原因で、`npm`を使用してUI Elementsをインストールする場合は`--legacy-peer-deps`フラグが必要です。 ``` npm install box-ui-elements --legacy-peer-deps yarn add box-ui-elements ``` NPMウェブサイトの詳細を確認する ## コンテンツプレビュー 特定のバージョンのプレビューライブラリが必要な場合は、コンテンツプレビューSDKを使用します。それ以外の場合は、コンテンツプレビューUI Elementラッパーを使用します。 ## 手動によるインストール すべてのUI Elementは、Box CDNから直接入手することもできます。 | Element | バージョン | ファイル | | --- | --- | --- | | コンテンツエクスプローラ | 23.0.0 | CSS https://cdn01.boxcdn.net/platform/elements/23.0.0/en-US/explorer.css | | | | Reactを使用するJS https://cdn01.boxcdn.net/platform/elements/23.0.0/en-US/explorer.js | | | | Reactを使用しないJS https://cdn01.boxcdn.net/platform/elements/23.0.0/en-US/explorer.no.react.js | | Content Open With | 23.0.0 | CSS https://cdn01.boxcdn.net/platform/elements/23.0.0/en-US/openwith.css | | | | Reactを使用するJS https://cdn01.boxcdn.net/platform/elements/23.0.0/en-US/openwith.js | | | | Reactを使用しないJS https://cdn01.boxcdn.net/platform/elements/23.0.0/en-US/openwith.no.react.js | | Content Picker | 23.0.0 | CSS https://cdn01.boxcdn.net/platform/elements/23.0.0/en-US/picker.css | | | | Reactを使用するJS https://cdn01.boxcdn.net/platform/elements/23.0.0/en-US/picker.js | | | | Reactを使用しないJS https://cdn01.boxcdn.net/platform/elements/23.0.0/en-US/picker.no.react.js | | Content Sidebar | 23.0.0 | CSS https://cdn01.boxcdn.net/platform/elements/23.0.0/en-US/sidebar.css | | | | Reactを使用するJS https://cdn01.boxcdn.net/platform/elements/23.0.0/en-US/sidebar.js | | | | Reactを使用しないJS https://cdn01.boxcdn.net/platform/elements/23.0.0/en-US/sidebar.no.react.js | | コンテンツアップローダー | 23.0.0 | CSS https://cdn01.boxcdn.net/platform/elements/23.0.0/en-US/uploader.css | | | | Reactを使用するJS https://cdn01.boxcdn.net/platform/elements/23.0.0/en-US/uploader.js | | | | Reactを使用しないJS https://cdn01.boxcdn.net/platform/elements/23.0.0/en-US/uploader.no.react.js | | コンテンツプレビューUI Element | 23.0.0 | CSS https://cdn01.boxcdn.net/platform/elements/23.0.0/en-US/preview.css | | | 23.0.0 | JS https://cdn01.boxcdn.net/platform/elements/23.0.0/en-US/preview.js | | コンテンツプレビューSDK | 2.106.0 | CSS https://cdn01.boxcdn.net/platform/preview/2.106.0/en-US/preview.css | | | | JS https://cdn01.boxcdn.net/platform/preview/2.106.0/en-US/preview.js | 上記のリンクを使用して要素のコードをアプリケーションのコードにダウンロードするか、CDNからページに直接埋め込みます。 ``` <!DOCTYPE html> <html lang="en-US"> <head> <!-- Latest version of the explorer css for your locale --> <link rel="stylesheet" href="https://cdn01.boxcdn.net/platform/elements/{VERSION}/en-US/explorer.css" /> </head> <body> <!-- Latest version of the explorer js for your locale --> <script src="https://cdn01.boxcdn.net/platform/elements/{VERSION}/en-US/explorer.js"></script> ... </body> </html> ``` Boxプレビューでは、このサンプルは若干異なって見えます。 ``` <!DOCTYPE html> <html lang="en-US"> <head> <meta charset="utf-8" /> <title>Box Content Preview Demo</title> <!-- Latest version of Box Content Preview for en-US locale --> <script src="https://cdn01.boxcdn.net/platform/preview/{VERSION}/en-US/preview.js"></script> <link rel="stylesheet" href="https://cdn01.boxcdn.net/platform/preview/{VERSION}/en-US/preview.css" /> </head> <body> <div class="preview-container" style="height:400px; width:100%;"></div> <script> var preview = new Box.Preview(); preview.show("93392244621", "EqFyi1Yq1tD9mxY8F38sxDfp73pFd7FP", { container: ".preview-container", showDownload: true, }); </script> </body> </html> ``` ### バージョン ほとんどのUI Elementには、2つの異なるバージョンがあります。 バンドルにReactとReactDOMなどが含まれている、標準的な`*.js`ファイル (`explore.js`など)。 - これは、Reactベースのアプリを構築していない場合や、アプリの構築プロセスの一環としてコンポーネントを含める必要がない場合に使用します。 - ReactライブラリとReactDOMライブラリが含まれています。 - このアセットのファイルサイズは以下のアセットよりも大きくなります。 ReactとReactDOMがバンドルされない小規模な`*.no.react.js`ファイル (`explore.no.react.js`など)。 - これは、ReactライブラリとReactDOMライブラリが両方ともすでにアプリケーションで読み込まれている場合に使用します。 - これらのライブラリでは、ReactおよびReactDOMが`>= 16.6`かつ`< 18`であることを想定しています。 2つの`js`ファイルのうち1つのみと追加の`css`ファイルをプロジェクトに追加する必要があります。 ### サポートされているロケール 上記のアセットURLでは`en-US`が使用されています。別のロケールを使用する場合は、上記のURLに含まれる`en-US`を以下のいずれかに置き換えてください。 `en-AU`, `en-CA`, `en-GB`, `da-DK`, `de-DE`, `es-ES`, `fi-FI`, `fr-CA`, `fr-FR`, `it-IT`, `ja-JP,`, `ko-KR`, `nb-NO`, `nl-NL`, `pl-PL`, `pt-BR`, `ru-RU`, `sv-SE`, `tr-TR`, `zh-CN`, `zh-TW` ## コンテンツプレビューのセルフホスティング 所有するサーバーからBox Content Previewライブラリを提供するには、以下の手順に従います。 ### 1. リリースをダウンロードする リポジトリをフォークして、提供するバージョンをチェックアウトするか、特定のバージョンをzipとしてダウンロードします。 - `git checkout v2.106.0`を使用して特定のバージョンをチェックアウトします。 - [リリース](https://github.com/box/box-content-preview/releases)に関するページから特定のバージョンをzipとしてダウンロードします。 ### 2. 依存関係をインストールする 次のコマンドを使用して、依存関係をインストールしてライブラリをビルドします。 ``` yarn install && yarn build:i18n && yarn build:prod ``` ### 3. ファイルを提供する `/dist`フォルダから`dev`フォルダを除くすべてをセルフサービス形式で提供します。フォルダ構造は変えずに、`third-party`を`2.106.0`と同じフォルダに配置する必要があります。 たとえば、`box-assets`ディレクトリを使用したセルフホスティングを行う場合は、以下のURLにアクセスできる必要があります。 - `https://cdn.YOUR_SITE.com/box-assets/2.106.0/en-US/preview.js` - `https://cdn.YOUR_SITE.com/box-assets/third-party/text/2.65.0/papaparse.min.js` - `https://cdn.YOUR_SITE.com/box-assets/third-party/model3d/1.12.0/three.min.js` ## 認証 UI Elementのいずれかを初期化するには、アプリケーションから有効なアクセストークンを提供する必要があります。 アプリケーションの認証方法を確認する アクセストークンをセキュアでない環境 (ユーザーのウェブブラウザ) に渡す前に[ダウンスコープ](g://authentication/tokens/downscope)することもお勧めします。 UI Elementは、アクセストークンが認証用に渡されることだけを想定しているため、Box Platformから利用できるさまざまな種類の認証に使用できます。 テスト目的の場合は、[開発者トークン](g://authentication/tokens/developer-tokens)を使用できます。 ## CORS UI Elementを使用するには、アプリケーションで、クロスオリジンリソース共有でウィジェットが使用されるドメインを許可する必要があります。詳細については、[CORSガイド](g://security/cors)を参照してください。 ## ソースコードとリリース Box UI Elementsのソースコードは[GitHubでホストされています](https://github.com/box/box-ui-elements)。このリポジトリには、使用方法と開発に関する詳細なドキュメントが含まれています。見つかったバグは、わかりやすい再現手順とともに [Issues] タブに登録してください。また、このリポジトリでは、[リリース](https://github.com/box/box-ui-elements/releases)のリストも保持されています。 **Source:** [https://ja.developer.box.com/guides/embed/ui-elements/installation/](https://ja.developer.box.com/guides/embed/ui-elements/installation/) --- ### ウェブアプリ: Box App UserへのOkta IDの関連付け **Type:** quick-start | **Category:** SSOとApp User | **Section:** Developer Guides ウェブアプリ: Box App UserへのOkta IDの関連付け Oktaは、企業に広く採用されているアクセス管理およびIDプラットフォームです。資格情報一式と… # ウェブアプリ: Box App UserへのOkta IDの関連付け [Okta](https://www.okta.com/)は、企業に広く採用されているアクセス管理およびIDプラットフォームです。資格情報一式と1つの安全なダッシュボードを使用して複数のアプリケーションを管理および認証するための統合された方法を提供しています。 カスタムBoxアプリケーションに接続している場合、[Okta API](https://developer.okta.com/)を使用して、そのBoxアプリケーション内でユーザーの本人確認を行うためのシングルサインオンメカニズムを提供できます。これにより、統合IDシステム (Okta) とBox APIの間のエクスペリエンスが統一されます。 ## 概要 このクイックスタートガイドでは、プログラムでOktaを使用してBoxアプリケーションにログインし、OktaユーザーにリンクされているBoxのApp Userをプロビジョニングしてから、そのユーザーに代わってBox APIコールを実行する方法を説明します。 ここでは、以下の手順を説明します。 1. [アプリケーションコードをスキャフォールディング](g://sso-identities-and-app-users/connect-okta-to-app-users/scaffold-application-code)して、ログインできるウェブアプリケーションを作成します。 2. [Oktaアプリケーションを設定および構成](g://sso-identities-and-app-users/connect-okta-to-app-users/configure-okta)してウェブアプリへのログインに使用できる1人目のユーザーを作成し、最終的にそのユーザーのBoxアカウントを作成します。 3. [Boxアプリケーションを設定および構成](g://sso-identities-and-app-users/connect-okta-to-app-users/configure-box)して、ウェブアプリケーションをBoxに接続できるようにします。 4. [アプリケーションのログインフローを作成](g://sso-identities-and-app-users/connect-okta-to-app-users/logging-into-app)して、Oktaユーザーがウェブアプリケーションにログインできるようにします。 5. Oktaユーザーが初めてウェブアプリケーションにログインするときに、[既存のBoxユーザーを検索し、必要に応じてBoxユーザーを作成](g://sso-identities-and-app-users/connect-okta-to-app-users/find-or-create-box-users)します。 6. [最後にアプリケーションを実行](g://sso-identities-and-app-users/connect-okta-to-app-users/run-the-app)して、フロー全体の動作を確認します。 このチュートリアルが完了すると、ブラウザに1つのメッセージが出力されます。今回Oktaユーザーが初めてアプリケーション経由でBoxにログインした場合は、関連付けられたBoxユーザーが作成され、`New user created: {{USERNAME}}`というメッセージがブラウザに出力されます。 その後このユーザーでログインを試みると、`Hello {{USERNAME}}`というメッセージがブラウザに出力されるようになります。 このガイドを簡略化するため、ここでは、ウェブアプリケーションのユーザーインターフェースは作成しません。代わりに、出力はアプリケーションコンソール/ターミナルを通じて表示されるほか、ブラウザで直接テキスト出力として表示されます。 開始する準備ができました **Source:** [https://ja.developer.box.com/guides/sso-identities-and-app-users/connect-okta-to-app-users/](https://ja.developer.box.com/guides/sso-identities-and-app-users/connect-okta-to-app-users/) --- ### ウェブアプリ統合 **Type:** guide | **Category:** アプリケーション | **Section:** Developer Guides ウェブアプリ統合 ウェブアプリ統合により、サードパーティ製アプリケーションをBox… # ウェブアプリ統合 ウェブアプリ統合により、サードパーティ製アプリケーションをBox内で使用できるようになり、ユーザーはファイルを編集または共有する際にそのサードパーティ製アプリケーションを使用できます。 ## 機能 - **ファイル操作**。ユーザーは、サードパーティ製アプリケーションを使用して、Box内に保存されているコンテンツを変更、共有、または編集できます。 - **推奨アプリのサポート**。統合は、Boxプレビューインターフェースで [**推奨アプリ**] の下に表示できます。詳細については、[推奨ウェブ統合](https://support.box.com/hc/ja/articles/360044195533-%E6%8E%A8%E5%A5%A8%E3%82%A2%E3%83%97%E3%83%AA%E3%82%92Enterprise%E3%81%AB%E5%B0%8E%E5%85%A5%E3%81%99%E3%82%8B)を参照してください。 - **スコープが設定された利用状況**。統合は、特定のコンテンツタイプやファイル拡張子に制限できます。 ## [推奨アプリ] での表示 ウェブアプリ統合が [**推奨アプリ**] に表示されるのは、[統合] で公開されている場合のみです。 ウェブアプリ統合の作成方法を確認する **Source:** [https://ja.developer.box.com/guides/applications/web-app-integrations/](https://ja.developer.box.com/guides/applications/web-app-integrations/) --- ### ウェブアプリ統合の作成 **Type:** guide | **Category:** アプリケーション | **Section:** Developer Guides ウェブアプリ統合の作成 このガイドでは、Platformアプリとのウェブアプリ統合を設定する方法について説明します。 サーバー側統合のサポートは終了しました。つまり、サーバー側の処理を使用するアプリケーションは引き続き動作しますが、事前コールバックのURLやBasic… # ウェブアプリ統合の作成 このガイドでは、Platformアプリとのウェブアプリ統合を設定する方法について説明します。 サーバー側統合のサポートは終了しました。つまり、サーバー側の処理を使用するアプリケーションは引き続き動作しますが、事前コールバックのURLやBasic認証など、サーバー側の構成オプションを変更することはできなくなります。これらのオプションを無効化し、実装を新しいものに変更できます。 ## OAuth 2.0アプリケーションの作成 [開発者コンソール](https://app.box.com/developers/console)に移動し、[OAuth 2.0認証](g://authentication/oauth2/oauth2-setup)を利用する[Platformアプリ](g://applications/app-types/platform-apps)を作成します。 ## 新しい統合の作成 次に、[**統合**] タブに移動し、[**ウェブアプリ統合を作成**] をクリックします。 ## 統合の構成 統合を構成するには、各値について、以下のガイダンスに従います。 ### アプリ情報 | フィールド | 説明 | | --- | --- | | 統合名 | 統合の名前。ユーザーがファイルまたはフォルダの [その他のオプション] > [統合] メニューを選択したときにBoxウェブアプリに表示されます。 | | 説明 | Box統合に表示される統合の説明。 | | サポートされているファイル拡張子 | 統合は、選択されているファイル拡張子の [その他のオプション] > [統合] メニューのオプションとしてのみ表示されます。 | | 必要な権限 | ユーザーが統合を表示するために必要な権限を決定します。[ダウンロードの権限が必要] にした場合、ユーザーはファイルをダウンロードできますが、そのファイルを更新することはできません。[すべての権限が必要] にした場合、ユーザーはファイルのダウンロードと更新を行えます。 | | 統合の範囲 | 統合の範囲を指定します。統合の呼び出し元となるファイル/フォルダ、またはその親フォルダを指定します。 | | [共有ページで表示] の切り替え | 共有ページで外部ユーザーに統合を表示可能にするかどうかを決定します。有効にした場合、コンテンツでコラボレーションしていないユーザーが共有リンクを介して項目にアクセスすると、コンテキストメニューに統合が表示されます。 | | [ロックして、この統合を使用したファイルの上書きを現在のユーザーにのみ許可] の切り替え | 異なるウェブアプリ統合でファイルを同時に編集可能にするかどうかを決定します。 | | 統合の種類 | 必要な統合の種類を選択します。使用できるオプションは、[ファイル]、[フォルダ]、[両方] です。 | ### コールバック構成 | フィールド | 説明 | | --- | --- | | クライアントコールバックのURL | ポップアップ統合での最初のリクエストの後に、Boxからの追加のコールバックリクエストを処理します。アプリケーションがRESTメソッドでファイルパラメータを指定した場合、事前コールバックのURLはクライアントから発信できません。そのため、必要なインターフェースをサーバーがユーザーに送信できるように、2番目のリクエストがクライアントからサーバーに送信される必要があります。 | | プロンプトメッセージ | ユーザーが統合を開始する際に表示されるメッセージを指定します。このフィールドを使用して、次に何が起こるかについてコンテキストを提供します。このメッセージは500文字に制限されています。 | | ユーザーエクスペリエンス | 統合が新しいウィンドウで開くことを通知します。 | | 新しいウィンドウの設定 | アプリケーションを新しいタブで開くかどうかを決定します。 | ### コールバックパラメータ [**コールバックパラメータ**] セクションでは、ユーザーが確認プロンプトを受け入れるとBoxからコールバックURLに送信されるパラメータを構成します。この設定が構成されていない場合、BoxからコールバックURLにパラメータが送信されません。パラメータを追加するには、[**メソッド**] (GETまたはPOST) を選択し、[**パラメータ名**] を指定して、[**パラメータ値**] を追加します。 **File**メソッドのサポートは終了しました。すでにこのメソッドを使用している場合は、その値を編集できません。**File**メソッドを**GET**または**POST**に変更することはできますが、この操作を元に戻すことはできません。 例: **GET - `userid` - `#user_id#`**。 以下のパラメータ値が使用可能です。 | パラメータ | メソッド | 説明 | | --- | --- | --- | | user_id | GET、POST | BoxユーザーID。この情報は、アクションを完了するためにユーザー認証が必要なポップアップ統合で使用されます。Box IDをアプリケーションに保存すると、統合からの後続の認証リクエストを有効にできます。 | | user_name | POST | Boxユーザーのフルネームまたはメールアドレス。Boxユーザーが常に自分の名前を指定しているとは限りません。 | | file_id | GET、POST | BoxファイルID。このIDを使用すると、ファイルを操作するBox APIコールを実行できます。 | | file_name | POST | ファイルの名前。 | | file_extension | GET、POST | ファイルの拡張子。 | | auth_code | GET、POST | OAuth 2.0承認コード。これは、認証の成功時にBoxによって生成されます。その後、アプリケーションは、この承認コードをOAuth 2.0アクセストークンの代わりにBoxに指定する必要があります。有効なアクセストークンが含まれた承認ヘッダーをすべてのBox APIリクエストに含める必要があります。 | | redirect_to_box_url | GET、POST | ポップアップ統合で、確認プロンプトによるリクエストの送信先となるURL。このURLを使用すると、ユーザーは [すべてのファイル] ページにリダイレクトされます。このパラメータにより、ポップアップパネルが閉じ、[すべてのファイル] ページは、統合による変更をすべて反映するよう更新されます。このパラメータをアプリケーションに追加しない場合は、URL全体を指定できます。成功: #redirect_to_box_url#&status=success&message=Your%20action%20was%20successful%2E。失敗: #redirect_to_box_url#&status=failure&message=Your%20action%20was%20unsuccessful%2E | ### 統合ステータス - **開発**: 統合は、[**一般設定**] タブで表示されるアプリケーションコラボレータのみが表示および使用できます。このオプションは、アプリケーションがまだ開発中でテストの実施中である場合に最もよく使用されます。 - **オンライン**: 統合は、すべてのBoxユーザーが表示し、使用できます。このオプションは、開発が完了し、アプリケーションを統合で公開する準備ができている場合に最もよく使用されます。 - **メンテナンス**: 統合は、[**一般設定**] タブで表示されるアプリケーションコラボレータのみが表示および使用できます。このオプションは、統合が [統合] で公開された後、メンテナンスでの更新を実行したり問題をトラブルシューティングしたりする必要がある場合に最もよく使用されます。このオプションを使用すると、アプリケーションのコラボレータ以外のすべてのユーザーに対して統合が一時的にオフラインになります。 ## Box統合のユースケースの例 ユーザーがポップアップ統合を選択すると、Boxから事前コールバックのURLにコールバックリクエストが送信されます。これにより、構成済みのコールバックパラメータがサーバーに送信されます。クライアントが必要なデータを最初のリクエストからすべて取得できない場合は、Boxが2番目のリクエストを送信することもあります。 次の例では、クライアントコールバックのURLが必要ありません。 - ポップアップ統合で、`download_file_url`コールバックパラメータを使用してREST呼び出しを実行する。 - ユーザーが確認プロンプトで [**OK**] をクリックしてポップアップを受け入れる。 - Boxが次のURLにリクエストを送信する (事前コールバックのURLにコールバックパラメータを追加): `http://www.doceditor.com/service?apikey=abc&file=&redirect=`。 - コールバックURLからのレスポンスにより、リクエストを送信したユーザーにユーザーインターフェースが表示される。ポップアップには、アクションを続行するために必要なすべての情報が表示されているため、追加のクライアントコールバックは必要ありません。 次の例では、クライアントコールバックのURLが必要です。 - ポップアップ統合で、ファイルコールバックパラメータを使用してREST呼び出しを実行する。 - ユーザーが確認プロンプトで [**OK**] をクリックしてポップアップを受け入れる。 - ポップアップによって表示されたページで、Boxからリモートサーバーに、ファイルのコンテンツを含むPOSTリクエストとともにコールバックパラメータが送信される。 - Boxがリモートサーバーからレスポンスを受信し、クライアントにクライアントコールバックのURLへのレスポンスを投稿するよう指示する。このURLで識別されたサーバーがレスポンスを解釈し、適切なセッションIDを持つユーザーをリダイレクトします。 ## クライアントコールバックのURLのリクエスト形式 BoxからクライアントコールバックのURLに送信されるPOSTリクエストは、事前コールバックのURLからレスポンスを取得し、元のコールバックと同じデータとともにレスポンスを同じURLに転送します。 | クライアントコールバックのURL | 例 | | --- | --- | | 2つのGETパラメータと1つのPOSTパラメータ: http://your-client-callback-url.com/?get_param1=value1&get_param2=value2 | POST data: post_param1=value1initial_callback_response | クライアントコールバックリクエストへのレスポンスはHTTPステータス302で、ユーザーは正しいURLにリダイレクトされるか、UIのHTMLにリダイレクトされます。 ほとんどの場合、このURLは、ウェブアプリ統合のために開発された個々のAPIまたはカスタムスクリプトを指します。これは、事前コールバックのURLの結果を解析します。また、このURLは、インターネット上で一般公開する必要があることに注意してください。 ## 統合の一般公開 Box統合を一般公開するには、統合をApp Centerに掲載する必要があります。詳細については、[統合](g://applications/integrations)ガイドに従ってください。 **Source:** [https://ja.developer.box.com/guides/applications/web-app-integrations/configure/](https://ja.developer.box.com/guides/applications/web-app-integrations/configure/) --- ### ウェブリンク **Type:** guide | **Category:** ウェブリンク | **Section:** Developer Guides ウェブリンク ウェブリンクは、URLを指すオブジェクトです。これらのオブジェクトは、Box… # ウェブリンク ウェブリンクは、URLを指すオブジェクトです。これらのオブジェクトは、Boxウェブアプリ内でブックマークとも呼ばれます。 ウェブリンクはファイルオブジェクトと同様に扱われます。つまり、共有リンクの作成についても同じようにサポートされ、コピー、完全削除、および復元が可能です。 **Source:** [https://ja.developer.box.com/guides/web-links/](https://ja.developer.box.com/guides/web-links/) --- ### ウェブリンクの作成 **Type:** guide | **Category:** ウェブリンク | **Section:** Developer Guides ウェブリンクの作成 Boxでウェブリンクを作成するには、APIにフォルダidと、ウェブリンクのリンク先であるurlを渡す必要があります。urlはhttp://またはhttps://で始まる必要があります。 # ウェブリンクの作成 Boxでウェブリンクを作成するには、APIにフォルダ`id`と、ウェブリンクのリンク先である`url`を渡す必要があります。`url`は`http://`または`https://`で始まる必要があります。 **Source:** [https://ja.developer.box.com/guides/web-links/create/](https://ja.developer.box.com/guides/web-links/create/) --- ### ウェブリンクの削除 **Type:** guide | **Category:** ウェブリンク | **Section:** Developer Guides ウェブリンクの削除 Boxでウェブリンクを削除するには、そのウェブリンクのIDをAPIに渡す必要があります。 # ウェブリンクの削除 Boxでウェブリンクを削除するには、そのウェブリンクのIDをAPIに渡す必要があります。 **Source:** [https://ja.developer.box.com/guides/web-links/delete/](https://ja.developer.box.com/guides/web-links/delete/) --- ### ウェブリンクの復元 **Type:** guide | **Category:** ごみ箱 | **Section:** Developer Guides ウェブリンクの復元 ごみ箱に移動されたが削除されていないウェブリンクを復元するには、/web_links/:web_link_idエンドポイントにPOSTリクエストを送信します。これにより、ウェブリンクがまだ使用可能であれば元の親フォルダに戻されます。オプションとしてparent… # ウェブリンクの復元 ごみ箱に移動されたが削除されていないウェブリンクを復元するには、`/web_links/:web_link_id`エンドポイントに`POST`リクエストを送信します。これにより、ウェブリンクがまだ使用可能であれば元の親フォルダに戻されます。オプションとして`parent`フォルダを指定することもできます。 **Source:** [https://ja.developer.box.com/guides/trash/restore-web-link/](https://ja.developer.box.com/guides/trash/restore-web-link/) --- ### ウェブリンクを完全に削除 **Type:** guide | **Category:** ごみ箱 | **Section:** Developer Guides ウェブリンクを完全に削除 ごみ箱に移動されたウェブリンクは、デフォルトで30日間ごみ箱に保持された後で削除されます。BusinessアカウントまたはEnterprise… # ウェブリンクを完全に削除 ごみ箱に移動されたウェブリンクは、デフォルトで30日間ごみ箱に保持された後で削除されます。BusinessアカウントまたはEnterpriseアカウントの管理者は、削除までの期間を変更できます。削除までの期間が経過する前にごみ箱からウェブリンクを完全に削除する場合は、ごみ箱に移動されたウェブリンクの`ID`を使用して`DELETE`リクエストを`/web_links/:web_link_id/trash`に送信します。 **Source:** [https://ja.developer.box.com/guides/trash/permanently-delete-web-link/](https://ja.developer.box.com/guides/trash/permanently-delete-web-link/) --- ### エージェントの作成 **Type:** guide | **Category:** Box AI Studio | **Section:** Developer Guides エージェントの作成 Box AI Studioは、Enterprise Advancedアカウントでのみ使用できます。 POST /2.0/ai_agentsエンドポイントを使用すると、新しいカスタムAI… # エージェントの作成 Box AI Studioは、Enterprise Advancedアカウントでのみ使用できます。 `POST /2.0/ai_agents`エンドポイントを使用すると、新しいカスタム[AIエージェント](g://box-ai/ai-agents/index)を作成できます。 ## リクエストの送信 リクエストを送信するには、`POST /2.0/ai_agents`エンドポイントを使用します。 アプリを承認するための開発者トークンを生成済みであることを確認します。詳細については、[Box AIの使い方](g://ai-studio/getting-started-ai-studio)を参照してください。 ### パラメータ コールを実行するには、以下のパラメータを渡す必要があります。必須のパラメータは**太字**で示されています。 | パラメータ | 説明 | 例 | | --- | --- | --- | | type | クエリの処理に使用されるエージェントのタイプ。 | ai_agent | | name | AIエージェントの名前。 | My AI Agent | | access_state | AIエージェントの状態。値はenabled、disabledのいずれかです。 | enabled | | icon_reference | AIエージェントのアイコン参照。これは、URL https://cdn01.boxcdn.net/app-assets/aistudio/avatars/<file_name>の形式で指定する必要があります。この場合、file_nameに使用可能な値はlogo_boxAi.png、logo_stamp.png、logo_legal.png、logo_finance.png、logo_config.png、logo_handshake.png、logo_analytics.png、logo_classification.pngです。 | https://cdn01.boxcdn.net/app-assets/aistudio/avatars/logo_analytics.svg | | allowed_entities | 許可するユーザーまたはグループのリスト。 | | | ask | 質問に使用されるAIエージェント。 | ask | | extract | 抽出に使用されるAIエージェント。 | | | text_gen | テキストの生成に使用されるAIエージェント。 | | **Source:** [https://ja.developer.box.com/guides/ai-studio/ai-studio-agents/create-agents/](https://ja.developer.box.com/guides/ai-studio/ai-studio-agents/create-agents/) --- ### エージェントの取得 **Type:** guide | **Category:** Box AI Studio | **Section:** Developer Guides エージェントの取得 Box AI Studioは、Enterprise Advancedアカウントでのみ使用できます。 すべてのAIエージェントのリストの取得 GET /2.0/ai_agentsエンドポイントを使用すると、指定されたパラメータに基づいてすべてのAI… # エージェントの取得 Box AI Studioは、Enterprise Advancedアカウントでのみ使用できます。 ## すべてのAIエージェントのリストの取得 `GET /2.0/ai_agents`エンドポイントを使用すると、指定されたパラメータに基づいてすべてのAIエージェントのリストを取得できます。 ### リクエストの送信 リクエストを送信するには、`GET /2.0/ai_agents`エンドポイントを使用します。 アプリを承認するための開発者トークンを生成済みであることを確認します。詳細については、[Box AI Studioの使い方](g://ai-studio/getting-started-ai-studio)を参照してください。 #### パラメータ コールを実行するには、以下のパラメータを渡す必要があります。必須のパラメータは**太字**で示されています。 | パラメータ | 説明 | 例 | | --- | --- | --- | | mode | 返されるエージェント構成にフィルタをかけるためのモード。使用可能な値はask、text_gen、extractです。 | ask | | fields | レスポンスで返されるフィールド。 | ask | | agent_state | 返されるエージェントの状態。値はenabled、disabledのいずれかです。 | enabled | | fields | レスポンスで返されるフィールド。値はask、text_gen、extractのいずれかです。 | ask | | include_box_default | レスポンスにBoxのデフォルトエージェントを含めるかどうか。 | true | | limit | 返す項目の1ページあたりの最大数。 | 1000 | | marker | 結果が返される開始位置のマーカー。 | JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii | **Source:** [https://ja.developer.box.com/guides/ai-studio/ai-studio-agents/get-agents/](https://ja.developer.box.com/guides/ai-studio/ai-studio-agents/get-agents/) --- ### エラー **Type:** guide | **Category:** APIコール | **Section:** Developer Guides エラー Box APIでは、HTTPステータスコードを使用して、リクエストが正常に処理されたかどうかを通知します。 クライアントエラー HTTP 4XX形式の大半のクライアントエラーとHTTP 5XX形式の一部のサーバーエラーでは、標準のクライアントエラーJSON… # エラー Box APIでは、[HTTPステータスコード](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html)を使用して、リクエストが正常に処理されたかどうかを通知します。 ## クライアントエラー HTTP 4XX形式の大半のクライアントエラーとHTTP 5XX形式の一部のサーバーエラーでは、標準のクライアントエラーJSONオブジェクトが返されます。 ``` { "type": "error", "status": 400, "code": "bad_digest", "help_url": "https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/", "message": "The specified content-md5 did not match what we received", "request_id": "abcdef123456" } ``` 詳細については、[クライアントエラーのリソース](resource://client_error)を参照してください。 ## 共通エラーコード Box APIの使用時に発生した一般的なエラーの解決策については、[開発者向けトラブルシューティングの記事](https://support.box.com/hc/ja/sections/360007552913-Box-Platform%E3%81%AB%E9%96%A2%E3%81%99%E3%82%8B%E3%83%88%E3%83%A9%E3%83%96%E3%83%AB%E3%82%B7%E3%83%A5%E3%83%BC%E3%83%86%E3%82%A3%E3%83%B3%E3%82%B0)を確認してください。 ### 400 Bad Request | | | | | --- | --- | --- | | エラー | bad_digest | | | メッセージ | The specified content-md5 did not match what we received. (指定のcontent-md5は受信したものと一致しませんでした。) | | | 解決策 | ファイルのアップロード中に、ファイルのSHA-1ハッシュとcontent-md5ヘッダーを指定して、ファイルが転送中に破損していないかどうかを確認できます。リクエストで指定されたSHA-1ハッシュは、アップロードで受信したものと一致していません。アップロードしたファイルの有効なSHA-1ハッシュを指定してください。 | | | | | | | エラー | bad_request | | | メッセージ | | | | 解決策 | APIリクエストで指定された必須パラメータが見つからないか無効です。詳細については、レスポンス本文の拡張エラーメッセージを確認してください。 | | | | | | | エラー | cannot_make_collaborated_subfolder_private | | | メッセージ | Cannot move a collaborated folder to a private folder unless the new owner is explicitly specified. (新しい所有者が明示的に指定されない限り、コラボレーションサブフォルダを非公開フォルダに移動することはできません。) | | | 解決策 | リクエストのowned_by.idフィールドを設定して、コンテンツの転送先となるユーザーのIDを指定してください。 | | | | | | | エラー | collaborations_not_available_on_root_folder | | | メッセージ | Root folder cannot be collaborated (ルートフォルダのコラボレーションができません) | | | 解決策 | ユーザーのルートフォルダ (フォルダID 0) にコラボレータを設定できません。ルートフォルダとは異なるフォルダIDを使用してください。 | | | | | | | エラー | cyclical_folder_structure | | | メッセージ | Folder move creates cyclical folder structure (フォルダの移動により循環フォルダ構造が作成されます) | | | 解決策 | フォルダの移動で指定したフォルダIDによって、循環フォルダ構造 (たとえば、フォルダがそのフォルダ内のサブフォルダに移動される構造) が作成されます。フォルダ移動リクエストで指定するフォルダを変更してください。 | | | | | | | エラー | folder_not_empty | | | メッセージ | Cannot delete – folder not empty (削除できません – フォルダにファイルが存在しません) | | | 解決策 | 削除する前に、フォルダからすべてのコンテンツを削除してください。 | | | | | | | エラー | invalid_collaboration_item | | | メッセージ | Item type must be specified and set to 'folder' (項目タイプは指定されていなければならず、「folder」に設定されていることが必要です) | | | 解決策 | コラボレーション項目のitem.typeフィールドをフォルダに設定してください。 | | | | | | | エラー | invalid_grant | | | メッセージ | Verify the authorization code is set correctly in your request, or your application likely needs to get a new authorization code. (リクエストに承認コードが正しく設定されていることを確認してください。そうしないと、アプリケーションで新しい承認コードが必要になる可能性があります。) | | | 解決策 | APIリクエストで指定された承認コードが見つからないか、無効になりました。考えられる解決策として、リクエストにアクセストークンが正しく追加されているかどうかを確認してください。正しく設定されている場合は、アクセストークンが期限切れになっている可能性があります。アクセストークンを更新するか、新しいアクセストークンを取得してください。 | | | | | | | エラー | invalid_grant | | | メッセージ | Current date time must be before the expiration date time listed in the 'exp' claim. (現在の日時は「exp」クレームに記載されている有効期限の日時よりも前である必要があります。) | | | 解決策 | このエラーは、ローカルマシンとBoxサーバーのUnix時間が同期されていない場合に発生します。このエラーを修正するには、ローカルマシンのUnix時間を、同期対象の時刻サーバーと一致するよう更新し、再度リクエストしてみてください。 | | | | | | | エラー | invalid_limit | | | メッセージ | Limit is not a valid number (制限値が有効な数値ではありません) | | | 解決策 | 指定された制限値に有効な数値を追加してください。 | | | | | | | エラー | invalid_offset | | | メッセージ | Offset is not a valid number (オフセットが有効な数値ではありません) | | | 解決策 | 指定されたオフセット値に有効な数値を追加してください。 | | | | | | | エラー | invalid_request_parameters | | | メッセージ | Invalid input parameters in request (リクエスト内に無効な入力パラメータがあります) | | | 解決策 | APIリクエストで無効なパラメータが送信されました。APIリファレンスドキュメントで、このAPI操作に指定すべき正しいリクエストパラメータを確認してください。 | | | | | | | エラー | invalid_status | | | メッセージ | You can change the status only if the collaboration is pending (ステータスを変更できるのは、コラボレーションが保留中の場合のみです) | | | 解決策 | コラボレーションのステータスは、現在のステータスが保留中に設定されている場合に、accessible_byフィールドで指定されたユーザーのみが承認済みまたは拒否済みに更新できます。 | | | | | | | エラー | invalid_upload_session_id | | | メッセージ | The upload session ID provided in the URL is not of a valid format. (URLに指定されているアップロードセッションIDが有効な形式ではありません。) | | | 解決策 | 分割アップロードAPIリクエストの送信時に指定されたセッションIDが無効です。作成されたセッションと同じセッションIDを使用してください。 | | | | | | | エラー | item_name_invalid | | | メッセージ | Item name invalid (項目名が無効です) | | | 解決策 | ファイルの名前が有効であることを確認してください。Boxでは、255文字以下のファイル名またはフォルダ名のみがサポートされています。印刷不可能な文字を含むファイル名、/、\、<、>、:、` | , ?, *, -`という文字を含む名前、先頭または末尾にスペースを含む名前のほか、「.」と「..」という特殊な名前も使用できません。 | | | | | | エラー | item_name_too_long | | | メッセージ | Item name too long (項目名が長すぎます) | | | 解決策 | 項目に指定されている名前の長さを短くしてください。Boxのファイル名またはフォルダ名に使用できる文字数は255文字以下です。 | | | | | | | エラー | metadata_after_file_contents | | | メッセージ | Metadata is included after file contents in a file upload request. (メタデータは、ファイルアップロードリクエストでファイルのコンテンツの後に含まれています。) | | | 解決策 | ファイルのコンテンツの前にファイルのメタデータを含めてください。 | | | エラー | password_reset_required | | | メッセージ | User needs to reset password (ユーザーはパスワードをリセットする必要があります) | | | 解決策 | ユーザーは、アカウントの設定手順を完了していません。 | | | | | | | エラー | requested_page_out_of_range | | | メッセージ | Requested representation page out of range (リクエストされたレプリゼンテーションページが範囲外です) | | | 解決策 | 指定された範囲ヘッダーは、指定した項目のサイズに収まりません。項目のサイズに収まるよう範囲を調整し、もう一度やり直してください。 | | | | | | | エラー | requested_preview_unavailable | | | メッセージ | Requested preview unavailable (リクエストされたプレビューは利用できません) | | | 解決策 | ファイルに対してリクエストされたサムネイルサイズが有効ではありません。API操作のリファレンスドキュメントで、利用可能な形式サイズを確認してください。 | | | | | | | エラー | sync_item_move_failure | | | メッセージ | Cannot move a synced item (同期した項目を移動できません) | | | 解決策 | 項目は、Box Syncクライアントによって同期が設定されているため移動できません。項目のsync_stateをnot_syncedに設定することで、解決できる場合があります。 | | | | | | | エラー | task_assignee_not_allowed | | | メッセージ | Assigner does not have sufficient privileges to assign task to assignee (任命者には、担当者にタスクを割り当てるのに十分な権限がありません) | | | 解決策 | タスクを割り当てようとしているユーザーに、そのための適切な権限がありません。タスクの割り当てを許可するようユーザー権限を調整してください。 | | | | | | | エラー | terms_of_service_required | | | メッセージ | User must accept custom terms of service before action can be taken (ユーザーは操作を実行する前にカスタムサービス利用規約に同意する必要があります) | | | 解決策 | Boxアカウントの管理者はカスタムサービス利用規約を設定していますが、ユーザーはまだログインしてこのサービス利用規約に同意していません。続行するには、ユーザーがこのサービス利用規約に同意するか、管理者が同規約を無効にする必要があります。詳細については、こちらで確認してください。 | | | | | | | エラー | user_already_collaborator | | | メッセージ | ユーザーはすでにコラボレータです | | | 解決策 | ある項目のコラボレータに設定しようとしているユーザーは、すでにその項目のコラボレータです。このリクエストは必要ありません。 | | | | | | ### 401 Unauthorized | | | | --- | --- | | エラー | unauthorized | | メッセージ | 許可なし | | 解決策 | 承認トークンは承認されていません。詳細については、本文の拡張エラーメッセージを確認してください。 | ### 403 Forbidden | | | | --- | --- | | エラー | access_denied_insufficient_permissions | | メッセージ | Access denied – insufficient permission (アクセスが拒否されました – 権限が不足しています) | | 解決策 | アクセストークンに適切なユーザー権限またはスコープが設定されていません。解決策の情報については、こちらを参照してください。 | | | | | エラー | insufficient_scope | | メッセージ | The request requires higher privileges than provided by the access token. (リクエストには、アクセストークンによって提供される権限よりも高い権限が必要です。) | | 解決策 | 通常、このエラーは、API操作に必要なスコープが有効になっていない場合に発生します。構成済みのアプリケーションスコープを確認し、該当する場合はアプリケーションを再承認してください。 | | エラー | access_denied_item_locked | | メッセージ | Access denied – item locked (アクセスが拒否されました – 項目がロックされています) | | 解決策 | ロックされた項目にアクセスしようとしていますが、アクセスするための適切な権限がありません。項目のロックを解除してから、再度アクセスしてみてください。 | | | | | エラー | access_from_location_blocked | | メッセージ | | | 解決策 | 管理者によって承認されていない場所からBoxにログインしようとしています。この問題を解決するには、管理者にお問い合わせください。 | | | | | エラー | file_size_limit_exceeded | | メッセージ | ファイルサイズがフォルダ所有者のファイルサイズ上限を超えています | | 解決策 | アカウントの種類に基づいたファイルサイズの上限については、こちらを参照してください。 | | | | | エラー | forbidden | | メッセージ | | | 解決策 | クライアントには、このセッションにアップロードするための権限がありません。アップロードできるのは、アップロードセッションを開始したユーザーのみです。 | | | | | エラー | forbidden_by_policy | | メッセージ | Access denied – Blocked by Shield Access Policy (アクセスが拒否されました – Shieldアクセスポリシーによってブロックされています) | | 解決策 | 会社に適用されているShieldアクセスポリシーによってこの操作が妨げられています。Enterprise管理者に連絡して、適用されているShieldアクセスポリシーを調整してください。 | | | | | エラー | forbidden_by_policy | | メッセージ | Access denied – Blocked by Shield Malware Detection Rule (アクセスが拒否されました – Shieldマルウェア検出ルールによってブロックされています) | | 解決策 | Shieldマルウェア検出ルールを有効化すると、悪意のある可能性のあるコンテンツをダウンロードしたり、ローカルで編集したりできなくなりますが、引き続きプレビューとオンライン編集は可能です。適用されているShieldポリシーを調整するには、会社の管理者にお問い合わせください。 | | | | | エラー | incorrect_shared_item_password | | メッセージ | | | 解決策 | 共有項目にはパスワードが必要ですが、パスワードが誤っているか指定されていません。 | | | | | エラー | storage_limit_exceeded | | メッセージ | アカウントのストレージサイズの上限に達しました | | 解決策 | アカウントのストレージサイズの上限に達しました。続行するには、アカウントをアップグレードするか、コンテンツを完全に削除してください。単にごみ箱に移動したコンテンツも、完全に削除されるまでアカウントの合計サイズにカウントされます。 | | | | | エラー | user_email_confirmation_required | | メッセージ | User needs to complete email confirmation (ユーザーはメール確認を完了する必要があります) | | 解決策 | ユーザーは、メール確認の手順をまだ完了していません。 | | | | | エラー | cors_origin_not_whitelisted | | メッセージ | Access denied - Did you forget to safelist your origin in the CORS configuration of your app? (アクセスが拒否されました – アプリのCORS構成のオリジンをセーフリストに追加し忘れていませんか。) | | 解決策 | アプリケーションはウェブサイトからBox APIにアクセスしようとしました。このアプリケーションでは、サイトがホストされているドメインに対してクロスオリジンリソース共有を明示的に許可する必要があります。 | ### 404 Not Found | | | | --- | --- | | エラー | not_found | | メッセージ | | | 解決策 | リソースが見つかりませんでした。詳細については、レスポンス本文の拡張エラーメッセージを確認してください。 | | | | | エラー | not_trashed | | メッセージ | Item is not trashed (項目はごみ箱に移動されていません) | | 解決策 | ごみ箱には、完全に削除する項目がありません。最初に、項目をごみ箱に移動してください。 | | | | | エラー | preview_cannot_be_generated | | メッセージ | Preview cannot be generated (プレビューを生成できません) | | 解決策 | 指定されたファイルのプレビューのサムネイルを生成できません。 | | | | | エラー | trashed | | メッセージ | Item is trashed (項目はごみ箱に移動されました) | | 解決策 | アクセス対象の項目がごみ箱にあり、変更できません。項目をごみ箱から移動してやり直してください。 | ### 405 Method Not Allowed | | | | --- | --- | | エラー | method_not_allowed | | メッセージ | Method Not Allowed (メソッドが許可されていません) | | 解決策 | API操作に使用されるHTTPメソッドは許可されていません。APIリファレンスドキュメントで、API操作に必要なHTTP動詞を確認してください。 | ### 409 Conflict | | | | --- | --- | | エラー | conflict | | メッセージ | A resource with this value already exists (この値のリソースはすでに存在します) | | 解決策 | このエラーは、作成するリソースがすでに存在する場合に発生する可能性があります。詳細については、レスポンス本文の拡張エラーメッセージを確認してください。 | | | | | エラー | item_name_in_use | | メッセージ | Item with the same name already exists (同じ名前の項目はすでに存在します) | | 解決策 | このエラーは、同じ名前のリソースがすでに存在している場合に発生する可能性があります。追加/変更するリソース名には一意の名前を指定してください。 | | | | | エラー | name_temporarily_reserved | | メッセージ | The item name is reserved by another processing item. Wait and then retry the request, or wait and check the parent folder to see if the name is in use. (項目名は別の処理項目によって予約されています。しばらく待ってからリクエストを再試行するか、しばらく待ってから名前が使用中であるかどうか親フォルダを確認してください。) | | 解決策 | 重複する2つのリクエストが同時に送信されました。Boxは最初のリクエストを確認して名前を予約しますが、最初のリクエストの処理が完了する前に2つ目の重複するリクエストを受信しています。最初のリクエストが完了してから2番目のリクエストを送信してください。 | | | | | エラー | operation_blocked_temporary | | メッセージ | The operation is blocked by another ongoing operation (他の進行中の操作によって操作がブロックされました) | | 解決策 | このエラーは、移動やコピーなど、他のフォルダ操作によってブロックされたフォルダにアクセスしようとしたときに返されます。後でもう一度やり直してください。 | | | | | エラー | recent_similar_comment | | メッセージ | A similar comment has been made recently (同様のコメントが最近作成されました) | | 解決策 | 同様のコメントが最近作成されており、重複する可能性があるためAPIがフラグを設定しています。コメントが実際に作成済みか確認するか、コメントの内容を変更してやり直してください。 | | | | | エラー | user_login_already_used | | メッセージ | User with the specified login already exists (指定のログインを持つユーザーがすでに存在します) | | 解決策 | 同じメールアドレスのユーザーがすでに存在します。既存ユーザーを参照するか、別のメールアドレスを指定してください。 | ### 410 Gone | | | | --- | --- | | エラー | session_expired | | メッセージ | | | 解決策 | 指定されたアップロードセッションIDに関連付けられたアップロードセッションは、有効期限が切れているためアクセスできません。 | | | | | エラー | upload_failed | | メッセージ | | | 解決策 | アップロードセッションで回復不能な状態になり、続行できません。このリクエストまたはその他のリクエストのアップロードセッションは、結果として、不適切な状態 (パーツ重複など) になりました。この状態の原因として、パーツの上限を超過しているか、重複するパーツがアップロード済みであることが考えられます。 | ### 411 Length Required | | | | --- | --- | | エラー | length_required | | メッセージ | content-length header was required, but not provided. (content-lengthヘッダーが要求されましたが、指定されていません。) | | 解決策 | APIリクエストでContent-Lengthヘッダーを指定してください。 | ### 412 Precondition Failed | | | | --- | --- | | エラー | precondition_failed | | メッセージ | The resource has been modified. Retrieve the resource again and retry (このリソースは変更されています。リソースをもう一度取得してから再試行してください) | | 解決策 | 詳細については、レスポンス本文の拡張エラーメッセージを確認してください。 | | | | | エラー | sync_state_precondition_failed | | メッセージ | The resource has been modified. Retrieve the resource again and retry (このリソースは変更されています。リソースをもう一度取得してから再試行してください) | | 解決策 | 詳細については、レスポンス本文の拡張エラーメッセージを確認してください。 | ### 413 Request Entity Too Large | | | | --- | --- | | エラー | request_entity_too_large | | メッセージ | Request Entity too Large (リクエストのエンティティが大きすぎます) | | 解決策 | アップロードのサイズが許容された上限を超えると、このエラーが発生します。レスポンス本文の拡張エラーメッセージを確認してください。 | ### 415 Unsupported Media Type | | | | --- | --- | | エラー | unsupported_media_type | | メッセージ | Previews for boxnote files are not yet supported. (boxnoteファイルのプレビューはサポートされていません。) | | 解決策 | このエラーは、Box Noteの埋め込みプレビューをリクエストしたときに発生します。現時点では、埋め込みプレビューがBox Notesでサポートされていません。 | ### 429 Too Many requests | | | | --- | --- | | エラー | rate_limit_exceeded | | メッセージ | Request rate limit exceeded, try again later. (リクエストのレート制限を超えました。後でもう一度やり直してください。) | | 解決策 | クライアントの処理が速すぎて、レート制限を受けました。クライアントでは、retry-afterヘッダーで指定された時間が経過してからリクエストをやり直すことが推奨されます。4つのレート制限に注意する必要があります。 | ### 500 Internal Service Error | | | | --- | --- | | エラー | internal_server_error | | メッセージ | Internal Server Error (内部サーバーエラー) | | 解決策 | クライアントは指数バックオフ戦略を使用してやり直す必要があります | ### 502 Bad Gateway | | | | --- | --- | | エラー | bad_gateway | | メッセージ | | | 解決策 | クライアントは指数バックオフ戦略を使用してやり直す必要があります | ### 503 Unavailable | | | | --- | --- | | エラー | unavailable | | メッセージ | 利用できません | | 解決策 | Retry-Afterヘッダーがレスポンスで返された場合、クライアントは、そのヘッダーの値に従ってリクエストを再試行する必要があります。稀に、クライアントが503のレスポンスを受け取った後も、書き込み操作が最終的にその変更を保持する可能性があるため、クライアントは、再試行時にこのケースを処理する必要があります。問題が引き続き発生する場合は、BoxのStatusサイトで、機能停止に関する既知の情報を確認してください。 | **Source:** [https://ja.developer.box.com/guides/api-calls/permissions-and-errors/common-errors/](https://ja.developer.box.com/guides/api-calls/permissions-and-errors/common-errors/) --- ### オプションや一括コマンドの使用 **Type:** quick-start | **Category:** CLI | **Section:** Developer Guides オプションや一括コマンドの使用 オプション オプションは、CLIコマンドで使用する追加のオプション機能を提供します。また、オプションはフラグまたは引数とも呼ばれる場合があります。前の手順で説明したように、--help… # オプションや一括コマンドの使用 ## オプション オプションは、CLIコマンドで使用する追加のオプション機能を提供します。また、オプションはフラグまたは引数とも呼ばれる場合があります。前の手順で説明したように、`--help`はオプションの一例です。 コマンドに有効なすべてのオプションを確認するには、[GitHubリポジトリ](https://github.com/box/boxcli#command-topics)を参照してください。 たとえば、[フォルダの削除](https://github.com/box/boxcli/blob/master/docs/folders.md#box-foldersdelete-id)に関するコマンドのドキュメントを参照すると、`--recursive`や`--force`など、このコマンドで使用するオプションのリストを確認できます。 ## as-userヘッダー [as-userヘッダー](g://authentication/jwt/as-user)を使用するには、コマンドの末尾に`--as-user=USERID`オプションを追加します。 たとえば、次のコマンドでは、ユーザーID 123456のアカウントのルートレベルに`Example_Folder`というフォルダが作成されます。 ``` box folders:create 0 Example_Folder --as-user=123456 ``` as-userヘッダーを使用できるのは、サービスアカウントと管理者のみです。必要なスコープでアプリケーションが承認されていない場合、または別のユーザーのデフォルトのトークンを取得するようCLIを構成した場合は、この呼び出しが失敗する可能性があります。詳細なエラーログを確認するには、コマンドに`-v`または`--verbose`を追加してください。 ## 一括コマンド CSVファイルを使用すると、コマンドを一括して実行できます。このスプレッドシートの各行が個別のAPIコールとして処理されます。 一括コマンドを実行するには、`--bulk-file-path=<PATH_TO_CSV>`オプションを使用します。ここで、`<PATH_TO_CSV>`は、必要な情報が記載されているCSVファイルのローカルパスになります。 たとえば、コマンド`box folders:create --bulk-file-path=pathtoacsv`を使用して、フォルダを作成してみましょう。 Finderウィンドウ/エクスプローラからターミナル/コマンドラインウィンドウにCSVファイルをドラッグすると、パスが自動で入力されます。 CSVファイルの列名を指定する際は、[GitHubリポジトリ](https://github.com/box/boxcli#command-topics)のドキュメントを参照し、引数名を確認するか`--help`オプションを使用します。この場合、列名は`PARENTID`と`NAME`となり、大文字と小文字は区別されません。このフォルダの一括作成コマンドの例では、こちらのCSV[テンプレート](https://github.com/box/boxcli/blob/main/docs/Bulk%20actions/folders/folders-create.csv)を使用することもできます。 以下のコマンドを実行すると、サービスアカウントのフォルダツリーのルートレベル (0) に3つのフォルダが作成されます。 ``` box folders:create --bulk-file-path=/Users/ExampleUser/Desktop/bulkcreatefolders.csv ``` ## オプションを使用した一括コマンド コマンドでオプションを渡すと、そのオプションがCSVファイルの各行に自動的に適用されます。たとえば、`box folders:collaborations:create --bulk-file-path=pathtocsv --role=editor`を実行すると、CSV内の各ユーザーに編集者としてコラボレーションが作成されます。 CSVファイルでオプションを使用することもできます。前の例を基に、コマンド自体で`--role=editor`オプションを使用する代わりに、CSVで`role`という名前の列を指定できます。コマンド自体は`box folders:collaborations:create --bulk-file-path=pathtocsv`となります。 一括コマンドの詳細については、[このドキュメント](g://cli/cli-docs/bulk-commands)を参照してください。 ## まとめ - コマンドや一括コマンドとともにオプションを使用しました。 オプションや一括コマンドの使い方を理解しました **Source:** [https://ja.developer.box.com/guides/cli/quick-start/options-and-bulk-commands/](https://ja.developer.box.com/guides/cli/quick-start/options-and-bulk-commands/) --- ### オフセットベースのページ割り **Type:** guide | **Category:** APIコール | **Section:** Developer Guides オフセットベースのページ割り オフセットベースのページングを使用するAPIは、offsetおよびlimit… # オフセットベースのページ割り オフセットベースのページングを使用するAPIは、`offset`および`limit`クエリパラメータを使用してコレクション内の項目のページ割りを行います。 オフセットベースのページ割りは、項目のリストがあらかじめ決められた固定長の場合によく使用されます。 ## ページング コレクション内のエントリの最初のページを取得するには、APIを`offset`パラメータを指定せずに呼び出すか、`offset`を`0`に設定して呼び出す必要があります。`limit`フィールドは省略可能です。 ``` curl https://api.box.com/2.0/folders/0/items?offset=0&limit=100 \ -H "authorization: Bearer ACCESS_TOKEN" ``` エントリの次のページを取得するには、以前の`offset`値と以前の結果で返された制限の合計 (`previous_offset + previous_limit`) と等しい`offset`パラメータを指定して、APIを呼び出す必要があります。 ``` curl https://api.box.com/2.0/folders/0/items?offset=100&limit=100 \ -H "authorization: Bearer ACCESS_TOKEN" ``` `offset`は、レスポンス配列内のエントリのサイズではなく、以前の`limit`分だけ加算されますので注意してください。これは制限を下回る可能性があるためです。一般的には、レスポンスオブジェクトの`limit`の値を使用して`offset`値を加算することをお勧めします。 次の`offset`値がレスポンスオブジェクト内の`total_count`値を超えている場合、項目の最終ページはリクエスト済みです。この時点では、これ以上取得する項目がありません。 ## オフセットと制限 以下のクエリパラメータは、コレクションのページ割りに使用されます。 | クエリパラメータ | 型 | デフォルト | | | --- | --- | --- | --- | | offset | Integer | 0 | コレクションで最初に返される項目の (ゼロベースの) オフセット。ゼロベースのオフセットでは、0は適切な値です。 | | limit | Integer | APIによって異なる | 返される最大エントリ数。値が最大値を超える場合は、最大値が使用されます。 | オフセットベースのページ割りの最大`offset`は`9999`です。さらに大きいオフセットが必要な場合はマーカーベースのページ割りをお勧めします。 ## コレクション コレクションのページ割りを行うと、APIによって、結果のセットを配列として含むオブジェクトのほか、結果の現在のページに関する情報が返されます。 | フィールド | 型 | | | --- | --- | --- | | entries | Array | このページの項目を含むページ。結果がない場合は空の配列になります。 | | offset | Integer | 結果の現在のページに使用されるオフセット | | limit | Integer | 結果の現在のページに使用される制限。この制限は、このAPIエンドポイントに許可されている最大値を超えない限り、limitクエリパラメータと同じになります。 | | total_count | Integer | コレクション全体の最後の項目のオフセットに1を加算した値。コレクション内の項目の合計数は、total_countよりも少ない場合があります。 | ## エンドポイントの例 以下は、オフセットベースのページ割りをサポートするエンドポイントの例です。 - [フォルダ内の項目を取得](endpoint://get_folders_id_items) - [ファイルのコメントのリストを取得](endpoint://get-files-id-comments) - [ごみ箱にあるすべての項目のリストを取得](endpoint://get-folders-trash-items) **Source:** [https://ja.developer.box.com/guides/api-calls/pagination/offset-based/](https://ja.developer.box.com/guides/api-calls/pagination/offset-based/) --- ### ガイド **Type:** guide | **Category:** ガイド | **Section:** Developer Guides # ガイド **Source:** [https://ja.developer.box.com/guides/](https://ja.developer.box.com/guides/) --- ### カスタムスキル **Type:** guide | **Category:** アプリケーション | **Section:** Developer Guides カスタムスキル カスタムスキル (Box Skill) とは、Boxにアップロードされたファイルに対してカスタマイズした処理を実行する一種のアプリケーションです。スキルは、サードパーティの機械学習サービスを使用して、Box… # カスタムスキル カスタムスキル (Box Skill) とは、Boxにアップロードされたファイルに対してカスタマイズした処理を実行する一種のアプリケーションです。スキルは、サードパーティの機械学習サービスを使用して、Boxにアップロードされたファイルから情報を自動的に抽出し、結果のデータをメタデータとしてファイルに適用しやすくすることを目的としています。 カスタムスキルは、Box管理者がフォルダに対して有効にする必要があります。そうすると、ファイルがフォルダにアップロードされるたびに、イベントがスキルのアプリケーションサーバーに送信されます。その後、このアプリケーションはファイルをダウンロードするか、調査するか、機械学習サービスに渡し、効果的なメタデータをファイルに書き込むことができます。 カスタムスキルの作成を開始する ## 認証方法 カスタムスキルの操作は、各スキルイベントに備わっている事前承認済みのAPI資格情報によって簡素化されます。ただし、このような理由により、カスタムスキルでのAPIアクセスには制限があります。このようなアプリケーションを操作するために認証タイプを選択する必要はありません。 ## 使用するタイミング アプリケーションが以下のような場合に、カスタムスキルを使用すると最も効果的です。 - Boxにアップロードされたファイルにメタデータの追加のみを行う - 新しいファイルをアップロードしない、またはその他のAPIコールを実行しない - 認証を処理する必要なく、機械学習サービスにファイルを渡せるようにする ## ユースケース 以下は、カスタムスキルのユースケースの例です。 画像からナンバープレートの詳細を自動的に抽出し、その詳細をキーワードとしてファイルに書き込むプロセス。 動画内で顔を自動的に検出し、検出した顔が表示された時点のタイムスタンプをタイムラインとしてファイルに書き込むプロセス。 ## 承認 カスタムスキルを使用するには、スキルがトリガーされるフォルダに割り当てておく必要があります。 カスタムスキルの承認方法を確認する **Source:** [https://ja.developer.box.com/guides/applications/app-types/custom-skills/](https://ja.developer.box.com/guides/applications/app-types/custom-skills/) --- ### カスタムスキルの承認 **Type:** guide | **Category:** 承認 | **Section:** Developer Guides カスタムスキルの承認 カスタムスキルは、使用前に、企業のBox管理者がフォルダに対して有効にしておく必要があります。 開発者の場合 開発者の場合は、開発者コンソールでアプリケーションに移動し、管理者に提出するそのアプリケーションのクライアントIDをコピーします。 Box… # カスタムスキルの承認 カスタムスキルは、使用前に、企業のBox管理者がフォルダに対して有効にしておく必要があります。 ## 開発者の場合 開発者の場合は、[開発者コンソール](https://app.box.com/developers/console)でアプリケーションに移動し、管理者に提出するそのアプリケーションのクライアントIDをコピーします。 # Box管理者の確認方法 自分の企業の管理者がわからない場合は、Boxの[アカウント設定][settings]ページに移動し、一番下までスクロールしてください。管理者の連絡先が設定されている場合は、[管理者の連絡先] の下に連絡先情報が表示されています。 ## 管理者の場合 カスタムスキルアプリケーションを有効にするには、[Box管理コンソールの [Skills] セクション](https://app.box.com/master/skills)に移動し、[スキルの追加] リンクをクリックして新しいスキルを追加します。 カスタムスキルアプリケーションのクライアントID (APIキー) を入力します。これは開発者から提出されたクライアントIDです。 [次へ] をクリックし、Box Skillアプリケーションで操作するフォルダを選択します。 ここには2つのオプションがあります。 - [**会社のすべてのコンテンツ**] を選択すると、各ユーザーのルートフォルダでスキルが承認されます。その結果、Box Skillアプリケーションによって処理されているフォルダにすべてのファイルがアップロードされます。 - [**フォルダのリストを選択**] を選択すると、スキルアプリケーションの処理対象となる特定のフォルダまたは一連のフォルダに対してアプリケーションが有効になります。 [Skillを有効化] をクリックし、利用規約と契約に同意します。これで、カスタムスキルが有効になります。選択したフォルダに新しいコンテンツが追加されると、Box[開発者コンソール](https://app.box.com/developers/console)で構成された呼び出しURLにイベントの送信が開始されます。 # 会社あたりSkillアプリケーションは10個まで どのような場合でも、1つの会社につき有効にできるスキルの数は10個という制限があります。会社でさらに多くのスキルを有効にする場合は、Boxの営業担当者にお問い合わせください。 **Source:** [https://ja.developer.box.com/guides/authorization/custom-skill-approval/](https://ja.developer.box.com/guides/authorization/custom-skill-approval/) --- ### カスタムメタデータテンプレートの作成 **Type:** quick-start | **Category:** メタデータ | **Section:** Developer Guides カスタムメタデータテンプレートの作成 会社用のカスタムメタデータテンプレートを作成するには、直接BoxのAPIを使用するかBox SDKのいずれかを使用して新しいテンプレートを作成します。 このcustomerInfoテンプレートでは、… # カスタムメタデータテンプレートの作成 会社用のカスタムメタデータテンプレートを作成するには、[直接BoxのAPI](e://post-metadata-templates-schema)を使用するかBox SDKのいずれかを使用して新しいテンプレートを作成します。 この`customerInfo`テンプレートでは、3つのフィールドを持つテンプレートを作成します。1つ目のフィールドは顧客の`name`を保持するテキストフィールド、2つ目のフィールドは顧客の業種`industry`に使用できる値のドロップダウンリスト、3つ目のフィールドは年間契約額の合計 (`tav`) を表します。 各種フィールドタイプについて確認する このテンプレートを作成するには、フィールドの構成と各フィールドの表示名を渡す必要があります。 ``` curl -X POST https://api.box.com/2.0/metadata_templates/schema \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -H "content-type: application/json" \ -d '{ "scope": "enterprise", "displayName": "Customer Info", "fields": [ { "type": "string", "displayName": "Name" }, { "type": "enum", "displayName": "Industry", "options": [ {"key": "Technology"}, {"key": "Healthcare"}, {"key": "Legal"} ] }, { "type": "float", "displayName": "Total account value", "key": "tav" } ] }' ``` ``` var templateParams = new BoxMetadataTemplate() { DisplayName = "Customer Info", Scope = "enterprise", Fields = new List<BoxMetadataTemplateField>() { new BoxMetadataTemplateField() { Type = "string", DisplayName = "Name" }, new BoxMetadataTemplateField() { Type = "enum", DisplayName = "Industry", Options = new List<BoxMetadataTemplateFieldOption>() { new BoxMetadataTemplateFieldOption() { Key = "Technology" }, new BoxMetadataTemplateFieldOption() { Key = "Healthcare" }, new BoxMetadataTemplateFieldOption() { Key = "Legal" } } }, new BoxMetadataTemplateField() { Type = "float", DisplayName = "Total account value", Key="tav" }, } }; BoxMetadataTemplate template = await client.MetadataManager.CreateMetadataTemplate(templateParams); ``` ``` MetadataTemplate.Field name = new MetadataTemplate.Field(); name.setType("string"); name.setDisplayName("Name"); MetadataTemplate.Field industry = new MetadataTemplate.Field(); industry.setType("enum"); industry.setDisplayName("Industry"); MetadataTemplate.Option technology = new MetadataTemplate.Option(); technology.setKey("Technology"); MetadataTemplate.Option healthcare = new MetadataTemplate.Option(); healthcare.setKey("Healthcare"); MetadataTemplate.Option legal = new MetadataTemplate.Option(); legal.setKey("Legal"); List<MetadataTemplate.Option> options = new ArrayList<MetadataTemplate.Option>(); options.add(technology); options.add(healthcare); options.add(legal); MetadataTemplate.Field tav = new MetadataTemplate.Field(); tav.setType("float"); tav.setDisplayName("Total account value"); tav.setKey("tav"); List<MetadataTemplate.Field> fields = new ArrayList<MetadataTemplate.Field>(); fields.add(name); fields.add(industry); fields.add(tav); MetadataTemplate template = MetadataTemplate.createMetadataTemplate(api, "enterprise", "customerInfo", "Customer Info", false, fields); ``` ``` from boxsdk.object.metadata_template import MetadataField, MetadataFieldType fields = [ MetadataField(MetadataFieldType.STRING, 'Name') MetadataField(MetadataFieldType.ENUM, 'Industry', options=['Technology', 'Healthcare', 'Legal']) ] template = client.create_metadata_template('Customer Info', fields) ``` ``` client.metadata.createTemplate( 'Customer Info', [ { type: 'string', displayName: 'Name' }, { type: 'enum', displayName: 'Industry', options: [ {key: 'Technology'}, {key: 'Healthcare'}, {key: 'Legal'} ] }, { type: 'float', displayName: 'Total account value', key: 'tav' } ] ).then(template => { // ... }); ``` # 管理者権限が必須 メタデータテンプレートの作成は、管理者権限を持つユーザーに制限されています。つまり、管理者、または管理者から**会社のメタデータテンプレートを作成、編集する**権限が付与されている共同管理者だけがウェブアプリまたはAPIを使用してテンプレートを管理できます。 このAPIにより、新しく作成されたメタデータテンプレートが返されます。 ``` { "id": "100ac693-a468-4b37-9535-05984b804dc2", "type": "metadata_template", "templateKey": "customerInfo", "scope": "enterprise_34567", "displayName": "Customer Info", "hidden": false, "copyInstanceOnItemCopy": false, "fields": [ { "id": "5c6a5906-003b-4654-9deb-472583fc2930", "type": "string", "key": "name", "displayName": "Name", "hidden": false }, { "id": "cf3eb5b8-52ef-456c-b175-44354a27e289", "type": "enum", "key": "industry", "displayName": "Industry", "options": [ {"key": "Technology"}, {"key": "Healthcare"}, {"key": "Legal"} ], "hidden": false }, { "id": "5c6a5906-4654-9deb-003b-472583fc2930", "type": "float", "key": "tav", "displayName": "Total account value", "hidden": false } ] } ``` # テンプレートキー テンプレートキーは、明示的に設定しませんでしたが、`displayName`値から自動的に派生します。この場合、`templateKey`は`customerInfo`になります。 カスタムテンプレートを作成しました **Source:** [https://ja.developer.box.com/guides/metadata/quick-start/create-template/](https://ja.developer.box.com/guides/metadata/quick-start/create-template/) --- ### クエリの作成 **Type:** guide | **Category:** メタデータ | **Section:** Developer Guides クエリの作成 メタデータクエリとは、/metadata_queries/execute_readエンドポイントに対するPOSTリクエストで、その本文にはメタデータクエリのすべてのパーツが含まれています。ここで最も重要なのは、検索対象のテンプレートを指定するfrom… # クエリの作成 メタデータクエリとは、`/metadata_queries/execute_read`エンドポイントに対する`POST`リクエストで、その本文にはメタデータクエリのすべてのパーツが含まれています。ここで最も重要なのは、検索対象のテンプレートを指定する`from`属性、検索するフォルダを指定する`ancestor_folder_id`、検索に使用するすべてのテンプレートフィールドを決定する`query`です。 ``` curl -X POST https://api.box.com/2.0/metadata_queries/execute_read \ -H 'Authorization: Bearer <ACCESS_TOKEN>' \ -H 'Content-Type: application/json' \ -d '{ "from": "enterprise_123456.contractTemplate", "query": "amount >= :value", "query_params": { "value": 100 }, "fields": [ "name", "metadata.enterprise_123456.contractTemplate.customerName", "metadata.enterprise_123456.contractTemplate.amount" ], "ancestor_folder_id": "5555", "order_by": [ { "field_key": "amount", "direction": "asc" } ], "limit": 100 }' ``` 使用可能なすべてのパラメータの詳細については、Boxの他の[メタデータクエリガイド](g://metadata/queries)または関連する[エンドポイントリファレンス](e://post_metadata_queries_execute_read)を参照してください。 クエリ構文の詳細を確認する ## レスポンス クエリに一致するファイルまたはフォルダがあれば、APIレスポンスで返されます。レスポンスの本文はJSONオブジェクトで、各ファイルまたはフォルダの`entries`のリストと、次の検索結果ページを見つけるための`next_marker`値が含まれています。各エントリは、クエリに一致したファイルまたはフォルダを表し、`field`パラメータで明示的にリクエストされたフィールドのみが返されます。 ``` { "entries": [ { "type": "file", "id": "1617554169109", "name": "My Contract.docx", "metadata": { "enterprise_123456": { "contractTemplate": { "$parent": "file_161753469109", "$scope": "enterprise_123456", "$template": "contractTemplate", "$version": 0, "customerName": "Phoenix Corp", "amount": 100 } } } } ], "limit": 20, "next_marker": "AAAAAmVYB1FWec8GH6yWu2nwmanfMh07IyYInaa7DZDYjgO1H4KoLW29vPlLY173OKsci6h6xGh61gG73gnaxoS+o0BbI1/h6le6cikjlupVhASwJ2Cj0tOD9wlnrUMHHw3/ISf+uuACzrOMhN6d5fYrbidPzS6MdhJOejuYlvsg4tcBYzjauP3+VU51p77HFAIuObnJT0ff" } ``` このAPIはデフォルトで、ページあたり`20`個の項目を返しますが、マーカーベースのページ割りを使用すると、さらに多くの項目をリクエストできます。 ページ割りクエリの結果の詳細を確認する **Source:** [https://ja.developer.box.com/guides/metadata/queries/create/](https://ja.developer.box.com/guides/metadata/queries/create/) --- ### クエリ構文 **Type:** guide | **Category:** メタデータ | **Section:** Developer Guides クエリ構文 メタデータクエリAPIのクエリ構文はSQLデータベースのクエリ構文と似ています。契約金額が100ドルを超える契約メタデータテンプレートに一致するすべてのファイルとフォルダに対してクエリを実行するには、以下のメタデータクエリを作成します。 この場合、from… # クエリ構文 メタデータクエリAPIのクエリ構文はSQLデータベースのクエリ構文と似ています。契約金額が100ドルを超える契約メタデータテンプレートに一致するすべてのファイルとフォルダに対してクエリを実行するには、以下のメタデータクエリを作成します。 ``` { "from": "enterprise_123456.contractTemplate", "query": "amount >= :value", "query_params": { "value": 100 }, "fields": [ "name", "metadata.enterprise_123456.contractTemplate.amount" ], "ancestor_folder_id": "5555" } ``` この場合、`from`値はメタデータテンプレートの`scope`と`templateKey`を表し、`ancestor_folder_id`はサブフォルダを含む検索範囲となるフォルダIDを表します。 ## fieldsパラメータ デフォルトでは、このAPIで返されるのは、`id`、`type`、および`etag`の値を含む、ファイルまたはフォルダの基本レプリゼンテーションのみです。その他のデータをリクエストするには、`fields`パラメータを使用すると、追加のフィールドや、その項目に関連付けられたメタデータに対してクエリを実行できます。 例: - `created_by`では、項目を作成したユーザーの詳細がレスポンスに追加されます。 - `metadata.<scope>.<templateKey>`では、`scope`と`templateKey`によって識別されたメタデータインスタンスの基本レプリゼンテーションが返されます。 - `metadata.<scope>.<templateKey>.<field>`では、`scope`と`templateKey`によって識別されたメタデータインスタンスの基本レプリゼンテーションのすべてのフィールドに加え、`field`の名前によって指定されたフィールドが返されます。同じ`scope`および`templateKey`の複数のフィールドを定義できます。 ## queryパラメータ `query`パラメータは、選択したメタデータインスタンスに対して実行する、SQLに似たクエリを表します。このパラメータは省略可能で、このパラメータを指定しない場合、APIはこのテンプレートに対してすべてのファイルとフォルダを返します。 左側の各フィールド名 (`amount`など) は、関連付けられたメタデータテンプレートのフィールドの`key`に一致する必要があります。つまり、関連付けられたメタデータインスタンスに実際に存在するフィールドだけを検索できます。その他のフィールド名を指定するとエラーが発生し、エラーが返されます。 ### query_paramsパラメータ クエリ文字列への動的な値の埋め込みをわかりやすくするために、`:value`のように、コロン構文を使用して引数を定義できます。たとえば、次のように指定された各引数では、`query_params`オブジェクトにそのキーを使用した後続の値が必要です。 ``` { ..., "query": "amount >= :amount AND country = :country", "query_params": { "amount": 100, "country": "United States" }, ... } ``` ### 論理演算子 クエリでは、以下の論理演算子がサポートされます。 | 演算子 | | | --- | --- | | AND | ANDで区切られたすべての条件がTRUEの場合に一致となります。 | | OR | ORで区切られた条件のいずれかがTRUEの場合に一致となります。 | | NOT | 先行する条件がTRUEでない場合に一致となります。 | | LIKE | テンプレートフィールドの値がパターンと一致する場合に一致となります。文字列値のみに対応します。詳細については、パターン一致を参照してください。その他の制限については以下を参照してください。 | | NOT LIKE | テンプレートフィールドの値がパターンと一致しない場合に一致となります。文字列値のみに対応します。詳細については、パターン一致を参照してください。その他の制限については以下を参照してください。 | | ILIKE | LIKEと同じですが、大文字と小文字が区別されません。その他の制限については以下を参照してください。 | | NOT ILIKE | NOT LIKEと同じですが、大文字と小文字が区別されません。その他の制限については以下を参照してください。 | | IN | テンプレートフィールドの値が指定されたリストの任意の値と等しい場合に一致となります。amount IN (:arg1, :arg2, :arg3)などの各リスト項目には、明示的に定義されたquery_params引数を使用します。仕様では、IN演算子はメタデータクエリの複数選択フィールドでサポートされていないため、400エラーが返されます。 | | NOT IN | INに似ていますが、テンプレートフィールドの値は、リストに指定されたどの引数にも一致しません。 | | IS NULL | テンプレートフィールドの値がnullの場合に一致となります。 | | IS NOT NULL | テンプレートフィールドの値がnullでない場合に一致となります。 | `ILIKE`演算子を使用した場合を除き、`string`または`enum`フィールドでの一致は、どれも大文字小文字が区別されます。 ### 比較演算子 クエリでは、以下の比較演算子がサポートされます。 | 演算子 | | | --- | --- | | = | テンプレートフィールドの値が、指定した値と等しいことを表します。 | | > | テンプレートフィールドの値が、指定した値よりも大きいことを表します。 | | < | テンプレートフィールドの値が、指定した値よりも小さいことを表します。 | | >= | テンプレートフィールドの値が、指定した値以上であることを表します。 | | <= | テンプレートフィールドの値が、指定した値以下であることを表します。 | | <> | テンプレートフィールドの値が、指定した値と等しくないことを表します。 | ビット単位演算子および算術演算子は、メタデータクエリAPIではサポートされていません。 ### パターン一致 `LIKE`、`NOT LIKE`、`ILIKE`および`NOT ILIKE`演算子は、パターンに対して文字列が一致するかどうかを照合します。このパターンでは、以下の予約文字をサポートします。 - `%` パーセント記号は0個、1個または複数個の文字を表します。たとえば、`%Contract`の場合、`Contract`、`Sales Contract`は一致しますが、`Contract (Sales)`は一致しません。 - `_` アンダースコアは1文字を表します。たとえば、`Bo_`の場合、`Box`、`Bot`は一致しますが、`Bots`は一致しません。 上記の文字はどちらも、他の文字の前後または文字の間に使用できます。パターンには、複数の予約文字を含めることができます。たとえば、`Box% (____)`の場合は`Box Contract (2020)`が一致します。 クエリの例は次のようになります。`%`でラップされた文字列は`query`属性ではなく`query_params`のリストに含まれていることに注意してください。 ``` { ..., "query": "country ILIKE :country", "query_params": { "country": "%United%" }, ... } ``` `%`または`_`文字を、その文字として照合する必要がある場合は、エスケープするためにバックスラッシュ文字`\`を使用できます。たとえば、`20\%`の場合は、リテラル値`20%`が一致します。 **Source:** [https://ja.developer.box.com/guides/metadata/queries/syntax/](https://ja.developer.box.com/guides/metadata/queries/syntax/) --- ### クエリ演算子 **Type:** guide | **Category:** 検索 | **Section:** Developer Guides クエリ演算子 GET /search APIでは、APIによって返された結果を絞り込むのに役立つさまざまなクエリ演算子がサポートされています。 これらの演算はすべて、検索の作成時にquery… # クエリ演算子 [`GET /search`](e://get_search) APIでは、APIによって返された結果を絞り込むのに役立つさまざまなクエリ演算子がサポートされています。 これらの演算はすべて、検索の作成時に`query`パラメータに渡されます。 ## 完全一致に使用する"" クエリを二重引用符 (`""`) で囲むと、APIによって完全一致のみが返されます。完全一致検索では、特定の文字の並びに基づいた検索結果は返されません。代わりに、フレーズ (つまり、単語の並び) に基づいた一致が返されます。 たとえば、`"Blue-Box"`を検索すると、`"blue.box"`、`"Blue Box"`、`"Blue-Box"`などの並びを含む、検索結果が返されます。つまり、`Blue`および`Box`という単語が指定した順序で連続して含まれている項目です。 ## 複数用語の一致に使用するAND `AND`演算子を使用すると、検索では、演算子の左側と右側にある検索語句を両方とも含む項目が返されます。 たとえば、`marketing AND BoxWorks`を検索すると、`marketing`と`BoxWorks`の両方が任意の順番でテキストに含まれている項目が返されます。テキストに`BoxWorks`のみが含まれる結果は返されません。 ## いずれかの検索語句の一致に使用するOR `OR`演算子を使用すると、検索では、演算子の左側と右側にある検索語句のいずれかを含む項目が返されます。 たとえば、`marketing OR BoxWorks`を検索すると、`marketing`と`BoxWorks`のいずれかがテキストに含まれている結果が返されます。サポートされている別のブール条件が使用されている場合を除き、複数語のクエリは暗黙的に`OR`として解釈されるため、この演算子の使用は必須ではありません。 ## 検索語句の除外に使用するNOT `NOT`演算子を使用すると、検索では、演算子に続く用語を含まない項目が返されます。 たとえば、`marketing AND NOT BoxWorks`を検索すると、テキストに`marketing`のみが含まれている結果が返されます。`BoxWorks`が含まれる結果は省略されます。 小文字の演算子 (`and`、`or`および`not`) および大文字と小文字を組み合わせた演算子 (`And`、`Or`および`Not`) はサポートされていないことに注意してください。 Boxコミュニティの記事で、Boxでの検索に関する最新情報を確認する **Source:** [https://ja.developer.box.com/guides/search/query-operators/](https://ja.developer.box.com/guides/search/query-operators/) --- ### クライアント資格情報許可 **Type:** guide | **Category:** 認証 | **Section:** Developer Guides クライアント資格情報許可 サーバー認証を利用し、クライアントIDとクライアントシークレットを使用してアプリケーションのIDを確認する場合は、以下の手順に従います。 前提条件 Box開発者コンソールでサーバー認証 (クライアント資格情報許可使用) を使用するPlatform… # クライアント資格情報許可 サーバー認証を利用し、クライアントIDとクライアントシークレットを使用してアプリケーションのIDを確認する場合は、以下の手順に従います。 ## 前提条件 - Box[開発者コンソール](https://app.box.com/developers/console)でサーバー認証 (クライアント資格情報許可使用) を使用するPlatformアプリケーション - [構成] タブからアプリケーションのクライアントシークレットを表示およびコピーするために、Boxアカウントで[2要素認証](https://support.box.com/hc/ja/articles/360043697154-%E3%82%A2%E3%82%AB%E3%82%A6%E3%83%B3%E3%83%88%E3%81%AE%E5%A4%9A%E8%A6%81%E7%B4%A0%E8%AA%8D%E8%A8%BC%E3%81%AE%E8%A8%AD%E5%AE%9A)が有効になっていること - Box管理コンソールでアプリケーションが[承認](g://authorization)されていること クライアントシークレットは機密情報であり、保護する必要があります。アクセストークンの取得時にBoxがアプリケーションのIDを安全に確認するために使用されるため、クライアントシークレットを自由に配布するべきではありません。配布方法には、メール、公開フォーラム、コードリポジトリ、分散されたネイティブアプリケーション、クライアント側のコードなどがあります。さらにセキュリティメカニズムを追加する場合は、Boxの標準的なJWTアプリケーションを使用することをお勧めします。 ## 利用方法 APIコールを実行して[アクセストークン](e://post-oauth2-token)を取得する際は、リクエスト本文にクライアントIDとクライアントシークレットを含める必要があります。`grant_type`を`client_credentials`に設定します。 アプリケーションの[サービスアカウント](page://platform/user-types/#service-account)として認証する場合は、以下のようにします。 - `box_subject_type`を`enterprise`に設定する - `box_subject_id`をEnterprise IDに設定する 管理者または管理対象ユーザーとして認証する場合は、以下のようにします。 - `box_subject_type`を`user`に設定する - `box_subject_id`をユーザーIDに設定する - Box[開発者コンソール](https://app.box.com/developers/console)で [**アプリ + Enterpriseアクセス**] および [**ユーザーアクセストークンを生成する**] を有効にする 任意のアプリケーションユーザーとして認証する場合は、以下のようにします。 - `box_subject_type`を`user`に設定する - `box_subject_id`をユーザーIDに設定する - Box[開発者コンソール](https://app.box.com/developers/console)で [**ユーザーアクセストークンを生成する**] を有効にする ## 一般的なエラー ### Grant credentials are invalid (許可の資格情報が無効です) 認証中に、次のエラーが表示される場合があります。 ``` Grant credentials are invalid [400 Bad Request] invalid_grant - Grant credentials are invalid ``` このエラーは次のいずれかを示します。 渡されたクライアントIDとクライアントシークレットが正しくないか、同じアプリケーションのものではない。 選択した[アプリケーションアクセス](g://authentication/client-credentials/client-credentials-setup/#application-access)に基づいて`box_subject_id`を使用できない。 [アプリアクセスのみ] が指定されているCCGアプリは、そのサービスアカウントとして認証するために送信時に`box_subject_type`を`enterprise`に設定できますが、管理対象ユーザーまたは管理者として認証できません。 `box_subject_type`を`user`に設定して使用するには、[**構成**] タブの [**高度な機能**] セクションでユーザーアクセストークンを生成するようアプリケーションを構成する必要があります。 アプリの設定に変更を加えたら、忘れずに管理コンソールでアプリケーションを[再承認](g://authorization/custom-app-approval#re-authorization-on-changes)してください。 - アプリケーションがBox管理コンソールで承認されていない **Source:** [https://ja.developer.box.com/guides/authentication/client-credentials/](https://ja.developer.box.com/guides/authentication/client-credentials/) --- ### クライアント資格情報許可を使用した設定 **Type:** guide | **Category:** 認証 | **Section:** Developer Guides クライアント資格情報許可を使用した設定 前提条件 サーバー側認証を使用してPlatformアプリを設定するには、Box Enterpriseアカウントから開発者コンソールにアクセスできることを確認する必要があります。または、Developer… # クライアント資格情報許可を使用した設定 ## 前提条件 サーバー側認証を使用してPlatformアプリを設定するには、Box Enterpriseアカウントから[開発者コンソール](https://app.box.com/developers/console)にアクセスできることを確認する必要があります。または、[Developerアカウント](https://account.box.com/signup/n/developer)にサインアップすることもできます。 ## アプリの作成手順 ### 開発者コンソールへの移動 Boxにログインし、[開発者コンソール](https://app.box.com/developers/console)に移動して、[**Platformアプリの作成**] を選択します。 ### アプリケーションの種類の選択 アプリケーションの種類のリストから [**Platformアプリ**] を選択します。次の手順を促すウィンドウが表示されます。 ### アプリケーションの基本情報の指定 アプリを説明するために、アプリの名前と説明を指定します。アプリの目的を選択するには、ドロップダウンリストを使用します。選択したオプションに応じて、さらに詳細を指定することが必要になる場合があります。 | 目的 | 詳細 | | --- | --- | | [自動化]、[カスタムポータル] | アプリの作成者 (お客様またはパートナー) を指定します。 | | 統合 | 統合のカテゴリ、外部システム名のほか、アプリの作成者 (お客様またはパートナー) を指定します。 | | [その他] | アプリの目的と、アプリの作成者 (お客様またはパートナー) を指定します。 | ### アプリケーションの認証の選択 クライアントIDとクライアントシークレットを使用してアプリケーションIDを確認する場合は [**サーバー認証 (クライアント資格情報許可)**] を選択し、[**アプリの作成**] で確定します。 選択すると、新しいアプリケーションを作成しない限り、別の認証方法に変更できません。 ## アプリ承認 アプリケーションを使用するには、Box管理者がBox管理コンソールでそのアプリケーションを承認しておく必要があります。 [開発者コンソール](https://app.box.com/developers/console)で、目的のアプリケーションの [**承認**] タブに移動します。 [**確認して送信**] をクリックして、承認を得るためにBox Enterprise管理者にメールを送信します。このプロセスの詳細については、[承認ガイド](g://authorization)を参照してください。 Platformアプリケーションの承認方法を確認する ## 基本的な構成 ### アプリケーションアクセス アプリケーションのアクセスレベルにより、アプリからアクセスできるユーザーおよびコンテンツが決まります。デフォルトでは、アプリケーションで問題なく操作できるのは、その[サービスアカウント](page://platform/user-types/#service-account)とすべての[App User](page://platform/user-types)のコンテンツのみです。企業の既存の管理対象ユーザーにもアクセスするには、[開発者コンソール](https://app.box.com/developers/console)の [**構成**] タブから [**アプリアクセスレベル**] に移動し、[**アプリ + Enterpriseアクセス**] に設定します。 ### アプリケーションスコープ アプリケーションのスコープにより、アプリケーションが呼び出すことができるエンドポイントとリソースが決まります。各オプションの詳細については、[スコープのガイド](g://api-calls/permissions-and-errors/scopes)を参照してください。 ### CORSドメイン アプリケーションがJavaScriptでフロントエンドのブラウザコードからAPIコールを実行する場合は、[クロスオリジンリソース共有](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing) (CORS) のために、これらの呼び出しの実行元となるドメインを許可リストに追加する必要があります。すべてのリクエストがサーバー側のコードから発行される場合は、このセクションをスキップできます。 許可リストに完全なURIを追加するには、[開発者コンソール](https://app.box.com/developers/console)の [**構成**] タブの下部にある [**CORSドメイン**] セクションに移動します。 ## SDKとクライアント資格情報許可の使用 各SDKのクライアント資格情報許可の詳細については、以下を参照してください。 [.Net](https://github.com/box/box-windows-sdk-v2/blob/main/docs/authentication.md#server-auth-with-ccg) [Java](https://github.com/box/box-java-sdk/blob/main/doc/authentication.md#client-credentials-grant) [Python](https://github.com/box/box-python-sdk/blob/main/docs/usage/authentication.md#client-credentials-grant) [Node](https://github.com/box/box-node-sdk/blob/main/docs/authentication.md#client-credentials-grant-authentication) [IOS](https://github.com/box/box-ios-sdk/blob/main/docs/usage/authentication.md#client-credentials-grant) **Source:** [https://ja.developer.box.com/guides/authentication/client-credentials/client-credentials-setup/](https://ja.developer.box.com/guides/authentication/client-credentials/client-credentials-setup/) --- ### グループとコラボレーションの管理 **Type:** guide | **Category:** CLI | **Section:** Developer Guides グループとコラボレーションの管理 スクリプト構造 このスクリプトでは、Box CLIを使用して、グループの作成や更新、グループへのユーザーの追加、グループとフォルダの間のコラボレーションの作成を行います。このスクリプトは、… # グループとコラボレーションの管理 ## スクリプト構造 このスクリプトでは、Box CLIを使用して、グループの作成や更新、グループへのユーザーの追加、グループとフォルダの間のコラボレーションの作成を行います。このスクリプトは、2つのパートから構成されています (以下のセクションで詳しく説明します)。両方のパートを実行することも、オプションのフラグを使用して実行するパートを決めることもできます。 ### グループの作成または更新 このスクリプトでは、`UserGroupAdditionPath`パラメータに指定した`.csv`ファイルを使用します。このファイルには、グループ名とユーザーのメールアドレスが記載されています。このファイルを作成する際には、複数のユーザーに同じグループ名を使用することも、1人のユーザーを複数のグループに割り当てることもできます。以下に例を示します。 | GroupName | UserEmail | | --- | --- | | Group1 | ManagedUser1@test.com | | Group1 | ManagedUser2@test.com | | Group2 | ManagedUser3@test.com | | Group3 | ManagedUser1@test.com | グループが存在しない場合は、スクリプトによってそのグループが作成されます。グループが存在する場合は、指定したデータに基づいてエントリが更新されます。 ### コラボレーションの作成または更新 このスクリプトでは、`CollaborationsCreationPath`パラメータに指定した`.csv`ファイルを使用します。このファイルには、グループ名、フォルダID、コラボレーションロールが記載されています。 スクリプトでは、行ごとに、グループが存在するかどうか、そのグループがすでに対応するフォルダにコラボレータとして追加されていないかどうかを確認します。以下に例を示します。 | GroupName | FolderId | CollaborationRole | | --- | --- | --- | | Group1 | 1111111 | editor | | Group2 | 1111111 | viewer_uploader | | Group2 | 2222222 | viewer | | Group3 | 1111111 | viewer_uploader | 両方の条件を満たしている場合、`CollaborationRole`列で定義されたロールを使用してグループがフォルダに割り当てられます。また、グループはすでに存在していても、`CollaborationRole`を変更した場合、スクリプトの実行時に`-UpdateExistingCollabs`フラグを渡すと、コラボレーションロールが更新されます。 ## 前提条件 ### Windows [.NET Core](https://dotnet.microsoft.com/download)の最新バージョンのインストール ### macOSおよびLinux [PowerShell](https://docs.microsoft.com/en-us/powershell/scripting/install/installing-powershell?view=powershell-7.2)をインストールします。`pwsh`コマンドを実行して、インストール結果をテストします。 ``` pwsh ``` どのディレクトリでこのコマンドを実行するかに応じて、出力が異なる場合があります。以下に例を示します。 ``` PowerShell 7.2.5 Copyright (c) Microsoft Corporation. https://aka.ms/powershell Type 'help' to get help. PS /Users/user/repos/boxcli/examples> ``` 問題が発生する場合は、[.NET Core](https://dotnet.microsoft.com/download)と[PowerShell](https://docs.microsoft.com/en-us/powershell/scripting/install/installing-powershell?view=powershell-7.2)の両方をインストールしたかどうか確認してください。 ### Box CLI スクリプトを使用するには、Box CLIをインストールし、構成する必要があります。これは、[クイックスタートガイド](g://cli/quick-start/create-oauth-app)の手順を実行することで行うことができます。ログインに使用するユーザーは、Boxのメイン管理者または共同管理者である必要があります。 ## スクリプトの構成 1. `boxcli` GitHubリポジトリを複製してこの例のフォルダにcdコマンドで移動するか、[`examples`](https://github.com/box/boxcli/tree/main/examples)ディレクトリからファイルをダウンロードします。 ``` git clone https://github.com/box/boxcli.git boxcli cd boxcli/examples/Mass\ Groups\ \&\ Collaborations\ Update/ ``` 1. グループとユーザーのメールアドレスのリストが含まれる`.csv`ファイルのパスを設定します。 ``` $UserGroupAdditionPath = "./User_Group_Addition.csv" ``` ``` * `UserEmail` is the primary email address for the user in Box. * `GroupName` is the name of the group. ``` 1. グループとユーザーのメールアドレスのリストが含まれる`.csv`ファイルに独自のパスを設定します。 ``` $CollaborationsCreationPath = "./Collaborations_Creation.csv" ``` ``` * `GroupName` is name of the group the script will add as a collaborator to the folder. * `FolderId` is the folder ID the collaborator will be added to. * `CollaborationRole` is the name of the role used when creating a collaboration. You can configure the available roles by setting the `AvailableCollaborationRoles` parameter: ``` ``` $AvailableCollaborationRoles = @("editor", "viewer", "previewer", "uploader", "previewer_uploader", "viewer_uploader", "co-owner") ``` ## スクリプトの実行 1. PowerShellコマンドを実行します。 ``` pwsh ``` 1. スクリプトを実行します。 ``` ./Mass_Groups_Collabs_Update.ps1 ``` ### オプションのフラグ フラグを使用すると、スクリプトの特定の部分を実行またはスキップできます。 - グループがすでに特定のフォルダのコラボレータとして設定されているものの、その役割が.`csv`ファイルで定義されたものとは異なる場合は、スクリプトによってそのことが通知されます。スクリプトによって既存のコラボレーションが変更されることはありません。`.csv`ファイルで定義された役割で既存のコラボレーションを更新するには、スクリプトを実行する際に追加の`-UpdateExistingCollabs`フラグを設定します。 ``` Mass_Groups_Collabs_Update.ps1 -UpdateExistingCollabs ``` - コラボレーションを作成せずにグループを更新するには、スクリプトの実行時に`-SkipCollabsCreation`ブール値フラグを追加します。 ``` Mass_Groups_Collabs_Update.ps1 -SkipCollabsCreation ``` - グループを更新せずにコラボレーションを作成するには、スクリプトの実行時に`-SkipGroupsUpdate`ブール値フラグを追加します。 ``` Mass_Groups_Collabs_Update.ps1 -SkipGroupsUpdate ``` ## ログ ログは、メインフォルダ内の`logs`フォルダに格納されます。以下のログファイルにアクセスできます。 - `Mass_Groups_Collabs_Update_all.txt`: すべてのログエントリが含まれています。 - `Mass_Groups_Collabs_Update_errors.txt`: エラーのみが含まれています。 **Source:** [https://ja.developer.box.com/guides/cli/scripts/manage-groups-collaborations/](https://ja.developer.box.com/guides/cli/scripts/manage-groups-collaborations/) --- ### グループとの共有 **Type:** guide | **Category:** コラボレーション | **Section:** Developer Guides グループとの共有 ファイルやフォルダをユーザーのグループと共有するには、グループID、ファイルまたはフォルダのIDに加え、グループがファイルまたはフォルダにアクセスする際に必要なロールまたは権限を使用してコラボレーションを作成します。 コラボレーションロールはeditor… # グループとの共有 ファイルやフォルダをユーザーのグループと共有するには、グループID、ファイルまたはフォルダのIDに加え、グループがファイルまたはフォルダにアクセスする際に必要なロールまたは権限を使用してコラボレーションを作成します。 コラボレーションロールは`editor`、`viewer`、`previewer`、`uploader`、`previewer uploader`、`viewer uploader`、`co-owner`、または`owner`です。各ロールについての詳しい説明は、Boxの[サポートドキュメント](https://support.box.com/hc/ja/articles/360044196413-%E3%82%B3%E3%83%A9%E3%83%9C%E3%83%AC%E3%83%BC%E3%82%BF%E3%81%AE%E6%A8%A9%E9%99%90%E3%83%AC%E3%83%99%E3%83%AB%E3%81%AB%E3%81%A4%E3%81%84%E3%81%A6)を参照してください。 ## ネストされたオブジェクト コラボレーションの作成時には、リクエスト本文に`accessible_by`と`item`という2つのネストされたオブジェクトを使用します。 `accessible_by`オブジェクトは、この項目の共有相手を指定し、グループ`id`と`type`を含みます。`type`フィールドは常に`group`に設定する必要があります。 `item`オブジェクトは、共有する項目を指定します。このオブジェクトには、`file`または`folder`として設定する必要がある`type`フィールドと、そのファイルまたはフォルダの`id`フィールドがあります。 **Source:** [https://ja.developer.box.com/guides/collaborations/groups/](https://ja.developer.box.com/guides/collaborations/groups/) --- ### クロスオリジンリソース共有 (CORS) **Type:** guide | **Category:** セキュリティ | **Section:** Developer Guides クロスオリジンリソース共有 (CORS) クロスオリジンリソース共有 (CORS) は、悪意のあるウェブサイトが明示的な権限を持たずに他のサイトのデータ (Box APIなど) にアクセスするのを防ぐために、ウェブブラウザで利用されているセキュリティメカニズムです。 CORS… # クロスオリジンリソース共有 (CORS) [クロスオリジンリソース共有 (CORS)](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) は、悪意のあるウェブサイトが明示的な権限を持たずに他のサイトのデータ (Box APIなど) にアクセスするのを防ぐために、ウェブブラウザで利用されているセキュリティメカニズムです。 CORSは、ウェブブラウザを使用してウェブページから送信されるBox APIリクエストのみに適用され、そのブラウザによって渡される`HTTP Origin`ヘッダーを利用します。サーバー側環境では機能しません。 CORSの全般的な情報の詳細については、MDN Web Docsを参照してください。 ## CORSのしくみ あるドメイン (`company.com`など) のブラウザで、別のドメイン (`box.com`) から画像、ファイル、またはAPIリソースを取得しようとする場合、適切なCORSヘッダーが存在しない限り、そのウェブブラウザにより、これらのアセットへのアクセスが阻止されます。 ブラウザからクロスオリジンリクエストを送信すると、そのリクエストを送信するサイトのドメインを含む`Origin`リクエストヘッダーがリクエストとともに渡されます。このヘッダーは変更できないため、ウェブブラウザのセキュリティにとって重要な部分となります。 デフォルトでは、`Access-Control-Allow-Origin`レスポンスヘッダーが存在しない場合、ブラウザは、別のドメインから読み込まれたアセットを受け入れることはありません。Boxなどのサーバーは、そのサーバー上のリソースへのアクセスが許可されたドメインのリストを明示的に取得することも、APIへのアクセスを任意のドメインに許可するために`*`値を返すこともできます。 ## BoxでのCORSの使用方法 Boxは、`Origin`リクエストヘッダーと`Access-Control-Allow-Origin`レスポンスヘッダーを使用して、開発者が定義したCORSルールを適用します。 ### Originヘッダーの検証 Box APIは、アプリケーション開発者が設定した、許可されたドメインのリストに対して`Origin`リクエストヘッダーを検証します。許可されたオリジンは複数設定でき、リストにないオリジンは`HTTP 403`エラーで返されます。 ``` { "type": "error", "status": 403, "code": "cors_origin_not_whitelisted", "context_info": { "origin": "https://company.com" }, "help_url": "https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/", "message": "Access denied - Did you forget to safelist your origin in the CORS config of your app?", "request_id": "4dsdfsa832213" } ``` オリジンが設定されていない場合は、このアプリケーションのBox APIに対するすべてのリクエストでエラーが返されます。 ### Access-Control-Allow-Originレスポンスヘッダー Box APIは、`Origin`ヘッダーを検証した後、リクエストされたデータのほか、値`*`が設定された`Origin`レスポンスヘッダーを返します。 ``` HTTP/1.1 200 OK Date: Wed, 23 Sep 2020 14:07:29 GMT Content-Type: application/json Transfer-Encoding: chunked Connection: keep-alive Strict-Transport-Security: max-age=31536000 Cache-Control: no-cache, no-store Access-Control-Allow-Origin: * Vary: Origin BOX-REQUEST-ID: 032cfb446dae4fd0b4c2bff80a1a97ba7 ``` このヘッダーを返すことにより、Box APIはウェブブラウザに対して、データをリクエストしたサイトでレスポンスを使用できることを通知します。 ## ドメインのCORSの有効化 アプリケーションが動作するドメインでCORSを有効にするには、開発者コンソールに移動して、アプリケーションを選択し、[**構成**] パネルの一番の下までスクロールして [**CORSドメイン**] の設定を見つけます。 アプリケーションでのAPIリクエストの発信元になると予想されるすべてのオリジンをコンマ区切りリストとして追加します。ドメインにはスキーマ (`http`または`https`) が必要で、`*.example.com`のようにサブドメインのワイルドカードを含めることができます。 サイトが非標準のポート上で動作する場合は、サイトにそのポートも含める必要があります。これは、特に、`localhost`または`127.0.0.1`で動作しているサイトに当てはまります。 オリジンのリストの例は、次のようになります。 ``` https://company.com,https://*.internal.company.com,http://localhost:3000 ``` ## CORSのデバッグ Box APIに対してAPIコールを実行した場合に発生する可能性のあるCORSエラーはいくつかあります。 ### HTTP 403 - 許可済みオリジンが定義されていない オリジンのリストを指定した後でも、このエラーが発生する場合があります。多くの場合、指定したオリジンに誤字があることが原因です。 1. **オリジンを確認する** - 開発者コンソールに戻り、オリジンがAPIコールの実行元のサイトをマップしていることを確認します。オリジンにはスキーム (`http(s)`) が含まれても、パスまたは末尾の`/`は含まれないことに注意してください。ブラウザのデバッグコンソールを使用してページを調査し、`Origin`リクエストヘッダーの値を確認することをお勧めします。この値は、開発者コンソールで指定された値のいずれかと一致する必要があります。 2. **資格情報を確認する** - このエラーのもう1つの理由として、オリジンを設定したアプリケーションとは別のアプリケーションとして認証している可能性が考えられます。資格情報が、使用するアプリケーションのものと一致することを確認してください。サーバー側スクリプトから呼び出しを実行して、APIコールが動作するかどうかを検証することをお勧めします。 ### Cross-Origin Request Blocked 場合によっては、CORSに言及するJavaScriptエラーが発生します。 ``` Cross-Origin Request Blocked: The Same Origin Policy disallows reading the remote resource at https://api.box.com/2.0/users/me. (Reason: CORS request did not succeed). ``` 多くの場合、このエラーはCORSとはほとんど関係がありません。代わりに、以下を確認することをお勧めします。 1. **認証ヘッダーを確認する** - 認証ヘッダーが指定されていないか、またはその形式が正しくない場合、このAPIでは、必要な`Access-Control-Allow-Origin`ヘッダーなしで一般的なエラーが返されます。その結果、ブラウザで前述のエラーが発生します。必ず`Authorization: Bearer ...`ヘッダーを使用してアクセストークンを渡してください。 2. **VPNやプロキシなどでブロックされたリクエストがないか確認する** - 場合によっては、VPN、会社のプロキシ、ブラウザの機能拡張、DNSプロバイダ、またはネットワークトラフィックを妨害する可能性があるその他のサービスによってBox APIがブロックされている可能性があります。このようなサービスはどれも、リクエストをインターセプトし、必要な`Access-Control-Allow-Origin`ヘッダーが含まれていないまったく新しいリクエストを返す場合があります。このケースをテストするには、ブラウザ以外の環境、シークレットウィンドウ、またはまったく別の (会社が所有していない) デバイスから同じAPIコールを実行してみてください。 ### Access-Control-Allow-Originヘッダーの問題 `Access-Control-Allow-Origin`ヘッダーで問題が発生した場合は、以下の手順を実行します。 1. **使用するドメインが許可済みオリジンのリストに存在するかどうかを確認する** - 開発者コンソールに移動して、アプリケーションを開きます。[**構成**] タブをクリックし、下にスクロールして、[**CORSドメイン**] セクションでリストにドメインを追加できます。 1. **サーバーが正しく設定されているかどうかを確認する** - クロスドメインリクエストを処理するか、**No 'access-control-allow-origin' header is present on the requested resource (リクエストしたリソースには「access-control-allow-origin」ヘッダーが存在しません)** という警告が表示された場合は非クロスドメインリクエストを使用するようサーバーを構成します。 **Source:** [https://ja.developer.box.com/guides/security/cors/](https://ja.developer.box.com/guides/security/cors/) --- ### コードサンプル **Type:** guide | **Category:** ツール | **Section:** Developer Guides コードサンプル 汎用メソッド 以下のコードは、汎用Toolkitメソッドを使用してSalesforceのBoxフォルダにメタデータを作成します。 新しいフォルダの関連付け 以下のコードは、特定のSalesforceレコードID… # コードサンプル ## 汎用メソッド 以下のコードは、汎用Toolkitメソッドを使用してSalesforceのBoxフォルダにメタデータを作成します。 ``` // Instantiate the Toolkit object box.Toolkit toolkit = new box.Toolkit(); // Get the Salesforce record id associated with a Box folder String recordId = toolkit.getRecordIdByFolderId('{some folder id}'); // Construct an object containing all the metadata you want Map<String, Object> metadata = new Map<String, Object>{ 'salesforce_id' => recordId, 'salesforce_url' => System.URL.getSalesforceBaseUrl().toExternalForm() + '/' + recordId, 'salesforce_user_name' => UserInfo.getName(), 'salesforce_user_email' => UserInfo.getUserEmail() }; // Specify the Box API endpoint to call String endpoint = 'https://api.box.com/2.0/folders/' + '{some folder id}' + '/metadata/global/properties'; // Create a new HttpRequest object and set appropriate values HttpRequest request = new HttpRequest(); request.setMethod('POST'); request.setEndpoint(endpoint); request.setBody(JSON.serialize(metadata)); request.setHeader('content-type', 'application/json'); // Send the HttpRequest through the generic Toolkit method, which will handle the authentication details HttpResponse response = toolkit.sendRequest(request); ``` ## 新しいフォルダの関連付け 以下のコードは、特定のSalesforceレコードID用のフォルダを作成します。 ``` // Instantiate the Toolkit object box.Toolkit boxToolkit = new box.Toolkit(); // Create a folder and associate it with an account Id accountId = '001j000000FBozw'; String accountFolderId = boxToolkit.createFolderForRecordId(accountId, null, true); system.debug('new item folder id: ' + accountFolderId); // If there was an error, accountFolderId will be null. mostRecentError will contain the error message if(accountFolderId == null) { system.debug('most recent error: ' + boxToolkit.mostRecentError); } // ALWAYS call this method when finished.Since salesforce doesn't allow http callouts after dml operations, we need to commit the pending database inserts/updates or we will lose the associations created boxToolkit.commitChanges(); ``` ## フォルダテンプレート 以下のコードは、レコード用のフォルダを作成し、サブフォルダ (フォルダテンプレート) を作成して現在のユーザーとコラボレーションします。 ``` // Instantiate the Toolkit object box.Toolkit boxToolkit = new box.Toolkit(); // Create a folder and associate it with an account Id accountId = '001j000000FBozz'; String accountFolderId = boxToolkit.createFolderForRecordId(accountId, null, true); system.debug('new item folder id: ' + accountFolderId); // Create two sub-folders in the newly created account folder String legalFolderId = boxToolkit.createFolder('Legal Documents', accountFolderId, null); system.debug('Legal Folder id: ' + legalFolderId); String pictureFolderId = boxToolkit.createFolder('Pictures', accountFolderId, null); system.debug('Picture Folder id: ' + pictureFolderId); // Collaborate the current user on the account folder. Note that we're sending false for the optCreateFolder param that shouldn't actually matter since the folder(s) already exists Id userId = UserInfo.getUserId(); box.Toolkit.CollaborationType collabType = box.Toolkit.CollaborationType.EDITOR; String collabId = boxToolkit.createCollaborationOnRecord(userId, accountId, collabType, false); system.debug('new collaboration id: ' + collabId); // ALWAYS call this method when finished. Since salesforce doesn't allow http callouts after dml operations, we need to commit the pending database inserts/updates or we will lose the associations created boxToolkit.commitChanges(); ``` ## メタデータ 以下のコードでは、Boxフォルダのメタデータとカスケードポリシーを取得、追加、削除、更新します。 ``` // Get metadata & attributes types Box.toolkit tk = new Box.Toolkit(); Box.MetadataTemplate mdt = tk.getMetadataTemplateByName('enterprise', 'testtemplate'); System.debug(mdt); System.debug(mdt.getAttributeTypes()); //get Map<String, String> of values and types. // Get Metadata Box.Toolkit tk = new Box.Toolkit(); Box.FolderMetadata fmd = tk.getBoxMetadataByFolderId('193488737189', 'enterprise', 'testTemplate'); System.debug(tk.mostRecentError); System.debug(fmd); // Create Metadata Box.KeyValuePair kvp = new Box.KeyValuePair(); kvp.key = 'recordName'; kvp.value = 'Account Test Name'; Box.KeyValuePair kvp2 = new Box.KeyValuePair(); kvp2.key = 'recordUrl'; kvp2.value = 'https://speed-nosoftware-3605-dev- ed.scratch.lightning.force.com/lightning/r/Account/001DR00001PsY7YYAV/view'; List<Box.KeyValuePair> kvps = new List<Box.KeyValuePair>(); kvps.add(kvp); kvps.add(kvp2); Box.Toolkit tk = new Box.Toolkit(); Box.FolderMetadata newfmd = tk.createBoxMetadataByFolderId('193488737189', 'enterprise', 'testTemplate', kvps); System.debug(tk.mostRecentError); System.debug(newfmd); // Update Metadata List<Box.FolderMetadataUpdate> updates = new List<Box.FolderMetadataUpdate>(); Box.FolderMetadataUpdate up1 = new Box.FolderMetadataUpdate(); Box.FolderMetadataUpdate up2 = new Box.FolderMetadataUpdate(); up1.op = 'replace'; up1.path = '/recordName'; up1.value = 'Account Name Test 2'; updates.add(up1); up2.op = 'replace'; up2.path = '/recordUrl'; up2.value = 'https://speed-nosoftware-2356-dev- ed.scratch.lightning.force.com/lightning/r/Account/001DR00001PsY7YYAV/view'; updates.add(up2); Box.Toolkit tk = new Box.Toolkit(); Box.FolderMetadata fmd = tk.UpdateBoxMetadataByFolderId('193488737189', 'global', 'lobSalesforceRecord', updates); System.debug(fmd); // Delete Metadata Box.Toolkit tk = new Box.Toolkit(); Boolean fmd = tk.deleteBoxMetadataByFolderId('193488737189', 'global', 'lobSalesforceRecord'); System.debug(tk.mostRecentError); System.debug(fmd); // Get Cascade Policy List Box.Toolkit tk = new Box.Toolkit(); List<Box.MetadataCascadePolicy> mcp = tk.getMetadataCascadePoliciesByFolderId('193488737189', null, 0, null); System.debug(mcp); System.debug(tk.mostRecentError); // Get Cascade Policy Box.Toolkit tk = new Box.Toolkit(); Box.MetadataCascadePolicy mcp = tk.getMetadataCascadePolicyById('MTkzNDg4NzM3MTg5I2cjbG9iU2FsZXNmb3JjZVJlY29yZC0wMTIwMTI0ZC03YWUxLTQzNjItYjdlMC05Y2RiYzhkMzIzZjM'); System.debug(mcp); System.debug(tk.mostRecentError); // Create Cascade Policy Box.Toolkit tk = new Box.Toolkit(); Box.MetadataCascadePolicy mcp = tk.createMetadataCascadePolicy('193488737189', 'global', 'lobSalesforceRecord'); System.debug(mcp); System.debug(tk.mostRecentError); // Delete Cascade Policy Box.Toolkit tk = new Box.Toolkit(); Boolean mcp = tk.deleteMetadataCascadePolicyById('MTkzNDg4NzM3MTg5I2cjbG9iU2FsZXNmb3JjZVJlY29yZC0wMTIwMTI0ZC03YWUxLTQzNjItYjdlMC05Y2RiYzhkMzIzZjM'); System.debug(mcp); System.debug(tk.mostRecentError); ``` その他の例: ``` // Get metadata example 1 Box.toolkit tk = new Box.Toolkit(); Box.FolderMetadata fmt = tk.getBoxMetadataByFolderId('205776356105', 'enterprise', 'testTemplate'); for(KeyValuePair kvp : fmt.keyValuePairs){ System.debug(kvp); } // Get metadata example 2 Box.toolkit tk = new Box.Toolkit(); System.debug(tk.getBoxMetadataByFolderId('205776356105', 'global', 'lobSalesforceRecord')); ``` ``` // Create metadata Box.toolkit tk = new Box.Toolkit(); List<Box.KeyValuePair> kvps = new List<Box.KeyValuePair>(); Box.KeyValuePair kvp1 = new Box.KeyValuePair(); kvp1.key = 'name'; kvp1.value = 'test'; kvps.add(kvp1); Box.KeyValuePair kvp2 = new Box.KeyValuePair(); kvp2.key = 'revenue'; kvp2.value = '5000'; kvps.add(kvp2); Box.KeyValuePair kvp3 = new Box.KeyValuePair(); kvp3.key = 'typeMulti'; kvp3.value = 'Customer;Other'; kvps.add(kvp3); System.debug(tk.createBoxMetadataByFolderId('205776356105', 'enterprise', 'testtemplate', kvps)); System.debug(tk.mostRecentError); ``` ``` // Update Metadata Box.toolkit tk = new Box.Toolkit(); System.debug(tk.getBoxMetadataByFolderId('205776356105', 'enterprise', 'mitchtemplate')); List<Box.FolderMetadataUpdate> fmus = new List<Box.FolderMetadataUpdate>(); Box.FolderMetadataUpdate fmu = new Box.FolderMetadataUpdate(); fmu.op = 'replace'; fmu.path = '/name'; fmu.value = 'Test 2'; fmus.add(fmu); Box.FolderMetadataUpdate fmu2 = new Box.FolderMetadataUpdate(); fmu2.op = 'replace'; fmu2.path = '/revenue'; fmu2.value = '3000'; fmus.add(fmu2); Box.FolderMetadataUpdate fmu3 = new Box.FolderMetadataUpdate(); fmu3.op = 'add'; fmu3.path = '/typeMulti'; fmu3.value = 'Customer'; fmus.add(fmu3); System.debug(tk.updateBoxMetadataByFolderId('205776356105', 'enterprise', 'testTemplate', fmus)); System.debug(tk.mostRecentError); ``` **Source:** [https://ja.developer.box.com/guides/tooling/salesforce-toolkit/samples/](https://ja.developer.box.com/guides/tooling/salesforce-toolkit/samples/) --- ### コマンドの作成とヘルプ機能 **Type:** quick-start | **Category:** CLI | **Section:** Developer Guides コマンドの作成とヘルプ機能 CLIコマンドの全一覧と使用方法に関する情報については、GitHub… # コマンドの作成とヘルプ機能 CLIコマンドの全一覧と使用方法に関する情報については、[GitHubリポジトリ](https://github.com/box/boxcli#command-topics-1)を参照してください。 一部のコマンドは、サービスアカウントと管理者しか使用できません。必要なスコープでユーザーが承認されていない場合、または別のユーザーのデフォルトのトークンを取得するようCLIを構成した場合は、呼び出しが失敗する可能性があります。詳細なエラーログを確認するには、コマンドに`-v`または`--verbose`を追加してください。 必要なエンドポイント用のコマンドが表示されない場合は、[カスタムリクエスト](https://github.com/box/boxcli/blob/master/docs/request.md)を作成できます。 helpコマンドで提供されない情報を確認するには、リファレンスドキュメントと併せてリポジトリのドキュメントを使用してください。このような情報には、制限事項、トークンの権限の要件、フィールドなどがあります。 ## はじめに: ブラウザのストレージをリセットする Box API資格情報をCLIにインポートしたので、これらの資格情報をブラウザのストレージから削除することをお勧めします。 資格情報をクリア API資格情報をブラウザのストレージから削除すると、**クライアントID**または**クライアントシークレット**を他のスクリプトで読み取ることができなくなります。 ## helpを使用したフォルダの作成 どのCLIコマンドも`box`で始まります。任意のコマンドにオプション`--help`を追加すると、そのコマンドを作成するためのヘルプが表示されます。たとえば、`box --help`を実行すると、使用可能なすべてのオブジェクトコマンドのリストが表示されます。オプションの詳細については、[手順4](g://cli/quick-start/options-and-bulk-commands/#options)で説明します。 次に、例として、フォルダオブジェクトを使用してコマンド`box folders --help`を実行します。その結果、このオブジェクトに実行できるすべての操作のリストが表示されます。 フォルダの作成に必要な引数を調べるためのコマンド: `box folders:create --help` コマンド`box folders:create 0 "My CLI Folder"`を実行し、レスポンスで返されたフォルダIDを書き留めておきます。 フォルダツリーのルートレベルである [すべてのファイル] ページは、常にフォルダID 0で表されます。 **自分の**Boxアカウントにログインします。このフォルダが自分のフォルダツリーに表示されているでしょうか? JWT認証を使用したBox CLIを設定すると、Boxアカウントにこのフォルダが表示されなくなります。このフォルダは、アプリケーションの承認後に作成されたアプリケーションのサービスアカウントに存在します。 ## まとめ - **ヘルプ**機能を使用してフォルダを作成しました 最初のフォルダを作成しました **Source:** [https://ja.developer.box.com/guides/cli/quick-start/build-commands-help/](https://ja.developer.box.com/guides/cli/quick-start/build-commands-help/) --- ### ごみ箱 **Type:** guide | **Category:** ごみ箱 | **Section:** Developer Guides ごみ箱 項目が削除される前に、ユーザーのごみ箱に入れられる可能性があります。ごみ箱は、ユーザーがBoxアプリを使用して、またはアプリケーションによってAPI経由で管理できます。 2段階の削除プロセス Box… # ごみ箱 項目が削除される前に、ユーザーのごみ箱に入れられる可能性があります。ごみ箱は、ユーザーがBoxアプリを使用して、またはアプリケーションによってAPI経由で管理できます。 ## 2段階の削除プロセス Boxでは、[ファイル](e://delete_files_id)、[フォルダ](e://delete_folders_id)、および[ウェブリンク](e://delete_web_links_id)を**ごみ箱に移動**し、その後で完全削除するという2段階のプロセスを使用します。 デフォルトでは、項目は**ごみ箱に移動**された後、30日間は復元可能です。この期間が経過すると**ごみ箱から削除**されます。会社の管理者は削除までの期間を変更することができます。 詳細については、Boxコミュニティの[ごみ箱の管理](https://support.box.com/hc/ja/articles/360044196093-%E3%81%94%E3%81%BF%E7%AE%B1%E3%81%AE%E7%AE%A1%E7%90%86)を参照してください。 **Source:** [https://ja.developer.box.com/guides/trash/](https://ja.developer.box.com/guides/trash/) --- ### ごみ箱の検索 **Type:** guide | **Category:** 検索 | **Section:** Developer Guides ごみ箱の検索 検索結果では、デフォルトで、ユーザーのごみ箱内のコンテンツは無視されます。ユーザーのごみ箱を検索するには、trash_contentクエリパラメータをtrashed_onlyに設定します。 現在、APIでサポートされているのは、ごみ箱にないコンテンツの検索 (non… # ごみ箱の検索 検索結果では、デフォルトで、ユーザーのごみ箱内のコンテンツは無視されます。ユーザーのごみ箱を検索するには、`trash_content`クエリパラメータを`trashed_only`に設定します。 ``` curl -i -X GET "https://api.box.com/2.0/search?query=sales&trash_content=trashed_only" \ -H "Authorization: Bearer <ACCESS_TOKEN>" ``` ``` long offsetValue = 0; long limitValue = 10; BoxSearch boxSearch = new BoxSearch(api); BoxSearchParameters searchParams = new BoxSearchParameters(); searchParams.setQuery("sales"); searchParams.setTrashContent("trashed_only"); PartialCollection<BoxItem.Info> searchResults = boxSearch.searchRange(offsetValue, limitValue, searchParams); ``` ``` BoxCollection<BoxItem> results = await client.SearchManager .QueryAsync("sales", mdFilters: filters, trashContent: "trashed_only"); ``` ``` client.search().query("sales", metadata_filters=metadata_search_filters, trash_content="trashed_only") ``` ``` client.search.query( 'sales', { trash_content: "trashed_only" }) .then(results => { // ... }); ``` 現在、APIでサポートされているのは、ごみ箱にないコンテンツの検索 (`non_trashed_only`、デフォルト) かユーザーのごみ箱にあるコンテンツの検索 (`trashed_only`) のみです。現時点では、その両方の場所にある項目を同時に検索することはできません。 **Source:** [https://ja.developer.box.com/guides/search/trash/](https://ja.developer.box.com/guides/search/trash/) --- ### コメント **Type:** guide | **Category:** コメント | **Section:** Developer Guides コメント コメントは、Box… # コメント コメントは、Boxユーザーがファイルに対して生成するメッセージです。コメントを使用すると、複数のユーザーがファイルでコラボレーションし、コンテンツに対するフィードバックについて話し合うことができます。 それぞれのコメントは特定のファイルおよびユーザーに関連付けられます。また、コメントは、独立したコメントとして作成することも、以前のコメントに対する返信として作成することも可能です。 **Source:** [https://ja.developer.box.com/guides/comments/](https://ja.developer.box.com/guides/comments/) --- ### コメントの作成 **Type:** guide | **Category:** コメント | **Section:** Developer Guides コメントの作成 コメントを作成するには、コメントのメッセージと、コメントを残すファイルのIDを指定してPOST /comments API… # コメントの作成 コメントを作成するには、コメントのメッセージと、コメントを残すファイルのIDを指定して[`POST /comments`](e://post_comments) APIを呼び出します。 コメントのメッセージでは、`@`記号を使用してユーザーをメンションすることもできます。そのためには、メッセージ内の任意の場所に`@[userid:name]`という文字列を追加します。`user_id`はターゲットユーザーのIDで、`name`には任意のカスタムフレーズを使用できます。Box UIでは、この名前がユーザーのプロフィールにリンクされます。 次に、この文字列を`message`ではなく`tagged_message`として渡します。 **Source:** [https://ja.developer.box.com/guides/comments/create-comment/](https://ja.developer.box.com/guides/comments/create-comment/) --- ### コラボレーション **Type:** guide | **Category:** コラボレーション | **Section:** Developer Guides … # コラボレーション アクセス制御リストと同様に、コラボレーションではファイルとフォルダに対するユーザーおよびグループのアクセス権限が定義されます。コラボレーションオブジェクトは、特定のロールによって定義される権限を含んだファイルまたはフォルダへのアクセス権限をユーザーまたはグループに付与します。 コラボレーションロールは`editor`、`viewer`、`previewer`、`uploader`、`previewer uploader`、`viewer uploader`、`co-owner`、または`owner`です。各ロールについての詳しい説明は、Boxの[サポートドキュメント](https://support.box.com/hc/ja/articles/360044196413-%E3%82%B3%E3%83%A9%E3%83%9C%E3%83%AC%E3%83%BC%E3%82%BF%E3%81%AE%E6%A8%A9%E9%99%90%E3%83%AC%E3%83%99%E3%83%AB%E3%81%AB%E3%81%A4%E3%81%84%E3%81%A6)を参照してください。 **Source:** [https://ja.developer.box.com/guides/collaborations/](https://ja.developer.box.com/guides/collaborations/) --- ### コラボレーションが許可されているドメインのリストの取得 **Type:** guide | **Category:** コラボレーション | **Section:** Developer Guides コラボレーションが許可されているドメインのリストの取得 コラボレーションが許可されているドメインのリストを取得すると、現在の会社でのコラボレーションの作成を許可するドメインがすべて返されます。 リクエストに必須のパラメータはありませんが、オプションでlimitおよびmarket… # コラボレーションが許可されているドメインのリストの取得 コラボレーションが許可されているドメインのリストを取得すると、現在の会社でのコラボレーションの作成を許可するドメインがすべて返されます。 リクエストに必須のパラメータはありませんが、オプションで`limit`および`market`パラメータを設定すると、結果セット全体を制限してページ単位で表示できます。 **Source:** [https://ja.developer.box.com/guides/collaborations/allowed-domains/list/](https://ja.developer.box.com/guides/collaborations/allowed-domains/list/) --- ### コラボレーションの利用規約の検索 **Type:** guide | **Category:** セキュリティ | **Section:** Developer Guides コラボレーションの利用規約の検索 コラボレーションに効力のあるサービス利用規約に関する情報を調べるには、GET /collaborations/:id APIを呼び出してクエリパラメータfields=acceptance_requirements_status… # コラボレーションの利用規約の検索 [コラボレーション](r://collaboration)に効力のあるサービス利用規約に関する情報を調べるには、[`GET /collaborations/:id`](e://get-collaborations-id) APIを呼び出してクエリパラメータ`fields=acceptance_requirements_status`を渡します。 ``` curl -X GET https://api.box.com/2.0/collaborations/2342342?fields=acceptance_requirements_status \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` 返されるレスポンスには、Mini版の`terms_of_service`オブジェクトを含む新しい`acceptance_requirements`オブジェクトが含まれます。 ``` { "type": "collaboration", "id": 2342342>, "acceptance_requirements": { "terms_of_service": { "type": "terms_of_service", "id": 6766677 } } } ``` この情報が返されるのは、外部ユーザーのサービス利用規約が企業で有効になっており、リクエストを実行するユーザーにサービス利用規約を表示するための[権限](g://security/terms-of-service/permissions)がある場合のみです。これは、管理者とエンドユーザーの両方に当てはまりますが、特定のサービス利用規約タイプが無効になっている場合でも、一般的に、管理者はAPIを介してユーザーのサービス利用規約情報を表示できます。 サービス利用規約タイプが有効になっていない場合は、APIによって空の結果が返されます。 ``` { "type": "collaboration", "id": 2342342>, "acceptance_requirements": { "terms_of_service": null } } ``` すでにユーザーが同意している場合でも、`terms_of_service`の情報は`acceptance_requirements`内で返されます。 **Source:** [https://ja.developer.box.com/guides/security/terms-of-service/for-colaboration/](https://ja.developer.box.com/guides/security/terms-of-service/for-colaboration/) --- ### コラボレーションの許可されたドメイン **Type:** guide | **Category:** コラボレーション | **Section:** Developer Guides コラボレーションの許可されたドメイン 会社のコンテンツと共有設定では、管理者は会社に対してコラボレーションの制限を設定できます。この設定では、許可された一連のドメインのみにコラボレーションを制限することも可能です。 許可されたドメインAPI… # コラボレーションの許可されたドメイン 会社のコンテンツと共有設定では、管理者は会社に対して[コラボレーションの制限](https://support.box.com/hc/ja/articles/4404822772755-Enterprise%E8%A8%AD%E5%AE%9A-%E3%82%B3%E3%83%B3%E3%83%86%E3%83%B3%E3%83%84%E3%81%A8%E5%85%B1%E6%9C%89-%E3%82%BF%E3%83%96)を設定できます。この設定では、許可された一連のドメインのみにコラボレーションを制限することも可能です。 許可されたドメインAPIを使用すると、適切な権限を持つアプリケーションは、会社の許可されたドメインをプログラムを使用して追加、取得、および削除できます。 **Source:** [https://ja.developer.box.com/guides/collaborations/allowed-domains/](https://ja.developer.box.com/guides/collaborations/allowed-domains/) --- ### コレクション **Type:** guide | **Category:** コレクション | **Section:** Developer Guides コレクション Boxにおけるコレクションとは、ファイル、フォルダ、およびウェブリンクをすべて1つのフォルダにまとめることなくグループ化する方法です。 APIを介して使用できるコレクションは「お気に入り」コレクションのみです。このコレクションのIDはユーザーごとに異なります。 # コレクション Boxにおけるコレクションとは、ファイル、フォルダ、およびウェブリンクをすべて1つのフォルダにまとめることなくグループ化する方法です。 APIを介して使用できるコレクションは「お気に入り」コレクションのみです。このコレクションのIDは[ユーザーごとに異なります](g://collections/list)。 **Source:** [https://ja.developer.box.com/guides/collections/](https://ja.developer.box.com/guides/collections/) --- ### コレクションからの項目の削除 **Type:** guide | **Category:** コレクション | **Section:** Developer Guides コレクションからの項目の削除 コレクションから項目を削除するには、その特定のタイプの項目に対してPUTエンドポイントを呼び出し、削除するコレクションのIDが含まれていない、コレクションIDのリストを渡します。 API… # コレクションからの項目の削除 コレクションから項目を削除するには、その特定のタイプの項目に対して`PUT`エンドポイントを呼び出し、削除するコレクションのIDが含まれていない、コレクションIDのリストを渡します。 APIを介して使用できるコレクションは「お気に入り」コレクションのみであるため、このコレクションから項目を削除するには、APIにコレクションの空の配列を渡してください。 ## コレクションからのファイルの削除 コレクションからファイルを削除するには、`PUT /files/:id` APIを呼び出し、コレクションIDの空の配列を渡します。 ## コレクションからのフォルダの削除 コレクションからフォルダを削除するには、`PUT /folders/:id` APIを呼び出し、コレクションIDの空の配列を渡します。 ## コレクションからのウェブリンクの削除 コレクションからウェブリンクを削除するには、`PUT /web_links/:id` APIを呼び出し、コレクションIDの空の配列を渡します。 **Source:** [https://ja.developer.box.com/guides/collections/remove/](https://ja.developer.box.com/guides/collections/remove/) --- ### コレクションのフォーク **Type:** quick-start | **Category:** ツール | **Section:** Developer Guides コレクションのフォーク ログインしたら、前の手順でインストールしたPostmanアプリにBox Postmanコレクションをフォークできます。Postmanコレクションをフォークすると、Postman環境としてAPI… # コレクションのフォーク ログインしたら、前の手順でインストールした**Postmanアプリ**に**Box Postmanコレクション**をフォークできます。Postmanコレクションをフォークすると、Postman環境としてAPI資格情報も自動的に読み込まれます。 ## コレクションと環境のフォーク 下のボタンをクリックすると、**Box Postmanコレクション**がPostmanアプリケーションにフォークされます。同時に、**アクセストークン**、**更新トークン**、**クライアントID**、および**クライアントシークレット**もPostman環境に読み込まれます。 Boxでは、Box Postmanコレクションをフォークすることをお勧めします。これにより、BoxがBox Postmanコレクションに変更を加えるたびに、そのコレクションを更新するかどうかが確認されます。このコレクションをコピーすることもできますが、重要な更新を見逃す可能性があります。 ## コレクションの探索 上のボタンをクリックすると、Postmanアプリケーションにコレクションをフォークするよう求められます。インポートが完了すると、このコレクションはアプリ内で左側のサイドバーに表示されます。 コレクションをクリックして開くと、170を超えるAPIエンドポイントを探索できます。 ## まとめ - PostmanコレクションをPostmanにフォークしました - さらにBox Postman環境をPostmanに読み込みました # 前の手順が完了していません 前の手順を完了し、**Boxアプリ**を選択してログインしてください。 # 前の手順が完了していません 前の手順を完了し、**Boxアプリ**を選択してログインしてください。 コレクションのフォークが完了しました **Source:** [https://ja.developer.box.com/guides/tooling/postman/quick-start/load-postman-collection/](https://ja.developer.box.com/guides/tooling/postman/quick-start/load-postman-collection/) --- ### コレクションへの項目の追加 **Type:** guide | **Category:** コレクション | **Section:** Developer Guides コレクションへの項目の追加 コレクションに項目を追加するには、その特定のタイプの項目に対してPUTエンドポイントを呼び出し、コレクションIDのリストを渡します。 APIを介して使用できるコレクションは「お気に入り」コレクションのみです。このコレクションのID… # コレクションへの項目の追加 コレクションに項目を追加するには、その特定のタイプの項目に対して`PUT`エンドポイントを呼び出し、コレクションIDのリストを渡します。 APIを介して使用できるコレクションは「お気に入り」コレクションのみです。このコレクションのIDは[ユーザーごとに異なります](g://collections/list)。 ## コレクションへのファイルの追加 コレクションにファイルを追加するには、`PUT /files/:id` APIを呼び出し、コレクションIDのリストを渡します。 ## コレクションへのフォルダの追加 コレクションにフォルダを追加するには、`PUT /folders/:id` APIを呼び出し、コレクションIDのリストを渡します。 ## コレクションへのウェブリンクの追加 コレクションにウェブリンクを追加するには、`PUT /web_links/:id` APIを呼び出し、コレクションIDのリストを渡します。 **Source:** [https://ja.developer.box.com/guides/collections/add/](https://ja.developer.box.com/guides/collections/add/) --- ### コレクション内の項目のリストの取得 **Type:** guide | **Category:** コレクション | **Section:** Developer Guides コレクション内の項目のリストの取得 フォルダ内のすべてのファイル、フォルダ、およびウェブリンクのリストを取得するには、GET /collections/:id/items APIを呼び出します。 API… # コレクション内の項目のリストの取得 フォルダ内のすべてのファイル、フォルダ、およびウェブリンクのリストを取得するには、[`GET /collections/:id/items`](e://get_collections_id_items) APIを呼び出します。 APIを介して使用できるコレクションは「お気に入り」コレクションのみです。このコレクションのIDは[ユーザーごとに異なります](g://collections/list)。 **Source:** [https://ja.developer.box.com/guides/collections/list-items/](https://ja.developer.box.com/guides/collections/list-items/) --- ### コンテンツアップローダー **Type:** guide | **Category:** Boxの埋め込み | **Section:** Developer Guides コンテンツアップローダー Box Content Uploader UI Element… # コンテンツアップローダー Box Content Uploader UI Elementを使用すると、開発者は、デスクトップまたはモバイルウェブアプリにアップロードウィジェットを埋め込むことができます。ユーザーはファイルを選択するかドラッグアンドドロップしてアップロードできます。サイズの大きなファイルのアップロードには、[分割アップロード](e://post-files-upload-sessions)APIを使用します。 ## インストール NPMまたはBox CDN経由でBox UI Elementsをインストールする方法は、[こちら](g://embed/ui-elements/installation)を参照してください。 ## 認証 UI Elementは認証に依存しない方法で設計されているため、Boxアカウントを持つユーザー (管理対象ユーザー) とBox以外のアカウントを持つユーザー (App User) のどちらにUI Elementを使用するかどうかに関係なく、UI Elementを使用するのに特別な設定は必要ありません。その理由は、UI Elementは認証のために「トークン」を受け取ることのみを予期しており、Boxにはトークンの生成方法としてOAuthとJWTの2つがあるからです。 認証方法の選択について確認する ## デモ ### Uploader ### ポップアップ形式のアップローダー # アクセストークン 上記のデモは、有効なアクセストークンを指定しなければ、完全に動作しない可能性があります。テスト目的の場合は、一時的な開発者トークンを使用できます。このトークンは、デモにある [JS] タブで更新する必要があります。 ## API ``` const { ContentUploader } = Box; const uploader = new ContentUploader(); /** * Shows the content uploader. * * @public * @param {String} folderId - Folder ID to upload to. * @param {String} accessToken - Box API access token. * @param {Object|void} [options] - Optional options. * @return {void} */ uploader.show(folderId, accessToken, options); /** * Hides and clears HTML for the uploader. * * @public * @return {void} */ uploader.hide(); /** * Adds an event listener to the content uploader. * Listeners should be added before calling show() * so no events are missed. * * @public * @param {String} eventName Name of the event. * @param {Function} listener Callback function. * @return {void} */ uploader.addListener(eventName, listener); /** * Removes an event listener from the content uploader. * * @public * @param {String} eventName Name of the event. * @param {Function} listener Callback function. * @return {void} */ uploader.removeListener(eventName, listener); /** * Removes all event listeners from the content uploader. * * @public * @return {void} */ uploader.removeAllListeners(); ``` ### パラメータ | パラメータ | 型 | 説明 | | --- | --- | --- | | folderId | String | BoxフォルダのID。アップロードするファイルが含まれているフォルダのIDです。Boxの [すべてのファイル] フォルダを使用する場合は、folderIdとして0を使用します。 | | accessToken | String | 使用するBox APIアクセストークン。このトークンには、上記のフォルダに対するアップロード権限が必要です。 | | options | Object | 省略可能なオプション。詳細については、以下を参照してください。 | ### オプション | パラメータ | 型 | デフォルト | 説明 | | --- | --- | --- | --- | | container | String | document.body | コンテンツアップローダーが配置されるコンテナのCSSセレクタ。hide()を呼び出すと、このコンテナは空になります。 | | sharedLink | String | | 共有リンクのURL。フォルダが共有されており、アクセストークンがファイルの所有者またはコラボレータに属していない場合は必須です。 | | sharedLinkPassword | String | | 共有リンクのパスワード。共有リンクにパスワードが設定されている場合は必須です。 | | onClose | Function | | アップロードするファイルがない場合やすべてのアップロードが完了している場合に表示される [閉じる] ボタンのコールバック関数。このオプションをnullに設定すると、このボタンは表示されません。 | | modal | Object | | ウィンドウ属性を指定すると、コンテンツアップローダーは所定の位置に作成されません。代わりに、コンテナ内にボタンが作成され、そのボタンをクリックすると、ウィンドウポップアップでコンテンツアップローダーが起動します。ウィンドウオプションについては、以下を参照してください。 | | size | String | undefined | コンテンツアップローダーがコンテナの幅の大小に合わせて表示されるように示します。値には空白か、smallまたはlargeを指定できます。空白にした場合、UI Elementはそのコンテナに合わせて調整され、自動でsmallの幅とlargeの幅が切り替わります。 | | isTouch | Boolean | デフォルトでは、ブラウザとデバイスのデフォルトのタッチサポートが設定されます。 | コンテンツエクスプローラがタッチ対応デバイスにレンダリングされることを示します。 | | fileLimit | Number | 100 | 一度にアップロードできるファイルの最大数。fileLimitを超えるファイルをアップロードのために選択した場合、最初のfileLimitを超えるファイルはアップロードに含まれません。この状況が発生した場合、フッターに警告メッセージが表示されます。 | | requestInterceptor | Function | | リクエストをインターセプトする関数。例については、このCodePenを参照してください。基盤となるXHRライブラリはaxios.jsで、インターセプタでは同様のアプローチに従っています。 | | responseInterceptor | Function | | レスポンスをインターセプトする関数。例については、このCodePenを参照してください。基盤となるXHRライブラリはaxios.jsで、インターセプタでは同様のアプローチに従っています。 | ### ウィンドウオプション | パラメータ | 型 | デフォルト | 説明 | | --- | --- | --- | --- | | buttonLabel | String | | ボタンのラベル | | buttonClassName | String | Boxの青いボタン | ボタンを装飾するためのCSSクラス | | modalClassName | String | | ウィンドウポップアップコンテンツを装飾するためのCSSクラス | | overlayClassName | String | | ウィンドウポップアップオーバーレイを装飾するためのCSSクラス | ### イベント | イベント名 | イベントデータ | 説明 | | --- | --- | --- | | close | | [閉じる] ボタンがクリックされたときに発生します。 | | complete | Array<File> | 現在のビューにあるアップロードがすべて完了したときに発生します。イベントデータはファイルオブジェクトの配列になります。 | | upload | ファイル | 1つのファイルが正常にアップロードされたときに発生します。イベントデータはファイルオブジェクトになります。 | | error | Object | 1つのファイルでアップロードエラーが生じたときに発生します。イベントデータはFile Web APIのプロパティファイルとエラーオブジェクトのエラーを含むオブジェクトになります。 | ## スコープ アプリケーションで、エンドユーザーがコンテンツアップローダー機能のサブセットのみにアクセスできるようにする必要がある場合は、[ダウンスコープ](guide://authentication/tokens/downscope)を使用して、アクセストークンを適切にダウンスコープして必要な権限のセットを含むトークンを生成し、コンテンツアップローダーを初期化するエンドユーザークライアントに安全に渡すことができます。 以下は、ダウンスコープと一緒に使用する、UI Element固有の新しいスコープのセットです。こうしたスコープにより、開発者は、ダウンスコープされたトークンに適切なスコープを構成して、コンテンツアップローダーのUIコントロールを有効/無効にすることができます。詳細については、[Box UI Elementsの専用スコープ](guide://api-calls/permissions-and-errors/scopes)を参照してください。 ### 基本スコープ | スコープ名 | 付与される権限 | | --- | --- | | base_upload | トークン交換リクエストの「resource」で指定されたフォルダへのアップロードを許可します。 | ### サンプルのシナリオ | シナリオ | スコープ | | --- | --- | | ユーザーがファイルをBoxフォルダにアップロードする | base_upload | **Source:** [https://ja.developer.box.com/guides/embed/ui-elements/uploader/](https://ja.developer.box.com/guides/embed/ui-elements/uploader/) --- ### コンテンツエクスプローラ **Type:** guide | **Category:** Boxの埋め込み | **Section:** Developer Guides コンテンツエクスプローラ Box Content Explorer UI Elementを使用すると、開発者は、Boxに保存されているコンテンツのフォルダビューをデスクトップまたはモバイルウェブアプリに埋め込むことができます。ライブラリはBox API… # コンテンツエクスプローラ Box Content Explorer UI Elementを使用すると、開発者は、Boxに保存されているコンテンツのフォルダビューをデスクトップまたはモバイルウェブアプリに埋め込むことができます。ライブラリはBox APIを介して指定されたフォルダに関する情報を取得した後、メインのBoxウェブアプリと同様にそのコンテンツをフォルダビューにレンダリングします。ユーザーは、そのフォルダ階層内を移動し、名前の変更、削除、共有などのファイル操作を実行できます。 コンテンツエクスプローラで、メタデータビューを使用できるようになりました。このビューでは、メタデータクエリを使用して、メタデータに基づいてファイルやフォルダを検索できます。データは埋め込みのビューに表示されます。 ## インストール NPMまたはBox CDN経由でBox UI Elementsをインストールする方法は、[こちら](g://embed/ui-elements/installation)を参照してください。 ## 認証 UI Elementは認証に依存しない方法で設計されているため、Boxアカウントを持つユーザー (管理対象ユーザー) とBox以外のアカウントを持つユーザー (App User) のどちらにUI Elementを使用するかどうかに関係なく、UI Elementを使用するのに特別な設定は必要ありません。その理由は、UI Elementは認証のために「トークン」を受け取ることのみを予期しており、Boxにはトークンの生成方法としてOAuthとJWTの2つがあるからです。 認証方法の選択について確認する ## サンプルHTML ``` <!DOCTYPE html> <html lang="en-US"> <head> <meta charset="utf-8" /> <title>Box Content Explorer Demo</title> <!-- Latest version of the explorer css for your locale --> <link rel="stylesheet" href="https://cdn01.boxcdn.net/platform/elements/{VERSION}/en-US/explorer.css" /> </head> <body> <div class="container" style="height:600px"></div> <!-- Latest version of the explorer js for your locale --> <script src="https://cdn01.boxcdn.net/platform/elements/{VERSION}/en-US/explorer.js"></script> <script> var folderId = "123"; var accessToken = "abc"; var contentExplorer = new Box.ContentExplorer(); contentExplorer.show(folderId, accessToken, { container: ".container", }); </script> </body> </html> ``` ## デモ ## API ``` const { ContentExplorer } = Box; const contentExplorer = new ContentExplorer(); /** * Shows the content explorer. * * @param {string} folderId - The root folder id * @param {string} accessToken - Box API access token * @param {Object} [options] - Options * @return {void} */ contentExplorer.show(folderId, accessToken, options); /** * Hides the content explorer, removes all event listeners, and clears out the * HTML. * * @return {void} */ contentExplorer.hide(); /** * Clears out the internal in-memory * cache for the content explorer forcing * re-load of items via the API. * * @public * @return {void} */ contentExplorer.clearCache(); /** * Adds an event listener to the content explorer. Listeners should be added * before calling show() so no events are missed. * * @param {string} eventName - Name of the event * @param {Function} listener - Callback function * @return {void} */ contentExplorer.addListener(eventName, listener); /** * Removes an event listener from the content explorer. * * @param {string} eventName - Name of the event * @param {Function} listener - Callback function * @return {void} */ contentExplorer.removeListener(eventName, listener); /** * Removes all event listeners from the content explorer. * * @return {void} */ contentExplorer.removeAllListeners(); ``` ### パラメータ | パラメータ | 型 | 説明 | | --- | --- | --- | | folderId | String | BoxフォルダのID。中を移動するフォルダのIDになります。Boxの [すべてのファイル] フォルダを使用する場合は、folderIdとして0を使用します。 | | accessToken | String | 使用するBox APIアクセストークン。このトークンには、上記のフォルダに対する読み取り/書き込みアクセス権限が必要です。このトークンのために渡される値は、エクスプローラの表示中は有効期限切れにならないことが前提となっています。 | | options | Object | 省略可能なオプション。詳細は以下を参照してください。たとえば、contentExplorer.show(FOLDER_ID, TOKEN, {canDelete: false})を使用すると、削除オプションが非表示になります。 | ### オプション | パラメータ | 型 | デフォルト | 説明 | | --- | --- | --- | --- | | container | String | document.body | コンテンツエクスプローラが配置されるコンテナのCSSセレクタ。hide() を呼び出すと、このコンテナは空になります。 | | sortBy | String | name | コンテンツリストの最初の並べ替え基準オプション。値はid、name、dateまたはsizeになります。 | | sortDirection | String | ASC | コンテンツリストの最初の並べ替え方向オプション。値はASCまたはDESCになります。 | | logoUrl | String | | ヘッダーに表示するカスタムロゴのURL。この値が「box」という文字列の場合は、Boxのロゴが表示されます。 | | canPreview | Boolean | true | このオプションがtrueに設定されていて、ファイルに対するcan_preview権限がtrueの場合、コンテンツエクスプローラでファイルをクリックできます。ファイルをクリックするとそのファイルのプレビューが開始されます。ファイルに対する権限can_previewがfalseに設定されている場合、このオプションによる効果はありません。このオプションは、プレビュー可能なファイルのみに適用できます。 | | canDownload | Boolean | true | これをfalseに設定すると、ダウンロードオプションが非表示になります。このオプションを非表示にするだけではダウンロードを防ぐことはできず、ファイルに対する権限でもcan_downloadをfalseに設定する必要があります。ファイルに対する権限can_downloadがfalseに設定されている場合、このオプションによる効果はありません。このオプションは、ファイルのみに適用できます。 | | canDelete | Boolean | true | これをfalseに設定すると、削除オプションが非表示になります。このオプションを非表示にするだけでは削除を防ぐことはできず、項目に対する権限でもcan_deleteをfalseに設定する必要があります。項目に対する権限can_deleteがfalseに設定されている場合、このオプションによる効果はありません。 | | canRename | Boolean | true | これをfalseに設定すると、名前の変更オプションが非表示になります。このオプションを非表示にするだけでは名前の変更を防ぐことはできず、項目に対する権限でもcan_renameをfalseに設定する必要があります。 | | canUpload | Boolean | true | これをfalseに設定すると、アップロードオプションが非表示になります。このオプションを非表示にするだけではアップロードを防ぐことはできず、現在のフォルダに対する権限でもcan_uploadをfalseに設定する必要があります。フォルダに対する権限can_uploadがfalseに設定されている場合、このオプションによる効果はありません。 | | canCreateNewFolder | Boolean | true | フォルダの新規作成オプションが非表示になります。このオプションを非表示にするだけではフォルダの新規作成を防ぐことはできず、フォルダ項目に対する権限でもcan_uploadをfalseに設定する必要があります。フォルダ項目に対する権限can_uploadがfalseに設定されている場合、このオプションによる効果はありません。 | | canShare | Boolean | true | falseに設定すると、共有ボタンが非表示になります。このボタンを非表示にするだけでは共有を防ぐことはできず、項目のpermissionsでもcan_shareをfalseに設定する必要があります。項目に対する権限can_shareがfalseに設定されている場合、このオプションによる効果はありません。 | | canSetShareAccess | Boolean | true | falseに設定すると、共有権限の変更を許可する共有ドロップダウン選択が非表示になります。この選択のドロップダウンを非表示にするだけでは共有権限の変更を防ぐことはできず、項目に対する権限でもcan_set_share_accessをfalseに設定する必要があります。項目に対する権限can_set_share_accessがfalseに設定されている場合、このオプションによる効果はありません。 | | sharedLink | String | | 共有リンクのURL。フォルダが共有されており、アクセストークンがファイルの所有者またはコラボレータに属していない場合は必須です。 | | sharedLinkPassword | String | | 共有リンクのパスワード。共有リンクにパスワードが設定されている場合は必須です。 | | size | String | undefined | コンテンツエクスプローラがコンテナの幅の大小に合わせて表示されるように示します。値には空白か、smallまたはlargeを指定できます。空白にした場合、UI Elementはそのコンテナに合わせて調整され、自動でsmallの幅とlargeの幅が切り替わります。 | | isTouch | Boolean | デフォルトでは、ブラウザとデバイスのデフォルトのタッチサポートが設定されます。 | コンテンツエクスプローラがタッチ対応デバイスにレンダリングされることを示します。 | | autoFocus | Boolean | false | trueに設定すると、初回読み込み時に項目グリッドに焦点が当てられます。 | | defaultView | String | files | 値はfiles、recents、またはmetadataになります。recentsに設定すると、デフォルトで、通常のファイル/フォルダ構造ではなく、最近使用した項目が表示されます。コンテンツエクスプローラでメタデータビューを表示するには、metadataを指定する必要があります。指定しない場合、通常のフォルダビューが表示されます。 | | requestInterceptor | Function | | リクエストをインターセプトする関数。例については、このCodePenを参照してください。基盤となるXHRライブラリはaxios.jsで、インターセプタでは同様のアプローチに従っています。 | | responseInterceptor | Function | | レスポンスをインターセプトする関数。例については、このCodePenを参照してください。基盤となるXHRライブラリはaxios.jsで、インターセプタでは同様のアプローチに従っています。 | | ContentOpenWithProps | Object | { show: false } | エクスプローラからプレビューする際にOpen With Elementを表示できます。 | | token | String | | 開発者コンソールで生成された開発者トークン。 | | metadataQuery | Object | | メタデータビューの情報を取得するために使用されるメタデータクエリ。 | | rootFolderID | String | | メタデータテンプレートが適用されているフォルダのID。metadataQueryはこのフォルダに適用されます。 | | fieldsToShow | Object | | 表示するメタデータフィールド/列 - メタデータテンプレートの有効なフィールド名を指定する必要があります。 | ### イベント | イベント名 | イベントデータ | 説明 | | --- | --- | --- | | select | Array<File | Web Link | Folder> | 項目行が選択されたときに発生します。 | | rename | File | Web Link | Folder | 項目の名前が変更されたときに発生します。 | | preview | File | ファイルがプレビューされたときに発生します。 | | download | Array<File> | 項目がダウンロードされたときに発生します。 | | delete | Array<File> | 項目が削除されたときに発生します。 | | upload | Array<File> | 項目がアップロードされたときに発生します。 | | navigate | Folder | フォルダ内に移動したときに発生します。 | | create | Folder | 新しいフォルダが作成されたときに発生します。 | ## キーボードショートカット クリックによって手動で、またはJavaScriptや上記の`autoFocus`プロパティによってプログラムで項目グリッドがフォーカスされていると、以下のキーボードショットカットが機能します (対応する操作が適切で許可されている場合)。 | キー | 動作 | | --- | --- | | Arrow Up | 前の項目行 | | Arrow Down | 次の項目行 | | Ctrl/Cmd + Arrow Up | 最初の項目行 | | Ctrl/Cmd + Arrow Down | 最後の項目行 | | / | 検索 | | Shift + X | 項目行を選択 | | Delete | 選択した項目を削除 | | Enter | 選択した項目を開く | | Shift + R | 選択した項目の名前を変更 | | Shift + S | 選択した項目を共有 | | Shift + D | 選択した項目をダウンロード | | g then f | ルートフォルダに移動 | | g then u | 現在のフォルダにアップロード | | g then b | ルートフォルダの階層リンクをフォーカス | | g then r | 最近使用した項目 | ## スコープ アプリケーションで、エンドユーザーがコンテンツエクスプローラ機能のサブセットのみにアクセスできるようにする必要がある場合は、[ダウンスコープ](guide://authentication/tokens/downscope)を使用して、アクセストークンを適切にダウンスコープして必要な権限のセットを含むトークンを生成し、コンテンツエクスプローラを初期化するエンドユーザークライアントに安全に渡すことができます。 以下は、ダウンスコープと一緒に使用する、UI Element固有の新しいスコープのセットです。こうしたスコープにより、開発者は、ダウンスコープされたトークンに適切なスコープを構成して、コンテンツエクスプローラのUIコントロールを有効/無効にすることができます。詳細については、[Box UI Elementsの専用スコープ](guide://api-calls/permissions-and-errors/scopes)を参照してください。 ### 基本スコープ | スコープ名 | 付与される権限 | | --- | --- | | base_explorer | ユーザー/ファイル/トークンの権限に基づいて、フォルダツリー内のコンテンツへのアクセスを許可します。 | ### 機能のスコープ | スコープ名 | 付与される権限 | | --- | --- | | item_preview | ユーザーがクリックしたときにファイルのプレビューを自動的に有効にします (プレビューUI Elementを参照する必要があります)。 | | item_download | ファイル/フォルダのコンテンツのダウンロードを許可します。 | | item_rename | ファイル/フォルダの名前変更を許可します。 | | item_share | ダウンスコープリクエストの「resource」で指定されたリソースの共有を許可します。 | | item_delete | ファイル/フォルダの削除を許可します。 | ### サンプルのシナリオ | シナリオ | スコープ | | --- | --- | | ユーザーがフォルダ構造内を移動する (基本機能) | base_explorer | | ユーザーが基本機能とプレビューを必要とする | base_explorer + item_preview | | ユーザーが基本機能、プレビュー、およびダウンロードを必要とする | base_explorer + item_preview + item_download | | ユーザーが基本機能、プレビュー、ダウンロード、およびファイル/フォルダ名の変更を必要とする | base_explorer + item_preview + item_download + item_rename | | ユーザーがすべての機能 (基本、プレビュー、ダウンロード、名前の変更、共有、アップロード、および削除) を必要とする | base_explorer + item_preview + item_download + item_rename + item_delete + item_share + item_upload | ## カスタム操作 コンテンツエクスプローラとContent Pickerでは、ファイルやフォルダの [**その他のオプション**] メニューの操作を拡張できます。カスタムオプションは、ユーザーが省略記号ボタンをクリックすると表示されます。 [**その他のオプション**] メニューをカスタマイズするには、カスタム操作の配列を`itemActions`に渡します。 ``` contentExplorer.show(configData.FOLDER_ID, configData.ACCESS_TOKEN, { container: ".container", itemActions: customActions, }); ``` この配列には、複数の操作を含めることができます。操作オブジェクトには、`label`および`onAction`コールバック関数を含める必要があります。`file`または`folder`の値を渡すことで、特定の項目の`type`のみに表示されるようカスタム操作にフィルタをかけることができます。`filter`値は、特定のファイル拡張子など、高度なフィルタに使用します。 ``` const customActions = [ { label: "Preview in New Window", onAction: (item) => alert('action ' + item), type: 'file', }, { label: "Open in Box.com", onAction: (item) => window.open("https://app.box.com"), }, { label: "Export", onAction: (item) => console.log('action ' + item), filter: (item) => item.extension?.toLowerCase() === 'pdf', } ]; ``` CodePenで実装例を確認してください。 **Source:** [https://ja.developer.box.com/guides/embed/ui-elements/explorer/](https://ja.developer.box.com/guides/embed/ui-elements/explorer/) --- ### コンテンツエクスプローラ - メタデータビュー **Type:** guide | **Category:** Boxの埋め込み | **Section:** Developer Guides … # コンテンツエクスプローラ - メタデータビュー コンテンツエクスプローラを使用すると、メタデータに基づいてファイルを表示することもできます。メタデータビューでは、[メタデータテンプレート](r://get-metadata-templates-id)と[メタデータクエリ](g://metadata/queries)を使用して、表示するデータを探します。 ## 前提条件 - [コンテンツエクスプローラ](g:///embed/ui-elements/explorer)ガイドを読む。 - [メタデータの用語](g://metadata/#metadata-terminology)を確認する。 - [メタデータクエリ](g://metadata/queries)に関する情報を確認する。 ## アプリの作成と構成 1. [Boxアプリを作成します](g:///applications/app-types)。 [CORSドメイン] にローカルでの開発用のアドレスを追加します。 2. [開発者トークン](g://authentication/tokens/developer-tokens)を生成します。 ## メタデータテンプレートの作成 次の手順では、メタデータテンプレートを作成します。 1. [メタデータAPI](g:///metadata/templates/create)または[管理コンソール](https://support.box.com/hc/en-us/articles/360044194033-Customizing-Metadata-Templates)を使用してテンプレートを作成します。 2. すでに作成済みのテンプレートをBoxフォルダに適用します。必ずカスケードポリシーを有効にするようにしてください。詳細な手順については、[テンプレートのカスタマイズと適用の手順](https://support.box.com/hc/en-us/articles/360044196173-Using-Metadata)を参照してください。 メタデータテンプレートは、ファイルにも適用できます。 ### 表示名と主なパラメータ - `displayName`パラメータは、管理コンソールに表示されるテンプレートの表示名です。 - `templateKey`パラメータは、テンプレートの一意の識別子です。これは、メタデータテンプレート作成の対象となる企業全体で一意である必要があります。`templateKey`パラメータを指定しなかった場合は、APIによって、`displayName`の値を基に一意の識別子が作成されます。 - `[fields].displayName`パラメータは、ウェブアプリおよびモバイルアプリでユーザーに表示されるフィールドの表示名です。 - `[fields].key`パラメータは、テンプレート内の特定のフィールドの一意の識別子です。この識別子は、そのフィールドが属するテンプレート内で一意である必要があります。 ## メタデータビューの表示 次に、コンテンツエクスプローラに渡される必須のプロパティを入力します。作業を簡単にするために、基本的なReactアプリに基づいた[サンプルプロジェクト](https://github.com/box-community/content-explorer-metadata/tree/main)を使用して、メタデータビューを起動できます。 1. メタデータのサンプルプロジェクトを複製します。 2. [`App.js`](https://github.com/box-community/content-explorer-metadata/blob/main/src/App.js)内のプレースホルダを実際の値で更新します。 | パラメータ | 説明 | | --- | --- | | DEVELOPER_TOKEN | 開発者コンソールで生成された開発者トークン。 | | ENTERPRISE_ID | Boxアプリケーションの [一般設定] タブからコピーしたEnterprise ID。 | | METADATA_TEMPLATE_NAME | 作成済みのメタデータテンプレートのtemplateKey。注: 適切な名前を指定済みであることを確認するには、メタデータAPIを使用して名前を取得するか、管理コンソールでURLから名前をコピーします。 UIでテンプレート名を変更しても、変更されるのは表示名のみです。コンポーネントで使用する名前は、常に最初に指定した名前になります。 | | METADATA_SOURCE | メタデータのソース。これは、スコープ、Enterprise ID、メタデータキーを組み合わせた文字列です。 | | ROOTFOLDER_ID | メタデータクエリを適用してフィルタがかけられたファイルを表示するBoxフォルダのID。 | `defaultView`、`fieldsToShow`、`metadataQuery`の各パラメータは、すでにサンプルプロジェクトで定義されています。これらのパラメータの例は、サンプルプロジェクトで確認できます。 | パラメータ | 説明 | | --- | --- | | defaultView | メタデータビューを描画するための必須プロパティ。指定されていない場合は、通常のファイルビューが表示されます。 | | fieldsToShow | コンテンツエクスプローラに表示する特定のメタデータ列を追加または非表示にします。 | | metadataQuery | ファイルに設定されているメタデータを検索してそのファイルを探す方法を指定します。メタデータクエリの詳細については、こちらのガイドを参照してください。 | 1. コンテンツエクスプローラコンポーネントに必須パラメータを渡します。 コンテンツエクスプローラのメタデータビューを含むReactコンポーネントのサンプルコードは次のようになります。 ``` function App() { const token = "<DEVELOPER_TOKEN>"; const rootFolderID = "<ROOTFOLDER_ID>"; const EID = "<ENTERPRISE_ID>"; const templateName = "<METADATA_TEMPLATE_NAME>"; const metadataSource = `enterprise_${EID}.${templateName}`; const metadataSourceFieldName = `metadata.${metadataSource}`; const metadataQuery = { from: metadataSource, query: "key = :arg1", query_params: { arg1: "value" }, ancestor_folder_id: 0, fields: [ `${metadataSourceFieldName}.name`, `${metadataSourceFieldName}.last_contacted_at`, `${metadataSourceFieldName}.industry`, `${metadataSourceFieldName}.role`, ], }; const fieldsToShow = [ // canEdit propetry determines if the user can edit the metadata directly from Content Explorer component { key: `${metadataSourceFieldName}.name`, canEdit: false }, // displayName alows to change the label on metadata column { key: `${metadataSourceFieldName}.industry`, canEdit: false, displayName: "alias" }, { key: `${metadataSourceFieldName}.last_contacted_at`, canEdit: true }, { key: `${metadataSourceFieldName}.role`, canEdit: true }, ]; const defaultView = "metadata"; return ( <IntlProvider locale="en"> <div className="App"> <header className="App-header"> <h2>Metadata view in Content Explorer</h2> </header> <section> <div className="metadata-based-view"> <ContentExplorer rootFolderId={rootFolderID} token={token} metadataQuery={metadataQuery} fieldsToShow={fieldsToShow} defaultView={defaultView} /> </div> </section> </div> </IntlProvider> ); } export default App; ``` ## メタデータキー 表示するフィールドを決定するには、コンテンツエクスプローラで、[表示名](e://post-metadata-templates-schema/#param-fields-displayName)ではなく、メタデータの[フィールドキー](e://post-metadata-templates-schema/#param-fields-key)を使用します。表示名は管理コンソールやユーザービューで確認できる一方、フィールドキーはAPIを使用して取得できます。 フィールドキーは、メタデータの表示名を変更した場合でも変わりません。これにより、UIビューでメタデータが変更されても、この機能は正常に動作します。 ### メタデータキーのサニタイズ [キー](e://post-metadata-templates-schema/#param-fields-key)は、英数字のみに制限されています。 - ハイフン`-`とアンダースコア`_`は許可されていません。 - 許可されているのは文字 (`a-z, A-Z`) と数字 (`0-9`) のみです。 **ラテン語以外の文字:** キーにラテン語以外のアルファベット (キリル文字、アラビア語、中国語など) が含まれている場合、それらは自動的に共通識別子に変更されます。 - 最初に出現した文字は`field` - それ以降出現した文字は`field1`、`field2`と続く キーは、表示名に基づいています。 **ヒント**: 詳細なフローについては、[メタデータビューに関するブログ記事](https://medium.com/box-developer-blog/metadata-view-in-box-content-explorer-4978e47e97e9)を参照してください。 **Source:** [https://ja.developer.box.com/guides/embed/ui-elements/explorer-metadata/](https://ja.developer.box.com/guides/embed/ui-elements/explorer-metadata/) --- ### コンテンツの入力 **Type:** guide | **Category:** ユーザー | **Section:** Developer Guides コンテンツの入力 サービスアカウントのetc/skel構造を使用してアーキテクチャファイルを定義すると、次のスクリプトを使用してskelの下にあるすべての項目を新しいユーザーのルートディレクトリに直接コピーできます。 # コンテンツの入力 サービスアカウントの`etc/skel`構造を使用してアーキテクチャファイルを定義すると、次のスクリプトを使用して`skel`の下にあるすべての項目を新しいユーザーのルートディレクトリに直接コピーできます。 ``` 'use strict' const box = require('box-node-sdk'); const fs = require('fs'); const skelFolderId = "45117847998"; const userID = "275111793"; let configFile = fs.readFileSync('config.json'); configFile = JSON.parse(configFile); let session = box.getPreconfiguredInstance(configFile); let serviceAccountClient = session.getAppAuthClient("enterprise"); (async () => { // The userID can be obtained when creating the user via the // API or by using the search users feature. // The skel folder ID shouldn't ever change unless it's deleted and recreated. await copySkelDirectoryForUser(userID, skelFolderId, serviceAccountClient); })(); async function copySkelDirectoryForUser(userID, skelFolderId, boxClient) { // Enable iterators in case there are more than the // default limit of items under the skel directory. boxClient._useIterators = true; // You collaborate the user temporarily on the skel directory // to copy all items into that user's root folder. let collabSkelFolder; try { collabSkelFolder = await boxClient.collaborations.createWithUserID(userID, skelFolderId, boxClient.collaborationRoles.EDITOR); } catch (e) { // Handle that the collaboration on the skel folder could already exist. if (e.response.body.code === 'user_already_collaborator') { let collaborationsIterator = await boxClient.folders.getCollaborations(skelFolderId); let collaborations = await autoPage(collaborationsIterator); let results = collaborations.filter((collaboration) => { return collaboration.accessible_by.id === userID; }); console.log(results); if (results.length > 0) { collabSkelFolder = results[0]; } else { throw new Error("Couldn't create new collaboration or located existing collaboration."); } } else { throw e; } } console.log(collabSkelFolder); // Switching context to make calls on behalf of the user. // To access this user's root folder, the boxClient needs // to be scoped to make API calls as the user. boxClient.asUser(userID); // Iterate over all the items under the skel directory. let skelFolderItemsIterator = await boxClient.folders.getItems(skelFolderId); let skelFolderCollection = await autoPage(skelFolderItemsIterator); console.log(skelFolderCollection); // Now, as the user, copy the folders and files into // the user's root folder -- folder ID '0'. let copyTasks = []; skelFolderCollection.forEach((item) => { if (item.type === 'folder') { copyTasks.push(boxClient.folders.copy(item.id, '0') .catch((e) => { let itemId = handleConflictError(e); if (itemId) { console.log(itemId); return boxClient.folders.get(itemId); } else { throw e; } })); } else if (item.type === 'file') { copyTasks.push(boxClient.files.copy(item.id, '0') .catch((e) => { let itemId = handleConflictError(e); if (itemId) { console.log(itemId); return boxClient.files.get(itemId); } else { throw e; } })); } else { console.log("Unable to resolve item type to known types..."); } }); let copiedItems = await Promise.all(copyTasks); console.log(copiedItems); // Switching the boxClient context back to that of the service account. boxClient.asSelf(); /* Since the service account owns the skel directory, boxClient needs to make API calls as the service account to remove the temporary collaboration on the skel directory. */ try { await boxClient.collaborations.delete(collabSkelFolder.id); console.log("Removed collaboration on skel..."); } catch (e) { console.log("Couldn't remove skel collaboration..."); console.log(e.respose.body); } function handleConflictError(e) { if (e && e.response && e.response.body) { let errorBody = e.response.body; if (errorBody.status === 409) { if (errorBody.context_info && errorBody.context_info.conflicts && errorBody.context_info.conflicts) { let conflict = errorBody.context_info.conflicts; if (conflict && conflict.id) { return conflict.id; } } } } } function autoPage(iterator, collection = []) { let moveToNextItem = async () => { let item = await iterator.next(); if (item.value) { collection.push(item.value); } if (item.done !== true) { return moveToNextItem(); } else { return collection; } } return moveToNextItem(); } } ``` ``` package com.box; import java.io.BufferedReader; import java.nio.charset.Charset; import java.nio.file.Files; import java.nio.file.Path; import java.nio.file.Paths; import java.util.ArrayList; import java.util.Collection; import java.util.Optional; import java.util.regex.Matcher; import java.util.regex.Pattern; import com.box.sdk.BoxAPIException; import com.box.sdk.BoxCollaboration; import com.box.sdk.BoxConfig; import com.box.sdk.BoxDeveloperEditionAPIConnection; import com.box.sdk.BoxFile; import com.box.sdk.BoxFolder; import com.box.sdk.BoxItem; import com.box.sdk.BoxUser; import com.eclipsesource.json.JsonObject; public class BoxPlayground { public static void main(String[] args) throws Exception { Path configPath = Paths.get("config.json"); try (BufferedReader reader = Files.newBufferedReader(configPath, Charset.forName("UTF-8"))) { String skelFolderId = "45117847998"; String userId = "275111793"; BoxConfig boxConfig = BoxConfig.readFrom(reader); BoxDeveloperEditionAPIConnection serviceAccountClient = BoxDeveloperEditionAPIConnection .getAppEnterpriseConnection(boxConfig); BoxDeveloperEditionAPIConnection userClient = BoxDeveloperEditionAPIConnection.getAppUserConnection(userId, boxConfig); BoxFolder skelFolder = new BoxFolder(serviceAccountClient, skelFolderId); BoxCollaboration.Info skelFolderCollaboration; try { skelFolderCollaboration = skelFolder.collaborate(new BoxUser(serviceAccountClient, userId), BoxCollaboration.Role.EDITOR); } catch (BoxAPIException e) { System.out.println("Searching for existing collaborator."); JsonObject errorMessage = JsonObject.readFrom(e.getResponse()); String code = errorMessage.get("code").asString().intern(); if (code == "user_already_collaborator") { System.out.println("Already collaborated..."); Collection<BoxCollaboration.Info > collaborations = skelFolder.getCollaborations(); System.out.println(collaborations.size()); Optional<BoxCollaboration.Info > results = collaborations.stream().filter(c -> { return c.getAccessibleBy().getID().intern() == userId; }).findFirst(); if (results.isPresent()) { skelFolderCollaboration = results.get(); } else { throw new Exception("Couldn't create new collaboration or find existing collaboration."); } } else { throw e; } } System.out.println(skelFolderCollaboration.getID()); BoxFolder collabedSkelFolder = new BoxFolder(userClient, skelFolderId); ArrayList<BoxItem.Info > copiedItems = new ArrayList<>(); for (BoxItem.Info itemInfo: collabedSkelFolder) { if (itemInfo instanceof BoxFile.Info) { BoxFile.Info fileInfo = (BoxFile.Info) itemInfo; BoxFile copyFile = new BoxFile(userClient, fileInfo.getID()); BoxFile.Info copiedFile; try { copiedFile = copyFile.copy(BoxFolder.getRootFolder(userClient)); } catch (BoxAPIException e) { System.out.println(e.getMessage()); String conflictId = getIdFromConflict(e.getMessage()); System.out.println(conflictId); copiedFile = new BoxFile(userClient, conflictId).getInfo(); } copiedItems.add((BoxItem.Info) copiedFile); } else if (itemInfo instanceof BoxFolder.Info) { BoxFolder.Info folderInfo = (BoxFolder.Info) itemInfo; BoxFolder copyFolder = new BoxFolder(userClient, folderInfo.getID()); BoxFolder.Info copiedFolder; try { copiedFolder = copyFolder.copy(BoxFolder.getRootFolder(userClient)); } catch (BoxAPIException e) { System.out.println(e.getMessage()); String conflictId = getIdFromConflict(e.getMessage()); System.out.println(conflictId); copiedFolder = new BoxFolder(userClient, conflictId).getInfo(); } copiedItems.add((BoxItem.Info) copiedFolder); } } System.out.println("Copied " + copiedItems.size() + " items from the skel directory."); BoxCollaboration tempSkelCollab = new BoxCollaboration(serviceAccountClient, skelFolderCollaboration.getID()); tempSkelCollab.delete(); System.out.println("Removed temporary skel directory collaboration."); } } private static String getIdFromConflict(String message) { String id = ""; Pattern p = Pattern.compile("\"id\":\"[0-9]+\""); Pattern p2 = Pattern.compile("[0-9]+"); Matcher m = p.matcher(message); if (m.find()) { String sub = m.group(); Matcher m2 = p2.matcher(sub); if (m2.find()) { id = m2.group(); } } return id; } } ``` ``` using System; using System.Collections; using System.Collections.Generic; using System.IO; using System.Linq; using System.Threading.Tasks; using Box.V2; using Box.V2.Config; using Box.V2.Exceptions; using Box.V2.JWTAuth; using Box.V2.Models; using Newtonsoft.Json.Linq; namespace BoxPlayground { public class Program { static void Main(string[] args) { ExecuteMainAsync().Wait(); } private static async Task ExecuteMainAsync() { using(FileStream fs = new FileStream("./config.json", FileMode.Open)) { var skelFolderId = "45117847998"; var userId = "275111793"; var session = new BoxJWTAuth(BoxConfig.CreateFromJsonFile(fs)); var client = session.AdminClient(session.AdminToken()); var userClient = session.UserClient(session.UserToken(userId), userId); BoxCollaboration collabSkelFolder; try { collabSkelFolder = await client.CollaborationsManager.AddCollaborationAsync( new BoxCollaborationRequest { AccessibleBy = new BoxCollaborationUserRequest { Id = userId }, Item = new BoxRequestEntity { Id = skelFolderId, Type = BoxType.folder }, Role = BoxCollaborationRole.Editor.ToString() }); } catch(BoxException e) { var errorMessage = JObject.Parse(e.Message); if (errorMessage.GetValue("code").ToString() == "user_already_collaborator") { System.Console.WriteLine("Already a collaborator"); var collaborations = await client.FoldersManager.GetCollaborationsAsync(skelFolderId); var existingCollab = collaborations.Entries.Find((collaboration) = >{ return collaboration.AccessibleBy.Id == userId; }); if (existingCollab != null) { collabSkelFolder = existingCollab; } else { throw new Exception("Couldn't create new collaboration or find existing collaboration"); } } else { throw e; } } var items = await userClient.FoldersManager.GetFolderItemsAsync(skelFolderId, limit: 1000, autoPaginate: true); var copyTasks = new List < Task < BoxItem >> (); items.Entries.ForEach((item) = >{ if (item.Type == BoxType.folder.ToString()) { copyTasks.Add(userClient.FoldersManager.CopyAsync(new BoxFolderRequest { Id = item.Id, Parent = new BoxRequestEntity { Id = "0" } }).ContinueWith((folder) = >{ try { return (BoxItem) folder.Result; } catch(Exception e) { var errorMessage = JObject.Parse(e.InnerException.Message); if (errorMessage.GetValue("status").ToObject < int > () == 409) { System.Console.WriteLine("Conflict found"); System.Console.WriteLine(errorMessage.SelectToken("context_info.conflicts.id")); return (BoxItem) userClient.FoldersManager.GetInformationAsync(errorMessage.SelectToken("context_info.conflicts.id").ToString()).Result; } else { throw e; } } })); } else if (item.Type == BoxType.file.ToString()) { copyTasks.Add(userClient.FilesManager.CopyAsync(new BoxFileRequest { Id = item.Id, Parent = new BoxRequestEntity { Id = "0" } }).ContinueWith((file) = >{ try { return (BoxItem) file.Result; } catch(Exception e) { var errorMessage = JObject.Parse(e.InnerException.Message); if (errorMessage.GetValue("status").ToObject < int > () == 409) { System.Console.WriteLine("Conflict found"); System.Console.WriteLine(errorMessage.SelectToken("context_info.conflicts.id")); return (BoxItem) userClient.FilesManager.GetInformationAsync(errorMessage.SelectToken("context_info.conflicts.id").ToString()).Result; } else { throw e; } } })); } else { System.Console.WriteLine("Couldn't process this item..."); } }); var copiedItems = await Task.WhenAll(copyTasks); System.Console.WriteLine($ "Copied {copiedItems.Count()} items from the skel directory."); if (await client.CollaborationsManager.RemoveCollaborationAsync(collabSkelFolder.Id)){ System.Console.WriteLine("Removed temporary skel directory collaboration..."); System.Console.WriteLine("Complete!"); } else { System.Console.WriteLine("Something went wrong when removing skel directory collaboration."); } } } } } ``` **Source:** [https://ja.developer.box.com/guides/users/provision/populate-content/](https://ja.developer.box.com/guides/users/provision/populate-content/) --- ### コンテンツプレビュー **Type:** guide | **Category:** Boxの埋め込み | **Section:** Developer Guides コンテンツプレビュー Box Content Preview UI Elementを使用すると、開発者は、Boxファイルの高品質でインタラクティブなプレビューをデスクトップアプリやモバイルウェブアプリに埋め込むことができます。 コンテンツプレビューUI Element… # コンテンツプレビュー Box Content Preview UI Elementを使用すると、開発者は、Boxファイルの高品質でインタラクティブなプレビューをデスクトップアプリやモバイルウェブアプリに埋め込むことができます。 ## コンテンツプレビューUI Elementとコンテンツプレビューライブラリ Reactコンポーネントは[Box Content Previewライブラリ](https://github.com/box/box-content-preview)のラッパーであるため、コンテンツプレビューUI Elementの動作は、他のUI Elementsとは異なります。また、プレビューライブラリのバンドルはローカライズされているため、コンテンツプレビューUI Elementでは言語 (デフォルトは`en-US`) を渡す必要もあります。 ``` var ContentPreview = require("./ContentPreview").default; <IntlProvider locale="en"> <ContentPreview contentSidebarProps={{ detailsSidebarProps: { hasAccessStats: true, hasClassification: true, hasNotices: true, hasProperties: true, hasRetentionPolicy: true, hasVersions: true, }, features: FEATURES, hasActivityFeed: true, hasMetadata: true, hasSkills: true, hasVersions: true, }} hasHeader={true} features={FEATURES} fileId={FILE_ID} token={TOKEN} {...PROPS} /> </IntlProvider>; ``` コンテンツプレビューライブラリは、ファイルとその変換後のレプリゼンテーションに関する情報をBox APIを介して取得し、ファイルタイプに適したビューアーを選択して、必要な静的アセットとファイルレプリゼンテーションを動的に読み込み、最後にファイルをレンダリングします。 また、このUI Elementを使用すると、複数のファイルのプレビューを同じコンテナに読み込むことができ、ファイル間を移動するための矢印も表示されます。これにより、メインのBoxウェブアプリと[期限付きで埋め込まれたリンクオブジェクト](r://file--full/#param-expiring_embed_link)でのプレビューが強化されます。 ## インストール NPMまたはBox CDN経由でBox UI Elementsをインストールする方法は、[こちら](g://embed/ui-elements/installation)を参照してください。 ## 認証 UI Elementは認証に依存しない方法で設計されているため、Boxの管理対象ユーザーとBox以外のユーザー (App User) のどちらでも機能します。その理由は、UI Elementは認証に[トークン](g://authentication/tokens/developer-tokens)のみを想定していて、Boxにはトークンの生成方法としてOAuthとJWTの2つがあるからです。 認証方法の選択について確認する ## サポートされているファイルの種類 Box Content Previewでは、ドキュメントと画像のほとんどの形式、HD動画、3Dモデル、360度画像、360度動画など、120以上のファイルタイプがサポートされています。サポートされているファイルの種類については、[こちら](https://support.box.com/hc/ja/articles/360043695794-Box-Content-Preview%E3%81%A7%E3%82%B5%E3%83%9D%E3%83%BC%E3%83%88%E3%81%95%E3%82%8C%E3%82%8B%E3%83%95%E3%82%A1%E3%82%A4%E3%83%AB)で確認できます。 サポートされているファイルの種類に他のオブジェクト (`DWG`ファイルなど) への参照が含まれている場合、Boxプレビューではこれらの参照がサポートされていないことに注意してください。サポートされていない参照を含むDWGファイルを表示しているすべてのエンドユーザーには、別の手順でワークフローを完了するよう促す通知が表示されます。 ## デモ ナビゲーション用の矢印を使用すると、さまざまなファイルタイプをプレビューできます。 ## API ``` const { Preview } = Box; const preview = new Preview(); /** * Shows a preview. * * @public * @param {string} fileId - File ID to preview * @param {string} accessToken - Box API access token * @param {Object} [options] - Options * @return {void} */ preview.show(fileId, accessToken, options); /** * Hides the preview. * * @return {void} */ preview.hide(); /** * Prints the current file, if printable. * * @return {void} */ preview.print(); /** * Downloads the current file. * * @return {void} */ preview.download(); /** * Resizes the current preview, if applicable. This function only needs to * be called when preview's viewport has changed while the window has not. * If the window is resizing, then preview will automatically resize itself. * * @return {void} */ preview.resize(); /** * Adds an event listener to the preview. Listeners should be added * before calling show() so no events are missed. * * @param {string} eventName - Name of the event * @param {Function} listener - Callback function * @return {void} */ preview.addListener(); /** * Removes an event listener from the preview. * * @param {string} eventName - Name of the event * @param {Function} listener - Callback function * @return {void} */ preview.removeListener(eventName, listener); /** * Removes all event listeners from the preview. * * @return {void} */ preview.removeAllListeners(); ``` ### パラメータ | パラメータ | 型 | 説明 | | --- | --- | --- | | fileId | String | BoxファイルID。 | | accessToken | String | 使用するBox APIアクセストークン。このトークンには、上記のフォルダに対する読み取り/書き込みアクセス権限が必要です。このトークンのために渡される値は、エクスプローラの表示中は有効期限切れにならないことが前提となっています。 | | options | Object | 省略可能なオプション。詳細は以下を参照してください。たとえば、contentExplorer.show(FOLDER_ID, TOKEN, {canDelete: false})を使用すると、削除オプションが非表示になります。 | ### オプション | パラメータ | 型 | デフォルト | 説明 | | --- | --- | --- | --- | | container | String | document.body | プレビューが配置されるコンテナのCSSセレクタ | | sharedLink | String | | 共有リンクのURL。ファイルが共有されており、アクセストークンがファイルの所有者またはコラボレータに属していない場合は必須です。 | | sharedLinkPassword | String | | 共有リンクのパスワード。共有リンクにパスワードが設定されている場合は必須です。 | | collection | Array | | プレビューするファイルIDのリスト。これを使用すると、同じコンテナ内にある複数のファイルのプレビューが表示され、ファイル間を移動するための矢印も表示されます。このリストにはFILE_IDを含める必要があること、およびSDKでは共有リンクまたはパスワードが必要なファイルのコレクションがサポートされないことに注意してください。 | | header | String | light | ヘッダーの表示と背景色を制御する値。ヘッダーなしの場合はnone、ヘッダーと背景を薄い色にする場合はlight、ヘッダーと背景を濃い色にする場合はdarkを使用します。 | | logoUrl | String | | ヘッダーに表示するカスタムロゴのURL。この値が「box」という文字列の場合は、Boxのロゴが表示されます。 | | showAnnotations | Boolean | false | ヘッダーの注釈ボタンとコンテンツの注釈を表示するかどうか。 | | showDownload | Boolean | false | ダウンロードボタンをヘッダーに表示するかどうか。また、印刷をサポートするビューアーに印刷ボタンを表示するかどうかも制御します。このオプションがアクセストークンに対するダウンロード権限より優先されることはありません。 | ## トークン生成関数 プレビューライブラリでは、オプションで、文字列トークンの代わりに、トークン生成関数を使用できます。トークン生成関数を使用すると、プレビューで使用するトークンを動的に決定できます。たとえば、ファイルごとに異なるアクセストークンを渡したり、プレビューを表示する前にトークンが更新されて有効であることを確認したりできます。トークン生成関数ではPromiseが返され、プレビューされるすべてのファイルに適用される単一の文字列トークンか、これらのファイルのアクセストークンへの指定のファイルIDのマップに解決されます。 ``` // Example token generator function that resolves to a single access token var singleTokenGenerator = function () { return someApi.getToken().then(function (data) { return data.token; }); }; // Example token generator function that resolves to a map of tokens var mapTokenGenerator = function () { return Promise.resolve({ file_1234: "some_token_abcd", file_2345: "some_token_bcde", }); }; ``` ## イベント プレビューオブジェクトは、イベントにバインドするための`addListener`と`removeListener`を公開します。イベントリスナーは`show()`が呼び出される前にバインドする必要があります。そうしないと、イベントが見つからない可能性があります。 ``` const listener = (value) => { // Do something with value }; // Attach listener before calling show otherwise events can be missed var preview = new Box.Preview(); preview.addListener(EVENTNAME, listener); // Show a preview preview.show(...); // Remove listener when needed preview.removeListener(EVENTNAME, listener); ``` `EVENTNAME`には、以下のいずれかを指定できます。 - `viewer`イベントは、ビューアーインスタンスが最初に使用可能になったときにトリガーされます。これは、`load`イベントにも含まれているプロパティと同じオブジェクトです。プレビューでは、`load`の前にこのイベントがトリガーされるため、クライアントは、`load`イベントがトリガーされる前にそのリスナーをアタッチできます。 - `load`イベントは、`show()`が呼び出されたときかプレビュー間の移動が発生したときに、プレビューが読み込まれるたびにトリガーされます。イベントデータには以下の内容が含まれます。 ``` error: 'message', // Error message if any error occurred while loading viewer: {...}, // Instance of the current viewer object if no error occurred metrics: {...}, // Performance metrics file: {...} // Box file object with properties defined in file.js ``` - `navigate`イベントは、移動が発生したときにトリガーされます。イベントには移動先のファイルのファイルIDが含まれており、このイベントは`load`の前にトリガーされます。 - `notification`イベントは、プレビューラッパーまたはいずれかのビューアーで警告や致命的ではないエラーなどの通知を表示する場合にトリガーされます。イベントデータには以下の内容が含まれます。 ``` message: 'message', // Message to show type: 'warning' // 'warning', 'notice', or 'error' ``` - `viewerevent`: ビューアーごとに、一連の独自のイベントがトリガーされます。たとえば、画像ビューアーでは`rotate`や`resize`などがトリガーされるのに対し、別のビューアーでは別の一連のイベントがトリガーされる場合があります。プレビューラッパーは、以下を含むイベントデータとともに、プレビューレベルでイベントを再発行します。 ``` event: EVENTNAME, // Event name data: DATA, // Event data object viewerName: VIEWERNAME, // Name of the viewer. See VIEWERNAME above fileId: fileId // The file ID ``` ### イベントの使用例 ``` var preview = new Box.Preview(); preview.addListener("viewer", (viewer) => { viewer.addListener("rotate", () => { // Do something when a viewer rotates a preview }); }); preview.addListener("load", (data) => { const viewer = data.viewer; viewer.addListener("rotate", () => { // Do something when a viewer rotates a preview }); }); preview.addListener("viewerevent", (data) => { if (data.viewerName === "Image") { if (data.event === "rotate") { // Do something when an image preview is rotated } } else if (data.viewerName === "Image360") { if (data.event === "rotate") { // Do something different when a 360-degree image is rotated } } else { } }); preview.addListener("rotate", (data) => { if (data.viewerName === "Image") { // Do something when an image preview is rotated } else if (data.viewerName === "Image360") { // Do something different when a 360-degree image is rotated } else { } }); ``` ## 注釈 コンテンツプレビューで、V4の[注釈](g://embed/ui-elements/annotations.md)を有効にすることができます。新しい注釈はリアルタイムで同期されます。 V4の注釈をプレビューに追加するには、以下の手順に従います。 1. `npm i box-annotations@latest`を実行し、[Boxの注釈](https://github.com/box/box-annotations)をインストールします。 Boxの注釈のバージョンは、メジャーバージョン4以上である必要があります。 1. `npm i box-ui-elements@16.0.0`を実行し、注釈に関連した変更を含む[BUIE](https://github.com/box/box-ui-elements/releases/tag/v16.0.0)バージョンをインストールします。 Box UI Elementsは、V4の注釈が十分に機能している、使用可能な最小バージョンである必要があります。 1. 次のように、コンテンツプレビューとBoxの注釈をアプリケーションにインポートします。 ``` import boxAnnotations from "https://cdn.skypack.dev/box-annotations@latest"; var file_id = "YOUR FILE ID"; var accessToken = "YOUR ACCESS TOKEN"; /* Enable annotations in sidebar */ var contentSidebarProps = { hasActivityFeed: true, features: { activityFeed: { annotations: { enabled: true, }, }, }, }; var options = { container: ".previewer", contentSidebarProps: contentSidebarProps, /* Enable annotations in preview */ enableAnnotationsDiscoverability: true, enableAnnotationsImageDiscoverability: true, showAnnotations: true, showAnnotationsControls: true, showAnnotationsDrawingCreate: true, }; /* BoxAnnotations */ var annotations = new BoxAnnotations(); /* Box Preview */ var contentPreviewer = new Box.ContentPreview(); /* Set annotation into previewer */ options["boxAnnotations"] = annotations; /* Show previewer */ contentPreviewer.show(file_id, accessToken, options); ``` プロパティ`features: { activityFeed: { annotations: { enabled: true } } } } `は、今後変更される可能性があります。 ``` <link href="https://cdn01.boxcdn.net/platform/elements/16.0.0/en-US/preview.css" rel="stylesheet" type="text/css"></link> <script src="https://cdn01.boxcdn.net/platform/elements/16.0.0/en-US/preview.js"></script> <style> .previewer { border: 1px solid #eee; height: 500px; width: 100%; } </style> <div class="previewer"></div> <script type="module" src="./script.js"></script> ``` ## Box AI for UI Elements Box AI for UI Elementsは、追加機能によってコンテンツプレビューUI Elementを強化するため、開発者はPlatformアプリにBox Q&A AI機能を追加できるようになります。Box AIの機能で強化されたプレビューUI Elementでは、以下の機能を提供します。 - Q&Aとドキュメントの要約。 - Box AIとの会話をリセットする [**会話をクリア**] ボタン。 - 回答の下に表示される引用情報 (回答に含まれる場合)。 - 箇条書きや表などのマークダウン形式の応答のリクエストを可能にする、書式設定サポート。 - 可能な限り最適な応答を得られるように以前のコンテキストの参照を可能にする、質問履歴。質問履歴は現在のセッションの間のみ保持されます。 - 会話をサポートするために、デフォルトでチャットの先頭に表示される質問の候補。 ### Box AI for UI Elementsの有効化 コンテンツプレビューのヘッダーでBox AIウィンドウを有効にするには、以下の手順に従います。 NodeおよびReactのバージョンが`18.x`以上であることを確認します。 [Box AI for UI Elementsを含むnpmパッケージ](https://www.npmjs.com/package/box-ui-elements/v/22.0.0)をダウンロードするか、[Box CDN](g://embed/ui-elements/installation)から直接ダウンロードします。 以下のピア依存関係をインストールします。 - [`box-ai-content-answers`](https://www.npmjs.com/package/@box/box-ai-content-answers) - [`blueprint-web`](https://www.npmjs.com/package/@box/blueprint-web) - [`blueprint-web-assets`](https://www.npmjs.com/package/@box/blueprint-web-assets) そのためには、次のコマンドを実行します。 ``` npx install-peerdeps box-ui-elements@^22.0.0 ``` ### JavaScriptの使用 Box AIの機能を有効にするには、以下を渡します。 - `true`に設定した`hasHeader`プロパティ - `contentAnswersProps`プロパティ。デフォルトで`show`、`isCitationsEnabled`、`isMarkdownEnabled`、`isResetChatEnabled`、`suggestedQuestions`の各フィールドが含まれています。 ``` const preview = new Box.Preview(); const suggestedQuestions = [ { label: 'What are the key takeaways?', prompt: 'What are the key takeaways?', id: '1234', }, { label: 'Summarize this document', prompt: 'Summarize this document', id: '5678', }, ]; preview.show(<FILE_ID>, <TOKEN>, { container: '.preview-container', contentAnswersProps={ show: true, isCitationsEnabled: true, isMarkdownEnabled: true, isResetChatEnabled: true, suggestedQuestions } hasHeader: true, }); ``` ### Reactコンポーネントの使用 ReactコンポーネントのヘッダーにBox AI要素を追加することもできます。そのためには、以下を追加します。 - `true`に設定した`hasHeader`プロパティ - `contentAnswersProps`プロパティ。デフォルトで`show`、`isCitationsEnabled`、`isMarkdownEnabled`、`isResetChatEnabled`、`suggestedQuestions`の各フィールドが含まれています。 `suggestedQuestions`を適切にローカライズするには、プロンプトが翻訳されていることを確認してください。省略可能な`label`プロパティはスクリーンリーダー用であるのに対し、`prompt`プロパティはAIウィンドウでユーザーに表示されるテキストです。 ``` import ContentPreview from 'box-ui-elements/es/elements/content-preview'; import { IntlProvider } from "react-intl"; const suggestedQuestions = [ { label: 'Key takeaways', prompt: 'What are the key takeaways from this document?', id: '1234', }, { label: 'Summarize', prompt: 'Summarize this document', id: '5678', }, ]; export default () => { // Storing variables in the front end is not secure. // You will want to grab this value from a database for production const TOKEN = process.env.REACT_APP_BOX_DEVELOPER_TOKEN const FILE_ID = process.env.REACT_APP_BOX_PREVIEW_FILE_ID return ( <IntlProvider locale="en"> <ContentPreview contentAnswersProps={{ show: true, isCitationsEnabled: true, isMarkdownEnabled: true, isResetChatEnabled: true, suggestedQuestions }} fileId={FILE_ID} token={TOKEN} hasHeader=true /> </IntlProvider> ); }; ``` 今回のリリースで提供されるコンテンツプレビュー用のイベントリスナー (`onAsk`、`onClearConversations`、`onRequestClose`) を使用して、さらにアプリをカスタマイズできます。 ## スコープ アプリケーションで、エンドユーザーがコンテンツプレビュー機能のサブセットのみにアクセスできるようにする必要がある場合は、[ダウンスコープ](guide://authentication/tokens/downscope)を使用して、アクセストークンを適切にダウンスコープして必要な権限のセットを含むトークンを生成し、コンテンツプレビューを初期化するエンドユーザークライアントに安全に渡すことができます。 以下は、ダウンスコープと一緒に使用する、UI Element固有の新しいスコープのセットです。こうしたスコープにより、開発者は、ダウンスコープされたトークンに適切なスコープを構成して、コンテンツプレビューのUIコントロールを有効/無効にすることができます。詳細については、[Box UI Elementsの専用スコープ](g://api-calls/permissions-and-errors/scopes)を参照してください。 ### 基本スコープ | スコープ名 | 付与される権限 | | --- | --- | | base_preview | ファイルのプレビューのみをユーザーに許可します。 | ### 機能のスコープ | スコープ名 | 付与される権限 | | --- | --- | | item_download | 生成されたプレビューからのコンテンツのダウンロード/印刷を許可します。 | | annotation_edit | ユーザーに注釈の編集 (削除) を許可します。注: ハイライトによる注釈を使用できるようにするには、ユーザーに対して、ドキュメントのテキストレイヤーを有効にする必要があります。テキストレイヤーは、ファイルのダウンロード権限を持たないすべてのユーザーで無効になっています。ユーザーのハイライト注釈を有効にするには、ユーザーにファイルのダウンロード権限があることを確認してください。 | | annotation_view_all | ユーザーに全ユーザーの注釈の表示を許可します。 | | annotation_view_self | ユーザーに自分の注釈のみの表示を許可します。 | # スコープを使用してハイライトによる注釈を有効にする ハイライト注釈は`annotation_edit`および`annotation_view_all`スコープに含まれていません。ハイライトを有効にするには、ダウンスコープされたアクセストークンに`item_download`スコープを含める必要があります。 ### サンプルのシナリオ | シナリオ | スコープ | | --- | --- | | ユーザーがプレビューのみできるようにする (ダウンロード/印刷、注釈は不可) | base_preview | | ユーザーがプレビュー、ダウンロード、印刷を実行できるようにする | base_preview + item_download | | ユーザーがプレビュー、すべての注釈の表示を実行できるようにする (注釈のダウンロード、印刷、作成は不可) | base_preview + annotation_view_all | | ユーザーがプレビュー、注釈の作成 (表示できるのは自分の注釈のみ) を実行できるようにする | base_preview + annotation_view_self + annotation_edit | | ユーザーがプレビュー、注釈の編集、すべての注釈の表示を実行できるようにする | base_preview + annotation_view_all + annotation_edit | | ユーザーがプレビュー、自分の注釈の表示のみ (追加/削除は不可) を実行できるようにする (例: レビュー期間が終了したら、すべてのドキュメントを読み取り専用モードで保存する必要がある場合) | base_preview + annotation_view_self | **Source:** [https://ja.developer.box.com/guides/embed/ui-elements/preview/](https://ja.developer.box.com/guides/embed/ui-elements/preview/) --- ### サービス利用規約 **Type:** guide | **Category:** セキュリティ | **Section:** Developer Guides サービス利用規約 Box APIを使用すると、管理者はBoxの使用に関するサービス利用規約を設定できます。また、ユーザーは、カスタムアプリケーションのサービス利用規約に同意および再同意できます。 用語 サービス利用規約 サービス利用規約とは、Box… # サービス利用規約 Box APIを使用すると、管理者はBoxの使用に関するサービス利用規約を設定できます。また、ユーザーは、カスタムアプリケーションのサービス利用規約に同意および再同意できます。 ## 用語 ### サービス利用規約 サービス利用規約とは、Boxに保存されている企業のデータをすべてのユーザーが使用できる条件を表す、企業レベルの記録文書です。 現在、どの企業にも2種類のサービス利用規約があり、個別に有効にすることが可能です。**管理対象ユーザー用サービス利用規約**は、企業のユーザーに対して有効にすることができます。一方、*_外部ユーザー用サービス利用規約_は、プライマリ企業のデータでコラボレーションする他の企業のユーザーに対して有効にすることができます。 ## サービス利用規約のユーザーステータス サービス利用規約のユーザーステータスは、特定のユーザーによるサービス利用規約への同意のステータスを表します。サービス利用規約とユーザーをどのように組み合わせた場合でも、サービス利用規約のユーザーステータスは1つだけです。 1つの利用規約に、サービス利用規約のユーザーステータスが複数あります (ユーザー1人につき1つ)。 1人のユーザーに、サービス利用規約のユーザーステータスが複数存在する場合もあります。ユーザーは、自社の管理対象ユーザー用サービス利用規約を承認または拒否できるだけでなく、コラボレーションしているさまざまな企業の複数の外部ユーザー用サービス利用規約も承認または拒否できます。 ## API **[会社の設定を編集する]** 権限を持つBox管理者として認証されているアプリケーションは、APIを介して会社の企業のサービス利用規約を表示、作成、編集できます。 - [`GET /terms_of_services/:id`](e://get-terms-of-services-id): 特定のサービス利用規約の情報を取得します。 - [`GET /terms_of_services`](e://get-terms-of-services): 管理対象ユーザーまたは外部ユーザー用に、企業内で使用されているすべてのサービス利用規約のリストを取得します。 - [`POST /terms_of_services`](e://post-terms-of-services): 外部ユーザーまたは管理対象ユーザー用にサービス利用規約の設定を作成します。 - [`PUT /terms_of_services/:id`](e://put-terms-of-services-id): 特定のサービス利用規約の設定を更新します。 さらに、アプリケーションは、APIを介して通常のユーザーのサービス利用規約を表示し承認することができます。 - [`GET /terms_of_service_user_statuses`](e://get-terms-of-service-user-statuses): ユーザーのすべてのサービス利用規約のリストを取得します。 - [`POST /terms_of_service_user_statuses`](e://post-terms-of-service-user-statuses): 特定のサービス利用規約を初めて承認または拒否します。 - [`PUT /terms_of_service_user_statuses/:id`](e://put-terms-of-service-user-statuses-id): 以前に承認または拒否された特定のサービス利用規約を承認または拒否します。 ## スコープ 説明されているアクションを実行するには、アプリケーションに以下のスコープを許可する必要があります。 - **[Enterpriseのプロパティを管理する]**: 企業のサービス利用規約の設定を有効化または編集するためと、外部ユーザーに利用規約の設定を表示するために必要です。 - **ユーザーを管理する**: 他のユーザーのサービス利用規約を承認するために必要です。 **Source:** [https://ja.developer.box.com/guides/security/terms-of-service/](https://ja.developer.box.com/guides/security/terms-of-service/) --- ### サポートされているAIモデル **Type:** guide | **Category:** Box AI | **Section:** Developer Guides サポートされているAIモデル Boxでは、さまざまなAIモデルがサポートされており、アクセスレベルと機能レベルという2つの側面で分類されます。 アクセスレベル コアモデル このモデルは、Box AI… # サポートされているAIモデル Boxでは、さまざまなAIモデルがサポートされており、アクセスレベルと機能レベルという2つの側面で分類されます。 ## アクセスレベル ### コアモデル このモデルは、Box AIに組み込まれており、デフォルトですべてのお客様が利用できます。構成は必要ありません。 ### 顧客希望で有効化できるモデル このモデルは、Box管理者が管理コンソールで有効にするか、Boxに有効にするようリクエストする必要があります。一部のモデルは、追加の条件や料金の対象になる場合があります。 ## 機能レベル ### 標準モデル 基本的な要約、Q&A、短いまたはシンプルなドキュメントからの構造化データの抽出など、高速でコスト効率のよいタスク向けに設計されており、大量のあまり複雑でないユースケースに最適です。 ### プレミアムモデル より高度な推論、大きなコンテキストウィンドウ、長いコンテンツ、複雑なコンテンツ、またはドメイン固有のコンテンツに対する優れたパフォーマンスを提供します。マルチステップ推論、大規模なメタデータ階層の理解、長いドキュメントや非構造化ドキュメントの分析などの高度なタスクに適しています。 モデルは、顧客希望で有効化できるモデルかつプレミアムモデルにすることも、コアモデルかつ標準モデルにすることもできます。つまり、アクセルレベルと機能レベルは、それぞれ独立した分類です (たとえば、モデルは、アクセスレベルに関係なくどちらの機能レベルにもなる可能性があります)。この2つの分類は相互に補完します。 ## モデルの使用 サポートされているAIモデルの使用方法を以下に示します。 - [AIエージェントのデフォルト構成](e://get_ai_agent_default)を取得する - [`POST 2.0/ai/ask`](e://post_ai_ask)、[`POST 2.0/ai/text_gen`](e://post_ai_text_gen)、[`POST 2.0/ai/extract`](e://post_ai_extract)、[`POST 2.0/ai/extract_structured`](e://post_ai_extract_structured)の各エンドポイントで使用されるAIエージェントの構成を上書きする APIコールで`model`パラメータを使用する際は、各タイルおよびモデルカードに表示されている**API名**を使用します。 たとえば、特定のモデルのAIエージェントの構成を取得するには、[model](e://get-ai-agent-default#param-model)パラメータを使用して、API名`azure__openai__gpt_4o_mini`を指定します。プロバイダ名の後に**2つのアンダースコア**を使用していることを確認してください。 このリストはモデルの提供状況により変更される可能性があります。 **ベータ**モードで提供されているモデルはパフォーマンスが大規模にテストされておらず、現状のままでの利用となるため、モデル/出力の品質、可用性、精度にはばらつきがある可能性があります。 ## Box AIのコアモデル Box AIには以下のモデルが搭載されています。Box AIと統合されているこれらのモデルは、エンタープライズグレードの標準に準拠しながら、さまざまなユースケースを支援します。各モデルの機能、対象のアプリケーション、利用に関して該当するガイドラインなどの情報については、以下をご確認ください。 A multimodal model with advanced reasoning and long-context understanding. チャット 利用可能 プレミアム 軽量のタスクを処理するように設計されたマルチモーダルモデル。 Box AI for Hubsのデフォルト Box AI for Documentsのデフォルト Box AI for NotesのQ&Aのデフォルト チャット 利用可能 標準 複雑なマルチステップタスクの処理で非常に効率的なマルチモーダルモデル。 チャット 利用可能 プレミアム 軽量のタスクを処理するように設計されたマルチモーダルモデル。 チャット 利用可能 標準 複雑なマルチステップタスクの処理で非常に効率的なマルチモーダルモデル。 チャット プレビュー 利用可能 プレミアム 最も優れた第2世代のテキスト埋め込みモデル。テキスト検索、コード検索、文の類似性判定に優れています。 埋め込み 利用可能 標準 100万トークンのコンテキストウィンドウと高度な推論機能が備わっている、Geminiマルチモーダルモデル。 チャット 利用可能 プレミアム 大規模かつ高頻度のタスクに最適になるよう設計されたGeminiマルチモーダルモデル。 チャット 利用可能 標準 軽量のタスクを処理するように設計されたGeminiマルチモーダルモデル。 Box AI Extractのデフォルト チャット 利用可能 標準 創造性豊かな文章作成AIや会話AIなど、さまざまな言語タスク向けにカスタマイズされたモデル。 チャット 利用可能 標準 高度な言語タスク向けに設計されており、理解とコンテキスト処理に重点が置かれているモデル。 チャット 利用可能 プレミアム 言語の理解と生成のタスクを強化するよう設計されたモデル。 チャット 利用可能 プレミアム 言語の理解と生成のタスクを強化するよう設計されたモデル チャット 利用可能 プレミアム 日常的なユースケースに最先端のパフォーマンスをもたらすモデル。 チャット 利用可能 プレミアム コーディングや複雑な問題解決に優れており、最先端のエージェント製品を支えるモデル。 チャット 利用可能 プレミアム 高度な言語処理が可能なモデル。幅広いコンテキストを処理できるため、複雑なタスクに適しています。 チャット 利用可能 標準 ドキュメントレベルの理解、図表やグラフの解釈、画像の見出し作成向けに構築されたモデルです。 チャット 利用可能 標準 テキストとマルチモーダルのエクスペリエンスを可能にする、ネイティブのマルチモーダルAIモデル。 チャット 利用可能 標準 ## 顧客希望で有効化できるモデル Box AIの一部の顧客は、リクエストに応じて追加のAIモデルを有効にしたり、管理コンソールから利用できる追加のAIモデルを有効にしたりすることができます。これらのモデルの使用は、追加の条件の対象になる場合があります。顧客希望で有効化できるモデルを選択すると、顧客は、選択した追加の[サブプロセッサ](https://www.box.com/legal/subprocessors)によって自身のデータが処理される可能性があることに同意したことになります。 データの抽出、コーディング、テキストの要約など、企業のユースケースに優れているモデル。 チャット ベータ プレミアム 深い専門知識を必要としない、論理ベースのタスクに適している軽量のモデル。 チャット ベータ プレミアム 複雑なマルチステップタスクの処理で非常に効率的なマルチモーダルモデル。 ベータ プレミアム **Source:** [https://ja.developer.box.com/guides/box-ai/ai-models/](https://ja.developer.box.com/guides/box-ai/ai-models/) --- ### サポートされているエンドポイント **Type:** guide | **Category:** 認証 | **Section:** Developer Guides サポートされているエンドポイント アプリトークン認証で現在サポートされているBox APIは少数です。 エンドポイント パス フォルダを作成 POST /folders ファイルをアップロード POST /files/content ファイルをダウンロード GET /files… # サポートされているエンドポイント アプリトークン認証で現在サポートされているBox APIは少数です。 | エンドポイント | パス | | --- | --- | | フォルダを作成 | POST /folders | | ファイルをアップロード | POST /files/content | | ファイルをダウンロード | GET /files/:id/content | | ファイルを削除 | DELETE /files/:id | | 埋め込みリンクを取得 | GET /files/:id | **Source:** [https://ja.developer.box.com/guides/authentication/app-token/endpoints/](https://ja.developer.box.com/guides/authentication/app-token/endpoints/) --- ### サポートされているファイルの種類 **Type:** guide | **Category:** レプリゼンテーション | **Section:** Developer Guides サポートされているファイルの種類 レプリゼンテーションAPIでサポートされているファイルの種類は以下のとおりです。 3Dグラフィックスとモデリングファイル ファイルの種類 PDFのサポート サムネイルのサポート テキストのサポート .3ds いいえ いいえ いいえ .box3d… # サポートされているファイルの種類 レプリゼンテーションAPIでサポートされているファイルの種類は以下のとおりです。 ## 3Dグラフィックスとモデリングファイル | ファイルの種類 | PDFのサポート | サムネイルのサポート | テキストのサポート | | --- | --- | --- | --- | | .3ds | いいえ | いいえ | いいえ | | .box3d | いいえ | いいえ | いいえ | | .dae | いいえ | いいえ | いいえ | | .fbx | いいえ | いいえ | いいえ | | .mtl | いいえ | いいえ | いいえ | | .obj | いいえ | いいえ | いいえ | | .ply | いいえ | いいえ | いいえ | | .stl | いいえ | いいえ | いいえ | ## オーディオ | ファイルの種類 | PDFのサポート | サムネイルのサポート | テキストのサポート | | --- | --- | --- | --- | | .aac | いいえ | いいえ | いいえ | | .aif | いいえ | いいえ | いいえ | | .aifc | いいえ | いいえ | いいえ | | .aiff | いいえ | いいえ | いいえ | | .amr | いいえ | いいえ | いいえ | | .au | いいえ | いいえ | いいえ | | .flac | いいえ | いいえ | いいえ | | .m4a | いいえ | いいえ | いいえ | | .mp3 | いいえ | いいえ | いいえ | | .ogg | いいえ | はい | いいえ | | .ra | いいえ | いいえ | いいえ | | .wav | いいえ | いいえ | いいえ | | .wma | いいえ | いいえ | いいえ | ## CAD | ファイルの種類 | PDFのサポート | サムネイルのサポート | テキストのサポート | | --- | --- | --- | --- | | .dwg | はい | はい | いいえ | ## ドキュメント | ファイルの種類 | PDFのサポート | サムネイルのサポート | テキストのサポート | | --- | --- | --- | --- | | .boxnote | いいえ | いいえ | はい | | .doc | はい | はい | はい | | .docx | はい | はい | はい | | .gdoc | はい | はい | はい | | .html | はい | いいえ | はい | | .msg | はい | いいえ | はい | | .odt | はい | はい | はい | | .pages | はい | はい | いいえ | | .pdf | はい | はい | はい | | .rtf | はい | はい | はい | | .wpd | はい | はい | はい | | .xhtml | はい | いいえ | はい | | .xml | はい | いいえ | はい | | .xsd | はい | いいえ | はい | | .xsl | はい | いいえ | はい | | .xbd | はい | はい | はい | | .xdw | はい | はい | はい | ## 描画 | ファイルの種類 | PDFのサポート | サムネイルのサポート | テキストのサポート | | --- | --- | --- | --- | | .ai | いいえ | はい | いいえ | | .boxcanvas | いいえ | いいえ | はい | | .indd | はい | はい | いいえ | | .psd | いいえ | はい | いいえ | | .svg | いいえ | はい | いいえ | ## 画像 | ファイルの種類 | PDFのサポート | サムネイルのサポート | テキストのサポート | | --- | --- | --- | --- | | .bmp | いいえ | はい | いいえ | | .cr2 | いいえ | はい | いいえ | | .crw | いいえ | はい | いいえ | | .dcm | いいえ | はい | いいえ | | .dicm | いいえ | はい | いいえ | | .dicom | いいえ | はい | いいえ | | .dng | いいえ | はい | いいえ | | .eps | いいえ | はい | いいえ | | .gif | いいえ | はい | いいえ | | .heic | いいえ | はい | いいえ | | .indd | はい | はい | いいえ | | .idml | はい | はい | いいえ | | .indt | はい | はい | いいえ | | .inx | はい | はい | いいえ | | .jpeg | いいえ | はい | いいえ | | .jpg | いいえ | はい | いいえ | | .nef | いいえ | はい | いいえ | | .png | いいえ | はい | いいえ | | .ps | いいえ | はい | いいえ | | .psd | いいえ | はい | いいえ | | .raf | いいえ | はい | いいえ | | .raw | いいえ | はい | いいえ | | .svg | いいえ | はい | いいえ | | .svs | いいえ | はい | いいえ | | .tif | いいえ | はい | いいえ | | .tiff | いいえ | はい | いいえ | | .tga | いいえ | はい | いいえ | | .webp | いいえ | はい | いいえ | ## プレゼンテーション | ファイルの種類 | PDFのサポート | サムネイルのサポート | テキストのサポート | | --- | --- | --- | --- | | .gslide | はい | はい | はい | | .gslides | はい | はい | はい | | .key | はい | はい | いいえ | | .odp | はい | はい | はい | | .otp | はい | はい | はい | | .ppt | はい | はい | はい | | .pptx | はい | はい | はい | ## スプレッドシート | ファイルの種類 | PDFのサポート | サムネイルのサポート | テキストのサポート | | --- | --- | --- | --- | | .csv | はい | はい | はい | | .gsheet | はい | はい | はい | | .numbers | はい | はい | いいえ | | .ods | はい | はい | はい | | .tsv | はい | はい | はい | | .xls | はい | はい | はい | | .xlsm | はい | はい | はい | | .xlsx | はい | はい | はい | | .xlsb | はい | はい | はい | ## テキストベースのファイル | ファイルの種類 | PDFのサポート | サムネイルのサポート | テキストのサポート | | --- | --- | --- | --- | | .as | はい | いいえ | はい | | .as3 | はい | いいえ | はい | | .asm | はい | いいえ | はい | | .bat | はい | いいえ | はい | | .c | はい | いいえ | はい | | .cc | はい | いいえ | はい | | .cmake | はい | いいえ | はい | | .cpp | はい | いいえ | はい | | .cs | はい | いいえ | はい | | .css | はい | いいえ | はい | | .cxx | はい | いいえ | はい | | .diff | はい | いいえ | はい | | .erb | はい | いいえ | はい | | .fdx | はい | いいえ | はい | | .groovy | はい | いいえ | はい | | .h | はい | いいえ | はい | | .haml | はい | いいえ | はい | | .hh | はい | いいえ | はい | | .java | はい | いいえ | はい | | .js | はい | いいえ | はい | | .json | はい | いいえ | はい | | .less | はい | いいえ | はい | | .log | はい | いいえ | はい | | .m | はい | いいえ | はい | | .make | はい | いいえ | はい | | .md | はい | いいえ | はい | | .ml | はい | いいえ | はい | | .mm | はい | いいえ | はい | | .php | はい | いいえ | はい | | .pl | はい | いいえ | はい | | .plist | はい | いいえ | はい | | .properties | はい | いいえ | はい | | .py | はい | いいえ | はい | | .rb | はい | いいえ | はい | | .rst | はい | いいえ | はい | | .sass | はい | いいえ | はい | | .scala | はい | いいえ | はい | | .scm | はい | いいえ | はい | | .script | はい | いいえ | はい | | .sh | はい | いいえ | はい | | .sml | はい | いいえ | はい | | .sql | はい | いいえ | はい | | .txt | はい | いいえ | はい | | .vi | はい | いいえ | はい | | .vim | はい | いいえ | はい | | .vtt | はい | いいえ | はい | | .webdoc | はい | いいえ | はい | | .yaml | はい | いいえ | はい | ## 動画 | ファイルの種類 | PDFのサポート | サムネイルのサポート | テキストのサポート | | --- | --- | --- | --- | | .3g2 | いいえ | はい | いいえ | | .3gp | いいえ | はい | いいえ | | .avi | いいえ | はい | いいえ | | .flv | いいえ | はい | いいえ | | .m2v | いいえ | はい | いいえ | | .m2ts | いいえ | はい | いいえ | | .m4v | いいえ | はい | いいえ | | .mkv | いいえ | はい | いいえ | | .mov | いいえ | はい | いいえ | | .mp4 | いいえ | はい | いいえ | | .mpeg | いいえ | はい | いいえ | | .mpg | いいえ | はい | いいえ | | .mts | いいえ | はい | いいえ | | .ogg | いいえ | はい | いいえ | | .qt | いいえ | はい | いいえ | | .ts | いいえ | はい | いいえ | | .swf | いいえ | はい | いいえ | | .wmv | いいえ | はい | いいえ | **Source:** [https://ja.developer.box.com/guides/representations/supported-file-types/](https://ja.developer.box.com/guides/representations/supported-file-types/) --- ### サムネイルレプリゼンテーションの取得 **Type:** guide | **Category:** レプリゼンテーション | **Section:** Developer Guides サムネイルレプリゼンテーションの取得 サムネイルとは小さい画像のことで、アプリケーション内でファイルのレプリゼンテーションとして使用できる.pngまたは.jpgで表されます。たとえば、ファイルをダウンロードまたはプレビューするリンクのプレースホルダとして使用されます。 1024x… # サムネイルレプリゼンテーションの取得 サムネイルとは小さい画像のことで、アプリケーション内でファイルのレプリゼンテーションとして使用できる`.png`または`.jpg`で表されます。たとえば、ファイルをダウンロードまたはプレビューするリンクのプレースホルダとして使用されます。 `1024x1024`および`2048x2048`のPNGを除くすべてのサムネイルレプリゼンテーションは、元のファイルをBoxにアップロードしたときに生成されます。 ファイルのサムネイルを取得する方法として、[サムネイルAPI](guide://representations/thumbnail)の使用は非推奨になりました。 ## 手順 サムネイルレプリゼンテーションを取得するには、以下の手順に従います。 - [すべてのレプリゼンテーションのリストを取得する](guide://representations/list-all-representations) - `[jpg?dimensions=32x32]`のように目的のサムネイル形式とサイズを表す`x-rep-hints`ヘッダーを渡して、[サムネイルをリクエストする](guide://representations/request-a-representation)。 - `url_template`を呼び出して[サムネイルをダウンロード](guide://representations/download-a-representation)する。その際、`{+asset_path}`を空の文字列に置き換えます。 場合によっては、サムネイルを直接作成できないこともあります。代わりに、APIから`location`レスポンスヘッダーで`HTTP 202`が返されます。この場所は、サムネイルの生成中に使用できる一時的な画像のためのものです。 このエンドポイントを再試行するまでの推定秒数を示すretry-afterレスポンスヘッダーも返されます。 ## 例 `x-rep-hints`ヘッダーの値の例を以下に示します。 | x-rep-hints: [jpg?dimensions=32x32] | | --- | | 32x32のJPEGサムネイルを返します。 | | x-rep-hints: [jpg?dimensions=32x32][jpg?dimensions=1024x1024] | | --- | | 32x32および1024x1024のJPEGサムネイルを返します。 | | x-rep-hints: [jpg?dimensions=32x32][png?dimensions=2048x2048] | | --- | | 32x32のJPEGサムネイルおよび2048x2048のPNGサムネイルを返します。 | | x-rep-hints: [jpg?dimensions=2048x2048,png?dimensions=2048x2048] | | --- | | 2048x2048のJPEGサムネイルおよび2048x2048のPNGサムネイルを返し、使用可能な最初のレプリゼンテーションを返します。どちらも使用可能でない場合は、レプリゼンテーションは返されません。 | ## サポートされているファイルサイズ 以下のサムネイルの形式とサイズが使用可能です。 | ファイルの種類 | サイズ | | --- | --- | | JPG | 32x32, 94x94, 160x160, 320x320, 1024x1024, 2048x2048* | | PNG | 1024x1024*, 2048x2048* | `*`が付いているサイズには、いくつかの制限があります。 ## ファイルサイズの制限 ### 2048x2048のJPEG `2048x2048`サイズのJPEGを使用できるのは、元のファイルがJPEGの場合のみです。このサイズを使用する場合は、PNGか、PNGとJPEGの両方をリクエストすることをお勧めします。 ### 動画ファイル `2048x2048`のJPEG、`2048x20148`のPNG、および`1024x1024`のPNGのレプリゼンテーションは、動画ファイルでは使用できません。 ### 元のファイルサイズ サムネイルは拡大されません。Boxにアップロードされたファイルの元のファイルサイズがレプリゼンテーションのサイズより小さい場合は、作成されるサムネイルのサイズの上限は元のファイルのサイズになります。 ## サポートされているファイルの種類 現時点でサポートされているファイルの種類は以下のとおりです。 | ファイルの種類 | ファイル拡張子 | | --- | --- | | ドキュメント | doc, docx, gdoc, gsheet, gslide, gslides, odp, ods, odt, pdf, ppt, pptx, rtf, wpd, xls, xlsm, xlsx, key, pages, numbers | | 画像 | ai, bmp, dcm, dicm, eps, gif, idml, indd, indt, inx, jpeg, jpg, png, ps, psd, svg, svs, tif, tiff, tga | | オーディオ | aac, aifc, aiff, amr, au, flac, m4a, mp3, ogg, ra, wav, wma | | 動画 | 3g2, 3gp, avi, m2v, m2ts, m4v, mkv, mov, mp4, mpeg, mpg, ogg, mts, qt, wmv | ファイルの種類が**ドキュメント**の場合、返されるレプリゼンテーションはプレースホルダアイコンとなり、実際のサムネイルではありません。 **Source:** [https://ja.developer.box.com/guides/representations/thumbnail-representation/](https://ja.developer.box.com/guides/representations/thumbnail-representation/) --- ### スコープ **Type:** guide | **Category:** APIコール | **Section:** Developer Guides スコープ 開発者コンソールでアプリケーションが作成されると、ユーザーはアプリケーションのスコープを設定する必要があります。ユーザーにBox内のファイルやフォルダへのアクセス権限が付与されるしくみと同様、アプリケーションにも、BoxユーザーやBox… # スコープ 開発者コンソールでアプリケーションが作成されると、ユーザーはアプリケーションのスコープを設定する必要があります。ユーザーにBox内のファイルやフォルダへのアクセス権限が付与されるしくみと同様、アプリケーションにも、BoxユーザーやBoxを使用する企業に代わって特定のアクションを実行するための独自の権限が付与されます。アプリケーションに対する権限セットの名前を「スコープ」と言います。つまり、アプリケーションのスコープにより、アプリケーションから呼び出すことのできる[エンドポイント](page://reference)が決まります。また、このスコープは、アプリケーションの[アクセストークン](g://authentication/tokens)が提供するアクセス権限に反映されます。 ## ユーザー権限とスコープ アクションを実行するための適切なスコープがアプリケーションに設定されている場合でも、アクセストークンと関連付けられた、呼び出しを実行するユーザーにはそのアクションを実行するための権限が必要であり、逆の場合も同様であることを理解することが重要です。 たとえば、ファイルを読み取るようにアプリケーションが設定されている場合、アクセスしようとするファイルの読み取り権限が認証済みユーザーにも必要です。 スコープ、トークンの権限、ユーザー権限がどのように連携しているかの詳細については、Boxの[セキュリティガイド](g://security)を参照してください。 ## スコープとOAuth 2承認 アプリケーションを承認するためにクライアント側のOAuth 2フローを介してユーザーを送信する際は、承認URLに一連のスコープを追加してユーザーのアクセストークンをさらに制限できます。 たとえば、アプリケーションで`root_readonly`および`root_readwrite`スコープが有効になっている場合は、ユーザーのリダイレクト時にこのスコープを指定することで、ユーザーのアクセストークンを`root_readonly`に制限できます。 ``` GET https://account.box.com/api/oauth2/authorize?scope=root_readonly&client_id=.... ``` スコープパラメータが省略されている場合、アプリケーションでは、そのアプリケーションの作成時に設定されたスコープが使用されます。 ## セルフサービススコープ これらのスコープは、アプリケーションの設定時に開発者コンソールから使用できます。[**構成**] タブの [**アプリケーションスコープ**] セクションに移動して、以下のスコープから1つ以上を選択します。 ### すべてのファイルとフォルダの読み取り | | | | --- | --- | | OAuthスコープ | root_readonly | | アプリケーションスコープ | Boxに格納されているすべてのファイルとフォルダの読み取り | アプリケーションで、認証済みユーザーはすべてのファイル/フォルダを読み取ることができるようになります。 これにより、アプリケーションにはファイルとフォルダに対する読み取り権限が付与されますが、APIコールを実行するユーザーには、アクセス対象の項目に対するアクセス権限が必要です。 つまり、[JWT](g://authentication/jwt)アプリケーションが[管理対象ユーザー](page://platform/user-types/#managed-users)の項目にアクセスする場合、サービスアカウントのトークンは、そのコンテンツにアクセスできるユーザーとして直接認証されるように、`as-user`[ヘッダー](g://authentication/jwt/as-user)を使用するか、[ユーザーアクセストークン](g://authentication/jwt/user-access-tokens)を作成する必要があります。 ### すべてのファイルとフォルダの読み取りと書き込み | | | | --- | --- | | OAuthスコープ | root_readwrite | | アプリケーションスコープ | Boxに格納されているすべてのファイルとフォルダの読み取りと書き込み | アプリケーションには、認証済みユーザーの書き込みアクセス権限が付与されます。これにより、アプリケーションでは、ファイルまたは新しいファイルバージョンのアップロード、コンテンツのダウンロード、新しいフォルダの作成、コラボレーションの更新または削除、コメントまたはタスクの作成などを実行できるようになります。 これにより、アプリケーションには項目に対する読み取り/書き込みアクセス権限が付与されますが、APIコールを行うユーザーには、コンテンツに対するアクセス権限が必要です。 ### ユーザーを管理する 開発者コンソールにある「ユーザーを管理する」スコープは、2つのOAuthスコープにマップされます。 | | | | --- | --- | | OAuthスコープ | manage_managed_users | | アプリケーションスコープ | ユーザーを管理する | アプリケーションには、[管理対象ユーザー](page://platform/user-types/#managed-users)を管理するための権限が付与されます。これにより、このアプリでは、ユーザーのプライマリログインの変更、ユーザーのパスワードのリセット、管理対象ユーザーのロールの変更を実行できます。 これを使用すると、アプリケーションでユーザーを管理できますが、クライアント側アプリケーションの場合、使用されるアクセストークンを、適切な権限を持つ管理者または共同管理者に関連付ける必要があります。 さらに、JWTアプリケーションの場合は、[アプリケーションアクセス](g://authentication/jwt/jwt-setup/#application-access)を [**アプリアクセス + Enterpriseアクセス**] にしてアプリケーションを設定する必要があります。 | | | | --- | --- | | OAuthスコープ | manage_app_users | | アプリケーションスコープ | ユーザーを管理する | アプリケーションには、[App User](page://platform/user-types/#app-user)を管理するための権限が付与されます。つまり、このスコープは、サーバー側で認証されている (JWT) アプリケーションのみに適用されます。 ### グループを管理する | | | | --- | --- | | OAuthスコープ | manage_groups | | アプリケーションスコープ | グループを管理する | アプリケーションには、企業のグループを管理するための権限が付与されます。これにより、このアプリでは、グループの作成、更新、削除のほか、グループメンバーシップの管理を実行できます。 これを使用すると、アプリケーションでグループを管理できますが、クライアント側アプリケーションの場合、使用されるアクセストークンを、適切な権限を持つ管理者または共同管理者に関連付ける必要があります。 さらに、JWTアプリケーションの場合は、[アプリケーションアクセス](g://authentication/jwt/jwt-setup/#application-access)を [**アプリアクセス + Enterpriseアクセス**] にしてアプリケーションを設定する必要があります。 ### Webhookを管理する | | | | --- | --- | | OAuthスコープ | manage_webhook | | アプリケーションスコープ | Webhookを管理する | アプリケーションには、ユーザーのWebhookを作成するための権限が付与されます。Webhookの[制限](g://webhooks/v2/limitations-v2)を確認してください。注目すべきは、1ユーザーにつき1つのアプリケーションあたりWebhookは1,000個までという制限があることです。 ### Enterpriseのプロパティを管理する | | | | --- | --- | | OAuthスコープ | manage_enterprise_properties | | アプリケーションスコープ | Enterpriseのプロパティを管理する | アプリケーションには、Enterprise Event Streamを表示するための権限に加え、Enterpriseの属性とレポートを表示および編集するための権限が付与されます。さらに、アプリケーションでは、デバイスピンの編集と削除も実行できます。 これを使用すると、アプリケーションで企業のプロパティを管理できますが、クライアント側アプリケーションの場合、使用されるアクセストークンを、適切な権限を持つ管理者または共同管理者に関連付ける必要があります。 ### リテンションポリシーを管理する | | | | --- | --- | | OAuthスコープ | manage_data_retention | | アプリケーションスコープ | リテンションポリシーを管理する | | 依存先 | enterprise_contentスコープ | アプリケーションには、Box Governanceでリテンションポリシーを表示および作成するための権限が付与されます。そのため、企業では[Box Governance](https://www.box.com/ja-jp/security/governance-and-compliance)を購入しておく必要があります。 このスコープを使用するには、`enterprise_content`スコープも適切に機能する必要があります。これらのスコープをリクエストするには、当社のサポートチャネルでチケットを作成します。 ### 署名リクエストを管理する | | | | --- | --- | | OAuthスコープ | sign_requests.readwrite | | アプリケーションスコープ | 署名リクエストを管理する | アプリケーションには、署名リクエストを取得、作成、キャンセル、および再送信するための権限が付与されます。 このスコープでは、アプリケーションに読み取り/書き込みスコープも設定する必要があります。これらのスコープは、有効にしたときに自動的に選択されます。さらに、企業ではSignが有効になっている必要があります。 ### Box AI APIを管理する | | | | --- | --- | | OAuthスコープ | ai.readwrite | | アプリケーションスコープ | AIを管理する | アプリケーションには、Box AI APIにリクエストを送信するための権限が付与されます。 ### Box Relayを管理する | | | | --- | --- | | OAuthスコープ | manage_triggers | | アプリケーションスコープ | Box Relayを管理する | アプリケーションには、ワークフローを取得し、`WORKFLOW_MANUAL_START`タイプのフローを開始するための権限が付与されます。 このスコープでは、アプリケーションに読み取り/書き込みスコープも設定する必要があります。 ## リクエストに応じて使用可能 リクエスト時にのみ使用できる追加のスコープがいくつかあります。これを使用するには、Boxの[サポートチーム](page://support)にチケットを送信してください。サポートチームは、個別にリクエストを確認し、ユースケースにスコープが必要な場合にのみ承認を行います。 無料トライアルのアカウントでは、スコープを追加でリクエストすることはできません。以下に示すスコープの有効化についてサポートリクエストを申請する前に、有料のEnterpriseアカウントにログインするか、[無料のDeveloperアカウントをEnterpriseアカウントプランにアップグレード](https://www.box.com/ja-jp/pricing)してください。 ### リーガルホールドを管理する | | | | --- | --- | | OAuthスコープ | manage_legal_holds | | アプリケーションスコープ | リテンションポリシーを管理する | | 依存先 | enterprise_contentスコープ | アプリケーションには、Box Governanceでリテンションポリシーを表示および作成するための権限が付与されます。そのため、会社ではBox Governanceを購入しておく必要があります。 このスコープが適切に機能するには、`enterprise_content`スコープを必要とします。このスコープは、当社のサポートチャネルでチケットを作成してリクエストできます。 ### メール通知を抑制する | | | | --- | --- | | アプリケーションスコープ | APIコールからメール通知を抑制する | APIコールが行われるときに、一部の種類の[メール通知](g://api-calls/suppress-notifications)を抑制できます。 ### グローバルコンテンツマネージャ (GCM) | | | | --- | --- | | OAuthスコープ | enterprise_content | | アプリケーションスコープ | グローバルコンテンツマネージャ | Enterprise設定に基づいて、管理者、[共同管理者][ca]、[サービスアカウント](page://platform/user-types/#service-account)が、所有していない、またはEnterprise内でコラボレータになっていない任意のコンテンツを取得できるようにします。 リテンションポリシーとリーガルホールドを管理するには、このスコープが必要です。 # 副次的影響 アプリケーションに対してこのスコープを有効にすると、一部のAPIコールの動作が変更されます。その最も顕著な例として、`as-user`ヘッダーを使用してユーザーとして明示的に認証しないとコンテンツを書き込めなくなることが挙げられます。また、このスコープを有効にすると、別の企業のユーザーが所有するコンテンツにはアクセスできなくなります。 そのため、やむを得ない場合を除き、このスコープはプロビジョニングされません。 ## ダウンスコープ用のスコープ 特にトークンをクライアント側 (ブラウザなどの公開された環境) に公開する必要がある場合など、アクセストークンをより厳格な権限レベルに[ダウンスコープ](g://authentication/tokens/downscope)しなければならないことがあります。その主な例として、ユーザーのブラウザでアクセストークンが必要となる[Box UI Elements](https://github.com/box/box-ui-elements)を使用する場合が挙げられます。 既存のアクセストークンをダウンスコープするために[`POST /oauth2/token`](endpoint://post-oauth2-token)エンドポイントで使用できる**追加**のスコープのリストを以下に示します。 | OAuthスコープ | 影響を受けるUI Element | 説明 | | --- | --- | --- | | annotation_edit | プレビュー | 注釈の編集と削除をユーザーに許可します。 | | annotation_view_all | プレビュー | すべてのユーザーによる注釈の表示をユーザーに許可します。 | | annotation_view_self | プレビュー | ユーザーに自分の注釈のみの表示を許可します。 | | base_explorer | Explorer | ユーザー/ファイル/トークンの権限に基づいて、フォルダツリー内のコンテンツへのアクセスを許可します。 | | base_picker | Picker | ユーザー/ファイル/トークンの権限に基づいて、フォルダツリー内のコンテンツへのアクセスを許可します。 | | base_preview | プレビュー | ファイルのプレビューのみをユーザーに許可します。 | | base_sidebar | Sidebar | サイドバーUI Elementに必要なファイルの基本情報の取得をユーザーに許可します。 | | base_upload | Uploader | トークンのダウンスコープ時に、resourceの下で指定されたフォルダへのアップロードを許可します。 | | item_delete | Explorer | ファイルとフォルダの削除を許可します。 | | item_download | Explorer、Preview | ファイルまたはフォルダのコンテンツのダウンロードを許可します。 | | item_preview | Explorer | ファイルのプレビューを有効にします。 | | item_rename | Explorer | ファイルとフォルダの名前変更を許可します。 | | item_share | Explorer、Picker | トークン交換のresourceで指定された項目の共有を許可します。 | | item_upload | Picker | Content Pickerでのアップロードを許可します。 | また、ダウンスコープ時には標準OAuthスコープもサポートされます。 | OAuthスコープ | 説明 | | --- | --- | | ai.readwrite | AI APIを管理する | | manage_managed_users | 管理対象ユーザーを管理する | | manage_app_users | App Userを管理 | | manage_data_retention | リテンションポリシーを管理する | | manage_enterprise_properties | Enterpriseのプロパティを管理する | | manage_groups | グループを管理する | | manage_webhook | Webhookを管理する | | sign_requests.readwrite | 署名リクエストを管理する | [ca][ca]: [[https://support.box.com/hc/ja/articles/1500005433721#h_01GSE1DYJKTY9EXEWJEDKFHCNV][https://support.box.com/hc/en-us/articles/1500005433721-Users-Groups-Settings#h_01GSE1DYJKTY9EXEWJEDKFHCNV](https://support.box.com/hc/ja/articles/1500005433721#h_01GSE1DYJKTY9EXEWJEDKFHCNV%5D%5Bhttps://support.box.com/hc/en-us/articles/1500005433721-Users-Groups-Settings#h_01GSE1DYJKTY9EXEWJEDKFHCNV)] **Source:** [https://ja.developer.box.com/guides/api-calls/permissions-and-errors/scopes/](https://ja.developer.box.com/guides/api-calls/permissions-and-errors/scopes/) --- ### ステータスコード **Type:** guide | **Category:** APIコール | **Section:** Developer Guides ステータスコード Box APIの使用時に受信したHTTPステータスコードの解釈に以下のルールを適用できます。 HTTPステータス 200-299 BoxはAPIリクエストを受信、認識、承認しました。リクエストは完了したか、完了に向けた処理中です。 300-399 Box… # ステータスコード Box APIの使用時に受信したHTTPステータスコードの解釈に以下のルールを適用できます。 | HTTPステータス | | | --- | --- | | 200-299 | BoxはAPIリクエストを受信、認識、承認しました。リクエストは完了したか、完了に向けた処理中です。 | | 300-399 | BoxはAPIリクエストを受信、認識、承認しましたが、リクエストを完了するにはクライアントによるさらなる処理が必要です。多くの場合、これには他のURLへのリダイレクトが含まれます。 | | 400-499 | リクエストの処理中にクライアントエラーが発生しました。多くの場合、クライアントが適切なパラメータを指定しなかった、リソースにアクセスできなかった、またはそれ以外の場合にも不可能なアクションを実行しようとしたことが原因です。 | | 500-599 | Boxはリクエストを受信、承認しましたが、処理中にBox内でエラーが発生しました。これらのエラーは、クライアントのリクエストの問題ではなく、Boxの問題を示します。 | **Source:** [https://ja.developer.box.com/guides/api-calls/status-codes/](https://ja.developer.box.com/guides/api-calls/status-codes/) --- ### ストリームタイプ **Type:** guide | **Category:** イベント | **Section:** Developer Guides ストリームタイプ ストリームタイプ スコープ 目的 説明 保持期間 アクセスパターン admin_logs 1つのEnterprise (承認された管理者向け) 履歴の照会 イベントの履歴を最大1年分照会できるようにします 365日 期間でフィルタをかけた後、stream… # ストリームタイプ | ストリームタイプ | スコープ | 目的 | 説明 | 保持期間 | アクセスパターン | | --- | --- | --- | --- | --- | --- | | admin_logs | 1つのEnterprise (承認された管理者向け) | 履歴の照会 | イベントの履歴を最大1年分照会できるようにします | 365日 | 期間でフィルタをかけた後、stream_positionでレスポンスのページ割りを行う | | admin_logs_streaming | 1つのEnterprise (承認された管理者向け) | ほぼリアルタイムでの登録 | ほぼリアルタイムでライブイベントにサブスクライブできるようにします | 14日 | stream_positionを使用してポーリングする | | all (デフォルト) | 1人のユーザー (任意のユーザー向け) | ほぼリアルタイムでの登録 | ユーザーに関するすべてのイベントを返します | 21日 | stream_positionを使用してポーリングまたはLong pollingを行う | | changes | 1人のユーザー (任意のユーザー向け) | ほぼリアルタイムでの登録 | ファイルの更新やコラボレーションなど、ファイルツリーを変更する可能性があるイベントを返します | 21日 | stream_positionを使用してポーリングまたはLong pollingを行う | | sync | 1人のユーザー (任意のユーザー向け) | ほぼリアルタイムでの登録 | changesに似ていますが、同期対象フォルダのみに適用されます | 31日 | stream_positionを使用してポーリングまたはLong pollingを行う | **Source:** [https://ja.developer.box.com/guides/events/parameters/stream-types/](https://ja.developer.box.com/guides/events/parameters/stream-types/) --- ### ストリーム位置のページ割り **Type:** guide | **Category:** イベント | **Section:** Developer Guides ストリーム位置のページ割り イベントストリームのページ割りは、stream_positionパラメータの使用によって機能します。 最初に、stream_positionクエリパラメータを指定せずにリクエストをGET /events APIに送信します。 このAPI… # ストリーム位置のページ割り イベントストリームのページ割りは、`stream_position`パラメータの使用によって機能します。 最初に、`stream_position`クエリパラメータを指定せずにリクエストを[`GET /events`](e://get_events) APIに送信します。 ``` curl https://api.box.com/2.0/events \ -H "authorization: Bearer ACCESS_TOKEN" ``` このAPIにより、使用可能なすべてのイベントが古い方から順に返されます。レスポンスには`next_stream_position`値も含まれており、これを使用して、ストリーム内の次の位置に対する次のAPIコールを実行できます。 ``` curl https://api.box.com/2.0/events?stream_position=388720462721 \ -H "authorization: Bearer ACCESS_TOKEN" ``` `stream_position`は、最も近いストリーム位置が返されるよう`now`に設定することもできます。 ``` curl https://api.box.com/2.0/events?stream_position=now \ -H "authorization: Bearer ACCESS_TOKEN" ``` この場合、APIによって空のリストと、次の呼び出しに使用できる`next_stream_position`が返されます。 **Source:** [https://ja.developer.box.com/guides/events/parameters/pagination/](https://ja.developer.box.com/guides/events/parameters/pagination/) --- ### すべてのメタデータテンプレートのリストの取得 **Type:** quick-start | **Category:** メタデータ | **Section:** Developer Guides すべてのメタデータテンプレートのリストの取得 会社には、ユーザーが独自に作成しなくてもすぐに使用できるメタデータテンプレートのリストがすでに存在することがよくあります。 一般に、メタデータテンプレートには、自社のみで使用できるものと、Box… # すべてのメタデータテンプレートのリストの取得 会社には、ユーザーが独自に作成しなくてもすぐに使用できるメタデータテンプレートのリストがすでに存在することがよくあります。 一般に、メタデータテンプレートには、自社のみで使用できるものと、Boxを使用するすべての企業が使用できるものがあります。テンプレートの`scope`により、テンプレートはすべての人が利用可能か (`global`)、自社のみで利用可能か (`enterprise`) が定義されます。 メタデータのスコープの詳細を確認する ## テンプレートのリストの取得 すべてのユーザーが使用できる[グローバルテンプレート](e://get_metadata_templates_global)はいくつかあります。 これらのテンプレートの多くはBoxの内部使用を目的としたものですが、アプリケーションでこれらを使用したり適用したりすることもできます。会社のニーズに固有のデータを保持するには、[社内のアプリケーションや管理者が作成した](e://get_metadata_templates_enterprise)テンプレートがより便利です。 ## メタデータテンプレート [メタデータテンプレート](g://metadata/templates)には、ファイルまたはフォルダに割り当てることができる一連のキー/値ペアが記載されています。 たとえば、`customerInfo`テンプレートは顧客に関するデータを保持しており、顧客名と顧客の業種のフィールドがあるとします。 ``` { "id": "100ac693-a468-4b37-9535-05984b804dc2", "type": "metadata_template", "templateKey": "customerInfo", "scope": "enterprise_12345", "displayName": "Customer Info", "hidden": false, "copyInstanceOnItemCopy": false, "fields": [ { "id": "5c6a5906-003b-4654-9deb-472583fc2930", "type": "string", "key": "name", "displayName": "Name", "hidden": false }, { "id": "cf3eb5b8-52ef-456c-b175-44354a27e289", "type": "enum", "key": "industry", "displayName": "Industry", "options": [ {"key": "Technology"}, {"key": "Healthcare"}, {"key": "Legal"} ], "hidden": false } ] } ``` 使用できるテンプレートのリストを取得しました **Source:** [https://ja.developer.box.com/guides/metadata/quick-start/list-all/](https://ja.developer.box.com/guides/metadata/quick-start/list-all/) --- ### すべてのメタデータテンプレートのリストの取得 **Type:** guide | **Category:** メタデータ | **Section:** Developer Guides すべてのメタデータテンプレートのリストの取得 enterpriseスコープまたはglobalスコープのメタデータテンプレートのリストを取得できます。 グローバルテンプレートのリストを取得 すべてのグローバルメタデータテンプレートのリストを取得するには、GET /metadata… # すべてのメタデータテンプレートのリストの取得 [enterpriseスコープまたはglobalスコープ](g://metadata/scopes)のメタデータテンプレートのリストを取得できます。 ## グローバルテンプレートのリストを取得 すべてのグローバルメタデータテンプレートのリストを取得するには、[`GET /metadata_templates/global`](e://get_metadata_templates_global) APIエンドポイントを呼び出します。 このAPIは、Boxによって作成され、すべての会社が使用できるすべてのメタデータテンプレートのリストを返します。 ## 現在の会社のテンプレートのリストを取得 現在の会社内で使用するために作成されたすべてのメタデータテンプレートのリストを取得するには、[`GET /metadata_templates/enterprise`](e://get_metadata_templates_enterprise) APIエンドポイントを呼び出します。 このAPIは、この会社によって作成されたすべてのメタデータテンプレートのリストを返します。これらのテンプレートは、この会社内のファイルにのみ適用できます。 ## ページ割り このAPIでは、[マーカーベースのページ割り](g://api-calls/pagination/marker-based)が使用されており、レスポンスの本文で、より多くのテンプレートを使用できることを示す`next_marker`値を返すことができます。 **Source:** [https://ja.developer.box.com/guides/metadata/templates/list/](https://ja.developer.box.com/guides/metadata/templates/list/) --- ### すべてのリーガルホールドポリシーのリストの取得 **Type:** guide | **Category:** リーガルホールド | **Section:** Developer Guides すべてのリーガルホールドポリシーのリストの取得 会社内に作成されたすべてのリーガルホールドポリシーのリストを取得するには、GET /legal_hold_policies APIエンドポイントを呼び出します。 必須のスコープ リーガルホールドAPI… # すべてのリーガルホールドポリシーのリストの取得 会社内に作成されたすべてのリーガルホールドポリシーのリストを取得するには、[`GET /legal_hold_policies`](e://get_legal_hold_policies) APIエンドポイントを呼び出します。 ## 必須のスコープ リーガルホールドAPIのいずれかを使用する前に、アプリケーションでは適切なスコープを有効にしておく必要があります。詳細については、[必須のスコープ](g://legal-holds#required-scopes)を参照してください。 **Source:** [https://ja.developer.box.com/guides/legal-holds/list/](https://ja.developer.box.com/guides/legal-holds/list/) --- ### すべてのリテンションポリシーのリストの取得 **Type:** guide | **Category:** リテンションポリシー | **Section:** Developer Guides すべてのリテンションポリシーのリストの取得 会社内に作成されたすべてのリテンションポリシーのリストを取得するには、GET /retention_policies APIエンドポイントを呼び出します。 必須のスコープ リテンションポリシーAPI… # すべてのリテンションポリシーのリストの取得 会社内に作成されたすべてのリテンションポリシーのリストを取得するには、[`GET /retention_policies`](e://get_retention_policies) APIエンドポイントを呼び出します。 ## 必須のスコープ リテンションポリシーAPIのいずれかを使用する前に、アプリケーションでは適切なスコープを有効にしておく必要があります。詳細については、[必須のスコープ](g://retention-policies#required-scopes)を参照してください。 **Source:** [https://ja.developer.box.com/guides/retention-policies/list/](https://ja.developer.box.com/guides/retention-policies/list/) --- ### セキュリティ **Type:** guide | **Category:** セキュリティ | **Section:** Developer Guides セキュリティ Box APIを使い始めたばかりの開発者でも、アプリケーションの承認を担当するBox管理者でも、Boxに保存されたコンテンツを保護するためにセキュリティメカニズムを理解することは非常に重要です。 Box APIは、Box… # セキュリティ Box APIを使い始めたばかりの開発者でも、アプリケーションの[承認](g://authorization/custom-app-approval)を担当するBox管理者でも、Boxに保存されたコンテンツを保護するためにセキュリティメカニズムを理解することは非常に重要です。 Box APIは、Boxウェブアプリと同じセキュリティの原則と制限に従います。つまり、Box APIを利用しても、コンテンツの[権限](https://support.box.com/hc/ja/articles/360044196413-%E3%82%B3%E3%83%A9%E3%83%9C%E3%83%AC%E3%83%BC%E3%82%BF%E3%81%AE%E6%A8%A9%E9%99%90%E3%83%AC%E3%83%99%E3%83%AB%E3%81%AB%E3%81%A4%E3%81%84%E3%81%A6)、[ウォーターフォール型のフォルダ構造](https://support.box.com/hc/ja/articles/360043697254-%E3%83%95%E3%82%A9%E3%83%AB%E3%83%80%E3%81%AE%E6%A8%A9%E9%99%90%E3%81%AB%E3%81%A4%E3%81%84%E3%81%A6)、または管理者向けの要件を回避することはできません。 ## アクセストークン さまざまなBox APIコールの中核となるのは[アクセストークン](g://authentication/tokens)です。ユーザー名とパスワードは使用できないため、Boxサーバーにはユーザーの本人確認を行う手段が必要になります。アクセストークンの全機能には、ユーザーの権限、トークンの権限、アプリケーションの設定が含まれます。 アクセストークンは認証済みのユーザーを表し、ユーザーが問題なく呼び出すことができるコンテンツを決定します。Boxウェブアプリを使用する場合と同様に、問題なく操作できるのは、アクセストークンに関連付けられたユーザーが所有するコンテンツまたはコラボレータとなっているコンテンツのみです。これは、トークンの[ダウンスコープ](g://authentication/tokens/downscope)によってさらに制限できます。 [アクセストークン](g://authentication/tokens)の有効期限は60分のみですが、必要に応じてそれより前に[取り消す](e://post-oauth2-revoke)ことができます。アクセストークンの有効期限が切れると、OAuth 2.0アプリケーションを使用している場合、[更新トークン](g://authentication/tokens/refresh)を別のアクセストークンと[交換](e://post-oauth2-token--refresh)できます。更新トークンは、60日後または1回の使用後に有効期限が切れます。また、サーバー認証アプリケーションを使用している場合は、新しいアクセストークンを得るために[アクセストークンをリクエストエンドポイント](e://post-oauth2-token)を呼び出す必要があります。セキュリティ上の理由により、Boxでは有効期間の長いアクセストークンを許可していません。 404エラーが発生する理由がわからない場合は、まず、現在のユーザーを取得エンドポイントを使用して、アクセストークンに関連付けられているユーザーを確認することをお勧めします。 ## スコープ [スコープ](g://api-calls/permissions-and-errors/scopes)は、アプリケーションの作成時に[開発者コンソール](https://app.box.com/developers/console)で構成されます。スコープにより、150を超えるエンドポイントのうち、アプリケーションが問題なく呼び出せるものが決まります。 スコープはユーザーの権限と連動しているため、書き込みスコープを付与しても、ユーザーは、Box Enterpriseのすべてのコンテンツに自動的にアクセスできるわけではありません。つまり、認証済みユーザーは、アクセス権限を持つコンテンツに対する書き込み呼び出しを実行したときに、成功を示すAPIレスポンスを受け取ることができます。 たとえば、ユーザーの管理およびグループの管理のスコープだけが有効になっているアプリケーションを考えてみましょう。このアプリケーションのアクセストークンがフォルダの情報を取得するAPIコールを実行しようとすると、関連付けられているユーザーがそのフォルダを所有している場合でも、403エラーが返されます。これは、この操作を実行するには読み取りスコープが必要なためです。このアプリケーションのアクセストークンには、ユーザーおよびグループに関連したAPIコールに対してのみ、成功を示すレスポンスが返されます。 ## 制限されたエンドポイント 適切な[権限](https://support.box.com/hc/ja/articles/360044194393-%E5%85%B1%E5%90%8C%E7%AE%A1%E7%90%86%E8%80%85%E6%A8%A9%E9%99%90%E3%81%AE%E4%BB%98%E4%B8%8E%E3%81%A8%E5%A4%89%E6%9B%B4)を付与された管理者または共同管理者のみが問題なく使用できるAPIエンドポイントがいくつかあります。原則として、管理者または共同管理者だけがBox管理コンソールで実行できる操作の場合、その操作のAPIコールを完了するには、これらのユーザーのいずれかに関連付けられたアクセストークンが必要になります。これについては、必要に応じて、特定のエンドポイントに関するAPI[リファレンス](page://reference)のドキュメントを参照してください。 管理者に制限されたエンドポイントの一部を以下に示します。 - [ユーザー](e://resources/user)の作成、削除、またはその情報の取得 - [グループ](e://resources/group)の作成、削除、または変更 - ユーザーまたは企業の[イベント](e://resources/event)の表示 企業でBox GovernanceやBox Shieldなどのアドオン製品を購入している場合は、以下のように、管理者ユーザーのアクセストークンでのみ使用できるエンドポイントが他にもあります。 - [セキュリティ分類](e://resources/classification)の操作 - [リーガルホールドポリシー](e://resources/legal-hold-policy)と[割り当て](e://resources/legal-hold-policy-assignment)の操作 - [リテンションポリシー](e://resources/retention-policies)と[割り当て](e://resources/retention-policy-assignment)の操作 ## アプリケーションアクセス サーバー認証 ([JWT](g://authentication/jwt)使用) または[クライアント資格情報許可](g://authentication/client-credentials)を利用するアプリケーションのアプリケーションアクセスは、[開発者コンソール](https://app.box.com/developers/console)でのみ構成できます。この設定により、アプリケーションで使用できる[ユーザーのタイプ](page://platform/user-types)が決まります。[**アプリアクセスのみ**] と [**アプリ + Enterpriseアクセス**] という2つのオプションがあります。 Box管理コンソールでこれらのアプリケーションのいずれかを[承認](g://authorization/custom-app-approval)すると、そのアプリケーションを表す[サービスアカウント](page://platform/user-types/#service-account) (`AutomationUser_xxxx_@boxdevedition.com`) が自動的に生成されます。このアカウントは管理者に似たユーザーで、APIを介してしかアクセスできません。その後、このユーザーを使用して、[App User](page://platform/user-types/#app-user)と呼ばれる、アプリケーションのユーザーを作成することができます。サービスアカウントとApp Userしか操作する必要がないアプリケーションの場合は、[**アプリアクセスのみ**] を選択します。[管理対象ユーザー](page://platform/user-types/#managed-users)とその既存のBoxコンテンツを操作する必要があるアプリケーションの場合は、[アプリ + Enterpriseアクセス] を選択します。 たとえば、読み取り/書き込みスコープと [アプリアクセスのみ] が指定されたJWTアプリケーションが管理コンソールで適切に[承認](g://authorization/custom-app-approval)されているとします。管理対象ユーザーがアクセストークンを取得し、自分が所有するフォルダに対してAPIコールを実行すると、「Cannot obtain token based on the enterprise configuration for your app (アプリに対するEnterpriseの構成に基づきトークンを取得できません)」というメッセージとともに400エラーが返されます。ユーザーにコンテンツへのアクセス権限があり、適切なスコープが有効になっていて、アプリが承認されていても、選択したアプリケーションアクセスで許可されるのは、アプリケーションによるサービスアカウントとApp Userの操作のみです。 ## Enterprise設定と承認 Box APIに関して言えば、注意すべきEnterprise設定がいくつかあります。 Platformアプリケーションは、公開アプリケーションと未公開アプリケーションという2つのカテゴリに分類されます。公開アプリケーションは、[Box統合](https://app.box.com/services)に表示されます。Box管理者は、公開アプリケーションと未公開アプリケーションをデフォルトで有効にすることによって、承認なしで使用できるようにするかどうかを決定できます。これらの設定のステータスにより、使用するアプリケーションを問題なく[承認](g://authorization/custom-app-approval)するために必要な操作が決まります。 上記の設定に関係なく、[JWT](g://authentication/jwt)または[クライアント資格情報許可](g://authentication/client-credentials)を利用するアプリケーションを企業で使用するために、管理者はBox管理コンソールでそのアプリケーションを明示的に[承認](g://authorization/custom-app-approval)する必要があります。承認は特定時点でのスナップショットです。つまり、開発者が開発者コンソールに再度アクセスして構成を変更した場合、管理者は、生成されたアクセストークンにその変更を反映するためにアプリケーションを再承認する必要があります。 [**デフォルトで未公開アプリを無効にする**] の設定をオンにした場合、管理者は、認証方法として[OAuth 2.0](g://authentication/oauth2)を利用しているアプリケーションを明示的に[有効にする](g://authorization/custom-app-approval)必要もあります。 また、この設定をオンにした場合は、サーバー認証アプリの有効化も必要になります。 **Source:** [https://ja.developer.box.com/guides/security/](https://ja.developer.box.com/guides/security/) --- ### セルフホストBox MCPサーバー **Type:** guide | **Category:** Box MCPサーバー | **Section:** Developer Guides セルフホストBox MCPサーバー セルフホストBox MCPサーバーとは、さまざまな操作 (ファイル検索、テキスト抽出、AIベースのクエリ実行、データ抽出など) を行うためにBox APIと統合されているPythonプロジェクトです。Box Pythonの次世代SDK… # セルフホストBox MCPサーバー [セルフホストBox MCPサーバー](https://github.com/box-community/mcp-server-box.git)とは、さまざまな操作 (ファイル検索、テキスト抽出、AIベースのクエリ実行、データ抽出など) を行うためにBox APIと統合されているPythonプロジェクトです。Box Pythonの次世代SDKライブラリを利用し、Boxのファイルやフォルダを操作するための一連のツールを提供します。 ## インストール ### 前提条件 - Python 3.13以上 - Box Platformアプリの資格情報 (クライアントID、クライアントシークレット) セルフホストBox MCPサーバーを設定するには、このセクションの手順に従います。 1. リポジトリを複製します。 ``` git clone https://github.com/box-community/mcp-server-box.git cd mcp-server-box ``` 1. `uv`がマシンにインストールされていない場合はインストールします。 ``` curl -LsSf https://astral.sh/uv/install.sh | sh ``` ``` powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" ``` その後ターミナルを再起動し、`uv`コマンドが取得されることを確認します。 1. プロジェクトを作成して設定します。 ``` # Create virtual environment and activate it uv venv source .venv/bin/activate # Lock the dependencies uv lock ``` ``` # Create virtual environment and activate it uv venv .venv\Scripts\activate # Lock the dependencies uv lock ``` 1. ルートディレクトリに`.env`ファイルを作成し、Box Platformアプリの資格情報を入力します。 ``` BOX_CLIENT_ID=your_client_id BOX_CLIENT_SECRET=your_client_secret ``` 動画によるチュートリアルを視聴して、Box MCPツールの使用例を確認することもできます。 ## Box MCPサーバーのローカルでの実行 Box MCPサーバーを起動するには、次のコマンドを実行します。 ``` uv --directory /Users/USER_NAME/PATH_TO_PROJECT/mcp-server-box run src/mcp_server_box.py ``` ローカルの設定が反映されるようにパスを更新します。 ### CursorをBox MCPクライアントとして使用する 前提条件: - [Cursorデスクトップアプリ](https://www.cursor.com/)をダウンロードする CursorでBox MCPサーバーの使用を開始するには、以下の手順に従います。 1. Cursorアプリを開きます。 2. 歯車アイコンをクリックして設定を開きます。 3. [Cursor Settings] タブで [`MCP`] を選択します。 4. [`Add new global MCP server`] ボタンをクリックします。これにより、`mcp.json`ファイルが開きます。 5. ローカルの設定を使用して値を更新し、次のJSONを貼り付けます。 ``` { "mcpServers": { "box": { "command": "uv", "args": [ "--directory", "/Users/USER_NAME/PATH_TO_PROJECT/mcp-server-box", "run", "src/mcp_server_box.py" ] } } } ``` 1. `mcp.json`ファイルを保存して閉じます。 2. 必要に応じて、Cursorを再起動します。 3. `box_authorize_app_tool`ツールを使用して、Box MCPの使用を開始します。 ### Claude for DesktopをBox MCPクライアントとして使用する 前提条件: - [Claude for Desktop](https://claude.ai/download)クライアントをダウンロードする - 必要に応じて、VS Codeの[`code`](https://code.visualstudio.com/docs/setup/mac#_configure-the-path-with-vs-code)コマンドを設定する Claude for DesktopでBox MCPを設定するには、以下の手順に従います。 1. `claude_desktop_config.json`を編集します。 ターミナルで次のコマンドを実行します。 ``` code ~/Library/Application\ Support/Claude/claude_desktop_config.json ``` または、Claudeのメインのナビゲーションで [`Settings`] を選択します。[Developers] タブを選択し、[`Edit Config`] をクリックします。これにより、`claude_desktop_config.json`を含むフォルダウィンドウが表示されます。 1. 構成を追加します。 ``` { "mcpServers": { "mcp-server-box": { "command": "uv", "args": [ "--directory", "/Users/Users/USER_NAME/PATH_TO_PROJECT/mcp-server-box", "run", "src/mcp_server_box.py" ] } } } ``` 1. Claude for Desktopを再起動します。 2. `box_authorize_app_tool`を使用してBox MCPサーバーを認証します。 ## 利用可能なツール ### 認証およびユーザーツール | ツール | 説明 | パラメータ | 戻り値 | | --- | --- | --- | --- | | box_who_am_i | 現在のユーザーの情報を取得し、接続のステータスを確認します。 | なし | ユーザー情報の文字列。 | | box_authorize_app_tool | Boxアプリケーションの承認プロセスを開始します。 | なし | 承認ステータスメッセージ。 | ### 検索およびナビゲーションツール | ツール | 説明 | パラメータ | 戻り値 | | --- | --- | --- | --- | | box_search_tool | Box内のファイルを検索します | - query (str): 検索クエリ。 - file_extensions (List[str], optional): 拡張子によるフィルタ。 - where_to_look_for_query (List[str], optional): 検索する場所。 - ancestor_folder_ids (List[str], optional): 検索を制限するためのフォルダID。 | 改行で区切られた、ファイル名とIDのリスト | | box_search_folder_by_name | 名前でフォルダを検索します | folder_name (str): フォルダの名前 | フォルダIDと情報 | | box_list_folder_content_by_folder_id | フォルダコンテンツのリストを取得します | folder_id (str): フォルダのID。 is_recursive (bool): 再帰的にリストを取得するかどうか。 | JSON形式のフォルダコンテンツ | ### ファイル操作 | ツール | 説明 | パラメータ | 戻り値 | | --- | --- | --- | --- | | box_read_tool | Boxファイルのテキストコンテンツを読み取ります | - file_id (str): 読み取るファイルのID。 | ファイルコンテンツ | | box_upload_file_from_path_tool | ローカルパスからファイルをアップロードします | file_path (str): ローカルファイルパス。 folder_id (str, optional): アップロード先フォルダID。 new_file_name (str, optional): 新しいファイルの名前。 | ファイルの詳細またはエラーメッセージ | | box_upload_file_from_content_tool | コンテンツをファイルとしてアップロードします | content (str|bytes): アップロードするコンテンツ。 file_name (str): ファイル名。 folder_id (str, optional): アップロード先フォルダID。 is_base64 (bool, optional): コンテンツがbase64でエンコードされているかどうか。 | アップロードの成功を示すメッセージ | | box_download_file_tool | Boxからファイルをダウンロードします | file_id (str): ファイルID。 save_file (bool, optional): ローカルに保存するかどうか。 save_path (str, optional): ローカルの保存パス。 | ファイルコンテンツまたは保存の確認 | ### フォルダ管理 | ツール | 説明 | パラメータ | 戻り値 | | --- | --- | --- | --- | | box_manage_folder_tool | フォルダを作成、更新、または削除します | - action (str): create、delete、またはupdate。 - folder_id (str, optional): フォルダID。 - name (str, optional): フォルダ名。 - parent_id (str, optional): 親フォルダID。 - description (str, optional): フォルダの説明。 - recursive (bool, optional): 再帰的な削除かどうか。 フォルダの詳細を含むステータスメッセージ ### Box AIのツール ツール | 説明 | | box_ask_ai_tool | ファイルについてBox AIに質問します | file_id (str): ファイルID。 prompt (str): AIに対する質問。 | AIの応答 | | box_ask_ai_tool_multi_file | 複数のファイルを使用してBox AIにクエリを実行します | file_ids (List[str]): ファイルIDのリスト。 prompt (str): AIに対する指示。 | AIが生成した回答 | | box_hubs_ask_ai_tool | HubについてBox AIに質問します | hubs_id (str): HubのID。 prompt (str): AIに対する質問。 | AIの応答 | | box_ai_extract_data | AIを使用してファイルからデータを抽出します | file_id (str): ファイルID。 fields (str): 抽出するフィールド。 | JSON形式で抽出されたデータ | ### Box Doc Genのツール | ツール | 説明 | パラメータ | 戻り値 | | --- | --- | --- | --- | | box_docgen_create_batch_tool | テンプレートを使用してドキュメントを生成します | - file_id (str): テンプレートファイルID。 - destination_folder_id (str): 出力フォルダID。 - user_input_file_path (str): JSON入力データのパス。 - output_type (str, optional): 出力形式。 | 一括生成の結果 | | box_docgen_get_job_tool | IDを指定してDoc Genジョブを取得します | job_id (str): ジョブの識別子 | JSON形式のジョブの詳細 | | box_docgen_list_jobs_tool | すべてのDoc Genジョブのリストを取得します | - marker (str, optional): ページ割りのマーカー。 - limit (int, optional): 返される最大ジョブ数。 | JSON形式のジョブのリスト | | box_docgen_list_jobs_by_batch_tool | 特定のバッチ内にあるジョブのリストを取得します | - batch_id (str): バッチの識別子。 - marker (str, optional): ページ割りのマーカー。 - limit (int, optional): 返される最大ジョブ数。 | バッチジョブの詳細 | | box_docgen_template_create_tool | ファイルをテンプレートとして設定します | file_id (str): 設定するファイルID | テープレートの詳細 | | box_docgen_template_list_tool | すべての使用可能なテンプレートのリストを取得します | - marker (str, optional): ページ割りのマーカー。 - limit (int, optional): リストに取得するテンプレートの最大数。 | テンプレートのリスト | | box_docgen_template_delete_tool | テンプレートの設定を削除します | template_id (str): テンプレートの識別子 | 削除の確認 | | box_docgen_template_get_by_id_tool | テンプレートの詳細を取得します | template_id (str): テンプレートの識別子 | テープレートの詳細 | | box_docgen_template_list_tags_tool | テンプレートタグのリストを取得します | - template_id (str): テンプレートID。 - template_version_id (str, optional): バージョンID。 - marker (str, optional): ページ割りのマーカー。 - limit (int, optional): 返される最大タグ数。 | タグのリスト | | box_docgen_template_list_jobs_tool | テンプレートを使用してジョブのリストを取得します | - template_id (str): テンプレートの識別子。 - marker (str, optional): ページ割りのマーカー。 - limit (int, optional): リストに取得する最大ジョブ数。 | ジョブの詳細 | ### Boxメタデータのツール | ツール | 説明 | パラメータ | 戻り値 | | --- | --- | --- | --- | | box_metadata_template_get_by_key_tool | キーを指定してメタデータテンプレートを取得します。 | template_name (str): 取得するメタデータテンプレートのキー。 | 指定したキーに関連付けられているメタデータテンプレート。 | | box_metadata_template_get_by_name_tool | 名前を指定してメタデータテンプレートを取得します。 | template_name (str): 取得するメタデータテンプレートの名前。 | 指定した名前に関連付けられているメタデータテンプレート。 | ## トラブルシューティング Claude for DesktopでMCPサーバーを実行したときにmacOSで`Error: spawn uv ENOENT`が発生した場合は、以下を実行できます。 - Homebrewを使用して`uv`を削除し手再インストールする: `brew install uv` - 構成内に`uv`実行可能ファイルのフルパスを指定する ``` /Users/USER_NAME/.local/bin/uv --directory /Users/USER_NAME/local/mcp-server-box run src/mcp_server_box.py ``` 設定に関連するその他の問題が発生した場合は、Boxの[Developer Communityフォーラム](https://community.box.com/ai-developers-23)に質問を投稿してください (英語のみ)。 **Source:** [https://ja.developer.box.com/guides/box-mcp/self-hosted/](https://ja.developer.box.com/guides/box-mcp/self-hosted/) --- ### タイプと形式 **Type:** guide | **Category:** APIコール | **Section:** Developer Guides タイプと形式 以下のセクションでは、Box API内で使用される可能性があるタイプと形式に関する基本的なコンセプトについて説明します。 リクエスト Box APIは、リクエスト本文でJSONを使用します。このルールには注目すべき例外がいくつかあります。 POST /oauth… # タイプと形式 以下のセクションでは、Box API内で使用される可能性があるタイプと形式に関する基本的なコンセプトについて説明します。 ## リクエスト Box APIは、リクエスト本文でJSONを使用します。このルールには注目すべき例外がいくつかあります。 - [`POST /oauth2/token`](endpoint://post-oauth2-token)はアクセストークンのリクエストに使用され、OAuth 2.0の仕様に従って、コンテンツタイプ`application/x-www-form-urlencoded`で送信される本文を受け入れます。 - [`POST /files/content`](endpoint://post-files-content)エンドポイントなど、バイナリデータをアップロードするのに使用されるほとんどのAPIでは、コンテンツタイプが`multipart/form-data`のフォームデータとしてデータが送信されることを予期します。 必須ではありませんが、`content-type: application/json`のように、送信されるデータのコンテンツタイプを定義するヘッダーを各APIリクエストで渡すことを強くお勧めします。 ### ヘッダー HTTP仕様に従い、Box APIのすべてのリクエストヘッダー名では大文字と小文字が区別されないため、小文字、大文字、または両方を組み合わせた形で指定できます。つまり、コンテンツタイプヘッダーは、`CONTENT-TYPE: application/json`、`content-type: application/json`、`content-type: application/json`、または多少変わった`cOnTeNt-TyPe: application/json`としても設定できます。 ヘッダーの値では、特に記載のない限り、大文字と小文字が区別されることがほとんどです。 ### GZip圧縮 デフォルトでは、Boxから送信されるデータは圧縮されません。帯域幅とレスポンス時間を改善するには、`Accept-Encoding: gzip, deflate`リクエストヘッダーを含めることでAPIレスポンスを圧縮できます。 ### 日付と時刻 Box APIは[RFC 3339](https://www.ietf.org/rfc/rfc3339.txt)タイムスタンプをサポートします。リクエスト内の日付の形式を設定するには、`2013-04-17T09:12:36-00:00`のように時刻をUTCに変換する方法をお勧めします。 タイムスタンプが特定の日に丸められる場合は、時刻部分を省略できます。この場合、`2013-04-17T13:35:01+00:00`は`2013-04-17`になります。タイムスタンプがミリ秒までサポートする場合、予期されるリクエストの形式は`2013-04-17T09:12:36.123-00:00`のようになります。 企業のタイムゾーンは経時的に変化するため、タイムゾーンはファイルやフォルダによって異なる場合があります。一般的な例は、夏時間です。標準時に作成された項目のタイムゾーンは、夏時間中に作成された項目とは異なります。このため、APIから返された日付を処理するには、`RFC3339`準拠の日時パーサーを使用することが重要です。 タイムスタンプは、Unixエポック (1970年1月1日) の`00:00:00 UTC`の開始後の日付に制限されます。 ## レスポンス 一般的に、Box APIはレスポンス本文でJSONを返します。このルールにも注目すべき例外がいくつかあります。 - 項目を削除するAPIでは、HTTPステータスコード`204 No Content`とともに空の本文が返されます。 - バイナリデータのリクエストに使用されるAPIでは、バイナリデータが添付されたステータスコード`200 OK`が返されるか、`202 Accepted`が返されるか、またはステータスコード`302 Found`とともに実際のバイナリファイルを指す`location`ヘッダーのみ (本文なし) が返されます。 `content-type`レスポンスヘッダーを使用すると、APIで返されるコンテンツのタイプがわかります。さらに、各APIエンドポイントのレスポンスタイプについては、APIリファレンスドキュメントで説明されています。 ### ヘッダー HTTP仕様に従い、Box APIのすべてのレスポンスヘッダー名では、大文字と小文字が区別されないため、今後変更される可能性があります。 つまり、APIでは、`CONTENT-TYPE: application/json`、`content-type: application/json`、または`content-type: application/json`というコンテンツタイプヘッダーが付いたレスポンスが返される可能性があります。リクエスト時にアプリケーションによってヘッダー名を標準の文字に変換された後、標準化されたそのヘッダーのセットを使用してヘッダーの値を検索できるのが理想的です。 ヘッダーの値では、特に記載のない限り、必ず大文字と小文字が区別されます。 ### リソース 1つしかリソースが返されない標準的なAPIレスポンスのほとんどは、次の形式に従っています。 ``` { "id": "12345", "type": "folder", ... } ``` これらのリソースはすべて、常に1つのIDとリソースのタイプを返します。 ### コレクション APIレスポンスで複数の項目が返される場合は、コレクションが返されます。これらのコレクションの正確な形式はエンドポイントごとに変わる場合がありますが、一般的には以下の形式になります。 ``` { "total_count": 5000, "limit": 1000, "offset": 2000, "order": [ { "by": "type", "direction": "ASC" } ], "entries": [ { "id": 12345, "etag": 1, "type": "file", "sequence_id": 3, "name": "Contract.pdf" } ] } ``` | フィールド | 必須かどうか? | | | --- | --- | --- | | entries | はい | コレクション内のエントリのリスト | | total_count | いいえ | リクエスト可能なコレクション内の合計数。このページの結果数よりも大きくてもかまいません。 | | limit | いいえ | オフセットベースのページ割りをサポートするエンドポイントに対して、返される結果の数の制限を指定します。 | | offset | いいえ | オフセットベースのページ割りをサポートするエンドポイントに対して、返される結果のオフセットを指定します。 | | order | いいえ | 並べ替えをサポートするエンドポイントに対して、結果が返される順番を指定します。 | | next_marker | いいえ | マーカーベースのページ割りをサポートするエンドポイントに対して、返すことができる次のページのマーカーを指定します。 | | prev_marker | いいえ | マーカーベースのページ割りをサポートするエンドポイントに対して、返すことができる前のページのマーカーを指定します。 | ### リクエストID APIコールがエラーで返されると、BoxのAPIから`request_id`フィールドを含むエラーオブジェクトが返されます。 ``` { "type": "error", "status": 400, "code": "item_name_invalid", "help_url": "https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/", "message": "Method Not Allowed", "request_id": "abcdef123456" } ``` 特定のエラーについてサポートに連絡する場合は、サポートチームがリクエストをすぐに見つけられるよう、`request_id`を含むAPIレスポンス全体を提供してください。 ほとんどのAPIコールでは、`box-request-id`レスポンスヘッダーも返されます。このヘッダーの値を、エラーレスポンスの本文に含まれる`request_id`値と混同しないでください。 ### 大きな数値 場合によっては、APIでフィールドに対して極端に大きな数値が返されることがあります。たとえば、フォルダのサイズがテラバイト級のデータまで大きくなった場合、結果として、フォルダの`size`フィールドが、非常に大きな数値になっている可能性があります。 このような場合は、これらの数値は`1.2318237429383e+31`などの[IEEE754](https://en.wikipedia.org/wiki/IEEE_754)形式で返されます。 **Source:** [https://ja.developer.box.com/guides/api-calls/types-and-formats/](https://ja.developer.box.com/guides/api-calls/types-and-formats/) --- ### ダウンロード **Type:** guide | **Category:** ダウンロード | **Section:** Developer Guides ダウンロード Box API… # ダウンロード Box APIを使用すると、ファイルをアプリケーションのサーバーにダウンロードすることも、エンドユーザーがブラウザで直接ダウンロードすることもできます。 ## ダウンロードすべきでない場合 ファイルのダウンロードが必ずしも望ましい解決策であるとは限りません。特に、ユーザーがプレビューしたりコメントや注釈を付けたりするためだけにファイルがダウンロードされる場合にこれが当てはまります。このような場合は、Boxの機能をアプリケーションに直接埋め込む方法のいずれかを利用することをお勧めします。 Boxの埋め込みの詳細を確認する ## アクセスエラー アプリケーションには、ダウンロードするファイルへのアクセス権限が必要であると理解しておくことが重要です。アプリケーションがJWTまたはアプリトークンを使用して認証される場合、ユーザーはサービスアカウントとして認証されます。このサービスアカウントには、そのアカウントが所有していないファイルへのアクセス権限がありません。 このユーザーがファイルにアクセスできない場合、アプリケーションでは`404 Not Found`エラーが表示されます。 各種ユーザータイプの詳細を確認する **Source:** [https://ja.developer.box.com/guides/downloads/](https://ja.developer.box.com/guides/downloads/) --- ### ダウンロードURLの取得 **Type:** guide | **Category:** ダウンロード | **Section:** Developer Guides ダウンロードURLの取得 Box公式SDKでは、ファイルのダウンロード時にバイナリデータが返されます。代わりにデータのダウンロードURLを取得する場合は、SDKの以下のメソッドを使用します。 リダイレクト Box SDKのいずれも使用していない場合は、HTTP… # ダウンロードURLの取得 Box公式SDKでは、ファイルのダウンロード時にバイナリデータが返されます。代わりにデータのダウンロードURLを取得する場合は、SDKの以下のメソッドを使用します。 # リダイレクト Box SDKのいずれも使用していない場合は、HTTPクライアントが自動的にHTTPリダイレクトに従わないようにすることが重要です。リダイレクトに自動的に従うと、コードは、APIによって返された`location`ヘッダーを検出し、それに従ってバイナリデータを取得します。 ## ダウンロードURLの有効期限 このダウンロードURLは、ファイルのダウンロードを許可するためにユーザーのブラウザに渡すことができますが、このURLが期限切れになった後でダウンロードするには再度リクエストする必要があります。ほとんどの場合、ダウンロードURLは15分間有効です。その後、新しいURLをリクエストする必要があります。この有効期限は、事前の通知なしに変更される場合があります。 **Source:** [https://ja.developer.box.com/guides/downloads/get-url/](https://ja.developer.box.com/guides/downloads/get-url/) --- ### タスク **Type:** guide | **Category:** タスク | **Section:** Developer Guides … # タスク ユーザーはタスクを使用することで、ファイルのコラボレータに対して、ファイルのレビューや作業の一部の完了をリクエストできます。タスクは、開発者がファイル中心のワークフローを作成するために使用できます。タスクの詳細については、[**コメントとタスクの追加**](https://support.box.com/hc/ja/articles/360043695954-%E3%82%B3%E3%83%A1%E3%83%B3%E3%83%88%E3%81%A8%E3%82%BF%E3%82%B9%E3%82%AF%E3%81%AE%E8%BF%BD%E5%8A%A0)を参照してください。 ## タスクのアクション Boxは現在、`action`値によって定義される、`review`と`complete`という2種類のタスクをサポートしています。 タスクのタイプによって、タスクがなりうる解決状態と、ウェブアプリおよびモバイルアプリでユーザーに表示されるインターフェースが決まります。 | タスクのアクション | 考えられる解決状態 | | --- | --- | | review | incomplete, approved, rejected | | complete | incomplete, complete | `review`タスクは`incomplete`状態で開始され、`incomplete`、`approved`、または`rejected`としてマークすることができます。ユーザーインターフェースには、テキストボックスのほか、タスクを承認または拒否する1組のボタンが表示されます。 `complete`タスクは`incomplete`状態で開始され、`incomplete`または`completed`としてマークすることができます。このタスクが完了としてマークされると、タスクの状態をそれ以上変更することはできなくなります。ユーザーインターフェースには、テキストボックスのほか、タスクを完了としてマークするためのボタンが表示されます。 ## 完了のルール ファイルに関連するタスクは、そのファイルの複数のコラボレータに割り当てることができます。また、タスクの`completion_rule`を使用すると、タスクを完了する必要があるのはタスクが割り当てられているすべてのユーザー (`all_assignees`) か1人の担当者のみ (`any_assignee`) かを定義できます。 **Source:** [https://ja.developer.box.com/guides/tasks/](https://ja.developer.box.com/guides/tasks/) --- ### タスクに関する情報の取得 **Type:** guide | **Category:** タスク | **Section:** Developer Guides タスクに関する情報の取得 割り当てられたタスクに関する情報を取得するには、タスクのidを指定してGET /tasks/:task_id APIを呼び出します。 # タスクに関する情報の取得 割り当てられたタスクに関する情報を取得するには、タスクの`id`を指定して[`GET /tasks/:task_id`](e://get_tasks_id) APIを呼び出します。 **Source:** [https://ja.developer.box.com/guides/tasks/get/](https://ja.developer.box.com/guides/tasks/get/) --- ### タスクの作成 **Type:** guide | **Category:** タスク | **Section:** Developer Guides タスクの作成 タスクを作成するには、タスクのactionと、タスクの追加先となるファイルを表すitemを指定してPOST /tasks APIを呼び出す必要があります。 タスクのアクション Boxは現在、action値によって定義される、reviewとcompleteという… # タスクの作成 タスクを作成するには、タスクの`action`と、タスクの追加先となるファイルを表す`item`を指定して[`POST /tasks`](e://post_tasks) APIを呼び出す必要があります。 ## タスクのアクション Boxは現在、`action`値によって定義される、`review`と`complete`という2種類のタスクをサポートしています。 タスクのタイプによって、タスクがなりうる解決状態と、ウェブアプリおよびモバイルアプリでユーザーに表示されるインターフェースが決まります。 | タスクのアクション | 考えられる解決状態 | | --- | --- | | review | incomplete, approved, rejected | | complete | incomplete, complete | `review`タスクは`incomplete`状態で開始され、`incomplete`、`approved`、または`rejected`としてマークすることができます。ユーザーインターフェースには、テキストボックスのほか、タスクを承認または拒否する1組のボタンが表示されます。 `complete`タスクは`incomplete`状態で開始され、`incomplete`または`completed`としてマークすることができます。このタスクが完了としてマークされると、タスクの状態をそれ以上変更することはできなくなります。ユーザーインターフェースには、テキストボックスのほか、タスクを完了としてマークするためのボタンが表示されます。 ## 完了のルール ファイルに関連するタスクは、そのファイルの複数のコラボレータに割り当てることができます。また、タスクの`completion_rule`を使用すると、タスクを完了する必要があるのはタスクが割り当てられているすべてのユーザー (`all_assignees`) か1人の担当者のみ (`any_assignee`) かを定義できます。 **Source:** [https://ja.developer.box.com/guides/tasks/create/](https://ja.developer.box.com/guides/tasks/create/) --- ### タスクの削除 **Type:** guide | **Category:** タスク | **Section:** Developer Guides タスクの削除 タスクを削除するには、タスクのidを指定してDELETE /tasks/:task_id APIを呼び出します。 # タスクの削除 タスクを削除するには、タスクの`id`を指定して[`DELETE /tasks/:task_id`](e://delete_tasks_id) APIを呼び出します。 **Source:** [https://ja.developer.box.com/guides/tasks/delete/](https://ja.developer.box.com/guides/tasks/delete/) --- ### タスクの割り当て **Type:** guide | **Category:** タスク | **Section:** Developer Guides タスクの割り当て Boxでタスクがユーザーに委任されると、タスク割り当てが作成されます。タスク割り当ては、そのユーザーにタスクを完了するよう求めるリクエストです。 タスクの解決方法は、タスクのactionタイプと、タスクの解決方法を定義するために使用されるresolution… # タスクの割り当て Boxでタスクがユーザーに委任されると、タスク割り当てが作成されます。タスク割り当ては、そのユーザーにタスクを完了するよう求めるリクエストです。 タスクの解決方法は、タスクの`action`タイプと、タスクの解決方法を定義するために使用される`resolution_state`によって異なります。 タスクのタイプについて確認する **Source:** [https://ja.developer.box.com/guides/tasks/assignments/](https://ja.developer.box.com/guides/tasks/assignments/) --- ### タスクの割り当てのリストの取得 **Type:** guide | **Category:** タスク | **Section:** Developer Guides タスクの割り当てのリストの取得 特定のタスクのすべての割り当てのリストを取得するには、タスクidを指定してGET /tasks/:task_id/assignmentsを呼び出します。 # タスクの割り当てのリストの取得 特定のタスクのすべての割り当てのリストを取得するには、タスク`id`を指定して[`GET /tasks/:task_id/assignments`](e://get_task_assignments_id)を呼び出します。 **Source:** [https://ja.developer.box.com/guides/tasks/assignments/list/](https://ja.developer.box.com/guides/tasks/assignments/list/) --- ### タスク割り当てに関する情報の取得 **Type:** guide | **Category:** タスク | **Section:** Developer Guides タスク割り当てに関する情報の取得 割り当てられたタスクに関する情報を取得するには、タスク割り当てのidを指定してGET /tasks/:task_id/assignments APIを呼び出します。 # タスク割り当てに関する情報の取得 割り当てられたタスクに関する情報を取得するには、タスク割り当ての`id`を指定して[`GET /tasks/:task_id/assignments`](e://get_task_assignments_id) APIを呼び出します。 **Source:** [https://ja.developer.box.com/guides/tasks/assignments/get/](https://ja.developer.box.com/guides/tasks/assignments/get/) --- ### タスク割り当ての解除 **Type:** guide | **Category:** タスク | **Section:** Developer Guides タスク割り当ての解除 タスクの割り当てを解除するには、タスク割り当てのidを指定してDELETE /task_assignments APIを呼び出します。 権限 割り当てを削除するユーザーは、ファイルのコラボレータである必要があります。 # タスク割り当ての解除 タスクの割り当てを解除するには、タスク割り当ての`id`を指定して[`DELETE /task_assignments`](e://delete_task_assignments_id) APIを呼び出します。 # 権限 割り当てを削除するユーザーは、ファイルのコラボレータである必要があります。 **Source:** [https://ja.developer.box.com/guides/tasks/assignments/unassign/](https://ja.developer.box.com/guides/tasks/assignments/unassign/) --- ### タスク割り当て状態の変更 **Type:** guide | **Category:** タスク | **Section:** Developer Guides タスク割り当て状態の変更 タスク割り当ての状態を更新するには、PUT /tasks/:task_id/assignments APIを呼び出し、completed、incomplete、approved、rejectedなどのresolution_state… # タスク割り当て状態の変更 タスク割り当ての状態を更新するには、[`PUT /tasks/:task_id/assignments`](e://put_task_assignments_id) APIを呼び出し、`completed`、`incomplete`、`approved`、`rejected`などの`resolution_state`を含めます。 ## 解決状態 Boxは現在、`action`値によって定義される、`review`と`complete`という2種類のタスクをサポートしています。 タスクのタイプによって、タスクがなりうる解決状態と、ウェブアプリおよびモバイルアプリでユーザーに表示されるインターフェースが決まります。 | タスクのアクション | 考えられる解決状態 | | --- | --- | | review | incomplete, approved, rejected | | complete | incomplete, complete | `review`タスクは`incomplete`状態で開始され、`incomplete`、`approved`、または`rejected`としてマークすることができます。ユーザーインターフェースには、テキストボックスのほか、タスクを承認または拒否する1組のボタンが表示されます。 `complete`タスクは`incomplete`状態で開始され、`incomplete`または`completed`としてマークすることができます。このタスクが完了としてマークされると、タスクの状態をそれ以上変更することはできなくなります。ユーザーインターフェースには、テキストボックスのほか、タスクを完了としてマークするためのボタンが表示されます。 **Source:** [https://ja.developer.box.com/guides/tasks/assignments/change-state/](https://ja.developer.box.com/guides/tasks/assignments/change-state/) --- ### ツール **Type:** guide | **Category:** ツール | **Section:** Developer Guides ツール Boxには、Box CLI、Postman、Salesforce Developer Toolkit、各種SDKなど、Box APIを使用するためのオプションがいくつか用意されています。 # ツール Boxには、[Box CLI](g://cli)、[Postman](g://tooling/postman)、[Salesforce Developer Toolkit](g://tooling/salesforce-toolkit)、[各種SDK](g://tooling/sdks)など、Box APIを使用するためのオプションがいくつか用意されています。 **Source:** [https://ja.developer.box.com/guides/tooling/](https://ja.developer.box.com/guides/tooling/) --- ### ディープリンク **Type:** guide | **Category:** モバイル | **Section:** Developer Guides ディープリンク Boxのモバイルアプリでは、フォルダオブジェクトとファイルオブジェクトへのディープリンクがサポートされています。ウェブページまたはネイティブアプリからディープリンクを使用してBoxで直接オブジェクトを開くことができます。 Boxのモバイルアプリでは、以下のURL… # ディープリンク Boxのモバイルアプリでは、フォルダオブジェクトとファイルオブジェクトへのディープリンクがサポートされています。ウェブページまたはネイティブアプリからディープリンクを使用してBoxで直接オブジェクトを開くことができます。 Boxのモバイルアプリでは、以下のURLがサポートされています。 | アプリケーション | オブジェクトタイプ | ディープリンクのURL | iOSおよびAndroid | | --- | --- | --- | --- | | Box | フォルダ | boxapp://folder?id=[folderid] | バージョン3.7以降 | | | ファイル | boxapp://file?id=[fileid] | | | | 共有リンク | boxapp://sharedlink?url=[sharedlink] | | | | | | | | Box for EMM | フォルダ | boxemm://folder?id=[folderid] | バージョン3.7以降 | | | ファイル | boxemm://file?id=[fileid] | | | | 共有リンク | boxemm://sharedlink?url=[sharedlink] | | **Source:** [https://ja.developer.box.com/guides/mobile/mobile-deep-linking/](https://ja.developer.box.com/guides/mobile/mobile-deep-linking/) --- ### テキストレプリゼンテーションの取得 **Type:** guide | **Category:** レプリゼンテーション | **Section:** Developer Guides テキストレプリゼンテーションの取得 テキストレプリゼンテーションでは、ドキュメントからプレーンテキストを抽出できます。 テキストは、プレーンテキストを含むさまざまな種類のドキュメントファイルやBox… # テキストレプリゼンテーションの取得 テキストレプリゼンテーションでは、ドキュメントからプレーンテキストを抽出できます。 テキストは、プレーンテキストを含むさまざまな種類のドキュメントファイルやBoxでサポートされているコードファイルに対して生成されます。テキストレイヤがないため、画像ファイルは含まれません。 テキストレプリゼンテーションは、PDFやサムネイルと同様に、ファイルのアップロード時に生成されます。ただし、500 MBを超えるファイルに対しては生成されません。 ## 手順 テキストレプリゼンテーションを取得するには、以下の手順に従います。 - [すべてのレプリゼンテーションのリストを取得する](guide://representations/list-all-representations) - 値`[extracted_text]`を指定した`x-rep-hints`ヘッダーを渡して、[テキストレプリゼンテーションをリクエスト](guide://representations/request-a-representation)する - `url_template`を呼び出して[テキストをダウンロード](guide://representations/download-a-representation)する。その際、`{+asset_path}`を空の文字列に置き換えます。 **Source:** [https://ja.developer.box.com/guides/representations/text/](https://ja.developer.box.com/guides/representations/text/) --- ### デフォルトのBox Sign通知の抑制 **Type:** guide | **Category:** Box Sign | **Section:** Developer Guides デフォルトのBox Sign通知の抑制 Box Sign APIを使用すると、Signのワークフローの中で送信されるデフォルトのBoxメール通知を抑制できます。この機能により、以下のようにBox Sign… # デフォルトのBox Sign通知の抑制 Box Sign APIを使用すると、Signのワークフローの中で送信されるデフォルトのBoxメール通知を抑制できます。この機能により、以下のようにBox Sign通知の管理を容易にします。 - 全面的にカスタマイズしたメール通知テンプレートを使用して、自社のドメインからメールを送信できます。 - メールとは別に、プッシュ通知またはテキストメッセージを送信できます。​ Boxメール通知を抑制することを選択すると、組織は、該当する場合に、使用される配信方法に対して署名者の同意を得ることを含め、適用されるすべての法律と規制に従い、署名プロセスにおいて適切なタイミングで適切な内容を含むすべての通知を署名者に確実に配信する責任を負うことになります。 ## Box Sign APIを使用したデフォルトの通知の抑制 Box Signのメール通知を抑制するには、以下のパラメータを設定する必要があります。 1. [`signers`](e://post-sign-requests/#param-signers)オブジェクトの`suppress_notifications`パラメータを`true`に設定して、通知をオフにします。 2. [`embed_url_external_user_id`](e://post-sign-requests/#param-signers-embed_url_external_user_id)パラメータを設定して、通知を送信しないユーザーを指定します。 この構成により、指定したユーザーに対するBox Signの自動メール通知は無効になります。その結果、独自の通知を構成して送信できます。 ``` curl -i -X POST "https://api.box.com/2.0/sign_requests" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -d '{ "signers": [ { "role": "signer", "email": "example_email@box.com" "suppress_notifications": true "embed_url_external_user_id": "1234" } ], "source_files": [ { "type": "file", "id": "123456789" } ], "parent_folder": { "type": "folder", "id": "0987654321" } }' ``` ## 署名ログのエントリ Box Signのデフォルトの通知が抑制されると、署名ログには、送信者によってすべてのBox Sign通知が抑制されたことが記録されます。また、このログには、API統合を介してBox Signに提供される、通知配信の目的で使用されるシステムに関する情報や組織のシステムにおける署名者のユーザーIDも記録されます。 **Source:** [https://ja.developer.box.com/guides/box-sign/suppress-sign-notifications/](https://ja.developer.box.com/guides/box-sign/suppress-sign-notifications/) --- ### テンプレートのファイルリクエストの作成 **Type:** guide | **Category:** ファイルリクエスト | **Section:** Developer Guides テンプレートのファイルリクエストの作成 現在、このAPI… # テンプレートのファイルリクエストの作成 現在、このAPIで可能なのは、別のフォルダに関連付けられた既存のファイルリクエストをコピーして新しいファイルリクエストを作成することだけです。テンプレートのファイルリクエストを使用したテンプレートフォルダの作成に関する以下のガイドを確認してください。 ## 1. テンプレートフォルダ 最初に、テンプレートのファイルリクエストを関連付けることができるテンプレートフォルダを作成します。これは実際にはどのフォルダでもかまいませんが、この目的でのみ使用されるフォルダを使用することをお勧めします。 フォルダはBoxウェブインターフェースまたはモバイルインターフェース、あるいは[`POST /folders`](e://post_folders) APIを使用して作成できます。 サーバー側JWT認証を使用する場合は、アプリケーションの[サービスアカウント](page://platform/user-types/#service-account)が所有するフォルダを作成することをお勧めします。こうすることで、通常のBoxユーザーが誤ってこのフォルダを削除することはなくなります。 ## 2. テンプレートのファイルリクエスト ファイルリクエストを作成するには、ウェブアプリのテンプレートフォルダに移動し、ページの上部にある3つの点をクリックします。その後、メニューから [**ファイルリクエスト**] を選択します。 次の設定パネルで、[**編集**] ボタンをクリックして、ファイルリクエストの設定ページにアクセスします。 設定ページで、ページを保存する前に、タイトルと説明を設定できます。 このページには、URLに含まれるファイルリクエストのIDも表示されます。URLの末尾の数字がファイルリクエストのIDなので、このURLを書き留めてください。これは、APIを使用する際に必要になります。 ``` https://*.app.box.com/filerequest/2338423584 ``` テンプレートフォルダがJWTユーザーに属している場合は、管理対象Boxユーザーをフォルダに[招待](e://post-collaborations)し、そのフォルダがウェブアプリに表示されるようにする必要があります。自分自身をフォルダに招待すると、自分でこのアプリを使用してファイルリクエストをフォルダに追加できます。 ## 3. テンプレートの使用 テンプレートのファイルリクエストを使用すると、[`POST /file-requests/:id/copy`](e://post_file_requests_id_copy) APIによって新しいコピーを作成できます。新しいフォルダのIDを取得したら、[1回のAPIコール](g://file-requests/copy)で既存のリクエスト (タイトル、説明、フォームの設定を含む) を新しいフォルダにコピーできます。 **Source:** [https://ja.developer.box.com/guides/file-requests/template/](https://ja.developer.box.com/guides/file-requests/template/) --- ### トークン **Type:** guide | **Category:** 認証 | **Section:** Developer Guides トークン さまざまなBox APIコールの中核となるのはアクセストークンです。Box… # トークン さまざまなBox APIコールの中核となるのはアクセストークンです。Boxウェブアプリを使用する場合と同様に、問題なく操作できるのは、アクセストークンに関連付けられたユーザーが所有するコンテンツまたはコラボレータとなっているコンテンツのみです。これは、トークンの[ダウンスコープ](g://authentication/tokens/downscope)によってさらに制限できます。 必須のアクセススコープ、アプリケーションアクセス、有効化された詳細設定、ユーザー権限、およびエンドポイント固有の制限は、すべてが合わさることで、どのAPIコールが成功するかが決まります。たとえば、フォルダに対するコラボレータアクセス権限がユーザーにある場合でも、読み取りスコープがアプリケーションに許可されていなければ、そのフォルダに関する情報を取得するコールは失敗します。 ## トークンの種類 | 型 | 有効期間 | | --- | --- | | アクセストークン | 60分 | | 更新トークン | 60日または1回の使用 | | 開発者トークン | 60分 | ## アプリケーションの種類とアクセストークン それぞれのアプリケーションの種類でどのようにアクセストークンが作成されるのかを以下に示します。 | Boxアプリケーションの種類 | アクセストークンの取得方法 | | --- | --- | | PlatformアプリとOAuth 2.0 | 明示的なユーザーによる付与 | | PlatformアプリとJWT | JWTアサーションの交換 | | Platformアプリとクライアント資格情報許可 | クライアントIDとクライアントシークレットの使用 | | アクセス制限付きアプリとアプリトークン | 開発者コンソールでのトークンの構成 | | カスタムスキル | イベントペイロードのアクセストークン | **Source:** [https://ja.developer.box.com/guides/authentication/tokens/](https://ja.developer.box.com/guides/authentication/tokens/) --- ### トークンおよびURLの有効期限 **Type:** guide | **Category:** APIコール | **Section:** Developer Guides トークンおよびURLの有効期限 Box APIには、自動的に有効期限が切れるトークン、コード、およびURLがいくつかあります。以下に、それぞれの有効期間の概要を示します。 承認コード 30秒後に有効期限切れ アクセストークン 60分後に有効期限切れ 更新トークン 6… # トークンおよびURLの有効期限 Box APIには、自動的に有効期限が切れるトークン、コード、およびURLがいくつかあります。以下に、それぞれの有効期間の概要を示します。 | | | | --- | --- | | 承認コード | 30秒後に有効期限切れ | | アクセストークン | 60分後に有効期限切れ | | 更新トークン | 60日後または1回の使用後に有効期限切れ | | ダウンロードURL | 15分後に有効期限切れ | 詳細については、それぞれのガイドを参照してください。 **Source:** [https://ja.developer.box.com/guides/api-calls/permissions-and-errors/expiration/](https://ja.developer.box.com/guides/api-calls/permissions-and-errors/expiration/) --- ### トークンのダウンスコープ **Type:** guide | **Category:** 認証 | **Section:** Developer Guides … # トークンのダウンスコープ ダウンスコープは、既存のアクセストークンをより制限の厳しい新しいトークンと交換するための方法です。 ## ダウンスコープする理由 アプリケーションは、完全に制御できない環境とアクセストークンを共有しなければならないことがあります。その一般的な例として、ウェブブラウザでBox UI Elementsを使用する場合があります。 アプリケーションがアクセストークンをブラウザに渡す必要がある場合、解決が必要となるセキュリティリスクが生じる可能性があります。このリスクを抑制するために、アクセストークンを、権限がより厳格な新しいトークンと交換できます。 ## 概要 ダウンスコープされたトークンは、元のトークンよりも権限 (スコープ) が少ないトークンです。また、オプションで、特定のファイルへのアクセスのみを許可するようさらに制限される場合もあります。 新しいトークンは、元のトークンの権限を取得し、渡されたトークンのほか、提供されたリソースにその権限を制限します。 ## ダウンスコープの実例 トークンをダウンスコープするには、`POST /oauth2/token`エンドポイントに既存のアクセストークン、スコープのリストのほか、トークンを制限するファイルのURL (省略可) を渡します。 | パラメータ | 説明 | | --- | --- | | subject_token | ダウンスコープする元のトークン。これには、OAuth 2.0やJWTトークン交換で取得したトークン、またはアプリトークンとして取得されたトークンを使用できます。 | | scope | 新しいトークンを制限するためのスコープのスペース区切りリスト。アプリケーションに有効な任意のスコープを使用できますが、Box UI Elementsのスコープの特殊なセットも使用可能です。 | | resource | トークンが制限されるファイルへの完全なURLパス (省略可)。 | | box_shared_link | Box上のファイルまたはフォルダの共有リンクURL (省略可)。パスワード保護されているリンクはサポートされていません。このオプションは、resourceオプションに追加して使用することができません。また、ウェブリンクに作成された共有リンクを指定することもできません。 | | subject_token_type | 常にurn:ietf:params:oauth:token-type:access_tokenに設定します。 | | grant_type | 常にurn:ietf:params:oauth:grant-type:token-exchangeに設定します。 | ## ダウンスコープされたアクセストークンオブジェクト `POST /oauth2/token`エンドポイントで返されるダウンスコープされたアクセストークンには、特定の制限に関する追加情報が含まれます。 ``` { "access_token": "1!DgsZ6V9kMWZu2StrxwQDF5BudQNen-xUmU2cfcVKArE....", "expires_in": 4175, "token_type": "bearer", "restricted_to": [ { "scope": "item_preview", "object": { "type": "folder", "id": "1234567890", "sequence_id": "0", "etag": "0", "name": "Test" } } ], "issued_token_type": "urn:ietf:params:oauth:token-type:access_token" } ``` ここで最も重要なのは、`restricted_to`エントリのリストです。このリストには、新しいトークンが権限を持つ`object`と`scope`の各組み合わせが含まれます。 ダウンスコープされたトークンに更新トークンは含まれません。新しいダウンスコープされたトークンを取得するには、元の更新トークンを更新し、その新しいトークンを使用してダウンスコープされたトークンを取得します。 **Source:** [https://ja.developer.box.com/guides/authentication/tokens/downscope/](https://ja.developer.box.com/guides/authentication/tokens/downscope/) --- ### トークンの使用 **Type:** guide | **Category:** 認証 | **Section:** Developer Guides トークンの使用 すべての認証済みAPIコールでは、Bearer TokenとしてアクセストークンをAuthorizationヘッダーに含めて渡す必要があります。そうしないと、401 Unauthorized HTTP… # トークンの使用 すべての認証済みAPIコールでは、`Bearer Token`としてアクセストークンを`Authorization`ヘッダーに含めて渡す必要があります。そうしないと、`401 Unauthorized` HTTPステータスが返されます。 ``` curl https://api.box.com/2.0/users/me \ -H "authorization: Bearer EGmDmRVfhfHsqesn5yVYHAqUkD0dyDfk" ``` アクセストークンが認証されるユーザーを調べるには、[`GET /users/me`](endpoint://get-users-id)エンドポイントを使用してください。 **Source:** [https://ja.developer.box.com/guides/authentication/tokens/api-calls/](https://ja.developer.box.com/guides/authentication/tokens/api-calls/) --- ### トークンの取り消し **Type:** guide | **Category:** 認証 | **Section:** Developer Guides トークンの取り消し アクセストークンまたは更新トークンをPOST /oauth2/revokeエンドポイントに送信することにより、アクセストークンをいつでも取り消すことができます。 SDKでの使用方法 すべてのBox SDK… # トークンの取り消し アクセストークンまたは更新トークンを[`POST /oauth2/revoke`](endpoint://post-oauth2-revoke)エンドポイントに送信することにより、アクセストークンをいつでも取り消すことができます。 # SDKでの使用方法 すべてのBox SDKでは、クライアントに関連付けられた現在のアクセストークンを手動で取り消すことがサポートされています。特定のトークンを取り消すには、最初にそのトークンで新しいSDKを初期化してから、関連する取り消しメソッドを呼び出します。 **Source:** [https://ja.developer.box.com/guides/authentication/tokens/revoke/](https://ja.developer.box.com/guides/authentication/tokens/revoke/) --- ### トークンの更新 **Type:** guide | **Category:** 認証 | **Section:** Developer Guides トークンの更新 アクセストークンを更新するには、アクセストークンに付属された更新トークンを使用します。更新は、アクセストークンの有効期限の前でも後でも行うことができます。 これを行うには、アプリケーションで以下のようにrefresh_tokenをPOST /oauth… # トークンの更新 アクセストークンを更新するには、アクセストークンに付属された更新トークンを使用します。更新は、アクセストークンの有効期限の前でも後でも行うことができます。 これを行うには、アプリケーションで以下のように`refresh_token`を[`POST /oauth2/token`](endpoint://post-oauth2-token)エンドポイントに渡します。 # SDKでの使用方法 すべてのBox SDKは、JWTおよびOAuth 2.0アプリケーションのためにアクセストークンの自動更新をサポートしています。 # 更新トークンの有効期限 更新トークンの有効期限は60日間で、このトークンを使用すると、新しいアクセストークンと更新トークンを1回だけ取得できます。アクセストークンと更新トークンが60日以内に更新されなかった場合は、ユーザーの再承認が必要になります。 アプリケーションが更新トークンを使用して新しいアクセストークンを取得するたびに、更新トークンは無効になり、新しい更新トークンが新しいアクセストークンとともに返されます。 その後、この新しい更新トークンは再度60日以内に1回だけ使用できます。 **Source:** [https://ja.developer.box.com/guides/authentication/tokens/refresh/](https://ja.developer.box.com/guides/authentication/tokens/refresh/) --- ### ドキュメントの生成 **Type:** guide | **Category:** Box Doc Gen | **Section:** Developer Guides ドキュメントの生成 POST /2.0/docgen_batchesエンドポイントを使用すると、Box Doc Genテンプレートを入力データとして使用してドキュメントを生成できます。 前提条件 Box Doc Gen APIの使用を開始する前に、Box Doc Gen… # ドキュメントの生成 `POST /2.0/docgen_batches`エンドポイントを使用すると、Box Doc Genテンプレートを入力データとして使用してドキュメントを生成できます。 ## 前提条件 Box Doc Gen APIの使用を開始する前に、[Box Doc Genの使い方](g://docgen/docgen-getting-started)ガイドに記載されている手順に従って、PlatformアプリとBox Doc Genテンプレートを作成してください。 ## リクエストの送信 ドキュメント (複数可) を生成するには、`POST /2.0/docgen_batches`エンドポイントを使用します。 ### パラメータ コールを実行するには、以下のパラメータを渡す必要があります。必須のパラメータは**太字**で示されています。 | パラメータ | 説明 | 例 | | --- | --- | --- | | file.id | Box Doc Genテンプレートとして設定するファイルのID。 | 12345678 | | file.type | 指定した入力データの種類。値は常に**file**になります。 | file | | file_version | テンプレートのファイルバージョン。 | 12345 | | input_source | 生成されるドキュメントの入力ソース。この値は、APIベースのすべてのドキュメント生成リクエストでapiにする必要があります。 | api | | output_type | 出力ファイルの種類。 | docx, pdf | | destination_folder.id | 生成されたドキュメントが保存されるフォルダのID。 | 12345678 | | destination_folder.type | 保存先の項目の種類。生成されたファイルはフォルダに保存されるため、値は常に**folder**になります。 | file | | document_generation_data.generated_file_name | 生成されるファイルの名前。 | New_Template | | document_generation_data.user_input | ドキュメントの生成に使用するJSONデータ。 | {"id": 2, "name": "Ink Cartridge", "type": "non-fragile"} | ## ユースケース Box Doc GenテンプレートとJSONデータを準備できたら、Box Doc Gen APIにドキュメント生成のリクエストを行うことができます。 コールのサンプルは次のようになります。 リクエストが処理されている間、`document_generation_data`配列の各エントリは個別のドキュメント生成ジョブとして処理され、そのジョブは、Box Doc Genによってドキュメント生成キューに追加されます。 生成されたドキュメントは、指定したフォルダに保存されます。 **Source:** [https://ja.developer.box.com/guides/docgen/generate-document/](https://ja.developer.box.com/guides/docgen/generate-document/) --- ### ドメインへのアクセスの許可 **Type:** guide | **Category:** APIコール | **Section:** Developer Guides ドメインへのアクセスの許可 Box APIを使用する際に重要なのは、必要に応じてアプリケーションとユーザーが以下のドメインにアクセスできることです。 ファイルプレビュー ファイルプレビュー機能を有効にするために、アプリケーションは、Boxコンテンツ配信ネットワーク (CDN… # ドメインへのアクセスの許可 Box APIを使用する際に重要なのは、必要に応じてアプリケーションとユーザーが以下のドメインにアクセスできることです。 ## ファイルプレビュー ファイルプレビュー機能を有効にするために、アプリケーションは、Boxコンテンツ配信ネットワーク (CDN) からJavaScriptファイルを読み込むことが必要になる場合があります。このファイルは、以下のドメインから読み込まれます。 - `api.box.com` - `boxcdn.net` - `boxcloud.com` - `dl2.boxcloud.com`～`dl20.boxcloud.com` ## ファイルのダウンロード 以下のAPIドメインは、Box APIを介してファイルをダウンロードする目的で使用されます。 - `api.box.com` - ダウンロードするファイルを最初にリクエストする - `dl.boxcloud.com` - 認証済みユーザー用のファイルを実際にダウンロードする - `public.boxcloud.com` - 認証されていないユーザー用のファイルを実際にダウンロードする これらのドメインへのアクセス権限の確認は、ファイルをダウンロードするための最初のステップにすぎません。ファイルをダウンロードするには、ユーザーは適切なアクセス権限を持ち、必要に応じて完全に認証されている必要があります。 ## ファイルのアップロード 以下のAPIドメインは、Box APIを介してファイルをアップロードする目的で使用されます。 - `api.box.com` - ファイルのアップロードを開始する - `upload.app.box.com`と`upload.box.com` - Boxにファイルをアップロードする **Source:** [https://ja.developer.box.com/guides/api-calls/allowing-domain-access/](https://ja.developer.box.com/guides/api-calls/allowing-domain-access/) --- ### ドメインへのコラボレーションの許可 **Type:** guide | **Category:** コラボレーション | **Section:** Developer Guides ドメインへのコラボレーションの許可 一般にコラボレーションの作成を制限している企業は、企業で作成されている可能性のあるコラボレーションのリストにexample.comなどのドメインを追加できます。 このエンドポイントには、コラボレーションを許可するdomain… # ドメインへのコラボレーションの許可 一般にコラボレーションの作成を制限している企業は、企業で作成されている可能性のあるコラボレーションのリストに`example.com`などのドメインを追加できます。 この[エンドポイント](endpoint://post_collaboration_whitelist_entries)には、コラボレーションを許可する`domain`と、以下のように設定できる`direction`が必要です。 - `inbound`: 外部ユーザーが企業のコンテンツでコラボレーションできるかどうか。 - `outbound`: 企業の管理対象ユーザーが外部の企業で所有されているコンテンツでコラボレーションできるかどうか。 - `both`: 上記の両方。 新しく許可されたドメインを設定する場合はbothパラメータを指定します。 **Source:** [https://ja.developer.box.com/guides/collaborations/allowed-domains/create/](https://ja.developer.box.com/guides/collaborations/allowed-domains/create/) --- ### バージョン管理のエラー **Type:** guide | **Category:** APIコール | **Section:** Developer Guides バージョン管理のエラー Boxでは、特定のAPIエンドポイントに対してバージョン管理機能を提供しています。このバージョン管理システムにより、Boxがエンドポイントのバージョンを新しく導入した場合でも、既存のエンドポイントのバージョンに対してシームレスな機能が保証されます。 API… # バージョン管理のエラー Boxでは、特定のAPIエンドポイントに対してバージョン管理機能を提供しています。このバージョン管理システムにより、Boxがエンドポイントのバージョンを新しく導入した場合でも、既存のエンドポイントのバージョンに対してシームレスな機能が保証されます。 APIのバージョン管理により、Boxは、自社のプラットフォームを継続的に強化できると同時に、機能の更新や廃止のための信頼できる手段をサードパーティの開発者に提供することもできます。 APIの変更について常に最新情報を把握できるように、[変更ログ](page://changelog)を注視し、開発者コンソールの [**アプリ情報**] セクションで最新のメールアドレスを指定しておいてください。 ## エラーの例 バージョン管理されているAPIコールの使用時に、バージョン管理に関連したエラーが発生する場合があります。このリファレンスでは、エラーが表示される最も一般的なケースを挙げ、そのようなエラーの例を示します。 ## 正しくないbox-versionヘッダーを使用した呼び出し 正しくない`box-version`ヘッダーを使用してAPIを呼び出すと、APIは`HTTP error code 400 - Bad Request`エラーで応答し、レスポンスのメッセージ内にサポート対象のバージョンを示します。 レスポンスの`message`フィールドには、以下のステータスメッセージのいずれかが含まれます。 | 詳細 | メッセージ | | --- | --- | | box-version値が、サポートされていないAPIバージョンであるか、正しくない形式で送信されました。 | Invalid API version specified in 'box-version' header. | | バージョン管理されているエンドポイントのみが呼び出されたときに、リクエストヘッダーにbox-versionヘッダーが含まれていませんでした。 | Missing required box-version header. | | box-versionが空です。 | Invalid (empty) API version specified in 'box-version' header. | | box-versionに複数のバージョンが含まれていました。リクエストごとに指定できるバージョンの数は1つのみです。 | The 'box-version' header supports only one header value per request, do not use comas. | | サポートされていないAPIバージョンが既存のエンドポイントに使用されています。 | Unsupported API version specified in 'box-version' header. | `box-version`ヘッダーが正しくない場合のレスポンスの例: ``` { "type": "error", "status": 400, "code": "invalid_api_version", "help_url": "https://developer.box.com/reference/error-codes/invalid-api-version", "message": "Invalid API version specified in 'box-version' header. Supported API versions: [2024.0].", "request_id": "abcdef123456" } ``` ## URLでの正しくないAPIバージョンの呼び出し Boxのドキュメントでは、APIのURLが示されています。たとえば、署名リクエストのエンドポイントへのアクセスには`https://api.box.com/2.0/sign_requests/`を使用します。誤って`https://api.box.com/3.0/sign_requests/`のような正しくないバージョンを呼び出すと、レスポンスでは`HTTP error code 404 - Not Found`エラーが返されます。 ## 非推奨のAPIの呼び出し Boxで非推奨としてマークされたAPIバージョンを使用した場合、APIは通常どおり応答します。また、非推奨になった日付を示す`Deprecation`ヘッダーが追加されます。次に例を示します。 ``` Deprecation: date="Fri, 11 Nov 2026 23:59:59 GMT" Box-API-Deprecated-Reason: https://developer.box.com/reference/deprecated ``` APIレスポンスを監視して`Deprecation`ヘッダーが存在するかどうかを確認し、その結果に応じて新しいAPIバージョンへの移行を計画する必要があります。 ## 存在しないバージョンの呼び出し 公式サポートが終了した古いAPIバージョン (`2025.0`など) を使用しようとすると、レスポンスでは`HTTP error code 404 - Not Found`が返されます。詳細については、[URLでの正しくないAPIバージョンの呼び出し](#calling-an-incorrect-api-version-in-the-url)を参照してください。 **Source:** [https://ja.developer.box.com/guides/api-calls/permissions-and-errors/versioning-errors/](https://ja.developer.box.com/guides/api-calls/permissions-and-errors/versioning-errors/) --- ### パーツのアップロード **Type:** guide | **Category:** アップロード | **Section:** Developer Guides パーツのアップロード 大きいファイルをアップロードする際は、そのファイルを小さいパーツに分割し、パーツのアップロードAPI… # パーツのアップロード 大きいファイルをアップロードする際は、そのファイルを小さいパーツに分割し、パーツのアップロードAPIを使用してそれらのパーツをアップロードできます。 ## アップロードセッションの作成 最初に[アップロードセッションを作成](g://uploads/chunked/create-session)します。結果のオブジェクトにより、各パーツのサイズとアップロードするパーツの数が定義されます。 ``` { "id": "F971964745A5CD0C001BBE4E58196BFD", "type": "upload_session", "session_expires_at": "2012-12-12T10:53:43-08:00", "part_size": 1024, "total_parts": 1000, "num_parts_processed": 455, "session_endpoints": { "upload_part": "https://upload.box.com/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD", "commit": "https://upload.box.com/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD/commit", "abort": "https://upload.box.com/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD", "list_parts": "https://upload.box.com/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD/parts", "status": "https://upload.box.com/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD", "log_event": "https://upload.box.com/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD/log" } } ``` ## ファイルの分割 ファイルをアップロードするパーツに分割します。コマンドラインを使用する場合は、`split`コマンドを使用します。 ``` split -b <PART_SIZE> <FILE_NAME> <YOUR_PART_NAME> ``` 例: ``` split -b 8388608 video.mp3 videopart ``` これにより、ファイルが複数のファイルに分割されます。 ## SHAダイジェストの取得 `SHA`ダイジェストの値を取得するには、次のopenSSLコマンドを使用して、ファイルのパーツをエンコードします。 ``` openssl sha1 -binary <FILE_PART_NAME> | base64 ``` 例: ``` openssl sha1 -binary videoparta | base64 ``` その結果、Base64でエンコードされたメッセージがアップロードの検証に使用されます。 ## パーツのアップロード アップロードするパーツのデータをアップロードします。その際、パーツのバイト範囲と、コンテンツを適切にアップロードするための`SHA`ダイジェストを指定します。 ### コンテンツの範囲 各パーツのサイズは、作成したアップロードセッションで指定されているパーツサイズとまったく同じサイズである必要があります。ただし、ファイルの最後のパーツは小さくなる可能性があるため、例外となります。`Content-Range`パラメータの定義は、次のパターンに従います。 ``` -H "Content-Range: bytes <LOWER_BOUND>-<HIGHER_BOUND>/<TOTAL_SIZE>" ``` `Content-Range`の値を指定する際は、以下の点に注意してください。 - 各パーツのバイト範囲の下限は、パーツサイズの倍数にする必要があります。 - 上限は、パーツサイズの倍数から1を引いた値にする必要があります。 たとえば、パーツサイズが`8388608`の場合、最初の2つのパーツのコンテンツの範囲は次のようになります。 ``` -H "Content-Range: bytes 0-8388607/32127641" \ ## first part -H "Content-Range: bytes 8388608-16777215/32127641" \ ## second part ``` ## レスポンス 各アップロードの後、結果のレスポンスには、アップロードされたパーツの`ID`と`SHA`が含まれます。 ``` { "part_id": "6F2D3486", "offset": 16777216, "size": 3222784, "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc" } ``` すべてのパーツアップロードのすべてのJSONレスポンスは、[セッションのコミット](g://uploads/chunked/commit-session)に必要なため、保持してください。 ## 範囲の重複 パーツアップロードのリクエストがエラーコード`range_overlaps_existing_part`で失敗するのは、アプリケーションがファイルの分割に失敗し、すでにコンテンツがアップロードされている範囲にパーツをアップロードしようとしたことが原因です。アプリケーションでは、この最後のパーツがセッションに継続されなかったと想定する必要があります。 ## 並行アップロード パーツは並行してアップロードできますが、可能な限り順番にアップロードするようにしてください。バイトオフセットが小さいパーツは、バイトオフセットが大きいパーツより先にアップロードする必要があります。 推奨されるのは、バイトオフセット順に並べたパーツのキューから、3～5個のパーツを並行してアップロードする方法です。パーツのアップロードが失敗した場合は、さらにパーツをアップロードする前に、失敗したアップロードを再試行してください。 **Source:** [https://ja.developer.box.com/guides/uploads/chunked/upload-part/](https://ja.developer.box.com/guides/uploads/chunked/upload-part/) --- ### はじめに **Type:** guide | **Category:** はじめに | **Section:** Developer Guides はじめに Boxのドキュメントは、主に以下の5つのセクションに分かれています。 Box Platformについて: Platform全般の概要。 開発者向けガイド: 開発者向けポータル、APIの動作、Boxの機能の使用方法に関する詳細なドキュメント。 API… # はじめに Boxのドキュメントは、主に以下の5つのセクションに分かれています。 - **Box Platformについて**: Platform全般の概要。 - **開発者向けガイド**: 開発者向けポータル、APIの動作、Boxの機能の使用方法に関する詳細なドキュメント。 - **APIリファレンス**: リクエストとレスポンスの例を含む、APIエンドポイントとリソースのリスト。 - **SDKとツール**: Box公式SDKとツールのリスト。 - **サンプルコードカタログ**: 複数のコードリポジトリが一元管理されているリスト。 Box APIを使用する開発が初めての方は、まずは[Box Platformについて](page://platform)セクションのコンテンツを熟読してください。 このセクションの内容は以下のとおりです。 - [Box Platformの概念](page://platform/box-platform-101)を学ぶ - 自分の[ユースケース](page://platform/use-cases)がBoxに適しているかどうかを評価する - さまざまな[Boxユーザーの種類](page://platform/user-types)を理解する - 適切な[アプリケーションの種類](page://platform/application-types)を選択する - 利用可能な[認証方法](page://platform/authentication-methods)を確認し、自分のユースケースに最適なものを選択する - どこで[サポート](page://platform/support)を受けられるかを確認する - Boxでのアプリケーション開発に必要な[ツール](page://platform/tools)を確認する 基礎を学んだら、以下の手順に従うことをお勧めします。 1. 最初の[Boxアプリケーション](g://getting-started/first-application)を作成します。 2. アプリケーションを構成します。 3. [エンドポイント](page://reference)を調べて、[一般的な値](page://platform/appendix/locating-values)を使用してAPIコールを実行します。 4. アプリケーションを[公開](g://getting-started/publish-app)します。 不明な点がある場合は、Boxの[フォーラム](https://forum.box.com)を確認してください。 **Source:** [https://ja.developer.box.com/guides/getting-started/](https://ja.developer.box.com/guides/getting-started/) --- ### ファイル **Type:** guide | **Category:** ファイル | **Section:** Developer Guides ファイル ファイルは、フォルダとともに、Box APIの中核を成します。ファイルはアップロードおよびダウンロードが可能で、コンテンツに関する重要なメタデータ情報を保持できます。 # ファイル ファイルは、[フォルダ](g://folders)とともに、Box APIの中核を成します。ファイルは[アップロード](g://uploads)および[ダウンロード](g://downloads)が可能で、コンテンツに関する重要なメタデータ情報を保持できます。 **Source:** [https://ja.developer.box.com/guides/files/](https://ja.developer.box.com/guides/files/) --- ### ファイルからメタデータを抽出する (構造化) **Type:** guide | **Category:** Box AI | **Section:** Developer Guides ファイルからメタデータを抽出する (構造化) Box AI APIを使用すると、指定したファイルからメタデータを抽出し、結果をキー/値ペアの形式で取得することができます。入力には、fields… # ファイルからメタデータを抽出する (構造化) Box AI APIを使用すると、指定したファイルからメタデータを抽出し、結果をキー/値ペアの形式で取得することができます。入力には、`fields`パラメータを使用して構造を作成するか、すでに定義済みのメタデータテンプレートを使用できます。テンプレートの作成の詳細については、[メタデータテンプレートのカスタマイズ](https://support.box.com/hc/en-us/articles/360044194033-Customizing-Metadata-Templates)を参照するか、[メタデータテンプレートAPI](g://metadata/templates/create)を使用してください。 ## 開始する前に Platformアプリを作成して認証するには、[Box AIの使い方](g://box-ai/ai-tutorials/prerequisites)に記載されている手順に従っていることを確認してください。 ## リクエストの送信 リクエストを送信するには、`POST /2.0/ai/extract_structured`エンドポイントを使用します。 ### パラメータ コールを実行するには、以下のパラメータを渡す必要があります。必須のパラメータは**太字**で示されています。 `items`配列に含めることができる要素は1つだけです。 | パラメータ | 説明 | 例 | | --- | --- | --- | | metadata_template | 抽出するフィールドを含むメタデータテンプレート。リクエストを機能させるには、metadata_templateまたはfieldsを指定する必要がありますが、両方を指定することはできません。 | | | metadata_template.type | メタデータテンプレートのタイプ。 | metadata_template | | metadata_template.scope | メタデータテンプレートのスコープ。globalまたはenterpriseのいずれかになります。globalテンプレートは、任意のBox Enterpriseで利用できますが、enterpriseテンプレートは特定のEnterpriseに関連付けられます。 | metadata_template | | metadata_template.template_key | メタデータテンプレートの名前。 | invoice | | items.id | ドキュメントのBoxファイルID。IDは、拡張子が付いている実際のファイルを参照する必要があります。 | 1233039227512 | | items.type | 指定した入力データのタイプ。 | file | | items.content | 項目のコンテンツ (多くの場合はテキストレプリゼンテーション)。 | This article is about Box AI. | | fields.type | フィールドのタイプ。これには、string、float、date、enum、multiSelectが含まれますが、これらに限定されるものではありません。 | string | | fields.description | フィールドの説明。 | The person's name. | | fields.displayName | フィールドの表示名。 | Name | | fields.key | フィールドの一意の識別子。 | name | | fields.options | このフィールドのオプションのリスト。ほとんどの場合、enumおよびmultiSelectフィールドタイプと組み合わせて使用します。 | [{"key":"First Name"},{"key":"Last Name"}] | | fields.options.key | フィールドの一意の識別子。 | First Name | | fields.prompt | キー (識別子) に関する追加のコンテキスト。キーの確認方法や形式を含めることができます。 | Name is the first and last name from the email address | | ai_agent | デフォルトのエージェント構成を上書きするために使用されるAIエージェント。このパラメータを使用すると、たとえば、modelパラメータを使用してデフォルトのLLMをカスタムのLLMに置き換えたり、よりカスタマイズされたユーザーエクスペリエンスを実現できるようにベースとなるpromptを微調整したり、temperatureなどのLLMパラメータを変更して結果の創造性を調整したりすることができます。ai_agentパラメータを使用する前に、GET 2.0/ai_agent_defaultリクエストを使用してデフォルト構成を取得できます。具体的なユースケースについては、AIモデルの上書きに関するチュートリアルを参照してください。 | | ## ユースケース この例では、サンプル請求書から構造化された形でメタデータを抽出する方法を示します。ベンダー名、請求書番号などの詳細情報を抽出する必要があるとします。 ### リクエストの作成 Box AIから応答を取得するには、以下のパラメータを使用して、`POST /2.0/ai/extract_structured`エンドポイントを呼び出します。 - `items.type`および`items.id`: データの抽出元となるファイルを指定します。 - `fields`: 指定したファイルから抽出するデータを指定します。 - `metadata_template`: 既存のメタデータテンプレートを指定します。 `fields`と`metadata_template`のどちらかを使用して、構造を指定できます。両方を使用することはできません。 ### fieldsパラメータの使用 `fields`パラメータを使用すると、抽出するデータを指定できます。各`fields`オブジェクトにはパラメータのサブセットがあり、それを使用して、検索対象のデータに関する情報を追加できます。たとえば、フィールドのタイプや説明、さらには追加のコンテキストを含めたプロンプトを追加することができます。 ``` curl --location 'https://api.box.com/2.0/ai/extract_structured' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer <ACCESS_TOKEN>'' \ --data '{ "items": [ { "id": "1517628697289", "type": "file" } ], "fields": [ { "key": "document_type", "type": "enum", "prompt": "what type of document is this?", "options": [ { "key": "Invoice" }, { "key": "Purchase Order" }, { "key": "Unknown" } ] }, { "key": "document_date", "type": "date" }, { "key": "vendor", "description": "The name of the entity.", "prompt": "Which vendor is sending this document.", "type": "string" }, { "key": "document_total", "type": "float" } ] }' ``` 応答には、以下のように、指定したフィールドとその値が示されます。 ``` { "document_date": "2024-02-13", "vendor": "Quasar Innovations", "document_total": $1050, "document_type": "Purchase Order" } ``` ### メタデータテンプレートの使用 メタデータテンプレートを使用する場合は、その`template_key`、`type`、`scope`を指定します。 ``` curl --location 'https://api.box.com/2.0/ai/extract_structured' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer <ACCESS_TOKEN>' \ --data '{ "items": [ { "id": "1517628697289", "type": "file" } ], "metadata_template": { "template_key": "rbInvoicePO", "type": "metadata_template", "scope": "enterprise_1134207681" } }' ``` 応答には、以下のように、メタデータテンプレートに含まれているフィールドとその値が示されます。 ``` { "documentDate": "February 13, 2024", "total": "$1050", "documentType": "Purchase Order", "vendor": "Quasar Innovations", "purchaseOrderNumber": "003" } ``` **Source:** [https://ja.developer.box.com/guides/box-ai/ai-tutorials/extract-metadata-structured/](https://ja.developer.box.com/guides/box-ai/ai-tutorials/extract-metadata-structured/) --- ### ファイルからメタデータを抽出する (自由形式) **Type:** guide | **Category:** Box AI | **Section:** Developer Guides ファイルからメタデータを抽出する (自由形式) Box AI APIを使用すると、ドキュメントまたは画像に対してクエリを実行し、指定したプロンプトに基づいてメタデータを抽出できます。自由形式とは、JSONやXML… # ファイルからメタデータを抽出する (自由形式) Box AI APIを使用すると、ドキュメントまたは画像に対してクエリを実行し、指定したプロンプトに基づいてメタデータを抽出できます。**自由形式**とは、JSONやXMLなどの形式の文字列化バージョン、またはプレーンテキストをプロンプトに含めることができるという意味です。 ## 開始する前に Platformアプリを作成して認証するには、[Box AIの使い方](g://box-ai/ai-tutorials/prerequisites)に記載されている手順に従っていることを確認してください。 ## リクエストの送信 リクエストを送信するには、`POST /2.0/ai/extract`エンドポイントを使用します。 ### パラメータ コールを実行するには、以下のパラメータを渡す必要があります。必須のパラメータは**太字**で示されています。 `items`配列に含めることができる要素は1つだけです。 | パラメータ | 説明 | 例 | | --- | --- | --- | | prompt | Box AIに対するテキストの生成またはリファインのリクエスト。プロンプトの長さは10000文字以内にする必要があります。 | 週1回の営業会議のアジェンダを作成してください。 | | items.id | ドキュメントのBoxファイルID。IDは、拡張子が付いている実際のファイルを参照する必要があります。 | 1233039227512 | | items.type | 指定した入力データのタイプ。 | file | | items.content | 項目のコンテンツ (多くの場合はテキストレプリゼンテーション)。 | This article is about Box AI. | | ai_agent | デフォルトのエージェント構成を上書きするために使用されるAIエージェント。このパラメータを使用すると、たとえば、modelパラメータを使用してデフォルトのLLMをカスタムのLLMに置き換えたり、よりカスタマイズされたユーザーエクスペリエンスを実現できるようにベースとなるpromptを微調整したり、temperatureなどのLLMパラメータを変更して結果の創造性を調整したりすることができます。ai_agentパラメータを使用する前に、GET 2.0/ai_agent_defaultリクエストを使用してデフォルト構成を取得できます。具体的なユースケースについては、AIモデルの上書きに関するチュートリアルを参照してください。 | | ## ユースケース この例では、サンプル請求書からメタデータを抽出する方法を示します。 ### リクエストの作成 Box AIから応答を取得するには、以下のパラメータを使用して、`POST /2.0/ai/extract`エンドポイントを呼び出します。 - クエリか、抽出するフィールドの構造化リストまたは非構造化リストを指定できる`prompt`。 - データの抽出元となるファイルの`type`および`id`。 ### プロンプトの作成 ユースケースや詳細度に応じて、さまざまなプロンプトを作成できます。 #### プレーンテキストを使用する このエンドポイントでは自由形式のプロンプトが許可されているため、プレーンテキストを使用して情報を取得できます。 ``` curl --location 'https://api.box.com/2.0/ai/extract' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer <ACCESS_TOKEN>' \ --data '{ "prompt": "find the document type (invoice or po), vendor, total, and po number", "items": [ { "type": "file", "id": "1443721424754" } ] }' ``` その場合、レスポンスは、テキストに含まれているキーワードに基づいて作成されます。 ``` { "answer": "{\"Document Type\": \"Invoice\", \"Vendor\": \"Quasar Innovations\", \"Total\": \"$1,050\", \"PO Number\": \"003\"}", "created_at": "2024-05-31T10:30:51.223-07:00", "completion_reason": "done" } ``` #### 特定の用語を使用する 文全体を書かなくても、請求書に含まれることが予想される用語でプロンプトを構成できます。 ``` curl --location 'https://api.box.com/2.0/ai/extract' \ --header 'Content-Type: application/json' \ --header 'Authorization: <ACCESS_TOKEN>' \ --data '{ "prompt": "{\"vendor\",\"total\",\"doctype\",\"date\",\"PO\"}", "items": [ { "type": "file", "id": "1443721424754" } ] }' ``` このアプローチを使用すると、以下のように、リクエストで指定した用語のリストとその値が返されます。 ``` { "answer": "{\"vendor\": \"Quasar Innovations\", \"total\": \"$1,050\", \"doctype\": \"Invoice\", \"PO\": \"003\"}", "created_at": "2024-05-31T10:28:51.906-07:00", "completion_reason": "done" } ``` #### キー/値ペアを使用する プロンプトには、Box AIがメタデータの構造を認識するのに役立つキー/値ペアのリストを指定することができます。このアプローチでは、`fields`配列内にキー/値ペアを列挙する必要があります。 ``` curl --location 'https://api.box.com/2.0/ai/extract' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer <ACCESS_TOKEN>' \ --data '{ "prompt": "{\"fields\": [{\"key\":\"vendor\",\"displayName\":\"Vendor\",\"type\":\"string\",\"description\":\ "Vendorname\"},{\"key\":\"documentType\",\"displayName\":\"Type\",\"type\":\"string\",\"description\":\"\"}]}", "items": [ { "type": "file", "id": "1443721424754" } ] }' ``` レスポンスには、以下のように、ファイル内に存在する`fields`とその値が含まれます。 ``` { "answer": "{\"vendor\": \"Quasar Innovations\", \"documentType\": \"Invoice\"}", "created_at": "2024-05-31T10:15:38.17-07:00", "completion_reason": "done" } ``` **Source:** [https://ja.developer.box.com/guides/box-ai/ai-tutorials/extract-metadata/](https://ja.developer.box.com/guides/box-ai/ai-tutorials/extract-metadata/) --- ### ファイルとフォルダの転送 **Type:** guide | **Category:** ユーザー | **Section:** Developer Guides ファイルとフォルダの転送 ユーザーアカウントのプロビジョニング解除における一般的な要件の1つが、ユーザーアカウント内に保存されているすべてのファイルとフォルダを別のユーザーアカウント、またはサービスアカウントなどの長期保存用の場所に転送することです。 Box… # ファイルとフォルダの転送 ユーザーアカウントのプロビジョニング解除における一般的な要件の1つが、ユーザーアカウント内に保存されているすべてのファイルとフォルダを別のユーザーアカウント、またはサービスアカウントなどの長期保存用の場所に転送することです。 Box内でこれを実行するのに使用される一般的な方法は以下の2つです。 - すべてのコンテンツをあるユーザーから別のユーザーに直接移動する、[所有フォルダの移動](e://put_users_id_folders_0)APIを使用する。 - コラボレーション転送の方法を使用して、一度に1つのファイルまたはフォルダの所有権を、あるユーザーから別のユーザーに変更する。 転送中は、ユーザーが所有するファイルにアクセスできなくなります。また、移動中もユーザーが所有する共有コンテンツにアクセスできない可能性があります。 コンテンツの量によっては、この操作にかなりの時間がかかる場合があります。 ## 所有フォルダの移動APIの使用 [所有フォルダの移動エンドポイント](e://put_users_id_folders_0)は、あるユーザーが所有するコンテンツ全体を別のユーザーに移動することを目的に設計されています。 所有フォルダの移動APIは、同期プロセスとして実行されるため、ソースユーザーのフォルダ全体に多数の項目がある場合、レスポンスが遅くなる可能性があります。 転送エンドポイントを呼び出すには、転送元のユーザーIDと転送先のユーザーIDを指定します。 ## コラボレーション転送の使用 コラボレーション転送は、[コラボレーションエンドポイント](e://post_collaborations)を使用して、単一のファイルまたはフォルダの所有権をあるユーザーから別のユーザーに即座に変更するプロセスです。 この方法では、単一のファイルまたはフォルダの所有権を即時に転送します。ただし、この方法でルート (すべてのファイルおよびフォルダ) を別のユーザーに転送することは**できません**。 `transfer_from_user`から`transfer_to_user`への転送の一般的なプロセスは以下の手順に従います。 ### 転送先ユーザーを共同所有者として追加 最初の手順は、転送するファイルまたはフォルダへの`co-owner`アクセス権限を持つコラボレータとして、`transfer_to_user`アカウントを追加することです。 `transfer_from_user`アカウントとして呼び出しを行い、[コラボレーションを追加](e://post_collaborations)エンドポイントを使用して`transfer_to_user`を共同所有者として追加します。 ### 転送先ユーザーとしてコラボレーションIDを取得 次の手順では、コラボレーション情報を取得するリクエストを`transfer_to_user`アカウントとして実行します。返されるコラボレーションオブジェクトには、最後の手順で使用するコラボレーションIDが含まれます。 `transfer_to_user`アカウントとして呼び出しを実行し、[コラボレーションを取得エンドポイント](e://get_collaborations_id)を使用して、転送するファイルまたはフォルダのIDのコラボレーションを取得します。コラボレーションIDをキャプチャします。 ### 転送元ユーザーを所有者として削除 最後の手順は、ファイルまたはフォルダの所有者として`transfer_from_user`アカウントを削除することです。これは、[コラボレーションを削除エンドポイント](e://delete_collaborations_id)を使用して行います。 `transfer_to_user`アカウントとして呼び出しを実行し、ファイルまたはフォルダのコラボレータとして`transfer_from_user`を削除します。 これにより、ファイルまたはフォルダの所有者は`transfer_to_user`アカウントになり、`transfer_from_user`アカウントはアクセスできなくなります。 **Source:** [https://ja.developer.box.com/guides/users/deprovision/transfer-folders/](https://ja.developer.box.com/guides/users/deprovision/transfer-folders/) --- ### ファイルのアップロード **Type:** guide | **Category:** Boxの埋め込み | **Section:** Developer Guides ファイルのアップロード ファイルのプレビューの埋め込みリンクを生成するには、そのファイルをBoxにアップロードする必要があります。ほとんどのファイルタイプでは、アップロード時に自動的に変換が開始されます。ただし、動画と3D… # ファイルのアップロード ファイルのプレビューの埋め込みリンクを生成するには、そのファイルをBoxにアップロードする必要があります。ほとんどのファイルタイプでは、アップロード時に自動的に変換が開始されます。ただし、動画と3Dファイルについては、最初のプレビュー時に変換が開始されます。変換を開始するために、ユーザーが明示的な操作を行う必要はありません。いずれの場合も、変換は1ファイルにつき1回だけ開始され、生成されたアセットは元のファイルがBoxに保存されている間は使用できます。 ## ファイルのアップロード [Box SDK](pages://sdks-and-tools)を使用してファイルをアップロードするか、またはAPIを使用して直接ファイルをアップロードするには、[アプリケーションの設定](guide://embed/box-view/setup)中に生成されたクライアントIDとアプリトークンを使用してアプリケーションを認証する必要があります。 アプリケーションの認証 認証済みクライアントが作成されたら、そのクライアントを使用して、変換するファイルをアプリトークンアプリケーションに直接アップロードできます。 Boxへのファイルのアップロード **Source:** [https://ja.developer.box.com/guides/embed/box-view/upload-file/](https://ja.developer.box.com/guides/embed/box-view/upload-file/) --- ### ファイルのすべてのタスクのリストの取得 **Type:** guide | **Category:** タスク | **Section:** Developer Guides ファイルのすべてのタスクのリストの取得 特定のファイルのすべてのタスクのリストを取得するには、ファイルのidを指定してGET /files/:id/tasksを呼び出します。 # ファイルのすべてのタスクのリストの取得 特定のファイルのすべてのタスクのリストを取得するには、ファイルの`id`を指定して[`GET /files/:id/tasks`](e://get_files_id_tasks)を呼び出します。 **Source:** [https://ja.developer.box.com/guides/tasks/for-file/](https://ja.developer.box.com/guides/tasks/for-file/) --- ### ファイルのすべてのレプリゼンテーションのリストの取得 **Type:** guide | **Category:** レプリゼンテーション | **Section:** Developer Guides ファイルのすべてのレプリゼンテーションのリストの取得 ファイルに使用できるレプリゼンテーションを確認するには、representationsフィールドのリクエスト中にGET /files/:id… # ファイルのすべてのレプリゼンテーションのリストの取得 ファイルに使用できるレプリゼンテーションを確認するには、[`representations`](resource://file#param-representations)フィールドのリクエスト中に[`GET /files/:id`](endpoint://get-files-id)エンドポイントを呼び出します。 ``` curl https://api.box.com/2.0/files/123?fields=representations \ -H "authorization: Bearer ACCESS_TOKEN" ``` このレスポンスには、次の形式でレプリゼンテーションのリストが含まれます。 ``` ... { "info": { "url": "https://api.box.com/2.0/internal_files/123/versions/345/representations/jpg_thumb_32x32" }, "properties": { "dimensions": "32x32", "paged": "false", "thumb": "true" }, "representation": "jpg" } ... ``` ## レスポンスのフィールド どのレプリゼンテーションにも一連のプロパティとレプリゼンテーションのタイプが含まれます。 `dimensions`フィールド (省略可) は、ファイルのサイズをピクセル単位の幅と高さで表します。 `paged`フィールド (省略可) は、このレプリゼンテーションがページ割りされたドキュメントかどうかを指定します。画像やPDFによっては、ページ割りされたドキュメントになることがよくあります。 `thumb`フィールド (省略可) は、このレプリゼンテーションがファイルのサムネイルとして適しているかどうかを指定します。 **Source:** [https://ja.developer.box.com/guides/representations/list-all-representations/](https://ja.developer.box.com/guides/representations/list-all-representations/) --- ### ファイルのダウンロード **Type:** guide | **Category:** ダウンロード | **Section:** Developer Guides ファイルのダウンロード ファイルをダウンロードするには、取得するコンテンツが含まれるファイルのIDをGET /files/:id/contentに渡します。 ダウンロードURL SDKを使用しない場合、このAPIコールでは、HTTP 302 Found… # ファイルのダウンロード ファイルをダウンロードするには、取得するコンテンツが含まれるファイルのIDを[`GET /files/:id/content`](e://get_files_id_content)に渡します。 ## ダウンロードURL SDKを使用しない場合、このAPIコールでは、`HTTP 302 Found`ステータスコードとともに、次のようなダウンロードURLへのリンクを含む`location`ヘッダーが返されます。 ``` https://dl.boxcloud.com/d/1/[long-random-string]/download ``` cURLで`-L`フラグを使用することで、自動的にこのリダイレクトに従うことができます。 SDKでは、結果として、バイナリデータがダウンロードされます。APIでは、ダウンロードURLが`location`ヘッダーを介して返されます。 また、SDKを介して[ダウンロードURLを取得](g://downloads/get-url)することも可能です。 ## ダウンロードURLの有効期限 このダウンロードURLは、ファイルのダウンロードを許可するためにユーザーのブラウザに渡すことができますが、このURLが期限切れになると、その後でダウンロードするには再度リクエストする必要があります。 ## ファイルの準備ができていない ファイルをダウンロードする準備がまだできていない場合は、クライアントがファイルをダウンロードできるようになるまでの秒数を示す`retry-after`ヘッダーが返されます。 このレスポンスは、ダウンロードリクエストの直前にファイルがアップロードされた場合に発生することがあります。 **Source:** [https://ja.developer.box.com/guides/downloads/file/](https://ja.developer.box.com/guides/downloads/file/) --- ### ファイルのプレビューの作成 **Type:** guide | **Category:** Boxの埋め込み | **Section:** Developer Guides ファイルのプレビューの作成 ファイルは、アプリトークンアプリケーションにアップロードされると、以下の2つの方法でプレビューすることができます。 直接埋め込み: カスタムの埋め込みリンクを使用した標準のHTML `コンポーネント。 - カスタマイズされたプレビューアー: Box [UI Elements](g://embed/ui-elements)を使用して全面的にカスタマイズされたプレビューウィジェット。 ## 直接埋め込み (iframe) 直接埋め込みリンクを使用すると、アプリケーションでのプレビューをカスタマイズするためのオプションが制限されます。このメソッドは軽量であるため、このAPIには、ドキュメントでのスクロール、動画のインタラクティブな再生や一時停止、画像の回転など、クライアント側の処理に対応するオプションはありません。 Box Viewの直接`<iframe>`埋め込みを作成するには、以下の2つの手順を実行します。 1. ファイル用に埋め込みURLを生成する 2. 生成した埋め込みURLを`<iframe>`に追加する ### ファイル用に埋め込みURLを生成する アプリトークンアプリケーションにアップロードされたファイルの公開ファイルプレビューURLを作成するには、直接のSDKメソッドを使用するか、APIに直接リクエストを発行します。 埋め込みURLをAPIから直接生成する場合は、[ファイル情報の取得エンドポイント](e://get_files_id)を使用して、`fields`パラメータを介して`expiring_embed_link`をリクエストします。 ``` curl https://api.box.com/2.0/files/FILE_ID?fields=expiring_embed_link \ -H "authorization: Bearer [APP_TOKEN]" ``` ``` String fileId = "12345678"; Uri embedUri = await client.FilesManager.GetPreviewLinkAsync(id: fileId); ``` ``` String fileID = "12345678"; BoxFile file = new BoxFile(api, fileID); URL embedLink = file.getPreviewLink(); ``` ``` file_id = '12345678' embed_url = client.file(file_id).get_embed_url() ``` ``` const fileId = '12345678'; client.files.getEmbedLink(fileId).then(embedURL => { // ... }); ``` レスポンスオブジェクト内では、公開埋め込みURLが次のようになります。 ``` https://app.box.com/preview/expiring_embed/gvoct6FE!YT_X1LauQ8ulDTad96hTl9xLCRYJ 5iU6O61KxiduxFIgX9HSWMcCWf7zju1XkEsf6-Ul2qtKXeaFeKPT4SysQJQdxrc144KgTIBuoI3bWMf4 cfhp3jdLYrK5hnr6KMq5H6r-AW31AcFtDJi1lnT0M4b3bvvZUaE2RRJGGINMauvS6MAT2luae5PvbFSx Ctqqx6XlN6QrqbhfJc0UeJF9qwMv3-O8q5fWn0qr8OTY4lkeYidtTs3Ux... ``` セキュリティ上の理由により、生成された埋め込みリンクは1分後に期限切れになるため、生成されたらすぐにアプリに埋め込む必要があります。 ### 生成した埋め込みURLを<iframe>に追加する アプリケーションのHTML内で、`iframe`要素を作成し、`src`属性を生成された埋め込みURLに設定します。 ``` <iframe src="https://app.box.com/preview/expiring_embed/gvoct6FE!ixgtCKQAziW 9tHPm-jueq4cmS4GnL9RTJRcVEsK_3W8xcxtVo_v6gKpoXY45odgG1QrcjBVYZMrriUyGvcoSM SX8s-smpaFFYQik0R-PCKFtwvbv0lonid6ZfYNbuNFl2j9hOIqBccvHrdVor7i6WvOm6zELzTY 4EWshcyYYBhDbJmYMrq61RtU_kvBe5P..."></iframe> ``` ## カスタマイズされたプレビューアー (UI Element) 高度なプレビューのカスタマイズ機能やイベント処理機能を活用するには、Box [UI Preview Element](guide://embed/ui-elements/preview)を使用します。 このプレビューElementを設定するには、まず、必須コンポーネントをインストールします。 Box Elementsとプレビューのインストール 新しいプレビューアーを表示するためのJavaScriptコードを追加する際、基本的なコードは次のようになります。 ``` var preview = new Box.Preview(); preview.show("FILE_ID", "ACCESS_TOKEN", { container: ".preview-container", showDownload: true }); ``` コードサンプル内のプレースホルダを以下の内容に置き換えてください。 - `FILE_ID`: アプリトークンアプリケーションにアップロードされたファイルのID。ファイルのアップロード時に返されるオブジェクトから取得できます。 - `ACCESS_TOKEN`: アプリケーションの構成時に設定されたプライマリアクセストークン、またはそのトークンのダウンスコープされたバージョン。 プライマリアクセストークンの高度な権限により、JavaScriptコードでは、ダウンスコープされたバージョンのトークンを使用することを強くお勧めします。[ダウンスコープのベストプラクティス](guide://embed/box-view/best-practices#use-downscoped-tokens)を参照してください。 **Source:** [https://ja.developer.box.com/guides/embed/box-view/create-preview/](https://ja.developer.box.com/guides/embed/box-view/create-preview/) --- ### ファイルのメタデータの更新 **Type:** quick-start | **Category:** メタデータ | **Section:** Developer Guides … # ファイルのメタデータの更新 メタデータをファイルまたはフォルダに適用したら、多くの場合は、後日メタデータの更新が必要になります。 メタデータインスタンスを更新するには、元のデータに一連の操作を適用します。これらの操作はアトミックに実行されるため、変更はすべて適用されるか、まったく適用されないかのいずれかになります。 インスタンスの更新の詳細を確認する この場合、顧客の`name`を`Box, Inc`から`Box`に変更するとします。適用できる操作は2つあり、まず、変更前に名前の値がまだ`Box, Inc`であることを確認し、次に変更を行います。 ``` curl -X PUT https://api.box.com/2.0/files/12345/metadata/enterprise/customerInfo \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -H "content-type: application/json-patch+json" \ -d '[ { "op": "test", "path": "/name", "value": "Box, Inc" }, { "op": "replace", "path": "/name", "value": "Box" } ]' ``` ``` var updates = new List<BoxMetadataUpdate>() { new BoxMetadataUpdate() { Op = MetadataUpdateOp.test, Path = "/name", Value = "Box, Inc" }, new BoxMetadataUpdate() { Op = MetadataUpdateOp.replace, Path = "/name", Value = "Box" } }; Dictionary<string, object> updatedMetadata = await client.MetadataManager .UpdateFileMetadataAsync("12345", updates, "enterprise", "customerInfo"); ``` ``` BoxFile file = new BoxFile(api, "12345"); file.updateMetadata( file.createMetadata( "customerInfo", "enterprise", new Metadata().test("/name", "Box, Inc").replace("/name", "Box") ); ``` ``` file = client.file(file_id='12345') metadata = file.metadata(scope='enterprise', template='customerInfo') updates = metadata.start_update() updates.test('/name', 'Box, Inc') updates.replace('/name', 'Box') file.update(updates) ``` ``` var updates = [ { op: 'test', path: '/name', value: 'Box, Inc' }, { op: 'replace', path: '/name', value: 'Box' } ]; client.files.updateMetadata( '12345', client.metadata.scopes.ENTERPRISE, "customerInfo", updates ).then(metadata => { //... }); ``` すべての操作の詳細を確認する このAPIにより、更新されたメタデータインスタンスが返されます。 ``` { "name": "Box", "industry": "Technology", "tav": 1000000, "$id": "01234500-12f1-1234-aa12-b1d234cb567e", "$parent": "folder_12345,", "$scope": "enterprise_34567", "$template": "customerInfo", "$type": "customerInfo-6bcba49f-ca6d-4d2a-a758-57fe6edf44d0", "$typeVersion": 2, "$version": 1, "$canEdit": true } ``` ファイルのメタデータを更新しました **Source:** [https://ja.developer.box.com/guides/metadata/quick-start/update-instance/](https://ja.developer.box.com/guides/metadata/quick-start/update-instance/) --- ### ファイルの復元 **Type:** guide | **Category:** ごみ箱 | **Section:** Developer Guides ファイルの復元 ごみ箱に移動されたが削除されていないファイルを復元するには、/files/:file_idエンドポイントにPOSTリクエストを送信します。これにより、ファイルがまだ使用可能であれば元のフォルダに戻されます。または、オプションとしてparent… # ファイルの復元 ごみ箱に移動されたが削除されていないファイルを復元するには、`/files/:file_id`エンドポイントに`POST`リクエストを送信します。これにより、ファイルがまだ使用可能であれば元のフォルダに戻されます。または、オプションとして`parent`フォルダを指定することもできます。 **Source:** [https://ja.developer.box.com/guides/trash/restore-file/](https://ja.developer.box.com/guides/trash/restore-file/) --- ### ファイルバージョンのアップロード **Type:** guide | **Category:** アップロード | **Section:** Developer Guides ファイルバージョンのアップロード 直接アップロードによってBoxにファイルの新しいバージョンをアップロードするには、ファイルのコンテンツ、目的のファイル名、フォルダIDを使用して、POST /files/:id/content APIにAPI… # ファイルバージョンのアップロード 直接アップロードによってBoxにファイルの新しいバージョンをアップロードするには、ファイルのコンテンツ、目的のファイル名、フォルダIDを使用して、[`POST /files/:id/content`](e://post_files_id_content) APIにAPIコールを実行します。 # 事前チェック アップロードしたファイルが拒否されることによる時間や帯域幅の無駄を防ぐため、ファイルをアップロードする前に[事前チェック](g://uploads/check)を実行することをお勧めします。 ## リクエスト形式 このAPIのリクエスト本文には、`multipart/form-data`のコンテンツタイプが使用されます。これを使用して、ファイル属性とファイルの実際のコンテンツの2つの部分を送信します。 最初の部分は`attributes`と呼ばれ、ファイル名や親フォルダの`id`など、ファイルに関する情報を含むJSONオブジェクトが含まれています。 以下の例では、ユーザーのルートフォルダに`test.txt`をアップロードしています。 ``` POST /api/2.0/files/123/content HTTP/1.1 Host: upload.box.com Authorization: Bearer [ACCESS_TOKEN] content-length: 343 content-type: multipart/form-data; boundary=------------------------9fd09388d840fef1 --------------------------9fd09388d840fef1 content-disposition: form-data; name="attributes" {"name":"test.txt", "parent":{"id":"0"}} --------------------------9fd09388d840fef1 content-disposition: form-data; name="file"; filename="test.txt" content-type: text/plain Test file text. --------------------------9fd09388d840fef1-- ``` マルチパート本文の`attributes` JSON部分は、マルチパートフォームデータの`file` 部分の前に置く必要があります。この順番を間違えると、APIがHTTP `400`ステータスコードとエラーコード`metadata_after_file_contents`を返します。 ## オプション ファイルのアップロード時に使用できるすべてのパラメータの詳細については、[このAPIコールに関するリファレンスドキュメント](e://post_files_id_content)を参照してください。パラメータには、設定することで転送中のファイルの破損を防ぐ`content-md5`や、アップロード時間とは異なる時間をファイル作成時間として明示的に指定できる機能が含まれます。 ファイルバージョンの場合、追加の[`if-match`ヘッダー](g://api-calls/ensure-consistency)を渡すことで、アプリケーションが最後にコンテンツを検査した後で更新されたファイルが上書きされるのを防ぐことができます。 ## 制約事項 直接アップロードできるファイルサイズの上限は50 MBです。ファイルがこれより大きい場合は、[分割アップロードAPI](g://uploads/chunked)を使用してください。 アップロードの上限は、認証済みユーザーのアカウントの種類によって決まります。詳細については、このトピックに関する[Boxコミュニティの記事](https://support.box.com/hc/ja/articles/360043697314-Box%E3%81%AB%E3%82%A2%E3%83%83%E3%83%97%E3%83%AD%E3%83%BC%E3%83%89%E3%81%A7%E3%81%8D%E3%82%8B%E6%9C%80%E5%A4%A7%E3%83%95%E3%82%A1%E3%82%A4%E3%83%AB%E3%82%B5%E3%82%A4%E3%82%BA)を参照してください。 **Source:** [https://ja.developer.box.com/guides/uploads/direct/file-version/](https://ja.developer.box.com/guides/uploads/direct/file-version/) --- ### ファイルバージョンのダウンロード **Type:** guide | **Category:** ダウンロード | **Section:** Developer Guides ファイルバージョンのダウンロード 特定のファイルバージョンをダウンロードするには、取得するコンテンツが含まれるファイルのIDとそのファイルのバージョンIDをGET /files/:id/contentに渡します。 ダウンロードURL SDKを使用しない場合、このAPI… # ファイルバージョンのダウンロード 特定のファイルバージョンをダウンロードするには、取得するコンテンツが含まれるファイルのIDとそのファイルのバージョンIDを[`GET /files/:id/content`](e://get_files_id_content)に渡します。 ## ダウンロードURL SDKを使用しない場合、このAPIコールでは、`HTTP 302 Found`ステータスコードとともに、次のようなダウンロードURLへのリンクを含む`location`ヘッダーが返されます。 ``` https://dl.boxcloud.com/d/1/[long-random-string]/download ``` cURLで`-L`フラグを使用することで、自動的にこのリダイレクトに従うことができます。 SDKでは、結果として、バイナリデータがダウンロードされます。APIでは、ダウンロードURLが`location`ヘッダーを介して返されます。 また、SDKを介して[ダウンロードURLを取得](g://downloads/get-url)することも可能です。 ## ダウンロードURLの有効期限 このダウンロードURLは、ファイルのダウンロードを許可するためにユーザーのブラウザに渡すことができますが、このURLが期限切れになると、その後でダウンロードするには再度リクエストする必要があります。 ## ファイルの準備ができていない ファイルをダウンロードする準備がまだできていない場合は、クライアントがファイルをダウンロードできるようになるまでの秒数を示す`retry-after`ヘッダーが返されます。 このレスポンスは、ダウンロードリクエストの直前にファイルがアップロードされた場合に発生することがあります。 **Source:** [https://ja.developer.box.com/guides/downloads/file-version/](https://ja.developer.box.com/guides/downloads/file-version/) --- ### ファイルへのメタデータテンプレートの追加 **Type:** quick-start | **Category:** 検索 | **Section:** Developer Guides ファイルへのメタデータテンプレートの追加 メタデータテンプレートは、手順4で結果が得られるように1つ以上のファイルに適用する必要があります。ファイルにメタデータを追加するには、UIを使用する方法とAPIを使用する方法の2とおりあります。 UI UI… # ファイルへのメタデータテンプレートの追加 メタデータテンプレートは、手順4で結果が得られるように1つ以上のファイルに適用する必要があります。ファイルにメタデータを追加するには、UIを使用する方法とAPIを使用する方法の2とおりあります。 ## UI UIを使用してファイルにメタデータを適用するには、ファイルに移動し、プレビューを開きます。[**メタデータ**] タブを使用して、[**追加**] をクリックします。手順1で作成したメタデータテンプレートを見つけて、値を選択し、必ず [**保存**] をクリックします。 ## API ファイルにメタデータテンプレートを追加するには、[ファイルにメタデータインスタンスを作成エンドポイント](e://post-files-id-metadata-id-id/)を使用する必要があります。また、前の手順で確認した`scope`および`templateKey`テンプレート値も必要になります。上記のUIを使用した方法で示したのと同じメタデータを適用するAPIコールの例を以下に示します。 規模を考慮したことにより、メタデータテンプレートが10,000を超えるファイルまたはフォルダに適用されると、403エラーが返されます。 1つ以上のファイルにテンプレートを適用しました **Source:** [https://ja.developer.box.com/guides/search/quick-start/apply-template-to-file/](https://ja.developer.box.com/guides/search/quick-start/apply-template-to-file/) --- ### ファイルへのメタデータの適用 **Type:** quick-start | **Category:** メタデータ | **Section:** Developer Guides ファイルへのメタデータの適用 新しいcustomerDataテンプレートが完成したら、このテンプレートをファイルまたはフォルダに適用できます。このテンプレートを適用するには、テンプレートのscopeとtemplateKeyのほか、テンプレートの適用先となる項目のID… # ファイルへのメタデータの適用 新しい`customerData`テンプレートが完成したら、このテンプレートをファイルまたはフォルダに適用できます。このテンプレートを適用するには、テンプレートの`scope`と`templateKey`のほか、テンプレートの適用先となる項目のIDが必要になります。 ``` curl -X POST https://api.box.com/2.0/files/12345/metadata/enterprise/customerInfo \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -H "content-type: application/json" \ -d '{ "name": "Box, Inc", "industry": "Technology", "tav": 1000000 }' ``` ``` var metadataValues = new Dictionary<string, object>() { { "name", "Box, Inc" }, { "industry", "Technology" }, { "tav", 100000 } }; Dictionary<string, object> metadata = await client.MetadataManager .CreateFileMetadataAsync(fileId: "12345", metadataValues, "enterprise", "customerInfo"); ``` ``` BoxFile file = new BoxFile(api, "12345"); file.createMetadata( "customerInfo", "enterprise", new Metadata() .add("name", "Box, Inc") .add("industry", "Technology") .add("tav", 100000) ); ``` ``` metadata = { 'name': 'Box, Inc', 'industry': 'Technology', 'tav': 1000000 } client.file(file_id='11111').metadata(scope='enterprise', template='customerInfo').set(metadata) ``` ``` client.files.addMetadata( '12345', client.metadata.scopes.ENTERPRISE, "customerInfo", { name: "Box, Inc", industry: "Technology", tav: 1000000 } ).then(metadata => { // ... }); ``` この例の`industry`フィールドは`enum`フィールドであるため、値にはこのフィールドで使用できるオプションのいずれかを指定する必要があります。それ以外の値を指定するとエラーが発生します。 このAPIにより、新しく作成されたメタデータインスタンスが返されます。 ``` { "name": "Box, Inc", "industry": "Technology", "tav": 1000000, "$id": "01234500-12f1-1234-aa12-b1d234cb567e", "$parent": "folder_12345,", "$scope": "enterprise_34567", "$template": "customerInfo", "$type": "customerInfo-6bcba49f-ca6d-4d2a-a758-57fe6edf44d0", "$typeVersion": 2, "$version": 1, "$canEdit": true } ``` ファイルにメタデータを適用しました **Source:** [https://ja.developer.box.com/guides/metadata/quick-start/create-instance/](https://ja.developer.box.com/guides/metadata/quick-start/create-instance/) --- ### ファイルリクエスト **Type:** guide | **Category:** ファイルリクエスト | **Section:** Developer Guides ファイルリクエスト Boxファイルリクエストを使用すると、どのユーザーに対しても、迅速かつ安全にファイルおよび関連付けられたメタデータをリクエストできます。ドラッグアンドドロップ方式のグラフィックインターフェースを使用して、以下が可能なウェブフォームを作成できます。 Box… # ファイルリクエスト Boxファイルリクエストを使用すると、どのユーザーに対しても、迅速かつ安全にファイルおよび関連付けられたメタデータをリクエストできます。ドラッグアンドドロップ方式のグラフィックインターフェースを使用して、以下が可能なウェブフォームを作成できます。 - Boxアカウントの有無に関係なく、フォルダにコラボレータを追加せずに、どのユーザーに対しても安全にファイルをリクエストする。 - メタデータフォームフィールド (必須/省略可として設定可能) を使用して追加情報を要求する。 - リンク設定を使用して、セキュリティと追跡の強化を可能にする。 - Box Relayを使用して自動化ワークフローを開始する。 **ファイルリクエストAPI**を使用すると、既存のファイルリクエストに基づく新しいファイルリクエストの作成、ファイルリクエストの設定の更新、ファイルリクエストの有効化/無効化と削除をプログラムによって実行できます。 ## ユースケース ファイルリクエストAPIは、特に、外部システムで新しいケース、プロジェクト、または顧客が作成されたときに自動的にフォルダが作成される場合に役立ちます。このように作成された各フォルダに対してファイルリクエストが自動的に生成されるため、顧客とその他のユーザーはドキュメントをプロジェクトにアップロードできます。 例 - **ケース管理** - この例では、各顧客のサポートケースには、関連付けられた独自のフォルダがあるため、新しいファイルリクエストを顧客に送信し、顧客に対してケースに関連したドキュメントをそのフォルダに送信するようリクエストできます。 - **プロジェクト管理** - この例では、各プロジェクトには、外部システムで定義されたプロジェクトごとに関連付けられた独自のフォルダがあります。このAPIを使用すると、このフォルダ内に自動的に**「クライアントドキュメント」**フォルダを作成することができます。また、必要に応じてドキュメントをアップロードできるようにリンクをクライアントに送信できます。 - **従業員の「受け渡し用」フォルダ** - この例では、銀行の新しいローンアドバイザは各自Boxに個人用フォルダを持っています。クライアントとの作業を支援するために、「受け渡し用」サブフォルダが関連付けられたファイルリクエストとともに自動的に生成されると、クライアントは担当ローンアドバイザの個人用フォルダにドキュメントを自動的にアップロードできるようになります。 ## 制限 現在、このAPIで可能なのは、別のフォルダに関連付けられた既存のファイルリクエストをコピーして新しいファイルリクエストを作成することだけです。テンプレートのファイルリクエストを使用してテンプレートフォルダを作成するには、ガイドを確認してください。 **Source:** [https://ja.developer.box.com/guides/file-requests/](https://ja.developer.box.com/guides/file-requests/) --- ### ファイルリクエストに関する情報の取得 **Type:** guide | **Category:** ファイルリクエスト | **Section:** Developer Guides ファイルリクエストに関する情報の取得 既存のファイルリクエストの詳細を取得するのに必要なのは、その一意のIDだけです。 ファイルリクエストのIDを確認するには、BoxウェブアプリにアクセスしてそのURL… # ファイルリクエストに関する情報の取得 既存の[ファイルリクエスト](g://file-requests/template)の詳細を取得するのに必要なのは、その一意のIDだけです。 ファイルリクエストのIDを確認するには、BoxウェブアプリにアクセスしてそのURLを調べます。ファイルリクエストテンプレートの設定に関する[ガイド](g://file-requests/template)で、ファイルリクエストIDの確認方法を確認してください。 **Source:** [https://ja.developer.box.com/guides/file-requests/get/](https://ja.developer.box.com/guides/file-requests/get/) --- ### ファイルリクエストのコピー **Type:** guide | **Category:** ファイルリクエスト | **Section:** Developer Guides ファイルリクエストのコピー 既存のテンプレートファイルリクエストのコピーを作成するために必要なのは、その一意のIDと、新しいファイルリクエストの適用先となるフォルダのIDだけです。 フォルダやファイルリクエストのIDを確認するには、BoxウェブアプリにアクセスしてそのURL… # ファイルリクエストのコピー 既存の[テンプレート](g://file-requests/template)ファイルリクエストのコピーを作成するために必要なのは、その一意のIDと、新しいファイルリクエストの適用先となるフォルダのIDだけです。 フォルダやファイルリクエストのIDを確認するには、BoxウェブアプリにアクセスしてそのURLを調べます。 フォルダIDは、フォルダにアクセスしたときにURLの末尾にある番号です。たとえば、`app.box.com/folder/123`というURLの場合、フォルダのIDは`123`です。 ファイルリクエストについては、ファイルリクエストテンプレートの設定に関する[ガイド](g://file-requests/template)で、ファイルリクエストIDの確認方法を確認してください。 ## コピー時にファイルリクエストを更新する テンプレートからコピーする際、ファイルリクエストに基本的な変更を行うことができます。ファイルリクエストをテンプレートからコピーするときに更新できるのは、ファイルリクエストのタイトル、説明、ステータス、およびその他いくつかの設定です。 ``` curl -i -X POST "https://api.box.com/2.0/file_requests/2342235/copy" \ -H "Authorization: Bearer <ACCESS_TOKEN>" \ -d '{ "title": "Please upload required documents", "description": "Please upload required documents", "status": "active", "is_email_required": true, "is_description_required": false, "folder": { "id": "342323423" } }' ``` テンプレート作成時に更新できるさまざまなフィールドの詳細については、[`POST /file-requests/:id/copy`](e://post_file_requests_id_copy) APIのリファレンスドキュメントを参照してください。 **Source:** [https://ja.developer.box.com/guides/file-requests/copy/](https://ja.developer.box.com/guides/file-requests/copy/) --- ### ファイルリクエストの削除 **Type:** guide | **Category:** ファイルリクエスト | **Section:** Developer Guides ファイルリクエストの削除 ファイルリクエストを削除するのに必要なのは、その一意のIDだけです。 ファイルリクエストのIDを確認するには、BoxウェブアプリにアクセスしてそのURLを調べます。ファイルリクエストテンプレートの設定に関するガイドで、ファイルリクエストID… # ファイルリクエストの削除 ファイルリクエストを削除するのに必要なのは、その一意のIDだけです。 ファイルリクエストのIDを確認するには、BoxウェブアプリにアクセスしてそのURLを調べます。ファイルリクエストテンプレートの設定に関する[ガイド](g://file-requests/template)で、ファイルリクエストIDの確認方法を確認してください。 **Source:** [https://ja.developer.box.com/guides/file-requests/delete/](https://ja.developer.box.com/guides/file-requests/delete/) --- ### ファイルリクエストの更新 **Type:** guide | **Category:** ファイルリクエスト | **Section:** Developer Guides ファイルリクエストの更新 既存のファイルリクエストの基本的な詳細の一部を更新するのに必要なのは、その一意のIDだけです。 テンプレート作成時に更新できるさまざまなフィールドの詳細については、POST /file-requests/:id/update API… # ファイルリクエストの更新 既存のファイルリクエストの基本的な詳細の一部を更新するのに必要なのは、その一意のIDだけです。 テンプレート作成時に更新できるさまざまなフィールドの詳細については、[`POST /file-requests/:id/update`](e://put_file_requests_id) APIのリファレンスドキュメントを参照してください。 ファイルリクエストのIDを確認するには、BoxウェブアプリにアクセスしてそのURLを調べます。ファイルリクエストテンプレートの設定に関する[ガイド](g://file-requests/template)で、ファイルリクエストIDの確認方法を確認してください。 **Source:** [https://ja.developer.box.com/guides/file-requests/update/](https://ja.developer.box.com/guides/file-requests/update/) --- ### ファイルレプリゼンテーションのダウンロード **Type:** guide | **Category:** レプリゼンテーション | **Section:** Developer Guides ファイルレプリゼンテーションのダウンロード レプリゼンテーションをダウンロードするには、レプリゼンテーションを選択した際に受け取ったurl_templateを使用します。{+asset_path… # ファイルレプリゼンテーションのダウンロード レプリゼンテーションをダウンロードするには、[レプリゼンテーションを選択](guide://representations/request-a-representation)した際に受け取った`url_template`を使用します。`{+asset_path}`は、レプリゼンテーションの種類に応じて置き換えます。 ## ページ割りされたレプリゼンテーション PDFのようにページ割りされたレプリゼンテーションでは、`{+asset_path}`を目的のページ番号とファイル拡張子に置き換えます (例: `1.pdf`)。 ``` curl https://dl.boxcloud.com/api/2.0/internal_files/123/versions/345/representations/pdf/content/3.pdf \ -H "authorization: Bearer ACCESS_TOKEN" ``` ## ページ割りされていないレプリゼンテーション ページ割りされていないレプリゼンテーションでは、`{+asset_path}`を空の文字列に置き換えます。 ``` curl https://dl.boxcloud.com/api/2.0/internal_files/123/versions/345/representations/jpg_32x32/content/ \ -H "authorization: Bearer ACCESS_TOKEN" ``` ## 省略可能なクエリパラメータ レプリゼンテーションを取得する場合、以下の省略可能なヘッダーを使用できます。 | パラメータ | オプション | デフォルト | | --- | --- | --- | | set_content_disposition_type | inline / attachment | null | 指定された値でAPIレスポンスの`content-disposition`ヘッダーを設定します。配置タイプを`attachment`に設定した場合、ほとんどのウェブブラウザではレスポンスをデバイスに保存するようユーザーに促します。一方、タイプを`inline`に設定した場合は、ブラウザでファイルが開かれます。 指定しなかった場合、レスポンスに`content-disposition`ヘッダーは含まれません。 | パラメータ | オプション | デフォルト | | --- | --- | --- | | set_content_disposition_filename | 拡張子のないファイル名 | null | アプリケーションでは、ダウンロードしたレプリゼンテーションのファイル名を定義できます。 定義しなかった場合、ファイル名は、Box内の元のファイル名から派生し、拡張子はレプリゼンテーションのファイルタイプに置き換えられます。 **Source:** [https://ja.developer.box.com/guides/representations/download-a-representation/](https://ja.developer.box.com/guides/representations/download-a-representation/) --- ### ファイルをBox Doc Genテンプレートとして設定 **Type:** guide | **Category:** Box Doc Gen | **Section:** Developer Guides ファイルをBox Doc Genテンプレートとして設定 既存のドキュメントをBox Doc Genテンプレートとして設定し、それを使用してドキュメントを生成できます。 開始する前に Box Doc Gen APIの使用を開始する前に、Box Doc Gen… # ファイルをBox Doc Genテンプレートとして設定 既存のドキュメントをBox Doc Genテンプレートとして設定し、それを使用してドキュメントを生成できます。 ## 開始する前に Box Doc Gen APIの使用を開始する前に、[Box Doc Genの使い方](g://docgen/docgen-getting-started)ガイドに記載されている手順に従って、PlatformアプリとBox Doc Genテンプレートを作成してください。 ## リクエストの送信 質問を含むリクエストを送信するには、`POST /2.0/docgen_templates`エンドポイントを使用し、必須のパラメータを指定します。 ### パラメータ コールを実行するには、以下のパラメータを渡す必要があります。必須のパラメータは**太字**で示されています。 | パラメータ | 説明 | 例 | | --- | --- | --- | | file.id | Box Doc Genテンプレートとして設定するファイルのID。 | 12345678 | | file.type | 指定した入力データの種類。値は常に**file**になります。 | file | ## ユースケース ### ファイルをBox Doc Genテンプレートとして設定する 次のサンプルでは、ファイルがBox Doc Genテンプレートとして認識されるように設定する方法を示します。 ファイルは`.docx`形式である必要があります。 ### ファイルからBox Doc Genテンプレートの設定を削除する ファイルのBox Doc Genテンプレートの設定が解除されるようにするには、`DELETE 2.0/docgen_templates/:template_id`リクエストを使用します。 **Source:** [https://ja.developer.box.com/guides/docgen/mark-template/](https://ja.developer.box.com/guides/docgen/mark-template/) --- ### ファイルを完全に削除 **Type:** guide | **Category:** ごみ箱 | **Section:** Developer Guides ファイルを完全に削除 ごみ箱に移動されたファイルは、デフォルトで30日間ごみ箱に保持された後で削除されます。BusinessアカウントまたはEnterprise… # ファイルを完全に削除 ごみ箱に移動されたファイルは、デフォルトで30日間ごみ箱に保持された後で削除されます。BusinessアカウントまたはEnterpriseアカウントの管理者は、削除までの期間を変更できます。削除までの期間が経過する前にごみ箱からファイルを完全に削除する場合は、ごみ箱に移動されたファイルの`ID`を使用して`DELETE`リクエストを`/files/:file_id/trash`に送信します。 **Source:** [https://ja.developer.box.com/guides/trash/permanently-delete-file/](https://ja.developer.box.com/guides/trash/permanently-delete-file/) --- ### ファイル情報の取得 **Type:** guide | **Category:** ファイル | **Section:** Developer Guides ファイル情報の取得 ファイルのコンテンツではなく、ファイル自体の情報を取得するには、ファイルのidを指定してGET /files/:id APIを呼び出します。 ファイルID ファイルのidを確認するには、ウェブアプリでファイルにアクセスして、URLからid… # ファイル情報の取得 ファイルのコンテンツではなく、ファイル自体の情報を取得するには、ファイルの`id`を指定して[`GET /files/:id`](e://get-files-id) APIを呼び出します。 ## ファイルID ファイルの`id`を確認するには、ウェブアプリでファイルにアクセスして、URLから`id`をコピーします。たとえば、URLが`https://*.app.box.com/file/123`の場合、`file_id`は`123`です。 ## その他のフィールド ファイルのフィールドをさらに取得するには、必ず`fields`クエリパラメータを渡してください。 追加フィールドのリクエストについて確認する **Source:** [https://ja.developer.box.com/guides/files/get/](https://ja.developer.box.com/guides/files/get/) --- ### フォルダ **Type:** guide | **Category:** フォルダ | **Section:** Developer Guides フォルダ フォルダは、ファイルとともに、Box APIの中核を成します。フォルダはアップロードおよびダウンロードが可能で、コンテンツに関する重要なメタデータ情報を保持できます。 # フォルダ フォルダは、[ファイル](g://files)とともに、Box APIの中核を成します。フォルダはアップロードおよびダウンロードが可能で、コンテンツに関する重要なメタデータ情報を保持できます。 **Source:** [https://ja.developer.box.com/guides/folders/](https://ja.developer.box.com/guides/folders/) --- ### フォルダツリーの作成 **Type:** guide | **Category:** フォルダ | **Section:** Developer Guides フォルダツリーの作成 以下の例は、フォルダツリーのJSON… # フォルダツリーの作成 以下の例は、フォルダツリーのJSONレプリゼンテーションを作成する方法を示しています。フォルダツリーは、フォルダの名前とそのフォルダ内にあるすべてのサブフォルダで構成されます。 以下のサンプルでは、先頭の**ルート**フォルダと、コードでトラバースする最大深度を指定できます。また、初期化されたSDKクライアントを渡すことができるため、どのユーザーが認証されるかを構成することもできます。 ``` using System; using System.Collections.Generic; using System.Diagnostics; using System.Dynamic; using System.IO; using System.Linq; using System.Net; using System.Net.Sockets; using System.Runtime.InteropServices; using System.Text; using System.Threading.Tasks; using Box.V2; using Box.V2.Auth; using Box.V2.Config; using Box.V2.Converter; using Box.V2.Exceptions; using Box.V2.JWTAuth; using Box.V2.Models; using Newtonsoft.Json; namespace BoxPlayground { public class Program4 { static void Main(string[] args) { ExecuteMainAsync().Wait(); } public class BoxFolderTreeBuilder { public BoxClient BoxClient { get; set; } public string RootFolderId { get; set; } public int MaxDepth { get; set; } public BoxFolderTreeBuilder(BoxClient boxClient, string rootFolderId = "0", int maxDepth = -1) { this.BoxClient = boxClient; this.RootFolderId = rootFolderId; this.MaxDepth = maxDepth; } public async Task<BoxFolderTree> BuildFolderTreeWithFlatLists() { var tree = new BoxFolderTree { RootId = this.RootFolderId, Files = new List<BoxFolderTreeItem>(), Folders = new List<BoxFolderTreeFolder>() }; var rootFolderItems = await this.BoxClient.FoldersManager.GetFolderItemsAsync(this.RootFolderId, limit: 1000, autoPaginate: true); var rootFolderChildren = new List<BoxFolderTreeFolder>(); foreach (var item in rootFolderItems.Entries) { var folderTreeItem = new BoxFolderTreeItem(item); folderTreeItem.Path = $"{this.RootFolderId}"; if (item.Type == "file") { tree.Files.Add(folderTreeItem); } else if (item.Type == "folder") { var childFolder = new BoxFolderTreeFolder(folderTreeItem); tree.Folders.Add(new BoxFolderTreeFolder(folderTreeItem)); rootFolderChildren.Add(childFolder); } } tree = await Dive(tree, rootFolderChildren, 1); return tree; } private async Task<BoxFolderTree> Dive(BoxFolderTree tree, List<BoxFolderTreeFolder> children, int currentDepth) { if (InTooDeep(currentDepth)) { return tree; } else { currentDepth++; var additionalChildren = new List<BoxFolderTreeFolder>(); foreach (var child in children) { var folderItems = await this.BoxClient.FoldersManager.GetFolderItemsAsync(child.Item.Id, limit: 1000, autoPaginate: true); var foundFolder = tree.Folders.FindIndex((f) => { return f.Item.Id == child.Item.Id; }); foreach (var item in folderItems.Entries) { if (foundFolder >= 0) { tree.Folders[foundFolder].Children.Add(item); } var folderTreeItem = new BoxFolderTreeItem(item); folderTreeItem.Path = $"{child.Path}/{child.Item.Id}"; if (item.Type == "file") { tree.Files.Add(folderTreeItem); } else if (item.Type == "folder") { var childFolder = new BoxFolderTreeFolder(folderTreeItem); tree.Folders.Add(new BoxFolderTreeFolder(folderTreeItem)); additionalChildren.Add(childFolder); } } } if (additionalChildren.Count == 0) { return tree; } else { return await Dive(tree, additionalChildren, currentDepth); } } } private bool InTooDeep(int depthCount) { if (this.MaxDepth < 0) { return false; } else { return (depthCount >= this.MaxDepth); } } public class BoxFolderTreeItem { [JsonProperty(PropertyName = "item")] public BoxItem Item { get; set; } [JsonProperty(PropertyName = "path")] public string Path { get; set; } public BoxFolderTreeItem(BoxItem item) { Item = item; } } public class BoxFolderTreeFolder : BoxFolderTreeItem { public BoxFolderTreeFolder(BoxFolderTreeItem item) : base(item.Item) { this.Path = item.Path; } [JsonProperty(PropertyName = "children")] public List<BoxItem> Children { get; set; } = new List<BoxItem>(); } public class BoxFolderTree { [JsonProperty(PropertyName = "rootId")] public string RootId { get; set; } [JsonProperty(PropertyName = "files")] public List<BoxFolderTreeItem> Files { get; set; } [JsonProperty(PropertyName = "folders")] public List<BoxFolderTreeFolder> Folders { get; set; } public string writeJSON() { var converter = new Box.V2.Converter.BoxJsonConverter(); return converter.Serialize<BoxFolderTreeBuilder.BoxFolderTree>(this); } } } private static async Task ExecuteMainAsync() { using (FileStream fs = new FileStream($"./config.json", FileMode.Open)) { var session = new BoxJWTAuth(BoxConfig.CreateFromJsonFile(fs)); var serviceAccountClient = session.AdminClient(session.AdminToken()); var folderTreeBuilder = new BoxFolderTreeBuilder(serviceAccountClient, rootFolderId: "37477903736"); var tree = await folderTreeBuilder.BuildFolderTreeWithFlatLists(); System.Console.WriteLine(tree.writeJSON()); } } } } ``` ``` package com.box; import java.io.BufferedReader; import java.nio.charset.Charset; import java.nio.file.Files; import java.nio.file.Path; import java.nio.file.Paths; import java.util.ArrayList; import com.box.sdk.BoxConfig; import com.box.sdk.BoxDeveloperEditionAPIConnection; import com.box.sdk.BoxFile; import com.box.sdk.BoxFolder; import com.box.sdk.BoxItem; import com.eclipsesource.json.JsonArray; import com.eclipsesource.json.JsonObject; public class BoxFolderTreeBuilder { private BoxDeveloperEditionAPIConnection _boxClient; private String _rootFolderId; private int _maxDepth; private static final String DEFAULT_ROOT_FOLDER_ID = "0"; private static final int DEFAULT_MAX_DEPTH = -1; public BoxFolderTreeBuilder(BoxDeveloperEditionAPIConnection boxClient) { this(boxClient, DEFAULT_ROOT_FOLDER_ID, DEFAULT_MAX_DEPTH); } public BoxFolderTreeBuilder(BoxDeveloperEditionAPIConnection boxClient, String rootFolderId) { this(boxClient, rootFolderId, DEFAULT_MAX_DEPTH); } public BoxFolderTreeBuilder(BoxDeveloperEditionAPIConnection boxClient, int maxDepth) { this(boxClient, DEFAULT_ROOT_FOLDER_ID, maxDepth); } public BoxFolderTreeBuilder(BoxDeveloperEditionAPIConnection boxClient, String rootFolderId, int maxDepth) { this._boxClient = boxClient; this._rootFolderId = rootFolderId; this._maxDepth = maxDepth; } public BoxFolderTree buildFolderTreeWithFlatLists() { BoxFolderTree tree = new BoxFolderTree(); tree.setRootId(this._rootFolderId); ArrayList<BoxFolderTreeFolder> rootFolderChildren = new ArrayList<>(); BoxFolder folder = new BoxFolder(this._boxClient, this._rootFolderId); String path = this._rootFolderId; for (BoxItem.Info itemInfo : folder) { if (itemInfo instanceof BoxFile.Info) { BoxFile.Info fileInfo = (BoxFile.Info) itemInfo; BoxFolderTreeFile treeFile = new BoxFolderTreeFile(fileInfo, path); tree.files.add(treeFile); } else if (itemInfo instanceof BoxFolder.Info) { BoxFolder.Info folderInfo = (BoxFolder.Info) itemInfo; BoxFolderTreeFolder treeFolder = new BoxFolderTreeFolder(folderInfo, path); tree.folders.add(treeFolder); rootFolderChildren.add(treeFolder); } } tree = Dive(tree, rootFolderChildren, 1); return tree; } private BoxFolderTree Dive(BoxFolderTree tree, ArrayList<BoxFolderTreeFolder> children, int currentDepth) { if (inTooDeep(currentDepth)) { return tree; } else { currentDepth++; ArrayList<BoxFolderTreeFolder> additionalChildren = new ArrayList<>(); for (BoxFolderTreeFolder child : children) { BoxFolder folderItems = new BoxFolder(this._boxClient, child.getItem().getID()); int foundFolder = -1; for (int i = 0; i < tree.folders.size(); i++) { if (child.getItem().getID() == tree.folders.get(i).getItem().getID()) { foundFolder = i; } } String path = String.format("%s/%s", child.getPath(), child.getItem().getID()); for (BoxItem.Info item : folderItems.getChildren()) { if (foundFolder >= 0) { tree.folders.get(foundFolder).children.add(new BoxFolderTreeItem(item)); } if (item instanceof BoxFile.Info) { BoxFile.Info fileInfo = (BoxFile.Info) item; tree.files.add(new BoxFolderTreeFile(fileInfo, path)); } else if (item instanceof BoxFolder.Info) { BoxFolder.Info folderInfo = (BoxFolder.Info) item; BoxFolderTreeFolder nestedFolder = new BoxFolderTreeFolder(folderInfo, path); tree.folders.add(nestedFolder); additionalChildren.add(nestedFolder); } } } if (additionalChildren.size() == 0) { return tree; } else { return Dive(tree, additionalChildren, currentDepth); } } } private Boolean inTooDeep(int depthCount) { if (this._maxDepth < 0) { return false; } else { return (depthCount >= this._maxDepth); } } public class BoxFolderTree { private String rootId; private ArrayList<BoxFolderTreeFile> files = new ArrayList<>(); private ArrayList<BoxFolderTreeFolder> folders = new ArrayList<>(); public String getRootId() { return this.rootId; } public void setRootId(String id) { this.rootId = id; } public String writeJSON() { JsonObject requestJSON = new JsonObject(); JsonArray filesJSON = new JsonArray(); for (BoxFolderTreeFile file : files) { filesJSON.add(file.convertToJSON()); } JsonArray foldersJSON = new JsonArray(); for (BoxFolderTreeFolder folder : folders) { foldersJSON.add(folder.convertToJSON()); } requestJSON.add("rootId", this.rootId); requestJSON.add("files", filesJSON); requestJSON.add("folders", foldersJSON); return requestJSON.toString(); } } public class BoxFolderTreeItem { private BoxItem.Info item; public BoxFolderTreeItem(BoxItem.Info item) { this.item = item; } public JsonObject convertToJSON() { JsonObject itemJSON = new JsonObject(); itemJSON.add("id", this.item.getID()); itemJSON.add("name", this.item.getName()); String type = (item instanceof BoxFile.Info == true) ? "file" : "folder"; itemJSON.add("type", type); return itemJSON; } } public class BoxFolderTreeFile { private BoxFile.Info item; private String path; public BoxFolderTreeFile(BoxFile.Info item, String path) { this.item = item; this.path = path; } public BoxFile.Info getItem() { return this.item; } public void setItem(BoxFile.Info info) { this.item = info; } public String getPath() { return this.path; } public void setPath(String path) { this.path = path; } public JsonObject convertToJSON() { JsonObject itemJSON = new JsonObject(); JsonObject fileJSON = new JsonObject(); fileJSON.add("id", this.item.getID()); fileJSON.add("type", "file"); fileJSON.add("name", this.item.getName()); itemJSON.add("path", this.path); itemJSON.add("item", fileJSON); return itemJSON; } } public class BoxFolderTreeFolder { private BoxFolder.Info item; private String path; private ArrayList<BoxFolderTreeItem> children; public BoxFolderTreeFolder(BoxFolder.Info item, String path) { this.item = item; this.path = path; this.children = new ArrayList<>(); } public BoxFolder.Info getItem() { return this.item; } public void setItem(BoxFolder.Info info) { this.item = info; } public String getPath() { return this.path; } public void setPath(String path) { this.path = path; } public JsonObject convertFolderToJSON() { JsonObject itemJSON = new JsonObject(); JsonObject folderJSON = new JsonObject(); folderJSON.add("id", this.item.getID()); folderJSON.add("type", "folder"); folderJSON.add("name", this.item.getName()); itemJSON.add("path", this.path); itemJSON.add("item", folderJSON); return itemJSON; } public JsonObject convertToJSON() { JsonObject folderJSON = this.convertFolderToJSON(); JsonArray children = new JsonArray(); for (BoxFolderTreeItem item : this.children) { children.add(item.convertToJSON()); } folderJSON.add("children", children); return folderJSON; } } public static void main(String[] args) throws Exception { Path configPath = Paths.get("config.json"); try (BufferedReader reader = Files.newBufferedReader(configPath, Charset.forName("UTF-8"))) { BoxConfig boxConfig = BoxConfig.readFrom(reader); BoxDeveloperEditionAPIConnection serviceAccountClient = BoxDeveloperEditionAPIConnection .getAppEnterpriseConnection(boxConfig); BoxFolderTreeBuilder treeBuilder = new BoxFolderTreeBuilder(serviceAccountClient, "43491738095", 2); BoxFolderTree tree = treeBuilder.buildFolderTreeWithFlatLists(); System.out.println(tree.writeJSON()); } } } ``` ``` class BoxFolderTreeBuilder { constructor(boxClient, options) { options = options || {}; boxClient._useIterators = true; this.boxClient = boxClient; this.maxDepth = options.maxDepth || -1; this.rootFolderId = options.rootFolderId || "0"; } async buildFolderTreeWithFlatLists() { let tree = { rootId: this.rootFolderId, folders: [], files: [] } let folderItemsIterator = await this.boxClient.folders.getItems(this.rootFolderId); let collection = await BoxUtilities.autoPage(folderItemsIterator); let rootFolderChildren = []; const path = `${this.rootFolderId}`; collection.forEach((item) => { if (item.type === "file") { tree.files.push({ item, path }) } else if (item.type === "folder") { let folderTreeFolder = { item, path, children: [] } tree.folders.push(folderTreeFolder); rootFolderChildren.push(folderTreeFolder); } }); tree = await this.dive(tree, rootFolderChildren, 1); return tree; } async dive(tree, children, currentDepth) { if (this.inTooDeep(currentDepth)) { return tree; } else { currentDepth++; let additionalChildren = []; let childrenPromises = []; children.forEach((child) => { let foundFolder = -1; childrenPromises.push(this.boxClient.folders.getItems(child.item.id) .then((folderItemsIterator) => { return BoxUtilities.autoPage(folderItemsIterator) .then((collection) => { for (let i = 0; i < tree.folders.length; i++) { if (child.item.id === tree.folders[i].item.id) { foundFolder = i; } } const path = `${child.path}/${child.item.id}`; collection.forEach((item) => { if (foundFolder >= 0) { tree.folders[foundFolder].children.push(item); } if (item.type === "file") { tree.files.push({ item, path }) } else if (item.type === "folder") { let folderTreeFolder = { item, path, children: [] } tree.folders.push(folderTreeFolder); additionalChildren.push(folderTreeFolder); } }); return; }); })); }); await Promise.all(childrenPromises); if (additionalChildren.length === 0) { return tree; } else { return this.dive(tree, additionalChildren, currentDepth); } } } inTooDeep(depthCount) { if (this.maxDepth < 0) { return false; } else { return (depthCount >= this.maxDepth); } } } class BoxUtilities { static async autoPage(iterator, collection = []) { let moveToNextItem = async () => { let item = await iterator.next(); if (item.value) { collection.push(item.value); } if (item.done !== true) { return moveToNextItem(); } else { return collection; } } return moveToNextItem(); } } let folderTreeBuilder = new BoxFolderTreeBuilder(client); folderTreeBuilder.buildFolderTreeWithFlatLists() .then((tree) => { console.log(JSON.stringify(tree)); }) ``` **Source:** [https://ja.developer.box.com/guides/folders/bulk/build-folder-tree/](https://ja.developer.box.com/guides/folders/bulk/build-folder-tree/) --- ### フォルダのコピー **Type:** guide | **Category:** フォルダ | **Section:** Developer Guides フォルダのコピー フォルダのコピーを宛先フォルダ内に作成します。 元のフォルダは変更されません。 Box上でフォルダをコピーするには、コピー先となるparentフォルダのidをAPI… # フォルダのコピー フォルダのコピーを宛先フォルダ内に作成します。 元のフォルダは変更されません。 Box上でフォルダをコピーするには、コピー先となる`parent`フォルダの`id`をAPIに渡す必要があります。 オプションで、新しいフォルダに別の名前を付けることもできます。 # 名前に関する制約事項 フォルダ名にはいくつかの制限があります。印字不可能なASCII文字、スラッシュ、バックスラッシュ (`/`、`\`) を含む名前のほか、末尾にスペースを含む名前は禁止されています。 また、`.`および`..`は予約済みの名前であるため、使用できません。 ## 非同期コピー コピーされるフォルダに含まれる項目が500個以下の場合は、APIコールと同時にコピーが実行されます。コールはコピー操作が完了するまで復帰しません。 コピー元のフォルダに500個を超える項目が含まれる場合は、非同期的にコピー操作が実行され、APIコールはコピー操作が完了していなくても直ちに復帰します。現時点では、コピー操作がいつ終了したのかを確認するAPIはありません。 ## フォルダのロック この操作の進行中は、ファイルツリーの一部がロックされます。ロックされるのは、主に元のフォルダとその子孫フォルダ、および宛先フォルダです。 操作の進行中は、ロックされているどのフォルダに対しても、他の移動、コピー、削除、または復元操作を実行できません。最も重要な点は、同じフォルダをフォルダツリーの2つの異なる部分に同時にコピーすることはできないということです。 ## メタデータ 宛先フォルダのいずれかの親フォルダにメタデータカスケードポリシーが適用されている場合は、メタデータカスケード操作が非同期的に開始されます。 現時点では、この操作がいつ終了したのかを確認するAPIはありません。 **Source:** [https://ja.developer.box.com/guides/folders/single/copy/](https://ja.developer.box.com/guides/folders/single/copy/) --- ### フォルダのロックの作成 **Type:** guide | **Category:** フォルダ | **Section:** Developer Guides フォルダのロックの作成 Box内のフォルダにロックを作成するには、ロックを適用するフォルダのidをBoxのAPIに指定します。必要に応じて、フォルダのロックとともに適用する特定のlocked_operationsを指定できます。 フォルダロック フォルダロックAPI… # フォルダのロックの作成 Box内のフォルダにロックを作成するには、ロックを適用するフォルダの`id`をBoxのAPIに指定します。必要に応じて、フォルダのロックとともに適用する特定の`locked_operations`を指定できます。 # フォルダロック フォルダロックAPIエンドポイントを使用する際は、アクセスしようとしているフォルダの所有者/共同所有者として認証されている必要があります。 # ロックされる操作の設定 フォルダロックリクエストに`locked_operations`オブジェクトが含まれる場合は、`move`と`delete`の両方を`true`に設定する必要があります。このオブジェクトでロック操作を1つだけ指定した場合または両方の値を`true`以外に設定した場合は、エラーが発生します。これらのオプションは、今後追加の操作を可能にするために実装されています。 ## ロック操作 フォルダに適用できるロック操作には、`move`と`delete`の2つがあります。 `move`ロックを使用すると、ロックが適用されている間、フォルダが新しい場所または新しい所有者に移動されなくなります。 `delete`ロックを使用すると、ロックが適用されている間、フォルダが削除されなくなります。 **Source:** [https://ja.developer.box.com/guides/folders/single/create-lock/](https://ja.developer.box.com/guides/folders/single/create-lock/) --- ### フォルダのロックの削除 **Type:** guide | **Category:** フォルダ | **Section:** Developer Guides フォルダのロックの削除 Box内のフォルダに適用されたロックを削除するには、フォルダのロックIDを指定してDELETE /folder_locks/:id APIを呼び出します。 フォルダロック フォルダロックAPI… # フォルダのロックの削除 Box内のフォルダに適用されたロックを削除するには、フォルダのロックIDを指定して`DELETE /folder_locks/:id` APIを呼び出します。 # フォルダロック フォルダロックAPIエンドポイントを使用する際は、アクセスしようとしているフォルダの所有者/共同所有者として認証されている必要があります。 # フォルダのロックIDを見つける方法 フォルダのロックを削除するには、フォルダのロックIDをAPIに指定する必要があります。フォルダのロックIDは、[フォルダのロックを作成](g://folders/single/create-lock)したとき、または特定のフォルダに対する[ロックのリストを取得](g://folders/single/get-locks)したときに、レスポンスに示されます。 **Source:** [https://ja.developer.box.com/guides/folders/single/delete-lock/](https://ja.developer.box.com/guides/folders/single/delete-lock/) --- ### フォルダのロックの取得 **Type:** guide | **Category:** フォルダ | **Section:** Developer Guides フォルダのロックの取得 Box内のフォルダに対する現在のロックのリストを取得するには、folder_idクエリ文字列パラメータとしてフォルダのIDを指定してGET /folder_locks/ APIを呼び出します。 フォルダロック フォルダロックAPI… # フォルダのロックの取得 Box内のフォルダに対する現在のロックのリストを取得するには、`folder_id`クエリ文字列パラメータとしてフォルダのIDを指定して`GET /folder_locks/` APIを呼び出します。 # フォルダロック フォルダロックAPIエンドポイントを使用する際は、アクセスしようとしているフォルダの所有者/共同所有者として認証されている必要があります。 ## フォルダID フォルダの`id`を確認するには、ウェブアプリでフォルダにアクセスして、URLから`id`をコピーします。たとえば、URLが`https://*.app.box.com/folder/123`の場合、`folder_id`は`123`です。 **Source:** [https://ja.developer.box.com/guides/folders/single/get-locks/](https://ja.developer.box.com/guides/folders/single/get-locks/) --- ### フォルダの作成 **Type:** guide | **Category:** フォルダ | **Section:** Developer Guides フォルダの作成 Box上でフォルダを作成するには、新しいフォルダのnameと、新しいフォルダの作成先になるparentフォルダのidをAPIに渡す必要があります。 名前に関する制約事項 フォルダ名にはいくつかの制限があります。印字不可能なASCII… # フォルダの作成 Box上でフォルダを作成するには、新しいフォルダの`name`と、新しいフォルダの作成先になる`parent`フォルダの`id`をAPIに渡す必要があります。 # 名前に関する制約事項 フォルダ名にはいくつかの制限があります。印字不可能なASCII文字、スラッシュ、バックスラッシュ (`/`、`\`) を含む名前のほか、末尾にスペースを含む名前は禁止されています。 また、`.`および`..`は予約済みの名前であるため、使用できません。 **Source:** [https://ja.developer.box.com/guides/folders/single/create/](https://ja.developer.box.com/guides/folders/single/create/) --- ### フォルダの削除 **Type:** guide | **Category:** フォルダ | **Section:** Developer Guides フォルダの削除 Box上でフォルダを削除するには、削除するフォルダのIDをAPIに渡す必要があります。 空でないフォルダの削除 フォルダが空でない場合、このAPIはエラーを返します。フォルダを削除するときにrecursive… # フォルダの削除 Box上でフォルダを削除するには、削除するフォルダのIDをAPIに渡す必要があります。 ## 空でないフォルダの削除 フォルダが空でない場合、このAPIはエラーを返します。フォルダを削除するときに`recursive`パラメータを渡すと、空でないフォルダも強制的に削除できます。その場合は、サブフォルダを含め、フォルダ内のすべての項目が削除されます。 ## フォルダのロック フォルダがBoxから完全に削除されるか、ごみ箱に移動されるかは、会社の設定に応じて決定されます。 この操作の進行中は、ファイルツリーの一部がロックされます。ロックされるのは、主に元のフォルダとその子孫フォルダすべてです。 操作の進行中は、ロックされているどのフォルダに対しても、それ以外の移動、コピー、削除、または復元操作を実行できません。 ## タイムアウト この操作のタイムアウトは60秒です。操作の時間には、`HTTP 503`が返されてからの時間も含まれます。 **Source:** [https://ja.developer.box.com/guides/folders/single/delete/](https://ja.developer.box.com/guides/folders/single/delete/) --- ### フォルダの復元 **Type:** guide | **Category:** ごみ箱 | **Section:** Developer Guides フォルダの復元 ごみ箱に移動されたが削除されていないフォルダを復元するには、/folders/:folder_idエンドポイントにPOSTリクエストを送信します。これにより、フォルダがまだ使用可能であれば元の親フォルダに戻されます。または、オプションとしてparent… # フォルダの復元 ごみ箱に移動されたが削除されていないフォルダを復元するには、`/folders/:folder_id`エンドポイントに`POST`リクエストを送信します。これにより、フォルダがまだ使用可能であれば元の親フォルダに戻されます。または、オプションとして`parent`フォルダを指定することもできます。 フォルダ復元の進行中は、ファイルツリーの一部がロックされます。ロックされるのは、リクエストの元のフォルダとその子孫フォルダ、および宛先フォルダです。 フォルダの復元中、ロックされているフォルダに対して、それ以外の移動、コピー、削除、復元の操作を実行することはできません。 **Source:** [https://ja.developer.box.com/guides/trash/restore-folder/](https://ja.developer.box.com/guides/trash/restore-folder/) --- ### フォルダの更新 **Type:** guide | **Category:** フォルダ | **Section:** Developer Guides フォルダの更新 Box上でフォルダを更新するには、次のAPIを呼び出す必要があります。 名前に関する制約事項 フォルダ名にはいくつかの制限があります。印字不可能なASCII… # フォルダの更新 Box上でフォルダを更新するには、次のAPIを呼び出す必要があります。 ## 名前に関する制約事項 フォルダ名にはいくつかの制限があります。印字不可能なASCII文字、スラッシュ、バックスラッシュ (`/`、`\`) を含む名前のほか、末尾にスペースを含む名前は禁止されています。 また、`.`および`..`は予約済みの名前であるため、使用できません。 ## タイムアウト この操作のタイムアウトは60秒です。この操作は、`HTTP 503`が返されたら完了します。 **Source:** [https://ja.developer.box.com/guides/folders/single/update/](https://ja.developer.box.com/guides/folders/single/update/) --- ### フォルダの移動 **Type:** guide | **Category:** フォルダ | **Section:** Developer Guides フォルダの移動 フォルダを移動するには、その親フォルダのID… # フォルダの移動 フォルダを移動するには、その親フォルダのIDを更新します。 ## 操作の詳細 この呼び出しは同期的に復帰します。これは、すべての子孫に大量の項目が含まれているフォルダを移動する場合にも当てはまります。つまり、非常に大きいフォルダの場合は、呼び出しが完了するまでに数分または数時間かかる可能性があるほか、移動中にツリーの一部がロックされることもあります。 フォルダの移動中は、ファイルツリーの一部がロックされます。ロックされるのは、主に元のフォルダとその子孫フォルダ、および宛先フォルダです。 移動操作の間は、ロックされているどのフォルダに対しても、それ以外の移動、コピー、削除、または復元操作を実行できません。 ## 非公開フォルダへのサブフォルダの移動 コラボレーションサブフォルダを非公開サブフォルダに移動しようとすると、[`cannot_make_collaborated_subfolder_private`](../../api-calls/permissions-and-errors/common-errors.md#400-bad-request)エラーが発生します。そのような場合は、次のようにリクエストに`owned_by.id`パラメータを設定し、そのフォルダが属しているユーザーのIDを指定します。 **Source:** [https://ja.developer.box.com/guides/folders/single/move/](https://ja.developer.box.com/guides/folders/single/move/) --- ### フォルダを完全に削除 **Type:** guide | **Category:** ごみ箱 | **Section:** Developer Guides フォルダを完全に削除 ごみ箱に移動されたフォルダは、デフォルトで30日間ごみ箱に保持された後で削除されます。BusinessアカウントまたはEnterprise… # フォルダを完全に削除 ごみ箱に移動されたフォルダは、デフォルトで30日間ごみ箱に保持された後で削除されます。BusinessアカウントまたはEnterpriseアカウントの管理者は、削除までの期間を変更できます。削除までの期間が経過する前にごみ箱からフォルダを完全に削除する場合は、ごみ箱に移動されたフォルダの`ID`を使用して`DELETE`リクエストを`/folders/:folder_id/trash`に送信します。 **Source:** [https://ja.developer.box.com/guides/trash/permanently-delete-folder/](https://ja.developer.box.com/guides/trash/permanently-delete-folder/) --- ### フォルダ内のすべてのファイルのアップロード **Type:** guide | **Category:** アップロード | **Section:** Developer Guides フォルダ内のすべてのファイルのアップロード アプリケーションによっては、1つのフォルダのすべてのファイルをアップロードできる場合もあります。SDKとCLI… # フォルダ内のすべてのファイルのアップロード アプリケーションによっては、1つのフォルダのすべてのファイルをアップロードできる場合もあります。SDKとCLIを使用してこの処理を実行するには、フォルダツリー内を移動してすべてのファイルを探し、そのファイルをアップロードする必要があります。 ``` using System; using System.Collections.Generic; using System.Diagnostics; using System.Dynamic; using System.IO; using System.Linq; using System.Net; using System.Net.Sockets; using System.Runtime.InteropServices; using System.Security.Cryptography; using System.Text; using System.Threading.Tasks; using Box.V2; using Box.V2.Auth; using Box.V2.Config; using Box.V2.Converter; using Box.V2.Exceptions; using Box.V2.JWTAuth; using Box.V2.Models; using Newtonsoft.Json; namespace BoxPlayground { public class Program { static void Main (string[] args) { ExecuteMainAsync ().Wait (); } const long CHUNKED_UPLOAD_MINIMUM = 200000; private static async Task ExecuteMainAsync () { var directoryName = "dotnetUploadFolder"; var parentFolderId = "0"; var files = Directory.EnumerateFiles (directoryName); using (FileStream fs = new FileStream ("./config.json", FileMode.Open)) { var session = new BoxJWTAuth (BoxConfig.CreateFromJsonFile (fs)); var client = session.AdminClient (session.AdminToken ()); var folderId = ""; try { var createdFolder = await client.FoldersManager.CreateAsync ( new BoxFolderRequest { Parent = new BoxRequestEntity { Id = parentFolderId }, Name = directoryName }); folderId = createdFolder.Id; } catch (BoxConflictException<BoxFolder> e) { folderId = e.ConflictingItems.FirstOrDefault ().Id; System.Console.WriteLine ($"Found existing folder: {folderId}"); } var fileUploadTasks = new List<Task<BoxFile>> (); foreach (var file in files) { fileUploadTasks.Add (Task.Run ( async () => { System.Console.WriteLine (file); var fileName = file.Split (Path.DirectorySeparatorChar) .Where ((item) => { return item != directoryName; }).FirstOrDefault (); System.Console.WriteLine (fileName); var fileInfo = new FileInfo (file); var preflightRequest = new BoxPreflightCheckRequest { Name = fileName, Size = fileInfo.Length, Parent = new BoxRequestEntity { Id = folderId } }; using (FileStream toUpload = new FileStream (file, FileMode.Open)) { try { var preflightCheck = await client.FilesManager.PreflightCheck (preflightRequest); if (toUpload.Length < CHUNKED_UPLOAD_MINIMUM) { using (SHA1 sha1 = SHA1.Create ()) { var fileUploadRequest = new BoxFileRequest { Name = fileName, Parent = new BoxRequestEntity { Id = folderId } }; var fileSHA = sha1.ComputeHash (toUpload); System.Console.WriteLine (fileSHA); return await client.FilesManager.UploadAsync (fileRequest: fileUploadRequest, stream: toUpload, contentMD5: fileSHA); } } else { return await client.FilesManager.UploadUsingSessionAsync (stream: toUpload, fileName: fileName, folderId: folderId); } } catch (BoxPreflightCheckConflictException<BoxFile> e) { if (toUpload.Length < CHUNKED_UPLOAD_MINIMUM) { using (SHA1 sha1 = SHA1.Create ()) { var fileSHA = sha1.ComputeHash (toUpload); return await client.FilesManager.UploadNewVersionAsync (fileName: e.ConflictingItem.Name, fileId: e.ConflictingItem.Id, stream: toUpload, contentMD5: fileSHA); } } else { await client.FilesManager.UploadFileVersionUsingSessionAsync (fileId: e.ConflictingItem.Id, stream: toUpload); return await client.FilesManager.GetInformationAsync (e.ConflictingItem.Id); } } } })); } var uploaded = await Task.WhenAll (fileUploadTasks); foreach (var file in uploaded) { System.Console.WriteLine (file.Id); } } } } } ``` ``` public class UploadAllFilesInFolder { public static final int CHUNKED_UPLOAD_MINIMUM = 20000; public static void main(String[] args) throws Exception { String directoryName = "javaUploadFolder"; Path configPath = Paths.get("config.json"); Path uploadFolderPath = Paths.get(directoryName); try (BufferedReader reader = Files.newBufferedReader(configPath, Charset.forName("UTF-8"))) { BoxConfig boxConfig = BoxConfig.readFrom(reader); BoxDeveloperEditionAPIConnection client = BoxDeveloperEditionAPIConnection.getAppEnterpriseConnection(boxConfig); String parentFolderId = "0"; String createdFolderId; BoxFolder createFolderInParentFolder = new BoxFolder(client, parentFolderId); try { BoxFolder.Info createdFolder = createFolderInParentFolder.createFolder(directoryName); System.out.println("Creating folder..."); System.out.println(createdFolder.getID()); createdFolderId = createdFolder.getID(); } catch (BoxAPIException e) { String existingFolderId = getIdFromConflict(e.getMessage()); System.out.println("Found existing folder..."); System.out.println(existingFolderId); createdFolderId = existingFolderId; } ArrayList < BoxFile.Info > uploadedFiles = new ArrayList < > (); try (DirectoryStream < Path > directory = Files.newDirectoryStream(uploadFolderPath)) { for (Path path: directory) { String fileName = path.getFileName().toString(); System.out.println(path); System.out.println(fileName); byte[] fileBytes = Files.readAllBytes(path); int fileSize = fileBytes.length; boolean useChunkedUpload = (fileSize > CHUNKED_UPLOAD_MINIMUM) ? true : false; uploadedFiles.add(uploadEachFile(client, createdFolderId, fileName, fileSize, fileBytes, useChunkedUpload)); } } for (BoxFile.Info file: uploadedFiles) { System.out.println(file.getID()); } } } private static BoxFile.Info uploadEachFile(BoxDeveloperEditionAPIConnection client, String folderId, String fileName, int fileSize, byte[] fileBytes, boolean useChunkedUpload) throws IOException, InterruptedException, NoSuchAlgorithmException { try { BoxFolder folder = new BoxFolder(client, folderId); folder.canUpload(fileName, fileSize); if (useChunkedUpload) { System.out.println("Using chunked upload..."); return folder.uploadLargeFile(new ByteArrayInputStream(fileBytes), fileName, fileSize); } else { System.out.println("Using normal upload..."); MessageDigest md = MessageDigest.getInstance("SHA-1"); try (Formatter formatter = new Formatter()) { for (byte b: md.digest(fileBytes)) { formatter.format("%02x", b); } String fileSHA = formatter.toString(); FileUploadParams fileUpload = new FileUploadParams(); fileUpload.setContent(new ByteArrayInputStream(fileBytes)); fileUpload.setSHA1(fileSHA); fileUpload.setName(fileName); return folder.uploadFile(fileUpload); } } } catch (BoxAPIException e) { if (e.getResponseCode() == 409) { // You can use the ID returned from the conflict error to continue String conflictId = getIdFromConflict(e.getResponse()); System.out.println("Found existing file: " + conflictId); BoxFile uploadFileVersion = new BoxFile(client, conflictId); if (useChunkedUpload) { System.out.println("Using chunked upload..."); return uploadFileVersion.uploadLargeFile(new ByteArrayInputStream(fileBytes), fileSize); } else { System.out.println("Using normal upload..."); MessageDigest md = MessageDigest.getInstance("SHA-1"); try (Formatter formatter = new Formatter()) { for (byte b: md.digest(fileBytes)) { formatter.format("%02x", b); } String fileSHA = formatter.toString(); uploadFileVersion.uploadVersion(new ByteArrayInputStream(fileBytes), fileSHA); return uploadFileVersion.getInfo(); } } } else { throw e; } } } private static String getIdFromConflict(String message) { String id = ""; Pattern p = Pattern.compile("\"id\":\"[0-9]+\""); Pattern p2 = Pattern.compile("[0-9]+"); Matcher m = p.matcher(message); if (m.find()) { String sub = m.group(); Matcher m2 = p2.matcher(sub); if (m2.find()) { id = m2.group(); } } return id; } } ``` ``` "use strict"; const fs = require("fs"); const path = require("path"); const box = require("box-node-sdk"); const crypto = require("crypto"); let configFile = fs.readFileSync("config.json"); configFile = JSON.parse(configFile); let session = box.getPreconfiguredInstance(configFile); let client = session.getAppAuthClient("enterprise"); const CHUNKED_UPLOAD_MINIMUM = 200000; const parentFolderId = "0"; const directoryName = "uploadFolder"; let files = []; fs.readdirSync(directoryName).forEach(file => { files.push({ fileName: file, content: fs.readFileSync(path.join(__dirname, directoryName, file)) }); }); client.folders .create(parentFolderId, directoryName) .then(createdFolder => { console.log(createdFolder); return processFiles(client, files, createdFolder.id); }) .catch(err => { let conflictId = handleFolderConflictError(err); if (conflictId) { console.log(`Found an existing folder: ${conflictId}`); return processFiles(client, files, conflictId); } else { throw err; } }) .then(results => { console.log(results); }) .catch(err => { console.log(err); }); function processFiles(client, files, folderId) { let fileUploadPromises = []; files.forEach(file => { fileUploadPromises.push( uploadAFile(client, folderId, file.fileName, file.content) ); }); return Promise.all(fileUploadPromises); } function uploadAFile(client, folderId, fileName, toUploadFile) { return client.files .preflightUploadFile(folderId, { name: fileName, size: toUploadFile.length }) .then(preflightResults => { console.log(preflightResults); if (toUploadFile.length < CHUNKED_UPLOAD_MINIMUM) { console.log("Using normal upload..."); let fileSha = crypto .createHash("sha1") .update(toUploadFile) .digest("hex"); client.setCustomHeader("content-md5", fileSha); return client.files.uploadFile(folderId, fileName, toUploadFile); } else { console.log("Using chunked upload..."); client.setCustomHeader("content-md5", null); return client.files .getChunkedUploader( folderId, toUploadFile.length, fileName, toUploadFile ) .then(uploader => { return new Promise((resolve, reject) => { uploader.on("error", err => { reject(err); }); uploader.on("chunkUploaded", part => { console.log("Part uploaded..."); console.log(part); }); uploader.on("uploadComplete", file => { console.log("File upload complete!"); resolve(file); }); console.log("Starting chunked uploader..."); uploader.start(); }); }); } }) .catch(err => { let conflictId = handleFileConflictError(err); if (conflictId) { console.log(`Found existing file with that name: ${conflictId}`); return uploadANewFileVersion(client, conflictId, toUploadFile); } else { throw err; } }); } function uploadANewFileVersion(client, conflictId, toUploadFile) { if (toUploadFile.length < CHUNKED_UPLOAD_MINIMUM) { console.log("Using normal upload..."); let fileSha = crypto .createHash("sha1") .update(toUploadFile) .digest("hex"); client.setCustomHeader("content-md5", fileSha); // You can optionally rename a folder while uploading a new version. // let newFileName = "ubuntu-no-gui.iso"; // let options = { // name: newFileName // } // return client.files.uploadNewFileVersion(conflictId, options, toUploadFile); return client.files.uploadNewFileVersion(conflictId, toUploadFile); } else { console.log("Using chunked upload..."); // You can optionally rename a folder while uploading a new version. // let newFileName = "ubuntu-no-gui.iso"; // let options = { // name: newFileName // } // return client.files.getNewVersionChunkedUploader(conflictId, toUploadFile.length, toUploadFile, options) client.setCustomHeader("content-md5", null); return client.files .getNewVersionChunkedUploader( conflictId, toUploadFile.length, toUploadFile, null ) .then(uploader => { return new Promise((resolve, reject) => { uploader.on("error", err => { reject(err); }); uploader.on("chunkUploaded", part => { console.log("Part uploaded..."); console.log(part); }); uploader.on("uploadComplete", file => { console.log("File upload complete!"); resolve(file); }); console.log("Starting chunked uploader..."); uploader.start(); }); }); } } function handleFileConflictError(e) { if (e && e.response && e.response.body) { let errorBody = e.response.body; if (errorBody.status === 409) { if ( errorBody.context_info && errorBody.context_info.conflicts && errorBody.context_info.conflicts ) { let conflict = errorBody.context_info.conflicts; if (conflict && conflict.id) { return conflict.id; } } } } } function handleFolderConflictError(e) { if (e && e.response && e.response.body) { let errorBody = e.response.body; if (errorBody.status === 409) { if ( errorBody.context_info && errorBody.context_info.conflicts && errorBody.context_info.conflicts.length > 0 ) { let conflict = errorBody.context_info.conflicts[0]; if (conflict && conflict.id) { return conflict.id; } } } } } ``` ``` box folders:upload ./folder_name_to_upload --parent-folder=$folder_id ``` ## 解説 上のスクリプトは、Box SDKとCLIを使用してフォルダ全体をアップロードします。このSDKスクリプトでは、最初にローカルフォルダに対応するディレクトリをBox内に作成します。 新しいディレクトリが作成されたら、ディレクトリ内のすべてのファイルをアップロードし、利用可能なすべてのBox機能を使用してアップロードを確実に成功させます。 アップロードの前に、[事前チェック](g://uploads/check)APIを使用してファイルの競合とサイズ制限をチェックします。名前の競合が見つかった場合、代わりにそのファイルの新しいバージョンをアップロードします。 ファイルの`SHA`ハッシュを使用して、アップロード時に`content-md5`ヘッダーを追加することで、ファイルのデータが失われたり改変されたりすることなくBoxに正常にアップロードされるようにします。 最後に、ファイルサイズが20 MBを超える場合、[分割アップロード](g://uploads/chunked)機能を使用して、大きいファイルのアップロードの信頼性を高めます。 **Source:** [https://ja.developer.box.com/guides/uploads/chunked/folder/](https://ja.developer.box.com/guides/uploads/chunked/folder/) --- ### フォルダ内のすべての項目に対するメタデータの強制適用 **Type:** guide | **Category:** メタデータ | **Section:** Developer Guides フォルダ内のすべての項目に対するメタデータの強制適用 メタデータカスケードポリシーがすでにフォルダに存在する場合は、メタデータカスケードポリシーのidを指定してPOST /metadata_cascade_policies/:id/apply API… # フォルダ内のすべての項目に対するメタデータの強制適用 メタデータカスケードポリシーがすでにフォルダに存在する場合は、メタデータカスケードポリシーの`id`を指定して[`POST /metadata_cascade_policies/:id/apply`](e://post_metadata_cascade_policies_id_apply) APIエンドポイントを呼び出すことで、フォルダ内のすべての項目にメタデータインスタンスを強制的に適用できます。 ポリシーの`id`を取得するには、フォルダに対する[すべてのポリシーのリストを取得](g://metadata/cascades/list)します。 メタデータカスケード操作は非同期的に開始されます。このAPIコールは、カスケード操作が完了する前に直ちに復帰し、`202 Accepted` HTTPステータスコードを返します。現時点では、この操作がいつ終了したのかを確認する方法はありません。 ## 競合解決 このAPIに追加の`conflict_resolution`パラメータを渡すことで、フォルダ内のいずれかの項目でテンプレートの既存のインスタンスを扱う方法を定義できます。 `conflict_resolution`に値を設定していない場合、デフォルトでは、このAPIによってすべての項目の既存の値が保持されます。値を`overwrite`に設定すると、カスケードポリシーに適用されているテンプレートの値が強制的に適用され、既存の値は上書きされます。 **Source:** [https://ja.developer.box.com/guides/metadata/cascades/force-apply/](https://ja.developer.box.com/guides/metadata/cascades/force-apply/) --- ### フォルダ名の変更 **Type:** guide | **Category:** フォルダ | **Section:** Developer Guides フォルダ名の変更 Box上でフォルダの名前を変更するには、そのフォルダの新しいnameをAPIに渡す必要があります。 名前に関する制約事項 フォルダ名にはいくつかの制限があります。印字不可能なASCII… # フォルダ名の変更 Box上でフォルダの名前を変更するには、そのフォルダの新しい`name`をAPIに渡す必要があります。 # 名前に関する制約事項 フォルダ名にはいくつかの制限があります。印字不可能なASCII文字、スラッシュ、バックスラッシュ (`/`、`\`) を含む名前のほか、末尾にスペースを含む名前は禁止されています。 また、`.`および`..`は予約済みの名前であるため、使用できません。 **Source:** [https://ja.developer.box.com/guides/folders/single/rename/](https://ja.developer.box.com/guides/folders/single/rename/) --- ### フォルダ所有者の変更 **Type:** guide | **Category:** フォルダ | **Section:** Developer Guides フォルダ所有者の変更 フォルダの所有者を変更するには、まず、フォルダの移行先となるユーザーをフォルダのコラボレータとして招待します。 次に、招待したユーザーのロールをowner… # フォルダ所有者の変更 フォルダの所有者を変更するには、まず、フォルダの移行先となるユーザーをフォルダのコラボレータとして招待します。 次に、招待したユーザーのロールを`owner`に変更して、作成したコラボレーションを更新します。 ``` curl -X PUT https://api.box.com/2.0/collaborations/1234 \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -H "content-type: application/json" \ -d '{ "role": "owner" }' ``` ``` BoxCollaborationRequest requestParams = new BoxCollaborationRequest() { Id = "12345", Role = "owner" }; BoxCollaboration collab = await client.CollaborationsManager.EditCollaborationAsync(requestParams); ``` ``` Collection<BoxCollaboration.Info> pendingCollaborations = BoxCollaboration.getPendingCollaborations(api); for (BoxCollaboration.Info collabInfo : pendingCollaborations) { collabInfo.setRole(BoxCollaboration.Role.OWNER); collabInfo.getResource().updateInfo(collabInfo); } ``` ``` from boxsdk.object.collaboration import CollaborationRole, CollaborationStatus collaboration = client.collaboration(collab_id='12345') updated_collaboration = collaboration.update_info(CollaborationRole.OWNER) ``` ``` client.collaborations.update('12345', {role: client.collaborationRoles.OWNER}) .then(collaboration => { // ... }); ``` 設定によっては、フォルダへのアクセス権限を持つユーザーが他のユーザーを招待できることもありますが、いかなる場合でも、所有権を移管できるのは、フォルダの現在の所有者のみです。 **Source:** [https://ja.developer.box.com/guides/folders/single/change-owner/](https://ja.developer.box.com/guides/folders/single/change-owner/) --- ### ブラウザでのダウンロード **Type:** guide | **Category:** ダウンロード | **Section:** Developer Guides ブラウザでのダウンロード アプリケーションでは、ファイルをHTML要素としてページに埋め込む場合があります。たとえば、オーディオプレーヤーを使用する場合です。 この場合、通常のダウンロードURLを使用しても機能しません。dl.boxcloud.com… # ブラウザでのダウンロード アプリケーションでは、ファイルをHTML要素としてページに埋め込む場合があります。たとえば、オーディオプレーヤーを使用する場合です。 ``` <audio controls> <source src="..." type="audio/mp3"> </audio> ``` この場合、通常の[ダウンロードURL](g://downloads/get-url)を使用しても機能しません。`dl.boxcloud.com`ドメインでは[クロスオリジンリソース共有](g://security/cors)がサポートされていないためです。 その代わり、アプリケーションでは次の形式を使用できます。 ``` https://api.box.com/2.0/files/[FILE_ID]/content?access_token=[ACCESS_TOKEN] ``` # CORS これを機能させるために、アプリケーションでは、このファイルをホストするウェブサイトのドメインを[CORSの設定](g://security/cors)で許可されたドメインのリストに追加しておく必要があります。 # トークンのダウンスコープ この方法を使用すると、アクセストークンがエンドユーザーに公開され、エンドユーザーはこのトークンを使用すると、意図したより多くの操作を行うことができる可能性があります。そのため、状況に応じてこのトークンを[ダウンスコープ](g://authentication/tokens/downscope)することをお勧めします。 **Source:** [https://ja.developer.box.com/guides/downloads/in-browser/](https://ja.developer.box.com/guides/downloads/in-browser/) --- ### ブラウザのサポート **Type:** guide | **Category:** Boxの埋め込み | **Section:** Developer Guides ブラウザのサポート Box UI Elementsは、以下のブラウザでサポートされています。 Chrome、Firefox、Safari、およびEdge (直近の2バージョン) Mobile ChromeおよびSafari # ブラウザのサポート Box UI Elementsは、以下のブラウザでサポートされています。 - Chrome、Firefox、Safari、およびEdge (直近の2バージョン) - Mobile ChromeおよびSafari **Source:** [https://ja.developer.box.com/guides/embed/ui-elements/browser/](https://ja.developer.box.com/guides/embed/ui-elements/browser/) --- ### プレビュー - ビューアーとイベント **Type:** guide | **Category:** Boxの埋め込み | **Section:** Developer Guides プレビュー - ビューアーとイベント このページでは、ファイルタイプごとのプレビュー機能について説明します。また、ビューアーの種類別にリッスンできるイベントのリストも示します。 テキストビューアー テキストビューアーでは、テキストファイルのプレビューがレンダリングされます。py… # プレビュー - ビューアーとイベント このページでは、ファイルタイプごとのプレビュー機能について説明します。また、ビューアーの種類別にリッスンできるイベントのリストも示します。 ## テキストビューアー テキストビューアーでは、テキストファイルのプレビューがレンダリングされます。`py`や`rb`のようなコードファイルの場合は、構文のハイライトを追加するために[`highlight.js`](https://github.com/isagalaev/highlight.js)が使用されます。 ### 動作 テキストビューアーには、ファイル内のテキストのうち最初の192KBが表示されます。その他のテキストは省略され、通知とダウンロードボタンがプレビューの最下部に追加されます。 ビューアーウィンドウのサイズを変更すると、使用可能なスペースに収まるようテキストの再流し込みが行われます。また、拡大ボタンと縮小ボタンにより、フォントサイズがそれぞれ縮小または拡大されます。 このビューアーでは印刷がサポートされており、`print()`が呼び出されるか印刷ボタンが押されると、適切な構文をハイライトした状態で印刷が行われます。サイズの大きなファイルを印刷すると、一部のブラウザでは数秒間動作が停止する場合があります。 ### コントロール - 拡大 - 縮小 - 全画面: Escキーを押すと終了可能 ### サポートされているファイル拡張子 `as`, `as3as`, `asmas`, `batas`, `cas`, `ccas`, `cmakeas`, `cppas`, `csas`, `cssas`, `cxxas`, `diffas`, `erbas`, `groovyas`, `has`, `hamlas`, `hhas`, `htmas`, `htmlas`, `javaas`, `jsas`, `lessas`, `mas`, `makeas`, `mdas`, `mlas`, `mmas`, `phpas`, `plas`, `plistas`, `propertiesas`, `pyas`, `rbas`, `rstas`, `sassas`, `scalaas`, `scriptas`, `scmas`, `smlas`, `sqlas`, `shas`, `vias`, `vimas`, `webdocas`, `xhtmlas`, `yaml`, ### イベント テキストビューアーでは、以下のイベントがトリガーされます。 | イベント名 | 説明 | イベントデータ | | --- | --- | --- | | destroy | プレビューは意図的に破棄されます。 | | | load | プレビューが読み込まれます。 | 1. {string} error (省略可): エラーメッセージ | | | | 2. {object} file: 現在のファイル | | | | 3. {object} metrics: ロガーからの情報 | | | | 4. {object} viewer: 現在のビューアー | | notification | 通知が表示されます。 | | | navigate | 指定したインデックスのプレビューが表示されます。 | {object}ファイル | | reload | プレビューが再読み込みされます。 | | | resize | プレビューのサイズが変更されます。 | 1. {number} height: ウィンドウの高さ | | | | 2. {number} width: ウィンドウの幅 | | zoom | プレビューが拡大または縮小されます。 | 1. {number} zoom: 新しい拡大/縮小値 | | | | 2. {boolean} canZoomIn: trueにするとビューアーをさらに拡大可能 | | | | 3. {boolean} canZoomOut: trueにするとビューアーをさらに縮小可能 | | printsuccess | 印刷が正常に開始されました。 | | ## 360度動画ビューアー 360度動画ビューアーでは、正距円筒図法を使用して保存された動画 (ほとんどの場合に360度カメラで撮影) のプレビューがレンダリングされます。 ### 動作 このビューアーでは、360度動画がインタラクティブに表示されます。 ### コントロール - マウスの左ボタンで表示方向を変更します (タッチ対応デバイスでは1回タッチ)。 ### VRボタン WebVRをサポートするブラウザの使用時に、対応するVRデバイスがコンピュータに接続されると、VRボタンを使用して、VRモードの開始と終了を切り替えることができます。 ### 制限 現在、このプレビューアーを使用するには、ファイルの名前を付ける際にファイル拡張子の前に`.360`を付ける必要があります。こうすることで、Preview SDKは、標準の動画プレビューではなく、このビューアーを実行することを認識します。 ### サポートされているファイル拡張子 `360.3g2`, `360.3gp`, `360.avi`, `360.m2v`, `360.m2ts`, `360.m4v`, `360.mkv`, `360.mov`, `360.mp4`, `360.mpeg`, `360.mpg`, `360.mts`, `360.qt`, `360.wmv` ### イベント 360度動画ビューアーでは、以下のイベントがトリガーされます。 | イベント名 | 説明 | イベントデータ | | --- | --- | --- | | destroy | プレビューは意図的に破棄されます。 | | | load | プレビューが読み込まれます。 | 1. {string} error (省略可): エラーメッセージ | | | | 2. {object} file: 現在のファイル | | | | 3. {object} metrics: ロガーからの情報 | | | | 4. {object} viewer: 現在のビューアー | | notification | 通知が表示されます。 | | | navigate | 指定したインデックスのプレビューが表示されます。 | {object}ファイル | | reload | プレビューが再読み込みされます。 | | | resize | プレビューのサイズが変更されます。 | 1. {number} height: ウィンドウの高さ | | | | 2. {number} width: ウィンドウの幅 | ## SWFビューアー SWFビューアーは、[`SWFObject`](https://github.com/swfobject/swfobject)を使用してSWFファイルを埋め込みます。 ### 動作 ユーザーがAdobe Flash Playerプラグインを使用している場合、`SWFObject`はSWFファイルを埋め込み、このプラグインで関連するコンテンツをレンダリングできるようにします。 Flashコンテンツによるネットワークリクエストはすべて、セキュリティの制約によってブロックされるため、ネットワーク接続を必要とするコンテンツはレンダリングされないことに注意してください。 ### サポートされているファイル拡張子 - `swf` ### イベント SWFビューアーでは、以下のイベントがトリガーされます。 | イベント名 | 説明 | イベントデータ | | --- | --- | --- | | destroy | プレビューは意図的に破棄されます。 | | | load | プレビューが読み込まれます。 | 1. {string} error (省略可): エラーメッセージ | | | | 2. {object} file: 現在のファイル | | | | 3. {object} metrics: ロガーからの情報 | | | | 4. {object} viewer: 現在のビューアー | | notification | 通知が表示されます。 | | | navigate | 指定したインデックスのプレビューが表示されます。 | {object}ファイル | | reload | プレビューが再読み込みされます。 | | | resize | プレビューのサイズが変更されます。 | 1. {number} height: ウィンドウの高さ | | | | 2. {number} width: ウィンドウの幅 | ## プレゼンテーションビューアー プレゼンテーションビューアーでは、PowerPointファイルのプレビューがレンダリングされます。 ### 動作 プレゼンテーションビューアーには、プレビューを閉じるときに表示していたスライドが記憶されます。次回そのファイルを開くと、すぐにそのスライドが表示されます。マウスで上下にスクロールするか、モバイルデバイスで上下にスワイプすると、スライド間を移動します。ビューアーを拡大または縮小すると、スライドのサイズもそれぞれ拡大または縮小されます。ズームレベルが原因でコンテンツがはみ出す場合は、マウスをスクロールすると、スライドをスクロールできます。通常のスクロール動作に戻すには、はみ出さなくなるまで縮小する必要があります。 ### コントロール - 拡大 - 縮小 - ページの設定: 上矢印と下矢印を使用するか、ページ番号をクリックしてテキストを入力します。 - 全画面: Escキーを押すと終了可能 ### サポートされているファイル拡張子 `ppt`, `pptx`, `odp` ### オプション | オプション | 型 | 説明 | | --- | --- | --- | | annotations | boolean | 省略可。コンテンツの注釈を表示するかどうか。デフォルト値はfalseです。 | ### イベント プレゼンテーションビューアーでは、以下のイベントがトリガーされます。 | イベント名 | 説明 | イベントデータ | | --- | --- | --- | | destroy | プレビューは意図的に破棄されます。 | | | load | プレビューが読み込まれます。 | 1. string error (省略可): エラーメッセージ | | | | 2. object file: 現在のファイル | | | | 3. object metrics: ロガーからの情報 | | | | 4. object viewer: 現在のビューアー | | notification | 通知が表示されます。 | | | navigate | 指定したインデックスのプレビューが表示されます。 | objectファイル | | reload | プレビューが再読み込みされます。 | | | resize | プレビューのサイズが変更されます。 | 1. number height: ウィンドウの高さ | | | | 2. number width: ウィンドウの幅 | | zoom | プレビューが拡大または縮小されます。 | 1. number zoom: 新しい拡大/縮小値 | | | | 2. boolean canZoomIn: trueにするとビューアーをさらに拡大可能 | | | | 3. boolean canZoomOut: trueにするとビューアーをさらに縮小可能 | | pagerender | ページがレンダリングされます。 | number レンダリングされたページのページ番号 | | pagefocus | ページが表示可能です。 | number フォーカスされたページのページ番号 | | scrollstart | ビューアーでスクロールを開始します。 | 1. number scrollTop: ビューポートの上部からスクロールしたピクセル数 | | | | 2. number scrollLeft: ビューポートの左側からスクロールしたピクセル数 | | scrollend | ビューアーでスクロールを停止します。 | 1. number scrollTop: ビューポートの上部からスクロールしたピクセル数 | | | | 2. number scrollLeft: ビューポートの左側からスクロールしたピクセル数 | ## MP4ビューアー MP4ビューアーでは、動画ファイルのプレビューがレンダリングされます。 ### 動作 MP4ビューアーは、黒い背景を使用して見やすくしています。音量は、音量アイコンをクリックしてミュートまたはミュート解除したり、音量スクラバをドラッグして変更したりできます。動画の位置は、再生スクラバをクリックまたはドラッグして変更できます。 ### コントロール - 再生/一時停止 - 音量 - 設定 - 全画面 (Escキーを押すと終了可能) ### 設定 設定は、プレビューツールバーにある歯車アイコンから使用できます。 - 動画速度の値: `0.25`、`0.5`、標準 (`1`)、`1.25`、`1.5`、`2.0` ### サポートされているファイル拡張子 `3g2`, `3gp`, `avi`, `m2v`, `m2ts`, `m4v`, `mkv`, `mov`, `mp4`, `mpeg`, `mpg`, `ogg`, `mts`, `qt`, `wmv` ### イベント MP4ビューアーでは、以下のイベントがトリガーされます。 | イベント名 | 説明 | イベントデータ | | --- | --- | --- | | destroy | プレビューは意図的に破棄されます。 | | | load | プレビューが読み込まれます。 | 1. string error (省略可): エラーメッセージ | | | | 2. object file: 現在のファイル | | | | 3. object metrics: ロガーからの情報 | | | | 4. object viewer: 現在のビューアー | | notification | 通知が表示されます。 | | | navigate | 指定したインデックスのプレビューが表示されます。 | objectファイル | | reload | プレビューが再読み込みされます。 | | | resize | プレビューのサイズが変更されます。 | 1. number height: ウィンドウの高さ | | | | 2. number width: ウィンドウの幅 | | speedchange | メディアの速度が変更されます。 | string 再生速度 | | play | 動画が再生されます。 | | | pause | 動画が一時停止されます。 | | | seek | 動画は任意の時点までスキップします。 | number 時刻 | ## MP3ビューアー MP3ビューアーでは、オーディオファイルのプレビューが表示されます。 ### 動作 音量は、音量アイコンをクリックしてミュートまたはミュート解除したり、音量スクラバをドラッグして変更したりできます。音声の位置は、再生スクラバをクリックまたはドラッグして変更できます。 ### コントロール - 再生/一時停止 - 音量 - 設定 ### 設定 設定は、プレビューツールバーにある歯車アイコンから使用できます。 - 音声速度: `0.25`、`0.5`、標準 (`1`)、`1.25`、`1.5`、`2.0` ### サポートされているファイル拡張子 `aac`, `aif`, `aifc`, `aiff`, `amr`, `au`, `flac`, `m4a`, `mp3`, `ra`, `wav`, `wma` ### イベント MP3ビューアーでは、以下のイベントがトリガーされます。 | イベント名 | 説明 | イベントデータ | | --- | --- | --- | | destroy | プレビューは意図的に破棄されます。 | | | load | プレビューが読み込まれます。 | 1. string error (省略可): エラーメッセージ | | | | 2. object file: 現在のファイル | | | | 3. object metrics: ロガーからの情報 | | | | 4. object viewer: 現在のビューアー | | notification | 通知が表示されます。 | | | navigate | 指定したインデックスのプレビューが表示されます。 | objectファイル | | reload | プレビューが再読み込みされます。 | | | resize | プレビューのサイズが変更されます。 | 1. number height: ウィンドウの高さ | | | | 2. number width: ウィンドウの幅 | | speedchange | メディアの速度が変更されます。 | string 再生速度 | | play | 動画が再生されます。 | | | pause | 動画が一時停止されます。 | | | seek | 動画は任意の時点までスキップします。 | number 時刻 | ## Officeビューアー Officeビューアーでは、MicrosoftのOffice Onlineビューアーの`<iframe>`を埋め込むことで、Microsoft Officeドキュメントのプレビューをレンダリングします。 ### 動作 現在、Officeビューアーでは、Boxウェブアプリ内からMicrosoft Office Onlineを使用したExcelファイルのプレビューがサポートされています。プラットフォームのユースケースおよび他のOfficeファイル形式のサポートは開発中です。 現時点では、次のように、いくつかの制限があります。 - ファイルはダウンロード可能にする必要があります。 - ファイルのサイズは5 MB未満にする必要があります。 - ファイルは、パスワード付きのBox共有リンクで共有できません (パスワードのない共有リンクは問題ありません)。 ### サポートされているファイル拡張子 `xlsx` ### イベント Officeビューアーでは、以下のイベントがトリガーされます。 | イベント名 | 説明 | イベントデータ | | --- | --- | --- | | destroy | プレビューは意図的に破棄されます。 | | | load | プレビューが読み込まれます。 | 1. {string} error (省略可): エラーメッセージ | | | | 2. {object} file: 現在のファイル | | | | 3. {object} metrics: ロガーからの情報 | | | | 4. {object} viewer: 現在のビューアー | | notification | 通知が表示されます。 | | | navigate | 指定したインデックスのプレビューが表示されます。 | {object}ファイル | | reload | プレビューが再読み込みされます。 | | | resize | プレビューのサイズが変更されます。 | 1. {number} height: ウィンドウの高さ | | | | 2. {number} width: ウィンドウの幅 | ## Markdownビューアー Markdownビューアーでは、[`Remarkable`](https://github.com/jonschlinkert/remarkable)を使用してマークダウンファイルと[`highlight.js`](https://github.com/isagalaev/highlight.js)を解析し、ビューアーに表示されるコードブロックに構文のハイライトを追加します。 ### 動作 Markdownビューアーでは、ファイル内の未加工のマークダウンのうち最初の192KBを解析し、GitHubのMarkdownスタイルを使用してレンダリングします。その他のコンテンツは省略され、ダウンロードボタンとともに通知がプレビューの最下部に追加されます。 このビューアーは、テーブル、構文のハイライト、自動URLリンクなど、[GitHub Flavored Markdown](https://guides.github.com/features/mastering-markdown/)をサポートします。 ビューアーウィンドウのサイズを変更すると、使用可能なスペースに収まるようマークダウンの再流し込みが行われます。また、このビューアーでは印刷がサポートされており、解析されたマークダウンが印刷されます。さらに、`print()`が呼び出されるか印刷ボタンが押されると、コード上で構文がハイライトされます。サイズの大きなファイルを印刷すると、一部のブラウザでは数秒間動作が停止する場合があります。 ### コントロール - 全画面 (Escキーを押すと終了可能) ### サポートされているファイル拡張子 `md` ### イベント Markdownビューアーでは、以下のイベントがトリガーされます。 | イベント名 | 説明 | イベントデータ | | --- | --- | --- | | destroy | プレビューは意図的に破棄されます。 | | | load | プレビューが読み込まれます。 | 1. {string} error (省略可): エラーメッセージ | | | | 2. {object} file: 現在のファイル | | | | 3. {object} metrics: ロガーからの情報 | | | | 4. {object} viewer: 現在のビューアー | | notification | 通知が表示されます。 | | | navigate | 指定したインデックスのプレビューが表示されます。 | {object}ファイル | | reload | プレビューが再読み込みされます。 | | | resize | プレビューのサイズが変更されます。 | 1. {number} height: ウィンドウの高さ | | | | 2. {number} width: ウィンドウの幅 | | printsuccess | 印刷が正常に開始されました。 | | ## Model3Dビューアー `Model3D`ビューアーでは、3Dモデルファイルのプレビューがレンダリングされるほか、各種レンダリングモードを有効にして、ワイヤフレームやテクスチャ座標など、モデルのさまざまな側面を調査できます。また、アニメーションデータは、それを含むファイル (`box3d`、`fbx`、`dae`など) でサポートされています。 ### 動作 `Model3D`ビューアーでは、モデルがインタラクティブに表示されます。マウスの左ボタンを使用すると、モデルを回転させることができます (タッチ対応デバイスでは1回タッチ)。モデルの任意の場所をクリックすると、軌道のフォーカスを変更できます。 ### コントロール - マウスホイールを使用 (またはタッチ対応デバイスの場合は2本指でスクロール) して拡大/縮小 (モデルまでの距離を変更)。 - マウスの右ボタンを使用 (またはタッチ対応デバイスの場合は3本指でスワイプ) して平行移動 (横方向の移動)。 - アニメーションの選択: 表示中のモデルにアニメーションが含まれている場合、ツールバーには2つのアニメーションボタンが表示されます。1つはアニメーションを再生/一時停止できるボタン、もう1つは現在のアニメーションを選択できるボタンです。 - VRボタン: WebVRをサポートするブラウザを使用していて、対応するVRデバイスがコンピュータに接続された場合、VRボタンを使用すると、VRモードの開始と終了を切り替えることができます。 ### 設定 設定は、プレビューツールバーにある歯車アイコンから使用できます。 - レンダリングモード: ライティングあり、ライティングなし、標準、シェイプ、UVオーバーレイ - ワイヤフレームの切り替え - スケルトンの切り替え - カメラ投影: 透視投影、平行投影 - レンダリング品質: 自動、詳細 - モデルの回転: X、Y、Z ## Box3Dパッケージ プレビューを使用すると、ユーザーはBox内に1つのファイルを表示できるため、デフォルトでは、モデルでテクスチャを表示できません。ただし、Boxウェブアプリを使用すると、ユーザーは、Box3Dパッケージを作成できます。このパッケージでは、依存するすべてのファイルが、共有およびプレビュー可能な1つファイルに統合されます。このパッケージを作成するには、Box内でモデルファイルを右クリックし、[3Dパッケージの作成] を選択します。Box内にある参照ファイルはすべて、作成されるパッケージに含まれます。 ### サポートされているファイル拡張子 `box3d`, `fbx`, `dae`, `3ds`, `obj`, `stl`, `ply` ### イベント `Model3D`ビューアーでは、以下のイベントがトリガーされます。 | イベント名 | 説明 | イベントデータ | | --- | --- | --- | | destroy | プレビューは意図的に破棄されます。 | | | load | プレビューが読み込まれます。 | 1. {string} error (省略可): エラーメッセージ | | | | 2. {object} file: 現在のファイル | | | | 3. {object} metrics: ロガーからの情報 | | | | 4. {object} viewer: 現在のビューアー | | notification | 通知が表示されます。 | | | navigate | 指定したインデックスのプレビューが表示されます。 | {object}ファイル | | reload | プレビューが再読み込みされます。 | | | resize | プレビューのサイズが変更されます。 | 1. {number} height: ウィンドウの高さ | | | | 2. {number} width: ウィンドウの幅 | ## 360度画像ビューアー 360度画像ビューアーでは、正距円筒図法を使用して保存された画像 (ほとんどの場合に360度カメラで撮影) のプレビューがレンダリングされます。 ### 動作 このビューアーでは、360度画像がインタラクティブに表示されます。まず、低解像度バージョンの画像が読み込まれ、フル解像度の画像の読み込みが終了するまで簡易表示されます。マウスの左ボタンでクリックしてドラッグすると、表示方向が変更されます (タッチ対応デバイスでは1回タッチしてドラッグ)。 ### コントロール - 全画面 (Escキーを押すと終了可能) - VRボタン: WebVRをサポートするブラウザの使用時に、対応するVRデバイスがコンピュータに接続されると、VRボタンを使用して、VRモードの開始と終了を切り替えることができます。 ### 制限 現在、このプレビューアーを使用するには、ファイルの名前を付ける際にファイル拡張子の前に「.360」を付ける必要があります。こうすることで、Preview SDKは、標準の画像ビューアーではなく、このビューアーを実行することを認識します。 ### サポートされているファイル拡張子 `360.jpg`, `360.jpeg`, `360.png`, `360.ai`, `360.bmp`, `360.dcm`, `360.eps`, `360.gif`, `360.ps`, `360.psd`, `360.svg`, `360.svs`, `360.tga`, `360.tif`, `360.tiff` ### イベント 360度画像ビューアーでは、以下のイベントがトリガーされます。 | イベント名 | 説明 | イベントデータ | | --- | --- | --- | | destroy | プレビューは意図的に破棄されます。 | | | load | プレビューが読み込まれます。 | 1. {string} error (省略可): エラーメッセージ | | | | 2. {object} file: 現在のファイル | | | | 3. {object} metrics: ロガーからの情報 | | | | 4. {object} viewer: 現在のビューアー | | notification | 通知が表示されます。 | | | navigate | 指定したインデックスのプレビューが表示されます。 | {object}ファイル | | reload | プレビューが再読み込みされます。 | | | resize | プレビューのサイズが変更されます。 | 1. {number} height: ウィンドウの高さ | | | | 2. {number} width: ウィンドウの幅 | ## 画像ビューアー 画像ビューアーでは、画像ファイルのプレビューがレンダリングされます。 ### 動作 ビューアーを回転させると、画像が右へ90度回転します。デフォルトのズームレベルでは、画像をクリックすると1回拡大されます。拡大されたドキュメントをクリックすると、デフォルトのズームレベルに戻ります。縮小されたドキュメントをクリックすると、元のズームレベルになるまで拡大されます。 ### コントロール - 拡大 - 縮小 - 回転 - 全画面: Escキーを押すと終了可能 ### サポートされているファイル拡張子 `ai`, `bmp`, `dcm`, `eps`, `idml`, `indt`, `indd`, `inx`, `gif`, `png`, `ps`, `psd`, `svs`, `tga` ### オプション | オプション | 型 | 説明 | | --- | --- | --- | | annotations | boolean | 省略可。コンテンツの注釈を表示するかどうか。デフォルト値はfalseです。 | ### イベント 画像ビューアーでは、以下のイベントがトリガーされます。 | イベント名 | 説明 | イベントデータ | | --- | --- | --- | | destroy | プレビューは意図的に破棄されます。 | | | load | プレビューが読み込まれます。 | 1. {string} error (省略可): エラーメッセージ | | | | 2. {object} file: 現在のファイル | | | | 3. {object} metrics: ロガーからの情報 | | | | 4. {object} viewer: 現在のビューアー | | notification | 通知が表示されます。 | | | navigate | 指定したインデックスのプレビューが表示されます。 | {object}ファイル | | reload | プレビューが再読み込みされます。 | | | resize | プレビューのサイズが変更されます。 | 1. {number} height: ウィンドウの高さ | | | | 2. {number} width: ウィンドウの幅 | | zoom | プレビューが拡大または縮小されます。 | 1. {number} zoom: 新しい拡大/縮小値 | | | | 2. {boolean} canZoomIn: trueにするとビューアーをさらに拡大可能 | | | | 3. {boolean} canZoomOut: trueにするとビューアーをさらに縮小可能 | | pan | プレビューが平行移動します。 | | | panstart | 平行移動が開始されます。 | | | panend | 平行移動が終了します。 | | | rotate | 画像が回転します。 | | | printsuccess | 印刷が正常に開始されました。 | | ## 複数画像ビューアー 複数画像ビューアーでは、複数画像のファイル (`tiff`、`tif`) のプレビューがレンダリングされます。 ### 動作 デフォルトのズームレベルでは、画像をクリックすると1回拡大されます。拡大されたドキュメントをクリックすると、デフォルトのズームレベルに戻ります。縮小されたドキュメントをクリックすると、元のズームレベルになるまで拡大されます。 ### コントロール - 拡大 - 縮小 - 全画面: Escキーを押すと終了可能 - ページの設定: 上矢印と下矢印を使用するか、ページ番号をクリックしてテキストを入力します。 ### サポートされているファイル拡張子 `tif`, `tiff` ### オプション | オプション | 型 | 説明 | | --- | --- | --- | | annotations | boolean | 省略可。コンテンツの注釈を表示するかどうか。デフォルト値はfalseです。 | ### イベント 画像ビューアーでは、以下のイベントがトリガーされます。 | イベント名 | 説明 | イベントデータ | | --- | --- | --- | | destroy | プレビューは意図的に破棄されます。 | | | load | プレビューが読み込まれます。 | 1. {string} error (省略可): エラーメッセージ | | | | 2. {object} file: 現在のファイル | | | | 3. {object} metrics: ロガーからの情報 | | | | 4. {object} viewer: 現在のビューアー | | notification | 通知が表示されます。 | | | navigate | 指定したインデックスのプレビューが表示されます。 | {object}ファイル | | reload | プレビューが再読み込みされます。 | | | resize | プレビューのサイズが変更されます。 | 1. {number} height: ウィンドウの高さ | | | | 2. {number} width: ウィンドウの幅 | | zoom | プレビューが拡大または縮小されます。 | 1. {number} zoom: 新しい拡大/縮小値 | | | | 2. {boolean} canZoomIn: trueにするとビューアーをさらに拡大可能 | | | | 3. {boolean} canZoomOut: trueにするとビューアーをさらに縮小可能 | | pagefocus | ページが表示可能です。 | {number} フォーカスされたページのページ番号 | | pan | プレビューが平行移動します。 | | | panstart | 平行移動が開始されます。 | | | panend | 平行移動が終了します。 | | ### メソッド 複数ページの画像ビューアーでは以下のメソッドを使用できます。 | メソッド名 | 説明 | メソッドのパラメータ | | --- | --- | --- | | zoom | 画像を拡大/縮小します。 | {string} 「in」、「out」、または「reset」 | | previousPage | 前のページに移動します。 | | | nextPage | 次のページに移動します。 | | | setPage | 指定したページに移動します。 | {number} ページ番号 | | toggleFullscreen | 全画面モードを切り替えます。 | | ## ドキュメントビューアー ドキュメントビューアーでは、さまざまなドキュメントタイプのプレビューがレンダリングされます。 ### 動作 ドキュメントビューアーには、プレビューを閉じるときに表示していたページが記憶されます。次回そのファイルを開くと、すぐにそのページが表示されます。ビューアーウィンドウのサイズを変更すると、ドキュメントのサイズが変更されます。 ### コントロール - 拡大 - 縮小 - ページの設定: 上矢印と下矢印を使用するか、ページ番号をクリックしてテキストを入力します。 - 全画面 (Escキーを押すと終了可能) ### サポートされているファイル拡張子 `as`, `as3`, `asm`, `bat`, `c`, `cc`, `cmake`, `cpp`, `cs`, `css`, `csv`, `cxx`, `diff`, `doc`, `docx`, `erb`, `gdoc`, `groovy`, `gsheet`, `h`, `haml`, `hh`, `htm`, `html`, `java`, `js`, `less`, `log`, `m`, `make`, `md`, `ml`, `mm`, `msg`, `odp`, `ods`, `odt`, `pdf`, `php`, `pl`, `plist`, `ppt`, `pptx`, `properties`, `py`, `rb`, `rst`, `rtf`, `sass`, `scala`, `scm`, `script`, `sh`, `sml`, `sql`, `tsv`, `txt`, `vi`, `vim`, `webdoc`, `wpd`, `xhtml`, `xls`, `xlsm`, `xlsx`, `xml`, `xsd`, `xsl`, `yaml` ### オプション | オプション | 型 | 説明 | | --- | --- | --- | | annotations | boolean | 省略可。コンテンツの注釈を表示するかどうか。デフォルト値はfalseです。 | ### イベント ドキュメントビューアーでは、以下のイベントがトリガーされます。 | イベント名 | 説明 | イベントデータ | | --- | --- | --- | | destroy | プレビューは意図的に破棄されます。 | | | load | プレビューが読み込まれます。 | 1. {string} error (省略可): エラーメッセージ | | | | 2. {object} file: 現在のファイル | | | | 3. {object} metrics: ロガーからの情報 | | | | 4. {object} viewer: 現在のビューアー | | notification | 通知が表示されます。 | | | navigate | 指定したインデックスのプレビューが表示されます。 | {object}ファイル | | reload | プレビューが再読み込みされます。 | | | resize | プレビューのサイズが変更されます。 | 1. {number} height: ウィンドウの高さ | | | | 2. {number} width: ウィンドウの幅 | | zoom | プレビューが拡大または縮小されます。 | 1. {number} newScale: 新しい拡大/縮小値 | | | | 2. {boolean} canZoomIn: trueにするとビューアーをさらに拡大可能 | | | | 3. {boolean} canZoomOut: trueにするとビューアーをさらに縮小可能 | | pagerender | ページがレンダリングされます。 | {number} レンダリングされたページのページ番号 | | pagefocus | ページが表示可能です。 | {number} フォーカスされたページのページ番号 | | scrollstart | ビューアーでスクロールを開始します。 | 1. {number} scrollTop: ビューポートの上部からスクロールしたピクセル数 | | | | 2. {number} scrollLeft: ビューポートの左側からスクロールしたピクセル数 | | scrollend | ビューアーでスクロールを停止します。 | 1. {number} scrollTop: ビューポートの上部からスクロールしたピクセル数 | | | | 2. {number} scrollLeft: ビューポートの左側からスクロールしたピクセル数 | | printsuccess | 印刷が正常に開始されました。 | | | printsuccess | 印刷に失敗しました。 | | ### 注釈 | イベント名 | 説明 | イベントデータ | | --- | --- | --- | | annotationdraw | テキストがハイライトされます。 | | | annotationcommentpending | ユーザーは、保留中のコメントが表示されているダイアログに戻ります。 | | | annotationcreate | 注釈の作成 | | | annotationcancel | 注釈が開始されましたが、作成前に破棄されました。 | | | annotationdelete | AnnotationIDが指定されている注釈が削除されます。IDが指定されていない場合は、スレッド内にある最初の (かつ残っている唯一の) 注釈が削除されます。 | | ## <iframe>ビューアー `<iframe>`ビューアーは、外部ソースからレンダリングされたコンテンツを表示するためのフレームを埋め込みます。 ### 動作 `<iframe>`ビューアーは、Box Notesのプレビューに使用されます。 Box Notesは、メインのBoxウェブアプリ内にフル機能搭載のビューアーを備えています。ただし、このようなフル機能搭載のビューアーは、Notesのファイルと同じディレクトリ内にある他のファイルのプレビューから移動しても初期化されません。この場合、`<iframe>`ビューアーは、Box Noteファイルの表示専用のレンダリング機能を埋め込みます。 ### サポートされているファイル拡張子 `boxnote` ### イベント `<iframe>`ビューアーでは、以下のイベントがトリガーされます。 | イベント名 | 説明 | イベントデータ | | --- | --- | --- | | destroy | プレビューは意図的に破棄されます。 | | | load | プレビューが読み込まれます。 | 1. {string} error (省略可): エラーメッセージ | | | | 2. {object} file: 現在のファイル | | | | 3. {object} metrics: ロガーからの情報 | | | | 4. {object} viewer: 現在のビューアー | | notification | 通知が表示されます。 | | | navigate | 指定したインデックスのプレビューが表示されます。 | {object}ファイル | | reload | プレビューが再読み込みされます。 | | | resize | プレビューのサイズが変更されます。 | 1. {number} height: ウィンドウの高さ | | | | 2. {number} width: ウィンドウの幅 | ## DASHビューアー DASHビューアーでは、[`Shaka Player`](https://github.com/google/shaka-player)を使用して、動画ファイルのプレビューがレンダリングされます。 ### 動作 DASHビューアーは、黒い背景を使用して、より自然な表示を実現しています。動画は、自動的に決まる初期の品質で、数バイトのチャンクに分割されてストリーミングされます。音量は、音量アイコンをクリックしてミュートまたはミュート解除したり、音量スクラバをドラッグして変更したりできます。動画の位置は、再生スクラバをクリックまたはドラッグして変更できます。 ### コントロール - 再生/一時停止 - 音量 - 設定 - 全画面 (Escキーを押すと終了可能) ### 設定 設定は、プレビューツールバーにある歯車アイコンから使用できます。 - 動画速度: `0.25`、`0.5`、標準 (`1`)、`1.25`、`1.5`、`2.0` - 動画品質: `480p`、`1080p`、`auto` ### サポートされているファイル拡張子 `3g2`, `3gp`, `avi`, `m2v`, `m2ts`, `m4v`, `mkv`, `mov`, `mp4`, `mpeg`, `mpg`, `ogg`, `mts`, `qt`, `wmv` ### イベント DASHビューアーでは、以下のイベントがトリガーされます。 | イベント名 | 説明 | イベントデータ | | --- | --- | --- | | destroy | プレビューは意図的に破棄されます。 | | | load | プレビューが読み込まれます。 | 1. {string} error (省略可): エラーメッセージ | | | | 2. {object} file: 現在のファイル | | | | 3. {object} metrics: ロガーからの情報 | | | | 4. {object} viewer: 現在のビューアー | | notification | 通知が表示されます。 | | | navigate | 指定したインデックスのプレビューが表示されます。 | {object}ファイル | | reload | プレビューが再読み込みされます。 | | | resize | プレビューのサイズが変更されます。 | 1. {number} height: ウィンドウの高さ | | | | 2. {number} width: ウィンドウの幅 | | speedchange | メディアの速度が変更されます。 | {string} 再生速度 | | qualitychange | 動画品質が変更されます。 | {string} メディア品質 | | bandwidthhistory | プレビューが破棄されたときに、帯域幅の履歴を提供します。 | {array} 帯域幅情報 | | switchhistory | プレビューが破棄されたときに、品質の切り替え履歴を提供します。 | {array} 品質切り替えオブジェクト | | adaptation | 品質が帯域幅の変更に適合されます。 | {number} 帯域幅 | | play | 動画が再生されます。 | | | pause | 動画が一時停止されます。 | | | seek | 動画は任意の時点までスキップします。 | {number} 時刻 | ## CSVビューアー CSVビューアーでは、[`PapaParse`](https://github.com/mholt/PapaParse)を使用してCSVおよびTSVファイルを解析し、[`React Virtualized`](https://github.com/bvaughn/react-virtualized)を使用して解析後のデータを表形式で表示します。 ### 動作 ビューアーウィンドウのサイズを変更すると、表のサイズが変更されます。拡大ボタンと縮小ボタンにより、フォントサイズがそれぞれ縮小または拡大されます。現在、列と行のサイズは固定されているため、はみ出すテキストは省略されます。 このビューアーは、印刷をサポートしていません。 ### コントロール - 拡大 - 縮小 - 全画面 (Escキーを押すと終了可能) ### サポートされているファイル拡張子 `csv`, `tsv` ### イベント CSVビューアーでは、以下のイベントがトリガーされます。 | イベント名 | 説明 | イベントデータ | | --- | --- | --- | | destroy | プレビューは意図的に破棄されます。 | | | load | プレビューが読み込まれます。 | 1. {string} error (省略可): エラーメッセージ | | | | 2. {object} file: 現在のファイル | | | | 3. {object} metrics: ロガーからの情報 | | | | 4. {object} viewer: 現在のビューアー | | notification | 通知が表示されます。 | | | navigate | 指定したインデックスのプレビューが表示されます。 | {object}ファイル | | reload | プレビューが再読み込みされます。 | | | resize | プレビューのサイズが変更されます。 | 1. {number} height: ウィンドウの高さ | | | | 2. {number} width: ウィンドウの幅 | | zoom | プレビューが拡大または縮小されます。 | 1. {number} zoom: 新しい拡大/縮小値 | | | | 2. {boolean} canZoomIn: trueにするとビューアーをさらに拡大可能 | | | | 3. {boolean} canZoomOut: trueにするとビューアーをさらに縮小可能 | **Source:** [https://ja.developer.box.com/guides/embed/ui-elements/viewers-and-events/](https://ja.developer.box.com/guides/embed/ui-elements/viewers-and-events/) --- ### フローアクション **Type:** guide | **Category:** ツール | **Section:** Developer Guides フローアクション Salesforceツールキットには、管理者が以下のメソッドを呼び出す際に使用できるラッパーが用意されています。このツールキットを使用すると、Box for SalesforceユーザーはSalesforce… # フローアクション Salesforceツールキットには、管理者が以下の[メソッド](g://tooling/salesforce-toolkit/methods)を呼び出す際に使用できるラッパーが用意されています。このツールキットを使用すると、Box for Salesforceユーザーは[Salesforceフロー](https://help.salesforce.com/s/articleView?id=sf.flow.htm&type=5)を使用して、自動化ソリューション (フォルダ構造など) を構築できます。 ## Salesforceフローのメソッド 以下のリストには、[Salesforceフロー](https://help.salesforce.com/s/articleView?id=sf.flow.htm&type=5)で呼び出し可能なすべてのメソッドを示しています。 - フォルダIDでBoxメタデータを作成する (`createBoxMetadataByFolderId`) - コラボレーションを作成する (`createCollaboration`) - レコードにコラボレーションを作成する (`createCollaborationOnRecord`) - 添付ファイルからファイルを作成する (`createFileFromAttachment`) - フォルダを作成する (`createFolder`) - フォルダの関連付けを作成する (`createFolderAssociation`) - レコードID用のフォルダを作成する (`createFolderForRecordId`) - テンプレートからレコードID用のフォルダを作成する (`createFolderForRecordIdFromTemplate`) - メタデータカスケードポリシーを作成する (`createMetadataCascadePolicy`) - レコードID用のオブジェクトフォルダを作成する (`createObjectFolderForRecordId`) - Slackチャンネルマッピングを作成する (`mapSfdcRecordToSlackChannel`) - フォルダIDでBoxメタデータを削除する (`deleteBoxMetadataByFolderId`) - コラボレーションを削除する (`deleteCollaboration`) - メタデータカスケードポリシーを削除する (`deleteMetadataCascadePolicyById`) - コラボレーションを編集する (`editCollaboration`) - 統合アクティビティを有効にする (`enableAppActivity`) - フォルダIDでBoxメタデータを取得する (`getBoxMetadataByFolderId`) - SalesforceレコードIDでフォルダの関連付けを取得する (`getFolderAssociationsByRecordId`) - レコードIDでフォルダIDを取得する (`getFolderIdByRecordId`) - フォルダURLを取得する (`getFolderUrl`) - フォルダIDでメタデータカスケードポリシーを取得する (`getMetadataCascadePoliciesByFolderId`) - IDでメタデータカスケードポリシーを取得する (`getMetadataCascadePolicyById`) - レコードIDでオブジェクトフォルダを取得する (`getObjectFolderByRecordId`) - フォルダIDでレコードIDを取得する (`getRecordIdByFolderId`) - ルートフォルダIDを取得する (`getRootFolderId`) - フォルダ用URLを取得する (`getUrlForFolder`) - フォルダを移動する (`moveFolder`) - Slackチャンネルアクセス管理を無効に設定する (`setSlackChannelAccessManagementDisabled`) - フォルダIDでBoxメタデータを更新する (`updateBoxMetadataByFolderId`) **Source:** [https://ja.developer.box.com/guides/tooling/salesforce-toolkit/flow-actions/](https://ja.developer.box.com/guides/tooling/salesforce-toolkit/flow-actions/) --- ### ページ割り **Type:** guide | **Category:** 検索 | **Section:** Developer Guides ページ割り 検索APIでは、offsetクエリパラメータとlimitクエリパラメータを使用したオフセットベースのページ割りがサポートされます。マーカーベースのページ割りはサポートされません。 APIによるページ割り 検索結果の最初のページを取得するには、APIをoffset… # ページ割り 検索APIでは、`offset`クエリパラメータと`limit`クエリパラメータを使用したオフセットベースのページ割りがサポートされます。マーカーベースのページ割りはサポートされません。 ## APIによるページ割り 検索結果の最初のページを取得するには、APIを`offset`パラメータを指定せずに呼び出すか、`offset`を`0`に設定して呼び出す必要があります。`limit`フィールドは省略可能です。 ``` curl https://api.box.com/2.0/search?query=sales&offset=0&limit=100 \ -H "authorization: Bearer ACCESS_TOKEN" ``` エントリの次のページを取得するには、以前の`offset`値と以前の結果で返された制限の合計 (`previous_offset + previous_limit`) と等しい`offset`パラメータを指定して、APIを呼び出す必要があります。 ``` curl https://api.box.com/2.0/search?query=sales&offset=100&limit=100 \ -H "authorization: Bearer ACCESS_TOKEN" ``` `offset`は、レスポンス配列内のエントリのサイズではなく、以前の`limit`分だけ加算されますので注意してください。これは制限を下回る可能性があるためです。一般的には、レスポンスオブジェクトの`limit`の値を使用して`offset`値を加算することをお勧めします。 次の`offset`値がレスポンスオブジェクト内の`total_count`値を超えている場合、項目の最終ページはリクエスト済みです。この時点では、これ以上取得する項目がありません。 オフセットベースのページ割りの詳細を確認する ## SDKによるページ割り Boxの各SDKには、APIによるページ割りのサポートが組み込まれています。以下のコードサンプルでは、検索APIでのページ割りの使用方法を示します。 ``` long offsetValue = 0; long limitValue = 50; BoxSearch boxSearch = new BoxSearch(api); BoxSearchParameters searchParams = new BoxSearchParameters(); searchParams.setQuery("sales"); PartialCollection<BoxItem.Info> page1 = boxSearch.searchRange(offsetValue, limitValue, searchParams); offsetValue += 50; PartialCollection<BoxItem.Info> page2 = boxSearch.searchRange(offsetValue, limitValue, searchParams); ``` ``` BoxCollection<BoxItem> page1 = await client.SearchManager .QueryAsync("sales", limit: 50); BoxCollection<BoxItem> page2 = await client.SearchManager .QueryAsync("sales", limit: 50, offset: 50); ``` ``` page1 = client.search().query(query='sales', limit=50) page2 = client.search().query(query='sales', limit=50, offset=50) ``` ``` const page1 = await client.search.query('sales', { limit: 50 }) const page2 = await client.search.query('sales'. { limit: 50, offset: 50 }) ``` **Source:** [https://ja.developer.box.com/guides/search/pagination/](https://ja.developer.box.com/guides/search/pagination/) --- ### ページ割り **Type:** guide | **Category:** APIコール | **Section:** Developer Guides ページ割り Box APIがサポートするコレクションのページ割り方法は… # ページ割り Box APIがサポートするコレクションのページ割り方法は2つあります。最も一般的なページ割りの方法はオフセットベースのページ割りで、項目のリストがあらかじめ決められた固定長の場合によく使用されます。 場合によっては、オフセットベースのページ割りの代替方法または完全な置き換えとして、APIエンドポイントがマーカーベースのページ割りをサポートすることもあります。マーカーベースのページ割りがよく使用されるのは、項目の全セットの長さが頻繁に変更される場合や全体の長さが事前にわからない可能性がある場合です。 **Source:** [https://ja.developer.box.com/guides/api-calls/pagination/](https://ja.developer.box.com/guides/api-calls/pagination/) --- ### ページ割りと並べ替え **Type:** guide | **Category:** メタデータ | **Section:** Developer Guides ページ割りと並べ替え デフォルトでは、1ページあたり返されるクエリ結果は20件のみで、この結果の順序は保証されておらず変更される可能性があります。ページ割りと並べ替えにより、さらに多くの結果を取得し、結果の順序を定義することが可能になります。 ページ割り API… # ページ割りと並べ替え デフォルトでは、1ページあたり返されるクエリ結果は20件のみで、この結果の順序は保証されておらず変更される可能性があります。ページ割りと並べ替えにより、さらに多くの結果を取得し、結果の順序を定義することが可能になります。 ## ページ割り APIはデフォルトで、20件の結果を含む最初のページのみを返します。ページあたりの結果の数を増やすようリクエストするには、リクエストに`limit`クエリパラメータを指定して送信します。 ``` curl -X POST https://api.box.com/2.0/metadata_queries/execute_read \ -H 'Authorization: Bearer <ACCESS_TOKEN>' \ -H 'Content-Type: application/json' \ -d '{ "from": "enterprise_123456.contractTemplate", "fields": ["name"], "ancestor_folder_id": "5555", "limit": 100 }' ``` `limit`の最大値は100です。返される結果ページ数を増やすには、各ページで`next_marker`値を返します。 ``` { "entries": [...], "next_marker": "AAAAAmVYB1FWec8GH6yWu2nwmanfMh07IyYInaa7DZDYjgO1H4KoLW29vPlLY173OKsci6h6xGh61gG73gnaxoS+o0BbI1/h6le6cikjlupVhASwJ2Cj0tOD9wlnrUMHHw3/ISf+uuACzrOMhN6d5fYrbidPzS6MdhJOejuYlvsg4tcBYzjauP3+VU51p77HFAIuObnJT0ff" } ``` この`next_marker`を使用すると、結果の次のページについて新しいリクエストを作成できます。 ``` curl -X POST https://api.box.com/2.0/metadata_queries/execute_read \ -H 'Authorization: Bearer <ACCESS_TOKEN>' \ -H 'Content-Type: application/json' \ -d '{ "from": "enterprise_123456.contractTemplate", "fields": ["name"], "ancestor_folder_id": "5555", "limit": 100, "marker": "AAAAAmVYB1FWec8GH6yWu2nwmanfMh07IyYInaa7DZDYjgO1H4KoLW29vPlLY173OKsci6h6xGh61gG73gnaxoS+o0BbI1/h6le6cikjlupVhASwJ2Cj0tOD9wlnrUMHHw3/ISf+uuACzrOMhN6d5fYrbidPzS6MdhJOejuYlvsg4tcBYzjauP3+VU51p77HFAIuObnJT0ff" }' ``` レスポンスに次のマーカーが含まれていない場合は、これ以上一致する結果がないことを意味します。 `next_marker`を使用するには、結果の次のページにまったく同じクエリを使用することが重要です。`query`、`query_params`などのパラメーターが変更されると、APIはエラーを返します。 ## 並べ替え 結果は、サポートされているどのメタデータフィールドタイプを使用しても並べ替えることができます。現在サポートされているタイプは、`float`、`date`および`string`[フィールド](g://metadata/fields)のみです。`enum`または`multiSelect`値による並べ替えは現在サポートされていません。 結果を並べ替えるには、並べ替えの基準として使用する1つ以上のフィールドキーに加えて、方向を指定します。 ``` "order_by": [ { "field_key": "amount”, "direction": "desc" }, { "field_key": "created_at" "direction": "desc" } ] ``` 並べ替えの方向は、指定したすべてのキーで同じにする必要があります。つまり、各`field_key`の`direction`は同じにする必要があります。 **Source:** [https://ja.developer.box.com/guides/metadata/queries/pagination/](https://ja.developer.box.com/guides/metadata/queries/pagination/) --- ### ベストプラクティス **Type:** guide | **Category:** 認証 | **Section:** Developer Guides ベストプラクティス クライアントシークレットのセキュリティ クライアントシークレットは機密情報であり、保護する必要があります。アクセストークンの取得時にBoxがアプリケーションのID… # ベストプラクティス ## クライアントシークレットのセキュリティ クライアントシークレットは機密情報であり、保護する必要があります。アクセストークンの取得時にBoxがアプリケーションのIDを安全に確認するために使用されるため、クライアントシークレットを自由に配布するべきではありません。配布方法には、メール、公開フォーラム、コードリポジトリ、分散されたネイティブアプリケーション、クライアント側のコードなどがあります。 ## トークンのキャッシュ 新しいトークンの取得はコストが高いため、トークンのキャッシュを使用して、不要なリクエストが行われないようにすることをお勧めします。 トークンは、取得後、Memcachedなどのインメモリキャッシュ、または組み込みのASP.NETキャッシュサービスに保存してください。デフォルトでは、アクセストークンの有効期限は60分ですが、バッファを確保するために50分程度に設定することをお勧めします。 トークンが必要になったら、まずキャッシュに有効なトークンがあるかどうかを確認します。トークンの有効期限が切れている場合は、新しいトークンを取得し、キャッシュに50分間保存します。 ``` def self.user_client(user_id) access_token=Rails.cache.fetch("box_tokens/user/#{user_id}", :expires_in => 50.minutes) do puts "getting new user token" response= Boxr::get_user_token(user_id, private_key: PRIVATE_KEY, private_key_password: ENV['JWT_PRIVATE_KEY_PASSWORD']) response.access_token end Boxr::Client.new(access_token) end ``` Box公式SDKでは、トークンのキャッシュが使用されています。 ## 有効期限が切れたトークン 有効期限が切れたトークンは、401: Unauthorizedエラーを返します。このエラーを処理して、トークンを更新する必要があります。 ## トークンのダウンスコープ アクセストークンについて考えるとき際は、最小権限の原則に従うことが重要です。そのためには、[ダウンスコープ](g://authentication/tokens/downscope)を行います。ダウンスコープでは、すべてのスコープが設定されたアクセストークンがより厳しく制限されたアクセストークンと交換され、そのトークンがクライアント側のコード、モバイル環境、またはUIツールに展開されます。 ``` //Define resource/scopes that downscoped token has access to String resource = "https://api.box.com/2.0/files/RESOURCE_ID"; List<String> scopes = new ArrayList<String>(); scopes.add("base_preview"); scopes.add("item_download"); //Preform token exchange ScopedToken downscopedToken = client.getLowerScopedToken(scopes,resource); //Downscoped token available in downscopedToken.getAccessToken() ``` ## トークンの取り消し すべてのスコープが設定されたアクセストークンもダウンスコープされたトークンも、[取り消す](g://authentication/tokens/revoke)ことができます。そのため、トークンの寿命を管理して、ユーザーがログアウトしたとき、不審なアクティビティがあったとき、新しいセキュリティ強化を推進する必要があるときなどに、リスクを減らすことができます。 ## 開発者トークン 開発者トークンは、開発またはテストのためだけに使用し、実稼働環境では使用しないでください。 **Source:** [https://ja.developer.box.com/guides/authentication/best-practices/](https://ja.developer.box.com/guides/authentication/best-practices/) --- ### ベストプラクティス **Type:** guide | **Category:** Boxの埋め込み | **Section:** Developer Guides ベストプラクティス アプリトークンの循環 アプリトークンの循環に関するガイドを参照してください。 ダウンスコープトークンの使用 アプリトークンは、… # ベストプラクティス ## アプリトークンの循環 [アプリトークンの循環](g://authentication/app-token/rollover)に関するガイドを参照してください。 ## ダウンスコープトークンの使用 アプリトークンは、2つのトークン (プライマリとセカンダリ) からなるセットで、アプリケーションによって管理されているコンテンツに対する高度な権限を保持しています。アプリトークンは、任意のBoxコンテンツをアップロード、ダウンロード、プレビュー、および変更するために、アプリケーションで使用できます。 何らかの理由でトークンをクライアント側で利用できるようにする必要がある場合は、元のアプリトークンの[ダウンスコープ](g://authentication/tokens/downscope)したバージョンを使用することを強くお勧めします。これは、必要に応じて、これらのトークンに高度な権限が付与されるためです。これが必要になる例として、Box Preview UI Elementを使用している場合が挙げられます。 **Source:** [https://ja.developer.box.com/guides/embed/box-view/best-practices/](https://ja.developer.box.com/guides/embed/box-view/best-practices/) --- ### ヘッダーによる一貫性の確保 **Type:** guide | **Category:** APIコール | **Section:** Developer Guides ヘッダーによる一貫性の確保 一部のBox APIでは、アプリケーションとBox間の一貫性を確保するために使用されるヘッダーがサポートされています。 etag、if-match、およびif-none-match API… # ヘッダーによる一貫性の確保 一部のBox APIでは、アプリケーションとBox間の一貫性を確保するために使用されるヘッダーがサポートされています。 ## etag、if-match、およびif-none-match APIを介してリクエスト可能なファイルシステムの項目 (ファイルまたはフォルダ) の多くは、項目の`etag`値を返します。 たとえば、ファイルリソースはJSONレスポンスで`etag`を返します。 ``` curl https://api.box.com/2.0/files/12345 \ -H "authorization: Bearer ACCESS_TOKEN" ``` ``` { "id": 12345, "etag": 1, "type": "file", "sequence_id": 3, "name": "Contract.pdf", ... } ``` この`etag`を`if-match`または`if-none-match`ヘッダーの値として使用できるのは、`etag`値が受信されてからリソースが変更されていないことを確認するためか、または変更されていない項目を不必要にダウンロードしないようにするためです。 たとえば、同じファイルを取得するのはそのファイルが変更された場合のみにするには、`if-none-match`ヘッダーで`etag`値を渡します。 ``` curl https://api.box.com/2.0/files/12345 \ -H "authorization: Bearer ACCESS_TOKEN" \ -H "if-none-match: 1" ``` ファイルが変更されていない場合、このAPIコールでは空のレスポンスが返されます。 ## 一貫性のある変更の確保 `if-match`ヘッダーを使用すると、アプリケーションは、最後に調べた項目がその後別のアプリケーションまたはユーザーによって変更が加えられても、項目が変更されないようにすることができます。これにより、2つのアプリケーションまたは2人のユーザーが項目を同時に変更しても変更が失われることはありません。 このヘッダーは、以下のエンドポイントでサポートされます。 | if-match対応のエンドポイント | | | --- | --- | | POST /files/:id/content | 新しいファイルバージョンをアップロード | | PUT /files/:id | ファイルの情報を更新 | | DELETE /files/:id | ファイルを削除 | | PUT /folders/:id | フォルダの情報を更新 | | DELETE /folders/:id | フォルダを削除 | | PUT /web_links/:id | ウェブリンクの情報を更新 | | DELETE /web_links/:id | ウェブリンクを削除 | これらのAPIコールのレスポンスは、項目が存在するかどうか、および`etag`値が最新バージョンと一致するかどうかによって異なります。 | 項目があるか? | Etagが一致するか? | HTTPステータス | | --- | --- | --- | | はい | はい | 200 | | はい | いいえ | 412 | | いいえ | はい | 412 | | いいえ | いいえ | 404 | # 項目の移動 `if-match`ヘッダーを使用してファイル、フォルダ、またはウェブリンクの移動を防ぐことはできません。Boxでは、必ず最新の項目が新しい場所に移動されます。 ## リクエストによる不要なダウンロードの防止 `if-none-match`ヘッダーを使用すると、アプリケーションは、最後に調べてから変更されていない項目の情報がダウンロードされないようにすることができます。これにより、不要な情報がダウンロードされなくなるため、アプリケーションの速度が向上し、帯域幅が節約されます。 | if-none-match対応のエンドポイント | | | --- | --- | | GET /files/:id | ファイルの情報を取得 | | GET /folders/:id | フォルダの情報を取得 | | GET /web_links/:id | ウェブリンクの情報を取得 | | GET /shared_items | 共有項目の情報を取得 | これらのAPIコールのレスポンスは、項目が存在するかどうか、および`etag`値が最新バージョンと一致するかどうかによって異なります。 | 項目があるか? | Etagが一致するか? | HTTPステータス | | --- | --- | --- | | はい | はい | 304 | | はい | いいえ | 200 | | いいえ | はい | 404 | | いいえ | いいえ | 404 | **Source:** [https://ja.developer.box.com/guides/api-calls/ensure-consistency/](https://ja.developer.box.com/guides/api-calls/ensure-consistency/) --- ### ボットのテスト **Type:** quick-start | **Category:** コラボレーション | **Section:** Developer Guides ボットのテスト この最後のセクションでは、Slackボットのさまざまな機能をテストします。 グループの作成: ボットがチャンネルに追加されると、現在のチャンネル参加者全員を含む新しいBoxグループが作成されます。このチャンネル内で (メールアドレスの照合を基に) 一致するBox… # ボットのテスト この最後のセクションでは、Slackボットのさまざまな機能をテストします。 - **グループの作成**: ボットがチャンネルに追加されると、現在のチャンネル参加者全員を含む新しいBoxグループが作成されます。このチャンネル内で (メールアドレスの照合を基に) 一致するBoxアカウントを持つユーザーのみが追加される必要があります。 - **User Event関数**: ユーザーは、チャンネルに参加した場合またはチャンネルから退出した場合に、チャンネルグループから追加または削除される必要があります。 - **コンテンツ追加関数**: ユーザーが有効な`/boxadd`スラッシュコマンドを入力すると、新しいコラボレーションによってそのコンテンツがグループと共有される必要があります。 上記の内容がまだできていない場合は、これまでに作成したすべてのコードが、一般公開されているアプリケーションとして展開されていることを確認します。 ## グループの作成のテスト ボットが初めてチャンネルに追加されるときに、予想されることがいくつかあります。 - SlackチャンネルIDと一致する名前で新しいグループが作成されます。 - 現在チャンネルに存在するすべてのユーザーがグループに追加されます (Slackメールアドレスが同じメールアドレスでEnterpriseアカウントと一致する限り) Slackボットを[手順1](g://collaborations/connect-slack-to-group-collabs/configure-slack)で構成した際に、SlackボットをSlackワークスペースにインストールしました。グループの作成をテストするには、Slackボットをチャンネルに追加する必要があります。 Slack UIまたは`/invite @bot_app_name`コマンドを使用して、任意のSlackチャンネルからSlackボットを招待します。 追加後、Boxにグループが作成され、メンバーが追加されていることを確認します。Box Enterprise管理者アカウントで、管理コンソールの [**[ユーザーとグループ](https://app.box.com/master/groups)**] セクションに移動します。成功した場合、表示されるグループには、グループ名としてランダムな英数字の文字列が使用されます。これはSlackのチャンネルIDで、グループ名に反映されています。 [**メンバー**] 列には、グループ作成時に社内で検出されてグループに追加された、一致するメールアドレスを持つBoxユーザーの数も表示されます。 グループとメンバーが表示されていれば、この手順は成功です。 グループに追加したメンバーが表示されず、ボットアプリケーションからエラーが返されない場合、最も可能性が高い原因として、メールアドレスの不一致が考えられます。Slackのアカウントで使用されているメールアドレスが、Box Enterpriseのユーザーで使用されているメールアドレスと一致することを確認してください。 ## User Event関数のテスト Box管理コンソールの [**[ユーザーとグループ](https://app.box.com/master/groups)**] セクションを開いたまま、Slackグループの横にある [**メンバー**] 列の数値を書き留めます。 ボットを招待したSlackチャンネルから、ボット以外のユーザーを追加または削除します。 Box管理コンソールの [ユーザーとグループ] セクションを更新すると、ユーザーの追加または削除に応じたメンバー数の増減がわかります。 メンバーの数が変化していれば、この手順は成功です。 ## コンテンツ追加関数のテスト グループとコンテンツを共有する機能をテストするには、チャンネル内の2人のユーザーに対するアクセス権限が必要です。1人はBoxアカウントからコンテンツを共有するユーザー、もう1人は、コンテンツが共有されたことを確認するためにファイルのリストを表示する、グループ内の別のユーザーです。 ボットを招待したSlackチャンネルで、ファイルやフォルダをグループと共有するためのスラッシュコマンドを`/boxadd [file/folder] [ID of file/folder]`形式 (`/boxadd folder 324554221`など) で入力します。 指定されるファイルまたはフォルダIDは、ファイルまたはフォルダを共有するユーザーのBoxアカウント内のコンテンツである必要があります。 Boxアカウント内のファイルまたはフォルダのIDを調べるには、[Boxサイト](https://box.com)内でファイルまたはフォルダを読み込み、URLを確認します。IDはURLの最後の文字列で、多くの場合、`/file/`または`/folder/`を含むセクションの直後に表示されます。 コマンドを入力したら、SlackチャンネルとBoxグループ内で別のユーザーの[Boxサイト](https://box.com)アカウントに移動します。共有したコンテンツがそのアカウントで使用できるようになっているはずです。 共有したコンテンツをグループ内の他のユーザーが使用できれば、この手順は成功です。 ## 次の手順 最小限のボットが展開されたので、ここまでに作成した機能に加えて、操作性を向上させる方法を検討できるようになりました。この工程における次の手順として、さまざまな領域を拡張することもできます。 - グループと共有されたファイルやフォルダの[共有リンクを作成](g://shared-links/create-or-update)するための新しいスラッシュコマンドを追加することで、そのグループに属していない他のユーザーや社外のユーザーとコンテンツを共有できるようにします。 - [リテンションポリシーを作成](e://post-retention-policies)し、グループと共有されたコンテンツに[割り当てる](e://post-retention-policy-assignments)ことで、共有コンテンツの寿命とガバナンスを制御できるようにします。 - チャンネル内のユーザーが、グループと共有されている[ファイルにコメント](e://post-comments)できるように新しいスラッシュコマンドを追加します。 **Source:** [https://ja.developer.box.com/guides/collaborations/connect-slack-to-group-collabs/test-bot/](https://ja.developer.box.com/guides/collaborations/connect-slack-to-group-collabs/test-bot/) --- ### マーカーベースのページ割り **Type:** guide | **Category:** APIコール | **Section:** Developer Guides マーカーベースのページ割り マーカーベースのページングを使用するAPIは、markerおよびlimit… # マーカーベースのページ割り マーカーベースのページングを使用するAPIは、`marker`および`limit`クエリパラメータを使用してコレクション内の項目のページ割りを行います。 マーカーベースのページ割りがよく使用されるのは、項目の全セットの長さが頻繁に変更される場合や全体の長さが事前にわからない可能性がある場合です。 ## ページング コレクション内のエントリの最初のページを取得するには、APIを`marker`パラメータを指定せずに呼び出すか、`marker`を`0`に設定して呼び出す必要があります。`limit`パラメータは省略可能です。 ``` curl https://api.box.com/2.0/folders/0/items?limit=100&usemarker=true \ -H "authorization: Bearer ACCESS_TOKEN" ``` オフセットベースのページ割りとマーカーベースのページ割りの両方をサポートするAPIでは、マーカーベースのページ割りが使用されるように`usemarker`クエリパラメータを`true`に設定する必要があります。 エントリの次のページを取得するには、APIレスポンスで受け取った`next_marker`値の値に等しい`marker`パラメータを指定して、APIを呼び出す必要があります。 ``` curl https://api.box.com/2.0/folders/0/items?marker=34332423&limit=100&usemarker=true \ -H "authorization: Bearer ACCESS_TOKEN" ``` 次の`next_marker`値がレスポンスオブジェクト内で`null`になっている場合、項目の最終ページはリクエスト済みです。この時点では、これ以上取得する項目がありません。 マーカーベースのページングを使用する場合、コレクション内のエントリの合計数を確認するには、エントリをすべて取得するしかありません。マーカーの内部実装は今後変更される可能性があるため、アプリケーションでは`next_marker`値を長期にわたって保持しないでください。 ## マーカーと制限 以下のクエリパラメータは、コレクションのページ割りに使用されます。 | クエリパラメータ | 型 | デフォルト | | | --- | --- | --- | --- | | marker | String | | コレクション内で最初に結果を返す位置。これは前のリクエストで返された値です。 | | limit | Integer | APIによって異なる | 返される最大エントリ数。値が最大値を超える場合は、最大値が使用されます。 | | usemarker | Boolean | | ページ割りのタイプを選択するために、両タイプのページ割りをサポートするAPIエンドポイントで使用可能なクエリパラメータ (省略可)。trueに設定すると、マーカーベースのページ割りが適用されます。 | ## コレクション コレクションのページ割りを行うと、APIによって、結果のセットを配列として含むオブジェクトのほか、結果の現在のページに関する情報が返されます。 | フィールド | 型 | | | --- | --- | --- | | entries | Array | このページの項目を含むページ。結果がない場合は空の配列になります。 | | next_marker | String | 結果の次のページを取得するためにmarker値として使用できる値。この値がnullまたは空の文字列の場合は、これ以上取得する結果がありません。 | | limit | Integer | 結果の現在のページに使用される制限。この制限は、このAPIエンドポイントに許可されている最大値を超えない限り、limitクエリパラメータと同じになります。 | ## エンドポイントの例 以下は、マーカーベースのページ割りをサポートするエンドポイントの例です。 - [フォルダ内の項目を取得](e://get_folders_id_items) - [ファイルのコラボレーションのリストを取得](e://get-files-id-collaborations) - [ユーザーのすべてのWebhookのリストを取得](e://get-webhooks) - [社内のすべてのユーザーのリストを取得](e://get-users) - [ごみ箱にあるすべての項目のリストを取得](e://get-folders-trash-items) **Source:** [https://ja.developer.box.com/guides/api-calls/pagination/marker-based/](https://ja.developer.box.com/guides/api-calls/pagination/marker-based/) --- ### メソッドと操作 **Type:** guide | **Category:** ツール | **Section:** Developer Guides メソッドと操作 ツールキットの詳細 クラス名: box.Toolkit インスタンス変数 mostRecentError… # メソッドと操作 ## ツールキットの詳細 クラス名: `box.Toolkit` ## インスタンス変数 ### mostRecentError インスタンスメソッドの呼び出し時に発生した最新のエラーを示す文字列。 この文字列が存在しても、操作が成功しなかったことを意味するわけではありません。そのエラーが回復可能であった可能性もあります。ただし、この文字列に値がない場合は、操作が成功したことを示しています。 ### Enum CollaborationType [コラボレーションのタイプ](https://support.box.com/hc/ja/articles/360044196413-%E3%82%B3%E3%83%A9%E3%83%9C%E3%83%AC%E3%83%BC%E3%82%BF%E3%81%AE%E6%A8%A9%E9%99%90%E3%83%AC%E3%83%99%E3%83%AB%E3%81%AB%E3%81%A4%E3%81%84%E3%81%A6)を示す列挙型。 可能性のある値: `EDITOR`、`VIEWER`、`PREVIEWER`、`UPLOADER`、`COOWNER`、`OWNER`、`PREVIEWERUPLOADER`、`VIEWERUPLOADER` ## 静的メソッド ### deleteServiceUserAssociation サービスアカウントとBox for Salesforce統合の関連付けをクリアするメソッド。間違ったサービスアカウントが使用されている場合、このメソッドを使用してアカウントを変更できます。 パラメータ: - なし 戻り値: - ユーザーのアカウントが存在していたが削除された場合は`true`。 - ユーザーのアカウントが何らかの理由 (存在しなかった場合を含む) で削除されなかった場合は`false`。 ### deleteUserAssociation | パラメータ | 型 | 説明 | | --- | --- | --- | | userId | id | 資格情報がクリアされるユーザーのID。 | 戻り値: - ユーザーのアカウントが存在していたが削除された場合は`true`。 - ユーザーのアカウントが何らかの理由 (存在しなかった場合を含む) で削除されなかった場合は`false`。 ## インスタンスメソッド - コンストラクタ、デストラクタ ### box.Toolkit() パラメータ: - なし ### commitChanges このメソッドは`box.Toolkit()`メソッドのデストラクタとして扱います。 このメソッドは重要です。すべてのフォルダ/コラボレーション操作が完了した後、毎回、例外なくこのメソッドを呼び出す必要があります。 Salesforceではデータベースの更新/挿入/削除の後の呼び出しは許可されないため、Toolkitクラスではすべての呼び出し操作が完了した後で挿入するオブジェクトのコレクションが保持されます。このメソッドを呼び出さない場合、このようなオブジェクトがデータベースから消去され、ユーザー/レコード/フォルダの関連付けを追跡するテーブルの同期も失われて、高度なデバッグによる修正が必要になります。 パラメータ: - なし 戻り値: - `Void` ### プラットフォームイベントを使用するcommitChanges このメソッドは`box.Toolkit()`メソッドのデストラクタとして扱います。 このメソッドは、上記の`commitChanges`とよく似ています。ただし、別のトランザクションでDMLステートメントを実行し、一部のシナリオでガバナ制限を回避するために、プラットフォームイベントを使用してデータベースに変更をコミットします。 | パラメータ | 型 | 説明 | | --- | --- | --- | | usePlatformEvent | boolean | プラットフォームイベントを使用する場合はtrue。元のメソッドを呼び出す場合はfalse。 | 戻り値: - `Void` ## ジェネリックメソッド Box for Salesforce Developer Toolkitは、パラメータとして[HttpRequest](https://developer.salesforce.com/docs/atlas.ja-jp.apexref.meta/apexref/apex_classes_restful_http_httprequest.htm)オブジェクトを受け取り、[HttpResponse](https://developer.salesforce.com/docs/atlas.ja-jp.apexcode.meta/apexcode/apex_classes_restful_http_httpresponse.htm#apex_classes_restful_http_httpresponse)オブジェクトを返すグローバルメソッドを提供します。このメソッドではサービスアカウントの認証の詳細情報を利用してBoxのAPIを呼び出すため、開発者は統合のビジネスロジックに集中して取り組むことができます。 ### sendRequest | パラメータ | 型 | 説明 | | --- | --- | --- | | request | HttpRequest | エンドポイントとメソッドが設定されたHttpRequestオブジェクト。 | 戻り値: - BoxのAPIコールからのレスポンスの詳細情報が含まれた[HttpResponse](https://developer.salesforce.com/docs/atlas.ja-jp.apexcode.meta/apexcode/apex_classes_restful_http_httpresponse.htm#apex_classes_restful_http_httpresponse)オブジェクト。 - HttpRequestのインプットの情報が不足している場合は`Toolkit.BoxApiException`。 - サービスアカウントの認証の詳細情報を取得する際に問題が発生した場合は`null`。この場合は、`mostRecentError`を確認してください。 ## ファイル操作 ### createFileFromAttachment バージョン3.46以降で使用可能です。 Salesforceの文字列長の上限は600万文字です。base64エンコード/デコードプロセスでは文字列が膨張するため、有効なファイルサイズの上限は、同期Apexの場合は4.3MB、非同期Apexの場合は8.6MBとなっています。 | パラメータ | 型 | 説明 | | --- | --- | --- | | att | Attachment | Box内のファイルに変換される添付ファイル。 | | fileNameOverride | string | 省略可 - 新しいファイルの名前。値が渡されなかった場合、添付ファイルの名前が使用されます。 | | folderIdOverride | string | 省略可 - この添付ファイルの配置先であるBoxフォルダID。値が渡されなかった場合、ファイルは添付ファイルのparentIdに当たるレコードに関連付けられているフォルダに配置されます。レコード固有のフォルダが存在していない場合は作成されます。 | | accessToken | string | 省略可 - accessTokenが送信された場合は、Box APIコールにその値が使用されます。そうでない場合は、デフォルトアカウントの資格情報が使用されます。 | 戻り値: - `string`。作成されたBoxファイルのIDが返されます。 - エラーが発生した場合は`null`。この場合には、`mostRecentError`を確認してください。 ### getObjectFolderByRecordId | パラメータ | 型 | 説明 | | --- | --- | --- | | recordId | id | ルートフォルダIDを取得する必要があるSalesforceレコードのID。 | 戻り値: - `string`。レコードIDが渡されたオブジェクトルートフォルダのBoxフォルダIDが返されます。 ## フォルダ操作 ### getRootFolderId パラメータ: - なし 戻り値: - `string`。SalesforceルートフォルダのBoxフォルダIDが返されます。 ### getObjectFolderByRecordId | パラメータ | 型 | 説明 | | --- | --- | --- | | recordId | id | ルートフォルダIDを取得する必要があるSalesforceレコードのID。 | 戻り値: - `string`。レコードIDが渡されたオブジェクトルートフォルダのBoxフォルダIDが返されます。 ### getFolderUrl - このメソッドは、特定のレコードの埋め込みウィジェットURLを取得します。このため、必要に応じて独自の埋め込みロジックを使用できます。 - このメソッドではシームレスログインの設定が優先されます。このため、シームレスログインが有効になっている場合、ユーザーはURLに自動的にログインされます。 | パラメータ | 型 | 説明 | | --- | --- | --- | | recordId | id | ルートフォルダIDを取得する必要があるSalesforceレコードのID。 | | isMobileContext | boolean | URLがモバイル (true) か、それ以外 (false) かを示すブール値。 | 戻り値: - `string`。渡されたSalesforceレコードIDに関連付けられているフォルダを表すURLが返されます。このURLをBox埋め込みウィジェットで使用して、任意のVisualforceページに埋め込むことができます。 ### createObjectFolderForRecordId | パラメータ | 型 | 説明 | | --- | --- | --- | | recordId | id | ルートフォルダIDを取得する必要があるSalesforceレコードのID。 | 戻り値: - `string`。作成されたルートフォルダのBoxフォルダIDが返されます。 - ルートフォルダがすでに存在していた場合、そのルートフォルダのBoxフォルダIDが返されます。 ### createFolder | パラメータ | 型 | 説明 | | --- | --- | --- | | folderName | string | 作成するフォルダの名前。フォルダ名には制限があります。詳細はこちらを参照してください。 | | parentFolderId | string | このフォルダが作成される親Boxフォルダ。 | | accessToken | string | 省略可 - accessTokenが送信された場合は、Box APIコールにその値が使用されます。そうでない場合は、デフォルトのサービスアカウントの資格情報が使用されます。 | 戻り値: - `string`。作成されたフォルダのBoxフォルダIDが返されます。 - フォルダが作成されなかった場合は`null`が返されます。この場合、`mostRecentError`で詳細を確認してください。 ### createFolderForRecordId | パラメータ | 型 | 説明 | | --- | --- | --- | | recordId | id | Boxフォルダの作成に使用されるSalesforceレコードID。 | | folderNameOverride | string | デフォルトでは、レコード名がフォルダ名になります。別の名前を付ける場合は、ここでその値を送信します。 | | optCreateRootFolder | boolean | オブジェクトのルートフォルダが存在しない場合に、それを作成するかどうかを示すブール値。falseを送信した場合、ルートフォルダが存在しないと呼び出しは失敗します。 | 戻り値: - `string`。作成されたフォルダのBoxフォルダIDが返されます。 - フォルダが作成されなかった場合は`null`が返されます。この場合、`mostRecentError`で詳細を確認してください。 - SalesforceレコードがすでにBoxフォルダに関連付けられている場合、既存のBoxフォルダIDが返されます。 ### moveFolder | パラメータ | 型 | 説明 | | --- | --- | --- | | folderId | string | 移動するフォルダのBoxフォルダID。 | | newParentFolderId | string | 新しい親フォルダになるフォルダのBoxフォルダID。 | | accessToken | string | 省略可 - accessTokenを送信すると、その値がBox APIコールに使用されます。そうでない場合、デフォルトのサービスアカウント資格情報が使用されます。 | 戻り値: - フォルダが正常に移動された場合は`true`。 - フォルダが正常に移動されなかった場合は`false`。`mostRecentError`で詳細を確認してください。 ### getUrlForFolder | パラメータ | 型 | 説明 | | --- | --- | --- | | recordId | id | レコードのID。 | 戻り値: - 指定されたURLを含む`pageReference`オブジェクト。 - パラメータが正しくない場合は`null`。 ### createFolderForRecordIdFromTemplate | パラメータ | 型 | 説明 | | --- | --- | --- | | recordId | id | SalesforceレコードID。 | | templateFolderId | string | テンプレートにするソースフォルダ。 | | folderNameOverride | string | 新しいフォルダの名前の上書き。 | | optCreateRootFolder | boolean | ルートフォルダが存在しない場合に作成するかどうかを決定するフラグ。 | 戻り値: - 新しく作成された`folder Id`。 - パラメータが正しくない場合は`null`。 ## フォルダ関連付けメソッド ### getFolderAssociationsByRecordId | パラメータ | 型 | 説明 | | --- | --- | --- | | recordId | id | 返されるフォルダマッピングエントリが関連付けられるSalesforceレコードID。 | 戻り値: - 返されるリストは、このレコードに関連付けられているすべてのフォルダマッピングエントリのコレクションです。 - 一般に、フォルダマッピングエントリが存在しない場合は空のリストになりますが、状況によって`null`になる場合があります。 ### getFolderIdByRecordId | パラメータ | 型 | 説明 | | --- | --- | --- | | recordId | id | フォルダIDを取得するSalesforceレコードID。 | 戻り値: - `string`。渡されたSalesforceレコードIDに関連付けられたBoxフォルダIDが返されます。 ### getRecordIdByFolderId | パラメータ | 型 | 説明 | | --- | --- | --- | | folderId | string | BoxフォルダID。 | 戻り値: - `id`。渡されたBoxフォルダIDに関連付けられたSalesforceレコードIDが返されます。 ### createFolderAssociation | パラメータ | 型 | 説明 | | --- | --- | --- | | recordId | id | Boxフォルダに関連付けるSalesforceレコードID。 | | folderId | string | Salesforceレコードに関連付けるBoxフォルダID。 | 戻り値: - `box__FRUP__c`オブジェクト - エラーが発生した場合 (`mostRecentError`を確認)、返されるFRUPオブジェクトは`null`になります。このFRUPエントリは、`commitChanges`メソッドの呼び出し時にデータベースに挿入されます。このメソッドでは、同じフォルダの複数レコードへの関連付けやその逆の関連付けが許可されないため、他のフォルダの関連付けとの一貫性が保証されます。 ## コラボレーションメソッド Box for Salesforce Developer Toolkitによって作成されたコラボレーションは、コラボレータにコラボレーションメールを送信しません。Box for Salesforce統合に使用されるサービスアカウントのみがコラボレーションメールを受け取ります。 ### createCollaboration | パラメータ | 型 | 説明 | | --- | --- | --- | | folderId | string | コラボレーションを作成するBoxフォルダのID。 | | boxUserId | string | コラボレーションするBoxユーザーのID (boxUserIdまたはemailAddressのどちらか一方のみ必要)。 | | emailAddress | box.Toolkit.CollaborationType | Boxユーザーのメールアドレス。 | | collabType | string | コラボレーションのタイプ (CollaborationType列挙型の定義を参照)。 | | accessToken | string | 省略可 - 送信した場合、この値はBox APIコールの認証に使用されます。nullの場合、サービスアカウントの資格情報が使用されます。 | 戻り値: - `string`。作成されたBoxコラボレーションのIDが返されます。 - エラーが発生した場合は`null`が返されます。その場合、`mostRecentError`を確認してください。 ### createCollaborationOnRecord | パラメータ | 型 | 説明 | | --- | --- | --- | | userId | id | コラボレーションするSalesforceユーザーID。 | | recordId | id | コラボレーションするレコードフォルダのSalesforceレコードID。 | | collabType | box.Toolkit.CollaborationType | コラボレーションのタイプ (CollaborationType列挙型の定義を参照)。 | | optCreateFolder | boolean | SalesforceレコードIDに関連付けられたBoxフォルダがまだ存在しない場合に、それを作成するかどうかを示すブール値。ルートフォルダが存在しない場合は、ルートフォルダも作成されます。falseに設定した場合、フォルダがまだ存在しないと呼び出しが失敗します。 | 戻り値: - `string`。作成されたBoxコラボレーションのIDが返されます。 - エラーが発生した場合は`null`が返されます。その場合、`mostRecentError`を確認してください。 ### editCollaboration | パラメータ | 型 | 説明 | | --- | --- | --- | | collabId | string | コラボレーションID | | collabType | enum | Box.Toolkit.CollaborationType列挙型 | | accessToken | string | | 戻り値: - トランザクションが成功したかどうかを示すブール値。 - パラメータが正しくない場合は`false`。 ### deleteCollaboration | パラメータ | 型 | 説明 | | --- | --- | --- | | collabId | string | コラボレーションID | | accessToken | string | | 戻り値: - トランザクションが成功したかどうかを示すブール値。 - パラメータが正しくない場合は`false`。 ## メタデータ すべてのメソッドに対する詳細なエラーレスポンスについては、`toolkit.mostRecentError`の値を確認してください。 ### getBoxMetadataByFolderId このメソッドでは、[フォルダのメタデータインスタンスを取得エンドポイント](e://get-folders-id-metadata-id-id)を呼び出します。 | パラメータ | 型 | 説明 | | --- | --- | --- | | folderId | string | メタデータを作成するBoxフォルダのID。 | | scope | string | メタデータテンプレートのスコープ。値は[global, enterprise]のいずれかです。 | | template_key | string | メタデータテンプレートの名前。 | 戻り値: - このフォルダ、スコープ、およびテンプレートキーに関連付けられた`FolderMetadata`レコード。カスタム値は、このオブジェクトの`keyValuePairs`変数で確認できます。 以下の場合は`null`。 - パラメータが正しくない - フォルダへのアクセス権限がない - メタデータカスケードポリシーが見つからない ### createBoxMetadataByFolderId このメソッドでは、[フォルダにメタデータインスタンスを作成](e://post-folders-id-metadata-id-id)エンドポイントを呼び出します。 | パラメータ | 型 | 説明 | | --- | --- | --- | | folderId | string | メタデータを作成するBoxフォルダのID。 | | scope | string | メタデータテンプレートのスコープ。値は [global、enterprise][global, enterprise] のいずれかです。 | | template_key | string | メタデータテンプレートの名前。 | | keyValuePairs | List<KeyValuePair> | このクラスはマップとして機能します。Boxメタデータに送信する属性のキー/値ペアをリストとして指定します。キー/値のマッピングはAPIと同じパターンに従います。数値型'3000'および'Customer;Order'などの複数選択値は、コードサンプルに見られる通常のメタデータ値と同様に、valueフィールドで文字列入力として表されます。 | 戻り値: - 新しく作成された`FolderMetadata`オブジェクト。 以下の場合は`null`。 - パラメータが正しくない - フォルダへのアクセス権限がない - メタデータカスケードポリシーが見つからない ### updateBoxMetadataByFolderId [フォルダのメタデータインスタンスを更新](e://put-folders-id-metadata-id-id)エンドポイントを呼び出します。 | パラメータ | 型 | 説明 | | --- | --- | --- | | folderId | string | メタデータを更新するBoxフォルダのID。 | | scope | string | メタデータテンプレートのスコープ。値は[global、enterprise][global, enterprise]のいずれかです。 | | template_key | string | メタデータテンプレートの名前。 | | mdUpdates | List<FolderMetadataUpdate> | メタデータの更新。操作、パス、および値を指定します。メタデータの更新レコードは、APIと同じパターンに従います。数値型 (3000) およびCustomer;Orderなどの複数選択値は、コードサンプルにおける通常のメタデータ値と同様に、valueフィールドで文字列入力として表されます。 | 戻り値: - 更新された`FolderMetadata`オブジェクト。 以下の場合は`null`。 - パラメータが正しくない - フォルダへのアクセス権限がない - メタデータカスケードポリシーが見つからない ### deleteBoxMetadataFolderId このメソッドでは、[フォルダからメタデータインスタンスを削除](e://delete-folders-id-metadata-id-id)エンドポイントを呼び出します。 | パラメータ | 型 | 説明 | | --- | --- | --- | | folderId | string | メタデータを更新するBoxフォルダのID。 | | scope | string | メタデータテンプレートのスコープ。値は[global、enterprise][global, enterprise]のいずれかです。 | | template_key | string | メタデータテンプレートの名前。 | 戻り値: - トランザクションが成功したかどうかを示すブール値。 - パラメータが誤ったパラメータである場合またはメタデータが見つからない場合は、`false`が返されることがあります。 ### getMetadataCascadePolicyById このメソッドでは、[フォルダからメタデータカスケードポリシーを取得](e://get-metadata-cascade-policies-id)エンドポイントを呼び出します。このメソッドはIDを必要とするため、最初に`getMetadataCascadePoliciesByFolderId`メソッドを呼び出す必要があります。 | パラメータ | 型 | 説明 | | --- | --- | --- | | policyId | string | 取得するカスケードポリシーのID。 | 戻り値: - Boxから取得された`MetadataCascadePolicy`オブジェクト。 以下の場合は`null`。 - パラメータが正しくない - フォルダへのアクセス権限がない - メタデータカスケードポリシーが見つからない ### getMetadataCascadePoliciesByFolderId このメソッドでは、フォルダIDを指定し、[メタデータカスケードポリシーを取得](e://get-metadata-cascade-policies)エンドポイントを呼び出すことで、カスケードポリシーを取得します。 | パラメータ | 型 | 説明 | 必須 | | --- | --- | --- | --- | | folderId | string | どのフォルダのポリシーを返すかを指定します。これは、IDが0のルートフォルダでは使用できません。 | はい | | paginationMarker | string | 結果が返される開始位置のマーカー。マーカーベースのページ割りに使用されます。 | いいえ | | Offset | integer | レスポンスが開始される項目のオフセット。 | いいえ | | ownerEnterpriseId | string | メタデータカスケードポリシーを検索するEnterprise ID。指定されていない場合は、デフォルトで現在のEnterpriseに設定されます。 | いいえ | 戻り値: - Boxから取得された`MetadataCascadePolicy`オブジェクトのリスト。 以下の場合は`null`。 - パラメータが正しくない - フォルダへのアクセス権限がない - メタデータカスケードポリシーが見つからない ### createMetadataCascadePolicy このメソッドでは、BoxフォルダID、スコープ、テンプレートキーを指定し、[メタデータカスケードポリシーを投稿](e://post-metadata-cascade-policies)エンドポイントを呼び出すことで、カスケードポリシーを作成します。 | パラメータ | 型 | 説明 | | --- | --- | --- | | folderId | string | メタデータカスケードポリシーを作成するBoxフォルダのID。 | | scope | string | メタデータカスケードポリシーのスコープ。値は [global、enterprise][global, enterprise] のいずれかです。 | | template_key | string | テンプレートキーの名前。 | 戻り値: - 新しく生成された`MetadataCascadePolicy`。 以下の場合は`null`。 - パラメータが正しくない - フォルダへのアクセス権限がない - メタデータカスケードポリシーの詳細が見つからない ### deleteMetadataCascadePolicy このメソッドでは、カスケードポリシーIDを指定し、[メタデータカスケードポリシーIDを削除](e://delete-metadata-cascade-policies-id)エンドポイントを呼び出すことで、カスケードポリシーを削除します。 | パラメータ | 型 | 説明 | | --- | --- | --- | | policyId | string | 削除するカスケードポリシーのID。 | 戻り値: - トランザクションが成功したかどうかを示すブール値。 - パラメータが正しくない場合、フォルダへのアクセス権限がない場合、またはメタデータカスケードポリシーが見つからない場合は、`false`が返されます。 ### enableAppActivity このメソッドでは、アプリアクティビティに指定されたフォルダにメタデータを適用してカスケードすることで、そのフォルダを有効にします。 | パラメータ | 型 | 説明 | | --- | --- | --- | | folderId | string | メタデータを削除するBoxフォルダのID。 | 戻り値: - トランザクションが成功したかどうかを示すブール値。 - パラメータが正しくない場合は`false`。 ## SalesforceとSlack ### getIntegrationMappings このツールキットのメソッドでは、[統合マッピングを取得](e://get-integration-mappings-slack)エンドポイントを呼び出して既存のマッピングを取得します。 | パラメータ | 型 | 説明 | | --- | --- | --- | | integration | String | Slackは、現在唯一サポートされている値です。 | | partnerItemId | String | 指定された統合側でマッピングされている項目のID。例: SlackチャンネルID。 | 戻り値: - `IntegrationMapping`オブジェクトのリスト。 - パラメータが正しくない場合、アクセス権限がない場合、または統合マッピングが見つからない場合は、`null`が返されます。 ### createIntegrationMapping このツールキットのメソッドでは、[統合マッピングを取得](e://get-integration-mappings-slack)エンドポイントを呼び出してマッピングを作成します。 Slackチャンネルにマッピングする場合、はデフォルト`FALSE`でに設定`access_management_disabled`されます。これにより、Slackチャンネルのメンバーリストに含まれていないコラボレータは自動的に削除されます。組織がBoxでの共有をどのように設定しているかに応じて、`TRUE`メソッドを使用して`setSlackChannelAccessManagementDisabled`を`access_ management_disabled`に設定するか、[グループ](https://support.box.com/hc/articles/360043694554-Creating-and-Managing-Groups)を使用することをお勧めします。これにより、Slackの設定に関係なく、どのユーザーも削除されなくなります。ファイルがSlackチャンネルにアップロードされると、コラボレーションはSlackに追加されるかSlackから削除されます。 | パラメータ | 型 | 説明 | | --- | --- | --- | | integration | String | Slackは、現在唯一サポートされている値です。 | | mapping | IntegrationMapping | Apex定義タイプIntegrationMapping。 | 戻り値: - トランザクションが成功したかどうかを示すブール値。 ### deleteIntegrationMapping このツールキットのメソッドでは、[統合マッピングを削除](e://delete-integration-mappings-slack-id)エンドポイントを呼び出してマッピングを削除します。 | パラメータ | 型 | 説明 | | --- | --- | --- | | integration | String | Slackは、現在唯一サポートされている値です。 | | integrationMappingId | String | getIntegrationMappingsから取得されます。 | 戻り値: - トランザクションが成功したかどうかを示すブール値。 ### mapSfdcRecordToSlackChannel このツールキットのメソッドでは、上記の統合マッピングメソッドを使用し、以下の4種類のユースケースで使用できるラッパーを提供します。 1. SalesforceまたはSlackにマッピングが存在しない場合は、Box for Salesforceフォルダ構造にフォルダが作成され、そのフォルダをSlackチャンネルとリンクするための統合マッピングが作成されます。 2. Salesforceからのマッピングのみ存在する場合は、引き続きそのフォルダが使用され、場所は変更されません。そのフォルダをSlackチャンネルとリンクするための統合マッピングを作成します。 3. Slackからのマッピングのみ存在する場合は、引き続きそのフォルダが使用され、既存のフォルダを使用するためにSalesforceレコード用にFRUPレコードが作成されます。このフォルダは、Salesforceルートフォルダ外に存在する可能性があります。 4. SalesforceとSlackに既存のマッピングがあるものの、相互に関連付けられていない場合は、`Toolkit.mostRecentError`またはフローアクション内でエラーがスローされ、マッピングがすでに存在することが示されます。 このメソッド/呼び出し可能なアクションは、Box for Salesforceパッケージの`Create Box Folder/Slack Channel Mapping`で提供されるフローテンプレートで使用されています。 Slackチャンネルにマッピングする場合、はデフォルト`FALSE`でに設定`access_management_disabled`されます。これにより、Slackチャンネルのメンバーリストに含まれていないコラボレータは自動的に削除されます。組織がBoxでの共有をどのように設定しているかに応じて、`TRUE`メソッドを使用して`setSlackChannelAccessManagementDisabled`を`access_ management_disabled`に設定するか、[グループ](https://support.box.com/hc/articles/360043694554-Creating-and-Managing-Groups)を使用することをお勧めします。これにより、Slackの設定に関係なく、どのユーザーも削除されなくなります。ファイルがSlackチャンネルにアップロードされると、コラボレーションはSlackに追加されるかSlackから削除されます。 | パラメータ | 型 | 説明 | | --- | --- | --- | | recordId | ID | SalesforceレコードID。 | | slackChanneld | String | | | slackWorkspaceOrOrgId | String | Box for Slackが組織全体でインストールされている場合は、オーガナイゼーションID (E1234567など) またはワークスペースID (T5555555など) を指定します。 | 戻り値: - トランザクションが成功したかどうかを示すブール値。 ### setSlackChannelAccessManagementDisabled このツールキットのメソッドでは、[統合マッピングを更新](e://put-integration-mappings-slack-id)エンドポイントを呼び出して、アクセス管理の非アクティブ化設定を更新します。 このメソッド/呼び出し可能なアクションは、Box for Salesforceパッケージの`Create Box Folder/Slack Channel Mapping`で提供されるフローテンプレートで使用されています。 | パラメータ | 型 | 説明 | | --- | --- | --- | | channelId | String | | | disabled | Boolean | 基になるBox項目に対するチャンネルメンバーのアクセスを自動で管理する必要があるかどうかを示します。チャンネルのタイプによっては、アクセスがコラボレーションまたは共有リンクの作成により管理されます。 | 戻り値: - トランザクションが成功したかどうかを示すブール値。 **Source:** [https://ja.developer.box.com/guides/tooling/salesforce-toolkit/methods/](https://ja.developer.box.com/guides/tooling/salesforce-toolkit/methods/) --- ### メタデータ **Type:** guide | **Category:** メタデータ | **Section:** Developer Guides メタデータ メタデータを使用すると、ユーザーやアプリケーションは、ファイルやフォルダに関連付けられたカスタムデータを定義、格納できます。 メタデータは、ファイルまたはフォルダに割り当てられているキー/値ペアで構成されます。たとえば、重要な契約には、clientNumber… # メタデータ メタデータを使用すると、ユーザーやアプリケーションは、ファイルやフォルダに関連付けられたカスタムデータを定義、格納できます。 メタデータは、ファイルまたはフォルダに割り当てられているキー/値ペアで構成されます。たとえば、重要な契約には、`clientNumber: 820183`と`clientName: bioMedicalCorp`のキー/値ペアが使用されている場合があります。 ## メタデータの用語 メタデータを操作するには、開発者は異なる数種類のリソースを使用する必要があります。 - **テンプレート:** [メタデータテンプレート](g://metadata/templates)には、ファイルに割り当てることができる再利用可能な一連のキー/値ペアが記載されています。たとえば、`invoiceData`テンプレートでは、請求書に関するデータを保持するため、請求書IDと顧客IDのフィールドが設定されています。 - **フィールド:** [メタデータテンプレートフィールド](g://metadata/fields)には、メタデータテンプレート内の特定のデータが記載されています。たとえば、請求書のIDを`invoiceData`テンプレートの`id`フィールドとして表すことができます。 - **インスタンス:** [メタデータインスタンス](g://metadata/instances)には、各フィールドに割り当てられている値など、テンプレートとファイルやフォルダ間の関係が記載されています。たとえば、ユーザーは、`invoiceData`メタデータテンプレートをファイルに割り当て、2つの値を指定しています (1つは請求書ID、もう1つは顧客ID)。特定のファイルまたはフォルダには最大100個のテンプレートを割り当てることができます。 - **カスケードポリシー**: [メタデータカスケードポリシー](g://metadata/cascades)には、フォルダに適用されているメタデータインスタンスを、そのフォルダ内の項目にどのように適用するかが記載されています。たとえば、ユーザーは、同じ`invoiceData`メタデータテンプレートをプロジェクトフォルダに割り当てると (2つの値を含む)、そのプロジェクトフォルダ内のすべてのファイルとフォルダに自動的に適用できます。 - **クエリ:** [メタデータクエリ](g://metadata/queries)を使用すると、ファイルやフォルダに設定されているメタデータを検索して、そのファイルやフォルダを見つけることができます。たとえば、特定のIDが付いた請求書についてすべてのファイルを検索するには、クエリで、その請求書に適用されている`invoiceData`テンプレートと値`id = :id` (ここで、`:id`は請求書の値) が設定されたすべてのファイルとフォルダを検索することができます。 ## メタデータの目的 メタデータは多くの目的で使用できます。会社がマーケティングチーム向けにデジタルアセットを効率よく編成する場合もあれば、開発者がワークフローや承認の促進のような高度なコンテンツ機能を提供する場合もあります。 たとえば、`marketingCollateral`テンプレートでは、特定のマーケティングコンテンツを使用する状況とタイミングを定義できます。ユーザーは、Boxウェブアプリでテンプレートのレプリゼンテーションを確認すると同時に、ファイルのプレビューに移動できます。 詳細については、[Boxコミュニティの記事](https://support.box.com/hc/ja/articles/360044196173-%E3%83%A1%E3%82%BF%E3%83%87%E3%83%BC%E3%82%BF%E3%81%AE%E4%BD%BF%E7%94%A8)を参照してください。 **Source:** [https://ja.developer.box.com/guides/metadata/](https://ja.developer.box.com/guides/metadata/) --- ### メタデータインスタンス **Type:** guide | **Category:** メタデータ | **Section:** Developer Guides メタデータインスタンス メタデータインスタンスには、メタデータテンプレートとファイルやフォルダ間の関係が記載されています。これには、テンプレートの各フィールドに割り当てられている値が含まれます。 たとえば、ユーザーは、invoiceData… # メタデータインスタンス [メタデータインスタンス](g://metadata/instances)には、[メタデータテンプレート](g://metadata/templates)とファイルやフォルダ間の関係が記載されています。これには、テンプレートの各フィールドに割り当てられている値が含まれます。 たとえば、ユーザーは、`invoiceData`メタデータテンプレートをファイルに割り当て、2つの値を指定しています。この場合、1つは請求書ID用、もう1つは顧客ID用です。 特定のファイルまたはフォルダには最大100個のテンプレートを割り当てることができます。 **Source:** [https://ja.developer.box.com/guides/metadata/instances/](https://ja.developer.box.com/guides/metadata/instances/) --- ### メタデータカスケードポリシー **Type:** guide | **Category:** メタデータ | **Section:** Developer Guides メタデータカスケードポリシー メタデータカスケードポリシーは、フォルダに適用されたメタデータインスタンスをそのフォルダ内の項目にどのように適用するかを記述したものです。たとえば、ユーザーがプロジェクトフォルダに同じinvoiceData… # メタデータカスケードポリシー メタデータカスケードポリシーは、フォルダに適用された[メタデータインスタンス](g://metadata/instances)をそのフォルダ内の項目にどのように適用するかを記述したものです。たとえば、ユーザーがプロジェクトフォルダに同じ`invoiceData`メタデータテンプレートを割り当てると、そのプロジェクトフォルダ内のすべてのファイルとフォルダに自動的に適用することができます。 各ポリシーで指定するメタデータテンプレートインスタンスとフォルダはそれぞれ1つだけです。 ## 有効化と権限 メタデータカスケードポリシーを使用するには、会社の管理者が会社全体に対してそのポリシーを有効化する必要があります。**管理コンソール**で [**Enterprise設定**]、[**コンテンツと共有**]、[**フォルダレベルメタデータのカスケード**] の順に選択します。[**構成の編集**] ボタンをクリックして、フォルダにカスケードポリシーを適用できるユーザーを選択します。 フォルダの編集権限を持ち、カスケードポリシーを作成できるユーザーは、その特定のフォルダ用にメタデータカスケードポリシーを作成できます。 ## 制限 ファイルのアップロードからメタデータの適用まで、若干の遅延が生じます。この遅延の程度はフォルダ内の項目の数によって大きく変わります。メタデータカスケード操作は非同期で実行され、現時点では、すべてのメタデータがいつすべてのファイルにカスケードされたかを確認する方法はありません。 **Source:** [https://ja.developer.box.com/guides/metadata/cascades/](https://ja.developer.box.com/guides/metadata/cascades/) --- ### メタデータカスケードポリシーのリストの取得 **Type:** guide | **Category:** メタデータ | **Section:** Developer Guides メタデータカスケードポリシーのリストの取得 フォルダのメタデータカスケードポリシーのリストを取得するには、folder_idを指定してGET /metadata_cascade_policies APIエンドポイントを呼び出します。 ページ割り このAPI… # メタデータカスケードポリシーのリストの取得 フォルダのメタデータカスケードポリシーのリストを取得するには、`folder_id`を指定して[`GET /metadata_cascade_policies`](e://get_metadata_cascade_policies) APIエンドポイントを呼び出します。 ## ページ割り このAPIでは、[マーカーベースのページ割り](g://api-calls/pagination/marker-based)が使用されており、レスポンスの本文で、より多くのテンプレートを使用できることを示す`next_marker`値を返すことができます。 **Source:** [https://ja.developer.box.com/guides/metadata/cascades/list/](https://ja.developer.box.com/guides/metadata/cascades/list/) --- ### メタデータカスケードポリシーの作成 **Type:** guide | **Category:** メタデータ | **Section:** Developer Guides メタデータカスケードポリシーの作成 メタデータテンプレートがフォルダに適用されたら、メタデータカスケードポリシーを作成できます。それには、ポリシーの適用先となるフォルダのfolder_idと、メタデータテンプレートのscopeおよびtemplateKeyを指定して、POST… # メタデータカスケードポリシーの作成 メタデータテンプレートがフォルダに適用されたら、メタデータカスケードポリシーを作成できます。それには、ポリシーの適用先となるフォルダの`folder_id`と、メタデータテンプレートの`scope`および`templateKey`を指定して、[`POST /metadata_cascade_policies`](e://post_metadata_cascade_policies) APIエンドポイントを呼び出します。 テンプレートの`scope`と`templateKey`を取得するには、[すべてのメタデータテンプレートのリストを取得](g://metadata/templates/list)するか、[ファイルのすべてのインスタンスのリストを取得](g://metadata/instances/list)します。 カスケードポリシーを作成できるのは、指定した`scope`と`templateKey`のフォルダにメタデータインスタンスがすでに適用されている場合のみです。 **Source:** [https://ja.developer.box.com/guides/metadata/cascades/create/](https://ja.developer.box.com/guides/metadata/cascades/create/) --- ### メタデータカスケードポリシーの削除 **Type:** guide | **Category:** メタデータ | **Section:** Developer Guides メタデータカスケードポリシーの削除 メタデータカスケードポリシーを削除するには、削除するポリシーのidを指定してDELETE /metadata_cascade_policies/:id APIエンドポイントを呼び出します。 ポリシーのid… # メタデータカスケードポリシーの削除 メタデータカスケードポリシーを削除するには、削除するポリシーの`id`を指定して[`DELETE /metadata_cascade_policies/:id`](e://delete_metadata_cascade_policies_id) APIエンドポイントを呼び出します。 ポリシーの`id`を取得するには、フォルダに対する[すべてのポリシーのリストを取得](g://metadata/cascades/list)します。 **Source:** [https://ja.developer.box.com/guides/metadata/cascades/delete/](https://ja.developer.box.com/guides/metadata/cascades/delete/) --- ### メタデータカスケードポリシーの取得 **Type:** guide | **Category:** メタデータ | **Section:** Developer Guides メタデータカスケードポリシーの取得 メタデータカスケードポリシーに関する情報を取得するには、ポリシーのidを指定してGET /metadata_cascade_policies/:id APIエンドポイントを呼び出します。 ポリシーのid… # メタデータカスケードポリシーの取得 メタデータカスケードポリシーに関する情報を取得するには、ポリシーの`id`を指定して[`GET /metadata_cascade_policies/:id`](e://get_metadata_cascade_policies_id) APIエンドポイントを呼び出します。 ポリシーの`id`を取得するには、フォルダに対する[すべてのポリシーのリストを取得](g://metadata/cascades/list)します。 **Source:** [https://ja.developer.box.com/guides/metadata/cascades/get/](https://ja.developer.box.com/guides/metadata/cascades/get/) --- ### メタデータクエリ **Type:** guide | **Category:** メタデータ | **Section:** Developer Guides メタデータクエリ メタデータクエリを使用すると、ファイルやフォルダに追加されているメタデータを検索して、そのファイルやフォルダを見つけることができます。 たとえば、特定のID… # メタデータクエリ メタデータクエリを使用すると、ファイルやフォルダに追加されているメタデータを検索して、そのファイルやフォルダを見つけることができます。 たとえば、特定のIDが付いた請求書についてすべてのファイルを検索するには、クエリで、その請求書に適用されている`invoiceData`テンプレートと値`id = :id` (この場合、`:id`は請求書の値) が設定されたすべてのファイルとフォルダを検索することができます。 ## 認証 メタデータクエリAPIは、従来の[OAuth 2.0](g://authentication/oauth2)または[JWT](g://authentication/jwt)を使用して認証されたアプリケーションで使用できます。 **Source:** [https://ja.developer.box.com/guides/metadata/queries/](https://ja.developer.box.com/guides/metadata/queries/) --- ### メタデータクエリAPIの使用 **Type:** quick-start | **Category:** 検索 | **Section:** Developer Guides メタデータクエリAPIの使用 最後に、メタデータクエリAPIコールを作成します。このAPIコールの本文の例を以下に示します。 このAPIコールでは、以下の条件を満たすファイルIDが返されます。 Contact Roleテンプレートが適用されている departments… # メタデータクエリAPIの使用 最後に、[メタデータクエリAPIコール](e://post-metadata-queries-execute-read/)を作成します。このAPIコールの本文の例を以下に示します。 ``` { "from": "enterprise_22201764.contact_role", "query": "departments = :departments", "query_params": {"departments": "legal"}, "ancestor_folder_id": "0", "fields": ["id"] } ``` このAPIコールでは、以下の条件を満たすファイルIDが返されます。 - Contact Roleテンプレートが適用されている - departmentsの値がlegalである - ルートフォルダの下のいずれかの場所にある (「0」は`ancestor_folder_id`であるため) 以下に示すように、この結果、呼び出しは成功し、手順2でテンプレートを追加したファイルに関する情報が表示されます。 検索クエリを使用してコンテンツが見つかりました **Source:** [https://ja.developer.box.com/guides/search/quick-start/metadata-query-api/](https://ja.developer.box.com/guides/search/quick-start/metadata-query-api/) --- ### メタデータクエリの作成 **Type:** quick-start | **Category:** メタデータ | **Section:** Developer Guides … # メタデータクエリの作成 最後の手順として、ファイル/フォルダに追加されているメタデータに基づいてそのファイルおよびフォルダを見つけるためのクエリを作成する方法を見てみましょう。 [メタデータクエリ](g://metadata/queries)を使用すると、ファイルやフォルダに追加されているメタデータを検索して、そのファイルやフォルダを見つけることができます。この検索構文はSQLに似ており、強力な検索を実行するためにブール演算と比較演算子をサポートしています。 この例では、`customerInfo`メタデータテンプレートのインスタンスが適用されているファイルまたはファイルを検索するクエリを作成します。このリストを、預金総額が200,000ドルを超える顧客に属しているファイルに絞り込みます。 ``` curl -X POST https://api.box.com/2.0/metadata_queries/execute_read \ -H 'Authorization: Bearer <ACCESS_TOKEN>" ' \ -H 'Content-Type: application/json' \ -d '{ "from": "enterprise_123456.customerInfo", "fields": [ "name", "enterprise_123456.customerInfo.name" "enterprise_123456.customerInfo.tav" ], "query": "tav >= :value", "query_params": { "value": 200000 }, "ancestor_folder_id": "0" }' ``` このAPIにより、一致したファイルとフォルダのリストのほか、そのファイルのクエリに一致したメタデータが返されます。 ``` { "entries": [ { "type": "file", "id": "11111", "etag": "0", "metadata": { "enterprise_123456": { "customerInfo": { "name": "Box", "tav": 1000000, "$parent": "folder_12345,", "$scope": "enterprise_123456", "$template": "customerInfo", "$version": 1 } } } } ], "limit": 20, "next_marker": "AAAAAmVYB1FWec8GH6yWu2nwmanfMh07IyYInaa7DZDYjgO1H4KoLW29vPlLY173OKsci6h6xGh61gG73gnaxoS+o0BbI1/h6le6cikjlupVhASwJ2Cj0tOD9wlnrUMHHw3/ISf+uuACzrOMhN6d5fYrbidPzS6MdhJOejuYlvsg4tcBYzjauP3+VU51p77HFAIuObnJT0ff" } ``` このAPIはデフォルトで、ページあたり`20`個の項目を返しますが、マーカーベースのページ割りを使用すると、さらに多くの項目をリクエストできます。 メタデータクエリの詳細を確認する メタデータを使用してファイルにクエリを実行しました **Source:** [https://ja.developer.box.com/guides/metadata/quick-start/create-query/](https://ja.developer.box.com/guides/metadata/quick-start/create-query/) --- ### メタデータクエリフィルタ **Type:** guide | **Category:** 検索 | **Section:** Developer Guides メタデータクエリフィルタ GET /search APIでは、関連付けられたメタデータを使用して、検索結果にフィルタをかけることができます。mdfilters… # メタデータクエリフィルタ [`GET /search`](e://get_search) APIでは、関連付けられたメタデータを使用して、検索結果にフィルタをかけることができます。`mdfilters`クエリパラメータを使用すると、開発者はメタデータテンプレートとクエリの対象となる値を指定できます。 ``` curl -i -X GET "https://api.box.com/2.0/search?query=sales&mdfilters=%5B%7B%22scope%22%3A%22enterprise%22%2C%22templateKey%22%3A%22contract%22%2C%22filters%22%3A%7B%22category%22%3A%22online%22%7D%7D%5D" \ -H "Authorization: Bearer <ACCESS_TOKEN>" ``` ``` long offsetValue = 0; long limitValue = 10; BoxSearch boxSearch = new BoxSearch(api); BoxSearchParameters searchParams = new BoxSearchParameters(); searchParams.setQuery("sales"); BoxMetadataFilter bmf = new BoxMetadataFilter(); bmf.setScope("enterprise"); bmf.setTemplateKey("contract"); bmf.setFilter("category", "online") searchParams.setMetadataFilter(bmf) PartialCollection<BoxItem.Info> searchResults = boxSearch.searchRange(offsetValue, limitValue, searchParams); ``` ``` var filter = new { category = "online" }; var filters = new List<BoxMetadataFilterRequest>() { new BoxMetadataFilterRequest() { Scope = "enterprise", TemplateKey = "contract", Filters: filter } }; BoxCollection<BoxItem> results = await client.SearchManager .QueryAsync("sales", mdFilters: filters); ``` ``` from boxsdk.object.search import MetadataSearchFilter, MetadataSearchFilters metadata_search_filter = MetadataSearchFilter(scope='enterprise', template_key='contract') metadata_search_filter.add_value_based_filter(field_key='category', value='online') metadata_search_filters = MetadataSearchFilters() metadata_search_filters.add_filter(metadata_search_filter) client.search().query("sales", metadata_filters=metadata_search_filters) ``` ``` client.search.query( 'sales', { mdfilters: [ { scope: 'enterprise', templateKey: 'contract', filters: { category: 'online' } } ] }) .then(results => { // ... }); ``` この例では、`enterprise.contract`メタデータが追加され、`category`フィールドが`online`に設定されている項目によって、クエリ`sales`に一致するコンテンツの検索にフィルタをかけます。 ## メタデータの概要 メタデータを使用すると、ユーザーやアプリケーションは、ファイルやフォルダに関連付けられたカスタムデータを定義、格納できます。 メタデータは、ファイルまたはフォルダに割り当てられているキー/値ペアで構成されます。たとえば、重要な契約には、`clientNumber: 820183`と`category: online`のキー/値ペアが使用されている場合があります。 `mdfilters`クエリパラメータを使用すると、開発者は、特定のメタデータが追加されているファイルとフォルダを検索できます。 メタデータテンプレートおよびインスタンスの詳細を確認する ## メタデータフィルタ構文 `mdfilters`パラメータに現在指定できるフィルタは1つだけですが、今後拡張される可能性があります。 各フィルタでは、フィルタをかけるメタデータテンプレートの`scope`および`templateKey`を定義します。 ``` [ { "scope": "enterprise", "templateKey": "contract", "filters": {} } ] ``` テンプレートの`scope`と`templateKey`を取得するには、会社の[すべてのメタデータテンプレートのリストを取得](g://metadata/templates/list)するか、[項目のすべてのメタデータインスタンスのリストを取得](g://metadata/instances/list)します。 テンプレートが定義されると、`filters`フィールドではいくつかの異なるフィルタ形式が受け入れられます。フィルタの形式は、フィルタとして使用するフィールドのタイプによって大きく異なります。 ### stringフィールドによるフィルタ `string`タイプのフィールドでフィルタをかけるには、フィルタでフィールドの`key`と、項目を検索する際に目的となる値を定義する必要があります。 ``` [ { "scope": "enterprise", "templateKey": "contract", "filters": { "category": "online" } } ] ``` この例では、`enterprise.contract`テンプレートのインスタンスが適用されていて、キー`category`のフィールドが値`online`に設定されているすべてのファイルとフォルダが検索されます。 ### floatフィールドによるフィルタ `float`タイプのフィールドでフィルタをかけるには、`gt` (より大きい) や `lt` (より小さい) の値を指定して範囲を定義する必要があります。厳密な値を検索する場合は、`gt`と`lt`の両方に同じ値を入力できます。 ``` [ { "scope": "enterprise", "templateKey": "contract", "filters": { "amount": { "gt": 10000, "lt": 20000 } } } ] ``` この例では、`enterprise.contract`テンプレートのインスタンスが適用されていて、キー`amount`のフィールドが`10000`以上`2000`以下の値に設定されているすべてのファイルおよびフォルダが検索されます。`gt`と`lt`はその値を含むことと、必ずしも両方を設定する必要がないことに注意してください。 数値に基づいてクエリを作成する場合は、-16777215～+16777215の範囲を超えないようにしてください。数値属性を使用したメタデータ検索では、インデックス値がFLOAT32として保存されます。結果として、-16777215～+16777215の整数は正確に表すことができます。この範囲外の数値を扱う処理では、精度が失われる場合があります。 ### dateフィールドによるフィルタ `date`タイプのフィールドでフィルタをかけるには、フィルタでフィールドの`key`と、項目の検索対象範囲を定義する必要があります。この範囲を定義するには、`gt` (より大きい) と`lt` (より小さい) の値を指定します。`gt`と`lt`はその値を含むことに注意してください。 ``` [ { "scope": "enterprise", "templateKey": "contract", "filters": { "expirationDate": { "gt": "2016-08-01T00:00:00Z", "lt": "2017-08-01T00:00:00Z" } } } ] ``` この例では、`enterprise.contract`テンプレートのインスタンスが適用されていて、`expirationDate`が`2016-08-01T00:00:00Z`から`2017-08-01T00:00:00Z`までの日付に設定されているファイルとフォルダがすべて検索されます。 ### enumフィールドによるフィルタ `enum`タイプのフィールドでフィルタをかけるには、フィルタでフィールドの`key`と、項目を検索する際に目的となる値を定義する必要があります。 ``` [ { "scope": "enterprise", "templateKey": "contract", "filters": { "category": "online" } } ] ``` この例では、`enterprise.contract`テンプレートのインスタンスが適用されていて、キー`category`のフィールドが値`online`に設定されているすべてのファイルとフォルダが検索されます。 ### multiSelectフィールドによるフィルタ `multiSelect`タイプのフィールドでフィルタをかけるには、フィルタでフィールドの`key`と、項目の検索で対象とする可能性がある値を定義する必要があります。検索を実行すると、クエリでは基本的に`OR`演算が実行され、指定した値のいずれかがこのフィールドと一致するテンプレートが取得されます。 ``` [ { "scope": "enterprise", "templateKey": "contract", "filters": { "category": [ "online", "enterprise" ] } } ] ``` この例では、`enterprise.contract`テンプレートのインスタンスが適用されていて、キー`category`のフィールドが値`online`または`enterprise`に設定されているすべてのファイルとフォルダが検索されます。 **Source:** [https://ja.developer.box.com/guides/search/metadata-filters/](https://ja.developer.box.com/guides/search/metadata-filters/) --- ### メタデータテンプレート **Type:** guide | **Category:** メタデータ | **Section:** Developer Guides メタデータテンプレート メタデータテンプレートには、ファイルまたはフォルダに割り当てることができる一連のキー/値ペアが記載されています。 たとえば、invoiceDataテンプレートでは、請求書に関するデータを保持するため、請求書IDと顧客ID… # メタデータテンプレート メタデータテンプレートには、ファイルまたはフォルダに割り当てることができる一連のキー/値ペアが記載されています。 たとえば、`invoiceData`テンプレートでは、請求書に関するデータを保持するため、請求書IDと顧客IDのフィールドが設定されています。 ファイルまたはフォルダには、`marketingCollateral`インスタンスや`retentionPolicy`インスタンスなど、複数の異なるテンプレート[インスタンス](g://metadata/instances)を関連付けることができます。 ## メタデータのスコープ メタデータテンプレートは、2つの異なるグループ、つまり**スコープ**にグループ化されます。 メタデータのスコープの詳細を確認する ## 権限と制限 テンプレートは企業あたり500個までに制限されています。 メタデータテンプレートの作成は、管理者権限を持つユーザーに制限されています。つまり、管理者、または管理者から**会社のメタデータテンプレートを作成、編集する**権限が付与されている共同管理者だけがウェブアプリまたはAPIを使用してテンプレートを管理できます。 **Source:** [https://ja.developer.box.com/guides/metadata/templates/](https://ja.developer.box.com/guides/metadata/templates/) --- ### メタデータテンプレートに関する情報を確認する **Type:** quick-start | **Category:** 検索 | **Section:** Developer Guides メタデータテンプレートに関する情報を確認する API… # メタデータテンプレートに関する情報を確認する APIを使用してメタデータテンプレートを作成し、成功を示すレスポンスが返ってきた場合は、この手順をスキップできます。 管理コンソールでメタデータテンプレートを作成した場合は、**会社のメタデータテンプレートを作成、編集する**権限を持つ管理者または共同管理者の[アクセストークン](g://authentication/tokens)を取得する必要があります。手順1で説明したとおり、これらの要件を満たすトークンを取得するには、管理者または共同管理者としてログインし、[開発者コンソール](https://account.box.com/developers/console)でアプリケーションを見つけて、[**構成**] タブの [**開発者トークンを生成**] をクリックする方法が最も簡単です。 以下に示すように、このトークンを使用して、[企業のすべてのメタデータテンプレートのリストを取得エンドポイント](e://get-metadata-templates-enterprise/)に対してAPIコールを実行すると、テンプレートに関する情報をレスポンス内で確認できます。特に、`scope`と`templateKey`に注意してください。 テンプレートに関する詳細を取得しました **Source:** [https://ja.developer.box.com/guides/search/quick-start/locate-template-info/](https://ja.developer.box.com/guides/search/quick-start/locate-template-info/) --- ### メタデータテンプレートのスコープ **Type:** guide | **Category:** メタデータ | **Section:** Developer Guides メタデータテンプレートのスコープ メタデータテンプレートは、2つの異なるグループ、つまりスコープにグループ化されます。 global: 所属する会社に関係なく、Box… # メタデータテンプレートのスコープ メタデータテンプレートは、2つの異なるグループ、つまり**スコープ**にグループ化されます。 - **`global`**: 所属する会社に関係なく、Boxを使用するすべてのユーザーが使用できるテンプレートのグループ。たとえば、追加のスキーマを関連付けずに自由形式のキー/値の`string`ペアを配置する場所として使用される`global.properties`テンプレートがあります。 - **`enterprise`または**`enterprise_*`: 社内のユーザーによって定義されたテンプレートのグループ。これらのテンプレートは、管理者がウェブアプリケーションで作成したものか、アプリケーションがAPIを使用して作成したものです。認証済みユーザーの企業内のテンプレートにアクセスまたは作成する場合は、省略形の`enterprise`を使用できます。別の企業に属するテンプレートにアクセスする場合は (例: 他の企業に属するファイルのメタデータにアクセスする場合)、`enterprise_*`スコープを使用します (`*`はテンプレートが属する企業のIDです)。 # 権限 `global`スコープ内ではメタデータテンプレートを作成できないことと、ユーザーの会社内で作成されたメタデータテンプレートにアクセスできるのはその会社へのアクセス権限を持つユーザーのみであることに注意してください。 **Source:** [https://ja.developer.box.com/guides/metadata/scopes/](https://ja.developer.box.com/guides/metadata/scopes/) --- ### メタデータテンプレートの作成 **Type:** guide | **Category:** メタデータ | **Section:** Developer Guides メタデータテンプレートの作成 メタデータテンプレートを作成するには、scope、displayName、および必要に応じて一連のfieldsをPOST /metadata_templates/schema APIに渡します。 メタデータテンプレートは、enterprise… # メタデータテンプレートの作成 メタデータテンプレートを作成するには、`scope`、`displayName`、および必要に応じて一連の`fields`を[`POST /metadata_templates/schema`](e://post_metadata_templates_schema) APIに渡します。 メタデータテンプレートは、`enterprise`スコープのみに作成できます。`global`スコープの場合はテンプレートを作成できません。 # 管理者権限が必須 メタデータテンプレートの作成は、管理者権限を持つユーザーに制限されています。つまり、管理者、または管理者から**会社のメタデータテンプレートを作成、編集する**権限が付与されている共同管理者だけがウェブアプリまたはAPIを使用してテンプレートを管理できます。 ## テンプレートフィールド `fields`属性は、ユーザーがテンプレートで入力できる個々のフィールドのセットを表します。たとえば、`customer`テンプレートに`string`タイプの`name`フィールドがあるとします。 テンプレートフィールドは、`string`、`enum`、`float`、`date`、`enum`、または`multiSelect`タイプのいずれかになります。各フィールドには少なくとも`type`、`displayName`、および`key`が必要です。 ``` { "scope": "enterprise", "displayName": "Customer", "fields": [ { "type": "string", "key": "name", "displayName": "Name" } ] } ``` `enum`および`multiSelect`フィールドタイプは、ユーザーが項目のリストからそれぞれ1つまたは複数のオプションを選択できるドロップダウンリストを表します。 ``` { "scope": "enterprise", "displayName": "Customer", "fields": [ { "type": "enum", "key": "industry", "displayName": "Industry", "options": [ {"key": "Technology"}, {"key": "Healthcare"}, {"key": "Legal"} ] } ] } ``` メタデータテンプレートフィールドの詳細を確認する ## テンプレートキー メタデータテンプレートが作成されると、`templateKey`を明示的に指定した場合を除き、テンプレートの`displayName`から自動的に`templateKey`が生成されます。テンプレートキーを作成する際に、名前に含まれるスペースと規格外の文字は削除され、文字列はキャメルケースに変換されます。 たとえば、`Test Name (with-special_) Characters`という名前のメタデータテンプレートの`templateKey`は`testNameWithspecialCharacters`になります。 その後、このテンプレートキーは、テンプレートの情報を取得したり、項目にテンプレートを割り当てたりするためのAPIリクエストを実行するときに使用されます。 **Source:** [https://ja.developer.box.com/guides/metadata/templates/create/](https://ja.developer.box.com/guides/metadata/templates/create/) --- ### メタデータテンプレートの作成 **Type:** quick-start | **Category:** 検索 | **Section:** Developer Guides メタデータテンプレートの作成 新しいメタデータテンプレートを作成するには、管理コンソールを使用する方法とAPIで管理者のアクセストークンを使用する方法の… # メタデータテンプレートの作成 新しいメタデータテンプレートを作成するには、管理コンソールを使用する方法とAPIで管理者のアクセストークンを使用する方法の2とおりあります。使用するメタデータテンプレートをすでに作成している場合は、次の手順に進むことができます。 ## 管理コンソール 管理コンソールでテンプレートを作成するには、次の場所に移動します。 [**管理コンソール**] > [**コンテンツ**] タブ > [**メタデータ**] > [**新規作成**] メタデータは、Business Plus以上のアカウント向けの機能です。アカウントをアップグレードするには、Boxアカウントチームまでお問い合わせください。 [**新規作成**] を選択すると、以下に示す、新しいテンプレートを作成するためのフォームが表示されます。[**ドロップダウン - 単一選択**] 形式を選択します。 [ドロップダウン - 複数選択] 形式を選択すると、このクイックスタートの後の手順でクエリの構造が変わります。 ## API APIを使用してメタデータテンプレートを作成するには、**会社のメタデータテンプレートを作成、編集する**権限を持つBox管理者または共同管理者に関連付けられた[アクセストークン](g://authentication/tokens)が必要です。トークンが誰に関連付けられているかがわからない場合は、[現在のユーザーを取得エンドポイント](e://get-users-me)に対してAPIコールを実行してください。これらの要件を満たすトークンを取得するには、管理者または共同管理者としてログインし、[開発者コンソール](https://account.box.com/developers/console)でアプリケーションを見つけて、[**構成**] タブの [**開発者トークンを生成**] をクリックする方法が最も簡単です。[開発者トークン](g://authentication/tokens/developer-tokens)は、必ず、このボタンがクリックされたときに開発者コンソールにログインしているユーザーに関連付けられます。 [Postman](https://postman.com/)および[Box Postmanコレクション](g://tooling/postman)を使用している場合に、上記の管理コンソールを使用して作成したのと同じメタデータテンプレートを作成するAPIコールの例を以下に示します。 [ドロップダウン - 単一選択] 以外のテンプレート形式を使用する場合は、APIコールの本文が上記の例とは異なるため、Boxのリファレンスドキュメントを確認してください。 このAPIコールに対するレスポンスでは、後で必要になる重要な情報が示されます。UIを使用してテンプレートを作成した場合は、この情報の取得方法を次の手順で確認してください。 メタデータテンプレートを作成しました **Source:** [https://ja.developer.box.com/guides/search/quick-start/create-metadata-template/](https://ja.developer.box.com/guides/search/quick-start/create-metadata-template/) --- ### メタデータテンプレートの削除 **Type:** guide | **Category:** メタデータ | **Section:** Developer Guides メタデータテンプレートの削除 メタデータテンプレートを削除するには、DELETE /metadata_templates/enterprise/:templateKey/schema APIを呼び出します。 このAPI… # メタデータテンプレートの削除 メタデータテンプレートを削除するには、[`DELETE /metadata_templates/enterprise/:templateKey/schema`](e://delete_metadata_templates_id_id_schema) APIを呼び出します。 このAPIは、テンプレートが正常に削除された場合に、レスポンスの本文がない`204 No Content` APIレスポンスを返します。また、すべてのファイルおよびフォルダからすべてのテンプレートインスタンスを削除します。 削除できるのは、`enterprise`スコープ内に作成されたテンプレートのみです。 # 管理者権限が必須 メタデータテンプレートの削除は、管理者権限を持つユーザーに制限されています。つまり、管理者、または管理者から**会社のメタデータテンプレートを作成、編集する**権限が付与されている共同管理者だけがウェブアプリまたはAPIを使用してテンプレートを管理できます。 **Source:** [https://ja.developer.box.com/guides/metadata/templates/delete/](https://ja.developer.box.com/guides/metadata/templates/delete/) --- ### メタデータテンプレートの取得 **Type:** guide | **Category:** メタデータ | **Section:** Developer Guides メタデータテンプレートの取得 メタデータテンプレートに関する情報を取得するには、テンプレートの名前とスコープ、またはテンプレートの識別子を使用します。 認証済みユーザーが取得できるのは、globalスコープまたはenterprise_:idスコープ (:idは会社のID… # メタデータテンプレートの取得 メタデータテンプレートに関する情報を取得するには、テンプレートの名前とスコープ、またはテンプレートの識別子を使用します。 認証済みユーザーが取得できるのは、`global`スコープまたは`enterprise_:id`スコープ (`:id`は会社のID) の中で[スコープ](g://metadata/scopes)が設定されたメタデータテンプレートに関する情報のみです。 ## 名前を指定してメタデータテンプレートを取得 名前を指定してメタデータテンプレートを取得するには、テンプレートの`scope`と`templateKey`を指定して[`GET /metadata_templates/:scope/:templateKey/schema`](e://get_metadata_templates_id_id_schema) APIエンドポイントを呼び出します。 テンプレートの`scope`と`templateKey`を取得するには、[すべてのメタデータテンプレートのリストを取得](g://metadata/templates/list)するか、[項目のすべてのインスタンスのリストを取得](g://metadata/instances/list)します。 ## IDを指定してメタデータテンプレートを取得 IDを指定してメタデータテンプレートを取得するには、テンプレートの`id`を[`GET /metadata_templates/:id`](e://get_metadata_templates_id) APIエンドポイントに渡す必要があります。 テンプレートの`id`を取得するには、[すべてのメタデータテンプレートのリストを取得](g://metadata/templates/list)するか、[項目のすべてのインスタンスのリストを取得](g://metadata/instances/list)します。 **Source:** [https://ja.developer.box.com/guides/metadata/templates/get/](https://ja.developer.box.com/guides/metadata/templates/get/) --- ### メタデータテンプレートの更新 **Type:** quick-start | **Category:** メタデータ | **Section:** Developer Guides … # メタデータテンプレートの更新 既存のメタデータテンプレートの更新方法を見てみましょう。 メタデータテンプレートの更新は、テンプレート自体を直接変更するのではなく、**操作**を利用して実行されます。この方法では、ファイルおよびフォルダにすでに適用されている既存のメタデータインスタンスを更新できます。 テンプレートの更新の詳細を確認する この場合は、`Name`フィールドが少しあいまいであることを認識しているため、`customerInfo`テンプレートの`Name`フィールドを`Company Name`に変更したいとしましょう。`editField`操作を使用することで、テンプレートと、ファイルまたはフォルダに適用されている可能性のあるテンプレートのすべてのインスタンスのフィールドの`displayName`および`key`を変更できます。 ``` curl -X PUT https://api.box.com/2.0/metadata_templates/enterprise/blueprintTemplate/schema \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -H "content-type: application/json" \ -d '[ { "op": "editField", "fieldKey": "name", "data": { "key": "company_name", "displayName": "Company Name" } } ]' ``` ``` var updates = new List<BoxMetadataTemplateUpdate>() { new BoxMetadataTemplateUpdate() { Op = MetadataTemplateUpdateOp.editField, FieldKey = "name", Data = new { key = "company_name", displayName = "Company Name" } } }; BoxMetadataTemplate updatedTemplate = await client.MetadataManager .UpdateMetadataTemplate(updates, "enterprise", "customerData"); ``` ``` List<MetadataTemplate.FieldOperation> updates = new ArrayList<MetadataTemplate.FieldOperation>(); String editField = "{\"op\":\"editField\",\"fieldKey\":\"name\",\"data\":{\"key\":\"company_name\",\"displayName\":\"Company Name\"}}"; updates.add(new MetadataTemplate.FieldOperation(editField)); MetadataTemplate.updateMetadataTemplate(api, "enterprise", "customerData", updates); ``` ``` template = client.metadata_template('enterprise', 'customerData') updates = template.start_update() updates.edit_field('name', key='company_name', display_name="Company Name") template.update_info(updates) ``` ``` var operations = [ { op: 'editField', fieldKey: 'name', data: { key: 'company_name', displayName: "Company Name" } } ]; client.metadata.updateTemplate( 'enterprise', 'customerData', operations ).then(template => { //.. }); ``` このAPIにより、更新されたメタデータテンプレートが返されます。 ``` { "id": "100ac693-a468-4b37-9535-05984b804dc2", "type": "metadata_template", "templateKey": "customerInfo", "scope": "enterprise_34567", "displayName": "Customer Info", "hidden": false, "copyInstanceOnItemCopy": false, "fields": [ { "id": "5c6a5906-003b-4654-9deb-472583fc2930", "type": "string", "key": "company_name", "displayName": "Company Name", "hidden": false }, { "id": "cf3eb5b8-52ef-456c-b175-44354a27e289", "type": "enum", "key": "industry", "displayName": "Industry", "options": [ {"key": "Technology"}, {"key": "Healthcare"}, {"key": "Legal"} ], "hidden": false }, { "id": "5c6a5906-4654-9deb-003b-472583fc2930", "type": "float", "key": "tav", "displayName": "Total account value", "hidden": false } ] } ``` 操作によってテンプレートを更新した場合は、テンプレートのインスタンスもすべて自動的に更新されるという利点があります。この場合、前の手順で作成したインスタンスは次のようになります。 ``` { "company_name": "Box", "industry": "Technology", "tav": 1000000, "$id": "01234500-12f1-1234-aa12-b1d234cb567e", "$parent": "folder_12345,", "$scope": "enterprise_34567", "$template": "customerInfo", "$type": "customerInfo-6bcba49f-ca6d-4d2a-a758-57fe6edf44d0", "$typeVersion": 2, "$version": 1, "$canEdit": true } ``` メタデータテンプレートを更新しました **Source:** [https://ja.developer.box.com/guides/metadata/quick-start/update-template/](https://ja.developer.box.com/guides/metadata/quick-start/update-template/) --- ### メタデータテンプレートの更新 **Type:** guide | **Category:** メタデータ | **Section:** Developer Guides メタデータテンプレートの更新 メタデータテンプレートを更新するには、操作の配列をPUT /metadata_templates/:scope/:templateKey/schema API… # メタデータテンプレートの更新 メタデータテンプレートを更新するには、操作の配列を[`PUT /metadata_templates/:scope/:templateKey/schema`](e://put_metadata_templates_id_id_schema) APIに渡します。 # 管理者権限が必須 メタデータテンプレートの更新は、管理者権限を持つユーザーに制限されています。つまり、管理者、または管理者から**会社のメタデータテンプレートを作成、編集する**権限が付与されている共同管理者だけがウェブアプリまたはAPIを使用してテンプレートを管理できます。 ## 操作 メタデータテンプレートの更新は、テンプレート自体を直接変更するのではなく、**操作**を利用して実行されます。この方法では、ファイルおよびフォルダにすでに適用されている既存のメタデータインスタンスを更新できます。 ## テンプレートの操作 テンプレートの操作により、テンプレートの詳細またはフィールドが更新されます。一般的に、これらの操作は、あまり影響なくテンプレートインスタンスに適用されるため安全です。 ### テンプレートの編集 `editTemplate`操作では、`displayName`や`copyInstanceOnItemCopy`など、テンプレートの基本プロパティを編集できます。 | パラメータ | | | --- | --- | | data | 変更するプロパティを表すオブジェクト | ``` [ { "op": "editTemplate", "data": { "displayName": "Client", "copyInstanceOnItemCopy": true } } ] ``` これにより、新しい表示名がClientになるようにテンプレートが更新されます。 これは、このテンプレートの既存のインスタンスに影響します。 ### テンプレートへのフィールドの追加 `addField`操作では、テンプレートにフィールドを追加します。 | パラメータ | | | --- | --- | | data | 追加するフィールドを表すオブジェクト | ``` [ { "op": "addField", "data": { "displayName": "Category", "key": "category", "hidden": false, "type": "string" } } ] ``` これにより、`displayName`および`key`が**category**に指定されている、非表示ではない新しい文字列フィールドが追加されます。 これは、このテンプレートの既存のインスタンスに影響します。 ### フィールドの並べ替え `reorderFields`操作では、テンプレート内のフィールドのリストを、リクエストされたフィールドリストに合わせて並べ替えます。 | パラメータ | | | --- | --- | | fieldKeys | リクエストされた順番になっているフィールドキーの新しいリスト | ``` { "op": "reorderFields", "fieldKeys": ["field2", "field1", "field3"] } ``` これにより、テンプレートのフィールドは、最初に`field2`、その後`field1`、`field3`が続くように並べ替えられます。 これは、このテンプレートの既存のインスタンスに影響します。フィールドは並べ替えられますが、フィールドの値はそのまま変わりません。 ## フィールドの操作 フィールドの操作により、テンプレートのスキーマが変換されます。以下に、このAPIで使用できる、以前に割り当てたテンプレートのデータを変更する可能性のある操作のリストを示します。 このような変更は、ファイルの変更ではなくテンプレートの変更としてログに記録されます。 ### フィールドの編集 `editField`操作では、`displayName`、`description`、`key`、`hidden`状態など、フィールドの基本プロパティをいくつでも編集できます。 | パラメータ | | | --- | --- | | data | フィールドに設定する新しいプロパティを表すオブジェクト | | fieldKey | 編集するフィールドのキー | ``` { "op": "editField", "fieldKey": "category", "data": { "displayName": "Customer Group" } } ``` これにより、新しい表示名が**Customer Group**になるようにフィールド`category`が更新されます。このキーが変更された場合、指定されたフィールドの既存の値は新しいキーに移行されます。検索インデックスは更新されますが、更新にかかる時間は、この変更の対象となるファイルの数によって異なります。 これは、このテンプレートの既存のインスタンスに影響する可能性があります。 ### フィールドの削除 `removeField`操作では、テンプレートからフィールドを削除します。 | パラメータ | | | --- | --- | | fieldKey | テンプレートから削除するフィールドのキー | ``` { "op": "removeField", "fieldKey": "brand" } ``` これにより、フィールド`brand`は、テンプレートに加えて、テンプレートのすべてのインスタンスから削除されます。検索インデックスは更新されますが、更新にかかる時間は、この変更の対象となるファイルの数によって異なります。 これは、このテンプレートの既存のインスタンスに影響します。 ## フィールドオプションの操作 [`enum`](g://metadata/fields/enum)および[`multiSelect`](g://metadata/fields/multi-select)メタデータフィールドタイプはどちらも、フィールドのオプションを変更するための追加操作をサポートしています。 | 操作 | | | --- | --- | | addEnumOption | enumフィールドにオプションを追加します | | editEnumOption | enumフィールドのオプションを編集します | | reorderEnumOptions | enumフィールドのオプションを並べ替えます | | removeEnumOption | enumフィールドのオプションを削除します | | addMultiSelectOption | multiSelectフィールドにオプションを追加します | | editMultiSelectOption | multiSelectフィールドのオプションを編集します | | reorderMultiSelectOptions | multiSelectフィールドのオプションを並べ替えます | | removeMultiSelectOption | multiSelectフィールドのオプションを削除します | **Source:** [https://ja.developer.box.com/guides/metadata/templates/update/](https://ja.developer.box.com/guides/metadata/templates/update/) --- ### メタデータによるコンテンツの検索 **Type:** quick-start | **Category:** 検索 | **Section:** Developer Guides メタデータによるコンテンツの検索 BoxメタデータクエリAPIを使用すると、適用したカスタムメタデータ値に厳密に基づき、プログラムによってBoxコンテンツを検索できます。 メタデータクエリの構造は、SQLクエリの構造に似ていて、ブール演算子 (AND、OR、NOT… # メタデータによるコンテンツの検索 BoxメタデータクエリAPIを使用すると、適用したカスタムメタデータ値に厳密に基づき、プログラムによってBoxコンテンツを検索できます。 メタデータクエリの構造は、SQLクエリの構造に似ていて、ブール演算子 (AND、OR、NOTなど) のほか、比較演算子または範囲演算子 (等しい、より大きい、より小さいなど) も使用できます。 メタデータクエリAPIのメリットを以下に示します。 - インデックス作成による遅延がない (つまり、メタデータの作成、更新、削除の直後にクエリを実行) - 1つ以上のフィールドを基準に並べ替え順を指定できる - クエリ可能な文字数に制限がない - クエリで項目プロパティやメタデータインスタンスが返される ## 概要 このガイドでは、以下の手順を説明します。 1. [メタデータテンプレートを作成する](g://search/quick-start/create-metadata-template) 2. APIを使用して[メタデータテンプレートに関する情報を確認する](g://search/quick-start/locate-template-info) 3. 1つ以上のファイルに[メタデータテンプレートを適用する](g://search/quick-start/apply-template-to-file) 4. 手順3のコンテンツを取得する[メタデータクエリAPIコールを作成する](g://search/quick-start/metadata-query-api) 開始する準備ができました **Source:** [https://ja.developer.box.com/guides/search/quick-start/](https://ja.developer.box.com/guides/search/quick-start/) --- ### メタデータの抽出 **Type:** guide | **Category:** CLI | **Section:** Developer Guides メタデータの抽出 このスクリプトでは、任意のBoxフォルダ内のすべてのファイルとフォルダのメタデータの詳細を抽出し、その結果を各メタデータテンプレートのCSVスプレッドシートに保存します。 前提条件 Windows .NET Coreの最新バージョンのインストール macOS… # メタデータの抽出 このスクリプトでは、任意のBoxフォルダ内のすべてのファイルとフォルダのメタデータの詳細を抽出し、その結果を各メタデータテンプレートのCSVスプレッドシートに保存します。 ## 前提条件 ### Windows [.NET Core](https://dotnet.microsoft.com/download)の最新バージョンのインストール ### macOSおよびLinux [PowerShell](https://docs.microsoft.com/en-us/powershell/scripting/install/installing-powershell?view=powershell-7.2)をインストールします。`pwsh`コマンドを実行して、インストール結果をテストします。 ``` pwsh ``` どのディレクトリでこのコマンドを実行するかに応じて、出力が異なる場合があります。以下に例を示します。 ``` PowerShell 7.2.5 Copyright (c) Microsoft Corporation. https://aka.ms/powershell Type 'help' to get help. PS /Users/user/repos/boxcli/examples> ``` 問題が発生する場合は、[.NET Core](https://dotnet.microsoft.com/download)と[PowerShell](https://docs.microsoft.com/en-us/powershell/scripting/install/installing-powershell?view=powershell-7.2)の両方をインストールしたかどうか確認してください。 ### Box CLI スクリプトを使用するには、Box CLIをインストールし、構成する必要があります。これは、[クイックスタートガイド](g://cli/quick-start/create-oauth-app)の手順を実行することで行うことができます。 ## スクリプトの構成 1. `boxcli` GitHubリポジトリを複製してこの例のフォルダにcdコマンドで移動するか、[`examples`](https://github.com/box/boxcli/tree/main/examples/Metadata%20Extraction)ディレクトリからファイルをダウンロードします。 ``` git clone https://github.com/box/boxcli.git cd boxcli/examples/Metadata\ Extraction/ ``` 1. `folderID`および`userID`パラメータを指定して、スキャンするフォルダとスクリプトを実行するユーザーをスクリプトに指示します。 ``` [string]$FolderID = "", [string]$UserID = "", ``` ``` If you don't want to specify the parameters directly in the script, you can either pass them as flags or allow the script to prompt you to enter them. A sample command with flags looks as follows: ``` ``` ./Metadata-extraction.ps1 -folderId 123456789 -userId 123456789 ``` ## スクリプトの実行 1. PowerShellコマンドを実行します。 ``` pwsh ``` 1. スクリプトを実行します。 ``` ./Metadata-extraction.ps1 -folderId 123456789 -userId 123456789 ``` ``` When the script finishes, you will see the following output or a similar one. ``` ``` Pulling data from Folder ID: 173961139760 metadata as user ID: 20718545815 Reading Item ID: 1016853559790 Metadata saved to: MetadataTemplate_properties.csv ``` ## ログ ログは、メインフォルダ内の`logs`フォルダに格納されます。以下のログファイルにアクセスできます。 - `Metadata-extraction_all.txt`: すべてのログエントリが含まれています。 - `Metadata-extraction_errors.txt`: エラーのみが含まれています。 **Source:** [https://ja.developer.box.com/guides/cli/scripts/metadata-extraction/](https://ja.developer.box.com/guides/cli/scripts/metadata-extraction/) --- ### メタデータの操作 **Type:** quick-start | **Category:** メタデータ | **Section:** Developer Guides メタデータの操作 メタデータAPI… # メタデータの操作 メタデータAPIは、アプリケーションがファイルやフォルダに自動的に情報を追加できるようにする優れたツールです。 ## 概要 このガイドでは、以下の手順を説明します。 1. 使用できる[すべてのテンプレートのリストを取得](g://metadata/quick-start/list-all)します。 2. 会社固有のデータを保持する[カスタムメタデータテンプレートを作成](g://metadata/quick-start/create-template)します。 3. ファイルに[カスタムメタデータテンプレートを適用](g://metadata/quick-start/create-instance)し、カスタムデータをファイルに割り当てられるようにします。 4. ファイルの[メタデータインスタンスを更新](g://metadata/quick-start/update-instance)し、ファイルに割り当てられたデータを変更できるようにします。 5. [メタデータテンプレートを更新](g://metadata/quick-start/update-template)し、このテンプレートのすべてのインスタンスに適用されたデータを変更します。 6. [メタデータを使用してファイルを検索するクエリを作成](g://metadata/quick-start/create-query)し、このテンプレートのすべてのインスタンスに適用されたデータを変更します。 開始する準備ができました **Source:** [https://ja.developer.box.com/guides/metadata/quick-start/](https://ja.developer.box.com/guides/metadata/quick-start/) --- ### メタデータフィールド **Type:** guide | **Category:** メタデータ | **Section:** Developer Guides メタデータフィールド メタデータテンプレートフィールドには、メタデータテンプレート内の特定のデータが記載されています。たとえば、請求書のIDをinvoiceDataテンプレートのidフィールドとして表すことができます。 すべてのメタデータテンプレートにはfield… # メタデータフィールド [メタデータテンプレートフィールド](r://metadata-template/#param-fields)には、メタデータテンプレート内の特定のデータが記載されています。たとえば、請求書のIDを`invoiceData`テンプレートの`id`フィールドとして表すことができます。 すべてのメタデータテンプレートには`field`オブジェクトのリストが含まれており、各フィールドは次のいずれかのタイプになります。 | | | | --- | --- | | string | テキストフィールド | | float | 数値入力フィールド | | date | 日付選択フィールド | | enum | 1つの値を選択するためのドロップダウンリスト | | multiSelect | 複数の値を選択するためのドロップダウンリスト | ## 基本的なフィールドタイプ 基本的なフィールドタイプは、テキストフィールドの場合は`string`、数値フィールドの場合は`float`、日時選択フィールドの場合は`date`です。 ## リストのフィールドタイプ さらに、メタデータテンプレートでは、ドロップダウンリストを表す2つのフィールドタイプをサポートしています。`enum`フィールドは、ユーザーが選択できるあらかじめ定義された項目のリストを表すのに対し、`multiSelect`フィールドは、ユーザーが複数の値を選択できる項目のリストを表します。 **Source:** [https://ja.developer.box.com/guides/metadata/fields/](https://ja.developer.box.com/guides/metadata/fields/) --- ### モバイル **Type:** guide | **Category:** モバイル | **Section:** Developer Guides モバイル BoxのモバイルSDKは、iOSプロジェクトやAndroidプロジェクト内からBox APIへのネイティブアクセスを提供します。 # モバイル BoxのモバイルSDKは、iOSプロジェクトやAndroidプロジェクト内からBox APIへのネイティブアクセスを提供します。 **Source:** [https://ja.developer.box.com/guides/mobile/](https://ja.developer.box.com/guides/mobile/) --- ### ユーザー **Type:** guide | **Category:** ユーザー | **Section:** Developer Guides ユーザー Box APIは、管理対象ユーザーアカウントでログインする実際の従業員や、App User… # ユーザー Box APIは、管理対象ユーザーアカウントでログインする実際の従業員や、App Userを使用して強力な自動化ワークフローを推進するアプリケーションなど、さまざまなユーザーをサポートしています。 ユーザータイプの詳細を確認する ## ユーザーのプロビジョニング (プロビジョニング解除) 従業員、顧客、ユーザーのオンボーディングとオフボーディングの管理は、Boxアプリケーションの一般的な要件です。 アカウントのプロビジョニングで必要となる主なタスクは以下のとおりです。 - ユーザーを表す新しいアプリと管理対象ユーザーアカウントを作成する。 - 共通の、または繰り返しが可能なフォルダおよびファイルアーキテクチャを使用して、新しいユーザーアカウントをインスタンス化する。 アカウントのプロビジョニング解除で必要となる主なタスクは以下のとおりです。 - オフボーディングのため、1つのアカウントから別のアカウントにファイルとフォルダを転送する。 - ユーザーアカウントを削除する。 **Source:** [https://ja.developer.box.com/guides/users/](https://ja.developer.box.com/guides/users/) --- ### ユーザーアクセストークン **Type:** guide | **Category:** 認証 | **Section:** Developer Guides ユーザーアクセストークン JWT… # ユーザーアクセストークン JWTアプリケーションは、[サービスアカウント](page://platform/user-types/#service-account)ではなく特定のユーザーに対してアクセストークンを作成できます。 ## 前提条件 アプリケーションは、ユーザーアクセストークンの作成を許可するように構成する必要があります。この設定は、[開発者コンソール](https://app.box.com/developers/console)の [**構成**] タブにあります。 さらに、認証済みユーザーは、管理者権限を持つユーザー、つまり、管理者、共同管理者、サービスアカウントのいずれかである必要があります。詳細については、[ユーザータイプ](page://platform/user-types)のガイドを参照してください。 ## SDKを使用したユーザーアクセストークン 特定のユーザーとして認証するBox SDKクライアントを作成するには、[SDKを使用したJWTのガイド](g://authentication/jwt/with-sdk)で説明されている手順に従います。ただし、「Enterprise」クライアントではなく、ユーザークライアントを作成します。 ``` var userId = "12345"; var sdk = new BoxJWTAuth(config); var token = sdk.UserToken(appUserID); BoxClient client = sdk.UserClient(userToken, userId); ``` ``` String userId = "12345"; BoxDeveloperEditionAPIConnection api = new BoxDeveloperEditionAPIConnection.getAppUserConnection(userId, config) ``` ``` user = client.user(user_id='12345') auth = JWTAuth( client_id='[CLIENT_ID]', client_secret='[CLIENT_SECRET]', user=app_user, jwt_key_id='[JWT_KEY_ID]', rsa_private_key_file_sys_path='[CERT.PEM]', rsa_private_key_passphrase='[PASSPHRASE]' ) auth.authenticate_user() user_client = Client(auth) ``` ``` var sdk = BoxSDK.getPreconfiguredInstance(config); var client = sdk.getAppAuthClient('user', '12345'); ``` Box SDKとJWTの使用の詳細を確認する ## SDKを使用しないユーザーアクセストークン 特定のユーザーとして認証するユーザーアクセストークンを作成するには、[SDKを使用しないJWTのガイド](g://authentication/jwt/without-sdk)で説明されている手順に従います。ただし、企業用のクレームを作成するのではなく、特定のユーザーID用のクレームを作成します。 ``` var userId = "12345"; var claims = new List<Claim>{ new Claim("sub", userid), new Claim("box_sub_type", "user"), new Claim("jti", jti), }; ``` ``` String userId = "12345"; JwtClaims claims = new JwtClaims(); claims.setIssuer(config.boxAppSettings.clientID); claims.setAudience(authenticationUrl); claims.setSubject(userId); claims.setClaim("box_sub_type", "user"); claims.setGeneratedJwtId(64); claims.setExpirationTimeMinutesInTheFuture(0.75f); ``` ``` user_id = '12345' claims = { 'iss': config['boxAppSettings']['clientID'], 'sub': user_id, 'box_sub_type': 'user', 'aud': authentication_url, 'jti': secrets.token_hex(64), 'exp': round(time.time()) + 45 } ``` ``` let user_id = '12345'; let claims = { iss: config.boxAppSettings.clientID, sub: user_id, box_sub_type: "user", aud: authenticationUrl, jti: crypto.randomBytes(64).toString("hex"), exp: Math.floor(Date.now() / 1000) + 45 }; ``` ``` user_id = '12345' claims = { iss: config['boxAppSettings']['clientID'], sub: user_id, box_sub_type: 'user', aud: authentication_url, jti: SecureRandom.hex(64), exp: Time.now.to_i + 45 } ``` ``` $userId = '12345'; $claims = [ 'iss' => $config->boxAppSettings->clientID, 'sub' => $userId, 'box_sub_type' => 'user', 'aud' => $authenticationUrl, 'jti' => base64_encode(random_bytes(64)), 'exp' => time() + 45, 'kid' => $config->boxAppSettings->appAuth->publicKeyID ]; ``` 手動によるJWT認証の使用の詳細を確認する **Source:** [https://ja.developer.box.com/guides/authentication/jwt/user-access-tokens/](https://ja.developer.box.com/guides/authentication/jwt/user-access-tokens/) --- ### ユーザーエクスペリエンス **Type:** guide | **Category:** アプリケーション | **Section:** Developer Guides ユーザーエクスペリエンス 以下に、ユーザーの視点からウェブアプリ統合がどのように見えるかについて説明します。 Boxユーザーは、Box統合でアプリケーションを見つけることができます。直接統合にアクセスするか、BoxウェブアプリのUI… # ユーザーエクスペリエンス 以下に、ユーザーの視点からウェブアプリ統合がどのように見えるかについて説明します。 1. Boxユーザーは、Box統合でアプリケーションを見つけることができます。直接統合にアクセスするか、BoxウェブアプリのUIで [**統合**] メニューを選択できます。 2. ユーザーは統合で、追加したいアプリケーションを選択します。公開されているどのBoxアプリケーションにも公開プロフィールページが用意されており、提供する統合などの詳細が示されています。 3. ユーザーは統合のリストで [**追加**] ボタンをクリックすることで、自分のアカウントにアプリケーションを追加します。アプリケーションがアカウントに追加されると、ユーザーはそのすべての統合を使用できるようになります。 4. ファイルまたはフォルダの [**その他の操作**] メニューで、統合を選択します。 5. ユーザーは、Boxから、ファイルまたはフォルダをアプリケーションと共有してよいか許可を求められます。統合を問題なく使用できるようにするには、確認プロンプトを受け入れる必要があります。 6. アクセスを許可すると、Boxからアプリケーションにデータが渡されます。その後、統合の種類に応じて、アプリケーションはポップアップパネルを表示したり、サーバーベースのプロセスを実行したりします。 **Source:** [https://ja.developer.box.com/guides/applications/web-app-integrations/user-experience/](https://ja.developer.box.com/guides/applications/web-app-integrations/user-experience/) --- ### ユーザーとのコンテンツの共有 **Type:** guide | **Category:** コラボレーション | **Section:** Developer Guides ユーザーとのコンテンツの共有 コンテンツをユーザーと共有するには、ユーザーIDまたはメールアドレス、コンテンツのIDのほか、ユーザーがコンテンツにアクセスする際に必要なロールまたは権限を使用してコラボレーションを作成します。コラボレーションロールはeditor、viewer… # ユーザーとのコンテンツの共有 コンテンツをユーザーと共有するには、ユーザーIDまたはメールアドレス、コンテンツのIDのほか、ユーザーがコンテンツにアクセスする際に必要なロールまたは権限を使用してコラボレーションを作成します。コラボレーションロールは`editor`、`viewer`、`previewer`、`uploader`、`previewer uploader`、`viewer uploader`、`co-owner`、または`owner`です。各ロールについての詳しい説明は、Boxの[サポートドキュメント](https://support.box.com/hc/ja/articles/360044196413-%E3%82%B3%E3%83%A9%E3%83%9C%E3%83%AC%E3%83%BC%E3%82%BF%E3%81%AE%E6%A8%A9%E9%99%90%E3%83%AC%E3%83%99%E3%83%AB%E3%81%AB%E3%81%A4%E3%81%84%E3%81%A6)を参照してください。 ## ネストされたオブジェクト コラボレーションの作成時には、リクエスト本文に`accessible_by`と`item`という2つのネストされたオブジェクトを使用します。 `accessible_by`オブジェクトは、この項目の共有相手を指定し、グループ`id`と`type`を含みます。`type`フィールドは常に`user`に設定する必要があります。 `item`オブジェクトは、共有する項目を指定します。このオブジェクトには、`file`として設定する必要がある`type`フィールドと、そのファイルの`id`フィールドがあります。 **Source:** [https://ja.developer.box.com/guides/collaborations/share-content/](https://ja.developer.box.com/guides/collaborations/share-content/) --- ### ユーザーとフォルダのプロビジョニング **Type:** guide | **Category:** CLI | **Section:** Developer Guides ユーザーとフォルダのプロビジョニング このスクリプトでは、Box CLI… # ユーザーとフォルダのプロビジョニング このスクリプトでは、Box CLIを使用して、個人用フォルダ構造の作成と管理対象ユーザーの一括作成を実行し、新しく作成したフォルダ構造に新しいユーザーをビューアー/アップローダーのロールを持つコラボレータとして追加することでそのユーザーのプロビジョニングを行います。 詳細については、クイックスタートガイドで[Box CLIの使い方とサンプルスクリプト](g://cli/quick-start/powershell-script-templates)を参照してください。 **Source:** [https://ja.developer.box.com/guides/cli/scripts/provision-users-folders/](https://ja.developer.box.com/guides/cli/scripts/provision-users-folders/) --- ### ユーザーのWebhookのリストを取得 **Type:** guide | **Category:** Webhook | **Section:** Developer Guides ユーザーのWebhookのリストを取得 認証済みユーザーのすべてのWebhookを取得するには、すべてのWebhookのリストを取得エンドポイントを使用します。 このエンドポイントを使用するには、アプリケーションの [Webhook… # ユーザーのWebhookのリストを取得 認証済みユーザーのすべてのWebhookを取得するには、[すべてのWebhookのリストを取得](endpoint://get_webhooks)エンドポイントを使用します。 このエンドポイントを使用するには、アプリケーションの [**Webhookを管理する**] スコープが有効になっている必要があります。 このAPIコールは、認証済みユーザーのWebhookのみをリストし、会社内の他のユーザーのWebhookはリストしません。 **Source:** [https://ja.developer.box.com/guides/webhooks/v2/list-v2/](https://ja.developer.box.com/guides/webhooks/v2/list-v2/) --- ### ユーザーのコレクションのリストの取得 **Type:** guide | **Category:** コレクション | **Section:** Developer Guides ユーザーのコレクションのリストの取得 ユーザーのすべてのコレクションのリストを取得するには、GET /collections APIを呼び出します。 APIを介して使用できるコレクションは「お気に入り」コレクションのみです。このコレクションのID… # ユーザーのコレクションのリストの取得 ユーザーのすべてのコレクションのリストを取得するには、[`GET /collections`](e://get_collections) APIを呼び出します。 APIを介して使用できるコレクションは「お気に入り」コレクションのみです。このコレクションのIDはユーザーごとに異なります。 ## お気に入りコレクション 現在APIを介して項目を追加および削除できるコレクションは「お気に入り」コレクションのみです。 お気に入りコレクションのIDはユーザーごとに異なります。ユーザーのお気に入りのコレクションIDを確認するには、ユーザーの全コレクションのリストを取得し、`collection_type`が`favorites`のコレクションを探します。 ``` { "entries": [ { "collection_type": "favorites", "id": "12345678", "name": "Favorites", "type": "collection" } ], "limit": 100, "offset": 0, "total_count": 1 } ``` **Source:** [https://ja.developer.box.com/guides/collections/list/](https://ja.developer.box.com/guides/collections/list/) --- ### ユーザーのゾーンの更新 **Type:** guide | **Category:** CLI | **Section:** Developer Guides ユーザーのゾーンの更新 このスクリプトは、マルチゾーンのBox… # ユーザーのゾーンの更新 この[スクリプト](https://github.com/box/boxcli/tree/main/examples/Mass%20Update%20User%20Zones)は、マルチゾーンのBoxテナント内の特定のデータ保管場所のゾーンにユーザーをプロビジョニングします。スクリプトによって以下の手順が実行されます。 1. 管理者または共同管理者のログインメールアドレスを使用して、関連付けられた企業とその企業に割り当てられているゾーンポリシーを検索します。割り当てられているゾーンポリシーは、特に指定がない限り、すべてのユーザーが継承します。これは、**デフォルトゾーン**とも呼ばれることもあります。 2. ユーザーのメールアドレスとゾーンマッピングが含まれる入力`.csv`ファイルに基づいて、ゾーン割り当てを行います。 通常、このスクリプトはユーザーのゾーンを初めてプロビジョニングするときに1回使用します。ただし、ゾーンの割り当てを更新するために、以降の実行でも使用できます。 ゾーンの割り当てに管理コンソールを使用する場合は、[こちらのガイド](https://support.box.com/hc/en-us/articles/360044193533-Assigning-Zones-through-the-Admin-Console)を参照してください。Box Zonesの詳細については、[公式ウェブサイト](https://www.box.com/zones)を参照してください。 ## 前提条件 ### Windows [.NET Core](https://dotnet.microsoft.com/download)の最新バージョンのインストール ### macOSおよびLinux [PowerShell](https://docs.microsoft.com/en-us/powershell/scripting/install/installing-powershell?view=powershell-7.2)をインストールします。`pwsh`コマンドを実行して、インストール結果をテストします。 ``` pwsh ``` どのディレクトリでこのコマンドを実行するかに応じて、出力が異なる場合があります。以下に例を示します。 ``` PowerShell 7.2.5 Copyright (c) Microsoft Corporation. https://aka.ms/powershell Type 'help' to get help. PS /Users/user/repos/boxcli/examples> ``` 問題が発生する場合は、[.NET Core](https://dotnet.microsoft.com/download)と[PowerShell](https://docs.microsoft.com/en-us/powershell/scripting/install/installing-powershell?view=powershell-7.2)の両方をインストールしたかどうか確認してください。 ### JWT認証を使用するアプリケーションの設定 このスクリプトを使用するには、[JWT認証を使用するBox CLI](g://cli/cli-docs/jwt-cli)をインストールし、構成する必要があります。 アプリを作成する際は、[**構成**] タブで以下の設定を構成します。 - [**アプリアクセスレベル**] で [`App + Enterprise Access`] を選択します。 - [**アプリケーションスコープ**] > [**管理操作**] の順に移動して、[`Manage Enterprise Properties`]、[`Manage Users`] を選択します。 - [**高度な機能**] で [`Generate user access tokens`] を選択します。 ### 管理者設定の調整 Boxの管理者または共同管理者に`Manage Users`以上の権限があることを確認します。この設定を確認するには、以下の手順に従います。 1. 管理コンソールの [**ユーザーとグループ**] セクションに移動します。 2. 確認するユーザーアカウントをクリックします。 3. [**ユーザーアクセス権限を編集**] セクションに移動して、ユーザーとグループに管理者権限を付与します。 ## .csvファイルの準備 `.csv`ファイルには、**Email**と**Region**というヘッダーを設定した2つの列が必要です。 - **Email**列には、Boxユーザーのプライマリメールアドレスを含めます。 - **Region**列には、スクリプトでユーザーを割り当てるゾーンのユーザーフレンドリ名 (ユーザーが理解しやすい名前) を含めます。この名前は、ゾーンの定義に使用する[ZonesTable](https://github.com/box/boxcli/blob/main/examples/Mass%20Update%20User%20Zones/Mass_Update_User_Zones.ps1#L23)というハッシュテーブルで指定します。キーはゾーンのユーザーフレンドリ名であり、対応する値はゾーンのグローバルIDです。 ``` $ZonesTable = @{ US = "100001" #US GermanyIreland = "100002" #Germany/Ireland with in region uploads/downloads/previews Australia = "100003" #Australia Japan = "100004" #Japan with in region uploads/downloads/previews Canada = "100005" #Canada JapanSingapore = "100007" #Japan/Singapore with in region uploads/downloads/previews UKGermany = "100008" #UK/Germany UK = "100009" #UK with in region uploads/downloads/previews France = "100012" #France } ``` 特定の企業で有効なゾーンに対応するIDを入手するには、Box Consultingまたはカスタマーサクセスマネージャまでお問い合わせください。 このスクリプトには、以下のようなメールアドレスとゾーン名が含まれているサンプル入力`.csv`ファイルが用意されています。 | Email | Region | | --- | --- | | betty@company.com | US | | roger@company.com | France | | sally@company.com | JapanSingapore | ## スクリプトの構成 この`.csv`ファイルを指すように`UserZonesUpdatePath`を設定します。 ``` $UserZonesUpdatePath = "./your_file_name.csv" ``` `adminEmail`を、このスクリプトでゾーンの割り当てに使用するアカウントの管理者または`co-admin`のログインメールアドレスに更新します。この値を指定しない場合、スクリプト実行時に指定するよう求められます。 ``` $adminEmail = "john@box.com" ``` ## スクリプトの実行 PowerShellコマンドを実行します。 ``` pwsh ``` スクリプトを実行します。 ``` ./Mass_Update_User_Zones.ps1 ``` ### オプションのフラグ シミュレーションモードでスクリプトを実行するには、`DryRun`ブール値フラグを追加します。ドライランでは、APIコールが実行されないというわけではありませんが、作成/更新/削除のコールはすべてスキップされます。 ``` ./Mass_Update_User_Zones.ps1 -DryRun ``` ## ログ ログは、メインフォルダ内の`logs`フォルダに格納されます。以下のログファイルにアクセスできます。 - `Mass_Update_User_Zones_all.txt`: すべてのログエントリが含まれています。 - `Mass_Update_User_Zones_errors.txt`: エラーのみが含まれています。 **Source:** [https://ja.developer.box.com/guides/cli/scripts/user-zones-mass-update/](https://ja.developer.box.com/guides/cli/scripts/user-zones-mass-update/) --- ### ユーザーのプロビジョニング **Type:** guide | **Category:** ユーザー | **Section:** Developer Guides ユーザーのプロビジョニング 新しいBox… # ユーザーのプロビジョニング 新しいBoxユーザーアカウントを設定する際、一般にはこの新しいアカウントに標準のフォルダ、コラボレーション、グループ関連付けを作成する必要があります。 通常、アカウントの標準設定が必要なタイミングを判断するには、ユーザーアカウントについて以下の事項を検討します。 - ユーザーが標準の会社のファイルまたはフォルダに即座にアクセスする必要があるか。 - コラボレーションを個別に関連付けるか、グループを介して関連付けるか。グループの関連付けを介する場合、ユーザーを追加する必要がある標準グループがあるか。 - ユーザーに完了すべきタスクを割り当てる必要があるか。 - ファイルに関する説明的なコメントが役に立つか。 # 新しいユーザーのパスワードリセットとメール確認 ユーザーを作成した後、すぐにAPIを介してそのユーザーによるアクションを実行しようとすると、エラーが発生する場合があります。たとえば、`user_email_confirmation_required`や`password_reset_required`といったエラーがよく発生します。このようなエラーが発生するとAPI内の一部のアクションがブロックされる場合がありますが、そのユーザーをフォルダのコラボレータとして追加したり、グループに追加したりすることはできます。 ## サンプル概要 Box App Userアカウントをプロビジョニングする際の注意事項は非常に多岐にわたるため、このシナリオでは、新しい[Box管理対象ユーザー](page://platform/user-types/#managed-users)のプロビジョニングを中心に検討します。 初めに、ユーザーアカウントのプロビジョニングで繰り返せる部分の大半を解決し、すべてのユーザーが最初にログインした時点で与えられる一般的なフォルダおよびファイル構造を作成し、グループを使用してユーザーの共有ファイルとフォルダへのアクセスを制御します。 **Source:** [https://ja.developer.box.com/guides/users/provision/](https://ja.developer.box.com/guides/users/provision/) --- ### ユーザーのプロビジョニング解除 **Type:** guide | **Category:** ユーザー | **Section:** Developer Guides ユーザーのプロビジョニング解除 通常のBox Enterprise… # ユーザーのプロビジョニング解除 通常のBox Enterpriseの保守の一部として、会社内でアクティブではなくなったユーザーのアカウントを削除します。会社からユーザーを削除する際は、ユーザーアカウントを削除する前に、そのユーザーが所有するすべてのコンテンツを別のアカウントに移動する必要があります。 ユーザーアカウントにまだコンテンツがある場合、ユーザー削除リクエストは失敗します。ユーザーアカウントとアカウント内のすべてのコンテンツを強制的に削除するオプションである`force`パラメータを、APIコールで使用できます。 ユーザーアカウントを廃止する際の標準的なベストプラクティスは、そのユーザーが所有するすべてのコンテンツを別の管理者レベルアカウントまたはアプリケーションサービスアカウントに移動することです。移動したら、コンテンツの所有権を別のユーザーに移管するか、必要に応じてそのコンテンツで別のユーザーとコラボレーションをすることができます。 ## プロビジョニング解除の例 以下のコードサンプルを使用して、ユーザーのコンテンツを転送し、ユーザーを削除できます。コンテンツが転送される際には、次のパターンに従って転送先ユーザーのルートフォルダに新しいフォルダが作成されます。`employee_email@email.com - employee_name's Files and Folders` ``` 'use strict' const box = require('box-node-sdk'); const fs = require('fs'); let configFile = fs.readFileSync('config.json'); configFile = JSON.parse(configFile); let session = box.getPreconfiguredInstance(configFile); let serviceAccountClient = session.getAppAuthClient('enterprise'); const transferUserID = '3278487052'; (async () => { let serviceAccount = await serviceAccountClient.users.get('me'); let transferredFolder = await serviceAccountClient.enterprise.transferUserContent(transferUserID,serviceAccount.id); console.log(transferredFolder); await serviceAccountClient.users.delete(transferUserID, null); console.log('Completed'); })(); ``` ``` Path configPath = Paths.get("config.json"); try (BufferedReader reader = Files.newBufferedReader(configPath,Charset.forName("UTF-8"))){ String transferUserId = "3277722534"; BoxConfig boxConfig = BoxConfig.readFrom(reader); BoxDeveloperEditionAPIConnection serviceAccountClient = BoxDeveloperEditionAPIConnection .getAppEnterpriseConnection(boxConfig); BoxUser destinationUser = new BoxUser(serviceAccountClient, BoxUser.getCurrentUser(serviceAccountClient).getID()); try { destinationUser.moveFolderToUser(transferUserId); } catch (BoxAPIException e) {} BoxUser removeUser = new BoxUser(serviceAccountClient, transferUserId); removeUser.delete(false, false); } ``` ``` using(FileStream fs = new FileStream("./config.json", FileMode.Open)) { var config = BoxConfig.CreateFromJsonFile(fs); var session = new BoxJWTAuth(config); var serviceAccountClient = session.AdminClient(session.AdminToken()); var transferUserId = "3276247601"; var serviceAccount = await serviceAccountClient.UsersManager.GetCurrentUserInformationAsync(); var moveAction = await serviceAccountClient.UsersManager.MoveUserFolderAsync(transferUserId,serviceAccount.Id); System.Console.WriteLine(moveAction.Name); await serviceAccountClient.UsersManager.DeleteEnterpriseUserAsync(transferUserId,false,false); } ``` ``` box users:transfer-content $transfer_from_user_id $transfer_to_user_id box users:delete $transfer_from_user_id --yes ``` **Source:** [https://ja.developer.box.com/guides/users/deprovision/](https://ja.developer.box.com/guides/users/deprovision/) --- ### ユーザーのプロビジョニング解除とフォルダのアーカイブ **Type:** guide | **Category:** CLI | **Section:** Developer Guides ユーザーのプロビジョニング解除とフォルダのアーカイブ このスクリプトを使用すると、ユーザーのリストによるプロビジョニング解除と削除が可能です。スクリプトでは以下の手順が実行されます。 EmployeeArchiveFolderName… # ユーザーのプロビジョニング解除とフォルダのアーカイブ このスクリプトを使用すると、ユーザーのリストによるプロビジョニング解除と削除が可能です。スクリプトでは以下の手順が実行されます。 1. `EmployeeArchiveFolderName`パラメータで指定された、別のユーザーのルートフォルダにユーザーコンテンツを転送します。 2. ユーザーを削除します。 ## 前提条件 ### Windows [.NET Core](https://dotnet.microsoft.com/download)の最新バージョンのインストール ### macOSおよびLinux [PowerShell](https://docs.microsoft.com/en-us/powershell/scripting/install/installing-powershell?view=powershell-7.2)をインストールします。`pwsh`コマンドを実行して、インストール結果をテストします。 ``` pwsh ``` どのディレクトリでこのコマンドを実行するかに応じて、出力が異なる場合があります。以下に例を示します。 ``` PowerShell 7.2.5 Copyright (c) Microsoft Corporation. https://aka.ms/powershell Type 'help' to get help. PS /Users/user/repos/boxcli/examples> ``` 問題が発生する場合は、[.NET Core](https://dotnet.microsoft.com/download)と[PowerShell](https://docs.microsoft.com/en-us/powershell/scripting/install/installing-powershell?view=powershell-7.2)の両方をインストールしたかどうか確認してください。 ### Box CLI スクリプトを使用するには、Box CLIをインストールし、構成する必要があります。これは、[クイックスタートガイド](g://cli/quick-start/create-oauth-app)の手順を実行することで行うことができます。ログインに使用するユーザーは、Boxのメイン管理者または共同管理者である必要があります。 ## スクリプトの構成 1. `boxcli` GitHubリポジトリを複製してこの例のフォルダにcdコマンドで移動するか、[`examples`](https://github.com/box/boxcli/tree/main/examples/User%20Deprovisioning)ディレクトリからファイルをダウンロードします。 ``` git clone https://github.com/box/boxcli.git boxcli cd boxcli/examples/User\ Deprovisioning/ ``` 削除する従業員のリストを`.csv`で作成します。 ヘッダー行は次のようになります。 ``` name, email ``` ``` where: * `name` is the name of the user in Box. * `email` is the primary email address of the user in Box. For example: |`name`| `email`| |------|--------| |Managed User 1| `ManagedUser1@test.com`| |Managed User 2| `ManagedUser2@test.com`| |Managed User 3| `ManagedUser3@test.com`| ``` ### パラメータのリスト | Parameter | Description | Required | Default Value | | --- | --- | --- | --- | | EmployeeList | 削除する従業員が記載された従業員リストCSVのパス。 | はい | - | | SkipTransferContent | このフラグを設定すると、スクリプトの実行時に、削除前にユーザーコンテンツの転送をスキップします。設定しない場合は、ユーザーのコンテンツが転送されます。 | いいえ | False | | NewFilesOwnerID | ユーザーの削除前にファイルの転送先となるユーザーのID。指定しなかった場合、スクリプトは、対話形式で入力を求めるか、現在認証されているユーザーのIDを使用してコンテンツを受け取ります。 | いいえ | 指定しなかった場合、スクリプトは、対話形式で入力を求めるか、現在認証されているユーザーのIDを使用します。 | | EmployeeArchiveFolderName | SkipTransferContentがFalseに設定されている場合にユーザーのコンテンツの移動先となるフォルダの名前。この名前のフォルダがそのユーザーのNewFilesOwnerIDルートフォルダにすでに存在する場合は、そのフォルダが使用されます。存在しない場合は、新しいフォルダが作成されます。 | はい | Employee Archive | | DryRun | 削除/作成/更新の呼び出しは行われず、読み取りの呼び出しのみが行われるモードでスクリプトを実行するかどうかを決定するフラグ。 | いいえ | False | ### スクリプトのパラメータの定義 パラメータを渡すには、以下のオプションを使用できます。 スクリプトでハードコードされた値を使用します。 このオプションを使用するには、実行する前に、[スクリプトのパラメータセクション](https://github.com/box/boxcli/tree/main/examples/User%20Deprovisioning/Users_Deprovision.ps1#L17-L36)に記載されている必須パラメータをすべて更新します。 パラメータを指定してスクリプトを実行します。 コマンドを指定するときにパラメータを指定できます。以下に例を示します。 ``` PS > ./Users_Deprovision.ps1 -EmployeeList ./Employees_to_delete.csv ` -NewFilesOwnerID 123456789 -EmployeeArchiveFolderName "Employee Archive" ``` ``` or ``` ``` PS > ./Users_Deprovision.ps1 -EmployeeList ./Employees_to_delete.csv ` -SkipTransferContent ``` ``` If you don't specify parameters, the script will prompt you to enter it. ``` ``` PS > ./Users_Deprovision.ps1 Please enter the path to the employee list CSV file: ./Employees_to_delete.csv Please specify the user ID of the user who will own the files of the users being deprovisioned. Press Enter if you want to use the current user as the new owner. User ID: 1234567689 Starting User Deprovisioning script... ``` ## スクリプトの実行 これで、あとはスクリプトを実行するだけです。 1. PowerShellコマンドを実行します。 ``` pwsh ``` 1. スクリプトを実行します: ``` ./Users_Deprovision.ps1 ``` ``` When all parameters are defined, you will see following output to confirm the script started: ``` ``` PS /home/rvb/box-cli/examples/User Deprovisioning> ./Users_Deprovision.ps1 Starting User Deprovisioning script... ``` ## ログ ログは、メインフォルダ内の`logs`フォルダに格納されます。以下のログファイルにアクセスできます。 - `Users_Deprovision_all.txt`: すべてのログエントリが含まれています。 - `Users_Deprovision_errors.txt`: エラーのみが含まれています。 **Source:** [https://ja.developer.box.com/guides/cli/scripts/deprovision-users/](https://ja.developer.box.com/guides/cli/scripts/deprovision-users/) --- ### ユーザーの削除 **Type:** guide | **Category:** ユーザー | **Section:** Developer Guides ユーザーの削除 App Userと管理対象ユーザーの削除プロセスは同じです。ユーザーアカウントを削除するには、削除するアカウントのユーザーIDを指定します。 ユーザーアカウントを削除するときに設定できるオプションパラメータも2つあります。 force… # ユーザーの削除 App Userと管理対象ユーザーの削除プロセスは同じです。ユーザーアカウントを削除するには、削除するアカウントのユーザーIDを指定します。 ユーザーアカウントを削除するときに設定できるオプションパラメータも2つあります。 - force: アカウントにまだコンテンツがある場合でも、ユーザーを削除するかどうか。 - notify: アカウントが削除されたという通知をユーザーに送信するかどうか。 ユーザーアカウントにまだコンテンツがある場合、ユーザー削除リクエストは失敗します。これを解決するには、別のアカウントに[すべてのファイルまたはフォルダを転送する](g://users/deprovision/transfer-folders)か、オプションの`force`パラメータを使用します。 **Source:** [https://ja.developer.box.com/guides/users/delete-user/](https://ja.developer.box.com/guides/users/delete-user/) --- ### ユーザーへのタスクの割り当て **Type:** guide | **Category:** タスク | **Section:** Developer Guides ユーザーへのタスクの割り当て ユーザーにタスクを割り当てるには、POST /task_assignments APIにタスクのidとユーザーの詳細を指定する必要があります。ユーザーについては、アプリケーションはユーザーidまたはユーザーのログインメールを使用できます。これはBox… # ユーザーへのタスクの割り当て ユーザーにタスクを割り当てるには、[`POST /task_assignments`](e://post_task_assignments) APIにタスクの`id`とユーザーの詳細を指定する必要があります。ユーザーについては、アプリケーションはユーザー`id`またはユーザーのログインメールを使用できます。これはBoxではユーザーの`login`と呼ばれます。 # 通知 タスクを作成すると、そのタスクが割り当てられるユーザーにメール通知が送信されます。 # 権限 タスクを割り当てるユーザーとタスクが割り当てられるユーザーの両方が、ファイルのコラボレータである必要があります。 **Source:** [https://ja.developer.box.com/guides/tasks/assignments/assign/](https://ja.developer.box.com/guides/tasks/assignments/assign/) --- ### よくある質問 **Type:** guide | **Category:** Boxの埋め込み | **Section:** Developer Guides よくある質問 Box Viewのしくみを教えてください。 新しいBox Viewを使用するには、こちらのガイドに従ってください。 埋め込みリンクとUI Element… # よくある質問 **Box Viewのしくみを教えてください。** 新しいBox Viewを使用するには、[こちら](guide://embed/box-view/setup)のガイドに従ってください。 **埋め込みリンクとUI Elementのうち、どちらのプレビュー方法が用途に適していますか?** [こちら](guide://embed/box-view/create-preview)のガイドに従い、自分のユースケースに最適な方法を選択してください。 **Box Viewでサポートされているファイルタイプを教えてください。**サポートされているファイルタイプについては、[サポート記事](https://support.box.com/hc/ja/articles/360043695794-Box-Content-Preview%E3%81%A7%E3%82%B5%E3%83%9D%E3%83%BC%E3%83%88%E3%81%95%E3%82%8C%E3%82%8B%E3%83%95%E3%82%A1%E3%82%A4%E3%83%AB)を参照してください。 **Box Viewを使用するモバイルでサポートされていないファイルタイプを教えてください。** - ウェブプレビューでサポートされているドキュメントはすべて、モバイルブラウザ (iOSのSafariとChrome) でサポートされます。 - モバイル向けの注釈の全面的なサポートは、Boxの注釈を活用する[コンテンツプレビューUI Element](guide://embed/ui-elements/preview)を介して利用できます。 - モバイルSDK (iOSおよびAndroid用) では、360度動画/画像、および3Dがサポートされていません。 - モバイルSDK (iOSおよびAndroid用) では、注釈 (読み取りと書き込み両方) がサポートされていません。 **注釈とは何ですか?** [注釈](g://embed/ui-elements/annotations)とは、ファイルにレンダリングされるマークアップメモです。開発者は、これを使用して、アプリケーションに埋め込まれたBoxプレビュー内から直接コラボレーション機能を提供できます。 **ファイルのアップロード後にアプリケーションでファイルレプリゼンテーションを取得するにはどうすればよいですか?** [Boxのレプリゼンテーション](guide://representations)を使用すると、Boxに保存されているファイル用に作成されたデジタルアセットを取得できます。これらのエンドポイントを使用することで、ファイルのPDF、テキスト、画像、およびサムネイルという種類のレプリゼンテーションを取得できます。 **Box ViewをBox以外のストレージプロバイダとともに使用できますか?** 現在、Box Viewと互換性があるのは、Boxに保存されているファイルだけです。表示する必要がなくなったファイルは、Boxから削除できます。ただし、プレビューを生成するには再度ファイルをアップロードする必要があります。そのため、少なくともファイルを表示できるようにしたい間は、Boxにファイルを保存しておくことをお勧めします。 **Box UI Elementを埋め込むときに発生するCORSエラーを修正する方法を教えてください。** [CORS](g://security/cors)エラーを修正するには、アプリケーションの構成ページで、CORSリクエストの作成を許可する各ドメインを追加します。サブドメインを表すためにワイルドカードがサポートされています (`https://*.domain.com`)。詳細については、[CORSガイド](g://security/cors)を参照してください。 **プレビューに表示されるBoxのロゴを置き換えるにはどうすればよいですか?** [プレビューUI Element](g://embed/ui-elements/logo)内でのロゴのカスタマイズについては、このガイドを参照してください。 **Source:** [https://ja.developer.box.com/guides/embed/box-view/faq/](https://ja.developer.box.com/guides/embed/box-view/faq/) --- ### リーガルホールド **Type:** guide | **Category:** リーガルホールド | **Section:** Developer Guides リーガルホールド リーガルホールドとは、係争中の訴訟や当然予期される訴訟で、関連する可能性のあるさまざまな形式の情報を会社が保全するために利用できるプロセスのことです。項目にホールドを適用すると、どのユーザーもBox… # リーガルホールド リーガルホールドとは、係争中の訴訟や当然予期される訴訟で、関連する可能性のあるさまざまな形式の情報を会社が保全するために利用できるプロセスのことです。項目にホールドを適用すると、どのユーザーもBoxから項目を削除できなくなります。 リーガルホールドの管理とフォルダやファイルへの割り当ては、Box APIを介して実行できます。 リーガルホールドは、Business Plus、Enterprise Advanced、またはEnterpriseアカウントに追加できる、[Box Governance](https://www.box.com/security/governance-and-compliance)パッケージの機能です。 ## ポリシー、割り当て、およびホールド リーガルホールドポリシーを操作するには、開発者は3つの異なるリソースを使用する必要があります。 - **ポリシー:** [リーガルホールドポリシー](r://legal_hold_policy)には、ホールドの一般的な動作が記載されています。これにより、ファイルの作成日時または更新日時に基づいて、影響を受けるファイルが特定されます。 - **割り当て:** [リーガルホールドポリシー割り当て](r://legal-hold-policy-assignment)は、ポリシーとカストディアンの関係です。この場合、カストディアンにはユーザー、フォルダ、ファイル、またはファイルバージョンを指定できます。割り当てを作成すると、そのカストディアンに属するすべてのファイルバージョンにホールドが適用されます。たとえば、フォルダに割り当てが作成されると、ポリシーはそのフォルダ内にあるすべてのファイルバージョンに適用されます。 - **ホールド**: [ファイルバージョンリーガルホールド](r://file_version_legal_hold)は、特定のファイルバージョンに割り当てられているすべてのポリシーを表します。各ファイルバージョンに設定できるファイルバージョンリーガルホールドは最大1つで、このホールドには、割り当てられた各ポリシーのリストが含まれていることに注意してください。 ## ユースケースの例 証拠開示の命令を受けた場合や顧客が係争中の場合は、リーガルホールドポリシーを作成して、保持すべきすべての証拠を追跡できます。実際のホールドは、特定のファイルまたはフォルダにポリシーを割り当てることで行われます。ホールドが不要になったら、割り当てを削除するとポリシーを解除できます。 ## 必須のスコープ リーガルホールドAPIのいずれかを使用する前に、アプリケーションでは、[GCMおよびリーガルホールドの管理のスコープ](g://api-calls/permissions-and-errors/scopes)を有効にしておく必要があります。これらは、開発者コンソールでは使用できないため、代わりにカスタマーサポートに連絡して有効する必要があります。 **Source:** [https://ja.developer.box.com/guides/legal-holds/](https://ja.developer.box.com/guides/legal-holds/) --- ### リーガルホールドポリシーの取得 **Type:** guide | **Category:** リーガルホールド | **Section:** Developer Guides リーガルホールドポリシーの取得 会社内に作成された特定のリーガルホールドポリシーの情報を取得するには、ポリシーのidを指定してGET /legal_hold_policies/:id APIエンドポイントを呼び出します。 必須のスコープ リーガルホールドAPI… # リーガルホールドポリシーの取得 会社内に作成された特定のリーガルホールドポリシーの情報を取得するには、ポリシーの`id`を指定して[`GET /legal_hold_policies/:id`](e://get_legal_hold_policies_id) APIエンドポイントを呼び出します。 ## 必須のスコープ リーガルホールドAPIのいずれかを使用する前に、アプリケーションでは適切なスコープを有効にしておく必要があります。詳細については、[必須のスコープ](g://legal-holds#required-scopes)を参照してください。 **Source:** [https://ja.developer.box.com/guides/legal-holds/get/](https://ja.developer.box.com/guides/legal-holds/get/) --- ### リテンションポリシー **Type:** guide | **Category:** リテンションポリシー | **Section:** Developer Guides … # リテンションポリシー リテンションポリシーは、指定した期間にわたってコンテンツが完全に削除されるのを防止します。管理者はリテンションポリシーを作成して特定のフォルダや会社全体に割り当てることができます。リテンションポリシーを使用すると、データを必要な期間保持し、法的にデータの保持が必要なくなったときに自動的にコンテンツを完全に削除することができます。 リテンションポリシーは、Business PlusアカウントまたはEnterpriseアカウントに追加できる、[Box Governance](https://www.box.com/security/governance-and-compliance)パッケージの機能です。 ## ポリシー、割り当て、およびリテンション リテンションポリシーを操作するには、開発者は3つの異なるリソースを使用する必要があります。 - **ポリシー:** [リテンションポリシー](r://retention_policy)には、リテンションポリシーの一般的な動作が記載されています。これにより、リテンションを保持する期間、リテンションの延長が可能かどうか、およびリテンションポリシーの終了条件が決まります。 - **割り当て:** [リテンションポリシー割り当て](r://retention_policy_assignment)は、ポリシーとフォルダや会社の関係です。割り当てを作成すると、そのフォルダや会社に属するすべてのファイルバージョンにリテンションが適用されます。たとえば、フォルダに割り当てが作成されると、ポリシーはそのフォルダ内にあるすべてのファイルバージョンに適用されます。 - **リテンション**: [ファイルバージョンリテンション](r://file_version_retention)は、特定のファイルバージョンに割り当てられているすべてのポリシーを表します。各ファイルバージョンに設定できるファイルバージョンのリテンションは最大1つで、このリソースには、割り当てられた各ポリシーのリストが含まれていることに注意してください。 Box APIの[ファイルバージョンリテンション](r://file_version_retention)セクションは非推奨になりました。代わりに、[リテンションの対象となるファイル](e://get-retention-policy-assignments-id-files-under-retention)エンドポイントまたは[リテンションの対象となるファイルバージョン](e://get-retention-policy-assignments-id-file-versions-under-retention)エンドポイントを使用できます。 ## リテンションポリシーによるファイルの削除 リテンションの対象となっているファイルは、フォルダから削除することはできますが、リテンションが期限切れるまではごみ箱に残ります。リテンションが期限切れになると、コンテンツが自動的に削除されるようにするか、ポリシーを削除するかを選択できます。 ## ファイルのリテンション期間の延長 リテンションの対象となっているファイルのリテンション期間は、`disposition_at`フィールドの値を将来の日付で[更新](e://put-files-id/#param-disposition_at)することで延長できます。一度延長した期間は、元に戻すことも、新しい日付より前に変更することもできません。 ## 必須のスコープ リテンションポリシーAPIのいずれかを使用する前に、アプリケーションでは、[GCMおよびリテンションポリシーの管理のスコープ](g://api-calls/permissions-and-errors/scopes)を有効にしておく必要があります。これらは、開発者コンソールでは使用できないため、代わりにカスタマーサポートに連絡して有効する必要があります。 **Source:** [https://ja.developer.box.com/guides/retention-policies/](https://ja.developer.box.com/guides/retention-policies/) --- ### リテンションポリシーの取得 **Type:** guide | **Category:** リテンションポリシー | **Section:** Developer Guides リテンションポリシーの取得 会社内に作成された特定のリテンションポリシーの情報を取得するには、ポリシーのidを指定してGET /retention_policies/:id APIエンドポイントを呼び出します。 必須のスコープ リテンションポリシーAPI… # リテンションポリシーの取得 会社内に作成された特定のリテンションポリシーの情報を取得するには、ポリシーの`id`を指定して[`GET /retention_policies/:id`](e://get_retention_policies_id) APIエンドポイントを呼び出します。 ## 必須のスコープ リテンションポリシーAPIのいずれかを使用する前に、アプリケーションでは適切なスコープを有効にしておく必要があります。詳細については、[必須のスコープ](g://retention-policies#required-scopes)を参照してください。 **Source:** [https://ja.developer.box.com/guides/retention-policies/get/](https://ja.developer.box.com/guides/retention-policies/get/) --- ### リモートBox MCPサーバー **Type:** guide | **Category:** Box MCPサーバー | **Section:** Developer Guides リモートBox MCPサーバー リモートBox MCPサーバーを使用すると、サードパーティ製のAIシステムを安全にBoxに接続してコンテンツを操作することができます。 Box MCPサーバーは、BoxのMain Beta Agreement… # リモートBox MCPサーバー リモートBox MCPサーバーを使用すると、サードパーティ製のAIシステムを安全にBoxに接続してコンテンツを操作することができます。 Box MCPサーバーは、BoxのMain Beta Agreementに従い提供されるため、利用可能な機能はいつでも変更される可能性があります。Box MCPサーバーは、Enterprise PlusまたはEnterprise Advancedプランをご利用のお客様が利用できます。 ## あらかじめ定義されたBox MCPサーバーにアクセスして管理する 1. Box管理コンソールのサイドバーにある [**統合**] をクリックします。 2. [統合] ウィンドウで [**Box統合とクライアント**] をクリックします。 3. [**統合の個別管理**] までスクロールします。 4. あらかじめ定義されたBox MCPサーバー (**Box MCP Server for Copilot Studio (ベータ)** など) を検索します。 5. 選択した統合にカーソルを合わせ、[**構成**] をクリックします。 6. [保存] をクリックします。 ## リストに記載されていないBox MCPサーバーを作成する リストに記載されていない新しいBox MCPサーバーを作成するには、以下の手順に従います。 1. Box管理コンソールのサイドバーにある [統合] をクリックします。 2. [Box統合とクライアント] タブで [**統合の個別管理**] までスクロールします。 3. [**Box MCP Server (Box MCPサーバー)**] を検索します。 4. [**Box MCP Server (Box MCPサーバー)**] アプリケーションにカーソルを合わせ、[**構成**] をクリックします。 5. [**追加の構成**] セクションで [**+ 統合資格情報を追加**] をクリックします。 6. 外部MCPクライアントから提供されたリダイレクトURIを入力します。 7. 生成されたクライアントIDとクライアントシークレットをコピーします。 8. [スコープ] で [*AIリクエストの管理*] が選択されていることを確認します。 ## MCPクライアントにBox MCPサーバーを追加する AIエージェントプラットフォームからBoxに接続するには、以下の操作を行う必要があります。 - エンドポイントURLを追加する: `https://mcp.box.com` - MCP名を渡す: `box-remote-mcp` - `authorization_token`を指定する 正確な手順はAIプラットフォームによって異なる場合があります。クライアント側での設定手順については、お使いのプラットフォームのドキュメントを参照してください。参考までに、次のサンプルコードを確認してください。 ``` response = await client.beta.messages.create( model="claude-3-opus-20240229", # Or your preferred model max_tokens=4096, messages=conversation_history, mcp_servers=[ { "type": "url", "url": "https://mcp.box.com", "name": "box-remote-mcp", "authorization_token": BEARER_TOKEN, } ], betas=["mcp-client-2025-04-04"] ) ``` ### AnthropicのMessages API リモートBox MCPサーバーをAnthropicのMessages API (ベータ版) と関連付けます。[こちらのサンプルチャットボットプロジェクト](https://github.com/box-community/remote-box-mcp-anthropic)を複製すると、すぐに作業を開始できます。これにより、Anthropicモデルとの会話が可能になり、BoxのリモートMCPサーバーが提供するツールにアクセスできます。このチャットボットは、ターミナルで実行され、コンテキストに対応した応答の会話履歴を維持し、非同期操作には`asyncio`を使用します。 ### Copilot Studio MCPサーバーを追加するには、Copilot Studio側が提供する手順に従います。詳細な手順とガイダンスは、こちらのMicrosoftの公式ドキュメントで確認できます: [Add an MCP Server in Copilot Studio](https://learn.microsoft.com/en-us/microsoft-copilot-studio/agent-extend-action-mcp#add-tools-from-an-existing-mcp-connector-to-an-agent) ### Azure API Center Azure API CenterのEnterprise RegistryにMCPサーバーを追加するには、Azureが提供する手順に従います。詳細な手順とガイダンスは、こちらのMicrosoftの公式ドキュメントで確認できます: [Add an MCP Server in Azure API Center's Enterprise Registry](https://learn.microsoft.com/en-us/azure/api-center/register-discover-mcp-server) ### MCPサーバーでのBox AIの機能の使用 サードパーティ製アプリケーションでBox AIを使用すると、Box MCPサーバー経由でアプリケーションにアクセスするため、最適なエクスペリエンスと質の高い結果を得ることができます。これにより、すべての機能、パフォーマンスの向上、シームレスなユーザーエクスペリエンスが実現します。 ## 利用可能なツール リモートBox MCPサーバーには、使用できるツールがいくつかあります。 | ツール | 説明 | | --- | --- | | box-remote-mcp_who_am_i | 現在認証されているBoxユーザーの詳細な情報を返します。 | | box-remote-mcp_search_folders_by_name | キーワードの照合を使用して、名前でBox内のフォルダを検索します。 | | box-remote-mcp_list_folder_content_by_folder_id | フォルダ内のファイル、フォルダ、ウェブリンクのリストを取得します。 | | box-remote-mcp_search_files_keyword | キーワードを使用してファイルを検索します。メタデータフィルタ、ファイル拡張子によるフィルタ処理、フィールドの選択がサポートされています。 | | box-remote-mcp_search_files_metadata | SQLに似たメタデータクエリを使用してファイルを検索します。パラメータを使用した複雑なフィルタ処理、フィールドの選択、フォルダの範囲指定がサポートされています。 | | box-remote-mcp_ai_qa_single_file | Box AIを使用して単一のファイルに質問します。 | | box-remote-mcp_ai_qa_multi_file | Box AIを使用して複数のファイルに質問します。 | | box-remote-mcp_ai_qa_hub | Box AIを使用してBox Hubに質問します。 | | box-remote-mcp_ai_extract_freeform | Box AIを使用して、ファイルから自由形式でメタデータを抽出します。あらかじめ定義されたテンプレート構造は必要ありません。 | | box-remote-mcp_ai_extract_structured | Box AIを使用して、ファイルから、カスタムフィールドの定義または既存のメタデータテンプレートに基づいて構造化メタデータを抽出します。 | **Source:** [https://ja.developer.box.com/guides/box-mcp/remote/](https://ja.developer.box.com/guides/box-mcp/remote/) --- ### レート制限 **Type:** guide | **Category:** APIコール | **Section:** Developer Guides レート制限 APIコールのレート制限には一般的に3種類あります。Boxは独自の判断でこの制限を使用して、ネットワークリソースの保護やカスタマーエクスペリエンスの品質維持をうまく実現することができます。 ユーザーベース このレート制限を使用すると、… # レート制限 APIコールのレート制限には一般的に3種類あります。Boxは独自の判断でこの制限を使用して、ネットワークリソースの保護やカスタマーエクスペリエンスの品質維持をうまく実現することができます。 ## ユーザーベース このレート制限を使用すると、1人のユーザーによって生成されるトラフィックが多すぎる場合に発生する可能性のある問題からBoxサービスが保護されます。ユーザーが1分間に実行できるAPIコールの数は、以下で説明するように制限されています。このレート制限は最も一般的で、すべてのBoxユーザーアカウントに適用されます。通常、ユーザーの1分あたりのAPIコールが1,000を超えると、この制限が開始されますが、特定のAPIエンドポイントには別のレート制限が適用されている可能性があります。 ## サービスの品質 このレート制限は、Boxのインフラストラクチャのサービスの品質を保護することを目的としています。インフラストラクチャ内でリソースの競合が生じると、システムの性能低下や機能停止を防ぐために自動のレート制限が導入されます。たとえば、アプリケーションが偶然同じ物理データベースサーバーにアクセスした場合 (アクセス先が同じ物理リソースである関連リソースにアクセスするファイル移行ツールの使用など)、Boxでは、負荷が急増したときに一時的なレート制限が課せられ、システムの復旧に合わせて調整されることがあります。 ## ライセンスベース すべてのBox Businessプランでは、1か月あたり1社ごとに許可されるAPIコールの数がライセンスされています。このライセンスベースのレート制限は、ネットワークリソースの過剰供給や乱用を防ぐことを目的としています。顧客が使用するツールや顧客のために使用されるツールがその顧客のAPIライセンス割り当てを超過しているか、ネットワーク管理を回避しようとしていることがBoxのインフラストラクチャで検出されると、さらに対象を絞ったレート制限が課せられる場合があります。Boxの[価格ページ](https://www.box.com/pricing)では、特定のアカウントレベルでライセンスされているデフォルトのAPI割り当てを確認できますが、割り当てを増やすためにPlatform APIの価格プランを購入する顧客もいることに注意してください。 ## APIごとのレート制限 現在、Box APIにはいくつかの異なるレート制限があります。 一般的なAPIコール - 1ユーザーあたりのAPIリクエストは1000件/分 アップロード - 1ユーザーあたりのファイルアップロードリクエストは240件/分 検索 - [検索エンドポイント](e://get_search)に対して、1ユーザーあたりの検索数は6件/秒 基本のレート制限に加えてさらに2つの制限が適用 - 1ユーザーあたりの検索数は60件/分 - 会社あたりの検索数は12件/秒 Box Sign - 署名リクエストの作成と再送信: 1ユーザーあたりのリクエスト数は100件/分 - 署名リクエストの取得: 1ユーザーあたりのリクエスト数は1,000件/分 ## レート制限エラー アプリケーションがレート制限に達すると、APIは、HTTPステータスコードが`429 Too Many Requests`のAPIレスポンスを返します。 レスポンスには以下のヘッダーとJSON本文が含まれます。 ``` retry-after: 100 ``` ``` { "type": "error", "status": 429, "code": "rate_limit_exceeded", "help_url": "https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/", "message": "Request rate limit exceeded, please try again later", "request_id": "abcdef123456" } ``` 詳細については、[クライアントエラーのリソース](resource://client_error)を参照してください。 `retry-after`ヘッダーでは、次のAPIコールが再試行可能になるまで待機する秒数を指示します。一般的には、APIコールの再試行に指数バックオフ戦略を使用することをお勧めします。 **Source:** [https://ja.developer.box.com/guides/api-calls/permissions-and-errors/rate-limits/](https://ja.developer.box.com/guides/api-calls/permissions-and-errors/rate-limits/) --- ### レスポンスの並べ替え **Type:** guide | **Category:** APIコール | **Section:** Developer Guides レスポンスの並べ替え APIから項目のコレクションが返される場合は、APIレスポンスの並べ替えがサポートされることがよくあります。 sortおよびdirection… # レスポンスの並べ替え APIから項目のコレクションが返される場合は、APIレスポンスの並べ替えがサポートされることがよくあります。 `sort`および`direction`クエリパラメータを使用すると、昇順または降順のいずれかでコレクションを並べ替えることができます。 ``` curl https://api.box.com/2.0/folders/0/items?sort=size&direction=DESC \ -H "authorization: Bearer ACCESS_TOKEN" ``` コレクションを返すすべてのAPIエンドポイントが並べ替えをサポートしているわけではありません。特にマーカーベースのページ割りを使用するエンドポイントでは、結果の並べ替えがサポートされないことがよくあります。 ## 並べ替え基準 並べ替えの基準となるフィールドは`sort`クエリパラメータによって定義されます。この値に使用できるオプションについては、APIエンドポイントのドキュメントを確認してください。 一部のAPIでは、`sort`フィールドが項目の並べ替えの2番目の基準になっています。たとえば、[`GET /folders/:id/items`](endpoint://get_folders_id_items)エンドポイントの場合、結果は常に、まずその種類で並べ替えられてから、他の基準で並べ替えられます。 ## 並べ替えの方向 並べ替えの方向では、`ASC` (昇順の場合) と`DESC` (降順の場合) という2つの値がサポートされます。 **Source:** [https://ja.developer.box.com/guides/api-calls/sorting/](https://ja.developer.box.com/guides/api-calls/sorting/) --- ### レプリゼンテーション **Type:** guide | **Category:** レプリゼンテーション | **Section:** Developer Guides レプリゼンテーション レプリゼンテーションとは、Boxに保存されているファイルの代替アセットです。このようなアセットには、PDF、サムネイル、またはテキスト抽出を使用できます。 レプリゼンテーションは、Box… # レプリゼンテーション レプリゼンテーションとは、Boxに保存されているファイルの代替アセットです。このようなアセットには、PDF、サムネイル、またはテキスト抽出を使用できます。 レプリゼンテーションは、Boxへのアップロード時またはアセットのリクエスト時に、サポートされているファイルの種類に対して自動的に生成されます。 このようなレプリゼンテーションは、`fields=representations`クエリパラメータと`x-rep-hints`ヘッダーを使用することで、`GET /files/:id`エンドポイントを介して公開されます。 **Source:** [https://ja.developer.box.com/guides/representations/](https://ja.developer.box.com/guides/representations/) --- ### ロゴのカスタマイズ **Type:** guide | **Category:** Boxの埋め込み | **Section:** Developer Guides ロゴのカスタマイズ それぞれのBox UI Elementsでは、埋め込まれたコンテナの左上隅に配置するカスタムロゴを指定できます。 デフォルトでは、それぞれのUI Elementでロゴとして汎用的なプレースホルダが使用されます。このプレースホルダは、Box… # ロゴのカスタマイズ それぞれのBox UI Elementsでは、埋め込まれたコンテナの左上隅に配置するカスタムロゴを指定できます。 デフォルトでは、それぞれのUI Elementでロゴとして汎用的なプレースホルダが使用されます。このプレースホルダは、Boxのロゴまたはカスタムロゴ (会社のロゴなど) に置き換えられます。 UI Elementにロゴを追加するには、JavaScript設定コードでロゴのURLをオプションとして指定します。コンテンツプレビューUI Elementを使用したこの追加方法の例を以下に示します。 ``` var preview = new Box.Preview(); preview.show(fileId, accessToken, { container: '.preview-container', sharedLink: 'https://app.box.com/v/foo', sharedLinkPassword: 'bar', collection: [FILE_ID, '123', '234', ...], header: 'light', logoUrl: 'http://i.imgur.com/xh8j3E2.png', showAnnotations: true, showDownload: true }); ``` # Boxのロゴ UI ElementにBoxのロゴを表示するには、文字列`box`を`logoURL`オプションとして指定してください。 ## 画像サイズ 画像ファイルは、高さの最大値32ピクセル、幅の最大値80ピクセルに収まります。画像がそれより大きい場合は、このサイズに合わせて縮小されます。 **Source:** [https://ja.developer.box.com/guides/embed/ui-elements/logo/](https://ja.developer.box.com/guides/embed/ui-elements/logo/) --- ### ワークフローの取得 **Type:** guide | **Category:** Box Relay | **Section:** Developer Guides ワークフローの取得 ワークフローを取得エンドポイントを使用すると、特定のフォルダに関するワークフローをすべて取得できます。これにより、WORKFLOW_MANUAL_START… # ワークフローの取得 [ワークフローを取得](e://get-workflows)エンドポイントを使用すると、特定のフォルダに関するワークフローをすべて取得できます。これにより、`WORKFLOW_MANUAL_START`タイプのフローの有無に関係なく、すべてのワークフローが返されます。 これらのエンドポイントの使用方法の詳細については、Boxの[ブログ](https://medium.com/@Box_Developers/%E6%89%8B%E5%8B%95%E9%96%8B%E5%A7%8B%E3%83%AF%E3%83%BC%E3%82%AF%E3%83%95%E3%83%AD%E3%83%BCapi%E3%81%A8box-relay-64f9136f1682)記事を参照してください。 **Source:** [https://ja.developer.box.com/guides/box-relay/get-workflows/](https://ja.developer.box.com/guides/box-relay/get-workflows/) --- ### ワークフローの開始 **Type:** guide | **Category:** Box Relay | **Section:** Developer Guides ワークフローの開始 ワークフローを開始エンドポイントを使用すると、WORKFLOW_MANUAL_STARTタイプのワークフロー内のフローを開始できます。他のタイプのフローは開始できません。実行時に構成を承認するようにフローを設定している場合は、オプションのoutcomes… # ワークフローの開始 [ワークフローを開始エンドポイント](e://post-workflows-id-start)を使用すると、`WORKFLOW_MANUAL_START`タイプのワークフロー内のフローを開始できます。他のタイプのフローは開始できません。実行時に構成を承認するようにフローを設定している場合は、オプションの`outcomes`配列オブジェクトを送信する必要があります。 このエンドポイントの使用方法の詳細については、Boxの[ブログ](https://medium.com/@Box_Developers/%E6%89%8B%E5%8B%95%E9%96%8B%E5%A7%8B%E3%83%AF%E3%83%BC%E3%82%AF%E3%83%95%E3%83%AD%E3%83%BCapi%E3%81%A8box-relay-64f9136f1682)記事を参照してください。 **Source:** [https://ja.developer.box.com/guides/box-relay/start-workflow/](https://ja.developer.box.com/guides/box-relay/start-workflow/) --- ### 一括操作 **Type:** guide | **Category:** フォルダ | **Section:** Developer Guides 一括操作 以下のページでは、複数のフォルダに対するさまざまな一括操作の方法について説明します。 # 一括操作 以下のページでは、複数のフォルダに対するさまざまな一括操作の方法について説明します。 **Source:** [https://ja.developer.box.com/guides/folders/bulk/](https://ja.developer.box.com/guides/folders/bulk/) --- ### 一般的なエラー **Type:** guide | **Category:** 承認 | **Section:** Developer Guides 一般的なエラー サービスまたはEnterpriseのアプリ承認を取得できません このエラーは、入力したクライアントIDが無効であることを示しています。この問題を解決するには、開発者コンソールからクライアントID… # 一般的なエラー ## サービスまたはEnterpriseのアプリ承認を取得できません このエラーは、入力したクライアントIDが無効であることを示しています。この問題を解決するには、開発者コンソールからクライアントIDを再度コピーし、末尾に余分な文字を含めていないことを確認してください。 ## アプリ承認の追加に問題が発生しました このエラーは、Enterprise設定を表示する権限は付与されているが、編集する権限が付与されていないBox共同管理者であることを示しています。アプリケーションを正常に承認するには、Box管理者に編集権限を付与してもらう必要があります。 ## 管理者により無効化されました このエラーは、承認の要件の一部が満たされていないことを示しています。特定のアプリケーションに必要な手順を確認するには、Boxの[承認ガイド](g://authorization)を参照してください。 **Source:** [https://ja.developer.box.com/guides/authorization/common-errors/](https://ja.developer.box.com/guides/authorization/common-errors/) --- ### 一般的なエラー **Type:** guide | **Category:** メタデータ | **Section:** Developer Guides 一般的なエラー メタデータクエリAPIのエラーのほとんどは、他のAPIによって返されるエラーに似ています。ただし、現在、一部の正しくないクライアントリクエストでは、適切な400 Bad Requestエラーではなく、サーバー側のエラーとともに、5XXの範囲のHTTP… # 一般的なエラー メタデータクエリAPIのエラーのほとんどは、[他のAPIによって返されるエラーに似ています](g://api-calls/permissions-and-errors/common-errors)。ただし、現在、一部の正しくないクライアントリクエストでは、適切な`400 Bad Request`エラーではなく、サーバー側のエラーとともに、`5XX`の範囲のHTTPステータスコードが返される場合があります。 これは既知の問題であり、近日中に解決される予定です。 ## テンプレートキーとスコープが正しくない 一般的なエラーとして、リクエストの`from`値に誤った値が使用されると、`HTTP 4XX`の範囲のさまざまなエラーが生じる可能性があります。 正しい`from`値を使用しないと、APIは検索対象のテンプレートを認識できません。`from`の値は、`scope.templateKey`の形式にする必要があります。 この場合、`scope`は会社のテンプレートのスコープで、`enterprise_123456`のようになります。ここでの数値は会社のIDです。`global`スコープや短縮形の`enterprise`スコープなど、この形式に一致しないスコープではエラーが返されます。 `templateKey`は、社内のメタデータテンプレートの一意のキーです。指定したキーを持つテンプレートが存在しない場合、またはキーが存在しないのにそのキーが誤った会社で使用されている場合は、このAPIによってエラーが返されます。 [企業のすべてのメタデータテンプレートのリストを取得エンドポイント](e://get-metadata-templates-enterprise)を使用すると、`scope`と`templateKey`を含む、社内で使用できるすべてのテンプレートのリストを取得できます。 ## query_paramに値がない 一般的なエラーとして、`query_params`オブジェクトにクエリ引数を含めるのを忘れると、`unexpected_json_type`というコードとともに`HTTP 400`エラーが返されます。 `query_params`にすべての引数が存在しないと、APIはリクエストを完全なクエリにコンパイルできません。 たとえば、検索`query`が`amount >= :value AND status = :status`のようになっているとします。コロン`:`で始まる引数はすべて、`query_params`に存在する必要があります。この場合、クエリパラメータは次のようになります。これらの値のいずれかを忘れると、エラーが発生します。 ``` "query_params": { "value": 100, "status": "active" } ``` 各引数の名前は開発者の好みに合わせて構成できるため、フィールドキーと一致させる必要はありません。必要なのは、先頭に`:`を付けることだけです。 ## ancestor_folder_idがない 一般的なエラーとして、リクエストに`ancestor_folder_id`を指定し忘れると、`bad_request`というコードとともに`HTTP 400`エラーが返されます。 `ancestor_folder_id`値がないと、APIは、検索対象の結果が含まれているフォルダを認識できません。よくわからない場合は、値`0`を使用すると、ユーザーのルートフォルダを指定できます。 **Source:** [https://ja.developer.box.com/guides/metadata/queries/errors/](https://ja.developer.box.com/guides/metadata/queries/errors/) --- ### 事前チェック **Type:** guide | **Category:** アップロード | **Section:** Developer Guides 事前チェック 事前チェックAPIを使用すると、アプリケーションでアップロードを開始する前にそのファイルがBoxに受け入れられるかどうかを確認できます。このAPI… # 事前チェック 事前チェックAPIを使用すると、アプリケーションでアップロードを開始する前にそのファイルがBoxに受け入れられるかどうかを確認できます。このAPIは、新しいファイルにも、既存ファイルの新しいバージョンのアップロードにも使用できます。 ## チェックリスト 事前チェックでは、ファイルが実際にアップロードされるときと同じように、以下のすべてのチェックが実行されます。 - フォルダにアップロードするアプリケーションおよびユーザーの権限 - ファイル名の競合 - ファイルサイズの上限や制限 - フォルダおよびファイルの名前に関する制約事項 - フォルダおよびアカウントのストレージ容量 ## 新しいファイルのチェック 新しいファイルのチェックを実行するには、実際のファイルをアップロードする場合と同じパラメータ (バイナリコンテンツを除く) を使用して[`OPTIONS /files/content`](e://options_files_content) APIを呼び出してください。 ## 新しいファイルバージョンのチェック 新しいファイルバージョンのチェックを実行するには、実際のファイルをアップロードする場合と同じパラメータ (バイナリコンテンツを除く) を使用して[`OPTIONS /files/:id/content`](e://options_files_content) APIを呼び出してください。 ## チェックと分割アップロード [分割アップロード](g://uploads/chunked)を実行する場合、[アップロードセッションの作成](g://uploads/chunked/create-session)でも事前チェックが実行されるため、事前チェックは必須ではありません。 ## レスポンスコード APIコールで問題が検出されると、HTTP `409 Conflict`ステータスコードとともに可能性のある競合を説明するメッセージが返されます。問題が検出されなかった場合、HTTP `200 OK`ステータスコードが返され、アップロードを続行できます。 `200 OK`レスポンスは、アップロード呼び出しが実際に成功することを保証するものではありません。事前チェックによりアップロードの失敗が99%以上削減されることが実証されていますが、ファイルのアップロード時に同時実行の問題が発生する可能性は残っています。 非常にアクティブで、クォータ制限に近づいているフォルダ、一般的なファイル名、およびアカウントの場合、事前チェックで`200 OK`が返されたとしても、実際のアップロード中に競合が発生する可能性があります。 ## レスポンスの本文 事前チェックでは多くの場合、競合が検出されるとAPIレスポンスで有益なデータが返されます。たとえば名前の競合が検出された場合、アプリケーションではエラーレスポンスで返される`SHA-1`を使用して、アップロードしようとしているファイルと既存ファイルが同一であるかどうかを確認できます。 **Source:** [https://ja.developer.box.com/guides/uploads/check/](https://ja.developer.box.com/guides/uploads/check/) --- ### 以前コラボレーションが許可されたドメインの削除 **Type:** guide | **Category:** コラボレーション | **Section:** Developer Guides 以前コラボレーションが許可されたドメインの削除 コラボレーションの許可されたドメインのリストからドメインを削除すると、自分の会社とそのドメイン内のユーザーとの間にコラボレーションを作成できなくなります。 許可リストからドメインを削除するには、リストのエントリのID… # 以前コラボレーションが許可されたドメインの削除 コラボレーションの許可されたドメインのリストからドメインを削除すると、自分の会社とそのドメイン内のユーザーとの間にコラボレーションを作成できなくなります。 許可リストからドメインを削除するには、リストのエントリのIDを削除リクエストに指定します。このIDは、[新しいドメインを許可する](guide://collaborations/allowed-domains/create)か[社内で許可されているドメインのリストを取得する](guide://collaborations/allowed-domains/list)と返されます。 **Source:** [https://ja.developer.box.com/guides/collaborations/allowed-domains/delete/](https://ja.developer.box.com/guides/collaborations/allowed-domains/delete/) --- ### 会社全体での検索 **Type:** guide | **Category:** 検索 | **Section:** Developer Guides 会社全体での検索 デフォルトでは、認証済みユーザーがアクセスできるコンテンツに対してのみ、検索が実行されます。場合によっては、管理者は、全ユーザーが所有する全コンテンツを検索することもできます。そのようなユースケースでは、scopeクエリパラメータの値をenterprise… # 会社全体での検索 デフォルトでは、認証済みユーザーがアクセスできるコンテンツに対してのみ、検索が実行されます。場合によっては、管理者は、全ユーザーが所有する全コンテンツを検索することもできます。そのようなユースケースでは、`scope`クエリパラメータの値を`enterprise_content`に設定できます。 ``` curl -i -X GET "https://api.box.com/2.0/search?query=sales&scope=enterprise_content" \ -H "Authorization: Bearer <ACCESS_TOKEN>" ``` ``` long offsetValue = 0; long limitValue = 10; BoxSearch boxSearch = new BoxSearch(api); BoxSearchParameters searchParams = new BoxSearchParameters(); searchParams.setQuery("sales"); searchParams.setScope("enterprise_content"); PartialCollection<BoxItem.Info> searchResults = boxSearch.searchRange(offsetValue, limitValue, searchParams); ``` ``` BoxCollection<BoxItem> results = await client.SearchManager .QueryAsync("sales", mdFilters: filters, scope: "enterprise_content"); ``` ``` client.search().query("sales", metadata_filters=metadata_search_filters, scope="enterprise_content") ``` ``` client.search.query( 'sales', { scope: "enterprise_content" }) .then(results => { // ... }); ``` `enterprise_content`スコープは、管理者が[サポートチャネル](p://support)を通じてリクエストできます。このスコープがユーザーに対して有効になっていると、そのユーザーは、アクセスできるコンテンツだけでなく、会社全体のコンテンツに対してクエリを実行できます。 **Source:** [https://ja.developer.box.com/guides/search/enterprise/](https://ja.developer.box.com/guides/search/enterprise/) --- ### 保留中のコラボレーションの取得 **Type:** guide | **Category:** コラボレーション | **Section:** Developer Guides 保留中のコラボレーションの取得 ユーザーの保留中のコラボレーションを取得するには、statusにpendingを指定してGET /collaborations APIを呼び出します。 これにより、ユーザーの保留中のコラボレーションを表示する現在のリストのみが返されます。このAPI… # 保留中のコラボレーションの取得 ユーザーの保留中のコラボレーションを取得するには、`status`に`pending`を指定して`GET /collaborations` APIを呼び出します。 これにより、ユーザーの保留中のコラボレーションを表示する現在のリストのみが返されます。このAPIでは、ユーザーのすべてのコラボレーションを返すことは許可されていません。 **Source:** [https://ja.developer.box.com/guides/collaborations/pending/](https://ja.developer.box.com/guides/collaborations/pending/) --- ### 共有フォルダの設定 **Type:** guide | **Category:** ユーザー | **Section:** Developer Guides … # 共有フォルダの設定 共有フォルダへのアクセスを管理する最後の手順として、必要なフォルダ構造をサービスアカウント内に作成します。次に、これらのフォルダに必要なユーザーの種類とアクセスレベルに基づいて、グループに必要な権限をマップします。ここでは、マーケティング部門を例に挙げて説明します。 ``` { "name": "Marketing Department", "parent": { "id": "0" }, "children": [ { "name": "Projects", "children": [] }, { "name": "Newsletter", "children": [ { "name": "Drafts", "children": [] } ] } ] } ``` このサンプルフォルダ構造を基にし、以前に使用したフォルダツリー作成コードを使用して`etc/skel`構造を作成できます。このコードは、実際の構造に応じて変更できます。 この構造が作成されると、各グループでアクセスする必要があるフォルダのIDが必要になります。たとえば、マーケティングマネージャであれば、マーケティング部門内のすべてのフォルダに対する`editor`アクセス権限が必要になるでしょう。一方、マーケティングプロジェクトマネージャが必要なのは、`Projects`フォルダへの`editor`アクセスだけと考えられます。このため、2つのグループを作成して、それぞれに適切な権限を付与します。 ``` "use strict"; const fs = require("fs"); const box = require("box-node-sdk"); let configFile = fs.readFileSync("config.json"); configFile = JSON.parse(configFile); let session = box.getPreconfiguredInstance(configFile); let serviceAccountClient = session.getAppAuthClient("enterprise"); const marketingDeptFolderID = "45765309069"; const marketingProjectsFolderID = "45765461670"; const marketingManagersGroupName = "Marketing Managers"; const marketingProjectManagersGroupName = "Marketing Project Managers"; (async () => { let marketingManagerGroup; try { marketingManagerGroup = await serviceAccountClient.groups.create( marketingManagersGroupName, { description: "For Marketing department leadership team.", invitability_level: "admins_only", member_viewability_level: "admins_only" } ); } catch (e) { marketingManagerGroup = await handleGroupConflictError( e, marketingManagersGroupName, serviceAccountClient ); } console.log(marketingManagerGroup); let marketingProjectManagerGroup; try { marketingProjectManagerGroup = await serviceAccountClient.groups.create( marketingProjectManagersGroupName, { description: "All team members who manage Marketing projects.", invitability_level: "admins_and_members", member_viewability_level: "admins_and_members" } ); } catch (e) { marketingProjectManagerGroup = await handleGroupConflictError( e, marketingProjectManagersGroupName, serviceAccountClient ); } console.log(marketingProjectManagerGroup); let collabMarketingManagers; try { collabMarketingManagers = await serviceAccountClient.collaborations.createWithGroupID( marketingManagerGroup.id, marketingDeptFolderID, serviceAccountClient.collaborationRoles.EDITOR ); } catch (e) { collabMarketingManagers = await handleFolderCollaborationConflictError( e, marketingDeptFolderID, marketingManagerGroup.id, serviceAccountClient ); } console.log(collabMarketingManagers); let collabMarketingProjectManagers; try { collabMarketingProjectManagers = await serviceAccountClient.collaborations.createWithGroupID( marketingProjectManagerGroup.id, marketingProjectsFolderID, serviceAccountClient.collaborationRoles.EDITOR ); } catch (e) { collabMarketingProjectManagers = await handleFolderCollaborationConflictError( e, marketingProjectsFolderID, marketingProjectManagerGroup.id, serviceAccountClient ); } console.log(collabMarketingProjectManagers); })(); async function autoPage(iterator, collection = []) { let moveToNextItem = async () => { let item = await iterator.next(); if (item.value) { collection.push(item.value); } if (item.done !== true) { return moveToNextItem(); } else { return collection; } }; return moveToNextItem(); } async function handleGroupConflictError(e, groupName, boxClient) { let storeIteratorSetting = boxClient._useIterators; if (e && e.response && e.response.body && e.response.body.status === 409) { boxClient._useIterators = true; let groupsIterator = await boxClient.groups.getAll({ name: groupName }); let groups = await autoPage(groupsIterator); let results = groups.filter(group => { return group.name === groupName; }); if (results.length > 0) { boxClient._useIterators = storeIteratorSetting; return results[0]; } else { throw new Error("Couldn't create group or find existing group."); } } else { throw e; } } async function handleFolderCollaborationConflictError( e, folderID, groupID, boxClient ) { let storeIteratorSetting = boxClient._useIterators; if (e && e.response && e.response.body && e.response.body.status === 409) { boxClient._useIterators = true; let collaborationsIterator = await boxClient.folders.getCollaborations( folderID ); let collaborations = await autoPage(collaborationsIterator); let results = collaborations.filter(collaboration => { return collaboration.accessible_by.id === groupID; }); console.log(results); if (results.length > 0) { boxClient._useIterators = storeIteratorSetting; return results[0]; } else { throw new Error( "Couldn't create new collaboration or located existing collaboration." ); } } else { throw e; } } ``` ``` package com.box; import java.io.BufferedReader; import java.nio.charset.Charset; import java.nio.file.Files; import java.nio.file.Path; import java.nio.file.Paths; import java.util.Collection; import java.util.Optional; import com.box.sdk.BoxAPIException; import com.box.sdk.BoxCollaboration; import com.box.sdk.BoxConfig; import com.box.sdk.BoxDeveloperEditionAPIConnection; import com.box.sdk.BoxFolder; import com.box.sdk.BoxGroup; import com.eclipsesource.json.JsonObject; public class BoxPlayground { public static void main(String[] args) throws Exception { Path configPath = Paths.get("config.json"); try (BufferedReader reader = Files.newBufferedReader(configPath, Charset.forName("UTF-8"))) { String marketingDeptFolderID = "45765309069"; String marketingProjectsFolderID = "45765461670"; String marketingManagersGroupName = "Marketing Managers"; String marketingProjectManagersGroupName = "Marketing Project Managers"; BoxConfig boxConfig = BoxConfig.readFrom(reader); BoxDeveloperEditionAPIConnection serviceAccountClient = BoxDeveloperEditionAPIConnection .getAppEnterpriseConnection(boxConfig); BoxGroup.Info marketingManagerGroup; try { marketingManagerGroup = BoxGroup.createGroup(serviceAccountClient, marketingManagersGroupName, null, null, "For Marketing department leadership team.", "admins_only", "admins_only"); } catch (BoxAPIException e) { JsonObject errorMessage = JsonObject.readFrom(e.getResponse()); int status = errorMessage.get("status").asInt(); if (status == 409) { marketingManagerGroup = handleGroupConflictError(marketingManagersGroupName, serviceAccountClient); } else { throw e; } } System.out.println(marketingManagerGroup.getID()); BoxGroup.Info marketingProjectManagerGroup; try { marketingProjectManagerGroup = BoxGroup.createGroup(serviceAccountClient, marketingProjectManagersGroupName, null, null, "All team members who manage Marketing projects.", "admins_and_members", "admins_and_members"); } catch (BoxAPIException e) { JsonObject errorMessage = JsonObject.readFrom(e.getResponse()); int status = errorMessage.get("status").asInt(); if (status == 409) { marketingProjectManagerGroup = handleGroupConflictError(marketingProjectManagersGroupName, serviceAccountClient); } else { throw e; } } System.out.println(marketingProjectManagerGroup.getID()); BoxFolder marketDeptFolder = new BoxFolder(serviceAccountClient, marketingDeptFolderID); BoxCollaboration.Info marketingDeptFolderCollaboration; try { marketingDeptFolderCollaboration = marketDeptFolder.collaborate( new BoxGroup(serviceAccountClient, marketingManagerGroup.getID()), BoxCollaboration.Role.EDITOR); } catch (BoxAPIException e) { System.out.println("Searching for existing collaborator."); JsonObject errorMessage = JsonObject.readFrom(e.getResponse()); int status = errorMessage.get("status").asInt(); if (status == 409) { marketingDeptFolderCollaboration = handleFolderCollaborationConflict(marketDeptFolder, marketingManagerGroup.getID()); } else { throw e; } } System.out.println(marketingDeptFolderCollaboration.getID()); BoxFolder marketingProjectsFolder = new BoxFolder(serviceAccountClient, marketingProjectsFolderID); BoxCollaboration.Info marketingProjectsFolderCollaboration; try { marketingProjectsFolderCollaboration = marketingProjectsFolder.collaborate( new BoxGroup(serviceAccountClient, marketingProjectManagerGroup.getID()), BoxCollaboration.Role.EDITOR); } catch (BoxAPIException e) { System.out.println("Searching for existing collaborator."); JsonObject errorMessage = JsonObject.readFrom(e.getResponse()); int status = errorMessage.get("status").asInt(); if (status == 409) { marketingProjectsFolderCollaboration = handleFolderCollaborationConflict(marketingProjectsFolder, marketingProjectManagerGroup.getID()); } else { throw e; } } System.out.println(marketingProjectsFolderCollaboration.getID()); } } private static BoxCollaboration.Info handleFolderCollaborationConflict(BoxFolder folder, String groupID) throws Exception { System.out.println("Already collaborated..."); Collection<BoxCollaboration.Info > collaborations = folder.getCollaborations(); Optional<BoxCollaboration.Info > results = collaborations.stream().filter(c -> { return c.getAccessibleBy().getID().intern() == groupID.intern(); }).findFirst(); if (results.isPresent()) { return results.get(); } else { throw new Exception("Couldn't create new collaboration or find existing collaboration."); } } private static BoxGroup.Info handleGroupConflictError(String groupName, BoxDeveloperEditionAPIConnection boxClient) throws Exception { Iterable<BoxGroup.Info > groups = BoxGroup.getAllGroupsByName(boxClient, groupName); BoxGroup.Info foundGroup = null; for (BoxGroup.Info group: groups) { if (group.getName().intern() == groupName) { foundGroup = group; break; } } if (foundGroup != null) { return foundGroup; } else { throw new Exception("Couldn't create group or find existing group."); } } } ``` ``` using System; using System.Collections; using System.Collections.Generic; using System.IO; using System.Linq; using System.Threading.Tasks; using Box.V2; using Box.V2.Config; using Box.V2.Exceptions; using Box.V2.JWTAuth; using Box.V2.Models; using Box.V2.Models.Request; using Newtonsoft.Json.Linq; namespace BoxPlayground { public class Program { static void Main(string[] args) { ExecuteMainAsync().Wait(); } private static async Task ExecuteMainAsync() { using(FileStream fs = new FileStream("./config.json", FileMode.Open)) { var marketingDeptFolderId = "45765309069"; var marketingProjectsFolderId = "45765461670"; var marketingManagersGroupName = "Marketing Managers"; var marketingProjectManagersGroupName = "Marketing Project Managers"; var session = new BoxJWTAuth(BoxConfig.CreateFromJsonFile(fs)); var serviceAccountClient = session.AdminClient(session.AdminToken()); BoxGroup marketingManagerGroup; try { marketingManagerGroup = await serviceAccountClient.GroupsManager.CreateAsync(new BoxGroupRequest { Name = marketingManagersGroupName, InvitabilityLevel = "admins_only", MemberViewabilityLevel = "admins_only" }); } catch(BoxException e) { var errorMessage = JObject.Parse(e.Message); if (errorMessage.GetValue("status").ToObject < int > () == 409) { marketingManagerGroup = await HandleGroupConflictError(marketingManagersGroupName, serviceAccountClient); } else { throw e; } } System.Console.WriteLine(marketingManagerGroup.Id); BoxGroup marketingProjectsManagerGroup; try { marketingProjectsManagerGroup = await serviceAccountClient.GroupsManager.CreateAsync(new BoxGroupRequest { Name = marketingProjectManagersGroupName, InvitabilityLevel = "admins_and_members", MemberViewabilityLevel = "admins_and_members" }); } catch(BoxException e) { var errorMessage = JObject.Parse(e.Message); if (errorMessage.GetValue("status").ToObject < int > () == 409) { marketingProjectsManagerGroup = await HandleGroupConflictError(marketingProjectManagersGroupName, serviceAccountClient); } else { throw e; } } System.Console.WriteLine(marketingProjectsManagerGroup.Id); BoxCollaboration marketingManagerCollab; try { marketingManagerCollab = await serviceAccountClient.CollaborationsManager.AddCollaborationAsync( new BoxCollaborationRequest { AccessibleBy = new BoxCollaborationUserRequest { Id = marketingManagerGroup.Id, Type = BoxType.group }, Item = new BoxRequestEntity { Id = marketingDeptFolderId, Type = BoxType.folder }, Role = BoxCollaborationRole.Editor.ToString() }); } catch(BoxException e) { var errorMessage = JObject.Parse(e.Message); if (errorMessage.GetValue("status").ToObject < int > () == 409) { marketingManagerCollab = await HandleFolderCollaborationConflictError(marketingDeptFolderId, marketingManagerGroup.Id, serviceAccountClient); } else { throw e; } } System.Console.WriteLine(marketingManagerCollab.Id); BoxCollaboration marketingProjectsManagerCollab; try { marketingProjectsManagerCollab = await serviceAccountClient.CollaborationsManager.AddCollaborationAsync( new BoxCollaborationRequest { AccessibleBy = new BoxCollaborationUserRequest { Id = marketingProjectsManagerGroup.Id, Type = BoxType.group }, Item = new BoxRequestEntity { Id = marketingProjectsFolderId, Type = BoxType.folder }, Role = BoxCollaborationRole.Editor.ToString() }); } catch(BoxException e) { var errorMessage = JObject.Parse(e.Message); if (errorMessage.GetValue("status").ToObject < int > () == 409) { marketingProjectsManagerCollab = await HandleFolderCollaborationConflictError(marketingProjectsFolderId, marketingProjectsManagerGroup.Id, serviceAccountClient); } else { throw e; } } System.Console.WriteLine(marketingProjectsManagerCollab.Id); } } public async static Task < BoxGroup > HandleGroupConflictError(string groupName, BoxClient boxClient) { System.Console.WriteLine("Found conflict."); var groups = await boxClient.GroupsManager.GetAllGroupsAsync(autoPaginate: true); return groups.Entries.Find((group) = >{ return group.Name == groupName; }); } public async static Task < BoxCollaboration > HandleFolderCollaborationConflictError(string folderId, string groupId, BoxClient boxClient) { System.Console.WriteLine("Already a collaborator"); var collaborations = await boxClient.FoldersManager.GetCollaborationsAsync(folderId); var existingCollab = collaborations.Entries.Find((collaboration) = >{ return collaboration.AccessibleBy.Id == groupId; }); if (existingCollab != null) { return existingCollab; } else { throw new Exception("Couldn't create new collaboration or find existing collaboration"); } } } } ``` ``` box groups:create "Marketing Managers" --invite=admins_only --view-members=admins_only box groups:create "Marketing Project Managers" --invite=admins_and_members --view-members=admins_and_members ``` グループを作成したら、ユーザーをそのグループに追加すると、そのユーザーにサービスアカウント内に作成された共有フォルダへの所定のアクセス権が付与されます。 ``` 'use strict' const fs = require('fs'); const box = require('box-node-sdk'); let configFile = fs.readFileSync('config.json'); configFile = JSON.parse(configFile); let session = box.getPreconfiguredInstance(configFile); let serviceAccountClient = session.getAppAuthClient("enterprise"); const marketingManagerGroupID = "839790214"; const marketingManagerUserID = "275111793"; (async () => { let addedUser; try { addedUser = await serviceAccountClient.groups.addUser(marketingManagerGroupID, marketingManagerUserID, { role: serviceAccountClient.groups.userRoles.ADMIN }); } catch (e) { addedUser = await handleGroupMembershipConflictError(e, marketingManagerGroupID, marketingManagerUserID, serviceAccountClient); } console.log(addedUser); })(); async function autoPage(iterator, collection = []) { let moveToNextItem = async () => { let item = await iterator.next(); if (item.value) { collection.push(item.value); } if (item.done !== true) { return moveToNextItem(); } else { return collection; } } return moveToNextItem(); } async function handleGroupMembershipConflictError(e, groupID, userID, boxClient) { let storeIteratorSetting = boxClient._useIterators; if (e && e.response && e.response.body && e.response.body.status === 409) { boxClient._useIterators = true; let groupMembershipsIterator = await boxClient.groups.getMemberships(groupID); let groupMemberships = await autoPage(groupMembershipsIterator); let results = groupMemberships.filter((groupMembership) => { return groupMembership.user.id === userID; }); if (results.length > 0) { boxClient._useIterators = storeIteratorSetting; return results[0]; } else { throw new Error("Couldn't create group membership or find existing group membership."); } } else { throw e; } } ``` ``` package com.box; import java.io.BufferedReader; import java.nio.charset.Charset; import java.nio.file.Files; import java.nio.file.Path; import java.nio.file.Paths; import com.box.sdk.BoxAPIException; import com.box.sdk.BoxConfig; import com.box.sdk.BoxDeveloperEditionAPIConnection; import com.box.sdk.BoxGroup; import com.box.sdk.BoxGroupMembership; import com.box.sdk.BoxUser; import com.box.sdk.BoxGroupMembership.Role; import com.eclipsesource.json.JsonObject; public class BoxPlayground { public static void main(String[] args) throws Exception { Path configPath = Paths.get("config.json"); try (BufferedReader reader = Files.newBufferedReader(configPath, Charset.forName("UTF-8"))) { String marketingManagerGroupID = "839982796"; String marketingManagerUserID = "275111793"; BoxConfig boxConfig = BoxConfig.readFrom(reader); BoxDeveloperEditionAPIConnection serviceAccountClient = BoxDeveloperEditionAPIConnection .getAppEnterpriseConnection(boxConfig); BoxGroupMembership.Info marketingManagerMembership = null; BoxGroup marketingManagerGroup = new BoxGroup(serviceAccountClient, marketingManagerGroupID); try { marketingManagerMembership = marketingManagerGroup .addMembership(new BoxUser(serviceAccountClient, marketingManagerUserID), Role.ADMIN); } catch (BoxAPIException e) { JsonObject errorMessage = JsonObject.readFrom(e.getResponse()); int status = errorMessage.get("status").asInt(); if (status == 409) { System.out.println("Found existing membership"); Iterable<BoxGroupMembership.Info > memberships = marketingManagerGroup.getAllMemberships(); for (BoxGroupMembership.Info membership: memberships) { if (membership.getUser().getID().intern() == marketingManagerUserID) { marketingManagerMembership = membership; break; } } if (marketingManagerMembership == null) { throw new Exception("Couldn't add user to group or find existing membership"); } } else { throw e; } } System.out.println(marketingManagerMembership.getID()); System.out.println(marketingManagerMembership.getRole()); } } } ``` ``` using System; using System.Collections; using System.Collections.Generic; using System.IO; using System.Linq; using System.Threading.Tasks; using Box.V2; using Box.V2.Config; using Box.V2.Exceptions; using Box.V2.JWTAuth; using Box.V2.Models; using Box.V2.Models.Request; using Newtonsoft.Json.Linq; namespace BoxPlayground { public class Program { static void Main(string[] args) { ExecuteMainAsync().Wait(); } private static async Task ExecuteMainAsync() { using(FileStream fs = new FileStream("./config.json", FileMode.Open)) { var marketingManagerGroupId = "839982796"; var marketingManagerUserId = "275111793"; var session = new BoxJWTAuth(BoxConfig.CreateFromJsonFile(fs)); var serviceAccountClient = session.AdminClient(session.AdminToken()); BoxGroupMembership marketingManagerMembership; try { marketingManagerMembership = await serviceAccountClient.GroupsManager.AddMemberToGroupAsync(new BoxGroupMembershipRequest { User = new BoxRequestEntity { Id = marketingManagerUserId }, Group = new BoxGroupRequest { Id = marketingManagerGroupId }, Role = "admin" }); } catch(BoxException e) { var errorMessage = JObject.Parse(e.Message); if (errorMessage.GetValue("status").ToObject < int > () == 409) { var groups = await serviceAccountClient.GroupsManager.GetAllGroupMembershipsForGroupAsync(marketingManagerGroupId, autoPaginate: true); marketingManagerMembership = groups.Entries.Find((group) = >{ return group.User.Id == marketingManagerUserId; }); if (marketingManagerMembership == null) { throw new Exception("Couldn't create new collaboration or find existing collaboration"); } } else { throw e; } } System.Console.WriteLine(marketingManagerMembership.Id); } } } } ``` ``` box groups:membership:add $user_id $group_id --role=admin ``` **Source:** [https://ja.developer.box.com/guides/users/provision/shared-folders/](https://ja.developer.box.com/guides/users/provision/shared-folders/) --- ### 共有リンク **Type:** guide | **Category:** 共有リンク | **Section:** Developer Guides 共有リンク 共有リンクは、Boxに保存されているファイル、フォルダ、またはウェブリンクを対象として生成されるURLです。これにより、リソースへの直接的な読み取り専用アクセスが可能になります。 共有リンクのアクセスレベルをオープンに設定すると、そのURL… # 共有リンク 共有リンクは、Boxに保存されているファイル、フォルダ、またはウェブリンクを対象として生成されるURLです。これにより、リソースへの直接的な読み取り専用アクセスが可能になります。 共有リンクのアクセスレベルをオープンに設定すると、そのURLを知っているすべてのユーザーが項目にアクセスできますが、アクセスレベルを会社またはコラボレータに設定すると、適切な認証済みBoxユーザーのみがアクセスできます。共有リンクに関連するすべてのオプションと管理設定については、[こちら](https://support.box.com/hc/ja/articles/360043697094-%E5%85%B1%E6%9C%89%E3%83%AA%E3%83%B3%E3%82%AF%E3%81%AE%E4%BD%9C%E6%88%90)を参照してください。 ユーザーは、ブラウザに共有リンクURLを入力することにより、共有項目にアクセスできます。アプリケーションからも[共有項目API](endpoint://get_shared_items)を使用して共有項目にアクセスできます。 **Source:** [https://ja.developer.box.com/guides/shared-links/](https://ja.developer.box.com/guides/shared-links/) --- ### 共有リンクのダウンロード **Type:** guide | **Category:** ダウンロード | **Section:** Developer Guides 共有リンクのダウンロード 共有リンクのファイルをダウンロードするには、最初にリンクのファイルを確認します。 共有リンクを使用してフォルダをダウンロードすることはできません。代わりに、ZIPアーカイブを作成してダウンロードしてください。 ファイルIDが確認されたら、BoxAPI… # 共有リンクのダウンロード [共有リンク](g://shared-links)のファイルをダウンロードするには、最初にリンクの[ファイルを確認](g://shared-links/find-for-item)します。 共有リンクを使用してフォルダをダウンロードすることはできません。代わりに、[ZIPアーカイブを作成してダウンロードしてください](g://downloads/zip-archive)。 ファイルIDが確認されたら、`BoxAPI`ヘッダーをAPIに渡して、ファイルをダウンロードできます。 項目の共有リンクを取得する場合、ユーザーには少なくとも、その項目に対するビューアーレベルのアクセス権限が必要です。 **Source:** [https://ja.developer.box.com/guides/downloads/shared-link/](https://ja.developer.box.com/guides/downloads/shared-link/) --- ### 共有リンクの作成または更新 **Type:** guide | **Category:** 共有リンク | **Section:** Developer Guides 共有リンクの作成または更新 ファイルリソース、フォルダリソース、またはウェブリンクリソースの共有リンクを直接作成して、適切なアクセスレベルを持つユーザーにコンテンツの表示を許可するための読み取り専用URL… # 共有リンクの作成または更新 ファイルリソース、フォルダリソース、またはウェブリンクリソースの共有リンクを直接作成して、適切なアクセスレベルを持つユーザーにコンテンツの表示を許可するための読み取り専用URLを生成できます。 ファイル、フォルダ、またはウェブリンクのアクティブな共有リンクは、常に1つのみ保持できます。 共有リンクの作成には少なくとも以下の情報が必要です。 - リソースのタイプ (ファイル、フォルダ、またはウェブリンク)。 - リソースのID。 共有リンクの作成時には、以下の情報もオプションとして指定できます。 以下のいずれかのアクセスレベル。 - open: パブリックな共有リンク。リンクを知っている全員がアクセスできます。 - company: 会社内のすべてのユーザーがアクセスできます。 - collaborators: コンテンツのコラボレーションに参加しているすべてのユーザーがアクセスできます。 有効期限。その日時から、共有リンクが自動的に無効になります。 リソースへのアクセスに必要なパスワード。 共有リンクの作成時にアクセスレベルを指定しなかった場合、会社の管理者が指定したデフォルトのアクセスレベルが使用されます。 ## ファイルの共有リンクの作成または更新 ファイルの共有リンクを作成するには、ファイルのIDとオプションの共有リンクパラメータを指定します。 ## フォルダの共有リンクの作成または更新 フォルダの共有リンクを作成するには、フォルダのIDとオプションの共有リンクパラメータを指定します。 ## ウェブリンクの共有リンクの作成または更新 ウェブリンクの共有リンクを作成するには、ウェブリンクのIDとオプションの共有リンクパラメータを指定します。 **Source:** [https://ja.developer.box.com/guides/shared-links/create-or-update/](https://ja.developer.box.com/guides/shared-links/create-or-update/) --- ### 共有リンクの削除 **Type:** guide | **Category:** 共有リンク | **Section:** Developer Guides 共有リンクの削除 ファイルを更新、フォルダを更新、またはウェブリンクを更新エンドポイントを呼び出し、shared_link値をnullに設定することで、リソースから共有リンクを削除できます。 共有リンクを削除して新しい共有リンクを作成すると、新しい共有リンクのURL… # 共有リンクの削除 [ファイルを更新](endpoint://put_files_id)、[フォルダを更新](endpoint://put_folders_id)、または[ウェブリンクを更新](endpoint://put_web_links_id)エンドポイントを呼び出し、`shared_link`値を`null`に設定することで、リソースから共有リンクを削除できます。 共有リンクを削除して新しい共有リンクを作成すると、新しい共有リンクのURLは以前と異なるものになり、以前のURLしか知らないユーザーはリソースにアクセスできなくなります。 ## ファイルの共有リンクの削除 ファイルの共有リンクを削除するには、ファイルのIDを指定し、`shared_link`フィールドを`null`に設定します。 ## フォルダの共有リンクの削除 フォルダの共有リンクを削除するには、フォルダのIDを指定し、`shared_link`フィールドを`null`に設定します。 ## ウェブリンクの共有リンクの削除 ウェブリンクの共有リンクを削除するには、ウェブリンクのIDを指定し、`shared_link`フィールドを`null`に設定します。 **Source:** [https://ja.developer.box.com/guides/shared-links/remove/](https://ja.developer.box.com/guides/shared-links/remove/) --- ### 共有リンクの権限 **Type:** guide | **Category:** 共有リンク | **Section:** Developer Guides 共有リンクの権限 共有リンクリソースには、permissionsフィールドを使用して更新できる3つの権限can_preview、can_download、can_editがあります。 ファイルの場合、can_editオプションにはtrue… # 共有リンクの権限 共有リンクリソースには、`permissions`フィールドを使用して更新できる3つの権限`can_preview`、`can_download`、`can_edit`があります。 ファイルの場合、`can_edit`オプションには`true`しか指定できません。また、管理者が管理コンソールで共有リンクの編集権限を制限している場合は、`can_edit`を`true`に設定することはできません。 ``` curl -i -X PUT 'https://api.box.com/2.0/files/123456789?fields=shared_link' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer [ACCESS TOKEN]' \ -d '{ "shared_link": { "permissions": { "can_preview": true, "can_download": true, "can_edit": true } } }' ``` **Source:** [https://ja.developer.box.com/guides/shared-links/permissions/](https://ja.developer.box.com/guides/shared-links/permissions/) --- ### 共有リンクの項目の検索 **Type:** guide | **Category:** 共有リンク | **Section:** Developer Guides 共有リンクの項目の検索 共有リンクの項目を検索APIは、BoxApi… # 共有リンクの項目の検索 [共有リンクの項目を検索](endpoint://get_shared_items)APIは、`BoxApi`ヘッダーを使用して共有リンクを入力として受け取り、その共有リンクが設定されているファイルまたはフォルダオブジェクトを返します。 共有リンクに関連付けられているファイルオブジェクトまたはフォルダオブジェクトを取得するには、リクエストの際に共有リンクの完全なURLを指定します。 共有リンクがフォルダに対するものである場合、このAPIのレスポンスには、そのフォルダ内のネストされた項目のリストが含まれないことに注意してください。 フォルダ内の項目をさらにトラバースするには、同じ`BoxApi`ヘッダーを使用して、[ネストされたフォルダ情報を取得する](e://get-folders-id)、[これらのフォルダ内の項目をリストする](e://get-folders-id-items)、[ネストされたファイル情報を取得する](e://get-files-id)、または[ファイルをダウンロード](e://get-files-id-content)してください。 **Source:** [https://ja.developer.box.com/guides/shared-links/find-for-item/](https://ja.developer.box.com/guides/shared-links/find-for-item/) --- ### 最初のアプリケーションの作成 **Type:** guide | **Category:** はじめに | **Section:** Developer Guides … # 最初のアプリケーションの作成 開発者用エンタープライズを設定したら、アプリケーションの作成を開始できます。 開発者用エンタープライズにログインしたら [[開発者コンソール](https://cloud.app.box.com/developers/console)] ボタンをクリックします。これが最初のアプリケーションである場合は、利用開始を促すメッセージが表示されます。 ## アプリケーションの種類の選択 まず、作成するアプリケーションの種類を選択します。ほとんどのパートナーが統合に [**Platformアプリ**] のオプションを使用しているため、このガイドではこの種類を使用します。 ## 認証方法の選択 [**Platformアプリ**] を選択したら、アプリで使用する[認証方法を選択](g://authentication/select)する必要があります。ほとんどのパートナーが統合に [[**ユーザー認証 (OAuth 2.0)**](g://authentication/oauth2)] のオプションを使用しているため、このガイドではこの種類を使用します。 ## アプリの命名 アプリの名前を選択します。名前は後から変更でき、アプリを公開するまで他の人の目に触れません。アプリの名前はアプリを公開すると管理者やお客様に表示されるため、わかりやすい名前を選択することをお勧めします。 [**アプリの作成**] ボタンをクリックしてアプリの作成を完了します。次に、アプリケーションの設定を構成します。 ## 一般設定 最も基本的な設定から始めます。[**一般設定**] タブを開き、以下のフィールドでチェックボックスをオンにしたり、入力したりします。 - [**アプリ名**] - アプリ作成時に設定する名前。ここで必要に応じて変更できます。 - [**連絡先メール**] - デフォルトでアプリケーションの開発者のアドレスに設定されます。アプリを公開すると、[統合](g://applications/integrations)でアプリを表示したBoxユーザーにこのアドレスが表示されることに注意してください。統合に問題があった場合にユーザーがサポートに連絡できるよう、サポートのメールアドレスに変更することをお勧めします。 - [**コラボレータ**] - この統合の作成に取り組むことができる他の開発者を追加します。追加された開発者は、設定を調整する必要があるときに開発者インターフェースにアクセスできるようになります。 ここに追加する開発者はすでにBoxユーザーである必要があります。Boxアカウントを持っていない場合は、開発者用エンタープライズで[アカウントを作成](https://support.box.com/hc/en-us/articles/360043694594-Add-Users)できます。 ## 詳細設定 [**構成**] タブに移動します。ここでは、アプリの詳細の指定、開発者トークンの生成、OAuth 2.0資格情報の確認、OAuth 2.0リダイレクトURIの追加と編集、アプリケーションスコープの選択、アプリの高度な機能の設定、CORSドメインの追加を行うことができます。 その他のタブでは、Webhookやウェブアプリ統合を作成したり、Enterpriseへのアクセスを有効化するためにアプリを送信したり、[Box統合](g://applications/integrations)にアプリを送信したり、このアプリケーションのアクティビティを確認できるレポートを生成したりすることができます。 ## アプリのテスト APIコールを行ってアプリをテストし、Boxでのレスポンス形式を確認できるようになりました。 現在の開発者アカウントに対して認証された[開発者トークン](g://authentication/tokens/developer-tokens/#create-developer-token)を使用します。 このトークンの有効期限は、生成されてから1時間です。 [Postmanコレクション](g://tooling/postman)から始めて、特定のコールを確認し、返されるレスポンスを確かめます。APIコールの例については、[APIリファレンスドキュメント](page://reference)を参照してください。ターミナルを使用したい場合は、[Box CLIツール](https://github.com/box/boxcli)を使用することもできます。 **Source:** [https://ja.developer.box.com/guides/getting-started/first-application/](https://ja.developer.box.com/guides/getting-started/first-application/) --- ### 最近の共有リンクの検索 **Type:** guide | **Category:** 検索 | **Section:** Developer Guides 最近の共有リンクの検索 デフォルトで検索APIによって返されるのは、ユーザーが所有する項目か、ユーザーが明示的にコラボレータに設定されている項目のみです。これらの検索結果には、ユーザーが共有リンクを介して最近アクセスした可能性がある項目は含まれません。 このAPI… # 最近の共有リンクの検索 デフォルトで検索APIによって返されるのは、ユーザーが所有する項目か、ユーザーが明示的にコラボレータに設定されている項目のみです。これらの検索結果には、ユーザーが共有リンクを介して最近アクセスした可能性がある項目は含まれません。 このAPIで共有リンクを有効にするには、`include_recent_shared_links`クエリパラメータを`true`に設定します。 ``` curl -i -X GET "https://api.box.com/2.0/search?query=sales&include_recent_shared_links=true" \ -H "Authorization: Bearer <ACCESS_TOKEN>" ``` ``` client.search().query("sales", metadata_filters=metadata_search_filters, include_recent_shared_links=True) ``` ``` client.search.query( 'sales', { include_recent_shared_links: true }) .then(results => { // ... }); ``` このパラメータは比較的新しいため、BoxのJava SDKとWindows SDKでのこのパラメータのサポートはまだ対応中であることに注意してください。 このパラメータがtrueに設定されている場合は、このAPIのレスポンス形式が[検索結果 (複数の共有リンクを含む)](r://search-results-with-shared-links) のリストを返すよう変更されることに十分注意してください。 **Source:** [https://ja.developer.box.com/guides/search/shared-links/](https://ja.developer.box.com/guides/search/shared-links/) --- ### 分割アップロード **Type:** guide | **Category:** アップロード | **Section:** Developer Guides 分割アップロード 大きなファイルでも、分割アップロードAPIを使用して一連のパーツに分割して個別にアップロードすることで、Boxに確実にアップロードできます。 このAPI… # 分割アップロード 大きなファイルでも、分割アップロードAPIを使用して一連のパーツに分割して個別にアップロードすることで、Boxに確実にアップロードできます。 このAPIを使用することにより、アプリケーションではファイルを分割してアップロードできるため、失敗したリクエストからより確実に回復できるようになります。つまり、アプリケーションがファイル全体ではなく単一のパーツのアップロードを再試行するだけで済む、ということです。 分割アップロードのもう1つの利点は、パーツを並行してアップロードできるため、パフォーマンスが向上することです。 ## 概要 分割アップロードでは、以下の一連のAPIコールを行う必要があります。 1. **[アップロードセッションを作成する](g://uploads/chunked/create-session)**: アプリケーションが新しいファイルまたはファイルの新しいバージョンのアップロードセッションを作成します。このセッションにより、ファイルの (新しい) 名前、サイズ、および親フォルダを定義します。 2. **[パーツをアップロードする](g://uploads/chunked/upload-part)**: アプリケーションがファイルの個々のパーツをチャンクとしてアップロードします。 3. **[セッションをコミットする](g://uploads/chunked/commit-session)**: アプリケーションがセッションをコミットします。このときにファイルの整合性がチェックされた後、セッションが作成されたときに指定された場所にファイルが配置されます。 ほとんどの[Box SDKではBoxからの分割アップロードがサポートされている](g://uploads/chunked/with-sdks)ため、アプリケーションコードの複雑さが解消されます。 ## 制約事項 分割アップロードAPIは、サイズが20 MB以上の大きいファイルを対象としています。これより小さいサイズのファイルのアップロードはサポートされていません。 このAPIは、セッション内でのパーツの再アップロードまたは上書きをサポートしていません。アップロード後のパーツは変更できません。 アップロードセッションの有効期間は7日間です。この期間に、クライアントは自身のペースでパーツをアップロードできます。 リソースの浪費やデータ破損を避けるために、クライアントは、アップロードの開始以降、ディスク上の基になるファイルが変更されていないことを確認する必要があります。 **Source:** [https://ja.developer.box.com/guides/uploads/chunked/](https://ja.developer.box.com/guides/uploads/chunked/) --- ### 分類 **Type:** guide | **Category:** メタデータ | **Section:** Developer Guides 分類 Boxを使用すると、ユーザーおよびアプリケーションは、セキュリティ分類ラベルをファイルを適用したり、分類ラベルをフォルダとそのコンテンツにカスケードしたりできます。分類は、BoxのGovernanceおよびShield… # 分類 Boxを使用すると、ユーザーおよびアプリケーションは、セキュリティ分類ラベルをファイルを適用したり、分類ラベルをフォルダとそのコンテンツにカスケードしたりできます。分類は、BoxのGovernanceおよびShield製品から不注意でアクセスされないよう、共有した機密性の高いコンテンツを保護するのに役立ちます。 分類APIを使用すると、新しい分類ラベルを作成したり、分類をファイルやフォルダに割り当てたりすることができます。 分類では、[メタデータAPI](g://metadata)を使用して、分類ラベルを作成したり、分類をファイルやフォルダに割り当てたりします。メタデータテンプレートとメタデータインスタンスの詳細については、[メタデータ](g://metadata)に関するガイドを参照してください。 ## 分類とメタデータ 分類を使用する場合、開発者はメタデータテンプレートとメタデータインスタンスを操作する必要があります。 - **分類テンプレート:** 分類を使用するために、会社では、1つ以上の分類を含む分類メタデータテンプレートを用意する必要があります。このテンプレートでは、`scope`/`templateKey`を`enterprise.securityClassification-6VMVochwUWo`にしておく必要があります。このテンプレートは、使用可能な分類レベル、そのラベル名、説明、`colorID`値を保持します。 - **テンプレートインスタンス**: ファイルやフォルダに分類を適用するために、開発者は、`enterprise.securityClassification-6VMVochwUWo`テンプレートのインスタンスを項目に適用します。テンプレートが適用されると、テンプレート上の分類のリストから分類のいずれかが選択されます。 **Source:** [https://ja.developer.box.com/guides/metadata/classifications/](https://ja.developer.box.com/guides/metadata/classifications/) --- ### 列挙型メタデータフィールド **Type:** guide | **Category:** メタデータ | **Section:** Developer Guides 列挙型メタデータフィールド enumタイプのメタデータフィールドは、ドロップダウンリストとしてユーザーに表示されます。ユーザーはリストから項目を1つ選択できます。 enumを使用すると、ユーザーは0個または… # 列挙型メタデータフィールド `enum`タイプのメタデータフィールドは、ドロップダウンリストとしてユーザーに表示されます。ユーザーはリストから項目を1つ選択できます。 `enum`を使用すると、ユーザーは0個または1個の値を選択できます。ユーザーが複数の値を選択できるようにするには、[`multiSelect`](g://metadata/fields/multi-select)テンプレートフィールドを使用します。 ## enumフィールドの作成 `enum`フィールドは、[メタデータテンプレートの作成](g://metadata/templates/create)時、または`addField`操作による[テンプレートの更新](g://metadata/templates/update)時にメタデータテンプレートに追加できます。 `enum`フィールドの必須属性は、`type`、`displayName`、`key`、およびオプションのリストです。 ``` { "scope": "enterprise", "displayName": "Contract", "fields": [ { "type": "enum", "key": "customer_state", "displayName": "Customer State", "description": "The US state where the customer is located", "hidden": false, "options": [ {"key": "N/A"}, {"key": "AL"}, {"key": "AK"} ] } ] } ``` 必要に応じて、UIでユーザーに表示される`description`を指定できます。また、このフィールドを`hidden`に設定して、ウェブアプリとモバイルアプリでユーザーに表示されないようにすることもできます。 ## enumフィールドの更新 `enum`テンプレートフィールドは、このフィールドが属する[テンプレートを更新](g://metadata/templates/update)することで更新できます。テンプレートの更新は、ファイルまたはフォルダにすでに割り当てられているテンプレートも確実に更新される**操作**によって行われます。 ### 基本的なフィールド値の変更 `enum`メタデータフィールドを更新する際に可能な操作の1つとして、フィールドの`key`、`displayName`、`description`、および`hidden`の値を変更するのに使用できる`editField`操作があります。 ``` [ { "op": "editField", "fieldKey": "customer_state", "data": { "displayName": "Customer State (USA)", "key": "customer_state_usa" } } ] ``` ここにある`fieldKey`は、変更するフィールドの元のキーを表します。`data.key`フィールドはフィールドの新しいキーです。 これは、このテンプレートの既存のインスタンスに影響します。 ### オプションの追加 `enum`フィールドにオプションを追加するには、`addEnumOption`操作を使用します。この操作では、`fieldKey`に、変更する`enum`フィールドのキーを設定するほか、`data`オブジェクトには、追加する新しいオプションの`key`を指定する必要があります。 ``` [ { "op": "addEnumOption", "fieldKey": "customer_state", "data": { "key": "AR" } } ] ``` オプションのリストは次のようになります。 ``` ... "options": [ {"key": "N/A"}, {"key": "AL"}, {"key": "AK"}, {"key": "AR"} ] ... ``` これは、このテンプレートの既存のインスタンスに影響します。 ### オプションの並べ替え `enum`フィールドでオプションを並べ替えるには、`reorderEnumOptions`操作を使用します。この操作では、`fieldKey`に、変更する`enum`フィールドのキーを設定するほか、`enumOptionKeys`配列にはオプションのキーを順番に指定する必要があります。 ``` [ { "op": "reorderEnumOptions", "fieldKey": "customer_state", "enumOptionKeys": [ "AL", "AK", "AR", "N/A" ] } ] ``` オプションのリストは次のようになります。 ``` ... "options": [ {"key": "AL"}, {"key": "AK"}, {"key": "AR"}, {"key": "N/A"} ] ... ``` この操作では、新しいオプションを追加することはできません。これは、このテンプレートの既存のインスタンスに影響します。 ### オプションの編集 `enum`フィールドのオプションを編集するには、`editEnumOption`操作を使用します。この操作では、`fieldKey`に、変更する`enum`フィールドのキーを設定し、`enumOptionKey`に、フィールドオプションのキーを設定する必要があります。最後に、`data`オブジェクトには、フィールドオプションの新しい`key`を指定する必要があります。 ``` [ { "op": "editEnumOption", "fieldKey": "customer_state", "enumOptionKey": "N/A", "data": { "key": "Outside USA" } } ] ``` オプションのリストは次のようになります。 ``` ... "options": [ {"key": "AL"}, {"key": "AK"}, {"key": "AR"}, {"key": "Outside USA"} ] ... ``` これは、このテンプレートの既存のインスタンスに影響します。 ### オプションの削除 `enum`フィールドからオプションを削除するには、`removeEnumOption`操作を使用します。この操作では、`fieldKey`に、変更する`enum`フィールドのキーを設定し、`enumOptionKey`に、削除するフィールドオプションのキーを設定します。 ``` [ { "op": "removeEnumOption", "fieldKey": "customer_state", "enumOptionKey": "AL" } ] ``` オプションのリストは次のようになります。 ``` ... "options": [ {"key": "AK"}, {"key": "AR"}, {"key": "Outside USA"} ] ... ``` これは、このテンプレートの既存のインスタンスに影響します。この値に設定されたすべてのフィールドでは、値が`null`にリセットされます。 **Source:** [https://ja.developer.box.com/guides/metadata/fields/enum/](https://ja.developer.box.com/guides/metadata/fields/enum/) --- ### 制限 **Type:** guide | **Category:** ファイル | **Section:** Developer Guides 制限 ファイルの操作には、いくつかの制限があります。 名前に関する制約事項 ファイルの名前にはいくつかの制約事項があります。印刷不可能なASCII… # 制限 ファイルの操作には、いくつかの制限があります。 ## 名前に関する制約事項 ファイルの名前にはいくつかの制約事項があります。印刷不可能なASCII文字、スラッシュ、およびバックスラッシュ (`/`、`\`) を含む名前のほか、`.`や`..`のような予約済みの名前は、許可されていない文字を削除して自動的にサニタイズされます。 **Source:** [https://ja.developer.box.com/guides/files/limitations/](https://ja.developer.box.com/guides/files/limitations/) --- ### 制限 **Type:** guide | **Category:** メタデータ | **Section:** Developer Guides 制限 メタデータクエリAPIには、いくつかの制限が適用されます。 ファイルとフォルダ ​メタデータクエリで返されるのは、リクエストしているユーザーがpreviewer… # 制限 メタデータクエリAPIには、いくつかの制限が適用されます。 ## ファイルとフォルダ ​メタデータクエリで返されるのは、リクエストしているユーザーが`previewer`以上のアクセス権限を持つ項目 (ファイルまたはフォルダ) のみです。 ## 会社のテンプレートとグローバルテンプレート メタデータクエリは、その会社によって作成されたメタデータテンプレートでのみ動作します。クエリでは、`​global.properties`テンプレートに保存された自由形式のキー/値ペアのコンテンツに基づく結果が返されません。 ## 分類メタデータテンプレート Boxでは、メタデータテンプレートを使用してコンテンツの分類を行うことができます。これらのメタデータテンプレートはメタデータクエリでは使用できません。なぜなら、大きな結果セットに関する問題が発生する可能性が高いためです。詳細は次に説明しています。 当面、将来これらのクエリのサポートを開始する計画はありません。 ## 推奨される結果セットのサイズ 可能であれば、結果セットの項目数が2,000未満になるリクエストのみを送信することをお勧めします。結果セットは、リクエストするユーザーの権限と`​ancestor_folder​`スコープが考慮される前に、`​from​`、`​query​`および`​query_params​`パラメータの評価だけに基づいてメタデータクエリに一致するファイルとフォルダのコレクション全体です。 結果セットの項目数が2,000を超えるメタデータクエリリクエストを送信した場合、APIは、以下の条件が両方とも満たされる場合に一致する結果をすべて返すことのみを保証できます。 1. リクエストするユーザーが、結果セットに含まれるすべての項目に対して**プレビューアー**以上の権限を持っていること。 2. 先祖フォルダに、結果セット内のすべてのファイルが含まれていること。 結果セットの項目数が2,000を超えており、上記の条件が当てはまらないメタデータクエリリクエストを送信すると、APIは、返される結果が少なくなるようクエリを制限する必要があることを示すレスポンスコード4XXとともにエラーを返す可能性があります。 たとえば、次に示す、`catalogImages​`というメタデータテンプレートの簡略化したレプリゼンテーションを考えてみます。これには、`​photographer`という文字列フィールドが1つあります。 ``` { "templateKey": "catalogImages", "fields": [ { "type": "string", "key": "photographer" } ] } ``` この例では、10人のphotographer (写真家) がいて、それぞれが`catalogImages​`テンプレートが適用されている同じ数の画像を取り込むとします。 ここで、Box Enterpriseに、`catalogImages`テンプレートが適用され、2つのフォルダ`Parts​`と`Products`に均等に分けられている、4,000個のファイルがあると考えてみます。この2つのフォルダは、以下に示すように親フォルダ`​Catalog​`の子です。 ``` Catalog/ | |- Parts/ | |- file_0000.jpeg |- ... |- file_1999.jpeg |- Products/ | |- file_2000.jpeg |- ... |- file_3999.jpeg ``` 以下の表に、考えられるいくつかのクエリの結果を示します。クエリについては、読みやすくするために平易な言葉で説明しています。 結果セットは、リクエストするユーザーの権限と`​ancestor_folder​`スコープが考慮される前に、`​from​`、`​query​`および`​query_params`パラメータの評価だけに基づいてメタデータクエリに一致する項目 (ファイルとフォルダ) のコレクションとして定義されることに注意してください。 | クエリ | 結果セット | 結果 | メモ | | --- | --- | --- | --- | | catalogImagesテンプレートが適用されている、写真家がMikeの項目を選択します。 | 200項目 | 成功 | Mikeに対応する項目のみを選択することで、結果セットはたった400ファイルに抑えられます。 | | catalogImagesテンプレートが適用されている項目を選択します。 | 4,000項目 | 失敗する可能性あり | 結果セットは2,000項目を超えます。ユーザーが結果セット内のすべてのファイルにアクセスできない場合は、クエリが失敗する可能性があります。 | | Products​フォルダにある、catalogImagesテンプレートが適用されている項目を選択します。 | 4,000項目 | 失敗する可能性あり | 結果セットは2,000項目を超えます。すべての結果が先祖フォルダに含まれるわけではありません。 | | Productsフォルダにある、catalogImagesテンプレートが適用されている、写真家がMikeの項目を選択します。 | 200項目 | 成功 | Mikeに対応する項目のみを選択することで、結果セットはたった400ファイルに抑えられます。 | **Source:** [https://ja.developer.box.com/guides/metadata/queries/limitations/](https://ja.developer.box.com/guides/metadata/queries/limitations/) --- ### 制限 **Type:** guide | **Category:** Webhook | **Section:** Developer Guides 制限 Webhookは1項目につき1つ Webhookは、1つの項目 (ファイルまたはフォルダ)、1つのアプリケーション、1人の認証済みユーザーごとに1つだけという制限があります。 ある項目にWebhookを1つ追加した後は、別のトリガーイベントに応答するWebhook… # 制限 ## Webhookは1項目につき1つ Webhookは、1つの項目 (ファイルまたはフォルダ)、1つのアプリケーション、1人の認証済みユーザーごとに1つだけという制限があります。 ある項目にWebhookを1つ追加した後は、別のトリガーイベントに応答するWebhookであっても、2つ目を追加することはできません。 例: `CleanupApp`というアプリケーションに関する`Junk`というフォルダ内の`FILE.UPLOADED`イベントを監視するように、`John Doe`によってWebhookが1つ設定されると、その時点で、`FILE.DOWNLOADED`イベントに対してトリガーされるものであっても、`John Doe`によって`CleanupApp`が`Junk`フォルダに2つ目のWebhookを追加することはできません。 別のイベントをリッスンするには、既存のWebhookを[更新](g://webhooks/v2/update-v2)するか、新しいアプリケーションを作成します。 ## Webhookの上限は1000個 各アプリケーションおよび各ユーザーのWebhookの数は1000個までという制限があります。 1人のユーザーにさらにWebhookを作成するには、別のアプリケーションを作成するか、フォルダツリーでより上位に適用するよう[既存のWebhookを更新](g://webhooks/v2/update-v2)します。 ## 通知URLに関する制約事項 Webhookの通知URL (`address`) は、有効なIPアドレスに解決される有効なHTTPS URLでなくてはなりません。これには、信頼できる認証局によって署名された証明書が必要になります。Boxでは自己署名SSL証明書がサポートされていません。 サーバーのIPアドレスは、インターネットからパブリックにアクセスできる必要があり、`(*.)box.com`アドレスにすることはできません。URLで使用されるポートは、標準HTTPSポート (`443`) でなければなりません。通知は他のポートには配信されません。 サポートされているTLSプロトコルのバージョンは、FIPS準拠の暗号スイートに対応した`TLS 1.2`と`TLS 1.3`です。 ## Webhookはルートフォルダに追加不可 V2 Webhookをルートフォルダ (IDが`0`のフォルダ) に作成することはできません。代わりに[V1 Webhook](g://webhooks/v1)を使用する必要があります。 項目の権限が原因でアクションを実行できない場合、試行されたアクションについての通知は送信されません。 ## NO_ACTIVE_SESSIONはWebhookペイロードで設定 Webhookの作成に使用したアプリの認証セッション (アクセストークン) が期限切れになると、そのWebhookでは、ペイロード全体を含むイベントが送信されなくなります。その場合、イベントトリガーは`NO_ACTIVE_SESSION`になります。 ### JWT認証 JWT認証アプリを使用して作成されたWebhookの場合、管理コンソールでこのアプリに対するアプリ承認を削除すると、セッションが期限切れになります。詳細については、[アプリケーションの承認ガイド](https://support.box.com/hc/en-us/articles/360043697014-Authorizing-Apps-in-the-Box-App-Approval-Process)を参照してください。 ### OAuth 2.0 OAuth 2.0認証アプリを使用して作成されたWebhookの場合、そのWebhookの作成に使用されたユーザーとアプリのアクセストークンと更新トークンの両方が期限切れになると、セッションが期限切れになります。 ### 開発者トークン 開発者トークンは更新できず、1時間後に期限切れになるため、イベントトリガー`NO_ACTIVE_SESSION`は、1時間後にWebhookペイロードで設定されます。 ## Webhookの削除理由 Webhookは以下の理由で削除される可能性があります。 1. Boxアプリケーションを削除すると、そのアプリケーションに関連付けられているすべてのWebhookが自動的に削除されます。 2. Webhookに関連付けられているアクティブなアクセストークンをすべて削除すると、そのWebhookが自動的に削除されます。これには、開発者トークンとパスワードが含まれます。 3. 最後に成功した配信から30日が経過し、最後に配信が成功した日から最後のトリガーの日付までの期間が14日を超えた場合、Webhookは自動的に削除されます。 これらのすべてのケースで、Boxは`WEBHOOK.DELETED`というイベント名を含むWebhookペイロードを通知URLに送信します。ペイロードの本文には以下の追加情報が含まれます。 ``` "additional_info": { "reason": "auto_cleanup" } ``` **Source:** [https://ja.developer.box.com/guides/webhooks/v2/limitations-v2/](https://ja.developer.box.com/guides/webhooks/v2/limitations-v2/) --- ### 割り当てのメッセージの変更 **Type:** guide | **Category:** タスク | **Section:** Developer Guides 割り当てのメッセージの変更 タスク割り当てのメッセージを更新するには、PUT /tasks/:task_id/assignments APIを呼び出し、タスク割り当ての新しいmessageを含めます。 # 割り当てのメッセージの変更 タスク割り当てのメッセージを更新するには、[`PUT /tasks/:task_id/assignments`](e://put_task_assignments_id) APIを呼び出し、タスク割り当ての新しい`message`を含めます。 **Source:** [https://ja.developer.box.com/guides/tasks/assignments/update-message/](https://ja.developer.box.com/guides/tasks/assignments/update-message/) --- ### 単一フォルダ **Type:** guide | **Category:** フォルダ | **Section:** Developer Guides 単一フォルダ 以下のページでは、単一フォルダに対するさまざまな操作方法について説明します。 # 単一フォルダ 以下のページでは、単一フォルダに対するさまざまな操作方法について説明します。 **Source:** [https://ja.developer.box.com/guides/folders/single/](https://ja.developer.box.com/guides/folders/single/) --- ### 呼び出しURL **Type:** guide | **Category:** Box Skills | **Section:** Developer Guides 呼び出しURL 新しいBox Skillsアプリケーションの作成時に、invocation_urlを指定するよう求められます。このURLは、Skillsアプリが監視するフォルダ内にファイルがアップロード、コピー、移動されたときに、Box… # 呼び出しURL 新しい[Box Skillsアプリケーション](guide://applications/app-types/custom-skills)の作成時に、`invocation_url`を指定するよう求められます。このURLは、Skillsアプリが監視するフォルダ内にファイルがアップロード、コピー、移動されたときに、Boxから[イベント通知ペイロード](guide://skills/handle/payload)が送信される公開ウェブアドレスです。 この通知をリッスンしているウェブサイトまたはアプリケーションは、Box上のファイルと、ファイルからインサイトを取得するために使用されている機械学習システムなどのシステムの間のブリッジとして機能します。 ## 要件 - 呼び出しURLは一般公開する必要があります。`localhost`または`127.0.0.1`のアドレスにはBoxのサーバーからアクセスできないため、通知を送信できません。 - 呼び出しURLの背後にあるサーバーは、HTTP `POST`リクエストをリッスンしている必要があります。Box Skillsは、`JSON`本文を使用した`POST`リクエストを介してイベント通知を送信します。 ## ホスティングのヒントとテクニック Boxのサーバーが`invocation_url`として使用できるよう、アプリケーションを公開URLですばやく公開する方法はいくつかあります。 - **ローカルトンネル** - 開発者のマシン上にあるウェブアプリケーションを公開アドレスに公開する最も簡単な方法の1つは、ローカルトンネルの使用です。一般的なトンネリングツールには、[`ngrok`](https://ngrok.com)や[`localtunnel`](https://www.npmjs.com/package/localtunnel)があります。 - **サーバーレス関数** - Box Skillを処理できるサーバーを設定するには、**サーバーレス関数**が役立ちます。Box Skillsは、監視対象のフォルダ内のアクティビティ (の欠如) に応じて生成できる呼び出しの数が異なります。[AWS Lambda](https://aws.amazon.com/lambda/)、[Google Cloud Functions](https://cloud.google.com/functions/)、[Microsoft Azure Functions](https://azure.microsoft.com/en-us/services/functions/)などのサーバーレス関数は、このような散発的なイベントに適しています。サーバーレス関数は、イベントの処理中にのみ実行され、課金の対象となります。 - **従来のアプリケーションホスティング** - サーバーレステクノロジが望ましくない場合、[Heroku](https://www.heroku.com/)、[Firebase](https://firebase.google.com/)、[AWS](https://aws.amazon.com/)、[GCP](https://cloud.google.com/functions/)など、従来のアプリケーションホスティングソリューションも使用できます。これらのアプリケーションはそれぞれ固有のサービスでホストされ、アプリケーション用の公開URLが呼び出しURLとして使用されます。 ## アプリケーションサーバーの詳細 一般に、呼び出しURLの背後にあるアプリケーションは、以下のタスクを実行する必要があります。 1. Boxからのイベント通知をキャプチャする。 2. Boxファイル (またはそのURL) のバイナリデータを処理サービスに送信する。 3. 処理サービスからのレスポンスをリッスンする。 4. 処理サービスからのレスポンスをBoxメタデータ形式に変換する。 5. Boxに保存されているファイルに新しいメタデータを適用する。 **Source:** [https://ja.developer.box.com/guides/skills/invocation-url/](https://ja.developer.box.com/guides/skills/invocation-url/) --- ### 基本的なサムネイルの取得 **Type:** guide | **Category:** レプリゼンテーション | **Section:** Developer Guides 基本的なサムネイルの取得 サムネイルとは小さい画像のことで、アプリケーション内でファイルのレプリゼンテーションとして使用できる.pngまたは.jpg… # 基本的なサムネイルの取得 サムネイルとは小さい画像のことで、アプリケーション内でファイルのレプリゼンテーションとして使用できる`.png`または`.jpg`で表されます。たとえば、ファイルをダウンロードまたはプレビューするリンクのプレースホルダとして使用されます。 ファイルのサムネイルを取得するには、[レプリゼンテーションAPI](guide://representations/thumbnail-representation)を使用する方法をお勧めします。 ## リクエスト ファイルのサムネイルをリクエストするには、[`GET /files/:id/thumbnail.:extension`](endpoint://get_files_id_thumbnail_id)エンドポイントを使用します。 サムネイルの作成に成功すると、そのサムネイルがレスポンスの本文内でバイナリデータとして返されます。 ## サムネイルの非同期的な作成 場合によっては、サムネイルを直接作成できないこともあります。代わりに、APIから`location`レスポンスヘッダーで`HTTP 202`が返されます。この場所は、サムネイルの生成中に使用できる一時的な画像のためのものです。 このエンドポイントを再試行するまでの推定秒数を示す`retry-after`レスポンスヘッダーも返されます。 ## サポートされているファイルサイズ 以下のサムネイルの形式とサイズが使用可能です。 | ファイルの種類 | サイズ | | --- | --- | | JPG | 32x32, 94x94, 160x160, 320x320, 1024x1024, 2048x2048* | | PNG | 1024x1024*, 2048x2048* | `*`が付いているサイズには、いくつかの制限があります。 ## ファイルサイズの制限 ### 元のファイルサイズ サムネイルは拡大されません。Boxにアップロードされたファイルの元のファイルサイズがレプリゼンテーションのサイズより小さい場合は、作成されるサムネイルのサイズの上限は元のファイルのサイズになります。 ## サポートされているファイルの種類 現時点でサポートされているファイルの種類は以下のとおりです。 | ファイルの種類 | ファイル拡張子 | | --- | --- | | ドキュメント | doc, docx, gdoc, gsheet, gslide, gslides, odp, ods, odt, pdf, ppt, pptx, rtf, wpd, xls, xlsm, xlsx, key, pages, numbers | | 画像 | ai, bmp, dcm, dicm, eps, gif, idml, indd, indt, inx, jpeg, jpg, png, ps, psd, svg, svs, tif, tiff, tga | | オーディオ | aac, aifc, aiff, amr, au, flac, m4a, mp3, ogg, ra, wav, wma | | 動画 | 3g2, 3gp, avi, m2v, m2ts, m4v, mkv, mov, mp4, mpeg, mpg, mts, ogg, qt, wmv | **Source:** [https://ja.developer.box.com/guides/representations/thumbnail/](https://ja.developer.box.com/guides/representations/thumbnail/) --- ### 専用スコープ **Type:** guide | **Category:** Boxの埋め込み | **Section:** Developer Guides 専用スコープ Box UI Elementsを使用する際に、開発者の多くが、Box… # 専用スコープ Box UI Elementsを使用する際に、開発者の多くが、Boxが定義した[アクセスレベル](https://support.box.com/hc/ja/articles/360044196413-%E3%82%B3%E3%83%A9%E3%83%9C%E3%83%AC%E3%83%BC%E3%82%BF%E3%81%AE%E6%A8%A9%E9%99%90%E3%83%AC%E3%83%99%E3%83%AB%E3%81%AB%E3%81%A4%E3%81%84%E3%81%A6)とは異なる独自の権限モデルを実装できることに関心を示します。 [ダウンスコープ](g://authentication/tokens/downscope) (トークン交換とも呼ばれます) とは、開発者がアクセストークンに対する権限をより詳細に制限できるBoxのメカニズムです。このメカニズムを使用することで、開発者はBox Platform上に独自の権限モデルを構築できます。 ## スコープとUI Element このプロセスを容易にするために、BoxではAPIスコープの新しいセットを作成しました。これにより、開発者は、UI Elementを利用しているアプリケーションでエンドユーザーが使用できるUIコントロールを制御できます。 Box UI Elementは、これらのスコープによって適用される権限を配慮するよう設計されています。したがって、対応する機能をトークンが許可するかどうかに応じて、UIコントロールが自動的に有効または無効になります。 このほかにも、これらの新しいスコープには利点があります。トークンのスコープは、アプリケーションでエンドユーザーにアクセスを許可する操作の厳密なセットに限定されるため、知識のあるエンドユーザーは、トークンを使用してAPIから直接アクセスすることはできません。このように、アプリケーションの安全性を強化できます。 ## スコープの原則 新しいスコープは、以下の原則を念頭に置いて設計されています。 - **すべてのスコープはモジュール化され、厳密には累積される:** 開発者はトークン交換リクエストで複数のスコープを組み合わせて、必要な機能セットを含むトークンを生成できます。また、混乱を避けるために、2つのスコープに同じ権限を設定しないでください。 - **スコープはUI Elementでの特定の操作に直接マップされる:** つまり、このスコープをトークンに追加すると、特定の操作が有効になります。特定のUI Elementで実行できるのは一部の操作のみのため、一部のスコープは意味を持ってこのUI Elementのみに適用される可能性があります。 - **スコープには、対応する操作の実行に必要な最小限の権限セットが含まれている:** アプリケーションのエンドユーザーの一部がAPIに対して直接トークンを使用しても、UI Elementを介して提供するよう意図した機能以外にはアクセスできません。 - **各UI Elementには、そのUI Elementが正常に機能するために必要なすべての権限がカプセル化されている「基本スコープ」が必要:** トークンの権限が少なくなると、UI Elementに対する基本的な操作が機能しません。このスコープを必ずトークン交換リクエストに含める必要があります。 上記の内容を踏まえて、各UI Elementには、以下の2種類のスコープを追加しています。 ### 基本スコープ 各UI Elementには「基本スコープ」があります。これにより、そのUI Elementが動作するために必要な最小限の権限のセットが提供されます。そのため、この「基本スコープ」は常にトークン交換リクエストに存在する必要があります。各UI Elementが動作するための基本の権限セットは異なる場合があるため (たとえば、コンテンツアップローダーUI Elementはプレビュー権限を必要としない)、UI Elementがそれぞれ独自の基本スコープを持っている可能性があります。 ### 機能のスコープ 基本スコープ以外に、機能レベルのスコープも導入されました。機能スコープを基本スコープと組み合わせる際、UI Element内で追加の機能が有効になります。また、ユーザーには、ダウンスコープされたトークンに追加された機能スコープで規定された操作を実行する権限が付与されます。基本スコープと同様、機能スコープもほとんどがUI Elementごとに異なります。機能スコープは厳密には累積されるため、(ドキュメントに別途記載がない限り) スコープに対するアクセス権限のみをユーザーに付与すると、そのユーザーには対応する操作のみを実行する権限が付与されることを想定できます。 基本スコープと機能スコープについて理解したところで、各UI Elementに関するドキュメントを参照してその専用スコープの詳細を確認してください。 **Source:** [https://ja.developer.box.com/guides/embed/ui-elements/scopes/](https://ja.developer.box.com/guides/embed/ui-elements/scopes/) --- ### 履歴からストリームへの移行 **Type:** guide | **Category:** イベント | **Section:** Developer Guides 履歴からストリームへの移行 Boxでは、admin_logsを使用してライブイベントを登録しているアプリケーションをadmin_logs_streamingに移行することをお勧めします。admin_logs_streaming… # 履歴からストリームへの移行 Boxでは、`admin_logs`を使用してライブイベントを登録しているアプリケーションを`admin_logs_streaming`に移行することをお勧めします。`admin_logs_streaming`を使用すると、レイテンシが低下し、一貫性が高まるだけでなく、遅れて届くイベントが見逃されなくなります。`admin_logs`と`admin_logs_streaming`の間のイベントの重複は、イベントIDを使用して排除することが可能です。 ## Enterpriseのstream_typeの比較 ### admins_logs_streamingのメリット - 遅れて届くイベントが、登録しているアプリケーションで見逃されなくなる - レイテンシが80%低下する (通常の操作時) - より一貫性のあるレイテンシが実現する (通常の操作時) - 遅れたイベントの埋め戻しをサービスで管理する必要がなくなったため、障害からの復旧がよりスムーズになる ### admin_logsとadmin_logs_streamingの相違点 - 2週間分のイベント履歴 (リテンション) が提供される - `created_after`および`created_before`フィルタパラメータがサポートされない - 重複を含む可能性がある (「少なくとも1回」は保証されている) - イベントが時系列で返されなくなる (イベントはほぼ処理された順で返される) ### admin_logsとadmin_logs_streamingの類似点 - 同じ[`GET /events`](e://events) APIエンドポイントを共有する - 同じイベントペイロードを返す (イベントIDを使用して2つのストリームタイプでのイベントの重複排除が可能) - `event_type`によるフィルタが可能 - `stream_position`を使用したイベントのページ割りが可能 ## admin_logsからadmin_logs_streamingへの移行方法 ### 1. 既存のリクエストは以下のようになります ``` curl https://api.box.com/2.0/events?stream_type=admin_logs&stream_position=1632893855 \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ### 2. admin_logs_streamingを使用して重複する既存のリクエストを開始します - 2週間前から開始し、埋め戻しする: ``` curl https://api.box.com/2.0/events?stream_type=admin_logs_streaming&stream_position=0 \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` または - 今すぐ開始し、並行して実行する: ``` curl https://api.box.com/2.0/events?stream_type=admin_logs_streaming&stream_position=now \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ### 3. これまでの結果のページ割りを行い、admin_logsイベントとの重複を排除します ``` curl https://api.box.com/2.0/events?stream_type=admin_logs_streaming&stream_position=1632893855 \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ### 4. 十分と思われるまで重複を継続します ### 5. 古いadmin_logsリクエストを無効にします **Source:** [https://ja.developer.box.com/guides/events/enterprise-events/migrate-to-stream/](https://ja.developer.box.com/guides/events/enterprise-events/migrate-to-stream/) --- ### 承認 **Type:** guide | **Category:** 承認 | **Section:** Developer Guides 承認 アプリケーションによっては、企業で使用する前に管理者の明示的な承認が必要になる場合があります。管理者が行う必要のある手順は、開発者が選択した認証方法と有効になっているEnterprise… # 承認 アプリケーションによっては、企業で使用する前に管理者の明示的な承認が必要になる場合があります。管理者が行う必要のある手順は、開発者が選択した認証方法と有効になっているEnterprise設定によって異なります。 ## 認証方法 以下の[認証方法](g://authentication/select)では、常に管理者の明示的な承認が必要です。 - [サーバー認証 (JWT使用)](g://authentication/jwt) - [サーバー認証 (クライアント資格情報許可使用)](g://authentication/client-credentials) - [カスタムスキル](g://applications/app-types/custom-skills) これらの認証方法では、[サービスアカウント](page://platform/user-types/#service-account)が自動的に生成されます。適切な[スコープ](g://api-calls/permissions-and-errors/scopes)が有効になっていると、サービスアカウントは管理者の多くの操作を実行できるため、使用する前に管理者の承認が必要になります。 [OAuth 2.0](g://authentication/oauth2)アプリと[アプリトークン](g://authentication/app-token)も、有効になっているEnterprise設定に基づき、管理者の明示的な承認が必要になる場合があります。 ## Enterprise設定 以下のEnterprise設定のいずれかが有効になっている場合は、後続の手順が必要です。 - デフォルトで公開サードパーティ製アプリを無効にする - デフォルトで未公開アプリを無効にする - アクセス制限付きアプリの場合に管理者の承認を要求する これらの[設定](https://support.box.com/hc/ja/articles/360044196653-%E3%82%AB%E3%82%B9%E3%82%BF%E3%83%A0%E3%82%A2%E3%83%97%E3%83%AA%E3%81%AE%E7%AE%A1%E7%90%86)は、次のように移動すると見つかります。 [**管理コンソール**] > [**統合**] > [**Platformアプリマネージャ**] > [**Platformアプリの設定**] ボタン。 公開Platformアプリとは、統合で見つかるアプリケーションのことです。 ## 必要なアクション 特定のアプリに対して管理者がどのような手順を完了する必要があるかについては、以下のシナリオを確認してください。 [**デフォルトで公開サードパーティ製アプリを無効にする**]: | 認証方法 | 有効 | 無効 | | --- | --- | --- | | OAuth 2.0 | 個々のアプリコントロールで使用可能に設定 | 使用準備完了 | | サーバー認証 (JWT使用) | なし | なし | | サーバー認証 (クライアント資格情報) | なし | なし | | アプリトークン認証 | なし | なし | [**デフォルトで未公開アプリを無効にする**]: | 認証方法 | 有効 | 無効 | | --- | --- | --- | | OAuth 2.0 | [統合] > [Platformアプリマネージャ] > [ユーザー認証アプリ] で、Platformアプリを選択し、[その他] メニューを使用してそのアプリを有効化します。 | 使用準備完了 | | サーバー認証 (JWT使用) | [統合] > [Platformアプリマネージャ] > [サーバー認証アプリ] で、Platformアプリを選択し、[その他] メニューでそのアプリを承認して有効化します。 | [統合] > [Platformアプリマネージャ] > [サーバー認証アプリ] で、Platformアプリを選択し、[その他] メニューを使用してそのアプリを承認します。 | | サーバー認証 (クライアント資格情報) | [統合] > [Platformアプリマネージャ] > [サーバー認証アプリ] で、Platformアプリを選択し、[その他] メニューでそのアプリを承認して有効化します。 | [統合] > [Platformアプリマネージャ] > [サーバー認証アプリ] で、Platformアプリを選択し、[その他] メニューでそのアプリを承認して有効化します。 | | アプリトークン認証 | [統合] > [Platformアプリマネージャ] > [サーバー認証アプリ] > [サーバー認証アプリ] で、Platformアプリを選択し、[その他] メニューでそのアプリを承認して有効化します。 | 使用準備完了 | [**アクセス制限付きアプリの場合に管理者の承認を要求する**]: | 認証方法 | 有効 | 無効 | | --- | --- | --- | | OAuth 2.0 | なし | なし | | サーバー認証 (JWT使用) | なし | なし | | サーバー認証 (クライアント資格情報) | なし | なし | | アプリトークン認証 | [統合] > [Platformアプリマネージャ] > [サーバー認証アプリ] で、Platformアプリを選択し、[その他] メニューを使用してそのアプリを承認します。 | 作成時に自動的に承認して有効化 | **Source:** [https://ja.developer.box.com/guides/authorization/](https://ja.developer.box.com/guides/authorization/) --- ### 文字列メタデータフィールド **Type:** guide | **Category:** メタデータ | **Section:** Developer Guides 文字列メタデータフィールド stringタイプのメタデータフィールドは、標準のテキストフィールドとしてユーザーに表示されます。 文字列フィールドの作成 stringフィールドは、メタデータテンプレートの作成時、またはaddField… # 文字列メタデータフィールド `string`タイプのメタデータフィールドは、標準のテキストフィールドとしてユーザーに表示されます。 ## 文字列フィールドの作成 `string`フィールドは、[メタデータテンプレートの作成](g://metadata/templates/create)時、または`addField`操作による[テンプレートの更新](g://metadata/templates/update)時にメタデータテンプレートに追加できます。 `string`フィールドの必須属性は、`type`、`displayName`、および`key`です。 ``` { "scope": "enterprise", "displayName": "Customer", "fields": [ { "type": "string", "key": "name", "displayName": "Name", "description": "The customer's legal name", "hidden": false } ] } ``` 必要に応じて、UIでユーザーに表示される`description`を指定できます。また、このフィールドを`hidden`に設定して、ウェブアプリとモバイルアプリでユーザーに表示されないようにすることもできます。 ## 文字列フィールドの更新 `string`テンプレートフィールドは、このフィールドが属する[テンプレートを更新](g://metadata/templates/update)することで更新できます。テンプレートの更新は、ファイルまたはフォルダにすでに割り当てられているテンプレートも確実に更新される**操作**によって行われます。 `string`メタデータフィールドを更新する際、関連する操作は、フィールドの`key`、`displayName`、`description`、および`hidden`の値を変更するのに使用できる`editField`操作のみです。 ``` [ { "op": "editField", "fieldKey": "name", "data": { "displayName": "Customer Name", "description": "The contact name at the customer", "key": "customer_name", "hidden": true } } ] ``` これは、このテンプレートの既存のインスタンスに影響します。 **Source:** [https://ja.developer.box.com/guides/metadata/fields/string/](https://ja.developer.box.com/guides/metadata/fields/string/) --- ### 新しいファイルのアップロード **Type:** guide | **Category:** アップロード | **Section:** Developer Guides 新しいファイルのアップロード 直接アップロードによってBoxにファイルをアップロードするには、ファイルのコンテンツ、目的のファイル名、フォルダIDを使用して、POST /files/content APIにAPI… # 新しいファイルのアップロード 直接アップロードによってBoxにファイルをアップロードするには、ファイルのコンテンツ、目的のファイル名、フォルダIDを使用して、[`POST /files/content`](e://post_files_content) APIにAPIコールを実行します。 アーカイブフォルダにファイルをアップロードするには、最初に、開発者コンソールで[グローバルコンテンツマネージャ](g://api-calls/permissions-and-errors/scopes) (GCM) スコープを有効にする必要があります。 # 事前チェック アップロードしたファイルが拒否されることによる時間や帯域幅の無駄を防ぐため、ファイルをアップロードする前に[事前チェック](g://uploads/check)を実行することをお勧めします。 ## リクエスト形式 このAPIのリクエスト本文には、`multipart/form-data`のコンテンツタイプが使用されます。これを使用して、ファイル属性とファイルの実際のコンテンツの2つの部分を送信します。 最初の部分は`attributes`と呼ばれ、ファイル名や親フォルダの`id`など、ファイルに関する情報を含むJSONオブジェクトが含まれています。 以下の例では、ユーザーのルートフォルダに`test.txt`をアップロードしています。 ``` POST /api/2.0/files/content HTTP/1.1 Host: upload.box.com Authorization: Bearer [ACCESS_TOKEN] content-length: 343 content-type: multipart/form-data; boundary=------------------------9fd09388d840fef1 --------------------------9fd09388d840fef1 content-disposition: form-data; name="attributes" {"name":"test.txt", "parent":{"id":"0"}} --------------------------9fd09388d840fef1 content-disposition: form-data; name="file"; filename="test.txt" content-type: text/plain Test file text. --------------------------9fd09388d840fef1-- ``` マルチパート本文の`attributes` JSON部分は、マルチパートフォームデータの`file` 部分の前に置く必要があります。この順番を間違えると、APIがHTTP `400`ステータスコードとエラーコード`metadata_after_file_contents`を返します。 ## オプション ファイルのアップロード時に使用できるすべてのパラメータの詳細については、[このAPIコールに関するリファレンスドキュメント](e://post_files_content)を参照してください。パラメータには、設定することで転送中のファイルの破損を防ぐ`content-md5`や、アップロード時間とは異なる時間をファイル作成時間として明示的に指定できる機能が含まれます。 ## 制約事項 直接アップロードできるファイルサイズの上限は50 MBです。ファイルがこれより大きい場合は、[分割アップロードAPI](g://uploads/chunked)を使用してください。 アップロードの上限は、認証済みユーザーのアカウントの種類によって決まります。詳細については、このトピックに関する[Boxコミュニティの記事](https://support.box.com/hc/ja/articles/360043697314-Box%E3%81%AB%E3%82%A2%E3%83%83%E3%83%97%E3%83%AD%E3%83%BC%E3%83%89%E3%81%A7%E3%81%8D%E3%82%8B%E6%9C%80%E5%A4%A7%E3%83%95%E3%82%A1%E3%82%A4%E3%83%AB%E3%82%B5%E3%82%A4%E3%82%BA)を参照してください。 **Source:** [https://ja.developer.box.com/guides/uploads/direct/file/](https://ja.developer.box.com/guides/uploads/direct/file/) --- ### 既存のタスクの変更 **Type:** guide | **Category:** タスク | **Section:** Developer Guides 既存のタスクの変更 Boxでタスクを更新するには、タスクのIDを指定してPUT /tasks/:task_id APIを呼び出す必要があります。このAPIを使用すると、タスクのactionタイプの変更、message… # 既存のタスクの変更 Boxでタスクを更新するには、タスクのIDを指定して[`PUT /tasks/:task_id`](e://put_tasks_id) APIを呼び出す必要があります。このAPIを使用すると、タスクの`action`タイプの変更、`message`の追加、期日の変更を行うことができます。 ## タスクのアクション Boxは現在、`action`値によって定義される、`review`と`complete`という2種類のタスクをサポートしています。 タスクのタイプによって、タスクがなりうる解決状態と、ウェブアプリおよびモバイルアプリでユーザーに表示されるインターフェースが決まります。 | タスクのアクション | 考えられる解決状態 | | --- | --- | | review | incomplete, approved, rejected | | complete | incomplete, complete | `review`タスクは`incomplete`状態で開始され、`incomplete`、`approved`、または`rejected`としてマークすることができます。ユーザーインターフェースには、テキストボックスのほか、タスクを承認または拒否する1組のボタンが表示されます。 `complete`タスクは`incomplete`状態で開始され、`incomplete`または`completed`としてマークすることができます。このタスクが完了としてマークされると、タスクの状態をそれ以上変更することはできなくなります。ユーザーインターフェースには、テキストボックスのほか、タスクを完了としてマークするためのボタンが表示されます。 ## 完了のルール ファイルに関連するタスクは、そのファイルの複数のコラボレータに割り当てることができます。また、タスクの`completion_rule`を使用すると、タスクを完了する必要があるのはタスクが割り当てられているすべてのユーザー (`all_assignees`) か1人の担当者のみ (`any_assignee`) かを定義できます。 **Source:** [https://ja.developer.box.com/guides/tasks/update/](https://ja.developer.box.com/guides/tasks/update/) --- ### 日付メタデータフィールド **Type:** guide | **Category:** メタデータ | **Section:** Developer Guides 日付メタデータフィールド dateタイプのメタデータフィールドは、日付選択機能としてユーザーに表示されます。 Boxウェブアプリでは日付が日付選択機能として表示されますが、実際の日付は、ミリ秒の形式で保存されています。日付の時間部分は、常にT00:00:00.000Z… # 日付メタデータフィールド `date`タイプのメタデータフィールドは、日付選択機能としてユーザーに表示されます。 Boxウェブアプリでは日付が日付選択機能として表示されますが、実際の日付は、ミリ秒の形式で保存されています。日付の時間部分は、常に`T00:00:00.000Z`に設定されています。 ## 日付フィールドの作成 `date`フィールドは、[メタデータテンプレートの作成](g://metadata/templates/create)時、または`addField`操作による[テンプレートの更新](g://metadata/templates/update)時にメタデータテンプレートに追加できます。 `date`フィールドの必須属性は、`type`、`displayName`、および`key`です。 ``` { "scope": "enterprise", "displayName": "Contract", "fields": [ { "type": "date", "key": "effective_date", "displayName": "Effective Date", "description": "The effective date when the contract goes in effect", "hidden": false } ] } ``` 必要に応じて、UIでユーザーに表示される`description`を指定できます。また、このフィールドを`hidden`に設定して、ウェブアプリとモバイルアプリでユーザーに表示されないようにすることもできます。 ## 日付フィールドの更新 `date`テンプレートフィールドは、このフィールドが属する[テンプレートを更新](g://metadata/templates/update)することで更新できます。テンプレートの更新は、ファイルまたはフォルダにすでに割り当てられているテンプレートも確実に更新される**操作**によって行われます。 `date`メタデータフィールドを更新する際、関連する操作は、フィールドの`key`、`displayName`、`description`、および`hidden`の値を変更するのに使用できる`editField`操作のみです。 ``` [ { "op": "editField", "fieldKey": "effective_date", "data": { "displayName": "Effective Contract Date", "description": "The contract's effective date", "key": "effective_contract_date", "hidden": true } } ] ``` これは、このテンプレートの既存のインスタンスに影響します。 **Source:** [https://ja.developer.box.com/guides/metadata/fields/date/](https://ja.developer.box.com/guides/metadata/fields/date/) --- ### 検索 **Type:** guide | **Category:** 検索 | **Section:** Developer Guides 検索 Box APIを使用すると、ファイルコンテンツ検索クエリを使用してBox内のコンテンツを見つけることができます。Box検索APIは、サポート対象のすべてのSDKとCLIで使用できます。 検索API… # 検索 Box APIを使用すると、ファイルコンテンツ検索クエリを使用してBox内のコンテンツを見つけることができます。Box検索APIは、サポート対象のすべてのSDKとCLIで使用できます。 検索APIで使用できる各種機能の詳細については、[リファレンスドキュメント](e://get_search)を参照してください。 ## クエリ演算子 検索APIは、`AND`、`OR`、`NOT`、`""`など、いくつかの[検索演算子](g://search/query-operators)をサポートします。これらの演算子を使用すると、より複雑な組み合わせの検索語句に一致する項目のみが返されるように検索結果を絞り込むことができます。 ``` curl -i -X GET "https://api.box.com/2.0/search?query=box%20AND%20sales" \ -H "Authorization: Bearer <ACCESS_TOKEN>" ``` 論理演算子の使用の詳細を確認する ## 検索インデックス作成 Boxは、Boxに格納されているファイルまたはフォルダの検索インデックスを保持します。ファイルまたはフォルダが変更されるたびに、これらの単語がインデックスに追加されます。検索が実行されると、APIは、検索インデックスで、クエリに一致するファイルやフォルダを探します。Box内でコンテンツが追加、更新、または削除されると、それに応じて検索インデックスが更新されます。 Boxの検索インデックスの詳細を確認する 10分経過してもインデックスが更新されない場合もあります。このような場合は、[Boxサポート](page://support)に問い合わせて問題を解決することをお勧めします。 ファイルコンテンツ検索が無効になっている企業 (たとえば、[KeySafe](https://www.box.com/security/keysafe)をご利用のお客様) の場合、ドキュメント内の文字を検索できません。ファイルコンテンツ検索が無効の状態でドキュメントを調べる必要がある場合は、アカウントチームまでお問い合わせください。 ## メタデータクエリとの比較 一見、検索クエリAPIは[メタデータクエリAPI](g://metadata/queries)とよく似ていますが、動作には重要な違いがいくつかあります。大まかに言うと、メタデータクエリは正確さとスループットの向上のために最適化されているのに対し、通常の検索は、人間のユーザーとの関連度のために最適化されています。 | | メタデータクエリAPI | 検索API | | --- | --- | --- | | インデックスの作成対象 | このAPIでは、検索対象のメタデータテンプレートの値に基づいてファイル/フォルダのみが返されます。 | このAPIでは、項目名、説明、コンテンツ (最初の10,000バイトまで) の値のほか、関連付けられたメタデータテンプレートインスタンスに基づいてファイル、フォルダ、ウェブリンクが返されます。 | | インデックス作成時間 | このAPIでは、ファイルまたはフォルダのメタデータが追加、削除、更新されるとすぐに正確な結果が返されます。 | このAPIは、検索インデックスの作成が遅延すると、その影響を受けます。この遅延は通常10分ですが、場合によっては長くなることがあります。つまり、メタデータが更新されてから10分を経過しても項目が返されない場合があります。 | | 一致 | このAPIでは、SQLの規則に基づいて完全一致が使用されます。結果は、指定した並べ替え順を基に返されます。 | このAPIでは、あいまい一致が使用されるため、文字列のトークン化、特殊文字の削除、およびその他の検索コンセプトに基づいて異なる結果が返される場合があります。結果の順序は、項目の関連度または更新日に基づいています。 | | 条件付きロジック | このAPIは、比較演算子を使用するマルチパートブール式をサポートします。 | このAPIでは、メタデータによるクエリのサポートが限定的です。サポートされるのは、一度に1つのメタデータテンプレートに対するクエリのみで、単純なクエリ操作のみが可能です。 | | レスポンスタイプ | このAPIでは、一致したファイル/フォルダと、クエリによって一致した関連するメタデータの両方が返されます。 | このAPIで返されるのは、一致した項目のみです。各項目のメタデータを返すには、後続のAPIコールが必要です。 | | スループット (Throughput) | このAPIには現在、ユーザーごとのレート制限のほか、企業あたりのリクエスト数が10件/秒という制限があります。 | このAPIでは、1ユーザーあたりの検索数は6件/秒、企業あたりの検索数は最大60件/分および12件/秒がサポートされています。 | | 規模 | このAPIでは、指定したメタデータテンプレートを使用して返される項目数に制限はありません。一致する結果が2,000件以下になるクエリのみを送信することをお勧めします。 | このAPIには、指定したメタデータテンプレートを使用して返される項目数に制限はありません。ただし、検索に一致する項目数が増えるにつれ、レスポンス時間が大幅に増大します。このAPIでは、1つのクエリに対する結果は1,000万件までという制限があります。一致する結果が50,000件以下になるクエリのみを送信することをお勧めします。 | | スコープ | このAPIは常に、ユーザーがアクセスできるコンテンツに制限されています。 | このAPIは、ユーザーがアクセスできるコンテンツ (​user_content​) または社内のすべてのコンテンツ (​enterprise_content​) のいずれかに制限される場合があります。 | メタデータクエリAPIの詳細を確認する **Source:** [https://ja.developer.box.com/guides/search/](https://ja.developer.box.com/guides/search/) --- ### 検索インデックス作成 **Type:** guide | **Category:** 検索 | **Section:** Developer Guides 検索インデックス作成 Boxは、Boxに格納されているファイルまたはフォルダの検索インデックスを保持します。ファイルまたはフォルダが変更されるたびに、これらの単語がインデックスに追加されます。検索が実行されると、API… # 検索インデックス作成 Boxは、Boxに格納されているファイルまたはフォルダの検索インデックスを保持します。ファイルまたはフォルダが変更されるたびに、これらの単語がインデックスに追加されます。検索が実行されると、APIは、検索インデックスで、クエリに一致するファイルやフォルダを探します。Box内でコンテンツが追加、更新、または削除されると、それに応じて検索インデックスが更新されます。 ## 検索可能になるまでの時間 ファイルのアップロードまたは変更後、そのファイルにインデックスが完全に作成され、検索できるようになるまで時間がかかる場合があります。ほとんどの場合、新しく追加または変更されたファイルは、10分以内にBoxの検索で検索可能になります。ただし、場合によっては、インデックス作成時間はその時点のサービスの負荷によって決まるため、10分を超えることもあります。 10分経過してもインデックスが更新されない場合もあります。このような場合は、[Boxサポート](page://support)に問い合わせて問題を解決することをお勧めします。 ## 検索アクセス 検索結果では、認証済みユーザーがアクセスできるコンテンツ (プレビュー/表示できる項目) のみが返されます。 つまり、検索結果に表示されるためには、ユーザーが所有する項目かコラボレーションしている項目である必要があります。ユーザーが項目にアクセスできない場合や共有リンクを介して項目が共有されている場合は、その項目も検索結果に表示されません。 ただし、例外として、共有リンクを介して最近アクセスされた項目は、`include_recent_shared_links`クエリパラメータを`true`に設定することで、検索結果に含めるようリクエストすることができます。 ## プレフィックス検索とワイルドカード検索 末尾のワイルドカード (プレフィックス検索とも呼ばれます) が検索結果に暗黙的に適用されているのは、テキストのインデックス作成方法が原因です。`Bo`を検索すると、タイトルに`Box`、`Boat`、または`Boxer`が含まれる項目が返されます。これは従来の検索エンジンで`Bo*`または`Bo%`を検索した結果と同じになります。Boxでは、`%ox%`のような従来のワイルドカードの表記法がサポートされていません。Boxは、タイトルのプレフィックス検索に対応していますが、本文コンテンツのプレフィックス検索、タイトルまたは本文コンテンツのサフィックス検索、タイトルまたは本文コンテンツのインフィックス (部分) 検索には対応していません。たとえば、`cal`を検索すると、`California`という**ファイル名**が一致しますが、`decal`または`recall`は一致しません。この場合、`California`、`recall`、`decal`を含め、**ファイル本文のコンテンツ**でのプレフィックス、インフィックス、またはサフィックスとは一致しません。 ## ステミング Boxの検索では、ステミングを使用して、クエリの単語をインデックスの単語と照合します。このため、同じ語幹を含む単語は、クエリ内と完全に同じ形式でなくても、結果セットに含まれる場合があります。たとえば、`run`と`running`は同じ語幹に対応するため、`running`で検索すると、タイトルに`run`を含むドキュメントが返されます。 ## ファイルコンテンツの検索 ファイル内のコンテンツも、Box検索インデックス内に格納されます。以下のファイルタイプでは、コンテンツの検索が可能です。 | | | | | | | --- | --- | --- | --- | --- | | boxnote | csv | doc | docx | gdoc | | gsheet | gslide | gslides | htm | html | | msg | odp | odt | ods | pdf | | ppt | pptx | rtf | tsv | wpd | | xhtml | xls | xlsm | xlsx | xml | | xsd | xsl | as | as3 | asm | | bat | c | cc | cmake | cpp | | cs | css | cxx | diff | erb | | groovy | h | haml | hh | java | | js | json | less | log | m | | make | md | ml | mm | php | | pl | plist | properties | py | rb | | rst | sass | scala | script | scm | | sml | sql | sh | txt | vi | | vim | webdoc | yaml | | | ## ドキュメントあたりのインデックスが作成されるテキスト Boxの検索インデックスには、Businessレベル以上のアカウントの場合、ドキュメントあたり最大10,000バイト (英語で約10,000文字) が格納されます。この量は、言語、Boxのインデックスの作成方法、およびドキュメントの種類によって、ドキュメントごとに異なる場合があります。 ファイルコンテンツ検索が無効になっている企業 (たとえば、[KeySafe](https://www.box.com/ja-jp/security/keysafe)をご利用のお客様) の場合、ドキュメント内の文字を検索できません。ファイルコンテンツ検索が無効の状態でドキュメントを調べる必要がある場合は、アカウントチームまでお問い合わせください。 ## OCRのサポート 現在、Boxではドキュメントに対してOCR処理を実行しません。 ## ドキュメントのバージョン 検索では、最新バージョンのドキュメントのコンテンツに対してのみインデックスを作成するため、古いドキュメントからの関連性のない多数の検索結果を選別する必要はありません。最新バージョン以外のドキュメントを照会する場合は、検索を使用できません。 ## 言語のサポート Boxの検索では、中国語、英語、フランス語、ドイツ語、イタリア語、日本語、およびスペイン語がサポートされています。Boxでは、1つのドキュメント内での複数言語のインデックス作成はサポートされていません。 ## ごみ箱 ごみ箱の検索は、このAPIで`trash_content`クエリパラメータを使用して実行できます。 Boxコミュニティの記事で、Boxでの検索に関する最新情報を確認する **Source:** [https://ja.developer.box.com/guides/search/indexing/](https://ja.developer.box.com/guides/search/indexing/) --- ### 検索結果に対するフィルタ **Type:** guide | **Category:** 検索 | **Section:** Developer Guides 検索結果に対するフィルタ GET /search APIでは、API… # 検索結果に対するフィルタ [`GET /search`](e://get_search) APIでは、APIによって返された結果にフィルタをかけるためのさまざまな方法がサポートされています。 ## コンテンツタイプによるフィルタ デフォルトでは、名前、説明、ファイルコンテンツ、タグ、またはコメントが指定されたクエリと一致する項目が返されます。`content_types`パラメータを設定すると、定義したコンテンツタイプのクエリに一致する項目のみに検索を絞り込むことができます。 ``` curl -i -X GET "https://api.box.com/2.0/search?query=sales&content_types=name,tags" \ -H "Authorization: Bearer <ACCESS_TOKEN>" ``` ``` long offsetValue = 0; long limitValue = 10; BoxSearch boxSearch = new BoxSearch(api); BoxSearchParameters searchParams = new BoxSearchParameters(); searchParams.setQuery("sales"); final List<String> contentTypes = new ArrayList<String>(); contentTypes.add("name"); contentTypes.add("tags"); searchParams.setContentTypes(contentTypes) PartialCollection<BoxItem.Info> searchResults = boxSearch.searchRange(offsetValue, limitValue, searchParams); ``` ``` var contentTypes = new List<string>(); contentTypes.Add("name"); contentTypes.Add("tags"); BoxCollection<BoxItem> results = await client.SearchManager .QueryAsync("sales", contentTypes: contentTypes); ``` ``` client.search().query("sales", content_types=["name", "tags"]) ``` ``` client.search.query( 'sales', { content_types: [ "name", "tags" ] }) .then(results => { // ... }); ``` | コンテンツタイプ | | | --- | --- | | name | nameフィールドで定義されている、項目の名前。 | | description | descriptionフィールドで定義されている、項目の説明。 | | file_content | ファイルの実際のコンテンツ。 | | comments | ファイルまたはフォルダに対するコメントのコンテンツ。 | | tags | tagsフィールドで定義されている、項目に適用されるタグ。 | ## 日付によるフィルタ デフォルトでは、指定した日付に作成されたファイルと指定した日付に更新されたファイルが返されます。ファイルまたはフォルダが最後に更新された日付でも、ファイルまたはフォルダが作成された日付でも結果にフィルタをかけることができます。 ``` curl -i -X GET "https://api.box.com/2.0/search?query=sales&created_at_range=2014-05-15T13:35:01Z,2015-05-15T13:35:01&updated_at_range=2014-05-15T13:35:01," \ -H "Authorization: Bearer <ACCESS_TOKEN>" ``` ``` long offsetValue = 0; long limitValue = 10; BoxSearch boxSearch = new BoxSearch(api); BoxSearchParameters searchParams = new BoxSearchParameters(); searchParams.setQuery("sales"); String createdFromDateString = "2014-05-15T13:35:01Z"; String createdToDateString = "2015-05-15T13:35:01Z"; Date createdFromDate = sdf.parse(createdFromDateString); Date createdToDate = sdf.parse(createdToDateString); DateRange createdRange = new DateRange(createdFromDate, createdToDate); searchParams.setCreatedRange(createdRange) String updatedFromDateString = "2014-05-15T13:35:01Z"; Date updatedFromDate = sdf.parse(updatedFromDateString); DateRange updatedRange = new DateRange(updatedFromDate, null); searchParams.setUpdatedRange(updatedRange) PartialCollection<BoxItem.Info> searchResults = boxSearch.searchRange(offsetValue, limitValue, searchParams); ``` ``` var createdAtRangeFromDate = new DateTime(1988, 11, 18, 9, 30, 0, DateTimeKind.Utc); var createdAtRangeToDate = new DateTime(2018, 11, 18, 9, 30, 0, DateTimeKind.Utc); var updatedAtRangeFromDate = new DateTime(1988, 11, 18, 9, 30, 0, DateTimeKind.Utc); BoxCollection<BoxItem> results = await client.SearchManager .QueryAsync("sales", contentTypes: contentTypes, createdAtRangeFromDate: createdAtRangeFromDate, createdAtRangeToDate: createdAtRangeToDate, updatedAtRangeFromDate: updatedAtRangeFromDate); ``` ``` client.search().query("sales", created_at_range=["2014-05-15T13:35:01Z", "2015-05-15T13:35:01Z"], updated_at_range=["2014-05-15T13:35:01Z", null]) ``` ``` client.search.query( 'sales', { created_at_range: "2014-05-15T13:35:01Z,2015-05-15T13:35:01Z", updated_at_range: "2014-05-15T13:35:01Z," }) .then(results => { // ... }); ``` | クエリパラメータ | | | --- | --- | | created_at_range | 結果を返すcreated_atの日付の範囲を定義します。上限または下限を空にすると、範囲を期限なしにすることができます。 | | updated_at_range | 結果を返すupdated_atの日付の範囲を定義します。上限または下限を空にすると、範囲を期限なしにすることができます。 | ## ファイル拡張子によるフィルタ デフォルトでは、さまざまな種類のファイル拡張子の項目が返されます。`file_extensions`クエリパラメータを使用すると、指定した1つ以上のファイル拡張子のファイルのみが返されるよう、検索結果にフィルタをかけることができます。 ``` curl -i -X GET "https://api.box.com/2.0/search?query=sales&file_extensions=pdf,txt" \ -H "Authorization: Bearer <ACCESS_TOKEN>" ``` ``` long offsetValue = 0; long limitValue = 10; BoxSearch boxSearch = new BoxSearch(api); BoxSearchParameters searchParams = new BoxSearchParameters(); searchParams.setQuery("sales"); final List<String> fileExtensions = new ArrayList<String>(); fileExtensions.add("pdf"); fileExtensions.add("txt"); searchParams.setFileExtensions(fileExtensions) PartialCollection<BoxItem.Info> searchResults = boxSearch.searchRange(offsetValue, limitValue, searchParams); ``` ``` var fileExtensions = new List<string>(); fileExtensions.Add("pdf"); fileExtensions.Add("txt"); BoxCollection<BoxItem> results = await client.SearchManager .QueryAsync("sales", fileExtensions: fileExtensions); ``` ``` client.search().query("sales", file_extensions=["pdf", "txt"]) ``` ``` client.search.query( 'sales', { file_extensions: [ "pdf", "txt" ] }) .then(results => { // ... }); ``` ## ファイルサイズによるフィルタ デフォルトでは、さまざまなファイルサイズの項目が返されます。`size_range`クエリパラメータを使用すると、指定したファイルサイズを超えないファイルのみが返されるよう、検索結果にフィルタをかけることができます。 ``` curl -i -X GET "https://api.box.com/2.0/search?query=sales&size_range=10000,20000" \ -H "Authorization: Bearer <ACCESS_TOKEN>" ``` ``` long offsetValue = 0; long limitValue = 10; BoxSearch boxSearch = new BoxSearch(api); BoxSearchParameters searchParams = new BoxSearchParameters(); searchParams.setQuery("sales"); SizeRange sizeRange = new SizeRange(10000, 20000); searchParams.setSizeRange(sizeRange); PartialCollection<BoxItem.Info> searchResults = boxSearch.searchRange(offsetValue, limitValue, searchParams); ``` ``` BoxCollection<BoxItem> results = await client.SearchManager .QueryAsync("sales", sizeRangeLowerBoundBytes: 10000, sizeRangeUpperBoundBytes: 20000); ``` ``` client.search().query("sales", size_range=[10000,20000]) ``` ``` client.search.query( 'sales', { size_range: '10000,20000' }) .then(results => { // ... }); ``` ## ファイルタイプによるフィルタ デフォルトでは、ファイル、フォルダ、およびウェブリンクがすべて返されます。結果をそのうちの1つだけに絞り込むには、`type`クエリパラメータを`file`、`folder`、`web_link`のいずれかに設定します。 ``` curl -i -X GET "https://api.box.com/2.0/search?query=sales&type=file" \ -H "Authorization: Bearer <ACCESS_TOKEN>" ``` ``` long offsetValue = 0; long limitValue = 10; BoxSearch boxSearch = new BoxSearch(api); BoxSearchParameters searchParams = new BoxSearchParameters(); searchParams.setQuery("sales"); searchParams.setType("file"); PartialCollection<BoxItem.Info> searchResults = boxSearch.searchRange(offsetValue, limitValue, searchParams); ``` ``` BoxCollection<BoxItem> results = await client.SearchManager .QueryAsync("sales", type: "file"); ``` ``` client.search().query("sales", type="file") ``` ``` client.search.query( 'sales', { type: "file" }) .then(results => { // ... }); ``` ## メタデータによるフィルタ 関連付けられたメタデータを使用して検索結果にフィルタをかけることも、メタデータのみに基づいてすべての検索を実行することもできます。どちらの場合も`mdfilters`クエリパラメータを使用します。 メタデータフィルタの詳細を確認する ## 所有者によるフィルタ デフォルトでは、項目の所有者に関係なく、認証済みユーザーがアクセスできるすべての項目が返されます。特定のユーザーが所有する項目のみに絞り込むには、`owner_user_ids`クエリパラメータを使用します。 ``` curl -i -X GET "https://api.box.com/2.0/search?query=sales&owner_user_ids=34446362,462281242" \ -H "Authorization: Bearer <ACCESS_TOKEN>" ``` ``` long offsetValue = 0; long limitValue = 10; BoxSearch boxSearch = new BoxSearch(api); BoxSearchParameters searchParams = new BoxSearchParameters(); searchParams.setQuery("sales"); final List<String> userIds = new ArrayList<String>(); userIds.add("34446362"); userIds.add("462281242"); searchParams.setOwnerUserIds(userIds) PartialCollection<BoxItem.Info> searchResults = boxSearch.searchRange(offsetValue, limitValue, searchParams); ``` ``` var userIds = new List<string>(); userIds.Add("34446362"); userIds.Add("462281242"); BoxCollection<BoxItem> results = await client.SearchManager .QueryAsync("sales", ownerUserIds: userIds); ``` ``` client.search().query("sales", owner_user_ids=["34446362", "462281242"]) ``` ``` client.search.query( 'sales', { owner_user_ids: "34446362,462281242" }) .then(results => { // ... }); ``` ## 親フォルダによるフィルタ デフォルトでは、ユーザーがアクセスできる任意のフォルダ内のすべての項目が返されます。特定のフォルダ内の項目のみに結果を絞り込むには、`ancestor_folder_ids`クエリパラメータを使用します。 ``` curl -i -X GET "https://api.box.com/2.0/search?query=sales&ancestor_folder_ids=45235463,73445321" \ -H "Authorization: Bearer <ACCESS_TOKEN>" ``` ``` long offsetValue = 0; long limitValue = 10; BoxSearch boxSearch = new BoxSearch(api); BoxSearchParameters searchParams = new BoxSearchParameters(); searchParams.setQuery("sales"); final List<String> folderIds = new ArrayList<String>(); folderIds.add("45235463"); folderIds.add("73445321"); searchParams.setAncestorFolderIds(folderIds) PartialCollection<BoxItem.Info> searchResults = boxSearch.searchRange(offsetValue, limitValue, searchParams); ``` ``` var folderIds = new List<string>(); folderIds.Add("45235463"); folderIds.Add("73445321"); BoxCollection<BoxItem> results = await client.SearchManager .QueryAsync("sales", ancestorFolderIds: folderIds); ``` ``` client.search().query("sales", ancestor_folder_ids=["45235463", "73445321"]) ``` ``` client.search.query( 'sales', { ancestor_folder_ids: "45235463,73445321" }) .then(results => { // ... }); ``` **Source:** [https://ja.developer.box.com/guides/search/filtering/](https://ja.developer.box.com/guides/search/filtering/) --- ### 権限 **Type:** guide | **Category:** セキュリティ | **Section:** Developer Guides … # 権限 以下は、ユーザー、管理者、および共同管理者がサービス利用規約およびサービス利用規約のステータスを操作する際に必要な権限のリストです。 ## サービス利用規約 エンドユーザーは、以下の場合にサービス利用規約の対象であると見なされます。 - サービス利用規約が有効になっている企業に属している、またはその企業とコラボレーションしている サービス利用規約の種類がユーザーと企業との関係を示している - 同じ企業に属するユーザー向けの管理対象ユーザー用サービス利用規約 - 企業とコラボレーションしているユーザー向けの外部ユーザー用サービス利用規約 エンドユーザーは以下の場合にサービス利用規約の設定を表示できます。 - そのユーザーがサービス利用規約の対象となっている、かつ - 企業でそのサービス利用規約が有効になっている 企業の管理者または共同管理者は、以下の場合にサービス利用規約の設定を表示できます。 - **[会社の設定を表示する]** 権限を持っている - アプリケーションの **[Enterpriseのプロパティを管理する]** スコープが有効になっている - そのサービス利用規約が自分の企業に属している 企業の管理者または共同管理者は、以下の場合にサービス利用規約の設定を編集できます。 - **[会社の設定を編集する]** 権限を持っている - アプリケーションの **[Enterpriseのプロパティを管理する]** スコープが有効になっている - そのサービス利用規約が自分の企業に属している 企業の管理者および共同管理者は、自社の管理対象ユーザー用サービス利用規約を承認していなくても、管理対象ユーザー用と外部ユーザー用の両方のサービス利用規約の設定を表示、作成、編集できます。 ## サービス利用規約のユーザーステータス エンドユーザーは以下の場合にサービス利用規約のユーザーステータスを表示および編集できます。 - ユーザーステータスがそのエンドユーザーに属している - 企業でそのサービス利用規約が有効になっている - そのエンドユーザーがサービス利用規約の対象である 企業の管理者および共同管理者は、以下の場合に他のユーザーに属するサービス利用規約のユーザーステータスを表示できます。 - **[ユーザーを管理する]** 権限を持っている - アプリケーションの **[ユーザーを管理する]** スコープが有効になっている - そのサービス利用規約が自分の企業に属している - 自社の管理対象ユーザー用サービス利用規約を承認済みである (該当する場合) 企業の管理者および共同管理者は、以下の場合に他のユーザーに属するサービス利用規約のユーザーステータスを編集できます。 - **[ユーザーを管理する]** 権限を持っている - アプリケーションの **[ユーザーを管理する]** スコープが有効になっている - そのエンドユーザーがサービス利用規約の対象である - そのエンドユーザーが管理者または共同管理者ではない - そのサービス利用規約が自分の企業に属している - 自社の管理対象ユーザー用サービス利用規約を承認済みである (該当する場合) エンドユーザーは、自社の管理対象ユーザー用サービス利用規約を承認するまで、コラボレーションしている企業の外部ユーザー用サービス利用規約の設定を承認、拒否、表示できません (該当する場合)。そのような操作を行おうとすると、`TERMS_OF_SERVICE_REQUIRED`エラーが発生します。 **Source:** [https://ja.developer.box.com/guides/security/terms-of-service/permissions/](https://ja.developer.box.com/guides/security/terms-of-service/permissions/) --- ### 権限とエラー **Type:** guide | **Category:** APIコール | **Section:** Developer Guides 権限とエラー 以下のガイドでは、Box APIに関連した権限やエラーについて説明します。一般的なエラー、レート制限、スコープ、トークンおよびURLの有効期限、App Diagnosticsレポートに関するページが用意されています。 # 権限とエラー 以下のガイドでは、Box APIに関連した権限やエラーについて説明します。[一般的なエラー](g://api-calls/permissions-and-errors/common-errors)、[レート制限](g://api-calls/permissions-and-errors/rate-limits)、[スコープ](g://api-calls/permissions-and-errors/scopes)、[トークンおよびURLの有効期限](g://api-calls/permissions-and-errors/expiration)、[App Diagnosticsレポート](g://api-calls/permissions-and-errors/app-diagnostics-report)に関するページが用意されています。 **Source:** [https://ja.developer.box.com/guides/api-calls/permissions-and-errors/](https://ja.developer.box.com/guides/api-calls/permissions-and-errors/) --- ### 次の手順 **Type:** quick-start | **Category:** CLI | **Section:** Developer Guides 次の手順 このクイックスタートガイドが完了しました。ここまで、以下の手順を実行しました。 OAuth 2.0アプリケーションを作成および構成しました。 CLIをインストールおよび構成しました。 CLI… # 次の手順 このクイックスタートガイドが完了しました。ここまで、以下の手順を実行しました。 1. OAuth 2.0アプリケーションを[作成および構成](g://cli/quick-start/create-oauth-app)しました。 2. CLIを[インストールおよび構成](g://cli/quick-start/install-and-configure)しました。 3. [CLIコマンドを作成および実行](g://cli/quick-start/build-commands-help)しました。 4. [オプションや一括コマンド](g://cli/quick-start/options-and-bulk-commands)について学習しました。 5. CLIを使用して[PowerShellスクリプトを実行する](g://cli/quick-start/powershell-script-templates)方法を確認しました。 次の手順を行うには、以下のリソースをお勧めします。 1. すべての[コマンド](https://github.com/box/boxcli#command-topics)を確認する。 2. [トークンのキャッシュ](https://github.com/box/boxcli/blob/master/docs/configure.md#box-configureenvironmentsupdate-name)の設定を確認する。 3. [オートコンプリート](https://github.com/box/boxcli/blob/master/docs/autocomplete.md)の設定を確認する。 4. すべての[CLIサンプルスクリプト](g://cli/scripts)を確認する。 **Source:** [https://ja.developer.box.com/guides/cli/quick-start/next-steps/](https://ja.developer.box.com/guides/cli/quick-start/next-steps/) --- ### 次の手順 **Type:** quick-start | **Category:** メタデータ | **Section:** Developer Guides … # 次の手順 このクイックスタートガイドが完了しました。ここまで、以下の手順を実行しました。 1. 使用できる[すべてのテンプレートのリストを取得](g://metadata/quick-start/list-all)しました。 2. 会社固有のデータを保持する[カスタムメタデータテンプレートを作成](g://metadata/quick-start/create-template)しました。 3. ファイルに[カスタムメタデータテンプレートを適用](g://metadata/quick-start/create-instance)し、カスタムデータをファイルに割り当てられるようにしました。 4. ファイルの[メタデータインスタンスを更新](g://metadata/quick-start/update-instance)し、ファイルに割り当てられたデータを変更できるようにしました。 5. [メタデータテンプレートを更新](g://metadata/quick-start/update-template)し、このテンプレートのすべてのインスタンスに適用されたデータを変更しました。 6. [ファイルやフォルダに対してクエリを実行](g://metadata/quick-start/create-query)し、ファイルとフォルダに適用されているメタデータインスタンスの値と照合しました。 ## 次の手順 Box APIでのメタデータの使用の詳細を確認するには、以下のリソースをお勧めします。 - [メタデータのスコープの詳細を確認する](g://metadata/scopes) - テンプレートで使用できる[各種フィールドタイプの詳細](g://metadata/fields) **Source:** [https://ja.developer.box.com/guides/metadata/quick-start/next-steps/](https://ja.developer.box.com/guides/metadata/quick-start/next-steps/) --- ### 次の手順 **Type:** quick-start | **Category:** 検索 | **Section:** Developer Guides 次の手順 このクイックスタートガイドが完了しました。ここまで、以下の手順を実行しました。 メタデータテンプレートを作成しました APIを使用して手順1のメタデータテンプレートに関する情報を確認しました… # 次の手順 このクイックスタートガイドが完了しました。ここまで、以下の手順を実行しました。 1. [メタデータテンプレートを作成](g://search/quick-start/create-metadata-template)しました 2. APIを使用して手順1の[メタデータテンプレートに関する情報を確認](g://search/quick-start/locate-template-info)しました 3. 1つ以上のファイルに[メタデータテンプレートを追加](g://search/quick-start/apply-template-to-file)しました 4. [メタデータクエリAPIを使用](g://search/quick-start/metadata-query-api)して手順3のファイルを特定しました ## 次の手順 詳細を確認するには、以下のリソースをお勧めします。 - [メタデータクエリのガイド](g://metadata/queries) - [一般的なエラー](g://metadata/queries/errors)と[制限](g://metadata/queries/limitations)の確認 - [メタデータクエリ](e://post-metadata-queries-execute-read)APIのリファレンスドキュメント メタデータクエリAPIをサポートするBox SDKは以下のとおりです。 - [Python SDK](https://github.com/box/box-python-sdk/blob/main/docs/usage/search.md#metadata-query) - [.NET SDK](https://github.com/box/box-node-sdk/blob/3fcc0d8bbd1ca11f1a3a78d741e4572718af53f0/docs/metadata.md#query) - [iOS SDK](https://github.com/box/box-ios-sdk/blob/c5ff8396e28c31fcf3c433f1b9e8f2f0d7a0e0db/docs/usage/search.md#metadata-search) - [Java SDK](https://github.com/box/box-java-sdk/blob/5e3a96c903fffa198c97e981ce75765a69bd6cb6/doc/metadata_template.md#execute-metadata-query) - [Node](https://github.com/box/box-node-sdk/blob/3fcc0d8bbd1ca11f1a3a78d741e4572718af53f0/docs/metadata.md#query) **Source:** [https://ja.developer.box.com/guides/search/quick-start/next-steps/](https://ja.developer.box.com/guides/search/quick-start/next-steps/) --- ### 次の手順 **Type:** quick-start | **Category:** モバイル | **Section:** Developer Guides 次の手順 このクイックスタートガイドが完了しました。ここまで、以下の手順を実行しました。 Xcodeで新しいiOSアプリを作成しました。 プロジェクトにiOS SDKをインストールしました。 iOS SDKからBox APIにアクセスできるようにBox… # 次の手順 このクイックスタートガイドが完了しました。ここまで、以下の手順を実行しました。 1. Xcodeで[新しいiOSアプリを作成](g://mobile/ios/quick-start/create-ios-app)しました。 2. プロジェクトに[iOS SDKをインストール](g://mobile/ios/quick-start/install-ios-sdk)しました。 3. iOS SDKからBox APIにアクセスできるように[Boxアプリを設定](g://mobile/ios/quick-start/configure-box-app)しました。 4. iOS SDKを使用してBox APIに対する[APIコールを実行](g://mobile/ios/quick-start/make-api-call)しました。 ## 次に行うべきこと アプリケーションで次の手順を行うには、次のリソースをお勧めします。 - [トークンのダウンスコープ](g://authentication/tokens/downscope): このクイックスタートガイドでは、開発者トークンを使用して最初の呼び出しを実行しました。スケーラブルなソリューションを実装するには、その実装に代わるダウンスコープされたトークンを生成するサーバー側ソリューションが必要です。 - [公式のJWTサンプルアプリケーション](https://github.com/box/box-ios-sdk/tree/master/SampleApps/JWTSampleApp): iOS SDKにバンドルされているこのサンプルアプリケーションにより、適切に構造化されたBox JWTアプリケーションをすぐに利用開始できます。ユーザーのログインは必要ありません。 - [公式のOAuth 2サンプルアプリケーション](https://github.com/box/box-ios-sdk/tree/master/SampleApps/OAuth2SampleApp): iOS SDKにバンドルされているこのサンプルアプリケーションにより、適切に構造化されたBox OAuth 2アプリケーションをすぐに利用開始できます。ユーザーのログインは不要です。 **Source:** [https://ja.developer.box.com/guides/mobile/ios/quick-start/next-steps/](https://ja.developer.box.com/guides/mobile/ios/quick-start/next-steps/) --- ### 次の手順 **Type:** quick-start | **Category:** ツール | **Section:** Developer Guides 次の手順 このクイックスタートガイドが完了しました。ここまで、以下の手順を実行しました。 デバイスにPostmanをインストールしました。 BoxへのアクセスについてPostmanアプリを認証できるようにBoxアプリを設定しました。 Boxアプリにログインして適切なAPI… # 次の手順 このクイックスタートガイドが完了しました。ここまで、以下の手順を実行しました。 1. デバイスに[Postmanをインストール](g://tooling/postman/quick-start/install-postman)しました。 2. BoxへのアクセスについてPostmanアプリを認証できるように[Boxアプリを設定](g://tooling/postman/quick-start/configure-box-app)しました。 3. Boxアプリに[ログイン](g://tooling/postman/quick-start/log-in-to-box)して適切なAPI資格情報を取得しました。 4. Postmanに、APIコールに必要なすべての資格情報とともに[BoxのPostmanコレクションを読み込み](g://tooling/postman/quick-start/load-postman-collection)ました。 5. Postmanを使用して、Box APIへの[最初のAPIコールを実行](g://tooling/postman/quick-start/make-api-call)しました。 ## 次に行うべきこと Box APIとPostmanの使用についてさらに詳しく知りたい方には、以下のリソースをお勧めします。 - Postmanチームが提供する[公式のPostman入門ガイド](https://learning.getpostman.com/getting-started/)。 - Postman内で[アクセストークンを更新する方法](g://tooling/postman/refresh)。 **Source:** [https://ja.developer.box.com/guides/tooling/postman/quick-start/next-steps/](https://ja.developer.box.com/guides/tooling/postman/quick-start/next-steps/) --- ### 注釈 **Type:** guide | **Category:** Boxの埋め込み | **Section:** Developer Guides 注釈 Boxの注釈を使用すると、開発者はアプリケーションに埋め込まれたBoxプレビュー内から直接コラボレーション機能を提供できます。Box… # 注釈 Boxの注釈を使用すると、開発者はアプリケーションに埋め込まれたBoxプレビュー内から直接コラボレーション機能を提供できます。Boxの注釈は幅広いユースケースに対応するため、使用するとプレビューアーの注意を引いたり、ドキュメントや画像の特定の部分に関するフィードバックを提供したりできます。 コンテンツプレビューの詳細を確認する 現在、Box Content Previewは、コメントのハイライト、ハイライトのみ、描画、ポイント注釈という4種類の注釈をサポートしています。Boxの注釈は、現在、ドキュメントと画像のプレビューでのみサポートされています。Box Content Previewでサポートされるファイルタイプの詳細なリストについては、[こちら](https://support.box.com/hc/ja/articles/360043695794-Box-Content-Preview%E3%81%A7%E3%82%B5%E3%83%9D%E3%83%BC%E3%83%88%E3%81%95%E3%82%8C%E3%82%8B%E3%83%95%E3%82%A1%E3%82%A4%E3%83%AB)で確認できます。 ## ブラウザのサポート Box UI Elementの[ブラウザのサポートの詳細](g://embed/ui-elements/browser)を確認してください。 ## 使用方法 Boxの注釈は、[NPMパッケージ](https://www.npmjs.com/package/box-annotations)から取り込むと使用できます。 ## 初期化 ``` /* global BoxAnnotations */ const boxAnnotations = new BoxAnnotations(); const annotatorConf = boxAnnotations.determineAnnotator( options, disabledAnnotationTypes ); // Construct and init annotator const annotator = new annotatorConf.CONSTRUCTOR(options); annotator.init(scale); ``` ここで、`disabledAnnotationTypes`は、無効にする有効な注釈の種類の文字列です。ビューアー固有の注釈の構成の詳細については、以下を参照してください。 ## 認証 UI Elementは認証に依存しない方法で設計されているため、Boxアカウントを持つユーザー (管理対象ユーザー) とBox以外のアカウントを持つユーザー (App User) のどちらにUI Elementを使用するかどうかに関係なく、UI Elementを使用するのに特別な設定は必要ありません。その理由は、UI Elementは認証のために「トークン」を受け取ることのみを予期しており、Boxにはトークンの生成方法としてOAuthとJWTの2つがあるからです。 認証方法の選択について確認する アプリケーションでエンドユーザーが注釈機能のサブセットだけにアクセスできるようにする必要がある場合は、[ダウンスコープ](g://authentication/tokens/downscope)を使用して、アクセストークンを適切にダウンスコープして必要な権限のセットを含むトークンを生成し、注釈を初期化するエンドユーザークライアントに安全に渡すことができます。 以下は、ダウンスコープと一緒に使用する、注釈固有の新しいスコープのセットです。こうしたスコープにより、開発者は、ダウンスコープされたトークンに適切なスコープを構成して、Boxの注釈に対する機能を有効/無効にすることができます。詳細については、[Box UI Elementsの専用スコープ](g://embed/ui-elements/scopes)を参照してください。 ## パラメータとオプション ``` const annotator = new annotatorConf.CONSTRUCTOR({ annotator, apiHost, token, container, file: { id, file_version: { id }, permissions }, isMobile, hasTouch, locale, modeButtons: { // Annotation mode buttons, i.e. point, draw, etc point: { // Accessibilty message for the point annotation mode button title: "Point annotation mode", // CSS selector for the point annotation mode button selector: ".bp-btn-annotate-point" } } }); ``` | パラメータ | デフォルト | 説明 | | --- | --- | --- | | annotator | | ビューアー固有の注釈構成オブジェクト | | apiHost | | Box APIコールのホスト (https://app.box.com/apiなど) | | fileId | | BoxファイルID | | token | | 文字列認証トークン。適切なスコープを使用した注釈トークンの生成方法の詳細については、以下を参照してください。 | | container | | プレビューが配置されるDOMノードまたはセレクタ | | file | | ファイルメタデータオブジェクト | | file.id | | 文字列Box_File ID | | file.file_version.id | | 文字列Box_File_Version ID | | file.permissions | | ファイル権限オブジェクト。権限のスコープを設定する方法については、以下を参照してください。 | | オプション | デフォルト | 説明 | | --- | --- | --- | | modeButtons | | 注釈モードボタンのCSSセレクタとアクセシビリティメッセージを含むオブジェクト。上記のパラメータとオプションを参照してください。 | | isMobile | false | ユーザーのブラウザがモバイルデバイスにあるかどうか | | hasTouch | false | モバイルブラウザがタッチ対応かどうか | | locale | en-US | 共有リンクのURL | ### 基本スコープ | スコープ名 | 付与される権限 | | --- | --- | | base_preview | ユーザー/ファイル/トークンの権限に基づいて、フォルダ内のファイルに対するプレビュー権限を許可します。 | ### 機能のスコープ | スコープ名 | 付与される権限 | | --- | --- | | item_download | ファイル/フォルダのコンテンツのダウンロードを許可します。 | | annotation_view_self | ユーザーに自分の注釈の表示を許可します。 | | annotation_view_all | ユーザーにファイルに付いているすべての注釈の表示を許可します。 | | annotation_edit | ユーザーに自分の注釈の編集を許可します (annotation_view_selfを含む)。 | ### サンプルのシナリオ | シナリオ | スコープの組み合わせ | | --- | --- | | ユーザーが基本的なプレビュー機能と自分の注釈の編集機能を必要とする | base_preview + annotation_edit | | ユーザーが基本的なプレビュー機能、自分の注釈の編集機能、およびドキュメントのテキストの選択機能を必要とする | base_preview + annotation_edit + item_download | | ユーザーが基本的なプレビュー機能、すべての注釈の表示機能、および自分の注釈の編集機能を必要とする | base_preview + annotation_view_all + annotation_edit | | ユーザーが基本的なプレビュー機能と自分の注釈のみを表示する機能を必要とする | base_preview + annotation_view_self | ## 注釈の有効化/無効化と注釈の種類 注釈の種類は、プレビューオプションで選択して無効にすることができます。ビューアーオプションによって、そのビューアーに対してグローバルな`showAnnotations`の値が上書きされます。ここでBoxの注釈とともに使用するプレビューインスタンスを設定する方法の詳細については、[Box Content Preview](g://embed/ui-elements/preview)を参照してください。 ``` preview.show(..., { showAnnotations: Boolean }); ``` 次と組み合わせます。 ``` preview.show(..., { viewers: { VIEWER_NAME: { annotations: { enabled: Boolean, enabledTypes: String[] | null } } } }); ``` これにより、`enabled`が`true`に設定されている場合は、注釈が有効になります。空の場合は`showAnnotations`の値に従います。`enabledTypes`の値は、このビューアーに対して有効にする注釈の種類のリストです。空の場合は、その注釈者のデフォルトの種類に従います。 ### 例 すべての注釈を有効にし、画像ビューアーに対してはオフにします。また、ドキュメントビューアーに対してはポイント注釈のみ有効にします。 ``` preview.show(fileId, token, { showAnnotations: true, viewers: { Image: { annotations: { enabled: false } }, Document: { annotations: { enabled: true, enabledTypes: ["point"] } } } }); ``` ## 注釈者 注釈者の名前には、`DocAnnotator`と`ImageAnnotator`のいずれかを指定することができます。`boxAnnotations.getAnnotators()`を呼び出すと、使用できる注釈のリストを取得できます。 ## その他のメソッド - `annotator.init()`: 注釈者を初期化します。 - `annotator.isModeAnnotatable(/* String */ type)`: 現在のビューアー/注釈者で現在の注釈モードが有効になっているかどうかを返します。 - `annotator.showModeAnnotateButton(/* String */ currentMode)`: 指定した注釈モードの注釈ボタンを示します。 - `annotator.getAnnotateButton(/* String */ annotatorSelector)`: 注釈ボタンの要素を取得します。 - `annotator.showAnnotations()`: 保存されている注釈を取得して表示します。 - `annotator.hideAnnotations()`: 注釈を非表示にします。 - `annotator.hideAnnotationsOnPage(/* number */ pageNum)`: 指定したページで注釈を非表示にします。 - `annotator.setScale()`: 拡大/縮小倍率を設定します。 - `annotator.toggleAnnotationHandler()`: 注釈モードのオンとオフを切り替えます。注釈モードがオンの場合は、その場所に注釈スレッドが作成されます。 - `annotator.disableAnnotationMode(/* String */ mode, /* HTMLElement */ buttonEl)`: 指定した注釈モードを無効にします。 - `annotator.enableAnnotationMode(/* String */ mode, /* HTMLElement */ buttonEl)`: 指定した注釈モードを有効にします。 - `annotator.getAnnotatedEl(/* HTMLElement */ containerEl)`: ビューアー内の注釈付きの要素を特定します。 - `annotator.createAnnotationThread(/* Annotation[] */ annotations, /* Object */ location, /* String */ [annotation type])`: 適切な種類の注釈スレッドを作成し、インメモリのマップに追加して返します。 ## イベント イベントは、`addListener`を使用して注釈者オブジェクトにバインドし、`removeListener`を使用して削除することができます。イベントリスナーは`showAnnotations()`が呼び出される前にバインドする必要があります。そうしないと、イベントが見つからない可能性があります。 ``` /* global BoxAnnotations */ const boxAnnotations = new BoxAnnotations(); const annotatorConf = boxAnnotations.determineAnnotator( options, disabledAnnotationTypes ); // Construct and init annotator const annotator = new annotatorConf.CONSTRUCTOR(options); var listener = value => { // Do something with value }; // Attach listener before calling show otherwise events can be missed annotator.addListener(EVENTNAME, listener); // Initialize a annotator annotator.showAnnotations(); // Remove listener when appropriate annotator.removeListener(EVENTNAME, listener); ``` `EVENTNAME`には、以下のいずれかを指定できます。 - `annotator`イベントは、注釈者インスタンスが最初に使用可能になったときにトリガーされます。Boxの注釈により、`load`の前にこのイベントがトリガーされるため、クライアントは、`load`イベントがBox Content Previewからトリガーされる前にそのリスナーをアタッチできます。 - `annotationsfetched`イベントは、Box APIから注釈が取得されているときにトリガーされます。 - `annotationmodeenter`イベントは、注釈モードに入るとトリガーされます。イベントデータには以下の内容が含まれます。 ``` { // Annotation mode that was entered mode: 'point', // Optional CSS selector for the container's header headerSelector: '.bp-preview-header', } ``` `annotationmodeexit`イベントは、注釈モードが終了するとトリガーされます。イベントデータには以下の内容が含まれます。 ``` { // Annotation mode that was exited mode: 'point', // Optional CSS selector for the container's header headerSelector: '.bp-preview-header', } ``` `annotationerror`イベントは、注釈エラーが発生したときにトリガーされます。イベントデータには以下の内容が含まれます。 ``` { message: 'message', // Error message to show } ``` `annotationpending`イベントは、注釈スレッドが作成されたにもかかわらず、まだサーバーに保存されていない場合にトリガーされます。イベントデータには以下の内容が含まれます。 ``` { data: { type: 'point', // Annotation type threadID: '123abc', userId: '456def', threadNumber: '1' // Thread number from Annotations API } } ``` `annotationthreadsaved`イベントは、注釈スレッドがサーバーに保存されたときにトリガーされます。イベントデータには以下の内容が含まれます。 ``` { data: { type: 'point', // Annotation type threadID: '123abc', userId: '456def', threadNumber: '1' // Thread number from Annotations API } } ``` `annotationthreaddeleted`イベントは、注釈スレッドがサーバーで削除されたときにトリガーされます。イベントデータには以下の内容が含まれます。 ``` { data: { type: 'point', // Annotation type threadID: '123abc', userId: '456def', threadNumber: '1' // Thread number from Annotations API } } ``` `annotationsaved`イベントは、注釈が追加され、サーバー上の既存の注釈スレッドに保存されたときにトリガーされます。イベントデータには以下の内容が含まれます。 ``` { data: { type: 'point', // Annotation type threadID: '123abc', userId: '456def', threadNumber: '1' // Thread number from Annotations API } } ``` `annotationdeleted`イベントは、サーバー上の既存のスレッドから注釈が削除されたときにトリガーされます。注釈スレッド全体は削除されません。イベントデータには以下の内容が含まれます。 ``` { data: { type: 'point', // Annotation type threadID: '123abc', userId: '456def', threadNumber: '1' // Thread number from Annotations API } } ``` `annotationcanceled`イベントは、新しいスレッドまたは既存のスレッドで注釈の投稿がキャンセルされたときにトリガーされます。イベントデータには以下の内容が含まれます。 ``` { data: { type: 'point', // Annotation type threadID: '123abc', userId: '456def', threadNumber: '1' // Thread number from Annotations API } } ``` `annotationdeleteerror`イベントは、新しいスレッドまたは既存のスレッドで注釈の削除中にエラーが発生したときにトリガーされます。イベントデータには以下の内容が含まれます。 ``` { data: { type: 'point', // Annotation type threadID: '123abc', userId: '456def', threadNumber: '1' // Thread number from Annotations API } } ``` `annotationcreateerror`イベントは、新しいスレッドまたは既存のスレッドで注釈の投稿中にエラーが発生したときにトリガーされます。イベントデータには以下の内容が含まれます。 ``` { data: { type: 'point', // Annotation type threadID: '123abc', userId: '456def', threadNumber: '1' // Thread number from Annotations API } } ``` `annotatorevent`: 注釈者ごとに、一連の独自のイベントがトリガーされます。たとえば、画像の注釈者では`rotate`や`resize`などがトリガーされるのに対し、別の注釈者では別の一連のイベントがトリガーされる場合があります。また、注釈者ラッパーは、以下を含むイベントデータとともに、Box Content Previewのプレビューレベルでイベントを再発行します。 ``` { event: EVENTNAME, // Event name data: DATA, // Event data object annotatorName: ANNOTATORNAME, // Name of the annotator fileVersionId: fileVersionId // The file version id fileId: fileId // The file id } ``` ### イベントの使用例 ``` preview.addListener("annotator", viewer => { annotator.addListener("annotationsfetched", () => { // Do something when annotations are fetched on a preview }); }); // Event listeners can be attached to viewers preview.addListener("load", data => { var viewer = data.viewer; viewer.addListener("annotationsfetched", () => { // Do something when annotations are fetched on a preview }); }); // Event listeners can be attached to annotators preview.addListener("load", data => { var annotator = data.viewer.annotator; annotator.addListener("annotationsfetched", () => { // Do something when annotations are fetched on a preview }); }); preview.addListener("annotatorevent", data => { if (data.event === "annotationsfetched") { // Do something when annotations are fetched on a preview } else if (data.event === "annotationerror") { // Do something different when an annotation error has occurred } else { } }); preview.addListener("annotatorevent", data => { if (data.viewerName === "Image") { if (data.event === "annotationsfetched") { // Do something when annotations are fetched on an image preview } } else if (data.viewerName === "MultiImage") { if (data.event === "annotationsfetched") { // Do something different when annotations are fetched on a multi-page image } } else { } }); preview.addListener("annotationsfetched", data => { if (data.viewerName === "Image") { // Do something when annotations are fetched on an image preview } else if (data.viewerName === "MultiImage") { // Do something different when annotations are fetched on a multi-page image } else { } }); ``` ## 注釈スレッド ### スレッドのメソッド 注釈スレッドには、以下のメソッドを使用できます。 | メソッド名 | 説明 | メソッドのパラメータ | | --- | --- | --- | | createDialog | スレッドのダイアログボックスを作成します。 | | | show | 注釈インジケータを表示します。 | | | hide | 注釈インジケータを非表示にします。 | | | reset | スレッドの状態を「inactive」にリセットします。 | | | showDialog | このスレッドに適切なダイアログを表示します。 | | | hideDialog | このスレッドに適切なダイアログを非表示にします。 | | | saveAnnotation | 注釈をローカルとサーバーに保存します。 | {string} 注釈の種類、{text} 保存する注釈のテキスト | | deleteAnnotation | 注釈を削除します。 | {string} 注釈ID、{boolean} サーバー上で削除するかどうか (デフォルトはtrue) | ### スレッドのイベント すべての注釈スレッドでは以下のイベントがトリガーされます。イベントデータには以下の内容が含まれます。 ``` { data: { type: 'point', // Annotation type threadID: '123abc', userId: '456def', threadNumber: '1' // Thread number from Annotations API } } ``` | イベント名 | 説明 | | --- | --- | | annotationpending | 注釈スレッドは作成されましたが、まだサーバーに保存されていません。 | | annotationthreadsaved | 注釈スレッドはサーバーに保存されました。 | | annotationthreaddeleted | 注釈スレッドはサーバーで削除されました。 | | annotationsaved | 注釈スレッドは追加され、サーバー上の既存の注釈スレッドに保存されました。 | | annotationdeleted | 注釈スレッドはサーバー上の既存のスレッドから削除されました。注釈スレッド全体は削除されていません。 | | annotationcanceled | 新しいスレッドまたは既存のスレッドで注釈スレッドの投稿がキャンセルされました。 | | annotationdeleteerror | 新しいスレッドまたは既存のスレッドで注釈の削除中にエラーが発生しました。 | | annotationcreateerror | 新しいスレッドまたは既存のスレッドで注釈の投稿中にエラーが発生しました。 | イベントの使用例については、上記の「**イベント**」セクションを参照してください。 ## 注釈ダイアログ ### ダイアログのメソッド 注釈ダイアログには、以下のメソッドを使用できます。 | メソッド名 | 説明 | メソッドのパラメータ | | --- | --- | --- | | show | ダイアログを配置して表示します。 | | | hide | ダイアログを非表示にします。 | | | hideMobileDialog | 共有モバイルダイアログを非表示にしてリセットします。 | | | addAnnotation | 注釈をダイアログに追加します。 | {Annotation} 追加する注釈 | | removeAnnotation | 注釈をダイアログから削除します。 | {string} 注釈ID | | postAnnotation | 注釈をダイアログで投稿します。 | {string} 投稿する注釈テキスト | | position | ダイアログを配置します。 | | ## サポートされている注釈の種類 ポイント注釈は、ドキュメント形式と画像形式の両方でサポートされています。コメントのハイライト、ハイライトのみ、描画による注釈はドキュメント形式でのみサポートされています。 サポートされているドキュメントのファイル拡張子: `pdf`、`doc`、`docx`、`ppt`、`pptx`、`xlsx`、`xls`、`xlsm`。 サポートされている画像のファイル拡張子: `ai`、`bmp`、`dcm`、`eps`、`gif`、`idml`、`indd`、`indt`、`inx``png`、`ps`、`psd`、`svs`、`tga`、`tif`、`tiff`。 **Source:** [https://ja.developer.box.com/guides/embed/ui-elements/annotations/](https://ja.developer.box.com/guides/embed/ui-elements/annotations/) --- ### 注釈トークン **Type:** guide | **Category:** 認証 | **Section:** Developer Guides 注釈トークン 注釈は、新しいBox Viewでサポートされる主な機能の1つです。開発者はこの機能を使用して、アプリケーションに埋め込まれたプレビュー内から直接、コラボレーション機能を提供できます。 Box View… # 注釈トークン 注釈は、新しいBox Viewでサポートされる主な機能の1つです。開発者はこの機能を使用して、アプリケーションに埋め込まれたプレビュー内から直接、コラボレーション機能を提供できます。 Box Viewでは、ハイライトのみ、ハイライトによる注釈、およびポイント注釈という3つの注釈の種類をサポートしています。注釈はドキュメントと画像のプレビューのみでサポートされます。 ## 注釈トークンとは 注釈トークンとは、ユーザーが注釈を付けることができるファイルに対してアプリケーションがプレビューの埋め込みリンクを作成できるようにするアクセストークンです。アプリケーションでは、アプリケーションのユーザーそれぞれに新しいApp Userが作成されない可能性があるため、注釈トークンを使用すると、注釈を付けたユーザーを追跡できます。 注釈トークンは、一意のユーザーIDと表示名にリンクされているプレビューセッション (有効期限付き埋め込みリンク) を生成するために、通常のアクセストークン、アプリトークン、またはファイルトークンの代わりに使用されます。 注釈トークンを使用して生成されたプレビューセッションは特定の外部ユーザーに関連付けられるため、アプリケーションでは、アプリケーションのエンドユーザーごとに異なる注釈トークンを使用して、個別にプレビューセッションを生成することを強くお勧めします。 ## 外部ユーザー情報 注釈に関連付けられた外部の表示名は、実際のところ、注釈に追加されるステートレスな「ラベル」です。つまり、注釈が追加されると、その表示名は完全に注釈と関連付けられるため、注釈を削除し、更新した表示名を使用して再度追加しなければ更新できません。 ## SDKを使用せずに作成 注釈トークンを作成するには、[JWTを使用して手動で認証する](g://authentication/jwt/without-sdk)手順に従いますが、その際、JWTクレームを次のデータに置き換えます。 ``` var claims = new List<Claim>{ new Claim("sub", '[EXTERNAL_USER_ID]'), new Claim("name", '[EXTERNAL_USER_DISPLAY_NAME]'), new Claim("box_sub_type", "external"), new Claim("jti", jti), }; ``` ``` JwtClaims claims = new JwtClaims(); claims.setIssuer(config.boxAppSettings.clientID); claims.setAudience(authenticationUrl); claims.setSubject("[EXTERNAL_USER_ID]"); claims.setName("[EXTERNAL_USER_DISPLAY_NAME]"); claims.setClaim("box_sub_type", "external"); claims.setGeneratedJwtId(64); claims.setExpirationTimeMinutesInTheFuture(0.75f); ``` ``` claims = { 'iss': config['boxAppSettings']['clientID'], 'sub': '[EXTERNAL_USER_ID]', 'name': '[EXTERNAL_USER_DISPLAY_NAME]', 'box_sub_type': 'external', 'aud': authentication_url, 'jti': secrets.token_hex(64), 'exp': round(time.time()) + 45 } ``` ``` let claims = { iss: config.boxAppSettings.clientID, sub: "[EXTERNAL_USER_ID]", name: "[EXTERNAL_USER_DISPLAY_NAME]", box_sub_type: "external", aud: authenticationUrl, jti: crypto.randomBytes(64).toString("hex"), exp: Math.floor(Date.now() / 1000) + 45 }; ``` ``` claims = { iss: config['boxAppSettings']['clientID'], sub: "[EXTERNAL_USER_ID]", name: "[EXTERNAL_USER_DISPLAY_NAME]", box_sub_type: 'external', aud: authentication_url, jti: SecureRandom.hex(64), exp: Time.now.to_i + 45 } ``` ``` $claims = [ 'iss' => $config->boxAppSettings->clientID, 'sub' => '[EXTERNAL_USER_ID]', 'name' => '[EXTERNAL_USER_DISPLAY_NAME]', 'box_sub_type' => 'external', 'aud' => $authenticationUrl, 'jti' => base64_encode(random_bytes(64)), 'exp' => time() + 45, 'kid' => $config->boxAppSettings->appAuth->publicKeyID ]; ``` | パラメータ | 型 | 説明 | | --- | --- | --- | | sub | String | この注釈を関連付ける外部ユーザーID。このIDには、アプリケーションで追跡される任意のIDを使用できます。 | | box_sub_type | String | 外部ユーザーIDを示す場合はexternal | | box_sub_type | String | この注釈を関連付ける外部ユーザー名。これはBox UIに表示されます。 | その後、ガイドに従ってこのクレームをアサーションに変換し、このアサーションを、既存の有効なアクセストークン、アプリトークン、またはファイルトークンのほか、スコープのセット、トークンの作成対象となるリソースとともに[`POST /oauth2/token`](e://post-oauth2-token)エンドポイントに渡します。 ``` var content = new FormUrlEncodedContent(new[] { new KeyValuePair<string, string>( "grant_type", "urn:ietf:params:oauth:grant-type:token-exchange"), new KeyValuePair<string, string>( "resource", "https://api.box.com/2.0/files/123456"), new KeyValuePair<string, string>( "subject_token", "[ACCESS_TOKEN]"), new KeyValuePair<string, string>( "subject_token_type", "urn:ietf:params:oauth:token-type:access_token"), new KeyValuePair<string, string>( "scope", "item_preview"), new KeyValuePair<string, string>( "actor_token", "[JWT_ASSERTION_FOR_ANNOTATOR_TOKEN]"), new KeyValuePair<string, string>( "actor_token_type", "urn:ietf:params:oauth:token-type:id_token"), }); ``` ``` List<NameValuePair> params = new ArrayList<NameValuePair>(); params.add(new BasicNameValuePair( "grant_type", "urn:ietf:params:oauth:grant-type:token-exchange")); params.add(new BasicNameValuePair( "resource", "https://api.box.com/2.0/files/123456")); params.add(new BasicNameValuePair( "subject_token", "[ACCESS_TOKEN]")); params.add(new BasicNameValuePair( "subject_token_type", "urn:ietf:params:oauth:token-type:access_token")); params.add(new BasicNameValuePair( "scope", "item_preview")); params.add(new BasicNameValuePair( "actor_token", "[JWT_ASSERTION_FOR_ANNOTATOR_TOKEN]")); params.add(new BasicNameValuePair( "actor_token_type", "urn:ietf:params:oauth:token-type:id_token")); ``` ``` params = urlencode({ 'grant_type': 'urn:ietf:params:oauth:grant-type:token-exchange', 'resource': 'https://api.box.com/2.0/files/123456', 'subject_token': '[ACCESS_TOKEN]', 'subject_token_type': 'urn:ietf:params:oauth:token-type:access_token', 'scope': 'item_preview', 'actor_token': '[JWT_ASSERTION_FOR_ANNOTATOR_TOKEN]', 'actor_token_type': 'urn:ietf:params:oauth:token-type:id_token' }).encode() ``` ``` let accessToken = await axios .post( authenticationUrl, querystring.stringify({ grant_type: "urn:ietf:params:oauth:grant-type:token-exchange", resource: "https://api.box.com/2.0/files/123456", subject_token: "[ACCESS_TOKEN]", subject_token_type: "urn:ietf:params:oauth:token-type:access_token", scope: "item_preview", actor_token: "[JWT_ASSERTION_FOR_ANNOTATOR_TOKEN]", actor_token_type: "urn:ietf:params:oauth:token-type:id_token" }) ) .then(response => response.data.access_token); ``` ``` params = URI.encode_www_form({ grant_type: 'urn:ietf:params:oauth:grant-type:token-exchange', resource: 'https://api.box.com/2.0/files/123456', subject_token: '[ACCESS_TOKEN]', subject_token_type: 'urn:ietf:params:oauth:token-type:access_token', scope: 'item_preview', actor_token: '[JWT_ASSERTION_FOR_ANNOTATOR_TOKEN]', actor_token_type: 'urn:ietf:params:oauth:token-type:id_token' }) ``` ``` $params = [ 'grant_type' => 'urn:ietf:params:oauth:grant-type:token-exchange', 'resource' => 'https://api.box.com/2.0/files/123456', 'subject_token' => '[ACCESS_TOKEN]', 'subject_token_type' => 'urn:ietf:params:oauth:token-type:access_token', 'scope' => 'item_preview', 'actor_token' => '[JWT_ASSERTION_FOR_ANNOTATOR_TOKEN]', 'actor_token_type' => 'urn:ietf:params:oauth:token-type:id_token' ]; ``` | パラメータ | 説明 | | --- | --- | | resource | トークンが制限されるファイルへの完全なURLパス (省略可)。 | | actor_token | 以前に作成されたJWTアサーション | | actor_token_type | 常にurn:ietf:params:oauth:token-type:id_tokenに設定します。 | ## SDKを使用して作成 SDKを使用してJWT注釈トークンを作成するために、アプリケーションはアクティブなトークンを別のトークンと交換できます。 ``` var options = { actor: { id: "[EXTERNAL_USER_ID]", name: "[EXTERNAL_USER_DISPLAY_NAME" } }; client .exchangeToken( "item_preview", "https://api.box.com/2.0/files/123456", options ) .then(tokenInfo => { //=> tokenInfo.accessToken }); ``` **Source:** [https://ja.developer.box.com/guides/authentication/tokens/annotator-tokens/](https://ja.developer.box.com/guides/authentication/tokens/annotator-tokens/) --- ### 浮動小数点メタデータフィールド **Type:** guide | **Category:** メタデータ | **Section:** Developer Guides 浮動小数点メタデータフィールド floatタイプのメタデータフィールドは、数値入力のみが可能な標準のテキストフィールドとしてユーザーに表示されます。 浮動小数点フィールドの作成 floatフィールドは、メタデータテンプレートの作成時、またはaddField… # 浮動小数点メタデータフィールド `float`タイプのメタデータフィールドは、数値入力のみが可能な標準のテキストフィールドとしてユーザーに表示されます。 ## 浮動小数点フィールドの作成 `float`フィールドは、[メタデータテンプレートの作成](g://metadata/templates/create)時、または`addField`操作による[テンプレートの更新](g://metadata/templates/update)時にメタデータテンプレートに追加できます。 `float`フィールドの必須属性は、`type`、`displayName`、および`key`です。 ``` { "scope": "enterprise", "displayName": "Contract", "fields": [ { "type": "float", "key": "contract_value", "displayName": "Contract Value", "description": "The contract's total value", "hidden": false } ] } ``` 必要に応じて、UIでユーザーに表示される`description`を指定できます。また、このフィールドを`hidden`に設定して、ウェブアプリとモバイルアプリでユーザーに表示されないようにすることもできます。 ## 浮動小数点フィールドの更新 `float`テンプレートフィールドは、このフィールドが属する[テンプレートを更新](g://metadata/templates/update)することで更新できます。テンプレートの更新は、ファイルまたはフォルダにすでに割り当てられているテンプレートも確実に更新される**操作**によって行われます。 `float`メタデータフィールドを更新する際、関連する操作は、フィールドの`key`、`displayName`、`description`、および`hidden`の値を変更するのに使用できる`editField`操作のみです。 ``` [ { "op": "editField", "fieldKey": "contract_value", "data": { "displayName": "Total Annual Contract Value", "description": "The contract's total anual value", "key": "contract_tav", "hidden": true } } ] ``` これは、このテンプレートの既存のインスタンスに影響します。 **Source:** [https://ja.developer.box.com/guides/metadata/fields/float/](https://ja.developer.box.com/guides/metadata/fields/float/) --- ### 目的のレプリゼンテーションのリクエスト **Type:** guide | **Category:** レプリゼンテーション | **Section:** Developer Guides 目的のレプリゼンテーションのリクエスト 特定のレプリゼンテーションを選択するには、必要なレプリゼンテーション形式を定義するx-rep-hintsヘッダーを使用してGET /files/:id… # 目的のレプリゼンテーションのリクエスト 特定のレプリゼンテーションを選択するには、必要なレプリゼンテーション形式を定義する[`x-rep-hints`](endpoint://get-files-id#param-x-rep-hints)ヘッダーを使用して[`GET /files/:id`](endpoint://get-files-id)エンドポイントを呼び出します。 ``` curl https://api.box.com/2.0/files/123?fields=representations \ -H "x-rep-hints: [pdf]" \ -H "authorization: Bearer ACCESS_TOKEN" ``` ## 複数のサイズ 形式によっては、特定のサイズを選択するために、`dimensions`を渡すことが必要になる場合があります。そのためには、ヘッダーに`dimensions`を追加します。 ``` curl https://api.box.com/2.0/files/123?fields=representations \ -H "x-rep-hints: [jpg?dimensions=94x94]" \ -H "authorization: Bearer ACCESS_TOKEN" ``` ## 複数のレプリゼンテーション `x-rep-hints`ヘッダーでさまざまなタイプを続けて指定することで、複数のレプリゼンテーションを取得できます。 ``` curl https://api.box.com/2.0/files/123?fields=representations \ -H "x-rep-hints: [pdf][jpg?dimensions=94x94]" \ -H "authorization: Bearer ACCESS_TOKEN" ``` ## APIレスポンス このAPIコールの結果、`{+asset_path}`値を含む`url_template`値を使用して1つ以上のレプリゼンテーションが返されます。 ``` { "etag": "1", "id": "123", "representations": { "entries": [ { "content": { "url_template": "https://dl.boxcloud.com/api/2.0/internal_files/123/versions/345/representations/pdf/content/{+asset_path}" }, "info": { "url": "https://api.box.com/2.0/internal_files/123/versions/345/representations/pdf" }, "properties": {}, "representation": "pdf", "status": { "state": "success" } } ] }, "type": "file" } ``` このレスポンスの`url_template`は、**不明瞭な**URLです。このURL形式は、時間が経つと変わる可能性があるため、`{+asset_path}`変数の有無を除き、この形式についてさまざまな憶測を立てないようにしてください。 **Source:** [https://ja.developer.box.com/guides/representations/request-a-representation/](https://ja.developer.box.com/guides/representations/request-a-representation/) --- ### 直接アップロード **Type:** guide | **Category:** アップロード | **Section:** Developer Guides 直接アップロード Boxにファイルをアップロードする最も簡単な方法は、直接アップロードを使用することです。直接アップロードにより、アプリケーションは1つのリクエストでファイルをアップロードできます。ファイルサイズが50 MB… # 直接アップロード Boxにファイルをアップロードする最も簡単な方法は、直接アップロードを使用することです。直接アップロードにより、アプリケーションは1つのリクエストでファイルをアップロードできます。ファイルサイズが50 MBを超える場合は、[分割アップロードエンドポイント](g://uploads/chunked)を使用することをお勧めします。 Boxにアップロードできるファイルサイズの上限は、アカウントの種類によって異なります。詳細については、[価格比較ページ](https://www.box.com/pricing)を参照してください。 - 個人用アカウント: 250 MB - Starter: 2 GB - Business: 5 GB - Business Plus: 15 GB - Enterprise: 50 GB - Digital Workplace Suite: 50 GB - Digital Workplace Global Suite: 50 GB - Digital Business Suite: 50 GB - Digital Business Global Suite: 50 GB - Enterprise Plus: 150 GB - Enterprise Advanced: 500 GB 自分のアカウントのファイルサイズの上限を確認するには、Boxにログインします。右上隅の円をクリックし、ドロップダウンメニューから [**アカウント設定**] を選択します。表示されたページで、[**アカウントの詳細**] セクションまで下にスクロールすると、[**最大ファイルサイズ**] が表示されています。 ## アップロードドメイン Boxへのアップロードは、通常のAPIコールとは異なるドメイン (`upload.box.com`) を介して行われます。独自のアップロードコードを記述する際は、この点に注意する必要があります。すべてのBox公式SDKでは、各APIコールに適切なドメインが選択されます。 **Source:** [https://ja.developer.box.com/guides/uploads/direct/](https://ja.developer.box.com/guides/uploads/direct/) --- ### 管理対象ユーザーの作成 **Type:** guide | **Category:** ユーザー | **Section:** Developer Guides 管理対象ユーザーの作成 新しい管理対象ユーザーを生成するには、最低でも管理対象ユーザーの名前とメールアドレスが必要になります。 管理対象ユーザーの作成時に指定するメールアドレスは一意である必要があります。既存のBox… # 管理対象ユーザーの作成 新しい管理対象ユーザーを生成するには、最低でも管理対象ユーザーの名前とメールアドレスが必要になります。 管理対象ユーザーの作成時に指定するメールアドレスは一意である必要があります。既存のBoxユーザーにすでに関連付けられているメールアドレスは使用できません。 App Userの作成時に設定できるすべての使用可能なオプションパラメータを確認するには、[ユーザーを作成](endpoint://post-users)エンドポイントを参照してください。 新しく作成したアカウントを変更できるようにするには、受信した確認メールにあるリンクをクリックする必要があります。 ユーザー作成リクエストから、ユーザーオブジェクトが返されます。このユーザーオブジェクトには管理対象ユーザーのIDが含まれています。これは、今後ユーザーを変更するAPIリクエストを実行するために使用できます。 新しい管理対象ユーザーが作成されると、使用されているメールアドレス宛てに、アカウントのパスワードの作成を求めるメールがBoxから届きます。このアクションが実行されるまで、アカウントは`pending`状態になります。 セキュリティ上の理由から、新しい管理対象ユーザーの作成時にパスワードを指定することはできません。 **Source:** [https://ja.developer.box.com/guides/users/create-managed-user/](https://ja.developer.box.com/guides/users/create-managed-user/) --- ### 統合 **Type:** guide | **Category:** アプリケーション | **Section:** Developer Guides 統合 Box統合は、BoxユーザーがBox… # 統合 [Box統合](https://app.box.com/services)は、BoxユーザーがBoxと組み合わせて使用できるアプリケーションについて最初に確認できる場所です。アプリケーションが他の企業で使用できる場合は、**統合**にサービスを登録すると、新しいユーザーを見つけるのに役立ちます。統合では、ユーザーが見つけやすいように、アプリが [おすすめ]、[人気]、[新着] セクションに分類されています。 ## Platformアプリの開発またはBoxパートナーへの参加 Box統合用のPlatformアプリの開発またはBoxパートナーへの参加の詳細については、Box Supportサイトの[Box Partner Resources](https://support.box.com/hc/en-us/sections/21356597387539-Box-Partner-Programs)のガイド (英語) を参照してください。 ## Platformアプリの公開 Box統合でPlatformアプリを公開するには、以下の手順に従います。 ### 前提条件 アプリケーションは、以下の要件を満たす必要があります。 - Platformアプリは完成した状態で、実稼働環境での使用準備ができていること。 - 統合ではOAuth 2.0以外の認証方法がサポートされていないため、PlatformアプリではOAuth 2.0認証を利用すること。 - 開発者として、**開発者コンソール**でそのPlatformアプリにアクセスできること。 ### 手順 開発者コンソールの [**Platformアプリ**] に移動し、公開するアプリを選択します。 上部のメニューで [**公開**] タブを選択します。 送信チェックリストをひととおり読み、アプリがすべての要件を満たしているかどうかを確認するチェックボックスをオンにします。 フォームで以下の項目を指定します。 - アプリが該当するカテゴリ - 簡単な説明と詳しい説明 - スクリーンショットとアプリアイコン - ユーザーをサポートするために使用される補足情報 右上にある [**プレビュー**] ボタンを使用して、登録されたときにアプリケーションがどのように表示されるかを確認します。 最後に、[**承認用に送信**] ボタンをクリックして、アプリケーションを承認用に送信します。承認のリクエストが届くと、Boxパートナーチームは通知を受け取り、リクエストをできるだけ早く確認します。質問がある場合は、[`integrate@box.com`](mailto:integrate@box.com)に英語でお問い合わせください。 ## Platformアプリの公開取り消し 承認されて公開されたPlatformアプリは、同じコントロールパネルから公開を取り消すことができます。 1. **開発者コンソール**に移動して、Platformアプリを選択します。 2. [**公開**] タブを選択します。 3. アプリの公開を取り消すことができます。 **Source:** [https://ja.developer.box.com/guides/applications/integrations/](https://ja.developer.box.com/guides/applications/integrations/) --- ### 統合の種類 **Type:** guide | **Category:** アプリケーション | **Section:** Developer Guides 統合の種類 現在、Boxではポップアップ統合を提供しています。 ポップアップ統合 ポップアップ統合の場合、Boxによってパネルが開き、統合用に構成されたアプリケーションのコールバックURL… # 統合の種類 現在、Boxではポップアップ統合を提供しています。 ## ポップアップ統合 ポップアップ統合の場合、Boxによってパネルが開き、統合用に構成されたアプリケーションのコールバックURLが読み込まれます。アプリケーションでは、ポップアップに統合のための独自のユーザーインターフェースが表示されます。 統合は、このリクエストとともに有効期間の短い承認コードを受信します。この承認コードを使用すると、Box APIに接続し、コードをアクセストークンに交換してから、BoxへのAPIコールを実行できます。 ポップアップパネルでは、HTMLの`<iframe>`タグを使用し、埋め込みコンテンツを表示します。Boxのコンテンツのセキュリティを保護するには、コールバックURLでSSLを使用する必要があります。また、コールバックURLからのレスポンスには、ランダムな文字列値に設定された`X-Frame-Options`ヘッダーを含める必要があります。 **Source:** [https://ja.developer.box.com/guides/applications/web-app-integrations/types/](https://ja.developer.box.com/guides/applications/web-app-integrations/types/) --- ### 統合マッピング **Type:** guide | **Category:** 統合マッピング | **Section:** Developer Guides 統合マッピング 統合マッピングを使用すると、パートナーアプリからのコンテンツがBoxのどこに保存されるかを管理できます。 # 統合マッピング [統合マッピング](r://integration-mappings)を使用すると、パートナーアプリからのコンテンツがBoxのどこに保存されるかを管理できます。 **Source:** [https://ja.developer.box.com/guides/integration-mappings/](https://ja.developer.box.com/guides/integration-mappings/) --- ### 署名の検証 **Type:** guide | **Category:** Webhook | **Section:** Developer Guides 署名の検証 Webhook署名は、Boxから送信されたWebhookペイロードが改ざんされていないことを確認するために役立ちます。署名により、中間者攻撃または再生攻撃が成功する可能性を大幅に低減できます。 署名を構成すると、Box… # 署名の検証 Webhook署名は、Boxから送信されたWebhookペイロードが改ざんされていないことを確認するために役立ちます。署名により、中間者攻撃または再生攻撃が成功する可能性を大幅に低減できます。 署名を構成すると、Boxは通知の本文の暗号化ダイジェストを生成し、これをWebhookペイロードのヘッダーに添付します。アプリケーションがペイロードを受信したら、同じダイジェストを計算し、それを受信したダイジェストと比較して署名を検証してください。ダイジェストが一致しない場合、ペイロードは信頼できません。 署名キーを頻繁に変更することで、保護レベルをさらに高めることができます。古いキーと新しいキーをスムーズに切り替えられるよう、Boxでは同時に2つの署名キーをサポートしています。 ## 署名設定 アプリケーションの通知に署名を添付するには、まず、アプリケーション用の署名キーを生成する必要があります。 アプリケーションのキーを構成するには、以下の手順に従います。 1. 開発者コンソールでアプリケーションに移動します。 2. [**Webhook**] タブをクリックします。 3. [**署名キーを管理**] ボタンをクリックします。 4. [**キーを生成**] ボタンをクリックして、キーを構成します。 プライマリキーまたはセカンダリキーを生成したら、その値をコピーします。この値は、Webhookペイロードの検証で必要になります。これで、すべてのWebhookに`BOX-SIGNATURE-PRIMARY`および`BOX-SIGNATURE-SECONDARY`ヘッダーペイロードが含まれるようになります。 ## SDKによる署名の検証 手動で署名を検証することもできますが、[Box公式SDK](g://tooling/sdks)には便利なメソッドが用意されています。 ## 手動による署名の検証 署名の検証は基本的に以下の手順で行います。 ### タイムスタンプの検証 ペイロードの`BOX-DELIVERY-TIMESTAMP`ヘッダーのタイムスタンプが10分以内のものであることを確認します。 ``` var timestamp = headers['BOX-DELIVERY-TIMESTAMP']; var date = Date.parse(timestamp); var expired = Date.now() - date > 10*60*1000; ``` ``` import dateutil.parser import pytz import datetime timestamp = headers["BOX-DELIVERY-TIMESTAMP"] date = dateutil.parser.parse(timestamp).astimezone(pytz.utc) now = datetime.datetime.now(pytz.utc) delta = datetime.timedelta(minutes=10) expiry_date = now - deltaMinutes expired = date >= expiry_date ``` ### HMAC署名の計算 [開発者コンソール](https://app.box.com/developers/console)でアプリケーションに構成されている2つの署名のいずれかを使用して、ペイロードのHMACを計算します。 最初にペイロード本文のバイトを追加してから、`BOX-DELIVERY-TIMESTAMP`ヘッダーにあるタイムスタンプのバイトを追加してください。 ``` var crypto = require('crypto'); var primaryKey = '...'; var secondaryKey = '...'; var payload = '{"type":"webhook_event"...}'; var hmac1 = crypto.createHmac('sha256', primaryKey); hmac1.update(payload); hmac1.update(timestamp); var hmac2 = crypto.createHmac('sha256', secondaryKey); hmac2.update(payload); hmac2.update(timestamp); ``` ``` import hmac import hashlib primary_key = '...' secondary_key = '...' payload = "{\"type\":\"webhook_event\"...}" bytes = bytes(payload, 'utf-8') + bytes(timestamp, 'utf-8') hmac1 = hmac.new(primary_key, bytes, hashlib.sha256).digest() hmac2 = hmac.new(secondary_key, bytes, hashlib.sha256).digest() ``` ### Base64変換 HMACを`Base64`でエンコードされたダイジェストに変換します。 ``` var digest1 = hmac1.digest('base64'); var digest2 = hmac2.digest('base64'); ``` ``` import base64 digest1 = base64.b64encode(hmac1) digest2 = base64.b64encode(hmac2) ``` ### 署名の比較 エンコードされたダイジェストを`BOX-SIGNATURE-PRIMARY`または`BOX-SIGNATURE-SECONDARY`ヘッダーの値と比較します。 `BOX-SIGNATURE-PRIMARY`ヘッダーの値をプライマリキーで作成されたダイジェストと比較し、`BOX-SIGNATURE-SECONDARY`ヘッダーの値をセカンダリキーで作成されたダイジェストと比較します。タイミング攻撃を防ぐため、署名間でタイミングの影響がない比較方法を使用してください。 ``` const crypto = require('crypto'); function compareSignatures(expectedSignature, receivedSignature) { const expectedBuffer = Buffer.from(expectedSignature, 'base64'); const receivedBuffer = Buffer.from(receivedSignature, 'base64'); if (expectedBuffer.length !== receivedBuffer.length) { return false; } return crypto.timingSafeEqual(expectedBuffer, receivedBuffer); } const signature1 = headers['BOX-SIGNATURE-SECONDARY']; const signature2 = headers['BOX-SIGNATURE-PRIMARY']; const primarySignatureValid = compareSignatures(digest1, signature1) const secondarySignatureValid = compareSignatures(digest2, signature2) const valid = !expired && (primarySignatureValid || secondarySignatureValid) ``` ``` import hmac def compare_signatures(expected_signature: Optional[str], received_signature: Optional[str]) -> bool: if not expected_signature or not received_signature: return False if len(expected_signature) != len(received_signature): return False return hmac.compare_digest(expected_signature, received_signature) signature1 = headers["BOX-SIGNATURE-SECONDARY"] signature2 = headers["BOX-SIGNATURE-PRIMARY"] primary_sig_valid = compare_signatures(digest1, signature1) secondary_sig_valid = compare_signatures(digest2, signature2) valid = not expired and (primary_sig_valid or secondary_sig_valid) ``` HTTPヘッダー名では大文字と小文字が区別されません。クライアントでは、すべてのヘッダーの名前を標準化された小文字または大文字の形式に変換してから、ヘッダーの値を確認する必要があります。 ## 署名のローテーション 有効にした場合、BoxはすべてのWebhookペイロードで2つの署名を送信します。少なくとも1つの署名が有効であれば、アプリケーションはペイロードを信頼できます。一度に1つの署名キーを更新すると、アプリケーションは常に少なくとも1つの有効な署名を含むペイロードを受信することになります。 ### 循環の手順 以下の手順は、[開発者コンソール](https://app.box.com/developers/console)でプライマリキーとセカンダリキーを作成済みで、どちらかのキーを置き換える準備ができていることを前提としています。 これらの手順に従うことにより、競合することなく、2つの新しいキーを使ってアプリケーションを構成できます。 1. [開発者コンソール](https://app.box.com/developers/console)で、[**Webhook**] タブに移動します。 2. [**署名キーを管理**] をクリックします。 3. [**リセット**] ボタンをクリックしてプライマリキーを変更します。 4. 新しいプライマリキーでアプリケーションを更新します。アプリケーションは、引き続き古いプライマリキーを含む通知を受信する可能性がありますが、セカンダリキーがまだ有効であるため、Webhookは正しく処理されます。 5. 古いプライマリキーを持つWebhookが動作していないことを確認できたら、同じプロセスを使用してセカンダリキーを更新できます。 **Source:** [https://ja.developer.box.com/guides/webhooks/v2/signatures-v2/](https://ja.developer.box.com/guides/webhooks/v2/signatures-v2/) --- ### 複数選択メタデータフィールド **Type:** guide | **Category:** メタデータ | **Section:** Developer Guides 複数選択メタデータフィールド multiSelectタイプのメタデータフィールドは、ドロップダウンリストとしてユーザーに表示されます。ユーザーはリストから複数の項目を選択できます。 multiSelectフィールドを使用すると、ユーザーは0個、… # 複数選択メタデータフィールド `multiSelect`タイプのメタデータフィールドは、ドロップダウンリストとしてユーザーに表示されます。ユーザーはリストから複数の項目を選択できます。 `multiSelect`フィールドを使用すると、ユーザーは0個、1個、または複数個の値を選択できます。ユーザーが選択できる値を1つだけに制限するには、[`enum`](g://metadata/fields/enum)テンプレートフィールドを使用します。 ## multiSelectフィールドの作成 `multiSelect`フィールドは、[メタデータテンプレートの作成](g://metadata/templates/create)時、または`addField`操作による[テンプレートの更新](g://metadata/templates/update)時にメタデータテンプレートに追加できます。 `multiSelect`フィールドの必須属性は、`type`、`displayName`、`key`、およびオプションのリストです。 ``` { "scope": "enterprise", "displayName": "Contract", "fields": [ { "type": "multiSelect", "key": "box_entity", "displayName": "Box Entity", "description": "The Box entity that this contract belongs to", "hidden": false, "options": [ {"key": "Box, Inc"}, {"key": "Box.com (UK) Ltd."}, {"key": "KK Box Japan"} ] } ] } ``` 必要に応じて、UIでユーザーに表示される`description`を指定できます。また、このフィールドを`hidden`に設定して、ウェブアプリとモバイルアプリでユーザーに表示されないようにすることもできます。 ## multiSelectフィールドの更新 `multiSelect`テンプレートフィールドは、このフィールドが属する[テンプレートを更新](g://metadata/templates/update)することで更新できます。テンプレートの更新は、ファイルまたはフォルダにすでに割り当てられているテンプレートも確実に更新される**操作**によって行われます。 ### 基本的なフィールド値の変更 `multiSelect`メタデータフィールドを更新する際に可能な操作の1つとして、フィールドの`key`、`displayName`、`description`、および`hidden`の値を変更するのに使用できる`editField`操作があります。 ``` [ { "op": "editField", "fieldKey": "box_entity", "data": { "displayName": "Box Entities", "key": "box_entities" } } ] ``` ここにある`fieldKey`は、変更するフィールドの元のキーを表します。`data.key`フィールドはフィールドの新しいキーです。 これは、このテンプレートの既存のインスタンスに影響します。 ### オプションの追加 `multiSelect`フィールドにオプションを追加するには、`addMultiSelectOption`操作を使用します。この操作では、`fieldKey`に、変更する`multiSelect`フィールドのキーを設定するほか、`data`オブジェクトには、追加する新しいオプションの`key`を指定する必要があります。 ``` [ { "op": "addMultiSelectOption", "fieldKey": "box_entity", "data": { "key": "Box (NL) BV" } } ] ``` オプションのリストは次のようになります。 ``` ... "options": [ {"key": "Box, Inc"}, {"key": "Box.com (UK) Ltd."}, {"key": "KK Box Japan"}, {"key": "Box (NL) BV"} ] ... ``` これは、このテンプレートの既存のインスタンスに影響します。 ### オプションの並べ替え `multiSelect`フィールドでオプションを並べ替えるには、`reorderMultiSelectOptions`操作を使用します。この操作では、`fieldKey`に、変更する`multiSelect`フィールドのキーを設定するほか、`multiSelectOptionKeys`配列にはオプションのキーを順番に指定する必要があります。 ``` [ { "op": "reorderMultiSelectOptions", "fieldKey": "box_entity", "multiSelectOptionKeys": [ "Box, Inc", "Box.com (UK) Ltd.", "Box (NL) BV", "KK Box Japan" ] } ] ``` オプションのリストは次のようになります。 ``` ... "options": [ {"key": "Box, Inc"}, {"key": "Box.com (UK) Ltd."}, {"key": "Box (NL) BV"}, {"key": "KK Box Japan"} ] ... ``` この操作では、新しいオプションを追加することはできません。これは、このテンプレートの既存のインスタンスに影響します。 ### オプションの編集 `multiSelect`フィールドのオプションを編集するには、`editMultiSelectOption`操作を使用します。この操作では、`fieldKey`に、変更する`multiSelect`フィールドのキーを設定し、`multiSelectOptionKey`に、フィールドオプションのキーを設定する必要があります。最後に、`data`オブジェクトには、フィールドオプションの新しい`key`を指定する必要があります。 ``` [ { "op": "editMultiSelectOption", "fieldKey": "box_entity", "multiSelectOptionKey": "Box (NL) BV", "data": { "key": "Box.nl BV" } } ] ``` オプションのリストは次のようになります。 ``` ... "options": [ {"key": "Box, Inc"}, {"key": "Box.com (UK) Ltd."}, {"key": "Box.nl BV"}, {"key": "KK Box Japan"} ] ... ``` これは、このテンプレートの既存のインスタンスに影響します。 ### オプションの削除 `multiSelect`フィールドからオプションを削除するには、`removeMultiSelectOption`操作を使用します。この操作では、`fieldKey`に、変更する`multiSelect`フィールドのキーを設定し、`multiSelectOptionKey`に、削除するフィールドオプションのキーを設定します。 ``` [ { "op": "removeMultiSelectOption", "fieldKey": "customer_state", "multiSelectOptionKey": "KK Box Japan" } ] ``` オプションのリストは次のようになります。 ``` ... "options": [ {"key": "Box, Inc"}, {"key": "Box.com (UK) Ltd."}, {"key": "Box.nl BV"} ] ... ``` これは、このテンプレートの既存のインスタンスに影響します。この値に設定されたすべてのフィールドでは、値が、選択した値のリストから削除されます。 **Source:** [https://ja.developer.box.com/guides/metadata/fields/multi-select/](https://ja.developer.box.com/guides/metadata/fields/multi-select/) --- ### 言語コード **Type:** guide | **Category:** APIコール | **Section:** Developer Guides 言語コード Box APIでは、ISO 639-1言語コードの修正版を使用して、ユーザーの言語を指定します。 以下は、作成または更新時に使用する言語コードのリストです。 言語 コード ベンガル語 bn デンマーク語 da ドイツ語 de 英語 (米国) en 英語 (英国) gb… # 言語コード Box APIでは、**ISO 639-1言語コード**の修正版を使用して、ユーザーの言語を指定します。 以下は、[作成](e://post_users#param-language)または[更新](e://put_users_id#param-language)時に使用する言語コードのリストです。 | 言語 | コード | | --- | --- | | ベンガル語 | bn | | デンマーク語 | da | | ドイツ語 | de | | 英語 (米国) | en | | 英語 (英国) | gb | | 英語 (カナダ) | e2 | | 英語 (オーストラリア) | e3 | | スペイン語 (ラテンアメリカ) | s2 | | スペイン語 | es | | フィンランド語 | fi | | フランス語 | fr | | フランス語 (カナダ) | f2 | | ヒンディー語 | hi | | イタリア語 | it | | 日本語 | ja | | 韓国語 | ko | | ノルウェー語 (ブークモール) | nb | | オランダ語 | nl | | ポーランド語 | pl | | ポルトガル語 | pt | | ロシア語 | ru | | スウェーデン語 | sv | | トルコ語 | tr | | 中国語 (簡体) | zh | | 中国語 (繁体) | zt | **Source:** [https://ja.developer.box.com/guides/api-calls/language-codes/](https://ja.developer.box.com/guides/api-calls/language-codes/) --- ### 設定 **Type:** guide | **Category:** Boxの埋め込み | **Section:** Developer Guides 設定 Boxにファイルをアップロードし、Box Viewを使用してプレビューする前に、Boxアプリケーションを作成し、そのアプリケーション用にアクセストークンを生成する必要があります。 アプリトークンアプリの作成 Box View… # 設定 Boxにファイルをアップロードし、Box Viewを使用してプレビューする前に、Boxアプリケーションを作成し、そのアプリケーション用にアクセストークンを生成する必要があります。 ## アプリトークンアプリの作成 Box Viewでは、**アプリトークン認証**と呼ばれる認証メカニズムを使用して、特定のBoxユーザーとは対照的に、アプリケーションのアカウント内に直接ファイルを保存します。これにより、ユーザーとコンテンツを関連付ける必要なく、ファイルのプレビューが可能になります。 最初の手順として、アプリケーションを作成し、管理者からアプリケーションの承認を受けて、BoxにAPIリクエストの発行を開始します。 アプリトークンアプリのセットアップと承認 アプリトークンアプリは、Box管理者による承認が必要です。承認されない場合は、APIリクエストの送信時に権限エラーが発生します。アプリ承認を受けるには、[このガイド](guide://authorization/custom-app-approval)に従ってください。 ## アクセストークンの生成 アプリケーションが読み込まれた状態で、左側のナビゲーションメニューで [**構成**] オプションをクリックします。アプリケーションの [構成] ページは次のようになります。 [**プライマリアクセストークン**] セクション内の [**キーを生成**] ボタンをクリックします。 Developerアカウント用の2要素認証設定がない場合は、アプリトークンを正常に生成できるよう事前に2要素認証の設定が求められます。プロンプトの指示に従って2要素認証を設定してください。 トークンの有効期限に30日、60日、または有効期限なしを選択します。 アプリトークンが生成されたら、コピーして安全に保存します。アプリトークンは、ページが再読み込みされると表示されなくなります。これは、Boxでは実際のトークンではなくトークンの一方向のハッシュが保存されているため、元のトークンを再取得できないからです。 **Source:** [https://ja.developer.box.com/guides/embed/box-view/setup/](https://ja.developer.box.com/guides/embed/box-view/setup/) --- ### 設定 **Type:** guide | **Category:** Box Skills | **Section:** Developer Guides 設定 カスタムスキルの設定は、複数の手順からなるプロセスです。 前提条件 OAuth 2.0認証を使用してPlatformアプリを設定するには、Box Enterpriseアカウントから開発者コンソールにアクセスできることを確認する必要があります。または、Developer… # 設定 カスタムスキルの設定は、複数の手順からなるプロセスです。 ## 前提条件 OAuth 2.0認証を使用してPlatformアプリを設定するには、Box Enterpriseアカウントから[開発者コンソール](https://app.box.com/developers/console)にアクセスできることを確認する必要があります。または、[Developerアカウント](https://account.box.com/signup/n/developer)にサインアップすることもできます。 ## アプリの作成手順 ### 1. 開発者コンソールにログインする Boxにログインし、[開発者コンソール](https://app.box.com/developers/console)に移動して、[**アプリの新規作成**] を選択します。 ### 2. カスタムスキルを作成する アプリケーションの種類のリストから [**Box Custom Skill**] を選択します。次の手順を促すウィンドウが表示されます。 ### 3. 名前を入力する 最後に、アプリケーションの一意の名前を選択し、[**Platformアプリの作成**] をクリックします。 ## 承認 スキルの使用を開始するには、スキルをトリガーするフォルダを選択しておく必要があります。 カスタムスキルの承認の詳細を確認する ## 基本的な構成 フォルダでカスタムスキルを有効にするには、いくつかの追加構成を完了しておく必要があります。 ### 呼び出しURL 選択したフォルダにファイルがアップロード、コピー、または移動されるたびに、スキルからリモートURLにペイロードが送信されます。このURLは呼び出しURLと呼ばれます。 呼び出しURLには、サーバー、開発マシン、またはサーバーレス関数を表す任意のHTTPエンドポイントを指定できます。唯一の要件は、そのURLが公開されていて、Boxサーバーからアクセスできることです。そのため、`localhost`は有効なアドレスではありません。 呼び出しURLを設定するには、[開発者コンソール](https://app.box.com/developers/console)の [**構成**] タブに移動し、[呼び出しURL] セクションまで下にスクロールします。 セキュアなHTTPSアドレスを入力し、フォームを保存します。これで、呼び出しURLを構成できました。 ### ファイル拡張子 デフォルトでは、フォルダ内の任意のファイルの種類に対してカスタムスキルがトリガーされます。選択したファイル拡張子だけがスキルをトリガーするよう指定するには、[開発者コンソール](https://app.box.com/developers/console)の [**構成**] タブに移動し、[**ファイル拡張子**] セクションまで下にスクロールします。 **Source:** [https://ja.developer.box.com/guides/skills/handle/setup/](https://ja.developer.box.com/guides/skills/handle/setup/) --- ### 認証 **Type:** guide | **Category:** 認証 | **Section:** Developer Guides 認証 Box API… # 認証 Box APIを使用する認証では、ユーザーの本人確認にアクセストークンを使用します。アクセストークンの取得方法は、ユーザーの承認に使用した方法によって異なります。アプリケーションで利用できる承認の種類は、ユースケースのほか、開発者コンソールで作成されたアプリケーションの種類に応じて異なります。 | Boxアプリケーションの種類 | 認証方法 | | --- | --- | | Platformアプリ | OAuth 2.0、JWT、またはクライアント資格情報許可 | | アクセス制限付きアプリ | アプリトークン | | カスタムスキル | 認証方法は選択不要 | 承認の種類の選択方法を確認する ## 認証のアクセストークン 各APIエンドポイントには、APIコールを実行するために有効でアクティブな**アクセストークン**が必要です。アクセストークンは、APIエンドポイントに対して認証済みBoxユーザーを識別する一意の文字列です。 ``` curl https://api.box.com/2.0/users/me \ -H "authorization: Bearer EGmDmRVfhfHsqesn5yVYHAqUkD0dyDfk" ``` アクセストークンの詳細を確認する **Source:** [https://ja.developer.box.com/guides/authentication/](https://ja.developer.box.com/guides/authentication/) --- ### 認証方法の選択 **Type:** guide | **Category:** 認証 | **Section:** Developer Guides 認証方法の選択 アプリケーションで使用できる承認の種類は、開発者コンソールで構成したBoxアプリケーションの種類によって異なります。 アプリケーションの種類の選択方法を確認する 各種Boxアプリケーションでは、以下の承認方法を使用できます。 Box… # 認証方法の選択 アプリケーションで使用できる承認の種類は、開発者コンソールで構成したBoxアプリケーションの種類によって異なります。 アプリケーションの種類の選択方法を確認する 各種Boxアプリケーションでは、以下の承認方法を使用できます。 | Boxアプリケーションの種類 | OAuth 2.0をサポートしますか? | JWTは? | クライアント資格情報は? | アプリトークンは? | | --- | --- | --- | --- | --- | | Platformアプリ | はい | はい | はい | いいえ | | アクセス制限付きアプリ | いいえ | いいえ | いいえ | はい | | カスタムスキル | いいえ | いいえ | いいえ | いいえ | ## クライアント側 ### OAuth 2.0 OAuth 2.0では、アプリケーションに対して、エンドユーザーをブラウザにリダイレクトしてBoxにログインさせ、ユーザーに代わってアプリケーションが処理を実行することを承認するよう要求します。 # OAuth 2.0はいつ使用すべきですか? クライアント側認証は、以下に当てはまるアプリに最適な認証方法です。 - 既存のBoxアカウントを持っているユーザーを使用する - ユーザーがBoxを使用していることを認識できるように、ID管理にBoxを使用する - アプリケーションのサービスアカウントではなく各ユーザーアカウント内にデータを保存する OAuth 2.0を使用したクライアント側認証を確認する ## サーバー側 ### JWT JSONウェブトークン (JWT) を使用するサーバー側認証では、エンドユーザーによる操作が必要ありません。また、適切な権限が付与されていれば、この認証方法を使用して、企業内の任意のユーザーの代理で操作することができます。IDの確認には、JWTアサーションおよび公開/秘密キーペアを使用します。 # JWTはいつ使用すべきですか? JWTを使用するサーバー側認証は、以下に当てはまるアプリに最適な認証方法です。 - Boxアカウントを持たないユーザーを使用する - 独自のIDシステムを使用する - Boxを使用していることをユーザーに認識させたくない - ユーザーのアカウントではなくアプリケーションのサービスアカウント内にデータを保存する JWTを使用したサーバー側認証を確認する ### クライアント資格情報許可 クライアント資格情報許可を使用するサーバー側認証では、エンドユーザーによる操作が必要ありません。また、適切な権限が付与されていれば、この認証方法を使用して、企業内の任意のユーザーの代理で操作することができます。IDの確認には、アプリケーションのクライアントIDとクライアントシークレットを使用します。 # クライアント資格情報許可はいつ使用すべきですか? クライアント資格情報許可を使用するサーバー側認証は、以下に当てはまるアプリに最適な認証方法です。 - Boxアカウントを持たないユーザーを使用する - 独自のID管理システムを使用する - Boxを使用していることをユーザーに認識させたくない - ユーザーのアカウントではなくアプリケーションのサービスアカウント内にデータを保存する クライアント資格情報許可を使用したサーバー側認証を確認する ### アプリトークン サーバー側アプリトークンは、アプリケーションに、それ自体のアカウントのデータに対する読み取りと書き込みのアクセス権限だけがある認証方法です。これは、主にBox Viewアプリケーションで使用されます。この認証方法を使用すると、アプリケーションはそのアプリケーションのサービスアカウントとして自動的に認証されるため、ユーザーを承認する必要がありません。 # アプリトークンはいつ使用すべきですか? アプリトークンを使用するサーバー側認証は、以下に当てはまるアプリに最適な認証方法です。 - ユーザーモデルがない環境、またはBoxアカウントを持たないユーザーがいる環境で使用する - 独自のID管理システムを使用する - Boxを使用していることをユーザーに認識させたくない - ユーザーのアカウントではなくアプリケーションのサービスアカウント内にデータを保存する アプリトークンを使用したサーバー側認証を確認する ## 比較 以下に、クライアント側とサーバー側の認証の主な違いの概要を示します。 | | OAuth 2.0 | JWT | クライアント資格情報 | アプリトークン | | --- | --- | --- | --- | --- | | ユーザーの関与が必要? | はい | いいえ | いいえ | いいえ | | 管理者の承認が必要? | いいえ | はい | はい | はい | | 他のユーザーの代理で操作可能? | はい | はい | はい | いいえ | | ユーザーにBoxを表示? | はい | いいえ | いいえ | いいえ | | App Userを作成可能? | いいえ | はい | はい | いいえ | アクセストークンは特定のBoxユーザーに関連付けられており、そのユーザーが誰であるかは、トークンがどのように取得されたかによって決まります。 たとえば、クライアント側認証を使用している場合、トークンは、自分のアカウントへのアクセス権限を付与したユーザーを表します。一方、サーバー側認証を使用している場合、トークンは、デフォルトでアプリケーションのサービスアカウントとなります。 **Source:** [https://ja.developer.box.com/guides/authentication/select/](https://ja.developer.box.com/guides/authentication/select/) --- ### 返信の作成 **Type:** guide | **Category:** コメント | **Section:** Developer Guides 返信の作成 以前のコメントへの返信を作成するには、新しいコメントのメッセージと、返信を残す以前のコメントのIDを指定してPOST /comments API… # 返信の作成 以前のコメントへの返信を作成するには、新しいコメントのメッセージと、返信を残す以前のコメントのIDを指定して[`POST /comments`](e://post_comments) APIを呼び出します。 返信のメッセージでは、`@`記号を使用してユーザーをメンションすることもできます。そのためには、メッセージ内の任意の場所に`@[userid:name]`という文字列を追加します。`user_id`はターゲットユーザーのIDで、`name`には任意のカスタムフレーズを使用できます。Box UIでは、この名前がユーザーのプロフィールにリンクされます。 次に、この文字列を`message`ではなく`tagged_message`として渡します。 **Source:** [https://ja.developer.box.com/guides/comments/create-reply/](https://ja.developer.box.com/guides/comments/create-reply/) --- ### 追加フィールドのリクエスト **Type:** guide | **Category:** APIコール | **Section:** Developer Guides 追加フィールドのリクエスト リソースに対して返されるフィールドの数は、リソースのリクエストに使用されるAPIエンドポイントに応じて異なります。 fields… # 追加フィールドのリクエスト リソースに対して返されるフィールドの数は、リソースのリクエストに使用されるAPIエンドポイントに応じて異なります。 ## fieldsクエリパラメータの使用 標準のレスポンスにデフォルトでは含まれない、リソースの特定のフィールドをリクエストするには、`fields`クエリパラメータをリクエストに追加します。このパラメータの値は、フィールド名のコンマ区切りリストです。 ``` curl https://api.box.com/2.0/files/12345?fields=is_package,lock \ -H "authorization: Bearer ACCESS_TOKEN" ``` ``` { "etag": "1", "id": "12345", "is_package": false, "lock": null, "type": "file" } ``` 特定のフィールドがリクエストされると、リクエストされたフィールドとフィールドの**基本**セット以外のフィールドが返されない点に注意してください。ファイルの場合、この基本セットは`etag`、`id`、および`type`値で構成されます。 ## リソースバリアント Box APIでは、以下のリソースバリアントを使用できます。 ### 標準 APIレスポンスで返されるデフォルトのフィールドセットです。Standardバリアントは、リソースに対して使用できるメインのAPIを介してそのリソースがリクエストされたときに返されます。たとえば、[`GET /files/:id`](endpoint://get_files_id)エンドポイントをリクエストすると、APIはファイルの標準バリエーションを返します。 ``` curl https://api.box.com/2.0/files/12345 \ -H "authorization: Bearer ACCESS_TOKEN" ``` ``` { "content_created_at": "2019-06-20T06:04:41-07:00", "content_modified_at": "2019-06-20T06:04:41-07:00", "created_at": "2019-06-20T07:28:42-07:00", "created_by": { "id": "191919191", "login": "joe@example.com", "name": "Joe Box", "type": "user" }, "description": "", "etag": "1", "file_version": { "id": "56663434454334", "sha1": "585afa5209bbd586c79499b7336601341ad06cce", "type": "file_version" }, "id": "12345", ... "size": 65000647, "trashed_at": null, "type": "file" } ``` ### Mini 別のレスポンスのネストされた部分としてリソースが返される場合は、サイズが縮小され、重要なフィールドの一部のみが返されることがよくあります。このバリアントは、一般にMiniリソースバリアントと呼ばれます。 たとえば、[`GET /folders/:id/items`](endpoint://get_folders_id_items)エンドポイントをリクエストすると、APIは`item_collection`内でネストされたファイルとフォルダの簡易バリエーションを返します。 ``` curl https://api.box.com/2.0/files/12345 \ -H "authorization: Bearer ACCESS_TOKEN" ``` ``` { "id": "0", "type": "folder", "item_collection": { "entries": [ { "etag": "1", "file_version": { "id": "56663434454334", "sha1": "585afa5209bbd586c79499b7336601341ad06cce", "type": "file_version" }, "id": "12345", "name": "Video.mp4", "sequence_id": "1", "sha1": "585afa5209bbd586c79499b7336601341ad06cce", "type": "file" } ... ] ... } ... } ``` ネストされたリソースの詳細をリクエストするには、そのリソースに対してAPIを呼び出して、IDでそのリソースをリクエストすることをお勧めします。その際、オプションで`field`クエリパラメータを渡すこともできます。 たとえば、フォルダ内の項目のリストを取得するときに返されるファイルの所有者を取得する場合は、クエリパラメータ`field=owned_by`を指定して、IDでそのファイルをリクエストします。 ### Full APIレスポンスで返すことができるフィールドセット全体です。Fullバリアントは、リソースに対して使用できるメインのAPIを介し、`fields`クエリパラメータを追加してそのリソースをリクエストしたときに返されます。 たとえば、`fields=is_package,lock`パラメータを指定して[`GET /files/:id`](endpoint://get_files_id)エンドポイントをリクエストすると、APIは、指定されたフィールドに加えて、そのファイルの基本的なフィールドを返します。 ``` curl https://api.box.com/2.0/files/12345?fields=is_package,lock \ -H "authorization: Bearer ACCESS_TOKEN" ``` ``` { "etag": "1", "id": "12345", "is_package": false, "lock": null, "type": "file" } ``` **Source:** [https://ja.developer.box.com/guides/api-calls/request-extra-fields/](https://ja.developer.box.com/guides/api-calls/request-extra-fields/) --- ### 追加フィールドのリクエスト **Type:** guide | **Category:** 検索 | **Section:** Developer Guides 追加フィールドのリクエスト デフォルトでは、検索APIによって標準形式のファイル、フォルダ、またはウェブリンクが返されます。これらの各リソースでは、fields… # 追加フィールドのリクエスト デフォルトでは、検索APIによって**標準**形式の[ファイル](r://file)、[フォルダ](r://folder)、または[ウェブリンク](r://web_link)が返されます。これらの各リソースでは、`fields`クエリパラメータを使用してリクエストできる追加のフィールドがサポートされています。 ``` curl -i -X GET "https://api.box.com/2.0/search?query=sales&fields=name,tags" \ -H "Authorization: Bearer <ACCESS_TOKEN>" ``` ``` long offsetValue = 0; long limitValue = 10; BoxSearch boxSearch = new BoxSearch(api); BoxSearchParameters searchParams = new BoxSearchParameters(); searchParams.setQuery("sales"); final List<String> fields = new ArrayList<String>(); fields.add("name"); fields.add("tags"); searchParams.setFields(fields) PartialCollection<BoxItem.Info> searchResults = boxSearch.searchRange(offsetValue, limitValue, searchParams); ``` ``` IEnumerable<string> fields = new List<string>() { "name", "tags"}; BoxCollection<BoxItem> results = await client.SearchManager .QueryAsync("sales", fields: fields); ``` ``` client.search().query("sales", metadata_filters=metadata_search_filters, fields=["name", "tags"]) ``` ``` client.search.query( 'sales', { fields: "name,tags" }) .then(results => { // ... }); ``` これらのフィールドの詳細については、[ファイル (詳細)](r://file--full)、[フォルダ (詳細)](r://folder--full)、および[ウェブリンク (詳細)](r://web_link) のリソースを確認してください。 `fields`パラメータを使用して、項目の追加情報をクエリで照会すると、これらのフィールドといくつかの**基本**フィールド (`id`、`type`、`name`など) のみが返されます。レスポンスに最初から含まれていたフィールドは、明示的にリクエストする必要があります。 **Source:** [https://ja.developer.box.com/guides/search/fields/](https://ja.developer.box.com/guides/search/fields/) --- ### 通常の検索との比較 **Type:** guide | **Category:** メタデータ | **Section:** Developer Guides 通常の検索との比較 一見、メタデータクエリAPIはコンテンツの検索APIとよく似ていますが、動作には重要な違いがいくつかあります。大まかに言うと、メタデータクエリAPI… # 通常の検索との比較 一見、[メタデータクエリAPI](e://post_metadata_queries_execute_read)は[コンテンツの検索API](e://get_search)とよく似ていますが、動作には重要な違いがいくつかあります。大まかに言うと、メタデータクエリAPIは正確さとスループットの向上のために最適化されているのに対し、通常の検索は、人間のユーザーとの関連度のために最適化されています。 ## 詳細な比較 | | メタデータクエリAPI | 検索API | | --- | --- | --- | | インデックスの作成対象 | このAPIでは、検索対象のメタデータテンプレートの値に基づいてファイル/フォルダのみが返されます。 | このAPIでは、項目名、説明、コンテンツ (最初の10,000バイトまで) の値のほか、関連付けられたメタデータテンプレートインスタンスに基づいてファイル、フォルダ、ウェブリンクが返されます。 | | インデックス作成時間 | このAPIでは、ファイルまたはフォルダのメタデータが追加、削除、更新されるとすぐに正確な結果が返されます。 | このAPIは、検索インデックスの作成が遅延すると、その影響を受けます。この遅延は通常10分ですが、場合によっては長くなることがあります。つまり、メタデータが更新されてから10分を経過しても項目が返されない場合があります。 | | 一致 | このAPIでは、SQLの規則に基づいて完全一致が使用されます。結果は、指定した並べ替え順を基に返されます。 | このAPIでは、あいまい一致が使用されるため、文字列のトークン化、特殊文字の削除、その他の検索コンセプトに基づいて異なる結果が返される場合があります。結果の順序は、項目の関連度または更新日に基づいています。 | | 条件付きロジック | このAPIは、比較演算子を使用するマルチパートブール式をサポートします。 | このAPIでは、メタデータによるクエリのサポートが限定的です。サポートされるのは、一度に1つのメタデータテンプレートに対するクエリのみで、単純なクエリ操作のみが可能です。 | | レスポンスタイプ | このAPIでは、一致したファイル/フォルダと、クエリによって一致した関連するメタデータの両方が返されます。 | このAPIで返されるのは、一致した項目のみです。各項目のメタデータを返すには、後続のAPIコールが必要です。 | | スループット (Throughput) | このAPIには現在、ユーザーごとのレート制限のほか、企業あたりのリクエスト数が10件/秒という制限があります。 | このAPIでは、1ユーザーあたりの検索数は6件/秒、企業あたりの検索数は最大60件/分および12件/秒がサポートされています。 | | 規模 | このAPIでは、指定したメタデータテンプレートを使用して返される項目数に制限はありません。一致する結果が2,000件以下になるクエリのみを送信することをお勧めします。 | このAPIには、指定したメタデータテンプレートを使用して返される項目数に制限はありません。ただし、検索に一致する項目数が増えるにつれ、レスポンス時間が大幅に増大します。このAPIでは、1つのクエリに対する結果は1,000万件までという制限があります。一致する結果が50,000件以下になるクエリのみを送信することをお勧めします。 | | スコープ | このAPIは常に、ユーザーがアクセスできるコンテンツに制限されています。 | このAPIは、ユーザーがアクセスできるコンテンツ (​user_content​) または社内のすべてのコンテンツ (​enterprise_content​) のいずれかに制限される場合があります。 | 一致する結果が10,000件を超える検索APIコールにより、関連度が多少変化することがあります。そのため、結果が重複する場合や結果が返されない場合があります。大規模なデータセットでは、検索を完全一致のソリューションと考えないでください。 ## シナリオ 使用するAPIを決定する際に役立つシナリオの例を以下に示します。 ### 企業全体を対象にして用語を検索する キーワード`Guarantee`に一致するコンテンツまたはメタデータを持つすべてのコンテンツを社内で検索します。 この場合は、[検索API](e://get_search)をお勧めします。このAPIでは、コンテンツとメタデータの両方で用語を照合し、対象範囲を企業全体のすべてのコンテンツに設定できます。 ### 複数のメタデータ値を検索する メタデータテンプレート`​Contract​`を使用して、金額が100,000ドルを超過し、更新日が2019年で、アカウント番号`​1234`に関連付けられていないすべてのドキュメントを検索します。 この場合は、[メタデータクエリAPI](e://post_metadata_queries_execute_read)をお勧めします。メタデータクエリを使用すると、数値、日付、文字列など、メタデータテンプレート内の複数のフィールドを評価するブール式を作成できます。 ### メタデータ検索とコンテンツ検索を組み合わせる メタデータテンプレート`​Contract​`を使用して、金額が100,000ドルを超過し、更新日が2019年で、タイトルや本文に「Sale」という用語が含まれておらず、アカウント番号`​1234`に関連付けられていないすべてのドキュメントを検索します。 このシナリオは、現在**サポートされていません**。現時点では、どちらのAPIも、あいまい検索 (「Sale」の検索) と、メタデータフィールドに一致するブール式の組み合わせをサポートしていません。 **Source:** [https://ja.developer.box.com/guides/metadata/queries/comparison/](https://ja.developer.box.com/guides/metadata/queries/comparison/) --- ### 通知の抑制 **Type:** guide | **Category:** APIコール | **Section:** Developer Guides 通知の抑制 一部のAPIコールでは、APIコールにbox-notifications: offヘッダーを指定することで、メール通知およびWebhook… # 通知の抑制 一部のAPIコールでは、APIコールに`box-notifications: off`ヘッダーを指定することで、メール通知およびWebhook通知をブロックできます。 ``` curl -X POST https://api.box.com/2.0/folders \ -H "box-notifications: off" \ -H "authorization: Bearer ACCESS_TOKEN" \ -d '{ "name": "New Folder", "parent": { "id": "0" } }' ``` たとえば、これをウイルススキャンツールに使用すると、社内でユーザーのファイルのコピーをダウンロードするたびに、そのファイルのすべてのコラボレータにダウンロードに関する通知メールが届くことはなくなります。 この場合でも、すべてのアクションがユーザーの更新フィードと監査ログに表示されます。 # スコープの要件 通知の抑制は、承認されたアプリケーションでのみ使用できます。アプリケーションに対して有効にする必要なスコープをリクエストするには、サポートにお問い合わせください。 この機能を正しく動作させるには、アプリケーションに対して以下の設定を構成する必要があります。 - **[APIコールからメール通知を抑制する]** - サポート経由のリクエストで対応可能 - **[Enterpriseのプロパティを管理する]** - 開発者コンソールから使用可能 - **[会社の設定を編集する]** の共同管理者権限 一部の通知は抑制できません。その代表として、ユーザー、コメント、コラボレーション、タスク割り当ての作成のほか、ユーザーのログインの変更時があります。 **Source:** [https://ja.developer.box.com/guides/api-calls/suppress-notifications/](https://ja.developer.box.com/guides/api-calls/suppress-notifications/) --- ### 開発者トークン **Type:** guide | **Category:** 認証 | **Section:** Developer Guides 開発者トークン 開発者トークンは、開発およびテスト中に開発者が利用できるアクセストークンです。これらのトークンは6… # 開発者トークン 開発者トークンは、開発およびテスト中に開発者が利用できるアクセストークンです。これらのトークンは60分後に期限切れになる有効期間の短いトークンであり、プログラムによって更新することはできません。 ## 開発者トークンの作成 アプリケーション用に開発者トークンを作成するには: - Box[開発者コンソール](https://app.box.com/developers/console)に移動し、開発者トークンの作成対象となるアプリケーションを選択します。 - [**構成**] タブを選択します。 - [開発者トークン] で、[**開発者トークンを生成**] を選択します。 [[Platformアプリ](g://applications)] ビューから直接、各アプリに用意されているメニューを使用して、開発者トークンを生成することもできます。 ## 開発者トークンの使用 開発者トークンは、さまざまなアクセストークンと同様、APIコールの`Authorization`ヘッダーで使用できます。 ``` curl https://api.box.com/2.0/users/me \ -H "authorization: Bearer [DEVELOPER_TOKEN]" ``` 開発者トークンは、トークンの生成時に開発者コンソールにログインしているユーザーに関連付けられます。 Box SDKは、基本のAPIクライアントを作成する際に、開発者トークンを使用して初期化することができます。 # 開発者トークンは実稼働環境で使用しないでください 開発者トークンは、開発またはテストのためだけに使用してください。 開発者コンソールで特定のアプリの開発者トークンを明示的に取り消すと、そのアプリケーションによって作成されたすべてのWebhookが削除されます。 ## SDKと開発者トークンの使用 各SDKの開発者トークンの詳細については、以下を参照してください。 [.Net](https://github.com/box/box-windows-sdk-v2/blob/main/docs/authentication.md#developer-token) [Java](https://github.com/box/box-java-sdk/blob/main/doc/authentication.md#developer-token) [Python](https://github.com/box/box-python-sdk/blob/main/docs/usage/authentication.md#developer-token) [Node](https://github.com/box/box-node-sdk/blob/main/docs/authentication.md#developer-token) [IOS](https://github.com/box/box-ios-sdk/blob/main/docs/usage/authentication.md#developer-token) **Source:** [https://ja.developer.box.com/guides/authentication/tokens/developer-tokens/](https://ja.developer.box.com/guides/authentication/tokens/developer-tokens/) --- ### 非アクティブなユーザーのレポート **Type:** guide | **Category:** CLI | **Section:** Developer Guides 非アクティブなユーザーのレポート このスクリプトは、一定の日数の間非アクティブであったユーザーのリストをCSVファイルで生成します。スクリプトによって以下の手順が実行されます。 userロールを持つユーザーを探します。 このスクリプトでは、他のロール (AppUser… # 非アクティブなユーザーのレポート このスクリプトは、一定の日数の間非アクティブであったユーザーのリストをCSVファイルで生成します。スクリプトによって以下の手順が実行されます。 `user`ロールを持つユーザーを探します。 このスクリプトでは、他のロール (`AppUser`など) は考慮していません。 [Box Events](resource://event)を使用して、そのユーザーが一定の日数の間に操作を行ったかどうかを確認します。デフォルトのイベントタイプのリストは、`LOGIN`、`UPLOAD`、`COPY`、`MOVE`、`PREVIEW`、`DOWNLOAD`、`EDIT`、`DELETE`、`UNDELETE`、`LOCK`、`UNLOCK`、`NEW_USER`です。このリストはスクリプトの設定で変更できます。 操作を行わなかったユーザーを、非アクティブなユーザーが含まれている`.csv`ファイルに追加します。このファイルは他のスクリプト ([ユーザーのプロビジョニング解除](g://cli/scripts/deprovision-users)など) の入力として使用できます。 ## 前提条件 ### Windows [.NET Core](https://dotnet.microsoft.com/download)の最新バージョンのインストール ### macOSおよびLinux [PowerShell](https://docs.microsoft.com/en-us/powershell/scripting/install/installing-powershell?view=powershell-7.2)をインストールします。`pwsh`コマンドを実行して、インストール結果をテストします。 ``` pwsh ``` どのディレクトリでこのコマンドを実行するかに応じて、出力が異なる場合があります。以下に例を示します。 ``` PowerShell 7.2.5 Copyright (c) Microsoft Corporation. https://aka.ms/powershell Type 'help' to get help. PS /Users/user/repos/boxcli/examples> ``` 問題が発生する場合は、[.NET Core](https://dotnet.microsoft.com/download)と[PowerShell](https://docs.microsoft.com/en-us/powershell/scripting/install/installing-powershell?view=powershell-7.2)の両方をインストールしたかどうか確認してください。 ### Box CLI スクリプトを使用するには、Box CLIをインストールし、構成する必要があります。これは、[クイックスタートガイド](g://cli/quick-start/create-oauth-app)の手順を実行することで行うことができます。ログインに使用するユーザーは、Boxのメイン管理者または共同管理者である必要があります。 ## スクリプトの構成 1. `boxcli` GitHubリポジトリを複製してこの例のフォルダにcdコマンドで移動するか、[`examples`](https://github.com/box/boxcli/tree/main/examples/Inactive%20Users%20Report)ディレクトリからファイルをダウンロードします。 ``` git clone https://github.com/box/boxcli.git cd boxcli/examples/Inactive\ Users\ Report/ ``` 1. スクリプトでUser Eventをスキャンする日数を設定します。この値を指定しなかった場合やデフォルト設定のままにした場合は、スクリプトによって入力するよう求められます。 ``` $daysInactive = "10" ``` 1. (省略可) レポート出力ファイル名を変更するには、`ReportOutputFile`パラメータを定義します。 ``` $ReportOutputFile = $ReportName + ".csv" ``` 1. (省略可) イベントタイプを変更するには、`eventType`パラメータのリストを定義します。 ``` $eventType = "LOGIN,UPLOAD,COPY,MOVE" ``` ## スクリプトの実行 PowerShellコマンドを実行します。 ``` pwsh ``` スクリプトを実行します。 ``` ./Inactive_Users_Report.ps1 ``` スクリプトの実行が完了すると、以下のような出力が表示されます。 ``` Looking for users inactive for more than 3 days. Found 6 users. Found 7 events in last 3 days Enterprise has: 0 App user, 6 regular users. With 1 admin role, 5 user roles. Need to check 5 users (regular user, with user role) for inactive. Found 5 users inactive for more than 3 days. Report is available at InactiveUsers.csv ``` ## ログ ログは、メインフォルダ内の`logs`フォルダに格納されます。以下のログファイルにアクセスできます。 - `Inactive_Users_Report_all.txt`: すべてのログエントリが含まれています。 - `Inactive_Users_Report_errors.txt`: エラーのみが含まれています。 **Source:** [https://ja.developer.box.com/guides/cli/scripts/report-inactive-users/](https://ja.developer.box.com/guides/cli/scripts/report-inactive-users/) --- ### 項目からのメタデータの削除 **Type:** guide | **Category:** メタデータ | **Section:** Developer Guides 項目からのメタデータの削除 ファイルまたはフォルダに割り当てられたメタデータテンプレートのインスタンスを削除するには、項目のidに加え、テンプレートのtemplateKeyとscopeを使用します。 メタデータのスコープには、global… # 項目からのメタデータの削除 ファイルまたはフォルダに割り当てられたメタデータテンプレートのインスタンスを削除するには、項目の`id`に加え、テンプレートの`templateKey`と`scope`を使用します。 メタデータの[スコープ](g://metadata/scopes)には、`global` (すべての会社が利用できるテンプレートの場合)、`enterprise` (現在の会社が利用できるテンプレートの場合)、または`enterprise_:id` (IDがスコープ名の`:id`である会社に属するテンプレートの場合) のいずれかを指定できます。 ## ファイルからメタデータを削除 ファイルからメタデータテンプレートのインスタンスを削除するには、[`DELETE /files/:file_id/metadata/:templateKey/schema`](e://delete_files_id_metadata_id_id) APIを呼び出します。 ファイルからインスタンスが正常に削除されている場合、このAPIは、レスポンスの本文がない`204 No Content` APIレスポンスを返します。 ## フォルダからメタデータを削除 フォルダからメタデータテンプレートのインスタンスを削除するには、[`DELETE /folders/:folder_id/metadata/:templateKey/schema`](e://delete_folders_id_metadata_id_id) APIを呼び出します。 フォルダからインスタンスが正常に削除されている場合、このAPIは、レスポンスの本文がない`204 No Content` APIレスポンスを返します。 **Source:** [https://ja.developer.box.com/guides/metadata/instances/delete/](https://ja.developer.box.com/guides/metadata/instances/delete/) --- ### 項目のすべてのメタデータのリストの取得 **Type:** guide | **Category:** メタデータ | **Section:** Developer Guides 項目のすべてのメタデータのリストの取得 ファイルまたはフォルダのメタデータインスタンスのリストを取得できます。 ファイルのメタデータのリストを取得 ファイルのすべてのメタデータインスタンスのリストを取得するには、GET /files/:file_id/metadata API… # 項目のすべてのメタデータのリストの取得 ファイルまたはフォルダのメタデータインスタンスのリストを取得できます。 ## ファイルのメタデータのリストを取得 ファイルのすべてのメタデータインスタンスのリストを取得するには、[`GET /files/:file_id/metadata`](e://get_files_id_metadata) APIエンドポイントを呼び出します。 このAPIはページングをサポートしておらず、常にこのファイルのすべてのメタデータインスタンスを返します。 ## フォルダのメタデータのリストを取得 任意のフォルダ (ルートフォルダを除く) のすべてのメタデータインスタンスのリストを取得するには、[`GET /folders/:file_id/metadata`](e://get_files_id_metadata) APIエンドポイントを呼び出します。 このAPIはページングをサポートしておらず、常にこのファイルのすべてのメタデータインスタンスを返します。このAPIは、IDが`0`のルートフォルダには使用できません。 **Source:** [https://ja.developer.box.com/guides/metadata/instances/list/](https://ja.developer.box.com/guides/metadata/instances/list/) --- ### 項目のメタデータの取得 **Type:** guide | **Category:** メタデータ | **Section:** Developer Guides 項目のメタデータの取得 ファイルまたはフォルダに割り当てられたメタデータテンプレートのインスタンスに関する情報を取得するには、項目のidに加え、テンプレートのtemplateKeyとscopeを使用します。 メタデータのスコープには、global… # 項目のメタデータの取得 ファイルまたはフォルダに割り当てられたメタデータテンプレートのインスタンスに関する情報を取得するには、項目の`id`に加え、テンプレートの`templateKey`と`scope`を使用します。 メタデータの[スコープ](g://metadata/scopes)には、`global` (すべての会社が利用できるテンプレートの場合)、`enterprise` (現在の会社が利用できるテンプレートの場合)、または`enterprise_:id` (IDがスコープ名の`:id`である会社に属するテンプレートの場合) のいずれかを指定できます。 ## ファイルのメタデータインスタンスを取得 ファイルのメタデータテンプレートのインスタンスを取得するには、ファイルの`file_id`およびテンプレートの`scope`と`templateKey`を指定して、[`GET /files/:file_id/metadata/:scope/:templateKey`](e://get_files_id_metadata_id_id) APIエンドポイントを呼び出します。 テンプレートの`scope`と`templateKey`を取得するには、[すべてのメタデータテンプレートのリストを取得](g://metadata/templates/list)するか、[ファイルのすべてのインスタンスのリストを取得](g://metadata/instances/list)します。 ## フォルダのメタデータインスタンスを取得 フォルダのメタデータテンプレートのインスタンスを取得するには、フォルダの`folder_id`およびテンプレートの`scope`と`templateKey`を指定して、[`GET /folders/:folder_id/metadata/:scope/:templateKey`](e://get_files_id_metadata_id_id) APIエンドポイントを呼び出します。 テンプレートの`scope`と`templateKey`を取得するには、[すべてのメタデータテンプレートのリストを取得](g://metadata/templates/list)するか、[フォルダのすべてのインスタンスのリストを取得](g://metadata/instances/list)します。 **Source:** [https://ja.developer.box.com/guides/metadata/instances/get/](https://ja.developer.box.com/guides/metadata/instances/get/) --- ### 項目のメタデータの更新 **Type:** guide | **Category:** メタデータ | **Section:** Developer Guides 項目のメタデータの更新 ファイルまたはフォルダに適用されたメタデータを更新するには、項目のid、テンプレートのtemplateKeyとscopeに加え、テンプレートインスタンスのデータを操作するための一連のJSON… # 項目のメタデータの更新 ファイルまたはフォルダに適用されたメタデータを更新するには、項目の`id`、テンプレートの`templateKey`と`scope`に加え、テンプレートインスタンスのデータを操作するための一連のJSON操作を使用します。 ## ファイルのメタデータの更新 ファイルのメタデータを更新するには、ファイルの`file_id`、テンプレートの`scope`と`templateKey`、およびテンプレートインスタンスのデータを操作するための一連のJSON操作を指定して[`PUT /files/:file_id/metadata/:scope/:templateKey`](e://put_files_id_metadata_id_id) APIエンドポイントを呼び出します。 認証済みユーザーがファイルのメタデータに対する変更を書き込めるようにするには、ファイルへの書き込みアクセス権限が必要です。 ## フォルダのメタデータを更新 フォルダのメタデータを更新するには、フォルダの`folder_id`、テンプレートの`scope`と`templateKey`、およびテンプレートインスタンスのデータを操作するための一連のJSON操作を指定して[`PUT /folders/:folder_id/metadata/:scope/:templateKey`](e://put_folders_id_metadata_id_id) APIエンドポイントを呼び出します。 認証済みユーザーがファイルのメタデータに対する変更を書き込めるようにするには、ファイルへの書き込みアクセス権限が必要です。 ## JSON操作 メタデータを更新する場合は、[JSON-Patchの仕様](https://tools.ietf.org/html/rfc6902)に従う必要があります。これは、操作オブジェクトのリストとして表されます。 メタデータインスタンスの場合、これらの操作には`add`、`replace`、`remove`、`test`、`move`、`copy`のいずれかを指定できます。どの操作も、`op`の名前、変更対象のフィールドを指す[JSON Pointer](https://tools.ietf.org/html/rfc6901) `path`のほか、実行される操作に応じた`value`または`from`値 (省略可) で構成されます。 ``` [ { "op": "test", "path": "/competitiveDocument", "value": "no" }, { "op": "remove", "path": "/competitiveDocument" }, { "op": "test", "path": "/status", "value": "active" }, { "op": "replace", "path": "/status", "value": "inactive" }, { "op": "test", "path": "/author", "value": "Jones" }, { "op": "copy", "from": "/author", "path": "/editor" }, { "op": "move", "from": "/currentState", "path": "/previousState" }, { "op": "add", "path": "/currentState", "value": "reviewed" } ] ``` メタデータを編集する際には、メタデータテンプレートのスキーマに準拠した値のみを使用できます。更新は完全に適用されるか、まったく適用されないかのどちらかです。更新操作の適用中にエラーが発生した場合、メタデータインスタンスは変更されません。 テンプレートインスタンスを更新できるのは、テンプレートがすでにファイルまたはフォルダに割り当てられている場合のみです。 ### 新しい値の追加 テンプレートに新しい値を追加するには、`add`操作を使用します。 ``` [ { "op": "add", "path": "/name", "value": "Model 3" } ] ``` これにより、値が`Model 3`の`name`フィールドが追加されます。この操作の前は、テンプレートの`name`フィールドに値がありませんでした。 ``` { // "name": null, // old value "name": "Model 3", // new value "category": "SUVs", "$type": "productInfo-8120731a-41e4-11ea-b77f-2e728ce88125", "$parent": "folder_3456", "$id": "22ba8c96-41e6-11ea-b77f-2e728ce88125", "$version": 3, "$typeVersion": 0, "$template": "productInfo", "$scope": "enterprise_1234567", "$canEdit": true } ``` `enum`および`multiSelect`フィールドの場合、この新しい値には、そのフィールドに有効なオプションのいずれかを指定する必要があります。 ### 値の置き換え テンプレート上の値を置き換えるには、`replace`操作を使用します。 ``` [ { "op": "replace", "path": "/name", "value": "Model 4" } ] ``` これにより、`name`フィールドの値`Model 3`が新しい値`Model 4`に置き換えられます。 ``` { // "name": "Model 3", # Old value "name": "Model 3", // new value "category": "SUVs", "$type": "productInfo-8120731a-41e4-11ea-b77f-2e728ce88125", "$parent": "folder_3456", "$id": "22ba8c96-41e6-11ea-b77f-2e728ce88125", "$version": 3, "$typeVersion": 0, "$template": "productInfo", "$scope": "enterprise_1234567", "$canEdit": true } ``` `enum`および`multiSelect`フィールドの場合、この新しい値には、そのフィールドに有効なオプションのいずれかを指定する必要があります。 ### 値のコピー 値をあるフィールドから別のフィールドにコピーするには、`copy`操作を使用します。 ``` [ { "op": "copy", "from": "/name", "path": "/displayName" } ] ``` これにより、`name`フィールドの値と一致する値が設定された`displayName`フィールドが追加されます。この操作の前は、テンプレートの`displayName`フィールドに値がありませんでした。 ``` { "name": "Model 3", "displayName": "Model 3", // new value, copied from the name "category": "SUVs", "$type": "productInfo-8120731a-41e4-11ea-b77f-2e728ce88125", "$parent": "folder_3456", "$id": "22ba8c96-41e6-11ea-b77f-2e728ce88125", "$version": 3, "$typeVersion": 0, "$template": "productInfo", "$scope": "enterprise_1234567", "$canEdit": true } ``` `enum`および`multiSelect`フィールドの場合、この新しい値には、そのフィールドに有効なオプションのいずれかを指定する必要があります。 ### 値の移動 値をあるフィールドから別のフィールドに移動するには、`move`操作を使用します。 ``` [ { "op": "copy", "from": "/name", "path": "/displayName" } ] ``` これにより、`name`フィールドの値と一致する値が設定された`displayName`フィールドが追加されます。この操作の前は、テンプレートの`displayName`フィールドに値がありませんでした。この操作の後、`name`フィールドはすでに存在しません。 ``` { // "name": "Model 3", // old value, no longer present now "displayName": "Model 3", // new value, copied from the name "category": "SUVs", "$type": "productInfo-8120731a-41e4-11ea-b77f-2e728ce88125", "$parent": "folder_3456", "$id": "22ba8c96-41e6-11ea-b77f-2e728ce88125", "$version": 3, "$typeVersion": 0, "$template": "productInfo", "$scope": "enterprise_1234567", "$canEdit": true } ``` `enum`および`multiSelect`フィールドの場合、この新しい値には、そのフィールドに有効なオプションのいずれかを指定する必要があります。 ### 値の削除 メタデータインスタンスから値を削除するには、`remove`操作を使用します。 ``` [ { "op": "remove", "path": "/name" } ] ``` これにより、`name`フィールドがメタデータインスタンスから完全に削除されます。 ``` { // "name": "Model 3", // old value, no longer present now "category": "SUVs", "$type": "productInfo-8120731a-41e4-11ea-b77f-2e728ce88125", "$parent": "folder_3456", "$id": "22ba8c96-41e6-11ea-b77f-2e728ce88125", "$version": 3, "$typeVersion": 0, "$template": "productInfo", "$scope": "enterprise_1234567", "$canEdit": true } ``` `enum`および`multiSelect`フィールドの場合、この新しい値には、そのフィールドに有効なオプションのいずれかを指定する必要があります。 ### 値のテスト フィールドに期待する値が設定されていることをテストするには、`test`操作を使用します。 ``` [ { "op": "test", "path": "/name", "value": "Model 4" } ] ``` テストに失敗すると、APIはいずれの操作も実行せず、次のエラーとともにHTTPステータス`409 Conflict`を返します。 ``` { "message": "value differs from expectations", "code": "failed_json_patch_application", "request_id": "bzxgr1gbcq5h67pj" } ``` この操作の主な目的は、何らかの操作が実行される前に、メタデータインスタンスの値が予想どおりであることを確認することです。Box APIでは、変更がすべて実行されるかまったく実行されないかのいずれかであるため、テストの失敗は、変換が適用される前にすべての値が予想どおりかどうかを確認するのに非常に役立ちます。 **Source:** [https://ja.developer.box.com/guides/metadata/instances/update/](https://ja.developer.box.com/guides/metadata/instances/update/) --- ### 項目へのメタデータの適用 **Type:** guide | **Category:** メタデータ | **Section:** Developer Guides 項目へのメタデータの適用 メタデータテンプレートは、項目のid、テンプレートのtemplateKeyとscope、およびテンプレート内の各フィールドの値のセットを使用してファイルまたはフォルダに適用できます。 メタデータのスコープには、global… # 項目へのメタデータの適用 メタデータテンプレートは、項目の`id`、テンプレートの`templateKey`と`scope`、およびテンプレート内の各フィールドの値のセットを使用してファイルまたはフォルダに適用できます。 メタデータの[スコープ](g://metadata/scopes)には、`global` (すべての会社が利用できるテンプレートの場合)、`enterprise` (現在の会社が利用できるテンプレートの場合)、または`enterprise_:id` (IDがスコープ名の`:id`である会社に属するテンプレートの場合) のいずれかを指定できます。 特定のファイルまたはフォルダには最大100個のテンプレートを割り当てることができます。 ## ファイルへのメタデータの適用 メタデータテンプレートのインスタンスをファイルに適用するには、ファイルの`file_id`、テンプレートの`scope`と`templateKey`、および必要に応じてテンプレート内の各[フィールド](g://metadata/fields)の値のセットを指定して[`POST /files/:file_id/metadata/:scope/:templateKey`](e://post_files_id_metadata_id_id) APIエンドポイントを呼び出します。 テンプレートの`scope`と`templateKey`を取得するには、[すべてのメタデータテンプレートのリストを取得](g://metadata/templates/list)するか、[ファイルのすべてのインスタンスのリストを取得](g://metadata/instances/list)します。 ## タプルがすでに存在することを示すエラー 指定されたメタデータテンプレートでこのファイルにすでにメタデータが適用されている場合、エラーコード`tuple_already_exists`でエラーが返されます。この場合は、インスタンスを[代わりに更新する](g://metadata/instances/update)必要があります。 ## フォルダにメタデータを適用 メタデータテンプレートのインスタンスをフォルダに適用するには、フォルダの`folder_id`、テンプレートの`scope`と`templateKey`、および必要に応じてテンプレート内の各[フィールド](g://metadata/fields)の値のセットを指定して[`POST /folders/:folder_id/metadata/:scope/:templateKey`](e://post_folders_id_metadata_id_id) APIエンドポイントを呼び出します。 テンプレートの`scope`と`templateKey`を取得するには、[すべてのメタデータテンプレートのリストを取得](g://metadata/templates/list)するか、[フォルダのすべてのインスタンスのリストを取得](g://metadata/instances/list)します。 ## タプルがすでに存在することを示すエラー 指定されたメタデータテンプレートでこのフォルダにすでにメタデータが適用されている場合、エラーコード`tuple_already_exists`でエラーが返されます。この場合は、インスタンスを[代わりに更新する](g://metadata/instances/update)必要があります。 ## リクエスト本文 リクエストの本文には、テンプレート内の各[フィールド](g://metadata/fields)の値を含めることができます。テンプレートに存在するフィールドを調べるには、[メタデータテンプレートを調査](g://metadata/templates/get)してください。 たとえば、次のテンプレートについて考えましょう。 ``` { "id": "8120731a-41e4-11ea-b77f-2e728ce88125", "type": "metadata_template", "templateKey": "productInfo", "scope": "enterprise_1234567", "displayName": "Product Info", "hidden": false, "copyInstanceOnItemCopy": true, "fields": [ { "id": "feed71de-41e5-11ea-b77f-2e728ce88125", "type": "string", "key": "name", "displayName": "Name", "hidden": false }, { "id": "02b36bb6-41e6-11ea-b77f-2e728ce88125", "type": "enum", "key": "category", "displayName": "Category", "hidden": false, "options": [ { "id": "06a7bcc2-41e6-11ea-b77f-2e728ce88125", "key": "SUVs" }, { "id": "0a50df02-41e6-11ea-b77f-2e728ce88125", "key": "Saloons" }, { "id": "0e466be0-41e6-11ea-b77f-2e728ce88125", "key": "Cabriolets" } ] } ] } ``` このテンプレートには、2つの[テンプレートフィールド](g://metadata/fields)として`name`と`category`があります。`name`フィールドは通常のテキストフィールドで、`category`は列挙型フィールドです。 このテンプレートをファイルまたはフォルダに割り当てるリクエストの本文には、テンプレートの任意のフィールドの値を含めることができます。本文にフィールドも値も含めないことも可能です。 この場合、次のリクエスト本文は有効な例です。 ``` { "name": "Model 3", "category": "SUVs" } ``` キー`properties`を使用してスコープが`global`に設定されたテンプレートは例外で、テンプレートに任意のデータを割り当てることができます。このテンプレートを使用すると、一連のキー/値ペアをテンプレートに割り当てることができます。 この例の`category`フィールドは`enum`フィールドで、このフィールドで使用できるオプションのいずれかを指定する必要があります。 **Source:** [https://ja.developer.box.com/guides/metadata/instances/create/](https://ja.developer.box.com/guides/metadata/instances/create/) --- ## API Reference ### AI LLMエンドポイントパラメータ (AWS) **Type:** resource | **Category:** api-resource | **Section:** API Reference AI LLMエンドポイントパラメータ (AWS) オブジェクト。 # AI LLMエンドポイントパラメータ (AWS) AI LLMエンドポイントパラメータ (AWS) オブジェクト。 --- ### AI LLMエンドポイントパラメータ (Google) **Type:** resource | **Category:** api-resource | **Section:** API Reference AI LLMエンドポイントパラメータ (Google) オブジェクト。 # AI LLMエンドポイントパラメータ (Google) AI LLMエンドポイントパラメータ (Google) オブジェクト。 --- ### AI LLMエンドポイントパラメータ (IBM) **Type:** resource | **Category:** api-resource | **Section:** API Reference AI LLMエンドポイントパラメータ (IBM) オブジェクト。 # AI LLMエンドポイントパラメータ (IBM) AI LLMエンドポイントパラメータ (IBM) オブジェクト。 --- ### AI LLMエンドポイントパラメータ (OpenAI) **Type:** resource | **Category:** api-resource | **Section:** API Reference AI LLMエンドポイントパラメータ (OpenAI) オブジェクト。 # AI LLMエンドポイントパラメータ (OpenAI) AI LLMエンドポイントパラメータ (OpenAI) オブジェクト。 --- ### AIエージェント **Type:** resource | **Category:** api-resource | **Section:** API Reference AIエージェントインスタンスのStandard版の表示。 # AIエージェント AIエージェントインスタンスのStandard版の表示。 --- ### AIエージェント (Full) **Type:** resource | **Category:** api-resource | **Section:** API Reference AIエージェントインスタンスのFull版の表示。 # AIエージェント (Full) AIエージェントインスタンスのFull版の表示。 --- ### AIエージェントのデフォルト構成を取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-ai-agent-default/ **Source:** [https://ja.developer.box.com/reference/get-ai-agent-default/](https://ja.developer.box.com/reference/get-ai-agent-default/) --- ### AIエージェントのリスト **Type:** resource | **Category:** api-resource | **Section:** API Reference ページ割りを使用したAIエージェントのリスト。 # AIエージェントのリスト ページ割りを使用したAIエージェントのリスト。 --- ### AIエージェントのリストを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-ai-agents/ **Source:** [https://ja.developer.box.com/reference/get-ai-agents/](https://ja.developer.box.com/reference/get-ai-agents/) --- ### AIエージェントの参照 **Type:** resource | **Category:** api-resource | **Section:** API Reference クエリの処理に使用されるAIエージェント。 # AIエージェントの参照 クエリの処理に使用されるAIエージェント。 --- ### AIエージェントの機能 (テキスト生成) **Type:** resource | **Category:** api-resource | **Section:** API Reference テキストの生成に使用するAIエージェント。 # AIエージェントの機能 (テキスト生成) テキストの生成に使用するAIエージェント。 --- ### AIエージェントの機能 (テキスト生成リクエスト) **Type:** resource | **Category:** api-resource | **Section:** API Reference テキストの生成に使用するAIエージェント。 # AIエージェントの機能 (テキスト生成リクエスト) テキストの生成に使用するAIエージェント。 --- ### AIエージェントの機能 (抽出) **Type:** resource | **Category:** api-resource | **Section:** API Reference メタデータ抽出に使用するAIエージェント。 # AIエージェントの機能 (抽出) メタデータ抽出に使用するAIエージェント。 --- ### AIエージェントの機能 (抽出リクエスト) **Type:** resource | **Category:** api-resource | **Section:** API Reference メタデータ抽出に使用するAIエージェント。 # AIエージェントの機能 (抽出リクエスト) メタデータ抽出に使用するAIエージェント。 --- ### AIエージェントの機能 (質問) **Type:** resource | **Category:** api-resource | **Section:** API Reference 質問に使用するAIエージェント。 # AIエージェントの機能 (質問) 質問に使用するAIエージェント。 --- ### AIエージェントの機能 (質問リクエスト) **Type:** resource | **Category:** api-resource | **Section:** API Reference クエリの処理に使用するAIエージェント。 # AIエージェントの機能 (質問リクエスト) クエリの処理に使用するAIエージェント。 --- ### AIエージェントを作成 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/post-ai-agents/ **Source:** [https://ja.developer.box.com/reference/post-ai-agents/](https://ja.developer.box.com/reference/post-ai-agents/) --- ### AIエージェントを削除 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/delete-ai-agents-id/ **Source:** [https://ja.developer.box.com/reference/delete-ai-agents-id/](https://ja.developer.box.com/reference/delete-ai-agents-id/) --- ### AIエージェントを更新 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/put-ai-agents-id/ **Source:** [https://ja.developer.box.com/reference/put-ai-agents-id/](https://ja.developer.box.com/reference/put-ai-agents-id/) --- ### AIによる抽出 (構造化) のレスポンス **Type:** resource | **Category:** api-resource | **Section:** API Reference AIによる抽出 (構造化) のレスポンス。 # AIによる抽出 (構造化) のレスポンス AIによる抽出 (構造化) のレスポンス。 --- ### AIによる抽出のレスポンス **Type:** resource | **Category:** api-resource | **Section:** API Reference AIによる抽出のレスポンス。このレスポンスのコンテンツは、リクエストされた構成に応じて異なる場合があります。 # AIによる抽出のレスポンス AIによる抽出のレスポンス。このレスポンスのコンテンツは、リクエストされた構成に応じて異なる場合があります。 --- ### AIの応答 **Type:** resource | **Category:** api-resource | **Section:** API Reference AIの応答。 # AIの応答 AIの応答。 --- ### AIの応答 (Full) **Type:** resource | **Category:** api-resource | **Section:** API Reference AIの質問への応答。 # AIの応答 (Full) AIの質問への応答。 --- ### AppItemイベントソース **Type:** resource | **Category:** api-resource | **Section:** API Reference イベントストリーム内のイベントをトリガーしたAppItem。 # AppItemイベントソース イベントストリーム内のイベントをトリガーしたAppItem。 --- ### Archive **Type:** resource | **Category:** api-resource | **Section:** API Reference アーカイブとは、冗長なコンテンツ、古くなったコンテンツ、または重要でないコンテンツの保存専用のフォルダです。アーカイブ内のコンテンツには、その所有者とコラボレータはアクセスできません。この機能を使用するには、Boxアプリケーションに対してGCMスコープをリクエストする必要があります。 # Archive アーカイブとは、冗長なコンテンツ、古くなったコンテンツ、または重要でないコンテンツの保存専用のフォルダです。アーカイブ内のコンテンツには、その所有者とコラボレータはアクセスできません。この機能を使用するには、Boxアプリケーションに対してGCMスコープをリクエストする必要があります。 --- ### Archives **Type:** resource | **Category:** api-resource | **Section:** API Reference アーカイブのリスト。 # Archives アーカイブのリスト。 --- ### Box Doc Genジョブ **Type:** resource | **Category:** api-resource | **Section:** API Reference Box Doc GenジョブのStandard版の表示。 # Box Doc Genジョブ Box Doc GenジョブのStandard版の表示。 --- ### Box Doc Genジョブ **Type:** resource | **Category:** api-resource | **Section:** API Reference 標準のパラメータのセットを含むBox Doc Genジョブのリスト。 # Box Doc Genジョブ 標準のパラメータのセットを含むBox Doc Genジョブのリスト。 --- ### Box Doc Genジョブ (Base) **Type:** resource | **Category:** api-resource | **Section:** API Reference Box Doc GenジョブのBase版の表示。 # Box Doc Genジョブ (Base) Box Doc GenジョブのBase版の表示。 --- ### Box Doc Genジョブ (Full) **Type:** resource | **Category:** api-resource | **Section:** API Reference Box Doc GenジョブのFull版の表示。 # Box Doc Genジョブ (Full) Box Doc GenジョブのFull版の表示。 --- ### Box Doc Genジョブ (Full) **Type:** resource | **Category:** api-resource | **Section:** API Reference すべてのパラメータを含むBox Doc Genジョブのリスト。 # Box Doc Genジョブ (Full) すべてのパラメータを含むBox Doc Genジョブのリスト。 --- ### Box Doc Genタグ **Type:** resource | **Category:** api-resource | **Section:** API Reference Box Doc Genタグのリスト。 # Box Doc Genタグ Box Doc Genタグのリスト。 --- ### Box Doc Genタグの処理メッセージ **Type:** resource | **Category:** api-resource | **Section:** API Reference ドキュメントのタグがまだ処理中であることをユーザーに通知するメッセージ。 # Box Doc Genタグの処理メッセージ ドキュメントのタグがまだ処理中であることをユーザーに通知するメッセージ。 --- ### Box Doc Genテンプレート **Type:** resource | **Category:** api-resource | **Section:** API Reference Box Doc Genテンプレートオブジェクト。 # Box Doc Genテンプレート Box Doc Genテンプレートオブジェクト。 --- ### Box Doc Genテンプレート **Type:** resource | **Category:** api-resource | **Section:** API Reference Box Doc Genテンプレートのリスト。 # Box Doc Genテンプレート Box Doc Genテンプレートのリスト。 --- ### Box Doc Genテンプレート (Base) **Type:** resource | **Category:** api-resource | **Section:** API Reference 他のリソース内にネストされたときに使用されるBox Doc GenテンプレートのBase版の表示。 # Box Doc Genテンプレート (Base) 他のリソース内にネストされたときに使用されるBox Doc GenテンプレートのBase版の表示。 --- ### Box Doc Genテンプレートタグ **Type:** resource | **Category:** api-resource | **Section:** API Reference Box Doc Genテンプレートタグオブジェクト。 # Box Doc Genテンプレートタグ Box Doc Genテンプレートタグオブジェクト。 --- ### Box Doc Genテンプレートのリストを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/v2025.0/get-docgen-templates/ **Source:** [https://ja.developer.box.com/reference/v2025.0/get-docgen-templates/](https://ja.developer.box.com/reference/v2025.0/get-docgen-templates/) --- ### Box Doc Genテンプレートを作成 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/v2025.0/post-docgen-templates/ **Source:** [https://ja.developer.box.com/reference/v2025.0/post-docgen-templates/](https://ja.developer.box.com/reference/v2025.0/post-docgen-templates/) --- ### Box Doc Genテンプレートを使用してドキュメントを生成 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/v2025.0/post-docgen-batches/ **Source:** [https://ja.developer.box.com/reference/v2025.0/post-docgen-batches/](https://ja.developer.box.com/reference/v2025.0/post-docgen-batches/) --- ### Box Doc Genテンプレートを削除 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/v2025.0/delete-docgen-templates-id/ **Source:** [https://ja.developer.box.com/reference/v2025.0/delete-docgen-templates-id/](https://ja.developer.box.com/reference/v2025.0/delete-docgen-templates-id/) --- ### Box Doc Genのバッチ (Base) **Type:** resource | **Category:** api-resource | **Section:** API Reference Box Doc GenバッチオブジェクトのBase版の表示。Box Doc Genのバッチには、1つ以上のBox Doc Genジョブが含まれています。 # Box Doc Genのバッチ (Base) Box Doc GenバッチオブジェクトのBase版の表示。Box Doc Genのバッチには、1つ以上のBox Doc Genジョブが含まれています。 --- ### Box Signテンプレート **Type:** resource | **Category:** api-resource | **Section:** API Reference Box Signテンプレートオブジェクト。 # Box Signテンプレート Box Signテンプレートオブジェクト。 --- ### Box Signテンプレート **Type:** resource | **Category:** api-resource | **Section:** API Reference 任意のBox Sign APIエンドポイントからデフォルトで返されるテンプレートのリスト。 # Box Signテンプレート 任意のBox Sign APIエンドポイントからデフォルトで返されるテンプレートのリスト。 --- ### Box Signテンプレートのリストを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-sign-templates/ **Source:** [https://ja.developer.box.com/reference/get-sign-templates/](https://ja.developer.box.com/reference/get-sign-templates/) --- ### Box Signリクエスト **Type:** resource | **Category:** api-resource | **Section:** API Reference Box Signリクエストオブジェクト。 # Box Signリクエスト Box Signリクエストオブジェクト。 --- ### Box Signリクエスト **Type:** resource | **Category:** api-resource | **Section:** API Reference 任意のBox Sign APIエンドポイントからデフォルトで返される署名リクエストのStandard版の表示。 # Box Signリクエスト 任意のBox Sign APIエンドポイントからデフォルトで返される署名リクエストのStandard版の表示。 --- ### Box Signリクエストのリストを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-sign-requests/ **Source:** [https://ja.developer.box.com/reference/get-sign-requests/](https://ja.developer.box.com/reference/get-sign-requests/) --- ### Box Signリクエストをキャンセル **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/post-sign-requests-id-cancel/ **Source:** [https://ja.developer.box.com/reference/post-sign-requests-id-cancel/](https://ja.developer.box.com/reference/post-sign-requests-id-cancel/) --- ### Box Signリクエストを作成 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/post-sign-requests/ **Source:** [https://ja.developer.box.com/reference/post-sign-requests/](https://ja.developer.box.com/reference/post-sign-requests/) --- ### Box Signリクエストを作成する **Type:** resource | **Category:** api-resource | **Section:** API Reference Box Signリクエストオブジェクトを作成します。 # Box Signリクエストを作成する Box Signリクエストオブジェクトを作成します。 --- ### Box Signリクエストを再送信 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/post-sign-requests-id-resend/ **Source:** [https://ja.developer.box.com/reference/post-sign-requests-id-resend/](https://ja.developer.box.com/reference/post-sign-requests-id-resend/) --- ### Collaboration **Type:** resource | **Category:** api-resource | **Section:** API Reference アクセス制御リストと同様に、コラボレーションではファイルとフォルダに 対するユーザーおよびグループのアクセス権限が定義されます。コラボレーションオブジェクトは、特定のロールによって定義される権限を含んだファイルまたはフォルダへのアクセス権限をユーザーまたはグループに付与します。 # Collaboration アクセス制御リストと同様に、コラボレーションではファイルとフォルダに 対するユーザーおよびグループのアクセス権限が定義されます。コラボレーションオブジェクトは、特定のロールによって定義される権限を含んだファイルまたはフォルダへのアクセス権限をユーザーまたはグループに付与します。 --- ### Collaborations **Type:** resource | **Category:** api-resource | **Section:** API Reference コラボレーションのリスト。 # Collaborations コラボレーションのリスト。 --- ### Collaborations **Type:** resource | **Category:** api-resource | **Section:** API Reference コラボレーションのリスト。 # Collaborations コラボレーションのリスト。 --- ### Collection **Type:** resource | **Category:** api-resource | **Section:** API Reference ファイルやフォルダなどの項目のコレクション。 現時点で利用可能なコレクションは、`favorites`コレクションのみです。 コレクションのコンテンツは、フォルダのコンテンツと同じ方法で調べることができます。 # Collection ファイルやフォルダなどの項目のコレクション。 現時点で利用可能なコレクションは、`favorites`コレクションのみです。 コレクションのコンテンツは、フォルダのコンテンツと同じ方法で調べることができます。 --- ### Collections **Type:** resource | **Category:** api-resource | **Section:** API Reference コレクションのリスト。 # Collections コレクションのリスト。 --- ### Comment **Type:** resource | **Category:** api-resource | **Section:** API Reference コメントのStandard版の表示。 # Comment コメントのStandard版の表示。 --- ### Comments **Type:** resource | **Category:** api-resource | **Section:** API Reference コメントのリスト。 # Comments コメントのリスト。 --- ### Device Pinner **Type:** resource | **Category:** api-resource | **Section:** API Reference デバイスピンを使用すると、どのデバイスでネイティブBoxアプリケーションの使用を許可するかを会社レベルで制御できます。 # Device Pinner デバイスピンを使用すると、どのデバイスでネイティブBoxアプリケーションの使用を許可するかを会社レベルで制御できます。 --- ### Device Pinners **Type:** resource | **Category:** api-resource | **Section:** API Reference デバイスピンのリスト。 # Device Pinners デバイスピンのリスト。 --- ### Event **Type:** resource | **Category:** api-resource | **Section:** API Reference Box内で発生したイベントの説明。 # Event Box内で発生したイベントの説明。 --- ### Events **Type:** resource | **Category:** api-resource | **Section:** API Reference イベントオブジェクトのリスト。 # Events イベントオブジェクトのリスト。 --- ### External Users Submit Delete Job Response **Type:** resource | **Category:** api-resource | **Section:** API Reference Multi-status response containing the result for each external user deletion request. # External Users Submit Delete Job Response Multi-status response containing the result for each external user deletion request. --- ### File **Type:** resource | **Category:** api-resource | **Section:** API Reference 任意のファイルAPIエンドポイントからデフォルトで返されるファイルのStandard版の表示。 # File 任意のファイルAPIエンドポイントからデフォルトで返されるファイルのStandard版の表示。 --- ### Files **Type:** resource | **Category:** api-resource | **Section:** API Reference ファイルのリスト。 # Files ファイルのリスト。 --- ### Folder **Type:** resource | **Category:** api-resource | **Section:** API Reference 任意のフォルダAPIエンドポイントからデフォルトで返されるフォルダのStandard版の表示。 # Folder 任意のフォルダAPIエンドポイントからデフォルトで返されるフォルダのStandard版の表示。 --- ### Group **Type:** resource | **Category:** api-resource | **Section:** API Reference 任意のグループAPIエンドポイントからデフォルトで返されるグループのStandard版の表示。 # Group 任意のグループAPIエンドポイントからデフォルトで返されるグループのStandard版の表示。 --- ### Groups **Type:** resource | **Category:** api-resource | **Section:** API Reference グループのリスト。 # Groups グループのリスト。 --- ### Hub **Type:** resource | **Category:** api-resource | **Section:** API Reference 任意のHub APIエンドポイントからデフォルトで返されるHubのStandard版の表示。 # Hub 任意のHub APIエンドポイントからデフォルトで返されるHubのStandard版の表示。 --- ### Hub (Base) **Type:** resource | **Category:** api-resource | **Section:** API Reference 最も基本的なHubのBase版の表示。 # Hub (Base) 最も基本的なHubのBase版の表示。 --- ### Hubs **Type:** resource | **Category:** api-resource | **Section:** API Reference Hubのページ割りされたリスト。 # Hubs Hubのページ割りされたリスト。 --- ### Hubコラボレーション **Type:** resource | **Category:** api-resource | **Section:** API Reference Hubコラボレーションオブジェクトは、特定のロールによって定義される権限を含んだHubへのアクセス権限をユーザーまたはグループに付与します。 # Hubコラボレーション Hubコラボレーションオブジェクトは、特定のロールによって定義される権限を含んだHubへのアクセス権限をユーザーまたはグループに付与します。 --- ### Hubコラボレーション **Type:** resource | **Category:** api-resource | **Section:** API Reference Hubコラボレーションのリスト。 # Hubコラボレーション Hubコラボレーションのリスト。 --- ### Hubコラボレーションを作成 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/v2025.0/post-hub-collaborations/ **Source:** [https://ja.developer.box.com/reference/v2025.0/post-hub-collaborations/](https://ja.developer.box.com/reference/v2025.0/post-hub-collaborations/) --- ### Hubコラボレーションを削除 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/v2025.0/delete-hub-collaborations-id/ **Source:** [https://ja.developer.box.com/reference/v2025.0/delete-hub-collaborations-id/](https://ja.developer.box.com/reference/v2025.0/delete-hub-collaborations-id/) --- ### Hubコラボレーションを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/v2025.0/get-hub-collaborations/ **Source:** [https://ja.developer.box.com/reference/v2025.0/get-hub-collaborations/](https://ja.developer.box.com/reference/v2025.0/get-hub-collaborations/) --- ### Hubコラボレーションを更新 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/v2025.0/put-hub-collaborations-id/ **Source:** [https://ja.developer.box.com/reference/v2025.0/put-hub-collaborations-id/](https://ja.developer.box.com/reference/v2025.0/put-hub-collaborations-id/) --- ### Hubの項目 **Type:** resource | **Category:** api-resource | **Section:** API Reference Hubの項目とは、Hubで参照されるBox項目のことです。 # Hubの項目 Hubの項目とは、Hubで参照されるBox項目のことです。 --- ### Hubの項目 **Type:** resource | **Category:** api-resource | **Section:** API Reference Hubの項目のリスト。 # Hubの項目 Hubの項目のリスト。 --- ### Hubの項目の管理のレスポンス **Type:** resource | **Category:** api-resource | **Section:** API Reference Hubの項目の管理操作のステータスを表すレスポンスのスキーマ。 # Hubの項目の管理のレスポンス Hubの項目の管理操作のステータスを表すレスポンスのスキーマ。 --- ### Hubの項目を取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/v2025.0/get-hub-items/ **Source:** [https://ja.developer.box.com/reference/v2025.0/get-hub-items/](https://ja.developer.box.com/reference/v2025.0/get-hub-items/) --- ### Hubの項目を管理 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/v2025.0/post-hubs-id-manage-items/ **Source:** [https://ja.developer.box.com/reference/v2025.0/post-hubs-id-manage-items/](https://ja.developer.box.com/reference/v2025.0/post-hubs-id-manage-items/) --- ### Hubをコピー **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/v2025.0/post-hubs-id-copy/ **Source:** [https://ja.developer.box.com/reference/v2025.0/post-hubs-id-copy/](https://ja.developer.box.com/reference/v2025.0/post-hubs-id-copy/) --- ### Hubを作成 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/v2025.0/post-hubs/ **Source:** [https://ja.developer.box.com/reference/v2025.0/post-hubs/](https://ja.developer.box.com/reference/v2025.0/post-hubs/) --- ### Hubを削除 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/v2025.0/delete-hubs-id/ **Source:** [https://ja.developer.box.com/reference/v2025.0/delete-hubs-id/](https://ja.developer.box.com/reference/v2025.0/delete-hubs-id/) --- ### IDを指定してBox Doc Genジョブを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/v2025.0/get-docgen-jobs-id/ **Source:** [https://ja.developer.box.com/reference/v2025.0/get-docgen-jobs-id/](https://ja.developer.box.com/reference/v2025.0/get-docgen-jobs-id/) --- ### IDを指定してBox Doc Genテンプレートを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/v2025.0/get-docgen-templates-id/ **Source:** [https://ja.developer.box.com/reference/v2025.0/get-docgen-templates-id/](https://ja.developer.box.com/reference/v2025.0/get-docgen-templates-id/) --- ### IDを指定してBox Signテンプレートを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-sign-templates-id/ **Source:** [https://ja.developer.box.com/reference/get-sign-templates-id/](https://ja.developer.box.com/reference/get-sign-templates-id/) --- ### IDを指定してBox Signリクエストを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-sign-requests-id/ **Source:** [https://ja.developer.box.com/reference/get-sign-requests-id/](https://ja.developer.box.com/reference/get-sign-requests-id/) --- ### IDを指定してHubの情報を取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/v2025.0/get-hubs-id/ **Source:** [https://ja.developer.box.com/reference/v2025.0/get-hubs-id/](https://ja.developer.box.com/reference/v2025.0/get-hubs-id/) --- ### IDを指定してHubの情報を更新 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/v2025.0/put-hubs-id/ **Source:** [https://ja.developer.box.com/reference/v2025.0/put-hubs-id/](https://ja.developer.box.com/reference/v2025.0/put-hubs-id/) --- ### IDを指定してShield情報バリアのセグメントメンバーを削除 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/delete-shield-information-barrier-segment-members-id/ **Source:** [https://ja.developer.box.com/reference/delete-shield-information-barrier-segment-members-id/](https://ja.developer.box.com/reference/delete-shield-information-barrier-segment-members-id/) --- ### IDを指定してShield情報バリアのセグメントメンバーを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-shield-information-barrier-segment-members-id/ **Source:** [https://ja.developer.box.com/reference/get-shield-information-barrier-segment-members-id/](https://ja.developer.box.com/reference/get-shield-information-barrier-segment-members-id/) --- ### IDを指定してShield情報バリアのセグメント制限を削除 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/delete-shield-information-barrier-segment-restrictions-id/ **Source:** [https://ja.developer.box.com/reference/delete-shield-information-barrier-segment-restrictions-id/](https://ja.developer.box.com/reference/delete-shield-information-barrier-segment-restrictions-id/) --- ### IDを指定してShield情報バリアのセグメント制限を取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-shield-information-barrier-segment-restrictions-id/ **Source:** [https://ja.developer.box.com/reference/get-shield-information-barrier-segment-restrictions-id/](https://ja.developer.box.com/reference/get-shield-information-barrier-segment-restrictions-id/) --- ### IDを指定してShield情報バリアレポートを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-shield-information-barrier-reports-id/ **Source:** [https://ja.developer.box.com/reference/get-shield-information-barrier-reports-id/](https://ja.developer.box.com/reference/get-shield-information-barrier-reports-id/) --- ### IDを指定してコレクションを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-collections-id/ **Source:** [https://ja.developer.box.com/reference/get-collections-id/](https://ja.developer.box.com/reference/get-collections-id/) --- ### IDを指定してメタデータテンプレートを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-metadata-templates-id/ **Source:** [https://ja.developer.box.com/reference/get-metadata-templates-id/](https://ja.developer.box.com/reference/get-metadata-templates-id/) --- ### Invite **Type:** resource | **Category:** api-resource | **Section:** API Reference 会社へのユーザーの招待。 # Invite 会社へのユーザーの招待。 --- ### Items **Type:** resource | **Category:** api-resource | **Section:** API Reference Mini版の表示に含まれるファイル、フォルダ、ウェブリンクのリスト。 # Items Mini版の表示に含まれるファイル、フォルダ、ウェブリンクのリスト。 --- ### Items **Type:** resource | **Category:** api-resource | **Section:** API Reference Mini版の表示に含まれるファイル、フォルダ、ウェブリンクのリスト。 # Items Mini版の表示に含まれるファイル、フォルダ、ウェブリンクのリスト。 --- ### Metadata query index **Type:** resource | **Category:** api-resource | **Section:** API Reference メタデータクエリインデックス。 # Metadata query index メタデータクエリインデックス。 --- ### OAuth 2.0エラー **Type:** resource | **Category:** api-resource | **Section:** API Reference OAuth 2.0エラー。 # OAuth 2.0エラー OAuth 2.0エラー。 --- ### Shieldリスト **Type:** resource | **Category:** api-resource | **Section:** API Reference ShieldリストのStandard版の表示。 # Shieldリスト ShieldリストのStandard版の表示。 --- ### Shieldリスト (Mini) **Type:** resource | **Category:** api-resource | **Section:** API Reference ShieldリストのMini版の表示。 # Shieldリスト (Mini) ShieldリストのMini版の表示。 --- ### ShieldリストIDを指定して1つのShieldリストを削除 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/v2025.0/delete-shield-lists-id/ **Source:** [https://ja.developer.box.com/reference/v2025.0/delete-shield-lists-id/](https://ja.developer.box.com/reference/v2025.0/delete-shield-lists-id/) --- ### ShieldリストIDを指定して1つのShieldリストを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/v2025.0/get-shield-lists-id/ **Source:** [https://ja.developer.box.com/reference/v2025.0/get-shield-lists-id/](https://ja.developer.box.com/reference/v2025.0/get-shield-lists-id/) --- ### Shieldリストのコンテンツ (IP) **Type:** resource | **Category:** api-resource | **Section:** API Reference IPアドレスのデータを含むShieldリストのコンテンツの表示。 # Shieldリストのコンテンツ (IP) IPアドレスのデータを含むShieldリストのコンテンツの表示。 --- ### Shieldリストのコンテンツ (ドメイン) **Type:** resource | **Category:** api-resource | **Section:** API Reference ドメインのデータを含むShieldリストのコンテンツの表示。 # Shieldリストのコンテンツ (ドメイン) ドメインのデータを含むShieldリストのコンテンツの表示。 --- ### Shieldリストのコンテンツ (メールアドレス) **Type:** resource | **Category:** api-resource | **Section:** API Reference メールアドレスのデータを含むShieldリストのコンテンツの表示。 # Shieldリストのコンテンツ (メールアドレス) メールアドレスのデータを含むShieldリストのコンテンツの表示。 --- ### Shieldリストのコンテンツ (国) **Type:** resource | **Category:** api-resource | **Section:** API Reference 国のデータを含むShieldリストのコンテンツの表示。 # Shieldリストのコンテンツ (国) 国のデータを含むShieldリストのコンテンツの表示。 --- ### Shieldリストのコンテンツ (統合) **Type:** resource | **Category:** api-resource | **Section:** API Reference 統合のデータを含むShieldリストのコンテンツの表示。 # Shieldリストのコンテンツ (統合) 統合のデータを含むShieldリストのコンテンツの表示。 --- ### Shieldリストのリスト **Type:** resource | **Category:** api-resource | **Section:** API Reference Shieldリストオブジェクトのリスト。 # Shieldリストのリスト Shieldリストオブジェクトのリスト。 --- ### Shieldリストを作成 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/v2025.0/post-shield-lists/ **Source:** [https://ja.developer.box.com/reference/v2025.0/post-shield-lists/](https://ja.developer.box.com/reference/v2025.0/post-shield-lists/) --- ### Shieldリストを更新 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/v2025.0/put-shield-lists-id/ **Source:** [https://ja.developer.box.com/reference/v2025.0/put-shield-lists-id/](https://ja.developer.box.com/reference/v2025.0/put-shield-lists-id/) --- ### Shield情報バリア **Type:** resource | **Category:** api-resource | **Section:** API Reference Shield情報バリアオブジェクトのStandard版の表示。 # Shield情報バリア Shield情報バリアオブジェクトのStandard版の表示。 --- ### Shield情報バリア (Base) **Type:** resource | **Category:** api-resource | **Section:** API Reference Shield情報バリアオブジェクトのBase版の表示。 # Shield情報バリア (Base) Shield情報バリアオブジェクトのBase版の表示。 --- ### Shield情報バリアのセグメント **Type:** resource | **Category:** api-resource | **Section:** API Reference Shield情報バリアのセグメントオブジェクト。 # Shield情報バリアのセグメント Shield情報バリアのセグメントオブジェクト。 --- ### Shield情報バリアのセグメントのリスト **Type:** resource | **Category:** api-resource | **Section:** API Reference Shield情報バリアのセグメントオブジェクトのリスト。 # Shield情報バリアのセグメントのリスト Shield情報バリアのセグメントオブジェクトのリスト。 --- ### Shield情報バリアのセグメントのリストを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-shield-information-barrier-segments/ **Source:** [https://ja.developer.box.com/reference/get-shield-information-barrier-segments/](https://ja.developer.box.com/reference/get-shield-information-barrier-segments/) --- ### Shield情報バリアのセグメントメンバー **Type:** resource | **Category:** api-resource | **Section:** API Reference Shield情報バリアのセグメントメンバーオブジェクトのStandard版の表示。 # Shield情報バリアのセグメントメンバー Shield情報バリアのセグメントメンバーオブジェクトのStandard版の表示。 --- ### Shield情報バリアのセグメントメンバー (Base) **Type:** resource | **Category:** api-resource | **Section:** API Reference Shield情報バリアのセグメントメンバーオブジェクトのBase版の表示。 # Shield情報バリアのセグメントメンバー (Base) Shield情報バリアのセグメントメンバーオブジェクトのBase版の表示。 --- ### Shield情報バリアのセグメントメンバー (Mini) **Type:** resource | **Category:** api-resource | **Section:** API Reference Shield情報バリアのセグメントメンバーオブジェクトのMini版の表示。 # Shield情報バリアのセグメントメンバー (Mini) Shield情報バリアのセグメントメンバーオブジェクトのMini版の表示。 --- ### Shield情報バリアのセグメントメンバーのリスト **Type:** resource | **Category:** api-resource | **Section:** API Reference Shield情報バリアのメンバーオブジェクトのリスト。 # Shield情報バリアのセグメントメンバーのリスト Shield情報バリアのメンバーオブジェクトのリスト。 --- ### Shield情報バリアのセグメントメンバーのリストを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-shield-information-barrier-segment-members/ **Source:** [https://ja.developer.box.com/reference/get-shield-information-barrier-segment-members/](https://ja.developer.box.com/reference/get-shield-information-barrier-segment-members/) --- ### Shield情報バリアのセグメントメンバーを作成 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/post-shield-information-barrier-segment-members/ **Source:** [https://ja.developer.box.com/reference/post-shield-information-barrier-segment-members/](https://ja.developer.box.com/reference/post-shield-information-barrier-segment-members/) --- ### Shield情報バリアのセグメントを作成 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/post-shield-information-barrier-segments/ **Source:** [https://ja.developer.box.com/reference/post-shield-information-barrier-segments/](https://ja.developer.box.com/reference/post-shield-information-barrier-segments/) --- ### Shield情報バリアのセグメントを削除 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/delete-shield-information-barrier-segments-id/ **Source:** [https://ja.developer.box.com/reference/delete-shield-information-barrier-segments-id/](https://ja.developer.box.com/reference/delete-shield-information-barrier-segments-id/) --- ### Shield情報バリアのセグメント制限 **Type:** resource | **Category:** api-resource | **Section:** API Reference Shield情報バリアオブジェクトのセグメント制限のStandard版の表示。 # Shield情報バリアのセグメント制限 Shield情報バリアオブジェクトのセグメント制限のStandard版の表示。 --- ### Shield情報バリアのセグメント制限 (Base) **Type:** resource | **Category:** api-resource | **Section:** API Reference Shield情報バリアのセグメント制限オブジェクトのBase版の表示。 # Shield情報バリアのセグメント制限 (Base) Shield情報バリアのセグメント制限オブジェクトのBase版の表示。 --- ### Shield情報バリアのセグメント制限 (Mini) **Type:** resource | **Category:** api-resource | **Section:** API Reference Shield情報バリアのセグメント制限オブジェクトのMini版の表示。 # Shield情報バリアのセグメント制限 (Mini) Shield情報バリアのセグメント制限オブジェクトのMini版の表示。 --- ### Shield情報バリアのセグメント制限のリスト **Type:** resource | **Category:** api-resource | **Section:** API Reference Shield情報バリアのセグメント制限オブジェクトのリスト。 # Shield情報バリアのセグメント制限のリスト Shield情報バリアのセグメント制限オブジェクトのリスト。 --- ### Shield情報バリアのセグメント制限のリストを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-shield-information-barrier-segment-restrictions/ **Source:** [https://ja.developer.box.com/reference/get-shield-information-barrier-segment-restrictions/](https://ja.developer.box.com/reference/get-shield-information-barrier-segment-restrictions/) --- ### Shield情報バリアのセグメント制限を作成 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/post-shield-information-barrier-segment-restrictions/ **Source:** [https://ja.developer.box.com/reference/post-shield-information-barrier-segment-restrictions/](https://ja.developer.box.com/reference/post-shield-information-barrier-segment-restrictions/) --- ### Shield情報バリアのリスト **Type:** resource | **Category:** api-resource | **Section:** API Reference Shield情報バリアオブジェクトのリスト。 # Shield情報バリアのリスト Shield情報バリアオブジェクトのリスト。 --- ### Shield情報バリアのリストを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-shield-information-barriers/ **Source:** [https://ja.developer.box.com/reference/get-shield-information-barriers/](https://ja.developer.box.com/reference/get-shield-information-barriers/) --- ### Shield情報バリアレポート **Type:** resource | **Category:** api-resource | **Section:** API Reference Shield情報バリアレポートオブジェクトのStandard版の表示。 # Shield情報バリアレポート Shield情報バリアレポートオブジェクトのStandard版の表示。 --- ### Shield情報バリアレポート (Base) **Type:** resource | **Category:** api-resource | **Section:** API Reference Shield情報バリアレポートオブジェクトのBase版の表示。 # Shield情報バリアレポート (Base) Shield情報バリアレポートオブジェクトのBase版の表示。 --- ### Shield情報バリアレポートのリスト **Type:** resource | **Category:** api-resource | **Section:** API Reference Shieldバリアレポートのリスト。 # Shield情報バリアレポートのリスト Shieldバリアレポートのリスト。 --- ### Shield情報バリアレポートのリストを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-shield-information-barrier-reports/ **Source:** [https://ja.developer.box.com/reference/get-shield-information-barrier-reports/](https://ja.developer.box.com/reference/get-shield-information-barrier-reports/) --- ### Shield情報バリアレポートの詳細 **Type:** resource | **Category:** api-resource | **Section:** API Reference レポートの生成時に、レポートファイルが配置されているフォルダとエラー (ある場合) を示します。 # Shield情報バリアレポートの詳細 レポートの生成時に、レポートファイルが配置されているフォルダとエラー (ある場合) を示します。 --- ### Shield情報バリアレポートを作成 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/post-shield-information-barrier-reports/ **Source:** [https://ja.developer.box.com/reference/post-shield-information-barrier-reports/](https://ja.developer.box.com/reference/post-shield-information-barrier-reports/) --- ### Shield情報バリアを作成 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/post-shield-information-barriers/ **Source:** [https://ja.developer.box.com/reference/post-shield-information-barriers/](https://ja.developer.box.com/reference/post-shield-information-barriers/) --- ### Shield情報バリア参照 **Type:** resource | **Category:** api-resource | **Section:** API Reference リクエストおよびレスポンスのShield情報バリア参照。 # Shield情報バリア参照 リクエストおよびレスポンスのShield情報バリア参照。 --- ### Skillsメタデータインスタンス **Type:** resource | **Category:** api-resource | **Section:** API Reference Boxスキルの使用に割り当てられたメタデータ。 # Skillsメタデータインスタンス Boxスキルの使用に割り当てられたメタデータ。 --- ### Slack統合マッピング **Type:** resource | **Category:** api-resource | **Section:** API Reference 統合マッピングオブジェクトのSlack固有のレプリゼンテーション。 # Slack統合マッピング 統合マッピングオブジェクトのSlack固有のレプリゼンテーション。 --- ### Slack統合マッピング (リスト) **Type:** resource | **Category:** api-resource | **Section:** API Reference 統合マッピングオブジェクトのリスト。 # Slack統合マッピング (リスト) 統合マッピングオブジェクトのリスト。 --- ### Slack統合マッピングのリストを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-integration-mappings-slack/ **Source:** [https://ja.developer.box.com/reference/get-integration-mappings-slack/](https://ja.developer.box.com/reference/get-integration-mappings-slack/) --- ### Slack統合マッピングリクエストを作成 **Type:** resource | **Category:** api-resource | **Section:** API Reference Slack統合マッピングオブジェクトを作成するリクエスト。 # Slack統合マッピングリクエストを作成 Slack統合マッピングオブジェクトを作成するリクエスト。 --- ### Slack統合マッピングを作成 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/post-integration-mappings-slack/ **Source:** [https://ja.developer.box.com/reference/post-integration-mappings-slack/](https://ja.developer.box.com/reference/post-integration-mappings-slack/) --- ### Slack統合マッピングを削除 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/delete-integration-mappings-slack-id/ **Source:** [https://ja.developer.box.com/reference/delete-integration-mappings-slack-id/](https://ja.developer.box.com/reference/delete-integration-mappings-slack-id/) --- ### Slack統合マッピングを更新 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/put-integration-mappings-slack-id/ **Source:** [https://ja.developer.box.com/reference/put-integration-mappings-slack-id/](https://ja.developer.box.com/reference/put-integration-mappings-slack-id/) --- ### Submit job to delete external users **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/v2025.0/post-external-users-submit-delete-job/ **Source:** [https://ja.developer.box.com/reference/v2025.0/post-external-users-submit-delete-job/](https://ja.developer.box.com/reference/v2025.0/post-external-users-submit-delete-job/) --- ### Task **Type:** resource | **Category:** api-resource | **Section:** API Reference タスクを使用すると、Boxでファイル中心のワークフローを実現できます。ユーザーはファイルに関連するタスクを作成し、タスクを完了するために他のユーザーに割り当てることができます。 # Task タスクを使用すると、Boxでファイル中心のワークフローを実現できます。ユーザーはファイルに関連するタスクを作成し、タスクを完了するために他のユーザーに割り当てることができます。 --- ### Tasks **Type:** resource | **Category:** api-resource | **Section:** API Reference タスクのリスト。 # Tasks タスクのリスト。 --- ### Teams統合マッピング **Type:** resource | **Category:** api-resource | **Section:** API Reference 統合マッピングオブジェクトのMicrosoft Teams固有のレプリゼンテーション。 # Teams統合マッピング 統合マッピングオブジェクトのMicrosoft Teams固有のレプリゼンテーション。 --- ### Teams統合マッピング (リスト) **Type:** resource | **Category:** api-resource | **Section:** API Reference 統合マッピングオブジェクトのリスト。 # Teams統合マッピング (リスト) 統合マッピングオブジェクトのリスト。 --- ### Teams統合マッピングのリストを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-integration-mappings-teams/ **Source:** [https://ja.developer.box.com/reference/get-integration-mappings-teams/](https://ja.developer.box.com/reference/get-integration-mappings-teams/) --- ### Teams統合マッピングリクエストを作成 **Type:** resource | **Category:** api-resource | **Section:** API Reference Teams統合マッピングオブジェクトを作成するリクエスト。 # Teams統合マッピングリクエストを作成 Teams統合マッピングオブジェクトを作成するリクエスト。 --- ### Teams統合マッピングを作成 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/post-integration-mappings-teams/ **Source:** [https://ja.developer.box.com/reference/post-integration-mappings-teams/](https://ja.developer.box.com/reference/post-integration-mappings-teams/) --- ### Teams統合マッピングを削除 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/delete-integration-mappings-teams-id/ **Source:** [https://ja.developer.box.com/reference/delete-integration-mappings-teams-id/](https://ja.developer.box.com/reference/delete-integration-mappings-teams-id/) --- ### Teams統合マッピングを更新 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/put-integration-mappings-teams-id/ **Source:** [https://ja.developer.box.com/reference/put-integration-mappings-teams-id/](https://ja.developer.box.com/reference/put-integration-mappings-teams-id/) --- ### Upload part **Type:** resource | **Category:** api-resource | **Section:** API Reference アップロードセッションチャンクのレプリゼンテーション。 # Upload part アップロードセッションチャンクのレプリゼンテーション。 --- ### Upload part **Type:** resource | **Category:** api-resource | **Section:** API Reference アップロードセッションのアップロード済みチャンクのリスト。 # Upload part アップロードセッションのアップロード済みチャンクのリスト。 --- ### User **Type:** resource | **Category:** api-resource | **Section:** API Reference 任意のユーザーAPIエンドポイントからデフォルトで返されるユーザーのStandard版の表示。 # User 任意のユーザーAPIエンドポイントからデフォルトで返されるユーザーのStandard版の表示。 --- ### User EventおよびEnterprise Eventのリストを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-events/ **Source:** [https://ja.developer.box.com/reference/get-events/](https://ja.developer.box.com/reference/get-events/) --- ### Users **Type:** resource | **Category:** api-resource | **Section:** API Reference ユーザーのリスト。 # Users ユーザーのリスト。 --- ### Watermark **Type:** resource | **Category:** api-resource | **Section:** API Reference 電子すかしとは、埋め込みファイルのプレビューに適用される半透明のオーバーレイです。電子すかしには、ビューアーのメールアドレスまたはユーザーIDと、ファイルのコンテンツのアクセス日時が表示されます。 # Watermark 電子すかしとは、埋め込みファイルのプレビューに適用される半透明のオーバーレイです。電子すかしには、ビューアーのメールアドレスまたはユーザーIDと、ファイルのコンテンツのアクセス日時が表示されます。 --- ### Webhook **Type:** resource | **Category:** api-resource | **Section:** API Reference 設定されたWebhookを表します。 # Webhook 設定されたWebhookを表します。 --- ### Webhook (Mini) **Type:** resource | **Category:** api-resource | **Section:** API Reference 設定されたWebhookを表します。 # Webhook (Mini) 設定されたWebhookを表します。 --- ### Webhook (V2) ペイロード **Type:** resource | **Category:** api-resource | **Section:** API Reference イベント発生時にWebhookアドレスに送信されるイベント。 # Webhook (V2) ペイロード イベント発生時にWebhookアドレスに送信されるイベント。 --- ### Webhooks **Type:** resource | **Category:** api-resource | **Section:** API Reference Webhookのリスト。 # Webhooks Webhookのリスト。 --- ### Webhookを作成 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/post-webhooks/ **Source:** [https://ja.developer.box.com/reference/post-webhooks/](https://ja.developer.box.com/reference/post-webhooks/) --- ### Webhookを削除 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/delete-webhooks-id/ **Source:** [https://ja.developer.box.com/reference/delete-webhooks-id/](https://ja.developer.box.com/reference/delete-webhooks-id/) --- ### Webhookを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-webhooks-id/ **Source:** [https://ja.developer.box.com/reference/get-webhooks-id/](https://ja.developer.box.com/reference/get-webhooks-id/) --- ### Webhookを更新 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/put-webhooks-id/ **Source:** [https://ja.developer.box.com/reference/put-webhooks-id/](https://ja.developer.box.com/reference/put-webhooks-id/) --- ### Workflow **Type:** resource | **Category:** api-resource | **Section:** API Reference Box Relayワークフローは、名前が付けられたフローのコレクションを表すオブジェクトです。 アプリケーションは、このリソースを使用するために、開発者コンソールでの`Manage Box Relay`アプリケーションスコープの使用が承認されている必要があります。 # Workflow Box Relayワークフローは、名前が付けられたフローのコレクションを表すオブジェクトです。 アプリケーションは、このリソースを使用するために、開発者コンソールでの`Manage Box Relay`アプリケーションスコープの使用が承認されている必要があります。 --- ### zipアーカイブをダウンロード **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-zip-downloads-id-content/ **Source:** [https://ja.developer.box.com/reference/get-zip-downloads-id-content/](https://ja.developer.box.com/reference/get-zip-downloads-id-content/) --- ### zipダウンロード **Type:** resource | **Category:** api-resource | **Section:** API Reference ファイルやフォルダのリストの`zip`アーカイブを作成するリクエストが成功したことを表します。 # zipダウンロード ファイルやフォルダのリストの`zip`アーカイブを作成するリクエストが成功したことを表します。 --- ### zipダウンロードのステータス **Type:** resource | **Category:** api-resource | **Section:** API Reference ダウンロード中の`zip`アーカイブのステータス。 # zipダウンロードのステータス ダウンロード中の`zip`アーカイブのステータス。 --- ### zipダウンロードのステータスを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-zip-downloads-id-status/ **Source:** [https://ja.developer.box.com/reference/get-zip-downloads-id-status/](https://ja.developer.box.com/reference/get-zip-downloads-id-status/) --- ### zipダウンロードを作成 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/post-zip-downloads/ **Source:** [https://ja.developer.box.com/reference/post-zip-downloads/](https://ja.developer.box.com/reference/post-zip-downloads/) --- ### アーカイブのリストを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/v2025.0/get-archives/ **Source:** [https://ja.developer.box.com/reference/v2025.0/get-archives/](https://ja.developer.box.com/reference/v2025.0/get-archives/) --- ### アーカイブを作成 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/v2025.0/post-archives/ **Source:** [https://ja.developer.box.com/reference/v2025.0/post-archives/](https://ja.developer.box.com/reference/v2025.0/post-archives/) --- ### アーカイブを削除 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/v2025.0/delete-archives-id/ **Source:** [https://ja.developer.box.com/reference/v2025.0/delete-archives-id/](https://ja.developer.box.com/reference/v2025.0/delete-archives-id/) --- ### アクセストークン **Type:** resource | **Category:** api-resource | **Section:** API Reference 認証済みのAPIコールを行うために使用できるトークン。 # アクセストークン 認証済みのAPIコールを行うために使用できるトークン。 --- ### アクセストークンをリクエスト **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/post-oauth2-token/ **Source:** [https://ja.developer.box.com/reference/post-oauth2-token/](https://ja.developer.box.com/reference/post-oauth2-token/) --- ### アクセストークンを取り消し **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/post-oauth2-revoke/ **Source:** [https://ja.developer.box.com/reference/post-oauth2-revoke/](https://ja.developer.box.com/reference/post-oauth2-revoke/) --- ### アクセストークンを更新 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/post-oauth2-token--refresh/ **Source:** [https://ja.developer.box.com/reference/post-oauth2-token--refresh/](https://ja.developer.box.com/reference/post-oauth2-token--refresh/) --- ### アップロードURL **Type:** resource | **Category:** api-resource | **Section:** API Reference ファイルのアップロードセッションの詳細。 # アップロードURL ファイルのアップロードセッションの詳細。 --- ### アップロードされたパーツ **Type:** resource | **Category:** api-resource | **Section:** API Reference いくつかのエンドポイントで返されるように、アップロードセッションの一部としてアップロードされたファイルのチャンク。 # アップロードされたパーツ いくつかのエンドポイントで返されるように、アップロードセッションの一部としてアップロードされたファイルのチャンク。 --- ### アップロードセッション **Type:** resource | **Category:** api-resource | **Section:** API Reference ファイルをアップロードするチャンクのアップロードセッション。 # アップロードセッション ファイルをアップロードするチャンクのアップロードセッション。 --- ### アップロードセッションをコミット **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/post-files-upload-sessions-id-commit/ **Source:** [https://ja.developer.box.com/reference/post-files-upload-sessions-id-commit/](https://ja.developer.box.com/reference/post-files-upload-sessions-id-commit/) --- ### アップロードセッションを作成 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/post-files-upload-sessions/ **Source:** [https://ja.developer.box.com/reference/post-files-upload-sessions/](https://ja.developer.box.com/reference/post-files-upload-sessions/) --- ### アップロードセッションを削除 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/delete-files-upload-sessions-id/ **Source:** [https://ja.developer.box.com/reference/delete-files-upload-sessions-id/](https://ja.developer.box.com/reference/delete-files-upload-sessions-id/) --- ### アップロードセッションを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-files-upload-sessions-id/ **Source:** [https://ja.developer.box.com/reference/get-files-upload-sessions-id/](https://ja.developer.box.com/reference/get-files-upload-sessions-id/) --- ### アップロード前の事前チェック **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/options-files-content/ **Source:** [https://ja.developer.box.com/reference/options-files-content/](https://ja.developer.box.com/reference/options-files-content/) --- ### アプリ項目 **Type:** resource | **Category:** api-resource | **Section:** API Reference アプリ項目は、アプリケーションが所有するコンテンツオブジェクトを表します。これは、さまざまなパスからファイルやフォルダをまとめてグループ化でき、そのセットは、コラボレーションを利用して共有できます。 # アプリ項目 アプリ項目は、アプリケーションが所有するコンテンツオブジェクトを表します。これは、さまざまなパスからファイルやフォルダをまとめてグループ化でき、そのセットは、コラボレーションを利用して共有できます。 --- ### アプリ項目の関連付け **Type:** resource | **Category:** api-resource | **Section:** API Reference アプリ項目の関連付けは、ファイルやフォルダとアプリ項目の関連付けを表します。フォルダとアプリ項目の関連付けは、そのフォルダのすべての子孫にカスケードされます。 # アプリ項目の関連付け アプリ項目の関連付けは、ファイルやフォルダとアプリ項目の関連付けを表します。フォルダとアプリ項目の関連付けは、そのフォルダのすべての子孫にカスケードされます。 --- ### アプリ項目の関連付け **Type:** resource | **Category:** api-resource | **Section:** API Reference アプリ項目の関連付けのリスト。 # アプリ項目の関連付け アプリ項目の関連付けのリスト。 --- ### イベントソース **Type:** resource | **Category:** api-resource | **Section:** API Reference イベントストリーム内のイベントを開始させるソースファイルまたはフォルダ。 # イベントソース イベントストリーム内のイベントを開始させるソースファイルまたはフォルダ。 --- ### イベントのLong pollingエンドポイントを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/options-events/ **Source:** [https://ja.developer.box.com/reference/options-events/](https://ja.developer.box.com/reference/options-events/) --- ### インスタンスIDでメタデータテンプレートを検索 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-metadata-templates/ **Source:** [https://ja.developer.box.com/reference/get-metadata-templates/](https://ja.developer.box.com/reference/get-metadata-templates/) --- ### ウェブリンク **Type:** resource | **Category:** api-resource | **Section:** API Reference ウェブリンクとは、URLを指すオブジェクトです。これらのオブジェクトはBoxウェブアプリケーション内ではブックマークとも呼ばれます。 ウェブリンクオブジェクトはファイルオブジェクトと同様に扱われ、通常のファイルに適用されるアクションの大部分もサポートしています。 # ウェブリンク ウェブリンクとは、URLを指すオブジェクトです。これらのオブジェクトはBoxウェブアプリケーション内ではブックマークとも呼ばれます。 ウェブリンクオブジェクトはファイルオブジェクトと同様に扱われ、通常のファイルに適用されるアクションの大部分もサポートしています。 --- ### ウェブリンク (Base) **Type:** resource | **Category:** api-resource | **Section:** API Reference ウェブリンクとは、URLを指すオブジェクトです。これらのオブジェクトはBoxウェブアプリケーション内ではブックマークとも呼ばれます。 ウェブリンクオブジェクトはファイルオブジェクトと同様に扱われ、通常のファイルに適用されるアクションの大部分もサポートしています。 # ウェブリンク (Base) ウェブリンクとは、URLを指すオブジェクトです。これらのオブジェクトはBoxウェブアプリケーション内ではブックマークとも呼ばれます。 ウェブリンクオブジェクトはファイルオブジェクトと同様に扱われ、通常のファイルに適用されるアクションの大部分もサポートしています。 --- ### ウェブリンク (Mini) **Type:** resource | **Category:** api-resource | **Section:** API Reference ウェブリンクとは、URLを指すオブジェクトです。これらのオブジェクトはBoxウェブアプリケーション内ではブックマークとも呼ばれます。 ウェブリンクオブジェクトはファイルオブジェクトと同様に扱われ、通常のファイルに適用されるアクションの大部分もサポートしています。 # ウェブリンク (Mini) ウェブリンクとは、URLを指すオブジェクトです。これらのオブジェクトはBoxウェブアプリケーション内ではブックマークとも呼ばれます。 ウェブリンクオブジェクトはファイルオブジェクトと同様に扱われ、通常のファイルに適用されるアクションの大部分もサポートしています。 --- ### ウェブリンクから共有リンクを削除 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/put-web-links-id--remove-shared-link/ **Source:** [https://ja.developer.box.com/reference/put-web-links-id--remove-shared-link/](https://ja.developer.box.com/reference/put-web-links-id--remove-shared-link/) --- ### ウェブリンクに共有リンクを追加 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/put-web-links-id--add-shared-link/ **Source:** [https://ja.developer.box.com/reference/put-web-links-id--add-shared-link/](https://ja.developer.box.com/reference/put-web-links-id--add-shared-link/) --- ### ウェブリンクの共有リンクを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-web-links-id--get-shared-link/ **Source:** [https://ja.developer.box.com/reference/get-web-links-id--get-shared-link/](https://ja.developer.box.com/reference/get-web-links-id--get-shared-link/) --- ### ウェブリンクの共有リンクを更新 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/put-web-links-id--update-shared-link/ **Source:** [https://ja.developer.box.com/reference/put-web-links-id--update-shared-link/](https://ja.developer.box.com/reference/put-web-links-id--update-shared-link/) --- ### ウェブリンクを作成 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/post-web-links/ **Source:** [https://ja.developer.box.com/reference/post-web-links/](https://ja.developer.box.com/reference/post-web-links/) --- ### ウェブリンクを削除 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/delete-web-links-id/ **Source:** [https://ja.developer.box.com/reference/delete-web-links-id/](https://ja.developer.box.com/reference/delete-web-links-id/) --- ### ウェブリンクを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-web-links-id/ **Source:** [https://ja.developer.box.com/reference/get-web-links-id/](https://ja.developer.box.com/reference/get-web-links-id/) --- ### ウェブリンクを完全に削除 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/delete-web-links-id-trash/ **Source:** [https://ja.developer.box.com/reference/delete-web-links-id-trash/](https://ja.developer.box.com/reference/delete-web-links-id-trash/) --- ### ウェブリンクを復元 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/post-web-links-id/ **Source:** [https://ja.developer.box.com/reference/post-web-links-id/](https://ja.developer.box.com/reference/post-web-links-id/) --- ### ウェブリンクを更新 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/put-web-links-id/ **Source:** [https://ja.developer.box.com/reference/put-web-links-id/](https://ja.developer.box.com/reference/put-web-links-id/) --- ### エージェントIDを指定してAIエージェントを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-ai-agents-id/ **Source:** [https://ja.developer.box.com/reference/get-ai-agents-id/](https://ja.developer.box.com/reference/get-ai-agents-id/) --- ### キーワードスキルカード **Type:** resource | **Category:** api-resource | **Section:** API Reference 一連のキーワードを含むスキルカード。 # キーワードスキルカード 一連のキーワードを含むスキルカード。 --- ### クライアントエラー **Type:** resource | **Category:** api-resource | **Section:** API Reference 一般的なエラー。 # クライアントエラー 一般的なエラー。 --- ### クライアントエラー **Type:** resource | **Category:** api-resource | **Section:** API Reference 一般的なエラー。 # クライアントエラー 一般的なエラー。 --- ### グループ (Base) **Type:** resource | **Category:** api-resource | **Section:** API Reference グループのBase版の表示。 # グループ (Base) グループのBase版の表示。 --- ### グループ (Full) **Type:** resource | **Category:** api-resource | **Section:** API Reference グループは複数のユーザーを含み、グループを使用するとコラボレーションなどの一部の操作をユーザーの代わりに実行できます。 # グループ (Full) グループは複数のユーザーを含み、グループを使用するとコラボレーションなどの一部の操作をユーザーの代わりに実行できます。 --- ### グループ (Mini) **Type:** resource | **Category:** api-resource | **Section:** API Reference グループのIDや名前を含むグループのMini版の表示。 # グループ (Mini) グループのIDや名前を含むグループのMini版の表示。 --- ### グループコラボレーションのリストを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-groups-id-collaborations/ **Source:** [https://ja.developer.box.com/reference/get-groups-id-collaborations/](https://ja.developer.box.com/reference/get-groups-id-collaborations/) --- ### グループのメンバーのリストを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-groups-id-memberships/ **Source:** [https://ja.developer.box.com/reference/get-groups-id-memberships/](https://ja.developer.box.com/reference/get-groups-id-memberships/) --- ### グループメンバーシップ **Type:** resource | **Category:** api-resource | **Section:** API Reference メンバーシップは、ユーザーがグループに属していることを示すために使用されます。 # グループメンバーシップ メンバーシップは、ユーザーがグループに属していることを示すために使用されます。 --- ### グループメンバーシップ **Type:** resource | **Category:** api-resource | **Section:** API Reference グループメンバーシップのリスト。 # グループメンバーシップ グループメンバーシップのリスト。 --- ### グループメンバーシップを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-group-memberships-id/ **Source:** [https://ja.developer.box.com/reference/get-group-memberships-id/](https://ja.developer.box.com/reference/get-group-memberships-id/) --- ### グループメンバーシップを更新 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/put-group-memberships-id/ **Source:** [https://ja.developer.box.com/reference/put-group-memberships-id/](https://ja.developer.box.com/reference/put-group-memberships-id/) --- ### グループを作成 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/post-groups/ **Source:** [https://ja.developer.box.com/reference/post-groups/](https://ja.developer.box.com/reference/post-groups/) --- ### グループを削除 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/delete-groups-id/ **Source:** [https://ja.developer.box.com/reference/delete-groups-id/](https://ja.developer.box.com/reference/delete-groups-id/) --- ### グループを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-groups-id/ **Source:** [https://ja.developer.box.com/reference/get-groups-id/](https://ja.developer.box.com/reference/get-groups-id/) --- ### グループを更新 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/put-groups-id/ **Source:** [https://ja.developer.box.com/reference/put-groups-id/](https://ja.developer.box.com/reference/put-groups-id/) --- ### ごみ箱に移動されたウェブリンクを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-web-links-id-trash/ **Source:** [https://ja.developer.box.com/reference/get-web-links-id-trash/](https://ja.developer.box.com/reference/get-web-links-id-trash/) --- ### ごみ箱内のウェブリンク **Type:** resource | **Category:** api-resource | **Section:** API Reference ごみ箱内のウェブリンクを表します。 # ごみ箱内のウェブリンク ごみ箱内のウェブリンクを表します。 --- ### ごみ箱内のウェブリンク (復元済み) **Type:** resource | **Category:** api-resource | **Section:** API Reference ごみ箱から復元されたウェブリンクを表します。 # ごみ箱内のウェブリンク (復元済み) ごみ箱から復元されたウェブリンクを表します。 --- ### ごみ箱内のファイル **Type:** resource | **Category:** api-resource | **Section:** API Reference ごみ箱内のファイルを表します。 # ごみ箱内のファイル ごみ箱内のファイルを表します。 --- ### ごみ箱内のファイル (復元済み) **Type:** resource | **Category:** api-resource | **Section:** API Reference ごみ箱から復元されたファイルを表します。 # ごみ箱内のファイル (復元済み) ごみ箱から復元されたファイルを表します。 --- ### ごみ箱内のファイルを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-files-id-trash/ **Source:** [https://ja.developer.box.com/reference/get-files-id-trash/](https://ja.developer.box.com/reference/get-files-id-trash/) --- ### ごみ箱内のフォルダ **Type:** resource | **Category:** api-resource | **Section:** API Reference ごみ箱内のフォルダを表します。 # ごみ箱内のフォルダ ごみ箱内のフォルダを表します。 --- ### ごみ箱内のフォルダ (復元済み) **Type:** resource | **Category:** api-resource | **Section:** API Reference ごみ箱から復元されたフォルダを表します。 # ごみ箱内のフォルダ (復元済み) ごみ箱から復元されたフォルダを表します。 --- ### ごみ箱内のフォルダを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-folders-id-trash/ **Source:** [https://ja.developer.box.com/reference/get-folders-id-trash/](https://ja.developer.box.com/reference/get-folders-id-trash/) --- ### ごみ箱内の項目のリストを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-folders-trash-items/ **Source:** [https://ja.developer.box.com/reference/get-folders-trash-items/](https://ja.developer.box.com/reference/get-folders-trash-items/) --- ### コメント (Base) **Type:** resource | **Category:** api-resource | **Section:** API Reference コメントのBase版の表示。 # コメント (Base) コメントのBase版の表示。 --- ### コメント (Full) **Type:** resource | **Category:** api-resource | **Section:** API Reference コメントとは、ファイルに関して作成されるメッセージです。コメントは単独で作成することも、他のコメントへの返答として作成することもできます。 # コメント (Full) コメントとは、ファイルに関して作成されるメッセージです。コメントは単独で作成することも、他のコメントへの返答として作成することもできます。 --- ### コメントを作成 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/post-comments/ **Source:** [https://ja.developer.box.com/reference/post-comments/](https://ja.developer.box.com/reference/post-comments/) --- ### コメントを削除 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/delete-comments-id/ **Source:** [https://ja.developer.box.com/reference/delete-comments-id/](https://ja.developer.box.com/reference/delete-comments-id/) --- ### コメントを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-comments-id/ **Source:** [https://ja.developer.box.com/reference/get-comments-id/](https://ja.developer.box.com/reference/get-comments-id/) --- ### コメントを更新 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/put-comments-id/ **Source:** [https://ja.developer.box.com/reference/put-comments-id/](https://ja.developer.box.com/reference/put-comments-id/) --- ### コラボレーションIDを指定してHubコラボレーションを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/v2025.0/get-hub-collaborations-id/ **Source:** [https://ja.developer.box.com/reference/v2025.0/get-hub-collaborations-id/](https://ja.developer.box.com/reference/v2025.0/get-hub-collaborations-id/) --- ### コラボレーションドメインの制限からのユーザー除外を作成 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/post-collaboration-whitelist-exempt-targets/ **Source:** [https://ja.developer.box.com/reference/post-collaboration-whitelist-exempt-targets/](https://ja.developer.box.com/reference/post-collaboration-whitelist-exempt-targets/) --- ### コラボレーションドメインの制限から除外するユーザーのリストを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-collaboration-whitelist-exempt-targets/ **Source:** [https://ja.developer.box.com/reference/get-collaboration-whitelist-exempt-targets/](https://ja.developer.box.com/reference/get-collaboration-whitelist-exempt-targets/) --- ### コラボレーションドメインの制限から除外するユーザーを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-collaboration-whitelist-exempt-targets-id/ **Source:** [https://ja.developer.box.com/reference/get-collaboration-whitelist-exempt-targets-id/](https://ja.developer.box.com/reference/get-collaboration-whitelist-exempt-targets-id/) --- ### コラボレーションを作成 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/post-collaborations/ **Source:** [https://ja.developer.box.com/reference/post-collaborations/](https://ja.developer.box.com/reference/post-collaborations/) --- ### コラボレーションを削除 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/delete-collaborations-id/ **Source:** [https://ja.developer.box.com/reference/delete-collaborations-id/](https://ja.developer.box.com/reference/delete-collaborations-id/) --- ### コラボレーションを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-collaborations-id/ **Source:** [https://ja.developer.box.com/reference/get-collaborations-id/](https://ja.developer.box.com/reference/get-collaborations-id/) --- ### コラボレーションを更新 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/put-collaborations-id/ **Source:** [https://ja.developer.box.com/reference/put-collaborations-id/](https://ja.developer.box.com/reference/put-collaborations-id/) --- ### コレクション項目のリストを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-collections-id-items/ **Source:** [https://ja.developer.box.com/reference/get-collections-id-items/](https://ja.developer.box.com/reference/get-collections-id-items/) --- ### コンテンツを検索 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-search/ **Source:** [https://ja.developer.box.com/reference/get-search/](https://ja.developer.box.com/reference/get-search/) --- ### サービス利用規約 **Type:** resource | **Category:** api-resource | **Section:** API Reference 1つのサービス利用規約に該当するとみなされるルートレベルのレコード。 # サービス利用規約 1つのサービス利用規約に該当するとみなされるルートレベルのレコード。 --- ### サービス利用規約 **Type:** resource | **Category:** api-resource | **Section:** API Reference サービス利用規約のリスト。 # サービス利用規約 サービス利用規約のリスト。 --- ### サービス利用規約 (Base) **Type:** resource | **Category:** api-resource | **Section:** API Reference 1つのサービス利用規約に該当するとみなされるルートレベルのレコード。 # サービス利用規約 (Base) 1つのサービス利用規約に該当するとみなされるルートレベルのレコード。 --- ### サービス利用規約のユーザーステータス **Type:** resource | **Category:** api-resource | **Section:** API Reference サービス利用規約とユーザーの関連付け。 # サービス利用規約のユーザーステータス サービス利用規約とユーザーの関連付け。 --- ### サービス利用規約のユーザーステータス **Type:** resource | **Category:** api-resource | **Section:** API Reference サービス利用規約のユーザーステータスのリスト。 # サービス利用規約のユーザーステータス サービス利用規約のユーザーステータスのリスト。 --- ### サービス利用規約のユーザーステータスのリストを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-terms-of-service-user-statuses/ **Source:** [https://ja.developer.box.com/reference/get-terms-of-service-user-statuses/](https://ja.developer.box.com/reference/get-terms-of-service-user-statuses/) --- ### サービス利用規約のリストを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-terms-of-services/ **Source:** [https://ja.developer.box.com/reference/get-terms-of-services/](https://ja.developer.box.com/reference/get-terms-of-services/) --- ### サービス利用規約を作成 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/post-terms-of-services/ **Source:** [https://ja.developer.box.com/reference/post-terms-of-services/](https://ja.developer.box.com/reference/post-terms-of-services/) --- ### サービス利用規約を取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-terms-of-services-id/ **Source:** [https://ja.developer.box.com/reference/get-terms-of-services-id/](https://ja.developer.box.com/reference/get-terms-of-services-id/) --- ### サービス利用規約を更新 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/put-terms-of-services-id/ **Source:** [https://ja.developer.box.com/reference/put-terms-of-services-id/](https://ja.developer.box.com/reference/put-terms-of-services-id/) --- ### スキルのWebhookペイロード **Type:** resource | **Category:** api-resource | **Section:** API Reference スキルの`invocation_url`に送信されるBoxスキルのペイロード。 # スキルのWebhookペイロード スキルの`invocation_url`に送信されるBoxスキルのペイロード。 --- ### ステータススキルカード **Type:** resource | **Category:** api-resource | **Section:** API Reference メタデータサイドバーにステータスメッセージを配置するBox Skillメタデータカード。 # ステータススキルカード メタデータサイドバーにステータスメッセージを配置するBox Skillメタデータカード。 --- ### ストレージポリシー **Type:** resource | **Category:** api-resource | **Section:** API Reference ストレージポリシーのリスト。 # ストレージポリシー ストレージポリシーのリスト。 --- ### ストレージポリシー **Type:** resource | **Category:** api-resource | **Section:** API Reference ストレージゾーンを示すストレージポリシーオブジェクト。 # ストレージポリシー ストレージゾーンを示すストレージポリシーオブジェクト。 --- ### ストレージポリシー (Mini) **Type:** resource | **Category:** api-resource | **Section:** API Reference ストレージポリシーオブジェクトのMini版の説明。 # ストレージポリシー (Mini) ストレージポリシーオブジェクトのMini版の説明。 --- ### ストレージポリシーのリストを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-storage-policies/ **Source:** [https://ja.developer.box.com/reference/get-storage-policies/](https://ja.developer.box.com/reference/get-storage-policies/) --- ### ストレージポリシーの割り当てを解除 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/delete-storage-policy-assignments-id/ **Source:** [https://ja.developer.box.com/reference/delete-storage-policy-assignments-id/](https://ja.developer.box.com/reference/delete-storage-policy-assignments-id/) --- ### ストレージポリシーを割り当て **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/post-storage-policy-assignments/ **Source:** [https://ja.developer.box.com/reference/post-storage-policy-assignments/](https://ja.developer.box.com/reference/post-storage-policy-assignments/) --- ### ストレージポリシーを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-storage-policies-id/ **Source:** [https://ja.developer.box.com/reference/get-storage-policies-id/](https://ja.developer.box.com/reference/get-storage-policies-id/) --- ### ストレージポリシー割り当て **Type:** resource | **Category:** api-resource | **Section:** API Reference ユーザーまたは企業へのストレージポリシーの割り当て。 # ストレージポリシー割り当て ユーザーまたは企業へのストレージポリシーの割り当て。 --- ### ストレージポリシー割り当て **Type:** resource | **Category:** api-resource | **Section:** API Reference ストレージポリシー割り当てのリスト。 # ストレージポリシー割り当て ストレージポリシー割り当てのリスト。 --- ### ストレージポリシー割り当てのリストを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-storage-policy-assignments/ **Source:** [https://ja.developer.box.com/reference/get-storage-policy-assignments/](https://ja.developer.box.com/reference/get-storage-policy-assignments/) --- ### ストレージポリシー割り当てを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-storage-policy-assignments-id/ **Source:** [https://ja.developer.box.com/reference/get-storage-policy-assignments-id/](https://ja.developer.box.com/reference/get-storage-policy-assignments-id/) --- ### ストレージポリシー割り当てを更新 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/put-storage-policy-assignments-id/ **Source:** [https://ja.developer.box.com/reference/put-storage-policy-assignments-id/](https://ja.developer.box.com/reference/put-storage-policy-assignments-id/) --- ### すべてのBox Doc Genジョブのリストを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/v2025.0/get-docgen-jobs/ **Source:** [https://ja.developer.box.com/reference/v2025.0/get-docgen-jobs/](https://ja.developer.box.com/reference/v2025.0/get-docgen-jobs/) --- ### すべてのHubのリストを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/v2025.0/get-hubs/ **Source:** [https://ja.developer.box.com/reference/v2025.0/get-hubs/](https://ja.developer.box.com/reference/v2025.0/get-hubs/) --- ### すべてのWebhookのリストを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-webhooks/ **Source:** [https://ja.developer.box.com/reference/get-webhooks/](https://ja.developer.box.com/reference/get-webhooks/) --- ### すべてのグローバルメタデータテンプレートのリストを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-metadata-templates-global/ **Source:** [https://ja.developer.box.com/reference/get-metadata-templates-global/](https://ja.developer.box.com/reference/get-metadata-templates-global/) --- ### すべてのコレクションのリストを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-collections/ **Source:** [https://ja.developer.box.com/reference/get-collections/](https://ja.developer.box.com/reference/get-collections/) --- ### すべてのファイルバージョンのリストを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-files-id-versions/ **Source:** [https://ja.developer.box.com/reference/get-files-id-versions/](https://ja.developer.box.com/reference/get-files-id-versions/) --- ### すべてのリーガルホールドポリシーのリストを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-legal-hold-policies/ **Source:** [https://ja.developer.box.com/reference/get-legal-hold-policies/](https://ja.developer.box.com/reference/get-legal-hold-policies/) --- ### すべての分類のリストを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-metadata-templates-enterprise-securityClassification-6VMVochwUWo-schema/ **Source:** [https://ja.developer.box.com/reference/get-metadata-templates-enterprise-securityClassification-6VMVochwUWo-schema/](https://ja.developer.box.com/reference/get-metadata-templates-enterprise-securityClassification-6VMVochwUWo-schema/) --- ### セッション終了メッセージ **Type:** resource | **Category:** api-resource | **Section:** API Reference 終了ジョブステータスについて通知するメッセージ。 # セッション終了メッセージ 終了ジョブステータスについて通知するメッセージ。 --- ### タイプとIDが指定されたエンティティ **Type:** resource | **Category:** api-resource | **Section:** API Reference タイプとIDが指定されたエンティティ。 # タイプとIDが指定されたエンティティ タイプとIDが指定されたエンティティ。 --- ### タイムラインスキルカード **Type:** resource | **Category:** api-resource | **Section:** API Reference タイムラインに画像のリストを配置するBox Skillメタデータカード。 # タイムラインスキルカード タイムラインに画像のリストを配置するBox Skillメタデータカード。 --- ### タスクを作成 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/post-tasks/ **Source:** [https://ja.developer.box.com/reference/post-tasks/](https://ja.developer.box.com/reference/post-tasks/) --- ### タスクを削除 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/delete-tasks-id/ **Source:** [https://ja.developer.box.com/reference/delete-tasks-id/](https://ja.developer.box.com/reference/delete-tasks-id/) --- ### タスクを割り当て **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/post-task-assignments/ **Source:** [https://ja.developer.box.com/reference/post-task-assignments/](https://ja.developer.box.com/reference/post-task-assignments/) --- ### タスクを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-tasks-id/ **Source:** [https://ja.developer.box.com/reference/get-tasks-id/](https://ja.developer.box.com/reference/get-tasks-id/) --- ### タスクを更新 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/put-tasks-id/ **Source:** [https://ja.developer.box.com/reference/put-tasks-id/](https://ja.developer.box.com/reference/put-tasks-id/) --- ### タスク割り当て **Type:** resource | **Category:** api-resource | **Section:** API Reference タスク割り当てでは、完了するためにどのタスクをどのユーザーに割り当てるかを定義します。 # タスク割り当て タスク割り当てでは、完了するためにどのタスクをどのユーザーに割り当てるかを定義します。 --- ### タスク割り当て **Type:** resource | **Category:** api-resource | **Section:** API Reference タスク割り当てのリスト。 # タスク割り当て タスク割り当てのリスト。 --- ### タスク割り当てのリストを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-tasks-id-assignments/ **Source:** [https://ja.developer.box.com/reference/get-tasks-id-assignments/](https://ja.developer.box.com/reference/get-tasks-id-assignments/) --- ### タスク割り当てを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-task-assignments-id/ **Source:** [https://ja.developer.box.com/reference/get-task-assignments-id/](https://ja.developer.box.com/reference/get-task-assignments-id/) --- ### タスク割り当てを更新 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/put-task-assignments-id/ **Source:** [https://ja.developer.box.com/reference/put-task-assignments-id/](https://ja.developer.box.com/reference/put-task-assignments-id/) --- ### タスク割り当てを解除 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/delete-task-assignments-id/ **Source:** [https://ja.developer.box.com/reference/delete-task-assignments-id/](https://ja.developer.box.com/reference/delete-task-assignments-id/) --- ### テキストを生成 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/post-ai-text-gen/ **Source:** [https://ja.developer.box.com/reference/post-ai-text-gen/](https://ja.developer.box.com/reference/post-ai-text-gen/) --- ### テキスト生成リクエスト用のAIエージェント **Type:** resource | **Category:** api-resource | **Section:** API Reference テキストの生成に使用されるAIエージェント。 # テキスト生成リクエスト用のAIエージェント テキストの生成に使用されるAIエージェント。 --- ### デバイスピンを削除 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/delete-device-pinners-id/ **Source:** [https://ja.developer.box.com/reference/delete-device-pinners-id/](https://ja.developer.box.com/reference/delete-device-pinners-id/) --- ### デバイスピンを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-device-pinners-id/ **Source:** [https://ja.developer.box.com/reference/get-device-pinners-id/](https://ja.developer.box.com/reference/get-device-pinners-id/) --- ### テンプレートのすべてのBox Doc Genジョブのリストを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/v2025.0/get-docgen-template-jobs-id/ **Source:** [https://ja.developer.box.com/reference/v2025.0/get-docgen-template-jobs-id/](https://ja.developer.box.com/reference/v2025.0/get-docgen-template-jobs-id/) --- ### テンプレート内のすべてのBox Doc Genテンプレートタグのリストを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/v2025.0/get-docgen-templates-id-tags/ **Source:** [https://ja.developer.box.com/reference/v2025.0/get-docgen-templates-id-tags/](https://ja.developer.box.com/reference/v2025.0/get-docgen-templates-id-tags/) --- ### ドメインの制限から除外されるユーザーのリストからユーザーを削除 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/delete-collaboration-whitelist-exempt-targets-id/ **Source:** [https://ja.developer.box.com/reference/delete-collaboration-whitelist-exempt-targets-id/](https://ja.developer.box.com/reference/delete-collaboration-whitelist-exempt-targets-id/) --- ### トランスクリプトスキルカード。 **Type:** resource | **Category:** api-resource | **Section:** API Reference ファイルにトランスクリプトを追加するBox Skillメタデータカード。 # トランスクリプトスキルカード。 ファイルにトランスクリプトを追加するBox Skillメタデータカード。 --- ### パーツのアップロード (Mini) **Type:** resource | **Category:** api-resource | **Section:** API Reference アップロードセッションチャンクのBase版の表示。 # パーツのアップロード (Mini) アップロードセッションチャンクのBase版の表示。 --- ### パーツのリストを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-files-upload-sessions-id-parts/ **Source:** [https://ja.developer.box.com/reference/get-files-upload-sessions-id-parts/](https://ja.developer.box.com/reference/get-files-upload-sessions-id-parts/) --- ### バッチIDを指定してBox Doc Genジョブを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/v2025.0/get-docgen-batch-jobs-id/ **Source:** [https://ja.developer.box.com/reference/v2025.0/get-docgen-batch-jobs-id/](https://ja.developer.box.com/reference/v2025.0/get-docgen-batch-jobs-id/) --- ### ファイル (Base) **Type:** resource | **Category:** api-resource | **Section:** API Reference 最も基本的なファイルのBase版の表示。`fields`クエリパラメータを使用すると、最小限の数のフィールドが返されます。 # ファイル (Base) 最も基本的なファイルのBase版の表示。`fields`クエリパラメータを使用すると、最小限の数のフィールドが返されます。 --- ### ファイル (Full) **Type:** resource | **Category:** api-resource | **Section:** API Reference 任意のファイルAPIエンドポイントからデフォルトで返される可能性があるファイルのFull版の表示。 # ファイル (Full) 任意のファイルAPIエンドポイントからデフォルトで返される可能性があるファイルのFull版の表示。 --- ### ファイル (Mini) **Type:** resource | **Category:** api-resource | **Section:** API Reference 他のリソースの下にネストされたときに使用されるファイルのMini版の表示。 # ファイル (Mini) 他のリソースの下にネストされたときに使用されるファイルのMini版の表示。 --- ### ファイル (競合) **Type:** resource | **Category:** api-resource | **Section:** API Reference 以前出力されていたファイルの表示。 # ファイル (競合) 以前出力されていたファイルの表示。 --- ### ファイルからBox Skillカードを削除 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/delete-files-id-metadata-global-boxSkillsCards/ **Source:** [https://ja.developer.box.com/reference/delete-files-id-metadata-global-boxSkillsCards/](https://ja.developer.box.com/reference/delete-files-id-metadata-global-boxSkillsCards/) --- ### ファイルからメタデータインスタンスを削除 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/delete-files-id-metadata-id-id/ **Source:** [https://ja.developer.box.com/reference/delete-files-id-metadata-id-id/](https://ja.developer.box.com/reference/delete-files-id-metadata-id-id/) --- ### ファイルから共有リンクを削除 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/put-files-id--remove-shared-link/ **Source:** [https://ja.developer.box.com/reference/put-files-id--remove-shared-link/](https://ja.developer.box.com/reference/put-files-id--remove-shared-link/) --- ### ファイルから分類を削除 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/delete-files-id-metadata-enterprise-securityClassification-6VMVochwUWo/ **Source:** [https://ja.developer.box.com/reference/delete-files-id-metadata-enterprise-securityClassification-6VMVochwUWo/](https://ja.developer.box.com/reference/delete-files-id-metadata-enterprise-securityClassification-6VMVochwUWo/) --- ### ファイルから電子すかしを削除 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/delete-files-id-watermark/ **Source:** [https://ja.developer.box.com/reference/delete-files-id-watermark/](https://ja.developer.box.com/reference/delete-files-id-watermark/) --- ### ファイルサムネイルを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-files-id-thumbnail-id/ **Source:** [https://ja.developer.box.com/reference/get-files-id-thumbnail-id/](https://ja.developer.box.com/reference/get-files-id-thumbnail-id/) --- ### ファイルにBox Skillカードを作成 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/post-files-id-metadata-global-boxSkillsCards/ **Source:** [https://ja.developer.box.com/reference/post-files-id-metadata-global-boxSkillsCards/](https://ja.developer.box.com/reference/post-files-id-metadata-global-boxSkillsCards/) --- ### ファイルにメタデータインスタンスを作成 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/post-files-id-metadata-id-id/ **Source:** [https://ja.developer.box.com/reference/post-files-id-metadata-id-id/](https://ja.developer.box.com/reference/post-files-id-metadata-id-id/) --- ### ファイルに共有リンクを追加 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/put-files-id--add-shared-link/ **Source:** [https://ja.developer.box.com/reference/put-files-id--add-shared-link/](https://ja.developer.box.com/reference/put-files-id--add-shared-link/) --- ### ファイルに分類を追加 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/post-files-id-metadata-enterprise-securityClassification-6VMVochwUWo/ **Source:** [https://ja.developer.box.com/reference/post-files-id-metadata-enterprise-securityClassification-6VMVochwUWo/](https://ja.developer.box.com/reference/post-files-id-metadata-enterprise-securityClassification-6VMVochwUWo/) --- ### ファイルに対するタスクのリストを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-files-id-tasks/ **Source:** [https://ja.developer.box.com/reference/get-files-id-tasks/](https://ja.developer.box.com/reference/get-files-id-tasks/) --- ### ファイルに電子すかしを適用 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/put-files-id-watermark/ **Source:** [https://ja.developer.box.com/reference/put-files-id-watermark/](https://ja.developer.box.com/reference/put-files-id-watermark/) --- ### ファイルのBox Skillカードのリストを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-files-id-metadata-global-boxSkillsCards/ **Source:** [https://ja.developer.box.com/reference/get-files-id-metadata-global-boxSkillsCards/](https://ja.developer.box.com/reference/get-files-id-metadata-global-boxSkillsCards/) --- ### ファイルのBox Skillカードを更新 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/put-files-id-metadata-global-boxSkillsCards/ **Source:** [https://ja.developer.box.com/reference/put-files-id-metadata-global-boxSkillsCards/](https://ja.developer.box.com/reference/put-files-id-metadata-global-boxSkillsCards/) --- ### ファイルのアプリ項目の関連付けのリストを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-files-id-app-item-associations/ **Source:** [https://ja.developer.box.com/reference/get-files-id-app-item-associations/](https://ja.developer.box.com/reference/get-files-id-app-item-associations/) --- ### ファイルのコメントのリストを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-files-id-comments/ **Source:** [https://ja.developer.box.com/reference/get-files-id-comments/](https://ja.developer.box.com/reference/get-files-id-comments/) --- ### ファイルのコラボレーションのリストを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-files-id-collaborations/ **Source:** [https://ja.developer.box.com/reference/get-files-id-collaborations/](https://ja.developer.box.com/reference/get-files-id-collaborations/) --- ### ファイルのすべてのBox Skillカードを更新 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/put-skill-invocations-id/ **Source:** [https://ja.developer.box.com/reference/put-skill-invocations-id/](https://ja.developer.box.com/reference/put-skill-invocations-id/) --- ### ファイルのメタデータインスタンスのリストを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-files-id-metadata/ **Source:** [https://ja.developer.box.com/reference/get-files-id-metadata/](https://ja.developer.box.com/reference/get-files-id-metadata/) --- ### ファイルのメタデータインスタンスを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-files-id-metadata-id-id/ **Source:** [https://ja.developer.box.com/reference/get-files-id-metadata-id-id/](https://ja.developer.box.com/reference/get-files-id-metadata-id-id/) --- ### ファイルのメタデータインスタンスを更新 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/put-files-id-metadata-id-id/ **Source:** [https://ja.developer.box.com/reference/put-files-id-metadata-id-id/](https://ja.developer.box.com/reference/put-files-id-metadata-id-id/) --- ### ファイルのリテンションを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-file-version-retentions-id/ **Source:** [https://ja.developer.box.com/reference/get-file-version-retentions-id/](https://ja.developer.box.com/reference/get-file-version-retentions-id/) --- ### ファイルの一部をアップロード **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/put-files-upload-sessions-id/ **Source:** [https://ja.developer.box.com/reference/put-files-upload-sessions-id/](https://ja.developer.box.com/reference/put-files-upload-sessions-id/) --- ### ファイルの共有リンクを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-files-id--get-shared-link/ **Source:** [https://ja.developer.box.com/reference/get-files-id--get-shared-link/](https://ja.developer.box.com/reference/get-files-id--get-shared-link/) --- ### ファイルの共有リンクを更新 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/put-files-id--update-shared-link/ **Source:** [https://ja.developer.box.com/reference/put-files-id--update-shared-link/](https://ja.developer.box.com/reference/put-files-id--update-shared-link/) --- ### ファイルの分類を取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-files-id-metadata-enterprise-securityClassification-6VMVochwUWo/ **Source:** [https://ja.developer.box.com/reference/get-files-id-metadata-enterprise-securityClassification-6VMVochwUWo/](https://ja.developer.box.com/reference/get-files-id-metadata-enterprise-securityClassification-6VMVochwUWo/) --- ### ファイルの分類を更新 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/put-files-id-metadata-enterprise-securityClassification-6VMVochwUWo/ **Source:** [https://ja.developer.box.com/reference/put-files-id-metadata-enterprise-securityClassification-6VMVochwUWo/](https://ja.developer.box.com/reference/put-files-id-metadata-enterprise-securityClassification-6VMVochwUWo/) --- ### ファイルの電子すかしを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-files-id-watermark/ **Source:** [https://ja.developer.box.com/reference/get-files-id-watermark/](https://ja.developer.box.com/reference/get-files-id-watermark/) --- ### ファイルバージョン **Type:** resource | **Category:** api-resource | **Section:** API Reference ファイルバージョンのStandard版の表示。 # ファイルバージョン ファイルバージョンのStandard版の表示。 --- ### ファイルバージョン **Type:** resource | **Category:** api-resource | **Section:** API Reference ファイルバージョンのリスト。 # ファイルバージョン ファイルバージョンのリスト。 --- ### ファイルバージョン (Base) **Type:** resource | **Category:** api-resource | **Section:** API Reference 最も基本的なファイルバージョンのBase版の表示。`fields`クエリパラメータを使用すると、最小限の数のフィールドが返されます。 # ファイルバージョン (Base) 最も基本的なファイルバージョンのBase版の表示。`fields`クエリパラメータを使用すると、最小限の数のフィールドが返されます。 --- ### ファイルバージョン (Full) **Type:** resource | **Category:** api-resource | **Section:** API Reference 任意のファイルバージョンAPIエンドポイントからデフォルトで返される可能性がある、ファイルバージョンのFull版の表示。 # ファイルバージョン (Full) 任意のファイルバージョンAPIエンドポイントからデフォルトで返される可能性がある、ファイルバージョンのFull版の表示。 --- ### ファイルバージョン (Mini) **Type:** resource | **Category:** api-resource | **Section:** API Reference 他のリソース内にネストされたときに使用されるファイルバージョンのMini版の表示。 # ファイルバージョン (Mini) 他のリソース内にネストされたときに使用されるファイルバージョンのMini版の表示。 --- ### ファイルバージョンリーガルホールド **Type:** resource | **Category:** api-resource | **Section:** API Reference ファイルバージョンリーガルホールドは、ファイルバージョンのすべてのリーガルホールドを表すエンティティです。 # ファイルバージョンリーガルホールド ファイルバージョンリーガルホールドは、ファイルバージョンのすべてのリーガルホールドを表すエンティティです。 --- ### ファイルバージョンリーガルホールド **Type:** resource | **Category:** api-resource | **Section:** API Reference リーガルホールドが設定されたファイルバージョンのリスト。 # ファイルバージョンリーガルホールド リーガルホールドが設定されたファイルバージョンのリスト。 --- ### ファイルバージョンリーガルホールドのリストを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-file-version-legal-holds/ **Source:** [https://ja.developer.box.com/reference/get-file-version-legal-holds/](https://ja.developer.box.com/reference/get-file-version-legal-holds/) --- ### ファイルバージョンリーガルホールドを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-file-version-legal-holds-id/ **Source:** [https://ja.developer.box.com/reference/get-file-version-legal-holds-id/](https://ja.developer.box.com/reference/get-file-version-legal-holds-id/) --- ### ファイルバージョンリテンション **Type:** resource | **Category:** api-resource | **Section:** API Reference リテンションポリシーは、指定した期間にわたってコンテンツが完全に削除されるのを防止します。管理者はポリシーを特定のフォルダや企業全体に適用できます。ファイルバージョンリテンションとは、保持されているファイルバージョンのレコードです。この機能を使用するには、アプリケーション管理コンソールから、APIキーに対して \[リテンションポリシーを管理する] スコープを有効にする必要があります。 **注**: ファイルリテンションAPIは**非推奨**になりました。リテンションの対象となるファイルおよびファイルバージョンに関する情報を取得するには、[リテンションの対象となるファイル](e://get-retention-policy-assignments-id-files-under-retention)または[リテンションの対象となるファイルバージョン](e://get-retention-policy-assignments-id-file-versions-under-retention)のエンドポイントを参照してください。 # ファイルバージョンリテンション リテンションポリシーは、指定した期間にわたってコンテンツが完全に削除されるのを防止します。管理者はポリシーを特定のフォルダや企業全体に適用できます。ファイルバージョンリテンションとは、保持されているファイルバージョンのレコードです。この機能を使用するには、アプリケーション管理コンソールから、APIキーに対して \[リテンションポリシーを管理する] スコープを有効にする必要があります。 **注**: ファイルリテンションAPIは**非推奨**になりました。リテンションの対象となるファイルおよびファイルバージョンに関する情報を取得するには、[リテンションの対象となるファイル](e://get-retention-policy-assignments-id-files-under-retention)または[リテンションの対象となるファイルバージョン](e://get-retention-policy-assignments-id-file-versions-under-retention)のエンドポイントを参照してください。 --- ### ファイルバージョンリテンション **Type:** resource | **Category:** api-resource | **Section:** API Reference ファイルバージョンリテンションのリスト。 **注**: ファイルリテンションAPIは**非推奨**になりました。リテンションの対象となるファイルおよびファイルバージョンに関する情報を取得するには、[リテンションの対象となるファイル](e://get-retention-policy-assignments-id-files-under-retention)または[リテンションの対象となるファイルバージョン](e://get-retention-policy-assignments-id-file-versions-under-retention)のエンドポイントを参照してください。 # ファイルバージョンリテンション ファイルバージョンリテンションのリスト。 **注**: ファイルリテンションAPIは**非推奨**になりました。リテンションの対象となるファイルおよびファイルバージョンに関する情報を取得するには、[リテンションの対象となるファイル](e://get-retention-policy-assignments-id-files-under-retention)または[リテンションの対象となるファイルバージョン](e://get-retention-policy-assignments-id-file-versions-under-retention)のエンドポイントを参照してください。 --- ### ファイルバージョンリテンションのリストを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-file-version-retentions/ **Source:** [https://ja.developer.box.com/reference/get-file-version-retentions/](https://ja.developer.box.com/reference/get-file-version-retentions/) --- ### ファイルバージョンをアップロード **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/post-files-id-content/ **Source:** [https://ja.developer.box.com/reference/post-files-id-content/](https://ja.developer.box.com/reference/post-files-id-content/) --- ### ファイルバージョンを削除 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/delete-files-id-versions-id/ **Source:** [https://ja.developer.box.com/reference/delete-files-id-versions-id/](https://ja.developer.box.com/reference/delete-files-id-versions-id/) --- ### ファイルバージョンを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-files-id-versions-id/ **Source:** [https://ja.developer.box.com/reference/get-files-id-versions-id/](https://ja.developer.box.com/reference/get-files-id-versions-id/) --- ### ファイルバージョンを復元 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/put-files-id-versions-id/ **Source:** [https://ja.developer.box.com/reference/put-files-id-versions-id/](https://ja.developer.box.com/reference/put-files-id-versions-id/) --- ### ファイルバージョンを昇格 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/post-files-id-versions-current/ **Source:** [https://ja.developer.box.com/reference/post-files-id-versions-current/](https://ja.developer.box.com/reference/post-files-id-versions-current/) --- ### ファイルリクエスト **Type:** resource | **Category:** api-resource | **Section:** API Reference 任意のファイルリクエストAPIエンドポイントからデフォルトで返されるファイルリクエストのStandard版の表示。 # ファイルリクエスト 任意のファイルリクエストAPIエンドポイントからデフォルトで返されるファイルリクエストのStandard版の表示。 --- ### ファイルリクエストをコピー **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/post-file-requests-id-copy/ **Source:** [https://ja.developer.box.com/reference/post-file-requests-id-copy/](https://ja.developer.box.com/reference/post-file-requests-id-copy/) --- ### ファイルリクエストを削除 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/delete-file-requests-id/ **Source:** [https://ja.developer.box.com/reference/delete-file-requests-id/](https://ja.developer.box.com/reference/delete-file-requests-id/) --- ### ファイルリクエストを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-file-requests-id/ **Source:** [https://ja.developer.box.com/reference/get-file-requests-id/](https://ja.developer.box.com/reference/get-file-requests-id/) --- ### ファイルリクエストを更新 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/put-file-requests-id/ **Source:** [https://ja.developer.box.com/reference/put-file-requests-id/](https://ja.developer.box.com/reference/put-file-requests-id/) --- ### ファイルをアップロード **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/post-files-content/ **Source:** [https://ja.developer.box.com/reference/post-files-content/](https://ja.developer.box.com/reference/post-files-content/) --- ### ファイルをコピー **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/post-files-id-copy/ **Source:** [https://ja.developer.box.com/reference/post-files-id-copy/](https://ja.developer.box.com/reference/post-files-id-copy/) --- ### ファイルをダウンロード **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-files-id-content/ **Source:** [https://ja.developer.box.com/reference/get-files-id-content/](https://ja.developer.box.com/reference/get-files-id-content/) --- ### ファイルを削除 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/delete-files-id/ **Source:** [https://ja.developer.box.com/reference/delete-files-id/](https://ja.developer.box.com/reference/delete-files-id/) --- ### ファイルを完全に削除 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/delete-files-id-trash/ **Source:** [https://ja.developer.box.com/reference/delete-files-id-trash/](https://ja.developer.box.com/reference/delete-files-id-trash/) --- ### ファイルを復元 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/post-files-id/ **Source:** [https://ja.developer.box.com/reference/post-files-id/](https://ja.developer.box.com/reference/post-files-id/) --- ### ファイルを更新 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/put-files-id/ **Source:** [https://ja.developer.box.com/reference/put-files-id/](https://ja.developer.box.com/reference/put-files-id/) --- ### ファイル情報を取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-files-id/ **Source:** [https://ja.developer.box.com/reference/get-files-id/](https://ja.developer.box.com/reference/get-files-id/) --- ### フォルダ (Base) **Type:** resource | **Category:** api-resource | **Section:** API Reference 最も基本的なフォルダのBase版の表示。`fields`クエリパラメータを使用すると、最小限の数のフィールドが返されます。 # フォルダ (Base) 最も基本的なフォルダのBase版の表示。`fields`クエリパラメータを使用すると、最小限の数のフィールドが返されます。 --- ### フォルダ (Full) **Type:** resource | **Category:** api-resource | **Section:** API Reference 任意のフォルダAPIエンドポイントからデフォルトで返される可能性があるフォルダのFull版の表示。 # フォルダ (Full) 任意のフォルダAPIエンドポイントからデフォルトで返される可能性があるフォルダのFull版の表示。 --- ### フォルダ (Mini) **Type:** resource | **Category:** api-resource | **Section:** API Reference 他のリソースの下にネストされたときに使用されるファイルバージョンのMini版の表示。 # フォルダ (Mini) 他のリソースの下にネストされたときに使用されるファイルバージョンのMini版の表示。 --- ### フォルダからメタデータインスタンスを削除 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/delete-folders-id-metadata-id-id/ **Source:** [https://ja.developer.box.com/reference/delete-folders-id-metadata-id-id/](https://ja.developer.box.com/reference/delete-folders-id-metadata-id-id/) --- ### フォルダから共有リンクを削除 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/put-folders-id--remove-shared-link/ **Source:** [https://ja.developer.box.com/reference/put-folders-id--remove-shared-link/](https://ja.developer.box.com/reference/put-folders-id--remove-shared-link/) --- ### フォルダから分類を削除 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/delete-folders-id-metadata-enterprise-securityClassification-6VMVochwUWo/ **Source:** [https://ja.developer.box.com/reference/delete-folders-id-metadata-enterprise-securityClassification-6VMVochwUWo/](https://ja.developer.box.com/reference/delete-folders-id-metadata-enterprise-securityClassification-6VMVochwUWo/) --- ### フォルダから電子すかしを削除 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/delete-folders-id-watermark/ **Source:** [https://ja.developer.box.com/reference/delete-folders-id-watermark/](https://ja.developer.box.com/reference/delete-folders-id-watermark/) --- ### フォルダコラボレーションのリストを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-folders-id-collaborations/ **Source:** [https://ja.developer.box.com/reference/get-folders-id-collaborations/](https://ja.developer.box.com/reference/get-folders-id-collaborations/) --- ### フォルダにメタデータインスタンスを作成 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/post-folders-id-metadata-id-id/ **Source:** [https://ja.developer.box.com/reference/post-folders-id-metadata-id-id/](https://ja.developer.box.com/reference/post-folders-id-metadata-id-id/) --- ### フォルダにメタデータカスケードポリシーを強制適用 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/post-metadata-cascade-policies-id-apply/ **Source:** [https://ja.developer.box.com/reference/post-metadata-cascade-policies-id-apply/](https://ja.developer.box.com/reference/post-metadata-cascade-policies-id-apply/) --- ### フォルダに共有リンクを追加 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/put-folders-id--add-shared-link/ **Source:** [https://ja.developer.box.com/reference/put-folders-id--add-shared-link/](https://ja.developer.box.com/reference/put-folders-id--add-shared-link/) --- ### フォルダに分類を追加 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/post-folders-id-metadata-enterprise-securityClassification-6VMVochwUWo/ **Source:** [https://ja.developer.box.com/reference/post-folders-id-metadata-enterprise-securityClassification-6VMVochwUWo/](https://ja.developer.box.com/reference/post-folders-id-metadata-enterprise-securityClassification-6VMVochwUWo/) --- ### フォルダに電子すかしを適用 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/put-folders-id-watermark/ **Source:** [https://ja.developer.box.com/reference/put-folders-id-watermark/](https://ja.developer.box.com/reference/put-folders-id-watermark/) --- ### フォルダのアプリ項目の関連付けのリストを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-folders-id-app-item-associations/ **Source:** [https://ja.developer.box.com/reference/get-folders-id-app-item-associations/](https://ja.developer.box.com/reference/get-folders-id-app-item-associations/) --- ### フォルダのメタデータインスタンスのリストを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-folders-id-metadata/ **Source:** [https://ja.developer.box.com/reference/get-folders-id-metadata/](https://ja.developer.box.com/reference/get-folders-id-metadata/) --- ### フォルダのメタデータインスタンスを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-folders-id-metadata-id-id/ **Source:** [https://ja.developer.box.com/reference/get-folders-id-metadata-id-id/](https://ja.developer.box.com/reference/get-folders-id-metadata-id-id/) --- ### フォルダのメタデータインスタンスを更新 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/put-folders-id-metadata-id-id/ **Source:** [https://ja.developer.box.com/reference/put-folders-id-metadata-id-id/](https://ja.developer.box.com/reference/put-folders-id-metadata-id-id/) --- ### フォルダの共有リンクを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-folders-id--get-shared-link/ **Source:** [https://ja.developer.box.com/reference/get-folders-id--get-shared-link/](https://ja.developer.box.com/reference/get-folders-id--get-shared-link/) --- ### フォルダの共有リンクを更新 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/put-folders-id--update-shared-link/ **Source:** [https://ja.developer.box.com/reference/put-folders-id--update-shared-link/](https://ja.developer.box.com/reference/put-folders-id--update-shared-link/) --- ### フォルダの分類を取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-folders-id-metadata-enterprise-securityClassification-6VMVochwUWo/ **Source:** [https://ja.developer.box.com/reference/get-folders-id-metadata-enterprise-securityClassification-6VMVochwUWo/](https://ja.developer.box.com/reference/get-folders-id-metadata-enterprise-securityClassification-6VMVochwUWo/) --- ### フォルダの分類を更新 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/put-folders-id-metadata-enterprise-securityClassification-6VMVochwUWo/ **Source:** [https://ja.developer.box.com/reference/put-folders-id-metadata-enterprise-securityClassification-6VMVochwUWo/](https://ja.developer.box.com/reference/put-folders-id-metadata-enterprise-securityClassification-6VMVochwUWo/) --- ### フォルダの電子すかしを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-folders-id-watermark/ **Source:** [https://ja.developer.box.com/reference/get-folders-id-watermark/](https://ja.developer.box.com/reference/get-folders-id-watermark/) --- ### フォルダロック **Type:** resource | **Category:** api-resource | **Section:** API Reference フォルダロックでは、特定のフォルダが移動または削除されないように、フォルダ所有者によって設定されるアクセス制限を定義します。 # フォルダロック フォルダロックでは、特定のフォルダが移動または削除されないように、フォルダ所有者によって設定されるアクセス制限を定義します。 --- ### フォルダロック **Type:** resource | **Category:** api-resource | **Section:** API Reference フォルダロックのリスト。 # フォルダロック フォルダロックのリスト。 --- ### フォルダロックのリストを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-folder-locks/ **Source:** [https://ja.developer.box.com/reference/get-folder-locks/](https://ja.developer.box.com/reference/get-folder-locks/) --- ### フォルダロックを作成 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/post-folder-locks/ **Source:** [https://ja.developer.box.com/reference/post-folder-locks/](https://ja.developer.box.com/reference/post-folder-locks/) --- ### フォルダロックを削除 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/delete-folder-locks-id/ **Source:** [https://ja.developer.box.com/reference/delete-folder-locks-id/](https://ja.developer.box.com/reference/delete-folder-locks-id/) --- ### フォルダをコピー **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/post-folders-id-copy/ **Source:** [https://ja.developer.box.com/reference/post-folders-id-copy/](https://ja.developer.box.com/reference/post-folders-id-copy/) --- ### フォルダを作成 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/post-folders/ **Source:** [https://ja.developer.box.com/reference/post-folders/](https://ja.developer.box.com/reference/post-folders/) --- ### フォルダを削除 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/delete-folders-id/ **Source:** [https://ja.developer.box.com/reference/delete-folders-id/](https://ja.developer.box.com/reference/delete-folders-id/) --- ### フォルダを完全に削除 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/delete-folders-id-trash/ **Source:** [https://ja.developer.box.com/reference/delete-folders-id-trash/](https://ja.developer.box.com/reference/delete-folders-id-trash/) --- ### フォルダを復元 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/post-folders-id/ **Source:** [https://ja.developer.box.com/reference/post-folders-id/](https://ja.developer.box.com/reference/post-folders-id/) --- ### フォルダを更新 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/put-folders-id/ **Source:** [https://ja.developer.box.com/reference/put-folders-id/](https://ja.developer.box.com/reference/put-folders-id/) --- ### フォルダ内の項目のリストを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-folders-id-items/ **Source:** [https://ja.developer.box.com/reference/get-folders-id-items/](https://ja.developer.box.com/reference/get-folders-id-items/) --- ### フォルダ情報を取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-folders-id/ **Source:** [https://ja.developer.box.com/reference/get-folders-id/](https://ja.developer.box.com/reference/get-folders-id/) --- ### メールエイリアス **Type:** resource | **Category:** api-resource | **Section:** API Reference ユーザーのメールエイリアス。 # メールエイリアス ユーザーのメールエイリアス。 --- ### メールエイリアス **Type:** resource | **Category:** api-resource | **Section:** API Reference メールエイリアスのリスト。 # メールエイリアス メールエイリアスのリスト。 --- ### メールエイリアスを作成 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/post-users-id-email-aliases/ **Source:** [https://ja.developer.box.com/reference/post-users-id-email-aliases/](https://ja.developer.box.com/reference/post-users-id-email-aliases/) --- ### メールエイリアスを削除 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/delete-users-id-email-aliases-id/ **Source:** [https://ja.developer.box.com/reference/delete-users-id-email-aliases-id/](https://ja.developer.box.com/reference/delete-users-id-email-aliases-id/) --- ### メタデータインスタンス **Type:** resource | **Category:** api-resource | **Section:** API Reference ファイルまたはフォルダに適用された、メタデータテンプレートのインスタンス。 # メタデータインスタンス ファイルまたはフォルダに適用された、メタデータテンプレートのインスタンス。 --- ### メタデータインスタンス **Type:** resource | **Category:** api-resource | **Section:** API Reference ファイルまたはフォルダに適用されているメタデータインスタンスのリスト。 # メタデータインスタンス ファイルまたはフォルダに適用されているメタデータインスタンスのリスト。 --- ### メタデータインスタンス (Base) **Type:** resource | **Category:** api-resource | **Section:** API Reference メタデータインスタンスのBase版の表示。 # メタデータインスタンス (Base) メタデータインスタンスのBase版の表示。 --- ### メタデータインスタンス (Full) **Type:** resource | **Category:** api-resource | **Section:** API Reference ファイルまたはフォルダに適用された、メタデータテンプレートのインスタンス。 # メタデータインスタンス (Full) ファイルまたはフォルダに適用された、メタデータテンプレートのインスタンス。 --- ### メタデータエラー **Type:** resource | **Category:** api-resource | **Section:** API Reference 一般的なメタデータ操作エラー。 # メタデータエラー 一般的なメタデータ操作エラー。 --- ### メタデータカスケードポリシー **Type:** resource | **Category:** api-resource | **Section:** API Reference メタデータカスケードポリシーのリスト。 # メタデータカスケードポリシー メタデータカスケードポリシーのリスト。 --- ### メタデータカスケードポリシー **Type:** resource | **Category:** api-resource | **Section:** API Reference メタデータカスケードポリシーにより、メタデータテンプレートインスタンスが自動的にターゲットフォルダ内のすべてのファイルとフォルダに適用されます。 # メタデータカスケードポリシー メタデータカスケードポリシーにより、メタデータテンプレートインスタンスが自動的にターゲットフォルダ内のすべてのファイルとフォルダに適用されます。 --- ### メタデータカスケードポリシーのリストを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-metadata-cascade-policies/ **Source:** [https://ja.developer.box.com/reference/get-metadata-cascade-policies/](https://ja.developer.box.com/reference/get-metadata-cascade-policies/) --- ### メタデータカスケードポリシーを作成 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/post-metadata-cascade-policies/ **Source:** [https://ja.developer.box.com/reference/post-metadata-cascade-policies/](https://ja.developer.box.com/reference/post-metadata-cascade-policies/) --- ### メタデータカスケードポリシーを削除 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/delete-metadata-cascade-policies-id/ **Source:** [https://ja.developer.box.com/reference/delete-metadata-cascade-policies-id/](https://ja.developer.box.com/reference/delete-metadata-cascade-policies-id/) --- ### メタデータカスケードポリシーを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-metadata-cascade-policies-id/ **Source:** [https://ja.developer.box.com/reference/get-metadata-cascade-policies-id/](https://ja.developer.box.com/reference/get-metadata-cascade-policies-id/) --- ### メタデータクエリの検索結果 **Type:** resource | **Category:** api-resource | **Section:** API Reference メタデータクエリと一致したファイルおよびフォルダのページ。 # メタデータクエリの検索結果 メタデータクエリと一致したファイルおよびフォルダのページ。 --- ### メタデータテンプレート **Type:** resource | **Category:** api-resource | **Section:** API Reference ファイルやフォルダに適用可能なメタデータのテンプレート。 # メタデータテンプレート ファイルやフォルダに適用可能なメタデータのテンプレート。 --- ### メタデータテンプレート **Type:** resource | **Category:** api-resource | **Section:** API Reference メタデータテンプレートのリスト。 # メタデータテンプレート メタデータテンプレートのリスト。 --- ### メタデータテンプレートを作成 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/post-metadata-templates-schema/ **Source:** [https://ja.developer.box.com/reference/post-metadata-templates-schema/](https://ja.developer.box.com/reference/post-metadata-templates-schema/) --- ### メタデータテンプレートを削除 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/delete-metadata-templates-id-id-schema/ **Source:** [https://ja.developer.box.com/reference/delete-metadata-templates-id-id-schema/](https://ja.developer.box.com/reference/delete-metadata-templates-id-id-schema/) --- ### メタデータテンプレートを更新 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/put-metadata-templates-id-id-schema/ **Source:** [https://ja.developer.box.com/reference/put-metadata-templates-id-id-schema/](https://ja.developer.box.com/reference/put-metadata-templates-id-id-schema/) --- ### メタデータによるファイル/フォルダに対するクエリ **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/post-metadata-queries-execute-read/ **Source:** [https://ja.developer.box.com/reference/post-metadata-queries-execute-read/](https://ja.developer.box.com/reference/post-metadata-queries-execute-read/) --- ### メタデータフィールドのフィルタ (日付範囲) **Type:** resource | **Category:** api-resource | **Section:** API Reference 検索結果のフィルタに使用するテンプレートの`date`フィールドを指定して、照合する日付の範囲を指定します。 # メタデータフィールドのフィルタ (日付範囲) 検索結果のフィルタに使用するテンプレートの`date`フィールドを指定して、照合する日付の範囲を指定します。 --- ### メタデータフィールドのフィルタ (浮動小数点の範囲) **Type:** resource | **Category:** api-resource | **Section:** API Reference 検索結果のフィルタに使用するテンプレートの`float`フィールドを指定して、照合する値の範囲を指定します。 # メタデータフィールドのフィルタ (浮動小数点の範囲) 検索結果のフィルタに使用するテンプレートの`float`フィールドを指定して、照合する値の範囲を指定します。 --- ### メタデータフィルタ **Type:** resource | **Category:** api-resource | **Section:** API Reference 検索結果のフィルタに使用されたメタデータテンプレート。 # メタデータフィルタ 検索結果のフィルタに使用されたメタデータテンプレート。 --- ### メタデータを抽出 (構造化) **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/post-ai-extract-structured/ **Source:** [https://ja.developer.box.com/reference/post-ai-extract-structured/](https://ja.developer.box.com/reference/post-ai-extract-structured/) --- ### メタデータを抽出 (自由形式) **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/post-ai-extract/ **Source:** [https://ja.developer.box.com/reference/post-ai-extract/](https://ja.developer.box.com/reference/post-ai-extract/) --- ### ユーザー (Base) **Type:** resource | **Category:** api-resource | **Section:** API Reference 他のリソース内にネストされたときに使用されるユーザーのMini版の表示。 # ユーザー (Base) 他のリソース内にネストされたときに使用されるユーザーのMini版の表示。 --- ### ユーザー (Full) **Type:** resource | **Category:** api-resource | **Section:** API Reference 任意のユーザーAPIエンドポイントから返される可能性があるユーザーのFull版の表示。 # ユーザー (Full) 任意のユーザーAPIエンドポイントから返される可能性があるユーザーのFull版の表示。 --- ### ユーザー (Mini) **Type:** resource | **Category:** api-resource | **Section:** API Reference 他のリソース内にネストされたときに返される可能性があるユーザーのMini版の表示。 # ユーザー (Mini) 他のリソース内にネストされたときに返される可能性があるユーザーのMini版の表示。 --- ### ユーザー (コラボレーション) **Type:** resource | **Category:** api-resource | **Section:** API Reference ユーザーのMini版の表示は、ステータスが`pending`の場合にのみ返すことができます。 # ユーザー (コラボレーション) ユーザーのMini版の表示は、ステータスが`pending`の場合にのみ返すことができます。 --- ### ユーザー (統合マッピング) **Type:** resource | **Category:** api-resource | **Section:** API Reference 統合マッピングAPIのためのユーザーのレプリゼンテーション。フィールド名とログインは必要ありません。 # ユーザー (統合マッピング) 統合マッピングAPIのためのユーザーのレプリゼンテーション。フィールド名とログインは必要ありません。 --- ### ユーザーグループのセッションを終了させるジョブを作成 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/post-groups-terminate-sessions/ **Source:** [https://ja.developer.box.com/reference/post-groups-terminate-sessions/](https://ja.developer.box.com/reference/post-groups-terminate-sessions/) --- ### ユーザーのアバター **Type:** resource | **Category:** api-resource | **Section:** API Reference BoxアプリケーションにアップロードされたアバターへのURLを保持するリソース。 # ユーザーのアバター BoxアプリケーションにアップロードされたアバターへのURLを保持するリソース。 --- ### ユーザーのアバターを削除 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/delete-users-id-avatar/ **Source:** [https://ja.developer.box.com/reference/delete-users-id-avatar/](https://ja.developer.box.com/reference/delete-users-id-avatar/) --- ### ユーザーのアバターを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-users-id-avatar/ **Source:** [https://ja.developer.box.com/reference/get-users-id-avatar/](https://ja.developer.box.com/reference/get-users-id-avatar/) --- ### ユーザーのアバターを追加または更新 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/post-users-id-avatar/ **Source:** [https://ja.developer.box.com/reference/post-users-id-avatar/](https://ja.developer.box.com/reference/post-users-id-avatar/) --- ### ユーザーのグループのリストを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-users-id-memberships/ **Source:** [https://ja.developer.box.com/reference/get-users-id-memberships/](https://ja.developer.box.com/reference/get-users-id-memberships/) --- ### ユーザーのセッションを終了させるジョブを作成 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/post-users-terminate-sessions/ **Source:** [https://ja.developer.box.com/reference/post-users-terminate-sessions/](https://ja.developer.box.com/reference/post-users-terminate-sessions/) --- ### ユーザーのメールエイリアスのリストを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-users-id-email-aliases/ **Source:** [https://ja.developer.box.com/reference/get-users-id-email-aliases/](https://ja.developer.box.com/reference/get-users-id-email-aliases/) --- ### ユーザーをグループから削除 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/delete-group-memberships-id/ **Source:** [https://ja.developer.box.com/reference/delete-group-memberships-id/](https://ja.developer.box.com/reference/delete-group-memberships-id/) --- ### ユーザーをグループに追加 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/post-group-memberships/ **Source:** [https://ja.developer.box.com/reference/post-group-memberships/](https://ja.developer.box.com/reference/post-group-memberships/) --- ### ユーザーを作成 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/post-users/ **Source:** [https://ja.developer.box.com/reference/post-users/](https://ja.developer.box.com/reference/post-users/) --- ### ユーザーを削除 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/delete-users-id/ **Source:** [https://ja.developer.box.com/reference/delete-users-id/](https://ja.developer.box.com/reference/delete-users-id/) --- ### ユーザーを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-users-id/ **Source:** [https://ja.developer.box.com/reference/get-users-id/](https://ja.developer.box.com/reference/get-users-id/) --- ### ユーザーを承認 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-authorize/ **Source:** [https://ja.developer.box.com/reference/get-authorize/](https://ja.developer.box.com/reference/get-authorize/) --- ### ユーザーを更新 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/put-users-id/ **Source:** [https://ja.developer.box.com/reference/put-users-id/](https://ja.developer.box.com/reference/put-users-id/) --- ### ユーザー招待ステータスを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-invites-id/ **Source:** [https://ja.developer.box.com/reference/get-invites-id/](https://ja.developer.box.com/reference/get-invites-id/) --- ### ユーザー招待を作成 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/post-invites/ **Source:** [https://ja.developer.box.com/reference/post-invites/](https://ja.developer.box.com/reference/post-invites/) --- ### リーガルホールドが設定されているファイル **Type:** resource | **Category:** api-resource | **Section:** API Reference リーガルホールドポリシー割り当てにより、リーガルホールドが設定されているファイルのリスト。 # リーガルホールドが設定されているファイル リーガルホールドポリシー割り当てにより、リーガルホールドが設定されているファイルのリスト。 --- ### リーガルホールドが設定されているファイルバージョン **Type:** resource | **Category:** api-resource | **Section:** API Reference リーガルホールドポリシー割り当てにより、リーガルホールドが設定されているファイルのリスト。 # リーガルホールドが設定されているファイルバージョン リーガルホールドポリシー割り当てにより、リーガルホールドが設定されているファイルのリスト。 --- ### リーガルホールドポリシー **Type:** resource | **Category:** api-resource | **Section:** API Reference リーガルホールドポリシーのリスト。 # リーガルホールドポリシー リーガルホールドポリシーのリスト。 --- ### リーガルホールドポリシー **Type:** resource | **Category:** api-resource | **Section:** API Reference リーガルホールドポリシー情報には、名前、説明、フィルタ日付など、ポリシーの基本的な特性が記載されています。 # リーガルホールドポリシー リーガルホールドポリシー情報には、名前、説明、フィルタ日付など、ポリシーの基本的な特性が記載されています。 --- ### リーガルホールドポリシー (Mini) **Type:** resource | **Category:** api-resource | **Section:** API Reference Mini版のリーガルホールドポリシー。 # リーガルホールドポリシー (Mini) Mini版のリーガルホールドポリシー。 --- ### リーガルホールドポリシーの割り当てを解除 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/delete-legal-hold-policy-assignments-id/ **Source:** [https://ja.developer.box.com/reference/delete-legal-hold-policy-assignments-id/](https://ja.developer.box.com/reference/delete-legal-hold-policy-assignments-id/) --- ### リーガルホールドポリシーを作成 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/post-legal-hold-policies/ **Source:** [https://ja.developer.box.com/reference/post-legal-hold-policies/](https://ja.developer.box.com/reference/post-legal-hold-policies/) --- ### リーガルホールドポリシーを削除 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/delete-legal-hold-policies-id/ **Source:** [https://ja.developer.box.com/reference/delete-legal-hold-policies-id/](https://ja.developer.box.com/reference/delete-legal-hold-policies-id/) --- ### リーガルホールドポリシーを割り当て **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/post-legal-hold-policy-assignments/ **Source:** [https://ja.developer.box.com/reference/post-legal-hold-policy-assignments/](https://ja.developer.box.com/reference/post-legal-hold-policy-assignments/) --- ### リーガルホールドポリシーを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-legal-hold-policies-id/ **Source:** [https://ja.developer.box.com/reference/get-legal-hold-policies-id/](https://ja.developer.box.com/reference/get-legal-hold-policies-id/) --- ### リーガルホールドポリシーを更新 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/put-legal-hold-policies-id/ **Source:** [https://ja.developer.box.com/reference/put-legal-hold-policies-id/](https://ja.developer.box.com/reference/put-legal-hold-policies-id/) --- ### リーガルホールドポリシー割り当て **Type:** resource | **Category:** api-resource | **Section:** API Reference リーガルホールド割り当ては、ユーザー、フォルダ、ファイル、またはファイルバージョンにリーガルホールドポリシーを割り当てる目的に使用されます。 リーガルホールド割り当てを作成すると、その割り当ての「apply-to」エンティティに属するファイルバージョンにホールドが適用されます。 # リーガルホールドポリシー割り当て リーガルホールド割り当ては、ユーザー、フォルダ、ファイル、またはファイルバージョンにリーガルホールドポリシーを割り当てる目的に使用されます。 リーガルホールド割り当てを作成すると、その割り当ての「apply-to」エンティティに属するファイルバージョンにホールドが適用されます。 --- ### リーガルホールドポリシー割り当て **Type:** resource | **Category:** api-resource | **Section:** API Reference リーガルホールドポリシー割り当てのリスト。 # リーガルホールドポリシー割り当て リーガルホールドポリシー割り当てのリスト。 --- ### リーガルホールドポリシー割り当て (Base) **Type:** resource | **Category:** api-resource | **Section:** API Reference リーガルホールド割り当ては、ユーザー、フォルダ、ファイル、またはファイルバージョンにリーガルホールドポリシーを割り当てる目的に使用されます。 リーガルホールド割り当てを作成すると、その割り当ての「apply-to」エンティティに属するファイルバージョンにホールドが適用されます。 # リーガルホールドポリシー割り当て (Base) リーガルホールド割り当ては、ユーザー、フォルダ、ファイル、またはファイルバージョンにリーガルホールドポリシーを割り当てる目的に使用されます。 リーガルホールド割り当てを作成すると、その割り当ての「apply-to」エンティティに属するファイルバージョンにホールドが適用されます。 --- ### リーガルホールドポリシー割り当てに関する以前のファイルバージョンのリストを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-legal-hold-policy-assignments-id-file-versions-on-hold/ **Source:** [https://ja.developer.box.com/reference/get-legal-hold-policy-assignments-id-file-versions-on-hold/](https://ja.developer.box.com/reference/get-legal-hold-policy-assignments-id-file-versions-on-hold/) --- ### リーガルホールドポリシー割り当てに関する現在のファイルバージョンを含むファイルのリストを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-legal-hold-policy-assignments-id-files-on-hold/ **Source:** [https://ja.developer.box.com/reference/get-legal-hold-policy-assignments-id-files-on-hold/](https://ja.developer.box.com/reference/get-legal-hold-policy-assignments-id-files-on-hold/) --- ### リーガルホールドポリシー割り当てのリストを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-legal-hold-policy-assignments/ **Source:** [https://ja.developer.box.com/reference/get-legal-hold-policy-assignments/](https://ja.developer.box.com/reference/get-legal-hold-policy-assignments/) --- ### リーガルホールドポリシー割り当てを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-legal-hold-policy-assignments-id/ **Source:** [https://ja.developer.box.com/reference/get-legal-hold-policy-assignments-id/](https://ja.developer.box.com/reference/get-legal-hold-policy-assignments-id/) --- ### リアルタイムサーバー **Type:** resource | **Category:** api-resource | **Section:** API Reference Long polling User Eventに使用できるリアルタイムサーバー。 # リアルタイムサーバー Long polling User Eventに使用できるリアルタイムサーバー。 --- ### リアルタイムサーバー **Type:** resource | **Category:** api-resource | **Section:** API Reference Long pollingに使用できるリアルタイムサーバーのリスト。 # リアルタイムサーバー Long pollingに使用できるリアルタイムサーバーのリスト。 --- ### リクエストしている企業のすべてのHubのリストを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/v2025.0/get-enterprise-hubs/ **Source:** [https://ja.developer.box.com/reference/v2025.0/get-enterprise-hubs/](https://ja.developer.box.com/reference/v2025.0/get-enterprise-hubs/) --- ### リクエスト本文に基づいてワークフローを開始 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/post-workflows-id-start/ **Source:** [https://ja.developer.box.com/reference/post-workflows-id-start/](https://ja.developer.box.com/reference/post-workflows-id-start/) --- ### リテンションの対象となるファイル **Type:** resource | **Category:** api-resource | **Section:** API Reference リテンションの対象となるファイルのリスト。 # リテンションの対象となるファイル リテンションの対象となるファイルのリスト。 --- ### リテンションの対象となるファイルバージョンを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-retention-policy-assignments-id-file-versions-under-retention/ **Source:** [https://ja.developer.box.com/reference/get-retention-policy-assignments-id-file-versions-under-retention/](https://ja.developer.box.com/reference/get-retention-policy-assignments-id-file-versions-under-retention/) --- ### リテンションの対象となるファイルを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-retention-policy-assignments-id-files-under-retention/ **Source:** [https://ja.developer.box.com/reference/get-retention-policy-assignments-id-files-under-retention/](https://ja.developer.box.com/reference/get-retention-policy-assignments-id-files-under-retention/) --- ### リテンションポリシー **Type:** resource | **Category:** api-resource | **Section:** API Reference リテンションポリシーのリスト。 # リテンションポリシー リテンションポリシーのリスト。 --- ### リテンションポリシー **Type:** resource | **Category:** api-resource | **Section:** API Reference リテンションポリシーは、指定した期間にわたってコンテンツが完全に削除されるのを防止します。管理者はリテンションポリシーを作成して特定のフォルダ、メタデータテンプレート、または企業全体に割り当てることができます。この機能を使用するには、アプリケーション管理コンソールから、APIキーに対して \[リテンションポリシーを管理する] スコープを有効にする必要があります。 # リテンションポリシー リテンションポリシーは、指定した期間にわたってコンテンツが完全に削除されるのを防止します。管理者はリテンションポリシーを作成して特定のフォルダ、メタデータテンプレート、または企業全体に割り当てることができます。この機能を使用するには、アプリケーション管理コンソールから、APIキーに対して \[リテンションポリシーを管理する] スコープを有効にする必要があります。 --- ### リテンションポリシー (Base) **Type:** resource | **Category:** api-resource | **Section:** API Reference リテンションポリシーのBase版の表示。 # リテンションポリシー (Base) リテンションポリシーのBase版の表示。 --- ### リテンションポリシー (Mini) **Type:** resource | **Category:** api-resource | **Section:** API Reference 他のリソース内にネストされたときに使用されるリテンションポリシーのMini版の表示。 # リテンションポリシー (Mini) 他のリソース内にネストされたときに使用されるリテンションポリシーのMini版の表示。 --- ### リテンションポリシーのリストを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-retention-policies/ **Source:** [https://ja.developer.box.com/reference/get-retention-policies/](https://ja.developer.box.com/reference/get-retention-policies/) --- ### リテンションポリシーを作成 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/post-retention-policies/ **Source:** [https://ja.developer.box.com/reference/post-retention-policies/](https://ja.developer.box.com/reference/post-retention-policies/) --- ### リテンションポリシーを削除 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/delete-retention-policies-id/ **Source:** [https://ja.developer.box.com/reference/delete-retention-policies-id/](https://ja.developer.box.com/reference/delete-retention-policies-id/) --- ### リテンションポリシーを割り当て **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/post-retention-policy-assignments/ **Source:** [https://ja.developer.box.com/reference/post-retention-policy-assignments/](https://ja.developer.box.com/reference/post-retention-policy-assignments/) --- ### リテンションポリシーを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-retention-policies-id/ **Source:** [https://ja.developer.box.com/reference/get-retention-policies-id/](https://ja.developer.box.com/reference/get-retention-policies-id/) --- ### リテンションポリシーを更新 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/put-retention-policies-id/ **Source:** [https://ja.developer.box.com/reference/put-retention-policies-id/](https://ja.developer.box.com/reference/put-retention-policies-id/) --- ### リテンションポリシー割り当て **Type:** resource | **Category:** api-resource | **Section:** API Reference リテンションの割り当ては、リテンションポリシーで保持されるファイルを指定するルールを表します。割り当てにより、フォルダまたはメタデータに基づいてファイルを保持したり、企業内のすべてのファイルを保持したりできます。 # リテンションポリシー割り当て リテンションの割り当ては、リテンションポリシーで保持されるファイルを指定するルールを表します。割り当てにより、フォルダまたはメタデータに基づいてファイルを保持したり、企業内のすべてのファイルを保持したりできます。 --- ### リテンションポリシー割り当て **Type:** resource | **Category:** api-resource | **Section:** API Reference リテンションポリシー割り当てのリスト。 # リテンションポリシー割り当て リテンションポリシー割り当てのリスト。 --- ### リテンションポリシー割り当て (Base) **Type:** resource | **Category:** api-resource | **Section:** API Reference リテンションポリシー割り当てのBase版の表示。 # リテンションポリシー割り当て (Base) リテンションポリシー割り当てのBase版の表示。 --- ### リテンションポリシー割り当てのリストを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-retention-policies-id-assignments/ **Source:** [https://ja.developer.box.com/reference/get-retention-policies-id-assignments/](https://ja.developer.box.com/reference/get-retention-policies-id-assignments/) --- ### リテンションポリシー割り当てを削除 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/delete-retention-policy-assignments-id/ **Source:** [https://ja.developer.box.com/reference/delete-retention-policy-assignments-id/](https://ja.developer.box.com/reference/delete-retention-policy-assignments-id/) --- ### リテンションポリシー割り当てを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-retention-policy-assignments-id/ **Source:** [https://ja.developer.box.com/reference/get-retention-policy-assignments-id/](https://ja.developer.box.com/reference/get-retention-policy-assignments-id/) --- ### ワークフロー (Full) **Type:** resource | **Category:** api-resource | **Section:** API Reference Box Relayワークフローは、名前が付けられたフローのコレクションを表すオブジェクトです。 アプリケーションは、このリソースを使用するために、開発者コンソールでの`Manage Box Relay`アプリケーションスコープの使用が承認されている必要があります。 # ワークフロー (Full) Box Relayワークフローは、名前が付けられたフローのコレクションを表すオブジェクトです。 アプリケーションは、このリソースを使用するために、開発者コンソールでの`Manage Box Relay`アプリケーションスコープの使用が承認されている必要があります。 --- ### ワークフロー (Mini) **Type:** resource | **Category:** api-resource | **Section:** API Reference Box Relayワークフローは、名前が付けられたフローのコレクションを表すオブジェクトです。 アプリケーションは、このリソースを使用するために、開発者コンソールでの`Manage Box Relay`アプリケーションスコープの使用が承認されている必要があります。 # ワークフロー (Mini) Box Relayワークフローは、名前が付けられたフローのコレクションを表すオブジェクトです。 アプリケーションは、このリソースを使用するために、開発者コンソールでの`Manage Box Relay`アプリケーションスコープの使用が承認されている必要があります。 --- ### ワークフロー (リスト) **Type:** resource | **Category:** api-resource | **Section:** API Reference ワークフローのリスト。 アプリケーションは、このリソースを使用するために、開発者コンソールでの`Manage Box Relay`アプリケーションスコープの使用が承認されている必要があります。 # ワークフロー (リスト) ワークフローのリスト。 アプリケーションは、このリソースを使用するために、開発者コンソールでの`Manage Box Relay`アプリケーションスコープの使用が承認されている必要があります。 --- ### ワークフローのリストを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-workflows/ **Source:** [https://ja.developer.box.com/reference/get-workflows/](https://ja.developer.box.com/reference/get-workflows/) --- ### 企業 (Base) **Type:** resource | **Category:** api-resource | **Section:** API Reference 他のリソース内にネストされたときに使用される企業のMini版の表示。 # 企業 (Base) 他のリソース内にネストされたときに使用される企業のMini版の表示。 --- ### 企業のShieldリストを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/v2025.0/get-shield-lists/ **Source:** [https://ja.developer.box.com/reference/v2025.0/get-shield-lists/](https://ja.developer.box.com/reference/v2025.0/get-shield-lists/) --- ### 企業のすべてのメタデータテンプレートのリストを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-metadata-templates-enterprise/ **Source:** [https://ja.developer.box.com/reference/get-metadata-templates-enterprise/](https://ja.developer.box.com/reference/get-metadata-templates-enterprise/) --- ### 会社のグループのリストを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-groups/ **Source:** [https://ja.developer.box.com/reference/get-groups/](https://ja.developer.box.com/reference/get-groups/) --- ### 会社のデバイスピンのリストを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-enterprises-id-device-pinners/ **Source:** [https://ja.developer.box.com/reference/get-enterprises-id-device-pinners/](https://ja.developer.box.com/reference/get-enterprises-id-device-pinners/) --- ### 会社ユーザーのリストを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-users/ **Source:** [https://ja.developer.box.com/reference/get-users/](https://ja.developer.box.com/reference/get-users/) --- ### 保留中のコラボレーションのリストを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-collaborations/ **Source:** [https://ja.developer.box.com/reference/get-collaborations/](https://ja.developer.box.com/reference/get-collaborations/) --- ### 共有リンクのアプリ項目を検索 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-shared-items--app-items/ **Source:** [https://ja.developer.box.com/reference/get-shared-items--app-items/](https://ja.developer.box.com/reference/get-shared-items--app-items/) --- ### 共有リンクのウェブリンクを検索 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-shared-items--web-links/ **Source:** [https://ja.developer.box.com/reference/get-shared-items--web-links/](https://ja.developer.box.com/reference/get-shared-items--web-links/) --- ### 共有リンクのファイルを検索 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-shared-items/ **Source:** [https://ja.developer.box.com/reference/get-shared-items/](https://ja.developer.box.com/reference/get-shared-items/) --- ### 共有リンクのフォルダを検索 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-shared-items--folders/ **Source:** [https://ja.developer.box.com/reference/get-shared-items--folders/](https://ja.developer.box.com/reference/get-shared-items--folders/) --- ### 最初の分類を追加 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/post-metadata-templates-schema--classifications/ **Source:** [https://ja.developer.box.com/reference/post-metadata-templates-schema--classifications/](https://ja.developer.box.com/reference/post-metadata-templates-schema--classifications/) --- ### 最近アクセスした項目のリストを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-recent-items/ **Source:** [https://ja.developer.box.com/reference/get-recent-items/](https://ja.developer.box.com/reference/get-recent-items/) --- ### 最近使用した項目 **Type:** resource | **Category:** api-resource | **Section:** API Reference ユーザーが最近アクセスした項目。 # 最近使用した項目 ユーザーが最近アクセスした項目。 --- ### 最近使用した項目 **Type:** resource | **Category:** api-resource | **Section:** API Reference 最近使用した項目のリスト。 # 最近使用した項目 最近使用した項目のリスト。 --- ### 分類 **Type:** resource | **Category:** api-resource | **Section:** API Reference ファイルまたはフォルダに適用される分類を含む、分類メタデータテンプレートのインスタンス。 項目に適用される分類に関する詳細を取得するには、分類メタデータテンプレートをリクエストしてください。 # 分類 ファイルまたはフォルダに適用される分類を含む、分類メタデータテンプレートのインスタンス。 項目に適用される分類に関する詳細を取得するには、分類メタデータテンプレートをリクエストしてください。 --- ### 分類テンプレート **Type:** resource | **Category:** api-resource | **Section:** API Reference 会社が定義したセキュリティ分類を保持するメタデータテンプレート。 # 分類テンプレート 会社が定義したセキュリティ分類を保持するメタデータテンプレート。 --- ### 分類を更新 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/put-metadata-templates-enterprise-securityClassification-6VMVochwUWo-schema--update/ **Source:** [https://ja.developer.box.com/reference/put-metadata-templates-enterprise-securityClassification-6VMVochwUWo-schema--update/](https://ja.developer.box.com/reference/put-metadata-templates-enterprise-securityClassification-6VMVochwUWo-schema--update/) --- ### 分類を追加 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/put-metadata-templates-enterprise-securityClassification-6VMVochwUWo-schema--add/ **Source:** [https://ja.developer.box.com/reference/put-metadata-templates-enterprise-securityClassification-6VMVochwUWo-schema--add/](https://ja.developer.box.com/reference/put-metadata-templates-enterprise-securityClassification-6VMVochwUWo-schema--add/) --- ### 名前を指定してメタデータテンプレートを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-metadata-templates-id-id-schema/ **Source:** [https://ja.developer.box.com/reference/get-metadata-templates-id-id-schema/](https://ja.developer.box.com/reference/get-metadata-templates-id-id-schema/) --- ### 所有フォルダの移動 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/put-users-id-folders-0/ **Source:** [https://ja.developer.box.com/reference/put-users-id-folders-0/](https://ja.developer.box.com/reference/put-users-id-folders-0/) --- ### 抽出 (構造化) リクエスト用のAIエージェント **Type:** resource | **Category:** api-resource | **Section:** API Reference 抽出 (構造化) に使用されるAIエージェント。 # 抽出 (構造化) リクエスト用のAIエージェント 抽出 (構造化) に使用されるAIエージェント。 --- ### 抽出リクエスト用のAIエージェント **Type:** resource | **Category:** api-resource | **Section:** API Reference 抽出に使用されるAIエージェント。 # 抽出リクエスト用のAIエージェント 抽出に使用されるAIエージェント。 --- ### 指定したIDのShield情報バリアのセグメントを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-shield-information-barrier-segments-id/ **Source:** [https://ja.developer.box.com/reference/get-shield-information-barrier-segments-id/](https://ja.developer.box.com/reference/get-shield-information-barrier-segments-id/) --- ### 指定したIDのShield情報バリアのセグメントを更新 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/put-shield-information-barrier-segments-id/ **Source:** [https://ja.developer.box.com/reference/put-shield-information-barrier-segments-id/](https://ja.developer.box.com/reference/put-shield-information-barrier-segments-id/) --- ### 指定したIDのShield情報バリアの変更されたステータスを追加 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/post-shield-information-barriers-change-status/ **Source:** [https://ja.developer.box.com/reference/post-shield-information-barriers-change-status/](https://ja.developer.box.com/reference/post-shield-information-barriers-change-status/) --- ### 指定したIDのShield情報バリアを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-shield-information-barriers-id/ **Source:** [https://ja.developer.box.com/reference/get-shield-information-barriers-id/](https://ja.developer.box.com/reference/get-shield-information-barriers-id/) --- ### 新規ユーザーのサービス利用規約のステータスを作成 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/post-terms-of-service-user-statuses/ **Source:** [https://ja.developer.box.com/reference/post-terms-of-service-user-statuses/](https://ja.developer.box.com/reference/post-terms-of-service-user-statuses/) --- ### 既存ファイルのアップロードセッションを作成 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/post-files-id-upload-sessions/ **Source:** [https://ja.developer.box.com/reference/post-files-id-upload-sessions/](https://ja.developer.box.com/reference/post-files-id-upload-sessions/) --- ### 既存ユーザーのサービス利用規約のステータスを更新 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/put-terms-of-service-user-statuses-id/ **Source:** [https://ja.developer.box.com/reference/put-terms-of-service-user-statuses-id/](https://ja.developer.box.com/reference/put-terms-of-service-user-statuses-id/) --- ### 検索結果 **Type:** resource | **Category:** api-resource | **Section:** API Reference 検索クエリに一致するファイル、フォルダ、およびウェブリンクのリスト。 # 検索結果 検索クエリに一致するファイル、フォルダ、およびウェブリンクのリスト。 --- ### 検索結果 (共有リンクを含む) **Type:** resource | **Category:** api-resource | **Section:** API Reference 検索クエリと一致したファイル、フォルダ、ウェブリンクの単一リスト (項目がユーザーと共有されたときに使用された共有リンクに関する追加情報を含む)。 このレスポンス形式は、`include_recent_shared_links`クエリパラメータが`true`に設定されている場合にのみ返されます。 # 検索結果 (共有リンクを含む) 検索クエリと一致したファイル、フォルダ、ウェブリンクの単一リスト (項目がユーザーと共有されたときに使用された共有リンクに関する追加情報を含む)。 このレスポンス形式は、`include_recent_shared_links`クエリパラメータが`true`に設定されている場合にのみ返されます。 --- ### 検索結果 (複数の共有リンクを含む) **Type:** resource | **Category:** api-resource | **Section:** API Reference 検索クエリと一致したファイル、フォルダ、ウェブリンクのリスト (項目がユーザーと共有されたときに使用されたすべての共有リンクに関する追加情報を含む)。 このレスポンス形式は、`include_recent_shared_links`クエリパラメータが`true`に設定されている場合にのみ返されます。 # 検索結果 (複数の共有リンクを含む) 検索クエリと一致したファイル、フォルダ、ウェブリンクのリスト (項目がユーザーと共有されたときに使用されたすべての共有リンクに関する追加情報を含む)。 このレスポンス形式は、`include_recent_shared_links`クエリパラメータが`true`に設定されている場合にのみ返されます。 --- ### 汎用的なソース **Type:** resource | **Category:** api-resource | **Section:** API Reference 汎用的なイベントソースタイプ。 # 汎用的なソース 汎用的なイベントソースタイプ。 --- ### 現在のユーザーを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-users-me/ **Source:** [https://ja.developer.box.com/reference/get-users-me/](https://ja.developer.box.com/reference/get-users-me/) --- ### 競合エラー **Type:** resource | **Category:** api-resource | **Section:** API Reference 競合が原因でファイルを作成できなかったときに発生するエラー。 # 競合エラー 競合が原因でファイルを作成できなかったときに発生するエラー。 --- ### 許可されたコラボレーションドメイン **Type:** resource | **Category:** api-resource | **Section:** API Reference コラボレーションが許可されたドメインのリスト。 # 許可されたコラボレーションドメイン コラボレーションが許可されたドメインのリスト。 --- ### 許可されたコラボレーションドメイン **Type:** resource | **Category:** api-resource | **Section:** API Reference ユーザーが社内のファイルやフォルダでコラボレーションできる (またはコラボレーションできない) 承認済みドメインを表すエントリ。 # 許可されたコラボレーションドメイン ユーザーが社内のファイルやフォルダでコラボレーションできる (またはコラボレーションできない) 承認済みドメインを表すエントリ。 --- ### 許可されたコラボレーションドメインからユーザーを除外 **Type:** resource | **Category:** api-resource | **Section:** API Reference この会社に許可されたコラボレーションドメインのリストによって課せられた制限から除外されるユーザー。 # 許可されたコラボレーションドメインからユーザーを除外 この会社に許可されたコラボレーションドメインのリストによって課せられた制限から除外されるユーザー。 --- ### 許可されたコラボレーションドメインからユーザーを除外 **Type:** resource | **Category:** api-resource | **Section:** API Reference この企業に許可されたコラボレーションドメインのリストによって課せられた制限から除外されるユーザーのリスト。 # 許可されたコラボレーションドメインからユーザーを除外 この企業に許可されたコラボレーションドメインのリストによって課せられた制限から除外されるユーザーのリスト。 --- ### 許可されたコラボレーションドメインのリストからドメインを削除 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/delete-collaboration-whitelist-entries-id/ **Source:** [https://ja.developer.box.com/reference/delete-collaboration-whitelist-entries-id/](https://ja.developer.box.com/reference/delete-collaboration-whitelist-entries-id/) --- ### 許可されたコラボレーションドメインのリストにドメインを追加 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/post-collaboration-whitelist-entries/ **Source:** [https://ja.developer.box.com/reference/post-collaboration-whitelist-entries/](https://ja.developer.box.com/reference/post-collaboration-whitelist-entries/) --- ### 許可されたコラボレーションドメインのリストを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-collaboration-whitelist-entries/ **Source:** [https://ja.developer.box.com/reference/get-collaboration-whitelist-entries/](https://ja.developer.box.com/reference/get-collaboration-whitelist-entries/) --- ### 許可されたコラボレーションドメインを取得 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/get-collaboration-whitelist-entries-id/ **Source:** [https://ja.developer.box.com/reference/get-collaboration-whitelist-entries-id/](https://ja.developer.box.com/reference/get-collaboration-whitelist-entries-id/) --- ### 質問リクエスト用のAIエージェント **Type:** resource | **Category:** api-resource | **Section:** API Reference クエリの処理に使用されるAIエージェント。 # 質問リクエスト用のAIエージェント クエリの処理に使用されるAIエージェント。 --- ### 質問を送信 **Type:** endpoint | **Category:** api-endpoint | **Section:** API Reference # undefined /reference/post-ai-ask/ **Source:** [https://ja.developer.box.com/reference/post-ai-ask/](https://ja.developer.box.com/reference/post-ai-ask/) --- ## Box AI Developer Zone ### Box AI Developer Zone **Type:** page | **Category:** Box AI Developer Zone | **Section:** Box AI Developer Zone Box AI Developer Zone Box AI Developer Zone Box AI Developer Zoneでは、AI… # Box AI Developer Zone Box AI Developer Zone Box AI Developer Zoneでは、AIエージェントやインテリジェントなワークフローを作成するための対話型のデモ、サンプルコード、ツールを紹介します。ユースケースを確認したり、Box AI APIを実際に体験したり、Box AI Studioでエージェントを作成したりしてみましょう。 対話型のデモをお試しください Box AI APIは、Enterprise PlusおよびEnterprise Advancedをご利用のすべてのお客様が利用できます。 選択した語調でドキュメントを要約します。 デモ 自然言語を使用するか文字列化したデータ構造を渡して、Box AI APIでメタデータを抽出します。 デモ ドキュメントのメタデータの候補を抽出します。BoxメタデータテンプレートIDまたはあらかじめ定義されたデータ構造を渡します。 デモ 新しい抽出エージェント (強化) を使用して、ドキュメントのメタデータの候補を抽出します。思考連鎖処理により最良の回答が得られます。 新着 チュートリアル ドキュメント Box AI APIを使用する際は、以下のリソースが参考になります。 仕様の詳細については、APIリファレンスをご確認ください。 ドキュメント Box AI APIの使用方法については、ガイドをご覧ください。 ドキュメント Boxでは、さまざまなAIモデルがサポートされており、アクセスレベルと機能レベルという2つの側面で分類されます。サポートされているAIモデルのリストを確認できます。 ドキュメント デフォルトのAIモデルの構成を上書きし、Box AI APIを使用してLLMを微調整します。 ドキュメント MCPサーバー Box MCPサーバーを使用する際は、以下のリソースが参考になります。 リモートBox MCPサーバーを使用すると、サードパーティ製のAIシステムを安全にBoxに接続してコンテンツを操作することができます。 新着 MCP PythonのDeveloper Communityオープンソースプロジェクト。これは、さまざまな操作 (ファイル検索、テキスト抽出、AIベースのクエリ実行、データ抽出など) を行うためにBox APIと統合されています。 MCP AIを活用したドキュメント生成のためにBox MCPサーバーからBox Doc Genを使用します。 チュートリアル LangChain MCPアダプタを使用して、Box MCPサーバーをLangChain互換のエージェントに変換します。 チュートリアル AIエージェント Boxで高度なAIエージェントを作成する方法を確認します。 Box AI Studio APIを使用してカスタムAIエージェントを作成および管理します。 新着 Box AI Studio Salesforce内でワークフローを自動化したり、インテリジェントなエージェントベースのプロセスを強化したりするのに役立つ、再利用可能なAgentforceアクションの利用を開始します。 新着 Salesforce OpenAI Responses APIとBoxエージェントを使用して、Boxインスタンスからエージェント型ワークフローに非構造化データを追加します。 OpenAI BoxのAIエージェントを作成するためのPythonライブラリの利用を開始します。 ベータ BoxのAI統合 BoxのAI統合を使用して、LLMモデルの既存のナレッジベースを拡張します。 Box内の非構造化コンテンツをSnowflakeの強力な分析機能にシームレスに接続し、新しいインサイトを取得してデータ駆動型のワークフローを自動化します。 新着 統合 Airbyteソースコネクタ「Box Data Extract」を使用して、非構造化ドキュメントを照会可能な構造化データに変換します。 統合 WeaviateのベクトルデータベースにBoxコンテンツを埋め込み、Weaviateの新しいQuery Agentを利用して、RAGワークフローを作成します。 統合 BoxとPineconeを関連付けることで、ベクトル埋め込みをカスタマイズし、LLMからより関連性の高い回答を取得できます。 統合 LlamaIndex用のBox reader一式を使用して、LLMワークフロー内でのBoxコンテンツへのアクセスを可能にします。 統合 LangChain向けのBox loaderを使用して、BoxコンテンツをLLMワークフローに含めます。 統合 Box MCPサーバーを使用して、BoxのセキュアなコンテンツでPydantic AIエージェントを拡張します。 デモ 動画 Box AI APIに関する最新のチュートリアルやデモをご覧ください。 Box AI APIの主要な機能を1分程で確認できます。 Box AI APIのテキスト生成エンドポイントのデモをご確認ください。 Box AI APIのドキュメントのQ&Aエンドポイントのデモをご確認ください。 Box AI APIを使用して、さまざまなプロンプトの形式でメタデータを抽出します。 Box AI APIを使用して、あらかじめ定義された構造でメタデータを抽出します。 Boxが公開APIを介してBox AIを公開することを選択した理由をご確認ください。 さらに動画を表示 **Source:** [https://ja.developer.box.com/ai-dev-zone/](https://ja.developer.box.com/ai-dev-zone/) --- ## Changelog ### `Google PaLM`の廃止と削除 **Type:** changelog | **Section:** Changelog Google PaLMの廃止と削除 # Google PaLMの廃止と削除 `Google`は`Google Pathways Language Models (PaLM)`の廃止を予定しています。 これに従い、日本時間2025年1月18日にBox AIから以下のモデルが削除される予定です。 - `text_bison` - `text_bison_32k` - `text_unicorn` - `google_text_embedding_gecko*` エージェントの上書きでこれらのいずれかのモデルを使用している場合は、[サポートされているモデルのリスト](https://developer.box.com/guides/box-ai/ai-agents/)をご確認ください。 **Source:** [https://ja.developer.box.com/changelog/2025-01-09-google-palm-deprecation-and-removal](https://ja.developer.box.com/changelog/2025-01-09-google-palm-deprecation-and-removal) --- ### `stream_type`をライブで監視する新しいイベントストリーム **Type:** changelog | **Section:** Changelog stream_typeをライブで監視する新しいイベントストリーム admin_logs_streamingというGET /events API用に新しいstream_typeをリリースしました。これにより、Boxで発生したイベントをほぼリアルタイムで監視できるようになります。 # stream_typeをライブで監視する新しいイベントストリーム `admin_logs_streaming`という[`GET /events`](e://get-events) API用に新しい`stream_type`をリリースしました。これにより、Boxで発生したイベントをほぼリアルタイムで監視できるようになります。 `admin_logs`を使用してライブイベントを登録しているアプリケーションは、最も低く一貫性のあるレイテンシを実現するために、`admin_logs_streaming`に移行することをお勧めします。この`stream_type`を使用するには、ユーザーは、**新規レポートの実行および既存レポートへのアクセスを行う**ための権限を持つEnterprise管理者または共同管理者である必要があります。 ## 更新内容 この新しいオプションについて説明するために、ドキュメントを更新しました。 - わかりやすくするために[イベント](g://events)ガイドを全面的に再編しました (各種セクションのすべてのページへの情報の追加を含む) - [`GET /events`](e://get-events)エンドポイントに関するOpenAPIの仕様を更新して、`admin_logs_streaming`の新しい`stream_type`オプションを含めました - 切り替え時の手順を含め、[`stream_type`ページ](g://events/enterprise-events/migrate-to-stream)の新しい移行方法を追加しました ## サポート情報 問題がある場合やさらにガイドが必要な場合は、必要なサポートについて、Boxの[Developer Forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum)に英語でリクエストを投稿してください。 **Source:** [https://ja.developer.box.com/changelog/2021-11-17-new-event-stream-live-monitoring](https://ja.developer.box.com/changelog/2021-11-17-new-event-stream-live-monitoring) --- ### 2019年12月31日にRelay APIエンドポイントを廃止 **Type:** changelog | **Section:** Changelog 2019年12月31日にRelay APIエンドポイントを廃止 2019年12月31日、すべてのRelay Classic APIエンドポイントが廃止されます。これには以下の機能が含まれます。 公開されているRelay Classicテンプレートのリストの取得 Relay… # 2019年12月31日にRelay APIエンドポイントを廃止 2019年12月31日、すべてのRelay Classic APIエンドポイントが廃止されます。これには以下の機能が含まれます。 - 公開されているRelay Classicテンプレートのリストの取得 - Relay Classicワークフローのリストの取得 - Relay Classicワークフローの開始 12月31日以降もアプリケーションを引き続き機能させるために、上記のRelay Classic APIへの呼び出しをすべて削除してください。 詳細については、この件に関する[コミュニティスレッド](https://community.box.com/t5/Platform-and-Development-Forum/Relay-Classic-APIs-to-EOL-on-December-31st-2019/m-p/77729#M7276)を参照してください。 **Source:** [https://ja.developer.box.com/changelog/2019-10-18-relay-api-endpoints-will-eol-on-december-31st-2019](https://ja.developer.box.com/changelog/2019-10-18-relay-api-endpoints-will-eol-on-december-31st-2019) --- ### Adobe Creative Cloudプレビューのサポート **Type:** changelog | **Section:** Changelog Adobe Creative Cloudプレビューのサポート ウェブアプリプレビューとの連携で、Adobe Photoshop、Illustrator、およびInDesignのファイルがAPIでサポートされるようになりました。 更新内容 拡張子がindt、idml、indd… # Adobe Creative Cloudプレビューのサポート ウェブアプリプレビューとの連携で、Adobe Photoshop、Illustrator、およびInDesignのファイルがAPIでサポートされるようになりました。 ## 更新内容 拡張子が`indt`、`idml`、`indd`、`inx`のファイルは、以下の機能でサポートされます。 - [サムネイル](g://representations/thumbnail) - [画像ビューアーUI Element](g://embed/ui-elements/viewers-and-events/#image-viewer) - [注釈](g://embed/ui-elements/annotations) - [サムネイルレプリゼンテーション](g://representations/thumbnail-representation) **Source:** [https://ja.developer.box.com/changelog/2021-10-06-support-for-adobe-creative-cloud-preview](https://ja.developer.box.com/changelog/2021-10-06-support-for-adobe-creative-cloud-preview) --- ### AI Studio v2 **Type:** changelog | **Section:** Changelog AI Studio v2 AI Studio機能の最新バージョンのリリースでは、以下に示す機能強化を実施しました。 ユーザーは、エージェントで問題が発生した場合に、AI Studio UIで直接、通知を受け取ります。 エージェントはリアルタイムで検証されます。検証に合格しないエージェントはユーザーに表示されません。 管理者は以下の操作が可能です。 ユーザーがカスタムAIエージェントの操作を開始したときに表示される質問の候補を制御する。 LLMのリクエストとレスポンスの詳細 (システムプロンプト、モデル、カスタム指示など) を確認する。 カスタムエージェントでBox AI画像プロセッサのパラメータを制御する。このパラメータは、特定の画像についてLLMに質問するために必要です。 # AI Studio v2 AI Studio機能の最新バージョンのリリースでは、以下に示す[機能強化](e://get-ai-agents/)を実施しました。 - **ユーザー**は、エージェントで問題が発生した場合に、AI Studio UIで直接、通知を受け取ります。 - エージェントはリアルタイムで検証されます。検証に合格しないエージェントはユーザーに表示されません。 **管理者**は以下の操作が可能です。 - ユーザーがカスタムAIエージェントの操作を開始したときに表示される質問の候補を制御する。 - LLMのリクエストとレスポンスの詳細 (システムプロンプト、モデル、カスタム指示など) を確認する。 - カスタムエージェントでBox AI画像プロセッサのパラメータを制御する。このパラメータは、特定の画像についてLLMに質問するために必要です。 詳細については、Boxの[API](e://get-ai-agents/)および[製品ドキュメント](https://support.box.com/hc/en-us/articles/37228357884179-Creating-and-Configuring-Agents)を参照してください。 ## サポート情報 問題がある場合やさらにガイドが必要な場合は、必要なサポートについて、Boxの[Developer Forum](https://forum.box.com/)に英語でリクエストを投稿してください。 **Source:** [https://ja.developer.box.com/changelog/2025-06-24-AI-studio-v2](https://ja.developer.box.com/changelog/2025-06-24-AI-studio-v2) --- ### Android SDKのサポート終了 (日本時間2023年6月1日) **Type:** changelog | **Section:** Changelog Android SDKのサポート終了 (日本時間2023年6月1日) 日本時間2023年6月1日をもって、Android SDKのサポートを終了いたします。既存のAndroid SDKアプリケーションは影響なく引き続きご利用いただけますが、新機能、更新、バグ修正は提供されなくなります。最新のAndroid機能を引き続きご利用いただくために、Java SDKを使用してAndroid版アプリを作成することをお勧めします。詳細については、こちらのドキュメントを参照してください。 # Android SDKのサポート終了 (日本時間2023年6月1日) 日本時間2023年6月1日をもって、[Android SDK](https://github.com/box/box-android-sdk)のサポートを終了いたします。既存のAndroid SDKアプリケーションは影響なく引き続きご利用いただけますが、新機能、更新、バグ修正は提供されなくなります。最新のAndroid機能を引き続きご利用いただくために、Java SDKを使用してAndroid版アプリを作成することをお勧めします。詳細については、[こちら](https://github.com/box/box-java-sdk/blob/main/doc/android.md)のドキュメントを参照してください。 ## サポート情報 問題がある場合やさらにガイドが必要な場合は、必要なサポートについて、Boxの[Developer Forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum)に英語でリクエストを投稿してください。 **Source:** [https://ja.developer.box.com/changelog/2023-02-24-android-end-of-support](https://ja.developer.box.com/changelog/2023-02-24-android-end-of-support) --- ### App Diagnosticsレポートへのフィードバック **Type:** changelog | **Section:** Changelog App Diagnosticsレポートへのフィードバック 新しいApp Diagnosticsレポートのリリースを開始しました。ぜひ皆様のご意見やご感想をお寄せください。フィードバックの提供については、フォーラムの投稿を参照してください。 # App Diagnosticsレポートへのフィードバック 新しい[App Diagnosticsレポート](https://developer.box.com/guides/api-calls/permissions-and-errors/app-diagnostics-report/)の[リリースを開始](https://developer.box.com/changelog/#2021-10-07-new-app-diagnostics-report)しました。ぜひ皆様のご意見やご感想をお寄せください。フィードバックの提供については、[フォーラムの投稿](https://support.box.com/hc/en-us/community/posts/4408877038483-App-Diagnostics-Report-Feedback)を参照してください。 **Source:** [https://ja.developer.box.com/changelog/2021-10-20-app-diagnostics-report-feedback](https://ja.developer.box.com/changelog/2021-10-20-app-diagnostics-report-feedback) --- ### Box `user_id`フィールドのサイズを変更 **Type:** changelog | **Section:** Changelog Box user_idフィールドのサイズを変更 すべてのPlatformユーザー (管理対象ユーザー、外部管理ユーザー、App User) の追跡に使用されるuser_idフィールドは、まもなく現在の32ビット整数ではなく、6… # Box user_idフィールドのサイズを変更 すべてのPlatformユーザー (管理対象ユーザー、外部管理ユーザー、App User) の追跡に使用される`user_id`フィールドは、まもなく現在の32ビット整数ではなく、64ビット整数の生成を開始するよう更新されます。 この更新は内部システムに影響するため、APIから生成された`user_id`文字列を32ビット整数フィールドに変換している場合には、新しい64ビット`user_id`の整数サイズをサポートするよう更新する必要があります。[APIドキュメント](endpoint://resources/user/)に従って、すべての`user_id`フィールドを文字列として保存することをお勧めします。 **Source:** [https://ja.developer.box.com/changelog/2018-08-17-box-user_id-field-size-changed](https://ja.developer.box.com/changelog/2018-08-17-box-user_id-field-size-changed) --- ### Box AI API - AWS AIモデルの提供開始 **Type:** changelog | **Section:** Changelog Box AI API - AWS AIモデルの提供開始 利用可能なAIモデルのリストが更新され、以下のAWSモデルが追加されました。 AWS Claude 3 Sonnet AWS Claude 3.5 Sonnet AWS Claude 3 Haiku AWS Titan Text Lite プレビューモードで提供されているモデルはパフォーマンスが大規模にテストされておらず、現状のままでの利用となるため、モデル/出力の品質、可用性、精度にはばらつきがある可能性があります。 提供されているモデルを使用して、AIエージェントの構成で使用されているデフォルトモデルを上書きできます。Box AI APIの詳細については、ガイドとAPIリファレンスを参照してください。 # Box AI API - AWS AIモデルの提供開始 [利用可能なAIモデル](https://developer.box.com/guides/box-ai/supported-models/)のリストが更新され、以下のAWSモデルが追加されました。 - AWS Claude 3 Sonnet - AWS Claude 3.5 Sonnet - AWS Claude 3 Haiku - AWS Titan Text Lite **プレビュー**モードで提供されているモデルはパフォーマンスが大規模にテストされておらず、現状のままでの利用となるため、モデル/出力の品質、可用性、精度にはばらつきがある可能性があります。 提供されているモデルを使用して、AIエージェントの構成で使用されている[デフォルトモデルを上書き](https://developer.box.com/guides/box-ai/supported-models/)できます。Box AI APIの詳細については、[ガイド](https://developer.box.com/guides/box-ai)と[APIリファレンス](https://developer.box.com/reference/post-ai-ask/)を参照してください。 ## サポート情報 問題がある場合やさらにガイドが必要な場合は、必要なサポートについて、Boxの[Developer Forum](https://forum.box.com/)に英語でリクエストを投稿してください。 **Source:** [https://ja.developer.box.com/changelog/2024-10-24-box-ai-aws-models](https://ja.developer.box.com/changelog/2024-10-24-box-ai-aws-models) --- ### Box AI API - AWS Claude 3.7 Sonnetの提供開始 **Type:** changelog | **Section:** Changelog Box AI API - AWS Claude 3.7 Sonnetの提供開始 利用可能なAIモデルのリストが更新され、AWS Claude 3.7 Sonnetが追加されました。 プレビューモードで提供されているモデルはパフォーマンスが大規模にテストされておらず、現状のままでの利用となるため、モデル/出力の品質、可用性、精度にはばらつきがある可能性があります。 提供されているモデルを使用して、AIエージェントの構成で使用されているデフォルトモデルを上書きできます。Box AI APIの詳細については、ガイドとAPIリファレンスを参照してください。 # Box AI API - AWS Claude 3.7 Sonnetの提供開始 [利用可能なAIモデル](https://developer.box.com/guides/box-ai/supported-models/)のリストが更新され、AWS Claude 3.7 Sonnetが追加されました。 **プレビュー**モードで提供されているモデルはパフォーマンスが大規模にテストされておらず、現状のままでの利用となるため、モデル/出力の品質、可用性、精度にはばらつきがある可能性があります。 提供されているモデルを使用して、AIエージェントの構成で使用されている[デフォルトモデルを上書き](https://developer.box.com/guides/box-ai/supported-models/)できます。Box AI APIの詳細については、[ガイド](https://developer.box.com/guides/box-ai)と[APIリファレンス](https://developer.box.com/reference/post-ai-ask/)を参照してください。 ## サポート情報 問題がある場合やさらにガイドが必要な場合は、必要なサポートについて、Boxの[Developer Forum](https://forum.box.com/)に英語でリクエストを投稿してください。 **Source:** [https://ja.developer.box.com/changelog/2025-02-26-aws-claude-3-7](https://ja.developer.box.com/changelog/2025-02-26-aws-claude-3-7) --- ### Box AI API - Google Gemini 2.5 Proの提供開始 (Gemini 2.5 Flash PreviewおよびPro Previewの廃止) **Type:** changelog | **Section:** Changelog Box AI API - Google Gemini 2.5 Proの提供開始 (Gemini 2.5 Flash PreviewおよびPro Previewの廃止) 利用可能なAIモデルのリストが更新され、Google Gemini 2.5 Proが追加されました。 以下のモデルは廃止されました。 Google Gemini 2.5 Flash Preview Google Gemini 2.5 Pro Preview 詳細については、廃止されたモデルを参照してください。 プレビューモードで提供されているモデルはパフォーマンスが大規模にテストされておらず、現状のままでの利用となるため、モデル/出力の品質、可用性、精度にはばらつきがある可能性があります。 提供されているモデルを使用して、AIエージェントの構成で使用されているデフォルトモデルを上書きできます。Box AI APIの詳細については、ガイドとAPIリファレンスを参照してください。 # Box AI API - Google Gemini 2.5 Proの提供開始 (Gemini 2.5 Flash PreviewおよびPro Previewの廃止) [利用可能なAIモデル](https://developer.box.com/guides/box-ai/supported-models/)のリストが更新され、Google Gemini 2.5 Proが追加されました。 以下のモデルは廃止されました。 - Google Gemini 2.5 Flash Preview - Google Gemini 2.5 Pro Preview 詳細については、[廃止されたモデル](https://cloud.google.com/vertex-ai/generative-ai/docs/learn/model-versions#expandable-1)を参照してください。 **プレビュー**モードで提供されているモデルはパフォーマンスが大規模にテストされておらず、現状のままでの利用となるため、モデル/出力の品質、可用性、精度にはばらつきがある可能性があります。 提供されているモデルを使用して、AIエージェントの構成で使用されている[デフォルトモデルを上書き](https://box-ai/ai-agents/ai-agent-overrides)できます。Box AI APIの詳細については、[ガイド](https://developer.box.com/guides/box-ai)と[APIリファレンス](https://developer.box.com/reference/post-ai-ask/)を参照してください。 ## サポート情報 問題がある場合やさらにガイドが必要な場合は、必要なサポートについて、Boxの[Developer Forum](https://forum.box.com/)に英語でリクエストを投稿してください。 **Source:** [https://ja.developer.box.com/changelog/2025-07-27-new-model-deprecated-models](https://ja.developer.box.com/changelog/2025-07-27-new-model-deprecated-models) --- ### Box AI API - 新しく利用可能になったAIモデル **Type:** changelog | **Section:** Changelog Box AI API - 新しく利用可能になったAIモデル 利用可能なAIモデルのリストが更新され、以下のモデルが追加されました。 Azure OpenAI GPT-4.1 Azure OpenAI GPT-4.1 Mini Gemini 2.5 Pro Preview Gemini 2.5 Flash Preview IBM Llama 4 Scout IBM Llama 3.2 Instruct プレビューモードで提供されているモデルはパフォーマンスが大規模にテストされておらず、現状のままでの利用となるため、モデル/出力の品質、可用性、精度にはばらつきがある可能性があります。 提供されているモデルを使用して、AIエージェントの構成で使用されているデフォルトモデルを上書きできます。Box AI APIの詳細については、ガイドとAPIリファレンスを参照してください。 # Box AI API - 新しく利用可能になったAIモデル [利用可能なAIモデル](https://developer.box.com/guides/box-ai/supported-models/)のリストが更新され、以下のモデルが追加されました。 - Azure OpenAI GPT-4.1 - Azure OpenAI GPT-4.1 Mini - Gemini 2.5 Pro Preview - Gemini 2.5 Flash Preview - IBM Llama 4 Scout - IBM Llama 3.2 Instruct **プレビュー**モードで提供されているモデルはパフォーマンスが大規模にテストされておらず、現状のままでの利用となるため、モデル/出力の品質、可用性、精度にはばらつきがある可能性があります。 提供されているモデルを使用して、AIエージェントの構成で使用されている[デフォルトモデルを上書き](https://box-ai/ai-agents/ai-agent-overrides)できます。Box AI APIの詳細については、[ガイド](https://developer.box.com/guides/box-ai)と[APIリファレンス](https://developer.box.com/reference/post-ai-ask/)を参照してください。 ## サポート情報 問題がある場合やさらにガイドが必要な場合は、必要なサポートについて、Boxの[Developer Forum](https://forum.box.com/)に英語でリクエストを投稿してください。 **Source:** [https://ja.developer.box.com/changelog/2025-04-29-new-ai-models](https://ja.developer.box.com/changelog/2025-04-29-new-ai-models) --- ### Box AI API - 新しく利用可能になったAIモデル **Type:** changelog | **Section:** Changelog Box AI API - 新しく利用可能になったAIモデル 利用可能なAIモデルのリストが更新され、以下のモデルが追加されました。 Azure OpenAI o3 (ベータ) Azure OpenAI o4 mini (ベータ) xAI Grok 3 (ベータ) xAI Grok 3 mini (ベータ) プレビューモードで提供されているモデルはパフォーマンスが大規模にテストされておらず、現状のままでの利用となるため、モデル/出力の品質、可用性、精度にはばらつきがある可能性があります。 提供されているモデルを使用して、AIエージェントの構成で使用されているデフォルトモデルを上書きできます。Box AI APIの詳細については、ガイドとAPIリファレンスを参照してください。 # Box AI API - 新しく利用可能になったAIモデル [利用可能なAIモデル](https://developer.box.com/guides/box-ai/supported-models/)のリストが更新され、以下のモデルが追加されました。 - Azure OpenAI o3 (ベータ) - Azure OpenAI o4 mini (ベータ) - xAI Grok 3 (ベータ) - xAI Grok 3 mini (ベータ) **プレビュー**モードで提供されているモデルはパフォーマンスが大規模にテストされておらず、現状のままでの利用となるため、モデル/出力の品質、可用性、精度にはばらつきがある可能性があります。 提供されているモデルを使用して、AIエージェントの構成で使用されている[デフォルトモデルを上書き](https://box-ai/ai-agents/ai-agent-overrides)できます。Box AI APIの詳細については、[ガイド](https://developer.box.com/guides/box-ai)と[APIリファレンス](https://developer.box.com/reference/post-ai-ask/)を参照してください。 ## サポート情報 問題がある場合やさらにガイドが必要な場合は、必要なサポートについて、Boxの[Developer Forum](https://forum.box.com/)に英語でリクエストを投稿してください。 **Source:** [https://ja.developer.box.com/changelog/2025-04-30-new-ai-models](https://ja.developer.box.com/changelog/2025-04-30-new-ai-models) --- ### Box AI API - 新しく利用可能になったAIモデルとGemini 1.5モデルの廃止 **Type:** changelog | **Section:** Changelog Box AI API - 新しく利用可能になったAIモデルとGemini 1.5モデルの廃止 利用可能なAIモデルのリストが更新され、以下のモデルが追加されました。 AWS Claude 4 Sonnet AWS Claude 4 Opus 以下のモデルは廃止されました。 Google Gemini 1.5 Flash 001 Google Gemini 1.5 Pro 001 詳細については、廃止されたモデルを参照してください。 Azure OpenAI GPT o4 Miniモデルは削除されました。 プレビューモードで提供されているモデルはパフォーマンスが大規模にテストされておらず、現状のままでの利用となるため、モデル/出力の品質、可用性、精度にはばらつきがある可能性があります。 提供されているモデルを使用して、AIエージェントの構成で使用されているデフォルトモデルを上書きできます。Box AI APIの詳細については、ガイドとAPIリファレンスを参照してください。 # Box AI API - 新しく利用可能になったAIモデルとGemini 1.5モデルの廃止 [利用可能なAIモデル](https://developer.box.com/guides/box-ai/supported-models/)のリストが更新され、以下のモデルが追加されました。 - AWS Claude 4 Sonnet - AWS Claude 4 Opus 以下のモデルは廃止されました。 - Google Gemini 1.5 Flash 001 - Google Gemini 1.5 Pro 001 詳細については、[廃止されたモデル](https://cloud.google.com/vertex-ai/generative-ai/docs/learn/model-versions#expandable-1)を参照してください。 Azure OpenAI GPT o4 Miniモデルは削除されました。 **プレビュー**モードで提供されているモデルはパフォーマンスが大規模にテストされておらず、現状のままでの利用となるため、モデル/出力の品質、可用性、精度にはばらつきがある可能性があります。 提供されているモデルを使用して、AIエージェントの構成で使用されている[デフォルトモデルを上書き](https://box-ai/ai-agents/ai-agent-overrides)できます。Box AI APIの詳細については、[ガイド](https://developer.box.com/guides/box-ai)と[APIリファレンス](https://developer.box.com/reference/post-ai-ask/)を参照してください。 ## サポート情報 問題がある場合やさらにガイドが必要な場合は、必要なサポートについて、Boxの[Developer Forum](https://forum.box.com/)に英語でリクエストを投稿してください。 **Source:** [https://ja.developer.box.com/changelog/2025-05-24-new-models-deprecated-models](https://ja.developer.box.com/changelog/2025-05-24-new-models-deprecated-models) --- ### Box AI API — ドキュメントのQ&Aおよびテキスト生成機能の正式リリース **Type:** changelog | **Section:** Changelog Box AI API — ドキュメントのQ&Aおよびテキスト生成機能の正式リリース Box AI APIのBox AIに質問する機能およびBox AIを使用してテキストを生成する機能が、Enterprise Plusをご利用のすべてのお客様に提供されるようになりました。 Box AI APIを使用すると、カスタムアプリケーション内でBox AI機能を利用できます。たとえば、Box AIの質疑応答機能をサードパーティ製アプリケーションに実装したり、自社製品のコンテンツエディタ内で直接コンテンツを生成したりできます。また、指定したドキュメントからメタデータを抽出することもできます。 メタデータ抽出に関連したエンドポイントは、現在、BoxのMain Beta Agreementに従い提供されるベータ機能のため、利用可能な機能は変更される可能性があります。 # Box AI API — ドキュメントのQ&Aおよびテキスト生成機能の正式リリース Box AI APIの[Box AIに質問する](g://box-ai/ai-tutorials/ask-questions/)機能および[Box AIを使用してテキストを生成する](g://box-ai/ai-tutorials/generate-text/)機能が、**Enterprise Plus**をご利用のすべてのお客様に提供されるようになりました。 [Box AI API](https://developer.box.com/guides/box-ai)を使用すると、カスタムアプリケーション内でBox AI機能を利用できます。たとえば、Box AIの質疑応答機能をサードパーティ製アプリケーションに実装したり、自社製品のコンテンツエディタ内で直接コンテンツを生成したりできます。また、指定したドキュメントからメタデータを抽出することもできます。 *メタデータ抽出に関連したエンドポイントは、現在、BoxのMain Beta Agreementに従い提供されるベータ機能のため、利用可能な機能は変更される可能性があります。* 現時点では、Box AI機能を使用すると、以下のことが可能です。 - 質問に対する応答を取得する。 - ドキュメントの要約を取得する。 - ドキュメント内で使用できるテキストを生成する。 - さらに高い自由度でプロンプトを使用し、指定したファイルから柔軟な方法でメタデータを抽出する。 - 指定したファイルから、[メタデータテンプレート](https://support.box.com/hc/en-us/articles/360044194033-Customizing-Metadata-Templates)または`fields`構造を使用してメタデータを抽出する。 - デフォルトのAPIモデルの構成を取得して上書きする。 Box AIの詳細については、[Box AI APIの開発者向けガイド](https://developer.box.com/guides/box-ai)を参照してください。また、Box AI APIの詳細については、[APIリファレンス](e://ai-agent-ask/)を参照してください。 ## Box AI for UI Elements [Box AI for UI Elements](g://embed/ui-elements/preview#box-ai-ui-element)では、Box AIのドキュメントのQ&A機能とテキスト生成機能で[コンテンツプレビュー](g://embed/ui-elements/preview)を強化します。Box AI for UI Elementsの強化により、ユーザーは、カスタムアプリケーションにAI機能を埋め込み、質問への回答、ドキュメントの要約、引用情報の追加、会話履歴の使用、書式設定のサポートのような操作を円滑に進めることができます。 ## サポート情報 問題がある場合やさらにガイドが必要な場合は、必要なサポートについて、Boxの[Developer Forum](https://forum.box.com/)に英語でリクエストを投稿してください。 **Source:** [https://ja.developer.box.com/changelog/2024-10-22-box-ai-text-gen-ask-ga](https://ja.developer.box.com/changelog/2024-10-22-box-ai-text-gen-ask-ga) --- ### Box AI APIとBox AI Dev Zoneの導入 **Type:** changelog | **Section:** Changelog Box AI APIとBox AI Dev Zoneの導入 Box AI APIを使用すると、カスタムアプリケーション内でBox AI機能を利用できます。たとえば、Box AIの質疑応答機能をサードパーティ製アプリケーションに実装したり、自社製品のコンテンツエディタ内で直接コンテンツを生成したりできます。 Box AI APIとBox AI for UI Elementsはベータ機能のため、利用可能な機能は変更される可能性があります。Box AIの機能は、Enterprise Plusをご利用のすべてのお客様が利用できます。 # Box AI APIとBox AI Dev Zoneの導入 Box AI APIを使用すると、カスタムアプリケーション内でBox AI機能を利用できます。たとえば、Box AIの質疑応答機能をサードパーティ製アプリケーションに実装したり、自社製品のコンテンツエディタ内で直接コンテンツを生成したりできます。 *Box AI APIとBox AI for UI Elementsはベータ機能のため、利用可能な機能は変更される可能性があります。Box AIの機能は、**Enterprise Plus**をご利用のすべてのお客様が利用できます。* 現在は、Box AIに対して、質問への回答、ドキュメンのコンテンツの要約、ドキュメントで使用できるテキストの生成を求めることができます。Box AIの詳細については、[Box AI APIの開発者向けガイド](https://developer.box.com/guides/box-ai)をご確認ください。また、詳細については、APIリファレンスをご確認ください。 ## Box AI Developer Zone Boxでは、Box AI APIと一緒に、Developerドキュメントのデモページを新しくリリースしました。[Box AI Dev Zone](https://developer.box.com/ai-dev-zone)では、対話型の優れたエクスペリエンスを通じてBox AI APIを確認できます。ユースケース、プロンプトと応答の例、サンプルコードが用意されています。 ## Box AI for UI Elements [Box AI for UI Elements](g://embed/ui-elements/preview#box-ai-ui-element)では、AIの質疑応答機能を使用して[コンテンツプレビュー](g://embed/ui-elements/preview)ヘッダーを強化します。この新しいBox AI for UI Elementsにより、ユーザーは、カスタムアプリケーションにAI機能を埋め込み、質問への回答やドキュメントの要約のような操作を円滑に進めることができます。 ## サポート情報 問題がある場合やさらにガイドが必要な場合は、必要なサポートについて、Boxの[Developer Forum](https://forum.box.com/)に英語でリクエストを投稿してください。 **Source:** [https://ja.developer.box.com/changelog/2024-05-02-introducing-box-ai](https://ja.developer.box.com/changelog/2024-05-02-introducing-box-ai) --- ### Box AI APIのデフォルトモデルの更新 **Type:** changelog | **Section:** Changelog Box AI APIのデフォルトモデルの更新 Box AI Platform APIのPOST /2.0/ai/askエンドポイントが新しいデフォルトモデルに更新され、単一ドキュメントと複数ドキュメントの両方のモードがAzureのgpt-4o-miniに基づくようになりました。 注: Box AI Platform APIは、現在、BoxのMain Beta Agreementに従い提供されるベータ機能のため、利用可能な機能は変更される可能性があります。Box AI Platform APIは、Enterprise Plusをご利用のすべてのお客様が利用できます。 # Box AI APIのデフォルトモデルの更新 Box AI Platform APIの`POST /2.0/ai/ask`エンドポイントが新しいデフォルトモデルに更新され、単一ドキュメントと複数ドキュメントの両方のモードがAzureの`gpt-4o-mini`に基づくようになりました。 **注**: Box AI Platform APIは、現在、BoxのMain Beta Agreementに従い提供されるベータ機能のため、利用可能な機能は変更される可能性があります。Box AI Platform APIは、Enterprise Plusをご利用のすべてのお客様が利用できます。 [デフォルトのエージェント構成](https://developer.box.com/guides/box-ai/ai-agents/get-agent-default-config/)と[サポートされているAIモデル](https://developer.box.com/guides/box-ai/supported-models/)の詳細については、開発者向けガイドを参照してください。 ## サポート情報 問題がある場合やさらにガイドが必要な場合は、必要なサポートについて、Boxの[Developer Forum](https://community.box.com/)に英語でリクエストを投稿してください。 **Source:** [https://ja.developer.box.com/changelog/2024-09-23-box-ai-api-defaul-model-update](https://ja.developer.box.com/changelog/2024-09-23-box-ai-api-defaul-model-update) --- ### Box AI Platform API (ベータ版) によるメタデータ抽出の提供開始 **Type:** changelog | **Section:** Changelog Box AI Platform API (ベータ版) によるメタデータ抽出の提供開始 最近この機能が追加されたBox AI Platform APIを使用すると、指定した入力データからメタデータを抽出できます。たとえば、請求書から金融情報を抽出したり、診断書から患者のデータを抽出したりすることができます。 注: Box AI Platform APIは、現在、BoxのMain Beta Agreementに従い提供されるベータ機能のため、利用可能な機能は変更される可能性があります。Box AI Platform APIは、Enterprise Plusをご利用のすべてのお客様が利用できます。 # Box AI Platform API (ベータ版) によるメタデータ抽出の提供開始 最近この機能が追加されたBox AI Platform APIを使用すると、指定した入力データからメタデータを抽出できます。たとえば、請求書から金融情報を抽出したり、診断書から患者のデータを抽出したりすることができます。 **注**: Box AI Platform APIは、現在、BoxのMain Beta Agreementに従い提供されるベータ機能のため、利用可能な機能は変更される可能性があります。Box AI Platform APIは、Enterprise Plusをご利用のすべてのお客様が利用できます。 以下のオプションがあります。 [`POST /2.0/ai_extract`](e://post-ai-extract)エンドポイントを使用すると、指定したファイルから自由な形式でメタデータを抽出できます。つまり、プロンプトの作成の自由度が増すため、リクエストを実行するのにメタデータテンプレートは必要ありません。[`POST /2.0/ai_extract_structured`](e://post-ai-extract-structured)エンドポイントを使用すると、[メタデータテンプレート](https://support.box.com/hc/en-us/articles/360044194033-Customizing-Metadata-Templates)または`fields`構造を使用して、指定したファイルからメタデータを抽出できます。 ## サポート情報 問題がある場合やさらにガイドが必要な場合は、必要なサポートについて、Boxの[Developer Forum](https://forum.box.com/)に英語でリクエストを投稿してください。 **Source:** [https://ja.developer.box.com/changelog/2024-09-17-box-ai-extract](https://ja.developer.box.com/changelog/2024-09-17-box-ai-extract) --- ### Box AI Studio API **Type:** changelog | **Section:** Changelog Box AI Studio API Enterprise Advancedをご利用のすべてのお客様に、Box AI Studio APIの提供を開始しました。Box AI Studioを使用すると、ビジネスニーズに最適なカスタムAIエージェントを作成して管理できます。たとえば、コンプライアンスコンサルタントとして機能し、特定のコンプライアンスルールを念頭に置いて顧客のドキュメントに関する質問に回答するAIエージェントを作成できます。 # Box AI Studio API Enterprise Advancedをご利用のすべてのお客様に、Box AI Studio APIの提供を開始しました。[Box AI Studio](https://support.box.com/hc/en-us/articles/37228079461267-Enabling-Box-AI-Studio-and-Managing-Agents)を使用すると、ビジネスニーズに最適なカスタムAIエージェントを作成して管理できます。たとえば、コンプライアンスコンサルタントとして機能し、特定のコンプライアンスルールを念頭に置いて顧客のドキュメントに関する質問に回答するAIエージェントを作成できます。 Box AI Studio APIを使用すると、以下を実行できます。 - すべてのAIエージェントのリストを取得する - AIエージェントの詳細を取得する - AIエージェントを新規作成する - 既存のAIエージェントを更新する - AIエージェントを削除する この機能の詳細については、Box AI Studio APIの開発者向け[ガイド](https://developer.box.com/guides/ai-studio/getting-started-ai-studio)と[APIリファレンス](https://developer.box.com/reference/get-ai-agents/)を参照してください。 ## サポート情報 問題がある場合やさらにガイドが必要な場合は、必要なサポートについて、Boxの[Developer Forum](https://community.box.com/)に英語でリクエストを投稿してください。 **Source:** [https://ja.developer.box.com/changelog/2025-02-18-box-ai-studio](https://ja.developer.box.com/changelog/2025-02-18-box-ai-studio) --- ### Box Android SDK `v4.2.0`のリリース **Type:** changelog | **Section:** Changelog Box Android SDK v4.2.0のリリース このバージョンは、TLS 1.0のサポート終了後に16台以上のデバイスをサポートすることを目的としています。 # Box Android SDK v4.2.0のリリース このバージョンは、TLS 1.0のサポート終了後に16台以上のデバイスをサポートすることを目的としています。 **Source:** [https://ja.developer.box.com/changelog/2018-06-18-box-android-sdk-v420-released](https://ja.developer.box.com/changelog/2018-06-18-box-android-sdk-v420-released) --- ### Box Android SDK `v4.2.3`のリリース **Type:** changelog | **Section:** Changelog Box Android SDK v4.2.3のリリース さまざまなバグ修正と安定性の改善が含まれます。 # Box Android SDK v4.2.3のリリース さまざまなバグ修正と安定性の改善が含まれます。 **Source:** [https://ja.developer.box.com/changelog/2019-03-18-box-android-sdk-v423-released](https://ja.developer.box.com/changelog/2019-03-18-box-android-sdk-v423-released) --- ### Box APIを使用したZIPアーカイブのダウンロード **Type:** changelog | **Section:** Changelog Box APIを使用したZIPアーカイブのダウンロード 最近リリースされたガイドで、大量のデータのダウンロードについて説明しています。Box APIを使用して、ファイル、フォルダ、またはその両方を含むZIP… # Box APIを使用したZIPアーカイブのダウンロード 最近リリースされた[ガイド](g://downloads/zip-archive)で、大量のデータのダウンロードについて説明しています。Box APIを使用して、ファイル、フォルダ、またはその両方を含むZIPアーカイブを[作成](e://post-zip-downloads)および[ダウンロード](e://get-zip-downloads-id-content)できます。 ## サポート情報 問題がある場合やさらにガイドが必要な場合は、必要なサポートについて、Boxの[Developer Forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum)に英語でリクエストを投稿してください。 **Source:** [https://ja.developer.box.com/changelog/2023-03-08-downloading-zip-archives](https://ja.developer.box.com/changelog/2023-03-08-downloading-zip-archives) --- ### Box CLI `v1.2.0`のリリース **Type:** changelog | **Section:** Changelog Box CLI v1.2.0のリリース 次のコマンドの一括操作が作成されました: ユーザー 更新 グループ 作成 更新 削除 グループメンバーシップ 作成 更新 削除 コラボレーション 追加 更新 削除 イベントタイプによるフィルタをbox events getおよびbox… # Box CLI v1.2.0のリリース - 次のコマンドの一括操作が作成されました: - ユーザー - 更新 - グループ - 作成 - 更新 - 削除 - グループメンバーシップ - 作成 - 更新 - 削除 - コラボレーション - 追加 - 更新 - 削除 - イベントタイプによるフィルタを`box events get`および`box events poll`に追加 - ファイルやフォルダからメタデータテンプレートを削除するコマンドを追加 - 基になる`box-windows-sdk`を`v3.6.0`に昇格 - ファイルやフォルダのメタデータへの浮動小数点型の作成を妨げるバグが修正されました。 - `User-Agent` HTTPヘッダーが正しく割り当てられないバグが修正されました。 - すべてのエラーが`stderr`に報告されないバグを修正しました。 - メタデータテンプレートの一括作成に関するバグが修正されました。 - グループの`membership`コマンドでコマンドが重複するバグが修正されました。 - ユーザーの`tracking_codes`に間違ったオブジェクトが作成されるバグが修正されました。 - ユーザーの一括作成時にCSVファイルのIDが要求されるバグが修正されました。 **Source:** [https://ja.developer.box.com/changelog/2018-04-11-box-cli-v120-release](https://ja.developer.box.com/changelog/2018-04-11-box-cli-v120-release) --- ### Box CLI `v1.4.0`のリリース **Type:** changelog | **Section:** Changelog Box CLI v1.4.0のリリース コラボレーションの有効期限を更新するオプションを追加 # Box CLI v1.4.0のリリース - コラボレーションの有効期限を更新するオプションを追加 **Source:** [https://ja.developer.box.com/changelog/2019-04-10-box-cli-v140-release](https://ja.developer.box.com/changelog/2019-04-10-box-cli-v140-release) --- ### Box CLI `v2.2.0`のリリース **Type:** changelog | **Section:** Changelog Box CLI v2.2.0のリリース v2.2.0リリースの変更ログを更新 (#143) 96b49d5 不要な依存関係を削除 (#141) 7ac5563 サードパーティライセンスのテキストを記録 (#142) 47b78f… # Box CLI v2.2.0のリリース - `v2.2.0`リリースの変更ログを更新 ([#143](https://github.com/box/boxcli/pull/143)) [`96b49d5`](https://github.com/box/boxcli/commit/96b49d5) - 不要な依存関係を削除 ([#141](https://github.com/box/boxcli/pull/141)) [`7ac5563`](https://github.com/box/boxcli/commit/7ac5563) - サードパーティライセンスのテキストを記録 ([#142](https://github.com/box/boxcli/pull/142)) [`47b78f1`](https://github.com/box/boxcli/commit/47b78f1) - コマンドドキュメントを別のページに作成 ([#139](https://github.com/box/boxcli/pull/139)) [`01534f1`](https://github.com/box/boxcli/commit/01534f1) - 変換された委任コマンドで一括入力エラーをキャッチ ([#134](https://github.com/box/boxcli/pull/134)) [`5cd5eee`](https://github.com/box/boxcli/commit/5cd5eee) - メタデータ設定コマンドを追加 ([#136](https://github.com/box/boxcli/pull/136)) [`efa33ed`](https://github.com/box/boxcli/commit/efa33ed) - Issueテンプレートを追加 ([#138](https://github.com/box/boxcli/pull/138)) [`a5cbddf`](https://github.com/box/boxcli/commit/a5cbddf) - 委任されたコマンドでの一括入力中に発生する重複呼び出しを修正 ([#133](https://github.com/box/boxcli/pull/133)) [`ba3d65a`](https://github.com/box/boxcli/commit/ba3d65a) - コレクションへの`web_links`の追加を修正 ([#132](https://github.com/box/boxcli/pull/132)) [`8fc2023`](https://github.com/box/boxcli/commit/8fc2023) - 検索の並べ替えフラグを追加 ([#131](https://github.com/box/boxcli/pull/131)) [`57f8d3d`](https://github.com/box/boxcli/commit/57f8d3d) [`v2.1.0...v2.2.0`](https://github.com/box/boxcli/compare/%60v2.1.0...v2.2.0%60) **Source:** [https://ja.developer.box.com/changelog/2019-05-10-box-cli-v220-release](https://ja.developer.box.com/changelog/2019-05-10-box-cli-v220-release) --- ### Box CLI `v2.3.0`のリリース **Type:** changelog | **Section:** Changelog Box CLI v2.3.0のリリース 変更ログ v2.2.0...v2.3.0 # Box CLI v2.3.0のリリース [変更ログ](https://github.com/box/boxcli/blob/master/CHANGELOG.md#230-2019-05-23) [`v2.2.0...v2.3.0`](https://github.com/box/boxcli/compare/%60v2.2.0...v2.3.0%60) **Source:** [https://ja.developer.box.com/changelog/2019-05-23-box-cli-v230-release](https://ja.developer.box.com/changelog/2019-05-23-box-cli-v230-release) --- ### Box CLI `v2.4.0`のリリース **Type:** changelog | **Section:** Changelog Box CLI v2.4.0のリリース 変更ログ コラボレーションロールを所有者に更新する際の出力を修正 (#165) f8be639 異種コレクションのすべての列をCSVに出力 (#164) a8dda02 plugin-helpを更新してlodash.template… # Box CLI v2.4.0のリリース [変更ログ](https://github.com/box/boxcli/blob/master/CHANGELOG.md#240-2019-08-29) - コラボレーションロールを所有者に更新する際の出力を修正 ([#165](https://github.com/box/boxcli/pull/165)) [`f8be639`](https://github.com/box/boxcli/commit/f8be639) - 異種コレクションのすべての列をCSVに出力 ([#164](https://github.com/box/boxcli/pull/164)) [`a8dda02`](https://github.com/box/boxcli/commit/a8dda02) - plugin-helpを更新して`lodash.template`に関する警告を解決 ([#160](https://github.com/box/boxcli/pull/160)) [`3730bc5`](https://github.com/box/boxcli/commit/3730bc5) - `lodash`を4.17.11から4.17.13に昇格 ([#156](https://github.com/box/boxcli/pull/156)) [`d035e74`](https://github.com/box/boxcli/commit/d035e74) - 外部App User IDの設定のサポートを追加 ([#153](https://github.com/box/boxcli/pull/153)) [`d68b61b`](https://github.com/box/boxcli/commit/d68b61b) - `js-yaml`を3.13.1に更新 ([#151](https://github.com/box/boxcli/pull/151)) [`13745df`](https://github.com/box/boxcli/commit/13745df) [`v2.3.0...v2.4.0`](https://github.com/box/boxcli/compare/%60v2.3.0...v2.4.0%60) **Source:** [https://ja.developer.box.com/changelog/2019-08-29-box-cli-v240-release](https://ja.developer.box.com/changelog/2019-08-29-box-cli-v240-release) --- ### Box CLI `v2.5.1`のリリース **Type:** changelog | **Section:** Changelog Box CLI v2.5.1のリリース 変更ログ stderrへのエラー以外の出力を抑制する--quietフラグを追加 (#167) 27045c6 box folders:updateの--restrict-collaboration… # Box CLI v2.5.1のリリース [変更ログ](https://github.com/box/boxcli/blob/master/CHANGELOG.md#251-2020-04-14) - `stderr`へのエラー以外の出力を抑制する`--quiet`フラグを追加 ([#167](https://github.com/box/boxcli/pull/167)) [`27045c6`](https://github.com/box/boxcli/commit/27045c6) - `box folders:update`の`--restrict-collaboration`フラグのバグを修正。これまで、このフラグは、trueとして渡された場合にコラボレーションが制限されず、falseとして渡された場合にコラボレーションが制限されていました ([#175](https://github.com/box/boxcli/pull/175)) [`e6e1120`](https://github.com/box/boxcli/commit/e6e1120) - ごみ箱内の項目を復元する`box trash:restore`とごみ箱内の項目の情報を取得する`box trash:get`を追加 ([#179](https://github.com/box/boxcli/pull/179)) [`74db947`](https://github.com/box/boxcli/commit/74db947) - 単一のコマンドで複数回指定できるフラグが一括コマンドのコマンドラインで渡されないバグを修正 ([#183](https://github.com/box/boxcli/pull/183)) [`63db0ac`](https://github.com/box/boxcli/commit/63db0ac) - **注**: 新しいリリースプロセスの開発のため、バージョン2.5.0はスキップされました [`v2.4.0...v2.5.1`](https://github.com/box/boxcli/compare/%60v2.4.0...v2.5.1%60) **Source:** [https://ja.developer.box.com/changelog/2020-04-21-box-cli-v251-release](https://ja.developer.box.com/changelog/2020-04-21-box-cli-v251-release) --- ### Box CLI `v2.6.0`のリリース **Type:** changelog | **Section:** Changelog Box CLI v2.6.0のリリース 変更ログ Zip機能の追加 (#203) 1953639 http、https、socks、pacプロトコルのプロキシサポートの追加。プロキシ設定は、box configure:settings (#202) 21671c… # Box CLI v2.6.0のリリース [変更ログ](https://github.com/box/boxcli/blob/master/CHANGELOG.md#260-2020-08-20) - Zip機能の追加 ([#203](https://github.com/box/boxcli/issues/203)) [`1953639`](https://github.com/box/boxcli/commit/1953639fe78def22e9c9d392e784577fc089f842) - `http`、`https`、`socks`、`pac`プロトコルのプロキシサポートの追加。プロキシ設定は、`box configure:settings` ([#202](https://github.com/box/boxcli/issues/202)) [`21671c8`](https://github.com/box/boxcli/commit/21671c854a3fe835eb46df6e640fa2237d23a313)で確認できます。 - Windowsでレポートを保存する際に発生するファイル名の問題を修正 ([#195](https://github.com/box/boxcli/issues/195)) [`31853d3`](https://github.com/box/boxcli/commit/31853d30e9e20a1dc6967a8277fa38165ca671f4) [https://github.com/box/boxcli/compare/v2.5.1...v2.6.0](https://github.com/box/boxcli/compare/v2.5.1...v2.6.0) **Source:** [https://ja.developer.box.com/changelog/2020-08-21-box-cli-v260-released](https://ja.developer.box.com/changelog/2020-08-21-box-cli-v260-released) --- ### Box CLI `v2.7.0`のリリース **Type:** changelog | **Section:** Changelog Box CLI v2.7.0のリリース 新機能と機能強化: 以前非表示になっていたコマンドcollaborations:add、shared-links:update、shared-links:delete、users:searchが使用可能になりました (#21… # Box CLI v2.7.0のリリース **新機能と機能強化:** - 以前非表示になっていたコマンド`collaborations:add`、`shared-links:update`、`shared-links:delete`、`users:search`が使用可能になりました ([#211](https://github.com/box/boxcli/issues/211)) - `filter_term`パラメータを`groups:list`に追加 ([#210](https://github.com/box/boxcli/issues/210)) **バグ修正:** - プロキシ設定に関するバグを修正 ([#213](https://github.com/box/boxcli/issues/213)) **Source:** [https://ja.developer.box.com/changelog/2020-11-04-box-cli-v270-released](https://ja.developer.box.com/changelog/2020-11-04-box-cli-v270-released) --- ### Box CLI `v2.8.0`のリリース **Type:** changelog | **Section:** Changelog Box CLI v2.8.0のリリース 警告: (#217) の変更により、Box項目の詳細が一部のコマンドに対して返されるようになりました。 新機能と機能強化: 一括コマンドの配列の内容を出力 (#217) バグ修正: プロキシ設定に関するバグを修正 (#218) # Box CLI v2.8.0のリリース **警告:** - ([#217](https://github.com/box/boxcli/pull/217)) の変更により、Box項目の詳細が一部のコマンドに対して返されるようになりました。 **新機能と機能強化:** - 一括コマンドの配列の内容を出力 ([#217](https://github.com/box/boxcli/pull/217)) **バグ修正:** - プロキシ設定に関するバグを修正 ([#218](https://github.com/box/boxcli/pull/218)) **Source:** [https://ja.developer.box.com/changelog/2020-12-03-box-cli-v280-released](https://ja.developer.box.com/changelog/2020-12-03-box-cli-v280-released) --- ### Box CLI `v2.9.0`のリリース **Type:** changelog | **Section:** Changelog Box CLI v2.9.0のリリース 新機能と機能強化 メタデータテンプレートの複数選択フィールドにオプションを追加する機能を追加 (#230) フォルダロック機能を追加 (#232) 共有リンク項目を取得するための検索パラメータのサポートを追加 (#23… # Box CLI v2.9.0のリリース ## 新機能と機能強化 - メタデータテンプレートの複数選択フィールドにオプションを追加する機能を追加 ([#230](https://github.com/box/boxcli/pull/230)) - フォルダロック機能を追加 ([#232](https://github.com/box/boxcli/pull/232)) - 共有リンク項目を取得するための検索パラメータのサポートを追加 ([#233](https://github.com/box/boxcli/pull/233)) ## バグ修正 - ストリーム位置のフラグが存在しない場合に発生するイベントコマンドのバグを修正 ([#234](https://github.com/box/boxcli/pull/234)) - folders:uploadコマンドでフォルダのコンテンツをアップロードできないバグを修正 ([#231](https://github.com/box/boxcli/issues/231)) **Source:** [https://ja.developer.box.com/changelog/2021-02-26-box-cli-v290-released](https://ja.developer.box.com/changelog/2021-02-26-box-cli-v290-released) --- ### Box CLI `v3.0.0`のリリース **Type:** changelog | **Section:** Changelog Box CLI v3.0.0のリリース Box CLIのv3.0.0をリリースしました。このリリースでは、OAuth 2.0サポートの追加のほか、いくつかの機能強化を実施しました。 # Box CLI v3.0.0のリリース [Box CLI](https://github.com/box/boxcli/releases)の`v3.0.0`をリリースしました。このリリースでは、OAuth 2.0サポートの追加のほか、いくつかの機能強化を実施しました。 CLIの機能強化やドキュメントの変更に加え、新しく[YouTube動画](https://www.youtube.com/watch?v=whxT3Bdx3E0&list=PL0F3BD5B64D6A39F1) (英語) もリリースしました。この動画では、Box CLIのクイックスタートガイドを使用して、5分ほどでCLIを利用する方法を紹介しています。 ## Developerドキュメントの変更 - OAuth 2.0認証方法の使用について[Box CLIのクイックスタートガイド](g://cli/quick-start)を更新 - [JWTの設定手順](g://cli/cli-docs/jwt-cli)を付録に移動 ## 新機能と機能強化 - OAuthを使用したログインのサポートを追加 ([#240](https://github.com/box/boxcli/pull/240)) - 機能: ファイルの一括処理時やトークンがある場合にas-userフラグをサポート ([#270](https://github.com/box/boxcli/pull/270)) - メタデータテンプレートの`copyInstanceOnItemCopy`フィールドのサポートを追加 ([#239](https://github.com/box/boxcli/pull/239)) - 検索の`mdfilter`の等価チェックにサポートに関する注記を追加 ([#253](https://github.com/box/boxcli/pull/253)) - Box Sign APIのサポートを追加 ([#258](https://github.com/box/boxcli/pull/258)) - メタデータクエリAPIのサポートを追加 ([#259](https://github.com/box/boxcli/pull/259)) - 修正: `folder:collaborations:add`が`role`を必須のフラグに設定 (`SDK-1070`) ([#261](https://github.com/box/boxcli/pull/261)) - 依存関係のマイナーアップグレード - リテンションの対象となっているファイルおよびファイルバージョン用に新しいAPIを追加 ([#250](https://github.com/box/boxcli/issues/250)) - 署名リクエストのサポートを追加 ([#258](https://github.com/box/boxcli/issues/258)) - メタデータクエリAPIをサポート ([#259](https://github.com/box/boxcli/issues/259)) - 作業: 従来のコミットを適用 ([#268](https://github.com/box/boxcli/issues/268)) - 機能: ファイルの一括処理時やトークンがある場合にas-userフラグをサポート ([#270](https://github.com/box/boxcli/issues/270)) ## 重大な変更 - Node 10のサポートを終了 - 不適切な用語の変更 ([#247](https://github.com/box/boxcli/issues/247)、[#252](https://github.com/box/boxcli/issues/252)) ## バグ修正 - 修正: folder:collaborations:addがroleを必須のフラグに設定 ([#261](https://github.com/box/boxcli/issues/261)) - 修正: 共有リンクの削除の例を修正 ([#262](https://github.com/box/boxcli/issues/262)) ## サポート情報 問題がある場合やさらにガイドが必要な場合は、必要なサポートについて、Boxの[Developer Forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum)に英語でリクエストを投稿してください。また、それぞれのGitHubリポジトリでSDKチームにお問い合わせいただくことも可能です。 **Source:** [https://ja.developer.box.com/changelog/2022-02-01-box-cli-v300-released](https://ja.developer.box.com/changelog/2022-02-01-box-cli-v300-released) --- ### Box CLI `v3.1.0`のリリース **Type:** changelog | **Section:** Changelog Box CLI v3.1.0のリリース 新機能と機能強化 検索に、すべての結果を返す--allフラグを追加 (#336) (23ea0a5) OAuth2ログインに一意のstateパラメータを追加 (#292) (5ce6a40) ベースURLの変更を許可 (#303) (e… # Box CLI v3.1.0のリリース ### 新機能と機能強化 - 検索に、すべての結果を返す--allフラグを追加 ([#336](https://github.com/box/boxcli/issues/336)) ([`23ea0a5`](https://github.com/box/boxcli/commit/23ea0a5c5b065ea3b91b73b64bb7b267a6ff0a18)) - `OAuth2`ログインに一意のstateパラメータを追加 ([#292](https://github.com/box/boxcli/issues/292)) ([`5ce6a40`](https://github.com/box/boxcli/commit/5ce6a40b4c6e2fc78b2b598a8b1529200c63902e)) - ベースURLの変更を許可 ([#303](https://github.com/box/boxcli/issues/303)) ([`e284059`](https://github.com/box/boxcli/commit/e28405971ebcf2c2284bb875b40ceb7eaebb41c4)) - コマンドラインから`oauth`承認を取得 ([#299](https://github.com/box/boxcli/issues/299)) ([`18c88bb`](https://github.com/box/boxcli/commit/18c88bb6835509394b92eb0685e3a9306ede8984)) - macOSとWindowsにネイティブの資格情報ストレージを使用 ([#295](https://github.com/box/boxcli/issues/295)) ([`74c4922`](https://github.com/box/boxcli/commit/74c492271ebc54e15500abbaaa2c7aac32be5070)) ### バグ修正 - `users:transfer-content`でquietフラグを考慮 ([#288](https://github.com/box/boxcli/issues/288)) ([`1d0bbab`](https://github.com/box/boxcli/commit/1d0bbab652bf74a59c8486fc4d5eac415161254c)) - `copy-instance-on-item-copy`フラグを正しく渡す ([#285](https://github.com/box/boxcli/issues/285)) ([`cd4fbf4`](https://github.com/box/boxcli/commit/cd4fbf4f746b83c2b066efb31b2e2952dba1312d)) - webhookトリガーの更新を修正 ([#297](https://github.com/box/boxcli/issues/297)) ([`09e94c3`](https://github.com/box/boxcli/commit/09e94c32ed8e4243e76dd19e67b6d1c17c2cdc04)) - `json.stringify`の置き換えにより、`json`フラグ使用時の大量の出力をサポート ([#328](https://github.com/box/boxcli/issues/328)) ([`1204f2c`](https://github.com/box/boxcli/commit/1204f2c146c713124060730e0554ab2f2dde27fa)) - Boxの検索でlimitフラグをサポート ([#323](https://github.com/box/boxcli/issues/323)) ([`0009a77`](https://github.com/box/boxcli/commit/0009a77ee3fc4b72ef01bbbeff0ea588c10a6f89))、[#322](https://github.com/box/boxcli/issues/322)をクローズ - 複数のリダイレクトURIでのOAuthをサポート ([#302](https://github.com/box/boxcli/issues/302)) ([`9fe216e`](https://github.com/box/boxcli/commit/9fe216e8d2f59e4375a4b7c766844366f7166a0a)) **Source:** [https://ja.developer.box.com/changelog/2022-06-17-box-cli-v310-released](https://ja.developer.box.com/changelog/2022-06-17-box-cli-v310-released) --- ### Box CLI `v3.10.0`のリリース **Type:** changelog | **Section:** Changelog Box CLI v3.10.0のリリース 新機能と機能強化 ユーザー追跡コードのサポートを更新 (#489) (159e6d0) # Box CLI v3.10.0のリリース ### 新機能と機能強化 - ユーザー追跡コードのサポートを更新 ([#489](https://github.com/box/boxcli/issues/489)) ([`159e6d0`](https://github.com/box/boxcli/commit/159e6d07fa91f2b199ca85207a4cad5cf4274f0e)) **Source:** [https://ja.developer.box.com/changelog/2023-08-16-box-cli-v3100-released](https://ja.developer.box.com/changelog/2023-08-16-box-cli-v3100-released) --- ### Box CLI `v3.12.0`のリリース **Type:** changelog | **Section:** Changelog Box CLI v3.12.0のリリース 新機能と機能強化 Signテンプレートをサポート (#496) (955106f) # Box CLI v3.12.0のリリース ### 新機能と機能強化 - Signテンプレートをサポート ([#496](https://github.com/box/boxcli/issues/496)) ([`955106f`](https://github.com/box/boxcli/commit/955106ffa5d7938c567e5440868f2ec3c87045ce)) **Source:** [https://ja.developer.box.com/changelog/2023-09-18-box-cli-v3120-released](https://ja.developer.box.com/changelog/2023-09-18-box-cli-v3120-released) --- ### Box CLI `v3.12.1`のリリース **Type:** changelog | **Section:** Changelog Box CLI v3.12.1のリリース バグ修正 ユーザーの取得でオフセットベースのページ割りを強制 (#504) (9bed083) # Box CLI v3.12.1のリリース ### バグ修正 - ユーザーの取得でオフセットベースのページ割りを強制 ([#504](https://github.com/box/boxcli/issues/504)) ([`9bed083`](https://github.com/box/boxcli/commit/9bed083d59b2386d045619fdf2f3ea915e44d231)) **Source:** [https://ja.developer.box.com/changelog/2023-11-06-box-cli-v3121-released](https://ja.developer.box.com/changelog/2023-11-06-box-cli-v3121-released) --- ### Box CLI `v3.12.2`のリリース **Type:** changelog | **Section:** Changelog Box CLI v3.12.2のリリース バグ修正 box-node-sdkを昇格 (#510) (2621f41) # Box CLI v3.12.2のリリース ### バグ修正 - `box-node-sdk`を昇格 ([#510](https://github.com/box/boxcli/issues/510)) ([`2621f41`](https://github.com/box/boxcli/commit/2621f4121999ff6e9d0cc0c391dfd3aa93aefe49)) **Source:** [https://ja.developer.box.com/changelog/2023-11-08-box-cli-v3122-released](https://ja.developer.box.com/changelog/2023-11-08-box-cli-v3122-released) --- ### Box CLI `v3.13.0`のリリース **Type:** changelog | **Section:** Changelog Box CLI v3.13.0のリリース 新機能と機能強化 UseDisplayNameフラグをメタデータ抽出スクリプトに追加 (#515) (b900fdb) 例外をスローする際のコンテキスト情報を追加 (#519) (b99a58d… # Box CLI v3.13.0のリリース ### 新機能と機能強化 - `UseDisplayName`フラグをメタデータ抽出スクリプトに追加 ([#515](https://github.com/box/boxcli/issues/515)) ([`b900fdb`](https://github.com/box/boxcli/commit/b900fdb984345c0fdfeb09e531f6a358ad8c3b8e)) - 例外をスローする際のコンテキスト情報を追加 ([#519](https://github.com/box/boxcli/issues/519)) ([`b99a58d`](https://github.com/box/boxcli/commit/b99a58d930eccf5363c82b84e4415336d7d69541)) - フォルダダウンロード時の上書き/スキップをサポート ([#516](https://github.com/box/boxcli/issues/516)) ([`300f914`](https://github.com/box/boxcli/commit/300f914ba8bb94d9c399699d126d81aba0b22142)) ### バグ修正 - メタデータ抽出スクリプトを修正 ([#514](https://github.com/box/boxcli/issues/514)) ([`2fad540`](https://github.com/box/boxcli/commit/2fad540badf60538fe1456f8071b74bf917f7464)) - 上書きフラグの機能を修正 ([#513](https://github.com/box/boxcli/issues/513)) ([`f4bf7af`](https://github.com/box/boxcli/commit/f4bf7af8e0bbdf7e73fab23d920259ef16672be0)) **Source:** [https://ja.developer.box.com/changelog/2024-02-22-box-cli-v3130-released](https://ja.developer.box.com/changelog/2024-02-22-box-cli-v3130-released) --- ### Box CLI `v3.14.0`のリリース **Type:** changelog | **Section:** Changelog Box CLI v3.14.0のリリース 新機能と機能強化 shared-links作成時のvanity_nameのサポートを追加 (#524) (38164bc) 署名リクエストの署名者グループIDをサポート (#521) (f7b1b44) # Box CLI v3.14.0のリリース ### 新機能と機能強化 - `shared-links`作成時の`vanity_name`のサポートを追加 ([#524](https://github.com/box/boxcli/issues/524)) ([`38164bc`](https://github.com/box/boxcli/commit/38164bc716879aef0a8a2b973a9c6fc7eb705978)) - 署名リクエストの署名者グループIDをサポート ([#521](https://github.com/box/boxcli/issues/521)) ([`f7b1b44`](https://github.com/box/boxcli/commit/f7b1b4409e0f72c264cc23a0f1ca1849060bf121)) **Source:** [https://ja.developer.box.com/changelog/2024-03-06-box-cli-v3140-released](https://ja.developer.box.com/changelog/2024-03-06-box-cli-v3140-released) --- ### Box CLI `v3.14.1`のリリース **Type:** changelog | **Section:** Changelog Box CLI v3.14.1のリリース バグ修正 searchコマンドの一括操作を修正 (#528) (782b0e6) sign-requests:createコマンドの一括操作を修正 (#531) (6d9cd6b) # Box CLI v3.14.1のリリース ### バグ修正 - `search`コマンドの一括操作を修正 ([#528](https://github.com/box/boxcli/issues/528)) ([`782b0e6`](https://github.com/box/boxcli/commit/782b0e6b00905d9724289cb05cf03a708c32ebb3)) - `sign-requests:create`コマンドの一括操作を修正 ([#531](https://github.com/box/boxcli/issues/531)) ([`6d9cd6b`](https://github.com/box/boxcli/commit/6d9cd6b82088185c1b98e8c4ed9ac26af4ee3362)) **Source:** [https://ja.developer.box.com/changelog/2024-06-06-box-cli-v3141-released](https://ja.developer.box.com/changelog/2024-06-06-box-cli-v3141-released) --- ### Box CLI `v3.15.0`のリリース **Type:** changelog | **Section:** Changelog Box CLI v3.15.0のリリース 新機能と機能強化 Box Node SDKの使用でAI APIをサポート (#539) (59551d2) # Box CLI v3.15.0のリリース ### 新機能と機能強化 - Box Node SDKの使用でAI APIをサポート ([#539](https://github.com/box/boxcli/issues/539)) ([`59551d2`](https://github.com/box/boxcli/commit/59551d2153549b5a87b2c3fae01eb3089d640c89)) **Source:** [https://ja.developer.box.com/changelog/2024-08-06-box-cli-v3150-released](https://ja.developer.box.com/changelog/2024-08-06-box-cli-v3150-released) --- ### Box CLI `v3.2.0`のリリース **Type:** changelog | **Section:** Changelog Box CLI v3.2.0のリリース 新機能と機能強化 ストリームタイプadmin_logs_streamingのサポートを追加 (#337) (7596157) バグ修正 ネイティブストレージエラーを修正 (#345) (b73b841) # Box CLI v3.2.0のリリース ### 新機能と機能強化 - ストリームタイプ`admin_logs_streaming`のサポートを追加 ([#337](https://github.com/box/boxcli/issues/337)) ([`7596157`](https://github.com/box/boxcli/commit/7596157e3a72ef152be44a04198e38d6c57de250)) ### バグ修正 - ネイティブストレージエラーを修正 ([#345](https://github.com/box/boxcli/issues/345)) ([`b73b841`](https://github.com/box/boxcli/commit/b73b841224ad7f5bb543c92962adb7fc5960bb8c)) **Source:** [https://ja.developer.box.com/changelog/2022-06-30-box-cli-v320-released](https://ja.developer.box.com/changelog/2022-06-30-box-cli-v320-released) --- ### Box CLI `v3.3.0`のリリース **Type:** changelog | **Section:** Changelog Box CLI v3.3.0のリリース 新機能と機能強化 編集可能な共有リンクのサポートを追加 (#350) (ab639e7) ファイルリクエスト API のサポートを追加 (#355) (73f0490) カスタム分析ヘッダーを設定できる機能を追加 (#348) (5a… # Box CLI v3.3.0のリリース ### 新機能と機能強化 - 編集可能な共有リンクのサポートを追加 ([#350](https://github.com/box/boxcli/issues/350)) ([`ab639e7`](https://github.com/box/boxcli/commit/ab639e7e9336e8745ef84dd6dfc646c987638ec3)) - ファイルリクエスト API のサポートを追加 ([#355](https://github.com/box/boxcli/issues/355)) ([`73f0490`](https://github.com/box/boxcli/commit/73f0490ff3c3dfefb89e14dde933d3a3ffc4113f)) - カスタム分析ヘッダーを設定できる機能を追加 ([#348](https://github.com/box/boxcli/issues/348)) ([`5a3387f`](https://github.com/box/boxcli/commit/5a3387fb687bcbd5d8441117c497312ac1d20f27)) - メタデータテンプレートの更新用に--copy-instance-on-item-copyフラグをサポート ([#357](https://github.com/box/boxcli/issues/357)) ([`5d8272a`](https://github.com/box/boxcli/commit/5d8272a0559ec97a345a2032456998383e7a6716)) - 認証方法としてクライアント資格情報許可をサポート ([#335](https://github.com/box/boxcli/issues/335)) ([`4649d8a`](https://github.com/box/boxcli/commit/4649d8adf39f64c8292b70c35b7bffa96e462edc)) **Source:** [https://ja.developer.box.com/changelog/2022-07-19-box-cli-v330-released](https://ja.developer.box.com/changelog/2022-07-19-box-cli-v330-released) --- ### Box CLI `v3.3.1`のリリース **Type:** changelog | **Section:** Changelog Box CLI v3.3.1のリリース バグ修正 OAuthログインを修正 (#364) (579b44b) # Box CLI v3.3.1のリリース ### バグ修正 - OAuthログインを修正 ([#364](https://github.com/box/boxcli/issues/364)) ([`579b44b`](https://github.com/box/boxcli/commit/579b44b83c60f6568c98cb5f1417effbac26c58c)) **Source:** [https://ja.developer.box.com/changelog/2022-07-25-box-cli-v331-released](https://ja.developer.box.com/changelog/2022-07-25-box-cli-v331-released) --- ### Box CLI `v3.3.2`のリリース **Type:** changelog | **Section:** Changelog Box CLI v3.3.2のリリース バグ修正 本文なしで呼び出す場合についてリクエストコマンドを修正 (#369) (9317888) # Box CLI v3.3.2のリリース ### バグ修正 - 本文なしで呼び出す場合についてリクエストコマンドを修正 ([#369](https://github.com/box/boxcli/issues/369)) ([`9317888`](https://github.com/box/boxcli/commit/9317888c3f1bff56ef784d7319f1b8ccf12239ef)) **Source:** [https://ja.developer.box.com/changelog/2022-07-29-box-cli-v332-released](https://ja.developer.box.com/changelog/2022-07-29-box-cli-v332-released) --- ### Box CLI `v3.4.0`のリリース **Type:** changelog | **Section:** Changelog Box CLI v3.4.0のリリース 新機能と機能強化 User DeprovisionサンプルスクリプトにDryRunモードを追加 (#392) (584a30e) 署名リクエストにredirect_urlとdeclined_redirect_urlを追加 (#39… # Box CLI v3.4.0のリリース ### 新機能と機能強化 - `User Deprovision`サンプルスクリプトに`DryRun`モードを追加 ([#392](https://github.com/box/boxcli/issues/392)) ([`584a30e`](https://github.com/box/boxcli/commit/584a30ef33446a6687ce558c810804202650299f)) - 署名リクエストに`redirect_url`と`declined_redirect_url`を追加 ([#395](https://github.com/box/boxcli/issues/395)) ([`261b7d2`](https://github.com/box/boxcli/commit/261b7d22a5e5adf3647276cbf59454cca9bf607f)) - ファイルのダウンロードと一括コマンド用に進捗バーを追加 ([#376](https://github.com/box/boxcli/issues/376)) ([`68359c7`](https://github.com/box/boxcli/commit/68359c7e97ce2b606184426cbbaac73914ceb81a)) - ダウンロード中に宛先パスを作成 ([#393](https://github.com/box/boxcli/issues/393)) ([`40881dd`](https://github.com/box/boxcli/commit/40881ddbd2c86e80f19689f012736fb19f18d945)) - 新しいライブラリを使用したWindowsにネイティブの資格情報ストレージ ([#385](https://github.com/box/boxcli/issues/385)) ([`a6918aa`](https://github.com/box/boxcli/commit/a6918aaa6e28bd29619bea31c97b845d8d429fec)) ### バグ修正 - フォルダのダウンロードでのホーム`dir`を正しく解決 ([#398](https://github.com/box/boxcli/issues/398)) ([`86d3230`](https://github.com/box/boxcli/commit/86d3230456827a042be04f5ef372b15d83fd6a10)) - `Users Deprovisioning`スクリプトのログを修正 ([#381](https://github.com/box/boxcli/issues/381)) ([`c85f77b`](https://github.com/box/boxcli/commit/c85f77b3042dfc3ddfe54b2acd94b220f6ee0e9b)) - `keytar`ライブラリの問題を修正 ([#394](https://github.com/box/boxcli/issues/394)) ([`1979f01`](https://github.com/box/boxcli/commit/1979f01758a30cd1dbf9d32c19ce2f3a00c0d5ec)) ### 注 格納用Box CLI環境をシステム資格情報ストレージに移行するには、次のコマンドをターミナルで実行します。([#295](https://github.com/box/boxcli/issues/295)) `box configure:environments:update` **Source:** [https://ja.developer.box.com/changelog/2022-09-26-box-cli-v340-released](https://ja.developer.box.com/changelog/2022-09-26-box-cli-v340-released) --- ### Box CLI `v3.5.0`のリリース **Type:** changelog | **Section:** Changelog Box CLI v3.5.0のリリース 新機能と機能強化 ダウンロードしたファイルの名前をsave-asパラメータで変更するオプションを追加 (#415) (81fe64e) 変更可能リテンションポリシーのサポートを追加し、リテンションポリシー割り当ての削除を有効化 (#42… # Box CLI v3.5.0のリリース ### 新機能と機能強化 - ダウンロードしたファイルの名前を`save-as`パラメータで変更するオプションを追加 ([#415](https://github.com/box/boxcli/issues/415)) ([`81fe64e`](https://github.com/box/boxcli/commit/81fe64eb2891e7ab55564e2428f64f1129b468e8)) - 変更可能リテンションポリシーのサポートを追加し、リテンションポリシー割り当ての削除を有効化 ([#420](https://github.com/box/boxcli/issues/420)) ([`26ab5b4`](https://github.com/box/boxcli/commit/26ab5b4d7ec49576fdac48abc025903622f8efe0)) **Source:** [https://ja.developer.box.com/changelog/2022-11-02-box-cli-v350-released](https://ja.developer.box.com/changelog/2022-11-02-box-cli-v350-released) --- ### Box CLI `v3.6.0`のリリース **Type:** changelog | **Section:** Changelog Box CLI v3.6.0のリリース 新機能と機能強化 idおよびtypeフィールドをshared-links:createレスポンスに追加 (#427) (5ea4cb8) リテンションの対象となるファイル用にdisposition_atフィールドを追加 (#429) (db… # Box CLI v3.6.0のリリース ### 新機能と機能強化 - `id`および`type`フィールドをshared-links:createレスポンスに追加 ([#427](https://github.com/box/boxcli/issues/427)) ([`5ea4cb8`](https://github.com/box/boxcli/commit/5ea4cb82294188dd30563ef9cea2c8e0b76bbfae)) - リテンションの対象となるファイル用に`disposition_at`フィールドを追加 ([#429](https://github.com/box/boxcli/issues/429)) ([`db824ef`](https://github.com/box/boxcli/commit/db824ef0b4111810b7902896062c950ef9ac01b3)) ### バグ修正 - `event:poll` polling-intervalを修正 ([#430](https://github.com/box/boxcli/issues/430)) ([`9ada74b`](https://github.com/box/boxcli/commit/9ada74b09eb5aa0e09881946a4f7f30e2d68e037)) **Source:** [https://ja.developer.box.com/changelog/2022-11-22-box-cli-v360-released](https://ja.developer.box.com/changelog/2022-11-22-box-cli-v360-released) --- ### Box CLI `v3.7.0`のリリース **Type:** changelog | **Section:** Changelog Box CLI v3.7.0のリリース 新機能と機能強化 フォルダの更新のコラボレータ用にフラグを追加 (#438) (83ac6d7) セッション終了のサポートを追加 (#446) (aef15a8) バグ修正 ディスクからのトークンのキャッシュの削除を修正 (#44… # Box CLI v3.7.0のリリース ### 新機能と機能強化 - フォルダの更新のコラボレータ用にフラグを追加 ([#438](https://github.com/box/boxcli/issues/438)) ([`83ac6d7`](https://github.com/box/boxcli/commit/83ac6d7c8eeb7f3dc8562c8132cade4f5af80ee1)) - セッション終了のサポートを追加 ([#446](https://github.com/box/boxcli/issues/446)) ([`aef15a8`](https://github.com/box/boxcli/commit/aef15a8d2c7ee904db320d879deb6ebf0f934d22)) ### バグ修正 - ディスクからのトークンのキャッシュの削除を修正 ([#445](https://github.com/box/boxcli/issues/445)) ([`aafb68a`](https://github.com/box/boxcli/commit/aafb68ae38a8280bd97cf978042a8df5b71b2f52)) - 列挙型に複数のオプションを追加する際のメタデータテンプレートの更新を修正 ([#442](https://github.com/box/boxcli/issues/442)) ([`8779eec`](https://github.com/box/boxcli/commit/8779eecf24bda5b093bc891f5097879e1876b601)) - Node 16での単一ファイルのアップロード ([#441](https://github.com/box/boxcli/issues/441)) ([`d94ab35`](https://github.com/box/boxcli/commit/d94ab35a38938daf4edbbd134774a3809facecbd)) **Source:** [https://ja.developer.box.com/changelog/2023-01-19-box-cli-v370-released](https://ja.developer.box.com/changelog/2023-01-19-box-cli-v370-released) --- ### Box CLI `v3.8.0`のリリース **Type:** changelog | **Section:** Changelog Box CLI v3.8.0のリリース 新機能と機能強化 メタデータカスケードポリシーの作成用のエイリアスを追加 (#460) (8d2f683) ログインコマンドに--reauthorizeフラグのサポートを追加 (#457) (f653a0d) バグ修正 keychain… # Box CLI v3.8.0のリリース ### 新機能と機能強化 - メタデータカスケードポリシーの作成用のエイリアスを追加 ([#460](https://github.com/box/boxcli/issues/460)) ([`8d2f683`](https://github.com/box/boxcli/commit/8d2f683e092c036efe352e6fd70904083ad7c208)) - ログインコマンドに`--reauthorize`フラグのサポートを追加 ([#457](https://github.com/box/boxcli/issues/457)) ([`f653a0d`](https://github.com/box/boxcli/commit/f653a0d526c7194f0a5e80dc837f0f16a9d4f27b)) ### バグ修正 - `keychain`ライブラリを`1.4.0`に昇格することで`keychain`アクセスを修正 ([#459](https://github.com/box/boxcli/issues/459)) ([`56919ce`](https://github.com/box/boxcli/commit/56919cefabef6de4d96a1f69f7c80740a680876c)) - 単体テストを修正 ([#456](https://github.com/box/boxcli/issues/456)) ([`f89d9ef`](https://github.com/box/boxcli/commit/f89d9ef5c3c4e7bf00c0be40f128428b1e7e6983)) **Source:** [https://ja.developer.box.com/changelog/2023-03-03-box-cli-v380-released](https://ja.developer.box.com/changelog/2023-03-03-box-cli-v380-released) --- ### Box CLI `v3.9.0`のリリース **Type:** changelog | **Section:** Changelog Box CLI v3.9.0のリリース 新機能と機能強化 max-itemsを追加、エンドポイントのリストのパフォーマンスを改善 (#470) (8f386f3) 統合マッピングAPIのサポートを追加 (#472) (bbf2548) retention-policy… # Box CLI v3.9.0のリリース ### 新機能と機能強化 - `max-items`を追加、エンドポイントのリストのパフォーマンスを改善 ([#470](https://github.com/box/boxcli/issues/470)) ([`8f386f3`](https://github.com/box/boxcli/commit/8f386f3b7c4ff4efbaa941321fd672694ce3c7a1)) - 統合マッピングAPIのサポートを追加 ([#472](https://github.com/box/boxcli/issues/472)) ([`bbf2548`](https://github.com/box/boxcli/commit/bbf2548223e0d07ce2412c04991e7d8f00022fa7)) - `retention-policy`と`retention-policy-assignment`の新しいフィールド ([#466](https://github.com/box/boxcli/issues/466)) ([`f960e59`](https://github.com/box/boxcli/commit/f960e59aaf55fe0a0507e9f4c9d867e7c3dd039a)) **Source:** [https://ja.developer.box.com/changelog/2023-06-02-box-cli-v390-released](https://ja.developer.box.com/changelog/2023-06-02-box-cli-v390-released) --- ### Box CLI `v3.9.1`のリリース **Type:** changelog | **Section:** Changelog Box CLI v3.9.1のリリース 新機能と機能強化 box-node-sdkおよびcsvライブラリのバージョンを昇格 (483) (fecb04b) # Box CLI v3.9.1のリリース ### 新機能と機能強化 - `box-node-sdk`および`csv`ライブラリのバージョンを昇格 ([483]((https://github.com/box/boxcli/pull/483))) ([`fecb04b`]((https://github.com/box/boxcli/pull/483/commits/fecb04b635980baf37a7fefc8860b5e07b0bc4e6))) **Source:** [https://ja.developer.box.com/changelog/2023-07-19-box-cli-v391-released](https://ja.developer.box.com/changelog/2023-07-19-box-cli-v391-released) --- ### Box CLI `v3.9.2`のリリース **Type:** changelog | **Section:** Changelog Box CLI v3.9.2のリリース バグ修正 コマンドに入力を渡す場合のエスケープされたスラッシュを修正 (#486) (7670210) # Box CLI v3.9.2のリリース ### バグ修正 - コマンドに入力を渡す場合のエスケープされたスラッシュを修正 ([#486](https://github.com/box/boxcli/issues/486)) ([`7670210`](https://github.com/box/boxcli/commit/7670210ffb5c38cef8dd153e823029d5237080b6)) **Source:** [https://ja.developer.box.com/changelog/2023-08-08-box-cli-v392-released](https://ja.developer.box.com/changelog/2023-08-08-box-cli-v392-released) --- ### Box CLI `v4.0.0`のリリース **Type:** changelog | **Section:** Changelog Box CLI v4.0.0のリリース ⚠ 重大な変更 古いNodeバージョンのサポートを終了し、TypeScript SDKを統合 (#548) 新機能と機能強化 古いNodeバージョンのサポートを終了し、TypeScript SDKを統合 (#548) (22179ec… # Box CLI v4.0.0のリリース ### ⚠ 重大な変更 - 古いNodeバージョンのサポートを終了し、TypeScript SDKを統合 ([#548](https://github.com/box/boxcli/issues/548)) ### 新機能と機能強化 - 古いNodeバージョンのサポートを終了し、TypeScript SDKを統合 ([#548](https://github.com/box/boxcli/issues/548)) ([`22179ec`](https://github.com/box/boxcli/commit/22179ecfc68b8dd315339ac204a7274d712d5a8e)) - Boxログイン用のブラウザのIncognitoオプション ([#561](https://github.com/box/boxcli/issues/561)) ([`a666766`](https://github.com/box/boxcli/commit/a6667664d6b43fd80de9e57482b0f4138efcd6cf)) - `@oclif/command`を`@oclif/core`ライブラリに置き換え ([#553](https://github.com/box/boxcli/issues/553)) ([`aed470b`](https://github.com/box/boxcli/commit/aed470b22d28ed19040b4417e3143f3323b9a916)) ### バグ修正 - CCG認証およびOAuthに対する環境の`defaultAsUserId`の使用を考慮 ([#554](https://github.com/box/boxcli/issues/554)) ([`b3a691e`](https://github.com/box/boxcli/commit/b3a691e8c886f7bb3a25ae8f7986f284a695f046)) **Source:** [https://ja.developer.box.com/changelog/2025-01-28-box-cli-v400-released](https://ja.developer.box.com/changelog/2025-01-28-box-cli-v400-released) --- ### Box CLI `v4.0.1`のリリース **Type:** changelog | **Section:** Changelog Box CLI v4.0.1のリリース バグ修正 configure:environments:set-currentコマンドを修正 (#568) (dc0905f) # Box CLI v4.0.1のリリース ### バグ修正 - `configure:environments:set-current`コマンドを修正 ([#568](https://github.com/box/boxcli/issues/568)) ([`dc0905f`](https://github.com/box/boxcli/commit/dc0905f7b85a32373e93ec7726afb261223e9fac)) **Source:** [https://ja.developer.box.com/changelog/2025-03-07-box-cli-v401-released](https://ja.developer.box.com/changelog/2025-03-07-box-cli-v401-released) --- ### Box CLI `v4.2.0`のリリース **Type:** changelog | **Section:** Changelog Box CLI v4.2.0のリリース 新機能と機能強化 TS SDKのBox CLIにプロキシを設定 (#577) (ec42077) フォルダの移動でowned-byフラグをサポート (#580) (2ec8e7f) Teams統合マッピングをサポート (#57… # Box CLI v4.2.0のリリース ### 新機能と機能強化 - TS SDKのBox CLIにプロキシを設定 ([#577](https://github.com/box/boxcli/issues/577)) ([`ec42077`](https://github.com/box/boxcli/commit/ec4207715360cc284574e1cbb573586218379517)) - フォルダの移動で`owned-by`フラグをサポート ([#580](https://github.com/box/boxcli/issues/580)) ([`2ec8e7f`](https://github.com/box/boxcli/commit/2ec8e7fcf241dcd2c5841b8912e178e2384db426)) - Teams統合マッピングをサポート ([#579](https://github.com/box/boxcli/issues/579)) ([`163a367`](https://github.com/box/boxcli/commit/163a36727c5f76b0e3b1c36049b3abae50148eb6)) - 配列を使用したメタデータクエリをサポート ([#581](https://github.com/box/boxcli/issues/581)) ([`6750708`](https://github.com/box/boxcli/commit/675070856eac6d06f2091203f4f19e41055dd97d)) **Source:** [https://ja.developer.box.com/changelog/2025-06-20-box-cli-v420-released](https://ja.developer.box.com/changelog/2025-06-20-box-cli-v420-released) --- ### Box CLI `v4.3.0`のリリース **Type:** changelog | **Section:** Changelog Box CLI v4.3.0のリリース 新機能と機能強化 ai:askコマンドにエージェントのサポートを追加 (#589) (095f411) バグ修正 メタデータクエリ配列のサポートを修正 (#583) (112db16) folders:create… # Box CLI v4.3.0のリリース ### 新機能と機能強化 - `ai:ask`コマンドにエージェントのサポートを追加 ([#589](https://github.com/box/boxcli/issues/589)) ([`095f411`](https://github.com/box/boxcli/commit/095f4110274f67c5b1024de49a256b5bbe35cf18)) ### バグ修正 - メタデータクエリ配列のサポートを修正 ([#583](https://github.com/box/boxcli/issues/583)) ([`112db16`](https://github.com/box/boxcli/commit/112db160230e5bb75f84e44cb86a8372341dd8ad)) - folders:createコマンドから`description`フラグを削除 ([#587](https://github.com/box/boxcli/issues/587)) ([`adca76b`](https://github.com/box/boxcli/commit/adca76b5fb03f62daf2104500b87f8a962382a35)) **Source:** [https://ja.developer.box.com/changelog/2025-08-07-box-cli-v430-released](https://ja.developer.box.com/changelog/2025-08-07-box-cli-v430-released) --- ### Box CLI 2.1.0のリリース **Type:** changelog | **Section:** Changelog Box CLI 2.1.0のリリース Box CLIの新しいバージョンがリリースされ、バージョンが2.0.0から2.1.0になりました。このリリースには、以下のように多数の機能強化とバグ修正が含まれています。 イベントコマンドのページングの修正(リンク) lodash… # Box CLI 2.1.0のリリース Box CLIの新しいバージョンがリリースされ、バージョンが2.0.0から2.1.0になりました。このリリースには、以下のように多数の機能強化とバグ修正が含まれています。 - イベントコマンドのページングの修正([リンク](https://github.com/box/boxcli/pull/126)) - `lodash`バージョンの更新([リンク](https://github.com/box/boxcli/pull/129)) - `--fields`フラグの使用時にAPIにフィールドパラメータを送信([リンク](https://github.com/box/boxcli/pull/113)) - イベントタイプフラグの修正([リンク](https://github.com/box/boxcli/pull/120)) - NPMビルドスクリプトの追加([リンク](https://github.com/box/boxcli/commit/f0f88f66e3014afba616b5a2994157d435094b56)) **Source:** [https://ja.developer.box.com/changelog/2019-03-29-box-cli-210-released](https://ja.developer.box.com/changelog/2019-03-29-box-cli-210-released) --- ### Box CLI V2のリリース **Type:** changelog | **Section:** Changelog Box CLI V2のリリース [Box CLI][guide]のメジャーバージョン (V2) がリリースされました。 更新情報については次のリンクを参照してください。 リリースノート: 大きな修正の詳細、重大な変更、バグの修正。 コマンドの一覧: 新しいCLI… # Box CLI V2のリリース [Box CLI][guide]のメジャーバージョン (V2) がリリースされました。 更新情報については次のリンクを参照してください。 - [リリースノート](https://github.com/box/boxcli/blob/master/CHANGELOG.md#200): 大きな修正の詳細、重大な変更、バグの修正。 - [コマンドの一覧](https://github.com/box/boxcli#command-topics): 新しいCLIで利用可能なすべてのコマンド。 - [インストールオプション][guide]: スタンドアロンインストーラとソースコードオプション。 [ガイド][guide]: [g://cli/quick-start/install-and-configure][g://cli/quick-start/install-and-configure] **Source:** [https://ja.developer.box.com/changelog/2018-12-21-box-cli-v2-released](https://ja.developer.box.com/changelog/2018-12-21-box-cli-v2-released) --- ### Box CLIとスクリプトライブラリによるタスクの自動化 **Type:** changelog | **Section:** Changelog Box CLIとスクリプトライブラリによるタスクの自動化 Box CLIは、タスクの自動化に使用できるテンプレートを含むサンプルスクリプトライブラリに対応するようになりました。まずは、以下を実行できるPowerShellスクリプトを提供します: フォルダ構造を設定する 管理対象ユーザーを作成する ユーザーをフォルダ構造にコラボレータとして追加する # Box CLIとスクリプトライブラリによるタスクの自動化 [Box CLI](g://cli)は、タスクの自動化に使用できるテンプレートを含むサンプルスクリプトライブラリに対応するようになりました。まずは、以下を実行できるPowerShellスクリプトを提供します: - フォルダ構造を設定する - 管理対象ユーザーを作成する - ユーザーをフォルダ構造にコラボレータとして追加する ## 更新内容 - Box CLIの[クイックスタートガイド](g://cli/quick-start/powershell-script-templates)に、PowerShellスクリプトを使用してフォルダ構造とコラボレータを作成する手順を記載しました。 - サンプルスクリプトはすべて[スクリプトライブラリ](https://github.com/box/boxcli/tree/main/examples)に含まれています。現在はPowerShellスクリプトが含まれていますが、今後さらにサンプルが追加される予定です。 ## 開発者向けリソース Box App Centerでのアプリケーションの作成、またはBoxパートナーへの参加をご希望の場合、詳細については[Box Partner Resources](https://support.box.com/hc/en-us/sections/360009473734-Box-Partner-Resources)のガイド (英語) を参照してください。 ## サポート情報 問題がある場合やさらにガイドが必要な場合は、必要なサポートについて、Boxの[Developer Forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum)に英語でリクエストを投稿してください。 **Source:** [https://ja.developer.box.com/changelog/2022-06-23-new-cli-script](https://ja.developer.box.com/changelog/2022-06-23-new-cli-script) --- ### Box CLIの更新 **Type:** changelog | **Section:** Changelog Box CLIの更新 Box CLIへの更新がリリースされました。このバージョンには以下の更新が含まれます。 新しいマルチゾーンコマンド: データ保管場所用のBox Multizonesのサポートが追加されました。 ユーザーによるCSV操作の修正: ユーザーがOpen With… # Box CLIの更新 [Box CLI](guide://cli/quick-start)への更新がリリースされました。このバージョンには以下の更新が含まれます。 **[新しいマルチゾーンコマンド](https://github.com/box/boxcli/pull/91)**: データ保管場所用の[Box Multizones](https://blog.box.com/blog/multizones-storage-data-residency-compliance/)のサポートが追加されました。 **[ユーザーによるCSV操作の修正](https://github.com/box/boxcli/pull/82)**: ユーザーがOpen With Elementを使用できなかったバグが修正されました。Open With Elementが、ユーザーデータのベータをCSVファイルに保存しなくなりました。 **[フォルダの更新時に`can_non_owners_invite`を設定する機能](https://github.com/box/boxcli/pull/92)**: 所有者以外のユーザーが他のユーザーをフォルダでのコラボレーションに招待できるかどうかを設定できるようになりました。 **[新しいCLI構成のダンプコマンド](https://github.com/box/boxcli/pull/83)**: 値をコピーして一般的な用途に使えるよう、Box構成ファイルを単一の文字列としてダンプする機能が追加されました。オプションで、エスケープ引用符を追加できます。Open Withは、環境変数または構成プロパティを (AWSの個別のボタンやAzureなどで) 提供します。 **Source:** [https://ja.developer.box.com/changelog/2018-06-25-update-to-the-box-cli](https://ja.developer.box.com/changelog/2018-06-25-update-to-the-box-cli) --- ### Box CLIの更新 **Type:** changelog | **Section:** Changelog Box CLIの更新 Box CLIスクリプトライブラリとCLIガイドへの最近の追加により、自動化がさらに改善され、反復タスクの処理が簡素化されました。 # Box CLIの更新 [Box CLIスクリプトライブラリ](g://cli/scripts)と[CLIガイド](g://cli/cli-docs)への最近の追加により、自動化がさらに改善され、反復タスクの処理が簡素化されました。 ## 新しいCLIスクリプト サンプルスクリプトライブラリに次のスクリプトが含まれ、使用できるようになりました。 - [ユーザーとフォルダのプロビジョニング](g://cli/scripts/provision-users-folders): 実装するフォルダ構造を構築してユーザーを追加します。 - [グループとコラボレーションの管理](g://cli/scripts/manage-groups-collaborations): グループを作成または更新し、グループにユーザーを追加して、最後にコラボレータとしてグループをフォルダに追加します。 - [非アクティブなユーザーのレポート](g://cli/scripts/report-inactive-users): 一定の日数の間非アクティブであったユーザーのリストをCSVファイルで生成します。 - [ユーザーのゾーンの更新](g://cli/scripts/user-zones-mass-update): マルチゾーンのBoxテナント内の特定のデータ保管場所のゾーンにユーザーをプロビジョニングします。 - [ユーザーのプロビジョニング解除](g://cli/scripts/deprovision-users): ユーザーを削除します。 ## 一括コマンドガイド [一括コマンドガイド](g://cli/cli-docs/bulk-commands)では、単一のコマンドを使用して、複数の項目が関与する操作を実行する方法について説明します。 ## 開発者向けリソース Box App Centerでのアプリケーションの作成、またはBoxパートナーへの参加をご希望の場合、詳細については[Box Partner Resources](https://support.box.com/hc/en-us/sections/360009473734-Box-Partner-Resources)のガイド (英語) を参照してください。 ## サポート情報 問題がある場合やさらにガイドが必要な場合は、必要なサポートについて、Boxの[Developer Forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum)に英語でリクエストを投稿してください。 **Source:** [https://ja.developer.box.com/changelog/2022-08-24-new-cli-scripts-added](https://ja.developer.box.com/changelog/2022-08-24-new-cli-scripts-added) --- ### Box CLIの高度な機能についてのYouTube動画のリリース **Type:** changelog | **Section:** Changelog Box CLIの高度な機能についてのYouTube動画のリリース 2月に、Box CLIのOAuth 2.0バージョンと並行して新しいYouTubeコンテンツをリリースしました。本日、このシリーズの3つ目の動画をリリースしました。この動画ではas-userヘッダーと一括コマンドオプションの使用について説明しています。 # Box CLIの高度な機能についてのYouTube動画のリリース 2月に、Box CLIのOAuth 2.0バージョンと並行して新しいYouTubeコンテンツを[リリース](https://developer.box.com/changelog/#2022-02-01-box-cli-v300-released)しました。本日、このシリーズの[3つ目の動画](https://youtu.be/WXkBctPosLE)をリリースしました。この動画ではas-userヘッダーと一括コマンドオプションの使用について説明しています。 [YouTube](https://www.youtube.com/playlist?list=PL0F3BD5B64D6A39F1)のBox Platform and Developerというプレイリストをご確認ください。このシリーズではもう1つの動画 (PowerShellを使用したCLI自動化) を予定しています。 最新のコンテンツをすべて入手するには、ぜひBoxチャンネルに[ご登録](https://www.youtube.com/user/box/featured)ください。 ## サポート情報 問題がある場合やさらにガイドが必要な場合は、必要なサポートについて、Boxの[Developer Forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum)に英語でリクエストを投稿してください。 **Source:** [https://ja.developer.box.com/changelog/2022-09-06-cli-video-3](https://ja.developer.box.com/changelog/2022-09-06-cli-video-3) --- ### Box Content Preview `v2.57.0`のリリース **Type:** changelog | **Section:** Changelog Box Content Preview v2.57.0のリリース 新機能と機能強化: コアコントロールコンポーネントのReactバージョンを追加 (#1282) 既存のコントロールアイコンのReactバージョンを追加 (#128… # Box Content Preview v2.57.0のリリース **新機能と機能強化:** - コアコントロールコンポーネントのReactバージョンを追加 ([#1282](https://github.com/box/box-content-preview/pull/1282)) - 既存のコントロールアイコンのReactバージョンを追加 ([#1280](https://github.com/box/box-content-preview/pull/1280)) - 全画面コントロールとズームコントロールのReactバージョンを追加 ([#1283](https://github.com/box/box-content-preview/pull/1283)) - テキストビューアーコントロールのReactバージョンを追加 ([#1284](https://github.com/box/box-content-preview/pull/1284)) - 注釈作成の手段を追加 ([#1275](https://github.com/box/box-content-preview/pull/1275)) - `react`および`react-dom`を`^16.9.0`にアップグレード ([#1278](https://github.com/box/box-content-preview/pull/1278)) **バグ修正:** - 新しく作成した注釈を選択 ([#1276](https://github.com/box/box-content-preview/pull/1276)) - Chromeで埋め込みリンクを使用したファイルのダウンロードを許可 ([#1277](https://github.com/box/box-content-preview/pull/1277)) - フォントのレンダリングに関する問題により`pdf.js`を`v2.2.228`に戻す ([#1274](https://github.com/box/box-content-preview/pull/1274)) **Source:** [https://ja.developer.box.com/changelog/2020-11-13-box-content-preview-v2570-released](https://ja.developer.box.com/changelog/2020-11-13-box-content-preview-v2570-released) --- ### Box Developer Communityサイト (英語のみ) **Type:** changelog | **Section:** Changelog Box Developer Communityサイト (英語のみ) 開発者と管理者向けに、Box Developer Communityサイト (英語のみ) を公開しました。ここでは、仲間や専門家とつながって、Boxのクラウドコンテンツ管理とコラボレーションプラットフォーム上に革新的なアプリケーションを構築することができます。https://forum.box.comからご参加ください。 # Box Developer Communityサイト (英語のみ) 開発者と管理者向けに、Box Developer Communityサイト (英語のみ) を公開しました。ここでは、仲間や専門家とつながって、Boxのクラウドコンテンツ管理とコラボレーションプラットフォーム上に革新的なアプリケーションを構築することができます。[https://forum.box.com](https://forum.box.com)からご参加ください。 # 参加してつながり、学習する - サポートを受けてフィードバックを提供する - 知識を共有してコミュニティリーダーになる - 他のBox開発者や管理者とつながってチャットで会話する - 他のコミュニティのメンバーやBoxに関するエキスパートから学習する - 最新の機能、更新情報、開発者向けのイベント、ブログ投稿などにアクセスする ## サポートを受けるための新しい場所 今後は新しい[Box Developer Communityフォーラム](https://forum.box.com/)で質問したり、ガイダンスを受けたりすることができます。この新しいフォーラムを利用すると、Box Developer Relationsチーム、同僚、Boxに関するエキスパートと直接会話できます。 **Source:** [https://ja.developer.box.com/changelog/2023-06-13-join-box-developer-community](https://ja.developer.box.com/changelog/2023-06-13-join-box-developer-community) --- ### Box Doc Gen **Type:** changelog | **Section:** Changelog Box Doc Gen Enterprise Advancedをご利用のすべてのお客様に、Box Doc Genの提供を開始しました。 Box Doc Genを使用すると、BoxにアップロードしたBox Doc Genテンプレートに基づいて、さまざまなビジネスドキュメントを生成できます。Box Doc Gen APIの使用により、データフィールドへの動的な入力も可能です。 # Box Doc Gen **Enterprise Advanced**をご利用のすべてのお客様に、[Box Doc Gen](g://docgen/docgen-getting-started/)の提供を開始しました。 [Box Doc Gen](https://developer.box.com/guides/docgen)を使用すると、BoxにアップロードしたBox Doc Genテンプレートに基づいて、さまざまなビジネスドキュメントを生成できます。Box Doc Gen APIの使用により、データフィールドへの動的な入力も可能です。 Box Doc Genの機能を使用すると、以下を実行できます。 - [ファイルをBox Doc Genテンプレートとして設定](g://docgen/mark-template/) - [ドキュメントを生成](g://docgen/generate-document/) - [Box Doc Genジョブ](g://docgen/docgen-jobs/)のステータスを確認 Box Doc GenおよびBox Doc Gen APIの詳細については、[Box Doc Genの開発者向けガイド](https://developer.box.com/guides/docgen)および[APIリファレンス](e://post-docgen-templates/)をそれぞれご確認ください。 ## サポート情報 問題がある場合やさらにガイドが必要な場合は、必要なサポートについて、Boxの[Developer Forum](https://forum.box.com/)に英語でリクエストを投稿してください。 **Source:** [https://ja.developer.box.com/changelog/2025-01-13-box-doc-gen](https://ja.developer.box.com/changelog/2025-01-13-box-doc-gen) --- ### Box Dotnet SDK Generated `v0.4.0`のリリース **Type:** changelog | **Section:** Changelog Box Dotnet SDK Generated v0.4.0のリリース バグ修正 ベースURLを変更 (box/box-codegen#491) (#126) (b4c6025) 自動更新のプルリクエストのCIを修正 (box/box-codegen#506) (#15… # Box Dotnet SDK Generated v0.4.0のリリース ### バグ修正 - ベースURLを変更 (box/box-codegen[#491](https://github.com/box/box-codegen/issues/491)) ([#126](https://github.com/box/box-codegen/issues/126)) ([`b4c6025`](https://github.com/box/box-codegen/commit/b4c6025dc7039e923b19282333f162bb9d3469a9)) - 自動更新のプルリクエストのCIを修正 (box/box-codegen[#506](https://github.com/box/box-codegen/issues/506)) ([#152](https://github.com/box/box-codegen/issues/152)) ([`766f03c`](https://github.com/box/box-codegen/commit/766f03c743b7a2ab363135ff282e468b6b71d377)) - ファイルやフォルダの分類を更新するためのスキーマを修正 (box/box-openapi[#423](https://github.com/box/box-codegen/issues/423)) ([#117](https://github.com/box/box-codegen/issues/117)) ([`40f5a97`](https://github.com/box/box-codegen/commit/40f5a97ea44118ff9425e8b0ebb767d9ed08cee7)) - Box Signの表現を改善 (box/box-openapi[#424](https://github.com/box/box-codegen/issues/424)) ([#122](https://github.com/box/box-codegen/issues/122)) ([`64b3bcd`](https://github.com/box/box-codegen/commit/64b3bcd2d99039d1c881a565de6e7bc40dfe7aa9)) ### 新機能と機能強化 - インターフェースメソッドのデフォルトの実装を追加 (box/box-codegen[#502](https://github.com/box/box-codegen/issues/502)) ([#148](https://github.com/box/box-codegen/issues/148)) ([`0f39071`](https://github.com/box/box-codegen/commit/0f39071d2442b9d07f9c51de8a5a757b16cc4fe7)) - ドキュメントの改善とマーカーページ割りを追加 (box/box-openapi[#431](https://github.com/box/box-codegen/issues/431)) ([#153](https://github.com/box/box-codegen/issues/153)) ([`780a58b`](https://github.com/box/box-codegen/commit/780a58b4d4b18c357381c76dd5e72dd791a20d89)) - 汎用型の`ExtraData`のサポートを追加 (box/box-codegen[#521](https://github.com/box/box-codegen/issues/521)) ([#170](https://github.com/box/box-codegen/issues/170)) ([`2a2208d`](https://github.com/box/box-codegen/commit/2a2208d422f5beb1718576acdc10d9eb973ba95c)) - プリミティブ型の共用体のサポートを追加 (box/box-codegen[#501](https://github.com/box/box-codegen/issues/501)) ([#150](https://github.com/box/box-codegen/issues/150)) ([`e75ce82`](https://github.com/box/box-codegen/commit/e75ce82b09641d4bec439d620facbbf25da97845)) - モデルを変更不可に設定し、認証に関するフィールドを非表示にする (box/box-codegen[#494](https://github.com/box/box-codegen/issues/494)) ([#127](https://github.com/box/box-codegen/issues/127)) ([`8adcc85`](https://github.com/box/box-codegen/commit/8adcc858ef0f924f168406b031d379c786fa90d0)) - Box Signの`SuppressNotifications`および`ExternalSystemName`フィールドを追加 (box/box-openapi[#425](https://github.com/box/box-codegen/issues/425)) ([#124](https://github.com/box/box-codegen/issues/124)) ([`c841881`](https://github.com/box/box-codegen/commit/c841881cea9b0636bb624fe45d77c2817327dd35)) - `StringEnum`をサポート (box/box-codegen[#514](https://github.com/box/box-codegen/issues/514)) ([#162](https://github.com/box/box-codegen/issues/162)) ([`6ac2fe9`](https://github.com/box/box-codegen/commit/6ac2fe9811efde6b02cd3ca50834b0bdafea1ab3)) **Source:** [https://ja.developer.box.com/changelog/2024-07-03-box-dotnet-sdk-generated-v040-released](https://ja.developer.box.com/changelog/2024-07-03-box-dotnet-sdk-generated-v040-released) --- ### Box Dotnet SDK Generated `v1.0.0`のリリース **Type:** changelog | **Section:** Changelog Box Dotnet SDK Generated v1.0.0のリリース バグ修正 IntegrationMappingPartnerItemSlackをIntegrationMappingPartnerItemSlackUnionに抽出 (box/box-codegen#53… # Box Dotnet SDK Generated v1.0.0のリリース ### バグ修正 - `IntegrationMappingPartnerItemSlack`を`IntegrationMappingPartnerItemSlackUnion`に抽出 (box/box-codegen[#530](https://github.com/box/box-codegen/issues/530)) ([#183](https://github.com/box/box-codegen/issues/183)) ([`3b1b634`](https://github.com/box/box-codegen/commit/3b1b634904edc73af094aa8aa6e89d32b9e92aee)) - 分割アップロードの信頼性を改善 (box/box-codegen[#529](https://github.com/box/box-codegen/issues/529)) ([#182](https://github.com/box/box-codegen/issues/182)) ([`e2a045f`](https://github.com/box/box-codegen/commit/e2a045f5d2afbe15be0284099ee2236f9c19cd73)) - 必須フィールドの一部から`init`を削除、`nullability`の修正 (box/box-codegen[#532](https://github.com/box/box-codegen/issues/532)) ([#190](https://github.com/box/box-codegen/issues/190)) ([`c58f8af`](https://github.com/box/box-codegen/commit/c58f8afa41fa4346eb3f2ced9e48695980e917e1)) - `retry-after`ヘッダーが設定されているステータスコード202のリクエストを再試行 (box/box-codegen[#533](https://github.com/box/box-codegen/issues/533)) ([#191](https://github.com/box/box-codegen/issues/191)) ([`abaafd7`](https://github.com/box/box-codegen/commit/abaafd70b982ae560430ff083b4bee1d533d5275)) - 分割アップロードを更新 (box/box-codegen[#523](https://github.com/box/box-codegen/issues/523)) ([#177](https://github.com/box/box-codegen/issues/177)) ([`9bcaf51`](https://github.com/box/box-codegen/commit/9bcaf51e0bcd3134dea2b37277a24abaa483754a)) ### 新機能と機能強化 - ユーザーコラボレーションに`is_active`パラメータを追加 (box/box-openapi[#437](https://github.com/box/box-codegen/issues/437)) ([#181](https://github.com/box/box-codegen/issues/181)) ([`ec5f2d1`](https://github.com/box/box-codegen/commit/ec5f2d1d2cdba330f26a7db40042b70d3ec5bca2)) - `namespaces`を簡略化 (box/box-codegen[#518](https://github.com/box/box-codegen/issues/518)) ([#175](https://github.com/box/box-codegen/issues/175)) ([`7831b09`](https://github.com/box/box-codegen/commit/7831b098971616497cbc90a8c277fee9b2c42c39)) - AIエージェントAPIをサポート (box/box-codegen[#531](https://github.com/box/box-codegen/issues/531)) ([#188](https://github.com/box/box-codegen/issues/188)) ([`0c29645`](https://github.com/box/box-codegen/commit/0c296458ef966e57c5aba2a8068034d4de820ef9)) - デフォルトのインターフェースプロパティをサポートし、依存関係を昇格 (box/box-codegen[#527](https://github.com/box/box-codegen/issues/527)) ([#184](https://github.com/box/box-codegen/issues/184)) ([`6b52792`](https://github.com/box/box-codegen/commit/6b52792057ab94f6bcc2f86b47e0ed5f25900adf)) **Source:** [https://ja.developer.box.com/changelog/2024-07-24-box-dotnet-sdk-generated-v100-released](https://ja.developer.box.com/changelog/2024-07-24-box-dotnet-sdk-generated-v100-released) --- ### Box Dotnet SDK Generated `v1.1.0`のリリース **Type:** changelog | **Section:** Changelog Box Dotnet SDK Generated v1.1.0のリリース バグ修正 不足していたitem_uploadスコープを追加 (#201) (483b055) Signテンプレートの署名者に不足していたフィールドを追加し、AIスキーマを修正 (box/box… # Box Dotnet SDK Generated v1.1.0のリリース ### バグ修正 - 不足していた`item_upload`スコープを追加 ([#201](https://github.com/box/box-codegen/issues/201)) ([`483b055`](https://github.com/box/box-codegen/commit/483b05586f8e45771e101d286fddebc564ff89bd)) - Signテンプレートの署名者に不足していたフィールドを追加し、AIスキーマを修正 (box/box-openapi[#451](https://github.com/box/box-codegen/issues/451)) ([#229](https://github.com/box/box-codegen/issues/229)) ([`121f733`](https://github.com/box/box-codegen/commit/121f733f52e945927125f4941206b1553202914d)) - `IntegrationMapping`スキーマを修正 (box/box-codegen[#551](https://github.com/box/box-codegen/issues/551)) ([#226](https://github.com/box/box-codegen/issues/226)) ([`3eca154`](https://github.com/box/box-codegen/commit/3eca15434b65bc0bb2421d36ec50691e7fe40e3b)) - ネットワークの例外処理を改善し、大きなファイルのアップロードを処理 (box/box-openapi[#444](https://github.com/box/box-codegen/issues/444)) ([#222](https://github.com/box/box-codegen/issues/222)) ([`75ccd07`](https://github.com/box/box-codegen/commit/75ccd078e29015b865462ea1aaf0420d5e63d9cd)) ### 新機能と機能強化 - Box AIのメソッドに新しいパラメータを追加し、`AiResponseFull`バリアントを導入 (box/box-openapi[#446](https://github.com/box/box-codegen/issues/446)) ([#224](https://github.com/box/box-codegen/issues/224)) ([`6d205c4`](https://github.com/box/box-codegen/commit/6d205c4e28a657ad65ae704a7343a8670806f7f1)) - `FetchOptions`にURLを追加 (box/box-codegen[#549](https://github.com/box/box-codegen/issues/549)) ([#231](https://github.com/box/box-codegen/issues/231)) ([`41c45dc`](https://github.com/box/box-codegen/commit/41c45dcf6476b6cae7941c0952c375aa76ce42a1)) - 分割アップロードのエンドポイントURLをパラメータ化 (box/box-openapi[#444](https://github.com/box/box-codegen/issues/444)) ([#208](https://github.com/box/box-codegen/issues/208)) ([`feac37c`](https://github.com/box/box-codegen/commit/feac37c34f99b5951731b605ef895f7f3b5de6dd)) - `nullable`フィールドをサポート (box/box-codegen[#550](https://github.com/box/box-codegen/issues/550)) ([#230](https://github.com/box/box-codegen/issues/230)) ([`b9da32b`](https://github.com/box/box-codegen/commit/b9da32b27f506618faa0119f725528555be14f60)) **Source:** [https://ja.developer.box.com/changelog/2024-08-23-box-dotnet-sdk-generated-v110-released](https://ja.developer.box.com/changelog/2024-08-23-box-dotnet-sdk-generated-v110-released) --- ### Box Dotnet SDK Generated `v1.10.0`のリリース **Type:** changelog | **Section:** Changelog Box Dotnet SDK Generated v1.10.0のリリース 新機能と機能強化 UploadWithPreflightCheckコンビニエンスメソッドを追加 (box/box-codegen#705) (#469) (8dff7bb) AI… # Box Dotnet SDK Generated v1.10.0のリリース ### 新機能と機能強化 - `UploadWithPreflightCheck`コンビニエンスメソッドを追加 (box/box-codegen[#705](https://github.com/box/box-dotnet-sdk-gen/issues/705)) ([#469](https://github.com/box/box-dotnet-sdk-gen/issues/469)) ([`8dff7bb`](https://github.com/box/box-dotnet-sdk-gen/commit/8dff7bb859cd034d4e43b81c7c11b9a3fdb396e8)) - AIエージェントの警告を追加し、より多くの種類のメタデータ値を許可 (box/box-openapi[#520](https://github.com/box/box-dotnet-sdk-gen/issues/520)) ([#474](https://github.com/box/box-dotnet-sdk-gen/issues/474)) ([`a53cff5`](https://github.com/box/box-dotnet-sdk-gen/commit/a53cff54395db91bad179d3c5bbae9800c1b79dd)) - Signテンプレートスキーマにセキュリティ設定のプロパティを追加 (box/box-openapi[#518](https://github.com/box/box-dotnet-sdk-gen/issues/518)) ([#462](https://github.com/box/box-dotnet-sdk-gen/issues/462)) ([`7fddaea`](https://github.com/box/box-dotnet-sdk-gen/commit/7fddaeab425a859dc1aa5dc3420891047d27efdf)) - AI APIにIBMモデルのサポートを追加 (box/box-openapi[#522](https://github.com/box/box-dotnet-sdk-gen/issues/522)) ([#475](https://github.com/box/box-dotnet-sdk-gen/issues/475)) ([`a187301`](https://github.com/box/box-dotnet-sdk-gen/commit/a187301543d6741c77799b66fde0f12d4fca710d)) - エラーの機密データのサニタイズをサポート (box/box-codegen[#695](https://github.com/box/box-dotnet-sdk-gen/issues/695)) ([#453](https://github.com/box/box-dotnet-sdk-gen/issues/453)) ([`5ee0c93`](https://github.com/box/box-dotnet-sdk-gen/commit/5ee0c932254a0cd1cc7bc814c29fe5f9e2151462)) **Source:** [https://ja.developer.box.com/changelog/2025-05-13-box-dotnet-sdk-generated-v1100-released](https://ja.developer.box.com/changelog/2025-05-13-box-dotnet-sdk-generated-v1100-released) --- ### Box Dotnet SDK Generated `v1.11.0`のリリース **Type:** changelog | **Section:** Changelog Box Dotnet SDK Generated v1.11.0のリリース バグ修正 トークンの取得にretrieveTokenメソッドを使用するようダウンスコープトークンを修正 (box/box-codegen#731) (#492) (292360e) イベントのnext… # Box Dotnet SDK Generated v1.11.0のリリース ### バグ修正 - トークンの取得に`retrieveToken`メソッドを使用するようダウンスコープトークンを修正 (box/box-codegen[#731](https://github.com/box/box-dotnet-sdk-gen/issues/731)) ([#492](https://github.com/box/box-dotnet-sdk-gen/issues/492)) ([`292360e`](https://github.com/box/box-dotnet-sdk-gen/commit/292360efe86797e42dbfb388a5bd2f5b41efa0c1)) - イベントの`next_stream_position`プロパティタイプを`long`に指定 (box/box-openapi[#535](https://github.com/box/box-dotnet-sdk-gen/issues/535)) ([#536](https://github.com/box/box-dotnet-sdk-gen/issues/536)) ([`da265bd`](https://github.com/box/box-dotnet-sdk-gen/commit/da265bd5c40defc4b2036811aefad59447faca09)) ### 新機能と機能強化 - Unionに`ReadOnlyCollection`型へのimplicit演算子を追加 (box/box-codegen[#633](https://github.com/box/box-dotnet-sdk-gen/issues/633)) ([#483](https://github.com/box/box-dotnet-sdk-gen/issues/483)) ([`a1fc2c5`](https://github.com/box/box-dotnet-sdk-gen/commit/a1fc2c584021c151fc9d1815877ffe73c972f711)) - AIスプレッドシートプロセッサを追加 (box/box-openapi[#533](https://github.com/box/box-dotnet-sdk-gen/issues/533)) ([#519](https://github.com/box/box-dotnet-sdk-gen/issues/519)) ([`c344023`](https://github.com/box/box-dotnet-sdk-gen/commit/c34402355243145a1cab7da78c6c2facde39fb36)) - アーカイブの公開APIを追加 (box/box-openapi[#540](https://github.com/box/box-dotnet-sdk-gen/issues/540)) ([#543](https://github.com/box/box-dotnet-sdk-gen/issues/543)) ([`be0bb9d`](https://github.com/box/box-dotnet-sdk-gen/commit/be0bb9d3e58f97bc87f749d08d828c990c71789b)) - 新しいHubs APIとHubの項目APIを追加 (box/box-openapi[#538](https://github.com/box/box-dotnet-sdk-gen/issues/538)) ([#537](https://github.com/box/box-dotnet-sdk-gen/issues/537)) ([`f2584cd`](https://github.com/box/box-dotnet-sdk-gen/commit/f2584cd9be40b67eaa3a500411b367543a26f830)) - `Metadata Error`の新しいスキーマを追加 (box/box-openapi[#539](https://github.com/box/box-dotnet-sdk-gen/issues/539)) ([#538](https://github.com/box/box-dotnet-sdk-gen/issues/538)) ([`425b4ad`](https://github.com/box/box-dotnet-sdk-gen/commit/425b4add7975d49584c8ed18a791caf72559203c)) - ShieldリストAPIを追加 (box/box-openapi[#528](https://github.com/box/box-dotnet-sdk-gen/issues/528)) ([#496](https://github.com/box/box-dotnet-sdk-gen/issues/496)) ([`8b81c87`](https://github.com/box/box-dotnet-sdk-gen/commit/8b81c879c8b8bb5c020ecb573e527e2a5d9f1701)) - JWTの秘密キー復号メカニズムの挿入を許可 (box/box-codegen[#754](https://github.com/box/box-dotnet-sdk-gen/issues/754)) ([#528](https://github.com/box/box-dotnet-sdk-gen/issues/528)) ([`865c729`](https://github.com/box/box-dotnet-sdk-gen/commit/865c729395556a3c4a8bb1f1418c3932d268bdc4)) - `OneOf`クラスをpublicに変更 (box/box-codegen[#773](https://github.com/box/box-dotnet-sdk-gen/issues/773)) ([#551](https://github.com/box/box-dotnet-sdk-gen/issues/551)) ([`f7dcc32`](https://github.com/box/box-dotnet-sdk-gen/commit/f7dcc3262b289da55ebc6210c5656cc98e3b14b4)) - Hubsのベータ版エンドポイントをサポート (box/box-openapi[#531](https://github.com/box/box-dotnet-sdk-gen/issues/531)) ([#511](https://github.com/box/box-dotnet-sdk-gen/issues/511)) ([`59c43b8`](https://github.com/box/box-dotnet-sdk-gen/commit/59c43b868e46edd26be0be13a5e1772a4d731128)) - AI Studioの新しいツールをサポート (box/box-openapi[#534](https://github.com/box/box-dotnet-sdk-gen/issues/534)) ([#520](https://github.com/box/box-dotnet-sdk-gen/issues/520)) ([`0b47597`](https://github.com/box/box-dotnet-sdk-gen/commit/0b47597f259884a2a5f567608e9e07997e3c6dc9)) - リーガルホールドとAIモデルを更新 (box/box-openapi[#526](https://github.com/box/box-dotnet-sdk-gen/issues/526)) ([#494](https://github.com/box/box-dotnet-sdk-gen/issues/494)) ([`6310e56`](https://github.com/box/box-dotnet-sdk-gen/commit/6310e560df6d9520598295139f55ec8a0a4d69d9)) **Source:** [https://ja.developer.box.com/changelog/2025-08-05-box-dotnet-sdk-generated-v1110-released](https://ja.developer.box.com/changelog/2025-08-05-box-dotnet-sdk-generated-v1110-released) --- ### Box Dotnet SDK Generated `v1.2.0`のリリース **Type:** changelog | **Section:** Changelog Box Dotnet SDK Generated v1.2.0のリリース バグ修正 queryParamsでdatetimeを正しく送信 (box/box-codegen#560) (#243) (9657526) メタデータクエリの結果のバリアントを修正 (box/box… # Box Dotnet SDK Generated v1.2.0のリリース ### バグ修正 - `queryParams`で`datetime`を正しく送信 (box/box-codegen[#560](https://github.com/box/box-codegen/issues/560)) ([#243](https://github.com/box/box-codegen/issues/243)) ([`9657526`](https://github.com/box/box-codegen/commit/9657526667753d77eacfd674cde60ab4030ae42d)) - メタデータクエリの結果のバリアントを修正 (box/box-openapi[#456](https://github.com/box/box-codegen/issues/456)) ([#249](https://github.com/box/box-codegen/issues/249)) ([`37625ea`](https://github.com/box/box-codegen/commit/37625eabe4f87d57a9f58920829c00cddd34bcb1)) ### 新機能と機能強化 - Hubsベータ版を追加 (box/box-openapi[#453](https://github.com/box/box-codegen/issues/453)) ([#241](https://github.com/box/box-codegen/issues/241)) ([`c28f660`](https://github.com/box/box-codegen/commit/c28f6605c94e250bbab853ef610c46c1d3c9ef95)) - タイプに未加工の`json`を追加 (box/box-codegen[#567](https://github.com/box/box-codegen/issues/567)) ([#258](https://github.com/box/box-codegen/issues/258)) ([`a1e7bc5`](https://github.com/box/box-codegen/commit/a1e7bc55da0dec8bfd1159a1c158154177581019)) - `ai/extract`および`ai/extract_structured`エンドポイントをサポート (box/box-codegen[#564](https://github.com/box/box-codegen/issues/564)) ([#253](https://github.com/box/box-codegen/issues/253)) ([`a17d8f8`](https://github.com/box/box-codegen/commit/a17d8f8dbce8ac7f42b9e23c8c216e992a64d762)) **Source:** [https://ja.developer.box.com/changelog/2024-09-26-box-dotnet-sdk-generated-v120-released](https://ja.developer.box.com/changelog/2024-09-26-box-dotnet-sdk-generated-v120-released) --- ### Box Dotnet SDK Generated `v1.3.0`のリリース **Type:** changelog | **Section:** Changelog Box Dotnet SDK Generated v1.3.0のリリース バグ修正 system.text.jsonを8.0.5に昇格 (box/box-codegen#578) (#271) (dad2f52) 新機能と機能強化 プロキシをサポート (box/box… # Box Dotnet SDK Generated v1.3.0のリリース ### バグ修正 - `system.text.json`を8.0.5に昇格 (box/box-codegen[#578](https://github.com/box/box-codegen/issues/578)) ([#271](https://github.com/box/box-codegen/issues/271)) ([`dad2f52`](https://github.com/box/box-codegen/commit/dad2f521066e73c3dcdaec196cd6940401e31f3a)) ### 新機能と機能強化 - プロキシをサポート (box/box-codegen[#564](https://github.com/box/box-codegen/issues/577)) ([#253](https://github.com/box/box-codegen/issues/274)) ([`dea1937`](https://github.com/box/box-codegen/commit/dea19373a7169365acb968a66c78c5937ef698e1)) **Source:** [https://ja.developer.box.com/changelog/2024-10-17-box-dotnet-sdk-generated-v130-released](https://ja.developer.box.com/changelog/2024-10-17-box-dotnet-sdk-generated-v130-released) --- ### Box Dotnet SDK Generated `v1.3.1`のリリース **Type:** changelog | **Section:** Changelog Box Dotnet SDK Generated v1.3.1のリリース バグ修正 クエリのparams内でStringEnumリストを正しくシリアル化 (#288) (dac8392) スキーマエラーをサポートするようクライアントエラースキーマを更新 (box/box… # Box Dotnet SDK Generated v1.3.1のリリース ### バグ修正 - クエリの`params`内で`StringEnum`リストを正しくシリアル化 ([#288](https://github.com/box/box-codegen/issues/288)) ([`dac8392`](https://github.com/box/box-codegen/commit/dac839280b43f4bd954d3966032ff4925150c061)) - スキーマエラーをサポートするようクライアントエラースキーマを更新 (box/box-openapi[#467](https://github.com/box/box-codegen/issues/467)) ([#281](https://github.com/box/box-codegen/issues/281)) ([`bef2632`](https://github.com/box/box-codegen/commit/bef2632af99f0477bd009bcb91248c678b4e1bab)) - 統合マッピングのレスポンスの説明を更新 (box/box-openapi[#463](https://github.com/box/box-codegen/issues/463)) ([#279](https://github.com/box/box-codegen/issues/279)) ([`05e07b0`](https://github.com/box/box-codegen/commit/05e07b025c234de4c4161e567c0919748d24f804)) **Source:** [https://ja.developer.box.com/changelog/2024-10-24-box-dotnet-sdk-generated-v131-released](https://ja.developer.box.com/changelog/2024-10-24-box-dotnet-sdk-generated-v131-released) --- ### Box Dotnet SDK Generated `v1.4.0`のリリース **Type:** changelog | **Section:** Changelog Box Dotnet SDK Generated v1.4.0のリリース バグ修正 MetadataQueryのQueryParamsのタイプをDictionaryからDictionaryに変更 (box/box… # Box Dotnet SDK Generated v1.4.0のリリース ### バグ修正 - `MetadataQuery`の`QueryParams`のタイプを`Dictionary<string, string>`から`Dictionary<string, object>`に変更 (box/box-openapi[#479](https://github.com/box/box-codegen/issues/479)) ([#298](https://github.com/box/box-codegen/issues/298)) ([`656b495`](https://github.com/box/box-codegen/commit/656b495bea779879bb82b2cda0cca5a30a8ad8ca)) - `RSAKey`への変換を修正 (box/box-codegen[#591](https://github.com/box/box-codegen/issues/591)) ([#297](https://github.com/box/box-codegen/issues/297)) ([`068b1f7`](https://github.com/box/box-codegen/commit/068b1f7b3ea3c62647e03e0e17176bde049949db)) ### 新機能と機能強化 - AI LLMエンドポイントのAWS `params`を追加。タイプを`AiLlmEndpointParamsGoogleOrAiLlmEndpointParamsOpenAi`から`AiLlmEndpointParamsAwsOrAiLlmEndpointParamsGoogleOrAiLlmEndpointParamsOpenAi`に変更 (box/box-openapi[#478](https://github.com/box/box-codegen/issues/478)) ([#291](https://github.com/box/box-codegen/issues/291)) ([`dcb8a20`](https://github.com/box/box-codegen/commit/dcb8a201577be08b644266c157db45cd6797c71c)) **Source:** [https://ja.developer.box.com/changelog/2024-10-31-box-dotnet-sdk-generated-v140-released](https://ja.developer.box.com/changelog/2024-10-31-box-dotnet-sdk-generated-v140-released) --- ### Box Dotnet SDK Generated `v1.5.0`のリリース **Type:** changelog | **Section:** Changelog Box Dotnet SDK Generated v1.5.0のリリース バグ修正 コンテンツのないステータスコードをサポート (box/box-codegen#604) (#314) (57747d5) コラボレーション、メタデータ、コレクションのリソースを更新 (box… # Box Dotnet SDK Generated v1.5.0のリリース ### バグ修正 - コンテンツのないステータスコードをサポート (box/box-codegen[#604](https://github.com/box/box-dotnet-sdk-gen/issues/604)) ([#314](https://github.com/box/box-dotnet-sdk-gen/issues/314)) ([`57747d5`](https://github.com/box/box-dotnet-sdk-gen/commit/57747d50c48dd4c433dad342a5e2a20ac0b15952)) - コラボレーション、メタデータ、コレクションのリソースを更新 (box/box-openapi[#483](https://github.com/box/box-dotnet-sdk-gen/issues/483)) ([#316](https://github.com/box/box-dotnet-sdk-gen/issues/316)) ([`d331f8a`](https://github.com/box/box-dotnet-sdk-gen/commit/d331f8a1f7110e5e00df170cedef85af682d58b4)) ### 新機能と機能強化 - 省略可能なURLパラメータを`FetchResponse`に追加 (box/box-codegen[#617](https://github.com/box/box-dotnet-sdk-gen/issues/617)) ([#331](https://github.com/box/box-dotnet-sdk-gen/issues/331)) ([`61484ec`](https://github.com/box/box-dotnet-sdk-gen/commit/61484ec9fbf96c0ae62116ec1ee0cbb50aae7493)) - プロキシに対するデフォルトの資格情報の使用を許可 (box/box-codegen[#623](https://github.com/box/box-dotnet-sdk-gen/issues/623)) ([#334](https://github.com/box/box-dotnet-sdk-gen/issues/334)) ([`bc4636e`](https://github.com/box/box-dotnet-sdk-gen/commit/bc4636e64859fd7d0b1449ec34b6144d0eb1a768))、[#333](https://github.com/box/box-dotnet-sdk-gen/issues/333)をクローズ - カスタムHTTPリクエストを行うためのメソッドを公開 (box/box-codegen[#622](https://github.com/box/box-dotnet-sdk-gen/issues/622)) ([#329](https://github.com/box/box-dotnet-sdk-gen/issues/329)) ([`e689140`](https://github.com/box/box-dotnet-sdk-gen/commit/e689140d6d3be772ff2370e7de5797707df7bdad)) - IDを指定してコレクションを取得エンドポイントをサポート (box/box-codegen[#595](https://github.com/box/box-dotnet-sdk-gen/issues/595)) ([#304](https://github.com/box/box-dotnet-sdk-gen/issues/304)) ([`9ebf59a`](https://github.com/box/box-dotnet-sdk-gen/commit/9ebf59ae388aa9aec5d8a0a3551f13e544c7571d)) **Source:** [https://ja.developer.box.com/changelog/2024-12-04-box-dotnet-sdk-generated-v150-released](https://ja.developer.box.com/changelog/2024-12-04-box-dotnet-sdk-generated-v150-released) --- ### Box Dotnet SDK Generated `v1.7.0`のリリース **Type:** changelog | **Section:** Changelog Box Dotnet SDK Generated v1.7.0のリリース バグ修正 ファイルレプリゼンテーションのpagedおよびthumbプロパティのタイプを修正 (box/box-openapi#503) (#383) (d6995ad… # Box Dotnet SDK Generated v1.7.0のリリース ### バグ修正 - ファイルレプリゼンテーションの`paged`および`thumb`プロパティのタイプを修正 (box/box-openapi[#503](https://github.com/box/box-dotnet-sdk-gen/issues/503)) ([#383](https://github.com/box/box-dotnet-sdk-gen/issues/383)) ([`d6995ad`](https://github.com/box/box-dotnet-sdk-gen/commit/d6995ad8ffa4f2cceb8195ffbfb6606f934a671f)) - クロスオリジンのリダイレクト時に`Authentication`ヘッダーが渡されるのを防止 (box/box-codegen[#648](https://github.com/box/box-dotnet-sdk-gen/issues/648)) ([#382](https://github.com/box/box-dotnet-sdk-gen/issues/382)) ([`a64d373`](https://github.com/box/box-dotnet-sdk-gen/commit/a64d373a935cd2a8e6f72184b8dc129a973e9d45)) ### 新機能と機能強化 - Box Signの共有リクエストを追加 (box/box-openapi[#504](https://github.com/box/box-dotnet-sdk-gen/issues/504)) ([#384](https://github.com/box/box-dotnet-sdk-gen/issues/384)) ([`d563886`](https://github.com/box/box-dotnet-sdk-gen/commit/d563886f2a2f48a20df13600f9c25ff95198a56f)) - 機能: /ai/askにHubのサポートを追加。`AiAsk`クラスの`Items`プロパティのタイプを`IReadOnlyList<AiItemBase>`から`IReadOnlyList<AiItemAsk>`に置き換え (box/box-codegen[#656](https://github.com/box/box-dotnet-sdk-gen/issues/656)) ([#397](https://github.com/box/box-dotnet-sdk-gen/issues/397)) ([`32b6d03`](https://github.com/box/box-dotnet-sdk-gen/commit/32b6d03aba97c18a8901efe98fc60c74e10197ce)) - `/ai/extract_structured`レスポンスのスキーマを更新 (box/box-codegen[#641](https://github.com/box/box-dotnet-sdk-gen/issues/641)) ([#391](https://github.com/box/box-dotnet-sdk-gen/issues/391)) ([`5f79a03`](https://github.com/box/box-dotnet-sdk-gen/commit/5f79a03453b9339a26eb130113d8f55748f0d912)) **Source:** [https://ja.developer.box.com/changelog/2025-02-06-box-dotnet-sdk-generated-v170-released](https://ja.developer.box.com/changelog/2025-02-06-box-dotnet-sdk-generated-v170-released) --- ### Box Dotnet SDK Generated `v1.8.0`のリリース **Type:** changelog | **Section:** Changelog Box Dotnet SDK Generated v1.8.0のリリース バグ修正 TaskCanceledExceptionがスローされた場合にHTTPリクエストを再試行しない (box/box-codegen#665) (#406) (1af0a6a) 新機能と機能強化 AI… # Box Dotnet SDK Generated v1.8.0のリリース ### バグ修正 - `TaskCanceledException`がスローされた場合にHTTPリクエストを再試行しない (box/box-codegen[#665](https://github.com/box/box-dotnet-sdk-gen/issues/665)) ([#406](https://github.com/box/box-dotnet-sdk-gen/issues/406)) ([`1af0a6a`](https://github.com/box/box-dotnet-sdk-gen/commit/1af0a6aaf5f1e80f092ce506abe1cc01bf110bb8)) ### 新機能と機能強化 - AI Studio APIをサポート (box/box-codegen[#626](https://github.com/box/box-dotnet-sdk-gen/issues/626)) ([#409](https://github.com/box/box-dotnet-sdk-gen/issues/409)) ([`9661450`](https://github.com/box/box-dotnet-sdk-gen/commit/966145021d4a1dd450cd199cc9ed3e9457f5a141)) **Source:** [https://ja.developer.box.com/changelog/2025-02-20-box-dotnet-sdk-generated-v180-released](https://ja.developer.box.com/changelog/2025-02-20-box-dotnet-sdk-generated-v180-released) --- ### Box Dotnet SDK Generated `v1.9.0`のリリース **Type:** changelog | **Section:** Changelog Box Dotnet SDK Generated v1.9.0のリリース バグ修正 verification_phone_numberプロパティを追加して署名リクエストを作成 (box/box-openapi#515) (#427) (d90faea) 単一の.NET… # Box Dotnet SDK Generated v1.9.0のリリース ### バグ修正 - `verification_phone_number`プロパティを追加して署名リクエストを作成 (box/box-openapi[#515](https://github.com/box/box-dotnet-sdk-gen/issues/515)) ([#427](https://github.com/box/box-dotnet-sdk-gen/issues/427)) ([`d90faea`](https://github.com/box/box-dotnet-sdk-gen/commit/d90faea77650a37ce794a93c51bd9a8eb91f619c)) - 単一の.NETバージョンがサポートされている場合に`targetFramework`を使用 (box/box-codegen[#684](https://github.com/box/box-dotnet-sdk-gen/issues/684)) ([#438](https://github.com/box/box-dotnet-sdk-gen/issues/438)) ([`4e64174`](https://github.com/box/box-dotnet-sdk-gen/commit/4e64174c21c6f1dd2cef75f1f29ebe2ace92d852)) ### 新機能と機能強化 - 共有リンクのアプリ項目を検索するエンドポイントを追加 (box/box-openapi[#514](https://github.com/box/box-dotnet-sdk-gen/issues/514)) ([#426](https://github.com/box/box-dotnet-sdk-gen/issues/426)) ([`4dc5dc1`](https://github.com/box/box-dotnet-sdk-gen/commit/4dc5dc14e3c204c537180df166d07735ae1c4e40)) - Teams統合マッピング (リスト) APIを追加 (box/box-openapi[#517](https://github.com/box/box-dotnet-sdk-gen/issues/517)) ([#429](https://github.com/box/box-dotnet-sdk-gen/issues/429)) ([`92063c4`](https://github.com/box/box-dotnet-sdk-gen/commit/92063c435d7cb38a7eeca2e71f42e32b995a659a)) - 認証クラス用のトークンストレージを公開 (box/box-codegen[#682](https://github.com/box/box-dotnet-sdk-gen/issues/682)) ([#435](https://github.com/box/box-dotnet-sdk-gen/issues/435)) ([`413058e`](https://github.com/box/box-dotnet-sdk-gen/commit/413058e78cb69c89be6a819c0e63f9457bd7f2f5)) **Source:** [https://ja.developer.box.com/changelog/2025-03-18-box-dotnet-sdk-generated-v190-released](https://ja.developer.box.com/changelog/2025-03-18-box-dotnet-sdk-generated-v190-released) --- ### Box Embedガイドの更新 **Type:** changelog | **Section:** Changelog Box Embedガイドの更新 Box Embedを使用すると、Boxウェブアプリをアプリケーションの任意の場所に埋め込むことができます。更新されたウェブアプリは、さまざまな変更に対応可能です。たとえば、統合で埋め込まれたBox… # Box Embedガイドの更新 [Box Embed](g://embed/box-embed/)を使用すると、Boxウェブアプリをアプリケーションの任意の場所に埋め込むことができます。更新されたウェブアプリは、さまざまな変更に対応可能です。たとえば、統合で埋め込まれたBoxウェブアプリが縮小された場合、ボタンやリストなどすべてのUIコンポーネントも、引き続き使用できるようにサイズが変更されます。 また、この更新にはクラウドゲーム (クリックジャッキングを防止してセキュリティを強化するためのウィジェット) の説明も含まれます。 # サポート情報 問題がある場合やさらにガイドが必要な場合は、必要なサポートについて、Boxの[Developer Forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum)に英語でリクエストを投稿してください。 **Source:** [https://ja.developer.box.com/changelog/2023-04-20-box-embed-guide-update](https://ja.developer.box.com/changelog/2023-04-20-box-embed-guide-update) --- ### Box for Salesforce管理パッケージのUI Elements **Type:** changelog | **Section:** Changelog Box for Salesforce管理パッケージのUI Elements Box for Salesforce管理パッケージで、Content Picker、エクスプローラ、プレビュー、アップローダーのUI ElementsをLightning… # Box for Salesforce管理パッケージのUI Elements [Box for Salesforce](g://tooling/salesforce-toolkit/)管理パッケージで、[Content Picker](g://embed/ui-elements/picker/)、[エクスプローラ](g://embed/ui-elements/explorer)、[プレビュー](g://embed/ui-elements/preview)、[アップローダー](g://embed/ui-elements/uploader)の[UI Elements](g://embed/ui-elements/)をLightningコンポーネントとして使用できます。これらのUI ElementsはLightningページまたはLightningフローで使用できます。 ## サポート情報 問題がある場合やさらにガイドが必要な場合は、必要なサポートについて、Boxの[Developer Forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum)に英語でリクエストを投稿してください。 **Source:** [https://ja.developer.box.com/changelog/2023-05-26-salesforce-ui-elements](https://ja.developer.box.com/changelog/2023-05-26-salesforce-ui-elements) --- ### Box Hubs API **Type:** changelog | **Section:** Changelog Box Hubs API Box Hubs APIを使用すると、アプリケーション内でプログラムによってコンテンツのHubの作成、管理、コラボレーションを行うことができます。Hubにより、チームやプロジェクト間のコンテンツの整理や共有を1か所で行うことができます。 Hubs APIを使用してできること Hubs APIは、主に以下の3種類のリソースで構成されており、これらのリソースにより包括的なHub管理機能を構築できます。 # Box Hubs API Box Hubs APIを使用すると、アプリケーション内でプログラムによってコンテンツのHubの作成、管理、コラボレーションを行うことができます。Hubにより、チームやプロジェクト間のコンテンツの整理や共有を1か所で行うことができます。 ## Hubs APIを使用してできること Hubs APIは、主に以下の3種類のリソースで構成されており、これらのリソースにより包括的なHub管理機能を構築できます。 [Hub](https://developer.box.com/reference/v2025.0/resources/hub/) - Hubを作成 - Hubをコピー - IDを指定してHubの情報を更新 - Hubを削除 - すべてのHubのリストを取得 - リクエストしている企業のすべてのHubのリストを取得 - IDを指定してHubの情報を取得 [Hubコラボレーション](https://developer.box.com/reference/v2025.0/resources/hub-collaboration/) - Hubコラボレーションを作成 - Hubコラボレーションを更新 - Hubコラボレーションを削除 - Hubコラボレーションを取得 - コラボレーションIDを指定してHubコラボレーションを取得 [Hubの項目](https://developer.box.com/reference/v2025.0/resources/hub-item/) - Hubの項目を取得 - Hubの項目を管理 Box Hubsの使用の詳細については、[Box Hubsのサポートドキュメント](https://support.box.com/hc/en-us/sections/26102544955027-Box-Hubs)を参照してください。 ## サポート情報 問題がある場合やさらにガイドが必要な場合は、必要なサポートについて、Boxの[Developer Forum](https://community.box.com/)に英語でリクエストを投稿してください。 **Source:** [https://ja.developer.box.com/changelog/2025-08-01-box-hubs-apis](https://ja.developer.box.com/changelog/2025-08-01-box-hubs-apis) --- ### Box iOS SDK `v4.0.0`のリリース **Type:** changelog | **Section:** Changelog Box iOS SDK v4.0.0のリリース Box iOS SDK 重大な変更: タスク割り当てのstatusフィールドを文字列から列挙型に変更 macOS、tvOS、およびwatchOSのサポートを削除 新機能と機能強化: 認証セッションクラスOAuth2Session… # Box iOS SDK v4.0.0のリリース Box iOS SDK **重大な変更:** - タスク割り当ての`status`フィールドを文字列から列挙型に変更 - `macOS`、`tvOS`、および`watchOS`のサポートを削除 **新機能と機能強化:** - 認証セッションクラス`OAuth2Session`、`SingleTokenSession`、`DelegatedAuthSession`を公開 **Source:** [https://ja.developer.box.com/changelog/2020-02-13-box-ios-sdk-v400-released](https://ja.developer.box.com/changelog/2020-02-13-box-ios-sdk-v400-released) --- ### Box iOS SDK `v4.1.0`のリリース **Type:** changelog | **Section:** Changelog Box iOS SDK v4.1.0のリリース Box iOS SDK… # Box iOS SDK v4.1.0のリリース Box iOS SDK **重大な変更:** **新機能と機能強化:** - アップロードとダウンロードをキャンセルする機能を追加 - ファイルとファイルバージョンのアップローダー表示名フィールドのサポートを追加 - ファイルとフォルダの分類フィールドのサポートを追加 - パスパラメータのサニタイズを追加 **バグ修正:** - APIレスポンスのログ記録を修正 **Source:** [https://ja.developer.box.com/changelog/2020-05-15-box-ios-sdk-v410-released](https://ja.developer.box.com/changelog/2020-05-15-box-ios-sdk-v410-released) --- ### Box iOS SDK `v4.2.0`のリリース **Type:** changelog | **Section:** Changelog Box iOS SDK v4.2.0のリリース 重大な変更: 新機能と機能強化: 接続が切断されたOAuthウェブセッションのエラー情報を追加 バグ修正: コラボレーションの作成に関するバグを修正 Enterprise Eventの取得に関するバグを修正 # Box iOS SDK v4.2.0のリリース **重大な変更:** **新機能と機能強化:** - 接続が切断されたOAuthウェブセッションのエラー情報を追加 **バグ修正:** - コラボレーションの作成に関するバグを修正 - Enterprise Eventの取得に関するバグを修正 **Source:** [https://ja.developer.box.com/changelog/2020-11-17-box-ios-sdk-v420-released](https://ja.developer.box.com/changelog/2020-11-17-box-ios-sdk-v420-released) --- ### Box iOS SDK `v4.3.0`のリリース **Type:** changelog | **Section:** Changelog Box iOS SDK v4.3.0のリリース 重大な変更: 新機能と機能強化: OAuth 2カスタムコールバックURLのサポートを追加 (#746) zipダウンロードのサポートを追加 (#749) バグ修正: kramdownの脆弱性にパッチを適用するためにgem… # Box iOS SDK v4.3.0のリリース **重大な変更:** **新機能と機能強化:** - OAuth 2カスタムコールバックURLのサポートを追加 ([#746](https://github.com/box/box-ios-sdk/pull/746)) - zipダウンロードのサポートを追加 ([#749](https://github.com/box/box-ios-sdk/pull/749)) **バグ修正:** - `kramdown`の脆弱性にパッチを適用するためにgemを更新 ([#742](https://github.com/box/box-ios-sdk/pull/742)) - `activesupport`の脆弱性にパッチを適用するためにgemを更新 ([#745](https://github.com/box/box-ios-sdk/pull/745)) **Source:** [https://ja.developer.box.com/changelog/2021-02-01-box-ios-sdk-v430-released](https://ja.developer.box.com/changelog/2021-02-01-box-ios-sdk-v430-released) --- ### Box iOS SDK `v4.4.0`のリリース **Type:** changelog | **Section:** Changelog Box iOS SDK v4.4.0のリリース 重大な変更: 新機能と機能強化: 共有リンク項目を取得するための検索パラメータのサポートを追加 (#756) フォルダロック機能のサポートを追加 (#759) メタデータテンプレートのcopyInstanceOnItemCopy… # Box iOS SDK v4.4.0のリリース **重大な変更:** **新機能と機能強化:** - 共有リンク項目を取得するための検索パラメータのサポートを追加 ([#756](https://github.com/box/box-ios-sdk/pull/756)) - フォルダロック機能のサポートを追加 ([#759](https://github.com/box/box-ios-sdk/pull/759)) - メタデータテンプレートの`copyInstanceOnItemCopy`フィールドのサポートを追加 ([#763](https://github.com/box/box-ios-sdk/pull/763)) - 新しいファイルバージョンのストリームアップロードのサポートを追加、新しいファイルバージョンのアップロード時の「If-Match」ヘッダーのサポートを追加 ([#766](https://github.com/box/box-ios-sdk/pull/766)) - `Event`モデルの詳細フィールドを追加 ([#770](https://github.com/box/box-ios-sdk/pull/770)) **バグ修正:** - iOS認証APIにスキーマのみを渡す ([#755](https://github.com/box/box-ios-sdk/pull/755)) - 名前によるフィルタにドキュメントされたパラメータを使用するよう`listEnterpriseGroups()`を更新 ([#757](https://github.com/box/box-ios-sdk/pull/757)) - トークンが取り消された場合にコールバックが呼び出されない、OAuthのバグを修正 ([#762](https://github.com/box/box-ios-sdk/pull/762)) **Source:** [https://ja.developer.box.com/changelog/2021-04-20-box-ios-sdk-v440-released](https://ja.developer.box.com/changelog/2021-04-20-box-ios-sdk-v440-released) --- ### Box iOS SDK `v5.0.0`のリリース **Type:** changelog | **Section:** Changelog Box iOS SDK v5.0.0のリリース 重大な変更: ページを返してロジックを簡素化するようPagingIteratorを更新 (#737) BoxClientの不適切な用語フィールドcollaborationWhiteList… # Box iOS SDK v5.0.0のリリース **重大な変更:** - ページを返してロジックを簡素化するようPagingIteratorを更新 ([#737](https://github.com/box/box-ios-sdk/pull/737)) - BoxClientの不適切な用語フィールド`collaborationWhiteList`を削除し、代わりに`collaborationAllowList`を使用 ([#790](https://github.com/box/box-ios-sdk/pull/790)) **新機能と機能強化:** - 不適切なイベントタイプを置き換え ([#785](https://github.com/box/box-ios-sdk/pull/785)) - SignAPIのサポートを追加 ([#792](https://github.com/box/box-ios-sdk/pull/792)) **Source:** [https://ja.developer.box.com/changelog/2021-10-28-box-ios-sdk-v500-released](https://ja.developer.box.com/changelog/2021-10-28-box-ios-sdk-v500-released) --- ### Box iOS SDK `v5.1.0`のリリース **Type:** changelog | **Section:** Changelog Box iOS SDK v5.1.0のリリース 新機能と機能強化 OAuth2承認ページのURLのカスタマイズを許可 (#811) (1901d29) Events: admin_logs_streaming streamタイプのサポートを追加 (#800) (0a3118e… # Box iOS SDK v5.1.0のリリース ### 新機能と機能強化 - `OAuth2`承認ページのURLのカスタマイズを許可 ([#811](https://github.com/box/box-ios-sdk/issues/811)) ([`1901d29`](https://github.com/box/box-ios-sdk/commit/1901d296a2be4b0f2eef25eda06928aebc81de9a)) - **`Events`:** `admin_logs_streaming stream`タイプのサポートを追加 ([#800](https://github.com/box/box-ios-sdk/issues/800)) ([`0a3118e`](https://github.com/box/box-ios-sdk/commit/0a3118ef95c2eb42b0080d0352784849e85eb422)) - **`RetentionPolicy`:** リテンションの対象となっているファイルおよびファイルバージョンを取得するための新しいAPI ([#807](https://github.com/box/box-ios-sdk/issues/807)) ([`38327f0`](https://github.com/box/box-ios-sdk/commit/38327f09a92dba7827e1866940a643d624757762)) - **`SharedLink`:** `vanity_name`のサポートを追加 ([#799](https://github.com/box/box-ios-sdk/issues/799)) ([`3ea6eb2`](https://github.com/box/box-ios-sdk/commit/3ea6eb2a1c2b713fd0769e93a2dc4ee51da695fd)) ### バグ修正 - **`SignRequest`:** `prefillTag`でエンコード`date_value`を`yyyy-mm-dd`形式に修正 ([#806](https://github.com/box/box-ios-sdk/issues/806)) ([`4f902a4`](https://github.com/box/box-ios-sdk/commit/4f902a47482de55ec69b5522e6cf5affd653b4c8)) **Source:** [https://ja.developer.box.com/changelog/2022-01-17-box-ios-sdk-v510-released](https://ja.developer.box.com/changelog/2022-01-17-box-ios-sdk-v510-released) --- ### Box iOS SDK `v5.2.0`のリリース **Type:** changelog | **Section:** Changelog Box iOS SDK v5.2.0のリリース 新機能と機能強化 disposition_atフィールドをFileオブジェクトに追加 (#814) (3c90df0) クライアント資格情報許可による認証方法のサポートを追加 (#821) (f6d7542) # Box iOS SDK v5.2.0のリリース ### 新機能と機能強化 - `disposition_at`フィールドを`File`オブジェクトに追加 ([#814](https://github.com/box/box-ios-sdk/issues/814)) ([`3c90df0`](https://github.com/box/box-ios-sdk/commit/3c90df038b9f490a9d38af85404fa1d6ddcd5d0d)) - クライアント資格情報許可による認証方法のサポートを追加 ([#821](https://github.com/box/box-ios-sdk/issues/821)) ([`f6d7542`](https://github.com/box/box-ios-sdk/commit/f6d75424e8c0d91517e3ffb8df67f77ad3f2374b)) **Source:** [https://ja.developer.box.com/changelog/2022-03-18-box-ios-sdk-v520-released](https://ja.developer.box.com/changelog/2022-03-18-box-ios-sdk-v520-released) --- ### Box iOS SDK `v5.2.1`のリリース **Type:** changelog | **Section:** Changelog Box iOS SDK v5.2.1のリリース バグ修正 カスタムAPIコール用にBoxResponseからフィールドを公開 (#833) (bae1536) # Box iOS SDK v5.2.1のリリース ### バグ修正 - カスタムAPIコール用に`BoxResponse`からフィールドを公開 ([#833](https://github.com/box/box-ios-sdk/issues/833)) ([`bae1536`](https://github.com/box/box-ios-sdk/commit/bae1536236a22de198281012b0ee43c84b0e3485)) **Source:** [https://ja.developer.box.com/changelog/2022-04-22-box-ios-sdk-v521-released](https://ja.developer.box.com/changelog/2022-04-22-box-ios-sdk-v521-released) --- ### Box iOS SDK `v5.3.0`のリリース **Type:** changelog | **Section:** Changelog Box iOS SDK v5.3.0のリリース 新機能と機能強化 version_numberをFileVersionに追加 (#853) (ac81667) FoldersModuleに非同期APIのサポートを追加 (#851) (58b9dde) ファイルリクエストAPI… # Box iOS SDK v5.3.0のリリース ### 新機能と機能強化 - `version_number`を`FileVersion`に追加 ([#853](https://github.com/box/box-ios-sdk/issues/853)) ([`ac81667`](https://github.com/box/box-ios-sdk/commit/ac81667ea409cbbe3de9be0c316c630ec6fbc2f5)) - `FoldersModule`に非同期APIのサポートを追加 ([#851](https://github.com/box/box-ios-sdk/issues/851)) ([`58b9dde`](https://github.com/box/box-ios-sdk/commit/58b9dde412eddc76915c99b960702f4af95b62a4)) - ファイルリクエストAPIのサポートを追加 ([#867](https://github.com/box/box-ios-sdk/issues/867)) ([`ec7813e`](https://github.com/box/box-ios-sdk/commit/ec7813e31706c08aaaeac75debdba8d7802786cb)) - アバターAPIにアップロードと削除のサポートを追加 ([#863](https://github.com/box/box-ios-sdk/issues/863)) ([`1e967f5`](https://github.com/box/box-ios-sdk/commit/1e967f5a3eaafbeb894cf8289032ad8ce8664266)) - 編集可能な共有リンクのサポートを追加 ([#861](https://github.com/box/box-ios-sdk/issues/861)) ([`bc6ea18`](https://github.com/box/box-ios-sdk/commit/bc6ea18bf2e10bebeb62401a55001139f05c76df)) - `send()`メソッドを`BoxClient`でパブリックに公開 ([#843](https://github.com/box/box-ios-sdk/issues/843)) ([`23caaca`](https://github.com/box/box-ios-sdk/commit/23caaca5b6fe8ec1b23470193bc011a62c66d49f)) ### バグ修正 - カスタムヘッダーからのContent-Typeを考慮 ([#841](https://github.com/box/box-ios-sdk/issues/841)) ([`a7c69a7`](https://github.com/box/box-ios-sdk/commit/a7c69a73c6142d4b82c718d2d311098dd2b70250)) **Source:** [https://ja.developer.box.com/changelog/2022-08-19-box-ios-sdk-v530-released](https://ja.developer.box.com/changelog/2022-08-19-box-ios-sdk-v530-released) --- ### Box iOS SDK `v5.4.0`のリリース **Type:** changelog | **Section:** Changelog Box iOS SDK v5.4.0のリリース 新機能と機能強化 SignRequestSignerにcontent_typeフィールドを追加 (#871) (1ec5b01) 署名リクエストにredirect_urlとdeclined_redirect_urlを追加 (#87… # Box iOS SDK v5.4.0のリリース ### 新機能と機能強化 - SignRequestSignerに`content_type`フィールドを追加 ([#871](https://github.com/box/box-ios-sdk/issues/871)) ([`1ec5b01`](https://github.com/box/box-ios-sdk/commit/1ec5b0149f01cd3a18f5cba39b77e01678655932)) - 署名リクエストに`redirect_url`と`declined_redirect_url`を追加 ([#870](https://github.com/box/box-ios-sdk/issues/870)) ([`f94d988`](https://github.com/box/box-ios-sdk/commit/f94d98862d2fdb2603f4684b963d29d04e0fdb3d)) - `sign` Webhookトリガーのサポートを追加 ([#875](https://github.com/box/box-ios-sdk/issues/875)) ([`994bfaf`](https://github.com/box/box-ios-sdk/commit/994bfaf3ead983f5014808f6c9e5ffe167ab8e42)) - リテンションポリシー割り当てを削除するメソッドを追加 ([#873](https://github.com/box/box-ios-sdk/issues/873)) ([`c5f146c`](https://github.com/box/box-ios-sdk/commit/c5f146c960bb1f940418975078d83fb63ff3bdec)) - 変更可能リテンションポリシーのサポートを追加 ([#872](https://github.com/box/box-ios-sdk/issues/872)) ([`e2b7a17`](https://github.com/box/box-ios-sdk/commit/e2b7a178c6592c9f7d1e7ce691c215680b3f45d0)) **Source:** [https://ja.developer.box.com/changelog/2022-11-08-box-ios-sdk-v540-released](https://ja.developer.box.com/changelog/2022-11-08-box-ios-sdk-v540-released) --- ### Box iOS SDK `v5.4.1`のリリース **Type:** changelog | **Section:** Changelog Box iOS SDK v5.4.1のリリース バグ修正 RetentionPolicyModuleのlistAssignmentsおよびassignメソッドを修正 (#886) (b668888) # Box iOS SDK v5.4.1のリリース ### バグ修正 - `RetentionPolicyModule`の`listAssignments`および`assign`メソッドを修正 ([#886](https://github.com/box/box-ios-sdk/issues/886)) ([`b668888`](https://github.com/box/box-ios-sdk/commit/b668888f35136dd1239526b70cc31a10bdd04744)) **Source:** [https://ja.developer.box.com/changelog/2023-02-24-box-ios-sdk-v541-released](https://ja.developer.box.com/changelog/2023-02-24-box-ios-sdk-v541-released) --- ### Box iOS SDK `v5.4.2`のリリース **Type:** changelog | **Section:** Changelog Box iOS SDK v5.4.2のリリース バグ修正 空の文字列nextMarkerはページの末尾として扱うよう変更 (#893) (49c17de) # Box iOS SDK v5.4.2のリリース ### バグ修正 - 空の文字列`nextMarker`はページの末尾として扱うよう変更 ([#893](https://github.com/box/box-ios-sdk/issues/893)) ([`49c17de`](https://github.com/box/box-ios-sdk/commit/49c17de588fcffcd2d151ce9047ebc09965f80ce)) **Source:** [https://ja.developer.box.com/changelog/2023-04-19-box-ios-sdk-v542-released](https://ja.developer.box.com/changelog/2023-04-19-box-ios-sdk-v542-released) --- ### Box iOS SDK `v5.5.0`のリリース **Type:** changelog | **Section:** Changelog Box iOS SDK v5.5.0のリリース 新機能と機能強化 SignRequestSignerInputContentTypeおよびSignRequestStatusで欠落している値をテストとともに追加 (#907) (56a8250) バグ修正 Apple… # Box iOS SDK v5.5.0のリリース ### 新機能と機能強化 - `SignRequestSignerInputContentType`および`SignRequestStatus`で欠落している値をテストとともに追加 ([#907](https://github.com/box/box-ios-sdk/issues/907)) ([`56a8250`](https://github.com/box/box-ios-sdk/commit/56a82500c0abe648825d8300979601a25f792c84)) ### バグ修正 - Appleシリコン上のiPhone Simulatorを識別 ([#902](https://github.com/box/box-ios-sdk/issues/902)) ([`7731a7f`](https://github.com/box/box-ios-sdk/commit/7731a7f434add74e163a76511fe1e2a3f26517f7)) - [#900](https://github.com/box/box-ios-sdk/issues/900)コードをmacOSに対応させる ([#900](https://github.com/box/box-ios-sdk/issues/900)) ([`3b0016e`](https://github.com/box/box-ios-sdk/commit/3b0016e44e674db0ea429273c03e5a29177372bf)) - 非推奨となった文字列スキャナAPIの使用を削除 ([#901](https://github.com/box/box-ios-sdk/issues/901)) ([`af5f0e5`](https://github.com/box/box-ios-sdk/commit/af5f0e52d184fbd27f56d972fb93b3e543547773)) **Source:** [https://ja.developer.box.com/changelog/2023-08-08-box-ios-sdk-v550-released](https://ja.developer.box.com/changelog/2023-08-08-box-ios-sdk-v550-released) --- ### Box iOS SDK `v5.6.0`のリリース **Type:** changelog | **Section:** Changelog Box iOS SDK v5.6.0のリリース 新機能と機能強化 Privacy Manifestファイルを追加 (#924) (cbef168) visionOSのサポートを追加 (#916) (a05b243) SignRequest… # Box iOS SDK v5.6.0のリリース ### 新機能と機能強化 - Privacy Manifestファイルを追加 ([#924](https://github.com/box/box-ios-sdk/issues/924)) ([`cbef168`](https://github.com/box/box-ios-sdk/commit/cbef168bb872941899be26116c647ac29f5dd44b)) - `visionOS`のサポートを追加 ([#916](https://github.com/box/box-ios-sdk/issues/916)) ([`a05b243`](https://github.com/box/box-ios-sdk/commit/a05b2433f1b2d0c1ec72f946e0706d03a4548703)) - `SignRequest`で追加のフィールドのサポートを追加 ([#919](https://github.com/box/box-ios-sdk/issues/919)) ([`36f464c`](https://github.com/box/box-ios-sdk/commit/36f464c23a161f5d0fcc6858c3615d884ce8ee07)) - `TokenInfo`のフィールドをpublicに変更 ([#920](https://github.com/box/box-ios-sdk/issues/920)) ([`eb26f47`](https://github.com/box/box-ios-sdk/commit/eb26f47bbde6749f44f149e95b3610e41c16d2f2)) **Source:** [https://ja.developer.box.com/changelog/2024-04-05-box-ios-sdk-v560-released](https://ja.developer.box.com/changelog/2024-04-05-box-ios-sdk-v560-released) --- ### Box Java SDK `v2.48.0`のリリース **Type:** changelog | **Section:** Changelog Box Java SDK v2.48.0のリリース v2.48.0 フィールドオプションにより名前ごとにグループを取得する機能を追加 (#789) 共有リンクのダウンスコープを追加 (#785) メタデータ値の浮動小数点の使用を非推奨にして、基になる値 (double… # Box Java SDK v2.48.0のリリース `v2.48.0` 1. フィールドオプションにより名前ごとにグループを取得する機能を追加 ([#789](https://github.com/box/box-java-sdk/issues/789)) 2. 共有リンクのダウンスコープを追加 ([#785](https://github.com/box/box-java-sdk/issues/785)) 3. メタデータ値の浮動小数点の使用を非推奨にして、基になる値 (double) を優先 ([#811](https://github.com/box/box-java-sdk/issues/811)) 4. グループコラボレーション用に反復子のサポートを追加 ([#813](https://github.com/box/box-java-sdk/issues/813)) 5. ファイルの新しいバージョンをアップロードする際にファイル名を設定する機能を追加 ([#810](https://github.com/box/box-java-sdk/issues/810)) 6. ファイルとフォルダの分類フィールドのサポートを追加 ([#809](https://github.com/box/box-java-sdk/issues/809)) 7. 追跡コードの設定のサポートを追加 ([#766](https://github.com/box/box-java-sdk/issues/766)) 8. ファイルとフォルダの`getIsExternallyOwned()`に関する問題を修正 ([#808](https://github.com/box/box-java-sdk/issues/808)) **Source:** [https://ja.developer.box.com/changelog/2020-06-24-box-java-sdk-v2480-released](https://ja.developer.box.com/changelog/2020-06-24-box-java-sdk-v2480-released) --- ### Box Java SDK `v2.49.0`のリリース **Type:** changelog | **Section:** Changelog Box Java SDK v2.49.0のリリース メタデータクエリのfieldsパラメータを追加 (#826) 圧縮機能を追加 (#825) 共有リンクの共有解除日を設定してバグを修正 (#819) # Box Java SDK v2.49.0のリリース 1. メタデータクエリの`fields`パラメータを追加 ([#826](https://github.com/box/box-java-sdk/issues/826)) 2. 圧縮機能を追加 ([#825](https://github.com/box/box-java-sdk/issues/825)) 3. 共有リンクの共有解除日を設定してバグを修正 ([#819](https://github.com/box/box-java-sdk/issues/819)) **Source:** [https://ja.developer.box.com/changelog/2020-07-17-box-java-sdk-v2490-released](https://ja.developer.box.com/changelog/2020-07-17-box-java-sdk-v2490-released) --- ### Box Java SDK `v2.50.0`のリリース **Type:** changelog | **Section:** Changelog Box Java SDK v2.50.0のリリース v2.50.0 リクエスト作成エラー時の再試行回数を追加 (#828) # Box Java SDK v2.50.0のリリース `v2.50.0` 1. リクエスト作成エラー時の再試行回数を追加 ([#828](https://github.com/box/box-java-sdk/issues/828)) **Source:** [https://ja.developer.box.com/changelog/2020-07-22-box-java-sdk-v2500-released](https://ja.developer.box.com/changelog/2020-07-22-box-java-sdk-v2500-released) --- ### Box Java SDK `v2.50.1`のリリース **Type:** changelog | **Section:** Changelog Box Java SDK v2.50.1のリリース Box内のフォルダのトークンをダウンスコープする際に発生するバグを修正 # Box Java SDK v2.50.1のリリース Box内のフォルダのトークンをダウンスコープする際に発生するバグを修正 **Source:** [https://ja.developer.box.com/changelog/2020-08-20-box-java-sdk-v2501-released](https://ja.developer.box.com/changelog/2020-08-20-box-java-sdk-v2501-released) --- ### Box Java SDK `v2.51.0`のリリース **Type:** changelog | **Section:** Changelog Box Java SDK v2.51.0のリリース 新機能と機能強化: メタデータテンプレートのcopyInstanceOnItemCopyフィールドのサポートを追加 (#850) BoxCollaborator.Infoでのより多くのフィールドのサポートを追加 (#84… # Box Java SDK v2.51.0のリリース **新機能と機能強化:** - メタデータテンプレートの`copyInstanceOnItemCopy`フィールドのサポートを追加 ([#850](https://github.com/box/box-java-sdk/pull/850)) - `BoxCollaborator.Info`でのより多くのフィールドのサポートを追加 ([#843](https://github.com/box/box-java-sdk/pull/843)) **バグ修正:** - ドキュメントされたパラメータを使用するための`getAllGroupsByName()`のアップデート ([#851](https://github.com/box/box-java-sdk/pull/851)) **Source:** [https://ja.developer.box.com/changelog/2020-10-29-box-java-sdk-v2510-released](https://ja.developer.box.com/changelog/2020-10-29-box-java-sdk-v2510-released) --- ### Box Java SDK `v2.51.1`のリリース **Type:** changelog | **Section:** Changelog Box Java SDK v2.51.1のリリース バグ修正: Enterprise間でのコラボレータによるファイルに対するupdateMetadataの呼び出しの修正 # Box Java SDK v2.51.1のリリース **バグ修正:** - Enterprise間でのコラボレータによるファイルに対する`updateMetadata`の呼び出しの修正 **Source:** [https://ja.developer.box.com/changelog/2020-11-13-box-java-sdk-v2511-released](https://ja.developer.box.com/changelog/2020-11-13-box-java-sdk-v2511-released) --- ### Box Java SDK `v2.52.0`のリリース **Type:** changelog | **Section:** Changelog Box Java SDK v2.52.0のリリース 新機能と機能強化: フォルダロック機能を追加 (#856) 共有リンク項目を取得するための検索パラメータのサポートを追加 (#855) バグ修正: 追跡コードを更新する際のバグを修正 (#857) # Box Java SDK v2.52.0のリリース **新機能と機能強化:** - フォルダロック機能を追加 ([#856](https://github.com/box/box-java-sdk/pull/856)) - 共有リンク項目を取得するための検索パラメータのサポートを追加 ([#855](https://github.com/box/box-java-sdk/pull/855)) **バグ修正:** - 追跡コードを更新する際のバグを修正 ([#857](https://github.com/box/box-java-sdk/pull/857)) **Source:** [https://ja.developer.box.com/changelog/2020-11-24-box-java-sdk-v2520-released](https://ja.developer.box.com/changelog/2020-11-24-box-java-sdk-v2520-released) --- ### Box Java SDK `v2.53.0`のリリース **Type:** changelog | **Section:** Changelog Box Java SDK v2.53.0のリリース 新機能と機能強化: BoxFolder.getChildrenへのオフセットおよび制限パラメータの追加 (#861) # Box Java SDK v2.53.0のリリース **新機能と機能強化:** - `BoxFolder.getChildren`へのオフセットおよび制限パラメータの追加 ([#861](https://github.com/box/box-java-sdk/pull/861)) **Source:** [https://ja.developer.box.com/changelog/2021-01-09-box-java-sdk-v2530-released](https://ja.developer.box.com/changelog/2021-01-09-box-java-sdk-v2530-released) --- ### Box Java SDK `v2.54.0`のリリース **Type:** changelog | **Section:** Changelog Box Java SDK v2.54.0のリリース 新機能と機能強化: ファイルリクエストのサポートを追加 (#869) バグ修正: BoxWeblinkの逆シリアル化を修正 (#881) # Box Java SDK v2.54.0のリリース **新機能と機能強化:** - ファイルリクエストのサポートを追加 ([#869](https://github.com/box/box-java-sdk/pull/869)) **バグ修正:** - `BoxWeblink`の逆シリアル化を修正 ([#881](https://github.com/box/box-java-sdk/pull/881)) **Source:** [https://ja.developer.box.com/changelog/2021-04-01-box-java-sdk-v2540-released](https://ja.developer.box.com/changelog/2021-04-01-box-java-sdk-v2540-released) --- ### Box Java SDK `v2.55.0`のリリース **Type:** changelog | **Section:** Changelog Box Java SDK v2.55.0のリリース 注: 以下の「重大な変更」による悪影響はないため、Boxでは、このリリースについてメジャーバージョンを上げないことを決定しました。この変更によるお客様への影響はありません。 重大な変更: API… # Box Java SDK v2.55.0のリリース 注: 以下の「重大な変更」による悪影響はないため、Boxでは、このリリースについてメジャーバージョンを上げないことを決定しました。この変更によるお客様への影響はありません。 **重大な変更:** - APIレスポンスと一致するようメタデータ実行クエリを更新 ([#890](https://github.com/box/box-java-sdk/pull/890)) - 注: この変更により、メソッドは、サポートが終了されることなく、削除されます。このメソッドは、基になるサービスでサポートされなくなったため、正しく使用できなくなりました。 **新機能と機能強化:** - 不適切な用語を削除または廃止 ([[#889](https://github.com/box/box-java-sdk/issues/889)])([https://github.com/box/box-java-sdk/pull/889](https://github.com/box/box-java-sdk/pull/889) ) - ユーザーの`is_external_collab_restricted`パラメータのサポートを追加 ([#896](https://github.com/box/box-java-sdk/pull/896)) - `GroupMembership`の設定可能な権限のサポートを追加 ([#897](https://github.com/box/box-java-sdk/pull/897)) - `SHIELD_JUSTIFICATION_APPROVAL`イベントタイプを追加 ([#898](https://github.com/box/box-java-sdk/pull/898)) - 割り当てのリテンションの対象となるファイルおよびファイルバージョンを取得する機能を追加 ([#899](https://github.com/box/box-java-sdk/pull/899)) - `TASK_UPDATE`、`FILE_VERSION_RESTORE`、`ADVANCED_FOLDER_SETTINGS_UPDATE`イベントタイプを追加 ([#902](https://github.com/box/box-java-sdk/pull/902)) - Box Sign APIのサポートを追加 ([#904](https://github.com/box/box-java-sdk/pull/904)) **バグ修正:** - `BoxLegalHoldPolicy`のセッターを追加 ([#885](https://github.com/box/box-java-sdk/pull/885)) - `BoxTaskAssignment`のセッターを追加 ([#886](https://github.com/box/box-java-sdk/pull/886)) - グループメンバーシップおよびウェブリンクのセッターを追加 ([#887](https://github.com/box/box-java-sdk/pull/887)) - Webhookのセッターを追加 ([#888](https://github.com/box/box-java-sdk/pull/888)) - `BoxFile.getThumbnail`のサポートを終了して`BoxFile.getRepresentationContent`を推奨 ([#891](https://github.com/box/box-java-sdk/pull/891)) **Source:** [https://ja.developer.box.com/changelog/2021-07-26-box-java-sdk-v2550-released](https://ja.developer.box.com/changelog/2021-07-26-box-java-sdk-v2550-released) --- ### Box Java SDK `v2.55.1`のリリース **Type:** changelog | **Section:** Changelog Box Java SDK v2.55.1のリリース バグ修正: #890で削除されたメタデータクエリ実行の方式を復元し、非推奨としてマーク (#905) # Box Java SDK v2.55.1のリリース **バグ修正:** - [#890](https://github.com/box/box-java-sdk/pull/890)で削除されたメタデータクエリ実行の方式を復元し、非推奨としてマーク ([#905](https://github.com/box/box-java-sdk/pull/905)) **Source:** [https://ja.developer.box.com/changelog/2021-07-30-box-java-sdk-v2551-released](https://ja.developer.box.com/changelog/2021-07-30-box-java-sdk-v2551-released) --- ### Box Java SDK `v2.56.0`のリリース **Type:** changelog | **Section:** Changelog Box Java SDK v2.56.0のリリース 新機能と機能強化: submaster GroupMembershipRoleをcoadminに置き換え、MASTER_INVITE_ACCEPTおよびMASTER_INVITE_REJECTをADMIN_INVITE… # Box Java SDK v2.56.0のリリース **新機能と機能強化:** - `submaster` `GroupMembershipRole`を`coadmin`に置き換え、`MASTER_INVITE_ACCEPT`および`MASTER_INVITE_REJECT`を`ADMIN_INVITE_ACCEPT`および`ADMIN_INVITE_REJECT`に置き換え ([#907](https://github.com/box/box-java-sdk/pull/907)) - ユーザーの作成APIコールに`tracking_codes`を追加 ([#910](https://github.com/box/box-java-sdk/pull/910)) **バグ修正:** - `BoxFileRequest.Info`オブジェクトの`url`を修正 ([#906](https://github.com/box/box-java-sdk/pull/906)) - アクセストークンの更新時に発生するスレッドロックの問題の修正を試行 ([#912](https://github.com/box/box-java-sdk/pull/912)) **Source:** [https://ja.developer.box.com/changelog/2021-08-31-box-java-sdk-v2560-released](https://ja.developer.box.com/changelog/2021-08-31-box-java-sdk-v2560-released) --- ### Box Java SDK `v2.57.0`のリリース **Type:** changelog | **Section:** Changelog Box Java SDK v2.57.0のリリース 新機能と機能強化: BoxFolder.getChildrenでのマーカーベースのページ割りのサポートを追加 (#927) minimal-jsonをバージョン0.9.5にアップグレード jose4jをバージョン0.7.… # Box Java SDK v2.57.0のリリース **新機能と機能強化:** - `BoxFolder.getChildren`でのマーカーベースのページ割りのサポートを追加 ([#927](https://github.com/box/box-java-sdk/pull/927)) - `minimal-json`をバージョン0.9.5にアップグレード - `jose4j`をバージョン0.7.9にアップグレード - バージョン4.0.1にGradleラッパーを追加 ([#928](https://github.com/box/box-java-sdk/pull/928)) **バグ修正:** - 無限再帰の修正 ([#924](https://github.com/box/box-java-sdk/pull/924)) - `BoxFile`および`BoxFolder`の`BoxSharedLink`にバニティURLを設定できないバグの修正 ([#925](https://github.com/box/box-java-sdk/issues/925)) **Source:** [https://ja.developer.box.com/changelog/2021-10-18-box-java-sdk-v2570-released](https://ja.developer.box.com/changelog/2021-10-18-box-java-sdk-v2570-released) --- ### Box Java SDK `v2.58.0`のリリース **Type:** changelog | **Section:** Changelog Box Java SDK v2.58.0のリリース 新機能と機能強化: 新しいGET /events stream_typeであるadmin_logs_streamingのSDKサポート (#938) 管理対象ユーザーまたはApp User… # Box Java SDK v2.58.0のリリース **新機能と機能強化:** - 新しいGET /events `stream_type`である`admin_logs_streaming`のSDKサポート ([#938](https://github.com/box/box-java-sdk/pull/938)) - 管理対象ユーザーまたはApp Userにこの接続を使用できることを示すために`BoxDeveloperEditionAPIConnection#getUserConnection`を追加 ([#940](https://github.com/box/box-java-sdk/pull/940)) **バグ修正:** - 非推奨の列挙型が使用されている問題を修正 ([#931](https://github.com/box/box-java-sdk/issues/931)) **Source:** [https://ja.developer.box.com/changelog/2021-11-23-box-java-sdk-v2580-released](https://ja.developer.box.com/changelog/2021-11-23-box-java-sdk-v2580-released) --- ### Box Java SDK `v3.0.0`のリリース **Type:** changelog | **Section:** Changelog Box Java SDK v3.0.0のリリース ⚠ 重大な変更 BoxFileVersionクラスを変更してfileVersionフィールドを削除 (#978) 非推奨となったAPI BoxCollaborationWhitelist… # Box Java SDK v3.0.0のリリース ### ⚠ 重大な変更 - `BoxFileVersion`クラスを変更して`fileVersion`フィールドを削除 ([#978](https://github.com/box/box-java-sdk/issues/978)) - 非推奨となったAPI `BoxCollaborationWhitelist`を削除して`BoxCollaborationAllowlist`に置き換え、`BoxCollaborationWhitelistExemptTarget`を削除して`BoxCollaborationAllowlistExemptTarget`に置き換え ([#969](https://github.com/box/box-java-sdk/issues/969)) - Java 7のサポートを終了 ([#962](https://github.com/box/box-java-sdk/issues/962)) - `bouncycastle`ライブラリを1.57にダウングレード ([#942](https://github.com/box/box-java-sdk/issues/942)) ### 新機能と機能強化 - `BoxEvent.EventType`にマップされていない場合でも、イベントの名前を含む`typeName`を`BoxEvent`に追加 ([#979](https://github.com/box/box-java-sdk/issues/979)) ([`b30f61f`](https://github.com/box/box-java-sdk/commit/b30f61f8cc9c02a1fc4cd5eb35469749e1a16558))、[#968](https://github.com/box/box-java-sdk/issues/968)をクローズ - 省略可能な`description`パラメータを`retention_policies`エンドポイント、`start_date_field`パラメータを`retention_policy_assignments endpoint`エンドポイントに新しく追加 ([#967](https://github.com/box/box-java-sdk/issues/967)) ([`0aa4ff4`](https://github.com/box/box-java-sdk/commit/0aa4ff48a1e035efc9ac6aaa42f18f4c92955b7b)) - ユーザーが抽出したい情報を指定できるように`BoxFile#getVersions(String... fields)`を追加。[#946](https://github.com/box/box-java-sdk/issues/946)を修正。([#947](https://github.com/box/box-java-sdk/issues/947)) ([`a2eb638`](https://github.com/box/box-java-sdk/commit/a2eb63896606a6c00ccee6bd9745f4c51f8d89a2)) - `BoxAPI`ドキュメントから`eventTypes`を削除。[#974](https://github.com/box/box-java-sdk/issues/974)を修正 ([#975](https://github.com/box/box-java-sdk/issues/975)) [`2c69360`](https://github.com/box/box-java-sdk/commit/2c69360e80b1bdd6213933cf2f4da195d52c92d4) - 非推奨となったAPI `BoxCollaborationWhitelist`を削除して`BoxCollaborationAllowlist`に置き換え、`BoxCollaborationWhitelistExemptTarget`を削除して`BoxCollaborationAllowlistExemptTarget`に置き換え ([#969](https://github.com/box/box-java-sdk/issues/969)) ([`2fd4d6f`](https://github.com/box/box-java-sdk/commit/2fd4d6f884410c8884c4c038687bfc8f32837b55)) ### バグ修正 - `BoxFileVersion`クラスを変更して`fileVersion`フィールドを削除 ([#978](https://github.com/box/box-java-sdk/issues/978)) ([`8c39451`](https://github.com/box/box-java-sdk/commit/8c3945167581400043a070c2f6906ef05d3d7b85)) - SDKロガーの名前を`"com.box.sdk"`に変更し、[#638](https://github.com/box/box-java-sdk/issues/638)を修正 ([#950](https://github.com/box/box-java-sdk/issues/950)) ([`443c230`](https://github.com/box/box-java-sdk/commit/443c23085e55bbcaa1524c5b9e1bf852a1e2a1ce)) - 日付値を使用して`BoxSignRequestPrefillTag`を作成したときの日付解析エラー。([#970](https://github.com/box/box-java-sdk/issues/970)) ([`cc2c8da`](https://github.com/box/box-java-sdk/commit/cc2c8da9ea7d066ae2c247c2de5ac8b8bbba9b99)) - `EventLog`の制限パラメータの送信を修正 ([#977](https://github.com/box/box-java-sdk/issues/977)) ([`96bdccc`](https://github.com/box/box-java-sdk/commit/96bdccc9ca40ed43a6028a2b0d055d9d9a8de525)) - `BoxFile`または`BoxFolder`で空のメタデータが使用されたときの`NullPointerException`を修正 ([#918](https://github.com/box/box-java-sdk/issues/918)) ([#945](https://github.com/box/box-java-sdk/issues/945)) ([`68bc3c5`](https://github.com/box/box-java-sdk/commit/68bc3c578d760b7239f6d704fed9bb5a834bf52a)) - 署名リクエストを逆シリアル化できない問題を修正 ([#951](https://github.com/box/box-java-sdk/issues/951))。([#952](https://github.com/box/box-java-sdk/issues/952)) ([`070bdc5`](https://github.com/box/box-java-sdk/commit/070bdc56074a1533c41f9085943d09502c79a7f4)) ### 依存関係のアップグレード - Java 7のサポートを終了 ([#962](https://github.com/box/box-java-sdk/issues/962)) ([`953ad78`](https://github.com/box/box-java-sdk/commit/953ad78ac84833082439d0def1dcc63dc11ac04a)) - `bouncycastle`ライブラリを1.57にダウングレード ([#942](https://github.com/box/box-java-sdk/issues/942)) ([`26aaed5`](https://github.com/box/box-java-sdk/commit/26aaed51fd914eaf2061da735f11830524e4cfe4)) **Source:** [https://ja.developer.box.com/changelog/2022-01-17-box-java-sdk-v300-released](https://ja.developer.box.com/changelog/2022-01-17-box-java-sdk-v300-released) --- ### Box Java SDK `v3.1.0`のリリース **Type:** changelog | **Section:** Changelog Box Java SDK v3.1.0のリリース 新機能と機能強化 クライアント資格情報許可による認証方法のサポートを追加 (#1002) (9cfcaff) ファイルの廃棄日を延長するAPI (#1001) (f3f6b60) メタデータクエリ実行時のindexName… # Box Java SDK v3.1.0のリリース ### 新機能と機能強化 - クライアント資格情報許可による認証方法のサポートを追加 ([#1002](https://github.com/box/box-java-sdk/issues/1002)) ([`9cfcaff`](https://github.com/box/box-java-sdk/commit/9cfcaff243dbf0541409f91f9f863a207345dc47)) - ファイルの廃棄日を延長するAPI ([#1001](https://github.com/box/box-java-sdk/issues/1001)) ([`f3f6b60`](https://github.com/box/box-java-sdk/commit/f3f6b6043eec362c5a8ad9a01d6588538ca34e71)) - メタデータクエリ実行時の`indexName`のサポート終了 ([#1000](https://github.com/box/box-java-sdk/issues/1000)) ([`c20dbbf`](https://github.com/box/box-java-sdk/commit/c20dbbf6a927e31cfdd7ffa71069c0897f7a0536)) ### 依存関係のアップグレード - Gradleを7.3.3にアップグレード ([#985](https://github.com/box/box-java-sdk/issues/985)) [`e4acbb1`](https://github.com/box/box-java-sdk/commit/e4acbb1f0c10ccdeeee139e2566b344052680010) **Source:** [https://ja.developer.box.com/changelog/2022-02-18-box-java-sdk-v310-released](https://ja.developer.box.com/changelog/2022-02-18-box-java-sdk-v310-released) --- ### Box Java SDK `v3.1.1`のリリース **Type:** changelog | **Section:** Changelog Box Java SDK v3.1.1のリリース バグ修正 エラーフィールドにエラーコードが含まれている場合にjwt認証を再試行 (#1020) (8c9d11d)、#1019をクローズ # Box Java SDK v3.1.1のリリース ### バグ修正 - エラーフィールドにエラーコードが含まれている場合に`jwt`認証を再試行 ([#1020](https://github.com/box/box-java-sdk/issues/1020)) ([`8c9d11d`](https://github.com/box/box-java-sdk/commit/8c9d11d1b3556552751c9f4ac99a0f7180af97f3))、[#1019](https://github.com/box/box-java-sdk/issues/1019)をクローズ **Source:** [https://ja.developer.box.com/changelog/2022-02-28-box-java-sdk-v311-released](https://ja.developer.box.com/changelog/2022-02-28-box-java-sdk-v311-released) --- ### Box Java SDK `v3.1.2`のリリース **Type:** changelog | **Section:** Changelog Box Java SDK v3.1.2のリリース バグ修正 CCG認証でのAs-Userヘッダーの使用を許可 (#1031) (b0c2389) Retry-Afterヘッダーが存在する場合の再試行ロジックを修正 (#1033) (05224c4) # Box Java SDK v3.1.2のリリース ### バグ修正 - CCG認証での`As-User`ヘッダーの使用を許可 ([#1031](https://github.com/box/box-java-sdk/issues/1031)) ([`b0c2389`](https://github.com/box/box-java-sdk/commit/b0c238913cc1dbcecfd546a5eae68277c3c76d42)) - `Retry-After`ヘッダーが存在する場合の再試行ロジックを修正 ([#1033](https://github.com/box/box-java-sdk/issues/1033)) ([`05224c4`](https://github.com/box/box-java-sdk/commit/05224c433d2a101a01959644674153df9542b711)) **Source:** [https://ja.developer.box.com/changelog/2022-03-22-box-java-sdk-v312-released](https://ja.developer.box.com/changelog/2022-03-22-box-java-sdk-v312-released) --- ### Box Java SDK `v3.2.0`のリリース **Type:** changelog | **Section:** Changelog Box Java SDK v3.2.0のリリース 新機能と機能強化 ベースURLの設定を刷新 (#1042) (129baf7) アバターV2 APIをサポート (#1044) (18651d7) # Box Java SDK v3.2.0のリリース ### 新機能と機能強化 - ベースURLの設定を刷新 ([#1042](https://github.com/box/box-java-sdk/issues/1042)) ([`129baf7`](https://github.com/box/box-java-sdk/commit/129baf704ced127788bb0f62ef9f4fb6a50fdc63)) - アバターV2 APIをサポート ([#1044](https://github.com/box/box-java-sdk/issues/1044)) ([`18651d7`](https://github.com/box/box-java-sdk/commit/18651d7a5b419796e3733c7582ae471d7af7ed5c)) **Source:** [https://ja.developer.box.com/changelog/2022-05-24-box-java-sdk-v320-released](https://ja.developer.box.com/changelog/2022-05-24-box-java-sdk-v320-released) --- ### Box Java SDK `v3.2.1`のリリース **Type:** changelog | **Section:** Changelog Box Java SDK v3.2.1のリリース バグ修正 OAuthで認証するための適切なURLを取得するよう修正 (#1059) (42876b4)、#1057をクローズ # Box Java SDK v3.2.1のリリース ### バグ修正 - OAuthで認証するための適切なURLを取得するよう修正 ([#1059](https://github.com/box/box-java-sdk/issues/1059)) ([`42876b4`](https://github.com/box/box-java-sdk/commit/42876b45ccdb7fa6f357186cecaba051abf1c269))、[#1057](https://github.com/box/box-java-sdk/issues/1057)をクローズ **Source:** [https://ja.developer.box.com/changelog/2022-06-11-box-java-sdk-v321-released](https://ja.developer.box.com/changelog/2022-06-11-box-java-sdk-v321-released) --- ### Box Java SDK `v3.3.0`のリリース **Type:** changelog | **Section:** Changelog Box Java SDK v3.3.0のリリース 新機能と機能強化 編集可能な共有リンクのサポートを追加 (#1064) (9b7d60c) バグ修正 閉じたストリームの例外をcanUploadメソッドで修正 (#1067) (543f91c) # Box Java SDK v3.3.0のリリース ### 新機能と機能強化 - 編集可能な共有リンクのサポートを追加 ([#1064](https://github.com/box/box-java-sdk/issues/1064)) ([`9b7d60c`](https://github.com/box/box-java-sdk/commit/9b7d60c41fbd481465bf3f2a5877746f10849712)) ### バグ修正 - 閉じたストリームの例外を`canUpload`メソッドで修正 ([#1067](https://github.com/box/box-java-sdk/issues/1067)) ([`543f91c`](https://github.com/box/box-java-sdk/commit/543f91c46dfcc9de7e61ce11cd93d472916533ac)) **Source:** [https://ja.developer.box.com/changelog/2022-07-04-box-java-sdk-v330-released](https://ja.developer.box.com/changelog/2022-07-04-box-java-sdk-v330-released) --- ### Box Java SDK `v3.4.0`のリリース **Type:** changelog | **Section:** Changelog Box Java SDK v3.4.0のリリース 新機能と機能強化 新しいBoxTrash#items APIでごみ箱内の項目を取得する際のページ割り機能を追加 (#1072) (9cd411d) バグ修正 本文の書き込みをバッファリングし、SDKログを修正 (#107… # Box Java SDK v3.4.0のリリース ### 新機能と機能強化 - 新しい`BoxTrash#items` APIでごみ箱内の項目を取得する際のページ割り機能を追加 ([#1072](https://github.com/box/box-java-sdk/issues/1072)) ([`9cd411d`](https://github.com/box/box-java-sdk/commit/9cd411d20af1bc76ae815905396d72008af62539)) ### バグ修正 - 本文の書き込みをバッファリングし、SDKログを修正 ([#1079](https://github.com/box/box-java-sdk/issues/1079)) ([`bc35ef3`](https://github.com/box/box-java-sdk/commit/bc35ef3279e68a3d794de454f506ba41d14c3b16)) **Source:** [https://ja.developer.box.com/changelog/2022-08-11-box-java-sdk-v340-released](https://ja.developer.box.com/changelog/2022-08-11-box-java-sdk-v340-released) --- ### Box Java SDK `v3.5.0`のリリース **Type:** changelog | **Section:** Changelog Box Java SDK v3.5.0のリリース 新機能と機能強化 署名リクエストとレスポンスにcontent-typeを追加 (#1087) (49411aa) notification_emailをBoxUserに追加 (#1088) (547722… # Box Java SDK v3.5.0のリリース ### 新機能と機能強化 - 署名リクエストとレスポンスに`content-type`を追加 ([#1087](https://github.com/box/box-java-sdk/issues/1087)) ([`49411aa`](https://github.com/box/box-java-sdk/commit/49411aaeea6d3ff8de10e3fbc3c60bba1bc54748)) - `notification_email`を`BoxUser`に追加 ([#1088](https://github.com/box/box-java-sdk/issues/1088)) ([`5477223`](https://github.com/box/box-java-sdk/commit/547722347a920ba11e5fff7a8df5201720af815a)) - 署名リクエストとレスポンスに`redirect_url`と`declined_redirect_url`を追加 ([#1089](https://github.com/box/box-java-sdk/issues/1089)) ([`3921fe1`](https://github.com/box/box-java-sdk/commit/3921fe1a4a6249146a8dd2f22e15801846bc073b)) ### バグ修正 - 空の本文が原因の署名リクエストのキャンセルの失敗を修正 ([#1085](https://github.com/box/box-java-sdk/issues/1085)) ([`32b8e79`](https://github.com/box/box-java-sdk/commit/32b8e79ebc8995ab933c32d28c3e2f17d9627a70)) **Source:** [https://ja.developer.box.com/changelog/2022-08-26-box-java-sdk-v350-released](https://ja.developer.box.com/changelog/2022-08-26-box-java-sdk-v350-released) --- ### Box Java SDK `v3.6.0`のリリース **Type:** changelog | **Section:** Changelog Box Java SDK v3.6.0のリリース 新機能と機能強化 変更可能リテンションポリシーのサポートと、リテンションポリシー割り当ての削除機能を追加 (#1093) (30e2fcb… # Box Java SDK v3.6.0のリリース ### 新機能と機能強化 - 変更可能リテンションポリシーのサポートと、リテンションポリシー割り当ての削除機能を追加 ([#1093](https://github.com/box/box-java-sdk/issues/1093)) ([`30e2fcb`](https://github.com/box/box-java-sdk/commit/30e2fcb74c12867fd3859c3490539557b47ab006)) ### バグ修正 - ユーザーの作成時に指定されていない省略可能なフィールドを送信しないように修正 ([#1095](https://github.com/box/box-java-sdk/issues/1095)) ([`b7d894d`](https://github.com/box/box-java-sdk/commit/b7d894d3f134137f3a5925f09accfd4334837f81)) **Source:** [https://ja.developer.box.com/changelog/2022-09-07-box-java-sdk-v360-released](https://ja.developer.box.com/changelog/2022-09-07-box-java-sdk-v360-released) --- ### Box Java SDK `v3.7.0`のリリース **Type:** changelog | **Section:** Changelog Box Java SDK v3.7.0のリリース 新機能と機能強化 ファイルとフォルダにis_accessible_via_shared_linkフィールドを追加 (#1103) (45e9906) バグ修正 BoxCollaboration.getItem… # Box Java SDK v3.7.0のリリース ### 新機能と機能強化 - ファイルとフォルダに`is_accessible_via_shared_link`フィールドを追加 ([#1103](https://github.com/box/box-java-sdk/issues/1103)) ([`45e9906`](https://github.com/box/box-java-sdk/commit/45e9906efca6a7f2d4d738914dc804de12d3646e)) ### バグ修正 - `BoxCollaboration.getItem()`が`BoxFolder.Info`ではなく`BoxItem.Info`を返すように修正 ([#1102](https://github.com/box/box-java-sdk/issues/1102)) ([`135850d`](https://github.com/box/box-java-sdk/commit/135850d97164ee5f6d74708d74c531f7fa8bee26))、[#1101](https://github.com/box/box-java-sdk/issues/1101) [#1100](https://github.com/box/box-java-sdk/issues/1100)をクローズ。以前、`BoxCollaboration.getItem()`は`BoxFolder.Info`を返していました。ただし、ファイルにコラボレーションが追加された場合は引き続き`BoxFolder.Info`が返され、その結果、任意のAPIコールを実行する際に`BoxAPIException`がスローされます。コラボレーション項目を取得する場合は`BoxItem.Info`として格納するか、その種類を確認して`BoxFile.Info`または`BoxFolder.Info`として格納することをお勧めします。 - 不足していたコンストラクタを`BoxNotificationEmail`クラスに追加 ([#1098](https://github.com/box/box-java-sdk/issues/1098)) ([`2534f34`](https://github.com/box/box-java-sdk/commit/2534f34133f9554abd1e80fc1555659a2c52b23f)) **Source:** [https://ja.developer.box.com/changelog/2022-09-21-box-java-sdk-v370-released](https://ja.developer.box.com/changelog/2022-09-21-box-java-sdk-v370-released) --- ### Box Java SDK `v3.7.1`のリリース **Type:** changelog | **Section:** Changelog Box Java SDK v3.7.1のリリース バグ修正 JSONを解析できなかった場合のログを改善 (#1106) (5e66ef8) # Box Java SDK v3.7.1のリリース ### バグ修正 - JSONを解析できなかった場合のログを改善 ([#1106](https://github.com/box/box-java-sdk/issues/1106)) ([`5e66ef8`](https://github.com/box/box-java-sdk/commit/5e66ef8cc983a6cff34995efc75e9effd3195d48)) **Source:** [https://ja.developer.box.com/changelog/2022-09-30-box-java-sdk-v371-released](https://ja.developer.box.com/changelog/2022-09-30-box-java-sdk-v371-released) --- ### Box Java SDK `v3.8.0`のリリース **Type:** changelog | **Section:** Changelog Box Java SDK v3.8.0のリリース 新機能と機能強化 Box Sign Webhookを追加 (#1109) (99051a5) バグ修正 BoxSignRequestPrefillTagを使用する際のNullPointerException (#112… # Box Java SDK v3.8.0のリリース ### 新機能と機能強化 - Box Sign Webhookを追加 ([#1109](https://github.com/box/box-java-sdk/issues/1109)) ([`99051a5`](https://github.com/box/box-java-sdk/commit/99051a575f120a8c0939359c1f4875b16b98b7f0)) ### バグ修正 - `BoxSignRequestPrefillTag`を使用する際の`NullPointerException` ([#1121](https://github.com/box/box-java-sdk/issues/1121)) ([`73fd5b6`](https://github.com/box/box-java-sdk/commit/73fd5b6e6e40f7e79b385edf46b8eee5ff612ace))、[#1120](https://github.com/box/box-java-sdk/issues/1120)をクローズ - JTIクレームが拒否された場合にJWT IDを再生成し、認証リクエストを再試行 ([#1110](https://github.com/box/box-java-sdk/issues/1110)) ([`420da0f`](https://github.com/box/box-java-sdk/commit/420da0f2c80bfe8cfbaba4fa8dec4826c4cb6337)) ### 依存関係のアップグレード - `org.bitbucket.b_c:jose4j:0.9.0`を昇格 ([#1111](https://github.com/box/box-java-sdk/issues/1111)) ([`349694d`](https://github.com/box/box-java-sdk/commit/349694ddcfeb701a9ecdfd5ae555d49bea4d1030)) **Source:** [https://ja.developer.box.com/changelog/2022-11-16-box-java-sdk-v380-released](https://ja.developer.box.com/changelog/2022-11-16-box-java-sdk-v380-released) --- ### Box Java SDK `v3.8.1`のリリース **Type:** changelog | **Section:** Changelog Box Java SDK v3.8.1のリリース バグ修正 以前のSDKバージョンの作業から状態をリストア (#1134) (b6d97dd) # Box Java SDK v3.8.1のリリース ### バグ修正 - 以前の`SDK`バージョンの作業から状態をリストア ([#1134](https://github.com/box/box-java-sdk/issues/1134)) ([`b6d97dd`](https://github.com/box/box-java-sdk/commit/b6d97dd5b0cc91eb2e4c922ff217e0878e0f63ec)) **Source:** [https://ja.developer.box.com/changelog/2022-12-19-box-java-sdk-v381-released](https://ja.developer.box.com/changelog/2022-12-19-box-java-sdk-v381-released) --- ### Box Java SDK `v3.8.2`のリリース **Type:** changelog | **Section:** Changelog Box Java SDK v3.8.2のリリース バグ修正 更新トークンがない場合の状態の復元を修正 (#1139) (3544709) # Box Java SDK v3.8.2のリリース ### バグ修正 - 更新トークンがない場合の状態の復元を修正 ([#1139](https://github.com/box/box-java-sdk/issues/1139)) ([`3544709`](https://github.com/box/box-java-sdk/commit/3544709480eb03e5bd50f5dc99be7409569304c4)) **Source:** [https://ja.developer.box.com/changelog/2023-01-04-box-java-sdk-v382-released](https://ja.developer.box.com/changelog/2023-01-04-box-java-sdk-v382-released) --- ### Box Java SDK `v4.0.0`のリリース **Type:** changelog | **Section:** Changelog Box Java SDK v4.0.0のリリース このリリースに含まれる最も重要な変更は、ネイティブのHTTPライブラリからOkHttpのライブラリへの置き換えです。これにより、SDKで以下が可能になります。 HTTPプロトコルのHTTP2バージョンのサポート Basic… # Box Java SDK v4.0.0のリリース このリリースに含まれる最も重要な変更は、ネイティブのHTTPライブラリから[OkHttp](https://square.github.io/okhttp/)のライブラリへの置き換えです。これにより、SDKで以下が可能になります。 - HTTPプロトコルのHTTP2バージョンのサポート - Basic認証方法以外も使用するプロキシのサポート。カスタムプロキシ認証の作成の詳細とNTLMプロキシ認証の例については、[こちら](https://github.com/box/box-java-sdk/blob/main/doc/configuration.md#example-ntlm-authenticator)を参照してください。 ### 重大な変更 - `BatchAPIRequest`はSDKのサポート対象外になりました - `BoxAPIConnection#DEFAULT_MAX_ATTEMPTS`は`BoxAPIConnection#DEFAULT_MAX_RETRIES`に置き換えられました - `BoxRedirectResponse`は削除され、置き換えはありません - `BoxEvent.Type`は`EventType`に置き換えられました - 非推奨となったメソッドが`BoxFile`、`BoxFileVersionRetention`、`BoxFolder`、`BoxGroup`、`BoxGroupMembership`、`BoxItem`、`BoxRetentionPolicy`、`BoxTask`、`BoxUser`、`BoxWebLink`、`EventLog`、`Metadata`、`MetadataTemplate`から削除されました 移行の詳細については[こちら](https://github.com/box/box-java-sdk/blob/main/doc/upgrades/3.x.x%20to%204.x.x.md)を参照してください。 ### 新機能と機能強化 - Java SDKでの`OkHttp`の使用 ([#1083](https://github.com/box/box-java-sdk/issues/1083)) ([`2656698`](https://github.com/box/box-java-sdk/commit/265669897100dd8f1757fc2c5f25665da42c2889)) **Source:** [https://ja.developer.box.com/changelog/2023-01-18-box-java-sdk-v400-released](https://ja.developer.box.com/changelog/2023-01-18-box-java-sdk-v400-released) --- ### Box Java SDK `v4.0.1`のリリース **Type:** changelog | **Section:** Changelog Box Java SDK v4.0.1のリリース バグ修正 OAUTH_SUFFIXがbaseAuthorizationURLに2回付加される (#1148) (3164770)、#1147をクローズ AbstractBoxMultipartRequest… # Box Java SDK v4.0.1のリリース ### バグ修正 - `OAUTH_SUFFIX`が`baseAuthorizationURL`に2回付加される ([#1148](https://github.com/box/box-java-sdk/issues/1148)) ([`3164770`](https://github.com/box/box-java-sdk/commit/3164770498e5115a43318640735317a896950f54))、[#1147](https://github.com/box/box-java-sdk/issues/1147)をクローズ - `AbstractBoxMultipartRequest`によって誤った進捗が`ProgressListener`に報告される ([#1151](https://github.com/box/box-java-sdk/issues/1151)) ([`947ded3`](https://github.com/box/box-java-sdk/commit/947ded394490fc840b8191bc7ad69ae0ea5f5c7d))、[#1149](https://github.com/box/box-java-sdk/issues/1149)をクローズ **Source:** [https://ja.developer.box.com/changelog/2023-03-06-box-java-sdk-v401-released](https://ja.developer.box.com/changelog/2023-03-06-box-java-sdk-v401-released) --- ### Box Java SDK `v4.1.0`のリリース **Type:** changelog | **Section:** Changelog Box Java SDK v4.1.0のリリース 新機能と機能強化 BoxUserメソッドの作成、更新で不足していたfieldsパラメータを追加 (#1155) (be3820d)、#1154をクローズ バグ修正 カスタムロガーハンドラの登録を許可 (#1156) (7373d… # Box Java SDK v4.1.0のリリース ### 新機能と機能強化 - `BoxUser`メソッドの作成、更新で不足していた`fields`パラメータを追加 ([#1155](https://github.com/box/box-java-sdk/issues/1155)) ([`be3820d`](https://github.com/box/box-java-sdk/commit/be3820dc4df15e99dfc13602d4f7269841bd15b3))、[#1154](https://github.com/box/box-java-sdk/issues/1154)をクローズ ### バグ修正 - カスタムロガーハンドラの登録を許可 ([#1156](https://github.com/box/box-java-sdk/issues/1156)) ([`7373d5c`](https://github.com/box/box-java-sdk/commit/7373d5cc2bf49bc198cbca70d056e43f0dffdb3a)) - `BoxAPIConnection`の復元時に`maxRetryAttempts`のデフォルト値にフォールバック ([#1161](https://github.com/box/box-java-sdk/issues/1161)) ([`2a10e5d`](https://github.com/box/box-java-sdk/commit/2a10e5d07497611e077a9207fe98c1d8146cfd22))、[#1160](https://github.com/box/box-java-sdk/issues/1160)をクローズ **Source:** [https://ja.developer.box.com/changelog/2023-04-24-box-java-sdk-v410-released](https://ja.developer.box.com/changelog/2023-04-24-box-java-sdk-v410-released) --- ### Box Java SDK `v4.1.1`のリリース **Type:** changelog | **Section:** Changelog Box Java SDK v4.1.1のリリース バグ修正 認証ヘッダーの追加の無効化をユーザーに許可 (#1167) (3433e5a) リクエストの再試行時にヘッダーをログに記録 (#1164) (e0c3d8e) # Box Java SDK v4.1.1のリリース ### バグ修正 - 認証ヘッダーの追加の無効化をユーザーに許可 ([#1167](https://github.com/box/box-java-sdk/issues/1167)) ([`3433e5a`](https://github.com/box/box-java-sdk/commit/3433e5a405ceb9bc32791642518b1fd65c4b4032)) - リクエストの再試行時にヘッダーをログに記録 ([#1164](https://github.com/box/box-java-sdk/issues/1164)) ([`e0c3d8e`](https://github.com/box/box-java-sdk/commit/e0c3d8e730962ba5c97105ce506ee931a3bba362)) **Source:** [https://ja.developer.box.com/changelog/2023-05-16-box-java-sdk-v411-released](https://ja.developer.box.com/changelog/2023-05-16-box-java-sdk-v411-released) --- ### Box Java SDK `v4.1.2`のリリース **Type:** changelog | **Section:** Changelog Box Java SDK v4.1.2のリリース バグ修正 大きいファイルをアップロードする際のClassCastException (#1174) (e7d28bd)、#1173をクローズ SharedLinkAPIConnectionコンストラクタをpublic… # Box Java SDK v4.1.2のリリース ### バグ修正 - 大きいファイルをアップロードする際のClassCastException ([#1174](https://github.com/box/box-java-sdk/issues/1174)) ([`e7d28bd`](https://github.com/box/box-java-sdk/commit/e7d28bddb706c8b4fd1328f0eebc50db19a8c656))、[#1173](https://github.com/box/box-java-sdk/issues/1173)をクローズ - `SharedLinkAPIConnection`コンストラクタをpublicに変更 ([#1172](https://github.com/box/box-java-sdk/issues/1172)) ([`4d1616d`](https://github.com/box/box-java-sdk/commit/4d1616ddd2c39d1cb0d03af998d2c47efe607853)) - 無効なグループメンバーシップロールを削除 ([#1171](https://github.com/box/box-java-sdk/issues/1171)) ([`a5915f9`](https://github.com/box/box-java-sdk/commit/a5915f94114a8269287831280a57949ed203e4e8)) **Source:** [https://ja.developer.box.com/changelog/2023-06-14-box-java-sdk-v412-released](https://ja.developer.box.com/changelog/2023-06-14-box-java-sdk-v412-released) --- ### Box Java SDK `v4.10.0`のリリース **Type:** changelog | **Section:** Changelog Box Java SDK v4.10.0のリリース 新機能と機能強化 maxRetriesパラメータを使用してgetRepresentationContentメソッドをオーバーロード (#1251) (d26bd4f) 署名リクエストでlogin_required… # Box Java SDK v4.10.0のリリース ### 新機能と機能強化 - `maxRetries`パラメータを使用して`getRepresentationContent`メソッドをオーバーロード ([#1251](https://github.com/box/box-java-sdk/issues/1251)) ([`d26bd4f`](https://github.com/box/box-java-sdk/commit/d26bd4f5a141150a372159bc3867abbbbdda1406)) - 署名リクエストで`login_required`、`password`、`suppress_nofitications`、`verification_phone_number`、`additional_info`フィールドをサポート ([#1250](https://github.com/box/box-java-sdk/issues/1250)) ([`3ee55b3`](https://github.com/box/box-java-sdk/commit/3ee55b3613c5f5fa92cdd4a17c0cb3e2cc86a9a4)) **Source:** [https://ja.developer.box.com/changelog/2024-06-06-box-java-sdk-v4100-released](https://ja.developer.box.com/changelog/2024-06-06-box-java-sdk-v4100-released) --- ### Box Java SDK `v4.11.0`のリリース **Type:** changelog | **Section:** Changelog Box Java SDK v4.11.0のリリース 新機能と機能強化 OkHttp呼び出しの作成のオーバーライドを許可 (#1257) (bd6fde6) バグ修正 分類テンプレートの更新時に不足していたフィールドを追加 (#1255) (f17f817) BoxFile… # Box Java SDK v4.11.0のリリース ### 新機能と機能強化 - OkHttp呼び出しの作成のオーバーライドを許可 ([#1257](https://github.com/box/box-java-sdk/issues/1257)) ([`bd6fde6`](https://github.com/box/box-java-sdk/commit/bd6fde6689bebe6cb5889c91214db68e08a4ec8b)) ### バグ修正 - 分類テンプレートの更新時に不足していたフィールドを追加 ([#1255](https://github.com/box/box-java-sdk/issues/1255)) ([`f17f817`](https://github.com/box/box-java-sdk/commit/f17f817bde5a412358bf3de8e489ed080715ec4b)) - `BoxFile`および`BoxFolder`の権限の逆シリアル化を修正 ([#1256](https://github.com/box/box-java-sdk/issues/1256)) ([`f088448`](https://github.com/box/box-java-sdk/commit/f08844889800a01f7c78941036f6228502fca8b0)) **Source:** [https://ja.developer.box.com/changelog/2024-07-15-box-java-sdk-v4110-released](https://ja.developer.box.com/changelog/2024-07-15-box-java-sdk-v4110-released) --- ### Box Java SDK `v4.11.1`のリリース **Type:** changelog | **Section:** Changelog Box Java SDK v4.11.1のリリース バグ修正 ファイルアップロードのマルチパートリクエストの順序を修正 (#1261) (7200ac7) # Box Java SDK v4.11.1のリリース ### バグ修正 - ファイルアップロードのマルチパートリクエストの順序を修正 ([#1261](https://github.com/box/box-java-sdk/issues/1261)) ([`7200ac7`](https://github.com/box/box-java-sdk/commit/7200ac77888b3639f2c294486be278e316efcfb0)) **Source:** [https://ja.developer.box.com/changelog/2024-07-16-box-java-sdk-v4111-released](https://ja.developer.box.com/changelog/2024-07-16-box-java-sdk-v4111-released) --- ### Box Java SDK `v4.12.0`のリリース **Type:** changelog | **Section:** Changelog Box Java SDK v4.12.0のリリース 新機能と機能強化 AIエージェントをサポート (#1265) (3cb2c7c) AIによる抽出 (自由形式および構造化) をサポート (#1266) (7ba90b9) # Box Java SDK v4.12.0のリリース ### 新機能と機能強化 - AIエージェントをサポート ([#1265](https://github.com/box/box-java-sdk/issues/1265)) ([`3cb2c7c`](https://github.com/box/box-java-sdk/commit/3cb2c7c275761a24be9403a6a2b41d0725ba8d9b)) - AIによる抽出 (自由形式および構造化) をサポート ([#1266](https://github.com/box/box-java-sdk/issues/1266)) ([`7ba90b9`](https://github.com/box/box-java-sdk/commit/7ba90b96070a32b3e2ac60e5c55bd04d0a5973c0)) **Source:** [https://ja.developer.box.com/changelog/2024-10-18-box-java-sdk-v4120-released](https://ja.developer.box.com/changelog/2024-10-18-box-java-sdk-v4120-released) --- ### Box Java SDK `v4.13.1`のリリース **Type:** changelog | **Section:** Changelog Box Java SDK v4.13.1のリリース バグ修正 ストリームから読み取る際にContent-Lengthを正しく計算 (#1277) (b1d5371) # Box Java SDK v4.13.1のリリース ### バグ修正 - ストリームから読み取る際に`Content-Length`を正しく計算 ([#1277](https://github.com/box/box-java-sdk/issues/1277)) ([`b1d5371`](https://github.com/box/box-java-sdk/commit/b1d5371491abe1729a95eb9dc39d375135c8681d)) **Source:** [https://ja.developer.box.com/changelog/2024-11-29-box-java-sdk-v4131-released](https://ja.developer.box.com/changelog/2024-11-29-box-java-sdk-v4131-released) --- ### Box Java SDK `v4.14.0`のリリース **Type:** changelog | **Section:** Changelog Box Java SDK v4.14.0のリリース 新機能と機能強化 共有リンクからのファイルのダウンロードをサポート (#1282) (9b7f28b) バグ修正 BoxAPIExceptionがリクエストをログに記録した際に機密データを削除 (#1284) (f1e226f… # Box Java SDK v4.14.0のリリース ### 新機能と機能強化 - 共有リンクからのファイルのダウンロードをサポート ([#1282](https://github.com/box/box-java-sdk/issues/1282)) ([`9b7f28b`](https://github.com/box/box-java-sdk/commit/9b7f28b0288977513b0db3ed4f800647545e1f2c)) ### バグ修正 - `BoxAPIException`がリクエストをログに記録した際に機密データを削除 ([#1284](https://github.com/box/box-java-sdk/issues/1284)) ([`f1e226f`](https://github.com/box/box-java-sdk/commit/f1e226f710c301202acff067ef34687ddbb57b7b)) - 開始日を指定した継続的なリーガルホールドポリシーの作成をサポート ([#1281](https://github.com/box/box-java-sdk/issues/1281)) ([`d9564e2`](https://github.com/box/box-java-sdk/commit/d9564e2e86ea110af933ca3dd0f728111d7140ae)) **Source:** [https://ja.developer.box.com/changelog/2025-01-22-box-java-sdk-v4140-released](https://ja.developer.box.com/changelog/2025-01-22-box-java-sdk-v4140-released) --- ### Box Java SDK `v4.15.0`のリリース **Type:** changelog | **Section:** Changelog Box Java SDK v4.15.0のリリース 新機能と機能強化 BoxFolderにcanNonOwnersViewCollaboratorsフラグを追加 (#1288) (9119adc) ダウンロードでzstdエンコードをサポート (#1287) (0e3c4c… # Box Java SDK v4.15.0のリリース ### 新機能と機能強化 - `BoxFolder`に`canNonOwnersViewCollaborators`フラグを追加 ([#1288](https://github.com/box/box-java-sdk/issues/1288)) ([`9119adc`](https://github.com/box/box-java-sdk/commit/9119adceae35e892e73ed61ed30cf82ad912960d)) - ダウンロードで`zstd`エンコードをサポート ([#1287](https://github.com/box/box-java-sdk/issues/1287)) ([`0e3c4c0`](https://github.com/box/box-java-sdk/commit/0e3c4c07e65ef1887cd5c393e3daf98aeb50ee47)) ### バグ修正 - AIの会話履歴を修正 ([#1289](https://github.com/box/box-java-sdk/issues/1289)) ([`29b6519`](https://github.com/box/box-java-sdk/commit/29b651987a5cbeead4b129cab20970f983cb6889)) **Source:** [https://ja.developer.box.com/changelog/2025-02-19-box-java-sdk-v4150-released](https://ja.developer.box.com/changelog/2025-02-19-box-java-sdk-v4150-released) --- ### Box Java SDK `v4.15.1`のリリース **Type:** changelog | **Section:** Changelog Box Java SDK v4.15.1のリリース バグ修正 content-lengthヘッダーの解析を修正 (#1292) (3bcf788) # Box Java SDK v4.15.1のリリース ### バグ修正 - content-lengthヘッダーの解析を修正 ([#1292](https://github.com/box/box-java-sdk/issues/1292)) ([`3bcf788`](https://github.com/box/box-java-sdk/commit/3bcf788dd9849305aa2cc85b8e5f88b35803ecb2)) **Source:** [https://ja.developer.box.com/changelog/2025-02-24-box-java-sdk-v4151-released](https://ja.developer.box.com/changelog/2025-02-24-box-java-sdk-v4151-released) --- ### Box Java SDK `v4.15.2`のリリース **Type:** changelog | **Section:** Changelog Box Java SDK v4.15.2のリリース バグ修正 APIリクエストとAPIレスポンスのログ記録を改善 (#1295) (6eb1f57) # Box Java SDK v4.15.2のリリース ### バグ修正 - APIリクエストとAPIレスポンスのログ記録を改善 ([#1295](https://github.com/box/box-java-sdk/issues/1295)) ([`6eb1f57`](https://github.com/box/box-java-sdk/commit/6eb1f57a584571b46daa14d045a36bca382493fa)) **Source:** [https://ja.developer.box.com/changelog/2025-02-26-box-java-sdk-v4152-released](https://ja.developer.box.com/changelog/2025-02-26-box-java-sdk-v4152-released) --- ### Box Java SDK `v4.15.3`のリリース **Type:** changelog | **Section:** Changelog Box Java SDK v4.15.3のリリース バグ修正 content-lengthヘッダーの値をトリミング (#1297) (fa11d14) # Box Java SDK v4.15.3のリリース ### バグ修正 - `content-length`ヘッダーの値をトリミング ([#1297](https://github.com/box/box-java-sdk/issues/1297)) ([`fa11d14`](https://github.com/box/box-java-sdk/commit/fa11d141edf511eabc5f2398e55dc411d0cdcd31)) **Source:** [https://ja.developer.box.com/changelog/2025-03-12-box-java-sdk-v4153-released](https://ja.developer.box.com/changelog/2025-03-12-box-java-sdk-v4153-released) --- ### Box Java SDK `v4.16.0`のリリース **Type:** changelog | **Section:** Changelog Box Java SDK v4.16.0のリリース 新機能と機能強化 zstd-jniのバージョンを昇格 (#1302) (9ebf8b5) # Box Java SDK v4.16.0のリリース ### 新機能と機能強化 - `zstd-jni`のバージョンを昇格 ([#1302](https://github.com/box/box-java-sdk/issues/1302)) ([`9ebf8b5`](https://github.com/box/box-java-sdk/commit/9ebf8b5d16c0ab8f4aa19849fdaa86935d38b294)) **Source:** [https://ja.developer.box.com/changelog/2025-04-15-box-java-sdk-v4160-released](https://ja.developer.box.com/changelog/2025-04-15-box-java-sdk-v4160-released) --- ### Box Java SDK `v4.16.1`のリリース **Type:** changelog | **Section:** Changelog Box Java SDK v4.16.1のリリース バグ修正 Locale.ROOTを使用して米国以外のロケールでの問題を防止 (#1306) (f083092) # Box Java SDK v4.16.1のリリース ### バグ修正 - `Locale.ROOT`を使用して米国以外のロケールでの問題を防止 ([#1306](https://github.com/box/box-java-sdk/issues/1306)) ([`f083092`](https://github.com/box/box-java-sdk/commit/f083092d5fdac37c93493945ab0c05ecdcdbc838)) **Source:** [https://ja.developer.box.com/changelog/2025-04-29-box-java-sdk-v4161-released](https://ja.developer.box.com/changelog/2025-04-29-box-java-sdk-v4161-released) --- ### Box Java SDK `v4.16.2`のリリース **Type:** changelog | **Section:** Changelog Box Java SDK v4.16.2のリリース バグ修正 BoxZipDownloadStatusのdownloadFileCountプロパティの解析を修正 (50c2249) # Box Java SDK v4.16.2のリリース ### バグ修正 - `BoxZipDownloadStatus`の`downloadFileCount`プロパティの解析を修正 ([`50c2249`](https://github.com/box/box-java-sdk/commit/50c2249ff5e0f0d1fdc99c9ff8786e9c134e58eb)) **Source:** [https://ja.developer.box.com/changelog/2025-06-02-box-java-sdk-v4162-released](https://ja.developer.box.com/changelog/2025-06-02-box-java-sdk-v4162-released) --- ### Box Java SDK `v4.16.3`のリリース **Type:** changelog | **Section:** Changelog Box Java SDK v4.16.3のリリース バグ修正 Webhookメッセージの署名の比較を修正 (#1315) (e2d407d) 有効なデータを返すよう、ファイルリクエストのコピーメソッドを修正 (#1320) (8392a43) # Box Java SDK v4.16.3のリリース ### バグ修正 - Webhookメッセージの署名の比較を修正 ([#1315](https://github.com/box/box-java-sdk/issues/1315)) ([`e2d407d`](https://github.com/box/box-java-sdk/commit/e2d407ded3370ffee6eb074044fd562629a904be)) - 有効なデータを返すよう、ファイルリクエストのコピーメソッドを修正 ([#1320](https://github.com/box/box-java-sdk/issues/1320)) ([`8392a43`](https://github.com/box/box-java-sdk/commit/8392a437c1a738bebb4e7d0f84d6bf833c76bdf3)) **Source:** [https://ja.developer.box.com/changelog/2025-07-23-box-java-sdk-v4163-released](https://ja.developer.box.com/changelog/2025-07-23-box-java-sdk-v4163-released) --- ### Box Java SDK `v4.2.0`のリリース **Type:** changelog | **Section:** Changelog Box Java SDK v4.2.0のリリース 新機能と機能強化 フィールドの指定をコラボレータに許可 (#1178) (1694d75) # Box Java SDK v4.2.0のリリース ### 新機能と機能強化 - フィールドの指定をコラボレータに許可 ([#1178](https://github.com/box/box-java-sdk/issues/1178)) ([`1694d75`](https://github.com/box/box-java-sdk/commit/1694d75fff0fbddb938426ef03ba24f360a344aa)) **Source:** [https://ja.developer.box.com/changelog/2023-06-21-box-java-sdk-v420-released](https://ja.developer.box.com/changelog/2023-06-21-box-java-sdk-v420-released) --- ### Box Java SDK `v4.2.1`のリリース **Type:** changelog | **Section:** Changelog Box Java SDK v4.2.1のリリース バグ修正 動的ソースからのデータである場合のアップロードを修正 (#1189) (77b39f2)、#1183 #1190をクローズ # Box Java SDK v4.2.1のリリース ### バグ修正 - 動的ソースからのデータである場合のアップロードを修正 ([#1189](https://github.com/box/box-java-sdk/issues/1189)) ([`77b39f2`](https://github.com/box/box-java-sdk/commit/77b39f2645d53bdab0ade23b637c211ea070fcf5))、[#1183](https://github.com/box/box-java-sdk/issues/1183) [#1190](https://github.com/box/box-java-sdk/issues/1190)をクローズ **Source:** [https://ja.developer.box.com/changelog/2023-08-03-box-java-sdk-v421-released](https://ja.developer.box.com/changelog/2023-08-03-box-java-sdk-v421-released) --- ### Box Java SDK `v4.3.0`のリリース **Type:** changelog | **Section:** Changelog Box Java SDK v4.3.0のリリース 新機能と機能強化 アクセスのみのコラボレーションをサポート (#1193) (664c01f) # Box Java SDK v4.3.0のリリース ### 新機能と機能強化 - アクセスのみのコラボレーションをサポート ([#1193](https://github.com/box/box-java-sdk/issues/1193)) ([`664c01f`](https://github.com/box/box-java-sdk/commit/664c01f80ca0647645c60920eb0ef1f9353a619f)) **Source:** [https://ja.developer.box.com/changelog/2023-08-11-box-java-sdk-v430-released](https://ja.developer.box.com/changelog/2023-08-11-box-java-sdk-v430-released) --- ### Box Java SDK `v4.4.0`のリリース **Type:** changelog | **Section:** Changelog Box Java SDK v4.4.0のリリース 新機能と機能強化 Signのテンプレートと新しいステータスをサポート (#1197) (e37c0dc) # Box Java SDK v4.4.0のリリース ### 新機能と機能強化 - Signのテンプレートと新しいステータスをサポート ([#1197](https://github.com/box/box-java-sdk/issues/1197)) ([`e37c0dc`](https://github.com/box/box-java-sdk/commit/e37c0dce86a422de5e8e6ed26fd93f1324f4b3e3)) **Source:** [https://ja.developer.box.com/changelog/2023-08-29-box-java-sdk-v440-released](https://ja.developer.box.com/changelog/2023-08-29-box-java-sdk-v440-released) --- ### Box Java SDK `v4.5.0`のリリース **Type:** changelog | **Section:** Changelog Box Java SDK v4.5.0のリリース 新機能と機能強化 iframeable_embed_urlフィールドをBoxSignRequestSignerクラスに追加 (#1202) (2e931d8) バグ修正 SharedLinkAPIConnection… # Box Java SDK v4.5.0のリリース ### 新機能と機能強化 - `iframeable_embed_url`フィールドを`BoxSignRequestSigner`クラスに追加 ([#1202](https://github.com/box/box-java-sdk/issues/1202)) ([`2e931d8`](https://github.com/box/box-java-sdk/commit/2e931d8c36694a665d1c6315d3bf2d226929b713)) ### バグ修正 - `SharedLinkAPIConnection`でリクエストインターセプタを使用 ([#1203](https://github.com/box/box-java-sdk/issues/1203)) ([`b2b6a1d`](https://github.com/box/box-java-sdk/commit/b2b6a1dba316ba50a1e011250c320fca156c6708))、[#1200](https://github.com/box/box-java-sdk/issues/1200)をクローズ - 列挙型の不足についてSignテンプレートを更新 ([#1201](https://github.com/box/box-java-sdk/issues/1201)) ([`fcb6657`](https://github.com/box/box-java-sdk/commit/fcb6657bb2375e32c3fb0f861e7ecaeb84503f2c)) **Source:** [https://ja.developer.box.com/changelog/2023-09-14-box-java-sdk-v450-released](https://ja.developer.box.com/changelog/2023-09-14-box-java-sdk-v450-released) --- ### Box Java SDK `v4.6.0`のリリース **Type:** changelog | **Section:** Changelog Box Java SDK v4.6.0のリリース 新機能と機能強化 削除済み項目の検索フィルタをサポート (#1207) (5e0e9ed) バグ修正 trustManagerとhostnameVerifier向けにprotectedアクセサを追加 (#1206) (0c79d… # Box Java SDK v4.6.0のリリース ### 新機能と機能強化 - 削除済み項目の検索フィルタをサポート ([#1207](https://github.com/box/box-java-sdk/issues/1207)) ([`5e0e9ed`](https://github.com/box/box-java-sdk/commit/5e0e9ed9aea2818da6fba0d562b56987c4948aaa)) ### バグ修正 - trustManagerとhostnameVerifier向けにprotectedアクセサを追加 ([#1206](https://github.com/box/box-java-sdk/issues/1206)) ([`0c79d17`](https://github.com/box/box-java-sdk/commit/0c79d1754bffeb3f0487e10d55d716ba1cbed1aa)) - クローズされていないレスポンス本文を修正 ([#1208](https://github.com/box/box-java-sdk/issues/1208)) ([`ab5e170`](https://github.com/box/box-java-sdk/commit/ab5e1702934607b258802b33f3663af3e9c56027)) **Source:** [https://ja.developer.box.com/changelog/2023-09-29-box-java-sdk-v460-released](https://ja.developer.box.com/changelog/2023-09-29-box-java-sdk-v460-released) --- ### Box Java SDK `v4.6.1`のリリース **Type:** changelog | **Section:** Changelog Box Java SDK v4.6.1のリリース 依存関係のアップグレード org.bitbucket.b_c:jose4j:0.9.3を昇格 (#1212) (f522a56) # Box Java SDK v4.6.1のリリース ### 依存関係のアップグレード - `org.bitbucket.b_c:jose4j:0.9.3`を昇格 ([#1212](https://github.com/box/box-java-sdk/issues/1212)) ([`f522a56`](https://github.com/box/box-java-sdk/commit/f522a5660f3522b11a0516774ba0cca69db3ec31)) **Source:** [https://ja.developer.box.com/changelog/2023-11-02-box-java-sdk-v461-released](https://ja.developer.box.com/changelog/2023-11-02-box-java-sdk-v461-released) --- ### Box Java SDK `v4.7.0`のリリース **Type:** changelog | **Section:** Changelog Box Java SDK v4.7.0のリリース 新機能と機能強化 署名者用にsigner_group_idを署名リクエストに追加 (#1220) (f560db8) BouncyCastleをv.1.70にアップグレード 注: BouncyCastle… # Box Java SDK v4.7.0のリリース ### 新機能と機能強化 - 署名者用に`signer_group_id`を署名リクエストに追加 ([#1220](https://github.com/box/box-java-sdk/issues/1220)) ([`f560db8`](https://github.com/box/box-java-sdk/commit/f560db8d5587406099066803789d16374ec7dbb9)) `BouncyCastle`をv.`1.70`にアップグレード **注**: `BouncyCastle`の新しいバージョンはFIPSとの互換性がありません。 - `IPrivateKeyDecryptor`を導入し、カスタム暗号化プロバイダの使用を許可 ([#1226](https://github.com/box/box-java-sdk/issues/1226)) ([`727e6d7`](https://github.com/box/box-java-sdk/commit/727e6d71ee375a48b4241a26a093becfe0965898)) ### バグ修正 - 分類の削除に関する記述を削除 ([#1222](https://github.com/box/box-java-sdk/issues/1222)) ([`9814038`](https://github.com/box/box-java-sdk/commit/981403896b4cd16a42c9feeecf30e75e1e8fa072)) **Source:** [https://ja.developer.box.com/changelog/2024-01-16-box-java-sdk-v470-released](https://ja.developer.box.com/changelog/2024-01-16-box-java-sdk-v470-released) --- ### Box Java SDK `v4.8.0`のリリース **Type:** changelog | **Section:** Changelog Box Java SDK v4.8.0のリリース 新機能と機能強化 BoxAPIRequest URLの変更を許可 (#1236) (eaea019) org.bouncycastle:bcprov-jdk18on:1.77とorg.bouncycastle:bcpkix-jdk… # Box Java SDK v4.8.0のリリース ### 新機能と機能強化 - `BoxAPIRequest` URLの変更を許可 ([#1236](https://github.com/box/box-java-sdk/issues/1236)) ([`eaea019`](https://github.com/box/box-java-sdk/commit/eaea0193ab7e72b73746ea85806e62468825bbce)) - `org.bouncycastle:bcprov-jdk18on:1.77`と`org.bouncycastle:bcpkix-jdk18on:1.77`を昇格 ([#1237](https://github.com/box/box-java-sdk/issues/1237)) ([`6c7fe7b`](https://github.com/box/box-java-sdk/commit/6c7fe7b74dbfb34e729fcecf8a29a1d3a1ba596f))、[#1235](https://github.com/box/box-java-sdk/issues/1235)をクローズ ### バグ修正 - 空のファイルのダウンロードについて修正 ([#1231](https://github.com/box/box-java-sdk/issues/1231)) ([`0e2230b`](https://github.com/box/box-java-sdk/commit/0e2230b0be36f6bfb35f1d6b9dd4ba58e4d125ec)) - `getSharedItem()`での`SharedLinkAPIConnection`の使用を停止 ([#1234](https://github.com/box/box-java-sdk/issues/1234)) ([`9f9af8e`](https://github.com/box/box-java-sdk/commit/9f9af8e22b4a38dc9a31a611ff1b962966bbd6b5)) **Source:** [https://ja.developer.box.com/changelog/2024-02-27-box-java-sdk-v480-released](https://ja.developer.box.com/changelog/2024-02-27-box-java-sdk-v480-released) --- ### Box Java SDK `v4.9.0`のリリース **Type:** changelog | **Section:** Changelog Box Java SDK v4.9.0のリリース 新機能と機能強化 AI APIをサポート (#1243) (4e64f27) ファイルバージョンのページ割りをサポート (#1240) (7e7af3f) バグ修正 空の共有リンクの作成をサポート (#1241) (0c8648… # Box Java SDK v4.9.0のリリース ### 新機能と機能強化 - AI APIをサポート ([#1243](https://github.com/box/box-java-sdk/issues/1243)) ([`4e64f27`](https://github.com/box/box-java-sdk/commit/4e64f27874fabf36f7fbf385ca4a60683f4a7670)) - ファイルバージョンのページ割りをサポート ([#1240](https://github.com/box/box-java-sdk/issues/1240)) ([`7e7af3f`](https://github.com/box/box-java-sdk/commit/7e7af3f6e40a44522a7649817547846e3f633fc8)) ### バグ修正 - 空の共有リンクの作成をサポート ([#1241](https://github.com/box/box-java-sdk/issues/1241)) ([`0c86487`](https://github.com/box/box-java-sdk/commit/0c86487848e5004a713873baffa2d9dcc63b1502)) - レプリゼンテーションコンテンツ取得に関する例外メッセージを更新 ([#1239](https://github.com/box/box-java-sdk/issues/1239)) ([`a608f9a`](https://github.com/box/box-java-sdk/commit/a608f9a4350b723e9f07eaf00af45243737a17c9)) **Source:** [https://ja.developer.box.com/changelog/2024-05-07-box-java-sdk-v490-released](https://ja.developer.box.com/changelog/2024-05-07-box-java-sdk-v490-released) --- ### Box Java SDK `v4.9.1`のリリース **Type:** changelog | **Section:** Changelog Box Java SDK v4.9.1のリリース バグ修正 org.bouncycastle:bcprov-jdk18on:1.78.1およびorg.bouncycastle:bcpkix-jdk18on:1.78.1を昇格 (#1246) (0557bed) # Box Java SDK v4.9.1のリリース ### バグ修正 - `org.bouncycastle:bcprov-jdk18on:1.78.1`および`org.bouncycastle:bcpkix-jdk18on:1.78.1`を昇格 ([#1246](https://github.com/box/box-java-sdk/issues/1246)) ([`0557bed`](https://github.com/box/box-java-sdk/commit/0557bed2b65d1be717b64a612d74fca73ba21096)) **Source:** [https://ja.developer.box.com/changelog/2024-06-06-box-java-sdk-v491-released](https://ja.developer.box.com/changelog/2024-06-06-box-java-sdk-v491-released) --- ### Box Node SDK `v1.33.0`のリリース **Type:** changelog | **Section:** Changelog Box Node SDK v1.33.0のリリース パスパラメータのサニタイズを追加 (#505) 46b780a ファイルのアップロードのためにすべてのストリームのサポートを追加 (#519) 93a27ec https://github.com/box/box-node… # Box Node SDK v1.33.0のリリース - パスパラメータのサニタイズを追加 ([#505](https://github.com/box/box-node-sdk/issues/505)) [`46b780a`](https://github.com/box/box-node-sdk/commit/46b780a577999262f09f167c577471275c066609) - ファイルのアップロードのためにすべてのストリームのサポートを追加 ([#519](https://github.com/box/box-node-sdk/issues/519)) [`93a27ec`](https://github.com/box/box-node-sdk/commit/93a27ec8a5cdf4cb23d16d322e1e884913472239) [https://github.com/box/box-node-sdk/compare/v1.32.0...v1.33.0](https://github.com/box/box-node-sdk/compare/v1.32.0...v1.33.0) **Source:** [https://ja.developer.box.com/changelog/2020-06-25-box-node-sdk-v1330-released](https://ja.developer.box.com/changelog/2020-06-25-box-node-sdk-v1330-released) --- ### Box Node SDK `v1.34.0`のリリース **Type:** changelog | **Section:** Changelog Box Node SDK v1.34.0のリリース Zip機能の追加 (#525) 2f89357 HTTP、HTTPS、SOCKS、PACプロトコルのプロキシサポートの追加 (#529) b08cc24 https://github.com/box/box-node-sdk… # Box Node SDK v1.34.0のリリース - Zip機能の追加 ([#525](https://github.com/box/box-node-sdk/issues/525)) [`2f89357`](https://github.com/box/box-node-sdk/commit/2f893577fd06dcac449ac9bfeb72cd76e1e839ae) - HTTP、HTTPS、SOCKS、PACプロトコルのプロキシサポートの追加 ([#529](https://github.com/box/box-node-sdk/issues/529)) [`b08cc24`](https://github.com/box/box-node-sdk/commit/b08cc24f240075fb24d9e5827f50ec9e26eeebc8) [https://github.com/box/box-node-sdk/compare/v1.33.0...v1.34.0](https://github.com/box/box-node-sdk/compare/v1.33.0...v1.34.0) **Source:** [https://ja.developer.box.com/changelog/2020-08-07-box-node-sdk-v1340-released](https://ja.developer.box.com/changelog/2020-08-07-box-node-sdk-v1340-released) --- ### Box Node SDK `v1.34.1`のリリース **Type:** changelog | **Section:** Changelog Box Node SDK v1.34.1のリリース 新しいファイルバージョンをアップロードする際の反復子のバグを修正 (#531) 69b1387 https://github.com/box/box-node-sdk/compare/v1.34.0...v1.34.1 # Box Node SDK v1.34.1のリリース - 新しいファイルバージョンをアップロードする際の反復子のバグを修正 ([#531](https://github.com/box/box-node-sdk/issues/531)) [`69b1387`](https://github.com/box/box-node-sdk/commit/69b138746c64ac8ee68b421853ca9ff4cc28531e) [https://github.com/box/box-node-sdk/compare/v1.34.0...v1.34.1](https://github.com/box/box-node-sdk/compare/v1.34.0...v1.34.1) **Source:** [https://ja.developer.box.com/changelog/2020-08-17-box-node-sdk-v1341-released](https://ja.developer.box.com/changelog/2020-08-17-box-node-sdk-v1341-released) --- ### Box Node SDK `v1.34.2`のリリース **Type:** changelog | **Section:** Changelog Box Node SDK v1.34.2のリリース ファイルをアップロードする際の反復子のバグを修正 (#534) b0baa18 https://github.com/box/box-node-sdk/compare/v1.34.1...v1.34.2 # Box Node SDK v1.34.2のリリース - ファイルをアップロードする際の反復子のバグを修正 ([#534](https://github.com/box/box-node-sdk/issues/534)) [`b0baa18`](https://github.com/box/box-node-sdk/commit/b0baa18ef6d9dab99fd1db5b898d2cce46e5521d) [https://github.com/box/box-node-sdk/compare/v1.34.1...v1.34.2](https://github.com/box/box-node-sdk/compare/v1.34.1...v1.34.2) **Source:** [https://ja.developer.box.com/changelog/2020-08-20-box-node-sdk-v1342-released](https://ja.developer.box.com/changelog/2020-08-20-box-node-sdk-v1342-released) --- ### Box Node SDK `v1.34.3`のリリース **Type:** changelog | **Section:** Changelog Box Node SDK v1.34.3のリリース バグ修正: ajv依存関係のアップグレード (#545) # Box Node SDK v1.34.3のリリース バグ修正: - `ajv`依存関係のアップグレード ([#545](https://github.com/box/box-node-sdk/issues/545)) **Source:** [https://ja.developer.box.com/changelog/2020-10-05-box-node-sdk-v1343-released](https://ja.developer.box.com/changelog/2020-10-05-box-node-sdk-v1343-released) --- ### Box Node SDK `v1.35.0`のリリース **Type:** changelog | **Section:** Changelog Box Node SDK v1.35.0のリリース 新機能と機能強化: 共有リンク項目を取得するための検索パラメータのサポートを追加 (#547) # Box Node SDK v1.35.0のリリース **新機能と機能強化:** - 共有リンク項目を取得するための検索パラメータのサポートを追加 ([#547](https://github.com/box/box-node-sdk/issues/547)) **Source:** [https://ja.developer.box.com/changelog/2020-11-02-box-node-sdk-v1350-released](https://ja.developer.box.com/changelog/2020-11-02-box-node-sdk-v1350-released) --- ### Box Node SDK `v1.36.0`のリリース **Type:** changelog | **Section:** Changelog Box Node SDK v1.36.0のリリース 新機能と機能強化: フォルダロック機能を追加 (#560) 名前によるグループのフィルタのサポートを追加 (#561) バグ修正: プロキシサポートの問題にパッチを適用するためのプロキシエージェントの更新 (#56… # Box Node SDK v1.36.0のリリース **新機能と機能強化:** - フォルダロック機能を追加 ([#560](https://github.com/box/box-node-sdk/pull/560)) - 名前によるグループのフィルタのサポートを追加 ([#561](https://github.com/box/box-node-sdk/pull/561)) **バグ修正:** - プロキシサポートの問題にパッチを適用するためのプロキシエージェントの更新 ([#563](https://github.com/box/box-node-sdk/pull/563)) - セキュリティの脆弱性にパッチを適用するための依存関係の更新 ([#566](https://github.com/box/box-node-sdk/pull/566)) **Source:** [https://ja.developer.box.com/changelog/2021-01-28-box-node-sdk-v1360-released](https://ja.developer.box.com/changelog/2021-01-28-box-node-sdk-v1360-released) --- ### Box Node SDK `v1.37.0`のリリース **Type:** changelog | **Section:** Changelog Box Node SDK v1.37.0のリリース 新機能と機能強化: メタデータテンプレートのcopyInstanceOnItemCopyフィールドのサポートを追加 (#572) バグ修正: Webhook署名の検証を修正 (#56… # Box Node SDK v1.37.0のリリース **新機能と機能強化:** - メタデータテンプレートの`copyInstanceOnItemCopy`フィールドのサポートを追加 ([#572](https://github.com/box/box-node-sdk/pull/572)) **バグ修正:** - Webhook署名の検証を修正 ([#568](https://github.com/box/box-node-sdk/pull/568)) - セキュリティの脆弱性にパッチを適用するための依存関係の更新 ([#578](https://github.com/box/box-node-sdk/pull/578)) **Source:** [https://ja.developer.box.com/changelog/2021-04-16-box-node-sdk-v1370-released](https://ja.developer.box.com/changelog/2021-04-16-box-node-sdk-v1370-released) --- ### Box Node SDK `v1.37.1`のリリース **Type:** changelog | **Section:** Changelog Box Node SDK v1.37.1のリリース バグ修正: 不適切な用語: whitelistからallowlistへの変更 (#625) # Box Node SDK v1.37.1のリリース **バグ修正:** - 不適切な用語: `whitelist`から`allowlist`への変更 ([#625](https://github.com/box/box-node-sdk/pull/625)) **Source:** [https://ja.developer.box.com/changelog/2021-05-19-box-node-sdk-v1371-released](https://ja.developer.box.com/changelog/2021-05-19-box-node-sdk-v1371-released) --- ### Box Node SDK `v1.37.2`のリリース **Type:** changelog | **Section:** Changelog Box Node SDK v1.37.2のリリース バグ修正: 一部のTypeScript@typesを直接的な依存関係として移動することで、後方互換性の問題を修正 (#630) # Box Node SDK v1.37.2のリリース **バグ修正:** - 一部のTypeScript[`@types`](https://github.com/types)を直接的な依存関係として移動することで、後方互換性の問題を修正 ([#630](https://github.com/box/box-node-sdk/pull/630)) **Source:** [https://ja.developer.box.com/changelog/2021-05-20-box-node-sdk-v1372-released](https://ja.developer.box.com/changelog/2021-05-20-box-node-sdk-v1372-released) --- ### Box Node SDK `v1.38.0`のリリース **Type:** changelog | **Section:** Changelog Box Node SDK v1.38.0のリリース 新機能と機能強化: 管理者による招待のために機密性の高い言語イベントタイプを追加 (#648) BetterDocsを使用してJSDocsをTypeScriptに適合 (#646) ProxyAgent… # Box Node SDK v1.38.0のリリース **新機能と機能強化:** - 管理者による招待のために機密性の高い言語イベントタイプを追加 ([#648](https://github.com/box/box-node-sdk/pull/648)) - `BetterDocs`を使用して`JSDocs`を`TypeScript`に適合 ([#646](https://github.com/box/box-node-sdk/pull/646)) - `ProxyAgent`のインポートを動的に変更 ([#641](https://github.com/box/box-node-sdk/pull/641)) - リテンションの対象となっているファイルおよびファイルバージョンを取得するための新しいAPI ([#585](https://github.com/box/box-node-sdk/pull/585)) **バグ修正:** - BuffersおよびReadableストリームを除くConfigを強く固定 ([#651](https://github.com/box/box-node-sdk/pull/651)) - `src/managers/search.ts`のドキュメントの誤字を修正 ([#649](https://github.com/box/box-node-sdk/pull/649)) - ドキュメントのリンク切れを更新 ([#647](https://github.com/box/box-node-sdk/pull/647)) - `exchangeToken`関数の型注釈を修正 ([#645](https://github.com/box/box-node-sdk/pull/645)) - ファイルの`getThumbnail` APIのサポートを終了して`getRepresentationContent`を推奨 ([#627](https://github.com/box/box-node-sdk/pull/627)) **Source:** [https://ja.developer.box.com/changelog/2021-08-06-box-node-sdk-v1380-released](https://ja.developer.box.com/changelog/2021-08-06-box-node-sdk-v1380-released) --- ### Box Node SDK `v1.39.0`のリリース **Type:** changelog | **Section:** Changelog Box Node SDK v1.39.0のリリース 新機能と機能強化: Box Sign APIのサポートを追加 (#658) TS Importsを強化 (#656) # Box Node SDK v1.39.0のリリース **新機能と機能強化:** - Box Sign APIのサポートを追加 ([#658](https://github.com/box/box-node-sdk/pull/658)) - TS Importsを強化 ([#656](https://github.com/box/box-node-sdk/pull/656)) **Source:** [https://ja.developer.box.com/changelog/2021-08-30-box-node-sdk-v1390-released](https://ja.developer.box.com/changelog/2021-08-30-box-node-sdk-v1390-released) --- ### Box Node SDK `v2.0.0`のリリース **Type:** changelog | **Section:** Changelog Box Node SDK v2.0.0のリリース 重要な変更: Node 6、7のサポートを終了 (#670) 新機能と機能強化: is_external_collab_restrictedユーザープロパティのサポートを追加 (#668) プロキシエージェントを4.0.0から… # Box Node SDK v2.0.0のリリース **重要な変更:** - Node 6、7のサポートを終了 ([#670](https://github.com/box/box-node-sdk/pull/670)) **新機能と機能強化:** - `is_external_collab_restricted`ユーザープロパティのサポートを追加 ([#668](https://github.com/box/box-node-sdk/pull/668)) - プロキシエージェントを4.0.0から5.0.0に昇格 ([#664](https://github.com/box/box-node-sdk/pull/664)) **Source:** [https://ja.developer.box.com/changelog/2021-09-29-box-node-sdk-v200-released](https://ja.developer.box.com/changelog/2021-09-29-box-node-sdk-v200-released) --- ### Box Node SDK `v2.1.0`のリリース **Type:** changelog | **Section:** Changelog Box Node SDK v2.1.0のリリース 新機能と機能強化 クライアント資格情報許可による認証方法 (#709) (fbf4e80) メタデータクエリ実行時のindex_nameのサポート終了 (#686) (e01cc65) テスト: Jest… # Box Node SDK v2.1.0のリリース ### 新機能と機能強化 - クライアント資格情報許可による認証方法 ([#709](https://github.com/box/box-node-sdk/issues/709)) ([`fbf4e80`](https://github.com/box/box-node-sdk/commit/fbf4e80648821e38479b24bf489e7d222ae6c18f)) - メタデータクエリ実行時の`index_name`のサポート終了 ([#686](https://github.com/box/box-node-sdk/issues/686)) ([`e01cc65`](https://github.com/box/box-node-sdk/commit/e01cc650e4e793955be543e93928ad82a3254492)) - **テスト:** Jestによるテストのサポートを追加 ([#676](https://github.com/box/box-node-sdk/issues/676)) ([`1a11759`](https://github.com/box/box-node-sdk/commit/1a11759db999510c69d6a27f7becd565620bb000)) ### バグ修正 - クライアント資格情報許可による認証方法でトークンのダウンスコープをサポート ([#710](https://github.com/box/box-node-sdk/issues/710)) ([`730368f`](https://github.com/box/box-node-sdk/commit/730368f410ff56e9a8c90feea2192b29c08df198)) - 整数ではなく浮動小数点にJWT有効期限フィールドを修正 ([#715](https://github.com/box/box-node-sdk/issues/715)) ([`7e950f1`](https://github.com/box/box-node-sdk/commit/7e950f1265a52ce251c42a186c8196089a9ed858))、[#713](https://github.com/box/box-node-sdk/issues/713)をクローズ **Source:** [https://ja.developer.box.com/changelog/2022-03-28-box-node-sdk-v210-released](https://ja.developer.box.com/changelog/2022-03-28-box-node-sdk-v210-released) --- ### Box Node SDK `v2.10.0`のリリース **Type:** changelog | **Section:** Changelog Box Node SDK v2.10.0のリリース 新機能と機能強化 情報バリアAPIのサポートを追加 (#822) (4814af3) SignRequestタイプとSignRequestCreateRequestタイプにnameフィールドとsignature_color… # Box Node SDK v2.10.0のリリース ### 新機能と機能強化 - 情報バリアAPIのサポートを追加 ([#822](https://github.com/box/box-node-sdk/issues/822)) ([`4814af3`](https://github.com/box/box-node-sdk/commit/4814af35c1741fbfe3fa03f8f0412ade8b38dfcc)) - `SignRequest`タイプと`SignRequestCreateRequest`タイプに`name`フィールドと`signature_color`フィールド、`SignRequestCreateSigner`タイプに`login_required`フィールドを追加 ([#822](https://github.com/box/box-node-sdk/issues/822)) ([`4814af3`](https://github.com/box/box-node-sdk/commit/4814af35c1741fbfe3fa03f8f0412ade8b38dfcc)) **Source:** [https://ja.developer.box.com/changelog/2023-05-11-box-node-sdk-v2100-released](https://ja.developer.box.com/changelog/2023-05-11-box-node-sdk-v2100-released) --- ### Box Node SDK `v2.2.0`のリリース **Type:** changelog | **Section:** Changelog Box Node SDK v2.2.0のリリース 新機能と機能強化 編集可能な共有リンク (#722) (f0c0135) # Box Node SDK v2.2.0のリリース ### 新機能と機能強化 - 編集可能な共有リンク ([#722](https://github.com/box/box-node-sdk/issues/722)) ([`f0c0135`](https://github.com/box/box-node-sdk/commit/f0c0135511fde46144e6c496432104321af443f6)) **Source:** [https://ja.developer.box.com/changelog/2022-04-20-box-node-sdk-v220-released](https://ja.developer.box.com/changelog/2022-04-20-box-node-sdk-v220-released) --- ### Box Node SDK `v2.3.0`のリリース **Type:** changelog | **Section:** Changelog Box Node SDK v2.3.0のリリース 新機能と機能強化 descriptionパラメータをuploadFileメソッドに追加 (#730) (2596584) バグ修正 不足していたjs-docsを共有リンクに追加 (#731) (3554d41) # Box Node SDK v2.3.0のリリース ### 新機能と機能強化 - `description`パラメータを`uploadFile`メソッドに追加 ([#730](https://github.com/box/box-node-sdk/issues/730)) ([`2596584`](https://github.com/box/box-node-sdk/commit/2596584dffb44c1995c8b6b3faa67564f4d32499)) ### バグ修正 - 不足していた`js-docs`を共有リンクに追加 ([#731](https://github.com/box/box-node-sdk/issues/731)) ([`3554d41`](https://github.com/box/box-node-sdk/commit/3554d41d9050e7a81224c35e3e2e257604a0b41b)) **Source:** [https://ja.developer.box.com/changelog/2022-04-28-box-node-sdk-v230-released](https://ja.developer.box.com/changelog/2022-04-28-box-node-sdk-v230-released) --- ### Box Node SDK `v2.4.0`のリリース **Type:** changelog | **Section:** Changelog Box Node SDK v2.4.0のリリース 新機能と機能強化 ファイルリクエストのサポートを追加 (#742) (30b2e76) admin_logs_streamingストリームタイプのサポートを追加 (#740) (406950a… # Box Node SDK v2.4.0のリリース ### 新機能と機能強化 - ファイルリクエストのサポートを追加 ([#742](https://github.com/box/box-node-sdk/issues/742)) ([`30b2e76`](https://github.com/box/box-node-sdk/commit/30b2e767c6c3af68e1463cc801914f9889dc593c)) - `admin_logs_streaming`ストリームタイプのサポートを追加 ([#740](https://github.com/box/box-node-sdk/issues/740)) ([`406950a`](https://github.com/box/box-node-sdk/commit/406950a03af54a022427e0532e889a61e0d25152)) ### バグ修正 - ストリームのクライアントエラーを適切に処理 ([#736](https://github.com/box/box-node-sdk/issues/736)) ([`12378d6`](https://github.com/box/box-node-sdk/commit/12378d6755c2e3cddcb79439cdcbbe8e1e61df13)) **Source:** [https://ja.developer.box.com/changelog/2022-07-13-box-node-sdk-v240-released](https://ja.developer.box.com/changelog/2022-07-13-box-node-sdk-v240-released) --- ### Box Node SDK `v2.5.0`のリリース **Type:** changelog | **Section:** Changelog Box Node SDK v2.5.0のリリース 新機能と機能強化 ユーザーアバターの更新と削除のサポートを追加 (#744) (aaf6175) バグ修正 OAuthを使用してトークンを生成する際のエラーを修正 (#750) (f826291)、#28… # Box Node SDK v2.5.0のリリース ### 新機能と機能強化 - ユーザーアバターの更新と削除のサポートを追加 ([#744](https://github.com/box/box-node-sdk/issues/744)) ([`aaf6175`](https://github.com/box/box-node-sdk/commit/aaf617528de5c61e19cfb25e28fe77c01532b9fa)) ### バグ修正 - OAuthを使用してトークンを生成する際のエラーを修正 ([#750](https://github.com/box/box-node-sdk/issues/750)) ([`f826291`](https://github.com/box/box-node-sdk/commit/f82629108a1af6c4d160de1976fd01fdf0d8dde3))、[#286](https://github.com/box/box-node-sdk/issues/286)をクローズ - テストファイルのlintエラーを修正 ([#747](https://github.com/box/box-node-sdk/issues/747)) ([`3b1e10d`](https://github.com/box/box-node-sdk/commit/3b1e10d206aa88a8bf99989bb7ff85776a9864a4)) **Source:** [https://ja.developer.box.com/changelog/2022-08-09-box-node-sdk-v250-released](https://ja.developer.box.com/changelog/2022-08-09-box-node-sdk-v250-released) --- ### Box Node SDK `v2.6.0`のリリース **Type:** changelog | **Section:** Changelog Box Node SDK v2.6.0のリリース 新機能と機能強化 署名リクエストにcontent_typeおよびredirect_urlフィールドを追加 (#758) (8abb9b6) 署名リクエストのWebhookを追加 (#760) (e92d1ab… # Box Node SDK v2.6.0のリリース ### 新機能と機能強化 - 署名リクエストに`content_type`および`redirect_url`フィールドを追加 ([#758](https://github.com/box/box-node-sdk/issues/758)) ([`8abb9b6`](https://github.com/box/box-node-sdk/commit/8abb9b602b13cd72c6c8de549d19756ae147b403)) - 署名リクエストのWebhookを追加 ([#760](https://github.com/box/box-node-sdk/issues/760)) ([`e92d1ab`](https://github.com/box/box-node-sdk/commit/e92d1abee5faf58166f4892d7b2e6bc3c6480ac6)) - アクセスのみのコラボレーションのサポートを追加 ([#759](https://github.com/box/box-node-sdk/issues/759)) ([`dd8261f`](https://github.com/box/box-node-sdk/commit/dd8261f970c207854058c3ed86ccabf9bec05ea8)) **Source:** [https://ja.developer.box.com/changelog/2022-09-23-box-node-sdk-v260-released](https://ja.developer.box.com/changelog/2022-09-23-box-node-sdk-v260-released) --- ### Box Node SDK `v2.7.0`のリリース **Type:** changelog | **Section:** Changelog Box Node SDK v2.7.0のリリース 新機能と機能強化 変更可能リテンションポリシーのサポートを追加し、リテンションポリシー割り当ての削除を有効化 (#769) (5e8c776) # Box Node SDK v2.7.0のリリース ### 新機能と機能強化 - 変更可能リテンションポリシーのサポートを追加し、リテンションポリシー割り当ての削除を有効化 ([#769](https://github.com/box/box-node-sdk/issues/769)) ([`5e8c776`](https://github.com/box/box-node-sdk/commit/5e8c776fc94e9dcf313cc15c96e42fbffaf36b74)) **Source:** [https://ja.developer.box.com/changelog/2022-10-27-box-node-sdk-v270-released](https://ja.developer.box.com/changelog/2022-10-27-box-node-sdk-v270-released) --- ### Box Node SDK `v2.7.1`のリリース **Type:** changelog | **Section:** Changelog Box Node SDK v2.7.1のリリース バグ修正 欠落していたRetentionTypeをエクスポート (#774) (7e6b244) # Box Node SDK v2.7.1のリリース ### バグ修正 - 欠落していた`RetentionType`をエクスポート ([#774](https://github.com/box/box-node-sdk/issues/774)) ([`7e6b244`](https://github.com/box/box-node-sdk/commit/7e6b244ba63d363ecc921be570140c9e1ed1d032)) **Source:** [https://ja.developer.box.com/changelog/2022-10-28-box-node-sdk-v271-released](https://ja.developer.box.com/changelog/2022-10-28-box-node-sdk-v271-released) --- ### Box Node SDK `v2.7.2`のリリース **Type:** changelog | **Section:** Changelog Box Node SDK v2.7.2のリリース バグ修正 ファイルとフォルダの更新にfieldsクエリパラメータを追加 (#776) (a327deb) # Box Node SDK v2.7.2のリリース ### バグ修正 - ファイルとフォルダの更新に`fields`クエリパラメータを追加 ([#776](https://github.com/box/box-node-sdk/issues/776)) ([`a327deb`](https://github.com/box/box-node-sdk/commit/a327debc83d98a4190a5a16cf848417ea5714db9)) **Source:** [https://ja.developer.box.com/changelog/2022-11-10-box-node-sdk-v272-released](https://ja.developer.box.com/changelog/2022-11-10-box-node-sdk-v272-released) --- ### Box Node SDK `v2.8.0`のリリース **Type:** changelog | **Section:** Changelog Box Node SDK v2.8.0のリリース 新機能と機能強化 セッション終了 (#782) (7fb56c6) # Box Node SDK v2.8.0のリリース ### 新機能と機能強化 - セッション終了 ([#782](https://github.com/box/box-node-sdk/issues/782)) ([`7fb56c6`](https://github.com/box/box-node-sdk/commit/7fb56c625f8eb03e6a5354b67a0debfd9e4ad7c8)) **Source:** [https://ja.developer.box.com/changelog/2022-12-21-box-node-sdk-v280-released](https://ja.developer.box.com/changelog/2022-12-21-box-node-sdk-v280-released) --- ### Box Node SDK `v2.8.1`のリリース **Type:** changelog | **Section:** Changelog Box Node SDK v2.8.1のリリース バグ修正 getReadStreamの読み取りの遅延を修正 (#790) (6bfc1ee) # Box Node SDK v2.8.1のリリース ### バグ修正 - `getReadStream`の読み取りの遅延を修正 ([#790](https://github.com/box/box-node-sdk/issues/790)) ([`6bfc1ee`](https://github.com/box/box-node-sdk/commit/6bfc1eebeb9a31606ff96127eeb1ad03d2f13d9c)) **Source:** [https://ja.developer.box.com/changelog/2023-01-05-box-node-sdk-v281-released](https://ja.developer.box.com/changelog/2023-01-05-box-node-sdk-v281-released) --- ### Box Node SDK `v2.9.0`のリリース **Type:** changelog | **Section:** Changelog Box Node SDK v2.9.0のリリース 新機能と機能強化 retention-policyとretention-policy-assignmentの新しいフィールド (#803) (f14ba84) バグ修正 tos… # Box Node SDK v2.9.0のリリース ### 新機能と機能強化 - `retention-policy`と`retention-policy-assignment`の新しいフィールド ([#803](https://github.com/box/box-node-sdk/issues/803)) ([`f14ba84`](https://github.com/box/box-node-sdk/commit/f14ba84013985513854ad396581d085d1d4f0255)) ### バグ修正 - `tos`ステータスが存在しない場合に空のオブジェクトを返す ([#797](https://github.com/box/box-node-sdk/issues/797)) ([`12fd9b0`](https://github.com/box/box-node-sdk/commit/12fd9b053707471722f53cd1760c8cf59451fe8d)) **Source:** [https://ja.developer.box.com/changelog/2023-04-19-box-node-sdk-v290-released](https://ja.developer.box.com/changelog/2023-04-19-box-node-sdk-v290-released) --- ### Box Node SDK `v3.0.0`のリリース **Type:** changelog | **Section:** Changelog Box Node SDK v3.0.0のリリース このリリースの最も重要な変更は、バージョン12未満のNodeのサポートの終了とNode 12からNode 16へのサポート環境の変更です。 重大な変更 use_indexの使用を削除 (#812) (d56799a… # Box Node SDK v3.0.0のリリース このリリースの最も重要な変更は、**バージョン12未満のNodeのサポートの終了**と**Node 12からNode 16へのサポート環境**の変更です。 ### 重大な変更 - `use_index`の使用を削除 ([#812](https://github.com/box/box-node-sdk/pull/812)) ([`d56799a`](https://github.com/box/box-node-sdk/commit/d56799a61f42265d7785f99e92a449c58d125aef)) - 非推奨の`BoxClient.batch()`および`BoxClient.batchExec()`メソッドを削除 - 非推奨の`CollaborationWhitelist`クラスを削除、代わりに`CollaborationAllowlist`を使用 - 非推奨の`CollaborationAllowlist.getWhitelistedDomain()`メソッドを削除、代わりに`CollaborationAllowlist.getAllowlistedDomain()`を使用 - 非推奨の`CollaborationAllowlist.getAllWhitelistedDomains()`メソッドを削除、代わりに`CollaborationAllowlist.getAllAllowlistedDomains()`を使用 - 非推奨の`Files.getThumbnail(fileID: string, options?: Record<string, any>, callback?: Function)`メソッドを削除、代わりに`Files.getRepresentationContent( fileID, representationType, options, callback)`を使用 移行の詳細は[こちら](https://github.com/box/box-node-sdk/blob/v3.0.0/docs/upgrade/2.x.x%20to%203.x.x.md)で確認できます。 ### 依存関係のアップグレード - `jsonwebtoken`を8.5.1から9.0.0に昇格 ([#802](https://github.com/box/box-node-sdk/pull/802)) ([`5b1d4e9`](https://github.com/box/box-node-sdk/pull/828/commits/5b1d4e9ec557c14c1d27695733cc0bcae49061cb)) - `vm2`を3.9.11から3.9.19に昇格 ([#826](https://github.com/box/box-node-sdk/pull/826)) ([`220df76`](https://github.com/box/box-node-sdk/commit/220df765080bc27c91daed51ac46620f6bc8b9ed)) **Source:** [https://ja.developer.box.com/changelog/2023-05-23-box-node-sdk-v300-released](https://ja.developer.box.com/changelog/2023-05-23-box-node-sdk-v300-released) --- ### Box Node SDK `v3.1.0`のリリース **Type:** changelog | **Section:** Changelog Box Node SDK v3.1.0のリリース 新機能と機能強化 統合マッピングAPIのサポートを追加 (#831) (a525327) バグ修正 コラボレーションの作成用にuserIdとgroupIdのタイプを修正 (#833) (f803ff8)、#832をクローズ # Box Node SDK v3.1.0のリリース ### 新機能と機能強化 - 統合マッピングAPIのサポートを追加 ([#831](https://github.com/box/box-node-sdk/issues/831)) ([`a525327`](https://github.com/box/box-node-sdk/commit/a525327c1362628a0ffdb36cb4bf3346ca0e0153)) ### バグ修正 - コラボレーションの作成用に`userId`と`groupId`のタイプを修正 ([#833](https://github.com/box/box-node-sdk/issues/833)) ([`f803ff8`](https://github.com/box/box-node-sdk/commit/f803ff82330fd78a8dc4875452a21aab54686b2e))、[#832](https://github.com/box/box-node-sdk/issues/832)をクローズ **Source:** [https://ja.developer.box.com/changelog/2023-06-01-box-node-sdk-v310-released](https://ja.developer.box.com/changelog/2023-06-01-box-node-sdk-v310-released) --- ### Box Node SDK `v3.1.1`のリリース **Type:** changelog | **Section:** Changelog Box Node SDK v3.1.1のリリース 新機能と機能強化 proxy-agentをバージョン6.3.0に昇格 (845) (3f89f83) # Box Node SDK v3.1.1のリリース ### 新機能と機能強化 - proxy-agentをバージョン6.3.0に昇格 ([845]((https://github.com/box/box-node-sdk/pull/845))) ([`3f89f83`]((https://github.com/box/box-node-sdk/commit/3f89f83e939de5c1e6e48abbfb56212b56e70526))) **Source:** [https://ja.developer.box.com/changelog/2023-07-19-box-node-sdk-v311-released](https://ja.developer.box.com/changelog/2023-07-19-box-node-sdk-v311-released) --- ### Box Node SDK `v3.2.0`のリリース **Type:** changelog | **Section:** Changelog Box Node SDK v3.2.0のリリース 新機能と機能強化 Signテンプレートをサポート (#848) (18d3413) # Box Node SDK v3.2.0のリリース ### 新機能と機能強化 - Signテンプレートをサポート ([#848](https://github.com/box/box-node-sdk/issues/848)) ([`18d3413`](https://github.com/box/box-node-sdk/commit/18d3413afeddf43c62dfd0caf1279e61c99b6b83)) **Source:** [https://ja.developer.box.com/changelog/2023-09-07-box-node-sdk-v320-released](https://ja.developer.box.com/changelog/2023-09-07-box-node-sdk-v320-released) --- ### Box Node SDK `v3.2.1`のリリース **Type:** changelog | **Section:** Changelog Box Node SDK v3.2.1のリリース バグ修正 tough-cookieの依存関係を上書き (#852) (99df873) # Box Node SDK v3.2.1のリリース ### バグ修正 - tough-cookieの依存関係を上書き ([#852](https://github.com/box/box-node-sdk/issues/852)) ([`99df873`](https://github.com/box/box-node-sdk/commit/99df873e1a1dad4a0073d53b4ed57c0eeb859401)) **Source:** [https://ja.developer.box.com/changelog/2023-10-06-box-node-sdk-v321-released](https://ja.developer.box.com/changelog/2023-10-06-box-node-sdk-v321-released) --- ### Box Node SDK `v3.3.0`のリリース **Type:** changelog | **Section:** Changelog Box Node SDK v3.3.0のリリース 新機能と機能強化 requestライブラリを@cypress/requestに置き換え (#860) (d365ae8) バグ修正 承認関数のコールバックをオプションとしてマーク (#858) (55f22fe) # Box Node SDK v3.3.0のリリース ### 新機能と機能強化 - `request`ライブラリを`@cypress/request`に置き換え ([#860](https://github.com/box/box-node-sdk/issues/860)) ([`d365ae8`](https://github.com/box/box-node-sdk/commit/d365ae8368c549ecdceb7dd5b928904fd3c58978)) ### バグ修正 - 承認関数のコールバックをオプションとしてマーク ([#858](https://github.com/box/box-node-sdk/issues/858)) ([`55f22fe`](https://github.com/box/box-node-sdk/commit/55f22fec7d7d35e487f3fb51bc9bbd3e848842ab)) **Source:** [https://ja.developer.box.com/changelog/2023-10-26-box-node-sdk-v330-released](https://ja.developer.box.com/changelog/2023-10-26-box-node-sdk-v330-released) --- ### Box Node SDK `v3.4.0`のリリース **Type:** changelog | **Section:** Changelog Box Node SDK v3.4.0のリリース 新機能と機能強化 PassThroughをスキップするためのリクエストオプションを追加 (#863) (726db45) # Box Node SDK v3.4.0のリリース ### 新機能と機能強化 - `PassThrough`をスキップするためのリクエストオプションを追加 ([#863](https://github.com/box/box-node-sdk/issues/863)) ([`726db45`](https://github.com/box/box-node-sdk/commit/726db45cfbb992e545fe2865283df63c898656ac)) **Source:** [https://ja.developer.box.com/changelog/2023-11-03-box-node-sdk-v340-released](https://ja.developer.box.com/changelog/2023-11-03-box-node-sdk-v340-released) --- ### Box Node SDK `v3.4.1`のリリース **Type:** changelog | **Section:** Changelog Box Node SDK v3.4.1のリリース バグ修正 proxy-agentの使用を更新、Node 12のサポートを終了 (#865) (e229d3f) # Box Node SDK v3.4.1のリリース ### バグ修正 - `proxy-agent`の使用を更新、Node 12のサポートを終了 ([#865](https://github.com/box/box-node-sdk/issues/865)) ([`e229d3f`](https://github.com/box/box-node-sdk/commit/e229d3f93de350c00768528a1c0d3a6ecfc697a9)) **Source:** [https://ja.developer.box.com/changelog/2023-11-03-box-node-sdk-v341-released](https://ja.developer.box.com/changelog/2023-11-03-box-node-sdk-v341-released) --- ### Box Node SDK `v3.4.2`のリリース **Type:** changelog | **Section:** Changelog Box Node SDK v3.4.2のリリース バグ修正 proxy-agentを修正 (#867) (3de7586) # Box Node SDK v3.4.2のリリース ### バグ修正 - `proxy-agent`を修正 ([#867](https://github.com/box/box-node-sdk/issues/867)) ([`3de7586`](https://github.com/box/box-node-sdk/commit/3de7586e44dbb7c8e1bff8f34471964805c810f5)) **Source:** [https://ja.developer.box.com/changelog/2023-11-08-box-node-sdk-v342-released](https://ja.developer.box.com/changelog/2023-11-08-box-node-sdk-v342-released) --- ### Box Node SDK `v3.5.0`のリリース **Type:** changelog | **Section:** Changelog Box Node SDK v3.5.0のリリース 新機能と機能強化 署名リクエストグループ (#870) (11bf5d2) バグ修正 proxy-agentを6.4.0に昇格 (#874) (55a8a0b) 分類の削除に関する記述を削除 (#869) (22384ab) # Box Node SDK v3.5.0のリリース ### 新機能と機能強化 - 署名リクエストグループ ([#870](https://github.com/box/box-node-sdk/issues/870)) ([`11bf5d2`](https://github.com/box/box-node-sdk/commit/11bf5d2db7e0cefc669aab99c8b65c632289ac46)) ### バグ修正 - proxy-agentを6.4.0に昇格 ([#874](https://github.com/box/box-node-sdk/issues/874)) ([`55a8a0b`](https://github.com/box/box-node-sdk/commit/55a8a0baebe151f4107fdbec0a1022e9534f88a4)) - 分類の削除に関する記述を削除 ([#869](https://github.com/box/box-node-sdk/issues/869)) ([`22384ab`](https://github.com/box/box-node-sdk/commit/22384abc3abbc35800cbcdea7c7eb9a452cc4859)) **Source:** [https://ja.developer.box.com/changelog/2024-02-19-box-node-sdk-v350-released](https://ja.developer.box.com/changelog/2024-02-19-box-node-sdk-v350-released) --- ### Box Node SDK `v3.5.1`のリリース **Type:** changelog | **Section:** Changelog Box Node SDK v3.5.1のリリース バグ修正 メタデータクエリメソッドのoptionsパラメータを修正 (#878) (7943420) # Box Node SDK v3.5.1のリリース ### バグ修正 - メタデータクエリメソッドの`options`パラメータを修正 ([#878](https://github.com/box/box-node-sdk/issues/878)) ([`7943420`](https://github.com/box/box-node-sdk/commit/79434209c572cd77c329d6008cda9837a9dba411)) **Source:** [https://ja.developer.box.com/changelog/2024-05-02-box-node-sdk-v351-released](https://ja.developer.box.com/changelog/2024-05-02-box-node-sdk-v351-released) --- ### Box Node SDK `v3.6.0`のリリース **Type:** changelog | **Section:** Changelog Box Node SDK v3.6.0のリリース 新機能と機能強化 安定したステータスに移行 (#880) (ae996ea) # Box Node SDK v3.6.0のリリース ### 新機能と機能強化 - 安定したステータスに移行 ([#880](https://github.com/box/box-node-sdk/issues/880)) ([`ae996ea`](https://github.com/box/box-node-sdk/commit/ae996eafd9e34de99119a7780384b90758908313)) **Source:** [https://ja.developer.box.com/changelog/2024-05-20-box-node-sdk-v360-released](https://ja.developer.box.com/changelog/2024-05-20-box-node-sdk-v360-released) --- ### Box Node SDK `v3.7.0`のリリース **Type:** changelog | **Section:** Changelog Box Node SDK v3.7.0のリリース 新機能と機能強化 AI APIをサポート (#883) (bb81e07) # Box Node SDK v3.7.0のリリース ### 新機能と機能強化 - AI APIをサポート ([#883](https://github.com/box/box-node-sdk/issues/883)) ([`bb81e07`](https://github.com/box/box-node-sdk/commit/bb81e074eb1017bd742c90159e6cf4e6ce9d9776)) **Source:** [https://ja.developer.box.com/changelog/2024-07-16-box-node-sdk-v370-released](https://ja.developer.box.com/changelog/2024-07-16-box-node-sdk-v370-released) --- ### Box Node SDK `v3.7.1`のリリース **Type:** changelog | **Section:** Changelog Box Node SDK v3.7.1のリリース バグ修正 ファイルをコピーする際のオプションのバージョンに型注釈を追加 (#885) (4f9312c) # Box Node SDK v3.7.1のリリース ### バグ修正 - ファイルをコピーする際のオプションのバージョンに型注釈を追加 ([#885](https://github.com/box/box-node-sdk/issues/885)) ([`4f9312c`](https://github.com/box/box-node-sdk/commit/4f9312c63138f8cf8e0a9e46a9e1345172dbdc6b)) **Source:** [https://ja.developer.box.com/changelog/2024-08-06-box-node-sdk-v371-released](https://ja.developer.box.com/changelog/2024-08-06-box-node-sdk-v371-released) --- ### Box Node SDK `v3.8.0`のリリース **Type:** changelog | **Section:** Changelog Box Node SDK v3.8.0のリリース 新機能と機能強化 AIエージェントをサポート (#887) (5b109ad) # Box Node SDK v3.8.0のリリース ### 新機能と機能強化 - AIエージェントをサポート ([#887](https://github.com/box/box-node-sdk/issues/887)) ([`5b109ad`](https://github.com/box/box-node-sdk/commit/5b109adbd506510fc83b1c90af13b063ddefab37)) **Source:** [https://ja.developer.box.com/changelog/2025-04-09-box-node-sdk-v380-released](https://ja.developer.box.com/changelog/2025-04-09-box-node-sdk-v380-released) --- ### Box Node SDK `v3.8.1`のリリース **Type:** changelog | **Section:** Changelog Box Node SDK v3.8.1のリリース バグ修正 HMAC署名に定数時間比較を使用 (#893) (d819efe) # Box Node SDK v3.8.1のリリース ### バグ修正 - HMAC署名に定数時間比較を使用 ([#893](https://github.com/box/box-node-sdk/issues/893)) ([`d819efe`](https://github.com/box/box-node-sdk/commit/d819efe663a59fce53412fbe153a76dd346d4536)) **Source:** [https://ja.developer.box.com/changelog/2025-06-11-box-node-sdk-v381-released](https://ja.developer.box.com/changelog/2025-06-11-box-node-sdk-v381-released) --- ### Box Node SDK `v3.8.2`のリリース **Type:** changelog | **Section:** Changelog Box Node SDK v3.8.2のリリース バグ修正 form-dataに関するCVE-2025-7783を解決するためにcypress/requestを昇格 (#904) (8e8d2da) # Box Node SDK v3.8.2のリリース ### バグ修正 - `form-data`に関する`CVE-2025-7783`を解決するために`cypress/request`を昇格 ([#904](https://github.com/box/box-node-sdk/issues/904)) ([`8e8d2da`](https://github.com/box/box-node-sdk/commit/8e8d2da58ab42bdfb9e5a49ca25e9b9fc50e0d61)) **Source:** [https://ja.developer.box.com/changelog/2025-07-29-box-node-sdk-v382-released](https://ja.developer.box.com/changelog/2025-07-29-box-node-sdk-v382-released) --- ### Box Platformの用語集 **Type:** changelog | **Section:** Changelog Box Platformの用語集 Box PlatformとBoxドキュメントにおけるエクスペリエンスの改善のため、Box Platformの用語集を作成しました。Boxのコンテンツベースおよびクラウドベースのソリューションでの作業を開始するために最も重要な用語や概念を確認できます。 # Box Platformの用語集 Box PlatformとBoxドキュメントにおけるエクスペリエンスの改善のため、[Box Platformの用語集](page/platform/box-glossary/)を作成しました。Boxのコンテンツベースおよびクラウドベースのソリューションでの作業を開始するために最も重要な用語や概念を確認できます。 包括的で詳細な用語リストにするため、このリストは定期的に更新される予定です。 ## サポート情報 問題がある場合やさらにガイドが必要な場合は、必要なサポートについて、Boxの[Developer Forum](https://forum.box.com/)に英語でリクエストを投稿してください。 **Source:** [https://ja.developer.box.com/changelog/2023-10-06-box-platform-glossary](https://ja.developer.box.com/changelog/2023-10-06-box-platform-glossary) --- ### Box Preview SDKに影響を及ぼす`PDF.js`の脆弱性 **Type:** changelog | **Section:** Changelog Box Preview SDKに影響を及ぼすPDF.jsの脆弱性 Box Preview SDKで使用されているPDF.jsライブラリでCVE-2024-4367の脆弱性が明らかになりました。この脆弱性により、PDF.jsタイプの欠陥が危険にさらされ、プレビューで開いたときに任意のJavaScriptの実行を許可するコードがチェックされます。 # Box Preview SDKに影響を及ぼすPDF.jsの脆弱性 [Box Preview SDK](https://github.com/box/box-content-preview/blob/master/README.md)で使用されている`PDF.js`ライブラリで`CVE-2024-4367`の脆弱性が明らかになりました。この脆弱性により、`PDF.js`タイプの欠陥が危険にさらされ、プレビューで開いたときに任意のJavaScriptの実行を許可するコードがチェックされます。 この脆弱性は、`4.1.392`以下のすべてのバージョンの`PDF.js`に存在するため、`2.106.0`未満のすべてのバージョンのPreview SDKに影響します。この脆弱性を軽減するには、アプリで使用されているPreview SDKを`2.106.0`以上にアップグレードしてください。 影響を受ける可能性があるユーザーとアプリケーション所有者全員に、メールで直接通知済みです。 ## サポート情報 問題がある場合やさらにガイドが必要な場合は、必要なサポートについて、Boxの[Developer Forum](https://forum.box.com/)に英語でリクエストを投稿してください。 **Source:** [https://ja.developer.box.com/changelog/2024-05-23-pdf-js-vulnerability](https://ja.developer.box.com/changelog/2024-05-23-pdf-js-vulnerability) --- ### Box Python SDK `v2.10.0`のリリース **Type:** changelog | **Section:** Changelog Box Python SDK v2.10.0のリリース 新機能と機能強化: メタデータテンプレートのcopyInstanceOnItemCopyフィールドのサポートを追加 (#546) actionパラメータとcompletion_rule… # Box Python SDK v2.10.0のリリース **新機能と機能強化:** - メタデータテンプレートの`copyInstanceOnItemCopy`フィールドのサポートを追加 ([#546](https://github.com/box/box-ios-sdk/pull/546)) - `action`パラメータと`completion_rule`パラメータを使用したタスクの作成を許可 ([#544](https://github.com/box/box-ios-sdk/pull/544)) - 圧縮機能を追加 ([#539](https://github.com/box/box-ios-sdk/pull/539)) **バグ修正:** - コラボレーションロールを所有者に更新する際のバグを修正 ([#536](https://github.com/box/box-ios-sdk/pull/536)) - `ints`を項目IDとして渡すことを許可 ([#530](https://github.com/box/box-ios-sdk/pull/530)) **Source:** [https://ja.developer.box.com/changelog/2020-10-02-box-python-sdk-v2100-released](https://ja.developer.box.com/changelog/2020-10-02-box-python-sdk-v2100-released) --- ### Box Python SDK `v2.11.0`のリリース **Type:** changelog | **Section:** Changelog Box Python SDK v2.11.0のリリース 新機能と機能強化: サムネイルを取得するためのメソッドの廃止および追加 (#572) # Box Python SDK v2.11.0のリリース **新機能と機能強化:** - サムネイルを取得するためのメソッドの廃止および追加 ([#572](https://github.com/box/box-python-sdk/pull/572)) **Source:** [https://ja.developer.box.com/changelog/2021-01-11-box-python-sdk-v2110-released](https://ja.developer.box.com/changelog/2021-01-11-box-python-sdk-v2110-released) --- ### Box Python SDK `v2.12.0`のリリース **Type:** changelog | **Section:** Changelog Box Python SDK v2.12.0のリリース 新機能と機能強化: メタデータクエリ機能を追加 (#574) フォルダロック機能を追加 (#581) include_recent_shared_linksフィールドの検索クエリサポートを追加 (#58… # Box Python SDK v2.12.0のリリース **新機能と機能強化:** - メタデータクエリ機能を追加 ([#574](https://github.com/box/box-python-sdk/pull/574)) - フォルダロック機能を追加 ([#581](https://github.com/box/box-python-sdk/pull/581)) - `include_recent_shared_links`フィールドの検索クエリサポートを追加 ([#582](https://github.com/box/box-python-sdk/pull/582)) - ドキュメントされたパラメータを使用して名前でフィルタをかけるために`get_groups()`を更新 ([#586](https://github.com/box/box-python-sdk/pull/586)) **Source:** [https://ja.developer.box.com/changelog/2021-04-16-box-python-sdk-v2120-released](https://ja.developer.box.com/changelog/2021-04-16-box-python-sdk-v2120-released) --- ### Box Python SDK `v2.12.1`のリリース **Type:** changelog | **Section:** Changelog Box Python SDK v2.12.1のリリース バグ修正: サムネイルレプリゼンテーションが見つからない場合のバグの修正 (#597) # Box Python SDK v2.12.1のリリース **バグ修正:** - サムネイルレプリゼンテーションが見つからない場合のバグの修正 ([#597](https://github.com/box/box-python-sdk/pull/597)) **Source:** [https://ja.developer.box.com/changelog/2021-06-16-box-python-sdk-v2121-released](https://ja.developer.box.com/changelog/2021-06-16-box-python-sdk-v2121-released) --- ### Box Python SDK `v2.13.0`のリリース **Type:** changelog | **Section:** Changelog Box Python SDK v2.13.0のリリース 新機能と機能強化: 不適切な用語の変更 (#609) Box Signのサポートを追加 (#617) バグ修正: 暗号化技術をバージョン3にアップグレード (#620) # Box Python SDK v2.13.0のリリース **新機能と機能強化:** - 不適切な用語の変更 ([#609](https://github.com/box/box-python-sdk/pull/609)) - Box Signのサポートを追加 ([#617](https://github.com/box/box-python-sdk/pull/617)) **バグ修正:** - 暗号化技術をバージョン3にアップグレード ([#620](https://github.com/box/box-python-sdk/pull/620)) **Source:** [https://ja.developer.box.com/changelog/2021-09-30-box-python-sdk-v2130-released](https://ja.developer.box.com/changelog/2021-09-30-box-python-sdk-v2130-released) --- ### Box Python SDK `v2.14.0`のリリース **Type:** changelog | **Section:** Changelog Box Python SDK v2.14.0のリリース 新機能と機能強化: イベントストリームに対するadmin_logs_streamingのサポートを追加 (#623) ファイルまたはフォルダへの共有リンクを作成するためのvanity_nameパラメータを追加 (#63… # Box Python SDK v2.14.0のリリース **新機能と機能強化:** - イベントストリームに対する`admin_logs_streaming`のサポートを追加 ([#623](https://github.com/box/box-python-sdk/pull/623)) - ファイルまたはフォルダへの共有リンクを作成するための`vanity_name`パラメータを追加 ([#637](https://github.com/box/box-python-sdk/pull/637)) - リテンションポリシー割り当てのために、リテンションの対象となるファイルおよびファイルバージョンの取得を追加 ([#633](https://github.com/box/box-python-sdk/pull/633)) - WebLinkクラスの基本の項目操作をサポート ([#639](https://github.com/box/box-python-sdk/pull/639)) **バグ修正:** - 暗号化技術をバージョン3.5.0未満に制限 ([#636](https://github.com/box/box-python-sdk/pull/636)) - ファイルのサムネイルを生成できないときの404エラーの発生を回避 ([#642](https://github.com/box/box-python-sdk/pull/642)) **Source:** [https://ja.developer.box.com/changelog/2021-12-08-box-python-sdk-v2140-released](https://ja.developer.box.com/changelog/2021-12-08-box-python-sdk-v2140-released) --- ### Box Python SDK `v2.9.0`のリリース **Type:** changelog | **Section:** Changelog Box Python SDK v2.9.0のリリース OAuthの例外処理を修正 パスパラメータのサニタイズを修正 # Box Python SDK v2.9.0のリリース - OAuthの例外処理を修正 - パスパラメータのサニタイズを修正 **Source:** [https://ja.developer.box.com/changelog/2020-06-23-box-python-sdk-v290-released](https://ja.developer.box.com/changelog/2020-06-23-box-python-sdk-v290-released) --- ### Box Python SDK `v3.0.0`のリリース **Type:** changelog | **Section:** Changelog Box Python SDK v3.0.0のリリース 重大な変更 Python 2.7のサポートを終了 (#645) 不足しているパラメータstream_position to get_admin_eventsメソッドを追加 (#648) Python 3.… # Box Python SDK v3.0.0のリリース **重大な変更** - Python 2.7のサポートを終了 ([#645](https://github.com/box/box-python-sdk/pull/645)) - 不足しているパラメータ`stream_position to get_admin_events`メソッドを追加 ([#648](https://github.com/box/box-python-sdk/pull/648)) - Python 3.5のサポートを終了 ([#654](https://github.com/box/box-python-sdk/pull/654)) - 不適切な用語を使用している非推奨のコードを削除 ([#651](https://github.com/box/box-python-sdk/pull/651)) - 一部の関数でキーワードのみの引数の使用を強制 ([#656](https://github.com/box/box-python-sdk/pull/656)) **新機能と機能強化:** - `six`ライブラリと`__future__` importを削除 ([#646](https://github.com/box/box-python-sdk/pull/646)) - メソッドのパラメータにタイプヒントを追加 ([#650](https://github.com/box/box-python-sdk/pull/650)) **バグ修正:** - `multi-input`の呼び出しに不足している`api_call`デコレータを追加 ([#653](https://github.com/box/box-python-sdk/pull/653)) - `mypy`がタイプヒントを認識できるように`py.typed`ファイルを追加 ([#657](https://github.com/box/box-python-sdk/pull/657)) **Source:** [https://ja.developer.box.com/changelog/2022-01-17-box-python-sdk-v300-released](https://ja.developer.box.com/changelog/2022-01-17-box-python-sdk-v300-released) --- ### Box Python SDK `v3.0.1`のリリース **Type:** changelog | **Section:** Changelog Box Python SDK v3.0.1のリリース バグ修正: sphinxをテスト要件に移動 (#662) # Box Python SDK v3.0.1のリリース **バグ修正:** - sphinxをテスト要件に移動 ([#662](https://github.com/box/box-python-sdk/pull/662)) **Source:** [https://ja.developer.box.com/changelog/2022-01-26-box-python-sdk-v301-released](https://ja.developer.box.com/changelog/2022-01-26-box-python-sdk-v301-released) --- ### Box Python SDK `v3.1.0`のリリース **Type:** changelog | **Section:** Changelog Box Python SDK v3.1.0のリリース 新機能と機能強化 Python 3.10のサポートを追加 (#692) (d4aed82) Python 3.8、Python 3.9、pypy-3.7、およびpypy-3.8のサポートを追加 (#689) (0aa94cc… # Box Python SDK v3.1.0のリリース ### 新機能と機能強化 - Python 3.10のサポートを追加 ([#692](https://github.com/box/box-python-sdk/issues/692)) ([`d4aed82`](https://github.com/box/box-python-sdk/commit/d4aed82831af97305bace9a4588d27b23856c306)) - Python 3.8、Python 3.9、`pypy-3.7`、および`pypy-3.8`のサポートを追加 ([#689](https://github.com/box/box-python-sdk/issues/689)) ([`0aa94cc`](https://github.com/box/box-python-sdk/commit/0aa94cc8a5c4db0fc204b27a60690b73c98a89cb)) - ファイル/フォルダの`MDQ`にある`use_index`パラメータを廃止 ([#666](https://github.com/box/box-python-sdk/issues/666)) ([`2595720`](https://github.com/box/box-python-sdk/commit/25957204b82c878e15dc3d118505a741171e9772)) - 外部パッケージの`mock`をPython標準ライブラリの`unittest.mock`に置き換え ([#697](https://github.com/box/box-python-sdk/issues/697)) ([`6fd6366`](https://github.com/box/box-python-sdk/commit/6fd63667aa7da4c794b4fb880d5c2949efe0073f)) - 暗号化技術ライブラリを最新バージョンにアップグレード ([#668](https://github.com/box/box-python-sdk/issues/668)) ([`9c94d08`](https://github.com/box/box-python-sdk/commit/9c94d0878515dc75c1f267e2fb1f189a852772b6))、[#667](https://github.com/box/box-python-sdk/issues/667)をクローズ ### バグ修正 - 再試行の上限に達したときに`UploadSession.commit`によって`None`が返される ([#696](https://github.com/box/box-python-sdk/issues/696)) ([`9456fe0`](https://github.com/box/box-python-sdk/commit/9456fe0124f4ac4e9c8a7bcc49039f07f310c477)) - `create_upload_session`に欠落している`api_call`デコレータを追加 ([#686](https://github.com/box/box-python-sdk/issues/686)) ([`3510d3a`](https://github.com/box/box-python-sdk/commit/3510d3ac085767205854014ecef80fd078d71773)) - 分割アップロードを修正 ([#673](https://github.com/box/box-python-sdk/issues/673)) ([`2605fd7`](https://github.com/box/box-python-sdk/commit/2605fd782396ad6e42bd11c10f846e771634b7a0))、[#671](https://github.com/box/box-python-sdk/issues/671)をクローズ **Source:** [https://ja.developer.box.com/changelog/2022-02-16-box-python-sdk-v310-released](https://ja.developer.box.com/changelog/2022-02-16-box-python-sdk-v310-released) --- ### Box Python SDK `v3.10.0`のリリース **Type:** changelog | **Section:** Changelog Box Python SDK v3.10.0のリリース 新機能と機能強化 安定したステータスに移行 (#872) (6203606) バグ修正 位置ヘッダーが存在しない場合の例外タイプを変更 (#871) (8c5e0ec) OAuthのaccess_token… # Box Python SDK v3.10.0のリリース ### 新機能と機能強化 - 安定したステータスに移行 ([#872](https://github.com/box/box-python-sdk/issues/872)) ([`6203606`](https://github.com/box/box-python-sdk/commit/620360607a51ee302cde61401db1424c9bf48d81)) ### バグ修正 - 位置ヘッダーが存在しない場合の例外タイプを変更 ([#871](https://github.com/box/box-python-sdk/issues/871)) ([`8c5e0ec`](https://github.com/box/box-python-sdk/commit/8c5e0eca7e494baa8138dceededa2009abc1717b)) - OAuthの`access_token`の注釈を修正 ([#855](https://github.com/box/box-python-sdk/issues/855)) ([`804780e`](https://github.com/box/box-python-sdk/commit/804780e4c8d410590fa20cdb6dd35224d59d2ec0)) - リテンションポリシー統合テストを修正 ([#867](https://github.com/box/box-python-sdk/issues/867)) ([`8e0d640`](https://github.com/box/box-python-sdk/commit/8e0d6406f26be87799838b0aa57acd62c79d59a2)) - 分類の削除に関する記述を削除 ([#861](https://github.com/box/box-python-sdk/issues/861)) ([`393cfef`](https://github.com/box/box-python-sdk/commit/393cfefa57e729f34221a4e5923a4a50532f4013)) - 例外ファイル取得のダウンロードURLを更新 ([#866](https://github.com/box/box-python-sdk/issues/866)) ([`94dcbcd`](https://github.com/box/box-python-sdk/commit/94dcbcd490d98ff19afd38c9880de8022ad2ec89)) **Source:** [https://ja.developer.box.com/changelog/2024-05-22-box-python-sdk-v3100-released](https://ja.developer.box.com/changelog/2024-05-22-box-python-sdk-v3100-released) --- ### Box Python SDK `v3.11.0`のリリース **Type:** changelog | **Section:** Changelog Box Python SDK v3.11.0のリリース 新機能と機能強化 分割アップロードにアップロードセッションurlsを使用 (#875) (c67b03c) # Box Python SDK v3.11.0のリリース ### 新機能と機能強化 - 分割アップロードにアップロードセッション`urls`を使用 ([#875](https://github.com/box/box-python-sdk/issues/875)) ([`c67b03c`](https://github.com/box/box-python-sdk/commit/c67b03c7d88533773d62d72f0b626031805d61eb)) **Source:** [https://ja.developer.box.com/changelog/2024-06-07-box-python-sdk-v3110-released](https://ja.developer.box.com/changelog/2024-06-07-box-python-sdk-v3110-released) --- ### Box Python SDK `v3.12.0`のリリース **Type:** changelog | **Section:** Changelog Box Python SDK v3.12.0のリリース 新機能と機能強化 必須パラメータが異なるcreate_sign_request関数を追加 (#878) (d972f54) Box AI機能をサポート (#877) (3026d2a) # Box Python SDK v3.12.0のリリース ### 新機能と機能強化 - 必須パラメータが異なるcreate_sign_request関数を追加 ([#878](https://github.com/box/box-python-sdk/issues/878)) ([`d972f54`](https://github.com/box/box-python-sdk/commit/d972f54dcf9962c6b911422793a682d8f6289f9e)) - Box AI機能をサポート ([#877](https://github.com/box/box-python-sdk/issues/877)) ([`3026d2a`](https://github.com/box/box-python-sdk/commit/3026d2ab9932cd07aa9ff15a3ac3c3c14d3089b0)) **Source:** [https://ja.developer.box.com/changelog/2024-08-06-box-python-sdk-v3120-released](https://ja.developer.box.com/changelog/2024-08-06-box-python-sdk-v3120-released) --- ### Box Python SDK `v3.13.0`のリリース **Type:** changelog | **Section:** Changelog Box Python SDK v3.13.0のリリース 新機能と機能強化 AIエージェントのデフォルトのサポートを追加 (#883) (c1010e0) # Box Python SDK v3.13.0のリリース ### 新機能と機能強化 - AIエージェントのデフォルトのサポートを追加 ([#883](https://github.com/box/box-python-sdk/issues/883)) ([`c1010e0`](https://github.com/box/box-python-sdk/commit/c1010e0349847586a9f00046570e975ec48eb0c5)) **Source:** [https://ja.developer.box.com/changelog/2024-08-22-box-python-sdk-v3130-released](https://ja.developer.box.com/changelog/2024-08-22-box-python-sdk-v3130-released) --- ### Box Python SDK `v3.14.0`のリリース **Type:** changelog | **Section:** Changelog Box Python SDK v3.14.0のリリース 新機能と機能強化 uploadメソッドにstream_file_contentパラメータを追加 (#890) (0e63c00) # Box Python SDK v3.14.0のリリース ### 新機能と機能強化 - uploadメソッドに`stream_file_content`パラメータを追加 ([#890](https://github.com/box/box-python-sdk/issues/890)) ([`0e63c00`](https://github.com/box/box-python-sdk/commit/0e63c002ee17618c08200c12caae4bb3890b1e90)) **Source:** [https://ja.developer.box.com/changelog/2025-04-09-box-python-sdk-v3140-released](https://ja.developer.box.com/changelog/2025-04-09-box-python-sdk-v3140-released) --- ### Box Python SDK `v3.2.0`のリリース **Type:** changelog | **Section:** Changelog Box Python SDK v3.2.0のリリース 新機能と機能強化 リテンションの対象となるファイル用にdisposition_atフィールドの設定を追加 (#710) (91b1373) クライアント資格情報許可による認証方法のサポートを追加 (#705) (d33d16d… # Box Python SDK v3.2.0のリリース ### 新機能と機能強化 - リテンションの対象となるファイル用に`disposition_at`フィールドの設定を追加 ([#710](https://github.com/box/box-python-sdk/issues/710)) ([`91b1373`](https://github.com/box/box-python-sdk/commit/91b13730a0beef2cf2a8a8c71087b11557fa5982)) - クライアント資格情報許可による認証方法のサポートを追加 ([#705](https://github.com/box/box-python-sdk/issues/705)) ([`d33d16d`](https://github.com/box/box-python-sdk/commit/d33d16db656cb5578f057a7e24f5396d635b5361)) ### バグ修正 - 欠落している`box_sign`オブジェクトを`__all__`リストに追加 ([#708](https://github.com/box/box-python-sdk/issues/708)) ([`5d80481`](https://github.com/box/box-python-sdk/commit/5d8048116640fa672d6a1d700a6c1111faf87bb9)) - `jwt`インポートのエラーを修正 ([#711](https://github.com/box/box-python-sdk/issues/711)) ([`ee7bb6f`](https://github.com/box/box-python-sdk/commit/ee7bb6f1dc5aa65dbf6ffeb18ee130f765f7b49b)) **Source:** [https://ja.developer.box.com/changelog/2022-03-11-box-python-sdk-v320-released](https://ja.developer.box.com/changelog/2022-03-11-box-python-sdk-v320-released) --- ### Box Python SDK `v3.3.0`のリリース **Type:** changelog | **Section:** Changelog Box Python SDK v3.3.0のリリース 新機能と機能強化 複数の日時形式のサポートを追加 (#722) (92364de) バグ修正 不足していたフィールドをmetadata templateフィールドに追加 (#719) (9e574a3)、#71… # Box Python SDK v3.3.0のリリース ### 新機能と機能強化 - 複数の日時形式のサポートを追加 ([#722](https://github.com/box/box-python-sdk/issues/722)) ([`92364de`](https://github.com/box/box-python-sdk/commit/92364de1e7c1eee1e85857546af65c307ca863a0)) ### バグ修正 - 不足していたフィールドをmetadata templateフィールドに追加 ([#719](https://github.com/box/box-python-sdk/issues/719)) ([`9e574a3`](https://github.com/box/box-python-sdk/commit/9e574a3e56f72c0e78a31ddda78bc11d36ff3516))、[#717](https://github.com/box/box-python-sdk/issues/717)をクローズ - upload_sessionのコミットで202の場合にNoneを戻す ([#718](https://github.com/box/box-python-sdk/issues/718)) ([`86a1856`](https://github.com/box/box-python-sdk/commit/86a185630e6cce8f742123c7340da08267621313))、[#715](https://github.com/box/box-python-sdk/issues/715)をクローズ **Source:** [https://ja.developer.box.com/changelog/2022-04-28-box-python-sdk-v330-released](https://ja.developer.box.com/changelog/2022-04-28-box-python-sdk-v330-released) --- ### Box Python SDK `v3.4.0`のリリース **Type:** changelog | **Section:** Changelog Box Python SDK v3.4.0のリリース 新機能と機能強化 ファイル用の編集可能な共有リンクのサポートを追加 (#737) (1396200) ユーザーアバターのアップロードと削除をサポート (#743) (fe00a9e) # Box Python SDK v3.4.0のリリース ### 新機能と機能強化 - ファイル用の編集可能な共有リンクのサポートを追加 ([#737](https://github.com/box/box-python-sdk/issues/737)) ([`1396200`](https://github.com/box/box-python-sdk/commit/1396200c24bf62de63f9cb7949af5997593b9fac)) - ユーザーアバターのアップロードと削除をサポート ([#743](https://github.com/box/box-python-sdk/issues/743)) ([`fe00a9e`](https://github.com/box/box-python-sdk/commit/fe00a9eb3434ee14bc4f01332d54c0272ed5f2d3)) **Source:** [https://ja.developer.box.com/changelog/2022-07-06-box-python-sdk-v340-released](https://ja.developer.box.com/changelog/2022-07-06-box-python-sdk-v340-released) --- ### Box Python SDK `v3.5.0`のリリース **Type:** changelog | **Section:** Changelog Box Python SDK v3.5.0のリリース 新機能と機能強化 署名リクエストにredirect_urlおよびdeclined_redirect_urlフィールドを追加 (#752) (5d1f60… # Box Python SDK v3.5.0のリリース ### 新機能と機能強化 - 署名リクエストに`redirect_url`および`declined_redirect_url`フィールドを追加 ([#752](https://github.com/box/box-python-sdk/issues/752)) ([`5d1f609`](https://github.com/box/box-python-sdk/commit/5d1f609ed4c2ddb24bd88ffac256a2809a012698)) - 変更可能リテンションポリシーサポートを追加し、リテンションポリシー割り当ての削除を有効化 ([#759](https://github.com/box/box-python-sdk/issues/759)) ([`847301b`](https://github.com/box/box-python-sdk/commit/847301b43be335365858a80420459dffaada4302)) - ファイルリクエストAPIのサポート ([#747](https://github.com/box/box-python-sdk/issues/747)) ([`71895e3`](https://github.com/box/box-python-sdk/commit/71895e33ff7cf339fd8e095a5393f04b86791d5a)) ### バグ修正 - ダウンロードしたファイルのコンテンツをログに記録しないよう修正 ([#760](https://github.com/box/box-python-sdk/issues/760)) ([`5d26431`](https://github.com/box/box-python-sdk/commit/5d264314f949c1f4d9136efd5cf8f13dd5897c05)) - 分割アップロード後のファイルのクローズ処理を修正 ([#761](https://github.com/box/box-python-sdk/issues/761)) ([`b433692`](https://github.com/box/box-python-sdk/commit/b433692ecc07d62d011785a557128c1780ea1647)) **Source:** [https://ja.developer.box.com/changelog/2022-09-23-box-python-sdk-v350-released](https://ja.developer.box.com/changelog/2022-09-23-box-python-sdk-v350-released) --- ### Box Python SDK `v3.5.1`のリリース **Type:** changelog | **Section:** Changelog Box Python SDK v3.5.1のリリース バグ修正 接続のリセットエラーが発生した場合に接続を更新 (#771) (bcaab27)、#756 #757 #763 #765 #766 #770をクローズ 一意のjtiクレームが必要というエラーが発生した場合にJWT… # Box Python SDK v3.5.1のリリース ### バグ修正 - 接続のリセットエラーが発生した場合に接続を更新 ([#771](https://github.com/box/box-python-sdk/issues/771)) ([`bcaab27`](https://github.com/box/box-python-sdk/commit/bcaab277c3cabba498076d066366abbaa5507904))、[#756](https://github.com/box/box-python-sdk/issues/756) [#757](https://github.com/box/box-python-sdk/issues/757) [#763](https://github.com/box/box-python-sdk/issues/763) [#765](https://github.com/box/box-python-sdk/issues/765) [#766](https://github.com/box/box-python-sdk/issues/766) [#770](https://github.com/box/box-python-sdk/issues/770)をクローズ - 一意の`jti`クレームが必要というエラーが発生した場合にJWT認証を再試行 ([#768](https://github.com/box/box-python-sdk/issues/768)) ([`878e958`](https://github.com/box/box-python-sdk/commit/878e958abfb01740656aaff42492777753e4c8ea)) - Python 3.10で動作するように`pyjtw`の依存関係を更新 ([#772](https://github.com/box/box-python-sdk/issues/772)) ([`b13c5cd`](https://github.com/box/box-python-sdk/commit/b13c5cd34105d3f774d3f6d35db7aaf51dd3e247)) **Source:** [https://ja.developer.box.com/changelog/2022-11-30-box-python-sdk-v351-released](https://ja.developer.box.com/changelog/2022-11-30-box-python-sdk-v351-released) --- ### Box Python SDK `v3.6.0`のリリース **Type:** changelog | **Section:** Changelog Box Python SDK v3.6.0のリリース 新機能と機能強化 ごみ箱の項目の取得にマーカーのサポートを追加 (#781) (e2d1846) プロキシ資格情報をサニタイズ (#782) (97fb5aa… # Box Python SDK v3.6.0のリリース ### 新機能と機能強化 - ごみ箱の項目の取得にマーカーのサポートを追加 ([#781](https://github.com/box/box-python-sdk/issues/781)) ([`e2d1846`](https://github.com/box/box-python-sdk/commit/e2d1846818aeccfcba2a2f09a5cd924c9f6cd534)) - プロキシ資格情報をサニタイズ ([#782](https://github.com/box/box-python-sdk/issues/782)) ([`97fb5aa`](https://github.com/box/box-python-sdk/commit/97fb5aa2ed72008570abb327269ecec150632af9)) ### バグ修正 - ユーザーサービス利用規約のステータスの空のリストを取得する際のインデックスエラーを修正 ([#780](https://github.com/box/box-python-sdk/issues/780)) ([`23d763a`](https://github.com/box/box-python-sdk/commit/23d763ac4ba592131c43eb0319929db25d041c30)) - 再試行が必要な例外を指定 ([#784](https://github.com/box/box-python-sdk/issues/784)) ([`833cd46`](https://github.com/box/box-python-sdk/commit/833cd46bafe774f19925f78600df90477bf07055)) **Source:** [https://ja.developer.box.com/changelog/2023-01-03-box-python-sdk-v360-released](https://ja.developer.box.com/changelog/2023-01-03-box-python-sdk-v360-released) --- ### Box Python SDK `v3.6.1`のリリース **Type:** changelog | **Section:** Changelog Box Python SDK v3.6.1のリリース バグ修正 接続リセットエラーが発生した場合に、CCGおよびJWT認証リクエストを再試行 (#790) (205997d)、#789をクローズ # Box Python SDK v3.6.1のリリース ### バグ修正 - 接続リセットエラーが発生した場合に、CCGおよびJWT認証リクエストを再試行 ([#790](https://github.com/box/box-python-sdk/issues/790)) ([`205997d`](https://github.com/box/box-python-sdk/commit/205997db9870395b9dd042854c4201338dcf925f))、[#789](https://github.com/box/box-python-sdk/issues/789)をクローズ **Source:** [https://ja.developer.box.com/changelog/2023-01-09-box-python-sdk-v361-released](https://ja.developer.box.com/changelog/2023-01-09-box-python-sdk-v361-released) --- ### Box Python SDK `v3.6.2`のリリース **Type:** changelog | **Section:** Changelog Box Python SDK v3.6.2のリリース バグ修正 Connection brokenおよびConnection resetリクエストエラーの再試行 (#794) (f1a0aa4) # Box Python SDK v3.6.2のリリース ### バグ修正 - `Connection broken`および`Connection reset`リクエストエラーの再試行 ([#794](https://github.com/box/box-python-sdk/issues/794)) ([`f1a0aa4`](https://github.com/box/box-python-sdk/commit/f1a0aa434369f06e80654a9f5c4b796100881aa6)) **Source:** [https://ja.developer.box.com/changelog/2023-02-07-box-python-sdk-v362-released](https://ja.developer.box.com/changelog/2023-02-07-box-python-sdk-v362-released) --- ### Box Python SDK `v3.7.0`のリリース **Type:** changelog | **Section:** Changelog Box Python SDK v3.7.0のリリース 新機能と機能強化 retention_policiesとretention_policy_assignmentsに省略可能な新しいフィールドを追加 (#803) (8b72f7e… # Box Python SDK v3.7.0のリリース ### 新機能と機能強化 - `retention_policies`と`retention_policy_assignments`に省略可能な新しいフィールドを追加 ([#803](https://github.com/box/box-python-sdk/issues/803)) ([`8b72f7e`](https://github.com/box/box-python-sdk/commit/8b72f7e992bce676723a40ac12bde06c8cca3bfb)) - 分割アップロードにマルチスレッドを使用 ([#800](https://github.com/box/box-python-sdk/issues/800)) ([`506ce0d`](https://github.com/box/box-python-sdk/commit/506ce0d1e72ab4eeb6c5933a32c753e232a2f624)) **Source:** [https://ja.developer.box.com/changelog/2023-03-08-box-python-sdk-v370-released](https://ja.developer.box.com/changelog/2023-03-08-box-python-sdk-v370-released) --- ### Box Python SDK `v3.7.1`のリリース **Type:** changelog | **Section:** Changelog Box Python SDK v3.7.1のリリース バグ修正 ドキュメントに従って、リーガルホールドの作成における日付のフィルタのパラメータ名を変更 (#810) (f52c66a) # Box Python SDK v3.7.1のリリース ### バグ修正 - ドキュメントに従って、リーガルホールドの作成における日付のフィルタのパラメータ名を変更 ([#810](https://github.com/box/box-python-sdk/issues/810)) ([`f52c66a`](https://github.com/box/box-python-sdk/commit/f52c66a8a8399a776493537f692460ace2995e40)) **Source:** [https://ja.developer.box.com/changelog/2023-04-18-box-python-sdk-v371-released](https://ja.developer.box.com/changelog/2023-04-18-box-python-sdk-v371-released) --- ### Box Python SDK `v3.7.2`のリリース **Type:** changelog | **Section:** Changelog Box Python SDK v3.7.2のリリース バグ修正 urllib3の古いバージョンを使用 (#815) (ee29aa3) # Box Python SDK v3.7.2のリリース ### バグ修正 - `urllib3`の古いバージョンを使用 ([#815](https://github.com/box/box-python-sdk/issues/815)) ([`ee29aa3`](https://github.com/box/box-python-sdk/commit/ee29aa3fcf9ac71e9866913a87414cf625c0b805)) **Source:** [https://ja.developer.box.com/changelog/2023-05-26-box-python-sdk-v372-released](https://ja.developer.box.com/changelog/2023-05-26-box-python-sdk-v372-released) --- ### Box Python SDK `v3.7.3`のリリース **Type:** changelog | **Section:** Changelog Box Python SDK v3.7.3のリリース バグ修正 ログ記録が非アクティブな場合にログ記録用のデータ処理を停止し、json形式のレスポンスをキャッシュ (#824) (3079171) # Box Python SDK v3.7.3のリリース ### バグ修正 - ログ記録が非アクティブな場合にログ記録用のデータ処理を停止し、`json`形式のレスポンスをキャッシュ ([#824](https://github.com/box/box-python-sdk/issues/824)) ([`3079171`](https://github.com/box/box-python-sdk/commit/3079171f8dfc1a4c85f8587e8ce90e8fbd826ee4)) **Source:** [https://ja.developer.box.com/changelog/2023-07-07-box-python-sdk-v373-released](https://ja.developer.box.com/changelog/2023-07-07-box-python-sdk-v373-released) --- ### Box Python SDK `v3.8.0`のリリース **Type:** changelog | **Section:** Changelog Box Python SDK v3.8.0のリリース 新機能と機能強化 collaborationのすべてのフィールドの更新をサポート (#829) (6dc7ecc) # Box Python SDK v3.8.0のリリース ### 新機能と機能強化 - `collaboration`のすべてのフィールドの更新をサポート ([#829](https://github.com/box/box-python-sdk/issues/829)) ([`6dc7ecc`](https://github.com/box/box-python-sdk/commit/6dc7ecc6f9c94e7531c4147a3645927b85928b2c)) **Source:** [https://ja.developer.box.com/changelog/2023-07-25-box-python-sdk-v380-released](https://ja.developer.box.com/changelog/2023-07-25-box-python-sdk-v380-released) --- ### Box Python SDK `v3.8.1`のリリース **Type:** changelog | **Section:** Changelog Box Python SDK v3.8.1のリリース バグ修正 JSONレスポンス検証の再試行戦略を修正 (#831) (69834eb) # Box Python SDK v3.8.1のリリース ### バグ修正 - JSONレスポンス検証の再試行戦略を修正 ([#831](https://github.com/box/box-python-sdk/issues/831)) ([`69834eb`](https://github.com/box/box-python-sdk/commit/69834eb4c91a5aa4bc294a9fa49ecf753979d029)) **Source:** [https://ja.developer.box.com/changelog/2023-08-01-box-python-sdk-v381-released](https://ja.developer.box.com/changelog/2023-08-01-box-python-sdk-v381-released) --- ### Box Python SDK `v3.9.0`のリリース **Type:** changelog | **Section:** Changelog Box Python SDK v3.9.0のリリース 新機能と機能強化 SignテンプレートAPIをサポート (#835) (fbc783d) テンプレートIDを使用した署名リクエストの作成をサポート (#834) (4f11d75) バグ修正 ChunkedUploader… # Box Python SDK v3.9.0のリリース ### 新機能と機能強化 - SignテンプレートAPIをサポート ([#835](https://github.com/box/box-python-sdk/issues/835)) ([`fbc783d`](https://github.com/box/box-python-sdk/commit/fbc783d5af2e75f883f1a0051613c513139f68fb)) - テンプレートIDを使用した署名リクエストの作成をサポート ([#834](https://github.com/box/box-python-sdk/issues/834)) ([`4f11d75`](https://github.com/box/box-python-sdk/commit/4f11d7596488194fc740936fe987f42864003d41)) ### バグ修正 - `ChunkedUploader`がクローズされていない`ThreadPoolExecutor`インスタンスを再開 ([#840](https://github.com/box/box-python-sdk/issues/840)) ([`f210f00`](https://github.com/box/box-python-sdk/commit/f210f00ad823d7755309f2e8804641e0debf8197)) **Source:** [https://ja.developer.box.com/changelog/2023-09-06-box-python-sdk-v390-released](https://ja.developer.box.com/changelog/2023-09-06-box-python-sdk-v390-released) --- ### Box Python SDK `v3.9.1`のリリース **Type:** changelog | **Section:** Changelog Box Python SDK v3.9.1のリリース バグ修正 レスポンスコードが202の場合に、ZIPの作成を再試行しない (#845) (3f6ed4e)、#844をクローズ # Box Python SDK v3.9.1のリリース ### バグ修正 - レスポンスコードが202の場合に、ZIPの作成を再試行しない ([#845](https://github.com/box/box-python-sdk/issues/845)) ([`3f6ed4e`](https://github.com/box/box-python-sdk/commit/3f6ed4e1053a494ed9f2b79828850e059d0a1617))、[#844](https://github.com/box/box-python-sdk/issues/844)をクローズ **Source:** [https://ja.developer.box.com/changelog/2023-09-14-box-python-sdk-v391-released](https://ja.developer.box.com/changelog/2023-09-14-box-python-sdk-v391-released) --- ### Box Python SDK `v3.9.2`のリリース **Type:** changelog | **Section:** Changelog Box Python SDK v3.9.2のリリース バグ修正 urllib3ライブラリに対するバージョン2未満の制限を削除 (#851) (1dcd82e) # Box Python SDK v3.9.2のリリース ### バグ修正 - `urllib3`ライブラリに対するバージョン2未満の制限を削除 ([#851](https://github.com/box/box-python-sdk/issues/851)) ([`1dcd82e`](https://github.com/box/box-python-sdk/commit/1dcd82e93267bfc68e3a7f8068b3c45ab7e86daf)) **Source:** [https://ja.developer.box.com/changelog/2023-10-18-box-python-sdk-v392-released](https://ja.developer.box.com/changelog/2023-10-18-box-python-sdk-v392-released) --- ### Box Python SDK Generated `v1.1.0`のリリース **Type:** changelog | **Section:** Changelog Box Python SDK Generated v1.1.0のリリース バグ修正 自動更新のプルリクエストのCIを修正 (box/box-codegen#506) (#187) (5e59f6… # Box Python SDK Generated v1.1.0のリリース ### バグ修正 - 自動更新のプルリクエストのCIを修正 (`box/box-codegen`[#506](https://github.com/box/box-codegen/issues/506)) ([#187](https://github.com/box/box-codegen/issues/187)) ([`5e59f69`](https://github.com/box/box-codegen/commit/5e59f69591e01cd2caf0033e0023061093989aa5)) ### 新機能と機能強化 - 不足していたマーカーページ割りフィールドを追加し、新しいイベントタイプ`AppItemEventSource` `(box/box-openapi[#431](https://github.com/box/box-codegen/issues/431))`を導入 ([#189](https://github.com/box/box-codegen/issues/189)) ([`8d22ce2`](https://github.com/box/box-codegen/commit/8d22ce20d57f4b5dcb5b344ff6bfc67bcaa3568d)) **Source:** [https://ja.developer.box.com/changelog/2024-06-12-box-python-sdk-generated-v110-released](https://ja.developer.box.com/changelog/2024-06-12-box-python-sdk-generated-v110-released) --- ### Box Python SDK Generated `v1.11.0`のリリース **Type:** changelog | **Section:** Changelog Box Python SDK Generated v1.11.0のリリース バグ修正 ファイルレプリゼンテーションのpagedおよびthumbプロパティのタイプを修正 (box/box-openapi#503) (#451) (e818fa6) 新機能と機能強化 Box Sign… # Box Python SDK Generated v1.11.0のリリース ### バグ修正 - ファイルレプリゼンテーションの`paged`および`thumb`プロパティのタイプを修正 (box/box-openapi[#503](https://github.com/box/box-python-sdk-gen/issues/503)) ([#451](https://github.com/box/box-python-sdk-gen/issues/451)) ([`e818fa6`](https://github.com/box/box-python-sdk-gen/commit/e818fa6c9c80e61a293fc24ed6f1a15978681662)) ### 新機能と機能強化 - Box Signの共有リクエストを追加 (box/box-openapi[#504](https://github.com/box/box-python-sdk-gen/issues/504)) ([#453](https://github.com/box/box-python-sdk-gen/issues/453)) ([`3590918`](https://github.com/box/box-python-sdk-gen/commit/359091873d26111b82f000e7837553cc799f2433)) - 機能: `/ai/ask`にHubのサポートを追加。`create_ai_ask`メソッドの`items`パラメータのタイプを`List[AiItemBase]`から`List[AiItemAsk]`に置き換え (box/box-openapi[#506](https://github.com/box/box-python-sdk-gen/issues/506)) ([#466](https://github.com/box/box-python-sdk-gen/issues/466)) ([`29f0364`](https://github.com/box/box-python-sdk-gen/commit/29f03649f3ec1471e859609d2b8bd77ad5d09106)) - `/ai/extract_structured`レスポンスのスキーマを更新 (box/box-codegen[#641](https://github.com/box/box-python-sdk-gen/issues/641)) ([#459](https://github.com/box/box-python-sdk-gen/issues/459)) ([`7c73cea`](https://github.com/box/box-python-sdk-gen/commit/7c73ceaa8888332b23bca4d6b64ef4999f942940)) **Source:** [https://ja.developer.box.com/changelog/2025-02-06-box-python-sdk-generated-v1110-released](https://ja.developer.box.com/changelog/2025-02-06-box-python-sdk-generated-v1110-released) --- ### Box Python SDK Generated `v1.11.1`のリリース **Type:** changelog | **Section:** Changelog Box Python SDK Generated v1.11.1のリリース バグ修正 プロキシの使用を修正 (box/box-codegen#662) (#476) (e1d62ac) # Box Python SDK Generated v1.11.1のリリース ### バグ修正 - プロキシの使用を修正 (box/box-codegen[#662](https://github.com/box/box-python-sdk-gen/issues/662)) ([#476](https://github.com/box/box-python-sdk-gen/issues/476)) ([`e1d62ac`](https://github.com/box/box-python-sdk-gen/commit/e1d62ac5a8063bf37244329329100752c3a069af)) **Source:** [https://ja.developer.box.com/changelog/2025-02-12-box-python-sdk-generated-v1111-released](https://ja.developer.box.com/changelog/2025-02-12-box-python-sdk-generated-v1111-released) --- ### Box Python SDK Generated `v1.13.0`のリリース **Type:** changelog | **Section:** Changelog Box Python SDK Generated v1.13.0のリリース バグ修正 verification_phone_numberプロパティを追加して署名リクエストを作成 (box/box-openapi#515) (#503) (6d19d1… # Box Python SDK Generated v1.13.0のリリース ### バグ修正 - `verification_phone_number`プロパティを追加して署名リクエストを作成 (box/box-openapi[#515](https://github.com/box/box-python-sdk-gen/issues/515)) ([#503](https://github.com/box/box-python-sdk-gen/issues/503)) ([`6d19d19`](https://github.com/box/box-python-sdk-gen/commit/6d19d197481a578d7d5ad8d632ac6f5c06bd3dce)) ### 新機能と機能強化 - 共有リンクのアプリ項目を検索するエンドポイントを追加 (box/box-openapi[#514](https://github.com/box/box-python-sdk-gen/issues/514)) ([#502](https://github.com/box/box-python-sdk-gen/issues/502)) ([`fd6c693`](https://github.com/box/box-python-sdk-gen/commit/fd6c6933f0fb518830e9ac810fd511a0cf60b429)) - Teams統合マッピング (リスト) APIを追加 (box/box-openapi[#517](https://github.com/box/box-python-sdk-gen/issues/517)) ([#505](https://github.com/box/box-python-sdk-gen/issues/505)) ([`d1aa250`](https://github.com/box/box-python-sdk-gen/commit/d1aa250fb01fbf742daf266d4458ba2eab2c5669)) - 事前チェックを伴うアップロードをサポート (box/box-codegen[#676](https://github.com/box/box-python-sdk-gen/issues/676)) ([#515](https://github.com/box/box-python-sdk-gen/issues/515)) ([`bb4597e`](https://github.com/box/box-python-sdk-gen/commit/bb4597e40d49e20eca44c4414e406b1352af1a2b)) **Source:** [https://ja.developer.box.com/changelog/2025-03-18-box-python-sdk-generated-v1130-released](https://ja.developer.box.com/changelog/2025-03-18-box-python-sdk-generated-v1130-released) --- ### Box Python SDK Generated `v1.14.0`のリリース **Type:** changelog | **Section:** Changelog Box Python SDK Generated v1.14.0のリリース バグ修正 リクエストのデフォルトのタイムアウトを設定 (box/box-codegen#707) (#552) (66b87c8) 新機能と機能強化 Sign… # Box Python SDK Generated v1.14.0のリリース ### バグ修正 - リクエストのデフォルトのタイムアウトを設定 (box/box-codegen[#707](https://github.com/box/box-python-sdk-gen/issues/707)) ([#552](https://github.com/box/box-python-sdk-gen/issues/552)) ([`66b87c8`](https://github.com/box/box-python-sdk-gen/commit/66b87c8986ce2f5fdb3a9eac995ef8a9643bcd76)) ### 新機能と機能強化 - Signテンプレートスキーマにセキュリティ設定のプロパティを追加 (box/box-openapi[#518](https://github.com/box/box-python-sdk-gen/issues/518)) ([#543](https://github.com/box/box-python-sdk-gen/issues/543)) ([`0a45d21`](https://github.com/box/box-python-sdk-gen/commit/0a45d218d1aa3fa62da7b5c8c01506fb657c0b36)) - エラーの機密データのサニタイズをサポート (box/box-codegen[#695](https://github.com/box/box-python-sdk-gen/issues/695)) ([#533](https://github.com/box/box-python-sdk-gen/issues/533)) ([`abb7b1d`](https://github.com/box/box-python-sdk-gen/commit/abb7b1d16a192edd99ff1fc4fb7c4caf79ee5f10)) **Source:** [https://ja.developer.box.com/changelog/2025-05-02-box-python-sdk-generated-v1140-released](https://ja.developer.box.com/changelog/2025-05-02-box-python-sdk-generated-v1140-released) --- ### Box Python SDK Generated `v1.15.0`のリリース **Type:** changelog | **Section:** Changelog Box Python SDK Generated v1.15.0のリリース バグ修正 本文をエスケープする場合としない場合のWebhook署名を計算 (box/box-codegen#737) (#607) (e5118b8) トークンの取得にretrieveToken… # Box Python SDK Generated v1.15.0のリリース ### バグ修正 - 本文をエスケープする場合としない場合のWebhook署名を計算 (box/box-codegen[#737](https://github.com/box/box-python-sdk-gen/issues/737)) ([#607](https://github.com/box/box-python-sdk-gen/issues/607)) ([`e5118b8`](https://github.com/box/box-python-sdk-gen/commit/e5118b8a257a042510374d91bd62a1f98c662fef)) - トークンの取得に`retrieveToken`メソッドを使用するようダウンスコープトークンを修正 (box/box-codegen[#731](https://github.com/box/box-python-sdk-gen/issues/731)) ([#598](https://github.com/box/box-python-sdk-gen/issues/598)) ([`e492685`](https://github.com/box/box-python-sdk-gen/commit/e4926851edccd4ee7e66157050cedd0d01cec5ea)) - Webhook署名を計算する際のスラッシュのエスケープを修正 (box/box-codegen[#736](https://github.com/box/box-python-sdk-gen/issues/736)) ([#603](https://github.com/box/box-python-sdk-gen/issues/603)) ([`430b175`](https://github.com/box/box-python-sdk-gen/commit/430b1754ec840582e28a277c6c8d369cbe7ebdf5)) - HMAC署名に定数時間比較を使用 (box/box-codegen[#739](https://github.com/box/box-python-sdk-gen/issues/739)) ([#610](https://github.com/box/box-python-sdk-gen/issues/610)) ([`6f6660c`](https://github.com/box/box-python-sdk-gen/commit/6f6660c8f3aa2b7b75b0fcd4ed015d8d761cd77f)) ### 新機能と機能強化 - AIエージェントの警告を追加し、より多くの種類のメタデータ値を許可 (box/box-openapi[#520](https://github.com/box/box-python-sdk-gen/issues/520)) ([#567](https://github.com/box/box-python-sdk-gen/issues/567)) ([`86aa1cc`](https://github.com/box/box-python-sdk-gen/commit/86aa1ccadac9acead7bceeafb50e45f38eb2d9cc)) - ShieldリストのAPIを追加 (box/box-openapi[#528](https://github.com/box/box-python-sdk-gen/issues/528)) ([#601](https://github.com/box/box-python-sdk-gen/issues/601)) ([`f980f65`](https://github.com/box/box-python-sdk-gen/commit/f980f6544a58a5c64ab0b3ec13b2771b81ea25ed)) - AI APIにIBMモデルのサポートを追加 (box/box-openapi[#522](https://github.com/box/box-python-sdk-gen/issues/522)) ([#568](https://github.com/box/box-python-sdk-gen/issues/568)) ([`767547a`](https://github.com/box/box-python-sdk-gen/commit/767547ae070909852800c447e65cbcc95b97c5a3)) - リーガルホールドとAIモデルを更新 (box/box-openapi[#526](https://github.com/box/box-python-sdk-gen/issues/526)) ([#599](https://github.com/box/box-python-sdk-gen/issues/599)) ([`d56228d`](https://github.com/box/box-python-sdk-gen/commit/d56228d81bd9777af5431ccc9d05233e13a0c2ed)) **Source:** [https://ja.developer.box.com/changelog/2025-06-12-box-python-sdk-generated-v1150-released](https://ja.developer.box.com/changelog/2025-06-12-box-python-sdk-generated-v1150-released) --- ### Box Python SDK Generated `v1.16.0`のリリース **Type:** changelog | **Section:** Changelog Box Python SDK Generated v1.16.0のリリース バグ修正 イベントのnext_stream_positionプロパティタイプをintに指定 (box/box-openapi#535) (#644) (64069db) 新機能と機能強化 AI… # Box Python SDK Generated v1.16.0のリリース ### バグ修正 - イベントの`next_stream_position`プロパティタイプを`int`に指定 (box/box-openapi[#535](https://github.com/box/box-python-sdk-gen/issues/535)) ([#644](https://github.com/box/box-python-sdk-gen/issues/644)) ([`64069db`](https://github.com/box/box-python-sdk-gen/commit/64069db8da33988c173380defd6be065daa02496)) ### 新機能と機能強化 - AIスプレッドシートプロセッサを追加 (box/box-openapi[#533](https://github.com/box/box-python-sdk-gen/issues/533)) ([#630](https://github.com/box/box-python-sdk-gen/issues/630)) ([`6635757`](https://github.com/box/box-python-sdk-gen/commit/66357578218913240bc923cb0dc771157ec95f54)) - アーカイブの公開APIを追加 (box/box-openapi[#540](https://github.com/box/box-python-sdk-gen/issues/540)) ([#651](https://github.com/box/box-python-sdk-gen/issues/651)) ([`c36d1db`](https://github.com/box/box-python-sdk-gen/commit/c36d1dbff42c89876c037983c792c5c7282459cc)) - 新しいHubs APIとHubの項目APIを追加 (box/box-openapi[#538](https://github.com/box/box-python-sdk-gen/issues/538)) ([#645](https://github.com/box/box-python-sdk-gen/issues/645)) ([`1daa3e8`](https://github.com/box/box-python-sdk-gen/commit/1daa3e8814403c78ed2a1d64187b8e4c379028fe)) - ネットワークの例外の再試行戦略に新しいプロパティを追加 (box/box-codegen[#763](https://github.com/box/box-python-sdk-gen/issues/763)) ([#650](https://github.com/box/box-python-sdk-gen/issues/650)) ([`13f9593`](https://github.com/box/box-python-sdk-gen/commit/13f9593dbc4a45d094ee5709d602188ef341a1a5)) - `Metadata Error`の新しいスキーマを追加 (box/box-openapi[#539](https://github.com/box/box-python-sdk-gen/issues/539)) ([#646](https://github.com/box/box-python-sdk-gen/issues/646)) ([`49d7f34`](https://github.com/box/box-python-sdk-gen/commit/49d7f349e1be4e23939ef10db1edfc6042b98175)) - JWTの秘密キー復号メカニズムの挿入を許可 (box/box-codegen[#754](https://github.com/box/box-python-sdk-gen/issues/754)) ([#636](https://github.com/box/box-python-sdk-gen/issues/636)) ([`4ea0af5`](https://github.com/box/box-python-sdk-gen/commit/4ea0af5f8f5b5516a7c23d7912c34690c017db29)) - Webhookの検証チェックを改善 (box/box-codegen[#745](https://github.com/box/box-python-sdk-gen/issues/745)) ([#628](https://github.com/box/box-python-sdk-gen/issues/628)) ([`f0ece63`](https://github.com/box/box-python-sdk-gen/commit/f0ece639d761c765b3bc59fbe3ba8582af755178)) - Hubsのベータ版エンドポイントをサポート (box/box-openapi[#531](https://github.com/box/box-python-sdk-gen/issues/531)) ([#622](https://github.com/box/box-python-sdk-gen/issues/622)) ([`b5e95fe`](https://github.com/box/box-python-sdk-gen/commit/b5e95fe5b219d067028aa395170718eca0d62189)) - AI Studioの新しいツールをサポート (box/box-openapi[#534](https://github.com/box/box-python-sdk-gen/issues/534)) ([#633](https://github.com/box/box-python-sdk-gen/issues/633)) ([`ac76eb2`](https://github.com/box/box-python-sdk-gen/commit/ac76eb2d7c5560b30c4cec171dd90b0a0ece4ab5)) **Source:** [https://ja.developer.box.com/changelog/2025-08-05-box-python-sdk-generated-v1160-released](https://ja.developer.box.com/changelog/2025-08-05-box-python-sdk-generated-v1160-released) --- ### Box Python SDK Generated `v1.2.0`のリリース **Type:** changelog | **Section:** Changelog Box Python SDK Generated v1.2.0のリリース バグ修正 分割アップロードの信頼性を改善 (#224) (05f0353) 新機能と機能強化 ユーザーコラボレーションにis_activeパラメータを追加 (box/box-openapi#43… # Box Python SDK Generated v1.2.0のリリース ### バグ修正 - 分割アップロードの信頼性を改善 ([#224](https://github.com/box/box-codegen/issues/224)) ([`05f0353`](https://github.com/box/box-codegen/commit/05f035354a76dac0d71849523e4a28641ac92aee)) ### 新機能と機能強化 - ユーザーコラボレーションに`is_active`パラメータを追加 (box/box-openapi[#437](https://github.com/box/box-codegen/issues/437)) ([#222](https://github.com/box/box-codegen/issues/222)) ([`2b7bbe4`](https://github.com/box/box-codegen/commit/2b7bbe41ed23e50c6717148fa5e9e2c24a3f5897)) - ステータスコード`202`のリクエストを再試行 (box/box-codegen[#511](https://github.com/box/box-codegen/issues/511)) ([#204](https://github.com/box/box-codegen/issues/204)) ([`f50ad6e`](https://github.com/box/box-codegen/commit/f50ad6e236003901792eb333738020cbdd8c8ae3)) - AIエージェントAPIをサポート (box/box-codegen[#531](https://github.com/box/box-codegen/issues/531)) ([#229](https://github.com/box/box-codegen/issues/229)) ([`c565383`](https://github.com/box/box-codegen/commit/c5653839e1a150377e7d5c4764d4c2a7b7d07c4a)) - `null`値のフィールドの送信をサポート (box/box-codegen[#528](https://github.com/box/box-codegen/issues/528)) ([#230](https://github.com/box/box-codegen/issues/230)) ([`f91076e`](https://github.com/box/box-codegen/commit/f91076e1bfbccae4a0dff4b66d7bafb5357858c5))、[#202](https://github.com/box/box-codegen/issues/202)をクローズ **Source:** [https://ja.developer.box.com/changelog/2024-07-26-box-python-sdk-generated-v120-released](https://ja.developer.box.com/changelog/2024-07-26-box-python-sdk-generated-v120-released) --- ### Box Python SDK Generated `v1.3.0`のリリース **Type:** changelog | **Section:** Changelog Box Python SDK Generated v1.3.0のリリース バグ修正 マルチパートリクエストのfetchメソッドを修正 (box/box-codegen#545) (#266) (08a0818) 新機能と機能強化 分割アップロードのエンドポイントURL… # Box Python SDK Generated v1.3.0のリリース ### バグ修正 - マルチパートリクエストのfetchメソッドを修正 (box/box-codegen[#545](https://github.com/box/box-codegen/issues/545)) ([#266](https://github.com/box/box-codegen/issues/266)) ([`08a0818`](https://github.com/box/box-codegen/commit/08a0818995d64995c3e2720a459f9221c9ca1dea)) ### 新機能と機能強化 - 分割アップロードのエンドポイントURLをパラメータ化 (box/box-openapi[#444](https://github.com/box/box-codegen/issues/444)) ([#264](https://github.com/box/box-codegen/issues/264)) ([`b5bce24`](https://github.com/box/box-codegen/commit/b5bce24478c70ae6bb997adc773a0e2a76223568)) **Source:** [https://ja.developer.box.com/changelog/2024-08-12-box-python-sdk-generated-v130-released](https://ja.developer.box.com/changelog/2024-08-12-box-python-sdk-generated-v130-released) --- ### Box Python SDK Generated `v1.4.0`のリリース **Type:** changelog | **Section:** Changelog Box Python SDK Generated v1.4.0のリリース バグ修正 Signテンプレートの署名者に不足していたフィールドを追加し、AIスキーマを修正 (box/box-openapi#451) (#281) (0708351) IntegrationMapping… # Box Python SDK Generated v1.4.0のリリース ### バグ修正 - Signテンプレートの署名者に不足していたフィールドを追加し、AIスキーマを修正 (box/box-openapi[#451](https://github.com/box/box-codegen/issues/451)) ([#281](https://github.com/box/box-codegen/issues/281)) ([`0708351`](https://github.com/box/box-codegen/commit/0708351171eca1fe4914b823a4257bbabd3cd075)) - `IntegrationMapping`スキーマを修正 (box/box-codegen[#551](https://github.com/box/box-codegen/issues/551)) ([#279](https://github.com/box/box-codegen/issues/279)) ([`0337e06`](https://github.com/box/box-codegen/commit/0337e06c6bf6d35dd51409c429b7fef295f5a406)) ### 新機能と機能強化 - Box AIのメソッドに新しいパラメータを追加し、`AiResponseFull`バリアントを導入 (box/box-openapi[#446](https://github.com/box/box-codegen/issues/446)) ([#277](https://github.com/box/box-codegen/issues/277)) ([`1267a21`](https://github.com/box/box-codegen/commit/1267a215fbc8292059603665a53b0159d7a1242c)) - `FetchOptions`にURLを追加 (box/box-codegen[#549](https://github.com/box/box-codegen/issues/549)) ([#283](https://github.com/box/box-codegen/issues/283)) ([`dd05b1c`](https://github.com/box/box-codegen/commit/dd05b1c2b1687d8647f4116c022dbf1890984adc)) **Source:** [https://ja.developer.box.com/changelog/2024-08-23-box-python-sdk-generated-v140-released](https://ja.developer.box.com/changelog/2024-08-23-box-python-sdk-generated-v140-released) --- ### Box Python SDK Generated `v1.4.1`のリリース **Type:** changelog | **Section:** Changelog Box Python SDK Generated v1.4.1のリリース バグ修正 Pythonでのダウンロード処理中にデータをメモリ内に保存しない (box/box-codegen#557) (#294) (7c645ae) # Box Python SDK Generated v1.4.1のリリース ### バグ修正 - Pythonでのダウンロード処理中にデータをメモリ内に保存しない (box/box-codegen[#557](https://github.com/box/box-codegen/issues/557)) ([#294](https://github.com/box/box-codegen/issues/294)) ([`7c645ae`](https://github.com/box/box-codegen/commit/7c645aea9fa8575531e0b40ffc997a0f65b6e409)) **Source:** [https://ja.developer.box.com/changelog/2024-08-30-box-python-sdk-generated-v141-released](https://ja.developer.box.com/changelog/2024-08-30-box-python-sdk-generated-v141-released) --- ### Box Python SDK Generated `v1.5.0`のリリース **Type:** changelog | **Section:** Changelog Box Python SDK Generated v1.5.0のリリース バグ修正 不足していたライセンスをsetup.pyに追加 (box/box-codegen#562) (#307) (679d789) メタデータクエリの結果のバリアントを修正 (box/box… # Box Python SDK Generated v1.5.0のリリース ### バグ修正 - 不足していたライセンスを`setup.py`に追加 (box/box-codegen[#562](https://github.com/box/box-codegen/issues/562)) ([#307](https://github.com/box/box-codegen/issues/307)) ([`679d789`](https://github.com/box/box-codegen/commit/679d7891b2a20e7407b8c9f00bd95c3b294ab861)) - メタデータクエリの結果のバリアントを修正 (box/box-openapi[#456](https://github.com/box/box-codegen/issues/456)) ([#313](https://github.com/box/box-codegen/issues/313)) ([`8830303`](https://github.com/box/box-codegen/commit/883030335e2a3c12a5e0b01d8a82df30ccce16a6)) ### 新機能と機能強化 - プロキシのサポートを追加 (box/box-codegen[#559](https://github.com/box/box-codegen/issues/559)) ([#302](https://github.com/box/box-codegen/issues/302)) ([`3d881ac`](https://github.com/box/box-codegen/commit/3d881acdebf2b18e2f0f82211f5abdcc32d1ddb0)) - 未加工の`json`レスポンスを格納するための`raw_data`フィールドを導入 (box/box-codegen[#566](https://github.com/box/box-codegen/issues/566)) ([#319](https://github.com/box/box-codegen/issues/319)) ([`3776dc3`](https://github.com/box/box-codegen/commit/3776dc3d44bc09eb68da99f45e36e058dca2607e)) - `ai/extract`および`ai/extract_structured`エンドポイントをサポート (box/box-codegen[#564](https://github.com/box/box-codegen/issues/564)) ([#317](https://github.com/box/box-codegen/issues/317)) ([`b3d8da4`](https://github.com/box/box-codegen/commit/b3d8da41007a9d47b73b699fd84da6f9540866d2)) - アプリ項目の関連付けをサポート (box/box-codegen[#561](https://github.com/box/box-codegen/issues/561)) ([#299](https://github.com/box/box-codegen/issues/299)) ([`8b6ea0b`](https://github.com/box/box-codegen/commit/8b6ea0bbec719a36eb11b6d214c08801c4f1a40b)) **Source:** [https://ja.developer.box.com/changelog/2024-09-18-box-python-sdk-generated-v150-released](https://ja.developer.box.com/changelog/2024-09-18-box-python-sdk-generated-v150-released) --- ### Box Python SDK Generated `v1.5.1`のリリース **Type:** changelog | **Section:** Changelog Box Python SDK Generated v1.5.1のリリース バグ修正 プロキシ資格情報のないプロキシurlを修正 (box/box-codegen#568) (#322) (fb19160)、#31… # Box Python SDK Generated v1.5.1のリリース ### バグ修正 - プロキシ資格情報のないプロキシ`url`を修正 (box/box-codegen[#568](https://github.com/box/box-codegen/issues/568)) ([#322](https://github.com/box/box-codegen/issues/322)) ([`fb19160`](https://github.com/box/box-codegen/commit/fb19160307b58d5f08bb12e0f846d71ff936ad6a))、[#318](https://github.com/box/box-codegen/issues/318)をクローズ - 分割アップロードで最後の空のチャンクを送信しないように修正 (box/box-codegen[#569](https://github.com/box/box-codegen/issues/569)) ([#324](https://github.com/box/box-codegen/issues/324)) ([`1605f04`](https://github.com/box/box-codegen/commit/1605f0495994b333e735bc98f28fa714324b75f5))、[#321](https://github.com/box/box-codegen/issues/321)をクローズ **Source:** [https://ja.developer.box.com/changelog/2024-09-19-box-python-sdk-generated-v151-released](https://ja.developer.box.com/changelog/2024-09-19-box-python-sdk-generated-v151-released) --- ### Box Python SDK Generated `v1.6.0`のリリース **Type:** changelog | **Section:** Changelog Box Python SDK Generated v1.6.0のリリース バグ修正 マルチパートリクエストのストリーム位置を0に設定 (box/box-codegen#581) (#348) (fa6942c) クライアントエラースキーマを更新 (box/box-openapi… # Box Python SDK Generated v1.6.0のリリース ### バグ修正 - マルチパートリクエストのストリーム位置を0に設定 (box/box-codegen[#581](https://github.com/box/box-codegen/issues/581)) ([#348](https://github.com/box/box-codegen/issues/348)) ([`fa6942c`](https://github.com/box/box-codegen/commit/fa6942c231024947250955ccc52f352744ab5f38)) - クライアントエラースキーマを更新 (box/box-openapi[#467](https://github.com/box/box-codegen/issues/467)) ([#347](https://github.com/box/box-codegen/issues/347)) ([`a42a253`](https://github.com/box/box-codegen/commit/a42a2532337c79d20b6524fda0acf717d9ccbd5f)) - リクエストの再試行時に元のストリーム位置を使用 (box/box-codegen[#583](https://github.com/box/box-codegen/issues/583)) ([#358](https://github.com/box/box-codegen/issues/358)) ([`060b4dc`](https://github.com/box/box-codegen/commit/060b4dc2b8bbbc1e17cce0fc049394e0527952b7)) - コメントにバックスラッシュが含まれる場合に未加工の`docstrings`を使用 (box/box-codegen[#571](https://github.com/box/box-codegen/issues/571)) ([#330](https://github.com/box/box-codegen/issues/330)) ([`8dd8cb7`](https://github.com/box/box-codegen/commit/8dd8cb71105c200bd03f5f894a4dbfb42baf0865)) ### 新機能と機能強化 - `download_file_to_output_stream`メソッドを`DownloadsManager`に追加 (box/box-codegen[#575](https://github.com/box/box-codegen/issues/575)) ([#334](https://github.com/box/box-codegen/issues/334)) ([`6820d08`](https://github.com/box/box-codegen/commit/6820d08f37c5c0605a580391bef2dc4f2a384c00)) - AI LLMエンドポイントのAWS `params`を追加 (box/box-openapi[#478](https://github.com/box/box-codegen/issues/478)) ([#354](https://github.com/box/box-codegen/issues/354)) ([`c8fa2c1`](https://github.com/box/box-codegen/commit/c8fa2c1131154d07a500290db6a7b34b06005c2b)) **Source:** [https://ja.developer.box.com/changelog/2024-10-30-box-python-sdk-generated-v160-released](https://ja.developer.box.com/changelog/2024-10-30-box-python-sdk-generated-v160-released) --- ### Box Python SDK Generated `v1.7.0`のリリース **Type:** changelog | **Section:** Changelog Box Python SDK Generated v1.7.0のリリース 新機能と機能強化 IDを指定してコレクションを取得エンドポイントをサポート (box/box-codegen#595) (#366) (1db5722)、#355をクローズ # Box Python SDK Generated v1.7.0のリリース ### 新機能と機能強化 - IDを指定してコレクションを取得エンドポイントをサポート (box/box-codegen[#595](https://github.com/box/box-codegen/issues/595)) ([#366](https://github.com/box/box-codegen/issues/366)) ([`1db5722`](https://github.com/box/box-codegen/commit/1db5722f7d02694739f1a52a6b2ebe0c406960b0))、[#355](https://github.com/box/box-codegen/issues/355)をクローズ **Source:** [https://ja.developer.box.com/changelog/2024-11-04-box-python-sdk-generated-v170-released](https://ja.developer.box.com/changelog/2024-11-04-box-python-sdk-generated-v170-released) --- ### Box Python SDK Generated `v1.8.0`のリリース **Type:** changelog | **Section:** Changelog Box Python SDK Generated v1.8.0のリリース バグ修正 列挙型の使用を修正 (box/box-codegen#615) (#387) (a9abccb)、#385をクローズ コンテンツのないステータスコードをサポート (box/box-codegen… # Box Python SDK Generated v1.8.0のリリース ### バグ修正 - 列挙型の使用を修正 (box/box-codegen[#615](https://github.com/box/box-python-sdk-gen/issues/615)) ([#387](https://github.com/box/box-python-sdk-gen/issues/387)) ([`a9abccb`](https://github.com/box/box-python-sdk-gen/commit/a9abccb8e552c971774ea1a9fa2096395a40317b))、[#385](https://github.com/box/box-python-sdk-gen/issues/385)をクローズ - コンテンツのないステータスコードをサポート (box/box-codegen[#604](https://github.com/box/box-python-sdk-gen/issues/604)) ([#378](https://github.com/box/box-python-sdk-gen/issues/378)) ([`051716c`](https://github.com/box/box-python-sdk-gen/commit/051716c84b4f0ab32b82608f94e3cf3ba09b390b)) - コラボレーション、メタデータ、コレクションのリソースを更新 (box/box-openapi[#483](https://github.com/box/box-python-sdk-gen/issues/483)) ([#380](https://github.com/box/box-python-sdk-gen/issues/380)) ([`0d45fed`](https://github.com/box/box-python-sdk-gen/commit/0d45fedc0b7b96234ef3901f412f259b1cae4c1a)) ### 新機能と機能強化 - カスタムHTTPリクエストを行うためのメソッドを公開 (box/box-codegen[#610](https://github.com/box/box-python-sdk-gen/issues/610)) ([#393](https://github.com/box/box-python-sdk-gen/issues/393)) ([`55a23d9`](https://github.com/box/box-python-sdk-gen/commit/55a23d9d6840642c248ab3b967ad5c2635484c8c)) - ファイルのダウンロードURLとファイルのサムネイルURLの取得をサポート (box/box-codegen[#617](https://github.com/box/box-python-sdk-gen/issues/617)) ([#397](https://github.com/box/box-python-sdk-gen/issues/397)) ([`fd609ab`](https://github.com/box/box-python-sdk-gen/commit/fd609ab9fe94da43b1a71815597c49471e157bb8)) **Source:** [https://ja.developer.box.com/changelog/2024-12-02-box-python-sdk-generated-v180-released](https://ja.developer.box.com/changelog/2024-12-02-box-python-sdk-generated-v180-released) --- ### Box Python SDK Generated `v1.9.0`のリリース **Type:** changelog | **Section:** Changelog Box Python SDK Generated v1.9.0のリリース バグ修正 SignRequestから未使用のパラメータを削除 (box/box-openapi#489) (#411) (578d9b4) 新機能と機能強化 ai_agentの情報をAiResponse… # Box Python SDK Generated v1.9.0のリリース ### バグ修正 - `SignRequest`から未使用のパラメータを削除 (box/box-openapi[#489](https://github.com/box/box-python-sdk-gen/issues/489)) ([#411](https://github.com/box/box-python-sdk-gen/issues/411)) ([`578d9b4`](https://github.com/box/box-python-sdk-gen/commit/578d9b48da7e55d2e3e4736c871400dc90d826b1)) ### 新機能と機能強化 - `ai_agent`の情報を`AiResponse`に追加 (box/box-openapi[#485](https://github.com/box/box-python-sdk-gen/issues/485)) ([#402](https://github.com/box/box-python-sdk-gen/issues/402)) ([`351a5b8`](https://github.com/box/box-python-sdk-gen/commit/351a5b8dfbc8a0095bafbbf0245d8575217fc3c9)) - ネットワーククライアントの実装を置き換えるサポートを追加 (box/box-codegen[#629](https://github.com/box/box-python-sdk-gen/issues/629)) ([#415](https://github.com/box/box-python-sdk-gen/issues/415)) ([`fb118dd`](https://github.com/box/box-python-sdk-gen/commit/fb118ddb1cbfb1d6a72e657bed57088fdff1ec02)) - 再試行戦略のカスタマイズを許可 (box/box-codegen[#635](https://github.com/box/box-python-sdk-gen/issues/635)) ([#418](https://github.com/box/box-python-sdk-gen/issues/418)) ([`8dfb3ed`](https://github.com/box/box-python-sdk-gen/commit/8dfb3ed13196de37a78a53325079e284c7e921d5)) - ファイル、フォルダ、ウェブリンクの更新で`userId`パラメータ (省略可) をサポート (box/box-openapi[#488](https://github.com/box/box-python-sdk-gen/issues/488)) ([#406](https://github.com/box/box-python-sdk-gen/issues/406)) ([`d9cff4c`](https://github.com/box/box-python-sdk-gen/commit/d9cff4c6adc9c5cc9ce1edf73dffe8ac5979ce71)) - Webhookメッセージの検証をサポート (box/box-codegen[#631](https://github.com/box/box-python-sdk-gen/issues/631)) ([#416](https://github.com/box/box-python-sdk-gen/issues/416)) ([`0fec20b`](https://github.com/box/box-python-sdk-gen/commit/0fec20b281fe195f0dd6aaf8f164bdd414587fc4)) **Source:** [https://ja.developer.box.com/changelog/2024-12-30-box-python-sdk-generated-v190-released](https://ja.developer.box.com/changelog/2024-12-30-box-python-sdk-generated-v190-released) --- ### Box SDKのメジャーリリースに関するお知らせ **Type:** changelog | **Section:** Changelog Box SDKのメジャーリリースに関するお知らせ 2023年1月に、Box Windows V2 SDKとBox Java SDKの2つのメジャーリリースを予定しています。 # Box SDKのメジャーリリースに関するお知らせ 2023年1月に、Box Windows V2 SDKとBox Java SDKの2つのメジャーリリースを予定しています。 Box Windows V2 SDKでは、.NET Frameworkの最小サポートバージョンを4.5から4.6.2以上に変更します。Box Java SDKでは、ネットワークライブラリの置き換えと、[OkHttp](https://square.github.io/okhttp/)の導入を行います。これにより、SDKでHTTP2プロトコルをサポートし、ユーザーはBasic認証以外でもプロキシを使用できるようになります。 両方のSDKで、サポートが終了したAPIを削除します。 - Box Windows V2 SDKの変更の詳細については、[こちら](https://github.com/box/box-windows-sdk-v2/releases/tag/v5.0.0-prerelease)を参照してください。 - Box Java SDKの変更の詳細については、[こちら](https://github.com/box/box-java-sdk/releases/tag/v4.0.0-prerelease)を参照してください。 ## サポート情報 問題がある場合やさらにガイドが必要な場合は、必要なサポートについて、Boxの[Developer Forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum)に英語でリクエストを投稿してください。 **Source:** [https://ja.developer.box.com/changelog/2022-12-19-sdk-box-java-net-releases](https://ja.developer.box.com/changelog/2022-12-19-sdk-box-java-net-releases) --- ### Box Shieldアクセスポリシーの新しい監視モード **Type:** changelog | **Section:** Changelog Box Shieldアクセスポリシーの新しい監視モード 最近Box Shieldに追加された新機能により、管理者は、新しい監視モードでアクセスポリシーをテストできるようになりました。 # Box Shieldアクセスポリシーの新しい監視モード 最近Box Shieldに追加された[新機能](https://support.box.com/hc/en-us/articles/360044196353#enforce_vs_monitor)により、管理者は、新しい監視モードでアクセスポリシーをテストできるようになりました。 ## 更新内容 - [スマートアクセスイベントセクション](g://events/event-triggers/shield-alert-events/#smart-access)のすべてのイベントに新しい`controlMode`フィールドを追加 - スマートアクセスイベントセクションでアプリケーションおよびFTPの制限に関する情報を追加 ## サポート情報 問題がある場合やさらにガイドが必要な場合は、必要なサポートについて、Boxの[Developer Forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum)に英語でリクエストを投稿してください。 **Source:** [https://ja.developer.box.com/changelog/2022-02-14-new-box-shield-event-field](https://ja.developer.box.com/changelog/2022-02-14-new-box-shield-event-field) --- ### Box Shieldスマートアクセスイベント **Type:** changelog | **Section:** Changelog Box Shieldスマートアクセスイベント 外部コラボレーションの制限および正当な理由の承認のイベントがEnterprise Event Streamから使用可能になりました。 この高度なセキュリティ機能を活用するには、Box Shieldを購入し、Box Enterpriseで有効にする必要があります。 # Box Shieldスマートアクセスイベント 外部コラボレーションの制限および正当な理由の承認のイベントが[Enterprise Event](g://events/enterprise-events/for-enterprise/) Streamから使用可能になりました。 この高度なセキュリティ機能を活用するには、[Box Shield](https://www.box.com/shield)を購入し、Box Enterpriseで有効にする必要があります。 これらのイベントは、`event_type`値が次のいずれかに設定されている、標準的な[イベントオブジェクト](r://event/)スキーマに従います: `SHIELD_EXTERNAL_COLLAB_INVITE_BLOCKED_MISSING_JUSTIFICATION`、`SHIELD_EXTERNAL_COLLAB_INVITE_JUSTIFIED`、`SHIELD_EXTERNAL_COLLAB_INVITE_BLOCKED`、`SHIELD_EXTERNAL_COLLAB_ACCESS_BLOCKED_MISSING_JUSTIFICATION`、`SHIELD_EXTERNAL_COLLAB_ACCESS_BLOCKED`、`SHIELD_JUSTIFICATION_APPROVAL`。 各イベントの`additional_details`ペイロードでは、より多くの情報が提供されます。詳細については、BoxのShieldイベントの[ガイド](g://events/event-triggers/shield-alert-events/#smart-access)を参照してください。 ## 機能 - Box Shieldの外部コラボレーションと正当な理由の承認のサポートをEnterprise Event Streamに追加 **Source:** [https://ja.developer.box.com/changelog/2021-02-26-box-shield-smart-access-events](https://ja.developer.box.com/changelog/2021-02-26-box-shield-smart-access-events) --- ### Box Sign APIでのリダイレクトURLの設定のサポート **Type:** changelog | **Section:** Changelog Box Sign APIでのリダイレクトURLの設定のサポート Box Sign APIで、署名リクエストに署名した、または署名リクエストを拒否したユーザーに対して、カスタムリダイレクトURLを設定するための新しいパラメータが提供されるようになりました。これにより、Box Signとアプリケーションを統合する際、署名者をアプリケーションにリダイレクトしたり、カスタムのランディングページを表示したりすることができます。 # Box Sign APIでのリダイレクトURLの設定のサポート [Box Sign API](https://developer.box.com/reference/post-sign-requests/)で、署名リクエストに署名した、または署名リクエストを拒否したユーザーに対して、カスタムリダイレクトURLを設定するための新しいパラメータが提供されるようになりました。これにより、Box Signとアプリケーションを統合する際、署名者をアプリケーションにリダイレクトしたり、カスタムのランディングページを表示したりすることができます。 ## 更新内容 Box Sign APIは、[署名リクエストを作成](https://developer.box.com/guides/box-sign/create-sign-request/)の呼び出しのリクエスト本文で渡すオプションのパラメータを提供します: - リクエストに署名した後に、ユーザーを特定のページにリダイレクトする`redirect_url` - リクエストを拒否した後に、ユーザーを特定のページにリダイレクトする`declined_redirect_url` リダイレクトURLは、すべての署名者に対してグローバルに定義することも、特定の署名者に対してのみ定義することもできます。詳細については、[署名リクエストを作成](https://developer.box.com/guides/box-sign/create-sign-request/)のガイドを参照してください。 ## 開発者向けリソース Box App Centerでのアプリケーションの作成、またはBoxパートナーへの参加をご希望の場合、詳細については[Box Partner Resources](https://support.box.com/hc/en-us/sections/360009473734-Box-Partner-Resources)のガイド (英語) を参照してください。 ## サポート情報 問題がある場合やさらにガイドが必要な場合は、必要なサポートについて、Boxの[Developer Forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum)に英語でリクエストを投稿してください。 **Source:** [https://ja.developer.box.com/changelog/2022-06-24-new-redirect-url-parameters](https://ja.developer.box.com/changelog/2022-06-24-new-redirect-url-parameters) --- ### Box Sign APIのリリース **Type:** changelog | **Section:** Changelog Box Sign APIのリリース 日本時間2021年7月27日に、Box Signをリリースしました。Box Signのリクエストの作成、リスト取得、再送信、キャンセルを実行する最新のAPIエンドポイントを使用することで、Box Signウェブアプリの全機能をプログラムによって利用できます。 Box SignのAPIエンドポイントを使用するために管理者がBox Signを有効にする必要はありませんが、Box Signを企業に導入する必要があります。Box SignがBoxインスタンスで利用できるようになると、管理者に通知されます。 # Box Sign APIのリリース 日本時間2021年7月27日に、Box Signをリリースしました。Box Signのリクエストの作成、リスト取得、再送信、キャンセルを実行する最新のAPIエンドポイントを使用することで、[Box Signウェブアプリ](https://support.box.com/hc/en-us/articles/4404086827411-Introducing-Box-Sign)の全機能をプログラムによって利用できます。 Box SignのAPIエンドポイントを使用するために管理者がBox Signを有効にする必要はありませんが、Box Signを企業に導入する必要があります。Box SignがBoxインスタンスで利用できるようになると、管理者に通知されます。 少なくとも、Box Signのリクエストを作成するには、署名用ファイルのほか、署名済みファイル/[署名ログ](https://support.box.com/hc/en-us/articles/4404095202579-Viewing-the-signing-log)の保存先フォルダを選択し、署名者を指定する必要があります。現時点では、1つのリクエストにつき署名できるファイルは1つだけです。 ``` curl -i -X PUT "https://api.box.com/2.0/sign_requests" \ -H "Authorization: Bearer <ACCESS_TOKEN>" \ -d '{ "signers": [ { "role": "signer", "email": "example_email@box.com" } ], "source_files": [ { "type": "file", "id": "123456789" } ], "parent_folder": { "type": "folder", "id": "0987654321" } }' ``` ## 機能 - Box Signのリクエストを**作成する**エンドポイントを追加: [ガイド](g://box-sign/create-sign-request) | [APIリファレンス](e:///post-sign-requests) - Box Signのリクエストの**リストを取得する**エンドポイントを追加: [ガイド](g://box-sign/list-sign-requests/#all) | [APIリファレンス](e://get-sign-requests) - IDを指定してBox Signのリクエストを**取得する**エンドポイントを追加: [ガイド](g://box-sign/list-sign-requests/#by-id) | [APIリファレンス](e://get-sign-requests-id) - Box Signのリクエストを**再送信する**エンドポイントを追加: [ガイド](g://box-sign/resend-sign-request) | [APIリファレンス](e://post-sign-requests-id-resend) - Box Signのリクエストを**キャンセルする**エンドポイントを追加: [ガイド](g://box-sign/cancel-sign-request) | [APIリファレンス](e://post-sign-requests-id-cancel) - Java SDKのサポート: [GitHub](https://github.com/box/box-java-sdk/blob/main/doc/sign_requests.md) **Source:** [https://ja.developer.box.com/changelog/2021-07-26-release-of-box-sign-api](https://ja.developer.box.com/changelog/2021-07-26-release-of-box-sign-api) --- ### Box Signクライアントの埋め込み機能の導入 **Type:** changelog | **Section:** Changelog Box Signクライアントの埋め込み機能の導入 Box Embedを使用して、ウェブサイトにBox Signの機能を埋め込むことができるようになりました。これにより、ユーザーはウェブサイトを離れ、Box Signにアクセスしてドキュメントに署名し、プロセスを完了するために戻る必要がなくなります。代わりに、Box Embedを使用すると、外部のウェブサイト内で署名プロセスを完了できます。 Box Signのエクスペリエンスをウェブサイトに統合するには、HTMLのiframeタグ内のドキュメントの署名を許可するために設計されたiframeable_embed_urlパラメータが必要です。 # Box Signクライアントの埋め込み機能の導入 [Box Embed](g://embed/box-embed)を使用して、ウェブサイトに[Box Signの機能を埋め込む](g://box-sign/create-sign-request#embedded-sign-client)ことができるようになりました。これにより、ユーザーはウェブサイトを離れ、Box Signにアクセスしてドキュメントに署名し、プロセスを完了するために戻る必要がなくなります。代わりに、Box Embedを使用すると、外部のウェブサイト内で署名プロセスを完了できます。 Box Signのエクスペリエンスをウェブサイトに統合するには、HTMLの`iframe`タグ内のドキュメントの署名を許可するために設計された[`iframeable_embed_url`](r://sign-request#param-signers-iframeable_embed_url)パラメータが必要です。 ## サポート情報 問題がある場合やさらにガイドが必要な場合は、必要なサポートについて、Boxの[Developer Forum](https://forum.box.com/)に英語でリクエストを投稿してください。 **Source:** [https://ja.developer.box.com/changelog/2023-08-16-embedded-sign-client](https://ja.developer.box.com/changelog/2023-08-16-embedded-sign-client) --- ### Box SignテンプレートAPI **Type:** changelog | **Section:** Changelog Box SignテンプレートAPI 新しいBox SignテンプレートAPIを使用すると、Box Signテンプレートのリストまたは特定のBox Sign… # Box SignテンプレートAPI 新しいBox SignテンプレートAPIを使用すると、[Box Signテンプレートのリスト](e://get-sign-templates)または[特定のBox Signテンプレートの詳細](e://get-sign-templates-id)を取得できます。この情報を使用して、テンプレートベースの署名リクエストを開始できます。 ## サポート情報 問題がある場合やさらにガイドが必要な場合は、Boxの[Developer Forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum)に英語でリクエストを投稿してください。 **Source:** [https://ja.developer.box.com/changelog/2023-05-10-box-sign-templates](https://ja.developer.box.com/changelog/2023-05-10-box-sign-templates) --- ### Box SignのEnterprise Event **Type:** changelog | **Section:** Changelog Box SignのEnterprise Event Box Signイベントが、Enterprise Event Streamを使用して利用できるようになりました。詳細については、Box Sign… # Box SignのEnterprise Event [Box Sign](g://box-sign)イベントが、Enterprise Event Streamを使用して利用できるようになりました。詳細については、[Box Signイベントガイド](g://events/event-triggers/sign-events)をご参照ください。 ## 更新内容 署名リクエストの[ドキュメントイベント](g://events/event-triggers/sign-events/#document-events)を追加: 作成、変換、完了、キャンセル、期限切れ 署名リクエストの[署名者イベント](g://events/event-triggers/sign-events/#signer-events)を追加: 割り当て、署名者による表示、ダウンロード、転送、署名、拒否 2つの新しい[ステータス](e://resources/sign-requests/#param-status)を追加: `downloaded`、`downloaded and signed` **Source:** [https://ja.developer.box.com/changelog/2021-10-27-box-sign-enterprise-events](https://ja.developer.box.com/changelog/2021-10-27-box-sign-enterprise-events) --- ### Box Signの使用 **Type:** changelog | **Section:** Changelog Box Signの使用 Boxでは、専用リソースページとしてBox Signの使用を新しくリリースしました。この総合的なガイドは、開発者が自分のアプリケーションにBox Signをシームレスに統合できるようにすることを目的としており、この強力な電子サインソリューションを最大限に活用するためのツールや知識を提供します。 # Box Signの使用 Boxでは、専用リソースページとして[Box Signの使用](https://developer.box.com/sign/)を新しくリリースしました。この総合的なガイドは、開発者が自分のアプリケーションにBox Signをシームレスに統合できるようにすることを目的としており、この強力な電子サインソリューションを最大限に活用するためのツールや知識を提供します。 ## 目次 - [クイックスタート](https://developer.box.com/sign/quick-start/) - [技術的なユースケース](https://developer.box.com/sign/technical-use-cases/) - [署名リクエストのオプション](https://developer.box.com/sign/request-options/) - [Webhook](https://developer.box.com/sign/webhooks/) - [ワークショップ](https://github.com/barduinor/box-python-gen-workshop/blob/main/workshops/sign/sign.md) **Source:** [https://ja.developer.box.com/changelog/2024-02-06-working-with-box-sign](https://ja.developer.box.com/changelog/2024-02-06-working-with-box-sign) --- ### Box Signの新しいWebhookトリガー **Type:** changelog | **Section:** Changelog Box Signの新しいWebhookトリガー Webhookイベントトリガーに、V2 Webhookのトリガーに使用できる次のBox Signイベントが含まれるようになりました。 SIGN_REQUEST.COMPLETED SIGN_REQUEST.DECLINED SIGN_REQUEST.EXPIRED Webhookの作成の詳細については、このガイドを参照してください。 # Box Signの新しいWebhookトリガー [Webhookイベントトリガー](g://webhooks/triggers)に、V2 Webhookのトリガーに使用できる次のBox Signイベントが含まれるようになりました。 - `SIGN_REQUEST.COMPLETED` - `SIGN_REQUEST.DECLINED` - `SIGN_REQUEST.EXPIRED` Webhookの作成の詳細については、[このガイド](g://webhooks/v2/create-v2)を参照してください。 ## 開発者向けリソース Box App Centerでのアプリケーションの作成、またはBoxパートナーへの参加をご希望の場合、詳細については[Box Partner Resources](https://support.box.com/hc/en-us/sections/360009473734-Box-Partner-Resources)のガイド (英語) を参照してください。 ## サポート情報 問題がある場合やさらにガイドが必要な場合は、必要なサポートについて、Boxの[Developer Forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum)に英語でリクエストを投稿してください。 **Source:** [https://ja.developer.box.com/changelog/2022-07-11-sign-webhooks-support](https://ja.developer.box.com/changelog/2022-07-11-sign-webhooks-support) --- ### Box Signの更新 **Type:** changelog | **Section:** Changelog Box Signの更新 署名リクエストでの複数ドキュメントの送信 Box Signの署名リクエストでの複数ドキュメントの送信が公開API… # Box Signの更新 ## 署名リクエストでの複数ドキュメントの送信 Box Signの署名リクエストでの[複数ドキュメントの送信](https://support.box.com/hc/en-us/sections/10302887198227-Multiple-documents-in-a-signature-request)が[公開API](e://post-sign-requests)でサポートされるようになりました。 ## 署名者向けの添付機能 [署名者向けの添付](r://sign-request#param-signers-inputs-content_type)機能により、ユーザーはファイル添付フィールドで署名者に追加ファイルをリクエストできます。 ## サポート情報 問題がある場合やさらにガイドが必要な場合は、必要なサポートについて、Boxの[Developer Forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum)に英語でリクエストを投稿してください。 **Source:** [https://ja.developer.box.com/changelog/2023-02-23-multidoc-support-API-and-signer-attachments](https://ja.developer.box.com/changelog/2023-02-23-multidoc-support-API-and-signer-attachments) --- ### Box Signの通知の抑制 **Type:** changelog | **Section:** Changelog Box Signの通知の抑制 Box Sign APIを使用すると、Box Signのワークフローの中で送信されるデフォルトのBoxメール通知を抑制できます。​​ # Box Signの通知の抑制 [Box Sign API](e://post-sign-requests)を使用すると、Box Signのワークフローの中で送信される**デフォルト**のBoxメール通知を抑制できます。​​ この機能により、デフォルトの通知をオフにして、独自のカスタマイズしたメッセージを使用したり、送信する際に経由するチャネルを決定したりすることができます。 ***注**: Box Signのメール通知を抑制することを選択すると、組織は、該当する場合に、使用される配信方法に対して署名者の同意を得ることを含め、適用されるすべての法律と規制に従い、署名プロセスにおいて適切なタイミングで適切な内容を含むすべての通知を署名者に確実に配信する責任を負うことになります。* ## Box Signの新しいWebhook Boxでは、通知の抑制機能とともに、電子サインワークフローのカスタマイズオプションを強化する以下の3つの[Webhook](https://developer.box.com/sign/webhooks/)を新しく導入します。 - `SIGN.REQUEST.SIGNATURE_REQUESTED` - `SIGN.REQUEST.SIGNER_SIGNED` - `SIGN.REQUEST.ERROR_FINALIZING` 上記のWebhookを使用すると、自分のアプリケーションで操作をトリガーしたり、Box Signで発生したイベントについてユーザーに通知したりできます。​​ ## サポート情報 問題がある場合やさらにガイドが必要な場合は、必要なサポートについて、Boxの[Developer Forum](https://forum.box.com/)に英語でリクエストを投稿してください。 **Source:** [https://ja.developer.box.com/changelog/2024-05-08-notification-suppression-for-sign](https://ja.developer.box.com/changelog/2024-05-08-notification-suppression-for-sign) --- ### Box Swift SDK Generated `0.3.0`のリリース **Type:** changelog | **Section:** Changelog Box Swift SDK Generated 0.3.0のリリース バグ修正 ベースURLを変更 (box/box-codegen#491) (#115) (d0a7adb) Box AIエンドポイントを修正 (box/box-openapi#418) (#88) (022f… # Box Swift SDK Generated 0.3.0のリリース ### バグ修正 - ベースURLを変更 (box/box-codegen[#491](https://github.com/box/box-codegen/issues/491)) ([#115](https://github.com/box/box-codegen/issues/115)) ([`d0a7adb`](https://github.com/box/box-codegen/commit/d0a7adb201c823313f0a5de25fa4fc5469590c97)) - Box AIエンドポイントを修正 (box/box-openapi[#418](https://github.com/box/box-codegen/issues/418)) ([#88](https://github.com/box/box-codegen/issues/88)) ([`022f83a`](https://github.com/box/box-codegen/commit/022f83aaa7fbe3f4292a06527875123ecc7b99f0)) - 自動更新のプルリクエストのCIを修正 (box/box-codegen[#506](https://github.com/box/box-codegen/issues/506)) ([#135](https://github.com/box/box-codegen/issues/135)) ([`a62e238`](https://github.com/box/box-codegen/commit/a62e238534cb625dbc98cbe59c98939c78b74f4a)) - Swiftで配列を使用したUnionの逆シリアル化を修正 (box/box-codegen[#486](https://github.com/box/box-codegen/issues/486)) ([#94](https://github.com/box/box-codegen/issues/94)) ([`4f187be`](https://github.com/box/box-codegen/commit/4f187bed1e88c93c1258be8723a39b45129ff21f)) - メタデータフィルタリソースを修正 (box/box-openapi[#419](https://github.com/box/box-codegen/issues/419)) ([#90](https://github.com/box/box-codegen/issues/90)) ([`b04f7ce`](https://github.com/box/box-codegen/commit/b04f7ceee9bca4f1f19d66401f38636e7737b4b1)) - ファイルやフォルダの分類を更新するためのスキーマを修正 (box/box-openapi[#423](https://github.com/box/box-codegen/issues/423)) ([#104](https://github.com/box/box-codegen/issues/104)) ([`caa9d2b`](https://github.com/box/box-codegen/commit/caa9d2b7d0a6c2728f543fa19acb7859f21fb5c9)) - Box Signの表現を改善 (box/box-openapi[#424](https://github.com/box/box-codegen/issues/424)) ([#111](https://github.com/box/box-codegen/issues/111)) ([`4fa69f0`](https://github.com/box/box-codegen/commit/4fa69f01ca3a2a7fc8dcdc71cbecb03c469a83e6)) ### 新機能と機能強化 - 不足していたマーカーページ割りフィールドを追加し、新しいイベントタイプを導入 `(box/box-openapi[#431](https://github.com/box/box-codegen/issues/431))` ([#136](https://github.com/box/box-codegen/issues/136)) ([`b186b11`](https://github.com/box/box-codegen/commit/b186b11a2c591cd4fdd3b50733750a7bb4ec94e9)) - `visionOS`のサポートを追加し、Swift用のPrivacy Manifestファイルを追加 `(box/box-codegen[#510](https://github.com/box/box-codegen/issues/510))` ([#139](https://github.com/box/box-codegen/issues/139)) ([`7fc76fc`](https://github.com/box/box-codegen/commit/7fc76fc1799db0a50ad22eb047d013c4597c5277)) - Swiftで日付のサポートを追加 (box/box-codegen[#488](https://github.com/box/box-codegen/issues/488)) ([#103](https://github.com/box/box-codegen/issues/103)) ([`7e1ea1a`](https://github.com/box/box-codegen/commit/7e1ea1af553cc8458eb9026c777608f7929e686d)) - Swiftでの分割アップロードを改善 `(box/box-codegen[#515](https://github.com/box/box-codegen/issues/515))` ([#143](https://github.com/box/box-codegen/issues/143)) ([`b8099ab`](https://github.com/box/box-codegen/commit/b8099ab41ea5b8706e14285a0f9db2fd3c0a7a6d)) - 通知の抑制をパブリックスキーマに移動 (box/box-openapi[#425](https://github.com/box/box-codegen/issues/425)) ([#113](https://github.com/box/box-codegen/issues/113)) ([`069be60`](https://github.com/box/box-codegen/commit/069be60613889b45b396bbe22262c5f8df32b158)) - スキーマを個別のモジュールに移動 (box/box-codegen[#483](https://github.com/box/box-codegen/issues/483)) ([#99](https://github.com/box/box-codegen/issues/99)) ([`c7a8506`](https://github.com/box/box-codegen/commit/c7a85069544c28e2be918eafd9e240f39660ead3)) - 一般的なエラーのスローを開始 `(box/box-codegen[#516](https://github.com/box/box-codegen/issues/516))` ([#147](https://github.com/box/box-codegen/issues/147)) ([`d12bbb7`](https://github.com/box/box-codegen/commit/d12bbb7d06bd3fcf39c31e316f1047065b56baac)) - Box AIエンドポイントをサポート (box/box-openapi[#416](https://github.com/box/box-codegen/issues/416)) ([#86](https://github.com/box/box-codegen/issues/86)) ([`175ab82`](https://github.com/box/box-codegen/commit/175ab82c18dc390bcd4c8e20aea8e405a2e31c4d)) - Swiftでの分割アップロードをサポート `(box/box-codegen[#513](https://github.com/box/box-codegen/issues/513))` ([#142](https://github.com/box/box-codegen/issues/142)) ([`9e0b4e2`](https://github.com/box/box-codegen/commit/9e0b4e26a9283b5900ae0fe0fa858394b732f51b)) - パーサーのエンドポイントおよびスキーマの除外をサポート (box/box-codegen[#487](https://github.com/box/box-codegen/issues/487)) ([#100](https://github.com/box/box-codegen/issues/100)) ([`af9e171`](https://github.com/box/box-codegen/commit/af9e171c101703c98ff9a53093d7fc9c306137d9)) **Source:** [https://ja.developer.box.com/changelog/2024-06-28-box-swift-sdk-generated-030-released](https://ja.developer.box.com/changelog/2024-06-28-box-swift-sdk-generated-030-released) --- ### Box Swift SDK Generated `0.3.1`のリリース **Type:** changelog | **Section:** Changelog Box Swift SDK Generated 0.3.1のリリース バグ修正 IntegrationMappingPartnerItemSlackをIntegrationMappingPartnerItemSlackUnionに抽出 (box/box-codegen#53… # Box Swift SDK Generated 0.3.1のリリース ### バグ修正 - `IntegrationMappingPartnerItemSlack`を`IntegrationMappingPartnerItemSlackUnion`に抽出 (box/box-codegen[#530](https://github.com/box/box-codegen/issues/530)) ([#165](https://github.com/box/box-codegen/issues/165)) ([`d51df9a`](https://github.com/box/box-codegen/commit/d51df9a19d06db886358e94ce70551c283e5cc45)) - 分割アップロードの信頼性を改善 (box/box-codegen[#529](https://github.com/box/box-codegen/issues/529)) ([#164](https://github.com/box/box-codegen/issues/164)) ([`5d87629`](https://github.com/box/box-codegen/commit/5d876299aa88b18accde22379950780bff100da0)) - ステータスコード202と`Retry-After`ヘッダーが設定されているリクエストを再試行 (box/box-codegen[#538](https://github.com/box/box-codegen/issues/538)) ([#177](https://github.com/box/box-codegen/issues/177)) ([`64f27b3`](https://github.com/box/box-codegen/commit/64f27b3858725adaa53a10a6e8df8c0bcfe73fea)) ### 新機能と機能強化 - ユーザーコラボレーションに`is_active`パラメータを追加 (box/box-openapi[#437](https://github.com/box/box-codegen/issues/437)) ([#163](https://github.com/box/box-codegen/issues/163)) ([`5f726bb`](https://github.com/box/box-codegen/commit/5f726bbffd682934ab5731e1620489b1ee54e5a1)) - Box AIのメソッドに新しいパラメータを追加し、`AiResponseFull`バリアントを導入 (box/box-openapi[#446](https://github.com/box/box-codegen/issues/446)) ([#201](https://github.com/box/box-codegen/issues/201)) ([`7c09090`](https://github.com/box/box-codegen/commit/7c0909032733742cb5a019c897910ced2e9d6788)) - Swift 5.6のサポートを追加 (box/box-codegen[#541](https://github.com/box/box-codegen/issues/541)) ([#180](https://github.com/box/box-codegen/issues/180)) ([`04b7020`](https://github.com/box/box-codegen/commit/04b7020f1220f73ad4637e6033d5539c56a64fcd)) - 分割アップロードのエンドポイントURLをパラメータ化 (box/box-openapi[#444](https://github.com/box/box-codegen/issues/444)) ([#192](https://github.com/box/box-codegen/issues/192)) ([`ea18f9e`](https://github.com/box/box-codegen/commit/ea18f9e5eb6558edb29ff378bceb5528ccd4fcfb)) - AIエージェントAPIをサポート (box/box-codegen[#531](https://github.com/box/box-codegen/issues/531)) ([#170](https://github.com/box/box-codegen/issues/170)) ([`fc9a00b`](https://github.com/box/box-codegen/commit/fc9a00bdcaffeaccfd87caad73fe666fb46c36ab)) **Source:** [https://ja.developer.box.com/changelog/2024-08-22-box-swift-sdk-generated-031-released](https://ja.developer.box.com/changelog/2024-08-22-box-swift-sdk-generated-031-released) --- ### Box Swift SDK Generated `0.4.0`のリリース **Type:** changelog | **Section:** Changelog Box Swift SDK Generated 0.4.0のリリース バグ修正 Signテンプレートの署名者に不足していたフィールドを追加し、AIスキーマを修正 (box/box-openapi#451) (#206) (31920e6) IntegrationMapping… # Box Swift SDK Generated 0.4.0のリリース ### バグ修正 - Signテンプレートの署名者に不足していたフィールドを追加し、AIスキーマを修正 (box/box-openapi[#451](https://github.com/box/box-codegen/issues/451)) ([#206](https://github.com/box/box-codegen/issues/206)) ([`31920e6`](https://github.com/box/box-codegen/commit/31920e67692c16b0600c4c9f4c279e22d02e4598)) - `IntegrationMapping`スキーマを修正 (box/box-codegen[#551](https://github.com/box/box-codegen/issues/551)) ([#203](https://github.com/box/box-codegen/issues/203)) ([`0074ee3`](https://github.com/box/box-codegen/commit/0074ee326627d01057cf50cb257d2291b646ab08)) - Swiftでの分割アップロードを修正 (box/box-codegen[#555](https://github.com/box/box-codegen/issues/555)) ([#215](https://github.com/box/box-codegen/issues/215)) ([`93ff568`](https://github.com/box/box-codegen/commit/93ff5686415d99aa807d57d9e062f5a96380d707)) ### 新機能と機能強化 - `FetchOptions`にURLを追加 (box/box-codegen[#549](https://github.com/box/box-codegen/issues/549)) ([#208](https://github.com/box/box-codegen/issues/208)) ([`b65822d`](https://github.com/box/box-codegen/commit/b65822d379b1d5e9be7b179ed754e725f5a499fa)) **Source:** [https://ja.developer.box.com/changelog/2024-09-05-box-swift-sdk-generated-040-released](https://ja.developer.box.com/changelog/2024-09-05-box-swift-sdk-generated-040-released) --- ### Box Swift SDK Generated `0.5.0`のリリース **Type:** changelog | **Section:** Changelog Box Swift SDK Generated 0.5.0のリリース バグ修正 メタデータクエリの結果のバリアントを修正 (box/box-openapi#456) (#232) (be2fa52) 新機能と機能強化 Hubsベータ版を追加 (box/box-openapi… # Box Swift SDK Generated 0.5.0のリリース ### バグ修正 - メタデータクエリの結果のバリアントを修正 (box/box-openapi[#456](https://github.com/box/box-codegen/issues/456)) ([#232](https://github.com/box/box-codegen/issues/232)) ([`be2fa52`](https://github.com/box/box-codegen/commit/be2fa52bb0d086f6c9b20fd5c3bdcad4b98f3f37)) ### 新機能と機能強化 - Hubsベータ版を追加 (box/box-openapi[#453](https://github.com/box/box-codegen/issues/453)) ([#220](https://github.com/box/box-codegen/issues/220)) ([`546f487`](https://github.com/box/box-codegen/commit/546f487bde9dae2407ff65620eb6e6a81e45b149)) **Source:** [https://ja.developer.box.com/changelog/2024-09-11-box-swift-sdk-generated-050-released](https://ja.developer.box.com/changelog/2024-09-11-box-swift-sdk-generated-050-released) --- ### Box Swift SDK Generated `0.6.1`のリリース **Type:** changelog | **Section:** Changelog Box Swift SDK Generated 0.6.1のリリース バグ修正 verification_phone_numberプロパティを追加して署名リクエストを作成 (box/box-openapi#515) (#391) (717b3a… # Box Swift SDK Generated 0.6.1のリリース ### バグ修正 - `verification_phone_number`プロパティを追加して署名リクエストを作成 (box/box-openapi[#515](https://github.com/box/box-swift-sdk-gen/issues/515)) ([#391](https://github.com/box/box-swift-sdk-gen/issues/391)) ([`717b3a8`](https://github.com/box/box-swift-sdk-gen/commit/717b3a8b285dfab92a9446cbd84443caa8dde148)) ### 新機能と機能強化 - 共有リンクのアプリ項目を検索するエンドポイントを追加 (box/box-openapi[#514](https://github.com/box/box-swift-sdk-gen/issues/514)) ([#390](https://github.com/box/box-swift-sdk-gen/issues/390)) ([`07b9be5`](https://github.com/box/box-swift-sdk-gen/commit/07b9be5d523f3d3fb89bdbb240e4ca9628a3736d)) - Hubsのサポートを`/ai/ask`に追加 (box/box-codegen[#656](https://github.com/box/box-swift-sdk-gen/issues/656)) ([#364](https://github.com/box/box-swift-sdk-gen/issues/364)) ([`9a49864`](https://github.com/box/box-swift-sdk-gen/commit/9a4986499eaefffdb4f2593968d59eaf030f516f)) - Teams統合マッピング (リスト) APIを追加 (box/box-openapi[#517](https://github.com/box/box-swift-sdk-gen/issues/517)) ([#393](https://github.com/box/box-swift-sdk-gen/issues/393)) ([`b9ed4e3`](https://github.com/box/box-swift-sdk-gen/commit/b9ed4e35d17f85c1d2bc2a4e9e148ae009551348)) - 認証クラス用のトークンストレージを公開 (box/box-codegen[#682](https://github.com/box/box-swift-sdk-gen/issues/682)) ([#400](https://github.com/box/box-swift-sdk-gen/issues/400)) ([`08221e5`](https://github.com/box/box-swift-sdk-gen/commit/08221e59cabc4042ea1d43bf578c2069ad66b444)) - AI Studio APIをサポート (box/box-codegen[#626](https://github.com/box/box-swift-sdk-gen/issues/626)) ([#375](https://github.com/box/box-swift-sdk-gen/issues/375)) ([`802571d`](https://github.com/box/box-swift-sdk-gen/commit/802571dd34977ae2ebf674dbdddd3e140829b819)) - 不明な列挙値をサポート (box/box-codegen[#670](https://github.com/box/box-swift-sdk-gen/issues/670)) ([#382](https://github.com/box/box-swift-sdk-gen/issues/382)) ([`8fe7ff4`](https://github.com/box/box-swift-sdk-gen/commit/8fe7ff45fa4e45f743acd4450270d945b0afd393)) - 事前チェックを伴うアップロードをサポート (box/box-codegen[#676](https://github.com/box/box-swift-sdk-gen/issues/676)) ([#399](https://github.com/box/box-swift-sdk-gen/issues/399)) ([`1befb4c`](https://github.com/box/box-swift-sdk-gen/commit/1befb4c1b4898375ea3ab353c7149fd10adc1f17)) - `/ai/extract_structured`レスポンスのスキーマを更新 (box/box-codegen[#641](https://github.com/box/box-swift-sdk-gen/issues/641)) ([#358](https://github.com/box/box-swift-sdk-gen/issues/358)) ([`430611a`](https://github.com/box/box-swift-sdk-gen/commit/430611a0036258d5f3ff8e1c6de0b833255ce0ed)) **Source:** [https://ja.developer.box.com/changelog/2025-03-18-box-swift-sdk-generated-061-released](https://ja.developer.box.com/changelog/2025-03-18-box-swift-sdk-generated-061-released) --- ### Box Swift SDK Generated `0.6.2`のリリース **Type:** changelog | **Section:** Changelog Box Swift SDK Generated 0.6.2のリリース バグ修正 トークンの取得にretrieveTokenメソッドを使用するようダウンスコープトークンを修正 (box/box-codegen#731) (#459) (8992b32) クエリパラメータへのDate… # Box Swift SDK Generated 0.6.2のリリース ### バグ修正 - トークンの取得に`retrieveToken`メソッドを使用するようダウンスコープトークンを修正 (box/box-codegen[#731](https://github.com/box/box-swift-sdk-gen/issues/731)) ([#459](https://github.com/box/box-swift-sdk-gen/issues/459)) ([`8992b32`](https://github.com/box/box-swift-sdk-gen/commit/8992b32e9dd058fc77b4d68418da81b162aea315)) - クエリパラメータへの`Date`の解析を修正 (box/box-codegen[#729](https://github.com/box/box-swift-sdk-gen/issues/729)) ([#449](https://github.com/box/box-swift-sdk-gen/issues/449)) ([`1a95d0c`](https://github.com/box/box-swift-sdk-gen/commit/1a95d0c80e0bd29dc1b467e7e98e6f5e6196ddfb)) - イベントの`next_stream_position`プロパティタイプを`int64`に指定 (box/box-openapi[#535](https://github.com/box/box-swift-sdk-gen/issues/535)) ([#502](https://github.com/box/box-swift-sdk-gen/issues/502)) ([`795fe1c`](https://github.com/box/box-swift-sdk-gen/commit/795fe1c7f0aa6074145b675fce4dd8e1432b0a64)) ### 新機能と機能強化 - `downloadZip`メソッドを追加 (box/box-codegen[#765](https://github.com/box/box-swift-sdk-gen/issues/765)) ([#505](https://github.com/box/box-swift-sdk-gen/issues/505)) ([`c03589d`](https://github.com/box/box-swift-sdk-gen/commit/c03589d6add3ee6d548f10b5380031cd38284e42)) - `rawData`プロパティを追加 (box/box-codegen[#724](https://github.com/box/box-swift-sdk-gen/issues/724)) ([#445](https://github.com/box/box-swift-sdk-gen/issues/445)) ([`77405ad`](https://github.com/box/box-swift-sdk-gen/commit/77405adc986adb8a1ce3bcff051ea8c481dbfd9d)) - AIエージェントの警告を追加し、より多くの種類のメタデータ値を許可 (box/box-openapi[#520](https://github.com/box/box-swift-sdk-gen/issues/520)) ([#435](https://github.com/box/box-swift-sdk-gen/issues/435)) ([`af1dc12`](https://github.com/box/box-swift-sdk-gen/commit/af1dc12763f9a84691573fd3ba8307925fc017d6)) - AIスプレッドシートプロセッサを追加 (box/box-openapi[#533](https://github.com/box/box-swift-sdk-gen/issues/533)) ([#484](https://github.com/box/box-swift-sdk-gen/issues/484)) ([`14726d1`](https://github.com/box/box-swift-sdk-gen/commit/14726d1952f5ddb2414f723a0b18fa5226269a64)) - アーカイブの公開APIを追加 (box/box-openapi[#540](https://github.com/box/box-swift-sdk-gen/issues/540)) ([#509](https://github.com/box/box-swift-sdk-gen/issues/509)) ([`8266386`](https://github.com/box/box-swift-sdk-gen/commit/82663868c61a31f43b229c6f24e29737913662a0)) - SwiftのCIを追加 (box/box-codegen[#755](https://github.com/box/box-swift-sdk-gen/issues/755)) ([#494](https://github.com/box/box-swift-sdk-gen/issues/494)) ([`76a3337`](https://github.com/box/box-swift-sdk-gen/commit/76a3337bed9bfc4629ec7dcb9af86bec4aa710f3)) - Hubs APIのベータ版エンドポイントを追加 (box/box-openapi[#531](https://github.com/box/box-swift-sdk-gen/issues/531)) ([#476](https://github.com/box/box-swift-sdk-gen/issues/476)) ([`a05aa5f`](https://github.com/box/box-swift-sdk-gen/commit/a05aa5fe2aaade1d7bdd7acb90c82fcb3a3bf262)) - 新しいHubs APIとHubの項目APIを追加 (box/box-openapi[#538](https://github.com/box/box-swift-sdk-gen/issues/538)) ([#503](https://github.com/box/box-swift-sdk-gen/issues/503)) ([`9058c45`](https://github.com/box/box-swift-sdk-gen/commit/9058c45c0bcd3e7f294a1bedac151637001aec63)) - `Metadata Error`の新しいスキーマを追加 (box/box-openapi[#539](https://github.com/box/box-swift-sdk-gen/issues/539)) ([#504](https://github.com/box/box-swift-sdk-gen/issues/504)) ([`2e9ecf9`](https://github.com/box/box-swift-sdk-gen/commit/2e9ecf9477854656958b715674b8aa0413508d31)) - Signテンプレートスキーマにセキュリティ設定のプロパティを追加 (box/box-openapi[#518](https://github.com/box/box-swift-sdk-gen/issues/518)) ([#426](https://github.com/box/box-swift-sdk-gen/issues/426)) ([`a741a73`](https://github.com/box/box-swift-sdk-gen/commit/a741a7305e2b2d174bc325e35ea9b77548a38095)) - ShieldリストAPIを追加 (box/box-openapi[#528](https://github.com/box/box-swift-sdk-gen/issues/528)) ([#462](https://github.com/box/box-swift-sdk-gen/issues/462)) ([`b5993b0`](https://github.com/box/box-swift-sdk-gen/commit/b5993b096b4fceb77301f76eba1c17225b2844d6)) - 任意の値が設定された`additionalProperties`のサポートを追加 (box/box-codegen[#711](https://github.com/box/box-swift-sdk-gen/issues/711)) ([#427](https://github.com/box/box-swift-sdk-gen/issues/427)) ([`7fbf706`](https://github.com/box/box-swift-sdk-gen/commit/7fbf7069eff66afddc328066f8aeb7321b249eea)) - `nullable`フィールドのサポートを追加 (box/box-codegen[#700](https://github.com/box/box-swift-sdk-gen/issues/700)) ([#420](https://github.com/box/box-swift-sdk-gen/issues/420)) ([`5d0ff41`](https://github.com/box/box-swift-sdk-gen/commit/5d0ff414b325db92db44c580cebb5636ab33553f)) - AI APIにIBMモデルのサポートを追加 (box/box-openapi[#522](https://github.com/box/box-swift-sdk-gen/issues/522)) ([#436](https://github.com/box/box-swift-sdk-gen/issues/436)) ([`0717222`](https://github.com/box/box-swift-sdk-gen/commit/071722246402e0ec2439ae1e5e3d26bca45a049f)) - `BoxClient`で`makeRequest`メソッドを公開 (box/box-codegen[#687](https://github.com/box/box-swift-sdk-gen/issues/687)) ([#408](https://github.com/box/box-swift-sdk-gen/issues/408)) ([`7ba7d09`](https://github.com/box/box-swift-sdk-gen/commit/7ba7d091b0c832276daa571fad2a7db75469676d)) - AI統合テストを改善 (box/box-codegen[#758](https://github.com/box/box-swift-sdk-gen/issues/758)) ([#499](https://github.com/box/box-swift-sdk-gen/issues/499)) ([`3c7e717`](https://github.com/box/box-swift-sdk-gen/commit/3c7e717c6ca076caf1a963b3f60d3bd88f8c4bff)) - `BoxAPIError`をスローする際にレスポンスの本文をサニタイズ (box/box-codegen[#760](https://github.com/box/box-swift-sdk-gen/issues/760)) ([#498](https://github.com/box/box-swift-sdk-gen/issues/498)) ([`2afc793`](https://github.com/box/box-swift-sdk-gen/commit/2afc7936dac87dee22adff3e22def92913f5854c)) - Swiftで`getDownloadUrl`をサポート (box/box-codegen[#751](https://github.com/box/box-swift-sdk-gen/issues/751)) ([#491](https://github.com/box/box-swift-sdk-gen/issues/491)) ([`5916ede`](https://github.com/box/box-swift-sdk-gen/commit/5916ede7454a1926de195e77b9a158c2af0fae2b)) - AI Studioの新しいツールをサポート (box/box-openapi[#534](https://github.com/box/box-swift-sdk-gen/issues/534)) ([#485](https://github.com/box/box-swift-sdk-gen/issues/485)) ([`e793d7b`](https://github.com/box/box-swift-sdk-gen/commit/e793d7b3a03e8d58ce6adb63a894a0330ae154d1)) - エラーの機密データのサニタイズをサポート (box/box-codegen[#695](https://github.com/box/box-swift-sdk-gen/issues/695)) ([#415](https://github.com/box/box-swift-sdk-gen/issues/415)) ([`330ca9a`](https://github.com/box/box-swift-sdk-gen/commit/330ca9ad17cbc79c93ffb114fd56c09a41f92694)) - リーガルホールドとAIモデルを更新 (box/box-openapi[#526](https://github.com/box/box-swift-sdk-gen/issues/526)) ([#460](https://github.com/box/box-swift-sdk-gen/issues/460)) ([`caa848a`](https://github.com/box/box-swift-sdk-gen/commit/caa848ac977c7fedeacbe018339d27b9d948bb1e)) **Source:** [https://ja.developer.box.com/changelog/2025-08-13-box-swift-sdk-generated-062-released](https://ja.developer.box.com/changelog/2025-08-13-box-swift-sdk-generated-062-released) --- ### Box TypeScript SDK Generated `v1.1.0`のリリース **Type:** changelog | **Section:** Changelog Box TypeScript SDK Generated v1.1.0のリリース バグ修正 自動更新のプルリクエストのCIを修正 (box/box-codegen#506) (#221) (bbc14f6) queryParamsで日付またはdatetime… # Box TypeScript SDK Generated v1.1.0のリリース ### バグ修正 - 自動更新のプルリクエストのCIを修正 (`box/box-codegen`[#506](https://github.com/box/box-typescript-sdk-gen/issues/506)) ([#221](https://github.com/box/box-typescript-sdk-gen/issues/221)) ([`bbc14f6`](https://github.com/box/box-typescript-sdk-gen/commit/bbc14f66e14a9386c8d54a5d0bb36ec2cdc501c1)) - `queryParams`で日付または`datetime`が使用されている場合に引用符を削除 (box/`box-codegen`[#509](https://github.com/box/box-typescript-sdk-gen/issues/509)) ([#225](https://github.com/box/box-typescript-sdk-gen/issues/225)) ([`28d2220`](https://github.com/box/box-typescript-sdk-gen/commit/28d22200602cf02d73590189c304109f1c26db17)) ### 新機能と機能強化 - 不足していたマーカーページ割りフィールドを追加し、新しいイベントタイプ`AppItemEventSource` `(box/box-openapi[#431](https://github.com/box/box-typescript-sdk-gen/issues/431))`を導入 ([#224](https://github.com/box/box-typescript-sdk-gen/issues/224)) ([`6c18ca3`](https://github.com/box/box-typescript-sdk-gen/commit/6c18ca3b00da0b878d28e142a2361b6386ef0c15)) **Source:** [https://ja.developer.box.com/changelog/2024-06-12-box-typescript-sdk-generated-v110-released](https://ja.developer.box.com/changelog/2024-06-12-box-typescript-sdk-generated-v110-released) --- ### Box TypeScript SDK Generated `v1.10.0`のリリース **Type:** changelog | **Section:** Changelog Box TypeScript SDK Generated v1.10.0のリリース バグ修正 SignRequestから未使用のパラメータを削除 (box/box-openapi#489) (#450) (f5683b… # Box TypeScript SDK Generated v1.10.0のリリース ### バグ修正 - `SignRequest`から未使用のパラメータを削除 (box/box-openapi[#489](https://github.com/box/box-typescript-sdk-gen/issues/489)) ([#450](https://github.com/box/box-typescript-sdk-gen/issues/450)) ([`f5683b7`](https://github.com/box/box-typescript-sdk-gen/commit/f5683b703625dd8d504ca52100f692cb8440a474)) ### 新機能と機能強化 - ネットワーククライアントの実装を置き換えるサポートを追加 (box/box-codegen[#629](https://github.com/box/box-typescript-sdk-gen/issues/629)) ([#454](https://github.com/box/box-typescript-sdk-gen/issues/454)) ([`1cb7ddb`](https://github.com/box/box-typescript-sdk-gen/commit/1cb7ddb3ada79cebc27fbfce9df90cd8ebad353c)) - 再試行戦略のカスタマイズを許可 (box/box-codegen[#635](https://github.com/box/box-typescript-sdk-gen/issues/635)) ([#457](https://github.com/box/box-typescript-sdk-gen/issues/457)) ([`530ca33`](https://github.com/box/box-typescript-sdk-gen/commit/530ca33ff3635581bd8ee91a82bc9f000b18812b)) - Webhookメッセージの検証をサポート (box/box-codegen[#631](https://github.com/box/box-typescript-sdk-gen/issues/631)) ([#455](https://github.com/box/box-typescript-sdk-gen/issues/455)) ([`09765a4`](https://github.com/box/box-typescript-sdk-gen/commit/09765a42fe25f15095bd1bd0d1377f2da222c9e4)) **Source:** [https://ja.developer.box.com/changelog/2024-12-30-box-typescript-sdk-generated-v1100-released](https://ja.developer.box.com/changelog/2024-12-30-box-typescript-sdk-generated-v1100-released) --- ### Box TypeScript SDK Generated `v1.12.0`のリリース **Type:** changelog | **Section:** Changelog Box TypeScript SDK Generated v1.12.0のリリース 新機能と機能強化 Box Signの共有リクエストを追加 (box/box-openapi#504) (#491) (e90255c) 機能: /ai/askにHubのサポートを追加。AiAsk… # Box TypeScript SDK Generated v1.12.0のリリース ### 新機能と機能強化 - Box Signの共有リクエストを追加 (box/box-openapi[#504](https://github.com/box/box-typescript-sdk-gen/issues/504)) ([#491](https://github.com/box/box-typescript-sdk-gen/issues/491)) ([`e90255c`](https://github.com/box/box-typescript-sdk-gen/commit/e90255c5d97a7a1a10dd529b58426142c5c6f0d4)) - 機能: `/ai/ask`にHubのサポートを追加。`AiAsk`インターフェースの`items`プロパティのタイプを`AiItemBase[]`から`AiItemAsk[]`に置き換え (box/box-codegen[#656](https://github.com/box/box-typescript-sdk-gen/issues/656)) ([#507](https://github.com/box/box-typescript-sdk-gen/issues/507)) ([`9f29d8c`](https://github.com/box/box-typescript-sdk-gen/commit/9f29d8cb1f1d3b8c7625da1ddb9f2abd62d133f0)) - `/ai/extract_structured`レスポンスのスキーマを更新 (box/box-codegen[#641](https://github.com/box/box-typescript-sdk-gen/issues/641)) ([#498](https://github.com/box/box-typescript-sdk-gen/issues/498)) ([`502ac11`](https://github.com/box/box-typescript-sdk-gen/commit/502ac11a2ad4e56fceece0deb6a15dbfc8b429ff)) **Source:** [https://ja.developer.box.com/changelog/2025-02-06-box-typescript-sdk-generated-v1120-released](https://ja.developer.box.com/changelog/2025-02-06-box-typescript-sdk-generated-v1120-released) --- ### Box TypeScript SDK Generated `v1.13.0`のリリース **Type:** changelog | **Section:** Changelog Box TypeScript SDK Generated v1.13.0のリリース 新機能と機能強化 AI Studio APIをサポート (box/box-codegen#626) (#520) (949b856) # Box TypeScript SDK Generated v1.13.0のリリース ### 新機能と機能強化 - AI Studio APIをサポート (box/box-codegen[#626](https://github.com/box/box-typescript-sdk-gen/issues/626)) ([#520](https://github.com/box/box-typescript-sdk-gen/issues/520)) ([`949b856`](https://github.com/box/box-typescript-sdk-gen/commit/949b856ce1d77b1aa425b91b46440b46b383438a)) **Source:** [https://ja.developer.box.com/changelog/2025-02-20-box-typescript-sdk-generated-v1130-released](https://ja.developer.box.com/changelog/2025-02-20-box-typescript-sdk-generated-v1130-released) --- ### Box TypeScript SDK Generated `v1.13.1`のリリース **Type:** changelog | **Section:** Changelog Box TypeScript SDK Generated v1.13.1のリリース バグ修正 TypeScriptのpackage.jsonでブラウザ構成を分割 (box/box-codegen#672) (#538) (ca7e291) # Box TypeScript SDK Generated v1.13.1のリリース ### バグ修正 - TypeScriptの`package.json`でブラウザ構成を分割 (box/box-codegen[#672](https://github.com/box/box-typescript-sdk-gen/issues/672)) ([#538](https://github.com/box/box-typescript-sdk-gen/issues/538)) ([`ca7e291`](https://github.com/box/box-typescript-sdk-gen/commit/ca7e29180e450cbb346a76aadfdade1062559b1e)) **Source:** [https://ja.developer.box.com/changelog/2025-03-07-box-typescript-sdk-generated-v1131-released](https://ja.developer.box.com/changelog/2025-03-07-box-typescript-sdk-generated-v1131-released) --- ### Box TypeScript SDK Generated `v1.13.2`のリリース **Type:** changelog | **Section:** Changelog Box TypeScript SDK Generated v1.13.2のリリース バグ修正 Typescriptのrollupプラグインの出力ディレクトリを修正 (box/box-codegen#678) (#543) (f828d5e) # Box TypeScript SDK Generated v1.13.2のリリース ### バグ修正 - Typescriptの`rollup`プラグインの出力ディレクトリを修正 (box/box-codegen[#678](https://github.com/box/box-typescript-sdk-gen/issues/678)) ([#543](https://github.com/box/box-typescript-sdk-gen/issues/543)) ([`f828d5e`](https://github.com/box/box-typescript-sdk-gen/commit/f828d5e7e3079c48590e9766f0dccd25ee1af9ca)) **Source:** [https://ja.developer.box.com/changelog/2025-03-11-box-typescript-sdk-generated-v1132-released](https://ja.developer.box.com/changelog/2025-03-11-box-typescript-sdk-generated-v1132-released) --- ### Box TypeScript SDK Generated `v1.14.0`のリリース **Type:** changelog | **Section:** Changelog Box TypeScript SDK Generated v1.14.0のリリース バグ修正 verification_phone_numberプロパティを追加して署名リクエストを作成 (box/box-openapi#515) (#546) (916502c… # Box TypeScript SDK Generated v1.14.0のリリース ### バグ修正 - `verification_phone_number`プロパティを追加して署名リクエストを作成 (box/box-openapi[#515](https://github.com/box/box-typescript-sdk-gen/issues/515)) ([#546](https://github.com/box/box-typescript-sdk-gen/issues/546)) ([`916502c`](https://github.com/box/box-typescript-sdk-gen/commit/916502c47cb4936ab93a40b3f1552c1860173a8e)) ### 新機能と機能強化 - 共有リンクのアプリ項目を検索するエンドポイントを追加 (box/box-openapi[#514](https://github.com/box/box-typescript-sdk-gen/issues/514)) ([#545](https://github.com/box/box-typescript-sdk-gen/issues/545)) ([`7c32eaf`](https://github.com/box/box-typescript-sdk-gen/commit/7c32eaf2af3ef08299d9dd69e744304b20f4309f)) - Teams統合マッピング (リスト) APIを追加 (box/box-openapi[#517](https://github.com/box/box-typescript-sdk-gen/issues/517)) ([#548](https://github.com/box/box-typescript-sdk-gen/issues/548)) ([`6ce1c7c`](https://github.com/box/box-typescript-sdk-gen/commit/6ce1c7c78c9bc5d70383065e95f01bc8133fdd52)) - 事前チェックを伴うアップロードをサポート (box/box-codegen[#676](https://github.com/box/box-typescript-sdk-gen/issues/676)) ([#554](https://github.com/box/box-typescript-sdk-gen/issues/554)) ([`e3aa784`](https://github.com/box/box-typescript-sdk-gen/commit/e3aa784b73c7b473fdf06c05c7f657a54fc08e4c)) **Source:** [https://ja.developer.box.com/changelog/2025-03-18-box-typescript-sdk-generated-v1140-released](https://ja.developer.box.com/changelog/2025-03-18-box-typescript-sdk-generated-v1140-released) --- ### Box TypeScript SDK Generated `v1.15.0`のリリース **Type:** changelog | **Section:** Changelog Box TypeScript SDK Generated v1.15.0のリリース 新機能と機能強化 エラーの機密データのサニタイズをサポート (box/box-codegen#695) (#573) (488e76a) # Box TypeScript SDK Generated v1.15.0のリリース ### 新機能と機能強化 - エラーの機密データのサニタイズをサポート (box/box-codegen[#695](https://github.com/box/box-typescript-sdk-gen/issues/695)) ([#573](https://github.com/box/box-typescript-sdk-gen/issues/573)) ([`488e76a`](https://github.com/box/box-typescript-sdk-gen/commit/488e76a1e1f66d5d4ac56b16e6a7dae9e7f497a1)) **Source:** [https://ja.developer.box.com/changelog/2025-04-10-box-typescript-sdk-generated-v1150-released](https://ja.developer.box.com/changelog/2025-04-10-box-typescript-sdk-generated-v1150-released) --- ### Box TypeScript SDK Generated `v1.15.1`のリリース **Type:** changelog | **Section:** Changelog Box TypeScript SDK Generated v1.15.1のリリース バグ修正 TypeScriptのデータのサニタイズを修正 (box/box-codegen#702) (#582) (eb79c0f) # Box TypeScript SDK Generated v1.15.1のリリース ### バグ修正 - TypeScriptのデータのサニタイズを修正 (box/box-codegen[#702](https://github.com/box/box-typescript-sdk-gen/issues/702)) ([#582](https://github.com/box/box-typescript-sdk-gen/issues/582)) ([`eb79c0f`](https://github.com/box/box-typescript-sdk-gen/commit/eb79c0faa11f40667289155e71b8893a96eb558a)) **Source:** [https://ja.developer.box.com/changelog/2025-04-11-box-typescript-sdk-generated-v1151-released](https://ja.developer.box.com/changelog/2025-04-11-box-typescript-sdk-generated-v1151-released) --- ### Box TypeScript SDK Generated `v1.16.0`のリリース **Type:** changelog | **Section:** Changelog Box TypeScript SDK Generated v1.16.0のリリース バグ修正 本文をエスケープする場合としない場合のWebhook署名を計算 (box/box-codegen#737) (#627) (6a21b8e) boxNetworkClient… # Box TypeScript SDK Generated v1.16.0のリリース ### バグ修正 - 本文をエスケープする場合としない場合のWebhook署名を計算 (box/box-codegen[#737](https://github.com/box/box-typescript-sdk-gen/issues/737)) ([#627](https://github.com/box/box-typescript-sdk-gen/issues/627)) ([`6a21b8e`](https://github.com/box/box-typescript-sdk-gen/commit/6a21b8ed54ef26041feccaa5481951355965e514)) - `boxNetworkClient`の循環依存関係を修正 (box/box-codegen[#708](https://github.com/box/box-typescript-sdk-gen/issues/708)) ([#591](https://github.com/box/box-typescript-sdk-gen/issues/591)) ([`b383889`](https://github.com/box/box-typescript-sdk-gen/commit/b383889b9fdc91c6cfed7169e4d36a22a8c8a0fa)) - トークンの取得に`retrieveToken`メソッドを使用するようダウンスコープトークンを修正 (box/box-codegen[#731](https://github.com/box/box-typescript-sdk-gen/issues/731)) ([#618](https://github.com/box/box-typescript-sdk-gen/issues/618)) ([`90edb0c`](https://github.com/box/box-typescript-sdk-gen/commit/90edb0cc9bddc474c20b8b83770a4d314843edab)) - Webhook署名を計算する際のスラッシュのエスケープを修正 (box/box-codegen[#736](https://github.com/box/box-typescript-sdk-gen/issues/736)) ([#624](https://github.com/box/box-typescript-sdk-gen/issues/624)) ([`a0307d0`](https://github.com/box/box-typescript-sdk-gen/commit/a0307d0c4c5dfed1a66e395a1dfb4c8ff387561d)) - メタデータフィルタで文字列のリストを処理 (box/box-codegen[#716](https://github.com/box/box-typescript-sdk-gen/issues/716)) ([#597](https://github.com/box/box-typescript-sdk-gen/issues/597)) ([`979ff2c`](https://github.com/box/box-typescript-sdk-gen/commit/979ff2c82edce9a969444febf1896d866ca154bf)) - メモリにコンテンツを格納しないようにファイルのダウンロードを改善 (box/box-codegen[#701](https://github.com/box/box-typescript-sdk-gen/issues/701)) ([#589](https://github.com/box/box-typescript-sdk-gen/issues/589)) ([`513a15e`](https://github.com/box/box-typescript-sdk-gen/commit/513a15eb28736d28d665324949d145dd3387d27d)) - ブラウザのユーティリティ関数を変更 (box/box-codegen[#686](https://github.com/box/box-typescript-sdk-gen/issues/686)) ([#585](https://github.com/box/box-typescript-sdk-gen/issues/585)) ([`7232170`](https://github.com/box/box-typescript-sdk-gen/commit/7232170fe7901cb7ba9ebf79ffc6a7c0b376a1c8)) - HMAC署名に定数時間比較を使用 (box/box-codegen[#739](https://github.com/box/box-typescript-sdk-gen/issues/739)) ([#630](https://github.com/box/box-typescript-sdk-gen/issues/630)) ([`efdcaaf`](https://github.com/box/box-typescript-sdk-gen/commit/efdcaaf605fc6f14bbbf171e2797d73e97302bfe)) ### 新機能と機能強化 - AIエージェントの警告を追加し、より多くの種類のメタデータ値を許可 (box/box-openapi[#520](https://github.com/box/box-typescript-sdk-gen/issues/520)) ([#600](https://github.com/box/box-typescript-sdk-gen/issues/600)) ([`a5a555f`](https://github.com/box/box-typescript-sdk-gen/commit/a5a555f835df5b550b9839e3e1fcff5d9f2b9f96)) - Signテンプレートスキーマにセキュリティ設定のプロパティを追加 (box/box-openapi[#518](https://github.com/box/box-typescript-sdk-gen/issues/518)) ([#588](https://github.com/box/box-typescript-sdk-gen/issues/588)) ([`dfd3e5f`](https://github.com/box/box-typescript-sdk-gen/commit/dfd3e5f7ecf8a8e49d79ed7df4d7e1f88f3e8537)) - ShieldリストのAPIを追加 (box/box-openapi[#528](https://github.com/box/box-typescript-sdk-gen/issues/528)) ([#622](https://github.com/box/box-typescript-sdk-gen/issues/622)) ([`be3af44`](https://github.com/box/box-typescript-sdk-gen/commit/be3af441a66da02254d38576bb9ec258142f6d2d)) - AI APIにIBMモデルのサポートを追加 (box/box-openapi[#522](https://github.com/box/box-typescript-sdk-gen/issues/522)) ([#601](https://github.com/box/box-typescript-sdk-gen/issues/601)) ([`b060b8c`](https://github.com/box/box-typescript-sdk-gen/commit/b060b8c21a13abdfb12988f9c6e6beb014fa104f)) - AI抽出エンドポイントの項目数の上限を引き上げ (box/box-openapi[#525](https://github.com/box/box-typescript-sdk-gen/issues/525)) ([#602](https://github.com/box/box-typescript-sdk-gen/issues/602)) ([`86c5d14`](https://github.com/box/box-typescript-sdk-gen/commit/86c5d14bafe8789c306a1688bcf010207c302ca9)) - リーガルホールドとAIモデルを更新 (box/box-openapi[#526](https://github.com/box/box-typescript-sdk-gen/issues/526)) ([#620](https://github.com/box/box-typescript-sdk-gen/issues/620)) ([`de3df57`](https://github.com/box/box-typescript-sdk-gen/commit/de3df57cc90577a49ea40de278bde423d17c4f06)) **Source:** [https://ja.developer.box.com/changelog/2025-06-12-box-typescript-sdk-generated-v1160-released](https://ja.developer.box.com/changelog/2025-06-12-box-typescript-sdk-generated-v1160-released) --- ### Box TypeScript SDK Generated `v1.17.0`のリリース **Type:** changelog | **Section:** Changelog Box TypeScript SDK Generated v1.17.0のリリース バグ修正 form-dataに関するCVE-2025-7783を解決するためにcypressを昇格 (box/box-codegen#769) (#677) (077413e… # Box TypeScript SDK Generated v1.17.0のリリース ### バグ修正 - `form-data`に関する`CVE-2025-7783`を解決するために`cypress`を昇格 (box/box-codegen[#769](https://github.com/box/box-typescript-sdk-gen/issues/769)) ([#677](https://github.com/box/box-typescript-sdk-gen/issues/677)) ([`077413e`](https://github.com/box/box-typescript-sdk-gen/commit/077413ec525fad4d8ebc4c7209fce20046731295)) ### 新機能と機能強化 - AIスプレッドシートプロセッサを追加 (box/box-openapi[#533](https://github.com/box/box-typescript-sdk-gen/issues/533)) ([#649](https://github.com/box/box-typescript-sdk-gen/issues/649)) ([`254fb54`](https://github.com/box/box-typescript-sdk-gen/commit/254fb54d928ec3a76304674f341be1c67d78a143)) - アーカイブの公開APIを追加 (box/box-openapi[#540](https://github.com/box/box-typescript-sdk-gen/issues/540)) ([#674](https://github.com/box/box-typescript-sdk-gen/issues/674)) ([`1cbb124`](https://github.com/box/box-typescript-sdk-gen/commit/1cbb12485a417b813df8b6918cf3721ae781a286)) - 新しいHubs APIとHubの項目APIを追加 (box/box-openapi[#538](https://github.com/box/box-typescript-sdk-gen/issues/538)) ([#666](https://github.com/box/box-typescript-sdk-gen/issues/666)) ([`25c9596`](https://github.com/box/box-typescript-sdk-gen/commit/25c9596bc71fe88e0a2b6d5e01c65fa682c2fd38)) - `Metadata Error`の新しいスキーマを追加 (box/box-openapi[#539](https://github.com/box/box-typescript-sdk-gen/issues/539)) ([#667](https://github.com/box/box-typescript-sdk-gen/issues/667)) ([`9af46ab`](https://github.com/box/box-typescript-sdk-gen/commit/9af46abe837ee0d812bcc15f1edf0d5a6530bfe0)) - JWTの秘密キー復号メカニズムの挿入を許可 (box/box-codegen[#754](https://github.com/box/box-typescript-sdk-gen/issues/754)) ([#656](https://github.com/box/box-typescript-sdk-gen/issues/656)) ([`cb0c35d`](https://github.com/box/box-typescript-sdk-gen/commit/cb0c35df4a5b3f9b8c611006dd33d480949a0d36)) - Webhookの検証チェックを改善 (box/box-codegen[#745](https://github.com/box/box-typescript-sdk-gen/issues/745)) ([#647](https://github.com/box/box-typescript-sdk-gen/issues/647)) ([`98b3b92`](https://github.com/box/box-typescript-sdk-gen/commit/98b3b9293ff3f0e5922d0772d87504770bb9303c)) - ネットワークの例外でリクエストを再試行 (box/box-codegen[#776](https://github.com/box/box-typescript-sdk-gen/issues/776)) ([#684](https://github.com/box/box-typescript-sdk-gen/issues/684)) ([`c0c4dba`](https://github.com/box/box-typescript-sdk-gen/commit/c0c4dbac40970d34da4c9e52fc43f029ae2f91a6)) - ESMビルドとツリーシェイキングをサポート (box/box-codegen[#762](https://github.com/box/box-typescript-sdk-gen/issues/762)) ([#663](https://github.com/box/box-typescript-sdk-gen/issues/663)) ([`8ca3302`](https://github.com/box/box-typescript-sdk-gen/commit/8ca33023d904edd596819c7c6df42022006274ed)) - Hubsのベータ版エンドポイントをサポート (box/box-openapi[#531](https://github.com/box/box-typescript-sdk-gen/issues/531)) ([#641](https://github.com/box/box-typescript-sdk-gen/issues/641)) ([`d8c7bb6`](https://github.com/box/box-typescript-sdk-gen/commit/d8c7bb66736a3c4679b116916c61e2ead824a305)) - AI Studioの新しいツールをサポート (box/box-openapi[#534](https://github.com/box/box-typescript-sdk-gen/issues/534)) ([#652](https://github.com/box/box-typescript-sdk-gen/issues/652)) ([`db2501b`](https://github.com/box/box-typescript-sdk-gen/commit/db2501bb13fc6ecebbb4c535b4a19c9be2cf64c2)) **Source:** [https://ja.developer.box.com/changelog/2025-08-05-box-typescript-sdk-generated-v1170-released](https://ja.developer.box.com/changelog/2025-08-05-box-typescript-sdk-generated-v1170-released) --- ### Box TypeScript SDK Generated `v1.17.1`のリリース **Type:** changelog | **Section:** Changelog Box TypeScript SDK Generated v1.17.1のリリース バグ修正 libからインポートする際のエクスポートの構文を修正 (#700) (782a287) # Box TypeScript SDK Generated v1.17.1のリリース ### バグ修正 - `lib`からインポートする際のエクスポートの構文を修正 ([#700](https://github.com/box/box-typescript-sdk-gen/issues/700)) ([`782a287`](https://github.com/box/box-typescript-sdk-gen/commit/782a287efd3481fc056effcf83886f05bc9adbf9)) **Source:** [https://ja.developer.box.com/changelog/2025-08-07-box-typescript-sdk-generated-v1171-released](https://ja.developer.box.com/changelog/2025-08-07-box-typescript-sdk-generated-v1171-released) --- ### Box TypeScript SDK Generated `v1.2.0`のリリース **Type:** changelog | **Section:** Changelog Box TypeScript SDK Generated v1.2.0のリリース バグ修正 ブラウザでのアップロードを修正 (box/box-codegen#524) (#248) (88d747e) 分割アップロードを更新 (box/box-codegen#523) (#24… # Box TypeScript SDK Generated v1.2.0のリリース ### バグ修正 - ブラウザでのアップロードを修正 (box/box-codegen[#524](https://github.com/box/box-typescript-sdk-gen/issues/524)) ([#248](https://github.com/box/box-typescript-sdk-gen/issues/248)) ([`88d747e`](https://github.com/box/box-typescript-sdk-gen/commit/88d747e0f03dfa3c2d6089257c6e8b5b635775e0)) - 分割アップロードを更新 (box/box-codegen[#523](https://github.com/box/box-typescript-sdk-gen/issues/523)) ([#247](https://github.com/box/box-typescript-sdk-gen/issues/247)) ([`27ceb35`](https://github.com/box/box-typescript-sdk-gen/commit/27ceb35e6444843eea9b7ec6923fe958c9a74571)) ### 新機能と機能強化 - ステータスコード`202`のリクエストを再試行 (box/box-codegen[#511](https://github.com/box/box-typescript-sdk-gen/issues/511)) ([#235](https://github.com/box/box-typescript-sdk-gen/issues/235)) ([`03b8f43`](https://github.com/box/box-typescript-sdk-gen/commit/03b8f4314ada5ef5596706b7599cc76565fe96a5)) - Typescriptで拡張可能な列挙型をサポート (box/box-codegen[#520](https://github.com/box/box-typescript-sdk-gen/issues/520)) ([#243](https://github.com/box/box-typescript-sdk-gen/issues/243)) ([`5237972`](https://github.com/box/box-typescript-sdk-gen/commit/523797273bc08e3b22609ef0019432ab3e43c3ba)) **Source:** [https://ja.developer.box.com/changelog/2024-07-08-box-typescript-sdk-generated-v120-released](https://ja.developer.box.com/changelog/2024-07-08-box-typescript-sdk-generated-v120-released) --- ### Box TypeScript SDK Generated `v1.3.0`のリリース **Type:** changelog | **Section:** Changelog Box TypeScript SDK Generated v1.3.0のリリース バグ修正 IntegrationMappingPartnerItemSlackをunionタイプに抽出 (box/box-codegen#530) (#255) (fa8952a… # Box TypeScript SDK Generated v1.3.0のリリース ### バグ修正 - `IntegrationMappingPartnerItemSlack`をunionタイプに抽出 (box/box-codegen[#530](https://github.com/box/box-typescript-sdk-gen/issues/530)) ([#255](https://github.com/box/box-typescript-sdk-gen/issues/255)) ([`fa8952a`](https://github.com/box/box-typescript-sdk-gen/commit/fa8952a6582d9965bbb4ab66bbeff057f5c68851)) - 分割アップロードの信頼性を改善 (box/box-codegen[#529](https://github.com/box/box-typescript-sdk-gen/issues/529)) ([#254](https://github.com/box/box-typescript-sdk-gen/issues/254)) ([`12d9288`](https://github.com/box/box-typescript-sdk-gen/commit/12d928850e0a1cd60f336a9919474b9aaba33028)) ### 新機能と機能強化 - ユーザーコラボレーションに`is_active`パラメータを追加 (box/box-openapi[#437](https://github.com/box/box-typescript-sdk-gen/issues/437)) ([#253](https://github.com/box/box-typescript-sdk-gen/issues/253)) ([`4d8d436`](https://github.com/box/box-typescript-sdk-gen/commit/4d8d436977b3e487a47e7717626f1c0f2eb43227)) - AIエージェントAPIをサポート (box/box-codegen[#531](https://github.com/box/box-typescript-sdk-gen/issues/531)) ([#260](https://github.com/box/box-typescript-sdk-gen/issues/260)) ([`0ec40d4`](https://github.com/box/box-typescript-sdk-gen/commit/0ec40d44c86a8a9cf4fe594966cfad1866be457c)) **Source:** [https://ja.developer.box.com/changelog/2024-07-24-box-typescript-sdk-generated-v130-released](https://ja.developer.box.com/changelog/2024-07-24-box-typescript-sdk-generated-v130-released) --- ### Box TypeScript SDK Generated `v1.4.0`のリリース **Type:** changelog | **Section:** Changelog Box TypeScript SDK Generated v1.4.0のリリース バグ修正 不足していたトークンのスコープを追加 (box/box-openapi#442) (#281) (ca77f58) マルチパートリクエストのfetchメソッドを修正 (box/box… # Box TypeScript SDK Generated v1.4.0のリリース ### バグ修正 - 不足していたトークンのスコープを追加 (box/box-openapi[#442](https://github.com/box/box-typescript-sdk-gen/issues/442)) ([#281](https://github.com/box/box-typescript-sdk-gen/issues/281)) ([`ca77f58`](https://github.com/box/box-typescript-sdk-gen/commit/ca77f58b10d3a302748750584730f0fcdd8b4b55)) - マルチパートリクエストのfetchメソッドを修正 (box/box-codegen[#545](https://github.com/box/box-typescript-sdk-gen/issues/545)) ([#303](https://github.com/box/box-typescript-sdk-gen/issues/303)) ([`f8ceac0`](https://github.com/box/box-typescript-sdk-gen/commit/f8ceac005f043017e7cde310490e79ab9195f8d7)) ### 新機能と機能強化 - 分割アップロードのエンドポイントURLをパラメータ化 (box/box-openapi[#444](https://github.com/box/box-typescript-sdk-gen/issues/444)) ([#302](https://github.com/box/box-typescript-sdk-gen/issues/302)) ([`293a6e9`](https://github.com/box/box-typescript-sdk-gen/commit/293a6e9aeabbba37e4c12e2322a79717a10e1775)) - **ts:** プロパティおよびメソッドにコメントを追加 (box/box-codegen[#537](https://github.com/box/box-typescript-sdk-gen/issues/537)) ([#284](https://github.com/box/box-typescript-sdk-gen/issues/284)) ([`db3a2b5`](https://github.com/box/box-typescript-sdk-gen/commit/db3a2b57fbe0eec17373a2acf8089ff247c98225)) **Source:** [https://ja.developer.box.com/changelog/2024-08-12-box-typescript-sdk-generated-v140-released](https://ja.developer.box.com/changelog/2024-08-12-box-typescript-sdk-generated-v140-released) --- ### Box TypeScript SDK Generated `v1.5.0`のリリース **Type:** changelog | **Section:** Changelog Box TypeScript SDK Generated v1.5.0のリリース バグ修正 Signテンプレートの署名者に不足していたフィールドを追加し、AIスキーマを修正 (box/box-openapi#451) (#317) (340fbd… # Box TypeScript SDK Generated v1.5.0のリリース ### バグ修正 - Signテンプレートの署名者に不足していたフィールドを追加し、AIスキーマを修正 (box/box-openapi[#451](https://github.com/box/box-typescript-sdk-gen/issues/451)) ([#317](https://github.com/box/box-typescript-sdk-gen/issues/317)) ([`340fbd8`](https://github.com/box/box-typescript-sdk-gen/commit/340fbd84f6fa408155c6a2a4b9b7b03b88f76f24)) - `IntegrationMapping`スキーマを修正 (box/box-codegen[#551](https://github.com/box/box-typescript-sdk-gen/issues/551)) ([#315](https://github.com/box/box-typescript-sdk-gen/issues/315)) ([`a863b1e`](https://github.com/box/box-typescript-sdk-gen/commit/a863b1eb8fcfccd78714e3f52ce96d89ef69ca72)) ### 新機能と機能強化 - Box AIのメソッドに新しいパラメータを追加し、`AiResponseFull`バリアントを導入 (box/box-openapi[#446](https://github.com/box/box-typescript-sdk-gen/issues/446)) ([#313](https://github.com/box/box-typescript-sdk-gen/issues/313)) ([`d9664fd`](https://github.com/box/box-typescript-sdk-gen/commit/d9664fd7d431685c8e115415085bbe69d17f272d)) - `FetchOptions`にURLを追加 (box/box-codegen[#549](https://github.com/box/box-typescript-sdk-gen/issues/549)) ([#319](https://github.com/box/box-typescript-sdk-gen/issues/319)) ([`30eaa6b`](https://github.com/box/box-typescript-sdk-gen/commit/30eaa6ba7aa0fcd5e2f71026d7bf58729d387221)) **Source:** [https://ja.developer.box.com/changelog/2024-08-23-box-typescript-sdk-generated-v150-released](https://ja.developer.box.com/changelog/2024-08-23-box-typescript-sdk-generated-v150-released) --- ### Box TypeScript SDK Generated `v1.5.1`のリリース **Type:** changelog | **Section:** Changelog Box TypeScript SDK Generated v1.5.1のリリース バグ修正 インターセプタのfetchオプションを修正 (box/box-codegen#556) (#326) (3751eea) # Box TypeScript SDK Generated v1.5.1のリリース ### バグ修正 - インターセプタのfetchオプションを修正 (box/box-codegen[#556](https://github.com/box/box-typescript-sdk-gen/issues/556)) ([#326](https://github.com/box/box-typescript-sdk-gen/issues/326)) ([`3751eea`](https://github.com/box/box-typescript-sdk-gen/commit/3751eea67047021fe298c841596ae362ed1e47da)) **Source:** [https://ja.developer.box.com/changelog/2024-08-30-box-typescript-sdk-generated-v151-released](https://ja.developer.box.com/changelog/2024-08-30-box-typescript-sdk-generated-v151-released) --- ### Box TypeScript SDK Generated `v1.6.0`のリリース **Type:** changelog | **Section:** Changelog Box TypeScript SDK Generated v1.6.0のリリース バグ修正 不足していたライセンスをpackage.jsonに追加 (box/box-codegen#562) (#343) (cc9a8b8) メタデータクエリの結果のバリアントを修正 (box… # Box TypeScript SDK Generated v1.6.0のリリース ### バグ修正 - 不足していたライセンスを`package.json`に追加 (box/box-codegen[#562](https://github.com/box/box-typescript-sdk-gen/issues/562)) ([#343](https://github.com/box/box-typescript-sdk-gen/issues/343)) ([`cc9a8b8`](https://github.com/box/box-typescript-sdk-gen/commit/cc9a8b8ac628e348d32176f8ba69add649c555bd)) - メタデータクエリの結果のバリアントを修正 (box/box-openapi[#456](https://github.com/box/box-typescript-sdk-gen/issues/456)) ([#349](https://github.com/box/box-typescript-sdk-gen/issues/349)) ([`2131e98`](https://github.com/box/box-typescript-sdk-gen/commit/2131e98ff5530c7440ff50ec0da46cc317d0a4ae)) ### 新機能と機能強化 - Hubsベータ版を追加 (box/box-openapi[#453](https://github.com/box/box-typescript-sdk-gen/issues/453)) ([#333](https://github.com/box/box-typescript-sdk-gen/issues/333)) ([`40359c7`](https://github.com/box/box-typescript-sdk-gen/commit/40359c71aa25ecfe7ec53bfa19de62b9d83d4ace)) - プロキシのサポートを追加 (box/box-codegen[#559](https://github.com/box/box-typescript-sdk-gen/issues/559)) ([#337](https://github.com/box/box-typescript-sdk-gen/issues/337)) ([`0ffd9c8`](https://github.com/box/box-typescript-sdk-gen/commit/0ffd9c8095d1aa742144146383ae94f1f4526af0)) **Source:** [https://ja.developer.box.com/changelog/2024-09-11-box-typescript-sdk-generated-v160-released](https://ja.developer.box.com/changelog/2024-09-11-box-typescript-sdk-generated-v160-released) --- ### Box TypeScript SDK Generated `v1.7.0`のリリース **Type:** changelog | **Section:** Changelog Box TypeScript SDK Generated v1.7.0のリリース 新機能と機能強化 レスポンスオブジェクトに未加工のデータを追加 (box/box-codegen#576) (#375) (bdb9d0c) ai/extractおよびai/extract… # Box TypeScript SDK Generated v1.7.0のリリース ### 新機能と機能強化 - レスポンスオブジェクトに未加工のデータを追加 (box/box-codegen[#576](https://github.com/box/box-typescript-sdk-gen/issues/576)) ([#375](https://github.com/box/box-typescript-sdk-gen/issues/375)) ([`bdb9d0c`](https://github.com/box/box-typescript-sdk-gen/commit/bdb9d0caab1a54ca56aef5de4260215d1d3fbd35)) - `ai/extract`および`ai/extract_structured`エンドポイントをサポート (box/box-codegen[#566](https://github.com/box/box-typescript-sdk-gen/issues/566)) ([#356](https://github.com/box/box-typescript-sdk-gen/issues/356)) ([`4a33562`](https://github.com/box/box-typescript-sdk-gen/commit/4a335621c7eaa413162a5daa65d63d8353ba37f5)) **Source:** [https://ja.developer.box.com/changelog/2024-10-17-box-typescript-sdk-generated-v170-released](https://ja.developer.box.com/changelog/2024-10-17-box-typescript-sdk-generated-v170-released) --- ### Box TypeScript SDK Generated `v1.8.0`のリリース **Type:** changelog | **Section:** Changelog Box TypeScript SDK Generated v1.8.0のリリース バグ修正 ClientErrorのadditionalPropertiesを修正 (box/box-openapi#477) (#385) (454714… # Box TypeScript SDK Generated v1.8.0のリリース ### バグ修正 - `ClientError`の`additionalProperties`を修正 (box/box-openapi[#477](https://github.com/box/box-typescript-sdk-gen/issues/477)) ([#385](https://github.com/box/box-typescript-sdk-gen/issues/385)) ([`4547148`](https://github.com/box/box-typescript-sdk-gen/commit/454714861019998b1fc6b7c44696b0178ffa022b)) - ブラウザでの分割アップロードを修正 (box/box-codegen[#619](https://github.com/box/box-typescript-sdk-gen/issues/619)) ([#436](https://github.com/box/box-typescript-sdk-gen/issues/436)) ([`0af2484`](https://github.com/box/box-typescript-sdk-gen/commit/0af2484dd8387cce1a8c235068ac3f834f8ecf42)) - コンテンツのないステータスコードをサポート (box/box-codegen[#604](https://github.com/box/box-typescript-sdk-gen/issues/604)) ([#415](https://github.com/box/box-typescript-sdk-gen/issues/415)) ([`c3f14c6`](https://github.com/box/box-typescript-sdk-gen/commit/c3f14c6af55ab78ed5dc981909c67397b0d7219e)) - スキーマエラーをサポートするようクライアントエラースキーマを更新 (box/box-openapi[#467](https://github.com/box/box-typescript-sdk-gen/issues/467)) ([#381](https://github.com/box/box-typescript-sdk-gen/issues/381)) ([`b845f12`](https://github.com/box/box-typescript-sdk-gen/commit/b845f12d194d5f4e0cfd66db1db294e2f9a9bff8)) - 統合マッピングのレスポンスの説明を更新 (box/box-openapi[#463](https://github.com/box/box-typescript-sdk-gen/issues/463)) ([#379](https://github.com/box/box-typescript-sdk-gen/issues/379)) ([`e3d71e1`](https://github.com/box/box-typescript-sdk-gen/commit/e3d71e100500c5fa9e478b5228fd395f68242cf2)) ### 新機能と機能強化 - AI LLMエンドポイントのAWS `params`を追加 (box/box-openapi[#478](https://github.com/box/box-typescript-sdk-gen/issues/478)) ([#388](https://github.com/box/box-typescript-sdk-gen/issues/388)) ([`d2fd1ec`](https://github.com/box/box-typescript-sdk-gen/commit/d2fd1ec4bddb19b353e286908c99477e08b90457)) - カスタムHTTPリクエストを行うためのメソッドを公開し、`FetchOptions`をクラスに変換 (box/box-codegen[#610](https://github.com/box/box-typescript-sdk-gen/issues/610)) ([#431](https://github.com/box/box-typescript-sdk-gen/issues/431)) ([`9a9ea62`](https://github.com/box/box-typescript-sdk-gen/commit/9a9ea628fd21001437d92b32f1760d5ba14cb46b)) - IDを指定してコレクションを取得エンドポイントをサポート (box/box-codegen[#595](https://github.com/box/box-typescript-sdk-gen/issues/595)) ([#396](https://github.com/box/box-typescript-sdk-gen/issues/396)) ([`f1f47be`](https://github.com/box/box-typescript-sdk-gen/commit/f1f47bebfc0981a5e67f301b6fc2e3a8568d5845)) - ファイルのダウンロードURLとファイルのサムネイルURLの取得をサポート (box/box-codegen[#617](https://github.com/box/box-typescript-sdk-gen/issues/617)) ([#435](https://github.com/box/box-typescript-sdk-gen/issues/435)) ([`1cb4d5d`](https://github.com/box/box-typescript-sdk-gen/commit/1cb4d5d93fbd94b952b876457008973a92d5aa23)) - TypeScriptの`nullable`フィールドをサポート (box/box-codegen[#612](https://github.com/box/box-typescript-sdk-gen/issues/612)) ([#425](https://github.com/box/box-typescript-sdk-gen/issues/425)) ([`991dc29`](https://github.com/box/box-typescript-sdk-gen/commit/991dc29bc805bf0c5198277142efb9a85de1dd42)) **Source:** [https://ja.developer.box.com/changelog/2024-12-03-box-typescript-sdk-generated-v180-released](https://ja.developer.box.com/changelog/2024-12-03-box-typescript-sdk-generated-v180-released) --- ### Box TypeScript SDK Generated `v1.9.0`のリリース **Type:** changelog | **Section:** Changelog Box TypeScript SDK Generated v1.9.0のリリース バグ修正 InterceptorインターフェースのbeforeRequestメソッドの署名を修正 (box/box-codegen#625) (#446) (ef2e76… # Box TypeScript SDK Generated v1.9.0のリリース ### バグ修正 - `Interceptor`インターフェースの`beforeRequest`メソッドの署名を修正 (box/box-codegen[#625](https://github.com/box/box-typescript-sdk-gen/issues/625)) ([#446](https://github.com/box/box-typescript-sdk-gen/issues/446)) ([`ef2e765`](https://github.com/box/box-typescript-sdk-gen/commit/ef2e7658cab705906325e40d6c7c6e96e5703201)) ### 新機能と機能強化 - `AiResponse`に`aiAgent`の情報を追加 (box/box-codegen[#624](https://github.com/box/box-typescript-sdk-gen/issues/624)) ([#440](https://github.com/box/box-typescript-sdk-gen/issues/440)) ([`24c2013`](https://github.com/box/box-typescript-sdk-gen/commit/24c20131b8275d43ecb02f3c94ac8e6116de3ea9)) - ファイル、フォルダ、ウェブリンクの更新で`userId`パラメータ (省略可) をサポート (box/box-openapi[#488](https://github.com/box/box-typescript-sdk-gen/issues/488)) ([#445](https://github.com/box/box-typescript-sdk-gen/issues/445)) ([`874f259`](https://github.com/box/box-typescript-sdk-gen/commit/874f259ce12e8440301ffb1b2b65a6765b87803f)) **Source:** [https://ja.developer.box.com/changelog/2024-12-09-box-typescript-sdk-generated-v190-released](https://ja.developer.box.com/changelog/2024-12-09-box-typescript-sdk-generated-v190-released) --- ### Box UI Elements `v11.0.0`のリリース **Type:** changelog | **Section:** Changelog Box UI Elements v11.0.0のリリース 11.0.0 (2019年11月9日) バグ修正 activity-feed: Edgeのタスク/コメントの長いユーザー名を修正 (#1604) (572e4d7) activity-feed… # Box UI Elements v11.0.0のリリース ## 11.0.0 (2019年11月9日) ### バグ修正 - **`activity-feed`:** Edgeのタスク/コメントの長いユーザー名を修正 ([#1604](https://github.com/box/box-ui-elements/issues/1604)) ([`572e4d7`](https://github.com/box/box-ui-elements/commit/572e4d7)) - **`activity-feed`:** アクティビティフィードのバージョン順序を修正 ([#1272](https://github.com/box/box-ui-elements/issues/1272)) ([`533c112`](https://github.com/box/box-ui-elements/commit/533c112)) - **`activity-feed`:** フィード項目と空の状態のインラインエラーをリファクタリング ([#1697](https://github.com/box/box-ui-elements/issues/1697)) ([`2702367`](https://github.com/box/box-ui-elements/commit/2702367)) - **`annotation`:** Boxの注釈で使用されるセレクタを追加することでヘッダーを修正 ([#1637](https://github.com/box/box-ui-elements/issues/1637)) ([`9302486`](https://github.com/box/box-ui-elements/commit/9302486)) - **`app-activity`:** resin機能名からアンダースコアを削除 ([#1456](https://github.com/box/box-ui-elements/issues/1456)) ([`b7c21e7`](https://github.com/box/box-ui-elements/commit/b7c21e7)) - **`app-activity`:** コメント/タスクに一致するようアプリのアクティビティを更新 ([#1449](https://github.com/box/box-ui-elements/issues/1449)) ([`b58aa2f`](https://github.com/box/box-ui-elements/commit/b58aa2f)) - **`arrow-stepper`:** KeyBindingコンポーネントの矢印ステッパーを修正 ([#1654](https://github.com/box/box-ui-elements/issues/1654)) ([`a05b015`](https://github.com/box/box-ui-elements/commit/a05b015)) - **`avatar`:** アバターのイニシャルのv位置を修正 ([#1311](https://github.com/box/box-ui-elements/issues/1311)) ([`23e6d5f`](https://github.com/box/box-ui-elements/commit/23e6d5f)) - **`avatar`:** アクティビティサイドバーでのアバターの解像度を修正 ([#1243](https://github.com/box/box-ui-elements/issues/1243)) ([`88a5f1c`](https://github.com/box/box-ui-elements/commit/88a5f1c)) - **`avatar`:** URL変更の効果の代わりに派生状態を使用 ([#1643](https://github.com/box/box-ui-elements/issues/1643)) ([`f89c138`](https://github.com/box/box-ui-elements/commit/f89c138)) - **`bdl`:** 色変数名のSCSSチェックを追加 ([#1514](https://github.com/box/box-ui-elements/issues/1514)) ([`a4f446f`](https://github.com/box/box-ui-elements/commit/a4f446f)) - **`bdl`:** 標準と太字に一致するようフォントの太さを調整 `lato` ([#1517](https://github.com/box/box-ui-elements/issues/1517)) ([`35a4070`](https://github.com/box/box-ui-elements/commit/35a4070)) - **`beta-feedback`:** `aria-labelledby`属性名を更新 ([#1249](https://github.com/box/box-ui-elements/issues/1249)) ([`c164aec`](https://github.com/box/box-ui-elements/commit/c164aec)) - **`breadcrumb`:** 欠落しているimportを追加 ([#1657](https://github.com/box/box-ui-elements/issues/1657)) ([`fec4735`](https://github.com/box/box-ui-elements/commit/fec4735)) - **`button`:** ボタンから水平方向の余白を削除 ([#1362](https://github.com/box/box-ui-elements/issues/1362)) ([`a6989a0`](https://github.com/box/box-ui-elements/commit/a6989a0)) - **`button`:** ボタンからの水平方向の余白の削除を元に戻す ([#1362](https://github.com/box/box-ui-elements/issues/1362)) ([#1400](https://github.com/box/box-ui-elements/issues/1400)) ([`3ac424c`](https://github.com/box/box-ui-elements/commit/3ac424c)) - **`classification`:** バッジに`tabindex`を含めない ([#1622](https://github.com/box/box-ui-elements/issues/1622)) ([`4ab0c20`](https://github.com/box/box-ui-elements/commit/4ab0c20)) - **`classification`:** 分類バッジUXの微調整 ([#1378](https://github.com/box/box-ui-elements/issues/1378)) ([`fa82a8d`](https://github.com/box/box-ui-elements/commit/fa82a8d)) - **`classification`:** IE11で分類のツールチップが表示されない ([#1710](https://github.com/box/box-ui-elements/issues/1710)) ([`d08b53c`](https://github.com/box/box-ui-elements/commit/d08b53c)) - **`classification`:** `onclick`のフロー定義 ([#1712](https://github.com/box/box-ui-elements/issues/1712)) ([`9e620ce`](https://github.com/box/box-ui-elements/commit/9e620ce)) - **`classification`:** 分類バッジアイコンの復元 ([#1390](https://github.com/box/box-ui-elements/issues/1390)) ([`5db4b3e`](https://github.com/box/box-ui-elements/commit/5db4b3e)) - **`collaborator-avatars`:** キーボードアクセシビリティを追加 ([#1680](https://github.com/box/box-ui-elements/issues/1680)) ([`baefaed`](https://github.com/box/box-ui-elements/commit/baefaed)) - **`collapsible`:** 純粋なコンポーネントにする必要がある ([#1407](https://github.com/box/box-ui-elements/issues/1407)) ([`5e32c80`](https://github.com/box/box-ui-elements/commit/5e32c80)) - **`comment`:** 複数のコメントをサポートするためにコメント領域に高さを追加 ([#1474](https://github.com/box/box-ui-elements/issues/1474)) ([`e270131`](https://github.com/box/box-ui-elements/commit/e270131)) - **`comment`:** コメントUIのパディングと`a11y`の調整 ([#1358](https://github.com/box/box-ui-elements/issues/1358)) ([`927a34a`](https://github.com/box/box-ui-elements/commit/927a34a)) - **`comment`:** 冗長な`aria-label`を削除 ([#1291](https://github.com/box/box-ui-elements/issues/1291)) ([`ef48f88`](https://github.com/box/box-ui-elements/commit/ef48f88)) - **`comment`:** 確認ダイアログにオーバーレイのZインデックスを使用 ([#1270](https://github.com/box/box-ui-elements/issues/1270)) ([`bcf2852`](https://github.com/box/box-ui-elements/commit/bcf2852)) - **`comments`:** エディタの既存のコメントをフォーマット ([#1469](https://github.com/box/box-ui-elements/issues/1469)) ([`6b82510`](https://github.com/box/box-ui-elements/commit/6b82510)) - **`constants`:** 明示的な型のインポート ([#1584](https://github.com/box/box-ui-elements/issues/1584)) ([`7d38fb8`](https://github.com/box/box-ui-elements/commit/7d38fb8)) - **`content-explorer`:** `ContentExplorer`および`ContentPicker`でウェブリンクの共有の処理が可能に ([#1515](https://github.com/box/box-ui-elements/issues/1515)) ([`55edef7`](https://github.com/box/box-ui-elements/commit/55edef7)) - **`content-explorer`:** `MDVGridView`インポートの修正 ([#1333](https://github.com/box/box-ui-elements/issues/1333)) ([`9740342`](https://github.com/box/box-ui-elements/commit/9740342)) - **`content-explorer`:** ウィンドウを閉じた後に行が動作しなくなる問題を修正 ([#1245](https://github.com/box/box-ui-elements/issues/1245)) ([`d7f53ff`](https://github.com/box/box-ui-elements/commit/d7f53ff)) - **`content-preview`:** ナビゲーション時にディープリンクパスを削除 ([#1665](https://github.com/box/box-ui-elements/issues/1665)) ([`84b4ea4`](https://github.com/box/box-ui-elements/commit/84b4ea4)) - **`content-uploader`:** 100%に達したときにキャンセルボタンを無効化 ([#1511](https://github.com/box/box-ui-elements/issues/1511)) ([`a6de1b0`](https://github.com/box/box-ui-elements/commit/a6de1b0)) - **`content-uploader`:** タスクをキャンセルすると他のタスクが開始される問題を修正 ([#1653](https://github.com/box/box-ui-elements/issues/1653)) ([`f35b2ea`](https://github.com/box/box-ui-elements/commit/f35b2ea)) - **`content-uploader`:** 同時に重複ファイルがアップロードされる問題を修正 ([#1652](https://github.com/box/box-ui-elements/issues/1652)) ([`6faed59`](https://github.com/box/box-ui-elements/commit/6faed59)) - **`datetime`:**ミリ秒なしの時間のサポートを追加 ([#1191](https://github.com/box/box-ui-elements/issues/1191)) ([`19f3703`](https://github.com/box/box-ui-elements/commit/19f3703)) - **`deps`:** `axios`のピア依存関係をダウングレード ([#1329](https://github.com/box/box-ui-elements/issues/1329)) ([`d1a1bd9`](https://github.com/box/box-ui-elements/commit/d1a1bd9)) - **`examples`:** 現在のBoxの設計言語に合わせて色を変更 ([#1281](https://github.com/box/box-ui-elements/issues/1281)) ([`94869ad`](https://github.com/box/box-ui-elements/commit/94869ad)) - **`explorer`:** オンデマンドで共有リンクを取得 ([#1479](https://github.com/box/box-ui-elements/issues/1479)) ([`2d29628`](https://github.com/box/box-ui-elements/commit/2d29628)) - **`feed`:** フィード項目のディープリンクのインラインエラー ([#1655](https://github.com/box/box-ui-elements/issues/1655)) ([`e2be3bd`](https://github.com/box/box-ui-elements/commit/e2be3bd)) - **`feed`:** IE11でタスク担当者名が切り詰められる ([#1694](https://github.com/box/box-ui-elements/issues/1694)) ([`a20e610`](https://github.com/box/box-ui-elements/commit/a20e610)) - **`floatfield`:** 浮動小数点フィールドの末尾の`.`を常に許可 ([#1178](https://github.com/box/box-ui-elements/issues/1178)) ([`61d4e3d`](https://github.com/box/box-ui-elements/commit/61d4e3d)) - **`footer-indicator`:** フッターインジケータの上に表示されるようにツールチップを移動 ([`bf7782c`](https://github.com/box/box-ui-elements/commit/bf7782c)) - **`header-flyout`:** IE11のスクロールのバグを修正するためのウィンドウに対する制約 ([#1310](https://github.com/box/box-ui-elements/issues/1310)) ([`f8bb323`](https://github.com/box/box-ui-elements/commit/f8bb323)) - **`i18n`:** 「承諾済み」コピーを「承認済み」に変更 ([#1214](https://github.com/box/box-ui-elements/issues/1214)) ([`674bf45`](https://github.com/box/box-ui-elements/commit/674bf45)) - **`i18n`:** HTMLで始まるメッセージによって例外が発生するバグを修正 ([#1490](https://github.com/box/box-ui-elements/issues/1490)) ([`73d95b9`](https://github.com/box/box-ui-elements/commit/73d95b9)) - **`i18n`:** `Param`と`Plural`を`styleguide.conf`に含めない ([#1197](https://github.com/box/box-ui-elements/issues/1197)) ([`2d34ad4`](https://github.com/box/box-ui-elements/commit/2d34ad4)) - **`i18n`:** タスク担当者メッセージに複数形式を使用 ([#1345](https://github.com/box/box-ui-elements/issues/1345)) ([`10d6b76`](https://github.com/box/box-ui-elements/commit/10d6b76)) - **`icons`:** 地球アイコンの背景を塗りつぶし ([#1226](https://github.com/box/box-ui-elements/issues/1226)) ([`c91d320`](https://github.com/box/box-ui-elements/commit/c91d320)) - **`icons`:** 左ナビゲーションのユーザビリティのためにコレクションアイコンを修正 ([#1238](https://github.com/box/box-ui-elements/issues/1238)) ([`9e91115`](https://github.com/box/box-ui-elements/commit/9e91115)) - **`icons`:** コレクションアイコンにSUIT classNamesを指定 ([#1242](https://github.com/box/box-ui-elements/issues/1242)) ([`3b62245`](https://github.com/box/box-ui-elements/commit/3b62245)) - **`icons`:** 再試行および公開アイコンを更新 ([#1297](https://github.com/box/box-ui-elements/issues/1297)) ([`bfa075a`](https://github.com/box/box-ui-elements/commit/bfa075a)) - **`icons`:** ごみ箱、移動/コピー、追加、ダウンロード、アップロード、コレクションを更新 ([#1702](https://github.com/box/box-ui-elements/issues/1702)) ([`b126ecb`](https://github.com/box/box-ui-elements/commit/b126ecb)) - **`icons`:** 追加アイコンのスタイルを更新し、非表示の目のアイコンを追加 ([#1266](https://github.com/box/box-ui-elements/issues/1266)) ([`b47e22e`](https://github.com/box/box-ui-elements/commit/b47e22e)) - **`iconworkflow`:** 背景の長方形を`viewBox`と同じにする ([#1241](https://github.com/box/box-ui-elements/issues/1241)) ([`9e07f2e`](https://github.com/box/box-ui-elements/commit/9e07f2e)) - **`inlinenotice`:** Boxデザインの標準に更新 ([#1576](https://github.com/box/box-ui-elements/issues/1576)) ([`a814657`](https://github.com/box/box-ui-elements/commit/a814657)) - **`item-properties`:** 説明テキストエリアに`aria-labelledby`を追加 ([#1229](https://github.com/box/box-ui-elements/issues/1229)) ([`05d86b1`](https://github.com/box/box-ui-elements/commit/05d86b1)) - **`left-sidebar`:** リンクのラッパーをドロップするためのキーを追加 ([#1299](https://github.com/box/box-ui-elements/issues/1299)) ([`9c78135`](https://github.com/box/box-ui-elements/commit/9c78135)) - **`left-sidebar`:** インジケータを読み込むための余白を調整 ([#1545](https://github.com/box/box-ui-elements/issues/1545)) ([`6ba65c6`](https://github.com/box/box-ui-elements/commit/6ba65c6)) - **`left-sidebar`:** 画面サイズが中の場合に切り替えアイコンを非表示にする ([#1344](https://github.com/box/box-ui-elements/issues/1344)) ([`716fe01`](https://github.com/box/box-ui-elements/commit/716fe01)) - **`media`:** `.btn-plain`を回避するためメディアボタンのCSSの特異性を向上 ([#1463](https://github.com/box/box-ui-elements/issues/1463)) ([`943638d`](https://github.com/box/box-ui-elements/commit/943638d)) - **`mention-selector`:** `hasReceivedFirstInteraction`ロジックを修正 ([#1434](https://github.com/box/box-ui-elements/issues/1434)) ([`afd94fa`](https://github.com/box/box-ui-elements/commit/afd94fa)) - **`menu`:** メニュー項目ボタンのパディングを修正 ([#1446](https://github.com/box/box-ui-elements/issues/1446)) ([`5baeb5b`](https://github.com/box/box-ui-elements/commit/5baeb5b)) - **`menu`:** 表示されている場合のみマウント時にメニューを自動フォーカス ([#1175](https://github.com/box/box-ui-elements/issues/1175)) ([`2ba8a1d`](https://github.com/box/box-ui-elements/commit/2ba8a1d)) - **`metadata`:** メタデータ入力フィールドのオートコンプリートを表示 ([#1629](https://github.com/box/box-ui-elements/issues/1629)) ([`85995cd`](https://github.com/box/box-ui-elements/commit/85995cd)) - **`metadata`:** Safariのテンプレートドロップダウンスクロールバーの問題 ([#1192](https://github.com/box/box-ui-elements/issues/1192)) ([`1dc0d99`](https://github.com/box/box-ui-elements/commit/1dc0d99)) - **`metadata-sidebar`:** `onApiError`を適切にバインド ([#1713](https://github.com/box/box-ui-elements/issues/1713)) ([`50b72f2`](https://github.com/box/box-ui-elements/commit/50b72f2)) - **`modal`:** スクリーンリーダーを改良するために閉じるボタンをヘッダーの後に移動 `a11y` ([#1684](https://github.com/box/box-ui-elements/issues/1684)) ([`29a1220`](https://github.com/box/box-ui-elements/commit/29a1220)) - **`nav-sidebar`:** フォーカスのアウトラインを修正するために切り替えボタンのサイズを縮小 ([#1305](https://github.com/box/box-ui-elements/issues/1305)) ([`9a14ae7`](https://github.com/box/box-ui-elements/commit/9a14ae7)) - **`notifications`:** アクセシビリティの属性を追加 ([#1682](https://github.com/box/box-ui-elements/issues/1682)) ([`21af355`](https://github.com/box/box-ui-elements/commit/21af355)) - **`open-with`:** エラーメッセージを改善 ([#1489](https://github.com/box/box-ui-elements/issues/1489)) ([`d3d98a5`](https://github.com/box/box-ui-elements/commit/d3d98a5)) - **`pill-selector`:** 行区切りの値をコピーと貼り付けを許可 ([#1350](https://github.com/box/box-ui-elements/issues/1350)) ([`7933932`](https://github.com/box/box-ui-elements/commit/7933932)) - **`pill-selector`:** 入力をキャッチする`onInput`を公開 ([#1450](https://github.com/box/box-ui-elements/issues/1450)) ([`48d22a4`](https://github.com/box/box-ui-elements/commit/48d22a4)) - **`pill-selector`:** UXの微調整 ([#1315](https://github.com/box/box-ui-elements/issues/1315)) ([`e4fdf58`](https://github.com/box/box-ui-elements/commit/e4fdf58)) - **`pill-selector-dropdown`:** `PillSelector`が無効になるときにピルを無効化 ([#1357](https://github.com/box/box-ui-elements/issues/1357)) ([`2bf496e`](https://github.com/box/box-ui-elements/commit/2bf496e)) - **`pill-selector-dropdown`:** aria属性を修正 ([#1681](https://github.com/box/box-ui-elements/issues/1681)) ([`1e0d1ab`](https://github.com/box/box-ui-elements/commit/1e0d1ab)) - **`pill-selector-dropdown`:** クリック時にピルが削除される問題を修正 ([#1367](https://github.com/box/box-ui-elements/issues/1367)) ([`d67fcfe`](https://github.com/box/box-ui-elements/commit/d67fcfe)) - **`pills`:** ピルセレクタ入力テキストの垂直方向の中央揃えを修正 ([#1364](https://github.com/box/box-ui-elements/issues/1364)) ([`d47c69c`](https://github.com/box/box-ui-elements/commit/d47c69c)) - **`pillselectordropdown`:** コンテキストメニューからの貼り付けをサポート ([#1597](https://github.com/box/box-ui-elements/issues/1597)) ([`d16b0da`](https://github.com/box/box-ui-elements/commit/d16b0da)) - **`preview`:** プレビューのヘッダースタイルをクリーンアップし、余分な境界線を削除 ([#1484](https://github.com/box/box-ui-elements/issues/1484)) ([`6c1a363`](https://github.com/box/box-ui-elements/commit/6c1a363)) - **`quick-search`:** 境界線の半径をBDLに従うように更新 ([#1439](https://github.com/box/box-ui-elements/issues/1439)) ([`936f5e0`](https://github.com/box/box-ui-elements/commit/936f5e0)) - **`radio-group`:** 値のプロパティを渡すことでラジオボタングループを修正 ([#1452](https://github.com/box/box-ui-elements/issues/1452)) ([`c0c05be`](https://github.com/box/box-ui-elements/commit/c0c05be)) - **`radio-group`:** 残りのプロパティをラジオボタン入力に渡す ([#1448](https://github.com/box/box-ui-elements/issues/1448)) ([`85ca38a`](https://github.com/box/box-ui-elements/commit/85ca38a)) - **`scripts`:** プッシュ前にすべてのファイルをビルドして更新 ([#1415](https://github.com/box/box-ui-elements/issues/1415)) ([`e432c47`](https://github.com/box/box-ui-elements/commit/e432c47)) - **`scroll-if-needed`:** セレクタドロップダウンのscroll-if-neededを修正 ([#1280](https://github.com/box/box-ui-elements/issues/1280)) ([`3776dc8`](https://github.com/box/box-ui-elements/commit/3776dc8)) - **`search`:** `ContentExplorer`検索の丸みのある角を削除 ([#1478](https://github.com/box/box-ui-elements/issues/1478)) ([`7d9100b`](https://github.com/box/box-ui-elements/commit/7d9100b)) - **`security`:** セキュリティの脆弱性に対処するために`axios`をアップグレード ([#1228](https://github.com/box/box-ui-elements/issues/1228)) ([`db26743`](https://github.com/box/box-ui-elements/commit/db26743)) - **`security-badge`:** `SecurityBadge`フロータイプの修正 ([#1664](https://github.com/box/box-ui-elements/issues/1664)) ([`ae23f01`](https://github.com/box/box-ui-elements/commit/ae23f01)) - **`select-field`:** 選択フィールドでの矢印スクロールを有効化 ([#1671](https://github.com/box/box-ui-elements/issues/1671)) ([`9f040f2`](https://github.com/box/box-ui-elements/commit/9f040f2)) - **`sidebar`:** コメント入力にflex-shrink 0を追加 ([#1359](https://github.com/box/box-ui-elements/issues/1359)) ([`cd840f4`](https://github.com/box/box-ui-elements/commit/cd840f4)) - **`sidebar`:** マークアップとアクセシビリティをタブリストに追加 ([#1563](https://github.com/box/box-ui-elements/issues/1563)) ([`f90a0d7`](https://github.com/box/box-ui-elements/commit/f90a0d7)) - **`sidebar`:** バージョン履歴サイドバーのディープリンクを修正 ([#1649](https://github.com/box/box-ui-elements/issues/1649)) ([`e85e57a`](https://github.com/box/box-ui-elements/commit/e85e57a)) - **`sidebar`:** 大きなビューポートでサイドバーが自動で開かない問題を修正 ([#1508](https://github.com/box/box-ui-elements/issues/1508)) ([`dac39ee`](https://github.com/box/box-ui-elements/commit/dac39ee)) - **`sidebar`:** サイドバーナビゲーションの追加タブの高さの最大値を制限 ([#1557](https://github.com/box/box-ui-elements/issues/1557)) ([`e7f953e`](https://github.com/box/box-ui-elements/commit/e7f953e)) - **`sidebar`:** タブを意味的にわかりやすくする ([#1236](https://github.com/box/box-ui-elements/issues/1236)) ([`eb398fc`](https://github.com/box/box-ui-elements/commit/eb398fc)) - **`sidebar`:** 項目プロパティのバージョンのパディング ([#1263](https://github.com/box/box-ui-elements/issues/1263)) ([`853e106`](https://github.com/box/box-ui-elements/commit/853e106)) - **`sidebar`:** 空の状態の不要な括弧を削除 ([#1645](https://github.com/box/box-ui-elements/issues/1645)) ([`824f390`](https://github.com/box/box-ui-elements/commit/824f390)) - **`sidebar`:** サイドバーが強制的に開かれた場合にダーティ状態を設定 ([#1366](https://github.com/box/box-ui-elements/issues/1366)) ([`e71409c`](https://github.com/box/box-ui-elements/commit/e71409c)) - **`sidebar`:** アクティビティフィードコンテナの`flexbox`を更新 ([#1341](https://github.com/box/box-ui-elements/issues/1341)) ([`c5e07b1`](https://github.com/box/box-ui-elements/commit/c5e07b1)) - **`subheader`:** グリッドビューに関するロジックを追加 ([#1659](https://github.com/box/box-ui-elements/issues/1659)) ([`7a53050`](https://github.com/box/box-ui-elements/commit/7a53050)) - **`task`:** タスク完了ルールアイコンの文字列 ([#1573](https://github.com/box/box-ui-elements/issues/1573)) ([`79c3f00`](https://github.com/box/box-ui-elements/commit/79c3f00)) - **`task-form`:** フォーム送信時にタスク担当者のオートコンプリートをクリア ([#1605](https://github.com/box/box-ui-elements/issues/1605)) ([`63efa10`](https://github.com/box/box-ui-elements/commit/63efa10)) - **`task-form`:** 日付選択機能でのテキスト入力を禁止 ([#1540](https://github.com/box/box-ui-elements/issues/1540)) ([`af49827`](https://github.com/box/box-ui-elements/commit/af49827)) - **`task-form`:** タスクフォームの送信ボタンを無効にしない ([#1323](https://github.com/box/box-ui-elements/issues/1323)) ([`9a4137b`](https://github.com/box/box-ui-elements/commit/9a4137b)) - **`task-form`:** 重要ではないが必須のフィールドが残っている場合のエラーメッセージを更新 ([#1353](https://github.com/box/box-ui-elements/issues/1353)) ([`be10f37`](https://github.com/box/box-ui-elements/commit/be10f37)) - **`task-new`:**位置の修正、CSSリファクタリング ([#1312](https://github.com/box/box-ui-elements/issues/1312)) ([`411c3e9`](https://github.com/box/box-ui-elements/commit/411c3e9)) - **`task-new`:** タスクステータスのチェックマークの位置を修正 ([#1321](https://github.com/box/box-ui-elements/issues/1321)) ([`9f554ff`](https://github.com/box/box-ui-elements/commit/9f554ff)) - **`task-new`:** タスクメニューを追加するための視覚的な微調整 ([#1334](https://github.com/box/box-ui-elements/issues/1334)) ([`95a3c73`](https://github.com/box/box-ui-elements/commit/95a3c73)) - **`task-new`:** タスクメニューを追加するための視覚的な微調整 ([#1328](https://github.com/box/box-ui-elements/issues/1328)) ([`cf1acf1`](https://github.com/box/box-ui-elements/commit/cf1acf1)) - **`tasks`:** 欠落しているresinコンポーネントを追加 ([#1513](https://github.com/box/box-ui-elements/issues/1513)) ([`00e9707`](https://github.com/box/box-ui-elements/commit/00e9707)) - **`tasks`:** 担当者の入力フィールドのインタラクション ([#1621](https://github.com/box/box-ui-elements/issues/1621)) ([`dc33967`](https://github.com/box/box-ui-elements/commit/dc33967)) - **`tasks`:** プレビューのアクティビティサイドバーにコメントメニューが表示されない ([#1250](https://github.com/box/box-ui-elements/issues/1250)) ([`be7bc2f`](https://github.com/box/box-ui-elements/commit/be7bc2f)) - **`tasks`:** タスクの問題を修正 ([#1189](https://github.com/box/box-ui-elements/issues/1189)) ([`630fd38`](https://github.com/box/box-ui-elements/commit/630fd38)) - **`tasks`:** サイズ変更時にウィンドウが終了する ([#1603](https://github.com/box/box-ui-elements/issues/1603)) ([`2cbe014`](https://github.com/box/box-ui-elements/commit/2cbe014)) - **`tasks`:** 担当者のアバターのサイズ変更を防止 ([#1332](https://github.com/box/box-ui-elements/issues/1332)) ([`4e760f7`](https://github.com/box/box-ui-elements/commit/4e760f7)) - **`tasks`:** タスクタイプのサブテキストのコピーを更新 ([#1627](https://github.com/box/box-ui-elements/issues/1627)) ([`c788770`](https://github.com/box/box-ui-elements/commit/c788770)) - **`tasks_new`:** 欠落しているresinコンポーネントを追加 ([#1295](https://github.com/box/box-ui-elements/issues/1295)) ([`dbbf598`](https://github.com/box/box-ui-elements/commit/dbbf598)) - **`tasks-new`:** ウィンドウ終了時にセレクタの連絡先をリセット ([#1301](https://github.com/box/box-ui-elements/issues/1301)) ([`f387a9b`](https://github.com/box/box-ui-elements/commit/f387a9b)) - **`tasks-new`:** 削除されたユーザーの「以前のコラボレータ」を表示 ([#1313](https://github.com/box/box-ui-elements/issues/1313)) ([`c61fa77`](https://github.com/box/box-ui-elements/commit/c61fa77)) - **`tasks-new`:** タスクのアクションが更新されない ([#1302](https://github.com/box/box-ui-elements/issues/1302)) ([`2f88e96`](https://github.com/box/box-ui-elements/commit/2f88e96)) - **`tasks-new`:** ドキュメントと文字列を更新 ([#1317](https://github.com/box/box-ui-elements/issues/1317)) ([`6560b23`](https://github.com/box/box-ui-elements/commit/6560b23)) - **`template-dropdown`:** `onMenuToggle`ハンドラを`TemplateDropdown`に追加 ([#1318](https://github.com/box/box-ui-elements/issues/1318)) ([`2cdfcc4`](https://github.com/box/box-ui-elements/commit/2cdfcc4)) - **`text-input`:** ツールチップの切り替え時にフォーカスが失われる ([#1185](https://github.com/box/box-ui-elements/issues/1185)) ([`8a4c294`](https://github.com/box/box-ui-elements/commit/8a4c294)) - **`tooltip`:** 色のコントラストとレイアウトの修正 ([#1692](https://github.com/box/box-ui-elements/issues/1692)) ([`1c11770`](https://github.com/box/box-ui-elements/commit/1c11770)) - **`unfied-share-modal`:**共有リンクのアクセスレベル ([#1647](https://github.com/box/box-ui-elements/issues/1647)) ([`732a1dd`](https://github.com/box/box-ui-elements/commit/732a1dd)) - **`unified-share-modal`:** ウィンドウメニューに制約を追加 ([#1196](https://github.com/box/box-ui-elements/issues/1196)) ([`6501413`](https://github.com/box/box-ui-elements/commit/6501413)) - **`unified-share-modal`:** タイトルの分類 ([#1453](https://github.com/box/box-ui-elements/issues/1453)) ([`4ce5a06`](https://github.com/box/box-ui-elements/commit/4ce5a06)) - **`uploader`:** `MultiputUploads` IE11でのハングを停止 ([#1283](https://github.com/box/box-ui-elements/issues/1283)) ([`c49e52f`](https://github.com/box/box-ui-elements/commit/c49e52f)) - **`uploads`:** 進行中のタスクをキャンセルしても保留中のタスクが開始されない ([#1570](https://github.com/box/box-ui-elements/issues/1570)) ([`dbf115c`](https://github.com/box/box-ui-elements/commit/dbf115c)) - **`uploads`:** アップロードの再開時のハングを修正 ([#1695](https://github.com/box/box-ui-elements/issues/1695)) ([`3da93c8`](https://github.com/box/box-ui-elements/commit/3da93c8)) - **`uploads`:** 論理ゲートを削除 ([#1646](https://github.com/box/box-ui-elements/issues/1646)) ([`38d10e4`](https://github.com/box/box-ui-elements/commit/38d10e4)) - **`uploads`:** 再試行後に項目エラーをリセット ([#1600](https://github.com/box/box-ui-elements/issues/1600)) ([`0218f10`](https://github.com/box/box-ui-elements/commit/0218f10)) - **`uploads`:** アップロードのキャンセルのためのresin ([#1397](https://github.com/box/box-ui-elements/issues/1397)) ([`16311dc`](https://github.com/box/box-ui-elements/commit/16311dc)) - **`user-link`:** 長いユーザー名の折り返しを許可 ([#1602](https://github.com/box/box-ui-elements/issues/1602)) ([`bff49bb`](https://github.com/box/box-ui-elements/commit/bff49bb)) - **`usm`:** [リンク設定] では行の折り返しができない ([#1674](https://github.com/box/box-ui-elements/issues/1674)) ([`938c483`](https://github.com/box/box-ui-elements/commit/938c483)) - **`usm`:** `itemTypedId`を`onPillCreate`に追加 ([#1320](https://github.com/box/box-ui-elements/issues/1320)) ([`c4149ea`](https://github.com/box/box-ui-elements/commit/c4149ea)) - **`usm`:** `itemTypedID`を`getContactsByEmail`に渡さない ([#1354](https://github.com/box/box-ui-elements/issues/1354)) ([`e60b020`](https://github.com/box/box-ui-elements/commit/e60b020)) - **`versions`:** 電子すかし付きファイルの以前のバージョンのプレビューを無効化 ([#1405](https://github.com/box/box-ui-elements/issues/1405)) ([`9a527f2`](https://github.com/box/box-ui-elements/commit/9a527f2)) - **`versions`:** 最も関連性の高いバージョンアクションの日付と名前を表示 ([#1568](https://github.com/box/box-ui-elements/issues/1568)) ([`b68eccd`](https://github.com/box/box-ui-elements/commit/b68eccd)) - **`versions`:** 破棄されたAPIファクトリによる無限読み込みを修正 ([#1347](https://github.com/box/box-ui-elements/issues/1347)) ([`95949e2`](https://github.com/box/box-ui-elements/commit/95949e2)) - **`versions`:** バージョングループに前の月/年が折りたたまれている問題を修正 ([#1365](https://github.com/box/box-ui-elements/issues/1365)) ([`65d23b9`](https://github.com/box/box-ui-elements/commit/65d23b9)) - **`versions`:** 復元されたバージョンと昇格されたバージョンのエクスペリエンスを改善 ([#1631](https://github.com/box/box-ui-elements/issues/1631)) ([`25d0741`](https://github.com/box/box-ui-elements/commit/25d0741)) - **`versions`:** 電子すかし付きファイルの制限を緩和 ([#1342](https://github.com/box/box-ui-elements/issues/1342)) ([`2487b42`](https://github.com/box/box-ui-elements/commit/2487b42)) - **`versions`:** バージョンの昇格時にページを再読み込み (一時的) ([#1395](https://github.com/box/box-ui-elements/issues/1395)) ([`de7e74e`](https://github.com/box/box-ui-elements/commit/de7e74e)) - **`versions`:** 電子すかし付きファイルのアクションとプレビューを制限 ([#1339](https://github.com/box/box-ui-elements/issues/1339)) ([`fcb390d`](https://github.com/box/box-ui-elements/commit/fcb390d)) - **`versions`:** 電子すかし付きファイルのプレビューを制限 ([#1351](https://github.com/box/box-ui-elements/issues/1351)) ([`93b95c4`](https://github.com/box/box-ui-elements/commit/93b95c4)) - **`versions`:** ファイルバージョンの権限を取得してアクションに使用 ([#1193](https://github.com/box/box-ui-elements/issues/1193)) ([`9d7567e`](https://github.com/box/box-ui-elements/commit/9d7567e)) - **`versions`:** 選択されている場合にバージョンボタンをスクロールして表示 ([#1276](https://github.com/box/box-ui-elements/issues/1276)) ([`e0cd7e3`](https://github.com/box/box-ui-elements/commit/e0cd7e3)) - **`versions`:** バージョン履歴を非表示にせずにサーバーエラーを表示 ([#1275](https://github.com/box/box-ui-elements/issues/1275)) ([`ef3b2fd`](https://github.com/box/box-ui-elements/commit/ef3b2fd)) - **`versions`:** 不要なボタンを回避するようバージョンアクションを更新 ([#1556](https://github.com/box/box-ui-elements/issues/1556)) ([`bc9672e`](https://github.com/box/box-ui-elements/commit/bc9672e)) - **`versions`:** 最新のリテンションスキーマを使用するようバージョンサイドバーを更新 ([#1662](https://github.com/box/box-ui-elements/issues/1662)) ([`fa66232`](https://github.com/box/box-ui-elements/commit/fa66232)) - `Xhr.js`の`Accept-Language`ヘッダーを追加 ([#1368](https://github.com/box/box-ui-elements/issues/1368)) ([`361d73f`](https://github.com/box/box-ui-elements/commit/361d73f)) - 長いテキストにカーソルを合わせたときにツールチップを表示 ([#1230](https://github.com/box/box-ui-elements/issues/1230)) ([`c41dd47`](https://github.com/box/box-ui-elements/commit/c41dd47)) - チェックマークの位置を微調整 ([#1678](https://github.com/box/box-ui-elements/issues/1678)) ([`cfd055b`](https://github.com/box/box-ui-elements/commit/cfd055b)) - さまざまなフォームのアクセシビリティの改善 ([#1688](https://github.com/box/box-ui-elements/issues/1688)) ([`150cbbe`](https://github.com/box/box-ui-elements/commit/150cbbe)) - **`versions`:** 最新の契約と一致するようバージョンの復元呼び出しを更新 ([#1198](https://github.com/box/box-ui-elements/issues/1198)) ([`2e590d3`](https://github.com/box/box-ui-elements/commit/2e590d3)) ### 作業 - **`deps`:** `react`のピア/開発の依存関係を更新 ([#1606](https://github.com/box/box-ui-elements/issues/1606)) ([`1163db5`](https://github.com/box/box-ui-elements/commit/1163db5)) - **`formik`:** V2にアップグレード ([#1698](https://github.com/box/box-ui-elements/issues/1698)) ([`6b9ded9`](https://github.com/box/box-ui-elements/commit/6b9ded9)) ### コードのリファクタリング - `react`と`react-dom`を`v16.8`にアップグレードし、アバターをリファクタリング ([#1171](https://github.com/box/box-ui-elements/issues/1171)) ([`7dd1bdf`](https://github.com/box/box-ui-elements/commit/7dd1bdf))、[#761](https://github.com/box/box-ui-elements/issues/761)をクローズ - **`deps`:** ピアの依存関係を最新の作業バージョンにアップグレード ([#1180](https://github.com/box/box-ui-elements/issues/1180)) ([`48d711e`](https://github.com/box/box-ui-elements/commit/48d711e)) ### 機能 - **`activity-feed`:** タスクおよびコメントのディープリンクのサポートを追加 ([#1623](https://github.com/box/box-ui-elements/issues/1623)) ([`52ecdcb`](https://github.com/box/box-ui-elements/commit/52ecdcb)) - **`additional-tabs`:** 無効になっているアプリをグレー表示 ([#1503](https://github.com/box/box-ui-elements/issues/1503)) ([`132782d`](https://github.com/box/box-ui-elements/commit/132782d)) - **`avatarinitials`:** `backgroundColor`をSCSSに移動 ([#1585](https://github.com/box/box-ui-elements/issues/1585)) ([`781a246`](https://github.com/box/box-ui-elements/commit/781a246)) - **`bdl`:** SCSS `bdl`スコープのためのスクリプトを追加 ([#1546](https://github.com/box/box-ui-elements/issues/1546)) ([`9bdc1e6`](https://github.com/box/box-ui-elements/commit/9bdc1e6)) - **`classification`:** 分類/分類アクションのアイコンを変更 ([#1520](https://github.com/box/box-ui-elements/issues/1520)) ([`8eb68b3`](https://github.com/box/box-ui-elements/commit/8eb68b3)) - **`classification`:** 新しいバッジとレイアウト ([#1231](https://github.com/box/box-ui-elements/issues/1231)) ([`2336262`](https://github.com/box/box-ui-elements/commit/2336262)) - **`classification`:** 詳細サイドバー内の新しいセクション ([#1237](https://github.com/box/box-ui-elements/issues/1237)) ([`90bf2f3`](https://github.com/box/box-ui-elements/commit/90bf2f3)) - **`classification`:** 階層リンクから分類を削除 ([#1549](https://github.com/box/box-ui-elements/issues/1549)) ([`adae46d`](https://github.com/box/box-ui-elements/commit/adae46d)) - **`classification`:** 分類のUIを更新 ([#1566](https://github.com/box/box-ui-elements/issues/1566)) ([`52e2b17`](https://github.com/box/box-ui-elements/commit/52e2b17)) - **`comments`:** コメント編集を実装 ([#1468](https://github.com/box/box-ui-elements/issues/1468)) ([`33dd037`](https://github.com/box/box-ui-elements/commit/33dd037)) - **`content-explorer`:** サイズ列でコンテンツを並べ替える機能を追加 ([#1239](https://github.com/box/box-ui-elements/issues/1239)) ([`b29b6bf`](https://github.com/box/box-ui-elements/commit/b29b6bf)) - **`content-explorer`:** グリッドビューの切り替えボタンを追加 ([#1349](https://github.com/box/box-ui-elements/issues/1349)) ([`97a1d44`](https://github.com/box/box-ui-elements/commit/97a1d44)) - **`content-explorer`:** 検索と履歴のサムネイルを取得 ([#1475](https://github.com/box/box-ui-elements/issues/1475)) ([`1035afb`](https://github.com/box/box-ui-elements/commit/1035afb)) - **`content-explorer`:** グリッドビュースライダ ([#1482](https://github.com/box/box-ui-elements/issues/1482)) ([`ef4a7ee`](https://github.com/box/box-ui-elements/commit/ef4a7ee)) - **`content-explorer`:** グリッドビューのスタイル ([#1464](https://github.com/box/box-ui-elements/issues/1464)) ([`f32b8ca`](https://github.com/box/box-ui-elements/commit/f32b8ca))、[#1409](https://github.com/box/box-ui-elements/issues/1409)をクローズ - **`content-explorer`:** `MDVGridView`からファイルをインポート ([#1294](https://github.com/box/box-ui-elements/issues/1294)) ([`a2e5bd9`](https://github.com/box/box-ui-elements/commit/a2e5bd9)) - **`content-explorer`:** 表示モード設定のローカルストレージ ([#1476](https://github.com/box/box-ui-elements/issues/1476)) ([`803b0a0`](https://github.com/box/box-ui-elements/commit/803b0a0)) - **`content-explorer`:** ギャラリービューの機能の切り替えを削除 ([#1571](https://github.com/box/box-ui-elements/issues/1571)) ([`3e948b8`](https://github.com/box/box-ui-elements/commit/3e948b8)) - **`content-explorer`:** サムネイル付きのカードを表示 ([#1409](https://github.com/box/box-ui-elements/issues/1409)) ([`7bbc2e8`](https://github.com/box/box-ui-elements/commit/7bbc2e8)) - **`content-explorer`:** アイコンでグリッドを表示 ([#1372](https://github.com/box/box-ui-elements/issues/1372)) ([`64a099e`](https://github.com/box/box-ui-elements/commit/64a099e)) - **`content-picker`:** 単一選択にラジオボタンを使用 ([#1685](https://github.com/box/box-ui-elements/issues/1685)) ([`acc3395`](https://github.com/box/box-ui-elements/commit/acc3395)) - **`content-sidebar`:** 編集/作成用にタスクウィンドウモードを追加 ([#1257](https://github.com/box/box-ui-elements/issues/1257)) ([`0bdfc96`](https://github.com/box/box-ui-elements/commit/0bdfc96)) - **`content-sidebar`:** サイドバーパネルのプログラムによる更新 ([#1561](https://github.com/box/box-ui-elements/issues/1561)) ([`2adbaef`](https://github.com/box/box-ui-elements/commit/2adbaef)) - **`dropdown-menu`:** ドロップダウンが閉じている場合に`esc`の伝播を許可 ([#1686](https://github.com/box/box-ui-elements/issues/1686)) ([`3d4d59e`](https://github.com/box/box-ui-elements/commit/3d4d59e)) - **`features`:** メタデータリストビューでカーソルを合わせたときに背景色を追加 ([#1618](https://github.com/box/box-ui-elements/issues/1618)) ([`635808e`](https://github.com/box/box-ui-elements/commit/635808e)) - **`features`:** 新機能metadata-based-viewを追加 ([#1519](https://github.com/box/box-ui-elements/issues/1519)) ([`faef59e`](https://github.com/box/box-ui-elements/commit/faef59e)) - **`features`:** 項目名のクリック時にプレビューを表示 ([#1620](https://github.com/box/box-ui-elements/issues/1620)) ([`74e46b2`](https://github.com/box/box-ui-elements/commit/74e46b2)) - **`ghost`:** ゴースト状態のヘルパーコンポーネントを作成 ([#1498](https://github.com/box/box-ui-elements/issues/1498)) ([`73aadae`](https://github.com/box/box-ui-elements/commit/73aadae)) - **`i18n`:** 新しい`FormattedCompMessage`コンポーネントを実装 ([#976](https://github.com/box/box-ui-elements/issues/976)) ([`31fdf12`](https://github.com/box/box-ui-elements/commit/31fdf12)) - **`icon`:** ユーザー追加の空の状態アイコンを作成 ([#1638](https://github.com/box/box-ui-elements/issues/1638)) ([`33dfacb`](https://github.com/box/box-ui-elements/commit/33dfacb)) - **`icon`:** ログインとストレージのアイコンを作成 ([#1708](https://github.com/box/box-ui-elements/issues/1708)) ([`0115fb6`](https://github.com/box/box-ui-elements/commit/0115fb6)) - **`icons`:** `CollectionItemLink`アイコンを追加 ([#1550](https://github.com/box/box-ui-elements/issues/1550)) ([`1558d36`](https://github.com/box/box-ui-elements/commit/1558d36)) - **`icons`:** 電光と星のコレクションアイコンを追加 ([#1338](https://github.com/box/box-ui-elements/issues/1338)) ([`8e9d503`](https://github.com/box/box-ui-elements/commit/8e9d503)) - **`icons`:** コレクションの塗りつぶされた星アイコンを追加 ([#1547](https://github.com/box/box-ui-elements/issues/1547)) ([`55a182e`](https://github.com/box/box-ui-elements/commit/55a182e)) - **`icons`:** `IconFolderTree`アイコンを追加 ([#1696](https://github.com/box/box-ui-elements/issues/1696)) ([`add261b`](https://github.com/box/box-ui-elements/commit/add261b)) - **`icons`:** コレクションのアイコンを追加 ([#1224](https://github.com/box/box-ui-elements/issues/1224)) ([`a01ea82`](https://github.com/box/box-ui-elements/commit/a01ea82)) - **`icons`:** 新しい盾アイコンを追加 ([#1216](https://github.com/box/box-ui-elements/issues/1216)) ([`753d0e2`](https://github.com/box/box-ui-elements/commit/753d0e2)) - **`icons`:** サンドボックスとパズルのピースのアイコンを追加 ([#1370](https://github.com/box/box-ui-elements/issues/1370)) ([`67b6db4`](https://github.com/box/box-ui-elements/commit/67b6db4)) - **`icons`:** ワークフローアイコンを追加 ([#1225](https://github.com/box/box-ui-elements/issues/1225)) ([`9d73144`](https://github.com/box/box-ui-elements/commit/9d73144)) - **`icons`:** タスクの空の状態アイコンを作成 ([#1583](https://github.com/box/box-ui-elements/issues/1583)) ([`cac4023`](https://github.com/box/box-ui-elements/commit/cac4023)) - **`icons`:** 新しい稲妻アイコン ([#1183](https://github.com/box/box-ui-elements/issues/1183)) ([`ebccf18`](https://github.com/box/box-ui-elements/commit/ebccf18)) - **`icons`:** `IconShare`と`IconCollaboration`を新しい`32x32`アイコンに更新 ([#1232](https://github.com/box/box-ui-elements/issues/1232)) ([`4f4e31b`](https://github.com/box/box-ui-elements/commit/4f4e31b)) - **`icons`:** 新しい地球アイコンに更新し、新しい地球を追加 `tinycon` ([#1217](https://github.com/box/box-ui-elements/issues/1217)) ([`3dded61`](https://github.com/box/box-ui-elements/commit/3dded61)) - **`inline-edit`:** インスタンスフィールドの入力をユーザーに表示 ([#1172](https://github.com/box/box-ui-elements/issues/1172)) ([`1f90dde`](https://github.com/box/box-ui-elements/commit/1f90dde)) - **`left-nav`:** Box Relayアイコンを追加 ([#1207](https://github.com/box/box-ui-elements/issues/1207)) ([`29f07a6`](https://github.com/box/box-ui-elements/commit/29f07a6))、[#1206](https://github.com/box/box-ui-elements/issues/1206)をクローズ - **`left-sidebar`:** `LeftSidebar`がカスタム`navLinkRenderer`をサポート ([#1510](https://github.com/box/box-ui-elements/issues/1510)) ([`f9705a2`](https://github.com/box/box-ui-elements/commit/f9705a2)) - **`leftsidebar`:** カーソルを合わせたときにのみドロップ領域を表示 ([#1548](https://github.com/box/box-ui-elements/issues/1548)) ([`a45c998`](https://github.com/box/box-ui-elements/commit/a45c998)) - **`media`:** メディアオブジェクトコンポーネントを作成 ([#1383](https://github.com/box/box-ui-elements/issues/1383)) ([`5140c13`](https://github.com/box/box-ui-elements/commit/5140c13)) - **`metadata`:** メタデータテンプレートのフィルタを有効化 ([#1598](https://github.com/box/box-ui-elements/issues/1598)) ([`7b341f7`](https://github.com/box/box-ui-elements/commit/7b341f7)) - **`metadata-views`:** 編集と編集キャンセルのアクションを処理 ([#1703](https://github.com/box/box-ui-elements/issues/1703)) ([`d55f84a`](https://github.com/box/box-ui-elements/commit/d55f84a)) - **`metadata-views`:** メタデータビューに編集アイコンを表示 ([#1667](https://github.com/box/box-ui-elements/issues/1667)) ([`1b8a29d`](https://github.com/box/box-ui-elements/commit/1b8a29d)) - **`metadata-views`:** メタデータビューでメタデータ列のプロパティタイプを更新 ([#1666](https://github.com/box/box-ui-elements/issues/1666)) ([`cbf96ef`](https://github.com/box/box-ui-elements/commit/cbf96ef)) - **`new-tasks`:** タスクのコラボレータを取得 ([#1286](https://github.com/box/box-ui-elements/issues/1286)) ([`fb84aee`](https://github.com/box/box-ui-elements/commit/fb84aee)) - **`office-online`:** `xlsb`ファイルのExcelスプレッドシートアイコンを追加 ([`ee8569f`](https://github.com/box/box-ui-elements/commit/ee8569f)) - **`pill-selector`:** ピルセレクタの`formik`ラッパー ([#1194](https://github.com/box/box-ui-elements/issues/1194)) ([`c75a7bb`](https://github.com/box/box-ui-elements/commit/c75a7bb)) - **`pill-selector`:** ダウンストリームの問題のためにフロータイプを更新 ([#1210](https://github.com/box/box-ui-elements/issues/1210)) ([`69f25e8`](https://github.com/box/box-ui-elements/commit/69f25e8)) - **`preview`:** プレビューヘッダーでのカスタムロゴURLのサポートを追加 ([#1714](https://github.com/box/box-ui-elements/issues/1714)) ([`d37b9ec`](https://github.com/box/box-ui-elements/commit/d37b9ec)) - **`preview`:** ポリシーによってブロックされたときのメッセージを改良 ([#1346](https://github.com/box/box-ui-elements/issues/1346)) ([`a6cde28`](https://github.com/box/box-ui-elements/commit/a6cde28)) - **`preview`:** セキュリティブロックの新しいアイコン ([#1396](https://github.com/box/box-ui-elements/issues/1396)) ([`9355631`](https://github.com/box/box-ui-elements/commit/9355631)) - **`preview`:** box-content-previewのデフォルトバージョンを2.16.0にアップグレード ([#1562](https://github.com/box/box-ui-elements/issues/1562)) ([`7617fd2`](https://github.com/box/box-ui-elements/commit/7617fd2)) - **`radio`:** `RadioButton`の`formik`ラッパー ([#1204](https://github.com/box/box-ui-elements/issues/1204)) ([`0b51080`](https://github.com/box/box-ui-elements/commit/0b51080)) - **`react`:** 最大バージョン履歴のテキストを追加 ([#1630](https://github.com/box/box-ui-elements/issues/1630)) ([`705e71f`](https://github.com/box/box-ui-elements/commit/705e71f)) - **`scroll`:** 必要時にスクロール表示をアップグレード ([#1200](https://github.com/box/box-ui-elements/issues/1200)) ([`1532617`](https://github.com/box/box-ui-elements/commit/1532617)) - **`security`:** `SecurityBadge`コンポーネントを追加 ([#1663](https://github.com/box/box-ui-elements/issues/1663)) ([`3d210bb`](https://github.com/box/box-ui-elements/commit/3d210bb)) - **`select`:** 開閉時にキャレットをそれぞれ上下に回転 ([#1218](https://github.com/box/box-ui-elements/issues/1218)) ([`9627e2b`](https://github.com/box/box-ui-elements/commit/9627e2b)) - **`select-field`:** カスタムオプションのレンダリングを許可 ([#1516](https://github.com/box/box-ui-elements/issues/1516)) ([`53fe270`](https://github.com/box/box-ui-elements/commit/53fe270)) - **`shared-link-settings-modal`:** 分類済みの場合に直接ダウンロードを無効化 ([#1500](https://github.com/box/box-ui-elements/issues/1500)) ([`2ede02a`](https://github.com/box/box-ui-elements/commit/2ede02a)) - **`sidebar`:** 外部でのサイドバーの切り替えのサポートを追加 ([#1293](https://github.com/box/box-ui-elements/issues/1293)) ([`04468fc`](https://github.com/box/box-ui-elements/commit/04468fc)) - **`sidebar`:** プログラムによる更新 ([#1472](https://github.com/box/box-ui-elements/issues/1472)) ([`c7a19e7`](https://github.com/box/box-ui-elements/commit/c7a19e7)) - **`sidebar`:** リテンションポリシー情報をサイドバーに表示 ([#1648](https://github.com/box/box-ui-elements/issues/1648)) ([`cb9e714`](https://github.com/box/box-ui-elements/commit/cb9e714)) - **`sidebar`:** 切り替えボタン ([#1268](https://github.com/box/box-ui-elements/issues/1268)) ([`e2ad4ab`](https://github.com/box/box-ui-elements/commit/e2ad4ab)) - **`task-new`:** 担当者を追加/削除する機能を追加 ([#1284](https://github.com/box/box-ui-elements/issues/1284)) ([`8e87280`](https://github.com/box/box-ui-elements/commit/8e87280)) - **`task-new`:** 編集ウィンドウのサポートを追加 ([#1261](https://github.com/box/box-ui-elements/issues/1261)) ([`d13839c`](https://github.com/box/box-ui-elements/commit/d13839c)) - **`tasks`:**タスクアイコンとツールチップを追加 ([#1491](https://github.com/box/box-ui-elements/issues/1491)) ([`cf1c5b7`](https://github.com/box/box-ui-elements/commit/cf1c5b7)) - **`tasks`:** いずれか/すべてのチェックボックスを追加 ([#1487](https://github.com/box/box-ui-elements/issues/1487)) ([`21271e3`](https://github.com/box/box-ui-elements/commit/21271e3)) - **`tasks`:** タスクのコメント変更オプションを追加 ([#1247](https://github.com/box/box-ui-elements/issues/1247)) ([`b5775de`](https://github.com/box/box-ui-elements/commit/b5775de)) - **`tasks`:** 新しいタスク編集APIメソッドを追加 ([#1260](https://github.com/box/box-ui-elements/issues/1260)) ([`e05d5a7`](https://github.com/box/box-ui-elements/commit/e05d5a7)) - **`tasks`:** タイトルと説明を含む新しいエラーメッセージを処理 ([#1564](https://github.com/box/box-ui-elements/issues/1564)) ([`7d691df`](https://github.com/box/box-ui-elements/commit/7d691df)) - **`tasks`:** 完了ルールの文字列 ([#1471](https://github.com/box/box-ui-elements/issues/1471)) ([`cdaf285`](https://github.com/box/box-ui-elements/commit/cdaf285)) - **`tasks`:** アイコンを使用しないようにタスクのステータスを更新 ([#1169](https://github.com/box/box-ui-elements/issues/1169)) ([`b4b8bf0`](https://github.com/box/box-ui-elements/commit/b4b8bf0)) - **`tasks-new`:** 担当者リストを追加 ([#1287](https://github.com/box/box-ui-elements/issues/1287)) ([`04b7458`](https://github.com/box/box-ui-elements/commit/04b7458)) - **`tasks-new`:** `TaskForm`でタスクメッセージと期日を編集 ([#1269](https://github.com/box/box-ui-elements/issues/1269)) ([`7f63d97`](https://github.com/box/box-ui-elements/commit/7f63d97)) - **`tasks-new`:** ウィンドウヘッダーからベータ版のラベル機能を削除 ([#1314](https://github.com/box/box-ui-elements/issues/1314)) ([`dca414b`](https://github.com/box/box-ui-elements/commit/dca414b)) - **`tasks-new`:** 編集ウィンドウ用のタスクのresin追跡 ([#1327](https://github.com/box/box-ui-elements/issues/1327)) ([`5b5b354`](https://github.com/box/box-ui-elements/commit/5b5b354)) - **`typography`:** 本文のタイポグラフィを更新 ([#1442](https://github.com/box/box-ui-elements/issues/1442)) ([`375c336`](https://github.com/box/box-ui-elements/commit/375c336))、[#1439](https://github.com/box/box-ui-elements/issues/1439) [#1441](https://github.com/box/box-ui-elements/issues/1441)をクローズ - **`unified-share-modal`:** 外部コラボレーションの警告メッセージを追加 ([#1220](https://github.com/box/box-ui-elements/issues/1220)) ([`064bd2f`](https://github.com/box/box-ui-elements/commit/064bd2f)) - **`unified-share-modal`:** 連絡先の数を制限するプロパティを追加 ([#1304](https://github.com/box/box-ui-elements/issues/1304)) ([`2af11b1`](https://github.com/box/box-ui-elements/commit/2af11b1)) - **`unified-share-modal`:** 招待セクションのツールチップの変更 ([#1499](https://github.com/box/box-ui-elements/issues/1499)) ([`d7730c7`](https://github.com/box/box-ui-elements/commit/d7730c7))、[#1498](https://github.com/box/box-ui-elements/issues/1498)をクローズ - **`unified-share-modal`:** 招待セクションのツールチップの変更 ([#1504](https://github.com/box/box-ui-elements/issues/1504)) ([`b9486bc`](https://github.com/box/box-ui-elements/commit/b9486bc)) - **`unified-share-modal`:** ファイルの分類を表示 ([#1425](https://github.com/box/box-ui-elements/issues/1425)) ([`e3c7277`](https://github.com/box/box-ui-elements/commit/e3c7277)) - **`unified-share-modal`:** 外部コラボレータのインジケータを表示 ([#1256](https://github.com/box/box-ui-elements/issues/1256)) ([`613a438`](https://github.com/box/box-ui-elements/commit/613a438)) - **`uploads`:** アップロードマネージャのresinターゲットを追加 ([#1384](https://github.com/box/box-ui-elements/issues/1384)) ([`29d2af5`](https://github.com/box/box-ui-elements/commit/29d2af5)) - **`uploads`:** 単一ファイルのアップロードを再開 ([#1552](https://github.com/box/box-ui-elements/issues/1552)) ([`093f889`](https://github.com/box/box-ui-elements/commit/093f889)) - **`uploads`:** 複数の失敗したアップロードを再開 ([#1553](https://github.com/box/box-ui-elements/issues/1553)) ([`60406b9`](https://github.com/box/box-ui-elements/commit/60406b9)) - **`uploads`:** 再開可能なアップロード用のアップロードマネージャコンテンツ ([#1555](https://github.com/box/box-ui-elements/issues/1555)) ([`8380bc7`](https://github.com/box/box-ui-elements/commit/8380bc7)) - **`usm`:** `initiallySelectedContacts`に基づいて招待セクションを展開 ([#1470](https://github.com/box/box-ui-elements/issues/1470)) ([`b756a22`](https://github.com/box/box-ui-elements/commit/b756a22)) - **`validators`:** `host`、`ipv4`、およびドメイン名の検証機能 ([#1212](https://github.com/box/box-ui-elements/issues/1212)) ([`f653dac`](https://github.com/box/box-ui-elements/commit/f653dac)) - **`versions`:** バージョンアクションにクライアント側エラーメッセージを追加 ([#1404](https://github.com/box/box-ui-elements/issues/1404)) ([`8ead57c`](https://github.com/box/box-ui-elements/commit/8ead57c)) - **`versions`:** サイドバーの戻るボタンにresin追跡を追加 ([#1309](https://github.com/box/box-ui-elements/issues/1309)) ([`901c23d`](https://github.com/box/box-ui-elements/commit/901c23d)) - **`versions`:** すべてのバージョン履歴アクションにresin追跡を追加 ([#1285](https://github.com/box/box-ui-elements/issues/1285)) ([`a4942d3`](https://github.com/box/box-ui-elements/commit/a4942d3)) - **`versions`:** `ContentSidebar`へのディープリンクのサポートを追加 ([#1203](https://github.com/box/box-ui-elements/issues/1203)) ([`78ab636`](https://github.com/box/box-ui-elements/commit/78ab636)) - **`versions`:** ファイルバージョン復元アクションのサポートを追加 ([#1184](https://github.com/box/box-ui-elements/issues/1184)) ([`d5396bd`](https://github.com/box/box-ui-elements/commit/d5396bd)) - **`versions`:** バージョンアクションコールバックのサポートを追加 ([#1417](https://github.com/box/box-ui-elements/issues/1417)) ([`099a09e`](https://github.com/box/box-ui-elements/commit/099a09e)) - **`versions`:** バージョン制限のサポートをサイドバーに追加 ([#1316](https://github.com/box/box-ui-elements/issues/1316)) ([`bec5699`](https://github.com/box/box-ui-elements/commit/bec5699)) - **`versions`:** 相対日付に基づくバージョングループヘッダーを追加 ([#1330](https://github.com/box/box-ui-elements/issues/1330)) ([`51d5633`](https://github.com/box/box-ui-elements/commit/51d5633)) - `metadata_queries` APIレイヤーを追加 ([#1481](https://github.com/box/box-ui-elements/issues/1481)) ([`2f6ef29`](https://github.com/box/box-ui-elements/commit/2f6ef29)) - 再開可能なアップロード機能の切り替えに関するプロパティを追加 ([#1447](https://github.com/box/box-ui-elements/issues/1447)) ([`3f19a3b`](https://github.com/box/box-ui-elements/commit/3f19a3b)) - プロパティ`initiallySelectedContacts`を`UnifiedShareModal`に追加 ([#1424](https://github.com/box/box-ui-elements/issues/1424)) ([`8966016`](https://github.com/box/box-ui-elements/commit/8966016)) - デフォルトのタスクアイコンを`$bdl-box-blue`に ([#1509](https://github.com/box/box-ui-elements/issues/1509)) ([`dbc7103`](https://github.com/box/box-ui-elements/commit/dbc7103)) - タスク/コメントに取得されるファイルコラボレータを増加 ([#1483](https://github.com/box/box-ui-elements/issues/1483)) ([`05f65f4`](https://github.com/box/box-ui-elements/commit/05f65f4)) ### パフォーマンスの向上 - **`sidebar`:** 500ミリ秒の遅延なしでサイドバーパネルを遅延読み込み ([#1223](https://github.com/box/box-ui-elements/issues/1223)) ([`bb216b4`](https://github.com/box/box-ui-elements/commit/bb216b4)) - **`sidebar`:** 重複するAPIコールを回避するためにレスポンスをマージ ([#1617](https://github.com/box/box-ui-elements/issues/1617)) ([`69ad154`](https://github.com/box/box-ui-elements/commit/69ad154)) - **`version`:** バージョン履歴ウィンドウを削除 ([#1633](https://github.com/box/box-ui-elements/issues/1633)) ([`eb0aac6`](https://github.com/box/box-ui-elements/commit/eb0aac6)) ### 取り消し - **`avatar`:** アバターを非フックの実装に戻す ([#1186](https://github.com/box/box-ui-elements/issues/1186)) ([`69f329b`](https://github.com/box/box-ui-elements/commit/69f329b)) ### 重大な変更 **`formik`:** `inputProps`切り替えコンポーネントからの削除。 `formik`は、V2にアップグレードされました。[ガイドをアップグレードしてください](https://github.com/jaredpalmer/formik/blob/master/docs/migrating-v2.md)。 ピア依存関係のReact要件が高くなりました リファクタリング (アバター): アバターがフックを使用するようリファクタリング 修正 (テスト): 各種テストの問題が修正され、Enzymeが3.8.0にダウングレードされました 修正 (アバター): 冗長なチェックが削除されました **`classification`:** また、用語の一貫性を保つために`advisoryMessage`プロパティが定義に変更されました 機能 (分類): 分類アイコンのストローク幅が大きくなりました **`typography`:** 本文の色がデフォルトで[＃222](https://github.com/box/box-developer-changelog/issues/222) (`bdl-gray`) になります 機能 (タイポグラフィ): 一般的なタイポグラフィの文字間隔が更新されました **`typography`:** 一般的なタイポグラフィの文字間隔は`em`ではなく`px`になりました。スケーリングを確認してください。 **`classification`:** 分類データをサイドバーに提供するためのAPIが`{ advisoryMessage, name }`に変更されました 機能: デザインの変更 機能: 分類バッジの変更 修正: PRフィードバック 修正: スナップショット **`icons`:** `IconShield`が盾を表す新しいアイコンに置き換えられました。32 x 32のガイドラインに従っています。必要に応じてスタイルを上書きしてください。 **`deps`:** react-*ピア依存関係を16.9.0に更新 React 16.9への更新には、ライフサイクルメソッドの非推奨の警告が含まれます。これは、依存関係の1つであるreact-tetherに影響します。この警告が表示されないようにする計画は今のところありません。 **`security`:** [https://nvd.nist.gov/vuln/detail/CVE-2019-10742](https://nvd.nist.gov/vuln/detail/CVE-2019-10742)に対処するため、`axios`のピア依存関係をアップグレード **`icons`:** `16x16`の代わりにデフォルトで`20x20`を使用する新しい地球アイコンに更新し、新しい地球`tinycon`を導入 **`validators`:** メールとドメインの検証に使用される[**`@hapi/address`**](https://github.com/hapi/address)のピア依存関係を追加 修正: メールチェック用の一般的でない`tlds`が追加されました 修正: 不良な`tlds`が追加されました **`scroll`:** scroll-into-view-if-neededのメジャーバージョンアップグレード。 **`i18n`:** `i18n` `FormattedCompMessage`コンポーネントをサポートするため、追加のピア依存関係が追加されました 新しいコンポーネント`FormattedCompMessage`が実装されました。このコンポーネントは、タグのコンテンツを翻訳者またはハッカーから隠し、代わりにソース文字列のコンテンツを翻訳に使用することで、HTMLまたはその他のJSXコンポーネントを含む可能性のある文字列を安全に翻訳します。例: ``` <FormattedCompMessage id="mystring" description="translator's comment"> You can <span class="foo">delete</span> <Link to={url}>these files</Link>, or just <span id="x" class="unshare">unshare them</span>. </FormattedCompMessage> ``` `FormattedCompMessage`は`react-intl`の上にレイヤとして構築され、これを使用して実際の翻訳を行います。その機能の目的は、React要素のツリーをコード化された文字列に変換し、`react-intl`でその文字列を翻訳して、コード化された翻訳済みの文字列をReact要素のツリーに再度変換し、最終的にソースツリーの隠されたReact要素を翻訳ツリーの適切な場所に戻すことです。 このコンポーネントは、新しいbabelプラグイン`babel-plugin-box-i18n`を使用して、コード化されたテキストをソースコードから抽出し、`react-intl`babelプラグインによって生成された同じタイプのJSONファイルに配置します。この方法により、これより下流の翻訳プロセスはそれ以上変更しなくても機能します。翻訳はしばらく時間を置いてからプロパティファイルに表示され、`react-intl`によって通常どおりピックアップされます。`FormattedCompMessage`は`react-intl`を使用してこれらの翻訳を取得できます。また、`babel-pluging-box-i18n`プラグインは、すべての文字列に一意のIDと翻訳者の説明が必要であるなどのBoxのポリシーも適用します。 `FormattedCompMessage`コンポーネントは、`FormattedCompMessage`の本文に`<Plural>`コンポーネントを埋め込むことにより、Reactの慣用語法で複数形をサポートできます。 ``` <FormattedCompMessage id="mystring" description="translator's comment" count={count}> <Plural category="one">This is the <strong>singular</strong> string.</Plural> <Plural category="other">This is the <strong>plural</strong> string.</Plural> </FormattedCompMessage> ``` HTMLとサブコンポーネントは複数形の文字列でも使用できることに注意してください。 `FormattedCompMessage`コンポーネントは、`FormattedCompMessage`の本文に`<Param>`コンポーネントを埋め込むことにより、Reactの慣用語法で置換パラメータをサポートできます。 ``` <FormattedCompMessage id="mystring" description="translator's comment"> User <Param value={user.name} description="The user's full name"/> has already deleted this file. </FormattedCompMessage> ``` `Param`タグは、通常のコンポーネントであるため、`Plural`タグ内でも使用できることに注意してください。 - **`deps`:** ピア依存関係が更新されました。NPM警告を回避するには、ダウンストリームアプリケーションも更新する必要があります。 - **`icons`:** 古い`IconShare`はデフォルトで`26x26`、古い`IconCollaboration`はデフォルトで`27x26`になっていましたが、新しいアイコンはデフォルトで`32x32`になりました。また、デフォルトのSVGクラス名が`bdl-IconShare`および`bdl-IconCollaboration`に変更されました。 **Source:** [https://ja.developer.box.com/changelog/2019-11-09-box-ui-elements-v1100-released](https://ja.developer.box.com/changelog/2019-11-09-box-ui-elements-v1100-released) --- ### Box UI Elements `v11.0.2`のリリース **Type:** changelog | **Section:** Changelog Box UI Elements v11.0.2のリリース 11.0.2 (2019/11/26) バグ修正 ビルド: 古いリリースパッケージ (991ee17) # Box UI Elements v11.0.2のリリース ## 11.0.2 (2019/11/26) ### バグ修正 - **ビルド:** 古いリリースパッケージ ([`991ee17`](https://github.com/box/box-ui-elements/commit/991ee17)) **Source:** [https://ja.developer.box.com/changelog/2019-11-26-box-ui-elements-v1102-released](https://ja.developer.box.com/changelog/2019-11-26-box-ui-elements-v1102-released) --- ### Box UI Elements `v13.0.0`のリリース **Type:** changelog | **Section:** Changelog Box UI Elements v13.0.0のリリース 13.0.0 (2021/04/22) バグ修正と機能 このリリースでは、複数のバグが修正されます。全一覧については、リリースノートを参照してください。 # Box UI Elements v13.0.0のリリース ## 13.0.0 (2021/04/22) ## バグ修正と機能 このリリースでは、複数のバグが修正されます。全一覧については、[リリースノートを参照してください](https://github.com/box/box-ui-elements/releases/tag/v13.0.0)。 **Source:** [https://ja.developer.box.com/changelog/2021-04-22-box-ui-elements-v1300-released](https://ja.developer.box.com/changelog/2021-04-22-box-ui-elements-v1300-released) --- ### Box UI Elements `v14.0.0`のリリース **Type:** changelog | **Section:** Changelog Box UI Elements v14.0.0のリリース 14.0.0 (2021-10-20) バグ修正と機能 このリリースでは、複数のバグが修正されます。全一覧については、リリースノートを参照してください。 # Box UI Elements v14.0.0のリリース ## 14.0.0 (2021-10-20) ## バグ修正と機能 このリリースでは、複数のバグが修正されます。全一覧については、[リリースノートを参照してください](https://github.com/box/box-ui-elements/releases/tag/v14.0.0)。 **Source:** [https://ja.developer.box.com/changelog/2021-10-20-box-ui-elements-v1400-released](https://ja.developer.box.com/changelog/2021-10-20-box-ui-elements-v1400-released) --- ### Box UI Elements `v15.0.0`のリリース **Type:** changelog | **Section:** Changelog Box UI Elements v15.0.0のリリース 15.0.0 (2022-05-16) バグ修正と機能 このリリースではいくつかのバグを修正し、新機能を追加しました。すべての変更点のリストについては、リリースノートを参照してください。 # Box UI Elements v15.0.0のリリース ## 15.0.0 (2022-05-16) ## バグ修正と機能 このリリースではいくつかのバグを修正し、新機能を追加しました。すべての変更点のリストについては、[リリースノートを参照してください](https://github.com/box/box-ui-elements/releases/tag/v15.0.0)。 **Source:** [https://ja.developer.box.com/changelog/2022-05-16-box-ui-elements-v1500-released](https://ja.developer.box.com/changelog/2022-05-16-box-ui-elements-v1500-released) --- ### Box UI Elements `v16.0.0`のリリース **Type:** changelog | **Section:** Changelog Box UI Elements v16.0.0のリリース 16.0.0 (2022-10-20) バグ修正と機能 このリリースではいくつかのバグを修正し、新機能を追加しました。すべての変更点のリストについては、リリースノートを参照してください。 # Box UI Elements v16.0.0のリリース ## 16.0.0 (2022-10-20) ## バグ修正と機能 このリリースではいくつかのバグを修正し、新機能を追加しました。すべての変更点のリストについては、[リリースノートを参照してください](https://github.com/box/box-ui-elements/releases/tag/v16.0.0)。 **Source:** [https://ja.developer.box.com/changelog/2022-10-20-box-ui-elements-v1600-released](https://ja.developer.box.com/changelog/2022-10-20-box-ui-elements-v1600-released) --- ### Box UI Elements `v17.0.0`のリリース **Type:** changelog | **Section:** Changelog Box UI Elements v17.0.0のリリース 17.0.0 (2023/04/20) バグ修正 aci-toggle: 情報バッジの垂直方向の調整 (#3290) (f73b9f9) avatar: 外部ユーザーアイコンにaria-labelを追加 (#326… # Box UI Elements v17.0.0のリリース # 17.0.0 (2023/04/20) ### バグ修正 - **aci-toggle:** 情報バッジの垂直方向の調整 ([#3290](https://github.com/box/box-ui-elements/issues/3290)) ([`f73b9f9`](https://github.com/box/box-ui-elements/commit/f73b9f9)) - **avatar:** 外部ユーザーアイコンに`aria-label`を追加 ([#3263](https://github.com/box/box-ui-elements/issues/3263)) ([`18cdf3f`](https://github.com/box/box-ui-elements/commit/18cdf3f)) - **collaborator-list-item:** 冗長なタイトルを削除 ([#3255](https://github.com/box/box-ui-elements/issues/3255)) ([`d805249`](https://github.com/box/box-ui-elements/commit/d805249)) - **content-explorer:** 矢印のナビゲーションを追加 ([#3219](https://github.com/box/box-ui-elements/issues/3219)) ([`35bf8de`](https://github.com/box/box-ui-elements/commit/35bf8de)) - **content-explorer:** アイコンに`svg`のタイトルを追加 ([#3227](https://github.com/box/box-ui-elements/issues/3227)) ([`506ca45`](https://github.com/box/box-ui-elements/commit/506ca45)) - **content-explorer:** フォルダツリーの階層リンクのテキストの色を変更 ([#3268](https://github.com/box/box-ui-elements/issues/3268)) ([`fc95d4d`](https://github.com/box/box-ui-elements/commit/fc95d4d)) - **content-explorer:** 名前の末尾にスペースを含むフォルダの作成を有効化 ([#3246](https://github.com/box/box-ui-elements/issues/3246)) ([`e0b03c7`](https://github.com/box/box-ui-elements/commit/e0b03c7)) - **content-explorer:** 項目の詳細で色のコントラストの問題を修正 ([#3273](https://github.com/box/box-ui-elements/issues/3273)) ([`4db0231`](https://github.com/box/box-ui-elements/commit/4db0231)) - **content-explorer:** 色のコントラストの問題を修正 ([#3221](https://github.com/box/box-ui-elements/issues/3221)) ([`b7ecaab`](https://github.com/box/box-ui-elements/commit/b7ecaab)) - **content-explorer:** 項目リストの列見出しのロールを修正 ([#3232](https://github.com/box/box-ui-elements/issues/3232)) ([`718a71a`](https://github.com/box/box-ui-elements/commit/718a71a)) - **content-explorer:** 選択した項目行のボタンの境界線をフォーカス ([#3314](https://github.com/box/box-ui-elements/issues/3314)) ([`a596557`](https://github.com/box/box-ui-elements/commit/a596557)) - **content-explorer:** 階層リンクを非アクティブ化する代わりに非表示にする ([#3260](https://github.com/box/box-ui-elements/issues/3260)) ([`5b5fec1`](https://github.com/box/box-ui-elements/commit/5b5fec1)) - **content-explorer:** [サブフォルダを含める] のサブヘッダーの修正 ([#3259](https://github.com/box/box-ui-elements/issues/3259)) ([`6ec1512`](https://github.com/box/box-ui-elements/commit/6ec1512)) - **content-explorer:** [サブフォルダを含める] のステータスメッセージ ([#3261](https://github.com/box/box-ui-elements/issues/3261)) ([`3ce688d`](https://github.com/box/box-ui-elements/commit/3ce688d)) - **content-explorer:** 選択した行の共有ボタンの境界線を更新 ([#3278](https://github.com/box/box-ui-elements/issues/3278)) ([`28c79dd`](https://github.com/box/box-ui-elements/commit/28c79dd)) - **content-picker:** `disabled`属性を追加 ([#3243](https://github.com/box/box-ui-elements/issues/3243)) ([`a88a96c`](https://github.com/box/box-ui-elements/commit/a88a96c)) - **content-sharing:** APIの作成時にAPIの条件を削除 ([#3251](https://github.com/box/box-ui-elements/issues/3251)) ([`24dcba2`](https://github.com/box/box-ui-elements/commit/24dcba2)) - **content-uploader:** 非アクティブなボタンをフォーカス不可に変更 ([#3248](https://github.com/box/box-ui-elements/issues/3248)) ([`2302712`](https://github.com/box/box-ui-elements/commit/2302712)) - **flyout:** ポップアップのオーバーレイCSSの特異性を向上 ([#3257](https://github.com/box/box-ui-elements/issues/3257)) ([`0933062`](https://github.com/box/box-ui-elements/commit/0933062)) - **i18n:** 翻訳を更新 ([#3250](https://github.com/box/box-ui-elements/issues/3250)) ([`d84d1ca`](https://github.com/box/box-ui-elements/commit/d84d1ca)) - **i18n:** 翻訳を更新 ([#3276](https://github.com/box/box-ui-elements/issues/3276)) ([`018a99c`](https://github.com/box/box-ui-elements/commit/018a99c)) - **i18n:** 翻訳を更新 ([#3285](https://github.com/box/box-ui-elements/issues/3285)) ([`bfbcf55`](https://github.com/box/box-ui-elements/commit/bfbcf55)) - **i18n:** 翻訳を更新 ([#3300](https://github.com/box/box-ui-elements/issues/3300)) ([`88116cb`](https://github.com/box/box-ui-elements/commit/88116cb)) - **itemlist:** リストが空の場合にヘッダーセクションを削除 ([#3224](https://github.com/box/box-ui-elements/issues/3224)) ([`0274618`](https://github.com/box/box-ui-elements/commit/0274618)) - **makeselectable:** スライダで矢印のホットキーを禁止 ([#3299](https://github.com/box/box-ui-elements/issues/3299)) ([`a893e5a`](https://github.com/box/box-ui-elements/commit/a893e5a)) - **metadata:** テンプレートのドロップダウンが切り詰められる問題を修正 ([#3265](https://github.com/box/box-ui-elements/issues/3265)) ([`c3ae099`](https://github.com/box/box-ui-elements/commit/c3ae099)) - **select-field:** ドロップダウンが上部に配置されている場合に下の余白を追加 ([#3302](https://github.com/box/box-ui-elements/issues/3302)) ([`11e6979`](https://github.com/box/box-ui-elements/commit/11e6979)) - **select-field:** 選択ドロップダウンのtetherクラスを追加 ([#3303](https://github.com/box/box-ui-elements/issues/3303)) ([`ce27f70`](https://github.com/box/box-ui-elements/commit/ce27f70)) - **selector-dropdown:** ドロップダウンのオーバーレイに動的配置を追加 ([#3262](https://github.com/box/box-ui-elements/issues/3262)) ([`7f05653`](https://github.com/box/box-ui-elements/commit/7f05653)) - **usm:** コラボレータリストのDOMでアイコンの前にユーザーを指定 ([#3306](https://github.com/box/box-ui-elements/issues/3306)) ([`32c656d`](https://github.com/box/box-ui-elements/commit/32c656d)) - コンソールの警告を回避するために省略するプロパティを追加 ([#3286](https://github.com/box/box-ui-elements/issues/3286)) ([`11328fb`](https://github.com/box/box-ui-elements/commit/11328fb)) - BEの並べ替えボタンのメニューオプションを調整 ([#3231](https://github.com/box/box-ui-elements/issues/3231)) ([`dcc06e2`](https://github.com/box/box-ui-elements/commit/dcc06e2)) - BEヘッダーの検索の`aria-label`を修正 ([#3244](https://github.com/box/box-ui-elements/issues/3244)) ([`ca01965`](https://github.com/box/box-ui-elements/commit/ca01965)) - USMおよび共有リンクコンポーネントの`bdl-gray-62`を置き換え ([#3289](https://github.com/box/box-ui-elements/issues/3289)) ([`1f25b98`](https://github.com/box/box-ui-elements/commit/1f25b98)) - **makeselectable:** Shiftと矢印で最初の行を選択 ([#3223](https://github.com/box/box-ui-elements/issues/3223)) ([`9b209e5`](https://github.com/box/box-ui-elements/commit/9b209e5)) - **scss:** dart-sassのすべての除算記号を置換 ([#3253](https://github.com/box/box-ui-elements/issues/3253)) ([`ac92e21`](https://github.com/box/box-ui-elements/commit/ac92e21)) - **shared-link-section:** アクセシビリティのツールチップ ([#3216](https://github.com/box/box-ui-elements/issues/3216)) ([`4ecdd81`](https://github.com/box/box-ui-elements/commit/4ecdd81)) - **sub-header:** メニュー項目の並べ替えのアクセシビリティ ([#3230](https://github.com/box/box-ui-elements/issues/3230)) ([`20f4454`](https://github.com/box/box-ui-elements/commit/20f4454)) - **sub-header:** 選択コンポーネントを使用するように並べ替えを更新し、テストを更新 ([#3239](https://github.com/box/box-ui-elements/issues/3239)) ([`528a157`](https://github.com/box/box-ui-elements/commit/528a157)) - **toggle:** 切り替えのロールを追加 ([#3254](https://github.com/box/box-ui-elements/issues/3254)) ([`cf0c894`](https://github.com/box/box-ui-elements/commit/cf0c894)) - **tooltip:** `ariaHidden`が`true`のときに`aria-describedby`を非アクティブ化 ([#3233](https://github.com/box/box-ui-elements/issues/3233)) ([`d9108c4`](https://github.com/box/box-ui-elements/commit/d9108c4)) - **tooltip:** ツールチップにダイアログを指定 ([#3226](https://github.com/box/box-ui-elements/issues/3226))" ([#3264](https://github.com/box/box-ui-elements/issues/3264)) ([`fa68dd6`](https://github.com/box/box-ui-elements/commit/fa68dd6)) - **usm:** `aria-label`を削除して`aria-haspopup`を追加 ([#3281](https://github.com/box/box-ui-elements/issues/3281)) ([`fd1a82d`](https://github.com/box/box-ui-elements/commit/fd1a82d)) - **usm:** 冗長なボタン要素を削除 ([#3282](https://github.com/box/box-ui-elements/issues/3282)) ([`a7005ff`](https://github.com/box/box-ui-elements/commit/a7005ff)) - コンテンツ共有のボタンのタイプを「submit」から「button」に変更 ([#3277](https://github.com/box/box-ui-elements/issues/3277)) ([`26b7e5f`](https://github.com/box/box-ui-elements/commit/26b7e5f)) - 入力領域の境界線の色のコントラストを改善 ([#3234](https://github.com/box/box-ui-elements/issues/3234)) ([`3917bee`](https://github.com/box/box-ui-elements/commit/3917bee)) - プレースホルダテキストの色のコントラストを改善 ([#3228](https://github.com/box/box-ui-elements/issues/3228)) ([`1f7b9f9`](https://github.com/box/box-ui-elements/commit/1f7b9f9)) - 入力領域の`box-shadow`を更新 ([#3236](https://github.com/box/box-ui-elements/issues/3236)) ([`07cc347`](https://github.com/box/box-ui-elements/commit/07cc347)) - **assets:** アイコンの名前が変更された後に適切なアイコンを使用 ([#3138](https://github.com/box/box-ui-elements/issues/3138)) ([`2c80164`](https://github.com/box/box-ui-elements/commit/2c80164)) - **content-explorer:** `MoreOptions`ボタンに`aria-label`を追加 ([#3197](https://github.com/box/box-ui-elements/issues/3197)) ([`f4b69f0`](https://github.com/box/box-ui-elements/commit/f4b69f0)) - **content-explorer:** グリッドのスライダに`aria-label`を追加 ([#3189](https://github.com/box/box-ui-elements/issues/3189)) ([`e3900b3`](https://github.com/box/box-ui-elements/commit/e3900b3)) - **content-explorer:** 共有リンクが存在しない場合にデフォルトの共有リンクを作成 ([#3209](https://github.com/box/box-ui-elements/issues/3209)) ([`5d05a2b`](https://github.com/box/box-ui-elements/commit/5d05a2b)) - **content-explorer:** すべてのプロパティを`modalContainer`から`Modal`に渡す ([#3104](https://github.com/box/box-ui-elements/issues/3104)) ([`5d5b314`](https://github.com/box/box-ui-elements/commit/5d5b314)) - **content-explorer:** `styleguidist`の例からプロパティを削除 ([#3146](https://github.com/box/box-ui-elements/issues/3146)) ([`1f0809b`](https://github.com/box/box-ui-elements/commit/1f0809b)) - **content-picker:** フッターにわかりやすい名前を追加 ([#3177](https://github.com/box/box-ui-elements/issues/3177)) ([`bd8e1e6`](https://github.com/box/box-ui-elements/commit/bd8e1e6)) - **content-sidebar:** 返信操作のインタラクション ([#3103](https://github.com/box/box-ui-elements/issues/3103)) ([`9400f5a`](https://github.com/box/box-ui-elements/commit/9400f5a)) - **content-sidebar:** 返信操作のインタラクション ([#3123](https://github.com/box/box-ui-elements/issues/3123)) ([`8d2c3f1`](https://github.com/box/box-ui-elements/commit/8d2c3f1)) - **content-sidebar:** スレッド形式のフィード項目の選択状態とカーソルを合わせたときの状態 ([#3173](https://github.com/box/box-ui-elements/issues/3173)) ([`a7dc6a9`](https://github.com/box/box-ui-elements/commit/a7dc6a9)) - **content-uploader:** `UploadInput`のキーボードのアクセシビリティを修正 ([#3205](https://github.com/box/box-ui-elements/issues/3205)) ([`e918b5f`](https://github.com/box/box-ui-elements/commit/e918b5f)) - **dropdown-menu:** レスポンシブなドロップダウンメニューの位置を修正 ([#3149](https://github.com/box/box-ui-elements/issues/3149)) ([`729f6f1`](https://github.com/box/box-ui-elements/commit/729f6f1)) - **grid-view:** グリッドビュースライダのフォーカスのアウトラインを再表示 ([#3212](https://github.com/box/box-ui-elements/issues/3212)) ([`b35e977`](https://github.com/box/box-ui-elements/commit/b35e977)) - **i18n:** 翻訳を更新 ([#3105](https://github.com/box/box-ui-elements/issues/3105)) ([`b8521e4`](https://github.com/box/box-ui-elements/commit/b8521e4)) - **i18n:** 翻訳を更新 ([#3111](https://github.com/box/box-ui-elements/issues/3111)) ([`29fc19c`](https://github.com/box/box-ui-elements/commit/29fc19c)) - **i18n:** 翻訳を更新 ([#3121](https://github.com/box/box-ui-elements/issues/3121)) ([`16bc077`](https://github.com/box/box-ui-elements/commit/16bc077)) - **i18n:** 翻訳を更新 ([#3130](https://github.com/box/box-ui-elements/issues/3130)) ([`8ca714b`](https://github.com/box/box-ui-elements/commit/8ca714b)) - **i18n:** 翻訳を更新 ([#3135](https://github.com/box/box-ui-elements/issues/3135)) ([`53c0370`](https://github.com/box/box-ui-elements/commit/53c0370)) - **i18n:** 翻訳を更新 ([#3137](https://github.com/box/box-ui-elements/issues/3137)) ([`7fe32a6`](https://github.com/box/box-ui-elements/commit/7fe32a6)) - **i18n:** 翻訳を更新 ([#3139](https://github.com/box/box-ui-elements/issues/3139)) ([`82f414d`](https://github.com/box/box-ui-elements/commit/82f414d)) - **i18n:** 翻訳を更新 ([#3150](https://github.com/box/box-ui-elements/issues/3150)) ([`d428a43`](https://github.com/box/box-ui-elements/commit/d428a43)) - **i18n:** 翻訳を更新 ([#3158](https://github.com/box/box-ui-elements/issues/3158)) ([`02eb624`](https://github.com/box/box-ui-elements/commit/02eb624)) - **i18n:** 翻訳を更新 ([#3159](https://github.com/box/box-ui-elements/issues/3159)) ([`6df6f0d`](https://github.com/box/box-ui-elements/commit/6df6f0d)) - **i18n:** 翻訳を更新 ([#3174](https://github.com/box/box-ui-elements/issues/3174)) ([`0e9ea9d`](https://github.com/box/box-ui-elements/commit/0e9ea9d)) - **i18n:** 翻訳を更新 ([#3183](https://github.com/box/box-ui-elements/issues/3183)) ([`c32bbae`](https://github.com/box/box-ui-elements/commit/c32bbae)) - **i18n:** 翻訳を更新 ([#3199](https://github.com/box/box-ui-elements/issues/3199)) ([`eb1acee`](https://github.com/box/box-ui-elements/commit/eb1acee)) - **i18n:** 翻訳を更新 ([#3207](https://github.com/box/box-ui-elements/issues/3207)) ([`d9d571d`](https://github.com/box/box-ui-elements/commit/d9d571d)) - **i18n:** 翻訳を更新 ([#3213](https://github.com/box/box-ui-elements/issues/3213)) ([`64364c3`](https://github.com/box/box-ui-elements/commit/64364c3)) - **i18n:** 翻訳を更新 ([#3220](https://github.com/box/box-ui-elements/issues/3220)) ([`39739ab`](https://github.com/box/box-ui-elements/commit/39739ab)) - **i18n:** 翻訳を更新 ([#3222](https://github.com/box/box-ui-elements/issues/3222)) ([`429c856`](https://github.com/box/box-ui-elements/commit/429c856)) - **item-action:** `aria-label`を`PlainButton`に追加 ([#3180](https://github.com/box/box-ui-elements/issues/3180)) ([`2553713`](https://github.com/box/box-ui-elements/commit/2553713)) - **item-remove:** `aria-label`を追加 ([#3181](https://github.com/box/box-ui-elements/issues/3181)) ([`0fce635`](https://github.com/box/box-ui-elements/commit/0fce635)) - **menu:** メニューヘッダーの長いタイトルを修正 ([#3125](https://github.com/box/box-ui-elements/issues/3125)) ([`79420f2`](https://github.com/box/box-ui-elements/commit/79420f2)) - **modal:** 長いファイル名のウィンドウヘッダーが正しく表示されていない ([#3108](https://github.com/box/box-ui-elements/issues/3108)) ([`d8321aa`](https://github.com/box/box-ui-elements/commit/d8321aa)) - **react-virtualized:** `react-virtualized`を昇格 ([#3160](https://github.com/box/box-ui-elements/issues/3160)) ([`b256b07`](https://github.com/box/box-ui-elements/commit/b256b07)) - **react-virtualized:** 重複する`a11y`ラベルを削除 ([#3204](https://github.com/box/box-ui-elements/issues/3204)) ([`c67a4dd`](https://github.com/box/box-ui-elements/commit/c67a4dd)) - **react-virtualized:** `Table_Grid_innerScrollContainer`のロールを削除 ([#3218](https://github.com/box/box-ui-elements/issues/3218)) ([`cabb4a8`](https://github.com/box/box-ui-elements/commit/cabb4a8)) - **replies:** 返信を削除した後の`total_replies_count`値の更新を修正 ([#3147](https://github.com/box/box-ui-elements/issues/3147)) ([`8f75827`](https://github.com/box/box-ui-elements/commit/8f75827)) - **sharedlinksettings:** 有効期限のタイムスタンプを修正 ([#3179](https://github.com/box/box-ui-elements/issues/3179)) ([`1a698c5`](https://github.com/box/box-ui-elements/commit/1a698c5)) - **sub-header:** アクセシビリティラベルを`SortButton`に追加 ([#3178](https://github.com/box/box-ui-elements/issues/3178)) ([`ba66a34`](https://github.com/box/box-ui-elements/commit/ba66a34)) - **threaded-replies:** 保留ステータスの場合に返信ボタンを非アクティブ化 ([#3186](https://github.com/box/box-ui-elements/issues/3186)) ([`efbc532`](https://github.com/box/box-ui-elements/commit/efbc532)) - **threaded-replies:** 返信のスタイルを修正 ([#3110](https://github.com/box/box-ui-elements/issues/3110)) ([`f78e36b`](https://github.com/box/box-ui-elements/commit/f78e36b)) - **tooltips:** 小さい画面でエラーのツールチップが切り詰められている ([#3107](https://github.com/box/box-ui-elements/issues/3107)) ([`7e12d88`](https://github.com/box/box-ui-elements/commit/7e12d88)) - **usm:** `aria label`を追加 ([#3191](https://github.com/box/box-ui-elements/issues/3191)) ([`f1f5c81`](https://github.com/box/box-ui-elements/commit/f1f5c81)) - **usm:** `aria-label`を有効期限アイコンに追加 ([#3193](https://github.com/box/box-ui-elements/issues/3193)) ([`af3c567`](https://github.com/box/box-ui-elements/commit/af3c567)) - **usm:** ツールチップを閉じるボタンに`aria-label`を追加 ([#3211](https://github.com/box/box-ui-elements/issues/3211)) ([`529bf10`](https://github.com/box/box-ui-elements/commit/529bf10)) - **usm:** ロール`img`を共有リンクの有効期限のツールチップアイコンに追加 ([#3195](https://github.com/box/box-ui-elements/issues/3195)) ([`a79e193`](https://github.com/box/box-ui-elements/commit/a79e193)) - **usm:** ツールチップにダイアログを指定 ([#3226](https://github.com/box/box-ui-elements/issues/3226)) ([`f52ad0e`](https://github.com/box/box-ui-elements/commit/f52ad0e)) - `initialSelectedItems`を`ContentExplorer`に渡した場合に警告を削除 ([#3151](https://github.com/box/box-ui-elements/issues/3151)) ([`bf3256a`](https://github.com/box/box-ui-elements/commit/bf3256a)) ### コードのリファクタリング - `bdl-gray-62`の色を廃止 ([#3312](https://github.com/box/box-ui-elements/issues/3312)) ([`93720ce`](https://github.com/box/box-ui-elements/commit/93720ce)) ### 機能 - **aci-toggle:** 説明のために個別のプロパティを追加 ([#3307](https://github.com/box/box-ui-elements/issues/3307)) ([`cadab1d`](https://github.com/box/box-ui-elements/commit/cadab1d)) - **aci-toggle:** UIの調整 ([#3297](https://github.com/box/box-ui-elements/issues/3297)) ([`84f9abb`](https://github.com/box/box-ui-elements/commit/84f9abb)) - **annotation:** `AnnotationActivity`のアイコンインジケータを追加 ([#3176](https://github.com/box/box-ui-elements/issues/3176)) ([`f773aa3`](https://github.com/box/box-ui-elements/commit/f773aa3)) - **annotation-activity:** `AnnotationActivityLink`を非表示にする ([#3089](https://github.com/box/box-ui-elements/issues/3089)) ([`dc3642e`](https://github.com/box/box-ui-elements/commit/dc3642e)) - **annotation-thread:** 応答フォーム、UI、その他軽微な修正を追加 ([#3157](https://github.com/box/box-ui-elements/issues/3157)) ([`55ca058`](https://github.com/box/box-ui-elements/commit/55ca058)) - **annotation-thread:** 注釈スレッドのコメントの外観を修正 ([#3128](https://github.com/box/box-ui-elements/issues/3128)) ([`fac5133`](https://github.com/box/box-ui-elements/commit/fac5133)) - **annotation-thread:** 注釈スレッドのイベントの処理 ([#3196](https://github.com/box/box-ui-elements/issues/3196)) ([`1c07b41`](https://github.com/box/box-ui-elements/commit/1c07b41)) - **annotation-thread:** 注釈スレッドに関連したフックのリファクタリング ([#3192](https://github.com/box/box-ui-elements/issues/3192)) ([`0168f1a`](https://github.com/box/box-ui-elements/commit/0168f1a)) - **annotation-thread:** 注釈スレッドの返信イベントの処理 ([#3201](https://github.com/box/box-ui-elements/issues/3201)) ([`3df222a`](https://github.com/box/box-ui-elements/commit/3df222a)) - **annotation-thread:** `useAnnotationThread`を導入して`useAnnotatorEvents`を処理 ([#3097](https://github.com/box/box-ui-elements/issues/3097)) ([`a8d1985`](https://github.com/box/box-ui-elements/commit/a8d1985)) - **annotation-thread:** イベントエミッターとフックのリファクタリングの使用 ([#3184](https://github.com/box/box-ui-elements/issues/3184)) ([`cfed356`](https://github.com/box/box-ui-elements/commit/cfed356)) - **annotations:** `hasVersions`プロパティに基づいて`AnnotationActivityLink`を非表示にする ([#3132](https://github.com/box/box-ui-elements/issues/3132)) ([`3469413`](https://github.com/box/box-ui-elements/commit/3469413)) - **assets:** キャンセルフローのアセットを更新 ([#3117](https://github.com/box/box-ui-elements/issues/3117)) ([`42e1122`](https://github.com/box/box-ui-elements/commit/42e1122)) - **checkbox:** `onClick`イベントの`stopPropagation`を許可 ([#3122](https://github.com/box/box-ui-elements/issues/3122)) ([`9c25858`](https://github.com/box/box-ui-elements/commit/9c25858)) - **checkbox:** フォーカス動作を設定可能にする ([#3214](https://github.com/box/box-ui-elements/issues/3214)) ([`18b8ea6`](https://github.com/box/box-ui-elements/commit/18b8ea6)) - **checkbox:** 入力にクラスを追加するためのプロパティ ([#3194](https://github.com/box/box-ui-elements/issues/3194)) ([`e0cc12d`](https://github.com/box/box-ui-elements/commit/e0cc12d)) - **checkbox:** `onClick`イベントの`stopPropagation`を許可を取り消す ([#3127](https://github.com/box/box-ui-elements/issues/3127)) ([`e37de34`](https://github.com/box/box-ui-elements/commit/e37de34))、[#3122](https://github.com/box/box-ui-elements/issues/3122)をクローズ - **cloud-game:** セキュリティのクラウドゲームにアクセシビリティを追加 ([#3086](https://github.com/box/box-ui-elements/issues/3086)) ([`684e9f6`](https://github.com/box/box-ui-elements/commit/684e9f6)) - **collapsible-sidebar:** Boxのロゴを非表示にするためのプロパティを追加 ([#3256](https://github.com/box/box-ui-elements/issues/3256)) ([`43279c0`](https://github.com/box/box-ui-elements/commit/43279c0)) - **collapsible-sidebar:** `wrapperClassName`プロパティを追加 ([#3295](https://github.com/box/box-ui-elements/issues/3295)) ([`2cde065`](https://github.com/box/box-ui-elements/commit/2cde065)) - **content-explorer:** フォルダツリーを追加 ([#3240](https://github.com/box/box-ui-elements/issues/3240)) ([`03b0dea`](https://github.com/box/box-ui-elements/commit/03b0dea)) - **content-explorer:** `ContentExplorer`での空の選択を許可 ([#3175](https://github.com/box/box-ui-elements/issues/3175)) ([`fead6e4`](https://github.com/box/box-ui-elements/commit/fead6e4)) - **content-explorer:** [サブフォルダを含める] のクリック可能なステータスメッセージ ([#3266](https://github.com/box/box-ui-elements/issues/3266)) ([`3d8eaf8`](https://github.com/box/box-ui-elements/commit/3d8eaf8)) - **content-explorer:** [サブフォルダを含める] の切り替え ([#3242](https://github.com/box/box-ui-elements/issues/3242)) ([`b75c7ee`](https://github.com/box/box-ui-elements/commit/b75c7ee)) - **content-sidebar:** ファイル取得時のコールバック関数を追加 ([#3118](https://github.com/box/box-ui-elements/issues/3118)) ([`5373031`](https://github.com/box/box-ui-elements/commit/5373031)) - **content-sidebar:** アクティブなコメントの返信のサポートを追加 ([#3134](https://github.com/box/box-ui-elements/issues/3134)) ([`3ef81e1`](https://github.com/box/box-ui-elements/commit/3ef81e1)) - **content-sidebar:** 対応済みのコメント/注釈で「編集済み」を非表示にする ([#3152](https://github.com/box/box-ui-elements/issues/3152)) ([`07f5fc7`](https://github.com/box/box-ui-elements/commit/07f5fc7)) - **content-sidebar:** スレッド形式のフィード項目の選択状態とカーソルを合わせたときの状態 ([#3162](https://github.com/box/box-ui-elements/issues/3162)) ([`a6c125d`](https://github.com/box/box-ui-elements/commit/a6c125d)) - **input-with-copy:** 設定のボタン用にノードを追加 ([#3267](https://github.com/box/box-ui-elements/issues/3267)) ([`719b31f`](https://github.com/box/box-ui-elements/commit/719b31f)) - **insights:** 高度なコンテンツインサイトのサポートを追加 ([#3116](https://github.com/box/box-ui-elements/issues/3116)) ([`a66ec89`](https://github.com/box/box-ui-elements/commit/a66ec89)) - **left-nav:** `\_sizes.media.scss`で通常の幅を更新 ([#3131](https://github.com/box/box-ui-elements/issues/3131)) ([`aaf112d`](https://github.com/box/box-ui-elements/commit/aaf112d)) - **list-view:** リストビュー項目のカーソルを合わせたときの状態の変更 ([#3115](https://github.com/box/box-ui-elements/issues/3115)) ([`103a5d1`](https://github.com/box/box-ui-elements/commit/103a5d1)) - **make-selectable:** 選択してクリックする機能をチェックボックスのクリックに追加 ([#3112](https://github.com/box/box-ui-elements/issues/3112)) ([`ffc2e33`](https://github.com/box/box-ui-elements/commit/ffc2e33)) - **make-selectable:** `selectToggle`関数を公開 ([#3109](https://github.com/box/box-ui-elements/issues/3109)) ([`8d9fb90`](https://github.com/box/box-ui-elements/commit/8d9fb90)) - **mediaquery:** `isTouchScreen`のロジックを追加 ([#3269](https://github.com/box/box-ui-elements/issues/3269)) ([`3e80a06`](https://github.com/box/box-ui-elements/commit/3e80a06)) - **modal:** 共有リンクの読み込み時に権限を確認するコールバックを追加 ([#3188](https://github.com/box/box-ui-elements/issues/3188)) ([`2b316db`](https://github.com/box/box-ui-elements/commit/2b316db)) - **preview:** 機能フラグに新しい署名ドロップダウンを追加 ([#3190](https://github.com/box/box-ui-elements/issues/3190)) ([`37e8a19`](https://github.com/box/box-ui-elements/commit/37e8a19)) - **threaded-replies:** `Replies`コンポーネントを作成 ([#3288](https://github.com/box/box-ui-elements/issues/3288)) ([`006e33c`](https://github.com/box/box-ui-elements/commit/006e33c)) - **threaded-replies:** `RepliesToggle`コンポーネントを作成 ([#3294](https://github.com/box/box-ui-elements/issues/3294)) ([`92d0ddb`](https://github.com/box/box-ui-elements/commit/92d0ddb)) - **threaded-replies:** `Reply`ボタンコンポーネントを作成 ([#3298](https://github.com/box/box-ui-elements/issues/3298)) ([`f9d4130`](https://github.com/box/box-ui-elements/commit/f9d4130)) - **threaded-replies:** コメントから`ActivityCard`を分離 ([#3279](https://github.com/box/box-ui-elements/issues/3279)) ([`7d1d3bf`](https://github.com/box/box-ui-elements/commit/7d1d3bf)) - **threaded-replies:** 返信の作成と返信の切り替えを実装 ([#3304](https://github.com/box/box-ui-elements/issues/3304)) ([`044a336`](https://github.com/box/box-ui-elements/commit/044a336)) - **threaded-replies:** コメントコンポーネントが機能するようリファクタリング ([#3270](https://github.com/box/box-ui-elements/issues/3270)) ([`3900d1c`](https://github.com/box/box-ui-elements/commit/3900d1c)) - **threaded-replies:** アクティビティフィルタを更新して追加のオプションをサポート ([#3280](https://github.com/box/box-ui-elements/issues/3280)) ([`76e4010`](https://github.com/box/box-ui-elements/commit/76e4010)) - `ContentExplorerModalContainer`に`additionalColumns`プロパティを追加 ([#3143](https://github.com/box/box-ui-elements/issues/3143)) ([`d4eea59`](https://github.com/box/box-ui-elements/commit/d4eea59)) - `ContentExplorerModalContainer`にヘッダーを表示するためのオプションを追加 ([#3144](https://github.com/box/box-ui-elements/issues/3144)) ([`5685142`](https://github.com/box/box-ui-elements/commit/5685142)) - `DropdownMenu`に省略可能なtetherプロパティを追加 ([#3245](https://github.com/box/box-ui-elements/issues/3245)) ([`9db75e7`](https://github.com/box/box-ui-elements/commit/9db75e7)) - **threaded-replies:** 解決のスタイルを修正 ([#3129](https://github.com/box/box-ui-elements/issues/3129)) ([`b291c50`](https://github.com/box/box-ui-elements/commit/b291c50)) - **threaded-replies:** さらに返信を読み込んだときに返信を表示したままにする ([#3133](https://github.com/box/box-ui-elements/issues/3133)) ([`295533c`](https://github.com/box/box-ui-elements/commit/295533c)) - **tooltip:** エラーのツールチップの位置をサポート ([#3187](https://github.com/box/box-ui-elements/issues/3187)) ([`941e990`](https://github.com/box/box-ui-elements/commit/941e990)) - `ContentExplorerModal`に`rowHeight`プロパティを追加 ([#3140](https://github.com/box/box-ui-elements/issues/3140)) ([`476d739`](https://github.com/box/box-ui-elements/commit/476d739)) ### 取り消し - 「作業 (回答): content-answers要素の基盤を追加… ([#3249](https://github.com/box/box-ui-elements/issues/3249)) ([`56f58a5`](https://github.com/box/box-ui-elements/commit/56f58a5))、[#3247](https://github.com/box/box-ui-elements/issues/3247)をクローズ - **annotation-activity:** `AnnotationActivityLink`を非表示にする ([#3120](https://github.com/box/box-ui-elements/issues/3120)) ([`ba22807`](https://github.com/box/box-ui-elements/commit/ba22807))、[#3089](https://github.com/box/box-ui-elements/issues/3089)をクローズ ### 重大な変更 - `bdl-gray-62`は`bdl-gray-65`に置き換えられました **Source:** [https://ja.developer.box.com/changelog/2023-04-20-box-ui-elements-v1700-released](https://ja.developer.box.com/changelog/2023-04-20-box-ui-elements-v1700-released) --- ### Box UI Elements `v17.1.0`のリリース **Type:** changelog | **Section:** Changelog Box UI Elements v17.1.0のリリース 17.1.0 (2023-05-10) バグ修正 content-explorer: 空のフォルダの [すべて選択] チェックボックス (#3324) (a193adb) content-explorer… # Box UI Elements v17.1.0のリリース # 17.1.0 (2023-05-10) ### バグ修正 - **content-explorer:** 空のフォルダの [すべて選択] チェックボックス ([#3324](https://github.com/box/box-ui-elements/issues/3324)) ([`a193adb`](https://github.com/box/box-ui-elements/commit/a193adb)) - **content-explorer:** [すべて選択] チェックボックスの状態が`selectedItems`に一致 ([#3319](https://github.com/box/box-ui-elements/issues/3319)) ([`7473dfd`](https://github.com/box/box-ui-elements/commit/7473dfd)) - **i18n:** 翻訳を更新 ([#3313](https://github.com/box/box-ui-elements/issues/3313)) ([`dd9a1fd`](https://github.com/box/box-ui-elements/commit/dd9a1fd)) - **i18n:** 翻訳を更新 ([#3317](https://github.com/box/box-ui-elements/issues/3317)) ([`95618cf`](https://github.com/box/box-ui-elements/commit/95618cf)) - **pill-selector-dropdown:** `isPositionDynamic`のデフォルト値を削除 ([#3320](https://github.com/box/box-ui-elements/issues/3320)) ([`e74f824`](https://github.com/box/box-ui-elements/commit/e74f824)) - **preview:** Edgeで動画が読み込まれない ([#3326](https://github.com/box/box-ui-elements/issues/3326)) ([`e5aa7e5`](https://github.com/box/box-ui-elements/commit/e5aa7e5)) - **usm:** itemプロパティを任意化 ([#3322](https://github.com/box/box-ui-elements/issues/3322)) ([`fe7c4bb`](https://github.com/box/box-ui-elements/commit/fe7c4bb)) ### 機能 - **sharing:** Canvasファイルの共有リンクのメッセージを変更 ([#3315](https://github.com/box/box-ui-elements/issues/3315)) ([`fa17afd`](https://github.com/box/box-ui-elements/commit/fa17afd)) - **sharing:** Canvasファイルの共有リンクのメッセージを変更 ([#3318](https://github.com/box/box-ui-elements/issues/3318)) ([`60a3a6e`](https://github.com/box/box-ui-elements/commit/60a3a6e)) **Source:** [https://ja.developer.box.com/changelog/2023-05-10-box-ui-elements-v1710-released](https://ja.developer.box.com/changelog/2023-05-10-box-ui-elements-v1710-released) --- ### Box UI Elements `v18.0.0`のリリース **Type:** changelog | **Section:** Changelog Box UI Elements v18.0.0のリリース 18.0.0 (2023-06-27) バグ修正 ci: releaseスクリプトの変数から空白を削除 (#3355) (2553ec1) content-explorer… # Box UI Elements v18.0.0のリリース # 18.0.0 (2023-06-27) ### バグ修正 - **ci:** releaseスクリプトの変数から空白を削除 ([#3355](https://github.com/box/box-ui-elements/issues/3355)) ([`2553ec1`](https://github.com/box/box-ui-elements/commit/2553ec1)) - **content-explorer:** グリッドボタンのスタイルの詳細度を向上 ([#3328](https://github.com/box/box-ui-elements/issues/3328)) ([`b2c878a`](https://github.com/box/box-ui-elements/commit/b2c878a)) - **content-explorer:** 未定義のオブジェクトで呼び出されるマッピング ([#3341](https://github.com/box/box-ui-elements/issues/3341)) ([`da6ada0`](https://github.com/box/box-ui-elements/commit/da6ada0)) - **content-picker:** フォルダ作成時の名前入力のトリミング ([#3364](https://github.com/box/box-ui-elements/issues/3364)) ([`4629726`](https://github.com/box/box-ui-elements/commit/4629726)) - **css:** IE7 CSSハックを削除してParcelのサポートを修正 ([#3368](https://github.com/box/box-ui-elements/issues/3368)) ([`cbff7f1`](https://github.com/box/box-ui-elements/commit/cbff7f1)) - **i18n:** 翻訳を更新 ([#3323](https://github.com/box/box-ui-elements/issues/3323)) ([`c810383`](https://github.com/box/box-ui-elements/commit/c810383)) - **i18n:** 翻訳を更新 ([#3344](https://github.com/box/box-ui-elements/issues/3344)) ([`755d64b`](https://github.com/box/box-ui-elements/commit/755d64b)) - **i18n:** 翻訳を更新 ([#3349](https://github.com/box/box-ui-elements/issues/3349)) ([`6ba9f27`](https://github.com/box/box-ui-elements/commit/6ba9f27)) - **i18n:** 翻訳を更新 ([#3351](https://github.com/box/box-ui-elements/issues/3351)) ([`4ff75e8`](https://github.com/box/box-ui-elements/commit/4ff75e8)) - **i18n:** 翻訳を更新 ([#3352](https://github.com/box/box-ui-elements/issues/3352)) ([`80c795a`](https://github.com/box/box-ui-elements/commit/80c795a)) - **i18n:** 翻訳を更新 ([#3359](https://github.com/box/box-ui-elements/issues/3359)) ([`c94305c`](https://github.com/box/box-ui-elements/commit/c94305c)) - **preview:** サムネイルのサイドバーの幅を更新 ([#3363](https://github.com/box/box-ui-elements/issues/3363)) ([`33c8236`](https://github.com/box/box-ui-elements/commit/33c8236)) - **sharing:** Canvasファイルの共有リンクのメッセージを削除 ([#3337](https://github.com/box/box-ui-elements/issues/3337)) ([`9558474`](https://github.com/box/box-ui-elements/commit/9558474)) - 共有リンクのビューアー権限の調整 ([#3335](https://github.com/box/box-ui-elements/issues/3335)) ([`5d78c11`](https://github.com/box/box-ui-elements/commit/5d78c11)) - 要素のテストページでdistパスとReactバージョンを更新 ([#3350](https://github.com/box/box-ui-elements/issues/3350)) ([`38ff124`](https://github.com/box/box-ui-elements/commit/38ff124)) - **pill-selector-dropdown:** `showAvatars`プロパティを`RoundPill`にパス ([#3329](https://github.com/box/box-ui-elements/issues/3329)) ([`5632743`](https://github.com/box/box-ui-elements/commit/5632743)) - **share-form:** 未定義のオブジェクトで呼び出されるマッピング ([#3340](https://github.com/box/box-ui-elements/issues/3340)) ([`a24abb2`](https://github.com/box/box-ui-elements/commit/a24abb2)) - **usm:** 共有ウィンドウのアップグレード通知のメッセージを修正 ([#3334](https://github.com/box/box-ui-elements/issues/3334)) ([`4a945ce`](https://github.com/box/box-ui-elements/commit/4a945ce)) ### 作業 - **deps:** `react-beautiful-dnd`をバージョン11.0.5に昇格 ([#3345](https://github.com/box/box-ui-elements/issues/3345)) ([`610c9d2`](https://github.com/box/box-ui-elements/commit/610c9d2)) - **node:** Node 18にアップグレード ([#3347](https://github.com/box/box-ui-elements/issues/3347)) ([`cbb3840`](https://github.com/box/box-ui-elements/commit/cbb3840)) ### 機能 - **cloud-game:** クラウドゲームの外観を調整 ([#3361](https://github.com/box/box-ui-elements/issues/3361)) ([`fe7fb51`](https://github.com/box/box-ui-elements/commit/fe7fb51)) - **pill-selector-dropdown:** エラーのツールチップの位置設定を許可 ([#3330](https://github.com/box/box-ui-elements/issues/3330)) ([`8df1551`](https://github.com/box/box-ui-elements/commit/8df1551)) - **preview:** デフォルトのPreview SDKのバージョンを更新 ([#3366](https://github.com/box/box-ui-elements/issues/3366)) ([`aa7a875`](https://github.com/box/box-ui-elements/commit/aa7a875)) - **security-controls:** 電子すかしの [詳細を表示] リンクを削除 ([#3353](https://github.com/box/box-ui-elements/issues/3353)) ([`379d055`](https://github.com/box/box-ui-elements/commit/379d055)) - **threaded-replies:** 注釈に対する返信 ([#3331](https://github.com/box/box-ui-elements/issues/3331)) ([`4f65525`](https://github.com/box/box-ui-elements/commit/4f65525)) - **uaa-integration:** UAAを`ActivitySidebar`に統合 ([#3316](https://github.com/box/box-ui-elements/issues/3316)) ([`b81e976`](https://github.com/box/box-ui-elements/commit/b81e976)) ### 重大な変更 **deps:** 使用中のプロジェクトにおける`react-beautiful-dnd`のバージョン11.0.5へのアップグレードが必要 **node:** Node 18にアップグレード **Source:** [https://ja.developer.box.com/changelog/2023-06-27-box-ui-elements-v1800-released](https://ja.developer.box.com/changelog/2023-06-27-box-ui-elements-v1800-released) --- ### Box UI Elements `v18.1.0`のリリース **Type:** changelog | **Section:** Changelog Box UI Elements v18.1.0のリリース 18.1.0 (2023-07-12) バグ修正 content-picker: デフォルトの共有リンクの共有権限を確認 (#3371) (2bb1ddb) i18n: 翻訳を更新 (#3372) (f01fd6d… # Box UI Elements v18.1.0のリリース # 18.1.0 (2023-07-12) ### バグ修正 - **content-picker:** デフォルトの共有リンクの共有権限を確認 ([#3371](https://github.com/box/box-ui-elements/issues/3371)) ([`2bb1ddb`](https://github.com/box/box-ui-elements/commit/2bb1ddb)) - **i18n:** 翻訳を更新 ([#3372](https://github.com/box/box-ui-elements/issues/3372)) ([`f01fd6d`](https://github.com/box/box-ui-elements/commit/f01fd6d)) - **readme:** `langauge`の誤字を修正 ([#3373](https://github.com/box/box-ui-elements/issues/3373)) ([`50e7fe0`](https://github.com/box/box-ui-elements/commit/50e7fe0)) ### 機能 - **uaa-integration:** UAAのアクティビティタイプをフィルタ ([#3369](https://github.com/box/box-ui-elements/issues/3369)) ([`b9d196f`](https://github.com/box/box-ui-elements/commit/b9d196f)) **Source:** [https://ja.developer.box.com/changelog/2023-07-12-box-ui-elements-v1810-released](https://ja.developer.box.com/changelog/2023-07-12-box-ui-elements-v1810-released) --- ### Box UI Elements `v19.0.0`のリリース **Type:** changelog | **Section:** Changelog Box UI Elements v19.0.0のリリース 19.0.0 (2024/01/25) バグ修正 activity-feed-zoom: 項目コンテナにmin-heightプロパティを追加 (#3411) (a60a70d) button… # Box UI Elements v19.0.0のリリース # 19.0.0 (2024/01/25) ### バグ修正 - **activity-feed-zoom:** 項目コンテナにmin-heightプロパティを追加 ([#3411](https://github.com/box/box-ui-elements/issues/3411)) ([`a60a70d`](https://github.com/box/box-ui-elements/commit/a60a70d)) - **button:** アクセシビリティのためにariaラベルを追加 ([#3377](https://github.com/box/box-ui-elements/issues/3377)) ([`9a9b5e3`](https://github.com/box/box-ui-elements/commit/9a9b5e3)) - **content-answers:** stylesに`bdl`プレフィックスを追加 ([#3421](https://github.com/box/box-ui-elements/issues/3421)) ([`fdbfc4d`](https://github.com/box/box-ui-elements/commit/fdbfc4d)) - **content-explorer:** 404の発生時に`onDelete`コールバックの成功を許可 ([#3468](https://github.com/box/box-ui-elements/issues/3468)) ([`13ed6da`](https://github.com/box/box-ui-elements/commit/13ed6da)) - **content-explorer:** デバイスがダウンロードをサポートするかどうかを検出 ([#3480](https://github.com/box/box-ui-elements/issues/3480)) ([`fa68f9b`](https://github.com/box/box-ui-elements/commit/fa68f9b)) - **content-explorer:** 階層リンクにおけるテキストの省略を修正 ([#3481](https://github.com/box/box-ui-elements/issues/3481)) ([`6099b1d`](https://github.com/box/box-ui-elements/commit/6099b1d)) - **content-explorer:** 残っていた`contentPreviewProps`を削除 ([#3489](https://github.com/box/box-ui-elements/issues/3489)) ([`4181e0c`](https://github.com/box/box-ui-elements/commit/4181e0c)) - **content-explorer:** デバイスが小さい場合にページ数を表示 ([#3498](https://github.com/box/box-ui-elements/issues/3498)) ([`98537b9`](https://github.com/box/box-ui-elements/commit/98537b9)) - **content-picker:** ページ割りコンポーネントを使用して適切なスタイルをインポート ([#3472](https://github.com/box/box-ui-elements/issues/3472)) ([`6aef87b`](https://github.com/box/box-ui-elements/commit/6aef87b)) - **content-sidebar:** 注釈の上に積み重なるようにZインデックスを大きくする ([#3478](https://github.com/box/box-ui-elements/issues/3478)) ([`762b82d`](https://github.com/box/box-ui-elements/commit/762b82d)) - **content-uploader:** テキストの省略を追加して間隔を調整 ([#3479](https://github.com/box/box-ui-elements/issues/3479)) ([`36df228`](https://github.com/box/box-ui-elements/commit/36df228)) - **flyout:** Flyoutのデフォルトのロールを「dialog」に設定 ([#3388](https://github.com/box/box-ui-elements/issues/3388)) ([`942f6b7`](https://github.com/box/box-ui-elements/commit/942f6b7)) - **i18n:** 翻訳を更新 ([#3396](https://github.com/box/box-ui-elements/issues/3396)) ([`2175a82`](https://github.com/box/box-ui-elements/commit/2175a82)) - **i18n:** 翻訳を更新 ([#3398](https://github.com/box/box-ui-elements/issues/3398)) ([`4d71c62`](https://github.com/box/box-ui-elements/commit/4d71c62)) - **i18n:** 翻訳を更新 ([#3401](https://github.com/box/box-ui-elements/issues/3401)) ([`0911005`](https://github.com/box/box-ui-elements/commit/0911005)) - **i18n:** 翻訳を更新 ([#3409](https://github.com/box/box-ui-elements/issues/3409)) ([`4c95746`](https://github.com/box/box-ui-elements/commit/4c95746)) - **i18n:** 翻訳を更新 ([#3413](https://github.com/box/box-ui-elements/issues/3413)) ([`65eb428`](https://github.com/box/box-ui-elements/commit/65eb428)) - **i18n:** 翻訳を更新 ([#3417](https://github.com/box/box-ui-elements/issues/3417)) ([`9aab003`](https://github.com/box/box-ui-elements/commit/9aab003)) - **i18n:** 翻訳を更新 ([#3422](https://github.com/box/box-ui-elements/issues/3422)) ([`523492a`](https://github.com/box/box-ui-elements/commit/523492a)) - **i18n:** 翻訳を更新 ([#3430](https://github.com/box/box-ui-elements/issues/3430)) ([`7b705bc`](https://github.com/box/box-ui-elements/commit/7b705bc)) - **i18n:** 翻訳を更新 ([#3433](https://github.com/box/box-ui-elements/issues/3433)) ([`0e8decb`](https://github.com/box/box-ui-elements/commit/0e8decb)) - **i18n:** 翻訳を更新 ([#3434](https://github.com/box/box-ui-elements/issues/3434)) ([`15e2e2e`](https://github.com/box/box-ui-elements/commit/15e2e2e)) - **i18n:** 翻訳を更新 ([#3437](https://github.com/box/box-ui-elements/issues/3437)) ([`0d06403`](https://github.com/box/box-ui-elements/commit/0d06403)) - **i18n:** 翻訳を更新 ([#3438](https://github.com/box/box-ui-elements/issues/3438)) ([`a6f4868`](https://github.com/box/box-ui-elements/commit/a6f4868)) - **i18n:** 翻訳を更新 ([#3452](https://github.com/box/box-ui-elements/issues/3452)) ([`22bb031`](https://github.com/box/box-ui-elements/commit/22bb031)) - **i18n:** 翻訳を更新 ([#3453](https://github.com/box/box-ui-elements/issues/3453)) ([`85d2521`](https://github.com/box/box-ui-elements/commit/85d2521)) - **i18n:** 翻訳を更新 ([#3454](https://github.com/box/box-ui-elements/issues/3454)) ([`e83185e`](https://github.com/box/box-ui-elements/commit/e83185e)) - **i18n:** 翻訳を更新 ([#3455](https://github.com/box/box-ui-elements/issues/3455)) ([`a10aa5c`](https://github.com/box/box-ui-elements/commit/a10aa5c)) - **i18n:** 翻訳を更新 ([#3456](https://github.com/box/box-ui-elements/issues/3456)) ([`41ad809`](https://github.com/box/box-ui-elements/commit/41ad809)) - **i18n:** 翻訳を更新 ([#3457](https://github.com/box/box-ui-elements/issues/3457)) ([`b3f57ff`](https://github.com/box/box-ui-elements/commit/b3f57ff)) - **i18n:** 翻訳を更新 ([#3458](https://github.com/box/box-ui-elements/issues/3458)) ([`a1c42d7`](https://github.com/box/box-ui-elements/commit/a1c42d7)) - **i18n:** 翻訳を更新 ([#3459](https://github.com/box/box-ui-elements/issues/3459)) ([`1b6f4c2`](https://github.com/box/box-ui-elements/commit/1b6f4c2)) - **i18n:** 翻訳を更新 ([#3462](https://github.com/box/box-ui-elements/issues/3462)) ([`13fc9b0`](https://github.com/box/box-ui-elements/commit/13fc9b0)) - **i18n:** 翻訳を更新 ([#3464](https://github.com/box/box-ui-elements/issues/3464)) ([`d1a888d`](https://github.com/box/box-ui-elements/commit/d1a888d)) - **i18n:** 翻訳を更新 ([#3465](https://github.com/box/box-ui-elements/issues/3465)) ([`5413089`](https://github.com/box/box-ui-elements/commit/5413089)) - **i18n:** 翻訳を更新 ([#3469](https://github.com/box/box-ui-elements/issues/3469)) ([`2ffe17f`](https://github.com/box/box-ui-elements/commit/2ffe17f)) - **i18n:** 翻訳を更新 ([#3470](https://github.com/box/box-ui-elements/issues/3470)) ([`1139bb0`](https://github.com/box/box-ui-elements/commit/1139bb0)) - **i18n:** 翻訳を更新 ([#3471](https://github.com/box/box-ui-elements/issues/3471)) ([`41e02db`](https://github.com/box/box-ui-elements/commit/41e02db)) - **modal-dialog:** `ModalDialog`にaria-modalを追加 ([#3380](https://github.com/box/box-ui-elements/issues/3380)) ([`c8f8509`](https://github.com/box/box-ui-elements/commit/c8f8509)) - **modify-reply:** オブジェクトをパラメータにマッピング ([#3387](https://github.com/box/box-ui-elements/issues/3387)) ([`3989675`](https://github.com/box/box-ui-elements/commit/3989675)) - **preview:** 注釈のバッジタイプアイコンにアクセシビリティを追加 ([#3404](https://github.com/box/box-ui-elements/issues/3404)) ([`d4b7852`](https://github.com/box/box-ui-elements/commit/d4b7852)) - **preview:** バージョンのパネルで操作のフォーカスインジケータを変更 ([#3397](https://github.com/box/box-ui-elements/issues/3397)) ([`f111c64`](https://github.com/box/box-ui-elements/commit/f111c64)) - **preview:** 昇格者フィールドに適切なユーザーを表示 ([#3414](https://github.com/box/box-ui-elements/issues/3414)) ([`458fdbf`](https://github.com/box/box-ui-elements/commit/458fdbf)) - **preview:** `onDismiss`コールバックをオーバーライドしないようにHOCを拡張 ([#3431](https://github.com/box/box-ui-elements/issues/3431)) ([`4cc57a3`](https://github.com/box/box-ui-elements/commit/4cc57a3)) - **search-form:** 検索操作コンポーネントを抽出 ([#3475](https://github.com/box/box-ui-elements/issues/3475)) ([`8d77320`](https://github.com/box/box-ui-elements/commit/8d77320)) - ボタンが非アクティブの場合に`textInputWithCopyButton`でコピーを非アクティブ化 ([#3419](https://github.com/box/box-ui-elements/issues/3419)) ([`68b2def`](https://github.com/box/box-ui-elements/commit/68b2def)) - 表示されていない場合にスクリーンリーダーに対してアップロードマネージャの進捗バーを非表示にする ([#3383](https://github.com/box/box-ui-elements/issues/3383)) ([`5592a48`](https://github.com/box/box-ui-elements/commit/5592a48)) - examplesラッパーから`core-js`を削除 ([#3392](https://github.com/box/box-ui-elements/issues/3392)) ([`48ccdf7`](https://github.com/box/box-ui-elements/commit/48ccdf7)) - 内部Boxユーザーの名前を削除 ([#3390](https://github.com/box/box-ui-elements/issues/3390)) ([`65cc5cb`](https://github.com/box/box-ui-elements/commit/65cc5cb)) - **preview-sidebar:** プレビューのバージョンの動作を修正 ([#3203](https://github.com/box/box-ui-elements/issues/3203)) ([`d940782`](https://github.com/box/box-ui-elements/commit/d940782)) - テストページのソースパスを更新 ([#3378](https://github.com/box/box-ui-elements/issues/3378)) ([`ff6b349`](https://github.com/box/box-ui-elements/commit/ff6b349)) ### 機能 - **aci:** featuresプロパティに`ACI`の構成を追加 ([#3410](https://github.com/box/box-ui-elements/issues/3410)) ([`e95a35e`](https://github.com/box/box-ui-elements/commit/e95a35e)) - **activityitems:** 新しいレイアウト ([#3405](https://github.com/box/box-ui-elements/issues/3405)) ([`665d30a`](https://github.com/box/box-ui-elements/commit/665d30a)) - **annotations:** 注釈の返信を編集 ([#3412](https://github.com/box/box-ui-elements/issues/3412)) ([`025ad7e`](https://github.com/box/box-ui-elements/commit/025ad7e)) - **assets:** Box AIアセットを追加 ([#3393](https://github.com/box/box-ui-elements/issues/3393)) ([`bc6b04d`](https://github.com/box/box-ui-elements/commit/bc6b04d)) - **content-answers:** `contentAnswers`ウィンドウのヘッダーとフッターを追加 ([#3403](https://github.com/box/box-ui-elements/issues/3403)) ([`a7d0a3e`](https://github.com/box/box-ui-elements/commit/a7d0a3e)) - **content-answers:** インラインエラーを追加 ([#3444](https://github.com/box/box-ui-elements/issues/3444)) ([`405cdb4`](https://github.com/box/box-ui-elements/commit/405cdb4)) - **content-answers:** 最初のウェルカムメッセージを含むウィンドウ本文を追加 ([#3415](https://github.com/box/box-ui-elements/issues/3415)) ([`6748e73`](https://github.com/box/box-ui-elements/commit/6748e73)) - **content-answers:** `contentAnswers`の表示を制御するプロパティを追加 ([#3399](https://github.com/box/box-ui-elements/issues/3399)) ([`f0b0922`](https://github.com/box/box-ui-elements/commit/f0b0922)) - **content-answers:** 下までのスクロールを追加 ([#3442](https://github.com/box/box-ui-elements/issues/3442)) ([`59c8c45`](https://github.com/box/box-ui-elements/commit/59c8c45)) - **content-answers:** アバター ([#3418](https://github.com/box/box-ui-elements/issues/3418)) ([`45166f4`](https://github.com/box/box-ui-elements/commit/45166f4)) - **content-answers:** ボタンのフォーカス ([#3448](https://github.com/box/box-ui-elements/issues/3448)) ([`2358321`](https://github.com/box/box-ui-elements/commit/2358321)) - **content-answers:** Content Answersウィンドウのエラー ([#3425](https://github.com/box/box-ui-elements/issues/3425)) ([`a5084a5`](https://github.com/box/box-ui-elements/commit/a5084a5)) - **content-answers:** content-answersウィンドウの最初のボタンコンポーネントを作成 ([#3395](https://github.com/box/box-ui-elements/issues/3395)) ([`217a393`](https://github.com/box/box-ui-elements/commit/217a393)) - **content-answers:** 許可されてないファイルタイプの場合にボタンを非アクティブ化 ([#3406](https://github.com/box/box-ui-elements/issues/3406)) ([`f950772`](https://github.com/box/box-ui-elements/commit/f950772)) - **content-answers:** インテリジェンスAPI ([#3420](https://github.com/box/box-ui-elements/issues/3420)) ([`76fd991`](https://github.com/box/box-ui-elements/commit/76fd991)) - **content-answers:** Questions Answersインテリジェンスエンドポイント ([#3435](https://github.com/box/box-ui-elements/issues/3435)) ([`4c7c0c0`](https://github.com/box/box-ui-elements/commit/4c7c0c0)) - **content-answers:** 再試行ボタン ([#3451](https://github.com/box/box-ui-elements/issues/3451)) ([`e0976b8`](https://github.com/box/box-ui-elements/commit/e0976b8)) - **content-explorer:** 自動選択された項目をコンテンツエクスプローラに追加 ([#3474](https://github.com/box/box-ui-elements/issues/3474)) ([`215cfdd`](https://github.com/box/box-ui-elements/commit/215cfdd)) - **content-sidebar:** プレビューとサイドバーへのレスポンスを有効化 ([#3497](https://github.com/box/box-ui-elements/issues/3497)) ([`1652982`](https://github.com/box/box-ui-elements/commit/1652982)) - **label-primitive:** ラベルにプロパティを渡す ([#3473](https://github.com/box/box-ui-elements/issues/3473)) ([`7e88772`](https://github.com/box/box-ui-elements/commit/7e88772)) - **modal:** レスポンスの動作を有効化 ([#3492](https://github.com/box/box-ui-elements/issues/3492)) ([`7fe59b8`](https://github.com/box/box-ui-elements/commit/7fe59b8)) - **pill-selector:** テキスト入力に関するオプションをさらに追加 ([#3440](https://github.com/box/box-ui-elements/issues/3440)) ([`d782e4a`](https://github.com/box/box-ui-elements/commit/d782e4a)) - **preview:** 返信および変更用のコメントフォームをフォーカス ([#3407](https://github.com/box/box-ui-elements/issues/3407)) ([`69293d8`](https://github.com/box/box-ui-elements/commit/69293d8)) - **threaded-replies:** 注釈の対応/未対応を追加 ([#3423](https://github.com/box/box-ui-elements/issues/3423)) ([`c489ad3`](https://github.com/box/box-ui-elements/commit/c489ad3)) - **threaded-replies:** スレッド形式の返信コメントを削除 ([#3402](https://github.com/box/box-ui-elements/issues/3402)) ([`37437c5`](https://github.com/box/box-ui-elements/commit/37437c5)) - **uaa-integration:** コメントの権限がない場合に処理 ([#3394](https://github.com/box/box-ui-elements/issues/3394)) ([`5a28b49`](https://github.com/box/box-ui-elements/commit/5a28b49)) - **uaa-integration:** アプリアクティビティ項目を解析 ([#3386](https://github.com/box/box-ui-elements/issues/3386)) ([`44fd12b`](https://github.com/box/box-ui-elements/commit/44fd12b)) - **uaa-integration:** UAAからのバージョンのレスポンスを解析 ([#3385](https://github.com/box/box-ui-elements/issues/3385)) ([`0fa730f`](https://github.com/box/box-ui-elements/commit/0fa730f)) - **usm:** レスポンスの動作を有効化 ([#3494](https://github.com/box/box-ui-elements/issues/3494)) ([`76db2a5`](https://github.com/box/box-ui-elements/commit/76db2a5)) - IE11のブラウザサポートを削除 ([#3382](https://github.com/box/box-ui-elements/issues/3382)) ([`e151c87`](https://github.com/box/box-ui-elements/commit/e151c87)) ### 取り消し - 「作業 (コード所有者): コード所有者を一時的に更新 ([#3446](https://github.com/box/box-ui-elements/issues/3446))」([#3476](https://github.com/box/box-ui-elements/issues/3476)) ([`3e38fa5`](https://github.com/box/box-ui-elements/commit/3e38fa5)) ### 重大な変更 - Internet Explorer 11はサポートされなくなりました **Source:** [https://ja.developer.box.com/changelog/2024-01-25-box-ui-elements-v1900-released](https://ja.developer.box.com/changelog/2024-01-25-box-ui-elements-v1900-released) --- ### Box UI Elements `v20.0.0`のリリース **Type:** changelog | **Section:** Changelog Box UI Elements v20.0.0のリリース 20.0.0 (2024/05/22) バグ修正 content-answers: content answersウィンドウにスタイルをスコープ (#3548) (97d49ff) fonts… # Box UI Elements v20.0.0のリリース # 20.0.0 (2024/05/22) ### バグ修正 - **content-answers:** content answersウィンドウにスタイルをスコープ ([#3548](https://github.com/box/box-ui-elements/issues/3548)) ([`97d49ff`](https://github.com/box/box-ui-elements/commit/97d49ff)) - **fonts:** 共通するフォントのバージョンを更新 ([#3499](https://github.com/box/box-ui-elements/issues/3499)) ([`870de6d`](https://github.com/box/box-ui-elements/commit/870de6d)) - **i18n:** 翻訳を更新 ([#3508](https://github.com/box/box-ui-elements/issues/3508)) ([`785be2a`](https://github.com/box/box-ui-elements/commit/785be2a)) - **i18n:** 翻訳を更新 ([#3509](https://github.com/box/box-ui-elements/issues/3509)) ([`85ebf26`](https://github.com/box/box-ui-elements/commit/85ebf26)) - **i18n:** 翻訳を更新 ([#3516](https://github.com/box/box-ui-elements/issues/3516)) ([`cb470e9`](https://github.com/box/box-ui-elements/commit/cb470e9)) - **i18n:** 翻訳を更新 ([#3525](https://github.com/box/box-ui-elements/issues/3525)) ([`ffb447c`](https://github.com/box/box-ui-elements/commit/ffb447c)) - **i18n:** 翻訳を更新 ([#3528](https://github.com/box/box-ui-elements/issues/3528)) ([`1cf016f`](https://github.com/box/box-ui-elements/commit/1cf016f)) - **i18n:** 翻訳を更新 ([#3534](https://github.com/box/box-ui-elements/issues/3534)) ([`36e95a9`](https://github.com/box/box-ui-elements/commit/36e95a9)) - **i18n:** 翻訳を更新 ([#3535](https://github.com/box/box-ui-elements/issues/3535)) ([`c8d03c3`](https://github.com/box/box-ui-elements/commit/c8d03c3)) - **i18n:** 翻訳を更新 ([#3538](https://github.com/box/box-ui-elements/issues/3538)) ([`cde1b88`](https://github.com/box/box-ui-elements/commit/cde1b88)) - **i18n:** 翻訳を更新 ([#3540](https://github.com/box/box-ui-elements/issues/3540)) ([`a7043e6`](https://github.com/box/box-ui-elements/commit/a7043e6)) - **i18n:** 翻訳を更新 ([#3541](https://github.com/box/box-ui-elements/issues/3541)) ([`3ced4a5`](https://github.com/box/box-ui-elements/commit/3ced4a5)) - **`multiput-upload`:** アップロードのパフォーマンスを改善 ([#3512](https://github.com/box/box-ui-elements/issues/3512)) ([`2583e94`](https://github.com/box/box-ui-elements/commit/2583e94)) - **`npm`:** `npmignore`にchromatic configを追加 ([#3546](https://github.com/box/box-ui-elements/issues/3546)) ([`e2e6731`](https://github.com/box/box-ui-elements/commit/e2e6731)) - **preview:** デフォルトのプレビューバージョンを`2.106.0`に更新 ([#3555](https://github.com/box/box-ui-elements/issues/3555)) ([`f07d616`](https://github.com/box/box-ui-elements/commit/f07d616)) - **`react-intl`:** 相対時間の単体テストで日付をモック ([#3518](https://github.com/box/box-ui-elements/issues/3518)) ([`3ce175b`](https://github.com/box/box-ui-elements/commit/3ce175b)) - **shared-link-settings-modal:** 有効期限の形式を修正 ([#3545](https://github.com/box/box-ui-elements/issues/3545)) ([`e47892f`](https://github.com/box/box-ui-elements/commit/e47892f)) - **upload:** `multiput`のアップロードパフォーマンス2を改善 ([#3517](https://github.com/box/box-ui-elements/issues/3517)) ([`2440746`](https://github.com/box/box-ui-elements/commit/2440746)) - **usm:** 項目タイプをhubsに修正 ([#3532](https://github.com/box/box-ui-elements/issues/3532)) ([`0d1e9cf`](https://github.com/box/box-ui-elements/commit/0d1e9cf)) - **usm:** アップセルの表示時にリンクの説明を非表示にする ([#3553](https://github.com/box/box-ui-elements/issues/3553)) ([`838a2e8`](https://github.com/box/box-ui-elements/commit/838a2e8)) ### 機能 - **content-explorer:** ウィンドウのレンダリング時にPortalを使用しないことを許可 ([#3501](https://github.com/box/box-ui-elements/issues/3501)) ([`b096d38`](https://github.com/box/box-ui-elements/commit/b096d38)) - **content-uploader:** コンテンツアップローダーに`allowPrepopulateFiles`プロパティを追加 ([#3519](https://github.com/box/box-ui-elements/issues/3519)) ([`12427b1`](https://github.com/box/box-ui-elements/commit/12427b1)) - **content-uploader:** ファイルの転送を成功させるために部分的なアップロードを実装 ([#3529](https://github.com/box/box-ui-elements/issues/3529)) ([`e70825c`](https://github.com/box/box-ui-elements/commit/e70825c)) - **docgen:** docgenのサイドバーベース ([#3484](https://github.com/box/box-ui-elements/issues/3484)) ([`4b18b21`](https://github.com/box/box-ui-elements/commit/4b18b21)) - **`react-intl`:** `react-intl`パッケージを昇格 [重大な変更] ([#3466](https://github.com/box/box-ui-elements/issues/3466)) ([`307c6a4`](https://github.com/box/box-ui-elements/commit/307c6a4)) - **usm:** hubsのアクセスレベルのラベルを追加 ([#3526](https://github.com/box/box-ui-elements/issues/3526)) ([`6504480`](https://github.com/box/box-ui-elements/commit/6504480)) - **usm:** インライン通知をコンポーネントとして追加 ([#3549](https://github.com/box/box-ui-elements/issues/3549)) ([`d646c65`](https://github.com/box/box-ui-elements/commit/d646c65)) ### 重大な変更 **`react-intl`:** `react-intl`依存関係のメジャーバージョンをアップグレード 修正: `intl`のタイプを修正 修正: メッセージの構文を修正 修正: コメントおよびi18n readmeファイルを修正 修正: `react-intl`のバージョンのコメントを修正 修正: jsファイルで`IntlShape`を型として使用 修正: `IntlShape`の型のインポートを修正 修正: 解決策を追加 修正: 他のリポジトリに一致するよう正確なバージョンを使用 修正: `IntlShape`の型のインポートを修正 修正: 従来のバージョンのサポートをすべて削除 修正: `relativeTime`ヘルパー関数を追加 修正: `PresenceAvatarTooltipContent`コンポーネントの`relativeTime`を修正 修正: `PresenceCollaborator`コンポーネントの`relativeTime`を修正 修正: `relativeTime`ヘルパーで等号付き不等式を使用 修正: 不要な剰余演算を削除 修正: `ReadableTime`の`relativeTime`を修正し、スナップショットを修正 修正: `lastModifiedByCellRenderer`の`relativeTime`を修正 修正: テストを修正 修正: jsを使用 修正: インポートを修正 修正: elseステートメントを修正 修正: インポートの並べ替えを元に戻す **Source:** [https://ja.developer.box.com/changelog/2024-05-22-box-ui-elements-v2000-released](https://ja.developer.box.com/changelog/2024-05-22-box-ui-elements-v2000-released) --- ### Box UI Elements `v20.0.1-beta.1`のリリース **Type:** changelog | **Section:** Changelog Box UI Elements v20.0.1-beta.1のリリース 20.0.1-beta.1 (2024/05/31) バグ修正 avatars: アバターを取得するためのタイプを追加 (#3560) (14a194f) # Box UI Elements v20.0.1-beta.1のリリース ## 20.0.1-beta.1 (2024/05/31) ### バグ修正 - **avatars:** アバターを取得するためのタイプを追加 ([#3560](https://github.com/box/box-ui-elements/issues/3560)) ([`14a194f`](https://github.com/box/box-ui-elements/commit/14a194f)) **Source:** [https://ja.developer.box.com/changelog/2024-05-31-box-ui-elements-v2001-beta1-released](https://ja.developer.box.com/changelog/2024-05-31-box-ui-elements-v2001-beta1-released) --- ### Box UI Elements `v21.0.0`のリリース **Type:** changelog | **Section:** Changelog Box UI Elements v21.0.0のリリース 21.0.0 (2024/07/16) バグ修正 hapi/addressのパッケージ依存関係をアップグレード (#3579) (b089619) react-virtualized… # Box UI Elements v21.0.0のリリース # 21.0.0 (2024/07/16) ### バグ修正 - hapi/addressのパッケージ依存関係をアップグレード ([#3579](https://github.com/box/box-ui-elements/issues/3579)) ([`b089619`](https://github.com/box/box-ui-elements/commit/b0896194b79263ab60b47363abfbb98258244a47)) - react-virtualizedのピア依存関係をアップグレード ([#3578](https://github.com/box/box-ui-elements/issues/3578)) ([`3ebae37`](https://github.com/box/box-ui-elements/commit/3ebae376521ab8a4232005bae32e81c2b82da903)) - **avatars:** アバターを取得するためのタイプを追加 ([#3560](https://github.com/box/box-ui-elements/issues/3560)) ([`14a194f`](https://github.com/box/box-ui-elements/commit/14a194f449018932134cc5df741ecd36c774a321)) - **content-sidebar:** サイドバーアイコンのスタイルに更新 ([#3561](https://github.com/box/box-ui-elements/issues/3561)) ([`381a3b6`](https://github.com/box/box-ui-elements/commit/381a3b642b0148553c6f65cea159b0718271117a)) - **content-uploader:** 複数の項目が削除可能な問題を修正 ([#3565](https://github.com/box/box-ui-elements/issues/3565)) ([`87815de`](https://github.com/box/box-ui-elements/commit/87815de94e8fb607f24a0e17750ffbaa2e713125)) - **i18n:** 翻訳を更新 ([#3563](https://github.com/box/box-ui-elements/issues/3563)) ([`6d9c65f`](https://github.com/box/box-ui-elements/commit/6d9c65f0054d329a20a65ef814b9c0e867c9baf7)) - **i18n:** 翻訳を更新 ([#3564](https://github.com/box/box-ui-elements/issues/3564)) ([`7988af8`](https://github.com/box/box-ui-elements/commit/7988af8eb56a8e6e5abf8bb07d53f3250b148cf5)) - **i18n:** 翻訳を更新 ([#3566](https://github.com/box/box-ui-elements/issues/3566)) ([`3103983`](https://github.com/box/box-ui-elements/commit/310398302abd67bb48dbf5317dc858f054b0cc16)) - **preview:** プレビューのエラーメッセージを更新 ([#3562](https://github.com/box/box-ui-elements/issues/3562)) ([`aff6217`](https://github.com/box/box-ui-elements/commit/aff6217671d25015d314813295b871facfb8a9cc)) ### 機能 - **docgen:** docgenのアイコンを追加 ([#3573](https://github.com/box/box-ui-elements/issues/3573)) ([`f5d4955`](https://github.com/box/box-ui-elements/commit/f5d49554683c965335366ba0f7f34771cec4d4d4)) - **react:** 重大な変更: React 18にアップグレード ([#3556](https://github.com/box/box-ui-elements/issues/3556)) ([`91e0978`](https://github.com/box/box-ui-elements/commit/91e09787c545194ef61cb057e74df7dfd111728b)) - **webpack:** 重大な変更: webpack 5および`react-styleguidist` 12.0.1にアップグレード ([#3568](https://github.com/box/box-ui-elements/issues/3568)) ([`a812294`](https://github.com/box/box-ui-elements/commit/a81229420c1a133145c9899efe908a080f59bd9f)) ### 重大な変更 - 未定義のバッファ参照を解決するためにhapi/addressをアップグレード - React 18をサポートするためにreact-virtualizedのピア依存関係をアップグレード **Source:** [https://ja.developer.box.com/changelog/2024-07-16-box-ui-elements-v2100-released](https://ja.developer.box.com/changelog/2024-07-16-box-ui-elements-v2100-released) --- ### Box UI Elements `v22.0.0`のリリース **Type:** changelog | **Section:** Changelog Box UI Elements v22.0.0のリリース 22.0.0 (2024/10/21) バグ修正 esbuildの不足していたexportを解決 (#3719) (495f19e) content-answers: content-answersを昇格 (#371… # Box UI Elements v22.0.0のリリース # 22.0.0 (2024/10/21) ### バグ修正 - `esbuild`の不足していたexportを解決 ([#3719](https://github.com/box/box-ui-elements/issues/3719)) ([`495f19e`](https://github.com/box/box-ui-elements/commit/495f19e20c8e3d6b7ab9fe8b6f5c3f833d1c5c46)) - **content-answers:** content-answersを昇格 ([#3713](https://github.com/box/box-ui-elements/issues/3713)) ([`21c2de1`](https://github.com/box/box-ui-elements/commit/21c2de1b3e64ff4766c36ed18a1e720ff79ae5b6)) - **content-uploader:** `ItemAction`の問題を解決 ([#3631](https://github.com/box/box-ui-elements/issues/3631)) ([`ba299b1`](https://github.com/box/box-ui-elements/commit/ba299b1dcee18d3197e5f7df0f15823070a071cb)) - **docgen-sidebar:** ネストされたタグを非表示にするための折りたたみ可能なコンポーネントを追加 ([#3626](https://github.com/box/box-ui-elements/issues/3626)) ([`3480efb`](https://github.com/box/box-ui-elements/commit/3480efb5a03ee73f4d78a5b26f626f059aa31115)) - **draft-js:** 0.11.7にアップグレード ([#3580](https://github.com/box/box-ui-elements/issues/3580)) ([`179ff9f`](https://github.com/box/box-ui-elements/commit/179ff9f718845500ddc76a56e06129e06b386886)) - **hubs:** 共有リンクのテキストを修正 ([#3657](https://github.com/box/box-ui-elements/issues/3657)) ([`a938524`](https://github.com/box/box-ui-elements/commit/a9385240dc53a9efe5277956a2d81ec1c253716a)) - **i18n:** 翻訳を更新 ([#3603](https://github.com/box/box-ui-elements/issues/3603)) ([`a467823`](https://github.com/box/box-ui-elements/commit/a4678232af14c2220ce8c7125a55bb6714781b7a)) - **i18n:** 翻訳を更新 ([#3607](https://github.com/box/box-ui-elements/issues/3607)) ([`8ad18b8`](https://github.com/box/box-ui-elements/commit/8ad18b8b7887c07189dee590ebc0a931fa5010e8)) - **i18n:** 翻訳を更新 ([#3612](https://github.com/box/box-ui-elements/issues/3612)) ([`4bfceaa`](https://github.com/box/box-ui-elements/commit/4bfceaaf71ed4271ba62d6878ef714617a920c8c)) - **i18n:** 翻訳を更新 ([#3615](https://github.com/box/box-ui-elements/issues/3615)) ([`945fa23`](https://github.com/box/box-ui-elements/commit/945fa23a8ba08bebf3bb4415e2b1827377eecbbd)) - **i18n:** 翻訳を更新 ([#3619](https://github.com/box/box-ui-elements/issues/3619)) ([`bc011eb`](https://github.com/box/box-ui-elements/commit/bc011eb1369fc36762cfa3d7a206a538400d536d)) - **i18n:** 翻訳を更新 ([#3620](https://github.com/box/box-ui-elements/issues/3620)) ([`62a9ef7`](https://github.com/box/box-ui-elements/commit/62a9ef7489e42d3cafa8edfabcddf57928ae514d)) - **i18n:** 翻訳を更新 ([#3627](https://github.com/box/box-ui-elements/issues/3627)) ([`ae5cc3d`](https://github.com/box/box-ui-elements/commit/ae5cc3d0b0f0b2afacb37048f994b39867d9006a)) - **i18n:** 翻訳を更新 ([#3633](https://github.com/box/box-ui-elements/issues/3633)) ([`13894ca`](https://github.com/box/box-ui-elements/commit/13894caaf44775d80d54b4458a997160be359ed1)) - **i18n:** 翻訳を更新 ([#3636](https://github.com/box/box-ui-elements/issues/3636)) ([`0bee28b`](https://github.com/box/box-ui-elements/commit/0bee28b6208179a1f0d2ce2428a5200be199302f)) - **i18n:** 翻訳を更新 ([#3639](https://github.com/box/box-ui-elements/issues/3639)) ([`83b403c`](https://github.com/box/box-ui-elements/commit/83b403cecc8dcdc210b31cf84fb59461f3325c8e)) - **i18n:** 翻訳を更新 ([#3643](https://github.com/box/box-ui-elements/issues/3643)) ([`4cf5b3d`](https://github.com/box/box-ui-elements/commit/4cf5b3d55042274e8d73c8a9f1998ceed791179a)) - **i18n:** 翻訳を更新 ([#3648](https://github.com/box/box-ui-elements/issues/3648)) ([`297fabf`](https://github.com/box/box-ui-elements/commit/297fabfe2ab8207ccdcb6e97057a4fb2f3022284)) - **i18n:** 翻訳を更新 ([#3653](https://github.com/box/box-ui-elements/issues/3653)) ([`7b0e0fb`](https://github.com/box/box-ui-elements/commit/7b0e0fb44e3d205d28a10d8bc851ebaecaf5222f)) - **i18n:** 翻訳を更新 ([#3659](https://github.com/box/box-ui-elements/issues/3659)) ([`41a17fe`](https://github.com/box/box-ui-elements/commit/41a17fe815b9ab7da9403836276de3fca379e86f)) - **i18n:** 翻訳を更新 ([#3667](https://github.com/box/box-ui-elements/issues/3667)) ([`1f77bce`](https://github.com/box/box-ui-elements/commit/1f77bce4f470988d818ce7128954e1cd964d4f7f)) - **i18n:** 翻訳を更新 ([#3673](https://github.com/box/box-ui-elements/issues/3673)) ([`7e5f7c1`](https://github.com/box/box-ui-elements/commit/7e5f7c1af0a05c35097827af5a55d5edd3470872)) - **i18n:** 翻訳を更新 ([#3674](https://github.com/box/box-ui-elements/issues/3674)) ([`ebe8348`](https://github.com/box/box-ui-elements/commit/ebe8348b9cf0a79298ea102f27217b6cd10b631f)) - **i18n:** 翻訳を更新 ([#3679](https://github.com/box/box-ui-elements/issues/3679)) ([`4bf65f8`](https://github.com/box/box-ui-elements/commit/4bf65f8b1c8ed6080a340bb28097d6f04d08ecc0)) - **i18n:** 翻訳を更新 ([#3683](https://github.com/box/box-ui-elements/issues/3683)) ([`549188a`](https://github.com/box/box-ui-elements/commit/549188a9f005b8dd0f63c0ed4906e8a64144c3a4)) - **i18n:** 翻訳を更新 ([#3686](https://github.com/box/box-ui-elements/issues/3686)) ([`9927e53`](https://github.com/box/box-ui-elements/commit/9927e53f47e54380d0f2e44e857fbd6b0a6528fd)) - **i18n:** 翻訳を更新 ([#3689](https://github.com/box/box-ui-elements/issues/3689)) ([`47e7a6b`](https://github.com/box/box-ui-elements/commit/47e7a6be3036280bf89220f65ed978b3ef0bc2c7)) - **i18n:** 翻訳を更新 ([#3692](https://github.com/box/box-ui-elements/issues/3692)) ([`d2e59c8`](https://github.com/box/box-ui-elements/commit/d2e59c846c3d72ab9efbe59f1123c72745945aa7)) - **i18n:** 翻訳を更新 ([#3694](https://github.com/box/box-ui-elements/issues/3694)) ([`1850977`](https://github.com/box/box-ui-elements/commit/1850977829e4888139462a6f65794b1cffc52a08)) - **i18n:** 翻訳を更新 ([#3697](https://github.com/box/box-ui-elements/issues/3697)) ([`665aedf`](https://github.com/box/box-ui-elements/commit/665aedff1834ffbc4bc1e903262b0d4e0bef2cc3)) - **i18n:** 翻訳を更新 ([#3701](https://github.com/box/box-ui-elements/issues/3701)) ([`fe9f7cc`](https://github.com/box/box-ui-elements/commit/fe9f7cca9b100afe1521df41c697ed6f0f621f66)) - **i18n:** 翻訳を更新 ([#3705](https://github.com/box/box-ui-elements/issues/3705)) ([`fa89f87`](https://github.com/box/box-ui-elements/commit/fa89f876d54680b95bdc2fd3eb0d07a3c729f03e)) - **i18n:** 翻訳を更新 ([#3711](https://github.com/box/box-ui-elements/issues/3711)) ([`b6b61bf`](https://github.com/box/box-ui-elements/commit/b6b61bf47429541b1cbb1091fd94024c4ceeb6c8)) - **metadata-instance-editor:** サポートリンクを修正 ([#3671](https://github.com/box/box-ui-elements/issues/3671)) ([`b82687e`](https://github.com/box/box-ui-elements/commit/b82687e5cc0a55b6f82eb2c9aa1ea7b3482263b4)) - **metadata-sidebar:** 読み込み状態を修正 ([#3684](https://github.com/box/box-ui-elements/issues/3684)) ([`5c54eb5`](https://github.com/box/box-ui-elements/commit/5c54eb51287b1273ad84145952be132b84ef9e04)) - **metadata-sidebar:** メタデータサイドバーのAI機能を修正 ([#3681](https://github.com/box/box-ui-elements/issues/3681)) ([`fd164ec`](https://github.com/box/box-ui-elements/commit/fd164ec57c58ac912bdb4edbe4f9cdc30296b11a)) - **metadata-sidebar:** storybookテストを修正 ([#3695](https://github.com/box/box-ui-elements/issues/3695)) ([`8326472`](https://github.com/box/box-ui-elements/commit/83264724fa9de3e0935cc6f5762362dadcca884f)) - **metadata-sidebar:** テンプレートを編集するための`onCancel`アクションを処理 ([#3669](https://github.com/box/box-ui-elements/issues/3669)) ([`6ad083b`](https://github.com/box/box-ui-elements/commit/6ad083b4d14a721973df5ef3959913772c481922)) - **metadata-sidebar:** `UnsavedChangesModal`の変更 ([#3691](https://github.com/box/box-ui-elements/issues/3691)) ([`305d3af`](https://github.com/box/box-ui-elements/commit/305d3af23a162db91e16ce13cc8c0bced865500d)) - **notification:** 通知の下のUIのブロックを解除 ([#3661](https://github.com/box/box-ui-elements/issues/3661)) ([`33b34d9`](https://github.com/box/box-ui-elements/commit/33b34d9c532501824ed45c8965f82df690bb6e5c)) - **quick-search:** クイック検索ボタンとフッターのナビゲーション ([#3623](https://github.com/box/box-ui-elements/issues/3623)) ([`0427112`](https://github.com/box/box-ui-elements/commit/04271125b0beedaae80f3ec48273ca5fdf266ac7)) - **quick-search:** クイック検索のナビゲーション ([#3622](https://github.com/box/box-ui-elements/issues/3622)) ([`b814223`](https://github.com/box/box-ui-elements/commit/b8142235903cd8ee5d36ee9121437b01552a5597)) - eslintとconfigをクリーンアップ ([#3584](https://github.com/box/box-ui-elements/issues/3584)) ([`c0ff8d7`](https://github.com/box/box-ui-elements/commit/c0ff8d7d7b24a919fc440a8f06f74b26fb0f5fa1))、[#3583](https://github.com/box/box-ui-elements/issues/3583)をクローズ - `box/frontend`からの変更を解決 ([#3590](https://github.com/box/box-ui-elements/issues/3590)) ([`1d91171`](https://github.com/box/box-ui-elements/commit/1d9117162d658215fc9b62bbbfa0d351349901ff)) - **quick-search:** クイックフィルタのナビゲーション ([#3582](https://github.com/box/box-ui-elements/issues/3582)) ([`6880f67`](https://github.com/box/box-ui-elements/commit/6880f67d6005f549ca7c2fbc5d9c395f25cf7128)) - react-popperをアップグレード ([#3583](https://github.com/box/box-ui-elements/issues/3583)) ([`13396e4`](https://github.com/box/box-ui-elements/commit/13396e4f9f06c30b542fa5846659539f00edc392)) ### 機能 - **taxonomy:** メタデータ階層フィールドの表示/作成/更新のサポートを追加 ([#3716](https://github.com/box/box-ui-elements/issues/3716)) ([`cccb0b0`](https://github.com/box/box-ui-elements/commit/cccb0b084a52838eb9f7e16c084507ef30ba30e1)) - 「重大な変更」のblueprintピア依存関係の`noop` ([#3721](https://github.com/box/box-ui-elements/issues/3721)) ([`5a117ae`](https://github.com/box/box-ui-elements/commit/5a117ae1f4e887365b65d07dd0b8a3f00ebf45db)) - **api:** 空のメタデータの候補の処理を追加 ([#3608](https://github.com/box/box-ui-elements/issues/3608)) ([`ecd4c80`](https://github.com/box/box-ui-elements/commit/ecd4c80873ae0d447fd5dbfdcf622775eeeb206e)) - **api:** メタデータAPIの`getMetadata`を拡張 ([#3611](https://github.com/box/box-ui-elements/issues/3611)) ([`765f592`](https://github.com/box/box-ui-elements/commit/765f592647c41bb1e2bd48ea32dd7b7e1ba2f305)) - **blueprint:** blueprintを追加 ([#3585](https://github.com/box/box-ui-elements/issues/3585)) ([`0f2d876`](https://github.com/box/box-ui-elements/commit/0f2d87617838dc2af7c702c91dbc4321d7b31bf5)) - **boxai-sidebar:** `BoxAISidebar`ヘッダーを追加 ([#3698](https://github.com/box/box-ui-elements/issues/3698)) ([`130b6b6`](https://github.com/box/box-ui-elements/commit/130b6b69c45a0b8e4a22009e3e9f44fb285e45e1)) - **boxai-sidebar:** Box AI用の空のサイドバー ([#3668](https://github.com/box/box-ui-elements/issues/3668)) ([`611377c`](https://github.com/box/box-ui-elements/commit/611377ce21b3ed7a804c82eb2c29189851861dc2)) - **content-answers:** Content Answersをアップグレード ([#3658](https://github.com/box/box-ui-elements/issues/3658)) ([`002d496`](https://github.com/box/box-ui-elements/commit/002d4966fa2158c33371d9a218a41206e1462f6b))、[#3626](https://github.com/box/box-ui-elements/issues/3626)をクローズ - **content-explorer-modal-container:** 省略可能な情報通知を追加 ([#3634](https://github.com/box/box-ui-elements/issues/3634)) ([`20d4c3f`](https://github.com/box/box-ui-elements/commit/20d4c3f3ca981820bf3684afe4ee68775b4b30bd)) - **content-sidebar:** コンテンツプレビューのサイドバーにアーカイブの日付を追加 ([#3625](https://github.com/box/box-ui-elements/issues/3625)) ([`10e68f3`](https://github.com/box/box-ui-elements/commit/10e68f301183244062b6613006a5aa0cbdd33526)) - **content-sidebar:** メニュー項目にdata-target-idを追加 ([#3610](https://github.com/box/box-ui-elements/issues/3610)) ([`cf05167`](https://github.com/box/box-ui-elements/commit/cf05167884084a199512a1d18d41cc9fde7a4fc7)) - **content-sidebar:** プレースホルダ`metadatasidebar`のデザイン変更を追加 ([#3570](https://github.com/box/box-ui-elements/issues/3570)) ([`6a0d7ee`](https://github.com/box/box-ui-elements/commit/6a0d7ee0857d9c91719654e2ac387a6e7dc135b9)) - **content-sidebar:** アーカイブファイルのバージョン変更を無効化 ([#3637](https://github.com/box/box-ui-elements/issues/3637)) ([`e735c4c`](https://github.com/box/box-ui-elements/commit/e735c4c3f5b755f3a773d2e7f185cd9a961de3cd)) - **content-sidebar:** デザインが変更されたサイドバーに`metadata.aiSuggestions`フラグを渡す ([#3665](https://github.com/box/box-ui-elements/issues/3665)) ([`b672f70`](https://github.com/box/box-ui-elements/commit/b672f7059697e922d2ae193ef6a98217695c843d)) - **metadata-sidebar:** `Autofill`ボタンのハンドラを追加 ([#3700](https://github.com/box/box-ui-elements/issues/3700)) ([`95735e0`](https://github.com/box/box-ui-elements/commit/95735e0291f233d173c17a19304119c83e51723d)) - **metadata-sidebar:** メタデータインスタンスリストを追加 ([#3664](https://github.com/box/box-ui-elements/issues/3664)) ([`b4e4b01`](https://github.com/box/box-ui-elements/commit/b4e4b01fefea753d21a4aa75dccde92fce05af21))、[#3605](https://github.com/box/box-ui-elements/issues/3605)をクローズ - **metadata-sidebar:** 削除ボタンを無効化 ([#3677](https://github.com/box/box-ui-elements/issues/3677)) ([`2941a97`](https://github.com/box/box-ui-elements/commit/2941a9732b5081872bfcd0c2fe490ab14c6dc2ed)) - **metadata-sidebar:** メタデータインスタンスの作成を処理 ([#3663](https://github.com/box/box-ui-elements/issues/3663)) ([`321ba7e`](https://github.com/box/box-ui-elements/commit/321ba7e715d51b269ad7bc566b197d0cab52b699)) - **metadata-sidebar:** メタデータインスタンスの削除を処理 ([#3662](https://github.com/box/box-ui-elements/issues/3662)) ([`f6abd4e`](https://github.com/box/box-ui-elements/commit/f6abd4e07d8d23b0a0fe5224b4ba2f6b4c44f4e7)) - **metadata-sidebar:** メタデータインスタンスの更新を処理 ([#3672](https://github.com/box/box-ui-elements/issues/3672)) ([`ef79e44`](https://github.com/box/box-ui-elements/commit/ef79e44d81eb875eec04233e48485f1c6326606d)) - **metadata-sidebar:** メタデータサイドバーのデザイン変更 ([#3654](https://github.com/box/box-ui-elements/issues/3654)) ([`fe4fede`](https://github.com/box/box-ui-elements/commit/fe4fededd993c4025b1b6f38cc8a6387af1a9acc))、[#3606](https://github.com/box/box-ui-elements/issues/3606)をクローズ - **metadata-sidebar:** ファイル拡張子に基づいて`areAiSuggestionsAvailable`を渡す ([#3675](https://github.com/box/box-ui-elements/issues/3675)) ([`dc074cf`](https://github.com/box/box-ui-elements/commit/dc074cf3f189a9ce06b7854d7245242732c1a294)) - **metadata-sidebar:** タブコンテンツのスタイルの変更 ([#3708](https://github.com/box/box-ui-elements/issues/3708)) ([`f7c06a4`](https://github.com/box/box-ui-elements/commit/f7c06a4c411b453df9a1617d50fdddf77b032db7)) - **taxonomy:** メタデータオプションのエンドポイントを追加 ([#3678](https://github.com/box/box-ui-elements/issues/3678)) ([`47ba331`](https://github.com/box/box-ui-elements/commit/47ba331ca562c152c49cccf2c090664177e1370d)) - **taxonomy:** メタデータ階層フィールドのサポートを追加 ([#3710](https://github.com/box/box-ui-elements/issues/3710)) ([`3a0c27e`](https://github.com/box/box-ui-elements/commit/3a0c27ea1cfbb22c6fd9090f7bd237e62f8536b6)) - **uaa-logging:** UAAパリティデータをログに記録 ([#3629](https://github.com/box/box-ui-elements/issues/3629)) ([`6cb5d8f`](https://github.com/box/box-ui-elements/commit/6cb5d8f1d972b40ec06ce08f39cb25aa1452ad10)) - **unified-share-modal:** カスタムアバターのクリックハンドラを追加 ([#3688](https://github.com/box/box-ui-elements/issues/3688)) ([`c034de4`](https://github.com/box/box-ui-elements/commit/c034de4daec6881c08b05caa1033db91382af6e0)) - **update_app_activity_item:** 権限フィールドを追加 ([#3680](https://github.com/box/box-ui-elements/issues/3680)) ([`c521c11`](https://github.com/box/box-ui-elements/commit/c521c113dafdc5787f7c4c163d3cbaa01a523c3b)) - `/2.0/ai/extract_structured`エンドポイントをサポート ([#3596](https://github.com/box/box-ui-elements/issues/3596)) ([`dee4eee`](https://github.com/box/box-ui-elements/commit/dee4eee4ff49d7e8e9bc69071ac23164ae180e4e)) - **unified-share-modal:** ターゲットとなる属性を追加 ([#3592](https://github.com/box/box-ui-elements/issues/3592)) ([`e26f1f1`](https://github.com/box/box-ui-elements/commit/e26f1f10731769ad7ed3cc94bdf6ab97117719d7)) - Metadata Suggestions APIをサポート ([#3571](https://github.com/box/box-ui-elements/issues/3571)) ([`c985402`](https://github.com/box/box-ui-elements/commit/c9854024dec37927cfabdef37c4f8fe82ffb8d34))、[#3565](https://github.com/box/box-ui-elements/issues/3565)をクローズ ### パフォーマンスの向上 - **content-answers:** プレビューでContent Answersを遅延読み込み ([#3720](https://github.com/box/box-ui-elements/issues/3720)) ([`ec115f7`](https://github.com/box/box-ui-elements/commit/ec115f749fea1c545663888c8d2cfc0bd3cfa514)) ### 取り消し - **content-explorer:** 名前変更ダイアログを元に戻す ([#3704](https://github.com/box/box-ui-elements/issues/3704)) ([`13b8c99`](https://github.com/box/box-ui-elements/commit/13b8c990bc5fb8528e3a79864f8f9579608febd1))、[#3666](https://github.com/box/box-ui-elements/issues/3666)をクローズ ### 重大な変更 - blueprint-webおよびblueprint-web-assetsピア依存関係 **Source:** [https://ja.developer.box.com/changelog/2024-10-21-box-ui-elements-v2200-released](https://ja.developer.box.com/changelog/2024-10-21-box-ui-elements-v2200-released) --- ### Box UI ElementsでのReact 18のサポート **Type:** changelog | **Section:** Changelog Box UI ElementsでのReact 18のサポート Box UI ElementsでReact 18がサポートされるようになりました。これにより、サードパーティ製アプリでのコンテンツコラボレーションで新たな段階の柔軟性と機能性が実現します。この更新により、React 18の最先端の機能を活用し、最新のフロントエンドスタックでイノベーションを推進すると同時に、インテリジェントなコンテンツクラウドとのシームレスな統合が可能になります。 # Box UI ElementsでのReact 18のサポート [Box UI Elements](g://embed/ui-elements)でReact 18がサポートされるようになりました。これにより、サードパーティ製アプリでのコンテンツコラボレーションで新たな段階の柔軟性と機能性が実現します。この更新により、React 18の最先端の機能を活用し、最新のフロントエンドスタックでイノベーションを推進すると同時に、インテリジェントなコンテンツクラウドとのシームレスな統合が可能になります。 詳細については、Boxの[ブログ記事](https://medium.com/box-developer-blog/seamless-integration-box-ui-elements-and-react-18-compatibility-4db97a09ff01)を参照してください。 ## サポート情報 問題がある場合やさらにガイドが必要な場合は、必要なサポートについて、Boxの[Developer Forum](https://medium.com/box-developer-blog/seamless-integration-box-ui-elements-and-react-18-compatibility-4db97a09ff01)に英語でリクエストを投稿してください。 **Source:** [https://ja.developer.box.com/changelog/2024-07-16-react-18-buie](https://ja.developer.box.com/changelog/2024-07-16-react-18-buie) --- ### Box Windows SDK `v3.24.0`のリリース **Type:** changelog | **Section:** Changelog Box Windows SDK v3.24.0のリリース 詳細については、変更ログを参照してください。 コミット: https://github.com/box/box-windows-sdk-v2/compare/v3.23.0...v3.24.0 nuget.org… # Box Windows SDK v3.24.0のリリース 詳細については、[変更ログ](https://github.com/box/box-windows-sdk-v2/blob/master/CHANGELOG.md#3240-2020-07-21)を参照してください。 コミット: [https://github.com/box/box-windows-sdk-v2/compare/v3.23.0...v3.24.0](https://github.com/box/box-windows-sdk-v2/compare/v3.23.0...v3.24.0) [`nuget.org/packages/Box.V2/3.24.0`](https://www.nuget.org/packages/Box.V2/3.24.0) [`nuget.org/packages/Box.V2.Core/3.24.0`](https://www.nuget.org/packages/Box.V2.Core/3.24.0) **Source:** [https://ja.developer.box.com/changelog/2020-07-21-box-windows-sdk-v3240-released](https://ja.developer.box.com/changelog/2020-07-21-box-windows-sdk-v3240-released) --- ### Box Windows SDK `v3.25.0`のリリース **Type:** changelog | **Section:** Changelog Box Windows SDK v3.25.0のリリース 3.25.0 [2020年10月19日][2020-10-19] 新機能と機能強化: グループ取得時のフィルタのサポートを追加 (#703) 圧縮機能を追加 (#70… # Box Windows SDK v3.25.0のリリース ## 3.25.0 [2020年10月19日][2020-10-19] **新機能と機能強化:** - グループ取得時のフィルタのサポートを追加 ([#703](https://github.com/box/box-windows-sdk-v2/issues/703)) - 圧縮機能を追加 ([#700](https://github.com/box/box-windows-sdk-v2/issues/700)) - オーバーロードされた`ExecuteMetadataQueryAsync()`メソッドの1つを廃止 ([#699](https://github.com/box/box-windows-sdk-v2/issues/699)) - メタデータテンプレートの`copyInstanceOnItemCopy`フィールドのサポートを追加 ([#698](https://github.com/box/box-windows-sdk-v2/issues/698)) **バグ修正:** - JWT認証の自動再試行に関するバグを修正 ([#697](https://github.com/box/box-windows-sdk-v2/issues/697)) [`www.nuget.org/packages/Box.V2/3.25.0`](https://www.nuget.org/packages/Box.V2/3.25.0) [`www.nuget.org/packages/Box.V2.Core/3.25.0`](https://www.nuget.org/packages/Box.V2.Core/3.25.0) **Source:** [https://ja.developer.box.com/changelog/2020-10-19-box-windows-sdk-v3250-released](https://ja.developer.box.com/changelog/2020-10-19-box-windows-sdk-v3250-released) --- ### Box Windows SDK `v4.0.0`のリリース **Type:** changelog | **Section:** Changelog Box Windows SDK v4.0.0のリリース 重要な変更: BoxClientおよびマネージャのインターフェースを抽出し、テスタビリティを改善 (#603) BoxConfigBuilderを追加し、BoxConfigを変更不可に設定 (#73… # Box Windows SDK v4.0.0のリリース **重要な変更:** - BoxClientおよびマネージャのインターフェースを抽出し、テスタビリティを改善 ([#603](https://github.com/box/box-windows-sdk-v2/pull/603)) - BoxConfigBuilderを追加し、BoxConfigを変更不可に設定 ([#737](https://github.com/box/box-windows-sdk-v2/pull/737)) - 非同期メソッドからタスクを公開 ([#742](https://github.com/box/box-windows-sdk-v2/pull/742)) - DateTimeの代わりにDateTimeOffsetを使用 ([#749](https://github.com/box/box-windows-sdk-v2/pull/749)) - 返された例外を修正 ([#753](https://github.com/box/box-windows-sdk-v2/pull/753)) - .NET Standardを2.0にアップグレード ([#755](https://github.com/box/box-windows-sdk-v2/pull/755)) **新機能と機能強化:** - 割り当てのリテンションの対象となるファイルおよびファイルバージョンを取得する機能を追加 ([#734](https://github.com/box/box-windows-sdk-v2/pull/734)) - `Folder`の更新のために`is_collaboration_restricted_to_enterprise`フラグのサポートを追加 ([#732](https://github.com/box/box-windows-sdk-v2/pull/732)) - 不適切な用語の変更 ([#738](https://github.com/box/box-windows-sdk-v2/pull/738)) - サービス利用規約のユーザーステータスの作成用に使いやすくなった新しいメソッドを追加 ([#740](https://github.com/box/box-windows-sdk-v2/pull/740)) - ごみ箱内の項目を取得する際に並べ替えと方向のパラメータを渡すことを許可 ([#754](https://github.com/box/box-windows-sdk-v2/pull/754)) - タスクのcompletion_ruleフィールドのサポートを追加 ([#758](https://github.com/box/box-windows-sdk-v2/pull/758)) - BoxSign APIのサポートを追加 ([#765](https://github.com/box/box-windows-sdk-v2/pull/765)) **バグ修正:** - アップロード時の`Cannot access a closed Stream.Request`例外を修正 ([#739](https://github.com/box/box-windows-sdk-v2/pull/739)) ([#757](https://github.com/box/box-windows-sdk-v2/pull/757)) [https://www.nuget.org/packages/Box.V2/4.0.0](https://www.nuget.org/packages/Box.V2/4.0.0) [https://www.nuget.org/packages/Box.V2.Core/4.0.0](https://www.nuget.org/packages/Box.V2.Core/4.0.0) **Source:** [https://ja.developer.box.com/changelog/2021-11-02-box-windows-sdk-v400-released](https://ja.developer.box.com/changelog/2021-11-02-box-windows-sdk-v400-released) --- ### Box Windows SDK `v4.1.0`のリリース **Type:** changelog | **Section:** Changelog Box Windows SDK v4.1.0のリリース バグ修正: デッドロックの防止を待機中に欠落しているconfigureAwait(false) を追加 (#775) (b16267e) 新機能と機能強化: BoxClient用に設定可能なTimeoutを追加 (#77… # Box Windows SDK v4.1.0のリリース **バグ修正:** - デッドロックの防止を待機中に欠落している`configureAwait`(false) を追加 ([#775](https://github.com/box/box-windows-sdk-v2/issues/775)) ([`b16267e`](https://github.com/box/box-windows-sdk-v2/commit/b16267e8f3dca5396e87be660e30a1e9405d8139)) **新機能と機能強化:** - `BoxClient`用に設定可能な`Timeout`を追加 ([#779](https://github.com/box/box-windows-sdk-v2/issues/779)) ([`ac842ed`](https://github.com/box/box-windows-sdk-v2/commit/ac842ed4ba1a2dfe499706524441bc6ae3b3c192)) - ファイルリクエストAPIを追加 ([#777](https://github.com/box/box-windows-sdk-v2/issues/777)) ([`1098f75`](https://github.com/box/box-windows-sdk-v2/commit/1098f75983e2d784521f13b8d53df0e55d03203b)) - `vanity_name`を`SharedLink`に追加 ([#782](https://github.com/box/box-windows-sdk-v2/issues/782)) ([`00a1e26`](https://github.com/box/box-windows-sdk-v2/commit/00a1e265569d76c2c9593aa259202d7febef629c)) [https://www.nuget.org/packages/Box.V2/4.1.0](https://www.nuget.org/packages/Box.V2/4.1.0) [https://www.nuget.org/packages/Box.V2.Core/4.1.0](https://www.nuget.org/packages/Box.V2.Core/4.1.0) **Source:** [https://ja.developer.box.com/changelog/2021-12-14-box-windows-sdk-v410-released](https://ja.developer.box.com/changelog/2021-12-14-box-windows-sdk-v410-released) --- ### Box Windows SDK `v4.2.0`のリリース **Type:** changelog | **Section:** Changelog Box Windows SDK v4.2.0のリリース バグ修正: 企業からユーザーをロールアウトしたときに正しくnullを渡す (#792) (c85c573) BoxAuthenticationFailedExceptionの作成により例外がスローされなくなる (#79… # Box Windows SDK v4.2.0のリリース **バグ修正:** - 企業からユーザーをロールアウトしたときに正しくnullを渡す ([#792](https://github.com/box/box-windows-sdk-v2/issues/792)) ([`c85c573`](https://github.com/box/box-windows-sdk-v2/commit/c85c5735865b7dd97ffa1428a8f57d2edff6811b)) - `BoxAuthenticationFailedException`の作成により例外がスローされなくなる ([#790](https://github.com/box/box-windows-sdk-v2/issues/790)) ([`55a706e`](https://github.com/box/box-windows-sdk-v2/commit/55a706e4091271aa55208a260b2f4f96e1527698)) - `AutoPaginate`のnull引数の例外 ([#666](https://github.com/box/box-windows-sdk-v2/issues/666)) ([`c61f08c`](https://github.com/box/box-windows-sdk-v2/commit/c61f08cc02d5c95ff71ef700e97393a0dc3dc890)) **新機能と機能強化:** - `admin_logs_streaming`のサポートを追加 ([#797](https://github.com/box/box-windows-sdk-v2/issues/797)) ([`a775e1e`](https://github.com/box/box-windows-sdk-v2/commit/a775e1e5c7696a1e5f82b5dc7edbed8eb09f640d)) - クライアント資格情報許可の`auth`のサポートを追加 ([#799](https://github.com/box/box-windows-sdk-v2/issues/799)) ([`b8a64ca`](https://github.com/box/box-windows-sdk-v2/commit/b8a64ca3887298feccef5185f6bfec4c3771b5a9)) - `disposition_at`フィールドをファイルオブジェクトに追加 ([#793](https://github.com/box/box-windows-sdk-v2/issues/793)) ([`2766a91`](https://github.com/box/box-windows-sdk-v2/commit/2766a914fad1eb40371cd4430b3450360088b331)) - `BoxConfig`で`auth`トークンの`uri`を設定する可能性を追加 ([#794](https://github.com/box/box-windows-sdk-v2/issues/794)) ([`ae8cd8b`](https://github.com/box/box-windows-sdk-v2/commit/ae8cd8b91dd91b8a786e53ff5b3501d2700686a4)) - `ExecuteMetadataQuery`の`index_name`を廃止 ([#800](https://github.com/box/box-windows-sdk-v2/issues/800)) ([`6a6a0e4`](https://github.com/box/box-windows-sdk-v2/commit/6a6a0e4a0e41ec70ec33acacba00bee6c7ee881f)) [https://www.nuget.org/packages/Box.V2/4.2.0](https://www.nuget.org/packages/Box.V2/4.2.0) [https://www.nuget.org/packages/Box.V2.Core/4.2.0](https://www.nuget.org/packages/Box.V2.Core/4.2.0) **Source:** [https://ja.developer.box.com/changelog/2022-02-10-box-windows-sdk-v420-released](https://ja.developer.box.com/changelog/2022-02-10-box-windows-sdk-v420-released) --- ### Box Windows SDK `v4.3.0`のリリース **Type:** changelog | **Section:** Changelog Box Windows SDK v4.3.0のリリース 新機能と機能強化: Coreプロジェクト向けにSourceLinkのサポートを追加 (#795) (a9cbede) バグ修正: 複数の場所で文字列解析に不足している列挙型を追加 (#813) (e37028… # Box Windows SDK v4.3.0のリリース **新機能と機能強化:** - Coreプロジェクト向けに`SourceLink`のサポートを追加 ([#795](https://github.com/box/box-windows-sdk-v2/issues/795)) ([`a9cbede`](https://github.com/box/box-windows-sdk-v2/commit/a9cbedece2ffb4f832be880bebf35b715c9cb28b)) **バグ修正:** - 複数の場所で文字列解析に不足している列挙型を追加 ([#813](https://github.com/box/box-windows-sdk-v2/issues/813)) ([`e370282`](https://github.com/box/box-windows-sdk-v2/commit/e3702826216132dfe1fb061af95a8d9700f114d4)) - セッションを使用して新しいファイルバージョンをアップロードする場合に適切にレスポンスをキャスト ([#810](https://github.com/box/box-windows-sdk-v2/issues/810)) ([`73d877f`](https://github.com/box/box-windows-sdk-v2/commit/73d877ff679b5999ea50cdfa68f14b0e2169ea65)) [https://www.nuget.org/packages/Box.V2/4.3.0](https://www.nuget.org/packages/Box.V2/4.3.0) [https://www.nuget.org/packages/Box.V2.Core/4.3.0](https://www.nuget.org/packages/Box.V2.Core/4.3.0) **Source:** [https://ja.developer.box.com/changelog/2022-04-01-box-windows-sdk-v430-released](https://ja.developer.box.com/changelog/2022-04-01-box-windows-sdk-v430-released) --- ### Box Windows SDK `v4.3.1`のリリース **Type:** changelog | **Section:** Changelog Box Windows SDK v4.3.1のリリース バグ修正: ベースurlsの使用を簡素化 (#815) (f8e7344) https://www.nuget.org/packages/Box.V2/4.3.1 https://www.nuget.org/packages… # Box Windows SDK v4.3.1のリリース **バグ修正:** - ベース`urls`の使用を簡素化 ([#815](https://github.com/box/box-windows-sdk-v2/issues/815)) ([`f8e7344`](https://github.com/box/box-windows-sdk-v2/commit/f8e73447afa5c0a893c3c4ace922fc360a376f66)) [https://www.nuget.org/packages/Box.V2/4.3.1](https://www.nuget.org/packages/Box.V2/4.3.1) [https://www.nuget.org/packages/Box.V2.Core/4.3.1](https://www.nuget.org/packages/Box.V2.Core/4.3.1) **Source:** [https://ja.developer.box.com/changelog/2022-04-19-box-windows-sdk-v431-released](https://ja.developer.box.com/changelog/2022-04-19-box-windows-sdk-v431-released) --- ### Box Windows SDK `v4.4.0`のリリース **Type:** changelog | **Section:** Changelog Box Windows SDK v4.4.0のリリース 新機能と機能強化: SharedLinkにcan_editフィードを追加 (#831) (e0d4197) version_numberをBoxFileVersionに追加 (#820) (f174358) アバターAPI… # Box Windows SDK v4.4.0のリリース **新機能と機能強化:** - `SharedLink`に`can_edit`フィードを追加 ([#831](https://github.com/box/box-windows-sdk-v2/issues/831)) ([`e0d4197`](https://github.com/box/box-windows-sdk-v2/commit/e0d4197070db0dbd947f4a51a6bbb1e01c0b0cdf)) - `version_number`を`BoxFileVersion`に追加 ([#820](https://github.com/box/box-windows-sdk-v2/issues/820)) ([`f174358`](https://github.com/box/box-windows-sdk-v2/commit/f174358973caefc9262df480208341fd8233dc7f)) - アバターAPIにアップロードと削除のサポートを追加 ([#829](https://github.com/box/box-windows-sdk-v2/issues/829)) ([`4dcb84a`](https://github.com/box/box-windows-sdk-v2/commit/4dcb84ade78d6bd0bc621ff2ed7f5f886486858a)) **バグ修正:** - `BoxAPIException`オブジェクトの初期化を修正 ([#828](https://github.com/box/box-windows-sdk-v2/issues/828)) ([`a298f01`](https://github.com/box/box-windows-sdk-v2/commit/a298f01187f84200825ec6ed4748fe8bbd717d11)) - 例外のレスポンスを適切に破棄 ([#819](https://github.com/box/box-windows-sdk-v2/issues/819)) ([`8415bd3`](https://github.com/box/box-windows-sdk-v2/commit/8415bd3dbe42910b99f99535247a26f8d8e645c1)) [https://www.nuget.org/packages/Box.V2/4.4.0](https://www.nuget.org/packages/Box.V2/4.4.0) [https://www.nuget.org/packages/Box.V2.Core/4.4.0](https://www.nuget.org/packages/Box.V2.Core/4.4.0) **Source:** [https://ja.developer.box.com/changelog/2022-06-14-box-windows-sdk-v440-released](https://ja.developer.box.com/changelog/2022-06-14-box-windows-sdk-v440-released) --- ### Box Windows SDK `v4.5.0`のリリース **Type:** changelog | **Section:** Changelog Box Windows SDK v4.5.0のリリース 新機能と機能強化: 署名リクエストにcontent-typeフィールドを追加 (#850) (054d3e1) BoxSharedLinkでeffective_accessを開示 #843 (d84ddd… # Box Windows SDK v4.5.0のリリース **新機能と機能強化:** - 署名リクエストに`content-type`フィールドを追加 ([#850](https://github.com/box/box-windows-sdk-v2/issues/850)) ([`054d3e1`](https://github.com/box/box-windows-sdk-v2/commit/054d3e1a5f44b6a4a0292e8f9444266b2de0fff0)) - `BoxSharedLink`で`effective_access`を開示 [#843](https://github.com/box/box-windows-sdk-v2/issues/843) ([`d84ddd4`](https://github.com/box/box-windows-sdk-v2/commit/d84ddd48aac489ecdd1d9dc740a7672cb064b0ca)) **バグ修正:** - アセンブリから`runtime`バージョンを取得できない場合のnull参照の例外を修正 ([#851](https://github.com/box/box-windows-sdk-v2/issues/851)) ([`77046fb`](https://github.com/box/box-windows-sdk-v2/commit/77046fb0c1ce80b6e7e2dc30058ed275e46e990c)) - ファイルレプリゼンテーションで無限再試行を指数バックオフ戦略に置換 ([#835](https://github.com/box/box-windows-sdk-v2/issues/835)) ([`f2a5713`](https://github.com/box/box-windows-sdk-v2/commit/f2a57136078de8b1fc59ec2c4a9e98c062d9d19b)) [https://www.nuget.org/packages/Box.V2/4.5.0](https://www.nuget.org/packages/Box.V2/4.5.0) [https://www.nuget.org/packages/Box.V2.Core/4.5.0](https://www.nuget.org/packages/Box.V2.Core/4.5.0) **Source:** [https://ja.developer.box.com/changelog/2022-08-24-box-windows-sdk-v450-released](https://ja.developer.box.com/changelog/2022-08-24-box-windows-sdk-v450-released) --- ### Box Windows SDK `v4.6.0`のリリース **Type:** changelog | **Section:** Changelog Box Windows SDK v4.6.0のリリース 新機能と機能強化: 署名リクエストにredirect_urlとdeclined_redirect_urlを追加 (#853) (5ef2f1… # Box Windows SDK v4.6.0のリリース **新機能と機能強化:** - 署名リクエストに`redirect_url`と`declined_redirect_url`を追加 ([#853](https://github.com/box/box-windows-sdk-v2/issues/853)) ([`5ef2f18`](https://github.com/box/box-windows-sdk-v2/commit/5ef2f18985d8c3b8e7c0cdba5709785bfb1d5f34)) - 変更可能リテンションポリシーのサポートを追加し、リテンションポリシー割り当ての削除を有効化 ([#856](https://github.com/box/box-windows-sdk-v2/issues/856)) ([`564904f`](https://github.com/box/box-windows-sdk-v2/commit/564904fa2ce0b1881a2f07b80cc3bb3e648310d0)) [https://www.nuget.org/packages/Box.V2/4.6.0](https://www.nuget.org/packages/Box.V2/4.6.0) [https://www.nuget.org/packages/Box.V2.Core/4.6.0](https://www.nuget.org/packages/Box.V2.Core/4.6.0) **Source:** [https://ja.developer.box.com/changelog/2022-10-18-box-windows-sdk-v460-released](https://ja.developer.box.com/changelog/2022-10-18-box-windows-sdk-v460-released) --- ### Box Windows SDK `v5.0.0`のリリース **Type:** changelog | **Section:** Changelog Box Windows SDK v5.0.0のリリース ⚠ 重大な変更 .NET Frameworkを4.6.2にアップグレード (#881) 非推奨となったメソッドを削除 (#881) use_indexリファレンスを削除 (#88… # Box Windows SDK v5.0.0のリリース ⚠ 重大な変更 - .NET Frameworkを4.6.2にアップグレード ([#881](https://github.com/box/box-windows-sdk-v2/issues/881)) - 非推奨となったメソッドを削除 ([#881](https://github.com/box/box-windows-sdk-v2/issues/881)) - `use_index`リファレンスを削除 ([#881](https://github.com/box/box-windows-sdk-v2/issues/881)) - `GetFileVersionsUnderRetentionForAssignmentAsync`から適切なオブジェクトが戻されるよう修正 ([#881](https://github.com/box/box-windows-sdk-v2/issues/881)) **新機能と機能強化:** - .NET Frameworkを4.6.2にアップグレード ([#881](https://github.com/box/box-windows-sdk-v2/issues/881)) ([`f1989aa`](https://github.com/box/box-windows-sdk-v2/commit/f1989aa94cd085ad4bec04b4ebedb04f40455569))、[#863](https://github.com/box/box-windows-sdk-v2/issues/863)をクローズ - 非推奨となったメソッドを削除 ([#881](https://github.com/box/box-windows-sdk-v2/issues/881)) ([`f1989aa`](https://github.com/box/box-windows-sdk-v2/commit/f1989aa94cd085ad4bec04b4ebedb04f40455569))、[#874](https://github.com/box/box-windows-sdk-v2/issues/874)をクローズ - `use_index`リファレンスを削除 ([#881](https://github.com/box/box-windows-sdk-v2/issues/881)) ([`f1989aa`](https://github.com/box/box-windows-sdk-v2/commit/f1989aa94cd085ad4bec04b4ebedb04f40455569))、[#870](https://github.com/box/box-windows-sdk-v2/issues/870)をクローズ **バグ修正:** - `IBoxFilesManager#ViewVersionsAsync`にページ割りオプションを追加 ([#869](https://github.com/box/box-windows-sdk-v2/issues/869)) ([`2324495`](https://github.com/box/box-windows-sdk-v2/commit/232449531440227a0c8b3489ceda813fe4f4a73f))、[#866](https://github.com/box/box-windows-sdk-v2/issues/866)をクローズ - `GetFileVersionsUnderRetentionForAssignmentAsync`から適切なオブジェクトが戻されるよう修正 ([#881](https://github.com/box/box-windows-sdk-v2/issues/881)) ([`f1989aa`](https://github.com/box/box-windows-sdk-v2/commit/f1989aa94cd085ad4bec04b4ebedb04f40455569))、[#875](https://github.com/box/box-windows-sdk-v2/issues/875)をクローズ [https://www.nuget.org/packages/Box.V2/5.0.0](https://www.nuget.org/packages/Box.V2/5.0.0) [https://www.nuget.org/packages/Box.V2.Core/5.0.0](https://www.nuget.org/packages/Box.V2.Core/5.0.0) **Source:** [https://ja.developer.box.com/changelog/2023-01-12-box-windows-sdk-v500-released](https://ja.developer.box.com/changelog/2023-01-12-box-windows-sdk-v500-released) --- ### Box Windows SDK `v5.1.0`のリリース **Type:** changelog | **Section:** Changelog Box Windows SDK v5.1.0のリリース 新機能と機能強化: BoxCCGAuthにユーザークライアントと管理者クライアントのイニシャルトークンを使用しないFactory Methodを追加 (#883) (c1337fc) https://www.nuget… # Box Windows SDK v5.1.0のリリース **新機能と機能強化:** - `BoxCCGAuth`にユーザークライアントと管理者クライアントのイニシャルトークンを使用しないFactory Methodを追加 ([#883](https://github.com/box/box-windows-sdk-v2/issues/883)) ([`c1337fc`](https://github.com/box/box-windows-sdk-v2/commit/c1337fc9d765bf7d4bc1757ea832bec92a602f76)) [https://www.nuget.org/packages/Box.V2/5.1.0](https://www.nuget.org/packages/Box.V2/5.1.0) [https://www.nuget.org/packages/Box.V2.Core/5.1.0](https://www.nuget.org/packages/Box.V2.Core/5.1.0) **Source:** [https://ja.developer.box.com/changelog/2023-01-17-box-windows-sdk-v510-released](https://ja.developer.box.com/changelog/2023-01-17-box-windows-sdk-v510-released) --- ### Box Windows SDK `v5.2.0`のリリース **Type:** changelog | **Section:** Changelog Box Windows SDK v5.2.0のリリース 新機能と機能強化: IdをMetadataTemplateFieldに追加 (#890) (b7fe214) start_date_fieldとdescriptionをリテンションポリシーに追加 (#888) (100b… # Box Windows SDK v5.2.0のリリース **新機能と機能強化:** - `Id`を`MetadataTemplateField`に追加 ([#890](https://github.com/box/box-windows-sdk-v2/issues/890)) ([`b7fe214`](https://github.com/box/box-windows-sdk-v2/commit/b7fe2149e1a0ade8573b497b7bb36e9f3c4f4a82)) - `start_date_field`と`description`をリテンションポリシーに追加 ([#888](https://github.com/box/box-windows-sdk-v2/issues/888)) ([`100b722`](https://github.com/box/box-windows-sdk-v2/commit/100b722ce4909395c00b527677564f37a61ec2cb)) - 設定可能な`JWTAudience`クレームを追加 ([#897](https://github.com/box/box-windows-sdk-v2/issues/897)) ([`50219fd`](https://github.com/box/box-windows-sdk-v2/commit/50219fdfd553d6335b6f0b4341719b09680c4ba0)) - `GetFolderItemsAsync`に共有リンクのサポートを追加 ([#892](https://github.com/box/box-windows-sdk-v2/issues/892)) ([`0eba85c`](https://github.com/box/box-windows-sdk-v2/commit/0eba85c693763472c51fe81cbc43222305e9eefb)) **バグ修正:** - `JWT`クレームで`aud`フィールドの固定値を使用 ([#896](https://github.com/box/box-windows-sdk-v2/issues/896)) ([`8c9982d`](https://github.com/box/box-windows-sdk-v2/commit/8c9982d160ec4806c796ee2621b1811232ea59c1)) [https://www.nuget.org/packages/Box.V2/5.2.0](https://www.nuget.org/packages/Box.V2/5.2.0) [https://www.nuget.org/packages/Box.V2.Core/5.2.0](https://www.nuget.org/packages/Box.V2.Core/5.2.0) **Source:** [https://ja.developer.box.com/changelog/2023-03-14-box-windows-sdk-v520-released](https://ja.developer.box.com/changelog/2023-03-14-box-windows-sdk-v520-released) --- ### Box Windows SDK `v5.2.1`のリリース **Type:** changelog | **Section:** Changelog Box Windows SDK v5.2.1のリリース バグ修正: ユーザーエージェントヘッダーを取得する際にすべての例外をキャッチ (#901) (75d8874) https://www.nuget.org/packages/Box.V2/5.2.1 https://www… # Box Windows SDK v5.2.1のリリース **バグ修正:** - ユーザーエージェントヘッダーを取得する際にすべての例外をキャッチ ([#901](https://github.com/box/box-windows-sdk-v2/issues/901)) ([`75d8874`](https://github.com/box/box-windows-sdk-v2/commit/75d887470698a5f312610cebd58be58aee7eaa9b)) [https://www.nuget.org/packages/Box.V2/5.2.1](https://www.nuget.org/packages/Box.V2/5.2.1) [https://www.nuget.org/packages/Box.V2.Core/5.2.1](https://www.nuget.org/packages/Box.V2.Core/5.2.1) **Source:** [https://ja.developer.box.com/changelog/2023-04-18-box-windows-sdk-v521-released](https://ja.developer.box.com/changelog/2023-04-18-box-windows-sdk-v521-released) --- ### Box Windows SDK `v5.2.2`のリリース **Type:** changelog | **Section:** Changelog Box Windows SDK v5.2.2のリリース バグ修正: .NET Coreバージョンを確認できない場合の例外をキャッチ (#906) (e3be209) https://www.nuget.org/packages/Box.V2/5.2.2 https://www… # Box Windows SDK v5.2.2のリリース **バグ修正:** - .NET Coreバージョンを確認できない場合の例外をキャッチ ([#906](https://github.com/box/box-windows-sdk-v2/issues/906)) ([`e3be209`](https://github.com/box/box-windows-sdk-v2/commit/e3be209b20a5c323f547d7634663883613959180)) [https://www.nuget.org/packages/Box.V2/5.2.2](https://www.nuget.org/packages/Box.V2/5.2.2) [https://www.nuget.org/packages/Box.V2.Core/5.2.2](https://www.nuget.org/packages/Box.V2.Core/5.2.2) **Source:** [https://ja.developer.box.com/changelog/2023-05-23-box-windows-sdk-v522-released](https://ja.developer.box.com/changelog/2023-05-23-box-windows-sdk-v522-released) --- ### Box Windows SDK `v5.3.0`のリリース **Type:** changelog | **Section:** Changelog Box Windows SDK v5.3.0のリリース 新機能と機能強化: attachmentコンテンツタイプをSignRequestSignerに追加 (#913) (ad612ff) バグ修正: 非推奨のBouncyCastleライブラリを置き換え (#909) (f00f… # Box Windows SDK v5.3.0のリリース **新機能と機能強化:** - `attachment`コンテンツタイプを`SignRequestSigner`に追加 ([#913](https://github.com/box/box-windows-sdk-v2/issues/913)) ([`ad612ff`](https://github.com/box/box-windows-sdk-v2/commit/ad612ffc7821a9ecbc180e3dbeefe16d3e397820)) **バグ修正:** - 非推奨の`BouncyCastle`ライブラリを置き換え ([#909](https://github.com/box/box-windows-sdk-v2/issues/909)) ([`f00f2af`](https://github.com/box/box-windows-sdk-v2/commit/f00f2af9c5277b42e6a62060c1b0229ecff0203e)) [https://www.nuget.org/packages/Box.V2/5.3.0](https://www.nuget.org/packages/Box.V2/5.3.0) [https://www.nuget.org/packages/Box.V2.Core/5.3.0](https://www.nuget.org/packages/Box.V2.Core/5.3.0) **Source:** [https://ja.developer.box.com/changelog/2023-09-04-box-windows-sdk-v530-released](https://ja.developer.box.com/changelog/2023-09-04-box-windows-sdk-v530-released) --- ### Box Windows SDK `v5.4.0`のリリース **Type:** changelog | **Section:** Changelog Box Windows SDK v5.4.0のリリース 新機能と機能強化: Signテンプレートと新しい署名リクエストのステータスをサポート (#920) (78580fb) https://www.nuget.org/packages/Box.V2/5.4.0 https… # Box Windows SDK v5.4.0のリリース **新機能と機能強化:** - Signテンプレートと新しい署名リクエストのステータスをサポート ([#920](https://github.com/box/box-windows-sdk-v2/issues/920)) ([`78580fb`](https://github.com/box/box-windows-sdk-v2/commit/78580fbd3de553273970376b96bc28c7c5614a97)) [https://www.nuget.org/packages/Box.V2/5.4.0](https://www.nuget.org/packages/Box.V2/5.4.0) [https://www.nuget.org/packages/Box.V2.Core/5.4.0](https://www.nuget.org/packages/Box.V2.Core/5.4.0) **Source:** [https://ja.developer.box.com/changelog/2023-09-07-box-windows-sdk-v540-released](https://ja.developer.box.com/changelog/2023-09-07-box-windows-sdk-v540-released) --- ### Box Windows SDK `v5.6.0`のリリース **Type:** changelog | **Section:** Changelog Box Windows SDK v5.6.0のリリース 新機能と機能強化: 署名リクエストでiframeable_embed_urlをサポート (#925) (e9de994) https://www.nuget.org/packages/Box.V2/5.6.0 https… # Box Windows SDK v5.6.0のリリース **新機能と機能強化:** - 署名リクエストで`iframeable_embed_url`をサポート ([#925](https://github.com/box/box-windows-sdk-v2/issues/925)) ([`e9de994`](https://github.com/box/box-windows-sdk-v2/commit/e9de994cea97afcc1c3bc52ddf1cc023b9ee731c)) [https://www.nuget.org/packages/Box.V2/5.6.0](https://www.nuget.org/packages/Box.V2/5.6.0) [https://www.nuget.org/packages/Box.V2.Core/5.6.0](https://www.nuget.org/packages/Box.V2.Core/5.6.0) **Source:** [https://ja.developer.box.com/changelog/2023-09-25-box-windows-sdk-v560-released](https://ja.developer.box.com/changelog/2023-09-25-box-windows-sdk-v560-released) --- ### Box Windows SDK `v5.6.1`のリリース **Type:** changelog | **Section:** Changelog Box Windows SDK v5.6.1のリリース バグ修正: BoxConflictErrorContextInfoのオブジェクトの値をサポート (#930) (496f758) https://www.nuget.org/packages/Box.V2/5.6.… # Box Windows SDK v5.6.1のリリース **バグ修正:** - `BoxConflictErrorContextInfo`のオブジェクトの値をサポート ([#930](https://github.com/box/box-windows-sdk-v2/issues/930)) ([`496f758`](https://github.com/box/box-windows-sdk-v2/commit/496f758c3436b1834188078027b7305ca6a98fce)) [https://www.nuget.org/packages/Box.V2/5.6.1](https://www.nuget.org/packages/Box.V2/5.6.1) [https://www.nuget.org/packages/Box.V2.Core/5.6.1](https://www.nuget.org/packages/Box.V2.Core/5.6.1) **Source:** [https://ja.developer.box.com/changelog/2023-11-29-box-windows-sdk-v561-released](https://ja.developer.box.com/changelog/2023-11-29-box-windows-sdk-v561-released) --- ### Box Windows SDK `v5.7.0`のリリース **Type:** changelog | **Section:** Changelog Box Windows SDK v5.7.0のリリース 新機能と機能強化: GetFolderItemsのマーカーベースのページ割りのバージョンを追加 (#936) (f877a8f) 署名リクエストの署名者グループIDをサポート (#938) (096a09… # Box Windows SDK v5.7.0のリリース **新機能と機能強化:** - `GetFolderItems`のマーカーベースのページ割りのバージョンを追加 ([#936](https://github.com/box/box-windows-sdk-v2/issues/936)) ([`f877a8f`](https://github.com/box/box-windows-sdk-v2/commit/f877a8f9105d65a3e3ca459fcbf4a1bb653ff0f3)) - 署名リクエストの署名者グループIDをサポート ([#938](https://github.com/box/box-windows-sdk-v2/issues/938)) ([`096a098`](https://github.com/box/box-windows-sdk-v2/commit/096a09805b189c591289e77ae5f8a8e6f1b466f1)) **バグ修正:** - 分類の削除に関する記述を削除 ([#932](https://github.com/box/box-windows-sdk-v2/issues/932)) ([`fb59489`](https://github.com/box/box-windows-sdk-v2/commit/fb594897850ad9daacf75cab702f3765cc7168c0)) [https://www.nuget.org/packages/Box.V2/5.7.0](https://www.nuget.org/packages/Box.V2/5.7.0) [https://www.nuget.org/packages/Box.V2.Core/5.7.0](https://www.nuget.org/packages/Box.V2.Core/5.7.0) **Source:** [https://ja.developer.box.com/changelog/2024-02-27-box-windows-sdk-v570-released](https://ja.developer.box.com/changelog/2024-02-27-box-windows-sdk-v570-released) --- ### Box Windows SDK `v5.7.1`のリリース **Type:** changelog | **Section:** Changelog Box Windows SDK v5.7.1のリリース バグ修正: 不足していた列挙値をBoxSortByに追加 (#953) (1f89bb0)、#952をクローズ EventSourceの不足していたフィールドを追加 (#956) (138eda5) 毎回Random… # Box Windows SDK v5.7.1のリリース **バグ修正:** - 不足していた列挙値を`BoxSortBy`に追加 ([#953](https://github.com/box/box-windows-sdk-v2/issues/953)) ([`1f89bb0`](https://github.com/box/box-windows-sdk-v2/commit/1f89bb047442dcdc9045aeff1c3d6aadf61e2856))、[#952](https://github.com/box/box-windows-sdk-v2/issues/952)をクローズ - `EventSource`の不足していたフィールドを追加 ([#956](https://github.com/box/box-windows-sdk-v2/issues/956)) ([`138eda5`](https://github.com/box/box-windows-sdk-v2/commit/138eda516ad59f08968d88b04e9bb06df3c397f2)) - 毎回Randomを再作成しない ([#945](https://github.com/box/box-windows-sdk-v2/issues/945)) ([`d03b1ce`](https://github.com/box/box-windows-sdk-v2/commit/d03b1ce65d4077e2895acfce3bc286ea501669aa))、[#944](https://github.com/box/box-windows-sdk-v2/issues/944) [#944](https://github.com/box/box-windows-sdk-v2/issues/944) [#944](https://github.com/box/box-windows-sdk-v2/issues/944) [#944](https://github.com/box/box-windows-sdk-v2/issues/944)をクローズ [https://www.nuget.org/packages/Box.V2/5.7.1](https://www.nuget.org/packages/Box.V2/5.7.1) [https://www.nuget.org/packages/Box.V2.Core/5.7.1](https://www.nuget.org/packages/Box.V2.Core/5.7.1) **Source:** [https://ja.developer.box.com/changelog/2024-06-28-box-windows-sdk-v571-released](https://ja.developer.box.com/changelog/2024-06-28-box-windows-sdk-v571-released) --- ### Box Windows SDK `v5.8.0`のリリース **Type:** changelog | **Section:** Changelog Box Windows SDK v5.8.0のリリース 新機能と機能強化: AIのサポートを追加 (#965) (a9e130a) バグ修正: System.IdentityModel.Tokens.Jwt依存関係のバージョンをv6.35.0に昇格 (#962) (6e4723… # Box Windows SDK v5.8.0のリリース **新機能と機能強化:** - AIのサポートを追加 ([#965](https://github.com/box/box-windows-sdk-v2/issues/965)) ([`a9e130a`](https://github.com/box/box-windows-sdk-v2/commit/a9e130a99cf9862f9b50178a6188b2820f9f2c32)) **バグ修正:** - `System.IdentityModel.Tokens.Jwt`依存関係のバージョンを`v6.35.0`に昇格 ([#962](https://github.com/box/box-windows-sdk-v2/issues/962)) ([`6e47237`](https://github.com/box/box-windows-sdk-v2/commit/6e472378e2fccea2db67bf5ef0eb017a31491703))、[#960](https://github.com/box/box-windows-sdk-v2/issues/960) [#961](https://github.com/box/box-windows-sdk-v2/issues/961)をクローズ - `Microsoft.AspNetCore.StaticFiles`および`System.Web`依存関係を削除 ([#964](https://github.com/box/box-windows-sdk-v2/issues/964)) ([`2c8eedc`](https://github.com/box/box-windows-sdk-v2/commit/2c8eedc91c473aca52249aad443345471ca7eafc)) [https://www.nuget.org/packages/Box.V2/5.8.0](https://www.nuget.org/packages/Box.V2/5.8.0) [https://www.nuget.org/packages/Box.V2.Core/5.8.0](https://www.nuget.org/packages/Box.V2.Core/5.8.0) **Source:** [https://ja.developer.box.com/changelog/2024-07-22-box-windows-sdk-v580-released](https://ja.developer.box.com/changelog/2024-07-22-box-windows-sdk-v580-released) --- ### BoxとCrowdStrikeの統合 **Type:** changelog | **Section:** Changelog BoxとCrowdStrikeの統合 CrowdStrikeは、Boxと統合され、エンドポイントのアクティビティを監視するエンドポイント検出ツールです。BoxおよびBoxを利用している組織に接続しているデバイスを監視し、デバイスや接続に関するデータを分析して潜在的な脅威のアクティビティを特定します。 CrowdStrikeとの統合により、企業でトリガーできるイベントストリームのイベントが追加されます。 # BoxとCrowdStrikeの統合 CrowdStrikeは、Boxと統合され、エンドポイントのアクティビティを監視するエンドポイント検出ツールです。BoxおよびBoxを利用している組織に接続しているデバイスを監視し、デバイスや接続に関するデータを分析して潜在的な脅威のアクティビティを特定します。 CrowdStrikeとの統合により、企業でトリガーできる[イベントストリームのイベント](g://events/enterprise-events/for-enterprise#event-types)が追加されます。 例えば、CrowdStrike Falconプラットフォームで新しいデバイスが検出されると、`EDR_CROWDSTRIKE_DEVICE_DETECTED`イベントがトリガーされます。すべてのイベントを含むリストは以下のとおりです。 - `EDR_CROWDSTRIKE_DEVICE_DETECTED` - `EDR_CROWDSTRIKE_NO_BOX_TOOLS` - `EDR_CROWDSTRIKE_BOX_TOOLS_OUTDATED` - `EDR_CROWDSTRIKE_DRIVE_OUTDATED` - `EDR_CROWDSTRIKE_ACCESS_ALLOWED_NO_CROWDSTRIKE_DEVICE` - `EDR_CROWDSTRIKE_ACCESS_REVOKED` ## サポート情報 問題がある場合やさらにガイドが必要な場合は、必要なサポートについて、Boxの[Developer Forum](https://forum.box.com/)に英語でリクエストを投稿してください。 **Source:** [https://ja.developer.box.com/changelog/2024-06-03-crowdstrike-integration](https://ja.developer.box.com/changelog/2024-06-03-crowdstrike-integration) --- ### BoxとCrowdStrikeの統合 **Type:** changelog | **Section:** Changelog BoxとCrowdStrikeの統合 CrowdStrikeは、Boxと統合され、エンドポイントのアクティビティを監視するエンドポイント検出ツールです。BoxおよびBoxを利用している組織に接続しているデバイスを監視し、デバイスや接続に関するデータを分析して潜在的な脅威のアクティビティを特定します。 CrowdStrikeとの統合により、企業でトリガーできるイベントストリームのイベントが追加されます。 # BoxとCrowdStrikeの統合 CrowdStrikeは、Boxと統合され、エンドポイントのアクティビティを監視するエンドポイント検出ツールです。BoxおよびBoxを利用している組織に接続しているデバイスを監視し、デバイスや接続に関するデータを分析して潜在的な脅威のアクティビティを特定します。 CrowdStrikeとの統合により、企業でトリガーできる[イベントストリームのイベント](g://events/enterprise-events/for-enterprise#event-types)が追加されます。 例えば、CrowdStrike Falconプラットフォームで新しいデバイスが検出されると、`EDR_CROWDSTRIKE_DEVICE_DETECTED`イベントがトリガーされます。すべてのイベントを含むリストは以下のとおりです。 - `EDR_CROWDSTRIKE_DEVICE_DETECTED` - `EDR_CROWDSTRIKE_NO_BOX_TOOLS` - `EDR_CROWDSTRIKE_BOX_TOOLS_OUTDATED` - `EDR_CROWDSTRIKE_DRIVE_OUTDATED` - `EDR_CROWDSTRIKE_ACCESS_ALLOWED_NO_CROWDSTRIKE_DEVICE` - `EDR_CROWDSTRIKE_ACCESS_REVOKED` ## サポート情報 問題がある場合やさらにガイドが必要な場合は、必要なサポートについて、Boxの[Developer Forum](https://forum.box.com/)に英語でリクエストを投稿してください。 **Source:** [https://ja.developer.box.com/changelog/2024-12-05-crowdstrike-integration](https://ja.developer.box.com/changelog/2024-12-05-crowdstrike-integration) --- ### Boxの注釈を更新 **Type:** changelog | **Section:** Changelog Boxの注釈を更新 顧客がカスタムアプリケーションで使用するBox APIを介して使用できる注釈機能に、… # Boxの注釈を更新 顧客がカスタムアプリケーションで使用するBox APIを介して使用できる注釈機能に、2つの拡張機能が加えられました。更新内容は以下のとおりです。 - **ポイント注釈モード**: ポイント注釈モードの導入により、ポイント注釈が強化されました。これにより、それぞれの注釈の後にポイント注釈アイコンを再選択しなくても、ドキュメントに注釈を追加できます。[こちら](guide://embed/ui-elements)を参照してください。 - **有効期限付き埋め込みリンクによる描画注釈**: 2017年11月に描画注釈機能が追加されました。これにより、エンドユーザーがタッチ対応デバイスでタッチまたはスタイラスを使用して自由形式で描画できるようになりました。正式リリース版の注釈描画機能は、期限付き埋め込みリンクによって提供されます。Get Embed Link APIを経由して注釈を使用するユーザーは、Boxプレビューでまったく新しい表現方法を使用できるようになりました。 **Source:** [https://ja.developer.box.com/changelog/2018-03-05-update-to-box-annotations](https://ja.developer.box.com/changelog/2018-03-05-update-to-box-annotations) --- ### Boxの注釈を更新 **Type:** changelog | **Section:** Changelog Box… # Boxの注釈を更新 一部のユーザーからパフォーマンスの問題が報告されたため、重要なビジネスアプリケーションへの影響を防ぐために更新プログラムがロールバックされました。描画注釈およびポイント注釈モード機能は現在無効化されています。パフォーマンスの修正の予定やこれらの機能が再び有効になる時期は未定です。ご不便をおかけして申し訳ございません。 描画注釈機能を無効化される前に使用していたユーザーは、Edit. Documentation機能が再び有効化された時点で、作成した注釈にアクセスできるようになります。それまでの間、作成した注釈はアプリケーションデータストアに保存されますが、ビューアーには表示されません。 **Source:** [https://ja.developer.box.com/changelog/2018-03-13-update-to-box-annotations](https://ja.developer.box.com/changelog/2018-03-13-update-to-box-annotations) --- ### Boxの注釈を更新 **Type:** changelog | **Section:** Changelog Boxの注釈を更新 2018年3月5日に発表された注釈の更新が再び有効になりました。 # Boxの注釈を更新 2018年3月5日に発表された注釈の更新が再び有効になりました。 **Source:** [https://ja.developer.box.com/changelog/2018-03-28-update-to-box-annotations](https://ja.developer.box.com/changelog/2018-03-28-update-to-box-annotations) --- ### Bulk delete external users **Type:** changelog | **Section:** Changelog Bulk delete external users You can now bulk delete up to 100 external user accounts through the public API. This job runs in the background, and sends a completion report when it's finished. # Bulk delete external users You can now [bulk delete](g://users/bulk-delete-external-users) up to 100 external user accounts through the public API. This job runs in the background, and sends a completion report when it's finished. The report contains details identifying which user deletions succeeded and which failed. ## サポート情報 問題がある場合やさらにガイドが必要な場合は、必要なサポートについて、Boxの[Developer Forum](https://community.box.com/)に英語でリクエストを投稿してください。 **Source:** [https://ja.developer.box.com/changelog/2025-08-15-external-users-bulk-delete](https://ja.developer.box.com/changelog/2025-08-15-external-users-bulk-delete) --- ### changesストリームのコラボレーションイベントの動作変更のお知らせ **Type:** changelog | **Section:** Changelog changesストリームのコラボレーションイベントの動作変更のお知らせ 本日以降、アプリケーションがBoxのイベントAPIエンドポイントからコラボレーションイベントを使用した場合のこのイベントの動作に対する変更のリリースを開始します。 この変更はCOLLAB_INVITE_COLLABORATOR、COLLAB_ADD_COLLABORATOR、COLLAB_ROLE_CHANGE、COLLAB_REMOVE_COLLABORATOR User Eventのみに影響し、クエリパラメータstream_typeがchangesに設定されます。既存のEnterprise Eventには影響しません。この新しい動作により、既存のアプリケーション内でダウンタイムが発生することはありません。また、稼働時間の中断を防ぐためのアプリケーションの変更も必要ありません。 # changesストリームのコラボレーションイベントの動作変更のお知らせ 本日以降、アプリケーションがBoxの[イベントAPIエンドポイント](https://developer.box.com/reference/get-events/)からコラボレーションイベントを使用した場合のこのイベントの動作に対する変更のリリースを開始します。 この変更は`COLLAB_INVITE_COLLABORATOR`、`COLLAB_ADD_COLLABORATOR`、`COLLAB_ROLE_CHANGE`、`COLLAB_REMOVE_COLLABORATOR` [User Event](https://developer.box.com/guides/events/user-events/for-user/#event-types)のみに影響し、クエリパラメータ`stream_type`が`changes`に設定されます。既存の[Enterprise Event](https://developer.box.com/guides/events/enterprise-events/for-enterprise/)には影響しません。この新しい動作により、既存のアプリケーション内でダウンタイムが発生することはありません。また、稼働時間の中断を防ぐためのアプリケーションの変更も必要ありません。 ## 変更の概要 これまで、`COLLAB_INVITE_COLLABORATOR`、`COLLAB_ADD_COLLABORATOR`、`COLLAB_ROLE_CHANGE`、`COLLAB_REMOVE_COLLABORATOR`タイプのイベントでは、その影響を受ける、`changes`ストリームをリッスンしているユーザーに対して通知が作成されていました。コラボレーション項目の所有者は、`all`ストリームもリッスンしていない限り、これらのイベントを受け取ることはありませんでした。 Boxでは、`all`ストリームと`changes`ストリーム間にパリティを確立することで、この相違を解消します。この新しい動作により、コラボレーションの通知は`changes`ストリームでコンテンツの所有者にも作成されるようになります。また、コラボレーションの所有者には、`all`ストリームでの表示内容に合わせて追加のイベントが表示されるようになります。 ## サポート情報 問題がある場合やさらにガイドが必要な場合は、必要なサポートについて、Boxの[Developer Forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum)に英語でリクエストを投稿してください。 **Source:** [https://ja.developer.box.com/changelog/2022-04-06-notice-of-behavior-change-for-collab-events](https://ja.developer.box.com/changelog/2022-04-06-notice-of-behavior-change-for-collab-events) --- ### Collaboration API - `pending`ステータス **Type:** changelog | **Section:** Changelog Collaboration API - pendingステータス Collaboration APIに、pendingステータスに関する情報を追加しました。 コラボレーションがpendingステータスの場合: loginとname… # Collaboration API - pendingステータス [Collaboration API](r://collaboration)に、`pending`ステータスに関する情報を追加しました。 コラボレーションが[`pending`ステータス](e://post-collaborations)の場合: - loginとnameは空の文字列を返します。 以下のフィールドが編集されます: - `user_id`を使用してコラボレーションが作成された場合、`login`と`name`は非表示になります。 - `login`を使用してコラボレーションが作成された場合、`name`は非表示になります。 ## サポート情報 問題がある場合やさらにガイドが必要な場合は、必要なサポートについて、Boxの[Developer Forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum)に英語でリクエストを投稿してください。 **Source:** [https://ja.developer.box.com/changelog/2023-03-28-collaborations-api-update](https://ja.developer.box.com/changelog/2023-03-28-collaborations-api-update) --- ### Developerドキュメントの更新 **Type:** changelog | **Section:** Changelog Developerドキュメントの更新 Developerドキュメントの更新およびバグ修正をいくつかリリースしました。以下をクリックして詳細を確認してください。 # Developerドキュメントの更新 Developerドキュメントの更新およびバグ修正をいくつかリリースしました。以下をクリックして詳細を確認してください。 ## 更新内容 - [メタデータクエリ](g://metadata/queries/create)の例に末尾のバックスラッシュを追加 - [メタデータクエリ](g://metadata/queries/create)の例から余分な引用符を削除 - [Shieldスマートアクセス](g://events/event-triggers/shield-alert-events/#smart-access)イベントの例を更新および追加 - `can_view_path`[フィールド](e://post-collaborations/#param-can_view_path)に注記を追加 - APIで返される適切なレスポンスを表すよう[ごみ箱](e://get-folders-id-trash)のリソースを修正 - 変更ログに`iOS`フィルタを追加 - フォルダロック[エンドポイント](r://folder-lock)に注記を追加 - [開発者トークン](g://authentication/tokens/developer-tokens)ガイドに、トークンを取り消すとWebhookが削除されるという注記を追加 - [サムネイル](e://get-files-id-thumbnail-id)エンドポイントから`94x94`オプションを削除 - イベントの[`limit`パラメータ](e://get-events/#param-limit)に注記を追加 - [ユーザーの`login`パラメータ](e://put-users-id/#param-login)に注記を追加 - PUT [`user`](e://put-users-id/#param-login)エンドポイントにApp Userを追加 - PUT [`user`](e://put-users-id/#param-login)エンドポイントに`external_app_user_id`フィールドを追加 - ドキュメント全体で`X-REF-HINTS`の参照すべてを`x-rep-hints`に変更 - Box Signの11個の[イベント](g://events/event-triggers/sign-events)すべてに新しいフィールドを追加 ## サポート情報 問題がある場合やさらにガイドが必要な場合は、必要なサポートについて、Boxの[Developer Forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum)に英語でリクエストを投稿してください。 **Source:** [https://ja.developer.box.com/changelog/2022-03-03-developer-documentation-updates](https://ja.developer.box.com/changelog/2022-03-03-developer-documentation-updates) --- ### DICOMの公式サポート終了のお知らせ **Type:** changelog | **Section:** Changelog DICOMの公式サポート終了のお知らせ 日本時間2022年1月1日をもちまして、Box DICOM (boxdicomスタディのアップロード、作成、プレビュー機能) の公式サポートを終了しました。 # DICOMの公式サポート終了のお知らせ 日本時間2022年1月1日をもちまして、Box DICOM (`boxdicom`スタディのアップロード、作成、プレビュー機能) の公式サポートを終了しました。 DICOMに関するDeveloperドキュメントは削除されました。詳細については、[Box製品アップデート](https://support.box.com/hc/en-us/articles/1500005724681-Box-DICOM-EOL-on-December-31-2021)を参照してください。 ## サポート情報 問題がある場合やさらにガイドが必要な場合は、必要なサポートについて、Boxの[Developer Forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum)に英語でリクエストを投稿してください。 **Source:** [https://ja.developer.box.com/changelog/2022-02-02-end-of-support-for-dicom](https://ja.developer.box.com/changelog/2022-02-02-end-of-support-for-dicom) --- ### Elements `v11.0`のリリース **Type:** changelog | **Section:** Changelog Elements v11.0のリリース Box UI Elementsバージョン11.0がリリースされました。この更新には、主要な新機能の強化が3つ含まれています。 コンテンツエクスプローラのグリッドビュー。 プレビューのサイドバー内の新しいタスク機能。 プレビューのサイドバーの複数のビジュアルバージョン。 # Elements v11.0のリリース Box UI Elementsバージョン11.0がリリースされました。この更新には、主要な新機能の強化が3つ含まれています。 - コンテンツエクスプローラのグリッドビュー。 - プレビューのサイドバー内の新しいタスク機能。 - プレビューのサイドバーの複数のビジュアルバージョン。 このリリース向けに更新されたJavaScriptファイルとCSSファイルへのリンクは、[UI Elementの手動によるインストール手順](g://embed/ui-elements/installation/#manual-installation)内で入手できます。 このリリースの変更点の詳細については、次のリソースを参照してください。 - [リリースノート](https://github.com/box/box-ui-elements/releases/tag/v11.0.0) - [お知らせに関するブログ記事](https://medium.com/box-developer-blog/announcing-elements-11-88ee900125fd) **Source:** [https://ja.developer.box.com/changelog/2019-11-25-elements-v110-released](https://ja.developer.box.com/changelog/2019-11-25-elements-v110-released) --- ### Enterprise Event APIにスーパーバイザ向けの`created_by`を追加 **Type:** changelog | **Section:** Changelog Enterprise Event APIにスーパーバイザ向けのcreated_byを追加 Box管理者などのスーパーバイザまたは内部管理者ユーザーがアクションを実行する場合のEnterprise Event APIエンドポイントのレスポンスオブジェクトに小さな変更が加えられました。 # Enterprise Event APIにスーパーバイザ向けのcreated_byを追加 Box管理者などのスーパーバイザまたは内部管理者ユーザーがアクションを実行する場合の[Enterprise Event](endpoint://get-events/#request) APIエンドポイントのレスポンスオブジェクトに小さな変更が加えられました。 この更新の前は、スーパーバイザまたは内部管理者ユーザーのユーザー情報がレスポンスオブジェクトの`created_by`フィールドに表示されていました。今回の更新により、そのユーザーがスーパーバイザまたは内部管理者である場合、レスポンスに一般的なユーザー情報が表示されるようになりました。 これまで、レスポンスの`created_by`フィールドは以下のように表示されていました。 ``` "created_by": { "type": "user", "id": "2030401181", "name": "sshah+iadev", "login": "admin_sshah" } ``` 今回の更新により、同じレスポンスが以下のように表示されます。 ``` "created_by": { "type": "user", "id": "box_support", "name": "Box Support", "login": "support@box.com" } ``` **Source:** [https://ja.developer.box.com/changelog/2018-12-05-enterprise-events-api-adds-created_by-for-supervisors](https://ja.developer.box.com/changelog/2018-12-05-enterprise-events-api-adds-created_by-for-supervisors) --- ### Enterprise Eventに新しい`action_by`フィールドを追加 **Type:** changelog | **Section:** Changelog Enterprise Eventに新しいaction_byフィールドを追加 ユーザーアカウントで実行された管理者アクションをより適切に記録するために、Enterprise Eventのレスポンスデータにaction_by… # Enterprise Eventに新しいaction_byフィールドを追加 ユーザーアカウントで実行された管理者アクションをより適切に記録するために、Enterprise Eventのレスポンスデータに`action_by`ミニユーザーオブジェクトが追加されました。このフィールドには、該当する場合に、ユーザー操作を実行した管理者アカウントが表示されます。 Enterpriseの管理者の場合、これにはアカウントのID、ログイン、および名前が含まれます。Boxの内部管理者が実行したアクションの場合、これは以下のようになります。 - id: `box_support` - login: `support@box.com` - name: `Box Support` 追加のオブジェクトは、Enterpriseの[イベントオブジェクト属性](endpoint://resources/event/)内に記録されます。 **Source:** [https://ja.developer.box.com/changelog/2018-08-21-add-new-action_by-field-to-enterprise-events](https://ja.developer.box.com/changelog/2018-08-21-add-new-action_by-field-to-enterprise-events) --- ### Eventの仕様への新しいフィールドの追加 **Type:** changelog | **Section:** Changelog Eventの仕様への新しいフィールドの追加 Eventリソースの仕様に、次の新しいフィールドが含まれるようになりました。 created_at: イベントの作成日時を指定 recorded_at: データベースへのイベントの登録日時の指定 # Eventの仕様への新しいフィールドの追加 Eventリソースの仕様に、次の新しいフィールドが含まれるようになりました。 - `created_at`: イベントの作成日時を指定 - `recorded_at`: データベースへのイベントの登録日時の指定 ## 更新内容 - [Event][Event]リソースの仕様[2](r://event)に新しいフィールド`created_at`と`recorded_at`を追加しました。 ## サポート情報 問題がある場合やさらにガイドが必要な場合は、必要なサポートについて、Boxの[Developer Forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum)に英語でリクエストを投稿してください。 **Source:** [https://ja.developer.box.com/changelog/2022-05-11-new-fields-in-event-api-ref](https://ja.developer.box.com/changelog/2022-05-11-new-fields-in-event-api-ref) --- ### Excelファイルのプレビューで注釈が利用可能に **Type:** changelog | **Section:** Changelog Excelファイルのプレビューで注釈が利用可能に 現在、注釈が有効 (showAnnotations=true) になっていても、Box UI Content Preview Elementまたは有効期限付き埋め込みリンクによる注釈機能がプレビューのExcel… # Excelファイルのプレビューで注釈が利用可能に 現在、注釈が有効 (`showAnnotations=true`) になっていても、[Box UI Content Preview Element](guide://embed/ui-elements)または有効期限付き埋め込みリンクによる注釈機能がプレビューのExcelファイル内に表示されません。 **2018年9月13日**以降、ユーザーは他のファイルタイプ(PDF、doc、PPT)と同様に、Excelファイルに注釈を付けることができます。3つの注釈タイプ(ハイライト、ポイント、描画)のすべてがサポートされます。`showAnnotations`が`true`に設定されている場合、Excelファイルの注釈が表示されます。 **Source:** [https://ja.developer.box.com/changelog/2018-09-05-annotations-available-for-excel-files-in-preview](https://ja.developer.box.com/changelog/2018-09-05-annotations-available-for-excel-files-in-preview) --- ### Java SDK `v2.10.0`のリリース **Type:** changelog | **Section:** Changelog Java SDK v2.10.0のリリース ユーザーのメールエイリアスを追加するためのis_confirmedパラメータ (省略可) を追加 (#499) トークン無効化のサポートを追加 (#510) メタデータテンプレートの削除 (#512) # Java SDK v2.10.0のリリース - ユーザーのメールエイリアスを追加するための`is_confirmed`パラメータ (省略可) を追加 ([#499](https://github.com/box/box-java-sdk/pull/499)) - トークン無効化のサポートを追加 ([#510](https://github.com/box/box-java-sdk/pull/510)) - メタデータテンプレートの削除 ([#512](https://github.com/box/box-java-sdk/pull/512)) **Source:** [https://ja.developer.box.com/changelog/2018-01-12-java-sdk-v2100-release](https://ja.developer.box.com/changelog/2018-01-12-java-sdk-v2100-release) --- ### Java SDK `v2.11.0`のリリース **Type:** changelog | **Section:** Changelog Java SDK v2.11.0のリリース 2GBを超えるファイルの分割アップロードを修正 (#531) 更新されたファイルバージョンのアップロードエンドポイントを追加し、古いメソッドを廃止 (#524) 一般的なJWTエラーを回避するためにJWT認証で変更された再試行を実行 # Java SDK v2.11.0のリリース 1. 2GBを超えるファイルの分割アップロードを修正 ([#531](https://github.com/box/box-java-sdk/pull/531)) 2. 更新されたファイルバージョンのアップロードエンドポイントを追加し、古いメソッドを廃止 ([#524](https://github.com/box/box-java-sdk/pull/524)) 3. 一般的なJWTエラーを回避するためにJWT認証で変更された再試行を実行 **Source:** [https://ja.developer.box.com/changelog/2018-01-25-java-sdk-v2110-release](https://ja.developer.box.com/changelog/2018-01-25-java-sdk-v2110-release) --- ### Java SDK `v2.12.0`のリリース **Type:** changelog | **Section:** Changelog Java SDK v2.12.0のリリース コラボレーション通知パラメータを修正 (#545) OAuth 2.0トークン作成イベントタイプを追加 (#533) Enterpriseへのユーザーの招待を実装 (#504) 分析用のX-Box-UAヘッダーに切り替え (#53… # Java SDK v2.12.0のリリース 1. コラボレーション通知パラメータを修正 ([#545](https://github.com/box/box-java-sdk/pull/545)) 2. OAuth 2.0トークン作成イベントタイプを追加 ([#533](https://github.com/box/box-java-sdk/pull/533)) 3. Enterpriseへのユーザーの招待を実装 ([#504](https://github.com/box/box-java-sdk/pull/504)) 4. 分析用の`X-Box-UA`ヘッダーに切り替え ([#536](https://github.com/box/box-java-sdk/pull/536)) 5. 大きいファイルのアップロード時のメモリ使用量を削減 ([#543](https://github.com/box/box-java-sdk/pull/543)) **Source:** [https://ja.developer.box.com/changelog/2018-02-01-java-sdk-v2120-release](https://ja.developer.box.com/changelog/2018-02-01-java-sdk-v2120-release) --- ### Java SDK `v2.13.0`のリリース **Type:** changelog | **Section:** Changelog Java SDK v2.13.0のリリース メタデータ値の処理を改善 (#553) # Java SDK v2.13.0のリリース 1. メタデータ値の処理を改善 ([#553](https://github.com/box/box-java-sdk/pull/553)) **Source:** [https://ja.developer.box.com/changelog/2018-02-08-java-sdk-v2130-release](https://ja.developer.box.com/changelog/2018-02-08-java-sdk-v2130-release) --- ### Java SDK `v2.14.0`のリリース **Type:** changelog | **Section:** Changelog Java SDK v2.14.0のリリース コラボレーションオブジェクトに足りないcan_view_pathプロパティを修正 (#560) 不足しているメソッドとドキュメントを追加 (#559) 項目のタグを設定するためのサポートを追加 (#554) # Java SDK v2.14.0のリリース 1. コラボレーションオブジェクトに足りない`can_view_path`プロパティを修正 ([#560](https://github.com/box/box-java-sdk/pull/560)) 2. 不足しているメソッドとドキュメントを追加 ([#559](https://github.com/box/box-java-sdk/pull/559)) 3. 項目のタグを設定するためのサポートを追加 ([#554](https://github.com/box/box-java-sdk/pull/554)) **Source:** [https://ja.developer.box.com/changelog/2018-02-15-java-sdk-v2140-release](https://ja.developer.box.com/changelog/2018-02-15-java-sdk-v2140-release) --- ### Java SDK `v2.14.1`のリリース **Type:** changelog | **Section:** Changelog Java SDK v2.14.1のリリース 指数バックオフにランダム化を追加 (#565) サポート対象時にTLSバージョン1.1以降を強制 (#548) 連続するAPIコールをEventStreamによって遅延 (#564) # Java SDK v2.14.1のリリース 1. 指数バックオフにランダム化を追加 ([#565](https://github.com/box/box-java-sdk/pull/565)) 2. サポート対象時にTLSバージョン1.1以降を強制 ([#548](https://github.com/box/box-java-sdk/pull/548)) 3. 連続するAPIコールを`EventStream`によって遅延 ([#564](https://github.com/box/box-java-sdk/pull/564)) **Source:** [https://ja.developer.box.com/changelog/2018-03-01-java-sdk-v2141-release](https://ja.developer.box.com/changelog/2018-03-01-java-sdk-v2141-release) --- ### Java SDK `v2.15.0`のリリース **Type:** changelog | **Section:** Changelog Java SDK v2.15.0のリリース コラボレーションフィールドの取得を許可 (#570) IDによるメタデータテンプレートの取得を実装 (#568) # Java SDK v2.15.0のリリース 1. コラボレーションフィールドの取得を許可 ([#570](https://github.com/box/box-java-sdk/pull/570)) 2. IDによるメタデータテンプレートの取得を実装 ([#568](https://github.com/box/box-java-sdk/pull/568)) **Source:** [https://ja.developer.box.com/changelog/2018-03-12-java-sdk-v2150-release](https://ja.developer.box.com/changelog/2018-03-12-java-sdk-v2150-release) --- ### Java SDK `v2.16.0`のリリース **Type:** changelog | **Section:** Changelog Java SDK v2.16.0のリリース JWT有効期限の間隔を調整 (#572) API接続でのカスタムヘッダーの設定を許可 (#562) JWT再試行タイムスタンプ解析を修正 (#575) ユーザー追跡コードのサポートを追加 (#487) # Java SDK v2.16.0のリリース 1. JWT有効期限の間隔を調整 ([#572](https://github.com/box/box-java-sdk/pull/572)) 2. API接続でのカスタムヘッダーの設定を許可 ([#562](https://github.com/box/box-java-sdk/pull/562)) 3. JWT再試行タイムスタンプ解析を修正 ([#575](https://github.com/box/box-java-sdk/pull/575)) 4. ユーザー追跡コードのサポートを追加 ([#487](https://github.com/box/box-java-sdk/pull/487)) **Source:** [https://ja.developer.box.com/changelog/2018-03-22-java-sdk-v2160-release](https://ja.developer.box.com/changelog/2018-03-22-java-sdk-v2160-release) --- ### Java SDK `v2.16.1`のリリース **Type:** changelog | **Section:** Changelog Java SDK v2.16.1のリリース CONTENT_ACCESSイベントタイプを追加 (#581) # Java SDK v2.16.1のリリース 1. `CONTENT_ACCESS`イベントタイプを追加 ([#581](https://github.com/box/box-java-sdk/pull/581)) **Source:** [https://ja.developer.box.com/changelog/2018-03-29-java-sdk-v2161-release](https://ja.developer.box.com/changelog/2018-03-29-java-sdk-v2161-release) --- ### Java SDK `v2.17.0`のリリース **Type:** changelog | **Section:** Changelog Java SDK v2.17.0のリリース メタデータ駆動のリテンションポリシーのサポートを追加 (#535) # Java SDK v2.17.0のリリース 1. メタデータ駆動のリテンションポリシーのサポートを追加 ([#535](https://github.com/box/box-java-sdk/pull/535)) **Source:** [https://ja.developer.box.com/changelog/2018-04-10-java-sdk-v2170-release](https://ja.developer.box.com/changelog/2018-04-10-java-sdk-v2170-release) --- ### Java SDK `v2.18.0`のリリース **Type:** changelog | **Section:** Changelog Java SDK v2.18.0のリリース エラーオブジェクト (#588) インターセプタのrequest.toString()のNPEのクイック修正 (#595) レプリゼンテーションコンテンツ取得のサポートを追加 (#583) privateKeyPassword… # Java SDK v2.18.0のリリース 1. エラーオブジェクト ([#588](https://github.com/box/box-java-sdk/pull/588)) 2. インターセプタの`request.toString()`のNPEのクイック修正 ([#595](https://github.com/box/box-java-sdk/pull/595)) 3. レプリゼンテーションコンテンツ取得のサポートを追加 ([#583](https://github.com/box/box-java-sdk/pull/583)) 4. `privateKeyPassword`が設定されていなかった`BoxConfig`コンストラクタメソッドを修正 ([#593](https://github.com/box/box-java-sdk/pull/593)) **Source:** [https://ja.developer.box.com/changelog/2018-04-30-java-sdk-v2180-release](https://ja.developer.box.com/changelog/2018-04-30-java-sdk-v2180-release) --- ### Java SDK `v2.19.0`のリリース **Type:** changelog | **Section:** Changelog Java SDK v2.19.0のリリース マルチゾーン (#598) BoxCollaborator.InfoにgetLogin()メソッドを追加 (#602) メタデータでのmultiSelectフィールドのサポートを追加 (#597) # Java SDK v2.19.0のリリース 1. マルチゾーン ([#598](https://github.com/box/box-java-sdk/pull/598)) 2. `BoxCollaborator.Info`に`getLogin()`メソッドを追加 ([#602](https://github.com/box/box-java-sdk/pull/602)) 3. メタデータでの`multiSelect`フィールドのサポートを追加 ([#597](https://github.com/box/box-java-sdk/pull/597)) **Source:** [https://ja.developer.box.com/changelog/2018-05-10-java-sdk-v2190-release](https://ja.developer.box.com/changelog/2018-05-10-java-sdk-v2190-release) --- ### Java SDK `v2.20.0`のリリース **Type:** changelog | **Section:** Changelog Java SDK v2.20.0のリリース メタデータフィールドの複数選択 (#610) 重複するas-userヘッダーのチェックを修正 (#612) # Java SDK v2.20.0のリリース 1. メタデータフィールドの複数選択 ([#610](https://github.com/box/box-java-sdk/pull/610)) 2. 重複するas-userヘッダーのチェックを修正 ([#612](https://github.com/box/box-java-sdk/pull/612)) **Source:** [https://ja.developer.box.com/changelog/2018-05-24-java-sdk-v2200-release](https://ja.developer.box.com/changelog/2018-05-24-java-sdk-v2200-release) --- ### Java SDK `v2.20.1`のリリース **Type:** changelog | **Section:** Changelog Java SDK v2.20.1のリリース レスポンス例外でJSON解析エラーを処理 (#615) uploadNewVersion()の戻りオブジェクトを修正 (#614) # Java SDK v2.20.1のリリース 1. レスポンス例外でJSON解析エラーを処理 ([#615](https://github.com/box/box-java-sdk/pull/615)) 2. `uploadNewVersion()`の戻りオブジェクトを修正 ([#614](https://github.com/box/box-java-sdk/pull/614)) **Source:** [https://ja.developer.box.com/changelog/2018-06-04-java-sdk-v2201-release](https://ja.developer.box.com/changelog/2018-06-04-java-sdk-v2201-release) --- ### Java SDK `v2.20.2`のリリース **Type:** changelog | **Section:** Changelog Java SDK v2.20.2のリリース レスポンスヘッダーで大文字と小文字の区別なし (#620) # Java SDK v2.20.2のリリース 1. レスポンスヘッダーで大文字と小文字の区別なし ([#620](https://github.com/box/box-java-sdk/pull/620)) **Source:** [https://ja.developer.box.com/changelog/2018-06-28-java-sdk-v2202-release](https://ja.developer.box.com/changelog/2018-06-28-java-sdk-v2202-release) --- ### Java SDK `v2.21.0`のリリース **Type:** changelog | **Section:** Changelog Java SDK v2.21.0のリリース Sharedlinkパスワード (#623) リンクを修正 (#626) # Java SDK v2.21.0のリリース 1. `Sharedlink`パスワード ([#623](https://github.com/box/box-java-sdk/pull/623)) 2. リンクを修正 ([#626](https://github.com/box/box-java-sdk/pull/626)) **Source:** [https://ja.developer.box.com/changelog/2018-07-06-java-sdk-v2210-release](https://ja.developer.box.com/changelog/2018-07-06-java-sdk-v2210-release) --- ### Java SDK `v2.22.0`のリリース **Type:** changelog | **Section:** Changelog Java SDK v2.22.0のリリース 別のユーザーにコンテンツを転送するためのパッチ (#632) # Java SDK v2.22.0のリリース 1. 別のユーザーにコンテンツを転送するためのパッチ ([#632](https://github.com/box/box-java-sdk/pull/632)) **Source:** [https://ja.developer.box.com/changelog/2018-08-09-java-sdk-v2220-release](https://ja.developer.box.com/changelog/2018-08-09-java-sdk-v2220-release) --- ### Java SDK `v2.23.0`のリリース **Type:** changelog | **Section:** Changelog Java SDK v2.23.0のリリース メタデータカスケードポリシー (#603) # Java SDK v2.23.0のリリース 1. メタデータカスケードポリシー ([#603](https://github.com/box/box-java-sdk/pull/603)) **Source:** [https://ja.developer.box.com/changelog/2018-08-23-java-sdk-v2230-release](https://ja.developer.box.com/changelog/2018-08-23-java-sdk-v2230-release) --- ### Java SDK `v2.23.1`のリリース **Type:** changelog | **Section:** Changelog Java SDK v2.23.1のリリース 多数のリクエストを発行する際に開かれるTCP接続が多すぎる問題を修正 (#646) # Java SDK v2.23.1のリリース 1. 多数のリクエストを発行する際に開かれるTCP接続が多すぎる問題を修正 ([#646](https://github.com/box/box-java-sdk/pull/646)) **Source:** [https://ja.developer.box.com/changelog/2018-09-13-java-sdk-v2231-release](https://ja.developer.box.com/changelog/2018-09-13-java-sdk-v2231-release) --- ### Java SDK `v2.23.2`のリリース **Type:** changelog | **Section:** Changelog Java SDK v2.23.2のリリース バッチヘッダーのパッチ (#649) # Java SDK v2.23.2のリリース 1. バッチヘッダーのパッチ ([#649](https://github.com/box/box-java-sdk/pull/649)) **Source:** [https://ja.developer.box.com/changelog/2018-09-27-java-sdk-v2232-release](https://ja.developer.box.com/changelog/2018-09-27-java-sdk-v2232-release) --- ### Java SDK `v2.24.0`のリリース **Type:** changelog | **Section:** Changelog Java SDK v2.24.0のリリース optionsオブジェクトのテストと実装を追加 (#661) BoxItemのオブジェクトタイプを公開 (#662) 接続ごとのタイムアウトを許可 (#660) 最大リクエスト数のグローバル設定を追加 (#657) is_ongoing… # Java SDK v2.24.0のリリース 1. optionsオブジェクトのテストと実装を追加 ([#661](https://github.com/box/box-java-sdk/pull/661)) 2. `BoxItem`のオブジェクトタイプを公開 ([#662](https://github.com/box/box-java-sdk/pull/662)) 3. 接続ごとのタイムアウトを許可 ([#660](https://github.com/box/box-java-sdk/pull/660)) 4. 最大リクエスト数のグローバル設定を追加 ([#657](https://github.com/box/box-java-sdk/pull/657)) 5. `is_ongoing`フィールドにオーバーロードを追加し、`is_ongoing`にgetterを追加 ([#653](https://github.com/box/box-java-sdk/pull/653)) **Source:** [https://ja.developer.box.com/changelog/2018-11-16-java-sdk-v2240-release](https://ja.developer.box.com/changelog/2018-11-16-java-sdk-v2240-release) --- ### Java SDK `v2.25.0`のリリース **Type:** changelog | **Section:** Changelog Java SDK v2.25.0のリリース outputstreamを介したBoxへのコンテンツストリーミングを許可。#667 # Java SDK v2.25.0のリリース 1. `outputstream`を介したBoxへのコンテンツストリーミングを許可。[#667](https://github.com/box/box-java-sdk/pull/667) **Source:** [https://ja.developer.box.com/changelog/2018-12-13-java-sdk-v2250-release](https://ja.developer.box.com/changelog/2018-12-13-java-sdk-v2250-release) --- ### Java SDK `v2.25.1`のリリース **Type:** changelog | **Section:** Changelog Java SDK v2.25.1のリリース bouncycastleとjose4jの依存関係のアップグレード (#669) # Java SDK v2.25.1のリリース 1. `bouncycastle`と`jose4j`の依存関係のアップグレード ([#669](https://github.com/box/box-java-sdk/pull/669)) **Source:** [https://ja.developer.box.com/changelog/2019-01-03-java-sdk-v2251-release](https://ja.developer.box.com/changelog/2019-01-03-java-sdk-v2251-release) --- ### Java SDK `v2.26.0`のリリース **Type:** changelog | **Section:** Changelog Java SDK v2.26.0のリリース 不足しているフィールドをタスクとフォルダに追加し、タスクのフィールドを取得する機能を追加 (#677) README.mdの誤字を修正 (#678) invite_emailフィールドをコラボレーションオブジェクトに追加 (#672) # Java SDK v2.26.0のリリース 1. 不足しているフィールドをタスクとフォルダに追加し、タスクのフィールドを取得する機能を追加 ([#677](https://github.com/box/box-java-sdk/pull/677)) 2. `README.md`の誤字を修正 ([#678](https://github.com/box/box-java-sdk/pull/678)) 3. `invite_email`フィールドをコラボレーションオブジェクトに追加 ([#672](https://github.com/box/box-java-sdk/pull/672)) **Source:** [https://ja.developer.box.com/changelog/2019-01-17-java-sdk-v2260-release](https://ja.developer.box.com/changelog/2019-01-17-java-sdk-v2260-release) --- ### Java SDK `v2.27.0`のリリース **Type:** changelog | **Section:** Changelog Java SDK v2.27.0のリリース メタデータの分類 (#671) # Java SDK v2.27.0のリリース 1. メタデータの分類 ([#671](https://github.com/box/box-java-sdk/pull/671)) **Source:** [https://ja.developer.box.com/changelog/2019-01-31-java-sdk-v2270-release](https://ja.developer.box.com/changelog/2019-01-31-java-sdk-v2270-release) --- ### Java SDK `v2.28.0`のリリース **Type:** changelog | **Section:** Changelog Java SDK v2.28.0のリリース トレースID付きの例外メッセージにリクエストIDを追加 (#684) ユーザーアバター機能 (#683) # Java SDK v2.28.0のリリース 1. トレースID付きの例外メッセージにリクエストIDを追加 ([#684](https://github.com/box/box-java-sdk/pull/684)) 2. ユーザーアバター機能 ([#683](https://github.com/box/box-java-sdk/pull/683)) **Source:** [https://ja.developer.box.com/changelog/2019-02-21-java-sdk-v2280-release](https://ja.developer.box.com/changelog/2019-02-21-java-sdk-v2280-release) --- ### Java SDK `v2.28.1`のリリース **Type:** changelog | **Section:** Changelog Java SDK v2.28.1のリリース BoxMetadataCascadePolicy.forceApply()のBoxAPIResponseでのレスポンスの間違ったキャスト (#685) # Java SDK v2.28.1のリリース 1. `BoxMetadataCascadePolicy.forceApply()`の`BoxAPIResponse`でのレスポンスの間違ったキャスト ([#685](https://github.com/box/box-java-sdk/pull/685)) **Source:** [https://ja.developer.box.com/changelog/2019-03-07-java-sdk-v2281-release](https://ja.developer.box.com/changelog/2019-03-07-java-sdk-v2281-release) --- ### Java SDK `v2.29.0`のリリース **Type:** changelog | **Section:** Changelog Java SDK v2.29.0のリリース 説明付きのファイルのアップロードのサポート (#690) 並べ替えと方向のフィールドを検索に追加 (#689) # Java SDK v2.29.0のリリース 1. 説明付きのファイルのアップロードのサポート ([#690](https://github.com/box/box-java-sdk/pull/690)) 2. 並べ替えと方向のフィールドを検索に追加 ([#689](https://github.com/box/box-java-sdk/pull/689)) **Source:** [https://ja.developer.box.com/changelog/2019-04-01-java-sdk-v2290-release](https://ja.developer.box.com/changelog/2019-04-01-java-sdk-v2290-release) --- ### Java SDK `v2.30.0`のリリース **Type:** changelog | **Section:** Changelog Java SDK v2.30.0のリリース action_byフィールドをBoxEventに追加 (#692) # Java SDK v2.30.0のリリース 1. `action_by`フィールドを`BoxEvent`に追加 ([#692](https://github.com/box/box-java-sdk/pull/692)) **Source:** [https://ja.developer.box.com/changelog/2019-04-04-java-sdk-v2300-release](https://ja.developer.box.com/changelog/2019-04-04-java-sdk-v2300-release) --- ### Java SDK `v2.30.1`のリリース **Type:** changelog | **Section:** Changelog Java SDK v2.30.1のリリース RFC3339タイムゾーン形式を正しく処理するように日付の解析を修正 (#693) # Java SDK v2.30.1のリリース 1. RFC3339タイムゾーン形式を正しく処理するように日付の解析を修正 ([#693](https://github.com/box/box-java-sdk/pull/693)) **Source:** [https://ja.developer.box.com/changelog/2019-04-08-java-sdk-v2301-release](https://ja.developer.box.com/changelog/2019-04-08-java-sdk-v2301-release) --- ### Java SDK `v2.31.0`のリリース **Type:** changelog | **Section:** Changelog Java SDK v2.31.0のリリース フォルダ項目の並べ替えのサポートを追加 (#694) # Java SDK v2.31.0のリリース 1. フォルダ項目の並べ替えのサポートを追加 ([#694](https://github.com/box/box-java-sdk/pull/694)) **Source:** [https://ja.developer.box.com/changelog/2019-04-11-java-sdk-v2310-release](https://ja.developer.box.com/changelog/2019-04-11-java-sdk-v2310-release) --- ### Java SDK `v2.32.0`のリリース **Type:** changelog | **Section:** Changelog Java SDK v2.32.0のリリース メタデータ設定をサポート (#697) # Java SDK v2.32.0のリリース 1. メタデータ設定をサポート ([#697](https://github.com/box/box-java-sdk/pull/697)) **Source:** [https://ja.developer.box.com/changelog/2019-04-25-java-sdk-v2320-release](https://ja.developer.box.com/changelog/2019-04-25-java-sdk-v2320-release) --- ### Java SDK `v2.33.0`のリリース **Type:** changelog | **Section:** Changelog Java SDK v2.33.0のリリース パーツバッファのサイズが正しいことを確認するためのテストを追加 (#703) フォルダオブジェクトでのcan_non_owners_inviteフィールドの設定を許可 (#700) # Java SDK v2.33.0のリリース 1. パーツバッファのサイズが正しいことを確認するためのテストを追加 ([#703](https://github.com/box/box-java-sdk/pull/703)) 2. フォルダオブジェクトでの`can_non_owners_invite`フィールドの設定を許可 ([#700](https://github.com/box/box-java-sdk/pull/700)) **Source:** [https://ja.developer.box.com/changelog/2019-05-23-java-sdk-v2330-release](https://ja.developer.box.com/changelog/2019-05-23-java-sdk-v2330-release) --- ### Java SDK `v2.34.0`のリリース **Type:** changelog | **Section:** Changelog Java SDK v2.34.0のリリース タスクのfields:アクションを追加 (#707) # Java SDK v2.34.0のリリース 1. タスクのfields:アクションを追加 ([#707](https://github.com/box/box-java-sdk/pull/707)) **Source:** [https://ja.developer.box.com/changelog/2019-06-06-java-sdk-v2340-release](https://ja.developer.box.com/changelog/2019-06-06-java-sdk-v2340-release) --- ### Java SDK `v2.35.0`のリリース **Type:** changelog | **Section:** Changelog Java SDK v2.35.0のリリース is_externally_ownedフィールドのサポートを追加 (#714) 古いerrorおよびerror_descriptionの例外メッセージを追加 (#710) # Java SDK v2.35.0のリリース 1. `is_externally_owned`フィールドのサポートを追加 ([#714](https://github.com/box/box-java-sdk/pull/714)) 2. 古い`error`および`error_description`の例外メッセージを追加 ([#710](https://github.com/box/box-java-sdk/pull/710)) **Source:** [https://ja.developer.box.com/changelog/2019-07-18-java-sdk-v2350-release](https://ja.developer.box.com/changelog/2019-07-18-java-sdk-v2350-release) --- ### Java SDK `v2.36.0`のリリース **Type:** changelog | **Section:** Changelog Java SDK v2.36.0のリリース 共有リンクに便利な機能を追加して設定を修正… (#720) ファイル、フォルダ、およびウェブリンクに足りないフィールドを追加 (#719) # Java SDK v2.36.0のリリース 1. 共有リンクに便利な機能を追加して設定を修正… ([#720](https://github.com/box/box-java-sdk/pull/720)) 2. ファイル、フォルダ、およびウェブリンクに足りないフィールドを追加 ([#719](https://github.com/box/box-java-sdk/pull/719)) **Source:** [https://ja.developer.box.com/changelog/2019-08-01-java-sdk-v2360-release](https://ja.developer.box.com/changelog/2019-08-01-java-sdk-v2360-release) --- ### Java SDK `v2.37.0`のリリース **Type:** changelog | **Section:** Changelog Java SDK v2.37.0のリリース BoxConfig.readFrom()に関する認証ドキュメントを改良 (#723) 複数選択メタデータの置換機能を追加 (#726) # Java SDK v2.37.0のリリース 1. `BoxConfig.readFrom()`に関する認証ドキュメントを改良 ([#723](https://github.com/box/box-java-sdk/pull/723)) 2. 複数選択メタデータの置換機能を追加 ([#726](https://github.com/box/box-java-sdk/pull/726)) **Source:** [https://ja.developer.box.com/changelog/2019-08-22-java-sdk-v2370-release](https://ja.developer.box.com/changelog/2019-08-22-java-sdk-v2370-release) --- ### Java SDK `v2.38.0`のリリース **Type:** changelog | **Section:** Changelog Java SDK v2.38.0のリリース フィールドtrashed_by、restored_at、restored_by、purged_atをFileVersionに追加 (#734) 分割アップロード時にファイル属性を設定 (#730) # Java SDK v2.38.0のリリース 1. フィールド`trashed_by`、`restored_at`、`restored_by`、`purged_at`を`FileVersion`に追加 ([#734](https://github.com/box/box-java-sdk/pull/734)) 2. 分割アップロード時にファイル属性を設定 ([#730](https://github.com/box/box-java-sdk/pull/730)) **Source:** [https://ja.developer.box.com/changelog/2019-09-19-java-sdk-v2380-release](https://ja.developer.box.com/changelog/2019-09-19-java-sdk-v2380-release) --- ### Java SDK `v2.39.0`のリリース **Type:** changelog | **Section:** Changelog Java SDK v2.39.0のリリース バッチのサポート終了 (#741) タスクcompletion_ruleのサポートを追加 (#738) # Java SDK v2.39.0のリリース 1. バッチのサポート終了 ([#741](https://github.com/box/box-java-sdk/pull/741)) 2. タスク`completion_rule`のサポートを追加 ([#738](https://github.com/box/box-java-sdk/pull/738)) **Source:** [https://ja.developer.box.com/changelog/2019-10-17-java-sdk-v2390-release](https://ja.developer.box.com/changelog/2019-10-17-java-sdk-v2390-release) --- ### Java SDK `v2.40.0`のリリース **Type:** changelog | **Section:** Changelog Java SDK v2.40.0のリリース comments.mdを更新 (#749) events.mdを更新 (#750) collections.mdを更新 (#748) files.mdを更新 (#747) files.mdを更新 (#746) files.md… # Java SDK v2.40.0のリリース 1. `comments.md`を更新 ([#749](https://github.com/box/box-java-sdk/pull/749)) 2. `events.md`を更新 ([#750](https://github.com/box/box-java-sdk/pull/750)) 3. `collections.md`を更新 ([#748](https://github.com/box/box-java-sdk/pull/748)) 4. `files.md`を更新 ([#747](https://github.com/box/box-java-sdk/pull/747)) 5. `files.md`を更新 ([#746](https://github.com/box/box-java-sdk/pull/746)) 6. `files.md`をタグのサムネイルコードサンプルに更新 ([#733](https://github.com/box/box-java-sdk/pull/733)) 7. `authentication.md`を更新 ([#739](https://github.com/box/box-java-sdk/pull/739)) **Source:** [https://ja.developer.box.com/changelog/2019-10-24-java-sdk-v2400-release](https://ja.developer.box.com/changelog/2019-10-24-java-sdk-v2400-release) --- ### Java SDK `v2.41.0`のリリース **Type:** changelog | **Section:** Changelog Java SDK v2.41.0のリリース BoxTasks Actions列挙型にcompleteフィールドの列挙型を追加 (#745) # Java SDK v2.41.0のリリース 1. `BoxTasks` Actions列挙型にcompleteフィールドの列挙型を追加 ([#745](https://github.com/box/box-java-sdk/pull/745)) **Source:** [https://ja.developer.box.com/changelog/2019-10-24-java-sdk-v2410-release](https://ja.developer.box.com/changelog/2019-10-24-java-sdk-v2410-release) --- ### Java SDK `v2.42.0`のリリース **Type:** changelog | **Section:** Changelog Java SDK v2.42.0のリリース SDK-1168 メタデータクエリ (#760) ユーザー取得メソッドにマーカーベースのページ割りを追加 (#759) # Java SDK v2.42.0のリリース 1. `SDK-1168` メタデータクエリ ([#760](https://github.com/box/box-java-sdk/pull/760)) 2. ユーザー取得メソッドにマーカーベースのページ割りを追加 ([#759](https://github.com/box/box-java-sdk/pull/759)) **Source:** [https://ja.developer.box.com/changelog/2019-12-17-java-sdk-v2420-release](https://ja.developer.box.com/changelog/2019-12-17-java-sdk-v2420-release) --- ### Java SDK `v2.43.0`のリリース **Type:** changelog | **Section:** Changelog Java SDK v2.43.0のリリース ファイルとフォルダの409以外のエラーでsetMetadataの例外をスロー (#762) # Java SDK v2.43.0のリリース 1. ファイルとフォルダの409以外のエラーで`setMetadata`の例外をスロー ([#762](https://github.com/box/box-java-sdk/pull/762)) **Source:** [https://ja.developer.box.com/changelog/2019-12-20-java-sdk-v2430-release](https://ja.developer.box.com/changelog/2019-12-20-java-sdk-v2430-release) --- ### Java SDK `v2.44.0`のリリース **Type:** changelog | **Section:** Changelog Java SDK v2.44.0のリリース 認証リクエストの再試行を修正 (#764) # Java SDK v2.44.0のリリース 1. 認証リクエストの再試行を修正 ([#764](https://github.com/box/box-java-sdk/pull/764)) **Source:** [https://ja.developer.box.com/changelog/2020-01-21-java-sdk-v2440-release](https://ja.developer.box.com/changelog/2020-01-21-java-sdk-v2440-release) --- ### Java SDK `v2.44.1`のリリース **Type:** changelog | **Section:** Changelog Java SDK v2.44.1のリリース Java Loggerのフォーマットのバグを修正 (#775) レスポンスの日付/時刻の解析を改善 (#772) # Java SDK v2.44.1のリリース 1. Java Loggerのフォーマットのバグを修正 ([#775](https://github.com/box/box-java-sdk/pull/775)) 2. レスポンスの日付/時刻の解析を改善 ([#772](https://github.com/box/box-java-sdk/pull/772)) **Source:** [https://ja.developer.box.com/changelog/2020-02-13-java-sdk-v2441-release](https://ja.developer.box.com/changelog/2020-02-13-java-sdk-v2441-release) --- ### Java SDK `v2.45.0`のリリース **Type:** changelog | **Section:** Changelog Java SDK v2.45.0のリリース 分割アップロード前の事前チェックを追加 (#782) 大きいファイルのアップロードの一部が正常にアップロードされたことを確認… (#781) ファイル名変更での予期しない切断に関するバグを修正 (#77… # Java SDK v2.45.0のリリース 1. 分割アップロード前の事前チェックを追加 ([#782](https://github.com/box/box-java-sdk/pull/782)) 2. 大きいファイルのアップロードの一部が正常にアップロードされたことを確認… ([#781](https://github.com/box/box-java-sdk/pull/781)) 3. ファイル名変更での予期しない切断に関するバグを修正 ([#779](https://github.com/box/box-java-sdk/pull/779)) 4. メタデータクエリによって返される項目ごとにメタデータを返す ([#778](https://github.com/box/box-java-sdk/pull/778)) **Source:** [https://ja.developer.box.com/changelog/2020-04-02-java-sdk-v2450-release](https://ja.developer.box.com/changelog/2020-04-02-java-sdk-v2450-release) --- ### Java SDK `v2.46.0`のリリース **Type:** changelog | **Section:** Changelog Java SDK v2.46.0のリリース 再試行ロジックを修正 (#787) パスパラメータのサニタイズを追加 (#790) コラボレーションの有効期限を設定する機能を追加 (#788) # Java SDK v2.46.0のリリース 1. 再試行ロジックを修正 ([#787](https://github.com/box/box-java-sdk/pull/787)) 2. パスパラメータのサニタイズを追加 ([#790](https://github.com/box/box-java-sdk/pull/790)) 3. コラボレーションの有効期限を設定する機能を追加 ([#788](https://github.com/box/box-java-sdk/pull/788)) **Source:** [https://ja.developer.box.com/changelog/2020-04-09-java-sdk-v2460-release](https://ja.developer.box.com/changelog/2020-04-09-java-sdk-v2460-release) --- ### Java SDK `v2.47.0`のリリース **Type:** changelog | **Section:** Changelog Java SDK v2.47.0のリリース パスパラメータのサニタイズを修正 (#797) ファイルとファイルバージョンのアップローダー表示名フィールドのサポートを追加 (#791) # Java SDK v2.47.0のリリース 1. パスパラメータのサニタイズを修正 ([#797](https://github.com/box/box-java-sdk/pull/797)) 2. ファイルとファイルバージョンのアップローダー表示名フィールドのサポートを追加 ([#791](https://github.com/box/box-java-sdk/pull/791)) **Source:** [https://ja.developer.box.com/changelog/2020-04-23-java-sdk-v2470-release](https://ja.developer.box.com/changelog/2020-04-23-java-sdk-v2470-release) --- ### Java SDK `v2.9.0`のリリース **Type:** changelog | **Section:** Changelog Java SDK v2.9.0のリリース readme更新の検索 (#506) アップロードの整合性のためにファイルのSHA-1ハッシュを渡すオプションを追加 (#502) イベントログの制限 (#507) サービス利用規約 (#484) wiremockポートの変更 (#50… # Java SDK v2.9.0のリリース 1. `readme`更新の検索 ([#506](https://github.com/box/box-java-sdk/pull/506)) 2. アップロードの整合性のためにファイルの`SHA-1`ハッシュを渡すオプションを追加 ([#502](https://github.com/box/box-java-sdk/pull/502)) 3. イベントログの制限 ([#507](https://github.com/box/box-java-sdk/pull/507)) 4. サービス利用規約 ([#484](https://github.com/box/box-java-sdk/pull/484)) 5. `wiremock`ポートの変更 ([#505](https://github.com/box/box-java-sdk/pull/505)) 6. 冗長な`response.disconnect()`を`moveFolderToUser()`から削除 ([#485](https://github.com/box/box-java-sdk/pull/485)) 7. イベントの`readme`のパッチ ([#503](https://github.com/box/box-java-sdk/pull/503)) 8. 不足しているWebhookトリガーを列挙型に追加 ([#497](https://github.com/box/box-java-sdk/pull/497)) 9. `MetadataTemplate.updateMetadataTemplate()`のタイプエラーを修正 ([#498](https://github.com/box/box-java-sdk/pull/498)) 10. 欠落しているイベントタイプを列挙型に追加 ([#500](https://github.com/box/box-java-sdk/pull/500)) 11. `modified_at`タイムスタンプを`BoxComment.Info`に追加 ([#501](https://github.com/box/box-java-sdk/pull/501)) 12. コラボレーションホワイトリスト ([#492](https://github.com/box/box-java-sdk/pull/492)) 13. 空の本文のごみ箱への移動のパッチ ([#495](https://github.com/box/box-java-sdk/pull/495)) 14. nullの有効期限を許可することで無期限のBoxファイルロックのサポートを追加 ([#494](https://github.com/box/box-java-sdk/pull/494)) 15. Batch APIに対するレスポンスの追加のテスト ([#474](https://github.com/box/box-java-sdk/pull/474)) 16. `BoxDeveloperEditionAPIConnection - decryptPrivateKey() - PEMParser returns PrivateKeyInfo already - Invalid cast` [#470](https://github.com/box/box-java-sdk/pull/470)を修正 ([#471](https://github.com/box/box-java-sdk/pull/471)) **Source:** [https://ja.developer.box.com/changelog/2018-01-04-java-sdk-v290-release](https://ja.developer.box.com/changelog/2018-01-04-java-sdk-v290-release) --- ### JWT形式に対して予定されている変更 **Type:** changelog | **Section:** Changelog JWT形式に対して予定されている変更 日本時間2021年8月5日に、インフラストラクチャの継続的なアップグレードの一環として、JSON Web Token (JWT) を使用するサーバー認証を利用しているカスタムアプリケーションに影響を及ぼす可能性がある変更の展開を開始する予定です。 潜在的な影響により、公式のBox SDKを使用せず、トークンをデータベースに格納しているユーザーによる追加の確認が必要になります。 影響を受ける可能性があるユーザーとアプリケーション所有者全員に、メールで直接通知済みです。 # JWT形式に対して予定されている変更 日本時間2021年8月5日に、インフラストラクチャの継続的なアップグレードの一環として、JSON Web Token (JWT) を使用するサーバー認証を利用しているカスタムアプリケーションに影響を及ぼす可能性がある変更の展開を開始する予定です。 潜在的な影響により、公式の[Box SDK](https://developer.box.com/sdks-and-tools)を使用せず、トークンをデータベースに格納しているユーザーによる追加の確認が必要になります。 影響を受ける可能性があるユーザーとアプリケーション所有者全員に、メールで直接通知済みです。 ## 変更の概要 今回の変更は、JSON Web Token (JWT) を使用するサーバー認証を利用しているアプリケーションのみに影響を及ぼす可能性があります。トークンは、Boxの[ドキュメント](https://developer.box.com/reference/post-oauth2-token/)で説明されているとおり、今後も文字列として返されますが、その形式は長くなり、特殊文字が含まれるようになります。 special characters. 現在返されるトークンの例: `NXWd9KDPVofXQKZJlQjICCWFHEmuOihs` 今回の変更後、トークンは次の形式で返されます。 `1!yxxhRreQCKcEbC_ZfYvPudyLe7Ed36gIQcqqZo2pfaVZyxNBkQjoHk0fgA1iTY3_uwXgif-hg-gne aUdLRmGCb2He6tyQ_rA8aV-CllTyBbd9Tx-wU6Fnt4Df9XjzBAk8Dj7RYc1Ew_fcY2vfycpCvjwHLgql jzjEpVIrOpOlK_2AyP5FExzn0x7DtbkaGc6avJU8UMQd_huXoJ7CnXIL_JBzVrW4D32pBLQ2AZIuecOZ NMIy9T8PdUiZIG6xKEPqYmm21mQHEM0d7dT5foSBtjm65-Ah2tb2MdSGFb1G1O24vz2GmYFgmIe5UOol qYIGg-0u2xQPC3F76WiNCiU_TP1JDQYi3HKaos807WkRtnBY5Vd-VAbY9DH-Qo3u1EiB0RFr4cht2N7V B99y-379IEYzCojL2V58dE_pBxpRMv4KcOLVsUfDkbx3uo34H4UzOycI_IWGWrhVJD4M7GeLeD_5Vkmj fbwYl2CmHdXAKbZKtXTHjzB0CZixZriT_wRUpsN8GTrrxGbx9ukgzJWRJwelGZ_1Yx7vP4Zkx3OfR5Be -Tso7xdHd9rW0FXsu024U7dMNuQ6kpP1_kJI2Y`. この形式はBoxにとって新しい形式ではありません。これは、[トークンのダウンスコープ](https://developer.box.com/guides/authentication/access-tokens/downscope)に使用されている形式と同じになります。 ## アプリケーションへの影響の確認 1. [**管理コンソール**] > [**アプリ**] タブ > [**カスタムアプリ**] に移動します。 2. 表示されている各アプリの行で [**表示**] をクリックします。 3. アプリの詳細ページの一番下までスクロールし、選択されている認証方法を確認します。影響を受けるアプリには、[**サーバー認証 (JWT使用)**] と表示されます。 上記で特定された各アプリケーションについて、以下の点を確認する必要があります。 1. 公式の[Box SDK](https://developer.box.com/sdks-and-tools)が使用されているかどうか。使用されている場合は、何もする必要はありません。常に最新バージョンを使用することをお勧めしますが、互換性に必要となる最小バージョンはありません。 1. 公式のSDKが使用されていない場合は、トークンがデータベースに格納されているかどうか。データベースに格納されている場合は、そのデータベースが新しい長さと特殊文字の両方に対応できるかを確認する必要があります。 ## リリース前のテスト サーバー認証 (JWT使用) を利用してトークンをデータベースに格納するアプリケーションを特定したら、8月5日より前に以下のテストを実行する必要があります。 前述のとおり、トークンの新しい形式は、現在、[トークンのダウンスコープ](https://developer.box.com/guides/authentication/access-tokens/downscope)時に使用されています。そのため、影響を確認するには、次の手順を実行してください。 アプリケーション用にアクセストークンを生成します。 手順1で生成したトークンを[ダウンスコープ](https://developer.box.com/guides/authentication/access-tokens/downscope)します。 ダウンスコープされたトークンをデータベースに格納します。 このトークンをデータベースに問題なく格納できる場合は、何もする必要はありません。 このトークンを格納できない場合は、追加の長さと特殊文字をサポートするようデータベースを更新する必要があります。 ## サポート情報 ご質問がある場合やさらにガイドが必要な場合は、[jwt-set-rollout@box.com](mailto:jwt-set-rollout@box.com)に英語でお問い合わせください。 **Source:** [https://ja.developer.box.com/changelog/2021-08-04-changes-to-jwt-token-format](https://ja.developer.box.com/changelog/2021-08-04-changes-to-jwt-token-format) --- ### JWT認証のアプリアクセスレベルの改善 **Type:** changelog | **Section:** Changelog JWT認証のアプリアクセスレベルの改善 企業の管理対象ユーザーと、JWTで認証されたアプリで作成されていないグループにアクセスできるようになりました。そのためには、開発者コンソールの [構成] タブで [アプリアクセスレベル] を [アプリ + Enterpriseアクセス] に設定します。 # JWT認証のアプリアクセスレベルの改善 企業の管理対象ユーザーと、[JWTで認証されたアプリ](g://authentication/jwt/jwt-setup)で作成されていない**グループ**にアクセスできるようになりました。そのためには、開発者コンソールの [**構成**] タブで [**アプリアクセスレベル**] を [**アプリ + Enterpriseアクセス**] に設定します。 ## サポート情報 問題がある場合やさらにガイドが必要な場合は、必要なサポートについて、Boxの[Developer Forum](https://forum.box.com/)に英語でリクエストを投稿してください。 **Source:** [https://ja.developer.box.com/changelog/2023-07-25-JWT-access-group-access](https://ja.developer.box.com/changelog/2023-07-25-JWT-access-group-access) --- ### Node SDK `v1.28.0`のリリース **Type:** changelog | **Section:** Changelog Node SDK v1.28.0のリリース v1.28.0リリースの準備 (#366) 8fa21de ウェブリンクの一般的な項目メソッドを追加 (#364) 7549d4f v1.27.0...v1.28.0 # Node SDK v1.28.0のリリース - `v1.28.0`リリースの準備 ([#366](https://github.com/box/box-node-sdk/pull/366)) [`8fa21de`](https://github.com/box/box-node-sdk/commit/8fa21de) - ウェブリンクの一般的な項目メソッドを追加 ([#364](https://github.com/box/box-node-sdk/pull/364)) [`7549d4f`](https://github.com/box/box-node-sdk/commit/7549d4f) [`v1.27.0...v1.28.0`](https://github.com/box/box-node-sdk/compare/%60v1.27.0...v1.28.0%60) **Source:** [https://ja.developer.box.com/changelog/2019-03-28-node-sdk-v1280-release](https://ja.developer.box.com/changelog/2019-03-28-node-sdk-v1280-release) --- ### Node SDK `v1.29.0`のリリース **Type:** changelog | **Section:** Changelog Node SDK v1.29.0のリリース v1.29.0リリースの準備 (#381) 4860e7c メタデータ設定のための便利なメソッドを追加 (#376) 1938e39 IssueテンプレートでHTMLコメントを使用 01f21df… # Node SDK v1.29.0のリリース - `v1.29.0`リリースの準備 ([#381](https://github.com/box/box-node-sdk/pull/381)) [`4860e7c`](https://github.com/box/box-node-sdk/commit/4860e7c) - メタデータ設定のための便利なメソッドを追加 ([#376](https://github.com/box/box-node-sdk/pull/376)) [`1938e39`](https://github.com/box/box-node-sdk/commit/1938e39) - IssueテンプレートでHTMLコメントを使用 [`01f21df`](https://github.com/box/box-node-sdk/commit/01f21df) - ドキュメント検索の並べ替えパラメータ ([#370](https://github.com/box/box-node-sdk/pull/370)) [`257e748`](https://github.com/box/box-node-sdk/commit/257e748) [`v1.28.0...v1.29.0`](https://github.com/box/box-node-sdk/compare/%60v1.28.0...v1.29.0%60) **Source:** [https://ja.developer.box.com/changelog/2019-04-25-node-sdk-v1290-release](https://ja.developer.box.com/changelog/2019-04-25-node-sdk-v1290-release) --- ### Node SDK `v1.29.1`のリリース **Type:** changelog | **Section:** Changelog Node SDK v1.29.1のリリース JTIクレームが拒否された場合にJTIを再生成し、認証リクエストを再試行 (#405) c0ccdb9 v1.29.0...v1.29.1 # Node SDK v1.29.1のリリース - JTIクレームが拒否された場合にJTIを再生成し、認証リクエストを再試行 ([#405](https://github.com/box/box-node-sdk/pull/405)) [`c0ccdb9`](https://github.com/box/box-node-sdk/commit/c0ccdb9) [`v1.29.0...v1.29.1`](https://github.com/box/box-node-sdk/compare/%60v1.29.0...v1.29.1%60) **Source:** [https://ja.developer.box.com/changelog/2019-08-22-node-sdk-v1291-release](https://ja.developer.box.com/changelog/2019-08-22-node-sdk-v1291-release) --- ### Node SDK `v1.30.0`のリリース **Type:** changelog | **Section:** Changelog Node SDK v1.30.0のリリース Batch APIメソッドが非推奨に (#433) b06f404 共有リンクを使用したトークン交換のサポートを追加 (#398) 76aa1cf v1.29.1...v1.30.0 # Node SDK v1.30.0のリリース - Batch APIメソッドが非推奨に ([#433](https://github.com/box/box-node-sdk/pull/433)) [`b06f404`](https://github.com/box/box-node-sdk/commit/b06f404) - 共有リンクを使用した[トークン交換](./lib/box-client.js#L495)のサポートを追加 ([#398](https://github.com/box/box-node-sdk/pull/398)) [`76aa1cf`](https://github.com/box/box-node-sdk/commit/76aa1cf) [`v1.29.1...v1.30.0`](https://github.com/box/box-node-sdk/compare/%60v1.29.1...v1.30.0%60) **Source:** [https://ja.developer.box.com/changelog/2019-11-21-node-sdk-v1300-release](https://ja.developer.box.com/changelog/2019-11-21-node-sdk-v1300-release) --- ### Node SDK `v1.31.0`のリリース **Type:** changelog | **Section:** Changelog Node SDK v1.31.0のリリース 認証リクエストの再試行を修正 (#454) dd3253e ユーザーエンドポイントにマーカーベースのページ割りを追加 (#461) 055cb5b 次のマーカーを取得するためにgetNextMarker()をPagingIterator… # Node SDK v1.31.0のリリース - 認証リクエストの再試行を修正 ([#454](https://github.com/box/box-node-sdk/pull/454)) [`dd3253e`](https://github.com/box/box-node-sdk/commit/dd3253e) - ユーザーエンドポイントにマーカーベースのページ割りを追加 ([#461](https://github.com/box/box-node-sdk/pull/461)) [`055cb5b`](https://github.com/box/box-node-sdk/commit/055cb5b) - 次のマーカーを取得するために`getNextMarker()`を`PagingIterator`に追加 ([#461](https://github.com/box/box-node-sdk/pull/461)) [`055cb5b`](https://github.com/box/box-node-sdk/commit/055cb5b) [`v1.30.0...v1.31.0`](https://github.com/box/box-node-sdk/compare/%60v1.30.0...v1.31.0%60) **Source:** [https://ja.developer.box.com/changelog/2020-02-14-node-sdk-v1310-release](https://ja.developer.box.com/changelog/2020-02-14-node-sdk-v1310-release) --- ### Node SDK `v1.32.0`のリリース **Type:** changelog | **Section:** Changelog Node SDK v1.32.0のリリース テストに合格しなかったためノード4とノード5のビルドをTravisから一時的に削除。今後調査予定 (#495)。dc558e9 前の呼び出しでレスポンスが返されないときに再試行中にエラーがスローされる問題を修正 (#477)。f1b… # Node SDK v1.32.0のリリース - テストに合格しなかったためノード4とノード5のビルドをTravisから一時的に削除。今後調査予定 ([#495](https://github.com/box/box-node-sdk/pull/495))。[`dc558e9`](https://github.com/box/box-node-sdk/commit/dc558e9) - 前の呼び出しでレスポンスが返されないときに再試行中にエラーがスローされる問題を修正 ([#477](https://github.com/box/box-node-sdk/pull/477))。[`f1b3449`](https://github.com/box/box-node-sdk/commit/f1b3449) - メタデータに基づいてBox項目に[クエリを実行](./docs/metadata.md#query)する機能を追加 ([#487](https://github.com/box/box-node-sdk/pull/487))。[`6f08931`](https://github.com/box/box-node-sdk/commit/6f08931) [`v1.31.0...v1.32.0`](https://github.com/box/box-node-sdk/compare/%60v1.31.0...v1.32.0%60) **Source:** [https://ja.developer.box.com/changelog/2020-04-01-node-sdk-v1320-release](https://ja.developer.box.com/changelog/2020-04-01-node-sdk-v1320-release) --- ### OAuth 2.0のリダイレクトURLの厳密なチェックの有効化 **Type:** changelog | **Section:** Changelog OAuth 2.0のリダイレクトURLの厳密なチェックの有効化 すべてのOAuth 2.0アプリケーションに対する厳密なチェックが有効になりました。 # OAuth 2.0のリダイレクトURLの厳密なチェックの有効化 すべてのOAuth 2.0アプリケーションに対する厳密なチェックが有効になりました。 2021年11月29日に、OAuth 2.0を使用する新しいアプリケーションでは、開発者コンソールの [構成] タブで設定されたURIが、リダイレクトに使用されるURIと厳密に一致することが必要になると[発表](https://developer.box.com/changelog/#2021-11-29-oauth-20-redirect-url-updates)しました。 この変更は現在完了済みです。この標準に準拠していないアプリケーションを使用していた企業には、アプリケーションの更新方法を説明したメールが過去数か月の間に4件送信されています。 ## リダイレクトエラーの解決方法 メールを受信していないか、見逃していた場合は、問題を軽減する以下の手順を確認してください。 1. Box開発者コンソールの [構成] タブで、対象のアプリケーションのリダイレクトURLを変更します。静的URLの場合は、開発者コンソールを更新して複数のURLを追加します。動的URLの場合は、静的URLを使用するか、stateパラメータを使用するようにアプリケーションを更新します。 2. アプリケーションコードで使用されているリダイレクトURLを変更して、開発者コンソールのURLと厳密に一致させます。 1の場合は、以下の手順に従ってください。 - アプリケーション所有者としてBoxにログインし、Box開発者コンソールに移動します。 - アプリケーションをクリックし、[構成] タブに移動します。 - [OAuth 2.0リダイレクトURI] セクションまで下にスクロールします。 - 現在表示されているURLを更新します。 2の場合は、アプリケーションコードを変更し、影響を受ける使用されているURLを、開発者コンソールのURLと厳密に一致するよう置き換えてください。 ## 更新内容 - リダイレクトURIは、渡されたURIと、OAuth 2.0アプリケーションの構成で設定されたURIを一致させるように厳密なチェックを強制するようになりました ## サポート情報 本件に関するご質問は、[Developer Forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum)に英語でリクエストを投稿していただくか、販売店から指定されたサポート窓口にお問い合わせください。[](https://support.box.com/hc/en-us/requests/new) **Source:** [https://ja.developer.box.com/changelog/2022-05-18-oauth-20-redirect-url-release](https://ja.developer.box.com/changelog/2022-05-18-oauth-20-redirect-url-release) --- ### OAuth 2アプリリダイレクトURIの要件の変更 **Type:** changelog | **Section:** Changelog OAuth 2アプリリダイレクトURIの要件の変更 日本時間2020年10月30日から、Boxでは、アプリケーションに影響を及ぼす可能性のある新規および既存のOAuth 2ベースのBox統合で使用されるリダイレクトURI… # OAuth 2アプリリダイレクトURIの要件の変更 日本時間2020年10月30日から、Boxでは、アプリケーションに影響を及ぼす可能性のある新規および既存の[OAuth 2](g://authentication/oauth2/)ベースのBox統合で使用されるリダイレクトURIに対してより厳しい要件を使用します。 現在アプリケーションの構成で空のリダイレクトURIを使用している既存のアプリケーション所有者は、[こちらの説明](g://authentication/oauth2/oauth2-setup/#redirect-uri)に従って、コードのリダイレクト手順 ([こちらを参照](g://authentication/oauth2/with-sdk/#2-redirect-user)) で使用されているリダイレクトと一致するようリダイレクトURIを更新する必要があります。 2020年10月30日以降、まだ空のURIを使用して構成されているアプリケーションでは、URIの調整が行われない場合にユーザーがアプリケーションにリダイレクトされると、エラーが返されるようになります。 影響を受けるアプリケーション所有者とコラボレータの全員には、各自のDeveloperアカウントに関連付けられたメールアドレスを利用して通知しました。 ## 確認して変更を行う方法 アプリケーションンが影響を受けた場合にリダイレクトURIを確認し、アプリケーションを更新するには、以下の手順を実行します。 - アプリケーションを所有するユーザーとして、[Box開発者コンソール](https://cloud.app.box.com/developers/console)に移動します。 - **OAuth 2** (クライアント側認証) を使用する**カスタムアプリ**ごとに、そのアプリケーションをクリックして開きます。 - 左のナビゲーションで [**構成**] をクリックします。 - [**OAuth 2.0リダイレクトURI**] セクションまで下にスクロールします。 - このURIが空のアプリケーションでは、<c0>こちらのガイドで説明されているように<c0>、Boxの認証手順からアプリケーションにユーザーをリダイレクトする際にアプリケーションコードで使用されるURIを追加します。 **Source:** [https://ja.developer.box.com/changelog/2020-09-29-changes-to-oauth-2-app-redirect-url-requirements](https://ja.developer.box.com/changelog/2020-09-29-changes-to-oauth-2-app-redirect-url-requirements) --- ### Open With UI ElementおよびAdobe Signの公式サポート終了 **Type:** changelog | **Section:** Changelog Open With UI ElementおよびAdobe Signの公式サポート終了 本日、Open With UI ElementをBox Tools、Google Workspace、およびAdobe Signと統合できるようになりました。Box… # Open With UI ElementおよびAdobe Signの公式サポート終了 本日、[Open With UI Element](g://embed/ui-elements/open-with)をBox Tools、Google Workspace、およびAdobe Signと統合できるようになりました。Boxでは、常にエクスペリエンスの改善に向けて取り組む中で、変化するユーザーのニーズにより合った新しい機能の開発に今後も注力してまいります。 日本時間2021年12月22日に、以下の変更が行われる予定です。 Box ToolsおよびGoogle Workspaceでは、新規のお客様に対するBox Open With UI Elementのサポートが終了する予定です。12月22日までにこのUI Elementを使用しなかったお客様は、新規のお客様とみなされます。12月22日までにBox Tools/Google WorkspaceでOpen With UI Elementを利用した場合は、既存のお客様とみなされ、別途通知があるまで引き続きサポートを受けることができます。Box ToolsおよびGoogle Workspaceのウェブアプリ機能に影響はありません。 Adobe Signは、新規のお客様も既存のお客様も、Open With UI Elementまたはウェブアプリから使用できなくなる予定です。 ご質問がある場合は、[サポート](https://developer.box.com/support)チケットを作成するか[Developer Forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum)に英語で投稿してお問い合わせください。 **Source:** [https://ja.developer.box.com/changelog/2021-09-21-end-of-support-for-open-with-ui-element](https://ja.developer.box.com/changelog/2021-09-21-end-of-support-for-open-with-ui-element) --- ### Platform ActivityのCSVレポート **Type:** changelog | **Section:** Changelog Platform ActivityのCSVレポート Box管理コンソールでEnterpriseのプラットフォームリソースの使用状況を表示するレポートを利用できるようになりました。このレポートの最初のバージョンでは、実効日である2018年4月1日までの、Boxの既存のContent… # Platform ActivityのCSVレポート Box管理コンソールでEnterpriseのプラットフォームリソースの使用状況を表示するレポートを利用できるようになりました。このレポートの最初のバージョンでは、実効日である2018年4月1日までの、Boxの既存のContent APIに対するAPIコールの総数への統合が表示されます。このレポートの今後の反復では、サービスごとの追加のリソース消費(月間アクティブユーザー、帯域幅、ストレージ)が表示され、履歴データも含められます。詳細については、[Boxコミュニティの記事「レポートの実行」][community]を参照してください。 **Source:** [https://ja.developer.box.com/changelog/2018-04-18-platform-activity-csv-report](https://ja.developer.box.com/changelog/2018-04-18-platform-activity-csv-report) --- ### Platform Activityの履歴のCSVレポート **Type:** changelog | **Section:** Changelog Platform Activityの履歴のCSVレポート ウェブサイトで新しいレポートが使用可能になりました。Box管理コンソールで、Enterpriseのプラットフォームリソースの過去の使用状況を表示するドキュメントを利用できます。このレポートには、2017年1月… # Platform Activityの履歴のCSVレポート ウェブサイトで新しいレポートが使用可能になりました。Box管理コンソールで、Enterpriseのプラットフォームリソースの過去の使用状況を表示するドキュメントを利用できます。このレポートには、2017年1月1日から2018年3月31日までのアプリケーションごとの月別の会社の月間アクティブユーザー、APIコール、および帯域幅消費が示されています。詳細については、[こちら](https://community.box.com/t5/How-to-Guides-for-Admins/Running-the-Platform-Activity-Report/ta-p/58620)を参照してください。 **Source:** [https://ja.developer.box.com/changelog/2018-07-11-historical-platform-activity-csv-report](https://ja.developer.box.com/changelog/2018-07-11-historical-platform-activity-csv-report) --- ### Postmanコレクションとクイックスタートを更新 **Type:** changelog | **Section:** Changelog Postmanコレクションとクイックスタートを更新 Box Postmanコレクションは、新機能と、統合されたクイックスタートガイドによって更新されました。主な機能は以下のとおりです。 エンドツーエンドのPostmanクイックスタートガイド。これは、ユーザーがPostman… # Postmanコレクションとクイックスタートを更新 Box Postmanコレクションは、新機能と、統合されたクイックスタートガイドによって更新されました。主な機能は以下のとおりです。 - エンドツーエンドの[Postmanクイックスタートガイド](g://tooling/postman/quick-start)。これは、ユーザーがPostmanのインストール、Boxアプリの設定、PostmanへのAPI資格情報の読み込みを行う際に役立ちます。 - Box API用に[再編成されたPostmanコレクション](g://tooling/postman/install)。これにより、API資格情報の期限切れが自動的に検出され、必要に応じてこれらの資格情報を更新するための統合ソリューションが提供されます。 しばらくの間は[従来のPostmanコレクション](g://tooling/postman)も引き続きご利用いただけます。 **Source:** [https://ja.developer.box.com/changelog/2020-01-20-refreshed-postman-collection-quick-start](https://ja.developer.box.com/changelog/2020-01-20-refreshed-postman-collection-quick-start) --- ### Preview SDK `v2.26.0`のリリース **Type:** changelog | **Section:** Changelog Preview SDK v2.26.0のリリース Preview SDKのバージョン2.26.0がリリースされ、新しいJavaScriptとCSSのPreviewファイルが使用可能になりました。新しい変更を導入するには、コンテンツプレビュー用のリンクをUI Element… # Preview SDK v2.26.0のリリース Preview SDKのバージョン`2.26.0`がリリースされ、新しいJavaScriptとCSSのPreviewファイルが使用可能になりました。新しい変更を導入するには、コンテンツプレビュー用のリンクを[UI Elementの手動によるインストール](g://embed/ui-elements/installation/#manual-installation)に関する記事で確認してください。 機能の変更点の全一覧については、`v2.26.0`の[リリースノート](https://github.com/box/box-content-preview/releases/tag/v2.26.0)を参照してください。 **Source:** [https://ja.developer.box.com/changelog/2019-11-20-preview-sdk-v2260-released](https://ja.developer.box.com/changelog/2019-11-20-preview-sdk-v2260-released) --- ### Preview SDK `v2.29.0`のリリース **Type:** changelog | **Section:** Changelog Preview SDK v2.29.0のリリース Preview SDKのバージョン2.29.0がリリースされ、新しいJavaScriptとCSSのPreviewファイルが使用可能になりました。新しい変更を導入するには、コンテンツプレビュー用のリンクをUI Element… # Preview SDK v2.29.0のリリース Preview SDKのバージョン`2.29.0`がリリースされ、新しいJavaScriptとCSSのPreviewファイルが使用可能になりました。新しい変更を導入するには、コンテンツプレビュー用のリンクを[UI Elementの手動によるインストール](g://embed/ui-elements/installation/#manual-installation)に関する記事で確認してください。 機能の変更点の全一覧については、`v2.29.0`の[リリースノート](https://github.com/box/box-content-preview/releases/tag/v2.29.0)を参照してください。 **Source:** [https://ja.developer.box.com/changelog/2019-12-03-preview-sdk-v2290-released](https://ja.developer.box.com/changelog/2019-12-03-preview-sdk-v2290-released) --- ### Preview SDK `v2.33.1`のリリース **Type:** changelog | **Section:** Changelog Preview SDK v2.33.1のリリース Preview SDKのバージョン2.33.1がリリースされ、新しいJavaScriptとCSSのPreviewファイルが使用可能になりました。新しい変更を導入するには、コンテンツプレビュー用のリンクをUI Element… # Preview SDK v2.33.1のリリース Preview SDKのバージョン`2.33.1`がリリースされ、新しいJavaScriptとCSSのPreviewファイルが使用可能になりました。新しい変更を導入するには、コンテンツプレビュー用のリンクを[UI Elementの手動によるインストール](g://embed/ui-elements/installation/#manual-installation)に関する記事で確認してください。 機能の変更点の全一覧については、`v2.33.1`の[リリースノート](https://github.com/box/box-content-preview/releases/tag/v2.33.1)を参照してください。 **Source:** [https://ja.developer.box.com/changelog/2020-01-22-preview-sdk-v2331-released](https://ja.developer.box.com/changelog/2020-01-22-preview-sdk-v2331-released) --- ### Preview SDK `v2.34.0`のリリース **Type:** changelog | **Section:** Changelog Preview SDK v2.34.0のリリース Preview SDKのバージョン2.34.0がリリースされ、新しいJavaScriptとCSSのPreviewファイルが使用可能になりました。新しい変更を導入するには、コンテンツプレビュー用のリンクをUI Element… # Preview SDK v2.34.0のリリース Preview SDKのバージョン`2.34.0`がリリースされ、新しいJavaScriptとCSSのPreviewファイルが使用可能になりました。新しい変更を導入するには、コンテンツプレビュー用のリンクを[UI Elementの手動によるインストール](g://embed/ui-elements/installation/#manual-installation)に関する記事で確認してください。 機能の変更点の全一覧については、`v2.34.0`の[リリースノート](https://github.com/box/box-content-preview/releases/tag/v2.34.0)を参照してください。 **Source:** [https://ja.developer.box.com/changelog/2020-02-03-preview-sdk-v2340-released](https://ja.developer.box.com/changelog/2020-02-03-preview-sdk-v2340-released) --- ### Python SDK `v2.0.0`のリリース **Type:** changelog | **Section:** Changelog Python SDK v2.0.0のリリース 重大な変更 Python 2.6はサポートされなくなりました。 Python 3.3はサポートされなくなりました。 client.search()により、検索APIを呼び出すためのquery()メソッドを公開するSearch… # Python SDK v2.0.0のリリース ## 重大な変更 Python 2.6はサポートされなくなりました。 Python 3.3はサポートされなくなりました。 `client.search()`により、検索APIを呼び出すための`query()`メソッドを公開する`Search`オブジェクトが返されるようになりました。`client.search(**search_params)`の代わりに`client.search().query(**search_params)`を使用してください。 `client.get_memberships(...)`の署名が変更されました。他のSDKとの一貫性を保つため、制限パラメータとオフセットパラメータの位置が入れ替えられました。 `client.groups(...)`が`client.get_groups`に変更されました。制限パラメータとオフセットパラメータの位置が入れ替えられました。 `item.create_shared_link(...)`と`file.get_shared_link_download_url(...)`の`unshared_at`パラメータは、`datetime.date`ではなく`RFC3339-formatted <https://tools.ietf.org/html/rfc3339#section-5.8>` `unicode`文字列を取得するようになりました。ユーザーは`v1.x`から移行する場合、`date`オブジェクト自体ではなく`date.isoformat()`の値を渡すことができます。 `Events.get_events(...)`では、イベントを表す`dict`のリストではなく、`Event`インスタンスのリストが返されるようになりました。`Event`は`Mapping`から継承されますが、`dict`と同じ機能をすべて備えているとは限りません。 `Events.get_events(...)`を使用していて、`Mapping`のリストではなく`dict`のリストを想定する場合、コードは影響を受けます。たとえば、`__setitem__` (`event['key'] = value`)、`update()`、`copy()`を使用する場合、またはコードが`Event`の`str`または`repr`に依存する場合がこれに該当します。`__getitem__` (`event['key']`)、`get()`、およびその他の`Mapping`メソッドの使用は影響を受けません。`Mapping`インスタンスでサポートされているメソッドについては、[Pythonドキュメント](https://docs.python.org/2.7/library/collections.html#collections-abstract-base-classes)を参照してください。 移行: まだ`Event`を`dict`として扱う必要がある場合は、`BaseAPIJSONObject`の新しいプロパティ`response_object`を使用して、元の`dict`のディープコピーを取得できます。 `LoggingNetwork`は削除されました。ログ記録の呼び出しは`DefaultNetwork`クラスから行われるようになりました。さらに、このクラスのログ記録形式の文字列は、これらの文字列をオーバーライドしたアプリケーションのログ記録を中断する形で変更されました。位置指定のプレースホルダではなく、キーワード形式のプレースホルダが使用されるようになりました。今後、カスタム形式の文字列はすべて、同じキーワード形式のプレースホルダを使用する必要があります。これは重大な変更ですが、キーワード形式のプレースホルダを使用すると、今後の変更は自動的に後方互換性が維持されるという利点があります (キーワードの変更/削除を伴う変更が行われない限り)。 `File.update_contents()`と`File.update_contents_with_stream()`では、適切な内部JSON構造を持つ`File`オブジェクトが正しく返されるようになりました。以前は、ファイルJSONが`file['entries'][0]`内で非表示になっている`File`オブジェクトが返されていました。これはバグ修正ですが、このバグを処理するコードをすでに作成しているクライアントにとっては重大な変更になります。 Box IDが同じでもタイプが異なる2つのオブジェクト (例: `File`と`Folder`) を`==`で比較した場合に、`False`が正しく返されるようになりました。 次のメソッドでは、単一のページではなく、返されたオブジェクトのコレクション全体の反復子が返されるようになりました。 - `client.users()` - `client.groups()` - `client.search().query()` - `folder.get_items()` `folder.get_items()`が反復子を返すようになったため、`folder.get_items_limit_offset()`と`folder.get_items_marker()`は削除されました。マーカーベースのページングを`folder.get_items()`で使用するには、`use_marker=True`パラメータを渡し、オプションとして`marker`パラメータを指定して、コレクションのそのポイントからページングを開始します。 さらに、`group.membership()`は名前が`group.get_memberships()`に変更され、メンバーシップオブジェクトの反復子を返すようになりました。このメソッドでは、ページング情報を含むタプルを返すオプションが提供されなくなりました。 `Translator`クラスが変更されました。`translator.get(...)`は引き続き、渡された型に対応するオブジェクトクラスのコンストラクタを返しますが、`translator.translate(...)`は、`Session`とレスポンスオブジェクトを直接受け取り、変換されたオブジェクトを生成します。また、このメソッドは、ネストされたオブジェクトが見つかった場合にもそれらを変換します。 - この変更により、`GroupMembership`にカスタムコンストラクタを使用する必要はなくなります。そのため、デフォルトの`BaseObject`コンストラクタが使用されるようになります。 ## 機能 公開されているAPIエンドポイントとパラメータはすべて、SDKでサポートされるようになりました。 オブジェクト変換システムの柔軟性が向上しました。 非グローバルの`Translator`インスタンスを作成できます。これにより、グローバルなデフォルトの`Translator`を拡張することも、拡張しないことも可能です。 カスタム`Translator`で`BoxSession`を初期化できます。 `BoxSession`または`Client`に関連付けられている`Translator`にカスタムサブクラスを登録できます。 APIレスポンスのすべての変換で、グローバルなデフォルトの`Translator`を直接使用する代わりに、`BoxSession`で参照される`Translator`が使用されるようになりました。 ネストされたオブジェクトは`translator.translate()`によって変換されるようになりました。 `BoxSession`に対してリクエストメソッドのいずれかを呼び出すときに`auto_session_renewal`が`True`である場合、アクセストークンがないと、`BoxSession`は、リクエストを実行する_前に_トークンを更新します。これにより、APIコールが1回省略されます。 認証オブジェクトを閉じられるようになりました。これにより、これらのオブジェクトは新しいトークンのリクエストに使用できなくなります。また、既存のトークンも取り消されます (ただし、この機能は、`revoke=False`を渡すことで無効にできます)。加えて、終了時に認証オブジェクトを自動的に閉じる`closing()`コンテキストマネージャメソッドも導入されます。 `JWTAuth`基本クラスに対するさまざまな機能強化: `authenticate_app_user()`メソッドは、管理対象ユーザーの認証にも使用できるようになったことを示すため、`authenticate_user()`という名前に変更されました。詳細については、メソッドの`docstring`を参照してください。`authenticate_app_user()`は、不要な後方非互換性が発生しないよう、`authenticate_user()`のエイリアスとなりました。 `authenticate_user()`への`user`引数に、ユーザーID文字列と`User`インスタンスのいずれかを指定できるようになりました。以前は、`User`インスタンスを指定する必要がありました。 コンストラクタは、`user`キーワード引数 (省略可) を受け取るようになりました。これには、ユーザーID文字列と`User`インスタンスのいずれかを指定できます。この引数が渡されると、`user`引数の値を渡さなくても`authenticate_user()`を呼び出すことができます。さらに重要なことに、これは、構築後すぐに`refresh()`を呼び出すことができることを意味します。その際、`authenticate_user()`を手動で呼び出す必要はありません。前述の`BoxSession`の`auto_session_renewal`機能の改善と組み合わせることで、最初のAPIコール時に、`JWTAuth`オブジェクトの認証を完全に自動で実行できます。 コンストラクタは、RSA秘密キーの受け渡し方法を2つサポートしています。1つはファイルシステムパスを使用する方法 (既存の機能)、もう1つはキーデータを直接渡す方法 (新機能) です。`rsa_private_key_file_sys_path`パラメータは省略可能になりましたが、`rsa_private_key_file_sys_path`または`rsa_private_key_data`のどちらか1つを渡す必要があります。 `JWTAuth`の`enterprise_id`引数を`None`にできることが文書化されました。 `authenticate_instance()`は`enterprise`引数を受け取れるようになりました。これは、構築時に`None`が`enterprise_id`に渡された場合に、Enterpriseのサービスアカウントユーザーとして設定および認証するために使用できます。 有効期限が適切な期間に含まれないことが原因で失敗した認証は、Box APIレスポンスのDateヘッダーで指定された時間を使用して、自動的に再試行されるようになりました。これは、Box SDKを実行しているマシンのシステム時刻がBox APIサーバーのシステム時刻と一致しない場合に必然的に発生する可能性があります。 `Event`クラスが追加されました。 `metadata()`メソッドは`Folder`および`File`で使用できるように`Item`に移動されました。 `BaseAPIJSONObject`基本クラス (すべてのAPIレスポンスオブジェクトのスーパークラス) が`__contains__`および`__iter__`をサポートするようになりました。これらの動作は`Mapping`と同じです。つまり、`__contains__`はオブジェクトのJSONキーをチェックし、`__iter__`はそのオブジェクトのすべてのキーを生成します。 `RecentItem`クラスが追加されました。 Box上でユーザーが最近アクセスした項目を取得する`client.get_recent_items()`が追加されました。 新しいコラボレーション作成時の`can_view_path`パラメータのサポートが追加されました。 エンドポイントからのオブジェクトのページングをより直接的に管理できるように`BoxObjectCollection`とサブクラス`LimitOffsetBasedObjectCollection`および`MarkerBasedObjectCollection`が追加されました。これらのクラスは、エンドポイントへのリクエストを構成して結果を格納するロジックを管理し、結果に対して繰り返し適用される`__next__`を提供します。結果を1つずつ返すか結果の`Page`として返すオプションも提供されます。 `downscope_token()`メソッドが`Client`クラスに追加されました。このメソッドによって生成されるトークンの権限は、指定されたスコープや、オプションとして指定された`File`または`Folder`に下げられています。 構成ファイルから`JWTAuth`を構成するためのメソッド`JWTAuth.from_settings_file`と`JWTAuth.from_settings_dictionary`が追加されました。 `network_response`プロパティが`BoxOAuthException`に追加されました。 APIの構成を`BoxSession`インスタンスごとに実行できるようになりました。 ## その他 - `BoxAPIException`に追加情報が加えられました。 - `collaboration()`メソッドが`Client`に追加されました。 - クラス階層が変更されました。これまで、`BaseEndpoint`は、すべてのスマートオブジェクトの親である`BaseObject`の親でした。今後、`BaseObject`は`BaseEndpoint`と`BaseAPIJSONObject`両方の子になります。`BaseObject`は、REST APIに含まれるすべてのオブジェクトの親です。`BaseAPIJSONObject`の別のサブクラスである`APIJSONObject`は、APIエンドポイントから直接アクセスできない`Event`など、疑似スマートオブジェクトを表すために作成されました。 - `network_response_constructor`が`Network`インターフェースの省略可能なプロパティとして追加されました。実装では、このプロパティを一時的に無効にし、これを使用して`NetworkResponse`インスタンスを構築することをお勧めします。このように、サブクラスの実装では、このプロパティを再度一時的に無効にすることで、`NetworkResponse`の機能を拡張できます。このプロパティは、`DefaultNetwork`実装で定義および使用されます。 - レスポンスログは新しい`LoggingNetworkResponse`クラスに移動されます (これは前述の`network_response_constructor`プロパティによって可能になります)。レスポンス本文をログに記録するかどうかは、呼び出し元がコンテンツを読み取るかストリーミングするかに基づき、SDKで決定されます。 - `LoggingNetwork`からのリクエスト/レスポンスログに情報が追加されました。 - `LoggingNetwork`にリクエスト例外のログ記録が追加されました。 - `JWTAuth.refresh()`の戻り値が認証インターフェースの戻り値と正確に一致するようバグが修正されました (そのために、アクセストークンのみではなく、((アクセストークン), (更新トークンまたはなし)) のタプルを返します)。特に、`JWTAuth`オブジェクトを更新しようとしたときに常に発生していた`BoxSession`の例外が修正されます。 - `ExtendableEnumMeta.__dir__()`から発生していた例外が修正されました。 - `CPython` 3.6のサポート。 - 必要最低限のバージョンが6から1.9.0に引き上げられました。 **Source:** [https://ja.developer.box.com/changelog/2018-11-01-python-sdk-v200-release](https://ja.developer.box.com/changelog/2018-11-01-python-sdk-v200-release) --- ### Python SDK `v2.1.0`のリリース **Type:** changelog | **Section:** Changelog Python SDK v2.1.0のリリース ユーザーがファイルを分割アップロードして、中断されたアップロードを再開する機能が追加されました。 Webhook… # Python SDK v2.1.0のリリース - ユーザーが[ファイルを分割アップロード](https://github.com/box/box-python-sdk/blob/master/docs/usage/files.md#chunked-upload)して、中断されたアップロードを再開する機能が追加されました。 - [Webhookメッセージを確認する](https://github.com/box/box-python-sdk/blob/master/docs/usage/webhook.md#validate-webhook-message)機能が追加されました。 - ユーザーがメタデータの分類を[ファイル](https://github.com/box/box-python-sdk/blob/master/docs/usage/files.md#set-a-classification)や[フォルダ](https://github.com/box/box-python-sdk/blob/master/docs/usage/folders.md#set-a-classification)に追加する機能が追加されました。 - APIオブジェクトで`.response_object()`メソッドを呼び出すとスローされるバグの修正。 **Source:** [https://ja.developer.box.com/changelog/2019-02-08-python-sdk-v210-release](https://ja.developer.box.com/changelog/2019-02-08-python-sdk-v210-release) --- ### Python SDK `v2.2.0`のリリース **Type:** changelog | **Section:** Changelog Python SDK v2.2.0のリリース ユーザーがユーザーのアバターを取得する機能が追加されました。 ランダム化されたジッターを伴う指数バックオフを使用するよう再試行戦略が変更されました。 # Python SDK v2.2.0のリリース - ユーザーがユーザーの[アバターを取得](https://github.com/box/box-python-sdk/blob/master/docs/usage/user.md#get-the-avatar-for-a-user)する機能が追加されました。 - ランダム化されたジッターを伴う指数バックオフを使用するよう再試行戦略が変更されました。 **Source:** [https://ja.developer.box.com/changelog/2019-02-15-python-sdk-v220-release](https://ja.developer.box.com/changelog/2019-02-15-python-sdk-v220-release) --- ### Python SDK `v2.2.1`のリリース **Type:** changelog | **Section:** Changelog Python SDK v2.2.1のリリース パッケージをインストールできなかったv2.2.0の問題を修正しています。 # Python SDK v2.2.1のリリース - パッケージをインストールできなかった`v2.2.0`の問題を修正しています。 **Source:** [https://ja.developer.box.com/changelog/2019-02-15-python-sdk-v221-release](https://ja.developer.box.com/changelog/2019-02-15-python-sdk-v221-release) --- ### Python SDK `v2.2.2`のリリース **Type:** changelog | **Section:** Changelog Python SDK v2.2.2のリリース requests-toolbelt依存関係の制限を更新 # Python SDK v2.2.2のリリース - `requests-toolbelt`依存関係の制限を更新 **Source:** [https://ja.developer.box.com/changelog/2019-03-14-python-sdk-v222-release](https://ja.developer.box.com/changelog/2019-03-14-python-sdk-v222-release) --- ### Python SDK `v2.3.0`のリリース **Type:** changelog | **Section:** Changelog Python SDK v2.3.0のリリース アップロード時にファイルの説明を設定する機能を追加 基本的な認証プロキシと非認証プロキシのサポートを追加 # Python SDK v2.3.0のリリース - [アップロード時にファイルの説明](https://github.com/box/box-python-sdk/blob/master/docs/usage/files.md#upload-a-file)を設定する機能を追加 - [基本的な認証プロキシと非認証プロキシ](https://github.com/box/box-python-sdk/blob/master/docs/usage/configuration.md#proxy)のサポートを追加 **Source:** [https://ja.developer.box.com/changelog/2019-03-28-python-sdk-v230-release](https://ja.developer.box.com/changelog/2019-03-28-python-sdk-v230-release) --- ### Python SDK `v2.3.2`のリリース **Type:** changelog | **Section:** Changelog Python SDK v2.3.2のリリース パッケージをインストールできなかったv2.3.1の問題を修正しています。 # Python SDK v2.3.2のリリース - パッケージをインストールできなかった`v2.3.1`の問題を修正しています。 **Source:** [https://ja.developer.box.com/changelog/2019-03-29-python-sdk-v232-release](https://ja.developer.box.com/changelog/2019-03-29-python-sdk-v232-release) --- ### Python SDK `v2.4.1`のリリース **Type:** changelog | **Section:** Changelog Python SDK v2.4.1のリリース ユーザーがファイルやフォルダでのメタデータの設定を使用する機能を追加 # Python SDK v2.4.1のリリース 1. ユーザーが[ファイル](https://github.com/box/box-python-sdk/blob/master/docs/usage/files.md#set-metadata)や[フォルダ](https://github.com/box/box-python-sdk/blob/master/docs/usage/folders.md#set-metadata)でのメタデータの設定を使用する機能を追加 **Source:** [https://ja.developer.box.com/changelog/2019-05-16-python-sdk-v241-release](https://ja.developer.box.com/changelog/2019-05-16-python-sdk-v241-release) --- ### Python SDK `v2.5.0`のリリース **Type:** changelog | **Section:** Changelog Python SDK v2.5.0のリリース Noneを渡してadd_member()メソッドのconfigurable_permissionフィールドをクリアできるようになりました。 # Python SDK v2.5.0のリリース `None`を渡して`add_member()`メソッドの`configurable_permission`フィールドをクリアできるようになりました。 **Source:** [https://ja.developer.box.com/changelog/2019-06-20-python-sdk-v250-release](https://ja.developer.box.com/changelog/2019-06-20-python-sdk-v250-release) --- ### Python SDK `v2.6.0`のリリース **Type:** changelog | **Section:** Changelog Python SDK v2.6.0のリリース created_before、created_after、event_typeパラメータを持つ、新しい管理者イベント取得関数が追加されました (@capk1rkに感謝します)。 # Python SDK v2.6.0のリリース `created_before`、`created_after`、`event_type`パラメータを持つ、新しい管理者イベント取得関数が追加されました (`@capk1rk`に感謝します)。 **Source:** [https://ja.developer.box.com/changelog/2019-08-29-python-sdk-v260-release](https://ja.developer.box.com/changelog/2019-08-29-python-sdk-v260-release) --- ### Python SDK `v2.6.1`のリリース **Type:** changelog | **Section:** Changelog Python SDK v2.6.1のリリース コピーメソッドにapi_呼び出しデコレータが追加されました。 # Python SDK v2.6.1のリリース - コピーメソッドに`api_`呼び出しデコレータが追加されました。 **Source:** [https://ja.developer.box.com/changelog/2019-10-24-python-sdk-v261-release](https://ja.developer.box.com/changelog/2019-10-24-python-sdk-v261-release) --- ### Python SDK `v2.7.0`のリリース **Type:** changelog | **Section:** Changelog Python SDK v2.7.0のリリース 省略可能なevent_typesパラメータの省略時にエラーが発生するget_admin_events… # Python SDK v2.7.0のリリース - 省略可能な`event_types`パラメータの省略時にエラーが発生する`get_admin_events`関数のバグが修正されました。 - ユーザーのリスト取得にマーカーベースのページ割りが追加されました。 - 新しいファイルや既存ファイルの新バージョンをアップロードするときにより多くの属性パラメータがサポートされるようになりました。 - アクセラレータURLの事前チェックとルックアップがアップロードの単一のリクエストに統合されました。 - JWTの再試行ロジックが修正され、再試行ごとに新しいJTIクレームが生成されるようになりました。 - JWT認証リクエストが誤ったエラーコードを返すバグが修正されました。 - 再試行ロジックが修正され、APIからRetry-Afterヘッダーが返された場合、SDKは再試行の前にヘッダーで指定された時間待機するようになりました。 **Source:** [https://ja.developer.box.com/changelog/2020-01-16-python-sdk-v270-release](https://ja.developer.box.com/changelog/2020-01-16-python-sdk-v270-release) --- ### Python SDK `v2.7.1`のリリース **Type:** changelog | **Section:** Changelog Python SDK v2.7.1のリリース リリース2.7.0で導入された_get_retry_request_callableの分割アップロードが失敗するバグを修正 # Python SDK v2.7.1のリリース - リリース2.7.0で導入された`_get_retry_request_callable`の分割アップロードが失敗するバグを修正 **Source:** [https://ja.developer.box.com/changelog/2020-01-22-python-sdk-v271-release](https://ja.developer.box.com/changelog/2020-01-22-python-sdk-v271-release) --- ### Python SDK `v2.8.0`のリリース **Type:** changelog | **Section:** Changelog Python SDK v2.8.0のリリース 共有リンクを使用したトークン交換のサポートを追加 ファイルのアップロードでSHA1値を渡す機能を追加 # Python SDK v2.8.0のリリース - 共有リンクを使用したトークン交換のサポートを追加 - ファイルのアップロードでSHA1値を渡す機能を追加 **Source:** [https://ja.developer.box.com/changelog/2020-04-24-python-sdk-v280-release](https://ja.developer.box.com/changelog/2020-04-24-python-sdk-v280-release) --- ### Python SDK V2のリリース **Type:** changelog | **Section:** Changelog Python SDK V2のリリース Box Python SDKのメジャーアップデート (バージョン2.0) がリリースされ、重要な更新とAPI機能パリティが加えられました。完全なAPI… # Python SDK V2のリリース [Box Python SDK](https://github.com/box/box-python-sdk)のメジャーアップデート (バージョン2.0) がリリースされ、重要な更新とAPI機能パリティが加えられました。完全なAPIリリースノートについては[こちらを参照してください](https://github.com/box/box-python-sdk/releases/tag/v2.0.0)。今回のリリースとともに、以下のドキュメントの変更が行われました。 - Pythonの[クイックスタートガイド](guide://)の更新。 - Pythonの[APIリファレンス](endpoint://)のコードサンプルの更新。 **Source:** [https://ja.developer.box.com/changelog/2018-10-19-python-sdk-v2-launched](https://ja.developer.box.com/changelog/2018-10-19-python-sdk-v2-launched) --- ### Relay Classic APIエンドポイントの廃止 **Type:** changelog | **Section:** Changelog Relay Classic APIエンドポイントの廃止 2019年10月18日にお知らせしたとおり、Classic Relay API… # Relay Classic APIエンドポイントの廃止 2019年10月18日にお知らせしたとおり、Classic Relay APIエンドポイントは本日をもって正式に廃止されます。 以下のエンドポイントはこの廃止の影響を受けるため、このエンドポイントにリクエストを送信するアプリケーションでエラーレスポンスが返されるようになります。 - 公開されているRelay Classicテンプレートのリストの取得 - Relay Classicワークフローのリストの取得 - Relay Classicワークフローの開始 このようなエラーレスポンスが発生するアプリケーションでは、上記のRelay Classic APIに対する呼び出しをすべて削除してください。 **Source:** [https://ja.developer.box.com/changelog/2019-12-30-eol-of-classic-relay-api-endpoints](https://ja.developer.box.com/changelog/2019-12-30-eol-of-classic-relay-api-endpoints) --- ### Relay Workflow APIの拡張 **Type:** changelog | **Section:** Changelog Relay Workflow APIの拡張 BoxとIBMで共同開発されたワークフローツールBox Relayの機能が、新しいWorkflow APIによって拡張されました。Relay Workflow APIを使用すると、Box Relay… # Relay Workflow APIの拡張 BoxとIBMで共同開発されたワークフローツール[Box Relay](https://www.box.com/collaboration/relay-workflow)の機能が、新しいWorkflow APIによって拡張されました。Relay Workflow APIを使用すると、Box Relayワークフローを起動し、アプリケーション内からそれらのワークフローのステータスを取得できます。また、Box Relayのインスタンスに直接ファイルで公開されているワークフローテンプレートを表示することもできます。APIの詳細については、Boxの[お知らせに関するブログ記事](https://medium.com/box-developer-blog/introducing-the-box-relay-workflow-api-f6eed1457711)を参照してください。 **Source:** [https://ja.developer.box.com/changelog/2018-07-31-expanded-relay-workflow-api](https://ja.developer.box.com/changelog/2018-07-31-expanded-relay-workflow-api) --- ### Salesforce SDKに汎用メソッドを追加 **Type:** changelog | **Section:** Changelog Salesforce SDKに汎用メソッドを追加 Box for Salesforce Developer Toolkitは、パラメータとしてHttpRequestオブジェクトを受け取り、HttpResponseオブジェクトを返すグローバルメソッドsendRequest… # Salesforce SDKに汎用メソッドを追加 Box for Salesforce Developer Toolkitは、パラメータとして[`HttpRequest`](https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_classes_restful_http_httprequest.htm)オブジェクトを受け取り、[`HttpResponse`](https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_classes_restful_http_httpresponse.htm#apex_classes_restful_http_httpresponse)オブジェクトを返すグローバルメソッド`sendRequest`を提供するようになりました。このメソッドは、サービスアカウントの認証の詳細を使用してBoxのAPIを呼び出すため、統合のビジネスロジックの組み込みに集中することができます。追加されたメソッドの詳細については、Salesforce Developer ToolkitドキュメントのBoxメタデータサイドバーの[メソッドの詳細](guide://tooling/sdks/salesforce)および[サンプルコード](guide://tooling/sdks/salesforce)を参照してください。 **Source:** [https://ja.developer.box.com/changelog/2018-08-16-generic-method-added-to-the-salesforce-sdk](https://ja.developer.box.com/changelog/2018-08-16-generic-method-added-to-the-salesforce-sdk) --- ### Salesforceツールキット - フローアクション **Type:** changelog | **Section:** Changelog Salesforceツールキット - フローアクション Salesforceツールキットには、管理者がメソッドを呼び出す際に使用できるラッパーが用意されています。このツールキットを使用すると、Box for SalesforceユーザーはSalesforce… # Salesforceツールキット - フローアクション Salesforceツールキットには、管理者が[メソッド](g://tooling/salesforce-toolkit/flow-actions)を呼び出す際に使用できるラッパーが用意されています。このツールキットを使用すると、Box for Salesforceユーザーは[Salesforceフロー](https://help.salesforce.com/s/articleView?id=sf.flow.htm&type=5)を使用して、自動化ソリューション (フォルダ構造など) を構築できます。 ## サポート情報 問題がある場合やさらにガイドが必要な場合は、必要なサポートについて、Boxの[Developer Forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum)に英語でリクエストを投稿してください。 **Source:** [https://ja.developer.box.com/changelog/2023-01-11-salesforce-toolkit-flow-actions](https://ja.developer.box.com/changelog/2023-01-11-salesforce-toolkit-flow-actions) --- ### Salesforceツールキット - 統合マッピング **Type:** changelog | **Section:** Changelog Salesforceツールキット - 統合マッピング Salesforceツールキットの新しいメソッドとフローアクションで統合マッピングを使用できるようになりました。統合マッピングにより、デフォルトのフォルダではなく、企業の任意のフォルダにSlackチャンネルをマッピングできます。 # Salesforceツールキット - 統合マッピング Salesforceツールキットの新しい[メソッド](g://tooling/salesforce-toolkit/methods/#salesforce_and_slack)と[フローアクション](g://tooling/salesforce-toolkit/flow-actions)で[統合マッピング](g://integration-mappings/slack-mappings)を使用できるようになりました。[統合マッピング](r://integration-mappings)により、デフォルトのフォルダではなく、企業の任意のフォルダにSlackチャンネルをマッピングできます。 ## サポート情報 問題がある場合やさらにガイドが必要な場合は、必要なサポートについて、Boxの[Developer Forum](https://forum.box.com/)に英語でリクエストを投稿してください。 **Source:** [https://ja.developer.box.com/changelog/2023-10-02-salesforce-toolkit-method-update](https://ja.developer.box.com/changelog/2023-10-02-salesforce-toolkit-method-update) --- ### SDKにおけるクライアント資格情報のサポート **Type:** changelog | **Section:** Changelog SDKにおけるクライアント資格情報のサポート Boxの.NETおよびJava SDKでは、クライアント資格情報許可による認証がサポートされるようになりました。今後数週間のうちに他のSDKのサポートもリリースする予定です。 # SDKにおけるクライアント資格情報のサポート Boxの[`.NET`](https://github.com/box/box-windows-sdk-v2)および[`Java`](https://github.com/box/box-java-sdk) SDKでは、クライアント資格情報許可による認証がサポートされるようになりました。今後数週間のうちに他のSDKのサポートもリリースする予定です。 2020年11月に、カスタムアプリケーション向けにクライアント資格情報という新しい認証タイプをリリースしました。今回は、その新しいタイプについてSDKのサポートのリリースを開始しました。 ## 更新内容 - [クライアント資格情報のガイドページ](g://authentication/client-credentials/)で新しいサンプルタグと例を追加。 ## サポート情報 問題がある場合やさらにガイドが必要な場合は、必要なサポートについて、Boxの[Developer Forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum)に英語でリクエストを投稿してください。 **Source:** [https://ja.developer.box.com/changelog/2022-02-16-client-credentials-support-in-the-sdks](https://ja.developer.box.com/changelog/2022-02-16-client-credentials-support-in-the-sdks) --- ### SDKのサポート対象バージョンのお知らせ **Type:** changelog | **Section:** Changelog SDKのサポート対象バージョンのお知らせ 日本時間2022年7月31日以降、サポートされるSDKは最新のメジャーバージョンのみになります。新機能、バグ修正、セキュリティ更新は、最新のメジャーバージョンのみに追加されます。 # SDKのサポート対象バージョンのお知らせ 日本時間2022年7月31日以降、サポートされるSDKは最新の**メジャー**バージョンのみになります。新機能、バグ修正、セキュリティ更新は、最新の**メジャー**バージョンのみに追加されます。 最新のリリースは、SDK開発の最先端を進んでいるため、積極的に開発に取り組み、最新の優れた機能を求めているお客様向けです。Boxでは、新機能のリリース日を指定するのではなく、修正したマイナーリリースやパッチリリースの周期を最大2～3か月に設定しました (ただし、リリースの頻度は高くなる可能性もあります)。それに加えて、メジャーリリースまたは重大なリリースのスケジュールはありません。代わりに、お客様がアップグレードを計画できるように、今後予定されている重大な変更について1四半期前にお知らせする予定です。使用しているメジャーバージョンが何であっても、すべてのユーザーが入手可能な最新のマイナーリリースを実行することを常にお勧めしています。また、正式サポートが終了する前の都合がよいタイミングで最新のSDKメジャーバージョンにアップグレードすることを強くお勧めします。 すべての変更には[セマンティックバージョニング](https://semver.org/)の修正版を使用しています。詳細については、[バージョン戦略](https://github.com/box/box-windows-sdk-v2/blob/main/VERSIONS.md)を参照してください。 ## 各SDKのサポート対象バージョン すべてのSDKのサポート対象バージョンの表へのリンクを以下に示します。 - [Python](https://github.com/box/box-python-sdk#version-schedule) - [.NET](https://github.com/box/box-windows-sdk-v2#supported-version) - [Java](https://github.com/box/box-java-sdk#version-schedule) - [node](https://github.com/box/box-node-sdk#supported-version) - [CLI](https://github.com/box/boxcli#supported-version) - [iOS](https://github.com/box/box-ios-sdk#supported-version) ## サポート情報 問題がある場合やさらにガイドが必要な場合は、必要なサポートについて、Boxの[Developer Forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum)に英語でリクエストを投稿してください。 **Source:** [https://ja.developer.box.com/changelog/2022-03-16-announcing-sdk-supported-versions](https://ja.developer.box.com/changelog/2022-03-16-announcing-sdk-supported-versions) --- ### Shieldの不審な場所に関するアラートの新しいイベントパラメータ **Type:** changelog | **Section:** Changelog Shieldの不審な場所に関するアラートの新しいイベントパラメータ Shieldの不審な場所に関する自動応答のリリースに伴い、Shieldアラートイベントのレスポンスにrule_response_actionパラメータを追加しました。このパラメータは、各Shieldアラートイベントのペイロードで返されますが、不審な場所に関するアラートイベントにしか適用できません。 # Shieldの不審な場所に関するアラートの新しいイベントパラメータ Shieldの不審な場所に関する自動応答のリリースに伴い、[Shieldアラートイベント](g://events/event-triggers/shield-alert-events/#suspicious-locations-alert)のレスポンスに`rule_response_action`パラメータを追加しました。このパラメータは、各Shieldアラートイベントのペイロードで返されますが、**不審な場所**に関するアラートイベントにしか適用できません。 パラメータの値は、管理コンソールの [**ターゲットユーザーのアクセス制限**] のルール設定によって異なります。 - アクティブな場合、アラートがトリガーされると、パラメータの値は`true`になります。 - 非アクティブな場合、アラートがトリガーされると、パラメータの値は`false`になります。 その他すべてのShieldアラート (**異常なダウンロード**、**悪意のあるコンテンツ**、**不審なセッション**) では、`rule_response_action`パラメータは常に`null`になります。 詳細については、[不審な場所のルールの設定](https://support.box.com/hc/en-us/articles/9090542213395-Shield-Threat-Detection-Rule-Settings#h_01GE85EWQ1TS5APY7RGN801QSC)を参照してください。 ## サポート情報 問題がある場合やさらにガイドが必要な場合は、必要なサポートについて、Boxの[Developer Forum](https://forum.box.com/)に英語でリクエストを投稿してください。 **Source:** [https://ja.developer.box.com/changelog/2024-01-19-rule-response-action-param-added%20copy](https://ja.developer.box.com/changelog/2024-01-19-rule-response-action-param-added%20copy) --- ### Shieldの不審な場所に関するアラートの新しいイベントパラメータ **Type:** changelog | **Section:** Changelog Shieldの不審な場所に関するアラートの新しいイベントパラメータ Shieldの不審な場所に関する自動応答のリリースに伴い、Shieldアラートイベントのレスポンスにrule_response_actionパラメータを追加しました。このパラメータは、各Shieldアラートイベントのペイロードで返されますが、不審な場所に関するアラートイベントにしか適用できません。 # Shieldの不審な場所に関するアラートの新しいイベントパラメータ Shieldの不審な場所に関する自動応答のリリースに伴い、[Shieldアラートイベント](g://events/event-triggers/shield-alert-events/#suspicious-locations-alert)のレスポンスに`rule_response_action`パラメータを追加しました。このパラメータは、各Shieldアラートイベントのペイロードで返されますが、**不審な場所**に関するアラートイベントにしか適用できません。 パラメータの値は、管理コンソールの [**ターゲットユーザーのアクセス制限**] のルール設定によって異なります。 - アクティブな場合、アラートがトリガーされると、パラメータの値は`true`になります。 - 非アクティブな場合、アラートがトリガーされると、パラメータの値は`false`になります。 その他すべてのShieldアラート (**異常なダウンロード**、**悪意のあるコンテンツ**、**不審なセッション**) では、`rule_response_action`パラメータは常に`null`になります。 詳細については、[不審な場所のルールの設定](https://support.box.com/hc/en-us/articles/9090542213395-Shield-Threat-Detection-Rule-Settings#h_01GE85EWQ1TS5APY7RGN801QSC)を参照してください。 ## サポート情報 問題がある場合やさらにガイドが必要な場合は、必要なサポートについて、Boxの[Developer Forum](https://forum.box.com/)に英語でリクエストを投稿してください。 **Source:** [https://ja.developer.box.com/changelog/2024-01-19-rule-response-action-param-added](https://ja.developer.box.com/changelog/2024-01-19-rule-response-action-param-added) --- ### Shield情報バリアの導入 **Type:** changelog | **Section:** Changelog Shield情報バリアの導入 情報バリアは、利益相反や潜在的な法的問題につながる可能性のあるコミュニケーションを防止します。たとえば、管理者は情報バリアを使用して、異なるプロジェクトで作業するチームを分け、特定のグループに制限されたコンテンツでのコラボレーションを防ぐことができます。 # Shield情報バリアの導入 情報バリアは、利益相反や潜在的な法的問題につながる可能性のあるコミュニケーションを防止します。たとえば、管理者は情報バリアを使用して、異なるプロジェクトで作業するチームを分け、特定のグループに制限されたコンテンツでのコラボレーションを防ぐことができます。 ## Shield情報バリアAPI Shield情報バリアでは、以下の処理が可能な新しいAPIを利用できます: - [Shield情報バリア](r://shield-information-barrier)の作成、管理、リストの取得 - [Shield情報バリアのセグメント](r://shield-information-barrier-segment)の作成、更新、削除、リストの取得 - [Shield情報バリアのセグメント制限](r://shield-information-barrier-segment-restriction)の作成、削除、リストの取得 - [Shield情報バリアのセグメントメンバー](r://shield-information-barrier-segment-member)の作成、削除、リストの取得 - [Shield情報バリアレポート](r://shield-information-barrier-report)の作成とリストの取得 ## Shield情報バリアイベント 情報バリアを設定すると、以下のイベントが作成されます: - バリアのアクティブ化または非アクティブ化など、ユーザーが情報バリアを構成したときにトリガーされるイベント。 - 制限されたフォルダへの項目の移動や、制限されたグループへのユーザーの追加など、制限されたアクションをユーザーが実行したときにトリガーされるイベント。 すべてのイベントのリストについては、[Shield情報バリアイベントトリガー](g://events/event-triggers/shield-information-barrier-events)リファレンスを参照してください。 ## サポート情報 問題がある場合やさらにガイドが必要な場合は、必要なサポートについて、Boxの[Developer Forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum)に英語でリクエストを投稿してください。 **Source:** [https://ja.developer.box.com/changelog/2022-10-28-information-barrier](https://ja.developer.box.com/changelog/2022-10-28-information-barrier) --- ### Signイベントペイロードへの新しいフィールドの追加 **Type:** changelog | **Section:** Changelog Signイベントペイロードへの新しいフィールドの追加 additional_details Signイベントペイロードに、複数の受信者に一度に送信される署名リクエストを識別するためのbatch_sendが含まれるようになりました。そのような一括送信リクエストが存在する場合、ペイロードはそのidも提供します。 # Signイベントペイロードへの新しいフィールドの追加 `additional_details` Signイベントペイロードに、複数の受信者に一度に送信される署名リクエストを識別するための`batch_send`が含まれるようになりました。そのような一括送信リクエストが存在する場合、ペイロードはその`id`も提供します。 ## 更新内容 - 新しいフィールド`batch_send`を[Signイベント](g://events/event-triggers/sign-events)の`additional_details`ペイロードに追加しました。 ## サポート情報 問題がある場合やさらにガイドが必要な場合は、必要なサポートについて、Boxの[Developer Forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum)に英語でリクエストを投稿してください。 **Source:** [https://ja.developer.box.com/changelog/2022-05-06-new-sign-events-payload-field](https://ja.developer.box.com/changelog/2022-05-06-new-sign-events-payload-field) --- ### Slack統合マッピング **Type:** changelog | **Section:** Changelog Slack統合マッピング Slack統合マッピングガイドで、Box Enterprise管理者が、Slackチャンネルのアップロードフォルダをカスタマイズして、デフォルトのフォルダを使用する代わりに企業内の任意のフォルダに変更する方法を確認できます。 Box API… # Slack統合マッピング [Slack統合マッピング](g://integration-mappings/slack-mappings)ガイドで、Box Enterprise管理者が、Slackチャンネルのアップロードフォルダをカスタマイズして、デフォルトのフォルダを使用する代わりに企業内の任意のフォルダに変更する方法を確認できます。 Box APIを使用することで、Slack統合マッピングの[作成](e://post_integration_mappings_slack)、[リストの取得](e://get_integration_mappings_slack)、[更新](e://update_integration_mappings_slack)、[削除](e://delete_integration_mappings_slack)が可能です。 [自動化スクリプト](https://github.com/box/boxcli/tree/main/examples/Integration%20Mappings)を使用して、管理者は一度に複数のマッピングを作成または更新できます。 発生する可能性が高い一般的な問題に対する解決策については、[トラブルシューティング](g://integration-mappings/slack-mappings/troubleshooting)セクションをご確認ください。 ## サポートを受けるための新しい場所 今後は新しい[Box Developer Communityフォーラム](https://forum.box.com/)で質問したり、ガイダンスを受けたりすることができます。この新しいフォーラムを利用すると、Box Developer Relationsチーム、同僚、Boxに関するエキスパートと直接会話できます。 **Source:** [https://ja.developer.box.com/changelog/2023-06-26-integration-mappings-guide](https://ja.developer.box.com/changelog/2023-06-26-integration-mappings-guide) --- ### StarterプランでBox Signを使用できるようになりました **Type:** changelog | **Section:** Changelog StarterプランでBox Signを使用できるようになりました Free、Personal Pro、StarterプランでBox Signを使用できるようになりました。 # StarterプランでBox Signを使用できるようになりました Free、Personal Pro、Starterプランで[Box Sign](g://box-sign)を使用できるようになりました。 ## サポート情報 問題がある場合やさらにガイドが必要な場合は、必要なサポートについて、Boxの[Developer Forum](https://support.box.com/hc/en-us/sections/360009473734-Box-Partner-Resources)に英語でリクエストを投稿してください。 **Source:** [https://ja.developer.box.com/changelog/2022-08-29-box-sign-available-for-starter](https://ja.developer.box.com/changelog/2022-08-29-box-sign-available-for-starter) --- ### Task (Assignment) APIのレスポンスの変更 **Type:** changelog | **Section:** Changelog Task (Assignment) APIのレスポンスの変更 タスクを取得エンドポイントおよびタスク割り当てを取得エンドポイントのAPIレスポンスの更新がリリースされました。 この変更の前は、有効なタスクID… # Task (Assignment) APIのレスポンスの変更 [タスクを取得](endpoint://get-tasks-id)エンドポイントおよび[タスク割り当てを取得](endpoint://get-task-assignments-id)エンドポイントのAPIレスポンスの更新がリリースされました。 この変更の前は、有効なタスクIDでタスクまたはタスク割り当てを取得する呼び出しを実行したときに、そのファイルが削除されているか、自分の権限が変更されてファイルを表示できなくなっていると、タスクがファイルとともに削除されたという404エラーが返されていました。 この新しい変更により、返されるレスポンスは404エラーレスポンスではなく、その項目が存在するものとする`null`レスポンスを持つタスクオブジェクトになります。 **Source:** [https://ja.developer.box.com/changelog/2019-04-15-changes-to-task-assignment-api-responses](https://ja.developer.box.com/changelog/2019-04-15-changes-to-task-assignment-api-responses) --- ### Tasks APIで新たにサポートされる値 **Type:** changelog | **Section:** Changelog Tasks APIで新たにサポートされる値 6月26日に、新しいタスクタイプである一般タスクのサポートが開始されました。タスクを作成または更新する際に、actionフィールドが、承認タスクの場合はreviewに、新しい一般タスクの場合はcomplete… # Tasks APIで新たにサポートされる値 6月26日に、新しいタスクタイプである一般タスクのサポートが開始されました。タスクを作成または更新する際に、`action`フィールドが、承認タスクの場合は`review`に、新しい一般タスクの場合は`complete`になります。 この変更は、タスク割り当ての更新時に使用できる値にも影響します。承認/レビュータスクを更新する場合、`resolution_state`を`incomplete`、`approved`、または`rejected`に設定できます。一般/完了タスクには、`incomplete`または`completed`の`resolution_state`を指定できます。 Tasks APIのレスポンスの本文内では、タスクに「一般」や「承認」という分類が付けられません。これは、BoxのUIでのみ反映されます。 ドキュメントは[こちら](endpoint://resources/task/)で参照できます。 **Source:** [https://ja.developer.box.com/changelog/2019-06-26-new-supported-values-in-tasks-api](https://ja.developer.box.com/changelog/2019-06-26-new-supported-values-in-tasks-api) --- ### Teams統合マッピング **Type:** changelog | **Section:** Changelog Teams統合マッピング MS Teamsの統合マッピング機能を使用して、Teamsのチャネルやチャットのコンテンツが保存されるBox内の場所を管理します。 すべてのTeams統合マッピングのリストを取得 新しいTeams統合マッピングを作成 既存のTeams… # Teams統合マッピング MS Teamsの[統合マッピング](r://integration-mapping-teams)機能を使用して、[Teamsのチャネルやチャットのコンテンツが保存されるBox内の場所](https://support.box.com/hc/en-us/articles/360050737154-Assigning-a-Default-Box-Folder-to-a-Teams-Channel-or-Chat)を管理します。 - すべてのTeams統合マッピングの[リストを取得](r://get-integration-mappings-teams) - 新しいTeams統合マッピングを[作成](r://post-integration-mappings-teams) - 既存のTeams統合マッピングを[更新](r://put-integration-mappings-teams-id) - Teams統合マッピングを[削除](r://delete-integration-mappings-teams-id) この機能の詳細については、Teams統合マッピングAPIの開発者向け[ガイド](g://integration-mappings/teams-mappings/index)を参照してください。 ## サポート情報 問題がある場合やさらにガイドが必要な場合は、必要なサポートについて、Boxの[Developer Forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum)に英語でリクエストを投稿してください。 **Source:** [https://ja.developer.box.com/changelog/2025-03-12-teams-integration-mappings](https://ja.developer.box.com/changelog/2025-03-12-teams-integration-mappings) --- ### TLS 1.0非推奨の完了 **Type:** changelog | **Section:** Changelog TLS 1.0非推奨の完了 2019年5月13日に、Box APIへのTLS 1.0リクエストを無効にするプロセスが開始されました。今後、すべてのTLS 1.0 APIリクエストが、API… # TLS 1.0非推奨の完了 2019年5月13日に、Box APIへのTLS 1.0リクエストを無効にするプロセスが開始されました。今後、すべてのTLS 1.0 APIリクエストが、APIコールの実行時に安全な接続を確立できなかったことを示すレスポンスを返します。 影響を受ける開発者には、これまで6～12か月にわたって複数のチャネルを通じて通知してきましたが、アプリケーションに影響がある場合は、BoxにAPIリクエストを再度送信できるようにシステムを更新する必要があります。 システムをTLS 1.2にアップグレードするには、TLS 1.0の公式サポート終了ガイドを参照してください。 質問や追加のサポートについては、[サポートチケットをお送りください](https://community.box.com/t5/custom/page/page-id/BoxSearchLithiumTKB)。 **Source:** [https://ja.developer.box.com/changelog/2019-05-15-tls-10-deprecated-complete](https://ja.developer.box.com/changelog/2019-05-15-tls-10-deprecated-complete) --- ### Users APIでマーカーベースのページ割りがサポート対象に **Type:** changelog | **Section:** Changelog Users APIでマーカーベースのページ割りがサポート対象に Users API… # Users APIでマーカーベースのページ割りがサポート対象に [Users API](e://get_users)で[マーカーベースのページ割り](g://api-calls/pagination/marker-based)がサポートされるようになりました。マーカーベースのページ割りとは、通常のオフセットベースのページ割りに代わるもので、多数のユーザーを有する会社のユーザーを取得する代替手段を提供します。 **Source:** [https://ja.developer.box.com/changelog/2019-12-05-marker-based-pagination-support-for-users-api](https://ja.developer.box.com/changelog/2019-12-05-marker-based-pagination-support-for-users-api) --- ### Webhookのレスポンスの更新 **Type:** changelog | **Section:** Changelog Webhookのレスポンスの更新 Webhookのレスポンスは、entriesの配列で適切なWebhook (Mini) オブジェクトを示すように更新されました。 # Webhookのレスポンスの更新 [Webhookのレスポンス](e://get-webhooks)は、entriesの配列で適切なWebhook (Mini) オブジェクトを示すように更新されました。 ## バグ修正 - [Webhook](e://resources/webhook--mini)用に`mini`リソースを追加 - [Webhookを取得](e://get-webhooks)のレスポンスオブジェクトを修正 **Source:** [https://ja.developer.box.com/changelog/2021-10-07-update-to-webhooks-response](https://ja.developer.box.com/changelog/2021-10-07-update-to-webhooks-response) --- ### Windows .NET SDK `v3.10.0`のリリース **Type:** changelog | **Section:** Changelog Windows .NET SDK v3.10.0のリリース メタデータカスケードポリシーの機能を追加 nuget.org/packages/Box.V2 nuget.org/packages/Box.V2.Core # Windows .NET SDK v3.10.0のリリース 1. メタデータカスケードポリシーの機能を追加 [`nuget.org/packages/Box.V2`](https://www.nuget.org/packages/Box.V2) [`nuget.org/packages/Box.V2.Core`](https://www.nuget.org/packages/Box.V2.Core/) **Source:** [https://ja.developer.box.com/changelog/2018-12-14-windows-net-sdk-v3100-release](https://ja.developer.box.com/changelog/2018-12-14-windows-net-sdk-v3100-release) --- ### Windows .NET SDK `v3.11.0`のリリース **Type:** changelog | **Section:** Changelog Windows .NET SDK v3.11.0のリリース より多くのグループフィールドの読み取りと書き込みのサポートを追加 共有リンクのUnsharedAtフィールドをnull… # Windows .NET SDK v3.11.0のリリース - より多くのグループフィールドの読み取りと書き込みのサポートを追加 - 共有リンクの`UnsharedAt`フィールドを`null`に設定できない問題を修正 - 新しいバージョンのアップロード時のファイル名の変更を修正 - ファイルバージョンのアップロード時にコンテンツ変更のタイムスタンプを設定する機能を追加 - ソース項目がウェブリンクの場合のイベントのソースの読み取りに関する問題を修正 [`nuget.org/packages/Box.V2/3.11.0`](https://www.nuget.org/packages/Box.V2/3.11.0) [`nuget.org/packages/Box.V2.Core/3.11.0`](https://www.nuget.org/packages/Box.V2.Core/3.11.0) **Source:** [https://ja.developer.box.com/changelog/2019-01-18-windows-net-sdk-v3110-release](https://ja.developer.box.com/changelog/2019-01-18-windows-net-sdk-v3110-release) --- ### Windows .NET SDK `v3.12.0`のリリース **Type:** changelog | **Section:** Changelog Windows .NET SDK v3.12.0のリリース ファイルのコラボレーションのコレクション全体をページングできるようにclient.FilesManager.GetCollaborationsCollectionAsync()と非推奨のclient… # Windows .NET SDK v3.12.0のリリース - ファイルのコラボレーションのコレクション全体をページングできるように`client.FilesManager.GetCollaborationsCollectionAsync()`と非推奨の`client.FilesManager.GetCollaborationsAsync()`を追加 - `client.WebLinksManager.CopyAsync()`、`client.WebLinksManager.CreateSharedLinkAsync()`、および`client.WebLinksManager.DeleteSharedLinkAsync()`を追加 - ユーザーのアバター画像を取得するための`client.UsersManager.GetUserAvatarAsync()`を追加 [`nuget.org/packages/Box.V2/3.12.0`](https://www.nuget.org/packages/Box.V2/3.12.0) [`nuget.org/packages/Box.V2.Core/3.12.0`](https://www.nuget.org/packages/Box.V2.Core/3.12.0) **Source:** [https://ja.developer.box.com/changelog/2019-02-08-windows-net-sdk-v3120-release](https://ja.developer.box.com/changelog/2019-02-08-windows-net-sdk-v3120-release) --- ### Windows .NET SDK `v3.13.0`のリリース **Type:** changelog | **Section:** Changelog Windows .NET SDK v3.13.0のリリース BoxCollaborationオブジェクトに.InviteEmailプロパティを追加。このプロパティは、保留中のコラボレーションで招待されたユーザーのメールアドレスを表示します。 BoxUser… # Windows .NET SDK v3.13.0のリリース - `BoxCollaboration`オブジェクトに`.InviteEmail`プロパティを追加。このプロパティは、保留中のコラボレーションで招待されたユーザーのメールアドレスを表示します。 - `BoxUser`オブジェクトに`.Timezone`、`.IsExternalCollabRestricted`、`.Tags`、および`.Hostname`プロパティを追加 [`nuget.org/packages/Box.V2/3.13.0`](https://www.nuget.org/packages/Box.V2/3.13.0) [`nuget.org/packages/Box.V2.Core/3.13.0`](https://www.nuget.org/packages/Box.V2.Core/3.13.0) **Source:** [https://ja.developer.box.com/changelog/2019-02-14-windows-net-sdk-v3130-release](https://ja.developer.box.com/changelog/2019-02-14-windows-net-sdk-v3130-release) --- ### Windows .NET SDK `v3.13.1`のリリース **Type:** changelog | **Section:** Changelog Windows .NET SDK v3.13.1のリリース イベントに関連した一部のオブジェクトで.IdプロパティがJSONから正しく逆シリアル化されていない問題を修正 nuget.org/packages/Box.V2/3.13.1 nuget.org/packages/Box… # Windows .NET SDK v3.13.1のリリース - イベントに関連した一部のオブジェクトで`.Id`プロパティがJSONから正しく逆シリアル化されていない問題を修正 [`nuget.org/packages/Box.V2/3.13.1`](https://www.nuget.org/packages/Box.V2/3.13.1) [`nuget.org/packages/Box.V2.Core/3.13.1`](https://www.nuget.org/packages/Box.V2.Core/3.13.1) **Source:** [https://ja.developer.box.com/changelog/2019-02-21-windows-net-sdk-v3131-release](https://ja.developer.box.com/changelog/2019-02-21-windows-net-sdk-v3131-release) --- ### Windows .NET SDK `v3.14.0`のリリース **Type:** changelog | **Section:** Changelog Windows .NET SDK v3.14.0のリリース APIレスポンスの例外メッセージにトレースIDが追加されました。 変換されたタスク割り当てステータスの逆シリアル化を修正 nuget.org/packages/Box.V2/3.14.0 nuget.org… # Windows .NET SDK v3.14.0のリリース - APIレスポンスの例外メッセージにトレースIDが追加されました。 - 変換されたタスク割り当てステータスの逆シリアル化を修正 [`nuget.org/packages/Box.V2/3.14.0`](https://www.nuget.org/packages/Box.V2/3.14.0) [`nuget.org/packages/Box.V2.Core/3.14.0`](https://www.nuget.org/packages/Box.V2.Core/3.14.0) **Source:** [https://ja.developer.box.com/changelog/2019-03-01-windows-net-sdk-v3140-release](https://ja.developer.box.com/changelog/2019-03-01-windows-net-sdk-v3140-release) --- ### Windows .NET SDK `v3.14.1`のリリース **Type:** changelog | **Section:** Changelog Windows .NET SDK v3.14.1のリリース サンプルファイルから不要なpackage.configが削除されました。 nuget.org/packages/Box.V2/3.14.1 nuget.org/packages/Box.V2.Core/3.14.1 # Windows .NET SDK v3.14.1のリリース - サンプルファイルから不要な`package.config`が削除されました。 [`nuget.org/packages/Box.V2/3.14.1`](https://www.nuget.org/packages/Box.V2/3.14.1) [`nuget.org/packages/Box.V2.Core/3.14.1`](https://www.nuget.org/packages/Box.V2.Core/3.14.1) **Source:** [https://ja.developer.box.com/changelog/2019-03-07-windows-net-sdk-v3141-release](https://ja.developer.box.com/changelog/2019-03-07-windows-net-sdk-v3141-release) --- ### Windows .NET SDK `v3.15.0`のリリース **Type:** changelog | **Section:** Changelog Windows .NET SDK v3.15.0のリリース カスタムIBoxServiceをBoxJWTAuthコンストラクタに渡すためのサポートが追加されました。 nuget.org/packages/Box.V2/3.15.0 nuget.org/packages/Box.V… # Windows .NET SDK v3.15.0のリリース - カスタム`IBoxService`を`BoxJWTAuth`コンストラクタに渡すためのサポートが追加されました。 [`nuget.org/packages/Box.V2/3.15.0`](https://www.nuget.org/packages/Box.V2/3.15.0) [`nuget.org/packages/Box.V2.Core/3.15.0`](https://www.nuget.org/packages/Box.V2.Core/3.15.0) **Source:** [https://ja.developer.box.com/changelog/2019-03-28-windows-net-sdk-v3150-release](https://ja.developer.box.com/changelog/2019-03-28-windows-net-sdk-v3150-release) --- ### Windows .NET SDK `v3.16.0`のリリース **Type:** changelog | **Section:** Changelog Windows .NET SDK v3.16.0のリリース 並べ替え順を制御するためにsortおよびdirectionパラメータをclient.SearchManager.SearchAsync()に追加 返されるサムネイル形式を制御するためにextension… # Windows .NET SDK v3.16.0のリリース - 並べ替え順を制御するために`sort`および`direction`パラメータを`client.SearchManager.SearchAsync()`に追加 - 返されるサムネイル形式を制御するために`extension`パラメータを`client.FilesManager.GetThumbnailAsync()`に追加 (`@guilmori`に感謝します)。 - クエリ文字列パラメータが正しくエンコードされなかったバグを修正 - メタデータのキーと値を設定し、指定されたキーの既存の値を上書きする`SetFileMetadataAsync()`および`SetFolderMetadataAsync()`メソッドが`client.MetadataManager`に追加されました。 - APIが一時的なエラーステータスコードで応答した場合にほとんどのAPIコールを自動的に再試行 [`nuget.org/packages/Box.V2/3.16.0`](https://www.nuget.org/packages/Box.V2/3.16.0) [`nuget.org/packages/Box.V2.Core/3.16.0`](https://www.nuget.org/packages/Box.V2.Core/3.16.0) **Source:** [https://ja.developer.box.com/changelog/2019-04-29-windows-net-sdk-v3160-release](https://ja.developer.box.com/changelog/2019-04-29-windows-net-sdk-v3160-release) --- ### Windows .NET SDK `v3.17.0`のリリース **Type:** changelog | **Section:** Changelog Windows .NET SDK v3.17.0のリリース イベントと検索のエンドポイントのクエリパラメータでの日付のエンコードを修正 FilesManager.DownloadStreamAsync… # Windows .NET SDK v3.17.0のリリース - イベントと検索のエンドポイントのクエリパラメータでの日付のエンコードを修正 - `FilesManager.DownloadStreamAsync()`のサポートを終了し、バイトオフセットに適切なパラメータ型が設定された後継のメソッド`FilesManager.DownloadAsync()`を導入 [`nuget.org/packages/Box.V2/3.17.0`](https://www.nuget.org/packages/Box.V2/3.17.0) [`nuget.org/packages/Box.V2.Core/3.17.0`](https://www.nuget.org/packages/Box.V2.Core/3.17.0) **Source:** [https://ja.developer.box.com/changelog/2019-05-09-windows-net-sdk-v3170-release](https://ja.developer.box.com/changelog/2019-05-09-windows-net-sdk-v3170-release) --- ### Windows .NET SDK `v3.18.0`のリリース **Type:** changelog | **Section:** Changelog Windows .NET SDK v3.18.0のリリース 詳細については、変更ログを参照してください。コミット: v3.17.0...v3.18.0 nuget.org/packages/Box.V2/3.18.0 nuget.org/packages/Box.V2.Core… # Windows .NET SDK v3.18.0のリリース 詳細については、[変更ログ](https://github.com/box/box-windows-sdk-v2/blob/master/CHANGELOG.md#3180)を参照してください。コミット: [`v3.17.0...v3.18.0`](https://github.com/box/box-windows-sdk-v2/compare/%60v3.17.0...v3.18.0%60) [`nuget.org/packages/Box.V2/3.18.0`](https://www.nuget.org/packages/Box.V2/3.18.0) [`nuget.org/packages/Box.V2.Core/3.18.0`](https://www.nuget.org/packages/Box.V2.Core/3.18.0) **Source:** [https://ja.developer.box.com/changelog/2019-06-20-windows-net-sdk-v3180-release](https://ja.developer.box.com/changelog/2019-06-20-windows-net-sdk-v3180-release) --- ### Windows .NET SDK `v3.19.0`のリリース **Type:** changelog | **Section:** Changelog Windows .NET SDK v3.19.0のリリース 詳細については、変更ログを参照してください。コミット: v3.18.0...v3.19.0 nuget.org/packages/Box.V2/3.19.0 nuget.org/packages/Box.V2.Core… # Windows .NET SDK v3.19.0のリリース 詳細については、[変更ログ](https://github.com/box/box-windows-sdk-v2/blob/master/CHANGELOG.md#3190)を参照してください。コミット: [`v3.18.0...v3.19.0`](https://github.com/box/box-windows-sdk-v2/compare/%60v3.18.0...v3.19.0%60) [`nuget.org/packages/Box.V2/3.19.0`](https://www.nuget.org/packages/Box.V2/3.19.0) [`nuget.org/packages/Box.V2.Core/3.19.0`](https://www.nuget.org/packages/Box.V2.Core/3.19.0) **Source:** [https://ja.developer.box.com/changelog/2019-08-29-windows-net-sdk-v3190-release](https://ja.developer.box.com/changelog/2019-08-29-windows-net-sdk-v3190-release) --- ### Windows .NET SDK `v3.20.0`のリリース **Type:** changelog | **Section:** Changelog Windows .NET SDK v3.20.0のリリース 詳細については、変更ログを参照してください。コミット: v3.19.0...v3.20.0 nuget.org/packages/Box.V2/3.20.0 nuget.org/packages/Box.V2.Core… # Windows .NET SDK v3.20.0のリリース 詳細については、[変更ログ](https://github.com/box/box-windows-sdk-v2/blob/master/CHANGELOG.md#3200)を参照してください。コミット: [`v3.19.0...v3.20.0`](https://github.com/box/box-windows-sdk-v2/compare/%60v3.19.0...v3.20.0%60) [`nuget.org/packages/Box.V2/3.20.0`](https://www.nuget.org/packages/Box.V2/3.20.0) [`nuget.org/packages/Box.V2.Core/3.20.0`](https://www.nuget.org/packages/Box.V2.Core/3.20.0) **Source:** [https://ja.developer.box.com/changelog/2019-09-19-windows-net-sdk-v3200-release](https://ja.developer.box.com/changelog/2019-09-19-windows-net-sdk-v3200-release) --- ### Windows .NET SDK `v3.21.0`のリリース **Type:** changelog | **Section:** Changelog Windows .NET SDK v3.21.0のリリース 詳細については、変更ログを参照してください。コミット: v3.20.0...v3.21.0 nuget.org/packages/Box.V2/3.21.0 nuget.org/packages/Box.V2.Core… # Windows .NET SDK v3.21.0のリリース 詳細については、[変更ログ](https://github.com/box/box-windows-sdk-v2/blob/master/CHANGELOG.md#3210)を参照してください。コミット: [`v3.20.0...v3.21.0`](https://github.com/box/box-windows-sdk-v2/compare/%60v3.20.0...v3.21.0%60) [`nuget.org/packages/Box.V2/3.21.0`](https://www.nuget.org/packages/Box.V2/3.21.0) [`nuget.org/packages/Box.V2.Core/3.21.0`](https://www.nuget.org/packages/Box.V2.Core/3.21.0) **Source:** [https://ja.developer.box.com/changelog/2019-12-06-windows-net-sdk-v3210-release](https://ja.developer.box.com/changelog/2019-12-06-windows-net-sdk-v3210-release) --- ### Windows .NET SDK `v3.22.0`のリリース **Type:** changelog | **Section:** Changelog Windows .NET SDK v3.22.0のリリース 詳細については、変更ログを参照してください。コミット: v3.21.0...v3.22.0 nuget.org/packages/Box.V2/3.22.0 nuget.org/packages/Box.V2.Core… # Windows .NET SDK v3.22.0のリリース 詳細については、[変更ログ](https://github.com/box/box-windows-sdk-v2/blob/master/CHANGELOG.md#3220-2020-02-25)を参照してください。コミット: [`v3.21.0...v3.22.0`](https://github.com/box/box-windows-sdk-v2/compare/%60v3.21.0...v3.22.0%60) [`nuget.org/packages/Box.V2/3.22.0`](https://www.nuget.org/packages/Box.V2/3.22.0) [`nuget.org/packages/Box.V2.Core/3.22.0`](https://www.nuget.org/packages/Box.V2.Core/3.22.0) **Source:** [https://ja.developer.box.com/changelog/2020-02-25-windows-net-sdk-v3220-release](https://ja.developer.box.com/changelog/2020-02-25-windows-net-sdk-v3220-release) --- ### Windows .NET SDK `v3.23.0`のリリース **Type:** changelog | **Section:** Changelog Windows .NET SDK v3.23.0のリリース 詳細については、変更ログを参照してください。コミット: v3.22.0...v3.23.0 nuget.org/packages/Box.V2/3.23.0 nuget.org/packages/Box.V2.Core… # Windows .NET SDK v3.23.0のリリース 詳細については、[変更ログ](https://github.com/box/box-windows-sdk-v2/blob/master/CHANGELOG.md#3230-2020-05-12)を参照してください。コミット: [`v3.22.0...v3.23.0`](https://github.com/box/box-windows-sdk-v2/compare/%60v3.22.0...v3.23.0%60) [`nuget.org/packages/Box.V2/3.23.0`](https://www.nuget.org/packages/Box.V2/3.23.0) [`nuget.org/packages/Box.V2.Core/3.23.0`](https://www.nuget.org/packages/Box.V2.Core/3.23.0) **Source:** [https://ja.developer.box.com/changelog/2020-05-12-windows-net-sdk-v3230-release](https://ja.developer.box.com/changelog/2020-05-12-windows-net-sdk-v3230-release) --- ### Windows .NET SDK `v3.4.1`のリリース **Type:** changelog | **Section:** Changelog Windows .NET SDK v3.4.1のリリース 許可されたコラボレーションドメインのサポートを追加。イベントタイプ列挙型を追加。BoxRepresentationStatusでの逆シリアル化の問題を修正 nuget.org/packages/Box.V2/3.4.… # Windows .NET SDK v3.4.1のリリース [許可されたコラボレーションドメイン](https://developer.box.com/reference/resources/collaboration-allowlist-entry/)のサポートを追加。イベントタイプ列挙型を追加。`BoxRepresentationStatus`での逆シリアル化の問題を修正 [`nuget.org/packages/Box.V2/3.4.1`](https://www.nuget.org/packages/Box.V2/3.4.1) [`nuget.org/packages/Box.V2.Core/3.4.1`](https://www.nuget.org/packages/Box.V2.Core/3.4.1) **Source:** [https://ja.developer.box.com/changelog/2018-01-10-windows-net-sdk-v341-release](https://ja.developer.box.com/changelog/2018-01-10-windows-net-sdk-v341-release) --- ### Windows .NET SDK `v3.4.2`のリリース **Type:** changelog | **Section:** Changelog Windows .NET SDK v3.4.2のリリース NuSpecファイルのBox SDKバージョンを更新し、Box V2およびBox V2.Coreの依存関係の問題を修正しました。 nuget.org/packages/Box.V2/3.4.2 nuget.org… # Windows .NET SDK v3.4.2のリリース `NuSpec`ファイルのBox SDKバージョンを更新し、`Box V2`および`Box V2.Core`の依存関係の問題を修正しました。 [`nuget.org/packages/Box.V2/3.4.2`](https://www.nuget.org/packages/Box.V2/3.4.2) [`nuget.org/packages/Box.V2.Core/3.4.2`](https://www.nuget.org/packages/Box.V2.Core/3.4.2) **Source:** [https://ja.developer.box.com/changelog/2018-01-31-windows-net-sdk-v342-release](https://ja.developer.box.com/changelog/2018-01-31-windows-net-sdk-v342-release) --- ### Windows .NET SDK `v3.5.1`のリリース **Type:** changelog | **Section:** Changelog Windows .NET SDK v3.5.1のリリース SDKがレート制限またはサーバーエラーレスポンスを受信したときに指数バックオフに切り替えられました。 Box APIへの接続のセキュリティを強化するため、可能な場合はTLS v1.… # Windows .NET SDK v3.5.1のリリース - SDKがレート制限またはサーバーエラーレスポンスを受信したときに指数バックオフに切り替えられました。 - Box APIへの接続のセキュリティを強化するため、可能な場合はTLS `v1.1`以上のサポートを強制します。 - ローカルのクロックとBoxサーバーのクロックが一致しない場合、およびJWT IDがすでに使用されている場合にJWT認証で変更された再試行を実行します。 - `RestoreTrashedAsync()`の`name`パラメータが省略可能になりました。 [`nuget.org/packages/Box.V2/3.5.1`](https://www.nuget.org/packages/Box.V2/3.5.1) [`nuget.org/packages/Box.V2.Core/3.5.1`](https://www.nuget.org/packages/Box.V2.Core/3.5.1) **Source:** [https://ja.developer.box.com/changelog/2018-03-15-windows-net-sdk-v351-release](https://ja.developer.box.com/changelog/2018-03-15-windows-net-sdk-v351-release) --- ### Windows .NET SDK `v3.5.2`のリリース **Type:** changelog | **Section:** Changelog Windows .NET SDK v3.5.2のリリース .NET Coreパッケージを修正 nuget.org/packages/Box.V2/3.5.2 nuget.org/packages/Box.V2.Core/3.5.2 # Windows .NET SDK v3.5.2のリリース .NET Coreパッケージを修正 [`nuget.org/packages/Box.V2/3.5.2`](https://www.nuget.org/packages/Box.V2/3.5.2) [`nuget.org/packages/Box.V2.Core/3.5.2`](https://www.nuget.org/packages/Box.V2.Core/3.5.2) **Source:** [https://ja.developer.box.com/changelog/2018-03-21-windows-net-sdk-v352-release](https://ja.developer.box.com/changelog/2018-03-21-windows-net-sdk-v352-release) --- ### Windows .NET SDK `v3.6.0`のリリース **Type:** changelog | **Section:** Changelog Windows .NET SDK v3.6.0のリリース 変更ログ nuget.org/packages/Box.V2/3.6.0 nuget.org/packages/Box.V2.Core # Windows .NET SDK v3.6.0のリリース [変更ログ](https://github.com/box/box-windows-sdk-v2/blob/master/CHANGELOG.md#360) [`nuget.org/packages/Box.V2/3.6.0`](https://www.nuget.org/packages/Box.V2/3.6.0) [`nuget.org/packages/Box.V2.Core`](https://www.nuget.org/packages/Box.V2.Core) **Source:** [https://ja.developer.box.com/changelog/2018-03-27-windows-net-sdk-v360-release](https://ja.developer.box.com/changelog/2018-03-27-windows-net-sdk-v360-release) --- ### Windows .NET SDK `v3.7.0`のリリース **Type:** changelog | **Section:** Changelog Windows .NET SDK v3.7.0のリリース メタデータテンプレートにリテンションポリシーを割り当てるためのサポートを追加 列挙型にCONTENT_ACCESSイベントタイプを追加 nuget.org/packages/Box.V2/3.7.0 nuget.org… # Windows .NET SDK v3.7.0のリリース 1. メタデータテンプレートにリテンションポリシーを割り当てるためのサポートを追加 2. 列挙型に`CONTENT_ACCESS`イベントタイプを追加 [`nuget.org/packages/Box.V2/3.7.0`](https://www.nuget.org/packages/Box.V2/3.7.0) [`nuget.org/packages/Box.V2.Core/3.7.0`](https://www.nuget.org/packages/Box.V2.Core/3.7.0) **Source:** [https://ja.developer.box.com/changelog/2018-04-11-windows-net-sdk-v370-release](https://ja.developer.box.com/changelog/2018-04-11-windows-net-sdk-v370-release) --- ### Windows .NET SDK `v3.8.0`のリリース **Type:** changelog | **Section:** Changelog Windows .NET SDK v3.8.0のリリース ユーザーがXamarinにBoxClientを作成できない問題を修正 イベントのBoxLockオブジェクトにファイルプロパティを追加 メタデータテンプレートを削除するためのMetadataManager… # Windows .NET SDK v3.8.0のリリース - ユーザーが`Xamarin`に`BoxClient`を作成できない問題を修正 - イベントの`BoxLock`オブジェクトにファイルプロパティを追加 - メタデータテンプレートを削除するための`MetadataManager.DeleteMetadataTemplate(string scope, string template)`を追加 - `BoxConfig`でAPI URLが変更可能に - APIレスポンスエラーオブジェクト/メッセージを改善 [`nuget.org/packages/Box.V2/3.8.0`](https://www.nuget.org/packages/Box.V2/3.8.0) [`nuget.org/packages/Box.V2.Core/3.8.0`](https://www.nuget.org/packages/Box.V2.Core/3.8.0) **Source:** [https://ja.developer.box.com/changelog/2018-04-30-windows-net-sdk-v380-release](https://ja.developer.box.com/changelog/2018-04-30-windows-net-sdk-v380-release) --- ### Windows .NET SDK `v3.9.0`のリリース **Type:** changelog | **Section:** Changelog Windows .NET SDK v3.9.0のリリース ストレージポリシーのサポートを追加 nuget.org/packages/Box.V2/3.9.0 nuget.org/packages/Box.V2.Core/3.9.0 # Windows .NET SDK v3.9.0のリリース - ストレージポリシーのサポートを追加 [`nuget.org/packages/Box.V2/3.9.0`](https://www.nuget.org/packages/Box.V2/3.9.0) [`nuget.org/packages/Box.V2.Core/3.9.0`](https://www.nuget.org/packages/Box.V2.Core/3.9.0) **Source:** [https://ja.developer.box.com/changelog/2018-05-10-windows-net-sdk-v390-release](https://ja.developer.box.com/changelog/2018-05-10-windows-net-sdk-v390-release) --- ### Windows .NET SDK `v3.9.1`のリリース **Type:** changelog | **Section:** Changelog Windows .NET SDK v3.9.1のリリース Xamarinアプリケーションの接続が切れるバグが修正されました。 nuget.org/packages/Box.V2/3.9.1 nuget.org/packages/Box.V2.Core/3.9.1 # Windows .NET SDK v3.9.1のリリース Xamarinアプリケーションの接続が切れるバグが修正されました。 [`nuget.org/packages/Box.V2/3.9.1`](https://www.nuget.org/packages/Box.V2/3.9.1) [`nuget.org/packages/Box.V2.Core/3.9.1`](https://www.nuget.org/packages/Box.V2.Core/3.9.1) **Source:** [https://ja.developer.box.com/changelog/2018-06-07-windows-net-sdk-v391-release](https://ja.developer.box.com/changelog/2018-06-07-windows-net-sdk-v391-release) --- ### Windows .NET SDK `v3.9.2`のリリース **Type:** changelog | **Section:** Changelog Windows .NET SDK v3.9.2のリリース コラボレータの招待をフォルダの所有者以外に許可するフラグの設定のサポートが追加されました。 nuget.org/packages/Box.V2/3.9.2 nuget.org/packages/Box.V2.Core/… # Windows .NET SDK v3.9.2のリリース 1. コラボレータの招待をフォルダの所有者以外に許可するフラグの設定のサポートが追加されました。 [`nuget.org/packages/Box.V2/3.9.2`](https://www.nuget.org/packages/Box.V2/3.9.2) [`nuget.org/packages/Box.V2.Core/3.9.2`](https://www.nuget.org/packages/Box.V2.Core/3.9.2) **Source:** [https://ja.developer.box.com/changelog/2018-06-14-windows-net-sdk-v392-release](https://ja.developer.box.com/changelog/2018-06-14-windows-net-sdk-v392-release) --- ### Windows .NET SDK `v3.9.3`のリリース **Type:** changelog | **Section:** Changelog Windows .NET SDK v3.9.3のリリース アセンブリに厳密な名前付け nuget.org/packages/Box.V2/3.9.3 nuget.org/packages/Box.V2.Core/3.9.3 # Windows .NET SDK v3.9.3のリリース - アセンブリに厳密な名前付け [`nuget.org/packages/Box.V2/3.9.3`](https://www.nuget.org/packages/Box.V2/3.9.3) [`nuget.org/packages/Box.V2.Core/3.9.3`](https://www.nuget.org/packages/Box.V2.Core/3.9.3) **Source:** [https://ja.developer.box.com/changelog/2018-09-04-windows-net-sdk-v393-release](https://ja.developer.box.com/changelog/2018-09-04-windows-net-sdk-v393-release) --- ### アプリケーションに影響を及ぼす可能性があるBox APIレスポンスヘッダーの変更 **Type:** changelog | **Section:** Changelog アプリケーションに影響を及ぼす可能性があるBox APIレスポンスヘッダーの変更 日本時間2021年5月11日に、インフラストラクチャの継続的なアップグレードの一環として、BoxのAPIレスポンスヘッダーが業界のベストプラクティスとAPIドキュメントに従って標準化され、常に小文字で返されるようになります。 この変更は、以下の影響を及ぼす可能性があります。 Salesforce SDK v1のユーザーは、影響を受けるため、最新のSDKバージョンにアップグレードする必要があります。アップグレードしなかった場合、2021年5月10日を過ぎると、Box Salesforce統合は機能しなくなります。 Box APIのユーザーで、Box SDKのいずれも使用していない場合は影響を受ける可能性があるため、コード全体でヘッダーの使用状況を確認する必要があります。ヘッダーの使用状況によっては、調整しないと、Box API統合で中断が生じる可能性があります。 影響を受ける可能性があるユーザーとアプリケーション管理者全員に、メールで直接通知済みです。 # アプリケーションに影響を及ぼす可能性があるBox APIレスポンスヘッダーの変更 日本時間2021年5月11日に、インフラストラクチャの継続的なアップグレードの一環として、BoxのAPIレスポンスヘッダーが業界のベストプラクティスとAPIドキュメントに従って標準化され、常に小文字で返されるようになります。 この変更は、以下の影響を及ぼす可能性があります。 - [Salesforce SDK `v1`](https://github.com/box/box-salesforce-sdk/releases/tag/1.0.0)のユーザーは、影響を受けるため、最新のSDKバージョンにアップグレードする必要があります。アップグレードしなかった場合、2021年5月10日を過ぎると、Box Salesforce統合は機能しなくなります。 - Box APIのユーザーで、[Box SDK](https://developer.box.com/sdks-and-tools/)のいずれも使用していない場合は影響を受ける可能性があるため、コード全体でヘッダーの使用状況を確認する必要があります。ヘッダーの使用状況によっては、調整しないと、Box API統合で中断が生じる可能性があります。 影響を受ける可能性があるユーザーとアプリケーション管理者全員に、メールで直接通知済みです。 ## 変更の概要 上記のリターンヘッダー (`location`や`retry-after`など) を使用しているアプリケーションでは、そのアプリケーションが大文字小文字を区別せずにこれらのヘッダーをチェックしているかを確認することが必要になります。この1年間で、Boxは自社のネットワークおよび可観測性のインフラストラクチャをアップグレードしてきました。このようなアップグレードでは、お客様のためにBoxの製品の信頼性と利用可能性の向上を目標としています。この具体的な変更により、Boxは、更新されたサービスプロキシを展開できるようになるため、サービストラフィックの監視強化、問題点の迅速な特定、アプリケーションパフォーマンスのチューニングを実現できます。 ## APIをご利用の場合: アプリケーションへの影響の確認 使用するアプリケーションが影響を受けるかどうかを確認するには、コードのレビューが必要になります。Box公式SDKのいずれかをBox APIへの接続だけに使用している場合は影響を受けません。SDKでは、大文字小文字を区別せずにレスポンスヘッダーが処理されるためです。 影響を受けているかどうかを確認するには、以下の手順に従います。 - Box APIリクエストからのレスポンスを処理するアプリケーションコードを特定します。これらのレスポンスからレスポンスヘッダーを抽出しなければ、影響を受けることはありません。 - このようなレスポンスヘッダーを抽出する場合、ヘッダーの大文字小文字を区別する必要があると、影響を受ける可能性があります。 たとえば、`Location`ヘッダーの先頭が大文字`L`で返されること (つまり、特定の文字による文字列の直接比較) を想定している場合は、変更後に中断されないようにコードを修正する必要があります。 ## APIをご利用の場合: 変更方法 影響を受けるアプリケーションを更新するには、これらのレスポンスヘッダーを確認する際に大文字小文字を区別しないようにしてください。具体的には、ヘッダー (`Location`など) が送信される際に先頭が大文字`L`でも小文字`l`でも同様に処理されるよう、慎重にコードを作成する必要があります。たとえば、このプロセスを処理するための2つの方法として、確認する前にすべてのヘッダーを強制的に小文字にするか、大文字小文字を区別しない正規表現による文字列チェックを使用することができます。 ## Salesforce SDK v1をご利用の場合: アプリケーションへの影響の確認 Box Salesforce SDKの`v1.0`を使用しているかどうかわからない場合は、アプリケーションコード内で、Box Salesforce SDKを格納している場所に移動し、以下の手順を実行します。 次のSalesforce SDKファイルを読み込む: `src/classes/BoxApiRequest.cls` 以下の行 ([6～7行目](https://github.com/box/box-salesforce-sdk/compare/1.0.0...v1.1.0#diff-1855f83ffd4977e5b9e4bfc167154f2e11b0161fd6c380502c48082b6837b0af)) を探す。 ``` public final static String HEADER_LOCATION_LOWER_CASE = 'location'; public final static String HEADER_LOCATION_CAPITALIZED = 'Location'; ``` 上記の行が存在する場合は、使用しているSalesforce SDKは`v1.1.0`以降です。この場合は影響を受けず、変更も必要ありません。上記の行が存在しない場合、使用しているSalesforce SDKは`v1.0`です。この場合は影響を受けるため、更新する必要があります。 ## Salesforce SDK v1をご利用の場合: 変更方法 影響を受けるアプリケーションを更新するには、使用しているSalesforce SDKのバージョンを更新する必要があります。[最新バージョン](https://github.com/box/box-salesforce-sdk)のSDKへのアップグレードをお勧めしますが、アプリケーションに影響がないようにするには、[`v1.1.0`以降](https://github.com/box/box-salesforce-sdk/releases)であればどれでも十分です。 ## サポート情報 問題がある場合やさらにガイドが必要な場合は、必要なサポートについて、Boxサポートチームに[チケットを申請](https://support.box.com/hc/en-us/requests/new)するか、Boxの[Developer Forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum)に英語でリクエストを投稿してください。 **Source:** [https://ja.developer.box.com/changelog/2021-02-05-box-api-response-header-changes](https://ja.developer.box.com/changelog/2021-02-05-box-api-response-header-changes) --- ### アプリケーション向けのPlatformインサイト **Type:** changelog | **Section:** Changelog アプリケーション向けのPlatformインサイト 管理者と共同管理者は、Platformインサイトのダッシュボードを使用して、組織におけるアプリケーション関連の情報を含むプラットフォームの利用状況を集約できるようになりました。Platformインサイトでは、APIコール数や、まだ有効になっていない、または承認されていないアプリケーションの数を確認できます。さらに、企業で最も使用されているアプリも確認できます。 詳細については、アプリケーションとPlatformインサイトに関するドキュメントを参照してください。 # アプリケーション向けのPlatformインサイト 管理者と共同管理者は、Platformインサイトのダッシュボードを使用して、組織におけるアプリケーション関連の情報を含むプラットフォームの利用状況を集約できるようになりました。Platformインサイトでは、APIコール数や、まだ有効になっていない、または承認されていないアプリケーションの数を確認できます。さらに、企業で最も使用されているアプリも確認できます。 詳細については、[アプリケーション](g://applications)と[Platformインサイト](https://support.box.com/hc/en-us/articles/20738406915219-Platform-Insights)に関するドキュメントを参照してください。 ## サポート情報 問題がある場合やさらにガイドが必要な場合は、必要なサポートについて、Boxの[Developer Forum](https://forum.box.com/)に英語でリクエストを投稿してください。 **Source:** [https://ja.developer.box.com/changelog/2023-10-03-platform-insights](https://ja.developer.box.com/changelog/2023-10-03-platform-insights) --- ### アプリと統合の命名規則の変更 **Type:** changelog | **Section:** Changelog アプリと統合の命名規則の変更 Box Platformの明確さと一貫性の改善のため、アプリと統合の命名規則を変更しました。 開発者 旧名称 新名称 場所 App Center 公開 Box統合のカタログに公開するためにPlatformアプリを送信するタブ 統合 Boxウェブ統合 Boxウェブアプリ内にサードパーティ製アプリケーションのボタンを定義するタブ カスタムアプリ Platformアプリ 開発者コンソール # アプリと統合の命名規則の変更 Box Platformの明確さと一貫性の改善のため、アプリと統合の命名規則を変更しました。 ## 開発者 | 旧名称 | 新名称 | 場所 | | --- | --- | --- | | App Center | 公開 | Box統合のカタログに公開するためにPlatformアプリを送信するタブ | | 統合 | Boxウェブ統合 | Boxウェブアプリ内にサードパーティ製アプリケーションのボタンを定義するタブ | | カスタムアプリ | Platformアプリ | 開発者コンソール | ## 管理者 | 旧名称 | 新名称 | 場所 | | --- | --- | --- | | アプリ | 統合 | 管理コンソール | | カスタムアプリマネージャ | Platformアプリマネージャ | 管理コンソール | | カスタムアプリ | Platformアプリ | 管理コンソール | ## Box Shield | 旧名称 | 新名称 | 場所 | | --- | --- | --- | | アプリケーションの制限ポリシー | 統合の制限 | 制限ポリシー | | Shieldのアプリケーション | Shieldの統合 | Shieldの統合一覧 | | アプリケーション | 統合 | 検出ルール | ## ユーザー | 旧名称 | 新名称 | 場所 | | --- | --- | --- | | アプリ | 統合 | Boxウェブアプリのタブ | ## サポート情報 問題がある場合やさらにガイドが必要な場合は、必要なサポートについて、Boxの[Developer Forum](https://forum.box.com/)に英語でリクエストを投稿してください。 **Source:** [https://ja.developer.box.com/changelog/2024-11-12-naming-change-apps-integrations](https://ja.developer.box.com/changelog/2024-11-12-naming-change-apps-integrations) --- ### アプリ項目の関連付け **Type:** changelog | **Section:** Changelog アプリ項目の関連付け アプリ項目の関連付けAPIを使用すると、特定のファイルまたはフォルダと関連があるアプリ項目を確認できます。これには、当該ファイルまたはフォルダの先祖に関連付けられているアプリ項目も含まれます。 # アプリ項目の関連付け [アプリ項目の関連付けAPI](r://app-item-association)を使用すると、特定のファイルまたはフォルダと関連があるアプリ項目を確認できます。これには、当該ファイルまたはフォルダの先祖に関連付けられているアプリ項目も含まれます。 [アプリ項目](r://app-item)とは、アプリケーションが所有するコンテンツオブジェクトです。さまざまなパスからファイルやフォルダをまとめてグループ化でき、そのセットは、コラボレーションを利用して共有できます。 [アプリ項目の関連付け](r://app-item-associations)とは、ファイルやフォルダとアプリ項目のつながりです。フォルダとアプリ項目の関連付けは、そのフォルダのすべての子孫にカスケードされます。 ## サポート情報 問題がある場合やさらにガイドが必要な場合は、必要なサポートについて、Boxの[Developer Forum](https://forum.box.com/)に英語でリクエストを投稿してください。 **Source:** [https://ja.developer.box.com/changelog/2024-09-16-app-item-associations](https://ja.developer.box.com/changelog/2024-09-16-app-item-associations) --- ### イベントAPIで分類の名前フィールドが追加 **Type:** changelog | **Section:** Changelog イベントAPIで分類の名前フィールドが追加 コンテンツに分類が存在する場合、イベントAPIにより、レスポンスオブジェクトで分類のnameフィールドが返されるようになりました。 # イベントAPIで分類の名前フィールドが追加 コンテンツに分類が存在する場合、[イベント](e://get-events/)APIにより、レスポンスオブジェクトで分類の`name`フィールドが返されるようになりました。 - イベントソースのレスポンスオブジェクトの更新については、[こちら](e://resources/event-source/)を参照してください。 - ユーザーソースおよびイベントソースによってトリガーされるイベントの例を紹介するために新しい[ガイドページ](g://events/event-triggers/event-source)が追加されました。 機能強化前と機能強化後のレスポンスの例を以下に示します。分類が存在しない場合は機能強化前の例が返されることに注意してください。 機能強化前: ``` { "source": { "item_type": "file", "item_id": "8903212345", "item_name": "example.docx", "parent": { "type": "folder", "name": "All Files", "id": "0" }, "owned_by": { "type": "user", "id": "11446498", "name": "Aaron Levie", "login": "notifications@example.com" } } } ``` 機能強化後: ``` { "source": { "item_type": "file", "item_id": "8903212345", "item_name": "example.docx", "parent": { "type": "folder", "name": "All Files", "id": "0" }, "owned_by": { "type": "user", "id": "11446498", "name": "Aaron Levie", "login": "notifications@example.com" }, "classification": { "name": "Top Secret" } } } ``` ## サポート情報 問題がある場合やさらにガイドが必要な場合は、必要なサポートについて、Boxの[Developer Forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum)に英語でリクエストを投稿してください。 **Source:** [https://ja.developer.box.com/changelog/2021-09-01-classification-name-field-now-in-events](https://ja.developer.box.com/changelog/2021-09-01-classification-name-field-now-in-events) --- ### ウェブアプリ統合でのサーバー側の処理のサポート終了 **Type:** changelog | **Section:** Changelog ウェブアプリ統合でのサーバー側の処理のサポート終了 日本時間12月2日に、OAuth 2.0ウェブアプリ統合で、事前コールバックのURLまたはサーバー側統合を作成するためのオプションを利用できなくなりました。 # ウェブアプリ統合でのサーバー側の処理のサポート終了 日本時間12月2日に、OAuth 2.0ウェブアプリ統合で、事前コールバックのURLまたはサーバー側統合を作成するためのオプションを利用できなくなりました。 ## 今後の手順 アプリケーションでサーバー側統合を構成済みの場合は、引き続き動作します。この機能の使用を停止するか、設定を調整する場合は、[こちらのドキュメント](https://cloud.app.box.com/file/958463673555?s=uwk4jvanbofom2ckvk9q0wcnkc2vxqdy)で回避策とサポートについてご確認ください。 ウェブアプリ統合の詳細については、[ガイド](g://applications/web-app-integrations/)を参照してください。 ## サポート情報 問題がある場合やさらにガイドが必要な場合は、必要なサポートについて、Boxの[Developer Forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum)に英語でリクエストを投稿してください。 **Source:** [https://ja.developer.box.com/changelog/2022-12-01-server-server-service-action-eol](https://ja.developer.box.com/changelog/2022-12-01-server-server-service-action-eol) --- ### ウェブアプリ統合ドキュメントの改善 **Type:** changelog | **Section:** Changelog ウェブアプリ統合ドキュメントの改善 開発者コンソールからの情報をすべて反映するよう、カスタムアプリを使用したウェブアプリ統合の作成に関するドキュメントを更新しました。 # ウェブアプリ統合ドキュメントの改善 開発者コンソールからの情報をすべて反映するよう、カスタムアプリを使用した[ウェブアプリ統合](g://applications/web-app-integrations/configure)の作成に関するドキュメントを更新しました。 ## 更新内容 - **アプリ情報**セクションのすべての要素に説明を追加しました。 - パラメータの構文に関する情報で**コールバックパラメータ**セクションを拡張しました。 ## サポート情報 問題がある場合やさらにガイドが必要な場合は、Boxの[Developer Forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum)に英語でリクエストを投稿してください。 **Source:** [https://ja.developer.box.com/changelog/2022-06-30-improvements-in-web-app-integrations-documentation](https://ja.developer.box.com/changelog/2022-06-30-improvements-in-web-app-integrations-documentation) --- ### カスタムアプリの承認フローの改善 **Type:** changelog | **Section:** Changelog カスタムアプリの承認フローの改善 カスタムアプリの承認フローをさらに改善しました。その結果、開発者コンソールの新しい [有効化] タブを使用して、Box管理者に対してOAuth 2.0カスタムアプリを有効化するよう直接リクエストできるようになりました。 さらに、Box… # カスタムアプリの承認フローの改善 カスタムアプリの承認フローをさらに改善しました。その結果、開発者コンソールの新しい [**有効化**] タブを使用して、Box管理者に対してOAuth 2.0カスタムアプリを有効化するよう直接リクエストできるようになりました。 さらに、Box管理者は、管理コンソールでカスタムアプリマネージャを使用して、カスタムアプリを表示および有効化できます。 ## 更新内容 - OAuth 2.0カスタムアプリ用の [**有効化**] タブを追加 - [カスタムアプリの承認](g://authorization/custom-app-approval)ページにOAuth2.0カスタムアプリケーションの有効化に関する情報を追加 - [カスタムアプリの承認](g://authorization/custom-app-approval)および[OAuth 2.0を使用した設定](g://authentication/oauth2/oauth2-setup)ページのスクリーンショットを更新 ## サポート情報 問題がある場合やさらにガイドが必要な場合は、必要なサポートについて、Boxの[Developer Forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum)に英語でリクエストを投稿してください。 **Source:** [https://ja.developer.box.com/changelog/2022-04-21-improvements-in-custom-apps-approval-flow](https://ja.developer.box.com/changelog/2022-04-21-improvements-in-custom-apps-approval-flow) --- ### カスタムアプリの詳細の追加 **Type:** changelog | **Section:** Changelog カスタムアプリの詳細の追加 カスタムアプリの目的を明確にし、企業に価値をもたらすため、カスタムアプリをより詳細に説明できる機能を追加しました。 OAuth、JWT、またはクライアント資格情報を使用してカスタムアプリを設定する際、アプリの目的と作成者を指定できます。また、アプリを外部システムと統合する場合は、統合のカテゴリを定義して外部システムの詳細を入力できます。 # カスタムアプリの詳細の追加 [カスタムアプリ](g://applications/app-types/platform-apps)の目的を明確にし、企業に価値をもたらすため、カスタムアプリをより詳細に説明できる機能を追加しました。 [OAuth](g://authentication/oauth2/oauth2-setup)、[JWT](g://authentication/jwt/jwt-setup)、または[クライアント資格情報](g://authentication/client-credentials/client-credentials-setup)を使用してカスタムアプリを設定する際、アプリの目的と作成者を指定できます。また、アプリを外部システムと統合する場合は、統合のカテゴリを定義して外部システムの詳細を入力できます。 ## サポート情報 問題がある場合やさらにガイドが必要な場合は、必要なサポートについて、Boxの[Developer Forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum)に英語でリクエストを投稿してください。 **Source:** [https://ja.developer.box.com/changelog/2023-04-17-new-custom-app-modal](https://ja.developer.box.com/changelog/2023-04-17-new-custom-app-modal) --- ### カスタムアプリ管理の新機能 **Type:** changelog | **Section:** Changelog カスタムアプリ管理の新機能 Box管理コンソールの [カスタムアプリマネージャ] セクションへの変更をリリースしました。これにより、カスタムOAuth2.0アプリケーションの有効化をより簡単に表示および管理できるようになります。 # カスタムアプリ管理の新機能 Box管理コンソールの [カスタムアプリマネージャ] セクションへの変更をリリースしました。これにより、カスタムOAuth2.0アプリケーションの有効化をより簡単に表示および管理できるようになります。 新しい機能の追加のほか、[カスタムアプリマネージャ] のUIも更新しました。Box APIを使用するアプリの変更および承認に関する詳細については、[ブログ](https://medium.com/box-developer-blog/custom-apps-manager-updates-c79ccf8ebe97)を参照してください。 ## 更新内容 - [承認](g://authorization)、[カスタムアプリの承認](g://authorization/custom-app-approval)、[アクセス制限付きアプリの承認](g://authorization/limited-access-approval)、[セキュリティ](g://security)ページのスクリーンショットを更新 - [カスタムアプリの承認](g://authorization/custom-app-approval)ページにOAuth2.0カスタムアプリケーションの承認プロセスに関する情報を追加 ## サポート情報 問題がある場合やさらにガイドが必要な場合は、必要なサポートについて、Boxの[Developer Forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum)に英語でリクエストを投稿してください。 **Source:** [https://ja.developer.box.com/changelog/2022-01-06-new-features-for-custom-app-management](https://ja.developer.box.com/changelog/2022-01-06-new-features-for-custom-app-management) --- ### クライアント資格情報許可による認証のお知らせ **Type:** changelog | **Section:** Changelog # クライアント資格情報許可による認証のお知らせ JWTアプリケーションの新しい認証方法がリリースされました。この新しい方法であるクライアント資格情報許可は、既存のアプリケーションに影響を及ぼすことはありませんが、新しいアプリに対してより簡単な認証方法を提供します。これまで、アプリケーションのIDを確認してアクセストークンを取得するために公開/秘密キーペアとアサーションが必要でしたが、クライアントIDとクライアントシークレットだけでトークンをリクエストできるようになりました。 ``` curl --location --request POST ‘https://api.box.com/oauth2/token’ \ --header ‘Content-Type: application/x-www-form-urlencoded’ \ --data-urlencode ‘client_id=<client_id>’ \ --data-urlencode ‘client_secret=<client_secret>’ \ --data-urlencode ‘grant_type=client_credentials’ \ --data-urlencode ‘box_subject_type=enterprise’ \ --data-urlencode ‘box_subject_id=<enterprise_id>’ ``` 詳細については、Boxの[ガイド](g://authentication/jwt/without-sdk/#client-credentials-grant)を参照してください。 ## 更新内容 - 新しいアプリケーション用の認証オプションとしてクライアント資格情報許可を追加しました - クライアントシークレットのコピー/表示に2要素認証の要件を追加しました - Enterpriseの承認リクエストに選択した認証方法を追加しました - 認証タイプを変更する機能を削除しました **Source:** [https://ja.developer.box.com/changelog/2020-11-17-client-credentials-grant](https://ja.developer.box.com/changelog/2020-11-17-client-credentials-grant) --- ### グループAPIで新しいフィルタと権限を追加 **Type:** changelog | **Section:** Changelog グループAPIで新しいフィルタと権限を追加 GET /groups APIでは、新しいfilter_termフィールドを使用して、名前でグループにフィルタをかけられるようになりました。 さらに、グループのすべてのエンドポイントにより、開発者は、新しいpermissions… # グループAPIで新しいフィルタと権限を追加 [`GET /groups`](e://get_groups) APIでは、新しい`filter_term`フィールドを使用して、名前でグループにフィルタをかけられるようになりました。 ``` curl -i -X GET "https://api.box.com/2.0/groups?filter_term=Engineering" \ -H "Authorization: Bearer <ACCESS_TOKEN>" ``` さらに、グループのすべてのエンドポイントにより、開発者は、新しい[`permissions`](r://group--full/#param-permissions)フィールドをリクエストできるようになりました。このフィールドには、現在、認証済みユーザーが任意の項目にグループを招待できるかどうかを定義する属性が1つあります。 ``` curl -i -X GET "https://api.box.com/2.0/groups?field=permissions" \ -H "Authorization: Bearer <ACCESS_TOKEN>" ``` ``` { "total_count": 1, "entries": [ { "type": "group", "id": "223353242", "permissions": { "can_invite_as_collaborator": true } } ], "limit": 100, "offset": 0 } ``` グループの操作方法の詳細については、[`Group API documentation`](e://get_groups)を参照してください。 **Source:** [https://ja.developer.box.com/changelog/2020-09-10-group-api-adds-new-filter-and-permissions](https://ja.developer.box.com/changelog/2020-09-10-group-api-adds-new-filter-and-permissions) --- ### クロスオリジンリソース共有 (CORS) ドキュメントの更新 **Type:** changelog | **Section:** Changelog クロスオリジンリソース共有 (CORS) ドキュメントの更新 クロスオリジンリソース共有 (CORS) に関するドキュメントを更新しました。 更新内容 Access-Control-Allow-Origin… # クロスオリジンリソース共有 (CORS) ドキュメントの更新 [クロスオリジンリソース共有 (CORS)](g://security/cors) に関するドキュメントを更新しました。 ## 更新内容 `Access-Control-Allow-Origin`ヘッダーの問題が発生した場合の対処方法の情報を追加しました。 ## サポート情報 問題がある場合やさらにガイドが必要な場合は、Boxの[Developer Forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum)に英語でリクエストを投稿してください。 **Source:** [https://ja.developer.box.com/changelog/2022-07-06-cors-issues](https://ja.developer.box.com/changelog/2022-07-06-cors-issues) --- ### クロスオリジンリソース共有 (CORS) ドキュメントの更新 **Type:** changelog | **Section:** Changelog クロスオリジンリソース共有 (CORS) ドキュメントの更新 クロスオリジンリソース共有 (CORS) に関するドキュメントを更新しました。 更新内容 Access-Control-Allow-Origin… # クロスオリジンリソース共有 (CORS) ドキュメントの更新 [クロスオリジンリソース共有 (CORS)](g://security/cors) に関するドキュメントを更新しました。 ## 更新内容 `Access-Control-Allow-Origin`ヘッダーの問題が発生した場合の対処方法の情報を追加しました。 ## サポート情報 問題がある場合やさらにガイドが必要な場合は、Boxの[開発者向けフォーラム](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum)に英語でリクエストを投稿してください。 **Source:** [https://ja.developer.box.com/changelog/2022-07-06-cors-documentation-update](https://ja.developer.box.com/changelog/2022-07-06-cors-documentation-update) --- ### コラボレーションで廃止されたフィールドを置き換え **Type:** changelog | **Section:** Changelog コラボレーションで廃止されたフィールドを置き換え 2018年に、新しいフィールドacceptance_requirements_statusがGETコラボレーション/ID APIエンドポイントに追加され、追加の通知ユースケースがサポートされるようになりました。このフィールドには、サービス利用規約、2要素認証、強力なパスワードの要件が含まれます。サービス利用規約の要件のみを含む既存のacceptance_requirementsフィールドは、新しいacceptance_requirements_statusに置き換えられました。 # コラボレーションで廃止されたフィールドを置き換え 2018年に、新しいフィールド`acceptance_requirements_status`がGETコラボレーション/ID APIエンドポイントに追加され、追加の通知ユースケースがサポートされるようになりました。このフィールドには、サービス利用規約、2要素認証、強力なパスワードの要件が含まれます。サービス利用規約の要件のみを含む既存の`acceptance_requirements`フィールドは、新しい`acceptance_requirements_status`に置き換えられました。 以前は、`GET /collaboration/<collaboration_id>?fields=acceptance_requirements`への呼び出しで以下のようなオブジェクトが返されていました。 ``` "acceptance_requirements": {     "terms_of_service": {         "type": "terms_of_service",         "id": <tos_id>     } } ``` 新しいフィールドを使用すると、リクエスト`GET /collaboration/<collaboration_id>?fields=acceptance_requirements_status`は以下を返します。 ``` "acceptance_requirements_status": { "terms_of_service_requirement": { "is_accepted": true, "terms_of_service": { "type": "terms_of_service", "id": <tos_id> } }, "strong_password_requirement": { "enterprise_has_strong_password_required_for_external_users": true, "user_has_strong_password": false }, "two_factor_authentication_requirement": { "enterprise_has_two_factor_auth_enabled": true, "user_has_two_factor_authentication_enabled" true } } ``` **Source:** [https://ja.developer.box.com/changelog/2019-05-31-replaced-obsolete-field-in-collaborations](https://ja.developer.box.com/changelog/2019-05-31-replaced-obsolete-field-in-collaborations) --- ### コラボレーションに未登録ユーザーを表示 **Type:** changelog | **Section:** Changelog コラボレーションに未登録ユーザーを表示 ファイルまたはフォルダのコラボレータとして未登録ユーザーが追加されている場合のために、コラボレーション戻りオブジェクトにフィールドinvite_emailが追加されました。現在返されるaccessible_byオブジェクトでは未登録ユーザーの結果としてnullが表示されることから、この変更が加えられました。新しいフィールドには、ユーザーの招待に使用されたメールアドレスが表示されます。 # コラボレーションに未登録ユーザーを表示 ファイルまたはフォルダのコラボレータとして未登録ユーザーが追加されている場合のために、コラボレーション戻りオブジェクトにフィールド`invite_email`が追加されました。現在返される`accessible_by`オブジェクトでは未登録ユーザーの結果として`null`が表示されることから、この変更が加えられました。新しいフィールドには、ユーザーの招待に使用されたメールアドレスが表示されます。 この変更は以下のエンドポイントに影響します。 - [コラボレーションを取得](endpoint://get-collaborations-id) - [ファイルコラボレーションを取得](endpoint://get-files-id-collaborations) - [フォルダコラボレーションを取得](endpoint://get-folders-id-collaborations) これまで、未登録ユーザーを含むコラボレーションオブジェクトは以下のように表示されていました。 ``` { "type": "collaboration", "id": "376164239", ..... "accessible_by": null ..... } ``` 今回の更新により、返されるオブジェクトは以下のように表示されます。 ``` { "type": "collaboration", "id": "376164239", ...... "accessible_by": null "invite_email": "sadfasdf@box.com", }, ...... } ``` **Source:** [https://ja.developer.box.com/changelog/2018-12-12-collaborations-now-show-unregistered-users](https://ja.developer.box.com/changelog/2018-12-12-collaborations-now-show-unregistered-users) --- ### コンテンツアクセスに関するEnterprise Eventの変更 **Type:** changelog | **Section:** Changelog コンテンツアクセスに関するEnterprise Eventの変更 本日以降、Enterprise Event Streamは、新しいコンテンツアクセスイベントの生成を開始します。 新しいCONTENT_ACCESS… # コンテンツアクセスに関するEnterprise Eventの変更 本日以降、[Enterprise Event Stream](g://events/enterprise-events/for-enterprise/)は、新しいコンテンツアクセスイベントの生成を開始します。 新しい`CONTENT_ACCESS`イベントは、ファイルに承認済みのユーザーがアクセスしたか、プログラムによってBoxアプリケーションがアクセスしたときにトリガーされます。 その他のイベントタイプの詳細については、[Enterprise Event](g://events/enterprise-events/for-enterprise/)に関するドキュメントを参照してください。 **Source:** [https://ja.developer.box.com/changelog/2020-07-16-change-to-enterprise-events-for-content-access](https://ja.developer.box.com/changelog/2020-07-16-change-to-enterprise-events-for-content-access) --- ### コンテンツエクスプローラのメタデータビュー **Type:** changelog | **Section:** Changelog コンテンツエクスプローラのメタデータビュー コンテンツエクスプローラで、メタデータクエリを使用してファイルやフォルダを検索できるメタデータビューを使用できるようになりました。データは埋め込みのビューに表示されます。 # コンテンツエクスプローラのメタデータビュー コンテンツエクスプローラで、メタデータクエリを使用してファイルやフォルダを検索できるメタデータビューを使用できるようになりました。データは埋め込みのビューに表示されます。 詳細については、[コンテンツエクスプローラのガイド](g://embed/ui-elements/explorer)とBoxの[ブログ記事](https://medium.com/box-developer-blog/metadata-view-in-box-content-explorer-4978e47e97e9)を参照してください。 ## サポート情報 問題がある場合やさらにガイドが必要な場合は、必要なサポートについて、Boxの[Developer Forum](https://forum.box.com/)に英語でリクエストを投稿してください。 **Source:** [https://ja.developer.box.com/changelog/2024-02-02-metadata-view-content-explorer](https://ja.developer.box.com/changelog/2024-02-02-metadata-view-content-explorer) --- ### コンテンツプレビューUI Elementの新しい注釈 **Type:** changelog | **Section:** Changelog コンテンツプレビューUI Elementの新しい注釈 コンテンツのプレビューエクスペリエンス向上のため、プレビューUI Element… # コンテンツプレビューUI Elementの新しい注釈 コンテンツのプレビューエクスペリエンス向上のため、プレビューUI Elementに新しい注釈の種類のサポートを追加しました。カスタムアプリケーションでコンテンツをプレビューするエンドユーザーは、テキストのハイライトや描画など、追加の注釈の種類を利用できるようになりました。すべての注釈はリアルタイムで同期されます。 ## サポート情報 問題がある場合やさらにガイドが必要な場合は、必要なサポートについて、Boxの[Developer Forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum)に英語でリクエストを投稿してください。 **Source:** [https://ja.developer.box.com/changelog/2022-10-19-annotations-in-preview](https://ja.developer.box.com/changelog/2022-10-19-annotations-in-preview) --- ### サンプルコードカタログのリリース **Type:** changelog | **Section:** Changelog サンプルコードカタログのリリース Box Developerドキュメントポータルでサンプルコードカタログv1.0.… # サンプルコードカタログのリリース Box Developerドキュメントポータルで[サンプルコードカタログ](https://developer.box.com/sample-code/)`v1.0.0`が利用可能になりました。さまざまなプログラミング言語のコードサンプルを閲覧し、カテゴリ別にフィルタできます。 ## サポート情報 問題がある場合やさらにガイドが必要な場合は、必要なサポートについて、Boxの[Developer Forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum)に英語でリクエストを投稿してください。 **Source:** [https://ja.developer.box.com/changelog/2023-02-08-sample-code-catalog-released](https://ja.developer.box.com/changelog/2023-02-08-sample-code-catalog-released) --- ### シンプルになったアプリ作成フロー **Type:** changelog | **Section:** Changelog シンプルになったアプリ作成フロー 新しくシンプルになったアプリ作成フローがBox開発者コンソールで使用できるようになりました。アプリケーションには、カスタムアプリ、アクセス制限付きアプリ、Box Custom Skillの3種類があります。 Box… # シンプルになったアプリ作成フロー 新しくシンプルになったアプリ作成フローがBox[開発者コンソール](https://app.box.com/developers/console)で使用できるようになりました。アプリケーションには、カスタムアプリ、アクセス制限付きアプリ、Box Custom Skillの3種類があります。 Boxでは、各種アプリを選択するタイミングを正確に説明するための平易な言葉と、選択に役立つ追加情報が必要な方のために関連するドキュメントへのリンクを追加しました。アプリケーションの種類の選択によって、使用できる認証方法に影響があります。 中でも注目すべきは、Boxの新しいアプリの種類であるアクセス制限付きアプリです。このアプリの種類は、[Box View](g://embed/box-view/)を使用したり、別のアプリケーション内でBoxのプレビューサービスを使用したりする場合に選択してください。この種類で利用できるのは、[APIの機能が制限されている](g://authentication/app-token/endpoints/)[アプリトークン認証](g://authentication/app-token/)のみです。詳細については、アプリの種類の選択に関する[ガイド](g://applications/app-types/select/)を参照してください。 **Source:** [https://ja.developer.box.com/changelog/2020-11-09-simplified-app-creation-flow](https://ja.developer.box.com/changelog/2020-11-09-simplified-app-creation-flow) --- ### タスクに関するEnterprise Eventの変更 **Type:** changelog | **Section:** Changelog タスクに関するEnterprise Eventの変更 本日以降、Enterprise Event Streamは、新しいタスクとタスク割り当てイベントの生成を開始します。一部の既存のタスクイベントでは追加のフィールドが返されます。 # タスクに関するEnterprise Eventの変更 本日以降、[Enterprise Event Stream](g://events/enterprise-events/for-enterprise/)は、新しいタスクとタスク割り当てイベントの生成を開始します。一部の既存のタスクイベントでは追加のフィールドが返されます。 ## 新しいイベント - タスクが更新されると、新しい`TASK_UPDATE`イベントがトリガーされます - ユーザーからタスクの割り当てが解除されると、新しい`TASK_ASSIGNMENT_DELETE`イベントがトリガーされます ## 更新されたイベント ### TASK_CREATEの変更 タスクが作成されたときに、このイベントでは、タスクのID (`task.id`)、タスクを作成したユーザーのID (`task.created_by.id`)、タスクの説明 (`task.message`)、およびタスクの期日 (`task.due_date`、省略可) が`additional_details`オブジェクト内に含まれるようになりました。 ``` "additional_details": { "task": { "id": "1234567", "due_at": "2020-07-06T10:49:44-07:00", "message": "task description", "created_by": { "id": 123456, "login": "email@example.com" }, ... } } ``` ### TASK_ASSIGNMENT_CREATEおよびTASK_ASSIGNMENT_UPDATEの変更 タスク割り当てが作成または更新されたときに、このイベントでは、タスクのID (`task.id`)、タスクを割り当てられたユーザーのID (`task_assignment.assigned_to.id`) とそのログイン (`task_assignment.assigned_to.login`)、タスクの説明 (`task.message`)、およびタスクの期日 (`task.due_date`、省略可) が`additional_details`オブジェクト内に含まれるようになりました。 ``` "additional_details": { "task": { "id": "1234567", "created_by": { "id": 12345, "login": "email@example.com" } }, "task_assignment": { "assigned_to": { "id": 12346, "login": "email+2@example.com" }, "status": "NOT_STARTED", "message": "assignee message" }, ... } ``` その他のイベントタイプの詳細については、[Enterprise Event](g://events/enterprise-events/for-enterprise/)に関するドキュメントを参照してください。 **Source:** [https://ja.developer.box.com/changelog/2020-06-11-change-to-enterprise-events-for-tasks](https://ja.developer.box.com/changelog/2020-06-11-change-to-enterprise-events-for-tasks) --- ### タスクの新しい`completion_rule`フィールド **Type:** changelog | **Section:** Changelog タスクの新しいcompletion_ruleフィールド タスクオブジェクトcompletion_rule… # タスクの新しいcompletion_ruleフィールド タスクオブジェクト`completion_rule`内で省略可能な新しいフィールドを使用できるようになりました。このフィールドは、[タスクを作成](endpoint://post-tasks)エンドポイントと[タスクを更新](endpoint://put-tasks-id)エンドポイントの使用時に設定でき、標準の[タスクオブジェクト](endpoint://resources/task/)の一部として返されます。 このフィールドの目的は、ユーザーの関与状況に基づいて、タスクが完了となる条件を設定することです。完了ルール`all_assignees`(デフォルト)を使用して作成されたタスクは、すべての担当者が作業を完了したときにのみ完了と見なされます。完了ルール`any_assignee`を使用して作成されたタスクは、1人の担当者が作業を完了すると完了と見なされます。 **Source:** [https://ja.developer.box.com/changelog/2019-09-11-new-completion_rule-field-for-tasks](https://ja.developer.box.com/changelog/2019-09-11-new-completion_rule-field-for-tasks) --- ### デフォルトのAIの構成の取得と上書き **Type:** changelog | **Section:** Changelog デフォルトのAIの構成の取得と上書き GET /2.0/ai_agent_defaultエンドポイントにより、AIサービスのデフォルトの構成を取得できるようになりました。 # デフォルトのAIの構成の取得と上書き [`GET /2.0/ai_agent_default`](e://get_ai_agent_default)エンドポイントにより、AIサービスのデフォルトの構成を取得できるようになりました。 構成の詳細を取得したら、[`POST /2.0/ai/ask`](e://post_ai_ask#param_ai_agent)および[`POST /2.0/ai/text_gen`](e://post_ai_text_gen#param_ai_agent)リクエストで利用可能な`ai_agent`パラメータを使用して構成を上書きできます。 ## サポート情報 問題がある場合やさらにガイドが必要な場合は、必要なサポートについて、Boxの[Developer Forum](https://forum.box.com/)に英語でリクエストを投稿してください。 **Source:** [https://ja.developer.box.com/changelog/2024-07-25-box-ai-overrides](https://ja.developer.box.com/changelog/2024-07-25-box-ai-overrides) --- ### トークン無効化のための新しいセキュリティ強化 **Type:** changelog | **Section:** Changelog トークン無効化のための新しいセキュリティ強化 トークン無効化エンドポイントの機能が強化され、ダウンスコープされたトークンを有効期限が切れる前に無効化できるようになりました。この更新の前は、/revoke… # トークン無効化のための新しいセキュリティ強化 [トークン無効化](endpoint://post-oauth2-revoke/)エンドポイントの機能が強化され、[ダウンスコープされたトークン](g://authentication/tokens/downscope)を有効期限が切れる前に無効化できるようになりました。この更新の前は、/revokeエンドポイントを使用して、完全スコープのアクセストークンのみ無効化することができました。この新しい拡張機能により、完全スコープのアクセストークンに加えて、ダウンスコープされたトークンも無効化できるようになりました。 詳細については[こちら](https://medium.com/box-developer-blog/new-security-enhancements-for-revoking-access-tokens-79b9960a7ce2)を参照してください。 **Source:** [https://ja.developer.box.com/changelog/2019-09-18-new-security-enhancements-for-token-revocation](https://ja.developer.box.com/changelog/2019-09-18-new-security-enhancements-for-token-revocation) --- ### ファイルAPIを使用したリテンションポリシーの拡張 **Type:** changelog | **Section:** Changelog ファイルAPIを使用したリテンションポリシーの拡張 すでにリテンションの対象となっているファイルの保持期間を、新しいdisposition_atフィールドを使用して延長できるようになりました。日付を延長した場合は、元に戻すことも、新しい日付より前の日付に更新することもできません。 # ファイルAPIを使用したリテンションポリシーの拡張 すでにリテンションの対象となっているファイルの保持期間を、新しい`disposition_at`フィールドを使用して延長できるようになりました。日付を延長した場合は、元に戻すことも、新しい日付より前の日付に更新することもできません。 ## 更新内容 - [ファイル (Full) リソース](e://resources/file--full/#param-disposition_at)に`disposition_at`フィールドを追加 - [PUTファイルエンドポイント](e://put-files-id/#param-disposition_at)に`disposition_at`パラメータを追加 - [ガイドのリテンションポリシーセクション](g://retention-policies/#extend-retention-for-a-file)に注記を追加 ## サポート情報 問題がある場合やさらにガイドが必要な場合は、必要なサポートについて、Boxの[Developer Forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum)に英語でリクエストを投稿してください。 **Source:** [https://ja.developer.box.com/changelog/2021-11-03-extend-retention-via-files-api](https://ja.developer.box.com/changelog/2021-11-03-extend-retention-via-files-api) --- ### ファイルおよびファイルバージョンに新しい`uploader_display_name`を追加 **Type:** changelog | **Section:** Changelog ファイルおよびファイルバージョンに新しいuploader_display_nameを追加 新しいフィールドuploader_display_nameがファイルリソースとファイルバージョンリソースの両方に追加されました。このフィールドでは、アップロード時にユーザーの名前を指定します。 # ファイルおよびファイルバージョンに新しいuploader_display_nameを追加 新しいフィールド`uploader_display_name`がファイルリソースとファイルバージョンリソースの両方に追加されました。このフィールドでは、アップロード時にユーザーの名前を指定します。 ``` { ... "uploader_display_name": "Ellis Wiggins" } ``` このフィールドをファイルおよびファイルバージョンのエンドポイントのいずれかでリクエストするには、`fields`クエリパラメータを指定します。以下に例を示します。 ``` curl -X GET https://api.box.com/2.0/files/12345?fields=uploader_display_name \ -H 'Authorization: Bearer <ACCESS_TOKEN>' ``` ログアウトした匿名ユーザーがファイルをアップロードすると、そのユーザーのメールアドレスが返されます。使用可能なメールアドレスがない場合、このフィールドはデフォルトで`Someone`というテキストが設定されます。 **Source:** [https://ja.developer.box.com/changelog/2020-04-23-add-new-uploader_display_name-field-to-file-and-file-versions](https://ja.developer.box.com/changelog/2020-04-23-add-new-uploader_display_name-field-to-file-and-file-versions) --- ### ファイルサイズの上限の更新 **Type:** changelog | **Section:** Changelog ファイルサイズの上限の更新 本日、Boxの新しいBusinessプランとしてEnterprise Plusプランをリリースしました。このプランでは、最大150 GB… # ファイルサイズの上限の更新 本日、Boxの新しいBusinessプランとしてEnterprise Plusプランをリリースしました。このプランでは、最大150 GBのアップロードとダウンロードをサポートします。また、以下のとおり、一部の既存プランでもファイルサイズの上限をアップグレードしました。ご利用のアカウントのファイルサイズの上限を確認する方法については、[アップロードに関するガイド](g://uploads/direct)を参照してください。 ## 更新内容 - Enterprise: 50 GB - Digital Workplace Suite: 50 GB - Digital Workplace Global Suite: 50 GB - Digital Business Suite: 50 GB - Digital Business Global Suite: 50 GB - Enterprise Plus: 150 GB **Source:** [https://ja.developer.box.com/changelog/2021-07-16-updated-file-size-limits](https://ja.developer.box.com/changelog/2021-07-16-updated-file-size-limits) --- ### ファイルのアップロードAPIの更新 **Type:** changelog | **Section:** Changelog ファイルのアップロードAPIの更新 ファイルのアップロードAPIとダウンスコープされたトークンを使用してファイルをアップロードする際にセキュリティの脆弱性が生じる可能性があることを受け、親フォルダIDが見つかっても、リクエスト送信者にアクセス権限がない場合に、40… # ファイルのアップロードAPIの更新 [ファイルのアップロードAPI](g://uploads/direct)とダウンスコープされたトークンを使用してファイルをアップロードする際にセキュリティの脆弱性が生じる可能性があることを受け、親フォルダIDが見つかっても、リクエスト送信者にアクセス権限がない場合に、404エラーを返すようにファイルのアップロードAPIを更新します。 # サポート情報 問題がある場合やさらにガイドが必要な場合は、必要なサポートについて、Boxの[Developer Forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum)に英語でリクエストを投稿してください。 **Source:** [https://ja.developer.box.com/changelog/2023-04-25-upload-api-update](https://ja.developer.box.com/changelog/2023-04-25-upload-api-update) --- ### ファイルの最大アップロードサイズの増加 **Type:** changelog | **Section:** Changelog ファイルの最大アップロードサイズの増加 以下のBoxアカウントプランで、APIを介してアップロードできる最大ファイルサイズが増加しました。 # ファイルの最大アップロードサイズの増加 以下のBoxアカウントプランで、APIを介してアップロードできる最大ファイルサイズが増加しました。 - Business Plus - Enterprise - Digital Workplace Suite - Digital Workplace Global Suite これまで、これらのアカウントの最大アップロードサイズは**5 GB**でした。このアップデートにより、最大ファイルサイズが**15 GB**に増加し、すぐに有効になります。 すべてのアカウントの最大ファイルサイズの詳細については、[直接アップロード](g://uploads/direct/)を参照してください。 **Source:** [https://ja.developer.box.com/changelog/2021-01-25-maximum-upload-file-size-limit-increases](https://ja.developer.box.com/changelog/2021-01-25-maximum-upload-file-size-limit-increases) --- ### ファイルの新しい`classification`フィールド **Type:** changelog | **Section:** Changelog ファイルの新しいclassificationフィールド Fieldオブジェクト内で、省略可能な新しいフィールドclassificationが使用できるようになりました。このフィールドは、現在ファイルに適用されている分類を表します。 # ファイルの新しいclassificationフィールド `Field`オブジェクト内で、省略可能な新しいフィールド`classification`が使用できるようになりました。このフィールドは、現在ファイルに適用されている分類を表します。 分類は、[ファイル情報の取得](endpoint://get-files-id)など、ファイルを返す任意のエンドポイントを介してリクエストでき、[追加`fields`のリクエスト](g://api-calls/request-extra-fields)をサポートします。 ``` { "id": "123456789", "type": "file", "etag": "1", "classification": {        "name": "Top Secret",        "definition": "Content that should not be shared outside the company.", "color": "#FF0000" }, ... } ``` 分類は、APIまたはBox Shieldを介して設定することも、ユーザーがウェブアプリケーションを使用して設定することもできます。 **Source:** [https://ja.developer.box.com/changelog/2020-04-23-new-classification-field-for-files](https://ja.developer.box.com/changelog/2020-04-23-new-classification-field-for-files) --- ### ファイルバージョンに新しいフィールドを追加 **Type:** changelog | **Section:** Changelog ファイルバージョンに新しいフィールドを追加 ファイルバージョンオブジェクト内で、省略可能な新しいフィールドtrashed_by、restored_by、およびrestored_at… # ファイルバージョンに新しいフィールドを追加 ファイルバージョンオブジェクト内で、省略可能な新しいフィールド`trashed_by`、`restored_by`、および`restored_at` が使用できるようになりました。 このフィールドは、標準の[ファイルバージョンオブジェクト](endpoint://resources/file-version/)の一部として返されます。 このフィールドの目的は、いつ、誰がファイルバージョンをごみ箱に移動したり、ごみ箱から出したりしたかを把握しやすくすることです。 **Source:** [https://ja.developer.box.com/changelog/2019-10-25-new-fields-for-file-versions](https://ja.developer.box.com/changelog/2019-10-25-new-fields-for-file-versions) --- ### フォルダを更新エンドポイントおよびフォルダ情報の取得エンドポイントに新しいフィールドを追加 **Type:** changelog | **Section:** Changelog フォルダを更新エンドポイントおよびフォルダ情報の取得エンドポイントに新しいフィールドを追加 フォルダを更新APIエンドポイントのis_collaboration_restricted_to_enterpriseに、… # フォルダを更新エンドポイントおよびフォルダ情報の取得エンドポイントに新しいフィールドを追加 [フォルダを更新APIエンドポイント](endpoint://put-folders-id)の`is_collaboration_restricted_to_enterprise`に、2つのメジャーリリースが追加されました。これは、将来のコラボレーションをEnterprise内のみに制限するかどうかを設定するために作成されるブール値です。既存のコラボレーションには影響しません。このフィールドの値は、[フォルダ情報の取得エンドポイント](endpoint://get-folders-id)を呼び出したときにも表示されます。 **Source:** [https://ja.developer.box.com/changelog/2018-08-21-add-new-fields-to-folder-update-and-get-info-endpoints](https://ja.developer.box.com/changelog/2018-08-21-add-new-fields-to-folder-update-and-get-info-endpoints) --- ### ベータリリースの導入: 新世代のPython SDK **Type:** changelog | **Section:** Changelog ベータリリースの導入: 新世代のPython SDK 最新世代 (現在はベータ版) のBox Python SDKをリリースしました。これは、開発者エクスペリエンスを向上させ、Boxコンテンツクラウドとの統合を効率化することを目的としています。 新世代のPython SDK… # ベータリリースの導入: 新世代のPython SDK [最新世代 (現在はベータ版) のBox Python SDK](https://github.com/box/box-python-sdk-gen)をリリースしました。これは、開発者エクスペリエンスを向上させ、Boxコンテンツクラウドとの統合を効率化することを目的としています。 [新世代のPython SDK](https://github.com/box/box-python-sdk-gen)では、以下を利用できるようになります。 - **APIの全面的なサポート**: 新世代のBox SDKにより、開発者はBox APIエコシステム全体をカバーできるようになります。Boxが提供する最新機能をすべて利用できるようになったため、より高性能で機能豊富なアプリケーションを作成できます。 - **迅速なAPIの更新**: 新しいBox APIがSDKに組み込まれるのを待つ必要はなくなります。Boxでは、自動生成による新しい開発アプローチにより、はるかに速いペースで (数日中に) 新しいBox APIをSDKに追加できるようになりました。これは、最新の機能をすぐにアプリケーションで利用できるようになることを意味します。 - **ドキュメントへの埋め込み**: Boxでは、開発者にとって情報へのアクセスが重要であることを理解しています。新しいアプローチを使用して、すべてのオブジェクトおよびパラメータに関する包括的なドキュメントをSDKのソースコードに直接含めました。つまり、この情報を開発者向けポータルで探す必要がなくなるため、時間の節約と開発プロセスの効率化につながります。 - **便利なメソッドの強化**: 開発エクスペリエンスを強化するBoxの取り組みにより、便利なメソッドの導入が推進されます。このようなメソッドは、認証、分割アップロード、指数バックオフ、自動再試行、型チェック (変数を正しく使用しているかどうかの確認に役立ちます) など、さまざまな側面をカバーします。 新世代のBox SDKを利用して、Boxコンテンツクラウドの可能性を最大限に引き出してください。より迅速かつ効率的に革新的なソリューションを作成しましょう。 **Source:** [https://ja.developer.box.com/changelog/2023-09-29-box-python-sdk-new-gen-released](https://ja.developer.box.com/changelog/2023-09-29-box-python-sdk-new-gen-released) --- ### ベータリリースの導入: 新世代のTypeScript SDK **Type:** changelog | **Section:** Changelog ベータリリースの導入: 新世代のTypeScript SDK 最新世代 (現在はベータ版) のBox Typescript SDKをリリースしました。これは、開発者エクスペリエンスを向上させ、Box… # ベータリリースの導入: 新世代のTypeScript SDK [最新世代 (現在はベータ版) のBox Typescript SDK](https://github.com/box/box-typescript-sdk-gen)をリリースしました。これは、開発者エクスペリエンスを向上させ、Boxコンテンツクラウドとの統合を効率化することを目的としています。 [新世代のTypescript SDK](https://github.com/box/box-typescript-sdk-gen)では、以下を利用できるようになります。 - **APIの全面的なサポート**: 新世代のBox SDKにより、開発者はBox APIエコシステム全体をカバーできるようになります。Boxが提供する最新機能をすべて利用できるようになったため、より高性能で機能豊富なアプリケーションを作成できます。 - **迅速なAPIの更新**: 新しいBox APIがSDKに組み込まれるのを待つ必要はなくなります。Boxでは、自動生成による新しい開発アプローチにより、はるかに速いペースで (数日中に) 新しいBox APIをSDKに追加できるようになりました。これは、最新の機能をすぐにアプリケーションで利用できるようになることを意味します。 - **ドキュメントへの埋め込み**: Boxでは、開発者にとって情報へのアクセスが重要であることを理解しています。新しいアプローチを使用して、すべてのオブジェクトおよびパラメータに関する包括的なドキュメントをSDKのソースコードに直接含めました。つまり、この情報を開発者向けポータルで探す必要がなくなるため、時間の節約と開発プロセスの効率化につながります。 - **便利なメソッドの強化**: 開発エクスペリエンスを強化するBoxの取り組みにより、便利なメソッドの導入が推進されます。このようなメソッドは、認証、分割アップロード、指数バックオフ、自動再試行、型チェック (変数を正しく使用しているかどうかの確認に役立ちます) など、さまざまな側面をカバーします。 新世代のBox SDKを利用して、Boxコンテンツクラウドの可能性を最大限に引き出してください。より迅速かつ効率的に革新的なソリューションを作成しましょう。 **Source:** [https://ja.developer.box.com/changelog/2023-09-29-box-node-sdk-new-generation-released](https://ja.developer.box.com/changelog/2023-09-29-box-node-sdk-new-generation-released) --- ### メタデータAPIへの重大な変更 **Type:** changelog | **Section:** Changelog メタデータAPIへの重大な変更 2018年3月29日に、メタデータAPIエンドポイントのレスポンス本文に新しいデータ型 (文字列の配列) が導入されます。この変更は、BoxのメタデータテンプレートにmultiSelectという新しいフィールドタイプを追加するために行われます。この新しいフィールドタイプは、ファイルまたはフォルダにテンプレートインスタンスを作成する際の、複数の値を選択するためのチェックボックスタイプを表します。このフィールドタイプでは、選択されたオプションが文字列の配列に格納されます。この配列内の各文字列が、選択されたmultiSelectオプションのキーに対応します。 # メタデータAPIへの重大な変更 2018年3月29日に、メタデータAPIエンドポイントのレスポンス本文に新しいデータ型 (文字列の配列) が導入されます。この変更は、Boxのメタデータテンプレートに`multiSelect`という新しいフィールドタイプを追加するために行われます。この新しいフィールドタイプは、ファイルまたはフォルダにテンプレートインスタンスを作成する際の、複数の値を選択するためのチェックボックスタイプを表します。このフィールドタイプでは、選択されたオプションが文字列の配列に格納されます。この配列内の各文字列が、選択された`multiSelect`オプションのキーに対応します。 以下にメタデータテンプレートのJSONレスポンス本文の例を示します。キー`audience1`の値は、この変更で導入される新しいデータ型 (文字列の配列) の例を示しています。 ``` { "audience1": ["internal", "internalEng"], "documentType": "Q1 plans", "competitiveDocument": "no", "status": "active", "author": "Jones", "currentState": "proposal", "$type": "marketingCollateral-d086c908-2498-4d3e-8a1f-01e82bfc2abe", "$parent": "file_5010739061", "$id": "2094c584-68e1-475c-a581-534a4609594e", "$version": 0, "$typeVersion": 0, "$template": "marketingCollateral", "$scope": "enterprise_12345" } ``` **Source:** [https://ja.developer.box.com/changelog/2018-02-28-breaking-change-to-metadata-apis](https://ja.developer.box.com/changelog/2018-02-28-breaking-change-to-metadata-apis) --- ### メタデータインスタンスのバージョンに対する変更 **Type:** changelog | **Section:** Changelog メタデータインスタンスのバージョンに対する変更 メタデータインフラストラクチャに対する継続的な改善の一環として、メタデータインスタンスのversion値に対する小規模な変更をリリースします。 # メタデータインスタンスのバージョンに対する変更 メタデータインフラストラクチャに対する継続的な改善の一環として、メタデータインスタンスの[`version`](r:/metadata/#param-$version)値に対する小規模な変更をリリースします。 これまで、メタデータインスタンスに関連付けられたバージョン番号は、関連付けられたメタデータテンプレートのフィールドが削除された場合または関連付けられたメタデータテンプレートで`enum`フィールドのオプションが削除された場合に増加していました。 今後は、こうした変更により、メタデータインスタンスのバージョン番号が増加することはありません。 バージョン番号の増加は常に暗黙的に行われてきたため、Boxでは、メタデータインスタンスのバージョンから得られる価値はほとんどないと認識しています。そのため、この変更がお客様に影響を及ぼすとは考えておりません。それでも、ご自身が影響を受けていることに気付いた場合は、カスタマーサクセスマネージャまたは当社のサポートチャネルまでお問い合わせください。 **Source:** [https://ja.developer.box.com/changelog/2020-03-30-change-to-metadata-instance-version](https://ja.developer.box.com/changelog/2020-03-30-change-to-metadata-instance-version) --- ### メタデータカスケードポリシーAPIのベータ版終了 **Type:** changelog | **Section:** Changelog メタデータカスケードポリシーAPIのベータ版終了 メタデータカスケードポリシーAPIが正式リリースされたため、ベータ版の提供を終了しました。 ここ数年、Box… # メタデータカスケードポリシーAPIのベータ版終了 [メタデータカスケードポリシーAPI](e://post_metadata_cascade_policies)が正式リリースされたため、ベータ版の提供を終了しました。 ここ数年、Boxでは、メタデータインフラストラクチャに対して多くの技術的な改善を行ってきました。そしてようやくメタデータカスケードポリシーAPIのベータ版を終了することになりました。このリリースには重大は変更は含まれていません。また、既存のアプリケーションでは、このリリースによる影響は見られません。 最初のリリース以来、メタデータカスケードポリシーでは、メタデータを新しいインスタンスに適用する際の処理速度が10倍以上になりました。さらに、Boxは、他のBox APIに合わせて、最適なAPIエクスペリエンスを保証するために信頼性と可観測性においても大きく前進しました。 メタデータとメタデータカスケードポリシーの詳細については、[メタデータのガイド](g://metadata)、およびBox専用の[メタデータカスケードポリシー](e://post_metadata_cascade_policies)リファレンスドキュメントを参照してください。 **Source:** [https://ja.developer.box.com/changelog/2020-10-21-metadata-cascade-policy-api-leaves-beta](https://ja.developer.box.com/changelog/2020-10-21-metadata-cascade-policy-api-leaves-beta) --- ### メタデータクエリAPIの構文の変更 **Type:** changelog | **Section:** Changelog メタデータクエリAPIの構文の変更 メタデータクエリAPIは、明示的に定義されたレスポンスフィールドを要求するよう更新されました。 # メタデータクエリAPIの構文の変更 [メタデータクエリAPI](g://metadata/queries)は、**明示的に定義されたレスポンスフィールドを要求する**よう更新されました。 ``` curl -X POST https://api.box.com/2.0/metadata_queries/execute_read \ -H 'Authorization: Bearer <ACCESS_TOKEN>" ' -H 'Content-Type: application/json' -d '{ "from": "enterprise_123456.customerInfo", "query": "tav >= :value", "query_params": { "value": 200000 }, "fields": [ "name", "metadata.enterprise_123456.customerInfo.tav" ], "ancestor_folder_id": "0" }' ``` さらに、**このレスポンス形式では項目のリストが返されるようになり**、クエリ結果のリストは返されなくなりました。メタデータは、項目と並んで表示されるのではなく、項目内にネストされるようになりました。レスポンスで返されるのは、`field`配列で指定されたフィールドとすべての基本フィールドだけです。 ``` { "entries": [{ "id": "394384323", "type": "file", "etag": 1, "name": "Contract.pdf", "metadata": { "enterprise_123456": { "customerInfo": { "$parent": "folder_12345,", "$scope": "enterprise_123456", "$template": "customerInfo", "$version": 1, "tav": 1000000 } } } }] } ``` ## 従来の構文 参考までに、このAPIでは、これまで、項目のすべての標準フィールドのほか、一致したメタデータが返されていました。 ``` curl -X POST https://api.box.com/2.0/metadata_queries/execute_read \ -H 'Authorization: Bearer <ACCESS_TOKEN>" ' -H 'Content-Type: application/json' -d '{ "from": "enterprise_123456.customerInfo", "query": "tav >= :value", "query_params": { "value": 200000 }, "ancestor_folder_id": "0" }' ``` レスポンスの本文では、項目がエントリのリストとして返され、それぞれに`item`と`metadata`インスタンスが含まれていました。 ``` { "entries":[ { "item":{ "type":"file", "id":"394384323", "name": "Contract.pdf", "file_version":{ "type":"file_version", "id":"33482348", "sha1":"69888bb1bff455d1b2f8afea75ed1ff0b4879bf6" }, ... }, "metadata":{ "enterprise_123456":{ "customerInfo":{ "tav": 1000000, "$id": "01234500-12f1-1234-aa12-b1d234cb567e", "$parent": "folder_12345,", "$scope": "enterprise_123456", "$template": "customerInfo", "$type": "customerInfo-6bcba49f-ca6d-4d2a-a758-57fe6edf44d0", "$typeVersion": 2, "$version": 1, "$canEdit": true } } } }, ... ], "limit": 20, "next_marker":"AAAAAmVYB1FWec8GH6yWu2nwmanfMh07IyYInaa7DZDYjgO1H4KoLW29vPlLY173OKsci6h6xGh61gG73gnaxoS+o0BbI1/h6le6cikjlupVhASwJ2Cj0tOD9wlnrUMHHw3/ISf+uuACzrOMhN6d5fYrbidPzS6MdhJOejuYlvsg4tcBYzjauP3+VU51p77HFAIuObnJT0ff" } ``` この従来の構文は、**既存のメタデータクエリAPIユーザーだけが引き続き利用できます**。既存のユーザー全員が新しい構文に移行すると、従来の構文は無効になります。 **Source:** [https://ja.developer.box.com/changelog/2020-07-15-changes-to-metadata-query-api-syntax](https://ja.developer.box.com/changelog/2020-07-15-changes-to-metadata-query-api-syntax) --- ### メタデータクエリのインデックスの変更 **Type:** changelog | **Section:** Changelog メタデータクエリのインデックスの変更 ファイル/フォルダのメタデータクエリリクエストを実行する際、検索対象となるファイル/フォルダが10,000を超えるクエリには検索インデックスの作成が必要になります。 このプロセスの効率を改善し、より簡潔にするために、メタデータクエリAPIリクエストでuse_indexキーを使用してインデックスを指定するという明示的な要件をなくすことで、インデックスの使用方法を変更しました。 # メタデータクエリのインデックスの変更 ファイル/フォルダの[メタデータクエリ](g://metadata/queries/)リクエストを実行する際、検索対象となるファイル/フォルダが10,000を超えるクエリには検索インデックスの作成が必要になります。 このプロセスの効率を改善し、より簡潔にするために、メタデータクエリAPIリクエストで`use_index`キーを使用してインデックスを指定するという明示的な要件をなくすことで、インデックスの使用方法を変更しました。 現在`use_index`キーを使用してインデックスを指定している既存のアプリケーションに影響はありません。指定されたインデックスはリクエストで無視され、最も効率的なインデックスが自動的に適用されます。 ## 以前のインデックス作成プロセス 検索対象のファイル/フォルダが10,000を超えるメタデータクエリリクエストに対してインデックスを作成して使用する場合の以前のプロセスは以下のとおりです。これは、変更前のプロセスです。 - インデックスをリクエストするには、メタデータクエリチームにお問い合わせください。 - メタデータクエリチームによってインデックスが作成され、新しく作成されたインデックスの名前が提供されます。 - メタデータクエリリクエストの実行時に、このインデックス名をAPIリクエストの`use_index`キーの値として指定していました。 ## 新しいインデックス作成プロセス インデックスを作成して使用する新しいプロセスは以下のとおりです。 - インデックスをリクエストするには、メタデータクエリチームにお問い合わせください。 メタデータクエリAPIリクエスト内の`use_index`キーは削除されました。その代わり、検索処理中に最も効率的なクエリが自動的に適用されます。 `use_index`キーで現在指定されているインデックスは無視され、代わりに最も効率的なインデックスが使用されます。 アプリケーションの所有者は、自己の判断でメタデータクエリリクエストから`use_index`キーと値を安全に削除できます。 **Source:** [https://ja.developer.box.com/changelog/2021-01-15-metadata-query-index-changes](https://ja.developer.box.com/changelog/2021-01-15-metadata-query-index-changes) --- ### メタデータテンプレートに`multiSelect`フィールドタイプを追加 **Type:** changelog | **Section:** Changelog メタデータテンプレートにmultiSelectフィールドタイプを追加 メタデータテンプレートにmultiSelectと呼ばれる新しい属性タイプが導入されました。これは複数選択に変換されます。この新しい属性タイプにより、Adobe Sign、G Suite… # メタデータテンプレートにmultiSelectフィールドタイプを追加 [メタデータテンプレート](endpoint://resources/metadata-template/)に`multiSelect`と呼ばれる新しい属性タイプが導入されました。これは複数選択に変換されます。この新しい属性タイプにより、Adobe Sign、G Suite、またはフォルダでファイルコンテンツのテンプレートインスタンスを作成する際、チェックボックススタイルの値の複数選択が可能になります。 このフィールドの追加により[メタデータオブジェクト](endpoint://resources/metadata-template/)(テンプレートインスタンス)が変更されます。これは、有効化されている`multiSelect`オプションが文字列値の配列を使用して表され、配列内の各文字列が`multiSelect`オプションのキーに対応しているためです。 **Source:** [https://ja.developer.box.com/changelog/2018-03-29-multiselect-field-type-added-to-metadata-templates](https://ja.developer.box.com/changelog/2018-03-29-multiselect-field-type-added-to-metadata-templates) --- ### メタデータの`date`フィールドの形式に影響する可能性のある変更 **Type:** changelog | **Section:** Changelog メタデータのdateフィールドの形式に影響する可能性のある変更 Boxのメタデータインフラストラクチャに対する継続的な改善の一環として、メタデータテンプレートのdateフィールドの形式に大きく影響する可能性のある3つの変更をリリースする予定です。これらの変更により、Box APIで返される形式は、APIコール間でより一貫性のあるものになります。 # メタデータのdateフィールドの形式に影響する可能性のある変更 Boxのメタデータインフラストラクチャに対する継続的な改善の一環として、メタデータテンプレートの`date`フィールドの形式に大きく影響する可能性のある3つの変更をリリースする予定です。これらの変更により、Box APIで返される形式は、APIコール間でより一貫性のあるものになります。 最初の変更は、日付におけるタイムゾーンオフセットの使用に影響します。これまでは、タイムゾーンオフセットを含めるように日付を設定した場合でも、APIによって返される日付には一貫性がなく、タイムゾーンオフセットが含まれるものもあれば、含まれないものもありました。今後は、すべての日付がUTC (協定世界時)に変換され、タイムゾーンオフセットは削除されます。 例: - 日付が`2020-02-20T12:00:00.000-01:00`に設定されたと想定します。 - これまでは、APIでは`2020-02-20T12:00:00.000-01:00` (元の値)または`2020-02-20T13:00:00.000Z` (UTCに調整された値)が返されました。 - 今後は、常に`2020-02-20T13:00:00.000Z` (UTCに調整された値)が返されます。 2つ目の変更は、メタデータAPIによって返される日付の秒未満の精度に影響します。これまでは、メタデータAPIで返される値の秒未満の精度は0～3桁でした。今後、Boxから返されるメタデータの日時値は、常にミリ秒まで正確になります。 例: - これまで、APIでは`2020-02-20T12:00:00Z`、`2020-02-20T12:00:00.0Z`、`2020-02-20T12:00:00.00Z`または`2020-02-20T12:00:00.000Z`が返される可能性がありました。 - 今後は、常に`2020-02-20T12:00:00.000Z`が返されます。 最後の変更は、メタデータインスタンスの更新時の[`test`](g/metadata/instances/update/#Test-a-value)操作の使用に影響します。これまでのテストでは、リテラル文字列値を使用して日時の値が比較されていました。今回の更新後は、UNIXのタイムスタンプ(ミリ秒単位)を使用して比較されます。 例: - これまでは、`2020-01-21T19:20:00.123-08:00`は`2020-01-22T03:20:00.123Z`と同じではありませんでした。 - 今後、`2020-01-21T19:20:00.123-08:00`は`2020-01-22T03:20:00.123Z`と同じになります。 ## 今回の変更がアプリケーションに及ぼす影響 `RFC3339`に準拠した日時の解析を実装するアプリケーションでは、これらはすべて同じ日付を表す有効な`RFC3339`値であるため、何も実行する必要はありません。`RFC3339`に準拠した日時の解析を実装していないアプリケーションは、解析を実行できるように更新する必要があります。 すべてのBox公式SDKでは、`RFC3339`に準拠した日時の解析をサポートしているため、Box公式SDKの最新バージョンを使用しているアプリケーションの場合、更新は不要です。 ## 今回の変更がアプリケーションに影響を及ぼした場合の対応 今回の変更は、今後数週間かけて段階的にリリースする予定です。メタデータチームは潜在的な影響を監視しますが、ご自身が影響を受けていることに気付いた場合は、カスタマーサクセスマネージャまたは当社のサポートチャネルまでお問い合わせください。 **Source:** [https://ja.developer.box.com/changelog/2020-03-30-potential-impactful-changes-to-format-of-metadata-date-fields](https://ja.developer.box.com/changelog/2020-03-30-potential-impactful-changes-to-format-of-metadata-date-fields) --- ### メタデータ駆動のリテンションポリシー **Type:** changelog | **Section:** Changelog メタデータ駆動のリテンションポリシー リテンションポリシーオブジェクトAPIエクスプローラElement… # メタデータ駆動のリテンションポリシー [リテンションポリシーオブジェクト](endpoint://resources/retention-policy/)APIエクスプローラElementに、メタデータ駆動のリテンションポリシーをサポートする新しい機能が導入されました。この機能では、カスタムメタデータに基づいてリテンションポリシーを個々のファイルに適用できます。これにより、グローバルレベルおよびフォルダレベルに加えて、起動ファイルレベルでもリテンションポリシーを設定できます。これらの新しい拡張されたBox Governance機能は、Box管理コンソールを介してBox管理者に提供され、さらに[リテンションポリシー](endpoint://resources/retention-policy/)および[リテンションの割り当て](endpoint://resources/retention-policy-assignment/)API、BoxのJava、Node、および.NET [ SDK](guides://tooling/sdks)でも使用できるようになります。 **Source:** [https://ja.developer.box.com/changelog/2018-04-11-metadata-driven-retention-policies](https://ja.developer.box.com/changelog/2018-04-11-metadata-driven-retention-policies) --- ### ユーザーのアバターを管理するための新しいエンドポイント **Type:** changelog | **Section:** Changelog ユーザーのアバターを管理するための新しいエンドポイント 本日より、ユーザーアバターAPIでユーザーアバターの追加、更新、削除がサポートされるようになりました。 ユーザーアバターを作成または更新するには、アップロードするファイルへのパスを含めてPOST /users-id… # ユーザーのアバターを管理するための新しいエンドポイント 本日より、ユーザーアバターAPIでユーザーアバターの追加、更新、削除がサポートされるようになりました。 ユーザーアバターを作成または更新するには、アップロードするファイルへのパスを含めて[`POST /users-id-avatar`](e://post-users-id-avatar)エンドポイントを呼び出します。すでにアバターが存在する場合は、新しくアップロードされた写真に置き換えられます。 ``` curl -i -X POST -L https://api.box.net/2.0/users/userID/avatar -H 'Authorization: Bearer <ACCESS_TOKEN>' --form 'pic=@"path/to/file/file.jpeg"' ``` レスポンスには、ファイルの場所へのURLを示す[user avatar](r://user-avatar)オブジェクトが含まれます。 ユーザーアバターを削除するには、[`DELETE /users-id-avatar`](e://delete-users-id-avatar)エンドポイントを呼び出します: ``` curl -i -X DELETE -L https://api.box.net/2.0/users/userID/avatar -H 'Authorization: Bearer <ACCESS_TOKEN>' ``` ## サポート情報 問題がある場合やさらにガイドが必要な場合は、必要なサポートについて、Boxの[Developer Forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum)に英語でリクエストを投稿してください。 **Source:** [https://ja.developer.box.com/changelog/2022-05-18-new-endpoints-for-user-avatar](https://ja.developer.box.com/changelog/2022-05-18-new-endpoints-for-user-avatar) --- ### リテンションAPIに対する新しい機能強化 **Type:** changelog | **Section:** Changelog リテンションAPIに対する新しい機能強化 指定されたリテンションポリシー割り当てのリテンションの対象となっているファイルおよびファイルバージョンを取得するために、新しく2つのAPIエンドポイントが導入されました。これらのAPIは、APIのリテンションポリシースイートに含まれており、個々のファイルおよびファイルバージョンリテンションエンドポイント (まもなくBox APIでの公式サポート終了予定) に代わるものとして作成されました。公式サポート終了日については、後日お知らせいたします。 # リテンションAPIに対する新しい機能強化 指定されたリテンションポリシー割り当てのリテンションの対象となっているファイルおよびファイルバージョンを取得するために、新しく2つのAPIエンドポイントが導入されました。これらのAPIは、APIの[リテンションポリシー](g://retention-policies)スイートに含まれており、個々の[ファイル](e://get-file-version-retentions-id)および[ファイルバージョン](e://get-file-version-retentions)リテンションエンドポイント (まもなくBox APIでの公式サポート終了予定) に代わるものとして作成されました。公式サポート終了日については、後日お知らせいたします。 リテンションポリシー割り当てによってリテンションポリシーが適用されると、その適用先となるフォルダが選択されます。そのフォルダ内のファイルおよびファイルバージョンは、新しいエンドポイントを呼び出したときに返されるコンテンツになります。 ## 機能 このリリースでは、以下の新しいコンテンツと機能が導入されました。 - [リテンションの対象となるファイルを取得](e://get-retention-policy-assignments-id-files-under-retention): 指定したリテンションポリシー割り当てに関連付けられている、リテンションの対象となるファイルのリストを返します。 - [リテンションの対象となるファイルバージョンを取得](e://get-retention-policy-assignments-id-file-versions-under-retention): 指定したリテンションポリシー割り当てに関連付けられている、リテンションの対象となるファイルバージョンのリストを返します。 - 編集可能な`description`フィールドを[リテンションポリシー](e://resources/retention-policy)リソースに追加。 - 書き込み不可の`start_field_date`を[リテンションポリシー割り当て](e://resources/retention-policy-assignment)リソースに追加。このフィールドは、メタデータフィールドのキーIDです。また、その値は、`assigned_to`のタイプが`metadata_template`でない場合または日付フィールドが選択されていない場合に`upload_date`にすることもできます。 **Source:** [https://ja.developer.box.com/changelog/2021-09-07-new-enhancements-to-retention-apis](https://ja.developer.box.com/changelog/2021-09-07-new-enhancements-to-retention-apis) --- ### リテンションポリシーAPIの改善 **Type:** changelog | **Section:** Changelog リテンションポリシーAPIの改善 最近のリテンションポリシーのAPIとリテンションポリシー割り当てに関する変更により、リテンションポリシー割り当てを削除し、ポリシーのリテンション期間と種類を指定することができるようになりました。 # リテンションポリシーAPIの改善 最近のリテンションポリシーのAPIとリテンションポリシー割り当てに関する変更により、リテンションポリシー割り当てを削除し、ポリシーのリテンション期間と種類を指定することができるようになりました。 ## 更新内容 - 新しい[`DELETE`](e://delete-retention-policy-assignments-id)エンドポイントを使用して既存のリテンションポリシー割り当てを削除します: ``` curl -i -X DELETE -L https://api.box.net/2.0/retention_policy_assignments/123456/ -H 'Authorization: Bearer <ACCESS_TOKEN>' ``` リテンションポリシーを[作成](e://post-retention-policies)または[更新](e://put-retention-policies-id)する場合は、次のパラメータを指定します: - `retention_length`: リテンションポリシーをコンテンツに割り当てた後にアクティブにする期間を日数で指定します。 - `retention_type`: ポリシーが`modifiable`または`non-modifiable`であるかを指定します。これは、特定の規制要件に準拠する必要があるかどうかに応じて、リテンションポリシーを全面的に変更可能にするか、限定的に変更可能にするかのいずれかを選択できることを意味します。 ## 開発者向けリソース Box App Centerでのアプリケーションの作成、またはBoxパートナーへの参加をご希望の場合、詳細については[Box Partner Resources](https://support.box.com/hc/en-us/sections/360009473734-Box-Partner-Resources)のガイド (英語) を参照してください。 ## サポート情報 問題がある場合やさらにガイドが必要な場合は、必要なサポートについて、Boxの[Developer Forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum)に英語でリクエストを投稿してください。 **Source:** [https://ja.developer.box.com/changelog/2022-07-23-retention-api-updates](https://ja.developer.box.com/changelog/2022-07-23-retention-api-updates) --- ### リテンションポリシーのマーカーベースのページ割りの追加 **Type:** changelog | **Section:** Changelog リテンションポリシーのマーカーベースのページ割りの追加 BoxのOpenAPIの仕様は、リテンションポリシーおよびリテンションポリシー割り当てのエンドポイントでmarkerベースのページ割りとfieldsクエリパラメータの使用を示すために更新されました。 # リテンションポリシーのマーカーベースのページ割りの追加 BoxのOpenAPIの仕様は、リテンションポリシーおよびリテンションポリシー割り当てのエンドポイントで`marker`ベースのページ割りと`fields`クエリパラメータの使用を示すために更新されました。 ## 更新内容 更新内容は以下のとおりです。 - [`GET /retention-policies`](e://get-retention-policies)および[`GET /retention-policies-id-assignments`](e://get-retention-policies-id-assignments)エンドポイントに`fields`、`limit`、`marker`クエリパラメータを追加しました。 - [リテンションポリシー](e://resources/retention-policies)および[リテンションポリシー割り当て](e://resources/retention-policy-assignments)のレスポンスオブジェクトに`limit`と`next_marker `を追加しました。 ## サポート情報 問題がある場合やさらにガイドが必要な場合は、必要なサポートについて、Boxの[Developer Forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum)に英語で投稿してください。 **Source:** [https://ja.developer.box.com/changelog/2021-11-16-added-retention-policy-marker-based-pagination](https://ja.developer.box.com/changelog/2021-11-16-added-retention-policy-marker-based-pagination) --- ### 今後予定されている重大な変更: Box AI API - 抽出 (構造化) **Type:** changelog | **Section:** Changelog 今後予定されている重大な変更: Box AI API - 抽出 (構造化) Box AI APIの抽出 (構造化) エンドポイントに重大な変更を予定しています。この変更は、追加のフィールドを導入し、メタデータのキー/値ペアを回答オブジェクト内にネストすることで、レスポンスを改善するものです。変更は1月中旬のリリースを予定しています。弊社の変更ログおよびBox開発者向けブログのフォローをお願いいたします。以下でコードスニペットの例をご確認いただけます。 # 今後予定されている重大な変更: Box AI API - 抽出 (構造化) Box AI APIの抽出 (構造化) エンドポイントに重大な変更を予定しています。この変更は、追加のフィールドを導入し、メタデータのキー/値ペアを回答オブジェクト内にネストすることで、レスポンスを改善するものです。**変更は1月中旬のリリースを予定しています**。弊社の[変更ログ](https://developer.box.com/changelog/)および[Box開発者向けブログ](https://medium.com/box-developer-blog)のフォローをお願いいたします。以下でコードスニペットの例をご確認いただけます。 現在のレスポンスの例: ``` { "name": "Marie", "date": "10/2/23" } ``` 新しいレスポンス形式の例: ``` { "answer": { "name": "Marie", "date": "10/2/23" }, "completion_reason": "done", "created_at": "2012-12-12T10:53:43-08:00" } ``` **Source:** [https://ja.developer.box.com/changelog/2024-12-10-upcoming-breaking-change-in-the-box-ai-api](https://ja.developer.box.com/changelog/2024-12-10-upcoming-breaking-change-in-the-box-ai-api) --- ### 共有フォルダのフォルダ項目の並べ替えに対する更新 **Type:** changelog | **Section:** Changelog 共有フォルダのフォルダ項目の並べ替えに対する更新 BoxのフォルダAPI… # 共有フォルダのフォルダ項目の並べ替えに対する更新 BoxのフォルダAPIを使用すると、[フォルダ内の項目を取得](e://get-folders-id-items)し、並べ替えパラメータに基づいてそのリストを[並べ替え](e://get-folders-id-items#param-sort)ることができます。コラボレータが表示できる、関連付けられたフォルダへのパスを持つ共有フォルダの項目の並べ替えを改善しました。 以前は、このようなフォルダの項目は、並べ替えパラメータの値にかかわらず、`id`に基づいて並べ替えられていました。現在は`sort`パラメータに基づいて並べ替えられます。 ## サポートを受けるための新しい場所 今後は新しい[Box Developer Communityフォーラム](https://forum.box.com/)で質問したり、ガイダンスを受けたりすることができます。この新しいフォーラムを利用すると、Box Developer Relationsチーム、同僚、Boxに関するエキスパートと直接会話できます。 **Source:** [https://ja.developer.box.com/changelog/2023-06-30-folder-items-api-update](https://ja.developer.box.com/changelog/2023-06-30-folder-items-api-update) --- ### 共有リンクのパスワードの強化 **Type:** changelog | **Section:** Changelog 共有リンクのパスワードの強化 Box APIで共有リンクを作成する場合 (ファイルに共有リンクを追加する場合など) のパスワードポリシーを強化しました。今後、パスワードは8文字以上で、以下を含める必要があります: 数字 大文字 英数字以外の文字 # 共有リンクのパスワードの強化 Box APIで共有リンクを作成する場合 ([ファイルに共有リンクを追加](e://put-files-id--add-shared-link#param-shared_link-password)する場合など) のパスワードポリシーを強化しました。今後、パスワードは8文字以上で、以下を含める必要があります: - 数字 - 大文字 - 英数字以外の文字 ## サポートを受けるための新しい場所 今後は新しい[Box Developer Communityフォーラム](https://forum.box.com/)で質問したり、ガイダンスを受けたりすることができます。この新しいフォーラムを利用すると、Box Developer Relationsチーム、同僚、Boxに関するエキスパートと直接会話できます。 **Source:** [https://ja.developer.box.com/changelog/2023-06-15-shared-link-passwords](https://ja.developer.box.com/changelog/2023-06-15-shared-link-passwords) --- ### 共有リンクを使用してトークンをダウンスコープするための新しいオプション **Type:** changelog | **Section:** Changelog 共有リンクを使用してトークンをダウンスコープするための新しいオプション アクセストークンをリクエストする際、共有リンクを使用してそのトークンをファイルまたはフォルダにダウンスコープできるようになりました。 この新しいパラメータは、resourceパラメータの代わりに使用できます。このパラメータを使用すると、ファイルIDまたはフォルダIDを指定して同じ操作を実行できます。 # 共有リンクを使用してトークンをダウンスコープするための新しいオプション アクセストークンをリクエストする際、共有リンクを使用してそのトークンをファイルまたはフォルダにダウンスコープできるようになりました。 この新しいパラメータは、`resource`パラメータの代わりに使用できます。このパラメータを使用すると、ファイルIDまたはフォルダIDを指定して同じ操作を実行できます。 ## 更新内容 - 新しい`box_shared_link`リクエストパラメータを[ダウンスコープのドキュメント](https://developer.box.com/guides/authentication/access-tokens/downscope/#downscoping-in-practice)に追加しました。以下の方法で、共有リンクを指定してアクセストークンをダウンスコープできます。 ``` { curl -i -X POST "https://api.box.com/oauth2/token" \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "subject_token=[ACCESS_TOKEN]" \ -d "subject_token_type=urn:ietf:params:oauth:token-type:access_token" \ -d "scope=item_upload item_preview base_explorer" \ -d "box_shared_link=https://cloud.box.com/s/123456" \ -d "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" } ``` - `box_shared_link`リクエストパラメータを[アクセストークンをリクエストAPIリファレンス](https://developer.box.com/reference/post-oauth2-token/#request)に追加しました。 **Source:** [https://ja.developer.box.com/changelog/2021-04-13-token-exchange-optional-parameter-added](https://ja.developer.box.com/changelog/2021-04-13-token-exchange-optional-parameter-added) --- ### 分割アップロードに関するガイドの改善 **Type:** changelog | **Section:** Changelog 分割アップロードに関するガイドの改善 複数の大きいファイルの分割アップロードのエクスペリエンスを改善するため、プロセスの詳細と、各手順の例をガイドに追加しました。 # 分割アップロードに関するガイドの改善 複数の大きいファイルの分割アップロードのエクスペリエンスを改善するため、プロセスの詳細と、各手順の例をガイドに追加しました。 [Box API](e://put-files-upload-sessions-id)を使用して効果的にファイルを分割し、複数のパーツでアップロードする方法の詳細については、[パーツのアップロードガイド](g://uploads/chunked/upload-part)を確認してください。 ## サポート情報 問題がある場合やさらにガイドが必要な場合は、必要なサポートについて、Boxの[Developer Forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum)に英語でリクエストを投稿してください。 **Source:** [https://ja.developer.box.com/changelog/2022-09-12-upload-part-improvements](https://ja.developer.box.com/changelog/2022-09-12-upload-part-improvements) --- ### 変更ログ **Type:** changelog | **Section:** Changelog # 変更ログ **Source:** [https://ja.developer.box.com/changelog/](https://ja.developer.box.com/changelog/) --- ### 廃止された言語バージョンのサポートの終了 **Type:** changelog | **Section:** Changelog 廃止された言語バージョンのサポートの終了 Python SDKおよびJava SDKの次のメジャーバージョンをリリースする予定です。これに伴い、廃止された言語バージョンのサポートが終了となりますのでご注意ください。 # 廃止された言語バージョンのサポートの終了 Python SDKおよびJava SDKの次のメジャーバージョンをリリースする予定です。これに伴い、廃止された言語バージョンのサポートが終了となりますのでご注意ください。 日本時間2022年1月18日に、[Python](https://github.com/box/box-python-sdk/releases) SDKと[Java](https://github.com/box/box-java-sdk/releases) SDKのライブラリのメジャーリリースが計画されており、廃止された言語バージョンのサポートが終了する予定です。Python SDKでは、Python SDKのバージョン`v3.0.0`以降のPython 2.7およびPython 3.5のサポートが終了します。Java SDKでは、Java SDKのバージョン`v3.0.0`以降のJava 7のサポートが終了します。Python SDKまたはJava SDKを使用するアプリケーションでは、[GitHub](https://github.com/box/sdks)のリリースセクションにあるこれらのライブラリの古いバージョンをそれぞれ使用できますが、今後の新機能は使用できません。 ## サポート情報 問題がある場合やさらにガイドが必要な場合は、必要なサポートについて、Boxの[Developer Forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum)に英語でリクエストを投稿してください。また、それぞれのGitHubリポジトリでSDKチームにお問い合わせいただくことも可能です。 **Source:** [https://ja.developer.box.com/changelog/2021-12-17-end-of-support-for-obsolete-language-versions](https://ja.developer.box.com/changelog/2021-12-17-end-of-support-for-obsolete-language-versions) --- ### 手動開始ワークフローの新しいエンドポイント **Type:** changelog | **Section:** Changelog 手動開始ワークフローの新しいエンドポイント Box Relay用に2つのAPIエンドポイントが新しく導入されました。 フォルダに構成されたワークフローを取得する ファイルのワークフロー内で手動開始フローを開始する # 手動開始ワークフローの新しいエンドポイント [Box Relay](https://www.box.com/collaboration/relay-workflow)用に2つのAPIエンドポイントが新しく導入されました。 - フォルダに構成されたワークフローを取得する - ファイルのワークフロー内で手動開始フローを開始する この新しいエンドポイントでは、ワークフロー内での情報の更新が許可されません。また、POSTエンドポイントで開始できるのは、`trigger_type`が`WORKFLOW_MANUAL_START`のフローのみです。POSTリクエスト本文内には`outcome_parametes`オブジェクト (省略可) があります。開始時に選択内容を承認するようフローが構成されている場合は、その選択内容をパラメータとして送信する必要があります。送信できるすべてのオプションを含むガイドは、まもなく利用できるようになります。 ## 機能 このリリースでは、以下の新しいコンテンツと機能が導入されました。 - 新しい[ワークフロー](r://workflow)リソース - 新しい[GET](e://get_workflows)ワークフローエンドポイント - 新しい[POST](e://post_workflows_id_start)手動開始ワークフローエンドポイント **Source:** [https://ja.developer.box.com/changelog/2021-07-16-manual-start-workflow-endpoints-now-active](https://ja.developer.box.com/changelog/2021-07-16-manual-start-workflow-endpoints-now-active) --- ### 抽出エージェント (強化) **Type:** changelog | **Section:** Changelog 抽出エージェント (強化) Boxでは、Gemini 2.5 Proを搭載した抽出エージェント (強化) を導入しました。このエージェントは、思考連鎖処理を使用して最良の回答を提供するだけでなく、これが正しい回答であるとエージェントが考える理由も開発者に示します。 抽出エージェント (強化) の特長を以下に示します。 より高い精度で複雑なドキュメントからキーと値のペアを抽出できるように改善 Box UIで簡単にアクセス: 1回のクリックで機能を有効化 非構造化データを、ファイルに付属する意味のあるメタデータに変換 Boxのメタデータ検索ツールを使用して迅速なインサイトの取得や検出が可能 機能の詳細については、製品ドキュメントの「テンプレートへのメタデータの自動入力」セクションを参照してください。 # 抽出エージェント (強化) Boxでは、Gemini 2.5 Proを搭載した抽出エージェント (強化) を導入しました。このエージェントは、思考連鎖処理を使用して最良の回答を提供するだけでなく、これが正しい回答であるとエージェントが考える理由も開発者に示します。 抽出エージェント (強化) の特長を以下に示します。 - より高い精度で複雑なドキュメントからキーと値のペアを抽出できるように改善 - Box UIで簡単にアクセス: 1回のクリックで機能を有効化 - 非構造化データを、ファイルに付属する意味のあるメタデータに変換 - Boxのメタデータ検索ツールを使用して迅速なインサイトの取得や検出が可能 機能の詳細については、[製品ドキュメント](https://support.box.com/hc/en-us/articles/360044196173-Using-Metadata)の「テンプレートへのメタデータの自動入力」セクションを参照してください。 ## サポート情報 問題がある場合やさらにガイドが必要な場合は、必要なサポートについて、Boxの[Developer Forum](https://forum.box.com/)に英語でリクエストを投稿してください。 **Source:** [https://ja.developer.box.com/changelog/2025-06-24-enhanced-extract-agent](https://ja.developer.box.com/changelog/2025-06-24-enhanced-extract-agent) --- ### 新しい「Box Platformについて」セクションの導入 **Type:** changelog | **Section:** Changelog 新しい「Box Platformについて」セクションの導入 利用開始時のエクスペリエンスを改善するために、Boxでは、このPlatformの使用を開始する際に利用できるリソースを再編および追加しました。詳細セクションについては、こちらをご確認ください。 # 新しい「Box Platformについて」セクションの導入 利用開始時のエクスペリエンスを改善するために、Boxでは、このPlatformの使用を開始する際に利用できるリソースを再編および追加しました。詳細セクションについては、[こちら](https://developer.box.com/platform/)をご確認ください。 ## サポート情報 問題がある場合やさらにガイドが必要な場合は、必要なサポートについて、Boxの[Developer Forum](https://forum.box.com/)に英語でリクエストを投稿してください。 **Source:** [https://ja.developer.box.com/changelog/2023-11-30-learn-page-updates](https://ja.developer.box.com/changelog/2023-11-30-learn-page-updates) --- ### 新しいApp Diagnosticsレポート **Type:** changelog | **Section:** Changelog 新しいApp Diagnosticsレポート 日本時間2021年10月8日以降、新しいレポートが順次リリースされます。このレポートは、10月25日までにすべてのお客様にリリースされる予定です。 # 新しいApp Diagnosticsレポート 日本時間2021年10月8日以降、新しいレポートが順次リリースされます。このレポートは、10月25日までにすべてのお客様にリリースされる予定です。 開発者は、開発者コンソールからApp Diagnosticsレポートを生成することにより、自分のアプリケーションに対するAPIアクティビティを確認できるようになりました。レポートの実行に必要な手順については、[ガイド](g://api-calls/permissions-and-errors/app-diagnostics-report)をご確認ください。 これまでと同様、問題が発生した場合は、[サポートチケット](https://developer.box.com/support)を申請するか、[Developer Forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum)に英語で投稿してください。 **Source:** [https://ja.developer.box.com/changelog/2021-10-07-new-app-diagnostics-report](https://ja.developer.box.com/changelog/2021-10-07-new-app-diagnostics-report) --- ### 新しいBox App Center (旧アプリギャラリー) **Type:** changelog | **Section:** Changelog 新しいBox App Center (旧アプリギャラリー) 全体的に更新されたBox App Centerが利用可能になりました。既存の1,500以上の統合をご利用いただけます。 # 新しいBox App Center (旧アプリギャラリー) 全体的に更新された[Box App Center](https://app.box.com/app-center)が利用可能になりました。既存の1,500以上の統合をご利用いただけます。 ## 更新内容 [Box App Center](https://app.box.com/app-center)は、アプリと統合の最新のリストを提供し、Boxウェブアプリからアクセスできます。 エンドユーザーの場合、Box App Centerを使用すると、Microsoft、Zoom、Salesforce、Slackなどのパートナーからすぐに使用できる統合が包括的に選択されているため、思いどおりの作業が簡単にできます。 ITリーダーや管理者は、Box App Centerでセキュリティやユーザーエクスペリエンスを低下させることなく、ユーザーに選択肢を提供できます。また、企業が承認したオプションのリストを提供することで、シャドーITを排除することができます。 Box App Centerは主要なBoxパッケージの一部となり、**すべて**のお客様にご利用いただけるようになりました。 ## 開発者向けリソース Box App Centerでのアプリケーションの作成、またはBoxパートナーへの参加をご希望の場合、詳細については[Box Partner Resources](https://support.box.com/hc/en-us/sections/360009473734-Box-Partner-Resources)のガイド (英語) を参照してください。 ## サポート情報 問題がある場合やさらにガイドが必要な場合は、必要なサポートについて、Boxの[Developer Forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum)に英語でリクエストを投稿してください。 **Source:** [https://ja.developer.box.com/changelog/2022-05-24-new-app-center](https://ja.developer.box.com/changelog/2022-05-24-new-app-center) --- ### 新しいBox CLIスクリプトを使用したメタデータの抽出 **Type:** changelog | **Section:** Changelog 新しいBox CLIスクリプトを使用したメタデータの抽出 Box CLIで新しいスクリプトを使用できるようになりました。このスクリプトにより、Boxのすべてのファイルとフォルダの詳細を示すメタデータを抽出し、CSVファイルに保存できます。 # 新しいBox CLIスクリプトを使用したメタデータの抽出 [Box CLI](g://cli)で新しいスクリプトを使用できるようになりました。このスクリプトにより、Boxのすべてのファイルとフォルダの詳細を示す[メタデータを抽出](g://cli/scripts/metadata-extraction)し、CSVファイルに保存できます。 ## サポート情報 問題がある場合やさらにガイドが必要な場合は、Boxの[Developer Forum](https://support.box.com/hc/en-us/sections/360009473734-Box-Partner-Resources)に英語でリクエストを投稿してください。 **Source:** [https://ja.developer.box.com/changelog/2022-10-05-metadata-extraction-script](https://ja.developer.box.com/changelog/2022-10-05-metadata-extraction-script) --- ### 新しいBox Open With Sidebar UI Element **Type:** changelog | **Section:** Changelog 新しいBox Open With Sidebar UI Element 新しいBox UI Elementのオープンベータ版である「Open With」Elementがリリースされました。「Open With」を使用すると、開発者は、Box… # 新しいBox Open With Sidebar UI Element 新しいBox UI Elementのオープンベータ版である「Open With」Elementがリリースされました。「Open With」を使用すると、開発者は、Boxに保存されたコンテンツを開くためのメニューをパートナーアプリケーションに埋め込むことができます。このベータリリースで利用可能なパートナーは、Adobe SignおよびG Suiteです。 この新しい要素のドキュメントと設定手順は、[こちら](guide://embed/ui-elements)から入手できます。 **Source:** [https://ja.developer.box.com/changelog/2018-09-27-new-box-open-with-sidebar-ui-element](https://ja.developer.box.com/changelog/2018-09-27-new-box-open-with-sidebar-ui-element) --- ### 新しいiOS SDKが使用可能になりました **Type:** changelog | **Section:** Changelog 新しいiOS SDKが使用可能になりました iOS SDKの新しいメジャーリリースが正式リリースされました。新しいSDKには、大幅な修正が数多く含まれています。 Swiftを使用して完全に再構築されました。 Cocoapods、Carthage、Swift Package… # 新しいiOS SDKが使用可能になりました iOS SDKの新しいメジャーリリースが正式リリースされました。新しいSDKには、大幅な修正が数多く含まれています。 - Swiftを使用して完全に再構築されました。 - Cocoapods、Carthage、Swift Package Managerのサポート。 - SDKでは、完全なAPI機能パリティが維持されるようになりました。 詳細については、[リリースに関するブログ記事](https://medium.com/box-developer-blog/the-new-box-ios-sdk-now-available-baf624b289b4)を参照してください。 **Source:** [https://ja.developer.box.com/changelog/2019-11-18-new-ios-sdk-now-available](https://ja.developer.box.com/changelog/2019-11-18-new-ios-sdk-now-available) --- ### 新しいShieldアラートイベント **Type:** changelog | **Section:** Changelog 新しいShieldアラートイベント 本日をもって、Box Shieldは、新しいイベントをリッスンするよう構成されている、Shieldをご利用のお客様向けに、Enterprise Event Stream内で新しいセキュリティイベントの生成を開始します。 Shield… # 新しいShieldアラートイベント 本日をもって、[Box Shield](https://www.box.com/shield)は、新しいイベントをリッスンするよう構成されている、Shieldをご利用のお客様向けに、[Enterprise Event Stream](g://events/enterprise-events/for-enterprise/)内で新しいセキュリティイベントの生成を開始します。 Shieldによって生成される可能性があるインシデントイベントは以下のとおりです。 - 不審な場所 - 不審なセッション - 異常なダウンロード - 悪意のあるコンテンツ これらのイベント内で生成されるペイロードの詳細については、[Shieldアラートイベント](g://events/event-triggers/shield-alert-events/)ドキュメントを参照してください。 **Source:** [https://ja.developer.box.com/changelog/2020-05-12-new-shield-alert-events](https://ja.developer.box.com/changelog/2020-05-12-new-shield-alert-events) --- ### 新しいShieldエラーコード **Type:** changelog | **Section:** Changelog 新しいShieldエラーコード Box Shieldの新しいエラーコードがリリースされました。新しい403 - forbidden_by_policyエラーコードは、会社が項目のダウンロードなどのアクションを防止するShield… # 新しいShieldエラーコード [Box Shield](https://www.box.com/shield)の新しいエラーコードがリリースされました。新しい`403 - forbidden_by_policy`エラーコードは、会社が項目のダウンロードなどのアクションを防止するShieldアクセスポリシーを適用したときに発生します。 アクションが必要な場合は、Box管理者に連絡し、Shieldアクセスポリシーを調整してください。 詳細とその他の解決策については[エラーコードドキュメント](guide://api-calls/permissions-and-errors/common-errors)を参照してください。 **Source:** [https://ja.developer.box.com/changelog/2019-10-23-new-shield-error-code](https://ja.developer.box.com/changelog/2019-10-23-new-shield-error-code) --- ### 新しいShieldダウンロードイベント **Type:** changelog | **Section:** Changelog 新しいShieldダウンロードイベント Shieldアクセスポリシーに基づいて制限されるダウンロードに対する新しいevent_typeを、Enterprise Event Streamにリリースしました。 # 新しいShieldダウンロードイベント Shieldアクセスポリシーに基づいて制限されるダウンロードに対する新しい`event_type`を、[Enterprise Event](g://events/enterprise-events/for-enterprise) Streamにリリースしました。 ダウンロードを制限するShieldアクセスポリシーを管理者が作成し、エンドユーザーがファイルをダウンロードできないようブロックされると、[Enterprise Event](g://events/enterprise-events/for-enterprise) Stream内でイベントが生成されます。また、ユーザーがダウンロードが制限されたファイルを含むフォルダを表示したとき、ダウンロードが制限されたファイルをプレビューで表示したとき、ダウンロードが制限されたファイルをAPIを介してダウンロードすることをリクエストしたときにもイベントが生成されます。これらのイベントは、標準のイベントオブジェクトスキーマと、`SHIELD_DOWNLOAD_BLOCKED`に設定された`event_type`値に従います。 ## 更新内容 - スマートアクセスのイベントトリガーのドキュメントに[新しいセクション](g://events/event-triggers/shield-alert-events/#download-restriction)を追加 - [Enterprise Eventのリスト](g://events/enterprise-events/for-enterprise/#event-types)に`SHIELD_DOWNLOAD_BLOCKED`を追加 ## サポート情報 問題がある場合やさらにガイドが必要な場合は、必要なサポートについて、Boxの[Developer Forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum)に英語でリクエストを投稿してください。 **Source:** [https://ja.developer.box.com/changelog/2021-11-22-new-shield-download-event](https://ja.developer.box.com/changelog/2021-11-22-new-shield-download-event) --- ### 新しいzipダウンロードAPI **Type:** changelog | **Section:** Changelog 新しいzipダウンロードAPI APIの新しいコレクションが利用可能になりました。開発者は、これを使用して、指定したリストのファイルやフォルダを含むzipファイルを作成できます。Boxは、このzipダウンロードAPI… # 新しいzipダウンロードAPI APIの新しいコレクションが利用可能になりました。開発者は、これを使用して、指定したリストのファイルやフォルダを含むzipファイルを作成できます。Boxは、この[zipダウンロードAPI](e://post_zip_downloads)に関するリファレンスドキュメントを更新しました。これらの新しいエンドポイントに対するSDKのサポートは、現在開発中であり、今後3か月以内にリリースする予定です。 **Source:** [https://ja.developer.box.com/changelog/2020-07-22-new-zip-download-apis-available](https://ja.developer.box.com/changelog/2020-07-22-new-zip-download-apis-available) --- ### 新しいコレクションイベント **Type:** changelog | **Section:** Changelog 新しいコレクションイベント 外部のコレクションイベントがEnterprise Event Streamから使用可能になりました。 Boxのコレクションを使用すると、ファイル、フォルダ、ウェブリンクを… # 新しいコレクションイベント 外部のコレクションイベントが[Enterprise Event](g://events/enterprise-events/for-enterprise/) Streamから使用可能になりました。 Boxの[コレクション](g://collections/)を使用すると、ファイル、フォルダ、ウェブリンクを1つのフォルダにまとめるのではなく、グループ化できます。これらの新しいイベントにより、社内で行われるコレクションの操作を監視することができます。 イベントは標準的なイベントオブジェクトスキーマに従っており、以下のようなものがあります。 - `COLLECTION_CREATE`: コレクションが作成されました - `COLLECTION_DELETE`: コレクションが削除されました - `COLLECTION_UPDATE`: コレクションが更新されました - `COLLECTION_ITEM_CREATE`: 項目がコレクションに追加されました - `COLLECTION_ITEM_DELETE`: 項目がコレクションから削除されました - `COLLECTION_ITEM_UPDATE`: コレクション内の項目が更新されました **Source:** [https://ja.developer.box.com/changelog/2021-03-16-new-collection-events](https://ja.developer.box.com/changelog/2021-03-16-new-collection-events) --- ### 新しいサイドバーUI ElementとOpen With UI Element正式リリース **Type:** changelog | **Section:** Changelog 新しいサイドバーUI ElementとOpen With UI Element正式リリース Box UI Elementsに2つのメジャーリリースが追加されました。 新しいサイドバーElement… # 新しいサイドバーUI ElementとOpen With UI Element正式リリース Box UI Elementsに2つのメジャーリリースが追加されました。 1. 新しいサイドバーElement: この新しい要素によって、ファイルのメタデータサイドバーを独自のアプリケーションまたはウェブサイトに直接組み込むことができます。ドキュメントは[こちら](guides://embed/ui-elements)で参照できます。 2. Open With Element正式リリース: Open With Elementはベータから正式リリースに移行しました。Open Withによって、Adobe Sign、G Suite、またはBox Editでファイルコンテンツを起動するための個別のボタンを作成できます。また、それを既存のコンテンツエクスプローラElementに統合することもできます。ドキュメントは[こちら](guides://embed/ui-elements)で参照できます。 リリース発表は[こちら](https://medium.com/box-developer-blog/new-sidebar-element-the-ga-of-open-with-935936a0628f)で参照できます。 **Source:** [https://ja.developer.box.com/changelog/2019-01-18-new-sidebar-ui-element-open-with-element-ga](https://ja.developer.box.com/changelog/2019-01-18-new-sidebar-ui-element-open-with-element-ga) --- ### 新しいファイルリクエストAPI **Type:** changelog | **Section:** Changelog 新しいファイルリクエストAPI APIの新しいコレクションが利用可能になりました。開発者はこれを使用して、ファイルリクエストを作成および更新できます。Box… # 新しいファイルリクエストAPI APIの新しいコレクションが利用可能になりました。開発者はこれを使用して、ファイルリクエストを作成および更新できます。Boxは、ファイルリクエストの管理に役立つよう、[リファレンスドキュメント](e://post_file_requests_id_copy)を更新したほか、[新しいガイド](g://file-requests)を追加しました。 既存のファイルリクエストのコピーを作成するために必要なのは、既存のファイルリクエストの一意のIDと、新しいリクエストの適用先となるフォルダのIDだけです。 ``` curl -i -X POST "https://api.box.com/2.0/file_requests/42037322/copy" \ -H "Authorization: Bearer <ACCESS_TOKEN>" \ -d '{ "folder": { "id": "2233212" } }' ``` さらに、開発者がファイルリクエストの詳細を取得したり、ファイルリクエストを更新または削除したりできるように追加のAPIも利用可能になりました。詳細については、Developerドキュメントをご確認ください。 - **テンプレートのファイルリクエストを作成する**: [ガイド](g://file-requests/template) - **ファイルリクエストのコピーを作成する**: [ガイド](g://file-requests/copy) | [APIリファレンス](e://post_file_requests_id_copy) - **ファイルリクエストに関する情報を取得する**: [ガイド](g://file-requests/get) | [APIリファレンス](e://get_file_requests_id) - **ファイルリクエストの構成を更新する**: [ガイド](g://file-requests/update) | [APIリファレンス](e://put_file_requests_id) - **ファイルリクエストを削除する**: [ガイド](g://file-requests/delete) | [APIリファレンス](e://delete_file_requests_id) **Source:** [https://ja.developer.box.com/changelog/2020-10-02-new-file-request-apis-available](https://ja.developer.box.com/changelog/2020-10-02-new-file-request-apis-available) --- ### 新しいメタデータクエリAPI **Type:** changelog | **Section:** Changelog 新しいメタデータクエリAPI 新しいAPIが使用可能になりました。開発者はこのAPIを使用して、ファイルやフォルダに追加されているメタデータによってそのファイルやフォルダに対してクエリを実行できます。Boxは、こちらのメタデータクエリAPI… # 新しいメタデータクエリAPI 新しいAPIが使用可能になりました。開発者はこのAPIを使用して、ファイルやフォルダに追加されているメタデータによってそのファイルやフォルダに対してクエリを実行できます。Boxは、こちらの[メタデータクエリAPI](e://post_metadata_queries_execute_read)のリファレンスドキュメントを更新したほか、新しい[ガイド](g://metadata/queries)と[メタデータのクイックスタートガイド](g://metadata/quick-start)の更新をリリースしました。 **Source:** [https://ja.developer.box.com/changelog/2020-04-21-new-metadata-query-apis-available](https://ja.developer.box.com/changelog/2020-04-21-new-metadata-query-apis-available) --- ### 新しいメタデータクエリインデックスのエンドポイント **Type:** changelog | **Section:** Changelog 新しいメタデータクエリインデックスのエンドポイント 指定したテンプレートとスコープのメタデータクエリインデックスのリストを取得する新しいAPIエンドポイントが導入されました。 # 新しいメタデータクエリインデックスのエンドポイント 指定したテンプレートとスコープのメタデータクエリインデックスのリストを取得する新しいAPIエンドポイントが導入されました。 メタデータクエリを使用すると、ファイルやフォルダに追加されているメタデータを検索して、そのファイルやフォルダを見つけることができます。 10,000を超えるファイルやフォルダに対してメタデータクエリを実行する際に、クエリのパフォーマンスが悪いと`HTTP 403`エラーが発生する場合があります。検索インデックスを作成すれば、これらのクエリを大規模に実行して、このエラー状態を回避できます。また、検索インデックスは、クエリの処理中に自動的に適用されます。 この新しいエンドポイントにより、作成されたこれらの検索インデックスの参照が可能になります。 ## 機能 このリリースでは、以下の新しいコンテンツと機能が導入されました。 - スコープやメタデータを指定してメタデータクエリインデックスのリストを取得するための新しいAPIエンドポイント。 - 新しいメタデータクエリインデックスの[レスポンスオブジェクト](https://developer.box.com/reference/resources/metadata-query-indices/)。 - 新しいメタデータクエリインデックス (複数) の[レスポンスオブジェクト](https://developer.box.com/reference/resources/metadata-query-index/)。 ## 更新内容 このリリースでは、次のように、コンテンツが更新されました。 - メタデータクエリインデックスのリストを取得する方法の詳細が記載されているメタデータクエリインデックスガイドを更新。 **Source:** [https://ja.developer.box.com/changelog/2021-03-25-new-metadata-query-indicies-endpoint](https://ja.developer.box.com/changelog/2021-03-25-new-metadata-query-indicies-endpoint) --- ### 新しい入門ガイド **Type:** changelog | **Section:** Changelog 新しい入門ガイド Box APIの利用を開始するには、Boxのステップバイステップガイドをご確認ください。最適なユースケース、ユーザーモデル、アーキテクチャパターンなどを紹介しています。 # 新しい入門ガイド Box APIの利用を開始するには、Boxの[ステップバイステップガイド](g://getting-started)をご確認ください。最適なユースケース、ユーザーモデル、アーキテクチャパターンなどを紹介しています。 ## 機能 - ユースケースの評価: [ガイド](page/platform/use-cases/) - 一般的なユーザーモデル: [ガイド](page/platform/user-types/) - 一般的なアーキテクチャパターン: [ガイド](page/platform/appendix/architecture-patterns/) - 一般的な値の確認: [ガイド](page/platform/appendix/locating-values/) - セキュリティの概要: [ガイド](g://security) - 認証のベストプラクティス: [ガイド](g://authentication/best-practices) - 詳細な承認手順: [ガイド](g://authorization) **Source:** [https://ja.developer.box.com/changelog/2021-08-03-getting-started-guide](https://ja.developer.box.com/changelog/2021-08-03-getting-started-guide) --- ### 新しい編集可能な共有リンクAPI **Type:** changelog | **Section:** Changelog 新しい編集可能な共有リンクAPI 開発者は、APIを使用して共有リンクでファイルを編集可能にできるようになりました。 # 新しい編集可能な共有リンクAPI 開発者は、APIを使用して共有リンクでファイルを編集可能にできるようになりました。 ## ドキュメントの更新 - [ファイル](r://file--full#param-shared_link-permissions)、[フォルダ](r://folder--full#param-shared_link-permissions)、[ウェブリンク](r://web-link/#param-shared_link-permissions)リソースの`permissions`オブジェクトに新しい`can_edit`値を追加 - [`file--full`](r://file--full/#param-shared_link_permission_options)リソースに新しい`shared_link_permission_options`フィールドを追加 - リファレンスドキュメントに[ウェブリンクの共有リンクセクション](e://get-shared-items--web-links)を追加 - 共有リンクのガイドドキュメントに[権限に関するページ](g://shared-links/permissions)を追加 - 同じPUTエンドポイントを使用しているため、[共有リンクの更新と追加](g://shared-links/create-or-update)のガイドページを統合 - 複数の共有リンクページでコードスニペットを更新 ## 機能強化の詳細 - ファイルにコラボレータとしてユーザーを設定するのではなく、`shared_link.permissions.can_edit`フィールドを`true`に設定することで編集権限を付与できます。 - ファイル、フォルダ、ウェブリンクのすべての共有リンクオブジェクトで`can_edit`フィールドが返されます。ただし、ファイルの場合はtrueにしか設定できません。 - この機能は今後の数四半期で弊社のSDKライブラリに追加されます。 - 管理者が編集可能な共有リンクを管理コンソールでオフにした場合、この機能は使用できません。 ### cURLの例 ``` curl -i -X PUT 'https://api.box.com/2.0/files/123456789?fields=shared_link' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer [ACCESS TOKEN]' \ -d '{ "shared_link": { "permissions": { "can_preview": true, "can_download": true, "can_edit": true } } }' ``` ## サポート情報 問題がある場合やさらにガイドが必要な場合は、必要なサポートについて、Boxの[Developer Forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum)に英語でリクエストを投稿してください。 **Source:** [https://ja.developer.box.com/changelog/2022-05-06-new-editable-shared-links-api](https://ja.developer.box.com/changelog/2022-05-06-new-editable-shared-links-api) --- ### 新しくなったBox CLIのYouTube動画 **Type:** changelog | **Section:** Changelog 新しくなったBox CLIのYouTube動画 2月に、OAuth 2.0バージョンのBox CLIと一緒に新しいYouTubeコンテンツをリリースしました。本日は、このシリーズの2番目の動画をリリースしました。この動画では、組み込みのヘルプ機能を使用してCLIでフォルダを作成する方法を紹介しています。 # 新しくなったBox CLIのYouTube動画 2月に、OAuth 2.0バージョンのBox CLIと一緒に新しいYouTubeコンテンツを[リリース](https://developer.box.com/changelog/#2022-02-01-box-cli-v300-released)しました。本日は、このシリーズの[2番目の動画](https://www.youtube.com/watch?v=66wlIyS07Aw&list=PL0F3BD5B64D6A39F1&index=2)をリリースしました。この動画では、組み込みのヘルプ機能を使用してCLIでフォルダを作成する方法を紹介しています。 [YouTube](https://www.youtube.com/playlist?list=PL0F3BD5B64D6A39F1)のBox Platform and Developerというプレイリストをご確認ください。さらに2つの動画 (as-userなどの高度なトピックとPowerShellを使用したCLI自動化) を予定しています。 最新のコンテンツをすべて入手するには、ぜひBoxチャンネルに[ご登録](https://www.youtube.com/user/box/featured)ください。 ## サポート情報 問題がある場合やさらにガイドが必要な場合は、必要なサポートについて、Boxの[Developer Forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum)に英語でリクエストを投稿してください。 **Source:** [https://ja.developer.box.com/changelog/2022-03-17-new-box-cli-youtube-video](https://ja.developer.box.com/changelog/2022-03-17-new-box-cli-youtube-video) --- ### 新しくなったフォルダロックAPI **Type:** changelog | **Section:** Changelog 新しくなったフォルダロックAPI フォルダに対する移動および削除アクションの制限を可能にするために、APIの新しいコレクションがリリースされました。フォルダのロックの作成および管理に役立つ、新しいAPI… # 新しくなったフォルダロックAPI フォルダに対する移動および削除アクションの制限を可能にするために、APIの新しいコレクションがリリースされました。フォルダのロックの作成および管理に役立つ、新しい[APIリファレンス](e://post-folder-locks)と[ガイド](g://folders/single/create-lock)が使用可能になりました。 フォルダが移動または削除されないようにそのフォルダにロックを作成するには、`POST /folder_locks/`エンドポイントにフォルダのIDを指定します。 ``` curl -i -X POST "https://api.box.com/2.0/folder_locks" \ -H "Authorization: Bearer <ACCESS_TOKEN>" \ -H "Content-Type: application/json" \ -d '{ "folder": { "type": "folder", "id": "33552487093" } }' ``` また、開発者が特定のフォルダに対するすべてのロックのリストを取得したり、フォルダから既存のフォルダのロックを削除したりできるように、追加のAPIエンドポイントが提供されています。 - **フォルダのロックを作成する**: [ガイド](g://folders/single/create-lock) | [APIリファレンス](e://post-folder-locks) - **フォルダに対するすべてのロックのリストを取得する**: [ガイド](g://folders/single/get-locks) | [APIリファレンス](e://get-folder-locks) - **フォルダのロックを削除する**: [ガイド](g://folders/single/delete-lock) | [APIリファレンス](e://delete-folder-locks-id) **Source:** [https://ja.developer.box.com/changelog/2020-10-22-new-folder-lock-apis-now-available](https://ja.developer.box.com/changelog/2020-10-22-new-folder-lock-apis-now-available) --- ### 新しくなったフォルダロックAPI **Type:** changelog | **Section:** Changelog 新しくなったフォルダロックAPI 開発者がフォルダに対する移動操作と削除操作をロックできるように、APIの新しいコレクションがリリースされました。フォルダロックの作成および管理に役立つ、新しいAPI… # 新しくなったフォルダロックAPI 開発者がフォルダに対する移動操作と削除操作をロックできるように、APIの新しいコレクションがリリースされました。フォルダロックの作成および管理に役立つ、新しい[APIリファレンス](e://post-folder-locks)と[ガイド](g://folders/single/create-lock)が使用可能になりました。 フォルダが移動または削除されないようにそのフォルダにロックを作成するには、`folder_locks`エンドポイントにフォルダのIDを指定します。 ``` curl -i -X POST "https://api.box.com/2.0/folder_locks" \ -H "Authorization: Bearer <ACCESS_TOKEN>" \ -H "Content-Type: application/json" \ -d '{ "folder": { "type": "folder", "id": "33552487093" } }' ``` また、開発者が特定のフォルダに対するすべてのロックのリストを取得したり、フォルダロックIDを使用して既存のフォルダロックを削除したりできるように、追加のAPIエンドポイントが提供されています。 - **フォルダのロックを作成する**: [ガイド](g://folders/single/create-lock) | [APIリファレンス](e://post-folder-locks) - **フォルダに対するすべてのロックのリストを取得する**: [ガイド](g://folders/single/get-locks) | [APIリファレンス](e://get-folder-locks) - **フォルダのロックを削除する**: [ガイド](g://folders/single/delete-lock) | [APIリファレンス](e://delete-folder-locks-id) **Source:** [https://ja.developer.box.com/changelog/2020-10-26-new-folder-lock-apis-now-available](https://ja.developer.box.com/changelog/2020-10-26-new-folder-lock-apis-now-available) --- ### 新世代のPython SDKのリリース **Type:** changelog | **Section:** Changelog 新世代のPython SDKのリリース Box Python SDKをリリースしました。これは、開発者エクスペリエンスを向上させ、Boxコンテンツクラウドとの統合を効率化することを目的としています。 新世代のPython SDKでは、以下を利用できるようになります。 API… # 新世代のPython SDKのリリース [Box Python SDK](https://github.com/box/box-python-sdk-gen)をリリースしました。これは、開発者エクスペリエンスを向上させ、Boxコンテンツクラウドとの統合を効率化することを目的としています。 [新世代のPython SDK](https://github.com/box/box-python-sdk-gen)では、以下を利用できるようになります。 - **APIの全面的なサポート**: 新世代のBox SDKにより、開発者はBox APIエコシステム全体をカバーできるようになります。Boxが提供する最新機能をすべて利用できるようになったため、より高性能で機能豊富なアプリケーションを作成できます。 - **迅速なAPIの更新**: 新しいBox APIがSDKに組み込まれるのを待つ必要はなくなります。Boxでは、自動生成による新しい開発アプローチにより、はるかに速いペースで (数日中に) 新しいBox APIをSDKに追加できるようになりました。これは、最新の機能をすぐにアプリケーションで利用できるようになることを意味します。 - **ドキュメントへの埋め込み**: Boxでは、開発者にとって情報へのアクセスが重要であることを理解しています。新しいアプローチを使用して、すべてのオブジェクトおよびパラメータに関する包括的なドキュメントをSDKのソースコードに直接含めました。つまり、この情報を開発者向けポータルで探す必要がなくなるため、時間の節約と開発プロセスの効率化につながります。 - **便利なメソッドの強化**: 開発エクスペリエンスを強化するBoxの取り組みにより、便利なメソッドの導入が推進されます。このようなメソッドは、認証、分割アップロード、指数バックオフ、自動再試行、型チェック (変数を正しく使用しているかどうかの確認に役立ちます) など、さまざまな側面をカバーします。 新世代のBox SDKを利用して、Boxコンテンツクラウドの可能性を最大限に引き出してください。より迅速かつ効率的に革新的なソリューションを作成しましょう。 **Source:** [https://ja.developer.box.com/changelog/2024-05-20-box-python-sdk-new-gen-released](https://ja.developer.box.com/changelog/2024-05-20-box-python-sdk-new-gen-released) --- ### 新世代のPython SDKのリリース **Type:** changelog | **Section:** Changelog 新世代のPython SDKのリリース Box Python SDKをリリースしました。これは、開発者エクスペリエンスを向上させ、Boxコンテンツクラウドとの統合を効率化することを目的としています。 # 新世代のPython SDKのリリース [Box Python SDK](https://github.com/box/box-python-sdk-gen)をリリースしました。これは、開発者エクスペリエンスを向上させ、Boxコンテンツクラウドとの統合を効率化することを目的としています。 [新世代のPython SDK](https://github.com/box/box-python-sdk-gen)では、以下を利用できるようになります。 - **APIの全面的なサポート**: 新世代のBox SDKにより、開発者はBox APIエコシステム全体をカバーできるようになります。Boxが提供する最新機能をすべて利用できるようになったため、より高性能で機能豊富なアプリケーションを作成できます。 - **迅速なAPIの更新**: 新しいBox APIがSDKに組み込まれるのを待つ必要はなくなります。Boxでは、自動生成による新しい開発アプローチにより、はるかに速いペースで (数日中に) 新しいBox APIをSDKに追加できるようになりました。これは、最新の機能をすぐにアプリケーションで利用できるようになることを意味します。 - **ドキュメントへの埋め込み**: Boxでは、開発者にとって情報へのアクセスが重要であることを理解しています。新しいアプローチを使用して、すべてのオブジェクトおよびパラメータに関する包括的なドキュメントをSDKのソースコードに直接含めました。つまり、この情報を開発者向けポータルで探す必要がなくなるため、時間の節約と開発プロセスの効率化につながります。 - **便利なメソッドの強化**: 開発エクスペリエンスを強化するBoxの取り組みにより、便利なメソッドの導入が推進されます。このようなメソッドは、認証、分割アップロード、指数バックオフ、自動再試行、型チェック (変数を正しく使用しているかどうかの確認に役立ちます) など、さまざまな側面をカバーします。 新世代のBox SDKを利用して、Boxコンテンツクラウドの可能性を最大限に引き出してください。より迅速かつ効率的に革新的なソリューションを作成しましょう。 **Source:** [https://ja.developer.box.com/changelog/2024-05-20-box-python-sdk-new-gen-released%20copy](https://ja.developer.box.com/changelog/2024-05-20-box-python-sdk-new-gen-released%20copy) --- ### 新世代のPython SDKのリリース **Type:** changelog | **Section:** Changelog 新世代のPython SDKのリリース Box Python SDKをリリースしました。これは、開発者エクスペリエンスを向上させ、Boxコンテンツクラウドとの統合を効率化することを目的としています。 # 新世代のPython SDKのリリース [Box Python SDK](https://github.com/box/box-python-sdk-gen)をリリースしました。これは、開発者エクスペリエンスを向上させ、Boxコンテンツクラウドとの統合を効率化することを目的としています。 [新世代のPython SDK](https://github.com/box/box-python-sdk-gen)では、以下を利用できるようになります。 - **APIの全面的なサポート**: 新世代のBox SDKにより、開発者はBox APIエコシステム全体をカバーできるようになります。Boxが提供する最新機能をすべて利用できるようになったため、より高性能で機能豊富なアプリケーションを作成できます。 - **迅速なAPIの更新**: 新しいBox APIがSDKに組み込まれるのを待つ必要はなくなります。Boxでは、自動生成による新しい開発アプローチにより、はるかに速いペースで (数日中に) 新しいBox APIをSDKに追加できるようになりました。これは、最新の機能をすぐにアプリケーションで利用できるようになることを意味します。 - **ドキュメントへの埋め込み**: Boxでは、開発者にとって情報へのアクセスが重要であることを理解しています。新しいアプローチを使用して、すべてのオブジェクトおよびパラメータに関する包括的なドキュメントをSDKのソースコードに直接含めました。つまり、この情報を開発者向けポータルで探す必要がなくなるため、時間の節約と開発プロセスの効率化につながります。 - **便利なメソッドの強化**: 開発エクスペリエンスを強化するBoxの取り組みにより、便利なメソッドの導入が推進されます。このようなメソッドは、認証、分割アップロード、指数バックオフ、自動再試行、型チェック (変数を正しく使用しているかどうかの確認に役立ちます) など、さまざまな側面をカバーします。 新世代のBox SDKを利用して、Boxコンテンツクラウドの可能性を最大限に引き出してください。より迅速かつ効率的に革新的なソリューションを作成しましょう。 **Source:** [https://ja.developer.box.com/changelog/2024-05-20-box-python-sdk-new-gen](https://ja.developer.box.com/changelog/2024-05-20-box-python-sdk-new-gen) --- ### 新世代のSwift SDKのリリース **Type:** changelog | **Section:** Changelog 新世代のSwift SDKのリリース Box Swift SDKをリリースしました。これは、開発者エクスペリエンスを向上させ、Boxコンテンツクラウドとの統合を効率化することを目的としています。 # 新世代のSwift SDKのリリース [Box Swift SDK](https://github.com/box/box-swift-sdk-gen)をリリースしました。これは、開発者エクスペリエンスを向上させ、Boxコンテンツクラウドとの統合を効率化することを目的としています。 [新世代のSwift SDK](https://github.com/box/box-swift-sdk-gen)では、以下を利用できるようになります。 - **APIの全面的なサポート**: 新世代のBox SDKにより、開発者はBox APIエコシステム全体をカバーできるようになります。Boxが提供する最新機能をすべて利用できるようになったため、より高性能で機能豊富なアプリケーションを作成できます。 - **迅速なAPIの更新**: 新しいBox APIがSDKに組み込まれるのを待つ必要はなくなります。Boxでは、自動生成による新しい開発アプローチにより、はるかに速いペースで (数日中に) 新しいBox APIをSDKに追加できるようになりました。これは、最新の機能をすぐにアプリケーションで利用できるようになることを意味します。 - **ドキュメントへの埋め込み**: Boxでは、開発者にとって情報へのアクセスが重要であることを理解しています。新しいアプローチを使用して、すべてのオブジェクトおよびパラメータに関する包括的なドキュメントをSDKのソースコードに直接含めました。つまり、この情報を開発者向けポータルで探す必要がなくなるため、時間の節約と開発プロセスの効率化につながります。 - **便利なメソッドの強化**: 開発エクスペリエンスを強化するBoxの取り組みにより、便利なメソッドの導入が推進されます。このようなメソッドは、認証、分割アップロード、指数バックオフ、自動再試行、型チェック (変数を正しく使用しているかどうかの確認に役立ちます) など、さまざまな側面をカバーします。 新世代のBox SDKを利用して、Boxコンテンツクラウドの可能性を最大限に引き出してください。より迅速かつ効率的に革新的なソリューションを作成しましょう。 **Source:** [https://ja.developer.box.com/changelog/2024-07-25-box-swift-sdk-new-gen-released](https://ja.developer.box.com/changelog/2024-07-25-box-swift-sdk-new-gen-released) --- ### 新世代のTypeScript SDKのリリース **Type:** changelog | **Section:** Changelog 新世代のTypeScript SDKのリリース Box TypeScript SDKをリリースしました。これは、開発者エクスペリエンスを向上させ、Boxコンテンツクラウドとの統合を効率化することを目的としています。 # 新世代のTypeScript SDKのリリース [Box TypeScript SDK](https://github.com/box/box-typescript-sdk-gen)をリリースしました。これは、開発者エクスペリエンスを向上させ、Boxコンテンツクラウドとの統合を効率化することを目的としています。 [新世代のTypescript SDK](https://github.com/box/box-typescript-sdk-gen)では、以下を利用できるようになります。 - **APIの全面的なサポート**: 新世代のBox SDKにより、開発者はBox APIエコシステム全体をカバーできるようになります。Boxが提供する最新機能をすべて利用できるようになったため、より高性能で機能豊富なアプリケーションを作成できます。 - **迅速なAPIの更新**: 新しいBox APIがSDKに組み込まれるのを待つ必要はなくなります。Boxでは、自動生成による新しい開発アプローチにより、はるかに速いペースで (数日中に) 新しいBox APIをSDKに追加できるようになりました。これは、最新の機能をすぐにアプリケーションで利用できるようになることを意味します。 - **ドキュメントへの埋め込み**: Boxでは、開発者にとって情報へのアクセスが重要であることを理解しています。新しいアプローチを使用して、すべてのオブジェクトおよびパラメータに関する包括的なドキュメントをSDKのソースコードに直接含めました。つまり、この情報を開発者向けポータルで探す必要がなくなるため、時間の節約と開発プロセスの効率化につながります。 - **便利なメソッドの強化**: 開発エクスペリエンスを強化するBoxの取り組みにより、便利なメソッドの導入が推進されます。このようなメソッドは、認証、分割アップロード、指数バックオフ、自動再試行、型チェック (変数を正しく使用しているかどうかの確認に役立ちます) など、さまざまな側面をカバーします。 新世代のBox SDKを利用して、Boxコンテンツクラウドの可能性を最大限に引き出してください。より迅速かつ効率的に革新的なソリューションを作成しましょう。 **Source:** [https://ja.developer.box.com/changelog/2024-05-20-box-node-sdk-new-gen-released](https://ja.developer.box.com/changelog/2024-05-20-box-node-sdk-new-gen-released) --- ### 検索APIで共有リンクのサポートを追加 **Type:** changelog | **Section:** Changelog 検索APIで共有リンクのサポートを追加 検索APIでは、ユーザーが最近共有リンクを介してアクセスしたファイル、フォルダ、およびウェブリンクが返されるようになりました。 共有項目をリクエストするには、新しいinclude_recent_shared_linksクエリパラメータをtrueに設定してGET /search APIを呼び出します。 このクエリパラメータが指定されていない場合またはtrueに設定されていない場合、デフォルトでは、このAPIによって共有項目が返されることはありません。 レスポンス形式の変更 include_recent_shared_linksをtrueに設定した場合、追加情報を返すことができるようにレスポンスが若干変更されました。APIでは、ファイル、フォルダ、およびウェブリンクの直接的なリストではなく、itemとaccessible_via_shared_linkプロパティを含むオブジェクトのリストが返されるようになりました。 # 検索APIで共有リンクのサポートを追加 [検索API](e://get_search)では、ユーザーが最近共有リンクを介してアクセスしたファイル、フォルダ、およびウェブリンクが返されるようになりました。 共有項目をリクエストするには、新しい`include_recent_shared_links`クエリパラメータを`true`に設定して[`GET /search`](e://get_search) APIを呼び出します。 ``` curl -i -X GET https://api.box.com/2.0/search?query=Contract&include_recent_shared_link=true ``` このクエリパラメータが指定されていない場合またはtrueに設定されていない場合、デフォルトでは、このAPIによって共有項目が返されることはありません。 ## レスポンス形式の変更 `include_recent_shared_links`を`true`に設定した場合、追加情報を返すことができるようにレスポンスが若干変更されました。APIでは、ファイル、フォルダ、およびウェブリンクの直接的なリストではなく、`item`と`accessible_via_shared_link`プロパティを含むオブジェクトのリストが返されるようになりました。 ``` { "entries": [ { "item": { "id": 12345, "etag": 1, "type": "file", "sequence_id": 3, "name": "Contract.pdf", ... }, "accessible_via_shared_link": "https://www.box.com/s/vspke7y05sb214wjokpk" } ... ], "limit": 1000, "offset": 2000, "total_count": 5000 } ``` ``` { "entries": [ { "id": 12345, "etag": 1, "type": "file", "sequence_id": 3, "name": "Contract.pdf", ... }, ... ], "limit": 1000, "offset": 2000, "total_count": 5000 } ``` このレスポンス形式の変更は、新しいクエリパラメータを使用して行われるAPIコールのみに適用されるため、既存のアプリケーションに影響することはありません。 **Source:** [https://ja.developer.box.com/changelog/2020-09-25-search-api-adds-support-for-shared-links](https://ja.developer.box.com/changelog/2020-09-25-search-api-adds-support-for-shared-links) --- ### 検索APIで共有リンクのサポートを追加 **Type:** changelog | **Section:** Changelog 検索APIで共有リンクのサポートを追加 検索APIでは、ユーザーが最近共有リンクを介してアクセスしたファイル、フォルダ、およびウェブリンクが返されるようになりました。 共有項目をリクエストするには、新しいinclude_recent_shared_linksクエリパラメータをtrueに設定してGET /search APIを呼び出します。 このクエリパラメータが指定されていない場合またはtrueに設定されていない場合、デフォルトでは、このAPIによって共有項目が返されることはありません。 レスポンス形式の変更 include_recent_shared_linksをtrueに設定した場合、追加情報を返すことができるようにレスポンスが若干変更されました。APIでは、ファイル、フォルダ、およびウェブリンクの直接的なリストではなく、itemとaccessible_via_shared_linkプロパティを含むオブジェクトのリストが返されるようになりました。 # 検索APIで共有リンクのサポートを追加 [検索API](e://get_search)では、ユーザーが最近共有リンクを介してアクセスしたファイル、フォルダ、およびウェブリンクが返されるようになりました。 共有項目をリクエストするには、新しい`include_recent_shared_links`クエリパラメータを`true`に設定して[`GET /search`](e://get_search) APIを呼び出します。 ``` curl -i -X GET https://api.box.com/2.0/search?query=Contract&include_recent_shared_link=true ``` このクエリパラメータが指定されていない場合またはtrueに設定されていない場合、デフォルトでは、このAPIによって共有項目が返されることはありません。 ## レスポンス形式の変更 `include_recent_shared_links`を`true`に設定した場合、追加情報を返すことができるようにレスポンスが若干変更されました。APIでは、ファイル、フォルダ、およびウェブリンクの直接的なリストではなく、`item`と`accessible_via_shared_link`プロパティを含むオブジェクトのリストが返されるようになりました。 ``` { "entries": [ { "item": { "id": 12345, "etag": 1, "type": "file", "sequence_id": 3, "name": "Contract.pdf", ... }, "accessible_via_shared_link": "https://www.box.com/s/vspke7y05sb214wjokpk" } ... ], "limit": 1000, "offset": 2000, "total_count": 5000 } ``` ``` { "entries": [ { "id": 12345, "etag": 1, "type": "file", "sequence_id": 3, "name": "Contract.pdf", ... }, ... ], "limit": 1000, "offset": 2000, "total_count": 5000 } ``` このレスポンス形式の変更は、新しいクエリパラメータを使用して行われるAPIコールのみに適用されるため、既存のアプリケーションに影響することはありません。 **Source:** [https://ja.developer.box.com/changelog/2020-10-08-search-api-adds-support-for-shared-links](https://ja.developer.box.com/changelog/2020-10-08-search-api-adds-support-for-shared-links) --- ### 検索APIで新しい`multiSelect`メタデータがサポート **Type:** changelog | **Section:** Changelog 検索APIで新しいmultiSelectメタデータがサポート 本日以降、検索APIでは、multiSelectメタデータフィールドの複数の値による項目の照合がサポートされるようになりました。この変更が行われる前は、multiSelectフィールドの値で項目を検索することはできませんでした。 メタデータフィールドが複数の値と一致する項目の検索を実行するために、mdfiltersパラメータでは値のリストがサポートされるようになりました。 # 検索APIで新しいmultiSelectメタデータがサポート 本日以降、[検索API](e://get_search)では、[`multiSelect`メタデータフィールド](g://metadata/fields/multi-select)の複数の値による項目の照合がサポートされるようになりました。この変更が行われる前は、`multiSelect`フィールドの値で項目を検索することはできませんでした。 メタデータフィールドが複数の値と一致する項目の検索を実行するために、`mdfilters`パラメータでは値のリストがサポートされるようになりました。 ``` curl -G 'https://api.box.com/2.0/search' \ -H 'Authorization: Bearer <ACCESS_TOKEN>' \ -d 'mdfilters=[{"scope":"enterprise_12345","templateKey":"contractInfo","filters":{"products":["shield","platform"]}}]' ``` この例の`mdfilters`クエリパラメータには、`scope`、`templateKey`、一連の`filters`を含むフィルタが1つ指定されています。 ``` [ { "scope": "enterprise_12345", "templateKey": "contractInfo", "filters": { "products": [ "shield", "platform" ] } } ] ``` 今回、ここでは新しく、`products`に対するフィルタは複数の値で検索できるようになりました。これにより、テンプレートの`products`値が`shield`または`platform`のいずれかであるファイルおよびフォルダのみが返されます。フィルタには複数の値を含めることができ、フィルタに指定された値のうち1つでも値があれば一致します。たとえば、`["shield", "governance"]`に対してフィルタ`["shield", "platform"]`が一致するのは、`shield`がフィルタに含まれているためです。 **Source:** [https://ja.developer.box.com/changelog/2020-08-25-multi-select-metadata-support-in-search-api](https://ja.developer.box.com/changelog/2020-08-25-multi-select-metadata-support-in-search-api) --- ### 検索APIのレスポンスの新しい`type`フィールド **Type:** changelog | **Section:** Changelog 検索APIのレスポンスの新しいtypeフィールド 返された共有リンク項目の検索結果レスポンスオブジェクトに、新しいフィールドtypeが導入されました。 このレスポンスオブジェクト形式が返されるのは、include_recent_shared_linksクエリパラメータをtrue… # 検索APIのレスポンスの新しいtypeフィールド 返された共有リンク項目の[検索結果レスポンスオブジェクト](https://developer.box.com/reference/resources/search-result-with-shared-link/)に、新しいフィールド`type`が導入されました。 このレスポンスオブジェクト形式が返されるのは、`include_recent_shared_links`クエリパラメータを`true`に設定した状態で[コンテンツの検索](https://developer.box.com/reference/get-search/)エンドポイントを呼び出した場合のみです。 現在このレスポンスオブジェクトを使用している既存のアプリケーションに影響はありません。 ## 更新内容 このリリースより前は、共有リンクの検索結果の戻りオブジェクトに次の2つのオブジェクトが含まれていました。 - `accessible_via_shared_link`: 項目にアクセスできる共有リンク。 - `item`: 検索クエリに一致したファイル、フォルダ、またはウェブリンク。 ``` { "accessible_via_shared_link": "https://www.box.com/s/vfejh7y01sb263wjtgfe", "item": { ... } } ``` この更新により、新しい`type`フィールドが導入されました。これは、常に`search_result`に設定される文字列です。 ``` { "type": "search_result", "accessible_via_shared_link": "https://www.box.com/s/vfejh7y01sb263wjtgfe", "item": { ... } } ``` 形式の詳細については、[共有リンクの検索結果](https://developer.box.com/reference/resources/search-result-with-shared-link/)レスポンスオブジェクトを参照してください。 **Source:** [https://ja.developer.box.com/changelog/2020-12-03-new-type-field-in-search-api-responses](https://ja.developer.box.com/changelog/2020-12-03-new-type-field-in-search-api-responses) --- ### 検索APIの新しいクエリパラメータ **Type:** changelog | **Section:** Changelog 検索APIの新しいクエリパラメータ 新しいフィールドrecent_updater_user_idsを使用してAPIでのコンテンツの検索にフィルタをかけられるようになりました。 # 検索APIの新しいクエリパラメータ 新しいフィールド`recent_updater_user_ids`を使用してAPIでのコンテンツの検索にフィルタをかけられるようになりました。 ## 更新内容 - [`GET /get-search`](e://get-search/#param-recent_updater_user_ids) APIエンドポイントに新しいクエリパラメータ`recent_updater_user_ids`を追加 ## 機能 - 指定したユーザーリスト (ユーザーIDのコンマ区切りリストとして定義) によって更新された項目のみに検索結果を絞り込みます。 - この機能では、項目の過去10バージョンのみを検索します。 ### cURLの例 ``` curl -i -X GET "https://api.box.com/2.0/search?query=sales&recent_updater_user_ids=1234567890,2314567890" \ -H "Authorization: Bearer <ACCESS_TOKEN>" ``` ## サポート情報 問題がある場合やさらにガイドが必要な場合は、必要なサポートについて、Boxの[Developer Forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum)に英語でリクエストを投稿してください。 **Source:** [https://ja.developer.box.com/changelog/2022-03-25-new-search-api-query-parameter](https://ja.developer.box.com/changelog/2022-03-25-new-search-api-query-parameter) --- ### 検索APIの新しいパラメータ **Type:** changelog | **Section:** Changelog 検索APIの新しいパラメータ Search APIで、新しいクエリパラメータであるsortとdirection (省略可) を使用できるようになりました。 このパラメータの目的は、アプリケーションが項目をmodified_at日付で昇順または降順にソートできるようにすることです。 # 検索APIの新しいパラメータ [Search API](e://get-search)で、新しいクエリパラメータである`sort`と`direction` (省略可) を使用できるようになりました。 このパラメータの目的は、アプリケーションが項目を`modified_at`日付で昇順または降順にソートできるようにすることです。 **Source:** [https://ja.developer.box.com/changelog/2019-10-25-new-parameters-for-search-api](https://ja.developer.box.com/changelog/2019-10-25-new-parameters-for-search-api) --- ### 検索の関連度とパフォーマンスの更新 **Type:** changelog | **Section:** Changelog 検索の関連度とパフォーマンスの更新 1月に、Boxの検索用トークナイザに対する更新がリリースされ、検索結果の関連性とパフォーマンスが向上しました。今回の変更によるメタデータのトークン化への影響はありません。 APIによる検索の注目すべき変更点は以下のとおりです。 「the… # 検索の関連度とパフォーマンスの更新 1月に、Boxの検索用[トークナイザ](https://en.wikipedia.org/wiki/Lexical_analysis#Tokenization)に対する更新がリリースされ、検索結果の関連性とパフォーマンスが向上しました。今回の変更によるメタデータのトークン化への影響はありません。 APIによる検索の注目すべき変更点は以下のとおりです。 - 「the」、「is」、「at」、「which」、「on」などの「[ストップワード](https://en.wikipedia.org/wiki/Stop_words)」が使用可能になりました - 日本語テキストのトークン化が改善され、検索結果が向上しました BoxのAPIを使用した検索方法の詳細については、[ファイルコンテンツ検索](g://search)に関するドキュメントを参照してください。 **Source:** [https://ja.developer.box.com/changelog/2020-07-30-updates-to-search-relevance-performance](https://ja.developer.box.com/changelog/2020-07-30-updates-to-search-relevance-performance) --- ### 空のOAuth 2リダイレクトURIの変更 **Type:** changelog | **Section:** Changelog 空のOAuth 2リダイレクトURIの変更 2020年9月28日に、OAuth 2アプリリダイレクトURIのセキュリティ要件に対して変更が予定されていることをお知らせしました。今後、空のリダイレクトURI… # 空のOAuth 2リダイレクトURIの変更 2020年9月28日に、[OAuth 2アプリリダイレクトURIのセキュリティ要件](https://developer.box.com/changelog/#2020-09-29-changes-to-oauth-2-app-redirect-url-requirements)に対して変更が予定されていることをお知らせしました。今後、空のリダイレクトURIを使用するアプリケーションは認められなくなり、ユーザーをリダイレクトしようとすると、一致しないURIがあることを示す`redirect_uri missing`というエラーが発生するようになります。 影響を受けるアプリケーションは、アプリケーションとアカウントに関連付けられた開発者のメールアドレス宛ての複数のメールを受信することになり、機能を維持できるようにこの変更の適用から除外された一部のアプリケーションに含まれます。 新しいアプリケーションや、リダイレクトURIが指定されているOAuth 2アプリケーションは影響を受けません。 ## OAuth 2アプリリダイレクトURIを更新する方法 OAuth 2アプリケーションでリダイレクト時にエラーが発生し始めたら、この変更による影響を受けている可能性があります。アプリケーションを更新するには、以下の手順に従ってください。 - アプリケーションを所有するユーザーとして、[Box開発者コンソール](https://cloud.app.box.com/developers/console)に移動します。 - 上部のナビゲーションで [**構成**] をクリックします。 - [**OAuth 2.0リダイレクトURI**] セクションまで下にスクロールします。  - このURIが空のアプリケーションでは、<c0>こちらのガイドで説明されているように<c0>、Boxの認証手順からアプリケーションにユーザーをリダイレクトする際にアプリケーションコードで使用されるURIを追加します。 **Source:** [https://ja.developer.box.com/changelog/2020-12-14-blank-oauth2-redirect-uri-change](https://ja.developer.box.com/changelog/2020-12-14-blank-oauth2-redirect-uri-change) --- ### 統合マッピングAPI **Type:** changelog | **Section:** Changelog 統合マッピングAPI 統合マッピングを使用すると、パートナーアプリからのコンテンツがBoxのどこに保存されるかを管理できます。 現在、この機能ではSlackのコンテンツレイヤーとしてBox… # 統合マッピングAPI [統合マッピング](r://integration-mappings)を使用すると、パートナーアプリからのコンテンツがBoxのどこに保存されるかを管理できます。 現在、この機能では[SlackのコンテンツレイヤーとしてBoxを使用する](https://support.box.com/hc/en-us/articles/4415585987859-Box-as-the-Content-Layer-for-Slack)場合のみサポートします。 ## サポート情報 問題がある場合やさらにガイドが必要な場合は、必要なサポートについて、Boxの[Developer Forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum)に英語でリクエストを投稿してください。 **Source:** [https://ja.developer.box.com/changelog/2023-05-24-integration-mappings-API](https://ja.developer.box.com/changelog/2023-05-24-integration-mappings-API) --- ### 署名リクエストAPIの改善 **Type:** changelog | **Section:** Changelog 署名リクエストAPIの改善 署名リクエストステータスパラメータに次の2つの値が追加されました。 finalizing: すべての署名者がリクエストに署名済みで、署名された最終的なドキュメントと署名ログがまだ生成されていない状態を示します。 error_finalizing: finalizingフェーズが正常に完了しなかった状態を示します。 # 署名リクエストAPIの改善 [署名リクエストステータス](r://sign-request#param-status)パラメータに次の2つの値が追加されました。 - `finalizing`: すべての署名者がリクエストに署名済みで、署名された最終的なドキュメントと署名ログがまだ生成されていない状態を示します。 - `error_finalizing`: `finalizing`フェーズが正常に完了しなかった状態を示します。 ## サポート情報 問題がある場合やさらにガイドが必要な場合は、必要なサポートについて、Boxの[Developer Forum](https://forum.box.com/)に英語でリクエストを投稿してください。 **Source:** [https://ja.developer.box.com/changelog/2023-07-12-sign-request-status](https://ja.developer.box.com/changelog/2023-07-12-sign-request-status) --- ### 署名リクエストへの新しいフィールドの追加 **Type:** changelog | **Section:** Changelog 署名リクエストへの新しいフィールドの追加 Box Signのリクエストのレスポンスオブジェクトに、新しいフィールドcontent_typeが含まれるようになりました。このフィールドは、署名者の入力用に選択されたinputのtypeに想定されるコンテンツタイプを識別します。 # 署名リクエストへの新しいフィールドの追加 Box Signのリクエストのレスポンスオブジェクトに、新しいフィールド`content_type`が含まれるようになりました。このフィールドは、署名者の入力用に選択された`input`の`type`に想定されるコンテンツタイプを識別します。 ## 更新内容 - [署名リクエストのレスポンスオブジェクト](r://sign-request/#param-signers-inputs-content_type)に新しいフィールド`content_type`を追加 ## サポート情報 問題がある場合やさらにガイドが必要な場合は、Boxの[Developer Forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum)に英語でリクエストを投稿してください。 **Source:** [https://ja.developer.box.com/changelog/2022-05-12-new-sign-requests-field](https://ja.developer.box.com/changelog/2022-05-12-new-sign-requests-field) --- ### 要件の変更に伴うOAuth 2.0リダイレクトURIの更新 **Type:** changelog | **Section:** Changelog 要件の変更に伴うOAuth 2.0リダイレクトURIの更新 Box開発者コンソールの新機能をリリースしました。開発者は、この新機能を使用して、OAuth 2.0アプリケーション用に複数のリダイレクトURIを追加できるようになります。 # 要件の変更に伴うOAuth 2.0リダイレクトURIの更新 Box開発者コンソールの新機能をリリースしました。開発者は、この新機能を使用して、OAuth 2.0アプリケーション用に複数のリダイレクトURIを追加できるようになります。 日本時間2021年11月30日以降、OAuth 2.0を使用する新規のアプリケーションでは、開発者コンソールの [構成] タブで設定されたURIとリダイレクト時に使用されるURIが厳密に一致する必要があります。また、そのため新規のアプリケーションと既存のアプリケーションの両方で、複数のリダイレクトURIを追加できるようになります。 既存のアプリケーションでは、サービスの中断を回避するために、日本時間2022年5月14日までにこのURLを変更する必要があります。 ## 更新内容 - Box開発者コンソールのOAuth 2.0アプリケーションの [構成] セクションに、複数のリダイレクトURIを追加するための新しいボタンが用意されました - リダイレクトURIは、渡されたURIと、OAuth 2.0アプリケーションの構成で設定されたURIを一致させるように厳密なチェックを強制するようになりました - [`GET /authorize`](e://get-authorize/#param-redirect_uri)エンドポイントのページで`redirect_uri`クエリパラメータの表現を更新しました - OAuth 2.0の[設定](g://authentication/oauth2/oauth2-setup/)、[SDKを使用したOAuth 2.0](g://authentication/oauth2/with-sdk/)、[SDKを使用しないOAuth 2.0](g://authentication/oauth2/without-sdk/)に関するガイドページを更新しました ## サポート情報 問題がある場合やさらにガイドが必要な場合は、必要なサポートについて、Boxの[Developer Forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum)に英語でリクエストを投稿してください。 **Source:** [https://ja.developer.box.com/changelog/2021-11-29-oauth-20-redirect-url-updates](https://ja.developer.box.com/changelog/2021-11-29-oauth-20-redirect-url-updates) --- ### 開発者コンソールでのWebhook V2の管理 **Type:** changelog | **Section:** Changelog 開発者コンソールでのWebhook V2の管理 アプリケーションのWebhookの管理が簡単で効率的になりました。開発者コンソールの [Webhook] タブだけで、アプリケーションのすべてのWebhookを確認できます。開発者コンソールのユーザーインターフェースを使用して、V… # 開発者コンソールでのWebhook V2の管理 アプリケーションのWebhookの管理が簡単で効率的になりました。[開発者コンソール](https://app.box.com/developers/console)の [**Webhook**] タブだけで、アプリケーションのすべてのWebhookを確認できます。[開発者コンソール](https://app.box.com/developers/console)のユーザーインターフェースを使用して、V2 Webhookを[作成](g://webhooks/v2/create-v2)、[更新](g://webhooks/v2/update-v2)、または[削除](g://webhooks/v2/delete-v2)できるようになりました。 ## サポート情報 問題がある場合やさらにガイドが必要な場合は、必要なサポートについて、Boxの[Developer Forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum)に英語でリクエストを投稿してください。 **Source:** [https://ja.developer.box.com/changelog/2022-10-19-webhooksv2-in-developer-console](https://ja.developer.box.com/changelog/2022-10-19-webhooksv2-in-developer-console) --- ### 開発者コンソールのアップデート **Type:** changelog | **Section:** Changelog 開発者コンソールのアップデート 開発者コンソールで新しく [承認] タブが使用可能になりました。さらに、[構成] タブ内の [アプリケーションアクセス] と [Scope (スコープ)] の設定でUIがわかりやすく変更されたことで、設定を決定しやすくなりました。このような変更は、設定の機能には影響しません。 # 開発者コンソールのアップデート 開発者コンソールで新しく [**承認**] タブが使用可能になりました。さらに、[**構成**] タブ内の [**アプリケーションアクセス**] と [**Scope (スコープ)**] の設定でUIがわかりやすく変更されたことで、設定を決定しやすくなりました。このような変更は、設定の機能には影響しません。 これで、開発者は [**承認**] タブに移動して、承認を得るためにアプリケーションを直接Box管理者に送信するようになります。 [**構成**] タブに関しては、JWTの [**アプリケーションアクセス**] の設定に役立つヒントが追加されたため、[**アプリアクセスのみ**] と [**アプリアクセス + Enterpriseアクセス**] のどちらにするかを明確に決めやすくなりました。現在、[**Scope (スコープ)**] セクションは、操作の種類 (コンテンツ操作、管理操作、管理者操作) でグループ化されています。 - **アプリの承認プロセス**: [ガイド](g://authorization/custom-app-approval) - **スコープ**: [ガイド](g://api-calls/permissions-and-errors/scopes) - **アプリケーションアクセス**: [ガイド](g://authentication/jwt/jwt-setup/#application-access) ## 更新内容 - 開発者コンソールに [承認] タブを追加しました - [構成] タブでJWTの [アプリケーションアクセス] の設定用UIを更新しました - [構成] タブで [Scopes (スコープ)] のUIのグループ化を更新しました **Source:** [https://ja.developer.box.com/changelog/2021-01-14-developer-console-updates](https://ja.developer.box.com/changelog/2021-01-14-developer-console-updates) --- ### 開発者コンソールの強化された \[マイアプリ] ビューの導入 **Type:** changelog | **Section:** Changelog 開発者コンソールの強化された [マイアプリ] ビューの導入 アプリケーション管理のエクスペリエンスをさらに改善するために、開発者コンソールに [マイアプリ] リストビューを導入します。このビューには、アプリケーションに関する主な情報が表示されるため、以下の操作が可能になります。 アプリケーションのクライアントIDを表示およびコピーする アプリケーションの説明を表示する カスタムアプリケーションを並べ替える アプリケーションの承認ステータスと有効化ステータスを確認する 構成にアクセスして、開発者トークンを生成する # 開発者コンソールの強化された [マイアプリ] ビューの導入 アプリケーション管理のエクスペリエンスをさらに改善するために、開発者コンソールに [[マイアプリ](g://applications)] リストビューを導入します。このビューには、アプリケーションに関する主な情報が表示されるため、以下の操作が可能になります。 - アプリケーションのクライアントIDを表示およびコピーする - アプリケーションの説明を表示する - カスタムアプリケーションを並べ替える - アプリケーションの承認ステータスと有効化ステータスを確認する - 構成にアクセスして、開発者トークンを生成する ## サポート情報 問題がある場合やさらにガイドが必要な場合は、必要なサポートについて、Boxの[Developer Forum](https://forum.box.com/)に英語でリクエストを投稿してください。 **Source:** [https://ja.developer.box.com/changelog/2023-12-11-introducing-my-apps-view](https://ja.developer.box.com/changelog/2023-12-11-introducing-my-apps-view) --- ### 開発者コンソールへのサービスアカウントのメールアドレスの追加 **Type:** changelog | **Section:** Changelog 開発者コンソールへのサービスアカウントのメールアドレスの追加 サーバー認証を利用するアプリケーションを管理者が承認すると、サービスアカウントの自動生成メールアドレスが開発者コンソールの [一般] タブに表示されるようになりました。その後、このメールアドレスは、Box… # 開発者コンソールへのサービスアカウントのメールアドレスの追加 サーバー認証を利用するアプリケーションを管理者が承認すると、サービスアカウントの自動生成メールアドレスが開発者コンソールの [一般] タブに表示されるようになりました。その後、このメールアドレスは、Boxコンテンツでユーザーをコラボレータに設定するために使用できます。これは、必ず`AutomationUser_AppServiceID_RandomString@boxdevedition.com`形式になります (例: `AutomationUser_123456_6jCo6Pqwo@boxdevedition.com`)。 詳細については、[ユーザータイプ](https://developer.box.com/guides/authentication/user-types/)と[サービスアカウント](https://developer.box.com/guides/authentication/user-types/service-account/)のガイドを参照してください。 ## 機能 - サービスアカウントユーザーの自動生成メールアドレスを開発者コンソールに追加 **Source:** [https://ja.developer.box.com/changelog/2021-03-25-service-account-information-in-developer-console](https://ja.developer.box.com/changelog/2021-03-25-service-account-information-in-developer-console) --- ### 項目ダウンロードイベントの動作変更のお知らせ **Type:** changelog | **Section:** Changelog 項目ダウンロードイベントの動作変更のお知らせ 本日以降、アプリケーションがBoxのイベントAPIエンドポイントから項目ダウンロードイベントを使用した場合のこのイベントの動作に対する変更のリリースを開始します。 この変更はITEM_DOWNLOADUser Eventのみに影響し、既存のEnterprise Eventには影響しません。この新しい動作により、既存のアプリケーション内でダウンタイムが発生することはありません。また、稼働時間の中断を防ぐためのアプリケーションの変更も必要ありません。 # 項目ダウンロードイベントの動作変更のお知らせ 本日以降、アプリケーションがBoxの[イベントAPIエンドポイント](https://developer.box.com/reference/get-events/)から項目ダウンロードイベントを使用した場合のこのイベントの動作に対する変更のリリースを開始します。 この変更は`ITEM_DOWNLOAD`[User Event](https://developer.box.com/guides/events/user-events/for-user/#event-types)のみに影響し、既存の[Enterprise Event](https://developer.box.com/guides/events/enterprise-events/for-enterprise/)には影響しません。この新しい動作により、既存のアプリケーション内でダウンタイムが発生することはありません。また、稼働時間の中断を防ぐためのアプリケーションの変更も必要ありません。 ## 変更の概要 以前の動作では、イベントを使用した場合、ダウンロードされた項目イベントが、コンテンツの所有者およびコンテンツに割り当てられたすべてのコラボレータのイベントタイプ`ITEM_DOWNLOAD`によって表示されました。つまり、2,000人のコラボレータが存在するファイルがダウンロードされた場合、このファイルの所有者に加えて2,000人のコラボレータ全員に、ファイルがダウンロードされたことを示すイベントが作成されます。 新しい動作では、項目のダウンロードに関する通知がコンテンツの所有者に対してのみ作成され、コラボレータに対しては生成されません。これは、コンテンツの所有者としていつ項目がダウンロードされたかを確認できるようにしたままイベントストリームのノイズを低減するのに役立ちます。 ## サポート情報 問題がある場合やさらにガイドが必要な場合は、必要なサポートについて、Boxの[Developer Forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum)に英語でリクエストを投稿してください。 **Source:** [https://ja.developer.box.com/changelog/2021-04-15-notice-of-behavior-change-for-item_download-events](https://ja.developer.box.com/changelog/2021-04-15-notice-of-behavior-change-for-item_download-events) --- ### 項目プレビューイベントの動作変更のお知らせ **Type:** changelog | **Section:** Changelog 項目プレビューイベントの動作変更のお知らせ 本日以降、アプリケーションがBoxのイベントAPIエンドポイントから項目プレビューイベントを使用した場合のこのイベントの動作に対する変更のリリースを開始します。 この変更はITEM_PREVIEWUser Eventのみに影響し、既存のEnterprise Eventには影響しません。この新しい動作により、既存のアプリケーション内でダウンタイムが発生することはありません。また、稼働時間の中断を防ぐためのアプリケーションの変更も必要ありません。 # 項目プレビューイベントの動作変更のお知らせ 本日以降、アプリケーションがBoxの[イベントAPIエンドポイント](https://developer.box.com/reference/get-events/)から項目プレビューイベントを使用した場合のこのイベントの動作に対する変更のリリースを開始します。 この変更は`ITEM_PREVIEW`[User Event](https://developer.box.com/guides/events/enterprise-events/for-user/#event-types)のみに影響し、既存の[Enterprise Event](https://developer.box.com/guides/events/user-events/for-enterprise/)には影響しません。この新しい動作により、既存のアプリケーション内でダウンタイムが発生することはありません。また、稼働時間の中断を防ぐためのアプリケーションの変更も必要ありません。 ## 変更の概要 以前の動作では、イベントを使用した場合、プレビューされた項目イベントが、コンテンツの所有者およびコンテンツに割り当てられたすべてのコラボレータのイベントタイプ`ITEM_PREVIEW`によって表示されました。つまり、2,000人のコラボレータが存在するファイルがプレビューされた場合、このファイルの所有者に加えて2,000人のコラボレータ全員に、ファイルがプレビューされたことを示すイベントが作成されます。 新しい動作では、項目のプレビューに関する通知がコンテンツの所有者に対してのみ作成され、コラボレータに対しては生成されません。これは、コンテンツの所有者としていつ項目がプレビューされたかを確認できるようにしたままイベントストリームのノイズを低減するのに役立ちます。 ## サポート情報 問題がある場合やさらにガイドが必要な場合は、必要なサポートについて、Boxの[Developer Forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum)に英語でリクエストを投稿してください。 **Source:** [https://ja.developer.box.com/changelog/2021-08-31-notice-of-behavior-change-for-item-preview-events](https://ja.developer.box.com/changelog/2021-08-31-notice-of-behavior-change-for-item-preview-events) --- ### 項目を開くイベントの動作変更のお知らせ **Type:** changelog | **Section:** Changelog 項目を開くイベントの動作変更のお知らせ 本日以降、アプリケーションがBoxのイベントAPIエンドポイントからITEM_OPENイベントを使用した場合のこのイベントの動作に対する変更のリリースを開始します。 この変更はITEM_OPEN Enterprise Event… # 項目を開くイベントの動作変更のお知らせ 本日以降、アプリケーションがBoxの[イベントAPIエンドポイント](https://developer.box.com/reference/get-events)から`ITEM_OPEN`イベントを使用した場合のこのイベントの動作に対する変更のリリースを開始します。 この変更は`ITEM_OPEN` [Enterprise Event](g://events/enterprise-events/for-enterprise)のみに影響します。この新しい動作により、既存のアプリケーション内でダウンタイムが発生することはありません。また、稼働時間の中断を防ぐためのアプリケーションの変更も必要ありません。 ## 変更の概要 以前の動作では、イベントを使用した場合、開かれた項目イベントが、コンテンツの所有者およびコンテンツに割り当てられたすべてのコラボレータのイベントタイプ`ITEM_OPEN`によって表示されました。つまり、2,000人のコラボレータが存在するファイルがDriveなどで開かれた場合、このファイルの所有者に加えて2,000人のコラボレータ全員に、ファイルが開かれたことを示すイベントが作成されます。 新しい動作では、項目が開かれたという通知がコンテンツの所有者に対してのみ作成され、コラボレータに対しては生成されません。これは、コンテンツの所有者としていつ項目が開かれたかを確認できるようにしたままイベントストリームのノイズを低減するのに役立ちます。 ## サポート情報 問題がある場合やさらにガイドが必要な場合は、必要なサポートについて、Boxの[Developer Forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum)に英語でリクエストを投稿してください。 **Source:** [https://ja.developer.box.com/changelog/2021-07-01-notice-of-behavior-change-for-item-open-events](https://ja.developer.box.com/changelog/2021-07-01-notice-of-behavior-change-for-item-open-events) --- ## Additional Resources ### AI **Type:** page | **Section:** Additional Resources AI AI allows to send an intelligence request to supported large language models and returns an answer based on the provided prompt and items… # AI AI allows to send an intelligence request to supported large language models and returns an answer based on the provided prompt and items. [AI](#ai) - [Send AI request](#send-ai-request) - [Send AI text generation request](#send-ai-text-generation-request) - [Get AI agent default configuration](#get-ai-agent-default-configuration) ## Send AI request To send an AI request to the supported large language models, call the [`ai.ask(body, options?, callback?)`](http://opensource.box.com/box-node-sdk/jsdoc/AIManager.html#ask) method with the prompt and items. The `items` parameter is a list of items to be processed by the LLM, often files. The `prompt` provided by the client to be answered by the LLM. The prompt's length is limited to 10000 characters. The `mode` specifies if this request is for a single or multiple items. If you select `single_item_qa` the items array can have one element only. Selecting `multiple_item_qa` allows you to provide up to 25 items. ``` client.ai.ask( { prompt: 'What is the capital of France?', items: [ { type: 'file', id: '12345' } ], mode: 'single_item_qa' }) .then(response => { /* response -> { "answer": "Paris", "created_at": "2021-10-01T00:00:00Z", "completion_reason": "done" } */ }); ``` NOTE: The AI endpoint may return a 412 status code if you use for your request a file which has just been updated to the box. It usually takes a few seconds for the file to be indexed and available for the AI endpoint. ## Send AI text generation request To send an AI text generation request to the supported large language models, call the [`ai.textGen(body, options?, callback?)`](http://opensource.box.com/box-node-sdk/jsdoc/AIManager.html#textGen) method with the prompt, items and dialogue history. The `dialogue_history` parameter is history of prompts and answers previously passed to the LLM. This provides additional context to the LLM in generating the response. The `items` parameter is a list of items to be processed by the LLM, often files. The `prompt` provided by the client to be answered by the LLM. The prompt's length is limited to 10000 characters. ``` client.ai.textGen( { prompt: 'What is the capital of France?', items: [ { type: 'file', id: '12345' } ], dialogue_history: [ { prompt: 'What is the capital of France?', answer: 'Paris', created_at: '2021-10-01T00:00:00Z' }, { prompt: 'What is the capital of Germany?', answer: 'Berlin', created_at: '2021-10-01T00:00:00Z' } ] }) .then(response => { /* response -> { "answer": "The capital of France is Paris.", "created_at": "2021-10-01T00:00:00Z", "completion_reason": "done" } */ }); ``` ## Get AI agent default configuration To get an AI agent default configuration call the [ai.getAiAgentDefaultConfig(options?, callback?)](http://opensource.box.com/box-node-sdk/jsdoc/AIManager.html#getAiAgentDefaultConfig) method. The `mode` parameter filters the agent configuration to be returned. It can be either `ask` or `text_gen`. The `language` parameter specifies the ISO language code to return the agent config for. If the language is not supported, the default agent configuration is returned. The `model` parameter specifies the model for which the default agent configuration should be returned. ``` client.ai.getAiAgentDefaultConfig({ mode: 'ask', language: 'en', model:'openai__gpt_3_5_turbo' }).then(response => { /* response -> { "type": "ai_agent_ask", "basic_text": { "llm_endpoint_params": { "type": "openai_params", "frequency_penalty": 1.5, "presence_penalty": 1.5, "stop": "<|im_end|>", "temperature": 0, "top_p": 1 }, "model": "openai__gpt_3_5_turbo", "num_tokens_for_completion": 8400, "prompt_template": "It is `{current_date}`, and I have $8000 and want to spend a week in the Azores. What should I see?", "system_message": "You are a helpful travel assistant specialized in budget travel" }, ... } */ }); ``` --- ### AI **Type:** page | **Section:** Additional Resources AI AI allows to send an intelligence request to supported large language models and returns an answer based on the provided prompt and items… # AI AI allows to send an intelligence request to supported large language models and returns an answer based on the provided prompt and items. [AI](#ai) - [Send AI request](#send-ai-request) - [Send AI text generation request](#send-ai-text-generation-request) - [Get AI Agent default configuration](#get-ai-agent-default-configuration) - [Extract metadata freeform](#extract-metadata-freeform) - [Extract metadata structured](#extract-metadata-structured) ## Send AI request To send an AI request, call static [`sendAIRequest(String prompt, List<BoxAIItem> items, Mode mode)`](https://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxAI.html#sendAIRequest-com.box.sdk.BoxAPIConnection-java.lang.String-java.util.List-com.box.sdk.BoxAI.Mode-) method. In the request you have to provide a prompt, a list of items that your prompt refers to and a mode of the request. There are two modes available: `SINGLE_ITEM_QA` and `MULTI_ITEM_QA`, which specifies if this request refers to for a single or multiple items. ``` BoxAIResponse response = BoxAI.sendAIRequest( api, "What is the content of the file?", Collections.singletonList("123456", BoxAIItem.Type.FILE), BoxAI.Mode.SINGLE_ITEM_QA ); ``` You can also provide a list of dialogue history entries to provide additional context to the LLM in generating the response, AI Agent configuration and flag to indicate whether citations should be returned. NOTE: The AI endpoint may return a 412 status code if you use for your request a file which has just been updated to the box. It usually takes a few seconds for the file to be indexed and available for the AI endpoint. ## Send AI text generation request To send an AI request specifically focused on the creation of new text, call static [`sendAITextGenRequest(String prompt, List<BoxAIItem> items, List<BoxAIDialogueEntry> dialogueHistory)`](https://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxAI.html#sendAITextGenRequest-com.box.sdk.BoxAPIConnection-java.lang.String-java.util.List-java.util.List-) method. In the request you have to provide a prompt, a list of items that your prompt refers to and optionally a dialogue history, which provides additional context to the LLM in generating the response. ``` List<BoxAIDialogueEntry> dialogueHistory = new ArrayList<>(); dialogueHistory.add( new BoxAIDialogueEntry( "Make my email about public APIs sound more professional", "Here is the first draft of your professional email about public APIs.", BoxDateFormat.parse("2013-05-16T15:26:57-07:00") ) ); BoxAIResponse response = BoxAI.sendAITextGenRequest( api, "Write an email to a client about the importance of public APIs.", Collections.singletonList(new BoxAIItem("123456", BoxAIItem.Type.FILE)), dialogueHistory ); ``` You can also provide an AI Agent configuration to customize the behavior of the AI response generation. ## Get AI Agent default configuration To get the default configuration of the AI Agent, call static [`getAiAgentDefaultConfig(BoxAPIConnection api, BoxAIAgent.Mode mode, String language, String model)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxAI.html#getAiAgentDefaultConfig-com.box.sdk.BoxAPIConnection-com.box.sdk.ai.BoxAIAgent.Mode-java.lang.String-java.lang.String-) method. In the request you have to provide the mode of the AI Agent, the language and the model, with the model is required while the language and mode are optional. ``` BoxAIAgentConfig config = BoxAI.getAiAgentDefaultConfig( api, BoxAIAgent.Mode.ASK, "en", "openai__gpt_3_5_turbo" ); ``` ## Extract metadata freeform To send an AI request to supported Large Language Models (LLMs) and extract metadata in form of key-value pairs, call static [`extractMetadataFreeform(BoxAPIConnection api, String prompt, List<BoxAIItem> items)`](https://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxAI.html#extractMetadataFreeform-com.box.sdk.BoxAPIConnection-java.lang.String-java.util.List-) method. In the request you have to provide a prompt, a list of items that your prompt refers to and an optional agent configuration. ``` BoxAIResponse response = BoxAI.extractMetadataFreeform( api, "firstName, lastName, location, yearOfBirth, company", Collections.singletonList(new BoxAIItem("123456", BoxAIItem.Type.FILE)) ); ``` ## Extract metadata structured Sends an AI request to supported Large Language Models (LLMs) and returns extracted metadata as a set of key-value pairs. For this request, you need to use an already defined metadata template or define a schema yourself. To send an AI request to extract metadata from files with a predefined metadata template, call static [`extractMetadataStructured extractMetadataStructured(BoxAPIConnection api, List<BoxAIItem> items, BoxAIExtractMetadataTemplate template)`](https://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxAI.html#extractMetadataStructured-com.box.sdk.BoxAPIConnection-java.util.List-com.box.sdk.ai.metadata.BoxAIExtractMetadataTemplate-) method. ``` BoxAIExtractMetadataTemplate template = new BoxAIExtractMetadataTemplate("templateKey", "enterprise"); BoxAIExtractStructuredResponse result = BoxAI.extractMetadataStructured( api, Collections.singletonList(new BoxAIItem("123456", BoxAIItem.Type.FILE)), template ); JsonObject sourceJson = result.getSourceJson(); ``` To send an AI request to extract metadata from files with custom fields, call static [`extractMetadataStructured extractMetadataStructured(BoxAPIConnection api, List<BoxAIItem> items, List<BoxAIExtractField> fields)`](https://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxAI.html#extractMetadataStructured-com.box.sdk.BoxAPIConnection-java.util.List-java.util.List-) method. ``` List<BoxAIExtractField> fields = new ArrayList<>(); fields.add(new BoxAIExtractField("firstName")); BoxAIExtractStructuredResponse result = BoxAI.extractMetadataStructured( api, Collections.singletonList(new BoxAIItem("123456", BoxAIItem.Type.FILE)), fields ); JsonObject sourceJson = result.getSourceJson(); ``` --- ### AI **Type:** page | **Section:** Additional Resources AI AI allows to send an intelligence request to supported large language models and returns an answer based on the provided prompt and items… # AI AI allows to send an intelligence request to supported large language models and returns an answer based on the provided prompt and items. - [Send AI request](#send-ai-request) - [Send AI text generation request](#send-ai-text-generation-request) - [Get AI agent default configuration](#get-ai-agent-default-configuration) ## Send AI request Calling the [`client.send_ai_question(items, prompt, mode, ai_agent)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.client.html#boxsdk.client.client.Client.send_ai_question) method will send an AI request to the supported large language models. The `items` parameter is a list of items to be processed by the LLM, often files. The `prompt` provided by the client to be answered by the LLM. The prompt's length is limited to 10000 characters. The `mode` specifies if this request is for a single or multiple items. If you select `single_item_qa` the items array can have one element only. Selecting `multiple_item_qa` allows you to provide up to 25 items. The `ai_agent` specifies the AI agent which will be used to handle queries. ``` items = [{ "id": "1582915952443", "type": "file", "content": "More information about public APIs" }] ai_agent = { 'type': 'ai_agent_ask', 'basic_text_multi': { 'model': 'openai__gpt_3_5_turbo' } } answer = client.send_ai_question( items=items, prompt="What is this file?", mode="single_item_qa", ai_agent=ai_agent ) print(answer) ``` NOTE: The AI endpoint may return a 412 status code if you use for your request a file which has just been updated to the box. It usually takes a few seconds for the file to be indexed and available for the AI endpoint. ## Send AI text generation request Calling the [`client.send_ai_text_gen(dialogue_history, items, prompt, ai_agent)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.client.html#boxsdk.client.client.Client.send_ai_text_gen) method will send an AI text generation request to the supported large language models. The `dialogue_history` parameter is history of prompts and answers previously passed to the LLM. This provides additional context to the LLM in generating the response. The `items` parameter is a list of items to be processed by the LLM, often files. The `prompt` provided by the client to be answered by the LLM. The prompt's length is limited to 10000 characters. The `ai_agent` specifies the AI agent which will be used for generating text. ``` items = [{ "id": "1582915952443", "type": "file", "content": "More information about public APIs" }] dialogue_history = [{ "prompt": "Make my email about public APIs sound more professional", "answer": "Here is the first draft of your professional email about public APIs", "created_at": "2013-12-12T10:53:43-08:00" }, { "prompt": "Can you add some more information?", "answer": "Public API schemas provide necessary information to integrate with APIs...", "created_at": "2013-12-12T11:20:43-08:00" }] ai_agent = { 'type': 'ai_agent_text_gen', 'basic_gen': { 'model': 'openai__gpt_3_5_turbo_16k' } } answer = client.send_ai_text_gen( dialogue_history=dialogue_history, items=items, prompt="Write an email to a client about the importance of public APIs.", ai_agent=ai_agent ) print(answer) ``` ## Get AI agent default configuration To get an AI agent default configuration call the [`client.get_ai_agent_default_config(mode, language, model)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.client.html#boxsdk.client.client.Client.get_ai_agent_default_config) method. The `mode` parameter filters the agent configuration to be returned. It can be either `ask` or `text_gen`. The `language` parameter specifies the ISO language code to return the agent config for. If the language is not supported, the default agent configuration is returned. The `model` parameter specifies the model for which the default agent configuration should be returned. ``` config = client.get_ai_agent_default_config( mode='text_gen', language='en', model='openai__gpt_3_5_turbo' ) print(config) ``` --- ### AI **Type:** page | **Section:** Additional Resources AI AI allows to send an intelligence request to supported large language models and returns an answer based on the provided prompt and items… # AI AI allows to send an intelligence request to supported large language models and returns an answer based on the provided prompt and items. - [Send AI question](#send-ai-request) - [Send AI text generation request](#send-ai-text-generation-request) ## Send AI question To send an AI request, use `BoxAIManager.SendAIQuestionAsync(BoxAIAskRequest aiAskRequest)` method In the request you have to provide a prompt, a list of items that your prompt refers to and a mode of the request. There are two modes available: `single_item_qa` and `multiple_item_qa`, which specifies if this request refers to for a single or multiple items. ``` BoxAIResponse response = await client.BoxAIManager.SendAIQuestionAsync( new BoxAIAskRequest { Prompt = "What is the name of the file?", Items = new List<BoxAIAskItem>() { new BoxAIAskItem() { Id = "12345" } }, Mode = AiAskMode.single_item_qa }; ); ``` NOTE: The AI endpoint may return a 412 status code if you use for your request a file which has just been updated to the box. It usually takes a few seconds for the file to be indexed and available for the AI endpoint. ## Send AI text generation request To send an AI request specifically focused on the creation of new text, call `BoxAIManager.SendAITextGenRequestAsync(BoxAiTextGenRequest aiTextGenRequest)` method. In the request you have to provide a prompt, a list of items that your prompt refers to and optionally a dialogue history, which provides additional context to the LLM in generating the response. ``` BoxAIResponse response = await client.BoxAIManager.SendAITextGenRequestAsync( new BoxAITextGenRequest { Prompt = "What is the name of the file?", Items = new List<BoxAITextGenItem>() { new BoxAITextGenItem() { Id = "12345" } }, DialogueHistory = new List<BoxAIDialogueHistory>() { new BoxAIDialogueHistory() { Prompt = "What is the name of the file?", Answer = "MyFile", CreatedAt = DateTimeOffset.Parse("2024-05-16T15:26:57-07:00") } new BoxAIDialogueHistory() { Prompt = "What is the size of the file?", Answer = "10kb", CreatedAt = DateTimeOffset.Parse("2024-05-16T15:26:57-07:00") } } }; ); ``` --- ### AiManager **Type:** page | **Section:** Additional Resources AiManager Ask question Generate text Get AI agent default configuration Extract metadata (freeform) Extract metadata (structured) Ask… # AiManager - [Ask question](#ask-question) - [Generate text](#generate-text) - [Get AI agent default configuration](#get-ai-agent-default-configuration) - [Extract metadata (freeform)](#extract-metadata-freeform) - [Extract metadata (structured)](#extract-metadata-structured) ## Ask question Sends an AI request to supported LLMs and returns an answer specifically focused on the user's question given the provided context. This operation is performed by calling function `createAiAsk`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-ai-ask/). ``` await client.ai.createAiAsk({ mode: 'single_item_qa' as AiAskModeField, prompt: 'which direction sun rises', items: [ { id: fileToAsk.id, type: 'file' as AiItemAskTypeField, content: 'Sun rises in the East', } satisfies AiItemAsk, ], aiAgent: aiAskAgentConfig, } satisfies AiAsk); ``` ### Arguments requestBody `AiAsk` - Request body of createAiAsk method optionalsInput `CreateAiAskOptionalsInput` ### Returns This function returns a value of type `undefined | AiResponseFull`. A successful response including the answer from the LLM.No content is available to answer the question. This is returned when the request item is a hub, but content in the hubs is not indexed. To ensure content in the hub is indexed, make sure Box AI for Hubs in the Admin Console was enabled before hub creation. ## Generate text Sends an AI request to supported Large Language Models (LLMs) and returns generated text based on the provided prompt. This operation is performed by calling function `createAiTextGen`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-ai-text-gen/). ``` await client.ai.createAiTextGen({ prompt: 'Parapharse the document.s', items: [ new AiTextGenItemsField({ id: fileToAsk.id, type: 'file' as AiTextGenItemsTypeField, content: 'The Earth goes around the sun. Sun rises in the East in the morning.', }), ], dialogueHistory: [ { prompt: 'What does the earth go around?', answer: 'The sun', createdAt: dateTimeFromString('2021-01-01T00:00:00Z'), } satisfies AiDialogueHistory, { prompt: 'On Earth, where does the sun rise?', answer: 'East', createdAt: dateTimeFromString('2021-01-01T00:00:00Z'), } satisfies AiDialogueHistory, ], aiAgent: aiTextGenAgentConfig, } satisfies AiTextGen); ``` ### Arguments requestBody `AiTextGen` - Request body of createAiTextGen method optionalsInput `CreateAiTextGenOptionalsInput` ### Returns This function returns a value of type `AiResponse`. A successful response including the answer from the LLM. ## Get AI agent default configuration Get the AI agent default config. This operation is performed by calling function `getAiAgentDefaultConfig`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-ai-agent-default/). ``` await client.ai.getAiAgentDefaultConfig({ mode: 'ask' as GetAiAgentDefaultConfigQueryParamsModeField, language: 'en-US', } satisfies GetAiAgentDefaultConfigQueryParams); ``` ### Arguments queryParams `GetAiAgentDefaultConfigQueryParams` - Query parameters of getAiAgentDefaultConfig method optionalsInput `GetAiAgentDefaultConfigOptionalsInput` ### Returns This function returns a value of type `AiAgentAskOrAiAgentExtractOrAiAgentExtractStructuredOrAiAgentTextGen`. A successful response including the default agent configuration. This response can be one of the following four objects: - AI agent for questions - AI agent for text generation - AI agent for freeform metadata extraction AI agent for structured metadata extraction. The response depends on the agent configuration requested in this endpoint. ## Extract metadata (freeform) Sends an AI request to supported Large Language Models (LLMs) and extracts metadata in form of key-value pairs. In this request, both the prompt and the output can be freeform. Metadata template setup before sending the request is not required. This operation is performed by calling function `createAiExtract`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-ai-extract/). ``` await client.ai.createAiExtract({ prompt: 'firstName, lastName, location, yearOfBirth, company', items: [new AiItemBase({ id: file.id })], aiAgent: agentIgnoringOverridingEmbeddingsModel, } satisfies AiExtract); ``` ### Arguments requestBody `AiExtract` - Request body of createAiExtract method optionalsInput `CreateAiExtractOptionalsInput` ### Returns This function returns a value of type `AiResponse`. A response including the answer from the LLM. ## Extract metadata (structured) Sends an AI request to supported Large Language Models (LLMs) and returns extracted metadata as a set of key-value pairs. For this request, you either need a metadata template or a list of fields you want to extract. Input is **either** a metadata template or a list of fields to ensure the structure. To learn more about creating templates, see [Creating metadata templates in the Admin Console](https://support.box.com/hc/en-us/articles/360044194033-Customizing-Metadata-Templates) or use the [metadata template API](g://metadata/templates/create). This operation is performed by calling function `createAiExtractStructured`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-ai-extract-structured/). ``` await client.ai.createAiExtractStructured({ fields: [ { key: 'firstName', displayName: 'First name', description: 'Person first name', prompt: 'What is the your first name?', type: 'string', } satisfies AiExtractStructuredFieldsField, { key: 'lastName', displayName: 'Last name', description: 'Person last name', prompt: 'What is the your last name?', type: 'string', } satisfies AiExtractStructuredFieldsField, { key: 'dateOfBirth', displayName: 'Birth date', description: 'Person date of birth', prompt: 'What is the date of your birth?', type: 'date', } satisfies AiExtractStructuredFieldsField, { key: 'age', displayName: 'Age', description: 'Person age', prompt: 'How old are you?', type: 'float', } satisfies AiExtractStructuredFieldsField, { key: 'hobby', displayName: 'Hobby', description: 'Person hobby', prompt: 'What is your hobby?', type: 'multiSelect', options: [ { key: 'guitar' } satisfies AiExtractStructuredFieldsOptionsField, { key: 'books' } satisfies AiExtractStructuredFieldsOptionsField, ], } satisfies AiExtractStructuredFieldsField, ], items: [new AiItemBase({ id: file.id })], aiAgent: agentIgnoringOverridingEmbeddingsModel, } satisfies AiExtractStructured); ``` ### Arguments requestBody `AiExtractStructured` - Request body of createAiExtractStructured method optionalsInput `CreateAiExtractStructuredOptionalsInput` ### Returns This function returns a value of type `AiExtractStructuredResponse`. A successful response including the answer from the LLM. --- ### AiManager **Type:** page | **Section:** Additional Resources AiManager Ask question Generate text Get AI agent default configuration Extract metadata (freeform) Extract metadata (structured) Ask… # AiManager - [Ask question](#ask-question) - [Generate text](#generate-text) - [Get AI agent default configuration](#get-ai-agent-default-configuration) - [Extract metadata (freeform)](#extract-metadata-freeform) - [Extract metadata (structured)](#extract-metadata-structured) ## Ask question Sends an AI request to supported LLMs and returns an answer specifically focused on the user's question given the provided context. This operation is performed by calling function `create_ai_ask`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-ai-ask/). ``` client.ai.create_ai_ask( CreateAiAskMode.SINGLE_ITEM_QA, "which direction sun rises", [ AiItemAsk( id=file_to_ask.id, type=AiItemAskTypeField.FILE, content="Sun rises in the East", ) ], ai_agent=ai_ask_agent_config, ) ``` ### Arguments mode `CreateAiAskMode` - Box AI handles text documents with text representations up to 1MB in size, or a maximum of 25 files, whichever comes first. If the text file size exceeds 1MB, the first 1MB of text representation will be processed. Box AI handles image documents with a resolution of 1024 x 1024 pixels, with a maximum of 5 images or 5 pages for multi-page images. If the number of image or image pages exceeds 5, the first 5 images or pages will be processed. If you set mode parameter to `single_item_qa`, the items array can have one element only. Currently Box AI does not support multi-modal requests. If both images and text are sent Box AI will only process the text. prompt `str` - The prompt provided by the client to be answered by the LLM. The prompt's length is limited to 10000 characters. items `List[AiItemAsk]` - The items to be processed by the LLM, often files. dialogue_history `Optional[List[AiDialogueHistory]]` - The history of prompts and answers previously passed to the LLM. This provides additional context to the LLM in generating the response. include_citations `Optional[bool]` - A flag to indicate whether citations should be returned. ai_agent `Optional[Union[AiAgentAsk, AiAgentReference]]` extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `Optional[AiResponseFull]`. A successful response including the answer from the LLM.No content is available to answer the question. This is returned when the request item is a hub, but content in the hubs is not indexed. To ensure content in the hub is indexed, make sure Box AI for Hubs in the Admin Console was enabled before hub creation. ## Generate text Sends an AI request to supported Large Language Models (LLMs) and returns generated text based on the provided prompt. This operation is performed by calling function `create_ai_text_gen`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-ai-text-gen/). ``` client.ai.create_ai_text_gen( "Parapharse the document.s", [ CreateAiTextGenItems( id=file_to_ask.id, type=CreateAiTextGenItemsTypeField.FILE, content="The Earth goes around the sun. Sun rises in the East in the morning.", ) ], dialogue_history=[ AiDialogueHistory( prompt="What does the earth go around?", answer="The sun", created_at=date_time_from_string("2021-01-01T00:00:00Z"), ), AiDialogueHistory( prompt="On Earth, where does the sun rise?", answer="East", created_at=date_time_from_string("2021-01-01T00:00:00Z"), ), ], ai_agent=ai_text_gen_agent_config, ) ``` ### Arguments prompt `str` - The prompt provided by the client to be answered by the LLM. The prompt's length is limited to 10000 characters. items `List[CreateAiTextGenItems]` - The items to be processed by the LLM, often files. The array can include **exactly one** element. **Note**: Box AI handles documents with text representations up to 1MB in size. If the file size exceeds 1MB, the first 1MB of text representation will be processed. dialogue_history `Optional[List[AiDialogueHistory]]` - The history of prompts and answers previously passed to the LLM. This parameter provides the additional context to the LLM when generating the response. ai_agent `Optional[Union[AiAgentReference, AiAgentTextGen]]` extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `AiResponse`. A successful response including the answer from the LLM. ## Get AI agent default configuration Get the AI agent default config. This operation is performed by calling function `get_ai_agent_default_config`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-ai-agent-default/). ``` client.ai.get_ai_agent_default_config(GetAiAgentDefaultConfigMode.ASK, language="en-US") ``` ### Arguments mode `GetAiAgentDefaultConfigMode` - The mode to filter the agent config to return. language `Optional[str]` - The ISO language code to return the agent config for. If the language is not supported the default agent config is returned. model `Optional[str]` - The model to return the default agent config for. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `Union[AiAgentAsk, AiAgentTextGen, AiAgentExtract, AiAgentExtractStructured]`. A successful response including the default agent configuration. This response can be one of the following four objects: - AI agent for questions - AI agent for text generation - AI agent for freeform metadata extraction AI agent for structured metadata extraction. The response depends on the agent configuration requested in this endpoint. ## Extract metadata (freeform) Sends an AI request to supported Large Language Models (LLMs) and extracts metadata in form of key-value pairs. In this request, both the prompt and the output can be freeform. Metadata template setup before sending the request is not required. This operation is performed by calling function `create_ai_extract`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-ai-extract/). ``` client.ai.create_ai_extract( "firstName, lastName, location, yearOfBirth, company", [AiItemBase(id=file.id)], ai_agent=agent_ignoring_overriding_embeddings_model, ) ``` ### Arguments prompt `str` - The prompt provided to a Large Language Model (LLM) in the request. The prompt can be up to 10000 characters long and it can be an XML or a JSON schema. items `List[AiItemBase]` - The items that LLM will process. Currently, you can use files only. ai_agent `Optional[Union[AiAgentReference, AiAgentExtract]]` extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `AiResponse`. A response including the answer from the LLM. ## Extract metadata (structured) Sends an AI request to supported Large Language Models (LLMs) and returns extracted metadata as a set of key-value pairs. For this request, you either need a metadata template or a list of fields you want to extract. Input is **either** a metadata template or a list of fields to ensure the structure. To learn more about creating templates, see [Creating metadata templates in the Admin Console](https://support.box.com/hc/en-us/articles/360044194033-Customizing-Metadata-Templates) or use the [metadata template API](g://metadata/templates/create). This operation is performed by calling function `create_ai_extract_structured`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-ai-extract-structured/). ``` client.ai.create_ai_extract_structured( [AiItemBase(id=file.id)], fields=[ CreateAiExtractStructuredFields( key="firstName", display_name="First name", description="Person first name", prompt="What is the your first name?", type="string", ), CreateAiExtractStructuredFields( key="lastName", display_name="Last name", description="Person last name", prompt="What is the your last name?", type="string", ), CreateAiExtractStructuredFields( key="dateOfBirth", display_name="Birth date", description="Person date of birth", prompt="What is the date of your birth?", type="date", ), CreateAiExtractStructuredFields( key="age", display_name="Age", description="Person age", prompt="How old are you?", type="float", ), CreateAiExtractStructuredFields( key="hobby", display_name="Hobby", description="Person hobby", prompt="What is your hobby?", type="multiSelect", options=[ CreateAiExtractStructuredFieldsOptionsField(key="guitar"), CreateAiExtractStructuredFieldsOptionsField(key="books"), ], ), ], ai_agent=agent_ignoring_overriding_embeddings_model, ) ``` ### Arguments items `List[AiItemBase]` - The items to be processed by the LLM. Currently you can use files only. metadata_template `Optional[CreateAiExtractStructuredMetadataTemplate]` - The metadata template containing the fields to extract. For your request to work, you must provide either `metadata_template` or `fields`, but not both. fields `Optional[List[CreateAiExtractStructuredFields]]` - The fields to be extracted from the provided items. For your request to work, you must provide either `metadata_template` or `fields`, but not both. ai_agent `Optional[Union[AiAgentReference, AiAgentExtractStructured]]` extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `AiExtractStructuredResponse`. A successful response including the answer from the LLM. --- ### AiStudioManager **Type:** page | **Section:** Additional Resources AiStudioManager List AI agents Create AI agent Update AI agent Get AI agent by agent ID Delete AI agent List AI agents Lists AI agents based… # AiStudioManager - [List AI agents](#list-ai-agents) - [Create AI agent](#create-ai-agent) - [Update AI agent](#update-ai-agent) - [Get AI agent by agent ID](#get-ai-agent-by-agent-id) - [Delete AI agent](#delete-ai-agent) ## List AI agents Lists AI agents based on the provided parameters. This operation is performed by calling function `getAiAgents`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-ai-agents/). ``` await client.aiStudio.getAiAgents(); ``` ### Arguments queryParams `GetAiAgentsQueryParams` - Query parameters of getAiAgents method headersInput `GetAiAgentsHeadersInput` - Headers of getAiAgents method cancellationToken `undefined | CancellationToken` - Token used for request cancellation. ### Returns This function returns a value of type `AiMultipleAgentResponse`. A successful response including the agents list. ## Create AI agent Creates an AI agent. At least one of the following capabilities must be provided: `ask`, `text_gen`, `extract`. This operation is performed by calling function `createAiAgent`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-ai-agents/). ``` await client.aiStudio.createAiAgent({ name: agentName, accessState: 'enabled', ask: new AiStudioAgentAsk({ accessState: 'enabled', description: 'desc1' }), } satisfies CreateAiAgentInput); ``` ### Arguments requestBodyInput `CreateAiAgentInput` - Request body of createAiAgent method optionalsInput `CreateAiAgentOptionalsInput` ### Returns This function returns a value of type `AiSingleAgentResponseFull`. Definition of created AI agent. ## Update AI agent Updates an AI agent. This operation is performed by calling function `updateAiAgentById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-ai-agents-id/). ``` await client.aiStudio.updateAiAgentById(createdAgent.id, { name: agentName, accessState: 'enabled', ask: new AiStudioAgentAsk({ accessState: 'disabled', description: 'desc2' }), } satisfies CreateAiAgentInput); ``` ### Arguments agentId `string` - The ID of the agent to update. Example: "1234" requestBodyInput `CreateAiAgentInput` - Request body of updateAiAgentById method optionalsInput `UpdateAiAgentByIdOptionalsInput` ### Returns This function returns a value of type `AiSingleAgentResponseFull`. Definition of created AI agent. ## Get AI agent by agent ID Gets an AI Agent using the `agent_id` parameter. This operation is performed by calling function `getAiAgentById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-ai-agents-id/). ``` await client.aiStudio.getAiAgentById(createdAgent.id, { queryParams: { fields: ['ask'] } satisfies GetAiAgentByIdQueryParams, } satisfies GetAiAgentByIdOptionalsInput); ``` ### Arguments agentId `string` - The agent id to get. Example: "1234" optionalsInput `GetAiAgentByIdOptionalsInput` ### Returns This function returns a value of type `AiSingleAgentResponseFull`. A successful response including the agent. ## Delete AI agent Deletes an AI agent using the provided parameters. This operation is performed by calling function `deleteAiAgentById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-ai-agents-id/). ``` await client.aiStudio.deleteAiAgentById(createdAgent.id); ``` ### Arguments agentId `string` - The ID of the agent to delete. Example: "1234" optionalsInput `DeleteAiAgentByIdOptionalsInput` ### Returns This function returns a value of type `undefined`. A successful response with no content. --- ### AiStudioManager **Type:** page | **Section:** Additional Resources AiStudioManager List AI agents Create AI agent Update AI agent Get AI agent by agent ID Delete AI agent List AI agents Lists AI agents based… # AiStudioManager - [List AI agents](#list-ai-agents) - [Create AI agent](#create-ai-agent) - [Update AI agent](#update-ai-agent) - [Get AI agent by agent ID](#get-ai-agent-by-agent-id) - [Delete AI agent](#delete-ai-agent) ## List AI agents Lists AI agents based on the provided parameters. This operation is performed by calling function `get_ai_agents`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-ai-agents/). ``` client.ai_studio.get_ai_agents() ``` ### Arguments mode `Optional[List[str]]` - The mode to filter the agent config to return. Possible values are: `ask`, `text_gen`, and `extract`. fields `Optional[List[str]]` - The fields to return in the response. agent_state `Optional[List[str]]` - The state of the agents to return. Possible values are: `enabled`, `disabled` and `enabled_for_selected_users`. include_box_default `Optional[bool]` - Whether to include the Box default agents in the response. marker `Optional[str]` - Defines the position marker at which to begin returning results. limit `Optional[int]` - The maximum number of items to return per page. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `AiMultipleAgentResponse`. A successful response including the agents list. ## Create AI agent Creates an AI agent. At least one of the following capabilities must be provided: `ask`, `text_gen`, `extract`. This operation is performed by calling function `create_ai_agent`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-ai-agents/). ``` client.ai_studio.create_ai_agent( agent_name, "enabled", ask=AiStudioAgentAsk(access_state="enabled", description="desc1"), ) ``` ### Arguments type `CreateAiAgentType` - The type of agent used to handle queries. name `str` - The name of the AI Agent. access_state `str` - The state of the AI Agent. Possible values are: `enabled`, `disabled`, and `enabled_for_selected_users`. icon_reference `Optional[str]` - The icon reference of the AI Agent. It should have format of the URL `https://cdn01.boxcdn.net/app-assets/aistudio/avatars/<file_name>` where possible values of `file_name` are: `logo_boxAi.png`,`logo_stamp.png`,`logo_legal.png`,`logo_finance.png`,`logo_config.png`,`logo_handshake.png`,`logo_analytics.png`,`logo_classification.png`. allowed_entities `Optional[List[AiAgentAllowedEntity]]` - List of allowed users or groups. ask `Optional[AiStudioAgentAsk]` text_gen `Optional[AiStudioAgentTextGen]` extract `Optional[AiStudioAgentExtract]` extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `AiSingleAgentResponseFull`. Definition of created AI agent. ## Update AI agent Updates an AI agent. This operation is performed by calling function `update_ai_agent_by_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-ai-agents-id/). ``` client.ai_studio.update_ai_agent_by_id( created_agent.id, agent_name, "enabled", ask=AiStudioAgentAsk(access_state="disabled", description="desc2"), ) ``` ### Arguments agent_id `str` - The ID of the agent to update. Example: "1234" type `UpdateAiAgentByIdType` - The type of agent used to handle queries. name `str` - The name of the AI Agent. access_state `str` - The state of the AI Agent. Possible values are: `enabled`, `disabled`, and `enabled_for_selected_users`. icon_reference `Optional[str]` - The icon reference of the AI Agent. It should have format of the URL `https://cdn01.boxcdn.net/app-assets/aistudio/avatars/<file_name>` where possible values of `file_name` are: `logo_boxAi.png`,`logo_stamp.png`,`logo_legal.png`,`logo_finance.png`,`logo_config.png`,`logo_handshake.png`,`logo_analytics.png`,`logo_classification.png`. allowed_entities `Optional[List[AiAgentAllowedEntity]]` - List of allowed users or groups. ask `Optional[AiStudioAgentAsk]` text_gen `Optional[AiStudioAgentTextGen]` extract `Optional[AiStudioAgentExtract]` extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `AiSingleAgentResponseFull`. Definition of created AI agent. ## Get AI agent by agent ID Gets an AI Agent using the `agent_id` parameter. This operation is performed by calling function `get_ai_agent_by_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-ai-agents-id/). ``` client.ai_studio.get_ai_agent_by_id(created_agent.id, fields=["ask"]) ``` ### Arguments agent_id `str` - The agent id to get. Example: "1234" fields `Optional[List[str]]` - The fields to return in the response. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `AiSingleAgentResponseFull`. A successful response including the agent. ## Delete AI agent Deletes an AI agent using the provided parameters. This operation is performed by calling function `delete_ai_agent_by_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-ai-agents-id/). ``` client.ai_studio.delete_ai_agent_by_id(created_agent.id) ``` ### Arguments agent_id `str` - The ID of the agent to delete. Example: "1234" extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `None`. A successful response with no content. --- ### Android **Type:** page | **Section:** Additional Resources Android The Java SDK should be compatible with modern Android applications written in both Java and Kotlin. To use the Java SDK in an… # Android The Java SDK should be compatible with modern Android applications written in both Java and Kotlin. To use the Java SDK in an android application add it to the project's gradle file in the `dependencies` block. For Groovy ``` // build.gradle dependencies { implementation "com.box:box-java-sdk:3.8.0" } ``` For Kotlin ``` // build.gradle.kts dependencies { implementation("com.box:box-java-sdk:3.8.0") } ``` ## Kotlin The Java SDK can also be used in Kotlin Android applications through interoperability thanks to the Kotlin design. You can read more about Kotlin and Java interoperability [here](https://kotlinlang.org/docs/java-interop.html) The following example creates an API connection with a developer token: ``` val api = BoxAPIConnection("myToken") ``` The following example shows how to get current user ``` val userID = "33333" val api = BoxAPIConnection("myToken") val user = BoxUser(api, userID) val userInfo = user.getInfo() ``` If you are using an IntelliJ-based IDE, you can copy our samples located in the [docs](https://ja.developer.box.com/doc/) directory and paste them into your file. The IDE should ask you to convert the pasted Java sample to Kotlin. Most samples still work after conversion using this approach. Note that the current Java SDK does not support Kotlin coroutines. By default, you cannot run network calls on the main thread in an Android application. There are various ways to overcome this. For example, if you are in a viewModel context, you can run the SDK method as a coroutine using viewModelScope. ``` viewModelScope.launch { val result = withContext(Dispatchers.IO) { /* SDK code goes here */ } // here you can access the result and load it to the viewModel } ``` The following example shows how to get the current items in the root folder, sorted by name in ascending order with additional "created_by" and "name" fields returned from the API. The items are then loaded to the custom data class defined earlier. ``` // data class definition used in viewModel data class Item( val isFolder: Boolean, val name: String, val createdBy: String ) // viewModel init code viewModelScope.launch { val result = withContext(Dispatchers.IO) { val res = BoxFolder(BoxAPIConnection("myToken"), "0") val iterator: Iterator<BoxItem.Info> = res.getChildren("name", BoxFolder.SortDirection.ASC, "created_by", "name") .iterator() val items = mutableListOf<Item>() when (val itemInfo = iterator.next()) { is BoxFile.Info -> items.add(Item(false, "File " + itemInfo.name, itemInfo.createdBy.name)) is BoxFolder.Info -> items.add(Item(true, "Folder " + itemInfo.name, itemInfo.createdBy.name)) } items } } ``` If you are familiar with Kotlin syntax, you might have noticed that we could have used the `.map` function (or a similar function) to map the API result to a list of items. Due to current limitations, using `.map` and similar operations on collections is not always possible and may lead to unexpected results. The preferred way is to use an explicit iterator to iterate over the collections returned by the SDK. If you find any problem related to the Java SDK in Kotlin-based app feel free to open an issue. --- ### App Auth Sample App **Type:** page | **Section:** Additional Resources App Auth Sample App To get started: Clone the SDK repo Edit examples/app-auth/index.js with your app credentials Run the sample app: # App Auth Sample App To get started: 1. Clone the SDK repo 2. Edit `examples/app-auth/index.js` with your app credentials 3. Run the sample app: ``` cd examples/app-auth/ npm install npm start ``` --- ### AppItemAssociationsManager **Type:** page | **Section:** Additional Resources AppItemAssociationsManager List file app item associations List folder app item associations List file app item associations This is a beta… # AppItemAssociationsManager - [List file app item associations](#list-file-app-item-associations) - [List folder app item associations](#list-folder-app-item-associations) ## List file app item associations **This is a beta feature, which means that its availability might be limited.** Returns all app items the file is associated with. This includes app items associated with ancestors of the file. Assuming the context user has access to the file, the type/ids are revealed even if the context user does not have **View** permission on the app item. This operation is performed by calling function `getFileAppItemAssociations`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-files-id-app-item-associations/). ``` await client.appItemAssociations.getFileAppItemAssociations(fileId); ``` ### Arguments fileId `string` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" optionalsInput `GetFileAppItemAssociationsOptionalsInput` ### Returns This function returns a value of type `AppItemAssociations`. Returns a collection of app item objects. If there are no app items on this file, an empty collection will be returned. This list includes app items on ancestors of this File. ## List folder app item associations **This is a beta feature, which means that its availability might be limited.** Returns all app items the folder is associated with. This includes app items associated with ancestors of the folder. Assuming the context user has access to the folder, the type/ids are revealed even if the context user does not have **View** permission on the app item. This operation is performed by calling function `getFolderAppItemAssociations`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-folders-id-app-item-associations/). ``` await client.appItemAssociations.getFolderAppItemAssociations(folderId); ``` ### Arguments folderId `string` - The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. Example: "12345" optionalsInput `GetFolderAppItemAssociationsOptionalsInput` ### Returns This function returns a value of type `AppItemAssociations`. Returns a collection of app item objects. If there are no app items on this folder an empty collection will be returned. This list includes app items on ancestors of this folder. --- ### AppItemAssociationsManager **Type:** page | **Section:** Additional Resources AppItemAssociationsManager List file app item associations List folder app item associations List file app item associations This is a beta… # AppItemAssociationsManager - [List file app item associations](#list-file-app-item-associations) - [List folder app item associations](#list-folder-app-item-associations) ## List file app item associations **This is a beta feature, which means that its availability might be limited.** Returns all app items the file is associated with. This includes app items associated with ancestors of the file. Assuming the context user has access to the file, the type/ids are revealed even if the context user does not have **View** permission on the app item. This operation is performed by calling function `get_file_app_item_associations`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-files-id-app-item-associations/). ``` client.app_item_associations.get_file_app_item_associations(file_id) ``` ### Arguments file_id `str` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" limit `Optional[int]` - The maximum number of items to return per page. marker `Optional[str]` - Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`. application_type `Optional[str]` - If given, only return app items for this application type. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `AppItemAssociations`. Returns a collection of app item objects. If there are no app items on this file, an empty collection will be returned. This list includes app items on ancestors of this File. ## List folder app item associations **This is a beta feature, which means that its availability might be limited.** Returns all app items the folder is associated with. This includes app items associated with ancestors of the folder. Assuming the context user has access to the folder, the type/ids are revealed even if the context user does not have **View** permission on the app item. This operation is performed by calling function `get_folder_app_item_associations`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-folders-id-app-item-associations/). ``` client.app_item_associations.get_folder_app_item_associations(folder_id) ``` ### Arguments folder_id `str` - The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. Example: "12345" limit `Optional[int]` - The maximum number of items to return per page. marker `Optional[str]` - Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`. application_type `Optional[str]` - If given, returns only app items for this application type. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `AppItemAssociations`. Returns a collection of app item objects. If there are no app items on this folder an empty collection will be returned. This list includes app items on ancestors of this folder. --- ### ArchivesManager **Type:** page | **Section:** Additional Resources ArchivesManager List archives Create archive Delete archive List archives Retrieves archives for an enterprise. This operation is performed… # ArchivesManager - [List archives](#list-archives) - [Create archive](#create-archive) - [Delete archive](#delete-archive) ## List archives Retrieves archives for an enterprise. This operation is performed by calling function `getArchivesV2025R0`. See the endpoint docs at [API Reference](https://developer.box.com/reference/v2025.0/get-archives/). ``` await client.archives.getArchivesV2025R0({ limit: 100, } satisfies GetArchivesV2025R0QueryParams); ``` ### Arguments queryParams `GetArchivesV2025R0QueryParams` - Query parameters of getArchivesV2025R0 method headersInput `GetArchivesV2025R0HeadersInput` - Headers of getArchivesV2025R0 method cancellationToken `undefined | CancellationToken` - Token used for request cancellation. ### Returns This function returns a value of type `ArchivesV2025R0`. Returns a list of archives in the enterprise. ## Create archive Creates an archive. This operation is performed by calling function `createArchiveV2025R0`. See the endpoint docs at [API Reference](https://developer.box.com/reference/v2025.0/post-archives/). ``` await client.archives.createArchiveV2025R0({ name: archiveName, } satisfies CreateArchiveV2025R0RequestBody); ``` ### Arguments requestBody `CreateArchiveV2025R0RequestBody` - Request body of createArchiveV2025R0 method optionalsInput `CreateArchiveV2025R0OptionalsInput` ### Returns This function returns a value of type `ArchiveV2025R0`. Returns a new archive object. ## Delete archive Permanently deletes an archive. This operation is performed by calling function `deleteArchiveByIdV2025R0`. See the endpoint docs at [API Reference](https://developer.box.com/reference/v2025.0/delete-archives-id/). ``` await client.archives.deleteArchiveByIdV2025R0(archive.id); ``` ### Arguments archiveId `string` - The ID of the archive. Example: "982312" optionalsInput `DeleteArchiveByIdV2025R0OptionalsInput` ### Returns This function returns a value of type `undefined`. Returns an empty response when the archive has been deleted. --- ### ArchivesManager **Type:** page | **Section:** Additional Resources ArchivesManager List archives Create archive Delete archive List archives Retrieves archives for an enterprise. This operation is performed… # ArchivesManager - [List archives](#list-archives) - [Create archive](#create-archive) - [Delete archive](#delete-archive) ## List archives Retrieves archives for an enterprise. This operation is performed by calling function `get_archives_v2025_r0`. See the endpoint docs at [API Reference](https://developer.box.com/reference/v2025.0/get-archives/). ``` client.archives.get_archives_v2025_r0(limit=100) ``` ### Arguments limit `Optional[int]` - The maximum number of items to return per page. marker `Optional[str]` - Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. box_version `BoxVersionHeaderV2025R0` - Version header. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `ArchivesV2025R0`. Returns a list of archives in the enterprise. ## Create archive Creates an archive. This operation is performed by calling function `create_archive_v2025_r0`. See the endpoint docs at [API Reference](https://developer.box.com/reference/v2025.0/post-archives/). ``` client.archives.create_archive_v2025_r0(archive_name) ``` ### Arguments name `str` - The name of the archive. box_version `BoxVersionHeaderV2025R0` - Version header. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `ArchiveV2025R0`. Returns a new archive object. ## Delete archive Permanently deletes an archive. This operation is performed by calling function `delete_archive_by_id_v2025_r0`. See the endpoint docs at [API Reference](https://developer.box.com/reference/v2025.0/delete-archives-id/). ``` client.archives.delete_archive_by_id_v2025_r0(archive.id) ``` ### Arguments archive_id `str` - The ID of the archive. Example: "982312" box_version `BoxVersionHeaderV2025R0` - Version header. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `None`. Returns an empty response when the archive has been deleted. --- ### Authentication **Type:** page | **Section:** Additional Resources Authentication The Box API uses OAuth2 for authentication, which can be difficult to implement. The SDK makes it easier by providing classes… # Authentication The Box API uses OAuth2 for authentication, which can be difficult to implement. The SDK makes it easier by providing classes that handle obtaining tokens and automatically refreshing them when possible. See the [OAuth 2 overview](https://developer.box.com/en/guides/authentication/) for a detailed overview of how the Box API handles authentication. [Ways to Authenticate](#ways-to-authenticate) - [Developer Token](#developer-token) - [Server Auth with JWT](#server-auth-with-jwt) [Traditional 3-Legged OAuth2](#traditional-3-legged-oauth2) - [Token Store](#token-store) [Box View Authentication with App Tokens](#box-view-authentication-with-app-tokens) [Client Credentials Grant Authentication](#client-credentials-grant-authentication) [As-User](#as-user) [Proxy Support](#proxy-support) [Token Exchange](#token-exchange) - [Annotator Tokens](#annotator-tokens) [Revoking Tokens](#revoking-tokens) ## Ways to Authenticate ### Developer Token The fastest way to get started using the API is with developer tokens. A developer token is simply a short-lived access token that cannot be refreshed and can only be used with your own account. Therefore, they're only useful for testing an app and aren't suitable for production. You can obtain a developer token from your application's [developer console](https://app.box.com/developers/console) page. The following example creates an API client with a developer token: ``` var BoxSDK = require('box-node-sdk'); var sdk = new BoxSDK({ clientID: 'YOUR-CLIENT-ID', clientSecret: 'YOUR-CLIENT_SECRET' }); var client = sdk.getBasicClient('YOUR-DEVELOPER-TOKEN'); ``` ### Server Auth with JWT Server auth allows your application to authenticate itself with the Box API for a given enterprise. By default, your application has a [Service Account](https://developer.box.com/en/guides/authentication/user-types/app-users/#service-accounts) that represents it and can perform API calls. The Service Account is separate from the Box accounts of the application developer and the enterprise admin of any enterprise that has authorized the app — files stored in that account are not accessible in any other account by default, and vice versa. If you generated your public and private keys automatically through the [Box Developer Console](https://app.box.com/developers/console), you can use the JSON file created there to configure your SDK instance and create a client to make calls as the Service Account: ``` var BoxSDK = require('box-node-sdk'); var jsonConfig = require('/path/to/config.json'); var sdk = BoxSDK.getPreconfiguredInstance(jsonConfig); var serviceAccountClient = sdk.getAppAuthClient('enterprise'); ``` Otherwise, you'll need to provide the necessary configuration fields directly to the SDK constructor: ``` var BoxSDK = require('box-node-sdk'); var sdk = new BoxSDK({ clientID: 'YOUR-CLIENT-ID', clientSecret: 'YOUR-CLIENT_SECRET', appAuth: { keyID: 'YOUR-KEY-ID', privateKey: 'YOUR-PRIVATE_KEY', passphrase: 'YOUR-PRIVATE-KEY-PASSPHRASE' } }); var serviceAccountClient = sdk.getAppAuthClient('enterprise', 'YOUR-ENTERPRISE-ID'); ``` App auth applications also often have associated App Users, which are [created and managed directly by the application](https://developer.box.com/en/guides/authentication/user-types/app-users/) — they do not have normal login credentials, and can only be accessed through the Box API by the application that created them. You may authenticate as the Service Account to provision and manage users, or as an individual app user or managed user to make calls as that user. See the [API documentation](https://developer.box.com/) and [sample app](https://github.com/box/box-node-sdk/blob/main/examples/app-auth) for detailed instructions on how to use app auth. Clients for making calls as an App User or Managed User can be created with the same SDK instance as in the above examples, similarly to creating a Service Account client: ``` var appUserClient = sdk.getAppAuthClient('user', 'YOUR-APP-USER-ID'); ``` ### Traditional 3-Legged OAuth2 If your application needs to integrate with existing Box users who will provide their login credentials to grant your application access to their account, you will need to go through the standard OAuth2 login flow. A detailed guide for this process is available in the [Authentication with OAuth API documentation](https://developer.box.com/en/guides/authentication/oauth2/). Using an auth code is the most common way of authenticating with the Box API for existing Box users, to integrate with their accounts. Your application must provide a way for the user to login to Box (usually with a browser or web view) in order to obtain an auth code. ``` var BoxSDK = require('box-node-sdk'); var sdk = new BoxSDK({ clientID: 'YOUR-CLIENT-ID', clientSecret: 'YOUR-CLIENT_SECRET' }); // the URL to redirect the user to var authorize_url = sdk.getAuthorizeURL({ response_type: 'code' }); ``` After a user logs in and grants your application access to their Box account, they will be redirected to your application's `redirect_uri` which will contain an auth code. This auth code can then be used along with your client ID and client secret to establish an API connection. A `PersistentClient` will automatically refresh the access token as needed. ``` var BoxSDK = require('box-node-sdk'); var sdk = new BoxSDK({ clientID: 'YOUR-CLIENT-ID', clientSecret: 'unused' }); var client = sdk.getBasicClient('YOUR-APP-TOKEN'); ``` ### Client Credentials Grant Authentication Allows you to obtain an access token by having client credentials and secret with enterprise or user ID, which allows you to work using service (anonymous) or user account. #### Obtaining Service Account token The [Service Account](https://developer.box.com/guides/getting-started/user-types/service-account//) is separate from the Box accounts of the application developer and the enterprise admin of any enterprise that has authorized the app — files stored in that account are not accessible in any other account by default, and vice versa. To obtain service account, you will have to provide enterprise ID with client ID and secret: ``` const BoxSDK = require('box-node-sdk'); const sdkConfig = { boxAppSettings: { clientID: "CLIENT_ID", clientSecret: "CLIENT_SECRET" }, enterpriseID: "ENTERPRISE_ID" } const sdk = BoxSDK.getPreconfiguredInstance(sdkConfig) const client = sdk.getAnonymousClient(); ``` #### Obtaining User token To obtain user account you will have to provide user ID with client ID and secret. ``` const BoxSDK = require('box-node-sdk'); const sdkConfig = { boxAppSettings: { clientID: "CLIENT_ID", clientSecret: "CLIENT_SECRET" }, enterpriseID: "ENTERPRISE_ID" //The enterprise id in this case is optional and can be ommited. } const sdk = BoxSDK.getPreconfiguredInstance(sdkConfig) const client = sdk.getCCGClientForUser("USER_ID"); ``` ## As-User The As-User header is used by enterprise admins to make API calls on behalf of their enterprise's users. This requires the API request to pass an `As-User: USER-ID` header. For more details see the [documentation on As-User](https://developer.box.com/en/guides/authentication/oauth2/as-user/). The following examples assume that the `client` has been instantiated with an access token belonging to an admin-level user or Service Account with appropriate privileges to make As-User calls. The `asUser(userID)` method sets up the client to impersonate a given user. All calls made with this instance of client will be made in context of the impersonated user. ``` client.asUser('USER-ID'); client.folders.getItems('0') .then(items => { // items contains the collection of files and folders // in the root folder of the user with USER-ID }); ``` The `asSelf()` method removes the As-User header and returns the client to making calls as the admin user or Service Account it was initialized as. ``` client.asSelf(); ``` ## Token Exchange You can exchange a client's access token for one with a lower scope, in order to restrict the permissions for a child client or to pass to a less secure location (e.g. a browser-based app). This is useful if you want to use the [Box UI Kits](https://developer.box.com/en/guides/embed/ui-elements/), since they generally do not need full read/write permissions to run. To exchange the token held by a client for a new token with only `item_preview` scope, restricted to a single file, suitable for the [Content Preview UI Kit](https://developer.box.com/en/guides/embed/ui-elements/preview/): ``` client.exchangeToken('item_preview', 'https://api.box.com/2.0/files/123456789') .then(tokenInfo => { // tokenInfo.accessToken contains the new downscoped access token }); ``` To exchange the client's token for one with scopes to upload and delete items, but not to view their contents, which would be suitable for an less-trusted server-side process; ``` client.exchangeToken(['item_upload', 'item_delete']) .then(tokenInfo => { // tokenInfo.accessToken contains the new downscoped access token }); ``` #### Annotator Tokens To generate an annotator token for use with [Box View annotations](https://developer.box.com/en/guides/embed/ui-elements/annotations/), pass the `actor` options to the token exchange method: ``` var options = { actor: { id: 'EXTERNAL_IDENTIFIER', name: 'Jane Doe' } }; client.exchangeToken('item_preview', 'https://api.box.com/2.0/files/123456', options) .then(tokenInfo => { // tokenInfo.accessToken contains the new annotator token }); ``` This will attach an external user name and ID to annotations made with the token, in order to attribute them to someone who does not have a Box account. ## Revoking tokens Access tokens for a client can be revoked when needed. As this removes the client's way of authenticating this client can no longer be used after this call. ``` client.revokeTokens("<TOKEN>") .then(() => { // the client's access token have been revoked }); ``` --- ### Authentication **Type:** page | **Section:** Additional Resources Authentication The Box API uses OAuth2 for authentication, which can be difficult to implement. The SDK makes it easier by providing classes… # Authentication The Box API uses OAuth2 for authentication, which can be difficult to implement. The SDK makes it easier by providing classes that handle obtaining tokens and automatically refreshing them. [Ways to Authenticate](#ways-to-authenticate) - [Developer Token](#developer-token) - [Server Authentication with JWT](#server-authentication-with-jwt) - [Standard 3-Legged Oauth 2.0](#standard-3-legged-oauth-20) - [Box View Authentication with App Token](#box-view-authentication-with-app-token) - [Client Credentials Grant](#client-credentials-grant) [Manual Token Creation](#manual-token-creation) [As User](#as-user) [Token Exchange](#token-exchange) [Revoke Token](#revoke-token) ## Ways to Authenticate ### Developer Token The fastest way to get started using the API is with developer tokens. A developer token is simply a short-lived access token that cannot be refreshed and can only be used with your own account. Therefore, they're only useful for testing an app and aren't suitable for production. You can obtain a developer token from your application's developer console. The following example creates an API connection with a developer token: ``` BoxAPIConnection api = new BoxAPIConnection("YOUR-DEVELOPER-TOKEN"); ``` ### Server Authentication with JWT App Users allows your application to provision and control Box accounts that do not have an associated login and can only be accessed through the Content API by the controlling application. An App User is a Box account that belongs to your Box Platform application and not an end-user of Box, like a [managed user](https://developer.box.com/v2.0/reference#user-object) It is important to emphasize that unlike typical Box accounts, these accounts do not have an associated login and can only be accessed through the Box API. You may authenticate as the service account to provision and manage users, or as an individual app user to make calls as that user. See the [API documentation](https://github.com/box/box-node-sdk/blob/main/docs/authentication.md#app-user-authentication) for detailed instruction on how to use app auth. The Java SDK also has a convenient helper function `BoxConfig.readFrom()` to assist in constructing an API connection. The `readFrom()` method takes in a stream constructed by the JSON config downloaded from the Developer Console seen [here](https://developer.box.com/docs/setting-up-a-jwt-app#section-use-an-application-config-file). Once a `BoxConfig` object has been created you can use that to create an API connection. ``` Reader reader = new FileReader("src/example/config/config.json"); BoxConfig boxConfig = BoxConfig.readFrom(reader); IAccessTokenCache tokenCache = new InMemoryLRUAccessTokenCache(100); BoxDeveloperEditionAPIConnection api = BoxDeveloperEditionAPIConnection.getAppEnterpriseConnection(boxConfig, tokenCache); ``` It is also possible to get an API connection for an app user or managed user: ``` Reader reader = new FileReader("src/example/config/config.json"); BoxConfig boxConfig = BoxConfig.readFrom(reader); IAccessTokenCache accessTokenCache = new InMemoryLRUAccessTokenCache(100); BoxDeveloperEditionAPIConnection api = BoxDeveloperEditionAPIConnection.getUserConnection(userId, boxConfig, accessTokenCache); ``` However, if you would like to do a manual set up then that is also possible with the below options. App User example: ``` JWTEncryptionPreferences jwtPreferences = new JWTEncryptionPreferences(); jwtPreferences.setPublicKeyID("PUBLIC-KEY-ID"); jwtPreferences.setPrivateKeyPassword("PRIVATE-KEY-PASSWORD"); jwtPreferences.setPrivateKey("PRIVATE-KEY"); jwtPreferences.setEncryptionAlgorithm(EncryptionAlgorithm.RSA_SHA_256); IAccessTokenCache accessTokenCache = new InMemoryLRUAccessTokenCache(100); BoxDeveloperEditionAPIConnection api = BoxDeveloperEditionAPIConnection .getUserConnection("USER-ID", "CLIENT-ID","CLIENT-SECRET", jwtPreferences, accessTokenCache); BoxUser.Info userInfo = BoxUser.getCurrentUser(api).getInfo(); ``` Server authentication allows your application to authenticate itself with the Box API for a given enterprise. A [Service Account](https://developer.box.com/v2.0/docs/service-account) always exists for a Box application. It is important to note that a Service Account is separate from the Box accounts of the applicaton developer and the enterprise admin of any enterprise that has authorized the app, meaning files stored in that account are not accessible in any other account by default. Service Account example: ``` JWTEncryptionPreferences jwtPreferences = new JWTEncryptionPreferences(); jwtPreferences.setPublicKeyID("PUBLIC-KEY-ID"); jwtPreferences.setPrivateKeyPassword("PRIVATE-KEY-PASSWORD"); jwtPreferences.setPrivateKey("PRIVATE-KEY"); jwtPreferences.setEncryptionAlgorithm(EncryptionAlgorithm.RSA_SHA_256); BoxConfig boxConfig = new BoxConfig("YOUR-CLIENT-ID", "YOUR-CLIENT-SECRET", "ENTERPRISE-ID", jwtPreferences); IAccessTokenCache tokenCache = new InMemoryLRUAccessTokenCache(10); BoxDeveloperEditionAPIConnection api = BoxDeveloperEditionAPIConnection.getAppEnterpriseConnection(boxConfig, tokenCache); ``` ### Standard 3-Legged Oauth 2.0 Using an auth code is the most common way of authenticating with the Box API. Your application must provide a way for the user to login to Box (usually with a browser or web view) in order to obtain an auth code. After a user logs in and grants your application access to their Box account, they will be redirected to your application's `redirect_uri` which will contain an auth code. This auth code can then be used along with your client ID and client secret to establish an API connection. ``` BoxAPIConnection api = new BoxAPIConnection("YOUR-CLIENT-ID", "YOUR-CLIENT-SECRET", "YOUR-AUTH-CODE"); ``` ### Box View Authentication with App Token Allows applications that do not own content stored in Box (e.g. app-owned content) to be able to use Box as a service provider rather than a content store. This is currently mostly used for previewing items. For scopes you can choose between "item_preview", "item_upload", or "item_delete". See the [Getting Started with the New Box View](https://developer.box.com/docs/getting-started-with-new-box-view) for detailed instruction. ``` BoxTransactionalAPIConnection api = new BoxTransactionalAPIConnection("YOUR-ACCESS-TOKEN"); ``` You can also request a specific scope of the transaction token by passing in: "item_preview", "item_upload", or "item_delete". ``` BoxAPIConnection api = BoxTransactionalAPIConnection.getTransactionConnection("YOUR-ACCESS-TOKEN", "item_preview"); ``` Lastly, you can choose to specify a resource to generate a token for with. If you're passing a token down to your client this is a great way to restrict access on that token in turn locking down what the token has access to. ``` BoxAPIConnection api = BoxTransactionalAPIConnection.getTransactionConnection("YOUR-ACCESS-TOKEN", "item_preview", "https://api.box.com/2.0/files/YOUR-FILE-ID"); ``` ### Client Credentials Grant Allows you to obtain an access token by having client credentials and secret with enterprise or user ID, which allows you to work using service or user account. The `BoxCCGAPIConnection` works the same way as the `BoxAPIConnection` so for example to get root folder you can do: ``` BoxCCGAPIConnection api = BoxCCGAPIConnection.userConnection( "client_id", "client_secret", "user_id" ); BoxFolder root = BoxFolder.getRootFolder(api); ``` Obtained token is valid for specified ammount of time and it will be refreshed automatically by default. #### Obtaining Service Account token The [Service Account](https://developer.box.com/guides/getting-started/user-types/service-account//) is separate from the Box accounts of the application developer and the enterprise admin of any enterprise that has authorized the app — files stored in that account are not accessible in any other account by default, and vice versa. To obtain service account you will have to provide enterprise ID with client id and secret: ``` BoxCCGAPIConnection api = BoxCCGAPIConnection.applicationServiceAccountConnection( "client_id", "client_secret", "enterprise_id" ); ``` #### Obtaining User token To obtain user account you will have to provide user ID with client id and secret ``` BoxCCGAPIConnection api = BoxCCGAPIConnection.userConnection( "client_id", "client_secret", "user_id" ); ``` In order to enable generating user token you have to go to your application configuration that can be found [here](https://app.box.com/developers/console). In`Configuration` tab, in section `Advanced Features` select `Generate user access tokens`. Do not forget to re-authorize application if it was already authorized. ## Manual Token Creation In certain advanced scenarios, you may want to obtain an access and refresh token yourself through manual calls to the API. In this case, you can create an API connection with the tokens directly. ``` BoxAPIConnection api = new BoxAPIConnection("YOUR-CLIENT-ID", "YOUR-CLIENT-SECRET", "YOUR-ACCESS-TOKEN", "YOUR-REFRESH-TOKEN"); ``` ## As User The purpose of as user is to be used by enterprise administrators to make API calls on behalf of their managed users. This can also be used by a Service Account to make API calls for managed users or app users. This is only meant to be used for `BoxAPIConnection`s and not `BoxDeveloperEditionAPIConnection`s. In order to invoke as user calls you can use ``` BoxAPIConnection api = new BoxAPIConnection("YOUR-ACCESS-TOKEN"); api.asUser("USER-ID"); ``` Once you are done making calls on behalf of a managed user or app user you can switch back to the admin or service account with ``` api.asSelf(); ``` ## Token Exchange You can exchange a API connection's access token for one with a lower scope, in order to restrict the permissions or to pass to a less secure location (e.g. a browser-based app). This is useful if you want to use the [Box UI Kits](https://developer.box.com/docs/box-ui-elements), since they generally do not need full read/write permissions to run. ``` BoxAPIConnection api = new BoxAPIConnection("YOUR-ACCESS-TOKEN"); String resource = "https://api.box.com/2.0/files/RESOURCE-ID"; List<String> scopes = new ArrayList<String>(); scopes.add("item_preview"); scopes.add("item_content_upload"); ScopedToken token = api.getLowerScopedToken(scopes, resource); ``` The above example will downscope an access token to only allow for previewing an item and uploading an item. ## Revoke Token At any point if you wish to revoke your tokens you can do so by calling the following. ``` BoxAPIConnection api = new BoxAPIConnection("YOUR-ACCESS-TOKEN"); api.revokeToken(); ``` --- ### Authentication **Type:** page | **Section:** Additional Resources Authentication The Box API uses OAuth2 for authentication, which can be difficult to implement. The SDK makes it easier by providing classes… # Authentication The Box API uses OAuth2 for authentication, which can be difficult to implement. The SDK makes it easier by providing classes that handle obtaining tokens and automatically refreshing them when possible. See the [OAuth 2 overview](https://developer.box.com/en/guides/authentication/) for a detailed overview of how the Box API handles authentication. [Ways to Authenticate](#ways-to-authenticate) - [Developer Token](#developer-token) - [Server Auth with JWT](#server-auth-with-jwt) - [Server Auth with CCG](#server-auth-with-ccg) [Traditional 3-Legged OAuth2](#traditional-3-legged-oauth2) - [AuthRepository Implementation](#authrepository-implementation) [Box View Authentication with App Tokens](#box-view-authentication-with-app-tokens) [As-User](#as-user) [Token Exchange](#token-exchange) ## Ways to Authenticate ### Developer Token The fastest way to get started using the API is with developer tokens. A developer token is simply a short-lived access token that cannot be refreshed and can only be used with your own account. Therefore, they're only useful for testing an app and aren't suitable for production. You can obtain a developer token from your application's [developer console](https://app.box.com/developers/console) page. The following example creates an API client with a developer token: ``` var config = new BoxConfigBuilder("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET", new Uri("http://localhost")).Build(); var session = new OAuthSession("YOUR_DEVELOPER_TOKEN", "N/A", 3600, "bearer"); var client = new BoxClient(config, session); ``` ### Server Auth with JWT Server auth allows your application to authenticate itself with the Box API for a given enterprise. By default, your application has a [Service Account](https://developer.box.com/guides/getting-started/user-types/service-account/) that represents it and can perform API calls. The Service Account is separate from the Box accounts of the application developer and the enterprise admin of any enterprise that has authorized the app — files stored in that account are not accessible in any other account by default, and vice versa. If you generated your public and private keys automatically through the [Box Developer Console](https://app.box.com/developers/console), you can use the JSON file created there to configure the SDK and create a client to make calls as the Service Account: ``` var config = BoxConfigBuilder.CreateFromJsonString(jsonConfig).Build(); var session = new BoxJWTAuth(config); var adminToken = await session.AdminTokenAsync(); //valid for 60 minutes so should be cached and re-used BoxClient adminClient = session.AdminClient(adminToken); ``` Otherwise, you'll need to provide the necessary configuration fields directly to the `BoxConfigBuilder` constructor: ``` var boxConfig = new BoxConfigBuilder("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET", "YOUR_ENTERPRISE_ID", "ENCRYPTED_PRIVATE_KEY", "PRIVATE_KEY_PASSWORD", "PUBLIC_KEY_ID").Build(); var boxJWT = new BoxJWTAuth(boxConfig); var adminToken = await boxJWT.AdminTokenAsync(); //valid for 60 minutes so should be cached and re-used BoxClient adminClient = boxJWT.AdminClient(adminToken); adminClient.Auth.SessionAuthenticated += delegate(object o, SessionAuthenticatedEventArgs e) { string newAccessToken = e.Session.AccessToken; // cache the new access token }; ``` App auth applications also often have associated [App Users](https://developer.box.com/guides/getting-started/user-types/app-users/), which are created and managed directly by the application — they do not have normal login credentials, and can only be accessed through the Box API by the application that created them. You may authenticate as the Service Account to provision and manage users, or as an individual app user to make calls as that user. See the [API documentation](https://developer.box.com/en/guides/applications/custom-apps/) and [sample app](https://github.com/box/box-windows-sdk-v2/tree/main/Box.V2.Samples.JWTAuth) for detailed instructions on how to use app auth. Clients for making calls as an App User or Managed User can be created with the same `BoxJWTAuth` instance as in the above examples, similarly to creating a Service Account client: ``` var appUserId = "12345"; var userToken = await boxJWT.UserTokenAsync(appUserID); //valid for 60 minutes so should be cached and re-used BoxClient appUserClient = boxJWT.UserClient(userToken, appUserId); appUserClient.Auth.SessionAuthenticated += delegate(object o, SessionAuthenticatedEventArgs e) { string newAccessToken = e.Session.AccessToken; // cache the new access token }; ``` ### Server Auth with CCG Server auth allows your application to authenticate itself with the Box API for a given enterprise. Client Credentials Grant (CCG) allows you to authenticate by providing `clientId` and `clientSecret` and `enterpriseId` of your app. By default, your application has a [Service Account](https://developer.box.com/guides/getting-started/user-types/service-account/) that represents it and can perform API calls. The Service Account is separate from the Box accounts of the application developer and the enterprise admin of any enterprise that has authorized the app — files stored in that account are not accessible in any other account by default, and vice versa. You'll need to provide the necessary configuration fields directly to the `BoxConfigBuilder` constructor: ``` var boxConfig = new BoxConfigBuilder("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET") .SetEnterpriseId("YOUR_ENTERPRISE_ID") .Build(); var boxCCG = new BoxCCGAuth(boxConfig); ``` There are two ways to create an admin client, the first one uses explicit admin token: ``` var adminToken = await boxCCG.AdminTokenAsync(); //valid for 60 minutes so should be cached and re-used IBoxClient adminClient = boxCCG.AdminClient(adminToken); adminClient.Auth.SessionAuthenticated += delegate(object o, SessionAuthenticatedEventArgs e) { string newAccessToken = e.Session.AccessToken; // cache the new access token }; ``` Second way leaves token management (caching) to the `Auth`, a new token is retrieved before the first call. Keep in mind that if you create multiple `adminClient` instances, the token won't be shared, it is expected that the `adminClient` instance is reused. ``` IBoxClient adminClient = boxCCG.AdminClient(); ``` App auth applications also often have associated [App Users](https://developer.box.com/guides/getting-started/user-types/app-users/), which are created and managed directly by the application — they do not have normal login credentials, and can only be accessed through the Box API by the application that created them. You may authenticate as the Service Account to provision and manage users, or as an individual app user to make calls as that user. See the [API documentation](https://developer.box.com/en/guides/applications/custom-apps/) for detailed instructions on how to use app auth. Clients for making calls as an App User or Managed User can be created with the same `BoxCCGAuth` instance as in the above examples, similarly to creating a Service Account client. You don't need to provide `enterpriseId` in this case: ``` var boxConfig = new BoxConfigBuilder("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET") .Build(); var boxCCG = new BoxCCGAuth(boxConfig); ``` Variant with explicit initial token: ``` var userToken = await boxCCG.UserTokenAsync("USER_ID"); //valid for 60 minutes so should be cached and re-used IBoxClient userClient = boxCCG.UserClient(userToken, "USER_ID"); userClient.Auth.SessionAuthenticated += delegate(object o, SessionAuthenticatedEventArgs e) { string newAccessToken = e.Session.AccessToken; // cache the new access token }; ``` Variant without initial token: ``` IBoxClient userClient = boxCCG.UserClient("USER_ID"); ``` ### Traditional 3-Legged OAuth2 If your application needs to integrate with existing Box users who will provide their login credentials to grant your application access to their account, you will need to go through the standard OAuth2 login flow. A detailed guide for this process is available in the [Authentication with OAuth API documentation](https://developer.box.com/en/guides/applications/custom-apps/oauth2-setup/). Using an auth code is the most common way of authenticating with the Box API for existing Box users, to integrate with their accounts. Your application must provide a way for the user to login to Box (usually with a browser or web view) in order to obtain an auth code. After a user logs in and grants your application access to their Box account, they will be redirected to your application's `redirect_uri` which will contain an auth code. This auth code can then be used along with your client ID and client secret to establish an API connection. The `BoxClient` will automatically refresh the access token as needed. ``` var config = new BoxConfigBuilder("CLIENT_ID", "CLIENT_SECRET", new System.Uri("YOUR_REDIRECT_URL")).Build(); var client = new BoxClient(config); OAuthSession session = // Create session from custom implementation var client = new BoxClient(config, session); ``` #### AuthRepository Implementation In order to maintain authentication and ensure that your users do not need to log in again every time they use your application, you should persist their token information to some sort of durable store (e.g. a database). The SDK provides an `AuthRepository` base class that you can extend to implement custom logic around token storage and refresh. ### Box View Authentication with App Tokens [Box View](https://developer.box.com/en/guides/embed/box-view/) uses a long-lived access token that is generated from the [Box Developer Console](https://app.box.com/developers/console) to make API calls. These access tokens cannot be automatically refreshed from the SDK, and must be manually changed in your application code. To use the primary or secondary access token generated in the Developer Console, simply create a basic client with that token: ``` var config = new BoxConfigBuilder("YOUR_CLIENT_ID", "N/A", new Uri("http://localhost")).Build(); var session = new OAuthSession("YOUR_APP_TOKEN", "N/A", 3600, "bearer"); var client = new BoxClient(config, session); ``` ## As-User The As-User header is used by enterprise admins to make API calls on behalf of their enterprise's users. This requires the API request to pass an `As-User: USER-ID` header. For more details see the [documentation on As-User](https://developer.box.com/en/guides/authentication/oauth2/as-user/). Constructing a `BoxClient` with the `asUser` parameter set will create a client that will make calls on behalf of the specified user: ``` var userId = "12345"; var client = new BoxClient(config, session, asUser: userId); ``` ## Token Exchange You can exchange a client's access token for one with a lower scope, in order to restrict the permissions for a child client or to pass to a less secure location (e.g. a browser-based app). This is useful if you want to use the [Box UI Kits](https://developer.box.com/en/guides/embed/ui-elements/), since they generally do not need full read/write permissions to run. To exchange the token held by a client for a new token with only `item_preview` scope, restricted to a single file, suitable for the [Content Preview UI Kit](https://developer.box.com/en/guides/embed/ui-elements/preview/): ``` var exchanger = new TokenExchange(client.Auth.Session.AccessToken, "item_preview"); exchanger.SetResource("https://api.box.com/2.0/files/123456789"); string downscopedToken = await exchanger.ExchangeAsync(); ``` To exchange the client's token for one with scopes to upload and delete items, but not to view their contents, which would be suitable for an less-trusted server-side process; ``` var scopes = new List<string>() { "item_upload", "item_download" }; var exchanger = new TokenExchange(client.Auth.Session.AccessToken, scopes); string downscopedToken = await exchanger.ExchangeAsync(); ``` --- ### Authentication **Type:** page | **Section:** Additional Resources Authentication Authentication Ways to Authenticate Developer Token Server Auth with JWT Traditional 3-Legged OAuth2 Client Credentials Grant… # Authentication [Authentication](#authentication) [Ways to Authenticate](#ways-to-authenticate) - [Developer Token](#developer-token) - [Server Auth with JWT](#server-auth-with-jwt) - [Traditional 3-Legged OAuth2](#traditional-3-legged-oauth2) [Client Credentials Grant](#client-credentials-grant) - [Obtaining Service Account token](#obtaining-service-account-token) - [Obtaining User token](#obtaining-user-token) [Token Store](#token-store) [As-User](#as-user) [Token Exchange](#token-exchange) [Revoking Tokens](#revoking-tokens) The Box API uses two flavors of OAuth2 for authentication, both of which can can be difficult to implement. The SDK makes it easier by providing classes that handle obtaining tokens and automatically refreshing them when possible. See the [Auth Types documentation](https://developer.box.com/docs/authentication-types-and-security) for a detailed overview of how the Box API handles authentication and how to choose between the different authentication types. ## Ways to Authenticate ### Developer Token The fastest way to get started using the API is with developer tokens. A developer token is a short-lived access token that cannot be refreshed and can only be used with your own account. Therefore, they're only useful for testing an app and aren't suitable for use in production. You can obtain a developer token from your application's [developer console](https://app.box.com/developers/console) page. The following example creates an SDK client with a developer token: ``` import BoxSDK let client = BoxSDK.getClient(token: "YOUR_DEVELOPER_TOKEN") ``` ### Server Auth with JWT Server auth allows your application to authenticate itself with the Box API for a given enterprise. By default, your application has a [Service Account](https://developer.box.com/docs/service-account) that represents it and can perform API calls. The Service Account is separate from the Box accounts of the application developer and the enterprise admin of any enterprise that has authorized the app — files stored in that account are not accessible in any other account by default, and vice versa. JWT Authentication requires a private key for signing the JSON Web Token, which is then exchanged for a valid Box access token that can be used to call the API. It is not secure to store this private key in a mobile app that is publicly distributed, so in order to use JWT Authentication the SDK requires that generation of the access token happens in some other service or process. The SDK can then make a request to that service for access tokens to use. To use the SDK with JWT Auth, you'll need to provide a block of code that is responsible for requesting a new token when one is needed. This block can call out to a web service or other endpoint that is responsible for generating the token. The block receives the unique ID of the user who needs to be authenticated, and a completion function to call with the results of the authentication. ``` import BoxSDK let sdk = BoxSDK(clientId: "YOUR CLIENT ID HERE", clientSecret: "YOUR CLIENT SECRET HERE") func getTokensFromAuthServer(uniqueID: String, completion: @escaping (Result<AccessTokenTuple, Error>) -> Void) { // Call auth service with unique ID; it passes back the access token and time-to-live (TTL) in seconds completion(.success((accessToken: accessToken, expiresIn: accessTokenTTLinSeconds))) } // Create client with unique ID — note that this can be any value your application understands. The unique // ID is a mechanism for your application to keep track of or map your users to Box sdk.getDelegatedAuthClient(authClosure: getTokensFromAuthServer, uniqueID: "myUser12345") { result in switch result { case let .success(client): // Use client to make API calls case let .failure(error): // Handle error creating client } } ``` As an alternative, you can call `async` version of `getDelegatedAuthClient(authClosure:uniqueID:)` method: ``` do { let client = try await sdk.getDelegatedAuthClient(authClosure: getTokensFromAuthServer, uniqueID: "myUser12345") // Use client to make API calls } catch { // Handle error creating client } ``` ### Traditional 3-Legged OAuth2 If your application needs to integrate with existing Box users who will provide their login credentials to grant your application access to their account, you will need to go through the standard OAuth2 login flow. A detailed guide for this process is available in the [Authentication with OAuth API documentation](https://developer.box.com/docs/oauth-20). Using an auth code is the most common way of authenticating with the Box API for existing Box users, to integrate with their accounts. The SDK provides a built-in flow for opening a secure web view, into which the user enters their Box login credentials. This requires that the application using the SDK registers itself for a custom URL scheme of the format `boxsdk-<<CLIENT ID>>://boxsdkoauth2redirect`. ``` import BoxSDK let sdk = BoxSDK(clientId: "YOUR CLIENT ID HERE", clientSecret: "YOUR CLIENT SECRET HERE") sdk.getOAuth2Client() { result in switch result { case let .success(client): // Use client to make API calls case let .failure(error): // Handle error creating client } } ``` As an alternative, you can call `async` version of `getOAuth2Client()` method: ``` do { let client = try await sdk.getOAuth2Client(tokenStore: KeychainTokenStore()) // Use client to make API calls } catch { // Handle error creating client } ``` If your application requires a custom URL scheme that differs from the default format `boxsdk-<<CLIENT ID>>://boxsdkoauth2redirect`, you have the option to pass in a custom callback URL string when creating the SDK client. This is the URL to which Box will redirect the user when authentication completes. This requires that the application using the SDK registers itself for the same custom callback URL. ``` import BoxSDK let sdk = BoxSDK(clientId: "YOUR CLIENT ID HERE", clientSecret: "YOUR CLIENT SECRET HERE", callbackURL: "YOUR CALLBACK URL HERE") sdk.getOAuth2Client() { result in switch result { case let .success(client): // Use client to make API calls case let .failure(error): // Handle error creating client } } ``` ### Client Credentials Grant Server auth with CCG allows you to obtain an access token by having client credentials and secret with enterprise or user ID, which allows you to work using service or user account. Obtained token is valid for specified amount of time and it will be refreshed automatically by default. A detailed guide for this process is available in the [Setup with Client Credentials Grant](https://developer.box.com/guides/authentication/client-credentials/client-credentials-setup/). #### Obtaining Service Account token By default, your application has a [Service Account](https://developer.box.com/guides/getting-started/user-types/service-account/) that represents it and can perform API calls. The Service Account is separate from the Box accounts of the application developer and the enterprise admin of any enterprise that has authorized the app — files stored in that account are not accessible in any other account by default, and vice versa. To obtain service account you will have to provide enterprise ID: ``` import BoxSDK let sdk = BoxSDK(clientId: "YOUR CLIENT ID HERE", clientSecret: "YOUR CLIENT SECRET HERE") sdk.getCCGClientForAccountService(enterpriseId: "YOUR ENTERPRISE ID HERE") { result in switch result { case let .success(client): // Use client to make API calls case let .failure(error): // Handle error creating client } } ``` As an alternative, you can call `async` version of `getCCGClientForAccountService(enterpriseId:)` method: ``` do { let client = try await sdk.getCCGClientForAccountService(enterpriseId: "YOUR ENTERPRISE ID HERE") // Use client to make API calls } catch { // Handle error creating client } ``` Remember that you can still make calls on behalf of managed users, which are part of your enterprise, by using [As-User](#as-user) behavior. #### Obtaining User token To obtain client for making calls as an App User or Managed User you will have to provide user ID: ``` import BoxSDK let sdk = BoxSDK(clientId: "YOUR CLIENT ID HERE", clientSecret: "YOUR CLIENT SECRET HERE") sdk.getCCGClientForUser(userId: "YOUR USER ID HERE") { result in switch result { case let .success(client): // Use client to make API calls case let .failure(error): // Handle error creating client } } ``` As an alternative, you can call `async` version of `getCCGClientForUser(userId:)` method: ``` do { let client = try await sdk.getCCGClientForUser(userId: "YOUR USER ID HERE") // Use client to make API calls } catch { // Handle error creating client } ``` ## Token Store In order to maintain authentication and ensure that your users do not need to log in again every time they use your application, you should persist their token information to some sort of durable store (e.g. the Keychain). The SDK provides a `TokenStore` interface which allows you to read and write tokens to whatever store your application uses at the correct points in the SDK's token handling logic. The interface requires three methods: The SDK provides a default `KeychainTokenStore` implementation that stores the user's tokens on the device Keychain, but you can also create your own custom token store by implementing something that conforms to the `TokenStore` protocol: ``` // The token store constructor should create a specific store instance for the user being authenticated — it may need // to take in a user ID or other unique identifier public protocol TokenStore { // Read the user's tokens from the data store and pass them to the completion func read(completion: @escaping (Result<TokenInfo, Error>) -> Void) // Write the token information to the store. The tokenInfo argument can be serialized for storage. // Call the completion after the write has completed. func write(tokenInfo: TokenInfo, completion: @escaping (Result<Void, Error>) -> Void) // Delete the user's token information from the store, and call the completion after the write. func clear(completion: @escaping (Result<Void, Error>) -> Void) } ``` ## As-User The `As-User` header is used to make API calls from one user account on behalf of another user. This is used by enterprise administrators and Service Accounts to make API calls on behalf of managed users or app users. This requires the API request to contain an `As-User: USER-ID` header with each API call, which the SDK handles automatically. For more details, see the [documentation on As-User](https://developer.box.com/reference#as-user-1). The following examples assume that the `client` has been instantiated with an access token belonging to an admin-role user or Service Account with appropriate privileges to make As-User calls. The `BoxClient#asUser(withId: String)` method clones the client to impersonate a given user. Note that a new client is created, and the original client instance is left unmodified. All calls made with the new instance of client will be made in context of the impersonated user. ``` let asUserClient = client.asUser(withId: "USER ID"); asUserClient.users.getCurrentUser() { result in guard case let .success(user) = result else { print("Could not retrieve user info!") return } print("Call was made as \(user.name) (\(user.login))") } ``` ## Token Exchange You can exchange a client's access token for one with a lower scope, in order to restrict the permissions for a child client or to pass to a less secure location (e.g. a browser-based app). To exchange the token held by a client for a new token with only `item_preview` scope, restricted to a single file: ``` client.exchangeToken(scope: ["item_preview"], resource: "https://api.box.com/2.0/files/123456789") { result in guard case let .success(tokenInfo) = result else { print("Error exchanging tokens") return } print("Got new access token: \(tokenInfo.accessToken)") } ``` ## Revoking Tokens Access tokens for a client can be revoked when needed. This removes the client's authentication, and the client can no longer be used after this operation. ``` client.destroy() { result in guard case .success = result else { print("Tokens could not be revoked!") } print("Tokens were successfully revoked") } ``` --- ### Authentication **Type:** page | **Section:** Additional Resources Authentication Authentication Ways to Authenticate Developer Token Server Auth with JWT Traditional 3-Legged OAuth2 Client Credentials Grant… # Authentication [Authentication](#authentication) [Ways to Authenticate](#ways-to-authenticate) - [Developer Token](#developer-token) - [Server Auth with JWT](#server-auth-with-jwt) - [Traditional 3-Legged OAuth2](#traditional-3-legged-oauth2) [Client Credentials Grant](#client-credentials-grant) - [Obtaining Service Account token](#obtaining-service-account-token) - [Obtaining User token](#obtaining-user-token) [Token Store](#token-store) [As-User](#as-user) [Token Exchange](#token-exchange) [Revoking Tokens](#revoking-tokens) The Box API uses two flavors of OAuth2 for authentication, both of which can can be difficult to implement. The SDK makes it easier by providing classes that handle obtaining tokens and automatically refreshing them when possible. See the [Auth Types documentation](https://developer.box.com/docs/authentication-types-and-security) for a detailed overview of how the Box API handles authentication and how to choose between the different authentication types. ## Ways to Authenticate ### Developer Token The fastest way to get started using the API is with developer tokens. A developer token is a short-lived access token that cannot be refreshed and can only be used with your own account. Therefore, they're only useful for testing an app and aren't suitable for use in production. You can obtain a developer token from your application's [developer console](https://app.box.com/developers/console) page. The following example creates an SDK client with a developer token: ``` import BoxSDK let client = BoxSDK.getClient(token: "YOUR_DEVELOPER_TOKEN") ``` ### Server Auth with JWT Server auth allows your application to authenticate itself with the Box API for a given enterprise. By default, your application has a [Service Account](https://developer.box.com/docs/service-account) that represents it and can perform API calls. The Service Account is separate from the Box accounts of the application developer and the enterprise admin of any enterprise that has authorized the app — files stored in that account are not accessible in any other account by default, and vice versa. JWT Authentication requires a private key for signing the JSON Web Token, which is then exchanged for a valid Box access token that can be used to call the API. It is not secure to store this private key in a mobile app that is publicly distributed, so in order to use JWT Authentication the SDK requires that generation of the access token happens in some other service or process. The SDK can then make a request to that service for access tokens to use. To use the SDK with JWT Auth, you'll need to provide a block of code that is responsible for requesting a new token when one is needed. This block can call out to a web service or other endpoint that is responsible for generating the token. The block receives the unique ID of the user who needs to be authenticated, and a completion function to call with the results of the authentication. ``` import BoxSDK let sdk = BoxSDK(clientId: "YOUR CLIENT ID HERE", clientSecret: "YOUR CLIENT SECRET HERE") func getTokensFromAuthServer(uniqueID: String, completion: @escaping (Result<AccessTokenTuple, Error>) -> Void) { // Call auth service with unique ID; it passes back the access token and time-to-live (TTL) in seconds completion(.success((accessToken: accessToken, expiresIn: accessTokenTTLinSeconds))) } // Create client with unique ID — note that this can be any value your application understands. The unique // ID is a mechanism for your application to keep track of or map your users to Box sdk.getDelegatedAuthClient(authClosure: getTokensFromAuthServer, uniqueID: "myUser12345") { result in switch result { case let .success(client): // Use client to make API calls case let .failure(error): // Handle error creating client } } ``` As an alternative, you can call `async` version of `getDelegatedAuthClient(authClosure:uniqueID:)` method: ``` do { let client = try await sdk.getDelegatedAuthClient(authClosure: getTokensFromAuthServer, uniqueID: "myUser12345") // Use client to make API calls } catch { // Handle error creating client } ``` ### Traditional 3-Legged OAuth2 If your application needs to integrate with existing Box users who will provide their login credentials to grant your application access to their account, you will need to go through the standard OAuth2 login flow. A detailed guide for this process is available in the [Authentication with OAuth API documentation](https://developer.box.com/docs/oauth-20). Using an auth code is the most common way of authenticating with the Box API for existing Box users, to integrate with their accounts. The SDK provides a built-in flow for opening a secure web view, into which the user enters their Box login credentials. This requires that the application using the SDK registers itself for a custom URL scheme of the format `boxsdk-<<CLIENT ID>>://boxsdkoauth2redirect`. ``` import BoxSDK let sdk = BoxSDK(clientId: "YOUR CLIENT ID HERE", clientSecret: "YOUR CLIENT SECRET HERE") sdk.getOAuth2Client() { result in switch result { case let .success(client): // Use client to make API calls case let .failure(error): // Handle error creating client } } ``` As an alternative, you can call `async` version of `getOAuth2Client()` method: ``` do { let client = try await sdk.getOAuth2Client(tokenStore: KeychainTokenStore()) // Use client to make API calls } catch { // Handle error creating client } ``` If your application requires a custom URL scheme that differs from the default format `boxsdk-<<CLIENT ID>>://boxsdkoauth2redirect`, you have the option to pass in a custom callback URL string when creating the SDK client. This is the URL to which Box will redirect the user when authentication completes. This requires that the application using the SDK registers itself for the same custom callback URL. ``` import BoxSDK let sdk = BoxSDK(clientId: "YOUR CLIENT ID HERE", clientSecret: "YOUR CLIENT SECRET HERE", callbackURL: "YOUR CALLBACK URL HERE") sdk.getOAuth2Client() { result in switch result { case let .success(client): // Use client to make API calls case let .failure(error): // Handle error creating client } } ``` ### Client Credentials Grant Server auth with CCG allows you to obtain an access token by having client credentials and secret with enterprise or user ID, which allows you to work using service or user account. Obtained token is valid for specified amount of time and it will be refreshed automatically by default. A detailed guide for this process is available in the [Setup with Client Credentials Grant](https://developer.box.com/guides/authentication/client-credentials/client-credentials-setup/). #### Obtaining Service Account token By default, your application has a [Service Account](https://developer.box.com/guides/getting-started/user-types/service-account/) that represents it and can perform API calls. The Service Account is separate from the Box accounts of the application developer and the enterprise admin of any enterprise that has authorized the app — files stored in that account are not accessible in any other account by default, and vice versa. To obtain service account you will have to provide enterprise ID: ``` import BoxSDK let sdk = BoxSDK(clientId: "YOUR CLIENT ID HERE", clientSecret: "YOUR CLIENT SECRET HERE") sdk.getCCGClientForAccountService(enterpriseId: "YOUR ENTERPRISE ID HERE") { result in switch result { case let .success(client): // Use client to make API calls case let .failure(error): // Handle error creating client } } ``` As an alternative, you can call `async` version of `getCCGClientForAccountService(enterpriseId:)` method: ``` do { let client = try await sdk.getCCGClientForAccountService(enterpriseId: "YOUR ENTERPRISE ID HERE") // Use client to make API calls } catch { // Handle error creating client } ``` Remember that you can still make calls on behalf of managed users, which are part of your enterprise, by using [As-User](#as-user) behavior. #### Obtaining User token To obtain client for making calls as an App User or Managed User you will have to provide user ID: ``` import BoxSDK let sdk = BoxSDK(clientId: "YOUR CLIENT ID HERE", clientSecret: "YOUR CLIENT SECRET HERE") sdk.getCCGClientForUser(userId: "YOUR USER ID HERE") { result in switch result { case let .success(client): // Use client to make API calls case let .failure(error): // Handle error creating client } } ``` As an alternative, you can call `async` version of `getCCGClientForUser(userId:)` method: ``` do { let client = try await sdk.getCCGClientForUser(userId: "YOUR USER ID HERE") // Use client to make API calls } catch { // Handle error creating client } ``` ## Token Store In order to maintain authentication and ensure that your users do not need to log in again every time they use your application, you should persist their token information to some sort of durable store (e.g. the Keychain). The SDK provides a `TokenStore` interface which allows you to read and write tokens to whatever store your application uses at the correct points in the SDK's token handling logic. The interface requires three methods: The SDK provides a default `KeychainTokenStore` implementation that stores the user's tokens on the device Keychain, but you can also create your own custom token store by implementing something that conforms to the `TokenStore` protocol: ``` // The token store constructor should create a specific store instance for the user being authenticated — it may need // to take in a user ID or other unique identifier public protocol TokenStore { // Read the user's tokens from the data store and pass them to the completion func read(completion: @escaping (Result<TokenInfo, Error>) -> Void) // Write the token information to the store. The tokenInfo argument can be serialized for storage. // Call the completion after the write has completed. func write(tokenInfo: TokenInfo, completion: @escaping (Result<Void, Error>) -> Void) // Delete the user's token information from the store, and call the completion after the write. func clear(completion: @escaping (Result<Void, Error>) -> Void) } ``` ## As-User The `As-User` header is used to make API calls from one user account on behalf of another user. This is used by enterprise administrators and Service Accounts to make API calls on behalf of managed users or app users. This requires the API request to contain an `As-User: USER-ID` header with each API call, which the SDK handles automatically. For more details, see the [documentation on As-User](https://developer.box.com/reference#as-user-1). The following examples assume that the `client` has been instantiated with an access token belonging to an admin-role user or Service Account with appropriate privileges to make As-User calls. The `BoxClient#asUser(withId: String)` method clones the client to impersonate a given user. Note that a new client is created, and the original client instance is left unmodified. All calls made with the new instance of client will be made in context of the impersonated user. ``` let asUserClient = client.asUser(withId: "USER ID"); asUserClient.users.getCurrentUser() { result in guard case let .success(user) = result else { print("Could not retrieve user info!") return } print("Call was made as \(user.name) (\(user.login))") } ``` ## Token Exchange You can exchange a client's access token for one with a lower scope, in order to restrict the permissions for a child client or to pass to a less secure location (e.g. a browser-based app). To exchange the token held by a client for a new token with only `item_preview` scope, restricted to a single file: ``` client.exchangeToken(scope: ["item_preview"], resource: "https://api.box.com/2.0/files/123456789") { result in guard case let .success(tokenInfo) = result else { print("Error exchanging tokens") return } print("Got new access token: \(tokenInfo.accessToken)") } ``` ## Revoking Tokens Access tokens for a client can be revoked when needed. This removes the client's authentication, and the client can no longer be used after this operation. ``` client.destroy() { result in guard case .success = result else { print("Tokens could not be revoked!") } print("Tokens were successfully revoked") } ``` --- ### Authentication **Type:** page | **Section:** Additional Resources Authentication Authentication Authentication methods Developer Token JWT Auth Authenticate Enterprise Authenticate user Client Credentials… # Authentication - [Authentication](#authentication) [Authentication methods](#authentication-methods) - [Developer Token](#developer-token) [JWT Auth](#jwt-auth) - [Authenticate Enterprise](#authenticate-enterprise) - [Authenticate user](#authenticate-user) [Client Credentials Grant](#client-credentials-grant) - [Obtaining Service Account token](#obtaining-service-account-token) - [Obtaining User token](#obtaining-user-token) - [Switching between Service Account and User](#switching-between-service-account-and-user) [OAuth 2.0 Auth](#oauth-20-auth) - [Authentication with OAuth2](#authentication-with-oauth2) - [Injecting existing token into BoxOAuth](#injecting-existing-token-into-boxoauth) [Retrieve current access token](#retrieve-current-access-token) [Refresh access token](#refresh-access-token) [Revoke token](#revoke-token) [Downscope token](#downscope-token) [Token storage](#token-storage) - [In-memory token storage](#in-memory-token-storage) - [Custom storage](#custom-storage) # Authentication methods ## Developer Token The fastest way to get started using the API is with developer token. A developer token is simply a short-lived access token that cannot be refreshed and can only be used with your own account. Therefore, they're only useful for testing an app and aren't suitable for production. You can obtain a developer token from your application's [developer console](https://app.box.com/developers/console) page. To create a `BoxClient` with a developer token, construct an `BoxDeveloperTokenAuth` object with the `token` set to the developer token and construct the client with that. ``` import { BoxClient } from 'box-typescript-sdk-gen/client.generated'; import { BoxDeveloperTokenAuth } from 'box-typescript-sdk-gen/box/developerTokenAuth.generated'; const auth = new BoxDeveloperTokenAuth({ token: 'DEVELOPER_TOKEN_GOES_HERE' }); const client = new BoxClient({ auth }); const me = await client.users.getUserMe(); console.log(`My user ID is ${me.id}`); ``` ## JWT Auth Before using JWT Auth make sure you set up correctly your Box platform app. The guide with all required steps can be found here: [Setup with JWT](https://developer.box.com/guides/authentication/jwt/jwt-setup/) ### Authenticate Enterprise JWT auth allows your application to authenticate itself with the Box API for a given enterprise. By default, your application has a [Service Account](https://developer.box.com/guides/getting-started/user-types/service-account/) that represents it and can perform API calls. The Service Account is separate from the Box accounts of the application developer and the enterprise admin of any enterprise that has authorized the app — files stored in that account are not accessible in any other account by default, and vice versa. If you generated your public and private keys automatically through the [Box Developer Console](https://app.box.com/developers/console), you can use the JSON file created there to configure your SDK instance and create a client to make calls as the Service Account. Call one of static `BoxJwtAuth` method: `JwtConfig.fromConfigFile(configFilePath)` and pass JSON file local path or `JwtConfig.fromConfigJsonString(configJsonString)` and pass JSON config file content as string. ``` import { BoxClient } from 'box-typescript-sdk-gen/client.generated'; import { BoxJwtAuth, JwtConfig, } from 'box-typescript-sdk-gen/box/jwtAuth.generated'; const jwtConfig = JwtConfig.fromConfigFile('/path/to/settings.json'); const jwtAuth = new BoxJwtAuth({ config: jwtConfig }); const client = new BoxClient({ auth: jwtAuth }); const me = await client.users.getUserMe(); console.log(`My user ID is ${me.id}`); ``` Otherwise, you'll need to provide the necessary configuration fields directly to the `JwtConfig` constructor: ``` import { BoxClient } from 'box-typescript-sdk-gen/client.generated'; import { BoxJwtAuth, JwtConfig, } from 'box-typescript-sdk-gen/box/jwtAuth.generated'; const jwtConfig = new JwtConfig({ clientId: 'YOUR_CLIENT_ID', clientSecret: 'YOUR_CLIENT_SECRET', jwtKeyId: 'YOUR_JWT_KEY_ID', privateKey: 'YOUR_PRIVATE_KEY', privateKeyPassphrase: 'PASSPHRASE', enterpriseId: 'YOUR_ENTERPRISE_ID', }); const jwtAuth = new BoxJwtAuth({ config: jwtConfig }); const serviceAccountClient = new BoxClient({ auth: jwtAuth }); ``` ### Authenticate user App auth applications also often have associated [App Users](https://developer.box.com/guides/getting-started/user-types/app-users/), which are created and managed directly by the application — they do not have normal login credentials, and can only be accessed through the Box API by the application that created them. You may authenticate as the Service Account to provision and manage users, or as an individual app user to make calls as that user. See the [API documentation](https://developer.box.com/) for detailed instructions on how to use app auth. Clients for making calls as an App User can be created with the same JSON JWT config file generated through the [Box Developer Console](https://app.box.com/developers/console). Calling `jwtAuth.withUserSubject('USER_ID')` method will return a new auth object, which is authenticated as the user with provided id, leaving the original object unchanged. ``` import { BoxClient } from 'box-typescript-sdk-gen/client.generated'; import { BoxJwtAuth, JwtConfig, } from 'box-typescript-sdk-gen/box/jwtAuth.generated'; const jwtConfig = JwtConfig.fromConfigFile('/path/to/settings.json'); const jwtAuth = new BoxJwtAuth({ config: jwtConfig }); const userAuth = jwtAuth.withUserSubject('USER_ID'); const userClient = new BoxClient({ auth: userAuth }); ``` Alternatively, clients for making calls as an App User can be created with the same `JwtConfig` constructor as in the above examples, similarly to creating a Service Account client. Simply pass the `userId` instead of `enterpriseId` when constructing the auth config instance: ``` import { BoxClient } from 'box-typescript-sdk-gen/client.generated'; import { BoxJwtAuth, JwtConfig, } from 'box-typescript-sdk-gen/box/jwtAuth.generated'; const jwtConfig = new JwtConfig({ clientId: 'YOUR_CLIENT_ID', clientSecret: 'YOUR_CLIENT_SECRET', jwtKeyId: 'YOUR_JWT_KEY_ID', privateKey: 'YOUR_PRIVATE_KEY', privateKeyPassphrase: 'PASSPHRASE', userId: 'USER_ID', }); const jwtAuth = new BoxJwtAuth({ config: jwtConfig }); const userClient = new BoxClient({ auth: jwtAuth }); ``` ## Client Credentials Grant Before using Client Credentials Grant Auth make sure you set up correctly your Box platform app. The guide with all required steps can be found here: [Setup with Client Credentials Grant](https://developer.box.com/guides/authentication/client-credentials/client-credentials-setup/) Client Credentials Grant Auth method allows you to obtain an access token by having client credentials and secret with enterprise or user ID, which allows you to work using service or user account. You can use `CCGAuth` to initialize a client object the same way as for other authentication types: ``` import { BoxClient } from 'box-typescript-sdk-gen/client.generated'; import { BoxCcgAuth, CcgConfig, } from 'box-typescript-sdk-gen/box/ccgAuth.generated'; const ccgConfig = new CcgConfig({ userId: 'YOUR_USER_ID', clientId: 'YOUR_CLIENT_ID', clientSecret: 'YOUR_CLIENT_SECRET', }); const ccgAuth = new BoxCcgAuth({ config: ccgConfig }); const client = new BoxClient({ auth: ccgAuth }); const me = await client.users.getUserMe(); console.log(`My user ID is ${me.id}`); ``` Obtained token is valid for specified amount of time, it will be refreshed automatically by default. ### Obtaining Service Account token The [Service Account](https://developer.box.com/guides/getting-started/user-types/service-account//) is separate from the Box accounts of the application developer and the enterprise admin of any enterprise that has authorized the app — files stored in that account are not accessible in any other account by default, and vice versa. To obtain service account you will have to provide enterprise ID with client id and secret: ``` import { BoxClient } from 'box-typescript-sdk-gen/client.generated'; import { BoxCcgAuth, CcgConfig, } from 'box-typescript-sdk-gen/box/ccgAuth.generated'; const ccgConfig = new CcgConfig({ enterpriseId: 'YOUR_ENTERPRISE_ID', clientId: 'YOUR_CLIENT_ID', clientSecret: 'YOUR_CLIENT_SECRET', }); const ccgAuth = new BoxCcgAuth({ config: ccgConfig }); const client = new BoxClient({ auth: ccgAuth }); ``` ### Obtaining User token In order to enable obtaining user token you have to go to your application configuration that can be found [here](https://app.box.com/developers/console). In `Configuration` tab, in section `Advanced Features` select `Generate user access tokens`. Do not forget to re-authorize application if it was already authorized. To obtain user account you will have to provide user ID with client id and secret. ``` import { BoxClient } from 'box-typescript-sdk-gen/client.generated'; import { BoxCcgAuth, CcgConfig, } from 'box-typescript-sdk-gen/box/ccgAuth.generated'; const ccgConfig = new CcgConfig({ userId: 'YOUR_USER_ID', clientId: 'YOUR_CLIENT_ID', clientSecret: 'YOUR_CLIENT_SECRET', }); const ccgAuth = new BoxCcgAuth({ config: ccgConfig }); const client = new BoxClient({ auth: ccgAuth }); ``` ### Switching between Service Account and User You can easily switch to be authenticated as a Service Account or as a User. To create a new auth object authenticated as Service Account you can call: ``` const enterpriseAuth = ccgAuth.withEnterpriseSubject('YOUR_ENTERPRISE_ID'); const enterpriseClient = new BoxClient({ auth: enterpriseAuth }); ``` To authenticate with user subject call: ``` const userAuth = ccgAuth.withUserSubject('YOUR_USER_ID'); const userClient = new BoxClient({ auth: userAuth }); ``` The new token will be automatically fetched with a next API call. ## OAuth 2.0 Auth ### Authentication with OAuth2 If your application needs to integrate with existing Box users who will provide their login credentials to grant your application access to their account, you will need to go through the standard OAuth2 login flow. A detailed guide for this process is available in the [Authentication with OAuth API documentation](https://developer.box.com/en/guides/authentication/oauth2/). Using an auth code is the most common way of authenticating with the Box API for existing Box users, to integrate with their accounts. Your application must provide a way for the user to login to Box (usually with a browser or web view) in order to obtain an auth code. ``` import { BoxOAuth, OAuthConfig, } from 'box-typescript-sdk-gen/box/oauth.generated'; const config = new OAuthConfig({ clientId: 'OAUTH_CLIENT_ID', clientSecret: 'OAUTH_CLIENT_SECRET', }); const oauth = new BoxOAuth({ config: config }); // the URL to redirect the user to var authorize_url = oauth.getAuthorizeUrl(); ``` After a user logs in and grants your application access to their Box account, they will be redirected to your application's `redirect_uri` which will contain an auth code. This auth code can then be used along with your client ID and client secret to establish an API connection. You need to provide the auth code to the SDK to obtain an access token. Calling `oauth.getTokensAuthorizationCodeGrant('code')` will exchange the auth code for an access token and save it in the `BoxOAuth` token storage. The SDK will automatically refresh the token when needed. All you need to do is create a client object with the `BoxOAuth` object and start making API calls. ``` await auth.retrieveToken(); ``` # Refresh access token Access tokens are short-lived and need to be refreshed periodically. The SDK will automatically refresh the token when needed. If you want to manually refresh the token, you can use the following code: ``` await auth.refreshToken(); ``` # Revoke token Access tokens for a client can be revoked when needed. This call invalidates old token. For BoxCcgAuth and BoxJwtAuth you can still reuse the `auth` object to retrieve a new token. If you make any new call after revoking the token, a new token will be automatically retrieved. For BoxOAuth it would be necessary to manually go through the authentication process again. For BoxDeveloperTokenAuth, it is necessary to provide a DeveloperTokenConfig during initialization, containing the client ID and client secret. To revoke current client's tokens in the storage use the following code: ``` await auth.revokeTokens(); // client's tokens have been revoked ``` # Downscope token You can exchange a client's access token for one with a lower scope, in order to restrict the permissions for a child client or to pass to a less secure location (e.g. a browser-based app). A downscoped token does not include a refresh token. In such a scenario, to obtain a new downscoped token, refresh the original token and utilize the newly acquired token to obtain the downscoped token. More information about downscoping tokens can be found [here](https://developer.box.com/guides/authentication/tokens/downscope/). If you want to learn more about available scopes please go [here](https://developer.box.com/guides/api-calls/permissions-and-errors/scopes/#scopes-for-downscoping). For example to get a new token with only `item_preview` scope, restricted to a single file, suitable for the [Content Preview UI Element](https://developer.box.com/en/guides/embed/ui-elements/preview/) you can use the following code. You can also initialize `BoxDeveloperTokenAuth` with the retrieved access token and use it to create a new Client. ``` let resource = 'https://api.box.com/2.0/files/123456789'; let token = await oauth.downscopeToken(['item_preview'], resource); const auth = new BoxDeveloperTokenAuth({ token: token.accessToken }); const client = new BoxClient({ auth }); ``` # Token storage ## In-memory token storage By default, the SDK stores the access token in volatile memory. When rerunning your application, the access token won't be reused from the previous run; a new token has to be obtained again. To use in-memory token storage, you don't need to do anything more than create an Auth class using AuthConfig, for example, for OAuth: ``` const config = new OAuthConfig({ clientId: 'OAUTH_CLIENT_ID', clientSecret: 'OAUTH_CLIENT_SECRET', }); const oauth = new BoxOAuth({ config: config }); ``` ## Custom storage You can also provide a custom token storage class. All you need to do is create a class that implements `TokenStorage` interface and pass an instance of your class to the AuthConfig constructor. ``` class MyCustomTokenStorage implements TokenStorage { async store(token: AccessToken): Promise<undefined> { // store token in your custom storage } async get(): Promise<undefined | AccessToken> { // retrieve token from your custom storage } async clear(): Promise<undefined> { // clear token from your custom storage } } const config = new OAuthConfig({ clientId: 'OAUTH_CLIENT_ID', clientSecret: 'OAUTH_CLIENT_SECRET', tokenStorage: new MyCustomTokenStorage(), }); const oauth = new BoxOAuth({ config: config }); ``` --- ### Authentication **Type:** page | **Section:** Additional Resources Authentication Authentication Authentication methods Developer Token JWT Auth Authenticate Enterprise Authenticate user Client Credentials… # Authentication - [Authentication](#authentication) [Authentication methods](#authentication-methods) - [Developer Token](#developer-token) [JWT Auth](#jwt-auth) - [Authenticate Enterprise](#authenticate-enterprise) - [Authenticate user](#authenticate-user) [Client Credentials Grant](#client-credentials-grant) - [Obtaining Service Account token](#obtaining-service-account-token) - [Obtaining User token](#obtaining-user-token) - [Switching between Service Account and User](#switching-between-service-account-and-user) [OAuth 2.0 Auth](#oauth-20-auth) - [Authentication with OAuth2](#authentication-with-oauth2) - [Injecting existing token into BoxOAuth](#injecting-existing-token-into-boxoauth) [Retrieve current access token](#retrieve-current-access-token) [Refresh access token](#refresh-access-token) [Revoke token](#revoke-token) [Downscope token](#downscope-token) [Token storage](#token-storage) - [In-memory token storage](#in-memory-token-storage) - [File token storage](#file-token-storage) - [File with in-memory token storage](#file-with-in-memory-token-storage) - [Custom storage](#custom-storage) # Authentication methods ## Developer Token The fastest way to get started using the API is with developer token. A developer token is simply a short-lived access token that cannot be refreshed and can only be used with your own account. Therefore, they're only useful for testing an app and aren't suitable for production. You can obtain a developer token from your application's [developer console](https://app.box.com/developers/console) page. To create a `BoxClient` with a developer token, construct an `BoxDeveloperTokenAuth` object with the `token` set to the developer token and construct the client with that. ``` from box_sdk_gen import BoxClient, BoxDeveloperTokenAuth auth = BoxDeveloperTokenAuth(token="DEVELOPER_TOKEN_GOES_HERE") client = BoxClient(auth=auth) me = client.users.get_user_me() print(f"My user ID is {me.id}") ``` ## JWT Auth Authenticating with a JWT requires some extra dependencies. To get them, use ``` pip install "box-sdk-gen[jwt]" ``` Before using JWT Auth make sure you set up correctly your Box platform app. The guide with all required steps can be found here: [Setup with JWT](https://developer.box.com/guides/authentication/jwt/jwt-setup/) ### Authenticate Enterprise JWT auth allows your application to authenticate itself with the Box API for a given enterprise. By default, your application has a [Service Account](https://developer.box.com/guides/getting-started/user-types/service-account/) that represents it and can perform API calls. The Service Account is separate from the Box accounts of the application developer and the enterprise admin of any enterprise that has authorized the app — files stored in that account are not accessible in any other account by default, and vice versa. If you generated your public and private keys automatically through the [Box Developer Console](https://app.box.com/developers/console), you can use the JSON file created there to configure your SDK instance and create a client to make calls as the Service Account. Call one of static `BoxJWTAuth` method: `JWTConfig.from_config_file(config_file_path='/path/to/settings.json')` and pass JSON file local path or `JWTConfig.from_config_json_string(config_json_string)` and pass JSON config file content as string. ``` from box_sdk_gen import BoxClient, BoxJWTAuth, JWTConfig jwt_config = JWTConfig.from_config_file(config_file_path="/path/to/settings.json") auth = BoxJWTAuth(config=jwt_config) client = BoxClient(auth=auth) service_account = client.users.get_user_me() print(f"Service Account user ID is {service_account.id}") ``` Otherwise, you'll need to provide the necessary configuration fields directly to the `JWTConfig` constructor: ``` from box_sdk_gen import BoxClient, BoxJWTAuth, JWTConfig jwt_config = JWTConfig( client_id="YOUR_CLIENT_ID", client_secret="YOUR_CLIENT_SECRET", jwt_key_id="YOUR_JWT_KEY_ID", private_key="YOUR_PRIVATE_KEY", private_key_passphrase="PASSPHRASE", enterprise_id="YOUR_ENTERPRISE_ID", ) auth = BoxJWTAuth(config=jwt_config) service_account_client = BoxClient(auth=auth) ``` ### Authenticate user App auth applications also often have associated [App Users](https://developer.box.com/guides/getting-started/user-types/app-users/), which are created and managed directly by the application — they do not have normal login credentials, and can only be accessed through the Box API by the application that created them. You may authenticate as the Service Account to provision and manage users, or as an individual app user to make calls as that user. See the [API documentation](https://developer.box.com/) for detailed instructions on how to use app auth. Clients for making calls as an App User can be created with the same JSON JWT config file generated through the [Box Developer Console](https://app.box.com/developers/console). Calling `auth.with_user_subject('USER_ID')` method will return a new auth object, which is authenticated as the user with provided id, leaving the original object unchanged. ``` from box_sdk_gen import BoxClient, BoxJWTAuth, JWTConfig jwt_config = JWTConfig.from_config_file(config_file_path="/path/to/settings.json") auth = BoxJWTAuth(config=jwt_config) user_auth = auth.with_user_subject("USER_ID") user_client = BoxClient(auth=user_auth) ``` Alternatively, clients for making calls as an App User can be created with the same `JWTConfig` constructor as in the above examples, similarly to creating a Service Account client. Simply pass the `user_id` instead of `enterprise_id` when constructing the auth config instance: ``` from box_sdk_gen import BoxClient, BoxJWTAuth, JWTConfig jwt_config = JWTConfig( client_id="YOUR_CLIENT_ID", client_secret="YOUR_CLIENT_SECRET", jwt_key_id="YOUR_JWT_KEY_ID", private_key="YOUR_PRIVATE_KEY", private_key_passphrase="PASSPHRASE", user_id="USER_ID", ) auth = BoxJWTAuth(config=jwt_config) user_client = BoxClient(auth=auth) ``` ## Client Credentials Grant Before using Client Credentials Grant Auth make sure you set up correctly your Box platform app. The guide with all required steps can be found here: [Setup with Client Credentials Grant](https://developer.box.com/guides/authentication/client-credentials/client-credentials-setup/) Client Credentials Grant Auth method allows you to obtain an access token by having client credentials and secret with enterprise or user ID, which allows you to work using service or user account. You can use `BoxCCGAuth` to initialize a client object the same way as for other authentication types: ``` from box_sdk_gen import BoxClient, BoxCCGAuth, CCGConfig ccg_config = CCGConfig( client_id="YOUR_CLIENT_ID", client_secret="YOUR_CLIENT_SECRET", user_id="YOUR_USER_ID", ) auth = BoxCCGAuth(config=ccg_config) client = BoxClient(auth=auth) print(f"Id of the authenticated user is: {client.users.get_user_me().id}") ``` Obtained token is valid for specified amount of time, it will be refreshed automatically by default. ### Obtaining Service Account token The [Service Account](https://developer.box.com/guides/getting-started/user-types/service-account//) is separate from the Box accounts of the application developer and the enterprise admin of any enterprise that has authorized the app — files stored in that account are not accessible in any other account by default, and vice versa. To obtain service account you will have to provide enterprise ID with client id and secret: ``` from box_sdk_gen import BoxClient, BoxCCGAuth, CCGConfig ccg_config = CCGConfig( client_id="YOUR_CLIENT_ID", client_secret="YOUR_CLIENT_SECRET", enterprise_id="YOUR_ENTERPRISE_ID", ) auth = BoxCCGAuth(config=ccg_config) client = BoxClient(auth=auth) ``` ### Obtaining User token In order to enable obtaining user token you have to go to your application configuration that can be found [here](https://app.box.com/developers/console). In `Configuration` tab, in section `Advanced Features` select `Generate user access tokens`. Do not forget to re-authorize application if it was already authorized. To obtain user account you will have to provide user ID with client id and secret. ``` from box_sdk_gen import BoxClient, BoxCCGAuth, CCGConfig ccg_config = CCGConfig( client_id="YOUR_CLIENT_ID", client_secret="YOUR_CLIENT_SECRET", user_id="YOUR_USER_ID", ) auth = BoxCCGAuth(config=ccg_config) client = BoxClient(auth=auth) ``` ### Switching between Service Account and User You can easily switch to be authenticated as a Service Account or as a User. To create a new auth object authenticated as Service Account you can call: ``` enterprise_auth = auth.with_enterprise_subject(enterprise_id="YOUR_ENTERPRISE_ID") enterprise_client = BoxClient(auth=enterprise_auth) ``` To authenticate with user subject call: ``` user_auth = auth.with_user_subject(user_id="YOUR_USER_ID") user_client = BoxClient(auth=user_auth) ``` The new token will be automatically fetched with a next API call. ## OAuth 2.0 Auth ### Authentication with OAuth2 If your application needs to integrate with existing Box users who will provide their login credentials to grant your application access to their account, you will need to go through the standard OAuth2 login flow. A detailed guide for this process is available in the [Authentication with OAuth API documentation](https://developer.box.com/en/guides/authentication/oauth2/). Using an auth code is the most common way of authenticating with the Box API for existing Box users, to integrate with their accounts. Your application must provide a way for the user to login to Box (usually with a browser or web view) in order to obtain an auth code. ``` from box_sdk_gen import BoxOAuth, OAuthConfig auth = BoxOAuth( OAuthConfig(client_id="YOUR_CLIENT_ID", client_secret="YOUR_CLIENT_SECRET") ) auth_url = auth.get_authorize_url() ``` After a user logs in and grants your application access to their Box account, they will be redirected to your application's `redirect_uri` which will contain an auth code. This auth code can then be used along with your client ID and client secret to establish an API connection. You need to provide the auth code to the SDK to obtain an access token. Calling `auth.get_tokens_authorization_code_grant('YOUR_ACCESS_CODE')` will exchange the auth code for an access token and save it in the `BoxOAuth` token storage. The SDK will automatically refresh the token when needed. All you need to do is create a client object with the `BoxOAuth` object and start making API calls. ``` auth.retrieve_token() ``` # Refresh access token Access tokens are short-lived and need to be refreshed periodically. The SDK will automatically refresh the token when needed. If you want to manually refresh the token, you can use the following code: ``` auth.refresh_token() ``` # Revoke token Access tokens for a client can be revoked when needed. This call invalidates old token. For BoxCCGAuth and BoxJWTAuth you can still reuse the `auth` object to retrieve a new token. If you make any new call after revoking the token, a new token will be automatically retrieved. For BoxOAuth it would be necessary to manually go through the authentication process again. For BoxDeveloperTokenAuth, it is necessary to provide a DeveloperTokenConfig during initialization, containing the client ID and client secret. To revoke current client's tokens in the storage use the following code: ``` client.auth.revoke_token() ``` # Downscope token You can exchange a client's access token for one with a lower scope, in order to restrict the permissions for a child client or to pass to a less secure location (e.g. a browser-based app). A downscoped token does not include a refresh token. In such a scenario, to obtain a new downscoped token, refresh the original token and utilize the newly acquired token to obtain the downscoped token. More information about downscoping tokens can be found [here](https://developer.box.com/guides/authentication/tokens/downscope/). If you want to learn more about available scopes please go [here](https://developer.box.com/guides/api-calls/permissions-and-errors/scopes/#scopes-for-downscoping). For example to get a new token with only `item_preview` scope, restricted to a single file, suitable for the [Content Preview UI Element](https://developer.box.com/en/guides/embed/ui-elements/preview/) you can use the following code. You can also initialize `BoxDeveloperTokenAuth` with the retrieved access token and use it to create a new Client. ``` from box_sdk_gen import BoxDeveloperTokenAuth, AccessToken, BoxClient resource = "https://api.box.com/2.0/files/123456789" downscoped_token: AccessToken = auth.downscope_token( scopes=["item_preview"], resource=resource, ) downscoped_auth = BoxDeveloperTokenAuth(token=downscoped_token.access_token) client = BoxClient(auth=downscoped_auth) ``` # Token storage ## In-memory token storage By default, the SDK stores the access token in volatile memory. When rerunning your application, the access token won't be reused from the previous run; a new token has to be obtained again. To use in-memory token storage, you don't need to do anything more than create an Auth class using AuthConfig, for example, for BoxOAuth: ``` from box_sdk_gen import BoxOAuth, OAuthConfig auth = BoxOAuth( OAuthConfig(client_id="YOUR_CLIENT_ID", client_secret="YOUR_CLIENT_SECRET") ) ``` ## File token storage If you want to keep an up-to-date access token in a file, allowing it to be reused after rerunning your application, you can use the `FileTokenStorage` class. To enable storing the token in a file, you need to pass an object of type `FileTokenStorage` to the AuthConfig class. For example, for BoxOAuth: ``` from box_sdk_gen import BoxOAuth, OAuthConfig, FileTokenStorage auth = BoxOAuth( OAuthConfig( client_id="YOUR_CLIENT_ID", client_secret="YOUR_CLIENT_SECRET", token_storage=FileTokenStorage(), ) ) ``` ## File with in-memory token storage If you want to keep an up-to-date access token in a file and also maintain a valid access token in in-memory cache, allowing you to reuse the token after rerunning your application while maintaining fast access times to the token, you can use the `FileWithInMemoryCacheTokenStorage` class. To enable storing the token in a file, you need to pass an object of type `FileWithInMemoryCacheTokenStorage` to the AuthConfig class. For example, for BoxOAuth: ``` from box_sdk_gen import BoxOAuth, OAuthConfig, FileWithInMemoryCacheTokenStorage auth = BoxOAuth( OAuthConfig( client_id="YOUR_CLIENT_ID", client_secret="YOUR_CLIENT_SECRET", token_storage=FileWithInMemoryCacheTokenStorage(), ) ) ``` ## Custom storage You can also provide a custom token storage class. All you need to do is create a class that inherits from `TokenStorage` and implements all of its abstract methods. Then, pass an instance of your class to the AuthConfig constructor. ``` from typing import Optional from box_sdk_gen import BoxOAuth, OAuthConfig, TokenStorage, AccessToken class MyCustomTokenStorage(TokenStorage): def store(self, token: AccessToken) -> None: # store token in your custom storage pass def get(self) -> Optional[AccessToken]: # retrieve token from your custom storage pass def clear(self) -> None: # clear token from your custom storage pass auth = BoxOAuth( OAuthConfig( client_id="YOUR_CLIENT_ID", client_secret="YOUR_CLIENT_SECRET", token_storage=MyCustomTokenStorage(), ) ) ``` --- ### Authentication **Type:** page | **Section:** Additional Resources Authentication Authentication Authentication methods Developer Token JWT Auth Authenticate Enterprise Authenticate User Client Credentials… # Authentication - [Authentication](#authentication) [Authentication methods](#authentication-methods) - [Developer Token](#developer-token) [JWT Auth](#jwt-auth) - [Authenticate Enterprise](#authenticate-enterprise) - [Authenticate User](#authenticate-user) [Client Credentials Grant](#client-credentials-grant) - [Obtaining Service Account token](#obtaining-service-account-token) - [Obtaining User token](#obtaining-user-token) - [Switching between Service Account and User](#switching-between-service-account-and-user) [OAuth 2.0 Auth](#oauth-20-auth) - [Authentication with OAuth2](#authentication-with-oauth2) - [Injecting existing token into BoxOAuth](#injecting-existing-token-into-boxoauth) [Retrieve current access token](#retrieve-current-access-token) [Refresh access token](#refresh-access-token) [Revoke token](#revoke-token) [Downscope token](#downscope-token) [Token storage](#token-storage) - [In-memory token storage](#in-memory-token-storage) - [Custom storage](#custom-storage) # Authentication methods ## Developer Token The fastest way to get started using the API is with developer token. A developer token is simply a short-lived access token that cannot be refreshed and can only be used with your own account. Therefore, they're only useful for testing an app and aren't suitable for production. You can obtain a developer token from your application's [developer console](https://app.box.com/developers/console) page. To create a `BoxClient` with a developer token, construct an `BoxDeveloperTokenAuth` object with the `token` set to the developer token and construct the client with that. ``` using Box.Sdk.Gen; var auth = new BoxDeveloperTokenAuth(token: "DEVELOPER_TOKEN_GOES_HERE"); var client = new BoxClient(auth: auth)); var me = await client.Users.GetUserMeAsync(); Console.WriteLine($"My user ID is {me.Id}"); ``` ## JWT Auth Before using JWT Auth make sure you set up correctly your Box platform app. The guide with all required steps can be found here: [Setup with JWT](https://developer.box.com/guides/authentication/jwt/jwt-setup/) ### Authenticate Enterprise JWT auth allows your application to authenticate itself with the Box API for a given enterprise. By default, your application has a [Service Account](https://developer.box.com/guides/getting-started/user-types/service-account/) that represents it and can perform API calls. The Service Account is separate from the Box accounts of the application developer and the enterprise admin of any enterprise that has authorized the app — files stored in that account are not accessible in any other account by default, and vice versa. If you generated your public and private keys automatically through the [Box Developer Console](https://app.box.com/developers/console), you can use the JSON file created there to configure your SDK instance and create a client to make calls as the Service Account. Call one of static `JwtConfig` methods: `JwtConfig.FromConfigFile(configFilePath)` and pass JSON file local path or `JwtConfig.FromConfigJsonString(configJsonString)` and pass JSON config file content as string. ``` using Box.Sdk.Gen; var config = JwtConfig.FromConfigFile("/path/to/settings.json"); var jwtAuth = new BoxJwtAuth(config); var client = new BoxClient(jwtAuth); var me = await client.Users.GetUserMeAsync(); Console.WriteLine($"My user ID is {me.Id}"); ``` Otherwise, you'll need to provide the necessary configuration fields directly to the `JwtConfig` constructor: ``` using Box.Sdk.Gen; var jwtConfig = new JwtConfig(clientId: "YOUR_CLIENT_ID", clientSecret: "YOUR_CLIENT_SECRET", jwtKeyId: "YOUR_JWT_KEY_ID", privateKey: "YOUR_PRIVATE_KEY", privateKeyPassphrase: "PASSPHRASE") { EnterpriseId = "YOUR_ENTERPRISE_ID" }; var jwtAuth = new BoxJwtAuth(jwtConfig); var serviceAccountClient = new BoxClient(jwtAuth); ``` ### Authenticate User App auth applications also often have associated [App Users](https://developer.box.com/guides/getting-started/user-types/app-users/), which are created and managed directly by the application — they do not have normal login credentials, and can only be accessed through the Box API by the application that created them. You may authenticate as the Service Account to provision and manage users, or as an individual app user to make calls as that user. See the [API documentation](https://developer.box.com/) for detailed instructions on how to use app auth. Clients for making calls as an App User can be created with the same JSON JWT config file generated through the [Box Developer Console](https://app.box.com/developers/console). Calling `jwtAuth.WithUserSubject("USER_ID")` method will return a new auth object, which is authenticated as the user with provided id, leaving the original object unchanged. ``` using Box.Sdk.Gen; var config = JwtConfig.FromConfigFile("/path/to/settings.json"); var jwtAuth = new BoxJwtAuth(config); var userAuth = jwtAuth.WithUserSubject("USER_ID"); var userClient = new BoxClient(userAuth); ``` Alternatively, clients for making calls as an App User can be created with the same `JwtConfig` constructor as in the above examples, similarly to creating a Service Account client. Simply pass the `userId` instead of `enterpriseId` when constructing the auth config instance: ``` using Box.Sdk.Gen; var jwtConfig = new JwtConfig(clientId: "YOUR_CLIENT_ID", clientSecret: "YOUR_CLIENT_SECRET", jwtKeyId: "YOUR_JWT_KEY_ID", privateKey: "YOUR_PRIVATE_KEY", privateKeyPassphrase: "PASSPHRASE") { UserId = "USER_ID" }; var jwtAuth = new BoxJwtAuth(jwtConfig); var userClient = new BoxClient(jwtAuth); ``` ## Client Credentials Grant Before using Client Credentials Grant Auth make sure you set up correctly your Box platform app. The guide with all required steps can be found here: [Setup with Client Credentials Grant](https://developer.box.com/guides/authentication/client-credentials/client-credentials-setup/) Client Credentials Grant Auth method allows you to obtain an access token by having client credentials and secret with enterprise or user ID, which allows you to work using service or user account. You can use `BoxCcgAuth` to initialize a client object the same way as for other authentication types: ``` using Box.Sdk.Gen; var config = new CcgConfig(clientId: "YOUR_CLIENT_ID", clientSecret: "YOUR_CLIENT_SECRET", userId: "YOUR_USER_ID"); var auth = new BoxCcgAuth(config: config); var client = new BoxClient(auth: auth); var me = await client.Users.GetUserMeAsync(); Console.WriteLine($"My user ID is {me.Id}")); ``` Obtained token is valid for specified amount of time, it will be refreshed automatically by default. ### Obtaining Service Account token The [Service Account](https://developer.box.com/guides/getting-started/user-types/service-account//) is separate from the Box accounts of the application developer and the enterprise admin of any enterprise that has authorized the app — files stored in that account are not accessible in any other account by default, and vice versa. To obtain service account you will have to provide enterprise ID with client id and secret: ``` using Box.Sdk.Gen; var config = new CcgConfig(clientId: "YOUR_CLIENT_ID", clientSecret: "YOUR_CLIENT_SECRET") { EnterpriseId: "YOUR_ENTERPRISE_ID" }; var auth = new BoxCcgAuth(config: config); var client = new BoxClient(auth: auth); var auth = new BoxCcgAuth(config: config); var client = new BoxClient(auth: auth); ``` ### Obtaining User token In order to enable obtaining user token you have to go to your application configuration that can be found [here](https://app.box.com/developers/console). In `Configuration` tab, in section `Advanced Features` select `Generate user access tokens`. Do not forget to re-authorize application if it was already authorized. To obtain user account you will have to provide user ID with client id and secret. ``` using Box.Sdk.Gen; var config = new CcgConfig(clientId: "YOUR_CLIENT_ID", clientSecret: "YOUR_CLIENT_SECRET") { UserId: "YOUR_USER_ID" }; var auth = new BoxCcgAuth(config: config); var client = new BoxClient(auth: auth); ``` ### Switching between Service Account and User In order to switch between being authenticated as Service Account and a User you can call: ``` await auth.WithEnterpriseSubjectAsync(enterpriseId: "YOUR_ENTERPRISE_ID"); ``` to authenticate as enterprise or ``` await auth.WithUserSubjectAsync(userId: "YOUR_USER_ID"); ``` to authenticate as User with provided ID. The new token will be automatically fetched with a next API call. ## OAuth 2.0 Auth ### Authentication with OAuth2 If your application needs to integrate with existing Box users who will provide their login credentials to grant your application access to their account, you will need to go through the standard OAuth2 login flow. A detailed guide for this process is available in the [Authentication with OAuth API documentation](https://developer.box.com/en/guides/authentication/oauth2/). Using an auth code is the most common way of authenticating with the Box API for existing Box users, to integrate with their accounts. Your application must provide a way for the user to login to Box (usually with a browser or web view) in order to obtain an auth code. ``` using Box.Sdk.Gen; var config = new OAuthConfig(clientId: "YOUR_CLIENT_ID", clientSecret: "YOUR_CLIENT_SECRET"); var auth = new BoxOAuth(config: config); // the URL to redirect the user to var authorizeUrl = auth.GetAuthorizeUrl(); ``` After a user logs in and grants your application access to their Box account, they will be redirected to your application's `redirect_uri` which will contain an auth code. This auth code can then be used along with your client ID and client secret to establish an API connection. You need to provide the auth code to the SDK to obtain an access token. Calling `oauth.getTokensAuthorizationCodeGrant('code')` will exchange the auth code for an access token and save it in the `BoxOAuth` token storage. The SDK will automatically refresh the token when needed. All you need to do is create a client object with the `BoxOAuth` object and start making API calls. ``` await auth.RetrieveTokenAsync(); ``` # Refresh access token Access tokens are short-lived and need to be refreshed periodically. The SDK will automatically refresh the token when needed. If you want to manually refresh the token, you can use the following code: ``` await auth.RefreshTokenAsync(); ``` # Revoke token Access tokens for a client can be revoked when needed. This call invalidates old token. For BoxCcgAuth and BoxJwtAuth you can still reuse the `auth` object to retrieve a new token. If you make any new call after revoking the token, a new token will be automatically retrieved. For BoxOAuth it would be necessary to manually go through the authentication process again. For BoxDeveloperTokenAuth, it is necessary to provide a DeveloperTokenConfig during initialization, containing the client ID and client secret. To revoke current client's tokens in the storage use the following code: ``` await auth.RevokeTokenAsync(); ``` # Downscope token You can exchange a client's access token for one with a lower scope, in order to restrict the permissions for a child client or to pass to a less secure location (e.g. a browser-based app). A downscoped token does not include a refresh token. In such a scenario, to obtain a new downscoped token, refresh the original token and utilize the newly acquired token to obtain the downscoped token. More information about downscoping tokens can be found [here](https://developer.box.com/guides/authentication/tokens/downscope/). If you want to learn more about available scopes please go [here](https://developer.box.com/guides/api-calls/permissions-and-errors/scopes/#scopes-for-downscoping). For example to get a new token with only `item_preview` scope, restricted to a single file, suitable for the [Content Preview UI Element](https://developer.box.com/en/guides/embed/ui-elements/preview/) you can use the following code. You can also initialize `BoxDeveloperTokenAuth` with the retrieved access token and use it to create a new Client. ``` using Box.Sdk.Gen; resourcePath = 'https://api.box.com/2.0/files/123456789' AccessToken downscopedToken = await auth.DownscopeTokenAsync( scopes: Array.AsReadOnly(new [] {"item_rename","item_preview"}), resource: resourcePath ); BoxClient downscopedClient = new BoxClient(auth: new BoxDeveloperTokenAuth(token: downscopedToken.AccessTokenField)); ``` # Token storage ## In-memory token storage By default, the SDK stores the access token in volatile memory. When rerunning your application, the access token won't be reused from the previous run; a new token has to be obtained again. To use in-memory token storage, you don't need to do anything more than create an Auth class using AuthConfig, for example, for BoxOAuth: ``` using Box.Sdk.Gen; var config = new OAuthConfig(clientId: "YOUR_CLIENT_ID", clientSecret: "YOUR_CLIENT_SECRET"); var auth = new BoxOAuth(config: config); ``` ## Custom storage You can also provide a custom token storage class. All you need to do is create a class that inherits from `TokenStorage` and implements all of its abstract methods. Then, pass an instance of your class to the AuthConfig constructor. ``` using Box.Sdk.Gen; class MyCustomTokenStorage : ITokenStorage { public Task StoreAsync(AccessToken token) { // store token in your custom storage } public Task<AccessToken?> GetAsync() { // retrieve token from your custom storage } public Task ClearAsync() { // clear token from your custom storage } } var config = new OAuthConfig(clientId: "YOUR_CLIENT_ID", clientSecret: "YOUR_CLIENT_SECRET", tokenStorage: new MyCustomTokenStorage()); var auth = new BoxOAuth(config: config) ``` --- ### AuthorizationManager **Type:** page | **Section:** Additional Resources AuthorizationManager Authorize user Request access token Refresh access token Revoke access token Authorize user Authorize a user by sending… # AuthorizationManager - [Authorize user](#authorize-user) - [Request access token](#request-access-token) - [Refresh access token](#refresh-access-token) - [Revoke access token](#revoke-access-token) ## Authorize user Authorize a user by sending them through the [Box](https://box.com) website and request their permission to act on their behalf. This is the first step when authenticating a user using OAuth 2.0. To request a user's authorization to use the Box APIs on their behalf you will need to send a user to the URL with this format. This operation is performed by calling function `authorizeUser`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-authorize/). *Currently we don't have an example for calling `authorizeUser` in integration tests* ### Arguments queryParams `AuthorizeUserQueryParams` - Query parameters of authorizeUser method optionalsInput `AuthorizeUserOptionalsInput` ### Returns This function returns a value of type `undefined`. Does not return any data, but rather should be used in the browser. ## Request access token Request an Access Token using either a client-side obtained OAuth 2.0 authorization code or a server-side JWT assertion. An Access Token is a string that enables Box to verify that a request belongs to an authorized session. In the normal order of operations you will begin by requesting authentication from the [authorize](#get-authorize) endpoint and Box will send you an authorization code. You will then send this code to this endpoint to exchange it for an Access Token. The returned Access Token can then be used to to make Box API calls. This operation is performed by calling function `requestAccessToken`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-oauth2-token/). *Currently we don't have an example for calling `requestAccessToken` in integration tests* ### Arguments requestBody `PostOAuth2Token` - Request body of requestAccessToken method optionalsInput `RequestAccessTokenOptionalsInput` ### Returns This function returns a value of type `AccessToken`. Returns a new Access Token that can be used to make authenticated API calls by passing along the token in a authorization header as follows `Authorization: Bearer <Token>`. ## Refresh access token Refresh an Access Token using its client ID, secret, and refresh token. This operation is performed by calling function `refreshAccessToken`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-oauth2-token--refresh/). *Currently we don't have an example for calling `refreshAccessToken` in integration tests* ### Arguments requestBodyInput `PostOAuth2TokenRefreshAccessTokenInput` - Request body of refreshAccessToken method optionalsInput `RefreshAccessTokenOptionalsInput` ### Returns This function returns a value of type `AccessToken`. Returns a new Access Token that can be used to make authenticated API calls by passing along the token in a authorization header as follows `Authorization: Bearer <Token>`. ## Revoke access token Revoke an active Access Token, effectively logging a user out that has been previously authenticated. This operation is performed by calling function `revokeAccessToken`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-oauth2-revoke/). *Currently we don't have an example for calling `revokeAccessToken` in integration tests* ### Arguments requestBody `PostOAuth2Revoke` - Request body of revokeAccessToken method optionalsInput `RevokeAccessTokenOptionalsInput` ### Returns This function returns a value of type `undefined`. Returns an empty response when the token was successfully revoked. --- ### AuthorizationManager **Type:** page | **Section:** Additional Resources AuthorizationManager Authorize user Request access token Refresh access token Revoke access token Authorize user Authorize a user by sending… # AuthorizationManager - [Authorize user](#authorize-user) - [Request access token](#request-access-token) - [Refresh access token](#refresh-access-token) - [Revoke access token](#revoke-access-token) ## Authorize user Authorize a user by sending them through the [Box](https://box.com) website and request their permission to act on their behalf. This is the first step when authenticating a user using OAuth 2.0. To request a user's authorization to use the Box APIs on their behalf you will need to send a user to the URL with this format. This operation is performed by calling function `authorize_user`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-authorize/). *Currently we don't have an example for calling `authorize_user` in integration tests* ### Arguments response_type `AuthorizeUserResponseType` - The type of response we'd like to receive. client_id `str` - The Client ID of the application that is requesting to authenticate the user. To get the Client ID for your application, log in to your Box developer console and click the **Edit Application** link for the application you're working with. In the OAuth 2.0 Parameters section of the configuration page, find the item labelled `client_id`. The text of that item is your application's Client ID. redirect_uri `Optional[str]` - The URI to which Box redirects the browser after the user has granted or denied the application permission. This URI match one of the redirect URIs in the configuration of your application. It must be a valid HTTPS URI and it needs to be able to handle the redirection to complete the next step in the OAuth 2.0 flow. Although this parameter is optional, it must be a part of the authorization URL if you configured multiple redirect URIs for the application in the developer console. A missing parameter causes a `redirect_uri_missing` error after the user grants application access. state `Optional[str]` - A custom string of your choice. Box will pass the same string to the redirect URL when authentication is complete. This parameter can be used to identify a user on redirect, as well as protect against hijacked sessions and other exploits. scope `Optional[str]` - A space-separated list of application scopes you'd like to authenticate the user for. This defaults to all the scopes configured for the application in its configuration page. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `None`. Does not return any data, but rather should be used in the browser. ## Request access token Request an Access Token using either a client-side obtained OAuth 2.0 authorization code or a server-side JWT assertion. An Access Token is a string that enables Box to verify that a request belongs to an authorized session. In the normal order of operations you will begin by requesting authentication from the [authorize](#get-authorize) endpoint and Box will send you an authorization code. You will then send this code to this endpoint to exchange it for an Access Token. The returned Access Token can then be used to to make Box API calls. This operation is performed by calling function `request_access_token`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-oauth2-token/). *Currently we don't have an example for calling `request_access_token` in integration tests* ### Arguments grant_type `RequestAccessTokenGrantType` - The type of request being made, either using a client-side obtained authorization code, a refresh token, a JWT assertion, client credentials grant or another access token for the purpose of downscoping a token. client_id `Optional[str]` - The Client ID of the application requesting an access token. Used in combination with `authorization_code`, `client_credentials`, or `urn:ietf:params:oauth:grant-type:jwt-bearer` as the `grant_type`. client_secret `Optional[str]` - The client secret of the application requesting an access token. Used in combination with `authorization_code`, `client_credentials`, or `urn:ietf:params:oauth:grant-type:jwt-bearer` as the `grant_type`. code `Optional[str]` - The client-side authorization code passed to your application by Box in the browser redirect after the user has successfully granted your application permission to make API calls on their behalf. Used in combination with `authorization_code` as the `grant_type`. refresh_token `Optional[str]` - A refresh token used to get a new access token with. Used in combination with `refresh_token` as the `grant_type`. assertion `Optional[str]` - A JWT assertion for which to request a new access token. Used in combination with `urn:ietf:params:oauth:grant-type:jwt-bearer` as the `grant_type`. subject_token `Optional[str]` - The token to exchange for a downscoped token. This can be a regular access token, a JWT assertion, or an app token. Used in combination with `urn:ietf:params:oauth:grant-type:token-exchange` as the `grant_type`. subject_token_type `Optional[RequestAccessTokenSubjectTokenType]` - The type of `subject_token` passed in. Used in combination with `urn:ietf:params:oauth:grant-type:token-exchange` as the `grant_type`. actor_token `Optional[str]` - The token used to create an annotator token. This is a JWT assertion. Used in combination with `urn:ietf:params:oauth:grant-type:token-exchange` as the `grant_type`. actor_token_type `Optional[RequestAccessTokenActorTokenType]` - The type of `actor_token` passed in. Used in combination with `urn:ietf:params:oauth:grant-type:token-exchange` as the `grant_type`. scope `Optional[str]` - The space-delimited list of scopes that you want apply to the new access token. The `subject_token` will need to have all of these scopes or the call will error with **401 Unauthorized**.. resource `Optional[str]` - Full URL for the file that the token should be generated for. box_subject_type `Optional[RequestAccessTokenBoxSubjectType]` - Used in combination with `client_credentials` as the `grant_type`. box_subject_id `Optional[str]` - Used in combination with `client_credentials` as the `grant_type`. Value is determined by `box_subject_type`. If `user` use user ID and if `enterprise` use enterprise ID. box_shared_link `Optional[str]` - Full URL of the shared link on the file or folder that the token should be generated for. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `AccessToken`. Returns a new Access Token that can be used to make authenticated API calls by passing along the token in a authorization header as follows `Authorization: Bearer <Token>`. ## Refresh access token Refresh an Access Token using its client ID, secret, and refresh token. This operation is performed by calling function `refresh_access_token`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-oauth2-token--refresh/). *Currently we don't have an example for calling `refresh_access_token` in integration tests* ### Arguments grant_type `RefreshAccessTokenGrantType` - The type of request being made, in this case a refresh request. client_id `str` - The client ID of the application requesting to refresh the token. client_secret `str` - The client secret of the application requesting to refresh the token. refresh_token `str` - The refresh token to refresh. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `AccessToken`. Returns a new Access Token that can be used to make authenticated API calls by passing along the token in a authorization header as follows `Authorization: Bearer <Token>`. ## Revoke access token Revoke an active Access Token, effectively logging a user out that has been previously authenticated. This operation is performed by calling function `revoke_access_token`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-oauth2-revoke/). *Currently we don't have an example for calling `revoke_access_token` in integration tests* ### Arguments client_id `Optional[str]` - The Client ID of the application requesting to revoke the access token. client_secret `Optional[str]` - The client secret of the application requesting to revoke an access token. token `Optional[str]` - The access token to revoke. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `None`. Returns an empty response when the token was successfully revoked. --- ### AvatarsManager **Type:** page | **Section:** Additional Resources AvatarsManager Get user avatar Add or update user avatar Delete user avatar Get user avatar Retrieves an image of a the user's avatar. This… # AvatarsManager - [Get user avatar](#get-user-avatar) - [Add or update user avatar](#add-or-update-user-avatar) - [Delete user avatar](#delete-user-avatar) ## Get user avatar Retrieves an image of a the user's avatar. This operation is performed by calling function `getUserAvatar`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-users-id-avatar/). ``` await client.avatars.getUserAvatar(user.id); ``` ### Arguments userId `string` - The ID of the user. Example: "12345" optionalsInput `GetUserAvatarOptionalsInput` ### Returns This function returns a value of type `ByteStream`. When an avatar can be found for the user the image data will be returned in the body of the response. ## Add or update user avatar Adds or updates a user avatar. This operation is performed by calling function `createUserAvatar`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-users-id-avatar/). ``` await client.avatars.createUserAvatar(user.id, { pic: decodeBase64ByteStream( 'iVBORw0KGgoAAAANSUhEUgAAAQAAAAEAAQMAAABmvDolAAAAA1BMVEW10NBjBBbqAAAAH0lEQVRoge3BAQ0AAADCoPdPbQ43oAAAAAAAAAAAvg0hAAABmmDh1QAAAABJRU5ErkJggg==', ), picContentType: 'image/png', picFileName: 'avatar.png', } satisfies CreateUserAvatarRequestBody); ``` ### Arguments userId `string` - The ID of the user. Example: "12345" requestBody `CreateUserAvatarRequestBody` - Request body of createUserAvatar method optionalsInput `CreateUserAvatarOptionalsInput` ### Returns This function returns a value of type `UserAvatar`. `ok`: Returns the `pic_urls` object with URLs to existing user avatars that were updated.`created`: Returns the `pic_urls` object with URLS to user avatars uploaded to Box with the request. ## Delete user avatar Removes an existing user avatar. You cannot reverse this operation. This operation is performed by calling function `deleteUserAvatar`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-users-id-avatar/). ``` await client.avatars.deleteUserAvatar(user.id); ``` ### Arguments userId `string` - The ID of the user. Example: "12345" optionalsInput `DeleteUserAvatarOptionalsInput` ### Returns This function returns a value of type `undefined`. `no_content`: Removes the avatar and returns an empty response. --- ### AvatarsManager **Type:** page | **Section:** Additional Resources AvatarsManager Get user avatar Add or update user avatar Delete user avatar Get user avatar Retrieves an image of a the user's avatar. This… # AvatarsManager - [Get user avatar](#get-user-avatar) - [Add or update user avatar](#add-or-update-user-avatar) - [Delete user avatar](#delete-user-avatar) ## Get user avatar Retrieves an image of a the user's avatar. This operation is performed by calling function `get_user_avatar`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-users-id-avatar/). ``` client.avatars.get_user_avatar(user.id) ``` ### Arguments user_id `str` - The ID of the user. Example: "12345" extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `ByteStream`. When an avatar can be found for the user the image data will be returned in the body of the response. ## Add or update user avatar Adds or updates a user avatar. This operation is performed by calling function `create_user_avatar`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-users-id-avatar/). ``` client.avatars.create_user_avatar( user.id, decode_base_64_byte_stream( "iVBORw0KGgoAAAANSUhEUgAAAQAAAAEAAQMAAABmvDolAAAAA1BMVEW10NBjBBbqAAAAH0lEQVRoge3BAQ0AAADCoPdPbQ43oAAAAAAAAAAAvg0hAAABmmDh1QAAAABJRU5ErkJggg==" ), pic_file_name="avatar.png", pic_content_type="image/png", ) ``` ### Arguments user_id `str` - The ID of the user. Example: "12345" pic `ByteStream` - The image file to be uploaded to Box. Accepted file extensions are `.jpg` or `.png`. The maximum file size is 1MB. pic_file_name `Optional[str]` pic_content_type `Optional[str]` extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `UserAvatar`. `ok`: Returns the `pic_urls` object with URLs to existing user avatars that were updated.`created`: Returns the `pic_urls` object with URLS to user avatars uploaded to Box with the request. ## Delete user avatar Removes an existing user avatar. You cannot reverse this operation. This operation is performed by calling function `delete_user_avatar`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-users-id-avatar/). ``` client.avatars.delete_user_avatar(user.id) ``` ### Arguments user_id `str` - The ID of the user. Example: "12345" extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `None`. `no_content`: Removes the avatar and returns an empty response. --- ### Box cURL samples **Type:** page | **Section:** Additional Resources Box cURL samples Authorize a user Authorize a user by sending them through the Box website and request their permission to act on their… # Box cURL samples ## Authorize a user Authorize a user by sending them through the [Box](https://box.com) website and request their permission to act on their behalf. This is the first step when authenticating a user using OAuth 2.0. To request a user's authorization to use the Box APIs on their behalf you will need to send a user to the URL with this format. ``` curl -i -X GET "https://account.box.com/api/oauth2/authorize?response_type=code&client_id=ly1nj6n11vionaie65emwzk575hnnmrk&redirect_uri=http://example.com/auth/callback" ``` ## Request an access token Request an Access Token using either a client-side obtained OAuth2 authorization code or a server-side JWT assertion. An Access Token is a string that enables Box to verify that a request belongs to an authorized session. In the normal order of operations you will begin by requesting authentication from the [authorize](#get-authorize) endpoint and Box will send you an authorization code. You will then send this code to this endpoint to exchange it for an Access Token. The returned Access Token can then be used to to make Box API calls. ``` curl -i -X POST "https://api.box.com/oauth2/token" \ -H "content-type: application/x-www-form-urlencoded" \ -d "client_id=[CLIENT_ID]" \ -d "client_secret=[CLIENT_SECRET]" \ -d "code=[CODE]" \ -d "grant_type=authorization_code" ``` ## Refresh an access token ``` curl -i -X POST "https://api.box.com/oauth2/token" \ -H "content-type: application/x-www-form-urlencoded" \ -d "client_id=[CLIENT_ID]" \ -d "client_secret=[CLIENT_SECRET]" \ -d "refresh_token=[REFRESH_TOKEN]" \ -d "grant_type=refresh_token" ``` ## Downscope a token ``` curl -i -X POST "https://api.box.com/oauth2/token" \ -H "content-type: application/x-www-form-urlencoded" \ -d "subject_token=[ACCESS_TOKEN]" \ -d "subject_token_type=urn:ietf:params:oauth:token-type:access_token" \ -d "scope=item_upload item_preview base_explorer" \ -d "resource=https://api.box.com/2.0/folders/123456" \ -d "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" ``` ## Revoke an access token Revoke an active Access Token, effectively logging a user out that has been previously authenticated. ``` curl -i -X POST "https://api.box.com/oauth2/revoke" \ -H "content-type: application/x-www-form-urlencoded" \ -d "client_id=[CLIENT_ID]" \ -d "client_secret=[CLIENT_SECRET]" \ -d "token=[ACCESS_TOKEN]" ``` ## Authentication with Client Credentials Creates a token using Client Credentials Grant, which allows you to log in as a Service Account. ``` curl -i -X POST "https://api.box.com/oauth2/token" \ -H "content-type: application/x-www-form-urlencoded" \ -d "client_id=[CLIENT_ID]" \ -d "client_secret=[CLIENT_SECRET]" \ -d "grant_type=client_credentials" \ -d "box_subject_type=enterprise" \ -d "box_subject_id=[ENTERPRISE_ID]" ``` ## Authentication with CCG as an admin or managed user Creates a token using Client Credentials Grant, which allows you to log in as an admin or a managed user. ``` curl -i -X POST "https://api.box.com/oauth2/token" \ -H "content-type: application/x-www-form-urlencoded" \ -d "client_id=[CLIENT_ID]" \ -d "client_secret=[CLIENT_SECRET]" \ -d "grant_type=client_credentials" \ -d "box_subject_type=user" \ -d "box_subject_id=[USER_ID]" ``` ## Authentication with CCG as app user Creates a token using Client Credentials Grant, which allows you to log in as any app user. ``` curl -i -X POST "https://api.box.com/oauth2/token" \ -H "content-type: application/x-www-form-urlencoded" \ -d "client_id=[CLIENT_ID]" \ -d "client_secret=[CLIENT_SECRET]" \ -d "grant_type=client_credentials" \ -d "box_subject_type=user" \ -d "box_subject_id=[APPUSER_ID]" ``` ## Send request to AI ``` curl -i -L POST "https://api.box.com/2.0/ai/ask" \ -H "content-type: application/json" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -d '{ "mode": "single_item_qa", "prompt": "What is the value provided by public APIs based on this document?", "items": [ { "type": "file", "id": "9842787262" } ], "dialogue_history": [ { "prompt": "Make my email about public APIs sound more professional", "answer": "Here is the first draft of your professional email about public APIs", "created_at": "2013-12-12T10:53:43-08:00" } ], "include_citations": true, "ai_agent": { "type": "ai_agent_ask", "long_text": { "model": "azure__openai__gpt_4o_mini", "prompt_template": "It is `{current_date}`, and I have $8000 and want to spend a week in the Azores. What should I see?", }, "basic_text": { "model": "azure__openai__gpt_4o_mini", } } }' ``` ## Send request to AI (extended) ``` curl -i -L POST "https://api.box.com/2.0/ai/ask" \ -H "content-type: application/json" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -d '{ "mode": "single_item_qa", "prompt": "What is the value provided by public APIs based on this document?", "items": [ { "type": "file", "id": "9842787262" } ], "dialogue_history": [ { "prompt": "Make my email about public APIs sound more professional", "answer": "Here is the first draft of your professional email about public APIs", "created_at": "2013-12-12T10:53:43-08:00" } ], "include_citations": true, "ai_agent": { "type": "ai_agent_ask", "long_text": { "model": "azure__openai__gpt_4o_mini", "system_message": "You are a helpful travel assistant specialized in budget travel", "prompt_template": "It is `{current_date}`, and I have $8000 and want to spend a week in the Azores. What should I see?", "num_tokens_for_completion": 8400, "llm_endpoint_params": { "type": "openai_params", "temperature": 0.0, "top_p": 1.0, "frequency_penalty": 1.5, "presence_penalty": 1.5, "stop": "<|im_end|>" }, "embeddings": { "model": "openai__text_embedding_ada_002", "strategy": { "id": "basic", "num_tokens_per_chunk": 8400 } } }, "basic_text": { "model": "azure__openai__gpt_4o_mini", "system_message": "You are a helpful travel assistant specialized in budget travel", "prompt_template": "It is `{current_date}`, and I have $8000 and want to spend a week in the Azores. What should I see?", "num_tokens_for_completion": 8400, "llm_endpoint_params": { "type": "openai_params", "temperature": 0.0, "top_p": 1.0, "frequency_penalty": 1.5, "presence_penalty": 1.5, "stop": "<|im_end|>" } }, "long_text_multi": { "model": "azure__openai__gpt_4o_mini", "system_message": "You are a helpful travel assistant specialized in budget travel", "prompt_template": "It is `{current_date}`, and I have $8000 and want to spend a week in the Azores. What should I see?", "num_tokens_for_completion": 8400, "llm_endpoint_params": { "type": "openai_params", "temperature": 0.0, "top_p": 1.0, "frequency_penalty": 1.5, "presence_penalty": 1.5, "stop": "<|im_end|>" }, "embeddings": { "model": "openai__text_embedding_ada_002", "strategy": { "id": "basic", "num_tokens_per_chunk": 8400 } } }, "basic_text_multi": { "model": "azure__openai__gpt_4o_mini", "system_message": "You are a helpful travel assistant specialized in budget travel", "prompt_template": "It is `{current_date}`, and I have $8000 and want to spend a week in the Azores. What should I see?", "num_tokens_for_completion": 8400, "llm_endpoint_params": { "type": "openai_params", "temperature": 0.0, "top_p": 1.0, "frequency_penalty": 1.5, "presence_penalty": 1.5, "stop": "<|im_end|>" } } }' ``` ## Send text generation request to AI ``` curl -i -L POST "https://api.box.com/2.0/ai/text_gen" \ -H "content-type: application/json" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -d '{ "prompt": "Write a social media post about protein powder.", "items": [ { "id": "12345678", "type": "file", "content": "More information about protein powders" }, ], "dialogue_history": [ { "prompt": "Can you add some more information?", "answer": "Public API schemas provide necessary information to integrate with APIs...", "created_at": "2013-12-12T11:20:43-08:00" } ], "ai_agent": { "type": "ai_agent_text_gen", "basic_gen": { "model": "azure__openai__gpt_4o_mini" } } }' ``` ## Send text generation request to AI (extended) ``` curl -i -L POST "https://api.box.com/2.0/ai/text_gen" \ -H "content-type: application/json" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -d '{ "prompt": "Write a social media post about protein powder.", "items": [ { "id": "12345678", "type": "file", "content": "More information about protein powders" }, ], "dialogue_history": [ { "prompt": "Make my email about public APIs sound more professional", "answer": "Here is the first draft of your professional email about public APIs", "created_at": "2013-12-12T10:53:43-08:00" }, { "prompt": "Can you add some more information?", "answer": "Public API schemas provide necessary information to integrate with APIs...", "created_at": "2013-12-12T11:20:43-08:00" } ], "ai_agent": { "type": "ai_agent_text_gen", "basic_gen": { "model": "azure__openai__gpt_4o_mini", "system_message": "You are a helpful travel assistant specialized in budget travel", "prompt_template": "It is `{current_date}`, and I have $8000 and want to spend a week in Azores. What should I see?", "num_tokens_for_completion": 8400, "llm_endpoint_params": { "type": "openai_params", "temperature": 2.0, "top_p": 1.0, "frequency_penalty": 1.5, "presence_penalty": 1.5, "stop": "<|im_end|>" }, "embeddings": { "model": " openai__text_embedding_ada_002", "strategy": { "id": "basic", "num_tokens_per_chunk": 64 } }, "content_template": "---{content}---" } } }' ``` ## Get default agent config ``` curl -L GET "https://api.box.com/2.0/ai_agent_default?mode=text_gen" \ -H 'Authorization: Bearer <ACCESS_TOKEN>' ``` ## Create agents Creates custom AI agents. ``` curl -L POST "https://api.box.com/2.0/ai-agents" \ -H 'Authorization: Bearer <ACCESS_TOKEN>' -d '{ type: type: string description: The type of agent used to handle queries. enum: - ai_agent example: ai_agent name: type: string description: The name of the AI Agent. example: 'My AI Agent' access_state: $ref: ../schemas/ai_agent_access_state.yml icon_reference: type: string minLength: 1 description: |- The icon reference of the AI Agent. It should have format of the URL https://cdn01.boxcdn.net/app-assets/aistudio/avatars/<file_name> where possible values of file_name are: `logo_boxAi.png`,`logo_stamp.png`,`logo_legal.png`,`logo_finance.png`,`logo_config.png`,`logo_handshake.png`,`logo_analytics.png`,`logo_classification.png example: 'https://cdn01.boxcdn.net/app-assets/aistudio/avatars/logo_analytics.svg' allowed_entities: type: array }, - d '{ items: $ref: '#/components/schemas/AiAgentAllowedEntity' description: List of allowed users or groups. ask: $ref: '#/components/schemas/AiStudioAgentAsk' text_gen: $ref: '#/components/schemas/AiStudioAgentTextGen' extract: $ref: '#/components/schemas/AiStudioAgentExtract' } ``` ## Delete AI agent ``` curl -L DELETE "https://api.box.com/2.0/ai_agents/12345" \ -H 'Authorization: Bearer <ACCESS_TOKEN>' ``` ## Get AI agent by ID ``` curl -i -X GET "https://api.box.com/2.0/ai_agents/1234567890" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Get AI agents ``` curl -i -X GET "https://api.box.com/2.0/ai_agents" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Update AI agents ``` curl -i -X PUT "https://api.box.com/2.0/ai_agents/1234567890" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Extract structured metadata ``` curl -i -L 'https://api.box.com/2.0/ai/extract_structured' \ -H 'content-type: application/json' \ -H 'authorization: Bearer <ACCESS_TOKEN>' \ -d '{ "items": [ { "id": "12345678", "type": "file", "content": "This is file content." } ], "metadata_template": { "template_key": "", "type": "metadata_template", "scope": "" }, "fields": [ { "key": "name", "description": "The name of the person.", "displayName": "Name", "prompt": "The name is the first and last name from the email address.", "type": "string", "options": [ { "key": "First Name" }, { "key": "Last Name" } ] } ], "ai_agent": { "type": "ai_agent_extract_structured", "long_text": { "model": "azure__openai__gpt_4o_mini" }, "basic_text": { "model": "azure__openai__gpt_4o_mini" } } }' ``` ## Extract structured metadata (extended) ``` curl -i -L 'https://api.box.com/2.0/ai/extract_structured' \ -H 'content-type: application/json' \ -H 'authorization: Bearer <ACCESS_TOKEN>' \ -d '{ "items": [ { "id": "12345678", "type": "file", "content": "This is file content." } ], "metadata_template": { "template_key": "", "type": "metadata_template", "scope": "" }, "fields": [ { "key": "name", "description": "The name of the person.", "displayName": "Name", "prompt": "The name is the first and last name from the email address.", "type": "string", "options": [ { "key": "First Name" }, { "key": "Last Name" } ] } ], "ai_agent": { "type": "ai_agent_extract_structured", "long_text": { "model": "azure__openai__gpt_4o_mini", "system_message": "You are a helpful travel assistant specialized in budget travel", "prompt_template": "It is `{current_date}`, and I have $8000 and want to spend a week in the Azores. What should I see?", "num_tokens_for_completion": 8400, "llm_endpoint_params": { "type": "openai_params", "temperature": 0, "top_p": 1, "frequency_penalty": 1.5, "presence_penalty": 1.5, "stop": "<|im_end|>" }, "embeddings": { "model": "openai__text_embedding_ada_002", "strategy": { "id": "basic", "num_tokens_per_chunk": 64 } } }, "basic_text": { "model": "azure__openai__gpt_4o_mini", "system_message": "You are a helpful travel assistant specialized in budget travel", "prompt_template": "It is `{current_date}`, and I have $8000 and want to spend a week in the Azores. What should I see?", "num_tokens_for_completion": 8400, "llm_endpoint_params": { "type": "openai_params", "temperature": 0, "top_p": 1, "frequency_penalty": 1.5, "presence_penalty": 1.5, "stop": "<|im_end|>" } } } }' ``` ## Extract metadata ``` curl -i -L 'https://api.box.com/2.0/ai/extract' \ -H 'content-type: application/json' \ -H 'authorization: Bearer <ACCESS_TOKEN>' \ -d '{ "prompt": "Extract data related to contract conditions", "items": [ { "type": "file", "id": "1497741268097" } ], "ai_agent": { "type": "ai_agent_extract", "long_text": { "model": "azure__openai__gpt_4o_mini", "prompt_template": "It is `{current_date}`, and I have $8000 and want to spend a week in the Azores. What should I see?", }, "basic_text": { "model": "azure__openai__gpt_4o_mini", } } }' ``` ## Extract metadata (extended) ``` curl -i -L 'https://api.box.com/2.0/ai/extract' \ -H 'content-type: application/json' \ -H 'authorization: Bearer <ACCESS_TOKEN>' \ -d '{ "prompt": "Extract data related to contract conditions", "items": [ { "type": "file", "id": "1497741268097" } ], "ai_agent": { "type": "ai_agent_extract", "long_text": { "model": "azure__openai__gpt_4o_mini", "system_message": "You are a helpful travel assistant specialized in budget travel", "prompt_template": "It is `{current_date}`, and I have $8000 and want to spend a week in the Azores. What should I see?", "num_tokens_for_completion": 8400, "llm_endpoint_params": { "type": "openai_params", "temperature": 0, "top_p": 1, "frequency_penalty": 1.5, "presence_penalty": 1.5, "stop": "<|im_end|>" }, "embeddings": { "model": "openai__text_embedding_ada_002", "strategy": { "id": "basic", "num_tokens_per_chunk": 64 } } }, "basic_text": { "model": "azure__openai__gpt_4o_mini", "system_message": "You are a helpful travel assistant specialized in budget travel", "prompt_template": "It is `{current_date}`, and I have $8000 and want to spend a week in the Azores. What should I see?", "num_tokens_for_completion": 8400, "llm_endpoint_params": { "type": "openai_params", "temperature": 0, "top_p": 1, "frequency_penalty": 1.5, "presence_penalty": 1.5, "stop": "<|im_end|>" } } } }' ``` ## Add a Doc Gen template ``` curl -L 'https://api.box.com/2.0/docgen_templates' \ -H 'box-version: 2025.0' \ -H 'Authorization: Bearer <ACCESS_TOKEN>' \ -H 'Content-Type: application/json' \ -D '{ "file": { "id": "12345678", "type": "file" } }' ``` ## Delete association between Doc Gen template and file ``` curl -L -X DELETE 'https://api.box.com/2.0/docgen_templates/12345678' \ -H 'box-version: 2025.0' \ -H 'Authorization: Bearer <ACCESS_TOKEN>' ``` ## Get all Doc Gen templates ``` curl -L 'https://api.box.com/2.0/docgen_templates' \ -H 'box-version: 2025.0' \ -H 'Authorization: Bearer <ACCESS_TOKEN>' ``` ## Get Doc Gen template by ID ``` curl -L 'https://api.box.com/2.0/docgen_templates/12345678' \ -H 'box-version: 2025.0' \ -H 'Authorization: Bearer <ACCESS_TOKEN>' ``` ## Get Doc Gen jobs for a template ``` curl -L 'https://api.box.com/2.0/docgen_template_jobs/12345678' \ -H 'box-version: 2025.0' \ -H 'Authorization: Bearer <ACCESS_TOKEN>' ``` ## Get Doc Gen template tags for template ``` curl -L 'https://api.box.com/2.0/docgen_templates/12345678/tags' \ -H 'box-version: 2025.0' \ -H 'Authorization: Bearer <ACCESS_TOKEN>' ``` ## Generate a document with Doc Gen ``` curl -L 'https://api.box.com/2.0/docgen_batches' \ -H 'box-version: 2025.0' \ -H 'Authorization: Bearer <ACCESS_TOKEN>' \ -D '{ "file": { "id": "12345678", "type": "file" }, "input_source": "api", "destination_folder": { "id": "12345678", "type": "folder" }, "output_type": "docx", "document_generation_data": [ { "generated_file_name": "Image test", "user_input": { "order": { "id": "12305", "date": "18-08-2023", "country": "US", "expiryDate": "18-08-2024", "currency": "$", "amount": 5060.5, "taxRate": 10, "requester": "John", "approver": "Smith", "department": "Procurement", "paymentTerms": "30 days", "deliveryTerms": "30 days", "deliveryDate": "18-09-2023", "vendor": { "company": "Example company", "address": { "street": "Example street", "city": "Example city", "zip": "EX-456" } }, "products": [ { "id": 1, "name": "A4 Papers", "type": "non-fragile", "quantity": 100, "price": 29, "amount": 2900 }, { "id": 2, "name": "Ink Cartridge", "type": "non-fragile", "quantity": 40, "price": 39, "amount": 1560 }, { "id": 3, "name": "Adhesive tape", "type": "non-fragile", "quantity": 20, "price": 30, "amount": 600.5 } ] } } } ]` ``` ## Get all Doc Gen jobs ``` curl -i -X GET "https://api.box.com/2.0/docgen_jobs" \ -H 'box-version: 2025.0' \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Get Doc Gen job by ID ``` curl -i -X GET "https://api.box.com/2.0/docgen_jobs/12345" \ -H 'box-version: 2025.0' \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Get Doc Gen job for a specific batch ``` curl -i -X GET "https://api.box.com/2.0/docgen_batch_jobs/12345" \ -H 'box-version: 2025.0' \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Get a file Retrieves the details about a file. ``` curl -i -X GET "https://api.box.com/2.0/files/12345" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Restore file Restores an file that has been moved to the trash. ``` curl -i -X POST "https://api.box.com/2.0/files/12345" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Update a file Updates a file. This can be used to rename or move a file, create a shared link, or lock a file. ``` curl -i -X PUT "https://api.box.com/2.0/files/12345" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -H "content-type: application/json" \ -d '{ "name": "New name" }' ``` ## Delete a file Deletes a file, either permanently or by moving it to the trash. The the enterprise settings determine whether the item will be permanently deleted from Box or moved to the trash. ``` curl -i -X DELETE "https://api.box.com/2.0/files/12345" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Download a file Returns the contents of a file in binary format. ``` curl -i -L -X GET "https://api.box.com/2.0/files/12345/content" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ ``` ## Download a file version ``` curl -i -L -X GET "https://api.box.com/2.0/files/12345/content?version=4" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ ``` ## Get download URL ``` curl -i -X GET "https://api.box.com/2.0/files/12345/content?version=4" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Download a shared link Returns the contents of a file in binary format. ``` curl -i -L -X GET "https://api.box.com/2.0/files/12345/content" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -H "boxapi: shared_link=https://cloud.box.com/shared/static/gjasdasjhasd&shared_link_password=letmein" \ ``` ## Upload a file version Update a file's content. For file sizes over 50MB we recommend using the Chunk Upload APIs. ``` curl -i -X POST "https://upload.box.com/api/2.0/files/12345/content" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -H "content-type: multipart/form-data" \ -F attributes='{"name":"Contract.pdf", "parent":{"id":"11446498"}}' \ -F file=@<FILE_NAME> ``` ## Preflight check Performs a check to verify that a file will be accepted by Box before you upload the entire file. ``` curl -i -X OPTIONS "https://api.box.com/2.0/files/content" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -H "content-type: application/json" \ -d '{"name":"Contract.pdf", "parent":{"id":"11446498"}}' ``` ``` curl -i -X OPTIONS "https://api.box.com/2.0/files/12345/content" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -H "content-type: application/json" \ -d '{"name":"Contract.pdf", "parent":{"id":"11446498"}}' ``` ## Upload a file Uploads a small file to Box. For file sizes over 50MB we recommend using the Chunk Upload APIs. ``` curl -i -X POST "https://upload.box.com/api/2.0/files/content" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -H "content-type: multipart/form-data" \ -F attributes='{"name":"Contract.pdf", "parent":{"id":"11446498"}}' \ -F file=@<FILE_NAME> ``` ## Create upload session Creates an upload session for a new file. ``` curl -i -X POST "https://upload.box.com/api/2.0/files/upload_sessions" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -H "content-type: application/json" \ -d '{ "folder_id": "0", "file_size": 104857600, "file_name": "Contract.pdf" }' ``` ## Create upload session for existing file Creates an upload session for an existing file. ``` curl -i -X POST "https://upload.box.com/api/2.0/files/12345/upload_sessions" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -H "content-type: application/json" \ -d '{ "file_size": 104857600 }' ``` ## Get upload session Return information about an upload session. ``` curl -i -X GET "https://upload.box.com/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Upload a part Updates a chunk of an upload session for a file. ``` curl -i -X PUT "https://upload.box.com/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -H "digest: sha=fpRyg5eVQletdZqEKaFlqwBXJzM=" \ -H "content-range: bytes 8388608-16777215/445856194" \ -H "content-type: application/octet-stream" \ --data-binary @<FILE_NAME> ``` ## Abort upload session Abort an upload session and discard all data uploaded. This cannot be reversed. ``` curl -i -X DELETE "https://upload.box.com/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## List parts Return a list of the chunks uploaded to the upload session so far. ``` curl -i -X GET "https://upload.box.com/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD/parts" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Commit upload session Close an upload session and create a file from the uploaded chunks. ``` curl -i -X POST "https://upload.box.com/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD/commit" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -H "digest: sha=fpRyg5eVQletdZqEKaFlqwBXJzM=" \ -H "content-type: application/json" \ -d '{ "parts": [ { "part_id": "BFDF5379", "offset": 0, "size": 8388608, "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc" }, { "part_id": "E8A3ED8E", "offset": 8388608, "size": 1611392, "sha1": "234b65934ed521fcfe3424b7d814ab8ded5185dc" } ], "attributes": { "content_modified_at": "2017-04-08T00:58:08Z" } }' ``` ## Copy a file Creates a copy of a file. ``` curl -i -X POST "https://api.box.com/2.0/files/12345/copy" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -H "content-type: application/json" \ -d '{ "parent": { "id": "123" } }' ``` ## Get a file thumbnail Retrieves a thumbnail, or smaller image representation, of a file. Sizes of `32x32`,`64x64`, `128x128`, and `256x256` can be returned in the `.png` format and sizes of `32x32`, `94x94`, `160x160`, and `320x320` can be returned in the `.jpg` format. Thumbnails can be generated for the image and video file formats listed [found on our community site]([http://community.box.com/t5/Managing-](http://community.box.com/t5/Managing-) Your-Content/What-file-types-are-supported-by-Box-s-Content-Preview/ ta-p/327). ``` curl -i -X GET "https://api.box.com/2.0/files/12345/thumbnail.png" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Get file collaborations Retrieves a list of collaborations for a file. This returns all the users that have access to the file. ``` curl -i -X GET "https://api.box.com/2.0/files/12345/collaborations" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## List a file's comments Retrieves a list of comments for a file. ``` curl -i -X GET "https://api.box.com/2.0/files/12345/comments" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Get file tasks Retrieves a list of all the tasks for a file. This endpoint does not support paging. ``` curl -i -X GET "https://api.box.com/2.0/files/12345/tasks" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Get trashed file Retrieves a file that has been moved to the trash. ``` curl -i -X GET "https://api.box.com/2.0/files/12345/trash" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Permanently delete file Permanently deletes a file that is in the trash. This action cannot be undone. ``` curl -i -X DELETE "https://api.box.com/2.0/files/12345/trash" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## List all file versions Retrieve information on all version of a file. This endpoint can be used to retrieve information about older versions of a file. Versions are only tracked for Box users with premium accounts. ``` curl -i -X GET "https://api.box.com/2.0/files/12345/versions" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Get a file version Retrieve a specific older version of a file. Versions are only tracked for Box users with premium accounts. ``` curl -i -X GET "https://api.box.com/2.0/files/12345/versions/456456" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Delete file version Move a file version to the trash. Versions are only tracked for Box users with premium accounts. ``` curl -i -X DELETE "https://api.box.com/2.0/files/12345/versions/456456" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Promote file version Promote a specific version of a file. If previous versions exist, this method can be used to promote one of the older versions to the top of the version history. This actually creates a new copy of the old version and puts it at the top of the versions history. The file will have the exact same contents as the older version, with the the same SHA1/etag, and the same name as the original. Other properties such as comments do not get updated to their former values. Don't use this endpoint to restore Box Notes, as it works with file formats such as PDF, DOC, PPTX or similar. ``` curl -i -X POST "https://api.box.com/2.0/files/12345/versions/current" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -H "content-type: application/json" \ -d '{ "type": "file_version", "id": "456456" }' ``` ## Restore file version Restores a specific version of a file after it was deleted. Don't use this endpoint to restore Box Notes, as it works with file formats such as PDF, DOC, PPTX or similar. ``` curl -i -X POST "https://api.box.com/2.0/files/12345/versions/456456" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -H "content-type: application/json" \ -d '{ "trashed_at": null }' ``` ## List file's metadata Retrieves all metadata for a given file. ``` curl -i -X GET "https://api.box.com/2.0/files/12345/metadata" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Get specific file metadata Retrieve a specific metadata template instance for a file ``` curl -i -X GET "https://api.box.com/2.0/files/12345/metadata/enterprise_27335/blueprintTemplate" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Create metadata on file Creates a piece of metadata on a file based on the specified template. Only values that are present in the metadata template will be accepted. ``` curl -i -X POST "https://api.box.com/2.0/files/12345/metadata/enterprise_27335/blueprintTemplate" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -H "content-type: application/json" \ -d '{ "audience": "internal", "documentType": "Q1 plans", "competitiveDocument": "no", "status": "active", "author": "Jones", "currentState": "proposal" }' ``` ## Update file metadata Updates a piece of metadata on a file. The metadata instance can only be updated if the instance already exists. When editing metadata, only values that adhere to the metadata template schema will be accepted. The update is applied atomically. If any errors occur during the application of the operations, the metadata instance remains unchanged. ``` curl -i -X PUT "https://api.box.com/2.0/files/12345/metadata/enterprise_27335/blueprintTemplate" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -H "content-type: application/json-patch+json" \ -d '[ { "op": "test", "path": "/competitiveDocument", "value": "no" }, { "op": "remove", "path": "/competitiveDocument" }, { "op": "test", "path": "/status", "value": "active" }, { "op": "replace", "path": "/status", "value": "inactive" }, { "op": "test", "path": "/author", "value": "Jones" }, { "op": "copy", "from": "/author", "path": "/editor" }, { "op": "test", "path": "/currentState", "value": "proposal" }, { "op": "move", "from": "/currentState", "path": "/previousState" }, { "op": "add", "path": "/currentState", "value": "reviewed" } ]' ``` ## Delete file metadata Deletes a piece of file metadata. ``` curl -i -X DELETE "https://api.box.com/2.0/files/12345/metadata/enterprise_27335/blueprintTemplate" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Get file watermark Retrieve the watermark for a file. ``` curl -i -X GET "https://api.box.com/2.0/files/12345/watermark" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Apply watermark to file Applies or update a watermark on a file. ``` curl -i -X PUT "https://api.box.com/2.0/files/12345/watermark" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -H "content-type: application/json" \ -d '{ "watermark": { "imprint": "default" } }' ``` ## Remove file watermark Removes the watermark from a file. ``` curl -i -X DELETE "https://api.box.com/2.0/files/12345/watermark" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Get a folder Retrieves details for a folder, including the first 100 entries in the folder. To fetch more items within the folder, please use the [Get items in a folder](#get-folders-id-items) endpoint. ``` curl -i -X GET "https://api.box.com/2.0/folders/4353455" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Restore folder Restores a folder that has been moved to the trash. ``` curl -i -X POST "https://api.box.com/2.0/folders/4353455" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Update a folder Updates a folder. This can be also be used to move the folder, create shared links, update collaborations, and more. ``` curl -i -X PUT "https://api.box.com/2.0/folders/4353455" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -H "content-type: application/json" \ -d '{ "name": "New folder name" }' ``` ## Move a folder ``` curl -i -X PUT "https://api.box.com/2.0/folders/4353455" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -H "content-type: application/json" \ -d '{ "name": "New folder name", "parent": { "id": "123" } }' ``` ## Move a subfolder to a private folder ``` curl -i -X PUT "https://api.box.com/2.0/folders/4353455" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -H "content-type: application/json" \ -d '{ "name": "New folder name", "parent": { "id": "123" } "owned_by": { "id": "123456" } }' ``` ## Rename a folder ``` curl -i -X PUT "https://api.box.com/2.0/folders/4353455" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -H "content-type: application/json" \ -d '{ "name": "New folder name" }' ``` ## Change folder owner ``` curl -i -X PUT "https://api.box.com/2.0/folders/4353455" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -H "content-type: application/json" \ -d '{ "owned_by": { "id": "123" } }' ``` ## Delete a folder Deletes a folder, either permanently or by moving it to the trash. ``` curl -i -X DELETE "https://api.box.com/2.0/folders/4353455" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Get items in folder Retrieves a page of items in a folder. These items can be files, folders, and web links. To request more information about the folder itself, like its size, please use the [Get a folder](#get-folders-id) endpoint instead. ``` curl -i -X GET "https://api.box.com/2.0/folders/0/items" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Create a folder Creates a new empty folder within the specified parent folder. ``` curl -i -X POST "https://api.box.com/2.0/folders" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -H "content-type: application/json" \ -d '{ "name": "New Folder", "parent": { "id": "0" } }' ``` ## Copy a folder Creates a copy of a folder within a destination folder. The original folder will not be changed. ``` curl -i -X POST "https://api.box.com/2.0/folders/4353455/copy" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -H "content-type: application/json" \ -d '{ "parent": { "id": "345345" } }' ``` ## Get folder collaborations Retrieves a list of collaborations for a folder. This returns all the users that have access to the folder. ``` curl -i -X GET "https://api.box.com/2.0/folders/4353455/collaborations" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Get trashed folder Retrieves a folder that has been moved to the trash. ``` curl -i -X GET "https://api.box.com/2.0/folders/4353455/trash" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Permanently delete folder Permanently deletes a folder that is in the trash. This action cannot be undone. ``` curl -i -X DELETE "https://api.box.com/2.0/folders/4353455/trash" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## List folder's metadata Retrieves all metadata for a given folder. ``` curl -i -X GET "https://api.box.com/2.0/folders/4353455/metadata" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Get specific folder metadata Retrieve a specific metadata template instance for a folder ``` curl -i -X GET "https://api.box.com/2.0/folders/4353455/metadata/enterprise_27335/blueprintTemplate" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Create metadata on folder Creates a piece of metadata on a folder based on the specified template. Only values that are present in the metadata template will be accepted. ``` curl -i -X POST "https://api.box.com/2.0/folders/4353455/metadata/enterprise_27335/blueprintTemplate" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -H "content-type: application/json" \ -d '{ "audience": "internal", "documentType": "Q1 plans", "competitiveDocument": "no", "status": "active", "author": "Jones", "currentState": "proposal" }' ``` ## Update folder metadata Updates a piece of metadata on a folder based. The metadata instance can only be updated if the instance already exists. When editing metadata, only values that adhere to the metadata template schema will be accepted. The update is applied atomically. If any errors occur during the application of the operations, the metadata instance remains unchanged. ``` curl -i -X PUT "https://api.box.com/2.0/folders/4353455/metadata/enterprise_27335/blueprintTemplate" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -H "content-type: application/json-patch+json" \ -d '[ { "op": "test", "path": "/competitiveDocument", "value": "no" }, { "op": "remove", "path": "/competitiveDocument" }, { "op": "test", "path": "/status", "value": "active" }, { "op": "replace", "path": "/status", "value": "inactive" }, { "op": "test", "path": "/author", "value": "Jones" }, { "op": "copy", "from": "/author", "path": "/editor" }, { "op": "test", "path": "/currentState", "value": "proposal" }, { "op": "move", "from": "/currentState", "path": "/previousState" }, { "op": "add", "path": "/currentState", "value": "reviewed" } ]' ``` ## Delete folder metadata Deletes a piece of folder metadata. ``` curl -i -X DELETE "https://api.box.com/2.0/folders/4353455/metadata/enterprise_27335/blueprintTemplate" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## List trashed items Retrieves the files and folders that have been moved to the trash. Any attribute in the full files or folders objects can be passed in with the `fields` parameter to retrieve those specific attributes that are not returned by default. ``` curl -i -X GET "https://api.box.com/2.0/folders/trash/items" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Get folder watermark Retrieve the watermark for a folder. ``` curl -i -X GET "https://api.box.com/2.0/folders/4353455/watermark" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Apply watermark to folder Applies or update a watermark on a folder. ``` curl -i -X PUT "https://api.box.com/2.0/folders/4353455/watermark" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -H "content-type: application/json" \ -d '{ "watermark": { "imprint": "default" } }' ``` ## Remove folder watermark Removes the watermark from a folder. ``` curl -i -X DELETE "https://api.box.com/2.0/folders/4353455/watermark" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Get folder lock Retrieve locks applied to a folder. ``` curl -i -X GET "https://api.box.com/2.0/folder_locks?folder_id=33552487093" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Create folder lock Creates a lock on a folder to prevent move and / or delete operations. ``` curl -i -X POST "https://api.box.com/2.0/folder_locks" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -H "content-type: application/json" \ -d '{ "folder": { "type": "folder", "id": "33552487093" }, "locked_operations": { "move": true, "delete": true } }' ``` ## Delete folder lock Deletes a lock on a folder. ``` curl -i -X DELETE "https://api.box.com/2.0/folder_locks/93134" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Get template by name Retrieves a metadata template by its scope and template name. ``` curl -i -X GET "https://api.box.com/2.0/metadata_templates/enterprise/blueprintTemplate/schema" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Update metadata template Updates a metadata template. The metadata template can only be updated if the template already exists. The update is applied atomically. If any errors occur during the application of the operations, the metadata template remains unchanged. ``` curl -i -X PUT "https://api.box.com/2.0/metadata_templates/enterprise/blueprintTemplate/schema" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -H "content-type: application/json-patch+json" \ -d '[ { "op": "editField", "fieldKey": "category", "data": { "displayName": "Customer Group" } } ]' ``` ## Delete metadata template Delete a metadata template and its instances. This deletion is permanent and can not be reversed. ``` curl -i -X DELETE "https://api.box.com/2.0/metadata_templates/enterprise/blueprintTemplate/schema" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Get a template by ID Retrieves a metadata template by its ID. ``` curl -i -X GET "https://api.box.com/2.0/metadata_templates/d9671692-3df6-11ea-b77f-2e728ce88125" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## List enterprise templates Used to retrieve all metadata templates within a user's enterprise ``` curl -i -X GET "https://api.box.com/2.0/metadata_templates/enterprise" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## List global templates Used to retrieve all globally available metadata templates. ``` curl -i -X GET "https://api.box.com/2.0/metadata_templates/global" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Create metadata template Creates a new metadata template that can be applied to files and folders. ``` curl -i -X POST "https://api.box.com/2.0/metadata_templates/schema" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -H "content-type: application/json" \ -d '{ "scope": "enterprise", "displayName": "Customer", "fields": [ { "type": "string", "key": "name", "displayName": "Name", "description": "The customer name", "hidden": false }, { "type": "date", "key": "last_contacted_at", "displayName": "Last Contacted At", "description": "When this customer was last contacted at", "hidden": false }, { "type": "enum", "key": "industry", "displayName": "Industry", "options": [ {"key": "Technology"}, {"key": "Healthcare"}, {"key": "Legal"} ] }, { "type": "multiSelect", "key": "role", "displayName": "Contact Role", "options": [ {"key": "Developer"}, {"key": "Business Owner"}, {"key": "Marketing"}, {"key": "Legal"}, {"key": "Sales"} ] } ] }' ``` ## List cascade policies Retrieve a collection of metadata cascade policies within a given folder for the current enterprise. ``` curl -i -X GET "https://api.box.com/2.0/metadata_cascade_policies?folder_id=31232" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Create cascade policy Creates a new metadata cascade policy that applies a given metadata template to a given folder and automatically cascades it down to its children. In order for the policy to work, a metadata instance must first be applied to the folder. ``` curl -i -X POST "https://api.box.com/2.0/metadata_cascade_policies" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -H "content-type: application/json" \ -d '{ "folder_id": "12321", "scope": "enterprise_27335", "templateKey": "productInfo" }' ``` ## Get cascade policy Retrieve a metadata cascade policy. ``` curl -i -X GET "https://api.box.com/2.0/metadata_cascade_policies/324324" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Delete cascade policy Deletes a metadata cascade policy. ``` curl -i -X DELETE "https://api.box.com/2.0/metadata_cascade_policies/324324" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Force apply cascade policy If a policy already exists on a folder, this will apply that policy to all existing files and sub-folders within the target folder. ``` curl -i -X POST "https://api.box.com/2.0/metadata_cascade_policies/21312/apply" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -H "content-type: application/json" \ -d '{ "conflict_resolution": "overwrite" }' ``` ## Create a metadata query ``` curl -i -X POST "https://api.box.com/2.0/files/12345" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -H "content-type: application/json" \ -d '{ "from": "enterprise_123456.contractTemplate", "query": "amount >= :value", "query_params": { "value": 100 }, "fields": [ "created_at", "metadata.enterprise_123456.contractTemplate.amount", "metadata.enterprise_123456.contractTemplate.customerName" ], "ancestor_folder_id": "5555", "order_by": [ { "field_key": "amount", "direction": "asc" } ], "limit": 100 }' ``` ## Get metadata query indices ``` curl -i -X GET "https://api.box.com/2.0/metadata_query_indices?scope=enterprise&template_key=properties" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Get comment Retrieves the message and metadata for a specific comment, as well as information on the user who created the comment. ``` curl -i -X GET "https://api.box.com/2.0/comments/12345" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Update comment Update the message of a comment. ``` curl -i -X PUT "https://api.box.com/2.0/comments/12345" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -H "content-type: application/json" \ -d '{ "message": "My New Message" }' ``` ## Delete comment Permanently deletes a comment. ``` curl -i -X DELETE "https://api.box.com/2.0/comments/12345" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Create comment Adds a comment comment by the user to a specific file, or as a reply to an other comment. ``` curl -i -X POST "https://api.box.com/2.0/comments" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -H "content-type: application/json" \ -d '{ "message": "Review completed!", "item": { "type": "file", "id": 426436 } }' ``` ## Create reply ``` curl -i -X POST "https://api.box.com/2.0/comments" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -H "content-type: application/json" \ -d '{ "message": "I agree with this.", "item": { "type": "comment", "id": 345344 } } ``` ## Tag User in Comment ``` curl -i -X POST "https://api.box.com/2.0/comments" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -H "content-type: application/json" \ -d '{ "tagged_message": "What do you think @[1234:John]?", "item": { "type": "file", "id": 123 } } ``` ## Tag User in Reply ``` curl -i -X POST "https://api.box.com/2.0/comments" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -H "content-type: application/json" \ -d '{ "message": " @[1234:John], I agree with this.", "item": { "type": "comment", "id": 345344 } } ``` ## Get collaboration Retrieves a single collaboration. ``` curl -i -X GET "https://api.box.com/2.0/collaborations/1234" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Update collaboration Updates a collaboration. Can be used to change the owner of an item, or to accept collaboration invites. ``` curl -i -X PUT "https://api.box.com/2.0/collaborations/1234" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -H "content-type: application/json" \ -d '{ "role": "viewer" }' ``` ## Delete collaboration Deletes a single collaboration. ``` curl -i -X DELETE "https://api.box.com/2.0/collaborations/1234" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## List pending collaborations Retrieves all pending collaboration invites for this user. ``` curl -i -X GET "https://api.box.com/2.0/collaborations?status=pending" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Create collaboration Adds a collaboration for a single user or a single group to a file or folder. Collaborations can be created using email address, user IDs, or a group IDs. If a collaboration is being created with a group, access to this endpoint is dependent on the group's ability to be invited. ``` curl -i -X POST "https://api.box.com/2.0/collaborations" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -H "content-type: application/json" \ -d '{ "item": { "type": "file", "id": "11446498" }, "accessible_by": { "type": "user", "login": "user@example.com" }, "role": "editor" }' ``` ``` curl -i -X POST "https://api.box.com/2.0/collaborations" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -H "content-type: application/json" \ -d '{ "item": { "type": "file", "id": "11446498" }, "accessible_by": { "type": "group", "id": "845344" }, "role": "editor" }' ``` ## Search for content Searches for items that are available to the user or an entire enterprise. ``` curl -i -X GET "https://api.box.com/2.0/search?query=sales" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Create task Creates a single task on a file. ``` curl -i -X POST "https://api.box.com/2.0/tasks" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -H "content-type: application/json" \ -d '{ "item": { "id": "11446498", "type": "file" }, "action": "review" }' ``` ## Get task Fetches a specific task. ``` curl -i -X GET "https://api.box.com/2.0/tasks/12345" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Update task Updates a specific task. ``` curl -i -X PUT "https://api.box.com/2.0/tasks/12345" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -H "content-type: application/json" \ -d '{ "action": "review" }' ``` ## Delete task Deletes a specific task. ``` curl -i -X DELETE "https://api.box.com/2.0/tasks/12345" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## List task's assignments Retrieves all of the assignments for a given task. ``` curl -i -X GET "https://api.box.com/2.0/tasks/12345/assignments" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Assign task Assigns a task to a user. Multiple assignments to different users are allowed per task. ``` curl -i -X POST "https://api.box.com/2.0/task_assignments" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -H "content-type: application/json" \ -d '{ "task": { "id": "11446498", "type": "task" }, "assign_to": { "id": "4823213" } }' ``` ## Get task assignment Fetches a specific task assignment. ``` curl -i -X GET "https://api.box.com/2.0/task_assignments/12345" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Update task assignment Updates a task assignment. This endpoint can be used to update the state of a task. ``` curl -i -X PUT "https://api.box.com/2.0/task_assignments/12345" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -H "content-type: application/json" \ -d '{ "message": "New message", "resolution_state": "completed" }' ``` ## Unassign task Deletes a specific task assignment. ``` curl -i -X DELETE "https://api.box.com/2.0/task_assignments/12345" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Find item for shared link Return the file or folder represented by a shared link. Shared items are any files or folders that are represented by a shared link, which can originate within the current enterprise or within another one. This endpoint allows an application to retrieve information about a shared item when only given a shared link. ``` curl -i -X GET "https://api.box.com/2.0/shared_items" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -H "boxapi: shared_link=https://app.box.com/s/gjasdasjhasd&shared_link_password=letmein" ``` The syntax is the same regardless of wether the shared link is a file or a folder. ``` curl -i -X GET "https://api.box.com/2.0/shared_items" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -H "boxapi: shared_link=https://app.box.com/s/jsasdsd8sad24&shared_link_password=letmein" ``` ## Create web link Creates a web link object within a folder. ``` curl -i -X POST "https://api.box.com/2.0/web_links" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -H "content-type: application/json" \ -d '{ "name": "Cloud Content Management", "url": "https://box.com", "parent": { "id": "0" } }' ``` ## Get web link Retrieve information about a web link. ``` curl -i -X GET "https://api.box.com/2.0/web_links/12345" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Restore web link Restores an web link that has been moved to the trash. ``` curl -i -X POST "https://api.box.com/2.0/web_links/12345" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Update web link Updates a web link object. ``` curl -i -X PUT "https://api.box.com/2.0/web_links/12345" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -H "content-type: application/json" \ -d '{ "name": "Cloud Content Management" }' ``` ## Delete web link Deletes a web link. ``` curl -i -X DELETE "https://api.box.com/2.0/web_links/12345" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Get trashed web link Retrieves a web link that has been moved to the trash. ``` curl -i -X GET "https://api.box.com/2.0/web_links/12345/trash" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Permanently delete web link Permanently deletes a web link that is in the trash. This action cannot be undone. ``` curl -i -X DELETE "https://api.box.com/2.0/web_links/12345/trash" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## List enterprise users Returns a list of all users for the Enterprise along with their user_id, public_name, and login. The application and the authenticated user need to have the permission to look up users in the entire enterprise. ``` curl -i -X GET "https://api.box.com/2.0/users" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Create user Creates a new managed user in an enterprise. This endpoint is only available to users and applications with the right admin permissions. ``` curl -i -X POST "https://api.box.com/2.0/users" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -H "content-type: application/json" \ -d '{ "login": "ceo@example.com", "name": "Aaron Levie" }' ``` ## Get authenticated user Retrieves information about the user who is currently authenticated. In the case of a 3-legged OAuth2, client-side authenticated application this will be the user who authorized the app. In the case of a JWT, server-side authenticated application this will be the service account that belongs to the application by default. Use the `As-User` header to change who this API call is made on behalf of. ``` curl -i -X GET "https://api.box.com/2.0/users/me" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Get user Retrieves information about a user in the enterprise. The application and the authenticated user need to have the permission to look up users in the entire enterprise. This endpoint also returns a limited set of information for external users who are collaborated on content owned by the enterprise for authenticated users with the right scopes. In this case, disallowed fields will return null instead. ``` curl -i -X GET "https://api.box.com/2.0/users/12345" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Update user Updates a managed user in an enterprise. This endpoint is only available to users and applications with the right admin permissions. ``` curl -i -X PUT "https://api.box.com/2.0/users/12345" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -H "content-type: application/json" \ -d '{ "name": "Aaron Levie" }' ``` ## Delete user Deletes a user. By default this will fail if the user still owns any content. Move their owned content first before proceeding, or use the `force` field to delete the user and their files. ``` curl -i -X DELETE "https://api.box.com/2.0/users/12345" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Get user avatar Retrieves an image of a the user's avatar. ``` curl -i -X GET "https://api.box.com/2.0/users/12345/avatar" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Add or update user avatar Uploads or updates a user avatar. ``` curl -i -X -L POST "https://api.box.net/2.0/users/12345/avatar" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ --form 'pic=@"path/to/file/file.jpeg"' ``` ## Delete user avatar Deletes a user avatar. ``` curl -i -X DELETE -L "https://api.box.net/2.0/users/12345/avatar" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Transfer owned folders Move all of the items owned by a user into a new folder in another user’s account. Only the root folder (`0`) can be transferred. Folders can only be moved across users by users with administrative permissions. This call will be performed synchronously which might lead to a slow response when the source user has a large number of items in all of its folders. If the destination path has a metadata cascade policy attached to any of the parent folders, a metadata cascade operation will be kicked off asynchronously. There is currently no way to check for when this operation is finished. ``` curl -i -X PUT "https://api.box.com/2.0/users/12345/folders/0" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -H "content-type: application/json" \ -d '{ "owned_by": { "id": "1232234" } }' ``` ## List user's email aliases Retrieves all email aliases for a user. The collection does not include the primary login for the user. ``` curl -i -X GET "https://api.box.com/2.0/users/12345/email_aliases" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Create email alias Adds a new email alias to a user account. ``` curl -i -X POST "https://api.box.com/2.0/users/12345/email_aliases" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -H "content-type: application/json" \ -d '{ "email": "alias@example.com" }' ``` ## Remove email alias Removes an email alias from a user. ``` curl -i -X DELETE "https://api.box.com/2.0/users/12345/email_aliases/23432" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## List user's groups Retrieves all the groups for a user. The user making an API call must have admin permissions to inspect the enterprise's groups. ``` curl -i -X GET "https://api.box.com/2.0/users/12345/memberships" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Invite user Invites an existing external user to join an enterprise. The existing user can not be part of another enterprise and must already have a Box account. Once invited, the user will receive an email and are prompted to accept the invitation within the Box web application. This method requires the "Manage An Enterprise" scope enabled for the application, which can be enabled within the developer console. ``` curl -i -X POST "https://api.box.com/2.0/invites" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -H "content-type: application/json" \ -d '{ "enterprise": { "id": "1232234" }, "actionable_by": { "login" : "freeuser@box.com" } }' ``` ## Get user invite status Returns the status of a user invite. ``` curl -i -X GET "https://api.box.com/2.0/invites/213723" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## List enterprise groups Retrieves all of the groups for a given enterprise. The user must have admin permissions to inspect enterprise's groups. ``` curl -i -X GET "https://api.box.com/2.0/groups" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Create group Creates a new group of users in an enterprise. Only users with admin permissions can create new groups. ``` curl -i -X POST "https://api.box.com/2.0/groups" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -H "content-type: application/json" \ -d '{ "name": "Customer Support" }' ``` ## Get group Retrieves information about a group. ``` curl -i -X GET "https://api.box.com/2.0/groups/57645" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Update group Updates a specific group. ``` curl -i -X PUT "https://api.box.com/2.0/groups/57645" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -H "content-type: application/json" \ -d '{ "name": "Customer Support" }' ``` ## Delete group Permanently deletes a group. ``` curl -i -X DELETE "https://api.box.com/2.0/groups/57645" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## List group's members Retrieves all the members for a group. The user must have admin permissions to inspect enterprise's groups. ``` curl -i -X GET "https://api.box.com/2.0/groups/57645/memberships" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## List group's collaborations Retrieves all the collaborations for a group. The user must have admin permissions to inspect enterprise's groups. Each collaboration object has details on which files or folders the group has access to and with what role. ``` curl -i -X GET "https://api.box.com/2.0/groups/57645/collaborations" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Add user to group Creates a group membership ``` curl -i -X POST "https://api.box.com/2.0/group_memberships" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -H "content-type: application/json" \ -d '{ "user": { "id": "1434325" }, "group": { "id": "4545523" } }' ``` ## Get group membership Retrieves a specific group membership. ``` curl -i -X GET "https://api.box.com/2.0/group_memberships/434534" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Update user's membership Updates a user's group membership. ``` curl -i -X PUT "https://api.box.com/2.0/group_memberships/434534" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -H "content-type: application/json" \ -d '{ "role": "admin" }' ``` ## Remove user from group Deletes a specific group membership. ``` curl -i -X DELETE "https://api.box.com/2.0/group_memberships/434534" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## List all webhooks Returns all defined webhooks for the requesting application. ``` curl -i -X GET "https://api.box.com/2.0/webhooks" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Create webhook Creates a webhook. ``` curl -i -X POST "https://api.box.com/2.0/webhooks" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -H "content-type: application/json" \ -d '{ "target": { "id": "21322", "type": "file" }, "address": "https://example.com/webhooks", "triggers": [ "FILE.PREVIEWED" ] }' ``` ``` curl -i -X POST "https://api.box.com/2.0/webhooks" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -H "content-type: application/json" \ -d '{ "target": { "id": "234234", "type": "folder" }, "address": "https://example.com/webhooks", "triggers": [ "FILE.UPLOADED" ] }' ``` ## Get webhook Retrieves a specific webhook ``` curl -i -X GET "https://api.box.com/2.0/webhooks/3321123" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Update webhook Updates a webhook. ``` curl -i -X PUT "https://api.box.com/2.0/webhooks/3321123" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -H "content-type: application/json" \ -d '{ "triggers": [ "FILE.DOWNLOADED" ] }' ``` ## Delete webhook Deletes a webhook. ``` curl -i -X DELETE "https://api.box.com/2.0/webhooks/3321123" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Update skill invocation Updates the status, usage and response metadata of a skill invocation. ``` curl -i -X PUT "https://api.box.com/2.0/skill_invocations/33243242" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -H "content-type: application/json" \ -d '{ "status": "success", "metadata": { "cards": [{ "type": "skill_card", "skill_card_type": "keyword", "skill_card_title": { "code": "license-plates", "message": "Licence Plates" }, "skill": { "type": "service" "id": "license-plates-service" }, "invocation": { "type": "skill_invocation" "id": "license-plates-service-123" }, "entries": { { "text": "DD-26-YT" }, { "text": "DN86 BOX" } } },{ "type": "skill_card", "skill_card_type": "transcript", "skill_card_title": { "code": "video-transcription", "message": "Video Transcription" }, "skill": { "type": "service" "id": "video-transcription-service" }, "invocation": { "type": "skill_invocation" "id": "video-transcription-service-123" }, "duration": 1000, "entries": { { "text": "Hi John, have I told you about Box recently?", "appears": [{ "start": 0 }] }, { "text": "No Aaron, you have not. Tell me more!", "appears": [{ "start": 5 }] } } },{ "type": "skill_card", "skill_card_type": "timeline", "skill_card_title": { "code": "face-detection", "message": "Faces" }, "skill": { "type": "service" "id": "face-detection-service" }, "invocation": { "type": "skill_invocation" "id": "face-detection-service-123" }, "duration": 1000, "entries": { { "text": "John", "appears": [{ "start": 0, "end": 5 }, { "start": 10, "end": 15 }], "image_url": "https://example.com/john.png" }, { "text": "Aaron", "appears": [{ "start": 5, "end": 10 }], "image_url": "https://example.com/aaron.png" } } },{ "type": "skill_card", "skill_card_type": "status", "skill_card_title": { "code": "hold", "message": "Please hold..." }, "skill": { "type": "service" "id": "face-detection-service" }, "invocation": { "type": "skill_invocation" "id": "face-detection-service-123" }, "status": { "code": "processing", "message": "We are processing this file right now." } }], }, "file": { "id": "12345" }, "usage": { "unit": "file", "value": 1 } }' ``` ## List Skill cards on file ``` curl -i -X PUT "https://api.box.com/2.0/files/12345/metadata/global/boxSkillsCards" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Create Skill cards on file ``` curl -i -X POST "https://api.box.com/2.0/files/12345/metadata/global/boxSkillsCards" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -H "content-type: application/json" \ -d '{ "cards": [{ "type": "skill_card", "skill_card_type": "keyword", "skill_card_title": { "code": "license-plates", "message": "Licence Plates" }, "skill": { "type": "service" "id": "license-plates-service" }, "invocation": { "type": "skill_invocation" "id": "license-plates-service-123" }, "entries": { { "text": "DD-26-YT" }, { "text": "DN86 BOX" } } },{ "type": "skill_card", "skill_card_type": "transcript", "skill_card_title": { "code": "video-transcription", "message": "Video Transcription" }, "skill": { "type": "service" "id": "video-transcription-service" }, "invocation": { "type": "skill_invocation" "id": "video-transcription-service-123" }, "duration": 1000, "entries": { { "text": "Hi John, have I told you about Box recently?", "appears": [{ "start": 0 }] }, { "text": "No Aaron, you have not. Tell me more!", "appears": [{ "start": 5 }] } } },{ "type": "skill_card", "skill_card_type": "timeline", "skill_card_title": { "code": "face-detection", "message": "Faces" }, "skill": { "type": "service" "id": "face-detection-service" }, "invocation": { "type": "skill_invocation" "id": "face-detection-service-123" }, "duration": 1000, "entries": { { "text": "John", "appears": [{ "start": 0, "end": 5 }, { "start": 10, "end": 15 }], "image_url": "https://example.com/john.png" }, { "text": "Aaron", "appears": [{ "start": 5, "end": 10 }], "image_url": "https://example.com/aaron.png" } } },{ "type": "skill_card", "skill_card_type": "status", "skill_card_title": { "code": "hold", "message": "Please hold..." }, "skill": { "type": "service" "id": "face-detection-service" }, "invocation": { "type": "skill_invocation" "id": "face-detection-service-123" }, "status": { "code": "processing", "message": "We are processing this file right now." } }], }' ``` ## Update Skill cards on file ``` curl -i -X PUT "https://api.box.com/2.0/files/12345/metadata/global/boxSkillsCards" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -H "content-type: application/json-patch+json" \ -d '[ "op": "replace", "path": "/cards/0", "value": { "type": "skill_card", "skill_card_type": "keyword", "skill_card_title": { "code": "license-plates", "message": "Licence Plates" }, "skill": { "type": "service" "id": "license-plates-service" }, "invocation": { "type": "skill_invocation" "id": "license-plates-service-123" }, "entries": { { "text": "DD-26-YT" }, { "text": "DN86 BOX" } } } ]' ``` ## Delete Skill cards from file ``` curl -i -X DELETE "https://api.box.com/2.0/files/12345/metadata/global/boxSkillsCards" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Get a long poll endpoint Returns a list of real-time servers that can be used for long-polling updates to the [event stream](#get-events). Long polling is the concept where a HTTP request is kept open until the server sends a response, then repeating the process over and over to receive updated responses. Long polling the event stream can only be used for user events, not for enterprise events. To use long polling, first use this endpoint to retrieve a list of long poll URLs. Next, make a long poll request to any of the provided URLs. When an event occurs in monitored account a response with the value `new_change` will be sent. The response contains no other details as it simply serves as a prompt to take further action such as sending a request to the [events endpoint](#get-events) with the last known `stream_position`. After the server sends this response it closes the connection. You must now repeat the long poll process to begin listening for events again. If no events occur for a while and the connection times out you will receive a response with the value `reconnect`. When you receive this response you’ll make another call to this endpoint to restart the process. If you receive no events in `retry_timeout` seconds then you will need to make another request to the real-time server (one of the URLs in the response for this endpoint). This might be necessary due to network errors. Finally, if you receive a `max_retries` error when making a request to the real-time server, you should start over by making a call to this endpoint first. ``` curl -i -X OPTIONS "https://api.box.com/2.0/events" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Get user and enterprise events Returns up to a year of past events for a given user or for the entire enterprise. By default this returns events for the authenticated user. To retrieve events for the entire enterprise, set the `stream_type` to `admin_logs` (historical - 1 year) or `admin_logs_streaming` (live - two weeks). The user making the API call will need to have admin privileges, and the application will need to have the permission to access the event feed to get the enterprise event feed. ``` curl -i -X GET "https://api.box.com/2.0/events" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ``` curl -i -X GET "https://api.box.com/2.0/events?stream_type=admin_logs" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ``` curl -i -X GET "https://api.box.com/2.0/events?stream_type=admin_logs&event_type=LOGIN,FAILED_LOGIN" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ``` curl -i -X GET "https://api.box.com/2.0/events?stream_type=admin_logs_streaming" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ``` curl -i -X GET "https://api.box.com/2.0/events?stream_type=admin_logs_streaming&event_type=LOGIN,FAILED_LOGIN" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## List all collections Retrieves all collections for a given user. Currently, only the `favorites` collection is supported. ``` curl -i -X GET "https://api.box.com/2.0/collections" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## List collection items Retrieves the files and/or folders contained within this collection. ``` curl -i -X GET "https://api.box.com/2.0/collections/926489/items" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Add file to collection ``` curl -i -X PUT "https://api.box.com/2.0/files/12345" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -H "content-type: application/json" \ -d '{ "collections": [ { "id": "123" } ] }' ``` ## Add folder to collection ``` curl -i -X PUT "https://api.box.com/2.0/folders/12345" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -H "content-type: application/json" \ -d '{ "collections": [ { "id": "123" } ] }' ``` ## Add web link to collection ``` curl -i -X PUT "https://api.box.com/2.0/web_links/12345" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -H "content-type: application/json" \ -d '{ "collections": [ { "id": "123" } ] }' ``` ## Remove file from collection ``` curl -i -X PUT "https://api.box.com/2.0/files/12345" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -H "content-type: application/json" \ -d '{ "collections": [] }' ``` ## Remove folder from collection ``` curl -i -X PUT "https://api.box.com/2.0/folders/12345" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -H "content-type: application/json" \ -d '{ "collections": [] }' ``` ## Remove web link from collection ``` curl -i -X PUT "https://api.box.com/2.0/web_links/12345" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -H "content-type: application/json" \ -d '{ "collections": [] }' ``` ## List recent items Returns information about the recent items accessed by a user, either in the last 90 days or up to the last 1000 items accessed. ``` curl -i -X GET "https://api.box.com/2.0/recent_items" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## List retention policies Retrieves all of the retention policies for an enterprise. ``` curl -i -X GET "https://api.box.com/2.0/retention_policies" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Create retention policy Creates a retention policy. ``` curl -i -X POST "https://api.box.com/2.0/retention_policies" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -H "content-type: application/json" \ -d '{ "policy_name": "Some Policy Name", "policy_type": "finite", "retention_length": 365, "disposition_action": "permanently_delete" }' ``` ## Get retention policy Retrieves a retention policy. ``` curl -i -X GET "https://api.box.com/2.0/retention_policies/982312" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Update retention policy Updates a retention policy. ``` curl -i -X PUT "https://api.box.com/2.0/retention_policies/982312" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -H "content-type: application/json" \ -d '{ "disposition_action": "permanently_delete" }' ``` ## List policy's assignments Returns a list of all retention policy assignments associated with a specified retention policy. ``` curl -i -X GET "https://api.box.com/2.0/retention_policies/982312/assignments" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Assign retention policy Assigns a retention policy to an item. ``` curl -i -X POST "https://api.box.com/2.0/retention_policy_assignments" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -H "content-type: application/json" \ -d '{ "policy_id": "173463", "assign_to": { "type": "folder", "id": "6564564" } }' ``` ## Get policy assignment Retrieves a retention policy assignment ``` curl -i -X GET "https://api.box.com/2.0/retention_policy_assignments/1233123" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## List all legal hold policies Retrieves a list of legal hold policies that belong to an enterprise. ``` curl -i -X GET "https://api.box.com/2.0/legal_hold_policies" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Create legal hold policy Create a new legal hold policy. ``` curl -i -X POST "https://api.box.com/2.0/legal_hold_policies" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -H "content-type: application/json" \ -d '{ "policy_name": "Policy 3", "description": "Automatic created policy" }' ``` ## Get legal hold policy Retrieve a legal hold policy. ``` curl -i -X GET "https://api.box.com/2.0/legal_hold_policies/324432" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Update legal hold policy Update legal hold policy. ``` curl -i -X PUT "https://api.box.com/2.0/legal_hold_policies/324432" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -H "content-type: application/json" \ -d '{ "policy_name": "Policy 4" }' ``` ## Delete legal hold policy Delete an existing legal hold policy. This is an asynchronous process. The policy will not be fully deleted yet when the response returns. ``` curl -i -X DELETE "https://api.box.com/2.0/legal_hold_policies/324432" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## List policy's assignments Retrieves a list of items a legal hold policy has been assigned to. ``` curl -i -X GET "https://api.box.com/2.0/legal_hold_policy_assignments?policy_id=324432" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Assign legal hold policy Assign a legal hold to a file, file version, folder, or user. ``` curl -i -X POST "https://api.box.com/2.0/legal_hold_policy_assignments" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -H "content-type: application/json" \ -d '{ "policy_id": "123244", "assign_to": { "type": "folder", "id": "6564564" } }' ``` ## Get policy assignment Retrieve a legal hold policy assignment. ``` curl -i -X GET "https://api.box.com/2.0/legal_hold_policy_assignments/753465" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Unassign legal hold policy Remove a legal hold from an item. This is an asynchronous process. The policy will not be fully removed yet when the response returns. ``` curl -i -X DELETE "https://api.box.com/2.0/legal_hold_policy_assignments/753465" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Get retention for file Returns information about a file version retention. ``` curl -i -X GET "https://api.box.com/2.0/file_version_retentions/3424234" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## List retentions on files Retrieves all file version retentions for the given enterprise. ``` curl -i -X GET "https://api.box.com/2.0/file_version_retentions" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## List files under retention for a retention policy Retrieves all files for the given retention policy id. ``` curl -i -X GET "https://app.box.com/api/2.0/retention_policy_assignments/3424234/files_under_retention" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## List file versions under retention for a retention policy Retrieves all file versions for the given retention policy id. ``` curl -i -X GET "https://app.box.com/api/2.0/retention_policy_assignments/3424234/file_versions_under_retention" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Inspect legal hold on file Retrieves information about the legal hold policies assigned to a file version. ``` curl -i -X GET "https://api.box.com/2.0/file_version_legal_holds/2348213" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## List legal holds for policy Get list of non-deleted legal holds for a single legal hold policy. ``` curl -i -X GET "https://api.box.com/2.0/file_version_legal_holds?policy_id=133870" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Get device pin Retrieves information about an individual device pin. ``` curl -i -X GET "https://api.box.com/2.0/device_pinners/2324234" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Delete device pin Deletes an individual device pin. ``` curl -i -X DELETE "https://api.box.com/2.0/device_pinners/2324234" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## List enterprise device pins Retrieves all the device pins within an enterprise. The user must have admin privileges, and the application needs the "manage enterprise" scope to make this call. ``` curl -i -X GET "https://api.box.com/2.0/enterprises/3442311/device_pinners" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## List terms of services Returns the current terms of service text and settings for the enterprise. ``` curl -i -X GET "https://api.box.com/2.0/terms_of_services" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Create terms of service Creates a terms of service for a given enterprise and type of user. ``` curl -i -X POST "https://api.box.com/2.0/terms_of_services" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -H "content-type: application/json" \ -d '{ "status": "enabled", "text": "By collaborating on this file you are accepting..." }' ``` ## Get terms of service Fetches a specific terms of service. ``` curl -i -X GET "https://api.box.com/2.0/terms_of_services/324234" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Update terms of service Updates a specific terms of service. ``` curl -i -X PUT "https://api.box.com/2.0/terms_of_services/324234" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -H "content-type: application/json" \ -d '{ "status": "enabled", "text": "By collaborating on this file you are accepting..." }' ``` ## List ToS user statuses Retrieves an overview of users and their status for a terms of service, including Whether they have accepted the terms and when. ``` curl -i -X GET "https://api.box.com/2.0/terms_of_service_user_statuses?tos_id=324234" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Set status for new user Sets the status for a terms of service for a user. ``` curl -i -X POST "https://api.box.com/2.0/terms_of_service_user_statuses" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -H "content-type: application/json" \ -d '{ "tos": { "type": "terms_of_service", "id": "1232132" }, "user": { "type": "user", "id": "3423423" }, "is_accepted": true }' ``` ## Set status for existing user Updates the status for a terms of service for a user. ``` curl -i -X PUT "https://api.box.com/2.0/terms_of_service_user_statuses/324234" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -H "content-type: application/json" \ -d '{ "is_accepted": true }' ``` ## List whitelist entries Returns the list of whitelist entries which specify what domains can collaborate with the current enterprise. ``` curl -i -X GET "https://api.box.com/2.0/collaboration_whitelist_entries" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Create whitelist entry Creates a collaboration whitelist entry, specifying a domain and direction to allow collaboration for. ``` curl -i -X POST "https://api.box.com/2.0/collaboration_whitelist_entries" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -H "content-type: application/json" \ -d '{ "domain": "example.com", "direction": "inboud" }' ``` ## Get whitelist entry Returns a specific collaboration whitelist entry. ``` curl -i -X GET "https://api.box.com/2.0/collaboration_whitelist_entries/213123" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Delete whitelist entry Deletes a specific collaboration whitelist entry. ``` curl -i -X DELETE "https://api.box.com/2.0/collaboration_whitelist_entries/213123" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## List whitelist exemptions Returns a list of users who have been exempt from the collaboration whitelist. ``` curl -i -X GET "https://api.box.com/2.0/collaboration_whitelist_exempt_targets" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Create whitelist exemption Creates a collaboration whitelist entry exemption, specifying a user that is exempted from the whitelist. ``` curl -i -X POST "https://api.box.com/2.0/collaboration_whitelist_exempt_targets" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -H "content-type: application/json" \ -d '{ "user": { "id": "23522323" } }' ``` ## Get whitelist exemption Returns a users who has been exempt from the collaboration whitelist. ``` curl -i -X GET "https://api.box.com/2.0/collaboration_whitelist_exempt_targets/984923" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Remove whitelist exemption Deletes a specific collaboration whitelist exemption. ``` curl -i -X DELETE "https://api.box.com/2.0/collaboration_whitelist_exempt_targets/984923" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## List storage policies Fetches all the storage policies in the enterprise. ``` curl -i -X GET "https://api.box.com/2.0/storage_policies" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Get storage policy Fetches a specific storage policy. ``` curl -i -X GET "https://api.box.com/2.0/storage_policies/34342" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## List policy assignments Fetches all the storage policy assignment for an enterprise or user. ``` curl -i -X GET "https://api.box.com/2.0/storage_policy_assignments?resolved_for_type=userresolved_for_id=984322" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Assign storage policy Creates a storage policy assignment for an enterprise or user. ``` curl -i -X POST "https://api.box.com/2.0/storage_policy_assignments" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -H "content-type: application/json" \ -d '{ "storage_policy": { "type": "storage_policy", "id": "1434325" }, "assigned_to": { "type": "user", "id": "9987987" } }' ``` ## Get policy assignment Fetches a specific storage policy assignment. ``` curl -i -X GET "https://api.box.com/2.0/storage_policy_assignments/932483" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Update policy assignment Updates a specific storage policy assignment. ``` curl -i -X PUT "https://api.box.com/2.0/storage_policy_assignments/932483" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -H "content-type: application/json" \ -d '{ "storage_policy": { "type": "storage_policy", "id": "1434325" } }' ``` ## Unassign storage policy Delete a storage policy assignment. Deleting a storage policy assignment on a user will have the user inherit the enterprise's default storage policy. There is a rate limit for calling this endpoint of only twice per user in a 24 hour period. ``` curl -i -X DELETE "https://api.box.com/2.0/storage_policy_assignments/932483" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -d '{ "items": { "type": "storage_policy", "id": "1434325" } }' ``` ## Create zip download ``` curl -i -X POST "https://api.box.com/2.0/zip_downloads" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -d '{ "download_file_name": "January Financials", "items": [ { "type": "file", "id": "12345" }, { "type": "file", "id": "34325" }, { "type": "folder", "id": "45678" } ] }' ``` ## Get zip download status ``` curl -i -X GET "https://api.box.com/2.0/zip_downloads/29l00nfxDyHOt7RphI9zT_w==nDnZEDjY2S8iEWWCHEEiptFxwoWojjlibZjJ6geuE5xnXENDTPxzgbks_yY=/status" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Download zip archive ``` curl -L GET "https://dl.boxcloud.com/2.0/zip_downloads/29l00nfxDyHOt7RphI9zT_w==nDnZEDjY2S8iEWWCHEEiptFxwoWojjlibZjJ6geuE5xnXENDTPxzgbks_yY=/content" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -o sample_curl.zip ``` ## List all classifications ``` curl -i -X GET "https://api.box.com/2.0/metadata_templates/enterprise/securityClassification-6VMVochwUWo/schema" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Add initial classifications ``` curl -i -X POST "https://api.box.com/2.0/metadata_templates/schema" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -H "content-type: application/json" \ -d '{ "templateKey": "securityClassification-6VMVochwUWo", "scope": "enterprise", "displayName": "Classification", "hidden": false, "copyInstanceOnItemCopy": true, "fields": [ { "type": "enum", "key": "Box__Security__Classification__Key", "displayName": "Classification", "hidden": false, "options": [ { "key": "Classified", "staticConfig": { "classification": { "colorID": 7, "classificationDefinition": "Top Seret" } } } ] } ] }' ``` ## Add another classification ``` curl -i -X PUT "https://api.box.com/2.0/metadata_templates/enterprise/securityClassification-6VMVochwUWo/schema" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -H "content-type: application/json-patch+json" \ -d '[{ "op": "addEnumOption", "fieldKey": "Box__Security__Classification__Key", "data": { "key": "Sensitive", "staticConfig":{ "classification": { "classificationDefinition": "Sensitive information that must not be shared.", "colorID": 4 } } } }]' ``` ## Update classification ``` curl -i -X PUT "https://api.box.com/2.0/metadata_templates/enterprise/securityClassification-6VMVochwUWo/schema" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -H "content-type: application/json-patch+json" \ -d '[{ "op": "editEnumOption", "fieldKey": "Box__Security__Classification__Key", "enumOptionKey": "Sensitive", "data": { "key": "Very Sensitive", "staticConfig": { "classification": { "classificationDefinition": "Sensitive information that must not be shared.", "colorID": 4 } } } }]' ``` ## Delete classification ``` curl -i -X PUT "https://api.box.com/2.0/metadata_templates/enterprise/securityClassification-6VMVochwUWo/schema" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -H "content-type: application/json-patch+json" \ -d '[{ "op": "removeEnumOption", "fieldKey": "Box__Security__Classification__Key", "enumOptionKey": "Sensitive" }]' ``` ## Delete all classifications ``` curl -i -X DELETE "https://api.box.com/2.0/metadata_templates/enterprise/securityClassification-6VMVochwUWo/schema" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Get classification on file ``` curl -i -X GET "https://api.box.com/2.0/files/12345/metadata/enterprise/securityClassification-6VMVochwUWo" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Add classification to file ``` curl -i -X POST "https://api.box.com/2.0/files/12345/metadata/enterprise/securityClassification-6VMVochwUWo" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -H "content-type: application/json" \ -d '{ "Box__Security__Classification__Key": "Sensitive" }' ``` ## Update classification on file ``` curl -i -X PUT "https://api.box.com/2.0/files/12345/metadata/enterprise/securityClassification-6VMVochwUWo" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -H "content-type: application/json-patch+json" \ -d '[{ "op": "replace", "path": "/Box__Security__Classification__Key", "value": "Internal" }]' ``` ## Remove classification from file ``` curl -i -X DELETE "https://api.box.com/2.0/files/12345/metadata/enterprise/securityClassification-6VMVochwUWo" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Get classification on folder ``` curl -i -X GET "https://api.box.com/2.0/folders/12345/metadata/enterprise/securityClassification-6VMVochwUWo" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Add classification to folder ``` curl -i -X POST "https://api.box.com/2.0/folders/12345/metadata/enterprise/securityClassification-6VMVochwUWo" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -H "content-type: application/json" \ -d '{ "Box__Security__Classification__Key": "Sensitive" }' ``` ## Update classification on folder ``` curl -i -X PUT "https://api.box.com/2.0/folders/12345/metadata/enterprise/securityClassification-6VMVochwUWo" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -H "content-type: application/json-patch+json" \ -d '[{ "op": "replace", "path": "/Box__Security__Classification__Key", "value": "Internal" }]' ``` ## Remove classification from folder ``` curl -i -X DELETE "https://api.box.com/2.0/folders/12345/metadata/enterprise/securityClassification-6VMVochwUWo" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Copy a file request ``` curl -i -X POST "https://api.box.com/2.0/file_requests/42037322/copy" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -d '{ "title": "Please upload required documents", "description": "Please upload required documents", "status": "active", "is_email_required": true, "is_description_required": false, "folder": { "id": "2233212", "type": "folder" } }' ``` ## Update a file request ``` curl -i -X PUT "https://api.box.com/2.0/file_requests/42037322" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -d '{ "title": "Please upload required documents", "description": "Please upload required documents", "status": "active", "is_email_required": true, "is_description_required": false }' ``` ## Get a file request ``` curl -i -X GET "https://api.box.com/2.0/file_requests/42037322" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Delete a file request ``` curl -i -X DELETE "https://api.box.com/2.0/file_requests/42037322" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Get shared link on a file ``` curl -i -X GET "https://api.box.com/2.0/files/32423234?fields=shared_link" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Add shared link to a file ``` curl -i -X PUT "https://api.box.com/2.0/files/32423234?fields=shared_link" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -d '{ "shared_link": { "access": "open", "password": "mypassword", "unshared_at": "2012-12-12T10:53:43-08:00", "permissions": { "can_download": false } } }' ``` ## Update shared link on a file ``` curl -i -X PUT "https://api.box.com/2.0/files/32423234?fields=shared_link" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -d '{ "shared_link": { "access": "open", "password": "mypassword", "unshared_at": "2012-12-12T10:53:43-08:00", "permissions": { "can_download": false } } }' ``` ## Remove shared link from a file ``` curl -i -X PUT "https://api.box.com/2.0/files/32423234?fields=shared_link" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -d '{ "shared_link": null }' ``` ## Get shared link on a folder ``` curl -i -X GET "https://api.box.com/2.0/folders/32423234?fields=shared_link" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Add shared link to a folder ``` curl -i -X PUT "https://api.box.com/2.0/folders/32423234?fields=shared_link" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -d '{ "shared_link": { "access": "open", "password": "mypassword", "unshared_at": "2012-12-12T10:53:43-08:00", "permissions": { "can_download": false } } }' ``` ## Update shared link on a folder ``` curl -i -X PUT "https://api.box.com/2.0/folders/32423234?fields=shared_link" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -d '{ "shared_link": { "access": "open", "password": "mypassword", "unshared_at": "2012-12-12T10:53:43-08:00", "permissions": { "can_download": false } } }' ``` ## Remove shared link from a folder ``` curl -i -X PUT "https://api.box.com/2.0/folders/32423234?fields=shared_link" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -d '{ "shared_link": null }' ``` ## Get shared link on a web link ``` curl -i -X GET "https://api.box.com/2.0/web_links/32423234?fields=shared_link" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Add shared link to a web link ``` curl -i -X PUT "https://api.box.com/2.0/web_links/32423234?fields=shared_link" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -d '{ "shared_link": { "access": "open", "password": "mypassword", "unshared_at": "2012-12-12T10:53:43-08:00", "permissions": { "can_download": false } } }' ``` ## Update shared link on a web link ``` curl -i -X PUT "https://api.box.com/2.0/web_links/32423234?fields=shared_link" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -d '{ "shared_link": { "access": "open", "password": "mypassword", "unshared_at": "2012-12-12T10:53:43-08:00", "permissions": { "can_download": false } } }' ``` ## Remove shared link from a web link ``` curl -i -X PUT "https://api.box.com/2.0/web_links/32423234?fields=shared_link" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -d '{ "shared_link": null }' ``` ## Gets a relay workflow with flows that are of type WORKFLOW_MANUAL_START ``` curl -i -X GET "https://api.box.com/2.0/workflows?folder_id=324234" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Start a flow in a relay workflow of type WORKFLOW_MANUAL_START ``` curl -i -X POST "https://api.box.com/2.0/workflows/42037322/start" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -d '{ "type": "workflow_parameters", "flow": { "id": "8937625", "type": "flow" }, "files": [{ "type": "file", "id": "389047572" }, { "type": "file", "id": "389047578" }], "folder": { "id": "2233212", "type": "folder" }, "outcomes": [ { "id": "34895783", "type": "outcome", "task_collaborators": { "type": "variable", "variable_type": "user_list", "variable_value": [{ "type": "user", "id": "890273642" }] }, "completion_rule": { "type": "variable", "variable_type": "task_completion_rule", "variable_value": "all_assignees" }, "file_collaborator_role": { "type": "variable", "variable_type": "collaborator_role", "variable_value": "viewer" } } ] }' ``` ## Create Box Sign request ``` curl -i -X POST "https://api.box.com/2.0/sign_requests" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -d '{ "signers": [ { "role": "signer", "email": "example_email@box.com" } ], "source_files": [ { "type": "file", "id": "123456789" } ], "parent_folder": { "type": "folder", "id": "0987654321" } }' ``` ## Get Box Sign requests ``` curl -i -X GET "https://api.box.com/2.0/sign_requests" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Get Box Sign request by ID ``` curl -i -X GET "https://api.box.com/2.0/sign_requests/<SIGN_REQUEST_ID>" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Cancel Box Sign request ``` curl -i -X POST "https://api.box.com/2.0/sign_requests/<SIGN_REQUEST_ID>/cancel" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Resend Box Sign request ``` curl -i -X POST "https://api.box.com/2.0/sign_requests/<SIGN_REQUEST_ID>/resend" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Terminate user sessions ``` curl -i -X POST "https://api.box.com/2.0/users/terminate_sessions" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -H "content-type: application/json" \ -H "accept: application/json" \ -d { user_ids: ["6178859178", "4824866571"] user_logins: ["user@example.com", "user2@example.com",] } ``` ## Terminate groups sessions ``` curl -i -X POST "https://api.box.com/2.0/groups/terminate_sessions" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -H "content-type: application/json" \ -H "accept: application/json" \ -d {   "group_ids": ["6178859178", "4824866571"], } ``` ## List integration mappings Slack ``` curl -X -L GET "https://api.box.com/2.0/integration_mappings/slack?partner_item_id=C987654321&box_item_id=123456789" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ ``` ## Create integration mapping Slack ``` curl -X -L POST "https://api.box.com/2.0/integration_mappings/slack" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -H 'content-type: application/json' \ -d '{ "partner_item": { "id": "C987654321", "type": "channel", "slack_workspace_id": "T5555555" }, "box_item": { "id": "123456789", "type": "folder" } }' ``` ## Update integration mapping Slack ``` curl -X -L PUT "https://api.box.com/2.0/integration_mappings/slack/512521" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -H 'content-type: application/json' \ -d'{ "options": { "is_access_management_disabled": true } }' ``` ## Delete integration mapping Slack ``` curl -X -L DELETE "https://api.box.com/2.0/integration_mappings/slack/512521" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -d '' ``` ## Get Box Sign template by ID ``` curl -L -X GET "https://api.box.com/2.0/sign_templates/12345678" \ -H "accept: application/json" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ ``` ## Get Box Sign templates ``` curl -L -X GET "https://api.box.com/2.0/sign_templates?marker=JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii&limit=1000" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ ``` ## List integration mappings Teams ``` curl -X -L GET "https://api.box.com/2.0/integration_mappings/teams" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ ``` ## Create integration mapping Teams ``` curl -X -L POST "https://api.box.com/2.0/integration_mappings/teams" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -H 'content-type: application/json' \ -d '{ "partner_item": { "id": "19%3ABCD-Avgfggkggyftdtfgghjhkhkhh%40thread:tacv2", "type": "channel", "team_id": "hjgjgjg-bhhj-564a-b643-hghgj685u", "tenant_id": "E1234567" }, "box_item": { "id": "42037322", "type": "folder" } }' ``` ## Update integration mapping Teams ``` curl -X -L PUT "https://api.box.com/2.0/integration_mappings/teams/12345" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -H 'content-type: application/json' \ ``` ## Delete integration mapping Teams ``` curl -X -L DELETE "https://api.box.com/2.0/integration_mappings/teams/342423" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -d '' ``` ## Create archive ``` curl -i -X POST "https://api.box.com/2.0/archives" \ -H "box-version: 2025.0" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -H "content-type: application/json" \ -d '{ "name": "Some Archive Name" }' ``` ## List archives ``` curl -i -X GET "https://api.box.com/2.0/archives" \ -H "box-version: 2025.0" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` ## Delete archive ``` curl -i -X DELETE "https://api.box.com/2.0/archives/12345" \ -H "box-version: 2025.0" \ -H "authorization: Bearer <ACCESS_TOKEN>" ``` # Bulk delete external users ``` curl -X -L POST "https://api.box.com/2.0/external_users/external_users_submit_delete_job" \ -H "authorization: Bearer <ACCESS_TOKEN>" \ -d '{ "external_users": "type": "array" "description": "List of external users to delete." "items": "$ref: #/components/schemas/UserReference" }' ``` --- ### Box Dotnet SDK Gen **Type:** page | **Section:** Additional Resources Box Dotnet SDK Gen Project Status build nuget version image Platform Coverage We are excited to introduce the stable release of the latest… # Box Dotnet SDK Gen [](http://opensource.box.com/badges) [](https://badge.fury.io/nu/box.sdk.gen) [](https://badge.fury.io/nu/box.sdk.gen) [](https://coveralls.io/github/box/box-dotnet-sdk-gen?branch=main) We are excited to introduce the stable release of the latest generation of Box Dotnet SDK Gen, designed to elevate the developer experience and streamline your integration with the Box Content Cloud. With this SDK, you’ll have access to: 1. Full API Support: The new generation of Box SDKs empowers developers with complete coverage of the Box API ecosystem. You can now access all the latest features and functionalities offered by Box, allowing you to build even more sophisticated and feature-rich applications. 2. Rapid API Updates: Say goodbye to waiting for new Box APIs to be incorporated into the SDK. With our new auto-generation development approach, we can now add new Box APIs to the SDK at a much faster pace (in a matter of days). This means you can leverage the most up-to-date features in your applications without delay. 3. Embedded Documentation: We understand that easy access to information is crucial for developers. With our new approach, we have included comprehensive documentation for all objects and parameters directly in the source code of the SDK. This means you no longer need to look up this information on the developer portal, saving you time and streamlining your development process. 4. Enhanced Convenience Methods: Our commitment to enhancing your development experience continues with the introduction of convenience methods. These methods cover various aspects such as chunk uploads, classification, and much more. 5. Seamless Start: The new SDKs integrate essential functionalities like authentication, automatic retries with exponential backoff, exception handling, request cancellation, and type checking, enabling you to focus solely on your application's business logic. Embrace the new generation of Box SDKs and unlock the full potential of the Box Content Cloud. # Table of contents - [Box Dotnet SDK Gen](#box-dotnet-sdk-gen) - [Table of contents](#table-of-contents) [Installing](#installing) - [BouncyCastle runtime integrity check](#bouncycastle-runtime-integrity-check) [Getting Started](#getting-started) [Documentation](#documentation) [Upgrades](#upgrades) [Integration Tests](#integration-tests) [Running integration tests locally](#running-integration-tests-locally) - [Create Platform Application](#create-platform-application) - [Export configuration](#export-configuration) - [Running tests](#running-tests) [Questions, Bugs, and Feature Requests?](#questions-bugs-and-feature-requests) [Copyright and License](#copyright-and-license) # Installing You can install SDK using Nuget ``` Install-Package Box.Sdk.Gen ``` Alternatively, you can find this package and it's latest version [on nuget](https://www.nuget.org/packages/Box.Sdk.Gen) and manually add it to the `.csproj` file as a reference: ``` <ItemGroup> <PackageReference Include="Box.Sdk.Gen" Version="X.Y.Z" /> </ItemGroup> ``` ## BouncyCastle runtime integrity check The version of BouncyCastle included in the SDK performs a checksum validation at runtime. As a result, any modifications to the .dll file, such as those introduced by optimizations like [ReadyToRun (R2R)](https://learn.microsoft.com/en-us/dotnet/core/deploying/ready-to-run) compilation, can alter the checksum, causing the validation to fail. This can lead to issues with SDK functionalities that rely on BouncyCastle, such as JWT authentication unusable. You can exclude BouncyCastle from ReadyToRun compilation by adding the following to your `.csproj` file: ``` <ItemGroup> <PublishReadyToRunExclude Include="bc-fips-1.0.2.dll" /> <PublishReadyToRunExclude Include="bcpkix-fips-1.0.2.dll" /> </ItemGroup> ``` # Getting Started To get started with the SDK, get a Developer Token from the Configuration page of your app in the Box Developer Console. You can use this token to make test calls for your own Box account. The SDK provides a `BoxDeveloperTokenAuth` class, which allows you to authenticate using your Developer Token. Use instance of `BoxDeveloperTokenAuth` to initialize `BoxClient` object. Using `BoxClient` object you can access managers, which allow you to perform some operations on your Box account. The example below demonstrates how to authenticate with Developer Token and print names of all items inside a root folder. ``` using Box.Sdk.Gen; var auth = new BoxDeveloperTokenAuth(token: "DEVELOPER_TOKEN_GOES_HERE"); var client = new BoxClient(auth: auth); var items = await client.Folders.GetFolderItemsAsync(folderId: "0"); if (items.Entries != null) { foreach (var item in items.Entries) { if (item.FileFull != null) { Console.WriteLine(item.FileFull.Name); } else if (item.FolderMini != null) { Console.WriteLine(item.FolderMini.Name); } else if (item.WebLink != null) { Console.WriteLine(item.WebLink.Name); } } } ``` The usage docs that show how to make calls to the Box API with the SDK can be found [here](https://github.com/box/box-Dotnet-sdk-gen/tree/main/docs). We recommend, familiarizing yourself with the remaining [authentication methods](https://github.com/box/box-Dotnet-sdk-gen/tree/main/docs/Authentication.md), [uploading files](https://github.com/box/box-Dotnet-sdk-gen/tree/main/docs/Uploads.md) and [downloading files](https://github.com/box/box-Dotnet-sdk-gen/tree/main/docs/Downloads.md). # Documentation Browse the [docs](https://ja.developer.box.com/9bf713975d30c4a497ecc93c108e61e0/README.md) or see [API Reference](https://developer.box.com/reference/) for more information. # Upgrades Upgrading from our legacy SDKs to the new generation SDKs is a straightforward process. See our [migration guide](https://ja.developer.box.com/440547b696987c10bede540d7415cf77/migration-guide.md) and [changelog](https://ja.developer.box.com/504ace9e948bd7b0fe986d9e7f12a88c/CHANGELOG.md) for more information. # Integration Tests ## Running integration tests locally ### Create Platform Application To run integration tests locally you will need a `Custom App` created in the Box Developer Console with `Server Authentication (with JWT)` selected as authentication method. Once created you can edit properties of the application: - In section `App Access Level` select `App + Enterprise Access`. You can enable all `Application Scopes`. - In section `Advanced Features` enable `Make API calls using the as-user header` and `Generate user access tokens`. Now select `Authorization` and submit application to be reviewed by account admin. ### Export configuration Select `Configuration` tab and in the bottom in the section `App Settings` download your app configuration settings as JSON. 1. Encode configuration file to Base64, e.g. using command: `base64 -i path_to_json_file` 2. Set environment variable: `JWT_CONFIG_BASE_64` with base64 encoded jwt configuration file 3. Set environment variable: `BOX_FILE_REQUEST_ID` with ID of file request already created in the user account, `BOX_EXTERNAL_USER_EMAIL` with email of free external user which not belongs to any enterprise. 4. Set environment variable: `WORKFLOW_FOLDER_ID` with the ID of the Relay workflow that deletes the file that triggered the workflow. The workflow should have a manual start to be able to start it from the API. 5. Set environment variable: `APP_ITEM_ASSOCIATION_FILE_ID` to the ID of the file with associated app item and `APP_ITEM_ASSOCIATION_FOLDER_ID` to the ID of the folder with associated app item. 6. Set environment variable: `APP_ITEM_SHARED_LINK` to the shared link associated with app item. 7. Set environment variable: `SLACK_AUTOMATION_USER_ID` to the ID of the user responsible for the Slack automation, `SLACK_ORG_ID` to the ID of the Slack organization and `SLACK_PARTNER_ITEM_ID` to the ID of the Slack partner item. ### Running tests To run integration tests locally: 1. `dotnet test` # Questions, Bugs, and Feature Requests? Need to contact us directly? Browse the issues tickets! Or, if that doesn't work, file a new one and we will get back to you. If you have general questions about the Box API, you can post to the [Box Developer Forum](https://forum.box.com/). # Copyright and License Copyright 2023 Box, Inc. All rights reserved. Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at [http://www.apache.org/licenses/LICENSE-2.0](http://www.apache.org/licenses/LICENSE-2.0) Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. For third party notices visit [THIRD-PARTY-NOTICES](THIRD-PARTY-NOTICES.txt) --- ### Box iOS SDK **Type:** page | **Section:** Additional Resources Box iOS SDK Project Status Platforms License Swift Package Manager Carthage compatible CocoaPods compatible Build Status Coverage Getting… # Box iOS SDK [](http://opensource.box.com/badges) [](https://cocoapods.org/pods/BoxSDK) [](https://raw.githubusercontent.com/box/box-ios-sdk/main/LICENSE) [](https://github.com/apple/swift-package-manager) [](https://github.com/Carthage/Carthage) [](https://cocoapods.org/pods/BoxSDK) [](https://travis-ci.com/box/box-swift-sdk) [](https://coveralls.io/github/box/box-ios-sdk?branch=main) Getting Started Docs: [https://developer.box.com/guides/mobile/ios/quick-start/](https://developer.box.com/guides/mobile/ios/quick-start/) # NOTE: The Box iOS SDK in **Objective-C** (prior to v3.0.0) has been moved from the main branch to the [objective-c-maintenance branch](https://github.com/box/box-ios-sdk/tree/objective-c-maintenance). Going forward, the main branch will contain the iOS SDK in **Swift**, starting with v3.0.0. Box iOS SDK - [Box iOS SDK](#box-ios-sdk) [NOTE:](#note) - [Requirements](#requirements) [Installing the SDK](#installing-the-sdk) - [Carthage](#carthage) - [CocoaPods](#cocoapods) [Swift Package Manager](#swift-package-manager) - [Importing BoxSDK into Project](#importing-boxsdk-into-project) - [Adding BoxSDK as a Dependency](#adding-boxsdk-as-a-dependency) [Getting Started](#getting-started) [Sample Apps](#sample-apps) - [OAuth2 Sample App](#oauth2-sample-app) - [JWT Auth Sample App](#jwt-auth-sample-app) [FIPS 140-2 Compliance](#fips-140-2-compliance) [Versions](#versions) - [Supported Version](#supported-version) - [Version schedule](#version-schedule) [Copyright and License](#copyright-and-license) ## Requirements - iOS 11.0+ / Mac OS X 10.13+ / tvOS 11.0+ / watchOS 4.0+ - Xcode 10.0+ ## Installing the SDK ### Carthage **Step 1**: Add to your `Cartfile` ``` git "https://github.com/box/box-ios-sdk.git" ~> 5.0 ``` **Step 2**: Update dependencies ``` $ carthage update --use-xcframeworks --platform iOS ``` **Step 3**: Drag the built xcframework from Carthage/Build into your project. For more detailed instructions, please see the [official documentation for Carthage](https://github.com/Carthage/Carthage#if-youre-building-for-ios-tvos-or-watchos). ### CocoaPods **Step 1**: Add to your `Podfile` ``` pod 'BoxSDK', '~> 5.0' ``` **Step 2**: Install pod by running the following command in the directory with the `Podfile` ``` $ pod install ``` For more detailed instructions, please see the [official documentation for Cocoapods](https://guides.cocoapods.org/using/using-cocoapods.html). ### Swift Package Manager #### Importing BoxSDK into Project **Step 1**: Click on Xcode project file **Step 2**: Click on Swift Packages and click on the plus to add a package **Step 3**: Enter the following repository url `https://github.com/box/box-ios-sdk.git` and click next **Step 4**: Leave the default settings to get the most recent release and click next to finish importing The process should look like below: #### Adding BoxSDK as a Dependency For detailed instructions, please see the [official documentation for SPM](https://swift.org/package-manager/). ## Getting Started To get started with the SDK, get a Developer Token from the Configuration page of your app in the [Box Developer Console](https://app.box.com/developers/console). You can use this token to make test calls for your own Box account. ``` import BoxSDK let client = BoxSDK.getClient(token: "YOUR_DEVELOPER_TOKEN") client.users.getCurrentUser() { result in switch result { case let .error(error): print("Error: \(error)") case let .success(user): print("\(user.name) (\(user.login)) is logged in") } } ``` The usage docs that show how to make calls to the Box API with the SDK can be found [here](https://github.com/box/box-ios-sdk/tree/main/BoxSDK/docs/usage). The Jazzy docs that show class, method, variable, etc definitions can be found [here](https://opensource.box.com/box-ios-sdk/). ## Sample Apps ### OAuth2 Sample App A sample app using OAuth2 Authentication can be found in the repository [here](https://github.com/box/box-ios-sdk/tree/main/BoxSDK/SampleApps/OAuth2SampleApp). This app demonstrates how to use the SDK to make calls, and can be run directly by entering your own credentials to log in. To execute the sample app: **Step 1**: Run carthage ``` $ cd SampleApps/OAuth2SampleApp $ carthage update --use-xcframeworks --platform iOS ``` **Step 2**: Open Xcode Project File ``` $ open OAuth2SampleApp.xcodeproj ``` **Step 3**: Insert your client ID and client secret First, find your OAuth2 app's client ID and secret from the [Box Developer Console](https://app.box.com/developers/console). Then, add these values to the sample app in the `Constants.swift` file in the sample app: ``` static let clientId = "YOUR CLIENT ID GOES HERE" static let clientSecret = "YOUR CLIENT SECRET GOES HERE" ``` **Step 4**: Set redirect URL Using the same client ID from the previous step, set the redirect URL for your application in the [Box Developer Console](https://app.box.com/developers/console) to `boxsdk-<<YOUR CLIENT ID>>://boxsdkoauth2redirect`, where `<<YOUR CLIENT ID>>` is replaced with your client ID. For example, if your client ID were `vvxff7v61xi7gqveejo8jh9d2z9xhox5` the redirect URL should be `boxsdk-vvxff7v61xi7gqveejo8jh9d2z9xhox5://boxsdkoauth2redirect` **Step 5**: Run the sample app ### JWT Auth Sample App A sample app using JWT Authentication can be found in the repository [here](https://github.com/box/box-ios-sdk/tree/main/BoxSDK/SampleApps/JWTSampleApp). This app demonstrates how to set up JWT authentication with a remote authorization service, and will not run until you provide the code to retrieve tokens. To execute the sample app: **Step 1**: Run carthage ``` $ cd SampleApps/JWTSampleApp $ carthage update --use-xcframeworks --platform iOS ``` **Step 2**: Open Xcode Project File ``` $ open JWTSampleApp.xcodeproj ``` **Step 3**: Insert your client ID and client secret First, find your OAuth2 app's client ID and secret from the [Box Developer Console](https://app.box.com/developers/console). Then, add these values to the sample app in the `Constants.swift` file in the sample app: ``` static let clientId = "YOUR CLIENT ID GOES HERE" static let clientSecret = "YOUR CLIENT SECRET GOES HERE" ``` **Step 4**: Add code for retrieving access tokens In the `ViewController.swift` file in the sample app, edit the `obtainJWTTokenFromExternalSources()` method: ``` func obtainJWTTokenFromExternalSources() -> DelegatedAuthClosure { return { uniqueID, completion in #error("Obtain a JWT Token from your own service or a Developer Token for your app in the Box Developer Console at https://app.box.com/developers/console and return it in the completion.") // The code below is an example implementation of the delegate function // Please provide your own implementation // ... } } ``` **Step 5**: Run the sample app ## FIPS 140-2 Compliance The Box iOS SDK uses the CommonCrypto library, which relies on Apple's corecrypto cryptographic module. This module has undergone multiple validations by the Cryptographic Module Validation Program (CMVP) and is confirmed to be compliant with FIPS 140-2 standards. For further information, please refer to [Apple's security certification](https://support.apple.com/en-gb/guide/certifications/apc30d0ed034/web) and [iOS security certifications](https://support.apple.com/en-gb/guide/certifications/apc3fa917cb49/1/web/1.0). ## Versions We use a modified version of [Semantic Versioning](https://semver.org/) for all changes. See [version strategy](https://ja.developer.box.com/d64027e54d383b70ba5ad7e1f71c646b/VERSIONS.md) for details which is effective from 30 July 2022. ### Supported Version Only the current MAJOR version of SDK is supported. New features, functionality, bug fixes, and security updates will only be added to the current MAJOR version. A current release is on the leading edge of our SDK development, and is intended for customers who are in active development and want the latest and greatest features. Instead of stating a release date for a new feature, we set a fixed minor or patch release cadence of maximum 2-3 months (while we may release more often). At the same time, there is no schedule for major or breaking release. Instead, we will communicate one quarter in advance the upcoming breaking change to allow customers to plan for the upgrade. We always recommend that all users run the latest available minor release for whatever major version is in use. We highly recommend upgrading to the latest SDK major release at the earliest convenient time and before the EOL date. ### Version schedule | Version | Supported Environments | State | First Release | EOL/Terminated | | --- | --- | --- | --- | --- | | 5 | iOS 11.0+ / Mac OS X 10.13+ / tvOS 11.0+ / watchOS 4.0+ | Supported | 28 Oct 2021 | TBD | | 4 | | EOL | 13 Feb 2020 | 28 Oct 2021 | | 3 | | EOL | 20 Nov 2019 | 13 Feb 2020 | ## Copyright and License Copyright 2019 Box, Inc. All rights reserved. Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at [http://www.apache.org/licenses/LICENSE-2.0](http://www.apache.org/licenses/LICENSE-2.0) Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. --- ### Box Java SDK **Type:** page | **Section:** Additional Resources Box Java SDK Project Status Platform License Build main Coverage The Box Java SDK for interacting with the Box Content API. Latest Release… # Box Java SDK [](http://opensource.box.com/badges) [](https://raw.githubusercontent.com/box/box-java-sdk/main/LICENSE) [](https://github.com/box/box-java-sdk/actions/workflows/build-main.yml) [](https://coveralls.io/github/box/box-java-sdk?branch=main) The Box Java SDK for interacting with the [Box Content API](https://developers.box.com/docs/). ## Latest Release Latest release can be found [here](https://github.com/box/box-java-sdk/tree/v4.16.3). ## Upgrades You can read about how to migrate to the 4 version [here](doc/upgrades/3.x.x%20to%204.x.x.md). ## Versions We use a modified version of [Semantic Versioning](https://semver.org/) for all changes. See [version strategy](https://ja.developer.box.com/27a720aa01575cc19988821a8bfea27a/VERSIONS.md) for details which is effective from 30 July 2022. ### Supported Version Only the current MAJOR version of SDK is supported. New features, functionality, bug fixes, and security updates will only be added to the current MAJOR version. A current release is on the leading edge of our SDK development, and is intended for customers who are in active development and want the latest and greatest features. Instead of stating a release date for a new feature, we set a fixed minor or patch release cadence of maximum 2-3 months (while we may release more often). At the same time, there is no schedule for major or breaking release. Instead, we will communicate one quarter in advance the upcoming breaking change to allow customers to plan for the upgrade. We always recommend that all users run the latest available minor release for whatever major version is in use. We highly recommend upgrading to the latest SDK major release at the earliest convenient time and before the EOL date. ### Version schedule | Version | Supported Environments | State | First Release | EOL/Terminated | | --- | --- | --- | --- | --- | | 4 | Java 8 and up | Supported | 17 Jan 2023 | TBD | | 3 | Java 8 and up | EOL | 17 Jan 2022 | 17 Jan 2023 | | 2 | | EOL | 07 Jan 2016 | 17 Jan 2022 | | 1 | | EOL | 15 Apr 2015 | 07 Jan 2016 | ## Getting Started Getting Started Docs: [https://developer.box.com/guides/tooling/sdks/java/](https://developer.box.com/guides/tooling/sdks/java/) API Reference: [https://developer.box.com/reference/](https://developer.box.com/reference/) ## JVM The SDK can be obtained by adding it as a [maven dependency](http://opensource.box.com/box-java-sdk/), cloning the source into your project, or by downloading one of the precompiled JARs from the [releases page on GitHub](https://github.com/box/box-java-sdk/releases). If you are developing application for Android visit our [Android guide](https://ja.developer.box.com/a31234172e176f050227bd567f34bbaa/android.md) **IF YOU USE THE JAR, you'll also need to include several dependencies:** [minimal-json v0.9.5](https://github.com/ralfstx/minimal-json) Maven: `com.eclipsesource.minimal-json:minimal-json:0.9.5` [jose4j v0.9.4](https://bitbucket.org/b_c/jose4j/wiki/Home) Maven: `org.bitbucket.b_c:jose4j:0.9.4` [bouncycastle bcprov-jdk18on v1.78.1](https://mvnrepository.com/artifact/org.bouncycastle/bcprov-jdk18on/1.78.1) Maven: `org.bouncycastle:bcprov-jdk18on:1.78.1` [bouncycastle bcpkix-jdk18on v1.78.1](https://mvnrepository.com/artifact/org.bouncycastle/bcpkix-jdk18on/1.78.1) Maven: `org.bouncycastle:bcpkix-jdk18on:1.78.1` [Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files 7](http://www.oracle.com/technetwork/java/javase/downloads/jce-7-download-432124.html) If you don't install this, you'll get an exception about key length or exception about parsing PKCS private key for Box Developer Edition. This is not a Box thing, this is a U.S. Government requirement concerning strong encryption. The listed jar is for Oracle JRE. There might be other similar JARs for different JRE versions like the one below for IBM JDK [Java Cryptography Extension for IBM JDK](https://www14.software.ibm.com/webapp/iwm/web/preLogin.do?source=jcesdk) [okhttp v4.12.0](https://mvnrepository.com/artifact/com.squareup.okhttp3/okhttp/4.12.0) Maven: `com.squareup.okhttp3:okhttp:4.12.0` [okio-jvm v3.2.0](https://mvnrepository.com/artifact/com.squareup.okio/okio-jvm/3.2.0) Maven: `com.squareup.okio:okio-jvm:3.2.0` [kotlin-stdlib v1.6.20](https://mvnrepository.com/artifact/org.jetbrains.kotlin/kotlin-stdlib/1.6.20) Maven: `org.jetbrains.kotlin:kotlin-stdlib:1.6.20` [kotlin-stdlib-common v1.6.20](https://mvnrepository.com/artifact/org.jetbrains.kotlin/kotlin-stdlib-common/1.6.20) Maven: `org.jetbrains.kotlin:kotlin-stdlib-common:1.6.20` An app has to be authorized by the admin of the enterprise before these tests. It's always good to begin with the [Getting Started Section](https://developer.box.com/docs/setting-up-a-jwt-app) at Box's developer website. ## Android If you are developing application for Android visit our [Android guide](https://ja.developer.box.com/a31234172e176f050227bd567f34bbaa/android.md). ## Box Java SDK and other frameworks Box Java SDK utilizes the OkHttp client as its underlying component. This client is widely adopted by various frameworks, which can occasionally result in issues. We recommend considering library upgrades or excluding OkHttp from those frameworks or the software development kit (SDK) to determine if that resolves the problems. Typically, it is advisable to search for any reports or instances where others encountered similar issues when using the specific framework alongside an external OkHttp client. ## Quick Test **Following things work only if the app has been configured and authorized as mentioned [here](https://developer.box.com/docs/setting-up-a-jwt-app)** Here is a simple example of how to authenticate with the API using a developer token and then print the ID and name of each item in your root folder. ``` BoxAPIConnection api = new BoxAPIConnection("developer-token"); BoxFolder rootFolder = BoxFolder.getRootFolder(api); for (BoxItem.Info itemInfo : rootFolder) { System.out.format("[%s] %s\n", itemInfo.getID(), itemInfo.getName()); } ``` For more details on how to get started, check out the [overview guide](https://ja.developer.box.com/7b374e99189519aca65b064deffbf92d/overview.md). It has a short explanation of how the SDK works and how you can get started using it. ### Sample Projects Three sample projects can be found in `src/example`. #### Main This project will output your name and a list of the files and folders in your root directory. To run the project, first provide a developer token in `src/example/java/com/box/sdk/example/Main.java`. You can obtain a developer token from your application's [developer console](https://app.box.com/developers/services). ``` public final class Main { private static final String DEVELOPER_TOKEN = "<YOUR_DEVELOPER_TOKEN>"; // ... } ``` Then just invoke `gradle runExample` to run the Main example! ### Other projects Below projects need app configurations stored in JSON format in `config.json` file at location `src/example/config/`. This configuration file can be downloaded from your application's `Configuration` tab in the [developer console](https://app.box.com/developers/console) #### CreateAppUser This project will output the user id of enterprise admin and will create a new App User for the enterprise. To run the project, first provide the name of the app user in `src/example/java/com/box/sdk/example/CreateAppUser.java`. ``` public final class CreateAppUser { private static final String APP_USER_NAME = ""; private static final String EXTERNAL_APP_USER_ID = ""; // ... } ``` Then just invoke `gradle runCreateAppUser` to run the CreateAppUser example! Note: The JCE bundled with oracle JRE supports keys upto 128 bit length only. To use larger cryptographic keys, install [JCE Unlimited Strength Jurisdiction Policy Files](http://www.oracle.com/technetwork/java/javase/downloads/jce8-download-2133166.html). #### AccessAsAppUser This project will retrieve the information of the given App User and will list the files/folders under root folder. To run the project, first provide the Id of the app user in `src/example/java/com/box/sdk/example/CreateAppUser.java`. ``` public final class AccessAsAppUser { private static final String USER_ID = ""; // ... } ``` Then just invoke `gradle runAccessAsAppUser` to run the AccessAsAppUser example! Note: The JCE bundled with oracle JRE supports keys upto 128 bit length only. To use larger cryptographic keys, install [JCE Unlimited Strength Jurisdiction Policy Files](http://www.oracle.com/technetwork/java/javase/downloads/jce8-download-2133166.html). #### BoxDeveloperEditionAPIConnectionAsEnterpriseUser This example shows how to get tokens for an enterprise user, say admin of the enterprise and do actions on behalf of admin. To run the project, follow below steps Turn on `Enterprise` in `Application Access` section in Developer Console for the app Turn on `Generate User Access Tokens` in `Advanced Features` section in Developer Console for the app Provide the Id of the admin user (or any enterprise user) in `src/example/java/com/box/sdk/example/BoxDeveloperEditionAPIConnectionAsEnterpriseUser.java`. ``` public final class BoxDeveloperEditionAPIConnectionAsEnterpriseUser { private static final String USER_ID = ""; // ... Reader reader = new FileReader("src/example/config/config.json"); BoxConfig boxConfig = BoxConfig.readFrom(reader); IAccessTokenCache accessTokenCache = new InMemoryLRUAccessTokenCache(10); BoxDeveloperEditionAPIConnection api = new BoxDeveloperEditionAPIConnection( USER_ID, DeveloperEditionEntityType.USER, boxConfig, accessTokenCache ); } ``` ## Compatibility The Box Java SDK is compatible with Java 8 and up. ## Compression Support The SDK supports both gzip and zstd compression for API requests. Compression is handled automatically based on server capabilities. ## Building The SDK uses Gradle for its build system. SDK comes with Gradle wrapper. Running `./gradlew build` from the root of the repository will compile, lint, and test the SDK. ``` $ ./gradlew build ``` The SDK also includes integration tests which make real API calls, and therefore are run separately from unit tests. Integration tests should be run against a test account since they create and delete data. To run the integration tests, remove the `.template` extension from `src/test/config/config.properties.template` and fill in your test account's information. Then run: ``` $ ./gradlew integrationTest ``` ## Documentation You can find guides and tutorials in the `doc` directory. - [BUILD ON BOX PLATFORM](https://developer.box.com/guides/getting-started/) - [Javadocs](http://box.github.io/box-java-sdk/javadoc/com/box/sdk/package-summary.html) - [Overview](https://github.com/box/box-java-sdk/blob/v4.16.3/doc/overview.md) - [Configuration](https://github.com/box/box-java-sdk/blob/v4.16.3/doc/configuration.md) - [Logging](https://github.com/box/box-java-sdk/blob/v4.16.3/doc/logging.md) - [Authentication](https://github.com/box/box-java-sdk/blob/v4.16.3/doc/authentication.md) - [Files](https://github.com/box/box-java-sdk/blob/v4.16.3/doc/files.md) - [Folders](https://github.com/box/box-java-sdk/blob/v4.16.3/doc/folders.md) - [Comments](https://github.com/box/box-java-sdk/blob/v4.16.3/doc/comments.md) - [Collaborations](https://github.com/box/box-java-sdk/blob/v4.16.3/doc/collaborations.md) - [Collaboration Allowlists](https://github.com/box/box-java-sdk/blob/v4.16.3/doc/collaboration_allowlists.md) - [Events](https://github.com/box/box-java-sdk/blob/v4.16.3/doc/events.md) - [Search](https://github.com/box/box-java-sdk/blob/v4.16.3/doc/search.md) - [Users](https://github.com/box/box-java-sdk/blob/v4.16.3/doc/users.md) - [Groups](https://github.com/box/box-java-sdk/blob/v4.16.3/doc/groups.md) - [Tasks](https://github.com/box/box-java-sdk/blob/v4.16.3/doc/tasks.md) - [Trash](https://github.com/box/box-java-sdk/blob/v4.16.3/doc/trash.md) - [Collections](https://github.com/box/box-java-sdk/blob/v4.16.3/doc/collections.md) - [Devices](https://github.com/box/box-java-sdk/blob/v4.16.3/doc/devices.md) - [Retention Policies](https://github.com/box/box-java-sdk/blob/v4.16.3/doc/retention_policies.md) - [Legal Holds Policy](https://github.com/box/box-java-sdk/blob/v4.16.3/doc/legal_holds.md) - [Watermarking](https://github.com/box/box-java-sdk/blob/v4.16.3/doc/watermarking.md) - [Webhooks](https://github.com/box/box-java-sdk/blob/v4.16.3/doc/webhooks.md) - [Web Links](https://github.com/box/box-java-sdk/blob/v4.16.3/doc/weblinks.md) - [Metadata Templates](https://github.com/box/box-java-sdk/blob/v4.16.3/doc/metadata_template.md) - [Classifications](https://github.com/box/box-java-sdk/blob/v4.16.3/doc/classifications.md) - [Recent Items](https://github.com/box/box-java-sdk/blob/v4.16.3/doc/recent_items.md) Javadocs are generated when `gradle javadoc` is run and can be found in `build/doc/javadoc`. ## FIPS 140-2 Compliance To generate a Json Web Signature used for retrieving tokens in the JWT authentication method, the Box Java SDK decrypts an encrypted private key. For this purpose, Box Java SDK uses libraries (`org.bouncycastle:bcpkix-jdk18on:1.77` and `org.bouncycastle:bcprov-jdk18on:1.77`) that are NOT compatible with FIPS 140-2 validated cryptographic library (`org.bouncycastle:bc-fips`). There are two ways of ensuring that decryption operation is FIPS-compiant. 1. You can provide a custom implementation of the `IPrivateKeyDecryptor` interface, which performs the decryption operation using FIPS-certified library of your choice. The interface requires the implementation of just one method: ``` PrivateKey decryptPrivateKey(String encryptedPrivateKey, String passphrase); ``` After implementing the custom decryptor, you need to set your custom decryptor class in the Box Config. Below is an example of setting up a `BoxDeveloperEditionAPIConnection` with a config file and the custom decryptor. ``` Reader reader = new FileReader(JWT_CONFIG_PATH); BoxConfig boxConfig = BoxConfig.readFrom(reader); boxConfig.setPrivateKeyDecryptor(customDecryptor) BoxDeveloperEditionAPIConnection api = BoxDeveloperEditionAPIConnection.getAppEnterpriseConnection(boxConfig); ``` 1. Alternative method is to override the Bouncy Castle libraries to the v.1.57 version, which are compatible with the FIPS 140-2 validated cryptographic library (`org.bouncycastle:bc-fips`). NOTE: This solution is not recommended as Bouncy Castle v.1.57 has some moderate vulnerabilities reported against those versions, including: - [CVE-2020-26939](https://github.com/advisories/GHSA-72m5-fvvv-55m6) - Observable Differences in Behavior to Error Inputs in Bouncy Castle - [CVE-2020-15522](https://github.com/advisories/GHSA-6xx3-rg99-gc3p) - Timing based private key exposure in Bouncy Castle Furthermore,using Bouncy Castle v.1.57 may lead to [Bouncycastle BadPaddingException for JWT auth](#bouncycastle-badPaddingException-for-jWT-auth). Gradle example ``` implementation('com.box:box-java-sdk:x.y.z') { exclude group: 'org.bouncycastle', module: 'bcprov-jdk15on' exclude group: 'org.bouncycastle', module: 'bcpkix-jdk15on' } runtimeOnly('org.bouncycastle:bcprov-jdk15on:1.57') runtimeOnly('org.bouncycastle:bcpkix-jdk15on:1.57') ``` Maven example: ``` <dependencies> <dependency> <groupId>com.box</groupId> <artifactId>box-java-sdk</artifactId> <version>x.y.z</version> <scope>compile</scope> <exclusions> <exclusion> <groupId>org.bouncycastle</groupId> <artifactId>bcprov-jdk15on</artifactId> </exclusion> <exclusion> <groupId>org.bouncycastle</groupId> <artifactId>bcpkix-jdk15on</artifactId> </exclusion> </exclusions> </dependency> <dependency> <groupId>org.bouncycastle</groupId> <artifactId>bcprov-jdk15on</artifactId> <version>1.57</version> <scope>runtime</scope> </dependency> <dependency> <groupId>org.bouncycastle</groupId> <artifactId>bcpkix-jdk15on</artifactId> <version>1.57</version> <scope>runtime</scope> </dependency> </dependencies> ``` ### Bouncycastle BadPaddingException for JWT auth As of October 2023, RSA keypairs generated on the Developer Console (refer to the [Generate a keypair guide](https://developer.box.com/guides/authentication/jwt/jwt-setup/#generate-a-keypair-recommended)) are no longer compatible with Bouncy Castle version 1.57, which was utilized in the Box Java SDK up to v4.6.1. Attempting to use a JWT configuration downloaded from the Developer Console results in a `javax.crypto.BadPaddingException: pad block corrupted` error. Prossible solutions: 1. Upgrade to the v4.7.0 of Box Java SDK, which uses newer version of the Bouncy Castle library. (recommended) Manually generate a keypair using OpenSSL version 1.0.x and add the Public Key to the Developer Console. The [manually add keypair guide](https://developer.box.com/guides/authentication/jwt/jwt-setup/#manually-add-keypair) provides assistance in this process. ## Copyright and License Copyright 2019 Box, Inc. All rights reserved. Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at [http://www.apache.org/licenses/LICENSE-2.0](http://www.apache.org/licenses/LICENSE-2.0) Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. --- ### Box Platform **Type:** page | **Category:** Box Platform | **Section:** Additional Resources Box Platform 構築を開始Box Platform ユーザーを管理Box Platform エクスペリエンスを構築Box Platform アプリを統合Box Platform Box製品を最大限利用するために役立つすべての開発者向けリソース Box Platform… # Box Platform 構築を開始**Box Platform** ユーザーを管理**Box Platform** エクスペリエンスを構築**Box Platform** アプリを統合**Box Platform** Box製品を最大限利用するために役立つすべての開発者向けリソース Box Platformを初めて使用する場合は、どのように始めればよいですか? こちらにまとめました。以下の手順に従って、新しいアプリケーションを作成したり、Box Platformの機能を確認したりしましょう。 Box Platformは、さまざまなユーザータイプを必要とする可能性がある多くのユースケースに対応します。ユーザータイプの違いについては詳細を確認してください。 アプリケーションを作成する際に、いくつかの種類から選択できます。こちらのガイドを読んで、ニーズに最適なものを確認してください。 Box Platformでは、OAuth 2.0、JSONウェブトークン (JWT)、クライアント資格情報、およびアプリトークン認証がサポートされています。詳細を確認し、アプリに適用する方法を選択してください。 これで、アプリケーションの作成を開始できるようになりました。開発者コンソールを起動して、お好みのアプリケーションを作成してください。 アプリの使用を開始するために満たすべき承認の要件を確認してください。 最後に、APIリファレンス、SDK、Box CLI、Postmanコレクション、Box UI Elementsなど、Boxの開発者向けツールキットを確認します。 SDKやツール別に見る Box Platformを使用した開発は、SDK、Box CLI、Postmanコレクション、フロントエンドUI Elementなどを使用すると簡単です。 *Box APIリファレンス* *box-python-sdk-gen* *box-java-sdk* *box-typescript-sdk-gen* *box-dotnet-sdk-gen* *box-ios-sdk* *box-swift-sdk-gen* *Box Postmanコレクション* *box-cli* *box-ui-elements* *Box Embed* 詳細を表示 Box Platformのその他のコンセプト さらに詳しく知りたい場合は、以下のガイドを使用すると、Box Platformの仕組みに関する補足情報を確認して、理解を広げ、Platformアプリケーションを改善できます。 Box APIを使用すると、ファイルをアプリケーションのサーバーにダウンロードすることも、エンドユーザーがブラウザで直接ダウンロードすることもできます。 ファイルアップロードAPIを使用して直接ファイルをアップロードすることも、大きなファイルには分割アップロードAPIを使用することもできます。 一般的なエラーのリファレンスを参照して、リクエスト処理の問題を伝えるために使用されるHTTPステータスコードの詳細を確認できます。 メタデータによって、ユーザーやアプリケーションがどのようにファイルやフォルダに関連付けられたカスタムデータを定義、格納できるかを確認します。 Webhookを使用すると、Boxコンテンツのイベントを監視し、イベントの発生時に任意のURLへの通知を受け取ることができます。 ファイルコンテンツ検索クエリを使用して、Box内の関連コンテンツを探すことができます。Box検索APIは、すべてのBox SDKとCLIでサポートされています。 BoxとSalesforceを統合しましょう。最近、Boxでは、ローコード/ノーコードのソリューションであるSalesforceフローのサポートを開始しました。 すべてのガイドを参照 その他のリソース **Source:** [https://ja.developer.box.com/](https://ja.developer.box.com/) --- ### Box Python SDK Gen **Type:** page | **Section:** Additional Resources Box Python SDK Gen Project Status build PyPI version image Platform Coverage We are excited to introduce the stable release of the latest… # Box Python SDK Gen [](http://opensource.box.com/badges) [](https://badge.fury.io/py/box-sdk-gen) [](https://pypi.python.org/pypi/box-sdk-gen) [](https://coveralls.io/github/box/box-python-sdk-gen?branch=main) We are excited to introduce the stable release of the latest generation of Box Python SDK, designed to elevate the developer experience and streamline your integration with the Box Content Cloud. With this SDK, you’ll have access to: 1. Full API Support: The new generation of Box SDKs empowers developers with complete coverage of the Box API ecosystem. You can now access all the latest features and functionalities offered by Box, allowing you to build even more sophisticated and feature-rich applications. 2. Rapid API Updates: Say goodbye to waiting for new Box APIs to be incorporated into the SDK. With our new auto-generation development approach, we can now add new Box APIs to the SDK at a much faster pace (in a matter of days). This means you can leverage the most up-to-date features in your applications without delay. 3. Embedded Documentation: We understand that easy access to information is crucial for developers. With our new approach, we have included comprehensive documentation for all objects and parameters directly in the source code of the SDK. This means you no longer need to look up this information on the developer portal, saving you time and streamlining your development process. 4. Enhanced Convenience Methods: Our commitment to enhancing your development experience continues with the introduction of convenience methods. These methods cover various aspects such as chunk uploads, classification, and much more. 5. Seamless Start: The new SDKs integrate essential functionalities like authentication, automatic retries with exponential backoff, exception handling, request cancellation, and type checking, enabling you to focus solely on your application's business logic. Embrace the new generation of Box SDKs and unlock the full potential of the Box Content Cloud. # Table of contents - [Box Python SDK Gen](#box-python-sdk-gen) - [Table of contents](#table-of-contents) - [Installing](#installing) - [Getting Started](#getting-started) - [Documentation](#documentation) - [Upgrades](#upgrades) [Integration Tests](#integration-tests) [Running integration tests locally](#running-integration-tests-locally) - [Create Platform Application](#create-platform-application) - [Export configuration](#export-configuration) - [Running tests](#running-tests) [Questions, Bugs, and Feature Requests?](#questions-bugs-and-feature-requests) [Copyright and License](#copyright-and-license) # Installing ``` pip install box-sdk-gen ``` This is autogenerated Box SDK version. Supported Python versions are Python 3.8 and above. To install also extra dependencies required for JWT authentication, use command: ``` pip install "box-sdk-gen[jwt]" ``` # Getting Started To get started with the SDK, get a Developer Token from the Configuration page of your app in the Box Developer Console. You can use this token to make test calls for your own Box account. The SDK provides an `BoxDeveloperTokenAuth` class, which allows you to authenticate using your Developer Token. Use instance of `BoxDeveloperTokenAuth` to initialize `BoxClient` object. Using `BoxClient` object you can access managers, which allow you to perform some operations on your Box account. The example below demonstrates how to authenticate with Developer Token and print names of all items inside a root folder. ``` from box_sdk_gen import BoxClient, BoxDeveloperTokenAuth def main(token: str): auth: BoxDeveloperTokenAuth = BoxDeveloperTokenAuth(token=token) client: BoxClient = BoxClient(auth=auth) for item in client.folders.get_folder_items('0').entries: print(item.name) if __name__ == '__main__': main('INSERT YOUR DEVELOPER TOKEN HERE') ``` # Documentation Browse the [docs](https://ja.developer.box.com/d3a5e9bde0b74dc93b9f940067935450/README.md) or see [API Reference](https://developer.box.com/reference/) for more information. # Upgrades Upgrading from our legacy SDKs to the new generation SDKs is a straightforward process. See our [migration guide](https://ja.developer.box.com/f56d27ebd4341fc1865ef46b28548d3e/migration-guide.md) and [changelog](https://ja.developer.box.com/7daad47414f02b4f709aff16ad114fdb/CHANGELOG.md) for more information. # Integration Tests ## Running integration tests locally ### Create Platform Application To run integration tests locally you will need a `Custom App` created in the Box Developer Console with `Server Authentication (with JWT)` selected as authentication method. Once created you can edit properties of the application: - In section `App Access Level` select `App + Enterprise Access`. You can enable all `Application Scopes`. - In section `Advanced Features` enable `Make API calls using the as-user header` and `Generate user access tokens`. Now select `Authorization` and submit application to be reviewed by account admin. ### Export configuration Select `Configuration` tab and in the bottom in the section `App Settings` download your app configuration settings as JSON. 1. Encode configuration file to Base64, e.g. using command: `base64 -i path_to_json_file` 2. Set environment variable: `JWT_CONFIG_BASE_64` with base64 encoded jwt configuration file 3. Set environment variable: `BOX_FILE_REQUEST_ID` with ID of file request already created in the user account, `BOX_EXTERNAL_USER_EMAIL` with email of free external user which not belongs to any enterprise. 4. Set environment variable: `WORKFLOW_FOLDER_ID` with the ID of the Relay workflow that deletes the file that triggered the workflow. The workflow should have a manual start to be able to start it from the API. 5. Set environment variable: `APP_ITEM_ASSOCIATION_FILE_ID` to the ID of the file with associated app item and `APP_ITEM_ASSOCIATION_FOLDER_ID` to the ID of the folder with associated app item. 6. Set environment variable: `APP_ITEM_SHARED_LINK` to the shared link associated with app item. 7. Set environment variable: `SLACK_AUTOMATION_USER_ID` to the ID of the user responsible for the Slack automation, `SLACK_ORG_ID` to the ID of the Slack organization and `SLACK_PARTNER_ITEM_ID` to the ID of the Slack partner item. ### Running tests To run integration tests locally: 1. `pip install -r requirements-test.txt` 2. `pytest` # Questions, Bugs, and Feature Requests? Need to contact us directly? Browse the issues tickets! Or, if that doesn't work, file a new one and we will get back to you. If you have general questions about the Box API, you can post to the [Box Developer Forum](https://forum.box.com/). # Copyright and License Copyright 2023 Box, Inc. All rights reserved. Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at [http://www.apache.org/licenses/LICENSE-2.0](http://www.apache.org/licenses/LICENSE-2.0) Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. --- ### Box TypeScript SDK Gen **Type:** page | **Section:** Additional Resources Box TypeScript SDK Gen Project Status build npm version image Platform Coverage We are excited to introduce the stable release of the latest… # Box TypeScript SDK Gen [](http://opensource.box.com/badges) [](https://badge.fury.io/js/box-typescript-sdk-gen) [](https://badge.fury.io/js/box-typescript-sdk-gen) [](https://coveralls.io/github/box/box-typescript-sdk-gen?branch=main) We are excited to introduce the stable release of the latest generation of Box TypeScript SDK, designed to elevate the developer experience and streamline your integration with the Box Content Cloud. With this SDK, you’ll have access to: 1. Full API Support: The new generation of Box SDKs empowers developers with complete coverage of the Box API ecosystem. You can now access all the latest features and functionalities offered by Box, allowing you to build even more sophisticated and feature-rich applications. 2. Rapid API Updates: Say goodbye to waiting for new Box APIs to be incorporated into the SDK. With our new auto-generation development approach, we can now add new Box APIs to the SDK at a much faster pace (in a matter of days). This means you can leverage the most up-to-date features in your applications without delay. 3. Embedded Documentation: We understand that easy access to information is crucial for developers. With our new approach, we have included comprehensive documentation for all objects and parameters directly in the source code of the SDK. This means you no longer need to look up this information on the developer portal, saving you time and streamlining your development process. 4. Enhanced Convenience Methods: Our commitment to enhancing your development experience continues with the introduction of convenience methods. These methods cover various aspects such as chunk uploads, classification, and much more. 5. Seamless Start: The new SDKs integrate essential functionalities like authentication, automatic retries with exponential backoff, exception handling, request cancellation, and type checking, enabling you to focus solely on your application's business logic. Embrace the new generation of Box SDKs and unlock the full potential of the Box Content Cloud. # Table of contents - [Box TypeScript SDK Gen](#box-typescript-sdk-gen) - [Table of contents](#table-of-contents) - [Installing](#installing) - [Getting Started](#getting-started) - [Documentation](#documentation) - [Browser Support](#browser-support) - [Upgrades](#upgrades) [Integration Tests](#integration-tests) [Running integration tests locally](#running-integration-tests-locally) - [Create Platform Application](#create-platform-application) - [Export configuration](#export-configuration) [Questions, Bugs, and Feature Requests?](#questions-bugs-and-feature-requests) [Copyright and License](#copyright-and-license) # Installing ``` npm install box-typescript-sdk-gen ``` If you use yarn, please do this instead: ``` yarn add box-typescript-sdk-gen ``` This is autogenerated Box SDK version. # Getting Started To get started with the SDK, get a Developer Token from the Configuration page of your app in the Box Developer Console. You can use this token to make test calls for your own Box account. The SDK provides an `DeveloperTokenAuth` class, which allows you to authenticate using your Developer Token. Use instance of `DeveloperTokenAuth` to initialize `Client` object. Using `Client` object you can access managers, which allow you to perform some operations on your Box account. The example below demonstrates how to authenticate with Developer Token and print names of all items inside a root folder. ``` const { BoxClient, BoxDeveloperTokenAuth } = require('box-typescript-sdk-gen'); async function main(token) { let auth = new BoxDeveloperTokenAuth({ token }); let client = new BoxClient({ auth }); let entries = (await client.folders.getFolderItems('0')).entries; entries.forEach((entry) => console.log(entry)); } main('INSERT YOUR DEVELOPER TOKEN HERE'); ``` In order to use in browser make sure you include the `lib/bundle.js` file and then you can access the classes like so: ``` const { BoxClient, BoxDeveloperTokenAuth } = window['box-typescript-sdk-gen']; ``` See example.html for an example website using this SDK. To run the example locally: 1. Start the local server by running `npx serve -p 3000` in the project directory. 2. Make sure `http://localhost:3000` is allowlisted in CORS Domains of your application. 3. Head over to `http://localhost:3000/example.html`. 4. Provide a fresh Developer Token to the dialog window that shows up upon running the example. 5. Make sure that you get an alert message that includes your user name. # Documentation Browse the [docs](https://ja.developer.box.com/677ee1162df8d3617dad0e717cd71eff/README.md) or see [API Reference](https://developer.box.com/reference/) for more information. # Browser Support This SDK works in modern browsers that support ES6+ features. It seamlessly integrates with frontend frameworks like ReactJS, Angular, and NextJS. Check out our example below: - [React Sample App](https://github.com/box-community/box-ts-sdk-react) # Upgrades Upgrading from our legacy SDKs to the new generation SDKs is a straightforward process. See our [migration guide](https://ja.developer.box.com/c1cfc600776a3c86c94118d743d3765e/migration-guide.md) and [changelog](https://ja.developer.box.com/c81473c7d1440103f9e94f839bfcaa23/CHANGELOG.md) for more information. # Integration Tests ## Running integration tests locally ### Create Platform Application To run integration tests locally you will need a `Custom App` created in the Box Developer Console with `Server Authentication (with JWT)` selected as authentication method. Once created you can edit properties of the application: - In section `App Access Level` select `App + Enterprise Access`. You can enable all `Application Scopes`. - In section `Advanced Features` enable `Make API calls using the as-user header` and `Generate user access tokens`. Now select `Authorization` and submit application to be reviewed by account admin. ### Export configuration Select `Configuration` tab and in the bottom in the section `App Settings` download your app configuration settings as JSON. 1. Encode configuration file to Base64, e.g. using command: `base64 -i path_to_json_file` 2. Set environment variable: `JWT_CONFIG_BASE_64` with base64 encoded jwt configuration file 3. Set environment variable: `BOX_FILE_REQUEST_ID` with ID of file request already created in the user account, `BOX_EXTERNAL_USER_EMAIL` with email of free external user which not belongs to any enterprise. 4. Set environment variable: `WORKFLOW_FOLDER_ID` with the ID of the Relay workflow that deletes the file that triggered the workflow. The workflow should have a manual start to be able to start it from the API. 5. Set environment variable: `APP_ITEM_ASSOCIATION_FILE_ID` to the ID of the file with associated app item and `APP_ITEM_ASSOCIATION_FOLDER_ID` to the ID of the folder with associated app item. 6. Set environment variable: `APP_ITEM_SHARED_LINK` to the shared link associated with app item. 7. Set environment variable: `SLACK_AUTOMATION_USER_ID` to the ID of the user responsible for the Slack automation, `SLACK_ORG_ID` to the ID of the Slack organization and `SLACK_PARTNER_ITEM_ID` to the ID of the Slack partner item. # Questions, Bugs, and Feature Requests? Need to contact us directly? Browse the issues tickets! Or, if that doesn't work, file a new one and we will get back to you. If you have general questions about the Box API, you can post to the [Box Developer Forum](https://forum.box.com/). # Copyright and License Copyright 2023 Box, Inc. All rights reserved. Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at [http://www.apache.org/licenses/LICENSE-2.0](http://www.apache.org/licenses/LICENSE-2.0) Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. --- ### Box TypeScript SDK Gen Browser Test Runner **Type:** page | **Section:** Additional Resources Box TypeScript SDK Gen Browser Test Runner A browser-based test runner for Box TypeScript SDK, built with Next.js and Cypress. Features Run… # Box TypeScript SDK Gen Browser Test Runner A browser-based test runner for Box TypeScript SDK, built with Next.js and Cypress. ## Features - Run Box TypeScript SDK Gen tests in the browser in headless mode. ## Prerequisites - Node.js (v18 or higher) - Chrome or Firefox browser ## Installation 1. This project comes together with the Box TypeScript SDK Gen repository. To run the test runner, you need have the Box TypeScript SDK Gen repository checked out in parent directory and build it. 2. Setup the Environment Variables align with `sdkTest.config.mjs` file. 3. Install dependencies: ``` npm install ``` 1. Run the test runner: ``` npm run cypress:run:all ``` ## Configuration Inside `sdkTest.config.mjs` file we have a list of tests that we need to skip as it's not supported in the browser. --- ### Box UI Elements **Type:** page | **Category:** Box UI Elements | **Section:** Additional Resources Box UI Elements Box AI API agent configurator Choose from multiple AI models from leading providers, all accessible through a single, easy… # Box UI Elements Box AI API agent configurator Choose from multiple AI models from leading providers, all accessible through a single, easy-to-use platform. Customize Box AI API parameters and fine-tune LLM parameters. Build complex AI configurations with our intuitive form-based interface. See your JSON configuration update in real-time as you make changes. Copy configuration and paste it directly in your project. **Source:** [https://ja.developer.box.com/agent-configurator/](https://ja.developer.box.com/agent-configurator/) --- ### Changelog **Type:** page | **Section:** Additional Resources Changelog All notable changes to this project will be documented in this file. See standard-version for commit guidelines. 3.8.2 (2025-07-2… # Changelog All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines. ### 3.8.2 (2025-07-29) ### Bug Fixes - Bump `cypress/request` to resolve `CVE-2025-7783` in `form-data` ([#904](https://github.com/box/box-node-sdk/issues/904)) ([8e8d2da](https://github.com/box/box-node-sdk/commit/8e8d2da58ab42bdfb9e5a49ca25e9b9fc50e0d61)) ### 3.8.1 (2025-06-11) ### Bug Fixes - Use constant-time comparison for HMAC signatures ([#893](https://github.com/box/box-node-sdk/issues/893)) ([d819efe](https://github.com/box/box-node-sdk/commit/d819efe663a59fce53412fbe153a76dd346d4536)) ## 3.8.0 (2025-04-09) ### New Features and Enhancements - Support AI agent ([#887](https://github.com/box/box-node-sdk/issues/887)) ([5b109ad](https://github.com/box/box-node-sdk/commit/5b109adbd506510fc83b1c90af13b063ddefab37)) ### 3.7.1 (2024-08-06) ### Bug Fixes - add version to copy file options annotation ([#885](https://github.com/box/box-node-sdk/issues/885)) ([4f9312c](https://github.com/box/box-node-sdk/commit/4f9312c63138f8cf8e0a9e46a9e1345172dbdc6b)) ## 3.7.0 (2024-07-16) ### New Features and Enhancements - Support AI APIs ([#883](https://github.com/box/box-node-sdk/issues/883)) ([bb81e07](https://github.com/box/box-node-sdk/commit/bb81e074eb1017bd742c90159e6cf4e6ce9d9776)) ## 3.6.0 (2024-05-20) ### New Features and Enhancements - Transition to stable status ([#880](https://github.com/box/box-node-sdk/issues/880)) ([ae996ea](https://github.com/box/box-node-sdk/commit/ae996eafd9e34de99119a7780384b90758908313)) ### 3.5.1 (2024-05-02) ### Bug Fixes - Fix `options` parameter in metadata query method ([#878](https://github.com/box/box-node-sdk/issues/878)) ([7943420](https://github.com/box/box-node-sdk/commit/79434209c572cd77c329d6008cda9837a9dba411)) ## 3.5.0 (2024-02-19) ### New Features and Enhancements - Sign request group ([#870](https://github.com/box/box-node-sdk/issues/870)) ([11bf5d2](https://github.com/box/box-node-sdk/commit/11bf5d2db7e0cefc669aab99c8b65c632289ac46)) ### Bug Fixes - Bumped proxy-agent to 6.4.0 ([#874](https://github.com/box/box-node-sdk/issues/874)) ([55a8a0b](https://github.com/box/box-node-sdk/commit/55a8a0baebe151f4107fdbec0a1022e9534f88a4)) - Remove delete classification ([#869](https://github.com/box/box-node-sdk/issues/869)) ([22384ab](https://github.com/box/box-node-sdk/commit/22384abc3abbc35800cbcdea7c7eb9a452cc4859)) ### 3.4.2 (2023-11-08) ### Bug Fixes - Fix `proxy-agent` ([#867](https://github.com/box/box-node-sdk/issues/867)) ([3de7586](https://github.com/box/box-node-sdk/commit/3de7586e44dbb7c8e1bff8f34471964805c810f5)) ### 3.4.1 (2023-11-03) ### Bug Fixes - Update `proxy-agent` usage, drop support Node 12 ([#865](https://github.com/box/box-node-sdk/issues/865)) ([e229d3f](https://github.com/box/box-node-sdk/commit/e229d3f93de350c00768528a1c0d3a6ecfc697a9)) ## 3.4.0 (2023-11-03) ### New Features and Enhancements - Add request option to skip `PassThrough` ([#863](https://github.com/box/box-node-sdk/issues/863)) ([726db45](https://github.com/box/box-node-sdk/commit/726db45cfbb992e545fe2865283df63c898656ac)) ## 3.3.0 (2023-10-26) ### New Features and Enhancements - Replace `request` library with `@cypress/request` ([#860](https://github.com/box/box-node-sdk/issues/860)) ([d365ae8](https://github.com/box/box-node-sdk/commit/d365ae8368c549ecdceb7dd5b928904fd3c58978)) ### Bug Fixes - mark auth funs callbacks as optional ([#858](https://github.com/box/box-node-sdk/issues/858)) ([55f22fe](https://github.com/box/box-node-sdk/commit/55f22fec7d7d35e487f3fb51bc9bbd3e848842ab)) ### 3.2.1 (2023-10-06) ### Bug Fixes - Overrides tough-cookie dependency ([#852](https://github.com/box/box-node-sdk/issues/852)) ([99df873](https://github.com/box/box-node-sdk/commit/99df873e1a1dad4a0073d53b4ed57c0eeb859401)) ## 3.2.0 (2023-09-07) ### New Features and Enhancements - Support sign template ([#848](https://github.com/box/box-node-sdk/issues/848)) ([18d3413](https://github.com/box/box-node-sdk/commit/18d3413afeddf43c62dfd0caf1279e61c99b6b83)) ### 3.1.1 (2023-07-19) ## 3.1.0 (2023-06-01) ### New Features and Enhancements - Added support for integration mappings API ([#831](https://github.com/box/box-node-sdk/issues/831)) ([a525327](https://github.com/box/box-node-sdk/commit/a525327c1362628a0ffdb36cb4bf3346ca0e0153)) ### Bug Fixes - Correct types of `userId` and `groupId` for creating collaboration ([#833](https://github.com/box/box-node-sdk/issues/833)) ([f803ff8](https://github.com/box/box-node-sdk/commit/f803ff82330fd78a8dc4875452a21aab54686b2e)), closes [#832](https://github.com/box/box-node-sdk/issues/832) ## 3.0.0 (2023-05-23) The most important change in this release is **dropping support for Node versions below 12** and changing the **support environments from Node 12 to Node 16**. ### Breaking Changes - Removed `use_index` usage. ([#812](https://github.com/box/box-node-sdk/pull/812)) ([d56799a](https://github.com/box/box-node-sdk/commit/d56799a61f42265d7785f99e92a449c58d125aef)) - Removed deprecated `BoxClient.batch()` and `BoxClient.batchExec()` method. - Removed deprecated `CollaborationWhitelist` class, use `CollaborationAllowlist` instead. - Removed deprecated `CollaborationAllowlist.getWhitelistedDomain()` method, use `CollaborationAllowlist.getAllowlistedDomain()` instead. - Removed deprecated `CollaborationAllowlist.getAllWhitelistedDomains()` method, use `CollaborationAllowlist.getAllAllowlistedDomains()` instead. - Remove deprecated `Files.getThumbnail(fileID: string, options?: Record<string, any>, callback?: Function)` method, use `Files.getRepresentationContent( fileID, representationType, options, callback)` instead. Migration details can be found [here](https://github.com/box/box-node-sdk/blob/v3.0.0/docs/upgrade/2.x.x%20to%203.x.x.md) ### Dependency Upgrades - Bumped `jsonwebtoken` from 8.5.1 to 9.0.0. ([#802](https://github.com/box/box-node-sdk/pull/802)) ([5b1d4e9](https://github.com/box/box-node-sdk/pull/828/commits/5b1d4e9ec557c14c1d27695733cc0bcae49061cb)) - Bumped `vm2` from 3.9.11 to 3.9.19 ([#826](https://github.com/box/box-node-sdk/pull/826)) ([220df76](https://github.com/box/box-node-sdk/commit/220df765080bc27c91daed51ac46620f6bc8b9ed)) ## 2.10.0 (2023-05-11) ### New Features and Enhancements - Added support for ethical wall API ([#822](https://github.com/box/box-node-sdk/issues/822)) ([4814af3](https://github.com/box/box-node-sdk/commit/4814af35c1741fbfe3fa03f8f0412ade8b38dfcc)) - Added `name` and `signature_color` fields to `SignRequest` and `SignRequestCreateRequest` types and `login_required` field to `SignRequestCreateSigner` type ([#822](https://github.com/box/box-node-sdk/issues/822)) ([4814af3](https://github.com/box/box-node-sdk/commit/4814af35c1741fbfe3fa03f8f0412ade8b38dfcc)) ## 2.9.0 (2023-04-19) ### New Features and Enhancements - New fields in `retention-policy` and `retention-policy-assignment` ([#803](https://github.com/box/box-node-sdk/issues/803)) ([f14ba84](https://github.com/box/box-node-sdk/commit/f14ba84013985513854ad396581d085d1d4f0255)) ### Bug Fixes - return empty object when `tos` status is not present ([#797](https://github.com/box/box-node-sdk/issues/797)) ([12fd9b0](https://github.com/box/box-node-sdk/commit/12fd9b053707471722f53cd1760c8cf59451fe8d)) ### 2.8.1 (2023-01-05) ### Bug Fixes - Fix `getReadStream` delay reading ([#790](https://github.com/box/box-node-sdk/issues/790)) ([6bfc1ee](https://github.com/box/box-node-sdk/commit/6bfc1eebeb9a31606ff96127eeb1ad03d2f13d9c)) ## 2.8.0 (2022-12-21) ### New Features and Enhancements - Session termination ([#782](https://github.com/box/box-node-sdk/issues/782)) ([7fb56c6](https://github.com/box/box-node-sdk/commit/7fb56c625f8eb03e6a5354b67a0debfd9e4ad7c8)) ### 2.7.2 (2022-11-10) ### Bug Fixes - Add `fields` query parameter to file and folder update ([#776](https://github.com/box/box-node-sdk/issues/776)) ([a327deb](https://github.com/box/box-node-sdk/commit/a327debc83d98a4190a5a16cf848417ea5714db9)) ### 2.7.1 (2022-10-28) ### Bug Fixes - Export missing `RetentionType` ([#774](https://github.com/box/box-node-sdk/issues/774)) ([7e6b244](https://github.com/box/box-node-sdk/commit/7e6b244ba63d363ecc921be570140c9e1ed1d032)) ## 2.7.0 (2022-10-27) ### New Features and Enhancements - Add support for modifiable retention policies & enable deleting retention policy assignment ([#769](https://github.com/box/box-node-sdk/issues/769)) ([5e8c776](https://github.com/box/box-node-sdk/commit/5e8c776fc94e9dcf313cc15c96e42fbffaf36b74)) ## 2.6.0 (2022-09-23) ### New Features and Enhancements - Add `content_type`, `redirect_url` field to Sign Request ([#758](https://github.com/box/box-node-sdk/issues/758)) ([8abb9b6](https://github.com/box/box-node-sdk/commit/8abb9b602b13cd72c6c8de549d19756ae147b403)) - Add sign request webhook ([#760](https://github.com/box/box-node-sdk/issues/760)) ([e92d1ab](https://github.com/box/box-node-sdk/commit/e92d1abee5faf58166f4892d7b2e6bc3c6480ac6)) - Added support for Access Only Collaboration ([#759](https://github.com/box/box-node-sdk/issues/759)) ([dd8261f](https://github.com/box/box-node-sdk/commit/dd8261f970c207854058c3ed86ccabf9bec05ea8)) ## 2.5.0 (2022-08-09) ### New Features and Enhancements - Added support update and remove user avatar ([#744](https://github.com/box/box-node-sdk/issues/744)) ([aaf6175](https://github.com/box/box-node-sdk/commit/aaf617528de5c61e19cfb25e28fe77c01532b9fa)) ### Bug Fixes - Fix error while generate token using oauth ([#750](https://github.com/box/box-node-sdk/issues/750)) ([f826291](https://github.com/box/box-node-sdk/commit/f82629108a1af6c4d160de1976fd01fdf0d8dde3)), closes [#286](https://github.com/box/box-node-sdk/issues/286) - Fix lint error in test file ([#747](https://github.com/box/box-node-sdk/issues/747)) ([3b1e10d](https://github.com/box/box-node-sdk/commit/3b1e10d206aa88a8bf99989bb7ff85776a9864a4)) ## 2.4.0 (2022-07-13) ### New Features and Enhancements - Added support for file requests ([#742](https://github.com/box/box-node-sdk/issues/742)) ([30b2e76](https://github.com/box/box-node-sdk/commit/30b2e767c6c3af68e1463cc801914f9889dc593c)) - Added support of `admin_logs_streaming` stream type ([#740](https://github.com/box/box-node-sdk/issues/740)) ([406950a](https://github.com/box/box-node-sdk/commit/406950a03af54a022427e0532e889a61e0d25152)) ### Bug Fixes - properly handle client errors in streams ([#736](https://github.com/box/box-node-sdk/issues/736)) ([12378d6](https://github.com/box/box-node-sdk/commit/12378d6755c2e3cddcb79439cdcbbe8e1e61df13)) ## 2.3.0 (2022-04-28) ### New Features and Enhancements - Add `description` parameter to `uploadFile` methods ([#730](https://github.com/box/box-node-sdk/issues/730)) ([2596584](https://github.com/box/box-node-sdk/commit/2596584dffb44c1995c8b6b3faa67564f4d32499)) ### Bug Fixes - added missing `js-docs` on shared links ([#731](https://github.com/box/box-node-sdk/issues/731)) ([3554d41](https://github.com/box/box-node-sdk/commit/3554d41d9050e7a81224c35e3e2e257604a0b41b)) ## 2.2.0 (2022-04-20) ### New Features and Enhancements - editable shared links ([#722](https://github.com/box/box-node-sdk/issues/722)) ([f0c0135](https://github.com/box/box-node-sdk/commit/f0c0135511fde46144e6c496432104321af443f6)) ## 2.1.0 (2022-03-28) ### New Features and Enhancements - Client Credentials Grant authentication method ([#709](https://github.com/box/box-node-sdk/issues/709)) ([fbf4e80](https://github.com/box/box-node-sdk/commit/fbf4e80648821e38479b24bf489e7d222ae6c18f)) - Deprecating `index_name` when executing metadata query ([#686](https://github.com/box/box-node-sdk/issues/686)) ([e01cc65](https://github.com/box/box-node-sdk/commit/e01cc650e4e793955be543e93928ad82a3254492)) - **test:** add support for testing with Jest ([#676](https://github.com/box/box-node-sdk/issues/676)) ([1a11759](https://github.com/box/box-node-sdk/commit/1a11759db999510c69d6a27f7becd565620bb000)) ### Bug Fixes - Client Credentials Grant authentication method supports token down-scoping ([#710](https://github.com/box/box-node-sdk/issues/710)) ([730368f](https://github.com/box/box-node-sdk/commit/730368f410ff56e9a8c90feea2192b29c08df198)) - Fix JWT expiration field being float instead of integer ([#715](https://github.com/box/box-node-sdk/issues/715)) ([7e950f1](https://github.com/box/box-node-sdk/commit/7e950f1265a52ce251c42a186c8196089a9ed858)), closes [#713](https://github.com/box/box-node-sdk/issues/713) ## 2.0.0 (2021-09-29) ### ⚠ BREAKING CHANGES - Drop support for Node 6,7 ([#670](https://github.com/box/box-node-sdk/pull/670)) ### New Features and Enhancements: - Add support for is_external_collab_restricted User property ([#668](https://github.com/box/box-node-sdk/pull/668)) - Bump proxy-agent from 4.0.0 to 5.0.0 ([#664](https://github.com/box/box-node-sdk/pull/664)) ## 1.39.0 (2021-08-30) ### New Features and Enhancements: - Add support for Box Sign API ([#658](https://github.com/box/box-node-sdk/pull/658)) - Enhance TS Imports ([#656](https://github.com/box/box-node-sdk/pull/656)) ## 1.38.0 (2021-08-05) ### New Features and Enhancements: - Add sensitive-language event types for admin invites ([#648](https://github.com/box/box-node-sdk/pull/648)) - Use BetterDocs to adapt JSDocs to TypeScript ([#646](https://github.com/box/box-node-sdk/pull/646)) - Change ProxyAgent import to be dynamic ([#641](https://github.com/box/box-node-sdk/pull/641)) - New API for get files and file versions under retention ([#585](https://github.com/box/box-node-sdk/pull/585)) ### Bug Fixes: - Deeply freeze Config except Buffers and Readable streams ([#651](https://github.com/box/box-node-sdk/pull/651)) - Fix a typo in docs of src/managers/search.ts ([#649](https://github.com/box/box-node-sdk/pull/649)) - Update broken documentation link ([#647](https://github.com/box/box-node-sdk/pull/647)) - fix type annotations for exchangeToken functions ([#645](https://github.com/box/box-node-sdk/pull/645)) - Deprecate files getThumbnail API in favor of getRepresentationContent ([#627](https://github.com/box/box-node-sdk/pull/627)) ## 1.37.2 (2021-05-20) ### Bug Fixes: - Fix backwards compatibility issue by moving some TypeScript @types as direct dependencies ([#630](https://github.com/box/box-node-sdk/pull/630)) ## 1.37.1 (2021-05-19) ### Bug Fixes: - Insensitive language: replace whitelist with allowlist ([#625](https://github.com/box/box-node-sdk/pull/625)) ## 1.37.0 (2021-04-16) ### New Features and Enhancements: - Add support for copyInstanceOnItemCopy field for metadata templates ([#572](https://github.com/box/box-node-sdk/pull/572)) ### Bug Fixes: - Fix webhook signature validation ([#568](https://github.com/box/box-node-sdk/pull/568)) - Update dependencies to patch security vulnerabilities ([#578](https://github.com/box/box-node-sdk/pull/578)) ## 1.36.0 (2021-01-27) ### New Features and Enhancements: - Add folder lock functionality ([#560](https://github.com/box/box-node-sdk/pull/560)) - Add support for filtering groups by name ([#561](https://github.com/box/box-node-sdk/pull/561)) ### Bug Fixes: - Update proxy-agent to patch proxy support issue ([#563](https://github.com/box/box-node-sdk/pull/563)) - Update dependencies to patch security vulnerabilities ([#566](https://github.com/box/box-node-sdk/pull/566)) ## 1.35.0 (2020-11-02) ### New Features and Enhancements: - Add support for search param to get shared link items ([#547](https://github.com/box/box-node-sdk/pull/547)) ## 1.34.3 (2020-10-02) ### Bug Fixes: - Upgrade ajv dependency ([#545](https://github.com/box/box-node-sdk/pull/545)) ## 1.34.2 (2020-08-20) - Make iterator bug fix for uploading files non breaking ([#534](https://github.com/box/box-node-sdk/pull/534)) ## 1.34.1 (2020-08-17) - Fix iterator bug for uploading new file versions ([#531](https://github.com/box/box-node-sdk/pull/531)) ## 1.34.0 (2020-08-04) - Add zip functionality ([#525](https://github.com/box/box-node-sdk/pull/525)) - Add proxy support for `http`, `https`, `socks` and `pac` protocols ([#529](https://github.com/box/box-node-sdk/pull/529)) ## 1.33.0 (2020-06-25) - Add path parameter sanitization ([#505](https://github.com/box/box-node-sdk/pull/505)) - Add support for all streams for uploading files ([#519](https://github.com/box/box-node-sdk/pull/519)) ## 1.32.0 (2020-04-01) - Temporarily removed Node 4 and Node 5 builds from Travis, due to tests not passing. Will investigate, going forward ([#495](https://github.com/box/box-node-sdk/pull/495)). - Fixed an issue where an error is thrown during a retry when a response is not returned by the previous call ([#477](https://github.com/box/box-node-sdk/pull/477)). - Added the ability to [query](./docs/metadata.md#query) Box items based on their metadata ([#487](https://github.com/box/box-node-sdk/pull/487)). ## 1.31.0 (2020-02-13) - Fixed Authentication Request Retries - Added marker-based paging for users endpoints - Added `getNextMarker()` to PagingIterator to get the next marker ## 1.30.0 (2019-11-21) - Deprecated Batch API methods - Added support for [token exchange](./lib/box-client.js#L495) using shared links ## 1.29.1 (2019-08-22) - Fixed an issue where JWT authentication requests could fail after being rate limited ## 1.29.0 (2019-04-25) Added convenience methods for setting metadata on [files](./docs/metadata.md#set-metadata-on-a-file) and [folders](./docs/metadata.md#set-metadata-on-a-folder) ([#376](https://github.com/box/box-node-sdk/pull/376)) ## 1.28.0 (2019-03-28) Added methods for [moving](./docs/web-links.md#move-a-web-link) and [copying](./docs/web-links.md#move-a-web-link) weblinks, as well as [adding or removing from a collection](./docs/web-links.md#add-web-link-to-a-collection) ## 1.27.0 (2019-02-28) - Added the trace ID from API response headers to error messages for easier debugging - Added more safety checks in the error flow to protect against throwing when handling a malformed request - Added support for [retrieving a user's avatar image](./docs/users.md#get-user-avatar) ## 1.26.2 (2019-02-22) Fixed an error where under high request rates, code in the error handling logic could throw when handling a malformed request ## 1.26.1 (2019-02-12) - Fixed an error where some methods could throw an error when constructing an iterator ## 1.26.0 (2019-02-12) - Added support for [replying to a comment](./docs/comments.md#reply-to-a-comment) (thanks @jpan-box!) Fixed an issue where calling `client.events.get()` could return an iterator that would only iterate over the first chunk of events. This method will now always return the raw JSON data in order to enable manual paging. For automatic paging through events, `client.events.getEventStream()` or `client.events.getEnterpriseEventStream()` should be used instead. ## 1.25.0 (2019-01-24) - Added the `retryStrategy` config parameter to allow customizing how the SDK retries failing requests ## 1.24.1 (2019-01-11) - Fixed an issue where token expiration was not being correctly handled ## 1.24.0 (2018-12-10) - Added a configuration option for populating the first-party client analytics header information ## 1.23.0 (2018-11-21) Added an `etag` option to common file and folder methods to allow handling race conditions - [`client.files.update()`](./docs/files.md#update-a-files-information) - [`client.files.delete()`](./docs/files.md#delete-a-file) - [`client.files.deletePermanently()`](./docs/trash.md#delete-a-file-from-the-trash) - [`client.files.deleteVersion()`](./docs/files.md#delete-a-previous-file-version) - [`client.folders.update()`](./docs/folders.md#update-a-folders-information) - [`client.folders.delete()`](./docs/folders.md#delete-a-folder) - [`client.folders.deletePermanently()`](./docs/trash.md#delete-a-folder-from-the-trash) ## 1.22.1 (2018-11-15) - Fixed an issue where retrying JWT auth token requests would sometimes fail due to a non-unique `jti` claim ## 1.22.0 (2018-09-17) - Chunked Uploader methods now return promises for [simpler handling of chunked uploads](./docs/files.md#automatic-uploader) - File attributes to set on the newly-uploaded file can now be [passed via `options.fileAttributes`](./docs/files.md#automatic-uploader) when creating a Chunked Uploader ## 1.21.0 (2018-09-13) - Added the ability to close an Event Stream by calling `eventStream.destroy()` (thanks @boneskull!) - Improved error messages related to certain authentication failure cases ## 1.20.0 (2018-08-09) - Added missing values to the `client.webhooks.triggerTypes` enum (thanks @MathersMax!) - Added support for [Metadata Cascade Policies](./docs/metadata.md#create-cascade-policy) ## 1.19.0 (2018-06-14) - Added `generateRepresentations` option to [`files.getRepresentationContent()`](./docs/files.md#get-representation-content) ## 1.18.0 (2018-05-24) Updated dependencies to resolve potential security issues: - `request@2.87.0` - Transitive dependencies of `jsonwebtoken@8.2.1` Added a static `BoxSDK.getBasicClient()` method to enable creating a client without needing to specify a client ID and secret (thanks to @cbetta) ## 1.17.0 (2018-05-10) - Updated dependencies: `request@2.85.0`, `jsonwebtoken@8.2.1` - Added support for [Storage Policies](https://ja.developer.box.com/127ef6eef52e4e56f73da7cb35736016/storage-policies.md) - Added the option to use a Token Store for caching tokens with App Auth using JWT ## 1.16.1 (2018-04-26) - Fixed a bug where metadata template deletion would not properly return results via callback ## 1.16.0 (2018-04-10) - Added support for [assigning Retention Policies to Metadata Templates](https://github.com/box/box-node-sdk/blob/main/docs/retention-policies.md#assign-retention-policy) ## 1.15.0 (2018-03-29) - Fixed [`client.webhooks.validateMessage() and `sdk.validateWebhookMessage()`](https://github.com/box/box-node-sdk/blob/main/docs/webhooks.md#validate-a-webhook-message) to accept the request body as an `Object` - Fixed `sdk.configure()` to correct reconfigure all options - Improved error messages for API errors and added the request object as `error.request` for easier debugging ## 1.14.1 (2018-03-13) - Fixed a bug when `files.getReadStream()` was called with null options ## 1.14.0 (2018-03-12) - Added support for [getting a metadata template by ID](./docs/metadata.md#get-by-id) - Added a `byteRange` option to [file download](./docs/files.md#download-a-file) to support partial file download - Improved error messages when using promises and in authentication flows ## 1.13.0 (2018-03-01) - Added support for getting a [stream of file representation contents](./docs/files.md#get-representation-content) - Switched to using exponential backoff for request retries ## 1.12.1 (2018-01-25) - Fixed an issue where chunked uploader would not work with response streams from the request library (0e7014561f9cd0f7f38f98536b3f0c3946231d2e) ## 1.12.0 (2018-01-11) - Added support for [metadata template deletion](./docs/metadata.md#delete-metadata-template) ## 1.11.0 (2017-12-12) - Added options to preserve file timestamps on [file upload](./docs/files.md#upload-a-file) and to rename a file or preserve modification timestamp on [new version upload](./docs/files.md#upload-a-new-version-of-a-file) - Added [Collaboration Whitelist](./docs/collaboration-whitelist.md) functionality to allow enterprise admins to control which external users can collaborate on their content - Added an option to Token Exchange to generate [annotator tokens](./docs/authentication.md#annotator-tokens) for use with Box View ## 1.10.1 (2017-11-28) - Updated to [jsonwebtoken@8.1.0](mailto:jsonwebtoken@8.1.0) to fix an issue where some users were getting an error when using App Auth ## 1.10.0 (2017-01-14) - Added support for [Terms of Service](https://ja.developer.box.com/932f3810fb86d1a28be4edb39d4c82da/terms-of-service.md) endpoints - Fixed a bug where receiving a collection without paging parameters from the API would cause the SDK to throw an exception when using the `iterators` SDK option. Now, this will return an iterator over the items returned by the API. - Fixed a bug in Token Exchange where passing multiple scopes would result in an error - Added support for [getting Representations info on a file](./docs/files.md#get-representation-info) ## 1.9.0 (2017-09-12) - Fixed token methods to return bluebird Promises instead of native Promises - Added support for the `notify` and `can_view_path` options on Collaborations ## 1.8.0 (2017-08-21) - Added support for [Batch API](./docs/client.md#batch-api) - Fixed a bug where the Event Stream would make more API calls than necessary, potentially hitting Box API rate limits - Added Promise support to methods on the SDK object - Added Node.js version to the User-Agent header that the SDK sends - Fixed a bug where using multiple Persistent Clients instances could cause some clients to end up with expired tokens ## 1.7.0 (2017-07-19) - Add support for passing IP to all token methods, and fixed a bug where a client's IP was not being correctly reported on token refreshes ## 1.6.0 (2017-06-23) - Added [Recent Items](https://ja.developer.box.com/4d81cc8152b9a29d4fa3be3b89640b0c/recent-items.md) support - Updated app auth expiration time default value and validation ## 1.5.1 (2017-06-15) - Revert deep-freezing Config properties, since it was causing errors ## 1.5.0 (2017-06-15) - Added support for [Token Exchange](./docs/authentication.md#token-exchange), which allows a client to get downscoped tokens suitable for passing to a browser app or worker process. - Ensured deeply-nested Config properties are immutable ## 1.4.2 (2017-05-22) - Fixed `BoxSDK.getPreconfiguredInstance()` to configure webhook keys ## 1.4.1 (2017-05-22) - Fixed `BoxSDK.getPreconfiguredInstance()` when app auth setttings are not populated ## 1.4.0 (2017-05-19) - Added support for [file collaborations](./docs/collaborations.md#add-a-collaboration). Users can now invite others to collaborate on single files. See [the blog post](https://blog.box.com/blog/file-collaboration-api/) for more information. - Fixed an issue where users were unable to use JWT Server Auth when their computers' clocks were not synchronized with the Box API servers. - All asynchronous client methods now return Promises in addition to taking a (now-optional) callback parameter, so you can write more modern JS with the SDK. - The SDK can now be preconfigured using a JSON blob that can be downloaded in the Box Dev Console for JWT Server Authentication apps, making it easier to get started developing! - Added support for [chunked upload](./docs/files.md#chunked-upload), where a large file can be uploaded one piece at a time. This makes large file uploads much faster and more reliable, since parts can be uploaded in parallel and failed parts can be retried in isolation. - Added an `is_confirmed` option to [email alias creation](./docs/users.md#add-email-alias) for admins to auto-confirm the alias. - Added support for the [Enterprise Events stream](./docs/events.md#enterprise-events). - Added an option to have collections methods (e.g. `folders.getItems()`, `enterprise.getUsers()`, etc) return [async iterators](./README.md#iterators) that will automatically page through the collection. This conforms to the [proposed async iteration spec](https://github.com/tc39/proposal-async-iteration), which will eventually allow them to be used in ergonomic for-await-of loop syntax. ## 1.3.0 (2017-01-24) - Added `BoxSDK.validateWebhookMessage()` and `client.webhooks.validateMessage()` for validating webhook messages from Box ## 1.2.0 (2016-12-12) - Added methods for all API endpoints; we now have full API coverage :tada: - Added support for renaming a file or folder on copy - Added `client.asUser(userID)` and `client.asSelf()` to support making calls on behalf of managed users - Fixed event streams so they don't go into an infinite error loop when auth expires - Fixed an error where App Auth clients would not be able to authorize due to clock skew - Fixed the `mdfilters` parameter in `client.search.query()` to support metadata search - Cloned options objects to prevent modification of passed-in objects by the SDK - Added better error messaging to the sample app ## 1.1.0 (2016-09-27) - Added endpoint to get a file's tasks - Fixed issues with stream uploads - Improved performance of file uploads - Added endpoints to delete files and folders from trash - Added endpoint to get a trashed folder - Upgraded request dependency to fix ReDoS vulnerability ## [1.0.0] (2016-07-13) Initial release. --- ### Changelog **Type:** page | **Section:** Additional Resources Changelog All notable changes to this project will be documented in this file. See standard-version for commit guidelines. 4.16.3 (2025-0… # Changelog All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines. ### 4.16.3 (2025-07-23) ### Bug Fixes: - Fix compare message webhook message signature ([#1315](https://github.com/box/box-java-sdk/issues/1315)) ([e2d407d](https://github.com/box/box-java-sdk/commit/e2d407ded3370ffee6eb074044fd562629a904be)) - Fix File Request Copy method to return valid data ([#1320](https://github.com/box/box-java-sdk/issues/1320)) ([8392a43](https://github.com/box/box-java-sdk/commit/8392a437c1a738bebb4e7d0f84d6bf833c76bdf3)) ### 4.16.2 (2025-06-02) ### Bug Fixes: - Fix parsing `downloadFileCount` property for `BoxZipDownloadStatus` ([50c2249](https://github.com/box/box-java-sdk/commit/50c2249ff5e0f0d1fdc99c9ff8786e9c134e58eb)) ### 4.16.1 (2025-04-29) ### Bug Fixes: - use `Locale.ROOT` to prevent issues with non-US locales ([#1306](https://github.com/box/box-java-sdk/issues/1306)) ([f083092](https://github.com/box/box-java-sdk/commit/f083092d5fdac37c93493945ab0c05ecdcdbc838)) ## 4.16.0 (2025-04-15) ### New Features and Enhancements: - Bump version of `zstd-jni` ([#1302](https://github.com/box/box-java-sdk/issues/1302)) ([9ebf8b5](https://github.com/box/box-java-sdk/commit/9ebf8b5d16c0ab8f4aa19849fdaa86935d38b294)) ### 4.15.3 (2025-03-12) ### Bug Fixes: - trim `content-length` header value ([#1297](https://github.com/box/box-java-sdk/issues/1297)) ([fa11d14](https://github.com/box/box-java-sdk/commit/fa11d141edf511eabc5f2398e55dc411d0cdcd31)) ### 4.15.2 (2025-02-26) ### Bug Fixes: - Improve logging for API Request and API Response ([#1295](https://github.com/box/box-java-sdk/issues/1295)) ([6eb1f57](https://github.com/box/box-java-sdk/commit/6eb1f57a584571b46daa14d045a36bca382493fa)) ### 4.15.1 (2025-02-24) ### Bug Fixes: - Fix parsing content length header ([#1292](https://github.com/box/box-java-sdk/issues/1292)) ([3bcf788](https://github.com/box/box-java-sdk/commit/3bcf788dd9849305aa2cc85b8e5f88b35803ecb2)) ## 4.15.0 (2025-02-19) ### New Features and Enhancements: - Add `canNonOwnersViewCollaborators` flag to `Folder` ([#1288](https://github.com/box/box-java-sdk/issues/1288)) ([9119adc](https://github.com/box/box-java-sdk/commit/9119adceae35e892e73ed61ed30cf82ad912960d)) - Support `zstd` encoding for downloads ([#1287](https://github.com/box/box-java-sdk/issues/1287)) ([0e3c4c0](https://github.com/box/box-java-sdk/commit/0e3c4c07e65ef1887cd5c393e3daf98aeb50ee47)) ### Bug Fixes: - Fix AI dialogue history ([#1289](https://github.com/box/box-java-sdk/issues/1289)) ([29b6519](https://github.com/box/box-java-sdk/commit/29b651987a5cbeead4b129cab20970f983cb6889)) ## 4.14.0 (2025-01-22) ### New Features and Enhancements: - Support downloading file from shared link ([#1282](https://github.com/box/box-java-sdk/issues/1282)) ([9b7f28b](https://github.com/box/box-java-sdk/commit/9b7f28b0288977513b0db3ed4f800647545e1f2c)) ### Bug Fixes: - Remove sensitive data when `BoxAPIException` logs request ([#1284](https://github.com/box/box-java-sdk/issues/1284)) ([f1e226f](https://github.com/box/box-java-sdk/commit/f1e226f710c301202acff067ef34687ddbb57b7b)) - Support creating ongoing Legal Hold policy with start date ([#1281](https://github.com/box/box-java-sdk/issues/1281)) ([d9564e2](https://github.com/box/box-java-sdk/commit/d9564e2e86ea110af933ca3dd0f728111d7140ae)) ### 4.13.1 (2024-11-29) ### Bug Fixes: - Correctly calculate `Content-Length` when reading from a stream ([#1277](https://github.com/box/box-java-sdk/issues/1277)) ([b1d5371](https://github.com/box/box-java-sdk/commit/b1d5371491abe1729a95eb9dc39d375135c8681d)) ## 4.13.0 (2024-11-21) ### New Features and Enhancements: - Enforce exact byte reading from `Content-Length` header for `BoxFile` representation ([#1274](https://github.com/box/box-java-sdk/issues/1274)) ([0b45cdb](https://github.com/box/box-java-sdk/commit/0b45cdb74c21996d1dfea505d25430a1fa9ee730)) - Expose `getVersionByID` method on `BoxFile` ([#1268](https://github.com/box/box-java-sdk/issues/1268)) ([6ea70f7](https://github.com/box/box-java-sdk/commit/6ea70f79ad39dd9a427ee574b5536d0ab1e3a9a4)) - make `tryRestoreUsingAccessTokenCache` in Box API connection public ([#1272](https://github.com/box/box-java-sdk/issues/1272)) ([50f5a61](https://github.com/box/box-java-sdk/commit/50f5a61184bd1a17a17e811536166f9f8e081a13)) ### Bug Fixes: - Fix `accessToken` locking mechanism ([#1270](https://github.com/box/box-java-sdk/issues/1270)) ([5eb4c93](https://github.com/box/box-java-sdk/commit/5eb4c93bd3653b28dc7def747779d008369f486a)) ## 4.12.0 (2024-10-17) ### New Features and Enhancements: - Support AI Agent ([#1265](https://github.com/box/box-java-sdk/issues/1265)) ([3cb2c7c](https://github.com/box/box-java-sdk/commit/3cb2c7c275761a24be9403a6a2b41d0725ba8d9b)) - Support AI extract and AI extract structured ([#1266](https://github.com/box/box-java-sdk/issues/1266)) ([7ba90b9](https://github.com/box/box-java-sdk/commit/7ba90b96070a32b3e2ac60e5c55bd04d0a5973c0)) ### 4.11.1 (2024-07-16) ### Bug Fixes: - Fix order of file upload multipart request ([#1261](https://github.com/box/box-java-sdk/issues/1261)) ([7200ac7](https://github.com/box/box-java-sdk/commit/7200ac77888b3639f2c294486be278e316efcfb0)) ## 4.11.0 (2024-07-15) ### New Features and Enhancements: - Allow overriding creation of OkHttp Call ([#1257](https://github.com/box/box-java-sdk/issues/1257)) ([bd6fde6](https://github.com/box/box-java-sdk/commit/bd6fde6689bebe6cb5889c91214db68e08a4ec8b)) ### Bug Fixes: - Add missing fields when update classification template ([#1255](https://github.com/box/box-java-sdk/issues/1255)) ([f17f817](https://github.com/box/box-java-sdk/commit/f17f817bde5a412358bf3de8e489ed080715ec4b)) - Fix deserializing permissions for `BoxFile` and `BoxFolder` ([#1256](https://github.com/box/box-java-sdk/issues/1256)) ([f088448](https://github.com/box/box-java-sdk/commit/f08844889800a01f7c78941036f6228502fca8b0)) ## 4.10.0 (2024-06-06) ### New Features and Enhancements: - Overload the `getRepresentationContent` method with a `maxRetries` parameter ([#1251](https://github.com/box/box-java-sdk/issues/1251)) ([d26bd4f](https://github.com/box/box-java-sdk/commit/d26bd4f5a141150a372159bc3867abbbbdda1406)) - Support `login_required`, `password`, `suppress_nofitications`, `verification_phone_number` and `additional_info` fields in sign request ([#1250](https://github.com/box/box-java-sdk/issues/1250)) ([3ee55b3](https://github.com/box/box-java-sdk/commit/3ee55b3613c5f5fa92cdd4a17c0cb3e2cc86a9a4)) ### 4.9.1 (2024-05-20) ### Bug Fixes: - Bumped `org.bouncycastle:bcprov-jdk18on:1.78.1` and `org.bouncycastle:bcpkix-jdk18on:1.78.1` ([#1246](https://github.com/box/box-java-sdk/issues/1246)) ([0557bed](https://github.com/box/box-java-sdk/commit/0557bed2b65d1be717b64a612d74fca73ba21096)) ## 4.9.0 (2024-05-06) ### New Features and Enhancements: - Support AI API ([#1243](https://github.com/box/box-java-sdk/issues/1243)) ([4e64f27](https://github.com/box/box-java-sdk/commit/4e64f27874fabf36f7fbf385ca4a60683f4a7670)) - Support pagination of file versions ([#1240](https://github.com/box/box-java-sdk/issues/1240)) ([7e7af3f](https://github.com/box/box-java-sdk/commit/7e7af3f6e40a44522a7649817547846e3f633fc8)) ### Bug Fixes: - Support create empty shared link ([#1241](https://github.com/box/box-java-sdk/issues/1241)) ([0c86487](https://github.com/box/box-java-sdk/commit/0c86487848e5004a713873baffa2d9dcc63b1502)) - Update exception message for get representation content ([#1239](https://github.com/box/box-java-sdk/issues/1239)) ([a608f9a](https://github.com/box/box-java-sdk/commit/a608f9a4350b723e9f07eaf00af45243737a17c9)) ## 4.8.0 (2024-02-27) ### New Features and Enhancements: - allow modifying `BoxAPIRequest` URL ([#1236](https://github.com/box/box-java-sdk/issues/1236)) ([eaea019](https://github.com/box/box-java-sdk/commit/eaea0193ab7e72b73746ea85806e62468825bbce)) - Bumped `org.bouncycastle:bcprov-jdk18on:1.77` and `org.bouncycastle:bcpkix-jdk18on:1.77` ([#1237](https://github.com/box/box-java-sdk/issues/1237)) ([6c7fe7b](https://github.com/box/box-java-sdk/commit/6c7fe7b74dbfb34e729fcecf8a29a1d3a1ba596f)), closes [#1235](https://github.com/box/box-java-sdk/issues/1235) ### Bug Fixes: - fix download for empty files ([#1231](https://github.com/box/box-java-sdk/issues/1231)) ([0e2230b](https://github.com/box/box-java-sdk/commit/0e2230b0be36f6bfb35f1d6b9dd4ba58e4d125ec)) - stop using `SharedLinkAPIConnection` in `getSharedItem()` ([#1234](https://github.com/box/box-java-sdk/issues/1234)) ([9f9af8e](https://github.com/box/box-java-sdk/commit/9f9af8e22b4a38dc9a31a611ff1b962966bbd6b5)) ## 4.7.0 (2024-01-16) ### New Features and Enhancements: - Add `signer_group_id` for signer in sign request ([#1220](https://github.com/box/box-java-sdk/issues/1220)) ([f560db8](https://github.com/box/box-java-sdk/commit/f560db8d5587406099066803789d16374ec7dbb9)) - Introduce `IPrivateKeyDecryptor` to allow using custom cryptography provider ([#1226](https://github.com/box/box-java-sdk/issues/1226)) ([727e6d7](https://github.com/box/box-java-sdk/commit/727e6d71ee375a48b4241a26a093becfe0965898)) ### Bug Fixes: - Remove delete classification ([#1222](https://github.com/box/box-java-sdk/issues/1222)) ([9814038](https://github.com/box/box-java-sdk/commit/981403896b4cd16a42c9feeecf30e75e1e8fa072)) ### 4.6.1 (2023-11-02) ### Dependency Upgrades: - Bumped `org.bitbucket.b_c:jose4j:0.9.3` ([#1212](https://github.com/box/box-java-sdk/issues/1212)) ([f522a56](https://github.com/box/box-java-sdk/commit/f522a5660f3522b11a0516774ba0cca69db3ec31)) ## 4.6.0 (2023-09-28) ### New Features and Enhancements: - Support search deleted filters ([#1207](https://github.com/box/box-java-sdk/issues/1207)) ([5e0e9ed](https://github.com/box/box-java-sdk/commit/5e0e9ed9aea2818da6fba0d562b56987c4948aaa)) ### Bug Fixes: - Added protected accessors for trust manager and hostname verifier. ([#1206](https://github.com/box/box-java-sdk/issues/1206)) ([0c79d17](https://github.com/box/box-java-sdk/commit/0c79d1754bffeb3f0487e10d55d716ba1cbed1aa)) - fix not closing response body ([#1208](https://github.com/box/box-java-sdk/issues/1208)) ([ab5e170](https://github.com/box/box-java-sdk/commit/ab5e1702934607b258802b33f3663af3e9c56027)) ## 4.5.0 (2023-09-13) ### New Features and Enhancements: - Add `iframeable_embed_url` field to `BoxSignRequestSigner` class ([#1202](https://github.com/box/box-java-sdk/issues/1202)) ([2e931d8](https://github.com/box/box-java-sdk/commit/2e931d8c36694a665d1c6315d3bf2d226929b713)) ### Bug Fixes: - `SharedLinkAPIConnection` uses request interceptor ([#1203](https://github.com/box/box-java-sdk/issues/1203)) ([b2b6a1d](https://github.com/box/box-java-sdk/commit/b2b6a1dba316ba50a1e011250c320fca156c6708)), closes [#1200](https://github.com/box/box-java-sdk/issues/1200) - Update sign template missing enum ([#1201](https://github.com/box/box-java-sdk/issues/1201)) ([fcb6657](https://github.com/box/box-java-sdk/commit/fcb6657bb2375e32c3fb0f861e7ecaeb84503f2c)) ## 4.4.0 (2023-08-29) ### New Features and Enhancements: - Support sign template and new sign status ([#1197](https://github.com/box/box-java-sdk/issues/1197)) ([e37c0dc](https://github.com/box/box-java-sdk/commit/e37c0dce86a422de5e8e6ed26fd93f1324f4b3e3)) ## 4.3.0 (2023-08-11) ### New Features and Enhancements: - Support access only collaboration ([#1193](https://github.com/box/box-java-sdk/issues/1193)) ([664c01f](https://github.com/box/box-java-sdk/commit/664c01f80ca0647645c60920eb0ef1f9353a619f)) ### 4.2.1 (2023-08-03) ### Bug Fixes: - Fixed upload when data are coming from a dynamic source ([#1189](https://github.com/box/box-java-sdk/issues/1189)) ([77b39f2](https://github.com/box/box-java-sdk/commit/77b39f2645d53bdab0ade23b637c211ea070fcf5)), closes [#1183](https://github.com/box/box-java-sdk/issues/1183) [#1190](https://github.com/box/box-java-sdk/issues/1190) ## 4.2.0 (2023-06-21) ### New Features and Enhancements: - Getting collaborators allows to specify fields ([#1178](https://github.com/box/box-java-sdk/issues/1178)) ([1694d75](https://github.com/box/box-java-sdk/commit/1694d75fff0fbddb938426ef03ba24f360a344aa)) ### 4.1.2 (2023-06-14) ### Bug Fixes: - Class cast exception when uploading large file ([#1174](https://github.com/box/box-java-sdk/issues/1174)) ([e7d28bd](https://github.com/box/box-java-sdk/commit/e7d28bddb706c8b4fd1328f0eebc50db19a8c656)), closes [#1173](https://github.com/box/box-java-sdk/issues/1173) - Make `SharedLinkAPIConnection` constructors public ([#1172](https://github.com/box/box-java-sdk/issues/1172)) ([4d1616d](https://github.com/box/box-java-sdk/commit/4d1616ddd2c39d1cb0d03af998d2c47efe607853)) - Remove invalid Group membership role ([#1171](https://github.com/box/box-java-sdk/issues/1171)) ([a5915f9](https://github.com/box/box-java-sdk/commit/a5915f94114a8269287831280a57949ed203e4e8)) ### 4.1.1 (2023-05-16) ### Bug Fixes: - Allow users to disable adding authentication header. ([#1167](https://github.com/box/box-java-sdk/issues/1167)) ([3433e5a](https://github.com/box/box-java-sdk/commit/3433e5a405ceb9bc32791642518b1fd65c4b4032)) - Logging headers when retrying request ([#1164](https://github.com/box/box-java-sdk/issues/1164)) ([e0c3d8e](https://github.com/box/box-java-sdk/commit/e0c3d8e730962ba5c97105ce506ee931a3bba362)) ## 4.1.0 (2023-04-24) ### New Features and Enhancements: - Add missing `fields` parameter to create and update `BoxUser` methods ([#1155](https://github.com/box/box-java-sdk/issues/1155)) ([be3820d](https://github.com/box/box-java-sdk/commit/be3820dc4df15e99dfc13602d4f7269841bd15b3)), closes [#1154](https://github.com/box/box-java-sdk/issues/1154) ### Bug Fixes: - Allow registering custom logger handlers ([#1156](https://github.com/box/box-java-sdk/issues/1156)) ([7373d5c](https://github.com/box/box-java-sdk/commit/7373d5cc2bf49bc198cbca70d056e43f0dffdb3a)) - Fallback to default value of `maxRetryAttempts` when restoring `BoxAPIConnection` ([#1161](https://github.com/box/box-java-sdk/issues/1161)) ([2a10e5d](https://github.com/box/box-java-sdk/commit/2a10e5d07497611e077a9207fe98c1d8146cfd22)), closes [#1160](https://github.com/box/box-java-sdk/issues/1160) ### 4.0.1 (2023-03-06) ### Bug Fixes: - `OAUTH_SUFFIX` gets appended twice to `baseAuthorizationURL` ([#1148](https://github.com/box/box-java-sdk/issues/1148)) ([3164770](https://github.com/box/box-java-sdk/commit/3164770498e5115a43318640735317a896950f54)), closes [#1147](https://github.com/box/box-java-sdk/issues/1147) - Wrong progress reported to `ProgressListener` by `AbstractBoxMultipartRequest` ([#1151](https://github.com/box/box-java-sdk/issues/1151)) ([947ded3](https://github.com/box/box-java-sdk/commit/947ded394490fc840b8191bc7ad69ae0ea5f5c7d)), closes [#1149](https://github.com/box/box-java-sdk/issues/1149) ## 4.0.0 (2023-01-17) The most important change this release includes is the replacement of the HTTP library from a native one to [OkHttp](https://square.github.io/okhttp/) which allows SDK to - Support the HTTP2 version of the HTTP protocol. Support proxies that do not use only basic authentication method. For details on creating custom proxy authenticators and an example of [NTLM proxy authentication](https://github.com/box/box-java-sdk/blob/kb/ok-http/doc/configuration.md#custom-proxy-authenticator). ### Breaking Changes - `BatchAPIRequest` – is no longer supported by the SDK - `BoxAPIConnection#DEFAULT_MAX_ATTEMPTS` is replaced with `BoxAPIConnection#DEFAULT_MAX_RETRIES` - `BoxRedirectResponse` – was removed and will not be replaced - `BoxEvent.Type` is replaced with `EventType` - Removing deprecated methods from `BoxFile`, `BoxFileVersionRetention`, `BoxFolder`, `BoxGroup`, `BoxGroupMembership`,`BoxItem`, `BoxRetentionPolicy`, `BoxTask`, `BoxUser`, `BoxWebLink`, `EventLog`, `Metadata` and `MetadataTemplate`. Migration details can be found [here](doc/upgrades/3.x.x%20to%204.x.x.md). ### New Features and Enhancements: - Using `OkHttp` in Java SDK ([#1083](https://github.com/box/box-java-sdk/issues/1083)) ([2656698](https://github.com/box/box-java-sdk/commit/265669897100dd8f1757fc2c5f25665da42c2889)) ### 3.8.2 (2023-01-04) ### Bug Fixes: - Fixed restoring state without refresh token. ([#1139](https://github.com/box/box-java-sdk/issues/1139)) ([3544709](https://github.com/box/box-java-sdk/commit/3544709480eb03e5bd50f5dc99be7409569304c4)) ### 3.8.1 (2022-12-19) ### Bug Fixes: - Restoring state from previous `SDK` version works. ([#1134](https://github.com/box/box-java-sdk/issues/1134)) ([b6d97dd](https://github.com/box/box-java-sdk/commit/b6d97dd5b0cc91eb2e4c922ff217e0878e0f63ec)) ## 3.8.0 (2022-11-15) ### New Features and Enhancements: - Added Box Sign webhooks ([#1109](https://github.com/box/box-java-sdk/issues/1109)) ([99051a5](https://github.com/box/box-java-sdk/commit/99051a575f120a8c0939359c1f4875b16b98b7f0)) ### Bug Fixes: - `NullPointerException` when using `BoxSignRequestPrefillTag` ([#1121](https://github.com/box/box-java-sdk/issues/1121)) ([73fd5b6](https://github.com/box/box-java-sdk/commit/73fd5b6e6e40f7e79b385edf46b8eee5ff612ace)), closes [#1120](https://github.com/box/box-java-sdk/issues/1120) - Regenerate JWT ID and retry auth request when JTI claim is rejected ([#1110](https://github.com/box/box-java-sdk/issues/1110)) ([420da0f](https://github.com/box/box-java-sdk/commit/420da0f2c80bfe8cfbaba4fa8dec4826c4cb6337)) ### Dependency Upgrades: - Bumped org.bitbucket.b_c:jose4j:0.9.0 ([#1111](https://github.com/box/box-java-sdk/issues/1111)) ([349694d](https://github.com/box/box-java-sdk/commit/349694ddcfeb701a9ecdfd5ae555d49bea4d1030)) ### 3.7.1 (2022-09-29) ### Bug Fixes: - Better logging when JSON cannot be parsed ([#1106](https://github.com/box/box-java-sdk/issues/1106)) ([5e66ef8](https://github.com/box/box-java-sdk/commit/5e66ef8cc983a6cff34995efc75e9effd3195d48)) ## 3.7.0 (2022-09-20) ### New Features and Enhancements: - Add `is_accessible_via_shared_link` field to File and Folder ([#1103](https://github.com/box/box-java-sdk/issues/1103)) ([45e9906](https://github.com/box/box-java-sdk/commit/45e9906efca6a7f2d4d738914dc804de12d3646e)) ### Bug Fixes: - `BoxCollaboration.getItem()` returns `BoxItem.Info` not `BoxFolder.Info` ([#1102](https://github.com/box/box-java-sdk/issues/1102)) ([135850d](https://github.com/box/box-java-sdk/commit/135850d97164ee5f6d74708d74c531f7fa8bee26)), closes [#1101](https://github.com/box/box-java-sdk/issues/1101) [#1100](https://github.com/box/box-java-sdk/issues/1100). `BoxCollaboration.getItem()` used to return `BoxFolder.Info`. However, if collaboration was added on a file it would still return `BoxFolder.Info` which will end with throwing `BoxAPIException` when doing any API call. If you are getting collaboration item it is best to store it as `BoxItem.Info` or check its type and store it as `BoxFile.Info` or `BoxFolder.Info`. - Add missing constructor to `BoxNotificationEmail` class ([#1098](https://github.com/box/box-java-sdk/issues/1098)) ([2534f34](https://github.com/box/box-java-sdk/commit/2534f34133f9554abd1e80fc1555659a2c52b23f)) ## 3.6.0 (2022-09-07) ### New Features and Enhancements: - Add support for modifiable retention policies & enable deleting retention policy assignment ([#1093](https://github.com/box/box-java-sdk/issues/1093)) ([30e2fcb](https://github.com/box/box-java-sdk/commit/30e2fcb74c12867fd3859c3490539557b47ab006)) ### Bug Fixes: - Stop sending not specified optional fields when creating a user ([#1095](https://github.com/box/box-java-sdk/issues/1095)) ([b7d894d](https://github.com/box/box-java-sdk/commit/b7d894d3f134137f3a5925f09accfd4334837f81)) ## 3.5.0 (2022-08-26) ### New Features and Enhancements: - Add `content-type` sign request and response ([#1087](https://github.com/box/box-java-sdk/issues/1087)) ([49411aa](https://github.com/box/box-java-sdk/commit/49411aaeea6d3ff8de10e3fbc3c60bba1bc54748)) - Add `notification_email` to `BoxUser` ([#1088](https://github.com/box/box-java-sdk/issues/1088)) ([5477223](https://github.com/box/box-java-sdk/commit/547722347a920ba11e5fff7a8df5201720af815a)) - Add `redirect_url` and `declined_redirect_url` to sign request response ([#1089](https://github.com/box/box-java-sdk/issues/1089)) ([3921fe1](https://github.com/box/box-java-sdk/commit/3921fe1a4a6249146a8dd2f22e15801846bc073b)) ### Bug Fixes: - Fixed canceling sign request fails because of empty body ([#1085](https://github.com/box/box-java-sdk/issues/1085)) ([32b8e79](https://github.com/box/box-java-sdk/commit/32b8e79ebc8995ab933c32d28c3e2f17d9627a70)) ## 3.4.0 (2022-08-10) ### New Features and Enhancements: - Added pagination for getting items in trash with new `BoxTrash#items` API ([#1072](https://github.com/box/box-java-sdk/issues/1072)) ([9cd411d](https://github.com/box/box-java-sdk/commit/9cd411d20af1bc76ae815905396d72008af62539)) ### Bug Fixes: - buffered body write and fixed SDK logging ([#1079](https://github.com/box/box-java-sdk/issues/1079)) ([bc35ef3](https://github.com/box/box-java-sdk/commit/bc35ef3279e68a3d794de454f506ba41d14c3b16)) ## 3.3.0 (2022-07-01) ### New Features and Enhancements: - Added support of Editable Shared Links ([#1064](https://github.com/box/box-java-sdk/issues/1064)) ([9b7d60c](https://github.com/box/box-java-sdk/commit/9b7d60c41fbd481465bf3f2a5877746f10849712)) ### Bug Fixes: - Fix closed stream exception in `canUpload` method ([#1067](https://github.com/box/box-java-sdk/issues/1067)) ([543f91c](https://github.com/box/box-java-sdk/commit/543f91c46dfcc9de7e61ce11cd93d472916533ac)) ### 3.2.1 (2022-06-10) ### Bug Fixes: - Fix getting proper URL to authenticate with OAuth ([#1059](https://github.com/box/box-java-sdk/issues/1059)) ([42876b4](https://github.com/box/box-java-sdk/commit/42876b45ccdb7fa6f357186cecaba051abf1c269)), closes [#1057](https://github.com/box/box-java-sdk/issues/1057) ## 3.2.0 (2022-05-23) ### New Features and Enhancements: - Revamped setting base URLs ([#1042](https://github.com/box/box-java-sdk/issues/1042)) ([129baf7](https://github.com/box/box-java-sdk/commit/129baf704ced127788bb0f62ef9f4fb6a50fdc63)) - support for Avatar V2 API ([#1044](https://github.com/box/box-java-sdk/issues/1044)) ([18651d7](https://github.com/box/box-java-sdk/commit/18651d7a5b419796e3733c7582ae471d7af7ed5c)) ### 3.1.2 (2022-03-22) ### Bug Fixes: - Allow using `As-User` header with CCG Authentication ([#1031](https://github.com/box/box-java-sdk/issues/1031)) ([b0c2389](https://github.com/box/box-java-sdk/commit/b0c238913cc1dbcecfd546a5eae68277c3c76d42)) - Fix retry logic when `Retry-After` header is present ([#1033](https://github.com/box/box-java-sdk/issues/1033)) ([05224c4](https://github.com/box/box-java-sdk/commit/05224c433d2a101a01959644674153df9542b711)) ### 3.1.1 (2022-02-28) ### Bug Fixes: - retry `jwt` auth when error code is in error field ([#1020](https://github.com/box/box-java-sdk/issues/1020)) ([8c9d11d](https://github.com/box/box-java-sdk/commit/8c9d11d1b3556552751c9f4ac99a0f7180af97f3)), closes [#1019](https://github.com/box/box-java-sdk/issues/1019) ## 3.1.0 (2022-02-17) ### New Features and Enhancements: - Added support for Client Credentials Grant authentication method ([#1002](https://github.com/box/box-java-sdk/issues/1002)) ([9cfcaff](https://github.com/box/box-java-sdk/commit/9cfcaff243dbf0541409f91f9f863a207345dc47)) - API to extend disposition date on a file ([#1001](https://github.com/box/box-java-sdk/issues/1001)) ([f3f6b60](https://github.com/box/box-java-sdk/commit/f3f6b6043eec362c5a8ad9a01d6588538ca34e71)) - Deprecating `indexName` when executing metadata query ([#1000](https://github.com/box/box-java-sdk/issues/1000)) ([c20dbbf](https://github.com/box/box-java-sdk/commit/c20dbbf6a927e31cfdd7ffa71069c0897f7a0536)) ### Dependency Upgrades: - Upgrade Gradle to 7.3.3 ([#985](https://github.com/box/box-java-sdk/issues/985)) ([e4acbb1](https://github.com/box/box-java-sdk/commit/e4acbb1f0c10ccdeeee139e2566b344052680010)) ## 3.0.0 (2022-01-17) ### ⚠ BREAKING CHANGES - Changed `BoxFileVersion` class and removed `fileVersion` field (#978) - Removed deprecated API `BoxCollaborationWhitelist` replaced with `BoxCollaborationAllowlist`, `BoxCollaborationWhitelistExemptTarget` replaced with `BoxCollaborationAllowlistExemptTarget` (#969) - Dropping Java 7 support (#962) - Downgrading `bouncycastle` libraries to 1.57 (#942) ### New Features and Enhancements: - Add `typeName` to `BoxEvent` that contains name of the event, even if it is not mapped to `BoxEvent.EventType` ([#979](https://github.com/box/box-java-sdk/issues/979)) ([b30f61f](https://github.com/box/box-java-sdk/commit/b30f61f8cc9c02a1fc4cd5eb35469749e1a16558)), closes [#968](https://github.com/box/box-java-sdk/issues/968) - Add new optional `description` parameter to the `retention_policies` endpoint and `start_date_field` to the `retention_policy_assignments endpoint`. ([#967](https://github.com/box/box-java-sdk/issues/967)) ([0aa4ff4](https://github.com/box/box-java-sdk/commit/0aa4ff48a1e035efc9ac6aaa42f18f4c92955b7b)) - Adding `BoxFile#getVersions(String... fields)` to allow users to specify what information they want to extract. Fixes [#946](https://github.com/box/box-java-sdk/issues/946). ([#947](https://github.com/box/box-java-sdk/issues/947)) ([a2eb638](https://github.com/box/box-java-sdk/commit/a2eb63896606a6c00ccee6bd9745f4c51f8d89a2)) - Missing `eventTypes` from `BoxAPI` Documents. Fixes [#974](https://github.com/box/box-java-sdk/issues/974) ([#975](https://github.com/box/box-java-sdk/issues/975)) ([2c69360](https://github.com/box/box-java-sdk/commit/2c69360e80b1bdd6213933cf2f4da195d52c92d4)) - Removed deprecated API `BoxCollaborationWhitelist` replaced with `BoxCollaborationAllowlist`, `BoxCollaborationWhitelistExemptTarget` replaced with `BoxCollaborationAllowlistExemptTarget` ([#969](https://github.com/box/box-java-sdk/issues/969)) ([2fd4d6f](https://github.com/box/box-java-sdk/commit/2fd4d6f884410c8884c4c038687bfc8f32837b55)) ### Bug Fixes: - Changed `BoxFileVersion` class and removed `fileVersion` field ([#978](https://github.com/box/box-java-sdk/issues/978)) ([8c39451](https://github.com/box/box-java-sdk/commit/8c3945167581400043a070c2f6906ef05d3d7b85)) - Changed SDK loggers name to `"com.box.sdk"`, fixes [#638](https://github.com/box/box-java-sdk/issues/638) ([#950](https://github.com/box/box-java-sdk/issues/950)) ([443c230](https://github.com/box/box-java-sdk/commit/443c23085e55bbcaa1524c5b9e1bf852a1e2a1ce)) - Date parsing error when `BoxSignRequestPrefillTag` created with date value. ([#970](https://github.com/box/box-java-sdk/issues/970)) ([cc2c8da](https://github.com/box/box-java-sdk/commit/cc2c8da9ea7d066ae2c247c2de5ac8b8bbba9b99)) - Fix sending limit param in `EventLog` ([#977](https://github.com/box/box-java-sdk/issues/977)) ([96bdccc](https://github.com/box/box-java-sdk/commit/96bdccc9ca40ed43a6028a2b0d055d9d9a8de525)) - Fixed `NullPointerException` when empty metadata used on BoxFile or `BoxFolder` ([#918](https://github.com/box/box-java-sdk/issues/918)) ([#945](https://github.com/box/box-java-sdk/issues/945)) ([68bc3c5](https://github.com/box/box-java-sdk/commit/68bc3c578d760b7239f6d704fed9bb5a834bf52a)) - Fixes issue ([#951](https://github.com/box/box-java-sdk/issues/951)) error when deserialising sign request ([#952](https://github.com/box/box-java-sdk/issues/952)) ([070bdc5](https://github.com/box/box-java-sdk/commit/070bdc56074a1533c41f9085943d09502c79a7f4)) ### Dependency Upgrades: - Dropping Java 7 support ([#962](https://github.com/box/box-java-sdk/issues/962)) ([953ad78](https://github.com/box/box-java-sdk/commit/953ad78ac84833082439d0def1dcc63dc11ac04a)) - Downgrading `bouncycastle` libraries to 1.57 ([#942](https://github.com/box/box-java-sdk/issues/942)) ([26aaed5](https://github.com/box/box-java-sdk/commit/26aaed51fd914eaf2061da735f11830524e4cfe4)) ## [2.58.0] (2021-11-23) ### ⚠ BREAKING CHANGES ### New Features and Enhancements: - SDK support for new GET /events stream_type: admin_logs_streaming ([#938](https://github.com/box/box-java-sdk/pull/938)) - Adding BoxDeveloperEditionAPIConnection#getUserConnection to indicate that we can use this connection for managed users or app users ([#940](https://github.com/box/box-java-sdk/pull/940)) ### Bug Fixes: - Fix for deprecated enums still being used ([#931](https://github.com/box/box-java-sdk/issues/931)) ## [2.57.0] (2021-10-18) ### ⚠ BREAKING CHANGES ### New Features and Enhancements: - Add support for marker-based paging in BoxFolder.getChildren ([#927](https://github.com/box/box-java-sdk/pull/927)) - Upgraded minimal-json to v0.9.5 - Upgraded jose4j to v0.7.9 - Adding Gradle wrapper in version 4.0.1 ([#928](https://github.com/box/box-java-sdk/pull/928)) ### Bug Fixes: - Fix for infinite recursion ([#924](https://github.com/box/box-java-sdk/pull/924)) - Fix unable to set Vanity URL on `BoxSharedLink` for BoxFile and BoxFolder ([#925](https://github.com/box/box-java-sdk/issues/925)) ## [2.56.0] (2021-08-31) ### New Features and Enhancements: - Replace `submaster` GroupMembershipRole with `coadmin`. Replace `MASTER_INVITE_ACCEPT` and `MASTER_INVITE_REJECT` with `ADMIN_INVITE_ACCEPT` and `ADMIN_INVITE_REJECT`. ([#907](https://github.com/box/box-java-sdk/pull/907)) - Add `tracking_codes` to create User API call ([#910](https://github.com/box/box-java-sdk/pull/910)) ### Bug Fixes: - Fix `url` for `BoxFileRequest.Info` object ([#906](https://github.com/box/box-java-sdk/pull/906)) - Attempt to fix thread locking issue on refresh of access token ([#912](https://github.com/box/box-java-sdk/pull/912)) ## [2.55.1] (2021-07-30) ### Bug Fixes: - Restore methods for Execute Metadata Query, which were removed in ([#890](https://github.com/box/box-java-sdk/pull/890)), and mark them as deprecated ([#905](https://github.com/box/box-java-sdk/pull/905)) ## [2.55.0] (2021-07-26) NOTE: Due to the benign nature of the "breaking change" below, we decided NOT to increment the major version for this release. There should be no customer impact due to this change. ### ⚠ BREAKING CHANGES Update execute metadata query to match API response ([#890](https://github.com/box/box-java-sdk/pull/890)) - NOTE: This change removes a method without deprecating it. It was not possible to use the method correctly at all, because the underlying service no longer supported it. ### New Features and Enhancements: - Remove or deprecate insensitive language ([#889])([https://github.com/box/box-java-sdk/pull/889](https://github.com/box/box-java-sdk/pull/889)) - Add support for `is_external_collab_restricted` parameter for User ([#896](https://github.com/box/box-java-sdk/pull/896)) - Add configurable permissions support for `GroupMembership` ([#897](https://github.com/box/box-java-sdk/pull/897)) - Add `SHIELD_JUSTIFICATION_APPROVAL` event type ([#898](https://github.com/box/box-java-sdk/pull/898)) - Add ability to get files under retention for assignment and file versions under retention for assignment ([#899](https://github.com/box/box-java-sdk/pull/899)) - Add `TASK_UPDATE`, `FILE_VERSION_RESTORE` and `ADVANCED_FOLDER_SETTINGS_UPDATE` event types ([#902](https://github.com/box/box-java-sdk/pull/902)) - Add SignAPI support ([#904](https://github.com/box/box-java-sdk/pull/904)) ### Bug Fixes: - Add setters for `BoxLegalHoldPolicy` ([#885](https://github.com/box/box-java-sdk/pull/885)) - Add setters for `BoxTaskAssignment` ([#886](https://github.com/box/box-java-sdk/pull/886)) - Add setters for Group Membership and Web Links ([#887](https://github.com/box/box-java-sdk/pull/887)) - Add setters for Webhooks ([#888](https://github.com/box/box-java-sdk/pull/888)) - Deprecate `BoxFile.getThumbnail` in favor of `BoxFile.getRepresentationContent` ([#891](https://github.com/box/box-java-sdk/pull/891)) ## [2.54.0] (2021-04-01) ### New Features and Enhancements: - Add file request support ([#869](https://github.com/box/box-java-sdk/pull/869)) ### Bug Fixes: - Fix `BoxWeblink` deserialization ([#881](https://github.com/box/box-java-sdk/pull/881)) ## [2.53.0] (2021-01-08) ### New Features and Enhancements: - Add offset and limit parameters to `BoxFolder.getChildren` ([#861](https://github.com/box/box-java-sdk/pull/861)) ## [2.52.0] (2020-11-24) ### New Features and Enhancements: - Add folder lock functionality ([#856](https://github.com/box/box-java-sdk/pull/856)) - Add support for search param to get shared link items ([#855](https://github.com/box/box-java-sdk/pull/855)) ### Bug Fixes: - Fix bug with updating tracking codes ([#857](https://github.com/box/box-java-sdk/pull/857)) ## [2.51.1] (2020-11-12) ### Bug Fixes: - Fix for cross-enterprise collaborator calls to updateMetadata on files ## [2.51.0] (2020-10-29) ### New Features and Enhancements: - Add support for `copyInstanceOnItemCopy` field for metadata templates ([#850](https://github.com/box/box-java-sdk/pull/850)) - Add support for more fields in `BoxCollaborator.Info` ([#843](https://github.com/box/box-java-sdk/pull/843)) ### Bug Fixes: - Update `getAllGroupsByName()` to use documented parameter ([#851](https://github.com/box/box-java-sdk/pull/851)) ## [2.50.1] (2020-08-20) - Fix bug that occurred when downscoping a token for a Box folder ([#832](https://github.com/box/box-java-sdk/pull/832)) ## [2.50.0] (2020-07-21) - API request creation errors are now retried with the same automatic retry logic as 429 and 5XX response errors ([#828](https://github.com/box/box-java-sdk/pull/828)) ## [2.49.0] (2020-07-17) - Fix bug with setting the unshared at date for a shared link ([#819](https://github.com/box/box-java-sdk/pull/819)) - Add zip functionality ([#825](https://github.com/box/box-java-sdk/pull/825)) - Add `fields` parameter for metadata query ([#826](https://github.com/box/box-java-sdk/pull/826)) ## [2.48.0] (2020-06-23) - Add ability to get groups by name with fields option ([#789](https://github.com/box/box-java-sdk/pull/789)) - Add shared link downscoping ([#785](https://github.com/box/box-java-sdk/pull/785)) - Deprecate the use of float for Metadata values, in preference of the underlying value (double) ([#811](https://github.com/box/box-java-sdk/pull/811)) - Add iterator support for group collaborations ([#813](https://github.com/box/box-java-sdk/pull/813)) - Add ability to set the filename when uploading a new version of a file ([#810](https://github.com/box/box-java-sdk/pull/810)) - Add support for the classification field for Files and Folders ([#809](https://github.com/box/box-java-sdk/pull/809)) - Add support for setting Tracking Codes ([#766](https://github.com/box/box-java-sdk/pull/766)) - Fix issue for `getIsExternallyOwned()` for Files and Folders ([#808](https://github.com/box/box-java-sdk/pull/808)) ## [2.47.0] (2020-04-23) - Add support for the uploader display name field for Files and File Versions ([#791](https://github.com/box/box-java-sdk/pull/791)) - Fix path parameter sanitization ([#797](https://github.com/box/box-java-sdk/pull/797)) ## [2.46.0] (2020-04-09) Fix retry logic ([#787](https://github.com/box/box-java-sdk/pull/787)) - Retry for 400 `invalid_grant` error in authentication requests (Clock Skew) - Honor Retry-After header, if present, by waiting for the time specified in the header before retrying - The concept of setting / getting "Maximum API Requests" has been deprecated in favor of "Maximum API Retries" to more clearly show the number of times a request will be retried after an error response is received. Add ability to set expiration date for a collaboration ([#788](https://github.com/box/box-java-sdk/pull/788)) Add path parameter sanitization ([#790](https://github.com/box/box-java-sdk/pull/790)) ## [2.45.0] (2020-04-02) - Add preflight check before chunked uploads ([#782](https://github.com/box/box-java-sdk/pull/782)) - Check that part was successfully uploaded for large file uploads before retrying for 500 errors ([#781](https://github.com/box/box-java-sdk/pull/781)) - Fix bug with premature disconnect when renaming files and weblinks ([#779](https://github.com/box/box-java-sdk/pull/779)) - Add metadata to each item returned by a metadata query ([#778](https://github.com/box/box-java-sdk/pull/778)) ## [2.44.1] (2020-02-13) - Fix formatting bug for Java Logger - Improve date / time parsing for responses ## [2.44.0] (2020-01-21) - Fix Authentication Request Retries ## [2.43.0] (2019-12-20) - Throw exceptions for setMetadata on Files and Folders for non-409 errors ## [2.42.0] (2019-12-17) - Added Metadata Query support - Added marker based pagination for get users methods ## [2.41.0] (2019-10-24) - Added enum action option for completed in Box Task class. ## [2.40.0] (2019-10-24) - General doc changes. ## [2.39.0] (2019-10-17) - Deprecated Batch API functionality. - Added support for [Task completion_rule](https://github.com/box/box-java-sdk/blob/main/src/main/java/com/box/sdk/BoxFile.java#L249) ## [2.38.0] (2019-09-19) - Added missing fields for File Version: trashed_by, restored_at, purged_at, purged_by. - Added support for [chunked uploads with file attributes](https://github.com/box/box-java-sdk/blob/main/doc/files.md#upload-a-large-file-in-chunks-including-attributes). ## [2.37.0] (2019-08-22) Added support for replace in multi-select metadata for [files](https://github.com/box/box-java-sdk/blob/main/doc/files.md#update-metadata) and for [folders](https://github.com/box/box-java-sdk/blob/main/doc/folders.md#update-metadata) - Improved getting started with JWT authentication docs that can be found [here](https://github.com/box/box-java-sdk/blob/main/doc/authentication.md#server-authentication-with-jwt) ## [2.36.0] (2019-08-01) - Added support for [removing shared link](https://github.com/box/box-java-sdk/blob/main/src/main/java/com/box/sdk/BoxItem.java#L413) and fixed an issue with setting null for shared link field on BoxItem. - Added support for additional fields for Box files, folders, and web links. ## [2.35.0] (2019-07-18) - Added support for retrieving [is_external_only field](https://github.com/box/box-java-sdk/blob/main/src/main/java/com/box/sdk/BoxFile.java#L1668) for Box Files and Folders. ## [2.34.0] (2019-06-06) Added support for retrieving a [string type action for tasks](https://github.com/box/box-java-sdk/blob/main/src/main/java/com/box/sdk/BoxTask.java#L281). Please use getActionType() going forward instead of the deprecated getAction(). ## [2.33.0] (2019-05-23) - Added support for [setting can_owners_invite field](https://github.com/box/box-java-sdk/blob/1ed10d7a457e44b863ec1c9b1d0d1408fb55e1e5/src/main/java/com/box/sdk/BoxFolder.java#L1272) Thank you @Band-Aid for you pull request! Greatly Appreciated. - Fixed a bug where chunked upload was not populating the correct part size for upload part. ## [2.32.0] (2019-04-25) - Added support [setting metadata](https://github.com/box/box-java-sdk/blob/main/doc/folders.md#set-metadata). ## [2.31.0] (2019-04-11) - Added support for [sorting folder items](https://github.com/box/box-java-sdk/blob/main/doc/folders.md#get-a-folders-items) retrieved from a folder by ascending or descending order. ## [2.30.1] (2019-04-08) - Fixed a bug where the SDK could throw when parsing JSON containing dates using the Zulu timezone format ## [2.30.0] (2019-04-04) - Added `action_by` field to enterprise events stream. ## [2.29.0] (2019-04-01) - Added support for [sorting results returned from Box Search](https://github.com/box/box-java-sdk/blob/main/doc/search.md#search-1) - Added ability to [attach a file description upon file upload](https://github.com/box/box-java-sdk/blob/main/doc/files.md#upload-a-file) ## [2.28.1] (2019-03-07) - Fixed a bug where BoxMetadataCascadePolicy.forceApply() would not return correctly. ## [2.28.0] (2019-02-21) - Added ability for user to [retrieve an avatar](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxUser.html#getAvatar--)) for a specified user. ## [2.27.0] (2019-01-31) - Added support for Metadata Classification for [File](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFile.html#setClassification-java.lang.String...-) and [Folder](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFolder.html#setClassification-java.lang.String...-) ## [2.26.0] (2019-01-17) - Added [invite_email](https://github.com/box/box-java-sdk/blob/main/src/main/java/com/box/sdk/BoxCollaboration.java#L277) field to collaboration object. - Added [is_collaboration_restricted_to_enterprise](https://github.com/box/box-java-sdk/blob/main/src/main/java/com/box/sdk/BoxFolder.java#L1104) field to folder object. - Added [status](https://github.com/box/box-java-sdk/blob/main/src/main/java/com/box/sdk/BoxTaskAssignment.java#L196) field to task assignment object. - Added ability to retrieve fields for [`BoxFile#getTasks()`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFile.html#getTasks-java.lang.String...-) - Fixed bug where offset based paging would not return correctly. ## [2.25.1] (2019-01-03) - Upgraded dependencies: jose4j to v0.5.5, and bouncycastle to v1.60 ## [2.25.0] (2018-12-13) - Added functionality to allow [content streaming to Box through outputstream](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFolder.html#uploadFile-com.box.UploadFileCallback-java.lang.String-). Thank you @gajarajkalburgi for the pr! ## [2.24.0] (2018-11-16) - Added `getOptionsObjects()` on `MetadataTemplate.Field` which returns both key and type. - Added functionality for [`BoxItem#getType()`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxItem.html#getType--) for BoxItem. - Added functionality for [`BoxAPIConnection#BoxGlobalSettings()`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxAPIConnection.html#setConnectTimeout-java.lang.String-) and [`BoxAPIConnection#BoxGlobalSettings()`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxAPIConnection.html#getConnectTimeout--) as well as getting and reading the timeout for the connection. - Added functionality for [`BoxGlobalSettings#getMaxRequestAttempts()`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxGlobalSettings.html#getMaxRequestAttempts--) and [`BoxGlobalSettings#setMaxRquestAttempts()`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxGlobalSettings.html#setMaxRequestAttempts-java.lang.Integer-) - Fixed a bug where [`BoxLegalHoldPolicy#create()`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxLegalHoldPolicy.html#create-com.box.BoxAPIConnection-java.lang.String-) was not setting the correct legal hold policy duration. ## [2.23.2] (2018-09-27) - Fixed a bug where the specified headers for batch requests were not being sent. ## [2.23.1] (2018-09-13) - Fixed a bug where too many TCP connections were being opened. Thank you @pmatte1 for implementing this fix! ## [2.23.0] (2018-08-23) - Added support for [Metadata Cascade Policy](https://github.com/box/box-java-sdk/blob/main/doc/folders.md#create-cascade-policy-on-folder) ## [2.22.0] (2018-08-09) - Deprecated the [moveFolderToUser()](https://github.com/box/box-java-sdk/blob/main/src/main/java/com/box/sdk/BoxUser.java#L455) for Box Users. We encourage users to use [transferContent](https://github.com/box/box-java-sdk/blob/main/src/main/java/com/box/sdk/BoxUser.java#L482) going forward because idiomatically it is more correct. ## [2.21.0] (2018-07-05) - Added functionality to allow users to [set passwords on shared links](https://github.com/box/box-java-sdk/pull/623) for Box files, folders, and web links. - Fixed wrong redirect for two links in the `Getting Started` and `Quick Test` section of the README. ## [2.20.2] (2018-06-28) - Fixed a bug where customers had issues with large file uploads because they fail to parse the Retry-After header from the commit response. Reason being headers storage/lookup was case sensitive. ## [2.20.1] (2018-06-04) - Added better exception handling for JSON parse in response exception. - Fixed a bug where uploadNewVersion() was returning an empty object. ## [2.20.0] (2018-05-24) - Fixed a bug where multiple As-User headers could be set. - Added support to [test update](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/Metadata.html#test-java.lang.String-java.util.List-) for multiselect field on metadata ## [2.19.0] (2018-05-10) - Added support for enterprise admins with Box Zones purchased to have support for [Box Storage Policies and Box Storage Policy Assignments](./doc/storage_policy) - Added support to allow users to work with [multiselect metadata](./doc/files.md#get-metadata) - Added `getLogin()` method for the "login" field on the "accessible by" for BoxCollaboration.Info class. ## [2.18.0] (2018-04-30) - Fixed a bug where the the private key password should be passed into `setPrivateKetPassword()` instead of the private key. A big thank you to [breach10ck](https://github.com/breach10ck) for their pull request! - Added an additional check to ensure that the [request properties on the request object is not null in the `toString()` method](https://github.com/box/box-java-sdk/pull/595) - Added support to [fetch the content of the generated representation](./doc/files.md#get-representation-content) after it has been generated - Improved error messages for API response errors to allow for better debugging. ## [2.17.0] (2018-04-10) - Added support for assigning [Retention Policies to Metadata Templates](./doc/retention_policies.md#create-retention-policy-assignment) ## [2.16.1] (2018-03-29) - Added `CONTENT_ACCESS` to event type enum ## [2.16.0] (2018-03-22) - Added support for [user tracking codes](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxUser.Info.html#getTrackingCodes--) on the user object. - Fixed a bug where JWT authentication would fail due to improper date parsing. - Added support for setting custom headers on API connection. This allow for setting [As-User support](./doc/overview.md#as-user) and [suppressing notifications](./doc/overview.md/suppressing-notifications) support. - Changed default JWT expiration window to reduce chances of error. ## [2.15.0] (2018-03-12) - Added support for retrieving a [metadata template by ID](./doc/metadata_template.md#get-by-id) - Added support for allowing the user to [retrieve specific Collaboration fields on a Collaboration object](./doc/collaborations.md#get-a-collaborations-information) ## [2.14.1] (2018-03-01) - Reduced the number of API calls that the `EventStream` makes to fetch new events, which should help users who are running into rate limit issues. - Force support for TLSv1.1 or higher when available to improve the security of connections to the Box API - Add randomized jitter to the exponential backoff algorithm used by the SDK to improve the success rate of retried requests. ## [2.14.0] (2018-02-15) - Added support for getting and setting the `can_view_path` field on a collaboration object. - Added support for getting and setting the `tags` field on files and folders. ## [2.13.0] (2018-02-07) - Fixed an issue where all types of metadata values were being coerced to Strings. This change deprecates `Metadata#get()` in favor of type-specific methods like `Metadata#getFloat()` or a generic `Metadata#getValue()`, which returns a `JsonValue` object that represents any JSON type. See the [file metadata](./doc/files.md#get-metadata) or [folder metadata](./doc/folders.md#get-metadata) documentation for more information. ## [2.12.0] (2018-02-01) - Fixed ability to notify users or groups regarding [file collaboration](https://github.com/box/box-java-sdk/blob/main/doc/files.md#share-a-file) or [folder collaboration](https://github.com/box/box-java-sdk/blob/main/doc/folders.md#share-a-folder) - Added [OAuth2 token creation event types](https://github.com/box/box-java-sdk/blob/main/src/main/java/com/box/sdk/BoxEvent.java#L747) - Added support for [inviting a user to another Box Enterprise](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxInvite.html) - Fixed an [OutOfMemory error in large file upload by capping the maximum number of parts that are uploaded concurrently](https://github.com/box/box-java-sdk/pull/543) ## [2.11.0] (2018-01-25) - [uploadLargeFile now returns a BoxFile object](https://github.com/box/box-java-sdk/pull/524) - [Fixed chunked upload for Box Files greater than 2GB](https://github.com/box/box-java-sdk/pull/531) - [Perform modified retry on JWT auth for when the local clock and the Box Server clock are not aligned as well as if the JWT ID has already been consumed](https://github.com/box/box-java-sdk/pull/523) - BoxFolder.search has been deprecated in favor of [BoxSearch.searchRange](https://github.com/box/box-java-sdk/blob/86b82f2be3c57e3b89ae150b5f237d410e2d4900/doc/search.md) ## [2.10.0] (2018-01-11) - [Add optional is_confirmed paramater for adding user email alias](https://github.com/box/box-java-sdk/pull/499) - Added support for [Metadata Template Delete](./doc/metadata_template#delete-a-metadata-template) ## [2.9.0] (2018-01-04) - Added option to pass file [SHA-1 hash for upload integrity](https://github.com/box/box-java-sdk/blob/main/doc/files.md#upload-a-file) - Added support for [Terms of Service](./doc/terms_of_service) endpoint - Fixed missing [webhook triggers](https://github.com/box/box-java-sdk/pull/497) - Fixed missing [event types for events enum](https://github.com/box/box-java-sdk/pull/500) - Added [modified_at timestamp to BoxComment.Info](https://github.com/box/box-java-sdk/pull/499) - Added support for [Collaboration Whitelists](./doc/collaboration_whitelists) endpoint ## [2.8.2] (2017-10-05) - Added additional check for `PrivateKeyInfo` in `BoxDeveloperEditionApiConnection` ## [2.8.1] (2017-10-05) - Added ability to [set connect and read timeout globally](https://github.com/box/box-java-sdk/pull/459) ## [2.8.0] (2017-09-07) - Added method for getting file representations - Changes to Representation object ## [2.7.0] (2017-08-30) - Added support for [Representations](https://github.com/box/box-java-sdk/blob/main/src/main/java/com/box/sdk/BoxFile.java#L445) endpoint ## [2.6.0] (2017-08-28) - Added support for [Batch](https://github.com/box/box-java-sdk/blob/575861fad0b3e67d432b5d5955d1e760b3f6444e/README.md#batchrequestexample) - Added support for [Unified Metadata](./doc/folders#get-metadata-using-unified-metadata-api) ## [2.5.0] (2017-07-28) - Added support for [Recent Items](https://github.com/box/box-java-sdk/blob/main/src/main/java/com/box/sdk/BoxRecents.java#L1) endpoint - Added support [Get All Groups By Name](https://github.com/box/box-java-sdk/blob/a1833950c18139fd9cbb4d8ee61d310c7bbedadf/src/main/java/com/box/sdk/BoxGroup.java#L143) endpoint - Added support for [Token Exchange](https://github.com/box/box-java-sdk/blob/main/src/main/java/com/box/sdk/BoxAPIConnection.java#L634) ## [2.4.0] (2017-05-02) - Support for multiput upload. New methods in BoxFolder and BoxFile support multiput upload for better performance and reliability for large files. - Single file collaborations. The BoxFile class now supports sharing individual files. - Automatic configuration for JWT auth. The Box Developer console now lets you download a JSON file of your JWT app configuration settings. You can import this file into the Java SDK to easily configure your app. ## [2.3.0] (2017-01-12) New API Endpoints: [Legal Holds](https://github.com/box/box-java-sdk/blob/main/doc/legal_holds.md) [Retention Policies](https://github.com/box/box-java-sdk/blob/main/doc/retention_policies.md) [Create Metadata Template](https://github.com/box/box-java-sdk/blob/main/doc/metadata_template.md#create-metadata-template) [Get All Metadata on File](https://github.com/box/box-java-sdk/blob/main/doc/files.md#get-all-metadata-on-file) [Get All Metadata on Folder](https://github.com/box/box-java-sdk/blob/main/doc/folders.md#get-all-metadata-on-folder) [Get Enterprise Metadata Templates](https://github.com/box/box-java-sdk/blob/main/doc/metadata_template.md#get-enterprise-metadata-templates) [Update Group](https://github.com/box/box-java-sdk/blob/main/doc/groups.md#update-a-group) [Watermarking](https://github.com/box/box-java-sdk/blob/main/doc/watermarking.md) [Webhooks V2](https://github.com/box/box-java-sdk/blob/main/doc/webhooks.md) [WebLinks](https://github.com/box/box-java-sdk/blob/main/doc/weblinks.md) [Collections](https://github.com/box/box-java-sdk/blob/main/doc/collections.md) [BoxGroupMembership with for Paging](https://github.com/box/box-java-sdk/blob/main/doc/groups.md) [Enterprise Device Pins](https://github.com/box/box-java-sdk/blob/86b82f2be3c57e3b89ae150b5f237d410e2d4900/doc/devices.md) New Features: Transactional Authentication. Support for Box's new Transactional Auth APIs. Upload file versions with SHA1. A file's SHA1 can be passed in to BoxFile.uploadVersion(...) when uploading new versions. Get effective_access for shared links. The effective_access field is accessible through BoxSharedLink. getEffectiveAccess(). Added additional Event Types. The TASK_ASSIGNMENT_COMPLETE, TASK_ASSIGNMENT_UPDATE, TASK_CREATE, COMMENT_DELETE types are now included in the BoxEvent class. ## [2.1.0] (2016-02-22) This release includes improvements to token caching for App Users and support for additional API endpoints. New Features: ``` - App Users token caching. A token cache can now be specified in BoxDeveloperEditionAPIConnection. This allows for improved performance when using App Users authentication. - Support for retrieving download URLs. The BoxFile.getDownloadURL() method allows for retrieving a direct download URL to a file. - File thumbnails. The BoxFile.getThumbnail() method allows for downloading the [Thumbnail](https://github.com/box/box-java-sdk/blob/main/doc/files.md#get-thumbnail) for a file. ``` Bug Fixes: ``` - Getting info for a file could crash when there's no preview. Previously, an exception would be thrown if BoxFile.getInfo (BoxFile.ALL_FIELDS) was called and the file didn't have a preview available. ``` --- ### Changelog **Type:** page | **Section:** Additional Resources Changelog All notable changes to this project will be documented in this file. See standard-version for commit guidelines. 3.14.0 (2025-0… # Changelog All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines. ## 3.14.0 (2025-04-09) ### New Features and Enhancements: - Add `stream_file_content` parameter to upload methods ([#890](https://github.com/box/box-python-sdk/issues/890)) ([0e63c00](https://github.com/box/box-python-sdk/commit/0e63c002ee17618c08200c12caae4bb3890b1e90)) ## 3.13.0 (2024-08-22) ### New Features and Enhancements: - Add support for get AI agent default ([#883](https://github.com/box/box-python-sdk/issues/883)) ([c1010e0](https://github.com/box/box-python-sdk/commit/c1010e0349847586a9f00046570e975ec48eb0c5)) ## 3.12.0 (2024-08-06) ### New Features and Enhancements: - add create sign request function with different required parameters ([#878](https://github.com/box/box-python-sdk/issues/878)) ([d972f54](https://github.com/box/box-python-sdk/commit/d972f54dcf9962c6b911422793a682d8f6289f9e)) - Support Box AI features ([#877](https://github.com/box/box-python-sdk/issues/877)) ([3026d2a](https://github.com/box/box-python-sdk/commit/3026d2ab9932cd07aa9ff15a3ac3c3c14d3089b0)) ## 3.11.0 (2024-06-07) ### New Features and Enhancements: - Use upload session `urls` for chunk upload ([#875](https://github.com/box/box-python-sdk/issues/875)) ([c67b03c](https://github.com/box/box-python-sdk/commit/c67b03c7d88533773d62d72f0b626031805d61eb)) ## 3.10.0 (2024-05-22) ### New Features and Enhancements: - Transition to stable status ([#872](https://github.com/box/box-python-sdk/issues/872)) ([6203606](https://github.com/box/box-python-sdk/commit/620360607a51ee302cde61401db1424c9bf48d81)) ### Bug Fixes: - Change exception type for missing location header ([#871](https://github.com/box/box-python-sdk/issues/871)) ([8c5e0ec](https://github.com/box/box-python-sdk/commit/8c5e0eca7e494baa8138dceededa2009abc1717b)) - fix annnotation of oauths access_token ([#855](https://github.com/box/box-python-sdk/issues/855)) ([804780e](https://github.com/box/box-python-sdk/commit/804780e4c8d410590fa20cdb6dd35224d59d2ec0)) - Fix retention policy integration test ([#867](https://github.com/box/box-python-sdk/issues/867)) ([8e0d640](https://github.com/box/box-python-sdk/commit/8e0d6406f26be87799838b0aa57acd62c79d59a2)) - Remove delete classification ([#861](https://github.com/box/box-python-sdk/issues/861)) ([393cfef](https://github.com/box/box-python-sdk/commit/393cfefa57e729f34221a4e5923a4a50532f4013)) - Update exception file get download URL ([#866](https://github.com/box/box-python-sdk/issues/866)) ([94dcbcd](https://github.com/box/box-python-sdk/commit/94dcbcd490d98ff19afd38c9880de8022ad2ec89)) ### 3.9.2 (2023-10-18) ### Bug Fixes: - Remove restriction to version <2 of `urllib3` library ([#851](https://github.com/box/box-python-sdk/issues/851)) ([1dcd82e](https://github.com/box/box-python-sdk/commit/1dcd82e93267bfc68e3a7f8068b3c45ab7e86daf)) ### 3.9.1 (2023-09-14) ### Bug Fixes: - do not retry creating a ZIP when response code is 202 ([#845](https://github.com/box/box-python-sdk/issues/845)) ([3f6ed4e](https://github.com/box/box-python-sdk/commit/3f6ed4e1053a494ed9f2b79828850e059d0a1617)), closes [#844](https://github.com/box/box-python-sdk/issues/844) ## 3.9.0 (2023-09-06) ### New Features and Enhancements: - adds get sign template and get sign templates methods on Client ([#835](https://github.com/box/box-python-sdk/issues/835)) ([fbc783d](https://github.com/box/box-python-sdk/commit/fbc783d5af2e75f883f1a0051613c513139f68fb)) - Support create sign request with template ID ([#834](https://github.com/box/box-python-sdk/issues/834)) ([4f11d75](https://github.com/box/box-python-sdk/commit/4f11d7596488194fc740936fe987f42864003d41)) ### Bug Fixes: - ChunkedUploader Resume Not Closing ThreadPoolExecutor Instances ([#840](https://github.com/box/box-python-sdk/issues/840)) ([f210f00](https://github.com/box/box-python-sdk/commit/f210f00ad823d7755309f2e8804641e0debf8197)) ### 3.8.1 (2023-08-01) ### Bug Fixes: - Fix JSON response validation retry strategy ([#831](https://github.com/box/box-python-sdk/issues/831)) ([69834eb](https://github.com/box/box-python-sdk/commit/69834eb4c91a5aa4bc294a9fa49ecf753979d029)) ## 3.8.0 (2023-07-25) ### New Features and Enhancements: - Support updating all fields of `collaboration` ([#829](https://github.com/box/box-python-sdk/issues/829)) ([6dc7ecc](https://github.com/box/box-python-sdk/commit/6dc7ecc6f9c94e7531c4147a3645927b85928b2c)) ### 3.7.3 (2023-07-07) ### Bug Fixes: - Stop processing data for logging when logging is disabled and cache response `json` ([#824](https://github.com/box/box-python-sdk/issues/824)) ([3079171](https://github.com/box/box-python-sdk/commit/3079171f8dfc1a4c85f8587e8ce90e8fbd826ee4)) ### 3.7.2 (2023-05-26) ### Bug Fixes: - Use the older version of `urllib3` ([#815](https://github.com/box/box-python-sdk/issues/815)) ([ee29aa3](https://github.com/box/box-python-sdk/commit/ee29aa3fcf9ac71e9866913a87414cf625c0b805)) ### 3.7.1 (2023-04-18) ### Bug Fixes: - Rename filter date parameters in legal hold creation according to the documentation ([#810](https://github.com/box/box-python-sdk/issues/810)) ([f52c66a](https://github.com/box/box-python-sdk/commit/f52c66a8a8399a776493537f692460ace2995e40)) ## 3.7.0 (2023-03-08) ### New Features and Enhancements: - Update `retention_policies` and `retention_policy_assignments` ([#803](https://github.com/box/box-python-sdk/issues/803)) ([8b72f7e](https://github.com/box/box-python-sdk/commit/8b72f7e992bce676723a40ac12bde06c8cca3bfb)) - Use multiple threading for chunked upload ([#800](https://github.com/box/box-python-sdk/issues/800)) ([506ce0d](https://github.com/box/box-python-sdk/commit/506ce0d1e72ab4eeb6c5933a32c753e232a2f624)) ### 3.6.2 (2023-02-07) ### Bug Fixes: - Retry `Connection broken` and `Connection reset` requests errors ([#794](https://github.com/box/box-python-sdk/issues/794)) ([f1a0aa4](https://github.com/box/box-python-sdk/commit/f1a0aa434369f06e80654a9f5c4b796100881aa6)) ### 3.6.1 (2023-01-09) ### Bug Fixes: - Retry CCG and JWT auth requests on connection reset error ([#790](https://github.com/box/box-python-sdk/issues/790)) ([205997d](https://github.com/box/box-python-sdk/commit/205997db9870395b9dd042854c4201338dcf925f)), closes [#789](https://github.com/box/box-python-sdk/issues/789) ## 3.6.0 (2023-01-03) ### New Features and Enhancements: - Add support marker in trash get items ([#781](https://github.com/box/box-python-sdk/issues/781)) ([e2d1846](https://github.com/box/box-python-sdk/commit/e2d1846818aeccfcba2a2f09a5cd924c9f6cd534)) - Sanitize proxy credentials ([#782](https://github.com/box/box-python-sdk/issues/782)) ([97fb5aa](https://github.com/box/box-python-sdk/commit/97fb5aa2ed72008570abb327269ecec150632af9)) ### Bug Fixes: - Fix index error when getting an empty list of user term of service statuses ([#780](https://github.com/box/box-python-sdk/issues/780)) ([23d763a](https://github.com/box/box-python-sdk/commit/23d763ac4ba592131c43eb0319929db25d041c30)) - Specify which exceptions should be retried ([#784](https://github.com/box/box-python-sdk/issues/784)) ([833cd46](https://github.com/box/box-python-sdk/commit/833cd46bafe774f19925f78600df90477bf07055)) ### 3.5.1 (2022-11-30) ### Bug Fixes: - Renew connection when Connection reset error occurs ([#771](https://github.com/box/box-python-sdk/issues/771)) ([bcaab27](https://github.com/box/box-python-sdk/commit/bcaab277c3cabba498076d066366abbaa5507904)), closes [#756](https://github.com/box/box-python-sdk/issues/756) [#757](https://github.com/box/box-python-sdk/issues/757) [#763](https://github.com/box/box-python-sdk/issues/763) [#765](https://github.com/box/box-python-sdk/issues/765) [#766](https://github.com/box/box-python-sdk/issues/766) [#770](https://github.com/box/box-python-sdk/issues/770) - Retry JWT auth when got error: required unique `jti` claim. ([#768](https://github.com/box/box-python-sdk/issues/768)) ([878e958](https://github.com/box/box-python-sdk/commit/878e958abfb01740656aaff42492777753e4c8ea)) - Update `pyjtw` dependency to work with Python 3.10 ([#772](https://github.com/box/box-python-sdk/issues/772)) ([b13c5cd](https://github.com/box/box-python-sdk/commit/b13c5cd34105d3f774d3f6d35db7aaf51dd3e247)) ## 3.5.0 (2022-09-23) ### New Features and Enhancements: - Add `redirect_url` and `declined_redirect_url` fields to Sign Request ([#752](https://github.com/box/box-python-sdk/issues/752)) ([5d1f609](https://github.com/box/box-python-sdk/commit/5d1f609ed4c2ddb24bd88ffac256a2809a012698)) - Add support for modifiable retention policies & enable deleting retention policy assignment ([#759](https://github.com/box/box-python-sdk/issues/759)) ([847301b](https://github.com/box/box-python-sdk/commit/847301b43be335365858a80420459dffaada4302)) - Support file request APIs ([#747](https://github.com/box/box-python-sdk/issues/747)) ([71895e3](https://github.com/box/box-python-sdk/commit/71895e33ff7cf339fd8e095a5393f04b86791d5a)) ### Bug Fixes: - Do not log the content of downloaded file ([#760](https://github.com/box/box-python-sdk/issues/760)) ([5d26431](https://github.com/box/box-python-sdk/commit/5d264314f949c1f4d9136efd5cf8f13dd5897c05)) - Fix closing file after chunked upload ([#761](https://github.com/box/box-python-sdk/issues/761)) ([b433692](https://github.com/box/box-python-sdk/commit/b433692ecc07d62d011785a557128c1780ea1647)) ## 3.4.0 (2022-07-06) ### New Features and Enhancements: - Add support for editable shared links for files ([#737](https://github.com/box/box-python-sdk/issues/737)) ([1396200](https://github.com/box/box-python-sdk/commit/1396200c24bf62de63f9cb7949af5997593b9fac)) - Support uploading and deleting user avatar ([#743](https://github.com/box/box-python-sdk/issues/743)) ([fe00a9e](https://github.com/box/box-python-sdk/commit/fe00a9eb3434ee14bc4f01332d54c0272ed5f2d3)) ## 3.3.0 (2022-04-28) ### New Features and Enhancements: - Add support for multiple date time formats ([#722](https://github.com/box/box-python-sdk/issues/722)) ([92364de](https://github.com/box/box-python-sdk/commit/92364de1e7c1eee1e85857546af65c307ca863a0)) ### Bug Fixes: - Add missing fields to metadata template field ([#719](https://github.com/box/box-python-sdk/issues/719)) ([9e574a3](https://github.com/box/box-python-sdk/commit/9e574a3e56f72c0e78a31ddda78bc11d36ff3516)), closes [#717](https://github.com/box/box-python-sdk/issues/717) - Upload session commit return None on 202 ([#718](https://github.com/box/box-python-sdk/issues/718)) ([86a1856](https://github.com/box/box-python-sdk/commit/86a185630e6cce8f742123c7340da08267621313)), closes [#715](https://github.com/box/box-python-sdk/issues/715) ## 3.2.0 (2022-03-11) ### New Features and Enhancements: - Add setting `disposition_at` field for files under retention ([#710](https://github.com/box/box-python-sdk/issues/710)) ([91b1373](https://github.com/box/box-python-sdk/commit/91b13730a0beef2cf2a8a8c71087b11557fa5982)) - Add support for Client Credentials Grant authentication method ([#705](https://github.com/box/box-python-sdk/issues/705)) ([d33d16d](https://github.com/box/box-python-sdk/commit/d33d16db656cb5578f057a7e24f5396d635b5361)) ### Bug Fixes: - Add missing `box_sign` object to `__all__` list ([#708](https://github.com/box/box-python-sdk/issues/708)) ([5d80481](https://github.com/box/box-python-sdk/commit/5d8048116640fa672d6a1d700a6c1111faf87bb9)) - Fix `jwt` import errors ([#711](https://github.com/box/box-python-sdk/issues/711)) ([ee7bb6f](https://github.com/box/box-python-sdk/commit/ee7bb6f1dc5aa65dbf6ffeb18ee130f765f7b49b)) ## 3.1.0 (2022-02-16) ### New Features and Enhancements: - Add support for Python 3.10 ([#692](https://github.com/box/box-python-sdk/issues/692)) ([d4aed82](https://github.com/box/box-python-sdk/commit/d4aed82831af97305bace9a4588d27b23856c306)) - Add support for Python 3.8, Python 3.9, `pypy-3.7` and `pypy-3.8`. ([#689](https://github.com/box/box-python-sdk/issues/689)) ([0aa94cc](https://github.com/box/box-python-sdk/commit/0aa94cc8a5c4db0fc204b27a60690b73c98a89cb)) - Deprecate `use_index` parameter from `MDQ` of files/folders ([#666](https://github.com/box/box-python-sdk/issues/666)) ([2595720](https://github.com/box/box-python-sdk/commit/25957204b82c878e15dc3d118505a741171e9772)) - Replace external package `mock` with Python standard library `unittest.mock` ([#697](https://github.com/box/box-python-sdk/issues/697)) ([6fd6366](https://github.com/box/box-python-sdk/commit/6fd63667aa7da4c794b4fb880d5c2949efe0073f)) - Upgrade cryptography library to the most recent version. ([#668](https://github.com/box/box-python-sdk/issues/668)) ([9c94d08](https://github.com/box/box-python-sdk/commit/9c94d0878515dc75c1f267e2fb1f189a852772b6)), closes [#667](https://github.com/box/box-python-sdk/issues/667) ### Bug Fixes: - `UploadSession.commit` returns `None` when retry limit was reached ([#696](https://github.com/box/box-python-sdk/issues/696)) ([9456fe0](https://github.com/box/box-python-sdk/commit/9456fe0124f4ac4e9c8a7bcc49039f07f310c477)) - Add missing `api_call` decorator for `create_upload_session` ([#686](https://github.com/box/box-python-sdk/issues/686)) ([3510d3a](https://github.com/box/box-python-sdk/commit/3510d3ac085767205854014ecef80fd078d71773)) - Fix chunked upload ([#673](https://github.com/box/box-python-sdk/issues/673)) ([2605fd7](https://github.com/box/box-python-sdk/commit/2605fd782396ad6e42bd11c10f846e771634b7a0)), closes [#671](https://github.com/box/box-python-sdk/issues/671) ## [3.0.1] (2022-01-26) ### Bug Fixes: Move sphinx to test requirements ([#662](https://github.com/box/box-python-sdk/pull/662)) ## [3.0.0] (2022-01-17) ### ⚠ Breaking Changes: Drop support for python 2.7 ([#645](https://github.com/box/box-python-sdk/pull/645)) Add missing parameter `stream_position` to `get_admin_events` method ([#648](https://github.com/box/box-python-sdk/pull/648)) Drop support for python 3.5 ([#654](https://github.com/box/box-python-sdk/pull/654)) Remove deprecated code using insensitive language ([#651](https://github.com/box/box-python-sdk/pull/651)) Enforcing usage of keyword-only arguments in some functions ([#656](https://github.com/box/box-python-sdk/pull/656)) ### New Features and Enhancements: Remove `six` library and `__future__` imports ([#646](https://github.com/box/box-python-sdk/pull/646)) Add type hints to method parameters ([#650](https://github.com/box/box-python-sdk/pull/650)) ### Bug Fixes: Add missing `api_call` decorators on `multiput` calls ([#653](https://github.com/box/box-python-sdk/pull/653)) Added `py.typed` file for `mypy` to recognise type hints ([#657](https://github.com/box/box-python-sdk/pull/657)) ## [2.14.0] (2021-12-08) ### New Features and Enhancements: Add `admin_logs_streaming` support for events stream ([#623](https://github.com/box/box-python-sdk/pull/623)) Add `vanity_name` parameter for creating shared link to a file or folder ([#637](https://github.com/box/box-python-sdk/pull/637)) Add getting files and file versions under retention for a retention policy assignment ([#633](https://github.com/box/box-python-sdk/pull/633)) Support base item operations for WebLink class ([#639](https://github.com/box/box-python-sdk/pull/639)) ### Bug Fixes: Limit cryptography to version <3.5.0 ([#636](https://github.com/box/box-python-sdk/pull/636)) Avoid raising 404 when a thumbnail cannot be generated for a file ([#642](https://github.com/box/box-python-sdk/pull/642)) ## [2.13.0] (2021-09-30) ### New Features and Enhancements: Sensitive language replacement ([#609](https://github.com/box/box-python-sdk/pull/609)) Add BoxSign support ([#617](https://github.com/box/box-python-sdk/pull/617)) ### Bug Fixes: Upgrade cryptography to version 3 ([#620](https://github.com/box/box-python-sdk/pull/620)) ## [2.12.1] (2021-06-16) ### Bug Fixes: Fix bug when thumbnail representations are not found ([#597](https://github.com/box/box-python-sdk/pull/597)) ## [2.12.0] (2021-04-16) ### New Features and Enhancements: Add metadata query functionality ([#574](https://github.com/box/box-python-sdk/pull/574)) Add folder lock functionality ([#581](https://github.com/box/box-python-sdk/pull/581)) Add search query support for the `include_recent_shared_links` field ([#582](https://github.com/box/box-python-sdk/pull/582)) Update `get_groups()` to use documented parameter to filter by name ([#586](https://github.com/box/box-python-sdk/pull/586)) ## [2.11.0] (2021-01-11) ### New Features and Enhancements: Deprecate and add method for getting a thumbnail ([#572](https://github.com/box/box-python-sdk/pull/572)) ## [2.10.0] (2020-10-02) ### New Features and Enhancements: Add support for `copyInstanceOnItemCopy` field for metadata templates ([#546](https://github.com/box/box-python-sdk/pull/546)) Allow creating tasks with the `action` and `completion_rule` parameters ([#544](https://github.com/box/box-python-sdk/pull/544)) Add zip functionality ([#539](https://github.com/box/box-python-sdk/pull/539)) ### Bug Fixes: Fix bug with updating a collaboration role to owner ([#536](https://github.com/box/box-python-sdk/pull/536)) Allow ints to be passed in as item IDs ([#530](https://github.com/box/box-python-sdk/pull/530)) ## [2.9.0] (2020-06-23) - Fix exception handling for OAuth - Fix path parameter sanitization ## [2.8.0] (2020-04-24) - Added support for token exchange using shared links - Added the ability to pass in a SHA1 value for file uploads ## [2.7.1] (2020-01-21) Fixed bug in `_get_retry_request_callable` introduced in release 2.7.0 which caused chunked uploads to fail ## [2.7.0] (2020-01-16) Fixed bug in `get_admin_events` function which caused errors when the optional `event_types` parameter was omitted. - Add marker based pagination for listing users. Added support for more attribute parameters when uploading new files and new versions of existing files. Combined preflight check and lookup of accelerator URL into a single request for uploads. - Fixed JWT retry logic so a new JTI claim is generated on each retry. Fixed bug where JWT authentication requests returned incorrect error codes. Fixed retry logic so when a `Retry-After` header is passed back from the API, the SDK waits for the amount of time specified in the header before retrying. ## [2.6.1] (2019-10-24) - Added `api_call` decorator for copy method. ## [2.6.0] (2019-08-29) Added a new get events function with created_before, created_after, and event_type parameters ## [2.5.0] (2019-06-20) Allowed passing `None` to clear configurable_permission field in the add_member() method. ## [2.4.1] (2019-05-16) - Patch release for issues with v2.4.0. ## [2.4.0] (2019-05-16) Added ability to set metadata on a [file](https://github.com/box/box-python-sdk/blob/main/docs/usage/files.md#set-metadata) or a [folder](https://github.com/box/box-python-sdk/blob/main/docs/usage/folders.md#set-metadata) ## [2.3.2] (2019-03-29) - Fixing an issue in v2.3.1 where package could not be installed. ## [2.3.1] (2019-03-29) - Fixing an issue in v2.3.0 where package could not be installed. ## [2.3.0] (2019-03-28) Added the ability to set file description upon upload Added support for basic authenticated proxy and unauthenticated proxy ## [2.2.2] (2019-03-14) - Updated requests-toolbelt dependency restriction. ## [2.2.1] (2019-02-15) - Fixing an issue in v2.2.0 where package could not be installed. ## [2.2.0] (2019-02-14) Added abilty for user to retrieve an avatar for a user. Changed retry strategy to use exponential backoff with randomized jitter. ## [2.1.0] (2019-02-07) Added ability for user to chunk upload files and resume uploads for interrupted uploads. Added ability to verify webhook message. Added ability for user to add metadata classification to [files](https://github.com/box/box-python-sdk/blob/main/docs/usage/files.md#set-a-classification) and [folders](https://github.com/box/box-python-sdk/blob/main/docs/usage/folders.md#set-a-classification). Bugfix where calling `.response_object()` method on an API object could throw. ## [2.0.0] ### ⚠ Breaking Changes Python 2.6 is no longer supported. Python 3.3 is no longer supported. `client.search()` now returns a `Search` object that exposes a `query()` method to call the Search API. Use `client.search().query(**search_params)` instead of `client.search(**search_params)`. `client.get_memberships(...)` has a change in signature. The limit and offset parameters have swapped positions to keep consistency with the rest of the SDK. `client.groups(...)` has been changed to `client.get_groups`. The limit and offset parameters have swapped positions. The `unshared_at` parameter for `item.create_shared_link(...)` and `file.get_shared_link_download_url(...)` now takes an [https://tools.ietf.org/html/rfc3339#section-5.8](https://tools.ietf.org/html/rfc3339#section-5.8) `unicode` string instead of a `datetime.date`. Users migrating from v1.x can pass the value of `date.isoformat()` instead of the `date` object itself. `Events.get_events(...)` now returns a list of `Event` instances rather than a list of `dict` representing events. `Event` inherits from `Mapping` but will not have all the same capabilities as `dict`. Your code is affected if you use `Events.get_events(...)` and expect a list of `dict` rather than a list of `Mapping`. For example, if you use `__setitem__` (`event['key'] = value`), `update()`, `copy()`, or if your code depends on the `str` or `repr` of the `Event`. Use of `__getitem__` (`event['key']`), `get()`, and other `Mapping` methods is unaffected. See [https://docs.python.org/2.7/library/collections.html#collections-abstract-base-classes](https://docs.python.org/2.7/library/collections.html#collections-abstract-base-classes) for methods supported on `Mapping` instances. Migration: If you still need to treat an `Event` as a `dict`, you can get a deepcopy of the original `dict` using the new property on `BaseAPIJSONObject`, `response_object`. `LoggingNetwork` has been removed. Logging calls are now made from the `DefaultNetwork` class. In addition, the logging format strings in this class have changed in a way that will break logging for any applications that have overridden any of these strings. They now use keyword format placeholders instead of positional placeholders. All custom format strings will now have to use the same keyword format placeholders. Though this is a breaking change, the good news is that using keyword format placeholders means that any future changes will be automatically backwards-compatibile (as long as there aren't any changes to change/remove any of the keywords). `File.update_contents()` and `File.update_contents_with_stream()` now correctly return a `File` object with the correct internal JSON structure. Previously it would return a `File` object where the file JSON is hidden inside `file['entries'][0]`. This is a bugfix, but will be a breaking change for any clients that have already written code to handle the bug. Comparing two objects (e.g. a `File` and a `Folder`) that have the same Box ID but different types with `==` will now correctly return `False`. The following methods now return iterators over the entire collection of returned objects, rather than a single page: - `client.users()` - `client.groups()` - `client.search().query()` - `folder.get_items()` Since `folder.get_items()` now returns an iterator, `folder.get_items_limit_offset()` and `folder.get_items_marker()` have been removed. To use marker based paging with `folder.get_items()`, pass the `use_marker=True` parameter and optionally specify a `marker` parameter to begin paging from that point in the collection. Additionally, `group.membership()` has been renamed to `group.get_memberships()`, and returns an iterator of membership objects. This method no longer provides the option to return tuples with paging information. The `Translator` class has been reworked; `translator.get(...)` still returns the constructor for the object class corresponding to the passed in type, but `translator.translate(...)` now takes a `Session` and response object directly and produces the translated object. This method will also translate any nested objects found. This change obviates the need for `GroupMembership` to have a custom constructor; it now uses the default `BaseObject` constructor. ### Features All publicly documented API endpoints and parameters should now be supported by the SDK Added more flexibility to the object translation system: Can create non-global `Translator` instances, which can extend or not-extend the global default `Translator`. - Can initialize `BoxSession` with a custom `Translator`. Can register custom subclasses on the `Translator` which is associated with a `BoxSession` or a `Client`. All translation of API responses now use the `Translator` that is referenced by the `BoxSession`, instead of directly using the global default `Translator`. - Nested objects are now translated by `translator.translate()` When the `auto_session_renewal` is `True` when calling any of the request methods on `BoxSession`, if there is no access token, `BoxSession` will renew the token before making the request. This saves an API call. Auth objects can now be closed, which prevents them from being used to request new tokens. This will also revoke any existing tokens (though that feature can be disabled by passing `revoke=False`). Also introduces a `closing()` context manager method, which will auto-close the auth object on exit. Various enhancements to the `JWTAuth` baseclass: The `authenticate_app_user()` method is renamed to `authenticate_user()`, to reflect that it may now be used to authenticate managed users as well. See the method docstring for details. `authenticate_app_user()` is now an alias of `authenticate_user()`, in order to not introduce an unnecessary backwards-incompatibility. The `user` argument to `authenticate_user()` may now be either a user ID string or a `User` instance. Before it had to be a `User` instance. The constructor now accepts an optional `user` keyword argument, which may be a user ID string or a `User` instance. When this is passed, `authenticate_user()` and can be called without passing a value for the `user` argument. More importantly, this means that `refresh()` can be called immediately after construction, with no need for a manual call to `authenticate_user()`. Combined with the aforementioned improvement to the `auto_session_renewal` functionality of `BoxSession`, this means that authentication for `JWTAuth` objects can be done completely automatically, at the time of first API call. The constructor now supports passing the RSA private key in two different ways: by file system path (existing functionality), or by passing the key data directly (new functionality). The `rsa_private_key_file_sys_path` parameter is now optional, but it is required to pass exactly one of `rsa_private_key_file_sys_path` or `rsa_private_key_data`. Document that the `enterprise_id` argument to `JWTAuth` is allowed to be `None`. `authenticate_instance()` now accepts an `enterprise` argument, which can be used to set and authenticate as the enterprise service account user, if `None` was passed for `enterprise_id` at construction time. Authentications that fail due to the expiration time not falling within the correct window of time are now automatically retried using the time given in the Date header of the Box API response. This can happen naturally when the system time of the machine running the Box SDK doesn't agree with the system time of the Box API servers. Added an `Event` class. Moved `metadata()` method to `Item` so it's now available for `Folder` as well as `File`. The `BaseAPIJSONObject` baseclass (which is a superclass of all API response objects) now supports `__contains__` and `__iter__`. They behave the same as for `Mapping`. That is, `__contains__` checks for JSON keys in the object, and `__iter__` yields all of the object's keys. Added a `RecentItem` class. Added `client.get_recent_items()` to retrieve a user's recently accessed items on Box. Added support for the `can_view_path` parameter when creating new collaborations. Added `BoxObjectCollection` and subclasses `LimitOffsetBasedObjectCollection` and `MarkerBasedObjectCollection` to more easily manage paging of objects from an endpoint. These classes manage the logic of constructing requests to an endpoint and storing the results, then provide `__next__` to easily iterate over the results. The option to return results one by one or as a `Page` of results is also provided. Added a `downscope_token()` method to the `Client` class. This generates a token that has its permissions reduced to the provided scopes and for the optionally provided `File` or `Folder`. Added methods for configuring `JWTAuth` from config file: `JWTAuth.from_settings_file` and `JWTAuth.from_settings_dictionary`. Added `network_response` property to `BoxOAuthException`. API Configuration can now be done per `BoxSession` instance. ### Other - Added extra information to `BoxAPIException`. - Added `collaboration()` method to `Client`. Reworked the class hierarchy. Previously, `BaseEndpoint` was the parent of `BaseObject` which was the parent of all smart objects. Now `BaseObject` is a child of both `BaseEndpoint` and `BaseAPIJSONObject`. `BaseObject` is the parent of all objects that are a part of the REST API. Another subclass of `BaseAPIJSONObject`, `APIJSONObject`, was created to represent pseudo-smart objects such as `Event` that are not directly accessible through an API endpoint. Added `network_response_constructor` as an optional property on the `Network` interface. Implementations are encouraged to override this property, and use it to construct `NetworkResponse` instances. That way, subclass implementations can easily extend the functionality of the `NetworkResponse`, by re-overriding this property. This property is defined and used in the `DefaultNetwork` implementation. Move response logging to a new `LoggingNetworkResponse` class (which is made possible by the aforementioned `network_response_constructor` property). Now the SDK decides whether to log the response body, based on whether the caller reads or streams the content. Add more information to the request/response logs from `LoggingNetwork`. - Add logging for request exceptions in `LoggingNetwork`. Bugfix so that the return value of `JWTAuth.refresh()` correctly matches that of the auth interface (by returning a tuple of ((access token), (refresh token or None)), instead of just the access token). In particular, this fixes an exception in `BoxSession` that always occurred when it tried to refresh any `JWTAuth` object. Fixed an exception that was being raised from `ExtendableEnumMeta.__dir__()`. - CPython 3.6 support. - Increased required minimum version of six to 1.9.0. ## [1.5.3] (2016-05-26) Bugfix so that `JWTAuth` opens the PEM private key file in `'rb'` mode. ## [1.5.2] (2016-05-19) Bugfix so that `OAuth2` always has the correct tokens after a call to `refresh()`. ## [1.5.1] (2016-03-23) Added a `revoke()` method to the `OAuth2` class. Calling it will revoke the current access/refresh token pair. ## [1.5.0] (2016-03-17) Added a new class, `LoggingClient`. It's a `Client` that uses the `LoggingNetwork` class so that requests to the Box API and its responses are logged. Added a new class, `DevelopmentClient` that combines `LoggingClient` with the existing `DeveloperTokenClient`. This client is ideal for exploring the Box API or for use when developing your application. Made the `oauth` parameter to `Client` optional. The constructor now accepts new parameters that it will use to construct the `OAuth2` instance it needs to auth with the Box API. Changed the default User Agent string sent with requests to the Box API. It is now 'box-python-sdk-<version>'. Box objects have an improved `__repr__`, making them easier to identify during debugging sessions. Box objects now implement `__dir__`, making them easier to explore. When created with a Box API response, these objects will now include the API response fields as attributes. ## [1.4.2] (2016-02-23) Make sure that `__all__` is only defined once, as a list of `str`. Some programs (e.g. PyInstaller) naively parse __init__.py files, and if `__all__` is defined twice, the second one will be ignored. This can cause `__all__` to appear as a list of `unicode` on Python 2. Create wheel with correct conditional dependencies and license file. Change the `license` meta-data from the full license text, to just a short string, as specified in [1][2]. [1] <[https://docs.python.org/3.5/distutils/setupscript.html#additional-meta-data](https://docs.python.org/3.5/distutils/setupscript.html#additional-meta-data)> [2] <[https://www.python.org/dev/peps/pep-0459/#license](https://www.python.org/dev/peps/pep-0459/#license)> Include entire test/ directory in source distribution. test/__init__.py was previously missing. Update documentation. ## [1.4.1] (2016-02-11) - Files now support getting a direct download url. ## [1.4.0] (2016-01-05) - Added key id parameter to JWT Auth. ## [1.3.3] (2016-01-04) ### Bugfixes Fixed import error for installations that don't have redis installed. Fixed use of `raw_input` in the developer token auth for py3 compatibility. ## [1.3.3] (2015-12-22) Added a new class, `DeveloperTokenClient` that makes it easy to get started using the SDK with a Box developer token. It uses another new class, `DeveloperTokenAuth` for auth. ### Bugfixes Added limit, offset, and filter_term parameters to `client.users()` to match up with the Box API. ## [1.3.2] (2015-11-16) - Fix `boxsdk.util.log.setup_logging()` on Python 3. ## [1.3.1] (2015-11-06) Add requests-toolbelt to setup.py (it was accidentally missing from 1.3.0). ## [1.3.0] (2015-11-05) - CPython 3.5 support. - Support for cryptography>=1.0 on PyPy 2.6. - Travis CI testing for CPython 3.5 and PyPy 2.6.0. - Added a logging network class that logs requests and responses. Added new options for auth classes, including storing tokens in Redis and storing them on a remote server. - Stream uploads of files from disk. ## [1.2.2] (2015-07-22) - The SDK now supports setting a password when creating a shared link. ## [1.2.1] (2015-07-22) ### Bugfixes Fixed an ImportError for installs that didn't install the [jwt] extras. ## [1.2.0] (2015-07-13) Added support for Box Developer Edition. This includes JWT auth (auth as enterprise or as app user), and `create_user` functionality. - Added support for setting shared link expiration dates. - Added support for setting shared link permissions. Added support for 'As-User' requests. See [https://developer.box.com/en/guides/authentication/oauth2/as-user/](https://developer.box.com/en/guides/authentication/oauth2/as-user/) Improved support for accessing shared items. Items returned from the `client.get_shared_item` method will remember the shared link (and the optionally provided shared link password) so methods called on the returned items will be properly authorized. ## [1.1.7] (2015-05-28) - Add context_info from failed requests to BoxAPIException instances. ### Bugfixes `Item.remove_shared_link()` was trying to return an incorrect (according to its own documentation) value, and was also attempting to calculate that value in a way that made an incorrect assumption about the API response. The latter problem caused invocations of the method to raise TypeError. The method now handles the response correctly, and correctly returns type `bool`. ## [1.1.6] (2015-04-17) - Added support for the Box accelerator API for premium accounts. ## [1.1.5] (2015-04-03) - Added support for preflight check during file uploads and updates. ## [1.1.4] (2015-04-01) - Added support to the search endpoint for metadata filters. Added support to the search endpoint for filtering based on result type and content types. ## [1.1.3] (2015-03-26) Added support for the /shared_items endpoint. `client.get_shared_item` can be used to get information about a shared link. See [https://developers.box.com/docs/#shared-items](https://developers.box.com/docs/#shared-items) ## [1.1.2] (2015-03-20) ### Bugfixes Certain endpoints (e.g. search, get folder items) no longer raise an exception when the response contains items that are neither files nor folders. ## [1.1.1] (2015-03-11) A minor change to namespacing. The `OAuth2` class can now be imported directly from `boxsdk`. Demo code has been updated to reflect the change. ## [1.1.0] (2015-03-02) ### Features The SDK now supports Box metadata. See the metadata docs for more information. The object paging API has been improved. SDK extensions that need fine-grained control over when the next "page" of API results will be fetched can now do that. ### Example Code The example code has been improved to be more robust and to work with all Python versions supported by the SDK (CPython 2.6-2.7, CPython 3.3-3.4, and PyPy). The example code has an example on how to use the new metadata feature. - The README has improved code examples. ### Bugfixes Oauth2 redirect URIs containing non-ASCII characters are now supported. --- ### Changelog **Type:** page | **Section:** Additional Resources Changelog All notable changes to this project will be documented in this file. See standard-version for commit guidelines. 5.8.0 (2024-07-2… # Changelog All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines. ## 5.8.0 (2024-07-22) ### New Features and Enhancements: - add support for AI ([#965](https://github.com/box/box-windows-sdk-v2/issues/965)) ([a9e130a](https://github.com/box/box-windows-sdk-v2/commit/a9e130a99cf9862f9b50178a6188b2820f9f2c32)) ### Bug Fixes: - Bump `System.IdentityModel.Tokens.Jwt` dependency version to `v6.35.0` ([#962](https://github.com/box/box-windows-sdk-v2/issues/962)) ([6e47237](https://github.com/box/box-windows-sdk-v2/commit/6e472378e2fccea2db67bf5ef0eb017a31491703)), closes [#960](https://github.com/box/box-windows-sdk-v2/issues/960) [#961](https://github.com/box/box-windows-sdk-v2/issues/961) - remove `Microsoft.AspNetCore.StaticFiles` and `System.Web` dependencies ([#964](https://github.com/box/box-windows-sdk-v2/issues/964)) ([2c8eedc](https://github.com/box/box-windows-sdk-v2/commit/2c8eedc91c473aca52249aad443345471ca7eafc)) ### 5.7.1 (2024-06-28) ### Bug Fixes: - Add missing enum values to `BoxSortBy` ([#953](https://github.com/box/box-windows-sdk-v2/issues/953)) ([1f89bb0](https://github.com/box/box-windows-sdk-v2/commit/1f89bb047442dcdc9045aeff1c3d6aadf61e2856)), closes [#952](https://github.com/box/box-windows-sdk-v2/issues/952) - Add missing fields of `EventSource` ([#956](https://github.com/box/box-windows-sdk-v2/issues/956)) ([138eda5](https://github.com/box/box-windows-sdk-v2/commit/138eda516ad59f08968d88b04e9bb06df3c397f2)) - do not recreate Random each time ([#945](https://github.com/box/box-windows-sdk-v2/issues/945)) ([d03b1ce](https://github.com/box/box-windows-sdk-v2/commit/d03b1ce65d4077e2895acfce3bc286ea501669aa)), closes [#944](https://github.com/box/box-windows-sdk-v2/issues/944) [#944](https://github.com/box/box-windows-sdk-v2/issues/944) [#944](https://github.com/box/box-windows-sdk-v2/issues/944) [#944](https://github.com/box/box-windows-sdk-v2/issues/944) ## 5.7.0 (2024-02-27) ### New Features and Enhancements: - add marker-based pagination version of `GetFolderItems` ([#936](https://github.com/box/box-windows-sdk-v2/issues/936)) ([f877a8f](https://github.com/box/box-windows-sdk-v2/commit/f877a8f9105d65a3e3ca459fcbf4a1bb653ff0f3)) - Support sign request signer group ID ([#938](https://github.com/box/box-windows-sdk-v2/issues/938)) ([096a098](https://github.com/box/box-windows-sdk-v2/commit/096a09805b189c591289e77ae5f8a8e6f1b466f1)) ### Bug Fixes: - Remove delete classification ([#932](https://github.com/box/box-windows-sdk-v2/issues/932)) ([fb59489](https://github.com/box/box-windows-sdk-v2/commit/fb594897850ad9daacf75cab702f3765cc7168c0)) ### 5.6.1 (2023-11-29) ### Bug Fixes: - support object value in `BoxConflictErrorContextInfo` ([#930](https://github.com/box/box-windows-sdk-v2/issues/930)) ([496f758](https://github.com/box/box-windows-sdk-v2/commit/496f758c3436b1834188078027b7305ca6a98fce)) ## 5.6.0 (2023-09-25) ### New Features and Enhancements: - Support `iframeable_embed_url` for sign request ([#925](https://github.com/box/box-windows-sdk-v2/issues/925)) ([e9de994](https://github.com/box/box-windows-sdk-v2/commit/e9de994cea97afcc1c3bc52ddf1cc023b9ee731c)) ## 5.5.0 (2023-09-20) ### New Features and Enhancements: - Add shared link header support in file and folder managers ([#923](https://github.com/box/box-windows-sdk-v2/issues/923)) ([ffbfc72](https://github.com/box/box-windows-sdk-v2/commit/ffbfc72289c70cdd91ea500326944a40b89993e3)) ## 5.4.0 (2023-09-07) ### New Features and Enhancements: - Support Sign Templates and new Sign Request statuses ([#920](https://github.com/box/box-windows-sdk-v2/issues/920)) ([78580fb](https://github.com/box/box-windows-sdk-v2/commit/78580fbd3de553273970376b96bc28c7c5614a97)) ## 5.3.0 (2023-09-04) ### New Features and Enhancements: - add `attachment` content type to `SignRequestSigner` ([#913](https://github.com/box/box-windows-sdk-v2/issues/913)) ([ad612ff](https://github.com/box/box-windows-sdk-v2/commit/ad612ffc7821a9ecbc180e3dbeefe16d3e397820)) ### Bug Fixes: - replace deprecated `BouncyCastle` library ([#909](https://github.com/box/box-windows-sdk-v2/issues/909)) ([f00f2af](https://github.com/box/box-windows-sdk-v2/commit/f00f2af9c5277b42e6a62060c1b0229ecff0203e)) ### 5.2.2 (2023-05-23) ### Bug Fixes: - catch exception when .net core version cannot be determined ([#906](https://github.com/box/box-windows-sdk-v2/issues/906)) ([e3be209](https://github.com/box/box-windows-sdk-v2/commit/e3be209b20a5c323f547d7634663883613959180)) ### 5.2.1 (2023-04-18) ### Bug Fixes: - Catch all exceptions when getting User Agent header ([#901](https://github.com/box/box-windows-sdk-v2/issues/901)) ([75d8874](https://github.com/box/box-windows-sdk-v2/commit/75d887470698a5f312610cebd58be58aee7eaa9b)) ## 5.2.0 (2023-03-14) ### New Features and Enhancements: - add `Id` to `MetadataTemplateField` ([#890](https://github.com/box/box-windows-sdk-v2/issues/890)) ([b7fe214](https://github.com/box/box-windows-sdk-v2/commit/b7fe2149e1a0ade8573b497b7bb36e9f3c4f4a82)) - add `start_date_field` and `description` to retention policies ([#888](https://github.com/box/box-windows-sdk-v2/issues/888)) ([100b722](https://github.com/box/box-windows-sdk-v2/commit/100b722ce4909395c00b527677564f37a61ec2cb)) - add configurable `JWTAudience` claim ([#897](https://github.com/box/box-windows-sdk-v2/issues/897)) ([50219fd](https://github.com/box/box-windows-sdk-v2/commit/50219fdfd553d6335b6f0b4341719b09680c4ba0)) - add shared link support to `GetFolderItemsAsync` ([#892](https://github.com/box/box-windows-sdk-v2/issues/892)) ([0eba85c](https://github.com/box/box-windows-sdk-v2/commit/0eba85c693763472c51fe81cbc43222305e9eefb)) ### Bug Fixes: - Use fixed value of `aud` field in `JWT` claim ([#896](https://github.com/box/box-windows-sdk-v2/issues/896)) ([8c9982d](https://github.com/box/box-windows-sdk-v2/commit/8c9982d160ec4806c796ee2621b1811232ea59c1)) ## 5.1.0 (2023-01-17) ### New Features and Enhancements: - `BoxCCGAuth` add User and Admin clients factory methods without initial token ([#883](https://github.com/box/box-windows-sdk-v2/issues/883)) ([c1337fc](https://github.com/box/box-windows-sdk-v2/commit/c1337fc9d765bf7d4bc1757ea832bec92a602f76)) ## 5.0.0 (2023-01-12) ### ⚠ BREAKING CHANGES - upgrade .net framework to 4.6.2 (#881) - remove deprecated methods (#881) - remove `use_index` references (#881) - return proper object from `GetFileVersionsUnderRetentionForAssignmentAsync`(#881) ### New Features and Enhancements: - upgrade .net framework to 4.6.2 ([#881](https://github.com/box/box-windows-sdk-v2/issues/881)) ([f1989aa](https://github.com/box/box-windows-sdk-v2/commit/f1989aa94cd085ad4bec04b4ebedb04f40455569)), closes [#863](https://github.com/box/box-windows-sdk-v2/issues/863) - remove deprecated methods ([#881](https://github.com/box/box-windows-sdk-v2/issues/881)) ([f1989aa](https://github.com/box/box-windows-sdk-v2/commit/f1989aa94cd085ad4bec04b4ebedb04f40455569)), closes [#874](https://github.com/box/box-windows-sdk-v2/issues/874) - remove `use_index` references ([#881](https://github.com/box/box-windows-sdk-v2/issues/881)) ([f1989aa](https://github.com/box/box-windows-sdk-v2/commit/f1989aa94cd085ad4bec04b4ebedb04f40455569)), closes [#870](https://github.com/box/box-windows-sdk-v2/issues/870) ### Bug Fixes: - Added pagination option to `IBoxFilesManager#ViewVersionsAsync` ([#869](https://github.com/box/box-windows-sdk-v2/issues/869)) ([2324495](https://github.com/box/box-windows-sdk-v2/commit/232449531440227a0c8b3489ceda813fe4f4a73f)), closes [#866](https://github.com/box/box-windows-sdk-v2/issues/866) - return proper object from `GetFileVersionsUnderRetentionForAssignmentAsync` ([#881](https://github.com/box/box-windows-sdk-v2/issues/881)) ([f1989aa](https://github.com/box/box-windows-sdk-v2/commit/f1989aa94cd085ad4bec04b4ebedb04f40455569)), closes [#875](https://github.com/box/box-windows-sdk-v2/issues/875) ## 4.6.0 (2022-10-18) ### New Features and Enhancements: - Add `redirect_url` and `declined_redirect_url` to Sign Request ([#853](https://github.com/box/box-windows-sdk-v2/issues/853)) ([5ef2f18](https://github.com/box/box-windows-sdk-v2/commit/5ef2f18985d8c3b8e7c0cdba5709785bfb1d5f34)) - Add support for modifiable retention policies & enable deleting retention policy assignment ([#856](https://github.com/box/box-windows-sdk-v2/issues/856)) ([564904f](https://github.com/box/box-windows-sdk-v2/commit/564904fa2ce0b1881a2f07b80cc3bb3e648310d0)) ## 4.5.0 (2022-08-24) ### New Features and Enhancements: - Add `content-type` field to sign request ([#850](https://github.com/box/box-windows-sdk-v2/issues/850)) ([054d3e1](https://github.com/box/box-windows-sdk-v2/commit/054d3e1a5f44b6a4a0292e8f9444266b2de0fff0)) - expose `effective_access` in `BoxSharedLink` [#843](https://github.com/box/box-windows-sdk-v2/issues/843) ([d84ddd4](https://github.com/box/box-windows-sdk-v2/commit/d84ddd48aac489ecdd1d9dc740a7672cb064b0ca)) ### Bug Fixes: - fix null reference exception when it's not possible to get `runtime` version from the assembly ([#851](https://github.com/box/box-windows-sdk-v2/issues/851)) ([77046fb](https://github.com/box/box-windows-sdk-v2/commit/77046fb0c1ce80b6e7e2dc30058ed275e46e990c)) - replace infinite retries with exponential backoff strategy in file representations ([#835](https://github.com/box/box-windows-sdk-v2/issues/835)) ([f2a5713](https://github.com/box/box-windows-sdk-v2/commit/f2a57136078de8b1fc59ec2c4a9e98c062d9d19b)) ## 4.4.0 (2022-06-14) ### New Features and Enhancements: - add `can_edit` field to `SharedLink` ([#831](https://github.com/box/box-windows-sdk-v2/issues/831)) ([e0d4197](https://github.com/box/box-windows-sdk-v2/commit/e0d4197070db0dbd947f4a51a6bbb1e01c0b0cdf)) - add `version_number` to `BoxFileVersion` ([#820](https://github.com/box/box-windows-sdk-v2/issues/820)) ([f174358](https://github.com/box/box-windows-sdk-v2/commit/f174358973caefc9262df480208341fd8233dc7f)) - add upload and delete support for Avatar API ([#829](https://github.com/box/box-windows-sdk-v2/issues/829)) ([4dcb84a](https://github.com/box/box-windows-sdk-v2/commit/4dcb84ade78d6bd0bc621ff2ed7f5f886486858a)) ### Bug Fixes: - Fix initialization of `BoxAPIException` object ([#828](https://github.com/box/box-windows-sdk-v2/issues/828)) ([a298f01](https://github.com/box/box-windows-sdk-v2/commit/a298f01187f84200825ec6ed4748fe8bbd717d11)) - properly dispose response on exception ([#819](https://github.com/box/box-windows-sdk-v2/issues/819)) ([8415bd3](https://github.com/box/box-windows-sdk-v2/commit/8415bd3dbe42910b99f99535247a26f8d8e645c1)) ### 4.3.1 (2022-04-19) ### Bug Fixes: - simplify base `urls` usage ([#815](https://github.com/box/box-windows-sdk-v2/issues/815)) ([f8e7344](https://github.com/box/box-windows-sdk-v2/commit/f8e73447afa5c0a893c3c4ace922fc360a376f66)) ## 4.3.0 (2022-04-01) ### New Features and Enhancements: - add `SourceLink` support for Core project ([#795](https://github.com/box/box-windows-sdk-v2/issues/795)) ([a9cbede](https://github.com/box/box-windows-sdk-v2/commit/a9cbedece2ffb4f832be880bebf35b715c9cb28b)) ### Bug Fixes: - add missing enum to string parsing in several places ([#813](https://github.com/box/box-windows-sdk-v2/issues/813)) ([e370282](https://github.com/box/box-windows-sdk-v2/commit/e3702826216132dfe1fb061af95a8d9700f114d4)) - properly cast response when uploading a new file version using session ([#810](https://github.com/box/box-windows-sdk-v2/issues/810)) ([73d877f](https://github.com/box/box-windows-sdk-v2/commit/73d877ff679b5999ea50cdfa68f14b0e2169ea65)) ## 4.2.0 (2022-02-10) ### Bug Fixes: - correctly pass null when rolling out user from the enterprise ([#792](https://github.com/box/box-windows-sdk-v2/issues/792)) ([c85c573](https://github.com/box/box-windows-sdk-v2/commit/c85c5735865b7dd97ffa1428a8f57d2edff6811b)) - Creating BoxAuthenticationFailedException no longer throws an exception ([#790](https://github.com/box/box-windows-sdk-v2/issues/790)) ([55a706e](https://github.com/box/box-windows-sdk-v2/commit/55a706e4091271aa55208a260b2f4f96e1527698)) - Null Argument Exception in AutoPaginate ([#666](https://github.com/box/box-windows-sdk-v2/issues/666)) ([c61f08c](https://github.com/box/box-windows-sdk-v2/commit/c61f08cc02d5c95ff71ef700e97393a0dc3dc890)) ### New Features and Enhancements: - add admin_logs_streaming support ([#797](https://github.com/box/box-windows-sdk-v2/issues/797)) ([a775e1e](https://github.com/box/box-windows-sdk-v2/commit/a775e1e5c7696a1e5f82b5dc7edbed8eb09f640d)) - add Client Credentials Grant auth support ([#799](https://github.com/box/box-windows-sdk-v2/issues/799)) ([b8a64ca](https://github.com/box/box-windows-sdk-v2/commit/b8a64ca3887298feccef5185f6bfec4c3771b5a9)) - add disposition_at field to the File object ([#793](https://github.com/box/box-windows-sdk-v2/issues/793)) ([2766a91](https://github.com/box/box-windows-sdk-v2/commit/2766a914fad1eb40371cd4430b3450360088b331)) - add possibility to set auth token uri in BoxConfig ([#794](https://github.com/box/box-windows-sdk-v2/issues/794)) ([ae8cd8b](https://github.com/box/box-windows-sdk-v2/commit/ae8cd8b91dd91b8a786e53ff5b3501d2700686a4)) - deprecate index_name in ExecuteMetadataQuery ([#800](https://github.com/box/box-windows-sdk-v2/issues/800)) ([6a6a0e4](https://github.com/box/box-windows-sdk-v2/commit/6a6a0e4a0e41ec70ec33acacba00bee6c7ee881f)) ## 4.1.0 (2021-12-14) ### Bug Fixes: - add missing configureAwait(false) when awaiting to prevent deadlocks ([#775](https://github.com/box/box-windows-sdk-v2/issues/775)) ([b16267e](https://github.com/box/box-windows-sdk-v2/commit/b16267e8f3dca5396e87be660e30a1e9405d8139)) ### New Features and Enhancements: - add configurable Timeout for BoxClient ([#779](https://github.com/box/box-windows-sdk-v2/issues/779)) ([ac842ed](https://github.com/box/box-windows-sdk-v2/commit/ac842ed4ba1a2dfe499706524441bc6ae3b3c192)) - add file request api ([#777](https://github.com/box/box-windows-sdk-v2/issues/777)) ([1098f75](https://github.com/box/box-windows-sdk-v2/commit/1098f75983e2d784521f13b8d53df0e55d03203b)) - add vanity_name to SharedLink ([#782](https://github.com/box/box-windows-sdk-v2/issues/782)) ([00a1e26](https://github.com/box/box-windows-sdk-v2/commit/00a1e265569d76c2c9593aa259202d7febef629c)) ## 4.0.0 (2021-11-02) ### Breaking changes: - Extract interfaces for BoxClient and Managers to improve testability ([#603](https://github.com/box/box-windows-sdk-v2/pull/603)) - Add BoxConfigBuilder and make BoxConfig immutable ([#737](https://github.com/box/box-windows-sdk-v2/pull/737)) - Expose tasks from async methods ([#742](https://github.com/box/box-windows-sdk-v2/pull/742)) - Use DateTimeOffset instead of DateTime ([#749](https://github.com/box/box-windows-sdk-v2/pull/749)) - Rework returned exceptions ([#753](https://github.com/box/box-windows-sdk-v2/pull/753)) - Upgrade .NET Standard to 2.0 ([#755](https://github.com/box/box-windows-sdk-v2/pull/755)) ### New Features and Enhancements: - Add ability to get files under retention for assignment and file versions under retention for assignment ([#734](https://github.com/box/box-windows-sdk-v2/pull/734)) - Add `is_collaboration_restricted_to_enterprise` flag support for `Folder` update ([#732](https://github.com/box/box-windows-sdk-v2/pull/732)) - Replace insensitive language ([#738](https://github.com/box/box-windows-sdk-v2/pull/738)) - Add new, easier to use method for create terms of service user status ([#740](https://github.com/box/box-windows-sdk-v2/pull/740)) - Allow sort and direction parameter to be passed in when getting trashed items ([#754](https://github.com/box/box-windows-sdk-v2/pull/754)) - Add support for Task completion_rule field ([#758](https://github.com/box/box-windows-sdk-v2/pull/758)) - Add BoxSign API support ([#765](https://github.com/box/box-windows-sdk-v2/pull/765)) ### Bug Fixes: - Fix `Cannot access a closed Stream.Request` exception during upload ([#739](https://github.com/box/box-windows-sdk-v2/pull/739)) ([#757](https://github.com/box/box-windows-sdk-v2/pull/757)) ## 3.26.0 [2021-04-01] **New Features and Enhancements:** - Add filter fields to get file version retentions ([#717](https://github.com/box/box-windows-sdk-v2/pull/717)) - Add support for search param to get shared link items ([#721](https://github.com/box/box-windows-sdk-v2/pull/721)) - Add folder lock functionality ([#725](https://github.com/box/box-windows-sdk-v2/pull/725)) ## 3.25.0 [2020-10-19] **New Features and Enhancements:** - Add support for filtering when getting Groups (#703) - Add zip functionality (#700) - Deprecate one of the overloaded `ExecuteMetadataQueryAsync()` methods (#699) - Add support for `copyInstanceOnItemCopy` field for metadata templates (#698) **Bug Fixes:** - Fix bug with JWT Authentication automatic retry (#697) ## 3.24.0 [2020-07-21] - Add path parameter sanitization - Add support for the classification field for Files and Folders - Fix bug with notification email field deserializing for `BoxUser` - Add `fields` parameter for metadata query - Add ability to set a request timeout for `FoldersManager.UpdateInformationAsync()` and `UsersManager.MoverUserFolderAsync()` ## 3.23.0 [2020-05-12] - Add ability to get and set a notification email address for a user - Fix deadlock issue for JWT authentication in UI elements - Add support for the uploader display name field for Files and File Versions ## 3.22.0 [2020-02-25] - Fixed Authentication Request Retries - Added the ability to query Box items based on their metadata. The method to do so is `MetadataManager.ExecuteMetadataQueryAsync()`. - Added `TrashedAt` field to `BoxItem` objects (file, folder, weblink). - Added marker based pagination for get users methods - Updated retry logic to retry on 503 status codes returned by the API - Provide better details for debugging, if the HttpClient used to make API requests times out ## 3.21.0 [2019-12-05] - Added `fields` parameter to `UsersManager.GetUserInformationAsync()` - Added `ExternalAppUserId` property to `BoxUser` model - Added the ability to set the `TrackingCodes` property when updating or creating a user (thanks @Cpcrook!) ## 3.20.0 [2019-09-19] - Added missing fields for File Version object. ## 3.19.0 [2019-08-29] - Added `FILE_VERSION_RESTORE` constant to Admin Event. - Added action_by field to Enterprise Event. - Audited missing fields on BoxFile and BoxFolder objects. - Better error handling and messaging for errors pertaining to OAuth2 error responses. ## 3.18.0 [2019-06-20] Added `sort` and `direction` parameters to `FoldersManager.GetFolderItemsAsync()` to enable sorting the folder items returned - Added a new `SearchManager.QueryAsync()` method with correct types for file size filter parameters - Deprecated the `SearchManager.SearchAsync()` method, which is superseded by `SearchManager.QueryAsync()` - Added support for setting the `IsExternalCollabRestricted` parameter when creating and updating Users Added a `WebProxy` property to `BoxConfig` instances, which can be used to manually set the network proxy used by the SDK ## 3.17.0 [2019-05-09] - Fixed the encoding of dates in the query parameters for Events and Search endpoints - Deprecated `FilesManager.DownloadStreamAsync()` and introduced a replacement method with correct parameter types for byte offsets: `FilesManager.DownloadAsync()` ## 3.16.0 [2019-04-29] - Added `sort` and `direction` parameters to `client.SearchManager.SearchAsync()` to control sort order - Added `extension` parameter to `client.FilesManager.GetThumbnailAsync()` to control which thumbnail format is returned (thanks @guilmori!) - Fixed a bug where query string parameters were not correctly encoded Added `SetFileMetadataAsync()` and `SetFolderMetadataAsync()` methods to `client.MetadataManager` to set metadata keys and values, overwriting existing values for the provided keys. - Automatically retry most API calls when the API responds with a transient error status code ## 3.15.0 [2019-03-28] - Added support for passing custom IBoxService to BoxJWTAuth constructor. ## 3.14.1 [2019-03-07] - Removed unnecessary package.config from sample files. ## 3.14.0 [2019-02-28] - Added trace ID to API response exception message. - Fix deserialization of translated task assignment status. ## 3.13.1 [2019-02-21] - Fixed an issue where some objects related to Events did not have their `.Id` property correctly deserialized from JSON ## 3.13.0 [2019-02-14] Added the `.InviteEmail` property to `BoxCollaboration` objects, which displays the email address for the invited user in a pending collaboration - Added `.Timezone`, `.IsExternalCollabRestricted`, `.Tags`, and `.Hostname` properties to `BoxUser` objects ## 3.12.0 [2019-02-07] Added `client.FilesManager.GetCollaborationsCollectionAsync()` and deprecated `client.FilesManager.GetCollaborationsAsync()` to enable paging through the entire collection of collaborations on a file Added `client.WebLinksManager.CopyAsync()`, `client.WebLinksManager.CreateSharedLinkAsync()`, and `client.WebLinksManager.DeleteSharedLinkAsync()` - Added `client.UsersManager.GetUserAvatarAsync()` for retrieving a user's avatar image ## 3.11.0 [2019-01-17] - Added support for reading and writing more Group fields - Fixed an issue where the `UnsharedAt` field of a shared link could not be set to `null` - Fixed renaming a file on new version upload - Added the ability to set the content modification timestamp on file version upload - Fixed issues around reading the source of an event when the source item is a web link ## 3.10.0 [2018-12-14] - Added support for Metadata Cascade Policies ## 3.9.3 [2018-09-04] - Strong named the assembly. ## 3.9.2 [2018-06-14] - Added support for [setting flag](https://github.com/box/box-windows-sdk-v2/blob/main/Box.V2/Models/Request/BoxFolderRequest.cs#L39) allowing non owners of a folder to invite collaborators. ## 3.9.1 [2018-06-07] - Fixed bug where Xamarin applications would run out of connections ## 3.9.0 [2018-05-10] - Added support for Storage Policies ## 3.8.0 [2018-04-30] - Fixed an issue where users could not create `BoxClient` on Xamarin - Added `File` property to `BoxLock` objects in events - Added `MetadataManager.DeleteMetadataTemplate(string scope, string template)` for deleting a Metadata template - Made API URLs modifiable in `BoxConfig` - Improved API response error objects/messages ## 3.7.0 [2018-04-10] - Added support for assigning a Retention Policy to a metadata template - Added `CONTENT_ACCESS` event type to enum ## 3.6.0 [2018-03-27] - Fixed an issue where a "Security protocol not supported" exception could be thrown on MacOS - Added `client.FilesManager.GetRepresentationContentAsync()` for fetching a stream over representation contents - Fixed parsing of some `Source` objects on `BoxEvent` objects ## 3.5.2 [2018-03-21] - Switched to exponential backoff when the SDK receives a rate limit or server error response. - Force support for TLSv1.1 or higher when available to improve the security of connections to the Box API. - Perform modified retry on JWT auth for when the local clock and the Box Server clock are not aligned as well as if the JWT ID has already been consumed. - Made `name` parameter optional on `RestoreTrashedAsync()`. ## 3.4.2 [2018-01-31] - Deprecated `uploadFileVersionUsingSessionAsync()`(which returned just a Box File Version) in favor of `uploadNewVersionUsingSessionAsync()`(which returns the entire Box File object containing the Box File Version). - Added support for OAuth2 access token creation type to the AdminEventTypesEnum - Added `ExpiresAt` param to `BoxCollaborationRequest`. ## 3.4.1 [2018-01-09] - Added support for [Collaboration Whitelist](https://github.com/box/box-windows-sdk-v2/blob/main/Box.V2/Managers/BoxCollaborationWhitelistManager.cs) endpoint - Added [Event Types Enum](https://github.com/box/box-windows-sdk-v2/blob/main/Box.V2/Config/Constants.cs#L287) - Fixed deserialization issue with BoxRepresentationStatus (#429) ## 3.3.0 [2017-11-22] - Added support for [Terms of Service](https://github.com/box/box-windows-sdk-v2/blob/main/Box.V2/Managers/BoxTermsOfServiceManager.cs) endpoint - Added support for [Metadata Template ID](https://github.com/box/box-windows-sdk-v2/blob/main/Box.V2/Managers/BoxMetadataManager.cs#L175) endpoint - Added missing fields for Folder Model (#414) ## 3.2.0 [2017-10-04] - Added support for [Representations](https://github.com/box/box-windows-sdk-v2/blob/main/Box.V2/Managers/BoxFilesManager.cs#L1216) endpoint - Added support for [Chunked Upload New File Version](https://github.com/box/box-windows-sdk-v2/blob/main/Box.V2/Managers/BoxFilesManager.cs#L423) - Fixed BoxEventsManager DateTime formatter (#400) ## 3.1.0 [2017-08-18] - Added Unified Metadata Support (#379) ## 3.0.0 [2017-07-28] - Major version bump to 3, targeting net45 - Upgrading the whole sln to vs2017 - Added support for [Recents](https://github.com/box/box-windows-sdk-v2/blob/main/Box.V2/Managers/BoxRecentItemsManager.cs#L1) endpoint - New operation on [Metadata](https://github.com/box/box-windows-sdk-v2/blob/main/Box.V2/Managers/BoxMetadataManager.cs#L1) endpoint - Progress on [Chunked Upload New File](https://github.com/box/box-windows-sdk-v2/blob/main/Box.V2/Managers/BoxFilesManager.cs#L463) - Minor bug fixes --- ### Changelog **Type:** page | **Section:** Additional Resources Changelog All notable changes to this project will be documented in this file. See standard-version for commit guidelines. 5.6.0 (2024-04-0… # Changelog All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines. ## 5.6.0 (2024-04-05) ### New Features and Enhancements - Add privacy manifest files ([#924](https://github.com/box/box-ios-sdk/issues/924)) ([cbef168](https://github.com/box/box-ios-sdk/commit/cbef168bb872941899be26116c647ac29f5dd44b)) - Add support for `visionOS` ([#916](https://github.com/box/box-ios-sdk/issues/916)) ([a05b243](https://github.com/box/box-ios-sdk/commit/a05b2433f1b2d0c1ec72f946e0706d03a4548703)) - Add support for additional fields in `SignRequest` ([#919](https://github.com/box/box-ios-sdk/issues/919)) ([36f464c](https://github.com/box/box-ios-sdk/commit/36f464c23a161f5d0fcc6858c3615d884ce8ee07)) - Make fields from `TokenInfo` publicly available ([#920](https://github.com/box/box-ios-sdk/issues/920)) ([eb26f47](https://github.com/box/box-ios-sdk/commit/eb26f47bbde6749f44f149e95b3610e41c16d2f2)) ## 5.5.0 (2023-08-08) ### New Features and Enhancements - Add missing values in `SignRequestSignerInputContentType` and `SignRequestStatus` along with the tests ([#907](https://github.com/box/box-ios-sdk/issues/907)) ([56a8250](https://github.com/box/box-ios-sdk/commit/56a82500c0abe648825d8300979601a25f792c84)) ### Bug Fixes - Identify iPhone Simulator on Apple Silicon ([#902](https://github.com/box/box-ios-sdk/issues/902)) ([7731a7f](https://github.com/box/box-ios-sdk/commit/7731a7f434add74e163a76511fe1e2a3f26517f7)) - Make code compatible with macOS. ([#900](https://github.com/box/box-ios-sdk/issues/900)) ([3b0016e](https://github.com/box/box-ios-sdk/commit/3b0016e44e674db0ea429273c03e5a29177372bf)) - Remove use of deprecated string scanner API. ([#901](https://github.com/box/box-ios-sdk/issues/901)) ([af5f0e5](https://github.com/box/box-ios-sdk/commit/af5f0e52d184fbd27f56d972fb93b3e543547773)) ### 5.4.2 (2023-04-19) ### Bug Fixes - An emoty string `nextMarker` should be treated as end-of-paging. ([#893](https://github.com/box/box-ios-sdk/issues/893)) ([49c17de](https://github.com/box/box-ios-sdk/commit/49c17de588fcffcd2d151ce9047ebc09965f80ce)) ### 5.4.1 (2023-02-24) ### Bug Fixes - Fix `listAssignments` and `assign` methods in `RetentionPolicyModule` ([#886](https://github.com/box/box-ios-sdk/issues/886)) ([b668888](https://github.com/box/box-ios-sdk/commit/b668888f35136dd1239526b70cc31a10bdd04744)) ## 5.4.0 (2022-11-08) ### New Features and Enhancements - Add `content_type` field to Sign Requests signer ([#871](https://github.com/box/box-ios-sdk/issues/871)) ([1ec5b01](https://github.com/box/box-ios-sdk/commit/1ec5b0149f01cd3a18f5cba39b77e01678655932)) - Add `redirect_url` and `declined_redirect_url` to Sign Request ([#870](https://github.com/box/box-ios-sdk/issues/870)) ([f94d988](https://github.com/box/box-ios-sdk/commit/f94d98862d2fdb2603f4684b963d29d04e0fdb3d)) - Add support for `sign` webhook triggers ([#875](https://github.com/box/box-ios-sdk/issues/875)) ([994bfaf](https://github.com/box/box-ios-sdk/commit/994bfaf3ead983f5014808f6c9e5ffe167ab8e42)) - Added method to remove retention policy assignment ([#873](https://github.com/box/box-ios-sdk/issues/873)) ([c5f146c](https://github.com/box/box-ios-sdk/commit/c5f146c960bb1f940418975078d83fb63ff3bdec)) - Added support for Modifiable Retention Policies ([#872](https://github.com/box/box-ios-sdk/issues/872)) ([e2b7a17](https://github.com/box/box-ios-sdk/commit/e2b7a178c6592c9f7d1e7ce691c215680b3f45d0)) ## 5.3.0 (2022-08-19) ### New Features and Enhancements - add `version_number` to `FileVersion` ([#853](https://github.com/box/box-ios-sdk/issues/853)) ([ac81667](https://github.com/box/box-ios-sdk/commit/ac81667ea409cbbe3de9be0c316c630ec6fbc2f5)) - Add support for async API in `FoldersModule` ([#851](https://github.com/box/box-ios-sdk/issues/851)) ([58b9dde](https://github.com/box/box-ios-sdk/commit/58b9dde412eddc76915c99b960702f4af95b62a4)) - Add support for file request API ([#867](https://github.com/box/box-ios-sdk/issues/867)) ([ec7813e](https://github.com/box/box-ios-sdk/commit/ec7813e31706c08aaaeac75debdba8d7802786cb)) - Add support for upload and delete Avatar API ([#863](https://github.com/box/box-ios-sdk/issues/863)) ([1e967f5](https://github.com/box/box-ios-sdk/commit/1e967f5a3eaafbeb894cf8289032ad8ce8664266)) - Add support of Editable Shared Link ([#861](https://github.com/box/box-ios-sdk/issues/861)) ([bc6ea18](https://github.com/box/box-ios-sdk/commit/bc6ea18bf2e10bebeb62401a55001139f05c76df)) - Expose `send()` method public in `BoxClient` ([#843](https://github.com/box/box-ios-sdk/issues/843)) ([23caaca](https://github.com/box/box-ios-sdk/commit/23caaca5b6fe8ec1b23470193bc011a62c66d49f)) ### Bug Fixes - Respect Content-Type coming from custom headers ([#841](https://github.com/box/box-ios-sdk/issues/841)) ([a7c69a7](https://github.com/box/box-ios-sdk/commit/a7c69a73c6142d4b82c718d2d311098dd2b70250)) ### 5.2.1 (2022-04-22) ### Bug Fixes - Expose fields from `BoxResponse` for custom API calls ([#833](https://github.com/box/box-ios-sdk/issues/833)) ([bae1536](https://github.com/box/box-ios-sdk/commit/bae1536236a22de198281012b0ee43c84b0e3485)) ## 5.2.0 (2022-03-18) ### New Features and Enhancements - Add `disposition_at` field to the `File` object ([#814](https://github.com/box/box-ios-sdk/issues/814)) ([3c90df0](https://github.com/box/box-ios-sdk/commit/3c90df038b9f490a9d38af85404fa1d6ddcd5d0d)) - Add support for Client Credentials Grant authentication method ([#821](https://github.com/box/box-ios-sdk/issues/821)) ([f6d7542](https://github.com/box/box-ios-sdk/commit/f6d75424e8c0d91517e3ffb8df67f77ad3f2374b)) ## 5.1.0 (2022-01-17) ### New Features and Enhancements - Allow to customize URL for the `OAuth2` authorization page ([#811](https://github.com/box/box-ios-sdk/issues/811)) ([1901d29](https://github.com/box/box-ios-sdk/commit/1901d296a2be4b0f2eef25eda06928aebc81de9a)) - **Events:** Add support for `admin_logs_streaming` stream type ([#800](https://github.com/box/box-ios-sdk/issues/800)) ([0a3118e](https://github.com/box/box-ios-sdk/commit/0a3118ef95c2eb42b0080d0352784849e85eb422)) - **RetentionPolicy:** New API for get files and file versions under retention ([#807](https://github.com/box/box-ios-sdk/issues/807)) ([38327f0](https://github.com/box/box-ios-sdk/commit/38327f09a92dba7827e1866940a643d624757762)) - **SharedLink:** add support for `vanity_name` ([#799](https://github.com/box/box-ios-sdk/issues/799)) ([3ea6eb2](https://github.com/box/box-ios-sdk/commit/3ea6eb2a1c2b713fd0769e93a2dc4ee51da695fd)) ### Bug Fixes - **SignRequest:** Fix encoding `date_value` to `yyyy-mm-dd` format in `prefillTag` ([#806](https://github.com/box/box-ios-sdk/issues/806)) ([4f902a4](https://github.com/box/box-ios-sdk/commit/4f902a47482de55ec69b5522e6cf5affd653b4c8)) ## 5.0.0 (2021-10-28) ### ⚠ BREAKING CHANGES - Update PagingIterator to return pages and simplify logic ([#737](https://github.com/box/box-ios-sdk/pull/737)) - Remove insensitive language field `collaborationWhiteList` in BoxClient. Use `collaborationAllowList` instead. ([#790](https://github.com/box/box-ios-sdk/pull/790)) ### New Features and Enhancements - Replace insensitive event types ([#785](https://github.com/box/box-ios-sdk/pull/785)) - Add SignAPI support ([#792](https://github.com/box/box-ios-sdk/pull/792)) ## 4.4.0 (2021-04-20) ### New Features and Enhancements - Add support for search param to get shared link items ([#756](https://github.com/box/box-ios-sdk/pull/756)) - Add support for folder lock functionality ([#759](https://github.com/box/box-ios-sdk/pull/759)) - Add support for copyInstanceOnItemCopy field for metadata templates ([#763](https://github.com/box/box-ios-sdk/pull/763)) - Add support for stream upload of new file versions and add support for 'If-Match' header when uploading new file versions ([#766](https://github.com/box/box-ios-sdk/pull/766)) - Add additional details field for `Event` model ([#770](https://github.com/box/box-ios-sdk/pull/770)) ### Bug Fixes - Pass only a scheme to iOS Authentication APIs ([#755](https://github.com/box/box-ios-sdk/pull/755)) - Update `listEnterpriseGroups()` to use documented parameter for filtering by name ([#757](https://github.com/box/box-ios-sdk/pull/757)) - Fix bug for OAuth where the callback is not called if token has been revoked ([#762](https://github.com/box/box-ios-sdk/pull/762)) ## 4.3.0 (2021-02-01) ### New Features and Enhancements - Add support for OAuth 2 custom callback URL ([#746](https://github.com/box/box-ios-sdk/pull/746)) - Add support for zip download ([#749](https://github.com/box/box-ios-sdk/pull/749)) ### Bug Fixes - Update gems to patch kramdown vulnerability ([#742](https://github.com/box/box-ios-sdk/pull/742)) - Update gems to patch activesupport vulnerability ([#745](https://github.com/box/box-ios-sdk/pull/745)) ## 4.2.0 (2020-11-16) ### New Features and Enhancements - Add error information to OAuth web session failures ### Bug Fixes - Fix bug with creating collaboration - Fix bug with getting enterprise events ## 4.1.0 (2020-05-15) ### New Features and Enhancements - Add ability to cancel uploads and downloads - Add support for the uploader display name field for Files and File Versions - Add support for the classification field for Files and Folders - Add path parameter sanitization ### Bug Fixes - Fix logging of API responses ## 4.0.0 (2020-02-13) ### ⚠ BREAKING CHANGES - Change `status` field for task assignments from a String to an Enum - Remove macOS, tvOS, and watchOS support ### New Features and Enhancements - Make authentication session classes `OAuth2Session`, `SingleTokenSession`, and `DelegatedAuthSession` public ## 3.1.0 (2020-01-09) ### New Features and Enhancements - Add shared link downscoping - Add closure parameter for progress of uploads and downloads - Add marker based pagination to list users endpoint ## 3.0.0 (2019-11-18) ### New Features and Enhancements - Added file specific icons for the Sample Apps. ## 3.0.0-rc.3 (2019-11-14) ### ⚠ BREAKING CHANGES - For Module methods that returned a collection of objects, changed from returning a PaginationIterator to returning a PagingIterator in a completion. - Modules are now automatically instantiated with the BoxClient object and no longer allow the client app to instantiate them - Related RetentionPolicy classes no longer allow rawData to be set by the client app - UploadPartDescription made private - Fixed bug with exponential backoff and changed SDK configuration item "retryAfterTime" to "retryBaseInterval" ### New Features and Enhancements - RetentionPolicyModule methods made public - Added additional supporting types - Improved support for logging to file, allow for custom file path, and fixed some related bugs - Improved console logging formatting - Updated Sample Apps to use new PagingIterator responses ## 3.0.0-rc.2 (2019-10-30) ### ⚠ BREAKING CHANGES - Changed SDK errors from customValue enum cases to specific enum cases ### New Features and Enhancements - Added Xcode 11 + iOS 13 support to Travis CI ## 3.0.0-rc.1 (2019-10-18) ### ⚠ BREAKING CHANGES - Changed TaskAssignment.resolutionState from String to new AssignmentState enum type - Changed Group.groupType from String to new GroupType enum type - Changed Folder.allowedSharedLinkAccessLevels from [String] to new [SharedLinkAccess] enum type - Changed File.allowedInviteeRoles from [String] to new [CollaborationRole] enum type - Network responses with 4xx or 5xx status codes are now transformed into an API Error - CollaborationItem changed from class to enum - CommentItem changed from class to enum - FolderItem changed from class to enum - WebhookItem changed from class to enum - TaskItem changed from class to enum - JSON decoding errors now emit expected type - Public method names changed to a new convention in many of the "module" classes - Redesigned error classes and error hierarchy - Temporarily removed progress closure for uploads and downloads ### New Features and Enhancements Added Xcode 11 support (SDK builds still target iOS 11.0) Removed AlamoFire dependency Added support for Device Pins Added SDK Configuration URL validation Added SDK-level constants rootFolder and currentUser for convenience Added support for Collaboration Whitelist endpoints Added support for Retention Policy endpoints Added support for Tasks endpoints Added support for Webhooks endpoints Added support for Groups and Group Membership endpoints Added support for Legal Holds endpoints Added support for Terms of Service endpoints Added support for Terms of Service User Status endpoints Added support for Watermarking endpoints Added support for Storage Policy endpoints Added support for Metadata Cascade Policy endpoints Added support for User endpoints Added support for Events endpoints Added Error Views in Sample Apps Improved structure and usability of Sample Apps ## 3.0.0-alpha.3 (2019-08-29) ### ⚠ BREAKING CHANGES - Changed File Entry Container "entries" from optional to not optional ### New Features and Enhancements - Added support for Web Links - Added support for Trash endpoints - Added support for Recent Items - Added support for File Version endpoints - Added support for Delete File endpoint - Added support for Chunked Upload Endpoints - Added support for upload preflight check - Added support for downloading a representation of a file - Added support for custom OAuth2 Callback URL - Added KeychainTokenStore for OAuth2SampleApp ## 3.0.0-alpha.2 (2019-08-08) ### ⚠ BREAKING CHANGES Moved some constants to different namespaces: - `Box.rootFolder` is now `BoxSDK.Constants.rootFolder` - `Box.currentUser` is now `BoxSDK.Constants.currentUser` Updated the arguments that `client.files.updateFileInfo()` takes for consistency with the rest of the SDK Changed the type of the `expiresAt` arguments in `client.files.lockFile()` from `String` to `Date` Removed unused arguments from `client.files.unlockFile()` Changed the type of the `unsharedAt` and `password` arguments of `client.files.setSharedLink()` and `client.folders.setSharedLink()` to accept `.null` values Replaced the `access`, `password`, `unsharedAt`, and `canDownload` arguments of `client.folders.updateFolder()` with a single `sharedLink` argument to enable setting the entire shared link field to `.null` in order to remove the shared link Replaced `client.getFavoritesCollectionId()` with `client.collections.getFavoritesCollection()` Removed `client.collections.addItemsToCollection()` and `client.collections.deleteItemsFromCollection()` Changed the result type for `client.files.addFileToFavorites()`, `client.files.addFileToCollection()`, `client.files.removeFileFromFavorites()`, and `client.files.removeFileFromCollection()` from `Void` to `File` Changed the result type for `client.folders.addFolderToFavorites()`, `client.folders.addFolderToCollection()`, `client.folders.removeFolderFromFavorites()`, and `client.folders.removeFolderFromCollection()` from `Void` to `Folder` ### New Features and Enhancements - Added support for [token downscoping](./docs/usage/authentication.md#token-exchange) - Added a `KeychainTokenStore` implementation to enable persisting authentication state on the Keychain - The SDK now automatically clears the token store after destroying a client and revoking its tokens ## [3.0.0-alpha.1] (2019-07-25) Initial beta release :tada: --- ### Changelog **Type:** page | **Section:** Additional Resources Changelog All notable changes to this project will be documented in this file. See standard-version for commit guidelines. 1.17.1 (2025-0… # Changelog All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines. ### 1.17.1 (2025-08-07) ### Bug Fixes - Fix exports syntax when importing from `lib` ([#700](https://github.com/box/box-typescript-sdk-gen/issues/700)) ([782a287](https://github.com/box/box-typescript-sdk-gen/commit/782a287efd3481fc056effcf83886f05bc9adbf9)) ## 1.17.0 (2025-08-05) ### Bug Fixes - Bump `cypress` to resolve `CVE-2025-7783` in `form-data` (box/box-codegen[#769](https://github.com/box/box-typescript-sdk-gen/issues/769)) ([#677](https://github.com/box/box-typescript-sdk-gen/issues/677)) ([077413e](https://github.com/box/box-typescript-sdk-gen/commit/077413ec525fad4d8ebc4c7209fce20046731295)) ### New Features and Enhancements - Add AI spreadsheet processor (box/box-openapi[#533](https://github.com/box/box-typescript-sdk-gen/issues/533)) ([#649](https://github.com/box/box-typescript-sdk-gen/issues/649)) ([254fb54](https://github.com/box/box-typescript-sdk-gen/commit/254fb54d928ec3a76304674f341be1c67d78a143)) - Add Archive Public API (box/box-openapi[#540](https://github.com/box/box-typescript-sdk-gen/issues/540)) ([#674](https://github.com/box/box-typescript-sdk-gen/issues/674)) ([1cbb124](https://github.com/box/box-typescript-sdk-gen/commit/1cbb12485a417b813df8b6918cf3721ae781a286)) - Add new Hubs APIs and Hubs items API (box/box-openapi[#538](https://github.com/box/box-typescript-sdk-gen/issues/538)) ([#666](https://github.com/box/box-typescript-sdk-gen/issues/666)) ([25c9596](https://github.com/box/box-typescript-sdk-gen/commit/25c9596bc71fe88e0a2b6d5e01c65fa682c2fd38)) - Add new schema for `Metadata Error` (box/box-openapi[#539](https://github.com/box/box-typescript-sdk-gen/issues/539)) ([#667](https://github.com/box/box-typescript-sdk-gen/issues/667)) ([9af46ab](https://github.com/box/box-typescript-sdk-gen/commit/9af46abe837ee0d812bcc15f1edf0d5a6530bfe0)) - Allow injecting private key decryption mechanism for JWT (box/box-codegen[#754](https://github.com/box/box-typescript-sdk-gen/issues/754)) ([#656](https://github.com/box/box-typescript-sdk-gen/issues/656)) ([cb0c35d](https://github.com/box/box-typescript-sdk-gen/commit/cb0c35df4a5b3f9b8c611006dd33d480949a0d36)) - Improve webhook validation checks (box/box-codegen[#745](https://github.com/box/box-typescript-sdk-gen/issues/745)) ([#647](https://github.com/box/box-typescript-sdk-gen/issues/647)) ([98b3b92](https://github.com/box/box-typescript-sdk-gen/commit/98b3b9293ff3f0e5922d0772d87504770bb9303c)) - Retry request on network exception (box/box-codegen[#776](https://github.com/box/box-typescript-sdk-gen/issues/776)) ([#684](https://github.com/box/box-typescript-sdk-gen/issues/684)) ([c0c4dba](https://github.com/box/box-typescript-sdk-gen/commit/c0c4dbac40970d34da4c9e52fc43f029ae2f91a6)) - Support ESM build and tree-shaking (box/box-codegen[#762](https://github.com/box/box-typescript-sdk-gen/issues/762)) ([#663](https://github.com/box/box-typescript-sdk-gen/issues/663)) ([8ca3302](https://github.com/box/box-typescript-sdk-gen/commit/8ca33023d904edd596819c7c6df42022006274ed)) - Support Hubs beta endpoints (box/box-openapi[#531](https://github.com/box/box-typescript-sdk-gen/issues/531)) ([#641](https://github.com/box/box-typescript-sdk-gen/issues/641)) ([d8c7bb6](https://github.com/box/box-typescript-sdk-gen/commit/d8c7bb66736a3c4679b116916c61e2ead824a305)) - Support new tools in AI Studio (box/box-openapi[#534](https://github.com/box/box-typescript-sdk-gen/issues/534)) ([#652](https://github.com/box/box-typescript-sdk-gen/issues/652)) ([db2501b](https://github.com/box/box-typescript-sdk-gen/commit/db2501bb13fc6ecebbb4c535b4a19c9be2cf64c2)) ## 1.16.0 (2025-06-12) ### Bug Fixes - Compute webhook signature with and without escaping the body (box/box-codegen[#737](https://github.com/box/box-typescript-sdk-gen/issues/737)) ([#627](https://github.com/box/box-typescript-sdk-gen/issues/627)) ([6a21b8e](https://github.com/box/box-typescript-sdk-gen/commit/6a21b8ed54ef26041feccaa5481951355965e514)) - Fix circular dependency in `boxNetworkClient` (box/box-codegen[#708](https://github.com/box/box-typescript-sdk-gen/issues/708)) ([#591](https://github.com/box/box-typescript-sdk-gen/issues/591)) ([b383889](https://github.com/box/box-typescript-sdk-gen/commit/b383889b9fdc91c6cfed7169e4d36a22a8c8a0fa)) - Fix downscope token to use `retrieveToken` method for token retrieval (box/box-codegen[#731](https://github.com/box/box-typescript-sdk-gen/issues/731)) ([#618](https://github.com/box/box-typescript-sdk-gen/issues/618)) ([90edb0c](https://github.com/box/box-typescript-sdk-gen/commit/90edb0cc9bddc474c20b8b83770a4d314843edab)) - Fix slash escaping when calculating webhook signature (box/box-codegen[#736](https://github.com/box/box-typescript-sdk-gen/issues/736)) ([#624](https://github.com/box/box-typescript-sdk-gen/issues/624)) ([a0307d0](https://github.com/box/box-typescript-sdk-gen/commit/a0307d0c4c5dfed1a66e395a1dfb4c8ff387561d)) - Handle list of strings in metadata filter (box/box-codegen[#716](https://github.com/box/box-typescript-sdk-gen/issues/716)) ([#597](https://github.com/box/box-typescript-sdk-gen/issues/597)) ([979ff2c](https://github.com/box/box-typescript-sdk-gen/commit/979ff2c82edce9a969444febf1896d866ca154bf)) - Improve file download to avoid storing content in memory (box/box-codegen[#701](https://github.com/box/box-typescript-sdk-gen/issues/701)) ([#589](https://github.com/box/box-typescript-sdk-gen/issues/589)) ([513a15e](https://github.com/box/box-typescript-sdk-gen/commit/513a15eb28736d28d665324949d145dd3387d27d)) - Modify utility functions for browser (box/box-codegen[#686](https://github.com/box/box-typescript-sdk-gen/issues/686)) ([#585](https://github.com/box/box-typescript-sdk-gen/issues/585)) ([7232170](https://github.com/box/box-typescript-sdk-gen/commit/7232170fe7901cb7ba9ebf79ffc6a7c0b376a1c8)) - Use constant-time comparison for HMAC signatures (box/box-codegen[#739](https://github.com/box/box-typescript-sdk-gen/issues/739)) ([#630](https://github.com/box/box-typescript-sdk-gen/issues/630)) ([efdcaaf](https://github.com/box/box-typescript-sdk-gen/commit/efdcaaf605fc6f14bbbf171e2797d73e97302bfe)) ### New Features and Enhancements - Add AI agents warnings; allow for more types of metadata value (box/box-openapi[#520](https://github.com/box/box-typescript-sdk-gen/issues/520)) ([#600](https://github.com/box/box-typescript-sdk-gen/issues/600)) ([a5a555f](https://github.com/box/box-typescript-sdk-gen/commit/a5a555f835df5b550b9839e3e1fcff5d9f2b9f96)) - Add security settings properties on sign template schema (box/box-openapi[#518](https://github.com/box/box-typescript-sdk-gen/issues/518)) ([#588](https://github.com/box/box-typescript-sdk-gen/issues/588)) ([dfd3e5f](https://github.com/box/box-typescript-sdk-gen/commit/dfd3e5f7ecf8a8e49d79ed7df4d7e1f88f3e8537)) - Add Shield Lists APIs (box/box-openapi[#528](https://github.com/box/box-typescript-sdk-gen/issues/528)) ([#622](https://github.com/box/box-typescript-sdk-gen/issues/622)) ([be3af44](https://github.com/box/box-typescript-sdk-gen/commit/be3af441a66da02254d38576bb9ec258142f6d2d)) - Add support of IBM models to AI API (box/box-openapi[#522](https://github.com/box/box-typescript-sdk-gen/issues/522)) ([#601](https://github.com/box/box-typescript-sdk-gen/issues/601)) ([b060b8c](https://github.com/box/box-typescript-sdk-gen/commit/b060b8c21a13abdfb12988f9c6e6beb014fa104f)) - Increase max items for ai extract endpoints (box/box-openapi[#525](https://github.com/box/box-typescript-sdk-gen/issues/525)) ([#602](https://github.com/box/box-typescript-sdk-gen/issues/602)) ([86c5d14](https://github.com/box/box-typescript-sdk-gen/commit/86c5d14bafe8789c306a1688bcf010207c302ca9)) - Update legal holds and AI models (box/box-openapi[#526](https://github.com/box/box-typescript-sdk-gen/issues/526)) ([#620](https://github.com/box/box-typescript-sdk-gen/issues/620)) ([de3df57](https://github.com/box/box-typescript-sdk-gen/commit/de3df57cc90577a49ea40de278bde423d17c4f06)) ### 1.15.1 (2025-04-11) ### Bug Fixes - Fix data sanitizer for TypeScript (box/box-codegen[#702](https://github.com/box/box-typescript-sdk-gen/issues/702)) ([#582](https://github.com/box/box-typescript-sdk-gen/issues/582)) ([eb79c0f](https://github.com/box/box-typescript-sdk-gen/commit/eb79c0faa11f40667289155e71b8893a96eb558a)) ## 1.15.0 (2025-04-10) ### New Features and Enhancements - Support sensitive data sanitization in errors (box/box-codegen[#695](https://github.com/box/box-typescript-sdk-gen/issues/695)) ([#573](https://github.com/box/box-typescript-sdk-gen/issues/573)) ([488e76a](https://github.com/box/box-typescript-sdk-gen/commit/488e76a1e1f66d5d4ac56b16e6a7dae9e7f497a1)) ## 1.14.0 (2025-03-18) ### Bug Fixes - Add `verification_phone_number` property to create sign request (box/box-openapi[#515](https://github.com/box/box-typescript-sdk-gen/issues/515)) ([#546](https://github.com/box/box-typescript-sdk-gen/issues/546)) ([916502c](https://github.com/box/box-typescript-sdk-gen/commit/916502c47cb4936ab93a40b3f1552c1860173a8e)) ### New Features and Enhancements - Add find app item for shared link endpoint (box/box-openapi[#514](https://github.com/box/box-typescript-sdk-gen/issues/514)) ([#545](https://github.com/box/box-typescript-sdk-gen/issues/545)) ([7c32eaf](https://github.com/box/box-typescript-sdk-gen/commit/7c32eaf2af3ef08299d9dd69e744304b20f4309f)) - Add Integration Mappings Teams API (box/box-openapi[#517](https://github.com/box/box-typescript-sdk-gen/issues/517)) ([#548](https://github.com/box/box-typescript-sdk-gen/issues/548)) ([6ce1c7c](https://github.com/box/box-typescript-sdk-gen/commit/6ce1c7c78c9bc5d70383065e95f01bc8133fdd52)) - Support upload with preflight check (box/box-codegen[#676](https://github.com/box/box-typescript-sdk-gen/issues/676)) ([#554](https://github.com/box/box-typescript-sdk-gen/issues/554)) ([e3aa784](https://github.com/box/box-typescript-sdk-gen/commit/e3aa784b73c7b473fdf06c05c7f657a54fc08e4c)) ### 1.13.2 (2025-03-11) ### Bug Fixes - Fix `rollup` plugin output directory in Typescript (box/box-codegen[#678](https://github.com/box/box-typescript-sdk-gen/issues/678)) ([#543](https://github.com/box/box-typescript-sdk-gen/issues/543)) ([f828d5e](https://github.com/box/box-typescript-sdk-gen/commit/f828d5e7e3079c48590e9766f0dccd25ee1af9ca)) ### 1.13.1 (2025-03-07) ### Bug Fixes - Split browser configuration in `package.json` for TypeScript (box/box-codegen[#672](https://github.com/box/box-typescript-sdk-gen/issues/672)) ([#538](https://github.com/box/box-typescript-sdk-gen/issues/538)) ([ca7e291](https://github.com/box/box-typescript-sdk-gen/commit/ca7e29180e450cbb346a76aadfdade1062559b1e)) ## 1.13.0 (2025-02-20) ### New Features and Enhancements - Support AI Studio API (box/box-codegen[#626](https://github.com/box/box-typescript-sdk-gen/issues/626)) ([#520](https://github.com/box/box-typescript-sdk-gen/issues/520)) ([949b856](https://github.com/box/box-typescript-sdk-gen/commit/949b856ce1d77b1aa425b91b46440b46b383438a)) ## 1.12.0 (2025-02-06) ### New Features and Enhancements - Add Box Sign shared requests (box/box-openapi[#504](https://github.com/box/box-typescript-sdk-gen/issues/504)) ([#491](https://github.com/box/box-typescript-sdk-gen/issues/491)) ([e90255c](https://github.com/box/box-typescript-sdk-gen/commit/e90255c5d97a7a1a10dd529b58426142c5c6f0d4)) - feat: Add hubs support to `/ai/ask`. Replace type of `items` property from `AiItemBase[]` to `AiItemAsk[]` in the `AiAsk` interface (box/box-codegen[#656](https://github.com/box/box-typescript-sdk-gen/issues/656)) ([#507](https://github.com/box/box-typescript-sdk-gen/issues/507)) ([9f29d8c](https://github.com/box/box-typescript-sdk-gen/commit/9f29d8cb1f1d3b8c7625da1ddb9f2abd62d133f0)) - Update `/ai/extract_structured` response schema (box/box-codegen[#641](https://github.com/box/box-typescript-sdk-gen/issues/641)) ([#498](https://github.com/box/box-typescript-sdk-gen/issues/498)) ([502ac11](https://github.com/box/box-typescript-sdk-gen/commit/502ac11a2ad4e56fceece0deb6a15dbfc8b429ff)) ## 1.11.0 (2025-01-21) ### Bug Fixes - Add missing field assignments in constructor (box/box-codegen[#646](https://github.com/box/box-typescript-sdk-gen/issues/646)) ([#485](https://github.com/box/box-typescript-sdk-gen/issues/485)) ([0592f7b](https://github.com/box/box-typescript-sdk-gen/commit/0592f7bcde962c50d88ec69f6c359af754200e56)) - Add missing token scope (box/box-openapi[#490](https://github.com/box/box-typescript-sdk-gen/issues/490)) ([#459](https://github.com/box/box-typescript-sdk-gen/issues/459)) ([f0c0d91](https://github.com/box/box-typescript-sdk-gen/commit/f0c0d918c6d1a6466f9c02c760e3cbee18dab940)) - correct parameters types in file representation (box/box-openapi[#503](https://github.com/box/box-typescript-sdk-gen/issues/503)) ([#489](https://github.com/box/box-typescript-sdk-gen/issues/489)) ([d11529a](https://github.com/box/box-typescript-sdk-gen/commit/d11529a2958504e9106996fd475f0d99825b6926)) - Fix invalid variant config for Integration mapping Slack (box/box-openapi[#492](https://github.com/box/box-typescript-sdk-gen/issues/492)) ([#462](https://github.com/box/box-typescript-sdk-gen/issues/462)) ([660dc6e](https://github.com/box/box-typescript-sdk-gen/commit/660dc6ecd0302930ef5ce4d051860bac69a12188)) - order of fields in the `IntegrationMapping` schema (box/box-openapi[#497](https://github.com/box/box-typescript-sdk-gen/issues/497)) ([#476](https://github.com/box/box-typescript-sdk-gen/issues/476)) ([93e2bc3](https://github.com/box/box-typescript-sdk-gen/commit/93e2bc3f878f28d11d66a680c75ef0c06eada991)) - Remove `eval` usage (box/box-codegen[#636](https://github.com/box/box-typescript-sdk-gen/issues/636)) ([#474](https://github.com/box/box-typescript-sdk-gen/issues/474)) ([7c86f34](https://github.com/box/box-typescript-sdk-gen/commit/7c86f345e863efa338ac5808c5ec43cb6c549953)) - Remove auth when cross origin redirect (box/box-codegen[#648](https://github.com/box/box-typescript-sdk-gen/issues/648)) ([#488](https://github.com/box/box-typescript-sdk-gen/issues/488)) ([56fb287](https://github.com/box/box-typescript-sdk-gen/commit/56fb2879ab70ef6d5584b2591ff9c8d3ade2b7d7)) ### New Features and Enhancements - Support Box Doc Gen API (box/box-codegen[#644](https://github.com/box/box-typescript-sdk-gen/issues/644)) ([#486](https://github.com/box/box-typescript-sdk-gen/issues/486)) ([0d3bc18](https://github.com/box/box-typescript-sdk-gen/commit/0d3bc1813e11c1e482794f57c0843823e7e4cbc8)) - Use extensible enums (box/box-codegen[#639](https://github.com/box/box-typescript-sdk-gen/issues/639)) ([#487](https://github.com/box/box-typescript-sdk-gen/issues/487)) ([2a24c7a](https://github.com/box/box-typescript-sdk-gen/commit/2a24c7a0dbc3c946a69c5081939943d9b184d441)) ## 1.10.0 (2024-12-30) ### Bug Fixes - Remove unused parameter from `SignRequest` (box/box-openapi[#489](https://github.com/box/box-typescript-sdk-gen/issues/489)) ([#450](https://github.com/box/box-typescript-sdk-gen/issues/450)) ([f5683b7](https://github.com/box/box-typescript-sdk-gen/commit/f5683b703625dd8d504ca52100f692cb8440a474)) ### New Features and Enhancements - Add support for replacing the network client implementation (box/box-codegen[#629](https://github.com/box/box-typescript-sdk-gen/issues/629)) ([#454](https://github.com/box/box-typescript-sdk-gen/issues/454)) ([1cb7ddb](https://github.com/box/box-typescript-sdk-gen/commit/1cb7ddb3ada79cebc27fbfce9df90cd8ebad353c)) - Allow for customizing retry strategy (box/box-codegen[#635](https://github.com/box/box-typescript-sdk-gen/issues/635)) ([#457](https://github.com/box/box-typescript-sdk-gen/issues/457)) ([530ca33](https://github.com/box/box-typescript-sdk-gen/commit/530ca33ff3635581bd8ee91a82bc9f000b18812b)) - Support webhook message validation (box/box-codegen[#631](https://github.com/box/box-typescript-sdk-gen/issues/631)) ([#455](https://github.com/box/box-typescript-sdk-gen/issues/455)) ([09765a4](https://github.com/box/box-typescript-sdk-gen/commit/09765a42fe25f15095bd1bd0d1377f2da222c9e4)) ## 1.9.0 (2024-12-09) ### Bug Fixes - Fix signature of `beforeRequest` method in `Interceptor` interface (box/box-codegen[#625](https://github.com/box/box-typescript-sdk-gen/issues/625)) ([#446](https://github.com/box/box-typescript-sdk-gen/issues/446)) ([ef2e765](https://github.com/box/box-typescript-sdk-gen/commit/ef2e7658cab705906325e40d6c7c6e96e5703201)) ### New Features and Enhancements - Add `aiAgent` info to `AIResponse` (box/box-codegen[#624](https://github.com/box/box-typescript-sdk-gen/issues/624)) ([#440](https://github.com/box/box-typescript-sdk-gen/issues/440)) ([24c2013](https://github.com/box/box-typescript-sdk-gen/commit/24c20131b8275d43ecb02f3c94ac8e6116de3ea9)) - Support optional `userId` parameter for updating files, folders and web links (box/box-openapi[#488](https://github.com/box/box-typescript-sdk-gen/issues/488)) ([#445](https://github.com/box/box-typescript-sdk-gen/issues/445)) ([874f259](https://github.com/box/box-typescript-sdk-gen/commit/874f259ce12e8440301ffb1b2b65a6765b87803f)) ## 1.8.0 (2024-12-03) ### Bug Fixes - fix `additionalProperties` in `ClientError` (box/box-openapi[#477](https://github.com/box/box-typescript-sdk-gen/issues/477)) ([#385](https://github.com/box/box-typescript-sdk-gen/issues/385)) ([4547148](https://github.com/box/box-typescript-sdk-gen/commit/454714861019998b1fc6b7c44696b0178ffa022b)) - Fix chunked uploads in browser (box/box-codegen[#619](https://github.com/box/box-typescript-sdk-gen/issues/619)) ([#436](https://github.com/box/box-typescript-sdk-gen/issues/436)) ([0af2484](https://github.com/box/box-typescript-sdk-gen/commit/0af2484dd8387cce1a8c235068ac3f834f8ecf42)) - Support status codes with no content (box/box-codegen[#604](https://github.com/box/box-typescript-sdk-gen/issues/604)) ([#415](https://github.com/box/box-typescript-sdk-gen/issues/415)) ([c3f14c6](https://github.com/box/box-typescript-sdk-gen/commit/c3f14c6af55ab78ed5dc981909c67397b0d7219e)) - update client error schema to support schema errors (box/box-openapi[#467](https://github.com/box/box-typescript-sdk-gen/issues/467)) ([#381](https://github.com/box/box-typescript-sdk-gen/issues/381)) ([b845f12](https://github.com/box/box-typescript-sdk-gen/commit/b845f12d194d5f4e0cfd66db1db294e2f9a9bff8)) - update integration mapping response description (box/box-openapi[#463](https://github.com/box/box-typescript-sdk-gen/issues/463)) ([#379](https://github.com/box/box-typescript-sdk-gen/issues/379)) ([e3d71e1](https://github.com/box/box-typescript-sdk-gen/commit/e3d71e100500c5fa9e478b5228fd395f68242cf2)) ### New Features and Enhancements - add AI LLM endpoint AWS `params` (box/box-openapi[#478](https://github.com/box/box-typescript-sdk-gen/issues/478)) ([#388](https://github.com/box/box-typescript-sdk-gen/issues/388)) ([d2fd1ec](https://github.com/box/box-typescript-sdk-gen/commit/d2fd1ec4bddb19b353e286908c99477e08b90457)) - Expose method for making custom HTTP requests, convert `FetchOptions` into a class (box/box-codegen[#610](https://github.com/box/box-typescript-sdk-gen/issues/610)) ([#431](https://github.com/box/box-typescript-sdk-gen/issues/431)) ([9a9ea62](https://github.com/box/box-typescript-sdk-gen/commit/9a9ea628fd21001437d92b32f1760d5ba14cb46b)) - Support get collection by ID endpoint (box/box-codegen[#595](https://github.com/box/box-typescript-sdk-gen/issues/595)) ([#396](https://github.com/box/box-typescript-sdk-gen/issues/396)) ([f1f47be](https://github.com/box/box-typescript-sdk-gen/commit/f1f47bebfc0981a5e67f301b6fc2e3a8568d5845)) - Support getting file download URL and file thumbnail URL (box/box-codegen[#617](https://github.com/box/box-typescript-sdk-gen/issues/617)) ([#435](https://github.com/box/box-typescript-sdk-gen/issues/435)) ([1cb4d5d](https://github.com/box/box-typescript-sdk-gen/commit/1cb4d5d93fbd94b952b876457008973a92d5aa23)) - Support `nullable` fields in TypeScript (box/box-codegen[#612](https://github.com/box/box-typescript-sdk-gen/issues/612)) ([#425](https://github.com/box/box-typescript-sdk-gen/issues/425)) ([991dc29](https://github.com/box/box-typescript-sdk-gen/commit/991dc29bc805bf0c5198277142efb9a85de1dd42)) ## 1.7.0 (2024-10-17) ### New Features and Enhancements - Include raw data in response object (box/box-codegen[#576](https://github.com/box/box-typescript-sdk-gen/issues/576)) ([#375](https://github.com/box/box-typescript-sdk-gen/issues/375)) ([bdb9d0c](https://github.com/box/box-typescript-sdk-gen/commit/bdb9d0caab1a54ca56aef5de4260215d1d3fbd35)) - Support `ai/extract` and `ai/extract_structured` endpoints (box/box-codegen[#566](https://github.com/box/box-typescript-sdk-gen/issues/566)) ([#356](https://github.com/box/box-typescript-sdk-gen/issues/356)) ([4a33562](https://github.com/box/box-typescript-sdk-gen/commit/4a335621c7eaa413162a5daa65d63d8353ba37f5)) ## 1.6.0 (2024-09-11) ### Bug Fixes - Add the missing license to `package.json` (box/box-codegen[#562](https://github.com/box/box-typescript-sdk-gen/issues/562)) ([#343](https://github.com/box/box-typescript-sdk-gen/issues/343)) ([cc9a8b8](https://github.com/box/box-typescript-sdk-gen/commit/cc9a8b8ac628e348d32176f8ba69add649c555bd)) - Fix variants in metadata query results (box/box-openapi[#456](https://github.com/box/box-typescript-sdk-gen/issues/456)) ([#349](https://github.com/box/box-typescript-sdk-gen/issues/349)) ([2131e98](https://github.com/box/box-typescript-sdk-gen/commit/2131e98ff5530c7440ff50ec0da46cc317d0a4ae)) ### New Features and Enhancements - add Hubs Beta (box/box-openapi[#453](https://github.com/box/box-typescript-sdk-gen/issues/453)) ([#333](https://github.com/box/box-typescript-sdk-gen/issues/333)) ([40359c7](https://github.com/box/box-typescript-sdk-gen/commit/40359c71aa25ecfe7ec53bfa19de62b9d83d4ace)) - Add support for proxy (box/box-codegen[#559](https://github.com/box/box-typescript-sdk-gen/issues/559)) ([#337](https://github.com/box/box-typescript-sdk-gen/issues/337)) ([0ffd9c8](https://github.com/box/box-typescript-sdk-gen/commit/0ffd9c8095d1aa742144146383ae94f1f4526af0)) ### 1.5.1 (2024-08-30) ### Bug Fixes - Fix fetch options with interceptor (box/box-codegen[#556](https://github.com/box/box-typescript-sdk-gen/issues/556)) ([#326](https://github.com/box/box-typescript-sdk-gen/issues/326)) ([3751eea](https://github.com/box/box-typescript-sdk-gen/commit/3751eea67047021fe298c841596ae362ed1e47da)) ## 1.5.0 (2024-08-23) ### Bug Fixes - Add missing fields to Sign Template Signer and fix AI schema (box/box-openapi[#451](https://github.com/box/box-typescript-sdk-gen/issues/451)) ([#317](https://github.com/box/box-typescript-sdk-gen/issues/317)) ([340fbd8](https://github.com/box/box-typescript-sdk-gen/commit/340fbd84f6fa408155c6a2a4b9b7b03b88f76f24)) - Fix `IntegrationMapping` schemas (box/box-codegen[#551](https://github.com/box/box-typescript-sdk-gen/issues/551)) ([#315](https://github.com/box/box-typescript-sdk-gen/issues/315)) ([a863b1e](https://github.com/box/box-typescript-sdk-gen/commit/a863b1eb8fcfccd78714e3f52ce96d89ef69ca72)) ### New Features and Enhancements - Add new parameters to Box AI methods and introduce `AiResponseFull` variant (box/box-openapi[#446](https://github.com/box/box-typescript-sdk-gen/issues/446)) ([#313](https://github.com/box/box-typescript-sdk-gen/issues/313)) ([d9664fd](https://github.com/box/box-typescript-sdk-gen/commit/d9664fd7d431685c8e115415085bbe69d17f272d)) - Include URL into `FetchOptions` (box/box-codegen[#549](https://github.com/box/box-typescript-sdk-gen/issues/549)) ([#319](https://github.com/box/box-typescript-sdk-gen/issues/319)) ([30eaa6b](https://github.com/box/box-typescript-sdk-gen/commit/30eaa6ba7aa0fcd5e2f71026d7bf58729d387221)) ## 1.4.0 (2024-08-12) ### Bug Fixes - Add missing token scope (box/box-openapi[#442](https://github.com/box/box-typescript-sdk-gen/issues/442)) ([#281](https://github.com/box/box-typescript-sdk-gen/issues/281)) ([ca77f58](https://github.com/box/box-typescript-sdk-gen/commit/ca77f58b10d3a302748750584730f0fcdd8b4b55)) - Fix fetch method for multipart request (box/box-codegen[#545](https://github.com/box/box-typescript-sdk-gen/issues/545)) ([#303](https://github.com/box/box-typescript-sdk-gen/issues/303)) ([f8ceac0](https://github.com/box/box-typescript-sdk-gen/commit/f8ceac005f043017e7cde310490e79ab9195f8d7)) ### New Features and Enhancements - Parametrise chunked uploads endpoint urls (box/box-openapi[#444](https://github.com/box/box-typescript-sdk-gen/issues/444)) ([#302](https://github.com/box/box-typescript-sdk-gen/issues/302)) ([293a6e9](https://github.com/box/box-typescript-sdk-gen/commit/293a6e9aeabbba37e4c12e2322a79717a10e1775)) - **ts:** Add comments to properties and methods (box/box-codegen[#537](https://github.com/box/box-typescript-sdk-gen/issues/537)) ([#284](https://github.com/box/box-typescript-sdk-gen/issues/284)) ([db3a2b5](https://github.com/box/box-typescript-sdk-gen/commit/db3a2b57fbe0eec17373a2acf8089ff247c98225)) ## 1.3.0 (2024-07-24) ### Bug Fixes - Extract `IntegrationMappingPartnerItemSlack` to union type (box/box-codegen[#530](https://github.com/box/box-typescript-sdk-gen/issues/530)) ([#255](https://github.com/box/box-typescript-sdk-gen/issues/255)) ([fa8952a](https://github.com/box/box-typescript-sdk-gen/commit/fa8952a6582d9965bbb4ab66bbeff057f5c68851)) - Improve chunked upload reliability (box/box-codegen[#529](https://github.com/box/box-typescript-sdk-gen/issues/529)) ([#254](https://github.com/box/box-typescript-sdk-gen/issues/254)) ([12d9288](https://github.com/box/box-typescript-sdk-gen/commit/12d928850e0a1cd60f336a9919474b9aaba33028)) ### New Features and Enhancements - Add `is_active` parameter to user collaboration (box/box-openapi[#437](https://github.com/box/box-typescript-sdk-gen/issues/437)) ([#253](https://github.com/box/box-typescript-sdk-gen/issues/253)) ([4d8d436](https://github.com/box/box-typescript-sdk-gen/commit/4d8d436977b3e487a47e7717626f1c0f2eb43227)) - Support AI Agent API (box/box-codegen[#531](https://github.com/box/box-typescript-sdk-gen/issues/531)) ([#260](https://github.com/box/box-typescript-sdk-gen/issues/260)) ([0ec40d4](https://github.com/box/box-typescript-sdk-gen/commit/0ec40d44c86a8a9cf4fe594966cfad1866be457c)) ## 1.2.0 (2024-07-08) ### Bug Fixes - Fix upload in browser (box/box-codegen[#524](https://github.com/box/box-typescript-sdk-gen/issues/524)) ([#248](https://github.com/box/box-typescript-sdk-gen/issues/248)) ([88d747e](https://github.com/box/box-typescript-sdk-gen/commit/88d747e0f03dfa3c2d6089257c6e8b5b635775e0)) - Update chunked upload (box/box-codegen[#523](https://github.com/box/box-typescript-sdk-gen/issues/523)) ([#247](https://github.com/box/box-typescript-sdk-gen/issues/247)) ([27ceb35](https://github.com/box/box-typescript-sdk-gen/commit/27ceb35e6444843eea9b7ec6923fe958c9a74571)) ### New Features and Enhancements - Retry request with status code `202` (box/box-codegen[#511](https://github.com/box/box-typescript-sdk-gen/issues/511)) ([#235](https://github.com/box/box-typescript-sdk-gen/issues/235)) ([03b8f43](https://github.com/box/box-typescript-sdk-gen/commit/03b8f4314ada5ef5596706b7599cc76565fe96a5)) - Support extensible enum types in Typescript (box/box-codegen[#520](https://github.com/box/box-typescript-sdk-gen/issues/520)) ([#243](https://github.com/box/box-typescript-sdk-gen/issues/243)) ([5237972](https://github.com/box/box-typescript-sdk-gen/commit/523797273bc08e3b22609ef0019432ab3e43c3ba)) ## 1.1.0 (2024-06-12) ### Bug Fixes - Fix CI for auto update pull requests (box/box-codegen[#506](https://github.com/box/box-typescript-sdk-gen/issues/506)) ([#221](https://github.com/box/box-typescript-sdk-gen/issues/221)) ([bbc14f6](https://github.com/box/box-typescript-sdk-gen/commit/bbc14f66e14a9386c8d54a5d0bb36ec2cdc501c1)) - remove quotation mark when date or `datetime` is used in `queryParams` (box/box-codegen[#509](https://github.com/box/box-typescript-sdk-gen/issues/509)) ([#225](https://github.com/box/box-typescript-sdk-gen/issues/225)) ([28d2220](https://github.com/box/box-typescript-sdk-gen/commit/28d22200602cf02d73590189c304109f1c26db17)) ### New Features and Enhancements - add missing marker pagination fields and introduce new event type `AppItemEventSource` `(box/box-openapi[#431](https://github.com/box/box-typescript-sdk-gen/issues/431))` ([#224](https://github.com/box/box-typescript-sdk-gen/issues/224)) ([6c18ca3](https://github.com/box/box-typescript-sdk-gen/commit/6c18ca3b00da0b878d28e142a2361b6386ef0c15)) ## 1.0.0 (2024-05-20) ### Bug Fixes - Change base urls (box/box-codegen[#491](https://github.com/box/box-typescript-sdk-gen/issues/491)) ([#199](https://github.com/box/box-typescript-sdk-gen/issues/199)) ([8a732e9](https://github.com/box/box-typescript-sdk-gen/commit/8a732e9050c2434dddfb62ebd611d0794284165b)) - Fix schemas for updating classification on a file and folder (box/box-openapi[#423](https://github.com/box/box-typescript-sdk-gen/issues/423)) ([#188](https://github.com/box/box-typescript-sdk-gen/issues/188)) ([68ecb04](https://github.com/box/box-typescript-sdk-gen/commit/68ecb0435e14cd8e21e81cbb8763c49d25952a3d)) - Fix union deserialization (box/box-codegen[#493](https://github.com/box/box-typescript-sdk-gen/issues/493)) ([#202](https://github.com/box/box-typescript-sdk-gen/issues/202)) ([23b9016](https://github.com/box/box-typescript-sdk-gen/commit/23b901685dd83e9f94386c5c889ab1b1a7ee75f8)) - Stop exporting `PartAccumulator` class (box/box-codegen[#494](https://github.com/box/box-typescript-sdk-gen/issues/494)) ([#200](https://github.com/box/box-typescript-sdk-gen/issues/200)) ([98a668e](https://github.com/box/box-typescript-sdk-gen/commit/98a668e8dbdce931d5737172db57d61424f8d75a)) ### New Features and Enhancements - Add `suppressNotifications` and `externalSystemName` fields for Box Sign (box/box-openapi[#425](https://github.com/box/box-typescript-sdk-gen/issues/425)) ([#197](https://github.com/box/box-typescript-sdk-gen/issues/197)) ([f4e4d52](https://github.com/box/box-typescript-sdk-gen/commit/f4e4d52822d4f9ef291916c8e7986d4d5201789b)) - Move schemas to separate modules (box/box-codegen[#483](https://github.com/box/box-typescript-sdk-gen/issues/483)) ([#182](https://github.com/box/box-typescript-sdk-gen/issues/182)) ([cf55214](https://github.com/box/box-typescript-sdk-gen/commit/cf5521440a81543dc7ac032221c1778267cef2f4)) - Support excluding endpoints and schemas in parser (box/box-codegen[#487](https://github.com/box/box-typescript-sdk-gen/issues/487)) ([#183](https://github.com/box/box-typescript-sdk-gen/issues/183)) ([3bd6076](https://github.com/box/box-typescript-sdk-gen/commit/3bd6076c45dcae5db2bafbcb49364fa5629ec8ce)) - Strict checks during deserialization (box/box-codegen[#484](https://github.com/box/box-typescript-sdk-gen/issues/484)) ([#185](https://github.com/box/box-typescript-sdk-gen/issues/185)) ([469afb9](https://github.com/box/box-typescript-sdk-gen/commit/469afb951bd4dbbd2ef7af916084b6baf02040f6)) ### 0.5.4 (2024-05-09) ### Bug Fixes - Ensure AuthorizationManager in authentication classes is initialized with NetworkSession object (box/box-codegen[#469](https://github.com/box/box-typescript-sdk-gen/issues/469)) ([#140](https://github.com/box/box-typescript-sdk-gen/issues/140)) ([464bc25](https://github.com/box/box-typescript-sdk-gen/commit/464bc25ddef82f36bd19d0cfb37e4692e343f913)) - Fix Box AI endpoints (box/box-openapi[#418](https://github.com/box/box-typescript-sdk-gen/issues/418)) ([#171](https://github.com/box/box-typescript-sdk-gen/issues/171)) ([6450322](https://github.com/box/box-typescript-sdk-gen/commit/6450322d6868cd2bf26768ca3aafddcf3422b6cf)) - Fix metadata filter resource (box/box-openapi[#419](https://github.com/box/box-typescript-sdk-gen/issues/419)) ([#173](https://github.com/box/box-typescript-sdk-gen/issues/173)) ([38ca06c](https://github.com/box/box-typescript-sdk-gen/commit/38ca06c95627a5795b854ba2c749f7e627284685)) - Remove most of use of any in generated code (box/box-codegen[#475](https://github.com/box/box-typescript-sdk-gen/issues/475)) ([#166](https://github.com/box/box-typescript-sdk-gen/issues/166)) ([9fabddf](https://github.com/box/box-typescript-sdk-gen/commit/9fabddfed89358b309eac2208a5aaa21a441befd)) ### New Features and Enhancements - Define interfaces for headers input (box/box-codegen[#468](https://github.com/box/box-typescript-sdk-gen/issues/468)) ([#134](https://github.com/box/box-typescript-sdk-gen/issues/134)) ([28b266c](https://github.com/box/box-typescript-sdk-gen/commit/28b266c0747f477e226d99893931c259a4ad2262)) - pack optional arguments of API methods into a new record(box/box-codegen[#471](https://github.com/box/box-typescript-sdk-gen/issues/471)) ([#156](https://github.com/box/box-typescript-sdk-gen/issues/156)) ([2f311c9](https://github.com/box/box-typescript-sdk-gen/commit/2f311c919ed2b9bdb104f66e91f0feb6c8798a71)) - Support Box AI endpoints (box/box-openapi[#416](https://github.com/box/box-typescript-sdk-gen/issues/416)) ([#170](https://github.com/box/box-typescript-sdk-gen/issues/170)) ([febd8d0](https://github.com/box/box-typescript-sdk-gen/commit/febd8d026795238218a0246a736433f2b95767ba)) - Support Date and DateTime types (box/box-codegen[#476](https://github.com/box/box-typescript-sdk-gen/issues/476)) ([#152](https://github.com/box/box-typescript-sdk-gen/issues/152)) ([9939ea9](https://github.com/box/box-typescript-sdk-gen/commit/9939ea9a9bb614499def01e6c767c3ed678ba2ba)) - Support revoking and downscoping token for BoxDeveloperTokenAuth ([#147](https://github.com/box/box-typescript-sdk-gen/issues/147)) ([6d09845](https://github.com/box/box-typescript-sdk-gen/commit/6d0984524d82765da925bc2081eadba5a5d03c66)) - Support union of primitives and objects (box/box-codegen[#481](https://github.com/box/box-typescript-sdk-gen/issues/481)) ([#172](https://github.com/box/box-typescript-sdk-gen/issues/172)) ([c3c6457](https://github.com/box/box-typescript-sdk-gen/commit/c3c6457bb069fe04df0c664ad6056a357077d55b)) ### 0.5.3 (2024-04-04) ### Bug Fixes - **docs:** fixes for chunked uploads docs (box/box-codegen[#457](https://github.com/box/box-typescript-sdk-gen/issues/457)) ([#128](https://github.com/box/box-typescript-sdk-gen/issues/128)) ([c94dbf5](https://github.com/box/box-typescript-sdk-gen/commit/c94dbf5926010e2bec8fc54c317999957a2f3eab)) ### New Features and Enhancements - Assign default value to fields and args of type enum with only one value (box/box-codegen[#465](https://github.com/box/box-typescript-sdk-gen/issues/465)) ([#131](https://github.com/box/box-typescript-sdk-gen/issues/131)) ([bf4d58c](https://github.com/box/box-typescript-sdk-gen/commit/bf4d58c4c19c10f0ede27a4e9c4f7b3861bcd6f7)) - Change `asUser` and `asEnterprise` method names (box/box-codegen[#464](https://github.com/box/box-typescript-sdk-gen/issues/464)) ([#125](https://github.com/box/box-typescript-sdk-gen/issues/125)) ([22c1907](https://github.com/box/box-typescript-sdk-gen/commit/22c19071723430498baa6aa5c5846b0249f061ca)) - **transformers:** determineIsType (box/box-codegen[#148](https://github.com/box/box-typescript-sdk-gen/issues/148)) ([#129](https://github.com/box/box-typescript-sdk-gen/issues/129)) ([57ccdac](https://github.com/box/box-typescript-sdk-gen/commit/57ccdaca74f68b7e221a43bce967e983ef4b0fcf)) ### 0.5.2 (2024-03-26) ### New Features and Enhancements - Support `additionalProperties` of type any in Python and TS (box/box-codegen[#453](https://github.com/box/box-typescript-sdk-gen/issues/453)) ([#97](https://github.com/box/box-typescript-sdk-gen/issues/97)) ([d159548](https://github.com/box/box-typescript-sdk-gen/commit/d159548d38b74fbb410ab1cadb16033948efa14b)) - Support custom Agent in Typescript (box/box-codegen[#452](https://github.com/box/box-typescript-sdk-gen/issues/452)) ([#117](https://github.com/box/box-typescript-sdk-gen/issues/117)) ([de06c26](https://github.com/box/box-typescript-sdk-gen/commit/de06c2672f3efb20e1b685e1c5abf92dff659da3)) - use getDiscriminatorsForUnion in generic serialization (box/box-codegen[#448](https://github.com/box/box-typescript-sdk-gen/issues/448)) ([#95](https://github.com/box/box-typescript-sdk-gen/issues/95)) ([06680c0](https://github.com/box/box-typescript-sdk-gen/commit/06680c05a6c7eb2ff2c20886c642901ac618cd83)) ### 0.5.1 (2024-03-11) ### New Features and Enhancements - Replace jsonwebtoken with jose (box/box-codegen[#444](https://github.com/box/box-typescript-sdk-gen/issues/444)) ([#85](https://github.com/box/box-typescript-sdk-gen/issues/85)) ([2ae8658](https://github.com/box/box-typescript-sdk-gen/commit/2ae86589d85764d485383cc0bc1474b611cc4dc2)) --- ### Changelog **Type:** page | **Section:** Additional Resources Changelog All notable changes to this project will be documented in this file. See standard-version for commit guidelines. 1.16.0 (2025-0… # Changelog All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines. ## 1.16.0 (2025-08-05) ### Bug Fixes - Specify events `next_stream_position` property type as `int` (box/box-openapi[#535](https://github.com/box/box-python-sdk-gen/issues/535)) ([#644](https://github.com/box/box-python-sdk-gen/issues/644)) ([64069db](https://github.com/box/box-python-sdk-gen/commit/64069db8da33988c173380defd6be065daa02496)) ### New Features and Enhancements - Add AI spreadsheet processor (box/box-openapi[#533](https://github.com/box/box-python-sdk-gen/issues/533)) ([#630](https://github.com/box/box-python-sdk-gen/issues/630)) ([6635757](https://github.com/box/box-python-sdk-gen/commit/66357578218913240bc923cb0dc771157ec95f54)) - Add Archive Public API (box/box-openapi[#540](https://github.com/box/box-python-sdk-gen/issues/540)) ([#651](https://github.com/box/box-python-sdk-gen/issues/651)) ([c36d1db](https://github.com/box/box-python-sdk-gen/commit/c36d1dbff42c89876c037983c792c5c7282459cc)) - Add new Hubs APIs and Hubs items API (box/box-openapi[#538](https://github.com/box/box-python-sdk-gen/issues/538)) ([#645](https://github.com/box/box-python-sdk-gen/issues/645)) ([1daa3e8](https://github.com/box/box-python-sdk-gen/commit/1daa3e8814403c78ed2a1d64187b8e4c379028fe)) - Add new property for network exception retry strategy (box/box-codegen[#763](https://github.com/box/box-python-sdk-gen/issues/763)) ([#650](https://github.com/box/box-python-sdk-gen/issues/650)) ([13f9593](https://github.com/box/box-python-sdk-gen/commit/13f9593dbc4a45d094ee5709d602188ef341a1a5)) - Add new schema for `Metadata Error` (box/box-openapi[#539](https://github.com/box/box-python-sdk-gen/issues/539)) ([#646](https://github.com/box/box-python-sdk-gen/issues/646)) ([49d7f34](https://github.com/box/box-python-sdk-gen/commit/49d7f349e1be4e23939ef10db1edfc6042b98175)) - Allow injecting private key decryption mechanism for JWT (box/box-codegen[#754](https://github.com/box/box-python-sdk-gen/issues/754)) ([#636](https://github.com/box/box-python-sdk-gen/issues/636)) ([4ea0af5](https://github.com/box/box-python-sdk-gen/commit/4ea0af5f8f5b5516a7c23d7912c34690c017db29)) - Improve webhook validation checks (box/box-codegen[#745](https://github.com/box/box-python-sdk-gen/issues/745)) ([#628](https://github.com/box/box-python-sdk-gen/issues/628)) ([f0ece63](https://github.com/box/box-python-sdk-gen/commit/f0ece639d761c765b3bc59fbe3ba8582af755178)) - Support Hubs beta endpoints (box/box-openapi[#531](https://github.com/box/box-python-sdk-gen/issues/531)) ([#622](https://github.com/box/box-python-sdk-gen/issues/622)) ([b5e95fe](https://github.com/box/box-python-sdk-gen/commit/b5e95fe5b219d067028aa395170718eca0d62189)) - Support new tools in AI Studio (box/box-openapi[#534](https://github.com/box/box-python-sdk-gen/issues/534)) ([#633](https://github.com/box/box-python-sdk-gen/issues/633)) ([ac76eb2](https://github.com/box/box-python-sdk-gen/commit/ac76eb2d7c5560b30c4cec171dd90b0a0ece4ab5)) ## 1.15.0 (2025-06-12) ### Bug Fixes - Compute webhook signature with and without escaping the body (box/box-codegen[#737](https://github.com/box/box-python-sdk-gen/issues/737)) ([#607](https://github.com/box/box-python-sdk-gen/issues/607)) ([e5118b8](https://github.com/box/box-python-sdk-gen/commit/e5118b8a257a042510374d91bd62a1f98c662fef)) - Fix downscope token to use `retrieveToken` method for token retrieval (box/box-codegen[#731](https://github.com/box/box-python-sdk-gen/issues/731)) ([#598](https://github.com/box/box-python-sdk-gen/issues/598)) ([e492685](https://github.com/box/box-python-sdk-gen/commit/e4926851edccd4ee7e66157050cedd0d01cec5ea)) - Fix slash escaping when calculating webhook signature (box/box-codegen[#736](https://github.com/box/box-python-sdk-gen/issues/736)) ([#603](https://github.com/box/box-python-sdk-gen/issues/603)) ([430b175](https://github.com/box/box-python-sdk-gen/commit/430b1754ec840582e28a277c6c8d369cbe7ebdf5)) - Use constant-time comparison for HMAC signatures (box/box-codegen[#739](https://github.com/box/box-python-sdk-gen/issues/739)) ([#610](https://github.com/box/box-python-sdk-gen/issues/610)) ([6f6660c](https://github.com/box/box-python-sdk-gen/commit/6f6660c8f3aa2b7b75b0fcd4ed015d8d761cd77f)) ### New Features and Enhancements - Add AI agents warnings; allow for more types of metadata value (box/box-openapi[#520](https://github.com/box/box-python-sdk-gen/issues/520)) ([#567](https://github.com/box/box-python-sdk-gen/issues/567)) ([86aa1cc](https://github.com/box/box-python-sdk-gen/commit/86aa1ccadac9acead7bceeafb50e45f38eb2d9cc)) - Add Shield Lists APIs (box/box-openapi[#528](https://github.com/box/box-python-sdk-gen/issues/528)) ([#601](https://github.com/box/box-python-sdk-gen/issues/601)) ([f980f65](https://github.com/box/box-python-sdk-gen/commit/f980f6544a58a5c64ab0b3ec13b2771b81ea25ed)) - Add support of IBM models to AI API (box/box-openapi[#522](https://github.com/box/box-python-sdk-gen/issues/522)) ([#568](https://github.com/box/box-python-sdk-gen/issues/568)) ([767547a](https://github.com/box/box-python-sdk-gen/commit/767547ae070909852800c447e65cbcc95b97c5a3)) - Update legal holds and AI models (box/box-openapi[#526](https://github.com/box/box-python-sdk-gen/issues/526)) ([#599](https://github.com/box/box-python-sdk-gen/issues/599)) ([d56228d](https://github.com/box/box-python-sdk-gen/commit/d56228d81bd9777af5431ccc9d05233e13a0c2ed)) ## 1.14.0 (2025-05-02) ### Bug Fixes - set default timeouts for requests (box/box-codegen[#707](https://github.com/box/box-python-sdk-gen/issues/707)) ([#552](https://github.com/box/box-python-sdk-gen/issues/552)) ([66b87c8](https://github.com/box/box-python-sdk-gen/commit/66b87c8986ce2f5fdb3a9eac995ef8a9643bcd76)) ### New Features and Enhancements - Add security settings properties on sign template schema (box/box-openapi[#518](https://github.com/box/box-python-sdk-gen/issues/518)) ([#543](https://github.com/box/box-python-sdk-gen/issues/543)) ([0a45d21](https://github.com/box/box-python-sdk-gen/commit/0a45d218d1aa3fa62da7b5c8c01506fb657c0b36)) - Support sensitive data sanitization in errors (box/box-codegen[#695](https://github.com/box/box-python-sdk-gen/issues/695)) ([#533](https://github.com/box/box-python-sdk-gen/issues/533)) ([abb7b1d](https://github.com/box/box-python-sdk-gen/commit/abb7b1d16a192edd99ff1fc4fb7c4caf79ee5f10)) ## 1.13.0 (2025-03-18) ### Bug Fixes - Add `verification_phone_number` property to create sign request (box/box-openapi[#515](https://github.com/box/box-python-sdk-gen/issues/515)) ([#503](https://github.com/box/box-python-sdk-gen/issues/503)) ([6d19d19](https://github.com/box/box-python-sdk-gen/commit/6d19d197481a578d7d5ad8d632ac6f5c06bd3dce)) ### New Features and Enhancements - Add find app item for shared link endpoint (box/box-openapi[#514](https://github.com/box/box-python-sdk-gen/issues/514)) ([#502](https://github.com/box/box-python-sdk-gen/issues/502)) ([fd6c693](https://github.com/box/box-python-sdk-gen/commit/fd6c6933f0fb518830e9ac810fd511a0cf60b429)) - Add Integration Mappings Teams API (box/box-openapi[#517](https://github.com/box/box-python-sdk-gen/issues/517)) ([#505](https://github.com/box/box-python-sdk-gen/issues/505)) ([d1aa250](https://github.com/box/box-python-sdk-gen/commit/d1aa250fb01fbf742daf266d4458ba2eab2c5669)) - Support upload with preflight check (box/box-codegen[#676](https://github.com/box/box-python-sdk-gen/issues/676)) ([#515](https://github.com/box/box-python-sdk-gen/issues/515)) ([bb4597e](https://github.com/box/box-python-sdk-gen/commit/bb4597e40d49e20eca44c4414e406b1352af1a2b)) ## 1.12.0 (2025-02-20) ### Bug Fixes - Fix handling responses with invalid JSON (box/box-codegen[#667](https://github.com/box/box-python-sdk-gen/issues/667)) ([#485](https://github.com/box/box-python-sdk-gen/issues/485)) ([46399d8](https://github.com/box/box-python-sdk-gen/commit/46399d8d91d9a22c75e03e870b091cac6d81237f)), closes [#470](https://github.com/box/box-python-sdk-gen/issues/470) ### New Features and Enhancements - Support AI Studio API (box/box-codegen[#626](https://github.com/box/box-python-sdk-gen/issues/626)) ([#483](https://github.com/box/box-python-sdk-gen/issues/483)) ([bd7fefa](https://github.com/box/box-python-sdk-gen/commit/bd7fefad8f2d941676732ea66c5b0d75bae9e703)) ### 1.11.1 (2025-02-12) ### Bug Fixes - Fix proxy usage (box/box-codegen[#662](https://github.com/box/box-python-sdk-gen/issues/662)) ([#476](https://github.com/box/box-python-sdk-gen/issues/476)) ([e1d62ac](https://github.com/box/box-python-sdk-gen/commit/e1d62ac5a8063bf37244329329100752c3a069af)) ## 1.11.0 (2025-02-06) ### Bug Fixes - Correct types of `paged` and `thumb` properties in File representation (box/box-openapi[#503](https://github.com/box/box-python-sdk-gen/issues/503)) ([#451](https://github.com/box/box-python-sdk-gen/issues/451)) ([e818fa6](https://github.com/box/box-python-sdk-gen/commit/e818fa6c9c80e61a293fc24ed6f1a15978681662)) ### New Features and Enhancements - Add Box Sign shared requests (box/box-openapi[#504](https://github.com/box/box-python-sdk-gen/issues/504)) ([#453](https://github.com/box/box-python-sdk-gen/issues/453)) ([3590918](https://github.com/box/box-python-sdk-gen/commit/359091873d26111b82f000e7837553cc799f2433)) - feat: Add hubs support to `/ai/ask`. Replace type of `items` parameter from `List[AiItemBase]` to `List[AiItemAsk]` in `create_ai_ask` method (box/box-openapi[#506](https://github.com/box/box-python-sdk-gen/issues/506)) ([#466](https://github.com/box/box-python-sdk-gen/issues/466)) ([29f0364](https://github.com/box/box-python-sdk-gen/commit/29f03649f3ec1471e859609d2b8bd77ad5d09106)) - Update `/ai/extract_structured` response schema (box/box-codegen[#641](https://github.com/box/box-python-sdk-gen/issues/641)) ([#459](https://github.com/box/box-python-sdk-gen/issues/459)) ([7c73cea](https://github.com/box/box-python-sdk-gen/commit/7c73ceaa8888332b23bca4d6b64ef4999f942940)) ## 1.10.0 (2025-01-21) ### Bug Fixes - Add missing token scope (box/box-openapi[#490](https://github.com/box/box-python-sdk-gen/issues/490)) ([#420](https://github.com/box/box-python-sdk-gen/issues/420)) ([41afe8b](https://github.com/box/box-python-sdk-gen/commit/41afe8bcbfc20e3ff22d34a273dcb416afb455da)) - Fix invalid variant config for Integration mapping Slack (box/box-openapi[#492](https://github.com/box/box-python-sdk-gen/issues/492)) ([#423](https://github.com/box/box-python-sdk-gen/issues/423)) ([d03ccd4](https://github.com/box/box-python-sdk-gen/commit/d03ccd46b88c71450c1c67ecef439e25b97cbad7)) - order of fields in the `IntegrationMapping` schema (box/box-openapi[#497](https://github.com/box/box-python-sdk-gen/issues/497)) ([#438](https://github.com/box/box-python-sdk-gen/issues/438)) ([13dea88](https://github.com/box/box-python-sdk-gen/commit/13dea88c4e43748eed600f55a638c14ef0a1a60a)) ### New Features and Enhancements - Support Box Doc Gen API (box/box-codegen[#644](https://github.com/box/box-python-sdk-gen/issues/644)) ([#446](https://github.com/box/box-python-sdk-gen/issues/446)) ([41fa63c](https://github.com/box/box-python-sdk-gen/commit/41fa63c0a3c957a34b03163dfeaa44a03a5873ff)) ## 1.9.0 (2024-12-30) ### Bug Fixes - Remove unused parameter from `SignRequest` (box/box-openapi[#489](https://github.com/box/box-python-sdk-gen/issues/489)) ([#411](https://github.com/box/box-python-sdk-gen/issues/411)) ([578d9b4](https://github.com/box/box-python-sdk-gen/commit/578d9b48da7e55d2e3e4736c871400dc90d826b1)) ### New Features and Enhancements - Add `ai_agent` info to `AiResponse` (box/box-openapi[#485](https://github.com/box/box-python-sdk-gen/issues/485)) ([#402](https://github.com/box/box-python-sdk-gen/issues/402)) ([351a5b8](https://github.com/box/box-python-sdk-gen/commit/351a5b8dfbc8a0095bafbbf0245d8575217fc3c9)) - Add support for replacing the network client implementation (box/box-codegen[#629](https://github.com/box/box-python-sdk-gen/issues/629)) ([#415](https://github.com/box/box-python-sdk-gen/issues/415)) ([fb118dd](https://github.com/box/box-python-sdk-gen/commit/fb118ddb1cbfb1d6a72e657bed57088fdff1ec02)) - Allow for customizing retry strategy (box/box-codegen[#635](https://github.com/box/box-python-sdk-gen/issues/635)) ([#418](https://github.com/box/box-python-sdk-gen/issues/418)) ([8dfb3ed](https://github.com/box/box-python-sdk-gen/commit/8dfb3ed13196de37a78a53325079e284c7e921d5)) - Support optional `userId` parameter for updating files, folders and web links (box/box-openapi[#488](https://github.com/box/box-python-sdk-gen/issues/488)) ([#406](https://github.com/box/box-python-sdk-gen/issues/406)) ([d9cff4c](https://github.com/box/box-python-sdk-gen/commit/d9cff4c6adc9c5cc9ce1edf73dffe8ac5979ce71)) - Support webhook message validation (box/box-codegen[#631](https://github.com/box/box-python-sdk-gen/issues/631)) ([#416](https://github.com/box/box-python-sdk-gen/issues/416)) ([0fec20b](https://github.com/box/box-python-sdk-gen/commit/0fec20b281fe195f0dd6aaf8f164bdd414587fc4)) ## 1.8.0 (2024-12-02) ### Bug Fixes - Fix enums usage (box/box-codegen[#615](https://github.com/box/box-python-sdk-gen/issues/615)) ([#387](https://github.com/box/box-python-sdk-gen/issues/387)) ([a9abccb](https://github.com/box/box-python-sdk-gen/commit/a9abccb8e552c971774ea1a9fa2096395a40317b)), closes [#385](https://github.com/box/box-python-sdk-gen/issues/385) - Support status codes with no content (box/box-codegen[#604](https://github.com/box/box-python-sdk-gen/issues/604)) ([#378](https://github.com/box/box-python-sdk-gen/issues/378)) ([051716c](https://github.com/box/box-python-sdk-gen/commit/051716c84b4f0ab32b82608f94e3cf3ba09b390b)) - update collaboration, metadata and collection resources (box/box-openapi[#483](https://github.com/box/box-python-sdk-gen/issues/483)) ([#380](https://github.com/box/box-python-sdk-gen/issues/380)) ([0d45fed](https://github.com/box/box-python-sdk-gen/commit/0d45fedc0b7b96234ef3901f412f259b1cae4c1a)) ### New Features and Enhancements - Expose method for making custom HTTP requests (box/box-codegen[#610](https://github.com/box/box-python-sdk-gen/issues/610)) ([#393](https://github.com/box/box-python-sdk-gen/issues/393)) ([55a23d9](https://github.com/box/box-python-sdk-gen/commit/55a23d9d6840642c248ab3b967ad5c2635484c8c)) - Support getting file download URL and file thumbnail URL (box/box-codegen[#617](https://github.com/box/box-python-sdk-gen/issues/617)) ([#397](https://github.com/box/box-python-sdk-gen/issues/397)) ([fd609ab](https://github.com/box/box-python-sdk-gen/commit/fd609ab9fe94da43b1a71815597c49471e157bb8)) ## 1.7.0 (2024-11-04) ### New Features and Enhancements - Support get collection by ID endpoint (box/box-codegen[#595](https://github.com/box/box-codegen/issues/595)) ([#366](https://github.com/box/box-codegen/issues/366)) ([1db5722](https://github.com/box/box-codegen/commit/1db5722f7d02694739f1a52a6b2ebe0c406960b0)), closes [#355](https://github.com/box/box-codegen/issues/355) ## 1.6.0 (2024-10-30) ### Bug Fixes - Set stream position to 0 for multipart requests (box/box-codegen[#581](https://github.com/box/box-codegen/issues/581)) ([#348](https://github.com/box/box-codegen/issues/348)) ([fa6942c](https://github.com/box/box-codegen/commit/fa6942c231024947250955ccc52f352744ab5f38)) - Update client error schema (box/box-openapi[#467](https://github.com/box/box-codegen/issues/467)) ([#347](https://github.com/box/box-codegen/issues/347)) ([a42a253](https://github.com/box/box-codegen/commit/a42a2532337c79d20b6524fda0acf717d9ccbd5f)) - Use original stream position when retrying requests (box/box-codegen[#583](https://github.com/box/box-codegen/issues/583)) ([#358](https://github.com/box/box-codegen/issues/358)) ([060b4dc](https://github.com/box/box-codegen/commit/060b4dc2b8bbbc1e17cce0fc049394e0527952b7)) - use raw `docstrings` when comments contain backslash (box/box-codegen[#571](https://github.com/box/box-codegen/issues/571)) ([#330](https://github.com/box/box-codegen/issues/330)) ([8dd8cb7](https://github.com/box/box-codegen/commit/8dd8cb71105c200bd03f5f894a4dbfb42baf0865)) ### New Features and Enhancements - Add `download_file_to_output_stream` method to `DownloadsManager` (box/box-codegen[#575](https://github.com/box/box-codegen/issues/575)) ([#334](https://github.com/box/box-codegen/issues/334)) ([6820d08](https://github.com/box/box-codegen/commit/6820d08f37c5c0605a580391bef2dc4f2a384c00)) - add AI LLM endpoint AWS `params` (box/box-openapi[#478](https://github.com/box/box-codegen/issues/478)) ([#354](https://github.com/box/box-codegen/issues/354)) ([c8fa2c1](https://github.com/box/box-codegen/commit/c8fa2c1131154d07a500290db6a7b34b06005c2b)) ### 1.5.1 (2024-09-19) ### Bug Fixes - Fix proxy `url` without proxy credentials (box/box-codegen[#568](https://github.com/box/box-codegen/issues/568)) ([#322](https://github.com/box/box-codegen/issues/322)) ([fb19160](https://github.com/box/box-codegen/commit/fb19160307b58d5f08bb12e0f846d71ff936ad6a)), closes [#318](https://github.com/box/box-codegen/issues/318) - Stop sending last empty chunk for chunk upload (box/box-codegen[#569](https://github.com/box/box-codegen/issues/569)) ([#324](https://github.com/box/box-codegen/issues/324)) ([1605f04](https://github.com/box/box-codegen/commit/1605f0495994b333e735bc98f28fa714324b75f5)), closes [#321](https://github.com/box/box-codegen/issues/321) ## 1.5.0 (2024-09-18) ### Bug Fixes - Add the missing license to `setup.py` (box/box-codegen[#562](https://github.com/box/box-codegen/issues/562)) ([#307](https://github.com/box/box-codegen/issues/307)) ([679d789](https://github.com/box/box-codegen/commit/679d7891b2a20e7407b8c9f00bd95c3b294ab861)) - Fix variants in metadata query results (box/box-openapi[#456](https://github.com/box/box-codegen/issues/456)) ([#313](https://github.com/box/box-codegen/issues/313)) ([8830303](https://github.com/box/box-codegen/commit/883030335e2a3c12a5e0b01d8a82df30ccce16a6)) ### New Features and Enhancements - Add support for proxy (box/box-codegen[#559](https://github.com/box/box-codegen/issues/559)) ([#302](https://github.com/box/box-codegen/issues/302)) ([3d881ac](https://github.com/box/box-codegen/commit/3d881acdebf2b18e2f0f82211f5abdcc32d1ddb0)) - Introduce `raw_data` field for storing raw `json` response (box/box-codegen[#566](https://github.com/box/box-codegen/issues/566)) ([#319](https://github.com/box/box-codegen/issues/319)) ([3776dc3](https://github.com/box/box-codegen/commit/3776dc3d44bc09eb68da99f45e36e058dca2607e)) - Support `ai/extract` and `ai/extract_structured` endpoints (box/box-codegen[#564](https://github.com/box/box-codegen/issues/564)) ([#317](https://github.com/box/box-codegen/issues/317)) ([b3d8da4](https://github.com/box/box-codegen/commit/b3d8da41007a9d47b73b699fd84da6f9540866d2)) - Support App item associations (box/box-codegen[#561](https://github.com/box/box-codegen/issues/561)) ([#299](https://github.com/box/box-codegen/issues/299)) ([8b6ea0b](https://github.com/box/box-codegen/commit/8b6ea0bbec719a36eb11b6d214c08801c4f1a40b)) ### 1.4.1 (2024-08-30) ### Bug Fixes - Do not store data in-memory during download process in Python (box/box-codegen[#557](https://github.com/box/box-codegen/issues/557)) ([#294](https://github.com/box/box-codegen/issues/294)) ([7c645ae](https://github.com/box/box-codegen/commit/7c645aea9fa8575531e0b40ffc997a0f65b6e409)) ## 1.4.0 (2024-08-23) ### Bug Fixes - Add missing fields to Sign Template Signer and fix AI schema (box/box-openapi[#451](https://github.com/box/box-codegen/issues/451)) ([#281](https://github.com/box/box-codegen/issues/281)) ([0708351](https://github.com/box/box-codegen/commit/0708351171eca1fe4914b823a4257bbabd3cd075)) - Fix `IntegrationMapping` schemas (box/box-codegen[#551](https://github.com/box/box-codegen/issues/551)) ([#279](https://github.com/box/box-codegen/issues/279)) ([0337e06](https://github.com/box/box-codegen/commit/0337e06c6bf6d35dd51409c429b7fef295f5a406)) ### New Features and Enhancements - Add new parameters to Box AI methods and introduce `AiResponseFull` variant (box/box-openapi[#446](https://github.com/box/box-codegen/issues/446)) ([#277](https://github.com/box/box-codegen/issues/277)) ([1267a21](https://github.com/box/box-codegen/commit/1267a215fbc8292059603665a53b0159d7a1242c)) - Include URL into `FetchOptions` (box/box-codegen[#549](https://github.com/box/box-codegen/issues/549)) ([#283](https://github.com/box/box-codegen/issues/283)) ([dd05b1c](https://github.com/box/box-codegen/commit/dd05b1c2b1687d8647f4116c022dbf1890984adc)) ## 1.3.0 (2024-08-12) ### Bug Fixes - Fix fetch method for multipart request (box/box-codegen[#545](https://github.com/box/box-codegen/issues/545)) ([#266](https://github.com/box/box-codegen/issues/266)) ([08a0818](https://github.com/box/box-codegen/commit/08a0818995d64995c3e2720a459f9221c9ca1dea)) ### New Features and Enhancements - Parametrise chunked uploads endpoint urls (box/box-openapi[#444](https://github.com/box/box-codegen/issues/444)) ([#264](https://github.com/box/box-codegen/issues/264)) ([b5bce24](https://github.com/box/box-codegen/commit/b5bce24478c70ae6bb997adc773a0e2a76223568)) ## 1.2.0 (2024-07-25) ### Bug Fixes - Improve chunked upload reliability ([#224](https://github.com/box/box-codegen/issues/224)) ([05f0353](https://github.com/box/box-codegen/commit/05f035354a76dac0d71849523e4a28641ac92aee)) ### New Features and Enhancements - Add `is_active` parameter to user collaboration (box/box-openapi[#437](https://github.com/box/box-codegen/issues/437)) ([#222](https://github.com/box/box-codegen/issues/222)) ([2b7bbe4](https://github.com/box/box-codegen/commit/2b7bbe41ed23e50c6717148fa5e9e2c24a3f5897)) - Retry request with status code `202` `(box/box-codegen[#511](https://github.com/box/box-codegen/issues/511))` ([#204](https://github.com/box/box-codegen/issues/204)) ([f50ad6e](https://github.com/box/box-codegen/commit/f50ad6e236003901792eb333738020cbdd8c8ae3)) - Support AI Agent API (box/box-codegen[#531](https://github.com/box/box-codegen/issues/531)) ([#229](https://github.com/box/box-codegen/issues/229)) ([c565383](https://github.com/box/box-codegen/commit/c5653839e1a150377e7d5c4764d4c2a7b7d07c4a)) - Support sending fields with `null` value (box/box-codegen[#528](https://github.com/box/box-codegen/issues/528)) ([#230](https://github.com/box/box-codegen/issues/230)) ([f91076e](https://github.com/box/box-codegen/commit/f91076e1bfbccae4a0dff4b66d7bafb5357858c5)), closes [#202](https://github.com/box/box-codegen/issues/202) ## 1.1.0 (2024-06-12) ### Bug Fixes - Fix CI for auto update pull requests (box/box-codegen[#506](https://github.com/box/box-codegen/issues/506)) ([#187](https://github.com/box/box-codegen/issues/187)) ([5e59f69](https://github.com/box/box-codegen/commit/5e59f69591e01cd2caf0033e0023061093989aa5)) ### New Features and Enhancements - add missing marker pagination fields and introduce new event type `AppItemEventSource` `(box/box-openapi[#431](https://github.com/box/box-codegen/issues/431))` ([#189](https://github.com/box/box-codegen/issues/189)) ([8d22ce2](https://github.com/box/box-codegen/commit/8d22ce20d57f4b5dcb5b344ff6bfc67bcaa3568d)) ## 1.0.0 (2024-05-20) ### Bug Fixes - Change base urls (box/box-codegen[#491](https://github.com/box/box-codegen/issues/491)) ([#167](https://github.com/box/box-codegen/issues/167)) ([7f7cb20](https://github.com/box/box-codegen/commit/7f7cb201720bf04efd25c21c1fb131b9f38e5f77)) - Fix schemas for updating classification on a file and folder (box/box-openapi[#423](https://github.com/box/box-codegen/issues/423)) ([#156](https://github.com/box/box-codegen/issues/156)) ([1c4bee1](https://github.com/box/box-codegen/commit/1c4bee1874dcf7f164cbe85ae200883bd4e81ea2)) - Make `PartAccumulator` class internal ([#169](https://github.com/box/box-codegen/issues/169)) ([16726e7](https://github.com/box/box-codegen/commit/16726e7324820572da50c3079b2fe449b103173d)) ### New Features and Enhancements - Add `suppressNotifications` and `externalSystemName` fields for Box Sign (box/box-openapi[#425](https://github.com/box/box-codegen/issues/425)) ([#165](https://github.com/box/box-codegen/issues/165)) ([34ea7c2](https://github.com/box/box-codegen/commit/34ea7c2275017a2d3256361de277272f36859974)) - Move schemas to separate modules (box/box-codegen[#483](https://github.com/box/box-codegen/issues/483)) ([#149](https://github.com/box/box-codegen/issues/149)) ([0ba0142](https://github.com/box/box-codegen/commit/0ba01427e8cffb3fa72892afbf281b11dac4f1ed)) - support excluding endpoints and schemas in parser (box/box-codegen[#487](https://github.com/box/box-codegen/issues/487)) ([#150](https://github.com/box/box-codegen/issues/150)) ([13308c4](https://github.com/box/box-codegen/commit/13308c48700528bd870ca97035d0c3f04e66c299)) ### 0.6.5 (2024-05-09) ### Bug Fixes - Add documentation to folder resource (box/box-openapi[#421](https://github.com/box/box-codegen/issues/421)) ([#144](https://github.com/box/box-codegen/issues/144)) ([ca4e62e](https://github.com/box/box-codegen/commit/ca4e62eafe6b508f92bfda4c7d7075e69c36fc31)) - Ensure `AuthorizationManager` in authentication classes is initialized with `NetworkSession` object (box/box-codegen[#469](https://github.com/box/box-codegen/issues/469)) ([#113](https://github.com/box/box-codegen/issues/113)) ([a5577c7](https://github.com/box/box-codegen/commit/a5577c734b5ca18567b423075661964735f6e46a)) - Fix Box AI endpoints (box/box-openapi[#418](https://github.com/box/box-codegen/issues/418)) ([#139](https://github.com/box/box-codegen/issues/139)) ([de2b8a3](https://github.com/box/box-codegen/commit/de2b8a3874d8647d9fc77d61ff998bf7d5400a69)) - Fix deserialization logic (box/box-codegen[#476](https://github.com/box/box-codegen/issues/476)) ([#126](https://github.com/box/box-codegen/issues/126)) ([90ea928](https://github.com/box/box-codegen/commit/90ea928aec6bf6a2d22c7156a570d2ade57daf80)) ### New Features and Enhancements - Support Box AI endpoints (box/box-openapi[#416](https://github.com/box/box-codegen/issues/416)) ([#137](https://github.com/box/box-codegen/issues/137)) ([7a90c0c](https://github.com/box/box-codegen/commit/7a90c0c10b29af35307fd1fbb3931442c4aad06b)) - Support revoking and downscoping token for `BoxDeveloperTokenAuth` (box/box-codegen[#472](https://github.com/box/box-codegen/issues/472)) ([#115](https://github.com/box/box-codegen/issues/115)) ([1b9628c](https://github.com/box/box-codegen/commit/1b9628c321b1ade72cbadac7ef4e63e4e7b132e0)) - Support union of primitives and objects (box/box-codegen[#481](https://github.com/box/box-codegen/issues/481)) ([#140](https://github.com/box/box-codegen/issues/140)) ([d08c3e9](https://github.com/box/box-codegen/commit/d08c3e9987c3d655b2741e412cfafa48d1959b6e)) ### 0.6.4 (2024-04-04) ### Bug Fixes - **docs:** fixes for chunked uploads docs (box/box-codegen[#457](https://github.com/box/box-codegen/issues/457)) ([#106](https://github.com/box/box-codegen/issues/106)) ([65f40f5](https://github.com/box/box-codegen/commit/65f40f55a5bd020fd9e1e2db31d4979a4f10d4cf)) ### New Features and Enhancements - Assign default value to fields and args of type enum with only one value (box/box-codegen[#465](https://github.com/box/box-codegen/issues/465)) ([#108](https://github.com/box/box-codegen/issues/108)) ([f884b60](https://github.com/box/box-codegen/commit/f884b600b8be77e8fdbbff553c066a927090c42d)) - Change `asUser` and `asEnterprise` method names (box/box-codegen[#464](https://github.com/box/box-codegen/issues/464)) ([#103](https://github.com/box/box-codegen/issues/103)) ([bb03852](https://github.com/box/box-codegen/commit/bb03852443fa0c3fcd8fec60cb10e5bff607abe5)) ### 0.6.3 (2024-03-26) ### New Features and Enhancements - Support datetime (box/box-codegen[#459](https://github.com/box/box-codegen/issues/459)) ([#98](https://github.com/box/box-codegen/issues/98)) ([5a4d1eb](https://github.com/box/box-codegen/commit/5a4d1ebec872faefeecb82fbc0262ba52cb7af9a)) ### 0.6.2 (2024-03-19) ### New Features and Enhancements - Support `additionalProperties` of type any in Python and TS (box/box-codegen[#453](https://github.com/box/box-codegen/issues/453)) ([#82](https://github.com/box/box-codegen/issues/82)) ([dfe7ef0](https://github.com/box/box-codegen/commit/dfe7ef02e47ec74da72b375d0b201df4bb9e68fc)) - use getDiscriminatorsForUnion in generic serialization (box/box-codegen[#448](https://github.com/box/box-codegen/issues/448)) ([#81](https://github.com/box/box-codegen/issues/81)) ([2bb15a8](https://github.com/box/box-codegen/commit/2bb15a8067d568a5d8699f73a2d808e8049e832f)) - Update `outcomes` parameter of `StartWorkflow` (box/box-openapi[#413](https://github.com/box/box-codegen/issues/413)) ([#88](https://github.com/box/box-codegen/issues/88)) ([238216f](https://github.com/box/box-codegen/commit/238216fa55be53c4f27e14e8807be389b2d5605a)) --- ### Changelog **Type:** page | **Section:** Additional Resources Changelog All notable changes to this project will be documented in this file. See standard-version for commit guidelines. 1.11.0 (2025-0… # Changelog All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines. ## 1.11.0 (2025-08-05) ### Bug Fixes - Fix downscope token to use `retrieveToken` method for token retrieval (box/box-codegen[#731](https://github.com/box/box-dotnet-sdk-gen/issues/731)) ([#492](https://github.com/box/box-dotnet-sdk-gen/issues/492)) ([292360e](https://github.com/box/box-dotnet-sdk-gen/commit/292360efe86797e42dbfb388a5bd2f5b41efa0c1)) - Specify events `next_stream_position` property type as `long` (box/box-openapi[#535](https://github.com/box/box-dotnet-sdk-gen/issues/535)) ([#536](https://github.com/box/box-dotnet-sdk-gen/issues/536)) ([da265bd](https://github.com/box/box-dotnet-sdk-gen/commit/da265bd5c40defc4b2036811aefad59447faca09)) ### New Features and Enhancements - Add `ReadOnlyCollection` implicit operator for Unions (box/box-codegen[#633](https://github.com/box/box-dotnet-sdk-gen/issues/633)) ([#483](https://github.com/box/box-dotnet-sdk-gen/issues/483)) ([a1fc2c5](https://github.com/box/box-dotnet-sdk-gen/commit/a1fc2c584021c151fc9d1815877ffe73c972f711)) - Add AI spreadsheet processor (box/box-openapi[#533](https://github.com/box/box-dotnet-sdk-gen/issues/533)) ([#519](https://github.com/box/box-dotnet-sdk-gen/issues/519)) ([c344023](https://github.com/box/box-dotnet-sdk-gen/commit/c34402355243145a1cab7da78c6c2facde39fb36)) - Add Archive Public API (box/box-openapi[#540](https://github.com/box/box-dotnet-sdk-gen/issues/540)) ([#543](https://github.com/box/box-dotnet-sdk-gen/issues/543)) ([be0bb9d](https://github.com/box/box-dotnet-sdk-gen/commit/be0bb9d3e58f97bc87f749d08d828c990c71789b)) - Add new Hubs APIs and Hubs items API (box/box-openapi[#538](https://github.com/box/box-dotnet-sdk-gen/issues/538)) ([#537](https://github.com/box/box-dotnet-sdk-gen/issues/537)) ([f2584cd](https://github.com/box/box-dotnet-sdk-gen/commit/f2584cd9be40b67eaa3a500411b367543a26f830)) - Add new schema for `Metadata Error` (box/box-openapi[#539](https://github.com/box/box-dotnet-sdk-gen/issues/539)) ([#538](https://github.com/box/box-dotnet-sdk-gen/issues/538)) ([425b4ad](https://github.com/box/box-dotnet-sdk-gen/commit/425b4add7975d49584c8ed18a791caf72559203c)) - add Shield Lists APIs (box/box-openapi[#528](https://github.com/box/box-dotnet-sdk-gen/issues/528)) ([#496](https://github.com/box/box-dotnet-sdk-gen/issues/496)) ([8b81c87](https://github.com/box/box-dotnet-sdk-gen/commit/8b81c879c8b8bb5c020ecb573e527e2a5d9f1701)) - Allow injecting private key decryption mechanism for JWT (box/box-codegen[#754](https://github.com/box/box-dotnet-sdk-gen/issues/754)) ([#528](https://github.com/box/box-dotnet-sdk-gen/issues/528)) ([865c729](https://github.com/box/box-dotnet-sdk-gen/commit/865c729395556a3c4a8bb1f1418c3932d268bdc4)) - Make `OneOf` classes public (box/box-codegen[#773](https://github.com/box/box-dotnet-sdk-gen/issues/773)) ([#551](https://github.com/box/box-dotnet-sdk-gen/issues/551)) ([f7dcc32](https://github.com/box/box-dotnet-sdk-gen/commit/f7dcc3262b289da55ebc6210c5656cc98e3b14b4)) - Support Hubs beta endpoints (box/box-openapi[#531](https://github.com/box/box-dotnet-sdk-gen/issues/531)) ([#511](https://github.com/box/box-dotnet-sdk-gen/issues/511)) ([59c43b8](https://github.com/box/box-dotnet-sdk-gen/commit/59c43b868e46edd26be0be13a5e1772a4d731128)) - Support new tools in AI Studio (box/box-openapi[#534](https://github.com/box/box-dotnet-sdk-gen/issues/534)) ([#520](https://github.com/box/box-dotnet-sdk-gen/issues/520)) ([0b47597](https://github.com/box/box-dotnet-sdk-gen/commit/0b47597f259884a2a5f567608e9e07997e3c6dc9)) - Update legal holds and AI models (box/box-openapi[#526](https://github.com/box/box-dotnet-sdk-gen/issues/526)) ([#494](https://github.com/box/box-dotnet-sdk-gen/issues/494)) ([6310e56](https://github.com/box/box-dotnet-sdk-gen/commit/6310e560df6d9520598295139f55ec8a0a4d69d9)) ## 1.10.0 (2025-05-13) ### New Features and Enhancements - Add `UploadWithPreflightCheck` convenient method (box/box-codegen[#705](https://github.com/box/box-dotnet-sdk-gen/issues/705)) ([#469](https://github.com/box/box-dotnet-sdk-gen/issues/469)) ([8dff7bb](https://github.com/box/box-dotnet-sdk-gen/commit/8dff7bb859cd034d4e43b81c7c11b9a3fdb396e8)) - Add AI agents warnings; allow for more types of metadata value (box/box-openapi[#520](https://github.com/box/box-dotnet-sdk-gen/issues/520)) ([#474](https://github.com/box/box-dotnet-sdk-gen/issues/474)) ([a53cff5](https://github.com/box/box-dotnet-sdk-gen/commit/a53cff54395db91bad179d3c5bbae9800c1b79dd)) - Add security settings properties on sign template schema (box/box-openapi[#518](https://github.com/box/box-dotnet-sdk-gen/issues/518)) ([#462](https://github.com/box/box-dotnet-sdk-gen/issues/462)) ([7fddaea](https://github.com/box/box-dotnet-sdk-gen/commit/7fddaeab425a859dc1aa5dc3420891047d27efdf)) - Add support of IBM models to AI API (box/box-openapi[#522](https://github.com/box/box-dotnet-sdk-gen/issues/522)) ([#475](https://github.com/box/box-dotnet-sdk-gen/issues/475)) ([a187301](https://github.com/box/box-dotnet-sdk-gen/commit/a187301543d6741c77799b66fde0f12d4fca710d)) - Support sensitive data sanitization in errors (box/box-codegen[#695](https://github.com/box/box-dotnet-sdk-gen/issues/695)) ([#453](https://github.com/box/box-dotnet-sdk-gen/issues/453)) ([5ee0c93](https://github.com/box/box-dotnet-sdk-gen/commit/5ee0c932254a0cd1cc7bc814c29fe5f9e2151462)) ## 1.9.0 (2025-03-18) ### Bug Fixes - Add `verification_phone_number` property to create sign request (box/box-openapi[#515](https://github.com/box/box-dotnet-sdk-gen/issues/515)) ([#427](https://github.com/box/box-dotnet-sdk-gen/issues/427)) ([d90faea](https://github.com/box/box-dotnet-sdk-gen/commit/d90faea77650a37ce794a93c51bd9a8eb91f619c)) - Use `targetFramework` when single .Net version is supported (box/box-codegen[#684](https://github.com/box/box-dotnet-sdk-gen/issues/684)) ([#438](https://github.com/box/box-dotnet-sdk-gen/issues/438)) ([4e64174](https://github.com/box/box-dotnet-sdk-gen/commit/4e64174c21c6f1dd2cef75f1f29ebe2ace92d852)) ### New Features and Enhancements - Add find app item for shared link endpoint (box/box-openapi[#514](https://github.com/box/box-dotnet-sdk-gen/issues/514)) ([#426](https://github.com/box/box-dotnet-sdk-gen/issues/426)) ([4dc5dc1](https://github.com/box/box-dotnet-sdk-gen/commit/4dc5dc14e3c204c537180df166d07735ae1c4e40)) - Add Integration Mappings Teams API (box/box-openapi[#517](https://github.com/box/box-dotnet-sdk-gen/issues/517)) ([#429](https://github.com/box/box-dotnet-sdk-gen/issues/429)) ([92063c4](https://github.com/box/box-dotnet-sdk-gen/commit/92063c435d7cb38a7eeca2e71f42e32b995a659a)) - Expose token storage for authentication classes (box/box-codegen[#682](https://github.com/box/box-dotnet-sdk-gen/issues/682)) ([#435](https://github.com/box/box-dotnet-sdk-gen/issues/435)) ([413058e](https://github.com/box/box-dotnet-sdk-gen/commit/413058e78cb69c89be6a819c0e63f9457bd7f2f5)) ## 1.8.0 (2025-02-20) ### Bug Fixes - Do not retry HTTP request when `TaskCanceledException` is thrown (box/box-codegen[#665](https://github.com/box/box-dotnet-sdk-gen/issues/665)) ([#406](https://github.com/box/box-dotnet-sdk-gen/issues/406)) ([1af0a6a](https://github.com/box/box-dotnet-sdk-gen/commit/1af0a6aaf5f1e80f092ce506abe1cc01bf110bb8)) ### New Features and Enhancements - Support AI Studio API (box/box-codegen[#626](https://github.com/box/box-dotnet-sdk-gen/issues/626)) ([#409](https://github.com/box/box-dotnet-sdk-gen/issues/409)) ([9661450](https://github.com/box/box-dotnet-sdk-gen/commit/966145021d4a1dd450cd199cc9ed3e9457f5a141)) ## 1.7.0 (2025-02-06) ### Bug Fixes - Correct types of `paged` and `thumb` properties in File representation (box/box-openapi[#503](https://github.com/box/box-dotnet-sdk-gen/issues/503)) ([#383](https://github.com/box/box-dotnet-sdk-gen/issues/383)) ([d6995ad](https://github.com/box/box-dotnet-sdk-gen/commit/d6995ad8ffa4f2cceb8195ffbfb6606f934a671f)) - Prevent `Authentication` header from being passed during cross-origin redirects (box/box-codegen[#648](https://github.com/box/box-dotnet-sdk-gen/issues/648)) ([#382](https://github.com/box/box-dotnet-sdk-gen/issues/382)) ([a64d373](https://github.com/box/box-dotnet-sdk-gen/commit/a64d373a935cd2a8e6f72184b8dc129a973e9d45)) ### New Features and Enhancements - Add Box Sign shared requests (box/box-openapi[#504](https://github.com/box/box-dotnet-sdk-gen/issues/504)) ([#384](https://github.com/box/box-dotnet-sdk-gen/issues/384)) ([d563886](https://github.com/box/box-dotnet-sdk-gen/commit/d563886f2a2f48a20df13600f9c25ff95198a56f)) - feat: Add hubs support to /ai/ask. Replace type of `Items` property from `IReadOnlyList<AiItemBase>` to `IReadOnlyList<AiItemAsk>` in the `AiAsk` class (box/box-codegen[#656](https://github.com/box/box-dotnet-sdk-gen/issues/656)) ([#397](https://github.com/box/box-dotnet-sdk-gen/issues/397)) ([32b6d03](https://github.com/box/box-dotnet-sdk-gen/commit/32b6d03aba97c18a8901efe98fc60c74e10197ce)) - Update `/ai/extract_structured` response schema (box/box-codegen[#641](https://github.com/box/box-dotnet-sdk-gen/issues/641)) ([#391](https://github.com/box/box-dotnet-sdk-gen/issues/391)) ([5f79a03](https://github.com/box/box-dotnet-sdk-gen/commit/5f79a03453b9339a26eb130113d8f55748f0d912)) ## 1.6.0 (2025-01-21) ### Bug Fixes - Add missing token scope (box/box-openapi[#490](https://github.com/box/box-dotnet-sdk-gen/issues/490)) ([#353](https://github.com/box/box-dotnet-sdk-gen/issues/353)) ([d41e1c8](https://github.com/box/box-dotnet-sdk-gen/commit/d41e1c8c3195a08850f3217fe747e9751a979c76)) - Fix invalid variant config for Integration mapping Slack (box/box-openapi[#492](https://github.com/box/box-dotnet-sdk-gen/issues/492)) ([#356](https://github.com/box/box-dotnet-sdk-gen/issues/356)) ([8320fb7](https://github.com/box/box-dotnet-sdk-gen/commit/8320fb7da8449a8ae9965bd3496523a0f3bfe5af)) - order of fields in the `IntegrationMapping` schema (box/box-openapi[#497](https://github.com/box/box-dotnet-sdk-gen/issues/497)) ([#370](https://github.com/box/box-dotnet-sdk-gen/issues/370)) ([3361ad1](https://github.com/box/box-dotnet-sdk-gen/commit/3361ad1833670f9e99902b2206112592f7272ab8)) - unused parameter from `SignRequest` (box/box-openapi[#489](https://github.com/box/box-dotnet-sdk-gen/issues/489)) ([#343](https://github.com/box/box-dotnet-sdk-gen/issues/343)) ([5d88a51](https://github.com/box/box-dotnet-sdk-gen/commit/5d88a5176489f82057a93bd5dc119e4ae3afdcd7)) ### New Features and Enhancements - Add `aiAgent` info to `AiResponse` (box/box-openapi[#485](https://github.com/box/box-dotnet-sdk-gen/issues/485)) ([#336](https://github.com/box/box-dotnet-sdk-gen/issues/336)) ([cbf91fc](https://github.com/box/box-dotnet-sdk-gen/commit/cbf91fc23012588f0f4175a713d562738818218e)) - Add support for replacing the network client implementation (box/box-codegen[#629](https://github.com/box/box-dotnet-sdk-gen/issues/629)) ([#347](https://github.com/box/box-dotnet-sdk-gen/issues/347)) ([29d904e](https://github.com/box/box-dotnet-sdk-gen/commit/29d904e72fd9c4511183ba35454a82ff9c2d7358)) - Support Box Doc Gen API (box/box-codegen[#644](https://github.com/box/box-dotnet-sdk-gen/issues/644)) ([#378](https://github.com/box/box-dotnet-sdk-gen/issues/378)) ([5cd0fde](https://github.com/box/box-dotnet-sdk-gen/commit/5cd0fdefb6a976fb8904beb08752f3e7dbb7428b)) - Support getting file download URL and file thumbnail URL (box/box-codegen[#642](https://github.com/box/box-dotnet-sdk-gen/issues/642)) ([#374](https://github.com/box/box-dotnet-sdk-gen/issues/374)) ([76b1513](https://github.com/box/box-dotnet-sdk-gen/commit/76b151371f405940eef5ef34fb00809c8f1d8f35)) - Support optional `userId` parameter for updating files, folders and web links (box/box-openapi[#488](https://github.com/box/box-dotnet-sdk-gen/issues/488)) ([#340](https://github.com/box/box-dotnet-sdk-gen/issues/340)) ([fd1c597](https://github.com/box/box-dotnet-sdk-gen/commit/fd1c59739c5361ec4462d2597f504fa3cff5be17)) ## 1.5.0 (2024-12-04) ### Bug Fixes - Support status codes with no content (box/box-codegen[#604](https://github.com/box/box-dotnet-sdk-gen/issues/604)) ([#314](https://github.com/box/box-dotnet-sdk-gen/issues/314)) ([57747d5](https://github.com/box/box-dotnet-sdk-gen/commit/57747d50c48dd4c433dad342a5e2a20ac0b15952)) - update collaboration, metadata and collection resources (box/box-openapi[#483](https://github.com/box/box-dotnet-sdk-gen/issues/483)) ([#316](https://github.com/box/box-dotnet-sdk-gen/issues/316)) ([d331f8a](https://github.com/box/box-dotnet-sdk-gen/commit/d331f8a1f7110e5e00df170cedef85af682d58b4)) ### New Features and Enhancements - Add optional URL parameter to `FetchResponse` (box/box-codegen[#617](https://github.com/box/box-dotnet-sdk-gen/issues/617)) ([#331](https://github.com/box/box-dotnet-sdk-gen/issues/331)) ([61484ec](https://github.com/box/box-dotnet-sdk-gen/commit/61484ec9fbf96c0ae62116ec1ee0cbb50aae7493)) - Allow using default credentials for proxy (box/box-codegen[#623](https://github.com/box/box-dotnet-sdk-gen/issues/623)) ([#334](https://github.com/box/box-dotnet-sdk-gen/issues/334)) ([bc4636e](https://github.com/box/box-dotnet-sdk-gen/commit/bc4636e64859fd7d0b1449ec34b6144d0eb1a768)), closes [#333](https://github.com/box/box-dotnet-sdk-gen/issues/333) - Expose method for making custom HTTP requests (box/box-codegen[#622](https://github.com/box/box-dotnet-sdk-gen/issues/622)) ([#329](https://github.com/box/box-dotnet-sdk-gen/issues/329)) ([e689140](https://github.com/box/box-dotnet-sdk-gen/commit/e689140d6d3be772ff2370e7de5797707df7bdad)) - Support get collection by ID endpoint (box/box-codegen[#595](https://github.com/box/box-dotnet-sdk-gen/issues/595)) ([#304](https://github.com/box/box-dotnet-sdk-gen/issues/304)) ([9ebf59a](https://github.com/box/box-dotnet-sdk-gen/commit/9ebf59ae388aa9aec5d8a0a3551f13e544c7571d)) ## 1.4.0 (2024-10-31) ### Bug Fixes - Change `QueryParams` type in `MetadataQuery` from `Dictionary<string, string>` to `Dictionary<string, object>` (box/box-openapi[#479](https://github.com/box/box-codegen/issues/479)) ([#298](https://github.com/box/box-codegen/issues/298)) ([656b495](https://github.com/box/box-codegen/commit/656b495bea779879bb82b2cda0cca5a30a8ad8ca)) - Fix conversion to `RSAKey` (box/box-codegen[#591](https://github.com/box/box-codegen/issues/591)) ([#297](https://github.com/box/box-codegen/issues/297)) ([068b1f7](https://github.com/box/box-codegen/commit/068b1f7b3ea3c62647e03e0e17176bde049949db)) ### New Features and Enhancements - add AI LLM endpoint AWS `params`. Change the type from `AiLlmEndpointParamsGoogleOrAiLlmEndpointParamsOpenAi` to `AiLlmEndpointParamsAwsOrAiLlmEndpointParamsGoogleOrAiLlmEndpointParamsOpenAi` (box/box-openapi[#478](https://github.com/box/box-codegen/issues/478)) ([#291](https://github.com/box/box-codegen/issues/291)) ([dcb8a20](https://github.com/box/box-codegen/commit/dcb8a201577be08b644266c157db45cd6797c71c)) ### 1.3.1 (2024-10-24) ### Bug Fixes - properly serialize `StringEnum` list when inside query `params` ([#288](https://github.com/box/box-codegen/issues/288)) ([dac8392](https://github.com/box/box-codegen/commit/dac839280b43f4bd954d3966032ff4925150c061)) - update client error schema to support schema errors (box/box-openapi[#467](https://github.com/box/box-codegen/issues/467)) ([#281](https://github.com/box/box-codegen/issues/281)) ([bef2632](https://github.com/box/box-codegen/commit/bef2632af99f0477bd009bcb91248c678b4e1bab)) - update integration mapping response description (box/box-openapi[#463](https://github.com/box/box-codegen/issues/463)) ([#279](https://github.com/box/box-codegen/issues/279)) ([05e07b0](https://github.com/box/box-codegen/commit/05e07b025c234de4c4161e567c0919748d24f804)) ## 1.3.0 (2024-10-17) ### Bug Fixes - bump `system.text.json` to 8.0.5 (box/box-codegen[#578](https://github.com/box/box-codegen/issues/578)) ([#271](https://github.com/box/box-codegen/issues/271)) ([dad2f52](https://github.com/box/box-codegen/commit/dad2f521066e73c3dcdaec196cd6940401e31f3a)) ### New Features and Enhancements - support proxy (box/box-codegen[#577](https://github.com/box/box-codegen/issues/577)) ([#274](https://github.com/box/box-codegen/issues/274)) ([dea1937](https://github.com/box/box-codegen/commit/dea19373a7169365acb968a66c78c5937ef698e1)) ## 1.2.0 (2024-09-26) ### Bug Fixes - correctly send `datetime` when in `queryParams` (box/box-codegen[#560](https://github.com/box/box-codegen/issues/560)) ([#243](https://github.com/box/box-codegen/issues/243)) ([9657526](https://github.com/box/box-codegen/commit/9657526667753d77eacfd674cde60ab4030ae42d)) - Fix variants in metadata query results (box/box-openapi[#456](https://github.com/box/box-codegen/issues/456)) ([#249](https://github.com/box/box-codegen/issues/249)) ([37625ea](https://github.com/box/box-codegen/commit/37625eabe4f87d57a9f58920829c00cddd34bcb1)) ### New Features and Enhancements - add Hubs Beta (box/box-openapi[#453](https://github.com/box/box-codegen/issues/453)) ([#241](https://github.com/box/box-codegen/issues/241)) ([c28f660](https://github.com/box/box-codegen/commit/c28f6605c94e250bbab853ef610c46c1d3c9ef95)) - include raw `json` in types (box/box-codegen[#567](https://github.com/box/box-codegen/issues/567)) ([#258](https://github.com/box/box-codegen/issues/258)) ([a1e7bc5](https://github.com/box/box-codegen/commit/a1e7bc55da0dec8bfd1159a1c158154177581019)) - Support `ai/extract` and `ai/extract_structured` endpoints (box/box-codegen[#564](https://github.com/box/box-codegen/issues/564)) ([#253](https://github.com/box/box-codegen/issues/253)) ([a17d8f8](https://github.com/box/box-codegen/commit/a17d8f8dbce8ac7f42b9e23c8c216e992a64d762)) ## 1.1.0 (2024-08-23) ### Bug Fixes - Add missing `item_upload` scope ([#201](https://github.com/box/box-codegen/issues/201)) ([483b055](https://github.com/box/box-codegen/commit/483b05586f8e45771e101d286fddebc564ff89bd)) - Add missing fields to Sign Template Signer and fix AI schema (box/box-openapi[#451](https://github.com/box/box-codegen/issues/451)) ([#229](https://github.com/box/box-codegen/issues/229)) ([121f733](https://github.com/box/box-codegen/commit/121f733f52e945927125f4941206b1553202914d)) - Fix `IntegrationMapping` schemas (box/box-codegen[#551](https://github.com/box/box-codegen/issues/551)) ([#226](https://github.com/box/box-codegen/issues/226)) ([3eca154](https://github.com/box/box-codegen/commit/3eca15434b65bc0bb2421d36ec50691e7fe40e3b)) - Improve handling of network exceptions, handle big file upload (box/box-openapi[#444](https://github.com/box/box-codegen/issues/444)) ([#222](https://github.com/box/box-codegen/issues/222)) ([75ccd07](https://github.com/box/box-codegen/commit/75ccd078e29015b865462ea1aaf0420d5e63d9cd)) ### New Features and Enhancements - add new parameters to Box AI methods and introduce `AiResponseFull` variant (box/box-openapi[#446](https://github.com/box/box-codegen/issues/446)) ([#224](https://github.com/box/box-codegen/issues/224)) ([6d205c4](https://github.com/box/box-codegen/commit/6d205c4e28a657ad65ae704a7343a8670806f7f1)) - Include URL into `FetchOptions` (box/box-codegen[#549](https://github.com/box/box-codegen/issues/549)) ([#231](https://github.com/box/box-codegen/issues/231)) ([41c45dc](https://github.com/box/box-codegen/commit/41c45dcf6476b6cae7941c0952c375aa76ce42a1)) - parametrise chunked uploads endpoint urls (box/box-openapi[#444](https://github.com/box/box-codegen/issues/444)) ([#208](https://github.com/box/box-codegen/issues/208)) ([feac37c](https://github.com/box/box-codegen/commit/feac37c34f99b5951731b605ef895f7f3b5de6dd)) - Support `nullable` fields (box/box-codegen[#550](https://github.com/box/box-codegen/issues/550)) ([#230](https://github.com/box/box-codegen/issues/230)) ([b9da32b](https://github.com/box/box-codegen/commit/b9da32b27f506618faa0119f725528555be14f60)) ## 1.0.0 (2024-07-24) ### Bug Fixes - Extract `IntegrationMappingPartnerItemSlack` to `IntegrationMappingPartnerItemSlackUnion` (box/box-codegen[#530](https://github.com/box/box-codegen/issues/530)) ([#183](https://github.com/box/box-codegen/issues/183)) ([3b1b634](https://github.com/box/box-codegen/commit/3b1b634904edc73af094aa8aa6e89d32b9e92aee)) - Improve chunked upload reliability (box/box-codegen[#529](https://github.com/box/box-codegen/issues/529)) ([#182](https://github.com/box/box-codegen/issues/182)) ([e2a045f](https://github.com/box/box-codegen/commit/e2a045f5d2afbe15be0284099ee2236f9c19cd73)) - remove `init` from some of the required fields, `nullability` fixes (box/box-codegen[#532](https://github.com/box/box-codegen/issues/532)) ([#190](https://github.com/box/box-codegen/issues/190)) ([c58f8af](https://github.com/box/box-codegen/commit/c58f8afa41fa4346eb3f2ced9e48695980e917e1)) - retry requests with status code of 202 and `retry-after` header (box/box-codegen[#533](https://github.com/box/box-codegen/issues/533)) ([#191](https://github.com/box/box-codegen/issues/191)) ([abaafd7](https://github.com/box/box-codegen/commit/abaafd70b982ae560430ff083b4bee1d533d5275)) - Update chunked upload (box/box-codegen[#523](https://github.com/box/box-codegen/issues/523)) ([#177](https://github.com/box/box-codegen/issues/177)) ([9bcaf51](https://github.com/box/box-codegen/commit/9bcaf51e0bcd3134dea2b37277a24abaa483754a)) ### New Features and Enhancements - Add `is_active` parameter to user collaboration (box/box-openapi[#437](https://github.com/box/box-codegen/issues/437)) ([#181](https://github.com/box/box-codegen/issues/181)) ([ec5f2d1](https://github.com/box/box-codegen/commit/ec5f2d1d2cdba330f26a7db40042b70d3ec5bca2)) - simplify `namespaces` (box/box-codegen[#518](https://github.com/box/box-codegen/issues/518)) ([#175](https://github.com/box/box-codegen/issues/175)) ([7831b09](https://github.com/box/box-codegen/commit/7831b098971616497cbc90a8c277fee9b2c42c39)) - Support AI Agent API (box/box-codegen[#531](https://github.com/box/box-codegen/issues/531)) ([#188](https://github.com/box/box-codegen/issues/188)) ([0c29645](https://github.com/box/box-codegen/commit/0c296458ef966e57c5aba2a8068034d4de820ef9)) - Support default interface properties, bump dependencies (box/box-codegen[#527](https://github.com/box/box-codegen/issues/527)) ([#184](https://github.com/box/box-codegen/issues/184)) ([6b52792](https://github.com/box/box-codegen/commit/6b52792057ab94f6bcc2f86b47e0ed5f25900adf)) ## 0.4.0 (2024-07-03) ### Bug Fixes - Change base urls (box/box-codegen[#491](https://github.com/box/box-codegen/issues/491)) ([#126](https://github.com/box/box-codegen/issues/126)) ([b4c6025](https://github.com/box/box-codegen/commit/b4c6025dc7039e923b19282333f162bb9d3469a9)) - Fix CI for auto update pull requests (box/box-codegen[#506](https://github.com/box/box-codegen/issues/506)) ([#152](https://github.com/box/box-codegen/issues/152)) ([766f03c](https://github.com/box/box-codegen/commit/766f03c743b7a2ab363135ff282e468b6b71d377)) - Fix schemas for updating classification on a file and folder (box/box-openapi[#423](https://github.com/box/box-codegen/issues/423)) ([#117](https://github.com/box/box-codegen/issues/117)) ([40f5a97](https://github.com/box/box-codegen/commit/40f5a97ea44118ff9425e8b0ebb767d9ed08cee7)) - Improve wording for box sign (box/box-openapi[#424](https://github.com/box/box-codegen/issues/424)) ([#122](https://github.com/box/box-codegen/issues/122)) ([64b3bcd](https://github.com/box/box-codegen/commit/64b3bcd2d99039d1c881a565de6e7bc40dfe7aa9)) ### New Features and Enhancements - Add default implementation for interface methods (box/box-codegen[#502](https://github.com/box/box-codegen/issues/502)) ([#148](https://github.com/box/box-codegen/issues/148)) ([0f39071](https://github.com/box/box-codegen/commit/0f39071d2442b9d07f9c51de8a5a757b16cc4fe7)) - Add docs improvements and marker pagination (box/box-openapi[#431](https://github.com/box/box-codegen/issues/431)) ([#153](https://github.com/box/box-codegen/issues/153)) ([780a58b](https://github.com/box/box-codegen/commit/780a58b4d4b18c357381c76dd5e72dd791a20d89)) - Add support for `ExtraData` of generic type `(box/box-codegen[#521](https://github.com/box/box-codegen/issues/521))` ([#170](https://github.com/box/box-codegen/issues/170)) ([2a2208d](https://github.com/box/box-codegen/commit/2a2208d422f5beb1718576acdc10d9eb973ba95c)) - Add support for unions of primitives (box/box-codegen[#501](https://github.com/box/box-codegen/issues/501)) ([#150](https://github.com/box/box-codegen/issues/150)) ([e75ce82](https://github.com/box/box-codegen/commit/e75ce82b09641d4bec439d620facbbf25da97845)) - Make models immutable, hide fields for auths (box/box-codegen[#494](https://github.com/box/box-codegen/issues/494)) ([#127](https://github.com/box/box-codegen/issues/127)) ([8adcc85](https://github.com/box/box-codegen/commit/8adcc858ef0f924f168406b031d379c786fa90d0)) - Add `SuppressNotifications` and `ExternalSystemName` fields for Box Sign (box/box-openapi[#425](https://github.com/box/box-codegen/issues/425)) ([#124](https://github.com/box/box-codegen/issues/124)) ([c841881](https://github.com/box/box-codegen/commit/c841881cea9b0636bb624fe45d77c2817327dd35)) - Support `StringEnum` (box/box-codegen[#514](https://github.com/box/box-codegen/issues/514)) ([#162](https://github.com/box/box-codegen/issues/162)) ([6ac2fe9](https://github.com/box/box-codegen/commit/6ac2fe9811efde6b02cd3ca50834b0bdafea1ab3)) ### 0.3.1 (2024-05-14) ### Bug Fixes - **docs:** fixes for chunked uploads docs (box/box-codegen[#457](https://github.com/box/box-codegen/issues/457)) ([#64](https://github.com/box/box-codegen/issues/64)) ([744fd8b](https://github.com/box/box-codegen/commit/744fd8b9586a7985eb7ff06d7a1379857da9886c)) - fix `datetimeToString` utils function (box/box-codegen[#459](https://github.com/box/box-codegen/issues/459)) ([#57](https://github.com/box/box-codegen/issues/57)) ([96745b6](https://github.com/box/box-codegen/commit/96745b64b75ded429a3ae5709ea826ffddede406)) - Fix Box AI endpoints (box/box-openapi[#418](https://github.com/box/box-codegen/issues/418)) ([#92](https://github.com/box/box-codegen/issues/92)) ([450a46d](https://github.com/box/box-codegen/commit/450a46d5e76df86d1f23a246094cf098dfafb689)) - fix docs code samples (box/box-codegen[#451](https://github.com/box/box-codegen/issues/451)) ([#53](https://github.com/box/box-codegen/issues/53)) ([5f79cfd](https://github.com/box/box-codegen/commit/5f79cfd07c8b922961c3db56d64dc142aec1191c)) - Fix metadata filter resource (box/box-openapi[#419](https://github.com/box/box-codegen/issues/419)) ([#94](https://github.com/box/box-codegen/issues/94)) ([8c119e7](https://github.com/box/box-codegen/commit/8c119e75719ea8557437f7a71d2c22409ae93cad)) - fix queryParams when they contain a json array (box/box-codegen[#470](https://github.com/box/box-codegen/issues/470)) ([#67](https://github.com/box/box-codegen/issues/67)) ([9e860cf](https://github.com/box/box-codegen/commit/9e860cf977e677f34350aa09249b1752f2c5004e)) - remove mixed union case serialization in c# (box/box-codegen[#485](https://github.com/box/box-codegen/issues/485)) ([#96](https://github.com/box/box-codegen/issues/96)) ([4b44940](https://github.com/box/box-codegen/commit/4b4494085e1977ddd563c316f8fe7feca9ccb425)) ### New Features and Enhancements - Assign default value to fields and args of type enum with only one value (box/box-codegen[#465](https://github.com/box/box-codegen/issues/465)) ([#66](https://github.com/box/box-codegen/issues/66)) ([be7a2b2](https://github.com/box/box-codegen/commit/be7a2b261610564bccc1ffdd59116fc37390ae2b)) - Change `asUser` and `asEnterprise` method names (box/box-codegen[#464](https://github.com/box/box-codegen/issues/464)) ([#61](https://github.com/box/box-codegen/issues/61)) ([f654666](https://github.com/box/box-codegen/commit/f65466661c1f4b73e43025d8f2f7c1b843fea252)) - Move schemas to separate modules (box/box-codegen[#483](https://github.com/box/box-codegen/issues/483)) ([#104](https://github.com/box/box-codegen/issues/104)) ([1c58465](https://github.com/box/box-codegen/commit/1c58465bf9405cda1aebce9f36d800022c09635c)) - Support Box AI endpoints (box/box-openapi[#416](https://github.com/box/box-codegen/issues/416)) ([#90](https://github.com/box/box-codegen/issues/90)) ([7664392](https://github.com/box/box-codegen/commit/7664392651e0338098bc1d1b1bc1f79477f158f3)) - support excluding endpoints and schemas in parser (box/box-codegen[#487](https://github.com/box/box-codegen/issues/487)) ([#105](https://github.com/box/box-codegen/issues/105)) ([d6aedf8](https://github.com/box/box-codegen/commit/d6aedf801890d96bf2e9da0b797136f771076ecc)) - support revoking and downscoping token for BoxDeveloperTokenAuth ([#74](https://github.com/box/box-codegen/issues/74)) ([adb7e04](https://github.com/box/box-codegen/commit/adb7e0491dab3cb527fe5992964cf190b51f1900)) - Update `outcomes` parameter of `StartWorkflow` (box/box-openapi[#413](https://github.com/box/box-codegen/issues/413)) ([#50](https://github.com/box/box-codegen/issues/50)) ([02c7c2b](https://github.com/box/box-codegen/commit/02c7c2b74b70d92be372b57c7b7b4473b98d76d0)) - use getDiscriminatorForUnion in C# (box/box-codegen[#462](https://github.com/box/box-codegen/issues/462)) ([#62](https://github.com/box/box-codegen/issues/62)) ([c6846d8](https://github.com/box/box-codegen/commit/c6846d8334fdb06da22f99baf416007230c69252)) ### 0.3.0 (2024-03-13) ### New Features and Enhancements - add method to authentication classes (box/box-codegen[#442](https://github.com/box/box-dotnet-sdk-gen/issues/442)) ([5560f23](https://github.com/box/box-dotnet-sdk-gen/commit/5560f2334d50e568d20a5b83bd7e99510ff97ca5)) - add `retrieveAuthorizationHeader` method to authentication classes (box/box-codegen[#442](https://github.com/box/box-dotnet-sdk-gen/issues/442)) ([480a710](https://github.com/box/box-dotnet-sdk-gen/commit/480a710f8fd713bc9355d85ac8919d4ad988dc92)) - add local to Function, Field and Type to mark as private for Python (box/box-codegen[#440](https://github.com/box/box-dotnet-sdk-gen/issues/440)) ([6c699c7](https://github.com/box/box-dotnet-sdk-gen/commit/6c699c7e17b6232b4900d37aa0e73059450ac1c3)) - Support version in request headers (box/box-codegen[#418](https://github.com/box/box-dotnet-sdk-gen/issues/418)) ([#34](https://github.com/box/box-dotnet-sdk-gen/issues/34)) ([cdc5806](https://github.com/box/box-dotnet-sdk-gen/commit/cdc5806fba30cf07e4f17e02e106b55c0a7c6a1d)) - throw BoxApiError in C# fetch, add additional data to ResponseInfo (box/box-codegen[#439](https://github.com/box/box-dotnet-sdk-gen/issues/439)) ([#23](https://github.com/box/box-dotnet-sdk-gen/issues/23)) ([6dce6d7](https://github.com/box/box-dotnet-sdk-gen/commit/6dce6d7eb28aa7936db1fecdedeff24eadded2c7)) --- ### ChunkedUploadsManager **Type:** page | **Section:** Additional Resources ChunkedUploadsManager This is a manager for chunked uploads (allowed for files at least 20MB). Create upload session Create upload session… # ChunkedUploadsManager This is a manager for chunked uploads (allowed for files at least 20MB). - [Create upload session](#create-upload-session) - [Create upload session for existing file](#create-upload-session-for-existing-file) - [Get upload session by URL](#get-upload-session-by-url) - [Get upload session](#get-upload-session) - [Upload part of file by URL](#upload-part-of-file-by-url) - [Upload part of file](#upload-part-of-file) - [Remove upload session by URL](#remove-upload-session-by-url) - [Remove upload session](#remove-upload-session) - [List parts by URL](#list-parts-by-url) - [List parts](#list-parts) - [Commit upload session by URL](#commit-upload-session-by-url) - [Commit upload session](#commit-upload-session) - [Upload big file](#upload-big-file) ## Create upload session Creates an upload session for a new file. This operation is performed by calling function `createFileUploadSession`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-files-upload-sessions/). ``` await client.chunkedUploads.createFileUploadSession({ fileName: fileName, fileSize: fileSize, folderId: parentFolderId, } satisfies CreateFileUploadSessionRequestBody); ``` ### Arguments requestBody `CreateFileUploadSessionRequestBody` - Request body of createFileUploadSession method optionalsInput `CreateFileUploadSessionOptionalsInput` ### Returns This function returns a value of type `UploadSession`. Returns a new upload session. ## Create upload session for existing file Creates an upload session for an existing file. This operation is performed by calling function `createFileUploadSessionForExistingFile`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-files-id-upload-sessions/). *Currently we don't have an example for calling `createFileUploadSessionForExistingFile` in integration tests* ### Arguments fileId `string` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" requestBody `CreateFileUploadSessionForExistingFileRequestBody` - Request body of createFileUploadSessionForExistingFile method optionalsInput `CreateFileUploadSessionForExistingFileOptionalsInput` ### Returns This function returns a value of type `UploadSession`. Returns a new upload session. ## Get upload session by URL Return information about an upload session. The actual endpoint URL is returned by the [`Create upload session`](e://post-files-upload-sessions) endpoint. This operation is performed by calling function `getFileUploadSessionByUrl`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-files-upload-sessions-id/). ``` await client.chunkedUploads.getFileUploadSessionByUrl(statusUrl); ``` ### Arguments url `string` - URL of getFileUploadSessionById method optionalsInput `GetFileUploadSessionByUrlOptionalsInput` ### Returns This function returns a value of type `UploadSession`. Returns an upload session object. ## Get upload session Return information about an upload session. The actual endpoint URL is returned by the [`Create upload session`](e://post-files-upload-sessions) endpoint. This operation is performed by calling function `getFileUploadSessionById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-files-upload-sessions-id/). ``` await client.chunkedUploads.getFileUploadSessionById(uploadSessionId); ``` ### Arguments uploadSessionId `string` - The ID of the upload session. Example: "D5E3F7A" optionalsInput `GetFileUploadSessionByIdOptionalsInput` ### Returns This function returns a value of type `UploadSession`. Returns an upload session object. ## Upload part of file by URL Uploads a chunk of a file for an upload session. The actual endpoint URL is returned by the [`Create upload session`](e://post-files-upload-sessions) and [`Get upload session`](e://get-files-upload-sessions-id) endpoints. This operation is performed by calling function `uploadFilePartByUrl`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-files-upload-sessions-id/). ``` await client.chunkedUploads.uploadFilePartByUrl( acc.uploadPartUrl, generateByteStreamFromBuffer(chunkBuffer), { digest: digest, contentRange: contentRange, } satisfies UploadFilePartByUrlHeadersInput, ); ``` ### Arguments url `string` - URL of uploadFilePart method requestBody `ByteStream` - Request body of uploadFilePart method headersInput `UploadFilePartByUrlHeadersInput` - Headers of uploadFilePart method optionalsInput `UploadFilePartByUrlOptionalsInput` ### Returns This function returns a value of type `UploadedPart`. Chunk has been uploaded successfully. ## Upload part of file Uploads a chunk of a file for an upload session. The actual endpoint URL is returned by the [`Create upload session`](e://post-files-upload-sessions) and [`Get upload session`](e://get-files-upload-sessions-id) endpoints. This operation is performed by calling function `uploadFilePart`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-files-upload-sessions-id/). ``` await client.chunkedUploads.uploadFilePart( acc.uploadSessionId, generateByteStreamFromBuffer(chunkBuffer), { digest: digest, contentRange: contentRange, } satisfies UploadFilePartHeadersInput, ); ``` ### Arguments uploadSessionId `string` - The ID of the upload session. Example: "D5E3F7A" requestBody `ByteStream` - Request body of uploadFilePart method headersInput `UploadFilePartHeadersInput` - Headers of uploadFilePart method optionalsInput `UploadFilePartOptionalsInput` ### Returns This function returns a value of type `UploadedPart`. Chunk has been uploaded successfully. ## Remove upload session by URL Abort an upload session and discard all data uploaded. This cannot be reversed. The actual endpoint URL is returned by the [`Create upload session`](e://post-files-upload-sessions) and [`Get upload session`](e://get-files-upload-sessions-id) endpoints. This operation is performed by calling function `deleteFileUploadSessionByUrl`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-files-upload-sessions-id/). ``` await client.chunkedUploads.deleteFileUploadSessionByUrl(abortUrl); ``` ### Arguments url `string` - URL of deleteFileUploadSessionById method optionalsInput `DeleteFileUploadSessionByUrlOptionalsInput` ### Returns This function returns a value of type `undefined`. A blank response is returned if the session was successfully aborted. ## Remove upload session Abort an upload session and discard all data uploaded. This cannot be reversed. The actual endpoint URL is returned by the [`Create upload session`](e://post-files-upload-sessions) and [`Get upload session`](e://get-files-upload-sessions-id) endpoints. This operation is performed by calling function `deleteFileUploadSessionById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-files-upload-sessions-id/). ``` await client.chunkedUploads.deleteFileUploadSessionById(uploadSessionId); ``` ### Arguments uploadSessionId `string` - The ID of the upload session. Example: "D5E3F7A" optionalsInput `DeleteFileUploadSessionByIdOptionalsInput` ### Returns This function returns a value of type `undefined`. A blank response is returned if the session was successfully aborted. ## List parts by URL Return a list of the chunks uploaded to the upload session so far. The actual endpoint URL is returned by the [`Create upload session`](e://post-files-upload-sessions) and [`Get upload session`](e://get-files-upload-sessions-id) endpoints. This operation is performed by calling function `getFileUploadSessionPartsByUrl`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-files-upload-sessions-id-parts/). ``` await client.chunkedUploads.getFileUploadSessionPartsByUrl(listPartsUrl); ``` ### Arguments url `string` - URL of getFileUploadSessionParts method optionalsInput `GetFileUploadSessionPartsByUrlOptionalsInput` ### Returns This function returns a value of type `UploadParts`. Returns a list of parts that have been uploaded. ## List parts Return a list of the chunks uploaded to the upload session so far. The actual endpoint URL is returned by the [`Create upload session`](e://post-files-upload-sessions) and [`Get upload session`](e://get-files-upload-sessions-id) endpoints. This operation is performed by calling function `getFileUploadSessionParts`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-files-upload-sessions-id-parts/). ``` await client.chunkedUploads.getFileUploadSessionParts(uploadSessionId); ``` ### Arguments uploadSessionId `string` - The ID of the upload session. Example: "D5E3F7A" optionalsInput `GetFileUploadSessionPartsOptionalsInput` ### Returns This function returns a value of type `UploadParts`. Returns a list of parts that have been uploaded. ## Commit upload session by URL Close an upload session and create a file from the uploaded chunks. The actual endpoint URL is returned by the [`Create upload session`](e://post-files-upload-sessions) and [`Get upload session`](e://get-files-upload-sessions-id) endpoints. This operation is performed by calling function `createFileUploadSessionCommitByUrl`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-files-upload-sessions-id-commit/). ``` await client.chunkedUploads.createFileUploadSessionCommitByUrl( commitUrl, { parts: parts } satisfies CreateFileUploadSessionCommitByUrlRequestBody, { digest: digest } satisfies CreateFileUploadSessionCommitByUrlHeadersInput, ); ``` ### Arguments url `string` - URL of createFileUploadSessionCommit method requestBody `CreateFileUploadSessionCommitByUrlRequestBody` - Request body of createFileUploadSessionCommit method headersInput `CreateFileUploadSessionCommitByUrlHeadersInput` - Headers of createFileUploadSessionCommit method optionalsInput `CreateFileUploadSessionCommitByUrlOptionalsInput` ### Returns This function returns a value of type `undefined | Files`. Returns the file object in a list.Returns when all chunks have been uploaded but not yet processed. Inspect the upload session to get more information about the progress of processing the chunks, then retry committing the file when all chunks have processed. ## Commit upload session Close an upload session and create a file from the uploaded chunks. The actual endpoint URL is returned by the [`Create upload session`](e://post-files-upload-sessions) and [`Get upload session`](e://get-files-upload-sessions-id) endpoints. This operation is performed by calling function `createFileUploadSessionCommit`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-files-upload-sessions-id-commit/). ``` await client.chunkedUploads.createFileUploadSessionCommit( uploadSessionId, { parts: parts } satisfies CreateFileUploadSessionCommitRequestBody, { digest: digest } satisfies CreateFileUploadSessionCommitHeadersInput, ); ``` ### Arguments uploadSessionId `string` - The ID of the upload session. Example: "D5E3F7A" requestBody `CreateFileUploadSessionCommitRequestBody` - Request body of createFileUploadSessionCommit method headersInput `CreateFileUploadSessionCommitHeadersInput` - Headers of createFileUploadSessionCommit method optionalsInput `CreateFileUploadSessionCommitOptionalsInput` ### Returns This function returns a value of type `undefined | Files`. Returns the file object in a list.Returns when all chunks have been uploaded but not yet processed. Inspect the upload session to get more information about the progress of processing the chunks, then retry committing the file when all chunks have processed. ## Upload big file Starts the process of chunk uploading a big file. Should return a File object representing uploaded file. This operation is performed by calling function `uploadBigFile`. ``` await client.chunkedUploads.uploadBigFile( fileByteStream, fileName, fileSize, parentFolderId, ); ``` ### Arguments file `ByteStream` - The stream of the file to upload. fileName `string` - The name of the file, which will be used for storage in Box. fileSize `number` - The total size of the file for the chunked upload in bytes. parentFolderId `string` - The ID of the folder where the file should be uploaded. cancellationToken `undefined | CancellationToken` - Token used for request cancellation. ### Returns This function returns a value of type `FileFull`. --- ### ChunkedUploadsManager **Type:** page | **Section:** Additional Resources ChunkedUploadsManager This is a manager for chunked uploads (allowed for files at least 20MB). Create upload session Create upload session… # ChunkedUploadsManager This is a manager for chunked uploads (allowed for files at least 20MB). - [Create upload session](#create-upload-session) - [Create upload session for existing file](#create-upload-session-for-existing-file) - [Get upload session by URL](#get-upload-session-by-url) - [Get upload session](#get-upload-session) - [Upload part of file by URL](#upload-part-of-file-by-url) - [Upload part of file](#upload-part-of-file) - [Remove upload session by URL](#remove-upload-session-by-url) - [Remove upload session](#remove-upload-session) - [List parts by URL](#list-parts-by-url) - [List parts](#list-parts) - [Commit upload session by URL](#commit-upload-session-by-url) - [Commit upload session](#commit-upload-session) - [Upload big file](#upload-big-file) ## Create upload session Creates an upload session for a new file. This operation is performed by calling function `create_file_upload_session`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-files-upload-sessions/). ``` client.chunked_uploads.create_file_upload_session( parent_folder_id, file_size, file_name ) ``` ### Arguments folder_id `str` - The ID of the folder to upload the new file to. file_size `int` - The total number of bytes of the file to be uploaded. file_name `str` - The name of new file. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `UploadSession`. Returns a new upload session. ## Create upload session for existing file Creates an upload session for an existing file. This operation is performed by calling function `create_file_upload_session_for_existing_file`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-files-id-upload-sessions/). *Currently we don't have an example for calling `create_file_upload_session_for_existing_file` in integration tests* ### Arguments file_id `str` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" file_size `int` - The total number of bytes of the file to be uploaded. file_name `Optional[str]` - The optional new name of new file. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `UploadSession`. Returns a new upload session. ## Get upload session by URL Return information about an upload session. The actual endpoint URL is returned by the [`Create upload session`](e://post-files-upload-sessions) endpoint. This operation is performed by calling function `get_file_upload_session_by_url`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-files-upload-sessions-id/). ``` client.chunked_uploads.get_file_upload_session_by_url(status_url) ``` ### Arguments url `str` - URL of getFileUploadSessionById method extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `UploadSession`. Returns an upload session object. ## Get upload session Return information about an upload session. The actual endpoint URL is returned by the [`Create upload session`](e://post-files-upload-sessions) endpoint. This operation is performed by calling function `get_file_upload_session_by_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-files-upload-sessions-id/). ``` client.chunked_uploads.get_file_upload_session_by_id(upload_session_id) ``` ### Arguments upload_session_id `str` - The ID of the upload session. Example: "D5E3F7A" extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `UploadSession`. Returns an upload session object. ## Upload part of file by URL Uploads a chunk of a file for an upload session. The actual endpoint URL is returned by the [`Create upload session`](e://post-files-upload-sessions) and [`Get upload session`](e://get-files-upload-sessions-id) endpoints. This operation is performed by calling function `upload_file_part_by_url`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-files-upload-sessions-id/). ``` client.chunked_uploads.upload_file_part_by_url( acc.upload_part_url, generate_byte_stream_from_buffer(chunk_buffer), digest, content_range, ) ``` ### Arguments url `str` - URL of uploadFilePart method request_body `ByteStream` - Request body of uploadFilePart method digest `str` - The [RFC3230][1] message digest of the chunk uploaded. Only SHA1 is supported. The SHA1 digest must be base64 encoded. The format of this header is as `sha=BASE64_ENCODED_DIGEST`. To get the value for the `SHA` digest, use the openSSL command to encode the file part: `openssl sha1 -binary <FILE_PART_NAME> | base64`. [1]: [https://tools.ietf.org/html/rfc3230](https://tools.ietf.org/html/rfc3230) content_range `str` - The byte range of the chunk. Must not overlap with the range of a part already uploaded this session. Each part’s size must be exactly equal in size to the part size specified in the upload session that you created. One exception is the last part of the file, as this can be smaller. When providing the value for `content-range`, remember that: _ The lower bound of each part's byte range must be a multiple of the part size. _ The higher bound must be a multiple of the part size - 1. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `UploadedPart`. Chunk has been uploaded successfully. ## Upload part of file Uploads a chunk of a file for an upload session. The actual endpoint URL is returned by the [`Create upload session`](e://post-files-upload-sessions) and [`Get upload session`](e://get-files-upload-sessions-id) endpoints. This operation is performed by calling function `upload_file_part`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-files-upload-sessions-id/). ``` client.chunked_uploads.upload_file_part( acc.upload_session_id, generate_byte_stream_from_buffer(chunk_buffer), digest, content_range, ) ``` ### Arguments upload_session_id `str` - The ID of the upload session. Example: "D5E3F7A" request_body `ByteStream` - Request body of uploadFilePart method digest `str` - The [RFC3230][1] message digest of the chunk uploaded. Only SHA1 is supported. The SHA1 digest must be base64 encoded. The format of this header is as `sha=BASE64_ENCODED_DIGEST`. To get the value for the `SHA` digest, use the openSSL command to encode the file part: `openssl sha1 -binary <FILE_PART_NAME> | base64`. [1]: [https://tools.ietf.org/html/rfc3230](https://tools.ietf.org/html/rfc3230) content_range `str` - The byte range of the chunk. Must not overlap with the range of a part already uploaded this session. Each part’s size must be exactly equal in size to the part size specified in the upload session that you created. One exception is the last part of the file, as this can be smaller. When providing the value for `content-range`, remember that: _ The lower bound of each part's byte range must be a multiple of the part size. _ The higher bound must be a multiple of the part size - 1. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `UploadedPart`. Chunk has been uploaded successfully. ## Remove upload session by URL Abort an upload session and discard all data uploaded. This cannot be reversed. The actual endpoint URL is returned by the [`Create upload session`](e://post-files-upload-sessions) and [`Get upload session`](e://get-files-upload-sessions-id) endpoints. This operation is performed by calling function `delete_file_upload_session_by_url`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-files-upload-sessions-id/). ``` client.chunked_uploads.delete_file_upload_session_by_url(abort_url) ``` ### Arguments url `str` - URL of deleteFileUploadSessionById method extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `None`. A blank response is returned if the session was successfully aborted. ## Remove upload session Abort an upload session and discard all data uploaded. This cannot be reversed. The actual endpoint URL is returned by the [`Create upload session`](e://post-files-upload-sessions) and [`Get upload session`](e://get-files-upload-sessions-id) endpoints. This operation is performed by calling function `delete_file_upload_session_by_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-files-upload-sessions-id/). ``` client.chunked_uploads.delete_file_upload_session_by_id(upload_session_id) ``` ### Arguments upload_session_id `str` - The ID of the upload session. Example: "D5E3F7A" extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `None`. A blank response is returned if the session was successfully aborted. ## List parts by URL Return a list of the chunks uploaded to the upload session so far. The actual endpoint URL is returned by the [`Create upload session`](e://post-files-upload-sessions) and [`Get upload session`](e://get-files-upload-sessions-id) endpoints. This operation is performed by calling function `get_file_upload_session_parts_by_url`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-files-upload-sessions-id-parts/). ``` client.chunked_uploads.get_file_upload_session_parts_by_url(list_parts_url) ``` ### Arguments url `str` - URL of getFileUploadSessionParts method offset `Optional[int]` - The offset of the item at which to begin the response. Queries with offset parameter value exceeding 10000 will be rejected with a 400 response. limit `Optional[int]` - The maximum number of items to return per page. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `UploadParts`. Returns a list of parts that have been uploaded. ## List parts Return a list of the chunks uploaded to the upload session so far. The actual endpoint URL is returned by the [`Create upload session`](e://post-files-upload-sessions) and [`Get upload session`](e://get-files-upload-sessions-id) endpoints. This operation is performed by calling function `get_file_upload_session_parts`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-files-upload-sessions-id-parts/). ``` client.chunked_uploads.get_file_upload_session_parts(upload_session_id) ``` ### Arguments upload_session_id `str` - The ID of the upload session. Example: "D5E3F7A" offset `Optional[int]` - The offset of the item at which to begin the response. Queries with offset parameter value exceeding 10000 will be rejected with a 400 response. limit `Optional[int]` - The maximum number of items to return per page. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `UploadParts`. Returns a list of parts that have been uploaded. ## Commit upload session by URL Close an upload session and create a file from the uploaded chunks. The actual endpoint URL is returned by the [`Create upload session`](e://post-files-upload-sessions) and [`Get upload session`](e://get-files-upload-sessions-id) endpoints. This operation is performed by calling function `create_file_upload_session_commit_by_url`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-files-upload-sessions-id-commit/). ``` client.chunked_uploads.create_file_upload_session_commit_by_url( commit_url, parts, digest ) ``` ### Arguments url `str` - URL of createFileUploadSessionCommit method parts `List[UploadPart]` - The list details for the uploaded parts. digest `str` - The [RFC3230][1] message digest of the whole file. Only SHA1 is supported. The SHA1 digest must be Base64 encoded. The format of this header is as `sha=BASE64_ENCODED_DIGEST`. [1]: [https://tools.ietf.org/html/rfc3230](https://tools.ietf.org/html/rfc3230) if_match `Optional[str]` - Ensures this item hasn't recently changed before making changes. Pass in the item's last observed `etag` value into this header and the endpoint will fail with a `412 Precondition Failed` if it has changed since. if_none_match `Optional[str]` - Ensures an item is only returned if it has changed. Pass in the item's last observed `etag` value into this header and the endpoint will fail with a `304 Not Modified` if the item has not changed since. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `Optional[Files]`. Returns the file object in a list.Returns when all chunks have been uploaded but not yet processed. Inspect the upload session to get more information about the progress of processing the chunks, then retry committing the file when all chunks have processed. ## Commit upload session Close an upload session and create a file from the uploaded chunks. The actual endpoint URL is returned by the [`Create upload session`](e://post-files-upload-sessions) and [`Get upload session`](e://get-files-upload-sessions-id) endpoints. This operation is performed by calling function `create_file_upload_session_commit`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-files-upload-sessions-id-commit/). ``` client.chunked_uploads.create_file_upload_session_commit( upload_session_id, parts, digest ) ``` ### Arguments upload_session_id `str` - The ID of the upload session. Example: "D5E3F7A" parts `List[UploadPart]` - The list details for the uploaded parts. digest `str` - The [RFC3230][1] message digest of the whole file. Only SHA1 is supported. The SHA1 digest must be Base64 encoded. The format of this header is as `sha=BASE64_ENCODED_DIGEST`. [1]: [https://tools.ietf.org/html/rfc3230](https://tools.ietf.org/html/rfc3230) if_match `Optional[str]` - Ensures this item hasn't recently changed before making changes. Pass in the item's last observed `etag` value into this header and the endpoint will fail with a `412 Precondition Failed` if it has changed since. if_none_match `Optional[str]` - Ensures an item is only returned if it has changed. Pass in the item's last observed `etag` value into this header and the endpoint will fail with a `304 Not Modified` if the item has not changed since. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `Optional[Files]`. Returns the file object in a list.Returns when all chunks have been uploaded but not yet processed. Inspect the upload session to get more information about the progress of processing the chunks, then retry committing the file when all chunks have processed. ## Upload big file Starts the process of chunk uploading a big file. Should return a File object representing uploaded file. This operation is performed by calling function `upload_big_file`. ``` client.chunked_uploads.upload_big_file( file_byte_stream, file_name, file_size, parent_folder_id ) ``` ### Arguments file `ByteStream` - The stream of the file to upload. file_name `str` - The name of the file, which will be used for storage in Box. file_size `int` - The total size of the file for the chunked upload in bytes. parent_folder_id `str` - The ID of the folder where the file should be uploaded. ### Returns This function returns a value of type `FileFull`. --- ### Classifications **Type:** page | **Section:** Additional Resources Classifications Classfications are a type of metadata that allows users and applications to define and assign a content classification to… # Classifications Classfications are a type of metadata that allows users and applications to define and assign a content classification to files and folders. Classifications use the metadata APIs to add and remove classifications, and assign them to files. For more details on metadata templates please see the [metadata documentation](https://ja.developer.box.com/11257628e7a6027222a06363c4d3b2a2/metadata.md). [Classifications](#classifications) - [Add initial classifications](#add-initial-classifications) - [List all classifications](#list-all-classifications) - [Add another classification](#add-another-classification) - [Update a classification](#update-a-classification) - [Delete a classification](#delete-a-classification) - [Delete all classifications](#delete-all-classifications) - [Add classification to file](#add-classification-to-file) - [Update classification on file](#update-classification-on-file) - [Get classification on file](#get-classification-on-file) - [Remove classification from file](#remove-classification-from-file) - [Add classification to folder](#add-classification-to-folder) - [Update classification on folder](#update-classification-on-folder) - [Get classification on folder](#get-classification-on-folder) - [Remove classification from folder](#remove-classification-from-folder) ## Add initial classifications If an enterprise does not already have a classification defined, the first classification(s) can be added with the [`metadata.createTemplate(templateName, fields, options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Metadata.html#createTemplate) method. ``` client.metadata.createTemplate( 'Classification', [ { type: "enum", key: "Box__Security__Classification__Key", displayName: "Classification", hidden: false, options: [ { key: "Classified", staticConfig: { classification: { colorID: 7, classificationDefinition: "Top Seret" } } } ] } ], { hidden: false, templateKey: 'securityClassification-6VMVochwUWo' } ) .then(template => { // the new classification template }); ``` ## List all classifications To retrieve a list of all the classifications in an enterprise call the [`metadata.getTemplateSchema(scope, template, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Metadata.html#getTemplateSchema) method to get the classifciations template, which will contain a list of all the classifications ``` client.metadata.getTemplateSchema('enterprise', 'securityClassification-6VMVochwUWo') .then(template => { // the classification template }); ``` ## Add another classification To add another classification, call the [`metadata.updateTemplate(scope, template, operations, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Metadata.html#updateTemplate) method with the an operation to add a new classification to the template. ``` var operations = [{ op: "addEnumOption", fieldKey: "Box__Security__Classification__Key", data: { key: "Sensitive", classification: { classificationDefinition: "Sensitive information that must not be shared.", colorID: 4 } } }]; client.metadata.updateTemplate('enterprise', 'securityClassification-6VMVochwUWo', operations) .then(template => { // the updated classification template }); ``` ## Update a classification To update an existing classification, call the [`metadata.updateTemplate(scope, template, operations, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Metadata.html#updateTemplate) method with the an operation to update the existing classification already present on the template. ``` var operations = [{ op: "editEnumOption", fieldKey: "Box__Security__Classification__Key", enumOptionKey: "Sensitive", data: { key: "Very Sensitive", classification: { classificationDefinition: "Sensitive information that must not be shared.", colorID: 4 } } }]; client.metadata.updateTemplate('enterprise', 'securityClassification-6VMVochwUWo', operations) .then(template => { // the updated classification template }); ``` ## Add classification to file To add a classification to a file, call [`files.setMetadata(fileID, scope, template, classification, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Files.html#setMetadata) with the name of the classification template, as well as the details of the classification to add to the file. ``` var classification = { Box__Security__Classification__Key: "Sensitive" }; client.files.addMetadata('11111', 'enterprise', 'securityClassification-6VMVochwUWo', classification) .then(metadata => { // the classification applied to the file }); ``` ## Update classification on file To update a classification on a file, call [`files.setMetadata(fileID, scope, template, classification, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Files.html#updateMetadata) with the name of the classification template, as well as the details of the classification to add to the file. ``` var classification = { Box__Security__Classification__Key: "Sensitive" }; client.files.addMetadata('11111', 'enterprise', 'securityClassification-6VMVochwUWo', classification) .then(metadata => { // the updated classification applied to the file }); ``` ## Get classification on file Retrieve the classification on a file by calling [`files.getMetadata(fileID, scope, template, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Files.html#getMetadata) with the ID of the file. ``` client.files.getMetadata('11111', 'enterprise', 'securityClassification-6VMVochwUWo') .then(metadata => { // the metadata instance, which includes the applied metadata }); ``` ## Remove classification from file A classification can be removed from a file by calling [`files.deleteMetadata(fileID, scope, template, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Files.html#deleteMetadata). ``` client.files.deleteMetadata('11111', 'enterprise', 'securityClassification-6VMVochwUWo') .then(() => { // removal succeeded — no value returned });; ``` ## Add classification to folder To add a classification to a folder, call [`folders.setMetadata(folderID, scope, template, classification, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Files.html#setMetadata) with the name of the classification template, as well as the details of the classification to add to the folder. ``` var classification = { Box__Security__Classification__Key: "Sensitive" }; client.folders.addMetadata('11111', 'enterprise', 'securityClassification-6VMVochwUWo', classification) .then(metadata => { // the classification applied to the folder }); ``` ## Update classification on folder To update a classification on a folder, call [`folders.setMetadata(folderID, scope, template, classification, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Files.html#updateMetadata) with the name of the classification template, as well as the details of the classification to add to the folder. ``` var classification = { Box__Security__Classification__Key: "Sensitive" }; client.folders.addMetadata('11111', 'enterprise', 'securityClassification-6VMVochwUWo', classification) .then(metadata => { // the updated classification applied to the folder }); ``` ## Get classification on folder Retrieve the classification on a folder by calling [`folders.getMetadata(folderID, scope, template, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Folders.html#getMetadata) with the ID of the folder. ``` client.folders.getMetadata('11111', 'enterprise', 'securityClassification-6VMVochwUWo') .then(metadata => { // the metadata instance, which includes the applied metadata }); ``` ## Remove classification from folder A classification can be removed from a folder by calling [`folders.deleteMetadata(folderID, scope, template, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Folders.html#deleteMetadata). ``` client.folders.deleteMetadata('11111', 'enterprise', 'securityClassification-6VMVochwUWo') .then(() => { // removal succeeded — no value returned });; ``` --- ### Classifications **Type:** page | **Section:** Additional Resources Classifications Classfications are a type of metadata that allows users and applications to define and assign a content classification to… # Classifications Classfications are a type of metadata that allows users and applications to define and assign a content classification to files and folders. Classifications use the metadata APIs to add and remove classifications, and assign them to files. For more details on metadata templates please see the [metadata documentation](./metadata.md). [Classifications](#classifications) - [Add initial classifications](#add-initial-classifications) - [List all classifications](#list-all-classifications) - [Add another classification](#add-another-classification) - [Update a classification](#update-a-classification) - [Delete a classification](#delete-a-classification) - [Delete all classifications](#delete-all-classifications) - [Add classification to file](#add-classification-to-file) - [Update classification on file](#update-classification-on-file) - [Get classification on file](#get-classification-on-file) - [Remove classification from file](#remove-classification-from-file) - [Add classification to folder](#add-classification-to-folder) - [Update classification on folder](#update-classification-on-folder) - [Get classification on folder](#get-classification-on-folder) - [Remove classification from folder](#remove-classification-from-folder) ## Add initial classifications If an enterprise does not already have a classification defined, the first classification(s) can be added with the [`createMetadataTemplate`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/MetadataTemplate.html#createMetadataTemplate-com.box.sdk.BoxAPIConnection-java.lang.String-java.lang.String-java.lang.String-boolean-java.util.List-) method. ``` MetadataTemplate.Field classification = new MetadataTemplate.Field(); classification.setType("enum"); classification.setKey(Metadata.CLASSIFICATION_KEY); classification.setDisplayName("Classification"); classification.setHidden("false"); List<String> options = new ArrayList<String>(); options.add("Top Secret"); classification.setOptions(topSecret) List<MetadataTemplate.Field> fields = new ArrayList<MetadataTemplate.Field>(); fields.add(classification); MetadataTemplate template = MetadataTemplate.createMetadataTemplate(api, Metadata.ENTERPRISE_METADATA_SCOPE, Metadata.CLASSIFICATION_TEMPLATE_KEY, "Classification", false, fields); ``` ## List all classifications To retrieve a list of all the classifications in an enterprise call the [`getMetadataTemplate`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/MetadataTemplate.html#getMetadataTemplate-com.box.sdk.BoxAPIConnection-) method to get the classifciations template, which will contain a list of all the classifications ``` MetadataTemplate template = MetadataTemplate.getMetadataTemplate(api, Metadata.CLASSIFICATION_TEMPLATE_KEY); ``` ## Add another classification To add another classification, call the [`updateMetadataTemplate`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/MetadataTemplate.html#updateMetadataTemplate-com.box.sdk.BoxAPIConnection-java.lang.String-java.lang.String-java.util.List-) method with the an operation to add a new classification to the template. ``` List<MetadataTemplate.FieldOperation> updates = new ArrayList<MetadataTemplate.FieldOperation>(); String update = "{\n op: \"addEnumOption\",\n fieldKey: \"Box__Security__Classification__Key\",\n data: {\n key: \"Sensitive\"\n }\n}"; updates.add(new MetadataTemplate.FieldOperation(addCategoryFieldJSON)); MetadataTemplate.updateMetadataTemplate(api, Metadata.ENTERPRISE_METADATA_SCOPE, Metadata.CLASSIFICATION_TEMPLATE_KEY, updates); ``` ## Update a classification To update an existing classification, call the [`updateMetadataTemplate`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/MetadataTemplate.html#updateMetadataTemplate-com.box.sdk.BoxAPIConnection-java.lang.String-java.lang.String-java.util.List-) method with the an operation to update the existing classification already present on the template. ``` List<MetadataTemplate.FieldOperation> updates = new ArrayList<MetadataTemplate.FieldOperation>(); String update = "{\n op: \"editEnumOption\",\n fieldKey: \"Box__Security__Classification__Key\",\n enumOptionKey: \"Sensitive\",\n data: {\n key: \"Very Sensitive\"\n }\n}"; updates.add(new MetadataTemplate.FieldOperation(addCategoryFieldJSON)); MetadataTemplate.updateMetadataTemplate(api, Metadata.ENTERPRISE_METADATA_SCOPE, Metadata.CLASSIFICATION_TEMPLATE_KEY, updates); ``` ## Add classification to file To add a classification to a file, call [`setMetadata(String templateKey, String templateScope, Metadata properties)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFile.html#setMetadata-java.lang.String-java.lang.String-com.box.sdk.Metadata-) with the name of the classification template, as well as the details of the classification to add to the file. ``` BoxFile file = new BoxFile(api, "id"); Metadata metadata = new Metadata() metadata.add(Metadata.CLASSIFICATION_KEY, "Sensitive") file.setMetadata(Metadata.CLASSIFICATION_TEMPLATE_KEY, Metadata.ENTERPRISE_METADATA_SCOPE, metadata); ``` ## Update classification on file To update a classification on a file, call [`setMetadata(String templateKey, String templateScope, Metadata properties)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFile.html#setMetadata-java.lang.String-java.lang.String-com.box.sdk.Metadata-) with the name of the classification template, as well as the details of the classification to add to the file. ``` BoxFile file = new BoxFile(api, "id"); Metadata metadata = new Metadata() metadata.add(Metadata.CLASSIFICATION_KEY, "Sensitive") file.setMetadata(Metadata.CLASSIFICATION_TEMPLATE_KEY, Metadata.ENTERPRISE_METADATA_SCOPE, metadata); ``` ## Get classification on file Retrieve the classification on a file by calling [`getMetadata(String templateKey)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFile.html#getMetadata-java.lang.String-) with the ID of the file. ``` BoxFile file = new BoxFile(api, "id"); Metadata metadata = file.getMetadata(Metadata.CLASSIFICATION_TEMPLATE_KEY); ``` ## Remove classification from file A classification can be removed from a file by calling [`deleteMetadata`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFile.html#deleteMetadata--). ``` BoxFile file = new BoxFile(api, "id"); file.deleteMetadata(Metadata.CLASSIFICATION_TEMPLATE_KEY); ``` ## Add classification to folder To add a classification to a folder, call [`setMetadata(String templateKey, String templateScope, Metadata properties)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFile.html#setMetadata-java.lang.String-java.lang.String-com.box.sdk.Metadata-) with the name of the classification template, as well as the details of the classification to add to the folder. ``` BoxFolder folder = new BoxFolder(api, "id"); Metadata metadata = new Metadata() metadata.add(Metadata.CLASSIFICATION_KEY, "Sensitive") folder.setMetadata(Metadata.CLASSIFICATION_TEMPLATE_KEY, Metadata.ENTERPRISE_METADATA_SCOPE, metadata); ``` ## Update classification on folder To update a classification on a folder, call [`setMetadata(String templateKey, String templateScope, Metadata properties)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFile.html#setMetadata-java.lang.String-java.lang.String-com.box.sdk.Metadata-) with the name of the classification template, as well as the details of the classification to add to the folder. ``` BoxFolder folder = new BoxFolder(api, "id"); Metadata metadata = new Metadata() metadata.add(Metadata.CLASSIFICATION_KEY, "Sensitive") folder.setMetadata(Metadata.CLASSIFICATION_TEMPLATE_KEY, Metadata.ENTERPRISE_METADATA_SCOPE, metadata); ``` ## Get classification on folder Retrieve the classification on a folder by calling [`getMetadata(String templateKey)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFolder.html#getMetadata-java.lang.String-) with the ID of the folder. ``` BoxFolder folder = new BoxFolder(api, "id"); Metadata metadata = folder.getMetadata(Metadata.CLASSIFICATION_TEMPLATE_KEY); ``` ## Remove classification from folder A classification can be removed from a folder by calling [`deleteMetadata`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFolder.html#deleteMetadata--). ``` BoxFolder folder = new BoxFolder(api, "id"); folder.deleteMetadata(Metadata.CLASSIFICATION_TEMPLATE_KEY); ``` --- ### Classifications **Type:** page | **Section:** Additional Resources Classifications Classifications are a type of metadata that allows users and applications to define and assign a content classification to… # Classifications Classifications are a type of metadata that allows users and applications to define and assign a content classification to files and folders. Classifications use the metadata APIs to add and remove classifications, and assign them to files. For more details on metadata templates please see the [metadata documentation](https://ja.developer.box.com/4b82910df764450d235d9ae5068029b3/metadata.md). - [Add initial classifications](#add-initial-classifications) - [List all classifications](#list-all-classifications) - [Add another classification](#add-another-classification) - [Update a classification](#update-a-classification) - [Delete a classification](#delete-a-classification) - [Delete all classifications](#delete-all-classifications) - [Add classification to file](#add-classification-to-file) - [Update classification on file](#update-classification-on-file) - [Get classification on file](#get-classification-on-file) - [Remove classification from file](#remove-classification-from-file) - [Add classification to folder](#add-classification-to-folder) - [Update classification on folder](#update-classification-on-folder) - [Get classification on folder](#get-classification-on-folder) - [Remove classification from folder](#remove-classification-from-folder) ## Add initial classifications If an enterprise does not already have a classification defined, the first classification(s) can be added with the `client.create_metadata_template(display_name, fields, template_key=None, hidden=False, scope='enterprise')`]([https://box-python-sdk.readthedocs.io/en/latest/boxsdk.client.html#boxsdk.client.client.Client.create_metadata_template](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.client.html#boxsdk.client.client.Client.create_metadata_template)) method. ``` from boxsdk.object.metadata_template import MetadataField, MetadataFieldType fields = [ MetadataField(MetadataFieldType.ENUM, 'Classification', key='Box__Security__Classification__Key', options=['Top Secret']) ] template = client.create_metadata_template('Classification', fields, template_key='securityClassification-6VMVochwUWo') ``` ## List all classifications To retrieve a list of all the classifications in an enterprise call the [`client.metadata_template(scope, template_key)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.client.html#boxsdk.client.client.Client.metadata_template) method to get the classifications template, which will contain a list of all the classifications. ``` template = client.metadata_template('enterprise', 'securityClassification-6VMVochwUWo').get() ``` ## Add another classification To add another classification, call the [`template.start_update()`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.metadata_template.MetadataTemplate.start_update) API to start making changes to the template, and then call the [`template.update_info(updates=new_updates)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.metadata_template.MetadataTemplate.update_info) with the changes to apply to the template. ``` template = client.metadata_template('enterprise', 'securityClassification-6VMVochwUWo') new_updates = template.start_update() new_updates.add_enum_option('Box__Security__Classification__Key', 'Sensitive') updated_template = template.update_info(updates=new_updates) ``` ## Update a classification To update a classification, call the [`template.start_update()`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.metadata_template.MetadataTemplate.start_update) API to start making changes to the template, and then call the [`template.update_info(updates=new_updates)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.metadata_template.MetadataTemplate.update_info) with the classification to change on the template. ``` template = client.metadata_template('enterprise', 'securityClassification-6VMVochwUWo') new_updates = template.start_update() new_updates.edit_enum_option('Box__Security__Classification__Key', 'Sensitive', 'Very Sensitive') updated_template = template.update_info(updates=new_updates) ``` ## Add classification to file To add a classification to a file, call [`file.metadata(scope='global', template='properties')`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.item.Item.metadata) with the name of the classification template, as well as the details of the classification to add to the file. ``` classification = { 'Box__Security__Classification__Key': 'Sensitive', } applied_metadata = client.file(file_id='11111').metadata(scope='enterprise', template='securityClassification-6VMVochwUWo').set(classification) ``` ## Update classification on file To update a classification on a file, call [`file.metadata(scope='global', template='properties')`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.item.Item.metadata) with the name of the classification template, as well as the details of the classification to add to the file. ``` classification = { 'Box__Security__Classification__Key': 'Sensitive', } applied_metadata = client.file(file_id='11111').metadata(scope='enterprise', template='securityClassification-6VMVochwUWo').set(classification) ``` ## Get classification on file Retrieve the classification on a file by calling [`file.metadata(scope='global', template='properties').get()`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.metadata.Metadata.get) on a file. ``` metadata = client.file(file_id='11111').metadata(scope='enterprise', template='securityClassification-6VMVochwUWo').get() ``` ## Remove classification from file A classification can be removed from a file by calling [`file.metadata(scope='global', template='properties').delete()`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.metadata.Metadata.delete). ``` client.file(file_id='11111').metadata(scope='securityClassification-6VMVochwUWo', template='myMetadata').delete() ``` ## Add classification to folder To add a classification to a folder, call [`folder.metadata(scope='global', template='properties')`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.item.Item.metadata) with the name of the classification template, as well as the details of the classification to add to the folder. ``` classification = { 'Box__Security__Classification__Key': 'Sensitive', } applied_metadata = client.folder(folder_id='11111').metadata(scope='enterprise', template='securityClassification-6VMVochwUWo').set(classification) ``` ## Update classification on folder To update a classification on a folder, call [`folder.metadata(scope='global', template='properties')`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.item.Item.metadata) with the name of the classification template, as well as the details of the classification to add to the folder. ``` classification = { 'Box__Security__Classification__Key': 'Sensitive', } applied_metadata = client.folder(folder_id='11111').metadata(scope='enterprise', template='securityClassification-6VMVochwUWo').set(classification) ``` ## Get classification on folder Retrieve the classification on a folder by calling [`folder.metadata(scope='global', template='properties').get()`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.metadata.Metadata.get) on a folder. ``` metadata = client.folder(folder_id='11111').metadata(scope='enterprise', template='securityClassification-6VMVochwUWo').get() ``` ## Remove classification from folder A classification can be removed from a folder by calling [`folder.metadata(scope='global', template='properties').delete()`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.metadata.Metadata.delete). ``` client.folder(folder_id='11111').metadata(scope='securityClassification-6VMVochwUWo', template='myMetadata').delete() ``` --- ### Classifications **Type:** page | **Section:** Additional Resources Classifications Classifications are a type of metadata that allows users and applications to define and assign a content classification to… # Classifications Classifications are a type of metadata that allows users and applications to define and assign a content classification to files and folders. Classifications use the metadata APIs to add and remove classifications, and assign them to files. For more details on metadata templates please see the [metadata documentation](https://ja.developer.box.com/98957703715f3b88682a57c875071faf/metadata.md). [Classifications](#classifications) - [Add initial classifications](#add-initial-classifications) - [List all classifications](#list-all-classifications) - [Add another classification](#add-another-classification) - [Update a classification](#update-a-classification) - [Delete a classification](#delete-a-classification) - [Delete all classifications](#delete-all-classifications) - [Add classification to file](#add-classification-to-file) - [Update classification on file](#update-classification-on-file) - [Get classification on file](#get-classification-on-file) - [Remove classification from file](#remove-classification-from-file) - [Add classification to folder](#add-classification-to-folder) - [Update classification on folder](#update-classification-on-folder) - [Get classification on folder](#get-classification-on-folder) - [Remove classification from folder](#remove-classification-from-folder) ## Add initial classifications If an enterprise does not already have a classification defined, the first classification(s) can be added with the `MetadataManager.CreateMetadataTemplate(BoxMetadataTemplate metadataTemplate)` method. ``` var field = new BoxMetadataTemplateField { DisplayName = "Classification", Type = "enum", Key = "Box_Security_Classification_Key", Options = new List<BoxMetadataTemplateFieldOption>() { new BoxMetadataTemplateFieldOption { Key = "Classified" } } }; var metadataTemplate = new BoxMetadataTemplate { DisplayName = "Classification", TemplateKey = "securityClassification-6VMVochwUWo", Scope = "enterprise", Fields = new List<BoxMetadataTemplateField>() { field }, }; var template = await client.MetadataManager.CreateMetadataTemplate(metadataTemplate); ``` ## List all classifications To retrieve a list of all the classifications in an enterprise call the `MetadataManager.GetMetadataTemplate(string scope, string template)` method to get the classifications template, which will contain a list of all the classifications. ``` var template = await client.MetadataManager.GetMetadataTemplate("enterprise", "securityClassification-6VMVochwUWo"); ``` ## Add another classification To add another classification, call the `MetadataManager.UpdateMetadataTemplate(IEnumerable<BoxMetadataTemplateUpdate> metadataTemplateUpdate, string scope, string template)` method with proper parameters. ``` var update = new BoxMetadataTemplateUpdate { Op = MetadataTemplateUpdateOp.addEnumOption, FieldKey = "Box_Security_Classification_Key", Data = new { key = "Sensitive" } }; var template = await client.MetadataManager .UpdateMetadataTemplate(new List<BoxMetadataTemplateUpdate>() { update }, "enterprise", "securityClassification-6VMVochwUWo"); ``` ## Update a classification To update a classification, call the `MetadataManager.UpdateMetadataTemplate(IEnumerable<BoxMetadataTemplateUpdate> metadataTemplateUpdate, string scope, string template)` method with proper parameters. ``` var update = new BoxMetadataTemplateUpdate { Op = MetadataTemplateUpdateOp.editEnumOption, FieldKey = "Box_Security_Classification_Key", EnumOptionKey = "Sensitive", Data = new { key = "Very Sensitive" } }; var template = await client.MetadataManager .UpdateMetadataTemplate(new List<BoxMetadataTemplateUpdate>() { update }, "enterprise", "securityClassification-6VMVochwUWo"); ``` ## Add classification to file To add a classification to a file, call `MetadataManager.SetFileMetadataAsync(string fileId, Dictionary<string, object> metadata, string scope, string template)` with the name of the classification template, as well as the details of the classification to add to the file. ``` var fileId = "0"; var classification = new Dictionary<string, object> { { "Box_Security_Classification_Key", "Sensitive" } }; var classificationData = await client.MetadataManager.SetFileMetadataAsync(fileId, classification, "enterprise", "securityClassification-6VMVochwUWo"); ``` ## Update classification on file To update a classification on a file, call `MetadataManager.UpdateFileMetadataAsync(string fileId, List<BoxMetadataUpdate> updates, string scope, string template)` with the name of the classification template, as well as the details of the classification to add to the file. ``` var fileId = "0"; var update = new BoxMetadataUpdate { Op = MetadataUpdateOp.replace, Path = "/Box_Security_Classification_Key", Value = "Very Sensitive" }; var classificationData = await client.MetadataManager .UpdateFileMetadataAsync(fileId, new List<BoxMetadataUpdate>() { update }, "enterprise", "securityClassification-6VMVochwUWo"); ``` ## Get classification on file Retrieve the classification on a file by calling `MetadataManager.GetFileMetadataAsync(string fileId, string scope, string template)` on a file. ``` var fileId = "0"; var fileMetadata = await client.MetadataManager.GetFileMetadataAsync(fileId, "enterprise", "securityClassification-6VMVochwUWo"); ``` ## Remove classification from file A classification can be removed from a file by calling `MetadataManager.DeleteFileMetadataAsync(string fileId, string scope, string template)`. ``` var fileId = "0"; var fileMetadata = await client.MetadataManager.DeleteFileMetadataAsync(fileId, "enterprise", "securityClassification-6VMVochwUWo"); ``` ## Add classification to folder To add a classification to a folder, call `MetadataManager.SetFolderMetadataAsync(string folderId, Dictionary<string, object> metadata, string scope, string template)` with the name of the classification template, as well as the details of the classification to add to the folder. ``` var folderId = "0"; var classification = new Dictionary<string, object> { { "Box_Security_Classification_Key", "Sensitive" } }; var classificationData = await client.MetadataManager.SetFolderMetadataAsync(folderId, classification, "enterprise", "securityClassification-6VMVochwUWo"); ``` ## Update classification on folder To update a classification on a folder, call `MetadataManager.UpdateFolderMetadataAsync(string folderId, List<BoxMetadataUpdate> updates, string scope, string template)`. with the name of the classification template, as well as the details of the classification to add to the folder. ``` var folderId = "0"; var update = new BoxMetadataUpdate { Op = MetadataUpdateOp.replace, Path = "/Box_Security_Classification_Key", Value = "Very Sensitive" }; var classificationData = await client.MetadataManager .UpdateFolderMetadataAsync(folderId, new List<BoxMetadataUpdate>(){ update }, "enterprise", "securityClassification-6VMVochwUWo"); ``` ## Get classification on folder Retrieve the classification on a folder by calling `MetadataManager.GetFolderMetadataAsync(string folderId, string scope, string template)` on a folder. ``` var folderId = "0"; var folderMetadata = await client.MetadataManager.GetFolderMetadataAsync(folderId, "enterprise", "securityClassification-6VMVochwUWo"); ``` ## Remove classification from folder A classification can be removed from a folder by calling `MetadataManager.DeleteFolderMetadataAsync(string folderId, string scope, string template)`. ``` var folderId = "0"; var folderMetadata = await client.MetadataManager.DeleteFolderMetadataAsync(folderId, "enterprise", "securityClassification-6VMVochwUWo"); ``` --- ### ClassificationsManager **Type:** page | **Section:** Additional Resources ClassificationsManager List all classifications Add classification Update classification Add initial classifications List all… # ClassificationsManager - [List all classifications](#list-all-classifications) - [Add classification](#add-classification) - [Update classification](#update-classification) - [Add initial classifications](#add-initial-classifications) ## List all classifications Retrieves the classification metadata template and lists all the classifications available to this enterprise. This API can also be called by including the enterprise ID in the URL explicitly, for example `/metadata_templates/enterprise_12345/securityClassification-6VMVochwUWo/schema`. This operation is performed by calling function `getClassificationTemplate`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-metadata-templates-enterprise-securityClassification-6VMVochwUWo-schema/). ``` await client.classifications.getClassificationTemplate(); ``` ### Arguments headersInput `GetClassificationTemplateHeadersInput` - Headers of getClassificationTemplate method cancellationToken `undefined | CancellationToken` - Token used for request cancellation. ### Returns This function returns a value of type `ClassificationTemplate`. Returns the `securityClassification` metadata template, which contains a `Box__Security__Classification__Key` field that lists all the classifications available to this enterprise. ## Add classification Adds one or more new classifications to the list of classifications available to the enterprise. This API can also be called by including the enterprise ID in the URL explicitly, for example `/metadata_templates/enterprise_12345/securityClassification-6VMVochwUWo/schema`. This operation is performed by calling function `addClassification`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-metadata-templates-enterprise-securityClassification-6VMVochwUWo-schema--add/). ``` await client.classifications.addClassification([ new AddClassificationRequestBody({ data: { key: getUuid(), staticConfig: { classification: { colorId: 4, classificationDefinition: 'Other description', } satisfies AddClassificationRequestBodyDataStaticConfigClassificationField, } satisfies AddClassificationRequestBodyDataStaticConfigField, } satisfies AddClassificationRequestBodyDataField, }), ]); ``` ### Arguments requestBody `readonly AddClassificationRequestBody[]` - Request body of addClassification method optionalsInput `AddClassificationOptionalsInput` ### Returns This function returns a value of type `ClassificationTemplate`. Returns the updated `securityClassification` metadata template, which contains a `Box__Security__Classification__Key` field that lists all the classifications available to this enterprise. ## Update classification Updates the labels and descriptions of one or more classifications available to the enterprise. This API can also be called by including the enterprise ID in the URL explicitly, for example `/metadata_templates/enterprise_12345/securityClassification-6VMVochwUWo/schema`. This operation is performed by calling function `updateClassification`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-metadata-templates-enterprise-securityClassification-6VMVochwUWo-schema--update/). ``` await client.classifications.updateClassification([ new UpdateClassificationRequestBody({ enumOptionKey: classification.key, data: { key: updatedClassificationName, staticConfig: { classification: { colorId: 2, classificationDefinition: updatedClassificationDescription, } satisfies UpdateClassificationRequestBodyDataStaticConfigClassificationField, } satisfies UpdateClassificationRequestBodyDataStaticConfigField, } satisfies UpdateClassificationRequestBodyDataField, }), ]); ``` ### Arguments requestBody `readonly UpdateClassificationRequestBody[]` - Request body of updateClassification method optionalsInput `UpdateClassificationOptionalsInput` ### Returns This function returns a value of type `ClassificationTemplate`. Returns the updated `securityClassification` metadata template, which contains a `Box__Security__Classification__Key` field that lists all the classifications available to this enterprise. ## Add initial classifications When an enterprise does not yet have any classifications, this API call initializes the classification template with an initial set of classifications. If an enterprise already has a classification, the template will already exist and instead an API call should be made to add additional classifications. This operation is performed by calling function `createClassificationTemplate`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-metadata-templates-schema--classifications/). *Currently we don't have an example for calling `createClassificationTemplate` in integration tests* ### Arguments requestBodyInput `CreateClassificationTemplateRequestBodyInput` - Request body of createClassificationTemplate method optionalsInput `CreateClassificationTemplateOptionalsInput` ### Returns This function returns a value of type `ClassificationTemplate`. Returns a new `securityClassification` metadata template, which contains a `Box__Security__Classification__Key` field that lists all the classifications available to this enterprise. --- ### ClassificationsManager **Type:** page | **Section:** Additional Resources ClassificationsManager List all classifications Add classification Update classification Add initial classifications List all… # ClassificationsManager - [List all classifications](#list-all-classifications) - [Add classification](#add-classification) - [Update classification](#update-classification) - [Add initial classifications](#add-initial-classifications) ## List all classifications Retrieves the classification metadata template and lists all the classifications available to this enterprise. This API can also be called by including the enterprise ID in the URL explicitly, for example `/metadata_templates/enterprise_12345/securityClassification-6VMVochwUWo/schema`. This operation is performed by calling function `get_classification_template`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-metadata-templates-enterprise-securityClassification-6VMVochwUWo-schema/). ``` client.classifications.get_classification_template() ``` ### Arguments extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `ClassificationTemplate`. Returns the `securityClassification` metadata template, which contains a `Box__Security__Classification__Key` field that lists all the classifications available to this enterprise. ## Add classification Adds one or more new classifications to the list of classifications available to the enterprise. This API can also be called by including the enterprise ID in the URL explicitly, for example `/metadata_templates/enterprise_12345/securityClassification-6VMVochwUWo/schema`. This operation is performed by calling function `add_classification`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-metadata-templates-enterprise-securityClassification-6VMVochwUWo-schema--add/). ``` client.classifications.add_classification( [ AddClassificationRequestBody( data=AddClassificationRequestBodyDataField( key=get_uuid(), static_config=AddClassificationRequestBodyDataStaticConfigField( classification=AddClassificationRequestBodyDataStaticConfigClassificationField( color_id=4, classification_definition="Other description" ) ), ) ) ] ) ``` ### Arguments request_body `List[AddClassificationRequestBody]` - Request body of addClassification method extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `ClassificationTemplate`. Returns the updated `securityClassification` metadata template, which contains a `Box__Security__Classification__Key` field that lists all the classifications available to this enterprise. ## Update classification Updates the labels and descriptions of one or more classifications available to the enterprise. This API can also be called by including the enterprise ID in the URL explicitly, for example `/metadata_templates/enterprise_12345/securityClassification-6VMVochwUWo/schema`. This operation is performed by calling function `update_classification`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-metadata-templates-enterprise-securityClassification-6VMVochwUWo-schema--update/). ``` client.classifications.update_classification( [ UpdateClassificationRequestBody( enum_option_key=classification.key, data=UpdateClassificationRequestBodyDataField( key=updated_classification_name, static_config=UpdateClassificationRequestBodyDataStaticConfigField( classification=UpdateClassificationRequestBodyDataStaticConfigClassificationField( color_id=2, classification_definition=updated_classification_description, ) ), ), ) ] ) ``` ### Arguments request_body `List[UpdateClassificationRequestBody]` - Request body of updateClassification method extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `ClassificationTemplate`. Returns the updated `securityClassification` metadata template, which contains a `Box__Security__Classification__Key` field that lists all the classifications available to this enterprise. ## Add initial classifications When an enterprise does not yet have any classifications, this API call initializes the classification template with an initial set of classifications. If an enterprise already has a classification, the template will already exist and instead an API call should be made to add additional classifications. This operation is performed by calling function `create_classification_template`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-metadata-templates-schema--classifications/). *Currently we don't have an example for calling `create_classification_template` in integration tests* ### Arguments scope `CreateClassificationTemplateScope` - The scope in which to create the classifications. This should be `enterprise` or `enterprise_{id}` where `id` is the unique ID of the enterprise. template_key `CreateClassificationTemplateTemplateKey` - Defines the list of metadata templates. display_name `CreateClassificationTemplateDisplayName` - The name of the template as shown in web and mobile interfaces. hidden `Optional[bool]` - Determines if the classification template is hidden or available on web and mobile devices. copy_instance_on_item_copy `Optional[bool]` - Determines if classifications are copied along when the file or folder is copied. fields `List[CreateClassificationTemplateFields]` - The classification template requires exactly one field, which holds all the valid classification values. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `ClassificationTemplate`. Returns a new `securityClassification` metadata template, which contains a `Box__Security__Classification__Key` field that lists all the classifications available to this enterprise. --- ### Client **Type:** page | **Section:** Additional Resources Client The client object is the primary interface for making API calls through the SDK. It automatically manages API access token upkeep… # Client The client object is the primary interface for making API calls through the SDK. It automatically manages API access token upkeep when possible, and has a number of options for altering the way calls are made. The various ways of creating an authenticated client are described in the [Authentication documentation](https://ja.developer.box.com/d428a57bd4889ec8d15c393c4114f1d7/authentication.md). [Custom API Calls](#custom-api-calls) - [GET](#get) - [POST](#post) - [PUT](#put) - [DELETE](#delete) - [OPTIONS](#options) ## Custom API Calls The client allows users to make API calls to any arbitrary API endpoint or URL, in order to provide flexibility for developers who may want to make calls not directly supported by the convenience methods provided by the managers (e.g. `client.folders.get()`). These API calls will be sent with the client's access token and any other client settings, but requires passing in the URL, full request parameters, and handling the full response manually. The URL argument for custom calls can be either an API endpoint path (e.g. `'/files/1234'`) or a full URL (e.g. `'https://api.box.com/2.0/files/1234'`). The `params` object contains [request parameters](https://github.com/request/request#requestoptions-callback) and is often useful for passing query string, request body, or header parameters. The response object that results from the call is an instance of [http.IncomingMessage](https://nodejs.org/api/http.html#http_class_http_incomingmessage). By default the entire response will have already been read and the body will be attached as `response.body`. ### GET To make a GET call, call the [`client.get(url, params, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/BoxClient.html#get) method with the URL of the endpoint and the request params. ``` var params = { qs: { fields: 'name,id' } }; client.get('/files/1234', params, function(err, response) { if (err) { // handle error } console.log(response.body); }); ``` ### POST To make a POST call, call the [`client.post(url, params, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/BoxClient.html#post) method with the URL of the endpoint and the request params. ``` var params = { body: { name: 'My New Folder', parent: { id: '0' } } }; client.post('/folders', params, function(err, response) { if (err) { // handle error } console.log(response.body); }); ``` ### PUT To make a PUT call, call the [`client.put(url, params, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/BoxClient.html#put) method with the URL of the endpoint and the request params. ``` var params = { body: { name: 'Changed Folder Name' } }; client.put('/folders/1234', params, function(err, response) { if (err) { // handle error } console.log(response.body); }); ``` ### DELETE To make a DELETE call, call the [`client.del(url, params, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/BoxClient.html#del) method with the URL of the endpoint and the request params. ``` client.del('/folders/1234', null, function(err, response) { if (err) { // handle error } console.log(response.body); }); ``` ### OPTIONS To make an OPTIONS call, call the [`client.options(url, params, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/BoxClient.html#options) method with the URL of the endpoint and the request params. ``` client.options('/files/content', null, function(err, response) { if (err) { // handle error } console.log(response.body); }); ``` --- ### Client **Type:** page | **Section:** Additional Resources Client This is the central entrypoint for all SDK interaction. The BoxClient houses all the API endpoints divided across resource managers… # Client This is the central entrypoint for all SDK interaction. The BoxClient houses all the API endpoints divided across resource managers. [Make custom HTTP request](#make-custom-http-request) - [JSON request](#json-request) - [Multi-part request](#multi-part-request) - [Binary response](#binary-response) [Additional headers](#additional-headers) - [As-User header](#as-user-header) - [Suppress notifications](#suppress-notifications) - [Custom headers](#custom-headers) [Custom Base URLs](#custom-base-urls) [Custom Agent Options](#custom-agent-options) [Interceptors](#interceptors) [Use Proxy for API calls](#use-proxy-for-api-calls) # Make custom HTTP request You can make custom HTTP requests using the `client.makeRequest()` method. This method allows you to make any HTTP request to the Box API. It will automatically use authentication and network configuration settings from the client. The method accepts a `FetchOptions` object as an argument and returns a `FetchResponse` object. ## JSON request The following example demonstrates how to make a custom POST request to create a new folder in the root folder. ``` const response: FetchResponse = await client.makeRequest( { method: "POST", url: "https://api.box.com/2.0/folders", data: {name: newFolderName, parent: {id: "0"}} } satisfies FetchOptionsInput ); console.log('Received status code: ', response.status) console.log('Created folder name: ', getSdValueByKey(response.content, "name")) ``` ## Multi-part request The following example demonstrates how to make a custom multipart request that uploads a file to a folder. ``` const multipartAttributes = {name: "newFileName", parent: { id: "0" }}; const uploadFileResponse: FetchResponse = await client.makeRequest({ method: "POST", url: "https://upload.box.com/api/2.0/files/content", contentType: "multipart/form-data", multipartData: [{ partName: "attributes", data: multipartAttributes } satisfies MultipartItem, { partName: "file", fileStream: fileContentStream } satisfies MultipartItem] } satisfies FetchOptionsInput); console.log('Received status code: ', response.status) ``` ## Binary response The following example demonstrates how to make a custom request that expects a binary response. It is required to specify the `responseFormat` parameter in the `FetchOptions` object to "binary". ``` const response: FetchResponse = await client.makeRequest({ method: "GET", url: "".concat("https://api.box.com/2.0/files/", uploadedFile.id, "/content") as string, responseFormat: "binary" as ResponseFormat } satisfies FetchOptionsInput); console.log('Received status code: ', response.status) const fileWriteStream = fs.createWriteStream('file.pdf'); response.content.pipe(fileWriteStream); ``` # Additional headers BoxClient provides a convenient methods, which allow passing additional headers, which will be included in every API call made by the client. ## As-User header The As-User header is used by enterprise admins to make API calls on behalf of their enterprise's users. This requires the API request to pass an As-User: USER-ID header. For more details see the [documentation on As-User](https://developer.box.com/en/guides/authentication/oauth2/as-user/). The following example assume that the client has been instantiated with an access token belonging to an admin-level user or Service Account with appropriate privileges to make As-User calls. Calling the `client.withAsUserHeader()` method creates a new client to impersonate user with the provided ID. All calls made with the new client will be made in context of the impersonated user, leaving the original client unmodified. ``` const userClient = client.withAsUserHeader('1234567'); ``` ## Suppress notifications If you are making administrative API calls (that is, your application has “Manage an Enterprise” scope, and the user signing in is a co-admin with the correct "Edit settings for your company" permission) then you can suppress both email and webhook notifications. This can be used, for example, for a virus-scanning tool to download copies of everyone’s files in an enterprise, without every collaborator on the file getting an email. All actions will still appear in users' updates feed and audit logs. **Note:** This functionality is only available for approved applications. Calling the `client.withSuppressedNotifications()` method creates a new client. For all calls made with the new client the notifications will be suppressed. ``` const newClient = client.withSuppressedNotifications(); ``` ## Custom headers You can also specify the custom set of headers, which will be included in every API call made by client. Calling the `client.withExtraHeaders()` method creates a new client, leaving the original client unmodified. ``` const newClient = client.withExtraHeaders({ ['customHeader']: 'customValue' }); ``` # Custom Base URLs You can also specify the custom base URLs, which will be used for API calls made by client. Calling the `client.withCustomBaseUrls()` method creates a new client, leaving the original client unmodified. ``` const newClient = client.withCustomBaseUrls({ baseUrl: 'https://api.box.com', uploadUrl: 'https://upload.box.com/api', oauth2Url: 'https://account.box.com/api/oauth2', }); ``` # Custom Agent Options You can also specify the custom agent options, which will be used for API calls made by client. Calling the `client.withCustomAgentOptions()` method creates a new client, leaving the original client unmodified. ``` const options: AgentOptions = {}; const newClient = client.withCustomAgentOptions(options); ``` # Interceptors You can specify custom interceptors - methods that will be called just before making a request and right after receiving a response from the server. Using these function allows you to modify the request payload and response. Interceptor interface accepts two methods with the following signatures: ``` beforeRequest(options: FetchOptions): FetchOptions; afterRequest(response: FetchResponse): FetchResponse; ``` You can apply more than one interceptor to the client by passing a list of interceptors to apply. Calling the `client.withInterceptors()` method creates a new client, leaving the original client unmodified. ``` function beforeRequest(options: FetchOptions): FetchOptions { return { method: options.method, headers: options.headers, params: { ...options.params, ...{ ['fields']: 'role' } }, data: options.data, fileStream: options.fileStream, multipartData: options.multipartData, contentType: options.contentType, responseFormat: options.responseFormat, auth: options.auth, networkSession: options.networkSession, cancellationToken: options.cancellationToken, }; } function emptyAfterRequest(response: FetchResponse): FetchResponse { return response; } const clientWithInterceptor: BoxClient = client.withInterceptors([ { beforeRequest: beforeRequest, afterRequest: emptyAfterRequest, }, ]); ``` # Use Proxy for API calls In order to use a proxy for API calls, calling the `client.withProxy(proxyConfig)` method creates a new client, leaving the original client unmodified, with the username and password being optional. If both custom agent options and proxy are provided, the proxy will take precedence. **Note:** We are only supporting http/s proxies with basic authentication. NTLM and other authentication methods are not supported. ``` newClient = client.withProxy({ url: 'http://127.0.0.1:1234/', username: 'user', password: 'password', }); ``` --- ### Client **Type:** page | **Section:** Additional Resources Client This is the central entrypoint for all SDK interaction. The BoxClient houses all the API endpoints divided across resource managers… # Client This is the central entrypoint for all SDK interaction. The BoxClient houses all the API endpoints divided across resource managers. [Make custom HTTP request](#make-custom-http-request) - [JSON request](#json-request) - [Multi-part request](#multi-part-request) - [Binary response](#binary-response) [Additional headers](#additional-headers) - [As-User header](#as-user-header) - [Suppress notifications](#suppress-notifications) - [Custom headers](#custom-headers) [Custom Base URLs](#custom-base-urls) [Use Proxy for API calls](#use-proxy-for-api-calls) # Make custom HTTP request You can make custom HTTP requests using the `client.make_request()` method. This method allows you to make any HTTP request to the Box API. It will automatically use authentication and network configuration settings from the client. The method accepts a `FetchOptions` object as an argument and returns a `FetchResponse` object. ## JSON request The following example demonstrates how to make a custom POST request to create a new folder in the root folder. ``` from box_sdk_gen import FetchResponse, FetchOptions response: FetchResponse = client.make_request( FetchOptions( method="POST", url="https://api.box.com/2.0/folders", data={"name": "new_folder_name", "parent": {"id": "0"}}, ) ) print("Received status code: ", response.status) print("Created folder name: ", response.data["name"]) ``` ## Multi-part request The following example demonstrates how to make a custom multipart request that uploads a file to a folder. ``` from box_sdk_gen import FetchResponse, FetchOptions, MultipartItem response: FetchResponse = client.make_request( FetchOptions( method="POST", url="https://upload.box.com/api/2.0/files/content", content_type="multipart/form-data", multipart_data=[ MultipartItem( part_name="attributes", data={"name": "new_folder_name", "parent": {"id": "0"}}, ), MultipartItem(part_name="file", file_stream=open("file.txt", "rb")), ], ) ) print("Received status code: ", response.status) ``` ## Binary response The following example demonstrates how to make a custom request that expects a binary response. It is required to specify the `response_format` parameter in the `FetchOptions` object to `ResponseFormat.BINARY`. ``` from box_sdk_gen import FetchResponse, FetchOptions, ResponseFormat file_id = "1234567" response: FetchResponse = client.make_request( FetchOptions( method="GET", url="".join(["https://api.box.com/2.0/files/", file_id, "/content"]), response_format=ResponseFormat.BINARY, ) ) print("Received status code: ", response.status) with open("file.txt", "wb") as file: file.write(response.content) ``` # Additional headers BoxClient provides a convenient methods, which allow passing additional headers, which will be included in every API call made by the client. ## As-User header The As-User header is used by enterprise admins to make API calls on behalf of their enterprise's users. This requires the API request to pass an As-User: USER-ID header. For more details see the [documentation on As-User](https://developer.box.com/en/guides/authentication/oauth2/as-user/). The following example assume that the client has been instantiated with an access token belonging to an admin-level user or Service Account with appropriate privileges to make As-User calls. Calling the `client.with_as_user_header()` method creates a new client to impersonate user with the provided ID. All calls made with the new client will be made in context of the impersonated user, leaving the original client unmodified. ``` user_client = client.with_as_user_header(user_id="1234567") ``` ## Suppress notifications If you are making administrative API calls (that is, your application has “Manage an Enterprise” scope, and the user signing in is a co-admin with the correct "Edit settings for your company" permission) then you can suppress both email and webhook notifications. This can be used, for example, for a virus-scanning tool to download copies of everyone’s files in an enterprise, without every collaborator on the file getting an email. All actions will still appear in users' updates feed and audit logs. **Note:** This functionality is only available for approved applications. Calling the `client.with_suppressed_notifications()` method creates a new client. For all calls made with the new client the notifications will be suppressed. ``` new_client = client.with_suppressed_notifications() ``` ## Custom headers You can also specify the custom set of headers, which will be included in every API call made by client. Calling the `client.with_extra_headers()` method creates a new client, leaving the original client unmodified. ``` new_client = client.with_extra_headers(extra_headers={"customHeader": "customValue"}) ``` # Custom Base URLs You can also specify the custom base URLs, which will be used for API calls made by client. Calling the `client.with_custom_base_urls()` method creates a new client, leaving the original client unmodified. ``` new_client = client.with_custom_base_urls( base_urls=BaseUrls( base_url="https://api.box.com", upload_url="https://upload.box.com/api", oauth_2_url="https://account.box.com/api/oauth2", ) ) ``` # Use Proxy for API calls In order to use a proxy for API calls, calling the `client.with_proxy(proxyConfig)` method creates a new client, leaving the original client unmodified, with the username and password being optional. **Note:** We are only supporting http/s proxies with basic authentication. NTLM and other authentication methods are not supported. ``` new_client = client.with_proxy( ProxyConfig(url="http://proxy.com", username="username", password="password") ) ``` --- ### Client **Type:** page | **Section:** Additional Resources Client This is the central entrypoint for all SDK interaction. The BoxClient houses all the API endpoints divided across resource managers… # Client This is the central entrypoint for all SDK interaction. The BoxClient houses all the API endpoints divided across resource managers. [Make custom HTTP request](#make-custom-http-request) - [JSON request](#json-request) - [Multi-part request](#multi-part-request) - [Binary response](#binary-response) [Additional headers](#additional-headers) - [As-User header](#as-user-header) - [Suppress notifications](#suppress-notifications) - [Custom headers](#custom-headers) [Custom Base URLs](#custom-base-urls) [Use Proxy for API calls](#use-proxy-for-api-calls) # Make custom HTTP request You can make custom HTTP requests using the `client.MakeRequestAsync()` method. This method allows you to make any HTTP request to the Box API. It will automatically use authentication and network configuration settings from the client. The method accepts a `FetchOptions` object as an argument and returns a `FetchResponse` object. ## JSON request The following example demonstrates how to make a custom POST request to create a new folder in the root folder. ``` string requestBodyPost = "{\"name\": \"newFolderName\", \"parent\": {\"id\": \"0\"}}"; FetchResponse response = await client.MakeRequestAsync(fetchOptions: new FetchOptions(method: "POST", url: "https://api.box.com/2.0/folders") { Data = JsonUtils.JsonToSerializedData(text: requestBodyPost) }); Console.WriteLine("Received status code: " + response.status); Console.WriteLine("Created folder name: " + response.data["name"]); ``` ## Multi-part request The following example demonstrates how to make a custom multipart request that uploads a file to a folder. ``` string multipartAttributes = "{\"name\": \"newFileName\", \"parent\": {\"id\": \"newFolderId\"}}"; FetchResponse response = await client.MakeRequestAsync(fetchOptions: new FetchOptions(method: "POST", url: "https://upload.box.com/api/2.0/files/content", contentType: "multipart/form-data") { FileStream = fileContentStream, MultipartData = Array.AsReadOnly(new [] {new MultipartItem(partName: "attributes") { Data = JsonUtils.JsonToSerializedData(text: multipartAttributes) },new MultipartItem(partName: "file") { FileStream = fileContentStream }}) }); Console.WriteLine("Received status code: " + response.status); ``` ## Binary response The following example demonstrates how to make a custom request that expects a binary response. It is required to specify the `responseFormat` parameter in the `FetchOptions` object to `Box.Sdk.Gen.ResponseFormat.Binary`. ``` string fileId = "123456789"; FetchResponse response = await client.MakeRequestAsync(fetchOptions: new FetchOptions(method: "GET", url: string.Concat("https://api.box.com/2.0/files/", fileId, "/content"), responseFormat: Box.Sdk.Gen.ResponseFormat.Binary)); Console.WriteLine("Received status code: " + response.status); string filePath = "output.txt"; using (FileStream fileStream = new FileStream(filePath, FileMode.Create, FileAccess.Write)) { responseStream.CopyTo(response.content); } ``` # Additional headers BoxClient provides a convenient methods, which allow passing additional headers, which will be included in every API call made by the client. ## As-User header The As-User header is used by enterprise admins to make API calls on behalf of their enterprise's users. This requires the API request to pass an As-User: USER-ID header. For more details see the [documentation on As-User](https://developer.box.com/en/guides/authentication/oauth2/as-user/). The following example assume that the client has been instantiated with an access token belonging to an admin-level user or Service Account with appropriate privileges to make As-User calls. Calling the `client.WithAsUserHeader()` method creates a new client to impersonate user with the provided ID. All calls made with the new client will be made in context of the impersonated user, leaving the original client unmodified. ``` var userClient = client.WithAsUserHeader(useId: "1234567"); ``` ## Suppress notifications If you are making administrative API calls (that is, your application has “Manage an Enterprise” scope, and the user signing in is a co-admin with the correct "Edit settings for your company" permission) then you can suppress both email and webhook notifications. This can be used, for example, for a virus-scanning tool to download copies of everyone’s files in an enterprise, without every collaborator on the file getting an email. All actions will still appear in users' updates feed and audit logs. **Note:** This functionality is only available for approved applications. Calling the `client.WithSuppressedNotifications()` method creates a new client. For all calls made with the new client the notifications will be suppressed. ``` var newClient = client.WithSuppressedNotifications(); ``` ## Custom headers You can also specify the custom set of headers, which will be included in every API call made by client. Calling the `client.WithExtraHeaders()` method creates a new client, leaving the original client unmodified. ``` var extraHeaders = new Dictionary<string, string?>() { { "customHeader", "customValue" } }; var newClient = client.WithExtraHeaders(extraHeaders: extraHeaders); ``` # Custom Base URLs You can also specify the custom base URLs, which will be used for API calls made by client. Calling the `client.WithCustomBaseUrls()` method creates a new client, leaving the original client unmodified. ``` var newClient = client.WithCustomBaseUrls(new BaseUrls( baseUrl: "https://api.box2.com", uploadUrl: "https://upload.box.com/api", oauth2Url: "https://account.box.com/api/oauth2" )); ``` # Use Proxy for API calls In order to use a proxy for API calls, call the `client.WithProxy(proxyConfig)` method that creates a new client with proxy, leaving the original client unmodified. In config, you can specify the username, password and domain for the proxy server. Alternatively you can set 'UseDefaultCredentials' to true to use the credentials of the currently logged on user - `DefaultCredentials`. NOTE: Setting UseDefaultCredentials takes precedence over Username, Password and Domain fields. If UseDefaultCredentials is set to true, the Username, Password and Domain fields will be ignored. ``` var newClient = client.WithProxy(new ProxyConfig("http://proxy.com") { Username = "username", Password = "password", Domain = "example" }); ``` To use proxy with default credentials: ``` var newClient = client.WithProxy(new ProxyConfig("http://proxy.com") { UseDefaultCredentials = true }); ``` --- ### Collaboration Allowlist **Type:** page | **Section:** Additional Resources Collaboration Allowlist The Collaboration Allowlist API allows you to manage a set of approved domains (i.e. a allowlist) that can… # Collaboration Allowlist The Collaboration Allowlist API allows you to manage a set of approved domains (i.e. a allowlist) that can collaborate with your enterprise. You can also manage whether the allowlisted domains are approved for outbound or inbound collaboration. It is important to note that the collaboration allowlist functionality is only available to customers with Box Governance. - [List Collaboration Allowlist Entries](#list-collaboration-allowlist-entries) - [Get Information for Collaboration Allowlist Entry](#get-information-for-collaboration-allowlist-entry) - [Allowlist a Domain for Collaboration](#allowlist-a-domain-for-collaboration) - [Remove a Domain from Allowlist](#remove-a-domain-from-allowlist) - [List Exempt Users](#list-exempt-users) - [Get Exempt User Information](#get-exempt-user-information) - [Exempt User from Allowlist](#exempt-user-from-allowlist) - [Remove User Exemption](#remove-user-exemption) ## List Collaboration Allowlist Entries To retrieve a list of collaboration allowlist entries, call [`collaboration_allowlist.get_entries(limit=None, marker=None, fields=None)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.collaboration_allowlist.CollaborationAllowlist.get_entries). This method returns a `BoxObjectCollection` which can iterate over the [`CollaborationAllowlistEntry`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.collaboration_allowlist_entry.CollaborationAllowlistEntry) objects in the collection. ``` allowlist_entries = client.collaboration_allowlist().get_entries() for entry in allowlist_entries: direction = entry.direction if entry.direction != 'both' else 'bidirectional' print(f'Domain {entry.domain} is allowlisted for {direction} collaboration') ``` ## Get Information for Collaboration Allowlist Entry To get information about a collaboration allowlist entry, use [`collaboration_allowlist_entry.get(*, fields=None, headers=None, **kwargs)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.base_object.BaseObject.get). This method returns a [`CollaborationAllowlistEntry`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.collaboration_allowlist_entry.CollaborationAllowlistEntry) object with fields populated by data form the API. ``` allowlist_entry = client.collaboration_allowlist_entry(entry_id='11111').get() ``` ## Allowlist a Domain for Collaboration To allowlist a domain for collaboration, call [`collaboration_allowlist.add_domain(domain, direction)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.collaboration_allowlist.CollaborationAllowlist.add_domain) with the domain to allowlist and the direction(s) collaboration should be allowed in. This method returns a [`CollaborationAllowlistEntry`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.collaboration_allowlist_entry.CollaborationAllowlistEntry) object representing the newly-allowlisted domain. You can determine the direction of the allowlist by passing in 'outbound', 'inbound', or 'both'. Outbound collaboration is defined as a user in your enterprise collaborating on content owned by someone outside your enterprise. Inbound collaboration is defined as a user outside of your enterprise collaborating on content owned by your enterprise. ``` from boxsdk.object.collaboration_allowlist import AllowlistDirection domain = 'example.com' allowlist_entry = client.collaboration_allowlist().add_domain(domain, direction=AllowlistDirection.INBOUND) ``` ## Remove a Domain from Allowlist To remove a collaboration allowlisted domain, call [`collaboration_allowlist_entry.delete()`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.base_object.BaseObject.delete). This will remove the domain from the allowlist, restricting collaboration to and from users in that domain. This method returns `True` to indicate that deletion was successful. ``` client.collaboration_allowlist_entry(entry_id='11111').delete() ``` ## List Exempt Users To get all exempt users from the collaboration allowlist, call [`collaboration_allowlist.get_exemptions(limit=None, marker=None, fields=None)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.collaboration_allowlist.CollaborationAllowlist.get_exemptions). This method returns a `BoxObjectCollection` that allows you to iterate over each [`CollaborationAllowlistExemptTarget`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.collaboration_allowlist_exempt_target.CollaborationAllowlistExemptTarget) in the collection. ``` exemptions = client.collaboration_allowlist().get_exemptions() for exemption in exemptions: print(f'{exemption.user.name} (ID: {exemption.user.id}) is exempt from the collaboration allowlist') ``` ## Get Exempt User Information To get information about an exempted user, call [`collaboration_allowlist_exempt_target.get(*, fields=None, headers=None, **kwargs)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.base_object.BaseObject.get). This method will return a [`CollaborationAllowlistExemptTarget](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.collaboration_allowlist_exempt_target.CollaborationAllowlistExemptTarget) with fields populated by data from the API. ``` exemption_id = '11111' exemption = client.collaboration_allowlist_exempt_target(exemption_id).get() ``` ## Exempt User from Allowlist To exempt a user from the collaboration allowlist, call [`collaboration_allowlist.add_exemption(user)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.collaboration_allowlist.CollaborationAllowlist.add_exemption) with the [`User`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.user.User) to exempt from the allowlist. This user will no longer be subject to the collaboration allowlist, and will be permitted to collaborate with users from any other domain. This method returns a [`CollaborationAllowlistExemptTarget`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.collaboration_allowlist_exempt_target.CollaborationAllowlistExemptTarget) object representing the exempted user. ``` user = client.user(user_id='11111') exemption = client.collaboration_allowlist().add_exemption(user) ``` ## Remove User Exemption To remove a user exemption from the collaboration allowlist, call [`collaboration_allowlist_exempt_target.delete()`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.base_object.BaseObject.delete). This will remove the exemption and make the user subject to the collaboration allowlist again. This method returns `True` to indicate that deletion was successful. ``` client.collaboration_allowlist_exempt_target(exemption_id='22222').delete() ``` --- ### Collaboration Allowlists **Type:** page | **Section:** Additional Resources Collaboration Allowlists Collaboration Allowlists are used to determine specific email domains that can collaborate with a Box Enterprise… # Collaboration Allowlists Collaboration Allowlists are used to determine specific email domains that can collaborate with a Box Enterprise. Certain users can be exempted from these restrictions, for example if they are a trusted person who needs to collaborate outside of the normally-allowed set of domains. - [Add a Domain to Collaboration Allowlist](#add-a-domain-to-collaboration-allowlist) - [Get a Allowlisted Domain's Information](#get-a-allowlisted-domains-information) - [Get Allowlisted Domains for an Enterprise](#get-allowlisted-domains-for-an-enterprise) - [Remove a Domain from Collaboration Allowlist](#remove-a-domain-from-collaboration-allowlist) - [Exempt a User from the Collaboration Allowlist](#exempt-a-user-from-the-collaboration-allowlist) - [Get an Exempt User's Information](#get-an-exempt-users-information) - [Get the User Collaboration Allowlists for an Enterprise](#get-the-user-collaboration-allowlists-for-an-enterprise) - [Remove a User Exemption from the Collaboration Allowlist](#remove-a-user-exemption-from-the-collaboration-allowlist) ## Add a Domain to Collaboration Allowlist You can allowlist a certain domain to allow collaboration with that domain for your enterprise by calling [`collaborationAllowlist.addDomain(domain, direction, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/CollaborationAllowlist.html#addDomain). The `direction` parameter determines the level of restriction on which way the collaboration flows. Set to `inbound` will allow users outside of our enterprise to collaboration with content inside your enterprise. Set to `outbound` will allow users inside your enterprise to collaboration with content owned by someone outside your enterprise. Set to `both` will allow both `inbound` and `outbound`. ``` client.collaborationAllowlist.addDomain('test.com', client.collaborationAllowlist.directions.INBOUND, callback); ``` ## Get a Allowlisted Domain's Information Information about a specific collaboration allowlist record, which shows the domain that is allowlisted, can be retrieved by calling [`collaborationAllowlist.getAllowlistedDomain(domainID, options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/CollaborationAllowlist.html#getAllowlistedDomain). ``` client.collaborationAllowlist.getAllowlistedDomain('12345', {}, callback); ``` ## Get Allowlisted Domains for an Enterprise You can retrieve a collection of allowlisted domains for an enterprise with [`collaborationAllowlist.getAllAllowlistedDomains(options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/CollaborationAllowlist.html#getAllAllowlistedDomains). ``` client.collaborationAllowlist.getAllAllowlistedDomains(callback); ``` Alternatively you can limit the number of allowlisted domains you wish to retrieve by setting a limit. The default is 100 entries and the maximum is 1,000 entries. ``` var options = { limit: 50; }; client.collaborationAllowlist.getAllAllowlistedDomains(options, callback); ``` ## Remove a Domain from Collaboration Allowlist You can remove a domain from the collaboration allowlist with [`collaborationAllowlist.removeDomain(domainID, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/CollaborationAllowlist.html#removeDomain). ``` client.collaborationAllowlist.removeDomain('12345', callback); ``` ## Exempt a User from the Collaboration Allowlist You can make a specific user exempt from the collaboration allowlist, which allows them to collaborate with users from any domain, by calling [`collaborationAllowlist.addExemption(userID, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Collaborations.html#addExemption). ``` client.collaborationAllowlist.addExemption('5678', callback); ``` ## Get an Exempt User's Information To retrieve information about a specific user exemption record, you can use [`collaborationAllowlist.getExemption(exemptionID, options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/CollaborationAllowlist.html#getExemption). ``` client.collaborationAllowlist.getExemption(`12345`, callback); ``` ## Get All Exempt Users for an Enterprise To retrieve a collection of users who are exempt from the collaboration allowlist for an enterprise, call [`collaborationAllowlist.getAllExemptions(options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/CollaborationAllowlist.html#getAllExemptions). ``` client.collaborationAllowlist.getAllExemptions(options, callback); ``` Alternatively you can limit the number of user collaboration allowlists you wish to retrieve by setting a limit, the default is 100 entries and the maximum is 1000 entries. ``` var options = { limit: 50; }; client.collaborationAllowlist.getAllExemptions(options, callback); ``` ## Remove a User Exemption from the Collaboration Allowlist To remove a user exemption from collaboration allowlist and make that user subject to allowlist restrictions again, you can call [`collaborationAllowlist.removeExemption(exemptionID, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/CollaborationAllowlist.html#removeExemption). ``` client.collaborationAllowlist.removeExemption('12345678', callback); ``` --- ### Collaboration Allowlists **Type:** page | **Section:** Additional Resources Collaboration Allowlists Collaboration Allowlists are used to manage a set of approved domains or Box users that an enterprise can… # Collaboration Allowlists Collaboration Allowlists are used to manage a set of approved domains or Box users that an enterprise can collaborate with. - [Add a Collaboration Allowlist For a Domain](#add-a-collaboration-allowlist-for-a-domain) - [Get a Collaboration Allowlist's Information for a Domain](#get-a-collaboration-allowlists-information-for-a-domain) - [Get all Collaboration Allowlist's Information for Domain](#get-all-collaboration-allowlists-information-for-domain) - [Remove a Collaboration Allowlist for a Domain](#remove-a-collaboration-allowlist-for-a-domain) - [Add a Collaboration Allowlist for a User](#add-a-collaboration-allowlist-for-a-user) - [Get a Collaboration Allowlist's Information for a User](#get-a-collaboration-allowlists-information-for-a-user) - [Get all Collaboration Allowlist's Information for a User](#get-all-collaboration-allowlists-information-for-a-user) - [Remove a Collaboration Allowlist for a User](#remove-a-collaboration-allowlist-for-a-user) ## Add a Collaboration Allowlist For a Domain A collaboration allowlist can be created for a domain with [`create(BoxAPIConnection api, String domain, AllowlistDirection direction)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxCollaborationAllowlist.html#create-com.box.sdk.BoxAPIConnection-java.lang.String-com.box.sdk.BoxCollaborationAllowlist.AllowlistDirection-). The `AllowlistDirection` parameter determines which way the allowlisting applies. You can set the value to inbound, outbound, or both. ``` BoxCollaborationAllowlist.create(api, "test.com", BoxCollaborationAllowlist.AllowlistDirection.BOTH); ``` ## Get a Collaboration Allowlist's Information for a Domain A specific collaboration allowlist for a domain can be retrieved with [`getInfo()`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxCollaborationAllowlist.html#getInfo--) ``` BoxCollaborationAllowlist domainAllowlist = new BoxCollaborationAllowlist(api, "id"); domainAllowlist.getInfo(); ``` ## Get all Collaboration Allowlist's Information for Domain All domain collaboration allowlists associated with an enterprise can be retrieved with [`getAll(BoxAPIConnection api)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxCollaborationAllowlist.html#getAll-com.box.sdk.BoxAPIConnection-java.lang.String...-) ``` BoxCollaborationAllowlist.getAll(api); ``` To specify the number of allowlists to retrieve you can pass a limit on how many allowlists to return to [`getAll(BoxAPIConnection api, int limit)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxCollaborationAllowlist.html#getAll-com.box.sdk.BoxAPIConnection-int-java.lang.String...-). ``` BoxCollaborationAllowlist.getAll(api, 10); ``` ## Remove a Collaboration Allowlist for a Domain To remove a collaboration allowlist you can call [`delete()`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxCollaborationAllowlist.html#delete--) ``` BoxCollaborationAllowlist domainToBeDeleted = new BoxCollaborationAllowlist(api, "allowlist-id"); domainToBeDeleted.delete(); ``` ## Add a Collaboration Allowlist for a User A collaboration allowlist can be created for a user with [`create(BoxAPIConnection api, String userID)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxCollaborationAllowlistExemptTarget.html#create-com.box.sdk.BoxAPIConnection-java.lang.String-) ``` String userID = "12345"; BoxCollaborationAllowlistExemptTarget.create(api, userID); ``` ## Get a Collaboration Allowlist's Information for a User To retrieve information regarding a specific user collaboration allowlist use [`getInfo()`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxCollaborationAllowlistExemptTarget.html#getInfo--) ``` BoxCollaborationAllowlistExemptTarget userAllowlist = new BoxCollaborationAllowlistExemptTarget(api, "allowlistID"); userAllowlist.getInfo(); ``` ## Get all Collaboration Allowlist's Information for a User To retrieve information regarding all user allowlists associated with an enterprise use [`getAll(BoxAPIConnection api)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxCollaborationAllowlistExemptTarget.html#getAll-com.box.sdk.BoxAPIConnection-java.lang.String...-) ``` BoxCollaborationAllowlistExemptTarget.getAll(api); ``` Alternatively you can specify the number of user allowlists to return with one request by passing a the maximum number of records to return to [`getAll(BoxApiConnection api, int limit)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxCollaborationAllowlistExemptTarget.html#getAll-com.box.sdk.BoxAPIConnection-int-java.lang.String...-) ``` BoxCollaborationAllowlistExemptTarget.getAll(api, 5); ``` ## Remove a Collaboration Allowlist for a User To remove a user collaboration allowlist entry from an enterprise use [`delete()`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxCollaborationAllowlistExemptTarget.html#delete--) ``` BoxCollaborationAllowlistExemptTarget userAllowlist = new BoxCollaborationAllowlistExemptTarget(api, "allowlist_id"); userAllowlist.delete(); ``` --- ### Collaboration Whitelists **Type:** page | **Section:** Additional Resources Collaboration Whitelists Collaboration Whitelists are used to determine specific email domains that can collaborate with a Box Enterprise… # Collaboration Whitelists Collaboration Whitelists are used to determine specific email domains that can collaborate with a Box Enterprise. Certain users can be exempted from these restrictions, for example if they are a trusted person who needs to collaborate outside of the normally-allowed set of domains. - [Add a Domain to Collaboration Whitelist](#add-a-domain-to-collaboration-whitelist) - [Get a Whitelisted Domain's Information](#get-a-whitelisted-domains-information) - [Get Whitelisted Domains for an Enterprise](#get-whitelisted-domains-for-an-enterprise) - [Remove a Domain from Collaboration Whitelist](#remove-a-domain-from-collaboration-whitelist) - [Exempt a User from the Collaboration Whitelist](#exempt-a-user-from-the-collaboration-whitelist) - [Get an Exempt User's Information](#get-an-exempt-users-information) - [Get All Exempt Users for an Enterprise](#get-all-exempt-users-for-an-enterprise) - [Remove a User Exemption from the Collaboration Whitelist](#remove-a-user-exemption-from-the-collaboration-whitelist) ## Add a Domain to Collaboration Whitelist You can whitelist a certain domain to allow collaboration with that domain for your enterprise by calling `CollaborationWhitelistManager.AddCollaborationWhitelistEntryAsync(string domainToWhitelist, string directionForWhitelist)`. ``` BoxCollaborationWhitelistEntry entry = await client.CollaborationWhitelistManager.AddCollaborationWhitelistEntryAsync( "example.com", "both" ); ``` ## Get a Whitelisted Domain's Information Information about a specific collaboration whitelist record, which shows the domain that is whitelisted, can be retrieved by calling `CollaborationWhitelistManager.GetCollaborationWhitelistEntryAsync(string id, IEnumerable<string> fields = null)`. ``` string entryID = "11111"; BoxCollaborationWhitelistEntry entry = await client.CollaborationWhitelistManager.GetCollaborationWhitelistEntryAsync( entryID ); ``` ## Get Whitelisted Domains for an Enterprise You can retrieve the collection of whitelisted domains for an enterprise by calling `CollaborationWhitelistManager.GetAllCollaborationWhitelistEntriesAsync(int limit= 100, string nextMarker = null, bool autoPaginate = false)`. ``` BoxCollectionMarkerBased<BoxCollaborationWhitelistEntry> whitelistedDomains = await client.CollaborationWhitelistManager .GetAllCollaborationWhitelistEntriesAsync(); ``` You can set the `limit` parameter to determine how many results will be fetched, and use the `nextMarker` parameter to manually page through the collection. Alternatively, setting the `autoPaginate` parameter to `true` will make as many API calls as necessary to retrieve the full collection and return it. ## Remove a Domain from Collaboration Whitelist You can remove a domain from the collaboration whitelist by calling `CollaborationWhitelistManager.DeleteCollaborationWhitelistEntryAsync(string id)`. ``` string entryID = "11111"; await client.CollaborationWhitelistManager.DeleteCollaborationWhitelistEntryAsync(entryID); ``` ## Exempt a User from the Collaboration Whitelist You can make a specific user exempt from the collaboration whitelist, which allows them to collaborate with users from any domain, by calling `CollaborationWhitelistManager.AddCollaborationWhitelistExemptUserAsync(string userId)`. ``` string userId = "22222"; BoxCollaborationWhitelistTargetEntry exemptUser = await client.CollaborationWhitelistManager .AddCollaborationWhitelistExemptUserAsync(userId); ``` ## Get an Exempt User's Information To retrieve information about a specific user exemption record, you can use `CollaborationWhitelistManager.GetCollaborationWhitelistExemptUserAsync(string id, IEnumerable<string> fields = null)`. ``` string exemptionID = "33333"; BoxCollaborationWhitelistTargetEntry exemptUser = await client.CollaborationWhitelistManager .GetCollaborationWhitelistExemptUserAsync(exemptionID); ``` ## Get All Exempt Users for an Enterprise To retrieve a collection of users who are exempt from the collaboration whitelist for an enterprise, call `CollaborationWhitelistManager.GetAllCollaborationWhitelistExemptUsersAsync(int limit = 100, string nextMarker = null, bool autoPaginate = false)`. ``` BoxCollectionMarkerBased<BoxCollaborationWhitelistTargetEntry> = await client.CollaborationWhitelistManager .GetAllCollaborationWhitelistExemptUsersAsync(); ``` You can set the `limit` parameter to determine how many results will be fetched, and use the `nextMarker` parameter to manually page through the collection. Alternatively, setting the `autoPaginate` parameter to `true` will make as many API calls as necessary to retrieve the full collection and return it. ## Remove a User Exemption from the Collaboration Whitelist To remove a user exemption from collaboration whitelist and make that user subject to whitelist restrictions again, you can call `CollaborationWhitelistManager.DeleteCollaborationWhitelistExemptUserAsync(string id)`. ``` string exemptionId = "55555"; await client.CollaborationWhitelistManager.DeleteCollaborationWhitelistExemptUserAsync(exemptionId); ``` --- ### CollaborationAllowlistEntriesManager **Type:** page | **Section:** Additional Resources CollaborationAllowlistEntriesManager List allowed collaboration domains Add domain to list of allowed collaboration domains Get allowed… # CollaborationAllowlistEntriesManager - [List allowed collaboration domains](#list-allowed-collaboration-domains) - [Add domain to list of allowed collaboration domains](#add-domain-to-list-of-allowed-collaboration-domains) - [Get allowed collaboration domain](#get-allowed-collaboration-domain) - [Remove domain from list of allowed collaboration domains](#remove-domain-from-list-of-allowed-collaboration-domains) ## List allowed collaboration domains Returns the list domains that have been deemed safe to create collaborations for within the current enterprise. This operation is performed by calling function `getCollaborationWhitelistEntries`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-collaboration-whitelist-entries/). ``` await client.collaborationAllowlistEntries.getCollaborationWhitelistEntries(); ``` ### Arguments queryParams `GetCollaborationWhitelistEntriesQueryParams` - Query parameters of getCollaborationWhitelistEntries method headersInput `GetCollaborationWhitelistEntriesHeadersInput` - Headers of getCollaborationWhitelistEntries method cancellationToken `undefined | CancellationToken` - Token used for request cancellation. ### Returns This function returns a value of type `CollaborationAllowlistEntries`. Returns a collection of domains that are allowed for collaboration. ## Add domain to list of allowed collaboration domains Creates a new entry in the list of allowed domains to allow collaboration for. This operation is performed by calling function `createCollaborationWhitelistEntry`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-collaboration-whitelist-entries/). ``` await client.collaborationAllowlistEntries.createCollaborationWhitelistEntry({ direction: 'inbound' as CreateCollaborationWhitelistEntryRequestBodyDirectionField, domain: domain, } satisfies CreateCollaborationWhitelistEntryRequestBody); ``` ### Arguments requestBody `CreateCollaborationWhitelistEntryRequestBody` - Request body of createCollaborationWhitelistEntry method optionalsInput `CreateCollaborationWhitelistEntryOptionalsInput` ### Returns This function returns a value of type `CollaborationAllowlistEntry`. Returns a new entry on the list of allowed domains. ## Get allowed collaboration domain Returns a domain that has been deemed safe to create collaborations for within the current enterprise. This operation is performed by calling function `getCollaborationWhitelistEntryById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-collaboration-whitelist-entries-id/). ``` await client.collaborationAllowlistEntries.getCollaborationWhitelistEntryById( newEntry.id!, ); ``` ### Arguments collaborationWhitelistEntryId `string` - The ID of the entry in the list. Example: "213123" optionalsInput `GetCollaborationWhitelistEntryByIdOptionalsInput` ### Returns This function returns a value of type `CollaborationAllowlistEntry`. Returns an entry on the list of allowed domains. ## Remove domain from list of allowed collaboration domains Removes a domain from the list of domains that have been deemed safe to create collaborations for within the current enterprise. This operation is performed by calling function `deleteCollaborationWhitelistEntryById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-collaboration-whitelist-entries-id/). ``` await client.collaborationAllowlistEntries.deleteCollaborationWhitelistEntryById( entry.id!, ); ``` ### Arguments collaborationWhitelistEntryId `string` - The ID of the entry in the list. Example: "213123" optionalsInput `DeleteCollaborationWhitelistEntryByIdOptionalsInput` ### Returns This function returns a value of type `undefined`. A blank response is returned if the entry was successfully deleted. --- ### CollaborationAllowlistEntriesManager **Type:** page | **Section:** Additional Resources CollaborationAllowlistEntriesManager List allowed collaboration domains Add domain to list of allowed collaboration domains Get allowed… # CollaborationAllowlistEntriesManager - [List allowed collaboration domains](#list-allowed-collaboration-domains) - [Add domain to list of allowed collaboration domains](#add-domain-to-list-of-allowed-collaboration-domains) - [Get allowed collaboration domain](#get-allowed-collaboration-domain) - [Remove domain from list of allowed collaboration domains](#remove-domain-from-list-of-allowed-collaboration-domains) ## List allowed collaboration domains Returns the list domains that have been deemed safe to create collaborations for within the current enterprise. This operation is performed by calling function `get_collaboration_whitelist_entries`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-collaboration-whitelist-entries/). ``` client.collaboration_allowlist_entries.get_collaboration_whitelist_entries() ``` ### Arguments marker `Optional[str]` - Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`. limit `Optional[int]` - The maximum number of items to return per page. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `CollaborationAllowlistEntries`. Returns a collection of domains that are allowed for collaboration. ## Add domain to list of allowed collaboration domains Creates a new entry in the list of allowed domains to allow collaboration for. This operation is performed by calling function `create_collaboration_whitelist_entry`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-collaboration-whitelist-entries/). ``` client.collaboration_allowlist_entries.create_collaboration_whitelist_entry( domain, CreateCollaborationWhitelistEntryDirection.INBOUND ) ``` ### Arguments domain `str` - The domain to add to the list of allowed domains. direction `CreateCollaborationWhitelistEntryDirection` - The direction in which to allow collaborations. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `CollaborationAllowlistEntry`. Returns a new entry on the list of allowed domains. ## Get allowed collaboration domain Returns a domain that has been deemed safe to create collaborations for within the current enterprise. This operation is performed by calling function `get_collaboration_whitelist_entry_by_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-collaboration-whitelist-entries-id/). ``` client.collaboration_allowlist_entries.get_collaboration_whitelist_entry_by_id( new_entry.id ) ``` ### Arguments collaboration_whitelist_entry_id `str` - The ID of the entry in the list. Example: "213123" extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `CollaborationAllowlistEntry`. Returns an entry on the list of allowed domains. ## Remove domain from list of allowed collaboration domains Removes a domain from the list of domains that have been deemed safe to create collaborations for within the current enterprise. This operation is performed by calling function `delete_collaboration_whitelist_entry_by_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-collaboration-whitelist-entries-id/). ``` client.collaboration_allowlist_entries.delete_collaboration_whitelist_entry_by_id( entry.id ) ``` ### Arguments collaboration_whitelist_entry_id `str` - The ID of the entry in the list. Example: "213123" extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `None`. A blank response is returned if the entry was successfully deleted. --- ### CollaborationAllowlistExemptTargetsManager **Type:** page | **Section:** Additional Resources CollaborationAllowlistExemptTargetsManager List users exempt from collaboration domain restrictions Create user exemption from collaboration… # CollaborationAllowlistExemptTargetsManager - [List users exempt from collaboration domain restrictions](#list-users-exempt-from-collaboration-domain-restrictions) - [Create user exemption from collaboration domain restrictions](#create-user-exemption-from-collaboration-domain-restrictions) - [Get user exempt from collaboration domain restrictions](#get-user-exempt-from-collaboration-domain-restrictions) - [Remove user from list of users exempt from domain restrictions](#remove-user-from-list-of-users-exempt-from-domain-restrictions) ## List users exempt from collaboration domain restrictions Returns a list of users who have been exempt from the collaboration domain restrictions. This operation is performed by calling function `getCollaborationWhitelistExemptTargets`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-collaboration-whitelist-exempt-targets/). ``` await client.collaborationAllowlistExemptTargets.getCollaborationWhitelistExemptTargets(); ``` ### Arguments queryParams `GetCollaborationWhitelistExemptTargetsQueryParams` - Query parameters of getCollaborationWhitelistExemptTargets method headersInput `GetCollaborationWhitelistExemptTargetsHeadersInput` - Headers of getCollaborationWhitelistExemptTargets method cancellationToken `undefined | CancellationToken` - Token used for request cancellation. ### Returns This function returns a value of type `CollaborationAllowlistExemptTargets`. Returns a collection of user exemptions. ## Create user exemption from collaboration domain restrictions Exempts a user from the restrictions set out by the allowed list of domains for collaborations. This operation is performed by calling function `createCollaborationWhitelistExemptTarget`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-collaboration-whitelist-exempt-targets/). ``` await client.collaborationAllowlistExemptTargets.createCollaborationWhitelistExemptTarget( { user: { id: user.id, } satisfies CreateCollaborationWhitelistExemptTargetRequestBodyUserField, } satisfies CreateCollaborationWhitelistExemptTargetRequestBody, ); ``` ### Arguments requestBody `CreateCollaborationWhitelistExemptTargetRequestBody` - Request body of createCollaborationWhitelistExemptTarget method optionalsInput `CreateCollaborationWhitelistExemptTargetOptionalsInput` ### Returns This function returns a value of type `CollaborationAllowlistExemptTarget`. Returns a new exemption entry. ## Get user exempt from collaboration domain restrictions Returns a users who has been exempt from the collaboration domain restrictions. This operation is performed by calling function `getCollaborationWhitelistExemptTargetById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-collaboration-whitelist-exempt-targets-id/). ``` await client.collaborationAllowlistExemptTargets.getCollaborationWhitelistExemptTargetById( newExemptTarget.id!, ); ``` ### Arguments collaborationWhitelistExemptTargetId `string` - The ID of the exemption to the list. Example: "984923" optionalsInput `GetCollaborationWhitelistExemptTargetByIdOptionalsInput` ### Returns This function returns a value of type `CollaborationAllowlistExemptTarget`. Returns the user's exempted from the list of collaboration domains. ## Remove user from list of users exempt from domain restrictions Removes a user's exemption from the restrictions set out by the allowed list of domains for collaborations. This operation is performed by calling function `deleteCollaborationWhitelistExemptTargetById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-collaboration-whitelist-exempt-targets-id/). ``` await client.collaborationAllowlistExemptTargets.deleteCollaborationWhitelistExemptTargetById( exemptTarget.id!, ); ``` ### Arguments collaborationWhitelistExemptTargetId `string` - The ID of the exemption to the list. Example: "984923" optionalsInput `DeleteCollaborationWhitelistExemptTargetByIdOptionalsInput` ### Returns This function returns a value of type `undefined`. A blank response is returned if the exemption was successfully deleted. --- ### CollaborationAllowlistExemptTargetsManager **Type:** page | **Section:** Additional Resources CollaborationAllowlistExemptTargetsManager List users exempt from collaboration domain restrictions Create user exemption from collaboration… # CollaborationAllowlistExemptTargetsManager - [List users exempt from collaboration domain restrictions](#list-users-exempt-from-collaboration-domain-restrictions) - [Create user exemption from collaboration domain restrictions](#create-user-exemption-from-collaboration-domain-restrictions) - [Get user exempt from collaboration domain restrictions](#get-user-exempt-from-collaboration-domain-restrictions) - [Remove user from list of users exempt from domain restrictions](#remove-user-from-list-of-users-exempt-from-domain-restrictions) ## List users exempt from collaboration domain restrictions Returns a list of users who have been exempt from the collaboration domain restrictions. This operation is performed by calling function `get_collaboration_whitelist_exempt_targets`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-collaboration-whitelist-exempt-targets/). ``` client.collaboration_allowlist_exempt_targets.get_collaboration_whitelist_exempt_targets() ``` ### Arguments marker `Optional[str]` - Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`. limit `Optional[int]` - The maximum number of items to return per page. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `CollaborationAllowlistExemptTargets`. Returns a collection of user exemptions. ## Create user exemption from collaboration domain restrictions Exempts a user from the restrictions set out by the allowed list of domains for collaborations. This operation is performed by calling function `create_collaboration_whitelist_exempt_target`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-collaboration-whitelist-exempt-targets/). ``` client.collaboration_allowlist_exempt_targets.create_collaboration_whitelist_exempt_target( CreateCollaborationWhitelistExemptTargetUser(id=user.id) ) ``` ### Arguments user `CreateCollaborationWhitelistExemptTargetUser` - The user to exempt. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `CollaborationAllowlistExemptTarget`. Returns a new exemption entry. ## Get user exempt from collaboration domain restrictions Returns a users who has been exempt from the collaboration domain restrictions. This operation is performed by calling function `get_collaboration_whitelist_exempt_target_by_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-collaboration-whitelist-exempt-targets-id/). ``` client.collaboration_allowlist_exempt_targets.get_collaboration_whitelist_exempt_target_by_id( new_exempt_target.id ) ``` ### Arguments collaboration_whitelist_exempt_target_id `str` - The ID of the exemption to the list. Example: "984923" extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `CollaborationAllowlistExemptTarget`. Returns the user's exempted from the list of collaboration domains. ## Remove user from list of users exempt from domain restrictions Removes a user's exemption from the restrictions set out by the allowed list of domains for collaborations. This operation is performed by calling function `delete_collaboration_whitelist_exempt_target_by_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-collaboration-whitelist-exempt-targets-id/). ``` client.collaboration_allowlist_exempt_targets.delete_collaboration_whitelist_exempt_target_by_id( exempt_target.id ) ``` ### Arguments collaboration_whitelist_exempt_target_id `str` - The ID of the exemption to the list. Example: "984923" extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `None`. A blank response is returned if the exemption was successfully deleted. --- ### Collaborations **Type:** page | **Section:** Additional Resources Collaborations Collaborations are used to share folders and files between users or groups. They also define what permissions a user has for… # Collaborations Collaborations are used to share folders and files between users or groups. They also define what permissions a user has for a folder or file. - [Add a Collaboration](#add-a-collaboration) - [Edit a Collaboration](#edit-a-collaboration) - [Remove a Collaboration](#remove-a-collaboration) - [Get a Collaboration's Information](#get-a-collaborations-information) - [Get the Collaborations on a Folder](#get-the-collaborations-on-a-folder) - [Get the Collaborations on a File](#get-the-collaborations-on-a-file) - [Get Pending Collaborations](#get-pending-collaborations) - [Respond to Pending Collaborations](#respond-to-pending-collaborations) ## Add a Collaboration A collaboration can be added for an existing user with [`collaborations.createWithUserID(userID, itemID, role, options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Collaborations.html#createWithUserID). The `role` parameter determines what permissions the collaborator will have on the folder. You can create a collaboration on a file by setting the `type` option to `'file'`. ``` // Invite user 123456 to collaborate on folder 987654 client.collaborations.createWithUserID('123456', '987654', client.collaborationRoles.EDITOR) .then(collaboration => { /* collaboration -> { type: 'collaboration', id: '11111', created_by: { type: 'user', id: '22222', name: 'Inviting User', login: 'inviter@example.com' }, created_at: '2016-11-16T21:33:31-08:00', modified_at: '2016-11-16T21:33:31-08:00', expires_at: null, status: 'accepted', accessible_by: { type: 'user', id: '123456', name: 'Collaborator User', login: 'collaborator@example.com' }, role: 'editor', acknowledged_at: '2016-11-16T21:33:31-08:00', item: { type: 'folder', id: '987654', sequence_id: '0', etag: '0', name: 'Collaborated Folder' } } */ }); ``` ``` // Invite user 123456 to collaborate on file 987654 var options = { type: client.itemTypes.FILE }; client.collaborations.createWithUserID('123456', '987654', client.collaborationRoles.EDITOR, options) .then(collaboration => { /* collaboration -> { type: 'collaboration', id: '11111', created_by: { type: 'user', id: '22222', name: 'Inviting User', login: 'inviter@example.com' }, created_at: '2016-11-16T21:33:31-08:00', modified_at: '2016-11-16T21:33:31-08:00', expires_at: null, status: 'accepted', accessible_by: { type: 'user', id: '123456', name: 'Collaborator User', login: 'collaborator@example.com' }, role: 'editor', acknowledged_at: '2016-11-16T21:33:31-08:00', item: { type: 'file', id: '987654', sequence_id: '0', etag: '0', name: 'Collaborated File' } } */ }); ``` You can also add a collaboration by providing an email address with [`collaborations.createWithUserEmail(email, itemID, role, options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Collaborations.html#createWithUserEmail). If the recipient doesn't have a Box account, they will be asked create one. ``` client.collaborations.createWithUserEmail('collaborator@example.com', '987654', client.collaborationRoles.VIEWER) .then(collaboration => { /* collaboration -> { type: 'collaboration', id: '11111', created_by: { type: 'user', id: '22222', name: 'Inviting User', login: 'inviter@example.com' }, created_at: '2016-11-16T21:33:31-08:00', modified_at: '2016-11-16T21:33:31-08:00', expires_at: null, status: 'accepted', accessible_by: { type: 'user', id: '33333', name: 'Collaborator User', login: 'collaborator@example.com' }, role: 'viewer', acknowledged_at: '2016-11-16T21:33:31-08:00', item: { type: 'folder', id: '987654', sequence_id: '0', etag: '0', name: 'Collaborated Folder' } } */ ``` Groups can also be added as collaborators by providing the group ID to [`collaborations.createWithGroupID(groupID, itemID, role, options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Collaborations.html#createWithGroupID). All members of the group will receive the same role and permissions. ``` client.collaborations.createWithGroupID('56473', '987654', client.collaborationRoles.UPLOADER) .then(collaboration => { /* collaboration -> { type: 'collaboration', id: '11111', created_by: null, created_at: '2016-11-16T21:48:44-08:00', modified_at: '2016-11-16T21:48:44-08:00', expires_at: null, status: 'accepted', accessible_by: { type: 'group', id: '56473', name: 'My Group' }, role: 'uploader', acknowledged_at: '2016-11-16T21:48:44-08:00', item: { type: 'folder', id: '987654', sequence_id: '0', etag: '0', name: 'Collaborated Folder' } } */ }); ``` ## Edit a Collaboration A collaboration can be edited by calling [`collaborations.update(collaborationID, updates, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Collaborations.html#update) with the fields to be updated. For example, to change the role of a collaboration: ``` client.collaborations.update('11111', {role: client.collaborationRoles.PREVIEWER}) .then(collaboration => { /* collaboration -> { type: 'collaboration', id: '11111', created_by: { type: 'user', id: '22222', name: 'Inviting User', login: 'inviter@example.com' }, created_at: '2015-11-03T18:36:37-08:00', modified_at: '2016-11-16T21:01:19-08:00', expires_at: null, status: 'accepted', accessible_by: { type: 'user', id: '33333', name: 'Collaborated User', login: 'collaborator@example.com' }, role: 'previewer', acknowledged_at: '2015-11-03T18:36:37-08:00', item: { type: 'folder', id: '44444', sequence_id: '1', etag: '1', name: 'Collaborated Folder' } } */ }); ``` ## Remove a Collaboration A collaboration can be removed by calling [`collaborations.delete(collaborationID, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Collaborations.html#delete). ``` client.collaborations.delete('56473') .then(() => { // removal succeeded — no value provided }); ``` ## Get a Collaboration's Information Calling [`collaborations.get(collaborationID, options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Collaborations.html#get) on a collaboration returns a snapshot of the collaboration's info. ``` var collaborationID = '22222'; client.collaborations.get(collaborationID) .then(collaboration => { /* collaboration -> { type: 'collaboration', id: '22222', created_by: { type: 'user', id: '11111', name: 'Example User', login: 'user@example.com' }, created_at: '2012-12-12T10:54:37-08:00', modified_at: '2012-12-12T11:30:43-08:00', expires_at: null, status: 'accepted', accessible_by: { type: 'user', id: '33333',, name: 'Collaborator User', login: 'collaborator@example.com' }, role: 'editor', acknowledged_at: '2012-12-12T11:30:43-08:00', item: { type: 'folder', id: '12345', sequence_id: '0', etag: '0', name: 'Shared Pictures' } } */ }); ``` ## Get the Collaborations on a Folder You can get all of the collaborations on a folder by calling [`folders.getCollaborations(folderID, options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Folders.html#getCollaborations) on the folder. ``` var folderID = '12345'; client.folders.getCollaborations(folderID) .then(collaborations => { /* collaborations -> { total_count: 1, entries: [ { type: 'collaboration', id: '11111', created_by: { type: 'user', id: '22222', name: 'Example User', login: 'user@example.com' }, created_at: '2011-11-29T12:56:35-08:00', modified_at: '2012-09-11T15:12:32-07:00', expires_at: null, status: 'accepted', accessible_by: { type: 'user', id: '33333', name: 'Collaborator User', login: 'collaborator@example.com' }, role: 'editor', acknowledged_at: '2011-11-29T12:59:40-08:00', item: null } ] } */ }); ``` ## Get the Collaborations on a File You can get the collection of collaborations on a file by calling [`files.getCollaborations(fileID, options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Files.html#getCollaborations) with the ID of the file. ``` var fileID = '98765'; client.files.getCollaborations(fileID) .then(collaborations => { /* collaborations -> { total_count: 1, entries: [ { type: 'collaboration', id: '11111', created_by: { type: 'user', id: '22222', name: 'Example User', login: 'user@example.com' }, created_at: '2011-11-29T12:56:35-08:00', modified_at: '2012-09-11T15:12:32-07:00', expires_at: null, status: 'accepted', accessible_by: { type: 'user', id: '33333', name: 'Collaborator User', login: 'collaborator@example.com' }, role: 'editor', acknowledged_at: '2011-11-29T12:59:40-08:00', item: null } ] } */ }); ``` ## Get Pending Collaborations A collection of all the user's pending collaborations can be retrieved with [`collaborations.getPending(callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Collaborations.html#getPending). ``` client.collaborations.getPending() .then(collaborations => { /* collaborations -> { total_count: 1, entries: [ { type: 'collaboration', id: '11111', created_by: { type: 'user', id: '22222', name: 'Example User', login: 'user@example.com' }, created_at: '2011-11-29T12:56:35-08:00', modified_at: '2012-09-11T15:12:32-07:00', expires_at: null, status: 'pending', accessible_by: { type: 'user', id: '33333', name: 'Collaborator User', login: 'collaborator@example.com' }, role: 'editor', acknowledged_at: '2011-11-29T12:59:40-08:00', item: null } ] } */ }); ``` ## Respond to Pending Collaborations You can accept or reject a pending collaboration by calling [`collaborations.respondToPending(collaborationID,newStatus, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Collaborations.html#respondToPending) with a status of `'accepted'` or `'rejected'`. ``` var collaborationID = '22222'; client.collaborations.respondToPending(collaborationID, 'accepted') .then(collaboration => { /* collaboration -> { type: 'collaboration', id: '22222', created_by: { type: 'user', id: '11111', name: 'Example User', login: 'user@example.com' }, created_at: '2012-12-12T10:54:37-08:00', modified_at: '2012-12-12T11:30:43-08:00', expires_at: null, status: 'accepted', accessible_by: { type: 'user', id: '33333',, name: 'Collaborator User', login: 'collaborator@example.com' }, role: 'editor', acknowledged_at: '2012-12-12T11:30:43-08:00', item: { type: 'folder', id: '12345', sequence_id: '0', etag: '0', name: 'Shared Pictures' } } */ }); ``` --- ### Collaborations **Type:** page | **Section:** Additional Resources Collaborations Collaborations are used to share folders between users or groups. They also define what permissions a user has for a folder… # Collaborations Collaborations are used to share folders between users or groups. They also define what permissions a user has for a folder. - [Add a Collaboration](#add-a-collaboration) - [Edit a Collaboration](#edit-a-collaboration) - [Remove a Collaboration](#remove-a-collaboration) - [Get a Collaboration's Information](#get-a-collaborations-information) - [Get the Collaborations on a Folder](#get-the-collaborations-on-a-folder) - [Get the Collaborations on a File](#get-the-collaborations-on-a-file) - [Get Pending Collaborations](#get-pending-collaborations) - [Accept or Decline a Pending Collaboration](#accept-or-decline-a-pending-collaboration) ## Add a Collaboration A collaboration can be added for an existing user or group with [`collaborate(BoxCollaborator collaborator, BoxCollaboration.Role role)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFolder.html#collaborate-com.box.sdk.BoxCollaborator-com.box.sdk.BoxCollaboration.Role-). The `role` parameter determines what permissions the collaborator will have on the folder. ``` BoxCollaborator user = new BoxUser(api, "user-id") BoxFolder folder = new BoxFolder(api, "folder-id"); folder.collaborate(user, BoxCollaboration.Role.EDITOR); ``` You can also add a collaboration by providing an email address with [`collaborate(String emailAddress, BoxCollaboration.Role role)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFolder.html#collaborate-java.lang.String-com.box.sdk.BoxCollaboration.Role-). If the recipient doesn't have a Box account, they will be asked create one. ``` BoxFolder folder = new BoxFile(api, "id"); folder.collaborate("gcurtis@box.com", BoxCollaboration.Role.EDITOR); ``` If you need to create a collaboration with a group, provide a group id. ``` BoxCollaborator group = new BoxGroup(api, "group-id"); BoxFolder folder = new BoxFolder(api, "folder-id"); folder.collaborate(group, BoxCollaboration.Role.EDITOR); ``` ## Edit a Collaboration A collaboration can be edited by creating a new [`BoxCollaboration.Info`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxCollaboration.Info.html) object or updating an existing one, and then passing it to [`updateInfo(BoxCollaboration.Info fieldsToUpdate)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxCollaboration.html#updateInfo-com.box.sdk.BoxCollaboration.Info-) ``` BoxCollaboration collaboration = new BoxCollaboration(api, "id"); BoxCollaboration.Info info = collaboration.new Info(); info.setStatus(BoxCollaboration.Status.ACCEPTED); collaboration.updateInfo(info); ``` ## Remove a Collaboration A collaboration can be removed by calling [`delete()`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxCollaboration.html#delete--). ``` BoxCollaboration collaboration = new BoxCollaboration(api, "id"); collaboration.delete(); ``` ## Get a Collaboration's Information Calling [`getInfo()`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxCollaboration.html#getInfo-java.lang.String...-) on a collaboration returns a snapshot of the collaboration's info. ``` BoxCollaboration collaboration = new BoxCollaboration(api, "id"); BoxCollaboration.Info info = collaboration.getInfo(); ``` You can also choose to retrieve only specific fields of the collaboration by calling [`getInfo(String... fields)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxCollaboration.html#getInfo-java.lang.String...-) with a list of field names. ``` BoxCollaboration collaboration = new BoxCollaboration(api, "id"); BoxCollaboration.Info info = collaboration.getInfo(BoxCollaboration.ALL_FIELDS); ``` ## Get the Collaborations on a Folder You can get all of the collaborations on a folder by calling [`getCollaborations()`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFolder.html#getCollaborations--) on the folder. ``` BoxFolder folder = new BoxFolder(api, "id"); Collection<BoxCollaboration.Info> collaborations = folder.getCollaborations(); ``` ## Get the Collaborations on a File You can get an iterator over all of the collaborations on a file by calling [`BoxFile#getAllFileCollaborations(String... fields)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFile.html#getAllFileCollaborations-java.lang.String...-) on the file. ``` BoxFile file = new BoxFile(api, "id"); Iterable<BoxCollaboration.Info> collaborations = file.getAllFileCollaborations(); ``` ## Get Pending Collaborations A collection of all the user's pending collaborations can be retrieved with [`getPendingCollaborations(BoxAPIConnection api)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxCollaboration.html#getPendingCollaborations-com.box.sdk.BoxAPIConnection-). ``` Collection<BoxCollaboration.Info> pendingCollaborations = BoxCollaboration.getPendingCollaborations(api); ``` ## Accept or Decline a Pending Collaboration To accept or decline a pending collaboration, update the info of the pending collaboration object with the desired status. ``` // Accept all pending collaborations Collection<BoxCollaboration.Info> pendingCollaborations = BoxCollaboration.getPendingCollaborations(api); for (BoxCollaboration.Info collabInfo : pendingCollaborations) { collabInfo.setStatus(BoxCollaboration.Status.ACCEPTED); collabInfo.getResource().updateInfo(collabInfo); } ``` --- ### Collaborations **Type:** page | **Section:** Additional Resources Collaborations Collaborations are used to share folders between users or groups. They also define what permissions a user has for a folder… # Collaborations Collaborations are used to share folders between users or groups. They also define what permissions a user has for a folder. - [Add a Collaboration](#add-a-collaboration) - [Edit a Collaboration](#edit-a-collaboration) - [Remove a Collaboration](#remove-a-collaboration) - [Get a Collaboration's Information](#get-a-collaborations-information) - [List Collaborations on a Folder or File](#list-collaborations-on-a-folder-or-file) - [List Pending Collaborations](#list-pending-collaborations) - [Accept or Reject a Pending Collaboration](#accept-or-reject-a-pending-collaboration) ## Add a Collaboration You can add a collaboration on a folder or a file by calling [`item.collaborate(accessible_by, role, can_view_path=None, notify=None, fields=None)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.item.Item.collaborate). Pass the [`User`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.user.User) or [`Group`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.group.Group) to collaborate the item with as the `accessible_by` parameter. The `role` parameter determines what permissions the collaborator will have on the folder. This method returns a [`Collaboration`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.collaboration.Collaboration) object representing the new collaboration on the item. ``` from boxsdk.object.collaboration import CollaborationRole user = client.user(user_id='11111') collaboration = client.folder(folder_id='22222').collaborate(user, CollaborationRole.VIEWER) collaborator = collaboration.accessible_by item = collaboration.item has_accepted = 'has' if collaboration.status == 'accepted' else 'has not' print(f'{collaborator.name} {has_accepted} accepted the collaboration to folder "{item.name}"') ``` Alternatively, you can also invite a user with their email address. ``` from boxsdk.object.collaboration import CollaborationRole email_of_invitee = 'testuser@example.com' collaboration = client.folder(folder_id='22222').collaborate_with_login(email_of_invitee, CollaborationRole.VIEWER) ``` Or, you can invite a group using the group id ``` from boxsdk.object.collaboration import CollaborationRole group = client.group(group_id='11111') collaboration = client.folder(folder_id='22222').collaborate(group, CollaborationRole.VIEWER) collaborator = collaboration.accessible_by item = collaboration.item has_accepted = 'has' if collaboration.status == 'accepted' else 'has not' print(f'{collaborator.name} {has_accepted} accepted the collaboration to folder "{item.name}"') ``` **Note:** The `can_view_path` parameter is currently only available for collaborations on folders. ## Edit a Collaboration A collaboration can be edited by calling [`collaboration.update_info(*, data=None, role=None, status=None, **kwargs)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.collaboration.Collaboration.update_info). Note that `role` fields is always required when updating a collaboration. This method returns an updated [`Collaboration`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.collaboration.Collaboration) object, leaving the original unmodified. ``` from boxsdk.object.collaboration import CollaborationRole collaboration_update = {'role': CollaborationRole.EDITOR, 'can_view_path': False} collaboration = client.collaboration(collab_id='12345') updated_collaboration = collaboration.update_info(data=collaboration_update) ``` ## Remove a Collaboration A collaboration can be removed by calling [`collaboration.delete()`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.base_object.BaseObject.delete). This will generally cause the user or group associated with the collaboration to lose access to the item. This method returns `True` to indicate that removal succeeded. ``` collaboration_id = '1111' client.collaboration(collaboration_id).delete() ``` ## Get a Collaboration's Information To get information about a specific collaboration, call [`collaboration.get()`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.base_object.BaseObject.get). This method returns a new [`Collaboration`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.collaboration.Collaboration) with fields populated by data from the API. ``` collaboration = client.collaboration(collab_id='12345').get() ``` ## List Collaborations on a Folder or File To retrieve all collaborations on a specified [`Folder`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.folder.Folder) or [`File`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.file.File), call [`item.get_collaborations(limit=None, marker=None, fields=None)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.item.Item.get_collaborations). This method returns a `BoxObjectCollection` that you can use to iterate over all [`Collaboration`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.collaboration.Collaboration) objects in the collection. ``` collaborations = client.folder(folder_id='22222').get_collaborations() for collab in collaborations: target = collab.accessible_by print(f'{target.type.capitalize()} {target.name} is collaborated on the folder') ``` ``` collaborations = client.file(file_id='11111').get_collaborations() for collab in collaborations target = collab.accessible_by print(f'{target.type.capitalize()} {target.name} is collaborated on the file') ``` ## List Pending Collaborations To retrieve all pending collaborations for the current user, call [`client.get_pending_collaborations(limit=None, offset=None, fields=None)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.client.html#boxsdk.client.client.Client.get_pending_collaborations). The user can accept or reject these collaborations. This method returns a `BoxObjectCollection` that you can use to iterate over all pending [`Collaboration`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.collaboration.Collaboration) objects in the collection. ``` pending_collaborations = client.get_pending_collaborations() for pending_collaboration in pending_collaborations: print(f'Collaboration {pending_collaboration.id} is pending') ``` ## Accept or Reject a Pending Collaboration To accept or reject a pending collaboration, call [`collaboration.accept()`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.collaboration.Collaboration.accept) or [`collaboration.reject()`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.collaboration.Collaboration.reject). These methods both return the updated [`Collaboration`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.collaboration.Collaboration) object, leaving the original unmodified. ``` accepted_collab = client.collaboration(collab_id='12345').accept() rejected_collab = client.collaboration(collab_id='98765').reject() ``` --- ### Collaborations **Type:** page | **Section:** Additional Resources Collaborations Collaborations are used to share folders and files between users or groups. They also define what permissions a user has for… # Collaborations Collaborations are used to share folders and files between users or groups. They also define what permissions a user has for a folder or file. - [Add a Collaboration](#add-a-collaboration) - [Edit a Collaboration](#edit-a-collaboration) - [Remove a Collaboration](#remove-a-collaboration) - [Get a Collaboration's Information](#get-a-collaborations-information) - [Get the Collaborations on a Folder](#get-the-collaborations-on-a-folder) - [Get the Collaborations on a File](#get-the-collaborations-on-a-file) - [Get Pending Collaborations](#get-pending-collaborations) ## Add a Collaboration A collaboration can be added for an existing user by calling `CollaborationsManager.AddCollaborationAsync(BoxCollaborationRequest collaborationRequest, IEnumerable<string> fields = null, bool? notify = null)`. The `Role` field of the `collaborationRequest` parameter determines what permissions the collaborator will have on the folder or file. ``` // collaborate folder 11111 with user 22222 BoxCollaborationRequest requestParams = new BoxCollaborationRequest() { Item = new BoxRequestEntity() { Type = BoxType.folder, Id = "11111" }, Role = "editor", AccessibleBy = new BoxCollaborationUserRequest() { Type = BoxType.user, Id = "22222" } }; BoxCollaboration collab = await client.CollaborationsManager.AddCollaborationAsync(requestParams); ``` Administrators can set the `notify` parameter to `false` to prevent the user who is being collaborated from receiving an email notification about the collaboration. If you want to collaborate a group, provide the type group and the group id. ``` // collaborate folder 11111 with group 333333 BoxCollaborationRequest requestParams = new BoxCollaborationRequest() { Item = new BoxRequestEntity() { Type = BoxType.folder, Id = "11111" }, Role = "editor", AccessibleBy = new BoxCollaborationUserRequest() { Type = BoxType.group, Id = "333333" } }; BoxCollaboration collab = await client.CollaborationsManager.AddCollaborationAsync(requestParams); ``` ## Edit a Collaboration A collaboration can be edited by calling `CollaborationsManager.EditCollaborationAsync(BoxCollaborationRequest collaborationRequest, IEnumerable<string> fields = null)` with the fields to be updated. For example, to change the role of a collaboration: ``` BoxCollaborationRequest requestParams = new BoxCollaborationRequest() { Id = "12345", Role = "viewer" }; BoxCollaboration collab = await client.CollaborationsManager.EditCollaborationAsync(requestParams); ``` ## Remove a Collaboration A collaboration can be removed by calling `CollaborationsManager.RemoveCollaborationAsync(string id)`. This will generally remove the user or group's access to the collaborated item. ``` await client.CollaborationsManager.RemoveCollaborationAsync(id: "12345"); ``` ## Get a Collaboration's Information To get information about a specific collaboration record, call `CollaborationsManager.GetCollaborationAsync(string id, IEnumerable<string> fields = null)` with the ID of the collaboration. ``` BoxCollaboration collab = await client.CollaborationsManager.GetCollaborationAsync(id: "22222"); ``` ## Get the Collaborations on a Folder You can get all of the collaborations on a folder by calling `FoldersManager.GetCollaborationsAsync(string id, IEnumerable<string> fields = null)` with the ID of the folder. ``` string folderId = "11111"; BoxCollection<BoxCollaboration> collaborations = await client.FoldersManager .GetCollaborationsAsync(folderId); ``` ## Get the Collaborations on a File You can get the collection of collaborations on a file by calling `FilesManager.GetCollaborationsCollectionAsync(string id, string marker = null, int? limit = null, IEnumerable<string> fields = null, bool autoPaginate = false)` with the ID of the file. ``` string fileId = "98765"; BoxCollectionMarkerBasedV2<BoxCollaboration> collaborations = await client.FilesManager .GetCollaborationsCollectionAsync(fileId); ``` ## Get Pending Collaborations A collection of all the user's pending collaborations can be retrieved with `CollaborationsManager.GetPendingCollaborationAsync(IEnumerable<string> fields = null)`. ``` BoxCollection<BoxCollaboration> pendingCollabs = await CollaborationsManager .GetPendingCollaborationAsync(); ``` --- ### Collaborations **Type:** page | **Section:** Additional Resources Collaborations Collaborations are used to share folders and files between users or groups. They also define what permissions a user has for… # Collaborations Collaborations are used to share folders and files between users or groups. They also define what permissions a user has for a folder or file. - [Get Collaboration](#get-collaboration) - [Add Collaboration](#add-collaboration) - [Update Collaboration](#update-collaboration) - [Delete Collaboration](#delete-collaboration) - [Get Pending Collaborations](#get-pending-collaborations) ## Get Collaboration To retrieve a Collaboration record from the API, call [`client.collaborations.get(collaborationId:fields:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/CollaborationsModule.html#/s:6BoxSDK20CollaborationsModuleC3get15collaborationId6fields10completionySS_SaySSGSgys6ResultOyAA13CollaborationCAA0A8SDKErrorCGctF) with the ID of the collaboration. ``` client.collaborations.get(collaborationId: "12345") { (result: Result<Collaboration, BoxSDKError>) in guard case let .success(collaboration) = result else { print("Error retrieving collaboration") return } let collaborator: String switch collaboration.accessibleBy.collaboratorValue { case let .user(user): collaborator = "user \(user.name)" case let .group(group): collaborator = "group \(group.name)" } let itemName: String switch collaboration.item { case let .file(file): itemName = file.name case let .folder(folder): itemName = folder.name case let .webLink(webLink): itemName = webLink.name } print("Collaboration \(collaboration.id) gives \(collaborator) access to \(itemName)") } ``` ## Add Collaboration To add a collaborator to an item, call [`client.collaborations.create(itemType:itemId:role:accessibleBy:accessibleByType:canViewPath:fields:notify:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/CollaborationsModule.html#/s:6BoxSDK20CollaborationsModuleC6create8itemType0F2Id4role12accessibleBy0jkG011canViewPath6fields6notify10completionySS_SSAA17CollaborationRoleOSSAA010AccessibleK0OSbSgSaySSGSgARys6ResultOyAA0R0CAA0A8SDKErrorCGctF) with the type and ID of the item, as well as the type and ID of the collaborator — a user or a group. A `role` for the collaborator must be specified, which will determine the permissions the collaborator receives on the item. To collaborate a user, pass in a user id and the `.user` accessible by type. ``` client.collaborations.create( itemType: "folder", itemId: "22222", role: .editor, accessibleBy: "33333", accessibleByType: .user ) { (result: Result<Collaboration, BoxSDKError>) in guard case let .success(collaboration) = result else { print("Error creating collaboration") return } print("Collaboration successfully created") } ``` To collaborate a group, pass in a group id and the `.group` accessible by type. ``` client.collaborations.create( itemType: "folder", itemId: "22222", role: .editor, accessibleBy: "44444", accessibleByType: .group ) { (result: Result<Collaboration, BoxSDKError>) in guard case let .success(collaboration) = result else { print("Error creating collaboration") return } print("Collaboration successfully created") } ``` ## Update Collaboration To update a collaboration record, call [`client.users.update(collaborationId:role:status:canViewPath:fields:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/CollaborationsModule.html#/s:6BoxSDK20CollaborationsModuleC6update15collaborationId4role6status11canViewPath6fields10completionySS_AA17CollaborationRoleOAA0O6StatusOSgSbSgSaySSGSgys6ResultOyAA0O0CAA0A8SDKErrorCGctF) with the ID of the collaboration to update and the properties to update, including at least the `role`. ``` client.collaborations.update(collaborationId: "12345", role: .viewer) { (result: Result<Collaboration, BoxSDKError>) in guard case let .success(collaboration) = result else { print("Error updating collaboration") return } print("Updated collaboration") } ``` ## Delete Collaboration To delete a collaboration, removing the collaborator's access to the relevant item, call [`client.collaborations.delete(collaborationId:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/CollaborationsModule.html#/s:6BoxSDK20CollaborationsModuleC6delete15collaborationId10completionySS_ys6ResultOyytAA0A8SDKErrorCGctF) with the ID of the collaboration to delete. ``` client.collaborations.delete(collaborationId: "12345") { (result: Result<Void, BoxSDKError>) in guard case .success = result else { print("Error deleting collaboration") return } print("Collaboration deleted") } ``` ## Get Pending Collaborations To retrieve a list of the pending collaborations requiring the user to accept or reject them, call [`client.collaborations.listPendingForEnterprise(offset:limit:fields:)`](https://opensource.box.com/box-ios-sdk/Classes/CollaborationsModule.html#/s:6BoxSDK20CollaborationsModuleC24listPendingForEnterprise6offset5limit6fields10completionySiSg_AISaySSGSgys6ResultOyAA14PagingIteratorCyAA13CollaborationCGAA0A8SDKErrorCGctF). The method returns an iterator, which is used to get pending collaborations. ``` let iterator = client.collaborations.listPendingForEnterprise() iterator.next { result in switch result { case let .success(page): for collaboration in page.entries { print("Collaboration created by \(collaboration.createdBy?.name)") } case let .failure(error): print(error) } } ``` --- ### Collaborations **Type:** page | **Section:** Additional Resources Collaborations Collaborations are used to share folders and files between users or groups. They also define what permissions a user has for… # Collaborations Collaborations are used to share folders and files between users or groups. They also define what permissions a user has for a folder or file. - [Get Collaboration](#get-collaboration) - [Add Collaboration](#add-collaboration) - [Update Collaboration](#update-collaboration) - [Delete Collaboration](#delete-collaboration) - [Get Pending Collaborations](#get-pending-collaborations) ## Get Collaboration To retrieve a Collaboration record from the API, call [`client.collaborations.get(collaborationId:fields:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/CollaborationsModule.html#/s:6BoxSDK20CollaborationsModuleC3get15collaborationId6fields10completionySS_SaySSGSgys6ResultOyAA13CollaborationCAA0A8SDKErrorCGctF) with the ID of the collaboration. ``` client.collaborations.get(collaborationId: "12345") { (result: Result<Collaboration, BoxSDKError>) in guard case let .success(collaboration) = result else { print("Error retrieving collaboration") return } let collaborator: String switch collaboration.accessibleBy.collaboratorValue { case let .user(user): collaborator = "user \(user.name)" case let .group(group): collaborator = "group \(group.name)" } let itemName: String switch collaboration.item { case let .file(file): itemName = file.name case let .folder(folder): itemName = folder.name case let .webLink(webLink): itemName = webLink.name } print("Collaboration \(collaboration.id) gives \(collaborator) access to \(itemName)") } ``` ## Add Collaboration To add a collaborator to an item, call [`client.collaborations.create(itemType:itemId:role:accessibleBy:accessibleByType:canViewPath:fields:notify:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/CollaborationsModule.html#/s:6BoxSDK20CollaborationsModuleC6create8itemType0F2Id4role12accessibleBy0jkG011canViewPath6fields6notify10completionySS_SSAA17CollaborationRoleOSSAA010AccessibleK0OSbSgSaySSGSgARys6ResultOyAA0R0CAA0A8SDKErrorCGctF) with the type and ID of the item, as well as the type and ID of the collaborator — a user or a group. A `role` for the collaborator must be specified, which will determine the permissions the collaborator receives on the item. To collaborate a user, pass in a user id and the `.user` accessible by type. ``` client.collaborations.create( itemType: "folder", itemId: "22222", role: .editor, accessibleBy: "33333", accessibleByType: .user ) { (result: Result<Collaboration, BoxSDKError>) in guard case let .success(collaboration) = result else { print("Error creating collaboration") return } print("Collaboration successfully created") } ``` To collaborate a group, pass in a group id and the `.group` accessible by type. ``` client.collaborations.create( itemType: "folder", itemId: "22222", role: .editor, accessibleBy: "44444", accessibleByType: .group ) { (result: Result<Collaboration, BoxSDKError>) in guard case let .success(collaboration) = result else { print("Error creating collaboration") return } print("Collaboration successfully created") } ``` ## Update Collaboration To update a collaboration record, call [`client.users.update(collaborationId:role:status:canViewPath:fields:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/CollaborationsModule.html#/s:6BoxSDK20CollaborationsModuleC6update15collaborationId4role6status11canViewPath6fields10completionySS_AA17CollaborationRoleOAA0O6StatusOSgSbSgSaySSGSgys6ResultOyAA0O0CAA0A8SDKErrorCGctF) with the ID of the collaboration to update and the properties to update, including at least the `role`. ``` client.collaborations.update(collaborationId: "12345", role: .viewer) { (result: Result<Collaboration, BoxSDKError>) in guard case let .success(collaboration) = result else { print("Error updating collaboration") return } print("Updated collaboration") } ``` ## Delete Collaboration To delete a collaboration, removing the collaborator's access to the relevant item, call [`client.collaborations.delete(collaborationId:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/CollaborationsModule.html#/s:6BoxSDK20CollaborationsModuleC6delete15collaborationId10completionySS_ys6ResultOyytAA0A8SDKErrorCGctF) with the ID of the collaboration to delete. ``` client.collaborations.delete(collaborationId: "12345") { (result: Result<Void, BoxSDKError>) in guard case .success = result else { print("Error deleting collaboration") return } print("Collaboration deleted") } ``` ## Get Pending Collaborations To retrieve a list of the pending collaborations requiring the user to accept or reject them, call [`client.collaborations.listPendingForEnterprise(offset:limit:fields:)`](https://opensource.box.com/box-ios-sdk/Classes/CollaborationsModule.html#/s:6BoxSDK20CollaborationsModuleC24listPendingForEnterprise6offset5limit6fields10completionySiSg_AISaySSGSgys6ResultOyAA14PagingIteratorCyAA13CollaborationCGAA0A8SDKErrorCGctF). The method returns an iterator, which is used to get pending collaborations. ``` let iterator = client.collaborations.listPendingForEnterprise() iterator.next { result in switch result { case let .success(page): for collaboration in page.entries { print("Collaboration created by \(collaboration.createdBy?.name)") } case let .failure(error): print(error) } } ``` --- ### Collections **Type:** page | **Section:** Additional Resources Collections Collections are used to store a custom user-defined set of items that may not all be in the same folder. Currently, the only… # Collections Collections are used to store a custom user-defined set of items that may not all be in the same folder. Currently, the only collection available is the `favorites` collection ([source](https://box.dev/reference/resources/collection/)). - [Get a User's Collections](#get-a-users-collections) - [Get the Items in a Collection](#get-the-items-in-a-collection) - [Add File to a Collection](#add-file-to-a-collection) - [Remove File from a Collection](#remove-file-from-a-collection) - [Add Folder to a Collection](#add-folder-to-a-collection) - [Remove Folder from a Collection](#remove-folder-from-a-collection) - [Add Web Link to a Collection](#add-web-link-to-a-collection) - [Remove Web Link from a Collection](#remove-web-link-from-a-collection) ## Get a User's Collections Get a list of all collections the user has defined by calling [`collections.getAll(callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Collections.html#getAll). A user always has a default collection called "Favorites" which they can add items to. ``` client.collections.getAll() .then(collections => { /* collections -> { total_count: 1, entries: [ { type: 'collection', id: '11111', name: 'Favorites', collection_type: 'favorites' } ], limit: 100, offset: 0 } */ }); ``` ## Get the Items in a Collection Get a list of the items in a collection by passing the ID of the collection to [`collections.getItems(collectionID, options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Collections.html#getItems). ``` client.collections.getItems('81934', {fields: 'name', limit: 2}) .then(items => { /* items -> { total_count: 24, entries: [ { type: 'folder', id: '192429928', sequence_id: '1', etag: '1', name: 'Stephen Curry Three Pointers' }, { type: 'file', id: '818853862', sequence_id: '0', etag: '0', name: 'Warriors.jpg' } ], offset: 0, limit: 2 } */ }); ``` ## Add File to a Collection To add a file to a collection, call the [`files.addToCollection(fileID, collectionID, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Files.html#addToCollection) method with the IDs of the file and collection. ``` client.files.addToCollection('87263', '235747', callback); ``` ## Remove File from a Collection To remove a file from a collection, call the [`files.removeFromCollection(fileID, collectionID, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Files.html#removeFromCollection) method with the IDs of the file and collection. ``` client.files.removeFromCollection('87263', '235747', callback); ``` ## Add Folder to a Collection To add a folder to a collection, call the [`folders.addToCollection(folderID, collectionID, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Folders.html#addToCollection) method with the IDs of the folder and collection. ``` client.folders.addToCollection('87263', '235747', callback); ``` ## Remove Folder from a Collection To remove a folder from a collection, call the [`folders.removeFromCollection(folderID, collectionID, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Folders.html#removeFromCollection) method with the IDs of the folder and collection. ``` client.folders.removeFromCollection('87263', '235747', callback); ``` ## Add Web Link to a Collection To add a web link to a collection, call the [`weblinks.addToCollection(webLinkID, collectionID, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/WebLinks.html#addToCollection) method with the IDs of the web link and collection. ``` client.weblinks.addToCollection('87263', '235747', callback); ``` ## Remove Web Link from a Collection To remove a web link from a collection, call the [`weblinks.removeFromCollection(webLinkID, collectionID, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/WebLinks.html#removeFromCollection) method with the IDs of the web link and collection. ``` client.weblinks.removeFromCollection('87263', '235747', callback); ``` --- ### Collections **Type:** page | **Section:** Additional Resources Collections Collections contain information about the items contained inside of them, including files and folders. The only collection… # Collections Collections contain information about the items contained inside of them, including files and folders. The only collection available currently is a “Favorites” collection. The contents of the collection are discovered in a similar way in which the contents of a folder are discovered. - [Get Collections](#get-collections) - [Get a Collection's Items](#get-a-collections-items) - [Add Items to a Collection](#add-items-to-a-collection) - [Remove Items from a Collection](#remove-items-from-a-collection) ## Get Collections Existing collections can be retrieved by calling the [`getAllCollections(BoxAPIConnection)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxCollection.html#getAllCollections-com.box.sdk.BoxAPIConnection-) method. Currently only "Favorites" collection is supported. ``` Iterable<BoxCollection.Info> collections = BoxCollection.getAllCollections(api); for (BoxCollection.Info collectionInfo : collections) { // Do something with the collection. } ``` ## Get a Collection's Items Every `BoxCollection` implements [`Iterable<BoxItem>`](https://box.github.io/box-java-sdk/javadoc/com/box/sdk/BoxCollection.html#iterator--) which allows you to iterate over the collection's contents. The iterator automatically handles paging and will make additional network calls to load more data from Box when necessary. ``` BoxFolder folder = new BoxFolder(api, "id"); for (BoxItem.Info itemInfo : folder) { if (itemInfo instanceof BoxFile.Info) { BoxFile.Info fileInfo = (BoxFile.Info) itemInfo; // Do something with the file. } else if (itemInfo instanceof BoxFolder.Info) { BoxFolder.Info folderInfo = (BoxFolder.Info) itemInfo; // Do something with the folder. } } ``` ## Add Items to a Collection Add an item to a collection by calling [`setCollections(BoxCollection... collections)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxItem.html#setCollections-com.box.sdk.BoxCollection...-) on any `BoxItem`. Note that this method will overwrite all collections that the item belongs to. ``` BoxCollection favorites = null; for (BoxCollection.Info info : BoxCollection.getAllCollections(api)) { if (info.getCollectionType().equals("favorites")) { favorites = info.getResource(); break; } } BoxFile file = new BoxFile(api, "id"); file.setCollections(favorites); ``` ## Remove Items from a Collection Remove an item from a collection by calling [`setCollections(BoxCollection... collections)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxItem.html#setCollections-com.box.sdk.BoxCollection...-) on any `BoxItem` and exclude the collection to wish to remove it from. ``` BoxFile file = new BoxFile(api, "id"); BoxFile.Info info = file.getInfo("collections"); ArrayList<BoxCollection> collections = new ArrayList<BoxCollection>(); for (BoxCollection.Info info : info.getCollections(api)) { // Include every existing collection except for favorites to remove the file // from the favorites collection. if (!info.getCollectionType().equals("favorites")) { collections.add(info.getResource()); } } file.setCollections(collections.toArray()); ``` --- ### Collections **Type:** page | **Section:** Additional Resources Collections Collections allow users to mark specific files, folders and web links to make it easier to find them. Get a User's Collections… # Collections Collections allow users to mark specific files, folders and web links to make it easier to find them. - [Get a User's Collections](#get-a-users-collections) - [Get the Items in a Collection](#get-the-items-in-a-collection) - [Add an Item to a Collection](#add-an-item-to-a-collection) - [Remove an Item from a Collection](#remove-an-item-from-a-collection) ## Get a User's Collections To get all collections belonging to a user, call [`client.collections(limit=None, offset=0, fields=None)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.client.html#boxsdk.client.client.Client.collections). This method returns a `BoxObjectCollection` that you can use to iterate over all the [`Collection`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.collection.Collection) objects in the set. ``` collections = client.collections() for collection in collections: print(f'Collection "{collection.name}" has ID {collection.id}') ``` ## Get the Items in a Collection To retrieve a list of items contained in a collection, call [`collection.get_items(limit=None, offset=0, fields=None)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.collection.Collection.get_items). This method returns a `BoxObjectCollection` that you can use to iterate over all the [`BaseItem`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.base_item.BaseItem) objects in the collection. [`BaseItem`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.base_item.BaseItem) is a super class for files, folders and web links. ``` items = client.collection(collection_id='12345').get_items() for item in items: print(f'{item.type.capitalize()} "{item.name}" is in the collection') ``` ## Add an Item to a Collection To add an [`BaseItem`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.base_item.BaseItem) to a collection, call [`item.add_to_collection(collection)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.base_item.BaseItem.add_to_collection) with the [`Collection`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.collection.Collection) you want to add the item to. This method returns the updated [`BaseItem`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.base_item.BaseItem) object. ``` collection = client.collection(collection_id='12345') updated_file = client.file(file_id='11111').add_to_collection(collection) print(f'File "{updated_file.name}" added to collection!') ``` ## Remove an Item from a Collection To remove an [`BaseItem`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.base_item.BaseItem) from a collection, call [`item.remove_from_collection(collection)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.base_item.BaseItem.remove_from_collection) with the [`Collection`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.collection.Collection) you want to remove the item from. This method returns the updated [`BaseItem`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.base_item.BaseItem) object. ``` collection = client.collection(collection_id='12345') updated_file = client.file(file_id='11111').remove_from_collection(collection) print(f'File "{updated_file.name}" removed from collection!') ``` --- ### Collections **Type:** page | **Section:** Additional Resources Collections Collections are used to store a custom user-defined set of items that may not all be in the same folder. Get a User's… # Collections Collections are used to store a custom user-defined set of items that may not all be in the same folder. - [Get a User's Collections](#get-a-users-collections) - [Get the Items in a Collection](#get-the-items-in-a-collection) - [Set an Item's Collections](#set-an-items-collections) ## Get a User's Collections Get a list of all collections the user has defined by calling `CollectionsManager.GetCollectionsAsync()`. A user always has a default collection called "Favorites" which they can add items to. ``` BoxCollection<BoxCollectionItem> collections = await client.CollectionsManager.GetCollectionsAsync(); ``` ## Get the Items in a Collection Get a list of the items in a collection by passing the ID of the collection to `CollectionsManager.GetCollectionItemsAsync(string collectionId, int limit = 100, int offset = 0, IEnumerable<string> fields = null, bool autoPaginate = false)`. ``` BoxCollection<BoxItem> items = await client.CollectionsManager.GetCollectionItemsAsync(id: "11111"); ``` ## Set an Item's Collections You can set the collections an item belongs to by calling `CollectionsManager.CreateOrDeleteCollectionsForFolderAsync(string folderId, BoxCollectionsRequest collectionsRequest)` or `CollectionsManager.CreateOrDeleteCollectionsForFileAsync(string fileId, BoxCollectionsRequest collectionsRequest)`. ``` // Put file 11111 into collection 22222 BoxCollectionsRequest requestParams = new BoxCollectionsRequest() { Collections = new List<BoxRequestEntity>() { new BoxRequestEntity() { Id = "22222" } }; }; BoxFile file = await client.CollectionsManager.CreateOrDeleteCollectionsForFileAsync(fileId: "11111", requestParams); ``` --- ### CollectionsManager **Type:** page | **Section:** Additional Resources CollectionsManager List all collections List collection items Get collection by ID List all collections Retrieves all collections for a… # CollectionsManager - [List all collections](#list-all-collections) - [List collection items](#list-collection-items) - [Get collection by ID](#get-collection-by-id) ## List all collections Retrieves all collections for a given user. Currently, only the `favorites` collection is supported. This operation is performed by calling function `getCollections`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-collections/). ``` await client.collections.getCollections(); ``` ### Arguments queryParams `GetCollectionsQueryParams` - Query parameters of getCollections method headersInput `GetCollectionsHeadersInput` - Headers of getCollections method cancellationToken `undefined | CancellationToken` - Token used for request cancellation. ### Returns This function returns a value of type `Collections`. Returns all collections for the given user. ## List collection items Retrieves the files and/or folders contained within this collection. This operation is performed by calling function `getCollectionItems`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-collections-id-items/). ``` await client.collections.getCollectionItems(favouriteCollection.id!); ``` ### Arguments collectionId `string` - The ID of the collection. Example: "926489" optionalsInput `GetCollectionItemsOptionalsInput` ### Returns This function returns a value of type `ItemsOffsetPaginated`. Returns an array of items in the collection. ## Get collection by ID Retrieves a collection by its ID. This operation is performed by calling function `getCollectionById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-collections-id/). ``` await client.collections.getCollectionById(collections.entries![0].id!); ``` ### Arguments collectionId `string` - The ID of the collection. Example: "926489" optionalsInput `GetCollectionByIdOptionalsInput` ### Returns This function returns a value of type `Collection`. Returns an array of items in the collection. --- ### CollectionsManager **Type:** page | **Section:** Additional Resources CollectionsManager List all collections List collection items Get collection by ID List all collections Retrieves all collections for a… # CollectionsManager - [List all collections](#list-all-collections) - [List collection items](#list-collection-items) - [Get collection by ID](#get-collection-by-id) ## List all collections Retrieves all collections for a given user. Currently, only the `favorites` collection is supported. This operation is performed by calling function `get_collections`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-collections/). ``` client.collections.get_collections() ``` ### Arguments fields `Optional[List[str]]` - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested. offset `Optional[int]` - The offset of the item at which to begin the response. Queries with offset parameter value exceeding 10000 will be rejected with a 400 response. limit `Optional[int]` - The maximum number of items to return per page. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `Collections`. Returns all collections for the given user. ## List collection items Retrieves the files and/or folders contained within this collection. This operation is performed by calling function `get_collection_items`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-collections-id-items/). ``` client.collections.get_collection_items(favourite_collection.id) ``` ### Arguments collection_id `str` - The ID of the collection. Example: "926489" fields `Optional[List[str]]` - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested. offset `Optional[int]` - The offset of the item at which to begin the response. Queries with offset parameter value exceeding 10000 will be rejected with a 400 response. limit `Optional[int]` - The maximum number of items to return per page. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `ItemsOffsetPaginated`. Returns an array of items in the collection. ## Get collection by ID Retrieves a collection by its ID. This operation is performed by calling function `get_collection_by_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-collections-id/). ``` client.collections.get_collection_by_id(collections.entries[0].id) ``` ### Arguments collection_id `str` - The ID of the collection. Example: "926489" extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `Collection`. Returns an array of items in the collection. --- ### Comments **Type:** page | **Section:** Additional Resources Comments Comment objects represent a user-created comment on a file. They can be added directly to a file. Get a Comment's Information Get… # Comments Comment objects represent a user-created comment on a file. They can be added directly to a file. - [Get a Comment's Information](#get-a-comments-information) - [Get the Comments on a File](#get-the-comments-on-a-file) - [Add a Comment to a File](#add-a-comment-to-a-file) - [Reply to a Comment](#reply-to-a-comment) - [Change a Comment's Message](#change-a-comments-message) - [Delete a Comment](#delete-a-comment) ## Get a Comment's Information Calling [`comments.get(commentID, options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Comments.html#get) on a comment returns a snapshot of the comment's info. ``` client.comments.get('11111') .then(comment => { /* comment -> { type: 'comment', id: '11111', is_reply_comment: false, message: 'Great work!', created_by: { type: 'user', id: '22222', name: 'Example User', login: 'user@example.com' }, created_at: '2012-12-12T11:25:01-08:00', item: { id: '33333', type: 'file' }, modified_at: '2012-12-12T11:25:01-08:00' } */ }); ``` ## Get the Comments on a File You can get all of the comments on a file by calling the [`files.getComments(fileID, options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Files.html#getComments) method. ``` var fileID = '12345'; client.files.getComments(fileID) .then(comments => { /* comments -> { total_count: 1, entries: [ { type: 'comment', id: '11111', is_reply_comment: false, message: 'Great work!', created_by: { type: 'user', id: '22222', name: 'Example User', login: 'user@example.com' }, created_at: '2012-12-12T11:25:01-08:00', item: { id: '33333', type: 'file' }, modified_at: '2012-12-12T11:25:01-08:00' } ] } */ }); ``` ## Add a Comment to a File A comment can be added to a file with the [`comments.create(fileID, text, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Comments.html#create) method. ``` client.comments.create('33333', 'Is this the latest version?') .then(comment => { /* comment -> { type: 'comment', id: '11111', is_reply_comment: false, message: 'Is this the latest version?', created_by: { type: 'user', id: '22222', name: 'Example User', login: 'user@example.com' }, created_at: '2012-12-12T11:25:01-08:00', item: { id: '33333', type: 'file' }, modified_at: '2012-12-12T11:25:01-08:00' } */ }); ``` A comment's message can also contain @mentions by using the string `@[userid:username]` anywhere within the message, where userid and username are the ID and username of the person being mentioned. [See the documentation](https://developers.box.com/docs/#comments-comment-object) on the `tagged_message` field for more information on @mentions. To make a tagged comment, use the [`comments.createTaggedComment(fileID, text, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Comments.html#createTaggedComment) method. ``` client.comments.createTaggedComment('33333', '@[23560:Bob] Is this the latest version?') .then(comment => { /* comment -> { type: 'comment', id: '11111', is_reply_comment: false, tagged_message: '@[23560:Bob] Is this the latest version?', created_by: { type: 'user', id: '22222', name: 'Example User', login: 'user@example.com' }, created_at: '2012-12-12T11:25:01-08:00', item: { id: '33333', type: 'file' }, modified_at: '2012-12-12T11:25:01-08:00' } */ }); ``` ## Reply to a Comment To reply to a comment, call [`comments.reply(commentID, text, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Comments.html#reply) with the ID of the comment to reply to and the text of the reply comment. ``` // Reply to the comment with ID 11111 client.comments.reply('11111', 'Yes, this is the latest version.') .then(comment => { /* comment -> { type: 'comment', id: '44444', is_reply_comment: true, message: 'Yes, this is the latest version', created_by: { type: 'user', id: '55555', name: 'Example User 2', login: 'user2@example.com' }, created_at: '2012-12-13T07:19:08-08:00', item: { id: '33333', type: 'file' }, modified_at: '2012-12-13T07:19:08-08:00' } */ }); ``` A comment's message can also contain at-mentions by using the string `@[userid:username]` anywhere within the message, where `userid` and `username` are the ID and username of the person being mentioned. [See the documentation](https://developers.box.com/docs/#comments-comment-object) on the `tagged_message` field for more information on at-mentions. To make a tagged reply, use the [`comments.createTaggedReply(commentID, text, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Comments.html#createTaggedReply) method. ``` client.comments.createTaggedReply('11111', '@[22222:Sam] Yes, this is the most recent version!') .then(comment => { /* comment -> { type: 'comment', id: '44444', is_reply_comment: false, tagged_message: '@[22222:Sam] Yes, this is the most recent version!', created_by: { type: 'user', id: '55555', name: 'Example User 2', login: 'user2@example.com' }, created_at: '2012-12-13T07:19:08-08:00', item: { id: '33333', type: 'file' }, modified_at: '2012-12-13T07:19:08-08:00' } */ }); ``` ## Change a Comment's Message The message of a comment can be changed with the [`comments.update(commentID, updates, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Comments.html#update) method. ``` client.comments.update('11111', {message: 'New message'}) .then(comment => { /* comment -> { type: 'comment', id: '11111', is_reply_comment: false, message: 'New message', created_by: { type: 'user', id: '22222', name: 'Example User', login: 'user@example.com' }, created_at: '2012-12-12T11:25:01-08:00', item: { id: '33333', type: 'file' }, modified_at: '2012-12-12T11:25:01-08:00' } */ }); ``` ## Delete a Comment A comment can be deleted with the [`comments.delete(commentID, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Comments.html#delete) method. ``` client.comments.delete('11111') .then(() => { // deletion successful — no value returned }); ``` --- ### Comments **Type:** page | **Section:** Additional Resources Comments Comment objects represent a user-created comment on a file. They can be added directly to a file or they can be a reply to another… # Comments Comment objects represent a user-created comment on a file. They can be added directly to a file or they can be a reply to another comment. - [Get a Comment's Information](#get-a-comments-information) - [Get the Comments on a File](#get-the-comments-on-a-file) - [Add a Comment to a File](#add-a-comment-to-a-file) - [Reply to a Comment](#reply-to-a-comment) - [Change a Comment's Message](#change-a-comments-message) - [Delete a Comment](#delete-a-comment) ## Get a Comment's Information Calling [`getInfo()`](https://box.github.io/box-java-sdk/javadoc/com/box/sdk/BoxComment.html#getInfo--) on a comment returns a snapshot of the comment's info. ``` BoxComment comment = new BoxComment(api, "id"); BoxComment.Info info = comment.getInfo(); ``` ## Get the Comments on a File You can get all of the comments on a file by calling the [`getComments()`](https://box.github.io/box-java-sdk/javadoc/com/box/sdk/BoxFile.html#getComments--) method. ``` BoxFile file = new BoxFile(api, "id"); List<BoxComment.Info> comments = file.getComments(); ``` ## Add a Comment to a File A comment can be added to a file with the [`addComment(String message)`](https://box.github.io/box-java-sdk/javadoc/com/box/sdk/BoxFile.html#addComment-java.lang.String-) method. ``` BoxFile file = new BoxFile(api, "id"); file.addComment("This file is pretty cool."); ``` The comment's message can also contain @mentions by using the string @[userid:username] anywhere within the message, where userid and username are the ID and username of the person being mentioned. [See the documentation] ([https://developers.box.com/docs/#comments-comment-object](https://developers.box.com/docs/#comments-comment-object)) on the `tagged_message` field for more information on @mentions. ``` BoxFile file = new BoxFile(api, "id"); file.addComment("Message mentioning @[1234:user@box.com]."); ``` ## Reply to a Comment You can reply to a comment with the [`reply(String message)`](https://box.github.io/box-java-sdk/javadoc/com/box/sdk/BoxComment.html#reply-java.lang.String-) method. ``` BoxComment comment = new BoxComment(api, "id"); comment.reply("I agree with this!"); ``` The comment's message can also contain @mentions by using the string @[userid:username] anywhere within the message, where userid and username are the ID and username of the person being mentioned. [See the documentation] ([https://developers.box.com/docs/#comments-comment-object](https://developers.box.com/docs/#comments-comment-object)) on the `tagged_message` field for more information on @mentions. ``` BoxComment comment = new BoxComment(api, "id"); comment.reply("@[1234:user@box.com] I agree with this!"); ``` ## Change a Comment's Message The message of a comment can be changed with the [`changeMessage(String message)`](https://box.github.io/box-java-sdk/javadoc/com/box/sdk/BoxComment.html#changeMessage-java.lang.String-) method. ``` BoxComment comment = new BoxComment(api, "id"); comment.changeMessage("An edited message."); ``` ## Delete a Comment A comment can be deleted with the [`delete()`](https://box.github.io/box-java-sdk/javadoc/com/box/sdk/BoxComment.html#delete--) method. ``` BoxComment comment = new BoxComment(api, "id"); comment.delete(); ``` --- ### Comments **Type:** page | **Section:** Additional Resources Comments Comment objects represent a user-created comment on a file. They can be added directly to a file. Get Information About a Comment… # Comments Comment objects represent a user-created comment on a file. They can be added directly to a file. - [Get Information About a Comment](#get-information-about-a-comment) - [Get the Comments on a File](#get-the-comments-on-a-file) - [Add a Comment to a File](#add-a-comment-to-a-file) - [Reply to a Comment](#reply-to-a-comment) - [Edit a Comment](#edit-a-comment) - [Delete a Comment](#delete-a-comment) ## Get Information About a Comment To get a specific comment object, first call `[client.comment(comment_id)`][comment](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.client.html#boxsdk.client.client.Client.comment) to construct the appropriate [`Comment`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.comment.Comment) object, and then call [`comment.get(*, fields=None, headers=None, **kwargs)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.base_object.BaseObject.get) to retrieve the data about the comment. The latter method returns a new [`Comment`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.comment.Comment) object with fields populated by data from the API, leaving the original unmodified. ``` comment = client.comment(comment_id='55555').get() print(f'The comment says "{comment.message}"') ``` ## Get the Comments on a File To retrieve the comment left on a file, call [`file.get_comments(limit=None, offset=0, fields=None)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.file.File.get_comments). This method returns a `BoxObjectCollection` that you can use to iterate over all the [`Comment`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.comment.Comment) objects in the set. ``` comments = client.file(file_id='11111').get_comments() for comment in comments: print(f'Comment was left by {comment.created_by.name} at {comment.created_at}') ``` ## Add a Comment to a File To leave a comment on a file, call [`file.add_comment(message)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.file.File.add_comment) with the message to leave in the comment. ``` comment = client.file(file_id='11111').add_comment('When should I have this done by?') ``` You can at-mention other users by adding special tags within the message, in the format `@[USER_ID:USER_NAME]`. For example, to at-mention John Doe, whose user ID is `"33333"`: `@[33333:John Doe]`. ``` comment = client.file(file_id='11111').add_comment('Hey @[44444:boss], when should I have this done by?') ``` This method returns a [`Comment`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.comment.Comment) object representing the newly-created comment. ## Reply to a Comment To reply to a comment, call [`comment.reply(message)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.comment.Comment.reply) with the message to leave in the comment. ``` reply_comment = client.comment(comment_id='12345').reply('If possible, please finish this by the end of the week!') ``` You can at-mention other users by adding special tags within the message, in the format `@[USER_ID:USER_NAME]`. For example, to at-mention John Doe, whose user ID is `"33333"`: `@[33333:John Doe]`. ``` reply_comment = client.comment(comment_id='12345').reply('@[33333:John Doe], if possible, please finish this by the end of the week!') ``` This method returns a [`Comment`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.comment.Comment) object representing the newly-created comment. ## Edit a Comment To edit a comment and change its message, call [`comment.edit(message)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.comment.Comment.edit) with the message to leave in the comment. You can at-mention other users by adding special tags within the message, in the format `@[USER_ID:USER_NAME]`. For example, to at-mention John Doe, whose user ID is `"33333"`: `@[33333:John Doe]`. This method returns an updated [`Comment`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.comment.Comment) object, leaving the original unmodified. ``` edited_comment = client.comment(comment_id='98765').edit('If possible, please finish this by Friday!') ``` ## Delete a Comment To delete a comment, call [`comment.delete()`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.base_object.BaseObject.delete). This will remove the comment from the file. This method returns `True` to indicate that the deletion succeeded. ``` client.comment(comment_id='12345').delete() ``` --- ### Comments **Type:** page | **Section:** Additional Resources Comments Comment objects represent a user-created comment on a file. They can be added directly to a file. Get a Comment's Information Get… # Comments Comment objects represent a user-created comment on a file. They can be added directly to a file. - [Get a Comment's Information](#get-a-comments-information) - [Get the Comments on a File](#get-the-comments-on-a-file) - [Add a Comment to a File](#add-a-comment-to-a-file) - [Change a Comment's Message](#change-a-comments-message) - [Delete a Comment](#delete-a-comment) ## Get a Comment's Information To get information about a specific comment, call `CommentsManager.GetInformationAsync(string id, IEnumerable<string> fields = null)` with the ID of the comment. ``` BoxComment comment = await client.CommentsManager.GetInformationAsync(id: "11111"); ``` ## Get the Comments on a File You can get all of the comments on a file by calling `FilesManager.GetCommentsAsync(string id, IEnumerable<string> fields = null)` with the ID of the file. ``` string fileId = "11111"; BoxCollection<BoxComment> comments = await client.FilesManager.GetCommentsAsync(fileId); ``` ## Add a Comment to a File A comment can be added to a file by calling `CommentsManager.AddCommentAsync(BoxCommentRequest commentRequest, IEnumerable<string> fields = null)`. ``` var requestParams = new BoxCommentRequest() { Item = new BoxRequestEntity() { Type = BoxType.File, Id = "12345" }, Message = "Great work!" }; BoxComment comment = await client.CommentsManager.AddCommentAsync(requestParams); ``` ## Change a Comment's Message The message of a comment can be changed by calling `CommentsManager.UpdateAsync(string id, BoxCommentRequest commentsRequest, IEnumerable<string> fields = null)` with the ID of the comment and the fields to update. ``` var requestParams = new BoxCommentRequest() { Message = "New message" }; BoxComment updatedComment = await client.CommentsManager.UpdateAsync(id: "11111", requestParams); ``` ## Delete a Comment A comment can be deleted by calling `CommentsManager.DeleteAsync(string id)` with the ID of the comment. ``` await client.CommentsManager.DeleteAsync(id: "11111"); ``` --- ### Comments **Type:** page | **Section:** Additional Resources Comments Comment objects represent a user-created comment on a file. They can be added directly to a file. Get Comment Create Comment Update… # Comments Comment objects represent a user-created comment on a file. They can be added directly to a file. - [Get Comment](#get-comment) - [Create Comment](#create-comment) - [Update Comment](#update-comment) - [Delete Comment](#delete-comment) ## Get Comment To retrieve information about a comment, call [`client.comments.get(commentId:fields:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/CommentsModule.html#/s:6BoxSDK14CommentsModuleC3get9commentId6fields10completionySS_SaySSGSgys6ResultOyAA7CommentCAA0A8SDKErrorCGctF) with the ID of the comment. ``` client.comments.get(commentId: "55555") { (result: Result<Comment, BoxSDKError>) in guard case let .success(comment) = result else { print("Error retrieving comment") return } print("Comment reads: \"\(comment.message)\"") } ``` ## Create Comment To create a comment, call [`client.comments.create(itemId:itemType:message:fields:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/CommentsModule.html#/s:6BoxSDK14CommentsModuleC6create6itemId0F4Type7message6fields10completionySS_S2SSaySSGSgys6ResultOyAA7CommentCAA0A8SDKErrorCGctF) with the type and ID of the item to add a comment to, as well as the comment message. ``` client.comments.create( itemId: "11111", itemType: "file", message: "Thanks!" ) { (result: Result<Comment, BoxSDKError>) in guard case let .success(comment) = result else { print("Error creating comment") return } print("Added comment to \(comment.item.name): \"\(comment.message)\"") } ``` ## Update Comment To update a comment, call [`client.comments.update(commentId:message:fields:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/CommentsModule.html#/s:6BoxSDK14CommentsModuleC6update9commentId7message6fields10completionySS_SSSaySSGSgys6ResultOyAA7CommentCAA0A8SDKErrorCGctF) with the ID of the comment to update and the properties to update. ``` client.comments.update( commentId: "55555", message: "Updated message" ) { (result: Result<Comment, BoxSDKError>) in guard case let .success(comment) = result else { print("Error updating comment") return } print("Comment message updated") } ``` ## Delete Comment To delete a comment, call [`client.comments.delete(commentId:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/CommentsModule.html#/s:6BoxSDK14CommentsModuleC6delete9commentId10completionySS_ys6ResultOyytAA0A8SDKErrorCGctF) with the ID of the comment to delete. ``` client.comments.delete(commentId: "55555") { (result: Result<Void, BoxSDKError>) in guard case .success = result else { print("Error deleting comment") return } print("Comment deleted") } ``` --- ### Comments **Type:** page | **Section:** Additional Resources Comments Comment objects represent a user-created comment on a file. They can be added directly to a file. Get Comment Create Comment Update… # Comments Comment objects represent a user-created comment on a file. They can be added directly to a file. - [Get Comment](#get-comment) - [Create Comment](#create-comment) - [Update Comment](#update-comment) - [Delete Comment](#delete-comment) ## Get Comment To retrieve information about a comment, call [`client.comments.get(commentId:fields:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/CommentsModule.html#/s:6BoxSDK14CommentsModuleC3get9commentId6fields10completionySS_SaySSGSgys6ResultOyAA7CommentCAA0A8SDKErrorCGctF) with the ID of the comment. ``` client.comments.get(commentId: "55555") { (result: Result<Comment, BoxSDKError>) in guard case let .success(comment) = result else { print("Error retrieving comment") return } print("Comment reads: \"\(comment.message)\"") } ``` ## Create Comment To create a comment, call [`client.comments.create(itemId:itemType:message:fields:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/CommentsModule.html#/s:6BoxSDK14CommentsModuleC6create6itemId0F4Type7message6fields10completionySS_S2SSaySSGSgys6ResultOyAA7CommentCAA0A8SDKErrorCGctF) with the type and ID of the item to add a comment to, as well as the comment message. ``` client.comments.create( itemId: "11111", itemType: "file", message: "Thanks!" ) { (result: Result<Comment, BoxSDKError>) in guard case let .success(comment) = result else { print("Error creating comment") return } print("Added comment to \(comment.item.name): \"\(comment.message)\"") } ``` ## Update Comment To update a comment, call [`client.comments.update(commentId:message:fields:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/CommentsModule.html#/s:6BoxSDK14CommentsModuleC6update9commentId7message6fields10completionySS_SSSaySSGSgys6ResultOyAA7CommentCAA0A8SDKErrorCGctF) with the ID of the comment to update and the properties to update. ``` client.comments.update( commentId: "55555", message: "Updated message" ) { (result: Result<Comment, BoxSDKError>) in guard case let .success(comment) = result else { print("Error updating comment") return } print("Comment message updated") } ``` ## Delete Comment To delete a comment, call [`client.comments.delete(commentId:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/CommentsModule.html#/s:6BoxSDK14CommentsModuleC6delete9commentId10completionySS_ys6ResultOyytAA0A8SDKErrorCGctF) with the ID of the comment to delete. ``` client.comments.delete(commentId: "55555") { (result: Result<Void, BoxSDKError>) in guard case .success = result else { print("Error deleting comment") return } print("Comment deleted") } ``` --- ### CommentsManager **Type:** page | **Section:** Additional Resources CommentsManager List file comments Get comment Update comment Remove comment Create comment List file comments Retrieves a list of comments… # CommentsManager - [List file comments](#list-file-comments) - [Get comment](#get-comment) - [Update comment](#update-comment) - [Remove comment](#remove-comment) - [Create comment](#create-comment) ## List file comments Retrieves a list of comments for a file. This operation is performed by calling function `getFileComments`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-files-id-comments/). ``` await client.comments.getFileComments(fileId); ``` ### Arguments fileId `string` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" optionalsInput `GetFileCommentsOptionalsInput` ### Returns This function returns a value of type `Comments`. Returns a collection of comment objects. If there are no comments on this file an empty collection will be returned. ## Get comment Retrieves the message and metadata for a specific comment, as well as information on the user who created the comment. This operation is performed by calling function `getCommentById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-comments-id/). ``` await client.comments.getCommentById(newComment.id!); ``` ### Arguments commentId `string` - The ID of the comment. Example: "12345" optionalsInput `GetCommentByIdOptionalsInput` ### Returns This function returns a value of type `CommentFull`. Returns a full comment object. ## Update comment Update the message of a comment. This operation is performed by calling function `updateCommentById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-comments-id/). ``` await client.comments.updateCommentById(newReplyComment.id!, { requestBody: { message: newMessage } satisfies UpdateCommentByIdRequestBody, } satisfies UpdateCommentByIdOptionalsInput); ``` ### Arguments commentId `string` - The ID of the comment. Example: "12345" optionalsInput `UpdateCommentByIdOptionalsInput` ### Returns This function returns a value of type `CommentFull`. Returns the updated comment object. ## Remove comment Permanently deletes a comment. This operation is performed by calling function `deleteCommentById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-comments-id/). ``` await client.comments.deleteCommentById(newComment.id!); ``` ### Arguments commentId `string` - The ID of the comment. Example: "12345" optionalsInput `DeleteCommentByIdOptionalsInput` ### Returns This function returns a value of type `undefined`. Returns an empty response when the comment has been deleted. ## Create comment Adds a comment by the user to a specific file, or as a reply to an other comment. This operation is performed by calling function `createComment`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-comments/). ``` await client.comments.createComment({ message: message, item: { id: fileId, type: 'file' as CreateCommentRequestBodyItemTypeField, } satisfies CreateCommentRequestBodyItemField, } satisfies CreateCommentRequestBody); ``` ### Arguments requestBody `CreateCommentRequestBody` - Request body of createComment method optionalsInput `CreateCommentOptionalsInput` ### Returns This function returns a value of type `CommentFull`. Returns the newly created comment object. Not all available fields are returned by default. Use the [fields](#param-fields) query parameter to explicitly request any specific fields. --- ### CommentsManager **Type:** page | **Section:** Additional Resources CommentsManager List file comments Get comment Update comment Remove comment Create comment List file comments Retrieves a list of comments… # CommentsManager - [List file comments](#list-file-comments) - [Get comment](#get-comment) - [Update comment](#update-comment) - [Remove comment](#remove-comment) - [Create comment](#create-comment) ## List file comments Retrieves a list of comments for a file. This operation is performed by calling function `get_file_comments`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-files-id-comments/). ``` client.comments.get_file_comments(file_id) ``` ### Arguments file_id `str` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" fields `Optional[List[str]]` - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested. limit `Optional[int]` - The maximum number of items to return per page. offset `Optional[int]` - The offset of the item at which to begin the response. Queries with offset parameter value exceeding 10000 will be rejected with a 400 response. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `Comments`. Returns a collection of comment objects. If there are no comments on this file an empty collection will be returned. ## Get comment Retrieves the message and metadata for a specific comment, as well as information on the user who created the comment. This operation is performed by calling function `get_comment_by_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-comments-id/). ``` client.comments.get_comment_by_id(new_comment.id) ``` ### Arguments comment_id `str` - The ID of the comment. Example: "12345" fields `Optional[List[str]]` - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `CommentFull`. Returns a full comment object. ## Update comment Update the message of a comment. This operation is performed by calling function `update_comment_by_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-comments-id/). ``` client.comments.update_comment_by_id(new_reply_comment.id, message=new_message) ``` ### Arguments comment_id `str` - The ID of the comment. Example: "12345" message `Optional[str]` - The text of the comment to update. fields `Optional[List[str]]` - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `CommentFull`. Returns the updated comment object. ## Remove comment Permanently deletes a comment. This operation is performed by calling function `delete_comment_by_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-comments-id/). ``` client.comments.delete_comment_by_id(new_comment.id) ``` ### Arguments comment_id `str` - The ID of the comment. Example: "12345" extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `None`. Returns an empty response when the comment has been deleted. ## Create comment Adds a comment by the user to a specific file, or as a reply to an other comment. This operation is performed by calling function `create_comment`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-comments/). ``` client.comments.create_comment( message, CreateCommentItem(id=file_id, type=CreateCommentItemTypeField.FILE) ) ``` ### Arguments message `str` - The text of the comment. To mention a user, use the `tagged_message` parameter instead. tagged_message `Optional[str]` - The text of the comment, including `@[user_id:name]` somewhere in the message to mention another user, which will send them an email notification, letting them know they have been mentioned. The `user_id` is the target user's ID, where the `name` can be any custom phrase. In the Box UI this name will link to the user's profile. If you are not mentioning another user, use `message` instead. item `CreateCommentItem` - The item to attach the comment to. fields `Optional[List[str]]` - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `CommentFull`. Returns the newly created comment object. Not all available fields are returned by default. Use the [fields](#param-fields) query parameter to explicitly request any specific fields. --- ### Configuration **Type:** page | **Section:** Additional Resources Configuration The BoxSDKNode is the base object used to configure client. Configure Proxy To set up your proxy, add your proxy settings to… # Configuration The `BoxSDKNode` is the base object used to configure [client](https://ja.developer.box.com/143730815748e8d3be0de65a363b9f8b/client.md). ## Configure Proxy To set up your proxy, add your proxy settings to the `BoxSDK` object as shown below. You must include the proxy url, which should contain the `protocol`, `url`, and `port`, which in the case below are `http`, `sample.proxyurl.com` and `80` respectively. While the port, username and password are optional, the protocol and url are required. If your proxy does not require authentication, you can set the username and password to null or omit the parameters completely. The supported proxy protocols are `http`, `https`, `socks`, `socks4`, `socks4a`, `socks5`, `socks5h`, `pac+data`, `pac+file`, `pac+ftp`, `pac+http` and `pac+https`. ``` let sdk = new BoxSDK({ clientID: 'YOUR-CLIENT-ID', clientSecret: 'YOUR-CLIENT_SECRET', proxy: { url: 'http://sample.proxyurl.com:80', username: 'sample-username', password: 'sample-password', } }); ``` ## Configure how client retries calls and handles timeouts You can confugure how many retries, how long to wait between retries or upload timeout: ``` sdk = BoxSDKNode.getPreconfiguredInstance(APP_SETTINGS); var additonalParams = { numMaxRetries: 3, retryIntervalMS: 3000, uploadRequestTimeoutMS: 90000 }; sdk.configure(additonalParams); ``` The `numMaxRetries` sets the maximum number of retries when API request fails. Default value is `5`. The `retryIntervalMS` is used to calculate the wait time between retries. It is a number of miliseconds. SDK uses `Exponential backoff` algorithm to calculate the wait time. Default value is `2000` ms. The `uploadRequestTimeoutMS` sets the timeout after which an upload request is aborted Default value is `60000` ms. The `configure` method appends config values to existing configuration. So if you want you can configure sdk in several steps: ``` sdk = BoxSDKNode.getPreconfiguredInstance(APP_SETTINGS); sdk.configure({ retryIntervalMS: 3000 }); // you need to extend number of retires in some scenario sdk.configure({ numMaxRetries: 10 }); ``` ## Disable stream PassThrough for streaming responses By default the SDK uses `PassThrough` stream to handle streaming responses. It helps to support delayed reading of the response body, but in some cases it can cause memory leaks or not fully works. To disable `PassThrough` stream use the `disableStreamPassThrough` method: ``` sdk = BoxSDKNode.getPreconfiguredInstance(APP_SETTINGS); sdk.configure({ disableStreamPassThrough: true }); ``` ## Configure Base URL The Base Url is the URL that is used by the SDK to access Box. The default base URL are already defined for the `BoxSDKNode` but if you want to change default behaviour use the `configure` method on the sdk instance: ``` sdk = BoxSDKNode.getPreconfiguredInstance(APP_SETTINGS); var additonalParams = { apiRootURL: 'https://my.company.url.com', uploadAPIRootURL: 'https://my.company.url.com/upload', authorizeRootURL: 'https://my.company.url.com/authorize' }; sdk.configure(additonalParams); ``` The `apiRootURL` sets to what URL all API calls will be directed. Final URL used to access Box is built using `apiRootURL` and the API Version (`2.0`). For example by default the `apiRootURL` is set to `https://api.box.com` so after appending currently supported API version the URL is : `https://api.box.com/2.0`. The `uploadAPIRootURL` is used to configure the base URL used while uploading files. Final URL used to access Box is built using `uploadAPIRootURL` and API Version (`2.0`). For example by default the `uploadAPIRootURL` is set to `https://upload.box.com/api` so after appending currently supported API version the URL is : `https://upload.box.com/api/2.0`. The `authorizeRootURL` is used to configure the base URL used to obtain OAuth2 authorization tokens. --- ### Configuration **Type:** page | **Section:** Additional Resources Configuration Proxy configuration Custom proxy authenticator Example: NTLM authenticator Configure retries of calls and timeouts Maximum… # Configuration [Proxy configuration](#proxy-configuration) [Custom proxy authenticator](#custom-proxy-authenticator) - [Example: NTLM authenticator](#example-ntlm-authenticator) [Configure retries of calls and timeouts](#configure-retries-of-calls-and-timeouts) - [Maximum retries](#maximum-retries) - [Connection timeout](#connection-timeout) - [Read timeout](#read-timeout) [URLs configuration](#urls-configuration) - [Base URL](#base-url) - [Base Upload URL](#base-upload-url) - [Base App URL](#base-app-url) - [Token URL](#token-url-deprecated) - [Revoke URL](#revoke-url-deprecated) [SSL configuration](#ssl-configuration) [Instrumenation of OpenTelemetry](#instrumenation-of-opentelemetry) # Proxy configuration To set up proxy use [BoxApiConnection.setProxy](https://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxAPIConnection.html#setProxy-java.net.Proxy-) to set proxy address and [BoxApiConnection.setProxyBasicAuthentication](https://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxAPIConnection.html#setProxyBasicAuthentication-java.lang.String-java.lang.String-) to set username and password required by proxy: ``` BoxAPIConnection api=new BoxAPIConnection("access_token"); Proxy proxy = new Proxy(Proxy.Type.HTTP,new InetSocketAddress("proxy_url",8888)); // You can use any subclass of BoxAPIConnection api.setProxy(proxy); api.setProxyBasicAuthentication("proxyUsername", "proxyPassword"); ``` Proxy username and password will be used only if provided `SocketAddress` is an instance of `InetSocketAddress`. If you would like to use a custom `SocketAddress` you can provide your own `okhttp3.Authenticator` using [BoxApiConnection.setProxyAuthenticator(Authenticator)](https://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxAPIConnection.html#setProxyAuthenticator-okhttp3.Authenticator-) ## Custom proxy authenticator By using [BoxApiConnection.setProxyBasicAuthentication](https://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxAPIConnection.html#setProxyBasicAuthentication-java.lang.String-java.lang.String-) you can enable default proxy authenticator that handles only Basic authentication. But you can provide your own authenticator by using [BoxApiConnection.setProxyAuthenticator(Authenticator)](https://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxAPIConnection.html#setProxyAuthenticator-okhttp3.Authenticator-). To do that you will need to add a dependency to your project: ``` "com.squareup.okhttp3:okhttp:XXX" ``` Please match the version with what SDK is using by checking `build.gradle` and looking for entry `implementation "com.squareup.okhttp3:okhttp:"`. Now you can add an authenticator. by calling ``` BoxAPIConnection api = new BoxAPIConnection("access_token"); Proxy proxy = new Proxy(Proxy.Type.HTTP,new InetSocketAddress("proxy_url",8888)); api.setProxy(proxy); api.setProxyAuthenticator((route, response) -> response .request() .newBuilder() .addHeader("Proxy-Authorization", "My custom authenticator") .build() ); ``` ### Example: NTLM authenticator For example, you can add NTLM authorization. This is example NTLM authenticator that is using parts from Apache Http Client 5. ``` import okhttp3.Authenticator; import okhttp3.Request; import okhttp3.Response; import okhttp3.Route; import org.apache.hc.client5.http.impl.auth.NTLMEngineException; public class NTLMAuthenticator implements Authenticator { final NTLMEngineImpl engine = new NTLMEngineImpl(); private final String domain; private final String username; private final String password; private final String ntlmMsg1; public NTLMAuthenticator(String username, String password, String domain) { this.domain = domain; this.username = username; this.password = password; String localNtlmMsg1 = null; try { localNtlmMsg1 = engine.generateType1Msg(null, null); } catch (Exception e) { e.printStackTrace(); } ntlmMsg1 = localNtlmMsg1; } @Override public Request authenticate(Route route, Response response) { if(response.code() == 407 && "Proxy authorization required".equals(response.message())) { String ntlmChallenge = response.headers("Proxy-Authenticate") .stream() .filter(h -> h.startsWith("NTLM ")) .findFirst().orElse(""); if(ntlmChallenge.length() > 5) { try { String ntlmMsg3 = engine.generateType3Msg(username, password.toCharArray(), domain, "ok-http-example-ntlm", ntlmChallenge.substring(5)); return response.request().newBuilder().header("proxy-Authorization", "NTLM " + ntlmMsg3).build(); } catch (NTLMEngineException e) { throw new RuntimeException(e); } } return response.request().newBuilder().header("proxy-Authorization", "NTLM " + ntlmMsg1).build(); } return response.request(); } } ``` The `NTLMEngineImpl` could be created by using Apache implementation that can be found [here](https://github.com/apache/httpcomponents-client/blob/master/httpclient5/src/main/java/org/apache/hc/client5/http/impl/auth/NTLMEngineImpl.java). You can add a dependency to `org.apache.httpcomponents.client5:httpclient5:5.1.3`. Copy the `NTLMEngineImpl` class and add it to your source. Now you can use custom NTML Authenticator in your `BoxAPIConnection`: ``` BoxAPIConnection api = new BoxAPIConnection("access_token"); Proxy proxy = new Proxy(Proxy.Type.HTTP,new InetSocketAddress("proxy_url",8888)); api.setProxy(proxy); api.setProxyAuthenticator(new NTLMAuthenticator("some proxy username", "some proxy password", "proxy workgroup")); ``` # Configure retries of calls and timeouts SDK can retry failed calls when: - failed writting request body when recieved HTTP response code: - 429 - rate limit exceeded - 5XX - internal server error - 400 error with error that `exp` claim has expired. This usially means there is a clock skew. SDK is using exponnetial strategy to calculate time between retries. If response contains `Retry-After` header its value will be used as a wait time between calls. You can check details in `com.box.sdk.BoxAPIRequest.send(com.box.sdk.ProgressListener)` method. ## Maximum retries To configure how many times API will retry calls use [BoxApiConnection.setMaxRetryAttempts](https://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxAPIConnection.html#setMaxRetryAttempts-int-): ``` // You can use any subclass of BoxAPIConnection api.setMaxRetryAttempts(10); ``` default value for retry attempts is `5`. ## Connection timeout To set up how log (in milliseconds) API waits to establish connection use [BoxApiConnection.setConnectTimeout](https://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxAPIConnection.html#setConnectTimeout-int-): ``` // You can use any subclass of BoxAPIConnection int connectionTimeout = 100; // timeout in milliseconds api.setConnectTimeout(connectionTimeout); ``` default value is `0` which mean API waits forever to establish connection. ## Read timeout To set up how log (in milliseconds) API waits to read data from connection use [BoxApiConnection.setReadTimeout](https://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxAPIConnection.html#setReadTimeout-int-): ``` // You can use any subclass of BoxAPIConnection int readTimeout = 100; // timeout in milliseconds api.setReadTimeout(readTimeout); ``` default value is `0` which mean API waits forever to read data from connection. # URLs configuration ### Base URL The default base URL used for making API calls to Box can be changed by calling `BoxAPIConnection#setBaseURL(String)` method on `BoxApiConnection`. Default value is `https://api.box.com/`. ``` BoxAPIConnection api = new BoxAPIConnection("YOUR-DEVELOPER-TOKEN"); api.setBaseURL("https://example.com"); String baseUrl = api.getBaseURL(); // will produce "https://example.com/2.0/" ``` Setting Base URL changes the Token and Revoke URL as well: ``` BoxAPIConnection api = new BoxAPIConnection("YOUR-DEVELOPER-TOKEN"); api.setBaseURL("https://example.com"); String baseUrl = api.getBaseURL(); // will produce "https://example.com/2.0/" String tokenUrl = api.getRevokeURL(); // will produce "https://example.com/oauth2/revoke" String revokeUrl = api.getTokenURL(); // will produce "https://example.com/oauth2/token" ``` ### Base Upload URL The default URL used for uploads can be changed by calling `BoxAPIConnection#setBaseUploadURL(String)` method on `BoxApiConnection`. Default value is `https://upload.box.com/api/`. ``` BoxAPIConnection api = new BoxAPIConnection("YOUR-DEVELOPER-TOKEN"); api.setBaseUploadURL("https://upload.example.com"); api.getBaseUploadURL(); // will produce "https://upload.example.com/2.0/" ``` ### Base App URL The default base app URL can be changed by calling `BoxAPIConnection#setBaseAppUrl()` method on `BoxApiConnection`. Default value is [https://app.box.com](https://app.box.com). ``` BoxAPIConnection api = new BoxAPIConnection("YOUR-DEVELOPER-TOKEN"); api.setBaseAppUrl("https://example.app.com"); api.getBaseAppUrl(); // will produce "https://app.example.com" ``` ### Token URL (deprecated) The default URL used for getting token can be changed by calling `setTokenURL()` method on `BoxApiConnection`. Default value is [https://api.box.com/oauth2/token](https://api.box.com/oauth2/token). This method is deprecated. Use `BoxAPIConnection#setBaseURL(String)` instead. ``` BoxAPIConnection api = new BoxAPIConnection("YOUR-DEVELOPER-TOKEN"); api.setTokenURL("https://example.com/token"); ``` If you use `setTokenUrl` this URL will be used over the one coming from `setBaseUrl` when doing authentication. ### Revoke URL (deprecated) The default URL used for invalidating token can be changed by calling `setRevokeURL()` method on `BoxApiConnection`. Default value is [https://api.box.com/oauth2/revoke](https://api.box.com/oauth2/revoke). This method is deprecated. Use `BoxAPIConnection#setBaseURL(String)` instead. ``` BoxAPIConnection api = new BoxAPIConnection("YOUR-DEVELOPER-TOKEN"); api.setRevokeURL("https://example.com/revoke"); ``` If you use `setRevokeUrl` this URL will be used over the one coming from`setBaseUrl` when doing authentication. # SSL configuration You can override default settings used to verify SSL certificates. This can be used to allow using self-signed certificates. For example: ``` BoxAPIConnection api = new BoxAPIConnection(...); // to allow self-signed certificates X509TrustManager trustManager = new X509TrustManager() { @Override public void checkClientTrusted(java.security.cert.X509Certificate[] chain, String authType) { } @Override public void checkServerTrusted(java.security.cert.X509Certificate[] chain, String authType) { } @Override public java.security.cert.X509Certificate[] getAcceptedIssuers() { return new java.security.cert.X509Certificate[]{}; } }; // to allow self-signed certificates created for localhost HostnameVerifier hostnameVerifier = (hostname, session) -> true; api.configureSslCertificatesValidation(trustManager, hostnameVerifier); ``` If you just need to provide trust manager use `BoxAPIConnection.DEFAULT_HOSTNAME_VERIFIER` as a hostname verifier. The same goes for hostname verifier. If you need just to provide it use `BoxAPIConnection.DEFAULT_TRUST_MANAGER` as a trust manager. Example: ``` BoxAPIConnection api = new BoxAPIConnection(...); X509TrustManager trustManager = ... api.configureSslCertificatesValidation(trustManager, BoxAPIConnection.DEFAULT_HOSTNAME_VERIFIER); ``` # Instrumenation of OpenTelemetry OpenTelemetry is an observability framework and toolkit for creating and managing telemetry data, such as traces, metrics, and logs. The Box Java SDK can be instrumented with OpenTelemetry to collect telemetry data about the requests made by the SDK. To start, add the [opentelemetry-okhttp-3.0](https://mvnrepository.com/artifact/io.opentelemetry.instrumentation/opentelemetry-okhttp-3.0) dependency to your project. Next, create a custom class that extends BoxAPIConnection and integrates telemetry in the overridden `createNewCall` method. Here's an example implementation: ``` public class BoxAPIConnectionWithTelemetry extends BoxAPIConnection { private OkHttpTelemetry telemetry; public BoxAPIConnectionWithTelemetry(String accessToken) { super(accessToken); } /** * Add required constructors */ public void setTelemetry(OpenTelemetry openTelemetry) { this.telemetry = OkHttpTelemetry.builder(openTelemetry).build(); } protected Call createNewCall(OkHttpClient httpClient, Request request) { return this.telemetry.newCallFactory(httpClient).newCall(request); } } ``` Please note that you should not modify either `httpClient` or `request` parameters in the createNewCall method. Altering these parameters can discard the BoxAPIConnection configuration and lead to unexpected behavior. --- ### Configuration **Type:** page | **Section:** Additional Resources Configuration The Python SDK has helpful custom config that you can set for a variety of use cases. Proxy Unauthenticated Proxy Basic… # Configuration The Python SDK has helpful custom config that you can set for a variety of use cases. [Proxy](#proxy) - [Unauthenticated Proxy](#unauthenticated-proxy) - [Basic Authentication Proxy](#basic-authentication-proxy) [Configure URLs](#configure-urls) - [Base URL](#base-url) - [OAUTH2 URLs](#oauth2-urls) - [Upload URL](#upload-url) [Max retry attmepts](#max-retry-attmepts) ## Proxy ### Unauthenticated Proxy In order to set up configuration for basic proxy with the Python SDK, simply specify the proxy address for the `Proxy.URL` field. ``` from boxsdk.config import Proxy Proxy.URL = 'http://example-proxy-address.com' ``` ### Basic Authentication Proxy The Python SDK also lets you set an authenticated proxy. To do this, specify the `user` and `password` fields and pass set that on the `Proxy.AUTH` field. ``` from boxsdk.config import Proxy Proxy.AUTH = { 'user': 'test_user', 'password': 'test_password', } ``` ## URLs configuration ### Base URL The default base URL used for making API calls to Box can be changed by setting the value of the `API.BASE_API_URL` field. ``` from boxsdk.config import API API.BASE_API_URL = 'https://new-base-url.com' ``` ### OAUTH2 URLs The default URLs used to authorize a user and obtain OAuth2 authorization tokens can be modified by overwriting `API.OAUTH2_API_URL` and `API.OAUTH2_AUTHORIZE_URL` constants. ``` from boxsdk.config import API API.OAUTH2_API_URL = 'https://my-company.com/oauth2' API.OAUTH2_AUTHORIZE_URL = 'https://my-company.com/authorize' ``` ### Upload URL The default URL used when uploading files to Box can be changed by assigning a new value to the `API.UPLOAD_URL` field. If this variable is ever changed from default value, the SDK will alwayse use this URL to upload files to Box, even if `use_upload_session_urls` is set to `True` while creating an upload session for a chunked upload. ``` from boxsdk.config import API API.UPLOAD_URL = 'https://my-company-upload-url.com' ``` ## Max retry attmepts The default maximum number of retries in case of failed API call is 5 (usually 202, 429 and >= 500 response codes are retried). To change this number you can set `API.MAX_RETRY_ATTEMPTS` field. ``` from boxsdk.config import API API.MAX_RETRY_ATTEMPTS = 6 ``` --- ### Configuration **Type:** page | **Section:** Additional Resources Configuration URLs configuration Base URL Account URL Upload URL Timeout Proxy Supress notifications Make API calls As-User Custom private… # Configuration [URLs configuration](#urls-configuration) - [Base URL](#base-url) - [Account URL](#account-url) - [Upload URL](#upload-url) [Timeout](#timeout) [Proxy](#proxy) [Supress notifications](#supress-notifications) [Make API calls As-User](#make-api-calls-as-user) [Custom private key decryptor for JWT](#custom-private-key-decryptor-for-jwt) ## URLs configuration ### Base URL The default base URL used for making API calls to Box can be changed by calling `SetBoxApiHostUri()` method. Default value is [https://api.box.com/](https://api.box.com/). ``` var customUri = new Uri("https://custom-api-url.com"); var boxConfig = new BoxConfigBuilder("clientID", "clientSecret") .SetBoxApiHostUri(customUri) .Build(); ``` ### Account URL The default account URL used to create OAuth authorization URL can be changed by calling `SetBoxAccountApiHostUri()` method. Default value is [https://account.box.com/api/](https://account.box.com/api/). ``` var customUri = new Uri("https://custom-account-url.com"); var boxConfig = new BoxConfigBuilder("clientID", "clientSecret") .SetBoxAccountApiHostUri(customUri) .Build(); ``` ### Upload URL The default URL used for uploads can be changed by calling `SetBoxUploadApiUri()` method. Default value is [https://upload.box.com/api/](https://upload.box.com/api/). ``` var customUri = new Uri("https://custom-upload-url.com"); var boxConfig = new BoxConfigBuilder("clientID", "clientSecret") .SetBoxUploadApiUri(customUri) .Build(); ``` ## Timeout The default request timeout can be changed by calling `SetTimeout()` method. Default timeout is 100 seconds. ``` var timeout = TimeSpan.FromSeconds(200); var boxConfig = new BoxConfigBuilder("clientID", "clientSecret") .SetTimeout(timeout) .Build(); ``` ## Proxy `BoxClient` uses .NET `WebProxy` class to support Proxy. To use proxy you need to call `SetWebProxy()` when building configuration. ``` var proxy = new WebProxy { Address = new Uri("https://my-proxy.com"), Credentials = new NetworkCredential { Domain = "myDomain", UserName = "username", Password = "password" } }; var config = new BoxConfigBuilder("clientID", "clientSecret") .SetWebProxy(proxy) .Build(); ``` ## Supress Notifications If you are making administrative API calls (that is, your application has “Manage an Enterprise” scope, and the user making the API call is a co-admin with the correct "Edit settings for your company" permission) then you can suppress both email and webhook notifications. ``` var config = new BoxConfigBuilder("clientID", "clientSecret", "redirect_uri").Build(); var auth = new OAuthSession("access_token", "refresh_token", 3600, "bearer"); var adminClient = new BoxClient(config, auth, suppressNotifications: true); ``` ## Make API calls As-User If you have an admin token with appropriate permissions, you can make API calls in the context of a managed user. In order to do this you must request Box.com to activate As-User functionality for your API key (see developer site for instructions). ``` var config = new BoxConfigBuilder("clientID", "clientSecret", "redirect_uri").Build(); var auth = new OAuthSession("access_token", "refresh_token", 3600, "bearer"); var userId = "12345678" var userClient = new BoxClient(config, auth, asUser: userId); //returns root folder items for the user with ID '12345678' var items = await userClient.FoldersManager.GetFolderItemsAsync("0", 500); ``` ## Custom private key decryptor for JWT To generate a Json Web Signature used for retrieving tokens in the JWT authentication method, the SDK decrypts an encrypted private key passed in the config. The SDK implementation currently uses `BouncyCastle.Cryptography` library. If you want to use a different implementation (e.g. for FIPS compliance reasons) you need provide implementation for `IPrivateKeyDecryptor` and pass it during creation of `BoxJwtAuth` object. ``` public class MyPrivateKeyDecryptor : IPrivateKeyDecryptor { public RSA DecryptPrivateKey(string encryptedPrivateKey, string passphrase) { // implementation goes here } } var boxJwtAuth = new BoxJWTAuth(boxConfig, new BoxService(new HttpRequestHandler(boxConfig.WebProxy, boxConfig.Timeout)), new MyPrivateKeyDecryptor()); var boxClient = new BoxClient(boxConfig, boxJwtAuth); ``` --- ### Configuration **Type:** page | **Section:** Additional Resources Configuration The iOS SDK provides dedicated method, that helps you to customize SDK configuration. All you need is to call sdk… # Configuration The iOS SDK provides dedicated method, that helps you to customize SDK configuration. All you need is to call [`sdk.updateConfiguration(apiBaseURL:uploadApiBaseURL:oauth2AuthorizeURL:maxRetryAttempts:tokenRefreshThreshold:consoleLogDestination:fileLogDestination:clientAnalyticsInfo:)`](https://opensource.box.com/box-ios-sdk/Classes/BoxSDK.html#/s:6BoxSDKAAC19updateConfiguration10apiBaseURL09uploadApifG0015oauth2AuthorizeG016maxRetryAttempts21tokenRefreshThreshold21consoleLogDestination04filesT019clientAnalyticsInfoy10Foundation0G0VSg_A2OSiSgSdSgAA07ConsolesT0CSgAA04FilesT0CSgAA06ClientwX0VSgtKF) method on `BoxSDK` instance with correct parameters, right after creating a `BoxSDK` instance, but before creating a `BoxClient`. [URLs configuration](#urls-configuration) - [Api Base URL](#api-base-url) - [Upload Api Base URL](#upload-api-base-url) - [OAuth Authorize URL](#oauth-authorize-url) [Max retry attempts](#max-retry-attempts) [Token Refresh Threshold](#token-refresh-threshold) [Logging](#logging) - [Console Logging](#console-logging) - [File Logging](#file-logging) [Client Analytics Info](#client-analytics-info) ## URLs configuration The `sdk.updateConfiguration()` method allows you to change base URLs from defaults to the ones you will specify. Just call this method on the `BoxSDK` instance with any of these parameters: ``` do { try sdk.updateConfiguration( apiBaseURL: URL(string: "https://my-company.com"), uploadApiBaseURL: URL(string: "https://my-company.com/upload"), oauth2AuthorizeURL: URL(string: "https://my-company.com/oauth2") ) } catch { print("An error occurred \(error)") } ``` The `updateConfiguration()` will throw an exception if any of passed URLs will be invalid. ### Api Base URL The `apiBaseURL` sets URL to which all API calls will be directed. Final URL that is used to access Box is built using `apiBaseURL` and the API Version (`2.0`). For example, by default the `apiBaseURL` is set to `https://api.box.com`, so after appending the currently supported API version the URL is : `https://api.box.com/2.0`. ### Upload Api Base URL The `uploadApiBaseURL` is used to configure the base URL used when uploading files. Final URL used to access Box is built using `uploadApiBaseURL`, the `/api/` path and API Version (`2.0`). For example, by default the `uploadApiBaseURL` is set to `https://upload.box.com`, so after appending `/api/` path and the currently supported API version the URL is : `https://upload.box.com/api/2.0`. ### OAuth Authorize URL The `oauth2AuthorizeURL` is an URL for the OAuth2 authorization page, where users are redirected to enter their credentials to obtain OAuth2 authorization tokens. By default is set to `https://account.box.com/api/oauth2/authorize`. ## Max retry attempts The default maximum number of retries in case of failed API call is `5`. To change this please call `sdk.updateConfiguration()` method with `maxRetryAttempts` parameter and your new value e.g. `10`: ``` do { try sdk.updateConfiguration( maxRetryAttempts: 10 ) } catch { print("An error occurred \(error)") } ``` ## Token Refresh Threshold You can specify how many seconds before the token expires, it should be refreshed. By default it is set to `60` seconds. To change this value, please call `sdk.updateConfiguration()` method with `tokenRefreshThreshold` parameter and your new value, e.g. `120`: ``` do { try sdk.updateConfiguration( tokenRefreshThreshold: 120 ) } catch { print("An error occurred \(error)") } ``` ## Logging ### Console Logging There could be a situation when the default console Box SDK logging is not sufficient for your needs. You can then create your own class that inherits form [`ConsoleLogDestination`](https://opensource.box.com/box-ios-sdk/Classes/ConsoleLogDestination.html) class and you can overwrite `write` method for you needs (as this is a method that writes logs into the console). If you named this class e.g. `CustomConsoleLogDestination` then call: ``` do { try sdk.updateConfiguration( consoleLogDestination: CustomConsoleLogDestination() ) } catch { print("An error occurred \(error)") } ``` ### File Logging By default, logging to a file is disabled in the Box SDK. To turn it on, you just need to pass the `fileLogDestination` parameter to the new instance of [`FileLogDestination`](https://opensource.box.com/box-ios-sdk/Classes/FileLogDestination.html). To create a new instance of `FileLogDestination`, you need to pass the `fileURL` parameter, which is the file path URL to write the logs to. ``` let fileLoggerURL = FileManager.default.urls(for: .documentDirectory, in: .allDomainsMask).first!.appendingPathComponent("box_sdk_log.txt") do { try sdk.updateConfiguration( fileLogDestination: FileLogDestination(fileURL: fileLoggerURL) ) } catch { print("An error occurred \(error)") } ``` ## Client Analytics Info If for some reasons you want to track your application usage on server, there is a way for that. You just need to create an instance of [`ClientAnalyticsInfo`](https://opensource.box.com/box-ios-sdk/Structs/ClientAnalyticsInfo.html) struct with `appName` and `appVersion` parameters related to your app and pass it to `sdk.updateConfiguration()` method. Those values will be added to `X-Box-UA` request header after `agent` and `env` values. Take a look at the following code: ``` let analyticsInfo = ClientAnalyticsInfo(appName: "MyCustomApp", appVersion: "1.2.0") do { try sdk.updateConfiguration(clientAnalyticsInfo: analyticsInfo) } catch { print("An error occurred \(error)") } ``` After this change, the `client=MyCustomApp/1.2.0` will be appended to the `X-Box-UA` request header value. If you run this code on `iPhone 11 Pro Max` and using SDK version `5.2.0` the final value for `X-Box-UA` header will be `agent=box-swift-sdk/5.2.0; env=iPhone Simulator/15.2; client=MyCustomApp/1.2.0`. --- ### Configuration **Type:** page | **Section:** Additional Resources Configuration The iOS SDK provides dedicated method, that helps you to customize SDK configuration. All you need is to call sdk… # Configuration The iOS SDK provides dedicated method, that helps you to customize SDK configuration. All you need is to call [`sdk.updateConfiguration(apiBaseURL:uploadApiBaseURL:oauth2AuthorizeURL:maxRetryAttempts:tokenRefreshThreshold:consoleLogDestination:fileLogDestination:clientAnalyticsInfo:)`](https://opensource.box.com/box-ios-sdk/Classes/BoxSDK.html#/s:6BoxSDKAAC19updateConfiguration10apiBaseURL09uploadApifG0015oauth2AuthorizeG016maxRetryAttempts21tokenRefreshThreshold21consoleLogDestination04filesT019clientAnalyticsInfoy10Foundation0G0VSg_A2OSiSgSdSgAA07ConsolesT0CSgAA04FilesT0CSgAA06ClientwX0VSgtKF) method on `BoxSDK` instance with correct parameters, right after creating a `BoxSDK` instance, but before creating a `BoxClient`. [URLs configuration](#urls-configuration) - [Api Base URL](#api-base-url) - [Upload Api Base URL](#upload-api-base-url) - [OAuth Authorize URL](#oauth-authorize-url) [Max retry attempts](#max-retry-attempts) [Token Refresh Threshold](#token-refresh-threshold) [Logging](#logging) - [Console Logging](#console-logging) - [File Logging](#file-logging) [Client Analytics Info](#client-analytics-info) ## URLs configuration The `sdk.updateConfiguration()` method allows you to change base URLs from defaults to the ones you will specify. Just call this method on the `BoxSDK` instance with any of these parameters: ``` do { try sdk.updateConfiguration( apiBaseURL: URL(string: "https://my-company.com"), uploadApiBaseURL: URL(string: "https://my-company.com/upload"), oauth2AuthorizeURL: URL(string: "https://my-company.com/oauth2") ) } catch { print("An error occurred \(error)") } ``` The `updateConfiguration()` will throw an exception if any of passed URLs will be invalid. ### Api Base URL The `apiBaseURL` sets URL to which all API calls will be directed. Final URL that is used to access Box is built using `apiBaseURL` and the API Version (`2.0`). For example, by default the `apiBaseURL` is set to `https://api.box.com`, so after appending the currently supported API version the URL is : `https://api.box.com/2.0`. ### Upload Api Base URL The `uploadApiBaseURL` is used to configure the base URL used when uploading files. Final URL used to access Box is built using `uploadApiBaseURL`, the `/api/` path and API Version (`2.0`). For example, by default the `uploadApiBaseURL` is set to `https://upload.box.com`, so after appending `/api/` path and the currently supported API version the URL is : `https://upload.box.com/api/2.0`. ### OAuth Authorize URL The `oauth2AuthorizeURL` is an URL for the OAuth2 authorization page, where users are redirected to enter their credentials to obtain OAuth2 authorization tokens. By default is set to `https://account.box.com/api/oauth2/authorize`. ## Max retry attempts The default maximum number of retries in case of failed API call is `5`. To change this please call `sdk.updateConfiguration()` method with `maxRetryAttempts` parameter and your new value e.g. `10`: ``` do { try sdk.updateConfiguration( maxRetryAttempts: 10 ) } catch { print("An error occurred \(error)") } ``` ## Token Refresh Threshold You can specify how many seconds before the token expires, it should be refreshed. By default it is set to `60` seconds. To change this value, please call `sdk.updateConfiguration()` method with `tokenRefreshThreshold` parameter and your new value, e.g. `120`: ``` do { try sdk.updateConfiguration( tokenRefreshThreshold: 120 ) } catch { print("An error occurred \(error)") } ``` ## Logging ### Console Logging There could be a situation when the default console Box SDK logging is not sufficient for your needs. You can then create your own class that inherits form [`ConsoleLogDestination`](https://opensource.box.com/box-ios-sdk/Classes/ConsoleLogDestination.html) class and you can overwrite `write` method for you needs (as this is a method that writes logs into the console). If you named this class e.g. `CustomConsoleLogDestination` then call: ``` do { try sdk.updateConfiguration( consoleLogDestination: CustomConsoleLogDestination() ) } catch { print("An error occurred \(error)") } ``` ### File Logging By default, logging to a file is disabled in the Box SDK. To turn it on, you just need to pass the `fileLogDestination` parameter to the new instance of [`FileLogDestination`](https://opensource.box.com/box-ios-sdk/Classes/FileLogDestination.html). To create a new instance of `FileLogDestination`, you need to pass the `fileURL` parameter, which is the file path URL to write the logs to. ``` let fileLoggerURL = FileManager.default.urls(for: .documentDirectory, in: .allDomainsMask).first!.appendingPathComponent("box_sdk_log.txt") do { try sdk.updateConfiguration( fileLogDestination: FileLogDestination(fileURL: fileLoggerURL) ) } catch { print("An error occurred \(error)") } ``` ## Client Analytics Info If for some reasons you want to track your application usage on server, there is a way for that. You just need to create an instance of [`ClientAnalyticsInfo`](https://opensource.box.com/box-ios-sdk/Structs/ClientAnalyticsInfo.html) struct with `appName` and `appVersion` parameters related to your app and pass it to `sdk.updateConfiguration()` method. Those values will be added to `X-Box-UA` request header after `agent` and `env` values. Take a look at the following code: ``` let analyticsInfo = ClientAnalyticsInfo(appName: "MyCustomApp", appVersion: "1.2.0") do { try sdk.updateConfiguration(clientAnalyticsInfo: analyticsInfo) } catch { print("An error occurred \(error)") } ``` After this change, the `client=MyCustomApp/1.2.0` will be appended to the `X-Box-UA` request header value. If you run this code on `iPhone 11 Pro Max` and using SDK version `5.2.0` the final value for `X-Box-UA` header will be `agent=box-swift-sdk/5.2.0; env=iPhone Simulator/15.2; client=MyCustomApp/1.2.0`. --- ### Configuration **Type:** page | **Section:** Additional Resources Configuration Max retry attempts Custom retry strategy Max retry attempts The default maximum number of retries in case of failed API call… # Configuration - [Max retry attempts](#max-retry-attempts) - [Custom retry strategy](#custom-retry-strategy) ## Max retry attempts The default maximum number of retries in case of failed API call is 5. To change this number you should initialize `BoxRetryStrategy` with the new value and pass it to `NetworkSession`. ``` const auth = new BoxDeveloperTokenAuth({ token: 'DEVELOPER_TOKEN_GOES_HERE' }); const networkSession = new NetworkSession({ retryStrategy: new BoxRetryStrategy({ maxAttempts: 6 }), }); const client = new BoxClient({ auth, networkSession }); ``` ## Custom retry strategy You can also implement your own retry strategy by subclassing `RetryStrategy` and overriding `shouldRetry` and `retryAfter` methods. This example shows how to set custom strategy that retries on 5xx status codes and waits 1 second between retries. ``` export class CustomRetryStrategy implements RetryStrategy { async shouldRetry( fetchOptions: FetchOptions, fetchResponse: FetchResponse, attemptNumber: number, ): Promise<boolean> { return false; } retryAfter( fetchOptions: FetchOptions, fetchResponse: FetchResponse, attemptNumber: number, ): number { return 1.0; } } const auth = new BoxDeveloperTokenAuth({ token: 'DEVELOPER_TOKEN_GOES_HERE' }); const networkSession = new NetworkSession({ retryStrategy: new CustomRetryStrategy(), }); const client = new BoxClient({ auth, networkSession }); ``` --- ### Configuration **Type:** page | **Section:** Additional Resources Configuration Max retry attempts Custom retry strategy Max retry attempts The default maximum number of retries in case of failed API call… # Configuration - [Max retry attempts](#max-retry-attempts) - [Custom retry strategy](#custom-retry-strategy) ## Max retry attempts The default maximum number of retries in case of failed API call is 5. To change this number you should initialize `BoxRetryStrategy` with the new value and pass it to `NetworkSession`. ``` from box_sdk_gen import ( BoxClient, BoxDeveloperTokenAuth, NetworkSession, BoxRetryStrategy, ) auth = BoxDeveloperTokenAuth(token="DEVELOPER_TOKEN_GOES_HERE") network_session = NetworkSession(retry_strategy=BoxRetryStrategy(max_attempts=6)) client = BoxClient(auth=auth, network_session=network_session) ``` ## Custom retry strategy You can also implement your own retry strategy by subclassing `RetryStrategy` and overriding `should_retry` and `retry_after` methods. This example shows how to set custom strategy that retries on 5xx status codes and waits 1 second between retries. ``` from box_sdk_gen import ( BoxClient, BoxDeveloperTokenAuth, NetworkSession, RetryStrategy, FetchOptions, FetchResponse, ) class CustomRetryStrategy(RetryStrategy): def should_retry( self, fetch_options: FetchOptions, fetch_response: FetchResponse, attempt_number: int, ) -> bool: return fetch_response.status_code >= 500 def retry_after( self, fetch_options: FetchOptions, fetch_response: FetchResponse, attempt_number: int, ) -> float: return 1.0 auth = BoxDeveloperTokenAuth(token="DEVELOPER_TOKEN_GOES_HERE") network_session = NetworkSession(retry_strategy=CustomRetryStrategy()) client = BoxClient(auth=auth, network_session=network_session) ``` --- ### Constructing API Calls Manually **Type:** page | **Section:** Additional Resources Constructing API Calls Manually The SDK also exposes low-level request methods for constructing your own API calls. These can be useful for… # Constructing API Calls Manually The SDK also exposes low-level request methods for constructing your own API calls. These can be useful for adding your own API calls that aren't yet explicitly supported by the SDK. To make a custom API call you need to provide implementation for `BoxResourceManager`. ``` public class BoxFolderHintsManager : BoxResourceManager { public BoxFolderHintsManager(IBoxConfig config, IBoxService service, IBoxConverter converter, IAuthRepository auth, string asUser = null, bool? suppressNotifications = null) : base(config, service, converter, auth, asUser, suppressNotifications) { } public async Task<MyCustomReturnObject> GetFolderItemsWithHintsAsync(string folderId, string xRepHints) { BoxRequest request = new BoxRequest(_config.FoldersEndpointUri, string.Format(Constants.ItemsPathString, folderId)) .Method(RequestMethod.Get) .Param(ParamFields, "representations") .Header(Constants.RequestParameters.XRepHints, xRepHints); return await ToResponseAsync<MyCustomReturnObject>(request).ConfigureAwait(false); } } ``` You need to first register your custom `BoxResourceManager`, then you can use it as any other SDK manager. ``` var client = boxJWT.UserClient(userToken, userId); client.AddResourcePlugin<BoxFolderHintsManager>(); string folderId = "11111"; string xRepHints = "[jpg?dimensions=32x32][jpg?dimensions=94x94]"; var boxFolderHintsManager = client.ResourcePlugins.Get<BoxFolderHintsManager>(); var response = await boxFolderHintsManager.GetFolderItemsWithHintsAsync(folderId, xRepHints); ``` --- ### Contributing **Type:** page | **Section:** Additional Resources Contributing All contributions are welcome to this project. Contributor License Agreement Before a contribution can be merged into this… # Contributing All contributions are welcome to this project. ## Contributor License Agreement Before a contribution can be merged into this project, please fill out the Contributor License Agreement (CLA) located at: [http://opensource.box.com/cla](http://opensource.box.com/cla) To learn more about CLAs and why they are important to open source projects, please see the [Wikipedia entry](http://en.wikipedia.org/wiki/Contributor_License_Agreement). ## Code of Conduct This project adheres to the [Box Open Code of Conduct](http://opensource.box.com/code-of-conduct/). By participating, you are expected to uphold this code. ## How to contribute - **File an issue** - if you found a bug, want to request an enhancement, or want to implement something (bug fix or feature). - **Send a pull request** - if you want to contribute code. Please be sure to file an issue first. ## Pull request best practices We want to accept your pull requests. Please follow these steps: ### Step 1: File an issue Before writing any code, please file an issue stating the problem you want to solve or the feature you want to implement. This allows us to give you feedback before you spend any time writing code. There may be a known limitation that can't be addressed, or a bug that has already been fixed in a different way. The issue allows us to communicate and figure out if it's worth your time to write a bunch of code for the project. ### Step 2: Fork this repository in GitHub This will create your own copy of our repository. ### Step 3: Add the upstream source The upstream source is the project under the Box organization on GitHub. To add an upstream source for this project, type: ``` git remote add upstream git@github.com:box/box-node-sdk.git ``` This will come in useful later. ### Step 4: Create a feature branch Create a branch with a descriptive name, such as `add-search`. ### Step 5: Push your feature branch to your fork We use [semantic-versioning](https://semver.org/) and the [conventional commit message format](https://www.conventionalcommits.org/en/v1.0.0/). Keep a separate feature branch for each issue you want to address. As you develop code, continue to push code to your remote feature branch. Example: ``` tag: short description longer description here if necessary. ``` The message summary should be a one-sentence description of the change, and it must be 72 characters in length or shorter. For a list of tags, please [click here](https://github.com/commitizen/conventional-commit-types/blob/master/index.json). Note that you must include the `!` for breaking changes (e.g. `feat!: removed old apis`). Shown below are examples of the release type that will be done based on a commit message. #### Commit Types "Semantic versioning" means that changes to the version number of the package (e.g. `3.42.11` to `3.43.0`) are done according to rules that indicate how the change will affect consumers. Read more on the [semver page](https://semver.org/). The version number is broken into 3 positions — `Major.Minor.Patch`. In semantic release terms, changes to the numbers follow `Breaking.Feature.Fix`. The `release` script parses commit messages and decides what type of release to make based on the types of commits detected since the last release. The rules for commit types are: - Anything that changes or removes an API, option, or output format is a breaking change denoted by `!`. - Anything that adds new functionality in a backwards-compatible way is a feature (`feat`). Consumers have to upgrade to the new version to use the feature, but nothing will break if they do so. - Bugfixes (`fix`) for existing behavior are a patch. Consumers don't have to do anything but upgrade. - Other prefixes, such as `docs` or `chore`, don't trigger releases and don't appear in the changelog. These tags signal that there are **no external changes to *any* APIs** (including non-breaking ones). In most cases, commits will be a `feat` or `fix`. Make sure to include the `!` in the title if there are non-backwards-compatible changes in the commit. | Commit message | Release type | New version | | --- | --- | --- | | feat!: remove old files endpoints | Major ("breaking") | X+1.0.0 | | feat: add new file upload endpoint | Minor ("feature") | X.Y+1.0 | | fix: file streaming during download | Patch ("fix") | X.Y.Z+1 | | docs: document files api | No release | X.Y.Z | | chore: remove commented code from file upload | No release | X.Y.Z | | refactor: rename a variable (invisible change) | No release | X.Y.Z | ### Step 6: Rebase Before sending a pull request, rebase against upstream, such as: ``` git fetch upstream git rebase upstream/main ``` This will add your changes on top of what's already in upstream, minimizing merge issues. ### Step 7: Run the tests Make sure that all tests are passing before submitting a pull request. ### Step 8: Send the pull request Send the pull request from your feature branch to us. Be sure to include a description that lets us know what work you did. Keep in mind that we like to see one issue addressed per pull request, as this helps keep our git history clean and we can more easily track down issues. --- ### Contributing **Type:** page | **Section:** Additional Resources Contributing All contributions are welcome to this project. Contributor License Agreement Before a contribution can be merged into this… # Contributing All contributions are welcome to this project. ## Contributor License Agreement Before a contribution can be merged into this project, please fill out the Contributor License Agreement (CLA) located at: [http://opensource.box.com/cla](http://opensource.box.com/cla) To learn more about CLAs and why they are important to open source projects, please see the [Wikipedia entry](http://en.wikipedia.org/wiki/Contributor_License_Agreement). ## Code of Conduct This project adheres to the [Box Open Code of Conduct](http://opensource.box.com/code-of-conduct/). By participating, you are expected to uphold this code. ## How to contribute - **File an issue** - if you found a bug, want to request an enhancement, or want to implement something (bug fix or feature). - **Send a pull request** - if you want to contribute code. Please be sure to file an issue first. ## Pull request best practices We want to accept your pull requests. Please follow these steps: ### Step 1: File an issue Before writing any code, please file an issue stating the problem you want to solve or the feature you want to implement. This allows us to give you feedback before you spend any time writing code. There may be a known limitation that can't be addressed, or a bug that has already been fixed in a different way. The issue allows us to communicate and figure out if it's worth your time to write a bunch of code for the project. ### Step 2: Fork this repository in GitHub This will create your own copy of our repository. ### Step 3: Add the upstream source The upstream source is the project under the Box organization on GitHub. To add an upstream source for this project, type: ``` git remote add upstream git@github.com:box/box-java-sdk.git ``` This will come in useful later. ### Step 4: Create a feature branch Create a branch with a descriptive name, such as `add-search`. ### Step 5: Push your feature branch to your fork We use [semantic-versioning](https://semver.org/) and the [conventional commit message format](https://www.conventionalcommits.org/en/v1.0.0/). Keep a separate feature branch for each issue you want to address. As you develop code, continue to push code to your remote feature branch. Example: ``` tag: short description longer description here if necessary. ``` The message summary should be a one-sentence description of the change, and it must be 72 characters in length or shorter. For a list of tags, please [click here](https://github.com/commitizen/conventional-commit-types/blob/master/index.json). Note that you must include the `!` for breaking changes (e.g. `feat!: removed old apis`). Shown below are examples of the release type that will be done based on a commit message. #### Commit Types "Semantic versioning" means that changes to the version number of the package (e.g. `3.42.11` to `3.43.0`) are done according to rules that indicate how the change will affect consumers. Read more on the [semver page](https://semver.org/). The version number is broken into 3 positions — `Major.Minor.Patch`. In semantic release terms, changes to the numbers follow `Breaking.Feature.Fix`. The `release` script parses commit messages and decides what type of release to make based on the types of commits detected since the last release. The rules for commit types are: - Anything that changes or removes an API, option, or output format is a breaking change denoted by `!`. - Anything that adds new functionality in a backwards-compatible way is a feature (`feat`). Consumers have to upgrade to the new version to use the feature, but nothing will break if they do so. - Bugfixes (`fix`) for existing behavior are a patch. Consumers don't have to do anything but upgrade. - Other prefixes, such as `docs` or `chore`, don't trigger releases and don't appear in the changelog. These tags signal that there are **no external changes to *any* APIs** (including non-breaking ones). In most cases, commits will be a `feat` or `fix`. Make sure to include the `!` in the title if there are non-backwards-compatible changes in the commit. | Commit message | Release type | New version | | --- | --- | --- | | feat!: remove old files endpoints | Major ("breaking") | X+1.0.0 | | feat: add new file upload endpoint | Minor ("feature") | X.Y+1.0 | | fix: file streaming during download | Patch ("fix") | X.Y.Z+1 | | docs: document files api | No release | X.Y.Z | | chore: remove commented code from file upload | No release | X.Y.Z | | refactor: rename a variable (invisible change) | No release | X.Y.Z | ### Step 6: Rebase Before sending a pull request, rebase against upstream, such as: ``` git fetch upstream git rebase upstream/main ``` This will add your changes on top of what's already in upstream, minimizing merge issues. ### Step 7: Run the tests Make sure that the code builds and passes all unit tests by running: ``` $ ./gradlew clean build ``` ### Step 8: Send the pull request Send the pull request from your feature branch to us. Be sure to include a description that lets us know what work you did. Keep in mind that we like to see one issue addressed per pull request, as this helps keep our git history clean and we can more easily track down issues. --- ### Contributing **Type:** page | **Section:** Additional Resources Contributing All contributions are welcome to this project. Contributor License Agreement Before a contribution can be merged into this… # Contributing All contributions are welcome to this project. ## Contributor License Agreement Before a contribution can be merged into this project, please fill out the Contributor License Agreement (CLA) located at: [http://opensource.box.com/cla](http://opensource.box.com/cla) To learn more about CLAs and why they are important to open source projects, please see the [Wikipedia entry](http://en.wikipedia.org/wiki/Contributor_License_Agreement). ## Code of Conduct This project adheres to the [Box Open Code of Conduct](http://opensource.box.com/code-of-conduct/). By participating, you are expected to uphold this code. ## How to contribute - **File an issue** - if you found a bug, want to request an enhancement, or want to implement something (bug fix or feature). - **Send a pull request** - if you want to contribute code. Please be sure to file an issue first. ## Pull request best practices We want to accept your pull requests. Please follow these steps: ### Step 1: File an issue Before writing any code, please file an issue stating the problem you want to solve or the feature you want to implement. This allows us to give you feedback before you spend any time writing code. There may be a known limitation that can't be addressed, or a bug that has already been fixed in a different way. The issue allows us to communicate and figure out if it's worth your time to write a bunch of code for the project. ### Step 2: Fork this repository in GitHub This will create your own copy of our repository. ### Step 3: Add the upstream source The upstream source is the project under the Box organization on GitHub. To add an upstream source for this project, type: ``` git remote add upstream git@github.com:box/box-python-sdk.git ``` This will come in useful later. ### Step 4: Create a feature branch Create a branch with a descriptive name, such as `add-search`. ### Step 5: Push your feature branch to your fork We use [semantic-versioning](https://semver.org/) and the [conventional commit message format](https://www.conventionalcommits.org/en/v1.0.0/). Keep a separate feature branch for each issue you want to address. As you develop code, continue to push code to your remote feature branch. Example: ``` tag: short description longer description here if necessary. ``` The message summary should be a one-sentence description of the change, and it must be 72 characters in length or shorter. For a list of tags, please [click here](https://github.com/commitizen/conventional-commit-types/blob/master/index.json). Note that you must include the `!` for breaking changes (e.g. `feat!: removed old apis`). Shown below are examples of the release type that will be done based on a commit message. #### Commit Types "Semantic versioning" means that changes to the version number of the package (e.g. `3.42.11` to `3.43.0`) are done according to rules that indicate how the change will affect consumers. Read more on the [semver page](https://semver.org/). The version number is broken into 3 positions — `Major.Minor.Patch`. In semantic release terms, changes to the numbers follow `Breaking.Feature.Fix`. The `release` script parses commit messages and decides what type of release to make based on the types of commits detected since the last release. The rules for commit types are: - Anything that changes or removes an API, option, or output format is a breaking change denoted by `!`. - Anything that adds new functionality in a backwards-compatible way is a feature (`feat`). Consumers have to upgrade to the new version to use the feature, but nothing will break if they do so. - Bugfixes (`fix`) for existing behavior are a patch. Consumers don't have to do anything but upgrade. - Other prefixes, such as `docs` or `chore`, don't trigger releases and don't appear in the changelog. These tags signal that there are **no external changes to *any* APIs** (including non-breaking ones). In most cases, commits will be a `feat` or `fix`. Make sure to include the `!` in the title if there are non-backwards-compatible changes in the commit. | Commit message | Release type | New version | | --- | --- | --- | | feat!: remove old files endpoints | Major ("breaking") | X+1.0.0 | | feat: add new file upload endpoint | Minor ("feature") | X.Y+1.0 | | fix: file streaming during download | Patch ("fix") | X.Y.Z+1 | | docs: document files api | No release | X.Y.Z | | chore: remove commented code from file upload | No release | X.Y.Z | | refactor: rename a variable (invisible change) | No release | X.Y.Z | ### Step 6: Rebase Before sending a pull request, rebase against upstream, such as: ``` git fetch upstream git rebase upstream/main ``` This will add your changes on top of what's already in upstream, minimizing merge issues. ### Step 7: Run the tests Make sure that all tests are passing before submitting a pull request. ### Step 8: Send the pull request Send the pull request from your feature branch to us. Be sure to include a description that lets us know what work you did. Keep in mind that we like to see one issue addressed per pull request, as this helps keep our git history clean and we can more easily track down issues. In addition, feel free to add yourself to AUTHORS.md if you aren't already listed. --- ### Contributing **Type:** page | **Section:** Additional Resources Contributing All contributions are welcome to this project. Contributor License Agreement Before a contribution can be merged into this… # Contributing All contributions are welcome to this project. ## Contributor License Agreement Before a contribution can be merged into this project, please fill out the Contributor License Agreement (CLA) located at: [http://opensource.box.com/cla](http://opensource.box.com/cla) To learn more about CLAs and why they are important to open source projects, please see the [Wikipedia entry](http://en.wikipedia.org/wiki/Contributor_License_Agreement). ## Code of Conduct This project adheres to the [Box Open Code of Conduct](http://opensource.box.com/code-of-conduct/). By participating, you are expected to uphold this code. ## How to contribute - **File an issue** - if you found a bug, want to request an enhancement, or want to implement something (bug fix or feature). - **Send a pull request** - if you want to contribute code. Please be sure to file an issue first. ## Pull request best practices We want to accept your pull requests. Please follow these steps: ### Step 1: File an issue Before writing any code, please file an issue stating the problem you want to solve or the feature you want to implement. This allows us to give you feedback before you spend any time writing code. There may be a known limitation that can't be addressed, or a bug that has already been fixed in a different way. The issue allows us to communicate and figure out if it's worth your time to write a bunch of code for the project. ### Step 2: Fork this repository in GitHub This will create your own copy of our repository. ### Step 3: Add the upstream source The upstream source is the project under the Box organization on GitHub. To add an upstream source for this project, type: ``` git remote add upstream git@github.com:box/box-windows-sdk-v2.git ``` This will come in useful later. ### Step 4: Create a feature branch Create a branch with a descriptive name, such as `add-search`. ### Step 5: Push your feature branch to your fork We use [semantic-versioning](https://semver.org/) and the [conventional commit message format](https://www.conventionalcommits.org/en/v1.0.0/). Keep a separate feature branch for each issue you want to address. As you develop code, continue to push code to your remote feature branch. Example: ``` tag: short description longer description here if necessary. ``` The message summary should be a one-sentence description of the change, and it must be 72 characters in length or shorter. For a list of tags, please [click here](https://github.com/commitizen/conventional-commit-types/blob/master/index.json). Note that you must include the `!` for breaking changes (e.g. `feat!: removed old apis`). Shown below are examples of the release type that will be done based on a commit message. #### Commit Types "Semantic versioning" means that changes to the version number of the package (e.g. `3.42.11` to `3.43.0`) are done according to rules that indicate how the change will affect consumers. Read more on the [semver page](https://semver.org/). The version number is broken into 3 positions — `Major.Minor.Patch`. In semantic release terms, changes to the numbers follow `Breaking.Feature.Fix`. The `release` script parses commit messages and decides what type of release to make based on the types of commits detected since the last release. The rules for commit types are: - Anything that changes or removes an API, option, or output format is a breaking change denoted by `!`. - Anything that adds new functionality in a backwards-compatible way is a feature (`feat`). Consumers have to upgrade to the new version to use the feature, but nothing will break if they do so. - Bugfixes (`fix`) for existing behavior are a patch. Consumers don't have to do anything but upgrade. - Other prefixes, such as `docs` or `chore`, don't trigger releases and don't appear in the changelog. These tags signal that there are **no external changes to *any* APIs** (including non-breaking ones). In most cases, commits will be a `feat` or `fix`. Make sure to include the `!` in the title if there are non-backwards-compatible changes in the commit. | Commit message | Release type | New version | | --- | --- | --- | | feat!: remove old files endpoints | Major ("breaking") | X+1.0.0 | | feat: add new file upload endpoint | Minor ("feature") | X.Y+1.0 | | fix: file streaming during download | Patch ("fix") | X.Y.Z+1 | | docs: document files api | No release | X.Y.Z | | chore: remove commented code from file upload | No release | X.Y.Z | | refactor: rename a variable (invisible change) | No release | X.Y.Z | ### Step 6: Rebase Before sending a pull request, rebase against upstream, such as: ``` git fetch upstream git rebase upstream/main ``` This will add your changes on top of what's already in upstream, minimizing merge issues. ### Step 7: Run the tests Make sure that all tests are passing before submitting a pull request by running: `dotnet test` ### Step 8: Send the pull request Send the pull request from your feature branch to us. Be sure to include a description that lets us know what work you did. Keep in mind that we like to see one issue addressed per pull request, as this helps keep our git history clean and we can more easily track down issues. --- ### Contributing **Type:** page | **Section:** Additional Resources Contributing All contributions are welcome to this project. Contributor License Agreement Before a contribution can be merged into this… # Contributing All contributions are welcome to this project. ## Contributor License Agreement Before a contribution can be merged into this project, please fill out the Contributor License Agreement (CLA) located at: [http://opensource.box.com/cla](http://opensource.box.com/cla) To learn more about CLAs and why they are important to open source projects, please see the [Wikipedia entry](http://en.wikipedia.org/wiki/Contributor_License_Agreement). ## Code of Conduct This project adheres to the [Box Open Code of Conduct](http://opensource.box.com/code-of-conduct/). By participating, you are expected to uphold this code. ## How to contribute - **File an issue** - if you found a bug, want to request an enhancement, or want to implement something (bug fix or feature). - **Send a pull request** - if you want to contribute code. Please be sure to file an issue first. ## Pull request best practices We want to accept your pull requests. Please follow these steps: ### Step 1: File an issue Before writing any code, please file an issue stating the problem you want to solve or the feature you want to implement. This allows us to give you feedback before you spend any time writing code. There may be a known limitation that can't be addressed, or a bug that has already been fixed in a different way. The issue allows us to communicate and figure out if it's worth your time to write a bunch of code for the project. ### Step 2: Fork this repository in GitHub This will create your own copy of our repository. ### Step 3: Add the upstream source The upstream source is the project under the Box organization on GitHub. To add an upstream source for this project, type: ``` git remote add upstream git@github.com:box/box-ios-sdk.git ``` This will come in useful later. ### Step 4: Create a feature branch Create a branch with a descriptive name, such as `add-search`. ### Step 5: Push your feature branch to your fork We use [semantic-versioning](https://semver.org/) and the [conventional commit message format](https://www.conventionalcommits.org/en/v1.0.0/). Keep a separate feature branch for each issue you want to address. As you develop code, continue to push code to your remote feature branch. Example: ``` tag: short description longer description here if necessary. ``` The message summary should be a one-sentence description of the change, and it must be 72 characters in length or shorter. For a list of tags, please [click here](https://github.com/commitizen/conventional-commit-types/blob/master/index.json). Note that you must include the `!` for breaking changes (e.g. `feat!: removed old apis`). Shown below are examples of the release type that will be done based on a commit message. #### Commit Types "Semantic versioning" means that changes to the version number of the package (e.g. `3.42.11` to `3.43.0`) are done according to rules that indicate how the change will affect consumers. Read more on the [semver page](https://semver.org/). The version number is broken into 3 positions — `Major.Minor.Patch`. In semantic release terms, changes to the numbers follow `Breaking.Feature.Fix`. The `release` script parses commit messages and decides what type of release to make based on the types of commits detected since the last release. The rules for commit types are: - Anything that changes or removes an API, option, or output format is a breaking change denoted by `!`. - Anything that adds new functionality in a backwards-compatible way is a feature (`feat`). Consumers have to upgrade to the new version to use the feature, but nothing will break if they do so. - Bugfixes (`fix`) for existing behavior are a patch. Consumers don't have to do anything but upgrade. - Other prefixes, such as `docs` or `chore`, don't trigger releases and don't appear in the changelog. These tags signal that there are **no external changes to *any* APIs** (including non-breaking ones). In most cases, commits will be a `feat` or `fix`. Make sure to include the `!` in the title if there are non-backwards-compatible changes in the commit. | Commit message | Release type | New version | | --- | --- | --- | | feat!: remove old files endpoints | Major ("breaking") | X+1.0.0 | | feat: add new file upload endpoint | Minor ("feature") | X.Y+1.0 | | fix: file streaming during download | Patch ("fix") | X.Y.Z+1 | | docs: document files api | No release | X.Y.Z | | chore: remove commented code from file upload | No release | X.Y.Z | | refactor: rename a variable (invisible change) | No release | X.Y.Z | ### Step 6: Rebase Before sending a pull request, rebase against upstream, such as: ``` git fetch upstream git rebase upstream/main ``` This will add your changes on top of what's already in upstream, minimizing merge issues. ### Step 7: Run the tests Make sure that all tests are passing before submitting a pull request. ### Step 8: Send the pull request Send the pull request from your feature branch to us. Be sure to include a description that lets us know what work you did. Keep in mind that we like to see one issue addressed per pull request, as this helps keep our git history clean and we can more easily track down issues. --- ### Contributing **Type:** page | **Section:** Additional Resources Contributing All contributions are welcome to this project. Contributor License Agreement Before a contribution can be merged into this… # Contributing All contributions are welcome to this project. ## Contributor License Agreement Before a contribution can be merged into this project, please fill out the Contributor License Agreement (CLA) located at: [http://opensource.box.com/cla](http://opensource.box.com/cla) To learn more about CLAs and why they are important to open source projects, please see the [Wikipedia entry](http://en.wikipedia.org/wiki/Contributor_License_Agreement). ## Code of Conduct This project adheres to the [Box Open Code of Conduct](http://opensource.box.com/code-of-conduct/). By participating, you are expected to uphold this code. ## How to contribute - **File an issue** - if you found a bug, want to request an enhancement, or want to implement something (bug fix or feature). - **Send a pull request** - this project is generated using [Box Codegen](https://github.com/box/box-codegen) based on[Box OpenAPI 3.0 Specification](https://github.com/box/box-openapi), so if you want found something you want to change in the generated code, you'll need to modify the codegen project and submit a pull request there. --- ### Contributing **Type:** page | **Section:** Additional Resources Contributing All contributions are welcome to this project. Contributor License Agreement Before a contribution can be merged into this… # Contributing All contributions are welcome to this project. ## Contributor License Agreement Before a contribution can be merged into this project, please fill out the Contributor License Agreement (CLA) located at: [http://opensource.box.com/cla](http://opensource.box.com/cla) To learn more about CLAs and why they are important to open source projects, please see the [Wikipedia entry](http://en.wikipedia.org/wiki/Contributor_License_Agreement). ## Code of Conduct This project adheres to the [Box Open Code of Conduct](http://opensource.box.com/code-of-conduct/). By participating, you are expected to uphold this code. ## How to contribute - **File an issue** - if you found a bug, want to request an enhancement, or want to implement something (bug fix or feature). - **Send a pull request** - this project is generated using [Box Codegen](https://github.com/box/box-codegen) based on[Box OpenAPI 3.0 Specification](https://github.com/box/box-openapi), so if you want found something you want to change in the generated code, you'll need to modify the codegen project and submit a pull request there. --- ### Contributing **Type:** page | **Section:** Additional Resources Contributing All contributions are welcome to this project. Contributor License Agreement Before a contribution can be merged into this… # Contributing All contributions are welcome to this project. ## Contributor License Agreement Before a contribution can be merged into this project, please fill out the Contributor License Agreement (CLA) located at: [http://opensource.box.com/cla](http://opensource.box.com/cla) To learn more about CLAs and why they are important to open source projects, please see the [Wikipedia entry](http://en.wikipedia.org/wiki/Contributor_License_Agreement). ## Code of Conduct This project adheres to the [Box Open Code of Conduct](http://opensource.box.com/code-of-conduct/). By participating, you are expected to uphold this code. ## How to contribute - **File an issue** - if you found a bug, want to request an enhancement, or want to implement something (bug fix or feature). - **Send a pull request** - this project is generated using [Box Codegen](https://github.com/box/box-codegen) based on[Box OpenAPI 3.0 Specification](https://github.com/box/box-openapi), so if you want found something you want to change in the generated code, you'll need to modify the codegen project and submit a pull request there. --- ### Contributor Covenant Code of Conduct **Type:** page | **Section:** Additional Resources Contributor Covenant Code of Conduct Our Pledge In the interest of fostering an open and welcoming environment, we as contributors and… # Contributor Covenant Code of Conduct ## Our Pledge In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation. ## Our Standards Examples of behavior that contributes to creating a positive environment include: - Using welcoming and inclusive language - Being respectful of differing viewpoints and experiences - Gracefully accepting constructive criticism - Focusing on what is best for the community - Showing empathy towards other community members Examples of unacceptable behavior by participants include: - The use of sexualized language or imagery and unwelcome sexual attention or advances - Trolling, insulting/derogatory comments, and personal or political attacks - Public or private harassment - Publishing others' private information, such as a physical or electronic address, without explicit permission - Other conduct which could reasonably be considered inappropriate in a professional setting ## Our Responsibilities Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior. Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful. ## Scope This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers. ## Enforcement Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at [oss@box.com](mailto:oss@box.com). The project team will review and investigate all complaints, and will respond in a way that it deems appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately. Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership. ## Attribution This Code of Conduct is adapted from the [Contributor Covenant](http://contributor-covenant.org), version 1.4, available at [http://contributor-covenant.org/version/1/4](http://contributor-covenant.org/version/1/4/) --- ### Custom API Calls **Type:** page | **Section:** Additional Resources Custom API Calls There are a few situations, where a user might want to make a custom API call — utilizing the SDK's authentication handling… # Custom API Calls There are a few situations, where a user might want to make a custom API call — utilizing the SDK's authentication handling, but creating the API request manually: - When new endpoints and parameters have been introduced to the API, but they are not yet supported directly by the SDK - Beta endpoints, that are not yet suitable for inclusion in the SDK - Hitting URLs specified directly in the response of another API call, e.g. Representation Info and Download URLs For these reasons BoxClient exposes this functionality through a set of methods on the client mapping to HTTP verbs: ``` client.get(/*...*/) client.post(/*...*/) client.put(/*...*/) client.delete(/*...*/) client.options(/*...*/) ``` and additionally a HTTP GET method call for downloading: ``` client.download(/*...*/) ``` Moreover, the SDK exposes a low-level method that is used under the hood by the all previous methods. However because of its complexity, we recommend that you should only use this method if all the other options do not suit your needs. ``` client.send(/*...*/) ``` [Custom API Calls](#custom-api-calls) - [Create URL](#create-url) - [Deserialize Response Body](#deserialize-response-body) [API Calls](#api-calls) - [Custom GET](#custom-get) - [Custom POST](#custom-post) - [Custom PUT](#custom-put) - [Custom DELETE](#custom-delete) - [Custom OPTIONS](#custom-options) - [Download](#download) - [Send](#send) ## Create URL When you want to execute custom API call, you must specify a destination URL. You can create it by yourself: ``` let fileId = "<YOUR_FILE_ID_HERE>" let url = URL(string: "https://api.box.com/2.0/files/\(fileId)")! ``` or you can use SDK's predefined method: [`URL.boxAPIEndpoint(_ endpoint:configuration)`](https://opensource.box.com/box-ios-sdk/Extensions/URL.html#/s:10Foundation3URLV6BoxSDKE14boxAPIEndpoint_13configurationACSS_AD0C16SDKConfigurationVtFZ) ``` let fileId = "<YOUR_FILE_ID_HERE>" let url = URL.boxAPIEndpoint("/2.0/files/\(fileId)", configuration: client.configuration) ``` The `boxAPIEndpoint` method requires to pass an endpoint path and configuration from the current `BoxClient` instance. It internally fetches `apiBaseURL` and appends to it the endpoint path you passed. The default value of `apiBaseURL` is `https://api.box.com`, but you can change it with [`sdk.updateConfiguration(apiBaseURL:uploadApiBaseURL:oauth2AuthorizeURL:maxRetryAttempts:tokenRefreshThreshold:consoleLogDestination:fileLogDestination:clientAnalyticsInfo:)`](https://opensource.box.com/box-ios-sdk/Classes/BoxSDK.html#/s:6BoxSDKAAC19updateConfiguration10apiBaseURL09uploadApifG0015oauth2AuthorizeG016maxRetryAttempts21tokenRefreshThreshold21consoleLogDestination04filesT019clientAnalyticsInfoy10Foundation0G0VSg_A2OSiSgSdSgAA07ConsolesT0CSgAA04FilesT0CSgAA06ClientwX0VSgtKF) method. ## Deserialize Response Body All exposed custom API methods return a [`BoxResponse`](https://opensource.box.com/box-ios-sdk/Structs/BoxResponse.html#/s:6BoxSDK0A8ResponseV7requestAA0A7RequestCvp) object or an error if request fails. The `BoxResponse` type has a `body` property of type `Data?`. If you want to deserialize its json content to specific custom type, you can use SDK's [`ObjectDeserializer.deserialize(data:)`](https://opensource.box.com/box-ios-sdk/Enums/ObjectDeserializer.html#/s:6BoxSDK18ObjectDeserializerO11deserialize4datas6ResultOyxAA0A8SDKErrorCG10Foundation4DataVSg_tAA0A5ModelRzlFZ) method to deserialize `Data?` to any type that conforms to `BoxModel`, or [`ObjectDeserializer.deserialize(response:)`](https://opensource.box.com/box-ios-sdk/Enums/ObjectDeserializer.html#/s:6BoxSDK18ObjectDeserializerO11deserialize8responses6ResultOyxAA0A8SDKErrorCGAA0A8ResponseV_tSeRzlFZ) to deserialize `BoxResponse` to any type that conforms to `Decodable`. ``` let fileId = "<YOUR_FILE_ID_HERE>" client.get(url: URL.boxAPIEndpoint("/2.0/files/\(fileId)", configuration: client.configuration)) { (result: Result<BoxResponse, BoxSDKError>) in let fileResult: Result<File, BoxSDKError> = result.flatMap { ObjectDeserializer.deserialize(data: $0.body)} switch fileResult { case .success(let file): print("File \(file.name) was created at \(file.createdAt)") case .failure(let error): print("Error retrieving file information") } } ``` As you can see, we are using `flatMap` operator on `Result` type to deserialize origin `body` to the specific type, which is `File` in our case. The [`ObjectDeserializer.deserialize(data: Data?)`](https://opensource.box.com/box-ios-sdk/Enums/ObjectDeserializer.html#/s:6BoxSDK18ObjectDeserializerO11deserialize4datas6ResultOyxAA0A8SDKErrorCG10Foundation4DataVSg_tAA0A5ModelRzlFZ) method returns `Result<ReturnType, BoxSDKError>`, where `ReturnType` is inferenced as a `File`. ## API Calls ### Custom GET To perform a custom HTTP GET method, call [`client.get(url:httpHeaders:queryParameters:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/BoxClient.html#/s:6BoxSDK0A6ClientC3get3url11httpHeaders15queryParameters10completiony10Foundation3URLV_SDyS2SGSDySSAA25QueryParameterConvertible_pSgGys6ResultOyAA0A8ResponseVAA0A8SDKErrorCGctF) with the destination `url` and with headers or query parameters if needed. As you can see in the `completion` parameter, the `Callback` closure returns a [`BoxResponse`](https://opensource.box.com/box-ios-sdk/Structs/BoxResponse.html#/s:6BoxSDK0A8ResponseV7requestAA0A7RequestCvp) type. You can find the `body` of the response in `body` property, which is of type `Data?`. If you want to deserialize it to a specific type, you can do so as in the example below: ``` let fileId = "<YOUR_FILE_ID_HERE>" // Get information about a file. client.get(url: URL.boxAPIEndpoint("/2.0/files/\(fileId)", configuration: client.configuration)) { (result: Result<BoxResponse, BoxSDKError>) in let fileResult: Result<File, BoxSDKError> = result.flatMap { ObjectDeserializer.deserialize(data: $0.body)} switch fileResult { case .success(let file): print("File \(file.name) was created at \(file.createdAt)") case .failure(let error): print("Error retrieving file information") } } ``` As an alternative, to manually deserialize a response body, you can use [`ResponseHandler.default(wrapping completion:)`](https://opensource.box.com/box-ios-sdk/Enums/ResponseHandler.html#/s:6BoxSDK15ResponseHandlerO7default8wrappingys6ResultOyAA0aC0VAA0A8SDKErrorCGcyAGyxAKGc_tAA0A5ModelRzlFZ) method: ``` let fileId = "<YOUR_FILE_ID_HERE>" // Get information about a file. client.get( url: URL.boxAPIEndpoint("/2.0/files/\(fileId)", configuration: client.configuration), completion: ResponseHandler.default( wrapping: { (result: Result<File, BoxSDKError>) in switch result { case .success(let file): print("File \(file.name) was created at \(file.createdAt)") case .failure(let error): print("Error retrieving file information") } } ) ) ``` This method will make sure that the response is successful (status code 2xx) and will deserialize the response body into the appropriate type. In these examples above, we used existing SDKs type `File`, but this can be replaced with any custom type that conforms to either `Decodable` or `BoxModel`. ### Custom POST To perform a custom HTTP POST method, call [`client.post(url:httpHeaders:queryParameters:json:completion)`](https://opensource.box.com/box-ios-sdk/Classes/BoxClient.html#/s:6BoxSDK0A6ClientC4post3url11httpHeaders15queryParameters4json10completiony10Foundation3URLV_SDyS2SGSDySSAA25QueryParameterConvertible_pSgGypSgys6ResultOyAA0A8ResponseVAA0A8SDKErrorCGctF) with the `url`, `json` body and with headers or query parameters if needed. As you can see in the `completion` parameter, the `Callback` closure returns a [`BoxResponse`](https://opensource.box.com/box-ios-sdk/Structs/BoxResponse.html#/s:6BoxSDK0A8ResponseV7requestAA0A7RequestCvp) type. You can find the `body` of the response in `body` property, which is of type `Data?`. If you want to deserialize it to a specific type, you can do so as shown in the examples below: ``` var body: [String: Any] = [:] body["parent"] = ["id": "<YOUR_FOLDER_ID_HERE>"] body["url"] = "https://example.com" body["name"] = "example name" // Creates a new web link with the specified url on the specified folder. client.post(url: URL.boxAPIEndpoint("/2.0/web_links", configuration: client.configuration), json: body) { result in let webLinkResult: Result<WebLink, BoxSDKError> = result.flatMap { ObjectDeserializer.deserialize(data: $0.body) } switch webLinkResult { case .success(let webLink): print("WebLink \(webLink.name) was created") case .failure(let error): print("Error creating a webLink \(error)") } } ``` or ``` var body: [String: Any] = [:] body["parent"] = ["id": "<YOUR_FOLDER_ID_HERE>"] body["url"] = "https://example.com" body["name"] = "example name" // Creates a new web link with the specified url on the specified folder. client.post( url: URL.boxAPIEndpoint("/2.0/web_links", configuration: client.configuration), json: body, completion: ResponseHandler.default( wrapping: { (result: Result<WebLink, BoxSDKError>) in switch result { case .success(let webLink): print("WebLink \(webLink.name) was created") case .failure(let error): print("Error creating a webLink \(error)") } } ) ) ``` In these examples we deserialized `body` as `WebLink` type, but you can deserialize response's body to any custom type that conforms to either `Decodable` or `BoxModel`. ### Custom PUT To perform a custom HTTP PUT method, call [`client.put(url:httpHeaders:queryParameters:json:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/BoxClient.html#/s:6BoxSDK0A6ClientC3put3url11httpHeaders15queryParameters4json10completiony10Foundation3URLV_SDyS2SGSDySSAA25QueryParameterConvertible_pSgGypSgys6ResultOyAA0A8ResponseVAA0A8SDKErrorCGctF) with the `url`, `json` body and with headers or query parameters if needed. As you can see in the `completion` parameter, the `Callback` closure returns a [`BoxResponse`](https://opensource.box.com/box-ios-sdk/Structs/BoxResponse.html#/s:6BoxSDK0A8ResponseV7requestAA0A7RequestCvp) type. You can find the `body` of the response in `body` property, which is of type `Data?`. If you want to deserialize it to a specific type, you can do so as shown in the examples below: ``` let taskId = "<YOUR_TASK_ID_HERE>" var body = [String: Any]() body["message"] = "Please to this ASAP!" body["action"] = "review" // Updates a specific task. client.put(url: URL.boxAPIEndpoint("/2.0/tasks/\(taskId)", configuration: client.configuration), json: body) { result in let taskResult: Result<Task, BoxSDKError> = result.flatMap { ObjectDeserializer.deserialize(data: $0.body) } switch taskResult { case .success(let task): print("Task \(task.id) was updated") case .failure(let error): print("Error updating a task \(error)") } } ``` or ``` let taskId = "<YOUR_TASK_ID_HERE>" var body = [String: Any]() body["message"] = "Please to this ASAP!" body["action"] = "review" // Updates a specific task. client.put( url: URL.boxAPIEndpoint("/2.0/tasks/\(taskId)", configuration: client.configuration), json: body, completion: ResponseHandler.default( wrapping: { (result: Result<Task, BoxSDKError>) in switch result { case .success(let task): print("Task \(task.id) was updated") case .failure(let error): print("Error updating a task \(error)") } } ) ) ``` In these examples we deserialized `body` as `Task` type, but we can deserialize it to any custom type that conforms to either `Decodable` or `BoxModel`. ### Custom DELETE To perform a custom HTTP DELETE method, call [`client.delete(url:httpHeaders:queryParameters:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/BoxClient.html#/s:6BoxSDK0A6ClientC6delete3url11httpHeaders15queryParameters10completiony10Foundation3URLV_SDyS2SGSDySSAA25QueryParameterConvertible_pSgGys6ResultOyAA0A8ResponseVAA0A8SDKErrorCGctF) with the `url` and with headers and query parameters if needed. As you can see in the `completion` parameter, the `Callback` closure returns a [`BoxResponse`](https://opensource.box.com/box-ios-sdk/Structs/BoxResponse.html#/s:6BoxSDK0A8ResponseV7requestAA0A7RequestCvp) type. You can find the `body` of the response in `body` property, which is of type `Data?`. In most cases the `body` property on success will be just nil, so to handle this you can do as follows: ``` let fileId = "<YOUR_FILE_ID_HERE>" // Discards a file to the trash. client.delete(url: URL.boxAPIEndpoint("/2.0/files/\(fileId)", configuration: client.configuration)) { result in switch result { case .success: print("The file was deleted") case .failure(let error): print("Error deleting a file \(error)") } } ``` ### Custom OPTIONS To perform a custom HTTP OPTIONS method, call [`client.options(url:httpHeaders:queryParameters:json:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/BoxClient.html#/s:6BoxSDK0A6ClientC7options3url11httpHeaders15queryParameters4json10completionAA0A11NetworkTaskC10Foundation3URLV_SDyS2SGSDySSAA25QueryParameterConvertible_pSgGypSgys6ResultOyAA0A8ResponseVAA0A8SDKErrorCGctF) with the `url`, `json` body and with headers or query parameters if needed. As you can see in the `completion` parameter, the `Callback` closure returns a [`BoxResponse`](https://opensource.box.com/box-ios-sdk/Structs/BoxResponse.html#/s:6BoxSDK0A8ResponseV7requestAA0A7RequestCvp) type. You can find the `body` of the response in `body` property, which is of type `Data?`. ``` var body: [String: Any] = ["parent": ["id": "<YOUR_FOLDER_ID_HERE>"]] body["name"] = "<YOUR_FILE_NAME_HERE>" // Verifies that new file will be accepted by Box before you send all the bytes over the wire. client.options(url: URL.boxAPIEndpoint("/2.0/files/content", configuration: client.configuration)) { result in switch result { case .success: print("The file is verified successfully") case .failure(let error): print("Error verifying a file \(error)") } } ``` This example will return an empty response when the checks pass or an error when the checks fail. In case of an empty response, the user can proceed with making an upload call. ### Download To perform a HTTP GET method call for downloading on the API, call [`client.download(url:downloadDestinationURL:httpHeaders:queryParameters:progress:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/BoxClient.html#/s:6BoxSDK0A6ClientC7options3url11httpHeaders15queryParameters4json10completionAA0A11NetworkTaskC10Foundation3URLV_SDyS2SGSDySSAA25QueryParameterConvertible_pSgGypSgys6ResultOyAA0A8ResponseVAA0A8SDKErrorCGctF). You must specify `url` of the API endpoint to call `downloadDestinationURL`, which specifies the URL on a disk, where the data will be saved. The `completion` is a callback, which returns a [`BoxResponse`](https://opensource.box.com/box-ios-sdk/Structs/BoxResponse.html#/s:6BoxSDK0A8ResponseV7requestAA0A7RequestCvp) object or an error if request fails. Headers and query parameters are optional, so add them if needed. ``` let fileId = "<YOUR_FILE_ID_HERE>" let destinationURL = FileManager.default.urls(for: .documentDirectory, in: .userDomainMask).first!.appendingPathComponent("<FILE_NAME_HERE>") // Download a file to a specified folder. client.download( url: URL.boxAPIEndpoint("/2.0/files/\(fileId)/content", configuration: client.configuration), downloadDestinationURL: destinationURL ) { result in switch result { case .success: print("The file was downloaded") case .failure(let error): print("Error downloaded a file \(error)") } } ``` This example will return an empty response on success or an error on failure. ### Send To perform a send method, call [`client.send(request:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/BoxClient.html#/s:6BoxSDK0A6ClientC4send7request10completionyAA0A7RequestC_ys6ResultOyAA0A8ResponseVAA0A8SDKErrorCGctF) with the [`request`](https://opensource.box.com/box-ios-sdk/Classes/BoxRequest.html#/s:6BoxSDK0A7RequestC10httpMethod3url0D7Headers11queryParams4body19downloadDestination4task8progressAcA10HTTPMethodO_10Foundation3URLVSDyS2SGSDySSAA25QueryParameterConvertible_pSgGAC8BodyTypeOAPSgySo16NSURLSessionTaskCcySo10NSProgressCctcfc) object, which represents the Box SDK API request. As you can see in the `completion` parameter, the `Callback` closure returns a [`BoxResponse`](https://opensource.box.com/box-ios-sdk/Structs/BoxResponse.html#/s:6BoxSDK0A8ResponseV7requestAA0A7RequestCvp) type. You can find the `body` of the response in `body` property, which is of type `Data?`. When creating a `BoxRequest` instance, please call [`init(httpMethod:url:httpHeaders:queryParams:body:downloadDestination:task:progress:)`](https://opensource.box.com/box-ios-sdk/Classes/BoxRequest.html#/s:6BoxSDK0A7RequestC10httpMethod3url0D7Headers11queryParams4body19downloadDestination4task8progressAcA10HTTPMethodO_10Foundation3URLVSDyS2SGSDySSAA25QueryParameterConvertible_pSgGAC8BodyTypeOAPSgySo16NSURLSessionTaskCcySo10NSProgressCctcfc) with the parameters you need, leaving unused parameters with their default value. Below is an example of how we can use `send()` method to update a particular file: ``` let fileId = "<YOUR_FILE_ID_HERE>" var body: [String: Any] = [:] body["name"] = "new_file_name.txt" body["description"] = "new description" let request = BoxRequest( httpMethod: .put, url: URL.boxAPIEndpoint("/2.0/files/\(fileId)", configuration: client.configuration), queryParams: ["fields": "name,description"], body: .jsonObject(body) ) client.send(request: request) { result in let fileResult: Result<File, BoxSDKError> = result.flatMap { ObjectDeserializer.deserialize(data: $0.body) } switch fileResult { case let .success(fileItem): print("The file was updated successfully") case let .failure(error): print("Error updating a file \(error)") } } ``` This is an another example showing the use of the `send()` method to download a file: ``` let fileId = "<YOUR_FILE_ID_HERE>" let filename = "<YOUR_DESTINATION_FILE_NAME>" let destinationURL = FileManager.default.urls(for: .documentDirectory, in: .userDomainMask).first!.appendingPathComponent(filename) let task = BoxDownloadTask() let request = BoxRequest( httpMethod: .get, url: URL.boxAPIEndpoint("/2.0/files/\(fileId)/content", configuration: client.configuration), downloadDestination: destinationURL, task: task.receiveTask, progress: { progress in let completed = String(format: "%.2f", progress.fractionCompleted * 100) print("Completed... \(completed)%") } ) client.send(request: request) { result in switch result { case .success: print("The file was downloaded") case let .failure(error): print("Error downloaded a file \(error)") } } // If you want to cancel downloading a file, please call `task.cancel()` method. ``` --- ### Custom API Calls **Type:** page | **Section:** Additional Resources Custom API Calls There are a few situations, where a user might want to make a custom API call — utilizing the SDK's authentication handling… # Custom API Calls There are a few situations, where a user might want to make a custom API call — utilizing the SDK's authentication handling, but creating the API request manually: - When new endpoints and parameters have been introduced to the API, but they are not yet supported directly by the SDK - Beta endpoints, that are not yet suitable for inclusion in the SDK - Hitting URLs specified directly in the response of another API call, e.g. Representation Info and Download URLs For these reasons BoxClient exposes this functionality through a set of methods on the client mapping to HTTP verbs: ``` client.get(/*...*/) client.post(/*...*/) client.put(/*...*/) client.delete(/*...*/) client.options(/*...*/) ``` and additionally a HTTP GET method call for downloading: ``` client.download(/*...*/) ``` Moreover, the SDK exposes a low-level method that is used under the hood by the all previous methods. However because of its complexity, we recommend that you should only use this method if all the other options do not suit your needs. ``` client.send(/*...*/) ``` [Custom API Calls](#custom-api-calls) - [Create URL](#create-url) - [Deserialize Response Body](#deserialize-response-body) [API Calls](#api-calls) - [Custom GET](#custom-get) - [Custom POST](#custom-post) - [Custom PUT](#custom-put) - [Custom DELETE](#custom-delete) - [Custom OPTIONS](#custom-options) - [Download](#download) - [Send](#send) ## Create URL When you want to execute custom API call, you must specify a destination URL. You can create it by yourself: ``` let fileId = "<YOUR_FILE_ID_HERE>" let url = URL(string: "https://api.box.com/2.0/files/\(fileId)")! ``` or you can use SDK's predefined method: [`URL.boxAPIEndpoint(_ endpoint:configuration)`](https://opensource.box.com/box-ios-sdk/Extensions/URL.html#/s:10Foundation3URLV6BoxSDKE14boxAPIEndpoint_13configurationACSS_AD0C16SDKConfigurationVtFZ) ``` let fileId = "<YOUR_FILE_ID_HERE>" let url = URL.boxAPIEndpoint("/2.0/files/\(fileId)", configuration: client.configuration) ``` The `boxAPIEndpoint` method requires to pass an endpoint path and configuration from the current `BoxClient` instance. It internally fetches `apiBaseURL` and appends to it the endpoint path you passed. The default value of `apiBaseURL` is `https://api.box.com`, but you can change it with [`sdk.updateConfiguration(apiBaseURL:uploadApiBaseURL:oauth2AuthorizeURL:maxRetryAttempts:tokenRefreshThreshold:consoleLogDestination:fileLogDestination:clientAnalyticsInfo:)`](https://opensource.box.com/box-ios-sdk/Classes/BoxSDK.html#/s:6BoxSDKAAC19updateConfiguration10apiBaseURL09uploadApifG0015oauth2AuthorizeG016maxRetryAttempts21tokenRefreshThreshold21consoleLogDestination04filesT019clientAnalyticsInfoy10Foundation0G0VSg_A2OSiSgSdSgAA07ConsolesT0CSgAA04FilesT0CSgAA06ClientwX0VSgtKF) method. ## Deserialize Response Body All exposed custom API methods return a [`BoxResponse`](https://opensource.box.com/box-ios-sdk/Structs/BoxResponse.html#/s:6BoxSDK0A8ResponseV7requestAA0A7RequestCvp) object or an error if request fails. The `BoxResponse` type has a `body` property of type `Data?`. If you want to deserialize its json content to specific custom type, you can use SDK's [`ObjectDeserializer.deserialize(data:)`](https://opensource.box.com/box-ios-sdk/Enums/ObjectDeserializer.html#/s:6BoxSDK18ObjectDeserializerO11deserialize4datas6ResultOyxAA0A8SDKErrorCG10Foundation4DataVSg_tAA0A5ModelRzlFZ) method to deserialize `Data?` to any type that conforms to `BoxModel`, or [`ObjectDeserializer.deserialize(response:)`](https://opensource.box.com/box-ios-sdk/Enums/ObjectDeserializer.html#/s:6BoxSDK18ObjectDeserializerO11deserialize8responses6ResultOyxAA0A8SDKErrorCGAA0A8ResponseV_tSeRzlFZ) to deserialize `BoxResponse` to any type that conforms to `Decodable`. ``` let fileId = "<YOUR_FILE_ID_HERE>" client.get(url: URL.boxAPIEndpoint("/2.0/files/\(fileId)", configuration: client.configuration)) { (result: Result<BoxResponse, BoxSDKError>) in let fileResult: Result<File, BoxSDKError> = result.flatMap { ObjectDeserializer.deserialize(data: $0.body)} switch fileResult { case .success(let file): print("File \(file.name) was created at \(file.createdAt)") case .failure(let error): print("Error retrieving file information") } } ``` As you can see, we are using `flatMap` operator on `Result` type to deserialize origin `body` to the specific type, which is `File` in our case. The [`ObjectDeserializer.deserialize(data: Data?)`](https://opensource.box.com/box-ios-sdk/Enums/ObjectDeserializer.html#/s:6BoxSDK18ObjectDeserializerO11deserialize4datas6ResultOyxAA0A8SDKErrorCG10Foundation4DataVSg_tAA0A5ModelRzlFZ) method returns `Result<ReturnType, BoxSDKError>`, where `ReturnType` is inferenced as a `File`. ## API Calls ### Custom GET To perform a custom HTTP GET method, call [`client.get(url:httpHeaders:queryParameters:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/BoxClient.html#/s:6BoxSDK0A6ClientC3get3url11httpHeaders15queryParameters10completiony10Foundation3URLV_SDyS2SGSDySSAA25QueryParameterConvertible_pSgGys6ResultOyAA0A8ResponseVAA0A8SDKErrorCGctF) with the destination `url` and with headers or query parameters if needed. As you can see in the `completion` parameter, the `Callback` closure returns a [`BoxResponse`](https://opensource.box.com/box-ios-sdk/Structs/BoxResponse.html#/s:6BoxSDK0A8ResponseV7requestAA0A7RequestCvp) type. You can find the `body` of the response in `body` property, which is of type `Data?`. If you want to deserialize it to a specific type, you can do so as in the example below: ``` let fileId = "<YOUR_FILE_ID_HERE>" // Get information about a file. client.get(url: URL.boxAPIEndpoint("/2.0/files/\(fileId)", configuration: client.configuration)) { (result: Result<BoxResponse, BoxSDKError>) in let fileResult: Result<File, BoxSDKError> = result.flatMap { ObjectDeserializer.deserialize(data: $0.body)} switch fileResult { case .success(let file): print("File \(file.name) was created at \(file.createdAt)") case .failure(let error): print("Error retrieving file information") } } ``` As an alternative, to manually deserialize a response body, you can use [`ResponseHandler.default(wrapping completion:)`](https://opensource.box.com/box-ios-sdk/Enums/ResponseHandler.html#/s:6BoxSDK15ResponseHandlerO7default8wrappingys6ResultOyAA0aC0VAA0A8SDKErrorCGcyAGyxAKGc_tAA0A5ModelRzlFZ) method: ``` let fileId = "<YOUR_FILE_ID_HERE>" // Get information about a file. client.get( url: URL.boxAPIEndpoint("/2.0/files/\(fileId)", configuration: client.configuration), completion: ResponseHandler.default( wrapping: { (result: Result<File, BoxSDKError>) in switch result { case .success(let file): print("File \(file.name) was created at \(file.createdAt)") case .failure(let error): print("Error retrieving file information") } } ) ) ``` This method will make sure that the response is successful (status code 2xx) and will deserialize the response body into the appropriate type. In these examples above, we used existing SDKs type `File`, but this can be replaced with any custom type that conforms to either `Decodable` or `BoxModel`. ### Custom POST To perform a custom HTTP POST method, call [`client.post(url:httpHeaders:queryParameters:json:completion)`](https://opensource.box.com/box-ios-sdk/Classes/BoxClient.html#/s:6BoxSDK0A6ClientC4post3url11httpHeaders15queryParameters4json10completiony10Foundation3URLV_SDyS2SGSDySSAA25QueryParameterConvertible_pSgGypSgys6ResultOyAA0A8ResponseVAA0A8SDKErrorCGctF) with the `url`, `json` body and with headers or query parameters if needed. As you can see in the `completion` parameter, the `Callback` closure returns a [`BoxResponse`](https://opensource.box.com/box-ios-sdk/Structs/BoxResponse.html#/s:6BoxSDK0A8ResponseV7requestAA0A7RequestCvp) type. You can find the `body` of the response in `body` property, which is of type `Data?`. If you want to deserialize it to a specific type, you can do so as shown in the examples below: ``` var body: [String: Any] = [:] body["parent"] = ["id": "<YOUR_FOLDER_ID_HERE>"] body["url"] = "https://example.com" body["name"] = "example name" // Creates a new web link with the specified url on the specified folder. client.post(url: URL.boxAPIEndpoint("/2.0/web_links", configuration: client.configuration), json: body) { result in let webLinkResult: Result<WebLink, BoxSDKError> = result.flatMap { ObjectDeserializer.deserialize(data: $0.body) } switch webLinkResult { case .success(let webLink): print("WebLink \(webLink.name) was created") case .failure(let error): print("Error creating a webLink \(error)") } } ``` or ``` var body: [String: Any] = [:] body["parent"] = ["id": "<YOUR_FOLDER_ID_HERE>"] body["url"] = "https://example.com" body["name"] = "example name" // Creates a new web link with the specified url on the specified folder. client.post( url: URL.boxAPIEndpoint("/2.0/web_links", configuration: client.configuration), json: body, completion: ResponseHandler.default( wrapping: { (result: Result<WebLink, BoxSDKError>) in switch result { case .success(let webLink): print("WebLink \(webLink.name) was created") case .failure(let error): print("Error creating a webLink \(error)") } } ) ) ``` In these examples we deserialized `body` as `WebLink` type, but you can deserialize response's body to any custom type that conforms to either `Decodable` or `BoxModel`. ### Custom PUT To perform a custom HTTP PUT method, call [`client.put(url:httpHeaders:queryParameters:json:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/BoxClient.html#/s:6BoxSDK0A6ClientC3put3url11httpHeaders15queryParameters4json10completiony10Foundation3URLV_SDyS2SGSDySSAA25QueryParameterConvertible_pSgGypSgys6ResultOyAA0A8ResponseVAA0A8SDKErrorCGctF) with the `url`, `json` body and with headers or query parameters if needed. As you can see in the `completion` parameter, the `Callback` closure returns a [`BoxResponse`](https://opensource.box.com/box-ios-sdk/Structs/BoxResponse.html#/s:6BoxSDK0A8ResponseV7requestAA0A7RequestCvp) type. You can find the `body` of the response in `body` property, which is of type `Data?`. If you want to deserialize it to a specific type, you can do so as shown in the examples below: ``` let taskId = "<YOUR_TASK_ID_HERE>" var body = [String: Any]() body["message"] = "Please to this ASAP!" body["action"] = "review" // Updates a specific task. client.put(url: URL.boxAPIEndpoint("/2.0/tasks/\(taskId)", configuration: client.configuration), json: body) { result in let taskResult: Result<Task, BoxSDKError> = result.flatMap { ObjectDeserializer.deserialize(data: $0.body) } switch taskResult { case .success(let task): print("Task \(task.id) was updated") case .failure(let error): print("Error updating a task \(error)") } } ``` or ``` let taskId = "<YOUR_TASK_ID_HERE>" var body = [String: Any]() body["message"] = "Please to this ASAP!" body["action"] = "review" // Updates a specific task. client.put( url: URL.boxAPIEndpoint("/2.0/tasks/\(taskId)", configuration: client.configuration), json: body, completion: ResponseHandler.default( wrapping: { (result: Result<Task, BoxSDKError>) in switch result { case .success(let task): print("Task \(task.id) was updated") case .failure(let error): print("Error updating a task \(error)") } } ) ) ``` In these examples we deserialized `body` as `Task` type, but we can deserialize it to any custom type that conforms to either `Decodable` or `BoxModel`. ### Custom DELETE To perform a custom HTTP DELETE method, call [`client.delete(url:httpHeaders:queryParameters:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/BoxClient.html#/s:6BoxSDK0A6ClientC6delete3url11httpHeaders15queryParameters10completiony10Foundation3URLV_SDyS2SGSDySSAA25QueryParameterConvertible_pSgGys6ResultOyAA0A8ResponseVAA0A8SDKErrorCGctF) with the `url` and with headers and query parameters if needed. As you can see in the `completion` parameter, the `Callback` closure returns a [`BoxResponse`](https://opensource.box.com/box-ios-sdk/Structs/BoxResponse.html#/s:6BoxSDK0A8ResponseV7requestAA0A7RequestCvp) type. You can find the `body` of the response in `body` property, which is of type `Data?`. In most cases the `body` property on success will be just nil, so to handle this you can do as follows: ``` let fileId = "<YOUR_FILE_ID_HERE>" // Discards a file to the trash. client.delete(url: URL.boxAPIEndpoint("/2.0/files/\(fileId)", configuration: client.configuration)) { result in switch result { case .success: print("The file was deleted") case .failure(let error): print("Error deleting a file \(error)") } } ``` ### Custom OPTIONS To perform a custom HTTP OPTIONS method, call [`client.options(url:httpHeaders:queryParameters:json:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/BoxClient.html#/s:6BoxSDK0A6ClientC7options3url11httpHeaders15queryParameters4json10completionAA0A11NetworkTaskC10Foundation3URLV_SDyS2SGSDySSAA25QueryParameterConvertible_pSgGypSgys6ResultOyAA0A8ResponseVAA0A8SDKErrorCGctF) with the `url`, `json` body and with headers or query parameters if needed. As you can see in the `completion` parameter, the `Callback` closure returns a [`BoxResponse`](https://opensource.box.com/box-ios-sdk/Structs/BoxResponse.html#/s:6BoxSDK0A8ResponseV7requestAA0A7RequestCvp) type. You can find the `body` of the response in `body` property, which is of type `Data?`. ``` var body: [String: Any] = ["parent": ["id": "<YOUR_FOLDER_ID_HERE>"]] body["name"] = "<YOUR_FILE_NAME_HERE>" // Verifies that new file will be accepted by Box before you send all the bytes over the wire. client.options(url: URL.boxAPIEndpoint("/2.0/files/content", configuration: client.configuration)) { result in switch result { case .success: print("The file is verified successfully") case .failure(let error): print("Error verifying a file \(error)") } } ``` This example will return an empty response when the checks pass or an error when the checks fail. In case of an empty response, the user can proceed with making an upload call. ### Download To perform a HTTP GET method call for downloading on the API, call [`client.download(url:downloadDestinationURL:httpHeaders:queryParameters:progress:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/BoxClient.html#/s:6BoxSDK0A6ClientC7options3url11httpHeaders15queryParameters4json10completionAA0A11NetworkTaskC10Foundation3URLV_SDyS2SGSDySSAA25QueryParameterConvertible_pSgGypSgys6ResultOyAA0A8ResponseVAA0A8SDKErrorCGctF). You must specify `url` of the API endpoint to call `downloadDestinationURL`, which specifies the URL on a disk, where the data will be saved. The `completion` is a callback, which returns a [`BoxResponse`](https://opensource.box.com/box-ios-sdk/Structs/BoxResponse.html#/s:6BoxSDK0A8ResponseV7requestAA0A7RequestCvp) object or an error if request fails. Headers and query parameters are optional, so add them if needed. ``` let fileId = "<YOUR_FILE_ID_HERE>" let destinationURL = FileManager.default.urls(for: .documentDirectory, in: .userDomainMask).first!.appendingPathComponent("<FILE_NAME_HERE>") // Download a file to a specified folder. client.download( url: URL.boxAPIEndpoint("/2.0/files/\(fileId)/content", configuration: client.configuration), downloadDestinationURL: destinationURL ) { result in switch result { case .success: print("The file was downloaded") case .failure(let error): print("Error downloaded a file \(error)") } } ``` This example will return an empty response on success or an error on failure. ### Send To perform a send method, call [`client.send(request:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/BoxClient.html#/s:6BoxSDK0A6ClientC4send7request10completionyAA0A7RequestC_ys6ResultOyAA0A8ResponseVAA0A8SDKErrorCGctF) with the [`request`](https://opensource.box.com/box-ios-sdk/Classes/BoxRequest.html#/s:6BoxSDK0A7RequestC10httpMethod3url0D7Headers11queryParams4body19downloadDestination4task8progressAcA10HTTPMethodO_10Foundation3URLVSDyS2SGSDySSAA25QueryParameterConvertible_pSgGAC8BodyTypeOAPSgySo16NSURLSessionTaskCcySo10NSProgressCctcfc) object, which represents the Box SDK API request. As you can see in the `completion` parameter, the `Callback` closure returns a [`BoxResponse`](https://opensource.box.com/box-ios-sdk/Structs/BoxResponse.html#/s:6BoxSDK0A8ResponseV7requestAA0A7RequestCvp) type. You can find the `body` of the response in `body` property, which is of type `Data?`. When creating a `BoxRequest` instance, please call [`init(httpMethod:url:httpHeaders:queryParams:body:downloadDestination:task:progress:)`](https://opensource.box.com/box-ios-sdk/Classes/BoxRequest.html#/s:6BoxSDK0A7RequestC10httpMethod3url0D7Headers11queryParams4body19downloadDestination4task8progressAcA10HTTPMethodO_10Foundation3URLVSDyS2SGSDySSAA25QueryParameterConvertible_pSgGAC8BodyTypeOAPSgySo16NSURLSessionTaskCcySo10NSProgressCctcfc) with the parameters you need, leaving unused parameters with their default value. Below is an example of how we can use `send()` method to update a particular file: ``` let fileId = "<YOUR_FILE_ID_HERE>" var body: [String: Any] = [:] body["name"] = "new_file_name.txt" body["description"] = "new description" let request = BoxRequest( httpMethod: .put, url: URL.boxAPIEndpoint("/2.0/files/\(fileId)", configuration: client.configuration), queryParams: ["fields": "name,description"], body: .jsonObject(body) ) client.send(request: request) { result in let fileResult: Result<File, BoxSDKError> = result.flatMap { ObjectDeserializer.deserialize(data: $0.body) } switch fileResult { case let .success(fileItem): print("The file was updated successfully") case let .failure(error): print("Error updating a file \(error)") } } ``` This is an another example showing the use of the `send()` method to download a file: ``` let fileId = "<YOUR_FILE_ID_HERE>" let filename = "<YOUR_DESTINATION_FILE_NAME>" let destinationURL = FileManager.default.urls(for: .documentDirectory, in: .userDomainMask).first!.appendingPathComponent(filename) let task = BoxDownloadTask() let request = BoxRequest( httpMethod: .get, url: URL.boxAPIEndpoint("/2.0/files/\(fileId)/content", configuration: client.configuration), downloadDestination: destinationURL, task: task.receiveTask, progress: { progress in let completed = String(format: "%.2f", progress.fractionCompleted * 100) print("Completed... \(completed)%") } ) client.send(request: request) { result in switch result { case .success: print("The file was downloaded") case let .failure(error): print("Error downloaded a file \(error)") } } // If you want to cancel downloading a file, please call `task.cancel()` method. ``` --- ### Deprecation notice **Type:** page | **Section:** Additional Resources Deprecation notice This version of the Box Node SDK is under maintenance mode, and will be deprecated soon, only critical security updates… # Deprecation notice This version of the Box Node SDK is under maintenance mode, and will be deprecated soon, only critical security updates and bug fixes will be provided. We recommend using the new version Box Typescript SDK, which can be found at [box/box-typescript-sdk-gen](https://github.com/box/box-typescript-sdk-gen) You can find the migration guide [here](https://github.com/box/box-typescript-sdk-gen/blob/main/migration-guide.md) for transitioning from Box Node SDK to the new `box-typescript-sdk-gen` package. If you have any questions, please create an issue in the new repository or reach out to [Box Developer Support](https://developer.box.com/support/). # Box Node.js SDK [](https://snyk.io/test/github/box/box-node-sdk) [](http://opensource.box.com/badges) [](https://coveralls.io/github/box/box-node-sdk?branch=main) A Node.js interface to the [Box Content API](https://developer.box.com/reference/). - [Deprecation notice](#deprecation-notice) [Box Node.js SDK](#box-nodejs-sdk) - [Installation](#installation) - [Getting Started](#getting-started) [Creating API Clients](#creating-api-clients) - [Basic Client](#basic-client) - [Persistent Client](#persistent-client) - [App Auth Client](#app-auth-client) [Using the Client to Make API Calls](#using-the-client-to-make-api-calls) - [Constructing API Calls Manually](#constructing-api-calls-manually) [FIPS 140-2 Compliance](#fips-140-2-compliance) [Versions](#versions) - [Supported Version](#supported-version) - [Version schedule](#version-schedule) [Questions, Bugs, and Feature Requests?](#questions-bugs-and-feature-requests) [Contributing to the Box Node.js SDK](#contributing-to-the-box-nodejs-sdk) [Changelog](#changelog) [Upgrades](#upgrades) [Documentation](#documentation) [Copyright and License](#copyright-and-license) ## Installation Node SDK Installation [details](https://developer.box.com/guides/tooling/sdks/node/). ``` npm install --save box-node-sdk ``` ## Getting Started To get started with the SDK, get a Developer Token from the Configuration page of your platform app in the [Box Developer Console](https://app.box.com/developers/console). You can use this token to make test calls for your own Box account. ``` var BoxSDK = require('box-node-sdk'); // Initialize the SDK with your app credentials var sdk = new BoxSDK({ clientID: 'CLIENT_ID', clientSecret: 'CLIENT_SECRET', }); // Create a basic API client, which does not automatically refresh the access token var client = sdk.getBasicClient('DEVELOPER_TOKEN'); // Get your own user object from the Box API // All client methods return a promise that resolves to the results of the API call, // or rejects when an error occurs client.users .get(client.CURRENT_USER_ID) .then((user) => console.log('Hello', user.name, '!')) .catch((err) => console.log('Got an error!', err)); ``` ## Creating API Clients Clients are used to communicate with the API on behalf of a user. Box supports three different types of client: - **Basic Client:** Simple, makes calls via the given access token until the access token expires - **Persistent Client:** For use with traditional OAuth2 apps, can refresh its tokens automatically and persist them via a token store - **App Auth Client:** Uses the app auth JWT grant to act on behalf of app/managed users and create new tokens automatically ### Basic Client Returns a Box Client with a Basic API Session. The client is able to make requests on behalf of a user. A basic session has no access to a user's refresh token. Because of this, once the session's tokens expire the client cannot recover and a new session will need to be generated. ``` var client = BoxSDK.getBasicClient('ACCESS_TOKEN'); ``` ### Persistent Client Returns a Box Client with a persistent API session. A persistent API session helps manage the user's tokens, and can refresh them automatically if the access token expires. If a central data-store is given, the session can read & write tokens to it. NOTE: If tokenInfo or tokenStore are formatted incorrectly, this method will throw an error. If you haven't explicitly created either of these objects or are otherwise not completely confident in their validity, you should wrap your call to getPersistentClient in a try-catch to handle any potential errors. If you do not provide a token store object, the SDK will continue refreshing tokens locally as long as the Node.js process lives, but will not able to restore the user's authentication on process restart or share that authentication state between different processes. ``` var client = sdk.getPersistentClient(tokenInfo, null); ``` Providing a token store will allow the SDK to persist the user's authentication state so that you can resume making API calls as a user if the Node.js process needs to restart, or share the authentication state between multiple different processes. ``` var client = sdk.getPersistentClient(tokenInfo, tokenStore); ``` The token store is the interface used by persistent clients to interact with the consumer app's central storage layer. For a token store to be valid, it must have the following three methods: ``` store.read(function (err, data) {}); // read TokenInfo from app central store. store.write(tokenInfo, function (err, data) {}); // write TokenInfo to the app's central store. store.clear(function (err, data) {}); // delete TokenInfo from the app's central store. ``` Note that these methods don't pass in identifying information as arguments. You'll most likely need to create them on-demand for each client. ### App Auth Client App Auth allows an platform app to fully manage the Box accounts of its users; they do not have direct login credentials to Box and all operations are performed through the API using a JWT grant. If you have a JSON configuration file from the [Box Developer Console](https://app.box.com/developers/console) that includes your private key information, you can import that directly to create an SDK instance: ``` var sdkConfig = require('/path/to/config.json'); var sdk = BoxSDK.getPreconfiguredInstance(sdkConfig); // Get the service account client, used to create and manage app user accounts // The enterprise ID is pre-populated by the JSON configuration, // so you don't need to specify it here var serviceAccountClient = sdk.getAppAuthClient('enterprise'); // Get an app user or managed user client var appUserClient = sdk.getAppAuthClient('user', 'YOUR-APP-USER-ID'); ``` Otherwise, you can manually pass the necessary configuration parameters to the SDK: ``` var sdk = new BoxSDK({ clientID: 'CLIENT_ID', clientSecret: 'CLIENT_SECRET', appAuth: { keyID: 'PUBLIC_KEY_ID', privateKey: 'PRIVATE_KEY', passphrase: 'PRIVATE_KEY_PASSPHRASE', }, }); // Get the service account client, used to create and manage app user accounts var serviceAccountClient = sdk.getAppAuthClient( 'enterprise', 'APP_ENTERPRISE_ID' ); // Get an app user or managed user client var appUserClient = sdk.getAppAuthClient('user', 'YOUR-APP-USER-ID'); ``` ## Using the Client to Make API Calls The different API endpoints you can call are represented as methods, grouped into managers by the type of object they interact with. For example: ``` // Get the user object for the current user client.users .get(client.CURRENT_USER_ID) .then((currentUser) => { /* ... */ }) .catch((error) => { /* handle any errors */ }); // Update the name for folder with ID 123 client.folders .update('123', { name: 'New Folder Name' }) .then((folderInfo) => { /* ... */ }) .catch((error) => { /* handle any errors */ }); // Upload a new file to folder 123 client.files .uploadFile('123', 'bicycle.png', fileContents) .then((fileObject) => { /* ... */ }) .catch((error) => { /* handle any errors */ }); // Delete the comment with ID 456 client.comments .delete('456') .then(() => { /* ... */ }) .catch((error) => { /* handle any errors */ }); ``` For complete documentation about the available operations, please see the [SDK documentation pages](./docs) and the auto-generated [JSDocs](https://rawgit.com/box/box-node-sdk/main/docs/jsdoc/index.html). These contain detailed information about which methods are available and how to use them. ### Constructing API Calls Manually The SDK also exposes low-level request methods for constructing your own API calls. These can be useful for adding your own API calls that aren't yet explicitly supported by the SDK. The low-level methods always return a response object that contains the raw API response, and do not turn non-2xx status codes into errors like the normal client methods do. ``` // GET /files/123?fields=id,name client.get('/files/123', {qs: {fields: 'id,name'}}) .then(response => { /* ... */ }) .catch(error => { /* handle any errors */ }); // PUT /files/123 // { // "name": "New File Name" // } client.put('/files/123', {body: {name: 'New File Name'}}); .then(response => { /* ... */ }) .catch(error => { /* handle any errors */ }); // DELETE /files/123 client.del('/files/123'); .then(response => { /* ... */ }) .catch(error => { /* handle any errors */ }); ``` ## FIPS 140-2 Compliance The Box Node SDK allows the use of FIPS 140-2 validated SSL libraries, such as OpenSSL 3.0. However, some actions are required to enable this functionality. By default, the version of OpenSSL Node.js includes is not FIPS enabled. Therefore, if you want to use OpenSSL 3.0 with FIPS, you need to [build OpenSSL 3.0 with FIPS enabled](https://github.com/openssl/openssl/blob/master/README-FIPS.md) and then build Node.js use the shared OpenSSL 3.0 library. According to [Node.js OpenSSL Strategy](https://github.com/nodejs/TSC/blob/main/OpenSSL-Strategy.md) document, you can use the OpenSSL 3.0 from Node.js v16 or later. ## Versions We use a modified version of [Semantic Versioning](https://semver.org/) for all changes. See [version strategy](https://ja.developer.box.com/8249b54722608e671700c4582b0da591/VERSIONS.md) for details which is effective from 30 July 2022. ### Supported Version Only the current MAJOR version of SDK is supported. New features, functionality, bug fixes, and security updates will only be added to the current MAJOR version. A current release is on the leading edge of our SDK development, and is intended for customers who are in active development and want the latest and greatest features. Instead of stating a release date for a new feature, we set a fixed minor or patch release cadence of maximum 2-3 months (while we may release more often). At the same time, there is no schedule for major or breaking release. Instead, we will communicate one quarter in advance the upcoming breaking change to allow customers to plan for the upgrade. We always recommend that all users run the latest available minor release for whatever major version is in use. We highly recommend upgrading to the latest SDK major release at the earliest convenient time and before the EOL date. ### Version schedule | Version | Supported Environments | State | First Release | EOL/Terminated | | --- | --- | --- | --- | --- | | 3 | Node.js >= 14 and <= 20 | Supported | 23 May 2023 | TBD | | 2 | Node.js >= 8 and <= 14 | Maintained | 29 Sep 2021 | 23 Jul 2023 | | 1 | | EOL | 28 Mar 2019 | 29 Sep 2021 | ## Questions, Bugs, and Feature Requests? [Browse the issues tickets](https://github.com/box/box-node-sdk/issues)! Or, if that doesn't work, [file a new one](https://github.com/box/box-node-sdk/issues/new) and someone will get back to you. If you have general questions about the Box API, you can post to the [Box Developer Forum](https://community.box.com/t5/Developer-Forum/bd-p/DeveloperForum). ## Contributing to the Box Node.js SDK 1. Clone this repo. 2. Run `npm install`. 3. Run `npm test` to ensure everything is working. Make the changes you want in the `lib/` directory. Be sure to add corresponding tests in the `tests/` directory! 4. Run the unit tests by command `npm run test` and integration test as instructed [here](https://ja.developer.box.com/f7109e04501d1e9338129a54b95bd487/README.md). 5. Create a pull request with your changes — we'll review it and help you get it merged. Currently, the **Sign Request** module is generated automatically from OpenAPI specs. To re-generate this module, download the latest version of Box OpenAPI specs [here](https://raw.githubusercontent.com/box/box-openapi/en/openapi.json), save it to the root directory and run `npm run codegen`. For more information, please see [the Contribution guidelines](https://ja.developer.box.com/c36870c09fe3c52df7afbcb304196baf/CONTRIBUTING.md). ## Changelog See [CHANGELOG.md](https://ja.developer.box.com/64ac35fa5d9a1316c1c1e819c1da7b1d/CHANGELOG.md). ## Upgrades You can read about how to migrate to the new version [here](./docs/upgrade/). ## Documentation You can find guides and tutorials in the `docs` directory. - [Configuration](https://ja.developer.box.com/72e1f486598c9052135a57b2d613a50b/configuration.md) ## Copyright and License Copyright 2018 Box, Inc. All rights reserved. Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at [http://www.apache.org/licenses/LICENSE-2.0](http://www.apache.org/licenses/LICENSE-2.0) Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. --- ### Deprecation notice **Type:** page | **Section:** Additional Resources Deprecation notice This version of the Box Python SDK is under maintenance mode, and will be deprecated soon, only critical security updates… # Deprecation notice This version of the Box Python SDK is under maintenance mode, and will be deprecated soon, only critical security updates and bug fixes will be provided. We recommend using the new version Box Python SDK, which can be found at [box/box-python-sdk-gen](https://github.com/box/box-python-sdk-gen) You can find the migration guide [here](https://github.com/box/box-python-sdk-gen/blob/main/migration-guide.md) for transitioning from Box Python SDK v3.x to the new `box-sdk-gen` package. If you have any questions, please create an issue in the new repository or reach out to [Box Developer Support](https://developer.box.com/support/). # Box Python SDK [](http://opensource.box.com/badges) [](http://box-python-sdk.readthedocs.org/en/latest) [](https://github.com/box/box-python-sdk/actions) [](https://pypi.python.org/pypi/boxsdk) [](https://pypi.python.org/pypi/boxsdk) [](https://coveralls.io/github/box/box-python-sdk?branch=main) Getting Started Docs: [https://developer.box.com/guides/tooling/sdks/python/](https://developer.box.com/guides/tooling/sdks/python/) - [Deprecation notice](#deprecation-notice) - [Box Python SDK](#box-python-sdk) - [Installing](#installing) - [Getting Started](#getting-started) [Authorization](#authorization) - [Server-to-Server Auth with JWT](#server-to-server-auth-with-jwt) [Traditional 3-legged OAuth2](#traditional-3-legged-oauth2) - [Get the Authorization URL](#get-the-authorization-url) - [Authenticate (Get Access/Refresh Tokens)](#authenticate-get-accessrefresh-tokens) - [Create an Authenticated Client](#create-an-authenticated-client) - [Instantiate a Client Given an Access and a Refresh Token](#instantiate-a-client-given-an-access-and-a-refresh-token) [Other Auth Options](#other-auth-options) [Usage Documentation](#usage-documentation) - [Making API Calls Manually](#making-api-calls-manually) [Other Client Options](#other-client-options) - [Logging Client](#logging-client) - [Developer Token Client](#developer-token-client) - [Development Client](#development-client) [Customization](#customization) - [Custom Subclasses](#custom-subclasses) [FIPS 140-2 Compliance](#fips-140-2-compliance) [Versions](#versions) - [Supported Version](#supported-version) - [Version schedule](#version-schedule) [Contributing](#contributing) - [Developer Setup](#developer-setup) - [Testing](#testing) [Questions, Bugs, and Feature Requests?](#questions-bugs-and-feature-requests) [Copyright and License](#copyright-and-license) # Installing ``` pip install boxsdk ``` The current version of the SDK is v3.x --- With this release support for Python 3.5 and earlier (including 2.x) has been dropped. if you're looking for the code or documentation for v1.5.x, please see the 1.5 branch. # Getting Started To get started with the SDK, get a Developer Token from the Configuration page of your app in the Box Developer Console. You can use this token to make test calls for your own Box account. The SDK provides an interactive `DevelopmentClient` that makes it easy to test out the SDK in a REPL. This client will automatically prompt for a new Developer Token when it requires one, and will log HTTP requests and responses to aid in debugging and understanding how the SDK makes API calls. ``` >>> from boxsdk import DevelopmentClient >>> client = DevelopmentClient() Enter developer token: <ENTER DEVELOPER TOKEN HERE> >>> user = client.user().get() GET https://api.box.com/2.0/users/me {'headers': {'Authorization': '---wXyZ', 'User-Agent': 'box-python-sdk-2.0.0', 'X-Box-UA': 'agent=box-python-sdk/2.0.0; env=python/3.6.5'}, 'params': None} "GET https://api.box.com/2.0/users/me" 200 454 {'Date': 'Thu, 01 Nov 2018 23:32:11 GMT', 'Content-Type': 'application/json', 'Transfer-Encoding': 'chunked', 'Connection': 'keep-alive', 'Strict-Transport-Security': 'max-age=31536000', 'Cache-Control': 'no-cache, no-store', 'Content-Encoding': 'gzip', 'Vary': 'Accept-Encoding', 'BOX-REQUEST-ID': '0b50luc09ahp56m2jmkla8mgmh2', 'Age': '0'} {'address': '', 'avatar_url': 'https://cloud.app.box.com/api/avatar/large/123456789', 'created_at': '2012-06-07T11:14:50-07:00', 'id': '123456789', 'job_title': '', 'language': 'en', 'login': 'user@example.com', 'max_upload_size': 16106127360, 'modified_at': '2018-10-30T17:01:27-07:00', 'name': 'Example User', 'phone': '', 'space_amount': 1000000000000000.0, 'space_used': 14330018065, 'status': 'active', 'timezone': 'America/Los_Angeles', 'type': 'user'} >>> print(f'The current user ID is {user.id}') The current user ID is 123456789 ``` Outside of a REPL, you can initialize a new `Client` with just the Developer Token to get started. ``` from boxsdk import OAuth2, Client auth = OAuth2( client_id='YOUR_CLIENT_ID', client_secret='YOUR_CLIENT_SECRET', access_token='YOUR_DEVELOPER_TOKEN', ) client = Client(auth) user = client.user().get() print(f'The current user ID is {user.id}') ``` # Authorization The Box API uses OAuth2 for auth. The SDK makes it relatively painless to work with OAuth2 tokens. ## Server-to-Server Auth with JWT The Python SDK supports your JWT Authentication applications. Authenticating with a JWT requires some extra dependencies. To get them, simply ``` pip install "boxsdk[jwt]" ``` Instead of instantiating your `Client` with an instance of `OAuth2`, instead use an instance of `JWTAuth`. ``` from boxsdk import JWTAuth from boxsdk import Client auth = JWTAuth( client_id='YOUR_CLIENT_ID', client_secret='YOUR_CLIENT_SECRET', enterprise_id='YOUR_ENTERPRISE_ID', jwt_key_id='YOUR_JWT_KEY_ID', rsa_private_key_file_sys_path='CERT.PEM', rsa_private_key_passphrase='PASSPHRASE', ) access_token = auth.authenticate_instance() client = Client(auth) ``` This client is able to create application users: ``` ned_stark_user = client.create_user('Ned Stark') ``` These users can then be authenticated: ``` ned_auth = JWTAuth( client_id='YOUR_CLIENT_ID', client_secret='YOUR_CLIENT_SECRET', user=ned_stark_user, jwt_key_id='YOUR_JWT_KEY_ID', rsa_private_key_file_sys_path='CERT.PEM', rsa_private_key_passphrase='PASSPHRASE' ) ned_auth.authenticate_user() ned_client = Client(ned_auth) ``` Requests made with `ned_client` (or objects returned from `ned_client`'s methods) will be performed on behalf of the newly created app user. ## Traditional 3-legged OAuth2 ### Get the Authorization URL ``` from boxsdk import OAuth2 oauth = OAuth2( client_id='YOUR_CLIENT_ID', client_secret='YOUR_CLIENT_SECRET', store_tokens=your_store_tokens_callback_method, ) auth_url, csrf_token = oauth.get_authorization_url('http://YOUR_REDIRECT_URL') ``` store_tokens is a callback used to store the access token and refresh token. You might want to define something like this: ``` def store_tokens(access_token, refresh_token): # store the tokens at secure storage (e.g. Keychain) ``` The SDK will keep the tokens in memory for the duration of the Python script run, so you don't always need to pass store_tokens. ### Authenticate (Get Access/Refresh Tokens) If you navigate the user to the auth_url, the user will eventually get redirected to [http://YOUR_REDIRECT_URL?code=YOUR_AUTH_CODE](http://YOUR_REDIRECT_URL?code=YOUR_AUTH_CODE). After getting the code, you will be able to use the code to exchange for an access token and refresh token. The SDK handles all the work for you; all you need to do is run: ``` # Make sure that the csrf token you get from the `state` parameter # in the final redirect URI is the same token you get from the # get_authorization_url method. assert 'THE_CSRF_TOKEN_YOU_GOT' == csrf_token access_token, refresh_token = oauth.authenticate('YOUR_AUTH_CODE') ``` ### Create an Authenticated Client ``` from boxsdk import Client client = Client(oauth) ``` And that's it! You can start using the client to do all kinds of cool stuff and the SDK will handle the token refresh for you automatically. ### Instantiate a Client Given an Access and a Refresh Token Alternatively, you can instantiate an OAuth2 object with the access token and refresh token. Once you have an oauth object you can pass that into the Client object to instantiate a client and begin making calls. ``` from boxsdk import Client, OAuth2 oauth = OAuth2( client_id='YOUR_CLIENT_ID', client_secret='YOUR_CLIENT_SECRET', access_token='ACCESS_TOKEN', refresh_token='REFRESH_TOKEN', ) client = Client(oauth) user = client.user().get() ``` This will retrieve the current user! From here you can use the client you created to start making calls. ## Other Auth Options For advanced uses of the SDK, three additional auth classes are provided: `CooperativelyManagedOAuth2`: Allows multiple auth instances to share tokens. `RemoteOAuth2`: Allows use of the SDK on clients without access to your application's client secret. Instead, you provide a `retrieve_access_token` callback. That callback should perform the token refresh, perhaps on your server that does have access to the client secret. `RedisManagedOAuth2`: Stores access and refresh tokens in Redis. This allows multiple processes (possibly spanning multiple machines) to share access tokens while synchronizing token refresh. This could be useful for a multiprocess web server, for example. # Usage Documentation Full documentation of the available functionality with example code is available in the SDK documentation pages, and there is also method-level documentation available on [ReadTheDocs](https://box-python-sdk.readthedocs.io/en/stable/index.html). ## Making API Calls Manually The Box API is continually evolving. As such, there are API endpoints available that are not specifically supported by the SDK. You can still use these endpoints by using the `make_request` method of the `Client`. ``` # https://developer.box.com/en/reference/get-metadata-templates-id/ # Returns a Python dictionary containing the result of the API request json_response = client.make_request( 'GET', client.get_url('metadata_templates', 'enterprise', 'customer', 'schema'), ).json() ``` `make_request()` takes two parameters: - `method` - an HTTP verb like `GET` or `POST` - `url` - the URL of the requested API endpoint The `Client` class and Box objects have a `get_url` method. Pass it an endpoint to get the correct URL for use with that object and endpoint. For API calls which require body or query params, you can use `**kwargs` to pass extra params: - `data` - takes a jsonified dictionary of body parameters - `params` - takes a dictionary of query parameters ``` # https://developer.box.com/reference/post-folders/ # Creates a new folder # JSONify the body body = json.dumps({ 'name': 'test-subfolder', 'parent': { 'id': '0', } }) client.make_request( 'POST', client.get_url('folders'), params={'fields': 'name,id'}, data=body ) ``` # Other Client Options ## Logging Client For more insight into the network calls the SDK is making, you can use the `LoggingClient` class. This class logs information about network requests and responses made to the Box API. ``` >>> from boxsdk import LoggingClient >>> client = LoggingClient() >>> client.user().get() GET https://api.box.com/2.0/users/me {'headers': {u'Authorization': u'Bearer ---------------------------kBjp', u'User-Agent': u'box-python-sdk-1.5.0'}, 'params': None} {"type":"user","id":"..","name":"Jeffrey Meadows","login":"..",..} <boxsdk.object.user.User at 0x10615b8d0> ``` ## Developer Token Client The Box Developer Console allows for the creation of short-lived developer tokens. The SDK makes it easy to use these tokens. Use the `get_new_token_callback` parameter to control how the client will get new developer tokens as needed. The default is to prompt standard input for a token. ## Development Client For exploring the Box API, or to quickly get going using the SDK, the `DevelopmentClient` class combines the `LoggingClient` with the `DeveloperTokenClient`. # Customization ## Custom Subclasses Custom object subclasses can be defined: ``` from boxsdk import Client from boxsdk import Folder class MyFolderSubclass(Folder): pass client = Client(oauth) client.translator.register('folder', MyFolderSubclass) folder = client.folder('0') >>> print folder >>> <Box MyFolderSubclass - 0> ``` If an object subclass is registered in this way, instances of this subclass will be returned from all SDK methods that previously returned an instance of the parent. See `BaseAPIJSONObjectMeta` and `Translator` to see how the SDK performs dynamic lookups to determine return types. # FIPS 140-2 Compliance The Python SDK allows the use of FIPS 140-2 validated SSL libraries, such as OpenSSL 3.0. However, some actions are required to enable this functionality. Currently, the latest distributions of Python default to OpenSSL v1.1.1, which is not FIPS compliant. Therefore, if you want to use OpenSSL 3.0 in your network communication, you need to ensure that Python uses a custom SSL library. One way to achieve this is by creating a custom Python distribution with the ssl module replaced. If you are using JWT for authentication, it is also necessary to ensure that the cryptography library, which is one of the extra dependencies for JWT, uses OpenSSL 3.0. To enable FIPS mode for the `cryptography` library, you need to install a FIPS-compliant version of OpenSSL during the installation process of cryptography using the `pip` command. # Versions We use a modified version of [Semantic Versioning](https://semver.org/) for all changes. See [version strategy](https://ja.developer.box.com/27a720aa01575cc19988821a8bfea27a/VERSIONS.md) for details which is effective from 30 July 2022. ## Supported Version Only the current MAJOR version of SDK is supported. New features, functionality, bug fixes, and security updates will only be added to the current MAJOR version. A current release is on the leading edge of our SDK development, and is intended for customers who are in active development and want the latest and greatest features. Instead of stating a release date for a new feature, we set a fixed minor or patch release cadence of maximum 2-3 months (while we may release more often). At the same time, there is no schedule for major or breaking release. Instead, we will communicate one quarter in advance the upcoming breaking change to allow customers to plan for the upgrade. We always recommend that all users run the latest available minor release for whatever major version is in use. We highly recommend upgrading to the latest SDK major release at the earliest convenient time and before the EOL date. ## Version schedule | Version | Supported Environments | State | First Release | EOL/Terminated | | --- | --- | --- | --- | --- | | 3 | Python 3.6+ | Supported | 17 Jan 2022 | TBD | | 2 | | EOL | 01 Nov 2018 | 17 Jan 2022 | | 1 | | EOL | 10 Feb 2015 | 01 Nov 2018 | # Contributing See [CONTRIBUTING.md](https://github.com/box/box-python-sdk/blob/main/CONTRIBUTING.md). ## Developer Setup Create a virtual environment and install packages - ``` mkvirtualenv boxsdk pip install -r requirements-dev.txt ``` ## Testing Run all tests using - ``` tox ``` The tox tests include code style checks via pep8 and pylint. The tox tests are configured to run on Python 3.6, 3.7, 3.8, 3.9, 3.10, 3.11. # Questions, Bugs, and Feature Requests? Need to contact us directly? Browse the issues tickets! Or, if that doesn't work, file a new one and we will get back to you. If you have general questions about the Box API, you can post to the Box Developer Forum. # Copyright and License ``` Copyright 2019 Box, Inc. All rights reserved. Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ``` --- ### Deprecation notice **Type:** page | **Section:** Additional Resources Deprecation notice This version of the Box .NET SDK is under maintenance mode, and will be deprecated soon, only critical security updates… # Deprecation notice This version of the Box .NET SDK is under maintenance mode, and will be deprecated soon, only critical security updates and bug fixes will be provided. We recommend using the new version Box .NET SDK, which can be found at [box/box-dotnet-sdk-gen](https://github.com/box/box-dotnet-sdk-gen) You can find the migration guide [here](https://github.com/box/box-dotnet-sdk-gen/blob/main/migration-guide.md) for transitioning from Box .NET SDK v5.x to the new `box-sdk-gen` package. If you have any questions, please create an issue in the new repository or reach out to [Box Developer Support](https://developer.box.com/support/). # Box Windows V2 SDK [](http://opensource.box.com/badges) [](https://raw.githubusercontent.com/box/box-windows-sdk-v2/main/LICENSE) [](https://github.com/box/box-windows-sdk-v2/actions/workflows/build_and_test.yml) The Box .NET SDK can be used to make API calls to the Box APIs in a .NET project. The SDK is available for both .NET Framework 4.6.2 and .NET Core 2.0 or above. The installation of the SDK depends on the platform used. ## Table of contents [Getting Started](#getting-started) - [Installation](#installation) - [Authentication](#authentication) - [Sample Apps](#sample-apps) [Usage](#usage) [Other Resources](#additional-resources) [Versions](#versions) - [Supported Version](#supported-version) - [Version schedule](#version-schedule) [Questions, Bugs, and Feature Requests?](#questions-bugs-and-feature-requests) [Contributing](#contributing) [Copyright and License](#copyright-and-license) ## Getting Started ### Installation You can install SDK library using Nuget If you want to use .NET Core ``` PM> Install-Package Box.V2.Core ``` If you want to use .NET Framework ``` PM> Install-Package Box.V2 ``` Or you can add it to your project directly in Visual Studio. You can also download latest version from our [Github's release page](https://github.com/box/box-windows-sdk-v2/releases) ### Authentication Our .NET SDK supports the following authentication methods: - [Server Auth with JWT](https://ja.developer.box.com/docs/authentication.md#server-auth-with-jwt) - [Server Auth with CCG](https://ja.developer.box.com/docs/authentication.md#server-auth-with-ccg) - [Traditional 3-Legged OAuth2](https://ja.developer.box.com/docs/authentication.md#traditional-3-legged-oauth2) - [Developer token](https://ja.developer.box.com/docs/authentication.md#developer-token) ### Sample apps You can check one of our sample apps included in this repository to see how to use the SDK - [Create App User](https://github.com/box/box-windows-sdk-v2/tree/main/Box.V2.Samples.Core.AppUser.Create/) - [Upload File](https://github.com/box/box-windows-sdk-v2/tree/main/Box.V2.Samples.Core.File.Upload/) - [Proxy example](https://github.com/box/box-windows-sdk-v2/tree/main/Box.V2.Samples.Core.HttpProxy/) - [JWT Auth](https://github.com/box/box-windows-sdk-v2/tree/main/Box.V2.Samples.JWTAuth/) - [Token exchange](https://github.com/box/box-windows-sdk-v2/tree/main/Box.V2.Samples.TransactionalAuth/) ## Usage You can find detailed usage documentation and code samples under [docs](https://ja.developer.box.com/073643284ab50a43e5967b215e71c6f5/README.md) directory. ## Other resources - [API Reference](https://developer.box.com/reference/) - [API Guides](https://developer.box.com/guides/) - [SDK Nuget Package](https://www.nuget.org/packages/Box.V2/) - [.NET Core SDK Nuget Package](https://www.nuget.org/packages/Box.V2.Core/) - [Box Windows SDK Video Tutorial](https://youtu.be/hqko0hxbaXU) - [Getting Started Docs](https://developer.box.com/guides/tooling/sdks/dotnet/) ## Versions We use a modified version of [Semantic Versioning](https://semver.org/) for all changes. See [version strategy](https://ja.developer.box.com/c7a878a5913191d95b5d99cc09ba99b4/VERSIONS.md) for details which is effective from 30 July 2022. ### Supported Version Only the current MAJOR version of SDK is supported. New features, functionality, bug fixes, and security updates will only be added to the current MAJOR version. A current release is on the leading edge of our SDK development, and is intended for customers who are in active development and want the latest and greatest features. Instead of stating a release date for a new feature, we set a fixed minor or patch release cadence of maximum 2-3 months (while we may release more often). At the same time, there is no schedule for major or breaking release. Instead, we will communicate one quarter in advance the upcoming breaking change to allow customers to plan for the upgrade. We always recommend that all users run the latest available minor release for whatever major version is in use. We highly recommend upgrading to the latest SDK major release at the earliest convenient time and before the EOL date. ### Version schedule | Version | Supported Environments | State | First Release | EOL/Terminated | | --- | --- | --- | --- | --- | | 5 | .NET Framework 4.6.2+ and .NET Core 2.0+ | Supported | 02 Nov 2021 | TBD | | 4 | .NET Framework 4.5+ and .NET Core 2.0+ | EOL | 02 Nov 2021 | TBD | | 3 | | EOL | 28 Jul 2017 | 02 Nov 2021 | | 2 | | EOL | 05 Nov 2015 | 28 Jul 2017 | ### Migrating from the old version? If you are migrating from the old major version visit our [upgrade documentation](https://ja.developer.box.com/docs/upgrades/). ## Questions, Bugs, and Feature Requests? [Browse the issues tickets](https://github.com/box/box-windows-sdk-v2/issues)! Or, if that doesn't work, [file a new one](https://github.com/box/box-windows-sdk-v2/issues/new) and someone will get back to you. If you have general questions about the Box API, you can post to the [Box Developer Forum](https://community.box.com/t5/Developer-Forum/bd-p/DeveloperForum). ## Contributing All contributions to this project are welcome! For more information, please see our [Contribution guidelines](https://ja.developer.box.com/716d2fedae801ced680fadf955be1b2b/CONTRIBUTING.md). ## Copyright and License Copyright 2018 Box, Inc. All rights reserved. Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at [http://www.apache.org/licenses/LICENSE-2.0](http://www.apache.org/licenses/LICENSE-2.0) Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. --- ### Device Pins **Type:** page | **Section:** Additional Resources Device Pins Device pins allow enterprises to control what devices can use native Box applications. To learn more about device pinning… # Device Pins Device pins allow enterprises to control what devices can use native Box applications. To learn more about device pinning, please see the [Device Pinning documentation](https://community.box.com/t5/For-Admins/Device-Pinning-Overview-And-FAQs/ta-p/172). - [Get Device Pin](#get-device-pin) - [Delete Device Pin](#delete-device-pin) - [Get All Device Pins](#get-all-device-pins) ## Get Device Pin To get information about a specific device pin, call the [`devicePins.get(pinID, options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/DevicePins.html#get) method with the ID of the device pin. ``` client.devicePins.get('11111') .then(pin => { /* pin -> { type: 'device_pinner', id: '11111', owned_by: { type: 'user', id: '22222', name: 'Example User', login: 'user@example.com' }, product_name: 'iPad' } */ }); ``` ## Delete Device Pin To remove a specific device pin, call the [`devicePins.delete(pinID, options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/DevicePins.html#delete) method with the ID of the device pin. ``` client.devicePins.delete('28345') .then(() => { // deletion succeeded — no value returned }); ``` ## Get All Device Pins Get all device pins records for the current enterprise by calling the [`devicePins.getAll(options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/DevicePins.html#getAll) method. ``` client.devicePins.getAll() .then(pins => { /* pins -> { entries: [ { type: 'device_pinner', id: '11111', owned_by: { type: 'user', id: '22222', name: 'Example User', login: 'user@example.com' }, product_name: 'iPad' }, { type: 'device_pinner', id: '11112', owned_by: { type: 'user', id: '22222', name: 'Example User', login: 'user@example.com' }, product_name: 'iPhone' } ], limit: 100, order: [ { by: 'id', direction: 'ASC' } ] } */ }); ``` --- ### Device Pins **Type:** page | **Section:** Additional Resources Device Pins Device pinning is a feature that allows enterprise admins to pin their user’s corporate-managed Box account to a particular… # Device Pins Device pinning is a feature that allows enterprise admins to pin their user’s corporate-managed Box account to a particular mobile device or Box Sync client. - [List Enterprise Device Pins](#list-enterprise-device-pins) - [Get Device Pin Information](#get-device-pin-information) - [Delete Device Pin](#delete-device-pin) ## List Enterprise Device Pins To retrieve all device pins for an enterprise, call [`client.device_pinners(enterprise=None, limit=None, marker=None, direction=None, fields=None)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.client.html#boxsdk.client.client.Client.device_pinners). If an `enterprise` is not specified, this defaults to the current enterprise. This method returns a `BoxObjectCollection` that allows you to iterate over the [`DevicePinner`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.device_pinner.DevicePinner) objects in the collection. ``` device_pins = client.device_pinners() for pin in device_pins: print(f'Pinned {pin.product_name} device for {pin.owned_by.name}') ``` ## Get Device Pin Information To get information about a specific device pin, call [`device_pinner.get(*, fields=None, headers=None, **kwargs)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.base_object.BaseObject.get). This method returns a new [`DevicePinner`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.device_pinner.DevicePinner) object with fields populated by data from the API. ``` device_pin_id = '1111' device_pin = client.device_pinner(device_pin_id).get() print(f'{pin.product_name} device for {pin.owned_by.name} is pinned') ``` ## Delete Device Pin To delete a specific device pin, call [`device_pinner.delete()`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.base_object.BaseObject.delete). This method returns `True` to indicate that the deletion was successful. ``` device_pin_id = '1111' client.device_pin(device_pin_id).delete() print('Device pin deleted!') ``` --- ### Device Pins **Type:** page | **Section:** Additional Resources Device Pins Device pins allow enterprises to control what devices can use native Box applications. To learn more about device pinning… # Device Pins Device pins allow enterprises to control what devices can use native Box applications. To learn more about device pinning, please see the [Device Pinning documentation](https://community.box.com/t5/For-Admins/Device-Pinning-Overview-And-FAQs/ta-p/172). - [Get Enterprise Device Pins](#get-enterprise-device-pins) - [Get Device Pin](#get-device-pin) - [Delete Device Pin](#delete-device-pin) ## Get Enterprise Device Pins Get all device pins records for an enterprise by calling `DevicePinManager.GetEnterpriseDevicePinsAsync(string enterpriseId, string marker = null, int limit = 100, BoxSortDirection direction = BoxSortDirection.ASC, bool autoPaginate = false)`. ``` BoxCollectionMarkerBased<BoxDevicePin> pins = await client.DevicePinManager .GetEnterpriseDevicePinsAsync(enterpriseId: "12345"); ``` ## Get Device Pin To get information about a specific device pin, call `DevicePinManager.GetDevicePin(string id)` with the ID of the device pin object. ``` BoxDevicePin pin = await client.DevicePinManager.GetDevicePin(id: "11111"); ``` ## Delete Device Pin To remove a specific device pin, call `DevicePinManager.DeleteDevicePin(string id)` with the ID of the device pin to delete. ``` await client.DevicePinManager.DeleteDevicePin(id: "11111"); ``` --- ### Device Pins **Type:** page | **Section:** Additional Resources Device Pins Get Device Pin Info Get Device Pins for Enterprise Delete Device Pin Get Device Pin Info To retrieve information about a device… # Device Pins - [Get Device Pin Info](#get-device-pin-info) - [Get Device Pins for Enterprise](#get-device-pins-for-enterprise) - [Delete Device Pin](#delete-device-pin) ## Get Device Pin Info To retrieve information about a device pin, call [`client.devicepins.get(devicePinId: String, fields: [String]?, completion: @escaping Callback<DevicePin>)`](https://opensource.box.com/box-ios-sdk/Classes/DevicePinsModule.html#/s:6BoxSDK16DevicePinsModuleC3get11devicePinId6fields10completionySS_SaySSGSgys6ResultOyAA0cH0CAA0A8SDKErrorCGctF) with the ID of the device pin. You can control which fields are returned on the resulting `Device Pin` object by passing the desired field names in the optional `fields` parameter. ``` client.devicePins.get(devicePinId: "11111", fields: ["product_name"]) { (result: Result<DevicePin, BoxSDKError>) in guard case let .success(devicePin) = result else { print("Error retrieving device pin information") return } print("Device Pin for \(devicePin.productName) was created at \(devicePin.createdAt)") } ``` ## Get Device Pins for Enterprise To retrieve information about the device pins active for the enterprise, call [`client.devicePins.listForEnterprise(enterpriseId: String, marker: String?, limit: Int?, direction: OrdeDirection?, fields: [String]?)`](https://opensource.box.com/box-ios-sdk/Classes/DevicePinsModule.html#/s:6BoxSDK16DevicePinsModuleC17listForEnterprise12enterpriseId6marker5limit9direction6fields10completionySS_SSSgSiSgAA14OrderDirectionOSgSaySSGSgys6ResultOyAA14PagingIteratorCyAA0C3PinCGAA0A8SDKErrorCGctF) with the ID of the enterpise. This method will return an iterator, which is used to retrieve device pins for the enterprise. ``` let iterator = client.devicePins.listForEnterprise(enterpriseId: "12345", direction: .ascending) iterator.next { results in switch results { case let .success(page): for devicePin in page.entries { print("Device type: \(devicePin.productName)") } case let .failure(error): print(error) } } ``` ## Delete Device Pin To delete a device pin, call [`client.devicePins.delete(devicePinId: String, completion: @escaping: Callback<Void>)`](https://opensource.box.com/box-ios-sdk/Classes/DevicePinsModule.html#/s:6BoxSDK16DevicePinsModuleC6delete11devicePinId10completionySS_ys6ResultOyytAA0A8SDKErrorCGctF) with the ID of the device pin to delete. ``` client.devicePins.delete(devicePinId: "12345") { result: Result<Void, BoxSDKError> in guard case .success = result else { print("Error deleting device pin") return } print("Device Pin successfully deleted") } ``` --- ### Device Pins **Type:** page | **Section:** Additional Resources Device Pins Get Device Pin Info Get Device Pins for Enterprise Delete Device Pin Get Device Pin Info To retrieve information about a device… # Device Pins - [Get Device Pin Info](#get-device-pin-info) - [Get Device Pins for Enterprise](#get-device-pins-for-enterprise) - [Delete Device Pin](#delete-device-pin) ## Get Device Pin Info To retrieve information about a device pin, call [`client.devicepins.get(devicePinId: String, fields: [String]?, completion: @escaping Callback<DevicePin>)`](https://opensource.box.com/box-ios-sdk/Classes/DevicePinsModule.html#/s:6BoxSDK16DevicePinsModuleC3get11devicePinId6fields10completionySS_SaySSGSgys6ResultOyAA0cH0CAA0A8SDKErrorCGctF) with the ID of the device pin. You can control which fields are returned on the resulting `Device Pin` object by passing the desired field names in the optional `fields` parameter. ``` client.devicePins.get(devicePinId: "11111", fields: ["product_name"]) { (result: Result<DevicePin, BoxSDKError>) in guard case let .success(devicePin) = result else { print("Error retrieving device pin information") return } print("Device Pin for \(devicePin.productName) was created at \(devicePin.createdAt)") } ``` ## Get Device Pins for Enterprise To retrieve information about the device pins active for the enterprise, call [`client.devicePins.listForEnterprise(enterpriseId: String, marker: String?, limit: Int?, direction: OrdeDirection?, fields: [String]?)`](https://opensource.box.com/box-ios-sdk/Classes/DevicePinsModule.html#/s:6BoxSDK16DevicePinsModuleC17listForEnterprise12enterpriseId6marker5limit9direction6fields10completionySS_SSSgSiSgAA14OrderDirectionOSgSaySSGSgys6ResultOyAA14PagingIteratorCyAA0C3PinCGAA0A8SDKErrorCGctF) with the ID of the enterpise. This method will return an iterator, which is used to retrieve device pins for the enterprise. ``` let iterator = client.devicePins.listForEnterprise(enterpriseId: "12345", direction: .ascending) iterator.next { results in switch results { case let .success(page): for devicePin in page.entries { print("Device type: \(devicePin.productName)") } case let .failure(error): print(error) } } ``` ## Delete Device Pin To delete a device pin, call [`client.devicePins.delete(devicePinId: String, completion: @escaping: Callback<Void>)`](https://opensource.box.com/box-ios-sdk/Classes/DevicePinsModule.html#/s:6BoxSDK16DevicePinsModuleC6delete11devicePinId10completionySS_ys6ResultOyytAA0A8SDKErrorCGctF) with the ID of the device pin to delete. ``` client.devicePins.delete(devicePinId: "12345") { result: Result<Void, BoxSDKError> in guard case .success = result else { print("Error deleting device pin") return } print("Device Pin successfully deleted") } ``` --- ### DevicePinnersManager **Type:** page | **Section:** Additional Resources DevicePinnersManager Get device pin Remove device pin List enterprise device pins Get device pin Retrieves information about an individual… # DevicePinnersManager - [Get device pin](#get-device-pin) - [Remove device pin](#remove-device-pin) - [List enterprise device pins](#list-enterprise-device-pins) ## Get device pin Retrieves information about an individual device pin. This operation is performed by calling function `getDevicePinnerById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-device-pinners-id/). ``` await client.devicePinners.getDevicePinnerById(devicePinnerId); ``` ### Arguments devicePinnerId `string` - The ID of the device pin. Example: "2324234" optionalsInput `GetDevicePinnerByIdOptionalsInput` ### Returns This function returns a value of type `DevicePinner`. Returns information about a single device pin. ## Remove device pin Deletes an individual device pin. This operation is performed by calling function `deleteDevicePinnerById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-device-pinners-id/). ``` await client.devicePinners.deleteDevicePinnerById(devicePinnerId); ``` ### Arguments devicePinnerId `string` - The ID of the device pin. Example: "2324234" optionalsInput `DeleteDevicePinnerByIdOptionalsInput` ### Returns This function returns a value of type `undefined`. Returns an empty response when the pin has been deleted. ## List enterprise device pins Retrieves all the device pins within an enterprise. The user must have admin privileges, and the application needs the "manage enterprise" scope to make this call. This operation is performed by calling function `getEnterpriseDevicePinners`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-enterprises-id-device-pinners/). ``` await client.devicePinners.getEnterpriseDevicePinners(enterpriseId); ``` ### Arguments enterpriseId `string` - The ID of the enterprise. Example: "3442311" optionalsInput `GetEnterpriseDevicePinnersOptionalsInput` ### Returns This function returns a value of type `DevicePinners`. Returns a list of device pins for a given enterprise. --- ### DevicePinnersManager **Type:** page | **Section:** Additional Resources DevicePinnersManager Get device pin Remove device pin List enterprise device pins Get device pin Retrieves information about an individual… # DevicePinnersManager - [Get device pin](#get-device-pin) - [Remove device pin](#remove-device-pin) - [List enterprise device pins](#list-enterprise-device-pins) ## Get device pin Retrieves information about an individual device pin. This operation is performed by calling function `get_device_pinner_by_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-device-pinners-id/). ``` client.device_pinners.get_device_pinner_by_id(device_pinner_id) ``` ### Arguments device_pinner_id `str` - The ID of the device pin. Example: "2324234" extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `DevicePinner`. Returns information about a single device pin. ## Remove device pin Deletes an individual device pin. This operation is performed by calling function `delete_device_pinner_by_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-device-pinners-id/). ``` client.device_pinners.delete_device_pinner_by_id(device_pinner_id) ``` ### Arguments device_pinner_id `str` - The ID of the device pin. Example: "2324234" extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `None`. Returns an empty response when the pin has been deleted. ## List enterprise device pins Retrieves all the device pins within an enterprise. The user must have admin privileges, and the application needs the "manage enterprise" scope to make this call. This operation is performed by calling function `get_enterprise_device_pinners`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-enterprises-id-device-pinners/). ``` client.device_pinners.get_enterprise_device_pinners(enterprise_id) ``` ### Arguments enterprise_id `str` - The ID of the enterprise. Example: "3442311" marker `Optional[str]` - Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`. limit `Optional[int]` - The maximum number of items to return per page. direction `Optional[GetEnterpriseDevicePinnersDirection]` - The direction to sort results in. This can be either in alphabetical ascending (`ASC`) or descending (`DESC`) order. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `DevicePinners`. Returns a list of device pins for a given enterprise. --- ### Devices **Type:** page | **Section:** Additional Resources Devices Device pinning is a feature that allows enterprise admins to pin their user’s corporate-managed Box account to a particular mobile… # Devices Device pinning is a feature that allows enterprise admins to pin their user’s corporate-managed Box account to a particular mobile device or Box Sync client. - [Get Enterprise Device Pins](#get-enterprise-device-pins) - [Get Device Pin](#get-device-pin) - [Delete Device Pin](#delete-device-pin) ## Get Enterprise Device Pins Calling the static [`getEnterpriceDevicePins(BoxAPIConnection api, String enterpriseID, String... fields)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxDevicePin.html#getEnterpriceDevicePins-com.box.sdk.BoxAPIConnection-java.lang.String-java.lang.String...-) will return an iterable that will page through all of the device pins belongs to enterprise with given ID. It is possible to specify maximum number of retrieved items per single response by passing the maxiumum number of records to retrieve to [`getEnterpriceDevicePins(BoxAPIConnection api, String enterpriseID, int limit, String... fields)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxDevicePin.html#getEnterpriceDevicePins-com.box.sdk.BoxAPIConnection-java.lang.String-int-java.lang.String...-) ``` Iterable<BoxDevicePin.Info> enterpriseDevicePins = BoxDevicePin.getEnterpriceDevicePins(api, id); for (BoxDevicePin.Info devicePin : enterpriseDevicePins) { // Do something with the device pin. } ``` ## Get Device Pin Existing collections can be retrieved by calling the [`getInfo(String... fields)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxDevicePin.html#getInfo-java.lang.String...-) method. Optional parameters can be used to retrieve specific fields of the Device Pin object. ``` BoxDevicePin devicePin = new BoxDevicePin(api, id); BoxDevicePin.Info devicePinInfo = devicePin.getInfo(); ``` ## Delete Device Pin A device pin can be deleted by calling the [`delete()`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxDevicePin.html#delete--) method. ``` BoxDevicePin devicePin = new BoxDevicePin(api, id); devicePin.delete(); ``` --- ### DocgenManager **Type:** page | **Section:** Additional Resources DocgenManager Get Box Doc Gen job by ID List all Box Doc Gen jobs Get Box Doc Gen jobs by batch ID Generate document using Box Doc Gen… # DocgenManager - [Get Box Doc Gen job by ID](#get-box-doc-gen-job-by-id) - [List all Box Doc Gen jobs](#list-all-box-doc-gen-jobs) - [Get Box Doc Gen jobs by batch ID](#get-box-doc-gen-jobs-by-batch-id) - [Generate document using Box Doc Gen template](#generate-document-using-box-doc-gen-template) ## Get Box Doc Gen job by ID Get details of the Box Doc Gen job. This operation is performed by calling function `getDocgenJobByIdV2025R0`. See the endpoint docs at [API Reference](https://developer.box.com/reference/v2025.0/get-docgen-jobs-id/). ``` await client.docgen.getDocgenJobByIdV2025R0(docgenJobItemFromList.id); ``` ### Arguments jobId `string` - Box Doc Gen job ID. Example: 123 optionalsInput `GetDocgenJobByIdV2025R0OptionalsInput` ### Returns This function returns a value of type `DocGenJobV2025R0`. Details of the Box Doc Gen job. ## List all Box Doc Gen jobs Lists all Box Doc Gen jobs for a user. This operation is performed by calling function `getDocgenJobsV2025R0`. See the endpoint docs at [API Reference](https://developer.box.com/reference/v2025.0/get-docgen-jobs/). ``` await client.docgen.getDocgenJobsV2025R0({ limit: 10000, } satisfies GetDocgenJobsV2025R0QueryParams); ``` ### Arguments queryParams `GetDocgenJobsV2025R0QueryParams` - Query parameters of getDocgenJobsV2025R0 method headersInput `GetDocgenJobsV2025R0HeadersInput` - Headers of getDocgenJobsV2025R0 method cancellationToken `undefined | CancellationToken` - Token used for request cancellation. ### Returns This function returns a value of type `DocGenJobsFullV2025R0`. A list of Box Doc Gen jobs. ## Get Box Doc Gen jobs by batch ID Lists Box Doc Gen jobs in a batch. This operation is performed by calling function `getDocgenBatchJobByIdV2025R0`. See the endpoint docs at [API Reference](https://developer.box.com/reference/v2025.0/get-docgen-batch-jobs-id/). ``` await client.docgen.getDocgenBatchJobByIdV2025R0(docgenBatch.id); ``` ### Arguments batchId `string` - Box Doc Gen batch ID. Example: 123 optionalsInput `GetDocgenBatchJobByIdV2025R0OptionalsInput` ### Returns This function returns a value of type `DocGenJobsV2025R0`. Returns a list of Box Doc Gen jobs in a Box Doc Gen batch. ## Generate document using Box Doc Gen template Generates a document using a Box Doc Gen template. This operation is performed by calling function `createDocgenBatchV2025R0`. See the endpoint docs at [API Reference](https://developer.box.com/reference/v2025.0/post-docgen-batches/). ``` await client.docgen.createDocgenBatchV2025R0({ file: new FileReferenceV2025R0({ id: uploadedFile.id }), inputSource: 'api', destinationFolder: new DocGenBatchCreateRequestV2025R0DestinationFolderField({ id: folder.id, }), outputType: 'pdf', documentGenerationData: [ { generatedFileName: 'test', userInput: { ['abc']: 'xyz' }, } satisfies DocGenDocumentGenerationDataV2025R0, ], } satisfies DocGenBatchCreateRequestV2025R0); ``` ### Arguments requestBody `DocGenBatchCreateRequestV2025R0` - Request body of createDocgenBatchV2025R0 method optionalsInput `CreateDocgenBatchV2025R0OptionalsInput` ### Returns This function returns a value of type `DocGenBatchBaseV2025R0`. The created Batch ID. --- ### DocgenManager **Type:** page | **Section:** Additional Resources DocgenManager Get Box Doc Gen job by ID List all Box Doc Gen jobs Get Box Doc Gen jobs by batch ID Generate document using Box Doc Gen… # DocgenManager - [Get Box Doc Gen job by ID](#get-box-doc-gen-job-by-id) - [List all Box Doc Gen jobs](#list-all-box-doc-gen-jobs) - [Get Box Doc Gen jobs by batch ID](#get-box-doc-gen-jobs-by-batch-id) - [Generate document using Box Doc Gen template](#generate-document-using-box-doc-gen-template) ## Get Box Doc Gen job by ID Get details of the Box Doc Gen job. This operation is performed by calling function `get_docgen_job_by_id_v2025_r0`. See the endpoint docs at [API Reference](https://developer.box.com/reference/v2025.0/get-docgen-jobs-id/). ``` client.docgen.get_docgen_job_by_id_v2025_r0(docgen_job_item_from_list.id) ``` ### Arguments job_id `str` - Box Doc Gen job ID. Example: 123 box_version `BoxVersionHeaderV2025R0` - Version header. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `DocGenJobV2025R0`. Details of the Box Doc Gen job. ## List all Box Doc Gen jobs Lists all Box Doc Gen jobs for a user. This operation is performed by calling function `get_docgen_jobs_v2025_r0`. See the endpoint docs at [API Reference](https://developer.box.com/reference/v2025.0/get-docgen-jobs/). ``` client.docgen.get_docgen_jobs_v2025_r0(limit=10000) ``` ### Arguments marker `Optional[str]` - Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`. limit `Optional[int]` - The maximum number of items to return per page. box_version `BoxVersionHeaderV2025R0` - Version header. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `DocGenJobsFullV2025R0`. A list of Box Doc Gen jobs. ## Get Box Doc Gen jobs by batch ID Lists Box Doc Gen jobs in a batch. This operation is performed by calling function `get_docgen_batch_job_by_id_v2025_r0`. See the endpoint docs at [API Reference](https://developer.box.com/reference/v2025.0/get-docgen-batch-jobs-id/). ``` client.docgen.get_docgen_batch_job_by_id_v2025_r0(docgen_batch.id) ``` ### Arguments batch_id `str` - Box Doc Gen batch ID. Example: 123 marker `Optional[str]` - Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`. limit `Optional[int]` - The maximum number of items to return per page. box_version `BoxVersionHeaderV2025R0` - Version header. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `DocGenJobsV2025R0`. Returns a list of Box Doc Gen jobs in a Box Doc Gen batch. ## Generate document using Box Doc Gen template Generates a document using a Box Doc Gen template. This operation is performed by calling function `create_docgen_batch_v2025_r0`. See the endpoint docs at [API Reference](https://developer.box.com/reference/v2025.0/post-docgen-batches/). ``` client.docgen.create_docgen_batch_v2025_r0( FileReferenceV2025R0(id=uploaded_file.id), "api", CreateDocgenBatchV2025R0DestinationFolder(id=folder.id), "pdf", [ DocGenDocumentGenerationDataV2025R0( generated_file_name="test", user_input={"abc": "xyz"} ) ], ) ``` ### Arguments - file `FileReferenceV2025R0` - file_version `Optional[FileVersionBaseV2025R0]` input_source `str` - Source of input. The value has to be `api` for all the API-based document generation requests. destination_folder `CreateDocgenBatchV2025R0DestinationFolder` output_type `str` - Type of the output file. document_generation_data `List[DocGenDocumentGenerationDataV2025R0]` box_version `BoxVersionHeaderV2025R0` - Version header. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `DocGenBatchBaseV2025R0`. The created Batch ID. --- ### DocgenTemplateManager **Type:** page | **Section:** Additional Resources DocgenTemplateManager Create Box Doc Gen template List Box Doc Gen templates Delete Box Doc Gen template Get Box Doc Gen template by ID List… # DocgenTemplateManager - [Create Box Doc Gen template](#create-box-doc-gen-template) - [List Box Doc Gen templates](#list-box-doc-gen-templates) - [Delete Box Doc Gen template](#delete-box-doc-gen-template) - [Get Box Doc Gen template by ID](#get-box-doc-gen-template-by-id) - [List all Box Doc Gen template tags in template](#list-all-box-doc-gen-template-tags-in-template) - [Get list of all Box Doc Gen jobs for template](#get-list-of-all-box-doc-gen-jobs-for-template) ## Create Box Doc Gen template Marks a file as a Box Doc Gen template. This operation is performed by calling function `createDocgenTemplateV2025R0`. See the endpoint docs at [API Reference](https://developer.box.com/reference/v2025.0/post-docgen-templates/). ``` await client.docgenTemplate.createDocgenTemplateV2025R0({ file: new FileReferenceV2025R0({ id: file.id }), } satisfies DocGenTemplateCreateRequestV2025R0); ``` ### Arguments requestBody `DocGenTemplateCreateRequestV2025R0` - Request body of createDocgenTemplateV2025R0 method optionalsInput `CreateDocgenTemplateV2025R0OptionalsInput` ### Returns This function returns a value of type `DocGenTemplateBaseV2025R0`. The file which has now been marked as a Box Doc Gen template. ## List Box Doc Gen templates Lists Box Doc Gen templates on which the user is a collaborator. This operation is performed by calling function `getDocgenTemplatesV2025R0`. See the endpoint docs at [API Reference](https://developer.box.com/reference/v2025.0/get-docgen-templates/). ``` await client.docgenTemplate.getDocgenTemplatesV2025R0(); ``` ### Arguments queryParams `GetDocgenTemplatesV2025R0QueryParams` - Query parameters of getDocgenTemplatesV2025R0 method headersInput `GetDocgenTemplatesV2025R0HeadersInput` - Headers of getDocgenTemplatesV2025R0 method cancellationToken `undefined | CancellationToken` - Token used for request cancellation. ### Returns This function returns a value of type `DocGenTemplatesV2025R0`. Returns a collection of templates. ## Delete Box Doc Gen template Unmarks file as Box Doc Gen template. This operation is performed by calling function `deleteDocgenTemplateByIdV2025R0`. See the endpoint docs at [API Reference](https://developer.box.com/reference/v2025.0/delete-docgen-templates-id/). ``` await client.docgenTemplate.deleteDocgenTemplateByIdV2025R0( createdDocgenTemplate.file!.id, ); ``` ### Arguments templateId `string` - ID of the file which will no longer be marked as a Box Doc Gen template. Example: "123" optionalsInput `DeleteDocgenTemplateByIdV2025R0OptionalsInput` ### Returns This function returns a value of type `undefined`. Returns an empty response when a file is no longer marked as a Box Doc Gen template. ## Get Box Doc Gen template by ID Lists details of a specific Box Doc Gen template. This operation is performed by calling function `getDocgenTemplateByIdV2025R0`. See the endpoint docs at [API Reference](https://developer.box.com/reference/v2025.0/get-docgen-templates-id/). ``` await client.docgenTemplate.getDocgenTemplateByIdV2025R0( createdDocgenTemplate.file!.id, ); ``` ### Arguments templateId `string` - The ID of a Box Doc Gen template. Example: 123 optionalsInput `GetDocgenTemplateByIdV2025R0OptionalsInput` ### Returns This function returns a value of type `DocGenTemplateV2025R0`. Returns a template. ## List all Box Doc Gen template tags in template Lists all tags in a Box Doc Gen template. This operation is performed by calling function `getDocgenTemplateTagsV2025R0`. See the endpoint docs at [API Reference](https://developer.box.com/reference/v2025.0/get-docgen-templates-id-tags/). ``` await client.docgenTemplate.getDocgenTemplateTagsV2025R0( fetchedDocgenTemplate.file!.id, ); ``` ### Arguments templateId `string` - ID of template. Example: 123 optionalsInput `GetDocgenTemplateTagsV2025R0OptionalsInput` ### Returns This function returns a value of type `DocGenTagsV2025R0`. A list of document generation template tags.Processing tags for the file. ## Get list of all Box Doc Gen jobs for template Lists the users jobs which use this template. This operation is performed by calling function `getDocgenTemplateJobByIdV2025R0`. See the endpoint docs at [API Reference](https://developer.box.com/reference/v2025.0/get-docgen-template-jobs-id/). ``` await client.docgenTemplate.getDocgenTemplateJobByIdV2025R0( fetchedDocgenTemplate.file!.id, ); ``` ### Arguments templateId `string` - Id of template to fetch jobs for. Example: 123 optionalsInput `GetDocgenTemplateJobByIdV2025R0OptionalsInput` ### Returns This function returns a value of type `DocGenJobsV2025R0`. A single Box Doc Gen template. --- ### DocgenTemplateManager **Type:** page | **Section:** Additional Resources DocgenTemplateManager Create Box Doc Gen template List Box Doc Gen templates Delete Box Doc Gen template Get Box Doc Gen template by ID List… # DocgenTemplateManager - [Create Box Doc Gen template](#create-box-doc-gen-template) - [List Box Doc Gen templates](#list-box-doc-gen-templates) - [Delete Box Doc Gen template](#delete-box-doc-gen-template) - [Get Box Doc Gen template by ID](#get-box-doc-gen-template-by-id) - [List all Box Doc Gen template tags in template](#list-all-box-doc-gen-template-tags-in-template) - [Get list of all Box Doc Gen jobs for template](#get-list-of-all-box-doc-gen-jobs-for-template) ## Create Box Doc Gen template Marks a file as a Box Doc Gen template. This operation is performed by calling function `create_docgen_template_v2025_r0`. See the endpoint docs at [API Reference](https://developer.box.com/reference/v2025.0/post-docgen-templates/). ``` client.docgen_template.create_docgen_template_v2025_r0(FileReferenceV2025R0(id=file.id)) ``` ### Arguments - file `FileReferenceV2025R0` box_version `BoxVersionHeaderV2025R0` - Version header. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `DocGenTemplateBaseV2025R0`. The file which has now been marked as a Box Doc Gen template. ## List Box Doc Gen templates Lists Box Doc Gen templates on which the user is a collaborator. This operation is performed by calling function `get_docgen_templates_v2025_r0`. See the endpoint docs at [API Reference](https://developer.box.com/reference/v2025.0/get-docgen-templates/). ``` client.docgen_template.get_docgen_templates_v2025_r0() ``` ### Arguments marker `Optional[str]` - Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`. limit `Optional[int]` - The maximum number of items to return per page. box_version `BoxVersionHeaderV2025R0` - Version header. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `DocGenTemplatesV2025R0`. Returns a collection of templates. ## Delete Box Doc Gen template Unmarks file as Box Doc Gen template. This operation is performed by calling function `delete_docgen_template_by_id_v2025_r0`. See the endpoint docs at [API Reference](https://developer.box.com/reference/v2025.0/delete-docgen-templates-id/). ``` client.docgen_template.delete_docgen_template_by_id_v2025_r0( created_docgen_template.file.id ) ``` ### Arguments template_id `str` - ID of the file which will no longer be marked as a Box Doc Gen template. Example: "123" box_version `BoxVersionHeaderV2025R0` - Version header. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `None`. Returns an empty response when a file is no longer marked as a Box Doc Gen template. ## Get Box Doc Gen template by ID Lists details of a specific Box Doc Gen template. This operation is performed by calling function `get_docgen_template_by_id_v2025_r0`. See the endpoint docs at [API Reference](https://developer.box.com/reference/v2025.0/get-docgen-templates-id/). ``` client.docgen_template.get_docgen_template_by_id_v2025_r0( created_docgen_template.file.id ) ``` ### Arguments template_id `str` - The ID of a Box Doc Gen template. Example: 123 box_version `BoxVersionHeaderV2025R0` - Version header. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `DocGenTemplateV2025R0`. Returns a template. ## List all Box Doc Gen template tags in template Lists all tags in a Box Doc Gen template. This operation is performed by calling function `get_docgen_template_tags_v2025_r0`. See the endpoint docs at [API Reference](https://developer.box.com/reference/v2025.0/get-docgen-templates-id-tags/). ``` client.docgen_template.get_docgen_template_tags_v2025_r0( fetched_docgen_template.file.id ) ``` ### Arguments template_id `str` - ID of template. Example: 123 template_version_id `Optional[str]` - Id of template version. marker `Optional[str]` - Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`. limit `Optional[int]` - The maximum number of items to return per page. box_version `BoxVersionHeaderV2025R0` - Version header. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `DocGenTagsV2025R0`. A list of document generation template tags.Processing tags for the file. ## Get list of all Box Doc Gen jobs for template Lists the users jobs which use this template. This operation is performed by calling function `get_docgen_template_job_by_id_v2025_r0`. See the endpoint docs at [API Reference](https://developer.box.com/reference/v2025.0/get-docgen-template-jobs-id/). ``` client.docgen_template.get_docgen_template_job_by_id_v2025_r0( fetched_docgen_template.file.id ) ``` ### Arguments template_id `str` - Id of template to fetch jobs for. Example: 123 marker `Optional[str]` - Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`. limit `Optional[int]` - The maximum number of items to return per page. box_version `BoxVersionHeaderV2025R0` - Version header. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `DocGenJobsV2025R0`. A single Box Doc Gen template. --- ### Documentation **Type:** page | **Section:** Additional Resources Documentation High-level Documentation General explanations of the available functionality and examples of how to use the SDK are available… # Documentation ## High-level Documentation General explanations of the available functionality and examples of how to use the SDK are available by topic: - [Authentication](https://ja.developer.box.com/d428a57bd4889ec8d15c393c4114f1d7/authentication.md) - [Client](https://ja.developer.box.com/143730815748e8d3be0de65a363b9f8b/client.md) - [Classifications](https://ja.developer.box.com/f1bf41dc1b0fa806f014f8c5ef66398f/classifications.md) - [Collaborations](https://ja.developer.box.com/a8deacbf7c7aec0bf5d2517167dfecc6/collaborations.md) - [Collaboration Allowlist](https://ja.developer.box.com/2bbe0b98b335c979acdd08be3d43d01d/collaboration-allowlist.md) - [Collections](https://ja.developer.box.com/e25161cb12e3320d1ab928f547797536/collections.md) - [Comments](https://ja.developer.box.com/110e688c968175285555001234bea4a1/comments.md) - [Device Pins](https://ja.developer.box.com/a4977220196aa51be31dad6990f4ae60/device-pins.md) - [Enterprise](https://ja.developer.box.com/0a1036051f4ab42add3e8ef488c65a7f/enterprise.md) - [Events](https://ja.developer.box.com/9da434c92a42385439c07666754720bb/events.md) - [Files](https://ja.developer.box.com/e37f8e07a0bbd3ad10865b2ab07fa4b5/files.md) - [File Requests](https://ja.developer.box.com/44e15a1734d3dd965d5774c18f6ec359/file_requests.md) - [Folders](https://ja.developer.box.com/cd22d73c970edf75b3964c50a3003bef/folders.md) - [Groups](https://ja.developer.box.com/80a71872d2ae5176890767a525c6a5f5/groups.md) - [Information Barrier Reports](https://ja.developer.box.com/6d14a2360a53849697dbdedf4e39bf9f/information-barrier-reports.md) - [Information Barrier Segment Members](https://ja.developer.box.com/84ed112835c93ff408943ba34868b730/information-barrier-segment-members.md) - [Information Barrier Segment Restrictions](https://ja.developer.box.com/de07196d0920c283a27c06e9453c3444/information-barrier-segment-restrictions.md) - [Information Barrier Segments](https://ja.developer.box.com/c8e42c03df1b5f368b74b4bbd89518a5/information-barrier-segments.md) - [Information Barriers](https://ja.developer.box.com/a9f6c7490eb1e535308567b42c7a2bd2/information-barriers.md) - [Integration Mappings](https://ja.developer.box.com/762a2604c694072de7128e07c0d2da3e/integration-mappings.md) - [Legal Hold Policies](https://ja.developer.box.com/f6f9f00b76b159cd8a4615a55416f8de/legal-hold-policies.md) - [Metadata](https://ja.developer.box.com/11257628e7a6027222a06363c4d3b2a2/metadata.md) - [Recent Items](https://ja.developer.box.com/4d81cc8152b9a29d4fa3be3b89640b0c/recent-items.md) - [Retention Policies](https://ja.developer.box.com/5a3d805495d4cc495cbe519f249b98bc/retention-policies.md) - [Search](https://ja.developer.box.com/283a3b0a03bb048565dd7d2d4e35f6e1/search.md) - [Shared Items](https://ja.developer.box.com/133dd18558863edd0de21f2f1ac4931a/shared-items.md) - [Sign Requests](https://ja.developer.box.com/48757b9e5a5f08e38fe3d1ea75213815/sign-requests.md) - [Sign Templates](https://ja.developer.box.com/8eb7b125724b23302549c217b7afe0a8/sign-templates.md) - [Storage Policies](https://ja.developer.box.com/127ef6eef52e4e56f73da7cb35736016/storage-policies.md) - [Tasks](https://ja.developer.box.com/fb582628bcdf34bacd84485ad8b1720b/tasks.md) - [Terms of Service](https://ja.developer.box.com/932f3810fb86d1a28be4edb39d4c82da/terms-of-service.md) - [Trash](https://ja.developer.box.com/a103079767ff771d1548093312b2b9fc/trash.md) - [Users](https://ja.developer.box.com/4518ab9f39785de366b4be251298c810/users.md) - [Watermarking](https://ja.developer.box.com/a73c217b233a91b80963baed59afb8a0/watermarking.md) - [Web Links](https://ja.developer.box.com/6480363d7eaf8fd9dd2a51782e2a2c5b/web-links.md) - [Webhooks](https://ja.developer.box.com/6efbed44c155682758bada5b9d5a8af5/webhooks.md) ## JSDocs In-depth documentation of available functions is also available via autogenerated [JSDocs](https://rawgit.com/box/box-node-sdk/main/docs/jsdoc/index.html). --- ### Documentation **Type:** page | **Section:** Additional Resources Documentation Under this directory you can find documentation and samples for available SDK functionalities. You can read more about… # Documentation Under this directory you can find documentation and samples for available SDK functionalities. You can read more about supported resources on [API reference](https://developer.box.com/reference/). - [AI](https://ja.developer.box.com/8d9194c240d49364c959eca2716c7608/ai.md) - [Authentication](https://ja.developer.box.com/dc0b3fa5b0ea1869810d2d55e9f55c28/authentication.md) - [Classifications](https://ja.developer.box.com/e38c515b24db20e4210c77b13331dd52/classifications.md) - [Collaboration Whitelist](https://ja.developer.box.com/b1fba4d73980e5874e8dc99d2cf3ddb8/collaboration-whitelist.md) - [Collaborations](https://ja.developer.box.com/58e0e1821ee0a05dcdbafe44e03c3de7/collaborations.md) - [Collections](https://ja.developer.box.com/c11206078efcf1bb9ce312f873251ba1/collections.md) - [Comments](https://ja.developer.box.com/4d285c8d4bb98247c48a7543455045b8/comments.md) - [Custom Requests](https://ja.developer.box.com/eeb4f476732acae1e7c6e6a41f518a17/custom-requests.md) - [Device Pins](https://ja.developer.box.com/c069701b826cdabfda54838e3b933b03/device-pins.md) - [Events](https://ja.developer.box.com/7156e10b9a2bc1ac9fdd62023d2796c9/events.md) - [File Request](https://ja.developer.box.com/df34f284d818af36bd0f76554e30930e/file-request.md) - [Files](https://ja.developer.box.com/5e57c9b7d8c81b1a020e7ea8f72ed9e7/files.md) - [Folders](https://ja.developer.box.com/f7e5ee16179fb52e8c10b592706847ad/folders.md) - [Groups](https://ja.developer.box.com/5fbab21d27cb975e2e3e5c618584a70d/groups.md) - [Legal Holds](https://ja.developer.box.com/95c21f32b98d90bea3114865f9e35ef0/legal-holds.md) - [Metadata Cascade Policies](https://ja.developer.box.com/91bfa832e8bc14d7574df20f558f7728/metadata-cascade-policies.md) - [Metadata](https://ja.developer.box.com/98957703715f3b88682a57c875071faf/metadata.md) - [Recent Items](https://ja.developer.box.com/c4bb23a06ea068823f68b3539db9fe63/recent-items.md) - [Retention Policies](https://ja.developer.box.com/0c5b0cd42026ceeb98cfdaef6059bf29/retention-policies.md) - [Search](https://ja.developer.box.com/123af590125abb1ddf7dfb7333d4f56c/search.md) - [Sign Requests](https://ja.developer.box.com/5e5d6b89b951b0140a2ec01686a96ebf/sign-requests.md) - [Sign Templates](https://ja.developer.box.com/9cdc629d22368a7fb9cc95c61706f1b2/sign-templates.md) - [Storage Policies](https://ja.developer.box.com/fb436b8d8804345e7e518c1e71b4c5d2/storage-policies.md) - [Tasks](https://ja.developer.box.com/2c543d54a5e3bb41a14045e5010e69e4/tasks.md) - [Terms Of Service](https://ja.developer.box.com/932773402c917580e62d4e787fcc857f/terms-of-service.md) - [Trash](https://ja.developer.box.com/159479202d344b8e488cb46b149ca4f9/trash.md) - [Users](https://ja.developer.box.com/749e66ffbf22bbc2c85dc0ff92edce27/users.md) - [Watermarking](https://ja.developer.box.com/d8c02a5cba2726a9e91a9f27f83d58bc/watermarking.md) - [Web Links](https://ja.developer.box.com/84d08d8a630c73d35ec485f1a9c41ced/web-links.md) - [Webhooks](https://ja.developer.box.com/9822d3af25f6eb5dbec34de1488e7b90/webhooks.md) --- ### Documentation **Type:** page | **Section:** Additional Resources Documentation High-level Documentation General explanations of the available functionality and examples of how to use the SDK are available… # Documentation ## High-level Documentation General explanations of the available functionality and examples of how to use the SDK are available by topic: - [Ai](https://ja.developer.box.com/fc42e321d2401ca0f6fe6f7e5ec20811/ai.md) - [Ai studio](https://ja.developer.box.com/8822997d67c91efdef77e9832080d4e1/aiStudio.md) - [App item associations](https://ja.developer.box.com/4034943d9e64ff39152dc3139f382930/appItemAssociations.md) - [Archives](https://ja.developer.box.com/03c7bbda6842fb29e607240095f13bfd/archives.md) - [Authorization](https://ja.developer.box.com/54db4bdfd48f3a6ec39ff167cf37866f/authorization.md) - [Avatars](https://ja.developer.box.com/7c3b30e7558d2a2b891bff3612cf9c5a/avatars.md) - [Chunked uploads](https://ja.developer.box.com/1bf542cbafed560ad041597c2e669b10/chunkedUploads.md) - [Classifications](https://ja.developer.box.com/7cd4dee4c8a39f7c49339926c04a1727/classifications.md) - [Collaboration allowlist entries](https://ja.developer.box.com/fefd69a7143c658da785ee8faf12e287/collaborationAllowlistEntries.md) - [Collaboration allowlist exempt targets](https://ja.developer.box.com/786501d756036bb7e91c363f879c6bbf/collaborationAllowlistExemptTargets.md) - [Collections](https://ja.developer.box.com/387abdb9c87dbbca0a7976c7e646f0bc/collections.md) - [Comments](https://ja.developer.box.com/5d89e1ff5d912ce9d6080560dbadbc14/comments.md) - [Device pinners](https://ja.developer.box.com/4ca72e5d948fc5485c6323931210c54d/devicePinners.md) - [Docgen](https://ja.developer.box.com/2714459337fc73828d66b04638378a84/docgen.md) - [Docgen template](https://ja.developer.box.com/ff7ab59ba903f6dc3bf5bd0548a55be3/docgenTemplate.md) - [Downloads](https://ja.developer.box.com/80f4868fdb960ff18c3bba8461ccefbb/downloads.md) - [Email aliases](https://ja.developer.box.com/ceaf283ee1976470bad67502d0c28b2d/emailAliases.md) - [Events](https://ja.developer.box.com/f1850d50f91fe5198f93afe29989c943/events.md) - [File classifications](https://ja.developer.box.com/167f08e301ea6c001265fba1e76c2c96/fileClassifications.md) - [File metadata](https://ja.developer.box.com/94ee1bf2763b45f6153f538236dc1612/fileMetadata.md) - [File requests](https://ja.developer.box.com/575355bac34130141841d217f6a657b0/fileRequests.md) - [File version legal holds](https://ja.developer.box.com/4ef97fec6c26bafa9ce8404356a5149c/fileVersionLegalHolds.md) - [File version retentions](https://ja.developer.box.com/b01b11eec48e9c775d002a333a1aa7c0/fileVersionRetentions.md) - [File versions](https://ja.developer.box.com/7b8b55e23fff06d0b6bcad2d313caeea/fileVersions.md) - [File watermarks](https://ja.developer.box.com/57cf27e58b81c4f89366758c08ba5447/fileWatermarks.md) - [Files](https://ja.developer.box.com/aa3d852da4ce11a548a6d62adfdaa3b7/files.md) - [Folder classifications](https://ja.developer.box.com/381e7a37b9c5e10f49114be777a6298c/folderClassifications.md) - [Folder locks](https://ja.developer.box.com/8a8fc37fc424948206c922024d88b576/folderLocks.md) - [Folder metadata](https://ja.developer.box.com/90c6a5cae9698e12462d169cd99fa132/folderMetadata.md) - [Folder watermarks](https://ja.developer.box.com/89888806b209dd3b28963340156b9605/folderWatermarks.md) - [Folders](https://ja.developer.box.com/8605da97a3a372ed9e2cad4a4ae42b15/folders.md) - [Groups](https://ja.developer.box.com/9852d820fbf91c6823cd938abf5ff29b/groups.md) - [Hub collaborations](https://ja.developer.box.com/58b33abec097635b202dc68d24c6c6aa/hubCollaborations.md) - [Hub items](https://ja.developer.box.com/089a7a2d714ef7dac8f630856ba131c8/hubItems.md) - [Hubs](https://ja.developer.box.com/06670926823945d5279e5d4cf62b91d1/hubs.md) - [Integration mappings](https://ja.developer.box.com/ea609e4da1a3e8be97f5cd3d8bfc8ec7/integrationMappings.md) - [Invites](https://ja.developer.box.com/570713a7f115e71ef94d2a31f91799d1/invites.md) - [Legal hold policies](https://ja.developer.box.com/f3c35a6cf28e239368a70c608a3b5eeb/legalHoldPolicies.md) - [Legal hold policy assignments](https://ja.developer.box.com/766e57e7ae862c1295aa97ebec2108e3/legalHoldPolicyAssignments.md) - [List collaborations](https://ja.developer.box.com/460f4df77c97e7a9dfe2771e42552f41/listCollaborations.md) - [Memberships](https://ja.developer.box.com/f9c0cc93abbed99477cb81bc2cee32f7/memberships.md) - [Metadata cascade policies](https://ja.developer.box.com/9de5dfde89750a42b5bef529b8d2b473/metadataCascadePolicies.md) - [Metadata templates](https://ja.developer.box.com/4b660eca31fb1d104018b476be30fc93/metadataTemplates.md) - [Recent items](https://ja.developer.box.com/e8464b93cdec65c4240e9a81184537dd/recentItems.md) - [Retention policies](https://ja.developer.box.com/4e5d789921f45688d198727e3c819442/retentionPolicies.md) - [Retention policy assignments](https://ja.developer.box.com/2a31d25ec24ac3f250d27f7747c03e1b/retentionPolicyAssignments.md) - [Search](https://ja.developer.box.com/c1f609590852cf05b33789df60c5a2a0/search.md) - [Session termination](https://ja.developer.box.com/008b747050b6524e6f57d8171f0ee468/sessionTermination.md) - [Shared links app items](https://ja.developer.box.com/b309bf564a6ff77fb7febda29f0450ae/sharedLinksAppItems.md) - [Shared links files](https://ja.developer.box.com/63dbc250e82521bacec64f9131840628/sharedLinksFiles.md) - [Shared links folders](https://ja.developer.box.com/f41a61a94c970f9780a93ebf59659dde/sharedLinksFolders.md) - [Shared links web links](https://ja.developer.box.com/273993f9ac7054ef527aa10d984fcdf2/sharedLinksWebLinks.md) - [Shield information barrier reports](https://ja.developer.box.com/3bc57ac1d4eaf4eca2d5d769ee84fdf1/shieldInformationBarrierReports.md) - [Shield information barrier segment members](https://ja.developer.box.com/7519790d3212be1e03e5ea77974af8e6/shieldInformationBarrierSegmentMembers.md) - [Shield information barrier segment restrictions](https://ja.developer.box.com/f0ec9d47cec408877261f55b58fc45e1/shieldInformationBarrierSegmentRestrictions.md) - [Shield information barrier segments](https://ja.developer.box.com/41b908f45bb5085e90cd70d1ba67a542/shieldInformationBarrierSegments.md) - [Shield information barriers](https://ja.developer.box.com/e3c23e60a043f54945a1dd9a63eb3852/shieldInformationBarriers.md) - [Shield lists](https://ja.developer.box.com/4d261bc4440e84e5b99f721eeb2956cc/shieldLists.md) - [Sign requests](https://ja.developer.box.com/07171b3c0c1cf0495a9aa54fa1c12c89/signRequests.md) - [Sign templates](https://ja.developer.box.com/6e4e135ed584d32f8c8fcd3dfcf258fe/signTemplates.md) - [Skills](https://ja.developer.box.com/2069b036c3e063717f1ba5c295b69369/skills.md) - [Storage policies](https://ja.developer.box.com/9d06b1b430c4a84e5e11b5f3b8c3d472/storagePolicies.md) - [Storage policy assignments](https://ja.developer.box.com/77a6621be0c09237fa869d5366ce04a1/storagePolicyAssignments.md) - [Task assignments](https://ja.developer.box.com/fd631f75e820875193cccb1cb27e5617/taskAssignments.md) - [Tasks](https://ja.developer.box.com/116e16a33227b329ae30ac6a68f9b316/tasks.md) - [Terms of service user statuses](https://ja.developer.box.com/86f8d1fe48e9b4bc997a4dfdd1c5b578/termsOfServiceUserStatuses.md) - [Terms of services](https://ja.developer.box.com/3f9018652046f755ba2c4f482bcec9c3/termsOfServices.md) - [Transfer](https://ja.developer.box.com/127d549d1ccfa1875e86ee3d271060de/transfer.md) - [Trashed files](https://ja.developer.box.com/f71fe80a773ee514f5867da629ca5d78/trashedFiles.md) - [Trashed folders](https://ja.developer.box.com/c5e78e27035cfb6433141e273b307358/trashedFolders.md) - [Trashed items](https://ja.developer.box.com/48aa1a5148c0149fffb3a64456a822f0/trashedItems.md) - [Trashed web links](https://ja.developer.box.com/348ae3e1fa3897632a53b9ee47955033/trashedWebLinks.md) - [Uploads](https://ja.developer.box.com/05b776ce26018b8d33b958a8ee419e8b/uploads.md) - [User collaborations](https://ja.developer.box.com/250b562d65a6727f865a1395773d8104/userCollaborations.md) - [Users](https://ja.developer.box.com/b2654a7dce5bf1ad888991ccd8496ab7/users.md) - [Web links](https://ja.developer.box.com/eeb85371c138f2c0492fc01a22eb5424/webLinks.md) - [Webhooks](https://ja.developer.box.com/b7cfc413355f7af7206ec4e1f9d71828/webhooks.md) - [Workflows](https://ja.developer.box.com/d10e200014d42126c441e15bff385374/workflows.md) - [Zip downloads](https://ja.developer.box.com/721efe8523b9cfa123495a1225868953/zipDownloads.md) --- ### Documentation **Type:** page | **Section:** Additional Resources Documentation High-level Documentation General explanations of the available functionality and examples of how to use the SDK are available… # Documentation ## High-level Documentation General explanations of the available functionality and examples of how to use the SDK are available by topic: - [Ai](https://ja.developer.box.com/a09026b413af100740e2d62f08e338a8/ai.md) - [Ai studio](https://ja.developer.box.com/d2fc436ac21a939f957804200fd51573/ai_studio.md) - [App item associations](https://ja.developer.box.com/3fe11188dfa3635fd55a7aeb7686ea0b/app_item_associations.md) - [Archives](https://ja.developer.box.com/19c490866888a750ea6f3e6c81ca8bbe/archives.md) - [Authorization](https://ja.developer.box.com/59f4e8c23b4987ec1bc1f0e9bd7ab180/authorization.md) - [Avatars](https://ja.developer.box.com/835511e98f383f1cbcf689229c7da2ba/avatars.md) - [Chunked uploads](https://ja.developer.box.com/e28a459d3fa63fb006a342ef28a13b43/chunked_uploads.md) - [Classifications](https://ja.developer.box.com/cdf5e5e0c239360f75fe50b4b657f8d5/classifications.md) - [Collaboration allowlist entries](https://ja.developer.box.com/74a70dbaba7d04ba57e696fe4437068c/collaboration_allowlist_entries.md) - [Collaboration allowlist exempt targets](https://ja.developer.box.com/204645934a033b7eb2c9cef9ea19c614/collaboration_allowlist_exempt_targets.md) - [Collections](https://ja.developer.box.com/3cfdf1ea1b847b61221ada88462f5554/collections.md) - [Comments](https://ja.developer.box.com/668e8f09c4fdeef337b7ac1c262001e1/comments.md) - [Device pinners](https://ja.developer.box.com/b4ed6470194d72582bfe8f541dab93ef/device_pinners.md) - [Docgen](https://ja.developer.box.com/7614dc2c59c23352f407b295008e49fd/docgen.md) - [Docgen template](https://ja.developer.box.com/6a6b103a64e8ff15d5cc2a6b577bc1ab/docgen_template.md) - [Downloads](https://ja.developer.box.com/3e62c42c0330571a33e2b70dde7c00cd/downloads.md) - [Email aliases](https://ja.developer.box.com/3180baa385460a64185c867e53196285/email_aliases.md) - [Events](https://ja.developer.box.com/68e3bc78e5339519a98765b19d0eaedf/events.md) - [File classifications](https://ja.developer.box.com/db6a7e2c5748e968aed6eefb8fb77a0d/file_classifications.md) - [File metadata](https://ja.developer.box.com/95d8e6c29063d06e0476accdd6b06837/file_metadata.md) - [File requests](https://ja.developer.box.com/527311a9e6fc596c5a59ca58625c8e61/file_requests.md) - [File version legal holds](https://ja.developer.box.com/14bbcbe0aba045c5337cc55fbba52303/file_version_legal_holds.md) - [File version retentions](https://ja.developer.box.com/d8b8993ac7b381689e41c53472631f2d/file_version_retentions.md) - [File versions](https://ja.developer.box.com/d4a2db69b4c5df3e1e505ddcced7d987/file_versions.md) - [File watermarks](https://ja.developer.box.com/3a5a549b5e5c0bf4ea5acb108cb922a2/file_watermarks.md) - [Files](https://ja.developer.box.com/1a3895c9c4085feb5a7b424c0b92b72a/files.md) - [Folder classifications](https://ja.developer.box.com/3991b429b08dfd4523d51558600e91e2/folder_classifications.md) - [Folder locks](https://ja.developer.box.com/a7b5efca17c684f1601b9c29827bdf61/folder_locks.md) - [Folder metadata](https://ja.developer.box.com/2a1e36f3381e803dc9adebb737cfd75a/folder_metadata.md) - [Folder watermarks](https://ja.developer.box.com/dad5e85c61ce5e5bb088e1735fcd32cf/folder_watermarks.md) - [Folders](https://ja.developer.box.com/4cea719129f8f7047d01357558228e59/folders.md) - [Groups](https://ja.developer.box.com/19c77e92519e0a377c60c8dda9c7d349/groups.md) - [Hub collaborations](https://ja.developer.box.com/2971b3b1575ebe0e6f2b6de997bec0a5/hub_collaborations.md) - [Hub items](https://ja.developer.box.com/2b9ba0977646a714310ca5ce75681a30/hub_items.md) - [Hubs](https://ja.developer.box.com/345655c51d5496c7fc3068f3ecd1e6e0/hubs.md) - [Integration mappings](https://ja.developer.box.com/7c4cb93f5abbc92622f1d06dc4ff0a48/integration_mappings.md) - [Invites](https://ja.developer.box.com/e8d87e010425e6b27fc254653694500f/invites.md) - [Legal hold policies](https://ja.developer.box.com/cc1ffb63a81826d05ca3a4950e63f8e3/legal_hold_policies.md) - [Legal hold policy assignments](https://ja.developer.box.com/2b6c038eab6a8600f9f6b532ed3532a0/legal_hold_policy_assignments.md) - [List collaborations](https://ja.developer.box.com/bf50c526ea161dafbd5382843fe2617e/list_collaborations.md) - [Memberships](https://ja.developer.box.com/fabf5a724fe1d6758e5433a6fa755617/memberships.md) - [Metadata cascade policies](https://ja.developer.box.com/1e39db6079a70edb0312a95531bf87ec/metadata_cascade_policies.md) - [Metadata templates](https://ja.developer.box.com/af2c8cef2f3d9fa291a686879e21b30b/metadata_templates.md) - [Recent items](https://ja.developer.box.com/5421143128a2076837c5c40e082fff9b/recent_items.md) - [Retention policies](https://ja.developer.box.com/e47f383b8d4d6865c6f3478c1fcb90d4/retention_policies.md) - [Retention policy assignments](https://ja.developer.box.com/883337653a1c49f9bd592ede24cfb143/retention_policy_assignments.md) - [Search](https://ja.developer.box.com/41d1e9a77431b613d308b4b383b2dc75/search.md) - [Session termination](https://ja.developer.box.com/cd389a41a0640c06a4712e408d3e71e1/session_termination.md) - [Shared links app items](https://ja.developer.box.com/d8c2a236b7ef57c5be71032bc6115936/shared_links_app_items.md) - [Shared links files](https://ja.developer.box.com/18e781ff9227033bcd1896624d8f34e0/shared_links_files.md) - [Shared links folders](https://ja.developer.box.com/84c8a671deed018692ed60bf777612a9/shared_links_folders.md) - [Shared links web links](https://ja.developer.box.com/beda87247d3103630705a063809e1308/shared_links_web_links.md) - [Shield information barrier reports](https://ja.developer.box.com/73579b1b9fbb371253789ee5cb2d8d44/shield_information_barrier_reports.md) - [Shield information barrier segment members](https://ja.developer.box.com/14027a92b5496fd7c9db7161f30f6281/shield_information_barrier_segment_members.md) - [Shield information barrier segment restrictions](https://ja.developer.box.com/85adc6b4f11a7d9c2a9a443a0f1d9faa/shield_information_barrier_segment_restrictions.md) - [Shield information barrier segments](https://ja.developer.box.com/d5af9c5729c6ec938df42f5610d2efab/shield_information_barrier_segments.md) - [Shield information barriers](https://ja.developer.box.com/fefd039c6cfecc64c50aa865fdd55057/shield_information_barriers.md) - [Shield lists](https://ja.developer.box.com/6393c29083285fac04053345968dc3e4/shield_lists.md) - [Sign requests](https://ja.developer.box.com/36a68c89098d3ebe8649b5351f685623/sign_requests.md) - [Sign templates](https://ja.developer.box.com/edc3ff97e19ce3ad45500ac5dc86e019/sign_templates.md) - [Skills](https://ja.developer.box.com/792f07c753b36b7648b47547c06a93fd/skills.md) - [Storage policies](https://ja.developer.box.com/62f44b17e16c80a951b00a2c86fd32fa/storage_policies.md) - [Storage policy assignments](https://ja.developer.box.com/8c0281073ae3f81d0cc3dbc537f5ba97/storage_policy_assignments.md) - [Task assignments](https://ja.developer.box.com/7bd13edd15c58703c420934a1cc2ef38/task_assignments.md) - [Tasks](https://ja.developer.box.com/ba79c47e22e68578b3fceba0f1225a5b/tasks.md) - [Terms of service user statuses](https://ja.developer.box.com/2cb30f787d2c3d525188041d80888c19/terms_of_service_user_statuses.md) - [Terms of services](https://ja.developer.box.com/641fd0bf3f5214d946f7633b972e6926/terms_of_services.md) - [Transfer](https://ja.developer.box.com/3705357f8d670d464178ec5dd3049ef4/transfer.md) - [Trashed files](https://ja.developer.box.com/b8081c45623ed15e1cd461c9457f9672/trashed_files.md) - [Trashed folders](https://ja.developer.box.com/5cc3673f450994accbd7ad299d875225/trashed_folders.md) - [Trashed items](https://ja.developer.box.com/cdb3cc83aff70c2d018934fbac244e78/trashed_items.md) - [Trashed web links](https://ja.developer.box.com/8865f15da142222971012311287e3144/trashed_web_links.md) - [Uploads](https://ja.developer.box.com/51c242a5a8f87bae3d50ed4fc2fe098f/uploads.md) - [User collaborations](https://ja.developer.box.com/254eb81c4645ee29e3a254c5cd55bb52/user_collaborations.md) - [Users](https://ja.developer.box.com/ee2eb34588a34363bceeac553216c603/users.md) - [Web links](https://ja.developer.box.com/fd88c2a990d46c5ab5117e733629b658/web_links.md) - [Webhooks](https://ja.developer.box.com/6c982161944f5adb31074ffa72e92e63/webhooks.md) - [Workflows](https://ja.developer.box.com/85c3e34f878e722529594e16e279bcc3/workflows.md) - [Zip downloads](https://ja.developer.box.com/6a6ad1c1ca1ec0808f1f75ab18cb2d55/zip_downloads.md) --- ### Documentation **Type:** page | **Section:** Additional Resources Documentation High-level Documentation General explanations of the available functionality and examples of how to use the SDK are available… # Documentation ## High-level Documentation General explanations of the available functionality and examples of how to use the SDK are available by topic: - [Ai](https://ja.developer.box.com/9c54c8a9e7d617c8142f8d7218ae7de6/Ai.md) - [Ai studio](https://ja.developer.box.com/7ec7f79b698d7091f3981cc181ae6f2e/AiStudio.md) - [App item associations](https://ja.developer.box.com/747dbfc211ee16fedd3463095b4f3d73/AppItemAssociations.md) - [Archives](https://ja.developer.box.com/68363b6a5902f6336758e607b491218a/Archives.md) - [Authorization](https://ja.developer.box.com/d0a0c38e6569699d1e89e8a61ac9364c/Authorization.md) - [Avatars](https://ja.developer.box.com/3f6c1c9ef77384881ea43a9031b053df/Avatars.md) - [Chunked uploads](https://ja.developer.box.com/168397dd0a28531ceb91fae9a6ba6683/ChunkedUploads.md) - [Classifications](https://ja.developer.box.com/bad50bfefaa4ff6b2711f458120f340e/Classifications.md) - [Collaboration allowlist entries](https://ja.developer.box.com/662f28c2244f02b000d59a07fa07611d/CollaborationAllowlistEntries.md) - [Collaboration allowlist exempt targets](https://ja.developer.box.com/42f060472f4271149debcfa17f461d43/CollaborationAllowlistExemptTargets.md) - [Collections](https://ja.developer.box.com/f5cdcd229ee876cf05b4e22fc5dec07b/Collections.md) - [Comments](https://ja.developer.box.com/254597f2dce8280d2a4abb74cb0a6d66/Comments.md) - [Device pinners](https://ja.developer.box.com/254830ff33e310766a56f197531bc5af/DevicePinners.md) - [Docgen](https://ja.developer.box.com/86f07ae5afdda6f43561e0f35ef27032/Docgen.md) - [Docgen template](https://ja.developer.box.com/badb81e071c9a0b7feb232e0cdaf7146/DocgenTemplate.md) - [Downloads](https://ja.developer.box.com/6ce06f0d62fa68d89e1813f578ff2540/Downloads.md) - [Email aliases](https://ja.developer.box.com/4658210ba0c7761d578c3f5823a06d35/EmailAliases.md) - [Events](https://ja.developer.box.com/8dd34d4c1b76e5cc254ac017ceb3b6f2/Events.md) - [File classifications](https://ja.developer.box.com/1f3f9f04590b2e101f25dd47250e3edf/FileClassifications.md) - [File metadata](https://ja.developer.box.com/c6bf7f682acb8bddad748d54c468859f/FileMetadata.md) - [File requests](https://ja.developer.box.com/949897e145c5a6ed40f9b4b8995ec102/FileRequests.md) - [File version legal holds](https://ja.developer.box.com/17f50a574b39c87d0175bf0b65352f73/FileVersionLegalHolds.md) - [File version retentions](https://ja.developer.box.com/aa22736bc5050e37a08fce5c8aeb4c15/FileVersionRetentions.md) - [File versions](https://ja.developer.box.com/0000158b67b7ecaaed5e28da59de5a95/FileVersions.md) - [File watermarks](https://ja.developer.box.com/6dc698be58eba864fa0da8aff4754dd7/FileWatermarks.md) - [Files](https://ja.developer.box.com/a2f1d8382c641f489e31d3274303ab58/Files.md) - [Folder classifications](https://ja.developer.box.com/bbcc2bdfb9e45ba4f2c1c50d1c083e76/FolderClassifications.md) - [Folder locks](https://ja.developer.box.com/4bbaf513cdeb7e6dad6b0232ce7ce2f0/FolderLocks.md) - [Folder metadata](https://ja.developer.box.com/506b6d6a02cce2665e62964deb674dd8/FolderMetadata.md) - [Folder watermarks](https://ja.developer.box.com/af0d2c0fd49cb12eaaeabb947f0cc973/FolderWatermarks.md) - [Folders](https://ja.developer.box.com/2066cdd4e1d1228c9ddd8b3bbffb51a9/Folders.md) - [Groups](https://ja.developer.box.com/a37e64a2a67bec61a90aa22548bbcd10/Groups.md) - [Hub collaborations](https://ja.developer.box.com/c178b0d27ec978ccb68a14298f78bd8d/HubCollaborations.md) - [Hub items](https://ja.developer.box.com/dc396a70c2e75eca8b46262a7fa76fb3/HubItems.md) - [Hubs](https://ja.developer.box.com/2ba3c9b781e0ce88dc400abbd9c5dda2/Hubs.md) - [Integration mappings](https://ja.developer.box.com/1555bc9e12479eaf3058df376ee790dd/IntegrationMappings.md) - [Invites](https://ja.developer.box.com/8f95eb52c4fee68cf65ee65ff741548b/Invites.md) - [Legal hold policies](https://ja.developer.box.com/4e5743178eb437f048b35b87c49f7fa1/LegalHoldPolicies.md) - [Legal hold policy assignments](https://ja.developer.box.com/628e7b43a5d4d10ef6613020d658f915/LegalHoldPolicyAssignments.md) - [List collaborations](https://ja.developer.box.com/15e4850545eca9890d3f3a0ac9ef1bdc/ListCollaborations.md) - [Memberships](https://ja.developer.box.com/5d7e3bbe50b84444f739b981aa7a90ec/Memberships.md) - [Metadata cascade policies](https://ja.developer.box.com/c57554bdaf0d44c3b59f2f977c10a3fb/MetadataCascadePolicies.md) - [Metadata templates](https://ja.developer.box.com/11b6140f794c573a66e8e18807e4cd4f/MetadataTemplates.md) - [Recent items](https://ja.developer.box.com/3edd4dc632bab6c9b51780ddb364cc22/RecentItems.md) - [Retention policies](https://ja.developer.box.com/757f3b6f7ada00444e869362def63c35/RetentionPolicies.md) - [Retention policy assignments](https://ja.developer.box.com/77cea9a333b25c448076ef9c8a27e6fb/RetentionPolicyAssignments.md) - [Search](https://ja.developer.box.com/28b956bd31d54689d233cf3c2565a3bb/Search.md) - [Session termination](https://ja.developer.box.com/7c8ce1945ad61320b6723b30c0155f45/SessionTermination.md) - [Shared links app items](https://ja.developer.box.com/4f83387f849ef80390aabc5a69aeeb88/SharedLinksAppItems.md) - [Shared links files](https://ja.developer.box.com/bdf2e7eec1d554cf65b60a162ff45322/SharedLinksFiles.md) - [Shared links folders](https://ja.developer.box.com/0846e2de2e792948afcdb45152220d45/SharedLinksFolders.md) - [Shared links web links](https://ja.developer.box.com/e1a04ef46c5992998c4535230d9141e5/SharedLinksWebLinks.md) - [Shield information barrier reports](https://ja.developer.box.com/901ea0b205bbefb6332637c066296cf1/ShieldInformationBarrierReports.md) - [Shield information barrier segment members](https://ja.developer.box.com/81721dae7f613dbf72af9963acd9fbdd/ShieldInformationBarrierSegmentMembers.md) - [Shield information barrier segment restrictions](https://ja.developer.box.com/cfbfe82062910f0c73af42469cd81972/ShieldInformationBarrierSegmentRestrictions.md) - [Shield information barrier segments](https://ja.developer.box.com/0da2a4792fff2d699ae7f48de535aa64/ShieldInformationBarrierSegments.md) - [Shield information barriers](https://ja.developer.box.com/32766871c6c3347a5e264f7872f5769d/ShieldInformationBarriers.md) - [Shield lists](https://ja.developer.box.com/92f0095d02c82ba410ed288f49e93b59/ShieldLists.md) - [Sign requests](https://ja.developer.box.com/89d4065f43b84a7c9238334bc9b7b1b3/SignRequests.md) - [Sign templates](https://ja.developer.box.com/ada0deab883578a1700240437684b295/SignTemplates.md) - [Skills](https://ja.developer.box.com/8d9aa74b7eaf4a027accd670284a6a1d/Skills.md) - [Storage policies](https://ja.developer.box.com/bedd4519d96757189bc0ca855d278c14/StoragePolicies.md) - [Storage policy assignments](https://ja.developer.box.com/418d00ab16ce6e8d031ed2b7806f1425/StoragePolicyAssignments.md) - [Task assignments](https://ja.developer.box.com/dbaa6892870b466f9ebcee31578c963a/TaskAssignments.md) - [Tasks](https://ja.developer.box.com/7a492aae73ab17cac5341acd8c15114b/Tasks.md) - [Terms of service user statuses](https://ja.developer.box.com/33514073546e1c822cd0dcc8a40f5b66/TermsOfServiceUserStatuses.md) - [Terms of services](https://ja.developer.box.com/bd83b1fdc2d3074bb154841004e322bb/TermsOfServices.md) - [Transfer](https://ja.developer.box.com/ae8bc2a5dc0f360509150755da9f9d82/Transfer.md) - [Trashed files](https://ja.developer.box.com/49cffe9600e3331b4e8ce7adeefcf3f4/TrashedFiles.md) - [Trashed folders](https://ja.developer.box.com/54096a5f84173e0d286e1fd5039c88b8/TrashedFolders.md) - [Trashed items](https://ja.developer.box.com/bc07421c01fd50a38981853c003dbdec/TrashedItems.md) - [Trashed web links](https://ja.developer.box.com/d4ad7b7835366e06a935680e53896873/TrashedWebLinks.md) - [Uploads](https://ja.developer.box.com/f9db97938b2f5c81a71257eba2d9c4ca/Uploads.md) - [User collaborations](https://ja.developer.box.com/e06e8d09f643cc3acd54c2cffc9522d1/UserCollaborations.md) - [Users](https://ja.developer.box.com/1a66d4c3c9e49421937828b798a2ccce/Users.md) - [Web links](https://ja.developer.box.com/99e23c4c2b872f87a6a2c45ee7055c18/WebLinks.md) - [Webhooks](https://ja.developer.box.com/5de24e652a33902fbdf953d0581a7c4a/Webhooks.md) - [Workflows](https://ja.developer.box.com/14410c56df80410ba7099312b5830a61/Workflows.md) - [Zip downloads](https://ja.developer.box.com/ff49054385b96efdc423c1860310a469/ZipDownloads.md) --- ### Downloads **Type:** page | **Section:** Additional Resources Downloads Downloads module is used to download files from Box. Downloads Download a File Get download URL Arguments Returns Download a File… # Downloads Downloads module is used to download files from Box. [Downloads](#downloads) - [Download a File](#download-a-file) [Get download URL](#get-download-url) - [Arguments](#arguments) - [Returns](#returns) ## Download a File To get the entire contents of the file as `ArrayBuffer`, call `downloadFile` method. This method returns a `ArrayBuffer` object which contains the file content. ``` const fs = require('fs'); const fileContent = await client.downloads.downloadFile('123456789'); const fileWriteStream = fs.createWriteStream('file.pdf'); fileContent.pipe(fileWriteStream); ``` ## Get download URL Get a URL to download a file This operation is performed by calling function `getDownloadFileUrl`. ``` await client.downloads.getDownloadFileUrl(uploadedFile.id); ``` ### Arguments fileId `string` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" ## optionalsInput GetDownloadFileUrlOptionalsInput ### Returns This function returns a value of type `string`. --- ### DownloadsManager **Type:** page | **Section:** Additional Resources DownloadsManager Download file URL Download file Download file Download file URL Get the download URL without downloading the content. This… # DownloadsManager - [Download file URL](#download-file-url) - [Download file](#download-file) - [Download file](#download-file) ## Download file URL Get the download URL without downloading the content. This operation is performed by calling function `get_download_file_url`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-files-id-content/). ``` client.downloads.get_download_file_url(uploaded_file.id) ``` ### Arguments file_id `str` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" version `Optional[str]` - The file version to download. access_token `Optional[str]` - An optional access token that can be used to pre-authenticate this request, which means that a download link can be shared with a browser or a third party service without them needing to know how to handle the authentication. When using this parameter, please make sure that the access token is sufficiently scoped down to only allow read access to that file and no other files or folders. range `Optional[str]` - The byte range of the content to download. The format `bytes={start_byte}-{end_byte}` can be used to specify what section of the file to download. boxapi `Optional[str]` - The URL, and optional password, for the shared link of this item. This header can be used to access items that have not been explicitly shared with a user. Use the format `shared_link=[link]` or if a password is required then use `shared_link=[link]&shared_link_password=[password]`. This header can be used on the file or folder shared, as well as on any files or folders nested within the item. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `str`. Returns the requested file if the client has the follow redirects setting enabled to automatically follow HTTP `3xx` responses as redirects. If not, the request will return `302` instead. For details, see the [download file guide](g://downloads/file#download-url).If the file is not ready to be downloaded yet `Retry-After` header will be returned indicating the time in seconds after which the file will be available for the client to download. This response can occur when the file was uploaded immediately before the download request. ## Download file Returns the contents of a file in binary format. This operation is performed by calling function `download_file`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-files-id-content/). ``` client.downloads.download_file(uploaded_file.id) ``` ### Arguments file_id `str` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" version `Optional[str]` - The file version to download. access_token `Optional[str]` - An optional access token that can be used to pre-authenticate this request, which means that a download link can be shared with a browser or a third party service without them needing to know how to handle the authentication. When using this parameter, please make sure that the access token is sufficiently scoped down to only allow read access to that file and no other files or folders. range `Optional[str]` - The byte range of the content to download. The format `bytes={start_byte}-{end_byte}` can be used to specify what section of the file to download. boxapi `Optional[str]` - The URL, and optional password, for the shared link of this item. This header can be used to access items that have not been explicitly shared with a user. Use the format `shared_link=[link]` or if a password is required then use `shared_link=[link]&shared_link_password=[password]`. This header can be used on the file or folder shared, as well as on any files or folders nested within the item. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `Optional[ByteStream]`. Returns the requested file if the client has the follow redirects setting enabled to automatically follow HTTP `3xx` responses as redirects. If not, the request will return `302` instead. For details, see the [download file guide](g://downloads/file#download-url).If the file is not ready to be downloaded yet `Retry-After` header will be returned indicating the time in seconds after which the file will be available for the client to download. This response can occur when the file was uploaded immediately before the download request. ## Download file Download file to a given output stream This operation is performed by calling function `download_file_to_output_stream`. ``` client.downloads.download_file_to_output_stream(uploaded_file.id, file_output_stream) ``` ### Arguments file_id `str` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" output_stream `OutputStream` - Download file to a given output stream version `Optional[str]` - The file version to download. access_token `Optional[str]` - An optional access token that can be used to pre-authenticate this request, which means that a download link can be shared with a browser or a third party service without them needing to know how to handle the authentication. When using this parameter, please make sure that the access token is sufficiently scoped down to only allow read access to that file and no other files or folders. range `Optional[str]` - The byte range of the content to download. The format `bytes={start_byte}-{end_byte}` can be used to specify what section of the file to download. boxapi `Optional[str]` - The URL, and optional password, for the shared link of this item. This header can be used to access items that have not been explicitly shared with a user. Use the format `shared_link=[link]` or if a password is required then use `shared_link=[link]&shared_link_password=[password]`. This header can be used on the file or folder shared, as well as on any files or folders nested within the item. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `None`. --- ### EmailAliasesManager **Type:** page | **Section:** Additional Resources EmailAliasesManager List user's email aliases Create email alias Remove email alias List user's email aliases Retrieves all email aliases… # EmailAliasesManager - [List user's email aliases](#list-users-email-aliases) - [Create email alias](#create-email-alias) - [Remove email alias](#remove-email-alias) ## List user's email aliases Retrieves all email aliases for a user. The collection does not include the primary login for the user. This operation is performed by calling function `getUserEmailAliases`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-users-id-email-aliases/). ``` await client.emailAliases.getUserEmailAliases(newUser.id); ``` ### Arguments userId `string` - The ID of the user. Example: "12345" optionalsInput `GetUserEmailAliasesOptionalsInput` ### Returns This function returns a value of type `EmailAliases`. Returns a collection of email aliases. ## Create email alias Adds a new email alias to a user account.. This operation is performed by calling function `createUserEmailAlias`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-users-id-email-aliases/). ``` await client.emailAliases.createUserEmailAlias(newUser.id, { email: newAliasEmail, } satisfies CreateUserEmailAliasRequestBody); ``` ### Arguments userId `string` - The ID of the user. Example: "12345" requestBody `CreateUserEmailAliasRequestBody` - Request body of createUserEmailAlias method optionalsInput `CreateUserEmailAliasOptionalsInput` ### Returns This function returns a value of type `EmailAlias`. Returns the newly created email alias object. ## Remove email alias Removes an email alias from a user. This operation is performed by calling function `deleteUserEmailAliasById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-users-id-email-aliases-id/). ``` await client.emailAliases.deleteUserEmailAliasById(newUser.id, newAlias.id!); ``` ### Arguments userId `string` - The ID of the user. Example: "12345" emailAliasId `string` - The ID of the email alias. Example: "23432" optionalsInput `DeleteUserEmailAliasByIdOptionalsInput` ### Returns This function returns a value of type `undefined`. Removes the alias and returns an empty response. --- ### EmailAliasesManager **Type:** page | **Section:** Additional Resources EmailAliasesManager List user's email aliases Create email alias Remove email alias List user's email aliases Retrieves all email aliases… # EmailAliasesManager - [List user's email aliases](#list-users-email-aliases) - [Create email alias](#create-email-alias) - [Remove email alias](#remove-email-alias) ## List user's email aliases Retrieves all email aliases for a user. The collection does not include the primary login for the user. This operation is performed by calling function `get_user_email_aliases`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-users-id-email-aliases/). ``` client.email_aliases.get_user_email_aliases(new_user.id) ``` ### Arguments user_id `str` - The ID of the user. Example: "12345" extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `EmailAliases`. Returns a collection of email aliases. ## Create email alias Adds a new email alias to a user account.. This operation is performed by calling function `create_user_email_alias`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-users-id-email-aliases/). ``` client.email_aliases.create_user_email_alias(new_user.id, new_alias_email) ``` ### Arguments user_id `str` - The ID of the user. Example: "12345" email `str` - The email address to add to the account as an alias. Note: The domain of the email alias needs to be registered to your enterprise. See the [domain verification guide](https://support.box.com/hc/en-us/articles/4408619650579-Domain-Verification) for steps to add a new domain. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `EmailAlias`. Returns the newly created email alias object. ## Remove email alias Removes an email alias from a user. This operation is performed by calling function `delete_user_email_alias_by_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-users-id-email-aliases-id/). ``` client.email_aliases.delete_user_email_alias_by_id(new_user.id, new_alias.id) ``` ### Arguments user_id `str` - The ID of the user. Example: "12345" email_alias_id `str` - The ID of the email alias. Example: "23432" extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `None`. Removes the alias and returns an empty response. --- ### Enterprise **Type:** page | **Section:** Additional Resources Enterprise Get Enterprise Users Invite User to Enterprise Add New User Add New App User Transfer User Content Get Enterprise Users Get a… # Enterprise - [Get Enterprise Users](#get-enterprise-users) - [Invite User to Enterprise](#invite-user-to-enterprise) - [Add New User](#add-new-user) - [Add New App User](#add-new-app-user) - [Transfer User Content](#transfer-user-content) ## Get Enterprise Users Get a list of users in the current enterprise by calling the [`enterprise.getUsers(options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Enterprise.html#getUsers) method. This method supports offset-based pagination and marker-based pagintation. To use offset-based pagination, do not pass in the `usemarker` parameter or set it to `false`. To use marker-based pagination, pass in the `usemarker` parameter as `true`. Use the `fields` option to specify the desired response fields, and `limit` (along with `offset` or `marker`) to control result set paging. Requesting information for only the fields you need can improve performance by reducing the size of the network response. ``` client.enterprise.getUsers({usemarker: true, marker: 'JFUirotE56hfyr56FH123'}) .then(users => { /* users -> { total_count: 1, entries: [ { type: 'user', id: '33333', name: 'Example User', login: 'user@example.com', created_at: '2012-05-03T21:39:11-07:00', modified_at: '2012-08-23T14:57:48-07:00', language: 'en', space_amount: 5368709120, space_used: 52947, max_upload_size: 104857600, status: 'active', job_title: '', phone: '5555551374', address: '10 Cloud Way Los Altos CA', avatar_url: 'https://app.box.com/api/avatar/large/deprecated' } ] } */ }); ``` ## Invite User to Enterprise Invite a user to an enterprise by calling the [`enterprise.inviteUser(enterpriseID, email, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Enterprise.html#inviteUser) method with the ID of the enterprise and the user's email address. ``` client.enterprise.inviteUser('1345', 'jsmith@box.com', callback); ``` ## Add New User To provision a new managed user within the current enterprise, call the [`enterprise.addUser(login, name, options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Enterprise.html#addUser) method with the email address the user will use to log in and the user's name. ``` client.enterprise.addUser( 'eddard@winterfell.example.com', 'Ned Stark', { role: client.enterprise.userRoles.COADMIN, address: '555 Box Lane', status: client.enterprise.userStatuses.CANNOT_DELETE_OR_EDIT }) .then(user => { /* user -> { type: 'user', id: '44444', name: 'Ned Stark', login: 'eddard@winterfell.example.com', created_at: '2012-11-15T16:34:28-08:00', modified_at: '2012-11-15T16:34:29-08:00', role: 'coadmin', language: 'en', timezone: 'America/Los_Angeles', space_amount: 5368709120, space_used: 0, max_upload_size: 2147483648, status: 'active', job_title: '', phone: '', address: '555 Box Lane', avatar_url: 'https://www.box.com/api/avatar/large/deprecated' } */ }); ``` ## Add New App User To provision a new app user within the current enterprise, call the [`enterprise.addAppUser(name, options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Enterprise.html#addAppUser) method with the user's name. ``` client.enterprise.addAppUser('Daenerys Targaryen', { external_app_user_id: 'external-id' }) .then(appUser => { /* appUser -> { type: 'user', id: '55555', name: 'Daenerys Targaryen', login: 'AppUser_59659_vuNs7OCQ7y@box.com', created_at: '2015-04-20T20:09:59-07:00', modified_at: '2015-04-20T20:09:59-07:00', language: 'en', timezone: 'America/Los_Angeles', space_amount: 5368709120, space_used: 0, max_upload_size: 16106127360, status: 'active', job_title: '', phone: '', address: '', avatar_url: '' } */ }); ``` ## Transfer User Content To transfer one managed user's content to another user's account, call the [`enterprise.transferUserContent(sourceUserID, destUserID, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Enterprise.html#transferUserContent) method with the IDs of the source and destination users. ``` var sourceUserID = '33333'; var destinationUserID = '44444'; client.enterprise.transferUserContent(sourceUserID, destinationUserID) .then(movedFolder => { /* movedFolder -> { type: 'folder', id: '123456789', sequence_id: '1', etag: '1', name: 'Other User's Files and Folders', created_at: '2018-04-23T11:00:07-07:00', modified_at: '2018-04-23T11:00:07-07:00', description: 'This folder contains files previously owned by Other User, and were transferred to you by your enterprise administrator. If you have any questions, please contact Enterprise Admin (admin@example.com).', size: 0, path_collection: { total_count: 1, entries: [ { type: 'folder', id: '0', sequence_id: null, etag: null, name: 'All Files' } ] }, created_by: { type: 'user', id: '99999', name: 'Enterprise Admin', login: 'admin@example.com' }, modified_by: { type: 'user', id: '99999', name: 'Enterprise Admin', login: 'admin@example.com' }, trashed_at: null, purged_at: null, content_created_at: '2018-04-23T11:00:07-07:00', content_modified_at: '2018-04-23T11:00:07-07:00', owned_by: { type: 'user', id: '33333', name: 'Example User', login: 'user@example.com' }, shared_link: null, folder_upload_email: null, parent: { type: 'folder', id: '0', sequence_id: null, etag: null, name: 'All Files' }, item_status: 'active' } */ }); ``` --- ### Event Stream **Type:** page | **Section:** Additional Resources Event Stream The Event Stream class utilizes long-polling to receive real-time events from Box. The SDK provides an easy way to set up and… # Event Stream The Event Stream class utilizes long-polling to receive real-time events from Box. The SDK provides an easy way to set up and manage the event stream which is extended from the stream.Readable class. [Event Stream](#event-stream) - [Listening to the Event Stream](#listening-to-the-event-stream) - [Deduplication](#deduplication) ## Listening to the Event Stream When the `EventStream` is started, it will begin long-polling asynchronously. Events received from the API are then forwarded to all listeners. You can also listen for errors and the end of the stream using the `error` and `end` events respectively. ``` const eventsStream = await client.events.getEventStream(); eventsStream.on('data', (event) => { console.log('Received event:', event); }); eventsStream.on('error', (error) => { console.error('Error in events stream:', error); }); eventsStream.on('end', () => { console.log('Events stream ended'); }); ``` ## Deduplication The `EventStream` class automatically deduplicates events based on their `event_id`. This means that if the same event is received multiple times, it will only be emitted once to the listeners. --- ### Event Stream **Type:** page | **Section:** Additional Resources Event Stream The Event Stream class utilizes long-polling to receive real-time events from Box. The SDK provides an easy way to set up and… # Event Stream The Event Stream class utilizes long-polling to receive real-time events from Box. The SDK provides an easy way to set up and manage the event stream which returns an iterable object and yields events as they are received. [Event Stream](#event-stream) - [Listening to the Event Stream](#listening-to-the-event-stream) - [Deduplication](#deduplication) ## Listening to the Event Stream When the `EventStream` is started, it will begin long-polling asynchronously. Events received from the API are then yielded to the caller. ``` event_stream = client.events.get_event_stream() for event in event_stream: print("Received event:", event) ``` ## Deduplication The `EventStream` class automatically deduplicates events based on their `event_id`. This means that if the same event is received multiple times, it will only be emitted once to the listeners. --- ### Events **Type:** page | **Section:** Additional Resources Events The Box API supports two types of event streams -- one for the events specific to a particular user and one for all of the events in… # Events The Box API supports two types of event streams -- one for the events specific to a particular user and one for all of the events in an enterprise. [User Events](#user-events) - [Listening to the EventStream](#listening-to-the-eventstream) - [Deduplicating Events](#deduplicating-events) - [Get the Current Stream Position](#get-the-current-stream-position) - [Get Events](#get-events) [Enterprise Events](#enterprise-events) - [Listening to the Enterprise Event Stream](#listening-to-the-enterprise-event-stream) - [Handling errors](#handling-errors) - [Persisting the Stream State](#persisting-the-stream-state) ## User Events The Box API provides an events endpoint that utilizes long-polling to send events in real-time. The SDK provides an `EventStream` class (which implements [stream.Readable](https://nodejs.org/api/stream.html#stream_readable_streams)) that automatically handles long-polling and deduplicating events. - [Listening to the EventStream](#listening-to-the-eventstream) - [Get the Current Stream Position](#get-the-current-stream-position) - [Get Events](#get-events) ### Listening to the EventStream When the `EventStream` is started, it will begin long-polling asynchronously. Events received from the API are then forwarded to any listeners. ``` client.events.getEventStream(function(err, stream) { if (err) { // handle error } stream.on('data', function(event) { // handle the event }); }); ``` By default, the stream will start at the current time. You can start the stream at a past stream position by passing a position marker: ``` client.events.getEventStream('1408838928446360', function(err, stream) { /* ... */ }); ``` When you're done listening for events, call `stream.pause()` to stop long-polling. ### Deduplicating Events Since the Box API [may send duplicate events](https://developers.box.com/docs/#events), the `EventStream` will remember the last 5000 received events and automatically ignore them. ### Get the Current Stream Position It is possible to get the current stream position, which can later be used to fetch events from that point in time forward. ``` client.events.getCurrentStreamPosition(callback); ``` ### Get Events To get the latest chunk of events, you can call [`events.get(options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Events.html#get). ``` client.events.get(null, callback); ``` You can also pass in a `stream_position` parameter to get events from a specific point in time: ``` client.events.get({stream_position: '1408838928446360'}, callback); ``` ### Destroying the Stream If you ever need to *stop* long-polling, use: ``` client.events.destroy(); ``` This *will not* cancel in-process network requests. It *will* ensure no further long-polling nor event fetching takes place. ## Enterprise Events The Box API has an enterprise events endpoint that is available to admin users and service accounts. The SDK includes an `EnterpriseEventStream` class (which implements [stream.Readable](https://nodejs.org/api/stream.html#stream_readable_streams)) that automatically handles polling for events and delivering them to the application. - [Listening to the Enterprise Event Stream](#listening-to-the-enterprise-event-stream) - [Handling errors](#handling-errors) - [Get the Stream Position](#get-the-stream-position) ### Listening to the Enterprise Event Stream When you attach a `'data'` event listener to an `EnterpriseEventStream`, it will begin fetching events from Box. Events received from the API are then forwarded to the listener. ``` client.events.getEnterpriseEventStream(function(err, stream) { if (err) { // Handle error } stream.on('data', function(event) { // Handle the event }); }); ``` To get events from admin events stream you have to pick stream_type from `admin_logs` or `admin_logs_streaming`. By default, the `admin_logs` stream is selected. Emphasis of this stream is on completeness over latency, which means that Box will deliver admin events in chronological order and without duplicates, but with higher latency. You can specify start and end time/dates. To monitor recent events that have been generated within Box across the enterprise use `admin_logs_streaming` as stream type. The emphasis for this feed is on low latency rather than chronological accuracy, which means that Box may return events more than once and out of chronological order. Events are returned via the API around 12 seconds after they are processed by Box (the 12 seconds buffer ensures that new events are not written after your cursor position). Only two weeks of events are available via this feed, and you cannot set start and end time/dates. Use `streamType` option to select stream type: ``` client.events.getEnterpriseEventStream({ streamType: 'admin_logs_streaming' }, callback); ``` By default, the stream will start at the current time. You can also start the stream from a specific date or from a previous stream position. To start from the earliest available events (~1 year), pass `streamPosition = '0'`. The stream will fetch all past events as quickly as your listener consumes them. Once the stream catches up to the current time, it will begin polling for new events every `pollingInterval` seconds (default = 60). ``` client.events.getEnterpriseEventStream({ startDate: '2016-01-01T00:00:00-08:00', pollingInterval: 60 }, callback); ``` Note that Box buffers enterprise events for ~60 seconds when using `admin_logs` stream type, before making them available to the `/events` API (to ensure that events are delivered in-order and without duplicates), so polling with an interval of less than 60 seconds is not normally needed with this event type. When using `admin_logs_streaming` you can set pooling interval to 12 seconds. If you pass `pollingInterval = 0`, then the stream will not use polling, but will end when all the currently available events have been delivered. ``` client.events.getEnterpriseEventStream({ startDate: '2016-01-01T00:00:00-08:00', endDate: '2017-01-01T00:00:00-08:00', pollingInterval: 0 }, callback); ``` You can also filter the event stream to only receive specific event types. The set of enterprise event types is available in `client.events.enterpriseEventTypes`. ``` client.events.getEnterpriseEventStream({ eventTypeFilter: [client.events.enterpriseEventTypes.UPLOAD, client.events.enterpriseEventTypes.DOWNLOAD] }, callback); ``` Since `EnterpriseEventStream` implements [stream.Readable](https://nodejs.org/api/stream.html#stream_readable_streams), you can use the usual flow-control mechanisms on the stream: ``` stream.pause(); stream.resume(); stream.isPaused(); ``` You can also pipe the output to a [stream.Writable](https://nodejs.org/api/stream.html#stream_writable_streams) stream (it must be an "object mode" stream): ``` stream.pipe(writableObjectModeStream); ``` ### Handling errors If an API or network error occurs, the stream will ignore the error and continue polling at the usual rate until the connection can be re-established. You can respond to errors with an `'error'` event listener: ``` stream.on('error', function(err) { // Handle the error. }); ``` ### Persisting the Stream State In many applications, you may need to persist the stream state so that you can resume processing events from the same point if your application is interrupted and restarted. You can attach a `newStreamState` event listener to be notified each time the stream position changes. ``` client.events.getEnterpriseEventStream(function(err, stream) { if (err) { // Handle error } // Restore the stream state from the previous run. stream.setStreamState(readState()); stream.on('newStreamState', function(streamState) { // Persist the stream state each time the stream position changes. writeState(streamState); }); stream.on('data', function(event) { // Handle the event. }); }); ``` --- ### Events **Type:** page | **Section:** Additional Resources Events The Box API provides an events endpoint that utilizes long-polling to send user events in real-time. The SDK provides an EventStream… # Events The Box API provides an events endpoint that utilizes long-polling to send user events in real-time. The SDK provides an `EventStream` class that automatically handles long-polling and deduplicating events. [User Events](#user-events) - [Deduplicating Events](#deduplicating-events) [Enterprise (Admin) Events](#enterprise-admin-events) - [Historical Querying](#historical-querying) - [Live Monitoring](#live-monitoring) ## User Events Subscribing to user events works by creating an `EventStream` and attaching listeners for the events that are fetched in near-real time from the API. When the `EventStream` is started, it will begin long-polling on a separate thread. Events received from the API are then forwarded to any listeners as a [`BoxEvent`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxEvent.html) object. To create an `EventStream` starting from the current point in time, use the [`EventStream(BoxAPIConnection api)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/EventStream.html#EventStream-com.box.sdk.BoxAPIConnection-) constructor. To start from a known stream position, pass the stream position to the [`EventStream(BoxAPIConnection api, long streamPosition)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/EventStream.html#EventStream-com.box.sdk.BoxAPIConnection-long-) constructor. ``` EventStream stream = new EventStream(api); stream.addListener(new EventListener() { public void onEvent(BoxEvent event) { // Handle the event. } }); stream.start(); ``` Keep in mind that events are received on a separate thread, so things like UI operations may need to be explicitly delegated back to the UI thread. When you're done listening for events, be sure to call `stream.stop()` to stop long-polling. ### Deduplicating Events Since the Box API [may send duplicate events](https://developers.box.com/docs/#events), the `EventStream` will remember the last 512 received events and automatically ignore them. ## Enterprise (Admin) Events ### Historical Querying The Box API provides an `EventLog` class and a `getEnterpriseEvents(BoxAPIConnection api, EnterpriseEventsRequest enterpriseEventsRequest)` method that reads from the `admin-logs` stream and returns an `Iterable<BoxEvent>` over Enterprise [`BoxEvent`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxEvent.html) records. The emphasis for this stream is on completeness over latency, which means that Box will deliver admin events in chronological order and without duplicates, but with higher latency. You can specify start and end time/dates. This method will only work with an API connection for an enterprise admin account or service account with a manage enterprise properties. ``` // get the last two hours of unfiltered enterprise events Date startDate = new Date(System.currentTimeMillis() - (1000 * 60 * 60 * 2)); Date endDate = new Date(System.currentTimeMillis()); EnterpriseEventsRequest request = new EnterpriseEventsRequest() .after(startDate) .before(endDate); EventLog eventLog = EventLog.getEnterpriseEvents(api, request); for (BoxEvent event : eventLog) { System.out.println("Enterprise Event Created by User: " + event.getCreatedBy().getName() + " Login: " + event.getCreatedBy().getLogin() + " Event Type: " + event.getEventType() + " Created at: " + event.getCreatedAt().toString() ); }; ``` Additionally, you can set a limit of the number of enterprise events to be retrieved per response by specifying the limit field. ``` // get first 20 events EnterpriseEventsRequest request = new EnterpriseEventsRequest() .limit(20); EventLog eventLog = EventLog.getEnterpriseEvents(api, request); for (BoxEvent event : eventLog) { System.out.println("Enterprise Event Created by User: " + event.getCreatedBy().getName() + " Login: " + event.getCreatedBy().getLogin() + " Event Type: " + event.getEventType() + " Created at: " + event.getCreatedAt().toString() ); }; ``` You can also filter events by type. ``` // filter events by type EnterpriseEventsRequest request = new EnterpriseEventsRequest() .types(EventType.ITEM_CREATE, EventType.ITEM_OPEN); EventLog eventLog = EventLog.getEnterpriseEvents(api, request); for (BoxEvent event : eventLog){ System.out.println("Enterprise Event Created by User: " + event.getCreatedBy().getName() + " Login: " + event.getCreatedBy().getLogin() + " Event Type: " + event.getEventType() + " Created at: " + event.getCreatedAt().toString() ); }; ``` You can also filter events by type name. This is usefull if a new event type is introduced and is not mapped to `BoxEvent.EventType`. ``` // filter events by type name EnterpriseEventsRequest request = new EnterpriseEventsRequest() .typeNames("ITEM_CREATE", "ITEM_OPEN"); EventLog eventLog = EventLog.getEnterpriseEvents(api, request); for (BoxEvent event : eventLog){ System.out.println("Enterprise Event Created by User: " + event.getCreatedBy().getName() + " Login: " + event.getCreatedBy().getLogin() + " Event Type: " + event.getEventType() + " Event Type Name: " + event.getTypeName() + " Created at: " + event.getCreatedAt().toString() ); }; ``` Bear in mind that if an event type is not mapped to `BoxEvent.EventType` the value of `BoxEvent#getEventType()` will be `BoxEvent.EventType.UNKNOWN` but `BoxEvent#getTypeName()` will return its name. If you want to progress within a stream you can use position parameter: ``` EnterpriseEventsRequest request1 = new EnterpriseEventsRequest().limit(20); EventLog eventLog1 = EventLog.getEnterpriseEvents(api, request1); // process revieved events EnterpriseEventsRequest request2 = new EnterpriseEventsRequest().limit(20) .position(eventLog1.getNextStreamPosition()); // get events from the next position EventLog eventLog2 = EventLog.getEnterpriseEvents(api, request2); // process revieved events ``` ### Live Monitoring To monitor recent events that have been generated within Box across the enterprise use `EventLog#getEnterpriseEventsStream(BoxAPIConnection api, EnterpriseEventsStreamRequest enterpriseEventsStreamRequest)`, method that reads from the `admin-logs-streaming` stream and returns an `Iterable<BoxEvent>` over Enterprise [`BoxEvent`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxEvent.html) records. The emphasis for this feed is on low latency rather than chronological accuracy, which means that Box may return events more than once and out of chronological order. Events are returned via the API around 12 seconds after they are processed by Box (the 12 seconds buffer ensures that new events are not written after your cursor position). Only two weeks of events are available via this feed, and you cannot set start and end time/dates. This method will only work with an API connection for an enterprise admin account or service account with a manage enterprise properties. ``` EnterpriseEventsStreamRequest request = new EnterpriseEventsStreamRequest() EventLog eventLog = EventLog.getEnterpriseEventsStream(api, request); for (BoxEvent event : eventLog) { System.out.println("Enterprise Event Created by User: " + event.getCreatedBy().getName() + " Login: " + event.getCreatedBy().getLogin() + " Event Type: " + event.getEventType() + " Created at: " + event.getCreatedAt().toString() ); }; ``` You can limit number of events returned. ``` // get first 20 events EnterpriseEventsStreamRequest request = new EnterpriseEventsStreamRequest() .limit(20) EventLog eventLog = EventLog.getEnterpriseEventsStream(api, request); ``` You can also filter events by type. ``` // filter events by type EnterpriseEventsStreamRequest request = new EnterpriseEventsStreamRequest() .types(EventType.ITEM_CREATE, EventType.ITEM_OPEN); EventLog eventLog = EventLog.getEnterpriseEventsStream(api, request); for (BoxEvent event : eventLog){ System.out.println("Enterprise Event Created by User: " + event.getCreatedBy().getName() + " Login: " + event.getCreatedBy().getLogin() + " Event Type: " + event.getEventType() + " Created at: " + event.getCreatedAt().toString() ); }; ``` You can also filter events by type name. This is usefull if a new event type is introduced and is not mapped to `BoxEvent.EventType`. ``` // filter events by type name EnterpriseEventsRequest request = new EnterpriseEventsStreamRequest() .typeNames("ITEM_CREATE", "ITEM_OPEN"); EventLog eventLog = EventLog.getEnterpriseEventsStream(api, request); for (BoxEvent event : eventLog){ System.out.println("Enterprise Event Created by User: " + event.getCreatedBy().getName() + " Login: " + event.getCreatedBy().getLogin() + " Event Type: " + event.getEventType() + " Event Type Name: " + event.getTypeName() + " Created at: " + event.getCreatedAt().toString() ); }; ``` Bear in mind that if an event type is not mapped to `BoxEvent.EventType` the value of `BoxEvent#getEventType()` will be `BoxEvent.EventType.UNKNOWN` but `BoxEvent#getTypeName()` will return its name. If you want to progress within a stream you can use position parameter: ``` EnterpriseEventsStreamRequest request1 = new EnterpriseEventsStreamRequest().limit(20); EventLog eventLog1 = EventLog.getEnterpriseEventsStream(api, request1); // process revieved events EnterpriseEventsStreamRequest request2 = new EnterpriseEventsStreamRequest().limit(20) .position(eventLog1.getNextStreamPosition()); // get events from the next position EventLog eventLog2 = EventLog.getEnterpriseEventsStream(api, request2); // process revieved events ``` If you have the next stream position, and make a subsequent call, the API will return immediately even when there are no events, the next stream position will be returned. If you have a stream position that is older than two weeks than API will return no events and next stream position. --- ### Events **Type:** page | **Section:** Additional Resources Events It is possible to poll the Box API for events, in order to get information about activity within Box as it happens. The Box API… # Events It is possible to poll the Box API for events, in order to get information about activity within Box as it happens. The Box API supports two types of event streams: one for the events specific to a particular user and one for all of the events in an enterprise. [User Events](#user-events) - [Listening to the Event Stream](#listening-to-the-event-stream) - [Get the Current Stream Position](#get-the-current-stream-position) - [Get Events Manually](#get-events-manually) [Enterprise Events](#enterprise-events) - [Get Events Manually](#get-events-manually-1) ## User Events The Box API provides an events endpoint that utilizes long-polling to send events in real-time. The SDK provides a generator that automatically handles long-polling and deduplicating events. ### Listening to the Event Stream To automatically receive events as they happen, call [`events.generate_events_with_long_polling(stream_position=None, stream_type=UserEventsStreamType.ALL)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.events.Events.generate_events_with_long_polling) and iterate over the results. By default, this will start listening for events from the current time onward; to get all available events, pass a `stream_position` of `0`. The generator yields [`Event`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.event.Event) objects representing each event. ``` events = client.events().generate_events_with_long_polling() for event in events: print(f'Got {event.event_type} event') ``` ### Get the Current Stream Position It is possible to get the current stream position, which can later be used to fetch events from that point in time forward, by calling [`events.get_latest_stream_position(stream_type=UserEventsStreamType.ALL)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.events.Events.get_latest_stream_position). This method returns the current stream position value as an `int`. ``` stream_position = client.events().get_latest_stream_position() print(f'The current stream position is {stream_position}') ``` ### Get Events Manually To manually retrieve a set of events, call [`events.get_events(limit=100, stream_position=0, stream_type=UserEventsStreamType.ALL)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.events.Events.get_events). By default, this will fetch the first available events chronologically; you can pass a specific `stream_position` to get events from a particular time. This method returns a `dict` with the relevant [`Event`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.event.Event) objects in a `list` under the `entries` key and the next stream position value under the `next_stream_position` key. ``` stream_position = 0 events = client.events().get_events(stream_position=stream_position) stream_position = events['next_stream_position'] for event in events['entries']: print(f'Got {event.event_type} event that occurred at {event.created_at}') ``` ## Enterprise Events Currently, the SDK only provides a manual interface for retrieving Enterprise (or Admin) Events. ### Get Events Manually To manually retrieve a set of admin events, call [`events.get_events(limit=100, stream_position=0, stream_type=UserEventsStreamType.ALL)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.events.Events.get_events) with `stream_type` set to `EnterpriseEventsStreamType.ADMIN_LOGS`. By default, this will fetch the first available events chronologically; you can pass a specific `stream_position` to get events from a particular time. This method returns a `dict` with the relevant [`Event`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.event.Event) objects in a `list` under the `entries` key and the next stream position value under the `next_stream_position` key. ``` from boxsdk.object.events import EnterpriseEventsStreamType stream_position = 0 events = client.events().get_events(stream_type=EnterpriseEventsStreamType.ADMIN_LOGS, stream_position=stream_position) stream_position = events['next_stream_position'] for event in events['entries']: print(f'Got {event.event_type} event that occurred at {event.created_at}') ``` ### Get Admin Events The SDK also allows you to retrieve enterprise events. Use [`events.get_admin_events_streaming(self, limit=None, stream_position=0, event_types=None)`] for live monitoring (events up to two weeks, low latency) and [`events.get_admin_events(self, limit=None, stream_position=0, created_after=None, created_before=None, event_types=None)`] for historical querying (events up to one year, higher latency). If `limit` param is set to None, then default API value (limit=100) will be used. Live monitoring example ``` events = client.events() .get_admin_events_streaming() for event in events['entries']: print(f'Got {event.event_type} event that occurred at {event.created_at}') ``` Addditionally, a list of event types can be passed along to filter down the returned events. ``` events = client.events() .get_admin_events_streaming(event_types=['ITEM_CREATE']) for event in events['entries']: print(f'Got {event.event_type} event that occurred at {event.created_at}') ``` When using historical querying you can specify before and after a certain datetime and the types of events to retrieve with the `event_type` by calling [`events.get_admin_events(self, limit=None, stream_position=0, created_after=None, created_before=None, event_types=None)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.events.Events.get_admin_events). If `limit` param is set to None, then default API value (limit=100) will be used. The format for the `created_after` and `created_before` fields are supported by [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) and look something like this: 2019-08-12T09:12:36-00:00. For more information on the date format please see [here](https://developer.box.com/en/guides/api-calls/types-and-formats/#date-and-times). This method returns a `dict` with the relevant [`Event`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.event.Event) objects in a `list` under the `entries` key and the next stream position value under the `next_stream_position` key. ``` events = client.events() .get_admin_events(created_after='2019-07-01T22:02:24-07:00') for event in events['entries']: print(f'Got {event.event_type} event that occurred at {event.created_at}') ``` Addditionally, a list of event types can be passed along to filter down the returned events. ``` events = client.events() .get_admin_events(created_after='2019-07-01T22:02:24-07:00', event_types=['ITEM_CREATE']) for event in events['entries']: print(f'Got {event.event_type} event that occurred at {event.created_at}') ``` --- ### Events **Type:** page | **Section:** Additional Resources Events The event feed provides a way for an application to subscribe to any actions performed by any user, users, or service in an… # Events The event feed provides a way for an application to subscribe to any actions performed by any user, users, or service in an enterprise. [User Events](#user-events) - [Get Events Manually](#deduplicating-events) [Enterprise (Admin) Events](#enterprise-admin-events) - [Historical Querying](#historical-querying) - [Live Monitoring](#live-monitoring) ## User Events User events provides a low latency stream of events relevant to the currently authenticated user. ### Get Events Manually The SDK provides an `BoxEventsManager` class and `UserEventsAsync(int limit, UserEventsStreamType streamType, string streamPosition, bool dedupeEvents)`. By default, this will fetch the first available events chronologically. You can pass a specific `stream_position` to get events from a particular time. ``` BoxEventCollection<BoxEnterpriseEvent> events = await client.EventsManager.UserEventsAsync(); ``` If you want to progress within a stream you can use position parameter: ``` BoxEventCollection<BoxEnterpriseEvent> events = await client.EventsManager.UserEventsAsync(20); string nextStreamPosition = events.NextStreamPosition; // process revieved events BoxEventCollection<BoxEnterpriseEvent> events2 = await client.EventsManager .UserEventsAsync(20, UserEventsStreamType.all, nextStreamPosition); // get events from the next position // process revieved events ``` ## Enterprise (Admin) Events Enterprise events provide an event feed for all users and content in an enterprise Box instance. ### Historical Querying The Box API provides an `BoxEventsManager` class and `EnterpriseEventsAsync(int limit, string streamPosition, IEnumerable<string> eventTypes, DateTimeOffset? createdAfter, DateTimeOffset? createdBefore = null)` method that reads from the `admin-logs` stream and returns an `BoxEventCollection<BoxEnterpriseEvent>`. The emphasis for this stream is on completeness over latency, which means that Box will deliver admin events in chronological order and without duplicates, but with higher latency. You can specify start and end time/dates. This method will only work with an API connection for an enterprise admin account or service account with a manage enterprise properties. ``` // get the last two hours of unfiltered enterprise events var createdAfter = DateTimeOffset.UtcNow.AddHours(-2); var createdBefore = DateTimeOffset.UtcNow; BoxEventCollection<BoxEnterpriseEvent> events = await client.EventsManager.EnterpriseEventsAsync(500, null, null, createdAfter, createdBefore); ``` You can also filter events by type. ``` // filter events by type var eventTypestoFilter = new List<string>() { "UPLOAD" }; BoxEventCollection<BoxEnterpriseEvent> events = await client.EventsManager.EnterpriseEventsAsync(500, null, eventTypestoFilter); ``` If you want to progress within a stream you can use position parameter: ``` BoxEventCollection<BoxEnterpriseEvent> events = await client.EventsManager.EnterpriseEventsAsync(20); string nextStreamPosition = events.NextStreamPosition; // process revieved events BoxEventCollection<BoxEnterpriseEvent> events2 = await client.EventsManager .EnterpriseEventsAsync(20, nextStreamPosition); // get events from the next position // process revieved events ``` ### Live Monitoring To monitor recent events that have been generated within Box across the enterprise use `EnterpriseEventsStreamingAsync(int limit, string streamPosition, IEnumerable<string> eventTypes)`, method that reads from the `admin-logs-streaming` stream and returns an `BoxEventCollection<BoxEnterpriseEvent>`. The emphasis for this feed is on low latency rather than chronological accuracy, which means that Box may return events more than once and out of chronological order. Events are returned via the API around 12 seconds after they are processed by Box (the 12 seconds buffer ensures that new events are not written after your cursor position). Only two weeks of events are available via this feed, and you cannot set start and end time/dates. This method will only work with an API connection for an enterprise admin account or service account with a manage enterprise properties. ``` BoxEventCollection<BoxEnterpriseEvent> events = await client.EventsManager.EnterpriseEventsStreamingAsync(); ``` You can limit number of events returned. ``` // get first 20 events int limit = 20 BoxEventCollection<BoxEnterpriseEvent> events = await client.EventsManager.EnterpriseEventsStreamingAsync(limit); ``` You can also filter events by type. ``` // filter events by type var eventTypestoFilter = new List<string>() { "UPLOAD" }; BoxEventCollection<BoxEnterpriseEvent> events = await client.EventsManager.EnterpriseEventsStreamingAsync(500, null, eventTypestoFilter); ``` If you want to progress within a stream you can use position parameter: ``` BoxEventCollection<BoxEnterpriseEvent> events = await client.EventsManager.EnterpriseEventsStreamingAsync(20); string nextStreamPosition = events.NextStreamPosition; // process revieved events BoxEventCollection<BoxEnterpriseEvent> events2 = await client.EventsManager .EnterpriseEventsStreamingAsync(20, nextStreamPosition); // get events from the next position // process revieved events ``` If you have the next stream position, and make a subsequent call, the API will return immediately even when there are no events, the next stream position will be returned. If you have a stream position that is older than two weeks than API will return no events and next stream position. --- ### EventsManager **Type:** page | **Section:** Additional Resources EventsManager Get events long poll endpoint List user and enterprise events Get event stream Get events long poll endpoint Returns a list of… # EventsManager - [Get events long poll endpoint](#get-events-long-poll-endpoint) - [List user and enterprise events](#list-user-and-enterprise-events) - [Get event stream](#get-event-stream) ## Get events long poll endpoint Returns a list of real-time servers that can be used for long-polling updates to the [event stream](#get-events). Long polling is the concept where a HTTP request is kept open until the server sends a response, then repeating the process over and over to receive updated responses. Long polling the event stream can only be used for user events, not for enterprise events. To use long polling, first use this endpoint to retrieve a list of long poll URLs. Next, make a long poll request to any of the provided URLs. When an event occurs in monitored account a response with the value `new_change` will be sent. The response contains no other details as it only serves as a prompt to take further action such as sending a request to the [events endpoint](#get-events) with the last known `stream_position`. After the server sends this response it closes the connection. You must now repeat the long poll process to begin listening for events again. If no events occur for a while and the connection times out you will receive a response with the value `reconnect`. When you receive this response you’ll make another call to this endpoint to restart the process. If you receive no events in `retry_timeout` seconds then you will need to make another request to the real-time server (one of the URLs in the response for this endpoint). This might be necessary due to network errors. Finally, if you receive a `max_retries` error when making a request to the real-time server, you should start over by making a call to this endpoint first. This operation is performed by calling function `getEventsWithLongPolling`. See the endpoint docs at [API Reference](https://developer.box.com/reference/options-events/). ``` await client.events.getEventsWithLongPolling(); ``` ### Arguments headersInput `GetEventsWithLongPollingHeadersInput` - Headers of getEventsWithLongPolling method cancellationToken `undefined | CancellationToken` - Token used for request cancellation. ### Returns This function returns a value of type `RealtimeServers`. Returns a paginated array of servers that can be used instead of the regular endpoints for long-polling events. ## List user and enterprise events Returns up to a year of past events for a given user or for the entire enterprise. By default this returns events for the authenticated user. To retrieve events for the entire enterprise, set the `stream_type` to `admin_logs_streaming` for live monitoring of new events, or `admin_logs` for querying across historical events. The user making the API call will need to have admin privileges, and the application will need to have the scope `manage enterprise properties` checked. This operation is performed by calling function `getEvents`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-events/). ``` await client.events.getEvents(); ``` ### Arguments queryParams `GetEventsQueryParams` - Query parameters of getEvents method headersInput `GetEventsHeadersInput` - Headers of getEvents method cancellationToken `undefined | CancellationToken` - Token used for request cancellation. ### Returns This function returns a value of type `Events`. Returns a list of event objects. Events objects are returned in pages, with each page (chunk) including a list of event objects. The response includes a `chunk_size` parameter indicating how many events were returned in this chunk, as well as the next `stream_position` that can be queried. ## Get event stream Get an event stream for the Box API This operation is performed by calling function `getEventStream`. ``` client.events.getEventStream(); ``` ### Arguments queryParams `GetEventStreamQueryParams` - Query parameters of getEvents method headersInput `GetEventStreamHeadersInput` - Headers of getEvents method cancellationToken `undefined | CancellationToken` - Token used for request cancellation. ### Returns This function returns a value of type `EventStream`. --- ### EventsManager **Type:** page | **Section:** Additional Resources EventsManager Get events long poll endpoint List user and enterprise events Get event stream Get events long poll endpoint Returns a list of… # EventsManager - [Get events long poll endpoint](#get-events-long-poll-endpoint) - [List user and enterprise events](#list-user-and-enterprise-events) - [Get event stream](#get-event-stream) ## Get events long poll endpoint Returns a list of real-time servers that can be used for long-polling updates to the [event stream](#get-events). Long polling is the concept where a HTTP request is kept open until the server sends a response, then repeating the process over and over to receive updated responses. Long polling the event stream can only be used for user events, not for enterprise events. To use long polling, first use this endpoint to retrieve a list of long poll URLs. Next, make a long poll request to any of the provided URLs. When an event occurs in monitored account a response with the value `new_change` will be sent. The response contains no other details as it only serves as a prompt to take further action such as sending a request to the [events endpoint](#get-events) with the last known `stream_position`. After the server sends this response it closes the connection. You must now repeat the long poll process to begin listening for events again. If no events occur for a while and the connection times out you will receive a response with the value `reconnect`. When you receive this response you’ll make another call to this endpoint to restart the process. If you receive no events in `retry_timeout` seconds then you will need to make another request to the real-time server (one of the URLs in the response for this endpoint). This might be necessary due to network errors. Finally, if you receive a `max_retries` error when making a request to the real-time server, you should start over by making a call to this endpoint first. This operation is performed by calling function `get_events_with_long_polling`. See the endpoint docs at [API Reference](https://developer.box.com/reference/options-events/). ``` client.events.get_events_with_long_polling() ``` ### Arguments extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `RealtimeServers`. Returns a paginated array of servers that can be used instead of the regular endpoints for long-polling events. ## List user and enterprise events Returns up to a year of past events for a given user or for the entire enterprise. By default this returns events for the authenticated user. To retrieve events for the entire enterprise, set the `stream_type` to `admin_logs_streaming` for live monitoring of new events, or `admin_logs` for querying across historical events. The user making the API call will need to have admin privileges, and the application will need to have the scope `manage enterprise properties` checked. This operation is performed by calling function `get_events`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-events/). ``` client.events.get_events() ``` ### Arguments stream_type `Optional[GetEventsStreamType]` - Defines the type of events that are returned _ `all` returns everything for a user and is the default _ `changes` returns events that may cause file tree changes such as file updates or collaborations. _ `sync` is similar to `changes` but only applies to synced folders _ `admin_logs` returns all events for an entire enterprise and requires the user making the API call to have admin permissions. This stream type is for programmatically pulling from a 1 year history of events across all users within the enterprise and within a `created_after` and `created_before` time frame. The complete history of events will be returned in chronological order based on the event time, but latency will be much higher than `admin_logs_streaming`. * `admin_logs_streaming` returns all events for an entire enterprise and requires the user making the API call to have admin permissions. This stream type is for polling for recent events across all users within the enterprise. Latency will be much lower than `admin_logs`, but events will not be returned in chronological order and may contain duplicates. stream_position `Optional[str]` - The location in the event stream to start receiving events from. _ `now` will return an empty list events and the latest stream position for initialization. _ `0` or `null` will return all events. limit `Optional[int]` - Limits the number of events returned. Note: Sometimes, the events less than the limit requested can be returned even when there may be more events remaining. This is primarily done in the case where a number of events have already been retrieved and these retrieved events are returned rather than delaying for an unknown amount of time to see if there are any more results. event_type `Optional[List[GetEventsEventType]]` - A comma-separated list of events to filter by. This can only be used when requesting the events with a `stream_type` of `admin_logs` or `adming_logs_streaming`. For any other `stream_type` this value will be ignored. created_after `Optional[DateTime]` - The lower bound date and time to return events for. This can only be used when requesting the events with a `stream_type` of `admin_logs`. For any other `stream_type` this value will be ignored. created_before `Optional[DateTime]` - The upper bound date and time to return events for. This can only be used when requesting the events with a `stream_type` of `admin_logs`. For any other `stream_type` this value will be ignored. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `Events`. Returns a list of event objects. Events objects are returned in pages, with each page (chunk) including a list of event objects. The response includes a `chunk_size` parameter indicating how many events were returned in this chunk, as well as the next `stream_position` that can be queried. ## Get event stream Get an event stream for the Box API This operation is performed by calling function `get_event_stream`. ``` client.events.get_event_stream() ``` ### Arguments query_params `GetEventStreamQueryParams` - Query parameters of getEvents method headers `GetEventStreamHeaders` - Headers of getEvents method ### Returns This function returns a value of type `EventStream`. --- ### File Requests **Type:** page | **Section:** Additional Resources File Requests File request objects represent a file request associated with a folder. Get a File Request's Information Copy a File Request's… # File Requests File request objects represent a file request associated with a folder. - [Get a File Request's Information](#get-a-file-requests-information) - [Copy a File Request's Information](#copy-a-file-requests-information) - [Update a File Request's Information](#update-a-file-requests-information) - [Delete a File Request](#delete-a-file-request) ## Get a File Request's Information Calling [`fileRequests.getById(fileRequestId: string)`](http://opensource.box.com/box-node-sdk/jsdoc/FileRequestsManager.html#getById) returns information on a file request [FileRequest](http://opensource.box.com/box-node-sdk/jsdoc/FileRequest.html). ``` client.fileRequests.getById(fileRequestId) ``` ## Copy a File Request's Information Calling [`fileRequests.copy(fileRequestId: string, copyBody: FileRequestCopyBody)`](http://opensource.box.com/box-node-sdk/jsdoc/FileRequestsManager.html#copy) copies an existing file request that is already present on one folder, and applies it to another folder. If you want to set certain fields of the newly copied file request when it is created, set those fields in the [`FileRequestCopyBody`](http://opensource.box.com/box-node-sdk/jsdoc/FileRequestCopyBody.html) that you pass into copy method. ``` client.fileRequests.copy(fileRequestId, { folder: { id: '157979815648', type: 'folder' } }).then((r: FileRequest) => { // do something with the copied file request console.log(r) }); ``` ## Update a File Request's Information Calling [`fileRequests.update(fileRequestId: string, updateBody: FileRequestUpdateBody)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFileRequest.html#updateInfo) updates a file request. This can be used to activate or deactivate a file request using [`FileRequestUpdateBody`](http://opensource.box.com/box-node-sdk/jsdoc/FileRequestUpdateBody.html) that you pass into update method. ``` client.fileRequests.update(fileRequestId, { title: 'Updated title' }).then((r: FileRequest) => { // do something with the updated file request console.log(r) }); ``` ## Delete a File Request Calling `fileRequests.delete(fileRequestId: string)`][delete](http://opensource.box.com/box-node-sdk/jsdoc/FileRequestsManager.html#delete) deletes a file request permanently. ``` client.fileRequests.delete('2484517969').then(() => console.log('Removed file request')); ``` --- ### File Requests **Type:** page | **Section:** Additional Resources File Requests File request objects represent a file request associated with a folder. Get a File Request's Information Copy a File Request's… # File Requests File request objects represent a file request associated with a folder. - [Get a File Request's Information](#get-a-file-requests-information) - [Copy a File Request's Information](#copy-a-file-requests-information) - [Update a File Request's Information](#update-a-file-requests-information) - [Delete a File Request](#delete-a-file-request) ## Get a File Request's Information Calling [`getInfo()`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFileRequest.html#getInfo) returns information on a file request. ``` BoxFileRequest fileRequest = new BoxFileRequest(api, "id"); BoxFileRequest.Info fileRequestInfo = fileRequest.getInfo(); ``` ## Copy a File Request's Information Calling [`copyInfo(String folderId)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxTask.html#copyInfo) copies an existing file request that is already present on one folder, and applies it to another folder. If you want to set certain fields of the newly copied file request when it is created, set those fields in the `BoxFileRequest.Info` that you pass into this method [`copyInfo(BoxFileRequest.Info info, String folderId)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxTask.html#copyInfo). ``` BoxFileRequest fileRequest = new BoxFileRequest(api, "id"); BoxFileRequest.Info fileRequestInfo = fileRequest.new Info(); fileRequestInfo.setDescription("Following documents are requested for your process"); fileRequestInfo.setIsDescriptionRequired(true); fileRequestInfo.setStatus(BoxFileRequest.Status.ACTIVE); fileRequestInfo = fileRequest.copyInfo(fileRequestInfo, "folderId"); ``` ## Update a File Request's Information Calling [`updateInfo(BoxFileRequest.Info info)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFileRequest.html#updateInfo) updates a file request. This can be used to activate or deactivate a file request. ``` BoxFileRequest fileRequest = new BoxFileRequest(api, "id"); BoxFileRequest.Info fileRequestInfo = fileRequest.new Info(); fileRequestInfo.setDescription("Following documents are requested for your process"); fileRequestInfo.setIsDescriptionRequired(true); fileRequestInfo.setStatus(BoxFileRequest.Status.ACTIVE); fileRequestInfo = fileRequest.updateInfo(fileRequestInfo); ``` ## Delete a File Request Calling [`delete()`](https://box.github.io/box-java-sdk/javadoc/com/box/sdk/BoxFileRequest.html#delete) deletes a file request permanently. ``` BoxFileRequest fileRequest = new BoxFileRequest(api, "id"); fileRequest.delete(); ``` --- ### File Requests **Type:** page | **Section:** Additional Resources File Requests File request objects represent a file request associated with a folder. Get a File Request's Information Copy a File Request's… # File Requests File request objects represent a file request associated with a folder. - [Get a File Request's Information](#get-a-file-requests-information) - [Copy a File Request's Information](#copy-a-file-requests-information) - [Update a File Request's Information](#update-a-file-requests-information) - [Delete a File Request](#delete-a-file-request) ## Get a File Request's Information To get a file request object, first call [`client.file_request(file_request_id)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.client.html#boxsdk.client.client.Client.file_request) to construct the appropriate [`FileRequest`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.file_request.FileRequest) object, and then calling [`file_request.get(*, fields=None, headers=None, **kwargs)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.base_object.BaseObject.get) will return the [`FileRequest`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.file_request.FileRequest) object populated with data from the API, leaving the original object unmodified. ``` file_request = client.file_request(file_request_id='123456').get() print(f'File request {file_request.id} on folder {file_request.folder.name}') ``` ## Copy a File Request's Information To copy a file request, first call [`client.file_request(file_request_id)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.client.html#boxsdk.client.client.Client.file_request) to construct the appropriate [`FileRequest`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.file_request.FileRequest) object, and then calling [`file_request.copy(folder, description=None, title=None, expires_at=None, require_description=None, require_email=None, status=None)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.file_request.FileRequest.copy). It will return the [`FileRequest`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.file_request.FileRequest) object populated with data new created file request from the API. ``` file_request = client.file_request(file_request_id='123456') folder = client.folder(folder_id='123456789') new_file_request = file_request.copy(folder=folder, title="Copied file request") ``` ## Update a File Request's Information To update a file request object, call [`file_request.update_info(data=file_request_update)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.base_object.BaseObject.update_info) with a `dict` of properties to update on the file request. This method returns a newly updated [`FileRequest`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.file_request.FileRequest) object, leaving the original object unmodified. ``` from boxsdk.object.file_request import StatusState update_data = { "description": 'Updated description', "is_email_required": True, "status": StatusState.ACTIVE } file_request.update_info(data=update_data) ``` ## Delete a File Request To delete a file request, call [`file_request.delete()`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.base_object.BaseObject.delete), it deletes a file request permanently. ``` file_request = client.file_request(file_request_id='123456') file_request.delete() ``` --- ### File Requests **Type:** page | **Section:** Additional Resources File Requests File request objects represent a file request associated with a folder. Get a File Request's Information Copy a File Request's… # File Requests File request objects represent a file request associated with a folder. - [Get a File Request's Information](#get-a-file-requests-information) - [Copy a File Request's Information](#copy-a-file-requests-information) - [Update a File Request's Information](#update-a-file-requests-information) - [Delete a File Request](#delete-a-file-request) ## Get a File Request's Information Calling `FileRequestsManager.GetFileRequestByIdAsync(string fileRequestId)`returns information on a file request. ``` BoxFileRequestObject fileRequest = await client.FileRequestsManager.GetFileRequestByIdAsync("12345"); ``` ## Copy a File Request's Information Calling `FileRequestsManager.CopyFileRequestAsync(string fileRequestId, BoxFileRequestCopyRequest copyRequest)` copies an existing file request that is already present on one folder, and applies it to another folder. ``` var destinationFolder = new BoxRequestEntity { Id = "123456", Type = BoxType.folder }; var copyRequest = new BoxFileRequestCopyRequest { Description = "New file request description", Folder = destinationFolder }; BoxFileRequestObject fileRequest = await client.FileRequestsManager.CopyFileRequestAsync("12345", copyRequest); ``` ## Update a File Request's Information Calling `FileRequestsManager.UpdateFileRequestAsync(string fileRequestId, BoxFileRequestUpdateRequest updateRequest)` updates a file request. This can be used to activate or deactivate a file request. ``` var updateRequest = new BoxFileRequestUpdateRequest { Description = "New file request description", Status = BoxFileRequestStatus.inactive }; BoxFileRequestObject fileRequest = await client.FileRequestsManager.UpdateFileRequestAsync("12345", updateRequest); ``` ## Delete a File Request Calling `FileRequestsManager.DeleteFileRequestAsync(string fileRequestId)` deletes a file request permanently. ``` bool isSuccess = await client.FileRequestsManager.DeleteFileRequestAsync("12345"); ``` --- ### File Requests **Type:** page | **Section:** Additional Resources File Requests File request objects represent a file request associated with a folder. Get a File Request's Information Copy a File Request's… # File Requests File request objects represent a file request associated with a folder. - [Get a File Request's Information](#get-a-file-requests-information) - [Copy a File Request's Information](#copy-a-file-requests-information) - [Update a File Request's Information](#update-a-file-requests-information) - [Delete a File Request](#delete-a-file-request) ## Get a File Request's Information To retrieve information about a file request, call [`client.fileRequests.get(fileRequestId::completion:)`](https://opensource.box.com/box-ios-sdk/Classes/FileRequestsModule.html#/s:6BoxSDK18FileRequestsModuleC3get13fileRequestId10completionySS_ys6ResultOyAA0cH0CAA0A8SDKErrorCGctF) with the ID of the file request. ``` client.fileRequests.get(fileRequestId: "123456") { result in guard case let .success(fileRequest) = result else { print("Error getting file request") return } print("File request title: \(fileRequest.title ?? "n/a"), description: \(fileRequest.description ?? "n/a")") } ``` ## Copy a File Request's Information To copy an existing file request that is already present on one folder, and applies it to another folder, call [`client.fileRequests.copy(fileRequestId:copyRequest:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/FileRequestsModule.html#/s:6BoxSDK18FileRequestsModuleC4copy13fileRequestId0fH010completionySS_AA0ch4CopyH0Vys6ResultOyAA0cH0CAA0A8SDKErrorCGctF). You must provide the ID of file request you want to copy, and an instance of the [`FileRequestCopyRequest`](https://opensource.box.com/box-ios-sdk/Structs/FileRequestCopyRequest.html#/s:6BoxSDK015FileRequestCopyD0V5titleSSSgvp) class, where you can set fields to replace fields from source file request. ``` let destinationFolder = FolderEntity(id: "33333") let copyRequest = FileRequestCopyRequest( title: "New file request title", description: "New file request description", isEmailRequired: true, isDescriptionRequired: false, folder: destinationFolder ) client.fileRequests.copy(fileRequestId: "123456", copyRequest: copyRequest) { result in guard case let .success(fileRequest) = result else { print("Error copying file request") return } print("Copied file request title: \(fileRequest.title ?? "n/a"), description: \(fileRequest.description ?? "n/a")") } ``` ## Update a File Request's Information To update a file request, call [`client.fileRequests.update(fileRequestId:ifMatch:updateRequest:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/FileRequestsModule.html#/s:6BoxSDK18FileRequestsModuleC6update13fileRequestId7ifMatch0fH010completionySS_SSSgAA0ch6UpdateH0Vys6ResultOyAA0cH0CAA0A8SDKErrorCGctF) with the ID of the file request and with an instance of the [`FileRequestUpdateRequest`](https://opensource.box.com/box-ios-sdk/Structs/FileRequestUpdateRequest.html) class, where you can set fields you want to update. If you want to make sure that an item hasn't changed recently before making changes, you can pass the last observed `etag` value to the `ifMatch` parameter. This call can be used to activate or deactivate a file request. ``` let updateRequest = FileRequestUpdateRequest( title: "Updated file request title", description: "Updated file request description", status: .inactive, isEmailRequired: false, isDescriptionRequired: true ) client.fileRequests.update(fileRequestId: "123456", updateRequest: updateRequest) { result in guard case let .success(fileRequest) = result else { print("Error updating file request") return } print("Updated file request title: \(fileRequest.title ?? "n/a"), description: \(fileRequest.description ?? "n/a")") } ``` ## Delete a File Request To delete a file request permanently, call [`client.fileRequests.delete(fileRequestId:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/FileRequestsModule.html#/s:6BoxSDK18FileRequestsModuleC6delete13fileRequestId10completionySS_ys6ResultOyytAA0A8SDKErrorCGctF) with the ID of the file request to delete. ``` client.fileRequests.delete(fileRequestId: "123456") { result in guard case .success = result else { print("Error removing file request") return } print("File request removed") } ``` --- ### File Requests **Type:** page | **Section:** Additional Resources File Requests File request objects represent a file request associated with a folder. Get a File Request's Information Copy a File Request's… # File Requests File request objects represent a file request associated with a folder. - [Get a File Request's Information](#get-a-file-requests-information) - [Copy a File Request's Information](#copy-a-file-requests-information) - [Update a File Request's Information](#update-a-file-requests-information) - [Delete a File Request](#delete-a-file-request) ## Get a File Request's Information To retrieve information about a file request, call [`client.fileRequests.get(fileRequestId::completion:)`](https://opensource.box.com/box-ios-sdk/Classes/FileRequestsModule.html#/s:6BoxSDK18FileRequestsModuleC3get13fileRequestId10completionySS_ys6ResultOyAA0cH0CAA0A8SDKErrorCGctF) with the ID of the file request. ``` client.fileRequests.get(fileRequestId: "123456") { result in guard case let .success(fileRequest) = result else { print("Error getting file request") return } print("File request title: \(fileRequest.title ?? "n/a"), description: \(fileRequest.description ?? "n/a")") } ``` ## Copy a File Request's Information To copy an existing file request that is already present on one folder, and applies it to another folder, call [`client.fileRequests.copy(fileRequestId:copyRequest:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/FileRequestsModule.html#/s:6BoxSDK18FileRequestsModuleC4copy13fileRequestId0fH010completionySS_AA0ch4CopyH0Vys6ResultOyAA0cH0CAA0A8SDKErrorCGctF). You must provide the ID of file request you want to copy, and an instance of the [`FileRequestCopyRequest`](https://opensource.box.com/box-ios-sdk/Structs/FileRequestCopyRequest.html#/s:6BoxSDK015FileRequestCopyD0V5titleSSSgvp) class, where you can set fields to replace fields from source file request. ``` let destinationFolder = FolderEntity(id: "33333") let copyRequest = FileRequestCopyRequest( title: "New file request title", description: "New file request description", isEmailRequired: true, isDescriptionRequired: false, folder: destinationFolder ) client.fileRequests.copy(fileRequestId: "123456", copyRequest: copyRequest) { result in guard case let .success(fileRequest) = result else { print("Error copying file request") return } print("Copied file request title: \(fileRequest.title ?? "n/a"), description: \(fileRequest.description ?? "n/a")") } ``` ## Update a File Request's Information To update a file request, call [`client.fileRequests.update(fileRequestId:ifMatch:updateRequest:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/FileRequestsModule.html#/s:6BoxSDK18FileRequestsModuleC6update13fileRequestId7ifMatch0fH010completionySS_SSSgAA0ch6UpdateH0Vys6ResultOyAA0cH0CAA0A8SDKErrorCGctF) with the ID of the file request and with an instance of the [`FileRequestUpdateRequest`](https://opensource.box.com/box-ios-sdk/Structs/FileRequestUpdateRequest.html) class, where you can set fields you want to update. If you want to make sure that an item hasn't changed recently before making changes, you can pass the last observed `etag` value to the `ifMatch` parameter. This call can be used to activate or deactivate a file request. ``` let updateRequest = FileRequestUpdateRequest( title: "Updated file request title", description: "Updated file request description", status: .inactive, isEmailRequired: false, isDescriptionRequired: true ) client.fileRequests.update(fileRequestId: "123456", updateRequest: updateRequest) { result in guard case let .success(fileRequest) = result else { print("Error updating file request") return } print("Updated file request title: \(fileRequest.title ?? "n/a"), description: \(fileRequest.description ?? "n/a")") } ``` ## Delete a File Request To delete a file request permanently, call [`client.fileRequests.delete(fileRequestId:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/FileRequestsModule.html#/s:6BoxSDK18FileRequestsModuleC6delete13fileRequestId10completionySS_ys6ResultOyytAA0A8SDKErrorCGctF) with the ID of the file request to delete. ``` client.fileRequests.delete(fileRequestId: "123456") { result in guard case .success = result else { print("Error removing file request") return } print("File request removed") } ``` --- ### FileClassificationsManager **Type:** page | **Section:** Additional Resources FileClassificationsManager Get classification on file Add classification to file Update classification on file Remove classification from… # FileClassificationsManager - [Get classification on file](#get-classification-on-file) - [Add classification to file](#add-classification-to-file) - [Update classification on file](#update-classification-on-file) - [Remove classification from file](#remove-classification-from-file) ## Get classification on file Retrieves the classification metadata instance that has been applied to a file. This API can also be called by including the enterprise ID in the URL explicitly, for example `/files/:id//enterprise_12345/securityClassification-6VMVochwUWo`. This operation is performed by calling function `getClassificationOnFile`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-files-id-metadata-enterprise-securityClassification-6VMVochwUWo/). ``` await client.fileClassifications.getClassificationOnFile(file.id); ``` ### Arguments fileId `string` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" optionalsInput `GetClassificationOnFileOptionalsInput` ### Returns This function returns a value of type `Classification`. Returns an instance of the `securityClassification` metadata template, which contains a `Box__Security__Classification__Key` field that lists all the classifications available to this enterprise. ## Add classification to file Adds a classification to a file by specifying the label of the classification to add. This API can also be called by including the enterprise ID in the URL explicitly, for example `/files/:id//enterprise_12345/securityClassification-6VMVochwUWo`. This operation is performed by calling function `addClassificationToFile`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-files-id-metadata-enterprise-securityClassification-6VMVochwUWo/). ``` await client.fileClassifications.addClassificationToFile(file.id, { requestBody: { boxSecurityClassificationKey: classification.key, } satisfies AddClassificationToFileRequestBody, } satisfies AddClassificationToFileOptionalsInput); ``` ### Arguments fileId `string` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" optionalsInput `AddClassificationToFileOptionalsInput` ### Returns This function returns a value of type `Classification`. Returns the classification template instance that was applied to the file. ## Update classification on file Updates a classification on a file. The classification can only be updated if a classification has already been applied to the file before. When editing classifications, only values are defined for the enterprise will be accepted. This operation is performed by calling function `updateClassificationOnFile`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-files-id-metadata-enterprise-securityClassification-6VMVochwUWo/). ``` await client.fileClassifications.updateClassificationOnFile(file.id, [ new UpdateClassificationOnFileRequestBody({ value: secondClassification.key, }), ]); ``` ### Arguments fileId `string` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" requestBody `readonly UpdateClassificationOnFileRequestBody[]` - Request body of updateClassificationOnFile method optionalsInput `UpdateClassificationOnFileOptionalsInput` ### Returns This function returns a value of type `Classification`. Returns the updated classification metadata template instance. ## Remove classification from file Removes any classifications from a file. This API can also be called by including the enterprise ID in the URL explicitly, for example `/files/:id//enterprise_12345/securityClassification-6VMVochwUWo`. This operation is performed by calling function `deleteClassificationFromFile`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-files-id-metadata-enterprise-securityClassification-6VMVochwUWo/). ``` await client.fileClassifications.deleteClassificationFromFile(file.id); ``` ### Arguments fileId `string` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" optionalsInput `DeleteClassificationFromFileOptionalsInput` ### Returns This function returns a value of type `undefined`. Returns an empty response when the classification is successfully deleted. --- ### FileClassificationsManager **Type:** page | **Section:** Additional Resources FileClassificationsManager Get classification on file Add classification to file Update classification on file Remove classification from… # FileClassificationsManager - [Get classification on file](#get-classification-on-file) - [Add classification to file](#add-classification-to-file) - [Update classification on file](#update-classification-on-file) - [Remove classification from file](#remove-classification-from-file) ## Get classification on file Retrieves the classification metadata instance that has been applied to a file. This API can also be called by including the enterprise ID in the URL explicitly, for example `/files/:id//enterprise_12345/securityClassification-6VMVochwUWo`. This operation is performed by calling function `get_classification_on_file`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-files-id-metadata-enterprise-securityClassification-6VMVochwUWo/). ``` client.file_classifications.get_classification_on_file(file.id) ``` ### Arguments file_id `str` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `Classification`. Returns an instance of the `securityClassification` metadata template, which contains a `Box__Security__Classification__Key` field that lists all the classifications available to this enterprise. ## Add classification to file Adds a classification to a file by specifying the label of the classification to add. This API can also be called by including the enterprise ID in the URL explicitly, for example `/files/:id//enterprise_12345/securityClassification-6VMVochwUWo`. This operation is performed by calling function `add_classification_to_file`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-files-id-metadata-enterprise-securityClassification-6VMVochwUWo/). ``` client.file_classifications.add_classification_to_file( file.id, box_security_classification_key=classification.key ) ``` ### Arguments file_id `str` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" box_security_classification_key `Optional[str]` - The name of the classification to apply to this file. To list the available classifications in an enterprise, use the classification API to retrieve the [classification template](e://get_metadata_templates_enterprise_securityClassification-6VMVochwUWo_schema) which lists all available classification keys. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `Classification`. Returns the classification template instance that was applied to the file. ## Update classification on file Updates a classification on a file. The classification can only be updated if a classification has already been applied to the file before. When editing classifications, only values are defined for the enterprise will be accepted. This operation is performed by calling function `update_classification_on_file`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-files-id-metadata-enterprise-securityClassification-6VMVochwUWo/). ``` client.file_classifications.update_classification_on_file( file.id, [UpdateClassificationOnFileRequestBody(value=second_classification.key)] ) ``` ### Arguments file_id `str` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" request_body `List[UpdateClassificationOnFileRequestBody]` - Request body of updateClassificationOnFile method extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `Classification`. Returns the updated classification metadata template instance. ## Remove classification from file Removes any classifications from a file. This API can also be called by including the enterprise ID in the URL explicitly, for example `/files/:id//enterprise_12345/securityClassification-6VMVochwUWo`. This operation is performed by calling function `delete_classification_from_file`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-files-id-metadata-enterprise-securityClassification-6VMVochwUWo/). ``` client.file_classifications.delete_classification_from_file(file.id) ``` ### Arguments file_id `str` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `None`. Returns an empty response when the classification is successfully deleted. --- ### FileMetadataManager **Type:** page | **Section:** Additional Resources FileMetadataManager List metadata instances on file Get metadata instance on file Create metadata instance on file Update metadata instance… # FileMetadataManager - [List metadata instances on file](#list-metadata-instances-on-file) - [Get metadata instance on file](#get-metadata-instance-on-file) - [Create metadata instance on file](#create-metadata-instance-on-file) - [Update metadata instance on file](#update-metadata-instance-on-file) - [Remove metadata instance from file](#remove-metadata-instance-from-file) ## List metadata instances on file Retrieves all metadata for a given file. This operation is performed by calling function `getFileMetadata`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-files-id-metadata/). ``` await client.fileMetadata.getFileMetadata(file.id); ``` ### Arguments fileId `string` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" optionalsInput `GetFileMetadataOptionalsInput` ### Returns This function returns a value of type `Metadatas`. Returns all the metadata associated with a file. This API does not support pagination and will therefore always return all of the metadata associated to the file. ## Get metadata instance on file Retrieves the instance of a metadata template that has been applied to a file. This operation is performed by calling function `getFileMetadataById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-files-id-metadata-id-id/). ``` await client.fileMetadata.getFileMetadataById( file.id, 'global' as GetFileMetadataByIdScope, 'properties', ); ``` ### Arguments fileId `string` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" scope `GetFileMetadataByIdScope` - The scope of the metadata template. Example: "global" templateKey `string` - The name of the metadata template. Example: "properties" optionalsInput `GetFileMetadataByIdOptionalsInput` ### Returns This function returns a value of type `MetadataFull`. An instance of the metadata template that includes additional "key:value" pairs defined by the user or an application. ## Create metadata instance on file Applies an instance of a metadata template to a file. In most cases only values that are present in the metadata template will be accepted, except for the `global.properties` template which accepts any key-value pair. This operation is performed by calling function `createFileMetadataById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-files-id-metadata-id-id/). ``` await client.fileMetadata.createFileMetadataById( file.id, 'enterprise' as CreateFileMetadataByIdScope, templateKey, { ['name']: 'John', ['age']: 23, ['birthDate']: '2001-01-03T02:20:50.520Z', ['countryCode']: 'US', ['sports']: ['basketball', 'tennis'], }, ); ``` ### Arguments fileId `string` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" scope `CreateFileMetadataByIdScope` - The scope of the metadata template. Example: "global" templateKey `string` - The name of the metadata template. Example: "properties" requestBody `CreateFileMetadataByIdRequestBody` - Request body of createFileMetadataById method optionalsInput `CreateFileMetadataByIdOptionalsInput` ### Returns This function returns a value of type `MetadataFull`. Returns the instance of the template that was applied to the file, including the data that was applied to the template. ## Update metadata instance on file Updates a piece of metadata on a file. The metadata instance can only be updated if the template has already been applied to the file before. When editing metadata, only values that match the metadata template schema will be accepted. The update is applied atomically. If any errors occur during the application of the operations, the metadata instance will not be changed. This operation is performed by calling function `updateFileMetadataById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-files-id-metadata-id-id/). ``` await client.fileMetadata.updateFileMetadataById( file.id, 'enterprise' as UpdateFileMetadataByIdScope, templateKey, [ { op: 'replace' as UpdateFileMetadataByIdRequestBodyOpField, path: '/name', value: 'Jack', } satisfies UpdateFileMetadataByIdRequestBody, { op: 'replace' as UpdateFileMetadataByIdRequestBodyOpField, path: '/age', value: 24, } satisfies UpdateFileMetadataByIdRequestBody, { op: 'replace' as UpdateFileMetadataByIdRequestBodyOpField, path: '/birthDate', value: '2000-01-03T02:20:50.520Z', } satisfies UpdateFileMetadataByIdRequestBody, { op: 'replace' as UpdateFileMetadataByIdRequestBodyOpField, path: '/countryCode', value: 'CA', } satisfies UpdateFileMetadataByIdRequestBody, { op: 'replace' as UpdateFileMetadataByIdRequestBodyOpField, path: '/sports', value: ['football'], } satisfies UpdateFileMetadataByIdRequestBody, ], ); ``` ### Arguments fileId `string` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" scope `UpdateFileMetadataByIdScope` - The scope of the metadata template. Example: "global" templateKey `string` - The name of the metadata template. Example: "properties" requestBody `readonly UpdateFileMetadataByIdRequestBody[]` - Request body of updateFileMetadataById method optionalsInput `UpdateFileMetadataByIdOptionalsInput` ### Returns This function returns a value of type `MetadataFull`. Returns the updated metadata template instance, with the custom template data included. ## Remove metadata instance from file Deletes a piece of file metadata. This operation is performed by calling function `deleteFileMetadataById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-files-id-metadata-id-id/). ``` await client.fileMetadata.deleteFileMetadataById( file.id, 'enterprise' as DeleteFileMetadataByIdScope, templateKey, ); ``` ### Arguments fileId `string` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" scope `DeleteFileMetadataByIdScope` - The scope of the metadata template. Example: "global" templateKey `string` - The name of the metadata template. Example: "properties" optionalsInput `DeleteFileMetadataByIdOptionalsInput` ### Returns This function returns a value of type `undefined`. Returns an empty response when the metadata is successfully deleted. --- ### FileMetadataManager **Type:** page | **Section:** Additional Resources FileMetadataManager List metadata instances on file Get metadata instance on file Create metadata instance on file Update metadata instance… # FileMetadataManager - [List metadata instances on file](#list-metadata-instances-on-file) - [Get metadata instance on file](#get-metadata-instance-on-file) - [Create metadata instance on file](#create-metadata-instance-on-file) - [Update metadata instance on file](#update-metadata-instance-on-file) - [Remove metadata instance from file](#remove-metadata-instance-from-file) ## List metadata instances on file Retrieves all metadata for a given file. This operation is performed by calling function `get_file_metadata`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-files-id-metadata/). ``` client.file_metadata.get_file_metadata(file.id) ``` ### Arguments file_id `str` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `Metadatas`. Returns all the metadata associated with a file. This API does not support pagination and will therefore always return all of the metadata associated to the file. ## Get metadata instance on file Retrieves the instance of a metadata template that has been applied to a file. This operation is performed by calling function `get_file_metadata_by_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-files-id-metadata-id-id/). ``` client.file_metadata.get_file_metadata_by_id( file.id, GetFileMetadataByIdScope.GLOBAL, "properties" ) ``` ### Arguments file_id `str` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" scope `GetFileMetadataByIdScope` - The scope of the metadata template. Example: "global" template_key `str` - The name of the metadata template. Example: "properties" extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `MetadataFull`. An instance of the metadata template that includes additional "key:value" pairs defined by the user or an application. ## Create metadata instance on file Applies an instance of a metadata template to a file. In most cases only values that are present in the metadata template will be accepted, except for the `global.properties` template which accepts any key-value pair. This operation is performed by calling function `create_file_metadata_by_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-files-id-metadata-id-id/). ``` client.file_metadata.create_file_metadata_by_id( file.id, CreateFileMetadataByIdScope.ENTERPRISE, template_key, { "name": "John", "age": 23, "birthDate": "2001-01-03T02:20:50.520Z", "countryCode": "US", "sports": ["basketball", "tennis"], }, ) ``` ### Arguments file_id `str` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" scope `CreateFileMetadataByIdScope` - The scope of the metadata template. Example: "global" template_key `str` - The name of the metadata template. Example: "properties" request_body `Dict` - Request body of createFileMetadataById method extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `MetadataFull`. Returns the instance of the template that was applied to the file, including the data that was applied to the template. ## Update metadata instance on file Updates a piece of metadata on a file. The metadata instance can only be updated if the template has already been applied to the file before. When editing metadata, only values that match the metadata template schema will be accepted. The update is applied atomically. If any errors occur during the application of the operations, the metadata instance will not be changed. This operation is performed by calling function `update_file_metadata_by_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-files-id-metadata-id-id/). ``` client.file_metadata.update_file_metadata_by_id( file.id, UpdateFileMetadataByIdScope.ENTERPRISE, template_key, [ UpdateFileMetadataByIdRequestBody( op=UpdateFileMetadataByIdRequestBodyOpField.REPLACE, path="/name", value="Jack", ), UpdateFileMetadataByIdRequestBody( op=UpdateFileMetadataByIdRequestBodyOpField.REPLACE, path="/age", value=24 ), UpdateFileMetadataByIdRequestBody( op=UpdateFileMetadataByIdRequestBodyOpField.REPLACE, path="/birthDate", value="2000-01-03T02:20:50.520Z", ), UpdateFileMetadataByIdRequestBody( op=UpdateFileMetadataByIdRequestBodyOpField.REPLACE, path="/countryCode", value="CA", ), UpdateFileMetadataByIdRequestBody( op=UpdateFileMetadataByIdRequestBodyOpField.REPLACE, path="/sports", value=["football"], ), ], ) ``` ### Arguments file_id `str` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" scope `UpdateFileMetadataByIdScope` - The scope of the metadata template. Example: "global" template_key `str` - The name of the metadata template. Example: "properties" request_body `List[UpdateFileMetadataByIdRequestBody]` - Request body of updateFileMetadataById method extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `MetadataFull`. Returns the updated metadata template instance, with the custom template data included. ## Remove metadata instance from file Deletes a piece of file metadata. This operation is performed by calling function `delete_file_metadata_by_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-files-id-metadata-id-id/). ``` client.file_metadata.delete_file_metadata_by_id( file.id, DeleteFileMetadataByIdScope.ENTERPRISE, template_key ) ``` ### Arguments file_id `str` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" scope `DeleteFileMetadataByIdScope` - The scope of the metadata template. Example: "global" template_key `str` - The name of the metadata template. Example: "properties" extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `None`. Returns an empty response when the metadata is successfully deleted. --- ### FileRequestsManager **Type:** page | **Section:** Additional Resources FileRequestsManager Get file request Update file request Delete file request Copy file request Get file request Retrieves the information… # FileRequestsManager - [Get file request](#get-file-request) - [Update file request](#update-file-request) - [Delete file request](#delete-file-request) - [Copy file request](#copy-file-request) ## Get file request Retrieves the information about a file request. This operation is performed by calling function `getFileRequestById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-file-requests-id/). ``` await client.fileRequests.getFileRequestById(fileRequestId); ``` ### Arguments fileRequestId `string` - The unique identifier that represent a file request. The ID for any file request can be determined by visiting a file request builder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/filerequest/123` the `file_request_id` is `123`. Example: "123" optionalsInput `GetFileRequestByIdOptionalsInput` ### Returns This function returns a value of type `FileRequest`. Returns a file request object. ## Update file request Updates a file request. This can be used to activate or deactivate a file request. This operation is performed by calling function `updateFileRequestById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-file-requests-id/). ``` await client.fileRequests.updateFileRequestById(copiedFileRequest.id, { title: 'updated title', description: 'updated description', } satisfies FileRequestUpdateRequest); ``` ### Arguments fileRequestId `string` - The unique identifier that represent a file request. The ID for any file request can be determined by visiting a file request builder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/filerequest/123` the `file_request_id` is `123`. Example: "123" requestBody `FileRequestUpdateRequest` - Request body of updateFileRequestById method optionalsInput `UpdateFileRequestByIdOptionalsInput` ### Returns This function returns a value of type `FileRequest`. Returns the updated file request object. ## Delete file request Deletes a file request permanently. This operation is performed by calling function `deleteFileRequestById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-file-requests-id/). ``` await client.fileRequests.deleteFileRequestById(updatedFileRequest.id); ``` ### Arguments fileRequestId `string` - The unique identifier that represent a file request. The ID for any file request can be determined by visiting a file request builder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/filerequest/123` the `file_request_id` is `123`. Example: "123" optionalsInput `DeleteFileRequestByIdOptionalsInput` ### Returns This function returns a value of type `undefined`. Returns an empty response when the file request has been successfully deleted. ## Copy file request Copies an existing file request that is already present on one folder, and applies it to another folder. This operation is performed by calling function `createFileRequestCopy`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-file-requests-id-copy/). ``` await client.fileRequests.createFileRequestCopy(fileRequestId, { folder: { id: fileRequest.folder.id, type: 'folder' as FileRequestCopyRequestFolderTypeField, } satisfies FileRequestCopyRequestFolderField, } satisfies FileRequestCopyRequest); ``` ### Arguments fileRequestId `string` - The unique identifier that represent a file request. The ID for any file request can be determined by visiting a file request builder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/filerequest/123` the `file_request_id` is `123`. Example: "123" requestBody `FileRequestCopyRequest` - Request body of createFileRequestCopy method optionalsInput `CreateFileRequestCopyOptionalsInput` ### Returns This function returns a value of type `FileRequest`. Returns updated file request object. --- ### FileRequestsManager **Type:** page | **Section:** Additional Resources FileRequestsManager Get file request Update file request Delete file request Copy file request Get file request Retrieves the information… # FileRequestsManager - [Get file request](#get-file-request) - [Update file request](#update-file-request) - [Delete file request](#delete-file-request) - [Copy file request](#copy-file-request) ## Get file request Retrieves the information about a file request. This operation is performed by calling function `get_file_request_by_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-file-requests-id/). ``` client.file_requests.get_file_request_by_id(file_request_id) ``` ### Arguments file_request_id `str` - The unique identifier that represent a file request. The ID for any file request can be determined by visiting a file request builder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/filerequest/123` the `file_request_id` is `123`. Example: "123" extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `FileRequest`. Returns a file request object. ## Update file request Updates a file request. This can be used to activate or deactivate a file request. This operation is performed by calling function `update_file_request_by_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-file-requests-id/). ``` client.file_requests.update_file_request_by_id( copied_file_request.id, title="updated title", description="updated description" ) ``` ### Arguments file_request_id `str` - The unique identifier that represent a file request. The ID for any file request can be determined by visiting a file request builder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/filerequest/123` the `file_request_id` is `123`. Example: "123" title `Optional[str]` - An optional new title for the file request. This can be used to change the title of the file request. This will default to the value on the existing file request. description `Optional[str]` - An optional new description for the file request. This can be used to change the description of the file request. This will default to the value on the existing file request. status `Optional[UpdateFileRequestByIdStatus]` - An optional new status of the file request. When the status is set to `inactive`, the file request will no longer accept new submissions, and any visitor to the file request URL will receive a `HTTP 404` status code. This will default to the value on the existing file request. is_email_required `Optional[bool]` - Whether a file request submitter is required to provide their email address. When this setting is set to true, the Box UI will show an email field on the file request form. This will default to the value on the existing file request. is_description_required `Optional[bool]` - Whether a file request submitter is required to provide a description of the files they are submitting. When this setting is set to true, the Box UI will show a description field on the file request form. This will default to the value on the existing file request. expires_at `Optional[DateTime]` - The date after which a file request will no longer accept new submissions. After this date, the `status` will automatically be set to `inactive`. This will default to the value on the existing file request. if_match `Optional[str]` - Ensures this item hasn't recently changed before making changes. Pass in the item's last observed `etag` value into this header and the endpoint will fail with a `412 Precondition Failed` if it has changed since. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `FileRequest`. Returns the updated file request object. ## Delete file request Deletes a file request permanently. This operation is performed by calling function `delete_file_request_by_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-file-requests-id/). ``` client.file_requests.delete_file_request_by_id(updated_file_request.id) ``` ### Arguments file_request_id `str` - The unique identifier that represent a file request. The ID for any file request can be determined by visiting a file request builder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/filerequest/123` the `file_request_id` is `123`. Example: "123" extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `None`. Returns an empty response when the file request has been successfully deleted. ## Copy file request Copies an existing file request that is already present on one folder, and applies it to another folder. This operation is performed by calling function `create_file_request_copy`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-file-requests-id-copy/). ``` client.file_requests.create_file_request_copy( file_request_id, CreateFileRequestCopyFolder( id=file_request.folder.id, type=CreateFileRequestCopyFolderTypeField.FOLDER ), ) ``` ### Arguments file_request_id `str` - The unique identifier that represent a file request. The ID for any file request can be determined by visiting a file request builder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/filerequest/123` the `file_request_id` is `123`. Example: "123" folder `CreateFileRequestCopyFolder` - The folder to associate the new file request to. title `Optional[str]` - An optional new title for the file request. This can be used to change the title of the file request. This will default to the value on the existing file request. description `Optional[str]` - An optional new description for the file request. This can be used to change the description of the file request. This will default to the value on the existing file request. status `Optional[CreateFileRequestCopyStatus]` - An optional new status of the file request. When the status is set to `inactive`, the file request will no longer accept new submissions, and any visitor to the file request URL will receive a `HTTP 404` status code. This will default to the value on the existing file request. is_email_required `Optional[bool]` - Whether a file request submitter is required to provide their email address. When this setting is set to true, the Box UI will show an email field on the file request form. This will default to the value on the existing file request. is_description_required `Optional[bool]` - Whether a file request submitter is required to provide a description of the files they are submitting. When this setting is set to true, the Box UI will show a description field on the file request form. This will default to the value on the existing file request. expires_at `Optional[DateTime]` - The date after which a file request will no longer accept new submissions. After this date, the `status` will automatically be set to `inactive`. This will default to the value on the existing file request. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `FileRequest`. Returns updated file request object. --- ### Files **Type:** page | **Section:** Additional Resources Files File objects represent individual files in Box. They can be used to download a file's contents, upload new versions, and perform other… # Files File objects represent individual files in Box. They can be used to download a file's contents, upload new versions, and perform other common file operations (move, copy, delete, etc.). [Files](#files) - [Get a File's Information](#get-a-files-information) - [Update a File's Information](#update-a-files-information) - [Download a File](#download-a-file) - [Get a File's Download URL](#get-a-files-download-url) - [Upload a File](#upload-a-file) [Chunked Upload](#chunked-upload) - [Automatic Uploader](#automatic-uploader) [Manual Process](#manual-process) - [Create Upload Session](#create-upload-session) - [Upload Part](#upload-part) - [Commit Upload Session](#commit-upload-session) - [Abort Upload Session](#abort-upload-session) - [Get Upload Session Parts](#get-upload-session-parts) - [Get Upload Session Status](#get-upload-session-status) [Upload Preflight Check](#upload-preflight-check) [Move a File](#move-a-file) [Copy a File](#copy-a-file) [Delete a File](#delete-a-file) [Get File Versions](#get-file-versions) [Upload a New Version of a File](#upload-a-new-version-of-a-file) [Download a Previous Version of a File](#download-a-previous-version-of-a-file) [Delete a Previous File Version](#delete-a-previous-file-version) [Find a File for a Shared Link](#find-a-file-for-a-shared-link) [Create or update a Shared Link](#create-or-update-a-shared-link) [Get a Shared Link](#get-a-shared-link) [Get information about Shared Link Permissions Options](#get-information-about-shared-link-permissions-options) [Remove a Shared Link](#remove-a-shared-link) [Promote Version](#promote-version) [Get Embed Link](#get-embed-link) [Lock a File](#lock-a-file) [Unlock a File](#unlock-a-file) [Get Representation Info](#get-representation-info) [Get Representation Content](#get-representation-content) [Create a Zip File](#create-a-zip-file) [Download a Zip File](#download-a-zip-file) ## Get a File's Information Calling [`files.get(fileID, options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Files.html#get) on a file returns a snapshot of the file's info. ``` client.files.get('11111') .then(file => { /* file -> { type: 'file', id: '11111', file_version: { type: 'file_version', id: '22222', sha1: '97b3dbba6eab7ad0f058240744c8636b7c7bea93' }, sequence_id: '1', etag: '1', sha1: '97b3dbba6eab7ad0f058240744c8636b7c7bea93', name: 'Puppy.png', description: '', size: 106833, path_collection: { total_count: 2, entries: [ { type: 'folder', id: '0', sequence_id: null, etag: null, name: 'All Files' }, { type: 'folder', id: '33333', sequence_id: '0', etag: '0', name: 'Collaborated Folder' } ] }, created_at: '2016-11-16T22:01:44-08:00', modified_at: '2016-11-16T22:01:51-08:00', trashed_at: null, purged_at: null, content_created_at: '2016-10-29T18:33:50-07:00', content_modified_at: '2016-10-29T18:33:50-07:00', created_by: { type: 'user', id: '44444', name: 'Owner', login: 'owner@example.com' }, modified_by: { type: 'user', id: '44444', name: 'Owner', login: 'owner@example.com' }, owned_by: { type: 'user', id: '44444', name: 'Owner', login: 'owner@example.com' }, shared_link: null, parent: { type: 'folder', id: '33333', sequence_id: '0', etag: '0', name: 'Collaborated Folder' }, item_status: 'active' } */ }); ``` Requesting information for only the fields you need with the `fields` option can improve performance and reduce the size of the network request. ``` // Only get information about a few specific fields. client.files.get('11111', { fields: 'size,owned_by' }) .then(file => { /* file -> { type: 'file', id: '11111', size: 106833, owned_by: { type: 'user', id: '44444', name: 'Owner', login: 'owner@example.com' } } */ }); ``` ## Update a File's Information Updating a file's information is done by calling [`files.update(fileID, updates, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Files.html#update) with the fields to be updated. ``` client.files.update('75937', { name : 'New name.pdf', fields: 'name' }) .then(updatedFile => { /* updatedFile => { type: 'file', id: '11111', name: 'New name.pdf' } */ }); ``` If you want to ensure that your updates do not overwrite any other updates (i.e. to prevent against possible race conditions), you can pass the last known value of the file's `etag` field via the `etag` option; this will generate an error if the file was modified between when you read that `etag` value and when your updates were processed by the API. ``` client.files.update('11111', { name: 'New name.pdf', etag: '5', fields: 'name' }) .then(updatedFile => { // ... }) .catch(err => { if (err.statusCode === 412) { // Precondition failed — the file was modified before our updates were processed // We should read the file again to ensure our updates are safe and retry } }); ``` ## Download a File A file can be downloaded by calling [`files.getReadStream(fileID, options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Files.html#getReadStream), which provides an instance of `stream.Readable` that will yield the file's contents. ``` var fs = require('fs'); client.files.getReadStream('12345', null, function(error, stream) { if (error) { // handle error } // write the file to disk var output = fs.createWriteStream('/path/to/file'); stream.pipe(output); }); ``` To download a previous version of the file, pass the `version` option: ``` client.files.getReadStream('123456', { version: '98765' }, callback); ``` To download only a subset of the file's contents, pass a byte range as an array of the byte indices to start and stop at to the `byteRange` option. **Note:** Byte indices are inclusive; for example, `[0, 99]` would download the first 100 bytes of the file. ``` client.files.getReadStream('12345', {byteRange: [0, 99] }, callback); ``` ## Get a File's Download URL The download URL of a file an be retrieved by calling [`files.getDownloadURL(fileID, options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Files.html#getDownloadURL). It returns the URL as a string. ``` client.files.getDownloadURL('12345') .then(downloadURL => { // downloadURL -> 'https://dl.boxcloud.com/...' }); ``` ## Upload a File The simplest way to upload a file to a folder is by calling the [`files.uploadFile(parentFolderID, filename, content, options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Files.html#uploadFile) method with a `stream.Readable` or `Buffer` of the file to upload. ``` var fs = require('fs'); var stream = fs.createReadStream('/path/to/My File.pdf'); var folderID = '0' client.files.uploadFile(folderID, 'My File.pdf', stream) .then(file => { /* file -> { total_count: 1, entries: [ { type: 'file', id: '11111', file_version: { type: 'file_version', id: '22222', sha1: '0beec7b5ea3f0fdbc95d0dd47f3c5bc275da8a33' }, sequence_id: '0', etag: '0', sha1: '0beec7b5ea3f0fdbc95d0dd47f3c5bc275da8a33', name: 'My File.pdf', description: '', size: 68431, path_collection: { total_count: 1, entries: [ { type: 'folder', id: '0', sequence_id: null, etag: null, name: 'All Files' } ] }, created_at: '2017-05-16T15:18:02-07:00', modified_at: '2017-05-16T15:18:02-07:00', trashed_at: null, purged_at: null, content_created_at: '2017-05-16T15:18:02-07:00', content_modified_at: '2017-05-16T15:18:02-07:00', created_by: { type: 'user', id: '33333', name: 'Test User', login: 'test@example.com' }, modified_by: { type: 'user', id: '33333', name: 'Test User', login: 'test@example.com' }, owned_by: { type: 'user', id: '33333', name: 'Test User', login: 'test@example.com' }, shared_link: null, parent: { type: 'folder', id: '0', sequence_id: null, etag: null, name: 'All Files' } item_status: 'active' } ] } */ }); ``` To preserve file timestamps, you may pass the created and modified times as optional parameters: ``` var fs = require('fs'); var stream = fs.createReadStream('/path/to/file'); var options = { content_created_at: '2015-05-12T17:38:14-0600', content_modified_at: '2016-02-15T22:42:09-0600', }; client.files.uploadFile('98768', 'New File', stream, options) .then(file => { // ... }); ``` If you want to pass a Readable you must pass the content length as an optional parameter. Here is an example of passing Base64 String as file content: ``` var {Readable} = require('stream'); var base64Content = 'TXkgY29udGVudAo='; // your base64 content var base64Buffer = Buffer.from(base64Content, 'base64'); // we are using just Readable to create a stream, but you can use any library you want var stream = new Readable() stream._read = () => { stream.push(base64Buffer); stream.push(null); }; // you have to pass options and define content length var options = { content_length: Buffer.byteLength(base64Content, 'base64') }; client.files.uploadFile('0', 'My Base64 File.txt', stream, options); ``` ## Chunked Upload For large files or in cases where the network connection is less reliable, you may want to upload the file in parts. This allows a single part to fail without aborting the entire upload, and failed parts can then be retried. ### Automatic Uploader The SDK provides a method of automatically handling a chunked upload; simply call [`files.getChunkedUploader(folderID, size, name, file, options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Files.html#getChunkedUploader) with the ID of the destination folder, the size and file name of the file to be uploaded, and a `Buffer` or `ReadableStream` of the file to be uploaded. ``` // Upload a 2GB file "huge.pdf" into folder 12345 var stream = fs.createReadStream('huge.pdf'); client.files.getChunkedUploader('12345', 2147483648, 'huge.pdf', stream) .then(uploader => uploader.start()) .then(file => { /* file -> { total_count: 1, entries: [ { type: 'file', id: '11111', file_version: { type: 'file_version', id: '22222', sha1: '0beec7b5ea3f0fdbc95d0dd47f3c5bc275da8a33' }, sequence_id: '0', etag: '0', sha1: '0beec7b5ea3f0fdbc95d0dd47f3c5bc275da8a33', name: 'huge.pdf', description: '', size: 2147483648, path_collection: { total_count: 1, entries: [ { type: 'folder', id: '12345', sequence_id: null, etag: null, name: 'My Folder' } ] }, created_at: '2017-05-16T15:18:02-07:00', modified_at: '2017-05-16T15:18:02-07:00', trashed_at: null, purged_at: null, content_created_at: '2017-05-16T15:18:02-07:00', content_modified_at: '2017-05-16T15:18:02-07:00', created_by: { type: 'user', id: '33333', name: 'Test User', login: 'test@example.com' }, modified_by: { type: 'user', id: '33333', name: 'Test User', login: 'test@example.com' }, owned_by: { type: 'user', id: '33333', name: 'Test User', login: 'test@example.com' }, shared_link: null, parent: { type: 'folder', id: '12345', sequence_id: null, etag: null, name: 'My Folder' } item_status: 'active' } ] } */ }); ``` A new version of a file can be uploaded in the same way by calling [`files.getNewVersionChunkedUploader(fileID, size, file, options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Files.html#getNewVersionChunkedUploader) with the ID of the file to upload a new version of, along with the size of the new version and a `Buffer` or `ReadableStream` of the new version. ``` // Upload a new 2GB version of file 98765 var stream = fs.createReadStream('huge.pdf'); client.files.getNewVersionChunkedUploader('11111', 2147483648, stream) .then(uploader => uploader.start()) .then(file => { /* file -> { total_count: 1, entries: [ { type: 'file', id: '11111', file_version: { type: 'file_version', id: '22222', sha1: '0beec7b5ea3f0fdbc95d0dd47f3c5bc275da8a33' }, sequence_id: '0', etag: '0', sha1: '0beec7b5ea3f0fdbc95d0dd47f3c5bc275da8a33', name: 'huge.pdf', description: '', size: 2147483648, path_collection: { total_count: 1, entries: [ { type: 'folder', id: '12345', sequence_id: null, etag: null, name: 'My Folder' } ] }, created_at: '2017-05-16T15:18:02-07:00', modified_at: '2017-05-21T15:18:02-07:00', trashed_at: null, purged_at: null, content_created_at: '2017-05-16T15:18:02-07:00', content_modified_at: '2017-05-21:18:02-07:00', created_by: { type: 'user', id: '33333', name: 'Test User', login: 'test@example.com' }, modified_by: { type: 'user', id: '33333', name: 'Test User', login: 'test@example.com' }, owned_by: { type: 'user', id: '33333', name: 'Test User', login: 'test@example.com' }, shared_link: null, parent: { type: 'folder', id: '12345', sequence_id: null, etag: null, name: 'My Folder' } item_status: 'active' } ] } */ }); ``` File attributes can be set on the newly uploaded file by passing the via the `options.fileAttributes` parameter: ``` // Upload a new file and prepopulate the description field var stream = fs.createReadStream('huge.pdf'); var options = { fileAttributes: { description: 'A very large PDF' } }; client.files.getChunkedUploader('12345', 2147483648, 'huge.pdf', stream, options) .then(uploader => uploader.start()) .then(file => { // ... }); ``` ### Manual Process For more complicated upload scenarios, such as those being coordinated across multiple processes or when an unrecoverable error occurs with the automatic uploader, the endpoints for chunked upload operations are also exposed directly. For example, this is roughly how a chunked upload is done manually: ``` // Upload a 2GB file "huge.pdf" into folder 12345 var parts = []; var hash = crypto.createHash('sha1'); client.files.createUploadSession( '12345', 2147483648, 'huge.pdf', function(err, session) { if (err) { // handle error return; } var sessionID = session.upload_session_id; // for each part in order, given `part` and `offset`... hash.update(part); client.files.uploadPart( sessionID, part, offset, 2147483648, null, function(err, partData) { if (err) { // handle error return; } parts.push(partData.part); } ); // once all parts have been uploaded... client.files.commitUploadSession(sessionID, hash.digest('base64'), {parts: parts}, callback); } ); ``` The individual endpoint methods are detailed below: #### Create Upload Session To start a chunked upload, create an upload session for the file by calling [`files.createUploadSession(folderID, size, name, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Files.html#createUploadSession) with the ID of the folder to upload into, as well as the size and file name of file being uploaded. This will check the destination folder for conflicts before starting the upload and pass the information for the upload session back to the callback. ``` // Create a session to upload a 2GB file "huge.pdf" into folder 12345 client.files.createUploadSession('12345', 2147483648, 'huge.pdf', callback); ``` #### Upload Part Parts are then uploaded by calling [`files.uploadPart(sessionID, part, offset, totalSize, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Files.html#uploadPart) with the ID of the upload session that was created, a `Buffer` containing the part of the file starting at `offset`, and the total size of the file being uploaded. When the upload of a part succeeds, the callback will be called with a part record, which should be stored for later integrity checking. ``` // Upload the part starting at byte offset 8388608 to upload session '93D9A837B45F' with part ID 'feedbeef' client.files.uploadPart('93D9A837B45F', part, 8388608, 2147483648, {part_id: 'feedbeef'}, callback); ``` #### Commit Upload Session Once all parts of the file have been uploaded, finalize the upload by calling [`files.commitUploadSession(sessionID, fileHash, options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Files.html#commitUploadSession) with the upload session ID and the base64-encoded SHA1 hash of the entire file. This will complete the upload and create the full file in the destination folder. Any valid file object attributes you want to assign to the newly-created file may be passed via the `options` parameter. See the [File object documentation](https://developer.box.com/en/reference/resources/file/) for more details. If you stored a list of part records for each uploaded part, you can pass them via `options.parts` for additional integrity checking. Otherwise, the API will assume that the list of parts is has received is the intended set. ``` // Finalize upload session 93D9A837B45F client.files.commitUploadSession( '93D9A837B45F', fileHash.digest('base64'), {description: 'A file I uploaded in chunks!'}, callback ); ``` #### Abort Upload Session An in-progress upload session may be destroyed, along with all parts already uploaded, by calling [`files.abortUploadSession(sessionID, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Files.html#abortUploadSession). This operation cannot be undone. ``` // Cancel upload session 93D9A837B45F client.files.abortUploadSession('93D9A837B45F', callback); ``` #### Get Upload Session Parts The list of parts successfully uploaded to an in-progress upload session can be retrieved by calling [`files.getUploadSessionParts(sessionID, options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Files.html#getUploadSessionParts). The list is returned as a paged collection using the `limit` and `offset` options. ``` // Get the list of parts already uploaded client.files.getUploadSessionParts('93D9A837B45F', {limit: 100}, callback); ``` #### Get Upload Session Status Information about an in-progress upload session can be retrieved by calling [`files.getUploadSession(sessionID, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Files.html#getUploadSession). ``` // Get info about upload session 93D9A837B45F client.files.getUploadSessionStatus('93D9A837B45F', callback); ``` ## Upload Preflight Check The Preflight Check in the [`files.preflightUploadFile(parentFolderID, fileData, options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Files.html#preflightUploadFile) method will verify that a file will be accepted by Box before you send all the bytes over the wire. Preflight checks verify all permissions as if the file was actually uploaded including: - Folder upload permission - File name collisions - File size caps - Folder and file name restrictions - Folder and account storage quota A successful response does not guarantee that your upload call will succeed, but in practice it has been shown to reduce failed uploads by more than 99%. Highly active folders, common filenames, and accounts near their quota limits may get a success for the preflight, and then have a real conflict during the actual upload. ``` // Verify that uploading a 200MB file named "Preso.ppt" to folder 12345 would succeed client.files.preflightUploadFile( '12345', { name: 'Preso.ppt', size: 200000000 }, null, callback ); ``` For uploading a new version of a file, use the [`files.preflightUploadNewFileVersion(fileID, fileData, options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Files.html#preflightUploadNewFileVersion) method. ``` // Check if uploading a larger version of this file will succeed client.files.preflightUploadNewFileVersion('87646', {size: 300000000}, null, callback); ``` ## Move a File To move a file from one folder to another, call [`files.move(fileID, newParentID, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Files.html#move) with the ID of the file to move and the ID of the folder to move it to. ``` // Move file 12345 to folder 9876 client.files.move('12345', '9876', callback); ``` ## Copy a File A file can be copied to a new folder with the [`files.copy(fileID, newParentID, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Files.html#copy) method. ``` var fileID = '11111'; var destinationFolderID = '22222'; client.files.copy(fileID, destinationFolderID) .then(fileCopy => { /* fileCopy -> { type: 'file', id: '11112', file_version: { type: 'file_version', id: '99999', sha1: '0beec7b5ea3f0fdbc95d0dd47f3c5bc275da8a33' }, sequence_id: '0', etag: '0', sha1: '0beec7b5ea3f0fdbc95d0dd47f3c5bc275da8a33', name: 'My File.pdf', description: '', size: 68431, path_collection: { total_count: 1, entries: [ { type: 'folder', id: '0', sequence_id: null, etag: null, name: 'All Files' }, { type: 'folder', id: '22222', sequence_id: null, etag: null, name: 'Personal Files' } ] }, created_at: '2017-05-16T15:18:02-07:00', modified_at: '2017-05-16T15:18:02-07:00', trashed_at: null, purged_at: null, content_created_at: '2017-05-16T15:18:02-07:00', content_modified_at: '2017-05-16T15:18:02-07:00', created_by: { type: 'user', id: '33333', name: 'Test User', login: 'test@example.com' }, modified_by: { type: 'user', id: '33333', name: 'Test User', login: 'test@example.com' }, owned_by: { type: 'user', id: '33333', name: 'Test User', login: 'test@example.com' }, shared_link: null, parent: { type: 'folder', id: '22222', sequence_id: null, etag: null, name: 'Personal Files' } item_status: 'active' } */ }); ``` An optional `name` parameter can also be passed to rename the file on copy. This can be used to avoid a name conflict when there is already an item with the same name in the target folder. ``` client.files.copy('12345', '0', {name: 'Renamed file.png'}, callback); ``` You can specify specific file version to copy by passing optional `version` parameter. ``` client.files.copy('12345', '0', {version: '1'}, callback); ``` ## Delete a File Calling the [`files.delete(fileID, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Files.html#delete) method will move the file to the user's trash. ``` client.files.delete('12345') .then(() => { // deletion succeeded — no value returned }); ``` If you want to ensure that your deletion does not overwrite any other updates (i.e. to prevent against possible race conditions), you can pass the last known value of the file's `etag` field via the `etag` option; this will generate an error if the file was modified between when you read that `etag` value and when the deletion is processed by the API. ``` client.files.delete('11111', { etag: '5' }) .then(() => { // File successfully deleted }) .catch(err => { if (err.statusCode === 412) { // Precondition failed — the file was modified before the deletion was processed // Read the file again to ensure it is safe to delete and then retry } }); ``` ## Get File Versions Retrieve a list of previous versions of a file by calling the [`files.getVersions(fileID, options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Files.html#getVersions). ``` client.files.getVersions('12345') .then(versions => { /* versions -> { total_count: 1, entries: [ { type: 'file_version', id: '22222', sha1: '359c6c1ed98081b9a69eb3513b9deced59c957f9', name: 'script.js', size: 92556, created_at: '2012-08-20T10:20:30-07:00', modified_at: '2012-11-28T13:14:58-08:00', modified_by: { type: 'user', id: '33333', name: 'Example User', login: 'user@example.com' } } ] } */ }); ``` Requesting information for only the fields you need with the `fields` option can improve performance and reduce the size of the network request. ``` // Only get information about a few specific fields. client.files.getVersions('12345', {fields: 'name,size,sha1'}) .then(versions => { /* versions -> { total_count: 1, entries: [ { type: 'file_version', id: '22222', sha1: '359c6c1ed98081b9a69eb3513b9deced59c957f9', name: 'script.js', size: 92556 } ] } */ }); ``` ## Upload a New Version of a File New versions of a file can be uploaded with the [`files.uploadNewFileVersion(fileID, content, options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Files.html#uploadNewFileVersion) method. ``` var fs = require('fs'); var stream = fs.createReadStream('/path/to/file.pdf'); client.files.uploadNewFileVersion('11111', stream) .then(file => { /* file -> { total_count: 1, entries: [ { type: 'file', id: '11111', file_version: { type: 'file_version', id: '22222', sha1: '0beec7b5ea3f0fdbc95d0dd47f3c5bc275da8a33' }, sequence_id: '0', etag: '0', sha1: '0beec7b5ea3f0fdbc95d0dd47f3c5bc275da8a33', name: 'My File.pdf', description: '', size: 68431, path_collection: { total_count: 1, entries: [ { type: 'folder', id: '0', sequence_id: null, etag: null, name: 'All Files' } ] }, created_at: '2017-05-16T15:18:02-07:00', modified_at: '2017-05-16T15:18:02-07:00', trashed_at: null, purged_at: null, content_created_at: '2017-05-16T15:18:02-07:00', content_modified_at: '2017-05-16T15:18:02-07:00', created_by: { type: 'user', id: '33333', name: 'Test User', login: 'test@example.com' }, modified_by: { type: 'user', id: '33333', name: 'Test User', login: 'test@example.com' }, owned_by: { type: 'user', id: '33333', name: 'Test User', login: 'test@example.com' }, shared_link: null, parent: { type: 'folder', id: '0', sequence_id: null, etag: null, name: 'All Files' } item_status: 'active' } ] } */ }) ``` If the stream passed in is not an fs stream, you must pass the stream length as an optional parameter as shown below. To rename the file on upload or manually specify a modification timestamp for the file, pass the corresponding optional parameter: ``` var fs = require('fs'); var stream = fs.createReadStream('/path/to/file.pdf'); var options = { name: 'New filename.pdf', content_modified_at: '2016-02-15T22:42:09-0600', content_length: 5 }; client.files.uploadNewFileVersion('11111', stream, options) .then(file => { /* file -> { total_count: 1, entries: [ { type: 'file', id: '11111', file_version: { type: 'file_version', id: '22222', sha1: '0beec7b5ea3f0fdbc95d0dd47f3c5bc275da8a33' }, sequence_id: '0', etag: '0', sha1: '0beec7b5ea3f0fdbc95d0dd47f3c5bc275da8a33', name: 'New filename.pdf', description: '', size: 68431, path_collection: { total_count: 1, entries: [ { type: 'folder', id: '0', sequence_id: null, etag: null, name: 'All Files' } ] }, created_at: '2017-05-16T15:18:02-07:00', modified_at: '2017-05-16T15:18:02-07:00', trashed_at: null, purged_at: null, content_created_at: '2017-05-16T15:18:02-07:00', content_modified_at: '2016-02-15T22:42:09-0600', created_by: { type: 'user', id: '33333', name: 'Test User', login: 'test@example.com' }, modified_by: { type: 'user', id: '33333', name: 'Test User', login: 'test@example.com' }, owned_by: { type: 'user', id: '33333', name: 'Test User', login: 'test@example.com' }, shared_link: null, parent: { type: 'folder', id: '0', sequence_id: null, etag: null, name: 'All Files' } item_status: 'active' } ] } */ }) ``` ## Download a Previous Version of a File For users with premium accounts, previous versions of a file can be downloaded by calling [`files.getReadStream(fileID, options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Files.html#getReadStream) with `options.version` specified. ``` var fs = require('fs'); client.files.getReadStream('12345', {version: '2'}, function(error, stream) { if (error) { // handle error } // write the file version to disk var output = fs.createWriteStream('/path/to/file'); stream.pipe(output); }); ``` ## Delete a Previous File Version An old version of a file can be moved to the trash by calling the [`files.deleteVersion(fileID, versionID, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Files.html#deleteVersion) method. ``` var fileID = '11111'; var versionID = '22222'; client.files.deleteVersion(fileID, versionID) .then(() => { // deletion succeeded — no value returned }); ``` If you want to ensure that your deletion does not overwrite any other updates (i.e. to prevent against possible race conditions), you can pass the last known value of the file's `etag` field via the `etag` option; this will generate an error if the file was modified between when you read that `etag` value and when the deletion is processed by the API. ``` var fileID = '11111'; var versionID = '22222'; client.files.deleteVersion(fileID, versionID, { etag: '5' }) .then(() => { // File version successfully deleted }) .catch(err => { if (err.statusCode === 412) { // Precondition failed — the file was modified before the deletion was processed // Read the file again to ensure it is safe to delete and then retry } }); ``` ## Find a File for a Shared Link To find a file given a shared link, use the [`sharedItems.get(url, password, options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/SharedItems.html#get) method. ``` client.sharedItems.get( 'https://app.box.com/s/gjasdasjhasd', 'letmein' ),then(file => { //... }); ``` ## Create or update a Shared Link To create or update a shared link for a file use [`files.update(fileID, updates, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Files.html#update) method, passing a new `shared_link` value in the `updates` parameter: ``` client.files.update('12345', { shared_link: { access: "open", password: "do-not-use-this-password", unshared_at: "2022-12-12T10:53:43-08:00", vanity_name: "my-shared-link", permissions: { can_view: true, can_download: true, can_edit: true } } }).then(file => { // ... }) ``` This will make a shared link to be `open` to everyone, but users will need to provide `password` to access the file. This link will be unshared at `"2022-12-12T10:53:43-08:00"`. By setting `vanity_name` we create custom URL `https://app.box.com/v/my-shared-link`. Custom URLs should not be used when sharing sensitive content as vanity URLs are a lot easier to guess than regular shared links. Additionally, everyone who has this link can `view`, `download` and `edit` the file. You can create shared link using default values ``` client.files.update('12345', { shared_link: {} }).then(file => { // ... }) ``` - Default `access` value comes from the access level specified by the enterprise admin. - Default `password`, `unshared_at`, `vanity_name` will be empty. - Default `permissions` comes from the values specified by the enterprise admin. You can remove any field set on a link by sending value `null` (or empty object when it comes to `permissions`). This will cause it's value to be default. For example, let's remove `access` and `permissions`: ``` client.files.update('12345', { shared_link: { access: null, permissions: {} } }).then(file => { // ... }) ``` This will remove `open` access, and it will fall back to default value set by the enterprise admin. The `permissions` we set on a shared link will be removed and default permissions defined by the enterprise admin will be applied. Other properties of the shared link will not be changed as we are not sending them. ## Get a Shared Link To check for an existing shared link on a file, inspect the `shared_link` field on a file object. This object, when present, contains a `unicode` string containing the shared link URL. ``` client.files.get('11111', { fields: 'shared_link' }) .then(file => { let url = file.shared_link.download_url //... }) ``` ## Get information about Shared Link Permissions Options To check what permissions can be set on a shared link you can ask for `shared_link_permission_options`: ``` client.files.get('11111', { fields: 'shared_link_permission_options' }) .then(file => { let options = file.shared_link_permission_options // options = [ "can_download", "can_preview", "can_edit" ] }) ``` Allowed values are defined by the enterprise admin in "Enterprise Settings -> Content & Sharing -> Actions link recipients can take", possible values are `["can_preview"]`, `["can_preview", "can_download"]` or `["can_preview", "can_download", "can_edit"]`. ## Remove a Shared Link A shared link for a file can be removed calling [`files.update(fileID, updates, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Files.html#update) with `null` for the `shared_link` value. ``` client.files.update('12345', { shared_link: null }).then(file => { // ... }) ``` ## Promote Version Promote file version to the top of the stack by calling the [`files.promoteVersion(fileID, versionID, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Files.html#promoteVersion) method. ``` var fileID = '11111'; var versionID = '22222'; client.files.promoteVersion(fileID, versionID) .then(version => { /* version -> { type: 'file_version', id: '33333', sha1: '12039d6dd9a7e6eefc78846802e', name: 'Stark Family Lineage.pptx', size: 37934912, created_at: '2013-11-20T13:20:50-08:00', modified_at: '2013-11-20T13:26:48-08:00', modified_by: { type: 'user', id: '44444', name: 'Eddard Stark', login: 'ned@winterfell.example.com' } } */ }); ``` ## Get Embed Link An embed link for a file can be generated by calling the [`files.getEmbedLink(fileID,callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Files.html#getEmbedLink) method. Embed link is an expiring URL for embedding a Box file preview into a webpage, usually via an `<iframe>` element. For more information, see the [API documentation](https://developer.box.com/en/reference/resources/file/#param-expiring_embed_link). ``` client.files.getEmbedLink('12345') .then(embedURL => { // embedURL -> "https://app.box.com/preview/expiring_embed/..." }); ``` ## Lock a File A file can be locked, which prevents other users from editing the file, by calling the [`files.lock(fileID, options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Files.html#lock) method You may optionally prevent other users from downloading the file, as well as set an expiration time for the lock. ``` var options = { expires_at: '2018-12-12T10:55:30-08:00', is_download_prevented: false } client.files.lock('11111', options) .then(file => { /* file -> { type: 'file', id: '11111', etag: '2', lock: { type: 'lock', id: '22222', created_by: { type: 'user', id: '33333', name: 'Example User', login: 'user@example.com' }, created_at: '2017-03-06T22:00:53-08:00', expires_at: '2018-12-12T10:55:30-08:00', is_download_prevented: false } } */ }); ``` ## Unlock a File A file can be unlocked by calling the [`files.unlock(fileID, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Files.html#unlock) method. ``` client.files.unlock('11111') .then(file => { /* file -> { type: 'file', id: '11111', etag: '2', lock: null } */ }); ``` ## Get Representation Info A file's representation info can be retrieved by calling [`files.getRepresentationInfo(fileID, representationTypes, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Files.html#getRepresentationInfo). You will be able to fetch information regarding PDF representation, thumbnail representation, multi-page images representation, and extracted text representation. ``` client.files.getRepresentationInfo('67890', client.files.representation.THUMBNAIL) .then(representations => { /* representations -> { entries: [ { content: { url_template: 'https://dl.boxcloud.com/.../{+asset_path}' }, info: { url: 'https://api.box.com/2.0/...' }, properties: { dimensions: '320x320', paged: 'false', thumb: 'true' }, representation: 'jpg', status: { state: 'success' } } ] } */ }); ``` You can specify your own set of representations to get info for by manually constructing the [X-Rep-Hints value](https://developer.box.com/en/reference/get-files-id/#param-X-Rep-Hints) and passing it as `representationTypes`. ``` client.files.getRepresentationInfo('67890', '[pdf][extracted_text]') .then(representations => { // ... }); ``` Setting the `generateRepresentations` option to `true` will automatically poll the status of all specified representations to generate them. ``` client.files.getRepresentationInfo('67890', '[pdf][extracted_text]', { generateRepresentations: true }) .then(representations => { // All representations should be generated // ... }); ``` ## Get Representation Content To get a stream over the contents of a single file representation, call the [`files.getRepresentationContent(fileID, representationType, options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Files.html#getRepresentationContent) method with the ID of the file and an [X-Rep-Hints value](https://developer.box.com/en/reference/get-files-id/#param-X-Rep-Hints) specifying the representation you want. **Note:** This method only supports getting the contents of a single representation; if your X-Rep-Hints value specifies multiple representations, the stream will be for an arbitrary one of them. ``` client.files.getRepresentationContent('12345', client.files.representation.PDF) .then(function(stream) { stream.on('data', function(chunk) { // read data from the stream }); }); ``` For representations with multiple files, e.g. multi-page images, you will need to pass an `assetPath` option to specify which file you want to fetch. ``` // If file 12345 is a document, its PNG representation will consist of one image per page of the document // Get the image of the first page of the document client.files.getRepresentationContent('12345', '[png?dimensions=1024x1024]', { assetPath: '1.png' }) .then(function(stream) { stream.on('data', function(chunk) { // read data from the stream }); }); ``` ## Create a Zip File Calling [`files.createZip(name, items, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Files.html#createZip) will let you create a new zip file with the specified name and with the specified items and will return a response with the download and status link. This file does not show up in your Box account, but will be temporarily available for download. ``` var name = 'test', items = [ { type: 'file', id: '466239504569' }, { type: 'folder', id: '466239504580' } ]; client.files.createZip(name, items) .then(zip => { /* zip -> { "download_url": "https://api.box.com/2.0/zip_downloads/124hfiowk3fa8kmrwh/content", "status_url": "https://api.box.com/2.0/zip_downloads/124hfiowk3fa8kmrwh/status", "expires_at": "2018-04-25T11:00:18-07:00", "name_conflicts": [ [ { "id": "100", "type": "file", "original_name": "salary.pdf", "download_name": "aqc823.pdf" }, { "id": "200", "type": "file", "original_name": "salary.pdf", "download_name": "aci23s.pdf" } ], [ { "id": "1000", "type": "folder", "original_name": "employees", "download_name": "3d366a_employees" }, { "id": "2000", "type": "folder", "original_name": "employees", "download_name": "3aa6a7_employees" } ] ] } */ }); ``` ## Download a Zip File Calling [`file.downloadZip(name, items, stream, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Files.html#downloadZip) will let you create a new zip file with the specified name and with the specified items and download it to the stream that is passed in. The return object is status object that contains information about the download, including whether it was successful. The created zip file does not show up in your Box account. ``` var name = 'test', items = [ { type: 'file', id: '466239504569' }, { type: 'folder', id: '466239504580' } ], stream = new Readable(); client.files.downloadZip(name, items, stream) .then(status => { /* status -> { "total_file_count": 20, "downloaded_file_count": 10, "skipped_file_count": 10, "skipped_folder_count": 10, "state": "succeeded" } */ }); ``` --- ### Files **Type:** page | **Section:** Additional Resources Files File objects represent individual files in Box. They can be used to download a file's contents, upload new versions, and perform other… # Files File objects represent individual files in Box. They can be used to download a file's contents, upload new versions, and perform other common file operations (move, copy, delete, etc.). - [Get a File's Information](#get-a-files-information) - [Update a File's Information](#update-a-files-information) - [Download a File](#download-a-file) - [Upload a File](#upload-a-file) - [Upload Preflight Check](#upload-preflight-check) - [Upload a Large File in Chunks](#upload-a-large-file-in-chunks) - [Upload a Large File in Chunks Including Attributes](#upload-a-large-file-in-chunks-including-attributes) - [Upload a Large File Version in Chunks](#upload-a-large-file-version-in-chunks) - [Upload a Large File Version in Chunks Including Attributes](#upload-a-large-file-version-in-chunks-including-attributes) - [Upload a Large File Or File Version Manually](#upload-a-large-file-or-file-version-manually) - [Move a File](#move-a-file) - [Copy a File](#copy-a-file) - [Delete a File](#delete-a-file) - [Get Previous Versions of a File](#get-previous-versions-of-a-file) - [Upload a New Version of a File](#upload-a-new-version-of-a-file) - [Download a Previous Version of a File](#download-a-previous-version-of-a-file) - [Promote a Previous Version of a File](#promote-a-previous-version-of-a-file) - [Delete a Previous Version of a File](#delete-a-previous-version-of-a-file) - [Lock a File](#lock-a-file) - [Unlock a File](#unlock-a-file) - [Find File for Shared Link](#find-file-for-shared-link) - [Download File for Shared Link](#download-file-for-shared-link) - [Create a Shared Link](#create-a-shared-link) - [Get a Shared Link](#get-a-shared-link) - [Update a Shared Link](#update-a-shared-link) - [Remove a Shared Link](#remove-a-shared-link) - [Add a Collaborator](#add-a-collaborator) - [Get an Embed Link](#get-an-embed-link) - [Create Metadata](#create-metadata) - [Set Metadata](#set-metadata) - [Get Metadata](#get-metadata) - [Update Metadata](#update-metadata) - [Delete Metadata](#delete-metadata) - [Get All Metadata on File](#get-all-metadata-on-file) - [Set Classification on File](#set-classification-on-file) - [Get Classification on File](#get-classification-on-file) - [Remove Classification on File](#remove-classification-on-file) - [Get File Representations](#get-file-representations) - [Get Representation Content](#get-representation-content) ## Get a File's Information Calling [`getInfo()`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFile.html#getInfo-java.lang.String...-) on a file returns a snapshot of the file's info. ``` BoxFile file = new BoxFile(api, "id"); BoxFile.Info info = file.getInfo(); ``` Requesting information for only the fields you need with [`getInfo(String... fields)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFile.html#getInfo-java.lang.String...-) can improve performance and reduce the size of the network request. ``` BoxFile file = new BoxFile(api, "id"); // Only get information about a few specific fields. BoxFile.Info info = file.getInfo("size", "owned_by"); ``` ## Update a File's Information Updating a file's information is done by creating a new [`BoxFile.Info`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFile.Info.html) object or updating an existing one, and then calling [`updateInfo(BoxFile.Info fieldsToUpdate)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFile.html#updateInfo-com.box.sdk.BoxFile.Info-). ``` BoxFile file = new BoxFile(api, "id"); BoxFile.Info info = file.new Info(); info.setName("New Name"); file.updateInfo(info); ``` ## Download a File A file can be downloaded by calling [`download(OutputStream stream)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFile.html#download-java.io.OutputStream-) and providing an `OutputStream` where the file's contents will be written. ``` BoxFile file = new BoxFile(api, "id"); BoxFile.Info info = file.getInfo(); FileOutputStream stream = new FileOutputStream(info.getName()); file.download(stream); stream.close(); ``` Download progress can be tracked by providing a [`ProgressListener`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/ProgressListener.html) to [`download(OutputStream stream, ProgressListener progress)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFile.html#download-java.io.OutputStream-com.box.sdk.ProgressListener-). The `ProgressListener` will then receive progress updates as the download completes. ``` BoxFile file = new BoxFile(api, "id"); BoxFile.Info info = file.getInfo(); FileOutputStream stream = new FileOutputStream(info.getName()); // Provide a ProgressListener to monitor the progress of the download. file.download(stream, new ProgressListener() { public void onProgressChanged(long numBytes, long totalBytes) { double percentComplete = numBytes / totalBytes; } }); stream.close(); ``` ## Upload a File Files are uploaded to a folder by calling the [`uploadFile(InputStream fileContents, String fileName)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFolder.html#uploadFile-java.io.InputStream-java.lang.String-) method on the [`BoxFolder`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFolder.html) you want to upload the file into. ``` BoxFolder rootFolder = BoxFolder.getRootFolder(api); FileInputStream stream = new FileInputStream("My File.txt"); BoxFile.Info newFileInfo = rootFolder.uploadFile(stream, "My File.txt"); stream.close(); ``` Note that using `FileInputStream` allows you to read the content of the file only once. If the first upload attempt fails, the stream will become exhausted, and request retry with no content might be performed. To retry an upload, you would have to create a new `FileInputStream` and call `uploadFile()` method again. If you want the SDK to automatically retry the upload in case of any error, you need to provide an `InputStream` class that supports the `reset()` operation. For example, you can read all bytes from your file into a `ByteArrayInputStream` and then use it for the upload method. Be aware that this approach will load the whole file into memory, so it is not recommended for large files, as it can exhaust easily your memory. ``` BoxFolder rootFolder = BoxFolder.getRootFolder(api); InputStream stream = new ByteArrayInputStream(Files.readAllBytes(new File(path).toPath())); BoxFile.Info newFileInfo = rootFolder.uploadFile(stream, "My File.txt"); stream.close(); ``` Upload progress can be tracked by providing the size of the file and a [`ProgressListener`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/ProgressListener.html) to [`uploadFile(InputStream fileContents, String fileName, long fileSize, ProgressListener progress)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFolder.html#uploadFile-java.io.InputStream-java.lang.String-long-com.box.sdk.ProgressListener-). The `ProgressListener` will then receive progress updates as the upload completes. ``` BoxFolder rootFolder = BoxFolder.getRootFolder(api); FileInputStream stream = new FileInputStream("My File.txt"); BoxFile.Info newFileInfo = rootFolder.uploadFile(stream, "My File.txt", 1024, new ProgressListener() { public void onProgressChanged(long numBytes, long totalBytes) { double percentComplete = numBytes / totalBytes; } }); stream.close(); ``` We also support the ability to attach a description of the file upon upload by calling the [`uploadFile(InputStream fileContents, String fileName, String fileDescription)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFolder.html#uploadFile-java.io.InputStream-java.lang.String-java.lang.String-) method. ``` BoxFolder rootFolder = BoxFolder.getRootFolder(api); FileInputStream stream = new FileInputStream("My File.txt"); BoxFile.Info newFileInfo = rootFolder.uploadFile(stream, "My File.txt", "File Description"); stream.close(); ``` ## Upload Preflight Check You may want to check if a file can be successfully uploaded before beginning the file transfer, in order to the time and bandwidth of sending the file over the network if the upload would not have succeeded. Calling the [`BoxFolder#canUpload(String fileName, long fileSize)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFolder.html#canUpload-java.lang.String-long-) method on the folder you want to upload a new file into will verify that there is no name conflict and that the account has enough storage space for the file. ``` String fileName = "My Doc.pdf"; BoxFolder rootFolder = BoxFolder.getRootFolder(api); try { folder.canUpload(fileName, 98734576); // If the file upload would not have succeeded, it will not be attempted folder.uploadFile(fileContents, fileName); } catch (BoxAPIException ex) ( ) ``` ## Upload a Large File in Chunks A large file can be uploaded with the [`uploadLargeFile(InputStream fileContents, String fileName, long fileSize)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFolder.html#uploadLargeFile-java.io.InputStream-java.lang.String-long-) method on the folder to upload the new file into. This will upload the file in parts with integrity checks on each part, to ensure that network errors mid-upload do not fail the entire operation. ``` File myFile = new File("My Large_File.txt"); FileInputStream stream = new FileInputStream(myFile); BoxFolder rootFolder = BoxFolder.getRootFolder(api); BoxFile.Info fileInfo = rootFolder.uploadLargeFile(inputStream, "My_Large_File.txt", myFile.length()); ``` ## Upload a Large File in Chunks Including Attributes A large file can be uploaded, including attributes, with the [`uploadLargeFile(InputStream fileContents, String fileName, long fileSize, Map<String, String> fileAttributes)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFolder.html#uploadLargeFile-java.io.InputStream-java.lang.String-long-java.util.Map-) method on the folder to upload the new file into. This will upload the file in parts with integrity checks on each part, to ensure that network errors mid-upload do not fail the entire operation. ``` File myFile = new File("My Large_File.txt"); FileInputStream stream = new FileInputStream(myFile); Map<String, String> fileAttributes = new HashMap<String, String>(); fileAttributes.put("content_modified_at", "2017-04-08T00:58:08Z"); BoxFolder rootFolder = BoxFolder.getRootFolder(api); BoxFile.Info fileInfo = rootFolder.uploadLargeFile(inputStream, "My_Large_File.txt", myFile.length(), fileAttributes); ``` ## Upload a Large File Version in Chunks To upload a new file version for a large file, call the [`uploadLargeFile(InputStream fileContents, long fileSize)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFile.html#uploadLargeFile-java.io.InputStream-long-) method on the file to be updated. This will upload the new version of the file in parts with integrity checks on each part, to ensure that network errors mid-upload do not fail the entire operation. ``` File myFile = new File("My Large_File.txt"); FileInputStream stream = new FileInputStream(myFile); String fileID = "12345"; BoxFile file = new BoxFile(api, fileID); BoxFile.Info fileInfo = file.uploadLargeFile(inputStream, myFile.length()); ``` ## Upload a Large File Version in Chunks Including Attributes To upload a new file version for a large file, including attributes, call the [`uploadLargeFile(InputStream fileContents, long fileSize, Map<String, String> fileAttributes)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFile.html#uploadLargeFile-java.io.InputStream-long-java.util.Map-) method on the file to be updated. This will upload the new version of the file in parts with integrity checks on each part, to ensure that network errors mid-upload do not fail the entire operation. ``` File myFile = new File("My Large_File.txt"); FileInputStream stream = new FileInputStream(myFile); Map<String, String> fileAttributes = new HashMap<String, String>(); fileAttributes.put("content_modified_at", "2017-04-08T00:58:08Z"); String fileID = "12345"; BoxFile file = new BoxFile(api, fileID); BoxFile.Info fileInfo = file.uploadLargeFile(inputStream, myFile.length(), fileAttributes); ``` ## Upload a Large File Or File Version Manually To start the process of uploading a large file or file version, first create a new upload session with [`BoxFolder#createUploadSession(String fileName, String fileSize)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFolder.html#createUploadSession-java.lang.String-long-) for a new file, or [`BoxFile#createUploadSession(long fileSize)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFile.html#createUploadSession-long-) for a new file version. Once the upload session is created, all other steps are identical for both cases. ``` BoxFileUploadSession.Info sessionInfo; if (/* uploading a new file */) { // Create the upload session for a new file BoxFolder rootFolder = BoxFolder.getRootFolder(api); sessionInfo = rootFolder.createUploadSession("New Large File.pdf", fileSize); } else if (/* uploading a new version of an exiting file */) { // Create the uplaod session for a new version of an existing file String fileID = "93465"; BoxFile file = new BoxFile(api, fileID); sessionInfo = file.createUploadSession(fileSize); } //Get the session resource from the session info BoxFileUploadSession session = sessionInfo.getResource(); //Create the Message Digest for the whole file MessageDigest digest = null; try { digest = MessageDigest.getInstance("SHA1"); } catch (NoSuchAlgorithmException ae) { throw new BoxAPIException("Digest algorithm not found", ae); } ``` Both of these methods will return a Once the upload session is created, the large file can be uploaded in chunks with the [`uploadPart(InputStream stream, long offset, int partSize, long totalSizeOfFile)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFileUploadSession.html#uploadPart-java.io.InputStream-long-int-long-) method of the session instance. If there is a failure in uploading any of the parts, the failed part can be uploaded again without affecting the other parts. ``` //Reading a large file FileInputStream fis = new FileInputStream("My_Large_File.txt"); //Create the digest input stream to calculate the digest for the whole file. DigestInputStream dis = new DigestInputStream(fis, digest); List<BoxFileUploadSessionPart> parts = new ArrayList<BoxFileUploadSessionPart>(); //Get the part size. Each uploaded part should match the part size returned as part of the upload session. //The last part of the file can be less than part size if the remaining bytes of the last part is less than //the given part size long partSize = sessionInfo.getPartSize(); //Start byte of the part long offset = 0; //Overall of bytes processed so far long processed = 0; while (processed < fileSize) { long diff = fileSize - processed; //The size last part of the file can be less than the part size. if (diff < partSize) { partSize = diff; } //Upload a part. It can be uploaded asynchorously BoxFileUploadSessionPart part = session.uploadPart(dis, offset, (int)partSize, fileSize); parts.add(part); //Increase the offset and proceesed bytes to calculate the Content-Range header. processed += partSize; offset += partSize; } ``` At any point in time, the list of parts that have been uploaded successfully can be retrieved with the [`listParts(int offset, int limit)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFileUploadSession.html#listParts-int-int-) method of the session instance. ``` //The following snippet retrives first 1000 parts that are uploaded. BoxFileUploadSessionPartList partList = session.listParts(0, 1000); List<BoxFileUploadSessionPart> parts = partList.getEntries(); ``` Once all the parts are uploaded successfully, the upload session can be committed with the [`commit(String digest, List<BoxFileUploadSessionPart> parts, Map<String, String> attributes, String ifMatch, String ifNoneMatch)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFileUploadSession.html#commit-java.lang.String-java.util.List-java.util.Map-java.lang.String-java.lang.String-) method. ``` //Creates the file hash byte[] digestBytes = digest.digest(); //Base64 encoding of the hash String digestStr = Base64.encode(digestBytes); //Commit the upload session. If there is a failure, abort the commit. BoxFile.Info fileInfo = session.commit(digestStr, parts, null, null, null); ``` The upload session can be aborted at any time with the [`abort()`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFileUploadSession.html#abort--) method of the session instance. This will cancel the upload and any parts that were already uploaded will be lost. ``` session.abort(); ``` The upload session status can be retrieved at any time with the [`getStatus()`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFileUploadSession.html#getStatus--) method. This call will update the parts processed and other information in the session info instance. ``` BoxFileUploadSession.Info updatedSessionInfo = session.getStatus(); ``` ## Move a File To move a file from one folder into another, call [`move(BoxFolder destination)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFile.html#move-com.box.sdk.BoxFolder-) on the file to be moved with the destination folder. ``` String fileID = "1234"; String destinationFolderID = "5678"; BoxFile file = new BoxFile(api, fileID); BoxFolder destinationFolder = new BoxFolder(destinationFolderID); file.move(destinationFolder) ``` To avoid name conflicts in the destination folder, you can optionally provide a new name for the file to [`move(BoxFolder destination, String newName)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFile.html#move-com.box.sdk.BoxFolder-java.lang.String-). The file will be placed into the destination folder with the new name. ``` String fileID = "1234"; String destinationFolderID = "5678"; BoxFile file = new BoxFile(api, fileID); BoxFolder destinationFolder = new BoxFolder(destinationFolderID); file.move(destinationFolder, "Vacation Photo (1).jpg"); ``` ## Copy a File A file can be copied to a new folder and optionally be renamed with the [`copy(BoxFolder destination)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFile.html#copy-com.box.sdk.BoxFolder-) and [`copy(BoxFolder destination, String newName)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFile.html#copy-com.box.sdk.BoxFolder-java.lang.String-) methods. ``` // Copy a file into the user's root folder BoxFolder rootFolder = BoxFolder.getRootFolder(api); BoxFile file = new BoxFile(api, "id"); BoxFile.Info copiedFileInfo = file.copy(rootFolder, "New Name"); ``` ## Delete a File Calling the [`delete()`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFile.html#delete--) method will move the file to the user's trash. ``` BoxFile file = new BoxFile(api, "id"); file.delete(); ``` ## Get Previous Versions of a File For users with premium accounts, versions of a file can be retrieved with the [`getVersions()`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFile.html#getVersions--) method. By default, it will return up to 1000 file versions with all default fields set. ``` BoxFile file = new BoxFile(api, "id"); Collection<BoxFileVersion> versions = file.getVersions(); for (BoxFileVersion version : versions) { System.out.format("SHA1 of \"%s\": %s\n", file.getInfo().getName(), version.getSha1()); } ``` File versions can be retrieved with specified starting position with the [`getVersionsRange(long offset, long limit)`][get-versions-range] method. You can use the `limit` and `offset` parameters to page through the all available file versions. ``` BoxFile file = new BoxFile(api, "id"); Collection<BoxFileVersion> versions = file.getVersionsRange(1000, 2000); for (BoxFileVersion version : versions) { System.out.format("SHA1 of \"%s\": %s\n", file.getInfo().getName(), version.getSha1()); } ``` You can specify selected fields to be returned while getting versions information. Assume we want to get version SHA1 and version number: ``` BoxFile file = new BoxFile(api, "id"); Collection<BoxFileVersion> versions = file.getVersions("sha1", "version_number"); for (BoxFileVersion version : versions) { System.out.format("SHA1 of \"%d\": %s\n", version.getVersionNumber(), version.getSha1()); } ``` You can find a list of available fields at [`BoxFile.ALL_VERSION_FIELDS`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFile.html#ALL_VERSION_FIELDS--). ## Upload a New Version of a File New versions of a file can be uploaded with the [`uploadNewVersion(InputStream fileContents)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFile.html#uploadNewVersion-java.io.InputStream-) method. ``` BoxFile file = new BoxFile(api, "id"); FileInputStream stream = new FileInputStream("My File.txt"); file.uploadNewVersion(stream); ``` ## Download a Previous Version of a File For users with premium accounts, previous versions of a file can be downloaded by calling [`download(OutputStream output)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFileVersion.html#download-java.io.OutputStream-). ``` BoxFile file = new BoxFile(api, "id"); Collection<BoxFileVersion> versions = file.getVersions(); BoxFileVersion firstVersion = versions.iterator().next(); FileOutputStream stream = new FileOutputStream(firstVersion.getName()); firstVersion.download(stream); stream.close(); ``` ## Promote a Previous Version of a File A previous version of a file can be promoted with the [`promote()`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFileVersion.html#promote--) method to become the current version of the file. ``` BoxFile file = new BoxFile(api, "id"); Collection<BoxFileVersion> versions = file.getVersions(); BoxFileVersion firstVersion = versions.iterator().next(); firstVersion.promote(); ``` ## Delete a Previous Version of a File A version of a file can be deleted and moved to the trash by calling [`delete()`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFileVersion.html#delete--). ``` BoxFile file = new BoxFile(api, "id"); Collection<BoxFileVersion> versions = file.getVersions(); BoxFileVersion firstVersion = versions.iterator().next(); firstVersion.delete(); ``` ## Lock a File A file can be locked indefinitely by calling [`lock()`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFile.html#lock-java.util.Date-) on the file to be locked. A locked file cannot be modified by any other user until it is unlocked. This is useful if you want to "check out" a file while you're working on it, to ensure that other collaborators do not make changes while your changes are in progress. ``` BoxFile file = new BoxFile(api, "id"); file.lock(); ``` When locking a file, you can optionally prevent other users from downloading the file in addition to prevent changes by calling [`lock(boolean preventDownload)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFile.html#lock-boolean-) with `true`. ``` // Lock the file and prevent downloading BoxFile file = new BoxFile(api, "id"); file.lock(true); ``` You can also set a date when the lock will automatically be released by calling [`lock(Date expirationDate)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFile.html#lock-java.util.Date-) with the date on which the lock should expire. This is recommended to prevent a file from accidentally being locked longer than intended. ``` final long ONE_WEEK_MILLIS = 1000 * 60 * 60 * 24 * 7; long expirationTimestamp = System.currentTimeMillis() + ONE_WEEK_MILLIS; Date expirationTime = new Date(expirationTimestamp); BoxFile file = new BoxFile(api, "id"); file.lock(expirationTime); ``` Both options can be passed together to [`lock(boolean preventDownload, Date expireTime)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFile.html#lock-java.util.Date-boolean-). ## Unlock a File A file can be unlocked by calling [`unlock()`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFile.html#unlock--). ``` BoxFile file = new BoxFile(api, "id"); file.unlock(); ``` ## Find File for Shared Link To get the file information for a shared link, you can call [`BoxItem.getSharedItem(BoxAPIConnection api, String sharedLink)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxItem.html#getSharedItem-com.box.sdk.BoxAPIConnection-java.lang.String-) with the shared link to get information about the file behind it. ``` String sharedLink = "https://app.box.com/s/abcdefghijklmnopqrstuvwxyz123456"; BoxItem.Info itemInfo = BoxItem.getSharedItem(api, sharedLink); ``` If the shared link is password-protected, call [`BoxItem.getSharedItem(BoxAPIConnection api, String sharedLink, String password)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxItem.html#getSharedItem-com.box.sdk.BoxAPIConnection-java.lang.String-java.lang.String-) with the shared link and password. ``` String sharedLink = "https://app.box.com/s/abcdefghijklmnopqrstuvwxyz123456"; String password = "letmein"; BoxItem.Info itemInfo = BoxItem.getSharedItem(api, sharedLink, password); ``` ## Download File from Shared Link A file can be downloaded via a shared link by calling [`downloadFromSharedLink(BoxAPIConnection api, OutputStream output, String sharedLink)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFile.html#downloadFromSharedLink-com.box.sdk.BoxAPIConnection-java.io.OutputStream-java.lang.String-) and providing an `OutputStream` where the file's contents will be written and shared link of the file. If the shared link is password-protected, call [`downloadFromSharedLink(BoxAPIConnection api, OutputStream output, String sharedLink, String password)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFile.html#downloadFromSharedLink-com.box.sdk.BoxAPIConnection-java.io.OutputStream-java.lang.String-java.lang.String-) method. ``` FileOutputStream stream = new FileOutputStream("My File.txt"); String sharedLink = "https://cloud.box.com/s/12339wbq4c7y2xd3drg4j9j9wer3ptt6n"; String password = "Secret123@"; BoxFile.downloadFromSharedLink(api, stream, sharedLink, password); stream.close(); ``` Download progress can be tracked by providing a [`ProgressListener`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/ProgressListener.html) to [` downloadFromSharedLink(BoxAPIConnection api, OutputStream output, String sharedLink, String password, ProgressListener listener)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFile.html#downloadFromSharedLink-com.box.sdk.BoxAPIConnection-java.io.OutputStream-java.lang.String-java.lang.String-com.box.sdk.ProgressListener-). The `ProgressListener` will then receive progress updates as the download completes. ``` FileOutputStream stream = new FileOutputStream("My File.txt"); // Provide a ProgressListener to monitor the progress of the download. BoxFile.downloadFromSharedLink(api, stream, sharedLink, password, new ProgressListener() { public void onProgressChanged(long numBytes, long totalBytes) { double percentComplete = numBytes / totalBytes; } }); stream.close(); ``` ## Create a Shared Link A shared link for a file can be generated by calling [`createSharedLink(BoxSharedLinkRequest sharedLinkRequest)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFile.html#createSharedLink-com.box.sdk.sharedlink.BoxSharedLinkRequest-). ``` // Optionally we can calculate and set the date when shared link will automatically be disabled final long ONE_WEEK_MILLIS = 1000 * 60 * 60 * 24 * 7; long unsharedTimestamp = System.currentTimeMillis() + ONE_WEEK_MILLIS; Date unsharedDate = new Date(unsharedTimestamp); BoxFile file = new BoxFile(api, "id"); BoxSharedLinkRequest sharedLinkRequest = new BoxSharedLinkRequest() .access(OPEN) .permissions(true, true) .unsharedDate(unsharedDate); BoxSharedLink sharedLink = file.createSharedLink(sharedLinkRequest); ``` A set of shared link access level constants are available through the SDK for convenience: - `BoxSharedLink.Access.OPEN` - `BoxSharedLink.Access.COLLABORATORS` - `BoxSharedLink.Access.COMPANY` - `BoxSharedLink.Access.DEFAULT` ## Get a Shared Link Retrieve the shared link for a file by calling [`getSharedLink()`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxItem.Info.html#getSharedLink--). ``` BoxFile file = new BoxFile(api, "id"); BoxFile.Info info = file.getInfo(); BoxSharedLink link = info.getSharedLink(); String url = link.getUrl(); ``` ## Update a Shared Link A shared link for a file can be updated by calling the same method as used when creating a shared link, [`createSharedLink(BoxSharedLinkRequest sharedLinkRequest)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFile.html#createSharedLink-com.box.sdk.sharedlink.BoxSharedLinkRequest-). ``` BoxFile file = new BoxFile(api, "id"); BoxSharedLinkRequest sharedLinkRequest = new BoxSharedLinkRequest() .access(OPEN) .permissions(true, true); BoxSharedLink sharedLink = file.createSharedLink(sharedLinkRequest); ``` ## Remove a Shared Link A shared link for a file can be removed by calling [`removeSharedLink()`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFile.html#removeSharedLink--). ``` BoxFile file = new BoxFile(api, "12345"); BoxFile.Info info = file.getInfo(); info.removeSharedLink(); file.updateInfo(info); ``` ## Add a Collaborator You can invite another person to collaborate on a file by email with [`collaborate(String emailAddress, BoxCollaboration.Role role, Boolean notify, Boolean canViewPath, Date expiresAt, Boolean isAccessOnly)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFile.html#collaborate-java.lang.String-com.box.sdk.BoxCollaboration.Role-java.lang.Boolean-java.lang.Boolean-java.lang.String-java.util.Date-java.lang.Boolean-). The `notify` parameter will determine if the user or group will receive an email notification when being added as a collaborator. This option is only available to enterprise administrators. The `canViewPath` parameter allows the invitee to see the entire list of ancestor folders of the associated file. The user will not gain privileges in any ancestor folder, but will be able to see the whole path to that file in the owner's account. The `expiresAt` parameter allows the owner to set a date-time in the future when the collaboration should expire. The `isAccessOnly` parameter allows the owner to set the collaboration to be access only collaboration. The `notify`, `canViewPath`, `expiresAt` and `isAccessOnly` parameters can be left as `null`. ``` BoxFile file = new BoxFile(api, "id"); BoxCollaboration.Info collabInfo = file.collaborate("testuser@example.com", BoxCollaboration.Role.EDITOR, true, true); ``` Alternatively, if you know the user's ID, you can invite them directly without needing to know their email address with the [`collaborate(BoxCollaborator user, BoxCollaboration.Role role, Boolean notify, Boolean canViewPath, Date expiresAt, Boolean isAccessOnly)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFile.html#collaborate-com.box.sdk.BoxCollaborator-com.box.sdk.BoxCollaboration.Role-java.lang.Boolean-java.lang.Boolean-java.lang.String-java.util.Date-java.lang.Boolean-) ``` BoxUser collaborator = new BoxUser(api, "user-id"); BoxFile file = new BoxFile(api, "file-id"); BoxCollaboration.Info collabInfo = file.collaborate(collaborator, BoxCollaboration.Role.EDITOR, true, true); ``` ## Get an Embed Link A file embed link can be generated by calling [`getPreviewLink()`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFile.html#getPreviewLink--). ``` BoxFile file = new BoxFile(api, "id"); URL embedLink = file.getPreviewLink(); ``` ## Create Metadata Metadata can be created on a file by calling [`createMetadata(Metadata metadata)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFile.html#createMetadata-com.box.sdk.Metadata-), [`createMetadata(String typeName, Metadata metadata)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFile.html#createMetadata-java.lang.String-com.box.sdk.Metadata-), or [`createMetadata(String typeName, String scope, Metadata metadata)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFile.html#createMetadata-java.lang.String-java.lang.String-com.box.sdk.Metadata-). ``` // Add property "foo" with value "bar" to the default metadata properties BoxFile file = new BoxFile(api, "id"); file.createMetadata(new Metadata().add("/foo", "bar")); ``` Note: This method will only succeed if the provided metadata template is not currently applied to the file, otherwise it will fail with a Conflict error. To get to know how to edit existing metadata please go to [set metadata](#set-metadata) and [update metadata](#update-metadata) sections. ## Set Metadata To set metadata on a file, call [`setMetadata(String templateName, String scope, Metadata metadata)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFile.html#setMetadata-java.lang.String-java.lang.String-com.box.sdk.Metadata-). This method will try to create provided metadata on a file. However, if metadata has already been applied to this file, it will overwrite values of metadata keys specified in the `metadata` parameter. The metadata keys not specified in the `metadata` parameter will remain unchanged. ``` BoxFile file = new BoxFile(api, "id"); file.setMetadata("test_template", "enterprise", new Metadata().add("/foo", "bar")); ``` Note: If you want to set new metadata on a file including hard reset of the current metadata (also removing keys not specified in the `metadata` param): first delete metadata as specified in [delete metadata](#delete-metadata) section and then set new metadata again. ## Get Metadata Retrieve a file's Metadata by calling [`getMetadata()`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFile.html#getMetadata--), [`getMetadata(String typeName)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFile.html#getMetadata-java.lang.String-), or [`getMetadata(String typeName, String scope)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFile.html#getMetadata-java.lang.String-java.lang.String-). These methods return a [`Metadata`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/Metadata.html) object, which allows access to metadata values. ``` // Get the default free-form metadata properties BoxFile file = new BoxFile(api, "id"); Metadata metadata = file.getMetadata(); // Unknown type metadata field, you can test for type or try to get as any type JsonValue unknownValue = metadata.getValue("/someField"); // String or Enum metadata fields String stringValue = metadata.getString("/author"); // Float metadata fields can be interpreted as any numeric type float floatValue = metadata.getFloat("/price"); // Date metadata fields Date dateValue = metadata.getDate("/deadline"); // Multiselect metadata fields List<String> multiSelectValues = metadata.getMultiSelect("/categories"); ``` ## Update Metadata Update a file's Metadata by calling [`updateMetadata(Metadata properties)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFile.html#updateMetadata-com.box.sdk.Metadata-). Note: This method will only succeed if the provided metadata template has already been applied to the file. If the file does not have existing metadata, this method will fail with a Not Found error. This is useful in cases where you know the file will already have metadata applied, since it will save an API call compared to `setMetadata()`. ``` BoxFile file = new BoxFile(api, "id"); file.updateMetadata(new Metadata("templateScope", "templateKey").add("/foo", "bar")); ``` Also, it is possible to add multi-select fields for your file metadata by calling [`updateMetadata(Metadata properties)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFile.html#updateMetadata-com.box.sdk.Metadata-) with a list of values. ``` BoxFile file = new BoxFile(api, "id"); List<String> valueList = new ArrayList<String>(); valueList.add("bar"); valueList.add("qux"); file.updateMetadata(new Metadata("templateScope", "templateKey").add("/foo", valueList)); ``` If you wanted to replace all selected fields for a specified key you can use the [`replace(String path, List<String> values)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/Metadata.html#replace-java.lang.String-java.util.List-). ``` BoxFile file = new BoxFile(api, "id"); List<String> valueList = new ArrayList<String>(); valueList.add("bar"); valueList.add("qux"); file.updateMetadata(new Metadata("templateScope", "templateKey").replace("/foo", valueList)); ``` If you wanted to remove a metadata value for a specified key you can use the [`remove(String path)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/Metadata.html#remove-java.lang.String-). ``` BoxFile file = new BoxFile(api, "id"); file.updateMetadata(new Metadata("templateScope", "templateKey").remove("/foo")); ``` ## Delete Metadata A file's Metadata can be deleted by calling [`deleteMetadata()`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFile.html#deleteMetadata--), [`deleteMetadata(String typeName)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFile.html#deleteMetadata-java.lang.String-), or [`deleteMetadata(String typeName, String scope)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFile.html#deleteMetadata-java.lang.String-java.lang.String-). ``` BoxFile file = new BoxFile(api, "id"); file.deleteMetadata("myMetadataTemplate"); ``` ## Get All Metadata on File Calling the [`getAllMetadata()`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFile.html#getAllMetadata-java.lang.String...-) method on a file will return an iterable that will page through all of the metadata associated with the file. ``` BoxFile file = new BoxFile(api, "id"); Iterable<Metadata> metadataList = file.getAllMetadata(); for (Metadata metadata : metadataList) { // Do something with the metadata. } ``` ## Set Classification on File Calling the [`setClassification(String classificationType)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFile.html#setClassification-java.lang.String...-) method on a file will add a classification template on the file. This method will return the classification type applied on the file. The classification types include `Public`, `Internal`, and `Confidential`. `Public` being the most available permission, `Internal` which restricts the specified file to company and collaborators only, and finally, `Confidential`, which is for collaborators only. ``` BoxFile file = new BoxFile(api, "id"); String classificationType = file.setClassification("Public"); ``` It is important to note that this call will attempt to create a classification on the file first, if one already exists then it will do the update. If you already know that a classification exists on the file and would like to save an API call, we encourage you to use the [`updateClassification(String classificationType)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFile.html#updateClassification-java.lang.String...-) method. ``` BoxFile file = new BoxFile(api, "id"); String classificationType = file.updateClassification("Public"); ``` ## Get Classification on File To retrieve the classification assigned on the file, use the [`getClassification()`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFile.html#getClassification-java.lang.String...-) method. This will return the classification type on the file. ``` BoxFile file = new BoxFile(api, "id"); String classificationType = file.getClassification(); ``` ## Remove Classification on File To remove classification from the file, use the [`deleteClassification()`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFile.html#deleteClassification--) method. ``` BoxFile file = new BoxFile(api, "id"); file.deleteClassification(); ``` ## Get File Representations To get the preview representations of a file, call the [`getInfoWithRepresentations(String representationHints, String... fields)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFile.html#getInfoWithRepresentations-java.lang.String-java.lang.String...-) method with the [representation hints](https://developer.box.com/v2.0/reference/#section-x-rep-hints-header) to fetch, along with any other fields on the file object to fetch simultaneously. This method returns a [`BoxFile.Info`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFile.Info.html) object that contains the representations as a list of [`Representation`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/Representation.html) objects. Note that this method only provides information about a set of available representations; your application will need to handle checking the status of the representations and downlaoding them via the provided content URL template. ``` BoxFile file = new BoxFile(api, "1234"); // Get the PDF representation and file name String repHints = "[pdf]"; BoxFile.Info fileInfo = file.getInfoWithRepresentations(repHints, "name"); List<Representation> representations = fileInfo.getRepresentations(); String name = fileInfo.getName(); ``` ## Get Representation Content To write the contents of a single file representation to an `OutputStream`, call the [`getRepresentationContent(String representationHint, OutputStream output)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFile.html#getRepresentationContent-java.lang.String-java.lang.String-java.io.OutputStream-) method with an [X-Rep-Hints value](https://developer.box.com/v2.0/reference/#section-x-rep-hints-header) specifying the representation you want. **Note:** This method only supports getting the contents of a single representation; if your X-Rep-Hints value specifies multiple representations, an arbitrary one of them will be fetched. ``` // Read the PDF representation of file 12345 into memory ByteArrayOutputStream output = new ByteArrayOutputStream(); BoxFile file = new BoxFile(api, "12345"); file.getRepresentationContent("[pdf]", output); ``` For representations with multiple files, e.g. multi-page images, you will need to pass an `assetPath` parameter to specify which file you want to fetch. ``` // If file 12345 is a document, its PNG representation will consist of one image per page of the document // Get the image of the first page of the document and write it to a file FileOutputStream output = new FileOutputStream("/path/to/file.png"); BoxFile file = new BoxFile(api, "12345"); file.getRepresentationContent("[png?dimensions=1024x1024]", "1.png", output); ``` Generating a representation for the selected file is an asynchronous operation and may take some time. Therefore, by default, the `getRepresentationContent` method periodically checks the status of the generated file and downloads it when it is ready. With the `maxRetries` parameter in [`getRepresentationContent(String representationHint, String assetPath, OutputStream output, int maxRetries)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFile.html#getRepresentationContent-java.lang.String-java.lang.String-java.io.OutputStream-int-), you can define the number of status checks for the generated file, which will be performed at intervals of 100 ms. If this number is exceeded, a `BoxApiException` will be thrown. ``` FileOutputStream output = new FileOutputStream("/path/to/file.png"); BoxFile file = new BoxFile(api, "12345"); file.getRepresentationContent("[png?dimensions=1024x1024]", "1.png", output, 10); ``` --- ### Files **Type:** page | **Section:** Additional Resources Files File objects represent individual files in Box. They can be used to download a file's contents, upload new versions, and perform other… # Files File objects represent individual files in Box. They can be used to download a file's contents, upload new versions, and perform other common file operations (move, copy, delete, etc.). - [Get a File's Information](#get-a-files-information) - [Update a File's Information](#update-a-files-information) - [Download a File](#download-a-file) - [Get a File's Download URL](#get-a-files-download-url) - [Upload a File](#upload-a-file) - [Copy a File](#copy-a-file) - [Delete a File](#delete-a-file) - [Get Previous File Versions](#get-previous-file-versions) - [Upload a New Version of a File](#upload-a-new-version-of-a-file) - [Upload a Large File Version in Chunks](#upload-a-large-file-version-in-chunks) - [Download a Previous Version of a File](#download-a-previous-version-of-a-file) - [Promote Version](#promote-version) - [Delete a Previous File Version](#delete-a-previous-file-version) - [Lock a File](#lock-a-file) - [Unlock a File](#unlock-a-file) - [Create or update a Shared Link](#create-or-update-a-shared-link) - [Get Embed Link](#get-embed-link) - [Get Representation Info](#get-representation-info) - [Get Thumbnail](#get-thumbnail) - [Download a Zip File](#download-a-zip-file) ## Get a File's Information To get information about a specific file, call `FilesManager.GetInformationAsync(string id, IEnumerable<string> fields = null)` with the ID of the file. ``` BoxFile file = await client.FilesManager.GetInformationAsync(id: "11111"); ``` ## Update a File's Information Updating a file's information is done by calling `FilesManager.UpdateInformationAsync(BoxFileRequest fileRequest, string etag = null, IEnumerable<string> fields = null)` with the fields of the file object to update. ``` // Rename file 11111 var requestParams = new BoxFileRequest() { Id = "11111", Name = "New name.pdf" }; BoxFile updatedFile = await client.FilesManager.UpdateInformationAsync(requestParams); ``` ## Download a File A file can be downloaded by calling `FilesManager.DownloadStreamAsync(string id, string versionId = null, TimeSpan? timeout = null, int? startOffsetInBytes = null, int? endOffsetInBytes = null)`, which provides a `Stream` that will yield the file's contents. ``` Stream fileContents = await client.FilesManager.DownloadStreamAsync(id: "11111"); ``` ## Get a File's Download URL The download URL of a file an be retrieved by calling `FilesManager.GetDownloadUriAsync(string id, string versionId = null)` with the ID of the file. ``` Uri downloadUri = await client.FilesManager.GetDownloadUriAsync(id: "11111"); ``` ## Upload a File The simplest way to upload a file to a folder is by calling `FilesManager.UploadAsync(BoxFileRequest fileRequest, Stream stream, IEnumerable<string> fields = null, TimeSpan? timeout = null, byte[] contentMD5 = null, bool setStreamPositionToZero = true, Uri uploadUri = null)` with the upload parameters and a stream of the file contents to upload. ``` using (FileStream fileStream = new FileStream(filePath, FileMode.Open)) { BoxFileRequest requestParams = new BoxFileRequest() { Name = uploadFileName, Parent = new BoxRequestEntity() { Id = "0" } }; BoxFile file = await client.FilesManager.UploadAsync(requestParams, fileStream); } ``` ## Copy a File A file can be copied to a new folder with the `FilesManager.CopyAsync(BoxFileRequest fileRequest, IEnumerable<string> fields = null)` method. ``` string fileId = "11111"; string destinationFolderId = "22222"; var requestParams = new BoxFileRequest() { Id = fileId, Parent = new BoxRequestEntity() { Id = destinationFolderId } }; BoxFile fileCopy = await client.FilesManager.CopyAsync(requestParams); ``` ## Delete a File Calling the `FilesManager.DeleteAsync(string id, string etag = null)` method will move the file to the user's trash. ``` await client.FilesManager.DeleteAsync(id: "11111"); ``` ## Get Previous File Versions Retrieve a list of previous versions of a file by calling `FilesManager.ViewVersionsAsync(string id, IEnumerable<string> fields = null)` with the ID of the file. ``` BoxCollection<BoxFileVersion> previousVersions = await client.FilesManager .ViewVersionsAsync(id: "11111"); ``` ## Upload a New Version of a File A new version of a file can be uploaded by calling `FilesManager.UploadNewVersionAsync(string fileName, string fileId, Stream stream, string etag = null, IEnumerable<string> fields = null, TimeSpan? timeout = null, byte[] contentMD5 = null, bool setStreamPositionToZero = true, Uri uploadUri = null)` with the name and ID of the file, and a `Stream` of the new contents of the file. ``` using (FileStream fileStream = new FileStream(filePath, FileMode.Open)) { BoxFile file = await client.FilesManager .UploadNewVersionAsync("File v2.pdf", "11111", fileStream); } ``` ## Upload a Large File Version in Chunks A new version of a large file (over 50MB) can be uploaded by calling `FilesManager.UploadUsingSessionAsync(Stream stream, string fileName, string folderId, TimeSpan? timeout = null, IProgress<BoxProgress> progress = null)` with the `Stream` of the new contents of the file, name, parent folder ID of the file, timeout (default none) and progress listener (default null). ``` var progress = new Progress<BoxProgress>(val => { Console.WriteLine("Uploaded {0}%", val.progress); }); using (FileStream fileStream = new FileStream(filePath, FileMode.Open)) { string parentFolderId = "0"; var bFile = await client.FilesManager.UploadUsingSessionAsync(fileStream, "File v2.pdf", parentFolderId, null, progress); Console.WriteLine("{0} uploaded to folder: {1} as file: {2}", filePath, parentFolderId, bFile.Id); } ``` ## Download a Previous Version of a File For users with premium accounts, previous versions of a file can be downloaded by calling `FilesManager.DownloadStreamAsync(string id, string versionId = null, TimeSpan? timeout = null, int? startOffsetInBytes = null, int? endOffsetInBytes = null)` with the ID of the file and the optional version ID. ``` string fileId = "11111"; Stream versionContents = await client.FilesManager.DownloadStreamAsync(fileId, versionId: "22222"); ``` ## Promote Version Promote file version to the top of the stack by calling `FilesManager.PromoteVersionAsync(string id, string versionId)` with the ID of the file and the ID of the version to make the current version. This will create a new file version with the same contents as the previous version, as the current version. ``` string fileId = "11111"; BoxFileVersion current = await client.FilesManager.PromoteVersionAsync(fileId, versionId: "22222"); ``` ## Delete a Previous File Version An old version of a file can be moved to the trash by calling `FilesManager.DeleteOldVersionAsync(string id, string versionId, string etag = null)` with the ID of the file and the ID of the file version to delete. ``` string fileId = "11111"; await client.FilesManager.DeleteOldVersionAsync(fileId, versionId: "22222"); ``` ## Lock a File A file can be locked, which prevents other users from editing the file, by calling the `FilesManager.LockAsync(BoxFileLockRequest lockFileRequest, string id)` method. You may optionally prevent other users from downloading the file, as well as set an expiration time for the lock. ``` var lockParams = new BoxFileLockRequest() { Lock = new BoxFileLock() { IsDownloadPrevented = true }; }; string fileId = "11111"; BoxFileLock lock = await client.FilesManager.LockAsync(lockParams, fileId); ``` ## Unlock a File A file can be unlocked by calling `FilesManager.UnLock(string id)` with the ID of the file to unlock. ``` await client.FilesManager.UnLock(id: "11111"); ``` ## Create or update a Shared Link A shared link for a file can be created or updated by calling `FilesManager.CreateSharedLinkAsync(string id, BoxSharedLinkRequest sharedLinkRequest, IEnumerable<string> fields = null)`. ``` string fileId = "11111"; var sharedLinkParams = new BoxSharedLinkRequest() { Access = BoxSharedLinkAccessType.open, Permissions = new BoxPermissionsRequest { Download = true, Edit = true } }; BoxFile file = client.FilesManager.CreateSharedLinkAsync(fileId, sharedLinkParams); string sharedLinkUrl = file.SharedLink.Url; ``` ## Get Embed Link An embed link for a file can be generated by calling the `FilesManager.GetPreviewLinkAsync(string id)` method with the ID of the file. The embed link is an expiring URL for embedding a Box file preview into a webpage, usually via an `<iframe>` element. For more information, see the [API documentation](https://developer.box.com/en/guides/embed/box-embed/). ``` Uri embedUri = await client.FilesManager.GetPreviewLinkAsync(id: "11111"); ``` ## Get Representation Info A file's representation info can be retrieved by calling `FilesManager.GetRepresentationsAsync(BoxRepresentationRequest representationRequest)`. You will be able to fetch information regarding PDF representation, thumbnail representation, multi-page images representation, and extracted text representation. You can specify your own set of representations to get info for by manually constructing the [X-Rep-Hints value](https://developer.box.com/en/reference/get-files-id/#param-X-Rep-Hints) and passing it as `representationTypes`. ``` var requestParams = new BoxRepresentationRequest() { FileId = "11111", XRepHints = "[pdf]" }; BoxRepresentationCollection<BoxRepresentation> representations = client.FilesManager .GetRepresentationsAsync(requestParams); ``` ## Get Thumbnail A thumbnail for a file can be retrieved by calling `FilesManager.GetThumbnailAsync(string id, int? minHeight = null, int? minWidth = null, int? maxHeight = null, int? maxWidth = null, bool throttle = true, bool handleRetry = true)`. ``` Stream thumbnailContents = await client.FilesManager.GetThumbnailAsync("11111", maxWidth: 160, maxHeight: 160); ``` ## Download a Zip File Calling `FilesManager.DownloadZip(BoxZipRequest zipRequest, OutputStream output)` will let you create a new zip file with the specified name and with the specified items and download it to the stream that is passed in. The return object is a `BoxZipDownloadStatus` object that contains information about the download, including whether it was successful. The created zip file does not show up in your Box account. ``` BoxZipRequest request = new BoxZipRequest(); request.Name = "test"; request.Items = new List<BoxZipItemRequest>(); var file = new BoxZipRequestItem() { Id = "466239504569", Type = BoxZipItemType.file }; var folder = new BoxZipRequestItem() { Id = "466239504580", Type = BoxZipItemType.folder }; request.Items.Add(file); request.Items.Add(folder); Stream fs = new FileStream(@"c:\temp\MyTest.zip"); BoxZipDownloadStatus status = await _filesManager.DownloadZip(request, fs); ``` --- ### Files **Type:** page | **Section:** Additional Resources Files File objects represent individual files in Box. They can be used to download a file's contents, upload new versions, and perform other… # Files File objects represent individual files in Box. They can be used to download a file's contents, upload new versions, and perform other common file operations (move, copy, delete, etc.). - [Get File Info](#get-file-info) - [Update File](#update-file) - [Upload File](#upload-file) - [Upload New File Version](#upload-new-file-version) - [Download File](#download-file) - [Copy File](#copy-file) - [Lock File](#lock-file) - [Unlock File](#unlock-file) - [Get File Thumbnail Image](#get-file-thumbnail-image) - [Get File Embed Link](#get-file-embed-link) - [Get File Collaborations](#get-file-collaborations) - [Get File Comments](#get-file-comments) - [Get File Tasks](#get-file-tasks) - [Add File to Favorites](#add-file-to-favorites) - [Remove File from Favorites](#remove-file-from-favorites) - [Get Shared Link](#get-shared-link) - [Set Shared Link](#set-shared-link) - [Remove Shared Link](#remove-shared-link) - [List Representations](#list-representations) - [Download Zip](#download-zip) ## Get File Info To retrieve information about a file, call [`client.files.get(fileId:fields:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/FilesModule.html#/s:6BoxSDK11FilesModuleC3get6fileId6fields10completionySS_SaySSGSgys6ResultOyAA4FileCAA0A8SDKErrorCGctF) with the ID of the file. You can control which fields are returned on the resulting `File` object by passing the desired field names in the optional `fields` parameter. ``` client.files.get(fileId: "11111", fields: ["name", "created_at"]) { (result: Result<File, BoxSDKError>) in guard case let .success(file) = result else { print("Error retrieving file information") return } print("File \(file.name) was created at \(file.createdAt)") } ``` ## Update File To update a file record, call [`client.files.updateFileInfo(fileId:name:description:parentId:sharedLink:tags:collections:lock:dispositionAt:ifMatch:fields:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/FilesModule.html#/s:6BoxSDK11FilesModuleC6update6fileId4name11description06parentG010sharedLink4tags11collections4lock13dispositionAt7ifMatch6fields10completionySS_SSSgA2qA17NullableParameterOyAA06SharedL4DataVGSgSaySSGSgAySyAA04LockY0VGSg10Foundation4DateVSgAqYys6ResultOyAA4FileCAA0A8SDKErrorCGctF) with the ID of the file to update and the properties to update. ``` client.files.update(fileId: "11111", name: "New file name.docx") { (result: Result<File, BoxSDKError>) in guard case let .success(file) = result else { print("Error updating file information") return } print("File \(file.name) was updated at \(file.modifiedAt)") } ``` ## Upload File To upload a file from data in memory, call [`client.files.upload(data:name:parentId:progress:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/FilesModule.html#/s:6BoxSDK11FilesModuleC6upload4data4name8parentId8progress21performPreflightCheck10completiony10Foundation4DataV_S2SySo10NSProgressCcSbys6ResultOyAA4FileCAA0A8SDKErrorCGctF) with the data to be uploaded, the name of the file, and the ID of the folder into which the file should be uploaded. Use ID `"0"` to upload a file into the root folder, "All Files". ``` let data = "test content".data(using: .utf8) let task: BoxUploadTask = client.files.upload(data: data, name: "Test File.txt", parentId: "0") { (result: Result<File, BoxSDKError>) in guard case let .success(file) = result else { print("Error uploading file") return } print("File \(file.name) was uploaded at \(file.createdAt) into \"\(file.parent.name)\"") } // To cancel upload if someConditionIsSatisfied { task.cancel() } ``` To upload a file from a stream, use [`client.files.streamUpload(stream:fileSize:name:parentId:progress:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/FilesModule.html#/s:6BoxSDK11FilesModuleC12streamUpload0E08fileSize4name8parentId8progress21performPreflightCheck10completionySo13NSInputStreamC_SiS2SySo10NSProgressCcSbys6ResultOyAA4FileCAA0A8SDKErrorCGctF). ``` let data = "test content".data(using: .utf8) let stream = InputStream(data: data) let task: BoxUploadTask = client.files.streamUpload( stream: stream, fileSize: 12, name: "Test File.txt", parentId: "0" ) { (result: Result<File, BoxSDKError>) in guard case let .success(file) = result else { print("Error uploading file") return } print("File \(file.name) was uploaded at \(file.createdAt) into \"\(file.parent.name)\"") } // To cancel upload if someConditionIsSatisfied { task.cancel() } ``` ## Upload New File Version To upload a new version of an existing file, call [`client.files.uploadVersion(forFile:name:contentModifiedAt:data:ifMatch:progress:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/FilesModule.html#/s:6BoxSDK11FilesModuleC13uploadVersion7forFile4name17contentModifiedAt4data8progress21performPreflightCheck10completionySS_SSSgAL10Foundation4DataVySo10NSProgressCcSbys6ResultOyAA0H0CAA0A8SDKErrorCGctF) with the ID of the file and the file contents to be uploaded. ``` let data = "updated file content".data(using: .utf8) let task: BoxUploadTask = client.files.uploadVersion( forFile: "11111", name: "New file name.txt", contentModifiedAt: "2019-08-07T09:19:13-07:00", data: data ) { (result: Result<File, BoxSDKError>) in guard case let .success(file) = result else { print("Error uploading file version") return } print("New version of \(file.name) was uploaded") } // To cancel upload if someConditionIsSatisfied { task.cancel() } ``` To upload a new version of an existing file from a stream, use [`client.files.streamUploadVersion(stream:fileSize:forFile:name:contentModifiedAt:ifMatch:progress:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/FilesModule.html#/s:6BoxSDK11FilesModuleC13uploadVersion7forFile4name17contentModifiedAt4data8progress21performPreflightCheck10completionySS_SSSgAL10Foundation4DataVySo10NSProgressCcSbys6ResultOyAA0H0CAA0A8SDKErrorCGctF). ``` let data = "updated file content".data(using: .utf8) let stream = InputStream(data: data) let task: BoxUploadTask = client.files.streamUploadVersion( stream: stream, fileSize: 12, forFile: "11111", name: "New file name.txt", contentModifiedAt: "2021-03-07T09:19:13-07:00" ) { (result: Result<File, BoxSDKError>) in guard case let .success(file) = result else { print("Error uploading file version") return } print("New version of \(file.name) was uploaded") } // To cancel upload if someConditionIsSatisfied { task.cancel() } ``` ## Download File To download a file to the device, call [`client.files.download(fileId:version:destinationURL:progress:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/FilesModule.html#/s:6BoxSDK11FilesModuleC8download6fileId14destinationURL7version8progress10completionySS_10Foundation0I0VSSSgySo10NSProgressCcys6ResultOyytAA0A8SDKErrorCGctF) with the ID of the file to download and a URL to the location where the file should be downloaded to. ``` let url = FileManager.default.homeDirectoryForCurrentUser let task: BoxDownloadTask = client.files.download(fileId: "11111", destinationURL: url) { (result: Result<Void, BoxSDKError>) in guard case .success = result else { print("Error downloading file") return } print("File downloaded successfully") } // To cancel download if someConditionIsSatisfied { task.cancel() } ``` ## Copy File To make a copy of a file, call [`client.files.copy(fileId:parentId:name:version:fields:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/FilesModule.html#/s:6BoxSDK11FilesModuleC4copy6fileId06parentG04name7version6fields10completionySS_S2SSgAKSaySSGSgys6ResultOyAA4FileCAA0A8SDKErrorCGctF) with the ID of the file to copy and the ID of the folder into which the copy should be placed. In case an item with the same name already exists in the destination folder, the `name` parameter can be used to provide a new name for the copied file. You can copy a specific file version by passing the version ID in the `version` parameter. ``` client.files.copy(fileId: "11111", parentId: "0") { (result: Result<File, BoxSDKError>) in guard case let .success(copiedFile) = result else { print("Error copying file") return } print("Copied file \(copiedFile.name) into folder \(copiedFile.parent.name); copy has file ID \(copiedFile.id)") } ``` ## Lock File To lock a file and prevent others from modifying it, call [`client.files.lock(fileId:expiresAt:isDownloadPrevented:fields:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/FilesModule.html#/s:6BoxSDK11FilesModuleC4lock6fileId9expiresAt19isDownloadPrevented6fields10completionySS_10Foundation4DateVSgSbSgSaySSGSgys6ResultOyAA4FileCAA0A8SDKErrorCGctF) with the ID of the file. To also prevent others from downloading the file while it is locked, set the `isDownloadPrevented` parameter to `true`. ``` client.files.lock(fileId: "11111") { (result: Result<File, BoxSDKError>) in guard case let .success(file) = result else { print("Error locking file") return } print("File \(file.name) locked") } ``` ## Unlock File To unlock a file, call [`client.files.unlock(fileId:fields:completion:)](https://opensource.box.com/box-ios-sdk/Classes/FilesModule.html#/s:6BoxSDK11FilesModuleC6unlock6fileId6fields10completionySS_SaySSGSgys6ResultOyAA4FileCAA0A8SDKErrorCGctF) with the ID of the file. ``` client.files.unlock(fileId: "11111") { (result: Result<File, BoxSDKError>) in guard case let .success(file) = result else { print("Error unlocking file") return } print("File \(file.name) unlocked") } ``` ## Get File Thumbnail Image To retrieve the thumbnail image for a file, call [`client.files.getThumbnail(forFile:extension:minHeight:minWidth:maxHeight:maxWidth:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/FilesModule.html#/s:6BoxSDK11FilesModuleC12getThumbnail7forFile9extension9minHeight0J5Width03maxK00mL010completionySS_AA0F9ExtensionOSiSgA3Nys6ResultOy10Foundation4DataVAA0A8SDKErrorCGctF) with the ID of the file and the desired image format extension. Optionally, constraints on the image dimensions can be specified in the `minHeight`, `minWidth`, `maxHeight`, and `maxWidth` parameters. ``` client.files.getThumbnail(forFile: "11111", extension: .png) { (result: Result<Data, BoxSDKError>) in guard case let .success(thumbnailData) = result else { print("Error getting file thumbnail") return } let thumbnailImage = UIImage(data: thumbnailData) } ``` ## Get File Embed Link To retrieve a URL that can be embedded in a web page `<iframe>` to display a file preview, call [`client.files.getEmbedLink(forFile:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/FilesModule.html#/s:6BoxSDK11FilesModuleC12getEmbedLink7forFile10completionySS_ys6ResultOyAA08ExpiringfG0CAA0A8SDKErrorCGctF) with the ID of the file. ``` client.files.getEmbedLink(forFile: "11111") { (result: Result<ExpiringEmbedLink, BoxSDKError>) in guard case let .success(embedLink) = result else { print("Error generating file embed link") return } print("File embed URL is \(embedLink.url)") } ``` ## Get File Collaborations To retrieve a list of collaborations on a file, call [`client.files.listCollaborations(forFile:marker:limit:fields:)`](https://opensource.box.com/box-ios-sdk/Classes/FilesModule.html#/s:6BoxSDK11FilesModuleC18listCollaborations7forFile6marker5limit6fields10completionySS_SSSgSiSgSaySSGSgys6ResultOyAA14PagingIteratorCyAA13CollaborationCGAA0A8SDKErrorCGctF) with the ID of the file. This method returns an iterator, which is used to retrieve file collaborations. ``` let iterator = client.files.listCollaborations(forFile: "11111") iterator.next { result in switch results { case let .success(page): for collaboration in page.entries { print("Collaboration created by \(collaboration.createdBy?.name)") } case let .failure(error): print(error) } } ``` ## Get File Comments To retrieve a list of comments on the file, call [`client.files.listComments(forFile:offset:limit:fields:)`](https://opensource.box.com/box-ios-sdk/Classes/FilesModule.html#/s:6BoxSDK11FilesModuleC12listComments7forFile6offset5limit6fields10completionySS_SiSgAJSaySSGSgys6ResultOyAA14PagingIteratorCyAA7CommentCGAA0A8SDKErrorCGctF) with the ID of the file. This method returns an iterator, which is used to page through the collection of file comments. ``` let iterator = client.files.listComments(forFile: "11111") iterator.next { results in switch results { case let .success(page): for comment in page.entries { print(comment.message) } case let .failure(error): print(error) } } ``` ## Get File Tasks To retrieve a list of file tasks, call [`client.files.listTasks(forFile:fields:)`](https://opensource.box.com/box-ios-sdk/Classes/FilesModule.html#/s:6BoxSDK11FilesModuleC9listTasks7forFile6fields10completionySS_SaySSGSgys6ResultOyAA14PagingIteratorCyAA4TaskCGAA0A8SDKErrorCGctF) with the ID of the file. This method returns an iterator, which is used to retrieve file comments. ``` let iterator = client.files.listTasks(forFile: "11111") iterator.next { results in switch results { case let .success(page): for task in page.entries { print("Task messsage: \(task.message)") } case let .failure(error): print(error) } } ``` ## Add File to Favorites To add a file to the user's favorites collection, call [`client.files.addToFavorites(fileId:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/FilesModule.html#/s:6BoxSDK11FilesModuleC14addToFavorites6fileId10completionySS_ys6ResultOyAA4FileCAA0A8SDKErrorCGctF) with the ID of the file. ``` client.files.addToFavorites(fileId: "11111") { (result: Result<Void, BoxSDKError>) in guard case .success = result else { print("Error adding file to favorites") return } print("File added to favorites") } ``` ## Remove File from Favorites To remove a file from the user's favorites collection, call [`client.files.removeFromFavorites(fileId:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/FilesModule.html#/s:6BoxSDK11FilesModuleC19removeFromFavorites6fileId10completionySS_ys6ResultOyAA4FileCAA0A8SDKErrorCGctF) with the ID of the file. ``` client.files.removeFromFavorites(fileId: "11111") { (result: Result<Void, BoxSDKError>) in guard case .success = result else { print("Error removing file from favorites") return } print("File removed from favorites") } ``` ## Get Shared Link To retrieve the shared link associated with a file, call [`client.files.getSharedLink(forFile:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/FilesModule.html#/s:6BoxSDK11FilesModuleC13getSharedLink7forFile10completionySS_ys6ResultOyAA0fG0CAA0A8SDKErrorCGctF) with the ID of the file. ``` client.files.getSharedLink(forFile: "11111") { (result: Result<SharedLink, BoxSDKError>) in guard case let .success(sharedLink) = result else { print("Error retrieving file shared link") return } print("File shared link URL is \(sharedLink.url), with \(sharedLink.access) access") } ``` ## Set Shared Link To add or update the shared link for a file, call [`client.files.setSharedLink(forFile:unsharedAt:vanityName:access:password:canDownload:canEdit:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/FilesModule.html#/s:6BoxSDK11FilesModuleC13setSharedLink7forFile10unsharedAt10vanityName6access8password11canDownload0P4Edit10completionySS_AA17NullableParameterOy10Foundation4DateVGSgANySSGSgAA0fG6AccessOSgAUSbSgAYys6ResultOyAA0fG0CAA0A8SDKErrorCGctF) with the ID of the file and the shared link properties to set. ``` client.files.setSharedLink( forFile: "11111", access: .open, canDownload: true, canEdit: true ) { (result: Result<SharedLink, BoxSDKError>) in guard case let .success(sharedLink) = result else { print("Error setting file shared link") return } print("File shared link URL is \(sharedLink.url), with \(sharedLink.access) access") } ``` ## Remove Shared Link To remove a file's shared link, call [`client.files.deleteSharedLink(forFile:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/FilesModule.html#/s:6BoxSDK11FilesModuleC16deleteSharedLink7forFile10completionySS_ys6ResultOyytAA0A8SDKErrorCGctF) with the ID of the file. ``` client.files.deleteSharedLink(fileId: "11111") { (result: Result<Void, BoxSDKError>) in guard case .success = result else { print("Error removing file shared link") return } print("File shared link removed") } ``` ## List Representations To retrieve information about available preview representations for a file, call [`client.files.listRepresentations(fileId:representationHint:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/FilesModule.html#/s:6BoxSDK11FilesModuleC19listRepresentations6fileId18representationHint10completionySS_AA018FileRepresentationJ0OSgys6ResultOySayAA0lM0VGAA0A8SDKErrorCGctF) with the ID of the file. Omitting the `representationHint` parameter will provide summary information about all available representations; in order to retrieve the representation status and URL, the `representationHint` parameter must be passed to select the desired representation. ``` // Get full information about PDF representation client.files.listRepresentations( fileId: "11111", representationHint: "[pdf]" ) { (result: Result<[FileRepresentation], BoxSDKError>) in guard case let .success(representations) = result else { print("Error fetching representations") return } print("PDF representation generation status: \(representations[0]?.status?.state)") } ``` ## Download Zip Calling [`client.files.downloadZip(name:items:destinationURL:completion:)`][download-zip] will let you create a new zip file with the specified name and with the specified items and download it to the specified URL location where the file should be downloaded to. The created zip file does not show up in your Box account. ``` let name = "New zip name" var items: [ZipDownloadItem] = [] items.append(ZipDownloadItem( type: "file", id: "11111" )) let items: [ZipDownloadItem] = [] items.append(ZipDownloadItem( type: "folder", id: "22222" )) let documentsURL = FileManager.default.urls(for: .documentDirectory, in: .userDomainMask)[0] let destinationURL = documentsURL.appendingPathComponent("New zip name.zip") client.files.downloadZip(name: name, items: items, destinationURL: destinationURL) { (result: Result<ZipDownloadStatus, BoxSDKError>) in guard case .success = result else { guard case let .success(zipDownloadStatus) = result else { print("Error downloading zip") return } print("Zip download status: \(zipDownloadStatus.state)") } ``` --- ### Files **Type:** page | **Section:** Additional Resources Files File objects represent individual files in Box. They can be used to download a file's contents, upload new versions, and perform other… # Files File objects represent individual files in Box. They can be used to download a file's contents, upload new versions, and perform other common file operations (move, copy, delete, etc.). - [Get File Info](#get-file-info) - [Update File](#update-file) - [Upload File](#upload-file) - [Upload New File Version](#upload-new-file-version) - [Download File](#download-file) - [Copy File](#copy-file) - [Lock File](#lock-file) - [Unlock File](#unlock-file) - [Get File Thumbnail Image](#get-file-thumbnail-image) - [Get File Embed Link](#get-file-embed-link) - [Get File Collaborations](#get-file-collaborations) - [Get File Comments](#get-file-comments) - [Get File Tasks](#get-file-tasks) - [Add File to Favorites](#add-file-to-favorites) - [Remove File from Favorites](#remove-file-from-favorites) - [Get Shared Link](#get-shared-link) - [Set Shared Link](#set-shared-link) - [Remove Shared Link](#remove-shared-link) - [List Representations](#list-representations) - [Download Zip](#download-zip) ## Get File Info To retrieve information about a file, call [`client.files.get(fileId:fields:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/FilesModule.html#/s:6BoxSDK11FilesModuleC3get6fileId6fields10completionySS_SaySSGSgys6ResultOyAA4FileCAA0A8SDKErrorCGctF) with the ID of the file. You can control which fields are returned on the resulting `File` object by passing the desired field names in the optional `fields` parameter. ``` client.files.get(fileId: "11111", fields: ["name", "created_at"]) { (result: Result<File, BoxSDKError>) in guard case let .success(file) = result else { print("Error retrieving file information") return } print("File \(file.name) was created at \(file.createdAt)") } ``` ## Update File To update a file record, call [`client.files.updateFileInfo(fileId:name:description:parentId:sharedLink:tags:collections:lock:dispositionAt:ifMatch:fields:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/FilesModule.html#/s:6BoxSDK11FilesModuleC6update6fileId4name11description06parentG010sharedLink4tags11collections4lock13dispositionAt7ifMatch6fields10completionySS_SSSgA2qA17NullableParameterOyAA06SharedL4DataVGSgSaySSGSgAySyAA04LockY0VGSg10Foundation4DateVSgAqYys6ResultOyAA4FileCAA0A8SDKErrorCGctF) with the ID of the file to update and the properties to update. ``` client.files.update(fileId: "11111", name: "New file name.docx") { (result: Result<File, BoxSDKError>) in guard case let .success(file) = result else { print("Error updating file information") return } print("File \(file.name) was updated at \(file.modifiedAt)") } ``` ## Upload File To upload a file from data in memory, call [`client.files.upload(data:name:parentId:progress:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/FilesModule.html#/s:6BoxSDK11FilesModuleC6upload4data4name8parentId8progress21performPreflightCheck10completiony10Foundation4DataV_S2SySo10NSProgressCcSbys6ResultOyAA4FileCAA0A8SDKErrorCGctF) with the data to be uploaded, the name of the file, and the ID of the folder into which the file should be uploaded. Use ID `"0"` to upload a file into the root folder, "All Files". ``` let data = "test content".data(using: .utf8) let task: BoxUploadTask = client.files.upload(data: data, name: "Test File.txt", parentId: "0") { (result: Result<File, BoxSDKError>) in guard case let .success(file) = result else { print("Error uploading file") return } print("File \(file.name) was uploaded at \(file.createdAt) into \"\(file.parent.name)\"") } // To cancel upload if someConditionIsSatisfied { task.cancel() } ``` To upload a file from a stream, use [`client.files.streamUpload(stream:fileSize:name:parentId:progress:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/FilesModule.html#/s:6BoxSDK11FilesModuleC12streamUpload0E08fileSize4name8parentId8progress21performPreflightCheck10completionySo13NSInputStreamC_SiS2SySo10NSProgressCcSbys6ResultOyAA4FileCAA0A8SDKErrorCGctF). ``` let data = "test content".data(using: .utf8) let stream = InputStream(data: data) let task: BoxUploadTask = client.files.streamUpload( stream: stream, fileSize: 12, name: "Test File.txt", parentId: "0" ) { (result: Result<File, BoxSDKError>) in guard case let .success(file) = result else { print("Error uploading file") return } print("File \(file.name) was uploaded at \(file.createdAt) into \"\(file.parent.name)\"") } // To cancel upload if someConditionIsSatisfied { task.cancel() } ``` ## Upload New File Version To upload a new version of an existing file, call [`client.files.uploadVersion(forFile:name:contentModifiedAt:data:ifMatch:progress:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/FilesModule.html#/s:6BoxSDK11FilesModuleC13uploadVersion7forFile4name17contentModifiedAt4data8progress21performPreflightCheck10completionySS_SSSgAL10Foundation4DataVySo10NSProgressCcSbys6ResultOyAA0H0CAA0A8SDKErrorCGctF) with the ID of the file and the file contents to be uploaded. ``` let data = "updated file content".data(using: .utf8) let task: BoxUploadTask = client.files.uploadVersion( forFile: "11111", name: "New file name.txt", contentModifiedAt: "2019-08-07T09:19:13-07:00", data: data ) { (result: Result<File, BoxSDKError>) in guard case let .success(file) = result else { print("Error uploading file version") return } print("New version of \(file.name) was uploaded") } // To cancel upload if someConditionIsSatisfied { task.cancel() } ``` To upload a new version of an existing file from a stream, use [`client.files.streamUploadVersion(stream:fileSize:forFile:name:contentModifiedAt:ifMatch:progress:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/FilesModule.html#/s:6BoxSDK11FilesModuleC13uploadVersion7forFile4name17contentModifiedAt4data8progress21performPreflightCheck10completionySS_SSSgAL10Foundation4DataVySo10NSProgressCcSbys6ResultOyAA0H0CAA0A8SDKErrorCGctF). ``` let data = "updated file content".data(using: .utf8) let stream = InputStream(data: data) let task: BoxUploadTask = client.files.streamUploadVersion( stream: stream, fileSize: 12, forFile: "11111", name: "New file name.txt", contentModifiedAt: "2021-03-07T09:19:13-07:00" ) { (result: Result<File, BoxSDKError>) in guard case let .success(file) = result else { print("Error uploading file version") return } print("New version of \(file.name) was uploaded") } // To cancel upload if someConditionIsSatisfied { task.cancel() } ``` ## Download File To download a file to the device, call [`client.files.download(fileId:version:destinationURL:progress:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/FilesModule.html#/s:6BoxSDK11FilesModuleC8download6fileId14destinationURL7version8progress10completionySS_10Foundation0I0VSSSgySo10NSProgressCcys6ResultOyytAA0A8SDKErrorCGctF) with the ID of the file to download and a URL to the location where the file should be downloaded to. ``` let url = FileManager.default.homeDirectoryForCurrentUser let task: BoxDownloadTask = client.files.download(fileId: "11111", destinationURL: url) { (result: Result<Void, BoxSDKError>) in guard case .success = result else { print("Error downloading file") return } print("File downloaded successfully") } // To cancel download if someConditionIsSatisfied { task.cancel() } ``` ## Copy File To make a copy of a file, call [`client.files.copy(fileId:parentId:name:version:fields:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/FilesModule.html#/s:6BoxSDK11FilesModuleC4copy6fileId06parentG04name7version6fields10completionySS_S2SSgAKSaySSGSgys6ResultOyAA4FileCAA0A8SDKErrorCGctF) with the ID of the file to copy and the ID of the folder into which the copy should be placed. In case an item with the same name already exists in the destination folder, the `name` parameter can be used to provide a new name for the copied file. You can copy a specific file version by passing the version ID in the `version` parameter. ``` client.files.copy(fileId: "11111", parentId: "0") { (result: Result<File, BoxSDKError>) in guard case let .success(copiedFile) = result else { print("Error copying file") return } print("Copied file \(copiedFile.name) into folder \(copiedFile.parent.name); copy has file ID \(copiedFile.id)") } ``` ## Lock File To lock a file and prevent others from modifying it, call [`client.files.lock(fileId:expiresAt:isDownloadPrevented:fields:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/FilesModule.html#/s:6BoxSDK11FilesModuleC4lock6fileId9expiresAt19isDownloadPrevented6fields10completionySS_10Foundation4DateVSgSbSgSaySSGSgys6ResultOyAA4FileCAA0A8SDKErrorCGctF) with the ID of the file. To also prevent others from downloading the file while it is locked, set the `isDownloadPrevented` parameter to `true`. ``` client.files.lock(fileId: "11111") { (result: Result<File, BoxSDKError>) in guard case let .success(file) = result else { print("Error locking file") return } print("File \(file.name) locked") } ``` ## Unlock File To unlock a file, call [`client.files.unlock(fileId:fields:completion:)](https://opensource.box.com/box-ios-sdk/Classes/FilesModule.html#/s:6BoxSDK11FilesModuleC6unlock6fileId6fields10completionySS_SaySSGSgys6ResultOyAA4FileCAA0A8SDKErrorCGctF) with the ID of the file. ``` client.files.unlock(fileId: "11111") { (result: Result<File, BoxSDKError>) in guard case let .success(file) = result else { print("Error unlocking file") return } print("File \(file.name) unlocked") } ``` ## Get File Thumbnail Image To retrieve the thumbnail image for a file, call [`client.files.getThumbnail(forFile:extension:minHeight:minWidth:maxHeight:maxWidth:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/FilesModule.html#/s:6BoxSDK11FilesModuleC12getThumbnail7forFile9extension9minHeight0J5Width03maxK00mL010completionySS_AA0F9ExtensionOSiSgA3Nys6ResultOy10Foundation4DataVAA0A8SDKErrorCGctF) with the ID of the file and the desired image format extension. Optionally, constraints on the image dimensions can be specified in the `minHeight`, `minWidth`, `maxHeight`, and `maxWidth` parameters. ``` client.files.getThumbnail(forFile: "11111", extension: .png) { (result: Result<Data, BoxSDKError>) in guard case let .success(thumbnailData) = result else { print("Error getting file thumbnail") return } let thumbnailImage = UIImage(data: thumbnailData) } ``` ## Get File Embed Link To retrieve a URL that can be embedded in a web page `<iframe>` to display a file preview, call [`client.files.getEmbedLink(forFile:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/FilesModule.html#/s:6BoxSDK11FilesModuleC12getEmbedLink7forFile10completionySS_ys6ResultOyAA08ExpiringfG0CAA0A8SDKErrorCGctF) with the ID of the file. ``` client.files.getEmbedLink(forFile: "11111") { (result: Result<ExpiringEmbedLink, BoxSDKError>) in guard case let .success(embedLink) = result else { print("Error generating file embed link") return } print("File embed URL is \(embedLink.url)") } ``` ## Get File Collaborations To retrieve a list of collaborations on a file, call [`client.files.listCollaborations(forFile:marker:limit:fields:)`](https://opensource.box.com/box-ios-sdk/Classes/FilesModule.html#/s:6BoxSDK11FilesModuleC18listCollaborations7forFile6marker5limit6fields10completionySS_SSSgSiSgSaySSGSgys6ResultOyAA14PagingIteratorCyAA13CollaborationCGAA0A8SDKErrorCGctF) with the ID of the file. This method returns an iterator, which is used to retrieve file collaborations. ``` let iterator = client.files.listCollaborations(forFile: "11111") iterator.next { result in switch results { case let .success(page): for collaboration in page.entries { print("Collaboration created by \(collaboration.createdBy?.name)") } case let .failure(error): print(error) } } ``` ## Get File Comments To retrieve a list of comments on the file, call [`client.files.listComments(forFile:offset:limit:fields:)`](https://opensource.box.com/box-ios-sdk/Classes/FilesModule.html#/s:6BoxSDK11FilesModuleC12listComments7forFile6offset5limit6fields10completionySS_SiSgAJSaySSGSgys6ResultOyAA14PagingIteratorCyAA7CommentCGAA0A8SDKErrorCGctF) with the ID of the file. This method returns an iterator, which is used to page through the collection of file comments. ``` let iterator = client.files.listComments(forFile: "11111") iterator.next { results in switch results { case let .success(page): for comment in page.entries { print(comment.message) } case let .failure(error): print(error) } } ``` ## Get File Tasks To retrieve a list of file tasks, call [`client.files.listTasks(forFile:fields:)`](https://opensource.box.com/box-ios-sdk/Classes/FilesModule.html#/s:6BoxSDK11FilesModuleC9listTasks7forFile6fields10completionySS_SaySSGSgys6ResultOyAA14PagingIteratorCyAA4TaskCGAA0A8SDKErrorCGctF) with the ID of the file. This method returns an iterator, which is used to retrieve file comments. ``` let iterator = client.files.listTasks(forFile: "11111") iterator.next { results in switch results { case let .success(page): for task in page.entries { print("Task messsage: \(task.message)") } case let .failure(error): print(error) } } ``` ## Add File to Favorites To add a file to the user's favorites collection, call [`client.files.addToFavorites(fileId:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/FilesModule.html#/s:6BoxSDK11FilesModuleC14addToFavorites6fileId10completionySS_ys6ResultOyAA4FileCAA0A8SDKErrorCGctF) with the ID of the file. ``` client.files.addToFavorites(fileId: "11111") { (result: Result<Void, BoxSDKError>) in guard case .success = result else { print("Error adding file to favorites") return } print("File added to favorites") } ``` ## Remove File from Favorites To remove a file from the user's favorites collection, call [`client.files.removeFromFavorites(fileId:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/FilesModule.html#/s:6BoxSDK11FilesModuleC19removeFromFavorites6fileId10completionySS_ys6ResultOyAA4FileCAA0A8SDKErrorCGctF) with the ID of the file. ``` client.files.removeFromFavorites(fileId: "11111") { (result: Result<Void, BoxSDKError>) in guard case .success = result else { print("Error removing file from favorites") return } print("File removed from favorites") } ``` ## Get Shared Link To retrieve the shared link associated with a file, call [`client.files.getSharedLink(forFile:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/FilesModule.html#/s:6BoxSDK11FilesModuleC13getSharedLink7forFile10completionySS_ys6ResultOyAA0fG0CAA0A8SDKErrorCGctF) with the ID of the file. ``` client.files.getSharedLink(forFile: "11111") { (result: Result<SharedLink, BoxSDKError>) in guard case let .success(sharedLink) = result else { print("Error retrieving file shared link") return } print("File shared link URL is \(sharedLink.url), with \(sharedLink.access) access") } ``` ## Set Shared Link To add or update the shared link for a file, call [`client.files.setSharedLink(forFile:unsharedAt:vanityName:access:password:canDownload:canEdit:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/FilesModule.html#/s:6BoxSDK11FilesModuleC13setSharedLink7forFile10unsharedAt10vanityName6access8password11canDownload0P4Edit10completionySS_AA17NullableParameterOy10Foundation4DateVGSgANySSGSgAA0fG6AccessOSgAUSbSgAYys6ResultOyAA0fG0CAA0A8SDKErrorCGctF) with the ID of the file and the shared link properties to set. ``` client.files.setSharedLink( forFile: "11111", access: .open, canDownload: true, canEdit: true ) { (result: Result<SharedLink, BoxSDKError>) in guard case let .success(sharedLink) = result else { print("Error setting file shared link") return } print("File shared link URL is \(sharedLink.url), with \(sharedLink.access) access") } ``` ## Remove Shared Link To remove a file's shared link, call [`client.files.deleteSharedLink(forFile:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/FilesModule.html#/s:6BoxSDK11FilesModuleC16deleteSharedLink7forFile10completionySS_ys6ResultOyytAA0A8SDKErrorCGctF) with the ID of the file. ``` client.files.deleteSharedLink(fileId: "11111") { (result: Result<Void, BoxSDKError>) in guard case .success = result else { print("Error removing file shared link") return } print("File shared link removed") } ``` ## List Representations To retrieve information about available preview representations for a file, call [`client.files.listRepresentations(fileId:representationHint:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/FilesModule.html#/s:6BoxSDK11FilesModuleC19listRepresentations6fileId18representationHint10completionySS_AA018FileRepresentationJ0OSgys6ResultOySayAA0lM0VGAA0A8SDKErrorCGctF) with the ID of the file. Omitting the `representationHint` parameter will provide summary information about all available representations; in order to retrieve the representation status and URL, the `representationHint` parameter must be passed to select the desired representation. ``` // Get full information about PDF representation client.files.listRepresentations( fileId: "11111", representationHint: "[pdf]" ) { (result: Result<[FileRepresentation], BoxSDKError>) in guard case let .success(representations) = result else { print("Error fetching representations") return } print("PDF representation generation status: \(representations[0]?.status?.state)") } ``` ## Download Zip Calling [`client.files.downloadZip(name:items:destinationURL:completion:)`][download-zip] will let you create a new zip file with the specified name and with the specified items and download it to the specified URL location where the file should be downloaded to. The created zip file does not show up in your Box account. ``` let name = "New zip name" var items: [ZipDownloadItem] = [] items.append(ZipDownloadItem( type: "file", id: "11111" )) let items: [ZipDownloadItem] = [] items.append(ZipDownloadItem( type: "folder", id: "22222" )) let documentsURL = FileManager.default.urls(for: .documentDirectory, in: .userDomainMask)[0] let destinationURL = documentsURL.appendingPathComponent("New zip name.zip") client.files.downloadZip(name: name, items: items, destinationURL: destinationURL) { (result: Result<ZipDownloadStatus, BoxSDKError>) in guard case .success = result else { guard case let .success(zipDownloadStatus) = result else { print("Error downloading zip") return } print("Zip download status: \(zipDownloadStatus.state)") } ``` --- ### FilesManager **Type:** page | **Section:** Additional Resources FilesManager Get file information Update file Delete file Copy file Get file thumbnail URL Get file thumbnail Get file information Retrieves… # FilesManager - [Get file information](#get-file-information) - [Update file](#update-file) - [Delete file](#delete-file) - [Copy file](#copy-file) - [Get file thumbnail URL](#get-file-thumbnail-url) - [Get file thumbnail](#get-file-thumbnail) ## Get file information Retrieves the details about a file. This operation is performed by calling function `getFileById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-files-id/). ``` await client.files.getFileById(uploadedFile.id, { queryParams: { fields: ['is_externally_owned', 'has_collaborations'], } satisfies GetFileByIdQueryParams, } satisfies GetFileByIdOptionalsInput); ``` ### Arguments fileId `string` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" optionalsInput `GetFileByIdOptionalsInput` ### Returns This function returns a value of type `FileFull`. Returns a file object. Not all available fields are returned by default. Use the [fields](#param-fields) query parameter to explicitly request any specific fields. ## Update file Updates a file. This can be used to rename or move a file, create a shared link, or lock a file. This operation is performed by calling function `updateFileById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-files-id/). ``` await client.files.updateFileById(fileToUpdate.id, { requestBody: { name: updatedName, description: 'Updated description', } satisfies UpdateFileByIdRequestBody, } satisfies UpdateFileByIdOptionalsInput); ``` ### Arguments fileId `string` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" optionalsInput `UpdateFileByIdOptionalsInput` ### Returns This function returns a value of type `FileFull`. Returns a file object. Not all available fields are returned by default. Use the [fields](#param-fields) query parameter to explicitly request any specific fields. ## Delete file Deletes a file, either permanently or by moving it to the trash. The the enterprise settings determine whether the item will be permanently deleted from Box or moved to the trash. This operation is performed by calling function `deleteFileById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-files-id/). ``` await client.files.deleteFileById(thumbnailFile.id); ``` ### Arguments fileId `string` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" optionalsInput `DeleteFileByIdOptionalsInput` ### Returns This function returns a value of type `undefined`. Returns an empty response when the file has been successfully deleted. ## Copy file Creates a copy of a file. This operation is performed by calling function `copyFile`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-files-id-copy/). ``` await client.files.copyFile(fileOrigin.id, { parent: { id: '0' } satisfies CopyFileRequestBodyParentField, name: copiedFileName, } satisfies CopyFileRequestBody); ``` ### Arguments fileId `string` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" requestBody `CopyFileRequestBody` - Request body of copyFile method optionalsInput `CopyFileOptionalsInput` ### Returns This function returns a value of type `FileFull`. Returns a new file object representing the copied file. Not all available fields are returned by default. Use the [fields](#param-fields) query parameter to explicitly request any specific fields. ## Get file thumbnail URL Get the download URL without downloading the content. This operation is performed by calling function `getFileThumbnailUrl`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-files-id-thumbnail-id/). ``` await client.files.getFileThumbnailUrl( thumbnailFile.id, 'png' as GetFileThumbnailUrlExtension, ); ``` ### Arguments fileId `string` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" extension `GetFileThumbnailUrlExtension` - The file format for the thumbnail. Example: "png" optionalsInput `GetFileThumbnailUrlOptionalsInput` ### Returns This function returns a value of type `string`. When a thumbnail can be created the thumbnail data will be returned in the body of the response.Sometimes generating a thumbnail can take a few seconds. In these situations the API returns a `Location`-header pointing to a placeholder graphic for this file type. The placeholder graphic can be used in a user interface until the thumbnail generation has completed. The `Retry-After`-header indicates when to the thumbnail will be ready. At that time, retry this endpoint to retrieve the thumbnail. ## Get file thumbnail Retrieves a thumbnail, or smaller image representation, of a file. Sizes of `32x32`,`64x64`, `128x128`, and `256x256` can be returned in the `.png` format and sizes of `32x32`, `160x160`, and `320x320` can be returned in the `.jpg` format. Thumbnails can be generated for the image and video file formats listed [found on our community site](https://community.box.com/t5/Migrating-and-Previewing-Content/File-Types-and-Fonts-Supported-in-Box-Content-Preview/ta-p/327). This operation is performed by calling function `getFileThumbnailById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-files-id-thumbnail-id/). ``` await client.files.getFileThumbnailById( thumbnailFile.id, 'png' as GetFileThumbnailByIdExtension, ); ``` ### Arguments fileId `string` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" extension `GetFileThumbnailByIdExtension` - The file format for the thumbnail. Example: "png" optionalsInput `GetFileThumbnailByIdOptionalsInput` ### Returns This function returns a value of type `undefined | ByteStream`. When a thumbnail can be created the thumbnail data will be returned in the body of the response.Sometimes generating a thumbnail can take a few seconds. In these situations the API returns a `Location`-header pointing to a placeholder graphic for this file type. The placeholder graphic can be used in a user interface until the thumbnail generation has completed. The `Retry-After`-header indicates when to the thumbnail will be ready. At that time, retry this endpoint to retrieve the thumbnail. --- ### FilesManager **Type:** page | **Section:** Additional Resources FilesManager Get file information Update file Delete file Copy file Get file thumbnail URL Get file thumbnail Get file information Retrieves… # FilesManager - [Get file information](#get-file-information) - [Update file](#update-file) - [Delete file](#delete-file) - [Copy file](#copy-file) - [Get file thumbnail URL](#get-file-thumbnail-url) - [Get file thumbnail](#get-file-thumbnail) ## Get file information Retrieves the details about a file. This operation is performed by calling function `get_file_by_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-files-id/). ``` client.files.get_file_by_id( uploaded_file.id, fields=["is_externally_owned", "has_collaborations"] ) ``` ### Arguments file_id `str` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" fields `Optional[List[str]]` - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested. Additionally this field can be used to query any metadata applied to the file by specifying the `metadata` field as well as the scope and key of the template to retrieve, for example `?fields=metadata.enterprise_12345.contractTemplate`. if_none_match `Optional[str]` - Ensures an item is only returned if it has changed. Pass in the item's last observed `etag` value into this header and the endpoint will fail with a `304 Not Modified` if the item has not changed since. boxapi `Optional[str]` - The URL, and optional password, for the shared link of this item. This header can be used to access items that have not been explicitly shared with a user. Use the format `shared_link=[link]` or if a password is required then use `shared_link=[link]&shared_link_password=[password]`. This header can be used on the file or folder shared, as well as on any files or folders nested within the item. x_rep_hints `Optional[str]` - A header required to request specific `representations` of a file. Use this in combination with the `fields` query parameter to request a specific file representation. The general format for these representations is `X-Rep-Hints: [...]` where `[...]` is one or many hints in the format `[fileType?query]`. For example, to request a `png` representation in `32x32` as well as `64x64` pixel dimensions provide the following hints. `x-rep-hints: [jpg?dimensions=32x32][jpg?dimensions=64x64]` Additionally, a `text` representation is available for all document file types in Box using the `[extracted_text]` representation. `x-rep-hints: [extracted_text]`. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `FileFull`. Returns a file object. Not all available fields are returned by default. Use the [fields](#param-fields) query parameter to explicitly request any specific fields. ## Update file Updates a file. This can be used to rename or move a file, create a shared link, or lock a file. This operation is performed by calling function `update_file_by_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-files-id/). ``` client.files.update_file_by_id( file_to_update.id, name=updated_name, description="Updated description" ) ``` ### Arguments file_id `str` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" name `Optional[str]` - An optional different name for the file. This can be used to rename the file. File names must be unique within their parent folder. The name check is case-insensitive, so a file named `New File` cannot be created in a parent folder that already contains a folder named `new file`. description `Optional[str]` - The description for a file. This can be seen in the right-hand sidebar panel when viewing a file in the Box web app. Additionally, this index is used in the search index of the file, allowing users to find the file by the content in the description. parent `Optional[UpdateFileByIdParent]` shared_link `Optional[UpdateFileByIdSharedLink]` lock `Optional[UpdateFileByIdLock]` - Defines a lock on an item. This prevents the item from being moved, renamed, or otherwise changed by anyone other than the user who created the lock. Set this to `null` to remove the lock. disposition_at `Optional[DateTime]` - The retention expiration timestamp for the given file. This date cannot be shortened once set on a file. permissions `Optional[UpdateFileByIdPermissions]` - Defines who can download a file. collections `Optional[List[UpdateFileByIdCollections]]` - An array of collections to make this file a member of. Currently we only support the `favorites` collection. To get the ID for a collection, use the [List all collections](https://community.box.com/t5/Migrating-and-Previewing-Content/File-Types-and-Fonts-Supported-in-Box-Content-Preview/ta-p/327) endpoint. Passing an empty array `[]` or `null` will remove the file from all collections. [1](https://community.box.com/t5/Migrating-and-Previewing-Content/File-Types-and-Fonts-Supported-in-Box-Content-Preview/ta-p/327): e://get-collections tags `Optional[List[str]]` - The tags for this item. These tags are shown in the Box web app and mobile apps next to an item. To add or remove a tag, retrieve the item's current tags, modify them, and then update this field. There is a limit of 100 tags per item, and 10,000 unique tags per enterprise. fields `Optional[List[str]]` - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested. if_match `Optional[str]` - Ensures this item hasn't recently changed before making changes. Pass in the item's last observed `etag` value into this header and the endpoint will fail with a `412 Precondition Failed` if it has changed since. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `FileFull`. Returns a file object. Not all available fields are returned by default. Use the [fields](#param-fields) query parameter to explicitly request any specific fields. ## Delete file Deletes a file, either permanently or by moving it to the trash. The the enterprise settings determine whether the item will be permanently deleted from Box or moved to the trash. This operation is performed by calling function `delete_file_by_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-files-id/). ``` client.files.delete_file_by_id(thumbnail_file.id) ``` ### Arguments file_id `str` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" if_match `Optional[str]` - Ensures this item hasn't recently changed before making changes. Pass in the item's last observed `etag` value into this header and the endpoint will fail with a `412 Precondition Failed` if it has changed since. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `None`. Returns an empty response when the file has been successfully deleted. ## Copy file Creates a copy of a file. This operation is performed by calling function `copy_file`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-files-id-copy/). ``` client.files.copy_file(file_origin.id, CopyFileParent(id="0"), name=copied_file_name) ``` ### Arguments file_id `str` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" name `Optional[str]` - An optional new name for the copied file. There are some restrictions to the file name. Names containing non-printable ASCII characters, forward and backward slashes (`/`, `\`), and protected names like `.` and `..` are automatically sanitized by removing the non-allowed characters. version `Optional[str]` - An optional ID of the specific file version to copy. parent `CopyFileParent` - The destination folder to copy the file to. fields `Optional[List[str]]` - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `FileFull`. Returns a new file object representing the copied file. Not all available fields are returned by default. Use the [fields](#param-fields) query parameter to explicitly request any specific fields. ## Get file thumbnail URL Get the download URL without downloading the content. This operation is performed by calling function `get_file_thumbnail_url`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-files-id-thumbnail-id/). ``` client.files.get_file_thumbnail_url(thumbnail_file.id, GetFileThumbnailUrlExtension.PNG) ``` ### Arguments file_id `str` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" extension `GetFileThumbnailUrlExtension` - The file format for the thumbnail. Example: "png" min_height `Optional[int]` - The minimum height of the thumbnail. min_width `Optional[int]` - The minimum width of the thumbnail. max_height `Optional[int]` - The maximum height of the thumbnail. max_width `Optional[int]` - The maximum width of the thumbnail. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `str`. When a thumbnail can be created the thumbnail data will be returned in the body of the response.Sometimes generating a thumbnail can take a few seconds. In these situations the API returns a `Location`-header pointing to a placeholder graphic for this file type. The placeholder graphic can be used in a user interface until the thumbnail generation has completed. The `Retry-After`-header indicates when to the thumbnail will be ready. At that time, retry this endpoint to retrieve the thumbnail. ## Get file thumbnail Retrieves a thumbnail, or smaller image representation, of a file. Sizes of `32x32`,`64x64`, `128x128`, and `256x256` can be returned in the `.png` format and sizes of `32x32`, `160x160`, and `320x320` can be returned in the `.jpg` format. Thumbnails can be generated for the image and video file formats listed [found on our community site](https://community.box.com/t5/Migrating-and-Previewing-Content/File-Types-and-Fonts-Supported-in-Box-Content-Preview/ta-p/327). This operation is performed by calling function `get_file_thumbnail_by_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-files-id-thumbnail-id/). ``` client.files.get_file_thumbnail_by_id( thumbnail_file.id, GetFileThumbnailByIdExtension.PNG ) ``` ### Arguments file_id `str` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" extension `GetFileThumbnailByIdExtension` - The file format for the thumbnail. Example: "png" min_height `Optional[int]` - The minimum height of the thumbnail. min_width `Optional[int]` - The minimum width of the thumbnail. max_height `Optional[int]` - The maximum height of the thumbnail. max_width `Optional[int]` - The maximum width of the thumbnail. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `Optional[ByteStream]`. When a thumbnail can be created the thumbnail data will be returned in the body of the response.Sometimes generating a thumbnail can take a few seconds. In these situations the API returns a `Location`-header pointing to a placeholder graphic for this file type. The placeholder graphic can be used in a user interface until the thumbnail generation has completed. The `Retry-After`-header indicates when to the thumbnail will be ready. At that time, retry this endpoint to retrieve the thumbnail. --- ### FileVersionLegalHoldsManager **Type:** page | **Section:** Additional Resources FileVersionLegalHoldsManager Get file version legal hold List file version legal holds Get file version legal hold Retrieves information… # FileVersionLegalHoldsManager - [Get file version legal hold](#get-file-version-legal-hold) - [List file version legal holds](#list-file-version-legal-holds) ## Get file version legal hold Retrieves information about the legal hold policies assigned to a file version. This operation is performed by calling function `getFileVersionLegalHoldById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-file-version-legal-holds-id/). ``` await client.fileVersionLegalHolds.getFileVersionLegalHoldById( fileVersionLegalHoldId, ); ``` ### Arguments fileVersionLegalHoldId `string` - The ID of the file version legal hold. Example: "2348213" optionalsInput `GetFileVersionLegalHoldByIdOptionalsInput` ### Returns This function returns a value of type `FileVersionLegalHold`. Returns the legal hold policy assignments for the file version. ## List file version legal holds Get a list of file versions on legal hold for a legal hold assignment. Due to ongoing re-architecture efforts this API might not return all file versions for this policy ID. Instead, this API will only return file versions held in the legacy architecture. Two new endpoints will available to request any file versions held in the new architecture. For file versions held in the new architecture, the `GET /legal_hold_policy_assignments/:id/file_versions_on_hold` API can be used to return all past file versions available for this policy assignment, and the `GET /legal_hold_policy_assignments/:id/files_on_hold` API can be used to return any current (latest) versions of a file under legal hold. The `GET /legal_hold_policy_assignments?policy_id={id}` API can be used to find a list of policy assignments for a given policy ID. Once the re-architecture is completed this API will be deprecated. This operation is performed by calling function `getFileVersionLegalHolds`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-file-version-legal-holds/). ``` await client.fileVersionLegalHolds.getFileVersionLegalHolds({ policyId: policyId, } satisfies GetFileVersionLegalHoldsQueryParams); ``` ### Arguments queryParams `GetFileVersionLegalHoldsQueryParams` - Query parameters of getFileVersionLegalHolds method optionalsInput `GetFileVersionLegalHoldsOptionalsInput` ### Returns This function returns a value of type `FileVersionLegalHolds`. Returns the list of file version legal holds for a specific legal hold policy. --- ### FileVersionLegalHoldsManager **Type:** page | **Section:** Additional Resources FileVersionLegalHoldsManager Get file version legal hold List file version legal holds Get file version legal hold Retrieves information… # FileVersionLegalHoldsManager - [Get file version legal hold](#get-file-version-legal-hold) - [List file version legal holds](#list-file-version-legal-holds) ## Get file version legal hold Retrieves information about the legal hold policies assigned to a file version. This operation is performed by calling function `get_file_version_legal_hold_by_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-file-version-legal-holds-id/). ``` client.file_version_legal_holds.get_file_version_legal_hold_by_id( file_version_legal_hold_id ) ``` ### Arguments file_version_legal_hold_id `str` - The ID of the file version legal hold. Example: "2348213" extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `FileVersionLegalHold`. Returns the legal hold policy assignments for the file version. ## List file version legal holds Get a list of file versions on legal hold for a legal hold assignment. Due to ongoing re-architecture efforts this API might not return all file versions for this policy ID. Instead, this API will only return file versions held in the legacy architecture. Two new endpoints will available to request any file versions held in the new architecture. For file versions held in the new architecture, the `GET /legal_hold_policy_assignments/:id/file_versions_on_hold` API can be used to return all past file versions available for this policy assignment, and the `GET /legal_hold_policy_assignments/:id/files_on_hold` API can be used to return any current (latest) versions of a file under legal hold. The `GET /legal_hold_policy_assignments?policy_id={id}` API can be used to find a list of policy assignments for a given policy ID. Once the re-architecture is completed this API will be deprecated. This operation is performed by calling function `get_file_version_legal_holds`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-file-version-legal-holds/). ``` client.file_version_legal_holds.get_file_version_legal_holds(policy_id) ``` ### Arguments policy_id `str` - The ID of the legal hold policy to get the file version legal holds for. marker `Optional[str]` - Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`. limit `Optional[int]` - The maximum number of items to return per page. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `FileVersionLegalHolds`. Returns the list of file version legal holds for a specific legal hold policy. --- ### FileVersionRetentionsManager **Type:** page | **Section:** Additional Resources FileVersionRetentionsManager List file version retentions Get retention on file List file version retentions Retrieves all file version… # FileVersionRetentionsManager - [List file version retentions](#list-file-version-retentions) - [Get retention on file](#get-retention-on-file) ## List file version retentions Retrieves all file version retentions for the given enterprise. **Note**: File retention API is now **deprecated**. To get information about files and file versions under retention, see [files under retention](e://get-retention-policy-assignments-id-files-under-retention) or [file versions under retention](e://get-retention-policy-assignments-id-file-versions-under-retention) endpoints. This operation is performed by calling function `getFileVersionRetentions`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-file-version-retentions/). ``` await client.fileVersionRetentions.getFileVersionRetentions(); ``` ### Arguments queryParams `GetFileVersionRetentionsQueryParams` - Query parameters of getFileVersionRetentions method headersInput `GetFileVersionRetentionsHeadersInput` - Headers of getFileVersionRetentions method cancellationToken `undefined | CancellationToken` - Token used for request cancellation. ### Returns This function returns a value of type `FileVersionRetentions`. Returns a list of all file version retentions for the enterprise. ## Get retention on file Returns information about a file version retention. **Note**: File retention API is now **deprecated**. To get information about files and file versions under retention, see [files under retention](e://get-retention-policy-assignments-id-files-under-retention) or [file versions under retention](e://get-retention-policy-assignments-id-file-versions-under-retention) endpoints. This operation is performed by calling function `getFileVersionRetentionById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-file-version-retentions-id/). ``` await client.fileVersionRetentions.getFileVersionRetentionById( fileVersionRetention.id!, ); ``` ### Arguments fileVersionRetentionId `string` - The ID of the file version retention. Example: "3424234" optionalsInput `GetFileVersionRetentionByIdOptionalsInput` ### Returns This function returns a value of type `FileVersionRetention`. Returns a file version retention object. --- ### FileVersionRetentionsManager **Type:** page | **Section:** Additional Resources FileVersionRetentionsManager List file version retentions Get retention on file List file version retentions Retrieves all file version… # FileVersionRetentionsManager - [List file version retentions](#list-file-version-retentions) - [Get retention on file](#get-retention-on-file) ## List file version retentions Retrieves all file version retentions for the given enterprise. **Note**: File retention API is now **deprecated**. To get information about files and file versions under retention, see [files under retention](e://get-retention-policy-assignments-id-files-under-retention) or [file versions under retention](e://get-retention-policy-assignments-id-file-versions-under-retention) endpoints. This operation is performed by calling function `get_file_version_retentions`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-file-version-retentions/). ``` client.file_version_retentions.get_file_version_retentions() ``` ### Arguments file_id `Optional[str]` - Filters results by files with this ID. file_version_id `Optional[str]` - Filters results by file versions with this ID. policy_id `Optional[str]` - Filters results by the retention policy with this ID. disposition_action `Optional[GetFileVersionRetentionsDispositionAction]` - Filters results by the retention policy with this disposition action. disposition_before `Optional[str]` - Filters results by files that will have their disposition come into effect before this date. disposition_after `Optional[str]` - Filters results by files that will have their disposition come into effect after this date. limit `Optional[int]` - The maximum number of items to return per page. marker `Optional[str]` - Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `FileVersionRetentions`. Returns a list of all file version retentions for the enterprise. ## Get retention on file Returns information about a file version retention. **Note**: File retention API is now **deprecated**. To get information about files and file versions under retention, see [files under retention](e://get-retention-policy-assignments-id-files-under-retention) or [file versions under retention](e://get-retention-policy-assignments-id-file-versions-under-retention) endpoints. This operation is performed by calling function `get_file_version_retention_by_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-file-version-retentions-id/). ``` client.file_version_retentions.get_file_version_retention_by_id( file_version_retention.id ) ``` ### Arguments file_version_retention_id `str` - The ID of the file version retention. Example: "3424234" extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `FileVersionRetention`. Returns a file version retention object. --- ### FileVersionsManager **Type:** page | **Section:** Additional Resources FileVersionsManager List all file versions Get file version Remove file version Restore file version Promote file version List all file… # FileVersionsManager - [List all file versions](#list-all-file-versions) - [Get file version](#get-file-version) - [Remove file version](#remove-file-version) - [Restore file version](#restore-file-version) - [Promote file version](#promote-file-version) ## List all file versions Retrieve a list of the past versions for a file. Versions are only tracked by Box users with premium accounts. To fetch the ID of the current version of a file, use the `GET /file/:id` API. This operation is performed by calling function `getFileVersions`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-files-id-versions/). ``` await client.fileVersions.getFileVersions(file.id); ``` ### Arguments fileId `string` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" optionalsInput `GetFileVersionsOptionalsInput` ### Returns This function returns a value of type `FileVersions`. Returns an array of past versions for this file. ## Get file version Retrieve a specific version of a file. Versions are only tracked for Box users with premium accounts. This operation is performed by calling function `getFileVersionById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-files-id-versions-id/). ``` await client.fileVersions.getFileVersionById( file.id, fileVersions.entries![0].id, ); ``` ### Arguments fileId `string` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" fileVersionId `string` - The ID of the file version. Example: "1234" optionalsInput `GetFileVersionByIdOptionalsInput` ### Returns This function returns a value of type `FileVersionFull`. Returns a specific version of a file. Not all available fields are returned by default. Use the [fields](#param-fields) query parameter to explicitly request any specific fields. ## Remove file version Move a file version to the trash. Versions are only tracked for Box users with premium accounts. This operation is performed by calling function `deleteFileVersionById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-files-id-versions-id/). ``` await client.fileVersions.deleteFileVersionById(file.id, fileVersion.id); ``` ### Arguments fileId `string` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" fileVersionId `string` - The ID of the file version. Example: "1234" optionalsInput `DeleteFileVersionByIdOptionalsInput` ### Returns This function returns a value of type `undefined`. Returns an empty response when the file has been successfully deleted. ## Restore file version Restores a specific version of a file after it was deleted. Don't use this endpoint to restore Box Notes, as it works with file formats such as PDF, DOC, PPTX or similar. This operation is performed by calling function `updateFileVersionById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-files-id-versions-id/). ``` await client.fileVersions.updateFileVersionById(file.id, fileVersion.id, { requestBody: { trashedAt: createNull(), } satisfies UpdateFileVersionByIdRequestBody, } satisfies UpdateFileVersionByIdOptionalsInput); ``` ### Arguments fileId `string` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" fileVersionId `string` - The ID of the file version. Example: "1234" optionalsInput `UpdateFileVersionByIdOptionalsInput` ### Returns This function returns a value of type `FileVersionFull`. Returns a restored file version object. ## Promote file version Promote a specific version of a file. If previous versions exist, this method can be used to promote one of the older versions to the top of the version history. This creates a new copy of the old version and puts it at the top of the versions history. The file will have the exact same contents as the older version, with the the same hash digest, `etag`, and name as the original. Other properties such as comments do not get updated to their former values. Don't use this endpoint to restore Box Notes, as it works with file formats such as PDF, DOC, PPTX or similar. This operation is performed by calling function `promoteFileVersion`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-files-id-versions-current/). ``` await client.fileVersions.promoteFileVersion(file.id, { requestBody: { id: fileVersions.entries![0].id, type: 'file_version' as PromoteFileVersionRequestBodyTypeField, } satisfies PromoteFileVersionRequestBody, } satisfies PromoteFileVersionOptionalsInput); ``` ### Arguments fileId `string` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" optionalsInput `PromoteFileVersionOptionalsInput` ### Returns This function returns a value of type `FileVersionFull`. Returns a newly created file version object. --- ### FileVersionsManager **Type:** page | **Section:** Additional Resources FileVersionsManager List all file versions Get file version Remove file version Restore file version Promote file version List all file… # FileVersionsManager - [List all file versions](#list-all-file-versions) - [Get file version](#get-file-version) - [Remove file version](#remove-file-version) - [Restore file version](#restore-file-version) - [Promote file version](#promote-file-version) ## List all file versions Retrieve a list of the past versions for a file. Versions are only tracked by Box users with premium accounts. To fetch the ID of the current version of a file, use the `GET /file/:id` API. This operation is performed by calling function `get_file_versions`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-files-id-versions/). ``` client.file_versions.get_file_versions(file.id) ``` ### Arguments file_id `str` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" fields `Optional[List[str]]` - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested. limit `Optional[int]` - The maximum number of items to return per page. offset `Optional[int]` - The offset of the item at which to begin the response. Queries with offset parameter value exceeding 10000 will be rejected with a 400 response. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `FileVersions`. Returns an array of past versions for this file. ## Get file version Retrieve a specific version of a file. Versions are only tracked for Box users with premium accounts. This operation is performed by calling function `get_file_version_by_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-files-id-versions-id/). ``` client.file_versions.get_file_version_by_id(file.id, file_versions.entries[0].id) ``` ### Arguments file_id `str` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" file_version_id `str` - The ID of the file version. Example: "1234" fields `Optional[List[str]]` - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `FileVersionFull`. Returns a specific version of a file. Not all available fields are returned by default. Use the [fields](#param-fields) query parameter to explicitly request any specific fields. ## Remove file version Move a file version to the trash. Versions are only tracked for Box users with premium accounts. This operation is performed by calling function `delete_file_version_by_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-files-id-versions-id/). ``` client.file_versions.delete_file_version_by_id(file.id, file_version.id) ``` ### Arguments file_id `str` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" file_version_id `str` - The ID of the file version. Example: "1234" if_match `Optional[str]` - Ensures this item hasn't recently changed before making changes. Pass in the item's last observed `etag` value into this header and the endpoint will fail with a `412 Precondition Failed` if it has changed since. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `None`. Returns an empty response when the file has been successfully deleted. ## Restore file version Restores a specific version of a file after it was deleted. Don't use this endpoint to restore Box Notes, as it works with file formats such as PDF, DOC, PPTX or similar. This operation is performed by calling function `update_file_version_by_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-files-id-versions-id/). ``` client.file_versions.update_file_version_by_id( file.id, file_version.id, trashed_at=create_null() ) ``` ### Arguments file_id `str` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" file_version_id `str` - The ID of the file version. Example: "1234" trashed_at `Optional[str]` - Set this to `null` to clear the date and restore the file. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `FileVersionFull`. Returns a restored file version object. ## Promote file version Promote a specific version of a file. If previous versions exist, this method can be used to promote one of the older versions to the top of the version history. This creates a new copy of the old version and puts it at the top of the versions history. The file will have the exact same contents as the older version, with the the same hash digest, `etag`, and name as the original. Other properties such as comments do not get updated to their former values. Don't use this endpoint to restore Box Notes, as it works with file formats such as PDF, DOC, PPTX or similar. This operation is performed by calling function `promote_file_version`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-files-id-versions-current/). ``` client.file_versions.promote_file_version( file.id, id=file_versions.entries[0].id, type=PromoteFileVersionType.FILE_VERSION ) ``` ### Arguments file_id `str` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" id `Optional[str]` - The file version ID. type `Optional[PromoteFileVersionType]` - The type to promote. fields `Optional[List[str]]` - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `FileVersionFull`. Returns a newly created file version object. --- ### FileWatermarksManager **Type:** page | **Section:** Additional Resources FileWatermarksManager Get watermark on file Apply watermark to file Remove watermark from file Get watermark on file Retrieve the watermark… # FileWatermarksManager - [Get watermark on file](#get-watermark-on-file) - [Apply watermark to file](#apply-watermark-to-file) - [Remove watermark from file](#remove-watermark-from-file) ## Get watermark on file Retrieve the watermark for a file. This operation is performed by calling function `getFileWatermark`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-files-id-watermark/). ``` await client.fileWatermarks.getFileWatermark(file.id); ``` ### Arguments fileId `string` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" optionalsInput `GetFileWatermarkOptionalsInput` ### Returns This function returns a value of type `Watermark`. Returns an object containing information about the watermark associated for to this file. ## Apply watermark to file Applies or update a watermark on a file. This operation is performed by calling function `updateFileWatermark`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-files-id-watermark/). ``` await client.fileWatermarks.updateFileWatermark(file.id, { watermark: new UpdateFileWatermarkRequestBodyWatermarkField({ imprint: 'default' as UpdateFileWatermarkRequestBodyWatermarkImprintField, }), } satisfies UpdateFileWatermarkRequestBody); ``` ### Arguments fileId `string` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" requestBody `UpdateFileWatermarkRequestBody` - Request body of updateFileWatermark method optionalsInput `UpdateFileWatermarkOptionalsInput` ### Returns This function returns a value of type `Watermark`. Returns an updated watermark if a watermark already existed on this file.Returns a new watermark if no watermark existed on this file yet. ## Remove watermark from file Removes the watermark from a file. This operation is performed by calling function `deleteFileWatermark`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-files-id-watermark/). ``` await client.fileWatermarks.deleteFileWatermark(file.id); ``` ### Arguments fileId `string` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" optionalsInput `DeleteFileWatermarkOptionalsInput` ### Returns This function returns a value of type `undefined`. Removes the watermark and returns an empty response. --- ### FileWatermarksManager **Type:** page | **Section:** Additional Resources FileWatermarksManager Get watermark on file Apply watermark to file Remove watermark from file Get watermark on file Retrieve the watermark… # FileWatermarksManager - [Get watermark on file](#get-watermark-on-file) - [Apply watermark to file](#apply-watermark-to-file) - [Remove watermark from file](#remove-watermark-from-file) ## Get watermark on file Retrieve the watermark for a file. This operation is performed by calling function `get_file_watermark`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-files-id-watermark/). ``` client.file_watermarks.get_file_watermark(file.id) ``` ### Arguments file_id `str` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `Watermark`. Returns an object containing information about the watermark associated for to this file. ## Apply watermark to file Applies or update a watermark on a file. This operation is performed by calling function `update_file_watermark`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-files-id-watermark/). ``` client.file_watermarks.update_file_watermark( file.id, UpdateFileWatermarkWatermark( imprint=UpdateFileWatermarkWatermarkImprintField.DEFAULT ), ) ``` ### Arguments file_id `str` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" watermark `UpdateFileWatermarkWatermark` - The watermark to imprint on the file. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `Watermark`. Returns an updated watermark if a watermark already existed on this file.Returns a new watermark if no watermark existed on this file yet. ## Remove watermark from file Removes the watermark from a file. This operation is performed by calling function `delete_file_watermark`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-files-id-watermark/). ``` client.file_watermarks.delete_file_watermark(file.id) ``` ### Arguments file_id `str` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `None`. Removes the watermark and returns an empty response. --- ### FolderClassificationsManager **Type:** page | **Section:** Additional Resources FolderClassificationsManager Get classification on folder Add classification to folder Update classification on folder Remove classification… # FolderClassificationsManager - [Get classification on folder](#get-classification-on-folder) - [Add classification to folder](#add-classification-to-folder) - [Update classification on folder](#update-classification-on-folder) - [Remove classification from folder](#remove-classification-from-folder) ## Get classification on folder Retrieves the classification metadata instance that has been applied to a folder. This API can also be called by including the enterprise ID in the URL explicitly, for example `/folders/:id/enterprise_12345/securityClassification-6VMVochwUWo`. This operation is performed by calling function `getClassificationOnFolder`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-folders-id-metadata-enterprise-securityClassification-6VMVochwUWo/). ``` await client.folderClassifications.getClassificationOnFolder(folder.id); ``` ### Arguments folderId `string` - The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. Example: "12345" optionalsInput `GetClassificationOnFolderOptionalsInput` ### Returns This function returns a value of type `Classification`. Returns an instance of the `securityClassification` metadata template, which contains a `Box__Security__Classification__Key` field that lists all the classifications available to this enterprise. ## Add classification to folder Adds a classification to a folder by specifying the label of the classification to add. This API can also be called by including the enterprise ID in the URL explicitly, for example `/folders/:id/enterprise_12345/securityClassification-6VMVochwUWo`. This operation is performed by calling function `addClassificationToFolder`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-folders-id-metadata-enterprise-securityClassification-6VMVochwUWo/). ``` await client.folderClassifications.addClassificationToFolder(folder.id, { requestBody: { boxSecurityClassificationKey: classification.key, } satisfies AddClassificationToFolderRequestBody, } satisfies AddClassificationToFolderOptionalsInput); ``` ### Arguments folderId `string` - The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. Example: "12345" optionalsInput `AddClassificationToFolderOptionalsInput` ### Returns This function returns a value of type `Classification`. Returns the classification template instance that was applied to the folder. ## Update classification on folder Updates a classification on a folder. The classification can only be updated if a classification has already been applied to the folder before. When editing classifications, only values are defined for the enterprise will be accepted. This operation is performed by calling function `updateClassificationOnFolder`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-folders-id-metadata-enterprise-securityClassification-6VMVochwUWo/). ``` await client.folderClassifications.updateClassificationOnFolder(folder.id, [ new UpdateClassificationOnFolderRequestBody({ value: secondClassification.key, }), ]); ``` ### Arguments folderId `string` - The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. Example: "12345" requestBody `readonly UpdateClassificationOnFolderRequestBody[]` - Request body of updateClassificationOnFolder method optionalsInput `UpdateClassificationOnFolderOptionalsInput` ### Returns This function returns a value of type `Classification`. Returns the updated classification metadata template instance. ## Remove classification from folder Removes any classifications from a folder. This API can also be called by including the enterprise ID in the URL explicitly, for example `/folders/:id/enterprise_12345/securityClassification-6VMVochwUWo`. This operation is performed by calling function `deleteClassificationFromFolder`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-folders-id-metadata-enterprise-securityClassification-6VMVochwUWo/). ``` await client.folderClassifications.deleteClassificationFromFolder(folder.id); ``` ### Arguments folderId `string` - The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. Example: "12345" optionalsInput `DeleteClassificationFromFolderOptionalsInput` ### Returns This function returns a value of type `undefined`. Returns an empty response when the classification is successfully deleted. --- ### FolderClassificationsManager **Type:** page | **Section:** Additional Resources FolderClassificationsManager Get classification on folder Add classification to folder Update classification on folder Remove classification… # FolderClassificationsManager - [Get classification on folder](#get-classification-on-folder) - [Add classification to folder](#add-classification-to-folder) - [Update classification on folder](#update-classification-on-folder) - [Remove classification from folder](#remove-classification-from-folder) ## Get classification on folder Retrieves the classification metadata instance that has been applied to a folder. This API can also be called by including the enterprise ID in the URL explicitly, for example `/folders/:id/enterprise_12345/securityClassification-6VMVochwUWo`. This operation is performed by calling function `get_classification_on_folder`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-folders-id-metadata-enterprise-securityClassification-6VMVochwUWo/). ``` client.folder_classifications.get_classification_on_folder(folder.id) ``` ### Arguments folder_id `str` - The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. Example: "12345" extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `Classification`. Returns an instance of the `securityClassification` metadata template, which contains a `Box__Security__Classification__Key` field that lists all the classifications available to this enterprise. ## Add classification to folder Adds a classification to a folder by specifying the label of the classification to add. This API can also be called by including the enterprise ID in the URL explicitly, for example `/folders/:id/enterprise_12345/securityClassification-6VMVochwUWo`. This operation is performed by calling function `add_classification_to_folder`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-folders-id-metadata-enterprise-securityClassification-6VMVochwUWo/). ``` client.folder_classifications.add_classification_to_folder( folder.id, box_security_classification_key=classification.key ) ``` ### Arguments folder_id `str` - The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. Example: "12345" box_security_classification_key `Optional[str]` - The name of the classification to apply to this folder. To list the available classifications in an enterprise, use the classification API to retrieve the [classification template](e://get_metadata_templates_enterprise_securityClassification-6VMVochwUWo_schema) which lists all available classification keys. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `Classification`. Returns the classification template instance that was applied to the folder. ## Update classification on folder Updates a classification on a folder. The classification can only be updated if a classification has already been applied to the folder before. When editing classifications, only values are defined for the enterprise will be accepted. This operation is performed by calling function `update_classification_on_folder`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-folders-id-metadata-enterprise-securityClassification-6VMVochwUWo/). ``` client.folder_classifications.update_classification_on_folder( folder.id, [UpdateClassificationOnFolderRequestBody(value=second_classification.key)], ) ``` ### Arguments folder_id `str` - The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. Example: "12345" request_body `List[UpdateClassificationOnFolderRequestBody]` - Request body of updateClassificationOnFolder method extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `Classification`. Returns the updated classification metadata template instance. ## Remove classification from folder Removes any classifications from a folder. This API can also be called by including the enterprise ID in the URL explicitly, for example `/folders/:id/enterprise_12345/securityClassification-6VMVochwUWo`. This operation is performed by calling function `delete_classification_from_folder`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-folders-id-metadata-enterprise-securityClassification-6VMVochwUWo/). ``` client.folder_classifications.delete_classification_from_folder(folder.id) ``` ### Arguments folder_id `str` - The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. Example: "12345" extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `None`. Returns an empty response when the classification is successfully deleted. --- ### FolderLocksManager **Type:** page | **Section:** Additional Resources FolderLocksManager List folder locks Create folder lock Delete folder lock List folder locks Retrieves folder lock details for a given… # FolderLocksManager - [List folder locks](#list-folder-locks) - [Create folder lock](#create-folder-lock) - [Delete folder lock](#delete-folder-lock) ## List folder locks Retrieves folder lock details for a given folder. You must be authenticated as the owner or co-owner of the folder to use this endpoint. This operation is performed by calling function `getFolderLocks`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-folder-locks/). ``` await client.folderLocks.getFolderLocks({ folderId: folder.id, } satisfies GetFolderLocksQueryParams); ``` ### Arguments queryParams `GetFolderLocksQueryParams` - Query parameters of getFolderLocks method optionalsInput `GetFolderLocksOptionalsInput` ### Returns This function returns a value of type `FolderLocks`. Returns details for all folder locks applied to the folder, including the lock type and user that applied the lock. ## Create folder lock Creates a folder lock on a folder, preventing it from being moved and/or deleted. You must be authenticated as the owner or co-owner of the folder to use this endpoint. This operation is performed by calling function `createFolderLock`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-folder-locks/). ``` await client.folderLocks.createFolderLock({ folder: { id: folder.id, type: 'folder', } satisfies CreateFolderLockRequestBodyFolderField, lockedOperations: { move: true, delete: true, } satisfies CreateFolderLockRequestBodyLockedOperationsField, } satisfies CreateFolderLockRequestBody); ``` ### Arguments requestBody `CreateFolderLockRequestBody` - Request body of createFolderLock method optionalsInput `CreateFolderLockOptionalsInput` ### Returns This function returns a value of type `FolderLock`. Returns the instance of the folder lock that was applied to the folder, including the user that applied the lock and the operations set. ## Delete folder lock Deletes a folder lock on a given folder. You must be authenticated as the owner or co-owner of the folder to use this endpoint. This operation is performed by calling function `deleteFolderLockById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-folder-locks-id/). ``` await client.folderLocks.deleteFolderLockById(folderLock.id!); ``` ### Arguments folderLockId `string` - The ID of the folder lock. Example: "12345" optionalsInput `DeleteFolderLockByIdOptionalsInput` ### Returns This function returns a value of type `undefined`. Returns an empty response when the folder lock is successfully deleted. --- ### FolderLocksManager **Type:** page | **Section:** Additional Resources FolderLocksManager List folder locks Create folder lock Delete folder lock List folder locks Retrieves folder lock details for a given… # FolderLocksManager - [List folder locks](#list-folder-locks) - [Create folder lock](#create-folder-lock) - [Delete folder lock](#delete-folder-lock) ## List folder locks Retrieves folder lock details for a given folder. You must be authenticated as the owner or co-owner of the folder to use this endpoint. This operation is performed by calling function `get_folder_locks`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-folder-locks/). ``` client.folder_locks.get_folder_locks(folder.id) ``` ### Arguments folder_id `str` - The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `FolderLocks`. Returns details for all folder locks applied to the folder, including the lock type and user that applied the lock. ## Create folder lock Creates a folder lock on a folder, preventing it from being moved and/or deleted. You must be authenticated as the owner or co-owner of the folder to use this endpoint. This operation is performed by calling function `create_folder_lock`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-folder-locks/). ``` client.folder_locks.create_folder_lock( CreateFolderLockFolder(id=folder.id, type="folder"), locked_operations=CreateFolderLockLockedOperations(move=True, delete=True), ) ``` ### Arguments locked_operations `Optional[CreateFolderLockLockedOperations]` - The operations to lock for the folder. If `locked_operations` is included in the request, both `move` and `delete` must also be included and both set to `true`. folder `CreateFolderLockFolder` - The folder to apply the lock to. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `FolderLock`. Returns the instance of the folder lock that was applied to the folder, including the user that applied the lock and the operations set. ## Delete folder lock Deletes a folder lock on a given folder. You must be authenticated as the owner or co-owner of the folder to use this endpoint. This operation is performed by calling function `delete_folder_lock_by_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-folder-locks-id/). ``` client.folder_locks.delete_folder_lock_by_id(folder_lock.id) ``` ### Arguments folder_lock_id `str` - The ID of the folder lock. Example: "12345" extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `None`. Returns an empty response when the folder lock is successfully deleted. --- ### FolderMetadataManager **Type:** page | **Section:** Additional Resources FolderMetadataManager List metadata instances on folder Get metadata instance on folder Create metadata instance on folder Update metadata… # FolderMetadataManager - [List metadata instances on folder](#list-metadata-instances-on-folder) - [Get metadata instance on folder](#get-metadata-instance-on-folder) - [Create metadata instance on folder](#create-metadata-instance-on-folder) - [Update metadata instance on folder](#update-metadata-instance-on-folder) - [Remove metadata instance from folder](#remove-metadata-instance-from-folder) ## List metadata instances on folder Retrieves all metadata for a given folder. This can not be used on the root folder with ID `0`. This operation is performed by calling function `getFolderMetadata`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-folders-id-metadata/). ``` await client.folderMetadata.getFolderMetadata(folder.id); ``` ### Arguments folderId `string` - The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. Example: "12345" optionalsInput `GetFolderMetadataOptionalsInput` ### Returns This function returns a value of type `Metadatas`. Returns all the metadata associated with a folder. This API does not support pagination and will therefore always return all of the metadata associated to the folder. ## Get metadata instance on folder Retrieves the instance of a metadata template that has been applied to a folder. This can not be used on the root folder with ID `0`. This operation is performed by calling function `getFolderMetadataById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-folders-id-metadata-id-id/). ``` await client.folderMetadata.getFolderMetadataById( folder.id, 'global' as GetFolderMetadataByIdScope, 'properties', ); ``` ### Arguments folderId `string` - The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. Example: "12345" scope `GetFolderMetadataByIdScope` - The scope of the metadata template. Example: "global" templateKey `string` - The name of the metadata template. Example: "properties" optionalsInput `GetFolderMetadataByIdOptionalsInput` ### Returns This function returns a value of type `MetadataFull`. An instance of the metadata template that includes additional "key:value" pairs defined by the user or an application. ## Create metadata instance on folder Applies an instance of a metadata template to a folder. In most cases only values that are present in the metadata template will be accepted, except for the `global.properties` template which accepts any key-value pair. To display the metadata template in the Box web app the enterprise needs to be configured to enable **Cascading Folder Level Metadata** for the user in the admin console. This operation is performed by calling function `createFolderMetadataById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-folders-id-metadata-id-id/). ``` await client.folderMetadata.createFolderMetadataById( folder.id, 'enterprise' as CreateFolderMetadataByIdScope, templateKey, { ['name']: 'John', ['age']: 23, ['birthDate']: '2001-01-03T02:20:50.520Z', ['countryCode']: 'US', ['sports']: ['basketball', 'tennis'], }, ); ``` ### Arguments folderId `string` - The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. Example: "12345" scope `CreateFolderMetadataByIdScope` - The scope of the metadata template. Example: "global" templateKey `string` - The name of the metadata template. Example: "properties" requestBody `CreateFolderMetadataByIdRequestBody` - Request body of createFolderMetadataById method optionalsInput `CreateFolderMetadataByIdOptionalsInput` ### Returns This function returns a value of type `MetadataFull`. Returns the instance of the template that was applied to the folder, including the data that was applied to the template. ## Update metadata instance on folder Updates a piece of metadata on a folder. The metadata instance can only be updated if the template has already been applied to the folder before. When editing metadata, only values that match the metadata template schema will be accepted. The update is applied atomically. If any errors occur during the application of the operations, the metadata instance will not be changed. This operation is performed by calling function `updateFolderMetadataById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-folders-id-metadata-id-id/). ``` await client.folderMetadata.updateFolderMetadataById( folder.id, 'enterprise' as UpdateFolderMetadataByIdScope, templateKey, [ { op: 'replace' as UpdateFolderMetadataByIdRequestBodyOpField, path: '/name', value: 'Jack', } satisfies UpdateFolderMetadataByIdRequestBody, { op: 'replace' as UpdateFolderMetadataByIdRequestBodyOpField, path: '/age', value: 24, } satisfies UpdateFolderMetadataByIdRequestBody, { op: 'replace' as UpdateFolderMetadataByIdRequestBodyOpField, path: '/birthDate', value: '2000-01-03T02:20:50.520Z', } satisfies UpdateFolderMetadataByIdRequestBody, { op: 'replace' as UpdateFolderMetadataByIdRequestBodyOpField, path: '/countryCode', value: 'CA', } satisfies UpdateFolderMetadataByIdRequestBody, { op: 'replace' as UpdateFolderMetadataByIdRequestBodyOpField, path: '/sports', value: ['football'], } satisfies UpdateFolderMetadataByIdRequestBody, ], ); ``` ### Arguments folderId `string` - The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. Example: "12345" scope `UpdateFolderMetadataByIdScope` - The scope of the metadata template. Example: "global" templateKey `string` - The name of the metadata template. Example: "properties" requestBody `readonly UpdateFolderMetadataByIdRequestBody[]` - Request body of updateFolderMetadataById method optionalsInput `UpdateFolderMetadataByIdOptionalsInput` ### Returns This function returns a value of type `MetadataFull`. Returns the updated metadata template instance, with the custom template data included. ## Remove metadata instance from folder Deletes a piece of folder metadata. This operation is performed by calling function `deleteFolderMetadataById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-folders-id-metadata-id-id/). ``` await client.folderMetadata.deleteFolderMetadataById( folder.id, 'enterprise' as DeleteFolderMetadataByIdScope, templateKey, ); ``` ### Arguments folderId `string` - The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. Example: "12345" scope `DeleteFolderMetadataByIdScope` - The scope of the metadata template. Example: "global" templateKey `string` - The name of the metadata template. Example: "properties" optionalsInput `DeleteFolderMetadataByIdOptionalsInput` ### Returns This function returns a value of type `undefined`. Returns an empty response when the metadata is successfully deleted. --- ### FolderMetadataManager **Type:** page | **Section:** Additional Resources FolderMetadataManager List metadata instances on folder Get metadata instance on folder Create metadata instance on folder Update metadata… # FolderMetadataManager - [List metadata instances on folder](#list-metadata-instances-on-folder) - [Get metadata instance on folder](#get-metadata-instance-on-folder) - [Create metadata instance on folder](#create-metadata-instance-on-folder) - [Update metadata instance on folder](#update-metadata-instance-on-folder) - [Remove metadata instance from folder](#remove-metadata-instance-from-folder) ## List metadata instances on folder Retrieves all metadata for a given folder. This can not be used on the root folder with ID `0`. This operation is performed by calling function `get_folder_metadata`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-folders-id-metadata/). ``` client.folder_metadata.get_folder_metadata(folder.id) ``` ### Arguments folder_id `str` - The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. Example: "12345" extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `Metadatas`. Returns all the metadata associated with a folder. This API does not support pagination and will therefore always return all of the metadata associated to the folder. ## Get metadata instance on folder Retrieves the instance of a metadata template that has been applied to a folder. This can not be used on the root folder with ID `0`. This operation is performed by calling function `get_folder_metadata_by_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-folders-id-metadata-id-id/). ``` client.folder_metadata.get_folder_metadata_by_id( folder.id, GetFolderMetadataByIdScope.GLOBAL, "properties" ) ``` ### Arguments folder_id `str` - The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. Example: "12345" scope `GetFolderMetadataByIdScope` - The scope of the metadata template. Example: "global" template_key `str` - The name of the metadata template. Example: "properties" extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `MetadataFull`. An instance of the metadata template that includes additional "key:value" pairs defined by the user or an application. ## Create metadata instance on folder Applies an instance of a metadata template to a folder. In most cases only values that are present in the metadata template will be accepted, except for the `global.properties` template which accepts any key-value pair. To display the metadata template in the Box web app the enterprise needs to be configured to enable **Cascading Folder Level Metadata** for the user in the admin console. This operation is performed by calling function `create_folder_metadata_by_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-folders-id-metadata-id-id/). ``` client.folder_metadata.create_folder_metadata_by_id( folder.id, CreateFolderMetadataByIdScope.ENTERPRISE, template_key, { "name": "John", "age": 23, "birthDate": "2001-01-03T02:20:50.520Z", "countryCode": "US", "sports": ["basketball", "tennis"], }, ) ``` ### Arguments folder_id `str` - The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. Example: "12345" scope `CreateFolderMetadataByIdScope` - The scope of the metadata template. Example: "global" template_key `str` - The name of the metadata template. Example: "properties" request_body `Dict` - Request body of createFolderMetadataById method extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `MetadataFull`. Returns the instance of the template that was applied to the folder, including the data that was applied to the template. ## Update metadata instance on folder Updates a piece of metadata on a folder. The metadata instance can only be updated if the template has already been applied to the folder before. When editing metadata, only values that match the metadata template schema will be accepted. The update is applied atomically. If any errors occur during the application of the operations, the metadata instance will not be changed. This operation is performed by calling function `update_folder_metadata_by_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-folders-id-metadata-id-id/). ``` client.folder_metadata.update_folder_metadata_by_id( folder.id, UpdateFolderMetadataByIdScope.ENTERPRISE, template_key, [ UpdateFolderMetadataByIdRequestBody( op=UpdateFolderMetadataByIdRequestBodyOpField.REPLACE, path="/name", value="Jack", ), UpdateFolderMetadataByIdRequestBody( op=UpdateFolderMetadataByIdRequestBodyOpField.REPLACE, path="/age", value=24 ), UpdateFolderMetadataByIdRequestBody( op=UpdateFolderMetadataByIdRequestBodyOpField.REPLACE, path="/birthDate", value="2000-01-03T02:20:50.520Z", ), UpdateFolderMetadataByIdRequestBody( op=UpdateFolderMetadataByIdRequestBodyOpField.REPLACE, path="/countryCode", value="CA", ), UpdateFolderMetadataByIdRequestBody( op=UpdateFolderMetadataByIdRequestBodyOpField.REPLACE, path="/sports", value=["football"], ), ], ) ``` ### Arguments folder_id `str` - The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. Example: "12345" scope `UpdateFolderMetadataByIdScope` - The scope of the metadata template. Example: "global" template_key `str` - The name of the metadata template. Example: "properties" request_body `List[UpdateFolderMetadataByIdRequestBody]` - Request body of updateFolderMetadataById method extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `MetadataFull`. Returns the updated metadata template instance, with the custom template data included. ## Remove metadata instance from folder Deletes a piece of folder metadata. This operation is performed by calling function `delete_folder_metadata_by_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-folders-id-metadata-id-id/). ``` client.folder_metadata.delete_folder_metadata_by_id( folder.id, DeleteFolderMetadataByIdScope.ENTERPRISE, template_key ) ``` ### Arguments folder_id `str` - The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. Example: "12345" scope `DeleteFolderMetadataByIdScope` - The scope of the metadata template. Example: "global" template_key `str` - The name of the metadata template. Example: "properties" extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `None`. Returns an empty response when the metadata is successfully deleted. --- ### Folders **Type:** page | **Section:** Additional Resources Folders Folder objects represent a folder from a user's account. They can be used to iterate through a folder's contents, collaborate a… # Folders Folder objects represent a folder from a user's account. They can be used to iterate through a folder's contents, collaborate a folder with another user or group, and perform other common folder operations (move, copy, delete, etc.). [Folders](#folders) - [Get a Folder's Information](#get-a-folders-information) - [Get a Folder's Items](#get-a-folders-items) - [Update a Folder's Information](#update-a-folders-information) - [Create a Folder](#create-a-folder) - [Copy a Folder](#copy-a-folder) - [Move a Folder](#move-a-folder) - [Rename a Folder](#rename-a-folder) - [Delete a Folder](#delete-a-folder) - [Lock a folder](#lock-a-folder) - [Get All Locks on a Folder](#get-all-locks-on-a-folder) - [Delete a Lock on a Folder](#delete-a-lock-on-a-folder) - [Find a Folder for a Shared Link](#find-a-folder-for-a-shared-link) - [Ceate or update a Shared Link](#create-or-update-a-shared-link) - [Get a Shared Link](#get-a-shared-link) - [Remove a Shared Link](#remove-a-shared-link) ## Get a Folder's Information Folder information can be retrieved by calling the [`folders.get(folderID, options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Folders.html#get) method. Use the `fields` option to specify the desired fields. ``` client.folders.get('11111') .then(folder => { /* folder -> { type: 'folder', id: '11111', sequence_id: '1', etag: '1', name: 'Pictures', created_at: '2012-12-12T10:53:43-08:00', modified_at: '2012-12-12T11:15:04-08:00', description: 'Some pictures I took', size: 629644, path_collection: { total_count: 1, entries: [ { type: 'folder', id: '0', sequence_id: null, etag: null, name: 'All Files' } ] }, created_by: { type: 'user', id: '22222', name: 'Example User' login: 'user@example.com' }, modified_by: { type: 'user', id: '22222', name: 'Example User', login: 'user@example.com' }, owned_by: { type: 'user', id: '22222', name: 'Example User', login: 'user@example.com' }, shared_link: null, parent: { type: 'folder', id: '0', sequence_id: null, etag: null, name: 'All Files' }, item_status: 'active', item_collection: { total_count: 1, entries: [ { type: 'file', id: '33333', sequence_id: '3', etag: '3', sha1: '134b65991ed521fcfe4724b7d814ab8ded5185dc', name: 'tigers.jpeg' } ], offset: 0, limit: 100 } } */ }); ``` Requesting information for only the fields you need can improve performance and reduce the size of the network request. ``` client.folders.get( '12345', { fields: 'name,shared_link,permissions,collections,sync_state' } ).then(folder => { // ... }); ``` The user's root folder can be accessed by calling the [`folders.get(folderID, options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Folders.html#get) method with the `folderID` value of `'0'`. ``` client.folders.get('0') .then(rootFolder => { // ... }); ``` ## Get a Folder's Items Folder items can be retrieved by calling the [`folders.getItems(folderID, options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Folders.html#getItems) method. This method supports offset-based pagination and marker-based pagination. To use offset-based pagination, do not pass in the `usemarker` parameter or set it to `false`. To use marker-based pagination, pass in the `usemarker` parameter as `true`. Use the `fields` option to specify the desired fields, and `limit` and (`offset` or `marker`) to control result set paging. Requesting information for only the fields you need can improve performance by reducing the size of the network response. ``` client.folders.getItems( '12345', { usemarker: 'false', fields: 'name', offset: 0, limit: 25 }) .then(items => { /* items -> { total_count: 2, entries: [ { type: 'folder', id: '11111', sequence_id: '1', etag: '1', name: 'Personal Documents' }, { type: 'file', id: '22222', sequence_id: '0', etag: '0', name: 'Q2 Strategy.pptx' } ], offset: 0, limit: 25, order: [ { by: 'type', direction: 'ASC' }, { by: 'name', direction: 'ASC' } ] } */ }); ``` ## Update a Folder's Information Updating a folder's information is done by calling the [`folders.update(folderID, updates, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Folders.html#update) method. Use the `updates` parameter to specify the fields to update and their new values. ``` client.folders.update('11111', {name: 'Pictures from 2017'}) .then(updatedFolder => { /* updatedFolder -> { type: 'folder', id: '11111', sequence_id: '1', etag: '1', name: 'Pictures from 2017', created_at: '2012-12-12T10:53:43-08:00', modified_at: '2012-12-12T11:15:04-08:00', description: 'Some pictures I took', size: 629644, path_collection: { total_count: 1, entries: [ { type: 'folder', id: '0', sequence_id: null, etag: null, name: 'All Files' } ] }, created_by: { type: 'user', id: '22222', name: 'Example User' login: 'user@example.com' }, modified_by: { type: 'user', id: '22222', name: 'Example User', login: 'user@example.com' }, owned_by: { type: 'user', id: '22222', name: 'Example User', login: 'user@example.com' }, shared_link: null, parent: { type: 'folder', id: '0', sequence_id: null, etag: null, name: 'All Files' }, item_status: 'active', item_collection: { total_count: 1, entries: [ { type: 'file', id: '33333', sequence_id: '3', etag: '3', sha1: '134b65991ed521fcfe4724b7d814ab8ded5185dc', name: 'tigers.jpeg' } ], offset: 0, limit: 100 } } */ }); ``` If you want to ensure that your update does not overwrite any other updates (i.e. to prevent against possible race conditions), you can pass the last known value of the folder's `etag` field via the `etag` option; this will generate an error if the folder was modified between when you read that `etag` value and when your updates are processed by the API. ``` client.folders.update('22222', { name: 'Renamed Folder', etag: '5', fields: 'name' }) .then(updatedFolder => { /* updatedFolder -> { type: 'folder', id: '22222', sequence_id: '1', etag: '6', name: 'Renamed Folder' } */ }) .catch(err => { if (err.statusCode === 412) { // Precondition failed — the folder was modified before the update was processed // Read the folder again to ensure it is safe to update and then retry } }); ``` ## Create a Folder Create a child folder by calling the [`folders.create(parentFolderID, newFolderName, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Folders.html#create) method. ``` client.folders.create('0', 'New Folder') .then(folder => { /* folder -> { type: 'folder', id: '123456', sequence_id: '0', etag: '0', name: 'New Folder', created_at: '2012-12-12T10:53:43-08:00', modified_at: '2012-12-12T11:15:04-08:00', description: '', size: 0, path_collection: { total_count: 1, entries: [ { type: 'folder', id: '0', sequence_id: null, etag: null, name: 'All Files' } ] }, created_by: { type: 'user', id: '22222', name: 'Example User' login: 'user@example.com' }, modified_by: { type: 'user', id: '22222', name: 'Example User', login: 'user@example.com' }, owned_by: { type: 'user', id: '22222', name: 'Example User', login: 'user@example.com' }, shared_link: null, parent: { type: 'folder', id: '0', sequence_id: null, etag: null, name: 'All Files' }, item_status: 'active', item_collection: { total_count: 0, entries: [], offset: 0, limit: 100 } } */ }); ``` ## Copy a Folder Call the [`folders.copy(sourceFolderID, destinationFolderID, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Folders.html#copy) method to copy a folder into another folder. ``` client.folders.copy('11111', '22222') .then(folderCopy => { /* folderCopy -> { type: 'folder', id: '1234567', sequence_id: '0', etag: '0', name: 'Pictures from 2017', created_at: '2012-12-12T10:53:43-08:00', modified_at: '2012-12-12T11:15:04-08:00', description: 'Some pictures I took', size: 629644, path_collection: { total_count: 1, entries: [ { type: 'folder', id: '0', sequence_id: null, etag: null, name: 'All Files' }, { type: 'folder', id: '22222', sequence_id: '3', etag: '3', name: 'Archives' } ] }, created_by: { type: 'user', id: '22222', name: 'Example User' login: 'user@example.com' }, modified_by: { type: 'user', id: '22222', name: 'Example User', login: 'user@example.com' }, owned_by: { type: 'user', id: '22222', name: 'Example User', login: 'user@example.com' }, shared_link: null, parent: { type: 'folder', id: '22222', sequence_id: '3', etag: '3', name: 'Archives' }, item_status: 'active', item_collection: { total_count: 1, entries: [ { type: 'file', id: '44444', sequence_id: '0', etag: '0', sha1: '134b65991ed521fcfe4724b7d814ab8ded5185dc', name: 'tigers.jpeg' } ], offset: 0, limit: 100 } } */ }); ``` An optional `name` parameter can also be passed to rename the folder on copy. This can be used to avoid a name conflict when there is already an item with the same name in the target folder. ``` client.folders.copy('12345', '0', {name: 'Renamed folder'}) .then(folderCopy => { // ... }); ``` ## Move a Folder Call the [`folders.move(sourceFolderID, destinationFolderID, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Folders.html#move) method with the destination you want the folder moved to. ``` var folderID = '11111'; var destinationFolderID = '22222'; client.folders.move(folderID, destinationfolderID) .then(folder => { /* folder -> { type: 'folder', id: '11111', sequence_id: '1', etag: '1', name: 'Pictures from 2017', created_at: '2012-12-12T10:53:43-08:00', modified_at: '2012-12-12T11:15:04-08:00', description: 'Some pictures I took', size: 629644, path_collection: { total_count: 1, entries: [ { type: 'folder', id: '0', sequence_id: null, etag: null, name: 'All Files' }, { type: 'folder', id: '22222', sequence_id: '3', etag: '3', name: 'Archives' } ] }, created_by: { type: 'user', id: '22222', name: 'Example User' login: 'user@example.com' }, modified_by: { type: 'user', id: '22222', name: 'Example User', login: 'user@example.com' }, owned_by: { type: 'user', id: '22222', name: 'Example User', login: 'user@example.com' }, shared_link: null, parent: { type: 'folder', id: '22222', sequence_id: '3', etag: '3', name: 'Archives' }, item_status: 'active', item_collection: { total_count: 1, entries: [ { type: 'file', id: '33333', sequence_id: '3', etag: '3', sha1: '134b65991ed521fcfe4724b7d814ab8ded5185dc', name: 'tigers.jpeg' } ], offset: 0, limit: 100 } } */ }); ``` ## Rename a Folder Use the [`folders.update(folderID, updates, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Folders.html#update) method to rename a folder by passing a new name for the folder in `updates.name`. ``` client.folders.update('12345', {name: 'New Name'}, callback); ``` ## Delete a Folder A folder can be deleted with the [`folders.delete(folderID, options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Folders.html#delete) method. ``` client.folders.delete('12345', {recursive: true}) .then(() => { // deletion succeeded — no value returned }); ``` ## Lock a Folder Use the [`folders.lock(folderID, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Folders.html#lock) to lock a folder ``` var folderID = '11111'; client.folders.lock(folderID) .then(folderLock => { /* folderLock -> { "id": "12345678", "type": "folder_lock", "created_at": "2020-09-14T23:12:53Z", "created_by": { "id": "11446498", "type": "user" }, "folder": { "id": "12345", "type": "folder", "etag": "1", "name": "Contracts", "sequence_id": "3" }, "lock_type": "freeze", "locked_operations": { "delete": true, "move": true } } */ }); ``` ## Get All Locks on a Folder Use the [`folders.getLocks(folderID, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Folders.html#lock) to get all locks on a folder. ``` var folderID = '11111'; client.folders.getLocks(folderID) .then(folderLocks => { /* folderLocks -> { "entries": [ { "folder": { "id": "12345", "etag": "1", "type": "folder", "sequence_id": "3", "name": "Contracts" }, "id": "12345678", "type": "folder_lock", "created_by": { "id": "11446498", "type": "user" }, "created_at": "2020-09-14T23:12:53Z", "locked_operations": { "move": true, "delete": true }, "lock_type": "freeze" } ], "limit": 1000, "next_marker": null } */ }); ``` ## Delete a Lock on a Folder Use the [`folders.deleteLock(folderLockID, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Folders.html#deleteLock) method to delete a folder lock. ``` var folderLockID = '12345'; client.folders.deleteLock(folderLockID) .then(() => { // deletion succeeded — no value returned }); ``` ## Find a Folder for a Shared Link To find a folder given a shared link, use the [`sharedItems.get(url, password, options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/SharedItems.html#get) method. ``` client.sharedItems.get( 'https://app.box.com/s/gjasdasjhasd', 'letmein' ),then(folder => { //... }); ``` ## Create or update a Shared Link To create or update a shared link for a file use [`folders.update(folderID, updates, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Folders.html#update) method, passing a new `shared_link` value in the `updates` parameter. ``` client.folders.update('12345', { shared_link: { access: "open", password: "do-not-use-this-password", unshared_at: "2022-12-12T10:53:43-08:00", vanity_name: "my-shared-link", permissions: { can_view: true, can_download: true } } }).then(folder => { // ... }) ``` This will make a shared link to be `open` to everyone, but users will need to provide `password` to access the folder. This link will be unshared at `"2022-12-12T10:53:43-08:00"`. By setting `vanity_name` we create custom URL `https://app.box.com/v/my-shared-link`. Custom URLs should not be used when sharing sensitive content as vanity URLs are a lot easier to guess than regular shared links. Additionally, everyone who has this link can `view` and `download` the folder. You can create shared link using default values ``` client.folders.update('12345', { shared_link: {} }).then(folder => { // ... }) ``` - Default `access` value comes from the access level specified by the enterprise admin. - Default `password`, `unshared_at`, `vanity_name` will be empty. - Default `permissions` allows to view and download folder. You can remove any field set on a link by sending value `null` (or empty object when it comes to `permissions`). This will cause it's value to be default. For example, let's remove `access` and `permissions`: ``` client.folders.update('12345', { shared_link: { access: null, permissions: {} } }).then(folder => { // ... }) ``` This will remove `open` access, and it will fall back to default value set by the enterprise admin. The `permissions` we set on a shared link will be removed and default permissions will be applied. Other properties of the shared link will not be changed as we are not sending them. ## Get a Shared Link To check for an existing shared link on a folder, inspect the `shared_link` field on a folder object. This object, when present, contains a `unicode` string containing the shared link URL. ``` client.folders.get('11111', { fields: 'shared_link' }) .then(folder => { let url = folder.shared_link.url //... }) ``` ## Remove a Shared Link A shared link for a folder can be removed calling [`folders.update(folderID, updates, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Folders.html#update) with `null` for the `shared_link` value. ``` client.folders.update('12345', { shared_link: null }).then(folder => { // ... }) ``` --- ### Folders **Type:** page | **Section:** Additional Resources Folders Folder objects represent a folder from a user's account. They can be used to iterate through a folder's contents, collaborate a… # Folders Folder objects represent a folder from a user's account. They can be used to iterate through a folder's contents, collaborate a folder with another user or group, and perform other common folder operations (move, copy, delete, etc.). - [Get the User's Root Folder](#get-the-users-root-folder) [Get a Folder's Items](#get-a-folders-items) - [SortParameters and Using PagingParameters](#sortparameters-and-using-pagingparameters) [Get a Folder's Information](#get-a-folders-information) [Update a Folder's Information](#update-a-folders-information) [Create a Folder](#create-a-folder) [Copy a Folder](#copy-a-folder) [Move a Folder](#move-a-folder) [Rename a Folder](#rename-a-folder) [Delete a Folder](#delete-a-folder) [Find Folder for Shared Link](#find-folder-for-shared-link) [Create a Shared Link](#create-a-shared-link) [Get a Shared Link](#get-a-shared-link) [Update a Shared Link](#update-a-shared-link) [Remove a Shared Link](#remove-a-shared-link) [Share a Folder](#share-a-folder) [Get All Collaborations for a Folder](#get-all-collaborations-for-a-folder) [Create Metadata](#create-metadata) [Set Metadata](#set-metadata) [Get Metadata](#get-metadata) [Update Metadata](#update-metadata) [Delete Metadata](#delete-metadata) [Get All Metadata on Folder](#get-all-metadata-on-folder) [Get Metadata for Multiple Files](#get-metadata-for-multiple-files) [Set Classification on Folder](#set-classification-on-folder) [Get Classification on Folder](#get-classification-on-folder) [Remove Classification on Folder](#remove-classification-on-folder) [Create Cascade Policy On Folder](#create-cascade-policy-on-folder) [Get a Cascade Policy's Information](#get-a-cascade-policys-information) [Get All Cascade Policies on Folder](#get-all-cascade-policies-on-folder) [Force Apply Cascade Policy on Folder](#force-apply-cascade-policy-on-folder) [Delete Cascade Policy](#delete-cascade-policy) [Lock a Folder](#lock-a-folder) [Get All Locks on a Folder](#get-all-locks-on-a-folder) [Delete a Lock on a Folder](#delete-a-lock-on-a-folder) ## Get the User's Root Folder The user's root folder can be accessed with the static [`getRootFolder(BoxAPIConnection api)`](https://box.github.io/box-java-sdk/javadoc/com/box/sdk/BoxFolder.html#getRootFolder-com.box.sdk.BoxAPIConnection-) method. ``` BoxFolder rootFolder = BoxFolder.getRootFolder(api); ``` ## Get a Folder's Items Every `BoxFolder` implements [`Iterable<BoxItem>`](https://box.github.io/box-java-sdk/javadoc/com/box/sdk/BoxFolder.html#iterator--) which allows you to iterate over the folder's contents. The iterator automatically handles paging and will make additional API calls to load more data when necessary. ``` BoxFolder folder = new BoxFolder(api, "id"); for (BoxItem.Info itemInfo : folder) { if (itemInfo instanceof BoxFile.Info) { BoxFile.Info fileInfo = (BoxFile.Info) itemInfo; // Do something with the file. } else if (itemInfo instanceof BoxFolder.Info) { BoxFolder.Info folderInfo = (BoxFolder.Info) itemInfo; // Do something with the folder. } } ``` `BoxFolder` purposely doesn't provide a way of getting a collection of `BoxItems`. Getting the entire contents of a folder is usually unnecessary and can be extremely inefficient for folders with a large number of items. If you really require a collection instead of an iterable, you can create the collection manually. ``` Collection<BoxItem> folderItems = new ArrayList<BoxItem>(); BoxFolder folder = new BoxFolder(api, "id"); for (BoxItem.Info itemInfo : folder) { folderItems.add(itemInfo.getResource()); } ``` We also allow users to sort the results of the folder items by `name`, `id`, or `date`. This will maintain the integrity of the ordering when you retrieve the items for a folder. You can do this by calling the [`getChildren(String sortField, BoxFolder.SortDirection sortDirection, String... fields)`](https://box.github.io/box-java-sdk/javadoc/com/box/sdk/BoxFolder.html#getChildren-java.lang.String-com.box.sdk.BoxFolder.SortDirection-java.lang.String...-) method. ``` BoxFolder folder = new BoxFolder(this.api, "12345"); Iterator<BoxItem.Info> itemIterator = folder.getChildren("name", BoxFolder.SortDirection.ASC).iterator(); while (itemIterator.hasNext()) { BoxItem.Info itemInfo = itemIterator.next(); // Do something } ``` ### SortParameters and Using PagingParameters `SortParameters` is an abstraction hiding way that SDK is doing sorting. `PagingParameters` is an abstraction hiding way that SDK is doing pagination. If you want to start offset based pagination: ``` BoxFolder folder = new BoxFolder(this.api, "12345"); // setup ascending sorting by name SortParameters sorting = SortParameters.ascending("name"); // setup paging with offset 0 and limit 100 long offset = 0; long limit = 100; PagingParameters paging = PagingParameters.offset(offset, limit) Iterable<BoxItem.Info> itemIterator = childFolder.getChildren(sorting, paging); while (itemIterator.hasNext()) { BoxItem.Info itemInfo=itemIterator.next(); // Do something } ``` With offset pagination you cannot set offset larger than 300000. With marker based pagination you can iterate over folders containing more than 300000 elements. With marker based pagination you cannot use sorting. Use `SortParameters.none()` to turn off sort. If you want to use PagingParameters to start marker based pagination do: ``` BoxFolder folder = new BoxFolder(this.api, "12345"); // disable sorting SortParameters sorting = SortParameters.none(); // setup paging with makred based pagination and limit 100 long limit = 100; PagingParameters paging = PagingParameters.marker(limit) Iterable<BoxItem.Info> itemIterator = childFolder.getChildren(sorting, paging); while (itemIterator.hasNext()) { BoxItem.Info itemInfo=itemIterator.next(); // Do something } ``` ## Get a Folder's Information Calling [`getInfo()`](https://box.github.io/box-java-sdk/javadoc/com/box/sdk/BoxFolder.html#getInfo-java.lang.String...-) on a folder returns a snapshot of the folder's info. ``` BoxFolder folder = new BoxFolder(api, "id"); BoxFolder.Info info = folder.getInfo(); ``` Requesting information for only the fields you need can improve performance and reduce the size of the network request. The [`getInfo(String... fields)`](https://box.github.io/box-java-sdk/javadoc/com/box/sdk/BoxFolder.html#getInfo-java.lang.String...-) method lets you specify which fields are retrieved. ``` BoxFolder folder = new BoxFolder(api, "id"); // Only get information about a few specific fields. BoxFolder.Info info = folder.getInfo("size", "owned_by"); ``` ## Update a Folder's Information Updating a folder's information is done by creating a new `BoxFolder.Info` object or updating an existing one, and then calling [`updateInfo(BoxFolder.Info fieldsToUpdate)`](https://box.github.io/box-java-sdk/javadoc/com/box/sdk/BoxFolder.html#updateInfo-com.box.sdk.BoxFolder.Info-). ``` BoxFolder folder = new BoxFolder(api, "id"); BoxFolder.Info info = folder.new Info(); info.setName("New Name"); folder.updateInfo(info); ``` ## Create a Folder Create a child folder by calling [`createFolder(String folderName)`](https://box.github.io/box-java-sdk/javadoc/com/box/sdk/BoxFolder.html#createFolder-java.lang.String-) on the parent folder. ``` BoxFolder parentFolder = new BoxFolder(api, "id"); BoxFolder.Info childFolderInfo = parentFolder.createFolder("Child Folder Name"); ``` ## Copy a Folder Call the [`copy(BoxFolder destination)`](https://box.github.io/box-java-sdk/javadoc/com/box/sdk/BoxFolder.html#copy-com.box.sdk.BoxFolder-) method to copy a folder to another folder. ``` BoxFolder folder = new BoxFolder(api, "id1"); BoxFolder destination = new BoxFolder(api, "id2"); folder.copy(destination); ``` You can also use the [`copy(BoxFolder destination, String newName)`](https://box.github.io/box-java-sdk/javadoc/com/box/sdk/BoxFolder.html#copy-com.box.sdk.BoxFolder-java.lang.String-) method to rename the folder while copying it. This allows you to make a copy of the folder in the same parent folder, but with a different name. ``` BoxFolder folder = new BoxFolder(api, "id1"); BoxFolder.Info parentFolderInfo = folder.getInfo().getParent(); BoxFolder parentFolder = parentFolderInfo.getResource(); folder.copy(parentFolder, "New Name"); ``` ## Move a Folder Call the [`move(BoxFolder destination)`](https://box.github.io/box-java-sdk/javadoc/com/box/sdk/BoxFolder.html#move-com.box.sdk.BoxFolder-) method with the destination you want the folder moved to. ``` BoxFolder folder = new BoxFolder(api, "id1"); BoxFolder destination = new BoxFolder(api, "id2"); folder.move(destination); ``` ## Rename a Folder Call the [`rename(String newName)`](https://box.github.io/box-java-sdk/javadoc/com/box/sdk/BoxFolder.html#rename-java.lang.String-) method with a new name for the folder. ``` BoxFolder folder = new BoxFolder(api, "id"); folder.rename("New Name"); ``` A folder can also be renamed by updating the folder's information. This is useful if you want to perform more than one change to the folder in a single API request. ``` BoxFolder folder = new BoxFolder(api, "id"); BoxFolder.Info info = folder.new Info(); info.setName("New Name"); folder.updateInfo(info); ``` ## Delete a Folder A folder can be deleted with the [`delete(boolean recursive)`](https://box.github.io/box-java-sdk/javadoc/com/box/sdk/BoxFolder.html#delete-boolean-) method. Passing `true` to this method indicates that the folder and its contents should be recursively deleted. ``` // Delete the folder and all its contents BoxFolder folder = new BoxFolder(api, "id"); folder.delete(true); ``` ## Find Folder for Shared Link To get the folder information for a shared link, you can call [`BoxItem.getSharedItem(BoxAPIConnection api, String sharedLink)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxItem.html#getSharedItem-com.box.sdk.BoxAPIConnection-java.lang.String-) with the shared link to get information about the folder behind it. ``` String sharedLink = "https://app.box.com/s/abcdefghijklmnopqrstuvwxyz123456"; BoxItem.Info itemInfo = BoxItem.getSharedItem(api, sharedLink); ``` If the shared link is password-protected, call [`BoxItem.getSharedItem(BoxAPIConnection api, String sharedLink, String password)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxItem.html#getSharedItem-com.box.sdk.BoxAPIConnection-java.lang.String-java.lang.String-) with the shared link and password. ``` String sharedLink = "https://app.box.com/s/abcdefghijklmnopqrstuvwxyz123456"; String password = "letmein"; BoxItem.Info itemInfo = BoxItem.getSharedItem(api, sharedLink, password); ``` ## Create a Shared Link A shared link for a folder can be generated by calling [`createSharedLink(BoxSharedLinkRequest sharedLinkRequest)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFolder.html#createSharedLink-com.box.sdk.sharedlink.BoxSharedLinkRequest-). ``` // Optionally we can calculate and set the date when shared link will automatically be disabled final long ONE_WEEK_MILLIS = 1000 * 60 * 60 * 24 * 7; long unsharedTimestamp = System.currentTimeMillis() + ONE_WEEK_MILLIS; Date unsharedDate = new Date(unsharedTimestamp); BoxFolder folder = new BoxFolder(api, "id"); BoxSharedLinkRequest sharedLinkRequest = new BoxSharedLinkRequest() .access(OPEN) .permissions(true, true) .unsharedDate(unsharedDate); BoxSharedLink sharedLink = folder.createSharedLink(sharedLinkRequest); ``` A set of shared link access level constants are available through the SDK for convenience: - `BoxSharedLink.Access.OPEN` - `BoxSharedLink.Access.COLLABORATORS` - `BoxSharedLink.Access.COMPANY` - `BoxSharedLink.Access.DEFAULT` ## Get a Shared Link Retrieve the shared link for a folder by calling [`getSharedLink()`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxItem.Info.html#getSharedLink--). ``` BoxFolder folder = new BoxFolder(api, "id"); BoxFolder.Info info = folder.getInfo() BoxSharedLink link = info.getSharedLink() String url = link.getUrl() ``` ## Update a Shared Link A shared link for a folder can be updated by calling the same method as used when creating a shared link, [`createSharedLink(BoxSharedLinkRequest sharedLinkRequest)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFolder.html#createSharedLink-com.box.sdk.sharedlink.BoxSharedLinkRequest-). ``` BoxFolder folder = new BoxFolder(api, "id"); BoxSharedLinkRequest sharedLinkRequest = new BoxSharedLinkRequest() .access(OPEN) .permissions(true, true); BoxSharedLink sharedLink = folder.createSharedLink(sharedLinkRequest); ``` ## Remove a Shared Link A shared link for a folder can be removed by calling [`removeSharedLink()`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFolder.html#removeSharedLink--). ``` BoxFolder folder = new BoxFolder(api, "12345"); BoxFolder.Info info = folder.getInfo(); info.removeSharedLink(); folder.updateInfo(info); ``` ## Share a Folder You can invite another person to collaborate on a folder with the [`collaborate(String emailAddress, BoxCollaboration.Role role)`](https://box.github.io/box-java-sdk/javadoc/com/box/sdk/BoxFolder.html#collaborate-java.lang.String-com.box.sdk.BoxCollaboration.Role-) method. ``` BoxFolder folder = new BoxFolder(api, "id"); BoxCollaboration.Info collabInfo = folder.collaborate("gcurtis@box.com", BoxCollaboration.Role.EDITOR); ``` If you already know the user's ID, you can invite them directly without needing to know their email address with the [`collaborate(BoxCollaborator user, BoxCollaboration.Role role)`](https://box.github.io/box-java-sdk/javadoc/com/box/sdk/BoxFolder.html#collaborate-com.box.sdk.BoxCollaborator-com.box.sdk.BoxCollaboration.Role-) method. ``` BoxUser collaborator = new User(api, "user-id"); BoxFolder folder = new BoxFolder(api, "folder-id"); BoxCollaboration.Info collabInfo = folder.collaborate(collaborator, BoxCollaboration.Role.EDITOR); ``` You can also create a collaboration with all properties set at once by using the [`collaborate(BoxCollaborator user, BoxCollaboration.Role role, Boolean notify, Boolean canViewPath, Date expiresAt, Boolean isAccessOnly)`](https://box.github.io/box-java-sdk/javadoc/com/box/sdk/BoxFolder.html#collaborate-com.box.sdk.BoxCollaborator-com.box.sdk.BoxCollaboration.Role-java.lang.Boolean-java.lang.Boolean-java.util.Date-java.lang.Boolean-) method. The `notify` parameter will determine if the user or group will receive an email notification when being added as a collaborator. This option is only available to enterprise administrators. The `canViewPath` parameter allows the invitee to see the entire list of ancestor folders of the associated file. The user will not gain privileges in any ancestor folder, but will be able to see the whole path to that file in the owner's account. The `expiresAt` parameter allows the owner to set a date-time in the future when the collaboration should expire. The `isAccessOnly` parameter allows the owner to set the collaboration to be access only collaboration. The `notify`, `canViewPath`, `expiresAt` and `isAccessOnly` parameters can be left as `null`. ## Get All Collaborations for a Folder The [`getCollaborations()`](https://box.github.io/box-java-sdk/javadoc/com/box/sdk/BoxFolder.html#getCollaborations--) method will return a collection of `BoxCollaboration.Info` objects for a folder. ``` BoxFolder folder = new BoxFolder(api, "id"); Collection<BoxCollaboration.Info> collaborations = folder.getCollaborations(); ``` ## Create Metadata Metadata can be created on a folder by calling [`createMetadata(Metadata metadata)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFolder.html#createMetadata-com.box.sdk.Metadata-), [`createMetadata(String templateName, Metadata metadata)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFolder.html#createMetadata-java.lang.String-com.box.sdk.Metadata-), or [`createMetadata(String templateName, String scope, Metadata metadata)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFolder.html#createMetadata-java.lang.String-java.lang.String-com.box.sdk.Metadata-) ``` BoxFolder folder = new BoxFolder(api, "id"); folder.createMetadata(new Metadata().add("/foo", "bar")); ``` Note: This method will only succeed if the provided metadata template is not currently applied to the folder, otherwise it will fail with a Conflict error. To get to know how to edit existing metadata please go to [set metadata](#set-metadata) and [update metadata](#update-metadata) sections. ## Set Metadata To set metadata on a folder, call [`setMetadata(String templateName, String scope, Metadata metadata)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFolder.html#setMetadata-java.lang.String-java.lang.String-com.box.sdk.Metadata-). This method will try to create provided metadata on a folder. However, if metadata has already been applied to this folder, it will overwrite values of metadata keys specified in the `metadata` parameter. The metadata keys not specified in the `metadata` parameter will remain unchanged. ``` BoxFolder folder = new BoxFolder(api, "id"); folder.setMetadata("test_template", "enterprise", new Metadata().add("/foo", "bar")); ``` Note: If you want to set new metadata on a folder including hard reset of the current metadata (also removing keys not specified in the `metadata` param): first delete metadata as specified in [delete metadata](#delete-metadata) section and then set new metadata again. ## Get Metadata Retrieve a folder's metadata by calling [`getMetadata()`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFolder.html#getMetadata--), [`getMetadata(String templateName)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFolder.html#getMetadata-java.lang.String-), or [`getMetadata(String templateName, String scope)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFolder.html#getMetadata-java.lang.String-java.lang.String-). These methods return a [`Metadata`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/Metadata.html) object, which allows access to metadata values. ``` BoxFolder folder = new BoxFolder(api, "id"); Metadata metadata = folder.getMetadata(); // Unknown type metadata field, you can test for type or try to get as any type JsonValue unknownValue = metadata.getValue("/someField"); // String or Enum metadata fields String stringValue = metadata.getString("/author"); // Float metadata fields can be interpreted as any numeric type float floatValue = metadata.getFloat("/price"); // Date metadata fields Date dateValue = metadata.getDate("/deadline"); ``` ## Update Metadata Update a folder's metadata by calling [`updateMetadata(Metadata properties)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFolder.html#updateMetadata-com.box.sdk.Metadata-). Note: This method will only succeed if the provided metadata template has already been applied to the folder. If the folder does not have existing metadata, this method will fail with a Not Found error. This is useful in cases where you know the folder will already have metadata applied, since it will save an API call compared to `setMetadata()`. ``` BoxFolder folder = new BoxFolder(api, "id"); folder.updateMetadata(new Metadata().add("/foo", "bar")); ``` Also, it is possible to add multi-select fields for your folder metadata by calling [`updateMetadata(Metadata properties)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFolder.html#updateMetadata-com.box.sdk.Metadata-) with a list of values. ``` BoxFolder folder = new BoxFolder(api, "id"); List<String> valueList = new ArrayList<String>(); valueList.add("bar"); valueList.add("qux"); folder.updateMetadata(new Metadata().add("/foo", valueList)); ``` If you wanted to replace all selected fields for a specified key you can use the [`replace(String key, List<String> values)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/Metadata.html#replace-java.lang.String-java.util.List-). ``` BoxFolder folder = new BoxFolder(api, "id"); List<String> valueList = new ArrayList<String>(); valueList.add("bar"); valueList.add("qux"); folder.updateMetadata(new Metadata().replace("/foo", valueList)); ``` ## Delete Metadata A folder's metadata can be deleted by calling [`deleteMetadata()`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFolder.html#deleteMetadata--), [`deleteMetadata(String templateName)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFolder.html#deleteMetadata-java.lang.String-), or [`deleteMetadata(String templateName, String scope)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFolder.html#deleteMetadata-java.lang.String-java.lang.String-). ``` BoxFolder folder = new BoxFolder(api, "id"); folder.deleteMetadata("myMetadataTemplate"); ``` ## Get All Metadata on Folder [`getAllMetadata()`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFolder.html#getAllMetadata-java.lang.String...-) method will return an iterable that will page through all of the metadata associated with the folder. ``` BoxFolder file = new BoxFolder(api, "id"); Iterable<Metadata> metadataList = folder.getAllMetadata(); for (Metadata metadata : metadataList) { // Do something with the metadata. } ``` ## Get Metadata for Multiple Files When fetching a large number of items, for example the items in a folder, it would often be impractical to fetch the metadata for each of those items individually. Instead, you can get the metadata for all of the items in a single API call by requesting the `metadata` field on those items: **Note:** The field name should have the form `metadata.<templateScope>.<templateKey>` ``` BoxFolder root = BoxFolder.getRootFolder(); Iterable<BoxItem.Info> itemsInFolder = root.getChildren("metadata.global.properties") for (BoxItem.Info itemInfo : itemsInFolder) { if (itemInfo instanceof BoxFile.Info) { BoxFile.Info fileInfo = (BoxFile.Info) itemInfo; Metadata itemMetadata = fileInfo.getMetadata("properties", "global"); } else if (itemInfo instanceof BoxFolder.Info) { BoxFolder.Info folderInfo = (BoxFolder.Info) itemInfo; Metadata itemMetadata = folderInfo.getMetadata("properties", "global"); } } ``` ## Set Classification on Folder Calling the [`setClassification(String classificationType)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFolder.html#setClassification-java.lang.String...-) method on a folder will add a classification template on the folder. This method will return the classification type applied on the folder. The classification types include `Public`, `Internal`, and `Confidential`. `Public` being the most available permission, `Internal` which restricts the specified file to company and collaborators only, and finally, `Confidential`, which is for collaborators only. ``` BoxFolder folder = new BoxFolder(api, "id"); String classificationType = folder.setClassification("Public"); ``` It is important to note that this call will attempt to create a classification on the folder first, if one already exists then it will do the update. If you already know that a classification exists on the folder and would like to save an API call, we encourage you to use the [`updateClassification(String classificationType)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFolder.html#updateClassification-java.lang.String...-) method. ``` BoxFolder folder = new BoxFolder(api, "id"); String classificationType = folder.updateClassification("Public"); ``` ## Get Classification on Folder To retrieve the classification assigned on the folder, use the [`getClassification()`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFolder.html#getClassification-java.lang.String...-) method. This will return the classification type on the folder. ``` BoxFolder folder = new BoxFolder(api, "id"); String classificationType = folder.getClassification(); ``` ## Remove Classification on Folder To remove classification from the folder, use the [`deleteClassification()`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFolder.html#deleteClassification--) method. ``` BoxFolder folder = new BoxFolder(api, "id"); folder.deleteClassification(); ``` ## Create Cascade Policy On Folder To set a metadata policy, which applies metadata values on a folder to new items in the folder, call [`BoxFolder.addMetadataCascadePolicy(String scope, String template)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFolder.html#addMetadataCascadePolicy-java.lang.String-java.lang.String-). ``` String scope = "global"; String templateKey = "template"; String folderId = "12345"; BoxFolder folder = new BoxFolder(api, folderId); BoxMetadataCascadePolicy.Info cascadePolicyInfo = folder.addMetadataCascadePolicy(scope, template); ``` ## Get a Cascade Policy's Information To retrieve information about a specific metadata cascade policy, call [`getInfo()`](https://box.github.io/box-java-sdk/javadoc/com/box/sdk/BoxFolder.html#getInfo-java.lang.String...-) ``` String cascadePolicyID = "1234"; BoxMetadataCascadePolicy metadataCascadePolicy = new BoxMetadataCascadePolicy(api, cascadePolicyID); BoxMetadataCascadePolicy.Info metadataCascadePolicyInfo = metadataCascadePolicy.getInfo(); ``` ## Get All Cascade Policies on Folder To get a list of all cascade policies on a folder, which show the metadata templates that are being applied to all items in the folder, call [`getMetadataCascadePolicies()`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFolder.html#getMetadataCascadePolicies--) on that folder. ``` String folderID = "2222"; BoxFolder folder = new BoxFolder(api, folderID); Iterable<BoxMetadataCascadePolicy.Info> metadataCascadePolicies = folder.getMetadataCascadePolicies(); for (BoxMetadataCascadePolicy.Info policyInfo : metadataCascadePolicies) { // take action on policy here } ``` You can also call [`getMetadataCascadePolicies(String enterpriseID, int limit, String... fields)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFolder.html#getMetadataCascadePolicies-java.lang.String-int-) and set the `enterpriseID` option to retrieve metadata cascade policies from another enterprise. ``` String folderID = "2222"; String enterpriseID = "3333"; int limit = 50; BoxFolder folder = new BoxFolder(api, folderID); Iterable<BoxMetadataCascadePolicy.Info> metadataCascadePolicies = folder.getMetadataCascadePolicies(enterpriseID, limit); for (BoxMetadataCascadePolicy.Info policyInfo : metadataCascadePolicies) { // take action on policy here } ``` ## Force Apply Cascade Policy on Folder To force apply a metadata template policy and apply metadata values to all existing items in an affected folder, call [`forceApply(String conflictResolution)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxMetadataCascadePolicy.html#forceApply-java.lang.String-) with the conflict resolution method for dealing with items that already have a metadata value that conflicts with the folder. Specifying a resolution value of `none` will preserve the existing values on items, and specifying `overwrite` will overwrite values on items in the folder with the metadata value from the folder. ``` String cascadePolicyID = "e4392a41-7de5-4232-bdf7-15e0d6bba067"; BoxMetadataCascadePolicy policy = new BoxMetadataCascadePolicy(api, cascadePolicyID); policy.forceApply("none"); ``` ## Delete Cascade Policy To remove a cascade policy and stop applying metadata from a folder to items in the folder, call [`delete()`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxMetadataCascadePolicy.html#delete--). ``` String cascadePolicyID = "e4392a41-7de5-4232-bdf7-15e0d6bba067"; BoxMetadataCascadePolicy policyToDelete = new BoxMetadataCascadePolicy(api, cascadePolicyID); policyToDelete.delete(); ``` ## Lock a Folder To lock a folder and prevent it from being moved and/or deleted, call [`lock()`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFolder.html#lock--) on a folder. ``` BoxFolder folder = new BoxFolder(api, "id"); FolderLock.Info folderLock = folder.lock(); ``` ## Get All Locks on a Folder To get all locks on a folder, call [`getlock()`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFolder.html#getLocks--) on folder. ``` BoxFolder folder = new BoxFolder(this.api, "id"); Iterable<BoxFolderLock.Info> locks = folder.getLocks(); for (BoxFolderLock.Info lockInfo : locks) { // Do something with each lockInfo here } ``` ## Delete a Lock on a Folder To delete a lock on a folder, call [`delete()`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFolderLock.html#delete--) on a BoxFolderLock object. This cannot be called on a BoxFolder object. ``` BoxFolderLock folderLock = new BoxFolderLock(this.api, "folderLockID"); folderLock.delete(); ``` --- ### Folders **Type:** page | **Section:** Additional Resources Folders Folder objects represent a folder from a user's account. They can be used to iterate through a folder's contents, collaborate a… # Folders Folder objects represent a folder from a user's account. They can be used to iterate through a folder's contents, collaborate a folder with another user or group, and perform other common folder operations (move, copy, delete, etc.). - [Get Information About a Folder](#get-information-about-a-folder) - [Get the User's Root Folder](#get-the-users-root-folder) - [Get the Items in a Folder](#get-the-items-in-a-folder) - [Update a Folder](#update-a-folder) - [Create a Folder](#create-a-folder) - [Copy a Folder](#copy-a-folder) - [Move a Folder](#move-a-folder) - [Rename a File](#rename-a-file) - [Delete a Folder](#delete-a-folder) - [Find a Folder for a Shared Link](#find-a-folder-for-a-shared-link) - [Create or update a Shared Link](#create-or-update-a-shared-link) - [Get a Shared Link](#get-a-shared-link) - [Remove a Shared Link](#remove-a-shared-link) - [Set Metadata](#set-metadata) - [Get Metadata](#get-metadata) - [Remove Metadata](#remove-metadata) - [Get All Metadata](#get-all-metadata) - [Get Metadata For Folder Items](#get-metadata-for-folder-items) - [Set a Classification](#set-a-classification) - [Retrieve a Classification](#retrieve-a-classification) - [Remove a Classification](#remove-a-classification) - [Create a Folder Lock](#create-a-folder-lock) - [Get Folder Locks](#get-folder-locks) - [Delete a Folder Lock](#delete-a-folder-lock) ## Get Information About a Folder To retrieve information about a folder, first call [`client.folder(folder_id)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.client.html#boxsdk.client.client.Client.folder) to initialize the [`Folder`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.folder.Folder) object. Then, call [`folder.get(*, fields=None, etag=None, **kwargs)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.item.Item.get) to retrieve data about the folder. This method returns a new [`Folder](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.folder.Folder) object with fields populated by data from the API, leaving the original object unmodified. You can pass a list of `fields` to retrieve from the API in order to filter to just the necessary fields or add ones not returned by default. ``` folder = client.folder(folder_id='22222').get() print(f'Folder "{folder.name}" has {folder.item_collection["total_count"]} items in it') ``` ## Get the User's Root Folder To get the current user's root folder, call [`client.root_folder()`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.client.html#boxsdk.client.client.Client.root_folder) to initialize the appropriate [`Folder`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.folder.Folder) object. ``` root_folder = client.root_folder().get() ``` ## Get the Items in a Folder To retrieve the items in a folder, call [`folder.get_items(limit=None, offset=0, marker=None, use_marker=False, sort=None, direction=None, fields=None)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.folder.Folder.get_items). This method returns a `BoxObjectCollection` that allows you to iterate over all the [`Item`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.item.Item) objects in the collection. ``` items = client.folder(folder_id='22222').get_items() for item in items: print(f'{item.type.capitalize()} {item.id} is named "{item.name}"') ``` ## Update a Folder To update a folder's information, call [`folder.update_info(*, data, etag=None, **kwargs)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.item.Item.update_info) with a `dict` of properties to update on the folder. This method returns a new updated [`Folder`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.folder.Folder) object, leaving the original object unmodified. ``` updated_folder = client.folder(folder_id='22222').update_info(data={ 'name': '[ARCHIVED] Planning documents', 'description': 'Old planning documents', }) print('Folder updated!') ``` ## Create a Folder A folder can be created by calling [`folder.create_subfolder(name)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.folder.Folder.create_subfolder) on the parent folder with the name of the subfolder to be created. This method returns a new [`Folder`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.folder.Folder) representing the created subfolder. ``` subfolder = client.folder('0').create_subfolder('My Stuff') print(f'Created subfolder with ID {subfolder.id}') ``` ## Copy a Folder A folder can be copied into a new parent folder by calling [`folder.copy(parent_folder, name=None)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.base_item.BaseItem.copy) with the destination folder and an optional new name for the file in case there is a name conflict in the destination folder. This method returns a new [`Folder`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.folder.Folder) object representing the copy of the folder in the destination folder. ``` folder_id = '22222' destination_folder_id = '44444' folder_to_copy = client.folder(folder_id) destination_folder = client.folder(destination_folder_id) folder_copy = folder_to_copy.copy(parent_folder=destination_folder) print(f'Folder "{folder_copy.name}" has been copied into folder "{folder_copy.parent.name}"') ``` ## Move a Folder To move a folder from one parent folder into another, call [`folder.move(parent_folder, name=None)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.base_item.BaseItem.move) with the destination folder to move the folder into. You can optionally provide a `name` parameter to automatically rename the folder in case of a name conflict in the destination folder. This method returns the updated [`Folder`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.folder.Folder) object in the new folder. ``` folder_id = '11111' destination_folder_id = '44444' folder_to_move = client.folder(folder_id) destination_folder = client.folder(destination_folder_id) moved_folder = folder_to_move.move(parent_folder=destination_folder) print(f'Folder "{moved_folder.name}" has been moved into folder "{moved_folder.parent.name}"') ``` ## Rename a File A folder can be renamed by calling [`folder.rename(name)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.base_item.BaseItem.rename). This method returns the updated [`Folder`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.folder.Folder) object with a new name. ``` folder = client.folder(folder_id='11111') renamed_folder = folder.rename("new-name") print(f'Folder was renamed to "{renamed_folder.name}"') ``` ## Delete a Folder Calling the [`folder.delete(recursive=True, etag=None)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.folder.Folder.delete) method will delete the folder. Depending on enterprise settings, this will either move the folder to the user's trash or permanently delete the folder. This method returns `True` to signify that the deletion was successful. By default, the method will delete the folder and all of its contents; to fail the deletion if the folder is not empty, set the `recursive` parameter to `False`. ``` client.folder(folder_id='22222').delete() ``` ## Find a Folder for a Shared Link To find a folder given a shared link, use the [`client.get_shared_item`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.client.html?highlight=get_shared_item#boxsdk.client.client.Client.get_shared_item) method. ``` folder = client.get_shared_item('https://app.box.com/s/gjasdasjhasd', password='letmein') ``` ## Create or update a Shared Link A shared link for a folder can be generated or updated by calling [`folder.get_shared_link(access=None, etag=None, unshared_at=None, allow_download=None, allow_preview=None, password=None, vanity_name=None, **kwargs)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.folder.Folder.get_shared_link). This method returns a `unicode` string containing the shared link URL. ``` folder_id = '11111' url = client.folder(folder_id).get_shared_link(access='open', allow_download=False) print(f'The folder shared link URL is: {url}') ``` ## Get a Shared Link To check for an existing shared link on a folder, simply call `folder.shared_link` This method returns a `unicode` string containing the shared link URL. ``` folder_id = '11111' shared_link = client.folder(folder_id).get().shared_link url = shared_link['url'] ``` ## Remove a Shared Link A shared link for a folder can be removed by calling [`folder.remove_shared_link(etag=None, **kwargs)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.item.Item.remove_shared_link). ``` folder_id = '11111' client.folder(folder_id).remove_shared_link() ``` ## Set Metadata To set metadata on a folder call the [`folder.metadata(scope='global', template='properties')`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.item.Item.metadata) to specify the scope and template key of the metadata template to attach. Then, call the [`metadata.set(data)`][metadata_set] method with the key/value pairs to attach. This method returns a `dict` containing the applied metadata instance. Note: This method will unconditionally apply the provided metadata, overwriting the existing metadata for the keys provided. To specifically create or update metadata, see the `create()` or `update()` methods. ``` metadata = { 'foo': 'bar', } applied_metadata = client.folder(folder_id='11111').metadata(scope='enterprise', template='testtemplate').set(metadata) print(f'Set metadata in instance ID {applied_metadata["$id"]}') ``` Metadata can be added to a folder either as free-form key/value pairs or from an existing template. To add metadata to a folder, first call [`folder.metadata(scope='global', template='properties')`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.item.Item.metadata) to specify the scope and template key of the metadata template to attach (or use the default values to attach free-form keys and values). Then, call [`metadata.create(data)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.metadata.Metadata.create) with the key/value pairs to attach. This method can only be used to attach a given metadata template to the folder for the first time, and returns a `dict` containing the applied metadata instance. Note: This method will only succeed if the provided metadata template is not currently applied to the folder, otherwise it will fail with a Conflict error. ``` metadata = { 'foo': 'bar', 'baz': 'quux', } applied_metadata = client.folder(folder_id='22222').metadata().create(metadata) print(f'Applied metadata in instance ID {applied_metadata["$id"]}') ``` Updating metadata values is performed via a series of discrete operations, which are applied atomically against the existing folder metadata. First, specify which metadata will be updated by calling [`folder.metadata(scope='global', template='properties')`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.item.Item.metadata). Then, start an update sequence by calling [`metadata.start_update()`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.metadata.Metadata.start_update) and add update operations to the returned [`MetadataUpdate`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.metadata.MetadataUpdate). Finally, perform the update by calling [`metadata.update(metadata_update)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.metadata.Metadata.update). This final method returns a `dict` of the updated metadata instance. Note: This method will only succeed if the provided metadata template has already been applied to the folder; If the folder does not have existing metadata, this method will fail with a Not Found error. This is useful you know the file will already have metadata applied, since it will save an API call compared to `set()`. ``` folder = client.folder(folder_id='22222') folder_metadata = folder.metadata(scope='enterprise', template='myMetadata') updates = folder_metadata.start_update() updates.add('/foo', 'bar') updates.update('/baz', 'murp', old_value='quux') # Ensure the old value was "quux" before updating to "murp" updated_metadata = folder_metadata.update(updates) print('Updated metadata on folder!') print(f'foo is now {updated_metadata["foo"]} and baz is now {updated_metadata["baz"]}') ``` ## Get Metadata To retrieve the metadata instance on a folder for a specific metadata template, first call [`folder.metadata(scope='global', template='properties')`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.item.Item.metadata) to specify the scope and template key of the metadata template to retrieve, then call [`metadata.get()`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.metadata.Metadata.get) to retrieve the metadata values attached to the folder. This method returns a `dict` containing the applied metadata instance. ``` metadata = client.folder(folder_id='22222').metadata(scope='enterprise', template='myMetadata').get() print(f'Got metadata instance {metadata["$id"]}') ``` ## Remove Metadata To remove a metadata instance from a folder, call [`folder.metadata(scope='global', template='properties')`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.item.Item.metadata) to specify the scope and template key of the metadata template to remove, then call [`metadata.delete()`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.metadata.Metadata.delete) to remove the metadata from the folder. This method returns `True` to indicate that the removal succeeded. ``` client.folder(folder_id='11111').metadata(scope='enterprise', template='myMetadata').delete() ``` ## Get All Metadata To retrieve all metadata attached to a folder, call [`folder.get_all_metadata()`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.item.Item.get_all_metadata). This method returns a [`BoxObjectCollection`][box_object_collection] that can be used to iterate over the `dict`s representing each metadata instance attached to the folder. ``` folder_metadata = client.folder(folder_id='22222').get_all_metadata() for instance in folder_metadata: if 'foo' in instance: print(f'Metadata instance {instance["id"]} has value "{instance["foo"]}" for foo') ``` ## Get Metadata For Folder Items When fetching folder items, you may wish to retrieve metadata for the items simultaneously to avoid needing to make an API call for each item. You can retrieve up to 3 metadata instances per item by passing the special `metadata.<scope>.<templateKey>` field to [`folder.get_items(limit=None, offset=0, marker=None, use_marker=False, sort=None, direction=None, fields=None)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.folder.Folder.get_items). The metadata is available as a multi-level `dict` on the returned [`Item`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.item.Item) objects. ``` fields = [ 'type', 'id', 'name', 'metadata.enterprise.vendorContract', ] items = client.folder(folder_id='22222').get_items(fields=fields) for item in items: if item.metadata: metadata = item.metadata['enterprise']['vendorContract'] print(f'{item.type.capitalize()} {item.id} is a vendor contract with vendor name {metadata["vendorName"]}') ``` ## Set a Classification It is important to note that this feature is available only if you have Governance. To add classification to a [`Folder`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.folder.Folder), call [`folder.set_classification(classification)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.item.Item.set_classification). This method returns the classification type on the [`Folder`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.folder.Folder) object. If a classification already exists then this call will update the existing classification with the new [`ClassificationType`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.item.ClassificationType). ``` from boxsdk.object.item import ClassificationType classification = client.folder(folder_id='11111').set_classification(ClassificationType.PUBLIC) print(f'Classification Type is: {classification}') ``` The set method will always work no matter the state your [`Folder`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.folder.Folder) is in. For cases already where a classification value already exists [`set_classification(classification)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.item.Item.set_classification) may make multiple API calls. Alternatively, if you already know you have a classification and you are simple updating it, you can use the [`update_classification(classification)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.item.Item.update_classification). This will ultimately help you save one extra API call. ``` classification = client.folder(folder_id='11111').update_classification(ClassificationType.NONE) print(f'Classification Type is: {classification}') ``` ## Retrieve a Classification To retrieve a classification from a [`Folder`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.folder.Folder), call [`folder.get_classification()`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.item.Item.get_classification). This method returns the classification type on the [`Folder`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.folder.Folder) object. ``` classification = client.folder(folder_id='11111').get_classification() print(f'Classification Type is: {classification}') ``` ## Remove a Classification To remove a classification from a [`Folder`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.folder.Folder), call [`folder.remove_classification()`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.item.Item.remove_classification). ``` client.folder(folder_id='11111').remove_classification() ``` ## Create a Folder Lock To lock a folder, call [`client.folder(folder_id).create_lock()`][create-folder-lock] with the ID of the folder. This prevents the folder from being moved and/or deleted. ``` lock = client.folder(folder_id).create_lock() print(f'Created a lock with ID {lock.folder.id}') ``` ## Get Folder Locks To retrieve a list of the locks on a folder, call [`client.folder(folder_id).get_locks()][get-folder-locks] with the ID of the folder. Currently only one lock can exist per folder. Folder locks define access restrictions placed by folder owners to prevent specific folders from being moved or deleted. ``` locks = client.folder(folder_id).get_locks() lock = locks.next() print(f'A lock on a folder with ID {lock.folder.id}') ``` ## Delete a Folder Lock To remove a folder lock, call [`client.folder_lock(folder_lock_id).delete()`][delete-folder-lock] with the ID of the folder lock. ``` client.folder_lock(folder_lock_id='22222').delete() ``` --- ### Folders **Type:** page | **Section:** Additional Resources Folders Folder objects represent a folder from a user's account. They can be used to iterate through a folder's contents, collaborate a… # Folders Folder objects represent a folder from a user's account. They can be used to iterate through a folder's contents, collaborate a folder with another user or group, and perform other common folder operations (move, copy, delete, etc.). - [Get a Folder's Items](#get-a-folders-items) - [Get a Folder's Information](#get-a-folders-information) - [Update a Folder's Information](#update-a-folders-information) - [Create a Folder](#create-a-folder) - [Copy a Folder](#copy-a-folder) - [Delete a Folder](#delete-a-folder) - [Create or update a Shared Link](#create-or-update-a-shared-link) - [Create a Folder Lock](#create-a-folder-lock) - [Get Folder Locks](#get-folder-locks) - [Delete a Folder Lock](#delete-a-folder-lock) ## Get a Folder's Items Folder items can be retrieved by calling the `FoldersManager.GetFolderItemsMarkerBasedAsync(string id, int limit string marker = null, IEnumerable<string> fields = null, bool autoPaginate = false, string sort = null, BoxSortDirection? direction = null, string sharedLink = null, string sharedLinkPassword = null)` method. Use the `fields` option to specify the desired fields. Requesting information for only the fields you need can improve performance by reducing the size of the network response. Following method supports marker-based pagination. ``` BoxCollection<BoxItem> folderItems = await client.FoldersManager.GetFolderItemsMarkerBasedAsync("11111", 100); ``` Alternatively you can use method with offset-based pagination. ``` BoxCollection<BoxItem> folderItems = await client.FoldersManager.GetFolderItemsAsync("11111", 100, offset: 10); ``` ## Get a Folder's Information Folder information can be retrieved by calling `FoldersManager.GetInformationAsync(string id, IEnumerable<string> fields = null)` with the ID of the folder. ``` BoxFolder folder = await client.FoldersManager.GetInformationAsync("11111"); ``` ## Update a Folder's Information Updating a folder's information is done by calling the `FoldersManager.UpdateInformationAsync(BoxFolderRequest folderRequest, IEnumerable<string> fields = null, string etag = null)` method. ``` var requestParams = new BoxFolderRequest() { Id = "11111", Name = "My Documents (2017)" }; BoxFolder updatedFolder = await client.FoldersManager.UpdateInformationAsync(requestParams); ``` ## Create a Folder Create a subfolder inside of another folder by calling `FoldersManager.CreateAsync(BoxFolderRequest folderRequest, IEnumerable<string> fields = null)`. ``` // Create a new folder in the user's root folder var folderParams = new BoxFolderRequest() { Name = "New folder", Parent = new BoxRequestEntity() { Id = "0" } }; BoxFolder folder = await client.FoldersManager.CreateAsync(folderParams); ``` ## Copy a Folder To copy a folder from its current location into a different folder, call `FoldersManager.CopyAsync(BoxFolderRequest folderRequest, IEnumerable<string> fields = null)`. ``` // Copy folder 11111 into folder 22222 var requestParams = new BoxFolderRequest() { Id = "11111", Parent = new BoxRequestEntity() { Id = "22222" } }; BoxFolder folderCopy = await client.FoldersManager.CopyAsync(requestParams); ``` ## Delete a Folder A folder can be deleted by calling `FoldersManager.DeleteAsync(string id, bool recursive = false, string etag = null)` with the ID of the folder to delete. By default, the folder will only be deleted if it is empty; to delete the folder and all of its contents, set the optional `recursive` parameter to `true`. ``` await client.FoldersManager.DeleteAsync("11111", recursive: true); ``` ## Create or update a Shared Link You can create or update a shared link for a folder by calling `FoldersManager.CreateSharedLinkAsync(string id, BoxSharedLinkRequest sharedLinkRequest, IEnumerable<string> fields = null)` with the ID of the folder and the shared link parameters. ``` var sharedLinkParams = new BoxSharedLinkRequest() { Access = BoxSharedLinkAccessType.open }; BoxFolder folder = await client.FoldersManager.CreateSharedLinkAsync("11111", sharedLinkParams); string sharedLinkUrl = folder.SharedLink.Url; ``` ## Create a Folder Lock To lock a folder, call `FoldersManager.CreateLockAsync(string id)` with the ID of the folder. This prevents the folder from being moved and/or deleted. ``` BoxFolderLock folderLock = await _foldersManager.CreateLockAsync("11111"); ``` ## Get Folder Locks To retrieve a list of the locks on a folder, call `FoldersManager.GetLocksAsync(string id, bool autoPaginate` with the ID of the folder. Currently only one lock can exist per folder. Folder locks define access restrictions placed by folder owners to prevent specific folders from being moved or deleted. ``` BoxCollection<BoxFolderLock> folderLock = await _foldersManager.GetLocksAsync("11111"); string id = folderLock.Entries[0].Id; ``` ## Delete a Folder Lock To remove a folder lock, call `FoldersManger.DeleteLockAsync(string id)` with the ID of the folder lock. ``` await _foldersManager.DeleteLockAsync("11111"); ``` --- ### Folders **Type:** page | **Section:** Additional Resources Folders Folder objects represent a folder from a user's account. They can be used to iterate through a folder's contents, collaborate a… # Folders Folder objects represent a folder from a user's account. They can be used to iterate through a folder's contents, collaborate a folder with another user or group, and perform other common folder operations (move, copy, delete, etc.). [Folders](#folders) - [Get Folder Info](#get-folder-info) - [Get Folder Items](#get-folder-items) - [Create Folder](#create-folder) - [Delete Folder](#delete-folder) - [Copy Folder](#copy-folder) - [Get Folder Collaborations](#get-folder-collaborations) - [Add Folder to Favorites](#add-folder-to-favorites) - [Remove Folder from Favorites](#remove-folder-from-favorites) - [Get Shared Link](#get-shared-link) - [Set Shared Link](#set-shared-link) - [Remove Shared Link](#remove-shared-link) - [Get Folder Locks](#get-folder-locks) - [Create Folder Lock](#create-folder-lock) - [Delete Folder Lock](#delete-folder-lock) ## Get Folder Info To retrieve information about a folder, call [`client.folders.get(folderId:fields:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/FoldersModule.html#/s:6BoxSDK13FoldersModuleC3get8folderId6fields10completionySS_SaySSGSgys6ResultOyAA6FolderCAA0A8SDKErrorCGctF) with the ID of the folder. You can control which fields are returned in the resulting `Folder` object by passing the `fields` parameter. ``` client.folders.get( folderId: "22222", fields: ["name", "created_at"] ) { (result: Result<Folder, BoxSDKError>) in guard case let .success(folder) = result else { print("Error getting folder information") return } print("Folder \(folder.name) was created at \(folder.createdAt)") } ``` As an alternative, you can call `async` method [`client.folders.get(folderId:fields)`](https://opensource.box.com/box-ios-sdk/Classes/FoldersModule.html#/s:6BoxSDK13FoldersModuleC3get8folderId6fieldsAA6FolderCSS_SaySSGSgtYaKF) ``` do { let folder = try await client.folders.get( folderId: "111111", fields: ["name", "created_at"] ) print("Folder \(folder.name) was created at \(folder.createdAt)") } catch { print("Error getting folder information") } ``` ## Get Folder Items To retrieve information about the items contained in a folder, call [`client.folders.listItems(folderId:usemarker:marker:offset:limit:sort:direction:fields:)`](https://opensource.box.com/box-ios-sdk/Classes/FoldersModule.html#/s:6BoxSDK13FoldersModuleC9listItems8folderId9usemarker6marker6offset5limit4sort9direction6fields10completionySS_SbSgSSSgSiSgApA06FolderF7OrderByOSgAA0R9DirectionOSgSaySSGSgys6ResultOyAA14PagingIteratorCyAA0Q4ItemOGAA0A8SDKErrorCGctF) with the ID of the folder. This method will return an iterator, which is used to retrieve folder items. ``` let iterator = client.folders.listItems(folderId: "22222", sort: .name, direction: .ascending) iterator.next { results in switch results { case let .success(page): for item in page.entries { switch item { case let .file(file): print("File \(file.name) (ID: \(file.id)) is in the folder") case let .folder(folder): print("Subfolder \(folder.name) (ID: \(folder.id)) is in the folder") case let .webLink(webLink): print("Web link \(webLink.name) (ID: \(webLink.id)) is in the folder") } } case let .failure(error): print(error) } } ``` As an alternative, you can retrieve folder items by iterator in `async` way. For instance, to fetch all folder items, call: ``` let iterator = client.folders.listItems(folderId: "22222", sort: .name, direction: .ascending) var allItems: [FolderItem] = [] do { repeat { let items = try await iterator.next() allItems.append(contentsOf: items.entries) } while true } catch let error as BoxSDKError where error.message == .endOfList { print("The end of the list has been reached") } catch { print("An error occurred: \(error)") } ``` ## Create Folder To create a new folder, call [`client.folders.create(name:parentId:fields:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/FoldersModule.html#/s:6BoxSDK13FoldersModuleC6create4name8parentId6fields10completionySS_SSSaySSGSgys6ResultOyAA6FolderCAA0A8SDKErrorCGctF) with a name for the new folder and the ID of the folder to create the new folder in. To create a new folder inside the root folder ("All Files"), use ID `"0"`. ``` client.folders.create(name: "New Folder", parentId: "22222") { (result: Result<Folder, BoxSDKError>) in guard case let .success(folder) = result else { print("Error creating folder") return } print("Created folder \"\(folder.name)\" inside of folder \"\(folder.parent?.name)\"") } ``` As an alternative, you can call `async` method [`client.folders.create(name:parentId:fields)`](https://opensource.box.com/box-ios-sdk/Classes/FoldersModule.html#/s:6BoxSDK13FoldersModuleC6create4name8parentId6fieldsAA6FolderCSS_SSSaySSGSgtYaKF). ``` do { let folder = try await client.folders.create(name: "New Folder", parentId: "22222") print("Created folder \"\(folder.name)\" inside of folder \"\(folder.parent?.name)\"") } catch { print("Error getting folder information") } ``` ## Delete Folder To delete a folder, call [`client.folders.delete(folderId:recursive:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/FoldersModule.html#/s:6BoxSDK13FoldersModuleC6delete8folderId9recursive10completionySS_SbSgys6ResultOyytAA0A8SDKErrorCGctF) with the ID of the folder to delete. By default, the folder will only be deleted if it is empty and has no items in it; if you wish to delete all the items in the folder as well, pass `recursive: true`. ``` client.folders.delete(folderId: "22222", recursive: true) { result: Result<Void, BoxSDKError>} in guard case .success = result else { print("Error deleting folder") return } print("Folder and contents successfully deleted") } ``` As an alternative, you can call `async` method [`client.folders.delete(folderId:recursive)`](https://opensource.box.com/box-ios-sdk/Classes/FoldersModule.html#/s:6BoxSDK13FoldersModuleC6delete8folderId9recursiveySS_SbSgtYaKF) ``` do { let folder = try await client.folders.delete(folderId: "22222", recursive: true) print("Folder and contents successfully deleted") } catch { print("Error deleting folder") } ``` ## Copy Folder To copy a folder from one parent folder to another, call [`client.folders.copy(folderId:destinationFolderID:name:fields:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/FoldersModule.html#/s:6BoxSDK13FoldersModuleC4copy8folderId19destinationFolderID4name6fields10completionySS_S2SSgSaySSGSgys6ResultOyAA0I0CAA0A8SDKErrorCGctF) with the ID of the folder to copy and the ID of the destination parent folder. To avoid a name conflict in the new parent folder, pass an alternate name for the folder in the `name` parameter; the folder will be renamed to the alternate name in case of a conflict. ``` client.folders.copy( folderId: "22222", destinationFolderID: "12345" ) { (result: Result<Folder, BoxSDKError>) in guard case let .success(folderCopy) = result else { print("Error copying folder") return } print("Copied folder \(folderCopy.name) to destination \(folderCopy.parent?.name)") } ``` As an alternative, you can call `async` method [`client.folders.copy(folderId:destinationFolderId:name:fields:)`](https://opensource.box.com/box-ios-sdk/Classes/FoldersModule.html#/s:6BoxSDK13FoldersModuleC4copy8folderId017destinationFolderG04name6fieldsAA0I0CSS_S2SSgSaySSGSgtYaKF) ``` do { let folderCopy = try await client.folders.copy(folderId: "22222", destinationFolderId: "12345") print("Copied folder \(folderCopy.name) to destination \(folderCopy.parent?.name)") } catch { print("Error copying folder") } ``` ## Get Folder Collaborations To retrieve a list of the collaborations on a folder, call [`client.folders.listCollaborations(folderId:fields:)`](https://opensource.box.com/box-ios-sdk/Classes/FoldersModule.html#/s:6BoxSDK13FoldersModuleC18listCollaborations8folderId6fields10completionySS_SaySSGSgys6ResultOyAA14PagingIteratorCyAA13CollaborationCGAA0A8SDKErrorCGctF) with the ID of the folder. ``` let iterator = client.folders.listCollaborations(folderId: "22222") iterator.next { results in switch results { case let .success(page): for collaboration in page.entries { if let collaborator = collaboration.accessibleBy { switch collaborator.collaboratorValue { case .user(let user): print("- user: \(user.name ?? "")") case .group(let group): print("- group: \(group.name ?? "")") } } } case let .failure(error): print(error) } } ``` As an alternative, you can retrieve collaborations items by iterator in `async` way. ``` let iterator = client.folders.listCollaborations(folderId: "163571796480") do { let page = try await iterator.next() for collaboration in page.entries { if let collaborator = collaboration.accessibleBy { switch collaborator.collaboratorValue { case .user(let user): print("- user: \(user.name ?? "")") case .group(let group): print("- group: \(group.name ?? "")") } } } } catch { print("An error occurred: \(error)") } ``` ## Add Folder to Favorites To add a folder to the user's favorites, call [`client.folders.addToFavorites(folderId:fields:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/FoldersModule.html#/s:6BoxSDK13FoldersModuleC14addToFavorites8folderId6fields10completionySS_SaySSGSgys6ResultOyAA6FolderCAA0A8SDKErrorCGctF) with the ID of the folder. ``` client.folders.addToFavorites(folderId: "22222") { (result: Result<Void, BoxSDKError>) in guard case .success = result else { print("Error adding folder to favorites") return } print("Added folder to favorites") } ``` As an alternative, you can call `async` method [`client.folders.addToFavorites(folderId:fields:)`](https://opensource.box.com/box-ios-sdk/Classes/FoldersModule.html#/s:6BoxSDK13FoldersModuleC14addToFavorites8folderId6fieldsAA6FolderCSS_SaySSGtYaKF). ``` do { try await client.folders.addToFavorites(folderId: "22222") print("Added folder to favorites") } catch { print("Error adding folder to favorites") } ``` ## Remove Folder from Favorites To remove a folder from the user's favorites, call [`client.folders.removeFromFavorites(folderId:fields:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/FoldersModule.html#/s:6BoxSDK13FoldersModuleC19removeFromFavorites8folderId6fields10completionySS_SaySSGSgys6ResultOyAA6FolderCAA0A8SDKErrorCGctF) with the ID of the folder. ``` client.folders.removeFromFavorites(folderId: "22222") { result in guard case .success = result else { print("Error removing folder from favorites") return } print("Removed folder to favorites") } ``` As an alternative, you can call `async` method [`client.folders.removeFromFavorites(folderId:fields:)`](https://opensource.box.com/box-ios-sdk/Classes/FoldersModule.html#/s:6BoxSDK13FoldersModuleC19removeFromFavorites8folderId6fieldsAA6FolderCSS_SaySSGSgtYaKF). ``` do { try await client.folders.removeFromFavorites(folderId: "22222") print("Removed folder to favorites") } catch { print("Error removing folder from favorites") } ``` ## Get Shared Link To retrieve the shared link associated with a folder, call [`client.folders.getSharedLink(forFolder:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/FoldersModule.html#/s:6BoxSDK13FoldersModuleC13getSharedLink9forFolder10completionySS_ys6ResultOyAA0fG0CAA0A8SDKErrorCGctF) with the ID of the folder. ``` client.folders.getSharedLink(forFolder: "11111") { (result: Result<SharedLink, BoxSDKError>) in guard case let .success(sharedLink) = result else { print("Error retrieving folder shared link") return } print("Folder shared link URL is \(sharedLink.url), with \(sharedLink.access) access") } ``` As an alternative, you can call `async` method [`client.folders.getSharedLink(forFolder:)`](https://opensource.box.com/box-ios-sdk/Classes/FoldersModule.html#/s:6BoxSDK13FoldersModuleC13getSharedLink9forFolder10completionySS_ys6ResultOyAA0fG0CAA0A8SDKErrorCGctF). ``` do { let sharedLink = try await client.folders.getSharedLink(forFolder: "11111") print("Folder shared link URL is \(sharedLink.url), with \(sharedLink.access) access") } catch { print("Error retrieving folder shared link") } ``` ## Set Shared Link To add or update the shared link for a folder, call [`client.folders.setSharedLink(forFolder:access:unsharedAt:vanityName:password:canDownload:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/FoldersModule.html#/s:6BoxSDK13FoldersModuleC13setSharedLink9forFolder6access10unsharedAt10vanityName8password11canDownload10completionySS_AA0fG6AccessOSgAA17NullableParameterOy10Foundation4DateVGSgAPySSGSgAWSbSgys6ResultOyAA0fG0CAA0A8SDKErrorCGctF) with the ID of the folder and the shared link properties to set. ``` client.folders.setSharedLink(forFolder: "11111", access: .open) { (result: Result<SharedLink, BoxSDKError>) in guard case let .success(sharedLink) = result else { print("Error setting folder shared link") return } print("Folder shared link URL is \(sharedLink.url), with \(sharedLink.access) access") } ``` As an alternative, you can call `async` method [`client.folders.setSharedLink(forFolder:access:unsharedAt:vanityName:password:canDownload:)`](https://opensource.box.com/box-ios-sdk/Classes/FoldersModule.html#/s:6BoxSDK13FoldersModuleC13setSharedLink9forFolder6access10unsharedAt10vanityName8password11canDownloadAA0fG0CSS_AA0fG6AccessOSgAA17NullableParameterOy10Foundation4DateVGSgAQySSGSgAXSbSgtYaKF). ``` do { let sharedLink = try await client.folders.setSharedLink(forFolder: "163571796480", access: .open) print("Folder shared link URL is \(sharedLink.url), with \(sharedLink.access) access") } catch { print("Error setting folder shared link") } ``` ## Remove Shared Link To remove a file's shared link, call [`client.folders.deleteSharedLink(forFolder:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/FoldersModule.html#/s:6BoxSDK13FoldersModuleC16deleteSharedLink9forFolder10completionySS_ys6ResultOyytAA0A8SDKErrorCGctF) with the ID of the folder. ``` client.folders.deleteSharedLink(forFolder: "11111") { (result: Result<Void, BoxSDKError>) in guard case .success = result else { print("Error removing folder shared link") return } print("Folder shared link removed") } ``` As an alternative, you can call `async` method [`client.folders.deleteSharedLink(forFolder:)`](https://opensource.box.com/box-ios-sdk/Classes/FoldersModule.html#/s:6BoxSDK13FoldersModuleC16deleteSharedLink9forFolderySS_tYaKF). ``` do { try await client.folders.deleteSharedLink(forFolder: "11111") print("Folder shared link removed") } catch { print("Error removing folder shared link") } ``` ## Get Folder Locks To retrieve a list of the locks on a folder, call [`client.folders.listLocks(folderId:completion:)`][get-folder-locks] with the ID of the folder. Folder locks define access restrictions placed by folder owners to prevent specific folders from being moved or deleted. ``` client.folders.listLocks(folderId: "22222") { results in switch results { case let .success(iterator): for i in 1 ... 10 { iterator.next { result in switch result { case let .success(folderLock): print("- \(folderLock.id)") case let .failure(error): print(error) } } } case let .failure(error): print(error) } } ``` As an alternative, you can retrieve all folder locks by iterator in `async` way. ``` let iterator = client.folders.listLocks(folderId: "22222") do { repeat { let page = try await iterator.next() for folderLock in page.entries { print("- \(folderLock.id)") } } while true } catch let error as BoxSDKError where error.message == .endOfList { print("The are no more items to fetch") } catch { print("An error occurred: \(error)") } ``` ## Create Folder Lock To lock a folder, call [`client.folders.createLock(folderId:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/FoldersModule.html#/s:6BoxSDK13FoldersModuleC10createLock8folderId10completionySS_ys6ResultOyAA06FolderF0CAA0A8SDKErrorCGctF) with the ID of the folder. This prevents the folder from being moved and/or deleted. ``` client.folders.createLock(folderId: "22222") { (result: Result<FolderLock, BoxSDKError>) in guard case let .success(folderLock) = result else { print("Error creating folder lock") return } print("Created folder lock with id \"\(folderLock.id)\" inside of folder with id \"\(folderLock.folder?.id)\"") } ``` As an alternative, you can call `async` method [`client.folders.createLock(folderId: "22222")`](https://opensource.box.com/box-ios-sdk/Classes/FoldersModule.html#/s:6BoxSDK13FoldersModuleC10createLock8folderIdAA06FolderF0CSS_tYaKF). ``` do { let folderLock = try await client.folders.createLock(folderId: "163571796480") print("Created folder lock with id \"\(folderLock.id)\" inside of folder with id \"\(folderLock.folder?.id)\"") } catch { print("Error creating folder lock") } ``` ## Delete Folder Lock To remove a folder lock, call [`client.folders.deleteLock(folderLockId:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/FoldersModule.html#/s:6BoxSDK13FoldersModuleC10deleteLock06folderF2Id10completionySS_ys6ResultOyytAA0A8SDKErrorCGctF) with the ID of the folder lock. ``` client.folders.deleteLock(folderLockId: "11111") { (result: Result<Void, BoxSDKError>) in guard case .success = result else { print("Error removing folder lock") return } print("Folder lock removed") } ``` As an alternative, you can call `async` method [`client.folders.deleteLock(folderId: "22222")`](https://opensource.box.com/box-ios-sdk/Classes/FoldersModule.html#/s:6BoxSDK13FoldersModuleC10deleteLock06folderF2IdySS_tYaKF). ``` do { try await client.folders.deleteSharedLink(forFolder: "11111") print("Folder shared link removed") } catch { print("Error removing folder shared link") } ``` --- ### Folders **Type:** page | **Section:** Additional Resources Folders Folder objects represent a folder from a user's account. They can be used to iterate through a folder's contents, collaborate a… # Folders Folder objects represent a folder from a user's account. They can be used to iterate through a folder's contents, collaborate a folder with another user or group, and perform other common folder operations (move, copy, delete, etc.). [Folders](#folders) - [Get Folder Info](#get-folder-info) - [Get Folder Items](#get-folder-items) - [Create Folder](#create-folder) - [Delete Folder](#delete-folder) - [Copy Folder](#copy-folder) - [Get Folder Collaborations](#get-folder-collaborations) - [Add Folder to Favorites](#add-folder-to-favorites) - [Remove Folder from Favorites](#remove-folder-from-favorites) - [Get Shared Link](#get-shared-link) - [Set Shared Link](#set-shared-link) - [Remove Shared Link](#remove-shared-link) - [Get Folder Locks](#get-folder-locks) - [Create Folder Lock](#create-folder-lock) - [Delete Folder Lock](#delete-folder-lock) ## Get Folder Info To retrieve information about a folder, call [`client.folders.get(folderId:fields:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/FoldersModule.html#/s:6BoxSDK13FoldersModuleC3get8folderId6fields10completionySS_SaySSGSgys6ResultOyAA6FolderCAA0A8SDKErrorCGctF) with the ID of the folder. You can control which fields are returned in the resulting `Folder` object by passing the `fields` parameter. ``` client.folders.get( folderId: "22222", fields: ["name", "created_at"] ) { (result: Result<Folder, BoxSDKError>) in guard case let .success(folder) = result else { print("Error getting folder information") return } print("Folder \(folder.name) was created at \(folder.createdAt)") } ``` As an alternative, you can call `async` method [`client.folders.get(folderId:fields)`](https://opensource.box.com/box-ios-sdk/Classes/FoldersModule.html#/s:6BoxSDK13FoldersModuleC3get8folderId6fieldsAA6FolderCSS_SaySSGSgtYaKF) ``` do { let folder = try await client.folders.get( folderId: "111111", fields: ["name", "created_at"] ) print("Folder \(folder.name) was created at \(folder.createdAt)") } catch { print("Error getting folder information") } ``` ## Get Folder Items To retrieve information about the items contained in a folder, call [`client.folders.listItems(folderId:usemarker:marker:offset:limit:sort:direction:fields:)`](https://opensource.box.com/box-ios-sdk/Classes/FoldersModule.html#/s:6BoxSDK13FoldersModuleC9listItems8folderId9usemarker6marker6offset5limit4sort9direction6fields10completionySS_SbSgSSSgSiSgApA06FolderF7OrderByOSgAA0R9DirectionOSgSaySSGSgys6ResultOyAA14PagingIteratorCyAA0Q4ItemOGAA0A8SDKErrorCGctF) with the ID of the folder. This method will return an iterator, which is used to retrieve folder items. ``` let iterator = client.folders.listItems(folderId: "22222", sort: .name, direction: .ascending) iterator.next { results in switch results { case let .success(page): for item in page.entries { switch item { case let .file(file): print("File \(file.name) (ID: \(file.id)) is in the folder") case let .folder(folder): print("Subfolder \(folder.name) (ID: \(folder.id)) is in the folder") case let .webLink(webLink): print("Web link \(webLink.name) (ID: \(webLink.id)) is in the folder") } } case let .failure(error): print(error) } } ``` As an alternative, you can retrieve folder items by iterator in `async` way. For instance, to fetch all folder items, call: ``` let iterator = client.folders.listItems(folderId: "22222", sort: .name, direction: .ascending) var allItems: [FolderItem] = [] do { repeat { let items = try await iterator.next() allItems.append(contentsOf: items.entries) } while true } catch let error as BoxSDKError where error.message == .endOfList { print("The end of the list has been reached") } catch { print("An error occurred: \(error)") } ``` ## Create Folder To create a new folder, call [`client.folders.create(name:parentId:fields:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/FoldersModule.html#/s:6BoxSDK13FoldersModuleC6create4name8parentId6fields10completionySS_SSSaySSGSgys6ResultOyAA6FolderCAA0A8SDKErrorCGctF) with a name for the new folder and the ID of the folder to create the new folder in. To create a new folder inside the root folder ("All Files"), use ID `"0"`. ``` client.folders.create(name: "New Folder", parentId: "22222") { (result: Result<Folder, BoxSDKError>) in guard case let .success(folder) = result else { print("Error creating folder") return } print("Created folder \"\(folder.name)\" inside of folder \"\(folder.parent?.name)\"") } ``` As an alternative, you can call `async` method [`client.folders.create(name:parentId:fields)`](https://opensource.box.com/box-ios-sdk/Classes/FoldersModule.html#/s:6BoxSDK13FoldersModuleC6create4name8parentId6fieldsAA6FolderCSS_SSSaySSGSgtYaKF). ``` do { let folder = try await client.folders.create(name: "New Folder", parentId: "22222") print("Created folder \"\(folder.name)\" inside of folder \"\(folder.parent?.name)\"") } catch { print("Error getting folder information") } ``` ## Delete Folder To delete a folder, call [`client.folders.delete(folderId:recursive:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/FoldersModule.html#/s:6BoxSDK13FoldersModuleC6delete8folderId9recursive10completionySS_SbSgys6ResultOyytAA0A8SDKErrorCGctF) with the ID of the folder to delete. By default, the folder will only be deleted if it is empty and has no items in it; if you wish to delete all the items in the folder as well, pass `recursive: true`. ``` client.folders.delete(folderId: "22222", recursive: true) { result: Result<Void, BoxSDKError>} in guard case .success = result else { print("Error deleting folder") return } print("Folder and contents successfully deleted") } ``` As an alternative, you can call `async` method [`client.folders.delete(folderId:recursive)`](https://opensource.box.com/box-ios-sdk/Classes/FoldersModule.html#/s:6BoxSDK13FoldersModuleC6delete8folderId9recursiveySS_SbSgtYaKF) ``` do { let folder = try await client.folders.delete(folderId: "22222", recursive: true) print("Folder and contents successfully deleted") } catch { print("Error deleting folder") } ``` ## Copy Folder To copy a folder from one parent folder to another, call [`client.folders.copy(folderId:destinationFolderID:name:fields:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/FoldersModule.html#/s:6BoxSDK13FoldersModuleC4copy8folderId19destinationFolderID4name6fields10completionySS_S2SSgSaySSGSgys6ResultOyAA0I0CAA0A8SDKErrorCGctF) with the ID of the folder to copy and the ID of the destination parent folder. To avoid a name conflict in the new parent folder, pass an alternate name for the folder in the `name` parameter; the folder will be renamed to the alternate name in case of a conflict. ``` client.folders.copy( folderId: "22222", destinationFolderID: "12345" ) { (result: Result<Folder, BoxSDKError>) in guard case let .success(folderCopy) = result else { print("Error copying folder") return } print("Copied folder \(folderCopy.name) to destination \(folderCopy.parent?.name)") } ``` As an alternative, you can call `async` method [`client.folders.copy(folderId:destinationFolderId:name:fields:)`](https://opensource.box.com/box-ios-sdk/Classes/FoldersModule.html#/s:6BoxSDK13FoldersModuleC4copy8folderId017destinationFolderG04name6fieldsAA0I0CSS_S2SSgSaySSGSgtYaKF) ``` do { let folderCopy = try await client.folders.copy(folderId: "22222", destinationFolderId: "12345") print("Copied folder \(folderCopy.name) to destination \(folderCopy.parent?.name)") } catch { print("Error copying folder") } ``` ## Get Folder Collaborations To retrieve a list of the collaborations on a folder, call [`client.folders.listCollaborations(folderId:fields:)`](https://opensource.box.com/box-ios-sdk/Classes/FoldersModule.html#/s:6BoxSDK13FoldersModuleC18listCollaborations8folderId6fields10completionySS_SaySSGSgys6ResultOyAA14PagingIteratorCyAA13CollaborationCGAA0A8SDKErrorCGctF) with the ID of the folder. ``` let iterator = client.folders.listCollaborations(folderId: "22222") iterator.next { results in switch results { case let .success(page): for collaboration in page.entries { if let collaborator = collaboration.accessibleBy { switch collaborator.collaboratorValue { case .user(let user): print("- user: \(user.name ?? "")") case .group(let group): print("- group: \(group.name ?? "")") } } } case let .failure(error): print(error) } } ``` As an alternative, you can retrieve collaborations items by iterator in `async` way. ``` let iterator = client.folders.listCollaborations(folderId: "163571796480") do { let page = try await iterator.next() for collaboration in page.entries { if let collaborator = collaboration.accessibleBy { switch collaborator.collaboratorValue { case .user(let user): print("- user: \(user.name ?? "")") case .group(let group): print("- group: \(group.name ?? "")") } } } } catch { print("An error occurred: \(error)") } ``` ## Add Folder to Favorites To add a folder to the user's favorites, call [`client.folders.addToFavorites(folderId:fields:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/FoldersModule.html#/s:6BoxSDK13FoldersModuleC14addToFavorites8folderId6fields10completionySS_SaySSGSgys6ResultOyAA6FolderCAA0A8SDKErrorCGctF) with the ID of the folder. ``` client.folders.addToFavorites(folderId: "22222") { (result: Result<Void, BoxSDKError>) in guard case .success = result else { print("Error adding folder to favorites") return } print("Added folder to favorites") } ``` As an alternative, you can call `async` method [`client.folders.addToFavorites(folderId:fields:)`](https://opensource.box.com/box-ios-sdk/Classes/FoldersModule.html#/s:6BoxSDK13FoldersModuleC14addToFavorites8folderId6fieldsAA6FolderCSS_SaySSGtYaKF). ``` do { try await client.folders.addToFavorites(folderId: "22222") print("Added folder to favorites") } catch { print("Error adding folder to favorites") } ``` ## Remove Folder from Favorites To remove a folder from the user's favorites, call [`client.folders.removeFromFavorites(folderId:fields:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/FoldersModule.html#/s:6BoxSDK13FoldersModuleC19removeFromFavorites8folderId6fields10completionySS_SaySSGSgys6ResultOyAA6FolderCAA0A8SDKErrorCGctF) with the ID of the folder. ``` client.folders.removeFromFavorites(folderId: "22222") { result in guard case .success = result else { print("Error removing folder from favorites") return } print("Removed folder to favorites") } ``` As an alternative, you can call `async` method [`client.folders.removeFromFavorites(folderId:fields:)`](https://opensource.box.com/box-ios-sdk/Classes/FoldersModule.html#/s:6BoxSDK13FoldersModuleC19removeFromFavorites8folderId6fieldsAA6FolderCSS_SaySSGSgtYaKF). ``` do { try await client.folders.removeFromFavorites(folderId: "22222") print("Removed folder to favorites") } catch { print("Error removing folder from favorites") } ``` ## Get Shared Link To retrieve the shared link associated with a folder, call [`client.folders.getSharedLink(forFolder:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/FoldersModule.html#/s:6BoxSDK13FoldersModuleC13getSharedLink9forFolder10completionySS_ys6ResultOyAA0fG0CAA0A8SDKErrorCGctF) with the ID of the folder. ``` client.folders.getSharedLink(forFolder: "11111") { (result: Result<SharedLink, BoxSDKError>) in guard case let .success(sharedLink) = result else { print("Error retrieving folder shared link") return } print("Folder shared link URL is \(sharedLink.url), with \(sharedLink.access) access") } ``` As an alternative, you can call `async` method [`client.folders.getSharedLink(forFolder:)`](https://opensource.box.com/box-ios-sdk/Classes/FoldersModule.html#/s:6BoxSDK13FoldersModuleC13getSharedLink9forFolder10completionySS_ys6ResultOyAA0fG0CAA0A8SDKErrorCGctF). ``` do { let sharedLink = try await client.folders.getSharedLink(forFolder: "11111") print("Folder shared link URL is \(sharedLink.url), with \(sharedLink.access) access") } catch { print("Error retrieving folder shared link") } ``` ## Set Shared Link To add or update the shared link for a folder, call [`client.folders.setSharedLink(forFolder:access:unsharedAt:vanityName:password:canDownload:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/FoldersModule.html#/s:6BoxSDK13FoldersModuleC13setSharedLink9forFolder6access10unsharedAt10vanityName8password11canDownload10completionySS_AA0fG6AccessOSgAA17NullableParameterOy10Foundation4DateVGSgAPySSGSgAWSbSgys6ResultOyAA0fG0CAA0A8SDKErrorCGctF) with the ID of the folder and the shared link properties to set. ``` client.folders.setSharedLink(forFolder: "11111", access: .open) { (result: Result<SharedLink, BoxSDKError>) in guard case let .success(sharedLink) = result else { print("Error setting folder shared link") return } print("Folder shared link URL is \(sharedLink.url), with \(sharedLink.access) access") } ``` As an alternative, you can call `async` method [`client.folders.setSharedLink(forFolder:access:unsharedAt:vanityName:password:canDownload:)`](https://opensource.box.com/box-ios-sdk/Classes/FoldersModule.html#/s:6BoxSDK13FoldersModuleC13setSharedLink9forFolder6access10unsharedAt10vanityName8password11canDownloadAA0fG0CSS_AA0fG6AccessOSgAA17NullableParameterOy10Foundation4DateVGSgAQySSGSgAXSbSgtYaKF). ``` do { let sharedLink = try await client.folders.setSharedLink(forFolder: "163571796480", access: .open) print("Folder shared link URL is \(sharedLink.url), with \(sharedLink.access) access") } catch { print("Error setting folder shared link") } ``` ## Remove Shared Link To remove a file's shared link, call [`client.folders.deleteSharedLink(forFolder:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/FoldersModule.html#/s:6BoxSDK13FoldersModuleC16deleteSharedLink9forFolder10completionySS_ys6ResultOyytAA0A8SDKErrorCGctF) with the ID of the folder. ``` client.folders.deleteSharedLink(forFolder: "11111") { (result: Result<Void, BoxSDKError>) in guard case .success = result else { print("Error removing folder shared link") return } print("Folder shared link removed") } ``` As an alternative, you can call `async` method [`client.folders.deleteSharedLink(forFolder:)`](https://opensource.box.com/box-ios-sdk/Classes/FoldersModule.html#/s:6BoxSDK13FoldersModuleC16deleteSharedLink9forFolderySS_tYaKF). ``` do { try await client.folders.deleteSharedLink(forFolder: "11111") print("Folder shared link removed") } catch { print("Error removing folder shared link") } ``` ## Get Folder Locks To retrieve a list of the locks on a folder, call [`client.folders.listLocks(folderId:completion:)`][get-folder-locks] with the ID of the folder. Folder locks define access restrictions placed by folder owners to prevent specific folders from being moved or deleted. ``` client.folders.listLocks(folderId: "22222") { results in switch results { case let .success(iterator): for i in 1 ... 10 { iterator.next { result in switch result { case let .success(folderLock): print("- \(folderLock.id)") case let .failure(error): print(error) } } } case let .failure(error): print(error) } } ``` As an alternative, you can retrieve all folder locks by iterator in `async` way. ``` let iterator = client.folders.listLocks(folderId: "22222") do { repeat { let page = try await iterator.next() for folderLock in page.entries { print("- \(folderLock.id)") } } while true } catch let error as BoxSDKError where error.message == .endOfList { print("The are no more items to fetch") } catch { print("An error occurred: \(error)") } ``` ## Create Folder Lock To lock a folder, call [`client.folders.createLock(folderId:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/FoldersModule.html#/s:6BoxSDK13FoldersModuleC10createLock8folderId10completionySS_ys6ResultOyAA06FolderF0CAA0A8SDKErrorCGctF) with the ID of the folder. This prevents the folder from being moved and/or deleted. ``` client.folders.createLock(folderId: "22222") { (result: Result<FolderLock, BoxSDKError>) in guard case let .success(folderLock) = result else { print("Error creating folder lock") return } print("Created folder lock with id \"\(folderLock.id)\" inside of folder with id \"\(folderLock.folder?.id)\"") } ``` As an alternative, you can call `async` method [`client.folders.createLock(folderId: "22222")`](https://opensource.box.com/box-ios-sdk/Classes/FoldersModule.html#/s:6BoxSDK13FoldersModuleC10createLock8folderIdAA06FolderF0CSS_tYaKF). ``` do { let folderLock = try await client.folders.createLock(folderId: "163571796480") print("Created folder lock with id \"\(folderLock.id)\" inside of folder with id \"\(folderLock.folder?.id)\"") } catch { print("Error creating folder lock") } ``` ## Delete Folder Lock To remove a folder lock, call [`client.folders.deleteLock(folderLockId:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/FoldersModule.html#/s:6BoxSDK13FoldersModuleC10deleteLock06folderF2Id10completionySS_ys6ResultOyytAA0A8SDKErrorCGctF) with the ID of the folder lock. ``` client.folders.deleteLock(folderLockId: "11111") { (result: Result<Void, BoxSDKError>) in guard case .success = result else { print("Error removing folder lock") return } print("Folder lock removed") } ``` As an alternative, you can call `async` method [`client.folders.deleteLock(folderId: "22222")`](https://opensource.box.com/box-ios-sdk/Classes/FoldersModule.html#/s:6BoxSDK13FoldersModuleC10deleteLock06folderF2IdySS_tYaKF). ``` do { try await client.folders.deleteSharedLink(forFolder: "11111") print("Folder shared link removed") } catch { print("Error removing folder shared link") } ``` --- ### FoldersManager **Type:** page | **Section:** Additional Resources FoldersManager Get folder information Update folder Delete folder List items in folder Create folder Copy folder Get folder information… # FoldersManager - [Get folder information](#get-folder-information) - [Update folder](#update-folder) - [Delete folder](#delete-folder) - [List items in folder](#list-items-in-folder) - [Create folder](#create-folder) - [Copy folder](#copy-folder) ## Get folder information Retrieves details for a folder, including the first 100 entries in the folder. Passing `sort`, `direction`, `offset`, and `limit` parameters in query allows you to manage the list of returned [folder items](r://folder--full#param-item-collection). To fetch more items within the folder, use the [Get items in a folder](e://get-folders-id-items) endpoint. This operation is performed by calling function `getFolderById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-folders-id/). ``` await client.folders.getFolderById('0'); ``` ### Arguments folderId `string` - The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. Example: "12345" optionalsInput `GetFolderByIdOptionalsInput` ### Returns This function returns a value of type `FolderFull`. Returns a folder, including the first 100 entries in the folder. If you used query parameters like `sort`, `direction`, `offset`, or `limit` the *folder items list* will be affected accordingly. To fetch more items within the folder, use the [Get items in a folder](e://get-folders-id-items)) endpoint. Not all available fields are returned by default. Use the [fields](#param-fields) query parameter to explicitly request any specific fields. ## Update folder Updates a folder. This can be also be used to move the folder, create shared links, update collaborations, and more. This operation is performed by calling function `updateFolderById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-folders-id/). ``` await client.folders.updateFolderById(folderToUpdate.id, { requestBody: { name: updatedName, description: 'Updated description', } satisfies UpdateFolderByIdRequestBody, } satisfies UpdateFolderByIdOptionalsInput); ``` ### Arguments folderId `string` - The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. Example: "12345" optionalsInput `UpdateFolderByIdOptionalsInput` ### Returns This function returns a value of type `FolderFull`. Returns a folder object for the updated folder Not all available fields are returned by default. Use the [fields](#param-fields) query parameter to explicitly request any specific fields. If the user is moving folders with a large number of items in all of their descendants, the call will be run asynchronously. If the operation is not completed within 10 minutes, the user will receive a 200 OK response, and the operation will continue running. ## Delete folder Deletes a folder, either permanently or by moving it to the trash. This operation is performed by calling function `deleteFolderById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-folders-id/). ``` await client.folders.deleteFolderById(newFolder.id); ``` ### Arguments folderId `string` - The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. Example: "12345" optionalsInput `DeleteFolderByIdOptionalsInput` ### Returns This function returns a value of type `undefined`. Returns an empty response when the folder is successfully deleted or moved to the trash. ## List items in folder Retrieves a page of items in a folder. These items can be files, folders, and web links. To request more information about the folder itself, like its size, use the [Get a folder](#get-folders-id) endpoint instead. This operation is performed by calling function `getFolderItems`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-folders-id-items/). ``` await client.folders.getFolderItems(folderOrigin.id); ``` ### Arguments folderId `string` - The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. Example: "12345" optionalsInput `GetFolderItemsOptionalsInput` ### Returns This function returns a value of type `Items`. Returns a collection of files, folders, and web links contained in a folder. ## Create folder Creates a new empty folder within the specified parent folder. This operation is performed by calling function `createFolder`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-folders/). ``` await client.folders.createFolder({ name: newFolderName, parent: { id: '0' } satisfies CreateFolderRequestBodyParentField, } satisfies CreateFolderRequestBody); ``` ### Arguments requestBody `CreateFolderRequestBody` - Request body of createFolder method optionalsInput `CreateFolderOptionalsInput` ### Returns This function returns a value of type `FolderFull`. Returns a folder object. Not all available fields are returned by default. Use the [fields](#param-fields) query parameter to explicitly request any specific fields. ## Copy folder Creates a copy of a folder within a destination folder. The original folder will not be changed. This operation is performed by calling function `copyFolder`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-folders-id-copy/). ``` await client.folders.copyFolder(folderOrigin.id, { parent: { id: '0' } satisfies CopyFolderRequestBodyParentField, name: copiedFolderName, } satisfies CopyFolderRequestBody); ``` ### Arguments folderId `string` - The unique identifier of the folder to copy. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder with the ID `0` can not be copied. Example: "0" requestBody `CopyFolderRequestBody` - Request body of copyFolder method optionalsInput `CopyFolderOptionalsInput` ### Returns This function returns a value of type `FolderFull`. Returns a new folder object representing the copied folder. Not all available fields are returned by default. Use the [fields](#param-fields) query parameter to explicitly request any specific fields. --- ### FoldersManager **Type:** page | **Section:** Additional Resources FoldersManager Get folder information Update folder Delete folder List items in folder Create folder Copy folder Get folder information… # FoldersManager - [Get folder information](#get-folder-information) - [Update folder](#update-folder) - [Delete folder](#delete-folder) - [List items in folder](#list-items-in-folder) - [Create folder](#create-folder) - [Copy folder](#copy-folder) ## Get folder information Retrieves details for a folder, including the first 100 entries in the folder. Passing `sort`, `direction`, `offset`, and `limit` parameters in query allows you to manage the list of returned [folder items](r://folder--full#param-item-collection). To fetch more items within the folder, use the [Get items in a folder](e://get-folders-id-items) endpoint. This operation is performed by calling function `get_folder_by_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-folders-id/). ``` client.folders.get_folder_by_id("0") ``` ### Arguments folder_id `str` - The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. Example: "12345" fields `Optional[List[str]]` - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested. Additionally this field can be used to query any metadata applied to the file by specifying the `metadata` field as well as the scope and key of the template to retrieve, for example `?fields=metadata.enterprise_12345.contractTemplate`. sort `Optional[GetFolderByIdSort]` - Defines the **second** attribute by which items are sorted. The folder type affects the way the items are sorted: _ **Standard folder**: Items are always sorted by their `type` first, with folders listed before files, and files listed before web links. _ **Root folder**: This parameter is not supported for marker-based pagination on the root folder (the folder with an `id` of `0`). * **Shared folder with parent path to the associated folder visible to the collaborator**: Items are always sorted by their `type` first, with folders listed before files, and files listed before web links. direction `Optional[GetFolderByIdDirection]` - The direction to sort results in. This can be either in alphabetical ascending (`ASC`) or descending (`DESC`) order. offset `Optional[int]` - The offset of the item at which to begin the response. Queries with offset parameter value exceeding 10000 will be rejected with a 400 response. limit `Optional[int]` - The maximum number of items to return per page. if_none_match `Optional[str]` - Ensures an item is only returned if it has changed. Pass in the item's last observed `etag` value into this header and the endpoint will fail with a `304 Not Modified` if the item has not changed since. boxapi `Optional[str]` - The URL, and optional password, for the shared link of this item. This header can be used to access items that have not been explicitly shared with a user. Use the format `shared_link=[link]` or if a password is required then use `shared_link=[link]&shared_link_password=[password]`. This header can be used on the file or folder shared, as well as on any files or folders nested within the item. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `FolderFull`. Returns a folder, including the first 100 entries in the folder. If you used query parameters like `sort`, `direction`, `offset`, or `limit` the *folder items list* will be affected accordingly. To fetch more items within the folder, use the [Get items in a folder](e://get-folders-id-items)) endpoint. Not all available fields are returned by default. Use the [fields](#param-fields) query parameter to explicitly request any specific fields. ## Update folder Updates a folder. This can be also be used to move the folder, create shared links, update collaborations, and more. This operation is performed by calling function `update_folder_by_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-folders-id/). ``` client.folders.update_folder_by_id( folder_to_update.id, name=updated_name, description="Updated description" ) ``` ### Arguments folder_id `str` - The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. Example: "12345" name `Optional[str]` - The optional new name for this folder. The following restrictions to folder names apply: names containing non-printable ASCII characters, forward and backward slashes (`/`, `\`), names with trailing spaces, and names `.` and `..` are not allowed. Folder names must be unique within their parent folder. The name check is case-insensitive, so a folder named `New Folder` cannot be created in a parent folder that already contains a folder named `new folder`. description `Optional[str]` - The optional description of this folder. sync_state `Optional[UpdateFolderByIdSyncState]` - Specifies whether a folder should be synced to a user's device or not. This is used by Box Sync (discontinued) and is not used by Box Drive. can_non_owners_invite `Optional[bool]` - Specifies if users who are not the owner of the folder can invite new collaborators to the folder. parent `Optional[UpdateFolderByIdParent]` shared_link `Optional[UpdateFolderByIdSharedLink]` folder_upload_email `Optional[UpdateFolderByIdFolderUploadEmail]` tags `Optional[List[str]]` - The tags for this item. These tags are shown in the Box web app and mobile apps next to an item. To add or remove a tag, retrieve the item's current tags, modify them, and then update this field. There is a limit of 100 tags per item, and 10,000 unique tags per enterprise. is_collaboration_restricted_to_enterprise `Optional[bool]` - Specifies if new invites to this folder are restricted to users within the enterprise. This does not affect existing collaborations. collections `Optional[List[UpdateFolderByIdCollections]]` - An array of collections to make this folder a member of. Currently we only support the `favorites` collection. To get the ID for a collection, use the [List all collections][1] endpoint. Passing an empty array `[]` or `null` will remove the folder from all collections. [1]: e://get-collections can_non_owners_view_collaborators `Optional[bool]` - Restricts collaborators who are not the owner of this folder from viewing other collaborations on this folder. It also restricts non-owners from inviting new collaborators. When setting this field to `false`, it is required to also set `can_non_owners_invite_collaborators` to `false` if it has not already been set. fields `Optional[List[str]]` - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested. if_match `Optional[str]` - Ensures this item hasn't recently changed before making changes. Pass in the item's last observed `etag` value into this header and the endpoint will fail with a `412 Precondition Failed` if it has changed since. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `FolderFull`. Returns a folder object for the updated folder Not all available fields are returned by default. Use the [fields](#param-fields) query parameter to explicitly request any specific fields. If the user is moving folders with a large number of items in all of their descendants, the call will be run asynchronously. If the operation is not completed within 10 minutes, the user will receive a 200 OK response, and the operation will continue running. ## Delete folder Deletes a folder, either permanently or by moving it to the trash. This operation is performed by calling function `delete_folder_by_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-folders-id/). ``` client.folders.delete_folder_by_id(new_folder.id) ``` ### Arguments folder_id `str` - The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. Example: "12345" recursive `Optional[bool]` - Delete a folder that is not empty by recursively deleting the folder and all of its content. if_match `Optional[str]` - Ensures this item hasn't recently changed before making changes. Pass in the item's last observed `etag` value into this header and the endpoint will fail with a `412 Precondition Failed` if it has changed since. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `None`. Returns an empty response when the folder is successfully deleted or moved to the trash. ## List items in folder Retrieves a page of items in a folder. These items can be files, folders, and web links. To request more information about the folder itself, like its size, use the [Get a folder](#get-folders-id) endpoint instead. This operation is performed by calling function `get_folder_items`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-folders-id-items/). ``` client.folders.get_folder_items(folder_origin.id) ``` ### Arguments folder_id `str` - The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. Example: "12345" fields `Optional[List[str]]` - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested. Additionally this field can be used to query any metadata applied to the file by specifying the `metadata` field as well as the scope and key of the template to retrieve, for example `?fields=metadata.enterprise_12345.contractTemplate`. usemarker `Optional[bool]` - Specifies whether to use marker-based pagination instead of offset-based pagination. Only one pagination method can be used at a time. By setting this value to true, the API will return a `marker` field that can be passed as a parameter to this endpoint to get the next page of the response. marker `Optional[str]` - Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`. offset `Optional[int]` - The offset of the item at which to begin the response. Queries with offset parameter value exceeding 10000 will be rejected with a 400 response. limit `Optional[int]` - The maximum number of items to return per page. sort `Optional[GetFolderItemsSort]` - Defines the **second** attribute by which items are sorted. The folder type affects the way the items are sorted: _ **Standard folder**: Items are always sorted by their `type` first, with folders listed before files, and files listed before web links. _ **Root folder**: This parameter is not supported for marker-based pagination on the root folder (the folder with an `id` of `0`). * **Shared folder with parent path to the associated folder visible to the collaborator**: Items are always sorted by their `type` first, with folders listed before files, and files listed before web links. direction `Optional[GetFolderItemsDirection]` - The direction to sort results in. This can be either in alphabetical ascending (`ASC`) or descending (`DESC`) order. boxapi `Optional[str]` - The URL, and optional password, for the shared link of this item. This header can be used to access items that have not been explicitly shared with a user. Use the format `shared_link=[link]` or if a password is required then use `shared_link=[link]&shared_link_password=[password]`. This header can be used on the file or folder shared, as well as on any files or folders nested within the item. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `Items`. Returns a collection of files, folders, and web links contained in a folder. ## Create folder Creates a new empty folder within the specified parent folder. This operation is performed by calling function `create_folder`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-folders/). ``` client.folders.create_folder(new_folder_name, CreateFolderParent(id="0")) ``` ### Arguments name `str` - The name for the new folder. The following restrictions to folder names apply: names containing non-printable ASCII characters, forward and backward slashes (`/`, `\`), names with trailing spaces, and names `.` and `..` are not allowed. Folder names must be unique within their parent folder. The name check is case-insensitive, so a folder named `New Folder` cannot be created in a parent folder that already contains a folder named `new folder`. parent `CreateFolderParent` - The parent folder to create the new folder within. folder_upload_email `Optional[CreateFolderFolderUploadEmail]` sync_state `Optional[CreateFolderSyncState]` - Specifies whether a folder should be synced to a user's device or not. This is used by Box Sync (discontinued) and is not used by Box Drive. fields `Optional[List[str]]` - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `FolderFull`. Returns a folder object. Not all available fields are returned by default. Use the [fields](#param-fields) query parameter to explicitly request any specific fields. ## Copy folder Creates a copy of a folder within a destination folder. The original folder will not be changed. This operation is performed by calling function `copy_folder`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-folders-id-copy/). ``` client.folders.copy_folder( folder_origin.id, CopyFolderParent(id="0"), name=copied_folder_name ) ``` ### Arguments folder_id `str` - The unique identifier of the folder to copy. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder with the ID `0` can not be copied. Example: "0" name `Optional[str]` - An optional new name for the copied folder. There are some restrictions to the file name. Names containing non-printable ASCII characters, forward and backward slashes (`/`, `\`), as well as names with trailing spaces are prohibited. Additionally, the names `.` and `..` are not allowed either. parent `CopyFolderParent` - The destination folder to copy the folder to. fields `Optional[List[str]]` - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `FolderFull`. Returns a new folder object representing the copied folder. Not all available fields are returned by default. Use the [fields](#param-fields) query parameter to explicitly request any specific fields. --- ### FolderWatermarksManager **Type:** page | **Section:** Additional Resources FolderWatermarksManager Get watermark for folder Apply watermark to folder Remove watermark from folder Get watermark for folder Retrieve… # FolderWatermarksManager - [Get watermark for folder](#get-watermark-for-folder) - [Apply watermark to folder](#apply-watermark-to-folder) - [Remove watermark from folder](#remove-watermark-from-folder) ## Get watermark for folder Retrieve the watermark for a folder. This operation is performed by calling function `getFolderWatermark`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-folders-id-watermark/). ``` await client.folderWatermarks.getFolderWatermark(folder.id); ``` ### Arguments folderId `string` - The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. Example: "12345" optionalsInput `GetFolderWatermarkOptionalsInput` ### Returns This function returns a value of type `Watermark`. Returns an object containing information about the watermark associated for to this folder. ## Apply watermark to folder Applies or update a watermark on a folder. This operation is performed by calling function `updateFolderWatermark`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-folders-id-watermark/). ``` await client.folderWatermarks.updateFolderWatermark(folder.id, { watermark: new UpdateFolderWatermarkRequestBodyWatermarkField({ imprint: 'default' as UpdateFolderWatermarkRequestBodyWatermarkImprintField, }), } satisfies UpdateFolderWatermarkRequestBody); ``` ### Arguments folderId `string` - The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. Example: "12345" requestBody `UpdateFolderWatermarkRequestBody` - Request body of updateFolderWatermark method optionalsInput `UpdateFolderWatermarkOptionalsInput` ### Returns This function returns a value of type `Watermark`. Returns an updated watermark if a watermark already existed on this folder.Returns a new watermark if no watermark existed on this folder yet. ## Remove watermark from folder Removes the watermark from a folder. This operation is performed by calling function `deleteFolderWatermark`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-folders-id-watermark/). ``` await client.folderWatermarks.deleteFolderWatermark(folder.id); ``` ### Arguments folderId `string` - The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. Example: "12345" optionalsInput `DeleteFolderWatermarkOptionalsInput` ### Returns This function returns a value of type `undefined`. An empty response will be returned when the watermark was successfully deleted. --- ### FolderWatermarksManager **Type:** page | **Section:** Additional Resources FolderWatermarksManager Get watermark for folder Apply watermark to folder Remove watermark from folder Get watermark for folder Retrieve… # FolderWatermarksManager - [Get watermark for folder](#get-watermark-for-folder) - [Apply watermark to folder](#apply-watermark-to-folder) - [Remove watermark from folder](#remove-watermark-from-folder) ## Get watermark for folder Retrieve the watermark for a folder. This operation is performed by calling function `get_folder_watermark`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-folders-id-watermark/). ``` client.folder_watermarks.get_folder_watermark(folder.id) ``` ### Arguments folder_id `str` - The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. Example: "12345" extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `Watermark`. Returns an object containing information about the watermark associated for to this folder. ## Apply watermark to folder Applies or update a watermark on a folder. This operation is performed by calling function `update_folder_watermark`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-folders-id-watermark/). ``` client.folder_watermarks.update_folder_watermark( folder.id, UpdateFolderWatermarkWatermark( imprint=UpdateFolderWatermarkWatermarkImprintField.DEFAULT ), ) ``` ### Arguments folder_id `str` - The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. Example: "12345" watermark `UpdateFolderWatermarkWatermark` - The watermark to imprint on the folder. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `Watermark`. Returns an updated watermark if a watermark already existed on this folder.Returns a new watermark if no watermark existed on this folder yet. ## Remove watermark from folder Removes the watermark from a folder. This operation is performed by calling function `delete_folder_watermark`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-folders-id-watermark/). ``` client.folder_watermarks.delete_folder_watermark(folder.id) ``` ### Arguments folder_id `str` - The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. Example: "12345" extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `None`. An empty response will be returned when the watermark was successfully deleted. --- ### Getting raw json response **Type:** page | **Section:** Additional Resources Getting raw json response The response returned by an API endpoint is being automatically translated to the corresponding object basing on… # Getting raw json response The response returned by an API endpoint is being automatically translated to the corresponding object basing on the value of the `type` field. If you want to get the raw response object, you can access response dict using `response_object` property. Example below will print the raw json response returned by the Get file information endpoint. ``` file = client.file('1122334455').get() print(json.dumps(file.response_object)) ``` --- ### Groups **Type:** page | **Section:** Additional Resources Groups Groups contain a set of users, and can be used in place of individual users in some operations, such as collaborations. Create Group… # Groups Groups contain a set of users, and can be used in place of individual users in some operations, such as collaborations. - [Create Group](#create-group) - [Get Group](#get-group) - [Update Group](#update-group) - [Delete Group](#delete-group) - [Add a User to a Group](#add-a-user-to-a-group) - [Get Membership](#get-membership) - [Get Group Memberships for a User](#get-group-memberships-for-a-user) - [Update Membership](#update-membership) - [Remove Membership](#remove-membership) - [Get Group Memberships](#get-group-memberships) - [Get Enterprise Groups](#get-enterprise-groups) - [Get Group Collaborations](#get-group-collaborations) ## Get All Groups To get a list of all groups in the calling user's enterprise, call the [`groups.getAll(options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Groups.html#getAll) method. Note that this requires permission to view an enterprise's groups, which is reserved for enterprise administrators. ``` client.groups.getAll() .then(groups => { /* groups -> { total_count: 1, entries: [ { type: 'group', id: '1786931', name: 'friends' } ], limit: 100, offset: 0 } */ }); ``` ## Create Group To create a new group, call the [`groups.create(name, options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Groups.html#create) method. ``` client.groups.create('My group', {description: 'An example group'}) .then(group => { /* group -> { type: 'group', id: '119720', name: 'Box Employees', created_at: '2013-05-16T15:27:57-07:00', modified_at: '2013-05-16T15:27:57-07:00' } */ }); ``` ## Get Group To retrieve the information for a group, call the [`groups.get(groupID, options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Groups.html#get) method. ``` client.groups.get('11111') .then(group => { /* group -> { type: 'group', id: '11111', name: 'Everyone', created_at: '2014-09-15T13:15:35-07:00', modified_at: '2014-09-15T13:15:35-07:00' } */ }); ``` Requesting information for only the fields you need with the `fields` option can improve performance and reduce the size of the network request. ``` client.groups.get('12345', {fields: 'name,description'}) .then(group => { // ... }); ``` ## Update Group To change the properties of a group object, call the [`groups.update(groupID, updates, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Groups.html#update) method with `updates` being the set of properties to update. ``` client.groups.update('11111', {name: 'New group name'}) .then(group => { /* group -> { type: 'group', id: '11111', name: 'New group name', created_at: '2014-09-15T13:15:35-07:00', modified_at: '2014-09-16T13:15:35-07:00' } */ }); ``` ## Delete Group To delete a group, call the [`groups.delete(groupID, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Groups.html#delete) method. ``` client.groups.delete('11111') .then(() => { // deletion succeeded — no value returned }); ``` ## Add a User to a Group To add a user to a group, call the [`groups.addUser(groupID, userID, options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Groups.html#addUser) method. ``` var groupID = '11111'; var userID = '22222'; client.groups.addUser(groupID, userID, {role: client.groups.userRoles.MEMBER}) .then(membership => { /* membership -> { type: 'group_membership', id: '33333', user: { type: 'user', id: '22222', name: 'Alison Wonderland', login: 'alice@example.com' }, group: { type: 'group', id: '11111', name: 'Employees' }, role: 'member', configurable_permissions: { can_run_reports: false, can_instant_login: false, can_create_accounts: false, can_edit_accounts: false } } */ }); ``` ## Get Membership To retrieve information about a specific membership record, which shows that a given user is in the group, call the [`groups.getMembership(membershipID, options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Groups.html#getMembership) method. ``` client.groups.getMembership('33333') .then(membership => { /* membership -> { type: 'group_membership', id: '33333', user: { type: 'user', id: '22222', name: 'Alison Wonderland', login: 'alice@example.com' }, group: { type: 'group', id: '11111', name: 'Employees' }, role: 'member', configurable_permissions: { can_run_reports: false, can_instant_login: false, can_create_accounts: false, can_edit_accounts: false }, created_at: '2013-05-16T15:27:57-07:00', modified_at: '2013-05-16T15:27:57-07:00' } */ }); ``` Requesting information for only the fields you need with the `fields` option can improve performance and reduce the size of the network request. ``` client.groups.getMembership('33333', {fields: 'user,created_at'}) .then(membership => { /* membership -> { type: 'group_membership', id: '33333', user: { type: 'user', id: '22222', name: 'Alison Wonderland', login: 'alice@example.com' }, created_at: '2013-05-16T15:27:57-07:00' */ }); ``` ## Get Group Memberships for a User To get a list of groups to which a user belongs, call the [`users.getGroupMemberships(userID, options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Users.html#getGroupMemberships) method. Note that this method requires the calling user to have permission to view groups, which is restricted to enterprise administrators. ``` var userID = '22222'; client.users.getGroupMemberships(userID) .then(memberships => { /* memberships -> { total_count: 1, entries: [ { type: 'group_membership', id: '12345', user: { type: 'user', id: '22222', name: 'Alison Wonderland', login: 'alice@example.com' }, group: { type: 'group', id: '11111', name: 'Employees' }, role: 'member' } ], limit: 100, offset: 0 } */ }); ``` ## Update Membership To update a membership record, call the [`groups.updateMembership(membershipID, options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Groups.html#updateMembership) method with `updates` being the properties to update. ``` // Promote a user to group admin client.groups.updateMembership('12345', {role: client.groups.userRoles.ADMIN}) .then(membership => { /* membership -> { type: 'group_membership', id: '33333', user: { type: 'user', id: '22222', name: 'Alison Wonderland', login: 'alice@example.com' }, group: { type: 'group', id: '11111', name: 'Employees' }, role: 'admin', configurable_permissions: { can_run_reports: false, can_instant_login: false, can_create_accounts: false, can_edit_accounts: false }, created_at: '2013-05-16T15:27:57-07:00', modified_at: '2013-05-16T15:27:57-07:00' } */ }); ``` ## Remove Membership To remove a specific membership record, which removes a user from the group, call the [`groups.removeMembership(membershipID, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Groups.html#removeMembership) method with the ID of the membership record to remove. ``` client.groups.removeMembership('33333') .then(() => { // removal succeeded — no value returned }); ``` ## Get Group Memberships To get a list of all memberships to a group, call the [`groups.getMemberships(groupID, options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Groups.html#getMemberships) method with the ID of the group to get the list of memberships for. ``` client.groups.getMemberships('11111') .then(memberships => { /* memberships -> { total_count: 2, entries: [ { type: 'group_membership', id: '44444', user: { type: 'user', id: '22222', name: 'Alice', login: 'alice@example.com' }, group: { type: 'group', id: '11111', name: 'Employees' }, role: 'member' }, { type: 'group_membership', id: '55555', user: { type: 'user', id: '66666', name: 'White Rabbit', login: 'rabbit@example.com' }, group: { type: 'group', id: '11111', name: 'Employees' }, role: 'member' } ], offset: 0, limit: 100 } */ }); ``` ## Get Group Collaborations To get a list of collaborations for a group, which show which items the group has access to, call the [`groups.getCollaborations(groupID, options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Groups.html#getCollaborations) method. ``` client.groups.getCollaborations('11111') .then(collaborations => { /* collaborations -> { total_count: 1, entries: [ { type: 'collaboration', id: '22222', created_by: { type: 'user', id: '33333', name: 'Example User', login: 'user@example.com' }, created_at: '2013-11-14T16:16:20-08:00', modified_at: '2013-11-14T16:16:20-08:00', expires_at: null, status: 'accepted', accessible_by: { type: 'group', id: '11111', name: 'Remote Employees' }, role: 'viewer', acknowledged_at: '2013-11-14T16:16:20-08:00', item: { type: 'folder', id: '44444', sequence_id: '0', etag: '0', name: 'Documents' } } ], offset: 0, limit: 100 } */ }); ``` ## Terminate user groups session To terminate a user's session for groups, call the [`groups.terminateSession(groupIDs, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Groups.html#terminateSession) method. ``` var groupIDs = ['11111', '22222']; client.groups.terminateSession(groupIDs) .then((result) => { /* result -> { message: 'Request is successful, please check the admin events for the status of the job' } */ }); ``` --- ### Groups **Type:** page | **Section:** Additional Resources Groups Groups are sets of users that can be used in collaborations. Get All Groups Create a Group Get Information About a Group Update a… # Groups Groups are sets of users that can be used in collaborations. - [Get All Groups](#get-all-groups) - [Create a Group](#create-a-group) - [Get Information About a Group](#get-information-about-a-group) - [Update a Group](#update-a-group) - [Delete a Group](#delete-a-group) - [Get first page of a Group's Collaborations](#get-a-groups-collaborations) - [Get all of a Group's Collaborations](#get-all-a-groups-collaborations) - [Create Membership](#create-membership) - [Get Membership](#get-membership) - [Update Membership](#update-membership) - [Delete Membership](#delete-membership) - [Get Memberships for Group](#get-memberships-for-group) - [Get Memberships for User](#get-memberships-for-user) ## Get All Groups Calling the static [`getAllGroups(BoxAPIConnection api)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxGroup.html#getAllGroups-com.box.sdk.BoxAPIConnection-) will return an iterable that will page through all of the user's groups. ``` Iterable<BoxGroup.Info> groups = BoxGroup.getAllGroups(api); for (BoxGroup.Info groupInfo : groups) { // Do something with the group. } ``` ## Create a Group The static [`createGroup(BoxAPIConnection api, String name)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxGroup.html#createGroup-com.box.sdk.BoxAPIConnection-java.lang.String-) method will let you create a new group with a specified name. ``` BoxGroup.Info groupInfo = BoxGroup.createGroup(api, "My Group"); ``` ## Get Information About a Group To look up the information about a group by the group's ID, instantiate the [`BoxGroup`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxGroup.html) object with the group ID and then call [`getInfo()`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxGroup.html#getInfo-java.lang.String...-) on the group. You can optionally call [`getInfo(String... fields)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxGroup.html#getInfo-java.lang.String...-) to specify the list of fields to retrieve for the group, which can result in reduced payload size. ``` String groupID = "92875"; BoxGroup.Info groupInfo = new BoxGroup(api, groupID).getInfo(); ``` ## Update a Group To update a group, call [`updateInfo(BoxGroup.Info fieldsToUpdate)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxGroup.html#updateInfo-com.box.sdk.BoxGroup.Info-) method. ``` BoxGroup group = new BoxGroup(api, id); BoxGroup.Info groupInfo = group.getInfo(); groupInfo.setName("New name for My Group"); group.updateInfo(groupInfo); ``` ## Delete a Group A group can be deleted by calling the [`delete()`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxGroup.html#delete--) method. ``` BoxGroup group = new BoxGroup(api, "id"); group.delete(); ``` ## Get first page of a Group's Collaborations The first page of a group's collaborations can be retrieved by calling the [`getCollaborations()`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxGroup.html#getCollaborations--) method. ``` BoxGroup group = new BoxGroup(api, "id"); Collection<BoxCollaboration.Info> collaborations = group.getCollaborations(); ``` ## Get all of a Group's Collaborations All of a group's collaborations can be retrieved by calling the [`getAllCollaborations(String... fields)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxGroup.html#getAllCollaborations--) method. An iterable is returned to allow a user to iterate until the last collaboration. ``` BoxGroup group = new BoxGroup(api, "id"); Iterable<BoxCollaboration.Info> collaborations = group.getAllCollaborations(); ``` ## Create Membership Membership for the group can be created by calling the [`addMembership(BoxUser user)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxGroup.html#addMembership-com.box.sdk.BoxUser-) and [`addMembership(BoxUser user, BoxGroupMembership.GroupRole role)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxGroup.html#addMembership-com.box.sdk.BoxUser-com.box.sdk.BoxGroupMembership.GroupRole-) methods. ``` BoxGroup group = new BoxGroup(api, "groupID"); BoxUser user = new BoxUser(api, "userID"); BoxGroupMembership.Info groupMembershipInfo = group.addMembership(user); ``` ## Get Membership A groups membership can be retrieved by calling the [`BoxGroupMembership.getInfo()`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxGroupMembership.html#getInfo--) method. ``` BoxGroupMembership membership = new BoxGroupMembership(api, id); BoxGroupMembership.Info groupMembershipInfo = membership.getInfo(); ``` ## Update Membership A groups membership can be updated by calling the [`BoxGroupMembership.updateInfo(BoxGroupMembership.Info fieldsToUpdate)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxGroupMembership.html#updateInfo-com.box.sdk.BoxGroupMembership.Info-) method. ``` BoxGroupMembership membership = new BoxGroupMembership(api, id); BoxGroupMembership.Info info = membership.new Info(); info.setGroupRole(BoxGroupMembership.GroupRole.MEMBER); membership.updateInfo(info); ``` ## Delete Membership A group can be deleted by calling the [`BoxGroupMembership.delete()`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxGroupMembership.html#delete--) method. ``` BoxGroupMembership membership = new BoxGroupMembership(api, id); membership.delete(); ``` ## Get Memberships for Group Calling the [`getAllMemberships(String... fields)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxGroup.html#getAllMemberships-java.lang.String...-) will return an iterable that will page through all of the group's memberships. Optional parameters can be used to retrieve specific fields of the Group Membership object. ``` BoxGroup group = new BoxGroup(api, id); Iterable<BoxGroupMembership.Info> memberships = group.getAllMemberships(); for (BoxGroupMembership.Info membershipInfo : memberships) { // Do something with the membership. } ``` ## Get Memberships for User Calling the [`BoxUser.getAllMemberships(String... fields)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxUser.html#getAllMemberships-java.lang.String...-) will return an iterable that will page through all of the user's memberships. Optional parameters can be used to retrieve specific fields of the Group Membership object. ``` BoxUser user = new BoxUser(api, id); Iterable<BoxGroupMembership.Info> memberships = user.getAllMemberships(); for (BoxGroupMembership.Info membershipInfo : memberships) { // Do something with the membership. } ``` --- ### Groups **Type:** page | **Section:** Additional Resources Groups Groups are sets of users that can be used in collaborations. List Groups Create a Group Get Information about a Group Update a Group… # Groups Groups are sets of users that can be used in collaborations. - [List Groups](#list-groups) - [Create a Group](#create-a-group) - [Get Information about a Group](#get-information-about-a-group) - [Update a Group](#update-a-group) - [Delete a Group](#delete-a-group) - [Get a Group's Collaborations](#get-a-groups-collaborations) - [Add User to Group](#add-user-to-group) - [Get Information about a Group Membership](#get-information-about-a-group-membership) - [Update Group Membership](#update-group-membership) - [Remove User from Group](#remove-user-from-group) - [List Group Members](#list-group-members) - [List Memberships for User](#list-memberships-for-user) ## List Groups Calling [`client.get_groups(name=None, limit=None, offset=None, fields=None)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.client.html#boxsdk.client.client.Client.get_groups) will return a `BoxObjectCollection` that allows you to iterate over the [`Group`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.group.Group) objects representing groups in the enterprise. ``` groups = client.get_groups() for group in groups: print(f'Group "{group.name}" has ID "{group.id}"') ``` Alternatively, you can set a filter on the name of the groups by passing the `name` parameter: ``` group_name = 'Example Group' groups = client.get_groups(group_name) for group in groups: print(f'Group {group.id} has a name matching {group_name}') ``` ## Create a Group To create a new group, call [`client.create_group(name, provenance=None, external_sync_identifier=None, description=None, invitability_level=None, member_viewability_level=None, fields=None)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.client.html#boxsdk.client.client.Client.create_group) with the name of the group and any optional group properties you want to set. This method returns a [`Group`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.group.Group) object representing the created group. You can read more about the optional parameters in the [Create Group API documentation](https://developer.box.com/en/reference/post-groups/). ``` created_group = client.create_group('Example Group') print(f'Created group with ID {created_group.id}') ``` ## Get Information about a Group To retrieve information about a group, first call [`client.group(group_id)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.client.html#boxsdk.client.client.Client.group) to initialize a [`Group`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.group.Group) object. Then, call [`group.get(*, fields=None, headers=None, **kwargs)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.base_object.BaseObject.get) to retrieve the data about that group. This method returns a new [`Group`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.group.Group) object with fields populated by data form the API, leaving the original object unmodified. ``` group = client.group(group_id='11111').get() print(f'Got group {group.name}') ``` You can optionally specify a list of `fields` to retrieve from the API, in order to filter out fields you don't need or add fields that are not returned from the API by default: ``` group = client.group(group_id='11111').get(['name', 'description', 'provenance']) print(f'The "{group.name}" group ({group.description}) came from {group.provenance}') ``` ## Update a Group To update a group, call [`group.update_info(data=group_update)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.base_object.BaseObject.update_info) with a `dict` of the group properties to update. This method returns a new [`Group`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.group.Group) object with the updates applied, leaving the original object unmodified. ``` group_update = {'name': 'New Group Name'} updated_group = client.group(group_id='11111').update_info(data=group_update) print(f'Changed the name of group {updated_group.id} to "{updated_group.name}"') ``` ## Delete a Group To delete a group, call [`group.delete()`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.base_object.BaseObject.delete). This method returns `True` to indicate that the deletion was successful. ``` client.group(group_id='11111').delete() print('The group was deleted!') ``` ## Get a Group's Collaborations To retrieve all collaborations for a group, call [`group.get_collaborations(limit=None, offset=None, fields=None)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.group.Group.get_collaborations). This method returns a `BoxObjectCollection` that allows you to iterate over the [`Collaboration`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.collaboration.Collaboration) objects in the collection. ``` collaborations = client.group(group_id='11111').get_collaborations() for collaboration in collaborations: print(f'The group is collaborated on {collaboration.item.type} {collaboration.item.id}') ``` ## Add User to Group To add a new member to the group, call [`group.add_member(user, role='member', configurable_permissions=None)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.group.Group.add_member) with the [`User`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.user.User) to add to the group. This method returns a new [`GroupMembership`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.group_membership.GroupMembership) object representing the presence of the user in the group. You can optionally specify the user's `role` in the group, and for users with an admin role you can configure which permissions they have in the group by passing a `dict` of [group permissions](https://developer.box.com/en/reference/resources/group-membership/) to `configurable_permissions`. ``` user = client.user('1111') membership = client.group(group_id='11111').add_member(user) print(f'Added {membership.user.name} to the {membership.group.name} group!') ``` ## Get Information about a Group Membership To retrieve information about a group membership, first call [`client.group_membership(group_membership_id)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.client.html#boxsdk.client.client.Client.group_membership) to initialize the [`GroupMembership`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.group_membership.GroupMembership) object. Then, call [`group_membership.get(*, fields=None, headers=None, **kwargs)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.base_object.BaseObject.get) to retrieve data about the group membership from the API. This returns a new [`GroupMembership`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.group_membership.GroupMembership) object with fields populated by data from the API, leaving the original object unmodified. ``` membership_id = '11111' membership = client.group_membership(membership_id).get() print(f'User "{membership.user.name}" is a member of the {membership.group.name} group') ``` ## Update Group Membership To update a group membership, call [`membership.update_info(data=membership_update)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.base_object.BaseObject.update_info) with a `dict` of properties to update on the membership object. This method returns a new [`GroupMembership`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.group_membership.GroupMembership) object with the changes applied, leaving the original object unmodified. ``` membership_id = '1234' membership_update = {'role': 'admin'} updated_membership = client.group_membership(membership_id).update_info(data=membership_update) print(f'Updated {updated_membership.user.name}\'s group role to {updated_membership.role}') ``` ## Remove User from Group To remove a user from a group, delete their associated group membership by calling [`group_membership.delete()`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.base_object.BaseObject.delete). This method returns `True` to indicate that the deletion was successful. ``` membership_id = '1234' client.group_membership(membership_id).delete() print('The membership was deleted!') ``` ## List Group Members To retrieve all of the memberships for a given group, call [`group.get_memberships(limit=None, offset=0, fields=None)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.group.Group.get_memberships). This method returns a `BoxObjectCollection` that allows you to iterate over all of the [`GroupMembership`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.group_membership.GroupMembership) objects in the collection. ``` group_memberships = client.group(group_id='11111').get_memberships() for membership in group_memberships: print(f'{membership.user.name} is a {membership.role} of the {membership.group.name} group') ``` ## List Memberships for User To retrieve all of the groups a user belongs to, get a list of their associated group memberships by calling [`user.get_group_memberships(limit=None, offset=0, fields=None)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.user.User.get_group_memberships). This method returns a `BoxObjectCollection` that allows you to iterate over the [`GroupMembership`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.group_membership.GroupMembership) objects in the collection. ``` user_memberships = client.user(user_id='33333').get_group_memberships() for membership in user_memberships: print(f'User is in the {membership.group.name} group') ``` --- ### Groups **Type:** page | **Section:** Additional Resources Groups Groups contain a set of users, and can be used in place of individual users in some operations, such as collaborations. Create Group… # Groups Groups contain a set of users, and can be used in place of individual users in some operations, such as collaborations. - [Create Group](#create-group) - [Get Group](#get-group) - [Get All Groups](#get-all-groups) - [Update Group](#update-group) - [Delete Group](#delete-group) - [Get Group Collaborations](#get-group-collaborations) - [Add a User to a Group](#add-a-user-to-a-group) - [Update Membership](#update-membership) - [Remove Membership](#remove-membership) - [Get Group Memberships](#get-group-memberships) - [Get Group Memberships for a User](#get-group-memberships-for-a-user) ## Create Group To create a new group, call `GroupsManager.CreateAsync(BoxGroupRequest groupRequest, IEnumerable<string> fields = null)` with the parameters for the group being created. ``` var groupParams = new BoxGroupRequest() { Name = "Engineers" }; BoxGroup group = await client.GroupsManager.CreateAsync(groupParams); ``` ## Get Group To retrieve the information for a group, call `GroupsManager.GetGroupAsync(string id, IEnumerable<string> fields = null)` with the ID of the group. ``` BoxGroup group = await client.GroupsManager.GetGroupAsync("11111"); ``` ## Get All Groups To get a list of all groups in the calling user's enterprise, call `GroupsManager.GetAllGroupsAsync(int? limit = null, int? offset = null, IEnumerable<string> fields = null, bool autoPaginate = false, string filterTerm = null)`. Note that this requires permission to view an enterprise's groups, which is reserved for enterprise administrators. ``` BoxCollection<BoxGroup> groups = await client.GroupsManager.GetAllGroupsAsync(); ``` ## Update Group To change the properties of a group object, call the `GroupsManager.UpdateAsync(string id, BoxGroupRequest groupRequest, IEnumerable<string> fields = null)` method with the set of properties to update. ``` var updates = new BoxGroupRequest() { Name = "New group name" }; BoxGroup updatedGroup = await client.GroupsManager.UpdateAsync("11111", updates); ``` ## Delete Group To delete a group, call `(string id)` with the ID of the group to delete. ``` await client.GroupsManager.DeleteAsync("11111"); ``` ## Get Group Collaborations To get a list of collaborations for a group, which show which items the group has access to, call `GroupsManager.GetCollaborationsForGroupAsync(string groupId, int? limit = null, int? offset = null, IEnumerable<string> fields = null, bool autoPaginate = false)` with the ID of the group. ``` BoxCollection<BoxCollaboration> groupCollaborations = await client.GroupsManager .GetCollaborationsForGroupAsync(groupId: "11111"); ``` ## Add a User to a Group To add a user to a group, call `GroupsManager.AddMemberToGroupAsync(BoxGroupMembershipRequest membershipRequest, IEnumerable<string> fields = null)`. ``` var requestParams = new BoxGroupMembershipRequest() { User = new BoxRequestEntity() { Id = "22222" }, Group = new BoxGroupRequest() { Id = "11111" } }; BoxGroupMembership membership = await client.GroupsManager.AddMemberToGroupAsync(requestParams); ``` To retrieve information about a specific membership record, which shows that a given user is in the group, call `GroupsManager.GetGroupMembershipAsync(string id, IEnumerable<string> fields = null)` with the ID of the membership object. ``` BoxGroupMembership membership = await client.GroupsManager.GetGroupMembershipAsync("33333"); ``` ## Update Membership To update a membership record, call `GroupsManager.UpdateGroupMembershipAsync(string membershipId, BoxGroupMembershipRequest memRequest, IEnumerable<string> fields = null)` with the ID of the membership object and the fields to update. ``` var updates = new BoxGroupMembershipRequest() { Role = "admin" }; BoxGroupMembership updatedMembership = await client.GroupsManager .UpdateGroupMembershipAsync("33333", updates); ``` ## Remove Membership To remove a specific membership record, which removes a user from the group, call the `GroupsManager.DeleteGroupMembershipAsync(string id)` method with the ID of the membership record to remove. ``` await client.GroupsManager.DeleteGroupMembershipAsync("33333"); ``` ## Get Group Memberships To get a list of all memberships to a group, call the `GroupsManager.GetAllGroupMembershipsForGroupAsync(string groupId, int? limit = null, int? offset = null, IEnumerable<string> fields = null, bool autoPaginate = false)` method with the ID of the group to get the list of memberships for. ``` BoxCollection<BoxGroupMembership> memberships = await client.GroupsManager .GetAllGroupMembershipsForGroupAsync("11111"); ``` ## Get Group Memberships for a User To get a list of groups to which a user belongs, call the `GroupsManager.GetAllGroupMembershipsForUserAsync(string userId, int? limit = null, int? offset = null, IEnumerable<string> fields = null, bool autoPaginate = false)` method. Note that this method requires the calling user to have permission to view groups, which is restricted to enterprise administrators. ``` BoxCollection<BoxGroupMembership> memberships = await client.GroupsManager .GetAllGroupMembershipsForUserAsync(userId: "11111"); ``` --- ### Groups **Type:** page | **Section:** Additional Resources Groups Groups contain a set of users and can be used in place of users in some operations such as collaborations. Create Group Update Group… # Groups Groups contain a set of users and can be used in place of users in some operations such as collaborations. - [Create Group](#create-group) - [Update Group](#update-group) - [Get Group Info](#get-group-info) - [Get Enterprise Groups](#get-enterprise-groups) - [Delete Group](#delete-group) [Group Membership](#group-membership) - [Get Group Membership Info](#get-group-membership-info) - [Create Group Membership](#create-group-membership) - [Update Group Membership](#update-group-membership) - [Delete Group Membership](#delete-group-membership) - [Get Memberships for Group](#get-memberships-for-group) - [Get Memberships for User](#get-memberships-for-user) - [Get Collaborations for Group](#get-collaborations-for-group) ## Create Group To create a new group, call [`client.groups.create(name: String, provenance: String?, externalSyncIdentifier: String?, description: String?, invitabilityLevel: GroupInvitabilityLevel?, memberViewabilityLevel: GroupMemberViewabilityLevel, fields: [String]?, completion: @escaping Callback<Group>)`][create_group] with the name of the group you wish to create. You can control which fields are returned in the resulting `Group` object by passing the `fields` parameter. ``` client.groups.create(name: "Team A", provenance: "Test", externalSyncIdentifier: "Test Sync", description: "Test Description", invitabilityLevel: .allManagedUsers, memberViewabilityLevel: .allManagedUsers) { (result: Result<Group, BoxSDKError>) in guard case let .success(group) = result else { print("Error creating new group") return } print("Group \(group.name) was created") } ``` ## Update Group To update an existing group, call [`client.groups.update(groupId: String, name: String?, provenance: NullableParameter<String>?, externalSyncIdentifier: NullableParameter<String>?, description: NullableParameter<String>?, invitabilityLevel: GroupInvitabilityLevel?, memberViewabilityLevel: GroupMemberViewabilityLevel?, fields: [String]?, completion: @escaping Callback<Group>)`](https://opensource.box.com/box-ios-sdk/Classes/GroupsModule.html#/s:6BoxSDK12GroupsModuleC6update7groupId4name10provenance22externalSyncIdentifier11description17invitabilityLevel017memberViewabilityO06fields10completionySS_SSSgAA17NullableParameterOySSGSgA2rA017GroupInvitabilityO0OSgAA0v6MemberqO0OSgSaySSGSgys6ResultOyAA0V0CAA0A8SDKErrorCGctF) with the ID of the group. You can control which fields are returned in the resulting `Group` object by passing the `fields` parameter. ``` client.groups.update(groupId: "11111", name: "Team A", provenance: .value("Test"), externalSyncIdentifier: .value("Test Sync"), description: .value("Test Description"), invitabilityLevel: .allManagedUsers, memberViewabilityLevel: .allManagedUsers) { (result: Result<Group, BoxSDKError>) in guard case let .success(group) = result else { print("Error updating the group") return } print("Group \(group.name) was updated with description: \(group.description)") } ``` ## Get Group Info To retrieve information about a group, call [`client.groups.get(groupId: String, fields: [String]?, completion: @escaping Callback<Group>)`](https://opensource.box.com/box-ios-sdk/Classes/GroupsModule.html#/s:6BoxSDK12GroupsModuleC3get7groupId6fields10completionySS_SaySSGSgys6ResultOyAA5GroupCAA0A8SDKErrorCGctF) with the ID of the group. You can control which fields are returned in the resulting `Group` object by passing the `fields` parameter. ``` client.groups.get(groupId: "12345") { (result: Result<Group, BoxSDKError>) in guard case let .success(group) = result else { print("Error getting group information") return } print("Group with name \(group.name) was retrieved.") } ``` ## Get Enterprise Groups To retrieve information about the groups within the enterprise, call [`client.groups.listForEnterprise(name: String?, offset: Int?, limit: Int?, fields: [String]?)`](https://opensource.box.com/box-ios-sdk/Classes/GroupsModule.html#/s:6BoxSDK12GroupsModuleC17listForEnterprise4name6offset5limit6fields10completionySSSg_SiSgAKSaySSGSgys6ResultOyAA14PagingIteratorCyAA5GroupCGAA0A8SDKErrorCGctF). You can also pass in a `name` paramter to act as a filter. This method will return an iterator object, which is used to retrieve groups in the enterprise. ``` let iterator = client.groups.listForEnterprise() iterator.next { results in switch results { case let .success(page): for group in page.entries { print("Group with name \(group.name) retrieved") } case let .failure(error): print(error) } } ``` ## Delete Group To delete a group, call [`client.groups.delete(groupId: String, completion: @escaping Callback<Void>)`](https://opensource.box.com/box-ios-sdk/Classes/GroupsModule.html#/s:6BoxSDK12GroupsModuleC6delete7groupId10completionySS_ys6ResultOyytAA0A8SDKErrorCGctF) with the ID of the group to delete. ``` client.groups.delete(groupId: "12345") { (result: Result<Void, BoxSDKError>) in guard case .success = result else { print("Error deleting group") return } print("Group was successfully deleted.") } ``` # Group Membership ## Get Group Membership Info To retrieve information about a specified group membership, call [`client.groups.getMembershipInfo(membershipId: String, fields: [String]?, completion: @escaping Callback<GroupMembership>)`](https://opensource.box.com/box-ios-sdk/Classes/GroupsModule.html#/s:6BoxSDK12GroupsModuleC17getMembershipInfo12membershipId6fields10completionySS_SaySSGSgys6ResultOyAA05GroupF0CAA0A8SDKErrorCGctF) with the ID of the group membership. You can control which fields are returned on the resulting `Group Membership` object by passing the desired field names in the optional `fields` parameter. ``` client.groups.getMembershipInfo(membershipId: "12345") { (result: Result<GroupMembership, BoxSDKError>) in guard case let .success(membership) = result else { print("Error retrieving group membership information") return } print("Group Membership for group \(membership.group?.name) was retrieved") } ``` ## Create Group Membership To create a new group membership, call [`client.groups.createMembership(userId: String, groupId: String, role: GroupRole?, configurablePermission: NullableParameter<ConfigurablePermissionData>?, fields: [String]?, completion: @escaping Callback<GroupMembership>)`](https://opensource.box.com/box-ios-sdk/Classes/GroupsModule.html#/s:6BoxSDK12GroupsModuleC16createMembership6userId05groupH04role22configurablePermission6fields10completionySS_SSAA9GroupRoleOSgAA17NullableParameterOyAA012ConfigurableL4DataVGSgSaySSGSgys6ResultOyAA0oF0CAA0A8SDKErrorCGctF). You can control which fields are returned on the resulting `Group Membership` object by passing the desired field names in the optional `fields` parameter. ``` client.createMembership(userId: "54321", groupId: "11111", role: .admin, configurablePermission: .value(ConfigurablePermissionData(canRunReports: true, canInstantLogin: true, canCreateAccounts: false, canEditAccounts: true))) { (result: Result<GroupMembership, BoxSDKError>) in guard case let .success(membership) = result else { print("Error creating group membership") return } print("Group membership for group \(membership.group?.name) was created") } ``` ## Update Group Membership To update an existing group membership, call [`client.groups.updateMembership(membershipId: String, role: GroupRole?, configurablePermission: NullableParameter<ConfigurablePermissionData>?, fields: [String]?, completion: @escaping Callback<GroupMembership>)`](https://opensource.box.com/box-ios-sdk/Classes/GroupsModule.html#/s:6BoxSDK12GroupsModuleC16updateMembership12membershipId4role22configurablePermission6fields10completionySS_AA9GroupRoleOSgAA17NullableParameterOyAA012ConfigurableK4DataVGSgSaySSGSgys6ResultOyAA0nF0CAA0A8SDKErrorCGctF) with the ID of the group membership to update. ``` client.groups.updateMembership(membershipId: "12345", role: .admin, configurablePermission: .value(ConfigurablePermissionData(canRunReports: true, canInstantLogin: true, canCreateAccounts: false, canEditAccounts: true))) { (result: Result<GroupMembership, BoxSDKError>) in guard case let .success(membership) = result else { print("Error updating group membership") return } print("Group membership with ID \(membership.id) was updated") } ``` ## Delete Group Membership To delete a group membership, call [`client.groups.deleteMembership(membershipId: String, completion: @escaping: Callback<Void>)`](https://opensource.box.com/box-ios-sdk/Classes/GroupsModule.html#/s:6BoxSDK12GroupsModuleC16deleteMembership12membershipId10completionySS_ys6ResultOyytAA0A8SDKErrorCGctF) with the ID of the group membership to delete. ``` client.groups.deleteMembership(membershipId: "12345") { (result: Result<Void, BoxSDKError>) in guard case .success = result else { print("Error deleting group membership") return } print("Group Membership was successfully deleted.") } ``` ## Get Memberships for Group To retrieve information about the memberships in a group, call [`client.groups.listMemberships(groupID: String, offset: Int?, limit: Int?, fields: [String]?)`](https://opensource.box.com/box-ios-sdk/Classes/GroupsModule.html#/s:6BoxSDK12GroupsModuleC15listMemberships7groupId6offset5limit6fields10completionySS_SiSgAJSaySSGSgys6ResultOyAA14PagingIteratorCyAA15GroupMembershipCGAA0A8SDKErrorCGctF) with the ID of the group to retrieve group memberships for. This method will return an iterator object, which is used to retrieve the memberships. ``` let iterator = client.groups.listMembership(groupId: "12345") iterator.next { result in switch results { case let .success(page): for membership in page.entries { print("Group Membership with ID \(membership.id) was retrieved") } case let .failure(error): print(error) } } ``` ## Get Memberships for User To retrieve information about the group memberships for a given user, call [`client.groups.listMembershipsForUser(userId: String, offset: Int?, limit: Int?, fields: [String]?)`](https://opensource.box.com/box-ios-sdk/Classes/GroupsModule.html#/s:6BoxSDK12GroupsModuleC22listMembershipsForUser6userId6offset5limit6fields10completionySS_SiSgAJSaySSGSgys6ResultOyAA14PagingIteratorCyAA15GroupMembershipCGAA0A8SDKErrorCGctF) with the ID of the user to retreive group memberships for. This method will return an iterator object, which is used to retrieve the memberships. ``` let iterator = client.groups.listMembershipsForUser(userId: "12345") iterator.next { result in switch results { case let .success(page): for membership in page.entries { print("Group Membership with ID \(membership.id) was retrieved") } case let .failure(error): print(error) } } ``` ## Get Collaborations for Group To retrieve all group collaborations for a given group, call [`client.groups.listCollaborations(groupId: String, offset: Int?, limit: Int? fields: [String]?)`](https://opensource.box.com/box-ios-sdk/Classes/GroupsModule.html#/s:6BoxSDK12GroupsModuleC18listCollaborations7groupId6offset5limit6fields10completionySS_SiSgAJSaySSGSgys6ResultOyAA14PagingIteratorCyAA13CollaborationCGAA0A8SDKErrorCGctF) with the ID of the group to retrieve collaborations for. This method will return an iterator object, which is used to retrieve the collaborations. ``` let iterator = client.groups.listCollaborations(groupId: "12345") iterator.next { results in switch results { case let .success(page): for collaboration in page.entries { print("Collaboration with ID \(collaboration.id) was retrieved") } case let .failure(error): print(error) } } ``` --- ### Groups **Type:** page | **Section:** Additional Resources Groups Groups contain a set of users and can be used in place of users in some operations such as collaborations. Create Group Update Group… # Groups Groups contain a set of users and can be used in place of users in some operations such as collaborations. - [Create Group](#create-group) - [Update Group](#update-group) - [Get Group Info](#get-group-info) - [Get Enterprise Groups](#get-enterprise-groups) - [Delete Group](#delete-group) [Group Membership](#group-membership) - [Get Group Membership Info](#get-group-membership-info) - [Create Group Membership](#create-group-membership) - [Update Group Membership](#update-group-membership) - [Delete Group Membership](#delete-group-membership) - [Get Memberships for Group](#get-memberships-for-group) - [Get Memberships for User](#get-memberships-for-user) - [Get Collaborations for Group](#get-collaborations-for-group) ## Create Group To create a new group, call [`client.groups.create(name: String, provenance: String?, externalSyncIdentifier: String?, description: String?, invitabilityLevel: GroupInvitabilityLevel?, memberViewabilityLevel: GroupMemberViewabilityLevel, fields: [String]?, completion: @escaping Callback<Group>)`][create_group] with the name of the group you wish to create. You can control which fields are returned in the resulting `Group` object by passing the `fields` parameter. ``` client.groups.create(name: "Team A", provenance: "Test", externalSyncIdentifier: "Test Sync", description: "Test Description", invitabilityLevel: .allManagedUsers, memberViewabilityLevel: .allManagedUsers) { (result: Result<Group, BoxSDKError>) in guard case let .success(group) = result else { print("Error creating new group") return } print("Group \(group.name) was created") } ``` ## Update Group To update an existing group, call [`client.groups.update(groupId: String, name: String?, provenance: NullableParameter<String>?, externalSyncIdentifier: NullableParameter<String>?, description: NullableParameter<String>?, invitabilityLevel: GroupInvitabilityLevel?, memberViewabilityLevel: GroupMemberViewabilityLevel?, fields: [String]?, completion: @escaping Callback<Group>)`](https://opensource.box.com/box-ios-sdk/Classes/GroupsModule.html#/s:6BoxSDK12GroupsModuleC6update7groupId4name10provenance22externalSyncIdentifier11description17invitabilityLevel017memberViewabilityO06fields10completionySS_SSSgAA17NullableParameterOySSGSgA2rA017GroupInvitabilityO0OSgAA0v6MemberqO0OSgSaySSGSgys6ResultOyAA0V0CAA0A8SDKErrorCGctF) with the ID of the group. You can control which fields are returned in the resulting `Group` object by passing the `fields` parameter. ``` client.groups.update(groupId: "11111", name: "Team A", provenance: .value("Test"), externalSyncIdentifier: .value("Test Sync"), description: .value("Test Description"), invitabilityLevel: .allManagedUsers, memberViewabilityLevel: .allManagedUsers) { (result: Result<Group, BoxSDKError>) in guard case let .success(group) = result else { print("Error updating the group") return } print("Group \(group.name) was updated with description: \(group.description)") } ``` ## Get Group Info To retrieve information about a group, call [`client.groups.get(groupId: String, fields: [String]?, completion: @escaping Callback<Group>)`](https://opensource.box.com/box-ios-sdk/Classes/GroupsModule.html#/s:6BoxSDK12GroupsModuleC3get7groupId6fields10completionySS_SaySSGSgys6ResultOyAA5GroupCAA0A8SDKErrorCGctF) with the ID of the group. You can control which fields are returned in the resulting `Group` object by passing the `fields` parameter. ``` client.groups.get(groupId: "12345") { (result: Result<Group, BoxSDKError>) in guard case let .success(group) = result else { print("Error getting group information") return } print("Group with name \(group.name) was retrieved.") } ``` ## Get Enterprise Groups To retrieve information about the groups within the enterprise, call [`client.groups.listForEnterprise(name: String?, offset: Int?, limit: Int?, fields: [String]?)`](https://opensource.box.com/box-ios-sdk/Classes/GroupsModule.html#/s:6BoxSDK12GroupsModuleC17listForEnterprise4name6offset5limit6fields10completionySSSg_SiSgAKSaySSGSgys6ResultOyAA14PagingIteratorCyAA5GroupCGAA0A8SDKErrorCGctF). You can also pass in a `name` paramter to act as a filter. This method will return an iterator object, which is used to retrieve groups in the enterprise. ``` let iterator = client.groups.listForEnterprise() iterator.next { results in switch results { case let .success(page): for group in page.entries { print("Group with name \(group.name) retrieved") } case let .failure(error): print(error) } } ``` ## Delete Group To delete a group, call [`client.groups.delete(groupId: String, completion: @escaping Callback<Void>)`](https://opensource.box.com/box-ios-sdk/Classes/GroupsModule.html#/s:6BoxSDK12GroupsModuleC6delete7groupId10completionySS_ys6ResultOyytAA0A8SDKErrorCGctF) with the ID of the group to delete. ``` client.groups.delete(groupId: "12345") { (result: Result<Void, BoxSDKError>) in guard case .success = result else { print("Error deleting group") return } print("Group was successfully deleted.") } ``` # Group Membership ## Get Group Membership Info To retrieve information about a specified group membership, call [`client.groups.getMembershipInfo(membershipId: String, fields: [String]?, completion: @escaping Callback<GroupMembership>)`](https://opensource.box.com/box-ios-sdk/Classes/GroupsModule.html#/s:6BoxSDK12GroupsModuleC17getMembershipInfo12membershipId6fields10completionySS_SaySSGSgys6ResultOyAA05GroupF0CAA0A8SDKErrorCGctF) with the ID of the group membership. You can control which fields are returned on the resulting `Group Membership` object by passing the desired field names in the optional `fields` parameter. ``` client.groups.getMembershipInfo(membershipId: "12345") { (result: Result<GroupMembership, BoxSDKError>) in guard case let .success(membership) = result else { print("Error retrieving group membership information") return } print("Group Membership for group \(membership.group?.name) was retrieved") } ``` ## Create Group Membership To create a new group membership, call [`client.groups.createMembership(userId: String, groupId: String, role: GroupRole?, configurablePermission: NullableParameter<ConfigurablePermissionData>?, fields: [String]?, completion: @escaping Callback<GroupMembership>)`](https://opensource.box.com/box-ios-sdk/Classes/GroupsModule.html#/s:6BoxSDK12GroupsModuleC16createMembership6userId05groupH04role22configurablePermission6fields10completionySS_SSAA9GroupRoleOSgAA17NullableParameterOyAA012ConfigurableL4DataVGSgSaySSGSgys6ResultOyAA0oF0CAA0A8SDKErrorCGctF). You can control which fields are returned on the resulting `Group Membership` object by passing the desired field names in the optional `fields` parameter. ``` client.createMembership(userId: "54321", groupId: "11111", role: .admin, configurablePermission: .value(ConfigurablePermissionData(canRunReports: true, canInstantLogin: true, canCreateAccounts: false, canEditAccounts: true))) { (result: Result<GroupMembership, BoxSDKError>) in guard case let .success(membership) = result else { print("Error creating group membership") return } print("Group membership for group \(membership.group?.name) was created") } ``` ## Update Group Membership To update an existing group membership, call [`client.groups.updateMembership(membershipId: String, role: GroupRole?, configurablePermission: NullableParameter<ConfigurablePermissionData>?, fields: [String]?, completion: @escaping Callback<GroupMembership>)`](https://opensource.box.com/box-ios-sdk/Classes/GroupsModule.html#/s:6BoxSDK12GroupsModuleC16updateMembership12membershipId4role22configurablePermission6fields10completionySS_AA9GroupRoleOSgAA17NullableParameterOyAA012ConfigurableK4DataVGSgSaySSGSgys6ResultOyAA0nF0CAA0A8SDKErrorCGctF) with the ID of the group membership to update. ``` client.groups.updateMembership(membershipId: "12345", role: .admin, configurablePermission: .value(ConfigurablePermissionData(canRunReports: true, canInstantLogin: true, canCreateAccounts: false, canEditAccounts: true))) { (result: Result<GroupMembership, BoxSDKError>) in guard case let .success(membership) = result else { print("Error updating group membership") return } print("Group membership with ID \(membership.id) was updated") } ``` ## Delete Group Membership To delete a group membership, call [`client.groups.deleteMembership(membershipId: String, completion: @escaping: Callback<Void>)`](https://opensource.box.com/box-ios-sdk/Classes/GroupsModule.html#/s:6BoxSDK12GroupsModuleC16deleteMembership12membershipId10completionySS_ys6ResultOyytAA0A8SDKErrorCGctF) with the ID of the group membership to delete. ``` client.groups.deleteMembership(membershipId: "12345") { (result: Result<Void, BoxSDKError>) in guard case .success = result else { print("Error deleting group membership") return } print("Group Membership was successfully deleted.") } ``` ## Get Memberships for Group To retrieve information about the memberships in a group, call [`client.groups.listMemberships(groupID: String, offset: Int?, limit: Int?, fields: [String]?)`](https://opensource.box.com/box-ios-sdk/Classes/GroupsModule.html#/s:6BoxSDK12GroupsModuleC15listMemberships7groupId6offset5limit6fields10completionySS_SiSgAJSaySSGSgys6ResultOyAA14PagingIteratorCyAA15GroupMembershipCGAA0A8SDKErrorCGctF) with the ID of the group to retrieve group memberships for. This method will return an iterator object, which is used to retrieve the memberships. ``` let iterator = client.groups.listMembership(groupId: "12345") iterator.next { result in switch results { case let .success(page): for membership in page.entries { print("Group Membership with ID \(membership.id) was retrieved") } case let .failure(error): print(error) } } ``` ## Get Memberships for User To retrieve information about the group memberships for a given user, call [`client.groups.listMembershipsForUser(userId: String, offset: Int?, limit: Int?, fields: [String]?)`](https://opensource.box.com/box-ios-sdk/Classes/GroupsModule.html#/s:6BoxSDK12GroupsModuleC22listMembershipsForUser6userId6offset5limit6fields10completionySS_SiSgAJSaySSGSgys6ResultOyAA14PagingIteratorCyAA15GroupMembershipCGAA0A8SDKErrorCGctF) with the ID of the user to retreive group memberships for. This method will return an iterator object, which is used to retrieve the memberships. ``` let iterator = client.groups.listMembershipsForUser(userId: "12345") iterator.next { result in switch results { case let .success(page): for membership in page.entries { print("Group Membership with ID \(membership.id) was retrieved") } case let .failure(error): print(error) } } ``` ## Get Collaborations for Group To retrieve all group collaborations for a given group, call [`client.groups.listCollaborations(groupId: String, offset: Int?, limit: Int? fields: [String]?)`](https://opensource.box.com/box-ios-sdk/Classes/GroupsModule.html#/s:6BoxSDK12GroupsModuleC18listCollaborations7groupId6offset5limit6fields10completionySS_SiSgAJSaySSGSgys6ResultOyAA14PagingIteratorCyAA13CollaborationCGAA0A8SDKErrorCGctF) with the ID of the group to retrieve collaborations for. This method will return an iterator object, which is used to retrieve the collaborations. ``` let iterator = client.groups.listCollaborations(groupId: "12345") iterator.next { results in switch results { case let .success(page): for collaboration in page.entries { print("Collaboration with ID \(collaboration.id) was retrieved") } case let .failure(error): print(error) } } ``` --- ### GroupsManager **Type:** page | **Section:** Additional Resources GroupsManager List groups for enterprise Create group Get group Update group Remove group List groups for enterprise Retrieves all of the… # GroupsManager - [List groups for enterprise](#list-groups-for-enterprise) - [Create group](#create-group) - [Get group](#get-group) - [Update group](#update-group) - [Remove group](#remove-group) ## List groups for enterprise Retrieves all of the groups for a given enterprise. The user must have admin permissions to inspect enterprise's groups. This operation is performed by calling function `getGroups`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-groups/). ``` await client.groups.getGroups(); ``` ### Arguments queryParams `GetGroupsQueryParams` - Query parameters of getGroups method headersInput `GetGroupsHeadersInput` - Headers of getGroups method cancellationToken `undefined | CancellationToken` - Token used for request cancellation. ### Returns This function returns a value of type `Groups`. Returns a collection of group objects. If there are no groups, an empty collection will be returned. ## Create group Creates a new group of users in an enterprise. Only users with admin permissions can create new groups. This operation is performed by calling function `createGroup`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-groups/). ``` await client.groups.createGroup({ name: groupName, description: groupDescription, } satisfies CreateGroupRequestBody); ``` ### Arguments requestBody `CreateGroupRequestBody` - Request body of createGroup method optionalsInput `CreateGroupOptionalsInput` ### Returns This function returns a value of type `GroupFull`. Returns the new group object. ## Get group Retrieves information about a group. Only members of this group or users with admin-level permissions will be able to use this API. This operation is performed by calling function `getGroupById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-groups-id/). ``` await client.groups.getGroupById(group.id, { queryParams: { fields: ['id', 'name', 'description', 'group_type'], } satisfies GetGroupByIdQueryParams, } satisfies GetGroupByIdOptionalsInput); ``` ### Arguments groupId `string` - The ID of the group. Example: "57645" optionalsInput `GetGroupByIdOptionalsInput` ### Returns This function returns a value of type `GroupFull`. Returns the group object. ## Update group Updates a specific group. Only admins of this group or users with admin-level permissions will be able to use this API. This operation is performed by calling function `updateGroupById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-groups-id/). ``` await client.groups.updateGroupById(group.id, { requestBody: { name: updatedGroupName } satisfies UpdateGroupByIdRequestBody, } satisfies UpdateGroupByIdOptionalsInput); ``` ### Arguments groupId `string` - The ID of the group. Example: "57645" optionalsInput `UpdateGroupByIdOptionalsInput` ### Returns This function returns a value of type `GroupFull`. Returns the updated group object. ## Remove group Permanently deletes a group. Only users with admin-level permissions will be able to use this API. This operation is performed by calling function `deleteGroupById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-groups-id/). ``` await client.groups.deleteGroupById(group.id); ``` ### Arguments groupId `string` - The ID of the group. Example: "57645" optionalsInput `DeleteGroupByIdOptionalsInput` ### Returns This function returns a value of type `undefined`. A blank response is returned if the group was successfully deleted. --- ### GroupsManager **Type:** page | **Section:** Additional Resources GroupsManager List groups for enterprise Create group Get group Update group Remove group List groups for enterprise Retrieves all of the… # GroupsManager - [List groups for enterprise](#list-groups-for-enterprise) - [Create group](#create-group) - [Get group](#get-group) - [Update group](#update-group) - [Remove group](#remove-group) ## List groups for enterprise Retrieves all of the groups for a given enterprise. The user must have admin permissions to inspect enterprise's groups. This operation is performed by calling function `get_groups`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-groups/). ``` client.groups.get_groups() ``` ### Arguments filter_term `Optional[str]` - Limits the results to only groups whose `name` starts with the search term. fields `Optional[List[str]]` - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested. limit `Optional[int]` - The maximum number of items to return per page. offset `Optional[int]` - The offset of the item at which to begin the response. Queries with offset parameter value exceeding 10000 will be rejected with a 400 response. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `Groups`. Returns a collection of group objects. If there are no groups, an empty collection will be returned. ## Create group Creates a new group of users in an enterprise. Only users with admin permissions can create new groups. This operation is performed by calling function `create_group`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-groups/). ``` client.groups.create_group(group_name, description=group_description) ``` ### Arguments name `str` - The name of the new group to be created. This name must be unique within the enterprise. provenance `Optional[str]` - Keeps track of which external source this group is coming, for example `Active Directory`, or `Okta`. Setting this will also prevent Box admins from editing the group name and its members directly via the Box web application. This is desirable for one-way syncing of groups. external_sync_identifier `Optional[str]` - An arbitrary identifier that can be used by external group sync tools to link this Box Group to an external group. Example values of this field could be an **Active Directory Object ID** or a **Google Group ID**. We recommend you use of this field in order to avoid issues when group names are updated in either Box or external systems. description `Optional[str]` - A human readable description of the group. invitability_level `Optional[CreateGroupInvitabilityLevel]` - Specifies who can invite the group to collaborate on folders. When set to `admins_only` the enterprise admin, co-admins, and the group's admin can invite the group. When set to `admins_and_members` all the admins listed above and group members can invite the group. When set to `all_managed_users` all managed users in the enterprise can invite the group. member_viewability_level `Optional[CreateGroupMemberViewabilityLevel]` - Specifies who can see the members of the group. _ `admins_only` - the enterprise admin, co-admins, group's group admin. _ `admins_and_members` - all admins and group members. * `all_managed_users` - all managed users in the enterprise. fields `Optional[List[str]]` - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `GroupFull`. Returns the new group object. ## Get group Retrieves information about a group. Only members of this group or users with admin-level permissions will be able to use this API. This operation is performed by calling function `get_group_by_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-groups-id/). ``` client.groups.get_group_by_id( group.id, fields=["id", "name", "description", "group_type"] ) ``` ### Arguments group_id `str` - The ID of the group. Example: "57645" fields `Optional[List[str]]` - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `GroupFull`. Returns the group object. ## Update group Updates a specific group. Only admins of this group or users with admin-level permissions will be able to use this API. This operation is performed by calling function `update_group_by_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-groups-id/). ``` client.groups.update_group_by_id(group.id, name=updated_group_name) ``` ### Arguments group_id `str` - The ID of the group. Example: "57645" name `Optional[str]` - The name of the new group to be created. Must be unique within the enterprise. provenance `Optional[str]` - Keeps track of which external source this group is coming, for example `Active Directory`, or `Okta`. Setting this will also prevent Box admins from editing the group name and its members directly via the Box web application. This is desirable for one-way syncing of groups. external_sync_identifier `Optional[str]` - An arbitrary identifier that can be used by external group sync tools to link this Box Group to an external group. Example values of this field could be an **Active Directory Object ID** or a **Google Group ID**. We recommend you use of this field in order to avoid issues when group names are updated in either Box or external systems. description `Optional[str]` - A human readable description of the group. invitability_level `Optional[UpdateGroupByIdInvitabilityLevel]` - Specifies who can invite the group to collaborate on folders. When set to `admins_only` the enterprise admin, co-admins, and the group's admin can invite the group. When set to `admins_and_members` all the admins listed above and group members can invite the group. When set to `all_managed_users` all managed users in the enterprise can invite the group. member_viewability_level `Optional[UpdateGroupByIdMemberViewabilityLevel]` - Specifies who can see the members of the group. _ `admins_only` - the enterprise admin, co-admins, group's group admin. _ `admins_and_members` - all admins and group members. * `all_managed_users` - all managed users in the enterprise. fields `Optional[List[str]]` - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `GroupFull`. Returns the updated group object. ## Remove group Permanently deletes a group. Only users with admin-level permissions will be able to use this API. This operation is performed by calling function `delete_group_by_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-groups-id/). ``` client.groups.delete_group_by_id(group.id) ``` ### Arguments group_id `str` - The ID of the group. Example: "57645" extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `None`. A blank response is returned if the group was successfully deleted. --- ### Handling null values in Box Dotnet SDK Gen **Type:** page | **Section:** Additional Resources Handling null values in Box Dotnet SDK Gen While using Box Dotnet SDK it's important to understand how null values behave. This document… # Handling null values in Box Dotnet SDK Gen While using Box Dotnet SDK it's important to understand how null values behave. This document provides a general overview of null value behaviour in Box Dotnet SDK to help developers manage data consistently and predictably. ## Understanding null behaviour The Box Dotnet SDK follows a consistent pattern when handling null values in update operations. This behaviour applies to most endpoints that modify resources such as users, files, folders and metadata. The updating field behaves differently depending on weather you omit it, set it to null, or provide a value: - Omitting the field: The field won't be included in request and the value will remain unchanged - Setting it to null: Setting a field to null, will cause sending HTTP request with field value set to null, what will result in removing its current value or disassociates it from the resource. - Providing a value: Providing a non-null value assigns or updates the field to that value. ## Example Usage The client.Files.UpdateFileByIdAsync() method demonstrates null handling when modifying the lock field while updating the file: ``` public async Task CreateUpdateFileAsync(BoxClient client) { var fileId = '12345'; var fileWithLockRequestBody = new UpdateFileByIdRequestBody() { Lock = new UpdateFileByIdRequestBodyLockField() { Access = UpdateFileByIdRequestBodyLockAccessField.Lock } }; var fileWithLockQueryParams = new UpdateFileByIdQueryParams() { Fields = new List<string>() { { "lock" } } }; // locking the file var fileWithLock = await client.Files.UpdateFileByIdAsync(fileId, fileWithLockRequestBody, fileWithLockQueryParams); Console.WriteLine(fileWithLock.Lock?.Id); var fileWithoutLockRequestBody = new UpdateFileByIdRequestBody() { Lock = null }; var fileWithoutLockQueryParams = new UpdateFileByIdQueryParams() { Fields = new List<string>() { { "lock" } } }; // unlocking the file using lock value as null var fileWithoutLock = await client.Files.UpdateFileByIdAsync(fileId, fileWithoutLockRequestBody, fileWithoutLockQueryParams); Console.WriteLine(fileWithoutLock.Lock?.Id); } ``` ## Summary To summarize, if you omit the field, the field remains unchanged. If you set it to null, it clears/removes the value. If you provide a value to that field, the field gets updated to that specified value. --- ### Handling null values in Box Python SDK Gen **Type:** page | **Section:** Additional Resources Handling null values in Box Python SDK Gen While using Box Python SDK it's important to understand how null values behave. This document… # Handling null values in Box Python SDK Gen While using Box Python SDK it's important to understand how null values behave. This document provides a general overview of null value behaviour in Box Python SDK to help developers manage data consistently and predictably. ## Understanding null behaviour The Box Python SDK follows a consistent pattern when handling null values in update operations. This behaviour applies to most endpoints that modify resources such as users, files, folders and metadata. The updating field behaves differently depending on weather you omit it, set it to null, or provide a value: - Omitting the field: The field won't be included in request and the value will remain unchanged. - Setting it to null: Setting a field to null, will cause sending HTTP request with field value set to null, what will result in removing its current value or disassociates it from the resource. - Providing a value: Providing a non-null value assigns or updates the field to that value. ## Example Usage The client.files.update_file_by_id() method demonstrates null handling when modifying the lock field while updating the file: ``` import null from box_sdk_gen def createUpdateFile(client): uploaded_file_id = '12345' # locking the file file_with_lock = client.files.update_file_by_id( uploaded_file_id, lock=UpdateFileByIdLock(access=UpdateFileByIdLockAccessField.LOCK), fields=['lock'], ) # unlocking the file using lock value as null file_without_lock = client.files.update_file_by_id( uploaded_file_id, lock=null, fields=['lock'] ) ``` ## Summary To summarize, if you omit the field, the field remains unchanged. If you set it to null, it clears/removes the value. If you provide a value to that field, the field gets updated to that specified value. --- ### Handling null values in Box Typescript SDK Gen **Type:** page | **Section:** Additional Resources Handling null values in Box Typescript SDK Gen While using Box Typescript SDK it's important to understand how null values behave. This… # Handling null values in Box Typescript SDK Gen While using Box Typescript SDK it's important to understand how null values behave. This document provides a general overview of null value behaviour in Box Typescript SDK to help developers manage data consistently and predictably. ## Understanding null behaviour The Box Typescript SDK follows a consistent pattern when handling null values in update operations. This behaviour applies to most endpoints that modify resources such as users, files, folders and metadata. The updating field behaves differently depending on weather you omit it, set it to null, or provide a value: - Omitting the field: The field won't be included in request and the value will remain unchanged - Setting it to null: Setting a field to null, will cause sending HTTP request with field value set to null, what will result in removing its current value or disassociates it from the resource. - Providing a value: Providing a non-null value assigns or updates the field to that value. ## Example Usage The client.files.updateFileById() method demonstrates null handling when modifying the lock field while updating the file: ``` async function create_update_file(client) { fileId = '12345'; // locking the file const fileWithLock = await client.files.updateFileById(fileId, { requestBody: { lock: { access: 'lock' } }, queryParams: { fields: ['lock'] }, }); console.log('File with lock ', fileWithLock); // unlocking the file using lock value as null const fileWithoutLock = await client.files.updateFileById(fileId, { requestBody: { lock: null }, queryParams: { fields: ['lock'] }, }); console.log('File without lock ', fileWithoutLock); } ``` ## Summary To summarize, if you omit the field, the field remains unchanged. If you set it to null, it clears/removes the value. If you provide a value to that field, the field gets updated to that specified value. --- ### HubCollaborationsManager **Type:** page | **Section:** Additional Resources HubCollaborationsManager Get hub collaborations Create hub collaboration Get hub collaboration by collaboration ID Update hub collaboration… # HubCollaborationsManager - [Get hub collaborations](#get-hub-collaborations) - [Create hub collaboration](#create-hub-collaboration) - [Get hub collaboration by collaboration ID](#get-hub-collaboration-by-collaboration-id) - [Update hub collaboration](#update-hub-collaboration) - [Remove hub collaboration](#remove-hub-collaboration) ## Get hub collaborations Retrieves all collaborations for a hub. This operation is performed by calling function `getHubCollaborationsV2025R0`. See the endpoint docs at [API Reference](https://developer.box.com/reference/v2025.0/get-hub-collaborations/). ``` await client.hubCollaborations.getHubCollaborationsV2025R0({ hubId: hub.id, } satisfies GetHubCollaborationsV2025R0QueryParams); ``` ### Arguments queryParams `GetHubCollaborationsV2025R0QueryParams` - Query parameters of getHubCollaborationsV2025R0 method optionalsInput `GetHubCollaborationsV2025R0OptionalsInput` ### Returns This function returns a value of type `HubCollaborationsV2025R0`. Retrieves the collaborations associated with the specified hub. ## Create hub collaboration Adds a collaboration for a single user or a single group to a hub. Collaborations can be created using email address, user IDs, or group IDs. This operation is performed by calling function `createHubCollaborationV2025R0`. See the endpoint docs at [API Reference](https://developer.box.com/reference/v2025.0/post-hub-collaborations/). ``` await client.hubCollaborations.createHubCollaborationV2025R0({ hub: new HubCollaborationCreateRequestV2025R0HubField({ id: hub.id }), accessibleBy: { type: 'user', id: user.id, } satisfies HubCollaborationCreateRequestV2025R0AccessibleByField, role: 'viewer', } satisfies HubCollaborationCreateRequestV2025R0); ``` ### Arguments requestBody `HubCollaborationCreateRequestV2025R0` - Request body of createHubCollaborationV2025R0 method optionalsInput `CreateHubCollaborationV2025R0OptionalsInput` ### Returns This function returns a value of type `HubCollaborationV2025R0`. Returns a new hub collaboration object. ## Get hub collaboration by collaboration ID Retrieves details for a hub collaboration by collaboration ID. This operation is performed by calling function `getHubCollaborationByIdV2025R0`. See the endpoint docs at [API Reference](https://developer.box.com/reference/v2025.0/get-hub-collaborations-id/). ``` await client.hubCollaborations.getHubCollaborationByIdV2025R0( createdCollaboration.id, ); ``` ### Arguments hubCollaborationId `string` - The ID of the hub collaboration. Example: "1234" optionalsInput `GetHubCollaborationByIdV2025R0OptionalsInput` ### Returns This function returns a value of type `HubCollaborationV2025R0`. Returns a hub collaboration object. ## Update hub collaboration Updates a hub collaboration. Can be used to change the hub role. This operation is performed by calling function `updateHubCollaborationByIdV2025R0`. See the endpoint docs at [API Reference](https://developer.box.com/reference/v2025.0/put-hub-collaborations-id/). ``` await client.hubCollaborations.updateHubCollaborationByIdV2025R0( createdCollaboration.id, { role: 'editor' } satisfies HubCollaborationUpdateRequestV2025R0, ); ``` ### Arguments hubCollaborationId `string` - The ID of the hub collaboration. Example: "1234" requestBody `HubCollaborationUpdateRequestV2025R0` - Request body of updateHubCollaborationByIdV2025R0 method optionalsInput `UpdateHubCollaborationByIdV2025R0OptionalsInput` ### Returns This function returns a value of type `HubCollaborationV2025R0`. Returns an updated hub collaboration object. ## Remove hub collaboration Deletes a single hub collaboration. This operation is performed by calling function `deleteHubCollaborationByIdV2025R0`. See the endpoint docs at [API Reference](https://developer.box.com/reference/v2025.0/delete-hub-collaborations-id/). ``` await client.hubCollaborations.deleteHubCollaborationByIdV2025R0( createdCollaboration.id, ); ``` ### Arguments hubCollaborationId `string` - The ID of the hub collaboration. Example: "1234" optionalsInput `DeleteHubCollaborationByIdV2025R0OptionalsInput` ### Returns This function returns a value of type `undefined`. A blank response is returned if the hub collaboration was successfully deleted. --- ### HubCollaborationsManager **Type:** page | **Section:** Additional Resources HubCollaborationsManager Get hub collaborations Create hub collaboration Get hub collaboration by collaboration ID Update hub collaboration… # HubCollaborationsManager - [Get hub collaborations](#get-hub-collaborations) - [Create hub collaboration](#create-hub-collaboration) - [Get hub collaboration by collaboration ID](#get-hub-collaboration-by-collaboration-id) - [Update hub collaboration](#update-hub-collaboration) - [Remove hub collaboration](#remove-hub-collaboration) ## Get hub collaborations Retrieves all collaborations for a hub. This operation is performed by calling function `get_hub_collaborations_v2025_r0`. See the endpoint docs at [API Reference](https://developer.box.com/reference/v2025.0/get-hub-collaborations/). ``` client.hub_collaborations.get_hub_collaborations_v2025_r0(hub.id) ``` ### Arguments hub_id `str` - The unique identifier that represent a hub. The ID for any hub can be determined by visiting this hub in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/hubs/123` the `hub_id` is `123`. marker `Optional[str]` - Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`. limit `Optional[int]` - The maximum number of items to return per page. box_version `BoxVersionHeaderV2025R0` - Version header. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `HubCollaborationsV2025R0`. Retrieves the collaborations associated with the specified hub. ## Create hub collaboration Adds a collaboration for a single user or a single group to a hub. Collaborations can be created using email address, user IDs, or group IDs. This operation is performed by calling function `create_hub_collaboration_v2025_r0`. See the endpoint docs at [API Reference](https://developer.box.com/reference/v2025.0/post-hub-collaborations/). ``` client.hub_collaborations.create_hub_collaboration_v2025_r0( CreateHubCollaborationV2025R0Hub(id=hub.id), CreateHubCollaborationV2025R0AccessibleBy(type="user", id=user.id), "viewer", ) ``` ### Arguments hub `CreateHubCollaborationV2025R0Hub` - Hubs reference. accessible_by `CreateHubCollaborationV2025R0AccessibleBy` - The user or group who gets access to the item. role `str` - The level of access granted to hub. Possible values are `editor`, `viewer`, and `co-owner`. box_version `BoxVersionHeaderV2025R0` - Version header. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `HubCollaborationV2025R0`. Returns a new hub collaboration object. ## Get hub collaboration by collaboration ID Retrieves details for a hub collaboration by collaboration ID. This operation is performed by calling function `get_hub_collaboration_by_id_v2025_r0`. See the endpoint docs at [API Reference](https://developer.box.com/reference/v2025.0/get-hub-collaborations-id/). ``` client.hub_collaborations.get_hub_collaboration_by_id_v2025_r0(created_collaboration.id) ``` ### Arguments hub_collaboration_id `str` - The ID of the hub collaboration. Example: "1234" box_version `BoxVersionHeaderV2025R0` - Version header. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `HubCollaborationV2025R0`. Returns a hub collaboration object. ## Update hub collaboration Updates a hub collaboration. Can be used to change the hub role. This operation is performed by calling function `update_hub_collaboration_by_id_v2025_r0`. See the endpoint docs at [API Reference](https://developer.box.com/reference/v2025.0/put-hub-collaborations-id/). ``` client.hub_collaborations.update_hub_collaboration_by_id_v2025_r0( created_collaboration.id, role="editor" ) ``` ### Arguments hub_collaboration_id `str` - The ID of the hub collaboration. Example: "1234" role `Optional[str]` - The level of access granted to hub. Possible values are `editor`, `viewer`, and `co-owner`. box_version `BoxVersionHeaderV2025R0` - Version header. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `HubCollaborationV2025R0`. Returns an updated hub collaboration object. ## Remove hub collaboration Deletes a single hub collaboration. This operation is performed by calling function `delete_hub_collaboration_by_id_v2025_r0`. See the endpoint docs at [API Reference](https://developer.box.com/reference/v2025.0/delete-hub-collaborations-id/). ``` client.hub_collaborations.delete_hub_collaboration_by_id_v2025_r0( created_collaboration.id ) ``` ### Arguments hub_collaboration_id `str` - The ID of the hub collaboration. Example: "1234" box_version `BoxVersionHeaderV2025R0` - Version header. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `None`. A blank response is returned if the hub collaboration was successfully deleted. --- ### HubItemsManager **Type:** page | **Section:** Additional Resources HubItemsManager Get hub items Manage hub items Get hub items Retrieves all items associated with a Hub. This operation is performed by… # HubItemsManager - [Get hub items](#get-hub-items) - [Manage hub items](#manage-hub-items) ## Get hub items Retrieves all items associated with a Hub. This operation is performed by calling function `getHubItemsV2025R0`. See the endpoint docs at [API Reference](https://developer.box.com/reference/v2025.0/get-hub-items/). ``` await client.hubItems.getHubItemsV2025R0({ hubId: createdHub.id, } satisfies GetHubItemsV2025R0QueryParams); ``` ### Arguments queryParams `GetHubItemsV2025R0QueryParams` - Query parameters of getHubItemsV2025R0 method optionalsInput `GetHubItemsV2025R0OptionalsInput` ### Returns This function returns a value of type `HubItemsV2025R0`. Retrieves the items associated with the specified Hub. ## Manage hub items Adds and/or removes Hub items from a Hub. This operation is performed by calling function `manageHubItemsV2025R0`. See the endpoint docs at [API Reference](https://developer.box.com/reference/v2025.0/post-hubs-id-manage-items/). ``` await client.hubItems.manageHubItemsV2025R0(createdHub.id, { operations: [ { action: 'add' as HubItemOperationV2025R0ActionField, item: new FolderReferenceV2025R0({ id: folder.id }), } satisfies HubItemOperationV2025R0, ], } satisfies HubItemsManageRequestV2025R0); ``` ### Arguments hubId `string` - The unique identifier that represent a hub. The ID for any hub can be determined by visiting this hub in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/hubs/123` the `hub_id` is `123`. Example: "12345" requestBody `HubItemsManageRequestV2025R0` - Request body of manageHubItemsV2025R0 method optionalsInput `ManageHubItemsV2025R0OptionalsInput` ### Returns This function returns a value of type `HubItemsManageResponseV2025R0`. --- ### HubItemsManager **Type:** page | **Section:** Additional Resources HubItemsManager Get hub items Manage hub items Get hub items Retrieves all items associated with a Hub. This operation is performed by… # HubItemsManager - [Get hub items](#get-hub-items) - [Manage hub items](#manage-hub-items) ## Get hub items Retrieves all items associated with a Hub. This operation is performed by calling function `get_hub_items_v2025_r0`. See the endpoint docs at [API Reference](https://developer.box.com/reference/v2025.0/get-hub-items/). ``` client.hub_items.get_hub_items_v2025_r0(created_hub.id) ``` ### Arguments hub_id `str` - The unique identifier that represent a hub. The ID for any hub can be determined by visiting this hub in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/hubs/123` the `hub_id` is `123`. marker `Optional[str]` - Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`. limit `Optional[int]` - The maximum number of items to return per page. box_version `BoxVersionHeaderV2025R0` - Version header. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `HubItemsV2025R0`. Retrieves the items associated with the specified Hub. ## Manage hub items Adds and/or removes Hub items from a Hub. This operation is performed by calling function `manage_hub_items_v2025_r0`. See the endpoint docs at [API Reference](https://developer.box.com/reference/v2025.0/post-hubs-id-manage-items/). ``` client.hub_items.manage_hub_items_v2025_r0( created_hub.id, operations=[ HubItemOperationV2025R0( action=HubItemOperationV2025R0ActionField.ADD, item=FolderReferenceV2025R0(id=folder.id), ) ], ) ``` ### Arguments hub_id `str` - The unique identifier that represent a hub. The ID for any hub can be determined by visiting this hub in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/hubs/123` the `hub_id` is `123`. Example: "12345" operations `Optional[List[HubItemOperationV2025R0]]` - List of operations to perform on Hub items. box_version `BoxVersionHeaderV2025R0` - Version header. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `HubItemsManageResponseV2025R0`. --- ### HubsManager **Type:** page | **Section:** Additional Resources HubsManager List all hubs Create hub List all hubs for requesting enterprise Get hub information by ID Update hub information by ID Delete… # HubsManager - [List all hubs](#list-all-hubs) - [Create hub](#create-hub) - [List all hubs for requesting enterprise](#list-all-hubs-for-requesting-enterprise) - [Get hub information by ID](#get-hub-information-by-id) - [Update hub information by ID](#update-hub-information-by-id) - [Delete hub](#delete-hub) - [Copy hub](#copy-hub) ## List all hubs Retrieves all hubs for requesting user. This operation is performed by calling function `getHubsV2025R0`. See the endpoint docs at [API Reference](https://developer.box.com/reference/v2025.0/get-hubs/). ``` await client.hubs.getHubsV2025R0({ scope: 'all', sort: 'name', direction: 'ASC' as GetHubsV2025R0QueryParamsDirectionField, } satisfies GetHubsV2025R0QueryParams); ``` ### Arguments queryParams `GetHubsV2025R0QueryParams` - Query parameters of getHubsV2025R0 method headersInput `GetHubsV2025R0HeadersInput` - Headers of getHubsV2025R0 method cancellationToken `undefined | CancellationToken` - Token used for request cancellation. ### Returns This function returns a value of type `HubsV2025R0`. Returns all hubs for the given user or enterprise. ## Create hub Creates a new Hub. This operation is performed by calling function `createHubV2025R0`. See the endpoint docs at [API Reference](https://developer.box.com/reference/v2025.0/post-hubs/). ``` await client.hubs.createHubV2025R0({ title: hubTitle, description: hubDescription, } satisfies HubCreateRequestV2025R0); ``` ### Arguments requestBody `HubCreateRequestV2025R0` - Request body of createHubV2025R0 method optionalsInput `CreateHubV2025R0OptionalsInput` ### Returns This function returns a value of type `HubV2025R0`. Returns a new Hub object. ## List all hubs for requesting enterprise Retrieves all hubs for a given enterprise. Admins or Hub Co-admins of an enterprise with GCM scope can make this call. This operation is performed by calling function `getEnterpriseHubsV2025R0`. See the endpoint docs at [API Reference](https://developer.box.com/reference/v2025.0/get-enterprise-hubs/). ``` await client.hubs.getEnterpriseHubsV2025R0({ sort: 'name', direction: 'ASC' as GetEnterpriseHubsV2025R0QueryParamsDirectionField, } satisfies GetEnterpriseHubsV2025R0QueryParams); ``` ### Arguments queryParams `GetEnterpriseHubsV2025R0QueryParams` - Query parameters of getEnterpriseHubsV2025R0 method headersInput `GetEnterpriseHubsV2025R0HeadersInput` - Headers of getEnterpriseHubsV2025R0 method cancellationToken `undefined | CancellationToken` - Token used for request cancellation. ### Returns This function returns a value of type `HubsV2025R0`. Returns all hubs for the given user or enterprise. ## Get hub information by ID Retrieves details for a hub by its ID. This operation is performed by calling function `getHubByIdV2025R0`. See the endpoint docs at [API Reference](https://developer.box.com/reference/v2025.0/get-hubs-id/). ``` await client.hubs.getHubByIdV2025R0(hubId); ``` ### Arguments hubId `string` - The unique identifier that represent a hub. The ID for any hub can be determined by visiting this hub in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/hubs/123` the `hub_id` is `123`. Example: "12345" optionalsInput `GetHubByIdV2025R0OptionalsInput` ### Returns This function returns a value of type `HubV2025R0`. Returns a hub object. ## Update hub information by ID Updates a Hub. Can be used to change title, description, or Hub settings. This operation is performed by calling function `updateHubByIdV2025R0`. See the endpoint docs at [API Reference](https://developer.box.com/reference/v2025.0/put-hubs-id/). ``` await client.hubs.updateHubByIdV2025R0(hubId, { title: newHubTitle, description: newHubDescription, } satisfies HubUpdateRequestV2025R0); ``` ### Arguments hubId `string` - The unique identifier that represent a hub. The ID for any hub can be determined by visiting this hub in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/hubs/123` the `hub_id` is `123`. Example: "12345" requestBody `HubUpdateRequestV2025R0` - Request body of updateHubByIdV2025R0 method optionalsInput `UpdateHubByIdV2025R0OptionalsInput` ### Returns This function returns a value of type `HubV2025R0`. Returns a Hub object. ## Delete hub Deletes a single hub. This operation is performed by calling function `deleteHubByIdV2025R0`. See the endpoint docs at [API Reference](https://developer.box.com/reference/v2025.0/delete-hubs-id/). ``` await client.hubs.deleteHubByIdV2025R0(hubId); ``` ### Arguments hubId `string` - The unique identifier that represent a hub. The ID for any hub can be determined by visiting this hub in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/hubs/123` the `hub_id` is `123`. Example: "12345" optionalsInput `DeleteHubByIdV2025R0OptionalsInput` ### Returns This function returns a value of type `undefined`. A blank response is returned if the hub was successfully deleted. ## Copy hub Creates a copy of a Hub. The original Hub will not be modified. This operation is performed by calling function `copyHubV2025R0`. See the endpoint docs at [API Reference](https://developer.box.com/reference/v2025.0/post-hubs-id-copy/). ``` await client.hubs.copyHubV2025R0(createdHub.id, { title: copiedHubTitle, description: copiedHubDescription, } satisfies HubCopyRequestV2025R0); ``` ### Arguments hubId `string` - The unique identifier that represent a hub. The ID for any hub can be determined by visiting this hub in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/hubs/123` the `hub_id` is `123`. Example: "12345" requestBody `HubCopyRequestV2025R0` - Request body of copyHubV2025R0 method optionalsInput `CopyHubV2025R0OptionalsInput` ### Returns This function returns a value of type `HubV2025R0`. Returns a new Hub object. --- ### HubsManager **Type:** page | **Section:** Additional Resources HubsManager List all hubs Create hub List all hubs for requesting enterprise Get hub information by ID Update hub information by ID Delete… # HubsManager - [List all hubs](#list-all-hubs) - [Create hub](#create-hub) - [List all hubs for requesting enterprise](#list-all-hubs-for-requesting-enterprise) - [Get hub information by ID](#get-hub-information-by-id) - [Update hub information by ID](#update-hub-information-by-id) - [Delete hub](#delete-hub) - [Copy hub](#copy-hub) ## List all hubs Retrieves all hubs for requesting user. This operation is performed by calling function `get_hubs_v2025_r0`. See the endpoint docs at [API Reference](https://developer.box.com/reference/v2025.0/get-hubs/). ``` client.hubs.get_hubs_v2025_r0( scope="all", sort="name", direction=GetHubsV2025R0Direction.ASC ) ``` ### Arguments query `Optional[str]` - The query string to search for hubs. scope `Optional[str]` - The scope of the hubs to retrieve. Possible values include `editable`, `view_only`, and `all`. Default is `all`. sort `Optional[str]` - The field to sort results by. Possible values include `name`, `updated_at`, `last_accessed_at`, `view_count`, and `relevance`. Default is `relevance`. direction `Optional[GetHubsV2025R0Direction]` - The direction to sort results in. This can be either in alphabetical ascending (`ASC`) or descending (`DESC`) order. marker `Optional[str]` - Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. limit `Optional[int]` - The maximum number of items to return per page. box_version `BoxVersionHeaderV2025R0` - Version header. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `HubsV2025R0`. Returns all hubs for the given user or enterprise. ## Create hub Creates a new Hub. This operation is performed by calling function `create_hub_v2025_r0`. See the endpoint docs at [API Reference](https://developer.box.com/reference/v2025.0/post-hubs/). ``` client.hubs.create_hub_v2025_r0(hub_title, description=hub_description) ``` ### Arguments title `str` - Title of the Hub. It cannot be empty and should be less than 50 characters. description `Optional[str]` - Description of the Hub. box_version `BoxVersionHeaderV2025R0` - Version header. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `HubV2025R0`. Returns a new Hub object. ## List all hubs for requesting enterprise Retrieves all hubs for a given enterprise. Admins or Hub Co-admins of an enterprise with GCM scope can make this call. This operation is performed by calling function `get_enterprise_hubs_v2025_r0`. See the endpoint docs at [API Reference](https://developer.box.com/reference/v2025.0/get-enterprise-hubs/). ``` client.hubs.get_enterprise_hubs_v2025_r0( sort="name", direction=GetEnterpriseHubsV2025R0Direction.ASC ) ``` ### Arguments query `Optional[str]` - The query string to search for hubs. sort `Optional[str]` - The field to sort results by. Possible values include `name`, `updated_at`, `last_accessed_at`, `view_count`, and `relevance`. Default is `relevance`. direction `Optional[GetEnterpriseHubsV2025R0Direction]` - The direction to sort results in. This can be either in alphabetical ascending (`ASC`) or descending (`DESC`) order. marker `Optional[str]` - Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. limit `Optional[int]` - The maximum number of items to return per page. box_version `BoxVersionHeaderV2025R0` - Version header. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `HubsV2025R0`. Returns all hubs for the given user or enterprise. ## Get hub information by ID Retrieves details for a hub by its ID. This operation is performed by calling function `get_hub_by_id_v2025_r0`. See the endpoint docs at [API Reference](https://developer.box.com/reference/v2025.0/get-hubs-id/). ``` client.hubs.get_hub_by_id_v2025_r0(hub_id) ``` ### Arguments hub_id `str` - The unique identifier that represent a hub. The ID for any hub can be determined by visiting this hub in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/hubs/123` the `hub_id` is `123`. Example: "12345" box_version `BoxVersionHeaderV2025R0` - Version header. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `HubV2025R0`. Returns a hub object. ## Update hub information by ID Updates a Hub. Can be used to change title, description, or Hub settings. This operation is performed by calling function `update_hub_by_id_v2025_r0`. See the endpoint docs at [API Reference](https://developer.box.com/reference/v2025.0/put-hubs-id/). ``` client.hubs.update_hub_by_id_v2025_r0( hub_id, title=new_hub_title, description=new_hub_description ) ``` ### Arguments hub_id `str` - The unique identifier that represent a hub. The ID for any hub can be determined by visiting this hub in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/hubs/123` the `hub_id` is `123`. Example: "12345" title `Optional[str]` - Title of the Hub. It cannot be empty and should be less than 50 characters. description `Optional[str]` - Description of the Hub. is_ai_enabled `Optional[bool]` - Indicates if AI features are enabled for the Hub. is_collaboration_restricted_to_enterprise `Optional[bool]` - Indicates if collaboration is restricted to the enterprise. can_non_owners_invite `Optional[bool]` - Indicates if non-owners can invite others to the Hub. can_shared_link_be_created `Optional[bool]` - Indicates if a shared link can be created for the Hub. box_version `BoxVersionHeaderV2025R0` - Version header. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `HubV2025R0`. Returns a Hub object. ## Delete hub Deletes a single hub. This operation is performed by calling function `delete_hub_by_id_v2025_r0`. See the endpoint docs at [API Reference](https://developer.box.com/reference/v2025.0/delete-hubs-id/). ``` client.hubs.delete_hub_by_id_v2025_r0(hub_id) ``` ### Arguments hub_id `str` - The unique identifier that represent a hub. The ID for any hub can be determined by visiting this hub in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/hubs/123` the `hub_id` is `123`. Example: "12345" box_version `BoxVersionHeaderV2025R0` - Version header. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `None`. A blank response is returned if the hub was successfully deleted. ## Copy hub Creates a copy of a Hub. The original Hub will not be modified. This operation is performed by calling function `copy_hub_v2025_r0`. See the endpoint docs at [API Reference](https://developer.box.com/reference/v2025.0/post-hubs-id-copy/). ``` client.hubs.copy_hub_v2025_r0( created_hub.id, title=copied_hub_title, description=copied_hub_description ) ``` ### Arguments hub_id `str` - The unique identifier that represent a hub. The ID for any hub can be determined by visiting this hub in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/hubs/123` the `hub_id` is `123`. Example: "12345" title `Optional[str]` - Title of the Hub. It cannot be empty and should be less than 50 characters. description `Optional[str]` - Description of the Hub. box_version `BoxVersionHeaderV2025R0` - Version header. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `HubV2025R0`. Returns a new Hub object. --- ### IAiManager **Type:** page | **Section:** Additional Resources IAiManager Ask question Generate text Get AI agent default configuration Extract metadata (freeform) Extract metadata (structured) Ask… # IAiManager - [Ask question](#ask-question) - [Generate text](#generate-text) - [Get AI agent default configuration](#get-ai-agent-default-configuration) - [Extract metadata (freeform)](#extract-metadata-freeform) - [Extract metadata (structured)](#extract-metadata-structured) ## Ask question Sends an AI request to supported LLMs and returns an answer specifically focused on the user's question given the provided context. This operation is performed by calling function `CreateAiAsk`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-ai-ask/). ``` await client.Ai.CreateAiAskAsync(requestBody: new AiAsk(mode: AiAskModeField.SingleItemQa, prompt: "which direction sun rises", items: Array.AsReadOnly(new [] {new AiItemAsk(id: fileToAsk.Id, type: AiItemAskTypeField.File) { Content = "Sun rises in the East" }}))); ``` ### Arguments requestBody `AiAsk` - Request body of createAiAsk method headers `CreateAiAskHeaders` - Headers of createAiAsk method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `AiResponseFull?`. A successful response including the answer from the LLM.No content is available to answer the question. This is returned when the request item is a hub, but content in the hubs is not indexed. To ensure content in the hub is indexed, make sure Box AI for Hubs in the Admin Console was enabled before hub creation. ## Generate text Sends an AI request to supported Large Language Models (LLMs) and returns generated text based on the provided prompt. This operation is performed by calling function `CreateAiTextGen`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-ai-text-gen/). ``` await client.Ai.CreateAiTextGenAsync(requestBody: new AiTextGen(prompt: "Parapharse the document.s", items: Array.AsReadOnly(new [] {new AiTextGenItemsField(id: fileToAsk.Id, type: AiTextGenItemsTypeField.File) { Content = "The Earth goes around the sun. Sun rises in the East in the morning." }})) { DialogueHistory = Array.AsReadOnly(new [] {new AiDialogueHistory() { Prompt = "What does the earth go around?", Answer = "The sun", CreatedAt = Utils.DateTimeFromString(dateTime: "2021-01-01T00:00:00Z") },new AiDialogueHistory() { Prompt = "On Earth, where does the sun rise?", Answer = "East", CreatedAt = Utils.DateTimeFromString(dateTime: "2021-01-01T00:00:00Z") }}) }); ``` ### Arguments requestBody `AiTextGen` - Request body of createAiTextGen method headers `CreateAiTextGenHeaders` - Headers of createAiTextGen method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `AiResponse`. A successful response including the answer from the LLM. ## Get AI agent default configuration Get the AI agent default config. This operation is performed by calling function `GetAiAgentDefaultConfig`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-ai-agent-default/). ``` await client.Ai.GetAiAgentDefaultConfigAsync(queryParams: new GetAiAgentDefaultConfigQueryParams(mode: GetAiAgentDefaultConfigQueryParamsModeField.Ask) { Language = "en-US" }); ``` ### Arguments queryParams `GetAiAgentDefaultConfigQueryParams` - Query parameters of getAiAgentDefaultConfig method headers `GetAiAgentDefaultConfigHeaders` - Headers of getAiAgentDefaultConfig method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `AiAgentAskOrAiAgentExtractOrAiAgentExtractStructuredOrAiAgentTextGen`. A successful response including the default agent configuration. This response can be one of the following four objects: - AI agent for questions - AI agent for text generation - AI agent for freeform metadata extraction - AI agent for structured metadata extraction. The response depends on the agent configuration requested in this endpoint. ## Extract metadata (freeform) Sends an AI request to supported Large Language Models (LLMs) and extracts metadata in form of key-value pairs. In this request, both the prompt and the output can be freeform. Metadata template setup before sending the request is not required. This operation is performed by calling function `CreateAiExtract`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-ai-extract/). ``` await client.Ai.CreateAiExtractAsync(requestBody: new AiExtract(prompt: "firstName, lastName, location, yearOfBirth, company", items: Array.AsReadOnly(new [] {new AiItemBase(id: file.Id)}))); ``` ### Arguments requestBody `AiExtract` - Request body of createAiExtract method headers `CreateAiExtractHeaders` - Headers of createAiExtract method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `AiResponse`. A response including the answer from the LLM. ## Extract metadata (structured) Sends an AI request to supported Large Language Models (LLMs) and returns extracted metadata as a set of key-value pairs. For this request, you either need a metadata template or a list of fields you want to extract. Input is **either** a metadata template or a list of fields to ensure the structure. To learn more about creating templates, see [Creating metadata templates in the Admin Console](https://support.box.com/hc/en-us/articles/360044194033-Customizing-Metadata-Templates) or use the [metadata template API](g://metadata/templates/create). This operation is performed by calling function `CreateAiExtractStructured`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-ai-extract-structured/). ``` await client.Ai.CreateAiExtractStructuredAsync(requestBody: new AiExtractStructured(items: Array.AsReadOnly(new [] {new AiItemBase(id: file.Id)})) { Fields = Array.AsReadOnly(new [] {new AiExtractStructuredFieldsField(key: "firstName") { DisplayName = "First name", Description = "Person first name", Prompt = "What is the your first name?", Type = "string" },new AiExtractStructuredFieldsField(key: "lastName") { DisplayName = "Last name", Description = "Person last name", Prompt = "What is the your last name?", Type = "string" },new AiExtractStructuredFieldsField(key: "dateOfBirth") { DisplayName = "Birth date", Description = "Person date of birth", Prompt = "What is the date of your birth?", Type = "date" },new AiExtractStructuredFieldsField(key: "age") { DisplayName = "Age", Description = "Person age", Prompt = "How old are you?", Type = "float" },new AiExtractStructuredFieldsField(key: "hobby") { DisplayName = "Hobby", Description = "Person hobby", Prompt = "What is your hobby?", Type = "multiSelect", Options = Array.AsReadOnly(new [] {new AiExtractStructuredFieldsOptionsField(key: "guitar"),new AiExtractStructuredFieldsOptionsField(key: "books")}) }}) }); ``` ### Arguments requestBody `AiExtractStructured` - Request body of createAiExtractStructured method headers `CreateAiExtractStructuredHeaders` - Headers of createAiExtractStructured method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `AiExtractStructuredResponse`. A successful response including the answer from the LLM. --- ### IAiStudioManager **Type:** page | **Section:** Additional Resources IAiStudioManager List AI agents Create AI agent Update AI agent Get AI agent by agent ID Delete AI agent List AI agents Lists AI agents… # IAiStudioManager - [List AI agents](#list-ai-agents) - [Create AI agent](#create-ai-agent) - [Update AI agent](#update-ai-agent) - [Get AI agent by agent ID](#get-ai-agent-by-agent-id) - [Delete AI agent](#delete-ai-agent) ## List AI agents Lists AI agents based on the provided parameters. This operation is performed by calling function `GetAiAgents`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-ai-agents/). ``` await client.AiStudio.GetAiAgentsAsync(); ``` ### Arguments queryParams `GetAiAgentsQueryParams` - Query parameters of getAiAgents method headers `GetAiAgentsHeaders` - Headers of getAiAgents method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `AiMultipleAgentResponse`. A successful response including the agents list. ## Create AI agent Creates an AI agent. At least one of the following capabilities must be provided: `ask`, `text_gen`, `extract`. This operation is performed by calling function `CreateAiAgent`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-ai-agents/). ``` await client.AiStudio.CreateAiAgentAsync(requestBody: new CreateAiAgent(name: agentName, accessState: "enabled") { Ask = new AiStudioAgentAsk(accessState: "enabled", description: "desc1") }); ``` ### Arguments requestBody `CreateAiAgent` - Request body of createAiAgent method headers `CreateAiAgentHeaders` - Headers of createAiAgent method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `AiSingleAgentResponseFull`. Definition of created AI agent. ## Update AI agent Updates an AI agent. This operation is performed by calling function `UpdateAiAgentById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-ai-agents-id/). ``` await client.AiStudio.UpdateAiAgentByIdAsync(agentId: createdAgent.Id, requestBody: new CreateAiAgent(name: agentName, accessState: "enabled") { Ask = new AiStudioAgentAsk(accessState: "disabled", description: "desc2") }); ``` ### Arguments agentId `string` - The ID of the agent to update. Example: "1234" requestBody `CreateAiAgent` - Request body of updateAiAgentById method headers `UpdateAiAgentByIdHeaders` - Headers of updateAiAgentById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `AiSingleAgentResponseFull`. Definition of created AI agent. ## Get AI agent by agent ID Gets an AI Agent using the `agent_id` parameter. This operation is performed by calling function `GetAiAgentById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-ai-agents-id/). ``` await client.AiStudio.GetAiAgentByIdAsync(agentId: createdAgent.Id, queryParams: new GetAiAgentByIdQueryParams() { Fields = Array.AsReadOnly(new [] {"ask"}) }); ``` ### Arguments agentId `string` - The agent id to get. Example: "1234" queryParams `GetAiAgentByIdQueryParams` - Query parameters of getAiAgentById method headers `GetAiAgentByIdHeaders` - Headers of getAiAgentById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `AiSingleAgentResponseFull`. A successful response including the agent. ## Delete AI agent Deletes an AI agent using the provided parameters. This operation is performed by calling function `DeleteAiAgentById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-ai-agents-id/). ``` await client.AiStudio.DeleteAiAgentByIdAsync(agentId: createdAgent.Id); ``` ### Arguments agentId `string` - The ID of the agent to delete. Example: "1234" headers `DeleteAiAgentByIdHeaders` - Headers of deleteAiAgentById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `null`. A successful response with no content. --- ### IAppItemAssociationsManager **Type:** page | **Section:** Additional Resources IAppItemAssociationsManager List file app item associations List folder app item associations List file app item associations This is a beta… # IAppItemAssociationsManager - [List file app item associations](#list-file-app-item-associations) - [List folder app item associations](#list-folder-app-item-associations) ## List file app item associations **This is a beta feature, which means that its availability might be limited.** Returns all app items the file is associated with. This includes app items associated with ancestors of the file. Assuming the context user has access to the file, the type/ids are revealed even if the context user does not have **View** permission on the app item. This operation is performed by calling function `GetFileAppItemAssociations`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-files-id-app-item-associations/). ``` await client.AppItemAssociations.GetFileAppItemAssociationsAsync(fileId: fileId); ``` ### Arguments fileId `string` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" queryParams `GetFileAppItemAssociationsQueryParams` - Query parameters of getFileAppItemAssociations method headers `GetFileAppItemAssociationsHeaders` - Headers of getFileAppItemAssociations method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `AppItemAssociations`. Returns a collection of app item objects. If there are no app items on this file, an empty collection will be returned. This list includes app items on ancestors of this File. ## List folder app item associations **This is a beta feature, which means that its availability might be limited.** Returns all app items the folder is associated with. This includes app items associated with ancestors of the folder. Assuming the context user has access to the folder, the type/ids are revealed even if the context user does not have **View** permission on the app item. This operation is performed by calling function `GetFolderAppItemAssociations`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-folders-id-app-item-associations/). ``` await client.AppItemAssociations.GetFolderAppItemAssociationsAsync(folderId: folderId); ``` ### Arguments folderId `string` - The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. Example: "12345" queryParams `GetFolderAppItemAssociationsQueryParams` - Query parameters of getFolderAppItemAssociations method headers `GetFolderAppItemAssociationsHeaders` - Headers of getFolderAppItemAssociations method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `AppItemAssociations`. Returns a collection of app item objects. If there are no app items on this folder an empty collection will be returned. This list includes app items on ancestors of this folder. --- ### IArchivesManager **Type:** page | **Section:** Additional Resources IArchivesManager List archives Create archive Delete archive List archives Retrieves archives for an enterprise. This operation is performed… # IArchivesManager - [List archives](#list-archives) - [Create archive](#create-archive) - [Delete archive](#delete-archive) ## List archives Retrieves archives for an enterprise. This operation is performed by calling function `GetArchivesV2025R0`. See the endpoint docs at [API Reference](https://developer.box.com/reference/v2025.0/get-archives/). ``` await client.Archives.GetArchivesV2025R0Async(queryParams: new GetArchivesV2025R0QueryParams() { Limit = 100 }); ``` ### Arguments queryParams `GetArchivesV2025R0QueryParams` - Query parameters of getArchivesV2025R0 method headers `GetArchivesV2025R0Headers` - Headers of getArchivesV2025R0 method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `ArchivesV2025R0`. Returns a list of archives in the enterprise. ## Create archive Creates an archive. This operation is performed by calling function `CreateArchiveV2025R0`. See the endpoint docs at [API Reference](https://developer.box.com/reference/v2025.0/post-archives/). ``` await client.Archives.CreateArchiveV2025R0Async(requestBody: new CreateArchiveV2025R0RequestBody(name: archiveName)); ``` ### Arguments requestBody `CreateArchiveV2025R0RequestBody` - Request body of createArchiveV2025R0 method headers `CreateArchiveV2025R0Headers` - Headers of createArchiveV2025R0 method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `ArchiveV2025R0`. Returns a new archive object. ## Delete archive Permanently deletes an archive. This operation is performed by calling function `DeleteArchiveByIdV2025R0`. See the endpoint docs at [API Reference](https://developer.box.com/reference/v2025.0/delete-archives-id/). ``` await client.Archives.DeleteArchiveByIdV2025R0Async(archiveId: archive.Id); ``` ### Arguments archiveId `string` - The ID of the archive. Example: "982312" headers `DeleteArchiveByIdV2025R0Headers` - Headers of deleteArchiveByIdV2025R0 method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `null`. Returns an empty response when the archive has been deleted. --- ### IAuthorizationManager **Type:** page | **Section:** Additional Resources IAuthorizationManager Authorize user Request access token Refresh access token Revoke access token Authorize user Authorize a user by… # IAuthorizationManager - [Authorize user](#authorize-user) - [Request access token](#request-access-token) - [Refresh access token](#refresh-access-token) - [Revoke access token](#revoke-access-token) ## Authorize user Authorize a user by sending them through the [Box](https://box.com) website and request their permission to act on their behalf. This is the first step when authenticating a user using OAuth 2.0. To request a user's authorization to use the Box APIs on their behalf you will need to send a user to the URL with this format. This operation is performed by calling function `AuthorizeUser`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-authorize/). *Currently we don't have an example for calling `AuthorizeUser` in integration tests* ### Arguments queryParams `AuthorizeUserQueryParams` - Query parameters of authorizeUser method headers `AuthorizeUserHeaders` - Headers of authorizeUser method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `null`. Does not return any data, but rather should be used in the browser. ## Request access token Request an Access Token using either a client-side obtained OAuth 2.0 authorization code or a server-side JWT assertion. An Access Token is a string that enables Box to verify that a request belongs to an authorized session. In the normal order of operations you will begin by requesting authentication from the [authorize](#get-authorize) endpoint and Box will send you an authorization code. You will then send this code to this endpoint to exchange it for an Access Token. The returned Access Token can then be used to to make Box API calls. This operation is performed by calling function `RequestAccessToken`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-oauth2-token/). *Currently we don't have an example for calling `RequestAccessToken` in integration tests* ### Arguments requestBody `PostOAuth2Token` - Request body of requestAccessToken method headers `RequestAccessTokenHeaders` - Headers of requestAccessToken method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `AccessToken`. Returns a new Access Token that can be used to make authenticated API calls by passing along the token in a authorization header as follows `Authorization: Bearer <Token>`. ## Refresh access token Refresh an Access Token using its client ID, secret, and refresh token. This operation is performed by calling function `RefreshAccessToken`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-oauth2-token--refresh/). *Currently we don't have an example for calling `RefreshAccessToken` in integration tests* ### Arguments requestBody `PostOAuth2TokenRefreshAccessToken` - Request body of refreshAccessToken method headers `RefreshAccessTokenHeaders` - Headers of refreshAccessToken method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `AccessToken`. Returns a new Access Token that can be used to make authenticated API calls by passing along the token in a authorization header as follows `Authorization: Bearer <Token>`. ## Revoke access token Revoke an active Access Token, effectively logging a user out that has been previously authenticated. This operation is performed by calling function `RevokeAccessToken`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-oauth2-revoke/). *Currently we don't have an example for calling `RevokeAccessToken` in integration tests* ### Arguments requestBody `PostOAuth2Revoke` - Request body of revokeAccessToken method headers `RevokeAccessTokenHeaders` - Headers of revokeAccessToken method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `null`. Returns an empty response when the token was successfully revoked. --- ### IAvatarsManager **Type:** page | **Section:** Additional Resources IAvatarsManager Get user avatar Add or update user avatar Delete user avatar Get user avatar Retrieves an image of a the user's avatar. This… # IAvatarsManager - [Get user avatar](#get-user-avatar) - [Add or update user avatar](#add-or-update-user-avatar) - [Delete user avatar](#delete-user-avatar) ## Get user avatar Retrieves an image of a the user's avatar. This operation is performed by calling function `GetUserAvatar`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-users-id-avatar/). ``` await client.Avatars.GetUserAvatarAsync(userId: user.Id); ``` ### Arguments userId `string` - The ID of the user. Example: "12345" headers `GetUserAvatarHeaders` - Headers of getUserAvatar method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `System.IO.Stream`. When an avatar can be found for the user the image data will be returned in the body of the response. ## Add or update user avatar Adds or updates a user avatar. This operation is performed by calling function `CreateUserAvatar`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-users-id-avatar/). ``` await client.Avatars.CreateUserAvatarAsync(userId: user.Id, requestBody: new CreateUserAvatarRequestBody(pic: Utils.DecodeBase64ByteStream(data: "iVBORw0KGgoAAAANSUhEUgAAAQAAAAEAAQMAAABmvDolAAAAA1BMVEW10NBjBBbqAAAAH0lEQVRoge3BAQ0AAADCoPdPbQ43oAAAAAAAAAAAvg0hAAABmmDh1QAAAABJRU5ErkJggg==")) { PicContentType = "image/png", PicFileName = "avatar.png" }); ``` ### Arguments userId `string` - The ID of the user. Example: "12345" requestBody `CreateUserAvatarRequestBody` - Request body of createUserAvatar method headers `CreateUserAvatarHeaders` - Headers of createUserAvatar method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `UserAvatar`. `ok`: Returns the `pic_urls` object with URLs to existing user avatars that were updated.`created`: Returns the `pic_urls` object with URLS to user avatars uploaded to Box with the request. ## Delete user avatar Removes an existing user avatar. You cannot reverse this operation. This operation is performed by calling function `DeleteUserAvatar`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-users-id-avatar/). ``` await client.Avatars.DeleteUserAvatarAsync(userId: user.Id); ``` ### Arguments userId `string` - The ID of the user. Example: "12345" headers `DeleteUserAvatarHeaders` - Headers of deleteUserAvatar method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `null`. `no_content`: Removes the avatar and returns an empty response. --- ### IChunkedUploadsManager **Type:** page | **Section:** Additional Resources IChunkedUploadsManager Create upload session Create upload session for existing file Get upload session by URL Get upload session Upload… # IChunkedUploadsManager - [Create upload session](#create-upload-session) - [Create upload session for existing file](#create-upload-session-for-existing-file) - [Get upload session by URL](#get-upload-session-by-url) - [Get upload session](#get-upload-session) - [Upload part of file by URL](#upload-part-of-file-by-url) - [Upload part of file](#upload-part-of-file) - [Remove upload session by URL](#remove-upload-session-by-url) - [Remove upload session](#remove-upload-session) - [List parts by URL](#list-parts-by-url) - [List parts](#list-parts) - [Commit upload session by URL](#commit-upload-session-by-url) - [Commit upload session](#commit-upload-session) - [Upload big file](#upload-big-file) ## Create upload session Creates an upload session for a new file. This operation is performed by calling function `CreateFileUploadSession`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-files-upload-sessions/). ``` await client.ChunkedUploads.CreateFileUploadSessionAsync(requestBody: new CreateFileUploadSessionRequestBody(fileName: fileName, fileSize: fileSize, folderId: parentFolderId)); ``` ### Arguments requestBody `CreateFileUploadSessionRequestBody` - Request body of createFileUploadSession method headers `CreateFileUploadSessionHeaders` - Headers of createFileUploadSession method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `UploadSession`. Returns a new upload session. ## Create upload session for existing file Creates an upload session for an existing file. This operation is performed by calling function `CreateFileUploadSessionForExistingFile`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-files-id-upload-sessions/). *Currently we don't have an example for calling `CreateFileUploadSessionForExistingFile` in integration tests* ### Arguments fileId `string` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" requestBody `CreateFileUploadSessionForExistingFileRequestBody` - Request body of createFileUploadSessionForExistingFile method headers `CreateFileUploadSessionForExistingFileHeaders` - Headers of createFileUploadSessionForExistingFile method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `UploadSession`. Returns a new upload session. ## Get upload session by URL Return information about an upload session. The actual endpoint URL is returned by the [`Create upload session`](e://post-files-upload-sessions) endpoint. This operation is performed by calling function `GetFileUploadSessionByUrl`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-files-upload-sessions-id/). ``` await client.ChunkedUploads.GetFileUploadSessionByUrlAsync(url: statusUrl); ``` ### Arguments url `string` - URL of getFileUploadSessionById method headers `GetFileUploadSessionByUrlHeaders` - Headers of getFileUploadSessionById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `UploadSession`. Returns an upload session object. ## Get upload session Return information about an upload session. The actual endpoint URL is returned by the [`Create upload session`](e://post-files-upload-sessions) endpoint. This operation is performed by calling function `GetFileUploadSessionById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-files-upload-sessions-id/). ``` await client.ChunkedUploads.GetFileUploadSessionByIdAsync(uploadSessionId: uploadSessionId); ``` ### Arguments uploadSessionId `string` - The ID of the upload session. Example: "D5E3F7A" headers `GetFileUploadSessionByIdHeaders` - Headers of getFileUploadSessionById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `UploadSession`. Returns an upload session object. ## Upload part of file by URL Uploads a chunk of a file for an upload session. The actual endpoint URL is returned by the [`Create upload session`](e://post-files-upload-sessions) and [`Get upload session`](e://get-files-upload-sessions-id) endpoints. This operation is performed by calling function `UploadFilePartByUrl`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-files-upload-sessions-id/). ``` await client.ChunkedUploads.UploadFilePartByUrlAsync(url: acc.UploadPartUrl, requestBody: Utils.GenerateByteStreamFromBuffer(buffer: chunkBuffer), headers: new UploadFilePartByUrlHeaders(digest: digest, contentRange: contentRange)); ``` ### Arguments url `string` - URL of uploadFilePart method requestBody `System.IO.Stream` - Request body of uploadFilePart method headers `UploadFilePartByUrlHeaders` - Headers of uploadFilePart method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `UploadedPart`. Chunk has been uploaded successfully. ## Upload part of file Uploads a chunk of a file for an upload session. The actual endpoint URL is returned by the [`Create upload session`](e://post-files-upload-sessions) and [`Get upload session`](e://get-files-upload-sessions-id) endpoints. This operation is performed by calling function `UploadFilePart`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-files-upload-sessions-id/). ``` await client.ChunkedUploads.UploadFilePartAsync(uploadSessionId: acc.UploadSessionId, requestBody: Utils.GenerateByteStreamFromBuffer(buffer: chunkBuffer), headers: new UploadFilePartHeaders(digest: digest, contentRange: contentRange)); ``` ### Arguments uploadSessionId `string` - The ID of the upload session. Example: "D5E3F7A" requestBody `System.IO.Stream` - Request body of uploadFilePart method headers `UploadFilePartHeaders` - Headers of uploadFilePart method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `UploadedPart`. Chunk has been uploaded successfully. ## Remove upload session by URL Abort an upload session and discard all data uploaded. This cannot be reversed. The actual endpoint URL is returned by the [`Create upload session`](e://post-files-upload-sessions) and [`Get upload session`](e://get-files-upload-sessions-id) endpoints. This operation is performed by calling function `DeleteFileUploadSessionByUrl`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-files-upload-sessions-id/). ``` await client.ChunkedUploads.DeleteFileUploadSessionByUrlAsync(url: abortUrl); ``` ### Arguments url `string` - URL of deleteFileUploadSessionById method headers `DeleteFileUploadSessionByUrlHeaders` - Headers of deleteFileUploadSessionById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `null`. A blank response is returned if the session was successfully aborted. ## Remove upload session Abort an upload session and discard all data uploaded. This cannot be reversed. The actual endpoint URL is returned by the [`Create upload session`](e://post-files-upload-sessions) and [`Get upload session`](e://get-files-upload-sessions-id) endpoints. This operation is performed by calling function `DeleteFileUploadSessionById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-files-upload-sessions-id/). ``` await client.ChunkedUploads.DeleteFileUploadSessionByIdAsync(uploadSessionId: uploadSessionId); ``` ### Arguments uploadSessionId `string` - The ID of the upload session. Example: "D5E3F7A" headers `DeleteFileUploadSessionByIdHeaders` - Headers of deleteFileUploadSessionById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `null`. A blank response is returned if the session was successfully aborted. ## List parts by URL Return a list of the chunks uploaded to the upload session so far. The actual endpoint URL is returned by the [`Create upload session`](e://post-files-upload-sessions) and [`Get upload session`](e://get-files-upload-sessions-id) endpoints. This operation is performed by calling function `GetFileUploadSessionPartsByUrl`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-files-upload-sessions-id-parts/). ``` await client.ChunkedUploads.GetFileUploadSessionPartsByUrlAsync(url: listPartsUrl); ``` ### Arguments url `string` - URL of getFileUploadSessionParts method queryParams `GetFileUploadSessionPartsByUrlQueryParams` - Query parameters of getFileUploadSessionParts method headers `GetFileUploadSessionPartsByUrlHeaders` - Headers of getFileUploadSessionParts method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `UploadParts`. Returns a list of parts that have been uploaded. ## List parts Return a list of the chunks uploaded to the upload session so far. The actual endpoint URL is returned by the [`Create upload session`](e://post-files-upload-sessions) and [`Get upload session`](e://get-files-upload-sessions-id) endpoints. This operation is performed by calling function `GetFileUploadSessionParts`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-files-upload-sessions-id-parts/). ``` await client.ChunkedUploads.GetFileUploadSessionPartsAsync(uploadSessionId: uploadSessionId); ``` ### Arguments uploadSessionId `string` - The ID of the upload session. Example: "D5E3F7A" queryParams `GetFileUploadSessionPartsQueryParams` - Query parameters of getFileUploadSessionParts method headers `GetFileUploadSessionPartsHeaders` - Headers of getFileUploadSessionParts method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `UploadParts`. Returns a list of parts that have been uploaded. ## Commit upload session by URL Close an upload session and create a file from the uploaded chunks. The actual endpoint URL is returned by the [`Create upload session`](e://post-files-upload-sessions) and [`Get upload session`](e://get-files-upload-sessions-id) endpoints. This operation is performed by calling function `CreateFileUploadSessionCommitByUrl`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-files-upload-sessions-id-commit/). ``` await client.ChunkedUploads.CreateFileUploadSessionCommitByUrlAsync(url: commitUrl, requestBody: new CreateFileUploadSessionCommitByUrlRequestBody(parts: parts), headers: new CreateFileUploadSessionCommitByUrlHeaders(digest: digest)); ``` ### Arguments url `string` - URL of createFileUploadSessionCommit method requestBody `CreateFileUploadSessionCommitByUrlRequestBody` - Request body of createFileUploadSessionCommit method headers `CreateFileUploadSessionCommitByUrlHeaders` - Headers of createFileUploadSessionCommit method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `Files?`. Returns the file object in a list.Returns when all chunks have been uploaded but not yet processed. Inspect the upload session to get more information about the progress of processing the chunks, then retry committing the file when all chunks have processed. ## Commit upload session Close an upload session and create a file from the uploaded chunks. The actual endpoint URL is returned by the [`Create upload session`](e://post-files-upload-sessions) and [`Get upload session`](e://get-files-upload-sessions-id) endpoints. This operation is performed by calling function `CreateFileUploadSessionCommit`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-files-upload-sessions-id-commit/). ``` await client.ChunkedUploads.CreateFileUploadSessionCommitAsync(uploadSessionId: uploadSessionId, requestBody: new CreateFileUploadSessionCommitRequestBody(parts: parts), headers: new CreateFileUploadSessionCommitHeaders(digest: digest)); ``` ### Arguments uploadSessionId `string` - The ID of the upload session. Example: "D5E3F7A" requestBody `CreateFileUploadSessionCommitRequestBody` - Request body of createFileUploadSessionCommit method headers `CreateFileUploadSessionCommitHeaders` - Headers of createFileUploadSessionCommit method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `Files?`. Returns the file object in a list.Returns when all chunks have been uploaded but not yet processed. Inspect the upload session to get more information about the progress of processing the chunks, then retry committing the file when all chunks have processed. ## Upload big file Starts the process of chunk uploading a big file. Should return a File object representing uploaded file. This operation is performed by calling function `UploadBigFile`. ``` await client.ChunkedUploads.UploadBigFileAsync(file: fileByteStream, fileName: fileName, fileSize: fileSize, parentFolderId: parentFolderId); ``` ### Arguments file `System.IO.Stream` - The stream of the file to upload. fileName `string` - The name of the file, which will be used for storage in Box. fileSize `long` - The total size of the file for the chunked upload in bytes. parentFolderId `string` - The ID of the folder where the file should be uploaded. cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `FileFull`. --- ### IClassificationsManager **Type:** page | **Section:** Additional Resources IClassificationsManager List all classifications Add classification Update classification Add initial classifications List all… # IClassificationsManager - [List all classifications](#list-all-classifications) - [Add classification](#add-classification) - [Update classification](#update-classification) - [Add initial classifications](#add-initial-classifications) ## List all classifications Retrieves the classification metadata template and lists all the classifications available to this enterprise. This API can also be called by including the enterprise ID in the URL explicitly, for example `/metadata_templates/enterprise_12345/securityClassification-6VMVochwUWo/schema`. This operation is performed by calling function `GetClassificationTemplate`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-metadata-templates-enterprise-securityClassification-6VMVochwUWo-schema/). ``` await client.Classifications.GetClassificationTemplateAsync(); ``` ### Arguments headers `GetClassificationTemplateHeaders` - Headers of getClassificationTemplate method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `ClassificationTemplate`. Returns the `securityClassification` metadata template, which contains a `Box__Security__Classification__Key` field that lists all the classifications available to this enterprise. ## Add classification Adds one or more new classifications to the list of classifications available to the enterprise. This API can also be called by including the enterprise ID in the URL explicitly, for example `/metadata_templates/enterprise_12345/securityClassification-6VMVochwUWo/schema`. This operation is performed by calling function `AddClassification`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-metadata-templates-enterprise-securityClassification-6VMVochwUWo-schema--add/). ``` await client.Classifications.AddClassificationAsync(requestBody: Array.AsReadOnly(new [] {new AddClassificationRequestBody(data: new AddClassificationRequestBodyDataField(key: Utils.GetUUID()) { StaticConfig = new AddClassificationRequestBodyDataStaticConfigField() { Classification = new AddClassificationRequestBodyDataStaticConfigClassificationField() { ColorId = 4, ClassificationDefinition = "Other description" } } })})); ``` ### Arguments requestBody `IReadOnlyList<AddClassificationRequestBody>` - Request body of addClassification method headers `AddClassificationHeaders` - Headers of addClassification method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `ClassificationTemplate`. Returns the updated `securityClassification` metadata template, which contains a `Box__Security__Classification__Key` field that lists all the classifications available to this enterprise. ## Update classification Updates the labels and descriptions of one or more classifications available to the enterprise. This API can also be called by including the enterprise ID in the URL explicitly, for example `/metadata_templates/enterprise_12345/securityClassification-6VMVochwUWo/schema`. This operation is performed by calling function `UpdateClassification`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-metadata-templates-enterprise-securityClassification-6VMVochwUWo-schema--update/). ``` await client.Classifications.UpdateClassificationAsync(requestBody: Array.AsReadOnly(new [] {new UpdateClassificationRequestBody(enumOptionKey: classification.Key, data: new UpdateClassificationRequestBodyDataField(key: updatedClassificationName) { StaticConfig = new UpdateClassificationRequestBodyDataStaticConfigField() { Classification = new UpdateClassificationRequestBodyDataStaticConfigClassificationField() { ColorId = 2, ClassificationDefinition = updatedClassificationDescription } } })})); ``` ### Arguments requestBody `IReadOnlyList<UpdateClassificationRequestBody>` - Request body of updateClassification method headers `UpdateClassificationHeaders` - Headers of updateClassification method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `ClassificationTemplate`. Returns the updated `securityClassification` metadata template, which contains a `Box__Security__Classification__Key` field that lists all the classifications available to this enterprise. ## Add initial classifications When an enterprise does not yet have any classifications, this API call initializes the classification template with an initial set of classifications. If an enterprise already has a classification, the template will already exist and instead an API call should be made to add additional classifications. This operation is performed by calling function `CreateClassificationTemplate`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-metadata-templates-schema--classifications/). *Currently we don't have an example for calling `CreateClassificationTemplate` in integration tests* ### Arguments requestBody `CreateClassificationTemplateRequestBody` - Request body of createClassificationTemplate method headers `CreateClassificationTemplateHeaders` - Headers of createClassificationTemplate method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `ClassificationTemplate`. Returns a new `securityClassification` metadata template, which contains a `Box__Security__Classification__Key` field that lists all the classifications available to this enterprise. --- ### ICollaborationAllowlistEntriesManager **Type:** page | **Section:** Additional Resources ICollaborationAllowlistEntriesManager List allowed collaboration domains Add domain to list of allowed collaboration domains Get allowed… # ICollaborationAllowlistEntriesManager - [List allowed collaboration domains](#list-allowed-collaboration-domains) - [Add domain to list of allowed collaboration domains](#add-domain-to-list-of-allowed-collaboration-domains) - [Get allowed collaboration domain](#get-allowed-collaboration-domain) - [Remove domain from list of allowed collaboration domains](#remove-domain-from-list-of-allowed-collaboration-domains) ## List allowed collaboration domains Returns the list domains that have been deemed safe to create collaborations for within the current enterprise. This operation is performed by calling function `GetCollaborationWhitelistEntries`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-collaboration-whitelist-entries/). ``` await client.CollaborationAllowlistEntries.GetCollaborationWhitelistEntriesAsync(); ``` ### Arguments queryParams `GetCollaborationWhitelistEntriesQueryParams` - Query parameters of getCollaborationWhitelistEntries method headers `GetCollaborationWhitelistEntriesHeaders` - Headers of getCollaborationWhitelistEntries method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `CollaborationAllowlistEntries`. Returns a collection of domains that are allowed for collaboration. ## Add domain to list of allowed collaboration domains Creates a new entry in the list of allowed domains to allow collaboration for. This operation is performed by calling function `CreateCollaborationWhitelistEntry`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-collaboration-whitelist-entries/). ``` await client.CollaborationAllowlistEntries.CreateCollaborationWhitelistEntryAsync(requestBody: new CreateCollaborationWhitelistEntryRequestBody(direction: CreateCollaborationWhitelistEntryRequestBodyDirectionField.Inbound, domain: domain)); ``` ### Arguments requestBody `CreateCollaborationWhitelistEntryRequestBody` - Request body of createCollaborationWhitelistEntry method headers `CreateCollaborationWhitelistEntryHeaders` - Headers of createCollaborationWhitelistEntry method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `CollaborationAllowlistEntry`. Returns a new entry on the list of allowed domains. ## Get allowed collaboration domain Returns a domain that has been deemed safe to create collaborations for within the current enterprise. This operation is performed by calling function `GetCollaborationWhitelistEntryById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-collaboration-whitelist-entries-id/). ``` await client.CollaborationAllowlistEntries.GetCollaborationWhitelistEntryByIdAsync(collaborationWhitelistEntryId: NullableUtils.Unwrap(newEntry.Id)); ``` ### Arguments collaborationWhitelistEntryId `string` - The ID of the entry in the list. Example: "213123" headers `GetCollaborationWhitelistEntryByIdHeaders` - Headers of getCollaborationWhitelistEntryById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `CollaborationAllowlistEntry`. Returns an entry on the list of allowed domains. ## Remove domain from list of allowed collaboration domains Removes a domain from the list of domains that have been deemed safe to create collaborations for within the current enterprise. This operation is performed by calling function `DeleteCollaborationWhitelistEntryById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-collaboration-whitelist-entries-id/). ``` await client.CollaborationAllowlistEntries.DeleteCollaborationWhitelistEntryByIdAsync(collaborationWhitelistEntryId: NullableUtils.Unwrap(entry.Id)); ``` ### Arguments collaborationWhitelistEntryId `string` - The ID of the entry in the list. Example: "213123" headers `DeleteCollaborationWhitelistEntryByIdHeaders` - Headers of deleteCollaborationWhitelistEntryById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `null`. A blank response is returned if the entry was successfully deleted. --- ### ICollaborationAllowlistExemptTargetsManager **Type:** page | **Section:** Additional Resources ICollaborationAllowlistExemptTargetsManager List users exempt from collaboration domain restrictions Create user exemption from… # ICollaborationAllowlistExemptTargetsManager - [List users exempt from collaboration domain restrictions](#list-users-exempt-from-collaboration-domain-restrictions) - [Create user exemption from collaboration domain restrictions](#create-user-exemption-from-collaboration-domain-restrictions) - [Get user exempt from collaboration domain restrictions](#get-user-exempt-from-collaboration-domain-restrictions) - [Remove user from list of users exempt from domain restrictions](#remove-user-from-list-of-users-exempt-from-domain-restrictions) ## List users exempt from collaboration domain restrictions Returns a list of users who have been exempt from the collaboration domain restrictions. This operation is performed by calling function `GetCollaborationWhitelistExemptTargets`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-collaboration-whitelist-exempt-targets/). ``` await client.CollaborationAllowlistExemptTargets.GetCollaborationWhitelistExemptTargetsAsync(); ``` ### Arguments queryParams `GetCollaborationWhitelistExemptTargetsQueryParams` - Query parameters of getCollaborationWhitelistExemptTargets method headers `GetCollaborationWhitelistExemptTargetsHeaders` - Headers of getCollaborationWhitelistExemptTargets method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `CollaborationAllowlistExemptTargets`. Returns a collection of user exemptions. ## Create user exemption from collaboration domain restrictions Exempts a user from the restrictions set out by the allowed list of domains for collaborations. This operation is performed by calling function `CreateCollaborationWhitelistExemptTarget`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-collaboration-whitelist-exempt-targets/). ``` await client.CollaborationAllowlistExemptTargets.CreateCollaborationWhitelistExemptTargetAsync(requestBody: new CreateCollaborationWhitelistExemptTargetRequestBody(user: new CreateCollaborationWhitelistExemptTargetRequestBodyUserField(id: user.Id))); ``` ### Arguments requestBody `CreateCollaborationWhitelistExemptTargetRequestBody` - Request body of createCollaborationWhitelistExemptTarget method headers `CreateCollaborationWhitelistExemptTargetHeaders` - Headers of createCollaborationWhitelistExemptTarget method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `CollaborationAllowlistExemptTarget`. Returns a new exemption entry. ## Get user exempt from collaboration domain restrictions Returns a users who has been exempt from the collaboration domain restrictions. This operation is performed by calling function `GetCollaborationWhitelistExemptTargetById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-collaboration-whitelist-exempt-targets-id/). ``` await client.CollaborationAllowlistExemptTargets.GetCollaborationWhitelistExemptTargetByIdAsync(collaborationWhitelistExemptTargetId: NullableUtils.Unwrap(newExemptTarget.Id)); ``` ### Arguments collaborationWhitelistExemptTargetId `string` - The ID of the exemption to the list. Example: "984923" headers `GetCollaborationWhitelistExemptTargetByIdHeaders` - Headers of getCollaborationWhitelistExemptTargetById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `CollaborationAllowlistExemptTarget`. Returns the user's exempted from the list of collaboration domains. ## Remove user from list of users exempt from domain restrictions Removes a user's exemption from the restrictions set out by the allowed list of domains for collaborations. This operation is performed by calling function `DeleteCollaborationWhitelistExemptTargetById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-collaboration-whitelist-exempt-targets-id/). ``` await client.CollaborationAllowlistExemptTargets.DeleteCollaborationWhitelistExemptTargetByIdAsync(collaborationWhitelistExemptTargetId: NullableUtils.Unwrap(exemptTarget.Id)); ``` ### Arguments collaborationWhitelistExemptTargetId `string` - The ID of the exemption to the list. Example: "984923" headers `DeleteCollaborationWhitelistExemptTargetByIdHeaders` - Headers of deleteCollaborationWhitelistExemptTargetById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `null`. A blank response is returned if the exemption was successfully deleted. --- ### ICollectionsManager **Type:** page | **Section:** Additional Resources ICollectionsManager List all collections List collection items Get collection by ID List all collections Retrieves all collections for a… # ICollectionsManager - [List all collections](#list-all-collections) - [List collection items](#list-collection-items) - [Get collection by ID](#get-collection-by-id) ## List all collections Retrieves all collections for a given user. Currently, only the `favorites` collection is supported. This operation is performed by calling function `GetCollections`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-collections/). ``` await client.Collections.GetCollectionsAsync(); ``` ### Arguments queryParams `GetCollectionsQueryParams` - Query parameters of getCollections method headers `GetCollectionsHeaders` - Headers of getCollections method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `Collections`. Returns all collections for the given user. ## List collection items Retrieves the files and/or folders contained within this collection. This operation is performed by calling function `GetCollectionItems`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-collections-id-items/). ``` await client.Collections.GetCollectionItemsAsync(collectionId: NullableUtils.Unwrap(favouriteCollection.Id)); ``` ### Arguments collectionId `string` - The ID of the collection. Example: "926489" queryParams `GetCollectionItemsQueryParams` - Query parameters of getCollectionItems method headers `GetCollectionItemsHeaders` - Headers of getCollectionItems method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `ItemsOffsetPaginated`. Returns an array of items in the collection. ## Get collection by ID Retrieves a collection by its ID. This operation is performed by calling function `GetCollectionById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-collections-id/). ``` await client.Collections.GetCollectionByIdAsync(collectionId: NullableUtils.Unwrap(NullableUtils.Unwrap(collections.Entries)[0].Id)); ``` ### Arguments collectionId `string` - The ID of the collection. Example: "926489" headers `GetCollectionByIdHeaders` - Headers of getCollectionById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `Collection`. Returns an array of items in the collection. --- ### ICommentsManager **Type:** page | **Section:** Additional Resources ICommentsManager List file comments Get comment Update comment Remove comment Create comment List file comments Retrieves a list of comments… # ICommentsManager - [List file comments](#list-file-comments) - [Get comment](#get-comment) - [Update comment](#update-comment) - [Remove comment](#remove-comment) - [Create comment](#create-comment) ## List file comments Retrieves a list of comments for a file. This operation is performed by calling function `GetFileComments`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-files-id-comments/). ``` await client.Comments.GetFileCommentsAsync(fileId: fileId); ``` ### Arguments fileId `string` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" queryParams `GetFileCommentsQueryParams` - Query parameters of getFileComments method headers `GetFileCommentsHeaders` - Headers of getFileComments method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `Comments`. Returns a collection of comment objects. If there are no comments on this file an empty collection will be returned. ## Get comment Retrieves the message and metadata for a specific comment, as well as information on the user who created the comment. This operation is performed by calling function `GetCommentById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-comments-id/). ``` await client.Comments.GetCommentByIdAsync(commentId: NullableUtils.Unwrap(newComment.Id)); ``` ### Arguments commentId `string` - The ID of the comment. Example: "12345" queryParams `GetCommentByIdQueryParams` - Query parameters of getCommentById method headers `GetCommentByIdHeaders` - Headers of getCommentById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `CommentFull`. Returns a full comment object. ## Update comment Update the message of a comment. This operation is performed by calling function `UpdateCommentById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-comments-id/). ``` await client.Comments.UpdateCommentByIdAsync(commentId: NullableUtils.Unwrap(newReplyComment.Id), requestBody: new UpdateCommentByIdRequestBody() { Message = newMessage }); ``` ### Arguments commentId `string` - The ID of the comment. Example: "12345" requestBody `UpdateCommentByIdRequestBody` - Request body of updateCommentById method queryParams `UpdateCommentByIdQueryParams` - Query parameters of updateCommentById method headers `UpdateCommentByIdHeaders` - Headers of updateCommentById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `CommentFull`. Returns the updated comment object. ## Remove comment Permanently deletes a comment. This operation is performed by calling function `DeleteCommentById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-comments-id/). ``` await client.Comments.DeleteCommentByIdAsync(commentId: NullableUtils.Unwrap(newComment.Id)); ``` ### Arguments commentId `string` - The ID of the comment. Example: "12345" headers `DeleteCommentByIdHeaders` - Headers of deleteCommentById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `null`. Returns an empty response when the comment has been deleted. ## Create comment Adds a comment by the user to a specific file, or as a reply to an other comment. This operation is performed by calling function `CreateComment`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-comments/). ``` await client.Comments.CreateCommentAsync(requestBody: new CreateCommentRequestBody(message: message, item: new CreateCommentRequestBodyItemField(id: fileId, type: CreateCommentRequestBodyItemTypeField.File))); ``` ### Arguments requestBody `CreateCommentRequestBody` - Request body of createComment method queryParams `CreateCommentQueryParams` - Query parameters of createComment method headers `CreateCommentHeaders` - Headers of createComment method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `CommentFull`. Returns the newly created comment object. Not all available fields are returned by default. Use the [fields](#param-fields) query parameter to explicitly request any specific fields. --- ### IDevicePinnersManager **Type:** page | **Section:** Additional Resources IDevicePinnersManager Get device pin Remove device pin List enterprise device pins Get device pin Retrieves information about an individual… # IDevicePinnersManager - [Get device pin](#get-device-pin) - [Remove device pin](#remove-device-pin) - [List enterprise device pins](#list-enterprise-device-pins) ## Get device pin Retrieves information about an individual device pin. This operation is performed by calling function `GetDevicePinnerById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-device-pinners-id/). ``` await client.DevicePinners.GetDevicePinnerByIdAsync(devicePinnerId: devicePinnerId); ``` ### Arguments devicePinnerId `string` - The ID of the device pin. Example: "2324234" headers `GetDevicePinnerByIdHeaders` - Headers of getDevicePinnerById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `DevicePinner`. Returns information about a single device pin. ## Remove device pin Deletes an individual device pin. This operation is performed by calling function `DeleteDevicePinnerById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-device-pinners-id/). ``` await client.DevicePinners.DeleteDevicePinnerByIdAsync(devicePinnerId: devicePinnerId); ``` ### Arguments devicePinnerId `string` - The ID of the device pin. Example: "2324234" headers `DeleteDevicePinnerByIdHeaders` - Headers of deleteDevicePinnerById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `null`. Returns an empty response when the pin has been deleted. ## List enterprise device pins Retrieves all the device pins within an enterprise. The user must have admin privileges, and the application needs the "manage enterprise" scope to make this call. This operation is performed by calling function `GetEnterpriseDevicePinners`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-enterprises-id-device-pinners/). ``` await client.DevicePinners.GetEnterpriseDevicePinnersAsync(enterpriseId: enterpriseId); ``` ### Arguments enterpriseId `string` - The ID of the enterprise. Example: "3442311" queryParams `GetEnterpriseDevicePinnersQueryParams` - Query parameters of getEnterpriseDevicePinners method headers `GetEnterpriseDevicePinnersHeaders` - Headers of getEnterpriseDevicePinners method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `DevicePinners`. Returns a list of device pins for a given enterprise. --- ### IDocgenManager **Type:** page | **Section:** Additional Resources IDocgenManager Get Box Doc Gen job by ID List all Box Doc Gen jobs Get Box Doc Gen jobs by batch ID Generate document using Box Doc Gen… # IDocgenManager - [Get Box Doc Gen job by ID](#get-box-doc-gen-job-by-id) - [List all Box Doc Gen jobs](#list-all-box-doc-gen-jobs) - [Get Box Doc Gen jobs by batch ID](#get-box-doc-gen-jobs-by-batch-id) - [Generate document using Box Doc Gen template](#generate-document-using-box-doc-gen-template) ## Get Box Doc Gen job by ID Get details of the Box Doc Gen job. This operation is performed by calling function `GetDocgenJobByIdV2025R0`. See the endpoint docs at [API Reference](https://developer.box.com/reference/v2025.0/get-docgen-jobs-id/). ``` await client.Docgen.GetDocgenJobByIdV2025R0Async(jobId: docgenJobItemFromList.Id); ``` ### Arguments jobId `string` - Box Doc Gen job ID. Example: 123 headers `GetDocgenJobByIdV2025R0Headers` - Headers of getDocgenJobByIdV2025R0 method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `DocGenJobV2025R0`. Details of the Box Doc Gen job. ## List all Box Doc Gen jobs Lists all Box Doc Gen jobs for a user. This operation is performed by calling function `GetDocgenJobsV2025R0`. See the endpoint docs at [API Reference](https://developer.box.com/reference/v2025.0/get-docgen-jobs/). ``` await client.Docgen.GetDocgenJobsV2025R0Async(queryParams: new GetDocgenJobsV2025R0QueryParams() { Limit = 10000 }); ``` ### Arguments queryParams `GetDocgenJobsV2025R0QueryParams` - Query parameters of getDocgenJobsV2025R0 method headers `GetDocgenJobsV2025R0Headers` - Headers of getDocgenJobsV2025R0 method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `DocGenJobsFullV2025R0`. A list of Box Doc Gen jobs. ## Get Box Doc Gen jobs by batch ID Lists Box Doc Gen jobs in a batch. This operation is performed by calling function `GetDocgenBatchJobByIdV2025R0`. See the endpoint docs at [API Reference](https://developer.box.com/reference/v2025.0/get-docgen-batch-jobs-id/). ``` await client.Docgen.GetDocgenBatchJobByIdV2025R0Async(batchId: docgenBatch.Id); ``` ### Arguments batchId `string` - Box Doc Gen batch ID. Example: 123 queryParams `GetDocgenBatchJobByIdV2025R0QueryParams` - Query parameters of getDocgenBatchJobByIdV2025R0 method headers `GetDocgenBatchJobByIdV2025R0Headers` - Headers of getDocgenBatchJobByIdV2025R0 method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `DocGenJobsV2025R0`. Returns a list of Box Doc Gen jobs in a Box Doc Gen batch. ## Generate document using Box Doc Gen template Generates a document using a Box Doc Gen template. This operation is performed by calling function `CreateDocgenBatchV2025R0`. See the endpoint docs at [API Reference](https://developer.box.com/reference/v2025.0/post-docgen-batches/). ``` await client.Docgen.CreateDocgenBatchV2025R0Async(requestBody: new DocGenBatchCreateRequestV2025R0(file: new FileReferenceV2025R0(id: uploadedFile.Id), inputSource: "api", destinationFolder: new DocGenBatchCreateRequestV2025R0DestinationFolderField(id: folder.Id), outputType: "pdf", documentGenerationData: Array.AsReadOnly(new [] {new DocGenDocumentGenerationDataV2025R0(generatedFileName: "test", userInput: new Dictionary<string, object>() { { "abc", "xyz" } })}))); ``` ### Arguments requestBody `DocGenBatchCreateRequestV2025R0` - Request body of createDocgenBatchV2025R0 method headers `CreateDocgenBatchV2025R0Headers` - Headers of createDocgenBatchV2025R0 method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `DocGenBatchBaseV2025R0`. The created Batch ID. --- ### IDocgenTemplateManager **Type:** page | **Section:** Additional Resources IDocgenTemplateManager Create Box Doc Gen template List Box Doc Gen templates Delete Box Doc Gen template Get Box Doc Gen template by ID… # IDocgenTemplateManager - [Create Box Doc Gen template](#create-box-doc-gen-template) - [List Box Doc Gen templates](#list-box-doc-gen-templates) - [Delete Box Doc Gen template](#delete-box-doc-gen-template) - [Get Box Doc Gen template by ID](#get-box-doc-gen-template-by-id) - [List all Box Doc Gen template tags in template](#list-all-box-doc-gen-template-tags-in-template) - [Get list of all Box Doc Gen jobs for template](#get-list-of-all-box-doc-gen-jobs-for-template) ## Create Box Doc Gen template Marks a file as a Box Doc Gen template. This operation is performed by calling function `CreateDocgenTemplateV2025R0`. See the endpoint docs at [API Reference](https://developer.box.com/reference/v2025.0/post-docgen-templates/). ``` await client.DocgenTemplate.CreateDocgenTemplateV2025R0Async(requestBody: new DocGenTemplateCreateRequestV2025R0(file: new FileReferenceV2025R0(id: file.Id))); ``` ### Arguments requestBody `DocGenTemplateCreateRequestV2025R0` - Request body of createDocgenTemplateV2025R0 method headers `CreateDocgenTemplateV2025R0Headers` - Headers of createDocgenTemplateV2025R0 method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `DocGenTemplateBaseV2025R0`. The file which has now been marked as a Box Doc Gen template. ## List Box Doc Gen templates Lists Box Doc Gen templates on which the user is a collaborator. This operation is performed by calling function `GetDocgenTemplatesV2025R0`. See the endpoint docs at [API Reference](https://developer.box.com/reference/v2025.0/get-docgen-templates/). ``` await client.DocgenTemplate.GetDocgenTemplatesV2025R0Async(); ``` ### Arguments queryParams `GetDocgenTemplatesV2025R0QueryParams` - Query parameters of getDocgenTemplatesV2025R0 method headers `GetDocgenTemplatesV2025R0Headers` - Headers of getDocgenTemplatesV2025R0 method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `DocGenTemplatesV2025R0`. Returns a collection of templates. ## Delete Box Doc Gen template Unmarks file as Box Doc Gen template. This operation is performed by calling function `DeleteDocgenTemplateByIdV2025R0`. See the endpoint docs at [API Reference](https://developer.box.com/reference/v2025.0/delete-docgen-templates-id/). ``` await client.DocgenTemplate.DeleteDocgenTemplateByIdV2025R0Async(templateId: NullableUtils.Unwrap(createdDocgenTemplate.File).Id); ``` ### Arguments templateId `string` - ID of the file which will no longer be marked as a Box Doc Gen template. Example: "123" headers `DeleteDocgenTemplateByIdV2025R0Headers` - Headers of deleteDocgenTemplateByIdV2025R0 method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `null`. Returns an empty response when a file is no longer marked as a Box Doc Gen template. ## Get Box Doc Gen template by ID Lists details of a specific Box Doc Gen template. This operation is performed by calling function `GetDocgenTemplateByIdV2025R0`. See the endpoint docs at [API Reference](https://developer.box.com/reference/v2025.0/get-docgen-templates-id/). ``` await client.DocgenTemplate.GetDocgenTemplateByIdV2025R0Async(templateId: NullableUtils.Unwrap(createdDocgenTemplate.File).Id); ``` ### Arguments templateId `string` - The ID of a Box Doc Gen template. Example: 123 headers `GetDocgenTemplateByIdV2025R0Headers` - Headers of getDocgenTemplateByIdV2025R0 method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `DocGenTemplateV2025R0`. Returns a template. ## List all Box Doc Gen template tags in template Lists all tags in a Box Doc Gen template. This operation is performed by calling function `GetDocgenTemplateTagsV2025R0`. See the endpoint docs at [API Reference](https://developer.box.com/reference/v2025.0/get-docgen-templates-id-tags/). ``` await client.DocgenTemplate.GetDocgenTemplateTagsV2025R0Async(templateId: NullableUtils.Unwrap(fetchedDocgenTemplate.File).Id); ``` ### Arguments templateId `string` - ID of template. Example: 123 queryParams `GetDocgenTemplateTagsV2025R0QueryParams` - Query parameters of getDocgenTemplateTagsV2025R0 method headers `GetDocgenTemplateTagsV2025R0Headers` - Headers of getDocgenTemplateTagsV2025R0 method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `DocGenTagsV2025R0`. A list of document generation template tags.Processing tags for the file. ## Get list of all Box Doc Gen jobs for template Lists the users jobs which use this template. This operation is performed by calling function `GetDocgenTemplateJobByIdV2025R0`. See the endpoint docs at [API Reference](https://developer.box.com/reference/v2025.0/get-docgen-template-jobs-id/). ``` await client.DocgenTemplate.GetDocgenTemplateJobByIdV2025R0Async(templateId: NullableUtils.Unwrap(fetchedDocgenTemplate.File).Id); ``` ### Arguments templateId `string` - Id of template to fetch jobs for. Example: 123 queryParams `GetDocgenTemplateJobByIdV2025R0QueryParams` - Query parameters of getDocgenTemplateJobByIdV2025R0 method headers `GetDocgenTemplateJobByIdV2025R0Headers` - Headers of getDocgenTemplateJobByIdV2025R0 method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `DocGenJobsV2025R0`. A single Box Doc Gen template. --- ### IDownloadsManager **Type:** page | **Section:** Additional Resources IDownloadsManager Download file URL Download file Download file URL Get the download URL without downloading the content. This operation is… # IDownloadsManager - [Download file URL](#download-file-url) - [Download file](#download-file) ## Download file URL Get the download URL without downloading the content. This operation is performed by calling function `GetDownloadFileUrl`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-files-id-content/). ``` await client.Downloads.GetDownloadFileUrlAsync(fileId: uploadedFile.Id); ``` ### Arguments fileId `string` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" queryParams `GetDownloadFileUrlQueryParams` - Query parameters of downloadFile method headers `GetDownloadFileUrlHeaders` - Headers of downloadFile method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `string`. Returns the requested file if the client has the follow redirects setting enabled to automatically follow HTTP `3xx` responses as redirects. If not, the request will return `302` instead. For details, see the [download file guide](g://downloads/file#download-url).If the file is not ready to be downloaded yet `Retry-After` header will be returned indicating the time in seconds after which the file will be available for the client to download. This response can occur when the file was uploaded immediately before the download request. ## Download file Returns the contents of a file in binary format. This operation is performed by calling function `DownloadFile`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-files-id-content/). ``` await client.Downloads.DownloadFileAsync(fileId: uploadedFile.Id); ``` ### Arguments fileId `string` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" queryParams `DownloadFileQueryParams` - Query parameters of downloadFile method headers `DownloadFileHeaders` - Headers of downloadFile method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `System.IO.Stream?`. Returns the requested file if the client has the follow redirects setting enabled to automatically follow HTTP `3xx` responses as redirects. If not, the request will return `302` instead. For details, see the [download file guide](g://downloads/file#download-url).If the file is not ready to be downloaded yet `Retry-After` header will be returned indicating the time in seconds after which the file will be available for the client to download. This response can occur when the file was uploaded immediately before the download request. --- ### IEmailAliasesManager **Type:** page | **Section:** Additional Resources IEmailAliasesManager List user's email aliases Create email alias Remove email alias List user's email aliases Retrieves all email aliases… # IEmailAliasesManager - [List user's email aliases](#list-users-email-aliases) - [Create email alias](#create-email-alias) - [Remove email alias](#remove-email-alias) ## List user's email aliases Retrieves all email aliases for a user. The collection does not include the primary login for the user. This operation is performed by calling function `GetUserEmailAliases`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-users-id-email-aliases/). ``` await client.EmailAliases.GetUserEmailAliasesAsync(userId: newUser.Id); ``` ### Arguments userId `string` - The ID of the user. Example: "12345" headers `GetUserEmailAliasesHeaders` - Headers of getUserEmailAliases method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `EmailAliases`. Returns a collection of email aliases. ## Create email alias Adds a new email alias to a user account.. This operation is performed by calling function `CreateUserEmailAlias`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-users-id-email-aliases/). ``` await client.EmailAliases.CreateUserEmailAliasAsync(userId: newUser.Id, requestBody: new CreateUserEmailAliasRequestBody(email: newAliasEmail)); ``` ### Arguments userId `string` - The ID of the user. Example: "12345" requestBody `CreateUserEmailAliasRequestBody` - Request body of createUserEmailAlias method headers `CreateUserEmailAliasHeaders` - Headers of createUserEmailAlias method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `EmailAlias`. Returns the newly created email alias object. ## Remove email alias Removes an email alias from a user. This operation is performed by calling function `DeleteUserEmailAliasById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-users-id-email-aliases-id/). ``` await client.EmailAliases.DeleteUserEmailAliasByIdAsync(userId: newUser.Id, emailAliasId: NullableUtils.Unwrap(newAlias.Id)); ``` ### Arguments userId `string` - The ID of the user. Example: "12345" emailAliasId `string` - The ID of the email alias. Example: "23432" headers `DeleteUserEmailAliasByIdHeaders` - Headers of deleteUserEmailAliasById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `null`. Removes the alias and returns an empty response. --- ### IEventsManager **Type:** page | **Section:** Additional Resources IEventsManager Get events long poll endpoint List user and enterprise events Get events long poll endpoint Returns a list of real-time… # IEventsManager - [Get events long poll endpoint](#get-events-long-poll-endpoint) - [List user and enterprise events](#list-user-and-enterprise-events) ## Get events long poll endpoint Returns a list of real-time servers that can be used for long-polling updates to the [event stream](#get-events). Long polling is the concept where a HTTP request is kept open until the server sends a response, then repeating the process over and over to receive updated responses. Long polling the event stream can only be used for user events, not for enterprise events. To use long polling, first use this endpoint to retrieve a list of long poll URLs. Next, make a long poll request to any of the provided URLs. When an event occurs in monitored account a response with the value `new_change` will be sent. The response contains no other details as it only serves as a prompt to take further action such as sending a request to the [events endpoint](#get-events) with the last known `stream_position`. After the server sends this response it closes the connection. You must now repeat the long poll process to begin listening for events again. If no events occur for a while and the connection times out you will receive a response with the value `reconnect`. When you receive this response you’ll make another call to this endpoint to restart the process. If you receive no events in `retry_timeout` seconds then you will need to make another request to the real-time server (one of the URLs in the response for this endpoint). This might be necessary due to network errors. Finally, if you receive a `max_retries` error when making a request to the real-time server, you should start over by making a call to this endpoint first. This operation is performed by calling function `GetEventsWithLongPolling`. See the endpoint docs at [API Reference](https://developer.box.com/reference/options-events/). ``` await client.Events.GetEventsWithLongPollingAsync(); ``` ### Arguments headers `GetEventsWithLongPollingHeaders` - Headers of getEventsWithLongPolling method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `RealtimeServers`. Returns a paginated array of servers that can be used instead of the regular endpoints for long-polling events. ## List user and enterprise events Returns up to a year of past events for a given user or for the entire enterprise. By default this returns events for the authenticated user. To retrieve events for the entire enterprise, set the `stream_type` to `admin_logs_streaming` for live monitoring of new events, or `admin_logs` for querying across historical events. The user making the API call will need to have admin privileges, and the application will need to have the scope `manage enterprise properties` checked. This operation is performed by calling function `GetEvents`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-events/). ``` await client.Events.GetEventsAsync(); ``` ### Arguments queryParams `GetEventsQueryParams` - Query parameters of getEvents method headers `GetEventsHeaders` - Headers of getEvents method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `Events`. Returns a list of event objects. Events objects are returned in pages, with each page (chunk) including a list of event objects. The response includes a `chunk_size` parameter indicating how many events were returned in this chunk, as well as the next `stream_position` that can be queried. --- ### IFileClassificationsManager **Type:** page | **Section:** Additional Resources IFileClassificationsManager Get classification on file Add classification to file Update classification on file Remove classification from… # IFileClassificationsManager - [Get classification on file](#get-classification-on-file) - [Add classification to file](#add-classification-to-file) - [Update classification on file](#update-classification-on-file) - [Remove classification from file](#remove-classification-from-file) ## Get classification on file Retrieves the classification metadata instance that has been applied to a file. This API can also be called by including the enterprise ID in the URL explicitly, for example `/files/:id//enterprise_12345/securityClassification-6VMVochwUWo`. This operation is performed by calling function `GetClassificationOnFile`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-files-id-metadata-enterprise-securityClassification-6VMVochwUWo/). ``` await client.FileClassifications.GetClassificationOnFileAsync(fileId: file.Id); ``` ### Arguments fileId `string` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" headers `GetClassificationOnFileHeaders` - Headers of getClassificationOnFile method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `Classification`. Returns an instance of the `securityClassification` metadata template, which contains a `Box__Security__Classification__Key` field that lists all the classifications available to this enterprise. ## Add classification to file Adds a classification to a file by specifying the label of the classification to add. This API can also be called by including the enterprise ID in the URL explicitly, for example `/files/:id//enterprise_12345/securityClassification-6VMVochwUWo`. This operation is performed by calling function `AddClassificationToFile`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-files-id-metadata-enterprise-securityClassification-6VMVochwUWo/). ``` await client.FileClassifications.AddClassificationToFileAsync(fileId: file.Id, requestBody: new AddClassificationToFileRequestBody() { BoxSecurityClassificationKey = classification.Key }); ``` ### Arguments fileId `string` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" requestBody `AddClassificationToFileRequestBody` - Request body of addClassificationToFile method headers `AddClassificationToFileHeaders` - Headers of addClassificationToFile method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `Classification`. Returns the classification template instance that was applied to the file. ## Update classification on file Updates a classification on a file. The classification can only be updated if a classification has already been applied to the file before. When editing classifications, only values are defined for the enterprise will be accepted. This operation is performed by calling function `UpdateClassificationOnFile`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-files-id-metadata-enterprise-securityClassification-6VMVochwUWo/). ``` await client.FileClassifications.UpdateClassificationOnFileAsync(fileId: file.Id, requestBody: Array.AsReadOnly(new [] {new UpdateClassificationOnFileRequestBody(value: secondClassification.Key)})); ``` ### Arguments fileId `string` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" requestBody `IReadOnlyList<UpdateClassificationOnFileRequestBody>` - Request body of updateClassificationOnFile method headers `UpdateClassificationOnFileHeaders` - Headers of updateClassificationOnFile method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `Classification`. Returns the updated classification metadata template instance. ## Remove classification from file Removes any classifications from a file. This API can also be called by including the enterprise ID in the URL explicitly, for example `/files/:id//enterprise_12345/securityClassification-6VMVochwUWo`. This operation is performed by calling function `DeleteClassificationFromFile`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-files-id-metadata-enterprise-securityClassification-6VMVochwUWo/). ``` await client.FileClassifications.DeleteClassificationFromFileAsync(fileId: file.Id); ``` ### Arguments fileId `string` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" headers `DeleteClassificationFromFileHeaders` - Headers of deleteClassificationFromFile method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `null`. Returns an empty response when the classification is successfully deleted. --- ### IFileMetadataManager **Type:** page | **Section:** Additional Resources IFileMetadataManager List metadata instances on file Get metadata instance on file Create metadata instance on file Update metadata instance… # IFileMetadataManager - [List metadata instances on file](#list-metadata-instances-on-file) - [Get metadata instance on file](#get-metadata-instance-on-file) - [Create metadata instance on file](#create-metadata-instance-on-file) - [Update metadata instance on file](#update-metadata-instance-on-file) - [Remove metadata instance from file](#remove-metadata-instance-from-file) ## List metadata instances on file Retrieves all metadata for a given file. This operation is performed by calling function `GetFileMetadata`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-files-id-metadata/). ``` await client.FileMetadata.GetFileMetadataAsync(fileId: file.Id); ``` ### Arguments fileId `string` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" headers `GetFileMetadataHeaders` - Headers of getFileMetadata method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `Metadatas`. Returns all the metadata associated with a file. This API does not support pagination and will therefore always return all of the metadata associated to the file. ## Get metadata instance on file Retrieves the instance of a metadata template that has been applied to a file. This operation is performed by calling function `GetFileMetadataById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-files-id-metadata-id-id/). ``` await client.FileMetadata.GetFileMetadataByIdAsync(fileId: file.Id, scope: GetFileMetadataByIdScope.Global, templateKey: "properties"); ``` ### Arguments fileId `string` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" scope `GetFileMetadataByIdScope` - The scope of the metadata template. Example: "global" templateKey `string` - The name of the metadata template. Example: "properties" headers `GetFileMetadataByIdHeaders` - Headers of getFileMetadataById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `MetadataFull`. An instance of the metadata template that includes additional "key:value" pairs defined by the user or an application. ## Create metadata instance on file Applies an instance of a metadata template to a file. In most cases only values that are present in the metadata template will be accepted, except for the `global.properties` template which accepts any key-value pair. This operation is performed by calling function `CreateFileMetadataById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-files-id-metadata-id-id/). ``` await client.FileMetadata.CreateFileMetadataByIdAsync(fileId: file.Id, scope: CreateFileMetadataByIdScope.Enterprise, templateKey: templateKey, requestBody: new Dictionary<string, object>() { { "name", "John" }, { "age", 23 }, { "birthDate", "2001-01-03T02:20:50.520Z" }, { "countryCode", "US" }, { "sports", Array.AsReadOnly(new [] {"basketball","tennis"}) } }); ``` ### Arguments fileId `string` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" scope `CreateFileMetadataByIdScope` - The scope of the metadata template. Example: "global" templateKey `string` - The name of the metadata template. Example: "properties" requestBody `Dictionary<string, object>` - Request body of createFileMetadataById method headers `CreateFileMetadataByIdHeaders` - Headers of createFileMetadataById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `MetadataFull`. Returns the instance of the template that was applied to the file, including the data that was applied to the template. ## Update metadata instance on file Updates a piece of metadata on a file. The metadata instance can only be updated if the template has already been applied to the file before. When editing metadata, only values that match the metadata template schema will be accepted. The update is applied atomically. If any errors occur during the application of the operations, the metadata instance will not be changed. This operation is performed by calling function `UpdateFileMetadataById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-files-id-metadata-id-id/). ``` await client.FileMetadata.UpdateFileMetadataByIdAsync(fileId: file.Id, scope: UpdateFileMetadataByIdScope.Enterprise, templateKey: templateKey, requestBody: Array.AsReadOnly(new [] {new UpdateFileMetadataByIdRequestBody() { Op = UpdateFileMetadataByIdRequestBodyOpField.Replace, Path = "/name", Value = "Jack" },new UpdateFileMetadataByIdRequestBody() { Op = UpdateFileMetadataByIdRequestBodyOpField.Replace, Path = "/age", Value = 24 },new UpdateFileMetadataByIdRequestBody() { Op = UpdateFileMetadataByIdRequestBodyOpField.Replace, Path = "/birthDate", Value = "2000-01-03T02:20:50.520Z" },new UpdateFileMetadataByIdRequestBody() { Op = UpdateFileMetadataByIdRequestBodyOpField.Replace, Path = "/countryCode", Value = "CA" },new UpdateFileMetadataByIdRequestBody() { Op = UpdateFileMetadataByIdRequestBodyOpField.Replace, Path = "/sports", Value = Array.AsReadOnly(new [] {"football"}) }})); ``` ### Arguments fileId `string` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" scope `UpdateFileMetadataByIdScope` - The scope of the metadata template. Example: "global" templateKey `string` - The name of the metadata template. Example: "properties" requestBody `IReadOnlyList<UpdateFileMetadataByIdRequestBody>` - Request body of updateFileMetadataById method headers `UpdateFileMetadataByIdHeaders` - Headers of updateFileMetadataById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `MetadataFull`. Returns the updated metadata template instance, with the custom template data included. ## Remove metadata instance from file Deletes a piece of file metadata. This operation is performed by calling function `DeleteFileMetadataById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-files-id-metadata-id-id/). ``` await client.FileMetadata.DeleteFileMetadataByIdAsync(fileId: file.Id, scope: DeleteFileMetadataByIdScope.Enterprise, templateKey: templateKey); ``` ### Arguments fileId `string` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" scope `DeleteFileMetadataByIdScope` - The scope of the metadata template. Example: "global" templateKey `string` - The name of the metadata template. Example: "properties" headers `DeleteFileMetadataByIdHeaders` - Headers of deleteFileMetadataById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `null`. Returns an empty response when the metadata is successfully deleted. --- ### IFileRequestsManager **Type:** page | **Section:** Additional Resources IFileRequestsManager Get file request Update file request Delete file request Copy file request Get file request Retrieves the information… # IFileRequestsManager - [Get file request](#get-file-request) - [Update file request](#update-file-request) - [Delete file request](#delete-file-request) - [Copy file request](#copy-file-request) ## Get file request Retrieves the information about a file request. This operation is performed by calling function `GetFileRequestById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-file-requests-id/). ``` await client.FileRequests.GetFileRequestByIdAsync(fileRequestId: fileRequestId); ``` ### Arguments fileRequestId `string` - The unique identifier that represent a file request. The ID for any file request can be determined by visiting a file request builder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/filerequest/123` the `file_request_id` is `123`. Example: "123" headers `GetFileRequestByIdHeaders` - Headers of getFileRequestById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `FileRequest`. Returns a file request object. ## Update file request Updates a file request. This can be used to activate or deactivate a file request. This operation is performed by calling function `UpdateFileRequestById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-file-requests-id/). ``` await client.FileRequests.UpdateFileRequestByIdAsync(fileRequestId: copiedFileRequest.Id, requestBody: new FileRequestUpdateRequest() { Title = "updated title", Description = "updated description" }); ``` ### Arguments fileRequestId `string` - The unique identifier that represent a file request. The ID for any file request can be determined by visiting a file request builder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/filerequest/123` the `file_request_id` is `123`. Example: "123" requestBody `FileRequestUpdateRequest` - Request body of updateFileRequestById method headers `UpdateFileRequestByIdHeaders` - Headers of updateFileRequestById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `FileRequest`. Returns the updated file request object. ## Delete file request Deletes a file request permanently. This operation is performed by calling function `DeleteFileRequestById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-file-requests-id/). ``` await client.FileRequests.DeleteFileRequestByIdAsync(fileRequestId: updatedFileRequest.Id); ``` ### Arguments fileRequestId `string` - The unique identifier that represent a file request. The ID for any file request can be determined by visiting a file request builder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/filerequest/123` the `file_request_id` is `123`. Example: "123" headers `DeleteFileRequestByIdHeaders` - Headers of deleteFileRequestById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `null`. Returns an empty response when the file request has been successfully deleted. ## Copy file request Copies an existing file request that is already present on one folder, and applies it to another folder. This operation is performed by calling function `CreateFileRequestCopy`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-file-requests-id-copy/). ``` await client.FileRequests.CreateFileRequestCopyAsync(fileRequestId: fileRequestId, requestBody: new FileRequestCopyRequest(folder: new FileRequestCopyRequestFolderField(id: fileRequest.Folder.Id) { Type = FileRequestCopyRequestFolderTypeField.Folder })); ``` ### Arguments fileRequestId `string` - The unique identifier that represent a file request. The ID for any file request can be determined by visiting a file request builder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/filerequest/123` the `file_request_id` is `123`. Example: "123" requestBody `FileRequestCopyRequest` - Request body of createFileRequestCopy method headers `CreateFileRequestCopyHeaders` - Headers of createFileRequestCopy method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `FileRequest`. Returns updated file request object. --- ### IFilesManager **Type:** page | **Section:** Additional Resources IFilesManager Get file information Update file Delete file Copy file Get file thumbnail URL Get file thumbnail Get file information… # IFilesManager - [Get file information](#get-file-information) - [Update file](#update-file) - [Delete file](#delete-file) - [Copy file](#copy-file) - [Get file thumbnail URL](#get-file-thumbnail-url) - [Get file thumbnail](#get-file-thumbnail) ## Get file information Retrieves the details about a file. This operation is performed by calling function `GetFileById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-files-id/). ``` await client.Files.GetFileByIdAsync(fileId: uploadedFile.Id, queryParams: new GetFileByIdQueryParams() { Fields = Array.AsReadOnly(new [] {"is_externally_owned","has_collaborations"}) }); ``` ### Arguments fileId `string` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" queryParams `GetFileByIdQueryParams` - Query parameters of getFileById method headers `GetFileByIdHeaders` - Headers of getFileById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `FileFull`. Returns a file object. Not all available fields are returned by default. Use the [fields](#param-fields) query parameter to explicitly request any specific fields. ## Update file Updates a file. This can be used to rename or move a file, create a shared link, or lock a file. This operation is performed by calling function `UpdateFileById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-files-id/). ``` await client.Files.UpdateFileByIdAsync(fileId: fileToUpdate.Id, requestBody: new UpdateFileByIdRequestBody() { Name = updatedName, Description = "Updated description" }); ``` ### Arguments fileId `string` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" requestBody `UpdateFileByIdRequestBody` - Request body of updateFileById method queryParams `UpdateFileByIdQueryParams` - Query parameters of updateFileById method headers `UpdateFileByIdHeaders` - Headers of updateFileById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `FileFull`. Returns a file object. Not all available fields are returned by default. Use the [fields](#param-fields) query parameter to explicitly request any specific fields. ## Delete file Deletes a file, either permanently or by moving it to the trash. The the enterprise settings determine whether the item will be permanently deleted from Box or moved to the trash. This operation is performed by calling function `DeleteFileById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-files-id/). ``` await client.Files.DeleteFileByIdAsync(fileId: thumbnailFile.Id); ``` ### Arguments fileId `string` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" headers `DeleteFileByIdHeaders` - Headers of deleteFileById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `null`. Returns an empty response when the file has been successfully deleted. ## Copy file Creates a copy of a file. This operation is performed by calling function `CopyFile`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-files-id-copy/). ``` await client.Files.CopyFileAsync(fileId: fileOrigin.Id, requestBody: new CopyFileRequestBody(parent: new CopyFileRequestBodyParentField(id: "0")) { Name = copiedFileName }); ``` ### Arguments fileId `string` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" requestBody `CopyFileRequestBody` - Request body of copyFile method queryParams `CopyFileQueryParams` - Query parameters of copyFile method headers `CopyFileHeaders` - Headers of copyFile method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `FileFull`. Returns a new file object representing the copied file. Not all available fields are returned by default. Use the [fields](#param-fields) query parameter to explicitly request any specific fields. ## Get file thumbnail URL Get the download URL without downloading the content. This operation is performed by calling function `GetFileThumbnailUrl`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-files-id-thumbnail-id/). ``` await client.Files.GetFileThumbnailUrlAsync(fileId: thumbnailFile.Id, extension: GetFileThumbnailUrlExtension.Png); ``` ### Arguments fileId `string` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" extension `GetFileThumbnailUrlExtension` - The file format for the thumbnail. Example: "png" queryParams `GetFileThumbnailUrlQueryParams` - Query parameters of getFileThumbnailById method headers `GetFileThumbnailUrlHeaders` - Headers of getFileThumbnailById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `string`. When a thumbnail can be created the thumbnail data will be returned in the body of the response.Sometimes generating a thumbnail can take a few seconds. In these situations the API returns a `Location`-header pointing to a placeholder graphic for this file type. The placeholder graphic can be used in a user interface until the thumbnail generation has completed. The `Retry-After`-header indicates when to the thumbnail will be ready. At that time, retry this endpoint to retrieve the thumbnail. ## Get file thumbnail Retrieves a thumbnail, or smaller image representation, of a file. Sizes of `32x32`,`64x64`, `128x128`, and `256x256` can be returned in the `.png` format and sizes of `32x32`, `160x160`, and `320x320` can be returned in the `.jpg` format. Thumbnails can be generated for the image and video file formats listed [found on our community site](https://community.box.com/t5/Migrating-and-Previewing-Content/File-Types-and-Fonts-Supported-in-Box-Content-Preview/ta-p/327). This operation is performed by calling function `GetFileThumbnailById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-files-id-thumbnail-id/). ``` await client.Files.GetFileThumbnailByIdAsync(fileId: thumbnailFile.Id, extension: GetFileThumbnailByIdExtension.Png); ``` ### Arguments fileId `string` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" extension `GetFileThumbnailByIdExtension` - The file format for the thumbnail. Example: "png" queryParams `GetFileThumbnailByIdQueryParams` - Query parameters of getFileThumbnailById method headers `GetFileThumbnailByIdHeaders` - Headers of getFileThumbnailById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `System.IO.Stream?`. When a thumbnail can be created the thumbnail data will be returned in the body of the response.Sometimes generating a thumbnail can take a few seconds. In these situations the API returns a `Location`-header pointing to a placeholder graphic for this file type. The placeholder graphic can be used in a user interface until the thumbnail generation has completed. The `Retry-After`-header indicates when to the thumbnail will be ready. At that time, retry this endpoint to retrieve the thumbnail. --- ### IFileVersionLegalHoldsManager **Type:** page | **Section:** Additional Resources IFileVersionLegalHoldsManager Get file version legal hold List file version legal holds Get file version legal hold Retrieves information… # IFileVersionLegalHoldsManager - [Get file version legal hold](#get-file-version-legal-hold) - [List file version legal holds](#list-file-version-legal-holds) ## Get file version legal hold Retrieves information about the legal hold policies assigned to a file version. This operation is performed by calling function `GetFileVersionLegalHoldById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-file-version-legal-holds-id/). ``` await client.FileVersionLegalHolds.GetFileVersionLegalHoldByIdAsync(fileVersionLegalHoldId: fileVersionLegalHoldId); ``` ### Arguments fileVersionLegalHoldId `string` - The ID of the file version legal hold. Example: "2348213" headers `GetFileVersionLegalHoldByIdHeaders` - Headers of getFileVersionLegalHoldById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `FileVersionLegalHold`. Returns the legal hold policy assignments for the file version. ## List file version legal holds Get a list of file versions on legal hold for a legal hold assignment. Due to ongoing re-architecture efforts this API might not return all file versions for this policy ID. Instead, this API will only return file versions held in the legacy architecture. Two new endpoints will available to request any file versions held in the new architecture. For file versions held in the new architecture, the `GET /legal_hold_policy_assignments/:id/file_versions_on_hold` API can be used to return all past file versions available for this policy assignment, and the `GET /legal_hold_policy_assignments/:id/files_on_hold` API can be used to return any current (latest) versions of a file under legal hold. The `GET /legal_hold_policy_assignments?policy_id={id}` API can be used to find a list of policy assignments for a given policy ID. Once the re-architecture is completed this API will be deprecated. This operation is performed by calling function `GetFileVersionLegalHolds`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-file-version-legal-holds/). ``` await client.FileVersionLegalHolds.GetFileVersionLegalHoldsAsync(queryParams: new GetFileVersionLegalHoldsQueryParams(policyId: policyId)); ``` ### Arguments queryParams `GetFileVersionLegalHoldsQueryParams` - Query parameters of getFileVersionLegalHolds method headers `GetFileVersionLegalHoldsHeaders` - Headers of getFileVersionLegalHolds method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `FileVersionLegalHolds`. Returns the list of file version legal holds for a specific legal hold policy. --- ### IFileVersionRetentionsManager **Type:** page | **Section:** Additional Resources IFileVersionRetentionsManager List file version retentions Get retention on file List file version retentions Retrieves all file version… # IFileVersionRetentionsManager - [List file version retentions](#list-file-version-retentions) - [Get retention on file](#get-retention-on-file) ## List file version retentions Retrieves all file version retentions for the given enterprise. **Note**: File retention API is now **deprecated**. To get information about files and file versions under retention, see [files under retention](e://get-retention-policy-assignments-id-files-under-retention) or [file versions under retention](e://get-retention-policy-assignments-id-file-versions-under-retention) endpoints. This operation is performed by calling function `GetFileVersionRetentions`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-file-version-retentions/). ``` await client.FileVersionRetentions.GetFileVersionRetentionsAsync(); ``` ### Arguments queryParams `GetFileVersionRetentionsQueryParams` - Query parameters of getFileVersionRetentions method headers `GetFileVersionRetentionsHeaders` - Headers of getFileVersionRetentions method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `FileVersionRetentions`. Returns a list of all file version retentions for the enterprise. ## Get retention on file Returns information about a file version retention. **Note**: File retention API is now **deprecated**. To get information about files and file versions under retention, see [files under retention](e://get-retention-policy-assignments-id-files-under-retention) or [file versions under retention](e://get-retention-policy-assignments-id-file-versions-under-retention) endpoints. This operation is performed by calling function `GetFileVersionRetentionById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-file-version-retentions-id/). ``` await client.FileVersionRetentions.GetFileVersionRetentionByIdAsync(fileVersionRetentionId: NullableUtils.Unwrap(fileVersionRetention.Id)); ``` ### Arguments fileVersionRetentionId `string` - The ID of the file version retention. Example: "3424234" headers `GetFileVersionRetentionByIdHeaders` - Headers of getFileVersionRetentionById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `FileVersionRetention`. Returns a file version retention object. --- ### IFileVersionsManager **Type:** page | **Section:** Additional Resources IFileVersionsManager List all file versions Get file version Remove file version Restore file version Promote file version List all file… # IFileVersionsManager - [List all file versions](#list-all-file-versions) - [Get file version](#get-file-version) - [Remove file version](#remove-file-version) - [Restore file version](#restore-file-version) - [Promote file version](#promote-file-version) ## List all file versions Retrieve a list of the past versions for a file. Versions are only tracked by Box users with premium accounts. To fetch the ID of the current version of a file, use the `GET /file/:id` API. This operation is performed by calling function `GetFileVersions`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-files-id-versions/). ``` await client.FileVersions.GetFileVersionsAsync(fileId: file.Id); ``` ### Arguments fileId `string` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" queryParams `GetFileVersionsQueryParams` - Query parameters of getFileVersions method headers `GetFileVersionsHeaders` - Headers of getFileVersions method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `FileVersions`. Returns an array of past versions for this file. ## Get file version Retrieve a specific version of a file. Versions are only tracked for Box users with premium accounts. This operation is performed by calling function `GetFileVersionById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-files-id-versions-id/). ``` await client.FileVersions.GetFileVersionByIdAsync(fileId: file.Id, fileVersionId: NullableUtils.Unwrap(fileVersions.Entries)[0].Id); ``` ### Arguments fileId `string` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" fileVersionId `string` - The ID of the file version. Example: "1234" queryParams `GetFileVersionByIdQueryParams` - Query parameters of getFileVersionById method headers `GetFileVersionByIdHeaders` - Headers of getFileVersionById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `FileVersionFull`. Returns a specific version of a file. Not all available fields are returned by default. Use the [fields](#param-fields) query parameter to explicitly request any specific fields. ## Remove file version Move a file version to the trash. Versions are only tracked for Box users with premium accounts. This operation is performed by calling function `DeleteFileVersionById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-files-id-versions-id/). ``` await client.FileVersions.DeleteFileVersionByIdAsync(fileId: file.Id, fileVersionId: fileVersion.Id); ``` ### Arguments fileId `string` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" fileVersionId `string` - The ID of the file version. Example: "1234" headers `DeleteFileVersionByIdHeaders` - Headers of deleteFileVersionById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `null`. Returns an empty response when the file has been successfully deleted. ## Restore file version Restores a specific version of a file after it was deleted. Don't use this endpoint to restore Box Notes, as it works with file formats such as PDF, DOC, PPTX or similar. This operation is performed by calling function `UpdateFileVersionById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-files-id-versions-id/). ``` await client.FileVersions.UpdateFileVersionByIdAsync(fileId: file.Id, fileVersionId: fileVersion.Id, requestBody: new UpdateFileVersionByIdRequestBody() { TrashedAt = null }); ``` ### Arguments fileId `string` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" fileVersionId `string` - The ID of the file version. Example: "1234" requestBody `UpdateFileVersionByIdRequestBody` - Request body of updateFileVersionById method headers `UpdateFileVersionByIdHeaders` - Headers of updateFileVersionById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `FileVersionFull`. Returns a restored file version object. ## Promote file version Promote a specific version of a file. If previous versions exist, this method can be used to promote one of the older versions to the top of the version history. This creates a new copy of the old version and puts it at the top of the versions history. The file will have the exact same contents as the older version, with the the same hash digest, `etag`, and name as the original. Other properties such as comments do not get updated to their former values. Don't use this endpoint to restore Box Notes, as it works with file formats such as PDF, DOC, PPTX or similar. This operation is performed by calling function `PromoteFileVersion`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-files-id-versions-current/). ``` await client.FileVersions.PromoteFileVersionAsync(fileId: file.Id, requestBody: new PromoteFileVersionRequestBody() { Id = NullableUtils.Unwrap(fileVersions.Entries)[0].Id, Type = PromoteFileVersionRequestBodyTypeField.FileVersion }); ``` ### Arguments fileId `string` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" requestBody `PromoteFileVersionRequestBody` - Request body of promoteFileVersion method queryParams `PromoteFileVersionQueryParams` - Query parameters of promoteFileVersion method headers `PromoteFileVersionHeaders` - Headers of promoteFileVersion method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `FileVersionFull`. Returns a newly created file version object. --- ### IFileWatermarksManager **Type:** page | **Section:** Additional Resources IFileWatermarksManager Get watermark on file Apply watermark to file Remove watermark from file Get watermark on file Retrieve the watermark… # IFileWatermarksManager - [Get watermark on file](#get-watermark-on-file) - [Apply watermark to file](#apply-watermark-to-file) - [Remove watermark from file](#remove-watermark-from-file) ## Get watermark on file Retrieve the watermark for a file. This operation is performed by calling function `GetFileWatermark`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-files-id-watermark/). ``` await client.FileWatermarks.GetFileWatermarkAsync(fileId: file.Id); ``` ### Arguments fileId `string` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" headers `GetFileWatermarkHeaders` - Headers of getFileWatermark method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `Watermark`. Returns an object containing information about the watermark associated for to this file. ## Apply watermark to file Applies or update a watermark on a file. This operation is performed by calling function `UpdateFileWatermark`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-files-id-watermark/). ``` await client.FileWatermarks.UpdateFileWatermarkAsync(fileId: file.Id, requestBody: new UpdateFileWatermarkRequestBody(watermark: new UpdateFileWatermarkRequestBodyWatermarkField(imprint: UpdateFileWatermarkRequestBodyWatermarkImprintField.Default))); ``` ### Arguments fileId `string` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" requestBody `UpdateFileWatermarkRequestBody` - Request body of updateFileWatermark method headers `UpdateFileWatermarkHeaders` - Headers of updateFileWatermark method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `Watermark`. Returns an updated watermark if a watermark already existed on this file.Returns a new watermark if no watermark existed on this file yet. ## Remove watermark from file Removes the watermark from a file. This operation is performed by calling function `DeleteFileWatermark`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-files-id-watermark/). ``` await client.FileWatermarks.DeleteFileWatermarkAsync(fileId: file.Id); ``` ### Arguments fileId `string` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" headers `DeleteFileWatermarkHeaders` - Headers of deleteFileWatermark method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `null`. Removes the watermark and returns an empty response. --- ### IFolderClassificationsManager **Type:** page | **Section:** Additional Resources IFolderClassificationsManager Get classification on folder Add classification to folder Update classification on folder Remove… # IFolderClassificationsManager - [Get classification on folder](#get-classification-on-folder) - [Add classification to folder](#add-classification-to-folder) - [Update classification on folder](#update-classification-on-folder) - [Remove classification from folder](#remove-classification-from-folder) ## Get classification on folder Retrieves the classification metadata instance that has been applied to a folder. This API can also be called by including the enterprise ID in the URL explicitly, for example `/folders/:id/enterprise_12345/securityClassification-6VMVochwUWo`. This operation is performed by calling function `GetClassificationOnFolder`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-folders-id-metadata-enterprise-securityClassification-6VMVochwUWo/). ``` await client.FolderClassifications.GetClassificationOnFolderAsync(folderId: folder.Id); ``` ### Arguments folderId `string` - The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. Example: "12345" headers `GetClassificationOnFolderHeaders` - Headers of getClassificationOnFolder method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `Classification`. Returns an instance of the `securityClassification` metadata template, which contains a `Box__Security__Classification__Key` field that lists all the classifications available to this enterprise. ## Add classification to folder Adds a classification to a folder by specifying the label of the classification to add. This API can also be called by including the enterprise ID in the URL explicitly, for example `/folders/:id/enterprise_12345/securityClassification-6VMVochwUWo`. This operation is performed by calling function `AddClassificationToFolder`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-folders-id-metadata-enterprise-securityClassification-6VMVochwUWo/). ``` await client.FolderClassifications.AddClassificationToFolderAsync(folderId: folder.Id, requestBody: new AddClassificationToFolderRequestBody() { BoxSecurityClassificationKey = classification.Key }); ``` ### Arguments folderId `string` - The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. Example: "12345" requestBody `AddClassificationToFolderRequestBody` - Request body of addClassificationToFolder method headers `AddClassificationToFolderHeaders` - Headers of addClassificationToFolder method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `Classification`. Returns the classification template instance that was applied to the folder. ## Update classification on folder Updates a classification on a folder. The classification can only be updated if a classification has already been applied to the folder before. When editing classifications, only values are defined for the enterprise will be accepted. This operation is performed by calling function `UpdateClassificationOnFolder`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-folders-id-metadata-enterprise-securityClassification-6VMVochwUWo/). ``` await client.FolderClassifications.UpdateClassificationOnFolderAsync(folderId: folder.Id, requestBody: Array.AsReadOnly(new [] {new UpdateClassificationOnFolderRequestBody(value: secondClassification.Key)})); ``` ### Arguments folderId `string` - The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. Example: "12345" requestBody `IReadOnlyList<UpdateClassificationOnFolderRequestBody>` - Request body of updateClassificationOnFolder method headers `UpdateClassificationOnFolderHeaders` - Headers of updateClassificationOnFolder method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `Classification`. Returns the updated classification metadata template instance. ## Remove classification from folder Removes any classifications from a folder. This API can also be called by including the enterprise ID in the URL explicitly, for example `/folders/:id/enterprise_12345/securityClassification-6VMVochwUWo`. This operation is performed by calling function `DeleteClassificationFromFolder`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-folders-id-metadata-enterprise-securityClassification-6VMVochwUWo/). ``` await client.FolderClassifications.DeleteClassificationFromFolderAsync(folderId: folder.Id); ``` ### Arguments folderId `string` - The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. Example: "12345" headers `DeleteClassificationFromFolderHeaders` - Headers of deleteClassificationFromFolder method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `null`. Returns an empty response when the classification is successfully deleted. --- ### IFolderLocksManager **Type:** page | **Section:** Additional Resources IFolderLocksManager List folder locks Create folder lock Delete folder lock List folder locks Retrieves folder lock details for a given… # IFolderLocksManager - [List folder locks](#list-folder-locks) - [Create folder lock](#create-folder-lock) - [Delete folder lock](#delete-folder-lock) ## List folder locks Retrieves folder lock details for a given folder. You must be authenticated as the owner or co-owner of the folder to use this endpoint. This operation is performed by calling function `GetFolderLocks`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-folder-locks/). ``` await client.FolderLocks.GetFolderLocksAsync(queryParams: new GetFolderLocksQueryParams(folderId: folder.Id)); ``` ### Arguments queryParams `GetFolderLocksQueryParams` - Query parameters of getFolderLocks method headers `GetFolderLocksHeaders` - Headers of getFolderLocks method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `FolderLocks`. Returns details for all folder locks applied to the folder, including the lock type and user that applied the lock. ## Create folder lock Creates a folder lock on a folder, preventing it from being moved and/or deleted. You must be authenticated as the owner or co-owner of the folder to use this endpoint. This operation is performed by calling function `CreateFolderLock`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-folder-locks/). ``` await client.FolderLocks.CreateFolderLockAsync(requestBody: new CreateFolderLockRequestBody(folder: new CreateFolderLockRequestBodyFolderField(id: folder.Id, type: "folder")) { LockedOperations = new CreateFolderLockRequestBodyLockedOperationsField(move: true, delete: true) }); ``` ### Arguments requestBody `CreateFolderLockRequestBody` - Request body of createFolderLock method headers `CreateFolderLockHeaders` - Headers of createFolderLock method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `FolderLock`. Returns the instance of the folder lock that was applied to the folder, including the user that applied the lock and the operations set. ## Delete folder lock Deletes a folder lock on a given folder. You must be authenticated as the owner or co-owner of the folder to use this endpoint. This operation is performed by calling function `DeleteFolderLockById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-folder-locks-id/). ``` await client.FolderLocks.DeleteFolderLockByIdAsync(folderLockId: NullableUtils.Unwrap(folderLock.Id)); ``` ### Arguments folderLockId `string` - The ID of the folder lock. Example: "12345" headers `DeleteFolderLockByIdHeaders` - Headers of deleteFolderLockById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `null`. Returns an empty response when the folder lock is successfully deleted. --- ### IFolderMetadataManager **Type:** page | **Section:** Additional Resources IFolderMetadataManager List metadata instances on folder Get metadata instance on folder Create metadata instance on folder Update metadata… # IFolderMetadataManager - [List metadata instances on folder](#list-metadata-instances-on-folder) - [Get metadata instance on folder](#get-metadata-instance-on-folder) - [Create metadata instance on folder](#create-metadata-instance-on-folder) - [Update metadata instance on folder](#update-metadata-instance-on-folder) - [Remove metadata instance from folder](#remove-metadata-instance-from-folder) ## List metadata instances on folder Retrieves all metadata for a given folder. This can not be used on the root folder with ID `0`. This operation is performed by calling function `GetFolderMetadata`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-folders-id-metadata/). ``` await client.FolderMetadata.GetFolderMetadataAsync(folderId: folder.Id); ``` ### Arguments folderId `string` - The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. Example: "12345" headers `GetFolderMetadataHeaders` - Headers of getFolderMetadata method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `Metadatas`. Returns all the metadata associated with a folder. This API does not support pagination and will therefore always return all of the metadata associated to the folder. ## Get metadata instance on folder Retrieves the instance of a metadata template that has been applied to a folder. This can not be used on the root folder with ID `0`. This operation is performed by calling function `GetFolderMetadataById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-folders-id-metadata-id-id/). ``` await client.FolderMetadata.GetFolderMetadataByIdAsync(folderId: folder.Id, scope: GetFolderMetadataByIdScope.Global, templateKey: "properties"); ``` ### Arguments folderId `string` - The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. Example: "12345" scope `GetFolderMetadataByIdScope` - The scope of the metadata template. Example: "global" templateKey `string` - The name of the metadata template. Example: "properties" headers `GetFolderMetadataByIdHeaders` - Headers of getFolderMetadataById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `MetadataFull`. An instance of the metadata template that includes additional "key:value" pairs defined by the user or an application. ## Create metadata instance on folder Applies an instance of a metadata template to a folder. In most cases only values that are present in the metadata template will be accepted, except for the `global.properties` template which accepts any key-value pair. To display the metadata template in the Box web app the enterprise needs to be configured to enable **Cascading Folder Level Metadata** for the user in the admin console. This operation is performed by calling function `CreateFolderMetadataById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-folders-id-metadata-id-id/). ``` await client.FolderMetadata.CreateFolderMetadataByIdAsync(folderId: folder.Id, scope: CreateFolderMetadataByIdScope.Enterprise, templateKey: templateKey, requestBody: new Dictionary<string, object>() { { "name", "John" }, { "age", 23 }, { "birthDate", "2001-01-03T02:20:50.520Z" }, { "countryCode", "US" }, { "sports", Array.AsReadOnly(new [] {"basketball","tennis"}) } }); ``` ### Arguments folderId `string` - The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. Example: "12345" scope `CreateFolderMetadataByIdScope` - The scope of the metadata template. Example: "global" templateKey `string` - The name of the metadata template. Example: "properties" requestBody `Dictionary<string, object>` - Request body of createFolderMetadataById method headers `CreateFolderMetadataByIdHeaders` - Headers of createFolderMetadataById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `MetadataFull`. Returns the instance of the template that was applied to the folder, including the data that was applied to the template. ## Update metadata instance on folder Updates a piece of metadata on a folder. The metadata instance can only be updated if the template has already been applied to the folder before. When editing metadata, only values that match the metadata template schema will be accepted. The update is applied atomically. If any errors occur during the application of the operations, the metadata instance will not be changed. This operation is performed by calling function `UpdateFolderMetadataById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-folders-id-metadata-id-id/). ``` await client.FolderMetadata.UpdateFolderMetadataByIdAsync(folderId: folder.Id, scope: UpdateFolderMetadataByIdScope.Enterprise, templateKey: templateKey, requestBody: Array.AsReadOnly(new [] {new UpdateFolderMetadataByIdRequestBody() { Op = UpdateFolderMetadataByIdRequestBodyOpField.Replace, Path = "/name", Value = "Jack" },new UpdateFolderMetadataByIdRequestBody() { Op = UpdateFolderMetadataByIdRequestBodyOpField.Replace, Path = "/age", Value = 24 },new UpdateFolderMetadataByIdRequestBody() { Op = UpdateFolderMetadataByIdRequestBodyOpField.Replace, Path = "/birthDate", Value = "2000-01-03T02:20:50.520Z" },new UpdateFolderMetadataByIdRequestBody() { Op = UpdateFolderMetadataByIdRequestBodyOpField.Replace, Path = "/countryCode", Value = "CA" },new UpdateFolderMetadataByIdRequestBody() { Op = UpdateFolderMetadataByIdRequestBodyOpField.Replace, Path = "/sports", Value = Array.AsReadOnly(new [] {"football"}) }})); ``` ### Arguments folderId `string` - The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. Example: "12345" scope `UpdateFolderMetadataByIdScope` - The scope of the metadata template. Example: "global" templateKey `string` - The name of the metadata template. Example: "properties" requestBody `IReadOnlyList<UpdateFolderMetadataByIdRequestBody>` - Request body of updateFolderMetadataById method headers `UpdateFolderMetadataByIdHeaders` - Headers of updateFolderMetadataById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `MetadataFull`. Returns the updated metadata template instance, with the custom template data included. ## Remove metadata instance from folder Deletes a piece of folder metadata. This operation is performed by calling function `DeleteFolderMetadataById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-folders-id-metadata-id-id/). ``` await client.FolderMetadata.DeleteFolderMetadataByIdAsync(folderId: folder.Id, scope: DeleteFolderMetadataByIdScope.Enterprise, templateKey: templateKey); ``` ### Arguments folderId `string` - The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. Example: "12345" scope `DeleteFolderMetadataByIdScope` - The scope of the metadata template. Example: "global" templateKey `string` - The name of the metadata template. Example: "properties" headers `DeleteFolderMetadataByIdHeaders` - Headers of deleteFolderMetadataById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `null`. Returns an empty response when the metadata is successfully deleted. --- ### IFoldersManager **Type:** page | **Section:** Additional Resources IFoldersManager Get folder information Update folder Delete folder List items in folder Create folder Copy folder Get folder information… # IFoldersManager - [Get folder information](#get-folder-information) - [Update folder](#update-folder) - [Delete folder](#delete-folder) - [List items in folder](#list-items-in-folder) - [Create folder](#create-folder) - [Copy folder](#copy-folder) ## Get folder information Retrieves details for a folder, including the first 100 entries in the folder. Passing `sort`, `direction`, `offset`, and `limit` parameters in query allows you to manage the list of returned [folder items](r://folder--full#param-item-collection). To fetch more items within the folder, use the [Get items in a folder](e://get-folders-id-items) endpoint. This operation is performed by calling function `GetFolderById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-folders-id/). ``` await client.Folders.GetFolderByIdAsync(folderId: "0"); ``` ### Arguments folderId `string` - The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. Example: "12345" queryParams `GetFolderByIdQueryParams` - Query parameters of getFolderById method headers `GetFolderByIdHeaders` - Headers of getFolderById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `FolderFull`. Returns a folder, including the first 100 entries in the folder. If you used query parameters like `sort`, `direction`, `offset`, or `limit` the *folder items list* will be affected accordingly. To fetch more items within the folder, use the [Get items in a folder](e://get-folders-id-items)) endpoint. Not all available fields are returned by default. Use the [fields](#param-fields) query parameter to explicitly request any specific fields. ## Update folder Updates a folder. This can be also be used to move the folder, create shared links, update collaborations, and more. This operation is performed by calling function `UpdateFolderById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-folders-id/). ``` await client.Folders.UpdateFolderByIdAsync(folderId: folderToUpdate.Id, requestBody: new UpdateFolderByIdRequestBody() { Name = updatedName, Description = "Updated description" }); ``` ### Arguments folderId `string` - The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. Example: "12345" requestBody `UpdateFolderByIdRequestBody` - Request body of updateFolderById method queryParams `UpdateFolderByIdQueryParams` - Query parameters of updateFolderById method headers `UpdateFolderByIdHeaders` - Headers of updateFolderById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `FolderFull`. Returns a folder object for the updated folder Not all available fields are returned by default. Use the [fields](#param-fields) query parameter to explicitly request any specific fields. If the user is moving folders with a large number of items in all of their descendants, the call will be run asynchronously. If the operation is not completed within 10 minutes, the user will receive a 200 OK response, and the operation will continue running. ## Delete folder Deletes a folder, either permanently or by moving it to the trash. This operation is performed by calling function `DeleteFolderById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-folders-id/). ``` await client.Folders.DeleteFolderByIdAsync(folderId: newFolder.Id); ``` ### Arguments folderId `string` - The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. Example: "12345" queryParams `DeleteFolderByIdQueryParams` - Query parameters of deleteFolderById method headers `DeleteFolderByIdHeaders` - Headers of deleteFolderById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `null`. Returns an empty response when the folder is successfully deleted or moved to the trash. ## List items in folder Retrieves a page of items in a folder. These items can be files, folders, and web links. To request more information about the folder itself, like its size, use the [Get a folder](#get-folders-id) endpoint instead. This operation is performed by calling function `GetFolderItems`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-folders-id-items/). ``` await client.Folders.GetFolderItemsAsync(folderId: folderOrigin.Id); ``` ### Arguments folderId `string` - The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. Example: "12345" queryParams `GetFolderItemsQueryParams` - Query parameters of getFolderItems method headers `GetFolderItemsHeaders` - Headers of getFolderItems method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `Items`. Returns a collection of files, folders, and web links contained in a folder. ## Create folder Creates a new empty folder within the specified parent folder. This operation is performed by calling function `CreateFolder`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-folders/). ``` await client.Folders.CreateFolderAsync(requestBody: new CreateFolderRequestBody(name: newFolderName, parent: new CreateFolderRequestBodyParentField(id: "0"))); ``` ### Arguments requestBody `CreateFolderRequestBody` - Request body of createFolder method queryParams `CreateFolderQueryParams` - Query parameters of createFolder method headers `CreateFolderHeaders` - Headers of createFolder method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `FolderFull`. Returns a folder object. Not all available fields are returned by default. Use the [fields](#param-fields) query parameter to explicitly request any specific fields. ## Copy folder Creates a copy of a folder within a destination folder. The original folder will not be changed. This operation is performed by calling function `CopyFolder`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-folders-id-copy/). ``` await client.Folders.CopyFolderAsync(folderId: folderOrigin.Id, requestBody: new CopyFolderRequestBody(parent: new CopyFolderRequestBodyParentField(id: "0")) { Name = copiedFolderName }); ``` ### Arguments folderId `string` - The unique identifier of the folder to copy. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder with the ID `0` can not be copied. Example: "0" requestBody `CopyFolderRequestBody` - Request body of copyFolder method queryParams `CopyFolderQueryParams` - Query parameters of copyFolder method headers `CopyFolderHeaders` - Headers of copyFolder method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `FolderFull`. Returns a new folder object representing the copied folder. Not all available fields are returned by default. Use the [fields](#param-fields) query parameter to explicitly request any specific fields. --- ### IFolderWatermarksManager **Type:** page | **Section:** Additional Resources IFolderWatermarksManager Get watermark for folder Apply watermark to folder Remove watermark from folder Get watermark for folder Retrieve… # IFolderWatermarksManager - [Get watermark for folder](#get-watermark-for-folder) - [Apply watermark to folder](#apply-watermark-to-folder) - [Remove watermark from folder](#remove-watermark-from-folder) ## Get watermark for folder Retrieve the watermark for a folder. This operation is performed by calling function `GetFolderWatermark`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-folders-id-watermark/). ``` await client.FolderWatermarks.GetFolderWatermarkAsync(folderId: folder.Id); ``` ### Arguments folderId `string` - The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. Example: "12345" headers `GetFolderWatermarkHeaders` - Headers of getFolderWatermark method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `Watermark`. Returns an object containing information about the watermark associated for to this folder. ## Apply watermark to folder Applies or update a watermark on a folder. This operation is performed by calling function `UpdateFolderWatermark`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-folders-id-watermark/). ``` await client.FolderWatermarks.UpdateFolderWatermarkAsync(folderId: folder.Id, requestBody: new UpdateFolderWatermarkRequestBody(watermark: new UpdateFolderWatermarkRequestBodyWatermarkField(imprint: UpdateFolderWatermarkRequestBodyWatermarkImprintField.Default))); ``` ### Arguments folderId `string` - The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. Example: "12345" requestBody `UpdateFolderWatermarkRequestBody` - Request body of updateFolderWatermark method headers `UpdateFolderWatermarkHeaders` - Headers of updateFolderWatermark method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `Watermark`. Returns an updated watermark if a watermark already existed on this folder.Returns a new watermark if no watermark existed on this folder yet. ## Remove watermark from folder Removes the watermark from a folder. This operation is performed by calling function `DeleteFolderWatermark`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-folders-id-watermark/). ``` await client.FolderWatermarks.DeleteFolderWatermarkAsync(folderId: folder.Id); ``` ### Arguments folderId `string` - The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. Example: "12345" headers `DeleteFolderWatermarkHeaders` - Headers of deleteFolderWatermark method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `null`. An empty response will be returned when the watermark was successfully deleted. --- ### IGroupsManager **Type:** page | **Section:** Additional Resources IGroupsManager List groups for enterprise Create group Get group Update group Remove group List groups for enterprise Retrieves all of the… # IGroupsManager - [List groups for enterprise](#list-groups-for-enterprise) - [Create group](#create-group) - [Get group](#get-group) - [Update group](#update-group) - [Remove group](#remove-group) ## List groups for enterprise Retrieves all of the groups for a given enterprise. The user must have admin permissions to inspect enterprise's groups. This operation is performed by calling function `GetGroups`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-groups/). ``` await client.Groups.GetGroupsAsync(); ``` ### Arguments queryParams `GetGroupsQueryParams` - Query parameters of getGroups method headers `GetGroupsHeaders` - Headers of getGroups method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `Groups`. Returns a collection of group objects. If there are no groups, an empty collection will be returned. ## Create group Creates a new group of users in an enterprise. Only users with admin permissions can create new groups. This operation is performed by calling function `CreateGroup`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-groups/). ``` await client.Groups.CreateGroupAsync(requestBody: new CreateGroupRequestBody(name: groupName) { Description = groupDescription }); ``` ### Arguments requestBody `CreateGroupRequestBody` - Request body of createGroup method queryParams `CreateGroupQueryParams` - Query parameters of createGroup method headers `CreateGroupHeaders` - Headers of createGroup method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `GroupFull`. Returns the new group object. ## Get group Retrieves information about a group. Only members of this group or users with admin-level permissions will be able to use this API. This operation is performed by calling function `GetGroupById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-groups-id/). ``` await client.Groups.GetGroupByIdAsync(groupId: group.Id, queryParams: new GetGroupByIdQueryParams() { Fields = Array.AsReadOnly(new [] {"id","name","description","group_type"}) }); ``` ### Arguments groupId `string` - The ID of the group. Example: "57645" queryParams `GetGroupByIdQueryParams` - Query parameters of getGroupById method headers `GetGroupByIdHeaders` - Headers of getGroupById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `GroupFull`. Returns the group object. ## Update group Updates a specific group. Only admins of this group or users with admin-level permissions will be able to use this API. This operation is performed by calling function `UpdateGroupById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-groups-id/). ``` await client.Groups.UpdateGroupByIdAsync(groupId: group.Id, requestBody: new UpdateGroupByIdRequestBody() { Name = updatedGroupName }); ``` ### Arguments groupId `string` - The ID of the group. Example: "57645" requestBody `UpdateGroupByIdRequestBody` - Request body of updateGroupById method queryParams `UpdateGroupByIdQueryParams` - Query parameters of updateGroupById method headers `UpdateGroupByIdHeaders` - Headers of updateGroupById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `GroupFull`. Returns the updated group object. ## Remove group Permanently deletes a group. Only users with admin-level permissions will be able to use this API. This operation is performed by calling function `DeleteGroupById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-groups-id/). ``` await client.Groups.DeleteGroupByIdAsync(groupId: group.Id); ``` ### Arguments groupId `string` - The ID of the group. Example: "57645" headers `DeleteGroupByIdHeaders` - Headers of deleteGroupById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `null`. A blank response is returned if the group was successfully deleted. --- ### IHubCollaborationsManager **Type:** page | **Section:** Additional Resources IHubCollaborationsManager Get hub collaborations Create hub collaboration Get hub collaboration by collaboration ID Update hub collaboration… # IHubCollaborationsManager - [Get hub collaborations](#get-hub-collaborations) - [Create hub collaboration](#create-hub-collaboration) - [Get hub collaboration by collaboration ID](#get-hub-collaboration-by-collaboration-id) - [Update hub collaboration](#update-hub-collaboration) - [Remove hub collaboration](#remove-hub-collaboration) ## Get hub collaborations Retrieves all collaborations for a hub. This operation is performed by calling function `GetHubCollaborationsV2025R0`. See the endpoint docs at [API Reference](https://developer.box.com/reference/v2025.0/get-hub-collaborations/). ``` await client.HubCollaborations.GetHubCollaborationsV2025R0Async(queryParams: new GetHubCollaborationsV2025R0QueryParams(hubId: hub.Id)); ``` ### Arguments queryParams `GetHubCollaborationsV2025R0QueryParams` - Query parameters of getHubCollaborationsV2025R0 method headers `GetHubCollaborationsV2025R0Headers` - Headers of getHubCollaborationsV2025R0 method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `HubCollaborationsV2025R0`. Retrieves the collaborations associated with the specified hub. ## Create hub collaboration Adds a collaboration for a single user or a single group to a hub. Collaborations can be created using email address, user IDs, or group IDs. This operation is performed by calling function `CreateHubCollaborationV2025R0`. See the endpoint docs at [API Reference](https://developer.box.com/reference/v2025.0/post-hub-collaborations/). ``` await client.HubCollaborations.CreateHubCollaborationV2025R0Async(requestBody: new HubCollaborationCreateRequestV2025R0(hub: new HubCollaborationCreateRequestV2025R0HubField(id: hub.Id), accessibleBy: new HubCollaborationCreateRequestV2025R0AccessibleByField(type: "user") { Id = user.Id }, role: "viewer")); ``` ### Arguments requestBody `HubCollaborationCreateRequestV2025R0` - Request body of createHubCollaborationV2025R0 method headers `CreateHubCollaborationV2025R0Headers` - Headers of createHubCollaborationV2025R0 method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `HubCollaborationV2025R0`. Returns a new hub collaboration object. ## Get hub collaboration by collaboration ID Retrieves details for a hub collaboration by collaboration ID. This operation is performed by calling function `GetHubCollaborationByIdV2025R0`. See the endpoint docs at [API Reference](https://developer.box.com/reference/v2025.0/get-hub-collaborations-id/). ``` await client.HubCollaborations.GetHubCollaborationByIdV2025R0Async(hubCollaborationId: createdCollaboration.Id); ``` ### Arguments hubCollaborationId `string` - The ID of the hub collaboration. Example: "1234" headers `GetHubCollaborationByIdV2025R0Headers` - Headers of getHubCollaborationByIdV2025R0 method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `HubCollaborationV2025R0`. Returns a hub collaboration object. ## Update hub collaboration Updates a hub collaboration. Can be used to change the hub role. This operation is performed by calling function `UpdateHubCollaborationByIdV2025R0`. See the endpoint docs at [API Reference](https://developer.box.com/reference/v2025.0/put-hub-collaborations-id/). ``` await client.HubCollaborations.UpdateHubCollaborationByIdV2025R0Async(hubCollaborationId: createdCollaboration.Id, requestBody: new HubCollaborationUpdateRequestV2025R0() { Role = "editor" }); ``` ### Arguments hubCollaborationId `string` - The ID of the hub collaboration. Example: "1234" requestBody `HubCollaborationUpdateRequestV2025R0` - Request body of updateHubCollaborationByIdV2025R0 method headers `UpdateHubCollaborationByIdV2025R0Headers` - Headers of updateHubCollaborationByIdV2025R0 method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `HubCollaborationV2025R0`. Returns an updated hub collaboration object. ## Remove hub collaboration Deletes a single hub collaboration. This operation is performed by calling function `DeleteHubCollaborationByIdV2025R0`. See the endpoint docs at [API Reference](https://developer.box.com/reference/v2025.0/delete-hub-collaborations-id/). ``` await client.HubCollaborations.DeleteHubCollaborationByIdV2025R0Async(hubCollaborationId: createdCollaboration.Id); ``` ### Arguments hubCollaborationId `string` - The ID of the hub collaboration. Example: "1234" headers `DeleteHubCollaborationByIdV2025R0Headers` - Headers of deleteHubCollaborationByIdV2025R0 method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `null`. A blank response is returned if the hub collaboration was successfully deleted. --- ### IHubItemsManager **Type:** page | **Section:** Additional Resources IHubItemsManager Get hub items Manage hub items Get hub items Retrieves all items associated with a Hub. This operation is performed by… # IHubItemsManager - [Get hub items](#get-hub-items) - [Manage hub items](#manage-hub-items) ## Get hub items Retrieves all items associated with a Hub. This operation is performed by calling function `GetHubItemsV2025R0`. See the endpoint docs at [API Reference](https://developer.box.com/reference/v2025.0/get-hub-items/). ``` await client.HubItems.GetHubItemsV2025R0Async(queryParams: new GetHubItemsV2025R0QueryParams(hubId: createdHub.Id)); ``` ### Arguments queryParams `GetHubItemsV2025R0QueryParams` - Query parameters of getHubItemsV2025R0 method headers `GetHubItemsV2025R0Headers` - Headers of getHubItemsV2025R0 method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `HubItemsV2025R0`. Retrieves the items associated with the specified Hub. ## Manage hub items Adds and/or removes Hub items from a Hub. This operation is performed by calling function `ManageHubItemsV2025R0`. See the endpoint docs at [API Reference](https://developer.box.com/reference/v2025.0/post-hubs-id-manage-items/). ``` await client.HubItems.ManageHubItemsV2025R0Async(hubId: createdHub.Id, requestBody: new HubItemsManageRequestV2025R0() { Operations = Array.AsReadOnly(new [] {new HubItemOperationV2025R0(action: HubItemOperationV2025R0ActionField.Add, item: new FolderReferenceV2025R0(id: folder.Id))}) }); ``` ### Arguments hubId `string` - The unique identifier that represent a hub. The ID for any hub can be determined by visiting this hub in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/hubs/123` the `hub_id` is `123`. Example: "12345" requestBody `HubItemsManageRequestV2025R0` - Request body of manageHubItemsV2025R0 method headers `ManageHubItemsV2025R0Headers` - Headers of manageHubItemsV2025R0 method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `HubItemsManageResponseV2025R0`. --- ### IHubsManager **Type:** page | **Section:** Additional Resources IHubsManager List all hubs Create hub List all hubs for requesting enterprise Get hub information by ID Update hub information by ID Delete… # IHubsManager - [List all hubs](#list-all-hubs) - [Create hub](#create-hub) - [List all hubs for requesting enterprise](#list-all-hubs-for-requesting-enterprise) - [Get hub information by ID](#get-hub-information-by-id) - [Update hub information by ID](#update-hub-information-by-id) - [Delete hub](#delete-hub) - [Copy hub](#copy-hub) ## List all hubs Retrieves all hubs for requesting user. This operation is performed by calling function `GetHubsV2025R0`. See the endpoint docs at [API Reference](https://developer.box.com/reference/v2025.0/get-hubs/). ``` await client.Hubs.GetHubsV2025R0Async(queryParams: new GetHubsV2025R0QueryParams() { Scope = "all", Sort = "name", Direction = GetHubsV2025R0QueryParamsDirectionField.Asc }); ``` ### Arguments queryParams `GetHubsV2025R0QueryParams` - Query parameters of getHubsV2025R0 method headers `GetHubsV2025R0Headers` - Headers of getHubsV2025R0 method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `HubsV2025R0`. Returns all hubs for the given user or enterprise. ## Create hub Creates a new Hub. This operation is performed by calling function `CreateHubV2025R0`. See the endpoint docs at [API Reference](https://developer.box.com/reference/v2025.0/post-hubs/). ``` await client.Hubs.CreateHubV2025R0Async(requestBody: new HubCreateRequestV2025R0(title: hubTitle) { Description = hubDescription }); ``` ### Arguments requestBody `HubCreateRequestV2025R0` - Request body of createHubV2025R0 method headers `CreateHubV2025R0Headers` - Headers of createHubV2025R0 method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `HubV2025R0`. Returns a new Hub object. ## List all hubs for requesting enterprise Retrieves all hubs for a given enterprise. Admins or Hub Co-admins of an enterprise with GCM scope can make this call. This operation is performed by calling function `GetEnterpriseHubsV2025R0`. See the endpoint docs at [API Reference](https://developer.box.com/reference/v2025.0/get-enterprise-hubs/). ``` await client.Hubs.GetEnterpriseHubsV2025R0Async(queryParams: new GetEnterpriseHubsV2025R0QueryParams() { Sort = "name", Direction = GetEnterpriseHubsV2025R0QueryParamsDirectionField.Asc }); ``` ### Arguments queryParams `GetEnterpriseHubsV2025R0QueryParams` - Query parameters of getEnterpriseHubsV2025R0 method headers `GetEnterpriseHubsV2025R0Headers` - Headers of getEnterpriseHubsV2025R0 method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `HubsV2025R0`. Returns all hubs for the given user or enterprise. ## Get hub information by ID Retrieves details for a hub by its ID. This operation is performed by calling function `GetHubByIdV2025R0`. See the endpoint docs at [API Reference](https://developer.box.com/reference/v2025.0/get-hubs-id/). ``` await client.Hubs.GetHubByIdV2025R0Async(hubId: hubId); ``` ### Arguments hubId `string` - The unique identifier that represent a hub. The ID for any hub can be determined by visiting this hub in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/hubs/123` the `hub_id` is `123`. Example: "12345" headers `GetHubByIdV2025R0Headers` - Headers of getHubByIdV2025R0 method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `HubV2025R0`. Returns a hub object. ## Update hub information by ID Updates a Hub. Can be used to change title, description, or Hub settings. This operation is performed by calling function `UpdateHubByIdV2025R0`. See the endpoint docs at [API Reference](https://developer.box.com/reference/v2025.0/put-hubs-id/). ``` await client.Hubs.UpdateHubByIdV2025R0Async(hubId: hubId, requestBody: new HubUpdateRequestV2025R0() { Title = newHubTitle, Description = newHubDescription }); ``` ### Arguments hubId `string` - The unique identifier that represent a hub. The ID for any hub can be determined by visiting this hub in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/hubs/123` the `hub_id` is `123`. Example: "12345" requestBody `HubUpdateRequestV2025R0` - Request body of updateHubByIdV2025R0 method headers `UpdateHubByIdV2025R0Headers` - Headers of updateHubByIdV2025R0 method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `HubV2025R0`. Returns a Hub object. ## Delete hub Deletes a single hub. This operation is performed by calling function `DeleteHubByIdV2025R0`. See the endpoint docs at [API Reference](https://developer.box.com/reference/v2025.0/delete-hubs-id/). ``` await client.Hubs.DeleteHubByIdV2025R0Async(hubId: hubId); ``` ### Arguments hubId `string` - The unique identifier that represent a hub. The ID for any hub can be determined by visiting this hub in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/hubs/123` the `hub_id` is `123`. Example: "12345" headers `DeleteHubByIdV2025R0Headers` - Headers of deleteHubByIdV2025R0 method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `null`. A blank response is returned if the hub was successfully deleted. ## Copy hub Creates a copy of a Hub. The original Hub will not be modified. This operation is performed by calling function `CopyHubV2025R0`. See the endpoint docs at [API Reference](https://developer.box.com/reference/v2025.0/post-hubs-id-copy/). ``` await client.Hubs.CopyHubV2025R0Async(hubId: createdHub.Id, requestBody: new HubCopyRequestV2025R0() { Title = copiedHubTitle, Description = copiedHubDescription }); ``` ### Arguments hubId `string` - The unique identifier that represent a hub. The ID for any hub can be determined by visiting this hub in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/hubs/123` the `hub_id` is `123`. Example: "12345" requestBody `HubCopyRequestV2025R0` - Request body of copyHubV2025R0 method headers `CopyHubV2025R0Headers` - Headers of copyHubV2025R0 method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `HubV2025R0`. Returns a new Hub object. --- ### IIntegrationMappingsManager **Type:** page | **Section:** Additional Resources IIntegrationMappingsManager List Slack integration mappings Create Slack integration mapping Update Slack integration mapping Delete Slack… # IIntegrationMappingsManager - [List Slack integration mappings](#list-slack-integration-mappings) - [Create Slack integration mapping](#create-slack-integration-mapping) - [Update Slack integration mapping](#update-slack-integration-mapping) - [Delete Slack integration mapping](#delete-slack-integration-mapping) - [List Teams integration mappings](#list-teams-integration-mappings) - [Create Teams integration mapping](#create-teams-integration-mapping) - [Update Teams integration mapping](#update-teams-integration-mapping) - [Delete Teams integration mapping](#delete-teams-integration-mapping) ## List Slack integration mappings Lists [Slack integration mappings](https://support.box.com/hc/en-us/articles/4415585987859-Box-as-the-Content-Layer-for-Slack) in a users' enterprise. You need Admin or Co-Admin role to use this endpoint. This operation is performed by calling function `GetSlackIntegrationMapping`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-integration-mappings-slack/). ``` await userClient.IntegrationMappings.GetSlackIntegrationMappingAsync(); ``` ### Arguments queryParams `GetSlackIntegrationMappingQueryParams` - Query parameters of getSlackIntegrationMapping method headers `GetSlackIntegrationMappingHeaders` - Headers of getSlackIntegrationMapping method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `IntegrationMappings`. Returns a collection of integration mappings. ## Create Slack integration mapping Creates a [Slack integration mapping](https://support.box.com/hc/en-us/articles/4415585987859-Box-as-the-Content-Layer-for-Slack) by mapping a Slack channel to a Box item. You need Admin or Co-Admin role to use this endpoint. This operation is performed by calling function `CreateSlackIntegrationMapping`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-integration-mappings-slack/). ``` await userClient.IntegrationMappings.CreateSlackIntegrationMappingAsync(requestBody: new IntegrationMappingSlackCreateRequest(partnerItem: new IntegrationMappingPartnerItemSlack(id: slackPartnerItemId) { SlackOrgId = slackOrgId }, boxItem: new IntegrationMappingBoxItemSlack(id: folder.Id))); ``` ### Arguments requestBody `IntegrationMappingSlackCreateRequest` - Request body of createSlackIntegrationMapping method headers `CreateSlackIntegrationMappingHeaders` - Headers of createSlackIntegrationMapping method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `IntegrationMapping`. Returns the created integration mapping. ## Update Slack integration mapping Updates a [Slack integration mapping](https://support.box.com/hc/en-us/articles/4415585987859-Box-as-the-Content-Layer-for-Slack). Supports updating the Box folder ID and options. You need Admin or Co-Admin role to use this endpoint. This operation is performed by calling function `UpdateSlackIntegrationMappingById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-integration-mappings-slack-id/). ``` await userClient.IntegrationMappings.UpdateSlackIntegrationMappingByIdAsync(integrationMappingId: slackIntegrationMapping.Id, requestBody: new UpdateSlackIntegrationMappingByIdRequestBody() { BoxItem = new IntegrationMappingBoxItemSlack(id: folder.Id) }); ``` ### Arguments integrationMappingId `string` - An ID of an integration mapping. Example: "11235432" requestBody `UpdateSlackIntegrationMappingByIdRequestBody` - Request body of updateSlackIntegrationMappingById method headers `UpdateSlackIntegrationMappingByIdHeaders` - Headers of updateSlackIntegrationMappingById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `IntegrationMapping`. Returns the updated integration mapping object. ## Delete Slack integration mapping Deletes a [Slack integration mapping](https://support.box.com/hc/en-us/articles/4415585987859-Box-as-the-Content-Layer-for-Slack). You need Admin or Co-Admin role to use this endpoint. This operation is performed by calling function `DeleteSlackIntegrationMappingById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-integration-mappings-slack-id/). ``` await userClient.IntegrationMappings.DeleteSlackIntegrationMappingByIdAsync(integrationMappingId: slackIntegrationMapping.Id); ``` ### Arguments integrationMappingId `string` - An ID of an integration mapping. Example: "11235432" headers `DeleteSlackIntegrationMappingByIdHeaders` - Headers of deleteSlackIntegrationMappingById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `null`. Empty body in response. ## List Teams integration mappings Lists [Teams integration mappings](https://support.box.com/hc/en-us/articles/360044681474-Using-Box-for-Teams) in a users' enterprise. You need Admin or Co-Admin role to use this endpoint. This operation is performed by calling function `GetTeamsIntegrationMapping`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-integration-mappings-teams/). ``` await userClient.IntegrationMappings.GetTeamsIntegrationMappingAsync(); ``` ### Arguments queryParams `GetTeamsIntegrationMappingQueryParams` - Query parameters of getTeamsIntegrationMapping method headers `GetTeamsIntegrationMappingHeaders` - Headers of getTeamsIntegrationMapping method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `IntegrationMappingsTeams`. Returns a collection of integration mappings. ## Create Teams integration mapping Creates a [Teams integration mapping](https://support.box.com/hc/en-us/articles/360044681474-Using-Box-for-Teams) by mapping a Teams channel to a Box item. You need Admin or Co-Admin role to use this endpoint. This operation is performed by calling function `CreateTeamsIntegrationMapping`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-integration-mappings-teams/). ``` await userClient.IntegrationMappings.CreateTeamsIntegrationMappingAsync(requestBody: new IntegrationMappingTeamsCreateRequest(partnerItem: new IntegrationMappingPartnerItemTeamsCreateRequest(type: IntegrationMappingPartnerItemTeamsCreateRequestTypeField.Channel, id: partnerItemId, tenantId: tenantId, teamId: teamId), boxItem: new FolderReference(id: folder.Id))); ``` ### Arguments requestBody `IntegrationMappingTeamsCreateRequest` - Request body of createTeamsIntegrationMapping method headers `CreateTeamsIntegrationMappingHeaders` - Headers of createTeamsIntegrationMapping method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `IntegrationMappingTeams`. Returns the created integration mapping. ## Update Teams integration mapping Updates a [Teams integration mapping](https://support.box.com/hc/en-us/articles/360044681474-Using-Box-for-Teams). Supports updating the Box folder ID and options. You need Admin or Co-Admin role to use this endpoint. This operation is performed by calling function `UpdateTeamsIntegrationMappingById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-integration-mappings-teams-id/). ``` await userClient.IntegrationMappings.UpdateTeamsIntegrationMappingByIdAsync(integrationMappingId: integrationMappingId, requestBody: new UpdateTeamsIntegrationMappingByIdRequestBody() { BoxItem = new FolderReference(id: "1234567") }); ``` ### Arguments integrationMappingId `string` - An ID of an integration mapping. Example: "11235432" requestBody `UpdateTeamsIntegrationMappingByIdRequestBody` - Request body of updateTeamsIntegrationMappingById method headers `UpdateTeamsIntegrationMappingByIdHeaders` - Headers of updateTeamsIntegrationMappingById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `IntegrationMappingTeams`. Returns the updated integration mapping object. ## Delete Teams integration mapping Deletes a [Teams integration mapping](https://support.box.com/hc/en-us/articles/360044681474-Using-Box-for-Teams). You need Admin or Co-Admin role to use this endpoint. This operation is performed by calling function `DeleteTeamsIntegrationMappingById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-integration-mappings-teams-id/). ``` await userClient.IntegrationMappings.DeleteTeamsIntegrationMappingByIdAsync(integrationMappingId: integrationMappingId); ``` ### Arguments integrationMappingId `string` - An ID of an integration mapping. Example: "11235432" headers `DeleteTeamsIntegrationMappingByIdHeaders` - Headers of deleteTeamsIntegrationMappingById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `null`. Empty body in response. --- ### IInvitesManager **Type:** page | **Section:** Additional Resources IInvitesManager Create user invite Get user invite status Create user invite Invites an existing external user to join an enterprise. The… # IInvitesManager - [Create user invite](#create-user-invite) - [Get user invite status](#get-user-invite-status) ## Create user invite Invites an existing external user to join an enterprise. The existing user can not be part of another enterprise and must already have a Box account. Once invited, the user will receive an email and are prompted to accept the invitation within the Box web application. This method requires the "Manage An Enterprise" scope enabled for the application, which can be enabled within the developer console. This operation is performed by calling function `CreateInvite`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-invites/). ``` await client.Invites.CreateInviteAsync(requestBody: new CreateInviteRequestBody(enterprise: new CreateInviteRequestBodyEnterpriseField(id: NullableUtils.Unwrap(NullableUtils.Unwrap(currentUser.Enterprise).Id)), actionableBy: new CreateInviteRequestBodyActionableByField() { Login = email })); ``` ### Arguments requestBody `CreateInviteRequestBody` - Request body of createInvite method queryParams `CreateInviteQueryParams` - Query parameters of createInvite method headers `CreateInviteHeaders` - Headers of createInvite method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `Invite`. Returns a new invite object. ## Get user invite status Returns the status of a user invite. This operation is performed by calling function `GetInviteById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-invites-id/). ``` await client.Invites.GetInviteByIdAsync(inviteId: invitation.Id); ``` ### Arguments inviteId `string` - The ID of an invite. Example: "213723" queryParams `GetInviteByIdQueryParams` - Query parameters of getInviteById method headers `GetInviteByIdHeaders` - Headers of getInviteById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `Invite`. Returns an invite object. --- ### ILegalHoldPoliciesManager **Type:** page | **Section:** Additional Resources ILegalHoldPoliciesManager List all legal hold policies Create legal hold policy Get legal hold policy Update legal hold policy Remove legal… # ILegalHoldPoliciesManager - [List all legal hold policies](#list-all-legal-hold-policies) - [Create legal hold policy](#create-legal-hold-policy) - [Get legal hold policy](#get-legal-hold-policy) - [Update legal hold policy](#update-legal-hold-policy) - [Remove legal hold policy](#remove-legal-hold-policy) ## List all legal hold policies Retrieves a list of legal hold policies that belong to an enterprise. This operation is performed by calling function `GetLegalHoldPolicies`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-legal-hold-policies/). ``` await client.LegalHoldPolicies.GetLegalHoldPoliciesAsync(); ``` ### Arguments queryParams `GetLegalHoldPoliciesQueryParams` - Query parameters of getLegalHoldPolicies method headers `GetLegalHoldPoliciesHeaders` - Headers of getLegalHoldPolicies method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `LegalHoldPolicies`. Returns a list of legal hold policies. ## Create legal hold policy Create a new legal hold policy. This operation is performed by calling function `CreateLegalHoldPolicy`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-legal-hold-policies/). ``` await client.LegalHoldPolicies.CreateLegalHoldPolicyAsync(requestBody: new CreateLegalHoldPolicyRequestBody(policyName: legalHoldPolicyName) { Description = legalHoldDescription, IsOngoing = false, FilterStartedAt = filterStartedAt, FilterEndedAt = filterEndedAt }); ``` ### Arguments requestBody `CreateLegalHoldPolicyRequestBody` - Request body of createLegalHoldPolicy method headers `CreateLegalHoldPolicyHeaders` - Headers of createLegalHoldPolicy method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `LegalHoldPolicy`. Returns a new legal hold policy object. ## Get legal hold policy Retrieve a legal hold policy. This operation is performed by calling function `GetLegalHoldPolicyById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-legal-hold-policies-id/). ``` await client.LegalHoldPolicies.GetLegalHoldPolicyByIdAsync(legalHoldPolicyId: legalHoldPolicyId); ``` ### Arguments legalHoldPolicyId `string` - The ID of the legal hold policy. Example: "324432" headers `GetLegalHoldPolicyByIdHeaders` - Headers of getLegalHoldPolicyById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `LegalHoldPolicy`. Returns a legal hold policy object. ## Update legal hold policy Update legal hold policy. This operation is performed by calling function `UpdateLegalHoldPolicyById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-legal-hold-policies-id/). ``` await client.LegalHoldPolicies.UpdateLegalHoldPolicyByIdAsync(legalHoldPolicyId: legalHoldPolicyId, requestBody: new UpdateLegalHoldPolicyByIdRequestBody() { PolicyName = updatedLegalHoldPolicyName }); ``` ### Arguments legalHoldPolicyId `string` - The ID of the legal hold policy. Example: "324432" requestBody `UpdateLegalHoldPolicyByIdRequestBody` - Request body of updateLegalHoldPolicyById method headers `UpdateLegalHoldPolicyByIdHeaders` - Headers of updateLegalHoldPolicyById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `LegalHoldPolicy`. Returns a new legal hold policy object. ## Remove legal hold policy Delete an existing legal hold policy. This is an asynchronous process. The policy will not be fully deleted yet when the response returns. This operation is performed by calling function `DeleteLegalHoldPolicyById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-legal-hold-policies-id/). ``` await client.LegalHoldPolicies.DeleteLegalHoldPolicyByIdAsync(legalHoldPolicyId: legalHoldPolicy.Id); ``` ### Arguments legalHoldPolicyId `string` - The ID of the legal hold policy. Example: "324432" headers `DeleteLegalHoldPolicyByIdHeaders` - Headers of deleteLegalHoldPolicyById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `null`. A blank response is returned if the policy was successfully deleted. --- ### ILegalHoldPolicyAssignmentsManager **Type:** page | **Section:** Additional Resources ILegalHoldPolicyAssignmentsManager List legal hold policy assignments Assign legal hold policy Get legal hold policy assignment Unassign… # ILegalHoldPolicyAssignmentsManager - [List legal hold policy assignments](#list-legal-hold-policy-assignments) - [Assign legal hold policy](#assign-legal-hold-policy) - [Get legal hold policy assignment](#get-legal-hold-policy-assignment) - [Unassign legal hold policy](#unassign-legal-hold-policy) - [List files with current file versions for legal hold policy assignment](#list-files-with-current-file-versions-for-legal-hold-policy-assignment) ## List legal hold policy assignments Retrieves a list of items a legal hold policy has been assigned to. This operation is performed by calling function `GetLegalHoldPolicyAssignments`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-legal-hold-policy-assignments/). ``` await client.LegalHoldPolicyAssignments.GetLegalHoldPolicyAssignmentsAsync(queryParams: new GetLegalHoldPolicyAssignmentsQueryParams(policyId: legalHoldPolicyId)); ``` ### Arguments queryParams `GetLegalHoldPolicyAssignmentsQueryParams` - Query parameters of getLegalHoldPolicyAssignments method headers `GetLegalHoldPolicyAssignmentsHeaders` - Headers of getLegalHoldPolicyAssignments method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `LegalHoldPolicyAssignments`. Returns a list of legal hold policy assignments. ## Assign legal hold policy Assign a legal hold to a file, file version, folder, or user. This operation is performed by calling function `CreateLegalHoldPolicyAssignment`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-legal-hold-policy-assignments/). ``` await client.LegalHoldPolicyAssignments.CreateLegalHoldPolicyAssignmentAsync(requestBody: new CreateLegalHoldPolicyAssignmentRequestBody(policyId: legalHoldPolicyId, assignTo: new CreateLegalHoldPolicyAssignmentRequestBodyAssignToField(type: CreateLegalHoldPolicyAssignmentRequestBodyAssignToTypeField.File, id: fileId))); ``` ### Arguments requestBody `CreateLegalHoldPolicyAssignmentRequestBody` - Request body of createLegalHoldPolicyAssignment method headers `CreateLegalHoldPolicyAssignmentHeaders` - Headers of createLegalHoldPolicyAssignment method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `LegalHoldPolicyAssignment`. Returns a new legal hold policy assignment. ## Get legal hold policy assignment Retrieve a legal hold policy assignment. This operation is performed by calling function `GetLegalHoldPolicyAssignmentById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-legal-hold-policy-assignments-id/). ``` await client.LegalHoldPolicyAssignments.GetLegalHoldPolicyAssignmentByIdAsync(legalHoldPolicyAssignmentId: legalHoldPolicyAssignmentId); ``` ### Arguments legalHoldPolicyAssignmentId `string` - The ID of the legal hold policy assignment. Example: "753465" headers `GetLegalHoldPolicyAssignmentByIdHeaders` - Headers of getLegalHoldPolicyAssignmentById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `LegalHoldPolicyAssignment`. Returns a legal hold policy object. ## Unassign legal hold policy Remove a legal hold from an item. This is an asynchronous process. The policy will not be fully removed yet when the response returns. This operation is performed by calling function `DeleteLegalHoldPolicyAssignmentById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-legal-hold-policy-assignments-id/). ``` await client.LegalHoldPolicyAssignments.DeleteLegalHoldPolicyAssignmentByIdAsync(legalHoldPolicyAssignmentId: legalHoldPolicyAssignmentId); ``` ### Arguments legalHoldPolicyAssignmentId `string` - The ID of the legal hold policy assignment. Example: "753465" headers `DeleteLegalHoldPolicyAssignmentByIdHeaders` - Headers of deleteLegalHoldPolicyAssignmentById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `null`. A blank response is returned if the assignment was successfully deleted. ## List files with current file versions for legal hold policy assignment Get a list of files with current file versions for a legal hold assignment. In some cases you may want to get previous file versions instead. In these cases, use the `GET /legal_hold_policy_assignments/:id/file_versions_on_hold` API instead to return any previous versions of a file for this legal hold policy assignment. Due to ongoing re-architecture efforts this API might not return all file versions held for this policy ID. Instead, this API will only return the latest file version held in the newly developed architecture. The `GET /file_version_legal_holds` API can be used to fetch current and past versions of files held within the legacy architecture. This endpoint does not support returning any content that is on hold due to a Custodian collaborating on a Hub. The `GET /legal_hold_policy_assignments?policy_id={id}` API can be used to find a list of policy assignments for a given policy ID. This operation is performed by calling function `GetLegalHoldPolicyAssignmentFileOnHold`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-legal-hold-policy-assignments-id-files-on-hold/). ``` await client.LegalHoldPolicyAssignments.GetLegalHoldPolicyAssignmentFileOnHoldAsync(legalHoldPolicyAssignmentId: legalHoldPolicyAssignmentId); ``` ### Arguments legalHoldPolicyAssignmentId `string` - The ID of the legal hold policy assignment. Example: "753465" queryParams `GetLegalHoldPolicyAssignmentFileOnHoldQueryParams` - Query parameters of getLegalHoldPolicyAssignmentFileOnHold method headers `GetLegalHoldPolicyAssignmentFileOnHoldHeaders` - Headers of getLegalHoldPolicyAssignmentFileOnHold method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `FilesOnHold`. Returns the list of current file versions held under legal hold for a specific legal hold policy assignment. --- ### IListCollaborationsManager **Type:** page | **Section:** Additional Resources IListCollaborationsManager List file collaborations List folder collaborations List pending collaborations List group collaborations List… # IListCollaborationsManager - [List file collaborations](#list-file-collaborations) - [List folder collaborations](#list-folder-collaborations) - [List pending collaborations](#list-pending-collaborations) - [List group collaborations](#list-group-collaborations) ## List file collaborations Retrieves a list of pending and active collaborations for a file. This returns all the users that have access to the file or have been invited to the file. This operation is performed by calling function `GetFileCollaborations`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-files-id-collaborations/). ``` await client.ListCollaborations.GetFileCollaborationsAsync(fileId: file.Id); ``` ### Arguments fileId `string` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" queryParams `GetFileCollaborationsQueryParams` - Query parameters of getFileCollaborations method headers `GetFileCollaborationsHeaders` - Headers of getFileCollaborations method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `Collaborations`. Returns a collection of collaboration objects. If there are no collaborations on this file an empty collection will be returned. This list includes pending collaborations, for which the `status` is set to `pending`, indicating invitations that have been sent but not yet accepted. ## List folder collaborations Retrieves a list of pending and active collaborations for a folder. This returns all the users that have access to the folder or have been invited to the folder. This operation is performed by calling function `GetFolderCollaborations`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-folders-id-collaborations/). ``` await client.ListCollaborations.GetFolderCollaborationsAsync(folderId: folder.Id); ``` ### Arguments folderId `string` - The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. Example: "12345" queryParams `GetFolderCollaborationsQueryParams` - Query parameters of getFolderCollaborations method headers `GetFolderCollaborationsHeaders` - Headers of getFolderCollaborations method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `Collaborations`. Returns a collection of collaboration objects. If there are no collaborations on this folder an empty collection will be returned. This list includes pending collaborations, for which the `status` is set to `pending`, indicating invitations that have been sent but not yet accepted. ## List pending collaborations Retrieves all pending collaboration invites for this user. This operation is performed by calling function `GetCollaborations`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-collaborations/). ``` await client.ListCollaborations.GetCollaborationsAsync(queryParams: new GetCollaborationsQueryParams(status: GetCollaborationsQueryParamsStatusField.Pending)); ``` ### Arguments queryParams `GetCollaborationsQueryParams` - Query parameters of getCollaborations method headers `GetCollaborationsHeaders` - Headers of getCollaborations method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `CollaborationsOffsetPaginated`. Returns a collection of pending collaboration objects. If the user has no pending collaborations, the collection will be empty. ## List group collaborations Retrieves all the collaborations for a group. The user must have admin permissions to inspect enterprise's groups. Each collaboration object has details on which files or folders the group has access to and with what role. This operation is performed by calling function `GetGroupCollaborations`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-groups-id-collaborations/). ``` await client.ListCollaborations.GetGroupCollaborationsAsync(groupId: group.Id); ``` ### Arguments groupId `string` - The ID of the group. Example: "57645" queryParams `GetGroupCollaborationsQueryParams` - Query parameters of getGroupCollaborations method headers `GetGroupCollaborationsHeaders` - Headers of getGroupCollaborations method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `CollaborationsOffsetPaginated`. Returns a collection of collaboration objects. If there are no collaborations, an empty collection will be returned. --- ### IMembershipsManager **Type:** page | **Section:** Additional Resources IMembershipsManager List user's groups List members of group Add user to group Get group membership Update group membership Remove user from… # IMembershipsManager - [List user's groups](#list-users-groups) - [List members of group](#list-members-of-group) - [Add user to group](#add-user-to-group) - [Get group membership](#get-group-membership) - [Update group membership](#update-group-membership) - [Remove user from group](#remove-user-from-group) ## List user's groups Retrieves all the groups for a user. Only members of this group or users with admin-level permissions will be able to use this API. This operation is performed by calling function `GetUserMemberships`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-users-id-memberships/). ``` await client.Memberships.GetUserMembershipsAsync(userId: user.Id); ``` ### Arguments userId `string` - The ID of the user. Example: "12345" queryParams `GetUserMembershipsQueryParams` - Query parameters of getUserMemberships method headers `GetUserMembershipsHeaders` - Headers of getUserMemberships method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `GroupMemberships`. Returns a collection of membership objects. If there are no memberships, an empty collection will be returned. ## List members of group Retrieves all the members for a group. Only members of this group or users with admin-level permissions will be able to use this API. This operation is performed by calling function `GetGroupMemberships`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-groups-id-memberships/). ``` await client.Memberships.GetGroupMembershipsAsync(groupId: group.Id); ``` ### Arguments groupId `string` - The ID of the group. Example: "57645" queryParams `GetGroupMembershipsQueryParams` - Query parameters of getGroupMemberships method headers `GetGroupMembershipsHeaders` - Headers of getGroupMemberships method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `GroupMemberships`. Returns a collection of membership objects. If there are no memberships, an empty collection will be returned. ## Add user to group Creates a group membership. Only users with admin-level permissions will be able to use this API. This operation is performed by calling function `CreateGroupMembership`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-group-memberships/). ``` await client.Memberships.CreateGroupMembershipAsync(requestBody: new CreateGroupMembershipRequestBody(user: new CreateGroupMembershipRequestBodyUserField(id: user.Id), group: new CreateGroupMembershipRequestBodyGroupField(id: group.Id))); ``` ### Arguments requestBody `CreateGroupMembershipRequestBody` - Request body of createGroupMembership method queryParams `CreateGroupMembershipQueryParams` - Query parameters of createGroupMembership method headers `CreateGroupMembershipHeaders` - Headers of createGroupMembership method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `GroupMembership`. Returns a new group membership object. ## Get group membership Retrieves a specific group membership. Only admins of this group or users with admin-level permissions will be able to use this API. This operation is performed by calling function `GetGroupMembershipById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-group-memberships-id/). ``` await client.Memberships.GetGroupMembershipByIdAsync(groupMembershipId: NullableUtils.Unwrap(groupMembership.Id)); ``` ### Arguments groupMembershipId `string` - The ID of the group membership. Example: "434534" queryParams `GetGroupMembershipByIdQueryParams` - Query parameters of getGroupMembershipById method headers `GetGroupMembershipByIdHeaders` - Headers of getGroupMembershipById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `GroupMembership`. Returns the group membership object. ## Update group membership Updates a user's group membership. Only admins of this group or users with admin-level permissions will be able to use this API. This operation is performed by calling function `UpdateGroupMembershipById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-group-memberships-id/). ``` await client.Memberships.UpdateGroupMembershipByIdAsync(groupMembershipId: NullableUtils.Unwrap(groupMembership.Id), requestBody: new UpdateGroupMembershipByIdRequestBody() { Role = UpdateGroupMembershipByIdRequestBodyRoleField.Admin }); ``` ### Arguments groupMembershipId `string` - The ID of the group membership. Example: "434534" requestBody `UpdateGroupMembershipByIdRequestBody` - Request body of updateGroupMembershipById method queryParams `UpdateGroupMembershipByIdQueryParams` - Query parameters of updateGroupMembershipById method headers `UpdateGroupMembershipByIdHeaders` - Headers of updateGroupMembershipById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `GroupMembership`. Returns a new group membership object. ## Remove user from group Deletes a specific group membership. Only admins of this group or users with admin-level permissions will be able to use this API. This operation is performed by calling function `DeleteGroupMembershipById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-group-memberships-id/). ``` await client.Memberships.DeleteGroupMembershipByIdAsync(groupMembershipId: NullableUtils.Unwrap(groupMembership.Id)); ``` ### Arguments groupMembershipId `string` - The ID of the group membership. Example: "434534" headers `DeleteGroupMembershipByIdHeaders` - Headers of deleteGroupMembershipById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `null`. A blank response is returned if the membership was successfully deleted. --- ### IMetadataCascadePoliciesManager **Type:** page | **Section:** Additional Resources IMetadataCascadePoliciesManager List metadata cascade policies Create metadata cascade policy Get metadata cascade policy Remove metadata… # IMetadataCascadePoliciesManager - [List metadata cascade policies](#list-metadata-cascade-policies) - [Create metadata cascade policy](#create-metadata-cascade-policy) - [Get metadata cascade policy](#get-metadata-cascade-policy) - [Remove metadata cascade policy](#remove-metadata-cascade-policy) - [Force-apply metadata cascade policy to folder](#force-apply-metadata-cascade-policy-to-folder) ## List metadata cascade policies Retrieves a list of all the metadata cascade policies that are applied to a given folder. This can not be used on the root folder with ID `0`. This operation is performed by calling function `GetMetadataCascadePolicies`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-metadata-cascade-policies/). ``` await client.MetadataCascadePolicies.GetMetadataCascadePoliciesAsync(queryParams: new GetMetadataCascadePoliciesQueryParams(folderId: folder.Id)); ``` ### Arguments queryParams `GetMetadataCascadePoliciesQueryParams` - Query parameters of getMetadataCascadePolicies method headers `GetMetadataCascadePoliciesHeaders` - Headers of getMetadataCascadePolicies method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `MetadataCascadePolicies`. Returns a list of metadata cascade policies. ## Create metadata cascade policy Creates a new metadata cascade policy that applies a given metadata template to a given folder and automatically cascades it down to any files within that folder. In order for the policy to be applied a metadata instance must first be applied to the folder the policy is to be applied to. This operation is performed by calling function `CreateMetadataCascadePolicy`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-metadata-cascade-policies/). ``` await client.MetadataCascadePolicies.CreateMetadataCascadePolicyAsync(requestBody: new CreateMetadataCascadePolicyRequestBody(folderId: folder.Id, scope: CreateMetadataCascadePolicyRequestBodyScopeField.Enterprise, templateKey: templateKey)); ``` ### Arguments requestBody `CreateMetadataCascadePolicyRequestBody` - Request body of createMetadataCascadePolicy method headers `CreateMetadataCascadePolicyHeaders` - Headers of createMetadataCascadePolicy method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `MetadataCascadePolicy`. Returns a new of metadata cascade policy. ## Get metadata cascade policy Retrieve a specific metadata cascade policy assigned to a folder. This operation is performed by calling function `GetMetadataCascadePolicyById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-metadata-cascade-policies-id/). ``` await client.MetadataCascadePolicies.GetMetadataCascadePolicyByIdAsync(metadataCascadePolicyId: cascadePolicyId); ``` ### Arguments metadataCascadePolicyId `string` - The ID of the metadata cascade policy. Example: "6fd4ff89-8fc1-42cf-8b29-1890dedd26d7" headers `GetMetadataCascadePolicyByIdHeaders` - Headers of getMetadataCascadePolicyById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `MetadataCascadePolicy`. Returns a metadata cascade policy. ## Remove metadata cascade policy Deletes a metadata cascade policy. This operation is performed by calling function `DeleteMetadataCascadePolicyById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-metadata-cascade-policies-id/). ``` await client.MetadataCascadePolicies.DeleteMetadataCascadePolicyByIdAsync(metadataCascadePolicyId: cascadePolicyId); ``` ### Arguments metadataCascadePolicyId `string` - The ID of the metadata cascade policy. Example: "6fd4ff89-8fc1-42cf-8b29-1890dedd26d7" headers `DeleteMetadataCascadePolicyByIdHeaders` - Headers of deleteMetadataCascadePolicyById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `null`. Returns an empty response when the policy is successfully deleted. ## Force-apply metadata cascade policy to folder Force the metadata on a folder with a metadata cascade policy to be applied to all of its children. This can be used after creating a new cascade policy to enforce the metadata to be cascaded down to all existing files within that folder. This operation is performed by calling function `ApplyMetadataCascadePolicy`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-metadata-cascade-policies-id-apply/). ``` await client.MetadataCascadePolicies.ApplyMetadataCascadePolicyAsync(metadataCascadePolicyId: cascadePolicyId, requestBody: new ApplyMetadataCascadePolicyRequestBody(conflictResolution: ApplyMetadataCascadePolicyRequestBodyConflictResolutionField.Overwrite)); ``` ### Arguments metadataCascadePolicyId `string` - The ID of the cascade policy to force-apply. Example: "6fd4ff89-8fc1-42cf-8b29-1890dedd26d7" requestBody `ApplyMetadataCascadePolicyRequestBody` - Request body of applyMetadataCascadePolicy method headers `ApplyMetadataCascadePolicyHeaders` - Headers of applyMetadataCascadePolicy method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `null`. Returns an empty response when the API call was successful. The metadata cascade operation will be performed asynchronously. The API call will return directly, before the cascade operation is complete. There is currently no API to check for the status of this operation. --- ### IMetadataTemplatesManager **Type:** page | **Section:** Additional Resources IMetadataTemplatesManager Find metadata template by instance ID Get metadata template by name Update metadata template Remove metadata… # IMetadataTemplatesManager - [Find metadata template by instance ID](#find-metadata-template-by-instance-id) - [Get metadata template by name](#get-metadata-template-by-name) - [Update metadata template](#update-metadata-template) - [Remove metadata template](#remove-metadata-template) - [Get metadata template by ID](#get-metadata-template-by-id) - [List all global metadata templates](#list-all-global-metadata-templates) - [List all metadata templates for enterprise](#list-all-metadata-templates-for-enterprise) - [Create metadata template](#create-metadata-template) ## Find metadata template by instance ID Finds a metadata template by searching for the ID of an instance of the template. This operation is performed by calling function `GetMetadataTemplatesByInstanceId`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-metadata-templates/). ``` await client.MetadataTemplates.GetMetadataTemplatesByInstanceIdAsync(queryParams: new GetMetadataTemplatesByInstanceIdQueryParams(metadataInstanceId: NullableUtils.Unwrap(createdMetadataInstance.Id))); ``` ### Arguments queryParams `GetMetadataTemplatesByInstanceIdQueryParams` - Query parameters of getMetadataTemplatesByInstanceId method headers `GetMetadataTemplatesByInstanceIdHeaders` - Headers of getMetadataTemplatesByInstanceId method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `MetadataTemplates`. Returns a list containing the 1 metadata template that matches the instance ID. ## Get metadata template by name Retrieves a metadata template by its `scope` and `templateKey` values. To find the `scope` and `templateKey` for a template, list all templates for an enterprise or globally, or list all templates applied to a file or folder. This operation is performed by calling function `GetMetadataTemplate`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-metadata-templates-id-id-schema/). ``` await client.MetadataTemplates.GetMetadataTemplateAsync(scope: GetMetadataTemplateScope.Enterprise, templateKey: NullableUtils.Unwrap(template.TemplateKey)); ``` ### Arguments scope `GetMetadataTemplateScope` - The scope of the metadata template. Example: "global" templateKey `string` - The name of the metadata template. Example: "properties" headers `GetMetadataTemplateHeaders` - Headers of getMetadataTemplate method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `MetadataTemplate`. Returns the metadata template matching the `scope` and `template` name. ## Update metadata template Updates a metadata template. The metadata template can only be updated if the template already exists. The update is applied atomically. If any errors occur during the application of the operations, the metadata template will not be changed. This operation is performed by calling function `UpdateMetadataTemplate`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-metadata-templates-id-id-schema/). ``` await client.MetadataTemplates.UpdateMetadataTemplateAsync(scope: UpdateMetadataTemplateScope.Enterprise, templateKey: templateKey, requestBody: Array.AsReadOnly(new [] {new UpdateMetadataTemplateRequestBody(op: UpdateMetadataTemplateRequestBodyOpField.AddField) { FieldKey = "newfieldname", Data = new Dictionary<string, object>() { { "type", "string" }, { "displayName", "newFieldName" } } }})); ``` ### Arguments scope `UpdateMetadataTemplateScope` - The scope of the metadata template. Example: "global" templateKey `string` - The name of the metadata template. Example: "properties" requestBody `IReadOnlyList<UpdateMetadataTemplateRequestBody>` - Request body of updateMetadataTemplate method headers `UpdateMetadataTemplateHeaders` - Headers of updateMetadataTemplate method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `MetadataTemplate`. Returns the updated metadata template, with the custom template data included. ## Remove metadata template Delete a metadata template and its instances. This deletion is permanent and can not be reversed. This operation is performed by calling function `DeleteMetadataTemplate`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-metadata-templates-id-id-schema/). ``` await client.MetadataTemplates.DeleteMetadataTemplateAsync(scope: DeleteMetadataTemplateScope.Enterprise, templateKey: NullableUtils.Unwrap(template.TemplateKey)); ``` ### Arguments scope `DeleteMetadataTemplateScope` - The scope of the metadata template. Example: "global" templateKey `string` - The name of the metadata template. Example: "properties" headers `DeleteMetadataTemplateHeaders` - Headers of deleteMetadataTemplate method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `null`. Returns an empty response when the metadata template is successfully deleted. ## Get metadata template by ID Retrieves a metadata template by its ID. This operation is performed by calling function `GetMetadataTemplateById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-metadata-templates-id/). ``` await client.MetadataTemplates.GetMetadataTemplateByIdAsync(templateId: template.Id); ``` ### Arguments templateId `string` - The ID of the template. Example: "f7a9891f" headers `GetMetadataTemplateByIdHeaders` - Headers of getMetadataTemplateById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `MetadataTemplate`. Returns the metadata template that matches the ID. ## List all global metadata templates Used to retrieve all generic, global metadata templates available to all enterprises using Box. This operation is performed by calling function `GetGlobalMetadataTemplates`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-metadata-templates-global/). ``` await client.MetadataTemplates.GetGlobalMetadataTemplatesAsync(); ``` ### Arguments queryParams `GetGlobalMetadataTemplatesQueryParams` - Query parameters of getGlobalMetadataTemplates method headers `GetGlobalMetadataTemplatesHeaders` - Headers of getGlobalMetadataTemplates method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `MetadataTemplates`. Returns all of the metadata templates available to all enterprises and their corresponding schema. ## List all metadata templates for enterprise Used to retrieve all metadata templates created to be used specifically within the user's enterprise. This operation is performed by calling function `GetEnterpriseMetadataTemplates`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-metadata-templates-enterprise/). ``` await client.MetadataTemplates.GetEnterpriseMetadataTemplatesAsync(); ``` ### Arguments queryParams `GetEnterpriseMetadataTemplatesQueryParams` - Query parameters of getEnterpriseMetadataTemplates method headers `GetEnterpriseMetadataTemplatesHeaders` - Headers of getEnterpriseMetadataTemplates method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `MetadataTemplates`. Returns all of the metadata templates within an enterprise and their corresponding schema. ## Create metadata template Creates a new metadata template that can be applied to files and folders. This operation is performed by calling function `CreateMetadataTemplate`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-metadata-templates-schema/). ``` await client.MetadataTemplates.CreateMetadataTemplateAsync(requestBody: new CreateMetadataTemplateRequestBody(scope: "enterprise", displayName: templateKey) { TemplateKey = templateKey, Fields = Array.AsReadOnly(new [] {new CreateMetadataTemplateRequestBodyFieldsField(type: CreateMetadataTemplateRequestBodyFieldsTypeField.String, key: "testName", displayName: "testName"),new CreateMetadataTemplateRequestBodyFieldsField(type: CreateMetadataTemplateRequestBodyFieldsTypeField.Float, key: "age", displayName: "age"),new CreateMetadataTemplateRequestBodyFieldsField(type: CreateMetadataTemplateRequestBodyFieldsTypeField.Date, key: "birthDate", displayName: "birthDate"),new CreateMetadataTemplateRequestBodyFieldsField(type: CreateMetadataTemplateRequestBodyFieldsTypeField.Enum, key: "countryCode", displayName: "countryCode") { Options = Array.AsReadOnly(new [] {new CreateMetadataTemplateRequestBodyFieldsOptionsField(key: "US"),new CreateMetadataTemplateRequestBodyFieldsOptionsField(key: "CA")}) },new CreateMetadataTemplateRequestBodyFieldsField(type: CreateMetadataTemplateRequestBodyFieldsTypeField.MultiSelect, key: "sports", displayName: "sports") { Options = Array.AsReadOnly(new [] {new CreateMetadataTemplateRequestBodyFieldsOptionsField(key: "basketball"),new CreateMetadataTemplateRequestBodyFieldsOptionsField(key: "football"),new CreateMetadataTemplateRequestBodyFieldsOptionsField(key: "tennis")}) }}) }); ``` ### Arguments requestBody `CreateMetadataTemplateRequestBody` - Request body of createMetadataTemplate method headers `CreateMetadataTemplateHeaders` - Headers of createMetadataTemplate method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `MetadataTemplate`. The schema representing the metadata template created. --- ### Information Barrier Reports **Type:** page | **Section:** Additional Resources Information Barrier Reports Information Barrier Reports Get shield information barrier report by ID List shield information barrier reports… # Information Barrier Reports [Information Barrier Reports](#information-barrier-reports) - [Get shield information barrier report by ID](#get-shield-information-barrier-report-by-id) - [List shield information barrier reports](#list-shield-information-barrier-reports) - [Create shield information barrier report](#create-shield-information-barrier-report) ## Get shield information barrier report by ID To retrieve a shield information barrier report by its ID, call the [`shieldInformationBarrierReports.getById(options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/ShieldInformationBarrierReportsManager.html#getById) method. ``` const barrierReport = await client.shieldInformationBarrierReports.getById({ shield_information_barrier_report_id: '12345', }); console.log(`Shield information barrier report id ${barrierReport.id}`); ``` ## List shield information barrier reports To retrieves a list of shield information barrier reports based on provided barrier ID, call the [`shieldInformationBarrierReports.getAll(options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/ShieldInformationBarrierReportsManager.html#getAll) method. ``` const result = await client.shieldInformationBarrierReports.getAll({ shield_information_barrier_id: '123' }); console.log(`There are ${result.entries.length} shield information barrier reports`); ``` ## Create shield information barrier report To create a shield information barrier report for a given barrier, call the [`shieldInformationBarrierReports.create(options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/ShieldInformationBarrierReportsManager.html#create) method with a `shield_information_barrier` object in the body of the request. ``` const barrierReport = await client.shieldInformationBarrierReports.create({ shield_information_barrier: { id: '123', type: 'shield_information_barrier' } }); console.log(`Shield information barrier report with id ${barrierReport.id} was created`); ``` --- ### Information Barrier Segment Members **Type:** page | **Section:** Additional Resources Information Barrier Segment Members Information Barrier Segment Members Get shield information barrier segment member by ID List shield… # Information Barrier Segment Members [Information Barrier Segment Members](#information-barrier-segment-members) - [Get shield information barrier segment member by ID](#get-shield-information-barrier-segment-member-by-id) - [List shield information barrier segment members](#list-shield-information-barrier-segment-members) - [Create shield information barrier segment member](#create-shield-information-barrier-segment-member) - [Delete shield information barrier segment member by ID](#delete-shield-information-barrier-segment-member-by-ID) ## Get shield information barrier segment member by ID To retrieve a shield information barrier segment member by its ID, call the [`shieldInformationBarrierSegmentMembers.getById(options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/ShieldInformationBarrierSegmentMembersManager.html#getById) method. ``` const barrierSegmentMember = await client.shieldInformationBarrierSegmentMembers.getById({ shield_information_barrier_segment_member_id: '12345', }); console.log(`Shield information barrier segment member id ${barrierSegmentMember.id}`); ``` ## List shield information barrier segment members To retrieves a list shield information barrier segment members based on provided segment IDs, call the [`shieldInformationBarrierSegmentMembers.getAll(options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/ShieldInformationBarrierSegmentMembersManager.html#getAll) method. ``` const result = await client.shieldInformationBarrierSegmentMembers.getAll({ shield_information_barrier_segment_id: '123' }); console.log(`There are ${result.entries.length} shield information barrier segment members`); ``` ## Create shield information barrier segment member To creates a new shield information barrier segment member, call the [`shieldInformationBarrierSegmentMembers.create(options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/ShieldInformationBarrierSegmentMembersManager.html#create) method with two objects in the body of the request, `barrer segment` and `user` where only `id` and `type` properties are required in each of them. ``` const barrierSegmentMember = await client.shieldInformationBarrierSegmentMembers.create({ shield_information_barrier_segment: { id: '234', type: 'shield_information_barrier_segment' }, user: { id: '456', type: 'user' } }); console.log(`Shield information barrier segment member id ${barrierSegmentMember.id} created`); ``` ## Delete shield information barrier segment member by ID To delete the shield information barrier segment member based on provided ID, call the [`shieldInformationBarrierSegmentMembers.delete(options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/ShieldInformationBarrierSegmentMembersManager.html#deleteById) method. ``` await client.shieldInformationBarrierSegmentMembers.deleteById({ shield_information_barrier_segment_member_id: '12345' }); ``` --- ### Information Barrier Segment Restrictions **Type:** page | **Section:** Additional Resources Information Barrier Segment Restrictions Information Barrier Segment Restrictions Get shield information barrier segment restriction by ID… # Information Barrier Segment Restrictions [Information Barrier Segment Restrictions](#information-barrier-segment-restrictions) - [Get shield information barrier segment restriction by ID](#get-shield-information-barrier-segment-restriction-by-id) - [List shield information barrier segment restrictions](#list-shield-information-barrier-segment-restrictions) - [Create shield information barrier segment restriction](#create-shield-information-barrier-segment-restriction) - [Delete shield information barrier segment restriction by ID](#delete-shield-information-barrier-segment-restriction-by-id) ## Get shield information barrier segment restriction by ID To retrieve a shield information barrier segment restriction by its ID, call the [`shieldInformationBarrierSegmentRestrictions.getById(options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/ShieldInformationBarrierSegmentRestrictionsManager.html#getById) method. ``` const barrierSegmentRestriction = await client.shieldInformationBarrierSegmentRestrictions.getById({ shield_information_barrier_segment_restriction_id: '12345', }); console.log(`Shield information barrier segment restriction id ${barrierSegmentRestriction.id}`); ``` ## List shield information barrier segment restrictions To retrieves a list of shield information barrier segment restrictions based on provided segment ID, call the [`shieldInformationBarrierSegmentRestrictions.getAll(options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/ShieldInformationBarrierSegmentRestrictionsManager.html#getAll) method. ``` const result = await client.shieldInformationBarrierSegmentRestrictions.getAll({ shield_information_barrier_segment_id: '123' }); console.log(`There are ${result.entries.length} shield information barrier segment restrictions`); ``` ## Create shield information barrier segment restriction To creates a new shield information barrier segment restriction, call the [`shieldInformationBarrierSegmentRestrictions.create(options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/ShieldInformationBarrierSegmentRestrictionsManager.html#create) method. As a body parameter, you need to pass an object with the properties: `type`, `shield_information_barrier_segment` and `restricted_segment`, like in the following example: ``` const barrierSegmentRestriction = await client.shieldInformationBarrierSegmentRestrictions.create({ type: 'shield_information_barrier_segment_restriction', shield_information_barrier_segment: { type: 'shield_information_barrier_segment', id: '1910967' }, restricted_segment: { type: 'shield_information_barrier_segment', id: '1910968' } }); console.log(`Shield information barrier segment restriction with id ${barrierSegmentRestriction.id} was created`); ``` ## Delete shield information barrier segment restriction by ID To delete the shield information barrier segment restriction based on provided ID, call the [`shieldInformationBarrierSegmentRestrictions.delete(options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/ShieldInformationBarrierSegmentRestrictionsManager.html#deleteById) method. ``` await client.shieldInformationBarrierSegmentRestrictions.deleteById({ shield_information_barrier_segment_restriction_id: '12345' }); ``` --- ### Information Barrier Segments **Type:** page | **Section:** Additional Resources Information Barrier Segments Information barrier segments (or just segments) are defined groups of users. They are different from user… # Information Barrier Segments Information barrier segments (or just segments) are defined groups of users. They are different from user groups, however, because with segments, a user can be a member of one, and only one, segment. This requirement for uniqueness in segments also means that you can add only individual users to segments, not user groups. [Information Barrier Segments](#information-barrier-segments) - [Get shield information barrier segment with specified ID](#get-shield-information-barrier-segment-with-specified-id) - [List shield information barrier segments](#list-shield-information-barrier-segments) - [Create shield information barrier segment](#create-shield-information-barrier-segment) - [Update shield information barrier segment](#update-shield-information-barrier-segment) - [Delete shield information barrier segment](#delete-shield-information-barrier-segment) ## Get shield information barrier segment with specified ID To get a shield information barrier segment based on provided ID by, call the [`shieldInformationBarrierSegments.getById(options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/ShieldInformationBarrierSegmentsManager.html#getById) method. ``` const barrierSegment = await client.shieldInformationBarrierSegments.getById({ shield_information_barrier_segment_id: '12345', }); console.log(`Shield information barrier segment id ${barrierSegment.id}`); ``` ## List shield information barrier segments To retrieve a list of shield information barrier segment objects for the specified Information Barrier ID, call the [`shieldInformationBarrierSegments.getAll(options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/ShieldInformationBarrierSegmentsManager.html#getAll) method. ``` const result = await client.shieldInformationBarrierSegments.getAll({ shield_information_barrier_id: '123' }); console.log(`There are ${result.entries.length} shield information barrier segments`); ``` ## Create shield information barrier segment To create a shield information barrier segment, call the [`shieldInformationBarrierSegments.create(options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/ShieldInformationBarrierSegmentsManager.html#create) method. The `name` and `shield_information_barrier` fields are required in the body, and the description is optional. ``` const barrierSegment = await client.shieldInformationBarrierSegments.create({ name: 'barrier segment name', description: 'barrier segment description', shield_information_barrier: { id: '123', type: 'shield_information_barrier' }, }); console.log(`Shield information barrier segment id ${barrierSegment.id} created`); ``` ## Update shield information barrier segment Updates the shield information barrier segment based on provided ID by calling [`shieldInformationBarrierSegments.update(body, options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/ShieldInformationBarrierSegmentsManager.html#update) method. ``` const barrierSegment = await client.shieldInformationBarrierSegments.update({ name: 'updated name', description: 'updated description', }, { shield_information_barrier_segment_id: '12345' }); console.log(`Shield information barrier segment id ${barrierSegment.id} updated`); ``` ## Delete shield information barrier segment To delete the shield information barrier segment based on provided ID, call the [`shieldInformationBarrierSegments.delete(options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/ShieldInformationBarrierSegmentsManager.html#deleteById) method. ``` await client.shieldInformationBarrierSegments.deleteById({ shield_information_barrier_segment_id: '12345' }); ``` --- ### Information Barriers **Type:** page | **Section:** Additional Resources Information Barriers Get shield information barrier with specified ID Get all shield information barriers Update shield information barrier… # Information Barriers - [Get shield information barrier with specified ID](#get-shield-information-barrier-with-specified-id) - [Get all shield information barriers](#get-all-shield-information-barriers) - [Update shield information barrier status](#update-shield-information-barrier-status) - [Create shield information barrier](#create-shield-information-barrier) ## Get shield information barrier with specified ID Get shield information barrier based on provided ID by [`shieldInformationBarriers.getById(options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/ShieldInformationBarrierManager.html#getById) method. ``` const barrier = await client.shieldInformationBarriers.getById({ shield_information_barrier_id: 12345, }); console.log( `Shield information barrier id ${barrier.id}` ); ``` ## Get all shield information barriers Retrieves a list of shield information barrier objects for the enterprise of JWT by [`shieldInformationBarriers.getAll(options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/ShieldInformationBarrierManager.html#getAll) method. ``` const result = await client.shieldInformationBarriers.getAll(); console.log(`There are ${result.entries.length} shield information barriers`); ``` ## Update shield information barrier status Change status of shield information barrier with the specified ID. [`shieldInformationBarriers.changeStatusById(body, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/ShieldInformationBarrierManager.html#changeStatusById) method. ``` const barrier = await client.shieldInformationBarriers.changeStatusById({ id: 12345, status: 'pending', }); console.log( `Shield information barrier id ${barrier.id} status is ${barrier.status}` ); ``` ## Create shield information barrier Creates a shield information barrier to separate individuals/groups within the same firm and prevents confidential information passing between them.[`shieldInformationBarriers.create(options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/ShieldInformationBarrierManager.html#create) method. ``` const barrier = await client.shieldInformationBarriers.create({ enterprise: { id: '12345', type: 'enterprise', }, }); console.log( `Shield information barrier id ${barrier.id} created` ); ``` --- ### Installation **Type:** page | **Section:** Additional Resources fastlane documentation Installation Make sure you have the latest version of the Xcode command line tools installed: For fastlane… ## fastlane documentation # Installation Make sure you have the latest version of the Xcode command line tools installed: ``` xcode-select --install ``` For *fastlane* installation instructions, see [Installing *fastlane*](https://docs.fastlane.tools/#installing-fastlane) # Available Actions ## iOS ### ios make_pull_request ``` [bundle exec] fastlane ios make_pull_request ``` Create PR with release changes ### ios make_release ``` [bundle exec] fastlane ios make_release ``` Create new release on github ### ios make_publish_pod ``` [bundle exec] fastlane ios make_publish_pod ``` Publish to version of cocoapods This README.md is auto-generated and will be re-generated every time [*fastlane*](https://fastlane.tools) is run. More information about *fastlane* can be found on [fastlane.tools](https://fastlane.tools). The documentation of *fastlane* can be found on [docs.fastlane.tools](https://docs.fastlane.tools). --- ### Integration mappings **Type:** page | **Section:** Additional Resources Integration mappings With integration mappings, you can manage where content from partner apps is stored in Box. It is well suited for… # Integration mappings With integration mappings, you can manage where content from partner apps is stored in Box. It is well suited for situations in which a particular Slack channel already has a corresponding folder in Box and allows to map it for uploads instead of using the automatically created folder within the default structure. For more details on Slack mapping please see the [Box as the Content Layer for Slack](https://support.box.com/hc/en-us/articles/4415585987859-Box-as-the-Content-Layer-for-Slack). [Integration mappings](#integration-mappings) - [List Slack integration mappings](#list-slack-integration-mappings) - [Create Slack integration mapping](#create-slack-integration-mapping) - [Update Slack integration mapping](#update-slack-integration-mapping) - [Delete Slack integration mapping](#delete-slack-integration-mapping) ## List Slack integration mappings To get a list of all Slack integration mappings, call the [`integrationMappings.getSlackIntegrationMappings(options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/IntegrationMappingsManager.html#getSlackIntegrationMappings) method. ``` const integrationMappings = await client.integrationMappings.getSlackIntegrationMappings(); console.log(`There are ${integrationMappings.entries.length} Slack integration mappings`); ``` The API gives you an option to filter the mappings by passing additional parameters. For example, if you want to get all integration mappings that are mapped to specific folder, you just need to pass the `box_item_id` param like below: ``` const integrationMappings = await client.integrationMappings.getSlackIntegrationMappings({box_item_id: '123'}); ``` On the other hand, if you want to get the mapping that is mapped to specific Slack channel, just pass the `partner_item_id` param, like below: ``` const integrationMappings = await client.integrationMappings.getSlackIntegrationMappings({partner_item_id: 'C12378991223'}); ``` If you want however to get all manually created mappings, you should pass the `is_manually_created` parameter set to true, like this: ``` const integrationMappings = await client.integrationMappings.getSlackIntegrationMappings({is_manually_created: true}); ``` ## Create Slack integration mapping To create a Slack integration mapping by mapping a Slack channel to a Box item, call the [`integrationMappings.createSlackIntegrationMapping(body, options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/IntegrationMappingsManager.html#createSlackIntegrationMapping) method. To correctly create the mapping, `partner_item` and `box_item` properties need to be passed in the body of the request. In the `partner_item`, you specify the mapping for the Slack, where `id` is the ID of the channel, `type` should be always `channel` and either `slack_org_id` or `slack_workspace_id` should be passed. The `box_item` represents the mapping for Box, where `id` is the ID of the folder and `type` should be always set to `folder`. ``` const mapping = await client.integrationMappings.createSlackIntegrationMapping({ partner_item: { type: 'channel', id: 'C12378991223', slack_org_id: 'E1234567' }, box_item: { id: '12345', type: 'folder', } }); console.log( `Slack integration mapping with id ${mapping.id} was created` ); ``` When calling a creation slack integration mapping request, you may get response with `400` status code and description like that: ``` Box as File Storage for Slack (user id: 123, user email: AutomationUser_456@boxdevedition.com) must be a collaborator in role co-owner or the owner of the folder 789, before it can be mapped to the channel XYZ. Please create a collaboration or ensure the ownership for Box as File Storage for Slack and retry.", ``` In this case, follow the description and add `Box as File Storage for Slack` Service as a collaborator in the role of co-owner role to the folder specified in the mapping. ``` const collaboration = await client.collaborations.createWithUserID('123', '12345', client.collaborationRoles.CO_OWNER); ``` Then call again te request to create the slack integration mapping, which should now succeed. ## Update Slack integration mapping To update a Slack integration mapping, call the [`integrationMappings.updateSlackIntegrationMapping(body, options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/IntegrationMappingsManager.html#updateSlackIntegrationMapping) method. You may want to call this method to change the mapping on Box by selecting a different folder or to modify the automatic management of channel member access to the underlying Box item. ``` const mapping = await client.integrationMappings.updateSlackIntegrationMapping({ box_item: { id: '12345', type: 'folder' }, options: { is_access_management_disabled: true } }, { integration_mapping_id: integrationMappingId }); console.log( `Slack integration mapping with id ${mapping.id} was updated` ); ``` ## Delete Slack integration mapping To delete a Slack integration mapping based on provided ID [`integrationMappings.deleteSlackIntegrationMappingById(options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/IntegrationMappingsManager.html#deleteSlackIntegrationMappingById) method. ``` await client.integrationMappings.deleteSlackIntegrationMappingById({ integration_mapping_id: 123456 }); ``` --- ### Integration tests **Type:** page | **Section:** Additional Resources Integration tests Setup To run the integration tests locally, you need an existing Box app. Create a platform app in https://cloud.app.box… # Integration tests ## Setup To run the integration tests locally, you need an existing Box app. Create a platform app in [https://cloud.app.box.com/developers/console](https://cloud.app.box.com/developers/console). Select the JWT authentication method. You must enable all possible scopes and authorize your app to access the Enterprise if you want to run all the tests. Some tests requires enterprise access and different scopes. When your application is ready download App Settings as and replace the existing `config.json` file in this directory with your own. There is an optional `userId` field that you can fill in with your existing `userId`, so this user will be used in the tests and no new user will be created. You can run the test using Visual Studio test explorer or from the command line by calling the following command ``` dotnet test .\Box.V2.Test.Integration ``` By default, integration tests will run for .net framework and .net core. You can run tests against either of these by passing the -f flag as follows. ``` dotnet test .\Box.V2.Test.Integration -f netcoreapp2.0 ``` ## Command approach for test setup Typically, integration tests require pre-existing resources (such as files) to operate on them. Such resources should also be removed from the account when the test ends or when an exception is thrown. To eliminate the need to duplicate such logic, the command approach was introduced. An example `IDisposableCommand` implementation looks like this ``` using System.Threading.Tasks; using Box.V2.Models; namespace Box.V2.Test.Integration.Configuration.Commands.DisposableCommands { public class CreateFolderCommand : CommandBase, IDisposableCommand { private readonly string _folderName; private readonly string _parentId; public string FolderId; public BoxFolder Folder; public CreateFolderCommand(string folderName, string parentId = "0", CommandScope scope = CommandScope.Test, CommandAccessLevel accessLevel = CommandAccessLevel.User) : base(scope, accessLevel) { _folderName = folderName; _parentId = parentId; } public async Task<string> Execute(IBoxClient client) { var createFolderRequest = new BoxFolderRequest { Name = _folderName, Parent = new BoxRequestEntity { Id = _parentId } }; Folder = await client.FoldersManager.CreateAsync(createFolderRequest); FolderId = Folder.Id; return FolderId; } public async Task Dispose(IBoxClient client) { await client.FoldersManager.DeleteAsync(FolderId); await client.FoldersManager.PurgeTrashedFolderAsync(FolderId); } } } ``` The Execute command will be called when the command is executed, and Dispose when the test is terminated or an exception is thrown. As you can see, dispose or execute command could consist of multiple API calls. `CommandAccessLevel` indicates which BoxClient should be used for the test (managed or service account). Depends on what you may need and the enterprise access (e.g., to create a MetadataTemplate). `CommandScope` indicates when dispose will be called (test, class, assembly). You can usually keep this as `CommandScope.Test` for single test setup commands. Commands are usually wrapped in helper methods that look like this ``` public static async Task<BoxFolder> CreateFolder(string parentId = "0", CommandScope commandScope = CommandScope.Test, CommandAccessLevel accessLevel = CommandAccessLevel.User) { var createFolderCommand = new CreateFolderCommand(GetUniqueName("folder"), parentId, commandScope, accessLevel); await ExecuteCommand(createFolderCommand); return createFolderCommand.Folder; } ``` You can then simply call this command in your test as follows ``` [TestMethod] public async Task GetWatermarkAsync_ForExistingFolder_ShouldCorrectlyApplyWatermarkOnFolder() { var folder = await CreateFolder(FolderId); await UserClient.FoldersManager.ApplyWatermarkAsync(folder.Id); var watermark = await UserClient.FoldersManager.GetWatermarkAsync(folder.Id); Assert.IsNotNull(watermark); } ``` As you can see, since this test does not test folder creation, so command logic is used. Try using or adding commands like this to simplify and reuse the test setup. This makes the tests more readable, easier to maintain, and ensures that the test account is in the same state after and before running all the tests. --- ### Integration Tests **Type:** page | **Section:** Additional Resources Integration Tests Running integration tests locally Create Platform Application To run integration tests locally you will need a Custom App… # Integration Tests ## Running integration tests locally ### Create Platform Application To run integration tests locally you will need a `Custom App` created at [https://cloud.app.box.com/developers/console](https://cloud.app.box.com/developers/console) with `Server Authentication (with JWT)` selected as authentication method. Once created you can edit properties of the application: - In section `App Access Level` select `App + Enterprise Access`. You can enable all `Application Scopes`. - In section `Advanced Features` enable `Make API calls using the as-user header` and `Generate user access tokens`. Now select `Authorization` and submit application to be reviewed by account admin. ### Export configuration There are two ways to set up JWT configuration: 1. First method: Select `Configuration` tab and in the bottom in the section `App Settings` download your app configuration settings as JSON. - Specify the path to the JWT config file in `test-config.json`, e.g. `"jwt_file_path": "/Users/me/jwt-config.json"` - Specify id of admin user account in `test-config.json`, e.g. `"admin_user_id": "13855142101"` 1. Alternatively: Select `Configuration` tab and in the bottom in the section `App Settings` download your app configuration settings as JSON. - Encode configuration file to Base64, e.g. using command: `base64 -i path_to_json_file` - Set environment variable: `JWT_CONFIG` with base64 encoded jwt configuration file - Set environment variable: `ADMIN_USER_ID` with id of admin user account ### Running integration tests To run integration tests, you can run command: ``` npm run jest ``` --- ### Integration Tests **Type:** page | **Section:** Additional Resources Integration Tests Running integration tests locally Create Platform Application To run integration tests locally you will need a Custom App… # Integration Tests ## Running integration tests locally ### Create Platform Application To run integration tests locally you will need a `Custom App` created at [https://cloud.app.box.com/developers/console](https://cloud.app.box.com/developers/console) with `Server Authentication (with JWT)` selected as authentication method. Once created you can edit properties of the application. In section `App Access Level` select `App + Enterprise Access`. You can enable all `Application Scopes`. In section `Advanced Features` enable `Make API calls using the as-user header` and `Generate user access tokens`. Now select `Authorization` and submit application to be reviewed by account admin. Next part is to obtain application settings. Select `Configuration` tab and in the bottom in the section `App Settings` download them as Json. ### Export configuration You will need to create environment variables in your system or IDE: - JAVA_COLLABORATOR_ID - you can find this in `General Settings` tab as `Collaborators` - JAVA_COLLABORATOR - you can find this in `General Settings` tab in field `User ID` - JAVA_ENTERPRISE_ID - you can find this in `General Settings` tab in field `Enterprise ID` - JAVA_JWT_CONFIG - contains Base64 of your configuration file. You can generate this in command line. On Linux/Mac OS you can use `base64 -i path_to_json_file`. ### Running Tests You can run tests from command line: ``` ./gradlew integrationTest ``` just remember that you need environment variables exported in previous step to be accessible. ## Useful help classes ### BoxApiProvider To obtain new API connection configured with provided JWT configuration use `BoxApiProvider` ``` BoxAPIConnection api = BoxApiProvider.jwtApiForServiceAccount(); ``` ### UniqueTestFolder `UniqueTestFolder` contains method that can help setup and remove unique folder for tests and upload files. To use new unique folder: ``` UniqueTestFolder.setupUniqeFolder(); // this will create a new test folder that can be used in tests UniqueTestFolder.getUniqueFolder(api); // this will retrieve unique folder UniqueTestFolder.removeUniqueFolder(); // this will remove unique folder with all subfolders and files ``` To upload files to root of the unique folder: ``` // to upload file with specified content BoxFile fileWithSpecifiedContent = UniqueTestFolder.uploadFileToUniqueFolder(api, "File Name", "Your content"); // to upload a file with some content BoxFile fileWithSomeContent = UniqueTestFolder.uploadFileToUniqueFolderWithSomeContent(api, "File Name"); ``` You can also upload file to some specified folder: ``` BoxFolder destinationFolder = UniqueTestFolder.getUniqueFolder(api); // obtain folder to upload file to BoxFile fileWithSomeContent = UniqueTestFolder.uploadFileWithSomeContent("File Name", destinationFolder); ``` ### Retry Sometimes API request can take some time to be processed and you might want to retry some logic when error occurs: ``` Retry.retry( () -> { BoxSignRequest signRequestGetByID = new BoxSignRequest(api, "signRequestId"); // do an API call, assert response - if call fails it will be repated BoxSignRequest.Info cancelationIfo = signRequestGetByID.cancel(); }, 5, // how many times retry the call 1000 // how long to wait between calls in miliseconds ); ``` ## Putting this all together Here is a sample test that uses some of the utility classes shown above: ``` public class BoxFolderIT { @BeforeClass public static void setup() { // create unique folder for all tests UniqueTestFolder.setupUniqeFolder(); } @AfterClass public static void tearDown() { // remove unique folder after all tests run UniqueTestFolder.removeUniqueFolder(); } @Test public void creatingAndDeletingFolderSucceeds() { // given BoxAPIConnection api = BoxApiProvider.jwtApiForServiceAccount(); BoxFolder rootFolder = UniqueTestFolder.getUniqueFolder(api); // expect new folder can be found // create subfolder in unique test folder BoxFolder childFolder = rootFolder.createFolder("My Folder").getResource(); assertThat(rootFolder, hasItem(Matchers.<BoxItem.Info>hasProperty("ID", equalTo(childFolder.getID())))); // expect folder cannot be found after deletion childFolder.delete(false); assertThat(rootFolder, not(hasItem(Matchers.<BoxItem.Info>hasProperty("ID", equalTo(childFolder.getID()))))); } } ``` --- ### Integration Tests **Type:** page | **Section:** Additional Resources Integration Tests Running integration tests locally Create Platform Application To run integration tests locally you will need a Custom App… # Integration Tests ## Running integration tests locally ### Create Platform Application To run integration tests locally you will need a `Custom App` created at [https://cloud.app.box.com/developers/console](https://cloud.app.box.com/developers/console) with `Server Authentication (with JWT)` selected as authentication method. Once created you can edit properties of the application: - In section `App Access Level` select `App + Enterprise Access`. You can enable all `Application Scopes`. - In section `Advanced Features` enable `Make API calls using the as-user header` and `Generate user access tokens`. Now select `Authorization` and submit application to be reviewed by account admin. ### Export configuration There are two ways to set up JWT configuration: 1. First method: Select `Configuration` tab and in the bottom in the section `App Settings` download your app configuration settings as JSON. - Specify the path to the JWT config file in `integration_tests.cfg`, e.g. `ConfigFilePath = /Users/me/jwt-config.json` - Specify id of admin user account in `integration_tests.cfg`, e.g. `AdminUserID = 13855142101` 1. Alternatively: Select `Configuration` tab and in the bottom in the section `App Settings` download your app configuration settings as JSON. - Encode configuration file to Base64, e.g. using command: `base64 -i path_to_json_file` - Set environment variable: `JWT_CONFIG_BASE_64` with base64 encoded jwt configuration file - Set environment variable: `ADMIN_USER_ID` with id of admin user account ### Running Tests You can run all tests (unit in all supported python environments and integration) using command: ``` tox ``` To run only integration tests, you can run: ``` tox -e integration-tests ``` --- ### Integration Tests **Type:** page | **Section:** Additional Resources Integration Tests Running integration tests locally Create Platform Application To run integration tests locally you will need a Custom App… # Integration Tests ## Running integration tests locally ### Create Platform Application To run integration tests locally you will need a `Custom App` created at [https://cloud.app.box.com/developers/console](https://cloud.app.box.com/developers/console) with `Server Authentication (Client Credentials Grant)` selected as authentication method. Once created you can edit properties of the application. In section `App Access Level` select `App + Enterprise Access`. You can enable all `Application Scopes`. In section `Advanced Features` enable `Make API calls using the as-user header`. Now select `Authorization` and submit application to be reviewed by account admin. ### Completing the configuration file Next, you will need to fill the `Configuration.json` file which is located under the following path `./IntegrationTests/Resources/Configuration.json` and look like this: ``` { "ccg": { "clientId": "", "clientSecret": "", "enterpriseId": "", "userId": "" }, "data": { "collaboratorId": "" } } ``` - `clientId` - you can find this in `Configuration` tab, in `Client ID` field - `clientSecret` - you can find this in `Configuration` tab, after tapped to `Fetch Client Secret` button - `enterpriseId` - you can find this in `General Settings` tab in field `Enterprise ID` - `userId` - you can find this in `General Settings` tab in field `User ID` - `collaboratorId` - please enter the ID of your designated collaborator here for testing purposes only. It is not required, however if you skip this field, then a few test will fail. You should pass either `enterpriseId` if you want to use Service Account account in your tests or `userId` if you want making calls as an App User or Managed User. In case when both these parameters will be filled, `enterpriseId` will be used. For more information about CCG authentication, please read [this document](../docs/usage/authentication.md#client-credentials-grant). ### Running Tests There are two ways to run tests: #### 1) From XCode First, open the `BoxSDK.xcworkspace` file and select the `BoxSDKIntegrationTests-iOS` scheme (`Product -> Scheme -> BoxSDKIntegrationTests-iOS`). Then run tests by selecting `Product -> Tests`. Make sure you have selected the target simulator before running these tests. #### 2) From command line Before run tests from command line, you should select the target simulator to run these tests on. In my case, I have `XCode 13.2.1` installed with `iOS SDK 15.2` and I want to run tests on iPhone 11 Simulator. So my destination target will be `platform=iOS Simulator,OS=15.2,name=iPhone 11`. ``` xcodebuild -workspace BoxSDK.xcworkspace \ -scheme BoxSDKIntegrationTests-iOS \ -destination "platform=iOS Simulator,OS=15.2,name=iPhone 11" \ -configuration Debug ENABLE_TESTABILITY=YES test ``` --- ### IntegrationMappingsManager **Type:** page | **Section:** Additional Resources IntegrationMappingsManager List Slack integration mappings Create Slack integration mapping Update Slack integration mapping Delete Slack… # IntegrationMappingsManager - [List Slack integration mappings](#list-slack-integration-mappings) - [Create Slack integration mapping](#create-slack-integration-mapping) - [Update Slack integration mapping](#update-slack-integration-mapping) - [Delete Slack integration mapping](#delete-slack-integration-mapping) - [List Teams integration mappings](#list-teams-integration-mappings) - [Create Teams integration mapping](#create-teams-integration-mapping) - [Update Teams integration mapping](#update-teams-integration-mapping) - [Delete Teams integration mapping](#delete-teams-integration-mapping) ## List Slack integration mappings Lists [Slack integration mappings](https://support.box.com/hc/en-us/articles/4415585987859-Box-as-the-Content-Layer-for-Slack) in a users' enterprise. You need Admin or Co-Admin role to use this endpoint. This operation is performed by calling function `getSlackIntegrationMapping`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-integration-mappings-slack/). ``` await userClient.integrationMappings.getSlackIntegrationMapping(); ``` ### Arguments queryParams `GetSlackIntegrationMappingQueryParams` - Query parameters of getSlackIntegrationMapping method headersInput `GetSlackIntegrationMappingHeadersInput` - Headers of getSlackIntegrationMapping method cancellationToken `undefined | CancellationToken` - Token used for request cancellation. ### Returns This function returns a value of type `IntegrationMappings`. Returns a collection of integration mappings. ## Create Slack integration mapping Creates a [Slack integration mapping](https://support.box.com/hc/en-us/articles/4415585987859-Box-as-the-Content-Layer-for-Slack) by mapping a Slack channel to a Box item. You need Admin or Co-Admin role to use this endpoint. This operation is performed by calling function `createSlackIntegrationMapping`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-integration-mappings-slack/). ``` await userClient.integrationMappings.createSlackIntegrationMapping({ partnerItem: new IntegrationMappingPartnerItemSlack({ id: slackPartnerItemId, slackOrgId: slackOrgId, }), boxItem: new IntegrationMappingBoxItemSlack({ id: folder.id }), } satisfies IntegrationMappingSlackCreateRequest); ``` ### Arguments requestBody `IntegrationMappingSlackCreateRequest` - Request body of createSlackIntegrationMapping method optionalsInput `CreateSlackIntegrationMappingOptionalsInput` ### Returns This function returns a value of type `IntegrationMapping`. Returns the created integration mapping. ## Update Slack integration mapping Updates a [Slack integration mapping](https://support.box.com/hc/en-us/articles/4415585987859-Box-as-the-Content-Layer-for-Slack). Supports updating the Box folder ID and options. You need Admin or Co-Admin role to use this endpoint. This operation is performed by calling function `updateSlackIntegrationMappingById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-integration-mappings-slack-id/). ``` await userClient.integrationMappings.updateSlackIntegrationMappingById( slackIntegrationMapping.id, { requestBody: { boxItem: new IntegrationMappingBoxItemSlack({ id: folder.id }), } satisfies UpdateSlackIntegrationMappingByIdRequestBody, } satisfies UpdateSlackIntegrationMappingByIdOptionalsInput, ); ``` ### Arguments integrationMappingId `string` - An ID of an integration mapping. Example: "11235432" optionalsInput `UpdateSlackIntegrationMappingByIdOptionalsInput` ### Returns This function returns a value of type `IntegrationMapping`. Returns the updated integration mapping object. ## Delete Slack integration mapping Deletes a [Slack integration mapping](https://support.box.com/hc/en-us/articles/4415585987859-Box-as-the-Content-Layer-for-Slack). You need Admin or Co-Admin role to use this endpoint. This operation is performed by calling function `deleteSlackIntegrationMappingById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-integration-mappings-slack-id/). ``` await userClient.integrationMappings.deleteSlackIntegrationMappingById( slackIntegrationMapping.id, ); ``` ### Arguments integrationMappingId `string` - An ID of an integration mapping. Example: "11235432" optionalsInput `DeleteSlackIntegrationMappingByIdOptionalsInput` ### Returns This function returns a value of type `undefined`. Empty body in response. ## List Teams integration mappings Lists [Teams integration mappings](https://support.box.com/hc/en-us/articles/360044681474-Using-Box-for-Teams) in a users' enterprise. You need Admin or Co-Admin role to use this endpoint. This operation is performed by calling function `getTeamsIntegrationMapping`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-integration-mappings-teams/). ``` await userClient.integrationMappings.getTeamsIntegrationMapping(); ``` ### Arguments queryParams `GetTeamsIntegrationMappingQueryParams` - Query parameters of getTeamsIntegrationMapping method headersInput `GetTeamsIntegrationMappingHeadersInput` - Headers of getTeamsIntegrationMapping method cancellationToken `undefined | CancellationToken` - Token used for request cancellation. ### Returns This function returns a value of type `IntegrationMappingsTeams`. Returns a collection of integration mappings. ## Create Teams integration mapping Creates a [Teams integration mapping](https://support.box.com/hc/en-us/articles/360044681474-Using-Box-for-Teams) by mapping a Teams channel to a Box item. You need Admin or Co-Admin role to use this endpoint. This operation is performed by calling function `createTeamsIntegrationMapping`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-integration-mappings-teams/). ``` await userClient.integrationMappings.createTeamsIntegrationMapping({ partnerItem: { type: 'channel' as IntegrationMappingPartnerItemTeamsCreateRequestTypeField, id: partnerItemId, tenantId: tenantId, teamId: teamId, } satisfies IntegrationMappingPartnerItemTeamsCreateRequest, boxItem: new FolderReference({ id: folder.id }), } satisfies IntegrationMappingTeamsCreateRequest); ``` ### Arguments requestBody `IntegrationMappingTeamsCreateRequest` - Request body of createTeamsIntegrationMapping method optionalsInput `CreateTeamsIntegrationMappingOptionalsInput` ### Returns This function returns a value of type `IntegrationMappingTeams`. Returns the created integration mapping. ## Update Teams integration mapping Updates a [Teams integration mapping](https://support.box.com/hc/en-us/articles/360044681474-Using-Box-for-Teams). Supports updating the Box folder ID and options. You need Admin or Co-Admin role to use this endpoint. This operation is performed by calling function `updateTeamsIntegrationMappingById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-integration-mappings-teams-id/). ``` await userClient.integrationMappings.updateTeamsIntegrationMappingById( integrationMappingId, { requestBody: { boxItem: new FolderReference({ id: '1234567' }), } satisfies UpdateTeamsIntegrationMappingByIdRequestBody, } satisfies UpdateTeamsIntegrationMappingByIdOptionalsInput, ); ``` ### Arguments integrationMappingId `string` - An ID of an integration mapping. Example: "11235432" optionalsInput `UpdateTeamsIntegrationMappingByIdOptionalsInput` ### Returns This function returns a value of type `IntegrationMappingTeams`. Returns the updated integration mapping object. ## Delete Teams integration mapping Deletes a [Teams integration mapping](https://support.box.com/hc/en-us/articles/360044681474-Using-Box-for-Teams). You need Admin or Co-Admin role to use this endpoint. This operation is performed by calling function `deleteTeamsIntegrationMappingById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-integration-mappings-teams-id/). ``` await userClient.integrationMappings.deleteTeamsIntegrationMappingById( integrationMappingId, ); ``` ### Arguments integrationMappingId `string` - An ID of an integration mapping. Example: "11235432" optionalsInput `DeleteTeamsIntegrationMappingByIdOptionalsInput` ### Returns This function returns a value of type `undefined`. Empty body in response. --- ### IntegrationMappingsManager **Type:** page | **Section:** Additional Resources IntegrationMappingsManager List Slack integration mappings Create Slack integration mapping Update Slack integration mapping Delete Slack… # IntegrationMappingsManager - [List Slack integration mappings](#list-slack-integration-mappings) - [Create Slack integration mapping](#create-slack-integration-mapping) - [Update Slack integration mapping](#update-slack-integration-mapping) - [Delete Slack integration mapping](#delete-slack-integration-mapping) - [List Teams integration mappings](#list-teams-integration-mappings) - [Create Teams integration mapping](#create-teams-integration-mapping) - [Update Teams integration mapping](#update-teams-integration-mapping) - [Delete Teams integration mapping](#delete-teams-integration-mapping) ## List Slack integration mappings Lists [Slack integration mappings](https://support.box.com/hc/en-us/articles/4415585987859-Box-as-the-Content-Layer-for-Slack) in a users' enterprise. You need Admin or Co-Admin role to use this endpoint. This operation is performed by calling function `get_slack_integration_mapping`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-integration-mappings-slack/). ``` user_client.integration_mappings.get_slack_integration_mapping() ``` ### Arguments marker `Optional[str]` - Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`. limit `Optional[int]` - The maximum number of items to return per page. partner_item_type `Optional[GetSlackIntegrationMappingPartnerItemType]` - Mapped item type, for which the mapping should be returned. partner_item_id `Optional[str]` - ID of the mapped item, for which the mapping should be returned. box_item_id `Optional[str]` - Box item ID, for which the mappings should be returned. box_item_type `Optional[GetSlackIntegrationMappingBoxItemType]` - Box item type, for which the mappings should be returned. is_manually_created `Optional[bool]` - Whether the mapping has been manually created. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `IntegrationMappings`. Returns a collection of integration mappings. ## Create Slack integration mapping Creates a [Slack integration mapping](https://support.box.com/hc/en-us/articles/4415585987859-Box-as-the-Content-Layer-for-Slack) by mapping a Slack channel to a Box item. You need Admin or Co-Admin role to use this endpoint. This operation is performed by calling function `create_slack_integration_mapping`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-integration-mappings-slack/). ``` user_client.integration_mappings.create_slack_integration_mapping( IntegrationMappingPartnerItemSlack( id=slack_partner_item_id, slack_org_id=slack_org_id ), IntegrationMappingBoxItemSlack(id=folder.id), ) ``` ### Arguments - partner_item `IntegrationMappingPartnerItemSlack` - box_item `IntegrationMappingBoxItemSlack` - options `Optional[IntegrationMappingSlackOptions]` extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `IntegrationMapping`. Returns the created integration mapping. ## Update Slack integration mapping Updates a [Slack integration mapping](https://support.box.com/hc/en-us/articles/4415585987859-Box-as-the-Content-Layer-for-Slack). Supports updating the Box folder ID and options. You need Admin or Co-Admin role to use this endpoint. This operation is performed by calling function `update_slack_integration_mapping_by_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-integration-mappings-slack-id/). ``` user_client.integration_mappings.update_slack_integration_mapping_by_id( slack_integration_mapping.id, box_item=IntegrationMappingBoxItemSlack(id=folder.id) ) ``` ### Arguments integration_mapping_id `str` - An ID of an integration mapping. Example: "11235432" box_item `Optional[IntegrationMappingBoxItemSlack]` options `Optional[IntegrationMappingSlackOptions]` extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `IntegrationMapping`. Returns the updated integration mapping object. ## Delete Slack integration mapping Deletes a [Slack integration mapping](https://support.box.com/hc/en-us/articles/4415585987859-Box-as-the-Content-Layer-for-Slack). You need Admin or Co-Admin role to use this endpoint. This operation is performed by calling function `delete_slack_integration_mapping_by_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-integration-mappings-slack-id/). ``` user_client.integration_mappings.delete_slack_integration_mapping_by_id( slack_integration_mapping.id ) ``` ### Arguments integration_mapping_id `str` - An ID of an integration mapping. Example: "11235432" extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `None`. Empty body in response. ## List Teams integration mappings Lists [Teams integration mappings](https://support.box.com/hc/en-us/articles/360044681474-Using-Box-for-Teams) in a users' enterprise. You need Admin or Co-Admin role to use this endpoint. This operation is performed by calling function `get_teams_integration_mapping`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-integration-mappings-teams/). ``` user_client.integration_mappings.get_teams_integration_mapping() ``` ### Arguments partner_item_type `Optional[GetTeamsIntegrationMappingPartnerItemType]` - Mapped item type, for which the mapping should be returned. partner_item_id `Optional[str]` - ID of the mapped item, for which the mapping should be returned. box_item_id `Optional[str]` - Box item ID, for which the mappings should be returned. box_item_type `Optional[GetTeamsIntegrationMappingBoxItemType]` - Box item type, for which the mappings should be returned. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `IntegrationMappingsTeams`. Returns a collection of integration mappings. ## Create Teams integration mapping Creates a [Teams integration mapping](https://support.box.com/hc/en-us/articles/360044681474-Using-Box-for-Teams) by mapping a Teams channel to a Box item. You need Admin or Co-Admin role to use this endpoint. This operation is performed by calling function `create_teams_integration_mapping`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-integration-mappings-teams/). ``` user_client.integration_mappings.create_teams_integration_mapping( IntegrationMappingPartnerItemTeamsCreateRequest( type=IntegrationMappingPartnerItemTeamsCreateRequestTypeField.CHANNEL, id=partner_item_id, tenant_id=tenant_id, team_id=team_id, ), FolderReference(id=folder.id), ) ``` ### Arguments - partner_item `IntegrationMappingPartnerItemTeamsCreateRequest` - box_item `FolderReference` extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `IntegrationMappingTeams`. Returns the created integration mapping. ## Update Teams integration mapping Updates a [Teams integration mapping](https://support.box.com/hc/en-us/articles/360044681474-Using-Box-for-Teams). Supports updating the Box folder ID and options. You need Admin or Co-Admin role to use this endpoint. This operation is performed by calling function `update_teams_integration_mapping_by_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-integration-mappings-teams-id/). ``` user_client.integration_mappings.update_teams_integration_mapping_by_id( integration_mapping_id, box_item=FolderReference(id="1234567") ) ``` ### Arguments integration_mapping_id `str` - An ID of an integration mapping. Example: "11235432" box_item `Optional[FolderReference]` extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `IntegrationMappingTeams`. Returns the updated integration mapping object. ## Delete Teams integration mapping Deletes a [Teams integration mapping](https://support.box.com/hc/en-us/articles/360044681474-Using-Box-for-Teams). You need Admin or Co-Admin role to use this endpoint. This operation is performed by calling function `delete_teams_integration_mapping_by_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-integration-mappings-teams-id/). ``` user_client.integration_mappings.delete_teams_integration_mapping_by_id( integration_mapping_id ) ``` ### Arguments integration_mapping_id `str` - An ID of an integration mapping. Example: "11235432" extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `None`. Empty body in response. --- ### InvitesManager **Type:** page | **Section:** Additional Resources InvitesManager Create user invite Get user invite status Create user invite Invites an existing external user to join an enterprise. The… # InvitesManager - [Create user invite](#create-user-invite) - [Get user invite status](#get-user-invite-status) ## Create user invite Invites an existing external user to join an enterprise. The existing user can not be part of another enterprise and must already have a Box account. Once invited, the user will receive an email and are prompted to accept the invitation within the Box web application. This method requires the "Manage An Enterprise" scope enabled for the application, which can be enabled within the developer console. This operation is performed by calling function `createInvite`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-invites/). ``` await client.invites.createInvite({ enterprise: { id: currentUser.enterprise!.id!, } satisfies CreateInviteRequestBodyEnterpriseField, actionableBy: { login: email, } satisfies CreateInviteRequestBodyActionableByField, } satisfies CreateInviteRequestBody); ``` ### Arguments requestBody `CreateInviteRequestBody` - Request body of createInvite method optionalsInput `CreateInviteOptionalsInput` ### Returns This function returns a value of type `Invite`. Returns a new invite object. ## Get user invite status Returns the status of a user invite. This operation is performed by calling function `getInviteById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-invites-id/). ``` await client.invites.getInviteById(invitation.id); ``` ### Arguments inviteId `string` - The ID of an invite. Example: "213723" optionalsInput `GetInviteByIdOptionalsInput` ### Returns This function returns a value of type `Invite`. Returns an invite object. --- ### InvitesManager **Type:** page | **Section:** Additional Resources InvitesManager Create user invite Get user invite status Create user invite Invites an existing external user to join an enterprise. The… # InvitesManager - [Create user invite](#create-user-invite) - [Get user invite status](#get-user-invite-status) ## Create user invite Invites an existing external user to join an enterprise. The existing user can not be part of another enterprise and must already have a Box account. Once invited, the user will receive an email and are prompted to accept the invitation within the Box web application. This method requires the "Manage An Enterprise" scope enabled for the application, which can be enabled within the developer console. This operation is performed by calling function `create_invite`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-invites/). ``` client.invites.create_invite( CreateInviteEnterprise(id=current_user.enterprise.id), CreateInviteActionableBy(login=email), ) ``` ### Arguments enterprise `CreateInviteEnterprise` - The enterprise to invite the user to. actionable_by `CreateInviteActionableBy` - The user to invite. fields `Optional[List[str]]` - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `Invite`. Returns a new invite object. ## Get user invite status Returns the status of a user invite. This operation is performed by calling function `get_invite_by_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-invites-id/). ``` client.invites.get_invite_by_id(invitation.id) ``` ### Arguments invite_id `str` - The ID of an invite. Example: "213723" fields `Optional[List[str]]` - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `Invite`. Returns an invite object. --- ### IRecentItemsManager **Type:** page | **Section:** Additional Resources IRecentItemsManager List recently accessed items List recently accessed items Returns information about the recent items accessed by a user… # IRecentItemsManager - [List recently accessed items](#list-recently-accessed-items) ## List recently accessed items Returns information about the recent items accessed by a user, either in the last 90 days or up to the last 1000 items accessed. This operation is performed by calling function `GetRecentItems`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-recent-items/). ``` await client.RecentItems.GetRecentItemsAsync(); ``` ### Arguments queryParams `GetRecentItemsQueryParams` - Query parameters of getRecentItems method headers `GetRecentItemsHeaders` - Headers of getRecentItems method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `RecentItems`. Returns a list recent items access by a user. --- ### IRetentionPoliciesManager **Type:** page | **Section:** Additional Resources IRetentionPoliciesManager List retention policies Create retention policy Get retention policy Update retention policy Delete retention… # IRetentionPoliciesManager - [List retention policies](#list-retention-policies) - [Create retention policy](#create-retention-policy) - [Get retention policy](#get-retention-policy) - [Update retention policy](#update-retention-policy) - [Delete retention policy](#delete-retention-policy) ## List retention policies Retrieves all of the retention policies for an enterprise. This operation is performed by calling function `GetRetentionPolicies`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-retention-policies/). ``` await client.RetentionPolicies.GetRetentionPoliciesAsync(); ``` ### Arguments queryParams `GetRetentionPoliciesQueryParams` - Query parameters of getRetentionPolicies method headers `GetRetentionPoliciesHeaders` - Headers of getRetentionPolicies method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `RetentionPolicies`. Returns a list retention policies in the enterprise. ## Create retention policy Creates a retention policy. This operation is performed by calling function `CreateRetentionPolicy`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-retention-policies/). ``` await client.RetentionPolicies.CreateRetentionPolicyAsync(requestBody: new CreateRetentionPolicyRequestBody(policyName: retentionPolicyName, policyType: CreateRetentionPolicyRequestBodyPolicyTypeField.Finite, dispositionAction: CreateRetentionPolicyRequestBodyDispositionActionField.RemoveRetention) { AreOwnersNotified = true, CanOwnerExtendRetention = true, Description = retentionDescription, RetentionLength = "1", RetentionType = CreateRetentionPolicyRequestBodyRetentionTypeField.Modifiable }); ``` ### Arguments requestBody `CreateRetentionPolicyRequestBody` - Request body of createRetentionPolicy method headers `CreateRetentionPolicyHeaders` - Headers of createRetentionPolicy method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `RetentionPolicy`. Returns a new retention policy object. ## Get retention policy Retrieves a retention policy. This operation is performed by calling function `GetRetentionPolicyById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-retention-policies-id/). ``` await client.RetentionPolicies.GetRetentionPolicyByIdAsync(retentionPolicyId: retentionPolicy.Id); ``` ### Arguments retentionPolicyId `string` - The ID of the retention policy. Example: "982312" queryParams `GetRetentionPolicyByIdQueryParams` - Query parameters of getRetentionPolicyById method headers `GetRetentionPolicyByIdHeaders` - Headers of getRetentionPolicyById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `RetentionPolicy`. Returns the retention policy object. ## Update retention policy Updates a retention policy. This operation is performed by calling function `UpdateRetentionPolicyById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-retention-policies-id/). ``` await client.RetentionPolicies.UpdateRetentionPolicyByIdAsync(retentionPolicyId: retentionPolicy.Id, requestBody: new UpdateRetentionPolicyByIdRequestBody() { PolicyName = updatedRetentionPolicyName }); ``` ### Arguments retentionPolicyId `string` - The ID of the retention policy. Example: "982312" requestBody `UpdateRetentionPolicyByIdRequestBody` - Request body of updateRetentionPolicyById method headers `UpdateRetentionPolicyByIdHeaders` - Headers of updateRetentionPolicyById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `RetentionPolicy`. Returns the updated retention policy object. ## Delete retention policy Permanently deletes a retention policy. This operation is performed by calling function `DeleteRetentionPolicyById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-retention-policies-id/). ``` await client.RetentionPolicies.DeleteRetentionPolicyByIdAsync(retentionPolicyId: retentionPolicy.Id); ``` ### Arguments retentionPolicyId `string` - The ID of the retention policy. Example: "982312" headers `DeleteRetentionPolicyByIdHeaders` - Headers of deleteRetentionPolicyById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `null`. Returns an empty response when the policy has been deleted. --- ### IRetentionPolicyAssignmentsManager **Type:** page | **Section:** Additional Resources IRetentionPolicyAssignmentsManager List retention policy assignments Assign retention policy Get retention policy assignment Remove… # IRetentionPolicyAssignmentsManager - [List retention policy assignments](#list-retention-policy-assignments) - [Assign retention policy](#assign-retention-policy) - [Get retention policy assignment](#get-retention-policy-assignment) - [Remove retention policy assignment](#remove-retention-policy-assignment) - [Get files under retention](#get-files-under-retention) ## List retention policy assignments Returns a list of all retention policy assignments associated with a specified retention policy. This operation is performed by calling function `GetRetentionPolicyAssignments`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-retention-policies-id-assignments/). ``` await client.RetentionPolicyAssignments.GetRetentionPolicyAssignmentsAsync(retentionPolicyId: retentionPolicy.Id); ``` ### Arguments retentionPolicyId `string` - The ID of the retention policy. Example: "982312" queryParams `GetRetentionPolicyAssignmentsQueryParams` - Query parameters of getRetentionPolicyAssignments method headers `GetRetentionPolicyAssignmentsHeaders` - Headers of getRetentionPolicyAssignments method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `RetentionPolicyAssignments`. Returns a list of the retention policy assignments associated with the specified retention policy. ## Assign retention policy Assigns a retention policy to an item. This operation is performed by calling function `CreateRetentionPolicyAssignment`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-retention-policy-assignments/). ``` await client.RetentionPolicyAssignments.CreateRetentionPolicyAssignmentAsync(requestBody: new CreateRetentionPolicyAssignmentRequestBody(policyId: retentionPolicy.Id, assignTo: new CreateRetentionPolicyAssignmentRequestBodyAssignToField(type: CreateRetentionPolicyAssignmentRequestBodyAssignToTypeField.Folder) { Id = folder.Id })); ``` ### Arguments requestBody `CreateRetentionPolicyAssignmentRequestBody` - Request body of createRetentionPolicyAssignment method headers `CreateRetentionPolicyAssignmentHeaders` - Headers of createRetentionPolicyAssignment method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `RetentionPolicyAssignment`. Returns a new retention policy assignment object. ## Get retention policy assignment Retrieves a retention policy assignment. This operation is performed by calling function `GetRetentionPolicyAssignmentById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-retention-policy-assignments-id/). ``` await client.RetentionPolicyAssignments.GetRetentionPolicyAssignmentByIdAsync(retentionPolicyAssignmentId: retentionPolicyAssignment.Id); ``` ### Arguments retentionPolicyAssignmentId `string` - The ID of the retention policy assignment. Example: "1233123" queryParams `GetRetentionPolicyAssignmentByIdQueryParams` - Query parameters of getRetentionPolicyAssignmentById method headers `GetRetentionPolicyAssignmentByIdHeaders` - Headers of getRetentionPolicyAssignmentById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `RetentionPolicyAssignment`. Returns the retention policy assignment object. ## Remove retention policy assignment Removes a retention policy assignment applied to content. This operation is performed by calling function `DeleteRetentionPolicyAssignmentById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-retention-policy-assignments-id/). ``` await client.RetentionPolicyAssignments.DeleteRetentionPolicyAssignmentByIdAsync(retentionPolicyAssignmentId: retentionPolicyAssignment.Id); ``` ### Arguments retentionPolicyAssignmentId `string` - The ID of the retention policy assignment. Example: "1233123" headers `DeleteRetentionPolicyAssignmentByIdHeaders` - Headers of deleteRetentionPolicyAssignmentById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `null`. Returns an empty response when the policy assignment is successfully deleted. ## Get files under retention Returns a list of files under retention for a retention policy assignment. This operation is performed by calling function `GetFilesUnderRetentionPolicyAssignment`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-retention-policy-assignments-id-files-under-retention/). ``` await client.RetentionPolicyAssignments.GetFilesUnderRetentionPolicyAssignmentAsync(retentionPolicyAssignmentId: retentionPolicyAssignment.Id); ``` ### Arguments retentionPolicyAssignmentId `string` - The ID of the retention policy assignment. Example: "1233123" queryParams `GetFilesUnderRetentionPolicyAssignmentQueryParams` - Query parameters of getFilesUnderRetentionPolicyAssignment method headers `GetFilesUnderRetentionPolicyAssignmentHeaders` - Headers of getFilesUnderRetentionPolicyAssignment method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `FilesUnderRetention`. Returns a list of files under retention that are associated with the specified retention policy assignment. --- ### ISearchManager **Type:** page | **Section:** Additional Resources ISearchManager Query files/folders by metadata Search for content Query files/folders by metadata Create a search using SQL-like syntax to… # ISearchManager - [Query files/folders by metadata](#query-files-folders-by-metadata) - [Search for content](#search-for-content) ## Query files/folders by metadata Create a search using SQL-like syntax to return items that match specific metadata. By default, this endpoint returns only the most basic info about the items for which the query matches. To get additional fields for each item, including any of the metadata, use the `fields` attribute in the query. This operation is performed by calling function `SearchByMetadataQuery`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-metadata-queries-execute-read/). ``` await client.Search.SearchByMetadataQueryAsync(requestBody: new MetadataQuery(ancestorFolderId: "0", from: searchFrom) { Query = "name = :name AND age < :age AND birthDate >= :birthDate AND countryCode = :countryCode AND sports = :sports", QueryParams = new Dictionary<string, object>() { { "name", "John" }, { "age", 50 }, { "birthDate", "2001-01-01T02:20:10.120Z" }, { "countryCode", "US" }, { "sports", Array.AsReadOnly(new [] {"basketball","tennis"}) } } }); ``` ### Arguments requestBody `MetadataQuery` - Request body of searchByMetadataQuery method headers `SearchByMetadataQueryHeaders` - Headers of searchByMetadataQuery method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `MetadataQueryResults`. Returns a list of files and folders that match this metadata query. ## Search for content Searches for files, folders, web links, and shared files across the users content or across the entire enterprise. This operation is performed by calling function `SearchForContent`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-search/). *Currently we don't have an example for calling `SearchForContent` in integration tests* ### Arguments queryParams `SearchForContentQueryParams` - Query parameters of searchForContent method headers `SearchForContentHeaders` - Headers of searchForContent method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `SearchResultsOrSearchResultsWithSharedLinks`. Returns a collection of search results. If there are no matching search results, the `entries` array will be empty. --- ### ISessionTerminationManager **Type:** page | **Section:** Additional Resources ISessionTerminationManager Create jobs to terminate users session Create jobs to terminate user group session Create jobs to terminate users… # ISessionTerminationManager - [Create jobs to terminate users session](#create-jobs-to-terminate-users-session) - [Create jobs to terminate user group session](#create-jobs-to-terminate-user-group-session) ## Create jobs to terminate users session Validates the roles and permissions of the user, and creates asynchronous jobs to terminate the user's sessions. Returns the status for the POST request. This operation is performed by calling function `TerminateUsersSessions`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-users-terminate-sessions/). ``` await client.SessionTermination.TerminateUsersSessionsAsync(requestBody: new TerminateUsersSessionsRequestBody(userIds: Array.AsReadOnly(new [] {Utils.GetEnvVar("USER_ID")}), userLogins: Array.AsReadOnly(new [] {NullableUtils.Unwrap(user.Login)}))); ``` ### Arguments requestBody `TerminateUsersSessionsRequestBody` - Request body of terminateUsersSessions method headers `TerminateUsersSessionsHeaders` - Headers of terminateUsersSessions method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `SessionTerminationMessage`. Returns a message about the request status. ## Create jobs to terminate user group session Validates the roles and permissions of the group, and creates asynchronous jobs to terminate the group's sessions. Returns the status for the POST request. This operation is performed by calling function `TerminateGroupsSessions`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-groups-terminate-sessions/). ``` await client.SessionTermination.TerminateGroupsSessionsAsync(requestBody: new TerminateGroupsSessionsRequestBody(groupIds: Array.AsReadOnly(new [] {group.Id}))); ``` ### Arguments requestBody `TerminateGroupsSessionsRequestBody` - Request body of terminateGroupsSessions method headers `TerminateGroupsSessionsHeaders` - Headers of terminateGroupsSessions method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `SessionTerminationMessage`. Returns a message about the request status. --- ### ISharedLinksAppItemsManager **Type:** page | **Section:** Additional Resources ISharedLinksAppItemsManager Find app item for shared link Find app item for shared link Returns the app item represented by a shared link… # ISharedLinksAppItemsManager - [Find app item for shared link](#find-app-item-for-shared-link) ## Find app item for shared link Returns the app item represented by a shared link. The link can originate from the current enterprise or another. This operation is performed by calling function `FindAppItemForSharedLink`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-shared-items--app-items/). ``` await client.SharedLinksAppItems.FindAppItemForSharedLinkAsync(headers: new FindAppItemForSharedLinkHeaders(boxapi: string.Concat("shared_link=", appItemSharedLink))); ``` ### Arguments headers `FindAppItemForSharedLinkHeaders` - Headers of findAppItemForSharedLink method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `AppItem`. Returns a full app item resource if the shared link is valid and the user has access to it. --- ### ISharedLinksFilesManager **Type:** page | **Section:** Additional Resources ISharedLinksFilesManager Find file for shared link Get shared link for file Add shared link to file Update shared link on file Remove shared… # ISharedLinksFilesManager - [Find file for shared link](#find-file-for-shared-link) - [Get shared link for file](#get-shared-link-for-file) - [Add shared link to file](#add-shared-link-to-file) - [Update shared link on file](#update-shared-link-on-file) - [Remove shared link from file](#remove-shared-link-from-file) ## Find file for shared link Returns the file represented by a shared link. A shared file can be represented by a shared link, which can originate within the current enterprise or within another. This endpoint allows an application to retrieve information about a shared file when only given a shared link. The `shared_link_permission_options` array field can be returned by requesting it in the `fields` query parameter. This operation is performed by calling function `FindFileForSharedLink`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-shared-items/). ``` await userClient.SharedLinksFiles.FindFileForSharedLinkAsync(queryParams: new FindFileForSharedLinkQueryParams(), headers: new FindFileForSharedLinkHeaders(boxapi: string.Concat("shared_link=", NullableUtils.Unwrap(fileFromApi.SharedLink).Url, "&shared_link_password=Secret123@"))); ``` ### Arguments queryParams `FindFileForSharedLinkQueryParams` - Query parameters of findFileForSharedLink method headers `FindFileForSharedLinkHeaders` - Headers of findFileForSharedLink method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `FileFull`. Returns a full file resource if the shared link is valid and the user has access to it. ## Get shared link for file Gets the information for a shared link on a file. This operation is performed by calling function `GetSharedLinkForFile`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-files-id--get-shared-link/). ``` await client.SharedLinksFiles.GetSharedLinkForFileAsync(fileId: fileId, queryParams: new GetSharedLinkForFileQueryParams(fields: "shared_link")); ``` ### Arguments fileId `string` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" queryParams `GetSharedLinkForFileQueryParams` - Query parameters of getSharedLinkForFile method headers `GetSharedLinkForFileHeaders` - Headers of getSharedLinkForFile method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `FileFull`. Returns the base representation of a file with the additional shared link information. ## Add shared link to file Adds a shared link to a file. This operation is performed by calling function `AddShareLinkToFile`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-files-id--add-shared-link/). ``` await client.SharedLinksFiles.AddShareLinkToFileAsync(fileId: fileId, requestBody: new AddShareLinkToFileRequestBody() { SharedLink = new AddShareLinkToFileRequestBodySharedLinkField() { Access = AddShareLinkToFileRequestBodySharedLinkAccessField.Open, Password = "Secret123@" } }, queryParams: new AddShareLinkToFileQueryParams(fields: "shared_link")); ``` ### Arguments fileId `string` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" requestBody `AddShareLinkToFileRequestBody` - Request body of addShareLinkToFile method queryParams `AddShareLinkToFileQueryParams` - Query parameters of addShareLinkToFile method headers `AddShareLinkToFileHeaders` - Headers of addShareLinkToFile method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `FileFull`. Returns the base representation of a file with a new shared link attached. ## Update shared link on file Updates a shared link on a file. This operation is performed by calling function `UpdateSharedLinkOnFile`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-files-id--update-shared-link/). ``` await client.SharedLinksFiles.UpdateSharedLinkOnFileAsync(fileId: fileId, requestBody: new UpdateSharedLinkOnFileRequestBody() { SharedLink = new UpdateSharedLinkOnFileRequestBodySharedLinkField() { Access = UpdateSharedLinkOnFileRequestBodySharedLinkAccessField.Collaborators } }, queryParams: new UpdateSharedLinkOnFileQueryParams(fields: "shared_link")); ``` ### Arguments fileId `string` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" requestBody `UpdateSharedLinkOnFileRequestBody` - Request body of updateSharedLinkOnFile method queryParams `UpdateSharedLinkOnFileQueryParams` - Query parameters of updateSharedLinkOnFile method headers `UpdateSharedLinkOnFileHeaders` - Headers of updateSharedLinkOnFile method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `FileFull`. Returns a basic representation of the file, with the updated shared link attached. ## Remove shared link from file Removes a shared link from a file. This operation is performed by calling function `RemoveSharedLinkFromFile`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-files-id--remove-shared-link/). ``` await client.SharedLinksFiles.RemoveSharedLinkFromFileAsync(fileId: fileId, requestBody: new RemoveSharedLinkFromFileRequestBody() { SharedLink = null }, queryParams: new RemoveSharedLinkFromFileQueryParams(fields: "shared_link")); ``` ### Arguments fileId `string` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" requestBody `RemoveSharedLinkFromFileRequestBody` - Request body of removeSharedLinkFromFile method queryParams `RemoveSharedLinkFromFileQueryParams` - Query parameters of removeSharedLinkFromFile method headers `RemoveSharedLinkFromFileHeaders` - Headers of removeSharedLinkFromFile method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `FileFull`. Returns a basic representation of a file, with the shared link removed. --- ### ISharedLinksFoldersManager **Type:** page | **Section:** Additional Resources ISharedLinksFoldersManager Find folder for shared link Get shared link for folder Add shared link to folder Update shared link on folder… # ISharedLinksFoldersManager - [Find folder for shared link](#find-folder-for-shared-link) - [Get shared link for folder](#get-shared-link-for-folder) - [Add shared link to folder](#add-shared-link-to-folder) - [Update shared link on folder](#update-shared-link-on-folder) - [Remove shared link from folder](#remove-shared-link-from-folder) ## Find folder for shared link Return the folder represented by a shared link. A shared folder can be represented by a shared link, which can originate within the current enterprise or within another. This endpoint allows an application to retrieve information about a shared folder when only given a shared link. This operation is performed by calling function `FindFolderForSharedLink`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-shared-items--folders/). ``` await userClient.SharedLinksFolders.FindFolderForSharedLinkAsync(queryParams: new FindFolderForSharedLinkQueryParams(), headers: new FindFolderForSharedLinkHeaders(boxapi: string.Concat("shared_link=", NullableUtils.Unwrap(folderFromApi.SharedLink).Url, "&shared_link_password=Secret123@"))); ``` ### Arguments queryParams `FindFolderForSharedLinkQueryParams` - Query parameters of findFolderForSharedLink method headers `FindFolderForSharedLinkHeaders` - Headers of findFolderForSharedLink method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `FolderFull`. Returns a full folder resource if the shared link is valid and the user has access to it. ## Get shared link for folder Gets the information for a shared link on a folder. This operation is performed by calling function `GetSharedLinkForFolder`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-folders-id--get-shared-link/). ``` await client.SharedLinksFolders.GetSharedLinkForFolderAsync(folderId: folder.Id, queryParams: new GetSharedLinkForFolderQueryParams(fields: "shared_link")); ``` ### Arguments folderId `string` - The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. Example: "12345" queryParams `GetSharedLinkForFolderQueryParams` - Query parameters of getSharedLinkForFolder method headers `GetSharedLinkForFolderHeaders` - Headers of getSharedLinkForFolder method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `FolderFull`. Returns the base representation of a folder with the additional shared link information. ## Add shared link to folder Adds a shared link to a folder. This operation is performed by calling function `AddShareLinkToFolder`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-folders-id--add-shared-link/). ``` await client.SharedLinksFolders.AddShareLinkToFolderAsync(folderId: folder.Id, requestBody: new AddShareLinkToFolderRequestBody() { SharedLink = new AddShareLinkToFolderRequestBodySharedLinkField() { Access = AddShareLinkToFolderRequestBodySharedLinkAccessField.Open, Password = "Secret123@" } }, queryParams: new AddShareLinkToFolderQueryParams(fields: "shared_link")); ``` ### Arguments folderId `string` - The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. Example: "12345" requestBody `AddShareLinkToFolderRequestBody` - Request body of addShareLinkToFolder method queryParams `AddShareLinkToFolderQueryParams` - Query parameters of addShareLinkToFolder method headers `AddShareLinkToFolderHeaders` - Headers of addShareLinkToFolder method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `FolderFull`. Returns the base representation of a folder with a new shared link attached. ## Update shared link on folder Updates a shared link on a folder. This operation is performed by calling function `UpdateSharedLinkOnFolder`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-folders-id--update-shared-link/). ``` await client.SharedLinksFolders.UpdateSharedLinkOnFolderAsync(folderId: folder.Id, requestBody: new UpdateSharedLinkOnFolderRequestBody() { SharedLink = new UpdateSharedLinkOnFolderRequestBodySharedLinkField() { Access = UpdateSharedLinkOnFolderRequestBodySharedLinkAccessField.Collaborators } }, queryParams: new UpdateSharedLinkOnFolderQueryParams(fields: "shared_link")); ``` ### Arguments folderId `string` - The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. Example: "12345" requestBody `UpdateSharedLinkOnFolderRequestBody` - Request body of updateSharedLinkOnFolder method queryParams `UpdateSharedLinkOnFolderQueryParams` - Query parameters of updateSharedLinkOnFolder method headers `UpdateSharedLinkOnFolderHeaders` - Headers of updateSharedLinkOnFolder method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `FolderFull`. Returns a basic representation of the folder, with the updated shared link attached. ## Remove shared link from folder Removes a shared link from a folder. This operation is performed by calling function `RemoveSharedLinkFromFolder`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-folders-id--remove-shared-link/). ``` await client.SharedLinksFolders.RemoveSharedLinkFromFolderAsync(folderId: folder.Id, requestBody: new RemoveSharedLinkFromFolderRequestBody() { SharedLink = null }, queryParams: new RemoveSharedLinkFromFolderQueryParams(fields: "shared_link")); ``` ### Arguments folderId `string` - The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. Example: "12345" requestBody `RemoveSharedLinkFromFolderRequestBody` - Request body of removeSharedLinkFromFolder method queryParams `RemoveSharedLinkFromFolderQueryParams` - Query parameters of removeSharedLinkFromFolder method headers `RemoveSharedLinkFromFolderHeaders` - Headers of removeSharedLinkFromFolder method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `FolderFull`. Returns a basic representation of a folder, with the shared link removed. --- ### ISharedLinksWebLinksManager **Type:** page | **Section:** Additional Resources ISharedLinksWebLinksManager Find web link for shared link Get shared link for web link Add shared link to web link Update shared link on web… # ISharedLinksWebLinksManager - [Find web link for shared link](#find-web-link-for-shared-link) - [Get shared link for web link](#get-shared-link-for-web-link) - [Add shared link to web link](#add-shared-link-to-web-link) - [Update shared link on web link](#update-shared-link-on-web-link) - [Remove shared link from web link](#remove-shared-link-from-web-link) ## Find web link for shared link Returns the web link represented by a shared link. A shared web link can be represented by a shared link, which can originate within the current enterprise or within another. This endpoint allows an application to retrieve information about a shared web link when only given a shared link. This operation is performed by calling function `FindWebLinkForSharedLink`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-shared-items--web-links/). ``` await userClient.SharedLinksWebLinks.FindWebLinkForSharedLinkAsync(queryParams: new FindWebLinkForSharedLinkQueryParams(), headers: new FindWebLinkForSharedLinkHeaders(boxapi: string.Concat("shared_link=", NullableUtils.Unwrap(webLinkFromApi.SharedLink).Url, "&shared_link_password=Secret123@"))); ``` ### Arguments queryParams `FindWebLinkForSharedLinkQueryParams` - Query parameters of findWebLinkForSharedLink method headers `FindWebLinkForSharedLinkHeaders` - Headers of findWebLinkForSharedLink method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `WebLink`. Returns a full web link resource if the shared link is valid and the user has access to it. ## Get shared link for web link Gets the information for a shared link on a web link. This operation is performed by calling function `GetSharedLinkForWebLink`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-web-links-id--get-shared-link/). ``` await client.SharedLinksWebLinks.GetSharedLinkForWebLinkAsync(webLinkId: webLinkId, queryParams: new GetSharedLinkForWebLinkQueryParams(fields: "shared_link")); ``` ### Arguments webLinkId `string` - The ID of the web link. Example: "12345" queryParams `GetSharedLinkForWebLinkQueryParams` - Query parameters of getSharedLinkForWebLink method headers `GetSharedLinkForWebLinkHeaders` - Headers of getSharedLinkForWebLink method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `WebLink`. Returns the base representation of a web link with the additional shared link information. ## Add shared link to web link Adds a shared link to a web link. This operation is performed by calling function `AddShareLinkToWebLink`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-web-links-id--add-shared-link/). ``` await client.SharedLinksWebLinks.AddShareLinkToWebLinkAsync(webLinkId: webLinkId, requestBody: new AddShareLinkToWebLinkRequestBody() { SharedLink = new AddShareLinkToWebLinkRequestBodySharedLinkField() { Access = AddShareLinkToWebLinkRequestBodySharedLinkAccessField.Open, Password = "Secret123@" } }, queryParams: new AddShareLinkToWebLinkQueryParams(fields: "shared_link")); ``` ### Arguments webLinkId `string` - The ID of the web link. Example: "12345" requestBody `AddShareLinkToWebLinkRequestBody` - Request body of addShareLinkToWebLink method queryParams `AddShareLinkToWebLinkQueryParams` - Query parameters of addShareLinkToWebLink method headers `AddShareLinkToWebLinkHeaders` - Headers of addShareLinkToWebLink method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `WebLink`. Returns the base representation of a web link with a new shared link attached. ## Update shared link on web link Updates a shared link on a web link. This operation is performed by calling function `UpdateSharedLinkOnWebLink`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-web-links-id--update-shared-link/). ``` await client.SharedLinksWebLinks.UpdateSharedLinkOnWebLinkAsync(webLinkId: webLinkId, requestBody: new UpdateSharedLinkOnWebLinkRequestBody() { SharedLink = new UpdateSharedLinkOnWebLinkRequestBodySharedLinkField() { Access = UpdateSharedLinkOnWebLinkRequestBodySharedLinkAccessField.Collaborators } }, queryParams: new UpdateSharedLinkOnWebLinkQueryParams(fields: "shared_link")); ``` ### Arguments webLinkId `string` - The ID of the web link. Example: "12345" requestBody `UpdateSharedLinkOnWebLinkRequestBody` - Request body of updateSharedLinkOnWebLink method queryParams `UpdateSharedLinkOnWebLinkQueryParams` - Query parameters of updateSharedLinkOnWebLink method headers `UpdateSharedLinkOnWebLinkHeaders` - Headers of updateSharedLinkOnWebLink method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `WebLink`. Returns a basic representation of the web link, with the updated shared link attached. ## Remove shared link from web link Removes a shared link from a web link. This operation is performed by calling function `RemoveSharedLinkFromWebLink`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-web-links-id--remove-shared-link/). ``` await client.SharedLinksWebLinks.RemoveSharedLinkFromWebLinkAsync(webLinkId: webLinkId, requestBody: new RemoveSharedLinkFromWebLinkRequestBody() { SharedLink = null }, queryParams: new RemoveSharedLinkFromWebLinkQueryParams(fields: "shared_link")); ``` ### Arguments webLinkId `string` - The ID of the web link. Example: "12345" requestBody `RemoveSharedLinkFromWebLinkRequestBody` - Request body of removeSharedLinkFromWebLink method queryParams `RemoveSharedLinkFromWebLinkQueryParams` - Query parameters of removeSharedLinkFromWebLink method headers `RemoveSharedLinkFromWebLinkHeaders` - Headers of removeSharedLinkFromWebLink method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `WebLink`. Returns a basic representation of a web link, with the shared link removed. --- ### IShieldInformationBarrierReportsManager **Type:** page | **Section:** Additional Resources IShieldInformationBarrierReportsManager List shield information barrier reports Create shield information barrier report Get shield… # IShieldInformationBarrierReportsManager - [List shield information barrier reports](#list-shield-information-barrier-reports) - [Create shield information barrier report](#create-shield-information-barrier-report) - [Get shield information barrier report by ID](#get-shield-information-barrier-report-by-id) ## List shield information barrier reports Lists shield information barrier reports. This operation is performed by calling function `GetShieldInformationBarrierReports`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-shield-information-barrier-reports/). ``` await client.ShieldInformationBarrierReports.GetShieldInformationBarrierReportsAsync(queryParams: new GetShieldInformationBarrierReportsQueryParams(shieldInformationBarrierId: barrierId)); ``` ### Arguments queryParams `GetShieldInformationBarrierReportsQueryParams` - Query parameters of getShieldInformationBarrierReports method headers `GetShieldInformationBarrierReportsHeaders` - Headers of getShieldInformationBarrierReports method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `ShieldInformationBarrierReports`. Returns a paginated list of shield information barrier report objects. ## Create shield information barrier report Creates a shield information barrier report for a given barrier. This operation is performed by calling function `CreateShieldInformationBarrierReport`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-shield-information-barrier-reports/). ``` await client.ShieldInformationBarrierReports.CreateShieldInformationBarrierReportAsync(requestBody: new ShieldInformationBarrierReference() { ShieldInformationBarrier = new ShieldInformationBarrierBase() { Id = barrierId, Type = ShieldInformationBarrierBaseTypeField.ShieldInformationBarrier } }); ``` ### Arguments requestBody `ShieldInformationBarrierReference` - Request body of createShieldInformationBarrierReport method headers `CreateShieldInformationBarrierReportHeaders` - Headers of createShieldInformationBarrierReport method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `ShieldInformationBarrierReport`. Returns the shield information barrier report information object. ## Get shield information barrier report by ID Retrieves a shield information barrier report by its ID. This operation is performed by calling function `GetShieldInformationBarrierReportById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-shield-information-barrier-reports-id/). ``` await client.ShieldInformationBarrierReports.GetShieldInformationBarrierReportByIdAsync(shieldInformationBarrierReportId: NullableUtils.Unwrap(createdReport.Id)); ``` ### Arguments shieldInformationBarrierReportId `string` - The ID of the shield information barrier Report. Example: "3423" headers `GetShieldInformationBarrierReportByIdHeaders` - Headers of getShieldInformationBarrierReportById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `ShieldInformationBarrierReport`. Returns the shield information barrier report object. --- ### IShieldInformationBarrierSegmentMembersManager **Type:** page | **Section:** Additional Resources IShieldInformationBarrierSegmentMembersManager Get shield information barrier segment member by ID Delete shield information barrier segment… # IShieldInformationBarrierSegmentMembersManager - [Get shield information barrier segment member by ID](#get-shield-information-barrier-segment-member-by-id) - [Delete shield information barrier segment member by ID](#delete-shield-information-barrier-segment-member-by-id) - [List shield information barrier segment members](#list-shield-information-barrier-segment-members) - [Create shield information barrier segment member](#create-shield-information-barrier-segment-member) ## Get shield information barrier segment member by ID Retrieves a shield information barrier segment member by its ID. This operation is performed by calling function `GetShieldInformationBarrierSegmentMemberById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-shield-information-barrier-segment-members-id/). ``` await client.ShieldInformationBarrierSegmentMembers.GetShieldInformationBarrierSegmentMemberByIdAsync(shieldInformationBarrierSegmentMemberId: NullableUtils.Unwrap(segmentMember.Id)); ``` ### Arguments shieldInformationBarrierSegmentMemberId `string` - The ID of the shield information barrier segment Member. Example: "7815" headers `GetShieldInformationBarrierSegmentMemberByIdHeaders` - Headers of getShieldInformationBarrierSegmentMemberById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `ShieldInformationBarrierSegmentMember`. Returns the shield information barrier segment member object. ## Delete shield information barrier segment member by ID Deletes a shield information barrier segment member based on provided ID. This operation is performed by calling function `DeleteShieldInformationBarrierSegmentMemberById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-shield-information-barrier-segment-members-id/). ``` await client.ShieldInformationBarrierSegmentMembers.DeleteShieldInformationBarrierSegmentMemberByIdAsync(shieldInformationBarrierSegmentMemberId: NullableUtils.Unwrap(segmentMember.Id)); ``` ### Arguments shieldInformationBarrierSegmentMemberId `string` - The ID of the shield information barrier segment Member. Example: "7815" headers `DeleteShieldInformationBarrierSegmentMemberByIdHeaders` - Headers of deleteShieldInformationBarrierSegmentMemberById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `null`. Returns an empty response if the segment member was deleted successfully. ## List shield information barrier segment members Lists shield information barrier segment members based on provided segment IDs. This operation is performed by calling function `GetShieldInformationBarrierSegmentMembers`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-shield-information-barrier-segment-members/). ``` await client.ShieldInformationBarrierSegmentMembers.GetShieldInformationBarrierSegmentMembersAsync(queryParams: new GetShieldInformationBarrierSegmentMembersQueryParams(shieldInformationBarrierSegmentId: NullableUtils.Unwrap(segment.Id))); ``` ### Arguments queryParams `GetShieldInformationBarrierSegmentMembersQueryParams` - Query parameters of getShieldInformationBarrierSegmentMembers method headers `GetShieldInformationBarrierSegmentMembersHeaders` - Headers of getShieldInformationBarrierSegmentMembers method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `ShieldInformationBarrierSegmentMembers`. Returns a paginated list of shield information barrier segment member objects. ## Create shield information barrier segment member Creates a new shield information barrier segment member. This operation is performed by calling function `CreateShieldInformationBarrierSegmentMember`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-shield-information-barrier-segment-members/). ``` await client.ShieldInformationBarrierSegmentMembers.CreateShieldInformationBarrierSegmentMemberAsync(requestBody: new CreateShieldInformationBarrierSegmentMemberRequestBody(shieldInformationBarrierSegment: new CreateShieldInformationBarrierSegmentMemberRequestBodyShieldInformationBarrierSegmentField() { Id = NullableUtils.Unwrap(segment.Id), Type = CreateShieldInformationBarrierSegmentMemberRequestBodyShieldInformationBarrierSegmentTypeField.ShieldInformationBarrierSegment }, user: new UserBase(id: Utils.GetEnvVar(name: "USER_ID")))); ``` ### Arguments requestBody `CreateShieldInformationBarrierSegmentMemberRequestBody` - Request body of createShieldInformationBarrierSegmentMember method headers `CreateShieldInformationBarrierSegmentMemberHeaders` - Headers of createShieldInformationBarrierSegmentMember method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `ShieldInformationBarrierSegmentMember`. Returns a new shield information barrier segment member object. --- ### IShieldInformationBarrierSegmentRestrictionsManager **Type:** page | **Section:** Additional Resources IShieldInformationBarrierSegmentRestrictionsManager Get shield information barrier segment restriction by ID Delete shield information… # IShieldInformationBarrierSegmentRestrictionsManager - [Get shield information barrier segment restriction by ID](#get-shield-information-barrier-segment-restriction-by-id) - [Delete shield information barrier segment restriction by ID](#delete-shield-information-barrier-segment-restriction-by-id) - [List shield information barrier segment restrictions](#list-shield-information-barrier-segment-restrictions) - [Create shield information barrier segment restriction](#create-shield-information-barrier-segment-restriction) ## Get shield information barrier segment restriction by ID Retrieves a shield information barrier segment restriction based on provided ID. This operation is performed by calling function `GetShieldInformationBarrierSegmentRestrictionById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-shield-information-barrier-segment-restrictions-id/). ``` await client.ShieldInformationBarrierSegmentRestrictions.GetShieldInformationBarrierSegmentRestrictionByIdAsync(shieldInformationBarrierSegmentRestrictionId: segmentRestrictionId); ``` ### Arguments shieldInformationBarrierSegmentRestrictionId `string` - The ID of the shield information barrier segment Restriction. Example: "4563" headers `GetShieldInformationBarrierSegmentRestrictionByIdHeaders` - Headers of getShieldInformationBarrierSegmentRestrictionById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `ShieldInformationBarrierSegmentRestriction`. Returns the shield information barrier segment restriction object. ## Delete shield information barrier segment restriction by ID Delete shield information barrier segment restriction based on provided ID. This operation is performed by calling function `DeleteShieldInformationBarrierSegmentRestrictionById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-shield-information-barrier-segment-restrictions-id/). ``` await client.ShieldInformationBarrierSegmentRestrictions.DeleteShieldInformationBarrierSegmentRestrictionByIdAsync(shieldInformationBarrierSegmentRestrictionId: segmentRestrictionId); ``` ### Arguments shieldInformationBarrierSegmentRestrictionId `string` - The ID of the shield information barrier segment Restriction. Example: "4563" headers `DeleteShieldInformationBarrierSegmentRestrictionByIdHeaders` - Headers of deleteShieldInformationBarrierSegmentRestrictionById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `null`. Empty body in response. ## List shield information barrier segment restrictions Lists shield information barrier segment restrictions based on provided segment ID. This operation is performed by calling function `GetShieldInformationBarrierSegmentRestrictions`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-shield-information-barrier-segment-restrictions/). ``` await client.ShieldInformationBarrierSegmentRestrictions.GetShieldInformationBarrierSegmentRestrictionsAsync(queryParams: new GetShieldInformationBarrierSegmentRestrictionsQueryParams(shieldInformationBarrierSegmentId: segmentId)); ``` ### Arguments queryParams `GetShieldInformationBarrierSegmentRestrictionsQueryParams` - Query parameters of getShieldInformationBarrierSegmentRestrictions method headers `GetShieldInformationBarrierSegmentRestrictionsHeaders` - Headers of getShieldInformationBarrierSegmentRestrictions method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `ShieldInformationBarrierSegmentRestrictions`. Returns a paginated list of shield information barrier segment restriction objects. ## Create shield information barrier segment restriction Creates a shield information barrier segment restriction object. This operation is performed by calling function `CreateShieldInformationBarrierSegmentRestriction`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-shield-information-barrier-segment-restrictions/). ``` await client.ShieldInformationBarrierSegmentRestrictions.CreateShieldInformationBarrierSegmentRestrictionAsync(requestBody: new CreateShieldInformationBarrierSegmentRestrictionRequestBody(restrictedSegment: new CreateShieldInformationBarrierSegmentRestrictionRequestBodyRestrictedSegmentField() { Id = segmentToRestrictId, Type = CreateShieldInformationBarrierSegmentRestrictionRequestBodyRestrictedSegmentTypeField.ShieldInformationBarrierSegment }, shieldInformationBarrierSegment: new CreateShieldInformationBarrierSegmentRestrictionRequestBodyShieldInformationBarrierSegmentField() { Id = segmentId, Type = CreateShieldInformationBarrierSegmentRestrictionRequestBodyShieldInformationBarrierSegmentTypeField.ShieldInformationBarrierSegment }, type: CreateShieldInformationBarrierSegmentRestrictionRequestBodyTypeField.ShieldInformationBarrierSegmentRestriction)); ``` ### Arguments requestBody `CreateShieldInformationBarrierSegmentRestrictionRequestBody` - Request body of createShieldInformationBarrierSegmentRestriction method headers `CreateShieldInformationBarrierSegmentRestrictionHeaders` - Headers of createShieldInformationBarrierSegmentRestriction method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `ShieldInformationBarrierSegmentRestriction`. Returns the newly created Shield Information Barrier Segment Restriction object. --- ### IShieldInformationBarrierSegmentsManager **Type:** page | **Section:** Additional Resources IShieldInformationBarrierSegmentsManager Get shield information barrier segment with specified ID Delete shield information barrier segment… # IShieldInformationBarrierSegmentsManager - [Get shield information barrier segment with specified ID](#get-shield-information-barrier-segment-with-specified-id) - [Delete shield information barrier segment](#delete-shield-information-barrier-segment) - [Update shield information barrier segment with specified ID](#update-shield-information-barrier-segment-with-specified-id) - [List shield information barrier segments](#list-shield-information-barrier-segments) - [Create shield information barrier segment](#create-shield-information-barrier-segment) ## Get shield information barrier segment with specified ID Retrieves shield information barrier segment based on provided ID.. This operation is performed by calling function `GetShieldInformationBarrierSegmentById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-shield-information-barrier-segments-id/). ``` await client.ShieldInformationBarrierSegments.GetShieldInformationBarrierSegmentByIdAsync(shieldInformationBarrierSegmentId: segmentId); ``` ### Arguments shieldInformationBarrierSegmentId `string` - The ID of the shield information barrier segment. Example: "3423" headers `GetShieldInformationBarrierSegmentByIdHeaders` - Headers of getShieldInformationBarrierSegmentById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `ShieldInformationBarrierSegment`. Returns the shield information barrier segment object. ## Delete shield information barrier segment Deletes the shield information barrier segment based on provided ID. This operation is performed by calling function `DeleteShieldInformationBarrierSegmentById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-shield-information-barrier-segments-id/). ``` await client.ShieldInformationBarrierSegments.DeleteShieldInformationBarrierSegmentByIdAsync(shieldInformationBarrierSegmentId: segmentId); ``` ### Arguments shieldInformationBarrierSegmentId `string` - The ID of the shield information barrier segment. Example: "3423" headers `DeleteShieldInformationBarrierSegmentByIdHeaders` - Headers of deleteShieldInformationBarrierSegmentById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `null`. Empty body in response. ## Update shield information barrier segment with specified ID Updates the shield information barrier segment based on provided ID.. This operation is performed by calling function `UpdateShieldInformationBarrierSegmentById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-shield-information-barrier-segments-id/). ``` await client.ShieldInformationBarrierSegments.UpdateShieldInformationBarrierSegmentByIdAsync(shieldInformationBarrierSegmentId: segmentId, requestBody: new UpdateShieldInformationBarrierSegmentByIdRequestBody() { Description = updatedSegmentDescription }); ``` ### Arguments shieldInformationBarrierSegmentId `string` - The ID of the shield information barrier segment. Example: "3423" requestBody `UpdateShieldInformationBarrierSegmentByIdRequestBody` - Request body of updateShieldInformationBarrierSegmentById method headers `UpdateShieldInformationBarrierSegmentByIdHeaders` - Headers of updateShieldInformationBarrierSegmentById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `ShieldInformationBarrierSegment`. Returns the updated shield information barrier segment object. ## List shield information barrier segments Retrieves a list of shield information barrier segment objects for the specified Information Barrier ID. This operation is performed by calling function `GetShieldInformationBarrierSegments`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-shield-information-barrier-segments/). ``` await client.ShieldInformationBarrierSegments.GetShieldInformationBarrierSegmentsAsync(queryParams: new GetShieldInformationBarrierSegmentsQueryParams(shieldInformationBarrierId: barrierId)); ``` ### Arguments queryParams `GetShieldInformationBarrierSegmentsQueryParams` - Query parameters of getShieldInformationBarrierSegments method headers `GetShieldInformationBarrierSegmentsHeaders` - Headers of getShieldInformationBarrierSegments method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `ShieldInformationBarrierSegments`. Returns a paginated list of shield information barrier segment objects. ## Create shield information barrier segment Creates a shield information barrier segment. This operation is performed by calling function `CreateShieldInformationBarrierSegment`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-shield-information-barrier-segments/). ``` await client.ShieldInformationBarrierSegments.CreateShieldInformationBarrierSegmentAsync(requestBody: new CreateShieldInformationBarrierSegmentRequestBody(shieldInformationBarrier: new ShieldInformationBarrierBase() { Id = barrierId, Type = ShieldInformationBarrierBaseTypeField.ShieldInformationBarrier }, name: segmentName) { Description = segmentDescription }); ``` ### Arguments requestBody `CreateShieldInformationBarrierSegmentRequestBody` - Request body of createShieldInformationBarrierSegment method headers `CreateShieldInformationBarrierSegmentHeaders` - Headers of createShieldInformationBarrierSegment method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `ShieldInformationBarrierSegment`. Returns a new shield information barrier segment object. --- ### IShieldInformationBarriersManager **Type:** page | **Section:** Additional Resources IShieldInformationBarriersManager Get shield information barrier with specified ID Add changed status of shield information barrier with… # IShieldInformationBarriersManager - [Get shield information barrier with specified ID](#get-shield-information-barrier-with-specified-id) - [Add changed status of shield information barrier with specified ID](#add-changed-status-of-shield-information-barrier-with-specified-id) - [List shield information barriers](#list-shield-information-barriers) - [Create shield information barrier](#create-shield-information-barrier) ## Get shield information barrier with specified ID Get shield information barrier based on provided ID. This operation is performed by calling function `GetShieldInformationBarrierById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-shield-information-barriers-id/). ``` await client.ShieldInformationBarriers.GetShieldInformationBarrierByIdAsync(shieldInformationBarrierId: barrierId); ``` ### Arguments shieldInformationBarrierId `string` - The ID of the shield information barrier. Example: "1910967" headers `GetShieldInformationBarrierByIdHeaders` - Headers of getShieldInformationBarrierById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `ShieldInformationBarrier`. Returns the shield information barrier object. ## Add changed status of shield information barrier with specified ID Change status of shield information barrier with the specified ID. This operation is performed by calling function `UpdateShieldInformationBarrierStatus`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-shield-information-barriers-change-status/). ``` await client.ShieldInformationBarriers.UpdateShieldInformationBarrierStatusAsync(requestBody: new UpdateShieldInformationBarrierStatusRequestBody(id: barrierId, status: UpdateShieldInformationBarrierStatusRequestBodyStatusField.Disabled)); ``` ### Arguments requestBody `UpdateShieldInformationBarrierStatusRequestBody` - Request body of updateShieldInformationBarrierStatus method headers `UpdateShieldInformationBarrierStatusHeaders` - Headers of updateShieldInformationBarrierStatus method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `ShieldInformationBarrier`. Returns the updated shield information barrier object. ## List shield information barriers Retrieves a list of shield information barrier objects for the enterprise of JWT. This operation is performed by calling function `GetShieldInformationBarriers`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-shield-information-barriers/). ``` await client.ShieldInformationBarriers.GetShieldInformationBarriersAsync(); ``` ### Arguments queryParams `GetShieldInformationBarriersQueryParams` - Query parameters of getShieldInformationBarriers method headers `GetShieldInformationBarriersHeaders` - Headers of getShieldInformationBarriers method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `ShieldInformationBarriers`. Returns a paginated list of shield information barrier objects, empty list if currently no barrier. ## Create shield information barrier Creates a shield information barrier to separate individuals/groups within the same firm and prevents confidential information passing between them. This operation is performed by calling function `CreateShieldInformationBarrier`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-shield-information-barriers/). ``` await client.ShieldInformationBarriers.CreateShieldInformationBarrierAsync(requestBody: new CreateShieldInformationBarrierRequestBody(enterprise: new EnterpriseBase() { Id = enterpriseId })); ``` ### Arguments requestBody `CreateShieldInformationBarrierRequestBody` - Request body of createShieldInformationBarrier method headers `CreateShieldInformationBarrierHeaders` - Headers of createShieldInformationBarrier method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `ShieldInformationBarrier`. Returns a new shield information barrier object. --- ### IShieldListsManager **Type:** page | **Section:** Additional Resources IShieldListsManager Get all shield lists in enterprise Create shield list Get single shield list by shield list id Delete single shield list… # IShieldListsManager - [Get all shield lists in enterprise](#get-all-shield-lists-in-enterprise) - [Create shield list](#create-shield-list) - [Get single shield list by shield list id](#get-single-shield-list-by-shield-list-id) - [Delete single shield list by shield list id](#delete-single-shield-list-by-shield-list-id) - [Update shield list](#update-shield-list) ## Get all shield lists in enterprise Retrieves all shield lists in the enterprise. This operation is performed by calling function `GetShieldListsV2025R0`. See the endpoint docs at [API Reference](https://developer.box.com/reference/v2025.0/get-shield-lists/). ``` await client.ShieldLists.GetShieldListsV2025R0Async(); ``` ### Arguments headers `GetShieldListsV2025R0Headers` - Headers of getShieldListsV2025R0 method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `ShieldListsV2025R0`. Returns the list of shield list objects. ## Create shield list Creates a shield list. This operation is performed by calling function `CreateShieldListV2025R0`. See the endpoint docs at [API Reference](https://developer.box.com/reference/v2025.0/post-shield-lists/). ``` await client.ShieldLists.CreateShieldListV2025R0Async(requestBody: new ShieldListsCreateV2025R0(name: shieldListCountryName, content: new ShieldListContentCountryV2025R0(type: ShieldListContentCountryV2025R0TypeField.Country, countryCodes: Array.AsReadOnly(new [] {"US","PL"}))) { Description = "A list of things that are shielded" }); ``` ### Arguments requestBody `ShieldListsCreateV2025R0` - Request body of createShieldListV2025R0 method headers `CreateShieldListV2025R0Headers` - Headers of createShieldListV2025R0 method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `ShieldListV2025R0`. Returns the shield list object. ## Get single shield list by shield list id Retrieves a single shield list by its ID. This operation is performed by calling function `GetShieldListByIdV2025R0`. See the endpoint docs at [API Reference](https://developer.box.com/reference/v2025.0/get-shield-lists-id/). ``` await client.ShieldLists.GetShieldListByIdV2025R0Async(shieldListId: shieldListCountry.Id); ``` ### Arguments shieldListId `string` - The unique identifier that represents a shield list. The ID for any Shield List can be determined by the response from the endpoint fetching all shield lists for the enterprise. Example: "90fb0e17-c332-40ed-b4f9-fa8908fbbb24 " headers `GetShieldListByIdV2025R0Headers` - Headers of getShieldListByIdV2025R0 method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `ShieldListV2025R0`. Returns the shield list object. ## Delete single shield list by shield list id Delete a single shield list by its ID. This operation is performed by calling function `DeleteShieldListByIdV2025R0`. See the endpoint docs at [API Reference](https://developer.box.com/reference/v2025.0/delete-shield-lists-id/). ``` await client.ShieldLists.DeleteShieldListByIdV2025R0Async(shieldListId: shieldListCountry.Id); ``` ### Arguments shieldListId `string` - The unique identifier that represents a shield list. The ID for any Shield List can be determined by the response from the endpoint fetching all shield lists for the enterprise. Example: "90fb0e17-c332-40ed-b4f9-fa8908fbbb24 " headers `DeleteShieldListByIdV2025R0Headers` - Headers of deleteShieldListByIdV2025R0 method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `null`. Shield List correctly removed. No content in response. ## Update shield list Updates a shield list. This operation is performed by calling function `UpdateShieldListByIdV2025R0`. See the endpoint docs at [API Reference](https://developer.box.com/reference/v2025.0/put-shield-lists-id/). ``` await client.ShieldLists.UpdateShieldListByIdV2025R0Async(shieldListId: shieldListCountry.Id, requestBody: new ShieldListsUpdateV2025R0(name: shieldListCountryName, content: new ShieldListContentCountryV2025R0(type: ShieldListContentCountryV2025R0TypeField.Country, countryCodes: Array.AsReadOnly(new [] {"US"}))) { Description = "Updated description" }); ``` ### Arguments shieldListId `string` - The unique identifier that represents a shield list. The ID for any Shield List can be determined by the response from the endpoint fetching all shield lists for the enterprise. Example: "90fb0e17-c332-40ed-b4f9-fa8908fbbb24 " requestBody `ShieldListsUpdateV2025R0` - Request body of updateShieldListByIdV2025R0 method headers `UpdateShieldListByIdV2025R0Headers` - Headers of updateShieldListByIdV2025R0 method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `ShieldListV2025R0`. Returns the shield list object. --- ### ISignRequestsManager **Type:** page | **Section:** Additional Resources ISignRequestsManager Cancel Box Sign request Resend Box Sign request Get Box Sign request by ID List Box Sign requests Create Box Sign… # ISignRequestsManager - [Cancel Box Sign request](#cancel-box-sign-request) - [Resend Box Sign request](#resend-box-sign-request) - [Get Box Sign request by ID](#get-box-sign-request-by-id) - [List Box Sign requests](#list-box-sign-requests) - [Create Box Sign request](#create-box-sign-request) ## Cancel Box Sign request Cancels a sign request. This operation is performed by calling function `CancelSignRequest`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-sign-requests-id-cancel/). ``` await client.SignRequests.CancelSignRequestAsync(signRequestId: NullableUtils.Unwrap(createdSignRequest.Id)); ``` ### Arguments signRequestId `string` - The ID of the signature request. Example: "33243242" headers `CancelSignRequestHeaders` - Headers of cancelSignRequest method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `SignRequest`. Returns a Sign Request object. ## Resend Box Sign request Resends a signature request email to all outstanding signers. This operation is performed by calling function `ResendSignRequest`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-sign-requests-id-resend/). *Currently we don't have an example for calling `ResendSignRequest` in integration tests* ### Arguments signRequestId `string` - The ID of the signature request. Example: "33243242" headers `ResendSignRequestHeaders` - Headers of resendSignRequest method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `null`. Returns an empty response when the API call was successful. The email notifications will be sent asynchronously. ## Get Box Sign request by ID Gets a sign request by ID. This operation is performed by calling function `GetSignRequestById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-sign-requests-id/). ``` await client.SignRequests.GetSignRequestByIdAsync(signRequestId: NullableUtils.Unwrap(createdSignRequest.Id)); ``` ### Arguments signRequestId `string` - The ID of the signature request. Example: "33243242" headers `GetSignRequestByIdHeaders` - Headers of getSignRequestById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `SignRequest`. Returns a signature request. ## List Box Sign requests Gets signature requests created by a user. If the `sign_files` and/or `parent_folder` are deleted, the signature request will not return in the list. This operation is performed by calling function `GetSignRequests`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-sign-requests/). ``` await client.SignRequests.GetSignRequestsAsync(); ``` ### Arguments queryParams `GetSignRequestsQueryParams` - Query parameters of getSignRequests method headers `GetSignRequestsHeaders` - Headers of getSignRequests method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `SignRequests`. Returns a collection of sign requests. ## Create Box Sign request Creates a signature request. This involves preparing a document for signing and sending the signature request to signers. This operation is performed by calling function `CreateSignRequest`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-sign-requests/). ``` await client.SignRequests.CreateSignRequestAsync(requestBody: new SignRequestCreateRequest(signers: Array.AsReadOnly(new [] {new SignRequestCreateSigner() { Email = signerEmail, SuppressNotifications = true, DeclinedRedirectUrl = "https://www.box.com", EmbedUrlExternalUserId = "123", IsInPerson = false, LoginRequired = false, Password = "password", Role = SignRequestCreateSignerRoleField.Signer }}), areRemindersEnabled: true, areTextSignaturesEnabled: true, daysValid: 30, declinedRedirectUrl: "https://www.box.com", emailMessage: "Please sign this document", emailSubject: "Sign this document", externalId: "123", externalSystemName: "BoxSignIntegration", isDocumentPreparationNeeded: false, name: "Sign Request", parentFolder: new FolderMini(id: destinationFolder.Id), redirectUrl: "https://www.box.com", prefillTags: Array.AsReadOnly(new [] {new SignRequestPrefillTag() { DateValue = Utils.DateFromString(date: "2035-01-01"), DocumentTagId = "0" }}), sourceFiles: Array.AsReadOnly(new [] {new FileBase(id: fileToSign.Id)}))); ``` ### Arguments requestBody `SignRequestCreateRequest` - Request body of createSignRequest method headers `CreateSignRequestHeaders` - Headers of createSignRequest method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `SignRequest`. Returns a Box Sign request object. --- ### ISignTemplatesManager **Type:** page | **Section:** Additional Resources ISignTemplatesManager List Box Sign templates Get Box Sign template by ID List Box Sign templates Gets Box Sign templates created by a user… # ISignTemplatesManager - [List Box Sign templates](#list-box-sign-templates) - [Get Box Sign template by ID](#get-box-sign-template-by-id) ## List Box Sign templates Gets Box Sign templates created by a user. This operation is performed by calling function `GetSignTemplates`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-sign-templates/). ``` await client.SignTemplates.GetSignTemplatesAsync(queryParams: new GetSignTemplatesQueryParams() { Limit = 2 }); ``` ### Arguments queryParams `GetSignTemplatesQueryParams` - Query parameters of getSignTemplates method headers `GetSignTemplatesHeaders` - Headers of getSignTemplates method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `SignTemplates`. Returns a collection of templates. ## Get Box Sign template by ID Fetches details of a specific Box Sign template. This operation is performed by calling function `GetSignTemplateById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-sign-templates-id/). ``` await client.SignTemplates.GetSignTemplateByIdAsync(templateId: NullableUtils.Unwrap(NullableUtils.Unwrap(signTemplates.Entries)[0].Id)); ``` ### Arguments templateId `string` - The ID of a Box Sign template. Example: "123075213-7d117509-8f05-42e4-a5ef-5190a319d41d" headers `GetSignTemplateByIdHeaders` - Headers of getSignTemplateById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `SignTemplate`. Returns details of a template. --- ### ISkillsManager **Type:** page | **Section:** Additional Resources ISkillsManager List Box Skill cards on file Create Box Skill cards on file Update Box Skill cards on file Remove Box Skill cards from file… # ISkillsManager - [List Box Skill cards on file](#list-box-skill-cards-on-file) - [Create Box Skill cards on file](#create-box-skill-cards-on-file) - [Update Box Skill cards on file](#update-box-skill-cards-on-file) - [Remove Box Skill cards from file](#remove-box-skill-cards-from-file) - [Update all Box Skill cards on file](#update-all-box-skill-cards-on-file) ## List Box Skill cards on file List the Box Skills metadata cards that are attached to a file. This operation is performed by calling function `GetBoxSkillCardsOnFile`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-files-id-metadata-global-boxSkillsCards/). *Currently we don't have an example for calling `GetBoxSkillCardsOnFile` in integration tests* ### Arguments fileId `string` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" headers `GetBoxSkillCardsOnFileHeaders` - Headers of getBoxSkillCardsOnFile method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `SkillCardsMetadata`. Returns all the metadata associated with a file. This API does not support pagination and will therefore always return all of the metadata associated to the file. ## Create Box Skill cards on file Applies one or more Box Skills metadata cards to a file. This operation is performed by calling function `CreateBoxSkillCardsOnFile`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-files-id-metadata-global-boxSkillsCards/). *Currently we don't have an example for calling `CreateBoxSkillCardsOnFile` in integration tests* ### Arguments fileId `string` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" requestBody `CreateBoxSkillCardsOnFileRequestBody` - Request body of createBoxSkillCardsOnFile method headers `CreateBoxSkillCardsOnFileHeaders` - Headers of createBoxSkillCardsOnFile method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `SkillCardsMetadata`. Returns the instance of the template that was applied to the file, including the data that was applied to the template. ## Update Box Skill cards on file Updates one or more Box Skills metadata cards to a file. This operation is performed by calling function `UpdateBoxSkillCardsOnFile`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-files-id-metadata-global-boxSkillsCards/). *Currently we don't have an example for calling `UpdateBoxSkillCardsOnFile` in integration tests* ### Arguments fileId `string` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" requestBody `IReadOnlyList<UpdateBoxSkillCardsOnFileRequestBody>` - Request body of updateBoxSkillCardsOnFile method headers `UpdateBoxSkillCardsOnFileHeaders` - Headers of updateBoxSkillCardsOnFile method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `SkillCardsMetadata`. Returns the updated metadata template, with the custom template data included. ## Remove Box Skill cards from file Removes any Box Skills cards metadata from a file. This operation is performed by calling function `DeleteBoxSkillCardsFromFile`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-files-id-metadata-global-boxSkillsCards/). *Currently we don't have an example for calling `DeleteBoxSkillCardsFromFile` in integration tests* ### Arguments fileId `string` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" headers `DeleteBoxSkillCardsFromFileHeaders` - Headers of deleteBoxSkillCardsFromFile method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `null`. Returns an empty response when the cards are successfully deleted. ## Update all Box Skill cards on file An alternative method that can be used to overwrite and update all Box Skill metadata cards on a file. This operation is performed by calling function `UpdateAllSkillCardsOnFile`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-skill-invocations-id/). *Currently we don't have an example for calling `UpdateAllSkillCardsOnFile` in integration tests* ### Arguments skillId `string` - The ID of the skill to apply this metadata for. Example: "33243242" requestBody `UpdateAllSkillCardsOnFileRequestBody` - Request body of updateAllSkillCardsOnFile method headers `UpdateAllSkillCardsOnFileHeaders` - Headers of updateAllSkillCardsOnFile method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `null`. Returns an empty response when the card has been successfully updated. --- ### IStoragePoliciesManager **Type:** page | **Section:** Additional Resources IStoragePoliciesManager List storage policies Get storage policy List storage policies Fetches all the storage policies in the enterprise… # IStoragePoliciesManager - [List storage policies](#list-storage-policies) - [Get storage policy](#get-storage-policy) ## List storage policies Fetches all the storage policies in the enterprise. This operation is performed by calling function `GetStoragePolicies`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-storage-policies/). ``` await client.StoragePolicies.GetStoragePoliciesAsync(); ``` ### Arguments queryParams `GetStoragePoliciesQueryParams` - Query parameters of getStoragePolicies method headers `GetStoragePoliciesHeaders` - Headers of getStoragePolicies method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `StoragePolicies`. Returns a collection of storage policies. ## Get storage policy Fetches a specific storage policy. This operation is performed by calling function `GetStoragePolicyById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-storage-policies-id/). ``` await client.StoragePolicies.GetStoragePolicyByIdAsync(storagePolicyId: storagePolicy.Id); ``` ### Arguments storagePolicyId `string` - The ID of the storage policy. Example: "34342" headers `GetStoragePolicyByIdHeaders` - Headers of getStoragePolicyById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `StoragePolicy`. Returns a storage policy object. --- ### IStoragePolicyAssignmentsManager **Type:** page | **Section:** Additional Resources IStoragePolicyAssignmentsManager List storage policy assignments Assign storage policy Get storage policy assignment Update storage policy… # IStoragePolicyAssignmentsManager - [List storage policy assignments](#list-storage-policy-assignments) - [Assign storage policy](#assign-storage-policy) - [Get storage policy assignment](#get-storage-policy-assignment) - [Update storage policy assignment](#update-storage-policy-assignment) - [Unassign storage policy](#unassign-storage-policy) ## List storage policy assignments Fetches all the storage policy assignment for an enterprise or user. This operation is performed by calling function `GetStoragePolicyAssignments`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-storage-policy-assignments/). ``` await client.StoragePolicyAssignments.GetStoragePolicyAssignmentsAsync(queryParams: new GetStoragePolicyAssignmentsQueryParams(resolvedForType: GetStoragePolicyAssignmentsQueryParamsResolvedForTypeField.User, resolvedForId: userId)); ``` ### Arguments queryParams `GetStoragePolicyAssignmentsQueryParams` - Query parameters of getStoragePolicyAssignments method headers `GetStoragePolicyAssignmentsHeaders` - Headers of getStoragePolicyAssignments method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `StoragePolicyAssignments`. Returns a collection of storage policies for the enterprise or user. ## Assign storage policy Creates a storage policy assignment for an enterprise or user. This operation is performed by calling function `CreateStoragePolicyAssignment`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-storage-policy-assignments/). ``` await client.StoragePolicyAssignments.CreateStoragePolicyAssignmentAsync(requestBody: new CreateStoragePolicyAssignmentRequestBody(storagePolicy: new CreateStoragePolicyAssignmentRequestBodyStoragePolicyField(id: policyId), assignedTo: new CreateStoragePolicyAssignmentRequestBodyAssignedToField(id: userId, type: CreateStoragePolicyAssignmentRequestBodyAssignedToTypeField.User))); ``` ### Arguments requestBody `CreateStoragePolicyAssignmentRequestBody` - Request body of createStoragePolicyAssignment method headers `CreateStoragePolicyAssignmentHeaders` - Headers of createStoragePolicyAssignment method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `StoragePolicyAssignment`. Returns the new storage policy assignment created. ## Get storage policy assignment Fetches a specific storage policy assignment. This operation is performed by calling function `GetStoragePolicyAssignmentById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-storage-policy-assignments-id/). ``` await client.StoragePolicyAssignments.GetStoragePolicyAssignmentByIdAsync(storagePolicyAssignmentId: storagePolicyAssignment.Id); ``` ### Arguments storagePolicyAssignmentId `string` - The ID of the storage policy assignment. Example: "932483" headers `GetStoragePolicyAssignmentByIdHeaders` - Headers of getStoragePolicyAssignmentById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `StoragePolicyAssignment`. Returns a storage policy assignment object. ## Update storage policy assignment Updates a specific storage policy assignment. This operation is performed by calling function `UpdateStoragePolicyAssignmentById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-storage-policy-assignments-id/). ``` await client.StoragePolicyAssignments.UpdateStoragePolicyAssignmentByIdAsync(storagePolicyAssignmentId: storagePolicyAssignment.Id, requestBody: new UpdateStoragePolicyAssignmentByIdRequestBody(storagePolicy: new UpdateStoragePolicyAssignmentByIdRequestBodyStoragePolicyField(id: storagePolicy2.Id))); ``` ### Arguments storagePolicyAssignmentId `string` - The ID of the storage policy assignment. Example: "932483" requestBody `UpdateStoragePolicyAssignmentByIdRequestBody` - Request body of updateStoragePolicyAssignmentById method headers `UpdateStoragePolicyAssignmentByIdHeaders` - Headers of updateStoragePolicyAssignmentById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `StoragePolicyAssignment`. Returns an updated storage policy assignment object. ## Unassign storage policy Delete a storage policy assignment. Deleting a storage policy assignment on a user will have the user inherit the enterprise's default storage policy. There is a rate limit for calling this endpoint of only twice per user in a 24 hour time frame. This operation is performed by calling function `DeleteStoragePolicyAssignmentById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-storage-policy-assignments-id/). ``` await client.StoragePolicyAssignments.DeleteStoragePolicyAssignmentByIdAsync(storagePolicyAssignmentId: storagePolicyAssignment.Id); ``` ### Arguments storagePolicyAssignmentId `string` - The ID of the storage policy assignment. Example: "932483" headers `DeleteStoragePolicyAssignmentByIdHeaders` - Headers of deleteStoragePolicyAssignmentById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `null`. Returns an empty response when the storage policy assignment is successfully deleted. --- ### ITaskAssignmentsManager **Type:** page | **Section:** Additional Resources ITaskAssignmentsManager List task assignments Assign task Get task assignment Update task assignment Unassign task List task assignments… # ITaskAssignmentsManager - [List task assignments](#list-task-assignments) - [Assign task](#assign-task) - [Get task assignment](#get-task-assignment) - [Update task assignment](#update-task-assignment) - [Unassign task](#unassign-task) ## List task assignments Lists all of the assignments for a given task. This operation is performed by calling function `GetTaskAssignments`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-tasks-id-assignments/). ``` await client.TaskAssignments.GetTaskAssignmentsAsync(taskId: NullableUtils.Unwrap(task.Id)); ``` ### Arguments taskId `string` - The ID of the task. Example: "12345" headers `GetTaskAssignmentsHeaders` - Headers of getTaskAssignments method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `TaskAssignments`. Returns a collection of task assignment defining what task on a file has been assigned to which users and by who. ## Assign task Assigns a task to a user. A task can be assigned to more than one user by creating multiple assignments. This operation is performed by calling function `CreateTaskAssignment`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-task-assignments/). ``` await client.TaskAssignments.CreateTaskAssignmentAsync(requestBody: new CreateTaskAssignmentRequestBody(task: new CreateTaskAssignmentRequestBodyTaskField(type: CreateTaskAssignmentRequestBodyTaskTypeField.Task, id: NullableUtils.Unwrap(task.Id)), assignTo: new CreateTaskAssignmentRequestBodyAssignToField() { Id = currentUser.Id })); ``` ### Arguments requestBody `CreateTaskAssignmentRequestBody` - Request body of createTaskAssignment method headers `CreateTaskAssignmentHeaders` - Headers of createTaskAssignment method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `TaskAssignment`. Returns a new task assignment object. ## Get task assignment Retrieves information about a task assignment. This operation is performed by calling function `GetTaskAssignmentById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-task-assignments-id/). ``` await client.TaskAssignments.GetTaskAssignmentByIdAsync(taskAssignmentId: NullableUtils.Unwrap(taskAssignment.Id)); ``` ### Arguments taskAssignmentId `string` - The ID of the task assignment. Example: "12345" headers `GetTaskAssignmentByIdHeaders` - Headers of getTaskAssignmentById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `TaskAssignment`. Returns a task assignment, specifying who the task has been assigned to and by whom. ## Update task assignment Updates a task assignment. This endpoint can be used to update the state of a task assigned to a user. This operation is performed by calling function `UpdateTaskAssignmentById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-task-assignments-id/). ``` await client.TaskAssignments.UpdateTaskAssignmentByIdAsync(taskAssignmentId: NullableUtils.Unwrap(taskAssignment.Id), requestBody: new UpdateTaskAssignmentByIdRequestBody() { Message = "updated message", ResolutionState = UpdateTaskAssignmentByIdRequestBodyResolutionStateField.Approved }); ``` ### Arguments taskAssignmentId `string` - The ID of the task assignment. Example: "12345" requestBody `UpdateTaskAssignmentByIdRequestBody` - Request body of updateTaskAssignmentById method headers `UpdateTaskAssignmentByIdHeaders` - Headers of updateTaskAssignmentById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `TaskAssignment`. Returns the updated task assignment object. ## Unassign task Deletes a specific task assignment. This operation is performed by calling function `DeleteTaskAssignmentById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-task-assignments-id/). ``` await client.TaskAssignments.DeleteTaskAssignmentByIdAsync(taskAssignmentId: NullableUtils.Unwrap(taskAssignment.Id)); ``` ### Arguments taskAssignmentId `string` - The ID of the task assignment. Example: "12345" headers `DeleteTaskAssignmentByIdHeaders` - Headers of deleteTaskAssignmentById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `null`. Returns an empty response when the task assignment was successfully deleted. --- ### ITasksManager **Type:** page | **Section:** Additional Resources ITasksManager List tasks on file Create task Get task Update task Remove task List tasks on file Retrieves a list of all the tasks for a… # ITasksManager - [List tasks on file](#list-tasks-on-file) - [Create task](#create-task) - [Get task](#get-task) - [Update task](#update-task) - [Remove task](#remove-task) ## List tasks on file Retrieves a list of all the tasks for a file. This endpoint does not support pagination. This operation is performed by calling function `GetFileTasks`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-files-id-tasks/). ``` await client.Tasks.GetFileTasksAsync(fileId: file.Id); ``` ### Arguments fileId `string` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" headers `GetFileTasksHeaders` - Headers of getFileTasks method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `Tasks`. Returns a list of tasks on a file. If there are no tasks on this file an empty collection is returned instead. ## Create task Creates a single task on a file. This task is not assigned to any user and will need to be assigned separately. This operation is performed by calling function `CreateTask`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-tasks/). ``` await client.Tasks.CreateTaskAsync(requestBody: new CreateTaskRequestBody(item: new CreateTaskRequestBodyItemField() { Type = CreateTaskRequestBodyItemTypeField.File, Id = file.Id }) { Message = "test message", DueAt = dateTime, Action = CreateTaskRequestBodyActionField.Review, CompletionRule = CreateTaskRequestBodyCompletionRuleField.AllAssignees }); ``` ### Arguments requestBody `CreateTaskRequestBody` - Request body of createTask method headers `CreateTaskHeaders` - Headers of createTask method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `Task`. Returns the newly created task. ## Get task Retrieves information about a specific task. This operation is performed by calling function `GetTaskById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-tasks-id/). ``` await client.Tasks.GetTaskByIdAsync(taskId: NullableUtils.Unwrap(task.Id)); ``` ### Arguments taskId `string` - The ID of the task. Example: "12345" headers `GetTaskByIdHeaders` - Headers of getTaskById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `Task`. Returns a task object. ## Update task Updates a task. This can be used to update a task's configuration, or to update its completion state. This operation is performed by calling function `UpdateTaskById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-tasks-id/). ``` await client.Tasks.UpdateTaskByIdAsync(taskId: NullableUtils.Unwrap(task.Id), requestBody: new UpdateTaskByIdRequestBody() { Message = "updated message" }); ``` ### Arguments taskId `string` - The ID of the task. Example: "12345" requestBody `UpdateTaskByIdRequestBody` - Request body of updateTaskById method headers `UpdateTaskByIdHeaders` - Headers of updateTaskById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `Task`. Returns the updated task object. ## Remove task Removes a task from a file. This operation is performed by calling function `DeleteTaskById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-tasks-id/). ``` await client.Tasks.DeleteTaskByIdAsync(taskId: NullableUtils.Unwrap(task.Id)); ``` ### Arguments taskId `string` - The ID of the task. Example: "12345" headers `DeleteTaskByIdHeaders` - Headers of deleteTaskById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `null`. Returns an empty response when the task was successfully deleted. --- ### ITermsOfServicesManager **Type:** page | **Section:** Additional Resources ITermsOfServicesManager List terms of services Create terms of service Get terms of service Update terms of service List terms of services… # ITermsOfServicesManager - [List terms of services](#list-terms-of-services) - [Create terms of service](#create-terms-of-service) - [Get terms of service](#get-terms-of-service) - [Update terms of service](#update-terms-of-service) ## List terms of services Returns the current terms of service text and settings for the enterprise. This operation is performed by calling function `GetTermsOfService`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-terms-of-services/). ``` await client.TermsOfServices.GetTermsOfServiceAsync(); ``` ### Arguments queryParams `GetTermsOfServiceQueryParams` - Query parameters of getTermsOfService method headers `GetTermsOfServiceHeaders` - Headers of getTermsOfService method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `TermsOfServices`. Returns a collection of terms of service text and settings for the enterprise. ## Create terms of service Creates a terms of service for a given enterprise and type of user. This operation is performed by calling function `CreateTermsOfService`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-terms-of-services/). ``` await client.TermsOfServices.CreateTermsOfServiceAsync(requestBody: new CreateTermsOfServiceRequestBody(status: CreateTermsOfServiceRequestBodyStatusField.Disabled, text: "Test TOS") { TosType = CreateTermsOfServiceRequestBodyTosTypeField.Managed }); ``` ### Arguments requestBody `CreateTermsOfServiceRequestBody` - Request body of createTermsOfService method headers `CreateTermsOfServiceHeaders` - Headers of createTermsOfService method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `TermsOfService`. Returns a new task object. ## Get terms of service Fetches a specific terms of service. This operation is performed by calling function `GetTermsOfServiceById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-terms-of-services-id/). *Currently we don't have an example for calling `GetTermsOfServiceById` in integration tests* ### Arguments termsOfServiceId `string` - The ID of the terms of service. Example: "324234" headers `GetTermsOfServiceByIdHeaders` - Headers of getTermsOfServiceById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `TermsOfService`. Returns a terms of service object. ## Update terms of service Updates a specific terms of service. This operation is performed by calling function `UpdateTermsOfServiceById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-terms-of-services-id/). ``` await client.TermsOfServices.UpdateTermsOfServiceByIdAsync(termsOfServiceId: tos.Id, requestBody: new UpdateTermsOfServiceByIdRequestBody(status: UpdateTermsOfServiceByIdRequestBodyStatusField.Disabled, text: "TOS")); ``` ### Arguments termsOfServiceId `string` - The ID of the terms of service. Example: "324234" requestBody `UpdateTermsOfServiceByIdRequestBody` - Request body of updateTermsOfServiceById method headers `UpdateTermsOfServiceByIdHeaders` - Headers of updateTermsOfServiceById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `TermsOfService`. Returns an updated terms of service object. --- ### ITermsOfServiceUserStatusesManager **Type:** page | **Section:** Additional Resources ITermsOfServiceUserStatusesManager List terms of service user statuses Create terms of service status for new user Update terms of service… # ITermsOfServiceUserStatusesManager - [List terms of service user statuses](#list-terms-of-service-user-statuses) - [Create terms of service status for new user](#create-terms-of-service-status-for-new-user) - [Update terms of service status for existing user](#update-terms-of-service-status-for-existing-user) ## List terms of service user statuses Retrieves an overview of users and their status for a terms of service, including Whether they have accepted the terms and when. This operation is performed by calling function `GetTermsOfServiceUserStatuses`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-terms-of-service-user-statuses/). ``` await client.TermsOfServiceUserStatuses.GetTermsOfServiceUserStatusesAsync(queryParams: new GetTermsOfServiceUserStatusesQueryParams(tosId: tos.Id) { UserId = user.Id }); ``` ### Arguments queryParams `GetTermsOfServiceUserStatusesQueryParams` - Query parameters of getTermsOfServiceUserStatuses method headers `GetTermsOfServiceUserStatusesHeaders` - Headers of getTermsOfServiceUserStatuses method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `TermsOfServiceUserStatuses`. Returns a list of terms of service statuses. ## Create terms of service status for new user Sets the status for a terms of service for a user. This operation is performed by calling function `CreateTermsOfServiceStatusForUser`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-terms-of-service-user-statuses/). ``` await client.TermsOfServiceUserStatuses.CreateTermsOfServiceStatusForUserAsync(requestBody: new CreateTermsOfServiceStatusForUserRequestBody(tos: new CreateTermsOfServiceStatusForUserRequestBodyTosField(id: tos.Id), user: new CreateTermsOfServiceStatusForUserRequestBodyUserField(id: user.Id), isAccepted: false)); ``` ### Arguments requestBody `CreateTermsOfServiceStatusForUserRequestBody` - Request body of createTermsOfServiceStatusForUser method headers `CreateTermsOfServiceStatusForUserHeaders` - Headers of createTermsOfServiceStatusForUser method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `TermsOfServiceUserStatus`. Returns a terms of service status object. ## Update terms of service status for existing user Updates the status for a terms of service for a user. This operation is performed by calling function `UpdateTermsOfServiceStatusForUserById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-terms-of-service-user-statuses-id/). ``` await client.TermsOfServiceUserStatuses.UpdateTermsOfServiceStatusForUserByIdAsync(termsOfServiceUserStatusId: createdTosUserStatus.Id, requestBody: new UpdateTermsOfServiceStatusForUserByIdRequestBody(isAccepted: true)); ``` ### Arguments termsOfServiceUserStatusId `string` - The ID of the terms of service status. Example: "324234" requestBody `UpdateTermsOfServiceStatusForUserByIdRequestBody` - Request body of updateTermsOfServiceStatusForUserById method headers `UpdateTermsOfServiceStatusForUserByIdHeaders` - Headers of updateTermsOfServiceStatusForUserById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `TermsOfServiceUserStatus`. Returns the updated terms of service status object. --- ### ITransferManager **Type:** page | **Section:** Additional Resources ITransferManager Transfer owned folders Transfer owned folders Move all of the items (files, folders and workflows) owned by a user into… # ITransferManager - [Transfer owned folders](#transfer-owned-folders) ## Transfer owned folders Move all of the items (files, folders and workflows) owned by a user into another user's account Only the root folder (`0`) can be transferred. Folders can only be moved across users by users with administrative permissions. All existing shared links and folder-level collaborations are transferred during the operation. Please note that while collaborations at the individual file-level are transferred during the operation, the collaborations are deleted when the original user is deleted. If the user has a large number of items across all folders, the call will be run asynchronously. If the operation is not completed within 10 minutes, the user will receive a 200 OK response, and the operation will continue running. If the destination path has a metadata cascade policy attached to any of the parent folders, a metadata cascade operation will be kicked off asynchronously. There is currently no way to check for when this operation is finished. The destination folder's name will be in the format `{User}'s Files and Folders`, where `{User}` is the display name of the user. To make this API call your application will need to have the "Read and write all files and folders stored in Box" scope enabled. Please make sure the destination user has access to `Relay` or `Relay Lite`, and has access to the files and folders involved in the workflows being transferred. Admins will receive an email when the operation is completed. This operation is performed by calling function `TransferOwnedFolder`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-users-id-folders-0/). ``` await client.Transfer.TransferOwnedFolderAsync(userId: sourceUser.Id, requestBody: new TransferOwnedFolderRequestBody(ownedBy: new TransferOwnedFolderRequestBodyOwnedByField(id: targetUser.Id)), queryParams: new TransferOwnedFolderQueryParams() { Notify = false }); ``` ### Arguments userId `string` - The ID of the user. Example: "12345" requestBody `TransferOwnedFolderRequestBody` - Request body of transferOwnedFolder method queryParams `TransferOwnedFolderQueryParams` - Query parameters of transferOwnedFolder method headers `TransferOwnedFolderHeaders` - Headers of transferOwnedFolder method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `FolderFull`. Returns the information for the newly created destination folder. --- ### ITrashedFilesManager **Type:** page | **Section:** Additional Resources ITrashedFilesManager Restore file Get trashed file Permanently remove file Restore file Restores a file that has been moved to the trash. An… # ITrashedFilesManager - [Restore file](#restore-file) - [Get trashed file](#get-trashed-file) - [Permanently remove file](#permanently-remove-file) ## Restore file Restores a file that has been moved to the trash. An optional new parent ID can be provided to restore the file to in case the original folder has been deleted. This operation is performed by calling function `RestoreFileFromTrash`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-files-id/). ``` await client.TrashedFiles.RestoreFileFromTrashAsync(fileId: file.Id); ``` ### Arguments fileId `string` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" requestBody `RestoreFileFromTrashRequestBody` - Request body of restoreFileFromTrash method queryParams `RestoreFileFromTrashQueryParams` - Query parameters of restoreFileFromTrash method headers `RestoreFileFromTrashHeaders` - Headers of restoreFileFromTrash method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `TrashFileRestored`. Returns a file object when the file has been restored. ## Get trashed file Retrieves a file that has been moved to the trash. Please note that only if the file itself has been moved to the trash can it be retrieved with this API call. If instead one of its parent folders was moved to the trash, only that folder can be inspected using the [`GET /folders/:id/trash`](e://get_folders_id_trash) API. To list all items that have been moved to the trash, please use the [`GET /folders/trash/items`](e://get-folders-trash-items/) API. This operation is performed by calling function `GetTrashedFileById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-files-id-trash/). ``` await client.TrashedFiles.GetTrashedFileByIdAsync(fileId: file.Id); ``` ### Arguments fileId `string` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" queryParams `GetTrashedFileByIdQueryParams` - Query parameters of getTrashedFileById method headers `GetTrashedFileByIdHeaders` - Headers of getTrashedFileById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `TrashFile`. Returns the file that was trashed, including information about when the it was moved to the trash. ## Permanently remove file Permanently deletes a file that is in the trash. This action cannot be undone. This operation is performed by calling function `DeleteTrashedFileById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-files-id-trash/). ``` await client.TrashedFiles.DeleteTrashedFileByIdAsync(fileId: file.Id); ``` ### Arguments fileId `string` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" headers `DeleteTrashedFileByIdHeaders` - Headers of deleteTrashedFileById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `null`. Returns an empty response when the file was permanently deleted. --- ### ITrashedFoldersManager **Type:** page | **Section:** Additional Resources ITrashedFoldersManager Restore folder Get trashed folder Permanently remove folder Restore folder Restores a folder that has been moved to… # ITrashedFoldersManager - [Restore folder](#restore-folder) - [Get trashed folder](#get-trashed-folder) - [Permanently remove folder](#permanently-remove-folder) ## Restore folder Restores a folder that has been moved to the trash. An optional new parent ID can be provided to restore the folder to in case the original folder has been deleted. During this operation, part of the file tree will be locked, mainly the source folder and all of its descendants, as well as the destination folder. For the duration of the operation, no other move, copy, delete, or restore operation can performed on any of the locked folders. This operation is performed by calling function `RestoreFolderFromTrash`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-folders-id/). ``` await client.TrashedFolders.RestoreFolderFromTrashAsync(folderId: folder.Id); ``` ### Arguments folderId `string` - The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. Example: "12345" requestBody `RestoreFolderFromTrashRequestBody` - Request body of restoreFolderFromTrash method queryParams `RestoreFolderFromTrashQueryParams` - Query parameters of restoreFolderFromTrash method headers `RestoreFolderFromTrashHeaders` - Headers of restoreFolderFromTrash method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `TrashFolderRestored`. Returns a folder object when the folder has been restored. ## Get trashed folder Retrieves a folder that has been moved to the trash. Please note that only if the folder itself has been moved to the trash can it be retrieved with this API call. If instead one of its parent folders was moved to the trash, only that folder can be inspected using the [`GET /folders/:id/trash`](e://get_folders_id_trash) API. To list all items that have been moved to the trash, please use the [`GET /folders/trash/items`](e://get-folders-trash-items/) API. This operation is performed by calling function `GetTrashedFolderById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-folders-id-trash/). ``` await client.TrashedFolders.GetTrashedFolderByIdAsync(folderId: folder.Id); ``` ### Arguments folderId `string` - The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. Example: "12345" queryParams `GetTrashedFolderByIdQueryParams` - Query parameters of getTrashedFolderById method headers `GetTrashedFolderByIdHeaders` - Headers of getTrashedFolderById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `TrashFolder`. Returns the folder that was trashed, including information about when the it was moved to the trash. ## Permanently remove folder Permanently deletes a folder that is in the trash. This action cannot be undone. This operation is performed by calling function `DeleteTrashedFolderById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-folders-id-trash/). ``` await client.TrashedFolders.DeleteTrashedFolderByIdAsync(folderId: folder.Id); ``` ### Arguments folderId `string` - The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. Example: "12345" headers `DeleteTrashedFolderByIdHeaders` - Headers of deleteTrashedFolderById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `null`. Returns an empty response when the folder was permanently deleted. --- ### ITrashedItemsManager **Type:** page | **Section:** Additional Resources ITrashedItemsManager List trashed items List trashed items Retrieves the files and folders that have been moved to the trash. Any attribute… # ITrashedItemsManager - [List trashed items](#list-trashed-items) ## List trashed items Retrieves the files and folders that have been moved to the trash. Any attribute in the full files or folders objects can be passed in with the `fields` parameter to retrieve those specific attributes that are not returned by default. This endpoint defaults to use offset-based pagination, yet also supports marker-based pagination using the `marker` parameter. This operation is performed by calling function `GetTrashedItems`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-folders-trash-items/). ``` await client.TrashedItems.GetTrashedItemsAsync(); ``` ### Arguments queryParams `GetTrashedItemsQueryParams` - Query parameters of getTrashedItems method headers `GetTrashedItemsHeaders` - Headers of getTrashedItems method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `Items`. Returns a list of items that have been deleted. --- ### ITrashedWebLinksManager **Type:** page | **Section:** Additional Resources ITrashedWebLinksManager Restore web link Get trashed web link Permanently remove web link Restore web link Restores a web link that has been… # ITrashedWebLinksManager - [Restore web link](#restore-web-link) - [Get trashed web link](#get-trashed-web-link) - [Permanently remove web link](#permanently-remove-web-link) ## Restore web link Restores a web link that has been moved to the trash. An optional new parent ID can be provided to restore the web link to in case the original folder has been deleted. This operation is performed by calling function `RestoreWeblinkFromTrash`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-web-links-id/). ``` await client.TrashedWebLinks.RestoreWeblinkFromTrashAsync(webLinkId: weblink.Id); ``` ### Arguments webLinkId `string` - The ID of the web link. Example: "12345" requestBody `RestoreWeblinkFromTrashRequestBody` - Request body of restoreWeblinkFromTrash method queryParams `RestoreWeblinkFromTrashQueryParams` - Query parameters of restoreWeblinkFromTrash method headers `RestoreWeblinkFromTrashHeaders` - Headers of restoreWeblinkFromTrash method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `TrashWebLinkRestored`. Returns a web link object when it has been restored. ## Get trashed web link Retrieves a web link that has been moved to the trash. This operation is performed by calling function `GetTrashedWebLinkById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-web-links-id-trash/). ``` await client.TrashedWebLinks.GetTrashedWebLinkByIdAsync(webLinkId: weblink.Id); ``` ### Arguments webLinkId `string` - The ID of the web link. Example: "12345" queryParams `GetTrashedWebLinkByIdQueryParams` - Query parameters of getTrashedWebLinkById method headers `GetTrashedWebLinkByIdHeaders` - Headers of getTrashedWebLinkById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `TrashWebLink`. Returns the web link that was trashed, including information about when the it was moved to the trash. ## Permanently remove web link Permanently deletes a web link that is in the trash. This action cannot be undone. This operation is performed by calling function `DeleteTrashedWebLinkById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-web-links-id-trash/). ``` await client.TrashedWebLinks.DeleteTrashedWebLinkByIdAsync(webLinkId: weblink.Id); ``` ### Arguments webLinkId `string` - The ID of the web link. Example: "12345" headers `DeleteTrashedWebLinkByIdHeaders` - Headers of deleteTrashedWebLinkById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `null`. Returns an empty response when the web link was permanently deleted. --- ### IUploadsManager **Type:** page | **Section:** Additional Resources IUploadsManager Upload file version Preflight check before upload Upload file Upload a file with a preflight check Upload file version… # IUploadsManager - [Upload file version](#upload-file-version) - [Preflight check before upload](#preflight-check-before-upload) - [Upload file](#upload-file) - [Upload a file with a preflight check](#upload-a-file-with-a-preflight-check) ## Upload file version Update a file's content. For file sizes over 50MB we recommend using the Chunk Upload APIs. The `attributes` part of the body must come **before** the `file` part. Requests that do not follow this format when uploading the file will receive a HTTP `400` error with a `metadata_after_file_contents` error code. This operation is performed by calling function `UploadFileVersion`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-files-id-content/). ``` await client.Uploads.UploadFileVersionAsync(fileId: uploadedFile.Id, requestBody: new UploadFileVersionRequestBody(attributes: new UploadFileVersionRequestBodyAttributesField(name: newFileVersionName), file: newFileContentStream)); ``` ### Arguments fileId `string` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" requestBody `UploadFileVersionRequestBody` - Request body of uploadFileVersion method queryParams `UploadFileVersionQueryParams` - Query parameters of uploadFileVersion method headers `UploadFileVersionHeaders` - Headers of uploadFileVersion method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `Files`. Returns the new file object in a list. ## Preflight check before upload Performs a check to verify that a file will be accepted by Box before you upload the entire file. This operation is performed by calling function `PreflightFileUploadCheck`. See the endpoint docs at [API Reference](https://developer.box.com/reference/options-files-content/). ``` await client.Uploads.PreflightFileUploadCheckAsync(requestBody: new PreflightFileUploadCheckRequestBody() { Name = newFileName, Size = 1024 * 1024, Parent = new PreflightFileUploadCheckRequestBodyParentField() { Id = "0" } }); ``` ### Arguments requestBody `PreflightFileUploadCheckRequestBody` - Request body of preflightFileUploadCheck method headers `PreflightFileUploadCheckHeaders` - Headers of preflightFileUploadCheck method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `UploadUrl`. If the check passed, the response will include a session URL that can be used to upload the file to. ## Upload file Uploads a small file to Box. For file sizes over 50MB we recommend using the Chunk Upload APIs. The `attributes` part of the body must come **before** the `file` part. Requests that do not follow this format when uploading the file will receive a HTTP `400` error with a `metadata_after_file_contents` error code. This operation is performed by calling function `UploadFile`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-files-content/). ``` await client.Uploads.UploadFileAsync(requestBody: new UploadFileRequestBody(attributes: new UploadFileRequestBodyAttributesField(name: newFileName, parent: new UploadFileRequestBodyAttributesParentField(id: "0")), file: fileContentStream)); ``` ### Arguments requestBody `UploadFileRequestBody` - Request body of uploadFile method queryParams `UploadFileQueryParams` - Query parameters of uploadFile method headers `UploadFileHeaders` - Headers of uploadFile method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `Files`. Returns the new file object in a list. ## Upload a file with a preflight check Upload a file with a preflight check This operation is performed by calling function `UploadWithPreflightCheck`. ``` await client.Uploads.UploadWithPreflightCheckAsync(requestBody: new UploadWithPreflightCheckRequestBody(attributes: new UploadWithPreflightCheckRequestBodyAttributesField(name: newFileName, size: -1, parent: new UploadWithPreflightCheckRequestBodyAttributesParentField(id: "0")), file: fileContentStream)); ``` ### Arguments requestBody `UploadWithPreflightCheckRequestBody` queryParams `UploadWithPreflightCheckQueryParams` - Query parameters of uploadFile method headers `UploadWithPreflightCheckHeaders` - Headers of uploadFile method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `Files`. --- ### IUserCollaborationsManager **Type:** page | **Section:** Additional Resources IUserCollaborationsManager Get collaboration Update collaboration Remove collaboration Create collaboration Get collaboration Retrieves a… # IUserCollaborationsManager - [Get collaboration](#get-collaboration) - [Update collaboration](#update-collaboration) - [Remove collaboration](#remove-collaboration) - [Create collaboration](#create-collaboration) ## Get collaboration Retrieves a single collaboration. This operation is performed by calling function `GetCollaborationById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-collaborations-id/). ``` await client.UserCollaborations.GetCollaborationByIdAsync(collaborationId: collaborationId); ``` ### Arguments collaborationId `string` - The ID of the collaboration. Example: "1234" queryParams `GetCollaborationByIdQueryParams` - Query parameters of getCollaborationById method headers `GetCollaborationByIdHeaders` - Headers of getCollaborationById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `Collaboration`. Returns a collaboration object. ## Update collaboration Updates a collaboration. Can be used to change the owner of an item, or to accept collaboration invites. This operation is performed by calling function `UpdateCollaborationById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-collaborations-id/). ``` await client.UserCollaborations.UpdateCollaborationByIdAsync(collaborationId: collaborationId, requestBody: new UpdateCollaborationByIdRequestBody(role: UpdateCollaborationByIdRequestBodyRoleField.Viewer)); ``` ### Arguments collaborationId `string` - The ID of the collaboration. Example: "1234" requestBody `UpdateCollaborationByIdRequestBody` - Request body of updateCollaborationById method headers `UpdateCollaborationByIdHeaders` - Headers of updateCollaborationById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `Collaboration?`. Returns an updated collaboration object unless the owner has changed.If the role is changed to `owner`, the collaboration is deleted and a new collaboration is created. The previous `owner` of the old collaboration will be a `co-owner` on the new collaboration. ## Remove collaboration Deletes a single collaboration. This operation is performed by calling function `DeleteCollaborationById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-collaborations-id/). ``` await client.UserCollaborations.DeleteCollaborationByIdAsync(collaborationId: collaborationId); ``` ### Arguments collaborationId `string` - The ID of the collaboration. Example: "1234" headers `DeleteCollaborationByIdHeaders` - Headers of deleteCollaborationById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `null`. A blank response is returned if the collaboration was successfully deleted. ## Create collaboration Adds a collaboration for a single user or a single group to a file or folder. Collaborations can be created using email address, user IDs, or a group IDs. If a collaboration is being created with a group, access to this endpoint is dependent on the group's ability to be invited. If collaboration is in `pending` status, the following fields are redacted: - `login` and `name` are hidden if a collaboration was created using `user_id`, - `name` is hidden if a collaboration was created using `login`. This operation is performed by calling function `CreateCollaboration`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-collaborations/). ``` await client.UserCollaborations.CreateCollaborationAsync(requestBody: new CreateCollaborationRequestBody(item: new CreateCollaborationRequestBodyItemField() { Type = CreateCollaborationRequestBodyItemTypeField.Folder, Id = folder.Id }, accessibleBy: new CreateCollaborationRequestBodyAccessibleByField(type: CreateCollaborationRequestBodyAccessibleByTypeField.User) { Id = user.Id }, role: CreateCollaborationRequestBodyRoleField.Editor)); ``` ### Arguments requestBody `CreateCollaborationRequestBody` - Request body of createCollaboration method queryParams `CreateCollaborationQueryParams` - Query parameters of createCollaboration method headers `CreateCollaborationHeaders` - Headers of createCollaboration method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `Collaboration`. Returns a new collaboration object. --- ### IUsersManager **Type:** page | **Section:** Additional Resources IUsersManager List enterprise users Create user Get current user Get user Update user Delete user List enterprise users Returns a list of… # IUsersManager - [List enterprise users](#list-enterprise-users) - [Create user](#create-user) - [Get current user](#get-current-user) - [Get user](#get-user) - [Update user](#update-user) - [Delete user](#delete-user) ## List enterprise users Returns a list of all users for the Enterprise along with their `user_id`, `public_name`, and `login`. The application and the authenticated user need to have the permission to look up users in the entire enterprise. This operation is performed by calling function `GetUsers`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-users/). ``` await client.Users.GetUsersAsync(); ``` ### Arguments queryParams `GetUsersQueryParams` - Query parameters of getUsers method headers `GetUsersHeaders` - Headers of getUsers method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `Users`. Returns all of the users in the enterprise. ## Create user Creates a new managed user in an enterprise. This endpoint is only available to users and applications with the right admin permissions. This operation is performed by calling function `CreateUser`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-users/). ``` await client.Users.CreateUserAsync(requestBody: new CreateUserRequestBody(name: userName) { Login = userLogin, IsPlatformAccessOnly = true }); ``` ### Arguments requestBody `CreateUserRequestBody` - Request body of createUser method queryParams `CreateUserQueryParams` - Query parameters of createUser method headers `CreateUserHeaders` - Headers of createUser method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `UserFull`. Returns a user object for the newly created user. ## Get current user Retrieves information about the user who is currently authenticated. In the case of a client-side authenticated OAuth 2.0 application this will be the user who authorized the app. In the case of a JWT, server-side authenticated application this will be the service account that belongs to the application by default. Use the `As-User` header to change who this API call is made on behalf of. This operation is performed by calling function `GetUserMe`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-users-me/). ``` await client.Users.GetUserMeAsync(); ``` ### Arguments queryParams `GetUserMeQueryParams` - Query parameters of getUserMe method headers `GetUserMeHeaders` - Headers of getUserMe method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `UserFull`. Returns a single user object. ## Get user Retrieves information about a user in the enterprise. The application and the authenticated user need to have the permission to look up users in the entire enterprise. This endpoint also returns a limited set of information for external users who are collaborated on content owned by the enterprise for authenticated users with the right scopes. In this case, disallowed fields will return null instead. This operation is performed by calling function `GetUserById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-users-id/). ``` await client.Users.GetUserByIdAsync(userId: user.Id); ``` ### Arguments userId `string` - The ID of the user. Example: "12345" queryParams `GetUserByIdQueryParams` - Query parameters of getUserById method headers `GetUserByIdHeaders` - Headers of getUserById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `UserFull`. Returns a single user object. Not all available fields are returned by default. Use the [fields](#param-fields) query parameter to explicitly request any specific fields using the [fields](#get-users-id--request--fields) parameter. ## Update user Updates a managed or app user in an enterprise. This endpoint is only available to users and applications with the right admin permissions. This operation is performed by calling function `UpdateUserById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-users-id/). ``` await client.Users.UpdateUserByIdAsync(userId: user.Id, requestBody: new UpdateUserByIdRequestBody() { Name = updatedUserName }); ``` ### Arguments userId `string` - The ID of the user. Example: "12345" requestBody `UpdateUserByIdRequestBody` - Request body of updateUserById method queryParams `UpdateUserByIdQueryParams` - Query parameters of updateUserById method headers `UpdateUserByIdHeaders` - Headers of updateUserById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `UserFull`. Returns the updated user object. ## Delete user Deletes a user. By default this will fail if the user still owns any content. Move their owned content first before proceeding, or use the `force` field to delete the user and their files. This operation is performed by calling function `DeleteUserById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-users-id/). ``` await client.Users.DeleteUserByIdAsync(userId: user.Id); ``` ### Arguments userId `string` - The ID of the user. Example: "12345" queryParams `DeleteUserByIdQueryParams` - Query parameters of deleteUserById method headers `DeleteUserByIdHeaders` - Headers of deleteUserById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `null`. Removes the user and returns an empty response. --- ### IWebhooksManager **Type:** page | **Section:** Additional Resources IWebhooksManager List all webhooks Create webhook Get webhook Update webhook Remove webhook List all webhooks Returns all defined webhooks… # IWebhooksManager - [List all webhooks](#list-all-webhooks) - [Create webhook](#create-webhook) - [Get webhook](#get-webhook) - [Update webhook](#update-webhook) - [Remove webhook](#remove-webhook) ## List all webhooks Returns all defined webhooks for the requesting application. This API only returns webhooks that are applied to files or folders that are owned by the authenticated user. This means that an admin can not see webhooks created by a service account unless the admin has access to those folders, and vice versa. This operation is performed by calling function `GetWebhooks`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-webhooks/). ``` await client.Webhooks.GetWebhooksAsync(); ``` ### Arguments queryParams `GetWebhooksQueryParams` - Query parameters of getWebhooks method headers `GetWebhooksHeaders` - Headers of getWebhooks method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `Webhooks`. Returns a list of webhooks. ## Create webhook Creates a webhook. This operation is performed by calling function `CreateWebhook`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-webhooks/). ``` await client.Webhooks.CreateWebhookAsync(requestBody: new CreateWebhookRequestBody(target: new CreateWebhookRequestBodyTargetField() { Id = folder.Id, Type = CreateWebhookRequestBodyTargetTypeField.Folder }, address: "https://example.com/new-webhook", triggers: Array.AsReadOnly(new [] {new StringEnum<CreateWebhookRequestBodyTriggersField>(CreateWebhookRequestBodyTriggersField.FileUploaded)}))); ``` ### Arguments requestBody `CreateWebhookRequestBody` - Request body of createWebhook method headers `CreateWebhookHeaders` - Headers of createWebhook method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `Webhook`. Returns the new webhook object. ## Get webhook Retrieves a specific webhook. This operation is performed by calling function `GetWebhookById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-webhooks-id/). ``` await client.Webhooks.GetWebhookByIdAsync(webhookId: NullableUtils.Unwrap(webhook.Id)); ``` ### Arguments webhookId `string` - The ID of the webhook. Example: "3321123" headers `GetWebhookByIdHeaders` - Headers of getWebhookById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `Webhook`. Returns a webhook object. ## Update webhook Updates a webhook. This operation is performed by calling function `UpdateWebhookById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-webhooks-id/). ``` await client.Webhooks.UpdateWebhookByIdAsync(webhookId: NullableUtils.Unwrap(webhook.Id), requestBody: new UpdateWebhookByIdRequestBody() { Address = "https://example.com/updated-webhook" }); ``` ### Arguments webhookId `string` - The ID of the webhook. Example: "3321123" requestBody `UpdateWebhookByIdRequestBody` - Request body of updateWebhookById method headers `UpdateWebhookByIdHeaders` - Headers of updateWebhookById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `Webhook`. Returns the new webhook object. ## Remove webhook Deletes a webhook. This operation is performed by calling function `DeleteWebhookById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-webhooks-id/). ``` await client.Webhooks.DeleteWebhookByIdAsync(webhookId: NullableUtils.Unwrap(webhook.Id)); ``` ### Arguments webhookId `string` - The ID of the webhook. Example: "3321123" headers `DeleteWebhookByIdHeaders` - Headers of deleteWebhookById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `null`. An empty response will be returned when the webhook was successfully deleted. --- ### IWebLinksManager **Type:** page | **Section:** Additional Resources IWebLinksManager Create web link Get web link Update web link Remove web link Create web link Creates a web link object within a folder… # IWebLinksManager - [Create web link](#create-web-link) - [Get web link](#get-web-link) - [Update web link](#update-web-link) - [Remove web link](#remove-web-link) ## Create web link Creates a web link object within a folder. This operation is performed by calling function `CreateWebLink`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-web-links/). ``` await client.WebLinks.CreateWebLinkAsync(requestBody: new CreateWebLinkRequestBody(url: "https://www.box.com", parent: new CreateWebLinkRequestBodyParentField(id: parent.Id)) { Name = Utils.GetUUID(), Description = "Weblink description" }); ``` ### Arguments requestBody `CreateWebLinkRequestBody` - Request body of createWebLink method headers `CreateWebLinkHeaders` - Headers of createWebLink method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `WebLink`. Returns the newly created web link object. ## Get web link Retrieve information about a web link. This operation is performed by calling function `GetWebLinkById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-web-links-id/). ``` await client.WebLinks.GetWebLinkByIdAsync(webLinkId: weblink.Id); ``` ### Arguments webLinkId `string` - The ID of the web link. Example: "12345" headers `GetWebLinkByIdHeaders` - Headers of getWebLinkById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `WebLink`. Returns the web link object. ## Update web link Updates a web link object. This operation is performed by calling function `UpdateWebLinkById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-web-links-id/). ``` await client.WebLinks.UpdateWebLinkByIdAsync(webLinkId: weblink.Id, requestBody: new UpdateWebLinkByIdRequestBody() { Name = updatedName, SharedLink = new UpdateWebLinkByIdRequestBodySharedLinkField() { Access = UpdateWebLinkByIdRequestBodySharedLinkAccessField.Open, Password = password } }); ``` ### Arguments webLinkId `string` - The ID of the web link. Example: "12345" requestBody `UpdateWebLinkByIdRequestBody` - Request body of updateWebLinkById method headers `UpdateWebLinkByIdHeaders` - Headers of updateWebLinkById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `WebLink`. Returns the updated web link object. ## Remove web link Deletes a web link. This operation is performed by calling function `DeleteWebLinkById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-web-links-id/). ``` await client.WebLinks.DeleteWebLinkByIdAsync(webLinkId: webLinkId); ``` ### Arguments webLinkId `string` - The ID of the web link. Example: "12345" headers `DeleteWebLinkByIdHeaders` - Headers of deleteWebLinkById method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `null`. An empty response will be returned when the web link was successfully deleted. --- ### IWorkflowsManager **Type:** page | **Section:** Additional Resources IWorkflowsManager List workflows Starts workflow based on request body List workflows Returns list of workflows that act on a given folder… # IWorkflowsManager - [List workflows](#list-workflows) - [Starts workflow based on request body](#starts-workflow-based-on-request-body) ## List workflows Returns list of workflows that act on a given `folder ID`, and have a flow with a trigger type of `WORKFLOW_MANUAL_START`. You application must be authorized to use the `Manage Box Relay` application scope within the developer console in to use this endpoint. This operation is performed by calling function `GetWorkflows`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-workflows/). ``` await adminClient.Workflows.GetWorkflowsAsync(queryParams: new GetWorkflowsQueryParams(folderId: workflowFolderId)); ``` ### Arguments queryParams `GetWorkflowsQueryParams` - Query parameters of getWorkflows method headers `GetWorkflowsHeaders` - Headers of getWorkflows method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `Workflows`. Returns the workflow. ## Starts workflow based on request body Initiates a flow with a trigger type of `WORKFLOW_MANUAL_START`. You application must be authorized to use the `Manage Box Relay` application scope within the developer console. This operation is performed by calling function `StartWorkflow`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-workflows-id-start/). ``` await adminClient.Workflows.StartWorkflowAsync(workflowId: NullableUtils.Unwrap(workflowToRun.Id), requestBody: new StartWorkflowRequestBody(flow: new StartWorkflowRequestBodyFlowField() { Type = "flow", Id = NullableUtils.Unwrap(NullableUtils.Unwrap(workflowToRun.Flows)[0].Id) }, files: Array.AsReadOnly(new [] {new StartWorkflowRequestBodyFilesField() { Type = StartWorkflowRequestBodyFilesTypeField.File, Id = workflowFileId }}), folder: new StartWorkflowRequestBodyFolderField() { Type = StartWorkflowRequestBodyFolderTypeField.Folder, Id = workflowFolderId }) { Type = StartWorkflowRequestBodyTypeField.WorkflowParameters }); ``` ### Arguments workflowId `string` - The ID of the workflow. Example: "12345" requestBody `StartWorkflowRequestBody` - Request body of startWorkflow method headers `StartWorkflowHeaders` - Headers of startWorkflow method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `null`. Starts the workflow. --- ### IZipDownloadsManager **Type:** page | **Section:** Additional Resources IZipDownloadsManager Create zip download Download zip archive Get zip download status Download ZIP Create zip download Creates a request to… # IZipDownloadsManager - [Create zip download](#create-zip-download) - [Download zip archive](#download-zip-archive) - [Get zip download status](#get-zip-download-status) - [Download ZIP](#download-zip) ## Create zip download Creates a request to download multiple files and folders as a single `zip` archive file. This API does not return the archive but instead performs all the checks to ensure that the user has access to all the items, and then returns a `download_url` and a `status_url` that can be used to download the archive. The limit for an archive is either the Account's upload limit or 10,000 files, whichever is met first. **Note**: Downloading a large file can be affected by various factors such as distance, network latency, bandwidth, and congestion, as well as packet loss ratio and current server load. For these reasons we recommend that a maximum ZIP archive total size does not exceed 25GB. This operation is performed by calling function `CreateZipDownload`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-zip-downloads/). ``` await client.ZipDownloads.CreateZipDownloadAsync(requestBody: new ZipDownloadRequest(items: Array.AsReadOnly(new [] {new ZipDownloadRequestItemsField(id: file1.Id, type: ZipDownloadRequestItemsTypeField.File),new ZipDownloadRequestItemsField(id: file2.Id, type: ZipDownloadRequestItemsTypeField.File),new ZipDownloadRequestItemsField(id: folder1.Id, type: ZipDownloadRequestItemsTypeField.Folder)})) { DownloadFileName = "zip" }); ``` ### Arguments requestBody `ZipDownloadRequest` - Request body of createZipDownload method headers `CreateZipDownloadHeaders` - Headers of createZipDownload method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `ZipDownload`. If the `zip` archive is ready to be downloaded, the API will return a response that will include a `download_url`, a `status_url`, as well as any conflicts that might have occurred when creating the request. ## Download zip archive Returns the contents of a `zip` archive in binary format. This URL does not require any form of authentication and could be used in a user's browser to download the archive to a user's device. By default, this URL is only valid for a few seconds from the creation of the request for this archive. Once a download has started it can not be stopped and resumed, instead a new request for a zip archive would need to be created. The URL of this endpoint should not be considered as fixed. Instead, use the [Create zip download](e://post_zip_downloads) API to request to create a `zip` archive, and then follow the `download_url` field in the response to this endpoint. This operation is performed by calling function `GetZipDownloadContent`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-zip-downloads-id-content/). ``` await client.ZipDownloads.GetZipDownloadContentAsync(downloadUrl: NullableUtils.Unwrap(zipDownload.DownloadUrl)); ``` ### Arguments downloadUrl `string` - The URL that can be used to download created `zip` archive. Example: `https://dl.boxcloud.com/2.0/zip_downloads/29l00nfxDyHOt7RphI9zT_w==nDnZEDjY2S8iEWWCHEEiptFxwoWojjlibZjJ6geuE5xnXENDTPxzgbks_yY=/content` headers `GetZipDownloadContentHeaders` - Headers of getZipDownloadContent method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `System.IO.Stream`. Returns the content of the items requested for this download, formatted as a stream of files and folders in a `zip` archive. ## Get zip download status Returns the download status of a `zip` archive, allowing an application to inspect the progress of the download as well as the number of items that might have been skipped. This endpoint can only be accessed once the download has started. Subsequently this endpoint is valid for 12 hours from the start of the download. The URL of this endpoint should not be considered as fixed. Instead, use the [Create zip download](e://post_zip_downloads) API to request to create a `zip` archive, and then follow the `status_url` field in the response to this endpoint. This operation is performed by calling function `GetZipDownloadStatus`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-zip-downloads-id-status/). ``` await client.ZipDownloads.GetZipDownloadStatusAsync(statusUrl: NullableUtils.Unwrap(zipDownload.StatusUrl)); ``` ### Arguments statusUrl `string` - The URL that can be used to get the status of the `zip` archive being downloaded. Example: `https://dl.boxcloud.com/2.0/zip_downloads/29l00nfxDyHOt7RphI9zT_w==nDnZEDjY2S8iEWWCHEEiptFxwoWojjlibZjJ6geuE5xnXENDTPxzgbks_yY=/status` headers `GetZipDownloadStatusHeaders` - Headers of getZipDownloadStatus method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `ZipDownloadStatus`. Returns the status of the `zip` archive that is being downloaded. ## Download ZIP Creates a zip and downloads its content This operation is performed by calling function `DownloadZip`. ``` await client.ZipDownloads.DownloadZipAsync(requestBody: new ZipDownloadRequest(items: Array.AsReadOnly(new [] {new ZipDownloadRequestItemsField(id: file1.Id, type: ZipDownloadRequestItemsTypeField.File),new ZipDownloadRequestItemsField(id: file2.Id, type: ZipDownloadRequestItemsTypeField.File),new ZipDownloadRequestItemsField(id: folder1.Id, type: ZipDownloadRequestItemsTypeField.Folder)})) { DownloadFileName = "zip" }); ``` ### Arguments requestBody `ZipDownloadRequest` - Zip download request body headers `DownloadZipHeaders` - Headers of zip download method cancellationToken `System.Threading.CancellationToken?` - Token used for request cancellation. ### Returns This function returns a value of type `System.IO.Stream`. --- ### Legal Hold Policies **Type:** page | **Section:** Additional Resources Legal Hold Policies A legal hold policy blocks permanent deletion of content during ongoing litigation. Admins can create legal hold… # Legal Hold Policies A legal hold policy blocks permanent deletion of content during ongoing litigation. Admins can create legal hold policies and then later assign them to specific folders, files, or users. - [Create Legal Hold Policy](#create-legal-hold-policy) - [Get Legal Hold Policy](#get-legal-hold-policy) - [Update Legal Hold Policy](#update-legal-hold-policy) - [Delete Legal Hold Policy](#delete-legal-hold-policy) - [Get Enterprise Legal Hold Policies](#get-enterprise-legal-hold-policies) - [Get Legal Hold Policy Assignments](#get-legal-hold-policy-assignments) - [Assign Legal Hold Policy](#assign-legal-hold-policy) - [Delete Legal Hold Policy Assignment](#delete-legal-hold-policy-assignment) - [Get Legal Hold Policy Assignment](#get-legal-hold-policy-assignment) - [Get File Version Legal Hold](#get-file-version-legal-hold) - [Get File Version Legal Holds](#get-file-version-legal-holds) ## Create Legal Hold Policy To create a new legal hold policy, call the [`legalHoldPolicies.create(name, options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/LegalHoldPolicies.html#create) method. ``` client.legalHoldPolicies.create('IRS Audit') .then(policy => { /* policy -> { type: 'legal_hold_policy', id: '11111', policy_name: 'IRS Audit', description: '', status: 'active', assignment_counts: { user: 0, folder: 0, file: 0, file_version: 0 }, is_ongoing: true, created_by: { type: 'user', id: '22222', name: 'Example User', login: 'user@example.com' }, created_at: '2017-01-24T16:57:22-08:00', modified_at: '2017-01-24T16:57:22-08:00', deleted_at: null, filter_started_at: null, filter_ended_at: null } */ }); ``` ## Get Legal Hold Policy To retrieve information about a specific legal hold policy, call the [`legalHoldPolicies.get(policyID, options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/LegalHoldPolicies.html#get) method. ``` client.legalHoldPolicies.get('11111') .then(policy => { /* policy -> { type: 'legal_hold_policy', id: '11111', policy_name: 'IRS Audit', description: '', status: 'active', assignment_counts: { user: 1, folder: 0, file: 0, file_version: 0 }, created_by: { type: 'user', id: '22222', name: 'Example User', login: 'user@example.com' }, created_at: '2016-05-18T10:28:45-07:00', modified_at: '2016-05-18T11:25:59-07:00', deleted_at: null, filter_started_at: '2016-05-17T01:00:00-07:00', filter_ended_at: '2016-05-21T01:00:00-07:00' } */ }); ``` Requesting information for only the fields you need with the `fields` option can improve performance and reduce the size of the network request. ``` client.legalHoldPolicies.get('12345', {fields: 'policy_name,created_at,created_by'}, callback); ``` ## Update Legal Hold Policy To update or modify an existing legal hold policy, call the [`legalHoldPolicies.update(policyID, updates, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/LegalHoldPolicies.html#update) method where `updates` is the set of key-value pairs to be updated on the policy object. ``` client.legalHoldPolicies.update('11111', {description: 'Documents related to IRS audit'}) .then(policy => { /* policy -> { type: 'legal_hold_policy', id: '11111', policy_name: 'IRS Audit', description: 'Documents related to IRS audit', status: 'active', assignment_counts: { user: 1, folder: 0, file: 0, file_version: 0 }, created_by: { type: 'user', id: '22222', name: 'Example User', login: 'user@example.com' }, created_at: '2016-05-18T10:28:45-07:00', modified_at: '2016-05-18T11:25:59-07:00', deleted_at: null, filter_started_at: '2016-05-17T01:00:00-07:00', filter_ended_at: '2016-05-21T01:00:00-07:00' } */ }); ``` ## Delete Legal Hold Policy To delete a legal hold policy, call the [`legalHoldPolicies.delete(policyID, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/LegalHoldPolicies.html#delete) method. Note that this is an asynchronous process - the policy will not be fully deleted yet when the response comes back. ``` client.legalHoldPolicies.delete('11111') .then(() => { // deletion started — no value returned }); ``` ## Get Enterprise Legal Hold Policies To retrieve all of the legal hold policies for the given enterprise, call the [`legalHoldPolicies.getAll(options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/LegalHoldPolicies.html#getAll) method. ``` client.legalHoldPolicies.getAll({policy_name: 'Important'}) .then(policies => { /* policies -> { entries: [ { type: 'legal_hold_policy', id: '11111', policy_name: 'Important Policy 1' }, { type: 'legal_hold_policy', id: '22222', policy_name: 'Important Policy 2' } ], limit: 100, order: [ { by: 'policy_name', direction: 'ASC' } ] } */ }); ``` ## Get Legal Hold Policy Assignments To get a list of all legal hold policy assignments associated with a specified legal hold policy, call the [`legalHoldPolicies.getAssignments(policyID, options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/LegalHoldPolicies.html#getAssignments) method. ``` client.legalHoldPolicies.getAssignments('8763245', {assign_to_type: 'folder'}) .then(assignments => { /* assignments -> { entries: [ { type: 'legal_hold_policy_assignment', id: '22222' } ], limit: 100, next_marker: 'someMarkerString' } */ }); ``` ## Assign Legal Hold Policy To assign a legal hold policy, call the [`legalHoldPolicies.assign(policyID, assignType, assignID, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/LegalHoldPolicies.html#assign) method. ``` client.legalHoldPolicies.assign('11111', 'folder', '12345') .then(assignment => { /* assignment -> { type: 'legal_hold_policy_assignment', id: '22222', legal_hold_policy: { type: 'legal_hold_policy', id: '11111', policy_name: 'IRS Audit' }, assigned_to: { type: 'folder', id: '12345' }, assigned_by: { type: 'user', id: '33333', name: 'Example User', login: 'user@example.com' }, assigned_at: '2016-05-18T17:38:03-07:00', deleted_at: null } */ }); ``` ## Delete Legal Hold Policy Assignment To delete a legal hold assignment and remove a legal hold policy from an item, call the [`legalHoldPolicies.deleteAssignment(assignmentID, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/LegalHoldPolicies.html#deleteAssignment) method. Note that this is an asynchronous process - the assignment will not be fully deleted yet when the response comes back. ``` client.legalHoldPolicies.deleteAssignment('22222') .then(() => { // deletion started — no value returned }); ``` ## Get Legal Hold Policy Assignment To retrieve information about a legal hold policy assignment, call the [`legalHoldPolicies.getAssignment(assignmentID, options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/LegalHoldPolicies.html#getAssignment) method. ``` client.legalHoldPolicies.getAssignment('22222') .then(assignment => { /* assignment -> { type: 'legal_hold_policy_assignment', id: '22222', legal_hold_policy: { type: 'legal_hold_policy', id: '11111', policy_name: 'IRS Audit' }, assigned_to: { type: 'user', id: '33333' }, assigned_by: { type: 'user', id: '11111', name: 'Example User', login: 'user@example.com' }, assigned_at: '2016-05-18T10:32:19-07:00', deleted_at: null } */ }); ``` Requesting information for only the fields you need with the `fields` option can improve performance and reduce the size of the network request. ``` client.legalHoldPolicies.getAssignment('22222', {fields: 'id,assigned_by,assigned_at'}) .then(assignment => { /* assignment -> { type: 'legal_hold_policy_assignment', id: '22222', assigned_by: { type: 'user', id: '11111', name: 'Example User', login: 'user@example.com' }, assigned_at: '2016-05-18T10:32:19-07:00' } */ }); ``` ## Get File Version Legal Hold A file version legal hold is a record for a held file version. To get information for a specific file version legal hold record, call the [`legalHoldPolicies.getFileVersionLegalHold(legalHoldID, options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/LegalHoldPolicies.html#getFileVersionLegalHold) method. ``` client.legalHoldPolicies.getFileVersionLegalHold('55555') .then(fileVersionHold => { /* fileVersionHold -> { type: 'legal_hold', id: '55555', file_version: { type: 'file_version', id: '123456789' }, file: { type: 'file', id: '66666', etag: '1' }, legal_hold_policy_assignments: [ { type: 'legal_hold_policy_assignment', id: '22222' }, { type: 'legal_hold_policy_assignment', id: '33333' } ], deleted_at: null } */ }); ``` Requesting information for only the fields you need with the `fields` option can improve performance and reduce the size of the network request. ``` client.legalHoldPolicies.getFileVersionLegalHold('8762345', {fields: 'id,file'}) .then(fileVersionHold => { /* fileVersionHold -> { type: 'legal_hold', id: '55555', file: { type: 'file', id: '66666', etag: '1' } } */ }); ``` ## Get File Version Legal Holds To retrieve a list of all file version legal holds for a given policy, call the [`legalHoldPolicies.getAllFileVersionLegalHolds(policyID, options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/LegalHoldPolicies.html#getAllFileVersionLegalHolds) method. ``` client.legalHoldPolicies.getAllFileVersionLegalHolds('11111') .then(holds => { /* holds -> { entries: [ { type: 'legal_hold', id: '22222' }, { type: 'legal_hold', id: '33333' }, { type: 'legal_hold', id: '44444' } ], limit: 100, order: [ { by: 'retention_policy_set_id, file_version_id', direction: 'ASC' } ] } */ }); ``` --- ### Legal Hold Policies **Type:** page | **Section:** Additional Resources Legal Hold Policies A legal hold policy blocks permanent deletion of content during ongoing litigation. Admins can create legal hold… # Legal Hold Policies A legal hold policy blocks permanent deletion of content during ongoing litigation. Admins can create legal hold policies and then later assign them to specific folders, files, or users. Legal Hold Policy information describes the basic characteristics of the Policy, such as name, description, and filter dates. It is important to note that the legal hold object contains no information about what this policy applies to. If an order of discovery is received or the customer is part of an ongoing litigation, a legal hold policy can be created to keep track of everything that needs to be held. The actual holding is done via Legal Hold Assignments. - [Get Information About a Legal Hold Policy](#get-information-about-a-legal-hold-policy) - [List Legal Hold Policies](#list-legal-hold-policies) - [Create New Legal Hold Policy](#create-new-legal-hold-policy) - [Update Legal Hold Policy](#update-legal-hold-policy) - [Delete Legal Hold Policy](#delete-legal-hold-policy) - [Assign Legal Hold Policy](#assign-legal-hold-policy) - [List Legal Hold Policy Assignments](#list-legal-hold-policy-assignments) - [Get Information About a Legal Hold Assignment](#get-information-about-a-legal-hold-assignment) - [Delete Legal Hold Assignment](#delete-legal-hold-assignment) - [List File Version Legal Holds](#list-file-version-legal-holds) - [Get Information about a File Version Legal Hold](#get-information-about-a-file-version-legal-hold) ## Get Information About a Legal Hold Policy To retrieve information about a legal hold policy, first call [`client.legal_hold_policy(policy_id)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.client.html#boxsdk.client.client.Client.legal_hold_policy) to initialize the [`LegalHoldPolicy`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.legal_hold_policy.LegalHoldPolicy) and then call [`legal_hold_policy.get(*, fields=None, headers=None, **kwargs)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.base_object.BaseObject.get) to retrieve data from the API. This method returns a new [`LegalHoldPolicy`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.legal_hold_policy.LegalHoldPolicy) object with fields populated by data form the API, leaving the original object unmodified. ``` legal_hold_policy = client.legal_hold_policy(policy_id='12345').get() print(f'The "{legal_hold_policy.policy_name}" policy is {legal_hold_policy.status}') ``` ## List Legal Hold Policies To get the legal hold policies available in the enterprise, call [`client.get_legal_hold_policies(policy_name=None, limit=None, marker=None, fields=None)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.client.html#boxsdk.client.client.Client.get_legal_hold_policies). You can optionally pass a `policy_name` value to filter the results to include only policies that are a case-insensitive prefix match by name. This method returns a `BoxObjectCollection` that allows you to iterate over the [`LegalHoldPolicy`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.legal_hold_policy.LegalHoldPolicy) objects in the collection. ``` policies = client.get_legal_hold_policies() for policy in policies: print(f'Legal Hold Policy "{policy.name}" has ID {policy.id}') ``` ## Create New Legal Hold Policy To create a new legal hold policy, call [`client.create_legal_hold_policy(policy_name, description=None, filter_starting_at=None, filter_ending_at=None, is_ongoing=None)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.client.html#boxsdk.client.client.Client.create_legal_hold_policy) with the name for the policy. You can optionally include a human-readable `description`, as well as parameters describing which time period the policy applies to. You must specify either `filter_starting_at` and `filter_ending_at` dates, or `is_ongoing=True`. This method returns a new [`LegalHoldPolicy`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.legal_hold_policy.LegalHoldPolicy) object representing the created policy. ``` new_policy = client.create_legal_hold_policy('New Policy', is_ongoing=True) print(f'Created legal hold policy with ID {new_policy.id}') ``` ## Update Legal Hold Policy To update an existing legal hold policy, call [`legal_hold_policy.update_info(data=policy_update)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.base_object.BaseObject.update_info) with a `dict` of properties to update on the policy. This method returns a new [`LegalHoldPolicy`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.legal_hold_policy.LegalHoldPolicy) object with the updates applied, leaving the original object unmodified. ``` policy_update = {'description': 'New Description', 'release_notes': 'Example Notes'} updated_policy = client.legal_hold_policy(policy_id='12345').update_info(data=policy_update) ``` ## Delete Legal Hold Policy To delete a legal hold policy, call [`legal_hold_policy.delete()`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.base_object.BaseObject.delete). This method returns `True` to indicate that the deletion request was successful. **Note:** This is an asynchronous process - the policy assignment may not be fully deleted yet when the response comes back. ``` client.legal_hold_policy(policy_id='12345').delete() print('Legal hold policy was deleted!') ``` ## Assign Legal Hold Policy To assign a legal hold policy, call [`legal_hold_policy.assign(assignee)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.legal_hold_policy.LegalHoldPolicy.assign). You can assign a legal hold policy to a [`Folder`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.folder.Folder), [`File`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.file.File), [`FileVersion`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.file_version.FileVersion), or [`User`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.user.User). This will cause the associated items to be held and unable to be deleted. ``` folder_to_assign = client.folder(folder_id='22222') assignment = client.legal_hold_policy(policy_id'12345').assign(folder_to_assign) print(f'Applied policy "{assignment.legal_hold_policy.policy_name}" to {assignment.assigned_to.type} {assignment.assigned_to.id}') ``` ## List Legal Hold Policy Assignments To get the assignments for a specific legal hold policy, call [`legal_hold_policy.get_assignments(assign_to_type=None, assign_to_id=None, limit=None, marker=None, fields=None)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.legal_hold_policy.LegalHoldPolicy.get_assignments). This method returns a `BoxObjectCollection` that allows you to iterate over the [`LegalHoldPolicyAssignment`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.legal_hold_policy_assignment.LegalHoldPolicyAssignments) objects in the collection. ``` assignments = client.legal_hold_policy(policy_id='12345').get_assignments() for assignment in assignments: print(f'Found policy assignment with ID {assignment.id}') ``` To filter by the assignee `type` and/or `id` you can use pass in the `assign_to_type` and `assign_to_id` filter. ``` folder_id = '1111' assignments = client.legal_hold_policy('1234').get_assignments('folder', folder_id) for assignment in assignments: print(f'Found policy assignment with ID {assignment.id}') ``` ## Get Information About a Legal Hold Assignment To retrieve information about a legal hold policy assignment, first call [`client.legal_hold_policy_assignment(policy_assignment_id)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.client.html#boxsdk.client.client.Client.legal_hold_policy_assignment) to initialize the [`LegalHoldPolicyAssignment`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.legal_hold_policy_assignment.LegalHoldPolicyAssignments) and then call [`legal_hold_policy_assignment.get(*, fields=None, headers=None, **kwargs)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.base_object.BaseObject.get) to retrieve data about the assignment from the API. This method returns a new [`LegalHoldPolicyAssignment`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.legal_hold_policy_assignment.LegalHoldPolicyAssignments) with fields populated by data from the API, leaving the original object unmodified. ``` assignment_id = '98765' assignment = client.legal_hold_policy_assignment(assignment_id).get() print(f'Policy {assignment.legal_hold_policy.id} is assigned to {assignment.assigned_to.type} {assignment.assigned_to.id}') ``` ## Delete Legal Hold Assignment To delete an existing legal hold policy assignment, call [`legal_hold_policy_assignment.delete()`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.base_object.BaseObject.delete). This method returns `True` to indicate that the deletion request was successful. **Note:** This is an asynchronous process - the policy assignment may not be fully deleted yet when the response comes back. ``` assignment_id = '1111' client.legal_hold_policy_assignment(assignment_id).delete() ``` ## List File Version Legal Holds To get the actual hold records associated with a policy, call [`legal_hold_policy.get_file_version_legal_holds()`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.legal_hold_policy.LegalHoldPolicy.get_file_version_legal_holds). This method returns a `BoxObjectCollection` that allows you to iterate over the [`LegalHold`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.legal_hold.LegalHold) objects in the collection. ``` legal_holds = client.legal_hold_policy(policy_id='12345').get_file_version_legal_holds() for legal_hold in legal_holds: print(f'Got file version legal hold with ID {legal_hold.id}') ``` ## Get Information about a File Version Legal Hold To retrieve information about a file version legal hold, call [`legal_hold.get(*, fields=None, headers=None, **kwargs)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.base_object.BaseObject.get). This method returns a new [`LegalHold`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.legal_hold.LegalHold) with fields populated by data from the API, leaving the original object unmodified. ``` file_version_legal_hold_id = '55555' legal_hold = client.legal_hold(file_version_legal_hold_id).get() print(f'Version {legal_hold.file_version.id} of file {legal_hold.file.id} is held by {len(legal_hold.legal_hold_policy_assignments)} assignment(s)') ``` --- ### Legal Hold Policies **Type:** page | **Section:** Additional Resources Legal Hold Policies A legal hold policy blocks permanent deletion of content during ongoing litigation. Admins can create legal hold… # Legal Hold Policies A legal hold policy blocks permanent deletion of content during ongoing litigation. Admins can create legal hold policies and then later assign them to specific folders, files, or users. - [Get Legal Hold Policy](#get-legal-hold-policy) - [Get Enterprise Legal Hold Policies](#get-enterprise-legal-hold-policies) - [Create Legal Hold Policy](#create-legal-hold-policy) - [Update Legal Hold Policy](#update-legal-hold-policy) - [Delete Legal Hold Policy](#delete-legal-hold-policy) - [Get Legal Hold Policy Assignment](#get-legal-hold-policy-assignment) - [Get Legal Hold Policy Assignments](#get-legal-hold-policy-assignments) - [Assign Legal Hold Policy](#assign-legal-hold-policy) - [Delete Legal Hold Policy Assignment](#delete-legal-hold-policy-assignment) - [Get File Version Legal Hold](#get-file-version-legal-hold) - [Get File Version Legal Holds](#get-file-version-legal-holds) ## Get Legal Hold Policy To retrieve information about a specific legal hold policy, call `LegalHoldPoliciesManager.GetLegalHoldPolicyAsync(string legalHoldId)` with the ID of the legal hold policy. ``` BoxLegalHoldPolicy policy = await client.LegalHoldPoliciesManager.GetLegalHoldPolicyAsync("11111"); ``` ## Get Enterprise Legal Hold Policies To retrieve all of the legal hold policies for the given enterprise, call `LegalHoldPoliciesManager.GetListLegalHoldPoliciesAsync(string policyName = null, string fields = null, int limit = 100, string marker = null, bool autoPaginate = false)`. ``` BoxCollectionMarkerBased<BoxLegalHoldPolicy> policies = await client.LegalHoldPoliciesManager .GetListLegalHoldPoliciesAsync(); ``` ## Create Legal Hold Policy To create a new legal hold policy, call `LegalHoldPoliciesManager.CreateLegalHoldPolicyAsync(BoxLegalHoldPolicyRequest createRequest)`. ``` var policyParams = new BoxLegalHoldPolicyRequest() { PolicyName = "IRS Audit" }; BoxLegalHoldPolicy policy = await client.LegalHoldPoliciesManager .CreateLegalHoldPolicyAsync(policyParams); ``` ## Update Legal Hold Policy To update or modify an existing legal hold policy, call `LegalHoldPoliciesManager.UpdateLegalHoldPolicyAsync(string legalHoldPolicyId, BoxLegalHoldPolicyRequest updateRequest)` with the ID of the policy to update and the fields to update. ``` var updates = new BoxLegalHoldPolicyRequest() { Description = "Hold for documents related to the IRS audit" }; BoxLegalHoldPolicy updatedPolicy = await client.LegalHoldPoliciesManager .UpdateLegalHoldPolicyAsync("11111", updates); ``` ## Delete Legal Hold Policy To delete a legal hold policy, call `LegalHoldPoliciesManager.DeleteLegalHoldPolicyAsync(string legalHoldPolicyId)`. Note that this is an asynchronous process - the policy will not be fully deleted yet when the response comes back. ``` await client.LegalHoldPoliciesManager.DeleteLegalHoldPolicyAsync("11111"); ``` ## Get Legal Hold Policy Assignment To retrieve information about a legal hold policy assignment, call `LegalHoldPoliciesManager.GetAssignmentAsync(string assignmentId)` with the ID of the assignment object. ``` BoxLegalHoldPolicyAssignment assignment = await client.LegalHoldPoliciesManager .GetAssignmentAsync(assignmentId: "22222"); ``` ## Get Legal Hold Policy Assignments To get a list of all legal hold policy assignments associated with a specified legal hold policy, call `LegalHoldPoliciesManager.GetAssignmentsAsync(string legalHoldPolicyId, string fields = null, string assignToType = null, string assignToId = null, int limit = 100, string marker = null, bool autoPaginate = false)` with the ID of the policy. ``` BoxCollectionMarkerBased<BoxLegalHoldPolicyAssignment> assignments = await client.LegalHoldPoliciesManager .GetAssignmentsAsync(legalHoldPolicyId: "11111"); ``` ## Assign Legal Hold Policy To assign a legal hold policy, call `LegalHoldPoliciesManager.CreateAssignmentAsync(BoxLegalHoldPolicyAssignmentRequest createRequest)`. ``` var requestParams = new BoxLegalHoldPolicyAssignmentRequest() { PolicyId = "11111", AssignTo = new BoxRequestEntity() { Type = "folder", Id = "12345" } }; BoxLegalHoldPolicyAssignment assignment = await client.LegalHoldPoliciesManager .CreateAssignmentAsync(requestParams); ``` ## Delete Legal Hold Policy Assignment To delete a legal hold assignment and remove a legal hold policy from an item, call the `LegalHoldPoliciesManager.DeleteAssignmentAsync(string assignmentId)` method. Note that this is an asynchronous process - the assignment will not be fully deleted yet when the response comes back. ``` await client.LegalHoldPoliciesManager.DeleteAssignmentAsync("22222"); ``` ## Get File Version Legal Hold A file version legal hold is a record for a held file version. To get information for a specific file version legal hold record, call `LegalHoldPoliciesManager.GetFileVersionLegalHoldAsync(string fileVersionLegalHoldId)` with the ID of the file version legal hold record. ``` BoxFileVersionLegalHold hold = await client.LegalHoldPoliciesManager .GetFileVersionLegalHoldAsync("55555"); ``` ## Get File Version Legal Holds To retrieve a list of all file version legal holds for a given policy, call `LegalHoldPoliciesManager.GetFileVersionLegalHoldsAsync(string policyId, IEnumerable<string> fields = null, int limit = 100, string marker = null, bool autoPaginate = false)` with the ID of the legal hold policy. ``` BoxCollectionMarkerBased<BoxFileVersionLegalHold> holds = await client.LegalHoldPoliciesManager .GetFileVersionLegalHoldsAsync(policyId: "11111"); ``` --- ### Legal Holds **Type:** page | **Section:** Additional Resources Legal Holds Get Legal Hold Policy Info Create Legal Hold Policy Update Legal Hold Policy Delete Legal Hold Policy Get Legal Hold Policies… # Legal Holds - [Get Legal Hold Policy Info](#get-legal-hold-policy-info) - [Create Legal Hold Policy](#create-legal-hold-policy) - [Update Legal Hold Policy](#update-legal-hold-policy) - [Delete Legal Hold Policy](#delete-legal-hold-policy) - [Get Legal Hold Policies](#get-legal-hold-policies) - [Get Policy Assignment Info](#get-policy-assignment-info) - [Create Policy Assignment](#create-policy-assignment) - [Delete Policy Assignment](#delete-policy-assignment) - [Get Policy Assignments](#get-policy-assignments) - [Get File Version Legal Hold Info](#get-file-version-legal-hold-info) - [Get File Version Legal Holds](#get-file-version-legal-holds) ## Get Legal Hold Policy Info To retrieve information about a legal hold policy, call [`client.legalHolds.get(policyId: String, fields: [String]?, completion: @escaping Callback<LegalHoldPolicy>)`](https://opensource.box.com/box-ios-sdk/Classes/LegalHoldsModule.html#/s:6BoxSDK16LegalHoldsModuleC3get8policyId6fields10completionySS_SaySSGSgys6ResultOyAA0C10HoldPolicyCAA0A8SDKErrorCGctF) with the ID of the policy. You can control which fields are returned in the resulting `Legal Hold Policy` object by passing the `fields` parameter. ``` client.legalHolds.get(policyId: "22222", fields: ["name", "created_at"]) { (result: Result<LegalHoldPolicy, BoxSDKError>) in guard case let .success(policy) = result else { print("Error getting policy information") return } print("Legal hold policy \(policy.id) was created at \(policy.createdAt)") } ``` ## Get Legal Hold Policies To retrieve information about the items contained in a folder, call [`client.legalHolds.listForEnterprise(policyName: String, marker: String?, limit: Int?, fields: [String]?)`](https://opensource.box.com/box-ios-sdk/Classes/LegalHoldsModule.html#/s:6BoxSDK16LegalHoldsModuleC17listForEnterprise10policyName6marker5limit6fields10completionySSSg_AJSiSgSaySSGSgys6ResultOyAA14PagingIteratorCyAA0C10HoldPolicyCGAA0A8SDKErrorCGctF) with the ID of the policy. This method will return an iterator object, which is used to retrieve policies in the enterprise. ``` let iterator = client.legalHolds.listForEnterprise(policyName: "policy1") iterator.next { results in switch results { case let .success(page): for policy in page.entries { print("Legal hold policy \(policy.name)") } case let .failure(error): print(error) } } ``` ## Create Legal Hold Policy To create a new legal hold policy, call [`client.legalHolds.create(policyName: String, description: String? filterStartedAt: Date?, filterEndedAt: Date?, isOngoing: Bool?, fields: [String]?, completion: @escaping Callback<LegalHoldPolicy>`](https://opensource.box.com/box-ios-sdk/Classes/LegalHoldsModule.html#/s:6BoxSDK16LegalHoldsModuleC6create10policyName11description15filterStartedAt0j5EndedL09isOngoing6fields10completionySS_SSSg10Foundation4DateVSgAPSbSgSaySSGSgys6ResultOyAA0C10HoldPolicyCAA0A8SDKErrorCGctF) with a name for the legal hold policy. ``` client.legalHolds.create(name: "New Folder") { (result: Result<LegalHoldPolicy, BoxSDKError>) in guard case let .success(policy) = result else { print("Error creating legal hold policy") return } print("Created legal hold policy \"\(policy.name)\"") } ``` ## Update Legal Hold Policy To update legal hold policy, call [`client.legalHolds.update(policyId: String, policyName: String?, description: String?, releaseNotes: String?, fields: [String]?, completion: @escaping Callback<LegalHoldPolicy>`](https://opensource.box.com/box-ios-sdk/Classes/LegalHoldsModule.html#/s:6BoxSDK16LegalHoldsModuleC6update8policyId0G4Name11description12releaseNotes6fields10completionySS_SSSgA2KSaySSGSgys6ResultOyAA0C10HoldPolicyCAA0A8SDKErrorCGctF). ``` client.legalHolds.update(policyId: "1234", policyName: "New Name") { (result: Result<LegalHoldPolicy, BoxSDKError>) in guard case let .success(policy) = result else { print("Error updating legal hold policy") return } print("Updated legal hold policy name is \"\(policy.name)\"") } ``` ## Delete Legal Hold Policy To delete a legal hold policy, call [`client.folders.delete(policyId: String, completion: @escaping Callback<Void>`](https://opensource.box.com/box-ios-sdk/Classes/LegalHoldsModule.html#/s:6BoxSDK16LegalHoldsModuleC6delete8policyId10completionySS_ys6ResultOyytAA0A8SDKErrorCGctF) with the ID of the legal hold policy to delete. ``` client.legalHolds.delete() { result: Result<Void, BoxSDKError>} in guard case .success = result else { print("Error deleting legal hold policy") return } print("Legal hold policy successfully deleted") } ``` ## Get Policy Assignment Info To retrieve information about a legal hold policy assignment, call [`client.legalHolds.getPolicyAssignment(assignmentId: String, fields: [String]?, completion: @escaping Callback<LegalHoldPolicyAssignment>)`](https://opensource.box.com/box-ios-sdk/Classes/LegalHoldsModule.html#/s:6BoxSDK16LegalHoldsModuleC19getPolicyAssignment12assignmentId6fields10completionySS_SaySSGSgys6ResultOyAA0c4HoldgH0CAA0A8SDKErrorCGctF) with the ID of the policy assignment. You can control which fields are returned in the resulting `Legal Hold Policy Assignment` object by passing the `fields` parameter. ``` client.legalHolds.getPolicyAssignment(assignmentId: "22222", fields: ["assigned_at"]) { (result: Result<LegalHoldPolicyAssignment, BoxSDKError>) in guard case let .success(assignment) = result else { print("Error getting policy assignment info") return } print("Legal hold policy assignment \(assignmnent.id) was created at \(assignment.assignedAt)") } ``` ## Get Policy Assignments To retrieve legal hold policy assignments, call [`client.legalHolds.listPolicyAssignments(policyId: String, assignToType: String?, assignToId: String?, marker: String?, limit: String?, fields: [String]?)`](https://opensource.box.com/box-ios-sdk/Classes/LegalHoldsModule.html#/s:6BoxSDK16LegalHoldsModuleC21listPolicyAssignments8policyId12assignToType0klJ06marker5limit6fields10completionySS_SSSgA2LSiSgSaySSGSgys6ResultOyAA14PagingIteratorCyAA0c4HoldG10AssignmentCGAA0A8SDKErrorCGctF) with the ID of a policy. This method will return an iterator object, which is used to retrieve policy assignments for a policy. ``` let iterator = client.legalHolds.listPolicyAssignments(policyId: "1234") iterator.next { results in switch results { case let .success(page): for assignment in page.entries { print("Policy Assignment \(assignment.id)") } case let .failure(error): print(error) } } ``` ## Assign Policy To assign a legal hold policy, call [`client.legalHolds.forceApply(policyId: String, assignToId: String, assignToType: String, fields: [String]?, completion: @escaping Callback<LegalHoldPolicyAssignment>`](https://opensource.box.com/box-ios-sdk/Classes/LegalHoldsModule.html#/s:6BoxSDK16LegalHoldsModuleC12assignPolicy8policyId0f2ToI00fJ4Type6fields10completionySS_S2SSaySSGSgys6ResultOyAA0c4HoldG10AssignmentCAA0A8SDKErrorCGctF) with an ID of a policy, an ID of a file, file version, folder, or user and the type of the box item that the policy is being assigned to. ``` client.legalHolds.forceApply(policyId: "1234", assignToId: "4568" ,assignToType: "file") { (result: Result<LegalHoldPolicyAssignment, BoxSDKError>) in guard case let .success(assignment) = result else { print("Error assigning legal hold policy") return } print("Assigned a legal hold policy at \"\(assignment.assignedAt)\"") } ``` ## Delete Policy Assignment To delete a legal hold policy assignment, call [`client.legalHolds.deletePolicyAssignment(policyId: String, completion: @escaping Callback<Void>`](https://opensource.box.com/box-ios-sdk/Classes/LegalHoldsModule.html#/s:6BoxSDK16LegalHoldsModuleC22deletePolicyAssignment12assignmentId10completionySS_ys6ResultOyytAA0A8SDKErrorCGctF) with the ID of the policy assignment to delete. ``` client.legalHolds.deletePolicyAssignment(assignmentId: "1234") { result: Result<Void, BoxSDKError>} in guard case .success = result else { print("Error deleting legal hold policy assignment") return } print("Legal hold policy assignment successfully deleted") } ``` ## Get File Version Legal Hold Info To retrieve information about a file version legal hold, call [`client.legalHolds.getFileVersionPolicy(legalHoldId: String, fields: [String]?, completion: @escaping Callback<FileVersionLegalHold>)`](https://opensource.box.com/box-ios-sdk/Classes/LegalHoldsModule.html#/s:6BoxSDK16LegalHoldsModuleC20getFileVersionPolicy11legalHoldId6fields10completionySS_SaySSGSgys6ResultOyAA0ghcK0CAA0A8SDKErrorCGctF) with the ID of legal hold. You can control which fields are returned in the resulting `File Version Legal Hold` object by passing the `fields` parameter. ``` client.legalHolds.getFileVersionPolicy(legalHoldId: "22222") { (result: Result<FileVersionLegalHold, BoxSDKError>) in guard case let .success(legalHold) = result else { print("Error getting file version legal hold") return } print("File version legal hold ID is \(legalHold.id)") } ``` ## Get File Version Legal Holds To retrieve all of the non-deleted legal holds for a single legal hold policy, call [`client.legalHolds.listFileVersionPolicies(policyId: String, marker: String?, limit: String?, fields: [String]?)`](https://opensource.box.com/box-ios-sdk/Classes/LegalHoldsModule.html#/s:6BoxSDK16LegalHoldsModuleC23listFileVersionPolicies8policyId6marker5limit6fields10completionySS_SSSgSiSgSaySSGSgys6ResultOyAA14PagingIteratorCyAA0ghC4HoldCGAA0A8SDKErrorCGctF) with the ID of a policy. This method will return an iterator object, which is used to retrieve legal holds for a policy. ``` let iterator = client.legalHolds.listFileVersionPolicies(policyId: "1234") iterator.next { result in switch results { case let .success(page): for hold in page.entries { print("Legal hold \(hold.id)") } case let .failure(error): print(error) } } ``` --- ### Legal Holds **Type:** page | **Section:** Additional Resources Legal Holds Get Legal Hold Policy Info Create Legal Hold Policy Update Legal Hold Policy Delete Legal Hold Policy Get Legal Hold Policies… # Legal Holds - [Get Legal Hold Policy Info](#get-legal-hold-policy-info) - [Create Legal Hold Policy](#create-legal-hold-policy) - [Update Legal Hold Policy](#update-legal-hold-policy) - [Delete Legal Hold Policy](#delete-legal-hold-policy) - [Get Legal Hold Policies](#get-legal-hold-policies) - [Get Policy Assignment Info](#get-policy-assignment-info) - [Create Policy Assignment](#create-policy-assignment) - [Delete Policy Assignment](#delete-policy-assignment) - [Get Policy Assignments](#get-policy-assignments) - [Get File Version Legal Hold Info](#get-file-version-legal-hold-info) - [Get File Version Legal Holds](#get-file-version-legal-holds) ## Get Legal Hold Policy Info To retrieve information about a legal hold policy, call [`client.legalHolds.get(policyId: String, fields: [String]?, completion: @escaping Callback<LegalHoldPolicy>)`](https://opensource.box.com/box-ios-sdk/Classes/LegalHoldsModule.html#/s:6BoxSDK16LegalHoldsModuleC3get8policyId6fields10completionySS_SaySSGSgys6ResultOyAA0C10HoldPolicyCAA0A8SDKErrorCGctF) with the ID of the policy. You can control which fields are returned in the resulting `Legal Hold Policy` object by passing the `fields` parameter. ``` client.legalHolds.get(policyId: "22222", fields: ["name", "created_at"]) { (result: Result<LegalHoldPolicy, BoxSDKError>) in guard case let .success(policy) = result else { print("Error getting policy information") return } print("Legal hold policy \(policy.id) was created at \(policy.createdAt)") } ``` ## Get Legal Hold Policies To retrieve information about the items contained in a folder, call [`client.legalHolds.listForEnterprise(policyName: String, marker: String?, limit: Int?, fields: [String]?)`](https://opensource.box.com/box-ios-sdk/Classes/LegalHoldsModule.html#/s:6BoxSDK16LegalHoldsModuleC17listForEnterprise10policyName6marker5limit6fields10completionySSSg_AJSiSgSaySSGSgys6ResultOyAA14PagingIteratorCyAA0C10HoldPolicyCGAA0A8SDKErrorCGctF) with the ID of the policy. This method will return an iterator object, which is used to retrieve policies in the enterprise. ``` let iterator = client.legalHolds.listForEnterprise(policyName: "policy1") iterator.next { results in switch results { case let .success(page): for policy in page.entries { print("Legal hold policy \(policy.name)") } case let .failure(error): print(error) } } ``` ## Create Legal Hold Policy To create a new legal hold policy, call [`client.legalHolds.create(policyName: String, description: String? filterStartedAt: Date?, filterEndedAt: Date?, isOngoing: Bool?, fields: [String]?, completion: @escaping Callback<LegalHoldPolicy>`](https://opensource.box.com/box-ios-sdk/Classes/LegalHoldsModule.html#/s:6BoxSDK16LegalHoldsModuleC6create10policyName11description15filterStartedAt0j5EndedL09isOngoing6fields10completionySS_SSSg10Foundation4DateVSgAPSbSgSaySSGSgys6ResultOyAA0C10HoldPolicyCAA0A8SDKErrorCGctF) with a name for the legal hold policy. ``` client.legalHolds.create(name: "New Folder") { (result: Result<LegalHoldPolicy, BoxSDKError>) in guard case let .success(policy) = result else { print("Error creating legal hold policy") return } print("Created legal hold policy \"\(policy.name)\"") } ``` ## Update Legal Hold Policy To update legal hold policy, call [`client.legalHolds.update(policyId: String, policyName: String?, description: String?, releaseNotes: String?, fields: [String]?, completion: @escaping Callback<LegalHoldPolicy>`](https://opensource.box.com/box-ios-sdk/Classes/LegalHoldsModule.html#/s:6BoxSDK16LegalHoldsModuleC6update8policyId0G4Name11description12releaseNotes6fields10completionySS_SSSgA2KSaySSGSgys6ResultOyAA0C10HoldPolicyCAA0A8SDKErrorCGctF). ``` client.legalHolds.update(policyId: "1234", policyName: "New Name") { (result: Result<LegalHoldPolicy, BoxSDKError>) in guard case let .success(policy) = result else { print("Error updating legal hold policy") return } print("Updated legal hold policy name is \"\(policy.name)\"") } ``` ## Delete Legal Hold Policy To delete a legal hold policy, call [`client.folders.delete(policyId: String, completion: @escaping Callback<Void>`](https://opensource.box.com/box-ios-sdk/Classes/LegalHoldsModule.html#/s:6BoxSDK16LegalHoldsModuleC6delete8policyId10completionySS_ys6ResultOyytAA0A8SDKErrorCGctF) with the ID of the legal hold policy to delete. ``` client.legalHolds.delete() { result: Result<Void, BoxSDKError>} in guard case .success = result else { print("Error deleting legal hold policy") return } print("Legal hold policy successfully deleted") } ``` ## Get Policy Assignment Info To retrieve information about a legal hold policy assignment, call [`client.legalHolds.getPolicyAssignment(assignmentId: String, fields: [String]?, completion: @escaping Callback<LegalHoldPolicyAssignment>)`](https://opensource.box.com/box-ios-sdk/Classes/LegalHoldsModule.html#/s:6BoxSDK16LegalHoldsModuleC19getPolicyAssignment12assignmentId6fields10completionySS_SaySSGSgys6ResultOyAA0c4HoldgH0CAA0A8SDKErrorCGctF) with the ID of the policy assignment. You can control which fields are returned in the resulting `Legal Hold Policy Assignment` object by passing the `fields` parameter. ``` client.legalHolds.getPolicyAssignment(assignmentId: "22222", fields: ["assigned_at"]) { (result: Result<LegalHoldPolicyAssignment, BoxSDKError>) in guard case let .success(assignment) = result else { print("Error getting policy assignment info") return } print("Legal hold policy assignment \(assignmnent.id) was created at \(assignment.assignedAt)") } ``` ## Get Policy Assignments To retrieve legal hold policy assignments, call [`client.legalHolds.listPolicyAssignments(policyId: String, assignToType: String?, assignToId: String?, marker: String?, limit: String?, fields: [String]?)`](https://opensource.box.com/box-ios-sdk/Classes/LegalHoldsModule.html#/s:6BoxSDK16LegalHoldsModuleC21listPolicyAssignments8policyId12assignToType0klJ06marker5limit6fields10completionySS_SSSgA2LSiSgSaySSGSgys6ResultOyAA14PagingIteratorCyAA0c4HoldG10AssignmentCGAA0A8SDKErrorCGctF) with the ID of a policy. This method will return an iterator object, which is used to retrieve policy assignments for a policy. ``` let iterator = client.legalHolds.listPolicyAssignments(policyId: "1234") iterator.next { results in switch results { case let .success(page): for assignment in page.entries { print("Policy Assignment \(assignment.id)") } case let .failure(error): print(error) } } ``` ## Assign Policy To assign a legal hold policy, call [`client.legalHolds.forceApply(policyId: String, assignToId: String, assignToType: String, fields: [String]?, completion: @escaping Callback<LegalHoldPolicyAssignment>`](https://opensource.box.com/box-ios-sdk/Classes/LegalHoldsModule.html#/s:6BoxSDK16LegalHoldsModuleC12assignPolicy8policyId0f2ToI00fJ4Type6fields10completionySS_S2SSaySSGSgys6ResultOyAA0c4HoldG10AssignmentCAA0A8SDKErrorCGctF) with an ID of a policy, an ID of a file, file version, folder, or user and the type of the box item that the policy is being assigned to. ``` client.legalHolds.forceApply(policyId: "1234", assignToId: "4568" ,assignToType: "file") { (result: Result<LegalHoldPolicyAssignment, BoxSDKError>) in guard case let .success(assignment) = result else { print("Error assigning legal hold policy") return } print("Assigned a legal hold policy at \"\(assignment.assignedAt)\"") } ``` ## Delete Policy Assignment To delete a legal hold policy assignment, call [`client.legalHolds.deletePolicyAssignment(policyId: String, completion: @escaping Callback<Void>`](https://opensource.box.com/box-ios-sdk/Classes/LegalHoldsModule.html#/s:6BoxSDK16LegalHoldsModuleC22deletePolicyAssignment12assignmentId10completionySS_ys6ResultOyytAA0A8SDKErrorCGctF) with the ID of the policy assignment to delete. ``` client.legalHolds.deletePolicyAssignment(assignmentId: "1234") { result: Result<Void, BoxSDKError>} in guard case .success = result else { print("Error deleting legal hold policy assignment") return } print("Legal hold policy assignment successfully deleted") } ``` ## Get File Version Legal Hold Info To retrieve information about a file version legal hold, call [`client.legalHolds.getFileVersionPolicy(legalHoldId: String, fields: [String]?, completion: @escaping Callback<FileVersionLegalHold>)`](https://opensource.box.com/box-ios-sdk/Classes/LegalHoldsModule.html#/s:6BoxSDK16LegalHoldsModuleC20getFileVersionPolicy11legalHoldId6fields10completionySS_SaySSGSgys6ResultOyAA0ghcK0CAA0A8SDKErrorCGctF) with the ID of legal hold. You can control which fields are returned in the resulting `File Version Legal Hold` object by passing the `fields` parameter. ``` client.legalHolds.getFileVersionPolicy(legalHoldId: "22222") { (result: Result<FileVersionLegalHold, BoxSDKError>) in guard case let .success(legalHold) = result else { print("Error getting file version legal hold") return } print("File version legal hold ID is \(legalHold.id)") } ``` ## Get File Version Legal Holds To retrieve all of the non-deleted legal holds for a single legal hold policy, call [`client.legalHolds.listFileVersionPolicies(policyId: String, marker: String?, limit: String?, fields: [String]?)`](https://opensource.box.com/box-ios-sdk/Classes/LegalHoldsModule.html#/s:6BoxSDK16LegalHoldsModuleC23listFileVersionPolicies8policyId6marker5limit6fields10completionySS_SSSgSiSgSaySSGSgys6ResultOyAA14PagingIteratorCyAA0ghC4HoldCGAA0A8SDKErrorCGctF) with the ID of a policy. This method will return an iterator object, which is used to retrieve legal holds for a policy. ``` let iterator = client.legalHolds.listFileVersionPolicies(policyId: "1234") iterator.next { result in switch results { case let .success(page): for hold in page.entries { print("Legal hold \(hold.id)") } case let .failure(error): print(error) } } ``` --- ### Legal Holds Policy **Type:** page | **Section:** Additional Resources Legal Holds Policy Legal Hold Policy information describes the basic characteristics of the Policy, such as name, description, and filter… # Legal Holds Policy Legal Hold Policy information describes the basic characteristics of the Policy, such as name, description, and filter dates. - [Get Legal Hold Policy](#get-legal-hold-policy) - [Get List of Legal Hold Policies](#get-list-of-legal-hold-policies) - [Create New Legal Hold Policy](#create-new-legal-hold-policy) - [Update Existing Legal Hold Policy](#update-existing-legal-hold-policy) - [Delete Legal Hold Policy](#delete-legal-hold-policy) - [Get Assignment](#get-assignment) - [Get List of Assignments](#get-list-of-assignments) - [Create New Assignment](#create-new-assignment) - [Delete Assignment](#delete-assignment) - [Get File Version Legal Hold](#get-file-version-legal-hold) - [Get List of File Version Legal Holds](#get-list-of-file-version-legal-holds) ## Get Legal Hold Policy Calling [`getInfo(String...)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxLegalHoldPolicy.html#getInfo-java.lang.String...-) will return a BoxLegalHoldPolicy.Info object containing information about the legal hold policy. If necessary to retrieve limited set of fields, it is possible to specify them using param. ``` BoxLegalHoldPolicy policy = new BoxLegalHoldPolicy(api, id); BoxLegalHoldPolicy.Info policyInfo = policy.getInfo(); ``` ## Get List of Legal Hold Policies Calling the static [`getAll(BoxAPIConnection)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxLegalHoldPolicy.html#getAll-com.box.sdk.BoxAPIConnection-) will return an iterable that will page through all of the legal hold policies. It is possible to specify name of legal hold policy, maximum number of items per response and fields to retrieve by calling the static [`getAll(BoxAPIConnection, String, int, String...)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxLegalHoldPolicy.html#getAll-com.box.sdk.BoxAPIConnection-java.lang.String-int-java.lang.String...-) method. ``` Iterable<BoxLegalHoldPolicy.Info> policies = BoxLegalHoldPolicy.getAll(api); for (BoxLegalHoldPolicy.Info policyInfo : policies) { // Do something with the legal hold policy. } ``` ## Create New Legal Hold Policy The static [`create(BoxAPIConnection api, String name, String description, Date startDate, Date endDate)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxLegalHoldPolicy.html#create-com.box.sdk.BoxAPIConnection-java.lang.String-java.lang.String-java.util.Date-java.util.Date-) method will let you create a new legal hold policy with a specified name, description, start and end dates. ``` BoxLegalHoldPolicy.Info policyInfo = BoxLegalHoldPolicy.create(api, name, description, startedAt, endedAt); ``` If you wish to create an ongoing Legal Hold Policy with no end date and a description, call [`createOngoing(BoxAPIConnection api, String name, String description)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxLegalHoldPolicy.html#createOngoing-com.box.sdk.BoxAPIConnection-java.lang.String-java.lang.String-). ``` BoxLegalHoldPolicy.Info policyInfo = BoxLegalHoldPolicy.createOngoing(api, name, description); ``` ## Update Existing Legal Hold Policy Updating a legal hold policy's information is done by calling [`updateInfo(BoxLegalHoldPolicy.Info fieldsToUpdate)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxLegalHoldPolicy.html#updateInfo-com.box.sdk.BoxLegalHoldPolicy.Info-). ``` BoxLegalHoldPolicy policy = new BoxLegalHoldPolicy(api, id); BoxLegalHoldPolicy.Info policyInfo = policy.new Info(); info.setDescription("new description"); info.setPolicyName("new policy name"); policy.updateInfo(info); ``` ## Delete Legal Hold Policy A legal hold policy can be deleted by calling the [`delete()`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxLegalHoldPolicy.html#delete--) method. ``` BoxLegalHoldPolicy policy = new BoxLegalHoldPolicy(api, id); policy.delete(); ``` ## Get Assignment Calling [`getInfo(String... fields)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxLegalHoldAssignment.html#getInfo-java.lang.String...-) will return a BoxLegalHoldAssignment.Info object containing information about the legal hold policy assignment. ``` BoxLegalHoldAssignment assignment = new BoxLegalHoldAssignment(api, id); BoxLegalHoldAssignment.Info info = assignment.getInfo("assigned_by"); ``` ## Get List of Assignments Calling the static [`getAssignments(String... fields)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxLegalHoldPolicy.html#getAssignments-java.lang.String...-) will return an iterable that will page through all of the assignments of the legal hold policy. It is possible to specify filters for type and id, maximum number of items per single response and fields to retrieve by calling [`getAssignments(String type, String id, int limit, String... fields)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxLegalHoldPolicy.html#getAssignments-java.lang.String-java.lang.String-int-java.lang.String...-). ``` BoxLegalHoldPolicy policy = new BoxLegalHoldPolicy(api, id); Iterable<BoxLegalHoldAssignment.Info> assignments = policy.getAssignments(BoxResource.getResourceType(BoxFolder.class), null, 50, "assigned_at"); for (BoxLegalHoldAssignment.Info assignmentInfo : assignments) { // Do something with the legal hold policy assignment. } ``` ## Create New Assignment To create new legal hold policy assignment call [`assignTo(BoxResource target)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxLegalHoldPolicy.html#assignTo-com.box.sdk.BoxResource-) method. Currently only BoxFile, BoxFileVersion, BoxFolder and BoxUser objects are supported as a parameter. ``` BoxLegalHoldPolicy policy = new BoxLegalHoldPolicy(api, policyID); BoxFolder folder = new BoxFolder(api, folderID); policy.assignTo(folder); ``` ## Delete Assignment A legal hold policy assignment can be deleted by calling the [`delete()`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxLegalHoldAssignment.html#delete--) method of BoxLegalHoldAssignment object. ``` BoxLegalHoldAssignment assignment = new BoxLegalHoldAssignment(api, id); assignment.delete(); ``` ## Get File Version Legal Hold Calling [`getInfo(String... fields)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFileVersionLegalHold.html#getInfo-java.lang.String...-) will return a BoxFileVersionLegalHold.Info object containing information about the file version legal hold policy. ``` BoxFileVersionLegalHold hold = new BoxFileVersionLegalHold(api, id); hold.getInfo("file"); ``` ## Get List of File Version Legal Holds To get an iterable with all non-deleted file version legal holds for current legal hold policy, call [`getFileVersionHolds(String... fields)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxLegalHoldPolicy.html#getFileVersionHolds-java.lang.String...-). It is possible to specify maximum number of items per single response by calling [`getFileVersionHolds(int limit, String... fields)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxLegalHoldPolicy.html#getFileVersionHolds-int-java.lang.String...-). ``` BoxLegalHoldPolicy policy = new BoxLegalHoldPolicy(api, id); Iterable<BoxFileVersionLegalHold.Info> fileVersionHolds = policy.getFileVersionHolds(); for (BoxFileVersionLegalHold.Info fileVersionHold : fileVersionHolds) { // Do something with the file version legal hold. } ``` --- ### LegalHoldPoliciesManager **Type:** page | **Section:** Additional Resources LegalHoldPoliciesManager List all legal hold policies Create legal hold policy Get legal hold policy Update legal hold policy Remove legal… # LegalHoldPoliciesManager - [List all legal hold policies](#list-all-legal-hold-policies) - [Create legal hold policy](#create-legal-hold-policy) - [Get legal hold policy](#get-legal-hold-policy) - [Update legal hold policy](#update-legal-hold-policy) - [Remove legal hold policy](#remove-legal-hold-policy) ## List all legal hold policies Retrieves a list of legal hold policies that belong to an enterprise. This operation is performed by calling function `getLegalHoldPolicies`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-legal-hold-policies/). ``` await client.legalHoldPolicies.getLegalHoldPolicies(); ``` ### Arguments queryParams `GetLegalHoldPoliciesQueryParams` - Query parameters of getLegalHoldPolicies method headersInput `GetLegalHoldPoliciesHeadersInput` - Headers of getLegalHoldPolicies method cancellationToken `undefined | CancellationToken` - Token used for request cancellation. ### Returns This function returns a value of type `LegalHoldPolicies`. Returns a list of legal hold policies. ## Create legal hold policy Create a new legal hold policy. This operation is performed by calling function `createLegalHoldPolicy`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-legal-hold-policies/). ``` await client.legalHoldPolicies.createLegalHoldPolicy({ policyName: legalHoldPolicyName, description: legalHoldDescription, isOngoing: false, filterStartedAt: filterStartedAt, filterEndedAt: filterEndedAt, } satisfies CreateLegalHoldPolicyRequestBody); ``` ### Arguments requestBody `CreateLegalHoldPolicyRequestBody` - Request body of createLegalHoldPolicy method optionalsInput `CreateLegalHoldPolicyOptionalsInput` ### Returns This function returns a value of type `LegalHoldPolicy`. Returns a new legal hold policy object. ## Get legal hold policy Retrieve a legal hold policy. This operation is performed by calling function `getLegalHoldPolicyById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-legal-hold-policies-id/). ``` await client.legalHoldPolicies.getLegalHoldPolicyById(legalHoldPolicyId); ``` ### Arguments legalHoldPolicyId `string` - The ID of the legal hold policy. Example: "324432" optionalsInput `GetLegalHoldPolicyByIdOptionalsInput` ### Returns This function returns a value of type `LegalHoldPolicy`. Returns a legal hold policy object. ## Update legal hold policy Update legal hold policy. This operation is performed by calling function `updateLegalHoldPolicyById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-legal-hold-policies-id/). ``` await client.legalHoldPolicies.updateLegalHoldPolicyById(legalHoldPolicyId, { requestBody: { policyName: updatedLegalHoldPolicyName, } satisfies UpdateLegalHoldPolicyByIdRequestBody, } satisfies UpdateLegalHoldPolicyByIdOptionalsInput); ``` ### Arguments legalHoldPolicyId `string` - The ID of the legal hold policy. Example: "324432" optionalsInput `UpdateLegalHoldPolicyByIdOptionalsInput` ### Returns This function returns a value of type `LegalHoldPolicy`. Returns a new legal hold policy object. ## Remove legal hold policy Delete an existing legal hold policy. This is an asynchronous process. The policy will not be fully deleted yet when the response returns. This operation is performed by calling function `deleteLegalHoldPolicyById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-legal-hold-policies-id/). ``` await client.legalHoldPolicies.deleteLegalHoldPolicyById(legalHoldPolicy.id); ``` ### Arguments legalHoldPolicyId `string` - The ID of the legal hold policy. Example: "324432" optionalsInput `DeleteLegalHoldPolicyByIdOptionalsInput` ### Returns This function returns a value of type `undefined`. A blank response is returned if the policy was successfully deleted. --- ### LegalHoldPoliciesManager **Type:** page | **Section:** Additional Resources LegalHoldPoliciesManager List all legal hold policies Create legal hold policy Get legal hold policy Update legal hold policy Remove legal… # LegalHoldPoliciesManager - [List all legal hold policies](#list-all-legal-hold-policies) - [Create legal hold policy](#create-legal-hold-policy) - [Get legal hold policy](#get-legal-hold-policy) - [Update legal hold policy](#update-legal-hold-policy) - [Remove legal hold policy](#remove-legal-hold-policy) ## List all legal hold policies Retrieves a list of legal hold policies that belong to an enterprise. This operation is performed by calling function `get_legal_hold_policies`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-legal-hold-policies/). ``` client.legal_hold_policies.get_legal_hold_policies() ``` ### Arguments policy_name `Optional[str]` - Limits results to policies for which the names start with this search term. This is a case-insensitive prefix. fields `Optional[List[str]]` - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested. marker `Optional[str]` - Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`. limit `Optional[int]` - The maximum number of items to return per page. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `LegalHoldPolicies`. Returns a list of legal hold policies. ## Create legal hold policy Create a new legal hold policy. This operation is performed by calling function `create_legal_hold_policy`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-legal-hold-policies/). ``` client.legal_hold_policies.create_legal_hold_policy( legal_hold_policy_name, description=legal_hold_description, filter_started_at=filter_started_at, filter_ended_at=filter_ended_at, is_ongoing=False, ) ``` ### Arguments policy_name `str` - The name of the policy. description `Optional[str]` - A description for the policy. filter_started_at `Optional[DateTime]` - The filter start date. When this policy is applied using a `custodian` legal hold assignments, it will only apply to file versions created or uploaded inside of the date range. Other assignment types, such as folders and files, will ignore the date filter. Required if `is_ongoing` is set to `false`. filter_ended_at `Optional[DateTime]` - The filter end date. When this policy is applied using a `custodian` legal hold assignments, it will only apply to file versions created or uploaded inside of the date range. Other assignment types, such as folders and files, will ignore the date filter. Required if `is_ongoing` is set to `false`. is_ongoing `Optional[bool]` - Whether new assignments under this policy should continue applying to files even after initialization. When this policy is applied using a legal hold assignment, it will continue applying the policy to any new file versions even after it has been applied. For example, if a legal hold assignment is placed on a user today, and that user uploads a file tomorrow, that file will get held. This will continue until the policy is retired. Required if no filter dates are set. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `LegalHoldPolicy`. Returns a new legal hold policy object. ## Get legal hold policy Retrieve a legal hold policy. This operation is performed by calling function `get_legal_hold_policy_by_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-legal-hold-policies-id/). ``` client.legal_hold_policies.get_legal_hold_policy_by_id(legal_hold_policy_id) ``` ### Arguments legal_hold_policy_id `str` - The ID of the legal hold policy. Example: "324432" extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `LegalHoldPolicy`. Returns a legal hold policy object. ## Update legal hold policy Update legal hold policy. This operation is performed by calling function `update_legal_hold_policy_by_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-legal-hold-policies-id/). ``` client.legal_hold_policies.update_legal_hold_policy_by_id( legal_hold_policy_id, policy_name=updated_legal_hold_policy_name ) ``` ### Arguments legal_hold_policy_id `str` - The ID of the legal hold policy. Example: "324432" policy_name `Optional[str]` - The name of the policy. description `Optional[str]` - A description for the policy. release_notes `Optional[str]` - Notes around why the policy was released. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `LegalHoldPolicy`. Returns a new legal hold policy object. ## Remove legal hold policy Delete an existing legal hold policy. This is an asynchronous process. The policy will not be fully deleted yet when the response returns. This operation is performed by calling function `delete_legal_hold_policy_by_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-legal-hold-policies-id/). ``` client.legal_hold_policies.delete_legal_hold_policy_by_id(legal_hold_policy.id) ``` ### Arguments legal_hold_policy_id `str` - The ID of the legal hold policy. Example: "324432" extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `None`. A blank response is returned if the policy was successfully deleted. --- ### LegalHoldPolicyAssignmentsManager **Type:** page | **Section:** Additional Resources LegalHoldPolicyAssignmentsManager List legal hold policy assignments Assign legal hold policy Get legal hold policy assignment Unassign… # LegalHoldPolicyAssignmentsManager - [List legal hold policy assignments](#list-legal-hold-policy-assignments) - [Assign legal hold policy](#assign-legal-hold-policy) - [Get legal hold policy assignment](#get-legal-hold-policy-assignment) - [Unassign legal hold policy](#unassign-legal-hold-policy) - [List files with current file versions for legal hold policy assignment](#list-files-with-current-file-versions-for-legal-hold-policy-assignment) ## List legal hold policy assignments Retrieves a list of items a legal hold policy has been assigned to. This operation is performed by calling function `getLegalHoldPolicyAssignments`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-legal-hold-policy-assignments/). ``` await client.legalHoldPolicyAssignments.getLegalHoldPolicyAssignments({ policyId: legalHoldPolicyId, } satisfies GetLegalHoldPolicyAssignmentsQueryParams); ``` ### Arguments queryParams `GetLegalHoldPolicyAssignmentsQueryParams` - Query parameters of getLegalHoldPolicyAssignments method optionalsInput `GetLegalHoldPolicyAssignmentsOptionalsInput` ### Returns This function returns a value of type `LegalHoldPolicyAssignments`. Returns a list of legal hold policy assignments. ## Assign legal hold policy Assign a legal hold to a file, file version, folder, or user. This operation is performed by calling function `createLegalHoldPolicyAssignment`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-legal-hold-policy-assignments/). ``` await client.legalHoldPolicyAssignments.createLegalHoldPolicyAssignment({ policyId: legalHoldPolicyId, assignTo: { type: 'file' as CreateLegalHoldPolicyAssignmentRequestBodyAssignToTypeField, id: fileId, } satisfies CreateLegalHoldPolicyAssignmentRequestBodyAssignToField, } satisfies CreateLegalHoldPolicyAssignmentRequestBody); ``` ### Arguments requestBody `CreateLegalHoldPolicyAssignmentRequestBody` - Request body of createLegalHoldPolicyAssignment method optionalsInput `CreateLegalHoldPolicyAssignmentOptionalsInput` ### Returns This function returns a value of type `LegalHoldPolicyAssignment`. Returns a new legal hold policy assignment. ## Get legal hold policy assignment Retrieve a legal hold policy assignment. This operation is performed by calling function `getLegalHoldPolicyAssignmentById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-legal-hold-policy-assignments-id/). ``` await client.legalHoldPolicyAssignments.getLegalHoldPolicyAssignmentById( legalHoldPolicyAssignmentId, ); ``` ### Arguments legalHoldPolicyAssignmentId `string` - The ID of the legal hold policy assignment. Example: "753465" optionalsInput `GetLegalHoldPolicyAssignmentByIdOptionalsInput` ### Returns This function returns a value of type `LegalHoldPolicyAssignment`. Returns a legal hold policy object. ## Unassign legal hold policy Remove a legal hold from an item. This is an asynchronous process. The policy will not be fully removed yet when the response returns. This operation is performed by calling function `deleteLegalHoldPolicyAssignmentById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-legal-hold-policy-assignments-id/). ``` await client.legalHoldPolicyAssignments.deleteLegalHoldPolicyAssignmentById( legalHoldPolicyAssignmentId, ); ``` ### Arguments legalHoldPolicyAssignmentId `string` - The ID of the legal hold policy assignment. Example: "753465" optionalsInput `DeleteLegalHoldPolicyAssignmentByIdOptionalsInput` ### Returns This function returns a value of type `undefined`. A blank response is returned if the assignment was successfully deleted. ## List files with current file versions for legal hold policy assignment Get a list of files with current file versions for a legal hold assignment. In some cases you may want to get previous file versions instead. In these cases, use the `GET /legal_hold_policy_assignments/:id/file_versions_on_hold` API instead to return any previous versions of a file for this legal hold policy assignment. Due to ongoing re-architecture efforts this API might not return all file versions held for this policy ID. Instead, this API will only return the latest file version held in the newly developed architecture. The `GET /file_version_legal_holds` API can be used to fetch current and past versions of files held within the legacy architecture. This endpoint does not support returning any content that is on hold due to a Custodian collaborating on a Hub. The `GET /legal_hold_policy_assignments?policy_id={id}` API can be used to find a list of policy assignments for a given policy ID. This operation is performed by calling function `getLegalHoldPolicyAssignmentFileOnHold`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-legal-hold-policy-assignments-id-files-on-hold/). ``` await client.legalHoldPolicyAssignments.getLegalHoldPolicyAssignmentFileOnHold( legalHoldPolicyAssignmentId, ); ``` ### Arguments legalHoldPolicyAssignmentId `string` - The ID of the legal hold policy assignment. Example: "753465" optionalsInput `GetLegalHoldPolicyAssignmentFileOnHoldOptionalsInput` ### Returns This function returns a value of type `FilesOnHold`. Returns the list of current file versions held under legal hold for a specific legal hold policy assignment. --- ### LegalHoldPolicyAssignmentsManager **Type:** page | **Section:** Additional Resources LegalHoldPolicyAssignmentsManager List legal hold policy assignments Assign legal hold policy Get legal hold policy assignment Unassign… # LegalHoldPolicyAssignmentsManager - [List legal hold policy assignments](#list-legal-hold-policy-assignments) - [Assign legal hold policy](#assign-legal-hold-policy) - [Get legal hold policy assignment](#get-legal-hold-policy-assignment) - [Unassign legal hold policy](#unassign-legal-hold-policy) - [List files with current file versions for legal hold policy assignment](#list-files-with-current-file-versions-for-legal-hold-policy-assignment) ## List legal hold policy assignments Retrieves a list of items a legal hold policy has been assigned to. This operation is performed by calling function `get_legal_hold_policy_assignments`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-legal-hold-policy-assignments/). ``` client.legal_hold_policy_assignments.get_legal_hold_policy_assignments( legal_hold_policy_id ) ``` ### Arguments policy_id `str` - The ID of the legal hold policy. assign_to_type `Optional[GetLegalHoldPolicyAssignmentsAssignToType]` - Filters the results by the type of item the policy was applied to. assign_to_id `Optional[str]` - Filters the results by the ID of item the policy was applied to. marker `Optional[str]` - Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`. limit `Optional[int]` - The maximum number of items to return per page. fields `Optional[List[str]]` - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `LegalHoldPolicyAssignments`. Returns a list of legal hold policy assignments. ## Assign legal hold policy Assign a legal hold to a file, file version, folder, or user. This operation is performed by calling function `create_legal_hold_policy_assignment`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-legal-hold-policy-assignments/). ``` client.legal_hold_policy_assignments.create_legal_hold_policy_assignment( legal_hold_policy_id, CreateLegalHoldPolicyAssignmentAssignTo( type=CreateLegalHoldPolicyAssignmentAssignToTypeField.FILE, id=file_id ), ) ``` ### Arguments policy_id `str` - The ID of the policy to assign. assign_to `CreateLegalHoldPolicyAssignmentAssignTo` - The item to assign the policy to. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `LegalHoldPolicyAssignment`. Returns a new legal hold policy assignment. ## Get legal hold policy assignment Retrieve a legal hold policy assignment. This operation is performed by calling function `get_legal_hold_policy_assignment_by_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-legal-hold-policy-assignments-id/). ``` client.legal_hold_policy_assignments.get_legal_hold_policy_assignment_by_id( legal_hold_policy_assignment_id ) ``` ### Arguments legal_hold_policy_assignment_id `str` - The ID of the legal hold policy assignment. Example: "753465" extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `LegalHoldPolicyAssignment`. Returns a legal hold policy object. ## Unassign legal hold policy Remove a legal hold from an item. This is an asynchronous process. The policy will not be fully removed yet when the response returns. This operation is performed by calling function `delete_legal_hold_policy_assignment_by_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-legal-hold-policy-assignments-id/). ``` client.legal_hold_policy_assignments.delete_legal_hold_policy_assignment_by_id( legal_hold_policy_assignment_id ) ``` ### Arguments legal_hold_policy_assignment_id `str` - The ID of the legal hold policy assignment. Example: "753465" extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `None`. A blank response is returned if the assignment was successfully deleted. ## List files with current file versions for legal hold policy assignment Get a list of files with current file versions for a legal hold assignment. In some cases you may want to get previous file versions instead. In these cases, use the `GET /legal_hold_policy_assignments/:id/file_versions_on_hold` API instead to return any previous versions of a file for this legal hold policy assignment. Due to ongoing re-architecture efforts this API might not return all file versions held for this policy ID. Instead, this API will only return the latest file version held in the newly developed architecture. The `GET /file_version_legal_holds` API can be used to fetch current and past versions of files held within the legacy architecture. This endpoint does not support returning any content that is on hold due to a Custodian collaborating on a Hub. The `GET /legal_hold_policy_assignments?policy_id={id}` API can be used to find a list of policy assignments for a given policy ID. This operation is performed by calling function `get_legal_hold_policy_assignment_file_on_hold`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-legal-hold-policy-assignments-id-files-on-hold/). ``` client.legal_hold_policy_assignments.get_legal_hold_policy_assignment_file_on_hold( legal_hold_policy_assignment_id ) ``` ### Arguments legal_hold_policy_assignment_id `str` - The ID of the legal hold policy assignment. Example: "753465" marker `Optional[str]` - Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`. limit `Optional[int]` - The maximum number of items to return per page. fields `Optional[List[str]]` - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `FilesOnHold`. Returns the list of current file versions held under legal hold for a specific legal hold policy assignment. --- ### ListCollaborationsManager **Type:** page | **Section:** Additional Resources ListCollaborationsManager List file collaborations List folder collaborations List pending collaborations List group collaborations List… # ListCollaborationsManager - [List file collaborations](#list-file-collaborations) - [List folder collaborations](#list-folder-collaborations) - [List pending collaborations](#list-pending-collaborations) - [List group collaborations](#list-group-collaborations) ## List file collaborations Retrieves a list of pending and active collaborations for a file. This returns all the users that have access to the file or have been invited to the file. This operation is performed by calling function `getFileCollaborations`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-files-id-collaborations/). ``` await client.listCollaborations.getFileCollaborations(file.id); ``` ### Arguments fileId `string` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" optionalsInput `GetFileCollaborationsOptionalsInput` ### Returns This function returns a value of type `Collaborations`. Returns a collection of collaboration objects. If there are no collaborations on this file an empty collection will be returned. This list includes pending collaborations, for which the `status` is set to `pending`, indicating invitations that have been sent but not yet accepted. ## List folder collaborations Retrieves a list of pending and active collaborations for a folder. This returns all the users that have access to the folder or have been invited to the folder. This operation is performed by calling function `getFolderCollaborations`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-folders-id-collaborations/). ``` await client.listCollaborations.getFolderCollaborations(folder.id); ``` ### Arguments folderId `string` - The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. Example: "12345" optionalsInput `GetFolderCollaborationsOptionalsInput` ### Returns This function returns a value of type `Collaborations`. Returns a collection of collaboration objects. If there are no collaborations on this folder an empty collection will be returned. This list includes pending collaborations, for which the `status` is set to `pending`, indicating invitations that have been sent but not yet accepted. ## List pending collaborations Retrieves all pending collaboration invites for this user. This operation is performed by calling function `getCollaborations`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-collaborations/). ``` await client.listCollaborations.getCollaborations({ status: 'pending' as GetCollaborationsQueryParamsStatusField, } satisfies GetCollaborationsQueryParams); ``` ### Arguments queryParams `GetCollaborationsQueryParams` - Query parameters of getCollaborations method optionalsInput `GetCollaborationsOptionalsInput` ### Returns This function returns a value of type `CollaborationsOffsetPaginated`. Returns a collection of pending collaboration objects. If the user has no pending collaborations, the collection will be empty. ## List group collaborations Retrieves all the collaborations for a group. The user must have admin permissions to inspect enterprise's groups. Each collaboration object has details on which files or folders the group has access to and with what role. This operation is performed by calling function `getGroupCollaborations`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-groups-id-collaborations/). ``` await client.listCollaborations.getGroupCollaborations(group.id); ``` ### Arguments groupId `string` - The ID of the group. Example: "57645" optionalsInput `GetGroupCollaborationsOptionalsInput` ### Returns This function returns a value of type `CollaborationsOffsetPaginated`. Returns a collection of collaboration objects. If there are no collaborations, an empty collection will be returned. --- ### ListCollaborationsManager **Type:** page | **Section:** Additional Resources ListCollaborationsManager List file collaborations List folder collaborations List pending collaborations List group collaborations List… # ListCollaborationsManager - [List file collaborations](#list-file-collaborations) - [List folder collaborations](#list-folder-collaborations) - [List pending collaborations](#list-pending-collaborations) - [List group collaborations](#list-group-collaborations) ## List file collaborations Retrieves a list of pending and active collaborations for a file. This returns all the users that have access to the file or have been invited to the file. This operation is performed by calling function `get_file_collaborations`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-files-id-collaborations/). ``` client.list_collaborations.get_file_collaborations(file.id) ``` ### Arguments file_id `str` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" fields `Optional[List[str]]` - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested. limit `Optional[int]` - The maximum number of items to return per page. marker `Optional[str]` - Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `Collaborations`. Returns a collection of collaboration objects. If there are no collaborations on this file an empty collection will be returned. This list includes pending collaborations, for which the `status` is set to `pending`, indicating invitations that have been sent but not yet accepted. ## List folder collaborations Retrieves a list of pending and active collaborations for a folder. This returns all the users that have access to the folder or have been invited to the folder. This operation is performed by calling function `get_folder_collaborations`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-folders-id-collaborations/). ``` client.list_collaborations.get_folder_collaborations(folder.id) ``` ### Arguments folder_id `str` - The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. Example: "12345" fields `Optional[List[str]]` - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested. limit `Optional[int]` - The maximum number of items to return per page. marker `Optional[str]` - Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `Collaborations`. Returns a collection of collaboration objects. If there are no collaborations on this folder an empty collection will be returned. This list includes pending collaborations, for which the `status` is set to `pending`, indicating invitations that have been sent but not yet accepted. ## List pending collaborations Retrieves all pending collaboration invites for this user. This operation is performed by calling function `get_collaborations`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-collaborations/). ``` client.list_collaborations.get_collaborations(GetCollaborationsStatus.PENDING) ``` ### Arguments status `GetCollaborationsStatus` - The status of the collaborations to retrieve. fields `Optional[List[str]]` - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested. offset `Optional[int]` - The offset of the item at which to begin the response. Queries with offset parameter value exceeding 10000 will be rejected with a 400 response. limit `Optional[int]` - The maximum number of items to return per page. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `CollaborationsOffsetPaginated`. Returns a collection of pending collaboration objects. If the user has no pending collaborations, the collection will be empty. ## List group collaborations Retrieves all the collaborations for a group. The user must have admin permissions to inspect enterprise's groups. Each collaboration object has details on which files or folders the group has access to and with what role. This operation is performed by calling function `get_group_collaborations`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-groups-id-collaborations/). ``` client.list_collaborations.get_group_collaborations(group.id) ``` ### Arguments group_id `str` - The ID of the group. Example: "57645" limit `Optional[int]` - The maximum number of items to return per page. offset `Optional[int]` - The offset of the item at which to begin the response. Queries with offset parameter value exceeding 10000 will be rejected with a 400 response. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `CollaborationsOffsetPaginated`. Returns a collection of collaboration objects. If there are no collaborations, an empty collection will be returned. --- ### Logging in SDK **Type:** page | **Section:** Additional Resources Logging in SDK We are using Java Util Logging within Box Java SDK. You can read about details of this approach here. Logging Levels We are… # Logging in SDK We are using `Java Util Logging` within Box Java SDK. You can read about details of this approach [here](https://docs.oracle.com/javase/8/docs/technotes/guides/logging/overview.html). ## Logging Levels We are using only few of the logging levels: - `FINE` - when logging debugging information, like success responses, - `WARNING` - when API returned 4xx response code, - `SEVERE` - when API returned 5XX response code. By default, the `Java Util Logging` prints to console output only messages that are logged at least at `INFO` level. You can limit what is being logged by setting desired level on `com.box.sdk` logger like this: ``` import com.box.sdk.BoxLogger; BoxLogger.defaultLogger().setLevelToError(); ``` Example above will limit printed logs to `SEVERE` level only. ### Getting FINE (ALL) logs printed By default `FINE` level logs are not printed to the console. There are several ways to do that. One way is to define custom handler: ``` import java.util.logging.ConsoleHandler; import java.util.logging.Handler; import java.util.logging.Level; import java.util.logging.Logger; Logger sdkLogger = BoxLogger.defaultLogger(); Handler systemOut = new ConsoleHandler(); // this handler will print any message to System.out systemOut.setLevel(Level.ALL); sdkLogger.addHandler(systemOut); // allow sdk logger to print FINE logs sdkLogger.setLevelToAll(); // prevent logs from being processed by default Console handler sdkLogger.setUseParentHandlers(false); ``` you can do this in your aplication initialization. ### Turn logging off To disable logging use `BoxLogger.defaultLogger().turnLoggingOff()`. ### Reset to default logging level To reset to default logging level use `BoxLogger.defaultLogger().resetToDefaultLevel()`. ## Putting SDK logs into application logs If you are using different logging solution like Log4J2 or Logstash you can use SLF4J and proper bridgge to get your logs into desired solution. Below is an example of adding SDK logs into Logstash. First you will need to add SLF4j and Logstash binaries: ``` implementation 'org.slf4j:jul-to-slf4j:1.7.32' // bridge from Java Util Logging to SLF4J API implementation 'org.slf4j:slf4j-api:1.7.32' // define SLF4J API implementation 'ch.qos.logback:logback-core:1.2.7' // use the Logback logging framework implementation 'ch.qos.logback:logback-classic:1.2.7' // get bindings between SLF4J and Logback ``` Now when initializing application you will need to make Java Util Logging to use SLF4J. This sample is based on description provided [here](http://www.slf4j.org/api/org/slf4j/bridge/SLF4JBridgeHandler.html): ``` import org.slf4j.bridge.SLF4JBridgeHandler; // Remove existing handlers attached to JUL root logger SLF4JBridgeHandler.removeHandlersForRootLogger(); // add SLF4JBridgeHandler to JUL's root logger SLF4JBridgeHandler.install(); ``` Now all logs generated by SDK will be captured by Logback. If you want to see debug logs from SDK you will need to add this configuration to your logback.xml file: ``` <logger name="com.box.sdk" level="DEBUG"/> ``` Below is a list of log levels used by SDK and coresponding Logback levels: | SDK | Logback | | --- | --- | | ALL | ALL | | OFF | OFF | | FINE | DEBUG | | INFO | INFO | | WARN | WARN | | SEVERE | ERROR | You can read more on java Util Logging to SLF4J bridge [here](http://www.slf4j.org/legacy.html#jul-to-slf4j). --- ### MembershipsManager **Type:** page | **Section:** Additional Resources MembershipsManager List user's groups List members of group Add user to group Get group membership Update group membership Remove user from… # MembershipsManager - [List user's groups](#list-users-groups) - [List members of group](#list-members-of-group) - [Add user to group](#add-user-to-group) - [Get group membership](#get-group-membership) - [Update group membership](#update-group-membership) - [Remove user from group](#remove-user-from-group) ## List user's groups Retrieves all the groups for a user. Only members of this group or users with admin-level permissions will be able to use this API. This operation is performed by calling function `getUserMemberships`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-users-id-memberships/). ``` await client.memberships.getUserMemberships(user.id); ``` ### Arguments userId `string` - The ID of the user. Example: "12345" optionalsInput `GetUserMembershipsOptionalsInput` ### Returns This function returns a value of type `GroupMemberships`. Returns a collection of membership objects. If there are no memberships, an empty collection will be returned. ## List members of group Retrieves all the members for a group. Only members of this group or users with admin-level permissions will be able to use this API. This operation is performed by calling function `getGroupMemberships`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-groups-id-memberships/). ``` await client.memberships.getGroupMemberships(group.id); ``` ### Arguments groupId `string` - The ID of the group. Example: "57645" optionalsInput `GetGroupMembershipsOptionalsInput` ### Returns This function returns a value of type `GroupMemberships`. Returns a collection of membership objects. If there are no memberships, an empty collection will be returned. ## Add user to group Creates a group membership. Only users with admin-level permissions will be able to use this API. This operation is performed by calling function `createGroupMembership`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-group-memberships/). ``` await client.memberships.createGroupMembership({ user: { id: user.id } satisfies CreateGroupMembershipRequestBodyUserField, group: { id: group.id } satisfies CreateGroupMembershipRequestBodyGroupField, } satisfies CreateGroupMembershipRequestBody); ``` ### Arguments requestBody `CreateGroupMembershipRequestBody` - Request body of createGroupMembership method optionalsInput `CreateGroupMembershipOptionalsInput` ### Returns This function returns a value of type `GroupMembership`. Returns a new group membership object. ## Get group membership Retrieves a specific group membership. Only admins of this group or users with admin-level permissions will be able to use this API. This operation is performed by calling function `getGroupMembershipById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-group-memberships-id/). ``` await client.memberships.getGroupMembershipById(groupMembership.id!); ``` ### Arguments groupMembershipId `string` - The ID of the group membership. Example: "434534" optionalsInput `GetGroupMembershipByIdOptionalsInput` ### Returns This function returns a value of type `GroupMembership`. Returns the group membership object. ## Update group membership Updates a user's group membership. Only admins of this group or users with admin-level permissions will be able to use this API. This operation is performed by calling function `updateGroupMembershipById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-group-memberships-id/). ``` await client.memberships.updateGroupMembershipById(groupMembership.id!, { requestBody: { role: 'admin' as UpdateGroupMembershipByIdRequestBodyRoleField, } satisfies UpdateGroupMembershipByIdRequestBody, } satisfies UpdateGroupMembershipByIdOptionalsInput); ``` ### Arguments groupMembershipId `string` - The ID of the group membership. Example: "434534" optionalsInput `UpdateGroupMembershipByIdOptionalsInput` ### Returns This function returns a value of type `GroupMembership`. Returns a new group membership object. ## Remove user from group Deletes a specific group membership. Only admins of this group or users with admin-level permissions will be able to use this API. This operation is performed by calling function `deleteGroupMembershipById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-group-memberships-id/). ``` await client.memberships.deleteGroupMembershipById(groupMembership.id!); ``` ### Arguments groupMembershipId `string` - The ID of the group membership. Example: "434534" optionalsInput `DeleteGroupMembershipByIdOptionalsInput` ### Returns This function returns a value of type `undefined`. A blank response is returned if the membership was successfully deleted. --- ### MembershipsManager **Type:** page | **Section:** Additional Resources MembershipsManager List user's groups List members of group Add user to group Get group membership Update group membership Remove user from… # MembershipsManager - [List user's groups](#list-users-groups) - [List members of group](#list-members-of-group) - [Add user to group](#add-user-to-group) - [Get group membership](#get-group-membership) - [Update group membership](#update-group-membership) - [Remove user from group](#remove-user-from-group) ## List user's groups Retrieves all the groups for a user. Only members of this group or users with admin-level permissions will be able to use this API. This operation is performed by calling function `get_user_memberships`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-users-id-memberships/). ``` client.memberships.get_user_memberships(user.id) ``` ### Arguments user_id `str` - The ID of the user. Example: "12345" limit `Optional[int]` - The maximum number of items to return per page. offset `Optional[int]` - The offset of the item at which to begin the response. Queries with offset parameter value exceeding 10000 will be rejected with a 400 response. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `GroupMemberships`. Returns a collection of membership objects. If there are no memberships, an empty collection will be returned. ## List members of group Retrieves all the members for a group. Only members of this group or users with admin-level permissions will be able to use this API. This operation is performed by calling function `get_group_memberships`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-groups-id-memberships/). ``` client.memberships.get_group_memberships(group.id) ``` ### Arguments group_id `str` - The ID of the group. Example: "57645" limit `Optional[int]` - The maximum number of items to return per page. offset `Optional[int]` - The offset of the item at which to begin the response. Queries with offset parameter value exceeding 10000 will be rejected with a 400 response. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `GroupMemberships`. Returns a collection of membership objects. If there are no memberships, an empty collection will be returned. ## Add user to group Creates a group membership. Only users with admin-level permissions will be able to use this API. This operation is performed by calling function `create_group_membership`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-group-memberships/). ``` client.memberships.create_group_membership( CreateGroupMembershipUser(id=user.id), CreateGroupMembershipGroup(id=group.id) ) ``` ### Arguments user `CreateGroupMembershipUser` - The user to add to the group. group `CreateGroupMembershipGroup` - The group to add the user to. role `Optional[CreateGroupMembershipRole]` - The role of the user in the group. configurable_permissions `Optional[Dict[str, bool]]` - Custom configuration for the permissions an admin if a group will receive. This option has no effect on members with a role of `member`. Setting these permissions overwrites the default access levels of an admin. Specifying a value of `null` for this object will disable all configurable permissions. Specifying permissions will set them accordingly, omitted permissions will be enabled by default. fields `Optional[List[str]]` - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `GroupMembership`. Returns a new group membership object. ## Get group membership Retrieves a specific group membership. Only admins of this group or users with admin-level permissions will be able to use this API. This operation is performed by calling function `get_group_membership_by_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-group-memberships-id/). ``` client.memberships.get_group_membership_by_id(group_membership.id) ``` ### Arguments group_membership_id `str` - The ID of the group membership. Example: "434534" fields `Optional[List[str]]` - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `GroupMembership`. Returns the group membership object. ## Update group membership Updates a user's group membership. Only admins of this group or users with admin-level permissions will be able to use this API. This operation is performed by calling function `update_group_membership_by_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-group-memberships-id/). ``` client.memberships.update_group_membership_by_id( group_membership.id, role=UpdateGroupMembershipByIdRole.ADMIN ) ``` ### Arguments group_membership_id `str` - The ID of the group membership. Example: "434534" role `Optional[UpdateGroupMembershipByIdRole]` - The role of the user in the group. configurable_permissions `Optional[Dict[str, bool]]` - Custom configuration for the permissions an admin if a group will receive. This option has no effect on members with a role of `member`. Setting these permissions overwrites the default access levels of an admin. Specifying a value of `null` for this object will disable all configurable permissions. Specifying permissions will set them accordingly, omitted permissions will be enabled by default. fields `Optional[List[str]]` - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `GroupMembership`. Returns a new group membership object. ## Remove user from group Deletes a specific group membership. Only admins of this group or users with admin-level permissions will be able to use this API. This operation is performed by calling function `delete_group_membership_by_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-group-memberships-id/). ``` client.memberships.delete_group_membership_by_id(group_membership.id) ``` ### Arguments group_membership_id `str` - The ID of the group membership. Example: "434534" extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `None`. A blank response is returned if the membership was successfully deleted. --- ### Metadata **Type:** page | **Section:** Additional Resources Metadata Metadata allows users and applications to define and store custom data associated with their files/folders. Metadata consists of… # Metadata Metadata allows users and applications to define and store custom data associated with their files/folders. Metadata consists of key:value pairs that belong to files/folders. For example, an important contract may have key:value pairs of `"clientNumber":"820183"` and `"clientName":"bioMedicalCorp"`. Metadata that belongs to a file/folder is grouped by templates. Templates allow the metadata service to provide a multitude of services, such as pre-defining sets of key:value pairs or schema enforcement on specific fields. Each file/folder can have multiple distinct template instances associated with it, and templates are also grouped by scopes. Currently, the only scopes support are `enterprise` and `global`. Enterprise scopes are defined on a per enterprises basis, whereas global scopes are Box application-wide. In addition to `enterprise` scoped templates, every file on Box has access to the `global` `properties` template. The Properties template is a bucket of free form key:value string pairs, with no additional schema associated with it. Properties are ideal for scenarios where applications want to write metadata to file objects in a flexible way, without pre-defined template structure. - [Create Metadata Template](#create-metadata-template) [Get Metadata Template](#get-metadata-template) - [Get by template scope and key](#get-by-template-scope-and-key) - [Get by ID](#get-by-id) [Update Metadata Template](#update-metadata-template) [Get Enterprise Metadata Templates](#get-enterprise-metadata-templates) [Delete Metadata Template](#delete-metadata-template) [Set Metadata on a File](#set-metadata-on-a-file) [Get Metadata on a File](#get-metadata-on-a-file) [Remove Metadata from a File](#remove-metadata-from-a-file) [Set Metadata on a Folder](#set-metadata-on-a-folder) [Get Metadata on a Folder](#get-metadata-on-a-folder) [Remove Metadata from a Folder](#remove-metadata-from-a-folder) [Create Cascade Policy](#create-cascade-policy) [Get Cascade Policy](#get-cascade-policy) [Get All Cascade Policies For a Folder](#get-all-cascade-policies-for-a-folder) [Force Apply Cascade Policy](#force-apply-cascade-policy) [Delete Cascade Policy](#delete-cascade-policy) [Query](#query) ## Create Metadata Template To create a new metadata template, call the [`metadata.createTemplate(templateName, fields, options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Metadata.html#createTemplate) method. ``` // Create a new template, but hide it for now until it's ready for use client.metadata.createTemplate( 'Vendor Contract', [ { type: 'date', key: 'signed', displayName: 'Date Signed' }, { type: 'string', key: 'vendor', displayName: 'Vendor' }, { type: 'enum', key: 'fy', displayName: 'Fiscal Year', options: [ {key: 'FY17'}, {key: 'FY18'}, {key: 'FY19'} ] } ], { hidden: true, templateKey: 'vcontract', copyInstanceOnItemCopy: false } ) .then(template => { /* template -> { id: '17f2d715-6acb-45f2-b96a-28b15efc9faa', templateKey: 'vcontract', scope: 'enterprise_12345', displayName: 'Vendor Contract', hidden: true, copyInstanceOnItemCopy: false, fields: [ { type: 'date', key: 'signed', displayName: 'Date Signed', hidden: false }, { type: 'string', key: 'vendor', displayName: 'Vendor', hidden: false }, { type: 'enum', key: 'fy', displayName: 'Fiscal Year', options: [ { key: 'FY17' }, { key: 'FY18' }, { key: 'FY19' } ], hidden: false } ] } */ }); ``` ## Get Metadata Template ### Get by template scope and key To retrieve a specific metadata template by its scope and template key, call the [`metadata.getTemplateSchema(scope, template, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Metadata.html#getTemplateSchema) method with the scope and template key. ``` client.metadata.getTemplateSchema('enterprise', 'vcontract') .then(template => { /* template -> { id: '17f2d715-6acb-45f2-b96a-28b15efc9faa', templateKey: 'vcontract', scope: 'enterprise_12345', displayName: 'Vendor Contract', hidden: true, fields: [ { type: 'date', key: 'signed', displayName: 'Date Signed', hidden: false }, { type: 'string', key: 'vendor', displayName: 'Vendor', hidden: false }, { type: 'enum', key: 'fy', displayName: 'Fiscal Year', options: [ { key: 'FY17' }, { key: 'FY18' }, { key: 'FY19' } ], hidden: false } ] } */ }); ``` ### Get by ID To get a specific metadata template by its ID, call the [`metadata.getTemplateByID(templateID, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Metadata.html#getTemplateByID) method with the ID of the template. ``` client.metadata.getTemplateByID('17f2d715-6acb-45f2-b96a-28b15efc9faa') .then(template => { /* template -> { id: '17f2d715-6acb-45f2-b96a-28b15efc9faa', templateKey: 'vcontract', scope: 'enterprise_12345', displayName: 'Vendor Contract', hidden: true, fields: [ { type: 'date', key: 'signed', displayName: 'Date Signed', hidden: false }, { type: 'string', key: 'vendor', displayName: 'Vendor', hidden: false }, { type: 'enum', key: 'fy', displayName: 'Fiscal Year', options: [ { key: 'FY17' }, { key: 'FY18' }, { key: 'FY19' } ], hidden: false } ] } */ }); ``` ## Update Metadata Template To update a metadata template, call the [`metadata.updateTemplate(scope, template, operations, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Metadata.html#updateTemplate) method with the operations to perform on the template. See the [API Documentation](https://developer.box.com/en/reference/put-metadata-templates-id-id-schema/) for more information on the operations available. ``` // Add a new option to the Fiscal Year field, and un-hide the template var operations = [ { op: 'addEnumOption', fieldKey: 'fy', data: { key: 'FY20' } }, { op: 'editTemplate', data: { hidden: false } } ]; client.metadata.updateTemplate('enterprise', 'vcontract', operations) .then(template => { /* template -> { templateKey: 'vcontract', scope: 'enterprise_12345', displayName: 'Vendor Contract', hidden: false, fields: [ { type: 'date', key: 'signed', displayName: 'Date Signed', hidden: false }, { type: 'string', key: 'vendor', displayName: 'Vendor', hidden: false }, { type: 'enum', key: 'fy', displayName: 'Fiscal Year', options: [ { key: 'FY17' }, { key: 'FY18' }, { key: 'FY19' }, { key: 'FY20' } ], hidden: false } ] } */ }); ``` ## Get Enterprise Metadata Templates Get all metadata templates for the current enterprise and scope by calling the [`metadata.getTemplates(scope, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Metadata.html#getTemplates) method. ``` client.metadata.getTemplates('enterprise') .then(templates => { /* templates -> { limit: 100, entries: [ { templateKey: 'documentFlow', scope: 'enterprise_12345', displayName: 'Document Flow', hidden: false, fields: [ { type: 'string', key: 'currentDocumentStage', displayName: 'Current Document Stage', hidden: false } { type: 'string', key: 'needsApprovalFrom', displayName: 'Needs Approval From', hidden: false }, { type: 'string', key: 'nextDocumentStage', displayName: 'Next Document Stage', hidden: false } { type: 'float', key: 'maximumDaysAllowedInCurrentStage', displayName: 'Maximum Days Allowed In Current Stage', hidden: false } { templateKey: 'marketingCollateral', scope: 'enterprise_12345', displayName: 'Marketing Collateral', hidden: false, fields: [ { type: 'string', key: 'audience1', displayName: 'Audience', hidden: false }, { type: 'string', key: 'previousState', displayName: 'Previous State', hidden: false } ] }, { templateKey: 'productInfo', scope: 'enterprise_12345', displayName: 'Product Info', hidden: false, fields: [ { type: 'float', key: 'skuNumber', displayName: 'SKU Number', hidden: false }, { type: 'enum', key: 'department', displayName: 'Department', hidden: false, options: [ { key: 'Beauty' }, { key: 'Shoes' }, { key: 'Accessories' }, { key: 'Clothing' }, { key: 'Handbags' }, { key: 'Bedding' }, { key: 'Watches' } ] }, { type: 'date', key: 'displayDate', displayName: 'Display Date', hidden: false } ] } ], next_marker: null, prev_marker: null } */ }); ``` Similarly, to get all metadata templates that are available to all enterprises use the `global` scope. ``` client.metadata.getTemplates('global') .then(templates => { // ... }); ``` ## Delete Metadata Template To delete a metadata template call the [`metadata.deleteTemplate(scope, template, callback)`](http://opensoure.box.com/box-node-sdk/Metadata.html#deleteTemplate) method with the template scope and template name. ``` client.metadata.deleteTemplate('enterprise', 'testtemplate', callback); ``` ## Set Metadata on a File To set metadata on a file, call [`files.setMetadata(fileID, scope, template, metadata, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Files.html#setMetadata) with the scope and template key of the metadata template, as well as an `Object` containing the metadata keys and values to set. **Note:** This method will unconditionally apply the provided metadata, overwriting existing metadata for the keys provided. To specifically create or update metadata, see the `addMetadata()` and `updateMetadata()` methods below. ``` var metadataValues = { audience: "internal", documentType: "Q1 plans", competitiveDocument: "no", status: "active", author: "Jones", currentState: "proposal" }; client.files.setMetadata('11111', client.metadata.scopes.ENTERPRISE, "marketingCollateral", metadataValues) .then(metadata => { /* metadata -> { audience: 'internal', documentType: 'Q1 plans', competitiveDocument: 'no', status: 'active', author: 'Jones', currentState: 'proposal', '$type': 'marketingCollateral-d086c908-2498-4d3e-8a1f-01e82bfc2abe', '$parent': 'file_11111', '$id': '2094c584-68e1-475c-a581-534a4609594e', '$version': 0, '$typeVersion': 0, '$template': 'marketingCollateral', '$scope': 'enterprise_12345' } */ }); ``` To add new metadata to a file, call [`files.addMetadata(fileID, scope, template, metadata, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Files.html#addMetadata) with a metadata template and an object of key/value pairs to add as metadata. **Note:**: This method will only succeed if the provided metadata template is not current applied to the file, otherwise it will fail with a Conflict error. ``` var metadataValues = { audience: "internal", documentType: "Q1 plans", competitiveDocument: "no", status: "active", author: "Jones", currentState: "proposal" }; client.files.addMetadata('11111', client.metadata.scopes.ENTERPRISE, "marketingCollateral", metadataValues) .then(metadata => { /* metadata -> { audience: 'internal', documentType: 'Q1 plans', competitiveDocument: 'no', status: 'active', author: 'Jones', currentState: 'proposal', '$type': 'marketingCollateral-d086c908-2498-4d3e-8a1f-01e82bfc2abe', '$parent': 'file_11111', '$id': '2094c584-68e1-475c-a581-534a4609594e', '$version': 0, '$typeVersion': 0, '$template': 'marketingCollateral', '$scope': 'enterprise_12345' } */ }); ``` Update a file's existing metadata by calling [`files.updateMetadata(fileID, scope, template, patch, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Files.html#updateMetadata) with an array of [JSON Patch](http://jsonpatch.com/) formatted operations. **Note:** This method will only succeed if the provided metadata template has already been applied to the file; if the file does not have existing metadata, this method will fail with a Not Found error. This is useful in cases where you know the file will already have metadata applied, since it will save an API call compared to `setMetadata()`. ``` var updates = [ { op: 'test', path: '/competitiveDocument', value: 'no' }, { op: 'remove', path: '/competitiveDocument' }, { op: 'test', path: '/status', value: 'active' }, { op: 'replace', path: '/status', value: 'inactive' }, { op: 'test', path: '/author', value: 'Jones' }, { op: 'copy', from: '/author', path: '/editor' }, { op: 'test', path: '/currentState', value: 'proposal' }, { op: 'move', from: '/currentState', path: '/previousState' }, { op: 'add', path: '/currentState', value: 'reviewed' } ]; client.files.updateMetadata('11111', client.metadata.scopes.ENTERPRISE, "marketingCollateral", updates) .then(metadata => { /* metadata -> { audience: 'internal', documentType: 'Q1 plans', status: 'inactive', author: 'Jones', '$type': 'marketingCollateral-d086c908-2498-4d3e-8a1f-01e82bfc2abe', '$parent': 'file_11111', '$id': '2094c584-68e1-475c-a581-534a4609594e', '$version': 1, '$typeVersion': 0, editor: 'Jones', previousState: 'proposal', currentState: 'reviewed', '$template': 'marketingCollateral', '$scope': 'enterprise_12345' } */ }); ``` ## Get Metadata on a File Retrieve a specific metadata template on a file by calling [`files.getMetadata(fileID, scope, template, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Files.html#getMetadata) with the ID of the file and which template to fetch. ``` client.files.getMetadata('11111', client.metadata.scopes.ENTERPRISE, 'marketingCollateral') .then(metadata => { /* metadata -> { audience: 'internal', documentType: 'Q1 plans', competitiveDocument: 'no', status: 'active', author: 'Jones', currentState: 'proposal', '$type': 'marketingCollateral-d086c908-2498-4d3e-8a1f-01e82bfc2abe', '$parent': 'file_11111', '$id': '2094c584-68e1-475c-a581-534a4609594e', '$version': 0, '$typeVersion': 0, '$template': 'marketingCollateral', '$scope': 'enterprise_12345' } */ }); ``` You can retrieve all metadata on a file by calling [`files.getAllMetadata(fileID, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Files.html#getAllMetadata). ``` client.files.getAllMetadata('11111') .then(metadata => { /* metadata -> { entries: [ { currentDocumentStage: 'Init', '$type': 'documentFlow-452b4c9d-c3ad-4ac7-b1ad-9d5192f2fc5f', '$parent': 'file_11111', '$id': '50ba0dba-0f89-4395-b867-3e057c1f6ed9', '$version': 4, '$typeVersion': 2, needsApprovalFrom: 'Smith', '$template': 'documentFlow', '$scope': 'enterprise_12345' }, { '$type': 'productInfo-9d7b6993-b09e-4e52-b197-e42f0ea995b9', '$parent': 'file_11111', '$id': '15d1014a-06c2-47ad-9916-014eab456194', '$version': 2, '$typeVersion': 1, skuNumber: 45334223, description: 'Watch', '$template': 'productInfo', '$scope': 'enterprise_12345' }, { Popularity: '25', '$type': 'properties', '$parent': 'file_11111', '$id': 'b6f36cbc-fc7a-4eda-8889-130f350cc057', '$version': 0, '$typeVersion': 2, '$template': 'properties', '$scope': 'global' } ], limit: 100 } */ }); ``` ## Remove Metadata from a File A metadata template can be removed from a file by calling [`files.deleteMetadata(fileID, scope, template, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Files.html#deleteMetadata). ``` client.files.deleteMetadata('67890', client.metadata.scopes.GLOBAL, client.metadata.templates.PROPERTIES) .then(() => { // removal succeeded — no value returned });; ``` ## Set Metadata on a Folder To set metadata on a folder, call [`folders.setMetadata(folderID, scope, template, metadata, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Files.html#setMetadata) with the scope and template key of the metadata template, as well as an `Object` containing the metadata keys and values to set. **Note:** This method will unconditionally apply the provided metadata, overwriting existing metadata for the keys provided. To specifically create or update metadata, see the `addMetadata()` and `updateMetadata()` methods below. ``` var metadataValues = { audience: "internal", documentType: "Q1 plans", competitiveDocument: "no", status: "active", author: "Jones", currentState: "proposal" }; client.folders.setMetadata('11111', client.metadata.scopes.ENTERPRISE, "marketingCollateral", metadataValues) .then(metadata => { /* metadata -> { audience: 'internal', documentType: 'Q1 plans', competitiveDocument: 'no', status: 'active', author: 'Jones', currentState: 'proposal', '$type': 'marketingCollateral-d086c908-2498-4d3e-8a1f-01e82bfc2abe', '$parent': 'folder_11111', '$id': '2094c584-68e1-475c-a581-534a4609594e', '$version': 0, '$typeVersion': 0, '$template': 'marketingCollateral', '$scope': 'enterprise_12345' } */ }); ``` To add new metadata to a folder, call [`folders.addMetadata(folderID, scope, template, metadata, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Files.html#addMetadata) with a metadata template and an object of key/value pairs to add as metadata. **Note:**: This method will only succeed if the provided metadata template is not current applied to the folder, otherwise it will fail with a Conflict error. ``` var metadataValues = { audience: "internal", documentType: "Q1 plans", competitiveDocument: "no", status: "active", author: "Jones", currentState: "proposal" }; client.folders.addMetadata('11111', client.metadata.scopes.ENTERPRISE, "marketingCollateral", metadataValues) .then(metadata => { /* metadata -> { audience: 'internal', documentType: 'Q1 plans', competitiveDocument: 'no', status: 'active', author: 'Jones', currentState: 'proposal', '$type': 'marketingCollateral-d086c908-2498-4d3e-8a1f-01e82bfc2abe', '$parent': 'folder_11111', '$id': '2094c584-68e1-475c-a581-534a4609594e', '$version': 0, '$typeVersion': 0, '$template': 'marketingCollateral', '$scope': 'enterprise_12345' } */ }); ``` Update a folder's existing metadata by calling [`folders.updateMetadata(fileID, scope, template, patch, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Files.html#updateMetadata) with an array of [JSON Patch](http://jsonpatch.com/) formatted operations. **Note:** This method will only succeed if the provided metadata template has already been applied to the folder; if the folder does not have existing metadata, this method will fail with a Not Found error. This is useful in cases where you know the folder will already have metadata applied, since it will save an API call compared to `setMetadata()`. ``` var updates = [ { op: 'test', path: '/competitiveDocument', value: 'no' }, { op: 'remove', path: '/competitiveDocument' }, { op: 'test', path: '/status', value: 'active' }, { op: 'replace', path: '/status', value: 'inactive' }, { op: 'test', path: '/author', value: 'Jones' }, { op: 'copy', from: '/author', path: '/editor' }, { op: 'test', path: '/currentState', value: 'proposal' }, { op: 'move', from: '/currentState', path: '/previousState' }, { op: 'add', path: '/currentState', value: 'reviewed' } ]; client.folders.updateMetadata('11111', client.metadata.scopes.ENTERPRISE, "marketingCollateral", updates) .then(metadata => { /* metadata -> { audience: 'internal', documentType: 'Q1 plans', status: 'inactive', author: 'Jones', '$type': 'marketingCollateral-d086c908-2498-4d3e-8a1f-01e82bfc2abe', '$parent': 'folder_11111', '$id': '2094c584-68e1-475c-a581-534a4609594e', '$version': 1, '$typeVersion': 0, editor: 'Jones', previousState: 'proposal', currentState: 'reviewed', '$template': 'marketingCollateral', '$scope': 'enterprise_12345' } */ }); ``` ## Get Metadata on a Folder Retrieve a specific metadata template on a folder by calling [`folders.getMetadata(folderID, scope, template, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Folders.html#getMetadata) with the ID of the folder and which template to fetch. ``` client.folders.getMetadata('11111', client.metadata.scopes.ENTERPRISE, 'marketingCollateral') .then(metadata => { /* metadata -> { audience: 'internal', documentType: 'Q1 plans', competitiveDocument: 'no', status: 'active', author: 'Jones', currentState: 'proposal', '$type': 'marketingCollateral-d086c908-2498-4d3e-8a1f-01e82bfc2abe', '$parent': 'folder_11111', '$id': '2094c584-68e1-475c-a581-534a4609594e', '$version': 0, '$typeVersion': 0, '$template': 'marketingCollateral', '$scope': 'enterprise_12345' } */ }); ``` You can retrieve all metadata on a folder by calling [`folders.getAllMetadata(folderID, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Folders.html#getAllMetadata). ``` client.folders.getAllMetadata('11111') .then(metadata => { /* metadata -> { entries: [ { currentDocumentStage: 'Init', '$type': 'documentFlow-452b4c9d-c3ad-4ac7-b1ad-9d5192f2fc5f', '$parent': 'folder_11111', '$id': '50ba0dba-0f89-4395-b867-3e057c1f6ed9', '$version': 4, '$typeVersion': 2, needsApprovalFrom: 'Smith', '$template': 'documentFlow', '$scope': 'enterprise_12345' }, { '$type': 'productInfo-9d7b6993-b09e-4e52-b197-e42f0ea995b9', '$parent': 'folder_11111', '$id': '15d1014a-06c2-47ad-9916-014eab456194', '$version': 2, '$typeVersion': 1, skuNumber: 45334223, description: 'Watch', '$template': 'productInfo', '$scope': 'enterprise_12345' }, { Popularity: '25', '$type': 'properties', '$parent': 'folder_11111', '$id': 'b6f36cbc-fc7a-4eda-8889-130f350cc057', '$version': 0, '$typeVersion': 2, '$template': 'properties', '$scope': 'global' } ], limit: 100 } */ }); ``` ## Remove Metadata from a Folder A folder's metadata can be removed by calling [`folders.deleteMetadata(folderID, scope, template, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Folders.html#deleteMetadata). ``` client.folders.deleteMetadata('67890', client.metadata.scopes.GLOBAL, client.metadata.templates.PROPERTIES) .then(() => { // removal succeeded — no value returned }); ``` ## Create Cascade Policy To set a metadata cascade policy, which applies metadata values on a folder to new items in the folder, call [`metadata.createCascadePolicy(scope, templateKey, folderID, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Metadata.html#createCascadePolicy) with the scope and template key of the metadata template to be cascaded, and the ID of the folder to apply the policy to. ``` var folderID = '22222'; client.metadata.createCascadePolicy('enterprise', 'testTemplate', folderID) .then(cascadePolicy => { /* cascadePolicy -> { id: '84113349-794d-445c-b93c-d8481b223434', type: 'metadata_cascade_policy', owner_enterprise: { type: 'enterprise', id: '11111' }, parent: { type: 'folder', id: '22222' }, scope: 'enterprise_11111', templateKey: 'testTemplate' } */ }); ``` ## Get Cascade Policy To retrieve information about a specific metadata cascade policy, call [`metadata.getCascadePolicy(policyID, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Metadata.html#getCascadePolicy) with the ID of the cascade policy. ``` var policyID = '84113349-794d-445c-b93c-d8481b223434'; client.metadata.getCascadePolicy(policyID) .then(cascadePolicy => { /* cascadePolicy -> { id: '84113349-794d-445c-b93c-d8481b223434', type: 'metadata_cascade_policy', owner_enterprise: { type: 'enterprise', id: '11111' }, parent: { type: 'folder', id: '22222' }, scope: 'enterprise_11111', templateKey: 'testTemplate' } */ }); ``` ## Get All Cascade Policies For a Folder To get a list of all cascade policies for a folder, which show the metadata templates that are being applied to all items in that folder, call [`metadata.getCascadePolicies(folderID, options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Metadata.html#getCascadePolicies) with the ID of the folder. You can set the `owner_enterprise_id` option to retrieve only cascade policies owned by a specific enterprise (defaults to the current enterprise). ``` var folderID = '22222'; client.metadata.getCascadePolicies(folderID) .then(cascadePolicies => { /* cascadePolicies -> { limit: 100, entries: [ { id: '84113349-794d-445c-b93c-d8481b223434', type: 'metadata_cascade_policy', owner_enterprise: { type: 'enterprise', id: '11111' }, parent: { type: 'folder', id: '22222' }, scope: 'enterprise_11111', templateKey: 'testTemplate' } ], next_marker: null, prev_marker: null } */ }); ``` ## Force Apply Cascade Policy To force apply a metadata cascade policy and apply metadata values to all existing items in the affected folder, call [`metadata.forceApplyCascadePolicy(policyID, resolutionMethod, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Metadata.html#forceApplyCascadePolicy) with the ID of the cascade policy to force apply and the conflict resolution method for dealing with items that already have a metadata value that conflicts with the folder. Specifying a resolution value of `'none'` will preserve the existing values on items, and specifying `'overwrite'` will overwrite values on the items in the folder with the metadata value from the folder. ``` var policyID = '84113349-794d-445c-b93c-d8481b223434'; client.metadata.forceApplyCascadePolicy(policyID, client.metadata.cascadeResolution.PRESERVE_EXISTING) .then(() => { // application started — no value returned }); ``` ## Delete Cascade Policy To remove a cascade policy and stop applying metadata from a folder to items in the folder, call [`metadata.deleteCascadePolicy(policyID, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Metadata.html#deleteCascadePolicy) with the ID of the cascade policy to delete. ``` var policyID = '84113349-794d-445c-b93c-d8481b223434'; client.metadata.deleteCascadePolicy(policyID) .then(() => { // deletion succeeded — no value returned }); ``` ## Query To query Box items based on their metadata, call [`metadata.query(from, ancestorFolderId, options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Metadata.html#query) with the metadata template and the folder ID to restrain the query. Additional options like a specific query, a marker, etc. can be passed in through the options object. **Important**: One of two possible response types are returned, based on whether the fields parameter is passed into the options parameter or not. The example directly below shows the response if the fields parameter is not passed in. ``` var from = 'enterprise_12345.someTemplate', ancestorFolderId = '5555', options = { query: 'amount >= :arg', query_params: { arg: 100 }, order_by: [ { field_key: 'amount', direction: 'asc' } ], limit: 100, marker: 'AAAAAmVYB1FWec8GH6yWu2nwmanfMh07IyYInaa7DZDYjgO1H4KoLW29vPlLY173OKsci6h6xGh61gG73gnaxoS+o0BbI1/h6le6cikjlupVhASwJ2Cj0tOD9wlnrUMHHw3/ISf+uuACzrOMhN6d5fYrbidPzS6MdhJOejuYlvsg4tcBYzjauP3+VU51p77HFAIuObnJT0ff' }; client.metadata.query(from, ancestorFolderId, options) .then(items => { /* items -> { "entries": [ { "item": { "type": "file", "id": "1617554169109", "file_version": { "type": "file_version", "id": "1451884469385", "sha1": "69888bb1bff455d1b2f8afea75ed1ff0b4879bf6" }, "sequence_id": "0", "etag": "0", "sha1": "69888bb1bff455d1b2f8afea75ed1ff0b4879bf6", "name": "My Contract.docx", "description": "", "size": 25600, "path_collection": { "total_count": 4, "entries": [ { "type": "folder", "id": "0", "sequence_id": null, "etag": null, "name": "All Files" }, { "type": "folder", "id": "15017998644", "sequence_id": "0", "etag": "0", "name": "Contracts" }, { "type": "folder", "id": "15286891196", "sequence_id": "1", "etag": "1", "name": "North America" }, { "type": "folder", "id": "16125613433", "sequence_id": "0", "etag": "0", "name": "2017" } ] }, "created_at": "2017-04-20T12:55:27-07:00", "modified_at": "2017-04-20T12:55:27-07:00", "trashed_at": null, "purged_at": null, "content_created_at": "2017-01-06T17:59:01-08:00", "content_modified_at": "2017-01-06T17:59:01-08:00", "created_by": { "type": "user", "id": "193973366", "name": "Box Admin", "login": "admin@company.com" }, "modified_by": { "type": "user", "id": "193973366", "name": "Box Admin", "login": "admin@company.com" }, "owned_by": { "type": "user", "id": "193973366", "name": "Box Admin", "login": "admin@company.com" }, "shared_link": null, "parent": { "type": "folder", "id": "16125613433", "sequence_id": "0", "etag": "0", "name": "2017" }, "item_status": "active" }, "metadata": { "enterprise_12345": { "someTemplate": { "$parent": "file_161753469109", "$version": 0, "customerName": "Phoenix Corp", "$type": "someTemplate-3d5fcaca-f496-4bb6-9046-d25c37bc5594", "$typeVersion": 0, "$id": "ba52e2cc-371d-4659-8d53-50f1ac642e35", "amount": 100, "claimDate": "2016-04-10T00:00:00Z", "region": "West", "$typeScope": "enterprise_123456" } } } } ], "next_marker": "" } */ }); ``` This second example shows the response if the fields parameter is passed in. ``` var from = 'enterprise_12345.someTemplate', ancestorFolderId = '5555', options = { query: 'amount >= :arg', query_params: { arg: 100 }, order_by: [ { field_key: 'amount', direction: 'asc' } ], fields: [ "id", "name", "sha1", "metadata.enterprise12345.someTemplate.amount" ] limit: 100, marker: 'AAAAAmVYB1FWec8GH6yWu2nwmanfMh07IyYInaa7DZDYjgO1H4KoLW29vPlLY173OKsci6h6xGh61gG73gnaxoS+o0BbI1/h6le6cikjlupVhASwJ2Cj0tOD9wlnrUMHHw3/ISf+uuACzrOMhN6d5fYrbidPzS6MdhJOejuYlvsg4tcBYzjauP3+VU51p77HFAIuObnJT0ff' }; client.metadata.query(from, ancestorFolderId, options) .then(items => { /* items -> { "entries":[ { "type": "file", "id": "1617554169109", "sha1": "69888bb1bff455d1b2f8afea75ed1ff0b4879bf6", "name": "My Contract.docx", "metadata": { "enterprise_12345": { "someTemplate": { "$parent": "file_161753469109", "$version": 0, "$type": "someTemplate-3d5fcaca-f496-4bb6-9046-d25c37bc5594", "$typeVersion": 0, "$id": "ba52e2cc-371d-4659-8d53-50f1ac642e35", "amount": 100, "$typeScope": "enterprise_123456" } } } } ], "next_marker":"" } */ }); ``` --- ### Metadata **Type:** page | **Section:** Additional Resources Metadata Metadata allows users and applications to define and store custom data associated with their files/folders. Metadata consists of… # Metadata Metadata allows users and applications to define and store custom data associated with their files/folders. Metadata consists of key:value pairs that belong to files/folders. For example, an important contract may have key:value pairs of `"clientNumber":"820183"` and `"clientName":"bioMedicalCorp"`. Metadata that belongs to a file/folder is grouped by templates. Templates allow the metadata service to provide a multitude of services, such as pre-defining sets of key:value pairs or schema enforcement on specific fields. Each file/folder can have multiple distinct template instances associated with it, and templates are also grouped by scopes. Currently, the only scopes support are `enterprise` and `global`. Enterprise scopes are defined on a per enterprises basis, whereas global scopes are Box application-wide. In addition to `enterprise` scoped templates, every file on Box has access to the `global` `properties` template. The Properties template is a bucket of free form key:value string pairs, with no additional schema associated with it. Properties are ideal for scenarios where applications want to write metadata to file objects in a flexible way, without pre-defined template structure. - [Create Metadata Template](#create-metadata-template) [Get Metadata Template](#get-metadata-template) - [Get by scope and template key](#get-by-scope-and-template-key) - [Get by template ID](#get-by-template-id) [Update Metadata Template](#update-metadata-template) [Get Enterprise Metadata Templates](#get-enterprise-metadata-templates) [Delete Metadata Template](#delete-metadata-template) ## Create Metadata Template To create a new metadata template, call [`client.create_metadata_template(display_name, fields, template_key=None, hidden=False, scope='enterprise', copy_instance_on_item_copy=False)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.client.html#boxsdk.client.client.Client.create_metadata_template) with the human-readable name of the template and the [`MetadataField`s](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.metadata_template.MetadataField) the template should have. You can optionally specify a key for the template, otherwise one will be derived from the display name. At the current time, only `enterprise` scope templates are supported. This method returns a [`MetadataTemplate`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.metadata_template.MetadataTemplate) object representing the created template. ``` from boxsdk.object.metadata_template import MetadataField, MetadataFieldType fields = [ MetadataField(MetadataFieldType.STRING, 'Name'), MetadataField(MetadataFieldType.DATE, 'Birthday', 'bday'), MetadataField(MetadataFieldType.ENUM, 'State', options=['CA', 'TX', 'NY']) ] template = client.create_metadata_template('Employee Record', fields, hidden=True) print(f'Metadata template ID {template.scope}/{template.templateKey} created!') ``` ## Get Metadata Template ### Get by scope and template key To retrieve a specific template by scope and template key, first use [`client.metadata_template(scope, template_key)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.client.html#boxsdk.client.client.Client.metadata_template) to construct the appropriate [`MetadataTemplate`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.metadata_template.MetadataTemplate) object, and then call [`template.get()`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.base_object.BaseObject.get) to retrieve data about the template. This method returns a new [`MetadataTemplate`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.metadata_template.MetadataTemplate) object with fields populated by data from the API, leaving the original object unmodified. ``` template = client.metadata_template('enterprise', 'employeeRecord').get() print(f'The {template.displayName} template has {len(template.fields)} fields') ``` ### Get by template ID To retrieve a template by ID, call [`client.get_metadata_template_by_id(template_id)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.client.html#boxsdk.client.client.Client.get_metadata_template_by_id) with the ID of the metadata template. This method returns a [`MetadataTemplate`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.metadata_template.MetadataTemplate) object with fields populated by data from the API. ``` template = client.metadata_template_by_id(template_id='abcdef-fba434-ace44').get() print(f'The {template.displayName} template has {len(template.fields)} fields') ``` ## Update Metadata Template To make changes to a metadata template, first call [`template.start_update()`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.metadata_template.MetadataTemplate.start_update) to create a [`MetadataTemplateUpdate`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.metadata_template.MetadataTemplateUpdate) to track updates. Call the methods on this object to add the necessary update operations, and then call [`template.update_info(*, updates, **kwargs)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.metadata_template.MetadataTemplate.update_info) with the updates object to apply the changes to the metadata template. This method returns an updated [`MetadataTemplate`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.metadata_template.MetadataTemplate) object with the changes applied, leaving the original object unmodified. ``` template = client.metadata_template('enterprise', 'employeeRecord') updates = template.start_update() updates.add_enum_option('state', 'WI') updates.edit_template({'hidden': False}) updates.edit_template({'copyInstanceOnItemCopy': False}) updated_template = template.update_info(updates=updates) ``` ## Get Enterprise Metadata Templates Get all metadata templates for the current enterprise by calling [`client.get_metadata_templates(scope='enterprise', limit=None, marker=None, fields=None)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.client.html#boxsdk.client.client.Client.get_metadata_templates). By default, this retrieves all templates scoped to the current enterprise, but you can pass the `scope` parameter to retrieve templates for a different scope. This method returns a [`BoxObjectCollection`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.pagination.html#boxsdk.pagination.box_object_collection.BoxObjectCollection) that allows you to iterate over all the [`MetadataTemplate`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.metadata_template.MetadataTemplate) objects in the collection. ``` templates = client.get_metadata_templates() for template in templates: print(f'Metadata template {template.templateKey} is in enterprise scope') ``` To return the metadata templates available to all enterprises pass in the `global` scope. ``` templates = client.get_metadata_templates(scope='global) for template in templates: print(f'Metadata template {template.templateKey} is in global scope') ``` ## Delete Metadata Template To delete a metadata template, call [`template.delete()`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.base_object.BaseObject.delete). This method returns `True` to indicate the deletion was successful. ``` client.metadata_template('enterprise', 'employeeRecord').delete() ``` --- ### Metadata **Type:** page | **Section:** Additional Resources Metadata Metadata allows users and applications to define and store custom data associated with their files/folders. Metadata consists of… # Metadata Metadata allows users and applications to define and store custom data associated with their files/folders. Metadata consists of key:value pairs that belong to files/folders. For example, an important contract may have key:value pairs of `"clientNumber":"820183"` and `"clientName":"bioMedicalCorp"`. Metadata that belongs to a file/folder is grouped by templates. Templates allow the metadata service to provide a multitude of services, such as pre-defining sets of key:value pairs or schema enforcement on specific fields. Each file/folder can have multiple distinct template instances associated with it, and templates are also grouped by scopes. Currently, the only scopes support are `enterprise` and `global`. Enterprise scopes are defined on a per enterprises basis, whereas global scopes are Box application-wide. In addition to `enterprise` scoped templates, every file on Box has access to the `global` `properties` template. The Properties template is a bucket of free form key:value string pairs, with no additional schema associated with it. Properties are ideal for scenarios where applications want to write metadata to file objects in a flexible way, without pre-defined template structure. - [Create Metadata Template](#create-metadata-template) - [Update Metadata Template](#update-metadata-template) [Get Metadata Template](#get-metadata-template) - [Get by template scope and key](#get-by-template-scope-and-key) - [Get by ID](#get-by-id) [Get Enterprise Metadata Templates](#get-enterprise-metadata-templates) [Set Metadata on a File](#set-metadata-on-a-file) [Get Metadata on a File](#get-metadata-on-a-file) [Remove Metadata from a File](#remove-metadata-from-a-file) [Set Metadata on a Folder](#set-metadata-on-a-folder) [Get Metadata on a Folder](#get-metadata-on-a-folder) [Remove Metadata from a Folder](#remove-metadata-from-a-folder) [Execute Metadata Query](#execute-metadata-query) ## Create Metadata Template To create a new metadata template, call `MetadataManager.CreateMetadataTemplate(BoxMetadataTemplate template)`. ``` var templateParams = new BoxMetadataTemplate() { TemplateKey = "marketingCollateral", DisplayName = "Marketing Collateral", Scope = "enterprise", Fields = new List<BoxMetadataTemplateField>() { new BoxMetadataTemplateField() { Type = "enum", Key = "audience", DisplayName = "Audience", Options = new List<BoxMetadataTemplateFieldOption>() { new BoxMetadataTemplateFieldOption() { Key = "internal" }, new BoxMetadataTemplateFieldOption() { Key = "external" } } }, new BoxMetadataTemplateField() { Type = "string", Key = "author", DisplayName = "Author" } } }; BoxMetadataTemplate template = await client.MetadataManager.CreateMetadataTemplate(templateParams); ``` ## Update Metadata Template To update a metadata template, call the `MetadataManager.UpdateMetadataTemplate(IEnumerable<BoxMetadataTemplateUpdate> metadataTemplateUpdate, string scope, string template)` method with the operations to perform on the template. See the [API Documentation](https://developer.box.com/en/reference/put-metadata-templates-id-id-schema/) for more information on the operations available. ``` var updates = new List<BoxMetadataTemplateUpdate>() { new BoxMetadataTemplateUpdate() { Op = MetadataTemplateUpdateOp.addEnumOption, FieldKey = "fy", Data = new { key = "FY20" } }, new BoxMetadataTemplateUpdate() { Op = MetadataTemplateUpdateOp.editTemplate, Data = new { hidden = false } } }; BoxMetadataTemplate updatedTemplate = await client.MetadataManager .UpdateMetadataTemplate(updates, "enterprise", "marketingCollateral"); ``` ## Get Metadata Template ### Get by template scope and key To retrieve a specific metadata template by its scope and template key, call the `MetadataManager.GetMetadataTemplate(string scope, string template)` method with the scope and template key. ``` BoxMetadataTemplate template = await client.MetadataManager .GetMetadataTemplate("enterprise", "marketingCollateral"); ``` ### Get by ID To get a specific metadata template by its ID, call the `MetadataManager.GetMetadataTemplateById(string templateId)` method with the ID of the template. ``` BoxMetadataTemplate template = await client.MetadataManager .GetMetadataTemplateById("17f2d715-6acb-45f2-b96a-28b15efc9faa"); ``` ## Get Enterprise Metadata Templates Get all metadata templates for the current enterprise and scope by calling `MetadataManager.GetEnterpriseMetadataAsync(string scope = "enterprise")`. ``` BoxEnterpriseMetadataTemplateCollection<BoxMetadataTemplate> templates = await client.MetadataManager .GetEnterpriseMetadataAsync(); ``` ## Get Global Metadata Templates Get all metadata templates available to all enterprises by calling `MetadataManager.GetEnterpriseMetadataAsync(string scope = "global")`. ``` BoxEnterpriseMetadataTemplateCollection<BoxMetadataTemplate> templates = await client.MetadataManager .GetEnterpriseMetadataAsync("global"); ``` ## Set Metadata on a File To set metadata on a file, call `MetadataManager.SetFileMetadataAsync(string fileId, Dictionary<string, object> metadata, string scope, string template)` with the scope and template key of the metadata template, as well as a `Dictionary` containing the metadata keys and values to set. **Note:** This method will unconditionally apply the provided metadata, overwriting existing metadata for the keys provided. To specifically create or update metadata, see the `CreateFileMetadataAsync()` and `UpdateFileMetadataAsync()` methods below. ``` var metadataValues = new Dictionary<string, object>() { { "audience", "internal" }, { "documentType", "Q1 plans" }, { "competitiveDocument", "no" }, { "status", "active" }, { "author": "M. Jones" }, { "currentState": "proposal" } }; Dictionary<string, object> metadata = await client.MetadataManager .SetFileMetadataAsync(fileId: "11111", metadataValues, "enterprise", "marketingCollateral"); ``` To add new metadata to a file, call `MetadataManager.CreateFileMetadataAsync(string fileId, Dictionary<string, object> metadata, string scope, string template)` with a metadata template and a `Dictionary` of key/value pairs to add as metadata. **Note:**: This method will only succeed if the provided metadata template is not current applied to the file, otherwise it will fail with a Conflict error. ``` var metadataValues = new Dictionary<string, object>() { { "audience", "internal" }, { "documentType", "Q1 plans" }, { "competitiveDocument", "no" }, { "status", "active" }, { "author": "M. Jones" }, { "currentState": "proposal" } }; Dictionary<string, object> metadata = await client.MetadataManager .CreateFileMetadataAsync(fileId: "11111", metadataValues, "enterprise", "marketingCollateral"); ``` Update a file's existing metadata by calling `MetadataManager.UpdateFileMetadataAsync(string fileId, List<BoxMetadataUpdate> updates, string scope, string template)` with a list of update operations to apply. **Note:** This method will only succeed if the provided metadata template has already been applied to the file; if the file does not have existing metadata, this method will fail with a Not Found error. This is useful in cases where you know the file will already have metadata applied, since it will save an API call compared to `SetFileMetadataAsync()`. ``` var updates = new List<BoxMetadataUpdate>() { new BoxMetadataUpdate() { Op = MetadataUpdateOp.test, Path = "/competitiveDocument", Value = "no" }, new BoxMetadataUpdate() { Op = MetadataUpdateOp.remove, Path = "/competitiveDocument" }, new BoxMetadataUpdate() { Op = MetadataUpdateOp.test, Path = "/status", Value = "active" }, new BoxMetadataUpdate() { Op = MetadataUpdateOp.replace, Path = "/competitiveDocument", Value = "inactive" }, new BoxMetadataUpdate() { Op = MetadataUpdateOp.test, Path = "/author", Value = "Jones" }, new BoxMetadataUpdate() { Op = MetadataUpdateOp.copy, From="/author", Path = "/editor" }, new BoxMetadataUpdate() { Op = MetadataUpdateOp.test, Path = "/currentState", Value = "proposal" }, new BoxMetadataUpdate() { Op = MetadataUpdateOp.move, From = "/currentState", Path = "/previousState" }, new BoxMetadataUpdate() { Op = MetadataUpdateOp.add, Path = "/currentState", Value = "reviewed" } }; Dictionary<string, object> updatedMetadata = await client.MetadataManager .UpdateFileMetadataAsync("11111", updates, "enterprise", "marketingCollateral"); ``` ## Get Metadata on a File Retrieve a specific metadata template on a file by calling `MetadataManager.GetFileMetadataAsync(string fileId, string scope, string template)` with the ID of the file and which template to fetch. ``` Dictionary<string, object> metadata = await client.MetadataManager. .GetFileMetadataAsync(fileId: "11111", "enterprise", "marketingCollateral"); ``` You can also get all metadata on a file by calling `MetadataManager.GetAllFileMetadataTemplatesAsync(string fileId)`. ``` BoxMetadataTemplateCollection<Dictionary<string, object>> metadataInstances = await client.MetadataManager .GetAllFileMetadataTemplatesAsync(fileId: "11111"); ``` ## Remove Metadata from a File A metadata template can be removed from a file by calling `MetadataManager.DeleteFileMetadataAsync(string fileId, string scope, string template)` with the ID of the file and the metadata template to remove. ``` await client.MetadataManager.DeleteFileMetadataAsync("11111", "enterprise", "marketingCollateral"); ``` ## Set Metadata on a Folder To set metadata on a folder, call `MetadataManager.SetFolderMetadataAsync(string folderId, Dictionary<string, object> metadata, string scope, string template)` with the scope and template key of the metadata template, as well as a `Dictionary` containing the metadata keys and values to set. **Note:** This method will unconditionally apply the provided metadata, overwriting existing metadata for the keys provided. To specifically create or update metadata, see the `CreateFileMetadataAsync()` and `UpdateFileMetadataAsync()` methods below. ``` var metadataValues = new Dictionary<string, object>() { { "audience", "internal" }, { "documentType", "Q1 plans" }, { "competitiveDocument", "no" }, { "status", "active" }, { "author": "M. Jones" }, { "currentState": "proposal" } }; Dictionary<string, object> metadata = await client.MetadataManager .SetFolderMetadataAsync(folderId: "11111", metadataValues, "enterprise", "marketingCollateral"); ``` To add new metadata to a folder, call `MetadataManager.CreateFolderMetadataAsync(string folderId, Dictionary<string, object> metadata, string scope, string template)` with a metadata template and a `Dictionary` of key/value pairs to add as metadata. **Note:**: This method will only succeed if the provided metadata template is not current applied to the folder, otherwise it will fail with a Conflict error. ``` var metadataValues = new Dictionary<string, object>() { { "audience", "internal" }, { "documentType", "Q1 plans" }, { "competitiveDocument", "no" }, { "status", "active" }, { "author": "M. Jones" }, { "currentState": "proposal" } }; Dictionary<string, object> metadata = await client.MetadataManager .CreateFolderMetadataAsync(folderId: "11111", metadataValues, "enterprise", "marketingCollateral"); ``` Update a folder's existing metadata by calling `MetadataManager.UpdateFolderMetadataAsync(string folderId, List<BoxMetadataUpdate> updates, string scope, string template)` with a list of update operations to apply. **Note:** This method will only succeed if the provided metadata template has already been applied to the folder; if the folder does not have existing metadata, this method will fail with a Not Found error. This is useful in cases where you know the folder will already have metadata applied, since it will save an API call compared to `SetFolderMetadataAsync()`. ``` var updates = new List<BoxMetadataUpdate>() { new BoxMetadataUpdate() { Op = MetadataUpdateOp.test, Path = "/competitiveDocument", Value = "no" }, new BoxMetadataUpdate() { Op = MetadataUpdateOp.remove, Path = "/competitiveDocument" }, new BoxMetadataUpdate() { Op = MetadataUpdateOp.test, Path = "/status", Value = "active" }, new BoxMetadataUpdate() { Op = MetadataUpdateOp.replace, Path = "/competitiveDocument", Value = "inactive" }, new BoxMetadataUpdate() { Op = MetadataUpdateOp.test, Path = "/author", Value = "Jones" }, new BoxMetadataUpdate() { Op = MetadataUpdateOp.copy, From="/author", Path = "/editor" }, new BoxMetadataUpdate() { Op = MetadataUpdateOp.test, Path = "/currentState", Value = "proposal" }, new BoxMetadataUpdate() { Op = MetadataUpdateOp.move, From = "/currentState", Path = "/previousState" }, new BoxMetadataUpdate() { Op = MetadataUpdateOp.add, Path = "/currentState", Value = "reviewed" } }; Dictionary<string, object> updatedMetadata = await client.MetadataManager .UpdateFolderMetadataAsync("11111", updates, "enterprise", "marketingCollateral"); ``` ## Get Metadata on a Folder Retrieve a specific metadata template on a folder by calling `MetadataManager.GetFolderMetadataAsync(string folderId, string scope, string template)` with the ID of the folder and which template to fetch. ``` Dictionary<string, object> metadata = await client.MetadataManager. .GetFolderMetadataAsync(folderId: "11111", "enterprise", "marketingCollateral"); ``` You can also get all metadata on a folder by calling `MetadataManager.GetAllFolderMetadataTemplatesAsync(string folderId)`. ``` BoxMetadataTemplateCollection<Dictionary<string, object>> metadataInstances = await client.MetadataManager .GetAllFolderMetadataTemplatesAsync(folderId: "11111"); ``` ## Remove Metadata from a Folder A metadata template can be removed from a folder by calling `MetadataManager.DeleteFolderMetadataAsync(string folderId, string scope, string template)` with the ID of the folder and the metadata template to remove. ``` await client.MetadataManager.DeleteFolderMetadataAsync("11111", "enterprise", "marketingCollateral"); ``` ## Execute Metadata Query There are two types of methods for executing a metadata query, methods without the fields parameter and with it. The method with the fields parameters returns a `BoxItem` object. The method without the fields parameters returns data that is a `BoxMetadataQueryItem` and is **deprecated**. The API will eventually not support this method and the other method should be used instead. Examples of these two types are shown below. The `MetadataManager.ExecuteMetadataQueryAsync(string from, string ancestorFolderId, IEnumerable<string> fields, string query, Dictionary<string, object> queryParameters, string indexName, List<BoxMetadataQueryOrderBy> orderBy, int limit, string marker, bool autoPaginate)` method queries files and folders based on their metadata and allows for fields to be passed in. A returned `BoxItem` must be cast to a `BoxFile` or `BoxFolder` to get its metadata. ``` var queryParams = new Dictionary<string, object>(); queryParams.Add("arg", "Bob Dylan"); List<string> fields = new List<string>(); fields.Add("id"); fields.Add("name"); fields.Add("sha1"); fields.Add("metadata.enterprise_240748.catalogImages.photographer"); BoxCollectionMarkerBased<BoxItem> items = await _metadataManager.ExecuteMetadataQueryAsync(from: "enterprise_67890.catalogImages", query: "photographer = :arg", fields: fields, queryParameters: queryParams, ancestorFolderId: "0", autoPaginate: true); BoxFile file = (BoxFile) items.Entries[0]; BoxFolder folder = (BoxFolder) items.Entries[1]; string metadataFile = file.Metadata["enterprise_240748"]["catalogImages"]["photographer"].Value; string metadataFolder = folder.Metadata["enterprise_240748"]["catalogImages"]["photographer"].Value; ``` **Deprecated** The `MetadataManager.ExecuteMetadataQueryAsync(string from, string ancestorFolderId, string query = null, Dictionary<string, object> queryParameters, string indexName, List<BoxMetadataQueryOrderBy> orderBy, int limit, string marker, bool autoPaginate)` method queries files and folders based on their metadata. ``` var queryParams = new Dictionary<string, object>(); queryParams.Add("arg", 100); List<BoxMetadataQueryOrderBy> orderByList = new List<BoxMetadataQueryOrderBy>(); var orderBy = new BoxMetadataQueryOrderBy() { FieldKey = "amount", Direction = BoxSortDirection.ASC }; orderByList.Add(orderBy); BoxCollectionMarkerBased<BoxMetadataQueryItem> items = await _metadataManager.ExecuteMetadataQueryAsync(from: "enterprise_123456.someTemplate", query: "amount >= :arg", queryParameters: queryParams, ancestorFolderId: "5555", indexName: "amountAsc", orderBy: orderByList, autoPaginate: true); ``` --- ### Metadata **Type:** page | **Section:** Additional Resources Metadata Metadata allows users and applications to define and store custom data associated with their files/folders. Metadata consists of… # Metadata Metadata allows users and applications to define and store custom data associated with their files/folders. Metadata consists of key-value pairs that belong to files/folders. For example, an important contract file stored on Box may have key-value pairs of `"clientNumber":"820183"` and `"clientName":"BioMedical Corp"`. Metadata that belongs to a file/folder is grouped by templates. Templates allow the metadata service to provide a multitude of features, such as pre-defining sets of key-value pairs or schema enforcement on specific fields. Each file/folder can have multiple distinct template instances associated with it, and templates are also grouped by scopes. Currently, the only scopes support are `enterprise` and `global`. Enterprise scopes are defined on a per-enterprise basis, whereas global scopes are Box application-wide. In addition to `enterprise` scoped templates, every file on Box has access to the `global` `properties` template. The `properties` template contains free-form key-value string pairs, with no additional schema associated with it. This is recommended for scenarios where applications want to write metadata to file objects in a flexible way, without pre-defined template structure. - [Get Metadata Template](#get-metadata-template) - [Create Metadata Template](#create-metadata-template) - [Update Metadata Template](#update-metadata-template) - [Delete Metadata Template](#delete-metadata-template) - [List Metadata Templates](#list-metadata-templates) - [Get All Metadata on File](#get-all-metadata-on-file) - [Get Metadata Instance on File](#get-metadata-instance-on-file) - [Add Metadata Instance to File](#add-metadata-instance-to-file) - [Update Metadata Instance on File](#update-metadata-instance-on-file) - [Remove Metadata Instance from File](#remove-metadata-instance-from-file) - [Get All Metadata on Folder](#get-all-metadata-on-folder) - [Get Metadata Instance on Folder](#get-metadata-instance-on-folder) - [Add Metadata Instance to Folder](#add-metadata-instance-to-folder) - [Update Metadata Instance on Folder](#update-metadata-instance-on-folder) - [Remove Metadata Instance from Folder](#remove-metadata-instance-from-folder) ## Get Metadata Template To retrieve information about a metadata template, call [`client.metadata.getTemplateByKey(scope:templateKey:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/MetadataModule.html#/s:6BoxSDK14MetadataModuleC16getTemplateByKey5scope08templateH010completionySS_SSys6ResultOyAA0cF0CAA0A8SDKErrorCGctF) with the scope and key of the template. ``` client.metadata.getTemplateByKey( scope: "enterprise", templateKey: "personnelRecord" ) { (result: Result<MetadataTemplate, BoxSDKError>) in guard case let .success(template) = result { print("Error retrieving metadata template") return } print("Metadata template has \(template.fields?.count) fields") } ``` Alternatively, if you know the ID of the metadata template, you can call [`client.metadata.getTemplateById(id:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/MetadataModule.html#/s:6BoxSDK14MetadataModuleC15getTemplateById2id10completionySS_ys6ResultOyAA0cF0CAA0A8SDKErrorCGctF) with the ID of the template. ``` client.metadata.getTemplateById( id: "26004e29-7b94-44a1-8a63-f9aa384c7421" ) { (result: Result<MetadataTemplate, BoxSDKError>) in guard case let .success(template) = result { print("Error retrieving metadata template") return } print("Metadata template has \(template.fields?.count) fields") } ``` ## Create Metadata Template To create a new metadata template, call [`client.metadata.createTemplate(scope:templateKey:displayName:hidden:copyInstanceOnItemCopy:fields:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/MetadataModule.html#/s:6BoxSDK14MetadataModuleC14createTemplate5scope11templateKey11displayName6hidden6fields10completionySS_S2SSbSayAA0C5FieldVGys6ResultOyAA0cF0CAA0A8SDKErrorCGctF) with the scope and name of the template, as well as the fields the template should contain. ``` var templateFields: [MetadataField] = [] templateFields.append(MetadataField( type: "string", key: "name", displayName: "Full Name" )) templateFields.append(MetadataField( type: "date", key: "birthday", displayName: "Birthday" )) templateFields.append(MetadataField( type: "enum", key: "department", displayName: "Department", options: [ ["key": "HR"], ["key": "Sales"], ["key": "Marketing"], ] )) client.metadata.createTemplate( scope: "enterprise", templateKey: "personnelRecord", displayName: "Personnel Record", hidden: false, fields: templateFields ) { (result: Result<MetadataTemplate, BoxSDKError>) in guard case let .success(template) = result { print("Error creating metadata template") return } print("Created metadata template with ID \(template.id)") } ``` ## Update Metadata Template To update a metadata template, including to modify its fields, call [`client.metadata.updateTemplate(scope:templateKey:operation:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/MetadataModule.html#/s:6BoxSDK14MetadataModuleC14updateTemplate5scope11templateKey9operation10completionySS_SSAA0cF9OperationOys6ResultOyAA0cF0CAA0A8SDKErrorCGctF) with the scope and key of the template to update, as well as the update operation to perform. In this example, we are updating the metadata template using the ReorderEnumOptions operation. Other metadata template update operations include: addEnumOption, addField, editTemplate, reorderFields ``` client.metadata.updateTemplate( scope: "enterprise", templateKey: "personnelRecord", operation: .reorderEnumOptions(fieldKey: "department", enumOptionKeys: ["Marketing", "Sales", "HR"]) ) { (result: Result<MetadataTemplate, BoxSDKError>) in guard case let .success(template) = result { print("Error updating metadata template") return } print("Updated metadata template with ID \(template.id)") } ``` ## Delete Metadata Template To delete a metadata template, call [`client.metadata.deleteTemplate(scope:templateKey:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/MetadataModule.html#/s:6BoxSDK14MetadataModuleC14deleteTemplate5scope11templateKey10completionySS_SSys6ResultOyytAA0A8SDKErrorCGctF) with the scope and key of the template to delete. ``` client.metadata.deleteTemplate( scope: "enterprise", templateKey: "personnelRecord" ) { (result: Result<Void, BoxSDKError>) in guard case .success = result { print("Error deleting metadata template") return } print("Metadata template deleted") } ``` ## List Metadata Templates To retrieve the collection of available metadata templates in a particular scope, call [`client.metadata.listEnterpriseTemplates(scope:marker:limit:)`](https://opensource.box.com/box-ios-sdk/Classes/MetadataModule.html#/s:6BoxSDK14MetadataModuleC23listEnterpriseTemplates5scope6marker5limit10completionySS_SSSgSiSgys6ResultOyAA14PagingIteratorCyAA0C8TemplateCGAA0A8SDKErrorCGctF) with the scope. This method will return an iterator, which is used to retrieve metadata templates. ``` let iterator = client.metadata.listEnterpriseTemplates(scope: "enterprise") iterator.next { results in switch results { case let .success(page): for template in page.entries { print("Template name: \(template.displayName)") } case let .failure(error): print(error) } } ``` Similarly, to get all templates available in the `global` scope. ``` let iterator = client.metadata.listEnterpriseTemplates(scope: "global") iterator.next { results in switch results { case let .success(page): for template in page.entries { print("Template name: \(template.displayName)") } case let .failure(error): print(error) } } ``` ## Get All Metadata on File To retrieve all metadata attached to a file, call [`client.metadata.list(forFileId:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/MetadataModule.html#/s:6BoxSDK14MetadataModuleC4list9forFileId10completionySS_ys6ResultOySayAA0C6ObjectCGAA0A8SDKErrorCGctF) with the ID of the file. ``` client.metadata.list(forFileId: "11111") { (result: Result<[MetadataObject], BoxSDKError>) in guard case let .success(metadata) = result { print("Error retrieving metadata") return } print("Retrieved \(metadata.count) metadata instances:") for instance in metadata { print("- \(instance.template)") } } ``` ## Get Metadata Instance on File To retrieve a specific metadata instance attached to a file, call [`client.metadata.get(forFileWithId:scope:templateKey:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/MetadataModule.html#/s:6BoxSDK14MetadataModuleC3get13forFileWithId5scope11templateKey10completionySS_S2Sys6ResultOyAA0C6ObjectCAA0A8SDKErrorCGctF) with the file ID, as well as the scope and key of the metadata template of the instance. ``` client.metadata.get( forFileWithId: "11111", scope: "enterprise", templateKey: "personnelRecord" ) { (result: Result<MetadataObject, BoxSDKError>) in guard case let .success(metadata) = result { print("Error retrieving metadata") return } print("Found personnel record for \(metadata.keys["name"])") } ``` ## Add Metadata Instance to File To attach a new metadata instance to a file, call [`client.metadata.create(forFileWithId:scope:templateKey:keys:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/MetadataModule.html#/s:6BoxSDK14MetadataModuleC6create13forFileWithId5scope11templateKey4keys10completionySS_S2SSDySSypGys6ResultOyAA0C6ObjectCAA0A8SDKErrorCGctF) with the ID of the file, as well as the scope and key of the metadata template to use and the metadata keys and values to attach. ``` let metadata = [ "name": "John Doe", "birthday": "2000-01-01T00:00:00Z", "department": "Sales" ] client.metadata.create( forFileWithId: "11111", scope: "enterprise", templateKey: "personnelRecord", keys: metadata ) { (result: Result<MetadataObject, BoxSDKError>) in guard case let .success(metadata) = result { print("Error adding metadata") return } print("Successfully attached metadata") } ``` ## Update Metadata Instance on File To update the values in a metadata instance attached to a file, call [`client.metadata.updateforFileWithId:scope:templateKey:operations:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/MetadataModule.html#/s:6BoxSDK14MetadataModuleC6update13forFileWithId5scope11templateKey10operations10completionySS_S2SSayAA0gC9OperationOGys6ResultOyAA0C6ObjectCAA0A8SDKErrorCGctF) with the ID of the file, the scope and key of the metadata template associated with the instance, and the operations to perform on the metadata. ``` client.metadata.update( forFileWithId: "11111", scope: "enterprise", templateKey: "personnelRecord", operations: [ .test(path: "/department", value: "Sales"), .replace(path: "/department", value: "Marketing") ] ) { (result: Result<MetadataObject, BoxSDKError>) in guard case let .success(metadata) = result { print("Error updating metadata") return } print("Employee department updated to \(metadata.keys["department"])") } ``` ## Remove Metadata Instance from File To remove a specific metadata instance from a file, call [`client.metadata.delete(forFileWithId:scope:templateKey:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/MetadataModule.html#/s:6BoxSDK14MetadataModuleC6delete13forFileWithId5scope11templateKey10completionySS_S2Sys6ResultOyytAA0A8SDKErrorCGctF) with the ID of the file, as well as the scope and key of the metadata template associated with the instance. ``` client.metadata.delete( forFileWithId: "11111", scope: "enterprise", templateKey: "personnelRecord" ) { (result: Result<Void, BoxSDKError>) in guard case .success = result { print("Error deleting metadata instance") return } print("Metadata instance deleted") } ``` ## Get All Metadata on Folder To retrieve all metadata attached to a folder, call [`client.metadata.list(forFolderId:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/MetadataModule.html#/s:6BoxSDK14MetadataModuleC4list11forFolderId10completionySS_ys6ResultOySayAA0C6ObjectCGAA0A8SDKErrorCGctF) with the ID of the folder. ``` client.metadata.list(forFolderId: "22222") { (result: Result<[MetadataObject], BoxSDKError>) in guard case let .success(metadata) = result { print("Error retrieving metadata") return } print("Retrieved \(metadata.count) metadata instances:") for instance in metadata { print("- \(instance.template)") } } ``` ## Get Metadata Instance on Folder To retrieve a specific metadata instance attached to a folder, call [`client.metadata.get(forFolderWithId:scope:templateKey:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/MetadataModule.html#/s:6BoxSDK14MetadataModuleC3get15forFolderWithId5scope11templateKey10completionySS_S2Sys6ResultOyAA0C6ObjectCAA0A8SDKErrorCGctF) with the folder ID, as well as the scope and key of the metadata template of the instance. ``` client.metadata.get( forFolderWithId: "22222", scope: "enterprise", templateKey: "personnelRecord" ) { (result: Result<MetadataObject, BoxSDKError>) in guard case let .success(metadata) = result { print("Error retrieving metadata") return } print("Found personnel record for \(metadata.keys["name"])") } ``` ## Add Metadata Instance to Folder To attach a new metadata instance to a folder, call [`client.metadata.create(forFolderWithId:scope:templateKey:keys:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/MetadataModule.html#/s:6BoxSDK14MetadataModuleC6create15forFolderWithId5scope11templateKey4keys10completionySS_S2SSDySSypGys6ResultOyAA0C6ObjectCAA0A8SDKErrorCGctF) with the ID of the folder, as well as the scope and key of the metadata template to use and the metadata keys and values to attach. ``` let metadata = [ "name": "John Doe", "birthday": "2000-01-01T00:00:00Z", "department": "Sales" ] client.metadata.create( forFolderWithId: "22222", scope: "enterprise", templateKey: "personnelRecord", keys: metadata ) { (result: Result<MetadataObject, BoxSDKError>) in guard case let .success(metadata) = result { print("Error adding metadata") return } print("Successfully attached metadata") } ``` ## Update Metadata Instance on Folder To update the values in a metadata instance attached to a folder, call [`client.metadata.update(forFolderWithId:scope:templateKey:operations:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/MetadataModule.html#/s:6BoxSDK14MetadataModuleC6update15forFolderWithId5scope11templateKey10operations10completionySS_S2SSayAA0gC9OperationOGys6ResultOyAA0C6ObjectCAA0A8SDKErrorCGctF) with the ID of the folder, the scope and key of the metadata template associated with the instance, and the operations to perform on the metadata. ``` client.metadata.update( forFolderWithId: "22222", scope: "enterprise", templateKey: "personnelRecord", operations: [ .test(path: "/department", value: "Sales"), .replace(path: "/department", value: "Marketing") ] ) { (result: Result<MetadataObject, BoxSDKError>) in guard case let .success(metadata) = result { print("Error updating metadata") return } print("Employee department updated to \(metadata.keys["department"])") } ``` ## Remove Metadata Instance from Folder To remove a specific metadata instance from a folder, call [`client.metadata.delete(forFolderWithId:scope:templateKey:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/MetadataModule.html#/s:6BoxSDK14MetadataModuleC6delete15forFolderWithId5scope11templateKey10completionySS_S2Sys6ResultOyytAA0A8SDKErrorCGctF) with the ID of the folder, as well as the scope and key of the metadata template associated with the instance. ``` client.metadata.delete( forFolderWithId: "22222", scope: "enterprise", templateKey: "personnelRecord" ) { (result: Result<Void, BoxSDKError>) in guard case .success = result { print("Error deleting metadata instance") return } print("Metadata instance deleted") } ``` --- ### Metadata **Type:** page | **Section:** Additional Resources Metadata Metadata allows users and applications to define and store custom data associated with their files/folders. Metadata consists of… # Metadata Metadata allows users and applications to define and store custom data associated with their files/folders. Metadata consists of key-value pairs that belong to files/folders. For example, an important contract file stored on Box may have key-value pairs of `"clientNumber":"820183"` and `"clientName":"BioMedical Corp"`. Metadata that belongs to a file/folder is grouped by templates. Templates allow the metadata service to provide a multitude of features, such as pre-defining sets of key-value pairs or schema enforcement on specific fields. Each file/folder can have multiple distinct template instances associated with it, and templates are also grouped by scopes. Currently, the only scopes support are `enterprise` and `global`. Enterprise scopes are defined on a per-enterprise basis, whereas global scopes are Box application-wide. In addition to `enterprise` scoped templates, every file on Box has access to the `global` `properties` template. The `properties` template contains free-form key-value string pairs, with no additional schema associated with it. This is recommended for scenarios where applications want to write metadata to file objects in a flexible way, without pre-defined template structure. - [Get Metadata Template](#get-metadata-template) - [Create Metadata Template](#create-metadata-template) - [Update Metadata Template](#update-metadata-template) - [Delete Metadata Template](#delete-metadata-template) - [List Metadata Templates](#list-metadata-templates) - [Get All Metadata on File](#get-all-metadata-on-file) - [Get Metadata Instance on File](#get-metadata-instance-on-file) - [Add Metadata Instance to File](#add-metadata-instance-to-file) - [Update Metadata Instance on File](#update-metadata-instance-on-file) - [Remove Metadata Instance from File](#remove-metadata-instance-from-file) - [Get All Metadata on Folder](#get-all-metadata-on-folder) - [Get Metadata Instance on Folder](#get-metadata-instance-on-folder) - [Add Metadata Instance to Folder](#add-metadata-instance-to-folder) - [Update Metadata Instance on Folder](#update-metadata-instance-on-folder) - [Remove Metadata Instance from Folder](#remove-metadata-instance-from-folder) ## Get Metadata Template To retrieve information about a metadata template, call [`client.metadata.getTemplateByKey(scope:templateKey:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/MetadataModule.html#/s:6BoxSDK14MetadataModuleC16getTemplateByKey5scope08templateH010completionySS_SSys6ResultOyAA0cF0CAA0A8SDKErrorCGctF) with the scope and key of the template. ``` client.metadata.getTemplateByKey( scope: "enterprise", templateKey: "personnelRecord" ) { (result: Result<MetadataTemplate, BoxSDKError>) in guard case let .success(template) = result { print("Error retrieving metadata template") return } print("Metadata template has \(template.fields?.count) fields") } ``` Alternatively, if you know the ID of the metadata template, you can call [`client.metadata.getTemplateById(id:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/MetadataModule.html#/s:6BoxSDK14MetadataModuleC15getTemplateById2id10completionySS_ys6ResultOyAA0cF0CAA0A8SDKErrorCGctF) with the ID of the template. ``` client.metadata.getTemplateById( id: "26004e29-7b94-44a1-8a63-f9aa384c7421" ) { (result: Result<MetadataTemplate, BoxSDKError>) in guard case let .success(template) = result { print("Error retrieving metadata template") return } print("Metadata template has \(template.fields?.count) fields") } ``` ## Create Metadata Template To create a new metadata template, call [`client.metadata.createTemplate(scope:templateKey:displayName:hidden:copyInstanceOnItemCopy:fields:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/MetadataModule.html#/s:6BoxSDK14MetadataModuleC14createTemplate5scope11templateKey11displayName6hidden6fields10completionySS_S2SSbSayAA0C5FieldVGys6ResultOyAA0cF0CAA0A8SDKErrorCGctF) with the scope and name of the template, as well as the fields the template should contain. ``` var templateFields: [MetadataField] = [] templateFields.append(MetadataField( type: "string", key: "name", displayName: "Full Name" )) templateFields.append(MetadataField( type: "date", key: "birthday", displayName: "Birthday" )) templateFields.append(MetadataField( type: "enum", key: "department", displayName: "Department", options: [ ["key": "HR"], ["key": "Sales"], ["key": "Marketing"], ] )) client.metadata.createTemplate( scope: "enterprise", templateKey: "personnelRecord", displayName: "Personnel Record", hidden: false, fields: templateFields ) { (result: Result<MetadataTemplate, BoxSDKError>) in guard case let .success(template) = result { print("Error creating metadata template") return } print("Created metadata template with ID \(template.id)") } ``` ## Update Metadata Template To update a metadata template, including to modify its fields, call [`client.metadata.updateTemplate(scope:templateKey:operation:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/MetadataModule.html#/s:6BoxSDK14MetadataModuleC14updateTemplate5scope11templateKey9operation10completionySS_SSAA0cF9OperationOys6ResultOyAA0cF0CAA0A8SDKErrorCGctF) with the scope and key of the template to update, as well as the update operation to perform. In this example, we are updating the metadata template using the ReorderEnumOptions operation. Other metadata template update operations include: addEnumOption, addField, editTemplate, reorderFields ``` client.metadata.updateTemplate( scope: "enterprise", templateKey: "personnelRecord", operation: .reorderEnumOptions(fieldKey: "department", enumOptionKeys: ["Marketing", "Sales", "HR"]) ) { (result: Result<MetadataTemplate, BoxSDKError>) in guard case let .success(template) = result { print("Error updating metadata template") return } print("Updated metadata template with ID \(template.id)") } ``` ## Delete Metadata Template To delete a metadata template, call [`client.metadata.deleteTemplate(scope:templateKey:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/MetadataModule.html#/s:6BoxSDK14MetadataModuleC14deleteTemplate5scope11templateKey10completionySS_SSys6ResultOyytAA0A8SDKErrorCGctF) with the scope and key of the template to delete. ``` client.metadata.deleteTemplate( scope: "enterprise", templateKey: "personnelRecord" ) { (result: Result<Void, BoxSDKError>) in guard case .success = result { print("Error deleting metadata template") return } print("Metadata template deleted") } ``` ## List Metadata Templates To retrieve the collection of available metadata templates in a particular scope, call [`client.metadata.listEnterpriseTemplates(scope:marker:limit:)`](https://opensource.box.com/box-ios-sdk/Classes/MetadataModule.html#/s:6BoxSDK14MetadataModuleC23listEnterpriseTemplates5scope6marker5limit10completionySS_SSSgSiSgys6ResultOyAA14PagingIteratorCyAA0C8TemplateCGAA0A8SDKErrorCGctF) with the scope. This method will return an iterator, which is used to retrieve metadata templates. ``` let iterator = client.metadata.listEnterpriseTemplates(scope: "enterprise") iterator.next { results in switch results { case let .success(page): for template in page.entries { print("Template name: \(template.displayName)") } case let .failure(error): print(error) } } ``` Similarly, to get all templates available in the `global` scope. ``` let iterator = client.metadata.listEnterpriseTemplates(scope: "global") iterator.next { results in switch results { case let .success(page): for template in page.entries { print("Template name: \(template.displayName)") } case let .failure(error): print(error) } } ``` ## Get All Metadata on File To retrieve all metadata attached to a file, call [`client.metadata.list(forFileId:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/MetadataModule.html#/s:6BoxSDK14MetadataModuleC4list9forFileId10completionySS_ys6ResultOySayAA0C6ObjectCGAA0A8SDKErrorCGctF) with the ID of the file. ``` client.metadata.list(forFileId: "11111") { (result: Result<[MetadataObject], BoxSDKError>) in guard case let .success(metadata) = result { print("Error retrieving metadata") return } print("Retrieved \(metadata.count) metadata instances:") for instance in metadata { print("- \(instance.template)") } } ``` ## Get Metadata Instance on File To retrieve a specific metadata instance attached to a file, call [`client.metadata.get(forFileWithId:scope:templateKey:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/MetadataModule.html#/s:6BoxSDK14MetadataModuleC3get13forFileWithId5scope11templateKey10completionySS_S2Sys6ResultOyAA0C6ObjectCAA0A8SDKErrorCGctF) with the file ID, as well as the scope and key of the metadata template of the instance. ``` client.metadata.get( forFileWithId: "11111", scope: "enterprise", templateKey: "personnelRecord" ) { (result: Result<MetadataObject, BoxSDKError>) in guard case let .success(metadata) = result { print("Error retrieving metadata") return } print("Found personnel record for \(metadata.keys["name"])") } ``` ## Add Metadata Instance to File To attach a new metadata instance to a file, call [`client.metadata.create(forFileWithId:scope:templateKey:keys:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/MetadataModule.html#/s:6BoxSDK14MetadataModuleC6create13forFileWithId5scope11templateKey4keys10completionySS_S2SSDySSypGys6ResultOyAA0C6ObjectCAA0A8SDKErrorCGctF) with the ID of the file, as well as the scope and key of the metadata template to use and the metadata keys and values to attach. ``` let metadata = [ "name": "John Doe", "birthday": "2000-01-01T00:00:00Z", "department": "Sales" ] client.metadata.create( forFileWithId: "11111", scope: "enterprise", templateKey: "personnelRecord", keys: metadata ) { (result: Result<MetadataObject, BoxSDKError>) in guard case let .success(metadata) = result { print("Error adding metadata") return } print("Successfully attached metadata") } ``` ## Update Metadata Instance on File To update the values in a metadata instance attached to a file, call [`client.metadata.updateforFileWithId:scope:templateKey:operations:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/MetadataModule.html#/s:6BoxSDK14MetadataModuleC6update13forFileWithId5scope11templateKey10operations10completionySS_S2SSayAA0gC9OperationOGys6ResultOyAA0C6ObjectCAA0A8SDKErrorCGctF) with the ID of the file, the scope and key of the metadata template associated with the instance, and the operations to perform on the metadata. ``` client.metadata.update( forFileWithId: "11111", scope: "enterprise", templateKey: "personnelRecord", operations: [ .test(path: "/department", value: "Sales"), .replace(path: "/department", value: "Marketing") ] ) { (result: Result<MetadataObject, BoxSDKError>) in guard case let .success(metadata) = result { print("Error updating metadata") return } print("Employee department updated to \(metadata.keys["department"])") } ``` ## Remove Metadata Instance from File To remove a specific metadata instance from a file, call [`client.metadata.delete(forFileWithId:scope:templateKey:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/MetadataModule.html#/s:6BoxSDK14MetadataModuleC6delete13forFileWithId5scope11templateKey10completionySS_S2Sys6ResultOyytAA0A8SDKErrorCGctF) with the ID of the file, as well as the scope and key of the metadata template associated with the instance. ``` client.metadata.delete( forFileWithId: "11111", scope: "enterprise", templateKey: "personnelRecord" ) { (result: Result<Void, BoxSDKError>) in guard case .success = result { print("Error deleting metadata instance") return } print("Metadata instance deleted") } ``` ## Get All Metadata on Folder To retrieve all metadata attached to a folder, call [`client.metadata.list(forFolderId:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/MetadataModule.html#/s:6BoxSDK14MetadataModuleC4list11forFolderId10completionySS_ys6ResultOySayAA0C6ObjectCGAA0A8SDKErrorCGctF) with the ID of the folder. ``` client.metadata.list(forFolderId: "22222") { (result: Result<[MetadataObject], BoxSDKError>) in guard case let .success(metadata) = result { print("Error retrieving metadata") return } print("Retrieved \(metadata.count) metadata instances:") for instance in metadata { print("- \(instance.template)") } } ``` ## Get Metadata Instance on Folder To retrieve a specific metadata instance attached to a folder, call [`client.metadata.get(forFolderWithId:scope:templateKey:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/MetadataModule.html#/s:6BoxSDK14MetadataModuleC3get15forFolderWithId5scope11templateKey10completionySS_S2Sys6ResultOyAA0C6ObjectCAA0A8SDKErrorCGctF) with the folder ID, as well as the scope and key of the metadata template of the instance. ``` client.metadata.get( forFolderWithId: "22222", scope: "enterprise", templateKey: "personnelRecord" ) { (result: Result<MetadataObject, BoxSDKError>) in guard case let .success(metadata) = result { print("Error retrieving metadata") return } print("Found personnel record for \(metadata.keys["name"])") } ``` ## Add Metadata Instance to Folder To attach a new metadata instance to a folder, call [`client.metadata.create(forFolderWithId:scope:templateKey:keys:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/MetadataModule.html#/s:6BoxSDK14MetadataModuleC6create15forFolderWithId5scope11templateKey4keys10completionySS_S2SSDySSypGys6ResultOyAA0C6ObjectCAA0A8SDKErrorCGctF) with the ID of the folder, as well as the scope and key of the metadata template to use and the metadata keys and values to attach. ``` let metadata = [ "name": "John Doe", "birthday": "2000-01-01T00:00:00Z", "department": "Sales" ] client.metadata.create( forFolderWithId: "22222", scope: "enterprise", templateKey: "personnelRecord", keys: metadata ) { (result: Result<MetadataObject, BoxSDKError>) in guard case let .success(metadata) = result { print("Error adding metadata") return } print("Successfully attached metadata") } ``` ## Update Metadata Instance on Folder To update the values in a metadata instance attached to a folder, call [`client.metadata.update(forFolderWithId:scope:templateKey:operations:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/MetadataModule.html#/s:6BoxSDK14MetadataModuleC6update15forFolderWithId5scope11templateKey10operations10completionySS_S2SSayAA0gC9OperationOGys6ResultOyAA0C6ObjectCAA0A8SDKErrorCGctF) with the ID of the folder, the scope and key of the metadata template associated with the instance, and the operations to perform on the metadata. ``` client.metadata.update( forFolderWithId: "22222", scope: "enterprise", templateKey: "personnelRecord", operations: [ .test(path: "/department", value: "Sales"), .replace(path: "/department", value: "Marketing") ] ) { (result: Result<MetadataObject, BoxSDKError>) in guard case let .success(metadata) = result { print("Error updating metadata") return } print("Employee department updated to \(metadata.keys["department"])") } ``` ## Remove Metadata Instance from Folder To remove a specific metadata instance from a folder, call [`client.metadata.delete(forFolderWithId:scope:templateKey:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/MetadataModule.html#/s:6BoxSDK14MetadataModuleC6delete15forFolderWithId5scope11templateKey10completionySS_S2Sys6ResultOyytAA0A8SDKErrorCGctF) with the ID of the folder, as well as the scope and key of the metadata template associated with the instance. ``` client.metadata.delete( forFolderWithId: "22222", scope: "enterprise", templateKey: "personnelRecord" ) { (result: Result<Void, BoxSDKError>) in guard case .success = result { print("Error deleting metadata instance") return } print("Metadata instance deleted") } ``` --- ### Metadata Cascade Policies **Type:** page | **Section:** Additional Resources Metadata Cascade Policies Metadata Cascade Policies allow the metadata values on a folder to be applied to the files within that folder. A… # Metadata Cascade Policies Metadata Cascade Policies allow the metadata values on a folder to be applied to the files within that folder. A cascade policy associates the folder with a specific metadata template whose instance values on the folder should be cascaded to files within the folder. **Note:** The Metadata Cascade Policy endpoints are currently in beta. Please email [betas+metadata@box.com](mailto:betas+metadata@box.com) if you would like to enable this beta feature for your enterprise. If you do not have this enabled for your enterprise, you will get a 403 error. - [Create a Metadata Cascade Policy](#create-a-metadata-cascade-policy) - [Get Information About a Metadata Cascade Policy](#get-information-about-a-metadata-cascade-policy) - [Get Cascade Policies on a Folder](#get-cascade-policies-on-a-folder) - [Force Apply Cascade Policy](#force-apply-cascade-policy) - [Remove Cascade Policy](#remove-cascade-policy) ## Create a Metadata Cascade Policy To create a metadata cascade policy on a folder, call [`folder.cascade_metadata(metadata_template)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.folder.Folder.cascade_metadata) with the [`MetadataTemplate`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.metadata_template.MetadataTemplate) whose values should be cascaded within the folder. This method returns a [`MetadataCascadePolicy`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.metadata_cascade_policy.MetadataCascadePolicy) object representing the newly-created policy. ``` folder = client.folder(folder_id='22222') metadata_template = client.metadata_template('enterprise', 'securityClassiciation') cascade_policy = folder.cascade_metadata(metadata_template) print(f'Folder {cascade_policy.parent.id} has a metadata cascade policy for {cascade_policy.scope} template "{cascade_policy.templateKey}"') ``` ## Get Information About a Metadata Cascade Policy To retrieve information about a metadata cascade policy, first call [`client.metadata_cascade_policy(policy_id)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.client.html#boxsdk.client.client.Client.metadata_cascade_policy) with the ID of the cascade policy to initialize the [`MetadataCascadePolicy`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.metadata_cascade_policy.MetadataCascadePolicy) object, then call [`cascade_policy.get()`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.base_object.BaseObject.get) to retrieve data about the policy. This method returns a new [`MetadataCascadePolicy`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.metadata_cascade_policy.MetadataCascadePolicy) object with fields populated by data from the API, leaving the original object unmodified. ``` cascade_policy = client.metadata_cascade_policy('84113349-794d-445c-b93c-d8481b223434').get() print(f'Cascade policy applies to a template owned by enterprise {cascade_policy.owner_enterprise.id}') ``` ## Get Cascade Policies on a Folder To get a list of the cascade policies applied to a folder, call [`folder.get_metadata_cascade_policies(owner_enterprise=None, limit=None, marker=None, fields=None)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.folder.Folder.get_metadata_cascade_policies). You can optionally pass an [`Enterprise`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.enterprise.Enterprise) object via the `owner_enterprise` parameter to retrieve cascade policies related to templates for a specific enterprise; if not specified, this defaults to the current enterprise. This method returns a [`BoxObjectCollection`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.pagination.html#boxsdk.pagination.box_object_collection.BoxObjectCollection) that allows you to iterate over the [`MetadataCascadePolicy`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.metadata_cascade_policy.MetadataCascadePolicy) objects in the collection. ``` cascade_policies = client.folder(folder_id='22222').get_metadata_cascade_policies() for policy in cascade_policies: print(f'Metadata template {policy.templateKey} is cascaded') ``` ## Force Apply Cascade Policy A Cascade Policy can be forced to re-apply to all files in the associated folder by calling [`cascade_policy.force_apply(conflict_resolution)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.metadata_cascade_policy.MetadataCascadePolicy.force_apply) with the conflict resolution strategy to use. If files in the folder already have metadata values that conflict with the ones being force applied from the folder, you can choose to either preserve the existing values or overwrite them with the folder's values. This method returns `True` to indicate that the force application was successful. ``` from boxsdk.object.metadata_cascade_policy import CascadePolicyConflictResolution cascade_policy = client.metadata_cascade_policy(policy_id='84113349-794d-445c-b93c-d8481b223434') cascade_policy.force_apply(CascadePolicyConflictResolution.PRESERVE_EXISTING) print('Cascade policy was force applied!') ``` ## Remove Cascade Policy A metadata cascade policy can be removed from a folder by calling [`cascade_policy.delete()`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.base_object.BaseObject.delete). This method returns `True` to indicate that the deletion was successful. ``` client.metadata_cascade_policy(policy_id='84113349-794d-445c-b93c-d8481b223434').delete() print('Cascade policy successfully removed') ``` --- ### Metadata Cascade Policies **Type:** page | **Section:** Additional Resources Metadata Cascade Policies A metadata cascade policy indicates if a metadata instance value should be cascaded to files and subfolders in a… # Metadata Cascade Policies A metadata cascade policy indicates if a metadata instance value should be cascaded to files and subfolders in a specific folder. Any user with edit permisions on a folder can create metadata cascade policies for that given folder. Policies are assigned to exactly one folder and exactly one metadata instance on that folder. It should be noted that there is some delay from file upload to metadata application. - [Create Metadata Cascade Policy](#create-metadata-cascade-policy) - [Get a Metadata Cascade Policy](#get-a-metadata-cascade-policy) - [Get Metadata Cascade Policies for Folder](#get-metadata-cascade-policies-for-folder) - [Force Apply Metadata Cascade Policy](#force-apply-metadata-cascade-policy) ## Create Metadata Cascade Policy To create a new metadata cascade policy, call `MetadataCascadePolicyManager.CreateCascadePolicyAsync(string folderId, string scope, string templateKey)`. ``` BoxMetadataCascadePolicy metadataCascadePolicy = await client.MetadataCascadePolicyManager .CreateCascadePolicyAsync("22222", "enterprise_11111", "templateKey"); ``` ## Get a Metadata Cascade Policy To get information about a specific metadata cascade policy, call `MetadataCascadePolicyManager.GetCascadePolicyAsync(string policyId)` ``` BoxMetadataCascadePolicy retrievedCascadePolicy = await client.MetadataCascadePolicyManager .GetCascadePolicyAsync("12345", IEnumerable<string> fields = null); ``` ## Get Metadata Cascade Policies for Folder To retrieve a collection of metadata cascade policies within a given folder for the current enterprise, use `MetadataCascadePolicyManager.GetAllMetadataCascadePoliciesAsync(string folderId, string ownerEnterpriseId = null, int limit = 100, string nextMarker = null, IEnumerable<string> fields = null, bool autopaginate = false)` ``` BoxCollectionMarkerBased<BoxMetadataCascadePolicy> metadataCascadePolicies = await client.MetadataCascadePolicyManager.GetAllMetadataCascadePoliciesAsync("12345"); ``` You can also retrieve metadata cascade policies for another enterprise with specific fields to retrieve by using `MetadataCascadePolicyManager.GetAllMetadataCascadePoliciesAsync(string folderId, string ownerEnterpriseId, int limit, IEnumberable<string> fields)` ``` string folderId = "1111"; string ownerEnterpriseId = "2222"; BoxCollectionMarkerBased<BoxMetadataCascadePolicy> metadataCascadePolicies = await client.MetadataCascadePolicyManager.GetAllMetadataCascadePoliciesAsync(folderId, ownerEnterpriseId); ``` ## Force Apply Metadata Cascade Policy To apply a policy on a folder that already has one, use `MetadataCascadePolicyManager.ForceApplyCascadePolicyAsync(string policyId, string conflictResolution)` ``` string policyId = "11111"; string conflictResolution = Constants.ConflictResolution.Overwrite BoxMetadataCascadePolicy newCascadePolicy = client.MetadataCascadePolicyManager .ForceApplyCascadePolicyAsync(policyId, conflictResolution); ``` The conflict_resolution field can be set to either `none` which will preserve the existing value on the file, or `overwrite`, which will force-apply the cascade policy's value over any existing value. --- ### Metadata Templates **Type:** page | **Section:** Additional Resources Metadata Templates Metadata that belongs to a file is grouped by templates. Templates allow the metadata service to provide a multitude of… # Metadata Templates Metadata that belongs to a file is grouped by templates. Templates allow the metadata service to provide a multitude of services, such as pre-defining sets of key:value pairs or schema enforcement on specific fields. - [Create Metadata Template](#create-metadata-template) - [Update Metadata Template](#update-metadata-template) [Get Metadata Template](#get-metadata-template) - [Get by scope and template key](#get-by-scope-and-template-key) - [Get by ID](#get-by-id) [Get Enterprise Metadata Templates](#get-enterprise-metadata-templates) [Delete a Metadata Template](#delete-a-metadata-template) [Execute Metadata Query](#execute-metadata-query) ## Create Metadata Template The [`createMetadataTemplate(BoxAPIConnection api, String templateScope, String templateKey, String displayName, Boolean hidden, List<Field> fields)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/MetadataTemplate.html#createMetadataTemplate-com.box.sdk.BoxAPIConnection-java.lang.String-java.lang.String-java.lang.String-boolean-java.util.List-) method will create a metadata template schema. You can create custom metadata fields that will be associated with the metadata template. ``` MetadataTemplate.Field metadataField = new MetadataTemplate.Field(); metadataField.setType("string"); metadataField.setKey("text"); metadataField.setDisplayName("Text"); List<MetadataTemplate.Field> fields = new ArrayList<MetadataTemplate.Field>(); fields.add(metadataField); MetadataTemplate template = MetadataTemplate.createMetadataTemplate(api, "enterprise", "CustomField", "Custom Field", false, fields); final JsonObject jsonObject = new JsonObject(); jsonObject.add("text", "This is a test text"); Metadata metadata = new Metadata(jsonObject); boxFile.createMetadata("CustomField", metadata); ``` ## Update Metadata Template To update an existing metadata template, call the [`updateMetadataTemplate(BoxAPIConnection api, String scope, String template, List<FieldOperation> fieldOperations)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/MetadataTemplate.html#updateMetadataTemplate-com.box.sdk.BoxAPIConnection-java.lang.String-java.lang.String-java.util.List-) method with the scope and key of the template, and the list of field operations to perform: ``` List<MetadataTemplate.FieldOperation> updates = new ArrayList<MetadataTemplate.FieldOperation>(); String addCategoryFieldJSON = "{\"op\":\"addField\","\"data\":{" + "\"displayName\":\"Category\",\"key\":\"category\",\"hidden\":false,\"type\":\"string\"}}"; updates.add(new MetadataTemplate.FieldOperation(addCategoryFieldJSON)); String changeTemplateNameJSON = "{\"op\":\"editTemplate\",\"data\":{" + "\"displayName\":\"My Metadata\"}}"; updates.add(new MetadataTemplate.FieldOperation(changeTemplateNameJSON)); MetadataTemplate.updateMetadataTemplate(api, "enterprise", "myData", updates); ``` ## Get Metadata Template ### Get by scope and template key The [`getMetadataTemplate(BoxAPIConnection api)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/MetadataTemplate.html#getMetadataTemplate-com.box.sdk.BoxAPIConnection-) method will return information about default metadata schema. Also, [`getMetadataTemplate(BoxAPIConnection api, String templateKey)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/MetadataTemplate.html#getMetadataTemplate-com.box.sdk.BoxAPIConnection-java.lang.String-) and [`getMetadataTemplate(BoxAPIConnection api, String templateKey, String templateScope, String... fields)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/MetadataTemplate.html#getMetadataTemplate-com.box.sdk.BoxAPIConnection-java.lang.String-java.lang.String-java.lang.String...-) can be used to set metadata template name, metadata scope and fields to retrieve. ``` MetadataTemplate template = MetadataTemplate.getMetadataTemplate(api, "templateName"); ``` ### Get by ID The static [`MetadataTemplate.getMetadataTemplateByID(BoxAPIConnection api, String templateID)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/MetadataTemplate.html#getMetadataTemplateByID-com.box.sdk.BoxAPIConnection-java.lang.String-) method will return a specific metadata template. ``` MetadataTemplate template = MetadataTemplate.getMetadataTemplateByID(api, "37c0204b-3fe1-4a32-b9da-f28e88f4c4c6"); ``` ## Get Enterprise Metadata Templates Calling the static [`getEnterpriseMetadataTemplates(BoxAPIConnection api, String... fields)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/MetadataTemplate.html#getEnterpriseMetadataTemplates-com.box.sdk.BoxAPIConnection-java.lang.String...-) will return an iterable that will page through all metadata templates within a user's enterprise. Also, [`getEnterpriseMetadataTemplates(String templateScope, BoxAPIConnection api, String... fields)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/MetadataTemplate.html#getEnterpriseMetadataTemplates-java.lang.String-com.box.sdk.BoxAPIConnection-java.lang.String...-) and [`getEnterpriseMetadataTemplates(String templateScope, int limit, BoxAPIConnection api, String... fields)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/MetadataTemplate.html#getEnterpriseMetadataTemplates-java.lang.String-int-com.box.sdk.BoxAPIConnection-java.lang.String...-) can be used to set metadata scope, limit of items per single response. ``` Iterable<MetadataTemplate> templates = MetadataTemplate.getEnterpriseMetadataTemplates(api); for (MetadataTemplate templateInfo : templates) { // Do something with the metadata template. } ``` To return the metadata templates available to all enterprises pass in the `global` scope. ``` Iterable<MetadataTemplate> templates = MetadataTemplate.getEnterpriseMetadataTemplates('global', api); for (MetadataTemplate templateInfo : templates) { // Do something with the metadata template. } ``` ## Delete a Metadata Template The [`deleteMetadataTemplate(BoxAPIConnection api, String scope, String template)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/MetadataTemplate.html#deleteMetadataTemplate-com.box.sdk.BoxAPIConnection-java.lang.String-java.lang.String-) method will remove a metadata template schema from an enterprise. ``` MetadataTemplate.deleteMetadataTemplate(api, "enterprise", "templateName"); ``` ## Execute Metadata Query The [`executeMetadataQuery(BoxAPIConnection api, MetadataQuery queryBody)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/MetadataTemplate.html#executeMetadataQuery-com.box.sdk.BoxAPIConnection-com.box.sdk.MetadataQuery-) method queries files and folders based on their metadata. ``` String from = "enterprise_341532.test"; String query = "testfield = :arg"; String ancestorFolderId = "0"; MetadataQuery.OrderBy primaryOrderBy = MetadataQuery.OrderBy.ascending("primarySortKey"); MetadataQuery.OrderBy secondaryOrderBy = MetadataQuery.OrderBy.ascending("secondarySortKey"); MetadataQuery mQuery = new MetadataQuery(from); mQuery.setQuery(query); mQuery.setAncestorFolderId(ancestorFolderId); mQuery.setOrderBy(primaryOrderBy, secondaryOrderBy); mQuery.addParameter("arg", "test"); mQuery.setFields("metadata.enterprise_341532.test.customField"); BoxResourceIterable<BoxItem.Info> results = MetadataTemplate.executeMetadataQuery(api, mQuery); for (BoxItem.Info r: results) { if (r instanceof BoxFile.Info) { BoxFile.Info fileInfo = (BoxFile.Info) r; Metadata fileMetadata = fileInfo.getMetadata("test", "enterprise_341532"); String customFieldValue = fileMetadata.getString("/customField"); System.out.println(customFieldValue); } else if (r instanceof BoxFolder.Info) { BoxFolder.Info folderInfo = (BoxFolder.Info) r; Metadata folderMetadata = folderInfo.getMetadata("test", "enterprise_341532"); String customFieldValue = folderMetadata.getString("/customField"); System.out.println(customFieldValue); } } ``` --- ### MetadataCascadePoliciesManager **Type:** page | **Section:** Additional Resources MetadataCascadePoliciesManager List metadata cascade policies Create metadata cascade policy Get metadata cascade policy Remove metadata… # MetadataCascadePoliciesManager - [List metadata cascade policies](#list-metadata-cascade-policies) - [Create metadata cascade policy](#create-metadata-cascade-policy) - [Get metadata cascade policy](#get-metadata-cascade-policy) - [Remove metadata cascade policy](#remove-metadata-cascade-policy) - [Force-apply metadata cascade policy to folder](#force-apply-metadata-cascade-policy-to-folder) ## List metadata cascade policies Retrieves a list of all the metadata cascade policies that are applied to a given folder. This can not be used on the root folder with ID `0`. This operation is performed by calling function `getMetadataCascadePolicies`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-metadata-cascade-policies/). ``` await client.metadataCascadePolicies.getMetadataCascadePolicies({ folderId: folder.id, } satisfies GetMetadataCascadePoliciesQueryParams); ``` ### Arguments queryParams `GetMetadataCascadePoliciesQueryParams` - Query parameters of getMetadataCascadePolicies method optionalsInput `GetMetadataCascadePoliciesOptionalsInput` ### Returns This function returns a value of type `MetadataCascadePolicies`. Returns a list of metadata cascade policies. ## Create metadata cascade policy Creates a new metadata cascade policy that applies a given metadata template to a given folder and automatically cascades it down to any files within that folder. In order for the policy to be applied a metadata instance must first be applied to the folder the policy is to be applied to. This operation is performed by calling function `createMetadataCascadePolicy`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-metadata-cascade-policies/). ``` await client.metadataCascadePolicies.createMetadataCascadePolicy({ folderId: folder.id, scope: 'enterprise' as CreateMetadataCascadePolicyRequestBodyScopeField, templateKey: templateKey, } satisfies CreateMetadataCascadePolicyRequestBody); ``` ### Arguments requestBody `CreateMetadataCascadePolicyRequestBody` - Request body of createMetadataCascadePolicy method optionalsInput `CreateMetadataCascadePolicyOptionalsInput` ### Returns This function returns a value of type `MetadataCascadePolicy`. Returns a new of metadata cascade policy. ## Get metadata cascade policy Retrieve a specific metadata cascade policy assigned to a folder. This operation is performed by calling function `getMetadataCascadePolicyById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-metadata-cascade-policies-id/). ``` await client.metadataCascadePolicies.getMetadataCascadePolicyById( cascadePolicyId, ); ``` ### Arguments metadataCascadePolicyId `string` - The ID of the metadata cascade policy. Example: "6fd4ff89-8fc1-42cf-8b29-1890dedd26d7" optionalsInput `GetMetadataCascadePolicyByIdOptionalsInput` ### Returns This function returns a value of type `MetadataCascadePolicy`. Returns a metadata cascade policy. ## Remove metadata cascade policy Deletes a metadata cascade policy. This operation is performed by calling function `deleteMetadataCascadePolicyById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-metadata-cascade-policies-id/). ``` await client.metadataCascadePolicies.deleteMetadataCascadePolicyById( cascadePolicyId, ); ``` ### Arguments metadataCascadePolicyId `string` - The ID of the metadata cascade policy. Example: "6fd4ff89-8fc1-42cf-8b29-1890dedd26d7" optionalsInput `DeleteMetadataCascadePolicyByIdOptionalsInput` ### Returns This function returns a value of type `undefined`. Returns an empty response when the policy is successfully deleted. ## Force-apply metadata cascade policy to folder Force the metadata on a folder with a metadata cascade policy to be applied to all of its children. This can be used after creating a new cascade policy to enforce the metadata to be cascaded down to all existing files within that folder. This operation is performed by calling function `applyMetadataCascadePolicy`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-metadata-cascade-policies-id-apply/). ``` await client.metadataCascadePolicies.applyMetadataCascadePolicy( cascadePolicyId, { conflictResolution: 'overwrite' as ApplyMetadataCascadePolicyRequestBodyConflictResolutionField, } satisfies ApplyMetadataCascadePolicyRequestBody, ); ``` ### Arguments metadataCascadePolicyId `string` - The ID of the cascade policy to force-apply. Example: "6fd4ff89-8fc1-42cf-8b29-1890dedd26d7" requestBody `ApplyMetadataCascadePolicyRequestBody` - Request body of applyMetadataCascadePolicy method optionalsInput `ApplyMetadataCascadePolicyOptionalsInput` ### Returns This function returns a value of type `undefined`. Returns an empty response when the API call was successful. The metadata cascade operation will be performed asynchronously. The API call will return directly, before the cascade operation is complete. There is currently no API to check for the status of this operation. --- ### MetadataCascadePoliciesManager **Type:** page | **Section:** Additional Resources MetadataCascadePoliciesManager List metadata cascade policies Create metadata cascade policy Get metadata cascade policy Remove metadata… # MetadataCascadePoliciesManager - [List metadata cascade policies](#list-metadata-cascade-policies) - [Create metadata cascade policy](#create-metadata-cascade-policy) - [Get metadata cascade policy](#get-metadata-cascade-policy) - [Remove metadata cascade policy](#remove-metadata-cascade-policy) - [Force-apply metadata cascade policy to folder](#force-apply-metadata-cascade-policy-to-folder) ## List metadata cascade policies Retrieves a list of all the metadata cascade policies that are applied to a given folder. This can not be used on the root folder with ID `0`. This operation is performed by calling function `get_metadata_cascade_policies`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-metadata-cascade-policies/). ``` client.metadata_cascade_policies.get_metadata_cascade_policies(folder.id) ``` ### Arguments folder_id `str` - Specifies which folder to return policies for. This can not be used on the root folder with ID `0`. owner_enterprise_id `Optional[str]` - The ID of the enterprise ID for which to find metadata cascade policies. If not specified, it defaults to the current enterprise. marker `Optional[str]` - Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`. offset `Optional[int]` - The offset of the item at which to begin the response. Queries with offset parameter value exceeding 10000 will be rejected with a 400 response. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `MetadataCascadePolicies`. Returns a list of metadata cascade policies. ## Create metadata cascade policy Creates a new metadata cascade policy that applies a given metadata template to a given folder and automatically cascades it down to any files within that folder. In order for the policy to be applied a metadata instance must first be applied to the folder the policy is to be applied to. This operation is performed by calling function `create_metadata_cascade_policy`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-metadata-cascade-policies/). ``` client.metadata_cascade_policies.create_metadata_cascade_policy( folder.id, CreateMetadataCascadePolicyScope.ENTERPRISE, template_key ) ``` ### Arguments folder_id `str` - The ID of the folder to apply the policy to. This folder will need to already have an instance of the targeted metadata template applied to it. scope `CreateMetadataCascadePolicyScope` - The scope of the targeted metadata template. This template will need to already have an instance applied to the targeted folder. template_key `str` - The key of the targeted metadata template. This template will need to already have an instance applied to the targeted folder. In many cases the template key is automatically derived of its display name, for example `Contract Template` would become `contractTemplate`. In some cases the creator of the template will have provided its own template key. Please [list the templates for an enterprise][list], or get all instances on a [file][file] or [folder][folder] to inspect a template's key. [list]: e://get-metadata-templates-enterprise [file]: e://get-files-id-metadata [folder]: e://get-folders-id-metadata extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `MetadataCascadePolicy`. Returns a new of metadata cascade policy. ## Get metadata cascade policy Retrieve a specific metadata cascade policy assigned to a folder. This operation is performed by calling function `get_metadata_cascade_policy_by_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-metadata-cascade-policies-id/). ``` client.metadata_cascade_policies.get_metadata_cascade_policy_by_id(cascade_policy_id) ``` ### Arguments metadata_cascade_policy_id `str` - The ID of the metadata cascade policy. Example: "6fd4ff89-8fc1-42cf-8b29-1890dedd26d7" extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `MetadataCascadePolicy`. Returns a metadata cascade policy. ## Remove metadata cascade policy Deletes a metadata cascade policy. This operation is performed by calling function `delete_metadata_cascade_policy_by_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-metadata-cascade-policies-id/). ``` client.metadata_cascade_policies.delete_metadata_cascade_policy_by_id(cascade_policy_id) ``` ### Arguments metadata_cascade_policy_id `str` - The ID of the metadata cascade policy. Example: "6fd4ff89-8fc1-42cf-8b29-1890dedd26d7" extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `None`. Returns an empty response when the policy is successfully deleted. ## Force-apply metadata cascade policy to folder Force the metadata on a folder with a metadata cascade policy to be applied to all of its children. This can be used after creating a new cascade policy to enforce the metadata to be cascaded down to all existing files within that folder. This operation is performed by calling function `apply_metadata_cascade_policy`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-metadata-cascade-policies-id-apply/). ``` client.metadata_cascade_policies.apply_metadata_cascade_policy( cascade_policy_id, ApplyMetadataCascadePolicyConflictResolution.OVERWRITE ) ``` ### Arguments metadata_cascade_policy_id `str` - The ID of the cascade policy to force-apply. Example: "6fd4ff89-8fc1-42cf-8b29-1890dedd26d7" conflict_resolution `ApplyMetadataCascadePolicyConflictResolution` - Describes the desired behavior when dealing with the conflict where a metadata template already has an instance applied to a child. _ `none` will preserve the existing value on the file _ `overwrite` will force-apply the templates values over any existing values. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `None`. Returns an empty response when the API call was successful. The metadata cascade operation will be performed asynchronously. The API call will return directly, before the cascade operation is complete. There is currently no API to check for the status of this operation. --- ### MetadataTemplatesManager **Type:** page | **Section:** Additional Resources MetadataTemplatesManager Find metadata template by instance ID Get metadata template by name Update metadata template Remove metadata… # MetadataTemplatesManager - [Find metadata template by instance ID](#find-metadata-template-by-instance-id) - [Get metadata template by name](#get-metadata-template-by-name) - [Update metadata template](#update-metadata-template) - [Remove metadata template](#remove-metadata-template) - [Get metadata template by ID](#get-metadata-template-by-id) - [List all global metadata templates](#list-all-global-metadata-templates) - [List all metadata templates for enterprise](#list-all-metadata-templates-for-enterprise) - [Create metadata template](#create-metadata-template) ## Find metadata template by instance ID Finds a metadata template by searching for the ID of an instance of the template. This operation is performed by calling function `getMetadataTemplatesByInstanceId`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-metadata-templates/). ``` await client.metadataTemplates.getMetadataTemplatesByInstanceId({ metadataInstanceId: createdMetadataInstance.id!, } satisfies GetMetadataTemplatesByInstanceIdQueryParams); ``` ### Arguments queryParams `GetMetadataTemplatesByInstanceIdQueryParams` - Query parameters of getMetadataTemplatesByInstanceId method optionalsInput `GetMetadataTemplatesByInstanceIdOptionalsInput` ### Returns This function returns a value of type `MetadataTemplates`. Returns a list containing the 1 metadata template that matches the instance ID. ## Get metadata template by name Retrieves a metadata template by its `scope` and `templateKey` values. To find the `scope` and `templateKey` for a template, list all templates for an enterprise or globally, or list all templates applied to a file or folder. This operation is performed by calling function `getMetadataTemplate`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-metadata-templates-id-id-schema/). ``` await client.metadataTemplates.getMetadataTemplate( 'enterprise' as GetMetadataTemplateScope, template.templateKey!, ); ``` ### Arguments scope `GetMetadataTemplateScope` - The scope of the metadata template. Example: "global" templateKey `string` - The name of the metadata template. Example: "properties" optionalsInput `GetMetadataTemplateOptionalsInput` ### Returns This function returns a value of type `MetadataTemplate`. Returns the metadata template matching the `scope` and `template` name. ## Update metadata template Updates a metadata template. The metadata template can only be updated if the template already exists. The update is applied atomically. If any errors occur during the application of the operations, the metadata template will not be changed. This operation is performed by calling function `updateMetadataTemplate`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-metadata-templates-id-id-schema/). ``` await client.metadataTemplates.updateMetadataTemplate( 'enterprise' as UpdateMetadataTemplateScope, templateKey, [ { op: 'addField' as UpdateMetadataTemplateRequestBodyOpField, fieldKey: 'newfieldname', data: { ['type']: 'string', ['displayName']: 'newFieldName' }, } satisfies UpdateMetadataTemplateRequestBody, ], ); ``` ### Arguments scope `UpdateMetadataTemplateScope` - The scope of the metadata template. Example: "global" templateKey `string` - The name of the metadata template. Example: "properties" requestBody `readonly UpdateMetadataTemplateRequestBody[]` - Request body of updateMetadataTemplate method optionalsInput `UpdateMetadataTemplateOptionalsInput` ### Returns This function returns a value of type `MetadataTemplate`. Returns the updated metadata template, with the custom template data included. ## Remove metadata template Delete a metadata template and its instances. This deletion is permanent and can not be reversed. This operation is performed by calling function `deleteMetadataTemplate`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-metadata-templates-id-id-schema/). ``` await client.metadataTemplates.deleteMetadataTemplate( 'enterprise' as DeleteMetadataTemplateScope, template.templateKey!, ); ``` ### Arguments scope `DeleteMetadataTemplateScope` - The scope of the metadata template. Example: "global" templateKey `string` - The name of the metadata template. Example: "properties" optionalsInput `DeleteMetadataTemplateOptionalsInput` ### Returns This function returns a value of type `undefined`. Returns an empty response when the metadata template is successfully deleted. ## Get metadata template by ID Retrieves a metadata template by its ID. This operation is performed by calling function `getMetadataTemplateById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-metadata-templates-id/). ``` await client.metadataTemplates.getMetadataTemplateById(template.id); ``` ### Arguments templateId `string` - The ID of the template. Example: "f7a9891f" optionalsInput `GetMetadataTemplateByIdOptionalsInput` ### Returns This function returns a value of type `MetadataTemplate`. Returns the metadata template that matches the ID. ## List all global metadata templates Used to retrieve all generic, global metadata templates available to all enterprises using Box. This operation is performed by calling function `getGlobalMetadataTemplates`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-metadata-templates-global/). ``` await client.metadataTemplates.getGlobalMetadataTemplates(); ``` ### Arguments queryParams `GetGlobalMetadataTemplatesQueryParams` - Query parameters of getGlobalMetadataTemplates method headersInput `GetGlobalMetadataTemplatesHeadersInput` - Headers of getGlobalMetadataTemplates method cancellationToken `undefined | CancellationToken` - Token used for request cancellation. ### Returns This function returns a value of type `MetadataTemplates`. Returns all of the metadata templates available to all enterprises and their corresponding schema. ## List all metadata templates for enterprise Used to retrieve all metadata templates created to be used specifically within the user's enterprise. This operation is performed by calling function `getEnterpriseMetadataTemplates`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-metadata-templates-enterprise/). ``` await client.metadataTemplates.getEnterpriseMetadataTemplates(); ``` ### Arguments queryParams `GetEnterpriseMetadataTemplatesQueryParams` - Query parameters of getEnterpriseMetadataTemplates method headersInput `GetEnterpriseMetadataTemplatesHeadersInput` - Headers of getEnterpriseMetadataTemplates method cancellationToken `undefined | CancellationToken` - Token used for request cancellation. ### Returns This function returns a value of type `MetadataTemplates`. Returns all of the metadata templates within an enterprise and their corresponding schema. ## Create metadata template Creates a new metadata template that can be applied to files and folders. This operation is performed by calling function `createMetadataTemplate`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-metadata-templates-schema/). ``` await client.metadataTemplates.createMetadataTemplate({ scope: 'enterprise', displayName: templateKey, templateKey: templateKey, fields: [ { type: 'string' as CreateMetadataTemplateRequestBodyFieldsTypeField, key: 'testName', displayName: 'testName', } satisfies CreateMetadataTemplateRequestBodyFieldsField, { type: 'float' as CreateMetadataTemplateRequestBodyFieldsTypeField, key: 'age', displayName: 'age', } satisfies CreateMetadataTemplateRequestBodyFieldsField, { type: 'date' as CreateMetadataTemplateRequestBodyFieldsTypeField, key: 'birthDate', displayName: 'birthDate', } satisfies CreateMetadataTemplateRequestBodyFieldsField, { type: 'enum' as CreateMetadataTemplateRequestBodyFieldsTypeField, key: 'countryCode', displayName: 'countryCode', options: [ { key: 'US', } satisfies CreateMetadataTemplateRequestBodyFieldsOptionsField, { key: 'CA', } satisfies CreateMetadataTemplateRequestBodyFieldsOptionsField, ], } satisfies CreateMetadataTemplateRequestBodyFieldsField, { type: 'multiSelect' as CreateMetadataTemplateRequestBodyFieldsTypeField, key: 'sports', displayName: 'sports', options: [ { key: 'basketball', } satisfies CreateMetadataTemplateRequestBodyFieldsOptionsField, { key: 'football', } satisfies CreateMetadataTemplateRequestBodyFieldsOptionsField, { key: 'tennis', } satisfies CreateMetadataTemplateRequestBodyFieldsOptionsField, ], } satisfies CreateMetadataTemplateRequestBodyFieldsField, ], } satisfies CreateMetadataTemplateRequestBody); ``` ### Arguments requestBody `CreateMetadataTemplateRequestBody` - Request body of createMetadataTemplate method optionalsInput `CreateMetadataTemplateOptionalsInput` ### Returns This function returns a value of type `MetadataTemplate`. The schema representing the metadata template created. --- ### MetadataTemplatesManager **Type:** page | **Section:** Additional Resources MetadataTemplatesManager Find metadata template by instance ID Get metadata template by name Update metadata template Remove metadata… # MetadataTemplatesManager - [Find metadata template by instance ID](#find-metadata-template-by-instance-id) - [Get metadata template by name](#get-metadata-template-by-name) - [Update metadata template](#update-metadata-template) - [Remove metadata template](#remove-metadata-template) - [Get metadata template by ID](#get-metadata-template-by-id) - [List all global metadata templates](#list-all-global-metadata-templates) - [List all metadata templates for enterprise](#list-all-metadata-templates-for-enterprise) - [Create metadata template](#create-metadata-template) ## Find metadata template by instance ID Finds a metadata template by searching for the ID of an instance of the template. This operation is performed by calling function `get_metadata_templates_by_instance_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-metadata-templates/). ``` client.metadata_templates.get_metadata_templates_by_instance_id( created_metadata_instance.id ) ``` ### Arguments metadata_instance_id `str` - The ID of an instance of the metadata template to find. marker `Optional[str]` - Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`. limit `Optional[int]` - The maximum number of items to return per page. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `MetadataTemplates`. Returns a list containing the 1 metadata template that matches the instance ID. ## Get metadata template by name Retrieves a metadata template by its `scope` and `templateKey` values. To find the `scope` and `templateKey` for a template, list all templates for an enterprise or globally, or list all templates applied to a file or folder. This operation is performed by calling function `get_metadata_template`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-metadata-templates-id-id-schema/). ``` client.metadata_templates.get_metadata_template( GetMetadataTemplateScope.ENTERPRISE, template.template_key ) ``` ### Arguments scope `GetMetadataTemplateScope` - The scope of the metadata template. Example: "global" template_key `str` - The name of the metadata template. Example: "properties" extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `MetadataTemplate`. Returns the metadata template matching the `scope` and `template` name. ## Update metadata template Updates a metadata template. The metadata template can only be updated if the template already exists. The update is applied atomically. If any errors occur during the application of the operations, the metadata template will not be changed. This operation is performed by calling function `update_metadata_template`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-metadata-templates-id-id-schema/). ``` client.metadata_templates.update_metadata_template( UpdateMetadataTemplateScope.ENTERPRISE, template_key, [ UpdateMetadataTemplateRequestBody( op=UpdateMetadataTemplateRequestBodyOpField.ADDFIELD, field_key="newfieldname", data={"type": "string", "displayName": "newFieldName"}, ) ], ) ``` ### Arguments scope `UpdateMetadataTemplateScope` - The scope of the metadata template. Example: "global" template_key `str` - The name of the metadata template. Example: "properties" request_body `List[UpdateMetadataTemplateRequestBody]` - Request body of updateMetadataTemplate method extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `MetadataTemplate`. Returns the updated metadata template, with the custom template data included. ## Remove metadata template Delete a metadata template and its instances. This deletion is permanent and can not be reversed. This operation is performed by calling function `delete_metadata_template`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-metadata-templates-id-id-schema/). ``` client.metadata_templates.delete_metadata_template( DeleteMetadataTemplateScope.ENTERPRISE, template.template_key ) ``` ### Arguments scope `DeleteMetadataTemplateScope` - The scope of the metadata template. Example: "global" template_key `str` - The name of the metadata template. Example: "properties" extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `None`. Returns an empty response when the metadata template is successfully deleted. ## Get metadata template by ID Retrieves a metadata template by its ID. This operation is performed by calling function `get_metadata_template_by_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-metadata-templates-id/). ``` client.metadata_templates.get_metadata_template_by_id(template.id) ``` ### Arguments template_id `str` - The ID of the template. Example: "f7a9891f" extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `MetadataTemplate`. Returns the metadata template that matches the ID. ## List all global metadata templates Used to retrieve all generic, global metadata templates available to all enterprises using Box. This operation is performed by calling function `get_global_metadata_templates`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-metadata-templates-global/). ``` client.metadata_templates.get_global_metadata_templates() ``` ### Arguments marker `Optional[str]` - Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`. limit `Optional[int]` - The maximum number of items to return per page. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `MetadataTemplates`. Returns all of the metadata templates available to all enterprises and their corresponding schema. ## List all metadata templates for enterprise Used to retrieve all metadata templates created to be used specifically within the user's enterprise. This operation is performed by calling function `get_enterprise_metadata_templates`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-metadata-templates-enterprise/). ``` client.metadata_templates.get_enterprise_metadata_templates() ``` ### Arguments marker `Optional[str]` - Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`. limit `Optional[int]` - The maximum number of items to return per page. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `MetadataTemplates`. Returns all of the metadata templates within an enterprise and their corresponding schema. ## Create metadata template Creates a new metadata template that can be applied to files and folders. This operation is performed by calling function `create_metadata_template`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-metadata-templates-schema/). ``` client.metadata_templates.create_metadata_template( "enterprise", template_key, template_key=template_key, fields=[ CreateMetadataTemplateFields( type=CreateMetadataTemplateFieldsTypeField.STRING, key="testName", display_name="testName", ), CreateMetadataTemplateFields( type=CreateMetadataTemplateFieldsTypeField.FLOAT, key="age", display_name="age", ), CreateMetadataTemplateFields( type=CreateMetadataTemplateFieldsTypeField.DATE, key="birthDate", display_name="birthDate", ), CreateMetadataTemplateFields( type=CreateMetadataTemplateFieldsTypeField.ENUM, key="countryCode", display_name="countryCode", options=[ CreateMetadataTemplateFieldsOptionsField(key="US"), CreateMetadataTemplateFieldsOptionsField(key="CA"), ], ), CreateMetadataTemplateFields( type=CreateMetadataTemplateFieldsTypeField.MULTISELECT, key="sports", display_name="sports", options=[ CreateMetadataTemplateFieldsOptionsField(key="basketball"), CreateMetadataTemplateFieldsOptionsField(key="football"), CreateMetadataTemplateFieldsOptionsField(key="tennis"), ], ), ], ) ``` ### Arguments scope `str` - The scope of the metadata template to create. Applications can only create templates for use within the authenticated user's enterprise. This value needs to be set to `enterprise`, as `global` scopes can not be created by applications. template_key `Optional[str]` - A unique identifier for the template. This identifier needs to be unique across the enterprise for which the metadata template is being created. When not provided, the API will create a unique `templateKey` based on the value of the `displayName`. display_name `str` - The display name of the template. hidden `Optional[bool]` - Defines if this template is visible in the Box web app UI, or if it is purely intended for usage through the API. fields `Optional[List[CreateMetadataTemplateFields]]` - An ordered list of template fields which are part of the template. Each field can be a regular text field, date field, number field, as well as a single or multi-select list. copy_instance_on_item_copy `Optional[bool]` - Whether or not to copy any metadata attached to a file or folder when it is copied. By default, metadata is not copied along with a file or folder when it is copied. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `MetadataTemplate`. The schema representing the metadata template created. --- ### Migration guide for versions 2.x.x -> 3.x.x **Type:** page | **Section:** Additional Resources Migration guide for versions 2.x.x -> 3.x.x Runtime requirements Dependencies jsonwebtoken Removed deprecated methods and classes… # Migration guide for versions 2.x.x -> 3.x.x - [Runtime requirements](#runtime-requirements) [Dependencies](#dependencies) - [`jsonwebtoken`](#jsonwebtoken) [Removed deprecated methods and classes](#removed-deprecated-methods-and-classes) - [Collaboration Whitelist](#collaboration-whitelist) - [Collaboration Allowlist](#collaboration-allowlist) - [Files](#files) This release contains a number of changes. The most notable are: - Drop support for Node versions below 12. - Bump `jsonwebtoken` to version 9.0.0. # Runtime requirements From this version, we will only support Node versions 12 and above. This is due to the fact that `jsonwebtoken` version 9.0.0 dropped support for Node versions below 12. If you are using an older version of Node, you will need to upgrade to a newer version. # Dependencies ## jsonwebtoken We have bumped the version of `jsonwebtoken` to 9.0.0 to fix a security vulnerability. If you are using `jsonwebtoken` directly, you will need to upgrade to version 9.0.0 to avoid conflicts. # Removed deprecated methods and classes ## Box Client The deprecated `BoxClient.batch()` and `BoxClient.batchExec()` methods have been removed, please make calls in parallel instead. Attribute `staleBufferMS` in [`UserConfigurationOptions`](http://opensource.box.com/box-node-sdk/jsdoc/global.html#UserConfigurationOptions) class has been removed, you can use `expiredBufferMS` attribute to set the time before we consider the token expired. ## Collaboration Whitelist The deprecated `CollaborationWhitelist` class has been removed, please use [`CollaborationAllowlist`](http://opensource.box.com/box-node-sdk/jsdoc/CollaborationAllowlist.html) class instead. ## Collaboration Allowlist Method `CollaborationAllowlist.getWhitelistedDomain()` has been removed, now to get the allow listed domain, use [`CollaborationAllowlist.getAllowlistedDomain()`](http://opensource.box.com/box-node-sdk/jsdoc/CollaborationAllowlist.html#getAllowlistedDomain) instead. Method `CollaborationAllowlist.getAllWhitelistedDomains()` has been removed, now to get all allow listed domains, use [`CollaborationAllowlist.getAllAllowlistedDomains()`](http://opensource.box.com/box-node-sdk/jsdoc/CollaborationAllowlist.html#getAllAllowlistedDomains) instead. ## Files Method `Files.getThumbnail( fileID: string, options?: Record<string, any>, callback?: Function )` has been removed, use [`Files.getRepresentationContent( fileID, representationType, options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Files.html#getRepresentationContent) instead. With this method, you can generate a representation of a file. A representation is an alternative asset for a file stored in Box. These assets can be PDFs, thumbnails, or text extractions. Representations are automatically generated for the supported file types, either when uploading to Box or when requesting the asset. **Useful links** - [Get Thumbnail Representation](https://developer.box.com/guides/representations/thumbnail-representation/) - [Supported File Types and Representations](https://developer.box.com/guides/representations/supported-file-types/) **Example** To get the thumbnail for a file has the extension in this list of [supported file types](https://developer.box.com/guides/representations/thumbnail-representation/#supported-file-types), you can use the following code: ``` const thumbnail = await client.files.getRepresentationContent('123', client.files.representations.THUMBNAIL); thumbnail.pipe(fs.createWriteStream('thumbnail.jpg')); ``` For others file types, you can get the list of representations available for a file using the [`Files.getRepresentationInfo()`](http://opensource.box.com/box-node-sdk/jsdoc/Files.html#getRepresentationInfo) method, then use the [`Files.getRepresentationContent()`](http://opensource.box.com/box-node-sdk/jsdoc/Files.html#getRepresentationContent) method to get the content of the representation. ``` const representations = await client.files.getRepresentationInfo(fileId); const representation = representations.entries.find((entry) => entry.representation === 'png'); if (!representation) { console.log('No png representation'); return; } const png = await client.files.getRepresentationContent(fileId, `[${representation.representation}?dimensions=${representation.properties.dimensions}]`); png.pipe(fs.createWriteStream('file.png')); ``` --- ### Migration guide for versions 3.x.x -> 4.x.x **Type:** page | **Section:** Additional Resources Migration guide for versions 3.x.x -> 4.x.x Configuration changes BoxDeveloperEditionAPIConnection MaxRequestAttempts Removed deprecated… # Migration guide for versions 3.x.x -> 4.x.x [Configuration changes](#configuration-changes) - [BoxDeveloperEditionAPIConnection](#boxdevelopereditionapiconnection) - [MaxRequestAttempts](#maxrequestattempts) [Removed deprecated methods and classes](#removed-deprecated-methods-and-classes) [Replaced methods and classes](#replaced-methods-and-classes) - [Shared links](#shared-links) - [Retention Policies](#retention-policies) - [Enterprise Events](#enterprise-events) - [Search](#search) - [BoxGroup](#boxgroup) - [MetadataTemplate](#metadatatemplate) - [Others](#others) The most important change this release includes is the replacement of the HTTP library from a native one to OkHttp which allows SDK to: - Support the HTTP2 version of the HTTP protocol. - Support proxies that do not use only basic authentication method. For details on creating custom proxy authenticators and an example of NTLM proxy authentication, see [here](https://github.com/box/box-java-sdk/blob/kb/ok-http/doc/configuration.md#custom-proxy-authenticator). # Configuration changes ## BoxDeveloperEditionAPIConnection Replaced `com.box.sdk.BoxDeveloperEditionAPIConnection#getAppUserConnection`with `com.box.sdk.BoxDeveloperEditionAPIConnection#getUserConnection`. ### Example To create `com.box.sdk.BoxDeveloperEditionAPIConnection` configured for user access: ``` Reader reader = new FileReader("some-config.json"); BoxConfig boxConfig = BoxConfig.readFrom(reader); BoxDeveloperEditionAPIConnection api = BoxDeveloperEditionAPIConnection.getUserConnection(boxConfig); ``` ### Documentation You can read more on BoxDeveloperEditionAPIConnection [here](../../README.md#boxdevelopereditionapiconnectionasenterpriseuser). ## MaxRequestAttempts The `MaxRequestAttempts` are removed from `com.box.sdk.BoxGlobalSettings` and replaced with `MaxRetryAttempts`. However, if you have API connection stored with the deprecated `MaxRequestAttempts` value it will be restored into `MaxRetryAttempts`. # Removed deprecated methods and classes 1. `com.box.sdk.BoxAPIRequest.BoxAPIRequest(java.net.URL, java.lang.String)` - use constuctor that accepts `com.box.sdk.BoxAPIConnection`. 2. `com.box.sdk.BoxUser.moveFolderToUser` - this method is removed as this operation is not allowed by API. You can only transfer root folder to another user using `com.box.sdk.BoxUser.transferContent`. # Replaced methods and classes ## Getting thumbnail Method `com.box.sdk.BoxFile.getThumbnail` was removed. To get any file representation use `com.box.sdk.BoxFile.getRepresentationContent(java.lang.String, java.io.OutputStream)` or `com.box.sdk.BoxFile.getRepresentationContent(java.lang.String, java.lang.String, java.io.OutputStream)`. ### Example To read the PDF representation of file with id `12345`: ``` ByteArrayOutputStream output = new ByteArrayOutputStream(); BoxFile file = new BoxFile(api, "12345"); file.getRepresentationContent("[pdf]", output); ``` ### Documentation For more details on getting representation content go [here](../files.md#get-representation-content). ## Shared links Removed variant of methods that do not use `com.box.sdk.sharedlink.BoxSharedLinkRequest`: 1. `com.box.sdk.BoxItem.createSharedLink` 2. `com.box.sdk.BoxFile.createSharedLink` 3. `com.box.sdk.BoxFolder.createSharedLink` 4. `com.box.sdk.BoxWebLink.createSharedLink` ### Example If you want to create a shared link, first create `com.box.sdk.sharedlink.BoxSharedLinkRequest`: ``` Date unsharedDate = ... BoxFile file = new BoxFile(api, "id"); BoxSharedLinkRequest sharedLinkRequest = new BoxSharedLinkRequest() .access(OPEN) .permissions(true, true) .unsharedDate(unsharedDate); BoxSharedLink sharedLink = file.createSharedLink(sharedLinkRequest); ``` ### Documentation For details on shared links, see: 1. [Create shared link for file](../files.md#create-a-shared-link) 2. [Create shared link for folder](../folders.md#create-a-shared-link) 3. [Create shared link for web link](../weblinks.md#create-shared-link) ## Retention Policies Removed variant of methods that were not using `com.box.sdk.BoxRetentionPolicy.BoxRetentionPolicyAction`: 1. `com.box.sdk.BoxRetentionPolicy.createFinitePolicy` ### Example If you want to create a finite retention policy: ``` BoxRetentionPolicy.createFinitePolicy(api, "My 30 days retention policy", 30, BoxRetentionPolicyAction.PermanentlyDelete); ``` ### Documentation You can read more on creating retention policies [here](../retention_policies.md#create-retention-policy). ## Enterprise Events Removed variant of methods that were not using `com.box.sdk.EnterpriseEventsRequest`: 1. `com.box.sdk.EventLog.getEnterpriseEvents` ### Example If you want to get historical enterprise events, first create `com.box.sdk.EnterpriseEventsRequest`: ``` EnterpriseEventsRequest request = new EnterpriseEventsRequest().limit(20); EventLog.getEnterpriseEvents(api, request1); // process recieved events ``` ### Documentation You can read more on getting enterprise events [here](../events.md#enterprise--admin--events). ## Search Method `com.box.sdk.BoxFolder.search` is replaced with class `com.box.sdk.BoxSearch`. ### Example If you would like to find the first 10 files matching "taxes": ``` long offsetValue = 0; long limitValue = 10; BoxSearchParameters searchParams = new BoxSearchParameters(); searchParams.setQuery("taxes"); searchParams.setType("file"); BoxSearch boxSearch = new BoxSearch(api); boxSearch.searchRange(offsetValue, limitValue, searchParams); ``` ### Documentation You can read more on search [here](https://ja.developer.box.com/4676a077454d7307989f4ff8b48c06db/search.md). ## BoxGroup All methods that use `com.box.sdk.BoxGroupMembership.Role` were removed. Use ones that use `com.box.sdk.BoxGroupMembership.GroupRole`. Also `com.box.sdk.BoxGroupMembership.Role` was replaced with `com.box.sdk.BoxGroupMembership.GroupRole`. ### Example To add a new member to a group with specific role: ``` BoxUser user = ... BoxGroup boxGroup = new BoxGroup(api, "group_id"); boxGroup.addMembership(user, BoxGroupMembership.GroupRole.ADMIN); ``` To get membership role use `com.box.sdk.BoxGroupMembership.Info.getGroupRole`: ``` BoxGroupMembership membership = new BoxGroupMembership(api, "membership_id"); membership.getInfo().getGroupRole(); ``` To change membership role use `com.box.sdk.BoxGroupMembership.Info.setGroupRole`: ``` BoxGroupMembership membership = new BoxGroupMembership(api, "membership_id"); BoxGroupMembership.Info membershipInfo = membership.getInfo(); membershipInfo.setGroupRole(BoxGroupMembership.GroupRole.MEMBER); membership.updateInfo(membershipInfo); ``` ### Documentation You can read more on groups [here](https://ja.developer.box.com/a0c1617a72414a043041fde8403ca480/groups.md). ## MetadataTemplate In `com.box.sdk.MetadataTemplate` methods that do not use `com.box.sdk.MetadataQuery` were removed. ### Example To execute a metadata query first create `com.box.sdk.MetadataQuery` instance. ``` MetadataQuery mQuery = new MetadataQuery("enterprise_341532.test"); mQuery.setQuery("testfield = :arg"); mQuery.setAncestorFolderId("0"); mQuery.setOrderBy( MetadataQuery.OrderBy.ascending("primarySortKey"), MetadataQuery.OrderBy.ascending("secondarySortKey") ); mQuery.addParameter("arg", "test"); mQuery.setFields("metadata.enterprise_341532.test.customField"); MetadataTemplate.executeMetadataQuery(api, mQuery); ``` ### Documentation You can read more on how to execute metadata query [here](../metadata_template.md#execute-metadata-query). ## Others | Old | New | | --- | --- | | com.box.sdk.BoxEvent.getType | com.box.sdk.BoxEvent.getEventType | | com.box.sdk.BoxEvent.Type | com.box.sdk.BoxEvent.EventType | | com.box.sdk.BoxFile.uploadVersion | com.box.sdk.BoxFile.uploadNewVersion | | com.box.sdk.BoxGlobalSettings.getMaxRequestAttempts | com.box.sdk.BoxGlobalSettings.getMaxRetryAttempts | | com.box.sdk.BoxGlobalSettings.setMaxRequestAttempts | com.box.sdk.BoxGlobalSettings.setMaxRetryAttempts | | com.box.sdk.BoxTask.Info.getAction | com.box.sdk.BoxTask.Info.getTaskType | --- ### Migration guide from `boxsdk` to `box-sdk-gen` **Type:** page | **Section:** Additional Resources Migration guide from boxsdk to box-sdk-gen Introduction Installation Key differences Manager approach Explicitly defined schemas Immutable… # Migration guide from boxsdk to box-sdk-gen - [Introduction](#introduction) - [Installation](#installation) [Key differences](#key-differences) - [Manager approach](#manager-approach) - [Explicitly defined schemas](#explicitly-defined-schemas) - [Immutable design](#immutable-design) [Authentication](#authentication) - [Developer Token](#developer-token) [JWT Auth](#jwt-auth) - [Using JWT configuration file](#using-jwt-configuration-file) - [Providing JWT configuration manually](#providing-jwt-configuration-manually) - [Authenticate user](#authenticate-user) [Client Credentials Grant](#client-credentials-grant) - [Obtaining Service Account token](#obtaining-service-account-token) - [Obtaining User token](#obtaining-user-token) [Switching between Service Account and User](#switching-between-service-account-and-user) [OAuth 2.0 Auth](#oauth-20-auth) - [Get Authorization URL](#get-authorization-url) - [Authenticate](#authenticate) [Store token and retrieve token callbacks](#store-token-and-retrieve-token-callbacks) [Downscope token](#downscope-token) [Revoke token](#revoke-token) [Configuration](#configuration) - [As-User header](#as-user-header) - [Custom Base URLs](#custom-base-urls) [Convenience methods](#convenience-methods) - [Webhook validation](#webhook-validation) - [Chunked upload of big files](#chunked-upload-of-big-files) ## Introduction The new `box-sdk-gen` SDK library helps Python developers to conveniently integrate with Box API. In the contrary to the previous library (`boxsdk`), it is not manually maintained, but auto-generated based on Open API Specification. This means you can leverage the most up-to-date Box API features in your applications without delay. More information and benefits of using the new can be found in the [README](https://github.com/box/box-python-sdk-gen/blob/main/README.md) file. ## Installation To install a new Box Python SDK GENERATED use command: ``` pip install box-sdk-gen ``` The new Box Python SDK GENERATED library could be used in the same project along with the legacy one. If you want to use a feature available only in the new SDK, you don't need to necessarily migrate all your code to use Box Python SDK GENERATED at once. You can use a new feature from the new library, while keeping the rest of your code unchanged. Note that it may be required to alias some imported names from the new SDK to avoid conflicts with the old one. However, we recommend to fully migrate to the new SDK eventually. ## Key differences ### Manager approach The main difference between the old SDK and the new one is the way how API methods are aggregated into objects. **Old (`boxsdk`)** Firstly, in the old SDK to be able to perform any action on an API object, e.g. `User`, you first had to create its class. To do it is required to call: ``` user = client.user(user_id='123456') ``` to create a class representing an already existing User with id '12345', or create a new one with a call: ``` user = client.create_user(name='Some User') ``` Then, you could perform any action on created class, which will affect the user, e.g. ``` updated_user = user.update_info(data={'name': 'New User Name'}) ``` **New (`box-sdk-gen`)** In the new SDK the API methods are grouped into dedicated manager classes, e.g. `User` object has dedicated `UserManager` class. Each manager class instance is available in `BoxClient` object. The fields storing references to the managers are named in the plural form of the resource that the manager handles - `client.users` for `UsersManager`. If you want to perform any operation connected with a `User` you need to call a respective method of `UserManager`. For example, to get info about existing user you need to call: ``` user = client.users.get_user_by_id(user_id='123456') ``` or to create a new user: ``` user = client.users.create_user(name='Some User') ``` The `User` object returned by both of these methods is a data class - it does not contain any methods to call. To perform any action on `User` object, you need to still use a `UserManager` method for that. Usually these methods have a first argument, which accepts id of the object you want to access, e.g. to update a user name, call method: ``` updated_user = client.users.update_user_by_id(user_id=user.id, name='New User Name') ``` ### Explicitly defined schemas **Old (`boxsdk`)** In the old SDK there were no data types explicitly defined - the responses were dynamically mapped into classes in the runtime. For example, if you get information about a file: ``` file = client.file(file_id='12345678').get() ``` you couldn't be sure which fields to expect in the response object until the runtime, because `File` class doesn't have any predefined fields. **New (`box-sdk-gen`)** In the new SDK the data classe are defined in `schemas` module, so you know, which fields to expect before actually making a call. For example `FileBase` class is defined this way: ``` class FileBase(BaseObject): def __init__(self, id: str, *, etag: Optional[str] = None, type: FileBaseTypeField = FileBaseTypeField.FILE.value, **kwargs): super().__init__(**kwargs) self.id = id self.type = type self.etag = etag ``` ### Immutable design The new SDK is designed to be mostly immutable. This means that methods, which used to modify the existing object in old SDK now return a new instance of the class with the modified state. This design pattern is used to avoid side effects and make the code more predictable and easier to reason about. Methods, which returns a new modified instance of an object, will always have a prefix `with_` in their names, e.g. **New (`box-sdk-gen`)** ``` from box_sdk_gen import BoxClient as_user_client: BoxClient = client.with_as_user_header('USER_ID') ``` ## Authentication The Box Python SDK GENERATED library offers the same authentication methods as the legacy one. Let's see the differences of their usage: ### Developer Token **Old (`boxsdk`)** ``` from boxsdk import Client, OAuth2 auth = OAuth2( client_id='YOUR_CLIENT_ID', client_secret='YOUR_CLIENT_SECRET', access_token='DEVELOPER_TOKEN_GOES_HERE', ) client = Client(auth) ``` The new SDK provides a convenient `BoxDeveloperTokenAuth`, which allows authenticating using developer token without necessity to provide a Client ID and Client Secret **New (`box-sdk-gen`)** ``` from box_sdk_gen import BoxClient, BoxDeveloperTokenAuth auth = BoxDeveloperTokenAuth(token='DEVELOPER_TOKEN_GOES_HERE') client = BoxClient(auth=auth) ``` ### JWT Auth #### Using JWT configuration file **Old (`boxsdk`)** The static method, which reads the JWT configuration file has been changed: ``` from boxsdk import JWTAuth, Client auth = JWTAuth.from_settings_file('/path/to/config.json') client = Client(auth) ``` **New (`box-sdk-gen`)** ``` from box_sdk_gen import BoxClient, BoxJWTAuth, JWTConfig jwt_config = JWTConfig.from_config_file(config_file_path='/path/to/config.json') auth = BoxJWTAuth(config=jwt_config) client = BoxClient(auth=auth) ``` #### Providing JWT configuration manually Some params in `JWTConfig` constructor have slightly different names than one in old `JWTAuth` class. **Old (`boxsdk`)** ``` from boxsdk import JWTAuth auth = JWTAuth( client_id='YOUR_CLIENT_ID', client_secret='YOUR_CLIENT_SECRET', enterprise_id='YOUR_ENTERPRISE_ID', user_id='USER_ID', jwt_key_id='YOUR_JWT_KEY_ID', rsa_private_key_file_sys_path='CERT.PEM', rsa_private_key_passphrase='PASSPHRASE', jwt_algorithm='RS256', ) ``` **New (`box-sdk-gen`)** ``` from box_sdk_gen import BoxJWTAuth, JWTConfig, JwtAlgorithm jwt_config = JWTConfig( client_id='YOUR_CLIENT_ID', client_secret='YOUR_CLIENT_SECRET', enterprise_id='YOUR_ENTERPRISE_ID', user_id='USER_ID', jwt_key_id='YOUR_JWT_KEY_ID', private_key='YOUR_PRIVATE_KEY', private_key_passphrase='PASSPHRASE', algorithm=JwtAlgorithm.RS256, ) auth = BoxJWTAuth(config=jwt_config) ``` #### Authenticate user In old SDK method for user authentication was named `authenticate_user(self, user: Union[str, 'User'] = None) -> str` and was accepting either user object or user id. If none provided, user ID stored in `JWTAuth` class instance was used. The `authenticate_user` method was modifying existing `BoxJWTAuth` class, which was exchanging the existing token with the one with the user access. **Old (`boxsdk`)** ``` auth.authenticate_user(user) ``` or ``` auth.authenticate_user('USER_ID') ``` **New (`box-sdk-gen`)** In new SDK, to authenticate as user you need to call `with_user_subject(self, user_id: str, *, token_storage: TokenStorage = None) -> BoxJWTAuth` method with id of the user to authenticate. The method returns a new instance of `BoxJWTAuth` class, which will perform authentication call in scope of the user on the first API call. The `token_storage` parameter is optional and allows to provide a custom token storage for the new instance of `BoxJWTAuth` class. The new auth instance can be used to create a new user client instance. ``` from box_sdk_gen import BoxJWTAuth, BoxClient user_auth: BoxJWTAuth = auth.with_user_subject('USER_ID') user_client: BoxClient = BoxClient(auth=user_auth) ``` ### Client Credentials Grant #### Obtaining Service Account token To authenticate as enterprise, the only difference between the old and the new SDK, is using the `CCGConfig` as a middle step. **Old (`boxsdk`)** ``` from boxsdk import CCGAuth, Client auth = CCGAuth( client_id="YOUR_CLIENT_ID", client_secret="YOUR_CLIENT_SECRET", enterprise_id="YOUR_ENTERPRISE_ID", ) client = Client(auth) ``` **New (`box-sdk-gen`)** ``` from box_sdk_gen import BoxClient, BoxCCGAuth, CCGConfig ccg_config = CCGConfig( client_id="YOUR_CLIENT_ID", client_secret="YOUR_CLIENT_SECRET", enterprise_id="YOUR_ENTERPRISE_ID", ) auth = BoxCCGAuth(config=ccg_config) client = BoxClient(auth=auth) ``` #### Obtaining User token In old SDK `CCGAuth` was accepting both user object and User ID. In the box-sdk-gen the `BoxCCGAuth` constructor accepts only User ID instead. **Old (`boxsdk`)** ``` from boxsdk import CCGAuth auth = CCGAuth( client_id="YOUR_CLIENT_ID", client_secret="YOUR_CLIENT_SECRET", user="YOUR_USER_ID" ) ``` **New (`box-sdk-gen`)** ``` from box_sdk_gen import BoxCCGAuth, CCGConfig ccg_config = CCGConfig( client_id="YOUR_CLIENT_ID", client_secret="YOUR_CLIENT_SECRET", user_id="YOUR_USER_ID" ) auth = BoxCCGAuth(config=ccg_config) ``` ### Switching between Service Account and User In old SDK there were two methods which allowed to switch between using service and user account. Calling these methods were modifying existing state of `CCGAuth` class, which was fetching a new token on the next API call. **Old (`boxsdk`)** ``` auth.authenticate_enterprise('ENTERPRISE_ID') ``` ``` auth.authenticate_user('USER_ID') ``` In the new SDK, to keep the immutability design, the methods switching authenticated subject were replaced with methods returning a new instance of `BoxCCGAuth` class. The new instance will fetch a new token on the next API call. The new auth instance can be used to create a new client instance. You can also specify `token_storage` parameter to provide a custom token storage for the new instance. The old instance of `BoxCCGAuth` class will remain unchanged and will still use the old token. **New (`box-sdk-gen`)** ``` from box_sdk_gen import BoxCCGAuth, BoxClient enterprise_auth: BoxCCGAuth = auth.with_enterprise_subject(enterprise_id='ENTERPRISE_ID') enterprise_client: BoxClient = BoxClient(auth=enterprise_auth) ``` ``` from box_sdk_gen import BoxCCGAuth, BoxClient user_auth: BoxCCGAuth = auth.with_user_subject(user_id='USER_ID') user_client: BoxClient = BoxClient(auth=user_auth) ``` Note that the new methods accept only user id or enterprise id, while the old ones were accepting user and enterprise object too. ### OAuth 2.0 Auth #### Get Authorization URL To get authorization url in the new SDK, you need to first create the `BoxOAuth` class (previously `OAuth2`) using `OAuthConfig` class. Then to get authorization url, call `get_authorize_url(self, *, options: GetAuthorizeUrlOptions = None) -> str` instead of `get_authorization_url(self, redirect_url: Optional[str]) -> Tuple[str, str]`. Note that this method now accepts the instance of `GetAuthorizeUrlOptions` class, which allows specifying extra options to API call. The new function returns only the authentication url string, while the old one returns tuple of authentication url and csrf_token. **Old (`boxsdk`)** ``` from boxsdk import OAuth2 auth = OAuth2( client_id='YOUR_CLIENT_ID', client_secret='YOUR_CLIENT_SECRET', ) auth_url, csrf_token = auth.get_authorization_url('http://YOUR_REDIRECT_URL') ``` **New (`box-sdk-gen`)** ``` from box_sdk_gen import BoxOAuth, OAuthConfig, GetAuthorizeUrlOptions auth = BoxOAuth( OAuthConfig( client_id='YOUR_CLIENT_ID', client_secret='YOUR_CLIENT_SECRET', ) ) auth_url = auth.get_authorize_url(options=GetAuthorizeUrlOptions(redirect_uri='http://YOUR_REDIRECT_URL')) ``` #### Authenticate The signature of method for authenticating with obtained auth code got changed from: `authenticate(self, auth_code: Optional[str]) -> Tuple[str, str]` to `get_tokens_authorization_code_grant(self, authorization_code: str, *, network_session: Optional[NetworkSession] = None) -> AccessToken`. The method now returns an AccessToken object with `access_token` and `refresh_token` fields, while the old one was returning a tuple of access token and refresh token. **Old (`boxsdk`)** ``` from boxsdk import Client access_token, refresh_token = auth.authenticate('YOUR_AUTH_CODE') client = Client(auth) ``` **New (`box-sdk-gen`)** ``` from box_sdk_gen import BoxClient, AccessToken access_token: AccessToken = auth.get_tokens_authorization_code_grant('YOUR_AUTH_CODE') client = BoxClient(auth) ``` ### Store token and retrieve token callbacks In old SDK you could provide a `store_tokens` callback method to an authentication class, which was called each time an access token was refreshed. It could be used to save your access token to a custom token storage and allow to reuse this token later. What is more, old SDK allowed also to provide `retrieve_tokens` callback, which is called each time the SDK needs to use token to perform an API call. To provide that, it was required to use `CooperativelyManagedOAuth2` and provide `retrieve_tokens` callback method to its constructor. **Old (`boxsdk`)** ``` from typing import Tuple from boxsdk.auth import CooperativelyManagedOAuth2 from boxsdk import Client def retrieve_tokens() -> Tuple[str, str]: # retrieve access_token and refresh_token return access_token, refresh_token def store_tokens(access_token: str, refresh_token: str): # store access_token and refresh_token pass auth = CooperativelyManagedOAuth2( client_id='YOUR_CLIENT_ID', client_secret='YOUR_CLIENT_SECRET', retrieve_tokens=retrieve_tokens, store_tokens=store_tokens ) access_token, refresh_token = auth.authenticate('YOUR_AUTH_CODE') client = Client(auth) ``` In the new SDK you can define your own class delegated for storing and retrieving a token. It has to inherit from `TokenStorage` and implement all of its abstract methods. Next step would be to pass an instance of this class to the AuthConfig constructor. **New (`box-sdk-gen`)** ``` from typing import Optional from box_sdk_gen import BoxOAuth, OAuthConfig, TokenStorage, AccessToken class MyCustomTokenStorage(TokenStorage): def store(self, token: AccessToken) -> None: # store token pass def get(self) -> Optional[AccessToken]: # get token pass def clear(self) -> None: # clear token pass auth = BoxOAuth( OAuthConfig( client_id='YOUR_CLIENT_ID', client_secret='YOUR_CLIENT_SECRET', token_storage=MyCustomTokenStorage() ) ) ``` or reuse one of the provided implementations: `FileTokenStorage` or `FileWithInMemoryCacheTokenStorage`: ``` from box_sdk_gen import BoxOAuth, OAuthConfig, FileWithInMemoryCacheTokenStorage auth = BoxOAuth( OAuthConfig( client_id='YOUR_CLIENT_ID', client_secret='YOUR_CLIENT_SECRET', token_storage=FileWithInMemoryCacheTokenStorage() ) ) ``` ### Downscope token The process of downscoping token in the new SDK is similar to the old one. The main difference is that the new method accepts the full resource path instead of file object. **Old (`boxsdk`)** ``` from boxsdk import Client, OAuth2 target_file = client.file(file_id='FILE_ID_HERE') token_info = client.downscope_token(['item_preview'], target_file) downscoped_auth = OAuth2( client_id=None, client_secret=None, access_token=token_info.access_token ) downscoped_client = Client(downscoped_auth) ``` **New (`box-sdk-gen`)** ``` from box_sdk_gen import BoxDeveloperTokenAuth, AccessToken, BoxClient resource = 'https://api.box.com/2.0/files/123456789' downscoped_token: AccessToken = auth.downscope_token( scopes=['item_preview'], resource=resource, ) downscoped_auth = BoxDeveloperTokenAuth(token=downscoped_token.access_token) client = BoxClient(auth=downscoped_auth) ``` ### Revoke token To revoke current client's tokens in the new SDK, you need to call `revoke_token` method of the auth class instead of `revoke` method. **Old (`boxsdk`)** ``` oauth.revoke() ``` **New (`box-sdk-gen`)** ``` client.auth.revoke_token() ``` ## Configuration ### As-User header The As-User header is used by enterprise admins to make API calls on behalf of their enterprise's users. This requires the API request to pass an `As-User: USER-ID` header. The following examples assume that the client has been instantiated with an access token with appropriate privileges to make As-User calls. In old SDK you could call client `as_user(self, user: User)` method to create a new client to impersonate the provided user. **Old (`boxsdk`)** ``` from boxsdk import Client user_to_impersonate = client.user(user_id='USER_ID') user_client: Client = client.as_user(user_to_impersonate) ``` **New (`box-sdk-gen`)** In the new SDK the method was renamed to `with_as_user_header(self, user_id: str) -> BoxClient` and returns a new instance of `BoxClient` class with the As-User header appended to all API calls made by the client. The method accepts only user id as a parameter. ``` from box_sdk_gen import BoxClient user_client: BoxClient = client.with_as_user_header(user_id='USER_ID') ``` Additionally `BoxClient` offers a `with_extra_headers(self, *, extra_headers: Dict[str, str] = None) -> BoxClient` method, which allows you to specify the custom set of headers, which will be included in every API call made by client. Calling the `client.with_extra_headers()` method creates a new client, leaving the original client unmodified. ``` from box_sdk_gen import BoxClient new_client: BoxClient = client.with_extra_headers(extra_headers={'customHeader': 'customValue'}) ``` ### Custom Base URLs **Old (`boxsdk`)** In old SDK you could specify the custom base URLs, which will be used for API calls made by setting the new values of static variables of the `API` class. ``` from boxsdk.config import API API.BASE_API_URL = 'https://new-base-url.com' API.OAUTH2_API_URL = 'https://my-company.com/oauth2' API.UPLOAD_URL = 'https://my-company-upload-url.com' ``` **New (`box-sdk-gen`)** In the new SDK this functionality has been implemented as part of the `BoxClient` class. By calling the `client.with_custom_base_urls()` method, you can specify the custom base URLs that will be used for API calls made by client. Following the immutability pattern, this call creates a new client, leaving the original client unmodified. ``` from box_sdk_gen import BoxClient, BaseUrls new_client: BoxClient = client.with_custom_base_urls(base_urls=BaseUrls( base_url='https://new-base-url.com', upload_url='https://my-company-upload-url.com', oauth_2_url='https://my-company.com/oauth2', )) ``` ## Convenience methods ### Webhook validation Webhook validation is used to validate a webhook message by verifying the signature and the delivery timestamp. **Old (`boxsdk`)** In the old SDK, you could pass the `body` as `bytes`, and it would return a `boolean` value indicating whether the message was valid. ``` body = b'{"webhook":{"id":"1234567890"},"trigger":"FILE.UPLOADED","source":{"id":"1234567890","type":"file","name":"Test.txt"}}' headers = { 'box-delivery-id': 'f96bb54b-ee16-4fc5-aa65-8c2d9e5b546f', 'box-delivery-timestamp': '2020-01-01T00:00:00-07:00', 'box-signature-algorithm': 'HmacSHA256', 'box-signature-primary': '4KvFa5/unRL8aaqOlnbInTwkOmieZkn1ZVzsAJuRipE=', 'box-signature-secondary': 'yxxwBNk7tFyQSy95/VNKAf1o+j8WMPJuo/KcFc7OS0Q=', 'box-signature-version': '1', } is_validated = Webhook.validate_message(body, headers, primary_key, secondary_key) print(f'The webhook message is validated to: {is_validated}') ``` **New (`box-sdk-gen`)** In the new SDK, the `WebhooksManager.validate_message()` method requires the `body` to be of type `string` and the rest of the code remains the same ``` from box_sdk_gen import WebhooksManager body = '{"webhook":{"id":"1234567890"},"trigger":"FILE.UPLOADED","source":{"id":"1234567890","type":"file","name":"Test.txt"}}' headers = { 'box-delivery-id': 'f96bb54b-ee16-4fc5-aa65-8c2d9e5b546f', 'box-delivery-timestamp': '2020-01-01T00:00:00-07:00', 'box-signature-algorithm': 'HmacSHA256', 'box-signature-primary': '4KvFa5/unRL8aaqOlnbInTwkOmieZkn1ZVzsAJuRipE=', 'box-signature-secondary': 'yxxwBNk7tFyQSy95/VNKAf1o+j8WMPJuo/KcFc7OS0Q=', 'box-signature-version': '1', } WebhooksManager.validate_message( body=body, headers=headers, primary_key=primary_key, secondary_key=secondary_key ) ``` ### Chunked upload of big files For large files or in cases where the network connection is less reliable, you may want to upload the file in parts. This allows a single part to fail without aborting the entire upload, and failed parts are being retried automatically. **Old (`boxsdk`)** In the old SDK, you could use the `get_chunked_uploader()` method to create a chunked uploader object. Then, you would call the `start()` method to begin the upload process. The `get_chunked_uploader()` method requires the `file_path` and `file_name` parameters. ``` chunked_uploader = client.folder('0').get_chunked_uploader(file_path='/path/to/file.txt', file_name='new_name.txt') uploaded_file = chunked_uploader.start() print(f'File "{uploaded_file.name}" uploaded to Box with file ID {uploaded_file.id}') ``` **New (`box-sdk-gen`)** In the new SDK, the equivalent method is `chunked_uploads.upload_big_file()`. It accepts a file-like object as the `file` parameter, and the `file_name` and `file_size` parameters are now passed as arguments. The `parent_folder_id` parameter is also required to specify the folder where the file will be uploaded. ``` import os with open('/path/to/file.txt', 'rb') as file_byte_stream: file_name = 'new_name.txt' file_size = os.path.getsize('/path/to/file.txt') parent_folder_id = '0' # ID of the folder where the file will be uploaded uploaded_file = client.chunked_uploads.upload_big_file( file=file_byte_stream, file_name=file_name, file_size=file_size, parent_folder_id=parent_folder_id ) ``` --- ### Migration Guide: From `Box Node SDK` to `Box TypeScript SDK` **Type:** page | **Section:** Additional Resources Migration Guide: From Box Node SDK to Box TypeScript SDK Migration Guide: From Box Node SDK to Box TypeScript SDK Introduction Installation… # Migration Guide: From Box Node SDK to Box TypeScript SDK [Migration Guide: From `Box Node SDK` to `Box TypeScript SDK`](#migration-guide-from-box-node-sdk-to-box-typescript-sdk) - [Introduction](#introduction) - [Installation](#installation) [Highlighting the Key Differences](#highlighting-the-key-differences) - [Native support for async-await and Promises](#native-support-for-async-await-and-promises) - [Embracing Explicitly Defined Schemas](#embracing-explicitly-defined-schemas) - [Immutable design](#immutable-design) [Diving into Authentication](#diving-into-authentication) - [Developer Token](#developer-token) [JWT Authentication](#jwt-authentication) - [Leveraging the JWT Configuration File](#leveraging-the-jwt-configuration-file) - [Manually Providing JWT Configuration](#manually-providing-jwt-configuration) - [User Authentication Simplified](#user-authentication-simplified) [Client Credentials Grant](#client-credentials-grant) - [Service Account Token Acquisition](#service-account-token-acquisition) - [User Token Acquisition](#user-token-acquisition) [Smooth Switching between Service Account and User](#smooth-switching-between-service-account-and-user) [OAuth 2.0 Authentication](#oauth-20-authentication) - [Fetching the Authorization URL](#fetching-the-authorization-url) - [Seamless Authentication](#seamless-authentication) [Customizable Token Storage and Retrieval Callbacks](#customizable-token-storage-and-retrieval-callbacks) [Downscope token](#downscope-token) [Revoke token](#revoke-token) [Configuration](#configuration) - [As-User header](#as-user-header) - [Custom Base URLs](#custom-base-urls) [Convenience methods](#convenience-methods) - [Webhook validation](#webhook-validation) - [Chunked upload of big files](#chunked-upload-of-big-files) ## Introduction Welcome to the `Box TypeScript SDK`, the pinnacle of Box's SDK evolution tailored for developers eager to integrate with the Box API using TypeScript. This next-generation toolkit is meticulously crafted with contemporary development practices, ensuring an unparalleled, seamless experience. While the `Box Node SDK` served its purpose well, the `Box TypeScript SDK` elevates the experience to new heights. One of its standout features is its auto-generation directly from the Open API Specification. This guarantees that developers are always equipped with the latest Box API features, eliminating any lag or discrepancies. This guide is your compass, offering insights and directions for a smooth migration from the legacy `Box Node SDK` to the state-of-the-art `Box TypeScript SDK`. As we journey through, we'll spotlight the key differences, enhanced functionalities, and the myriad benefits that await. For those who wish to delve deeper into the intricacies and advantages of the new SDK, the [official README](https://github.com/box/box-typescript-sdk-gen/blob/main/README.md) is a treasure trove of information. ## Installation Embarking on your journey with the `Box TypeScript SDK` is straightforward. Here's how you can set it up: ``` npm install box-typescript-sdk-gen ``` For those who are hesitant to make the full leap, fear not. The `Box TypeScript SDK` can coexist peacefully alongside the legacy `Box Node SDK` within the same project. This coexistence offers a gentle migration path, allowing developers to transition at their own pace. However, for an optimal experience, a complete transition to the new SDK is recommended in due course. ## Highlighting the Key Differences ### Native support for async-await and Promises The new SDK introduces a more organized and intuitive method of interacting with the Box API. Let's explore the changes: **Legacy (`Box Node SDK`):** In the older SDK, API interactions allowed for passing `callback` as the last argument ``` function callback(user) { console.log('hello', user); } client.users.get('123456', {} /* options */, callback); ``` If you didn't provide the `callback` a Promise would be returned. **Modern (`Box TypeScript SDK`):** The new SDK ensures promises are used consistently across the full SDK. ``` const user = await client.users.getUserById('123456'); ``` ### Embracing Explicitly Defined Schemas The new SDK brings clarity to data interactions by providing explicit data type definitions: **Legacy (`Box Node SDK`):** The older SDK was more ambiguous, which could lead to potential issues: ``` const file = await client.files.get('12345678'); /* file has generic Object type */ ``` **Modern (`Box TypeScript SDK`):** With the new SDK, developers can be confident in the data structures they're working with: ``` interface FileBase { id: string; type: FileBaseTypeField; etag?: string; } ``` ### Immutable design The new SDK is designed to be mostly immutable. This means that methods, which used to modify the existing object in old SDK now return a new instance of the class with the modified state. This design pattern is used to avoid side effects and make the code more predictable and easier to reason about. Methods, which returns a new modified instance of an object, will always have a prefix `with` in their names, e.g. **New (`box-sdk-gen`)** ``` asUserClient: BoxClient = client.withAsUserHeader('USER_ID'); ``` ## Diving into Authentication Authentication is a crucial aspect of any SDK. Let's delve into the authentication methods supported by both SDKs and understand the enhancements in the new version: ### Developer Token The Developer Token remains a straightforward method for authentication: **Legacy (`Box Node SDK`):** ``` var BoxSDK = require('box-node-sdk'); var sdk = new BoxSDK({ clientID: 'YOUR-CLIENT-ID', clientSecret: 'YOUR-CLIENT_SECRET', }); var client = sdk.getBasicClient('YOUR-DEVELOPER-TOKEN'); ``` **Modern (`Box TypeScript SDK`):** The new SDK offers a more streamlined approach: ``` import { BoxClient, BoxDeveloperTokenAuth } from 'box-typescript-sdk-gen'; const auth = new BoxDeveloperTokenAuth({ token: 'DEVELOPER_TOKEN_GOES_HERE' }); const client = new BoxClient({ auth }); ``` ### JWT Authentication JSON Web Tokens (JWT) offer a secure method of authentication. Here's how the process has evolved: #### Leveraging the JWT Configuration File **Legacy (`Box Node SDK`):** ``` var BoxSDK = require('box-node-sdk'); var jsonConfig = require('/path/to/config.json'); var sdk = BoxSDK.getPreconfiguredInstance(jsonConfig); var serviceAccountClient = sdk.getAppAuthClient('enterprise'); ``` **Modern (`Box TypeScript SDK`):** The new SDK provides a more organized approach: ``` import { BoxClient, BoxJwtAuth, JwtConfig } from 'box-typescript-sdk-gen'; const jwtConfig = JwtConfig.fromConfigFile('/path/to/config.json'); const auth = new BoxJwtAuth({ config: jwtConfig }); const client = new BoxClient({ auth }); ``` #### Manually Providing JWT Configuration For those who prefer manual configurations, both SDKs offer flexibility: **Legacy (`Box Node SDK`):** ``` var BoxSDK = require('box-node-sdk'); var sdk = new BoxSDK({ clientID: 'YOUR-CLIENT-ID', clientSecret: 'YOUR-CLIENT_SECRET', appAuth: { keyID: 'YOUR-KEY-ID', privateKey: 'YOUR-PRIVATE_KEY', passphrase: 'YOUR-PRIVATE-KEY-PASSPHRASE', }, }); var serviceAccountClient = sdk.getAppAuthClient( 'enterprise', 'YOUR-ENTERPRISE-ID', ); ``` **Modern (`Box TypeScript SDK`):** The new SDK introduces a more structured approach: ``` import { BoxJwtAuth, JwtConfig } from 'box-typescript-sdk-gen'; const jwtConfig = new JwtConfig({ clientId: 'YOUR_CLIENT_ID', clientSecret: 'YOUR_CLIENT_SECRET', enterpriseId: 'YOUR_ENTERPRISE_ID', userId: 'USER_ID', jwtKeyId: 'YOUR_JWT_KEY_ID', privateKey: 'YOUR_PRIVATE_KEY', privateKeyPassphrase: 'PASSPHRASE', jwtAlgorithm: 'RS256', }); const auth = new BoxJwtAuth({ config: jwtConfig }); ``` #### User Authentication Simplified To authenticate as user you need to call `withUserSubject` method with id of the user to authenticate. The method returns a new instance of `BoxJwtAuth` class, which will perform authentication call in scope of the user on the first API call. The new auth instance can be used to create a new user client instance. **Legacy (`Box Node SDK`):** ``` const userClient = sdk.getAppAuthClient('user', 'USER_ID'); ``` **Modern (`Box TypeScript SDK`):** ``` const userAuth = jwtAuth.withUserSubject('USER_ID'); const userClient = new BoxClient({ auth: userAuth }); ``` ### Client Credentials Grant The Client Credentials Grant method is a popular choice for many developers. Let's see how it's been enhanced: #### Service Account Token Acquisition **Legacy (`Box Node SDK`):** ``` const BoxSDK = require('box-node-sdk'); const sdkConfig = { boxAppSettings: { clientID: 'CLIENT_ID', clientSecret: 'CLIENT_SECRET', }, enterpriseID: 'ENTERPRISE_ID', }; const sdk = BoxSDK.getPreconfiguredInstance(sdkConfig); const client = sdk.getAnonymousClient(); ``` **Modern (`Box TypeScript SDK`):** The new SDK offers a more organized structure: ``` import { CcgConfig, BoxCcgAuth, BoxClient } from 'box-typescript-sdk-gen'; const ccgConfig = new CcgConfig({ clientId: 'YOUR_CLIENT_ID', clientSecret: 'YOUR_CLIENT_SECRET', enterpriseId: 'YOUR_ENTERPRISE_ID', }); const auth = new BoxCcgAuth({ config: ccgConfig }); const client = new BoxClient({ auth }); ``` #### User Token Acquisition **Legacy (`Box Node SDK`):** ``` const BoxSDK = require('box-node-sdk'); const sdkConfig = { boxAppSettings: { clientID: 'CLIENT_ID', clientSecret: 'CLIENT_SECRET', }, enterpriseID: 'ENTERPRISE_ID', // The enterprise id in this case is optional and can be omitted. }; const sdk = BoxSDK.getPreconfiguredInstance(sdkConfig); const client = sdk.getCCGClientForUser('USER_ID'); ``` **Modern (`Box TypeScript SDK`):** The new SDK streamlines the process: ``` import { CcgConfig, BoxCcgAuth, BoxClient } from 'box-typescript-sdk-gen'; const ccgConfig = new CcgConfig({ clientId: 'YOUR_CLIENT_ID', clientSecret: 'YOUR_CLIENT_SECRET', userId: 'YOUR_USER_ID', }); const auth = new BoxCcgAuth({ config: ccgConfig }); const client = new BoxClient({ auth }); ``` ### Smooth Switching between Service Account and User In the new SDK, to keep the immutability design, the methods responsible for switching authenticated subject return a new instance of `BoxCcgAuth` class. The new instance will fetch a new token on the next API call. The new auth instance can be used to create a new client instance. The old instance of `BoxCcgAuth` class will remain unchanged and will still use the old token. **Legacy (`Box Node SDK`):** ``` const client = sdk.getCCGClientForUser('USER_ID'); ``` **Modern (`Box TypeScript SDK`):** To authenticate with enterprise subject call: ``` const enterpriseAuth = ccgAuth.withEnterpriseSubject('YOUR_ENTERPRISE_ID'); const enterpriseClient = new BoxClient({ auth: enterpriseAuth }); ``` To authenticate with user subject call: ``` const userAuth = ccgAuth.withUserSubject('YOUR_USER_ID'); const userClient = new BoxClient({ auth: userAuth }); ``` ### OAuth 2.0 Authentication OAuth 2.0 remains a robust authentication method. Let's explore the improvements: #### Fetching the Authorization URL **Legacy (`Box Node SDK`):** ``` var BoxSDK = require('box-node-sdk'); var sdk = new BoxSDK({ clientID: 'YOUR-CLIENT-ID', clientSecret: 'YOUR-CLIENT_SECRET', }); // the URL to redirect the user to var authorize_url = sdk.getAuthorizeURL({ response_type: 'code', }); ``` **Modern (`Box TypeScript SDK`):** The new SDK provides more flexibility: ``` import { BoxOAuth, OAuthConfig } from 'box-typescript-sdk-gen'; const config = new OAuthConfig({ clientId: 'OAUTH_CLIENT_ID', clientSecret: 'OAUTH_CLIENT_SECRET', }); const oauth = new BoxOAuth({ config: config }); var authorize_url = oauth.getAuthorizeUrl(); ``` #### Seamless Authentication **Legacy (`Box Node SDK`):** ``` sdk.getTokensAuthorizationCodeGrant('<CODE>', null, function (err, tokenInfo) { if (err) { // handle error } var tokenStore = new TokenStore(); tokenStore.write(tokenInfo, function (storeErr) { if (storeErr) { // handle token write error } var client = sdk.getPersistentClient(tokenInfo, tokenStore); }); }); ``` **Modern (`Box TypeScript SDK`):** The new SDK simplifies the process: ``` await oauth.getTokensAuthorizationCodeGrant('code'); const client = new BoxClient({ auth: oauth }); ``` ### Customizable Token Storage and Retrieval Callbacks Token management is crucial for maintaining secure sessions. The new SDK offers enhanced flexibility: **Legacy (`Box Node SDK`):** ``` function TokenStore() { // The token store constructor should create a specific store instance // for the user in question — it may need to take in a user ID or other // identifier. } TokenStore.prototype.read = function (callback) { // Read the user's tokens from your data store and // call the callback. // callback(error) if some error occured // callback(null, tokenInfo) if the read succeeded }; TokenStore.prototype.write = function (tokenInfo, callback) { // Write the token information to the store. // The tokenInfo argument is an Object, and can be // serialized as JSON for storage. // Call the callback after the write. // callback(error) if some error occured // callback(null) if the write succeeded }; TokenStore.prototype.clear = function (callback) { // Delete the user's token information from the store, // and call the callback after the write. // callback(error) if some error occured // callback(null) if the deletion succeeded }; ``` **Modern (`Box TypeScript SDK`):** The new SDK allows developers to define custom classes for token storage: ``` import { BoxOAuth } from 'box-typescript-sdk-gen'; import { TokenStorage } from 'box-typescript-sdk-gen/box/tokenStorage.generated'; import { AccessToken } from 'box-typescript-sdk-gen/schemas/accessToken.generated'; class CustomTokenStorage extends TokenStorage { async store(token: AccessToken): Promise<undefined> { // Store token } async get(): Promise<undefined | AccessToken> { // Retrieve token return token; } async clear(): Promise<undefined> { // Clear token } } const tokenStorage = new CustomTokenStorage(); const authConfig = { /* ... , */ tokenStorage }; const auth = new BoxOAuth({ config: authConfig }); ``` ### Downscope token To process of downscoping token in the new SDK is enhanced and more flexible. **Legacy (`Box Node SDK`):** ``` client .exchangeToken('item_preview', 'https://api.box.com/2.0/files/123456789') .then((tokenInfo) => { // tokenInfo.accessToken contains the new downscoped access token }); ``` **Modern (`Box TypeScript SDK`):** ``` let resource = 'https://api.box.com/2.0/files/123456789'; let token = await oauth.downscopeToken(['item_preview'], resource); const auth = new BoxDeveloperTokenAuth({ token: token.accessToken }); const client = new BoxClient({ auth }); ``` ### Revoke token The difference between the old and new SDK in the process of revoking token is as follows. **Legacy (`Box Node SDK`):** ``` client.revokeTokens('<TOKEN>').then(() => { // the client's access token have been revoked }); ``` **Modern (`Box TypeScript SDK`):** ``` await auth.revokeTokens(); ``` ## Configuration ### As-User header The As-User header is used by enterprise admins to make API calls on behalf of their enterprise's users. This requires the API request to pass an `As-User: USER-ID` header. The following examples assume that the client has been instantiated with an access token with appropriate privileges to make As-User calls. In old SDK the client `asUser(userID)` method set up the client to impersonate a given user. It modified existing client, so that all calls made with its instance were made in context of the impersonated user. **Legacy (`Box Node SDK`):** ``` client.asUser('USER-ID'); client.folders.getItems('0').then((items) => { // items contains the collection of files and folders // in the root folder of the user with USER-ID }); ``` **Modern (`Box TypeScript SDK`):** In the new SDK the method was renamed to `withAsUserHeader(userId: string): BoxClient` and returns a new instance of `BoxClient` class with the As-User header appended to all API calls made by the client. ``` const userClient = client.withAsUserHeader('1234567'); ``` ### Custom Base URLs **Legacy (`Box Node SDK`):** In old SDK you could specify the custom base URLs, which will be used for API calls made by using the `configure` method on the SDK instance: ``` const sdk = BoxSDKNode.getPreconfiguredInstance(APP_SETTINGS); var additonalParams = { apiRootURL: 'https://my.company.url.com', uploadAPIRootURL: 'https://my.company.url.com/upload', authorizeRootURL: 'https://my.company.url.com/authorize', }; sdk.configure(additonalParams); ``` **Modern (`Box TypeScript SDK`):** In the new SDK this functionality has been implemented as part of the `BoxClient` class. By calling the `client.withCustomBaseUrls()` method, you can specify the custom base URLs that will be used for API calls made by client. Following the immutability pattern, this call creates a new client, leaving the original client unmodified. ``` const newClient = client.withCustomBaseUrls({ baseUrl: 'https://api.box.com', uploadUrl: 'https://upload.box.com/api', oauth2Url: 'https://account.box.com/api/oauth2', }); ``` ## Convenience methods ### Webhook validation Webhook validation is used to validate a webhook message by verifying the signature and the delivery timestamp. **Legacy (`Box Node SDK`):** In the old SDK, you could pass the `body` as either a `JSON` object or a `string`, and it would return a `boolean` value indicating whether the message was valid. ``` let isValid = BoxSDK.validateWebhookMessage( body, headers, primaryKey, secondaryKey, ); ``` **Modern (`Box TypeScript SDK`):** In the new SDK, the `WebhooksManager.validateMessage()` method requires the `body` to be of type `string`. So if the body is in `JSON` type, you must convert it to a `string` using `JSON.stringify(body)` before calling `validateMessage()`. ``` let stringBody = JSON.stringify(body); let isValid = await WebhooksManager.validateMessage( stringBody, headers, primaryKey, { secondaryKey: secondaryKey } satisfies ValidateMessageOptionalsInput, ); ``` ### Chunked upload of big files For large files or in cases where the network connection is less reliable, you may want to upload the file in parts. This allows a single part to fail without aborting the entire upload, and failed parts are being retried automatically. **Legacy (`Box Node SDK`):** In the old SDK, you could use the `getChunkedUploader()` method to create a chunked uploader object. Then, you would call the `start()` method to begin the upload process. The `getChunkedUploader()` method requires the `parentFolderId`, `fileSize`, `fileName` and `stream` parameters. ``` var stream = fs.createReadStream('/path/to/file.txt'); var fileName = 'new_name.txt'; var fileSize = fs.statSync('/path/to/file.txt').size; var parentFolderId = '0'; client.files .getChunkedUploader(parentFolderId, fileSize, fileName, stream) .then((uploader) => uploader.start()) .then((file) => { /* ... */ }); ``` **Modern (`Box TypeScript SDK`):** In the new SDK, the equivalent method is `chunked_uploads.uploadBigFile()`. It accepts a `Readable` object as the `file` parameter, and the `fileName` and `fileSize` parameters are now passed as arguments. The `parentFolderId` parameter is also required to specify the folder where the file will be uploaded. ``` import { File } from 'box-typescript-sdk-gen/schemas/file.generated'; var fileByteStream = fs.createReadStream('/path/to/file.txt'); var fileName = 'new_name.txt'; var fileSize = fs.statSync('/path/to/file.txt').size; var parentFolderId = '0'; const uploadedFile: File = await client.chunkedUploads.uploadBigFile( fileByteStream, fileName, fileSize, parentFolderId, ); ``` --- ### Migration Guide: From `Box Windows V2 SDK` to `Box Dotnet SDK` **Type:** page | **Section:** Additional Resources Migration Guide: From Box Windows V2 SDK to Box Dotnet SDK Introduction Installation Highlighting the Key Differences Nullable reference… # Migration Guide: From Box Windows V2 SDK to Box Dotnet SDK - [Introduction](#introduction) - [Installation](#installation) [Highlighting the Key Differences](#highlighting-the-key-differences) - [Nullable reference types support](#nullable-reference-types-support) - [Self-documenting object creation](#self-documenting-object-creation) - [Native cancellation token support](#native-cancellation-token-support) - [One package to rule them all](#one-package-to-rule-them-all) - [Simplified namespaces](#simplified-namespaces) - [Enum wrapper](#enum-wrapper) - [Union types](#union-types) [Diving into Authentication](#diving-into-authentication) - [Developer Token](#developer-token) [JWT Authentication](#jwt-authentication) - [Leveraging the JWT Configuration File](#leveraging-the-jwt-configuration-file) - [Manually Providing JWT Configuration](#manually-providing-jwt-configuration) - [User Authentication Simplified](#user-authentication-simplified) [Client Credentials Grant](#client-credentials-grant) - [Service Account Token Acquisition](#service-account-token-acquisition) - [User Token Acquisition](#user-token-acquisition) [Smooth Switching between Service Account and User](#smooth-switching-between-service-account-and-user) [OAuth 2.0 Authentication](#oauth-20-authentication) - [Fetching the Authorization URL](#fetching-the-authorization-url) - [Seamless Authentication](#seamless-authentication) [Customizable Token Storage](#customizable-token-storage) [Configuration](#configuration) - [As-User header](#as-user-header) - [Custom Base URLs](#custom-base-urls) [Convenience methods](#convenience-methods) - [Chunked upload of big files](#chunked-upload-of-big-files) ## Introduction Welcome to the `Box DotNet SDK`, the pinnacle of Box's SDK evolution tailored for developers eager to integrate with the Box API using C# with .NET. This next-generation toolkit is meticulously crafted with contemporary development practices, ensuring an unparalleled, seamless experience. While the `Box Windows V2 SDK` served its purpose well, the `Box DotNet SDK` elevates the experience to new heights. One of its standout features is its auto-generation directly from the Open API Specification. This guarantees that developers are always equipped with the latest Box API features, eliminating any lag or discrepancies. This guide is your compass, offering insights and directions for a smooth migration from the legacy `Box Windows V2 SDK` to the state-of-the-art `Box DotNet SDK`. As we journey through, we'll spotlight the key differences, enhanced functionalities, and the myriad benefits that await. For those who wish to delve deeper into the intricacies and advantages of the new SDK, the [official README](https://github.com/box/box-dotnet-sdk-gen/blob/main/README.md) is a treasure trove of information. ## Installation Embarking on your journey with the `Box DotNet SDK` is straightforward. Here's how you can set it up: ``` Install-Package Box.Sdk.Gen ``` Alternatively, you can find this package and it's latest version [on nuget](https://www.nuget.org/packages/Box.Sdk.Gen) and manually add it to the `.csproj` file as a reference: ``` <ItemGroup> <PackageReference Include="Box.Sdk.Gen" Version="X.Y.Z" /> </ItemGroup> ``` For those who are hesitant to make the full leap, fear not. The `Box DotNet SDK` can coexist peacefully alongside the legacy `Box Windows V2 SDK` within the same project. This coexistence offers a gentle migration path, allowing developers to transition at their own pace. However, for an optimal experience, a complete transition to the new SDK is recommended in due course. ## Highlighting the Key Differences ### Nullable reference types support The SDK now supports [nullable reference types](https://learn.microsoft.com/en-us/dotnet/csharp/nullable-references) whenever possible. This allows to perform null state analyis and detect many problems even before the code is run. To enable support for nullable references, enable it in your project by adding the following line to your .csproj ``` <Nullable>enable</Nullable> ``` When this option is enabled, a null state analysis will be performed and more information about the object will be present. Let's examine the following scenario: ``` var user = await client.Users.GetUserMeAsync(); // a warning is displayed: "Enterprise" may be null here. You should add a check for the null value to prevent NRE Console.WriteLine(user.Enterprise.Id); ``` Thanks to the null state analysis, it is known that `Enterprise` part of the `user` is not always present in the object and can sometimes be set to `null`. In this case, we need to perform an additional check to avoid the [Null Reference Exception](https://learn.microsoft.com/en-us/dotnet/api/system.nullreferenceexception). ``` var user = await client.Users.GetUserMeAsync(); // no warning now Console.WriteLine(user.Enterprise?.Id); ``` Without nullable reference types, it would not be possible to determine which reference types could be set to null, and we would have to do it with each of them. Otherwise we would risk encountering Null Reference Exception. ### Self-documenting object creation In the Legacy SDK `Box Windows V2 SDK` all objects exposed setters and an empty constructor. It was possible to create an object without setting some of the fields required by the API. This would result in the API error (usually Bad Request) saying that the request was missing some requeired fields. Some of the functions validated if the request fields are set properly, but even then, the lack of required fields could not be detected when call to such function was executed. The modern `Box DotNet SDK` is designed to minimize problems with object creation and "force" the creation of objects in the correct state by utilizng constructors capabilities. Let's look at the following example ``` // It is not possible to create user without a name so it's a required argument of a constructor var requestBody = new CreateUserRequestBodyArg(name: "my-test-account"); var response = await client.Users.CreateUserAsync(requestBody); ``` If a field is required by the API, it must be passed to the constructor. In other words, it's not possible to create a `CreateUserRequestBodyArg` without a name supplied as an argument to the constructor. Optional parameters can be passed using [object initializer syntax](https://learn.microsoft.com/en-us/dotnet/csharp/programming-guide/classes-and-structs/object-and-collection-initializers). ``` // IsPlatformAccessOnly is not required by the API so it's passed in object initializer var requestBody = new CreateUserRequestBodyArg(name: "my-test-account") { IsPlatformAccessOnly = true }; var response = await client.Users.CreateUserAsync(requestBody); ``` This allows for smooth, one-line and immutable object creation and it's easy to see which fields must be filled in and which are optional. Combined with the previous point about nullable reference types, it allows you to take full advantage of C#'s typing arsenal to prevent errors in your code even before the code is executed. ### Native cancellation token support The new SDK also introduces native support for [CancellationToken](https://learn.microsoft.com/en-us/dotnet/api/system.threading.cancellationtoken) for every call made to the Box API. This means that every API call can be easily cancelled and the task can be shutdown gracefully. Every API method accepts cancellation token usually as the last, optional parameter. You can use `CancellationToken` in response to your system events or as a timeout mechanism by utilizing the `CancelAfter` method. ``` var requestBody = new CreateUserRequestBodyArg(name: "my-test-account"); var cancellationTokenSource = new CancellationTokenSource(); var cancellationToken = cancellationTokenSource.Token; // cancel request after 10s cancellationTokenSource.CancelAfter(10000); try { var response = await client.Users.CreateUserAsync(requestBody, cancellationToken: cancellationToken); } catch (TaskCanceledException ex) { //handle exception } ``` When task is cancelled, native .NET `TaskCanceledException` is thrown. ### One package to rule them all Legacy `Box Windows V2 SDK` was distributed as a two separate packages namely `Box.V2` and `Box.V2.Core`. Adding the fact that some supported frameworks overlapped in both packages caused additional confusion for the customers, who had to decide which one was best for their projects. Additionally, the maintenance of both packages introduced developer overhead, extending the time of development for some features. In our new generation .NET SDK `Box DotNet SDK`, we have decided to distribute one package that is designed for multiple platforms, namely `Box.Sdk.Gen`. The determination of the best possible package match to the project in which this package is used will be delegated to the .NET platform itself. Each target platform with significiant differences will have a separate code base so that one target does not limit another. Most of the SDK is automatically generated now, so this will not cause a significant development overhead. For now, only .NET (formerly .NET Core) is supported, but .NET Framework support is planned for the future. ### Simplified namespaces Legacy `Box Windows V2 SDK` contained multiple namespaces which greatly reduced the discoverability of new features. The namespaces were also grouped based on their physical location rather than purpose they serve. Developers had to navigate through numerous namespaces to find the classes and methods they needed, which could be overwhelming and confusing, especially for newcomers. To simplify it, our the new generation .NET SDK `Box DotNet SDK`, provides only 4 main namespaces: - Box.Sdk.Gen - mostly contains base classes used by the SDK (e.g. `OneOf`, `StringEnum`). - Box.Sdk.Gen.Managers - contains managers that expose endpoints as functions. It also contains classes used to create requests, such as typed request body or query parameters. - Box.Sdk.Gen.Schemas - contains data models described by the API spec. - Box.Sdk.Gen.Internal - utility functions and classes used by the SDK. Should be used only if needed too. ### Enum wrapper Legacy `Box Windows V2 SDK` used [C# enumeration types](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/builtin-types/enum) when API exposed model with limited number of possible value for `String`. ``` public enum BoxRetentionType { modifiable, non_modifiable } //response fails during deserialization if BoxRetention type returned from the API is not defined on enum (e.g. partially_modifiable) var retentionType = await (client.RetentionPoliciesManager.GetRetentionPolicyAsync('id')).Type; ``` Sometimes this led to a situation where a newly added enum variant was present in the specification, but not in the SDK, and an exception could be thrown when deserializing the response. To overcome these issues the new generation .NET SDK `Box DotNet SDK` wraps enum types in safe, custom `StringEnum` structure. ``` // Type can be null, but it no longer fails, var retentionType = (await client.RetentionPolicies.GetRetentionPolicyByIdAsync(retentionPolicyId: retentionPolicy.Id)).Type; if (retentionType.Value.HasValue) { //it's a nullable enum so we need to access the underlying value RetentionPolicyRetentionTypeField enumVal = retentionType.Value.Value; } else { //if the enum value was null it means that this enum is unknown to the SDK at the moment, but we still can access the original value that came from the api through .StringValue prop string enumVaueAsString = retentionType.StringValue; } ``` This allows safe access to the underlying enumeration type. If the enumeration value is not yet known to the SDK, you can still access the original value from the API, by accessing `.StringValue` field. Thanks to [implicit conversion operators](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/operators/user-defined-conversion-operators) converting enum types to `StringEnum` is simple and usually there's no need to do it explicitly. ``` var requestBody = new CreateRetentionPolicyRequestBody("myPolicy", CreateRetentionPolicyRequestBodyPolicyTypeField.Finite, CreateRetentionPolicyRequestBodyDispositionActionField.PermanentlyDelete); RetentionPolicy retentionPolicy = await client.RetentionPolicies.CreateRetentionPolicyAsync(requestBody); ``` Usually there's no need to wrap enum type in the `StringEnum`, but if such need arises, you can use existing constructor of the `StringEnum`. ``` RetentionPolicyRetentionTypeField retentionPolicyType = RetentionPolicyRetentionTypeField.Modifiable; StringEnum<RetentionPolicyRetentionTypeField> retentionPolicyTypeWrapped = new StringEnum<RetentionPolicyRetentionTypeField>(retentionPolicyType); ``` ### Union types Box APIs can return and accept objects with different schemas at certain endpoints. This means that in C#, they must be represented by different classes to take full advantage of the type system. Legacy `Box Windows V2 SDK` used approach with common ancestor, by returning base object (in this case `BoxEntity`) that needed to be explicitly casted to the desired type. ``` var enterpriseEvents = await boxClient.EventsManager.EnterpriseEventsAsync(); foreach (BoxEnterpriseEvent entry in enterpriseEvents.Entries) { // we need to check if Source is of type BoxFileEventSource and cast it if (entry.Source is BoxFileEventSource fileEvent) { Console.WriteLine(fileEvent.Parent.Id); } } ``` This solution is error-prone and relies on the knowledge of the internals of the SDK. New generation .NET SDK `Box DotNet SDK` provides a custom structure to represent union types (or sum types) called `OneOf<T1, T2, ...>`. The different variant are represented as different fields on this structure. This allows new SDK users to use it like any other model. In addition, the SDK does not directly expose the `OneOf` structure in the models, but inherits from it, so you do not need to know how it works in detail when working with models. ``` var enterpriseEvents = await client.Events.GetEventsAsync(queryParams: new GetEventsQueryParams() { StreamType = GetEventsQueryParamsStreamTypeField.AdminLogs }); foreach (var entry in enterpriseEvents.Entries) { //if .File is not null it means it was returned from the API if (entry.Source.File != null) { Console.WriteLine(entry.Source.File.Parent.Id); } } ``` ## Diving into Authentication Authentication is a crucial aspect of any SDK. Let's delve into the authentication methods supported by both SDKs and understand the enhancements in the new version: ### Developer Token The Developer Token remains a straightforward method for authentication: **Legacy (`Box Windows V2 SDK`):** ``` using Box.Sdk.V2.Auth; using Box.Sdk.V2.Config; using Box.Sdk.V2; var config = new BoxConfigBuilder("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET").Build(); var session = new OAuthSession("YOUR_DEVELOPER_TOKEN", "N/A", 3600, "bearer"); var client = new BoxClient(config, session); ``` **Modern (`Box DotNet SDK`):** The new SDK offers a more streamlined approach: ``` using Box.Sdk.Gen; var auth = new BoxDeveloperTokenAuth(token: "DEVELOPER_TOKEN_GOES_HERE"); var client = new BoxClient(auth: auth); ``` ### JWT Authentication JSON Web Tokens (JWT) offer a secure method of authentication. Here's how the process has evolved: #### Leveraging the JWT Configuration File **Legacy (`Box Windows V2 SDK`):** ``` using Box.Sdk.V2; using Box.Sdk.V2.Config; using Box.Sdk.V2.JWTAuth; using var file = File.Open("/path/to/config.json", FileMode.Open, FileAccess.Read, FileShare.None); var config = BoxConfigBuilder.CreateFromJsonFile(file).Build(); var boxJWT = new BoxJWTAuth(config); var adminToken = await boxJWT.AdminTokenAsync(); BoxClient client = boxJWT.AdminClient(adminToken); ``` **Modern (`Box DotNet SDK`):** The new SDK provides a more organized approach: ``` using Box.Sdk.Gen; using var file = File.Open("/path/to/config.json", FileMode.Open, FileAccess.Read, FileShare.None); var jwtConfig = JwtConfig.FromConfigFile(file); var auth = new BoxJwtAuth(config: jwtConfig); var client = new BoxClient(auth: auth); ``` #### Manually Providing JWT Configuration For those who prefer manual configurations, both SDKs offer flexibility: **Legacy (`Box Windows V2 SDK`):** ``` using Box.Sdk.V2; using Box.Sdk.V2.Config; using Box.Sdk.V2.JWTAuth; var boxConfig = new BoxConfigBuilder("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET", "YOUR_ENTERPRISE_ID", "YOUR_PRIVATE_KEY", "YOUR_PRIVATE_KEY_PASSPHRASE", "YOUR_KEY_ID").Build(); var boxJWT = new BoxJWTAuth(boxConfig); var adminToken = await boxJWT.AdminTokenAsync(); BoxClient adminClient = boxJWT.AdminClient(adminToken); ``` **Modern (`Box DotNet SDK`):** The new SDK introduces a more structured approach: ``` using Box.Sdk.Gen; var jwtConfig = new JwtConfig(clientId: "YOUR_CLIENT_ID", clientSecret: "YOUR_CLIENT_SECRET", enterpriseId: "YOUR_ENTERPRISE_ID", privateKey: "YOUR_PRIVATE_KEY", privateKeyPassphrase: "YOUR_PRIVATE_KEY_PASSPHRASE", publicKeyId: "YOUR_KEY_ID"); var auth = new BoxJwtAuth(config: jwtConfig); var client = new BoxClient(auth: auth); ``` #### User Authentication Simplified Authenticating as a user has been made even more straightforward: **Legacy (`Box Windows V2 SDK`):** ``` using Box.Sdk.V2; using Box.Sdk.V2.Config; using Box.Sdk.V2.JWTAuth; var userToken = await boxJWT.UserTokenAsync("USER_ID"); var userClient = boxJWT.UserClient(userToken, "YOUR_USER_ID"); ``` **Modern (`Box DotNet SDK`):** The new SDK makes this method more organised: ``` using Box.Sdk.Gen; await auth.AsUserAsync("USER_ID"); var userClient = new BoxClient(auth: auth); ``` ### Client Credentials Grant The Client Credentials Grant method is a popular choice for many developers. Let's see how it's been enhanced: #### Service Account Token Acquisition **Legacy (`Box Windows V2 SDK`):** ``` using Box.Sdk.V2.CCGAuth; using Box.Sdk.V2.Config; var boxConfig = new BoxConfigBuilder(clientId: "YOUR_CLIENT_ID", clientSecret: "YOUR_CLIENT_SECRET") .SetEnterpriseId("YOUR_ENTERPRISE_ID") .Build(); var boxCCG = new BoxCCGAuth(boxConfig); var adminToken = await boxCCG.AdminTokenAsync(); var adminClient = boxCCG.AdminClient(adminToken: adminToken); ``` **Modern (`Box DotNet SDK`):** The new SDK offers a more organized structure: ``` using Box.Sdk.Gen; var ccgConfig = new CcgConfig(clientId: "YOUR_CLIENT_ID", clientSecret: "YOUR_CLIENT_SECRET", enterpriseId: "YOUR_ENTERPRISE_ID"); var auth = new BoxCcgAuth(config: ccgConfig); var client = new BoxClient(auth: auth); ``` #### User Token Acquisition **Legacy (`Box Windows V2 SDK`):** ``` using Box.Sdk.V2.CCGAuth; using Box.Sdk.V2.Config; var boxConfig = new BoxConfigBuilder(clientId: "YOUR_CLIENT_ID", clientSecret: "YOUR_CLIENT_SECRET") .Build(); var boxCCG = new BoxCCGAuth(boxConfig); var userToken = await boxCCG.UserTokenAsync("YOUR_USER_ID"); var userClient = boxCCG.UserClient(userToken: userToken, userId: "YOUR_USER_ID"); ``` **Modern (`Box DotNet SDK`):** The new SDK streamlines the process: ``` using Box.Sdk.Gen; var ccgConfig = new CcgConfig(clientId: "YOUR_CLIENT_ID", clientSecret: "YOUR_CLIENT_SECRET", userId: "YOUR_USER_ID"); var auth = new BoxCcgAuth(config: ccgConfig); var userClient = new BoxClient(auth: auth); ``` ### Smooth Switching between Service Account and User Transitioning between account types is now more intuitive: **Modern (`Box DotNet SDK`):** ``` using Box.Sdk.Gen; await auth.AsEnterpriseAsync("ENTERPRISE_ID"); ``` ### OAuth 2.0 Authentication OAuth 2.0 remains a robust authentication method. Let's explore the improvements: #### Fetching the Authorization URL **Legacy (`Box Windows V2 SDK`):** ``` using Box.Sdk.V2; using Box.Sdk.V2.Config; var config = new BoxConfigBuilder("CLIENT_ID", "CLIENT_SECRET", new System.Uri("YOUR_REDIRECT_URL")).Build(); var client = new BoxClient(config); // the URL to redirect the user to var authorizeUrl = "https://account.box.com/api/oauth2/authorize?client_id=[CLIENT_ID]&response_type=code"; ``` **Modern (`Box DotNet SDK`):** The new SDK provides more flexibility: ``` using Box.Sdk.Gen; var config = new OAuthConfig(clientId: "YOUR_CLIENT_ID", clientSecret: "YOUR_CLIENT_SECRET"); var auth = new BoxOAuth(config: config); // the URL to redirect the user to var authorizeUrl = auth.GetAuthorizeUrl(new GetAuthorizeUrlOptions() { RedirectUri = "YOUR_REDIRECT_URL" }); ``` #### Seamless Authentication **Legacy (`Box Windows V2 SDK`):** ``` using Box.Sdk.V2; var session = await client.Auth.AuthenticateAsync("[CODE]"); var client = new BoxClient(config, session); ``` **Modern (`Box DotNet SDK`):** The new SDK simplifies the process: ``` using Box.Sdk.Gen; await auth.GetTokensAuthorizationCodeGrantAsync("code"); ``` ### Customizable Token Storage Token management is crucial for maintaining secure sessions. The new SDK offers enhanced flexibility: **Legacy (`Box Windows V2 SDK`):** ``` // there are no good ways to implement token storage in the legacy sdk // best that can be done is to respond to the authorization events public class CustomTokenStorage { // retrieves token string RetrieveToken(); // stores token void SaveToken(string accessToken); } var client = new BoxClient(config, session); client.Auth.SessionAuthenticated += delegate (object o, SessionAuthenticatedEventArgs e) { string newAccessToken = e.Session.AccessToken; tokenStorage.SaveToken(newAccessToken); }; ``` **Modern (`Box DotNet SDK`):** The new SDK allows developers to define custom classes for token storage: ``` using Box.Sdk.Gen; using Box.Sdk.Gen.Schemas; using Task = System.Threading.Tasks.Task; class CustomTokenStorage : ITokenStorage { // Clear token public Task ClearAsync() { throw new NotImplementedException(); } // Retrieve token public Task<AccessToken?> GetAsync() { throw new NotImplementedException(); } // Store token public Task StoreAsync(AccessToken token) { throw new NotImplementedException(); } } var tokenStorage = new CustomTokenStorage(); var config = new OAuthConfig(clientId: "YOUR_CLIENT_ID", clientSecret: "YOUR_CLIENT_SECRET", tokenStorage: tokenStorage); ``` ## Configuration ### As-User header The As-User header is used by enterprise admins to make API calls on behalf of their enterprise's users. This requires the API request to pass an `As-User: USER-ID` header. The following examples assume that the client has been instantiated with an access token with appropriate privileges to make As-User calls. In old SDK you could call client constructor with `asUser` parameter to create a new client to impersonate the provided user. **Legacy (`Box Windows V2 SDK`):** ``` using Box.V2.Config; var config = new BoxConfigBuilder("clientId", "clientSecret").Build(); var client = new BoxClient(config, asUser: "userId"); ``` **Modern (`Box DotNet SDK`):** In the new SDK the method was renamed to `WithAsUserHeader(string userId)` and returns a new instance of `BoxClient` class with the As-User header appended to all API calls made by the client. The method accepts only user id as a parameter. ``` using Box.Sdk.Gen; var client = new BoxClient(new BoxCcgAuth(new CcgConfig("clientId", "clientSecret"))); var asUserClient = client.WithAsUserHeader("userId"); ``` Additionally `BoxClient` offers a `WithExtraHeaders(Dictionary<string, string>? extraHeaders = default) ` method, which allows you to specify the custom set of headers, which will be included in every API call made by client. Calling the `client.WithExtraHeaders(extraHeaders)` method creates a new client, leaving the original client unmodified. ``` using Box.Sdk.Gen; var client = new BoxClient(new BoxCcgAuth(new CcgConfig("clientId", "clientSecret"))); var clientWithHeaders = client.WithExtraHeaders(new Dictionary<string, string>() { { "customHeaders", "customHeaderValue" } }); ``` ### Custom Base URLs **Legacy (`Box Windows V2 SDK`):** In old SDK you could specify the custom base URLs, which will be used for API calls made by setting the new values by calling function of `BoxConfigBuilder`. ``` using Box.V2.Config; var config = new BoxConfigBuilder("clientId", "clientSecret") .SetBoxApiHostUri(new Uri("https://new-base-url.com")) .SetBoxUploadApiUri(new Uri("https://my-company-upload-url.com")) .Build(); ``` **Modern (`Box DotNet SDK`):** In the new SDK this functionality has been implemented as part of the `BoxClient` class. By calling the `client.WithCustomBaseUrls()` method, you can specify the custom base URLs that will be used for API calls made by client. Following the immutability pattern, this call creates a new client, leaving the original client unmodified. ``` using Box.Sdk.Gen; var client = new BoxClient(new BoxCcgAuth(new CcgConfig("clientId", "clientSecret"))); var clientWithCustomUrls = client.WithCustomBaseUrls(new BaseUrls("https://new-base-url.com", "https://my-company-upload-url.com", "https://my-company.com/oauth2")); ``` ## Convenience methods ### Chunked upload of big files For large files or in cases where the network connection is less reliable, you may want to upload the file in parts. This allows a single part to fail without aborting the entire upload, and failed parts are being retried automatically. **Legacy (`Box Windows V2 SDK`):** In the old SDK, you could use the `UploadUsingSessionAsync` method of the `FilesManager` class to upload a large file. This method accepted a `Stream` as the input stream, and the file name and parent folder ID were passed as parameters. ``` using (FileStream fileStream = new FileStream(filePath, FileMode.Open)) { string parentFolderId = "0"; var bFile = await client.FilesManager.UploadUsingSessionAsync(fileStream, "File v2.pdf", parentFolderId); Console.WriteLine("{0} uploaded to folder: {1} as file: {2}", filePath, parentFolderId, bFile.Id); } ``` **Modern (`Box DotNet SDK`):** In the new SDK, the equivalent method is `ChunkedUploads.UploadBigFileAsync()`. It accepts a `Stream` object as the `file` parameter, and the `fileName` and `fileSize` parameters are now passed as arguments. The `parentFolderId` parameter is also required to specify the folder where the file will be uploaded. ``` int fileSize = 20 * 1024 * 1024; using var fileByteStream = new FileStream("My_Large_File.txt", FileMode.Open, FileAccess.Read); string fileName = "My_Large_File.txt"; const string parentFolderId = "0"; var uploadedFile = await client.ChunkedUploads.UploadBigFileAsync( file: fileByteStream, fileName: fileName, fileSize: fileSize, parentFolderId: parentFolderId ); ``` --- ### Recent Items **Type:** page | **Section:** Additional Resources Recent Items Recent Items returns information about files that have been accessed by a user not long ago. It keeps track of items that were… # Recent Items Recent Items returns information about files that have been accessed by a user not long ago. It keeps track of items that were accessed either in the last 90 days or the last 1000 items accessed (both conditions must be met). - [Get a User's Recent Items](#get-a-users-recent-items) ## Get a User's Recent Items Get a list of all recent items the user has by calling [`recentItems.get(options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/RecentItems.html#get). ``` client.recentItems.get({limit: 1000}) .then(recentItems => { /* recentItems -> { next_marker: '', limit: 1000, order: { by: 'interacted_at', direction: 'DESC' }, entries: [ { type: 'recent_item', interaction_type: 'item_preview', interacted_at: '2017-06-06T15:46:28-07:00', item: { type: 'file', id: '11111', file_version: { type: 'file_version', id: '22222', sha1: 'd0a8c75ba72bf923bfb0c855bbcf1e8f7cc817dd' }, sequence_id: '0', etag: '0', sha1: 'd0a8c75ba72bf923bfb0c855bbcf1e8f7cc817dd', name: 'File2.txt' }, interaction_shared_link: "https://app.box.com/s/27jtnq2g8b7bu30pivpbz6nb2ef47mfs" }, { type: 'recent_item', interaction_type: 'item_preview', interacted_at: '2017-06-06T15:46:27-07:00', item: { type: 'file', id: '33333', file_version: { type: 'file_version', id: '44444', sha1: '12a715416bc96ba3ea860480c815657d5e0809da' }, sequence_id: '0', etag: '0', sha1: '12a715416bc96ba3ea860480c815657d5e0809da', name: 'Image1.png' }, interaction_shared_link: null } ] } */ }); ``` --- ### Recent Items **Type:** page | **Section:** Additional Resources Recent Items Recent Items returns information about files that have been accessed by a user not long ago. It keeps track of items that were… # Recent Items Recent Items returns information about files that have been accessed by a user not long ago. It keeps track of items that were accessed either in the last 90 days or the last 1000 items accessed (both conditions must be met). - [Get a User's Recent Items](#get-a-users-recent-items) ## Get a User's Recent Items Get a list of all recent items the user has by calling [`BoxRecents.getRecentItems(BoxAPIConnection api, int limit, String... fields)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxRecents.html#getRecentItems-com.box.sdk.BoxAPIConnection-int-java.lang.String...-). This returns an ordered iterable of the [`BoxRecentItem`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxRecentItem.html) records, which describe which item the user interacted with, when they interacted with it, and what type of interaction it was. Any `fields` specified relate to the items themselves (e.g. the recent files and folders). ``` // Get the latest 100 items the user has interacted with Iterable<BoxRecentItem> recentItems = BoxRecents.getRecentItems(api, 100); ``` --- ### Recent Items **Type:** page | **Section:** Additional Resources Recent Items Recent Items returns information about files that have been accessed by a user not long ago. It keeps track of items that were… # Recent Items Recent Items returns information about files that have been accessed by a user not long ago. It keeps track of items that were accessed either in the last 90 days or the last 1000 items accessed (both conditions must be met). - [Get a User's Recent Items](#get-a-users-recent-items) ## Get a User's Recent Items Get a list of all recent items the user has by calling `GetRecentItemsAsync(int limit = 100, string marker = null, IEnumerable<string> fields = null, bool autoPaginate = false)`. ``` BoxCollectionMarkerBasedV2<BoxRecentItem> recentItems = await client.RecentItemsManager .GetRecentItemsAsync(limit: 500); ``` --- ### Recent Items **Type:** page | **Section:** Additional Resources Recent Items A recent item object represents a file that has been recently accessed by a user. Items accessed either in the last 90 days or… # Recent Items A recent item object represents a file that has been recently accessed by a user. Items accessed either in the last 90 days or the last 1000 accessed items are tracked. - [Get Recent Items](#get-recent-items) ## Get Recent Items To get recently accessed items, call [`client.recentItems.list(marker: String?, limit: Int?, fields: [String]?)`](https://opensource.box.com/box-ios-sdk/Classes/RecentItemsModule.html#/s:6BoxSDK17RecentItemsModuleC4list6marker5limit6fields10completionySSSg_SiSgSaySSGSgys6ResultOyAA14PagingIteratorCyAA0C4ItemCGAA0A8SDKErrorCGctF). This method will return an iterator object, which is used to retrieve recent items. ``` let iterator = client.recentItems.list() iterator.next { results in switch results { case let .success(page): for item in page.entries { print("Interaction type is \(item.interactionType)") } case let .failure(error): print(error) } } ``` --- ### Recent Items **Type:** page | **Section:** Additional Resources Recent Items A recent item object represents a file that has been recently accessed by a user. Items accessed either in the last 90 days or… # Recent Items A recent item object represents a file that has been recently accessed by a user. Items accessed either in the last 90 days or the last 1000 accessed items are tracked. - [Get Recent Items](#get-recent-items) ## Get Recent Items To get recently accessed items, call [`client.recentItems.list(marker: String?, limit: Int?, fields: [String]?)`](https://opensource.box.com/box-ios-sdk/Classes/RecentItemsModule.html#/s:6BoxSDK17RecentItemsModuleC4list6marker5limit6fields10completionySSSg_SiSgSaySSGSgys6ResultOyAA14PagingIteratorCyAA0C4ItemCGAA0A8SDKErrorCGctF). This method will return an iterator object, which is used to retrieve recent items. ``` let iterator = client.recentItems.list() iterator.next { results in switch results { case let .success(page): for item in page.entries { print("Interaction type is \(item.interactionType)") } case let .failure(error): print(error) } } ``` --- ### RecentItemsManager **Type:** page | **Section:** Additional Resources RecentItemsManager List recently accessed items List recently accessed items Returns information about the recent items accessed by a user… # RecentItemsManager - [List recently accessed items](#list-recently-accessed-items) ## List recently accessed items Returns information about the recent items accessed by a user, either in the last 90 days or up to the last 1000 items accessed. This operation is performed by calling function `getRecentItems`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-recent-items/). ``` await client.recentItems.getRecentItems(); ``` ### Arguments queryParams `GetRecentItemsQueryParams` - Query parameters of getRecentItems method headersInput `GetRecentItemsHeadersInput` - Headers of getRecentItems method cancellationToken `undefined | CancellationToken` - Token used for request cancellation. ### Returns This function returns a value of type `RecentItems`. Returns a list recent items access by a user. --- ### RecentItemsManager **Type:** page | **Section:** Additional Resources RecentItemsManager List recently accessed items List recently accessed items Returns information about the recent items accessed by a user… # RecentItemsManager - [List recently accessed items](#list-recently-accessed-items) ## List recently accessed items Returns information about the recent items accessed by a user, either in the last 90 days or up to the last 1000 items accessed. This operation is performed by calling function `get_recent_items`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-recent-items/). ``` client.recent_items.get_recent_items() ``` ### Arguments fields `Optional[List[str]]` - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested. limit `Optional[int]` - The maximum number of items to return per page. marker `Optional[str]` - Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `RecentItems`. Returns a list recent items access by a user. --- ### Redirect user to auth_url, where they will enter their Box credentials **Type:** page | **Section:** Additional Resources Authentication The Box API uses OAuth2 for authentication, which can be difficult to implement. The SDK makes it easier by providing classes… # Authentication The Box API uses OAuth2 for authentication, which can be difficult to implement. The SDK makes it easier by providing classes that handle obtaining tokens and automatically refreshing them when possible. See the [OAuth 2 overview](https://developer.box.com/en/guides/authentication/) for a detailed overview of how the Box API handles authentication. [Ways to Authenticate](#ways-to-authenticate) - [Developer Token](#developer-token) - [Server Auth with JWT](#server-auth-with-jwt) [Client Credentials Grant](#client-credentials-grant) - [Obtaining Service Account token](#obtaining-service-account-token) - [Obtaining User token](#obtaining-user-token) [Traditional 3-Legged OAuth2](#traditional-3-legged-oauth2) - [Redirect to Authorization URL](#redirect-to-authorization-url) - [Authenticate (Get Token Pair)](#authenticate-get-token-pair) - [Initialize a Client Given Access and Refresh Token](#initialize-a-client-given-access-and-refresh-token) [Box View Authentication with App Tokens](#box-view-authentication-with-app-tokens) [As-User](#as-user) [Downscoping token](#downscoping-token) [Revoking Tokens](#revoking-tokens) ## Ways to Authenticate ### Developer Token The fastest way to get started using the API is with developer tokens. A developer token is simply a short-lived access token that cannot be refreshed and can only be used with your own account. Therefore, they're only useful for testing an app and aren't suitable for production. You can obtain a developer token from your application's [developer console](https://app.box.com/developers/console) page. For manual testing in a Python REPL, you can interactively create a [`DevelopmentClient`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.client.html#module-boxsdk.client.development_client). This client will prompt for a new developer token any time the current one expires, and will automatically log API requests and responses for testing and debugging. ``` >>> from boxsdk import DevelopmentClient >>> client = DevelopmentClient() Enter developer token: <ENTER DEVELOPER TOKEN HERE> >>> me = client.user().get() GET https://api.box.com/2.0/users/me {'headers': {'Authorization': '---wXyZ', 'User-Agent': 'box-python-sdk-2.0.0', 'X-Box-UA': 'agent=box-python-sdk/2.0.0; env=python/3.6.5'}, 'params': None} "GET https://api.box.com/2.0/users/me" 200 454 {'Date': 'Tue, 30 Oct 2018 20:57:36 GMT', 'Content-Type': 'application/json', 'Transfer-Encoding': 'chunked', 'Connection': 'keep-alive', 'Strict-Transport-Security': 'max-age=31536000', 'Cache-Control': 'no-cache, no-store', 'Content-Encoding': 'gzip', 'Vary': 'Accept-Encoding', 'BOX-REQUEST-ID': '0dnjcjpu1krfunto6s7mrpal2ba', 'Age': '0'} {'address': '', 'avatar_url': 'https://cloud.app.box.com/api/avatar/large/33333', 'created_at': '2012-06-07T11:14:50-07:00', 'id': '33333', 'job_title': '', 'language': 'en', 'login': 'user@example.com', 'max_upload_size': 16106127360, 'modified_at': '2018-10-29T12:13:57-07:00', 'name': 'Example User', 'phone': '', 'space_amount': 1000000000000000.0, 'space_used': 14330011102, 'status': 'active', 'timezone': 'America/Los_Angeles', 'type': 'user'} >>> ``` To create a [`Client`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.client.html#boxsdk.client.client.Client) non-interactively with a developer token, construct an [`OAuth2`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.auth.html#boxsdk.auth.oauth2.OAuth2) object with the `access_token` set to the developer token and construct the client with that. ``` from boxsdk import Client, OAuth2 auth = OAuth2( client_id='YOUR_CLIENT_ID', client_secret='YOUR_CLIENT_SECRET', access_token='DEVELOPER_TOKEN_GOES_HERE', ) client = Client(auth) me = client.user().get() print(f'My user ID is {me.id}') ``` ### Server Auth with JWT Authenticating with a JWT requires some extra dependencies. To get them, simply ``` pip install "boxsdk[jwt]" ``` Server auth allows your application to authenticate itself with the Box API for a given enterprise. By default, your application has a [Service Account](https://developer.box.com/en/guides/authentication/user-types/app-users/) that represents it and can perform API calls. The Service Account is separate from the Box accounts of the application developer and the enterprise admin of any enterprise that has authorized the app — files stored in that account are not accessible in any other account by default, and vice versa. If you generated your public and private keys automatically through the [Box Developer Console](https://app.box.com/developers/console), you can use the JSON file created there to configure your SDK instance and create a client to make calls as the Service Account by calling the appropriate static [`JWTAuth`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.auth.html#boxsdk.auth.jwt_auth.JWTAuth) method: ``` from boxsdk import JWTAuth, Client auth = JWTAuth.from_settings_file('/path/to/settings.json') client = Client(auth) service_account = client.user().get() print(f'Service Account user ID is {service_account.id}') ``` Otherwise, you'll need to provide the necessary configuration fields directly to the [`JWTAuth`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.auth.html#boxsdk.auth.jwt_auth.JWTAuth) constructor: ``` from boxsdk import JWTAuth, Client service_account_auth = JWTAuth( client_id='YOUR_CLIENT_ID', client_secret='YOUR_CLIENT_SECRET', enterprise_id='YOUR_ENTERPRISE_ID', jwt_key_id='YOUR_JWT_KEY_ID', rsa_private_key_file_sys_path='CERT.PEM', rsa_private_key_passphrase='PASSPHRASE', store_tokens=your_store_tokens_callback_method, ) access_token = auth.authenticate_instance() service_account_client = Client(auth) ``` App auth applications also often have associated App Users, which are [created and managed directly by the application](https://developer.box.com/en/guides/authentication/user-types/app-users/) — they do not have normal login credentials, and can only be accessed through the Box API by the application that created them. You may authenticate as the Service Account to provision and manage users, or as an individual app user to make calls as that user. See the [API documentation](https://developer.box.com/) for detailed instructions on how to use app auth. Clients for making calls as an App User can be created with the same [`JWTAuth`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.auth.html#boxsdk.auth.jwt_auth.JWTAuth) constructor as in the above examples, similarly to creating a Service Account client. Simply pass the [`User`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.user.User) object for the app user instead of an `enterprise_id` when constructing the auth instance: ``` app_user = service_account_client.user(user_id='APP_USER_ID') app_user_auth = JWTAuth( client_id='YOUR_CLIENT_ID', client_secret='YOUR_CLIENT_SECRET', user=app_user, jwt_key_id='YOUR_JWT_KEY_ID', rsa_private_key_file_sys_path='CERT.PEM', rsa_private_key_passphrase='PASSPHRASE', store_tokens=your_store_tokens_callback_method, ) app_user_auth.authenticate_user() app_user_client = Client(app_user_auth) ``` ### Client Credentials Grant Allows you to obtain an access token by having client credentials and secret with enterprise or user ID, which allows you to work using a service or user account. You can use `CCGAuth` to initialize a client object the same way as for other authentication types: ``` auth = CCGAuth( client_id="YOUR_CLIENT_ID", client_secret="YOUR_CLIENT_SECRET", user="YOUR_USER_ID" ) client = Client(auth) print(f'Id of the authenticated user is: {client.user().get().id}') ``` Obtained token is valid for specified amount of time, it will be refreshed automatically by default. #### Obtaining Service Account token The [Service Account](https://developer.box.com/guides/getting-started/user-types/service-account//) is separate from the Box accounts of the application developer and the enterprise admin of any enterprise that has authorized the app — files stored in that account are not accessible in any other account by default, and vice versa. To obtain service account you will have to provide enterprise ID with client id and secret: ``` auth = CCGAuth( client_id="YOUR_CLIENT_ID", client_secret="YOUR_CLIENT_SECRET", enterprise_id="YOUR_ENETRPRISE_ID" ) ``` Remember that you can still make calls on behalf of managed users, which are part of your enterprise, by using [As-User](#as-user) bahaviour. #### Obtaining User token To obtain user account you will have to provide user ID with client id and secret ``` auth = CCGAuth( client_id="YOUR_CLIENT_ID", client_secret="YOUR_CLIENT_SECRET", user="YOUR_USER_ID" ) ``` In order to enable obtaining user token you have to go to your application configuration that can be found [here](https://app.box.com/developers/console). In`Configuration` tab, in section `Advanced Features` select `Generate user access tokens`. Do not forget to re-authorize application if it was already authorized. ### Traditional 3-Legged OAuth2 If your application needs to integrate with existing Box users who will provide their login credentials to grant your application access to their account, you will need to go through the standard OAuth2 login flow. A detailed guide for this process is available in the [Authentication with OAuth API documentation](https://developer.box.com/en/guides/authentication/oauth2/). Using an auth code is the most common way of authenticating with the Box API for existing Box users, to integrate with their accounts. Your application must provide a way for the user to login to Box (usually with a browser or web view) in order to obtain an auth code. After a user logs in and grants your application access to their Box account, they will be redirected to your application's `redirect_uri` which will contain an auth code. This auth code can then be used along with your client ID and client secret to establish an API connection. #### Redirect to Authorization URL The first step in the process is to redirect the user to the Box Authorize URL, which you can generate (along with a CSRF token) by calling [`oauth.get_authorization_url(redirect_url)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.auth.html#boxsdk.auth.oauth2.OAuth2.get_authorization_url) with your application's redirect URL. ``` from boxsdk import OAuth2 oauth = OAuth2( client_id='YOUR_CLIENT_ID', client_secret='YOUR_CLIENT_SECRET', store_tokens=your_store_tokens_callback_method, ) auth_url, csrf_token = oauth.get_authorization_url('http://YOUR_REDIRECT_URL') # Redirect user to auth_url, where they will enter their Box credentials ``` The SDK will keep the tokens in memory for the duration of the Python script run, so you don't always need to pass `store_tokens`. #### Authenticate (Get Token Pair) If you navigate the user to the auth_url, the user will be redirected to `https://YOUR_REDIRECT_URL?code=YOUR_AUTH_CODE&state=CSRF_TOKEN` after they log in to Box. After getting the auth code, you will be able to exchange it for an access token and refresh token. The SDK handles all the work for you; all you need to do is call [`oauth.authenticate(auth_code)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.auth.html#boxsdk.auth.oauth2.OAuth2.authenticate) with the auth code pulled from the query parameters of the incoming URL: ``` from boxsdk import Client # Make sure that the csrf token you get from the `state` parameter # in the final redirect URI is the same token you get from the # get_authorization_url method to protect against CSRF vulnerabilities. assert 'THE_CSRF_TOKEN_YOU_GOT' == csrf_token access_token, refresh_token = oauth.authenticate('YOUR_AUTH_CODE') client = Client(oauth) ``` #### Initialize a Client Given Access and Refresh Token You can also instantiate a client given the access and refresh token. You first need to construct an [OAuth2](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.auth.html#boxsdk.auth.oauth2.OAuth2) object with the access and refresh token passed in. Once you have created the oauth object you then pass it into your [Client](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.client.html#boxsdk.client.client.Client) object to instantiate your client. Finally, you can begin making calls with your client. ``` from boxsdk import Client, OAuth2 oauth = OAuth2( client_id='YOUR_CLIENT_ID', client_secret='YOUR_CLIENT_SECRET', access_token='ACCESS_TOKEN', refresh_token='REFRESH_TOKEN', ) client = Client(oauth) user = client.user().get() print(f'User ID is {user.id}') ``` ### Box View Authentication with App Tokens [Box View](https://developer.box.com/en/guides/embed/box-view/) uses a long-lived access token that is generated from the [Box Developer Console](https://app.box.com/developers/console) to make API calls. These access tokens cannot be automatically refreshed from the SDK, and must be manually changed in your application code. To use the primary or secondary access token generated in the Developer Console, simply create a [`Client`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.client.html#boxsdk.client.client.Client) with that token: ``` from boxsdk import Client, OAuth2 auth = OAuth2( client_id='YOUR_CLIENT_ID', client_secret='', access_token='APP_ACCESS_TOKEN_GOES_HERE' ) client = Client(auth) ``` ## As-User The As-User header is used by enterprise admins to make API calls on behalf of their enterprise's users. This requires the API request to pass an `As-User: USER-ID` header. For more details see the [documentation on As-User](https://developer.box.com/en/guides/authentication/oauth2/as-user/). The following examples assume that the `client` has been instantiated with an access token belonging to an admin-level user or Service Account with appropriate privileges to make As-User calls. Calling the [`client.as_user(user)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.cloneable.Cloneable.as_user) method with the [`User`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.user.User) creates a new client to impersonate the provided user. All calls made with the new client will be made in context of the impersonated user, leaving the original client unmodified. ``` user_to_impersonate = client.user(user_id='USER_ID_GOES_HERE') user_client = client.as_user(user_to_impersonate) ``` ## Downscoping token You can downscope a client's access token for one with a lower scope, in order to restrict the permissions for a child client or to pass to a less secure location (e.g. a browser-based app). This is useful if you want to use the [Box UI Elements](https://developer.box.com/en/guides/embed/ui-elements/), since they generally do not need full read/write permissions to run. To exchange the token held by a client for a new token with only `item_preview` scope, restricted to a single file, suitable for the [Content Preview UI Element](https://developer.box.com/en/guides/embed/ui-elements/preview/), call [`client.downscope_token(scopes, item=None, additional_data=None)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.client.html#boxsdk.client.client.Client.downscope_token) with the scope(s) needed. This method returns a [`TokenResponse`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.auth.html#boxsdk.auth.oauth2.TokenResponse) object with the downscoped token information. ``` target_file = client.file(file_id='FILE_ID_HERE') token_info = client.downscope_token(['item_preview'], target_file) downscoped_client = Client( OAuth2( client_id=None, client_secret=None, access_token=token_info.access_token ) ) ``` But bear in mind that there is no way of refreshing this token, and you will need to add you own logic to do that. ## Revoking Tokens To revoke the tokens contained in an [`OAuth2`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.auth.html#boxsdk.auth.oauth2.OAuth2) instance, removing the ability to call the Box API, call [`oauth.revoke()`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.auth.html#boxsdk.auth.oauth2.OAuth2.revoke). ``` oauth.revoke() ``` --- ### Retention Policies **Type:** page | **Section:** Additional Resources Retention Policies A retention policy blocks permanent deletion of content for a specified amount of time. Admins can create retention… # Retention Policies A retention policy blocks permanent deletion of content for a specified amount of time. Admins can create retention policies and then later assign them to specific folders or their entire enterprise. To use this feature, you must have the manage retention policies scope enabled for your API key via your application management console. - [Create Retention Policy](#create-retention-policy) - [Get Retention Policy](#get-retention-policy) - [Update Retention Policy](#update-retention-policy) - [Get Enterprise Retention Policies](#get-enterprise-retention-policies) - [Get Retention Policy Assignments](#get-retention-policy-assignments) - [Assign Retention Policy](#assign-retention-policy) - [Get Retention Policy Assignment](#get-retention-policy-assignment) - [Delete Retention Policy Assignment](#delete-retention-policy-assignment) - [Get File Version Retention](#get-file-version-retention) - [Get File Version Retentions](#get-file-version-retentions) ## Create Retention Policy To create a new retention policy, call the [`retentionPolicies.create(name, type, action, options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/RetentionPolicies.html#create) method. ``` client.retentionPolicies.create( 'Tax Documents', client.retentionPolicies.policyTypes.INDEFINITE, client.retentionPolicies.dispositionActions.REMOVE_RETENTION) ).then(policy => { /* policy -> { type: 'retention_policy', id: '123456789', policy_name: 'Tax Documents', policy_type: 'indefinite', retention_length: 'indefinite', retention_type: 'modifiable', description: 'Policy to retain all reports', disposition_action: 'remove_retention', can_owner_extend_retention: false, status: 'active', are_owners_notified: true, custom_notification_recipients: [] assignment_counts: { enterprise: 0, folder: 1, metadata_template: 0 }, created_by: { type: 'user', id: '11111', name: 'Example User', login: 'user@example.com' }, created_at: '2015-05-01T11:12:54-07:00', modified_at: '2015-06-08T11:11:50-07:00' } */ }); ``` ## Get Retention Policy To retrieve information about a specific retention policy, call the [`retentionPolicies.get(policyID, options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/RetentionPolicies.html#get) method. ``` client.retentionPolicies.get('123456789').then((policy) => { /* policy -> { type: 'retention_policy', id: '123456789', policy_name: 'Tax Documents', policy_type: 'indefinite', retention_length: 'indefinite', retention_type: 'modifiable', description: 'Policy to retain all reports', disposition_action: 'remove_retention', can_owner_extend_retention: false, status: 'active', are_owners_notified: true, custom_notification_recipients: [] assignment_counts: { enterprise: 0, folder: 1, metadata_template: 0 }, created_by: { type: 'user', id: '11111', name: 'Example User', login: 'user@example.com' }, created_at: '2015-05-01T11:12:54-07:00', modified_at: '2015-06-08T11:11:50-07:00' } */ }); ``` ## Update Retention Policy To update or modify an existing retention policy, call the [`retentionPolicies.update(policyID, updates, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/RetentionPolicies.html#update) method where `updates` is the set of key-value pairs to be updated on the policy object. ``` client.retentionPolicies .update('123456789', { status: 'retired' }) .then((policy) => { /* policy -> { type: 'retention_policy', id: '123456789', policy_name: 'Tax Documents', policy_type: 'indefinite', retention_length: 'indefinite', retention_type: 'modifiable', description: 'Policy to retain all reports', disposition_action: 'remove_retention', can_owner_extend_retention: false, status: 'retired', are_owners_notified: true, custom_notification_recipients: [] assignment_counts: { enterprise: 0, folder: 1, metadata_template: 0 }, created_by: { type: 'user', id: '11111', name: 'Example User', login: 'user@example.com' }, created_at: '2015-05-01T11:12:54-07:00', modified_at: '2015-06-08T11:11:50-07:00' } */ }); ``` ## Get Enterprise Retention Policies To retrieve all of the retention policies for the given enterprise, call the [`retentionPolicies.getAll(options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/RetentionPolicies.html#getAll) method. ``` client.retentionPolicies.getAll({ policy_name: 'Tax' }).then((policies) => { /* policies -> { entries: [ { type: 'retention_policy', id: '123456789', name: 'Tax Documents' } ], limit: 100, next_marker: 'someMarkerString' } */ }); ``` ## Get Retention Policy Assignments To get a list of all retention policy assignments associated with a specified retention policy, call the [`retentionPolicies.getAssignments(policyID, options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/RetentionPolicies.html#getAssignments) method. ``` client.retentionPolicies .getAssignments('123456789', { type: 'folder' }) .then((assignments) => { /* assignments -> { entries: [ { type: 'retention_policy_assignment', id: '12345678' } ], limit: 100, next_marker: 'someMarkerString' } */ }); ``` ## Assign Retention Policy To assign a retention policy, call the [`retentionPolicies.assign(policyID, assignType, assignID, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/RetentionPolicies.html#assign) method. If assigning to an `enterprise`, no `assignID` should be provided. ``` client.retentionPolicies .assign('11111', 'folder', '22222') .then((assignment) => { /* assignment -> { type: 'retention_policy_assignment', id: '12345', retention_policy: { type: 'retention_policy', id: '11111', policy_name: 'Tax Documents' }, assigned_to: { type: 'folder', id: '22222' }, assigned_by: { type: 'user', id: '33333', name: 'Example User', login: 'user@example.com' }, assigned_at: '2015-07-20T14:28:09-07:00' } */ }); ``` ``` client.retentionPolicies.assign('98726345', 'enterprise', null, callback); ``` You can also assign a retention policy to a metadata template, with optional field filters. This will attach the retention policy to any items that have the specified metadata template applied. If the `filter_fields` option is provided, the retention policy will only apply to items with the specified value in the metadata field. **Note:** Currently, only one filter field can be specified, and only enum metadata fields are supported at this time. ``` var policyID = '1234'; // metadata template is specified by ID var metadataTemplate = 'cff6f515-5a92-4dca-b4b3-e401ef97cf76'; var options = { filter_fields: [ { // fields and enum values are specified by ID field: '7475b170-3d5e-4dec-b617-9cfd35ae1ecd', value: '59157d60-6fec-419c-b0cc-506391ff51b8', }, ], }; client.retentionPolicies .assign( policyID, client.retentionPolicies.assignmentTypes.METADATA, metadataTemplate, options ) .then((assignment) => { /* assignment -> { type: 'retention_policy_assignment', id: '12345', retention_policy: { type: 'retention_policy', id: '11111', policy_name: 'Tax Documents' }, assigned_to: { type: 'metadata_template', id: 'cff6f515-5a92-4dca-b4b3-e401ef97cf76' }, filter_fields: [ { field: '7475b170-3d5e-4dec-b617-9cfd35ae1ecd', value: '59157d60-6fec-419c-b0cc-506391ff51b8' } ] assigned_by: { type: 'user', id: '33333', name: 'Example User', login: 'user@example.com' }, assigned_at: '2015-07-20T14:28:09-07:00', start_date_field: 'upload_date' } */ }); ``` ## Get Retention Policy Assignment To retrieve information about a retention policy assignment, call the [`retentionPolicies.getAssignment(assignmentID, options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/RetentionPolicies.html#getAssignment) method. ``` client.retentionPolicies.getAssignment('12345').then((assignment) => { /* assignment -> { type: 'retention_policy_assignment', id: '12345', retention_policy: { type: 'retention_policy', id: '11111', policy_name: 'Tax Documents' }, assigned_to: { type: 'folder', id: '22222' }, assigned_by: { type: 'user', id: '33333', name: 'Example User', login: 'user@example.com' }, assigned_at: '2015-07-20T14:28:09-07:00' } */ }); ``` ## Delete Retention Policy Assignment To delete a retention policy assignment, call the [`retentionPolicies.deleteAssignment(assignmentID, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/RetentionPolicies.html#deleteAssignment) method. ``` client.retentionPolicies.deleteAssignment('12345') .then(() => { // deletion succeeded — no value returned }); ``` ## Get File Version Retention A file version retention is a record for a retained file version. To get information for a specific file version retention record, call the [`retentionPolicies.getFileVersionRetention(retentionID, options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/RetentionPolicies.html#getFileVersionRetention) method. ``` client.retentionPolicies.getFileVersionRetention('55555').then((retention) => { /* retention -> { type: 'file_version_retention', id: '55555', applied_at: '2015-08-06T22:02:24-07:00', disposition_at: '2016-08-06T21:45:28-07:00', winning_retention_policy: { type: 'retention_policy', id: '11111', policy_name: 'Tax Documents' }, file_version: { type: 'file_version', id: '44444', sha1: '4262d6250b0e6f440dca43a2337bd4621bad9136' }, file: { type: 'file', id: '33333', etag: '2' } } */ }); ``` ## Get File Version Retentions To retrieve a list of all file version retentions for the given enterprise or to filter for some category of file version retention records, call the [`retentionPolicies.getAllFileVersionRetentions(options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/RetentionPolicies.html#getAllFileVersionRetentions) method. Optional filters are passed via the `options` parameter. ``` // Get only the retention records set to delete items before a certain date var options = { disposition_action: client.retentionPolicies.dispositionActions.PERMANENTLY_DELETE, disposition_before: '2038-01-01T12:34:56-08:00', }; client.retentionPolicies .getAllFileVersionRetentions(options) .then((retentions) => { /* retentions -> { entries: [ { type: 'file_version_retention', id: '112725' }, { type: 'file_version_retention', id: '112729' }, { type: 'file_version_retention', id: '112733' } ], limit: 100, order: [ { by: 'file_version_id', direction: 'ASC' } ] } */ }); ``` ## Get Files Under Retention For Assignment To retrieve information about files under retention, call the [`retentionPolicies.getFilesUnderRetentionForAssignment(assignmentID, options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/RetentionPolicies.html#getFilesUnderRetentionForAssignment) method. ``` client.retentionPolicies .getFilesUnderRetentionForAssignment('12345') .then((files) => { /* files -> { entries: [ { id: 12345, etag: 1, type: 'file', sequence_id: 3, name: 'Contract.pdf', sha1: '85136C79CBF9FE36BB9D05D0639C70C265C18D37', file_version: { id: 123456, type: 'file_version', sha1: '134b65991ed521fcfe4724b7d814ab8ded5185dc', }, applied_at: '2012-12-12T10:53:43-08:00' } ], limit: 1000, marker: 'some marker' } */ }); ``` ## Get File Versions Under Retention For Assignment To retrieve information about files under retention, call the [`retentionPolicies.getFileVersionUnderRetentionForAssignment(assignmentID, options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/RetentionPolicies.html#getFileVersionUnderRetentionForAssignment) method. ``` client.retentionPolicies .getFilesVersionUnderRetentionForAssignment('12345') .then((fileVersions) => { /* fileVersions -> { entries: [ { id: 123456, etag: 1, type: 'file_version', sequence_id: 3, name: 'Contract.pdf', sha1: '85136C79CBF9FE36BB9D05D0639C70C265C18D37', file_version: { id: 1234567, type: 'file_version', sha1: '134b65991ed521fcfe4724b7d814ab8ded5185dc', }, applied_at: '2012-12-12T10:53:43-08:00' } ], limit: 1000, marker: 'some marker' } */ }); ``` --- ### Retention Policies **Type:** page | **Section:** Additional Resources Retention Policies A retention policy blocks permanent deletion of content for a specified amount of time. Admins can create retention… # Retention Policies A retention policy blocks permanent deletion of content for a specified amount of time. Admins can create retention policies and then later assign them to specific folders or their entire enterprise. [Create Retention Policy](#create-retention-policy) - [Indefinite Retention Policies](#indefinite-policies) - [Finite Retention Policies](#finite-policies) - [Optional parameters](#optional-parameters) [Get Retention Policy](#get-retention-policy) [Update Retention Policy](#update-retention-policy) [Get Retention Policies](#get-retention-policies) [Get Retention Policy Assignments](#get-retention-policy-assignments) [Create Retention Policy Assignment](#create-retention-policy-assignment) [Get Retention Policy Assignment](#get-retention-policy-assignment) [Delete Retention Policy Assignment](#delete-retention-policy-assignment) [Get File Version Retention](#get-file-version-retention) [Get File Version Retentions](#get-file-version-retentions) [Get Files Under Retention For Assignment](#get-files-under-retention-for-assignment) [Get File Versions Under Retention For Assignment](#get-file-versions-under-retention-for-assignment) [Extend retention for a file](#extend-retention-for-a-file) ## Create Retention Policy ### Indefinite policies The static [`createIndefinitePolicy(BoxAPIConnection api, String name)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxRetentionPolicy.html#createIndefinitePolicy-com.box.sdk.BoxAPIConnection-java.lang.String-) method will let you create a new indefinite retention policy with a specified name. ``` BoxRetentionPolicy.createIndefinitePolicy(api, name); ``` ### Finite policies The static [`BoxRetentionPolicy.createFinitePolicy(com.box.sdk.BoxAPIConnection, java.lang.String, int, com.box.sdk.BoxRetentionPolicy.BoxRetentionPolicyAction)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxRetentionPolicy.html#createFinitePolicy-com.box.sdk.BoxAPIConnection-java.lang.String-int-com.box.sdk.BoxRetentionPolicy.BoxRetentionPolicyAction-) method will let you create a new finite retention policy with a specified name, amount of time to apply the retention policy (in days) and a disposition action. ``` BoxRetentionPolicy.createFinitePolicy(api, name, length, PermanentlyDelete); ``` ### Optional parameters Both finite and indefinite policies allow you to specify optional parameters using the [`RetentionPolicyParams`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/RetentionPolicyParams.html) object. ``` String notifiedUserID = "12345"; String description = "Policy to retain all reports"; RetentionPolicyParams optionalParams = new RetentionPolicyParams(); optionalParams.setCanOwnerExtendRetention(true); optionalParams.setAreOwnersNotified(true); optionalParams.setDescription(description); optionalParams.addCustomNotificationRecipient(notifiedUserID); // Create indefinite policy with optional parameters BoxRetentionPolicy.createIndefinitePolicy(api, "Retain Stuff Forever", optionalParams); // Create finite policy with optional parameters BoxRetentionPolicy.createFinitePolicy(api, "Keep One Year", 365, BoxRetentionPolicyAction.RemoveRetention, optionalParams); ``` ## Get Retention Policy Calling [`getInfo(String... fields)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxRetentionPolicy.html#getInfo-java.lang.String...-) will return a [`BoxRetentionPolicy.Info'][retention-policy-info] object containing information about the retention policy. If necessary to retrieve limited set of fields, it is possible to specify them using the `fields` parameter. ``` // Get the policy name and status for a given retention policy BoxRetentionPolicy policy = new BoxRetentionPolicy(api, id); policy.getInfo("policy_name", "status"); ``` ## Update Retention Policy Updating a retention policy's information is done by calling [`updateInfo(BoxRetentionPolicy.Info fieldsToUpdate)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxRetentionPolicy.html#updateInfo-com.box.sdk.BoxRetentionPolicy.Info-). ``` BoxRetentionPolicy policy = new BoxRetentionPolicy(api, id); BoxRetentionPolicy.Info policyInfo = policy.new Info(); policyInfo.setPolicyName("new policy name"); policy.updateInfo(policyInfo); ``` ## Get Retention Policies Calling the static [`getAll(BoxAPIConnection api, String... fields)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxRetentionPolicy.html#getAll-com.box.sdk.BoxAPIConnection-java.lang.String...-) will return an iterable that will page through all of the retention policies. It is possible to specify filter for the name of retention policy, filter for the type of the policy, filter for the id of user, limit of items per single response and fields to retrieve by calling the static [`getAll(String name, String type, String userID, int limit, BoxAPIConnection api, String... fields)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxRetentionPolicy.html#getAll-java.lang.String-java.lang.String-java.lang.String-int-com.box.sdk.BoxAPIConnection-java.lang.String...-) method. ``` Iterable<BoxRetentionPolicy.Info> policies = BoxRetentionPolicy.getAll(api); for (BoxRetentionPolicy.Info policyInfo : policies) { // Do something with the retention policy. } ``` ## Get Retention Policy Assignments Calling [`getAllAssignments(String... fields)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxRetentionPolicy.html#getAllAssignments-java.lang.String...-) will return an iterable that will page through all of the assignments of the retention policy. It is possible to specify maximum number of items per single response and fields to retrieve by calling [`getAllAssignments(int limit, String... fields)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxRetentionPolicy.html#getAllAssignments-int-java.lang.String...-). If it is necessary to retrieve only assignments of certain type, you can call [`getFolderAssignments(int limit, String... fields)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxRetentionPolicy.html#getFolderAssignments-int-java.lang.String...-) or [`getEnterpriseAssignments(int limit, String... fields)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxRetentionPolicy.html#getEnterpriseAssignments-int-java.lang.String...-). ``` BoxRetentionPolicy policy = new BoxRetentionPolicy(api, id); Iterable<BoxRetentionPolicyAssignment.Info> allAssignments = policy.getAllAssignments("assigned_by"); Iterable<BoxRetentionPolicyAssignment.Info> folderAssignments = policy.getFolderAssignments(50, "assigned_by"); Iterable<BoxRetentionPolicyAssignment.Info> enterpriseAssignments = policy.getEnterpriseAssignments(); for (BoxRetentionPolicyAssignments.Info assignmentInfo : allAssignments) { // Do something with the assignment. } for (BoxRetentionPolicyAssignments.Info assignmentInfo : folderAssignments) { // Do something with the assignment. } for (BoxRetentionPolicyAssignments.Info assignmentInfo : enterpriseAssignments) { // Do something with the assignment. } ``` ## Create Retention Policy Assignment To create new retention policy assignment call [`assignTo(BoxFolder target)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxRetentionPolicy.html#assignTo-com.box.sdk.BoxFolder-) method to assign the policy to a specific folder, [`assignToEnterprise()`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxRetentionPolicy.html#assignToEnterprise--) to assign the retention policy to the entire enterprise, or [`assignToMetadataTemplate(String templateID, String startDateField, MetadataFieldFilter... filterFields)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxRetentionPolicy.html#assignToMetadataTemplate-java.lang.String-com.box.sdk.MetadataFieldFilter-) to assign the policy to items with a specific metadata template. ``` // Assign the policy to the entire enterprise BoxRetentionPolicy policy = new BoxRetentionPolicy(api, policyID); policy.assignToEnterprise(); // Assign the policy to a single folder BoxFolder folder = new BoxFolder(api, folderID); policy.assignTo(folderID); // Assign the policy to all items with metadata template String metadataTemplateID = "f0dce190-8106-43ca-9d67-7dce9b10a55e"; policy.assignToMetadataTemplate(metadataTemplateID); // You can also pass an optional `startDateField` parameter containing the ID of the metadata template's `date` field String dateFieldID = "fb523725-04b1-4502-b871-eac305274533"; policy.assignToMetadataTemplate(metadataTemplateID, dateFieldID); ``` ## Get Retention Policy Assignment Calling [`getInfo(String... fields)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxRetentionPolicyAssignment.html#getInfo-java.lang.String...-) will return a [`BoxRetentionPolicyAssignment.Info`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxRetentionPolicyAssignment.Info.html) object containing information about the retention policy assignment. ``` BoxRetentionPolicyAssignment assignment = new BoxRetentionPolicyAssignment(api, id); BoxRetentionPolicyAssignment.Info assignmentInfo = assignment.getInfo("assigned_to"); ``` ## Delete Retention Policy Assignment To delete Retention Policy Assignment call [`delete()`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxRetentionPolicyAssignment.html#delete()) method. ``` BoxRetentionPolicyAssignment assignment = new BoxRetentionPolicyAssignment(api, id); assignment.delete(); ``` ## Get File Version Retention Calling [`getInfo(String... fields)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFileVersionRetention.html#getInfo-java.lang.String...-) will return a [`BoxFileVersionRetention.Info`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFileVersionRetention.Info.html) object containing information about the file version retention policy. ``` BoxFileVersionRetention policy = new BoxFileVersionRetention(api, id); BoxFileVersionRetention.Info policyInfo = policy.getInfo(); ``` ## Get File Version Retentions To get an iterable with all file version retentions for the current retention policy, call the static [`getAll(BoxAPIConnection api, String... fields)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFileVersionRetention.html#getAll-com.box.sdk.BoxAPIConnection-java.lang.String...-) method. It is possible to add filters to query passing a [`BoxFileVersionRetention.QueryFilter`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFileVersionRetention.QueryFilter.html) object as a parameter to [`getRetentions(BoxAPIConnection api, BoxFileVersionRetention.QueryFilter filter, String... fields)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFileVersionRetention.html#getRetentions-com.box.sdk.BoxAPIConnection-com.box.sdk.BoxFileVersionRetention.QueryFilter-java.lang.String...-). ``` BoxFileVersionRetention.QueryFilter filter = new BoxFileVersionRetention.QueryFilter() .addFileID("0") .addFileVersionID("1") .addPolicyID("2") .addDispositionAction(BoxRetentionPolicy.ACTION_PERMANENTLY_DELETE) .addDispositionBefore(BoxDateFormat.parse("2016-09-15T13:15:35+0000")) .addDispositionAfter(BoxDateFormat.parse("2014-09-15T13:15:35+0000")); Iterable<BoxFileVersionRetention.Info> retentions = BoxFileVersionRetention.getRetentions(api, filter, "file", "applied_at"); for (BoxFileVersionRetention.Info retentionInfo : retentions) { // Do something with the file version retention. } ``` ## Get Files Under Retention For Assignment To get an iterable with all files under retention for assignment policy, call the [`getFilesUnderRetention(BoxAPIConnection api, int limit, String... fields)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxRetentionPolicyAssignment.html#getFilesUnderRetention-com.box.sdk.BoxAPIConnection-java.lang.String...-) method. This will return an interable with [`BoxFile.Info`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFile.Info.html) objects containing information about the files. ``` BoxRetentionPolicyAssignment policyAssignment = new BoxRetentionPolicyAssignment(api, id); Iterable<BoxFile.Info> filesUnderRetention = policyAssignment.getFilesUnderRetention(); for (BoxFile.Info item : filesUnderRetention){ // Do something with the files under retention. } ``` ## Get File Versions Under Retention For Assignment To get an iterable with all file versions under retention for assignment policy, call the [`getFileVersionsUnderRetention(BoxAPIConnection api, int limit, String... fields)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxRetentionPolicyAssignment.html#getFileVersionsUnderRetention-com.box.sdk.BoxAPIConnection-java.lang.String...-) method. This will return an interable with [`BoxFile.Info`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFile.Info.html) objects containing information about the file. You can get version by calling [`BoxFile.Info#getVersion()`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFileVersion.html). ``` BoxRetentionPolicyAssignment policyAssignment = new BoxRetentionPolicyAssignment(api, id); Iterable<BoxFile.Info> fileVersionsUnderRetention = policyAssignment.getFileVersionsUnderRetention(); for (BoxFile.Info file : fileVersionsUnderRetention){ BoxFileVersion version = file.getVersion(); // Do something with the file version under retention. } ``` ## Extend retention for a file Once you create retention policy and assign it to a folder all files and subfolders will have same policy applied. If you need to extend retention for some file you can change it's `dispositionAt` value: ``` BoxFile.Info info = someFile.getInfo(); // to read current disposition date coming from retention policy BoxFile.Info info = someFile.getInfo("disposition_at"); Date currentDispositionDate = info.getDispositionAt(); // calculate new disposition date Date dispositionAt = Date.from( LocalDateTime.ofInstant(currentDispositionDate.toInstant(), ZoneId.of("Z")) .plusDays(30) .toInstant(UTC) ); // to change disposition date on a file you need to updateInfo info.setDispositionAt(dispositionAt); uploadedFile.updateInfo(info); ``` --- ### Retention Policies **Type:** page | **Section:** Additional Resources Retention Policies A retention policy blocks permanent deletion of content for a specified amount of time. Admins can create retention… # Retention Policies A retention policy blocks permanent deletion of content for a specified amount of time. Admins can create retention policies and then later assign them to specific folders or their entire enterprise. - [Create Retention Policy](#create-retention-policy) - [Get Retention Policy](#get-retention-policy) - [Get Retention Policies](#get-retention-policies) - [Update Retention Policy](#update-retention-policy) - [Assign Retention Policy](#assign-retention-policy) - [Get Retention Policy Assignment](#get-retention-policy-assignment) - [Get Retention Policy Assignments](#get-retention-policy-assignments) - [Get File Version Retentions](#get-file-version-retentions) (deprecated, use [Get Files under Retention for a Retention Policy Assignment](#get-files-under-retention-for-an-assignment) and [Get File Versions under Retention for a Retention Policy Assignment](#get-file-versions-under-retention-for-an-assignment) instead) - [Get Information about a File Version Retention](#get-information-about-a-file-version-retention) - [Get Files under Retention for a Retention Policy Assignment](#get-files-under-retention-for-a-retention-policy-assignment) - [Get File Versions under Retention for a Retention Policy Assignment](#get-file-versions-under-retention-for-a-retention-policy-assignment) ## Create Retention Policy To create a retention policy object, call [`client.create_retention_policy(policy_name, disposition_action, retention_length, can_owner_extend_retention=None, are_owners_notified=None, custom_notification_recipients=None)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.client.html#boxsdk.client.client.Client.create_retention_policy). This will let you create a new indefinite [`RetentionPolicy`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.retention_policy.RetentionPolicy) object populated with data from the API. ``` policy_name = 'Test Indefinite Policy Name' disposition_action = 'remove_retention' indefinite_retention_policy = client.create_retention_policy(policy_name, disposition_action, float('inf')) print(f'Indefinite Retention Policy ID is {indefinite_retention_policy.id} and the policy name is {indefinite_retention_policy.policy_name}') ``` Alternatively, if you want to create a finite retention policy, you can do so by calling [`client.create_retention_policy(policy_name, disposition_action, retention_length=5)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.client.html#boxsdk.client.client.Client.create_retention_policy) ``` policy_name = 'Test Finite Policy Name' disposition_action = 'remove_retention' retention_length = 5 finite_retention_policy = client.create_retention_policy(policy_name=policy_name, disposition_action=disposition_action, retention_length=retention_length) print(f'Finite Retention Policy ID is {finite_retention_policy.id} and the policy name is {finite_retention_policy.policy_name}') ``` ## Get Retention Policy To get a retention policy object, first call [`client.retention_policy(retention_id)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.client.html#boxsdk.client.client.Client.retention_policy) to construct the appropriate [`RetentionPolicy`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.retention_policy.RetentionPolicy) object, and then calling [`retention_policy.get(*, fields=None, headers=None, **kwargs)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.base_object.BaseObject.get) will return the [`RetentionPolicy`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.retention_policy.RetentionPolicy) object populated with data from the API. ``` retention_policy = client.retention_policy(retention_id='12345').get() print(f'Retention Policy ID is {retention_policy.id} and the name is {retention_policy.policy_name}') ``` ## Get Retention Policies To retrieve all retention policies for an enterprise, call [`client.get_retention_policies`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.client.html#boxsdk.client.client.Client.get_retention_policies). This method returns a `BoxObjectCollection` that allows you to iterate over the [`Retention Policy`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.retention_policy.RetentionPolicy) objects in the collection. ``` retention_policies = client.get_retention_policies() for policy in retention_policies: print(f'The policy ID is {policy.id} and the name is {policy.policy_name}') ``` ## Update Retention Policy To update a retention policy object, calling [`retention_policy.update_info(data=policy_update)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.base_object.BaseObject.update_info) with a `dict` of properties to update on the retention policy. This method returns a newly updates [`RetentionPolicy`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.retention_policy.RetentionPolicy) object, leaving the original object unmodified. ``` policy_update = {'policy_name': 'New Policy Name',} updated_retention_policy = client.retention_policy(retention_id='12345').update_info(data=policy_update) print(f'Retention Policy ID is {updated_retention_policy.id} and the new policy name is {updated_retention_policy.policy_name}') ``` ## Assign Retention Policy To assign a retention policy, call [`retention_policy.assign(folder)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.retention_policy.RetentionPolicy.assign) will create a new [`RetentionPolicyAssignment`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.retention_policy_assignment.RetentionPolicyAssignment) object populated with data from the API. ``` folder = client.folder(folder_id='1111') assignment = client.retention_policy(retention_id='12345').assign(folder) print(f'Assignment ID is {assignment.id} and it is assigned by {assignment.assigned_by.name}') ``` ## Get Retention Policy Assignment To get a retention policy object, first call [`client.retention_policy_assignment(assignment_id)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.client.client.Client.retention_policy_assignment) to construct the appropriate [`Retention Policy Assignment`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.retention_policy_assignment.RetentionPolicyAssignment) object, and then calling [`retention_policy_assignment.get(*, fields=None, headers=None, **kwargs)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.base_object.BaseObject.get) will return the [`Retention Policy Assignment`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.retention_policy_assignment.RetentionPolicyAssignment) object populated with data from the API. ``` assignment = client.retention_policy_assignment('12345').get() print(f'Assignment id is {assignment.id} and it is assigned by {assignment.assigned_by.name}') ``` ## Get Retention Policy Assignments To retrieve all retention policy assignments for an enterprise, call [`retention_policy.assignments(assignment_type=None, limit=None, marker=None, fields=None)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.retention_policy.assignments) will return a `BoxObjectCollection` that allows you to iterate over the [`RetentionPolicyAssignment`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.retention_policy_assignment.RetentionPolicyAssignment) objects in the collection. ``` assignments = client.retention_policy(retention_id='12345').assignments(limit=10) for assignment in assignments: print(f'Assignment ID is {assignment.id} and it is assigned by {assignment.assigned_by.name}') ``` Alternatively, you can also specify the `type` of assignment to retrieve with [`retention_policy.assignments(assignment_type='folder')`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.retention_policy.assignments). ``` assignments = client.retention_policy(retention_id='12345').assignments(assignment_type='folder', limit=10) for assignment in assignments: print(f'Assignment ID is {assignment.id} and it is assigned by {assignment.assigned_by.name}') ``` ## Get File Version Retentions To retrieve all file version retentions, call [`client.get_file_version_retentions(target_file=None, file_version=None, policy=None, disposition_action=None, disposition_before=None, disposition_after=None, limit=None, marker=None, fields=None)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.client.html#boxsdk.client.client,Client.get_file_version_retentions). This method will return a `BoxObjectCollection` that allows you to iterate over the [`FileVersionRetention`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.file_version_retention.FileVersionRetention) objects in the collection. ``` retentions = client.get_file_version_retentions() for retention in retentions: print(f'The file version retention ID is {retention.id} and the data time applied at is {retention.applied_at}') ``` ## Get Information about a File Version Retention To get a file version retention object, first call [`client.file_version_retention(retention_id)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.client.html#boxsdk.client.client.Client.file_version_retention) to construct the appropriate [`File Version Retention`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.file_version_retention.FileVersionRetention) object, and then calling [`file_version_retention.get(*, fields=None, headers=None, **kwargs)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.base_object.BaseObject.get) will return the [`FileVersionRetention`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.client.html#boxsdk.client.client.Client.file_version_retention) object populated with data from the API. ``` retention_info = client.file_version_retention(retention_id='12345').get() print(f'The file version retention ID is {retention.id} and the data time applied at is {retention.applied_at}') ``` ## Get Files under Retention for a Retention Policy Assignment To retrieve all files under retention for a Retention Policy Assignment, call [`retention_policy_assignment.get_files_under_retention(limit=None, marker=None)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#module-boxsdk.object.retention_policy_assignment). This method will return a `MarkerBasedObjectCollection` that allows you to iterate over the [`File`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#module-boxsdk.object.file) objects in the collection. ``` retention_policy_assignment = client.retention_policy_assignment(assignment_id='12345').get() files_under_retention = retention_policy_assignment.get_files_under_retention() for file in files_under_retention: print(f'The file with ID {file.object_id} and name {file.name} is under retention for a retention policy assignment with ID {retention_policy_assignment.object_id}') ``` ## Get File Versions under Retention for a Retention Policy Assignment To retrieve all file versions under retention for a retention policy assignment, call [`retention_policy_assignment.get_file_versions_under_retention(limit=None, marker=None)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#module-boxsdk.object.retention_policy_assignment). This method will return a `MarkerBasedObjectCollection` that allows you to iterate over the [`FileVersion`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#module-boxsdk.object.file_version) objects in the collection. ``` retention_policy_assignment = client.retention_policy_assignment(assignment_id='12345').get() file_versions_under_retention = retention_policy_assignment.get_file_versions_under_retention() for file_version in file_versions_under_retention: print(f'The version {file_version.file_version.object_id} of {file_version.name} file is under retention for a retention policy assignment with ID {retention_policy_assignment.object_id}') ``` --- ### Retention Policies **Type:** page | **Section:** Additional Resources Retention Policies A retention policy blocks permanent deletion of content for a specified amount of time. Admins can create retention… # Retention Policies A retention policy blocks permanent deletion of content for a specified amount of time. Admins can create retention policies and then later assign them to specific folders or their entire enterprise. To use this feature, you must have the manage retention policies scope enabled for your API key via your application management console. - [Create Retention Policy](#create-retention-policy) - [Get Retention Policy](#get-retention-policy) - [Update Retention Policy](#update-retention-policy) - [Get Enterprise Retention Policies](#get-enterprise-retention-policies) - [Get Retention Policy Assignments](#get-retention-policy-assignments) - [Assign Retention Policy](#assign-retention-policy) - [Get Retention Policy Assignment](#get-retention-policy-assignment) - [Get File Version Retention](#get-file-version-retention) - [Get File Version Retentions](#get-file-version-retentions) (will be deprecated in the future, use [Get Files Under Retention For Assignment](#get-files-under-retention-for-assignment) and [Get File Version Under Retention For Assignment](#get-file-versions-under-retention-for-assignment) instead) - [Get Files Under Retention For Assignment](#get-files-under-retention-for-assignment) - [Get File Version Under Retention For Assignment](#get-file-versions-under-retention-for-assignment) ## Create Retention Policy To create a new retention policy, call `RetentionPoliciesManager.CreateRetentionPolicyAsync(BoxRetentionPolicyRequest retentionPolicyRequest)` with the parameters for the new retention policy. ``` var policyParams = new BoxRetentionPolicyRequest() { PolicyName = "Important Documents!", PolicyType = "finite", RetentionLength = 365, DispositionAction = "remove_retention" }; BoxRetentionPolicy policy = await client.RetentionPoliciesManager .CreateRetentionPolicyAsync(policyParams); ``` ## Get Retention Policy To retrieve information about a specific retention policy, call `RetentionPoliciesManager.GetRetentionPolicyAsync(string id, IEnumerable<string> fields = null)` with the ID of the policy. ``` BoxRetentionPolicy policy = await client.RetentionPoliciesManager.GetRetentionPolicyAsync("11111"); ``` ## Update Retention Policy To update or modify an existing retention policy, call `RetentionPoliciesManager.UpdateRetentionPolicyAsync(string id, BoxRetentionPolicyRequest retentionPolicyRequest, IEnumerable<string> fields = null)` with the ID of the policy to update and the set of fields to update. ``` var updates = new BoxRetentionPolicyRequest() { PolicyName = "New Policy Name" }; BoxRetentionPolicy updatedPolicy = await client.RetentionPoliciesManager .UpdateRetentionPolicyAsync("11111", updates); ``` ## Get Enterprise Retention Policies To retrieve all of the retention policies for the given enterprise, call `RetentionPoliciesManager.GetRetentionPoliciesAsync(string policyName = null, string policyType = null, string createdByUserId = null, IEnumerable<string> fields = null, int limit = 100, string marker = null, bool autoPaginate = false)`. ``` BoxCollectionMarkerBased<BoxRetentionPolicy> policies = await client.RetentionPoliciesManager .GetRetentionPoliciesAsync(); ``` ## Get Retention Policy Assignments To get a list of all retention policy assignments associated with a specified retention policy, call `RetentionPoliciesManager.GetRetentionPolicyAssignmentsAsync(string retentionPolicyId, string type = null, IEnumerable<string> fields = null, int limit = 100, string marker = null, bool autoPaginate = false)` with the ID of the policy to get asisgnments for. ``` BoxCollectionMarkerBased<BoxRetentionPolicyAssignment> assignments = await client.RetentionPoliciesManager .GetRetentionPolicyAssignmentsAsync(retentionPolicyId: "11111"); ``` ## Assign Retention Policy To assign a retention policy, call `RetentionPoliciesManager.CreateRetentionPolicyAssignmentAsync(BoxRetentionPolicyAssignmentRequest policyAssignmentRequest, IEnumerable<string> fields = null)` with the parameters of the assignment. ``` var assignmentParams = new BoxRetentionPolicyAssignmentRequest() { PolicyId = "11111", AssignTo = new BoxRequestEntity() { Type = BoxType.folder, Id = "22222" } }; BoxRetentionPolicyAssignment assignment = await client.RetentionPoliciesManager .CreateRetentionPolicyAssignmentAsync(assignmentParams); ``` ## Get Retention Policy Assignment To retrieve information about a retention policy assignment, call `RetentionPoliciesManager.GetRetentionPolicyAssignmentAsync(string retentionPolicyAssignmentId, IEnumerable<string> fields = null)` with the ID of the assignment. ``` BoxRetentionPolicyAssignment assignment = await client.RetentionPoliciesManager .GetRetentionPolicyAssignmentAsync("33333"); ``` ## Get File Version Retention A file version retention is a record for a retained file version. To get information for a specific file version retention record, call the `RetentionPoliciesManager.GetFileVersionRetentionAsync(string fileVersionRetentionId, IEnumerable<string> fields = null)` method with the ID of the retention object. ``` BoxFileVersionRetention retention = await client.RetentionPoliciesManager .GetFileVersionRetentionAsync("55555"); ``` ## Get File Version Retentions To retrieve a list of all file version retentions for the given enterprise or to filter for some category of file version retention records, call `RetentionPoliciesManager.GetFileVersionRetentionsAsync(IEnumerable<string> fields = null, int limit = 100, string marker = null, bool autoPaginate = false, string fileId = null, string fileVersionId = null, string policyId = null, DateTime? dispositionBefore = null, DateTime? dispositionAfter = null, DispositionAction? dispositionAction = null)`. ``` BoxCollectionMarkerBased<BoxFileVersionRetention> retentions = await client.RetentionPoliciesManager .GetFileVersionRetentionsAsync(); ``` ## Get Files Under Retention For Assignment To retrieve a list of all files under retention for assignment, call `RetentionPoliciesManager.GetFilesUnderRetentionForAssignmentAsync(string retentionPolicyAssignmentId, IEnumerable<string> fields = null, int limit = 100, string marker = null, bool autoPaginate = false)`. ``` BoxCollectionMarkerBased<BoxFile> filesUnderRetentionForAssignment = await client.RetentionPoliciesManager .GetFilesUnderRetentionForAssignmentAsync("55555"); ``` ## Get File Versions Under Retention For Assignment To retrieve a list of all file versions under retention for assignment, call `RetentionPoliciesManager.GetFileVersionsUnderRetentionForAssignmentAsync(string retentionPolicyAssignmentId, IEnumerable<string> fields = null, int limit = 100, string marker = null, bool autoPaginate = false)`. ``` BoxCollectionMarkerBased<BoxFileVersion> fileVersionsUnderRetentionForAssignment = await client.RetentionPoliciesManager .GetFileVersionsUnderRetentionForAssignmentAsync("55555"); ``` --- ### Retention Policies **Type:** page | **Section:** Additional Resources Retention Policies A retention policy blocks permanent deletion of content for a specified amount of time. Admins can create retention… # Retention Policies A retention policy blocks permanent deletion of content for a specified amount of time. Admins can create retention policies and then later assign them to specific folders or their entire enterprise. To use this feature, you must have the manage retention policies scope enabled for your API key via your application management console. - [Create Retention Policy](#create-retention-policy) - [Update Retention Policy](#update-retention-policy) - [Get Retention Policy](#get-retention-policy) - [Get Retention Policies](#get-retention-policies) - [Create Retention Policy Assignment](#create-retention-policy-assignment) - [Get Retention Policy Assignment](#get-retention-policy-assignment) - [Get Retention Policy Assignments](#get-retention-policy-assignments) - [Delete Retention Policy Assignment](#delete-retention-policy-assignment) - [Get File Version Retention](#get-file-version-retention) - [Get File Version Retentions](#get-file-version-retentions) (will be deprecated in the future, use [Get Files Under Retention For Assignment](#get-files-under-retention-for-assignment) and [Get File Version Under Retention For Assignment](#get-file-versions-under-retention-for-assignment) instead) - [Get Files Under Retention For Assignment](#get-files-under-retention-for-assignment) - [Get File Version Under Retention For Assignment](#get-file-versions-under-retention-for-assignment) ## Create Retention Policy To create a retention policy, call [`client.retentionPolicy.create(name:type:length:dispositionAction:canOwnerExtendRetention:areOwnersNotified:customNotificationRecipients:retentionType:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/RetentionPoliciesModule.html#/s:6BoxSDK23RetentionPoliciesModuleC6create4name4type6length17dispositionAction014canOwnerExtendC017areOwnersNotified28customNotificationRecipients13retentionType10completionySS_AA0c6PolicyV0OSiSgAA011DispositionK0OSbSgASSayAA4UserCGSgAA0cV0OSgys6ResultOyAA0cX0CAA0A8SDKErrorCGctF). You can create either a `indefinite` retention policy, or a `finite`. To create a `indefinite` retention policy, you must set a `type` to `.indefinite` and a `dispositionAction` to `.removeRetention`. ``` client.retentionPolicy.create( name: "Test Indefinite Policy Name", type: .indefinite, dispositionAction: .removeRetention ) { result in guard case let .success(retentionPolicy) = result else { print("Error creating retention policy") return } print("Retention policy: \(retentionPolicy.id) was created") } ``` To create a `finite` retention policy, you must set `type` to `.finite`, set amount of time in days to apply the retention policy (`length`) and a `dispositionAction`. The disposition action can be `.permanentlyDelete` or `.removeRetention`. ``` client.retentionPolicy.create( name: "Test Finite Policy Name", type: .finite, length: 60, dispositionAction: .permanentlyDelete ) { result in guard case let .success(retentionPolicy) = result else { print("Error creating retention policy") return } print("Retention policy: \(retentionPolicy.id) was created") } ``` ## Update Retention Policy To update a retention policy, call [`client.retentionPolicy.update(policyId:name:dispositionAction:status:setRetentionTypeToNonModifiable:length:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/RetentionPoliciesModule.html#/s:6BoxSDK23RetentionPoliciesModuleC6update8policyId4name17dispositionAction6status03setC19TypeToNonModifiable6length10completionySS_SSSgAA011DispositionK0OSgAA0C12PolicyStatusOSgSbSiSgys6ResultOyAA0cU0CAA0A8SDKErrorCGctF). ``` client.retentionPolicy.update(policyId: "1234", name: "New Policy Name") { result in guard case let .success(retentionPolicy) = result else { print("Error updating a retention policy") return } print("Updated retention policy: \(retentionPolicy.id)") } ``` ## Get Retention Policy To retrieve information about a retention policy, call [`client.retentionPolicy.get(policyId:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/RetentionPoliciesModule.html#/s:6BoxSDK23RetentionPoliciesModuleC3get8policyId10completionySS_ys6ResultOyAA0C6PolicyCAA0A8SDKErrorCGctF) with the ID of the retention policy. ``` client.retentionPolicy.get(policyId: "1234") { result in guard case let .success(retentionPolicy) = result else { print("Error getting retention policy") return } print("Retention policy: \(retentionPolicy.id)") } ``` ## Get Retention Policies To retrieve all retention policies for an enterprise, call [`client.retentionPolicy.list(name:type:createdByUserId:marker:limit:)`](https://opensource.box.com/box-ios-sdk/Classes/RetentionPoliciesModule.html#/s:6BoxSDK23RetentionPoliciesModuleC4list4name4type15createdByUserId6marker5limitAA14PagingIteratorCyAA0C11PolicyEntryCGSSSg_AA0cQ4TypeOSgA2OSiSgtF). This method will return an iterator, which is used to get the policies. As you can see in the method signature, it is possible to specify filter for the name, type and created user of the retention policy. All of mentioned fields are optional and if not set, all retention policies will be returned. You can also set a number of items per single response by setting a limit. ``` let iterator = client.retentionPolicy.list(type: .indefinite) iterator.next { results in switch results { case let .success(page): for policy in page.entries { print("Retention policy \(policy.id)") } case let .failure(error): print(error) } } ``` ## Create Retention Policy Assignment To create new retention policy assignment call [`client.retentionPolicy.assign(policyId:assignedContentId:assignContentType:filterFields:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/RetentionPoliciesModule.html#/s:6BoxSDK23RetentionPoliciesModuleC6assign8policyId015assignedContentH00fJ4Type12filterFields10completionySS_SSAA0c20PolicyAssignmentItemK0OSayAA19MetadataFieldFilterVGSgys6ResultOyAA0coP0CAA0A8SDKErrorCGctF) method to assign the policy. Retention policy can be assigned to a specific folder, to a metadata template or to the entire enterprise. ``` client.retentionPolicy.assign(policyId: "12345", assignedContentId: "1111", assignContentType: .folder) { result in guard case let .success(retentionPolicyAssignment) = result else { print("Error creating retention policy assignment") return } print("Retention policy assignment: \(retentionPolicyAssignment.id) was created") } ``` ## Get Retention Policy Assignment To retrieve information about a retention policy assignment, call [`client.retentionPolicy.getAssignment(assignmentId:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/RetentionPoliciesModule.html#/s:6BoxSDK23RetentionPoliciesModuleC13getAssignment12assignmentId10completionySS_ys6ResultOyAA0c6PolicyG0CAA0A8SDKErrorCGctF) with the ID of the assignment. ``` client.retentionPolicy.getAssignment(assignmentId: "123456") { result in guard case let .success(retentionPolicyAssignment) = result else { print("Error getting retention policy assignment") return } print("Retention policy assignment: \(retentionPolicyAssignment.id)") } ``` ## Get Retention Policy Assignments To get a list of all retention policy assignments associated with a specified retention policy, call [`client.retentionPolicy.listAssignments(policyId:type:marker:limit:fields)`](https://opensource.box.com/box-ios-sdk/Classes/RetentionPoliciesModule.html#/s:6BoxSDK23RetentionPoliciesModuleC15listAssignments8policyId4type6marker5limit6fieldsAA14PagingIteratorCyAA0C16PolicyAssignmentCGSS_AA0cpQ8ItemTypeOSgSSSgSiSgSaySSGSgtF). This method will return an iterator, which is used to get the assignments. ``` let iterator = client.retentionPolicy.listAssignments(policyId:"12345") iterator.next { results in switch results { case let .success(page): for assignment in page.entries { print("Retention policy assignment\(assignment.id)") } case let .failure(error): print(error) } } ``` You can also filter assignments by setting `type` parameter to one of values: `.folder`, `.metadataTemplate` or `.enterprise`: ``` let iterator = client.retentionPolicy.listAssignments(policyId:"12345", type: .folder) iterator.next { results in switch results { case let .success(page): for assignment in page.entries { print("Retention policy assignment\(assignment.id)") } case let .failure(error): print(error) } } ``` ## Delete Retention Policy Assignment To remove a retention policy assignment applied to content, call [`client.retentionPolicy.deleteAssignment(assignmentId:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/RetentionPoliciesModule.html#/s:6BoxSDK23RetentionPoliciesModuleC16deleteAssignment12assignmentId10completionySS_ys6ResultOyytAA0A8SDKErrorCGctF) with the ID of the assignment. ``` client.retentionPolicy.deleteAssignment(assignmentId: "123456") { result in guard case let .success = result else { print("Error deleting retention policy assignment") return } print("Retention policy assignment was deleted") } ``` ## Get File Version Retention A file version retention is a record for a retained file version. To get information for a specific file version retention record, call [`client.files.getVersionRetention(retentionId:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/FilesModule.html#/s:6BoxSDK11FilesModuleC19getVersionRetention11retentionId10completionySS_ys6ResultOyAA04FilefG0CAA0A8SDKErrorCGctF) with the ID of the file version retention. ``` client.files.getVersionRetention(retentionId: "123456"){ result in guard case let .success(retention) = result else { print("Error getting file version retention") return } print("File version retention: \(retention.id)") } ``` ## Get File Version Retentions To retrieves all file version retentions for the given enterprise, call [`client.files.listVersionRetentions(fileId:fileVersionId:policyId:dispositionAction:dispositionBefore:dispositionAfter:limit:marker:)`](https://opensource.box.com/box-ios-sdk/Classes/FilesModule.html#/s:6BoxSDK11FilesModuleC21listVersionRetentions6fileId0hfI006policyI017dispositionAction0K6Before0K5After5limit6markerAA14PagingIteratorCyAA04FileF9RetentionCGSSSg_A2rA011DispositionL0OSg10Foundation4DateVSgAYSiSgARtF). This method will return an iterator, which is used to get the file version retentions. ``` let iterator = client.files.listVersionRetentions() iterator.next { results in switch results { case let .success(page): for retention in page.entries { print("File version retention \(retention.id)") } case let .failure(error): print(error) } } ``` ## Get Files Under Retention For Assignment To get all files under retention for assignment policy, call the [`client.retentionPolicy.listFilesUnderRetentionForAssignment(retentionPolicyAssignmentId:limit:marker:)`](https://opensource.box.com/box-ios-sdk/Classes/RetentionPoliciesModule.html#/s:6BoxSDK23RetentionPoliciesModuleC014listFilesUnderC13ForAssignment015retentionPolicyJ2Id5limit6markerAA14PagingIteratorCyAA4FileCGSS_SiSgSSSgtF) method. This method will return an iterator, which is used to get the [`File`](https://opensource.box.com/box-ios-sdk/Classes/File.html) objects under retention. ``` let iterator = client.retentionPolicy.listFilesUnderRetentionForAssignment(retentionPolicyAssignmentId: "123456") iterator.next { results in switch results { case let .success(page): for file in page.entries { print("File \(file.name ?? "")") } case let .failure(error): print(error) } } ``` ## Get File Versions Under Retention For Assignment To get all file versions under retention placed in the file objects for a retention policy assignment, call the [`client.retentionPolicy.listFileVersionsUnderRetentionForAssignment(retentionPolicyAssignmentId:limit:marker:)`](https://opensource.box.com/box-ios-sdk/Classes/RetentionPoliciesModule.html#/s:6BoxSDK23RetentionPoliciesModuleC021listFileVersionsUnderC13ForAssignment015retentionPolicyK2Id5limit6markerAA14PagingIteratorCyAA0G0CGSS_SiSgSSSgtF) method. This method will return an iterator, which is used to get the [`FileVersion`](https://opensource.box.com/box-ios-sdk/Classes/FileVersion.html) object nested in [`File`](https://opensource.box.com/box-ios-sdk/Classes/File.html) object. ``` let iterator = client.retentionPolicy.listFileVersionsUnderRetentionForAssignment(retentionPolicyAssignmentId: "123456") iterator.next { results in switch results { case let .success(page): for file in page.entries { print("File version \(file.fileVersion?.id ?? "")") } case let .failure(error): print(error) } } ``` --- ### Retention Policies **Type:** page | **Section:** Additional Resources Retention Policies A retention policy blocks permanent deletion of content for a specified amount of time. Admins can create retention… # Retention Policies A retention policy blocks permanent deletion of content for a specified amount of time. Admins can create retention policies and then later assign them to specific folders or their entire enterprise. To use this feature, you must have the manage retention policies scope enabled for your API key via your application management console. - [Create Retention Policy](#create-retention-policy) - [Update Retention Policy](#update-retention-policy) - [Get Retention Policy](#get-retention-policy) - [Get Retention Policies](#get-retention-policies) - [Create Retention Policy Assignment](#create-retention-policy-assignment) - [Get Retention Policy Assignment](#get-retention-policy-assignment) - [Get Retention Policy Assignments](#get-retention-policy-assignments) - [Delete Retention Policy Assignment](#delete-retention-policy-assignment) - [Get File Version Retention](#get-file-version-retention) - [Get File Version Retentions](#get-file-version-retentions) (will be deprecated in the future, use [Get Files Under Retention For Assignment](#get-files-under-retention-for-assignment) and [Get File Version Under Retention For Assignment](#get-file-versions-under-retention-for-assignment) instead) - [Get Files Under Retention For Assignment](#get-files-under-retention-for-assignment) - [Get File Version Under Retention For Assignment](#get-file-versions-under-retention-for-assignment) ## Create Retention Policy To create a retention policy, call [`client.retentionPolicy.create(name:type:length:dispositionAction:canOwnerExtendRetention:areOwnersNotified:customNotificationRecipients:retentionType:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/RetentionPoliciesModule.html#/s:6BoxSDK23RetentionPoliciesModuleC6create4name4type6length17dispositionAction014canOwnerExtendC017areOwnersNotified28customNotificationRecipients13retentionType10completionySS_AA0c6PolicyV0OSiSgAA011DispositionK0OSbSgASSayAA4UserCGSgAA0cV0OSgys6ResultOyAA0cX0CAA0A8SDKErrorCGctF). You can create either a `indefinite` retention policy, or a `finite`. To create a `indefinite` retention policy, you must set a `type` to `.indefinite` and a `dispositionAction` to `.removeRetention`. ``` client.retentionPolicy.create( name: "Test Indefinite Policy Name", type: .indefinite, dispositionAction: .removeRetention ) { result in guard case let .success(retentionPolicy) = result else { print("Error creating retention policy") return } print("Retention policy: \(retentionPolicy.id) was created") } ``` To create a `finite` retention policy, you must set `type` to `.finite`, set amount of time in days to apply the retention policy (`length`) and a `dispositionAction`. The disposition action can be `.permanentlyDelete` or `.removeRetention`. ``` client.retentionPolicy.create( name: "Test Finite Policy Name", type: .finite, length: 60, dispositionAction: .permanentlyDelete ) { result in guard case let .success(retentionPolicy) = result else { print("Error creating retention policy") return } print("Retention policy: \(retentionPolicy.id) was created") } ``` ## Update Retention Policy To update a retention policy, call [`client.retentionPolicy.update(policyId:name:dispositionAction:status:setRetentionTypeToNonModifiable:length:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/RetentionPoliciesModule.html#/s:6BoxSDK23RetentionPoliciesModuleC6update8policyId4name17dispositionAction6status03setC19TypeToNonModifiable6length10completionySS_SSSgAA011DispositionK0OSgAA0C12PolicyStatusOSgSbSiSgys6ResultOyAA0cU0CAA0A8SDKErrorCGctF). ``` client.retentionPolicy.update(policyId: "1234", name: "New Policy Name") { result in guard case let .success(retentionPolicy) = result else { print("Error updating a retention policy") return } print("Updated retention policy: \(retentionPolicy.id)") } ``` ## Get Retention Policy To retrieve information about a retention policy, call [`client.retentionPolicy.get(policyId:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/RetentionPoliciesModule.html#/s:6BoxSDK23RetentionPoliciesModuleC3get8policyId10completionySS_ys6ResultOyAA0C6PolicyCAA0A8SDKErrorCGctF) with the ID of the retention policy. ``` client.retentionPolicy.get(policyId: "1234") { result in guard case let .success(retentionPolicy) = result else { print("Error getting retention policy") return } print("Retention policy: \(retentionPolicy.id)") } ``` ## Get Retention Policies To retrieve all retention policies for an enterprise, call [`client.retentionPolicy.list(name:type:createdByUserId:marker:limit:)`](https://opensource.box.com/box-ios-sdk/Classes/RetentionPoliciesModule.html#/s:6BoxSDK23RetentionPoliciesModuleC4list4name4type15createdByUserId6marker5limitAA14PagingIteratorCyAA0C11PolicyEntryCGSSSg_AA0cQ4TypeOSgA2OSiSgtF). This method will return an iterator, which is used to get the policies. As you can see in the method signature, it is possible to specify filter for the name, type and created user of the retention policy. All of mentioned fields are optional and if not set, all retention policies will be returned. You can also set a number of items per single response by setting a limit. ``` let iterator = client.retentionPolicy.list(type: .indefinite) iterator.next { results in switch results { case let .success(page): for policy in page.entries { print("Retention policy \(policy.id)") } case let .failure(error): print(error) } } ``` ## Create Retention Policy Assignment To create new retention policy assignment call [`client.retentionPolicy.assign(policyId:assignedContentId:assignContentType:filterFields:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/RetentionPoliciesModule.html#/s:6BoxSDK23RetentionPoliciesModuleC6assign8policyId015assignedContentH00fJ4Type12filterFields10completionySS_SSAA0c20PolicyAssignmentItemK0OSayAA19MetadataFieldFilterVGSgys6ResultOyAA0coP0CAA0A8SDKErrorCGctF) method to assign the policy. Retention policy can be assigned to a specific folder, to a metadata template or to the entire enterprise. ``` client.retentionPolicy.assign(policyId: "12345", assignedContentId: "1111", assignContentType: .folder) { result in guard case let .success(retentionPolicyAssignment) = result else { print("Error creating retention policy assignment") return } print("Retention policy assignment: \(retentionPolicyAssignment.id) was created") } ``` ## Get Retention Policy Assignment To retrieve information about a retention policy assignment, call [`client.retentionPolicy.getAssignment(assignmentId:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/RetentionPoliciesModule.html#/s:6BoxSDK23RetentionPoliciesModuleC13getAssignment12assignmentId10completionySS_ys6ResultOyAA0c6PolicyG0CAA0A8SDKErrorCGctF) with the ID of the assignment. ``` client.retentionPolicy.getAssignment(assignmentId: "123456") { result in guard case let .success(retentionPolicyAssignment) = result else { print("Error getting retention policy assignment") return } print("Retention policy assignment: \(retentionPolicyAssignment.id)") } ``` ## Get Retention Policy Assignments To get a list of all retention policy assignments associated with a specified retention policy, call [`client.retentionPolicy.listAssignments(policyId:type:marker:limit:fields)`](https://opensource.box.com/box-ios-sdk/Classes/RetentionPoliciesModule.html#/s:6BoxSDK23RetentionPoliciesModuleC15listAssignments8policyId4type6marker5limit6fieldsAA14PagingIteratorCyAA0C16PolicyAssignmentCGSS_AA0cpQ8ItemTypeOSgSSSgSiSgSaySSGSgtF). This method will return an iterator, which is used to get the assignments. ``` let iterator = client.retentionPolicy.listAssignments(policyId:"12345") iterator.next { results in switch results { case let .success(page): for assignment in page.entries { print("Retention policy assignment\(assignment.id)") } case let .failure(error): print(error) } } ``` You can also filter assignments by setting `type` parameter to one of values: `.folder`, `.metadataTemplate` or `.enterprise`: ``` let iterator = client.retentionPolicy.listAssignments(policyId:"12345", type: .folder) iterator.next { results in switch results { case let .success(page): for assignment in page.entries { print("Retention policy assignment\(assignment.id)") } case let .failure(error): print(error) } } ``` ## Delete Retention Policy Assignment To remove a retention policy assignment applied to content, call [`client.retentionPolicy.deleteAssignment(assignmentId:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/RetentionPoliciesModule.html#/s:6BoxSDK23RetentionPoliciesModuleC16deleteAssignment12assignmentId10completionySS_ys6ResultOyytAA0A8SDKErrorCGctF) with the ID of the assignment. ``` client.retentionPolicy.deleteAssignment(assignmentId: "123456") { result in guard case let .success = result else { print("Error deleting retention policy assignment") return } print("Retention policy assignment was deleted") } ``` ## Get File Version Retention A file version retention is a record for a retained file version. To get information for a specific file version retention record, call [`client.files.getVersionRetention(retentionId:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/FilesModule.html#/s:6BoxSDK11FilesModuleC19getVersionRetention11retentionId10completionySS_ys6ResultOyAA04FilefG0CAA0A8SDKErrorCGctF) with the ID of the file version retention. ``` client.files.getVersionRetention(retentionId: "123456"){ result in guard case let .success(retention) = result else { print("Error getting file version retention") return } print("File version retention: \(retention.id)") } ``` ## Get File Version Retentions To retrieves all file version retentions for the given enterprise, call [`client.files.listVersionRetentions(fileId:fileVersionId:policyId:dispositionAction:dispositionBefore:dispositionAfter:limit:marker:)`](https://opensource.box.com/box-ios-sdk/Classes/FilesModule.html#/s:6BoxSDK11FilesModuleC21listVersionRetentions6fileId0hfI006policyI017dispositionAction0K6Before0K5After5limit6markerAA14PagingIteratorCyAA04FileF9RetentionCGSSSg_A2rA011DispositionL0OSg10Foundation4DateVSgAYSiSgARtF). This method will return an iterator, which is used to get the file version retentions. ``` let iterator = client.files.listVersionRetentions() iterator.next { results in switch results { case let .success(page): for retention in page.entries { print("File version retention \(retention.id)") } case let .failure(error): print(error) } } ``` ## Get Files Under Retention For Assignment To get all files under retention for assignment policy, call the [`client.retentionPolicy.listFilesUnderRetentionForAssignment(retentionPolicyAssignmentId:limit:marker:)`](https://opensource.box.com/box-ios-sdk/Classes/RetentionPoliciesModule.html#/s:6BoxSDK23RetentionPoliciesModuleC014listFilesUnderC13ForAssignment015retentionPolicyJ2Id5limit6markerAA14PagingIteratorCyAA4FileCGSS_SiSgSSSgtF) method. This method will return an iterator, which is used to get the [`File`](https://opensource.box.com/box-ios-sdk/Classes/File.html) objects under retention. ``` let iterator = client.retentionPolicy.listFilesUnderRetentionForAssignment(retentionPolicyAssignmentId: "123456") iterator.next { results in switch results { case let .success(page): for file in page.entries { print("File \(file.name ?? "")") } case let .failure(error): print(error) } } ``` ## Get File Versions Under Retention For Assignment To get all file versions under retention placed in the file objects for a retention policy assignment, call the [`client.retentionPolicy.listFileVersionsUnderRetentionForAssignment(retentionPolicyAssignmentId:limit:marker:)`](https://opensource.box.com/box-ios-sdk/Classes/RetentionPoliciesModule.html#/s:6BoxSDK23RetentionPoliciesModuleC021listFileVersionsUnderC13ForAssignment015retentionPolicyK2Id5limit6markerAA14PagingIteratorCyAA0G0CGSS_SiSgSSSgtF) method. This method will return an iterator, which is used to get the [`FileVersion`](https://opensource.box.com/box-ios-sdk/Classes/FileVersion.html) object nested in [`File`](https://opensource.box.com/box-ios-sdk/Classes/File.html) object. ``` let iterator = client.retentionPolicy.listFileVersionsUnderRetentionForAssignment(retentionPolicyAssignmentId: "123456") iterator.next { results in switch results { case let .success(page): for file in page.entries { print("File version \(file.fileVersion?.id ?? "")") } case let .failure(error): print(error) } } ``` --- ### RetentionPoliciesManager **Type:** page | **Section:** Additional Resources RetentionPoliciesManager List retention policies Create retention policy Get retention policy Update retention policy Delete retention… # RetentionPoliciesManager - [List retention policies](#list-retention-policies) - [Create retention policy](#create-retention-policy) - [Get retention policy](#get-retention-policy) - [Update retention policy](#update-retention-policy) - [Delete retention policy](#delete-retention-policy) ## List retention policies Retrieves all of the retention policies for an enterprise. This operation is performed by calling function `getRetentionPolicies`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-retention-policies/). ``` await client.retentionPolicies.getRetentionPolicies(); ``` ### Arguments queryParams `GetRetentionPoliciesQueryParams` - Query parameters of getRetentionPolicies method headersInput `GetRetentionPoliciesHeadersInput` - Headers of getRetentionPolicies method cancellationToken `undefined | CancellationToken` - Token used for request cancellation. ### Returns This function returns a value of type `RetentionPolicies`. Returns a list retention policies in the enterprise. ## Create retention policy Creates a retention policy. This operation is performed by calling function `createRetentionPolicy`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-retention-policies/). ``` await client.retentionPolicies.createRetentionPolicy({ policyName: retentionPolicyName, policyType: 'finite' as CreateRetentionPolicyRequestBodyPolicyTypeField, areOwnersNotified: true, canOwnerExtendRetention: true, description: retentionDescription, dispositionAction: 'remove_retention' as CreateRetentionPolicyRequestBodyDispositionActionField, retentionLength: '1', retentionType: 'modifiable' as CreateRetentionPolicyRequestBodyRetentionTypeField, } satisfies CreateRetentionPolicyRequestBody); ``` ### Arguments requestBody `CreateRetentionPolicyRequestBody` - Request body of createRetentionPolicy method optionalsInput `CreateRetentionPolicyOptionalsInput` ### Returns This function returns a value of type `RetentionPolicy`. Returns a new retention policy object. ## Get retention policy Retrieves a retention policy. This operation is performed by calling function `getRetentionPolicyById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-retention-policies-id/). ``` await client.retentionPolicies.getRetentionPolicyById(retentionPolicy.id); ``` ### Arguments retentionPolicyId `string` - The ID of the retention policy. Example: "982312" optionalsInput `GetRetentionPolicyByIdOptionalsInput` ### Returns This function returns a value of type `RetentionPolicy`. Returns the retention policy object. ## Update retention policy Updates a retention policy. This operation is performed by calling function `updateRetentionPolicyById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-retention-policies-id/). ``` await client.retentionPolicies.updateRetentionPolicyById(retentionPolicy.id, { requestBody: { policyName: updatedRetentionPolicyName, } satisfies UpdateRetentionPolicyByIdRequestBody, } satisfies UpdateRetentionPolicyByIdOptionalsInput); ``` ### Arguments retentionPolicyId `string` - The ID of the retention policy. Example: "982312" optionalsInput `UpdateRetentionPolicyByIdOptionalsInput` ### Returns This function returns a value of type `RetentionPolicy`. Returns the updated retention policy object. ## Delete retention policy Permanently deletes a retention policy. This operation is performed by calling function `deleteRetentionPolicyById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-retention-policies-id/). ``` await client.retentionPolicies.deleteRetentionPolicyById(retentionPolicy.id); ``` ### Arguments retentionPolicyId `string` - The ID of the retention policy. Example: "982312" optionalsInput `DeleteRetentionPolicyByIdOptionalsInput` ### Returns This function returns a value of type `undefined`. Returns an empty response when the policy has been deleted. --- ### RetentionPoliciesManager **Type:** page | **Section:** Additional Resources RetentionPoliciesManager List retention policies Create retention policy Get retention policy Update retention policy Delete retention… # RetentionPoliciesManager - [List retention policies](#list-retention-policies) - [Create retention policy](#create-retention-policy) - [Get retention policy](#get-retention-policy) - [Update retention policy](#update-retention-policy) - [Delete retention policy](#delete-retention-policy) ## List retention policies Retrieves all of the retention policies for an enterprise. This operation is performed by calling function `get_retention_policies`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-retention-policies/). ``` client.retention_policies.get_retention_policies() ``` ### Arguments policy_name `Optional[str]` - Filters results by a case sensitive prefix of the name of retention policies. policy_type `Optional[GetRetentionPoliciesPolicyType]` - Filters results by the type of retention policy. created_by_user_id `Optional[str]` - Filters results by the ID of the user who created policy. fields `Optional[List[str]]` - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested. limit `Optional[int]` - The maximum number of items to return per page. marker `Optional[str]` - Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `RetentionPolicies`. Returns a list retention policies in the enterprise. ## Create retention policy Creates a retention policy. This operation is performed by calling function `create_retention_policy`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-retention-policies/). ``` client.retention_policies.create_retention_policy( retention_policy_name, CreateRetentionPolicyPolicyType.FINITE, CreateRetentionPolicyDispositionAction.REMOVE_RETENTION, description=retention_description, retention_length="1", retention_type=CreateRetentionPolicyRetentionType.MODIFIABLE, can_owner_extend_retention=True, are_owners_notified=True, ) ``` ### Arguments policy_name `str` - The name for the retention policy. description `Optional[str]` - The additional text description of the retention policy. policy_type `CreateRetentionPolicyPolicyType` - The type of the retention policy. A retention policy type can either be `finite`, where a specific amount of time to retain the content is known upfront, or `indefinite`, where the amount of time to retain the content is still unknown. disposition_action `CreateRetentionPolicyDispositionAction` - The disposition action of the retention policy. `permanently_delete` deletes the content retained by the policy permanently. `remove_retention` lifts retention policy from the content, allowing it to be deleted by users once the retention policy has expired. retention_length `Optional[str]` - The length of the retention policy. This value specifies the duration in days that the retention policy will be active for after being assigned to content. If the policy has a `policy_type` of `indefinite`, the `retention_length` will also be `indefinite`. retention_type `Optional[CreateRetentionPolicyRetentionType]` - Specifies the retention type: _ `modifiable`: You can modify the retention policy. For example, you can add or remove folders, shorten or lengthen the policy duration, or delete the assignment. Use this type if your retention policy is not related to any regulatory purposes. _ `non_modifiable`: You can modify the retention policy only in a limited way: add a folder, lengthen the duration, retire the policy, change the disposition action or notification settings. You cannot perform other actions, such as deleting the assignment or shortening the policy duration. Use this type to ensure compliance with regulatory retention policies. can_owner_extend_retention `Optional[bool]` - Whether the owner of a file will be allowed to extend the retention. are_owners_notified `Optional[bool]` - Whether owner and co-owners of a file are notified when the policy nears expiration. custom_notification_recipients `Optional[List[UserMini]]` - A list of users notified when the retention policy duration is about to end. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `RetentionPolicy`. Returns a new retention policy object. ## Get retention policy Retrieves a retention policy. This operation is performed by calling function `get_retention_policy_by_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-retention-policies-id/). ``` client.retention_policies.get_retention_policy_by_id(retention_policy.id) ``` ### Arguments retention_policy_id `str` - The ID of the retention policy. Example: "982312" fields `Optional[List[str]]` - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `RetentionPolicy`. Returns the retention policy object. ## Update retention policy Updates a retention policy. This operation is performed by calling function `update_retention_policy_by_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-retention-policies-id/). ``` client.retention_policies.update_retention_policy_by_id( retention_policy.id, policy_name=updated_retention_policy_name ) ``` ### Arguments retention_policy_id `str` - The ID of the retention policy. Example: "982312" policy_name `Optional[str]` - The name for the retention policy. description `Optional[str]` - The additional text description of the retention policy. disposition_action `Optional[str]` - The disposition action of the retention policy. This action can be `permanently_delete`, which will cause the content retained by the policy to be permanently deleted, or `remove_retention`, which will lift the retention policy from the content, allowing it to be deleted by users, once the retention policy has expired. You can use `null` if you don't want to change `disposition_action`. retention_type `Optional[str]` - Specifies the retention type: _ `modifiable`: You can modify the retention policy. For example, you can add or remove folders, shorten or lengthen the policy duration, or delete the assignment. Use this type if your retention policy is not related to any regulatory purposes. _ `non-modifiable`: You can modify the retention policy only in a limited way: add a folder, lengthen the duration, retire the policy, change the disposition action or notification settings. You cannot perform other actions, such as deleting the assignment or shortening the policy duration. Use this type to ensure compliance with regulatory retention policies. When updating a retention policy, you can use `non-modifiable` type only. You can convert a `modifiable` policy to `non-modifiable`, but not the other way around. retention_length `Optional[str]` - The length of the retention policy. This value specifies the duration in days that the retention policy will be active for after being assigned to content. If the policy has a `policy_type` of `indefinite`, the `retention_length` will also be `indefinite`. status `Optional[str]` - Used to retire a retention policy. If not retiring a policy, do not include this parameter or set it to `null`. can_owner_extend_retention `Optional[bool]` - Determines if the owner of items under the policy can extend the retention when the original retention duration is about to end. are_owners_notified `Optional[bool]` - Determines if owners and co-owners of items under the policy are notified when the retention duration is about to end. custom_notification_recipients `Optional[List[UserBase]]` - A list of users notified when the retention duration is about to end. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `RetentionPolicy`. Returns the updated retention policy object. ## Delete retention policy Permanently deletes a retention policy. This operation is performed by calling function `delete_retention_policy_by_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-retention-policies-id/). ``` client.retention_policies.delete_retention_policy_by_id(retention_policy.id) ``` ### Arguments retention_policy_id `str` - The ID of the retention policy. Example: "982312" extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `None`. Returns an empty response when the policy has been deleted. --- ### RetentionPolicyAssignmentsManager **Type:** page | **Section:** Additional Resources RetentionPolicyAssignmentsManager List retention policy assignments Assign retention policy Get retention policy assignment Remove retention… # RetentionPolicyAssignmentsManager - [List retention policy assignments](#list-retention-policy-assignments) - [Assign retention policy](#assign-retention-policy) - [Get retention policy assignment](#get-retention-policy-assignment) - [Remove retention policy assignment](#remove-retention-policy-assignment) - [Get files under retention](#get-files-under-retention) ## List retention policy assignments Returns a list of all retention policy assignments associated with a specified retention policy. This operation is performed by calling function `getRetentionPolicyAssignments`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-retention-policies-id-assignments/). ``` await client.retentionPolicyAssignments.getRetentionPolicyAssignments( retentionPolicy.id, ); ``` ### Arguments retentionPolicyId `string` - The ID of the retention policy. Example: "982312" optionalsInput `GetRetentionPolicyAssignmentsOptionalsInput` ### Returns This function returns a value of type `RetentionPolicyAssignments`. Returns a list of the retention policy assignments associated with the specified retention policy. ## Assign retention policy Assigns a retention policy to an item. This operation is performed by calling function `createRetentionPolicyAssignment`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-retention-policy-assignments/). ``` await client.retentionPolicyAssignments.createRetentionPolicyAssignment({ policyId: retentionPolicy.id, assignTo: { type: 'folder' as CreateRetentionPolicyAssignmentRequestBodyAssignToTypeField, id: folder.id, } satisfies CreateRetentionPolicyAssignmentRequestBodyAssignToField, } satisfies CreateRetentionPolicyAssignmentRequestBody); ``` ### Arguments requestBody `CreateRetentionPolicyAssignmentRequestBody` - Request body of createRetentionPolicyAssignment method optionalsInput `CreateRetentionPolicyAssignmentOptionalsInput` ### Returns This function returns a value of type `RetentionPolicyAssignment`. Returns a new retention policy assignment object. ## Get retention policy assignment Retrieves a retention policy assignment. This operation is performed by calling function `getRetentionPolicyAssignmentById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-retention-policy-assignments-id/). ``` await client.retentionPolicyAssignments.getRetentionPolicyAssignmentById( retentionPolicyAssignment.id, ); ``` ### Arguments retentionPolicyAssignmentId `string` - The ID of the retention policy assignment. Example: "1233123" optionalsInput `GetRetentionPolicyAssignmentByIdOptionalsInput` ### Returns This function returns a value of type `RetentionPolicyAssignment`. Returns the retention policy assignment object. ## Remove retention policy assignment Removes a retention policy assignment applied to content. This operation is performed by calling function `deleteRetentionPolicyAssignmentById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-retention-policy-assignments-id/). ``` await client.retentionPolicyAssignments.deleteRetentionPolicyAssignmentById( retentionPolicyAssignment.id, ); ``` ### Arguments retentionPolicyAssignmentId `string` - The ID of the retention policy assignment. Example: "1233123" optionalsInput `DeleteRetentionPolicyAssignmentByIdOptionalsInput` ### Returns This function returns a value of type `undefined`. Returns an empty response when the policy assignment is successfully deleted. ## Get files under retention Returns a list of files under retention for a retention policy assignment. This operation is performed by calling function `getFilesUnderRetentionPolicyAssignment`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-retention-policy-assignments-id-files-under-retention/). ``` await client.retentionPolicyAssignments.getFilesUnderRetentionPolicyAssignment( retentionPolicyAssignment.id, ); ``` ### Arguments retentionPolicyAssignmentId `string` - The ID of the retention policy assignment. Example: "1233123" optionalsInput `GetFilesUnderRetentionPolicyAssignmentOptionalsInput` ### Returns This function returns a value of type `FilesUnderRetention`. Returns a list of files under retention that are associated with the specified retention policy assignment. --- ### RetentionPolicyAssignmentsManager **Type:** page | **Section:** Additional Resources RetentionPolicyAssignmentsManager List retention policy assignments Assign retention policy Get retention policy assignment Remove retention… # RetentionPolicyAssignmentsManager - [List retention policy assignments](#list-retention-policy-assignments) - [Assign retention policy](#assign-retention-policy) - [Get retention policy assignment](#get-retention-policy-assignment) - [Remove retention policy assignment](#remove-retention-policy-assignment) - [Get files under retention](#get-files-under-retention) ## List retention policy assignments Returns a list of all retention policy assignments associated with a specified retention policy. This operation is performed by calling function `get_retention_policy_assignments`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-retention-policies-id-assignments/). ``` client.retention_policy_assignments.get_retention_policy_assignments( retention_policy.id ) ``` ### Arguments retention_policy_id `str` - The ID of the retention policy. Example: "982312" type `Optional[GetRetentionPolicyAssignmentsType]` - The type of the retention policy assignment to retrieve. fields `Optional[List[str]]` - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested. marker `Optional[str]` - Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. limit `Optional[int]` - The maximum number of items to return per page. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `RetentionPolicyAssignments`. Returns a list of the retention policy assignments associated with the specified retention policy. ## Assign retention policy Assigns a retention policy to an item. This operation is performed by calling function `create_retention_policy_assignment`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-retention-policy-assignments/). ``` client.retention_policy_assignments.create_retention_policy_assignment( retention_policy.id, CreateRetentionPolicyAssignmentAssignTo( type=CreateRetentionPolicyAssignmentAssignToTypeField.FOLDER, id=folder.id ), ) ``` ### Arguments policy_id `str` - The ID of the retention policy to assign. assign_to `CreateRetentionPolicyAssignmentAssignTo` - The item to assign the policy to. filter_fields `Optional[List[CreateRetentionPolicyAssignmentFilterFields]]` - If the `assign_to` type is `metadata_template`, then optionally add the `filter_fields` parameter which will require an array of objects with a field entry and a value entry. Currently only one object of `field` and `value` is supported. start_date_field `Optional[str]` - The date the retention policy assignment begins. If the `assigned_to` type is `metadata_template`, this field can be a date field's metadata attribute key id. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `RetentionPolicyAssignment`. Returns a new retention policy assignment object. ## Get retention policy assignment Retrieves a retention policy assignment. This operation is performed by calling function `get_retention_policy_assignment_by_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-retention-policy-assignments-id/). ``` client.retention_policy_assignments.get_retention_policy_assignment_by_id( retention_policy_assignment.id ) ``` ### Arguments retention_policy_assignment_id `str` - The ID of the retention policy assignment. Example: "1233123" fields `Optional[List[str]]` - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `RetentionPolicyAssignment`. Returns the retention policy assignment object. ## Remove retention policy assignment Removes a retention policy assignment applied to content. This operation is performed by calling function `delete_retention_policy_assignment_by_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-retention-policy-assignments-id/). ``` client.retention_policy_assignments.delete_retention_policy_assignment_by_id( retention_policy_assignment.id ) ``` ### Arguments retention_policy_assignment_id `str` - The ID of the retention policy assignment. Example: "1233123" extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `None`. Returns an empty response when the policy assignment is successfully deleted. ## Get files under retention Returns a list of files under retention for a retention policy assignment. This operation is performed by calling function `get_files_under_retention_policy_assignment`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-retention-policy-assignments-id-files-under-retention/). ``` client.retention_policy_assignments.get_files_under_retention_policy_assignment( retention_policy_assignment.id ) ``` ### Arguments retention_policy_assignment_id `str` - The ID of the retention policy assignment. Example: "1233123" marker `Optional[str]` - Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`. limit `Optional[int]` - The maximum number of items to return per page. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `FilesUnderRetention`. Returns a list of files under retention that are associated with the specified retention policy assignment. --- ### SDK Overview **Type:** page | **Section:** Additional Resources SDK Overview This guide covers the basics behind the various components of the Box Java SDK. It's also recommended that you take a look at… # SDK Overview This guide covers the basics behind the various components of the Box Java SDK. It's also recommended that you take a look at the documentation for the Box API. - [Authentication](#authentication) - [Resource Types](#resource-types) - [Requests and Responses](#requests-and-responses) - [Error Handling](#error-handling) - [As-User](#as-user) - [Suppressing Notifications](#suppressing-notifications) ## Authentication The first step in using the SDK is always authenticating and connecting to the API. The SDK does this through the [`BoxAPIConnection`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxAPIConnection.html) class. This class represents an authenticated connection to a specific version of the Box API. It is responsible for things such as: - Storing authentication information. - Automatically refreshing tokens. Configuring rate-limiting, number of retry attempts and other connection settings. You can also create more than one `BoxAPIConnection`. For example, you can have a connection for each user if your application supports multiple user accounts. See the [Authentication guide](https://ja.developer.box.com/69a8a62320adb7087794d5bb03d56230/authentication.md) for details on how to create and use `BoxAPIConnection`. ## Resource Types Resources types are the classes you'll use the most. Things like `BoxFile`, `BoxFolder`, `BoxUser`, etc. are all resource types. A resource always has an ID and an associated API connection. Instantiating and using a resource type is simple: ``` // Print the name of the folder with ID "1234". BoxFolder folder = new BoxFolder(api, "1234") BoxFolder.Info info = folder.getInfo(); System.out.println(info.getName()); ``` A resource type will always have the same API connection as the type that instantiated it. For example, `creator` will have the same API connection that `folder` does. ``` BoxFolder folder = new BoxFolder(api, "1234") BoxFolder.Info info = folder.getInfo(); // This BoxUser has the same BoxAPIConnection as "folder". BoxUser creator = info.getCreatedBy(); ``` ## Requests and Responses All communication with Box's API is done through `BoxAPIRequest` and `BoxAPIResponse` (or their subclasses). These classes handle all the dirty work of setting appropriate headers, handling errors, and sending/receiving data. You generally won't need to use these classes directly, as the resource types are easier and cover most use-cases. However, these classes are extremely flexible and can be used if you need to make custom API calls. Here's an example using `BoxAPIRequest` and `BoxJSONResponse` that gets a list of items with some custom fields: ``` BoxAPIConnection api = new BoxAPIConnection("token"); URL url = new URL("https://api.box.com/2.0/folders/0/items?fields=name,created_at") BoxAPIRequest request = new BoxAPIRequest(api, url, "GET"); BoxJSONResponse response = (BoxJSONResponse) request.send(); String json = response.getJSON(); ``` ## Error Handling Unless otherwise noted, the classes and methods in the SDK can throw an unchecked [`BoxAPIException`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxAPIException.html) (unchecked meaning that the compiler won't force you to handle it) if an error occurs. This includes network errors or error statuses returned by the API. You should be aware of this when using the SDK so that your code can catch any errors that might happen when communicating with Box. If the error was due to a general networking error (for example, if the network connection was lost), the `BoxAPIException` will contain the underlying `IOException` as its cause. If the error was due to an API error, the `BoxAPIException` will contain the response code and body returned by the API. ``` BoxAPIConnection api = new BoxAPIConnection("token"); try { BoxFolder rootFolder = BoxFolder.getRootFolder(api); } catch (BoxAPIException e) { // Log the response code and the error message returned by the API. System.err.format("The API returned the error code: %d\n\n%s", e.getResponseCode(), e.getResponse()); } ``` ## As-User As-User is used by enterprise administrators to make API calls for their managed users. It can also be used by a Service Account to make API calls for managed users or app users. As-User state is set on the [`BoxAPIConnection`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxAPIConnection.html) instance with [`asUser(String userID)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxAPIConnection.html#asUser-java.lang.String-) and will be used for all requests made from that API connection going forward, until the state is removed with [`asSelf()`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxAPIConnection.html#asSelf--). ``` String userID = "12345"; String fileID = "98765"; BoxAPIConnection api = new BoxAPIConnection("ACCESS_TOKEN"); BoxFile file = new BoxFile(api, fileID); // API call made as user associated with access token BoxFile.Info info = file.getInfo(); api.asUser(userID); // API call made as user associated with userID info = file.getInfo(); api.asSelf(); // API call made as user associated with access token again BoxFile.Info info = file.getInfo(); ``` ## Suppressing Notifications If you are making administrative API calls (that is, your application has “Manage an Enterprise” scope, and the user signing in is a co-admin with the correct "Edit settings for your company" permission) then you can suppress both email and webhook notifications. This can be used, for example, for a virus-scanning tool to download copies of everyone’s files in an enterprise, without every collaborator on the file getting an email. All actions will still appear in users' updates feed and audit logs. **Note:** This functionality is only available for approved applications. To turn on notification suppression for all calls made through a [`BoxAPIConnection`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxAPIConnection.html) instance, call [`suppressNotifications()`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxAPIConnection.html#suppressNotifications--). To re-enable notifications on an API connection, call [`enableNotifications`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxAPIConnection.html#enableNotifications--). ``` String userID = "12345"; String fileID = "98765"; OutputStream downloadStream; BoxAPIConnection api = new BoxAPIConnection("ACCESS_TOKEN"); BoxFile file = new BoxFile(api, fileID); // Notifications are sent by default downlaodStream = file.download(); api.suppressNotifications(); // Notifications are suppressed downlaodStream = file.download(); api.enableNotifications(); // Notifications are sent again downlaodStream = file.download(); ``` --- ### SDKとツール **Type:** page | **Category:** SDKとツール | **Section:** Additional Resources SDKとツール Boxで開発およびサポートされているSDKおよびツールは以下のとおりです。 SDK アプリケーションの作成に使用できるSDKの一覧を以下に示します。これとは別に、新しく追加された次世代のPython SDK、TypeScript SDK、.NET SDK… # SDKとツール Boxで開発およびサポートされているSDKおよびツールは以下のとおりです。 ## SDK アプリケーションの作成に使用できるSDKの一覧を以下に示します。これとは別に、新しく追加された次世代のPython SDK、TypeScript SDK、.NET SDKも記載しています。.NET SDKはまだベータ機能ですが、試しに使用して、備わっているすべての機能を確認することをお勧めします。 下の表には、SDKが、プロジェクトがメンテナンスされるかどうかとAPIパリティが備わっているかどうかを示す追加情報とともに記載されています。 **ステータス**: 現在のプロジェクトのステータスを説明します。ステータスの詳細については、[Box Open Sourceウェブサイト](https://opensource.box.com/badges/)を参照してください。Boxでは、アクティブなプロジェクトを積極的に開発しています。このようなプロジェクトには最新のセキュリティ更新プログラムや新機能が提供されます。このようなプロジェクトのサポートについては、GitHubまたは[Developer Forum](https://community.box.com/)を参照してください。 **APIパリティ**: 完全なAPIパリティを持つプロジェクトは、Box Platformで利用可能になった時点で、すべてのプラットフォーム機能が積極的に更新されます。部分的なAPIパリティを持つプロジェクトには一部の機能が欠けていますが、Boxではそのようなプロジェクトを完全なパリティに移行する取り組みを進めています。 ### 次世代のSDK 最新世代のBox Python SDK、Box TypeScript SDK、.NET SDK、Swift SDKは、開発者エクスペリエンスを向上させ、Boxコンテンツクラウドとの統合を効率化することを目的としています。 Swift SDKはパブリックベータ段階です。 新しいSDKに実装予定の機能を以下に示します。 - **APIの全面的なサポート**: 新しいBox SDKにより、開発者はBox APIエコシステム全体をカバーできるようになります。Boxが提供する最新機能をすべて利用して、機能豊富なアプリケーションを作成できます。 - **迅速なAPIの更新**: 自動生成による新しい開発アプローチにより、SDKへのBox APIの追加がさらに速いペースで (数日中に) 可能になります。これは、最新の機能をすぐにアプリケーションで利用できるようになることを意味します。 - **ドキュメントへの埋め込み**: 必要な情報すべてが1か所に保存されるように、すべてのオブジェクトおよびパラメータはSDKのソースコードに直接記述されます。 - **便利なメソッドの強化**: 新しく導入された便利なメソッドは、認証、分割アップロード、指数バックオフ、自動再試行、型チェック (変数を正しく使用しているかどうかの確認に役立ちます) など、さまざまな側面をカバーします。 任意のプログラミング言語の**Box Platform** SDKをダウンロードして開始します。 | プラットフォーム | ステータス | APIパリティ | | --- | --- | --- | | Pythonの次世代SDK | アクティブ | Full | | TypeScriptの次世代SDK | アクティブ | Full | | .NET SDK | アクティブ | Full | | Swift SDK (ベータ) | アクティブ | Full | | Javaの次世代SDK (ベータ) | アクティブ | Full | ### 従来のSDK 次の表に、アプリケーションの作成時に使用できる従来のBox SDKを示します。最新のAPIサポートや機能には、次世代のSDKを使用してください。 | プラットフォーム | ステータス | APIパリティ | | --- | --- | --- | | Java SDK | アクティブ | Full | | iOS Content SDK | アクティブ | Full | | Android Content SDK | 廃止 | 部分的 | | .NET SDK | 安定 | Full | | Python SDK | 安定 | Full | | Node SDK | 安定 | Full | 日本時間2023年6月1日をもって、Android SDKのサポートは終了しました。既存のAndroid SDKアプリケーションは影響なく引き続きご利用いただけますが、新機能、更新、バグ修正は提供されなくなります。 最新のAndroid機能を引き続きご利用いただくために、Java SDKを使用してAndroid版アプリを作成することをお勧めします。詳細については、[こちら](https://github.com/box/box-java-sdk/blob/main/doc/android.md)のドキュメントを参照してください。 ## Box CLI Box CLIは、使い勝手の良いコマンドラインツールです。これにより、開発者でも開発者以外のユーザーでもBox APIを利用してルーチンや一括操作を実行できるようになります。 | プラットフォーム | ステータス | APIパリティ | | --- | --- | --- | | CLI | アクティブ | Full | ## Postmanコレクション [Postman](https://postman.com)は、完全な開発環境を構成しなくても、使いやすいインターフェースでHTTPリクエストを作成およびテストできるツールです。**Box Postmanコレクション**は事前設定済みのリクエストをまとめたもので、これにより、リクエストを手動で設定しなくても、Box APIを利用できるようになります。 Postmanの使用を開始するには、Postmanクイックスタートガイドを使用するのが最も簡単な方法です。 Box Postmanコレクションの使い方 ## Salesforce Developer Toolkit Salesforce Developer Toolkitを使用すると、Box for Salesforce統合の動作をプログラムによりカスタマイズできます。このツールキットに含まれる複数のグローバルAPEXメソッドを使用して、デフォルトの動作をトリガーしたり、拡張したりできます。このグローバルメソッドにより、内部のSalesforceレコードとBoxフォルダのマッピングを更新し、権限の管理を処理できます。 この機能は最新のBox for [Salesforceパッケージ](https://support.box.com/hc/ja/articles/360044195713-Box-for-Salesforce%E3%81%AE%E3%82%A4%E3%83%B3%E3%82%B9%E3%83%88%E3%83%BC%E3%83%AB%E3%81%A8%E8%A8%AD%E5%AE%9A)に含まれています。 # このツールキットに含まれない機能 このツールキットは、BOX Content API用のフル機能を備えたAPEXラッパーではありません。このようなラッパーをお求めの場合は、[Box SDK for Salesforce](https://github.com/box/box-salesforce-sdk)を参照してください。 ## 公式UIライブラリ 組み込みのUIコンポーネントを使用してアプリケーションを拡張することで、Box上のファイルを参照、共有、プレビューできるようになります。 | | | | | --- | --- | --- | | 参照 | 共有 | プレビュー | | | | | | 組み込みのUIを使用して、Box上のファイルをナビゲートおよび操作できます。 | 組み込みのUI Elementを使ってファイルを共有することで、ファイルとフォルダのコラボレーションが可能になります。 | 豊富なプレビュー機能によって、PDFからHDビデオまで、120種類を超えるファイル形式をプレビューできます。 | | プラットフォーム | | | --- | --- | | iOS | Browse SDK、Share SDK、Preview SDK | | Android | Browse SDK、Share SDK、Preview SDK | | JavaScript | Box UI Elements | ## 非公式およびコミュニティツール 以下のツールは、Boxで開発され、Boxとそのコミュニティメンバーによって管理されています。このツールについては、定期的な製品更新やセキュリティ更新は提供されません。 | プラットフォーム | メンテナンスの有無 | APIパリティ | | --- | --- | --- | | Salesforce SDK | Boxとコミュニティメンバーが限定的に実施 | 部分的 | | Ruby SDK | Boxとコミュニティメンバーが限定的に実施 | 部分的 | | クライアント側JS SDK | Boxとコミュニティメンバーが限定的に実施 | 部分的 | **メンテナンス:** メンテナンスが限定されているプロジェクトについては、コミュニティとBoxが協力して更新を実施します。セキュリティ更新は不定期に提供されます。プレミアムサポートプランをご利用の場合、このようなツールに関する緊急の機能リクエストについてはカスタマーサービスにお問い合わせください。このようなプロジェクトに関するその他のサポートクエリについては、GitHubまたは[Developer Forum](https://community.box.com/)を参照してください。 **APIパリティ:** APIパリティが限定されているプロジェクトでは、Box Platformに公開されたときに新しい機能が自動的に導入されないため、一部の機能を使用できない場合があります。プレミアムサポートプランをご利用の場合、このようなツールに関する緊急の機能リクエストについてはカスタマーサービスにお問い合わせください。 **Source:** [https://ja.developer.box.com/sdks-and-tools/](https://ja.developer.box.com/sdks-and-tools/) --- ### Search **Type:** page | **Section:** Additional Resources Search Search for Content Search for Content To get a list of items matching a search query, call the search.query(searchQuery, options… # Search - [Search for Content](#search-for-content) ## Search for Content To get a list of items matching a search query, call the [`search.query(searchQuery, options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Search.html#query) method. There are many possible options for advanced search filtering, which are documented in the [Search API Reference](https://developer.box.com/en/guides/search/). ``` // Search for PDF or Word documents matching "Mobile" client.search.query( 'Mobile', { fields: 'name,modified_at,size,extension,permissions,sync_state', file_extensions: 'pdf,doc', limit: 200, offset: 0 }) .then(results => { /* results -> { total_count: 1, entries: [ { type: 'file', id: '11111', sequence_id: '1', etag: '1', sha1: 'f89d97c5eea0a68e2cec911s932eca34a52355d2', name: 'Box for Sales - Empowering Your Mobile Worker White paper 2pg (External).pdf', description: '', size: 408979, path_collection: { total_count: 2, entries: [ { type: 'folder', id: '0', sequence_id: null, etag: null, name: 'All Files' }, { type: 'folder', id: '22222', sequence_id: '1', etag: '1', name: 'Marketing Active Work' } ] }, created_at: '2014-05-17T12:59:45-07:00', modified_at: '2014-05-17T13:00:20-07:00', trashed_at: null, purged_at: null, content_created_at: '2014-05-17T12:58:58-07:00', content_modified_at: '2014-05-17T12:58:58-07:00', created_by: { type: 'user', id: '33333', name: 'Example User', login: 'user@example.com' }, modified_by: { type: 'user', id: '33333', name: 'Example User', login: 'user@example.com' }, owned_by: { type: 'user', id: '33333', name: 'Example User', login: 'user@example.com' }, shared_link: null, parent: { type: 'folder', id: '22222', sequence_id: '1', etag: '1', name: 'Marketing Active Work' }, item_status: 'active' } ], limit: 200, offset: 0 } */ }); ``` ``` // Search for all Powerpoint presentations with the TopSecret metadata applied client.search.query( '', { file_extensions: 'ppt,pptx', mdfilters: [ { templateKey: 'TopSecret', scope: 'enterprise', filters: {} } ] }) .then(results => { // ... }); ``` --- ### Search **Type:** page | **Section:** Additional Resources Search Different examples of search which have been implemented in the example SearchExamplesAsAppUser.java For more information refer to… # Search Different examples of search which have been implemented in the example [SearchExamplesAsAppUser.java](https://github.com/box/box-java-sdk/blob/main/src/example/java/com/box/sdk/example/SearchExamplesAsAppUser.java) For more information refer to the [Search API documentation](https://developer.box.com/v2.0/reference#searching-for-content). - [Search](#search) ## Search A search can be performed in your Box instance with specified starting position with [`searchRange(long offset, long limit, BoxSearchParameters queryParams)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxSearch.html#searchRange-long-long-com.box.sdk.BoxSearchParameters-) You can use the `limit` and `offset` parameters to page through the search results. ``` // Find the first 10 files matching "taxes" long offsetValue = 0; long limitValue = 10; BoxSearch boxSearch = new BoxSearch(api); BoxSearchParameters searchParams = new BoxSearchParameters(); searchParams.setQuery("taxes"); searchParams.setType("file"); PartialCollection<BoxItem.Info> searchResults = boxSearch.searchRange(offsetValue, limitValue, searchParams); ``` You can also sort the search results with the `sort` and `direction` flags passed into BoxSearch. This allows for the order of items returned to be maintained. The `sort` field can only be set to `modified_at` currently. For direction you can specify either `DESC` for descending order or `ASC` for ascending order to sort the results. ``` long offsetValue = 0; long limitValue = 10; BoxSearch boxSearch = new BoxSearch(api); BoxSearchParameters searchParams = new BoxSearchParameters(); searchParams.setQuery("taxes"); searchParams.setSort("modified_at"); searchParams.setDirection("DESC"); PartialCollection<BoxItem.Info> searchResults = boxSearch.searchRange(offsetValue, limitValue, searchParams); ``` --- ### Search **Type:** page | **Section:** Additional Resources Search Search provides a powerful way of finding items that are accessible by a single user or an entire enterprise. Search for Content… # Search Search provides a powerful way of finding items that are accessible by a single user or an entire enterprise. - [Search for Content](#search-for-content) - [Metadata Query](#metadata-query) ## Search for Content To get a list of items matching a search query, call [`search.query(query, limit=None, offset=0, ancestor_folders=None, file_extensions=None, metadata_filters=None, result_type=None, content_types=None, scope=None, created_at_range=None, updated_at_range=None, size_range=None, owner_users=None, trash_content=None, fields=None, sort=None, direction=None, **kwargs)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.search.Search.query) will return an `Iterable` that allows you to iterate over the [`Item`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.item.Item) objects in the collection. ``` items = client.search().query(query='TEST QUERY', limit=100, file_extensions=['pdf', 'doc']) for item in items: print(f'The item ID is {item.id} and the item name is {item.name}') ``` ### Metadata Search To filter by metadata in your search, first create [`MetadataSearchFilter`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.search.MetadataSearchFilter) object with the specified `template_key` and `scope` as well as adding filter, `field_key` and `value` with [`metadata_filter.add_value_based_filter(field_key, value)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.search.MetadataSearchFilter.add_value_based_filter). Next, create a [`MetadataSearchFilters`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.search.MetadataSearchFilters) object and call [`metadata_filters.add_filter(metadata_filter)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.search.MetadataSearchFilters.add_filter) and pass in the [`MetadataSearchFilter`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.search.MetadataSearchFilter) object created earlier. Finally, call [`search.query(query, metadata_filters=None, **kwargs)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.search.Search.query) with [`MetadataSearchFilters`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.search.MetadataSearchFilters) object passed in. ``` from boxsdk.object.search import MetadataSearchFilter, MetadataSearchFilters metadata_search_filter = MetadataSearchFilter(template_key='marketingCollateral', scope='enterprise') metadata_search_filter.add_value_based_filter(field_key='documentType', value='datasheet') metadata_search_filter.add_value_based_filter(field_key='clientNumber', value='a123') metadata_search_filters = MetadataSearchFilters() metadata_search_filters.add_filter(metadata_search_filter) client.search().query(None, limit=100, offset=0, metadata_filters=metadata_search_filters) ``` ### Search with Shared Link Items To get a list of items matching a search query, including items that a user might have accessed recently through a shared link, call [`search.query_with_shared_links(query, limit=None, offset=0, ancestor_folders=None, file_extensions=None, metadata_filters=None, result_type=None, content_types=None, scope=None, created_at_range=None, updated_at_range=None, size_range=None, owner_users=None, trash_content=None, fields=None, sort=None, direction=None, **kwargs)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.search.Search.query_with_shared_links). This method will return an `Iterable` that allows you to iterate over the search result objects in the collection. ``` search_results = client.search().query_with_shared_links(query='TEST QUERY', limit=100, file_extensions=['pdf', 'doc']) for search_result in search_results: print(f'The item ID is {search_result.item.id} and the item name is {search_result.item.name}') ``` ## Metadata Query To search using SQL-like syntax to return items that match specific metadata, call `search.metadata_query(from_template, ancestor_folder_id, query=None, query_params=None, use_index=None, order_by=None, marker=None, limit=None, fields=None)` **Note:** paramter `use_index` is deprecated and if provided, will be ignored. The current way to create an index is to contact the MDQ team directly via email. MDQ will now use static query analysis to use the index that is most efficient for the call. By default, this method returns only the most basic info about the items for which the query matches. To get additional fields for each item, including any of the metadata, use the fields parameter. ``` from_template = 'enterprise_12345.someTemplate' ancestor_folder_id = '5555' query = 'amount >= :arg' query_params = {'arg': 100} order_by = [ { 'field_key': 'amount', 'direction': 'asc' } ] fields = ['type', 'id', 'name', 'metadata.enterprise_67890.catalogImages.$parent'] limit = 2 marker = 'AAAAAmVYB1FWec8GH6yWu2nwmanfMh07IyYInaa7DZDYjgO1H4KoLW29vPlLY173OKs' items = client.search().metadata_query( from_template=from_template, ancestor_folder_id=ancestor_folder_id, query=query, query_params=query_params, order_by=order_by, marker=marker, limit=limit, fields=fields ) for item in items: print(f'The item ID is {item.id} and the item name is {item.name}') ``` --- ### Search **Type:** page | **Section:** Additional Resources Search Search for Content Search for Content with Shared Link Items Metadata Search Search for Content To get a list of items matching a… # Search [Search for Content](#search-for-content) - [Search for Content with Shared Link Items](#search-for-content-with-shared-link-items) - [Metadata Search](#metadata-search) ## Search for Content To get a list of items matching a search query, call the ``` SearchManager.QueryAsync(string query, string scope = null, IEnumerable<string> fileExtensions = null, DateTime? createdAfter = null, DateTime? createdBefore = null, DateTime? updatedAfter = null, DateTime? updatedBefore = null, long? sizeLowerBound = null, long? sizeUpperBound = null, IEnumerable<string> ownerUserIds = null, IEnumerable<string> ancestorFolderIds = null, IEnumerable<string> contentTypes = null, string type = null, string trashContent = null, List<BoxMetadataFilterRequest> mdFilters = null, int limit = 30, int offset = 0, IEnumerable<string> fields = null, string sort = null, BoxSortDirection? direction = null) ``` method. There are many possible options for advanced search filtering, which are documented in the [Search API Reference](https://developer.box.com/en/guides/search/). For most types of searches, a query string is required; for example, it is not possible to search for all files created after a certain date through the Search API. ``` // Search for PDF or Word documents matching "Meeting Notes" BoxCollection<BoxItem> results = await client.SearchManager .QueryAsync("Meeting Notes", fileExtensions: new { "pdf", "docx" }); ``` ## Search for Content with Shared Link Items To get a list of items matching a search query, including items that a user might have accessed recently through a shared link, call the ``` SearchManager.QueryAsyncWithSharedLinks(string query, string scope = null, IEnumerable<string> fileExtensions = null, DateTime? createdAfter = null, DateTime? createdBefore = null, DateTime? updatedAfter = null, DateTime? updatedBefore = null, long? sizeLowerBound = null, long? sizeUpperBound = null, IEnumerable<string> ownerUserIds = null, IEnumerable<string> ancestorFolderIds = null, IEnumerable<string> contentTypes = null, string type = null, string trashContent = null, List<BoxMetadataFilterRequest> mdFilters = null, int limit = 30, int offset = 0, IEnumerable<string> fields = null, string sort = null, BoxSortDirection? direction = null) ``` method. There are many possible options for advanced search filtering, which are documented in the [Search API Reference](https://developer.box.com/en/guides/search/). For most types of searches, a query string is required. ``` // Search for PDF or Word documents matching "Meeting Notes" BoxCollection<BoxSearchResult> results = await client.SearchManager .QueryAsyncWithSharedLinks("Meeting Notes", fileExtensions: new { "pdf", "docx" }); ``` ### Metadata Search When searching on metadata values, a search query string is not required and can be set to `null`. ``` // Search for all Powerpoint presentations with the TopSecret metadata applied var metadataFilters = new List<BoxMetadataFilterRequest>() { new BoxMetadataFilterRequest() { TemplateKey = "TopSecret", Scope = "enterprise" } }; BoxCollection<BoxItem> results = await client.SearchManager .QueryAsync(null, fileExtensions: new { "pptx" }, mdFilters: metadataFilters); ``` --- ### Search **Type:** page | **Section:** Additional Resources Search Content Search Content Search with Shared Link Items Metadata Search Content Search To get a list of items matching a search query… # Search - [Content Search](#content-search) - [Content Search with Shared Link Items](#content-search-with-shared-link-items) - [Metadata Search](#metadata-search) ## Content Search To get a list of items matching a search query, call [`client.search.query(query:...)`](https://opensource.box.com/box-ios-sdk/Classes/SearchModule.html#/s:6BoxSDK12SearchModuleC5queryAD5scope14fileExtensions12createdAfter0I6Before07updatedJ00lK011sizeAtLeast0mN4Most12ownerUserIDs014ancestorFolderS08searchIn8itemType0V5Trash14metadataFilter6fields6offset5limit10completionySSSg_AA0C5ScopeOSgSaySSGSg10Foundation4DateVSgA4_A4_A4_s5Int64VSgA7_A0_A0_SayAA0c7ContentY0OGSgAA0c4ItemY0OSgSbSgAA08MetadataC6FilterCSgA0_SiSgA19_ys6ResultOyAA14PagingIteratorCyAA0U4ItemOGAA0A8SDKErrorCGctF) with the string to query for. There are many possible options for advanced search filtering, which can be used to narrow down the search results. This method will return an iterator object, which is used to get the results. ``` let iterator = client.search.query(query: "Quarterly Business Review") iterator.next { results in switch results { case let .success(page): for item in page.entries { switch item { case let .file(file): print("- File \(file.name) (ID: \(file.id))") case let .folder(folder): print("- Folder \(file.name) (ID: \(file.id))") case let .webLink(webLink): print("- Web Link \(file.name) (ID: \(file.id))") } } case let .failure(error): print(error) } } ``` ## Content Search with Shared Link Items To get a list of items matching a search query, including items that a user might have accessed recently through a shared link, call [`client.search.queryWithSharedLinks(query:...)`](https://opensource.box.com/box-ios-sdk/Classes/SearchModule.html#/s:6BoxSDK12SearchModuleC5queryAD5scope14fileExtensions12createdAfter0I6Before07updatedJ00lK011sizeAtLeast0mN4Most12ownerUserIDs014ancestorFolderS08searchIn8itemType0V5Trash14metadataFilter6fields6offset5limit10completionySSSg_AA0C5ScopeOSgSaySSGSg10Foundation4DateVSgA4_A4_A4_s5Int64VSgA7_A0_A0_SayAA0c7ContentY0OGSgAA0c4ItemY0OSgSbSgAA08MetadataC6FilterCSgA0_SiSgA19_ys6ResultOyAA14PagingIteratorCyAA0U4ItemOGAA0A8SDKErrorCGctF) with the string to query for. There are many possible options for advanced search filtering, which can be used to narrow down the search results. This method will return an iterator object, which is used to get the results. ``` let iterator = client.search.queryWithSharedLinks(query: "Quarterly Business Review") iterator.next { results in switch results { case let .success(page): for searchResult in page.entries { let item = searchResult.item switch item { case let .file(file): print("- File \(file.name) (ID: \(file.id))") case let .folder(folder): print("- Folder \(file.name) (ID: \(file.id))") case let .webLink(webLink): print("- Web Link \(file.name) (ID: \(file.id))") } } case let .failure(error): print(error) } } ``` ## Metadata Search To search within metadata for specific values, use the helper methods included in the SDK to construct the metadata query and call [`client.search.query(query:...)`](https://opensource.box.com/box-ios-sdk/Classes/SearchModule.html#/s:6BoxSDK12SearchModuleC5queryAD5scope14fileExtensions12createdAfter0I6Before07updatedJ00lK011sizeAtLeast0mN4Most12ownerUserIDs014ancestorFolderS08searchIn8itemType0V5Trash14metadataFilter6fields6offset5limit10completionySSSg_AA0C5ScopeOSgSaySSGSg10Foundation4DateVSgA4_A4_A4_s5Int64VSgA7_A0_A0_SayAA0c7ContentY0OGSgAA0c4ItemY0OSgSbSgAA08MetadataC6FilterCSgA0_SiSgA19_ys6ResultOyAA14PagingIteratorCyAA0U4ItemOGAA0A8SDKErrorCGctF) with the metadata filters and optionally a search query. If no additional content query string is needed, just set the `query` parameter to `nil`. This method will return an iterator object, which is used to get the results. ``` let metadataFilters = MetadataSearchFilter() metadataFilters.addFilter(templateKey: "contract", fieldKey: "contractType", fieldValue: "NDA") metadataFilters.addFilter(templateKey: "contract", fieldKey: "date", fieldValue: "2019-01-01T00:00:00Z", relation: .greaterThan) let iterator = client.search.query(query: nil, metadataFilter: metadataFilters) iterator.next { results in switch results { case let .success(page): for item in page.entries { switch item { case let .file(file): print("- File \(file.name) (ID: \(file.id))") case let .folder(folder): print("- Folder \(file.name) (ID: \(file.id))") case let .webLink(webLink): print("- Web Link \(file.name) (ID: \(file.id))") } } case let .failure(error): print(error) } } ``` --- ### Search **Type:** page | **Section:** Additional Resources Search Content Search Content Search with Shared Link Items Metadata Search Content Search To get a list of items matching a search query… # Search - [Content Search](#content-search) - [Content Search with Shared Link Items](#content-search-with-shared-link-items) - [Metadata Search](#metadata-search) ## Content Search To get a list of items matching a search query, call [`client.search.query(query:...)`](https://opensource.box.com/box-ios-sdk/Classes/SearchModule.html#/s:6BoxSDK12SearchModuleC5queryAD5scope14fileExtensions12createdAfter0I6Before07updatedJ00lK011sizeAtLeast0mN4Most12ownerUserIDs014ancestorFolderS08searchIn8itemType0V5Trash14metadataFilter6fields6offset5limit10completionySSSg_AA0C5ScopeOSgSaySSGSg10Foundation4DateVSgA4_A4_A4_s5Int64VSgA7_A0_A0_SayAA0c7ContentY0OGSgAA0c4ItemY0OSgSbSgAA08MetadataC6FilterCSgA0_SiSgA19_ys6ResultOyAA14PagingIteratorCyAA0U4ItemOGAA0A8SDKErrorCGctF) with the string to query for. There are many possible options for advanced search filtering, which can be used to narrow down the search results. This method will return an iterator object, which is used to get the results. ``` let iterator = client.search.query(query: "Quarterly Business Review") iterator.next { results in switch results { case let .success(page): for item in page.entries { switch item { case let .file(file): print("- File \(file.name) (ID: \(file.id))") case let .folder(folder): print("- Folder \(file.name) (ID: \(file.id))") case let .webLink(webLink): print("- Web Link \(file.name) (ID: \(file.id))") } } case let .failure(error): print(error) } } ``` ## Content Search with Shared Link Items To get a list of items matching a search query, including items that a user might have accessed recently through a shared link, call [`client.search.queryWithSharedLinks(query:...)`](https://opensource.box.com/box-ios-sdk/Classes/SearchModule.html#/s:6BoxSDK12SearchModuleC5queryAD5scope14fileExtensions12createdAfter0I6Before07updatedJ00lK011sizeAtLeast0mN4Most12ownerUserIDs014ancestorFolderS08searchIn8itemType0V5Trash14metadataFilter6fields6offset5limit10completionySSSg_AA0C5ScopeOSgSaySSGSg10Foundation4DateVSgA4_A4_A4_s5Int64VSgA7_A0_A0_SayAA0c7ContentY0OGSgAA0c4ItemY0OSgSbSgAA08MetadataC6FilterCSgA0_SiSgA19_ys6ResultOyAA14PagingIteratorCyAA0U4ItemOGAA0A8SDKErrorCGctF) with the string to query for. There are many possible options for advanced search filtering, which can be used to narrow down the search results. This method will return an iterator object, which is used to get the results. ``` let iterator = client.search.queryWithSharedLinks(query: "Quarterly Business Review") iterator.next { results in switch results { case let .success(page): for searchResult in page.entries { let item = searchResult.item switch item { case let .file(file): print("- File \(file.name) (ID: \(file.id))") case let .folder(folder): print("- Folder \(file.name) (ID: \(file.id))") case let .webLink(webLink): print("- Web Link \(file.name) (ID: \(file.id))") } } case let .failure(error): print(error) } } ``` ## Metadata Search To search within metadata for specific values, use the helper methods included in the SDK to construct the metadata query and call [`client.search.query(query:...)`](https://opensource.box.com/box-ios-sdk/Classes/SearchModule.html#/s:6BoxSDK12SearchModuleC5queryAD5scope14fileExtensions12createdAfter0I6Before07updatedJ00lK011sizeAtLeast0mN4Most12ownerUserIDs014ancestorFolderS08searchIn8itemType0V5Trash14metadataFilter6fields6offset5limit10completionySSSg_AA0C5ScopeOSgSaySSGSg10Foundation4DateVSgA4_A4_A4_s5Int64VSgA7_A0_A0_SayAA0c7ContentY0OGSgAA0c4ItemY0OSgSbSgAA08MetadataC6FilterCSgA0_SiSgA19_ys6ResultOyAA14PagingIteratorCyAA0U4ItemOGAA0A8SDKErrorCGctF) with the metadata filters and optionally a search query. If no additional content query string is needed, just set the `query` parameter to `nil`. This method will return an iterator object, which is used to get the results. ``` let metadataFilters = MetadataSearchFilter() metadataFilters.addFilter(templateKey: "contract", fieldKey: "contractType", fieldValue: "NDA") metadataFilters.addFilter(templateKey: "contract", fieldKey: "date", fieldValue: "2019-01-01T00:00:00Z", relation: .greaterThan) let iterator = client.search.query(query: nil, metadataFilter: metadataFilters) iterator.next { results in switch results { case let .success(page): for item in page.entries { switch item { case let .file(file): print("- File \(file.name) (ID: \(file.id))") case let .folder(folder): print("- Folder \(file.name) (ID: \(file.id))") case let .webLink(webLink): print("- Web Link \(file.name) (ID: \(file.id))") } } case let .failure(error): print(error) } } ``` --- ### SearchManager **Type:** page | **Section:** Additional Resources SearchManager Query files/folders by metadata Search for content Query files/folders by metadata Create a search using SQL-like syntax to… # SearchManager - [Query files/folders by metadata](#query-files-folders-by-metadata) - [Search for content](#search-for-content) ## Query files/folders by metadata Create a search using SQL-like syntax to return items that match specific metadata. By default, this endpoint returns only the most basic info about the items for which the query matches. To get additional fields for each item, including any of the metadata, use the `fields` attribute in the query. This operation is performed by calling function `searchByMetadataQuery`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-metadata-queries-execute-read/). ``` await client.search.searchByMetadataQuery({ ancestorFolderId: '0', from: searchFrom, query: 'name = :name AND age < :age AND birthDate >= :birthDate AND countryCode = :countryCode AND sports = :sports', queryParams: { ['name']: 'John', ['age']: 50, ['birthDate']: '2001-01-01T02:20:10.120Z', ['countryCode']: 'US', ['sports']: ['basketball', 'tennis'], }, } satisfies MetadataQuery); ``` ### Arguments requestBody `MetadataQuery` - Request body of searchByMetadataQuery method optionalsInput `SearchByMetadataQueryOptionalsInput` ### Returns This function returns a value of type `MetadataQueryResults`. Returns a list of files and folders that match this metadata query. ## Search for content Searches for files, folders, web links, and shared files across the users content or across the entire enterprise. This operation is performed by calling function `searchForContent`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-search/). ``` await client.search.searchForContent({ ancestorFolderIds: ['0'], mdfilters: [ { filters: searchFilters, scope: 'enterprise' as MetadataFilterScopeField, templateKey: templateKey, } satisfies MetadataFilter, ], } satisfies SearchForContentQueryParams); ``` ### Arguments queryParams `SearchForContentQueryParams` - Query parameters of searchForContent method headersInput `SearchForContentHeadersInput` - Headers of searchForContent method cancellationToken `undefined | CancellationToken` - Token used for request cancellation. ### Returns This function returns a value of type `SearchResultsOrSearchResultsWithSharedLinks`. Returns a collection of search results. If there are no matching search results, the `entries` array will be empty. --- ### SearchManager **Type:** page | **Section:** Additional Resources SearchManager Query files/folders by metadata Search for content Query files/folders by metadata Create a search using SQL-like syntax to… # SearchManager - [Query files/folders by metadata](#query-files-folders-by-metadata) - [Search for content](#search-for-content) ## Query files/folders by metadata Create a search using SQL-like syntax to return items that match specific metadata. By default, this endpoint returns only the most basic info about the items for which the query matches. To get additional fields for each item, including any of the metadata, use the `fields` attribute in the query. This operation is performed by calling function `search_by_metadata_query`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-metadata-queries-execute-read/). ``` client.search.search_by_metadata_query( search_from, "0", query="name = :name AND age < :age AND birthDate >= :birthDate AND countryCode = :countryCode AND sports = :sports", query_params={ "name": "John", "age": 50, "birthDate": "2001-01-01T02:20:10.120Z", "countryCode": "US", "sports": ["basketball", "tennis"], }, ) ``` ### Arguments from_ `str` - Specifies the template used in the query. Must be in the form `scope.templateKey`. Not all templates can be used in this field, most notably the built-in, Box-provided classification templates can not be used in a query. query `Optional[str]` - The query to perform. A query is a logical expression that is very similar to a SQL `SELECT` statement. Values in the search query can be turned into parameters specified in the `query_param` arguments list to prevent having to manually insert search values into the query string. For example, a value of `:amount` would represent the `amount` value in `query_params` object. query_params `Optional[Dict]` - Set of arguments corresponding to the parameters specified in the `query`. The type of each parameter used in the `query_params` must match the type of the corresponding metadata template field. ancestor_folder_id `str` - The ID of the folder that you are restricting the query to. A value of zero will return results from all folders you have access to. A non-zero value will only return results found in the folder corresponding to the ID or in any of its subfolders. order_by `Optional[List[SearchByMetadataQueryOrderBy]]` - A list of template fields and directions to sort the metadata query results by. The ordering `direction` must be the same for each item in the array. limit `Optional[int]` - A value between 0 and 100 that indicates the maximum number of results to return for a single request. This only specifies a maximum boundary and will not guarantee the minimum number of results returned. marker `Optional[str]` - Marker to use for requesting the next page. fields `Optional[List[str]]` - By default, this endpoint returns only the most basic info about the items for which the query matches. This attribute can be used to specify a list of additional attributes to return for any item, including its metadata. This attribute takes a list of item fields, metadata template identifiers, or metadata template field identifiers. For example: _ `created_by` will add the details of the user who created the item to the response. _ `metadata.<scope>.<templateKey>` will return the mini-representation of the metadata instance identified by the `scope` and `templateKey`. * `metadata.<scope>.<templateKey>.<field>` will return all the mini-representation of the metadata instance identified by the `scope` and `templateKey` plus the field specified by the `field` name. Multiple fields for the same `scope` and `templateKey` can be defined. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `MetadataQueryResults`. Returns a list of files and folders that match this metadata query. ## Search for content Searches for files, folders, web links, and shared files across the users content or across the entire enterprise. This operation is performed by calling function `search_for_content`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-search/). ``` client.search.search_for_content( ancestor_folder_ids=["0"], mdfilters=[ MetadataFilter( filters=search_filters, scope=MetadataFilterScopeField.ENTERPRISE, template_key=template_key, ) ], ) ``` ### Arguments query `Optional[str]` - The string to search for. This query is matched against item names, descriptions, text content of files, and various other fields of the different item types. This parameter supports a variety of operators to further refine the results returns. _ `""` - by wrapping a query in double quotes only exact matches are returned by the API. Exact searches do not return search matches based on specific character sequences. Instead, they return matches based on phrases, that is, word sequences. For example: A search for `"Blue-Box"` may return search results including the sequence `"blue.box"`, `"Blue Box"`, and `"Blue-Box"`; any item containing the words `Blue` and `Box` consecutively, in the order specified. _ `AND` - returns items that contain both the search terms. For example, a search for `marketing AND BoxWorks` returns items that have both `marketing` and `BoxWorks` within its text in any order. It does not return a result that only has `BoxWorks` in its text. _ `OR` - returns items that contain either of the search terms. For example, a search for `marketing OR BoxWorks` returns a result that has either `marketing` or `BoxWorks` within its text. Using this operator is not necessary as we implicitly interpret multi-word queries as `OR` unless another supported boolean term is used. _ `NOT` - returns items that do not contain the search term provided. For example, a search for `marketing AND NOT BoxWorks` returns a result that has only `marketing` within its text. Results containing `BoxWorks` are omitted. We do not support lower case (that is, `and`, `or`, and `not`) or mixed case (that is, `And`, `Or`, and `Not`) operators. This field is required unless the `mdfilters` parameter is defined. scope `Optional[SearchForContentScope]` - Limits the search results to either the files that the user has access to, or to files available to the entire enterprise. The scope defaults to `user_content`, which limits the search results to content that is available to the currently authenticated user. The `enterprise_content` can be requested by an admin through our support channels. Once this scope has been enabled for a user, it will allow that use to query for content across the entire enterprise and not only the content that they have access to. file_extensions `Optional[List[str]]` - Limits the search results to any files that match any of the provided file extensions. This list is a comma-separated list of file extensions without the dots. created_at_range `Optional[List[str]]` - Limits the search results to any items created within a given date range. Date ranges are defined as comma separated RFC3339 timestamps. If the the start date is omitted (`,2014-05-17T13:35:01-07:00`) anything created before the end date will be returned. If the end date is omitted (`2014-05-15T13:35:01-07:00,`) the current date will be used as the end date instead. updated_at_range `Optional[List[str]]` - Limits the search results to any items updated within a given date range. Date ranges are defined as comma separated RFC3339 timestamps. If the start date is omitted (`,2014-05-17T13:35:01-07:00`) anything updated before the end date will be returned. If the end date is omitted (`2014-05-15T13:35:01-07:00,`) the current date will be used as the end date instead. size_range `Optional[List[int]]` - Limits the search results to any items with a size within a given file size range. This applied to files and folders. Size ranges are defined as comma separated list of a lower and upper byte size limit (inclusive). The upper and lower bound can be omitted to create open ranges. owner_user_ids `Optional[List[str]]` - Limits the search results to any items that are owned by the given list of owners, defined as a list of comma separated user IDs. The items still need to be owned or shared with the currently authenticated user for them to show up in the search results. If the user does not have access to any files owned by any of the users an empty result set will be returned. To search across an entire enterprise, we recommend using the `enterprise_content` scope parameter which can be requested with our support team. recent_updater_user_ids `Optional[List[str]]` - Limits the search results to any items that have been updated by the given list of users, defined as a list of comma separated user IDs. The items still need to be owned or shared with the currently authenticated user for them to show up in the search results. If the user does not have access to any files owned by any of the users an empty result set will be returned. This feature only searches back to the last 10 versions of an item. ancestor_folder_ids `Optional[List[str]]` - Limits the search results to items within the given list of folders, defined as a comma separated lists of folder IDs. Search results will also include items within any subfolders of those ancestor folders. The folders still need to be owned or shared with the currently authenticated user. If the folder is not accessible by this user, or it does not exist, a `HTTP 404` error code will be returned instead. To search across an entire enterprise, we recommend using the `enterprise_content` scope parameter which can be requested with our support team. content_types `Optional[List[SearchForContentContentTypes]]` - Limits the search results to any items that match the search query for a specific part of the file, for example the file description. Content types are defined as a comma separated lists of Box recognized content types. The allowed content types are as follows. _ `name` - The name of the item, as defined by its `name` field. _ `description` - The description of the item, as defined by its `description` field. _ `file_content` - The actual content of the file. _ `comments` - The content of any of the comments on a file or folder. * `tags` - Any tags that are applied to an item, as defined by its `tags` field. type `Optional[SearchForContentType]` - Limits the search results to any items of this type. This parameter only takes one value. By default the API returns items that match any of these types. _ `file` - Limits the search results to files, _ `folder` - Limits the search results to folders, * `web_link` - Limits the search results to web links, also known as bookmarks. trash_content `Optional[SearchForContentTrashContent]` - Determines if the search should look in the trash for items. By default, this API only returns search results for items not currently in the trash (`non_trashed_only`). _ `trashed_only` - Only searches for items currently in the trash _ `non_trashed_only` - Only searches for items currently not in the trash * `all_items` - Searches for both trashed and non-trashed items. mdfilters `Optional[List[MetadataFilter]]` - Limits the search results to any items for which the metadata matches the provided filter. This parameter is a list that specifies exactly **one** metadata template used to filter the search results. The parameter is required unless the `query` parameter is provided. sort `Optional[SearchForContentSort]` - Defines the order in which search results are returned. This API defaults to returning items by relevance unless this parameter is explicitly specified. _ `relevance` (default) returns the results sorted by relevance to the query search term. The relevance is based on the occurrence of the search term in the items name, description, content, and additional properties. _ `modified_at` returns the results ordered in descending order by date at which the item was last modified. direction `Optional[SearchForContentDirection]` - Defines the direction in which search results are ordered. This API defaults to returning items in descending (`DESC`) order unless this parameter is explicitly specified. When results are sorted by `relevance` the ordering is locked to returning items in descending order of relevance, and this parameter is ignored. limit `Optional[int]` - Defines the maximum number of items to return as part of a page of results. include_recent_shared_links `Optional[bool]` - Defines whether the search results should include any items that the user recently accessed through a shared link. When this parameter has been set to true, the format of the response of this API changes to return a list of [Search Results with Shared Links](r://search_results_with_shared_links). fields `Optional[List[str]]` - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested. offset `Optional[int]` - The offset of the item at which to begin the response. Queries with offset parameter value exceeding 10000 will be rejected with a 400 response. deleted_user_ids `Optional[List[str]]` - Limits the search results to items that were deleted by the given list of users, defined as a list of comma separated user IDs. The `trash_content` parameter needs to be set to `trashed_only`. If searching in trash is not performed, an empty result set is returned. The items need to be owned or shared with the currently authenticated user for them to show up in the search results. If the user does not have access to any files owned by any of the users, an empty result set is returned. Data available from 2023-02-01 onwards. deleted_at_range `Optional[List[str]]` - Limits the search results to any items deleted within a given date range. Date ranges are defined as comma separated RFC3339 timestamps. If the the start date is omitted (`2014-05-17T13:35:01-07:00`), anything deleted before the end date will be returned. If the end date is omitted (`2014-05-15T13:35:01-07:00`), the current date will be used as the end date instead. The `trash_content` parameter needs to be set to `trashed_only`. If searching in trash is not performed, then an empty result is returned. Data available from 2023-02-01 onwards. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `Union[SearchResults, SearchResultsWithSharedLinks]`. Returns a collection of search results. If there are no matching search results, the `entries` array will be empty. --- ### SessionTerminationManager **Type:** page | **Section:** Additional Resources SessionTerminationManager Create jobs to terminate users session Create jobs to terminate user group session Create jobs to terminate users… # SessionTerminationManager - [Create jobs to terminate users session](#create-jobs-to-terminate-users-session) - [Create jobs to terminate user group session](#create-jobs-to-terminate-user-group-session) ## Create jobs to terminate users session Validates the roles and permissions of the user, and creates asynchronous jobs to terminate the user's sessions. Returns the status for the POST request. This operation is performed by calling function `terminateUsersSessions`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-users-terminate-sessions/). ``` await client.sessionTermination.terminateUsersSessions({ userIds: [getEnvVar('USER_ID')], userLogins: [user.login!], } satisfies TerminateUsersSessionsRequestBody); ``` ### Arguments requestBody `TerminateUsersSessionsRequestBody` - Request body of terminateUsersSessions method optionalsInput `TerminateUsersSessionsOptionalsInput` ### Returns This function returns a value of type `SessionTerminationMessage`. Returns a message about the request status. ## Create jobs to terminate user group session Validates the roles and permissions of the group, and creates asynchronous jobs to terminate the group's sessions. Returns the status for the POST request. This operation is performed by calling function `terminateGroupsSessions`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-groups-terminate-sessions/). ``` await client.sessionTermination.terminateGroupsSessions({ groupIds: [group.id], } satisfies TerminateGroupsSessionsRequestBody); ``` ### Arguments requestBody `TerminateGroupsSessionsRequestBody` - Request body of terminateGroupsSessions method optionalsInput `TerminateGroupsSessionsOptionalsInput` ### Returns This function returns a value of type `SessionTerminationMessage`. Returns a message about the request status. --- ### SessionTerminationManager **Type:** page | **Section:** Additional Resources SessionTerminationManager Create jobs to terminate users session Create jobs to terminate user group session Create jobs to terminate users… # SessionTerminationManager - [Create jobs to terminate users session](#create-jobs-to-terminate-users-session) - [Create jobs to terminate user group session](#create-jobs-to-terminate-user-group-session) ## Create jobs to terminate users session Validates the roles and permissions of the user, and creates asynchronous jobs to terminate the user's sessions. Returns the status for the POST request. This operation is performed by calling function `terminate_users_sessions`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-users-terminate-sessions/). ``` client.session_termination.terminate_users_sessions( [get_env_var("USER_ID")], [user.login] ) ``` ### Arguments user_ids `List[str]` - A list of user IDs. user_logins `List[str]` - A list of user logins. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `SessionTerminationMessage`. Returns a message about the request status. ## Create jobs to terminate user group session Validates the roles and permissions of the group, and creates asynchronous jobs to terminate the group's sessions. Returns the status for the POST request. This operation is performed by calling function `terminate_groups_sessions`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-groups-terminate-sessions/). ``` client.session_termination.terminate_groups_sessions([group.id]) ``` ### Arguments group_ids `List[str]` - A list of group IDs. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `SessionTerminationMessage`. Returns a message about the request status. --- ### Shared Items **Type:** page | **Section:** Additional Resources Shared Items Shared Items represent files and folders on Box accessed via a shared link. Get a Shared Item Get a Shared Item To get the file… # Shared Items Shared Items represent files and folders on Box accessed via a shared link. - [Get a Shared Item](#get-a-shared-item) ## Get a Shared Item To get the file or folder information for a shared link, call the [`sharedItems.get(url, password, options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/SharedItems.html#get) method. The `password` parameter should be passed as a `null` value if none is required. ``` client.sharedItems.get( 'https://app.box.com/s/1a2b3c4d5e', null, {fields: 'type,id,parent,extension,shared_link'}, callback ); ``` --- ### Shared Items **Type:** page | **Section:** Additional Resources Shared Items Shared Items represent files and folders on Box accessed via a shared link. Get a Shared Item Get a Shared Item To get the file… # Shared Items Shared Items represent files and folders on Box accessed via a shared link. - [Get a Shared Item](#get-a-shared-item) ## Get a Shared Item To get the file or folder information for a shared link, you can call [`BoxItem.getSharedItem(BoxAPIConnection api, String sharedLink)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxItem.html#getSharedItem-com.box.sdk.BoxAPIConnection-java.lang.String-) with the shared link to get information about the item behind it. ``` String sharedLink = "https://app.box.com/s/abcdefghijklmnopqrstuvwxyz123456"; BoxItem.Info itemInfo = BoxItem.getSharedItem(api, sharedLink); ``` If the shared link is password-protected, call [`BoxItem.getSharedItem(BoxAPIConnection api, String sharedLink, String password)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxItem.html#getSharedItem-com.box.sdk.BoxAPIConnection-java.lang.String-java.lang.String-) with the shared link and password. ``` String sharedLink = "https://app.box.com/s/abcdefghijklmnopqrstuvwxyz123456"; String password = "foo"; BoxItem.Info itemInfo = BoxItem.getSharedItem(api, sharedLink, password); ``` --- ### Shared Items **Type:** page | **Section:** Additional Resources Shared Items Shared Items represent files and folders on Box available via a shared link. Get Shared Item Get Shared Item To get the file or… # Shared Items Shared Items represent files and folders on Box available via a shared link. - [Get Shared Item](#get-shared-item) ## Get Shared Item To get the file or folder information for a shared link, call [`client.sharedItems.getSharedItem(sharedLinkURL:sharedLinkPassword:fields:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/SharedItemsModule.html#/s:6BoxSDK17SharedItemsModuleC3get13sharedLinkURL0gH8Password6fields10completionySS_SSSgSaySSGSgys6ResultOyAA0C4ItemCAA0A8SDKErrorCGctF) with the URL of the shared link. The `sharedLinkPassword` parameter should be provided if the shared link is password-protected. ``` client.sharedItems.get( sharedLinkURL: "https://app.box.com/s/qqwertyuiopasdfghjklzxcvbnm123456" ) { (result: Result<SharedItem, BoxSDKError>) in guard case let .success(item) = result else { print("Error resolving shared item") return } print("The shared link resolves to item:") switch item { case let .file(file): print("- File \(file.name) (ID: \(file.id))") case let .folder(folder): print("- Folder \(file.name) (ID: \(file.id))") case let .webLink(webLink): print("- Web Link \(file.name) (ID: \(file.id))") } } ``` --- ### Shared Items **Type:** page | **Section:** Additional Resources Shared Items Shared Items represent files and folders on Box available via a shared link. Get Shared Item Get Shared Item To get the file or… # Shared Items Shared Items represent files and folders on Box available via a shared link. - [Get Shared Item](#get-shared-item) ## Get Shared Item To get the file or folder information for a shared link, call [`client.sharedItems.getSharedItem(sharedLinkURL:sharedLinkPassword:fields:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/SharedItemsModule.html#/s:6BoxSDK17SharedItemsModuleC3get13sharedLinkURL0gH8Password6fields10completionySS_SSSgSaySSGSgys6ResultOyAA0C4ItemCAA0A8SDKErrorCGctF) with the URL of the shared link. The `sharedLinkPassword` parameter should be provided if the shared link is password-protected. ``` client.sharedItems.get( sharedLinkURL: "https://app.box.com/s/qqwertyuiopasdfghjklzxcvbnm123456" ) { (result: Result<SharedItem, BoxSDKError>) in guard case let .success(item) = result else { print("Error resolving shared item") return } print("The shared link resolves to item:") switch item { case let .file(file): print("- File \(file.name) (ID: \(file.id))") case let .folder(folder): print("- Folder \(file.name) (ID: \(file.id))") case let .webLink(webLink): print("- Web Link \(file.name) (ID: \(file.id))") } } ``` --- ### SharedLinksAppItemsManager **Type:** page | **Section:** Additional Resources SharedLinksAppItemsManager Find app item for shared link Find app item for shared link Returns the app item represented by a shared link… # SharedLinksAppItemsManager - [Find app item for shared link](#find-app-item-for-shared-link) ## Find app item for shared link Returns the app item represented by a shared link. The link can originate from the current enterprise or another. This operation is performed by calling function `findAppItemForSharedLink`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-shared-items--app-items/). ``` await client.sharedLinksAppItems.findAppItemForSharedLink({ boxapi: ''.concat('shared_link=', appItemSharedLink) as string, } satisfies FindAppItemForSharedLinkHeadersInput); ``` ### Arguments headersInput `FindAppItemForSharedLinkHeadersInput` - Headers of findAppItemForSharedLink method optionalsInput `FindAppItemForSharedLinkOptionalsInput` ### Returns This function returns a value of type `AppItem`. Returns a full app item resource if the shared link is valid and the user has access to it. --- ### SharedLinksAppItemsManager **Type:** page | **Section:** Additional Resources SharedLinksAppItemsManager Find app item for shared link Find app item for shared link Returns the app item represented by a shared link… # SharedLinksAppItemsManager - [Find app item for shared link](#find-app-item-for-shared-link) ## Find app item for shared link Returns the app item represented by a shared link. The link can originate from the current enterprise or another. This operation is performed by calling function `find_app_item_for_shared_link`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-shared-items--app-items/). ``` client.shared_links_app_items.find_app_item_for_shared_link( "".join(["shared_link=", app_item_shared_link]) ) ``` ### Arguments boxapi `str` - A header containing the shared link and optional password for the shared link. The format for this header is `shared_link=[link]&shared_link_password=[password]`. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `AppItem`. Returns a full app item resource if the shared link is valid and the user has access to it. --- ### SharedLinksFilesManager **Type:** page | **Section:** Additional Resources SharedLinksFilesManager Find file for shared link Get shared link for file Add shared link to file Update shared link on file Remove shared… # SharedLinksFilesManager - [Find file for shared link](#find-file-for-shared-link) - [Get shared link for file](#get-shared-link-for-file) - [Add shared link to file](#add-shared-link-to-file) - [Update shared link on file](#update-shared-link-on-file) - [Remove shared link from file](#remove-shared-link-from-file) ## Find file for shared link Returns the file represented by a shared link. A shared file can be represented by a shared link, which can originate within the current enterprise or within another. This endpoint allows an application to retrieve information about a shared file when only given a shared link. The `shared_link_permission_options` array field can be returned by requesting it in the `fields` query parameter. This operation is performed by calling function `findFileForSharedLink`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-shared-items/). ``` await userClient.sharedLinksFiles.findFileForSharedLink( {} satisfies FindFileForSharedLinkQueryParams, { boxapi: ''.concat( 'shared_link=', fileFromApi.sharedLink!.url, '&shared_link_password=Secret123@', ) as string, } satisfies FindFileForSharedLinkHeadersInput, ); ``` ### Arguments queryParams `FindFileForSharedLinkQueryParams` - Query parameters of findFileForSharedLink method headersInput `FindFileForSharedLinkHeadersInput` - Headers of findFileForSharedLink method optionalsInput `FindFileForSharedLinkOptionalsInput` ### Returns This function returns a value of type `FileFull`. Returns a full file resource if the shared link is valid and the user has access to it. ## Get shared link for file Gets the information for a shared link on a file. This operation is performed by calling function `getSharedLinkForFile`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-files-id--get-shared-link/). ``` await client.sharedLinksFiles.getSharedLinkForFile(fileId, { fields: 'shared_link', } satisfies GetSharedLinkForFileQueryParams); ``` ### Arguments fileId `string` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" queryParams `GetSharedLinkForFileQueryParams` - Query parameters of getSharedLinkForFile method optionalsInput `GetSharedLinkForFileOptionalsInput` ### Returns This function returns a value of type `FileFull`. Returns the base representation of a file with the additional shared link information. ## Add shared link to file Adds a shared link to a file. This operation is performed by calling function `addShareLinkToFile`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-files-id--add-shared-link/). ``` await client.sharedLinksFiles.addShareLinkToFile( fileId, { sharedLink: { access: 'open' as AddShareLinkToFileRequestBodySharedLinkAccessField, password: 'Secret123@', } satisfies AddShareLinkToFileRequestBodySharedLinkField, } satisfies AddShareLinkToFileRequestBody, { fields: 'shared_link' } satisfies AddShareLinkToFileQueryParams, ); ``` ### Arguments fileId `string` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" requestBody `AddShareLinkToFileRequestBody` - Request body of addShareLinkToFile method queryParams `AddShareLinkToFileQueryParams` - Query parameters of addShareLinkToFile method optionalsInput `AddShareLinkToFileOptionalsInput` ### Returns This function returns a value of type `FileFull`. Returns the base representation of a file with a new shared link attached. ## Update shared link on file Updates a shared link on a file. This operation is performed by calling function `updateSharedLinkOnFile`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-files-id--update-shared-link/). ``` await client.sharedLinksFiles.updateSharedLinkOnFile( fileId, { sharedLink: { access: 'collaborators' as UpdateSharedLinkOnFileRequestBodySharedLinkAccessField, } satisfies UpdateSharedLinkOnFileRequestBodySharedLinkField, } satisfies UpdateSharedLinkOnFileRequestBody, { fields: 'shared_link' } satisfies UpdateSharedLinkOnFileQueryParams, ); ``` ### Arguments fileId `string` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" requestBody `UpdateSharedLinkOnFileRequestBody` - Request body of updateSharedLinkOnFile method queryParams `UpdateSharedLinkOnFileQueryParams` - Query parameters of updateSharedLinkOnFile method optionalsInput `UpdateSharedLinkOnFileOptionalsInput` ### Returns This function returns a value of type `FileFull`. Returns a basic representation of the file, with the updated shared link attached. ## Remove shared link from file Removes a shared link from a file. This operation is performed by calling function `removeSharedLinkFromFile`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-files-id--remove-shared-link/). ``` await client.sharedLinksFiles.removeSharedLinkFromFile( fileId, { sharedLink: createNull() } satisfies RemoveSharedLinkFromFileRequestBody, { fields: 'shared_link' } satisfies RemoveSharedLinkFromFileQueryParams, ); ``` ### Arguments fileId `string` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" requestBody `RemoveSharedLinkFromFileRequestBody` - Request body of removeSharedLinkFromFile method queryParams `RemoveSharedLinkFromFileQueryParams` - Query parameters of removeSharedLinkFromFile method optionalsInput `RemoveSharedLinkFromFileOptionalsInput` ### Returns This function returns a value of type `FileFull`. Returns a basic representation of a file, with the shared link removed. --- ### SharedLinksFilesManager **Type:** page | **Section:** Additional Resources SharedLinksFilesManager Find file for shared link Get shared link for file Add shared link to file Update shared link on file Remove shared… # SharedLinksFilesManager - [Find file for shared link](#find-file-for-shared-link) - [Get shared link for file](#get-shared-link-for-file) - [Add shared link to file](#add-shared-link-to-file) - [Update shared link on file](#update-shared-link-on-file) - [Remove shared link from file](#remove-shared-link-from-file) ## Find file for shared link Returns the file represented by a shared link. A shared file can be represented by a shared link, which can originate within the current enterprise or within another. This endpoint allows an application to retrieve information about a shared file when only given a shared link. The `shared_link_permission_options` array field can be returned by requesting it in the `fields` query parameter. This operation is performed by calling function `find_file_for_shared_link`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-shared-items/). ``` user_client.shared_links_files.find_file_for_shared_link( "".join( [ "shared_link=", file_from_api.shared_link.url, "&shared_link_password=Secret123@", ] ) ) ``` ### Arguments fields `Optional[List[str]]` - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested. if_none_match `Optional[str]` - Ensures an item is only returned if it has changed. Pass in the item's last observed `etag` value into this header and the endpoint will fail with a `304 Not Modified` if the item has not changed since. boxapi `str` - A header containing the shared link and optional password for the shared link. The format for this header is as follows: `shared_link=[link]&shared_link_password=[password]`. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `FileFull`. Returns a full file resource if the shared link is valid and the user has access to it. ## Get shared link for file Gets the information for a shared link on a file. This operation is performed by calling function `get_shared_link_for_file`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-files-id--get-shared-link/). ``` client.shared_links_files.get_shared_link_for_file(file_id, "shared_link") ``` ### Arguments file_id `str` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" fields `str` - Explicitly request the `shared_link` fields to be returned for this item. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `FileFull`. Returns the base representation of a file with the additional shared link information. ## Add shared link to file Adds a shared link to a file. This operation is performed by calling function `add_share_link_to_file`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-files-id--add-shared-link/). ``` client.shared_links_files.add_share_link_to_file( file_id, "shared_link", shared_link=AddShareLinkToFileSharedLink( access=AddShareLinkToFileSharedLinkAccessField.OPEN, password="Secret123@" ), ) ``` ### Arguments file_id `str` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" shared_link `Optional[AddShareLinkToFileSharedLink]` - The settings for the shared link to create on the file. Use an empty object (`{}`) to use the default settings for shared links. fields `str` - Explicitly request the `shared_link` fields to be returned for this item. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `FileFull`. Returns the base representation of a file with a new shared link attached. ## Update shared link on file Updates a shared link on a file. This operation is performed by calling function `update_shared_link_on_file`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-files-id--update-shared-link/). ``` client.shared_links_files.update_shared_link_on_file( file_id, "shared_link", shared_link=UpdateSharedLinkOnFileSharedLink( access=UpdateSharedLinkOnFileSharedLinkAccessField.COLLABORATORS ), ) ``` ### Arguments file_id `str` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" shared_link `Optional[UpdateSharedLinkOnFileSharedLink]` - The settings for the shared link to update. fields `str` - Explicitly request the `shared_link` fields to be returned for this item. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `FileFull`. Returns a basic representation of the file, with the updated shared link attached. ## Remove shared link from file Removes a shared link from a file. This operation is performed by calling function `remove_shared_link_from_file`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-files-id--remove-shared-link/). ``` client.shared_links_files.remove_shared_link_from_file( file_id, "shared_link", shared_link=create_null() ) ``` ### Arguments file_id `str` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" shared_link `Optional[RemoveSharedLinkFromFileSharedLink]` - By setting this value to `null`, the shared link is removed from the file. fields `str` - Explicitly request the `shared_link` fields to be returned for this item. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `FileFull`. Returns a basic representation of a file, with the shared link removed. --- ### SharedLinksFoldersManager **Type:** page | **Section:** Additional Resources SharedLinksFoldersManager Find folder for shared link Get shared link for folder Add shared link to folder Update shared link on folder… # SharedLinksFoldersManager - [Find folder for shared link](#find-folder-for-shared-link) - [Get shared link for folder](#get-shared-link-for-folder) - [Add shared link to folder](#add-shared-link-to-folder) - [Update shared link on folder](#update-shared-link-on-folder) - [Remove shared link from folder](#remove-shared-link-from-folder) ## Find folder for shared link Return the folder represented by a shared link. A shared folder can be represented by a shared link, which can originate within the current enterprise or within another. This endpoint allows an application to retrieve information about a shared folder when only given a shared link. This operation is performed by calling function `findFolderForSharedLink`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-shared-items--folders/). ``` await userClient.sharedLinksFolders.findFolderForSharedLink( {} satisfies FindFolderForSharedLinkQueryParams, { boxapi: ''.concat( 'shared_link=', folderFromApi.sharedLink!.url, '&shared_link_password=Secret123@', ) as string, } satisfies FindFolderForSharedLinkHeadersInput, ); ``` ### Arguments queryParams `FindFolderForSharedLinkQueryParams` - Query parameters of findFolderForSharedLink method headersInput `FindFolderForSharedLinkHeadersInput` - Headers of findFolderForSharedLink method optionalsInput `FindFolderForSharedLinkOptionalsInput` ### Returns This function returns a value of type `FolderFull`. Returns a full folder resource if the shared link is valid and the user has access to it. ## Get shared link for folder Gets the information for a shared link on a folder. This operation is performed by calling function `getSharedLinkForFolder`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-folders-id--get-shared-link/). ``` await client.sharedLinksFolders.getSharedLinkForFolder(folder.id, { fields: 'shared_link', } satisfies GetSharedLinkForFolderQueryParams); ``` ### Arguments folderId `string` - The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. Example: "12345" queryParams `GetSharedLinkForFolderQueryParams` - Query parameters of getSharedLinkForFolder method optionalsInput `GetSharedLinkForFolderOptionalsInput` ### Returns This function returns a value of type `FolderFull`. Returns the base representation of a folder with the additional shared link information. ## Add shared link to folder Adds a shared link to a folder. This operation is performed by calling function `addShareLinkToFolder`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-folders-id--add-shared-link/). ``` await client.sharedLinksFolders.addShareLinkToFolder( folder.id, { sharedLink: { access: 'open' as AddShareLinkToFolderRequestBodySharedLinkAccessField, password: 'Secret123@', } satisfies AddShareLinkToFolderRequestBodySharedLinkField, } satisfies AddShareLinkToFolderRequestBody, { fields: 'shared_link' } satisfies AddShareLinkToFolderQueryParams, ); ``` ### Arguments folderId `string` - The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. Example: "12345" requestBody `AddShareLinkToFolderRequestBody` - Request body of addShareLinkToFolder method queryParams `AddShareLinkToFolderQueryParams` - Query parameters of addShareLinkToFolder method optionalsInput `AddShareLinkToFolderOptionalsInput` ### Returns This function returns a value of type `FolderFull`. Returns the base representation of a folder with a new shared link attached. ## Update shared link on folder Updates a shared link on a folder. This operation is performed by calling function `updateSharedLinkOnFolder`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-folders-id--update-shared-link/). ``` await client.sharedLinksFolders.updateSharedLinkOnFolder( folder.id, { sharedLink: { access: 'collaborators' as UpdateSharedLinkOnFolderRequestBodySharedLinkAccessField, } satisfies UpdateSharedLinkOnFolderRequestBodySharedLinkField, } satisfies UpdateSharedLinkOnFolderRequestBody, { fields: 'shared_link' } satisfies UpdateSharedLinkOnFolderQueryParams, ); ``` ### Arguments folderId `string` - The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. Example: "12345" requestBody `UpdateSharedLinkOnFolderRequestBody` - Request body of updateSharedLinkOnFolder method queryParams `UpdateSharedLinkOnFolderQueryParams` - Query parameters of updateSharedLinkOnFolder method optionalsInput `UpdateSharedLinkOnFolderOptionalsInput` ### Returns This function returns a value of type `FolderFull`. Returns a basic representation of the folder, with the updated shared link attached. ## Remove shared link from folder Removes a shared link from a folder. This operation is performed by calling function `removeSharedLinkFromFolder`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-folders-id--remove-shared-link/). ``` await client.sharedLinksFolders.removeSharedLinkFromFolder( folder.id, { sharedLink: createNull() } satisfies RemoveSharedLinkFromFolderRequestBody, { fields: 'shared_link' } satisfies RemoveSharedLinkFromFolderQueryParams, ); ``` ### Arguments folderId `string` - The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. Example: "12345" requestBody `RemoveSharedLinkFromFolderRequestBody` - Request body of removeSharedLinkFromFolder method queryParams `RemoveSharedLinkFromFolderQueryParams` - Query parameters of removeSharedLinkFromFolder method optionalsInput `RemoveSharedLinkFromFolderOptionalsInput` ### Returns This function returns a value of type `FolderFull`. Returns a basic representation of a folder, with the shared link removed. --- ### SharedLinksFoldersManager **Type:** page | **Section:** Additional Resources SharedLinksFoldersManager Find folder for shared link Get shared link for folder Add shared link to folder Update shared link on folder… # SharedLinksFoldersManager - [Find folder for shared link](#find-folder-for-shared-link) - [Get shared link for folder](#get-shared-link-for-folder) - [Add shared link to folder](#add-shared-link-to-folder) - [Update shared link on folder](#update-shared-link-on-folder) - [Remove shared link from folder](#remove-shared-link-from-folder) ## Find folder for shared link Return the folder represented by a shared link. A shared folder can be represented by a shared link, which can originate within the current enterprise or within another. This endpoint allows an application to retrieve information about a shared folder when only given a shared link. This operation is performed by calling function `find_folder_for_shared_link`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-shared-items--folders/). ``` user_client.shared_links_folders.find_folder_for_shared_link( "".join( [ "shared_link=", folder_from_api.shared_link.url, "&shared_link_password=Secret123@", ] ) ) ``` ### Arguments fields `Optional[List[str]]` - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested. if_none_match `Optional[str]` - Ensures an item is only returned if it has changed. Pass in the item's last observed `etag` value into this header and the endpoint will fail with a `304 Not Modified` if the item has not changed since. boxapi `str` - A header containing the shared link and optional password for the shared link. The format for this header is as follows: `shared_link=[link]&shared_link_password=[password]`. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `FolderFull`. Returns a full folder resource if the shared link is valid and the user has access to it. ## Get shared link for folder Gets the information for a shared link on a folder. This operation is performed by calling function `get_shared_link_for_folder`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-folders-id--get-shared-link/). ``` client.shared_links_folders.get_shared_link_for_folder(folder.id, "shared_link") ``` ### Arguments folder_id `str` - The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. Example: "12345" fields `str` - Explicitly request the `shared_link` fields to be returned for this item. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `FolderFull`. Returns the base representation of a folder with the additional shared link information. ## Add shared link to folder Adds a shared link to a folder. This operation is performed by calling function `add_share_link_to_folder`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-folders-id--add-shared-link/). ``` client.shared_links_folders.add_share_link_to_folder( folder.id, "shared_link", shared_link=AddShareLinkToFolderSharedLink( access=AddShareLinkToFolderSharedLinkAccessField.OPEN, password="Secret123@" ), ) ``` ### Arguments folder_id `str` - The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. Example: "12345" shared_link `Optional[AddShareLinkToFolderSharedLink]` - The settings for the shared link to create on the folder. Use an empty object (`{}`) to use the default settings for shared links. fields `str` - Explicitly request the `shared_link` fields to be returned for this item. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `FolderFull`. Returns the base representation of a folder with a new shared link attached. ## Update shared link on folder Updates a shared link on a folder. This operation is performed by calling function `update_shared_link_on_folder`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-folders-id--update-shared-link/). ``` client.shared_links_folders.update_shared_link_on_folder( folder.id, "shared_link", shared_link=UpdateSharedLinkOnFolderSharedLink( access=UpdateSharedLinkOnFolderSharedLinkAccessField.COLLABORATORS ), ) ``` ### Arguments folder_id `str` - The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. Example: "12345" shared_link `Optional[UpdateSharedLinkOnFolderSharedLink]` - The settings for the shared link to update. fields `str` - Explicitly request the `shared_link` fields to be returned for this item. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `FolderFull`. Returns a basic representation of the folder, with the updated shared link attached. ## Remove shared link from folder Removes a shared link from a folder. This operation is performed by calling function `remove_shared_link_from_folder`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-folders-id--remove-shared-link/). ``` client.shared_links_folders.remove_shared_link_from_folder( folder.id, "shared_link", shared_link=create_null() ) ``` ### Arguments folder_id `str` - The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. Example: "12345" shared_link `Optional[RemoveSharedLinkFromFolderSharedLink]` - By setting this value to `null`, the shared link is removed from the folder. fields `str` - Explicitly request the `shared_link` fields to be returned for this item. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `FolderFull`. Returns a basic representation of a folder, with the shared link removed. --- ### SharedLinksWebLinksManager **Type:** page | **Section:** Additional Resources SharedLinksWebLinksManager Find web link for shared link Get shared link for web link Add shared link to web link Update shared link on web… # SharedLinksWebLinksManager - [Find web link for shared link](#find-web-link-for-shared-link) - [Get shared link for web link](#get-shared-link-for-web-link) - [Add shared link to web link](#add-shared-link-to-web-link) - [Update shared link on web link](#update-shared-link-on-web-link) - [Remove shared link from web link](#remove-shared-link-from-web-link) ## Find web link for shared link Returns the web link represented by a shared link. A shared web link can be represented by a shared link, which can originate within the current enterprise or within another. This endpoint allows an application to retrieve information about a shared web link when only given a shared link. This operation is performed by calling function `findWebLinkForSharedLink`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-shared-items--web-links/). ``` await userClient.sharedLinksWebLinks.findWebLinkForSharedLink( {} satisfies FindWebLinkForSharedLinkQueryParams, { boxapi: ''.concat( 'shared_link=', webLinkFromApi.sharedLink!.url, '&shared_link_password=Secret123@', ) as string, } satisfies FindWebLinkForSharedLinkHeadersInput, ); ``` ### Arguments queryParams `FindWebLinkForSharedLinkQueryParams` - Query parameters of findWebLinkForSharedLink method headersInput `FindWebLinkForSharedLinkHeadersInput` - Headers of findWebLinkForSharedLink method optionalsInput `FindWebLinkForSharedLinkOptionalsInput` ### Returns This function returns a value of type `WebLink`. Returns a full web link resource if the shared link is valid and the user has access to it. ## Get shared link for web link Gets the information for a shared link on a web link. This operation is performed by calling function `getSharedLinkForWebLink`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-web-links-id--get-shared-link/). ``` await client.sharedLinksWebLinks.getSharedLinkForWebLink(webLinkId, { fields: 'shared_link', } satisfies GetSharedLinkForWebLinkQueryParams); ``` ### Arguments webLinkId `string` - The ID of the web link. Example: "12345" queryParams `GetSharedLinkForWebLinkQueryParams` - Query parameters of getSharedLinkForWebLink method optionalsInput `GetSharedLinkForWebLinkOptionalsInput` ### Returns This function returns a value of type `WebLink`. Returns the base representation of a web link with the additional shared link information. ## Add shared link to web link Adds a shared link to a web link. This operation is performed by calling function `addShareLinkToWebLink`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-web-links-id--add-shared-link/). ``` await client.sharedLinksWebLinks.addShareLinkToWebLink( webLinkId, { sharedLink: { access: 'open' as AddShareLinkToWebLinkRequestBodySharedLinkAccessField, password: 'Secret123@', } satisfies AddShareLinkToWebLinkRequestBodySharedLinkField, } satisfies AddShareLinkToWebLinkRequestBody, { fields: 'shared_link' } satisfies AddShareLinkToWebLinkQueryParams, ); ``` ### Arguments webLinkId `string` - The ID of the web link. Example: "12345" requestBody `AddShareLinkToWebLinkRequestBody` - Request body of addShareLinkToWebLink method queryParams `AddShareLinkToWebLinkQueryParams` - Query parameters of addShareLinkToWebLink method optionalsInput `AddShareLinkToWebLinkOptionalsInput` ### Returns This function returns a value of type `WebLink`. Returns the base representation of a web link with a new shared link attached. ## Update shared link on web link Updates a shared link on a web link. This operation is performed by calling function `updateSharedLinkOnWebLink`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-web-links-id--update-shared-link/). ``` await client.sharedLinksWebLinks.updateSharedLinkOnWebLink( webLinkId, { sharedLink: { access: 'collaborators' as UpdateSharedLinkOnWebLinkRequestBodySharedLinkAccessField, } satisfies UpdateSharedLinkOnWebLinkRequestBodySharedLinkField, } satisfies UpdateSharedLinkOnWebLinkRequestBody, { fields: 'shared_link' } satisfies UpdateSharedLinkOnWebLinkQueryParams, ); ``` ### Arguments webLinkId `string` - The ID of the web link. Example: "12345" requestBody `UpdateSharedLinkOnWebLinkRequestBody` - Request body of updateSharedLinkOnWebLink method queryParams `UpdateSharedLinkOnWebLinkQueryParams` - Query parameters of updateSharedLinkOnWebLink method optionalsInput `UpdateSharedLinkOnWebLinkOptionalsInput` ### Returns This function returns a value of type `WebLink`. Returns a basic representation of the web link, with the updated shared link attached. ## Remove shared link from web link Removes a shared link from a web link. This operation is performed by calling function `removeSharedLinkFromWebLink`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-web-links-id--remove-shared-link/). ``` await client.sharedLinksWebLinks.removeSharedLinkFromWebLink( webLinkId, { sharedLink: createNull() } satisfies RemoveSharedLinkFromWebLinkRequestBody, { fields: 'shared_link' } satisfies RemoveSharedLinkFromWebLinkQueryParams, ); ``` ### Arguments webLinkId `string` - The ID of the web link. Example: "12345" requestBody `RemoveSharedLinkFromWebLinkRequestBody` - Request body of removeSharedLinkFromWebLink method queryParams `RemoveSharedLinkFromWebLinkQueryParams` - Query parameters of removeSharedLinkFromWebLink method optionalsInput `RemoveSharedLinkFromWebLinkOptionalsInput` ### Returns This function returns a value of type `WebLink`. Returns a basic representation of a web link, with the shared link removed. --- ### SharedLinksWebLinksManager **Type:** page | **Section:** Additional Resources SharedLinksWebLinksManager Find web link for shared link Get shared link for web link Add shared link to web link Update shared link on web… # SharedLinksWebLinksManager - [Find web link for shared link](#find-web-link-for-shared-link) - [Get shared link for web link](#get-shared-link-for-web-link) - [Add shared link to web link](#add-shared-link-to-web-link) - [Update shared link on web link](#update-shared-link-on-web-link) - [Remove shared link from web link](#remove-shared-link-from-web-link) ## Find web link for shared link Returns the web link represented by a shared link. A shared web link can be represented by a shared link, which can originate within the current enterprise or within another. This endpoint allows an application to retrieve information about a shared web link when only given a shared link. This operation is performed by calling function `find_web_link_for_shared_link`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-shared-items--web-links/). ``` user_client.shared_links_web_links.find_web_link_for_shared_link( "".join( [ "shared_link=", web_link_from_api.shared_link.url, "&shared_link_password=Secret123@", ] ) ) ``` ### Arguments fields `Optional[List[str]]` - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested. if_none_match `Optional[str]` - Ensures an item is only returned if it has changed. Pass in the item's last observed `etag` value into this header and the endpoint will fail with a `304 Not Modified` if the item has not changed since. boxapi `str` - A header containing the shared link and optional password for the shared link. The format for this header is as follows: `shared_link=[link]&shared_link_password=[password]`. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `WebLink`. Returns a full web link resource if the shared link is valid and the user has access to it. ## Get shared link for web link Gets the information for a shared link on a web link. This operation is performed by calling function `get_shared_link_for_web_link`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-web-links-id--get-shared-link/). ``` client.shared_links_web_links.get_shared_link_for_web_link(web_link_id, "shared_link") ``` ### Arguments web_link_id `str` - The ID of the web link. Example: "12345" fields `str` - Explicitly request the `shared_link` fields to be returned for this item. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `WebLink`. Returns the base representation of a web link with the additional shared link information. ## Add shared link to web link Adds a shared link to a web link. This operation is performed by calling function `add_share_link_to_web_link`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-web-links-id--add-shared-link/). ``` client.shared_links_web_links.add_share_link_to_web_link( web_link_id, "shared_link", shared_link=AddShareLinkToWebLinkSharedLink( access=AddShareLinkToWebLinkSharedLinkAccessField.OPEN, password="Secret123@" ), ) ``` ### Arguments web_link_id `str` - The ID of the web link. Example: "12345" shared_link `Optional[AddShareLinkToWebLinkSharedLink]` - The settings for the shared link to create on the web link. Use an empty object (`{}`) to use the default settings for shared links. fields `str` - Explicitly request the `shared_link` fields to be returned for this item. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `WebLink`. Returns the base representation of a web link with a new shared link attached. ## Update shared link on web link Updates a shared link on a web link. This operation is performed by calling function `update_shared_link_on_web_link`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-web-links-id--update-shared-link/). ``` client.shared_links_web_links.update_shared_link_on_web_link( web_link_id, "shared_link", shared_link=UpdateSharedLinkOnWebLinkSharedLink( access=UpdateSharedLinkOnWebLinkSharedLinkAccessField.COLLABORATORS ), ) ``` ### Arguments web_link_id `str` - The ID of the web link. Example: "12345" shared_link `Optional[UpdateSharedLinkOnWebLinkSharedLink]` - The settings for the shared link to update. fields `str` - Explicitly request the `shared_link` fields to be returned for this item. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `WebLink`. Returns a basic representation of the web link, with the updated shared link attached. ## Remove shared link from web link Removes a shared link from a web link. This operation is performed by calling function `remove_shared_link_from_web_link`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-web-links-id--remove-shared-link/). ``` client.shared_links_web_links.remove_shared_link_from_web_link( web_link_id, "shared_link", shared_link=create_null() ) ``` ### Arguments web_link_id `str` - The ID of the web link. Example: "12345" shared_link `Optional[RemoveSharedLinkFromWebLinkSharedLink]` - By setting this value to `null`, the shared link is removed from the web link. fields `str` - Explicitly request the `shared_link` fields to be returned for this item. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `WebLink`. Returns a basic representation of a web link, with the shared link removed. --- ### ShieldInformationBarrierReportsManager **Type:** page | **Section:** Additional Resources ShieldInformationBarrierReportsManager List shield information barrier reports Create shield information barrier report Get shield… # ShieldInformationBarrierReportsManager - [List shield information barrier reports](#list-shield-information-barrier-reports) - [Create shield information barrier report](#create-shield-information-barrier-report) - [Get shield information barrier report by ID](#get-shield-information-barrier-report-by-id) ## List shield information barrier reports Lists shield information barrier reports. This operation is performed by calling function `getShieldInformationBarrierReports`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-shield-information-barrier-reports/). ``` await client.shieldInformationBarrierReports.getShieldInformationBarrierReports( { shieldInformationBarrierId: barrierId, } satisfies GetShieldInformationBarrierReportsQueryParams, ); ``` ### Arguments queryParams `GetShieldInformationBarrierReportsQueryParams` - Query parameters of getShieldInformationBarrierReports method optionalsInput `GetShieldInformationBarrierReportsOptionalsInput` ### Returns This function returns a value of type `ShieldInformationBarrierReports`. Returns a paginated list of shield information barrier report objects. ## Create shield information barrier report Creates a shield information barrier report for a given barrier. This operation is performed by calling function `createShieldInformationBarrierReport`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-shield-information-barrier-reports/). ``` await client.shieldInformationBarrierReports.createShieldInformationBarrierReport( { shieldInformationBarrier: { id: barrierId, type: 'shield_information_barrier' as ShieldInformationBarrierBaseTypeField, } satisfies ShieldInformationBarrierBase, } satisfies ShieldInformationBarrierReference, ); ``` ### Arguments requestBody `ShieldInformationBarrierReference` - Request body of createShieldInformationBarrierReport method optionalsInput `CreateShieldInformationBarrierReportOptionalsInput` ### Returns This function returns a value of type `ShieldInformationBarrierReport`. Returns the shield information barrier report information object. ## Get shield information barrier report by ID Retrieves a shield information barrier report by its ID. This operation is performed by calling function `getShieldInformationBarrierReportById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-shield-information-barrier-reports-id/). ``` await client.shieldInformationBarrierReports.getShieldInformationBarrierReportById( createdReport.id!, ); ``` ### Arguments shieldInformationBarrierReportId `string` - The ID of the shield information barrier Report. Example: "3423" optionalsInput `GetShieldInformationBarrierReportByIdOptionalsInput` ### Returns This function returns a value of type `ShieldInformationBarrierReport`. Returns the shield information barrier report object. --- ### ShieldInformationBarrierReportsManager **Type:** page | **Section:** Additional Resources ShieldInformationBarrierReportsManager List shield information barrier reports Create shield information barrier report Get shield… # ShieldInformationBarrierReportsManager - [List shield information barrier reports](#list-shield-information-barrier-reports) - [Create shield information barrier report](#create-shield-information-barrier-report) - [Get shield information barrier report by ID](#get-shield-information-barrier-report-by-id) ## List shield information barrier reports Lists shield information barrier reports. This operation is performed by calling function `get_shield_information_barrier_reports`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-shield-information-barrier-reports/). ``` client.shield_information_barrier_reports.get_shield_information_barrier_reports( barrier_id ) ``` ### Arguments shield_information_barrier_id `str` - The ID of the shield information barrier. marker `Optional[str]` - Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`. limit `Optional[int]` - The maximum number of items to return per page. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `ShieldInformationBarrierReports`. Returns a paginated list of shield information barrier report objects. ## Create shield information barrier report Creates a shield information barrier report for a given barrier. This operation is performed by calling function `create_shield_information_barrier_report`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-shield-information-barrier-reports/). ``` client.shield_information_barrier_reports.create_shield_information_barrier_report( shield_information_barrier=ShieldInformationBarrierBase( id=barrier_id, type=ShieldInformationBarrierBaseTypeField.SHIELD_INFORMATION_BARRIER, ) ) ``` ### Arguments - shield_information_barrier `Optional[ShieldInformationBarrierBase]` extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `ShieldInformationBarrierReport`. Returns the shield information barrier report information object. ## Get shield information barrier report by ID Retrieves a shield information barrier report by its ID. This operation is performed by calling function `get_shield_information_barrier_report_by_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-shield-information-barrier-reports-id/). ``` client.shield_information_barrier_reports.get_shield_information_barrier_report_by_id( created_report.id ) ``` ### Arguments shield_information_barrier_report_id `str` - The ID of the shield information barrier Report. Example: "3423" extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `ShieldInformationBarrierReport`. Returns the shield information barrier report object. --- ### ShieldInformationBarrierSegmentMembersManager **Type:** page | **Section:** Additional Resources ShieldInformationBarrierSegmentMembersManager Get shield information barrier segment member by ID Delete shield information barrier segment… # ShieldInformationBarrierSegmentMembersManager - [Get shield information barrier segment member by ID](#get-shield-information-barrier-segment-member-by-id) - [Delete shield information barrier segment member by ID](#delete-shield-information-barrier-segment-member-by-id) - [List shield information barrier segment members](#list-shield-information-barrier-segment-members) - [Create shield information barrier segment member](#create-shield-information-barrier-segment-member) ## Get shield information barrier segment member by ID Retrieves a shield information barrier segment member by its ID. This operation is performed by calling function `getShieldInformationBarrierSegmentMemberById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-shield-information-barrier-segment-members-id/). ``` await client.shieldInformationBarrierSegmentMembers.getShieldInformationBarrierSegmentMemberById( segmentMember.id!, ); ``` ### Arguments shieldInformationBarrierSegmentMemberId `string` - The ID of the shield information barrier segment Member. Example: "7815" optionalsInput `GetShieldInformationBarrierSegmentMemberByIdOptionalsInput` ### Returns This function returns a value of type `ShieldInformationBarrierSegmentMember`. Returns the shield information barrier segment member object. ## Delete shield information barrier segment member by ID Deletes a shield information barrier segment member based on provided ID. This operation is performed by calling function `deleteShieldInformationBarrierSegmentMemberById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-shield-information-barrier-segment-members-id/). ``` await client.shieldInformationBarrierSegmentMembers.deleteShieldInformationBarrierSegmentMemberById( segmentMember.id!, ); ``` ### Arguments shieldInformationBarrierSegmentMemberId `string` - The ID of the shield information barrier segment Member. Example: "7815" optionalsInput `DeleteShieldInformationBarrierSegmentMemberByIdOptionalsInput` ### Returns This function returns a value of type `undefined`. Returns an empty response if the segment member was deleted successfully. ## List shield information barrier segment members Lists shield information barrier segment members based on provided segment IDs. This operation is performed by calling function `getShieldInformationBarrierSegmentMembers`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-shield-information-barrier-segment-members/). ``` await client.shieldInformationBarrierSegmentMembers.getShieldInformationBarrierSegmentMembers( { shieldInformationBarrierSegmentId: segment.id!, } satisfies GetShieldInformationBarrierSegmentMembersQueryParams, ); ``` ### Arguments queryParams `GetShieldInformationBarrierSegmentMembersQueryParams` - Query parameters of getShieldInformationBarrierSegmentMembers method optionalsInput `GetShieldInformationBarrierSegmentMembersOptionalsInput` ### Returns This function returns a value of type `ShieldInformationBarrierSegmentMembers`. Returns a paginated list of shield information barrier segment member objects. ## Create shield information barrier segment member Creates a new shield information barrier segment member. This operation is performed by calling function `createShieldInformationBarrierSegmentMember`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-shield-information-barrier-segment-members/). ``` await client.shieldInformationBarrierSegmentMembers.createShieldInformationBarrierSegmentMember( { shieldInformationBarrierSegment: { id: segment.id!, type: 'shield_information_barrier_segment' as CreateShieldInformationBarrierSegmentMemberRequestBodyShieldInformationBarrierSegmentTypeField, } satisfies CreateShieldInformationBarrierSegmentMemberRequestBodyShieldInformationBarrierSegmentField, user: new UserBase({ id: getEnvVar('USER_ID') }), } satisfies CreateShieldInformationBarrierSegmentMemberRequestBody, ); ``` ### Arguments requestBody `CreateShieldInformationBarrierSegmentMemberRequestBody` - Request body of createShieldInformationBarrierSegmentMember method optionalsInput `CreateShieldInformationBarrierSegmentMemberOptionalsInput` ### Returns This function returns a value of type `ShieldInformationBarrierSegmentMember`. Returns a new shield information barrier segment member object. --- ### ShieldInformationBarrierSegmentMembersManager **Type:** page | **Section:** Additional Resources ShieldInformationBarrierSegmentMembersManager Get shield information barrier segment member by ID Delete shield information barrier segment… # ShieldInformationBarrierSegmentMembersManager - [Get shield information barrier segment member by ID](#get-shield-information-barrier-segment-member-by-id) - [Delete shield information barrier segment member by ID](#delete-shield-information-barrier-segment-member-by-id) - [List shield information barrier segment members](#list-shield-information-barrier-segment-members) - [Create shield information barrier segment member](#create-shield-information-barrier-segment-member) ## Get shield information barrier segment member by ID Retrieves a shield information barrier segment member by its ID. This operation is performed by calling function `get_shield_information_barrier_segment_member_by_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-shield-information-barrier-segment-members-id/). ``` client.shield_information_barrier_segment_members.get_shield_information_barrier_segment_member_by_id( segment_member.id ) ``` ### Arguments shield_information_barrier_segment_member_id `str` - The ID of the shield information barrier segment Member. Example: "7815" extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `ShieldInformationBarrierSegmentMember`. Returns the shield information barrier segment member object. ## Delete shield information barrier segment member by ID Deletes a shield information barrier segment member based on provided ID. This operation is performed by calling function `delete_shield_information_barrier_segment_member_by_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-shield-information-barrier-segment-members-id/). ``` client.shield_information_barrier_segment_members.delete_shield_information_barrier_segment_member_by_id( segment_member.id ) ``` ### Arguments shield_information_barrier_segment_member_id `str` - The ID of the shield information barrier segment Member. Example: "7815" extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `None`. Returns an empty response if the segment member was deleted successfully. ## List shield information barrier segment members Lists shield information barrier segment members based on provided segment IDs. This operation is performed by calling function `get_shield_information_barrier_segment_members`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-shield-information-barrier-segment-members/). ``` client.shield_information_barrier_segment_members.get_shield_information_barrier_segment_members( segment.id ) ``` ### Arguments shield_information_barrier_segment_id `str` - The ID of the shield information barrier segment. marker `Optional[str]` - Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`. limit `Optional[int]` - The maximum number of items to return per page. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `ShieldInformationBarrierSegmentMembers`. Returns a paginated list of shield information barrier segment member objects. ## Create shield information barrier segment member Creates a new shield information barrier segment member. This operation is performed by calling function `create_shield_information_barrier_segment_member`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-shield-information-barrier-segment-members/). ``` client.shield_information_barrier_segment_members.create_shield_information_barrier_segment_member( CreateShieldInformationBarrierSegmentMemberShieldInformationBarrierSegment( id=segment.id, type=CreateShieldInformationBarrierSegmentMemberShieldInformationBarrierSegmentTypeField.SHIELD_INFORMATION_BARRIER_SEGMENT, ), UserBase(id=get_env_var("USER_ID")), ) ``` ### Arguments type `Optional[CreateShieldInformationBarrierSegmentMemberType]` - A type of the shield barrier segment member. shield_information_barrier `Optional[ShieldInformationBarrierBase]` shield_information_barrier_segment `CreateShieldInformationBarrierSegmentMemberShieldInformationBarrierSegment` - The `type` and `id` of the requested shield information barrier segment. user `UserBase` - User to which restriction will be applied. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `ShieldInformationBarrierSegmentMember`. Returns a new shield information barrier segment member object. --- ### ShieldInformationBarrierSegmentRestrictionsManager **Type:** page | **Section:** Additional Resources ShieldInformationBarrierSegmentRestrictionsManager Get shield information barrier segment restriction by ID Delete shield information… # ShieldInformationBarrierSegmentRestrictionsManager - [Get shield information barrier segment restriction by ID](#get-shield-information-barrier-segment-restriction-by-id) - [Delete shield information barrier segment restriction by ID](#delete-shield-information-barrier-segment-restriction-by-id) - [List shield information barrier segment restrictions](#list-shield-information-barrier-segment-restrictions) - [Create shield information barrier segment restriction](#create-shield-information-barrier-segment-restriction) ## Get shield information barrier segment restriction by ID Retrieves a shield information barrier segment restriction based on provided ID. This operation is performed by calling function `getShieldInformationBarrierSegmentRestrictionById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-shield-information-barrier-segment-restrictions-id/). ``` await client.shieldInformationBarrierSegmentRestrictions.getShieldInformationBarrierSegmentRestrictionById( segmentRestrictionId, ); ``` ### Arguments shieldInformationBarrierSegmentRestrictionId `string` - The ID of the shield information barrier segment Restriction. Example: "4563" optionalsInput `GetShieldInformationBarrierSegmentRestrictionByIdOptionalsInput` ### Returns This function returns a value of type `ShieldInformationBarrierSegmentRestriction`. Returns the shield information barrier segment restriction object. ## Delete shield information barrier segment restriction by ID Delete shield information barrier segment restriction based on provided ID. This operation is performed by calling function `deleteShieldInformationBarrierSegmentRestrictionById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-shield-information-barrier-segment-restrictions-id/). ``` await client.shieldInformationBarrierSegmentRestrictions.deleteShieldInformationBarrierSegmentRestrictionById( segmentRestrictionId, ); ``` ### Arguments shieldInformationBarrierSegmentRestrictionId `string` - The ID of the shield information barrier segment Restriction. Example: "4563" optionalsInput `DeleteShieldInformationBarrierSegmentRestrictionByIdOptionalsInput` ### Returns This function returns a value of type `undefined`. Empty body in response. ## List shield information barrier segment restrictions Lists shield information barrier segment restrictions based on provided segment ID. This operation is performed by calling function `getShieldInformationBarrierSegmentRestrictions`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-shield-information-barrier-segment-restrictions/). ``` await client.shieldInformationBarrierSegmentRestrictions.getShieldInformationBarrierSegmentRestrictions( { shieldInformationBarrierSegmentId: segmentId, } satisfies GetShieldInformationBarrierSegmentRestrictionsQueryParams, ); ``` ### Arguments queryParams `GetShieldInformationBarrierSegmentRestrictionsQueryParams` - Query parameters of getShieldInformationBarrierSegmentRestrictions method optionalsInput `GetShieldInformationBarrierSegmentRestrictionsOptionalsInput` ### Returns This function returns a value of type `ShieldInformationBarrierSegmentRestrictions`. Returns a paginated list of shield information barrier segment restriction objects. ## Create shield information barrier segment restriction Creates a shield information barrier segment restriction object. This operation is performed by calling function `createShieldInformationBarrierSegmentRestriction`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-shield-information-barrier-segment-restrictions/). ``` await client.shieldInformationBarrierSegmentRestrictions.createShieldInformationBarrierSegmentRestriction( { restrictedSegment: { id: segmentToRestrictId, type: 'shield_information_barrier_segment' as CreateShieldInformationBarrierSegmentRestrictionRequestBodyRestrictedSegmentTypeField, } satisfies CreateShieldInformationBarrierSegmentRestrictionRequestBodyRestrictedSegmentField, shieldInformationBarrierSegment: { id: segmentId, type: 'shield_information_barrier_segment' as CreateShieldInformationBarrierSegmentRestrictionRequestBodyShieldInformationBarrierSegmentTypeField, } satisfies CreateShieldInformationBarrierSegmentRestrictionRequestBodyShieldInformationBarrierSegmentField, type: 'shield_information_barrier_segment_restriction' as CreateShieldInformationBarrierSegmentRestrictionRequestBodyTypeField, } satisfies CreateShieldInformationBarrierSegmentRestrictionRequestBodyInput, ); ``` ### Arguments requestBodyInput `CreateShieldInformationBarrierSegmentRestrictionRequestBodyInput` - Request body of createShieldInformationBarrierSegmentRestriction method optionalsInput `CreateShieldInformationBarrierSegmentRestrictionOptionalsInput` ### Returns This function returns a value of type `ShieldInformationBarrierSegmentRestriction`. Returns the newly created Shield Information Barrier Segment Restriction object. --- ### ShieldInformationBarrierSegmentRestrictionsManager **Type:** page | **Section:** Additional Resources ShieldInformationBarrierSegmentRestrictionsManager Get shield information barrier segment restriction by ID Delete shield information… # ShieldInformationBarrierSegmentRestrictionsManager - [Get shield information barrier segment restriction by ID](#get-shield-information-barrier-segment-restriction-by-id) - [Delete shield information barrier segment restriction by ID](#delete-shield-information-barrier-segment-restriction-by-id) - [List shield information barrier segment restrictions](#list-shield-information-barrier-segment-restrictions) - [Create shield information barrier segment restriction](#create-shield-information-barrier-segment-restriction) ## Get shield information barrier segment restriction by ID Retrieves a shield information barrier segment restriction based on provided ID. This operation is performed by calling function `get_shield_information_barrier_segment_restriction_by_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-shield-information-barrier-segment-restrictions-id/). ``` client.shield_information_barrier_segment_restrictions.get_shield_information_barrier_segment_restriction_by_id( segment_restriction_id ) ``` ### Arguments shield_information_barrier_segment_restriction_id `str` - The ID of the shield information barrier segment Restriction. Example: "4563" extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `ShieldInformationBarrierSegmentRestriction`. Returns the shield information barrier segment restriction object. ## Delete shield information barrier segment restriction by ID Delete shield information barrier segment restriction based on provided ID. This operation is performed by calling function `delete_shield_information_barrier_segment_restriction_by_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-shield-information-barrier-segment-restrictions-id/). ``` client.shield_information_barrier_segment_restrictions.delete_shield_information_barrier_segment_restriction_by_id( segment_restriction_id ) ``` ### Arguments shield_information_barrier_segment_restriction_id `str` - The ID of the shield information barrier segment Restriction. Example: "4563" extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `None`. Empty body in response. ## List shield information barrier segment restrictions Lists shield information barrier segment restrictions based on provided segment ID. This operation is performed by calling function `get_shield_information_barrier_segment_restrictions`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-shield-information-barrier-segment-restrictions/). ``` client.shield_information_barrier_segment_restrictions.get_shield_information_barrier_segment_restrictions( segment_id ) ``` ### Arguments shield_information_barrier_segment_id `str` - The ID of the shield information barrier segment. marker `Optional[str]` - Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`. limit `Optional[int]` - The maximum number of items to return per page. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `ShieldInformationBarrierSegmentRestrictions`. Returns a paginated list of shield information barrier segment restriction objects. ## Create shield information barrier segment restriction Creates a shield information barrier segment restriction object. This operation is performed by calling function `create_shield_information_barrier_segment_restriction`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-shield-information-barrier-segment-restrictions/). ``` client.shield_information_barrier_segment_restrictions.create_shield_information_barrier_segment_restriction( CreateShieldInformationBarrierSegmentRestrictionShieldInformationBarrierSegment( id=segment_id, type=CreateShieldInformationBarrierSegmentRestrictionShieldInformationBarrierSegmentTypeField.SHIELD_INFORMATION_BARRIER_SEGMENT, ), CreateShieldInformationBarrierSegmentRestrictionRestrictedSegment( id=segment_to_restrict_id, type=CreateShieldInformationBarrierSegmentRestrictionRestrictedSegmentTypeField.SHIELD_INFORMATION_BARRIER_SEGMENT, ), type=CreateShieldInformationBarrierSegmentRestrictionType.SHIELD_INFORMATION_BARRIER_SEGMENT_RESTRICTION, ) ``` ### Arguments type `CreateShieldInformationBarrierSegmentRestrictionType` - The type of the shield barrier segment restriction for this member. shield_information_barrier `Optional[ShieldInformationBarrierBase]` shield_information_barrier_segment `CreateShieldInformationBarrierSegmentRestrictionShieldInformationBarrierSegment` - The `type` and `id` of the requested shield information barrier segment. restricted_segment `CreateShieldInformationBarrierSegmentRestrictionRestrictedSegment` - The `type` and `id` of the restricted shield information barrier segment. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `ShieldInformationBarrierSegmentRestriction`. Returns the newly created Shield Information Barrier Segment Restriction object. --- ### ShieldInformationBarrierSegmentsManager **Type:** page | **Section:** Additional Resources ShieldInformationBarrierSegmentsManager Get shield information barrier segment with specified ID Delete shield information barrier segment… # ShieldInformationBarrierSegmentsManager - [Get shield information barrier segment with specified ID](#get-shield-information-barrier-segment-with-specified-id) - [Delete shield information barrier segment](#delete-shield-information-barrier-segment) - [Update shield information barrier segment with specified ID](#update-shield-information-barrier-segment-with-specified-id) - [List shield information barrier segments](#list-shield-information-barrier-segments) - [Create shield information barrier segment](#create-shield-information-barrier-segment) ## Get shield information barrier segment with specified ID Retrieves shield information barrier segment based on provided ID.. This operation is performed by calling function `getShieldInformationBarrierSegmentById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-shield-information-barrier-segments-id/). ``` await client.shieldInformationBarrierSegments.getShieldInformationBarrierSegmentById( segmentId, ); ``` ### Arguments shieldInformationBarrierSegmentId `string` - The ID of the shield information barrier segment. Example: "3423" optionalsInput `GetShieldInformationBarrierSegmentByIdOptionalsInput` ### Returns This function returns a value of type `ShieldInformationBarrierSegment`. Returns the shield information barrier segment object. ## Delete shield information barrier segment Deletes the shield information barrier segment based on provided ID. This operation is performed by calling function `deleteShieldInformationBarrierSegmentById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-shield-information-barrier-segments-id/). ``` await client.shieldInformationBarrierSegments.deleteShieldInformationBarrierSegmentById( segmentId, ); ``` ### Arguments shieldInformationBarrierSegmentId `string` - The ID of the shield information barrier segment. Example: "3423" optionalsInput `DeleteShieldInformationBarrierSegmentByIdOptionalsInput` ### Returns This function returns a value of type `undefined`. Empty body in response. ## Update shield information barrier segment with specified ID Updates the shield information barrier segment based on provided ID.. This operation is performed by calling function `updateShieldInformationBarrierSegmentById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-shield-information-barrier-segments-id/). ``` await client.shieldInformationBarrierSegments.updateShieldInformationBarrierSegmentById( segmentId, { requestBody: { description: updatedSegmentDescription, } satisfies UpdateShieldInformationBarrierSegmentByIdRequestBody, } satisfies UpdateShieldInformationBarrierSegmentByIdOptionalsInput, ); ``` ### Arguments shieldInformationBarrierSegmentId `string` - The ID of the shield information barrier segment. Example: "3423" optionalsInput `UpdateShieldInformationBarrierSegmentByIdOptionalsInput` ### Returns This function returns a value of type `ShieldInformationBarrierSegment`. Returns the updated shield information barrier segment object. ## List shield information barrier segments Retrieves a list of shield information barrier segment objects for the specified Information Barrier ID. This operation is performed by calling function `getShieldInformationBarrierSegments`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-shield-information-barrier-segments/). ``` await client.shieldInformationBarrierSegments.getShieldInformationBarrierSegments( { shieldInformationBarrierId: barrierId, } satisfies GetShieldInformationBarrierSegmentsQueryParams, ); ``` ### Arguments queryParams `GetShieldInformationBarrierSegmentsQueryParams` - Query parameters of getShieldInformationBarrierSegments method optionalsInput `GetShieldInformationBarrierSegmentsOptionalsInput` ### Returns This function returns a value of type `ShieldInformationBarrierSegments`. Returns a paginated list of shield information barrier segment objects. ## Create shield information barrier segment Creates a shield information barrier segment. This operation is performed by calling function `createShieldInformationBarrierSegment`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-shield-information-barrier-segments/). ``` await client.shieldInformationBarrierSegments.createShieldInformationBarrierSegment( { shieldInformationBarrier: { id: barrierId, type: 'shield_information_barrier' as ShieldInformationBarrierBaseTypeField, } satisfies ShieldInformationBarrierBase, name: segmentName, description: segmentDescription, } satisfies CreateShieldInformationBarrierSegmentRequestBody, ); ``` ### Arguments requestBody `CreateShieldInformationBarrierSegmentRequestBody` - Request body of createShieldInformationBarrierSegment method optionalsInput `CreateShieldInformationBarrierSegmentOptionalsInput` ### Returns This function returns a value of type `ShieldInformationBarrierSegment`. Returns a new shield information barrier segment object. --- ### ShieldInformationBarrierSegmentsManager **Type:** page | **Section:** Additional Resources ShieldInformationBarrierSegmentsManager Get shield information barrier segment with specified ID Delete shield information barrier segment… # ShieldInformationBarrierSegmentsManager - [Get shield information barrier segment with specified ID](#get-shield-information-barrier-segment-with-specified-id) - [Delete shield information barrier segment](#delete-shield-information-barrier-segment) - [Update shield information barrier segment with specified ID](#update-shield-information-barrier-segment-with-specified-id) - [List shield information barrier segments](#list-shield-information-barrier-segments) - [Create shield information barrier segment](#create-shield-information-barrier-segment) ## Get shield information barrier segment with specified ID Retrieves shield information barrier segment based on provided ID.. This operation is performed by calling function `get_shield_information_barrier_segment_by_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-shield-information-barrier-segments-id/). ``` client.shield_information_barrier_segments.get_shield_information_barrier_segment_by_id( segment_id ) ``` ### Arguments shield_information_barrier_segment_id `str` - The ID of the shield information barrier segment. Example: "3423" extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `ShieldInformationBarrierSegment`. Returns the shield information barrier segment object. ## Delete shield information barrier segment Deletes the shield information barrier segment based on provided ID. This operation is performed by calling function `delete_shield_information_barrier_segment_by_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-shield-information-barrier-segments-id/). ``` client.shield_information_barrier_segments.delete_shield_information_barrier_segment_by_id( segment_id ) ``` ### Arguments shield_information_barrier_segment_id `str` - The ID of the shield information barrier segment. Example: "3423" extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `None`. Empty body in response. ## Update shield information barrier segment with specified ID Updates the shield information barrier segment based on provided ID.. This operation is performed by calling function `update_shield_information_barrier_segment_by_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-shield-information-barrier-segments-id/). ``` client.shield_information_barrier_segments.update_shield_information_barrier_segment_by_id( segment_id, description=updated_segment_description ) ``` ### Arguments shield_information_barrier_segment_id `str` - The ID of the shield information barrier segment. Example: "3423" name `Optional[str]` - The updated name for the shield information barrier segment. description `Optional[str]` - The updated description for the shield information barrier segment. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `ShieldInformationBarrierSegment`. Returns the updated shield information barrier segment object. ## List shield information barrier segments Retrieves a list of shield information barrier segment objects for the specified Information Barrier ID. This operation is performed by calling function `get_shield_information_barrier_segments`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-shield-information-barrier-segments/). ``` client.shield_information_barrier_segments.get_shield_information_barrier_segments( barrier_id ) ``` ### Arguments shield_information_barrier_id `str` - The ID of the shield information barrier. marker `Optional[str]` - Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`. limit `Optional[int]` - The maximum number of items to return per page. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `ShieldInformationBarrierSegments`. Returns a paginated list of shield information barrier segment objects. ## Create shield information barrier segment Creates a shield information barrier segment. This operation is performed by calling function `create_shield_information_barrier_segment`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-shield-information-barrier-segments/). ``` client.shield_information_barrier_segments.create_shield_information_barrier_segment( ShieldInformationBarrierBase( id=barrier_id, type=ShieldInformationBarrierBaseTypeField.SHIELD_INFORMATION_BARRIER, ), segment_name, description=segment_description, ) ``` ### Arguments - shield_information_barrier `ShieldInformationBarrierBase` name `str` - Name of the shield information barrier segment. description `Optional[str]` - Description of the shield information barrier segment. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `ShieldInformationBarrierSegment`. Returns a new shield information barrier segment object. --- ### ShieldInformationBarriersManager **Type:** page | **Section:** Additional Resources ShieldInformationBarriersManager Get shield information barrier with specified ID Add changed status of shield information barrier with… # ShieldInformationBarriersManager - [Get shield information barrier with specified ID](#get-shield-information-barrier-with-specified-id) - [Add changed status of shield information barrier with specified ID](#add-changed-status-of-shield-information-barrier-with-specified-id) - [List shield information barriers](#list-shield-information-barriers) - [Create shield information barrier](#create-shield-information-barrier) ## Get shield information barrier with specified ID Get shield information barrier based on provided ID. This operation is performed by calling function `getShieldInformationBarrierById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-shield-information-barriers-id/). ``` await client.shieldInformationBarriers.getShieldInformationBarrierById( barrierId, ); ``` ### Arguments shieldInformationBarrierId `string` - The ID of the shield information barrier. Example: "1910967" optionalsInput `GetShieldInformationBarrierByIdOptionalsInput` ### Returns This function returns a value of type `ShieldInformationBarrier`. Returns the shield information barrier object. ## Add changed status of shield information barrier with specified ID Change status of shield information barrier with the specified ID. This operation is performed by calling function `updateShieldInformationBarrierStatus`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-shield-information-barriers-change-status/). ``` await client.shieldInformationBarriers.updateShieldInformationBarrierStatus({ id: barrierId, status: 'disabled' as UpdateShieldInformationBarrierStatusRequestBodyStatusField, } satisfies UpdateShieldInformationBarrierStatusRequestBody); ``` ### Arguments requestBody `UpdateShieldInformationBarrierStatusRequestBody` - Request body of updateShieldInformationBarrierStatus method optionalsInput `UpdateShieldInformationBarrierStatusOptionalsInput` ### Returns This function returns a value of type `ShieldInformationBarrier`. Returns the updated shield information barrier object. ## List shield information barriers Retrieves a list of shield information barrier objects for the enterprise of JWT. This operation is performed by calling function `getShieldInformationBarriers`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-shield-information-barriers/). ``` await client.shieldInformationBarriers.getShieldInformationBarriers(); ``` ### Arguments queryParams `GetShieldInformationBarriersQueryParams` - Query parameters of getShieldInformationBarriers method headersInput `GetShieldInformationBarriersHeadersInput` - Headers of getShieldInformationBarriers method cancellationToken `undefined | CancellationToken` - Token used for request cancellation. ### Returns This function returns a value of type `ShieldInformationBarriers`. Returns a paginated list of shield information barrier objects, empty list if currently no barrier. ## Create shield information barrier Creates a shield information barrier to separate individuals/groups within the same firm and prevents confidential information passing between them. This operation is performed by calling function `createShieldInformationBarrier`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-shield-information-barriers/). ``` await client.shieldInformationBarriers.createShieldInformationBarrier({ enterprise: { id: enterpriseId } satisfies EnterpriseBase, } satisfies CreateShieldInformationBarrierRequestBody); ``` ### Arguments requestBody `CreateShieldInformationBarrierRequestBody` - Request body of createShieldInformationBarrier method optionalsInput `CreateShieldInformationBarrierOptionalsInput` ### Returns This function returns a value of type `ShieldInformationBarrier`. Returns a new shield information barrier object. --- ### ShieldInformationBarriersManager **Type:** page | **Section:** Additional Resources ShieldInformationBarriersManager Get shield information barrier with specified ID Add changed status of shield information barrier with… # ShieldInformationBarriersManager - [Get shield information barrier with specified ID](#get-shield-information-barrier-with-specified-id) - [Add changed status of shield information barrier with specified ID](#add-changed-status-of-shield-information-barrier-with-specified-id) - [List shield information barriers](#list-shield-information-barriers) - [Create shield information barrier](#create-shield-information-barrier) ## Get shield information barrier with specified ID Get shield information barrier based on provided ID. This operation is performed by calling function `get_shield_information_barrier_by_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-shield-information-barriers-id/). ``` client.shield_information_barriers.get_shield_information_barrier_by_id(barrier_id) ``` ### Arguments shield_information_barrier_id `str` - The ID of the shield information barrier. Example: "1910967" extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `ShieldInformationBarrier`. Returns the shield information barrier object. ## Add changed status of shield information barrier with specified ID Change status of shield information barrier with the specified ID. This operation is performed by calling function `update_shield_information_barrier_status`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-shield-information-barriers-change-status/). ``` client.shield_information_barriers.update_shield_information_barrier_status( barrier_id, UpdateShieldInformationBarrierStatusStatus.DISABLED ) ``` ### Arguments id `str` - The ID of the shield information barrier. status `UpdateShieldInformationBarrierStatusStatus` - The desired status for the shield information barrier. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `ShieldInformationBarrier`. Returns the updated shield information barrier object. ## List shield information barriers Retrieves a list of shield information barrier objects for the enterprise of JWT. This operation is performed by calling function `get_shield_information_barriers`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-shield-information-barriers/). ``` client.shield_information_barriers.get_shield_information_barriers() ``` ### Arguments marker `Optional[str]` - Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. limit `Optional[int]` - The maximum number of items to return per page. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `ShieldInformationBarriers`. Returns a paginated list of shield information barrier objects, empty list if currently no barrier. ## Create shield information barrier Creates a shield information barrier to separate individuals/groups within the same firm and prevents confidential information passing between them. This operation is performed by calling function `create_shield_information_barrier`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-shield-information-barriers/). ``` client.shield_information_barriers.create_shield_information_barrier( EnterpriseBase(id=enterprise_id) ) ``` ### Arguments enterprise `EnterpriseBase` - The `type` and `id` of enterprise this barrier is under. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `ShieldInformationBarrier`. Returns a new shield information barrier object. --- ### ShieldListsManager **Type:** page | **Section:** Additional Resources ShieldListsManager Get all shield lists in enterprise Create shield list Get single shield list by shield list id Delete single shield list… # ShieldListsManager - [Get all shield lists in enterprise](#get-all-shield-lists-in-enterprise) - [Create shield list](#create-shield-list) - [Get single shield list by shield list id](#get-single-shield-list-by-shield-list-id) - [Delete single shield list by shield list id](#delete-single-shield-list-by-shield-list-id) - [Update shield list](#update-shield-list) ## Get all shield lists in enterprise Retrieves all shield lists in the enterprise. This operation is performed by calling function `getShieldListsV2025R0`. See the endpoint docs at [API Reference](https://developer.box.com/reference/v2025.0/get-shield-lists/). ``` await client.shieldLists.getShieldListsV2025R0(); ``` ### Arguments headersInput `GetShieldListsV2025R0HeadersInput` - Headers of getShieldListsV2025R0 method cancellationToken `undefined | CancellationToken` - Token used for request cancellation. ### Returns This function returns a value of type `ShieldListsV2025R0`. Returns the list of shield list objects. ## Create shield list Creates a shield list. This operation is performed by calling function `createShieldListV2025R0`. See the endpoint docs at [API Reference](https://developer.box.com/reference/v2025.0/post-shield-lists/). ``` await client.shieldLists.createShieldListV2025R0({ name: shieldListCountryName, description: 'A list of things that are shielded', content: new ShieldListContentCountryV2025R0({ type: 'country' as ShieldListContentCountryV2025R0TypeField, countryCodes: ['US', 'PL'], }), } satisfies ShieldListsCreateV2025R0); ``` ### Arguments requestBody `ShieldListsCreateV2025R0` - Request body of createShieldListV2025R0 method optionalsInput `CreateShieldListV2025R0OptionalsInput` ### Returns This function returns a value of type `ShieldListV2025R0`. Returns the shield list object. ## Get single shield list by shield list id Retrieves a single shield list by its ID. This operation is performed by calling function `getShieldListByIdV2025R0`. See the endpoint docs at [API Reference](https://developer.box.com/reference/v2025.0/get-shield-lists-id/). ``` await client.shieldLists.getShieldListByIdV2025R0(shieldListCountry.id); ``` ### Arguments shieldListId `string` - The unique identifier that represents a shield list. The ID for any Shield List can be determined by the response from the endpoint fetching all shield lists for the enterprise. Example: "90fb0e17-c332-40ed-b4f9-fa8908fbbb24 " optionalsInput `GetShieldListByIdV2025R0OptionalsInput` ### Returns This function returns a value of type `ShieldListV2025R0`. Returns the shield list object. ## Delete single shield list by shield list id Delete a single shield list by its ID. This operation is performed by calling function `deleteShieldListByIdV2025R0`. See the endpoint docs at [API Reference](https://developer.box.com/reference/v2025.0/delete-shield-lists-id/). ``` await client.shieldLists.deleteShieldListByIdV2025R0(shieldListCountry.id); ``` ### Arguments shieldListId `string` - The unique identifier that represents a shield list. The ID for any Shield List can be determined by the response from the endpoint fetching all shield lists for the enterprise. Example: "90fb0e17-c332-40ed-b4f9-fa8908fbbb24 " optionalsInput `DeleteShieldListByIdV2025R0OptionalsInput` ### Returns This function returns a value of type `undefined`. Shield List correctly removed. No content in response. ## Update shield list Updates a shield list. This operation is performed by calling function `updateShieldListByIdV2025R0`. See the endpoint docs at [API Reference](https://developer.box.com/reference/v2025.0/put-shield-lists-id/). ``` await client.shieldLists.updateShieldListByIdV2025R0(shieldListCountry.id, { name: shieldListCountryName, description: 'Updated description', content: new ShieldListContentCountryV2025R0({ type: 'country' as ShieldListContentCountryV2025R0TypeField, countryCodes: ['US'], }), } satisfies ShieldListsUpdateV2025R0); ``` ### Arguments shieldListId `string` - The unique identifier that represents a shield list. The ID for any Shield List can be determined by the response from the endpoint fetching all shield lists for the enterprise. Example: "90fb0e17-c332-40ed-b4f9-fa8908fbbb24 " requestBody `ShieldListsUpdateV2025R0` - Request body of updateShieldListByIdV2025R0 method optionalsInput `UpdateShieldListByIdV2025R0OptionalsInput` ### Returns This function returns a value of type `ShieldListV2025R0`. Returns the shield list object. --- ### ShieldListsManager **Type:** page | **Section:** Additional Resources ShieldListsManager Get all shield lists in enterprise Create shield list Get single shield list by shield list id Delete single shield list… # ShieldListsManager - [Get all shield lists in enterprise](#get-all-shield-lists-in-enterprise) - [Create shield list](#create-shield-list) - [Get single shield list by shield list id](#get-single-shield-list-by-shield-list-id) - [Delete single shield list by shield list id](#delete-single-shield-list-by-shield-list-id) - [Update shield list](#update-shield-list) ## Get all shield lists in enterprise Retrieves all shield lists in the enterprise. This operation is performed by calling function `get_shield_lists_v2025_r0`. See the endpoint docs at [API Reference](https://developer.box.com/reference/v2025.0/get-shield-lists/). ``` client.shield_lists.get_shield_lists_v2025_r0() ``` ### Arguments box_version `BoxVersionHeaderV2025R0` - Version header. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `ShieldListsV2025R0`. Returns the list of shield list objects. ## Create shield list Creates a shield list. This operation is performed by calling function `create_shield_list_v2025_r0`. See the endpoint docs at [API Reference](https://developer.box.com/reference/v2025.0/post-shield-lists/). ``` client.shield_lists.create_shield_list_v2025_r0( shield_list_country_name, ShieldListContentCountryV2025R0( type=ShieldListContentCountryV2025R0TypeField.COUNTRY, country_codes=["US", "PL"], ), description="A list of things that are shielded", ) ``` ### Arguments name `str` - The name of the shield list. description `Optional[str]` - Optional description of Shield List. content `ShieldListContentRequestV2025R0` box_version `BoxVersionHeaderV2025R0` - Version header. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `ShieldListV2025R0`. Returns the shield list object. ## Get single shield list by shield list id Retrieves a single shield list by its ID. This operation is performed by calling function `get_shield_list_by_id_v2025_r0`. See the endpoint docs at [API Reference](https://developer.box.com/reference/v2025.0/get-shield-lists-id/). ``` client.shield_lists.get_shield_list_by_id_v2025_r0(shield_list_country.id) ``` ### Arguments shield_list_id `str` - The unique identifier that represents a shield list. The ID for any Shield List can be determined by the response from the endpoint fetching all shield lists for the enterprise. Example: "90fb0e17-c332-40ed-b4f9-fa8908fbbb24 " box_version `BoxVersionHeaderV2025R0` - Version header. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `ShieldListV2025R0`. Returns the shield list object. ## Delete single shield list by shield list id Delete a single shield list by its ID. This operation is performed by calling function `delete_shield_list_by_id_v2025_r0`. See the endpoint docs at [API Reference](https://developer.box.com/reference/v2025.0/delete-shield-lists-id/). ``` client.shield_lists.delete_shield_list_by_id_v2025_r0(shield_list_country.id) ``` ### Arguments shield_list_id `str` - The unique identifier that represents a shield list. The ID for any Shield List can be determined by the response from the endpoint fetching all shield lists for the enterprise. Example: "90fb0e17-c332-40ed-b4f9-fa8908fbbb24 " box_version `BoxVersionHeaderV2025R0` - Version header. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `None`. Shield List correctly removed. No content in response. ## Update shield list Updates a shield list. This operation is performed by calling function `update_shield_list_by_id_v2025_r0`. See the endpoint docs at [API Reference](https://developer.box.com/reference/v2025.0/put-shield-lists-id/). ``` client.shield_lists.update_shield_list_by_id_v2025_r0( shield_list_country.id, shield_list_country_name, ShieldListContentCountryV2025R0( type=ShieldListContentCountryV2025R0TypeField.COUNTRY, country_codes=["US"] ), description="Updated description", ) ``` ### Arguments shield_list_id `str` - The unique identifier that represents a shield list. The ID for any Shield List can be determined by the response from the endpoint fetching all shield lists for the enterprise. Example: "90fb0e17-c332-40ed-b4f9-fa8908fbbb24 " name `str` - The name of the shield list. description `Optional[str]` - Optional description of Shield List. content `ShieldListContentRequestV2025R0` box_version `BoxVersionHeaderV2025R0` - Version header. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `ShieldListV2025R0`. Returns the shield list object. --- ### Sign Requests **Type:** page | **Section:** Additional Resources Sign Requests Get sign request by ID List sign requests Create sign request Cancel sign request Resend sign request Get sign request by ID… # Sign Requests - [Get sign request by ID](#get-sign-request-by-id) - [List sign requests](#list-sign-requests) - [Create sign request](#create-sign-request) - [Cancel sign request](#cancel-sign-request) - [Resend sign request](#resend-sign-request) ## Get sign request by ID Gets a sign request by ID [`signRequests.getById(options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/SignRequestsManager.html#getById) method. ``` const sr = await client.signRequests.getById({ sign_request_id: 12345, }); console.log( `Sign request id ${sr.id} contains ${sr.source_files.length} files` ); ``` ## List sign requests Gets sign requests created by a user [`signRequests.getAll(options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/SignRequestsManager.html#getAll) method. ``` const result = await client.signRequests.getAll(); console.log(`There are ${result.count} sign requests`); ``` ## Create sign request Creates a sign request. This involves preparing a document for signing and sending the sign request to signers. [`signRequests.create(body, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/SignRequestsManager.html#create) method. The list of source files is currently limited to ten files. Only the ID and type fields are required for each file. ``` const signRequest = await client.signRequests.create({ signers: [ { role: 'signer', email: 'user@example.com', }, ], source_files: [ { type: 'file', id: '12345', }, ], parent_folder: { type: 'folder', id: '1234567', }, }); console.log(`Created a new sign request id ${signRequest.id}`); ``` ## Cancel sign request Cancels a sign request [`signRequests.cancelById(options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/SignRequestsManager.html#cancelById) method. ``` const signRequest = await client.signRequests.cancelById({ sign_request_id: 12345, }); console.log(`Sign request id ${sr.id} cancelled`); ``` ## Resend sign request Resends a sign request email to all outstanding signers [`signRequests.resendById(options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/SignRequestsManager.html#resendById) method. ``` const id = 12345; await client.signRequests.resendById({ sign_request_id: id }); console.log(`Sign request id ${sr.id} resent`); ``` --- ### Sign Requests **Type:** page | **Section:** Additional Resources Sign Requests Sign Requests are used to request e-signatures on documents from signers. A Sign Request can refer to one or more Box Files… # Sign Requests Sign Requests are used to request e-signatures on documents from signers. A Sign Request can refer to one or more Box Files and can be sent to one or more Box Sign Request Signers. - [Create Sign Request](#create-sign-request) - [Get all Sign Requests](#get-all-sign-requests) - [Get Sign Request by ID](#get-sign-request-by-id) - [Cancel Sign Request](#cancel-sign-request) - [Resend Sign Request](#resend-sign-request) ## Create Sign Request The [`createSignRequest(BoxAPIConnection api, List<BoxSignRequestSigner> signers, List<BoxSignRequestFile> files, String parentFolderId)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxSignRequest.html#createSignRequest-com.box.sdk.BoxAPIConnection-java.util.List-java.util.List-java.lang.String-) method will create a Sign Request. You need to provide 1 to 10 files (from which the signing document will be created) and at least one signer to receive the Sign Request. You can use [`BoxSignRequestFile`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxSignRequestFile.html) and [`BoxSignRequestSigner`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxSignRequestSigner.html) classes to provide the necessary data. ``` List<BoxSignRequestFile> files = new ArrayList<BoxSignRequestFile>(); BoxSignRequestFile file = new BoxSignRequestFile("12345"); files.add(file); // you can also use specific version of the file BoxFile file = new BoxFile(api, "12345"); List<BoxFileVersion> versions = file.getVersions(); BoxFileVersion firstVersion = versions.get(0); BoxSignRequestFile file = new BoxSignRequestFile(firstVersion.getFileID(), firstVersion.getVersionID()); List<BoxSignRequestSigner> signers = new ArrayList<BoxSignRequestSigner>(); BoxSignRequestSigner newSigner = new BoxSignRequestSigner("signer@mail.com"); signers.add(newSigner); String destinationParentFolderId = "55555"; BoxSignRequest.Info signRequestInfo = BoxSignRequest.createSignRequest(api, files, signers, destinationParentFolderId); ``` [`createSignRequest`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxSignRequest.html#createSignRequest-com.box.sdk.BoxAPIConnection-java.util.List-java.util.List-java.lang.String-) allows you to specify optional parameters using the [`BoxSignRequestCreateParams`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxSignRequestCreateParams.html) object. ``` List<BoxSignRequestFile> files = new ArrayList<BoxSignRequestFile>(); BoxSignRequestFile file = new BoxSignRequestFile("12345"); files.add(file); List<BoxSignRequestSigner> signers = new ArrayList<BoxSignRequestSigner>(); BoxSignRequestSigner newSigner = new BoxSignRequestSigner("signer@mail.com"); signers.add(newSigner); String destinationParentFolderId = "55555"; BoxSignRequestCreateParams createParams = new BoxSignRequestCreateParams() .setIsDocumentPreparationNeeded(true); BoxSignRequest.Info signRequestInfo = BoxSignRequest.createSignRequest(api, files, signers, destinationParentFolderId, createParams); ``` If you set `isDocumentPreparationNeeded` flag to true, you need to visit `prepareUrl` before the Sign Request will be sent. For more information on `isDocumentPreparationNeeded` and the other `BoxSignRequestCreateParams` available, please refer to the [developer documentation](https://developer.box.com/guides/box-sign/). ## Get All Sign Requests Calling the static [`getAll(BoxAPIConnection api, String... fields)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxSignRequest.html#getAll-com.box.sdk.BoxAPIConnection-java.lang.String...-) will return an iterable that will page through all the Sign Requests. The static [`getAll(int limit, BoxAPIConnection api, String... fields)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxSignRequest.html#getAll-int-com.box.sdk.BoxAPIConnection-java.lang.String...-) method offers `limit` and `fields` parameters. The `limit` parameter specifies the maximum number of items to be returned in a single response. The `fields` parameter is used to specify what additional properties should be returned on the `BoxSignRequest.Info` objects. For more information on what `fields` are available, please refer to the [developer documentation](https://developer.box.com/guides/box-sign/). ``` Iterable<BoxSignRequest.Info> signRequests = BoxSignRequest.getAll(api); for (BoxSignRequest.Info signRequestInfo : signRequests) { // Do something with each `signRequestInfo`. } ``` ## Get Sign Request by ID Calling [`getInfo(String fields ...)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxSignRequest.html#getInfo-java.lang.String...-) will return a [`BoxSignRequest.Info`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxSignRequest.Info.html) object containing information about the Sign Request. The `fields` parameter is used to specify what additional properties should be returned on the `BoxSignRequest.Info` objects. ``` BoxSignRequest signRequest = new BoxSignRequest(api, id); BoxSignRequest.Info signRequestInfo = signRequest.getInfo(); //using `fields` parameter BoxSignRequest.Info signRequestInfoWithFields = signRequest.getInfo("status") ``` ## Cancel Sign Request Calling [`cancel()`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxSignRequest.html#cancel--) will cancel a created Sign Request. ``` BoxSignRequest signRequest = new BoxSignRequest(api, id); BoxSignRequest.Info signRequestInfo = signRequest.getInfo(); signRequestInfo.cancel(); ``` ## Resend Sign Request Calling [`resend()`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxSignRequest.html#resend--) will resend a Sign Request to all signers that have not signed it yet. There is an 10-minute cooling-off period between re-sending reminder emails. If this method is called during the cooling-off period, a [`BoxAPIException`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxAPIException.html) will be thrown. ``` BoxSignRequest signRequest = new BoxSignRequest(api, id); BoxSignRequest.Info signRequestInfo = signRequest.getInfo(); signRequestInfo.resend(); ``` --- ### Sign Requests **Type:** page | **Section:** Additional Resources Sign Requests Sign Requests are used to request e-signatures on documents from signers. A Sign Request can refer to one or more Box Files… # Sign Requests Sign Requests are used to request e-signatures on documents from signers. A Sign Request can refer to one or more Box Files and can be sent to one or more Box Sign Request Signers. - [Create Sign Request](#create-sign-request) - [Get all Sign Requests](#get-all-sign-requests) - [Get Sign Request by ID](#get-sign-request-by-id) - [Cancel Sign Request](#cancel-sign-request) - [Resend Sign Request](#resend-sign-request) ## Create Sign Request The [`client.create_sign_request_v2(signers, files=None, parent_folder_id=None, prefill_tags=None, are_reminders_enabled=None, are_text_signatures_enabled=None, days_valid=None, email_message=None, email_subject=None, external_id=None, is_document_preparation_needed=None, redirect_url=None, declined_redirect_url=None, template_id=None)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.client.html#boxsdk.client.client.Client.create_sign_request) method will create a Sign Request. You need to provide at least one file and up to 10 files (from which the signing document will be created) or template_id of the sign request template. You need to include at least one signer that will receive the Sign Request. Example with files: ``` source_file = { 'id': '12345', 'type': 'file' } files = [source_file] signer = { 'name': 'John Doe', 'email': 'signer@mail.com' } signers = [signer] parent_folder_id = '123456789' new_sign_request = client.create_sign_request_v2(signers, files=files, parent_folder_id=parent_folder_id) print(f'(Sign Request ID: {new_sign_request.id})') ``` Example with sign template ``` signer = { 'name': 'John Doe', 'email': 'signer@mail.com' } new_sign_request = client.create_sign_request_v2(signers, template_id='12345') print(f'(Sign Request ID: {new_sign_request.id})') ``` If you set `isDocumentPreparationNeeded` flag to true, you need to visit `prepareUrl` before the Sign Request will be sent. For more information on `isDocumentPreparationNeeded` and the other parameters available, please refer to the [developer documentation](https://developer.box.com/guides/sign-request/). ## Get All Sign Requests Calling the [`client.get_sign_requests()`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.client.html#boxsdk.client.client.Client.get_sign_requests) will return an iterable that will page through all the Sign Requests. This method offers `limit` and `fields` parameters. The `limit` parameter specifies the maximum number of items to be returned in a single response. The `fields` parameter is used to specify what additional properties should be returned on the return object. For more information on what `fields` are available, please refer to the [developer documentation](https://developer.box.com/guides/box-sign/). ``` sign_requests = client.get_sign_requests() for sign_request in sign_requests: print(f'(Sign Request ID: {sign_request.id})') ``` ## Get Sign Request by ID Calling [`client.sign_request(sign_request_id)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.client.html#boxsdk.client.client.Client.sign_request) will return an object containing information about the Sign Request. The `fields` parameter is used to specify what additional properties should be returned in the return object. ``` sign_request = client.sign_request(sign_request_id='12345').get() print(f'Sign Request ID is {sign_request.id}') ``` ## Cancel Sign Request Calling [`sign_requests.cancel()`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.retention_policy.SignRequest.cancel) will cancel a created Sign Request. ``` sign_request = client.sign_request(sign_request_id='12345') cancelled_sign_request = sign_request.cancel() print(f'Cancelled Sign Request status is {cancelled_sign_request.status}') ``` ## Resend Sign Request Calling [`sign_requests.resend()`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.retention_policy.SignRequest.resend) will resend a Sign Request to all signers that have not signed it yet. There is an 10-minute cooling-off period between re-sending reminder emails. ``` sign_request = client.sign_request(sign_request_id='12345') sign_request.resend() ``` --- ### Sign Requests **Type:** page | **Section:** Additional Resources Sign Requests Sign Requests are used to request e-signatures on documents from signers. A Sign Request can refer to one or more Box Files… # Sign Requests Sign Requests are used to request e-signatures on documents from signers. A Sign Request can refer to one or more Box Files and can be sent to one or more Box Sign Request Signers. - [Create Sign Request](#create-sign-request) - [Get all Sign Requests](#get-all-sign-requests) - [Get Sign Request by ID](#get-sign-request-by-id) - [Cancel Sign Request](#cancel-sign-request) - [Resend Sign Request](#resend-sign-request) ## Create Sign Request The `SignRequestsManager.CreateSignRequestAsync(BoxSignRequestCreateRequest signRequestCreateRequest)` method will create a Sign Request. You need to provide at least one file and up to ten files (from which the signing document will be created) with at least one signer to receive the Sign Request. ``` var sourceFiles = new List<BoxSignRequestCreateSourceFile> { new BoxSignRequestCreateSourceFile() { Id = "12345" } }; var signers = new List<BoxSignRequestSignerCreate> { new BoxSignRequestSignerCreate() { Email = "example@gmail.com" } }; var parentFolder = new BoxRequestEntity() { Id = "12345", Type = BoxType.folder }; var request = new BoxSignRequestCreateRequest { SourceFiles = sourceFiles, Signers = signers, ParentFolder = parentFolder }; BoxSignRequest signRequest = await client.SignRequestsManager.CreateSignRequestAsync(request); ``` If you set `isDocumentPreparationNeeded` flag to true, you need to visit `prepareUrl` before the Sign Request will be sent. For more information on `isDocumentPreparationNeeded` and the other parameters available, please refer to the [developer documentation](https://developer.box.com/guides/sign-request/). ## Get All Sign Requests Calling the `SignRequestsManager.GetSignRequestsAsync(int limit = 100, string nextMarker = null, bool autoPaginate = false)` will return an iterable that will page through all the Sign Requests. ``` BoxCollectionMarkerBased<BoxSignRequest> signRequests = await client.SignRequestsManager.GetSignRequestsAsync(); ``` ## Get Sign Request by ID Calling `SignRequestsManager.GetSignRequestByIdAsync(string signRequestId)` will return an object containing information about the Sign Request. ``` BoxSignRequest signRequest = await client.SignRequestsManager.GetSignRequestByIdAsync("12345"); ``` ## Cancel Sign Request Calling `SignRequestsManager.CancelSignRequestAsync(string signRequestId)` will cancel a created Sign Request. ``` BoxSignRequest cancelledSignRequest = await client.SignRequestsManager.CancelSignRequestAsync("12345"); ``` ## Resend Sign Request Calling `SignRequestsManager.ResendSignRequestAsync(string signRequestId)` will resend a Sign Request to all signers that have not signed it yet. There is an 10-minute cooling-off period between re-sending reminder emails. ``` await client.SignRequestsManager.ResendSignRequestAsync("12345"); ``` --- ### Sign Requests **Type:** page | **Section:** Additional Resources Sign Requests Sign Requests are used to request e-signatures on documents from signers. A Sign Request can refer to one or more Box Files… # Sign Requests Sign Requests are used to request e-signatures on documents from signers. A Sign Request can refer to one or more Box Files and can be sent to one or more Box Sign Request Signers. - [Create Sign Request](#create-sign-request) - [List Sign Requests](#list-sign-requests) - [Get Sign Request by ID](#get-sign-request-by-id) - [Cancel Sign Request by ID](#cancel-sign-request-by-id) - [Resend Sign Request by ID](#resend-sign-request-by-id) ## Create Sign Request To create a sign request, call [`client.signRequests.create(signers:sourceFiles:parentFolder:parameters:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/SignRequestsModule.html#/s:6BoxSDK18SignRequestsModuleC6create7signers11sourceFiles12parentFolder10parameters10completionySayAA0C19RequestCreateSignerVG_SayAA0cnO10SourceFileVGAA0cno6ParentK0VAA0cnO10ParametersVSgys6ResultOyAA0cN0CAA0A8SDKErrorCGctF) You need to provide at least one file and up to ten files (from which the signing document will be created) with at least one signer to receive the Sign Request and a destination folder. You should use [`SignRequestCreateSourceFile`](https://opensource.box.com/box-ios-sdk/Structs/SignRequestCreateSourceFile.html) ,[`SignRequestCreateSigner`](https://opensource.box.com/box-ios-sdk/Structs/SignRequestCreateSigner.html) and [`SignRequestCreateParentFolder`](https://opensource.box.com/box-ios-sdk/Structs/SignRequestCreateParentFolder.html) types to provide the necessary data. ``` let signers = [SignRequestCreateSigner(email: "signer@mail.com", role: .approver)] let sourceFiles = [SignRequestCreateSourceFile(id: "12345"), SignRequestCreateSourceFile(id: "34567")] let parentFolder = SignRequestCreateParentFolder(id: "234") client.signRequests.create(signers: signers, sourceFiles: sourceFiles, parentFolder: parentFolder) { (result: Result<SignRequest, BoxSDKError>) in guard case let .success(signRequest) = result else { print("Error creating sign request") return } print("Sign request \(signRequest.id) was created") } ``` [`create`](https://opensource.box.com/box-ios-sdk/Classes/SignRequestsModule.html#/s:6BoxSDK18SignRequestsModuleC6create7signers11sourceFiles12parentFolder10parameters10completionySayAA0C19RequestCreateSignerVG_SayAA0cnO10SourceFileVGAA0cno6ParentK0VAA0cnO10ParametersVSgys6ResultOyAA0cN0CAA0A8SDKErrorCGctF) method allows you to specify optional parameters using the [`SignRequestCreateParameters`](https://opensource.box.com/box-ios-sdk/Structs/SignRequestCreateParameters.html) object. ``` let signers = [SignRequestCreateSigner(email: "signer@mail.com", role: .approver)] let sourceFiles = [SignRequestCreateSourceFile(id: "12345", fileVersionId: "5")] let parentFolder = SignRequestCreateParentFolder(id: "234") let params = SignRequestCreateParameters( isDocumentPreparationNeeded: true, emailSubject: "Sign Request from Acme", emailMessage: "Hello! Please sign the document below" ) client.signRequests.create(signers: signers, sourceFiles: sourceFiles, parentFolder: parentFolder) { (result: Result<SignRequest, BoxSDKError>) in guard case let .success(signRequest) = result else { print("Error creating sign request") return } print("Sign request \(signRequest.id) was created") } ``` If you set `isDocumentPreparationNeeded` flag to true, you need to visit `prepareUrl` before the Sign Request will be sent. ## List Sign Requests To retrieve sign requests, call [`client.signRequests.list(marker:limit:)`](https://opensource.box.com/box-ios-sdk/Classes/SignRequestsModule.html#/s:6BoxSDK18SignRequestsModuleC4list6marker5limitAA14PagingIteratorCyAA0C7RequestCGSSSg_SiSgtF). This method will return an iterator object, which is used to get the sign requests. ``` let iterator = client.signRequests.list() iterator.next { results in switch results { case let .success(page): for signRequest in page.entries { print("Sign request \(signRequest.id)") } case let .failure(error): print(error) } } ``` ## Get Sign Request by ID To retrieve information about a sign request, call [`client.signRequests.getById(id:)`](https://opensource.box.com/box-ios-sdk/Classes/SignRequestsModule.html#/s:6BoxSDK18SignRequestsModuleC7getById2id10completionySS_ys6ResultOyAA0C7RequestCAA0A8SDKErrorCGctF) with the ID of the sign request. ``` client.signRequests.getById(id: "1234") { (result: Result<SignRequest, BoxSDKError>) in guard case let .success(signRequest) = result else { print("Error getting sign request") return } print("Sign request \(signRequest.id)") } ``` ## Cancel Sign Request by ID To cancel a created sign request, call [`client.signRequests.cancelById(id:, completion:)`](https://opensource.box.com/box-ios-sdk/Classes/SignRequestsModule.html#/s:6BoxSDK18SignRequestsModuleC10cancelById2id10completionySS_ys6ResultOyAA0C7RequestCAA0A8SDKErrorCGctF) ``` client.signRequests.cancelById(id: "1234") { (result: Result<SignRequest, BoxSDKError>) in guard case let .success(signRequest) = result else { print("Error cancelling sign request") return } print("Sign request \(signRequest.id) is cancelled") } ``` ## Resend Sign Request by ID To resend a sign request to all signers that have not signed it yet, call [`client.signRequests.resendById(id:, completion:)`](https://opensource.box.com/box-ios-sdk/Classes/SignRequestsModule.html#/s:6BoxSDK18SignRequestsModuleC10resendById2id10completionySS_ys6ResultOyytAA0A8SDKErrorCGctF). There is an 10-minute cooling-off period between re-sending reminder emails. If this method is called during the cooling-off period, a BoxAPIError will be thrown. ``` client.signRequests.resendById(id: "1234") { result: Result<Void, BoxSDKError>} in guard case .success = result else { print("Error resending sign request") return } print("Sign request successfully resent") } ``` --- ### Sign Requests **Type:** page | **Section:** Additional Resources Sign Requests Sign Requests are used to request e-signatures on documents from signers. A Sign Request can refer to one or more Box Files… # Sign Requests Sign Requests are used to request e-signatures on documents from signers. A Sign Request can refer to one or more Box Files and can be sent to one or more Box Sign Request Signers. - [Create Sign Request](#create-sign-request) - [List Sign Requests](#list-sign-requests) - [Get Sign Request by ID](#get-sign-request-by-id) - [Cancel Sign Request by ID](#cancel-sign-request-by-id) - [Resend Sign Request by ID](#resend-sign-request-by-id) ## Create Sign Request To create a sign request, call [`client.signRequests.create(signers:sourceFiles:parentFolder:parameters:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/SignRequestsModule.html#/s:6BoxSDK18SignRequestsModuleC6create7signers11sourceFiles12parentFolder10parameters10completionySayAA0C19RequestCreateSignerVG_SayAA0cnO10SourceFileVGAA0cno6ParentK0VAA0cnO10ParametersVSgys6ResultOyAA0cN0CAA0A8SDKErrorCGctF) You need to provide at least one file and up to ten files (from which the signing document will be created) with at least one signer to receive the Sign Request and a destination folder. You should use [`SignRequestCreateSourceFile`](https://opensource.box.com/box-ios-sdk/Structs/SignRequestCreateSourceFile.html) ,[`SignRequestCreateSigner`](https://opensource.box.com/box-ios-sdk/Structs/SignRequestCreateSigner.html) and [`SignRequestCreateParentFolder`](https://opensource.box.com/box-ios-sdk/Structs/SignRequestCreateParentFolder.html) types to provide the necessary data. ``` let signers = [SignRequestCreateSigner(email: "signer@mail.com", role: .approver)] let sourceFiles = [SignRequestCreateSourceFile(id: "12345"), SignRequestCreateSourceFile(id: "34567")] let parentFolder = SignRequestCreateParentFolder(id: "234") client.signRequests.create(signers: signers, sourceFiles: sourceFiles, parentFolder: parentFolder) { (result: Result<SignRequest, BoxSDKError>) in guard case let .success(signRequest) = result else { print("Error creating sign request") return } print("Sign request \(signRequest.id) was created") } ``` [`create`](https://opensource.box.com/box-ios-sdk/Classes/SignRequestsModule.html#/s:6BoxSDK18SignRequestsModuleC6create7signers11sourceFiles12parentFolder10parameters10completionySayAA0C19RequestCreateSignerVG_SayAA0cnO10SourceFileVGAA0cno6ParentK0VAA0cnO10ParametersVSgys6ResultOyAA0cN0CAA0A8SDKErrorCGctF) method allows you to specify optional parameters using the [`SignRequestCreateParameters`](https://opensource.box.com/box-ios-sdk/Structs/SignRequestCreateParameters.html) object. ``` let signers = [SignRequestCreateSigner(email: "signer@mail.com", role: .approver)] let sourceFiles = [SignRequestCreateSourceFile(id: "12345", fileVersionId: "5")] let parentFolder = SignRequestCreateParentFolder(id: "234") let params = SignRequestCreateParameters( isDocumentPreparationNeeded: true, emailSubject: "Sign Request from Acme", emailMessage: "Hello! Please sign the document below" ) client.signRequests.create(signers: signers, sourceFiles: sourceFiles, parentFolder: parentFolder) { (result: Result<SignRequest, BoxSDKError>) in guard case let .success(signRequest) = result else { print("Error creating sign request") return } print("Sign request \(signRequest.id) was created") } ``` If you set `isDocumentPreparationNeeded` flag to true, you need to visit `prepareUrl` before the Sign Request will be sent. ## List Sign Requests To retrieve sign requests, call [`client.signRequests.list(marker:limit:)`](https://opensource.box.com/box-ios-sdk/Classes/SignRequestsModule.html#/s:6BoxSDK18SignRequestsModuleC4list6marker5limitAA14PagingIteratorCyAA0C7RequestCGSSSg_SiSgtF). This method will return an iterator object, which is used to get the sign requests. ``` let iterator = client.signRequests.list() iterator.next { results in switch results { case let .success(page): for signRequest in page.entries { print("Sign request \(signRequest.id)") } case let .failure(error): print(error) } } ``` ## Get Sign Request by ID To retrieve information about a sign request, call [`client.signRequests.getById(id:)`](https://opensource.box.com/box-ios-sdk/Classes/SignRequestsModule.html#/s:6BoxSDK18SignRequestsModuleC7getById2id10completionySS_ys6ResultOyAA0C7RequestCAA0A8SDKErrorCGctF) with the ID of the sign request. ``` client.signRequests.getById(id: "1234") { (result: Result<SignRequest, BoxSDKError>) in guard case let .success(signRequest) = result else { print("Error getting sign request") return } print("Sign request \(signRequest.id)") } ``` ## Cancel Sign Request by ID To cancel a created sign request, call [`client.signRequests.cancelById(id:, completion:)`](https://opensource.box.com/box-ios-sdk/Classes/SignRequestsModule.html#/s:6BoxSDK18SignRequestsModuleC10cancelById2id10completionySS_ys6ResultOyAA0C7RequestCAA0A8SDKErrorCGctF) ``` client.signRequests.cancelById(id: "1234") { (result: Result<SignRequest, BoxSDKError>) in guard case let .success(signRequest) = result else { print("Error cancelling sign request") return } print("Sign request \(signRequest.id) is cancelled") } ``` ## Resend Sign Request by ID To resend a sign request to all signers that have not signed it yet, call [`client.signRequests.resendById(id:, completion:)`](https://opensource.box.com/box-ios-sdk/Classes/SignRequestsModule.html#/s:6BoxSDK18SignRequestsModuleC10resendById2id10completionySS_ys6ResultOyytAA0A8SDKErrorCGctF). There is an 10-minute cooling-off period between re-sending reminder emails. If this method is called during the cooling-off period, a BoxAPIError will be thrown. ``` client.signRequests.resendById(id: "1234") { result: Result<Void, BoxSDKError>} in guard case .success = result else { print("Error resending sign request") return } print("Sign request successfully resent") } ``` --- ### Sign Templates **Type:** page | **Section:** Additional Resources Sign Templates Get sign template by ID List sign templates Get sign template by ID Gets a sign template by ID signTemplates.getById(options… # Sign Templates - [Get sign template by ID](#get-sign-template-by-id) - [List sign templates](#list-sign-templates) ## Get sign template by ID Gets a sign template by ID [`signTemplates.getById(options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/SignTemplatesManager.html#getById) method. ``` const sr = await client.signTemplates.getById({ template_id: 12345, }); console.log( `Sign template id ${sr.id} contains ${sr.source_files.length} files` ); ``` ## List sign templates Gets sign templates created by a user [`signTemplates.getAll(options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/SignTemplatesManager.html#getAll) method. ``` const result = await client.signTemplates.getAll(); console.log(`There are ${result.count} sign templates`); ``` --- ### Sign Templates **Type:** page | **Section:** Additional Resources Sign Templates Box Sign enables you to create templates so you can automatically add the same fields and formatting to requests for… # Sign Templates Box Sign enables you to create templates so you can automatically add the same fields and formatting to requests for signature. With templates, you don't need to repetitively add the same fields to each request every time you send a new document for signature. Making and testing a template takes a few minutes, but when done it makes working with Box Sign easier and faster. - [Get all Sign Templates](#get-all-sign-templates) - [Get Sign Template by ID](#get-sign-template-by-id) ## Get All Sign Templates Calling the static [`getAll(BoxAPIConnection api)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxSignTemplate.html#getAll-com.box.sdk.BoxAPIConnection-) will return an iterable that will page through all the Sign Templates. The static [`getAll(BoxAPIConnection api, int limit)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxSignTemplate.html#getAll-com.box.sdk.BoxAPIConnection-int-) method offers `limit` parameter. The `limit` parameter specifies the maximum number of items to be returned in a single response. ``` Iterable<BoxSignTemplate.Info> signTemplates = BoxSignTemplate.getAll(api); for (BoxSignTemplate.Info signTemplateInfo : signTemplates) { // Do something with each `signTemplateInfo`. } ``` ## Get Sign Template by ID Calling [`getInfo()`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxSignTemplate.html#getInfo-) will return a [`BoxSignTemplate.Info`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxSignTemplate.Info.html) object containing information about the Sign Template. ``` BoxSignTemplate signTemplate = new BoxSignTemplate(api, id); BoxSignTemplate.Info signTemplateInfo = signTemplate.getInfo(); ``` --- ### Sign Templates **Type:** page | **Section:** Additional Resources Sign Templates Sign Templates are reusable templates that can be used to create Sign Requests. For now, Sign Templates can only be created… # Sign Templates Sign Templates are reusable templates that can be used to create Sign Requests. For now, Sign Templates can only be created through the Box web application. - [Get All Sign Templates](#get-all-sign-templates) - [Get Sign Template by ID](#get-sign-template-by-id) ## Get All Sign Templates Calling the [`client.get_sign_templates()`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.client.html#boxsdk.client.client.Client.get_sign_templates) method will return an iterable that will page through all the Sign Templates. This method offers `limit` parameter. The `limit` parameter specifies the maximum number of items to be returned in a single response. ``` sign_templates = client.get_sign_templates() for sign_template in sign_templates: print(f'(Sign Template ID: {sign_template.id})') ``` ## Get Sign Template by ID Calling the [`client.get_sign_template(template_id)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.client.html#boxsdk.client.client.Client.get_sign_template) method will return a Sign Template object. ``` sign_template = client.get_sign_template('12345') print(f'(Sign Template ID: {sign_template.id})') ``` --- ### Sign Templates **Type:** page | **Section:** Additional Resources Sign Templates Box Sign enables you to create templates so you can automatically add the same fields and formatting to requests for… # Sign Templates Box Sign enables you to create templates so you can automatically add the same fields and formatting to requests for signature. With templates, you don't need to repetitively add the same fields to each request every time you send a new document for signature. - [Get All Sign Templates](#get-all-sign-templates) - [Get Sign Template by ID](#get-sign-template-by-id) ## Get All Sign Templates Calling the `SignTemplatesManager.GetSignTemplatesAsync(int limit = 100, string nextMarker = null, bool autoPaginate = false)` method will return an iterable that will page through all the Sign Templates. ``` BoxCollectionMarkerBased<BoxSignTemplate> signTemplates = await client.SignTemplatesManager.GetSignTemplatesAsync(); ``` ## Get Sign Template by ID Calling the `SignTemplatesManager.GetSignTemplateByIdAsync(string signTemplateId)` method will return the Sign Template with the given ID. ``` BoxSignTemplate signTemplate = await client.SignTemplatesManager.GetSignTemplateByIdAsync("12345"); ``` --- ### SignRequestsManager **Type:** page | **Section:** Additional Resources SignRequestsManager Cancel Box Sign request Resend Box Sign request Get Box Sign request by ID List Box Sign requests Create Box Sign… # SignRequestsManager - [Cancel Box Sign request](#cancel-box-sign-request) - [Resend Box Sign request](#resend-box-sign-request) - [Get Box Sign request by ID](#get-box-sign-request-by-id) - [List Box Sign requests](#list-box-sign-requests) - [Create Box Sign request](#create-box-sign-request) ## Cancel Box Sign request Cancels a sign request. This operation is performed by calling function `cancelSignRequest`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-sign-requests-id-cancel/). ``` await client.signRequests.cancelSignRequest(createdSignRequest.id!); ``` ### Arguments signRequestId `string` - The ID of the signature request. Example: "33243242" optionalsInput `CancelSignRequestOptionalsInput` ### Returns This function returns a value of type `SignRequest`. Returns a Sign Request object. ## Resend Box Sign request Resends a signature request email to all outstanding signers. This operation is performed by calling function `resendSignRequest`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-sign-requests-id-resend/). *Currently we don't have an example for calling `resendSignRequest` in integration tests* ### Arguments signRequestId `string` - The ID of the signature request. Example: "33243242" optionalsInput `ResendSignRequestOptionalsInput` ### Returns This function returns a value of type `undefined`. Returns an empty response when the API call was successful. The email notifications will be sent asynchronously. ## Get Box Sign request by ID Gets a sign request by ID. This operation is performed by calling function `getSignRequestById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-sign-requests-id/). ``` await client.signRequests.getSignRequestById(createdSignRequest.id!); ``` ### Arguments signRequestId `string` - The ID of the signature request. Example: "33243242" optionalsInput `GetSignRequestByIdOptionalsInput` ### Returns This function returns a value of type `SignRequest`. Returns a signature request. ## List Box Sign requests Gets signature requests created by a user. If the `sign_files` and/or `parent_folder` are deleted, the signature request will not return in the list. This operation is performed by calling function `getSignRequests`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-sign-requests/). ``` await client.signRequests.getSignRequests(); ``` ### Arguments queryParams `GetSignRequestsQueryParams` - Query parameters of getSignRequests method headersInput `GetSignRequestsHeadersInput` - Headers of getSignRequests method cancellationToken `undefined | CancellationToken` - Token used for request cancellation. ### Returns This function returns a value of type `SignRequests`. Returns a collection of sign requests. ## Create Box Sign request Creates a signature request. This involves preparing a document for signing and sending the signature request to signers. This operation is performed by calling function `createSignRequest`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-sign-requests/). ``` await client.signRequests.createSignRequest({ signers: [ { email: signerEmail, suppressNotifications: true, declinedRedirectUrl: 'https://www.box.com', embedUrlExternalUserId: '123', isInPerson: false, loginRequired: false, password: 'password', role: 'signer' as SignRequestCreateSignerRoleField, } satisfies SignRequestCreateSigner, ], areRemindersEnabled: true, areTextSignaturesEnabled: true, daysValid: 30, declinedRedirectUrl: 'https://www.box.com', emailMessage: 'Please sign this document', emailSubject: 'Sign this document', externalId: '123', externalSystemName: 'BoxSignIntegration', isDocumentPreparationNeeded: false, name: 'Sign Request', parentFolder: new FolderMini({ id: destinationFolder.id }), redirectUrl: 'https://www.box.com', prefillTags: [ { dateValue: dateFromString('2035-01-01'), documentTagId: '0', } satisfies SignRequestPrefillTag, ], sourceFiles: [new FileBase({ id: fileToSign.id })], } satisfies SignRequestCreateRequest); ``` ### Arguments requestBody `SignRequestCreateRequest` - Request body of createSignRequest method optionalsInput `CreateSignRequestOptionalsInput` ### Returns This function returns a value of type `SignRequest`. Returns a Box Sign request object. --- ### SignRequestsManager **Type:** page | **Section:** Additional Resources SignRequestsManager Cancel Box Sign request Resend Box Sign request Get Box Sign request by ID List Box Sign requests Create Box Sign… # SignRequestsManager - [Cancel Box Sign request](#cancel-box-sign-request) - [Resend Box Sign request](#resend-box-sign-request) - [Get Box Sign request by ID](#get-box-sign-request-by-id) - [List Box Sign requests](#list-box-sign-requests) - [Create Box Sign request](#create-box-sign-request) ## Cancel Box Sign request Cancels a sign request. This operation is performed by calling function `cancel_sign_request`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-sign-requests-id-cancel/). ``` client.sign_requests.cancel_sign_request(created_sign_request.id) ``` ### Arguments sign_request_id `str` - The ID of the signature request. Example: "33243242" extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `SignRequest`. Returns a Sign Request object. ## Resend Box Sign request Resends a signature request email to all outstanding signers. This operation is performed by calling function `resend_sign_request`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-sign-requests-id-resend/). *Currently we don't have an example for calling `resend_sign_request` in integration tests* ### Arguments sign_request_id `str` - The ID of the signature request. Example: "33243242" extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `None`. Returns an empty response when the API call was successful. The email notifications will be sent asynchronously. ## Get Box Sign request by ID Gets a sign request by ID. This operation is performed by calling function `get_sign_request_by_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-sign-requests-id/). ``` client.sign_requests.get_sign_request_by_id(created_sign_request.id) ``` ### Arguments sign_request_id `str` - The ID of the signature request. Example: "33243242" extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `SignRequest`. Returns a signature request. ## List Box Sign requests Gets signature requests created by a user. If the `sign_files` and/or `parent_folder` are deleted, the signature request will not return in the list. This operation is performed by calling function `get_sign_requests`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-sign-requests/). ``` client.sign_requests.get_sign_requests() ``` ### Arguments marker `Optional[str]` - Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`. limit `Optional[int]` - The maximum number of items to return per page. senders `Optional[List[str]]` - A list of sender emails to filter the signature requests by sender. If provided, `shared_requests` must be set to `true`. shared_requests `Optional[bool]` - If set to `true`, only includes requests that user is not an owner, but user is a collaborator. Collaborator access is determined by the user access level of the sign files of the request. Default is `false`. Must be set to `true` if `senders` are provided. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `SignRequests`. Returns a collection of sign requests. ## Create Box Sign request Creates a signature request. This involves preparing a document for signing and sending the signature request to signers. This operation is performed by calling function `create_sign_request`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-sign-requests/). ``` client.sign_requests.create_sign_request( [ SignRequestCreateSigner( email=signer_email, suppress_notifications=True, declined_redirect_url="https://www.box.com", embed_url_external_user_id="123", is_in_person=False, login_required=False, password="password", role=SignRequestCreateSignerRoleField.SIGNER, ) ], source_files=[FileBase(id=file_to_sign.id)], parent_folder=FolderMini(id=destination_folder.id), is_document_preparation_needed=False, redirect_url="https://www.box.com", declined_redirect_url="https://www.box.com", are_text_signatures_enabled=True, email_subject="Sign this document", email_message="Please sign this document", are_reminders_enabled=True, name="Sign Request", prefill_tags=[ SignRequestPrefillTag( date_value=date_from_string("2035-01-01"), document_tag_id="0" ) ], days_valid=30, external_id="123", external_system_name="BoxSignIntegration", ) ``` ### Arguments source_files `Optional[List[FileBase]]` - List of files to create a signing document from. This is currently limited to ten files. Only the ID and type fields are required for each file. signature_color `Optional[CreateSignRequestSignatureColor]` - Force a specific color for the signature (blue, black, or red). signers `List[SignRequestCreateSigner]` - Array of signers for the signature request. 35 is the max number of signers permitted. **Note**: It may happen that some signers belong to conflicting [segments](r://shield-information-barrier-segment-member) (user groups). This means that due to the security policies, users are assigned to segments to prevent exchanges or communication that could lead to ethical conflicts. In such a case, an attempt to send the sign request will result in an error. Read more about [segments and ethical walls](https://support.box.com/hc/en-us/articles/9920431507603-Understanding-Information-Barriers#h_01GFVJEHQA06N7XEZ4GCZ9GFAQ). parent_folder `Optional[FolderMini]` is_document_preparation_needed `Optional[bool]` - Indicates if the sender should receive a `prepare_url` in the response to complete document preparation using the UI. redirect_url `Optional[str]` - When specified, the signature request will be redirected to this url when a document is signed. declined_redirect_url `Optional[str]` - The uri that a signer will be redirected to after declining to sign a document. are_text_signatures_enabled `Optional[bool]` - Disables the usage of signatures generated by typing (text). email_subject `Optional[str]` - Subject of sign request email. This is cleaned by sign request. If this field is not passed, a default subject will be used. email_message `Optional[str]` - Message to include in sign request email. The field is cleaned through sanitization of specific characters. However, some html tags are allowed. Links included in the message are also converted to hyperlinks in the email. The message may contain the following html tags including `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. If this field is not passed, a default message will be used. are_reminders_enabled `Optional[bool]` - Reminds signers to sign a document on day 3, 8, 13 and 18. Reminders are only sent to outstanding signers. name `Optional[str]` - Name of the signature request. prefill_tags `Optional[List[SignRequestPrefillTag]]` - When a document contains sign-related tags in the content, you can prefill them using this `prefill_tags` by referencing the 'id' of the tag as the `external_id` field of the prefill tag. days_valid `Optional[int]` - Set the number of days after which the created signature request will automatically expire if not completed. By default, we do not apply any expiration date on signature requests, and the signature request does not expire. external_id `Optional[str]` - This can be used to reference an ID in an external system that the sign request is related to. template_id `Optional[str]` - When a signature request is created from a template this field will indicate the id of that template. external_system_name `Optional[str]` - Used as an optional system name to appear in the signature log next to the signers who have been assigned the `embed_url_external_id`. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `SignRequest`. Returns a Box Sign request object. --- ### SignTemplatesManager **Type:** page | **Section:** Additional Resources SignTemplatesManager List Box Sign templates Get Box Sign template by ID List Box Sign templates Gets Box Sign templates created by a user… # SignTemplatesManager - [List Box Sign templates](#list-box-sign-templates) - [Get Box Sign template by ID](#get-box-sign-template-by-id) ## List Box Sign templates Gets Box Sign templates created by a user. This operation is performed by calling function `getSignTemplates`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-sign-templates/). ``` await client.signTemplates.getSignTemplates({ limit: 2, } satisfies GetSignTemplatesQueryParams); ``` ### Arguments queryParams `GetSignTemplatesQueryParams` - Query parameters of getSignTemplates method headersInput `GetSignTemplatesHeadersInput` - Headers of getSignTemplates method cancellationToken `undefined | CancellationToken` - Token used for request cancellation. ### Returns This function returns a value of type `SignTemplates`. Returns a collection of templates. ## Get Box Sign template by ID Fetches details of a specific Box Sign template. This operation is performed by calling function `getSignTemplateById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-sign-templates-id/). ``` await client.signTemplates.getSignTemplateById(signTemplates.entries![0].id!); ``` ### Arguments templateId `string` - The ID of a Box Sign template. Example: "123075213-7d117509-8f05-42e4-a5ef-5190a319d41d" optionalsInput `GetSignTemplateByIdOptionalsInput` ### Returns This function returns a value of type `SignTemplate`. Returns details of a template. --- ### SignTemplatesManager **Type:** page | **Section:** Additional Resources SignTemplatesManager List Box Sign templates Get Box Sign template by ID List Box Sign templates Gets Box Sign templates created by a user… # SignTemplatesManager - [List Box Sign templates](#list-box-sign-templates) - [Get Box Sign template by ID](#get-box-sign-template-by-id) ## List Box Sign templates Gets Box Sign templates created by a user. This operation is performed by calling function `get_sign_templates`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-sign-templates/). ``` client.sign_templates.get_sign_templates(limit=2) ``` ### Arguments marker `Optional[str]` - Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`. limit `Optional[int]` - The maximum number of items to return per page. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `SignTemplates`. Returns a collection of templates. ## Get Box Sign template by ID Fetches details of a specific Box Sign template. This operation is performed by calling function `get_sign_template_by_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-sign-templates-id/). ``` client.sign_templates.get_sign_template_by_id(sign_templates.entries[0].id) ``` ### Arguments template_id `str` - The ID of a Box Sign template. Example: "123075213-7d117509-8f05-42e4-a5ef-5190a319d41d" extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `SignTemplate`. Returns details of a template. --- ### SkillsManager **Type:** page | **Section:** Additional Resources SkillsManager List Box Skill cards on file Create Box Skill cards on file Update Box Skill cards on file Remove Box Skill cards from file… # SkillsManager - [List Box Skill cards on file](#list-box-skill-cards-on-file) - [Create Box Skill cards on file](#create-box-skill-cards-on-file) - [Update Box Skill cards on file](#update-box-skill-cards-on-file) - [Remove Box Skill cards from file](#remove-box-skill-cards-from-file) - [Update all Box Skill cards on file](#update-all-box-skill-cards-on-file) ## List Box Skill cards on file List the Box Skills metadata cards that are attached to a file. This operation is performed by calling function `getBoxSkillCardsOnFile`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-files-id-metadata-global-boxSkillsCards/). ``` await client.skills.getBoxSkillCardsOnFile(file.id); ``` ### Arguments fileId `string` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" optionalsInput `GetBoxSkillCardsOnFileOptionalsInput` ### Returns This function returns a value of type `SkillCardsMetadata`. Returns all the metadata associated with a file. This API does not support pagination and will therefore always return all of the metadata associated to the file. ## Create Box Skill cards on file Applies one or more Box Skills metadata cards to a file. This operation is performed by calling function `createBoxSkillCardsOnFile`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-files-id-metadata-global-boxSkillsCards/). ``` await client.skills.createBoxSkillCardsOnFile(file.id, { cards: cardsToCreate, } satisfies CreateBoxSkillCardsOnFileRequestBody); ``` ### Arguments fileId `string` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" requestBody `CreateBoxSkillCardsOnFileRequestBody` - Request body of createBoxSkillCardsOnFile method optionalsInput `CreateBoxSkillCardsOnFileOptionalsInput` ### Returns This function returns a value of type `SkillCardsMetadata`. Returns the instance of the template that was applied to the file, including the data that was applied to the template. ## Update Box Skill cards on file Updates one or more Box Skills metadata cards to a file. This operation is performed by calling function `updateBoxSkillCardsOnFile`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-files-id-metadata-global-boxSkillsCards/). ``` await client.skills.updateBoxSkillCardsOnFile(file.id, [ { op: 'replace' as UpdateBoxSkillCardsOnFileRequestBodyOpField, path: '/cards/0', value: cardToUpdate, } satisfies UpdateBoxSkillCardsOnFileRequestBody, ]); ``` ### Arguments fileId `string` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" requestBody `readonly UpdateBoxSkillCardsOnFileRequestBody[]` - Request body of updateBoxSkillCardsOnFile method optionalsInput `UpdateBoxSkillCardsOnFileOptionalsInput` ### Returns This function returns a value of type `SkillCardsMetadata`. Returns the updated metadata template, with the custom template data included. ## Remove Box Skill cards from file Removes any Box Skills cards metadata from a file. This operation is performed by calling function `deleteBoxSkillCardsFromFile`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-files-id-metadata-global-boxSkillsCards/). ``` await client.skills.deleteBoxSkillCardsFromFile(file.id); ``` ### Arguments fileId `string` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" optionalsInput `DeleteBoxSkillCardsFromFileOptionalsInput` ### Returns This function returns a value of type `undefined`. Returns an empty response when the cards are successfully deleted. ## Update all Box Skill cards on file An alternative method that can be used to overwrite and update all Box Skill metadata cards on a file. This operation is performed by calling function `updateAllSkillCardsOnFile`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-skill-invocations-id/). *Currently we don't have an example for calling `updateAllSkillCardsOnFile` in integration tests* ### Arguments skillId `string` - The ID of the skill to apply this metadata for. Example: "33243242" requestBody `UpdateAllSkillCardsOnFileRequestBody` - Request body of updateAllSkillCardsOnFile method optionalsInput `UpdateAllSkillCardsOnFileOptionalsInput` ### Returns This function returns a value of type `undefined`. Returns an empty response when the card has been successfully updated. --- ### SkillsManager **Type:** page | **Section:** Additional Resources SkillsManager List Box Skill cards on file Create Box Skill cards on file Update Box Skill cards on file Remove Box Skill cards from file… # SkillsManager - [List Box Skill cards on file](#list-box-skill-cards-on-file) - [Create Box Skill cards on file](#create-box-skill-cards-on-file) - [Update Box Skill cards on file](#update-box-skill-cards-on-file) - [Remove Box Skill cards from file](#remove-box-skill-cards-from-file) - [Update all Box Skill cards on file](#update-all-box-skill-cards-on-file) ## List Box Skill cards on file List the Box Skills metadata cards that are attached to a file. This operation is performed by calling function `get_box_skill_cards_on_file`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-files-id-metadata-global-boxSkillsCards/). ``` client.skills.get_box_skill_cards_on_file(file.id) ``` ### Arguments file_id `str` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `SkillCardsMetadata`. Returns all the metadata associated with a file. This API does not support pagination and will therefore always return all of the metadata associated to the file. ## Create Box Skill cards on file Applies one or more Box Skills metadata cards to a file. This operation is performed by calling function `create_box_skill_cards_on_file`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-files-id-metadata-global-boxSkillsCards/). ``` client.skills.create_box_skill_cards_on_file(file.id, cards_to_create) ``` ### Arguments file_id `str` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" cards `List[Union[KeywordSkillCard, TimelineSkillCard, TranscriptSkillCard, StatusSkillCard]]` - A list of Box Skill cards to apply to this file. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `SkillCardsMetadata`. Returns the instance of the template that was applied to the file, including the data that was applied to the template. ## Update Box Skill cards on file Updates one or more Box Skills metadata cards to a file. This operation is performed by calling function `update_box_skill_cards_on_file`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-files-id-metadata-global-boxSkillsCards/). ``` client.skills.update_box_skill_cards_on_file( file.id, [ UpdateBoxSkillCardsOnFileRequestBody( op=UpdateBoxSkillCardsOnFileRequestBodyOpField.REPLACE, path="/cards/0", value=card_to_update, ) ], ) ``` ### Arguments file_id `str` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" request_body `List[UpdateBoxSkillCardsOnFileRequestBody]` - Request body of updateBoxSkillCardsOnFile method extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `SkillCardsMetadata`. Returns the updated metadata template, with the custom template data included. ## Remove Box Skill cards from file Removes any Box Skills cards metadata from a file. This operation is performed by calling function `delete_box_skill_cards_from_file`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-files-id-metadata-global-boxSkillsCards/). ``` client.skills.delete_box_skill_cards_from_file(file.id) ``` ### Arguments file_id `str` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `None`. Returns an empty response when the cards are successfully deleted. ## Update all Box Skill cards on file An alternative method that can be used to overwrite and update all Box Skill metadata cards on a file. This operation is performed by calling function `update_all_skill_cards_on_file`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-skill-invocations-id/). *Currently we don't have an example for calling `update_all_skill_cards_on_file` in integration tests* ### Arguments skill_id `str` - The ID of the skill to apply this metadata for. Example: "33243242" status `UpdateAllSkillCardsOnFileStatus` - Defines the status of this invocation. Set this to `success` when setting Skill cards. metadata `UpdateAllSkillCardsOnFileMetadata` - The metadata to set for this skill. This is a list of Box Skills cards. These cards will overwrite any existing Box skill cards on the file. file `UpdateAllSkillCardsOnFileFile` - The file to assign the cards to. file_version `Optional[UpdateAllSkillCardsOnFileFileVersion]` - The optional file version to assign the cards to. usage `Optional[UpdateAllSkillCardsOnFileUsage]` - A descriptor that defines what items are affected by this call. Set this to the default values when setting a card to a `success` state, and leave it out in most other situations. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `None`. Returns an empty response when the card has been successfully updated. --- ### Storage Policies **Type:** page | **Section:** Additional Resources Storage Policies Storage policies allow enterprise administrators to choose where their content is physically stored; different policies can… # Storage Policies Storage policies allow enterprise administrators to choose where their content is physically stored; different policies can be purchased and assigned either as the default policy for the entire enterprise or on a per-user basis. ## Get Available Storage Policies for an Enterprise To get a list of the storage policies that are available for the current user's enterprise, call the [`storagePolicies.getAll(options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/StoragePolicies.html#getAll) method. ``` client.storagePolicies.getAll() .then(policies => { /* policies -> { next_marker: null, limit: 1000, entries: [ { type: 'storage_policy', id: '42', name: 'Montreal / Dublin' }, { type: 'storage_policy', id: '126', name: 'Frankfurt / Dublin' }, { type: 'storage_policy', id: '162', name: 'US' } ] } */ }); ``` ## Get Information About a Specific Storage Policy Information about a specific storage policy (by its ID) can be retrieved by calling the [`storagePolicies.get(storagePolicyID, options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/StoragePolicies.html#get) method with the ID of the assignment object. ``` client.storagePolicies.get('6') .then(storagePolicy => { /* storagePolicy -> { type: 'storage_policy', id: '6', name: 'Tokyo & Singapore' } */ }); ``` ## Assign a Storage Policy to a User To assign a storage policy to a user, call the [`storagePolicies.assign(storagePolicyID, userID, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/StoragePolicies.html#assign) method with the ID of the storage policy to assign and the ID of the user to which it should be assigned. **Note:** This method will check if an assignment already exists for the user and take appropriate action. It should work regardless of the current status of the user. ``` var storagePolicyID = '7'; var userID = '22222'; client.storagePolicies.assign(storagePolicyID, userID) .then(assignment => { /* assignment -> { type: 'storage_policy_assignment', id: 'dXNlcl8yMjIyMg==', storage_policy: 'storage_policy', id: '7' }, assigned_to: { type: 'user', id: '22222' } } */ }); ``` ## Get Information About a Specific Storage Policy Assignment To get information about a specific storage policy assignment by ID, call the [`storagePolicies.getAssignment(asisgnmentID, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/StoragePolicies.html#getAssignment) method with the ID of the storage policy assignment. ``` client.storagePolicies.getAssignment('dXNlcl8yMjIyMg==') .then(assignment => { /* assignment -> { type: 'storage_policy_assignment', id: 'dXNlcl8yMjIyMg==', storage_policy: 'storage_policy', id: '7' }, assigned_to: { type: 'user', id: '22222' } } */ }); ``` ## Get the Storage Policy Assigned to a User To determine which storage policy is assigned to a user, call [`storagePolicies.getAssignmentForTarget(userID, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/StoragePolicies.html#getAssignmentForTarget) with the ID of the user. ``` client.storagePolicies.getAssignmentForTarget('22222') .then(assignment => { /* assignment -> { type: 'storage_policy_assignment', id: 'dXNlcl8yMjIyMg==', storage_policy: 'storage_policy', id: '7' }, assigned_to: { type: 'user', id: '22222' } } */ }); ``` ## Create a Storage Policy Assignment To create a new storage policy assignment, call the [`storagePolicies.createAssignment(policyID, userID, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/StoragePolicies.html#createAssignment) method with the ID of the storage policy to assign and the ID of the user to assign it to. **Note:** This method only works if the user does not already have an assignment. If the current state of the user is not known, use the [`storagePolicies.assign()`](#assign-a-storage-policy-to-a-user) method instead. ``` client.storagePolicies.createAssignment('7', '22222') .then(assignment => { /* assignment -> { type: 'storage_policy_assignment', id: 'dXNlcl8yMjIyMg==', storage_policy: 'storage_policy', id: '7' }, assigned_to: { type: 'user', id: '22222' } } */ }); ``` ## Update a Storage Policy Assignment To update a storage policy assignment, for example to update which storage policy is asisgned to a user, call the [`storagePolicies.updateAssignment(assignmentID, updates, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/StoragePolicies.html#updateAssignment) method with the ID of the assignment to update and an object containing key/value mapping of fields to update on the assignment. ``` // Reassign user 22222 to storage policy 10 var assignmentID = 'dXNlcl8yMjIyMg=='; var updates = { storage_policy: { type: 'storage_policy', id: '10' } }; client.storagePolicies.updateAssignment(assignmentID, updates) .then(updatedAssignment => { /* updatedAssignment -> { type: 'storage_policy_assignment', id: 'dXNlcl8yMjIyMg==', storage_policy: 'storage_policy', id: '10' }, assigned_to: { type: 'user', id: '22222' } } */ }); ``` ## Remove a Storage Policy Assignment To remove a storage policy assignment and return the user it was assigned to to the default storage policy for the enterprise, call [`storagePolicies.removeAssignment(assignmentID, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/StoragePolicies.html#removeAssignment) with the ID of the assignment to remove. ``` client.storagePolicies.removeAssignment('dXNlcl8yMjIyMg==') .then(() => { // deletion succeeded — no value returned }); ``` --- ### Storage Policies **Type:** page | **Section:** Additional Resources Storage Policies Allows the enterprise admin to manage the Storage Policies for users in their enterprise. Used for an enterprise to decide… # Storage Policies Allows the enterprise admin to manage the Storage Policies for users in their enterprise. Used for an enterprise to decide storage location for users based on where they work/reside. - [Get Storage Policy](#get-storage-policy) - [List Available Storage Policies](#list-available-storage-policies) - [Assign a Storage Policy to a User](#assign-a-storage-policy-to-a-user) - [Get Assignment Information about a Storage Policy Assignment](#get-assignment-information-about-a-storage-policy-assignment) - [Get Assignment for User](#get-assignment-for-user) - [Delete Assignment](#delete-assignment) ## Get Storage Policy To get a storage policy object, first call [`client.storage_policy(policy_id)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.client.html#boxsdk.client.client.Client.storage_policy) to construct the appropriate [`Storage Policy`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.storage_policy.StoragePolicy) object, and then calling [`storage_policy.get(*, fields=None, headers=None, **kwargs)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.base_object.BaseObject.get) will return the [`StoragePolicy`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.storage_policy.StoragePolicy) object populated with data from the API. ``` storage_policy = client.storage_policy(policy_id='12345').get() print(f'Storage Policy ID is {storage_policy.id} and name is {storage_policy.name}') ``` ## List Available Storage Policies To retrieve all storage policies for an enterprise, call [`client.get_storage_policies(limit=None, fields=None)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.client.html#boxsdk.client.client.Client.get_storage_policies). This method returns a `BoxObjectCollection` that allows you to iterate over the [`StoragePolicy`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.storage_policy.StoragePolicy) objects in the collection. ``` storage_policies = client.get_storage_policies(limit=100) for storage_policy in storage_policies: print(f'The storage policy id is {storage_policy.id} and name is {storage_policy.name}') ``` ## Assign a Storage Policy to a User To assign a storage policy to a user, call [`storage_policy.assign(user)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.storage_policy.StoragePolicy.assign) will create a [`StoragePolicyAssignment`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.storage_policy_assignment.StoragePolicyAssignment) object with data populated from the API. ``` user = client.user(user_id='12345') assignment = client.storage_policy(policy_id='56781').assign(user) print(f'Assignment ID is {assignment.id} and the assignee id is {assignment.assigned_to.id}') ``` If you know the user does not have a storage policy assigned you can directly create a storage policy assignment by calling [`storage_policy.create_assignment(user)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.storage_policy.StoragePolicy.create_assignment) will create a [StoragePolicyAssignment](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.storage_policy_assignment.StoragePolicyAssignment) object with data populated from the API. ``` user = client.user('56781') assignment = client.storage_policy(policy_id='12345').create_assignment(user) print(f'Storage Policy Assignment ID is {assignment.id} and the assignee ID is {assignment.assigned_to.id}') ``` If the user already has an assignment, you can call [storage_policy_assignment.update_info(data=updated_storage_policy)][update_info] with a `dict` of properties to update on the storage policy assignment. This method returns a newly update [`StoragePolicyAssignment`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.client.html#boxsdk.client.client.Client.storage_policy_assignment) object with data populated from the API, leaving the original object unmodified. ``` updated_storage_policy = {'storage_policy': {'type': 'storage_policy', 'id': '12345'}} updated_assignment = client.storage_policy_assignment(assignment_id='ZW50ZXJwcmldfgeV82MDMwMDQ=').update_info(data=updated_storage_policy) print(f'Update storage policy ID is {updated_assignment.storage_policy.id}') ``` ## Get Assignment Information about a Storage Policy Assignment To get a storage policy assignment object, first call [`client.storage_policy_assignment(assignment_id)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.client.html#boxsdk.client.client.Client.storage_policy_assignment) to construct the appropriate [`Storage Policy Assignment`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.storage_policy_assignment.StoragePolicyAssignment) object, and then calling [`storage_policy_assignment.get(*, fields=None, headers=None, **kwargs)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.base_object.BaseObject.get) will return the [`StoragePolicyAssignment`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.storage_policy_assignment.StoragePolicyAssignment) object populated with data from the API. ``` assignment = client.storage_policy_assignment(assignment_id='12345').get() print(f'Assignment ID is {assignment.id} and the storage policy ID is {assignment.storage_policy.id}') ``` ## Get Assignment for User To get a storage policy assignment object for a user, calling [`user.get_storage_policy_assignment()`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.user.User.get_storage_policy_assignment) will return the [`StoragePolicyAssignment`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.storage_policy_assignment.StoragePolicyAssignment) object populated with data from the API. ``` assignment = client.user(user_id='12345').get_storage_policy_assignment() print(f'Assignment ID is {assignment.id} and the storage policy ID is {assignment.storage_policy.id}') ``` ## Delete Assignment To delete a storage policy assignment, call [`storage_policy_assignment.delete()`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.base_object.BaseObject.delete). This method returns `True` to indicate that the deletion was successful. ``` client.storage_policy_assignment(assignment_id='12345').delete() print('The storage policy assignment was successfully delete!') ``` --- ### Storage Policies **Type:** page | **Section:** Additional Resources Storage Policies Storage policies allow enterprise administrators to choose where their content is physically stored; different policies can… # Storage Policies Storage policies allow enterprise administrators to choose where their content is physically stored; different policies can be purchased and assigned either as the default policy for the entire enterprise or on a per-user basis. ## Get Available Storage Policies for an Enterprise To get a list of the storage policies that are available for the current user's enterprise, call the `StoragePoliciesManager.GetListStoragePoliciesAsync(string fields = null, string marker = null, int limit = 100, bool autoPaginate = false)` method. ``` BoxCollectionMarkerBased<BoxStoragePolicy> policies = await client.StoragePoliciesManager .GetListStoragePoliciesAsync(); ``` ## Get Information About a Specific Storage Policy Information about a specific storage policy (by its ID) can be retrieved by calling the `StoragePoliciesManager.GetStoragePolicyAsync(String policyId)` method with the ID of the storage policy to retrieve. ``` BoxStoragePolicy policy = await client.StoragePoliciesManager.GetStoragePolicyAsync(policyId: "6"); ``` ## Assign a Storage Policy to a User To assign a storage policy to a user, call the `StoragePoliciesManager.AssignAsync(string userId, string storagePolicyId)` method with the ID of the storage policy to assign and the ID of the user to which it should be assigned. **Note:** This method will check if an assignment already exists for the user and take appropriate action. It should work regardless of the current status of the user. ``` BoxStoragePolicyAssignment assignment = await client.StoragePoliciesManager .AssignAsync(userId: "22222", storagePolicyId: "6"); ``` ## Get Information About a Specific Storage Policy Assignment To get information about a specific storage policy assignment by ID, call the `StoragePoliciesManager.GetAssignmentAsync(string assignmentId)` method with the ID of the storage policy assignment. ``` BoxStoragePolicyAssignment assignment = await client.StoragePoliciesManager .GetAssignmentAsync(assignmentId: "dXNlcl8yMjIyMg=="); ``` ## Get the Storage Policy Assigned to a User To determine which storage policy is assigned to a user, call `StoragePoliciesManager.GetAssignmentForTargetAsync(string entityId, string entityType = "user")` with the ID of the user. ``` BoxStoragePolicyAssignment assignment = client.StoragePoliciesManager .GetAssignmentForTargetAsync("22222"); ``` ## Create a Storage Policy Assignment To create a new storage policy assignment, call the `StoragePoliciesManager.CreateAssignmentAsync(string userId, string policyId)` method with the ID of the storage policy to assign and the ID of the user to assign it to. **Note:** This method only works if the user does not already have an assignment. If the current state of the user is not known, use the [`AssignAsync()`](#assign-a-storage-policy-to-a-user) method instead. ``` BoxStoragePolicyAssignment assignment = client.StoragePoliciesManager .CreateAssignmentAsync(userId: "22222", policyId: "6"); ``` ## Update a Storage Policy Assignment To update a storage policy assignment, for example to update which storage policy is asisgned to a user, call the `StoragePoliciesManager.UpdateStoragePolicyAssignment(string assignmentId, String policyId)` method with the ID of the assignment to update and the new policy ID to assign. ``` // Reassign user 1234 to storage policy 7 BoxStoragePolicyAssignment assignment = await client.StoragePoliciesManager .UpdateStoragePolicyAssignment(assignmentId: "dXNlcl8yMjIyMg==", policyId: "7"); ``` ## Remove a Storage Policy Assignment To remove a storage policy assignment and return the user it was assigned to to the default storage policy for the enterprise, call `StoragePoliciesManager.DeleteAssignmentAsync(string assignmentId)` with the ID of the assignment to remove. ``` await client.StoragePoliciesManager.DeleteAssignmentAsync(assignmentId: "dXNlcl8yMjIyMg=="); ``` --- ### Storage Policies **Type:** page | **Section:** Additional Resources Storage Policies Get Storage Policy Info Get Storage Policies Get Storage Policy Assignment Info Get Storage Policy Assignments Create… # Storage Policies - [Get Storage Policy Info](#get-storage-policy-info) - [Get Storage Policies](#get-storage-policies) - [Get Storage Policy Assignment Info](#get-storage-policy-assignment-info) - [Get Storage Policy Assignments](#get-storage-policy-assignments) - [Create Storage Policy Assignment](#create-storage-policy-assignment) - [Assign Storage Policy](#assign-storage-policy) - [Update Storage Policy Assignment](#update-storage-policy-assignment) - [Delete Storage Policy Assignment](#delete-storage-policy-assignment) ## Get Storage Policy Info To retrieve information about a storage policy, call [`client.storagePolicies.get(storagePolicyId: String, fields: [String]?, completion: @escaping Callback<StoragePolicy>)`](https://opensource.box.com/box-ios-sdk/Classes/StoragePoliciesModule.html#/s:6BoxSDK21StoragePoliciesModuleC3get15storagePolicyId6fields10completionySS_SaySSGSgys6ResultOyAA0cH0CAA0A8SDKErrorCGctF) with the ID of the storage policy. You can control which fields are returned in the resulting `Storage Policy` object by passing the `fields` parameter. ``` client.storagePolicies.get(storagePolicyId: "22222") { (result: Result<StoragePolicy, BoxSDKError>) in guard case let .success(policy) = result else { print("Error getting storage policy") return } print("Policy ID is \(policy.id)") } ``` ## Get Storage Policies To retrieve the storage policies in an enterprise, call [`client.storagePolicies.listForEnterprise(marker: String?, limit: Int?, fields: [String]?)`](https://opensource.box.com/box-ios-sdk/Classes/StoragePoliciesModule.html#/s:6BoxSDK21StoragePoliciesModuleC17listForEnterprise6marker5limit6fields10completionySSSg_SiSgSaySSGSgys6ResultOyAA14PagingIteratorCyAA0C6PolicyCGAA0A8SDKErrorCGctF). This method will return an iterator, which is used to get the policies. ``` let iterator = client.storagePolicies.listForEnterprise() iterator.next { results in switch results { case let .success(page): for policy in page.entries { print("Storage policy \(policy.id)") } case let .failure(error): print(error) } } ``` ## Get Storage Policy Assignment Info To get storage policy assignment, call [`client.storagePolicies.getAssignment(storagePolicyAssignmentId: String, fields: [String]?, completion: @escaping Callback<StoragePolicyAssignment>`](https://opensource.box.com/box-ios-sdk/Classes/StoragePoliciesModule.html#/s:6BoxSDK21StoragePoliciesModuleC13getAssignment013storagePolicyG2Id6fields10completionySS_SaySSGSgys6ResultOyAA0ciG0CAA0A8SDKErrorCGctF) with the id of a storage policy assignment. ``` client.storagePolicy.getAssignment(storagePolicyAssignmentId: "1234") { (result: Result<StoragePolicyAssignment, BoxSDKError>) in guard case let .success(assignment) = result else { print("Error getting storage policy assignment") return } print("Storage policy assignment ID \(assignment.id)") } ``` ## Get Storage Policy Assignments To get storage policy assignments for a user or enterprise, call [`client.storagePolicies.listAssignments(resolvedForType: String, resolvedForId: String, fields: [String]?, completion: @escaping Callback<StoragePolicyAssignment>`](https://opensource.box.com/box-ios-sdk/Classes/StoragePoliciesModule.html#/s:6BoxSDK21StoragePoliciesModuleC15listAssignments15resolvedForType0hI2Id6fields10completionySS_SSSaySSGSgys6ResultOyAA0C16PolicyAssignmentCAA0A8SDKErrorCGctF). This always returns a single storage policy assignment. ``` client.storagePolicy.listAssignments(resolvedForType: "user", resolvedForId: "1234") { (result: Result<StoragePolicyAssignment, BoxSDKError>) in guard case let .success(assignment) = result else { print("Error getting storage policy assignment") return } print("Storage policy assignment for user \(assignment.assignedTo?.id) is \(assignment.id)") } ``` ## Assign Storage Policy To assign a storage policy, call [`client.storagePolicies.assign(storagePolicyId: String, assignedToType: String, assignedToId, fields: [String]?, completion: @escaping Callback<StoragePolicyAssignment>`](https://opensource.box.com/box-ios-sdk/Classes/StoragePoliciesModule.html#/s:6BoxSDK21StoragePoliciesModuleC6assign15storagePolicyId14assignedToType0jkI06fields10completionySS_S2SSaySSGSgys6ResultOyAA0cH10AssignmentCAA0A8SDKErrorCGctF). ``` client.storagePolicy.assign(storagePolicyId: "1234", assignedToType: "user", assignedToId: "123") { (result: Result<StoragePolicyAssignment, BoxSDKError>) in guard case let .success(assignment) = result else { print("Error assigning a storage policy") return } print("Created storage policy assignment ID is \(assignment.id). The ID of the user it is assigned to \(assignment.assignedTo?.id)") } ``` ## Force Assign Storage Policy To assign a storage policy, call [`client.storagePolicies.forceAssign(storagePolicyId: String, assignedToType: String, assignedToId, fields: [String]?, completion: @escaping Callback<StoragePolicyAssignment>`](https://opensource.box.com/box-ios-sdk/Classes/StoragePoliciesModule.html#/s:6BoxSDK21StoragePoliciesModuleC11forceAssign15storagePolicyId14assignedToType0klJ06fields10completionySS_S2SSaySSGSgys6ResultOyAA0cI10AssignmentCAA0A8SDKErrorCGctF). The difference between this call and the createPolicyAssignment() above is that this method will guarantee an update to the assignee's policy. If an assignee already has a policy assigned to it, the createPolicyAssignment() will return a 409 Conflict error. assignPolicy() will instead make an additional updatePolicyAssignment() call to replace the existing policy with the new policy for a policy assignment. ``` client.storagePolicy.forceAssign(storagePolicyId: "1234", assignedToType: "user", assignedToId: "123") { (result: Result<StoragePolicyAssignment, BoxSDKError>) in guard case let .success(assignment) = result else { print("Error assigning a storage policy") return } print("Created storage policy assignment ID is \(assignment.id). The ID of the user it is assigned to \(assignment.assignedTo?.id)") } ``` ## Update Storage Policy Assignment To update storage policy assignment, call [`client.storagePolicies.updateAssignment(storagePolicyId: String, assignedToType: String, assignedToId, fields: [String]?, completion: @escaping Callback<StoragePolicyAssignment>`](https://opensource.box.com/box-ios-sdk/Classes/StoragePoliciesModule.html#/s:6BoxSDK21StoragePoliciesModuleC16updateAssignment013storagePolicyG2Id0hiJ06fields10completionySS_SSSgSaySSGSgys6ResultOyAA0ciG0CAA0A8SDKErrorCGctF). ``` client.storagePolicy.updateAssignment(storagePolicyAssignmentId: "1234", storagePolicyId: "123") { (result: Result<StoragePolicyAssignment, BoxSDKError>) in guard case let .success(assignment) = result else { print("Error updating a storage policy assignment") return } print("Updated storage policy assignment \(assignment.id)") } ``` ## Delete Storage Policy Assignment To delete a storage policy assignment, call [`client.folders.deleteAssignment(storagePolicyAssignmentId: String, completion: @escaping Callback<Void>`](https://opensource.box.com/box-ios-sdk/Classes/StoragePoliciesModule.html#/s:6BoxSDK21StoragePoliciesModuleC16deleteAssignment013storagePolicyG2Id10completionySS_ys6ResultOyytAA0A8SDKErrorCGctF) with the ID of the storage policy to delete. ``` client.storagePolicies.deleteAssignment(storagePolicyAssignmentId: "22222") { result: Result<Void, BoxSDKError>} in guard case .success = result else { print("Error deleting storage policy assignment") return } print("Storage policy assignment is successfully deleted.") } ``` --- ### Storage Policies **Type:** page | **Section:** Additional Resources Storage Policies Get Storage Policy Info Get Storage Policies Get Storage Policy Assignment Info Get Storage Policy Assignments Create… # Storage Policies - [Get Storage Policy Info](#get-storage-policy-info) - [Get Storage Policies](#get-storage-policies) - [Get Storage Policy Assignment Info](#get-storage-policy-assignment-info) - [Get Storage Policy Assignments](#get-storage-policy-assignments) - [Create Storage Policy Assignment](#create-storage-policy-assignment) - [Assign Storage Policy](#assign-storage-policy) - [Update Storage Policy Assignment](#update-storage-policy-assignment) - [Delete Storage Policy Assignment](#delete-storage-policy-assignment) ## Get Storage Policy Info To retrieve information about a storage policy, call [`client.storagePolicies.get(storagePolicyId: String, fields: [String]?, completion: @escaping Callback<StoragePolicy>)`](https://opensource.box.com/box-ios-sdk/Classes/StoragePoliciesModule.html#/s:6BoxSDK21StoragePoliciesModuleC3get15storagePolicyId6fields10completionySS_SaySSGSgys6ResultOyAA0cH0CAA0A8SDKErrorCGctF) with the ID of the storage policy. You can control which fields are returned in the resulting `Storage Policy` object by passing the `fields` parameter. ``` client.storagePolicies.get(storagePolicyId: "22222") { (result: Result<StoragePolicy, BoxSDKError>) in guard case let .success(policy) = result else { print("Error getting storage policy") return } print("Policy ID is \(policy.id)") } ``` ## Get Storage Policies To retrieve the storage policies in an enterprise, call [`client.storagePolicies.listForEnterprise(marker: String?, limit: Int?, fields: [String]?)`](https://opensource.box.com/box-ios-sdk/Classes/StoragePoliciesModule.html#/s:6BoxSDK21StoragePoliciesModuleC17listForEnterprise6marker5limit6fields10completionySSSg_SiSgSaySSGSgys6ResultOyAA14PagingIteratorCyAA0C6PolicyCGAA0A8SDKErrorCGctF). This method will return an iterator, which is used to get the policies. ``` let iterator = client.storagePolicies.listForEnterprise() iterator.next { results in switch results { case let .success(page): for policy in page.entries { print("Storage policy \(policy.id)") } case let .failure(error): print(error) } } ``` ## Get Storage Policy Assignment Info To get storage policy assignment, call [`client.storagePolicies.getAssignment(storagePolicyAssignmentId: String, fields: [String]?, completion: @escaping Callback<StoragePolicyAssignment>`](https://opensource.box.com/box-ios-sdk/Classes/StoragePoliciesModule.html#/s:6BoxSDK21StoragePoliciesModuleC13getAssignment013storagePolicyG2Id6fields10completionySS_SaySSGSgys6ResultOyAA0ciG0CAA0A8SDKErrorCGctF) with the id of a storage policy assignment. ``` client.storagePolicy.getAssignment(storagePolicyAssignmentId: "1234") { (result: Result<StoragePolicyAssignment, BoxSDKError>) in guard case let .success(assignment) = result else { print("Error getting storage policy assignment") return } print("Storage policy assignment ID \(assignment.id)") } ``` ## Get Storage Policy Assignments To get storage policy assignments for a user or enterprise, call [`client.storagePolicies.listAssignments(resolvedForType: String, resolvedForId: String, fields: [String]?, completion: @escaping Callback<StoragePolicyAssignment>`](https://opensource.box.com/box-ios-sdk/Classes/StoragePoliciesModule.html#/s:6BoxSDK21StoragePoliciesModuleC15listAssignments15resolvedForType0hI2Id6fields10completionySS_SSSaySSGSgys6ResultOyAA0C16PolicyAssignmentCAA0A8SDKErrorCGctF). This always returns a single storage policy assignment. ``` client.storagePolicy.listAssignments(resolvedForType: "user", resolvedForId: "1234") { (result: Result<StoragePolicyAssignment, BoxSDKError>) in guard case let .success(assignment) = result else { print("Error getting storage policy assignment") return } print("Storage policy assignment for user \(assignment.assignedTo?.id) is \(assignment.id)") } ``` ## Assign Storage Policy To assign a storage policy, call [`client.storagePolicies.assign(storagePolicyId: String, assignedToType: String, assignedToId, fields: [String]?, completion: @escaping Callback<StoragePolicyAssignment>`](https://opensource.box.com/box-ios-sdk/Classes/StoragePoliciesModule.html#/s:6BoxSDK21StoragePoliciesModuleC6assign15storagePolicyId14assignedToType0jkI06fields10completionySS_S2SSaySSGSgys6ResultOyAA0cH10AssignmentCAA0A8SDKErrorCGctF). ``` client.storagePolicy.assign(storagePolicyId: "1234", assignedToType: "user", assignedToId: "123") { (result: Result<StoragePolicyAssignment, BoxSDKError>) in guard case let .success(assignment) = result else { print("Error assigning a storage policy") return } print("Created storage policy assignment ID is \(assignment.id). The ID of the user it is assigned to \(assignment.assignedTo?.id)") } ``` ## Force Assign Storage Policy To assign a storage policy, call [`client.storagePolicies.forceAssign(storagePolicyId: String, assignedToType: String, assignedToId, fields: [String]?, completion: @escaping Callback<StoragePolicyAssignment>`](https://opensource.box.com/box-ios-sdk/Classes/StoragePoliciesModule.html#/s:6BoxSDK21StoragePoliciesModuleC11forceAssign15storagePolicyId14assignedToType0klJ06fields10completionySS_S2SSaySSGSgys6ResultOyAA0cI10AssignmentCAA0A8SDKErrorCGctF). The difference between this call and the createPolicyAssignment() above is that this method will guarantee an update to the assignee's policy. If an assignee already has a policy assigned to it, the createPolicyAssignment() will return a 409 Conflict error. assignPolicy() will instead make an additional updatePolicyAssignment() call to replace the existing policy with the new policy for a policy assignment. ``` client.storagePolicy.forceAssign(storagePolicyId: "1234", assignedToType: "user", assignedToId: "123") { (result: Result<StoragePolicyAssignment, BoxSDKError>) in guard case let .success(assignment) = result else { print("Error assigning a storage policy") return } print("Created storage policy assignment ID is \(assignment.id). The ID of the user it is assigned to \(assignment.assignedTo?.id)") } ``` ## Update Storage Policy Assignment To update storage policy assignment, call [`client.storagePolicies.updateAssignment(storagePolicyId: String, assignedToType: String, assignedToId, fields: [String]?, completion: @escaping Callback<StoragePolicyAssignment>`](https://opensource.box.com/box-ios-sdk/Classes/StoragePoliciesModule.html#/s:6BoxSDK21StoragePoliciesModuleC16updateAssignment013storagePolicyG2Id0hiJ06fields10completionySS_SSSgSaySSGSgys6ResultOyAA0ciG0CAA0A8SDKErrorCGctF). ``` client.storagePolicy.updateAssignment(storagePolicyAssignmentId: "1234", storagePolicyId: "123") { (result: Result<StoragePolicyAssignment, BoxSDKError>) in guard case let .success(assignment) = result else { print("Error updating a storage policy assignment") return } print("Updated storage policy assignment \(assignment.id)") } ``` ## Delete Storage Policy Assignment To delete a storage policy assignment, call [`client.folders.deleteAssignment(storagePolicyAssignmentId: String, completion: @escaping Callback<Void>`](https://opensource.box.com/box-ios-sdk/Classes/StoragePoliciesModule.html#/s:6BoxSDK21StoragePoliciesModuleC16deleteAssignment013storagePolicyG2Id10completionySS_ys6ResultOyytAA0A8SDKErrorCGctF) with the ID of the storage policy to delete. ``` client.storagePolicies.deleteAssignment(storagePolicyAssignmentId: "22222") { result: Result<Void, BoxSDKError>} in guard case .success = result else { print("Error deleting storage policy assignment") return } print("Storage policy assignment is successfully deleted.") } ``` --- ### Storage Policy **Type:** page | **Section:** Additional Resources Storage Policy Allows the enterprise admin to manage the Storage Policies for users in their enterprise. Used for an enterprise to decide… # Storage Policy Allows the enterprise admin to manage the Storage Policies for users in their enterprise. Used for an enterprise to decide storage location for users based on where they work/reside. - [Get Storage Policy](#get-storage-policy) - [Get List of Storage Policies](#get-list-of-storage-policies) - [Create New Assignment](#create-new-assignment) - [Get Assignment](#get-assignment) - [Get Assignment For Target](#get-assignment-for-target) - [Update Existing Assignment](#update-existing-assignment) - [Assign Storage Policy](#assign-storage-policy) - [Delete Assignment](#delete-assignment) ## Get Storage Policy Calling [`getInfo(String fields ...)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxStoragePolicy.html#getInfo--) will return BoxStoragePolicy.Info object containing information about the storage policy. If necessary to retrieve limited set of fields. It is possible to specify them using param. ``` BoxStoragePolicy storagePolicy = new BoxStoragePolicy(api, id); BoxStoragePolicy.Info storagePolicyInfo = storagePolicy.getInfo(); ``` ## Get List of Storage Policies Calling the static [`getAll(BoxAPIConnection api)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxStoragePolicy.html#getAll--) will return an iterable that will page through all of the storage policies. It is possible to specify maximum number of items per response and fields to retrieve by calling the static [`getAll(BoxAPIConnection api, int limit, String fields ...)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxStoragePolicy.html#getAll-java.lang.String...-) method. ``` Iterable<BoxStoragePolicy.Info> storagePolicies = BoxStoragePolicy.getAll(api); for (BoxStoragePolicy.Info storagePolicyInfo : storagePolicies) { //Do something with the storage policy. } ``` ## Create New Assignment To create new storage policy assignment call [`create(BoxAPIConnection api, String policyID, String userID)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxStoragePolicyAssignment.html#create-com.box.sdk.BoxAPIConnection-java.lang.String-java.lang.String-) method. ``` BoxStoragePolicyAssignment.Info assignmentInfo = BoxStoragePolicyAssignment.create(api, policyID, userID); ``` ## Update Existing Assignment Updating a storage policy assignment information is done by calling [`updateInfo(BoxStoragePolicyAssignment.Info updatedInfo)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxStoragePolicyAssignment.html#updateInfo-com.box.sdk.BoxStoragePolicyAssignment.Info-). ``` BoxStoragePolicyAssignment storagePolicyAssignment = new BoxStoragePolicyAssignment(api, "ASSIGNMENT_ID"); BoxStoragePolicyAssignment.Info assignmentInfo = storagePolicyAssignment.new Info(); assignmentInfo.setStoragePolicyID("NEW_STORAGE_POLICY_ID"); storagePolicyAssignment.updateInfo(assignmentInfo); ``` ## Get Assignment Calling [`getInfo(String fields ...)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxStoragePolicyAssignment.html#getInfo--) will return a BoxStoragePolicyAssignment.Info object containing information about the storage policy assignment. ``` BoxStoragePolicyAssignment storagePolicyAssignment = new BoxStoragePolicyAssignment(api, id); BoxStoragePolicyAssignment.Info assignmentInfo = storagePolicyAssignment.getInfo(); ``` ## Get Assignment for Target Calling [`getAssignmentForTarget(BoxAPIConnection api, String resolvedForType, String resolvedForID)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxStoragePolicyAssignment.html#getAssignmentForTarget-com.box.BoxAPIConnection-java.lang.String-java.lang.String-) will return a BoxStorageAssignment.Info object containing information about the storage policy assignment. ``` BoxStoragePolicyAssignment.Info assignmentInfo = BoxStoragePolicyAssignment.getAssignmentForTarget(api, "user", "1234") ``` ## Assign Storage Policy Calling [`assign(BoxAPIConnection api, String storagePolicyID, String userID)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxStoragePolicyAssigbment.html#assign-com.box.BoxAPIConnection-java.lang.String-java.lang.String-) will check if this user already has storage policy assigned to them. If not then a new this user will be assigned the specified storage policy. ``` BoxStoragePolicyAssignment.Info assignmentInfo = BoxStoragePolicyAssignment.assign(api, "1234", "5678"); ``` ## Delete Assignment Calling [`delete()`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxStoragePolicyAssignment.html#delete--) will remove the storage policy assignment from the user. ``` BoxStoragePolicyAssignment assignment = new BoxStoragePolicyAssignment(api, "dXNlcl8xMjM0"); assignment.delete(); ``` --- ### StoragePoliciesManager **Type:** page | **Section:** Additional Resources StoragePoliciesManager List storage policies Get storage policy List storage policies Fetches all the storage policies in the enterprise… # StoragePoliciesManager - [List storage policies](#list-storage-policies) - [Get storage policy](#get-storage-policy) ## List storage policies Fetches all the storage policies in the enterprise. This operation is performed by calling function `getStoragePolicies`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-storage-policies/). ``` await client.storagePolicies.getStoragePolicies(); ``` ### Arguments queryParams `GetStoragePoliciesQueryParams` - Query parameters of getStoragePolicies method headersInput `GetStoragePoliciesHeadersInput` - Headers of getStoragePolicies method cancellationToken `undefined | CancellationToken` - Token used for request cancellation. ### Returns This function returns a value of type `StoragePolicies`. Returns a collection of storage policies. ## Get storage policy Fetches a specific storage policy. This operation is performed by calling function `getStoragePolicyById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-storage-policies-id/). ``` await client.storagePolicies.getStoragePolicyById(storagePolicy.id); ``` ### Arguments storagePolicyId `string` - The ID of the storage policy. Example: "34342" optionalsInput `GetStoragePolicyByIdOptionalsInput` ### Returns This function returns a value of type `StoragePolicy`. Returns a storage policy object. --- ### StoragePoliciesManager **Type:** page | **Section:** Additional Resources StoragePoliciesManager List storage policies Get storage policy List storage policies Fetches all the storage policies in the enterprise… # StoragePoliciesManager - [List storage policies](#list-storage-policies) - [Get storage policy](#get-storage-policy) ## List storage policies Fetches all the storage policies in the enterprise. This operation is performed by calling function `get_storage_policies`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-storage-policies/). ``` client.storage_policies.get_storage_policies() ``` ### Arguments fields `Optional[List[str]]` - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested. marker `Optional[str]` - Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`. limit `Optional[int]` - The maximum number of items to return per page. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `StoragePolicies`. Returns a collection of storage policies. ## Get storage policy Fetches a specific storage policy. This operation is performed by calling function `get_storage_policy_by_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-storage-policies-id/). ``` client.storage_policies.get_storage_policy_by_id(storage_policy.id) ``` ### Arguments storage_policy_id `str` - The ID of the storage policy. Example: "34342" extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `StoragePolicy`. Returns a storage policy object. --- ### StoragePolicyAssignmentsManager **Type:** page | **Section:** Additional Resources StoragePolicyAssignmentsManager List storage policy assignments Assign storage policy Get storage policy assignment Update storage policy… # StoragePolicyAssignmentsManager - [List storage policy assignments](#list-storage-policy-assignments) - [Assign storage policy](#assign-storage-policy) - [Get storage policy assignment](#get-storage-policy-assignment) - [Update storage policy assignment](#update-storage-policy-assignment) - [Unassign storage policy](#unassign-storage-policy) ## List storage policy assignments Fetches all the storage policy assignment for an enterprise or user. This operation is performed by calling function `getStoragePolicyAssignments`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-storage-policy-assignments/). ``` await client.storagePolicyAssignments.getStoragePolicyAssignments({ resolvedForType: 'user' as GetStoragePolicyAssignmentsQueryParamsResolvedForTypeField, resolvedForId: userId, } satisfies GetStoragePolicyAssignmentsQueryParams); ``` ### Arguments queryParams `GetStoragePolicyAssignmentsQueryParams` - Query parameters of getStoragePolicyAssignments method optionalsInput `GetStoragePolicyAssignmentsOptionalsInput` ### Returns This function returns a value of type `StoragePolicyAssignments`. Returns a collection of storage policies for the enterprise or user. ## Assign storage policy Creates a storage policy assignment for an enterprise or user. This operation is performed by calling function `createStoragePolicyAssignment`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-storage-policy-assignments/). ``` await client.storagePolicyAssignments.createStoragePolicyAssignment({ storagePolicy: new CreateStoragePolicyAssignmentRequestBodyStoragePolicyField( { id: policyId }, ), assignedTo: { id: userId, type: 'user' as CreateStoragePolicyAssignmentRequestBodyAssignedToTypeField, } satisfies CreateStoragePolicyAssignmentRequestBodyAssignedToField, } satisfies CreateStoragePolicyAssignmentRequestBody); ``` ### Arguments requestBody `CreateStoragePolicyAssignmentRequestBody` - Request body of createStoragePolicyAssignment method optionalsInput `CreateStoragePolicyAssignmentOptionalsInput` ### Returns This function returns a value of type `StoragePolicyAssignment`. Returns the new storage policy assignment created. ## Get storage policy assignment Fetches a specific storage policy assignment. This operation is performed by calling function `getStoragePolicyAssignmentById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-storage-policy-assignments-id/). ``` await client.storagePolicyAssignments.getStoragePolicyAssignmentById( storagePolicyAssignment.id, ); ``` ### Arguments storagePolicyAssignmentId `string` - The ID of the storage policy assignment. Example: "932483" optionalsInput `GetStoragePolicyAssignmentByIdOptionalsInput` ### Returns This function returns a value of type `StoragePolicyAssignment`. Returns a storage policy assignment object. ## Update storage policy assignment Updates a specific storage policy assignment. This operation is performed by calling function `updateStoragePolicyAssignmentById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-storage-policy-assignments-id/). ``` await client.storagePolicyAssignments.updateStoragePolicyAssignmentById( storagePolicyAssignment.id, { storagePolicy: new UpdateStoragePolicyAssignmentByIdRequestBodyStoragePolicyField({ id: storagePolicy2.id, }), } satisfies UpdateStoragePolicyAssignmentByIdRequestBody, ); ``` ### Arguments storagePolicyAssignmentId `string` - The ID of the storage policy assignment. Example: "932483" requestBody `UpdateStoragePolicyAssignmentByIdRequestBody` - Request body of updateStoragePolicyAssignmentById method optionalsInput `UpdateStoragePolicyAssignmentByIdOptionalsInput` ### Returns This function returns a value of type `StoragePolicyAssignment`. Returns an updated storage policy assignment object. ## Unassign storage policy Delete a storage policy assignment. Deleting a storage policy assignment on a user will have the user inherit the enterprise's default storage policy. There is a rate limit for calling this endpoint of only twice per user in a 24 hour time frame. This operation is performed by calling function `deleteStoragePolicyAssignmentById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-storage-policy-assignments-id/). ``` await client.storagePolicyAssignments.deleteStoragePolicyAssignmentById( storagePolicyAssignment.id, ); ``` ### Arguments storagePolicyAssignmentId `string` - The ID of the storage policy assignment. Example: "932483" optionalsInput `DeleteStoragePolicyAssignmentByIdOptionalsInput` ### Returns This function returns a value of type `undefined`. Returns an empty response when the storage policy assignment is successfully deleted. --- ### StoragePolicyAssignmentsManager **Type:** page | **Section:** Additional Resources StoragePolicyAssignmentsManager List storage policy assignments Assign storage policy Get storage policy assignment Update storage policy… # StoragePolicyAssignmentsManager - [List storage policy assignments](#list-storage-policy-assignments) - [Assign storage policy](#assign-storage-policy) - [Get storage policy assignment](#get-storage-policy-assignment) - [Update storage policy assignment](#update-storage-policy-assignment) - [Unassign storage policy](#unassign-storage-policy) ## List storage policy assignments Fetches all the storage policy assignment for an enterprise or user. This operation is performed by calling function `get_storage_policy_assignments`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-storage-policy-assignments/). ``` client.storage_policy_assignments.get_storage_policy_assignments( GetStoragePolicyAssignmentsResolvedForType.USER, user_id ) ``` ### Arguments marker `Optional[str]` - Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`. resolved_for_type `GetStoragePolicyAssignmentsResolvedForType` - The target type to return assignments for. resolved_for_id `str` - The ID of the user or enterprise to return assignments for. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `StoragePolicyAssignments`. Returns a collection of storage policies for the enterprise or user. ## Assign storage policy Creates a storage policy assignment for an enterprise or user. This operation is performed by calling function `create_storage_policy_assignment`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-storage-policy-assignments/). ``` client.storage_policy_assignments.create_storage_policy_assignment( CreateStoragePolicyAssignmentStoragePolicy(id=policy_id), CreateStoragePolicyAssignmentAssignedTo( id=user_id, type=CreateStoragePolicyAssignmentAssignedToTypeField.USER ), ) ``` ### Arguments storage_policy `CreateStoragePolicyAssignmentStoragePolicy` - The storage policy to assign to the user or enterprise. assigned_to `CreateStoragePolicyAssignmentAssignedTo` - The user or enterprise to assign the storage policy to. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `StoragePolicyAssignment`. Returns the new storage policy assignment created. ## Get storage policy assignment Fetches a specific storage policy assignment. This operation is performed by calling function `get_storage_policy_assignment_by_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-storage-policy-assignments-id/). ``` client.storage_policy_assignments.get_storage_policy_assignment_by_id( storage_policy_assignment.id ) ``` ### Arguments storage_policy_assignment_id `str` - The ID of the storage policy assignment. Example: "932483" extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `StoragePolicyAssignment`. Returns a storage policy assignment object. ## Update storage policy assignment Updates a specific storage policy assignment. This operation is performed by calling function `update_storage_policy_assignment_by_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-storage-policy-assignments-id/). ``` client.storage_policy_assignments.update_storage_policy_assignment_by_id( storage_policy_assignment.id, UpdateStoragePolicyAssignmentByIdStoragePolicy(id=storage_policy_2.id), ) ``` ### Arguments storage_policy_assignment_id `str` - The ID of the storage policy assignment. Example: "932483" storage_policy `UpdateStoragePolicyAssignmentByIdStoragePolicy` - The storage policy to assign to the user or enterprise. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `StoragePolicyAssignment`. Returns an updated storage policy assignment object. ## Unassign storage policy Delete a storage policy assignment. Deleting a storage policy assignment on a user will have the user inherit the enterprise's default storage policy. There is a rate limit for calling this endpoint of only twice per user in a 24 hour time frame. This operation is performed by calling function `delete_storage_policy_assignment_by_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-storage-policy-assignments-id/). ``` client.storage_policy_assignments.delete_storage_policy_assignment_by_id( storage_policy_assignment.id ) ``` ### Arguments storage_policy_assignment_id `str` - The ID of the storage policy assignment. Example: "932483" extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `None`. Returns an empty response when the storage policy assignment is successfully deleted. --- ### TaskAssignmentsManager **Type:** page | **Section:** Additional Resources TaskAssignmentsManager List task assignments Assign task Get task assignment Update task assignment Unassign task List task assignments… # TaskAssignmentsManager - [List task assignments](#list-task-assignments) - [Assign task](#assign-task) - [Get task assignment](#get-task-assignment) - [Update task assignment](#update-task-assignment) - [Unassign task](#unassign-task) ## List task assignments Lists all of the assignments for a given task. This operation is performed by calling function `getTaskAssignments`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-tasks-id-assignments/). ``` await client.taskAssignments.getTaskAssignments(task.id!); ``` ### Arguments taskId `string` - The ID of the task. Example: "12345" optionalsInput `GetTaskAssignmentsOptionalsInput` ### Returns This function returns a value of type `TaskAssignments`. Returns a collection of task assignment defining what task on a file has been assigned to which users and by who. ## Assign task Assigns a task to a user. A task can be assigned to more than one user by creating multiple assignments. This operation is performed by calling function `createTaskAssignment`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-task-assignments/). ``` await client.taskAssignments.createTaskAssignment({ task: new CreateTaskAssignmentRequestBodyTaskField({ type: 'task' as CreateTaskAssignmentRequestBodyTaskTypeField, id: task.id!, }), assignTo: { id: currentUser.id, } satisfies CreateTaskAssignmentRequestBodyAssignToField, } satisfies CreateTaskAssignmentRequestBody); ``` ### Arguments requestBody `CreateTaskAssignmentRequestBody` - Request body of createTaskAssignment method optionalsInput `CreateTaskAssignmentOptionalsInput` ### Returns This function returns a value of type `TaskAssignment`. Returns a new task assignment object. ## Get task assignment Retrieves information about a task assignment. This operation is performed by calling function `getTaskAssignmentById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-task-assignments-id/). ``` await client.taskAssignments.getTaskAssignmentById(taskAssignment.id!); ``` ### Arguments taskAssignmentId `string` - The ID of the task assignment. Example: "12345" optionalsInput `GetTaskAssignmentByIdOptionalsInput` ### Returns This function returns a value of type `TaskAssignment`. Returns a task assignment, specifying who the task has been assigned to and by whom. ## Update task assignment Updates a task assignment. This endpoint can be used to update the state of a task assigned to a user. This operation is performed by calling function `updateTaskAssignmentById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-task-assignments-id/). ``` await client.taskAssignments.updateTaskAssignmentById(taskAssignment.id!, { requestBody: { message: 'updated message', resolutionState: 'approved' as UpdateTaskAssignmentByIdRequestBodyResolutionStateField, } satisfies UpdateTaskAssignmentByIdRequestBody, } satisfies UpdateTaskAssignmentByIdOptionalsInput); ``` ### Arguments taskAssignmentId `string` - The ID of the task assignment. Example: "12345" optionalsInput `UpdateTaskAssignmentByIdOptionalsInput` ### Returns This function returns a value of type `TaskAssignment`. Returns the updated task assignment object. ## Unassign task Deletes a specific task assignment. This operation is performed by calling function `deleteTaskAssignmentById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-task-assignments-id/). ``` await client.taskAssignments.deleteTaskAssignmentById(taskAssignment.id!); ``` ### Arguments taskAssignmentId `string` - The ID of the task assignment. Example: "12345" optionalsInput `DeleteTaskAssignmentByIdOptionalsInput` ### Returns This function returns a value of type `undefined`. Returns an empty response when the task assignment was successfully deleted. --- ### TaskAssignmentsManager **Type:** page | **Section:** Additional Resources TaskAssignmentsManager List task assignments Assign task Get task assignment Update task assignment Unassign task List task assignments… # TaskAssignmentsManager - [List task assignments](#list-task-assignments) - [Assign task](#assign-task) - [Get task assignment](#get-task-assignment) - [Update task assignment](#update-task-assignment) - [Unassign task](#unassign-task) ## List task assignments Lists all of the assignments for a given task. This operation is performed by calling function `get_task_assignments`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-tasks-id-assignments/). ``` client.task_assignments.get_task_assignments(task.id) ``` ### Arguments task_id `str` - The ID of the task. Example: "12345" extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `TaskAssignments`. Returns a collection of task assignment defining what task on a file has been assigned to which users and by who. ## Assign task Assigns a task to a user. A task can be assigned to more than one user by creating multiple assignments. This operation is performed by calling function `create_task_assignment`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-task-assignments/). ``` client.task_assignments.create_task_assignment( CreateTaskAssignmentTask(type=CreateTaskAssignmentTaskTypeField.TASK, id=task.id), CreateTaskAssignmentAssignTo(id=current_user.id), ) ``` ### Arguments task `CreateTaskAssignmentTask` - The task to assign to a user. assign_to `CreateTaskAssignmentAssignTo` - The user to assign the task to. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `TaskAssignment`. Returns a new task assignment object. ## Get task assignment Retrieves information about a task assignment. This operation is performed by calling function `get_task_assignment_by_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-task-assignments-id/). ``` client.task_assignments.get_task_assignment_by_id(task_assignment.id) ``` ### Arguments task_assignment_id `str` - The ID of the task assignment. Example: "12345" extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `TaskAssignment`. Returns a task assignment, specifying who the task has been assigned to and by whom. ## Update task assignment Updates a task assignment. This endpoint can be used to update the state of a task assigned to a user. This operation is performed by calling function `update_task_assignment_by_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-task-assignments-id/). ``` client.task_assignments.update_task_assignment_by_id( task_assignment.id, message="updated message", resolution_state=UpdateTaskAssignmentByIdResolutionState.APPROVED, ) ``` ### Arguments task_assignment_id `str` - The ID of the task assignment. Example: "12345" message `Optional[str]` - An optional message by the assignee that can be added to the task. resolution_state `Optional[UpdateTaskAssignmentByIdResolutionState]` - The state of the task assigned to the user. _ For a task with an `action` value of `complete` this can be `incomplete` or `completed`. _ For a task with an `action` of `review` this can be `incomplete`, `approved`, or `rejected`. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `TaskAssignment`. Returns the updated task assignment object. ## Unassign task Deletes a specific task assignment. This operation is performed by calling function `delete_task_assignment_by_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-task-assignments-id/). ``` client.task_assignments.delete_task_assignment_by_id(task_assignment.id) ``` ### Arguments task_assignment_id `str` - The ID of the task assignment. Example: "12345" extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `None`. Returns an empty response when the task assignment was successfully deleted. --- ### Tasks **Type:** page | **Section:** Additional Resources Tasks Tasks enable file-centric workflows in Box. User can create tasks on files and assign them to collaborators on Box. Create a Task Get… # Tasks Tasks enable file-centric workflows in Box. User can create tasks on files and assign them to collaborators on Box. - [Create a Task](#create-a-task) - [Get a Task's Information](#get-a-tasks-information) - [Update a Task](#update-a-task) - [Delete a Task](#delete-a-task) - [Get Assignments for a Task](#get-assignments-for-a-task) - [Get Task Assignment](#get-task-assignment) - [Assign Task](#assign-task) - [Update Task Assignment](#update-task-assignment) - [Remove Task Assignment](#remove-task-assignment) - [Get Tasks on a File](#get-tasks-on-a-file) ## Create a Task To create a task call the [`tasks.create(fileID, options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Tasks.html#create) method. ``` var options = { message: 'Please review for publication!', due_at: '2014-04-03T11:09:43-07:00' }; client.tasks.create('22222', options) .then(task => { /* task -> { type: 'task', id: '11111', item: { type: 'file', id: '22222', sequence_id: '0', etag: '0', sha1: '0bbd79a105c504f99573e3799756debba4c760cd', name: 'box-logo.png' }, due_at: '2014-04-03T11:09:43-07:00', action: 'review', message: 'Please review for publication!', task_assignment_collection: { total_count: 0, entries: [] }, is_completed: false, created_by: { type: 'user', id: '33333', name: 'Example User', login: 'user@example.com' }, created_at: '2013-04-03T11:12:54-07:00' } */ }); ``` ## Get a Task's Information To get a task information call the [`tasks.get(taskID, options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Tasks.html#get) method. ``` client.tasks.get('11111') .then(task => { /* task -> { type: 'task', id: '11111', item: { type: 'file', id: '22222', sequence_id: '0', etag: '0', sha1: '0bbd79a105c504f99573e3799756debba4c760cd', name: 'box-logo.png' }, due_at: '2014-04-03T11:09:43-07:00', action: 'review', message: 'Please review for publication!', task_assignment_collection: { total_count: 0, entries: [] }, is_completed: false, created_by: { type: 'user', id: '33333', name: 'Example User', login: 'user@example.com' }, created_at: '2013-04-03T11:12:54-07:00' } */ }); ``` Requesting information for only the fields you need with the `fields` option can improve performance and reduce the size of the network request. ``` client.tasks.get('11111', {fields: 'message,is_completed'}) .then(task => { /* task -> { type: 'task', id: '11111', message: 'Please review for publication!', is_completed: false } */ }); ``` ## Update a Task To update a task call the [`tasks.update(taskID, updates, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Tasks.html#update) method with the set of fields to update and their new values. ``` client.tasks.update('11111', { message: 'Could you please review?' }) .then(task => { /* task -> { type: 'task', id: '11111', item: { type: 'file', id: '22222', sequence_id: '0', etag: '0', sha1: '0bbd79a105c504f99573e3799756debba4c760cd', name: 'box-logo.png' }, due_at: '2014-04-03T11:09:43-07:00', action: 'review', message: 'Could you please review?', task_assignment_collection: { total_count: 0, entries: [] }, is_completed: false, created_by: { type: 'user', id: '33333', name: 'Example User', login: 'user@example.com' }, created_at: '2013-04-03T11:12:54-07:00' } */ }); ``` ## Delete a Task To delete a task, call the [`tasks.delete(taskID, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Tasks.html#delete) method with the ID of the task to be deleted. ``` client.tasks.delete('11111') .then(() => { // deletion succeeded — no value returned }); ``` ## Get Assignments for a Task To get a list of assignments for a task, which associate the task to users who must complete it, call the [`tasks.getAssignments(taskID, options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Tasks.html#getAssignments) method. ``` client.tasks.getAssignments('11111') .then(assignments => { /* assignments -> { total_count: 1, entries: [ { type: 'task_assignment', id: '22222', item: { type: 'file', id: '44444', sequence_id: '0', etag: '0', sha1: '0bbd79a105c504f99573e3799756debba4c760cd', name: 'box-logo.png' }, assigned_to: { type: 'user', id: '33333', name: 'Example User', login: 'user@example.com' } } ] } */ }); ``` ## Get Task Assignment To retrieve information about a specific task assignment, call the [`tasks.getAssignment(assignmentID, options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Tasks.html#getAssignment) method with the ID of the assignment to get. ``` client.tasks.getAssignment('12345') .then(assignment => { /* assignment -> { type: 'task_assignment', id: '12345', item: { type: 'file', id: '33333', sequence_id: '0', etag: '0', sha1: '7840095ee096ee8297676a138d4e316eabb3ec96', name: 'script.js' }, assigned_to: { type: 'user', id: '22222', name: 'Sample Assignee', login: 'assignee@exmaple.com' }, message: null, completed_at: null, assigned_at: '2013-05-10T11:43:41-07:00', reminded_at: null, resolution_state: 'incomplete', assigned_by: { type: 'user', id: '33333', name: 'Example User', login: 'user@example.com' } } */ }); ``` ## Assign Task To assign a task to a user, call [`tasks.assignByUserID(taskID, userID, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Tasks.html#assignByUserID) or [`tasks.assignByEmail(taskID, email, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Tasks.html#assignByEmail) with the ID of the task to assign and either the ID or login email address of the user to whom the task should be assigned. ``` // Assign task 11111 to user 22222 var taskID = '11111'; var userID = '22222'; client.tasks.assignByUserID(taskID, userID) .then(assignment => { /* assignment -> { type: 'task_assignment', id: '12345', item: { type: 'file', id: '33333', sequence_id: '0', etag: '0', sha1: '7840095ee096ee8297676a138d4e316eabb3ec96', name: 'script.js' }, assigned_to: { type: 'user', id: '22222', name: 'Sample Assignee', login: 'assignee@exmaple.com' }, message: null, completed_at: null, assigned_at: '2013-05-10T11:43:41-07:00', reminded_at: null, resolution_state: 'incomplete', assigned_by: { type: 'user', id: '33333', name: 'Example User', login: 'user@example.com' } } */ }); ``` ``` // Assign task 11111 to the user with email address assignee@exmaple.com client.tasks.assignByEmail('11111', 'assignee@example.com') .then(assignment => { // ... }); ``` ## Update Task Assignment To update a task assignment, call the [`tasks.updateAssignment(assignmentID, options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Tasks.html#updateAssignment) method. This can be used to resolve or complete a task. ``` // Complete a task client.tasks.updateAssignment( '12345', { message: 'Done!', resolution_state: client.tasks.resolutionStates.COMPLETE }) .then(assignment => { /* assignment -> { type: 'task_assignment', id: '12345', item: { type: 'file', id: '33333', sequence_id: '0', etag: '0', sha1: '7840095ee096ee8297676a138d4e316eabb3ec96', name: 'script.js' }, assigned_to: { type: 'user', id: '22222', name: 'Sample Assignee', login: 'assignee@exmaple.com' }, message: 'Done!', completed_at: null, assigned_at: '2013-05-10T11:43:41-07:00', reminded_at: null, resolution_state: 'complete', assigned_by: { type: 'user', id: '33333', name: 'Example User', login: 'user@example.com' } } */ }); ``` ``` // Update the task assignment message client.tasks.updateAssignment( '12345', { message: 'This needs some more changes' }) .then(assignment => { // ... }); ``` ## Remove Task Assignment To delete a task assignment, effectively unassigning a user from the task, call the [`tasks.deleteAssignment(assignmentID, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Tasks.html#deleteAssignment) method with the ID of the assignment to remove. ``` client.tasks.deleteAssignment('12345') .then(() => { // deletion succeeded — no value returned }); ``` ## Get Tasks on a File Calling the [`files.getTasks(fileID, options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Files.html#getTasks) method will retrieve all of the tasks for given file. ``` client.files.getTasks('11111') .then(tasks => { /* tasks -> { total_count: 1, entries: [ { type: 'task', id: '22222', item: { type: 'file', id: '11111', sequence_id: '6', etag: '6', sha1: '81cc829fb8366fcfc108aa6c5a9bde01a6a10c16', name: 'box-logo.png' }, due_at: null } ] } */ }); ``` --- ### Tasks **Type:** page | **Section:** Additional Resources Tasks Task objects represent a user-created task on a file. Get a Task's Information Get the Tasks on a File Add a Task to a File Update a… # Tasks Task objects represent a user-created task on a file. - [Get a Task's Information](#get-a-tasks-information) - [Get the Tasks on a File](#get-the-tasks-on-a-file) - [Add a Task to a File](#add-a-task-to-a-file) - [Update a Task's Information](#update-a-tasks-information) - [Delete a Task](#delete-a-task) - [Get a Task's Assignments](#get-a-tasks-assignments) - [Get Information About a Task Assignment](#get-information-about-a-task-assignment) - [Add a Task Assignment](#add-a-task-assignment) - [Delete a Task Assignment](#delete-a-task-assignment) - [Update a Task Assignment](#update-a-task-assignment) ## Get a Task's Information Calling [`getInfo()`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxTask.html#getInfo--) on a task returns a snapshot of the task's info. ``` BoxTask task = new BoxTask(api, "id"); BoxTask.Info info = task.getInfo(); ``` ## Get the Tasks on a File You can get all of the tasks on a file by calling the [`getTasks()`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFile.html#getTasks--) method. ``` BoxFile file = new BoxFile(api, "id"); List<BoxTask.Info> tasks = file.getTasks(); ``` ## Add a Task to a File A task can be added to a file with the [`addTask(BoxTask.Action action, String message, Date dueAt)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFile.html#addTask-com.box.sdk.BoxTask.Action-java.lang.String-java.util.Date-) method. ``` BoxFile file = new BoxFile(api, "id"); Date dueAt = new Date(); file.addTask(BoxTask.Action.REVIEW, "Please review this file.", dueAt); ``` ## Update a Task's Information The message of a task can be changed with the [`updateInfo(BoxTask.Info fieldsToUpdate)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxTask.html#updateInfo-com.box.sdk.BoxTask.Info-) method. ``` BoxTask task = new BoxTask(api, "id"); BoxTask.Info info = task.new Info(); info.setMessage("An edited message."); task.updateInfo(info); ``` ## Delete a Task A task can be deleted with the [`delete()`](https://box.github.io/box-java-sdk/javadoc/com/box/sdk/BoxTask.html#delete--) method. ``` BoxTask task = new BoxTask(api, "id"); task.delete(); ``` ## Get a Task's Assignments Retreive a tasks assignments with the [`getAssignments()`](https://box.github.io/box-java-sdk/javadoc/com/box/sdk/BoxTask.html#getAssignments--) method. ``` BoxTask task = new BoxTask(api, "id"); task.getAssignments(); ``` ## Get Information About a Task Assignment To look up information about a task assignment by its ID, instantiate the [`BoxTaskAssignment`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxTaskAssignment.html) object with the ID, and call [`getInfo()`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxTaskAssignment.html#getInfo--) on the assignment. To retrieve only specific fields on the task assignment, call [`getInfo(String... fields)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxTaskAssignment.html#getInfo-java.lang.String...-) with the fields to retrieve. ``` String assignmentID = "4256974"; BoxTaskAssignment.Info assignmentInfo = new BoxTaskAssignment(api, assignmentID).getInfo(); ``` ## Add a Task Assignment An assignment can be added to a task with the [`addAssignment(BoxUser assignee)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxTask.html#addAssignment-com.box.sdk.BoxUser-) method. ``` BoxUser user = new BoxUser(api, "user-id") BoxTask task = new BoxTask(api, "id"); task.addAssignment(user); ``` ## Delete a Task Assignment An assignment can be deleted from a task with the [`delete()`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxTaskAssignment.html#delete--) method on a [`BoxTaskAssignment`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxTaskAssignment.html) instance. ``` BoxTaskAssignment taskAssignment = new BoxTaskAssignment(api, "id"); taskAssignment.delete(); ``` ## Update a Task Assignment A task assignment can be updated with the [`updateInfo(BoxTask.Info fieldsToUpdate)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxTaskAssignment.html#updateInfo-com.box.sdk.BoxTaskAssignment.Info-) method. Updating the resolution state: ``` String assignmentID = "12345"; BoxTaskAssignment taskAssignment = new BoxTaskAssignment(api, assignmentID); BoxTaskAssignment.Info info = taskAssignment.getInfo(); info.setResolutionState(BoxTaskAssignment.ResolutionState.APPROVED); taskAssignment.updateInfo(info); ``` Updating the message: ``` String assignmentID = "12345"; BoxTaskAssignment taskAssignment = new BoxTaskAssignment(api, assignmentID); BoxTaskAssignment.Info info = taskAssignment.getInfo(); info.setMessage("Please review the meeting notes"); taskAssignment.updateInfo(info); ``` --- ### Tasks **Type:** page | **Section:** Additional Resources Tasks Tasks enable file-centric workflows in Box. User can create tasks on files and assign them to collaborators on Box. Get a Task's… # Tasks Tasks enable file-centric workflows in Box. User can create tasks on files and assign them to collaborators on Box. - [Get a Task's Information](#get-a-tasks-information) - [List Tasks on File](#list-tasks-on-file) - [Add Task to File](#add-task-to-file) - [Update Task Info](#update-task-info) - [Delete a Task](#delete-a-task) - [Assign a Task](#assign-a-task) - [Assign a Task with User Login](#assign-a-task-with-user-login) - [List Task Assignments](#list-task-assignments) - [Get Information about Task Assignment](#get-information-about-task-assignment) - [Update Task Assignment](#update-task-assignment) - [Delete Task Assignment](#delete-task-assignment) ## Get a Task's Information To get a task object, first call [`client.task(task_id)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.client.html#boxsdk.client.client.Client.task) to construct the appropriate [`Task`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.task.Task) object, and then calling [`task.get(*, fields=None, headers=None, **kwargs)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.base_object.BaseObject.get) will return the [`Task`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.task.Task) object populated with data from the API, leaving the original object unmodified. ``` task = client.task(task_id='12345').get() print(f'Task ID is {task.id} and the type is {task.type}') ``` ## List Tasks on File To retrieve all tasks on a file, call [`file.get_tasks(fields=None)`]['get_tasks'] will return a `BoxObjectCollection` that allows you to iterate over the [`Task`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.task.Task) objects in the collection. ``` tasks = client.file(file_id='11111').get_tasks() for task in tasks: print(f'Task ID is {task.id} and the type is {task.type}') ``` ## Add Task to File To create a single task for a single user on a single file, call [`file.create_task(message=None, due_at=None)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.file.File.create_Task) will return a newly created [`Task`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.task.Task) object populated with data from the API. ``` message = 'Please review this' due_at = "2014-04-03T11:09:43-07:00" task = client.file(file_id='11111').create_task(message, due_at) print(f'Task message is {task.message} and it is due at {task.due_at}') ``` ## Update Task Info To update a task object, first call [`task.update_info(data=task_update)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.base_object.BaseObject.update_info) with a `dict` of properties to update on the task. This method returns a newly updated [`Task`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.task.Task) object, leaving the original object unmodified. ``` task_update = {'message': 'New Message', 'due_at': '2014-04-03T11:09:43-10:00'} updated_task = client.task(task_id='12345').update_info(data=task_update) print(f'New task message is {updated_task.message} and the new due time is {updated_task.due_at}') ``` ## Delete a Task To delete a task, first call [`client.task(task_id)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.client.html#boxsdk.client.client.Client.task) to construct the appropriate task object, and then call [`task.delete()`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.base_object.BaseObject.delete). This method returns `True` to indicate that the deleteion was successful. ``` client.client.task('12345').delete() print('The task was successfully delete!') ``` ## Assign a Task To assign a task object, first call [`client.task(task_id)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.client.html#boxsdk.client.client.Client.task) to construct the appropriate task object, then call [`task.assign(user)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.task.Task.assign) will return an [`Task Assignment`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.task_assignment.TaskAssignment) object, populated with data from the API. ``` user = client.user(user_id='11111') assignment = client.task(task_id='12345').assign(user) print(f'Assignment ID is {assignment.id} and is assigned to user {assignment.assigned_to.name}') ``` ## Assign a Task with User Login To assign a task object with a user login, first call [`task.assign_with_login(login)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.task_assignment.assign_with_login) with a `unicode` value for user login. This method will return a [`TaskAssignment`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.task_assignment.TaskAssignment) object, populated with data from the API. ``` assignment = client.task(task_id='12345').assign_with_login('test_user@example.com') print(f'Assignment ID is {assignment.id} and the assignee is {assignment.assigned_to.login}') ``` ## List Task Assignments To retrieve all assignments for an enterprise, first call [`client.task(task_id)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.client.html#boxsdk.client.client.Client.task) to construct the appropriate task object. Then call ['task.get_assignments(fields=None)'](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.task.Task.get_assignments). This method returns a `BoxObjectCollection` that allows you to iterate over the ['TaskAssignment'](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.task_assignment.TaskAssignment) objects in the collection. ``` assignments = client.task(task_id='12345').get_assignments() for assignment in assignments: print(f'Assignment ID is {assignment.id} and the assignee is {assignment.assigned_to.login}') ``` ## Get Information about Task Assignment To get a task assignment object, first call [`client.task_assignment(assignment_id)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.client.html#boxsdk.client.client.Client.task_assignment) to construct the appropriate [`TaskAssignment`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.task_assignment.TaskAssignment) object, and then calling ['task_assignment.get(*, fields=None, headers=None, **kwargs)'](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.base_object.BaseObject.get) will return the [`TaskAssignment`][task_assignment] object populated with data from the API. ``` assignment= client.task_assignment('12345').get() print(f'Assignment ID is {assignment.id} and assignment type is {assignment.type}') ``` ## Update Task Assignment To update a task assignment object, call [`assignment.update_info(data=updated_task)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.base_object.BaseObject.update_info) with a `dict` of properties to update on a task assignment. This method returns a newly update [`TaskAssignment`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.task_assignment.TaskAssignment) object, leaving the original object unmodified. ``` from boxsdk.object.task_assignment import ResolutionState updated_task = {'resolution_state': ResolutionState.APPROVED} updated_assignment = client.task_assignment(assignment_id='12345').update_info(data=updated_task) print(f'Assignment ID is {updated_assignment.id} and resolution state is {updated_assignment.resolution_state}') ``` ``` updated_task = {'message': 'new message'} updated_assignment = client.task_assignment(assignment_id='12345').update_info(data=updated_task) print(f'Assignment ID is {updated_assignment.id} and message is {updated_task.message}') ``` ## Delete Task Assignment To delete a task assignment, call [`task_assignment.delete()`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.base_object.BaseObject.delete). This method returns `True` to indicate that the deletion was successful. ``` client.task_assignment(assignment_id='12345').delete() print('The task assignment was successfully delete!') ``` --- ### Tasks **Type:** page | **Section:** Additional Resources Tasks Tasks enable file-centric workflows in Box. User can create tasks on files and assign them to collaborators on Box. Get a Task's… # Tasks Tasks enable file-centric workflows in Box. User can create tasks on files and assign them to collaborators on Box. - [Get a Task's Information](#get-a-tasks-information) - [Get Tasks on a File](#get-tasks-on-a-file) - [Create a Task](#create-a-task) - [Update a Task](#update-a-task) - [Delete a Task](#delete-a-task) - [Get Assignments for a Task](#get-assignments-for-a-task) - [Assign Task](#assign-task) - [Get Task Assignment](#get-task-assignment) - [Update Task Assignment](#update-task-assignment) - [Remove Task Assignment](#remove-task-assignment) ## Get a Task's Information To get a task information call `TasksManager.GetTaskAsync(string taskId)` with the ID of the task. ``` BoxTask task = await client.TasksManager.GetTaskAsync("11111"); ``` ## Get Tasks on a File Calling the `FilesManager.GetFileTasks(string id, IEnumerable<string> fields = null)` method will retrieve all of the tasks for the given file. ``` BoxCollection<BoxTask> tasks = await client.FilesManager.FilesManager.GetFileTasks("11111"); ``` ## Create a Task To create a task, call `TasksManager.CreateTaskAsync(BoxTaskCreateRequest taskCreateRequest)` with the parameters of the task. ``` var taskParams = new BoxTaskCreateRequest() { Item = new BoxRequestEntity() { Type = BoxType.file, Id = "11111" }, Message = "Please review!" }; BoxTask task = await client.TasksManager.CreateTaskAsync(taskParams); ``` ## Update a Task To update a task, call `TasksManager.UpdateTaskAsync(BoxTaskUpdateRequest taskUpdateRequest)`. ``` var updates = new BoxTaskUpdateRequest() { Id = "22222", Message = "Could you please review this?" }; BoxTask updatedTask = await client.TasksManager.UpdateTaskAsync(updates); ``` ## Delete a Task To delete a task, call the `TasksManager.DeleteTaskAsync(string taskId)` method with the ID of the task to be deleted. ``` await client.TasksManager.DeleteTaskAsync("11111"); ``` ## Get Assignments for a Task To get a list of assignments for a task, which associate the task to users who must complete it, call `TasksManager.GetAssignmentsAsync(string taskId)` with the ID of the task. ``` BoxCollection<BoxTaskAssignment> assignments = await client.TasksManager .GetAssignmentsAsync(taskId: "11111"); ``` ## Assign Task To assign a task to a user, call `TasksManager.CreateTaskAssignmentAsync(BoxTaskAssignmentRequest taskAssignmentRequest)` with the ID of the task to assign and either the ID or login email address of the user to whom the task should be assigned. ``` // Assign task 11111 to user 22222 var assignmentParams = new BoxTaskAssignmentRequest() { Task = new BoxTaskRequest() { Id = "11111" }, AssignTo = new BoxAssignmentRequest() { Id = "22222" } }; BoxTaskAssignment assignment = await client.TasksManager.CreateTaskAssignmentAsync(assignmentParams); ``` ``` // Assign task 11111 to user with login user@example.com var assignmentParams = new BoxTaskAssignmentRequest() { Task = new BoxTaskRequest() { Id = "11111" }, AssignTo = new BoxAssignmentRequest() { Login = "user@example.com" } }; BoxTaskAssignment assignment = await client.TasksManager.CreateTaskAssignmentAsync(assignmentParams); ``` ## Get Task Assignment To retrieve information about a specific task assignment, call the `TasksManager.GetTaskAssignmentAsync(string taskAssignmentId)` method with the ID of the assignment to get. ``` BoxTaskAssignment assignment = await client.TasksManager.GetTaskAssignmentAsync("12345"); ``` ## Update Task Assignment To update a task assignment, call the `TasksManager.UpdateTaskAssignmentAsync(BoxTaskAssignmentUpdateRequest taskAssignmentUpdateRequest)` method. This can be used to resolve or complete a task. Updating the resolution state: ``` var requestParams = new BoxTaskAssignmentUpdateRequest() { Id = "12345", ResolutionState = ResolutionStateType.approved }; BoxTaskAssignment updatedAssignment = await client.TasksManager.UpdateTaskAssignmentAsync(requestParams); ``` Updating the message: ``` var requestParams = new BoxTaskAssignmentUpdateRequest() { Id = "12345", Message = "Updated message" }; BoxTaskAssignment updatedAssignment = await client.TasksManager.UpdateTaskAssignmentAsync(requestParams); ``` ## Remove Task Assignment To delete a task assignment, effectively unassigning a user from the task, call the `TasksManager.DeleteTaskAssignmentAsync(string taskAssignmentId)` method with the ID of the assignment to remove. ``` await client.TasksManager.DeleteTaskAssignmentAsync("12345"); ``` --- ### TasksManager **Type:** page | **Section:** Additional Resources TasksManager List tasks on file Create task Get task Update task Remove task List tasks on file Retrieves a list of all the tasks for a file… # TasksManager - [List tasks on file](#list-tasks-on-file) - [Create task](#create-task) - [Get task](#get-task) - [Update task](#update-task) - [Remove task](#remove-task) ## List tasks on file Retrieves a list of all the tasks for a file. This endpoint does not support pagination. This operation is performed by calling function `getFileTasks`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-files-id-tasks/). ``` await client.tasks.getFileTasks(file.id); ``` ### Arguments fileId `string` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" optionalsInput `GetFileTasksOptionalsInput` ### Returns This function returns a value of type `Tasks`. Returns a list of tasks on a file. If there are no tasks on this file an empty collection is returned instead. ## Create task Creates a single task on a file. This task is not assigned to any user and will need to be assigned separately. This operation is performed by calling function `createTask`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-tasks/). ``` await client.tasks.createTask({ item: { type: 'file' as CreateTaskRequestBodyItemTypeField, id: file.id, } satisfies CreateTaskRequestBodyItemField, message: 'test message', dueAt: dateTime, action: 'review' as CreateTaskRequestBodyActionField, completionRule: 'all_assignees' as CreateTaskRequestBodyCompletionRuleField, } satisfies CreateTaskRequestBody); ``` ### Arguments requestBody `CreateTaskRequestBody` - Request body of createTask method optionalsInput `CreateTaskOptionalsInput` ### Returns This function returns a value of type `Task`. Returns the newly created task. ## Get task Retrieves information about a specific task. This operation is performed by calling function `getTaskById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-tasks-id/). ``` await client.tasks.getTaskById(task.id!); ``` ### Arguments taskId `string` - The ID of the task. Example: "12345" optionalsInput `GetTaskByIdOptionalsInput` ### Returns This function returns a value of type `Task`. Returns a task object. ## Update task Updates a task. This can be used to update a task's configuration, or to update its completion state. This operation is performed by calling function `updateTaskById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-tasks-id/). ``` await client.tasks.updateTaskById(task.id!, { requestBody: { message: 'updated message', } satisfies UpdateTaskByIdRequestBody, } satisfies UpdateTaskByIdOptionalsInput); ``` ### Arguments taskId `string` - The ID of the task. Example: "12345" optionalsInput `UpdateTaskByIdOptionalsInput` ### Returns This function returns a value of type `Task`. Returns the updated task object. ## Remove task Removes a task from a file. This operation is performed by calling function `deleteTaskById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-tasks-id/). ``` await client.tasks.deleteTaskById(task.id!); ``` ### Arguments taskId `string` - The ID of the task. Example: "12345" optionalsInput `DeleteTaskByIdOptionalsInput` ### Returns This function returns a value of type `undefined`. Returns an empty response when the task was successfully deleted. --- ### TasksManager **Type:** page | **Section:** Additional Resources TasksManager List tasks on file Create task Get task Update task Remove task List tasks on file Retrieves a list of all the tasks for a file… # TasksManager - [List tasks on file](#list-tasks-on-file) - [Create task](#create-task) - [Get task](#get-task) - [Update task](#update-task) - [Remove task](#remove-task) ## List tasks on file Retrieves a list of all the tasks for a file. This endpoint does not support pagination. This operation is performed by calling function `get_file_tasks`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-files-id-tasks/). ``` client.tasks.get_file_tasks(file.id) ``` ### Arguments file_id `str` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `Tasks`. Returns a list of tasks on a file. If there are no tasks on this file an empty collection is returned instead. ## Create task Creates a single task on a file. This task is not assigned to any user and will need to be assigned separately. This operation is performed by calling function `create_task`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-tasks/). ``` client.tasks.create_task( CreateTaskItem(type=CreateTaskItemTypeField.FILE, id=file.id), action=CreateTaskAction.REVIEW, message="test message", due_at=date_time, completion_rule=CreateTaskCompletionRule.ALL_ASSIGNEES, ) ``` ### Arguments item `CreateTaskItem` - The file to attach the task to. action `Optional[CreateTaskAction]` - The action the task assignee will be prompted to do. Must be _ `review` defines an approval task that can be approved or, rejected _ `complete` defines a general task which can be completed. message `Optional[str]` - An optional message to include with the task. due_at `Optional[DateTime]` - Defines when the task is due. Defaults to `null` if not provided. completion_rule `Optional[CreateTaskCompletionRule]` - Defines which assignees need to complete this task before the task is considered completed. _ `all_assignees` (default) requires all assignees to review or approve the the task in order for it to be considered completed. _ `any_assignee` accepts any one assignee to review or approve the the task in order for it to be considered completed. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `Task`. Returns the newly created task. ## Get task Retrieves information about a specific task. This operation is performed by calling function `get_task_by_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-tasks-id/). ``` client.tasks.get_task_by_id(task.id) ``` ### Arguments task_id `str` - The ID of the task. Example: "12345" extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `Task`. Returns a task object. ## Update task Updates a task. This can be used to update a task's configuration, or to update its completion state. This operation is performed by calling function `update_task_by_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-tasks-id/). ``` client.tasks.update_task_by_id(task.id, message="updated message") ``` ### Arguments task_id `str` - The ID of the task. Example: "12345" action `Optional[UpdateTaskByIdAction]` - The action the task assignee will be prompted to do. Must be _ `review` defines an approval task that can be approved or rejected, _ `complete` defines a general task which can be completed. message `Optional[str]` - The message included with the task. due_at `Optional[DateTime]` - When the task is due at. completion_rule `Optional[UpdateTaskByIdCompletionRule]` - Defines which assignees need to complete this task before the task is considered completed. _ `all_assignees` (default) requires all assignees to review or approve the the task in order for it to be considered completed. _ `any_assignee` accepts any one assignee to review or approve the the task in order for it to be considered completed. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `Task`. Returns the updated task object. ## Remove task Removes a task from a file. This operation is performed by calling function `delete_task_by_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-tasks-id/). ``` client.tasks.delete_task_by_id(task.id) ``` ### Arguments task_id `str` - The ID of the task. Example: "12345" extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `None`. Returns an empty response when the task was successfully deleted. --- ### Terms of Service **Type:** page | **Section:** Additional Resources Terms of Service Terms of Service are custom objects that the admin of an enterprise can configure. This will prompt the end user to accept… # Terms of Service Terms of Service are custom objects that the admin of an enterprise can configure. This will prompt the end user to accept/re-accept or decline the custom Terms of Service for platform applications built on Box Platform. [Terms of Service](#terms-of-service) - [Get Terms of Service for an Enterprise](#get-terms-of-service-for-an-enterprise) - [Get a Terms of Service By ID](#get-a-terms-of-service-by-id) - [Update a Terms of Service for an Enterprise](#update-a-terms-of-service-for-an-enterprise) - [Create a Terms of Service for an Enterprise](#create-a-terms-of-service-for-an-enterprise) - [Get Terms of Service Status for User](#get-terms-of-service-status-for-user) - [Create User Status on Terms of Service](#create-user-status-on-terms-of-service) - [Update User Status on Terms of Service](#update-user-status-on-terms-of-service) - [Accept or Decline a Terms of Service](#accept-or-decline-a-terms-of-service) ## Get Terms of Service for an Enterprise To get terms of service call the [`termsOfService.getAll(options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/TermsOfService.html#getAll) method. ``` client.termsOfService.getAll() .then(termsOfService => { /* termsOfService -> { entries: [ total_count: 1, { type: 'terms_of_service', id: '12345', status: 'disabled', enterprise: { type: 'enterprise', id: '55555' }, tos_type: 'managed', text: 'By using this service, you agree to ...', created_at: '2018-04-19T13:55:09-07:00', modified_at: '2018-04-19T13:55:09-07:00' } ] */ }); ``` Alternatively, you can specify the Terms of Service type. You can either specify "managed" or "external". This field specifies the type of user the Terms of Service applies to. ``` client.termsOfService.getAll({ tos_type: 'managed' }) .then(termsOfService => { /* termsOfService -> { entries: [ total_count: 1, { type: 'terms_of_service', id: '12345', status: 'disabled', enterprise: { type: 'enterprise', id: '55555' }, tos_type: 'managed', text: 'By using this service, you agree to ...', created_at: '2018-04-19T13:55:09-07:00', modified_at: '2018-04-19T13:55:09-07:00' } ] */ }); ``` ## Get a Terms of Service By ID To get the terms of service with an ID call the [`termsOfService.get(termsOfServicesID, options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/TermsOfService.html#get) method. ``` client.termsOfService.get('12345') .then(tos => { /* tos -> { type: 'terms_of_service', id: '12345', status: 'disabled', enterprise: { type: 'enterprise', id: '55555' }, tos_type: 'managed', text: 'By using this service, you agree to ...', created_at: '2018-04-19T13:55:09-07:00', modified_at: '2018-04-19T13:55:09-07:00' } */ }); ``` ## Update a Terms of Service for an Enterprise To update a terms of service call the [`termsOfService.update(termsOfServicesID, updates, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/TermsOfService.html#update) method with the fields to update and their new values. ``` client.termsOfService.update('12345', { status: 'disabled' }) .then(tos => { /* tos -> { type: 'terms_of_service', id: '12345', status: 'disabled', enterprise: { type: 'enterprise', id: '55555' }, tos_type: 'managed', text: 'By using this service, you agree to ...', created_at: '2018-04-19T13:55:09-07:00', modified_at: '2018-04-19T13:55:09-07:00' } */ }); ``` The termsOfServicesStatus can be set to 'enabled' or 'disabled'. You can also specify the conditions of the terms of service in the termsOfServicesText parameter. ## Create a Terms of Service for an Enterprise To create a terms of service call the [`termsOfService.create(termsOfServicesType, termsOfServicesStatus, termsOfServicesText, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/TermsOfService.html#create) method. **Note:** Only two terms of service can exist per enterprise: one managed terms of service and one external terms of service. If you wish to have a different terms of service, update one of the existing terms of service. ``` client.termsOfService.create('managed', 'enabled', 'By using this service, you agree to ...') .then(tos => { /* tos -> { type: 'terms_of_service', id: '12345', status: 'enabled', enterprise: { type: 'enterprise', id: '55555' }, tos_type: 'managed', text: 'By using this service, you agree to ...', created_at: '2018-04-19T13:55:09-07:00', modified_at: '2018-04-19T13:55:09-07:00' } */ }); ``` ``` client.termsOfService.create('external', 'disabled', 'This is a new terms of service but disabled') .then(tos => { /* tos -> { type: 'terms_of_service', id: '12346', status: 'disabled', enterprise: { type: 'enterprise', id: '55555' }, tos_type: 'external', text: 'This is a new terms of service but disabled', created_at: '2018-04-19T13:55:09-07:00', modified_at: '2018-04-19T13:55:09-07:00' } */ }); ``` ## Get Terms of Service Status for User To get user status on a terms of service call the [`termsOfService.getUserStatus(termsOfStatusID, options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/TermsOfService.html#getUserStatus) method. If no `user_id` option is specified, this will default to current user. ``` client.termsOfService.getUserStatus('11111', { user_id: '22222' }) .then(tosStatus => { /* tosStatus -> { type: 'terms_of_service_user_status', id: '12345', tos: { type: 'terms_of_service', id: '11111' }, user: { type: 'user', id: '22222' }, is_accepted: true, created_at: '2018-04-11T15:33:49-07:00', modified_at: '2018-04-11T15:33:49-07:00' } */ }); ``` ## Create User Status on Terms of Service To accept or decline a terms of service for a user who has never accepted/decline this terms of service before call the [`termsOfService.createUserStatus(termsOfServicesID, isAccepted, options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/TermsOfService.html#createUserStatus) method. ``` client.termsOfService.createUserStatus('11111', true, {user_id: '22222'}) .then(tosStatus => { /* tosStatus -> { type: 'terms_of_service_user_status', id: '12345', tos: { type: 'terms_of_service', id: '11111' }, user: { type: 'user', id: '22222' }, is_accepted: true, created_at: '2018-04-11T15:33:49-07:00', modified_at: '2018-04-11T15:33:49-07:00' } */ }); ``` It is important to note that this will accept or decline a custom terms of service for a user that has never taken action on this terms of service before. For a user that has, this will return a 409 Conflict Error. If no user is specified, this will default to current user. ## Update User Status on Terms of Service To update user status on a terms of service call the [`termsOfService.updateUserStatus(termsOfServiceUserStatusID, isAccepted, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/TermsOfService.html#updateUserStatus) method. ``` client.termsOfService.updateUserStatus('5678', false) .then(tosStatus => { /* tosStatus -> { type: 'terms_of_service_user_status', id: '12345', tos: { type: 'terms_of_service', id: '11111' }, user: { type: 'user', id: '22222' }, is_accepted: false, created_at: '2018-04-11T15:33:49-07:00', modified_at: '2018-04-11T15:33:49-07:00' } */ }); ``` It is important to note that this will accept or decline a custom terms of service for a user. For a user that has taken action in this terms of service, this will update their status. If the user has never taken action on this terms of service then this will return a 404 Not Found Error. ## Accept or Decline a Terms of Service To create user/terms of service association and accept/decline call the [`termsOfService.setUserStatus(termsOfServicesID, isAccepted, options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/TermsOfService.html#setUserStatus)) method. ``` client.termsOfService.setUserStatus('1234', true, { user_id: '5678' }, callback); ) ``` It is important to note that regardless of whether the user has taken action on this terms of service. This will create and update the user status on the terms of service. --- ### Terms of Service **Type:** page | **Section:** Additional Resources Terms of Service Terms of Service allows Box Admins to configure a custom Terms of Service for end users to accept/re-accept/decline for… # Terms of Service Terms of Service allows Box Admins to configure a custom Terms of Service for end users to accept/re-accept/decline for platform applications [Terms of Service](#terms-of-service) - [Create a Terms of Service](#create-a-terms-of-service) - [Edit a Terms of Service](#edit-a-terms-of-service) - [Get a Terms of Service](#get-a-terms-of-service) - [Get All Terms of Services](#get-all-terms-of-services) - [Accept or Decline a Terms of Service for New User](#accept-or-decline-a-terms-of-service-for-new-user) - [Accept or Decline a Terms of Service for Existing User](#accept-or-decline-a-terms-of-service-for-existing-user) - [Get User Status on a Terms of Service](#get-user-status-on-a-terms-of-service) ## Create a Terms of Service A terms of service can be created in an enterprise. Please note that only two can be created. One external and one managed. If a terms of service already exists please use the update call to change the current terms of service. You can create a custom terms of service by calling [`create(BoxAPIConnection api, BoxTermsOfService.TermsOfServiceStatus status, BoxTermsOfService.TermsOfServiceType type, String text)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxTermsOfService.html#create-com.box.sdk.BoxAPIConnection-com.box.sdk.BoxTermsOfService.TermsOfServiceStatus-com.box.sdk.BoxTermsOfService.TermsOfServiceType-java.lang.String-). ``` BoxTermsOfService.Info newTOS = BoxTermsOfService.create( api, BoxTermsOfService.TermsOfServiceStatus.ENABLED, BoxTermsOfService.TermsOfServiceType.EXTERNAL, "Terms of Service..." ); ``` ## Edit a Terms of Service You can update a terms of service status and text after you have created them by calling [`updateInfo(BoxTermsOfService.Info fieldsToUpdate)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxTermsOfService.html#updateInfo-com.box.sdk.BoxTermsOfService.Info-) ``` BoxTermsOfService termsOfService = new BoxTermsOfService(api, "tos-id"); BoxTermsOfService.Info termsOfServiceInfo = termsOfService.new Info(); termsOfServiceInfo.setStatus(BoxTermsOfService.TermsOfServiceStatus.DISABLED); termsOfServiceInfo.setText("New Terms of Service Text"); termsOfService.updateInfo(termsOfService); ``` ## Get a Terms of Service You can retrieve a terms of service by providing the ID and calling [`getInfo()`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxTermsOfService.html#getInfo--). ``` BoxTermsOfService termsOfService = new BoxTermsOfService(api, "tos-id"); BoxTermsOfService.Info tosInfo = termsOfService.getInfo(); ``` ## Get All Terms of Services You can also retrieve all terms of service in your enterprise by calling [`getAllTermsOfServices(BoxAPIConnection api)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxTermsOfService.html#getAllTermsOfServices-com.box.sdk.BoxAPIConnection-). This will return an iterable that will page through all of the enterprises terms of services. ``` List<BoxTermsOfService.Info> termsOfServices = BoxTermsOfService.getAllTermsOfServices(api); for(BoxTermsOfService.Info termsOfServiceInfo : termsOfServices){ // Do something with the terms of service. } ``` You can also filter by managed or external terms of service by calling [`getAllTermsOfServices(BoxAPIConnection api, BoxTermsOfService.TermsOfServiceType type)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxTermsOfService.html#getAllTermsOfServices-com.box.sdk.BoxAPIConnection-com.box.sdk.BoxTermsOfService.TermsOfServiceType-). ## Accept or Decline a Terms of Service for New User For new users you can accept or decline a terms of service by calling [`create(BoxAPIConnection api, String tosID, Boolean accepted, String userID)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxTermsOfServiceUserStatus.html#create-com.box.sdk.BoxAPIConnection-java.lang.String-java.lang.Boolean-java.lang.String-) ``` BoxTermsOfService.Info newUserStatus = BoxTermsOfServiceUserStatus.create(api, "tos-id", true, "user-id"); ``` You can only create a new user status on a terms of service if the user has never accepted/declined a terms of service. If they have then you will need to make the update call. ## Accept or Decline a Terms of Service for Existing User For an existing user you can accept or decline a terms of service by calling [`updateInfo(BoxTermsOfService.Info fieldsToUpdate)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxTermsOfServiceUserStatus.html#updateInfo-com.box.sdk.BoxTermsOfServiceUserStatus.Info-). ``` BoxTermsOfServiceUserStatus tosUserStatus = new BoxTermsOfServiceUserStatus(api, "tos-user-status-id"); BoxTermOfServiceUserStatus.Info tosUserStatusInfo = tosUserStatus.new Info(); tosUserStatusInfo.setStatus(newStatus); tosUserStatus.updateInfo(tosUSerStatusInfo); ``` ## Get User Status on a Terms of Service You can retrieve the terms of service status for a user by calling [`getInfo(BoxAPIConnection api, String tosID, String userID)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxTermsOfServiceUserStatus.html#getInfo-com.box.sdk.BoxAPIConnection-java.lang.String-) ``` List<BoxTermsOfServiceUserStatus.Info> tosUserStatusInfo = BoxTermsOfServiceUserStatus.getInfo(api, "tos-id", "user-id"); for(BoxTermsOfServiceUserStatus.Info info : toUserStatusInfo){ // Do something with the user status on terms of service. } ``` Alternatively you can get the user status by the ID of the terms of service by calling [`getInfo(BoxAPIConnection api, String tosID)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxTermsOfServiceUserStatus.html#getInfo-com.box.sdk.BoxAPIConnection-java.lang.String-java.lang.String-). ``` List<BoxTermsOfServiceUserStatus.Info> tosUserStatusInfo = BoxTermsOfServiceUserStatus.getInfo(api, "tos-id"); for(BoxTermsOfServiceUserStatus.Info info : toUserStatusInfo){ // Do something with the user status on terms of service. } ``` --- ### Terms of Service **Type:** page | **Section:** Additional Resources Terms of Service Terms of Service allows Box Admins to configure a custom Terms of Service for end users to accept/re-accept/decline for… # Terms of Service Terms of Service allows Box Admins to configure a custom Terms of Service for end users to accept/re-accept/decline for platform applications [Terms of Service](#terms-of-service) - [Create a Terms of Service](#create-a-terms-of-service) - [Edit a Terms of Service](#edit-a-terms-of-service) - [Get Terms of Service](#get-terms-of-service) - [List Terms of Service](#list-terms-of-service) - [Accept or Decline a Terms of Service](#accept-or-decline-a-terms-of-service) - [Get User Status for a Terms of Service](#get-user-status-for-a-terms-of-service) ## Create a Terms of Service A Terms of Service can be created in an enterprise. Please note that only two can be created. One external and one managed. If a terms of service already exists please use the update call to change the current terms of service. To create a Terms of Service object, calling [`client.create_terms_of_service(status, tos_type, text)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.client.html#boxsdk.client.client.Client.create_terms_of_service) will let you create a new [`TermsOfService`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.terms_of_service.TermsOfService) object with the specified status, type, and text. This method will return a newly created [`TermsOfService`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.terms_of_service.TermsOfService) object populated with data from the API. ``` from boxsdk.object.terms_of_service import TermsOfServiceType, TermsOfServiceStatus terms_of_service = client.create_terms_of_service(TermsOfServiceStatus.ENABLED,TermsOfServiceType.MANAGED, 'Example Text') print(f'Terms of Service status is {terms_of_service.status} and the message is {terms_of_service.text}') ``` ## Edit a Terms of Service To update a terms of service object, first call [`terms_of_service.update_info(data=update_object)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.base_object.BaseObject.update_info) with a `dict` of properties to update on the terms of service. This method returns a newly updated [`TermsOfService`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.client.html#boxsdk.client.client.Client.terms_of_service) object, leaving the original object unmodified. ``` update_object = {'text': 'New Text'} updated_tos = client.terms_of_service(tos_id='12345').update_info(data=update_object) print(f'The updated message for your custom terms of service is {updated_tos.text} with ID {updated_tos.id}') ``` ## Get Terms of Service To get a terms of service object, call [`client.terms_of_service(service_id)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.client.html#boxsdk.client.client.Client.terms_of_service) to construct the appropriate [`TermsOfService`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.terms_of_service.TermsOfService), and then calling [`terms_of_service.get(*, fields=None, headers=None, **kwargs)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.base_object.BaseObject.get) will return the [`TermsOfService`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.terms_of_service.TermsOfService) object populated with data from the API. ``` terms_of_service = client.terms_of_service(tos_id='12345').get() print(f'Terms of Service ID is {terms_of_service.id} and the message is {terms_of_service.text}') ``` ## List Terms of Service To retrieve all terms of service for an enterprise, call [`client.get_terms_of_services(limit=None, marker=None, fields=None)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.client.html#boxsdk.client.client.Client.terms_of_service). This method returns a `BoxObjectCollection` that allows you to iterate over the [`TermOfService`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.terms_of_service.TermsOfService) objects in the collection. ``` terms_of_services = client.get_terms_of_services() for terms_of_service in terms_of_services: print(f'Terms of Service ID is {terms_of_service.id} and the message is {terms_of_service.text}') ``` ## Accept or Decline a Terms of Service To accept or decline a terms of service, calling [`terms_of_service.set_user_status(is_accepted, user)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.terms_of_service.TermsOfService.set_user_status) will allow you to create a newly updated [`TermsOfServiceUserStatus`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.terms_of_service_user_status.TermsOfServiceUserStatus) object populated with data from the API, leaving the original object umodified if a [`TermsOfService`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.terms_of_service.TermsOfService) object already exists for a user. If the user does not have a [`TermsOfService`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.terms_of_service.TermsOfService) object assigned then [`terms_of_service.set_user_status(is_accepted, user)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.terms_of_service.TermsOfService.set_user_status) will create a new [`TermsOfServiceUserStatus`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.terms_of_service_user_status.TermsOfServiceUserStatus) object populated with data from the API. ``` user = client.user(user_id='22222') user_status = client.terms_of_service(tos_id='12345').set_user_status(is_accepted=True, user=user) print(f'User status ID is {user_status.id} and the accepted status is {user_status.is_accepted}') ``` It is important to note that regardless of whether the user has taken action on this terms of service. This will create and update the user status on the terms of service. Note that this example will make multiple API calls, if you know that your user has already accepted or decline a Terms of Service and you wish to change their status, call [`terms_of_service_user_status.update_info(data=data_to_update)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.base_object.BaseObject.update_info) with a `dict` of properties to update on the terms of service user status. This method returns a newly updated [`TermsOfServiceUserStatus`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.terms_of_service_user_status.TermsOfServiceUserStatus) object, leaving the original object unmodified. ``` user_status = client.terms_of_service_user_status(tos_user_status_id='12345').update_info(data={'is_accepted': True}) print(f'Terms of Service User Status ID is {user_status.id} and the accepted status is {user_status.is_accepted}') ``` It is important to note that this will accept or decline a custom terms of service for a user. For a user that has taken action in this terms of service, this will update their status. If the user has never taken action on this terms of service then this will return a 404 Not Found Error. ## Get User Status for a Terms of Service To get a terms of service user status object, first call [`client.terms_of_service_user_status(status_id)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.client.Client.terms_of_service_user_status) to construct the appropriate [`TermsOfServiceUserStatus`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.terms_of_service_user_status.TermsOfServiceUserStatus) object. Then calling [`client.user(user_id)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.client.html#boxsdk.client.client.Client.user) to construct the user you wish to retrieve a [`TermsOfServiceUserStatus`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.terms_of_service_user_status.TermsOfServiceUserStatus) object for. Finally, calling [`terms_of_service_user_status.get(*, fields=None, headers=None, **kwargs)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.base_object.BaseObject.get) will return the [`TermsOfServiceUserStatus`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.terms_of_service_user_status.TermsOfServiceUserStatus) object populated with data from the API. ``` user = client.user(user_id='11111') user_status = client.terms_of_service(tos_id='12345').get_user_status(user) print(f'User status ID is {user_status.id} and the accepted status is {user_status.is_accepted}') ``` --- ### Terms of Service **Type:** page | **Section:** Additional Resources Terms of Service Terms of Service are custom objects that the admin of an enterprise can configure. This will prompt the end user to accept… # Terms of Service Terms of Service are custom objects that the admin of an enterprise can configure. This will prompt the end user to accept/re-accept or decline the custom Terms of Service for platform applications built on Box Platform. [Terms of Service](#terms-of-service) - [Create a Terms of Service for an Enterprise](#create-a-terms-of-service-for-an-enterprise) - [Update a Terms of Service for an Enterprise](#update-a-terms-of-service-for-an-enterprise) - [Get a Terms of Service By ID](#get-a-terms-of-service-by-id) - [Get Terms of Service for an Enterprise](#get-terms-of-service-for-an-enterprise) - [Create User Status on Terms of Service](#create-user-status-on-terms-of-service) - [Update User Status on Terms of Service](#update-user-status-on-terms-of-service) - [Get Terms of Service Status for User](#get-terms-of-service-status-for-user) ## Create a Terms of Service for an Enterprise To create a terms of service call the `TermsOfServiceManager.CreateTermsOfServicesAsync(BoxTermsOfServicesRequest termsOfServicesRequest)` method with the parameters for the new terms of service. ``` var tosParams = new CreateTermsOfServicesAsync() { Status = "enabled" TosType = "external", Text = "By using this service, you agree to ..." }; BoxTermsOfService tos = await client.TermsOfServiceManager.CreateTermsOfServicesAsync(tosParams); ``` ## Update a Terms of Service for an Enterprise To update a terms of service call `TermsOfServiceManager.UpdateTermsOfServicesAsync(string tosId, BoxTermsOfServicesRequest termsOfServicesRequest)` method with the fields to update and their new values. ``` var updates = new BoxTermsOfServicesRequest() { Status = "disabled", Text = "Updated Text" }; BoxTermsOfService updatedToS = client.TermsOfServiceManager .UpdateTermsOfServicesAsync("11111", updates); ``` ## Get a Terms of Service By ID To get the terms of service with an ID call `TermsOfServiceManager.GetTermsOfServicesByIdAsync(string tosId)` with the ID of the terms of service object. ``` BoxTermsOfService tos = await client.TermsOfServiceManager.GetTermsOfServicesByIdAsync("11111"); ``` ## Get Terms of Service for an Enterprise To get the terms of service for an enterprise, call `TermsOfServiceManager.GetTermsOfServicesAsync(string tosType = null)`. ``` BoxTermsOfServiceCollection<BoxTermsOfService> termsOfService = await client.TermsOfServiceManager .GetTermsOfServicesAsync(); ``` ## Create User Status on Terms of Service For create user status on a terms of service call the `TermsOfServiceManager.CreateBoxTermsOfServiceUserStatusesAsync(BoxTermsOfServiceUserStatusCreateRequest termsOfServiceUserStatusCreateRequest)` You can only create a user status on a terms of service if the user has never accepted/declined a terms of service. If they have then you will need to make the update call.. ``` var createStatusRequest = new BoxTermsOfServiceUserStatusCreateRequest() { TermsOfService = new BoxRequestEntity() { Id = "11111", Type = BoxType.terms_of_service }, User = new BoxRequestEntity() { Id = "22222", Type = BoxType.user }, IsAccepted = true }; BoxTermsOfServiceUserStatuses termsOfServiceUserStatuses = await client.TermsOfServiceManager.CreateBoxTermsOfServiceUserStatusesAsync(createStatusRequest); ``` ## Update User Status on Terms of Service To update user status on a terms of service call the `TermsOfServiceManager.UpdateTermsofServiceUserStatusesAsync(string tosId, bool isAccepted)` method with the ID of the status object, and the new acceptance value for the user. It is important to note that this will accept or decline a custom terms of service for a user. For a user that has taken action in this terms of service, this will update their status. If the user has never taken action on this terms of service then this will return a 404 Not Found error. ``` BoxTermsOfServiceUserStatuses updatedStatus = await client.TermsOfServiceManager .UpdateTermsofServiceUserStatusesAsync("12345", false); ``` ## Get Terms of Service Status for User To get user status on a terms of service call the `TermsOfServiceManager.GetTermsOfServiceUserStatusesAsync(string tosId, String userId = null)` method with the ID of the terms of service. If no user ID is provided, the method defaults to the current user. ``` BoxTermsOfServiceUserStatusesCollection<BoxTermsOfServiceUserStatuses> tosStatuses = await client.TermsOfServiceManager .GetTermsOfServiceUserStatusesAsync(tosId: "11111", userId: "22222"); ``` --- ### Terms of Services **Type:** page | **Section:** Additional Resources Terms of Services Terms of Service are custom objects that the admin of an enterprise can configure. This will prompt the end user to accept… # Terms of Services Terms of Service are custom objects that the admin of an enterprise can configure. This will prompt the end user to accept/re-accept or decline the custom Terms of Service for custom applications built on Box Platform. - [Get Terms of Service By ID](#get-terms-of-service-by-id) - [Create Terms of Service](#create-terms-of-service) - [Update Terms of Service](#update-terms-of-service) - [List Terms of Services for an Enterprise](#list-terms-of-services-for-an-enterprise) - [Create User Status on Terms of Service](#create-user-status-on-terms-of-service) - [Update User Status of Terms of Service](#update-user-status-of-terms-of-service) - [Get User Status for Terms of Service](#get-user-status-for-terms-of-service) ## Get Terms of Service By ID To retrieve information about a terms of service, call [`client.termsOfService.get(tosId:fields:completion)`](https://opensource.box.com/box-ios-sdk/Classes/TermsOfServicesModule.html#/s:6BoxSDK21TermsOfServicesModuleC3get5tosId6fields10completionySS_SaySSGSgys6ResultOyAA0cD7ServiceCAA0A8SDKErrorCGctF) with the ID of the terms of service. You can control which fields are returned in the resulting `Terms of Service` object by passing the `fields` parameter. ``` client.termsOfService.get( tosID: "12345" ) { (result: Result<TermsOfService, BoxSDKError>) in guard case let .success(termsOfService) = result else { print("Error getting terms of service information") return } print("Terms of Service with id: \(termsOfService.id) was retrieved") } ``` ## Create Terms of Service To create a terms of service, call [`client.termsOfService.create(status:tosType:text:fields:completion`](https://opensource.box.com/box-ios-sdk/Classes/TermsOfServicesModule.html#/s:6BoxSDK21TermsOfServicesModuleC6create6status7tosType4text6fields10completionyAA0cD13ServiceStatusO_AA0cdnJ0OSSSaySSGSgys6ResultOyAA0cdN0CAA0A8SDKErrorCGctF). You can control which fields are returned in the resulting `Terms of Service` object by passing the `fields` parameter. ``` client.termsOfService.create( status: .enabled, tosType: .managed, text: "Test Terms of Service" ) { (result: Result<TermsOfService, BoxSDKError>) in guard case let .success(termsOfService) = result else { print("Error creating terms of service") return } print("Terms of Service with id: \(termsOfService.id) was created") } ``` ## Update Terms of Service To update a terms of service, call [`client.termsOfService.update(tosId:text:status:fields:completion)`](https://opensource.box.com/box-ios-sdk/Classes/TermsOfServicesModule.html#/s:6BoxSDK21TermsOfServicesModuleC6update5tosId4text6status6fields10completionySS_SSAA0cD13ServiceStatusOSaySSGSgys6ResultOyAA0cdN0CAA0A8SDKErrorCGctF) with the ID of the terms of service to update. You can control which fields are returned in the resulting `Terms of Service` object by passing the `fields` parameter. ``` client.termsOfService.update( tosId: "12345", text: "Updated Text String", status: TermsOfServiceStatus.enabled ) { (result: Result<TermsOfService, BoxSDKError>) in guard calse let .success(termsOfService) = result else { print("Error updating terms of service") return } print("Terms of Service with id: \(termsOfService.id) was updated with text: \(termsOfService.text)") } ``` ## List Terms of Services for an Enterprise To retrieve a list of terms of services for an enterprise, call [`client.termsOfService.listForEnterprise(tosType:fields:completion)`](https://opensource.box.com/box-ios-sdk/Classes/TermsOfServicesModule.html#/s:6BoxSDK21TermsOfServicesModuleC17listForEnterprise7tosType6fields10completionyAA0cd7ServiceK0OSg_SaySSGSgys6ResultOySayAA0cdN0CGAA0A8SDKErrorCGctF) with the type of terms of service to retrieve. If left nil, then terms of services of both types, `managed` and `external` will be retrieved. You can control which fields are returned in the resulting `Terms of Service` objects by passing the `fields` parameter. ``` let termsOfServiceItems = client.termsOfService.listForEnterprise() print("Terms of Service with ID \(termsOfServiceItems[0].id) and Terms of Service with ID \(termsOfServiceItems[1].id) was retrieved.") ``` ## Create User Status on Terms of Service To accept or decline a terms of service for a user who has never accepted/declined this terms of service before call [`client.termsOfService.createUserStatus(tosId:isAccepted:userId:fields:completion)`](https://opensource.box.com/box-ios-sdk/Classes/TermsOfServicesModule.html#/s:6BoxSDK21TermsOfServicesModuleC16createUserStatus5tosId10isAccepted04userK06fields10completionySS_SbSSSgSaySSGSgys6ResultOyAA0cd7ServicehI0CAA0A8SDKErrorCGctF). You can control which fields are returned in the resulting `Terms of Service User Status` object by passing the `fields` parameter. ``` client.termsOfService.createUserStatus( tosId: "12345", isAccepted: true, userId: "54321" ) { (result: Result<TermsOfServiceUserStatus, BoxSDKError>) in guard case let .success(userStatus) = result else { print("Error accepting Terms of Service for new user") return } print("User status for accepting of Terms of Service is \(userStatus.isAccepted)") } ``` ## Update User Status of Terms of Service To update a user status on a terms of service call [`client.termsOfService.updateUserStatus(userStatusId:isAccepted:fields:completion)`](https://opensource.box.com/box-ios-sdk/Classes/TermsOfServicesModule.html#/s:6BoxSDK21TermsOfServicesModuleC16updateUserStatus04userI2Id10isAccepted6fields10completionySS_SbSaySSGSgys6ResultOyAA0cd7ServicehI0CAA0A8SDKErrorCGctF). You can control which fields are returned in the resulting `Terms of Service User Status` object by passing the `fields` parameter. ``` client.termsOfService.updateUserStatus( userStatusId: "12345", isAccepted: true ) { (result: Result<TermsOfServiceUserStatus, BoxSDKError>) in guard case let .success(userStatus) = result else { print("Error updating Terms of Service User Status") return } print("User status for updating of Terms of Service is \(userStatus.isAccepted)") } ``` ## Get User Status for Terms of Service To retrieve the user status for a user on a terms of service, call [`client.termsOfService.getUserStatus(tosId:userId:fields:completion)`](https://opensource.box.com/box-ios-sdk/Classes/TermsOfServicesModule.html#/s:6BoxSDK21TermsOfServicesModuleC13getUserStatus5tosId04userK06fields10completionySS_SSSgSaySSGSgys6ResultOyAA0cd7ServicehI0CAA0A8SDKErrorCGctF) with the ID of the `Terms of Service` object and the ID of the user. ``` client.termsOfService.getUserStatus( tosId: "12345", userId: "54321" ) { (result: Result<TermsOfServiceUserStatus, BoxSDKError>) in guard case let .success(userStatus) = result else { print("Error retrieving user status for Terms of Service") return } print("User status with ID \(userStatus.id) was retrieved") } ``` --- ### Terms of Services **Type:** page | **Section:** Additional Resources Terms of Services Terms of Service are custom objects that the admin of an enterprise can configure. This will prompt the end user to accept… # Terms of Services Terms of Service are custom objects that the admin of an enterprise can configure. This will prompt the end user to accept/re-accept or decline the custom Terms of Service for custom applications built on Box Platform. - [Get Terms of Service By ID](#get-terms-of-service-by-id) - [Create Terms of Service](#create-terms-of-service) - [Update Terms of Service](#update-terms-of-service) - [List Terms of Services for an Enterprise](#list-terms-of-services-for-an-enterprise) - [Create User Status on Terms of Service](#create-user-status-on-terms-of-service) - [Update User Status of Terms of Service](#update-user-status-of-terms-of-service) - [Get User Status for Terms of Service](#get-user-status-for-terms-of-service) ## Get Terms of Service By ID To retrieve information about a terms of service, call [`client.termsOfService.get(tosId:fields:completion)`](https://opensource.box.com/box-ios-sdk/Classes/TermsOfServicesModule.html#/s:6BoxSDK21TermsOfServicesModuleC3get5tosId6fields10completionySS_SaySSGSgys6ResultOyAA0cD7ServiceCAA0A8SDKErrorCGctF) with the ID of the terms of service. You can control which fields are returned in the resulting `Terms of Service` object by passing the `fields` parameter. ``` client.termsOfService.get( tosID: "12345" ) { (result: Result<TermsOfService, BoxSDKError>) in guard case let .success(termsOfService) = result else { print("Error getting terms of service information") return } print("Terms of Service with id: \(termsOfService.id) was retrieved") } ``` ## Create Terms of Service To create a terms of service, call [`client.termsOfService.create(status:tosType:text:fields:completion`](https://opensource.box.com/box-ios-sdk/Classes/TermsOfServicesModule.html#/s:6BoxSDK21TermsOfServicesModuleC6create6status7tosType4text6fields10completionyAA0cD13ServiceStatusO_AA0cdnJ0OSSSaySSGSgys6ResultOyAA0cdN0CAA0A8SDKErrorCGctF). You can control which fields are returned in the resulting `Terms of Service` object by passing the `fields` parameter. ``` client.termsOfService.create( status: .enabled, tosType: .managed, text: "Test Terms of Service" ) { (result: Result<TermsOfService, BoxSDKError>) in guard case let .success(termsOfService) = result else { print("Error creating terms of service") return } print("Terms of Service with id: \(termsOfService.id) was created") } ``` ## Update Terms of Service To update a terms of service, call [`client.termsOfService.update(tosId:text:status:fields:completion)`](https://opensource.box.com/box-ios-sdk/Classes/TermsOfServicesModule.html#/s:6BoxSDK21TermsOfServicesModuleC6update5tosId4text6status6fields10completionySS_SSAA0cD13ServiceStatusOSaySSGSgys6ResultOyAA0cdN0CAA0A8SDKErrorCGctF) with the ID of the terms of service to update. You can control which fields are returned in the resulting `Terms of Service` object by passing the `fields` parameter. ``` client.termsOfService.update( tosId: "12345", text: "Updated Text String", status: TermsOfServiceStatus.enabled ) { (result: Result<TermsOfService, BoxSDKError>) in guard calse let .success(termsOfService) = result else { print("Error updating terms of service") return } print("Terms of Service with id: \(termsOfService.id) was updated with text: \(termsOfService.text)") } ``` ## List Terms of Services for an Enterprise To retrieve a list of terms of services for an enterprise, call [`client.termsOfService.listForEnterprise(tosType:fields:completion)`](https://opensource.box.com/box-ios-sdk/Classes/TermsOfServicesModule.html#/s:6BoxSDK21TermsOfServicesModuleC17listForEnterprise7tosType6fields10completionyAA0cd7ServiceK0OSg_SaySSGSgys6ResultOySayAA0cdN0CGAA0A8SDKErrorCGctF) with the type of terms of service to retrieve. If left nil, then terms of services of both types, `managed` and `external` will be retrieved. You can control which fields are returned in the resulting `Terms of Service` objects by passing the `fields` parameter. ``` let termsOfServiceItems = client.termsOfService.listForEnterprise() print("Terms of Service with ID \(termsOfServiceItems[0].id) and Terms of Service with ID \(termsOfServiceItems[1].id) was retrieved.") ``` ## Create User Status on Terms of Service To accept or decline a terms of service for a user who has never accepted/declined this terms of service before call [`client.termsOfService.createUserStatus(tosId:isAccepted:userId:fields:completion)`](https://opensource.box.com/box-ios-sdk/Classes/TermsOfServicesModule.html#/s:6BoxSDK21TermsOfServicesModuleC16createUserStatus5tosId10isAccepted04userK06fields10completionySS_SbSSSgSaySSGSgys6ResultOyAA0cd7ServicehI0CAA0A8SDKErrorCGctF). You can control which fields are returned in the resulting `Terms of Service User Status` object by passing the `fields` parameter. ``` client.termsOfService.createUserStatus( tosId: "12345", isAccepted: true, userId: "54321" ) { (result: Result<TermsOfServiceUserStatus, BoxSDKError>) in guard case let .success(userStatus) = result else { print("Error accepting Terms of Service for new user") return } print("User status for accepting of Terms of Service is \(userStatus.isAccepted)") } ``` ## Update User Status of Terms of Service To update a user status on a terms of service call [`client.termsOfService.updateUserStatus(userStatusId:isAccepted:fields:completion)`](https://opensource.box.com/box-ios-sdk/Classes/TermsOfServicesModule.html#/s:6BoxSDK21TermsOfServicesModuleC16updateUserStatus04userI2Id10isAccepted6fields10completionySS_SbSaySSGSgys6ResultOyAA0cd7ServicehI0CAA0A8SDKErrorCGctF). You can control which fields are returned in the resulting `Terms of Service User Status` object by passing the `fields` parameter. ``` client.termsOfService.updateUserStatus( userStatusId: "12345", isAccepted: true ) { (result: Result<TermsOfServiceUserStatus, BoxSDKError>) in guard case let .success(userStatus) = result else { print("Error updating Terms of Service User Status") return } print("User status for updating of Terms of Service is \(userStatus.isAccepted)") } ``` ## Get User Status for Terms of Service To retrieve the user status for a user on a terms of service, call [`client.termsOfService.getUserStatus(tosId:userId:fields:completion)`](https://opensource.box.com/box-ios-sdk/Classes/TermsOfServicesModule.html#/s:6BoxSDK21TermsOfServicesModuleC13getUserStatus5tosId04userK06fields10completionySS_SSSgSaySSGSgys6ResultOyAA0cd7ServicehI0CAA0A8SDKErrorCGctF) with the ID of the `Terms of Service` object and the ID of the user. ``` client.termsOfService.getUserStatus( tosId: "12345", userId: "54321" ) { (result: Result<TermsOfServiceUserStatus, BoxSDKError>) in guard case let .success(userStatus) = result else { print("Error retrieving user status for Terms of Service") return } print("User status with ID \(userStatus.id) was retrieved") } ``` --- ### TermsOfServicesManager **Type:** page | **Section:** Additional Resources TermsOfServicesManager List terms of services Create terms of service Get terms of service Update terms of service List terms of services… # TermsOfServicesManager - [List terms of services](#list-terms-of-services) - [Create terms of service](#create-terms-of-service) - [Get terms of service](#get-terms-of-service) - [Update terms of service](#update-terms-of-service) ## List terms of services Returns the current terms of service text and settings for the enterprise. This operation is performed by calling function `getTermsOfService`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-terms-of-services/). ``` await client.termsOfServices.getTermsOfService(); ``` ### Arguments queryParams `GetTermsOfServiceQueryParams` - Query parameters of getTermsOfService method headersInput `GetTermsOfServiceHeadersInput` - Headers of getTermsOfService method cancellationToken `undefined | CancellationToken` - Token used for request cancellation. ### Returns This function returns a value of type `TermsOfServices`. Returns a collection of terms of service text and settings for the enterprise. ## Create terms of service Creates a terms of service for a given enterprise and type of user. This operation is performed by calling function `createTermsOfService`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-terms-of-services/). ``` await client.termsOfServices.createTermsOfService({ status: 'disabled' as CreateTermsOfServiceRequestBodyStatusField, tosType: 'managed' as CreateTermsOfServiceRequestBodyTosTypeField, text: 'Test TOS', } satisfies CreateTermsOfServiceRequestBody); ``` ### Arguments requestBody `CreateTermsOfServiceRequestBody` - Request body of createTermsOfService method optionalsInput `CreateTermsOfServiceOptionalsInput` ### Returns This function returns a value of type `TermsOfService`. Returns a new task object. ## Get terms of service Fetches a specific terms of service. This operation is performed by calling function `getTermsOfServiceById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-terms-of-services-id/). *Currently we don't have an example for calling `getTermsOfServiceById` in integration tests* ### Arguments termsOfServiceId `string` - The ID of the terms of service. Example: "324234" optionalsInput `GetTermsOfServiceByIdOptionalsInput` ### Returns This function returns a value of type `TermsOfService`. Returns a terms of service object. ## Update terms of service Updates a specific terms of service. This operation is performed by calling function `updateTermsOfServiceById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-terms-of-services-id/). ``` await client.termsOfServices.updateTermsOfServiceById(tos.id, { status: 'disabled' as UpdateTermsOfServiceByIdRequestBodyStatusField, text: 'TOS', } satisfies UpdateTermsOfServiceByIdRequestBody); ``` ### Arguments termsOfServiceId `string` - The ID of the terms of service. Example: "324234" requestBody `UpdateTermsOfServiceByIdRequestBody` - Request body of updateTermsOfServiceById method optionalsInput `UpdateTermsOfServiceByIdOptionalsInput` ### Returns This function returns a value of type `TermsOfService`. Returns an updated terms of service object. --- ### TermsOfServicesManager **Type:** page | **Section:** Additional Resources TermsOfServicesManager List terms of services Create terms of service Get terms of service Update terms of service List terms of services… # TermsOfServicesManager - [List terms of services](#list-terms-of-services) - [Create terms of service](#create-terms-of-service) - [Get terms of service](#get-terms-of-service) - [Update terms of service](#update-terms-of-service) ## List terms of services Returns the current terms of service text and settings for the enterprise. This operation is performed by calling function `get_terms_of_service`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-terms-of-services/). ``` client.terms_of_services.get_terms_of_service() ``` ### Arguments tos_type `Optional[GetTermsOfServiceTosType]` - Limits the results to the terms of service of the given type. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `TermsOfServices`. Returns a collection of terms of service text and settings for the enterprise. ## Create terms of service Creates a terms of service for a given enterprise and type of user. This operation is performed by calling function `create_terms_of_service`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-terms-of-services/). ``` client.terms_of_services.create_terms_of_service( CreateTermsOfServiceStatus.DISABLED, "Test TOS", tos_type=CreateTermsOfServiceTosType.MANAGED, ) ``` ### Arguments status `CreateTermsOfServiceStatus` - Whether this terms of service is active. tos_type `Optional[CreateTermsOfServiceTosType]` - The type of user to set the terms of service for. text `str` - The terms of service text to display to users. The text can be set to empty if the `status` is set to `disabled`. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `TermsOfService`. Returns a new task object. ## Get terms of service Fetches a specific terms of service. This operation is performed by calling function `get_terms_of_service_by_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-terms-of-services-id/). *Currently we don't have an example for calling `get_terms_of_service_by_id` in integration tests* ### Arguments terms_of_service_id `str` - The ID of the terms of service. Example: "324234" extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `TermsOfService`. Returns a terms of service object. ## Update terms of service Updates a specific terms of service. This operation is performed by calling function `update_terms_of_service_by_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-terms-of-services-id/). ``` client.terms_of_services.update_terms_of_service_by_id( tos.id, UpdateTermsOfServiceByIdStatus.DISABLED, "TOS" ) ``` ### Arguments terms_of_service_id `str` - The ID of the terms of service. Example: "324234" status `UpdateTermsOfServiceByIdStatus` - Whether this terms of service is active. text `str` - The terms of service text to display to users. The text can be set to empty if the `status` is set to `disabled`. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `TermsOfService`. Returns an updated terms of service object. --- ### TermsOfServiceUserStatusesManager **Type:** page | **Section:** Additional Resources TermsOfServiceUserStatusesManager List terms of service user statuses Create terms of service status for new user Update terms of service… # TermsOfServiceUserStatusesManager - [List terms of service user statuses](#list-terms-of-service-user-statuses) - [Create terms of service status for new user](#create-terms-of-service-status-for-new-user) - [Update terms of service status for existing user](#update-terms-of-service-status-for-existing-user) ## List terms of service user statuses Retrieves an overview of users and their status for a terms of service, including Whether they have accepted the terms and when. This operation is performed by calling function `getTermsOfServiceUserStatuses`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-terms-of-service-user-statuses/). ``` await client.termsOfServiceUserStatuses.getTermsOfServiceUserStatuses({ tosId: tos.id, userId: user.id, } satisfies GetTermsOfServiceUserStatusesQueryParams); ``` ### Arguments queryParams `GetTermsOfServiceUserStatusesQueryParams` - Query parameters of getTermsOfServiceUserStatuses method optionalsInput `GetTermsOfServiceUserStatusesOptionalsInput` ### Returns This function returns a value of type `TermsOfServiceUserStatuses`. Returns a list of terms of service statuses. ## Create terms of service status for new user Sets the status for a terms of service for a user. This operation is performed by calling function `createTermsOfServiceStatusForUser`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-terms-of-service-user-statuses/). ``` await client.termsOfServiceUserStatuses.createTermsOfServiceStatusForUser({ tos: new CreateTermsOfServiceStatusForUserRequestBodyTosField({ id: tos.id }), user: new CreateTermsOfServiceStatusForUserRequestBodyUserField({ id: user.id, }), isAccepted: false, } satisfies CreateTermsOfServiceStatusForUserRequestBody); ``` ### Arguments requestBody `CreateTermsOfServiceStatusForUserRequestBody` - Request body of createTermsOfServiceStatusForUser method optionalsInput `CreateTermsOfServiceStatusForUserOptionalsInput` ### Returns This function returns a value of type `TermsOfServiceUserStatus`. Returns a terms of service status object. ## Update terms of service status for existing user Updates the status for a terms of service for a user. This operation is performed by calling function `updateTermsOfServiceStatusForUserById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-terms-of-service-user-statuses-id/). ``` await client.termsOfServiceUserStatuses.updateTermsOfServiceStatusForUserById( createdTosUserStatus.id, { isAccepted: true, } satisfies UpdateTermsOfServiceStatusForUserByIdRequestBody, ); ``` ### Arguments termsOfServiceUserStatusId `string` - The ID of the terms of service status. Example: "324234" requestBody `UpdateTermsOfServiceStatusForUserByIdRequestBody` - Request body of updateTermsOfServiceStatusForUserById method optionalsInput `UpdateTermsOfServiceStatusForUserByIdOptionalsInput` ### Returns This function returns a value of type `TermsOfServiceUserStatus`. Returns the updated terms of service status object. --- ### TermsOfServiceUserStatusesManager **Type:** page | **Section:** Additional Resources TermsOfServiceUserStatusesManager List terms of service user statuses Create terms of service status for new user Update terms of service… # TermsOfServiceUserStatusesManager - [List terms of service user statuses](#list-terms-of-service-user-statuses) - [Create terms of service status for new user](#create-terms-of-service-status-for-new-user) - [Update terms of service status for existing user](#update-terms-of-service-status-for-existing-user) ## List terms of service user statuses Retrieves an overview of users and their status for a terms of service, including Whether they have accepted the terms and when. This operation is performed by calling function `get_terms_of_service_user_statuses`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-terms-of-service-user-statuses/). ``` client.terms_of_service_user_statuses.get_terms_of_service_user_statuses( tos.id, user_id=user.id ) ``` ### Arguments tos_id `str` - The ID of the terms of service. user_id `Optional[str]` - Limits results to the given user ID. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `TermsOfServiceUserStatuses`. Returns a list of terms of service statuses. ## Create terms of service status for new user Sets the status for a terms of service for a user. This operation is performed by calling function `create_terms_of_service_status_for_user`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-terms-of-service-user-statuses/). ``` client.terms_of_service_user_statuses.create_terms_of_service_status_for_user( CreateTermsOfServiceStatusForUserTos(id=tos.id), CreateTermsOfServiceStatusForUserUser(id=user.id), False, ) ``` ### Arguments tos `CreateTermsOfServiceStatusForUserTos` - The terms of service to set the status for. user `CreateTermsOfServiceStatusForUserUser` - The user to set the status for. is_accepted `bool` - Whether the user has accepted the terms. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `TermsOfServiceUserStatus`. Returns a terms of service status object. ## Update terms of service status for existing user Updates the status for a terms of service for a user. This operation is performed by calling function `update_terms_of_service_status_for_user_by_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-terms-of-service-user-statuses-id/). ``` client.terms_of_service_user_statuses.update_terms_of_service_status_for_user_by_id( created_tos_user_status.id, True ) ``` ### Arguments terms_of_service_user_status_id `str` - The ID of the terms of service status. Example: "324234" is_accepted `bool` - Whether the user has accepted the terms. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `TermsOfServiceUserStatus`. Returns the updated terms of service status object. --- ### TransferManager **Type:** page | **Section:** Additional Resources TransferManager Transfer owned folders Transfer owned folders Move all of the items (files, folders and workflows) owned by a user into… # TransferManager - [Transfer owned folders](#transfer-owned-folders) ## Transfer owned folders Move all of the items (files, folders and workflows) owned by a user into another user's account Only the root folder (`0`) can be transferred. Folders can only be moved across users by users with administrative permissions. All existing shared links and folder-level collaborations are transferred during the operation. Please note that while collaborations at the individual file-level are transferred during the operation, the collaborations are deleted when the original user is deleted. If the user has a large number of items across all folders, the call will be run asynchronously. If the operation is not completed within 10 minutes, the user will receive a 200 OK response, and the operation will continue running. If the destination path has a metadata cascade policy attached to any of the parent folders, a metadata cascade operation will be kicked off asynchronously. There is currently no way to check for when this operation is finished. The destination folder's name will be in the format `{User}'s Files and Folders`, where `{User}` is the display name of the user. To make this API call your application will need to have the "Read and write all files and folders stored in Box" scope enabled. Please make sure the destination user has access to `Relay` or `Relay Lite`, and has access to the files and folders involved in the workflows being transferred. Admins will receive an email when the operation is completed. This operation is performed by calling function `transferOwnedFolder`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-users-id-folders-0/). ``` await client.transfer.transferOwnedFolder( sourceUser.id, { ownedBy: { id: targetUser.id, } satisfies TransferOwnedFolderRequestBodyOwnedByField, } satisfies TransferOwnedFolderRequestBody, { queryParams: { notify: false } satisfies TransferOwnedFolderQueryParams, } satisfies TransferOwnedFolderOptionalsInput, ); ``` ### Arguments userId `string` - The ID of the user. Example: "12345" requestBody `TransferOwnedFolderRequestBody` - Request body of transferOwnedFolder method optionalsInput `TransferOwnedFolderOptionalsInput` ### Returns This function returns a value of type `FolderFull`. Returns the information for the newly created destination folder. --- ### TransferManager **Type:** page | **Section:** Additional Resources TransferManager Transfer owned folders Transfer owned folders Move all of the items (files, folders and workflows) owned by a user into… # TransferManager - [Transfer owned folders](#transfer-owned-folders) ## Transfer owned folders Move all of the items (files, folders and workflows) owned by a user into another user's account Only the root folder (`0`) can be transferred. Folders can only be moved across users by users with administrative permissions. All existing shared links and folder-level collaborations are transferred during the operation. Please note that while collaborations at the individual file-level are transferred during the operation, the collaborations are deleted when the original user is deleted. If the user has a large number of items across all folders, the call will be run asynchronously. If the operation is not completed within 10 minutes, the user will receive a 200 OK response, and the operation will continue running. If the destination path has a metadata cascade policy attached to any of the parent folders, a metadata cascade operation will be kicked off asynchronously. There is currently no way to check for when this operation is finished. The destination folder's name will be in the format `{User}'s Files and Folders`, where `{User}` is the display name of the user. To make this API call your application will need to have the "Read and write all files and folders stored in Box" scope enabled. Please make sure the destination user has access to `Relay` or `Relay Lite`, and has access to the files and folders involved in the workflows being transferred. Admins will receive an email when the operation is completed. This operation is performed by calling function `transfer_owned_folder`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-users-id-folders-0/). ``` client.transfer.transfer_owned_folder( source_user.id, TransferOwnedFolderOwnedBy(id=target_user.id), notify=False ) ``` ### Arguments user_id `str` - The ID of the user. Example: "12345" owned_by `TransferOwnedFolderOwnedBy` - The user who the folder will be transferred to. fields `Optional[List[str]]` - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested. notify `Optional[bool]` - Determines if users should receive email notification for the action performed. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `FolderFull`. Returns the information for the newly created destination folder. --- ### Trash **Type:** page | **Section:** Additional Resources Trash Under normal circumstances, when an item in Box is deleted, it is not actually erased immediately. Instead, it is moved to the Trash… # Trash Under normal circumstances, when an item in Box is deleted, it is not actually erased immediately. Instead, it is moved to the Trash. The Trash allows you to recover files and folders that have been deleted. By default, items in the Trash will be purged after 30 days. - [Get Trashed Items](#get-trashed-items) - [Restore a File From Trash](#restore-a-file-from-trash) - [Delete a File from the Trash](#delete-a-file-from-the-trash) - [Get a Trashed File](#get-a-trashed-file) - [Get a Trashed Folder](#get-a-trashed-folder) - [Restore a Folder from Trash](#restore-a-folder-from-trash) - [Delete a Folder from the Trash](#delete-a-folder-from-the-trash) ## Get Trashed Items To retrieve files and folders that have been moved to the Trash, call the [`trash.get(options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Trash.html#get) method. ``` client.trash.get() .then(trashedItems => { /* trashedItems -> { total_count: 2, entries: [ { type: 'file', id: '11111', sequence_id: '1', etag: '1', sha1: '9d976863fc849f6061ecf9736710bd9c2bce488c', name: 'file Tue Jul 24 145436 2012KWPX5S.csv' }, { type: 'file', id: '22222', sequence_id: '1', etag: '1', sha1: '09b0e2e9760caf7448c702db34ea001f356f1197', name: 'file Tue Jul 24 010055 20129Z6GS3.csv' } ], offset: 0, limit: 100 } */ }); ``` ## Restore a File From Trash Calling the [`files.restoreFromTrash(fileID, options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Files.html#restoreFromTrash) will restore an item from the user's trash. Default behavior is to restore the item to the folder it was in before it was moved to the trash. Options are available to handle possible failure cases: if an item with the same name already exists in folder's old location, the restored folder can be given an alternate name with the `name` option. If the folder's old location no longer exists, it can be placed inside a new parent folder with the `parent_id` option. ``` client.files.restoreFromTrash( '11111', { // New name in case of conflict name: 'New Name', // File will be placed in this folder if original location no longer exists parent_id: '0' }) .then(restoredFile => { /* trashedFile -> { type: 'file', id: '11111', sequence_id: '2', etag: '2', sha1: '4bd9e98652799fc57cf9423e13629c151152ce6c', name: 'Screenshot_1_30_13_6_37_PM.png', description: '', size: 163265, path_collection: { total_count: 1, entries: [ { type: 'folder', id: '0', sequence_id: null, etag: null, name: 'All Files' } ] }, created_at: '2013-01-30T18:43:56-08:00', modified_at: '2013-01-30T18:44:00-08:00', trashed_at: null, purged_at: null, content_created_at: '2013-01-30T18:43:56-08:00', content_modified_at: '2013-01-30T18:44:00-08:00', created_by: { type: 'user', id: '33333', name: 'Example User', login: 'user@example.com' }, modified_by: { type: 'user', id: '33333', name: 'Example User', login: 'user@example.com' }, owned_by: { type: 'user', id: '33333', name: 'Example User', login: 'user@example.com' }, shared_link: null, parent: { type: 'folder', id: '0', sequence_id: null, etag: null, name: 'All Files' }, item_status: 'active' } */ }); ``` ## Delete a File from the Trash Calling the [`files.deletePermanently(fileID, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Files.html#deletePermanently) method will remove the file permanently from the user's trash. ``` client.files.deletePermanently('11111') .then(() => { // deletion succeeded — no value returned }); ``` If you want to ensure that your deletion does not overwrite any other updates (i.e. to prevent against possible race conditions), you can pass the last known value of the file's `etag` field via the `etag` option; this will generate an error if the file was modified between when you read that `etag` value and when the deletion is processed by the API. ``` client.files.deletePermanently('11111', { etag: '5' }) .then(() => { // File successfully deleted }) .catch(err => { if (err.statusCode === 412) { // Precondition failed — the file was modified before the deletion was processed // Read the file again to ensure it is safe to delete and then retry } }); ``` ## Get a Trashed File Information about a file in the trash can be retrieved with the [`files.getTrashedFile(fileID, options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Files.html#getTrashedFile) method. ``` client.files.getTrashedFile('11111') .then(trashedFile => { /* trashedFile -> { type: 'file', id: '11111', sequence_id: '2', etag: '2', sha1: '4bd9e98652799fc57cf9423e13629c151152ce6c', name: 'Screenshot_1_30_13_6_37_PM.png', description: '', size: 163265, path_collection: { total_count: 1, entries: [ { type: 'folder', id: '1', sequence_id: null, etag: null, name: 'Trash' } ] }, created_at: '2013-01-30T18:43:56-08:00', modified_at: '2013-01-30T18:44:00-08:00', trashed_at: '2013-02-07T10:49:34-08:00', purged_at: '2013-03-09T10:49:34-08:00', content_created_at: '2013-01-30T18:43:56-08:00', content_modified_at: '2013-01-30T18:44:00-08:00', created_by: { type: 'user', id: '33333', name: 'Example User', login: 'user@example.com' }, modified_by: { type: 'user', id: '33333', name: 'Example User', login: 'user@example.com' }, owned_by: { type: 'user', id: '33333', name: 'Example User', login: 'user@example.com' }, shared_link: null, parent: { type: 'folder', id: '0', sequence_id: null, etag: null, name: 'All Files' }, item_status: 'trashed' } */ }); ``` Requesting information for only the fields you need with the `fields` option can improve performance and reduce the size of the network request. ``` // Only get information about a few specific fields. client.files.getTrashedFile('11111', {fields: 'size,owned_by'}) .then(trashedFile => { /* trashedFile -> { type: 'file', id: '11111', sequence_id: '2', etag: '2', sha1: '4bd9e98652799fc57cf9423e13629c151152ce6c', size: 163265, owned_by: { type: 'user', id: '33333', name: 'Example User', login: 'user@example.com' } } */ }); ``` ## Get a Trashed Folder Information about a folder in the trash can be retrieved with the [`folders.getTrashedFolder(folderID, options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Folders.html#getTrashedFolder) method. ``` client.folders.getTrashedFolder('22222') .then(trashedFolder => { /* trashedFolder -> { type: 'folder', id: '22222', sequence_id: '1', etag: '1', name: 'Old Files', created_at: '2013-05-06T22:37:30-07:00', modified_at: '2013-05-06T22:39:08-07:00', description: '', size: 18482, path_collection: { total_count: 1, entries: [ { type: 'folder', id: '1', sequence_id: null, etag: null, name: 'Trash' } ] }, created_by: { type: 'user', id: '33333', name: 'Example User', login: 'user@example.com' }, modified_by: { type: 'user', id: '33333', name: 'Example User', login: 'user@example.com' }, trashed_at: '2013-05-29T09:37:13-07:00', purged_at: null, content_created_at: '2013-05-06T22:37:30-07:00', content_modified_at: '2013-05-06T22:39:08-07:00', owned_by: { type: 'user', id: '33333', name: 'Example User', login: 'user@example.com' }, shared_link: null, folder_upload_email: null, parent: { type: 'folder', id: '0', sequence_id: null, etag: null, name: 'All Files' }, item_status: 'trashed' } */ }); ``` Requesting information for only the fields you need with the `fields` option can improve performance and reduce the size of the network request. ``` client.folders.getTrashedFolder('22222', {fields: 'name,trashed_at,purged_at'}) .then(trashedFolder => { /* trashedFolder -> { type: 'folder', id: '22222', sequence_id: '1', etag: '1', trashed_at: '2013-05-29T09:37:13-07:00', purged_at: null } */ }); ``` ## Restore a Folder from Trash A folder can be restored from the trash with the [`folders.restoreFromTrash(folderID, options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Folders.html#restoreFromTrash) method. Default behavior is to restore the item to the folder it was in before it was moved to the trash. Options are available to handle possible failure cases: if an item with the same name already exists in folder's old location, the restored folder can be given an alternate name with the `name` option. If the folder's old location no longer exists, it can be placed inside a new parent folder with the `parent_id` option. ``` client.folders.restoreFromTrash( '22222', { // New name in case of conflict name: 'New Name', // Folder will be placed in this parent folder if the original parent no longer exists parent_id: '0' }) .then(restoredFolder => { /* trashedFolder -> { type: 'folder', id: '22222', sequence_id: '1', etag: '1', name: 'Old Files', created_at: '2013-05-06T22:37:30-07:00', modified_at: '2013-05-06T22:39:08-07:00', description: '', size: 18482, path_collection: { total_count: 1, entries: [ { type: 'folder', id: '0', sequence_id: null, etag: null, name: 'All Files' } ] }, created_by: { type: 'user', id: '33333', name: 'Example User', login: 'user@example.com' }, modified_by: { type: 'user', id: '33333', name: 'Example User', login: 'user@example.com' }, trashed_at: null, purged_at: null, content_created_at: '2013-05-06T22:37:30-07:00', content_modified_at: '2013-05-06T22:39:08-07:00', owned_by: { type: 'user', id: '33333', name: 'Example User', login: 'user@example.com' }, shared_link: null, folder_upload_email: null, parent: { type: 'folder', id: '0', sequence_id: null, etag: null, name: 'All Files' }, item_status: 'active' } */ }); ``` ## Delete a Folder from the Trash A folder can be removed permanently from trash by calling [`folders.deletePermanently(folderID, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Folders.html#deletePermanently). ``` client.folders.deletePermanently('22222') .then(() => { // deletion succeeded — no value returned }); ``` If you want to ensure that your deletion does not overwrite any other updates (i.e. to prevent against possible race conditions), you can pass the last known value of the folder's `etag` field via the `etag` option; this will generate an error if the folder was modified between when you read that `etag` value and when the deletion is processed by the API. ``` client.folders.deletePermanently('22222', { etag: '5' }) .then(() => { // Folder successfully deleted }) .catch(err => { if (err.statusCode === 412) { // Precondition failed — the folder was modified before the deletion was processed // Read the folder again to ensure it is safe to delete and then retry } }); ``` --- ### Trash **Type:** page | **Section:** Additional Resources Trash Under normal circumstances, when an item in Box is deleted, it is not actually erased immediately. Instead, it is moved to the Trash… # Trash Under normal circumstances, when an item in Box is deleted, it is not actually erased immediately. Instead, it is moved to the Trash. The Trash allows you to recover files and folders that have been deleted. By default, items in the Trash will be purged after 30 days. - [Get Trashed Items](#get-trashed-items) - [Get Trashed File Information](#get-trashed-file-information) - [Get Trashed Folder Information](#get-trashed-folder-information) - [Permanently Delete File From Trash](#permanently-delete-file-from-trash) - [Permanently Delete Folder From Trash](#permanently-delete-folder-from-trash) - [Restore a File from the Trash](#restore-a-file-from-the-trash) - [Restore a Folder from the Trash](#restore-a-folder-from-the-trash) ## Get Trashed Items The [`BoxTrash`](https://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxTrash.html) implements `Iterable<BoxItem.Info>`, so to get the collection of items currently in the trash, simply iterate over it. ``` BoxTrash trash = new BoxTrash(api); for (BoxItem.Info itemInfo : trash) { // Process the item } ``` Alternatively you can specify sort order, limit, use marker based pagination or specify which fields you want to extract with [`BoxTrash#items`](https://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxTrash.html#items-com.box.sdk.SortParameters-com.box.sdk.PagingParameters-java.lang.String...-). To use sorting you have to use offset based pagination: ``` BoxTrash trash = new BoxTrash(api); Iterable<BoxItem.Info> trashEntries = trash.items( SortParameters.ascending("name"), PagingParameters.offset(0, 500) ); for (BoxItem.Info trashEntry : trashEntries) { // Process the item } ``` If you have a lot of items in trash and offset value is in tens of thousands it is better to use marker based pagination. However, marker based pagination cannot be used with sorting. To disable sorting use `SortParameters.none()`: ``` BoxTrash trash = new BoxTrash(api); Iterable<BoxItem.Info> trashEntries = trash.items( SortParameters.none(), PagingParameters.marker(500) ); for (BoxItem.Info trashEntry : trashEntries) { // Process the item } ``` ## Get Trashed File Information Ordinarily, trying to call [`getInfo()`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFile.html#getInfo-java.lang.String...-) on a file that is in the trash will return a 404 error. To get the information of a file in the trash, you must instead call [`BoxTrash#getFileInfo(String fileID)`](https://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxTrash.html#getFileInfo-java.lang.String-) with the ID of the trashed file. You can optionally pass a specific list of fields to retrieve to [`getFileInfo(String fileID, String... fields)`](https://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxTrash.html#getFileInfo-java.lang.String-java.lang.String...-), which will return only the specified fields to reduce payload size. ``` String fileID = "9873459"; BoxTrash trash = new BoxTrash(api); BoxFile.Info fileInfo = trash.getFileInfo(fileID); ``` ## Get Trashed Folder Information Ordinarily, trying to call [`getInfo()`][folder-get-info] on a folder that is in the trash will return a 404 error. To get the information of a folder in the trash, you must instead call [`BoxTrash#getFolderInfo(String fileID)`](https://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxTrash.html#getFolderInfo-java.lang.String-) with the ID of the trashed folder. You can optionally pass a specific list of fields to retrieve to [`getFileInfo(String folderID, String... fields)`](https://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxTrash.html#getFolderInfo-java.lang.String-java.lang.String...-), which will return only the specified fields to reduce payload size. ``` String folderID = "2345343"; BoxTrash trash = new BoxTrash(api); BoxFolder.Info folderInfo = trash.getFolderInfo(folderInfo); ``` ## Permanently Delete File From Trash To delete a file from the trash, call [`BoxTrash#deleteFile(String fileID)`](https://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxTrash.html#deleteFile-java.lang.String-) with the ID of the file to delete. **Note:** This will permanently delete the file, and cannot be undone. ``` String fileID = "87398"; BoxTrash trash = new BoxTrash(api); trash.deleteFile(fileID); ``` ## Permanently Delete Folder From Trash To delete a folder from the trash, call [`BoxTrash#deleteFolder(String fileID)`](https://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxTrash.html#deleteFolder-java.lang.String-) with the ID of the folder to delete. **Note:** This will permanently delete the folder, and cannot be undone. ``` String folder = "123456"; BoxTrash trash = new BoxTrash(api); trash.deleteFolder(folderID); ``` ## Restore a File from the Trash To restore a file from the trash, effectively undeleting it, call [`BoxTrash#restoreFile(String fileID)`](https://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxTrash.html#restoreFile-java.lang.String-) with the ID of the file. To avoid scenarios where the parent folder that previously contained the file is no longer available, the user does not have permission to create items in that folder, or that folder has an item with the same name as the one being restored; you can pass a new parent folder ID and/or file name to [`BoxTrash#restoreFile(String fileID, String newName, String newParentID)`](https://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxTrash.html#restoreFile-java.lang.String-java.lang.String-java.lang.String-). The new name and parent will only be used if a conflict is encountered while trying to restore the file to its original location. ``` String fileID = "125367"; String newName = "Presentation 2018 ORIGINAL.pptx"; String newParentID = "98765"; BoxTrash trash = new BoxTrash(api); // Avoid conflicts at the original location trash.restoreFile(fileID, newName, newParentID); ``` ## Restore a Folder from the Trash To restore a folder from the trash, effectively undeleting it, call [`BoxTrash#restoreFolder(String folderID)`](https://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxTrash.html#restoreFolder-java.lang.String-) with the ID of the folder. To avoid scenarios where the parent folder that previously contained the folder to be restored is no longer available, the user does not have permission to create items in that folder, or that folder has an item with the same name as the one being restored; you can pass a new parent folder ID and/or folder name to [`BoxTrash#restoreFolder(String folderID, String newName, String newParentID)`](https://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxTrash.html#restoreFolder-java.lang.String-java.lang.String-java.lang.String-). The new name and parent will only be used if a conflict is encountered while trying to restore the folder to its original location. ``` String folderID = "125367"; String newName = "My Documents ORIGINAL"; String newParentID = "98765"; BoxTrash trash = new BoxTrash(api); // Avoid conflicts at the original location trash.restoreFolder(folderID, newName, newParentID); ``` --- ### Trash **Type:** page | **Section:** Additional Resources Trash Under normal circumstances, when an item in Box is deleted, it is not actually erased immediately. Instead, it is moved to the Trash… # Trash Under normal circumstances, when an item in Box is deleted, it is not actually erased immediately. Instead, it is moved to the Trash. The Trash allows you to recover files and folders that have been deleted. By default, items in the Trash will be purged after 30 days. - [List Trashed Items](#list-trashed-items) - [Get Trashed Items](#get-trashed-items) - [Restore Item from Trash](#restore-item-from-trash) - [Permanently Delete Item](#permanently-delete-item) ## List Trashed Items To retrieve all trashed items for an enterprise, call [`client.trash().get_items(imit=None, offset=None, fields=None)`][get_trashed_items]. This method returns a `BoxObjectCollection` that allows you to iterate over the [`Trash`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.trash.Trash) objects in the collection. ``` trashed_items = client.trash().get_items() for trashed_item in trashed_items: print(f'The item ID is {trashed_item.id} and the item name is {trashed_item.name}') ``` ## Get Trashed Items To get a trashed item, call [`client.trash().get_item(item, fields)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.trash.Trash.get_item) with the item you wish to retrieve passed in. This method will return the ['Item'](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.item.Item) object populated with data from the API. ``` file_to_retrieve = client.file(file_id='11111') file_from_trash = client.trash().get_item(file_to_retrieve) print(f'File ID is {file_from_trash.id} and name is {file_from_trash.name}') ``` ``` folder = client.folder(folder_id='22222') folder_from_trash = client.trash().get_item(folder) print(f'Folder ID is {folder_from_trash.id} and name is {folder_from_trash.name}') ``` ``` web_link = client.web_link(web_link_i='33333') web_link_from_trash = client.trash().get_item(web_link) print(f'Web link ID is {web_link_from_trash.id} and name is {web_link_from_trash.name}') ``` ## Restore Item from Trash To retore a trashed item, effectively undeleting it, call [`client.trash().restore(item, name=None, parent_folder, fields=None)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.trash.Trash.restore_item) with the constructed [`Item`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.item.Item) object will let you restore the specific object from your trash. This method will return a [`Item`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.item.Item) object populated with data from the API, leaving the original object unmodified. ``` file_to_restore = client.file(file_id='11111') restored_file = client.trash().restore_item(file_to_restore) print(f'File ID is {restored_file.id} and name is {restored_file.name}') ``` ``` folder_to_restore = client.folder(folder_id='22222') restored_folder = client.trash().restore_item(folder_to_restore) print(f'Folder ID is {restored_folder.id} and name is {restored_folder.name}') ``` ``` web_link_to_restore = client.web_link(web_link_id='33333') restored_web_link = client.trash().restore_item(web_link_to_restore) print(f'Web link ID is {restored_web_link.id} and name is {restored_web_link.name}') ``` In order to avoid conflicts, you can set a new name and new parent folder for the item you wish to restore. ``` file_to_restore = client.file(file_id='11111') new_name = 'New File Name' new_parent_folder = client.folder(folder_id='22222') restored_file = client.trash().restore_item(file_to_restore, new_name, new_parent_folder) print(f'New name for file is {restored_file.name} and new parent folder is {restored_file.parent.name}') ``` ## Permanently Delete Item To delete an [`Item`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.item.Item) object from trash, call [`client.trash().permanently_delete_item(item)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.trash.Trash.permanently_delete). This method returns `True` to indicate that the deletion was successful. ``` file_to_delete = client.file(file_id='11111') client.trash().permanently_delete_item(file_to_delete) print('The file was deleted from trash!') ``` ``` folder = client.folder(folder_id='22222') client.trash().permanently_delete_item(folder) print('The folder was deleted from trash!') ``` ``` web_link = client.web_link(web_link_id='33333') client.trash().permanently_delete_item(web_link) print('The web link was deleted from trash!') ``` --- ### Trash **Type:** page | **Section:** Additional Resources Trash Under normal circumstances, when an item in Box is deleted, it is not actually erased immediately. Instead, it is moved to the Trash… # Trash Under normal circumstances, when an item in Box is deleted, it is not actually erased immediately. Instead, it is moved to the Trash. The Trash allows you to recover files and folders that have been deleted. By default, items in the Trash will be purged after 30 days. - [Get Trashed Items](#get-trashed-items) - [Get a Trashed File](#get-a-trashed-file) - [Get a Trashed Folder](#get-a-trashed-folder) - [Purge a File from the Trash](#purge-a-file-from-the-trash) - [Purge a Folder from the Trash](#purge-a-folder-from-the-trash) - [Restore a File From Trash](#restore-a-file-from-trash) - [Restore a Folder from Trash](#restore-a-folder-from-trash) ## Get Trashed Items To retrieve files and folders that have been moved to the Trash, call `FoldersManager.GetTrashItemsAsync(int limit, int offset = 0, IEnumerable<string> fields = null, bool autoPaginate=false)`. ``` BoxCollection<BoxItem> trashedItems = await client.FoldersManager.GetTrashItemsAsync(limit: 100); ``` ## Get a Trashed File Information about a file in the trash can be retrieved by calling the `FilesManager.GetTrashedAsync(string id, IEnumerable<string> fields = null)` method with the ID of the file in the trash. ``` BoxFile trashedFile = await client.FilesManager.GetTrashedAsync("11111"); ``` ## Get a Trashed Folder Information about a folder in the trash can be retrieved by calling the `FoldersManager.GetTrashedFolderAsync(string id, IEnumerable<string> fields = null)` method with the ID of the folder in the trash. ``` BoxFolder trashedFolder = await client.FoldersManager.GetTrashedFolderAsync("22222"); ``` ## Purge a File from the Trash Calling the `FilesManager.PurgeTrashedAsync(string id)` method will remove the file permanently from the user's trash. ``` await client.FilesManager.PurgeTrashedAsync("11111"); ``` ## Purge a Folder from the Trash Calling the `FoldersManager.PurgeTrashedFolderAsync(string id)` method will remove the folder permanently from the user's trash. ``` await client.FoldersManager.PurgeTrashedFolderAsync("22222"); ``` ## Restore a File From Trash Calling `FilesManager.RestoreTrashedAsync(BoxFileRequest fileRequest, IEnumerable<string> fields = null)` will restore an item from the user's trash. Default behavior is to restore the item to the folder it was in before it was moved to the trash. Options are available to handle possible failure cases: if an item with the same name already exists in folder's old location, the restored folder can be given an alternate name with the `Name` option. If the folder's old location no longer exists, it can be placed inside a new parent folder with the `Parent.Id` option. ``` var requestParams = new BoxFileRequest() { Name = "Name in case of conflict", Parent = new BoxRequestEntity() { // File will be placed in this folder if original location no longer exists Id = "12345" } }; BoxFile restoredFile = await client.FilesManager.RestoreTrashedAsync(requestParams); ``` ## Restore a Folder from Trash A folder can be restored from the trash with the `FoldersManager.RestoreTrashedFolderAsync(BoxFolderRequest folderRequest, IEnumerable<string> fields = null)` method. Default behavior is to restore the item to the folder it was in before it was moved to the trash. Options are available to handle possible failure cases: if an item with the same name already exists in folder's old location, the restored folder can be given an alternate name with the `Name` option. If the folder's old location no longer exists, it can be placed inside a new parent folder with the `Parent.Id` option. ``` var requestParams = new BoxFolderRequest() { Name = "Name in case of conflict", Parent = new BoxRequestEntity() { // Folder will be placed in this parent folder if original location no longer exists Id = "12345" } }; BoxFolder restoredFolder = await client.FoldersManager.RestoreTrashedFolderAsync(requestParams); ``` --- ### TrashedFilesManager **Type:** page | **Section:** Additional Resources TrashedFilesManager Restore file Get trashed file Permanently remove file Restore file Restores a file that has been moved to the trash. An… # TrashedFilesManager - [Restore file](#restore-file) - [Get trashed file](#get-trashed-file) - [Permanently remove file](#permanently-remove-file) ## Restore file Restores a file that has been moved to the trash. An optional new parent ID can be provided to restore the file to in case the original folder has been deleted. This operation is performed by calling function `restoreFileFromTrash`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-files-id/). ``` await client.trashedFiles.restoreFileFromTrash(file.id); ``` ### Arguments fileId `string` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" optionalsInput `RestoreFileFromTrashOptionalsInput` ### Returns This function returns a value of type `TrashFileRestored`. Returns a file object when the file has been restored. ## Get trashed file Retrieves a file that has been moved to the trash. Please note that only if the file itself has been moved to the trash can it be retrieved with this API call. If instead one of its parent folders was moved to the trash, only that folder can be inspected using the [`GET /folders/:id/trash`](e://get_folders_id_trash) API. To list all items that have been moved to the trash, please use the [`GET /folders/trash/items`](e://get-folders-trash-items/) API. This operation is performed by calling function `getTrashedFileById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-files-id-trash/). ``` await client.trashedFiles.getTrashedFileById(file.id); ``` ### Arguments fileId `string` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" optionalsInput `GetTrashedFileByIdOptionalsInput` ### Returns This function returns a value of type `TrashFile`. Returns the file that was trashed, including information about when the it was moved to the trash. ## Permanently remove file Permanently deletes a file that is in the trash. This action cannot be undone. This operation is performed by calling function `deleteTrashedFileById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-files-id-trash/). ``` await client.trashedFiles.deleteTrashedFileById(file.id); ``` ### Arguments fileId `string` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" optionalsInput `DeleteTrashedFileByIdOptionalsInput` ### Returns This function returns a value of type `undefined`. Returns an empty response when the file was permanently deleted. --- ### TrashedFilesManager **Type:** page | **Section:** Additional Resources TrashedFilesManager Restore file Get trashed file Permanently remove file Restore file Restores a file that has been moved to the trash. An… # TrashedFilesManager - [Restore file](#restore-file) - [Get trashed file](#get-trashed-file) - [Permanently remove file](#permanently-remove-file) ## Restore file Restores a file that has been moved to the trash. An optional new parent ID can be provided to restore the file to in case the original folder has been deleted. This operation is performed by calling function `restore_file_from_trash`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-files-id/). ``` client.trashed_files.restore_file_from_trash(file.id) ``` ### Arguments file_id `str` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" name `Optional[str]` - An optional new name for the file. parent `Optional[RestoreFileFromTrashParent]` fields `Optional[List[str]]` - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `TrashFileRestored`. Returns a file object when the file has been restored. ## Get trashed file Retrieves a file that has been moved to the trash. Please note that only if the file itself has been moved to the trash can it be retrieved with this API call. If instead one of its parent folders was moved to the trash, only that folder can be inspected using the [`GET /folders/:id/trash`](e://get_folders_id_trash) API. To list all items that have been moved to the trash, please use the [`GET /folders/trash/items`](e://get-folders-trash-items/) API. This operation is performed by calling function `get_trashed_file_by_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-files-id-trash/). ``` client.trashed_files.get_trashed_file_by_id(file.id) ``` ### Arguments file_id `str` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" fields `Optional[List[str]]` - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `TrashFile`. Returns the file that was trashed, including information about when the it was moved to the trash. ## Permanently remove file Permanently deletes a file that is in the trash. This action cannot be undone. This operation is performed by calling function `delete_trashed_file_by_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-files-id-trash/). ``` client.trashed_files.delete_trashed_file_by_id(file.id) ``` ### Arguments file_id `str` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `None`. Returns an empty response when the file was permanently deleted. --- ### TrashedFoldersManager **Type:** page | **Section:** Additional Resources TrashedFoldersManager Restore folder Get trashed folder Permanently remove folder Restore folder Restores a folder that has been moved to… # TrashedFoldersManager - [Restore folder](#restore-folder) - [Get trashed folder](#get-trashed-folder) - [Permanently remove folder](#permanently-remove-folder) ## Restore folder Restores a folder that has been moved to the trash. An optional new parent ID can be provided to restore the folder to in case the original folder has been deleted. During this operation, part of the file tree will be locked, mainly the source folder and all of its descendants, as well as the destination folder. For the duration of the operation, no other move, copy, delete, or restore operation can performed on any of the locked folders. This operation is performed by calling function `restoreFolderFromTrash`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-folders-id/). ``` await client.trashedFolders.restoreFolderFromTrash(folder.id); ``` ### Arguments folderId `string` - The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. Example: "12345" optionalsInput `RestoreFolderFromTrashOptionalsInput` ### Returns This function returns a value of type `TrashFolderRestored`. Returns a folder object when the folder has been restored. ## Get trashed folder Retrieves a folder that has been moved to the trash. Please note that only if the folder itself has been moved to the trash can it be retrieved with this API call. If instead one of its parent folders was moved to the trash, only that folder can be inspected using the [`GET /folders/:id/trash`](e://get_folders_id_trash) API. To list all items that have been moved to the trash, please use the [`GET /folders/trash/items`](e://get-folders-trash-items/) API. This operation is performed by calling function `getTrashedFolderById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-folders-id-trash/). ``` await client.trashedFolders.getTrashedFolderById(folder.id); ``` ### Arguments folderId `string` - The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. Example: "12345" optionalsInput `GetTrashedFolderByIdOptionalsInput` ### Returns This function returns a value of type `TrashFolder`. Returns the folder that was trashed, including information about when the it was moved to the trash. ## Permanently remove folder Permanently deletes a folder that is in the trash. This action cannot be undone. This operation is performed by calling function `deleteTrashedFolderById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-folders-id-trash/). ``` await client.trashedFolders.deleteTrashedFolderById(folder.id); ``` ### Arguments folderId `string` - The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. Example: "12345" optionalsInput `DeleteTrashedFolderByIdOptionalsInput` ### Returns This function returns a value of type `undefined`. Returns an empty response when the folder was permanently deleted. --- ### TrashedFoldersManager **Type:** page | **Section:** Additional Resources TrashedFoldersManager Restore folder Get trashed folder Permanently remove folder Restore folder Restores a folder that has been moved to… # TrashedFoldersManager - [Restore folder](#restore-folder) - [Get trashed folder](#get-trashed-folder) - [Permanently remove folder](#permanently-remove-folder) ## Restore folder Restores a folder that has been moved to the trash. An optional new parent ID can be provided to restore the folder to in case the original folder has been deleted. During this operation, part of the file tree will be locked, mainly the source folder and all of its descendants, as well as the destination folder. For the duration of the operation, no other move, copy, delete, or restore operation can performed on any of the locked folders. This operation is performed by calling function `restore_folder_from_trash`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-folders-id/). ``` client.trashed_folders.restore_folder_from_trash(folder.id) ``` ### Arguments folder_id `str` - The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. Example: "12345" name `Optional[str]` - An optional new name for the folder. parent `Optional[RestoreFolderFromTrashParent]` fields `Optional[List[str]]` - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `TrashFolderRestored`. Returns a folder object when the folder has been restored. ## Get trashed folder Retrieves a folder that has been moved to the trash. Please note that only if the folder itself has been moved to the trash can it be retrieved with this API call. If instead one of its parent folders was moved to the trash, only that folder can be inspected using the [`GET /folders/:id/trash`](e://get_folders_id_trash) API. To list all items that have been moved to the trash, please use the [`GET /folders/trash/items`](e://get-folders-trash-items/) API. This operation is performed by calling function `get_trashed_folder_by_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-folders-id-trash/). ``` client.trashed_folders.get_trashed_folder_by_id(folder.id) ``` ### Arguments folder_id `str` - The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. Example: "12345" fields `Optional[List[str]]` - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `TrashFolder`. Returns the folder that was trashed, including information about when the it was moved to the trash. ## Permanently remove folder Permanently deletes a folder that is in the trash. This action cannot be undone. This operation is performed by calling function `delete_trashed_folder_by_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-folders-id-trash/). ``` client.trashed_folders.delete_trashed_folder_by_id(folder.id) ``` ### Arguments folder_id `str` - The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. Example: "12345" extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `None`. Returns an empty response when the folder was permanently deleted. --- ### TrashedItemsManager **Type:** page | **Section:** Additional Resources TrashedItemsManager List trashed items List trashed items Retrieves the files and folders that have been moved to the trash. Any attribute… # TrashedItemsManager - [List trashed items](#list-trashed-items) ## List trashed items Retrieves the files and folders that have been moved to the trash. Any attribute in the full files or folders objects can be passed in with the `fields` parameter to retrieve those specific attributes that are not returned by default. This endpoint defaults to use offset-based pagination, yet also supports marker-based pagination using the `marker` parameter. This operation is performed by calling function `getTrashedItems`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-folders-trash-items/). ``` await client.trashedItems.getTrashedItems(); ``` ### Arguments queryParams `GetTrashedItemsQueryParams` - Query parameters of getTrashedItems method headersInput `GetTrashedItemsHeadersInput` - Headers of getTrashedItems method cancellationToken `undefined | CancellationToken` - Token used for request cancellation. ### Returns This function returns a value of type `Items`. Returns a list of items that have been deleted. --- ### TrashedItemsManager **Type:** page | **Section:** Additional Resources TrashedItemsManager List trashed items List trashed items Retrieves the files and folders that have been moved to the trash. Any attribute… # TrashedItemsManager - [List trashed items](#list-trashed-items) ## List trashed items Retrieves the files and folders that have been moved to the trash. Any attribute in the full files or folders objects can be passed in with the `fields` parameter to retrieve those specific attributes that are not returned by default. This endpoint defaults to use offset-based pagination, yet also supports marker-based pagination using the `marker` parameter. This operation is performed by calling function `get_trashed_items`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-folders-trash-items/). ``` client.trashed_items.get_trashed_items() ``` ### Arguments fields `Optional[List[str]]` - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested. limit `Optional[int]` - The maximum number of items to return per page. offset `Optional[int]` - The offset of the item at which to begin the response. Queries with offset parameter value exceeding 10000 will be rejected with a 400 response. usemarker `Optional[bool]` - Specifies whether to use marker-based pagination instead of offset-based pagination. Only one pagination method can be used at a time. By setting this value to true, the API will return a `marker` field that can be passed as a parameter to this endpoint to get the next page of the response. marker `Optional[str]` - Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`. direction `Optional[GetTrashedItemsDirection]` - The direction to sort results in. This can be either in alphabetical ascending (`ASC`) or descending (`DESC`) order. sort `Optional[GetTrashedItemsSort]` - Defines the **second** attribute by which items are sorted. Items are always sorted by their `type` first, with folders listed before files, and files listed before web links. This parameter is not supported when using marker-based pagination. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `Items`. Returns a list of items that have been deleted. --- ### TrashedWebLinksManager **Type:** page | **Section:** Additional Resources TrashedWebLinksManager Restore web link Get trashed web link Permanently remove web link Restore web link Restores a web link that has been… # TrashedWebLinksManager - [Restore web link](#restore-web-link) - [Get trashed web link](#get-trashed-web-link) - [Permanently remove web link](#permanently-remove-web-link) ## Restore web link Restores a web link that has been moved to the trash. An optional new parent ID can be provided to restore the web link to in case the original folder has been deleted. This operation is performed by calling function `restoreWeblinkFromTrash`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-web-links-id/). ``` await client.trashedWebLinks.restoreWeblinkFromTrash(weblink.id); ``` ### Arguments webLinkId `string` - The ID of the web link. Example: "12345" optionalsInput `RestoreWeblinkFromTrashOptionalsInput` ### Returns This function returns a value of type `TrashWebLinkRestored`. Returns a web link object when it has been restored. ## Get trashed web link Retrieves a web link that has been moved to the trash. This operation is performed by calling function `getTrashedWebLinkById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-web-links-id-trash/). ``` await client.trashedWebLinks.getTrashedWebLinkById(weblink.id); ``` ### Arguments webLinkId `string` - The ID of the web link. Example: "12345" optionalsInput `GetTrashedWebLinkByIdOptionalsInput` ### Returns This function returns a value of type `TrashWebLink`. Returns the web link that was trashed, including information about when the it was moved to the trash. ## Permanently remove web link Permanently deletes a web link that is in the trash. This action cannot be undone. This operation is performed by calling function `deleteTrashedWebLinkById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-web-links-id-trash/). ``` await client.trashedWebLinks.deleteTrashedWebLinkById(weblink.id); ``` ### Arguments webLinkId `string` - The ID of the web link. Example: "12345" optionalsInput `DeleteTrashedWebLinkByIdOptionalsInput` ### Returns This function returns a value of type `undefined`. Returns an empty response when the web link was permanently deleted. --- ### TrashedWebLinksManager **Type:** page | **Section:** Additional Resources TrashedWebLinksManager Restore web link Get trashed web link Permanently remove web link Restore web link Restores a web link that has been… # TrashedWebLinksManager - [Restore web link](#restore-web-link) - [Get trashed web link](#get-trashed-web-link) - [Permanently remove web link](#permanently-remove-web-link) ## Restore web link Restores a web link that has been moved to the trash. An optional new parent ID can be provided to restore the web link to in case the original folder has been deleted. This operation is performed by calling function `restore_weblink_from_trash`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-web-links-id/). ``` client.trashed_web_links.restore_weblink_from_trash(weblink.id) ``` ### Arguments web_link_id `str` - The ID of the web link. Example: "12345" name `Optional[str]` - An optional new name for the web link. parent `Optional[RestoreWeblinkFromTrashParent]` fields `Optional[List[str]]` - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `TrashWebLinkRestored`. Returns a web link object when it has been restored. ## Get trashed web link Retrieves a web link that has been moved to the trash. This operation is performed by calling function `get_trashed_web_link_by_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-web-links-id-trash/). ``` client.trashed_web_links.get_trashed_web_link_by_id(weblink.id) ``` ### Arguments web_link_id `str` - The ID of the web link. Example: "12345" fields `Optional[List[str]]` - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `TrashWebLink`. Returns the web link that was trashed, including information about when the it was moved to the trash. ## Permanently remove web link Permanently deletes a web link that is in the trash. This action cannot be undone. This operation is performed by calling function `delete_trashed_web_link_by_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-web-links-id-trash/). ``` client.trashed_web_links.delete_trashed_web_link_by_id(weblink.id) ``` ### Arguments web_link_id `str` - The ID of the web link. Example: "12345" extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `None`. Returns an empty response when the web link was permanently deleted. --- ### Untitled **Type:** page | **Section:** Additional Resources The Box Python SDK is an open source project supported by Box used to interact with the Box API. This is a list of contributors. @Jeff… The Box Python SDK is an open source project supported by [Box](https://box.com) used to interact with the Box API. This is a list of contributors. - [@Jeff-Meadows](https://github.com/Jeff-Meadows) - [@jmoldow](https://github.com/jmoldow) - [@aptxkid](https://github.com/aptxkid) - [@hnguyen08](https://github.com/hnguyen08) - [@potrebic](https://github.com/potrebic) - [@nsundareswaran](https://github.com/nsundareswaran) - [@kelseymorris95](https://github.com/kelseymorris95) - [@sp4x](https://github.com/sp4x) - [@capk1rk](https://github.com/capk1rk) - [@aculler](https://github.com/aculler) - [@ben-reilly](https://github.com/ben-reilly) - [@ab](https://github.com/ab) --- ### Upgrading from 4.x.x to 5.x.x **Type:** page | **Section:** Additional Resources Upgrading from 4.x.x to 5.x.x Follow the General changes to see the changes that are package indenpendent. Also refer to the Box.V2 or Box.V… # Upgrading from 4.x.x to 5.x.x Follow the [General changes](#general-changes) to see the changes that are package indenpendent. Also refer to the [Box.V2](#box-v2) or [Box.V2.Core](#box-v2-core) section depending on the package you are using. ## General changes ### Removed deprecated methods Some old, deprecated methods have been removed from version 5.x.x. Read this section further to see a new, alternative methods. #### BoxMetadataManager/IBoxMetadataManager ``` //Old ExecuteMetadataQueryAsync(string from, string ancestorFolderId, IEnumerable<string> fields, string query, Dictionary<string, object> queryParameters, string indexName, List<BoxMetadataQueryOrderBy> orderBy, int limit, string marker, bool autoPaginate) ExecuteMetadataQueryAsync(string from, string ancestorFolderId, string query = null, Dictionary<string, object> queryParameters = null, string indexName = null, List<BoxMetadataQueryOrderBy> orderBy = null, int limit = 100, string marker = null, bool autoPaginate = false) //New ExecuteMetadataQueryAsync(BoxMetadataQueryRequest queryRequest) ``` #### BoxConfigBuilder/IBoxConfigBuilder ``` //Old SetBoxApiUri(...) SetBoxTokenApiUri(...) //New SetBoxApiHostUri(...) ``` #### BoxFilesManager/IBoxFilesManager ``` //Old DownloadStreamAsync(...) //New DownloadAsync(...) ``` ``` //Old UploadFileVersionUsingSessionAsync(...) //New UploadNewVersionUsingSessionAsync(...) ``` ``` //Old GetCollaborationsAsync(...) //New GetCollaborationsCollectionAsync(...) ``` ``` //Old GetFilePreviewAsync(...) GetPreviewAsync(...) //New GetPreviewLinkAsync(...) ``` #### BoxSearchManager/IBoxSearchManager ``` //Old SearchAsync(...) //New QueryAsync(...) ``` #### BoxFolderManager/IBoxFolderManager ``` //Old GetTrashItemsAsync(string id, int limit, int offset = 0, IEnumerable<string> fields = null) //New GetTrashItemsAsync(int limit, int offset = 0, IEnumerable<string> fields = null, bool autoPaginate = false, string sort = null, BoxSortDirection? direction = null) ``` ``` //Old GetItemsAsync(...) //New GetFolderItemsAsync(...) ``` #### BoxTermsOfServiceManager/IBoxTermsOfServiceManager ``` //Old CreateBoxTermsOfServiceUserStatusesAsync(BoxTermsOfServiceUserStatusesRequest termsOfServicesUserStatusesRequest) //New CreateBoxTermsOfServiceUserStatusesAsync(BoxTermsOfServiceUserStatusCreateRequest termsOfServiceUserStatusCreateRequest) ``` #### OAuthSession ``` //Old OAuthSession(string access_token, string refresh_token, int expires_in, string token_type, AuthVersion authVersion) //New OAuthSession(string access_token, string refresh_token, int expires_in, string token_type) ``` #### BoxRetentionPoliciesManager/IBoxRetentionPoliciesManager ``` //Old Task<BoxCollectionMarkerBased<BoxFileVersion>> GetFileVersionsUnderRetentionForAssignmentAsync(...) //New Task<BoxCollectionMarkerBased<BoxFile>> GetFileVersionsUnderRetentionForAssignmentAsync(...) ``` ### Deprecated fields Some old, deprecated fields have been removed from version 5.x.x. Read this section further to see a new, alternative fields. #### BoxConfigBuilder/IBoxConfigBuilder ``` //Old BoxAuthTokenApiUri //New BoxApiHostUri ``` #### Constants ``` //Old MasterInviteAccept //New AdminInviteAccept ``` ``` //Old MasterInviteReject //New AdminInviteReject ``` ``` //Old V1AuthString //New //V1 Auth is no longer support in the API. ``` #### IBoxConfig ``` //Old BoxAuthTokenApiUri //New BoxApiHostUri ``` #### BoxPermissionsRequest ``` //Old BoxPermissionType? Preview //New //Deprecated field. Value is always true ``` #### OAuthSession ``` //Old AuthVersion //New //Box API have now one auth version so there is no need to differentiate between them. ``` #### BoxFileVersion ``` //Old BoxFileVersion //New //No alternative as this field was used only in GetFileVersionsUnderRetentionForAssignmentAsync(...). //This method now returns proper BoxFile object instead. ``` ## Box.V2 ### Minimal .NET runtime version upgrade If you are still using .NET Framework version lower than 4.6.2 you need to upgrade to the 4.6.2+ version. You can do it by changing target framework in the .csproj file of your project. For SDK-style projects Before ``` <TargetFramework>net45<TargetFramework/> ``` After ``` <TargetFramework>net462<TargetFramework/> ``` See [SDK-style target framework](https://learn.microsoft.com/en-us/dotnet/standard/frameworks) for more information. For non SDK-style projects Before ``` <TargetFrameworkVersion>v4.5</TargetFrameworkVersion> ``` After ``` <TargetFrameworkVersion>v4.6.2</TargetFrameworkVersion> ``` See [MSBuild target framework](https://learn.microsoft.com/en-us/visualstudio/msbuild/msbuild-target-framework-and-target-platform?view=vs-2022) for more information We recommend to upgrade to the newest version possible. See [.NET Framework lifecycle](https://learn.microsoft.com/en-us/lifecycle/products/microsoft-net-framework) ## Box.V2.Core No changes --- ### Upgrading to v4 **Type:** page | **Section:** Additional Resources Upgrading to v4 v4 of the Box Java SDK introduces a lot of new design changes. Since this is a major version bump, there will be breaking… # Upgrading to v4 v4 of the Box Java SDK introduces a lot of new design changes. Since this is a major version bump, there will be breaking changes that will require you to update your application. ## What's New ### Features **Automatic rate-limiting and error retry.** API requests will automatically be retried with exponential back off if a 500+ (server error) or 429 (too many requests) response code is returned. **OAuth redesign.** OAuth should now be easier to use, allowing you to authenticate with an access token, auth code, or developer token. **New EventStream class.** This class makes it easier to listen for API events by allowing you to specify listeners that will be notified when an event occurs. **New classes for making custom API requests.** The BoxAPIRequest and BoxAPIResponse classes make it easy to send custom requests to the API while still having OAuth, rate-limiting back off, error handling and response parsing automatically handled. ### General Improvements **Simpler and more intuitive design.** We aimed to make the overall design of the SDK more intuitive and easier to learn. **More documentation and examples.** The Javadocs have been completely overhauled and there are new guides explaining how to accomplish common tasks with the SDK. **SDK size has been dramatically decreased.** Many of the SDK's dependencies have been removed and its overall size has been reduced - making it more suitable for mobile apps. **Easier integration.** With a single build process, it's easier and simpler to get the SDK building with other applications. It also follows the standard directory layout, making it easier to import into various IDEs or build systems. ## Authentication Authentication has been simplified by allowing you to provide tokens or auth codes directly. All authentication is now done by creating a `BoxAPIConnection` in order to establish an authenticated connection with the API. Connect to the API using a developer token: ``` BoxAPIConnection api = new BoxAPIConnection("YOUR-DEVELOPER-TOKEN"); ``` Connect to the API using access and refresh tokens: ``` BoxAPIConnection api = new BoxAPIConnection("CLIENT-ID", "CLIENT-SECRET", "ACCESS-TOKEN", "REFRESH-TOKEN"); ``` Connect to the API using an auth code: ``` BoxAPIConnection api = new BoxAPIConnection("CLIENT-ID", "CLIENT-SECRET", "AUTH-CODE"); ``` More information on authentication can be found [here](https://ja.developer.box.com/69a8a62320adb7087794d5bb03d56230/authentication.md). ## New Resource Types Previously, interaction with the API was done through managers and request objects. For example: ``` BoxClient client = new BoxClient(...); IBoxFilesManager filesManager = boxClient.getFilesManager(); BoxDefaultRequestObject requestObj = new BoxDefaultRequestObject(); requestObj.getRequestExtras().addField(BoxFile.FIELD_SHA1); requestObj.getRequestExtras().addField(BoxFile.FIELD_DESCRIPTION); BoxFile file = filesManager.getFile(fileId, requestObj); ``` These objects have been removed and interacting with the API has been simplified. Resources can now be manipulated directly without needing to use managers or build custom requests. ``` BoxAPIConnection api = new BoxAPIConnection(...); BoxFile file = new BoxFile(api, fileID); BoxFile.Info fileInfo = file.getInfo("sha1", "description"); ``` More information on resource types can be found [here](resource-types.md). ## Custom Requests The SDK now provides request and response objects that allow you to easily make custom requests to the Box API. These objects will handle authentication, automatic retry, rate-limiting and errors out-of-the-box, giving you the flexibility to make your own API requests without having to worry about handling these things yourself. ``` BoxAPIConnection api = new BoxAPIConnection(...); URL url = new URL("https://api.box.com/2.0/folders/0/items?fields=name,created_at") BoxJSONRequest request = new BoxJSONRequest(api, url, "GET"); BoxJSONResponse response = (BoxJSONResponse) request.send(); String json = response.getJSON(); ``` More information on resource types can be found [here](https://ja.developer.box.com/7b374e99189519aca65b064deffbf92d/overview.md). --- ### UploadsManager **Type:** page | **Section:** Additional Resources UploadsManager Upload file version Preflight check before upload Upload file Upload file version Update a file's content. For file sizes… # UploadsManager - [Upload file version](#upload-file-version) - [Preflight check before upload](#preflight-check-before-upload) - [Upload file](#upload-file) ## Upload file version Update a file's content. For file sizes over 50MB we recommend using the Chunk Upload APIs. The `attributes` part of the body must come **before** the `file` part. Requests that do not follow this format when uploading the file will receive a HTTP `400` error with a `metadata_after_file_contents` error code. This operation is performed by calling function `uploadFileVersion`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-files-id-content/). ``` await client.uploads.uploadFileVersion(file.id, { attributes: { name: file.name!, } satisfies UploadFileVersionRequestBodyAttributesField, file: generateByteStream(20), } satisfies UploadFileVersionRequestBody); ``` ### Arguments fileId `string` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" requestBody `UploadFileVersionRequestBody` - Request body of uploadFileVersion method optionalsInput `UploadFileVersionOptionalsInput` ### Returns This function returns a value of type `Files`. Returns the new file object in a list. ## Preflight check before upload Performs a check to verify that a file will be accepted by Box before you upload the entire file. This operation is performed by calling function `preflightFileUploadCheck`. See the endpoint docs at [API Reference](https://developer.box.com/reference/options-files-content/). ``` await client.uploads.preflightFileUploadCheck({ name: newFileName, size: 1024 * 1024, parent: { id: '0' } satisfies PreflightFileUploadCheckRequestBodyParentField, } satisfies PreflightFileUploadCheckRequestBody); ``` ### Arguments requestBody `PreflightFileUploadCheckRequestBody` - Request body of preflightFileUploadCheck method headersInput `PreflightFileUploadCheckHeadersInput` - Headers of preflightFileUploadCheck method cancellationToken `undefined | CancellationToken` - Token used for request cancellation. ### Returns This function returns a value of type `UploadUrl`. If the check passed, the response will include a session URL that can be used to upload the file to. ## Upload file Uploads a small file to Box. For file sizes over 50MB we recommend using the Chunk Upload APIs. The `attributes` part of the body must come **before** the `file` part. Requests that do not follow this format when uploading the file will receive a HTTP `400` error with a `metadata_after_file_contents` error code. This operation is performed by calling function `uploadFile`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-files-content/). ``` const fs = require('fs'); const attrs = { name: 'filename.txt', parent: { id: '0' } }; const body = { attributes: attrs, file: fs.createReadStream('filename.txt'), }; const files = await client.uploads.uploadFile(body); const file = files.entries[0]; console.log(`File uploaded with id ${file.id}, name ${file.name}`); ``` ### Arguments requestBody `UploadFileRequestBody` - Request body of uploadFile method ## optionalsInput UploadFileOptionalsInput ### Returns This function returns a value of type `Files`. Returns the new file object in a list. --- ### UploadsManager **Type:** page | **Section:** Additional Resources UploadsManager Upload file version Preflight check before upload Upload file Upload a file with a preflight check Upload file version Update… # UploadsManager - [Upload file version](#upload-file-version) - [Preflight check before upload](#preflight-check-before-upload) - [Upload file](#upload-file) - [Upload a file with a preflight check](#upload-a-file-with-a-preflight-check) ## Upload file version Update a file's content. For file sizes over 50MB we recommend using the Chunk Upload APIs. The `attributes` part of the body must come **before** the `file` part. Requests that do not follow this format when uploading the file will receive a HTTP `400` error with a `metadata_after_file_contents` error code. This operation is performed by calling function `upload_file_version`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-files-id-content/). ``` client.uploads.upload_file_version( uploaded_file.id, UploadFileVersionAttributes(name=new_file_version_name), new_file_content_stream, ) ``` ### Arguments file_id `str` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" attributes `UploadFileVersionAttributes` - The additional attributes of the file being uploaded. Mainly the name and the parent folder. These attributes are part of the multi part request body and are in JSON format. The `attributes` part of the body must come **before** the `file` part. Requests that do not follow this format when uploading the file will receive a HTTP `400` error with a `metadata_after_file_contents` error code. file `ByteStream` - The content of the file to upload to Box. The `attributes` part of the body must come **before** the `file` part. Requests that do not follow this format when uploading the file will receive a HTTP `400` error with a `metadata_after_file_contents` error code. file_file_name `Optional[str]` file_content_type `Optional[str]` fields `Optional[List[str]]` - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested. if_match `Optional[str]` - Ensures this item hasn't recently changed before making changes. Pass in the item's last observed `etag` value into this header and the endpoint will fail with a `412 Precondition Failed` if it has changed since. content_md_5 `Optional[str]` - An optional header containing the SHA1 hash of the file to ensure that the file was not corrupted in transit. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `Files`. Returns the new file object in a list. ## Preflight check before upload Performs a check to verify that a file will be accepted by Box before you upload the entire file. This operation is performed by calling function `preflight_file_upload_check`. See the endpoint docs at [API Reference](https://developer.box.com/reference/options-files-content/). ``` client.uploads.preflight_file_upload_check( name=new_file_name, size=1024 * 1024, parent=PreflightFileUploadCheckParent(id="0") ) ``` ### Arguments name `Optional[str]` - The name for the file. size `Optional[int]` - The size of the file in bytes. parent `Optional[PreflightFileUploadCheckParent]` extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `UploadUrl`. If the check passed, the response will include a session URL that can be used to upload the file to. ## Upload file Uploads a small file to Box. For file sizes over 50MB we recommend using the Chunk Upload APIs. The `attributes` part of the body must come **before** the `file` part. Requests that do not follow this format when uploading the file will receive a HTTP `400` error with a `metadata_after_file_contents` error code. This operation is performed by calling function `upload_file`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-files-content/). ``` client.uploads.upload_file( UploadFileAttributes( name=new_file_name, parent=UploadFileAttributesParentField(id="0") ), file_content_stream, ) ``` ### Arguments attributes `UploadFileAttributes` - The additional attributes of the file being uploaded. Mainly the name and the parent folder. These attributes are part of the multi part request body and are in JSON format. The `attributes` part of the body must come **before** the `file` part. Requests that do not follow this format when uploading the file will receive a HTTP `400` error with a `metadata_after_file_contents` error code. file `ByteStream` - The content of the file to upload to Box. The `attributes` part of the body must come **before** the `file` part. Requests that do not follow this format when uploading the file will receive a HTTP `400` error with a `metadata_after_file_contents` error code. file_file_name `Optional[str]` file_content_type `Optional[str]` fields `Optional[List[str]]` - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested. content_md_5 `Optional[str]` - An optional header containing the SHA1 hash of the file to ensure that the file was not corrupted in transit. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `Files`. Returns the new file object in a list. ## Upload a file with a preflight check Upload a file with a preflight check This operation is performed by calling function `upload_with_preflight_check`. ``` client.uploads.upload_with_preflight_check( UploadWithPreflightCheckAttributes( name=new_file_name, size=-1, parent=UploadWithPreflightCheckAttributesParentField(id="0"), ), file_content_stream, ) ``` ### Arguments - attributes `UploadWithPreflightCheckAttributes` file `ByteStream` - The content of the file to upload to Box. The `attributes` part of the body must come **before** the `file` part. Requests that do not follow this format when uploading the file will receive a HTTP `400` error with a `metadata_after_file_contents` error code. file_file_name `Optional[str]` file_content_type `Optional[str]` fields `Optional[List[str]]` - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested. content_md_5 `Optional[str]` - An optional header containing the SHA1 hash of the file to ensure that the file was not corrupted in transit. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `Files`. --- ### UserCollaborationsManager **Type:** page | **Section:** Additional Resources UserCollaborationsManager Get collaboration Update collaboration Remove collaboration Create collaboration Get collaboration Retrieves a… # UserCollaborationsManager - [Get collaboration](#get-collaboration) - [Update collaboration](#update-collaboration) - [Remove collaboration](#remove-collaboration) - [Create collaboration](#create-collaboration) ## Get collaboration Retrieves a single collaboration. This operation is performed by calling function `getCollaborationById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-collaborations-id/). ``` await client.userCollaborations.getCollaborationById(collaborationId); ``` ### Arguments collaborationId `string` - The ID of the collaboration. Example: "1234" optionalsInput `GetCollaborationByIdOptionalsInput` ### Returns This function returns a value of type `Collaboration`. Returns a collaboration object. ## Update collaboration Updates a collaboration. Can be used to change the owner of an item, or to accept collaboration invites. This operation is performed by calling function `updateCollaborationById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-collaborations-id/). ``` await client.userCollaborations.updateCollaborationById(collaborationId, { role: 'viewer' as UpdateCollaborationByIdRequestBodyRoleField, } satisfies UpdateCollaborationByIdRequestBody); ``` ### Arguments collaborationId `string` - The ID of the collaboration. Example: "1234" requestBody `UpdateCollaborationByIdRequestBody` - Request body of updateCollaborationById method optionalsInput `UpdateCollaborationByIdOptionalsInput` ### Returns This function returns a value of type `undefined | Collaboration`. Returns an updated collaboration object unless the owner has changed.If the role is changed to `owner`, the collaboration is deleted and a new collaboration is created. The previous `owner` of the old collaboration will be a `co-owner` on the new collaboration. ## Remove collaboration Deletes a single collaboration. This operation is performed by calling function `deleteCollaborationById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-collaborations-id/). ``` await client.userCollaborations.deleteCollaborationById(collaborationId); ``` ### Arguments collaborationId `string` - The ID of the collaboration. Example: "1234" optionalsInput `DeleteCollaborationByIdOptionalsInput` ### Returns This function returns a value of type `undefined`. A blank response is returned if the collaboration was successfully deleted. ## Create collaboration Adds a collaboration for a single user or a single group to a file or folder. Collaborations can be created using email address, user IDs, or a group IDs. If a collaboration is being created with a group, access to this endpoint is dependent on the group's ability to be invited. If collaboration is in `pending` status, the following fields are redacted: `login` and `name` are hidden if a collaboration was created using `user_id`, - `name` is hidden if a collaboration was created using `login`. This operation is performed by calling function `createCollaboration`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-collaborations/). ``` await client.userCollaborations.createCollaboration({ item: { type: 'folder' as CreateCollaborationRequestBodyItemTypeField, id: folder.id, } satisfies CreateCollaborationRequestBodyItemField, accessibleBy: { type: 'user' as CreateCollaborationRequestBodyAccessibleByTypeField, id: user.id, } satisfies CreateCollaborationRequestBodyAccessibleByField, role: 'editor' as CreateCollaborationRequestBodyRoleField, } satisfies CreateCollaborationRequestBody); ``` ### Arguments requestBody `CreateCollaborationRequestBody` - Request body of createCollaboration method optionalsInput `CreateCollaborationOptionalsInput` ### Returns This function returns a value of type `Collaboration`. Returns a new collaboration object. --- ### UserCollaborationsManager **Type:** page | **Section:** Additional Resources UserCollaborationsManager Get collaboration Update collaboration Remove collaboration Create collaboration Get collaboration Retrieves a… # UserCollaborationsManager - [Get collaboration](#get-collaboration) - [Update collaboration](#update-collaboration) - [Remove collaboration](#remove-collaboration) - [Create collaboration](#create-collaboration) ## Get collaboration Retrieves a single collaboration. This operation is performed by calling function `get_collaboration_by_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-collaborations-id/). ``` client.user_collaborations.get_collaboration_by_id(collaboration_id) ``` ### Arguments collaboration_id `str` - The ID of the collaboration. Example: "1234" fields `Optional[List[str]]` - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `Collaboration`. Returns a collaboration object. ## Update collaboration Updates a collaboration. Can be used to change the owner of an item, or to accept collaboration invites. This operation is performed by calling function `update_collaboration_by_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-collaborations-id/). ``` client.user_collaborations.update_collaboration_by_id( collaboration_id, UpdateCollaborationByIdRole.VIEWER ) ``` ### Arguments collaboration_id `str` - The ID of the collaboration. Example: "1234" role `UpdateCollaborationByIdRole` - The level of access granted. status `Optional[UpdateCollaborationByIdStatus]` - Set the status of a `pending` collaboration invitation, effectively accepting, or rejecting the invite. expires_at `Optional[DateTime]` - Update the expiration date for the collaboration. At this date, the collaboration will be automatically removed from the item. This feature will only work if the **Automatically remove invited collaborators: Allow folder owners to extend the expiry date** setting has been enabled in the **Enterprise Settings** of the **Admin Console**. When the setting is not enabled, collaborations can not have an expiry date and a value for this field will be result in an error. Additionally, a collaboration can only be given an expiration if it was created after the **Automatically remove invited collaborator** setting was enabled. can_view_path `Optional[bool]` - Determines if the invited users can see the entire parent path to the associated folder. The user will not gain privileges in any parent folder and therefore can not see content the user is not collaborated on. Be aware that this meaningfully increases the time required to load the invitee's **All Files** page. We recommend you limit the number of collaborations with `can_view_path` enabled to 1,000 per user. Only owner or co-owners can invite collaborators with a `can_view_path` of `true`. `can_view_path` can only be used for folder collaborations. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `Optional[Collaboration]`. Returns an updated collaboration object unless the owner has changed.If the role is changed to `owner`, the collaboration is deleted and a new collaboration is created. The previous `owner` of the old collaboration will be a `co-owner` on the new collaboration. ## Remove collaboration Deletes a single collaboration. This operation is performed by calling function `delete_collaboration_by_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-collaborations-id/). ``` client.user_collaborations.delete_collaboration_by_id(collaboration_id) ``` ### Arguments collaboration_id `str` - The ID of the collaboration. Example: "1234" extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `None`. A blank response is returned if the collaboration was successfully deleted. ## Create collaboration Adds a collaboration for a single user or a single group to a file or folder. Collaborations can be created using email address, user IDs, or a group IDs. If a collaboration is being created with a group, access to this endpoint is dependent on the group's ability to be invited. If collaboration is in `pending` status, the following fields are redacted: `login` and `name` are hidden if a collaboration was created using `user_id`, - `name` is hidden if a collaboration was created using `login`. This operation is performed by calling function `create_collaboration`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-collaborations/). ``` client.user_collaborations.create_collaboration( CreateCollaborationItem(type=CreateCollaborationItemTypeField.FOLDER, id=folder.id), CreateCollaborationAccessibleBy( type=CreateCollaborationAccessibleByTypeField.USER, id=user.id ), CreateCollaborationRole.EDITOR, ) ``` ### Arguments item `CreateCollaborationItem` - The item to attach the comment to. accessible_by `CreateCollaborationAccessibleBy` - The user or group to give access to the item. role `CreateCollaborationRole` - The level of access granted. is_access_only `Optional[bool]` - If set to `true`, collaborators have access to shared items, but such items won't be visible in the All Files list. Additionally, collaborators won't see the the path to the root folder for the shared item. can_view_path `Optional[bool]` - Determines if the invited users can see the entire parent path to the associated folder. The user will not gain privileges in any parent folder and therefore can not see content the user is not collaborated on. Be aware that this meaningfully increases the time required to load the invitee's **All Files** page. We recommend you limit the number of collaborations with `can_view_path` enabled to 1,000 per user. Only owner or co-owners can invite collaborators with a `can_view_path` of `true`. `can_view_path` can only be used for folder collaborations. expires_at `Optional[DateTime]` - Set the expiration date for the collaboration. At this date, the collaboration will be automatically removed from the item. This feature will only work if the **Automatically remove invited collaborators: Allow folder owners to extend the expiry date** setting has been enabled in the **Enterprise Settings** of the **Admin Console**. When the setting is not enabled, collaborations can not have an expiry date and a value for this field will be result in an error. fields `Optional[List[str]]` - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested. notify `Optional[bool]` - Determines if users should receive email notification for the action performed. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `Collaboration`. Returns a new collaboration object. --- ### Users **Type:** page | **Section:** Additional Resources Users Users represent an individual's account on Box. Get User's Information Get the Current User's Information Get User Avatar Set User… # Users Users represent an individual's account on Box. - [Get User's Information](#get-users-information) - [Get the Current User's Information](#get-the-current-users-information) - [Get User Avatar](#get-user-avatar) - [Set User Avatar](#set-user-avatar) - [Delete User Avatar](#delete-user-avatar) - [Update User](#update-user) - [Delete User](#delete-user) - [Get Email Aliases](#get-email-aliases) - [Add Email Alias](#add-email-alias) - [Delete Email Alias](#delete-email-alias) ## Get User's Information To get a user call the [`users.get(userID, options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Users.html#get) method. ``` client.users.get('33333') .then(user => { /* user -> { type: 'user', id: '33333', name: 'Example User', login: 'user@example.com', created_at: '2012-03-26T15:43:07-07:00', modified_at: '2012-12-12T11:34:29-08:00', language: 'en', space_amount: 5368709120, space_used: 2377016, max_upload_size: 262144000, status: 'active', job_title: 'Employee', phone: '5555555555', address: '555 Office Drive', avatar_url: 'https://app.box.com/api/avatar/deprecated' } */ }); ``` Requesting information for only the fields you need with the `fields` option can improve performance and reduce the size of the network request. ``` // Only get information about a few specific fields. client.users.get('123', {fields: 'name,login'}) .then(user => { /* user -> { type: 'user', id: '33333', name: 'Example User', login: 'user@example.com' } */ }); ``` ## Get the Current User's Information To get the current user call the [`users.get(userID, options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Users.html#get) method with the `CURRENT_USER_ID` constant. ``` client.users.get(client.CURRENT_USER_ID) .then(currentUser => { /* currentUser -> { type: 'user', id: '33333', name: 'Example User', login: 'user@example.com', created_at: '2012-03-26T15:43:07-07:00', modified_at: '2012-12-12T11:34:29-08:00', language: 'en', space_amount: 5368709120, space_used: 2377016, max_upload_size: 262144000, status: 'active', job_title: 'Employee', phone: '5555555555', address: '555 Office Drive', avatar_url: 'https://app.box.com/api/avatar/deprecated' } */ }); ``` ## Get User Avatar Calling [`users.getAvatar(userID, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Users.html#getAvatar) will yield a `Readable` stream over the bytes of the user's avatar image. ``` client.users.getAvatar('22222') .then(avatarImageStream => { avatarImageStream.on('data', bytes => { // read avatar image bytes }); }); ``` ## Set User Avatar Calling [`users.setAvatar(userID, avatar, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Users.html#setAvatar) will set user's avatar with the input file. ``` const fs = require('fs'); var readStream = fs.createReadStream('image.jpg'); client.users.setAvatar('22222', readStream).then(result => { // read avatar urls }); ``` ## Delete User Avatar Calling [`users.deleteAvatar(userID, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Users.html#deleteAvatar) will delete the user's avatar. ``` client.users.deleteAvatar('22222', () => { console.log('User avatar deleted!'); }); ``` ## Update User To update a user call the [`users.update(userID, updates, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Users.html#update) method where `updates` contains the fields to update. ``` client.users.update('33333', {name: 'New Name', job_title: 'New Title', phone: '555-1111'}) .then(user => { /* user -> { type: 'user', id: '33333', name: 'New Name', login: 'user@example.com', created_at: '2012-03-26T15:43:07-07:00', modified_at: '2012-12-12T11:34:29-08:00', language: 'en', space_amount: 5368709120, space_used: 2377016, max_upload_size: 262144000, status: 'active', job_title: 'New Title', phone: '555-1111', address: '555 Office Drive', avatar_url: 'https://app.box.com/api/avatar/deprecated' } */ }); ``` To change a user's login email, update the `login` parameter on the user. Note that the new email address must already be added as a verified email alias for the user. ``` client.users.update('33333', { login: 'newemail@example.com' }) .then(user => { /* user -> { type: 'user', id: '33333', name: 'New Name', login: 'newemail@example.com', created_at: '2012-03-26T15:43:07-07:00', modified_at: '2012-12-12T11:34:29-08:00', language: 'en', space_amount: 5368709120, space_used: 2377016, max_upload_size: 262144000, status: 'active', job_title: 'New Title', phone: '555-1111', address: '555 Office Drive', avatar_url: 'https://app.box.com/api/avatar/deprecated' } */ }); ``` ## Delete User To delete a user call the [`users.delete(userID, options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Users.html#delete) method. If the user still has files in their account and the `force` parameter is not sent, an error is returned. ``` client.users.delete('33333') .then(() => { // deletion succeeded — no value returned }); ``` ``` // Delete the user even if they still have files in their account client.users.delete('123', {force: true}) .then(() => { // deletion succeeded — no value returned }); ``` ## Get Email Aliases To get a users email aliases call the [`users.getEmailAliases(userID, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Users.html#getEmailAliases) method. ``` client.users.getEmailAliases('33333') .then(emailAliases => { /* emailAliases -> { total_count: 2, entries: [ { type: 'email_alias', id: '1234', is_confirmed: true, email: 'user+foo@example.com' }, { type: 'email_alias', id: '1235', is_confirmed: true, email: 'user+bar@example.com' } ] } */ }); ``` ## Add Email Alias To add an email alias for a user call the [`users.addEmailAlias(userID, email, callback`](http://opensource.box.com/box-node-sdk/jsdoc/Users.html#addEmailAlias) method. ``` client.users.addEmailAlias('33333', 'user+baz@example.com') .then(alias => { /* alias -> { type: 'email_alias', id: '12345', is_confirmed: false, email: 'user+baz@example.com' } */ }); ``` Enterprise admins can automatically confirm the email alias via the `is_confirmed` option: ``` client.users.addEmailAlias('33333', 'user+quux@example.com', {is_confirmed: true}) .then(alias => { /* alias -> { type: 'email_alias', id: '12346', is_confirmed: true, email: 'user+quux@example.com' } */ }); ``` ## Delete Email Alias To delete a users email alias call the [`users.removeEmailAlias(userID, aliasID, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Users.html#removeEmailAlias) method. ``` var userID = '33333'; var aliasID = '12345'; client.users.removeEmailAlias(userID, aliasID) .then(() => { // removal successful — no value returned }); ``` ## Terminate users session To terminate user's sessions call the [`users.terminateSession(options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Users.html#terminateSession) method. ``` var userIDs = ['33333', '44444']; var userLogins = ['user1@example.com', 'user2@example.com']; client.users.terminateSession({ user_ids: userIDs, user_logins: userLogins }).then((result) => { /* result -> { message: "Request is successful, please check the admin events for the status of the job" } */ }); ``` --- ### Users **Type:** page | **Section:** Additional Resources Users Users represent an individual's account on Box. Get the Current User's Information Get User Information Get Avatar for a User Add or… # Users Users represent an individual's account on Box. - [Get the Current User's Information](#get-the-current-users-information) - [Get User Information](#get-user-information) - [Get Avatar for a User](#get-avatar-for-a-user) - [Add or update user avatar](#add-or-update-user-avatar) - [Delete user avatar](#delete-user-avatar) - [Create An Enterprise User](#create-an-enterprise-user) - [Create An App User](#create-an-app-user) - [Update User](#update-user) - [Delete User](#delete-user) - [Invite User](#invite-user) - [Get Email Aliases](#get-email-aliases) - [Add Email Alias](#add-email-alias) - [Delete Email Alias](#delete-email-alias) - [Get Enterprise Users](#get-enterprise-users) - [Get Enterprise Users (Marker Pagination)](#get-enterprise-users-marker-pagination) - [Get App Users By External App User ID](#get-app-users-by-external-app-user-id) - [Get App Users By External App User ID (Marker Pagination)](#get-app-users-by-external-app-user-id-marker-pagination) - [Move User's Folder](#move-users-folder) ## Get the Current User's Information To get the current user, call the static [`getCurrentUser(BoxAPIConnection api)`](https://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxUser.html#getCurrentUser-com.box.sdk.BoxAPIConnection-) method. Then use [`getInfo(String... fields)`](https://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxUser.html#getInfo-java.lang.String...-) to get information about the user. ``` BoxUser user = BoxUser.getCurrentUser(api); BoxUser.Info info = user.getInfo(); ``` ## Get User Information To get information about a user, call the [`getInfo()`](https://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxUser.html#getInfo-java.lang.String...-) method on the user object. ``` String userID = "33333"; BoxUser user = new BoxUser(api, userID); BoxUser.Info userInfo = user.getInfo(); ``` ## Get Avatar for a User To retrieve the avatar for a User, call the [`downloadAvatar(OutputStream stream)`](https://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxUser.html#downloadAvatar-java.io.OutputStream-) method on the user object. ``` String userID = "33333"; // some stream do download avatar try (ByteArrayOutputStream outputStream = new ByteArrayOutputStream()){ BoxUser user=new BoxUser(api,userID); user.downloadAvatar(outputStream); } catch (IOException e) { throw new RuntimeException(e); } ``` ## Add or update user avatar To add or update the avatar for a User, call the [`uploadAvatar(File)`](https://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxUser.html#uploadAvatar-java.io.File-) method on the user object. ``` String userID = "33333"; BoxUser user = new BoxUser(api, userID); AvatarUploadResponse response = user.uploadAvatar(new File("path_to_avatar_file")); ``` In return, you will get an object with links to several representations of an avatar within Box account. Your image file should have correct extension, it is used to determine image type used in upload. Supported formats are JPG and PNG. The image size cannot exceed 1024 * 1024 pixels or 1MB. You can upload avatart using `InputStream` with [`uploadAvatar(InputStream, String)`](https://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxUser.html#uploadAvatar-java.io.InputStream-java.lang.String-): ``` String userID = "33333"; BoxUser user = new BoxUser(api, userID); AvatarUploadResponse response = user.uploadAvatar(Files.newInputStream(Paths.get("path_to_avatar_file")), "file_name.jpeg"); ``` Both upload methods supports [`ProgressListener`](https://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/ProgressListener.html). ## Delete user avatar To delete User avatar image use [`deleteAvatar()`](https://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxUser.html#deleteAvatar--) method on the user object: ``` String userID = "33333"; BoxUser user = new BoxUser(api, userID); user.deleteAvatar(); ``` ## Create An Enterprise User To create an enterprise user, call the [`createEnterpriseUser(BoxAPIConnection api, String loginEmail, String userName, String... fields)`](https://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxUser.html#createEnterpriseUser-com.box.sdk.BoxAPIConnection-java.lang.String-java.lang.String-java.lang.String...-). To pass additional optional parameters, use the [`createEnterpriseUser(BoxAPIConnection api, String loginEmail, String userName, CreateUserParams options, String... fields)`](https://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxUser.html#createAppUser-com.box.sdk.BoxAPIConnection-java.lang.String-com.box.sdk.CreateUserParams-java.lang.String...-) method. ``` BoxUser.Info createdUserInfo = BoxUser.createEnterpriseUser(api, "user@example.com", "A User"); ``` ## Create An App User To create an app user, call the [`createAppUser(BoxAPIConnection api, String userName, String... fields)`](https://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxUser.html#createAppUser-com.box.sdk.BoxAPIConnection-java.lang.String-java.lang.String...-) method. To pass additional optional parameters, use the [`createAppUser(BoxAPIConnection api, String userName, CreateUserParams options, String... fields)`](https://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxUser.html#createAppUser-com.box.sdk.BoxAPIConnection-java.lang.String-com.box.sdk.CreateUserParams-java.lang.String...-) method. ``` BoxUser.Info createdUserInfo = BoxUser.createAppUser(api, "A User"); ``` ``` CreateUserParams params = new CreateUserParams(); params.setExternalAppUserId("An Identifier Like Login"); BoxUser.Info createdUserInfo = BoxUser.createAppUser(api, "A User", params); ``` ## Update User To update a user call the [`updateInfo(BoxUser.Info fieldsToUpdate, String... fields)`](https://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxUser.html#updateInfo-com.box.sdk.BoxUser.Info-java.lang.String...-) method. ``` BoxUser user = new BoxUser(api, "0"); BoxUser.Info info = user.new Info(); info.setName(name); user.updateInfo(info); ``` ## Delete User To delete a user call the [`delete(boolean notifyUser, boolean force)`](https://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxUser.html#delete-boolean-boolean-) method or one that uses API default parameters [`delete()](https://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxUser.html#delete--) The `notifyUser` determines whether the user should receive an email about the deletion, and the `force` parameter will cause the user to be deleted even if they still have files in their account. ``` BoxUser user = new BoxUser(api, "0"); user.delete(false, false); ``` ## Invite User To invite an existing user to join an Enterprise call the [`inviteUser(String enterpriseID, String userEmail)`](https://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxUser.html#inviteUser-java.lang.String-java.lang.String-) method. ``` BoxUser user = new BoxUser(api, "0"); user.invite("Enterprise ID", "Invited User Login"); ``` ## Get Email Aliases To get a user's email aliases call the [`getEmailAliases()`](https://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxUser.html#getEmailAliases--) method. ``` BoxUser user = new BoxUser(api, "0"); Collection<EmailAlias> emailAliases = user.getEmailAliases(); ``` ## Add Email Alias To add an email alias for a user, call the [`addEmailAlias(String emailAddress)`](https://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxUser.html#addEmailAlias-java.lang.String-) method. ``` BoxUser user = new BoxUser(api, "0"); user.addEmailAlias("user+alias@example.com"); ``` Enterprise admins can automatically confirm the new email alias by calling the [`addEmailAlias(String emailAddress, boolean confirm)`](https://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxUser.html#addEmailAlias-java.lang.String-boolean-) method: ``` BoxUser user = new BoxUser(api, "0"); user.addEmailAlias("user+alias@eexample.com", true); ``` ## Delete Email Alias To delete a users email alias call the [`deleteEmailAlias(String emailAliasID)`](https://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxUser.html#deleteEmailAlias-java.lang.String-) method. ``` BoxUser user = new BoxUser(api, "0"); user.deleteEmailAlias("123"); ``` ## Get Enterprise Users To get an enterprise's users call the [`getAllEnterpriseUsers(BoxAPIConnection api)`](https://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxUser.html#getAllEnterpriseUsers-com.box.sdk.BoxAPIConnection-), [`getAllEnterpriseUsers(BoxAPIConnection api, String filterTerm, String... fields)`](https://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxUser.html#getAllEnterpriseUsers-com.box.sdk.BoxAPIConnection-java.lang.String-java.lang.String...-), or [`getAllEnterpriseOrExternalUsers(BoxAPIConnection api, String filterTerm, String... fields)`](https://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxUser.html#getAllEnterpriseOrExternalUsers-com.box.sdk.BoxAPIConnection-java.lang.String-java.lang.String...-) method. ``` Iterable<BoxUser.Info> users = BoxUser.getAllEnterpriseUsers(api); ``` ## Get Enterprise Users (Marker Pagination) To get a list of all users in an enterprise, call the [`getAllEnterpriseUsers(BoxAPIConnection api, boolean usemarker, String marker)`](https://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxUser.html#getAllEnterpriseUsers-com.box.sdk.BoxAPIConnection-), [`getAllEnterpriseUsers(BoxAPIConnection api, String filterTerm, boolean usemarker, String marker, String... fields)`](https://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxUser.html#getAllEnterpriseUsers-com.box.sdk.BoxAPIConnection-java.lang.String-java.lang.String...-), or [`getAllEnterpriseOrExternalUsers(BoxAPIConnection api, String filterTerm, boolean usemarker, String marker, String... fields)`](https://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxUser.html#getAllEnterpriseOrExternalUsers-com.box.sdk.BoxAPIConnection-java.lang.String-java.lang.String...-) method. To get a list of users starting from the first page of results, set the `usemarker` parameter as `true` and the `marker` parameter as `null`. If you would like to get the marker for the next page of results from the page the iterator is currently on, you must cast the iterable to `BoxResourseIterable<BoxUser.info>` and call `getNextMarker()` on that iterable. For more information on marker pagination, look here: [https://developer.box.com/en/guides/api-calls/pagination/marker-based/](https://developer.box.com/en/guides/api-calls/pagination/marker-based/). ``` Iterable<BoxUser.Info> users = BoxUser.getAllEnterpriseUsers(api, true, null); // Get marker String marker = ((BoxResourceIterable<BoxUser.Info>) users).getNextMarker(); ``` ## Get App Users By External App User ID To get app user using external app user ID, call the [`getAppUsersByExternalAppUserID(BoxAPIConnection api, String externalID, String... fields)`](https://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxUser.html#getAppUsersByExternalAppUserID-com.box.sdk.BoxAPIConnection-java.lang.String-java.lang.String...-). This method allows you to easily associate Box app users with your application's identifiers for those users. ``` Iterable<BoxUser.Info> users = BoxUser.getAppUsersByExternalAppUserID(api, "external_app_user_id"); ``` ## Get App Users By External App User ID (Marker Pagination) To get app user using external app user ID, call the [`getAppUsersByExternalAppUserID(BoxAPIConnection api, String externalID, boolean usemarker, String marker, String... fields)`](https://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxUser.html#getAppUsersByExternalAppUserID-com.box.sdk.BoxAPIConnection-java.lang.String-java.lang.String...-). This method allows you to easily associate Box app users with your application's identifiers for those users. To get a list of users starting from the first page of results, set the `usemarker` parameter as `true` and the `marker` parameter as `null`. If you would like to get the marker for the next page of results from the page the iterator is currently on, you must cast the iterable to `BoxResourseIterable<BoxUser.info>` and call `getNextMarker()` on that iterable. For more information on marker pagination, look here: [https://developer.box.com/en/guides/api-calls/pagination/marker-based/](https://developer.box.com/en/guides/api-calls/pagination/marker-based/). ``` Iterable<BoxUser.Info> users = BoxUser.getAppUsersByExternalAppUserID(api, "external_app_user_id"); // Get marker String marker = ((BoxResourceIterable<BoxUser.Info>) users).getNextMarker(); ``` ## Move User's Folder To move all of a user's content to another user, call the [`transferContent(String destinationUserID)`](https://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxUser.html#transferContent-java.lang.String-) method. ``` String sourceUserID = "11111"; String destinationUserID = "22222"; BoxUser sourceUser = new BoxUser(api, sourceUserID); BoxFolder.Info transferredFolderInfo = sourceUser.transferContent(destinationUserID); ``` --- ### Users **Type:** page | **Section:** Additional Resources Users Users represent an individual's account on Box. Users Get User Information Get the Current User's Information Create An Enterprise… # Users Users represent an individual's account on Box. [Users](#users) - [Get User Information](#get-user-information) - [Get the Current User's Information](#get-the-current-users-information) - [Create An Enterprise User](#create-an-enterprise-user) - [Get the Avatar for a User](#get-the-avatar-for-a-user) - [Upload user avatar](#upload-user-avatar) - [Delete user avatar](#delete-user-avatar) - [Create An App User](#create-an-app-user) - [Update User](#update-user) - [Delete User](#delete-user) - [Invite User to Enterprise](#invite-user-to-enterprise) - [Get Email Aliases](#get-email-aliases) - [Add Email Alias](#add-email-alias) - [Remove Email Alias](#remove-email-alias) - [Get Enterprise Users](#get-enterprise-users) - [Transfer User Content](#transfer-user-content) ## Get User Information To get information about a user, call the [`user.get(*, fields=None, headers=None, **kwargs)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.base_object.BaseObject.get) method. This method returns a new [`User`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.user.User) object with fields populated by data from the API. ``` user_id = '33333' user = client.user(user_id).get() ``` You can specify which fields on the `User` object you want by passing an `Iterable` of field names: ``` user_id = '33333' user = client.user(user_id).get(['id', 'name', 'login', 'is_sync_enabled']) if user.is_sync_enabled: print(f'User {user.id} has sync enabled') ``` ## Get the Current User's Information To get the current user, call [`client.user(user_id='me')`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.client.html#boxsdk.client.client.Client.user) to create the [`User`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.user.User) object and then call [`user.get(*, fields=None, headers=None, **kwargs)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.base_object.BaseObject.get) to retrieve the user information from the API. ``` current_user = client.user().get() ``` ## Create An Enterprise User To create an enterprise user, call the [`client.create_user(name, login, **user_attributes)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.client.html#boxsdk.client.client.Client.create_user) method. This method returns a new [`User`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.user.User) object. ``` new_user = client.create_user('Temp User', 'user@example.com') ``` ## Get the Avatar for a User To get the avatar for a user call the [`user.get_avatar()`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.user.html#boxsdk.user.User.get_avatar) method with the [`User`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.user.User) object for the user you wish to retrieve an avatar for. This will return the user avatar to you in bytes. ``` avatar = client.user('33333').get_avatar() ``` ## Upload user avatar To add or update the avatar for a user, call the [`user.upload_avatar(image_path)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.user.User.upload_avatar) method with the [`User`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.user.User). Put the path to your image as a method parameter. The supported image extensions are `jpg`, `jpeg` and `png`. The image size cannot exceed 1024 * 1024 pixels or 1MB. ``` avatar_urls = client.user('33333').upload_avatar(image_path='path/to/the/image.png') ``` In return, you will get links to several representations of an avatar within Box account. Alternatively you can upload the avatar by passing the image byte stream and the image extension to the method [`upload_avatar_stream(image_stream, image_extension)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.user.User.upload_avatar_stream): ``` image_stream = open('path/to/the/image.png', 'rb') avatar_urls = client.user('33333').upload_avatar_stream(image_stream=image_stream, image_extension='png') ``` ## Delete user avatar To delete the user avatar image use [`delete_avatar()`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.user.User.delete_avatar) method with the [`User`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.user.User). ``` client.user('33333').delete_avatar() ``` ## Create An App User Platform applications may create App Users, which represent a "headless" user managed exclusively by the application. These users can only be accessed via the API, and cannot login to the web application or other Box services. To create a new app user, call [`client.create_user(name, login=None, **user_attributes)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.client.html#boxsdk.client.client.Client.create_user) without a `login` value. This returns the [`User`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.user.User) object for the new app user. ``` new_app_user = client.create_user('App User 123', login=None) ``` ## Update User To update a user object, call the [`user.update_info(data=data_to_update)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.base_object.BaseObject.update_info) method with a `dict` of fields to update on the user. ``` user_id = '33333' user = client.user(user_id) updated_user = user.update_info(data={'name': 'Smart User'}) ``` ## Delete User To delete a user call the [`user.delete(notify=True, force=False)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.user.User.delete) method. The method returns `True` to indicate that the deletion succeeded. The `notify` parameter determines whether the user should receive an email about the deletion, and the `force` parameter will cause the user to be deleted even if they still have files in their account. If `force` is set to `False` and the user still has files in their account, the deletion will fail. ``` user_id = '33333' client.user(user_id).delete(force=True) ``` ## Invite User to Enterprise To invite an existing user to join an Enterprise call the [`enterprise.invite_user(user_email)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.enterprise.Enterprise.invite_user) method. This method returns an [`Invite`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.invite.Invite) object representing the status of the invitation. ``` enterprise = client.get_current_enterprise() invitation = enterprise.invite_user('user@example.com') ``` ## Get Email Aliases To get a user's email aliases call the [`user.get_email_aliases(limit=None, fields=None)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.user.User.get_email_aliases) method. This method returns a [`BoxObjectCollection`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.pagination.box_object_collection.BoxObjectCollection) used to iterate over the collection of [`EmailAlias`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.email_alias.EmailAlias) objects. ``` user_id = '33333' user = client.user(user_id) email_aliases = user.get_email_aliases() for alias in email_aliases: print(f'User {user.id} has email alias {alias.email}') ``` ## Add Email Alias To add an email alias for a user, call the [`user.add_email_alias(email)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.user.User.add_email_alias) method with the email address to add as an email alias for the user. This will allow the user to log in and be collaborated by this email in addition to their login email address. Not all emails addresses can be added as email aliases. Email addresses whose domains match the domain of the login email address can always be made aliases. Email addresses whose domains differ from the domain of the login email address can be made aliases depending on the Box account configuration. The method returns an [`EmailAlias`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.email_alias.EmailAlias) object. ``` user_id = '33333' user = client.user(user_id) email_alias = user.add_email_alias('alias@example.com') ``` ## Remove Email Alias To remove an email alias from a user, call the [`user.remove_email_alias(email_alias)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.user.User.remove_email_alias) method with the [`EmailAlias`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.email_alias.EmailAlias) object to remove. The method returns `True` to signify that the removal succeeded. ``` user_id = '33333' email_alias_id = '12345' user = client.user(user_id) email_alias = client.email_alias(email_alias_id) user.remove_email_alias(email_alias) ``` ## Get Enterprise Users To get the users in an enterprise, call [`client.users(limit=None, offset=0, filter_term=None, user_type=None, fields=None)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.client.html#boxsdk.client.client.Client.users). You can specify a `filter_term` to filter on the user's `name` and `login` fields, or select a `user_type` to filter down to only managed or external users. This method returns a [`BoxObjectCollection`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.pagination.box_object_collection.BoxObjectCollection) used to iterate over the collection of [`User`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.user.User) objects. ``` users = client.users(user_type='all') for user in users: print(f'{user.name} (User ID: {user.id})') ``` ## Transfer User Content To move all of a user's content to a different user, call the [`user.transfer_content(self, destination_user, notify=None, fields=None)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.user.User.transfer_content) method with the [`User`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.user.User) object representing the destination user. This will create a new folder in the destination user's account, containing all files and folders from the original user's account; the method returns a [`Folder`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.folder.Folder) object representing this new folder in the destination user's account. ``` source_user_id = '33333' destination_user_id = '44444' user = client.user(source_user_id) destination_user = client.user(destination_user_id) folder = user.transfer_content(destination_user) print(f'Created new folder "{folder.name}" in the account of user {destination_user.id}') ``` --- ### Users **Type:** page | **Section:** Additional Resources Users Users represent an individual's account on Box. Get the Current User's Information Get User's Information Get User Avatar Add or… # Users Users represent an individual's account on Box. - [Get the Current User's Information](#get-the-current-users-information) - [Get User's Information](#get-users-information) - [Get User Avatar](#get-user-avatar) - [Add or update User Avatar](#add-or-update-user-avatar) - [Delete User Avatar](#delete-user-avatar) - [Add New User](#add-new-user) - [Add New App User](#add-new-app-user) - [Update User](#update-user) - [Delete User](#delete-user) - [Get Email Aliases](#get-email-aliases) - [Add Email Alias](#add-email-alias) - [Delete Email Alias](#delete-email-alias) - [Get Enterprise Users](#get-enterprise-users) - [Transfer User Content](#transfer-user-content) ## Get the Current User's Information To get the current user call the `UsersManager.GetCurrentUserInformationAsync(IEnumerable<string> fields = null)` method. ``` BoxUser currentUser = await client.UsersManager.GetCurrentUserInformationAsync(); ``` ## Get User's Information To get a user call `UsersManager.GetUserInformationAsync(string userId)` with the ID of the user. ``` BoxUser user = await client.UsersManager.GetUserInformationAsync(userId: "33333"); ``` ## Get User Avatar To retrieve the avatar image for a user, call `UsersManager.GetUserAvatar(string userId)` with the ID of the user. ``` Stream imageStream = await client.UsersManager.GetUserAvatar(string userId); ``` ## Add or Update User Avatar To add or update user avatar call the `UsersManager.AddOrUpdateUserAvatarAsync(string userId, FileStream stream)` method with the ID of the user and and a fileStream of the avatar contents to upload. ``` using (FileStream fileStream = new FileStream(filePath, FileMode.Open)) { BoxUploadAvatarResponse response = await client.UsersManager.AddOrUpdateUserAvatarAsync(userId, fileStream); } ``` Alternatively, you can use a generic stream (e.g. MemoryStream) and provide filename explicitly. The filename should also contain file extension (.jpg or .png). ``` Stream genericStream; BoxUploadAvatarResponse response = await client.UsersManager.AddOrUpdateUserAvatarAsync(userId, genericStream, "avatar.png"); ``` ## Delete User Avatar To remove existing user avatar call the `UsersManager.DeleteUserAvatarAsync(string userId)` method with the ID of the user. ``` bool isDeleted = await client.UsersManager.DeleteUserAvatarAsync(userId); ``` ## Add New User To provision a new managed user within the current enterprise, call the `UsersManager.CreateEnterpriseUserAsync(BoxUserRequest userRequest, IEnumerable<string> fields = null)` method with the email address the user will use to log in and the user's name. ``` var userParams = new BoxUserRequest() { Name = "Example User", Login = "user@example.com" }; BoxUser newUser = await client.UsersManager.CreateEnterpriseUserAsync(userParams); ``` ## Add New App User To provision a new app user within the current enterprise, call the `UsersManager.CreateEnterpriseUserAsync(BoxUserRequest userRequest, IEnumerable<string> fields = null)` method with the `BoxUserRequest.IsPlatformAccessOnly` property set to `true`. ``` var userParams = new BoxUserRequest() { Name = "App User 12", ExternalAppUserId = "external-id", IsPlatformAccessOnly = true }; BoxUser newUser = await client.UsersManager.CreateEnterpriseUserAsync(userParams); ``` ## Update User To update a user's information, call `UsersManager.UpdateUserInformationAsync(BoxUserRequest userRequest, IEnumerable<string> fields = null)` with the fields to update. ``` var updates = new BoxUserRequest() { Id = "44444", Role = "coadmin", CanSeeManagedUsers = true }; BoxUser updatedUser = await client.UsersManager.UpdateUserInformationAsync(updates); ``` ## Delete User To delete a user call the `UsersManager.DeleteEnterpriseUserAsync(string userId, bool notify, bool force)` method. If the user still has files in their account and the `force` parameter is not sent, an error is returned. ``` await client.UsersManager.DeleteEnterpriseUserAsync("44444", notify: false, force: true); ``` ## Get Email Aliases To get a users email aliases, call `UsersManager.GetEmailAliasesAsync(string userId)` with the ID of the user. ``` BoxCollection<BoxEmailAlias> aliases = await client.UsersManager .GetEmailAliasesAsync(userId: "33333"); ``` ## Add Email Alias To add an email alias for a user, call `UsersManager.AddEmailAliasAsync(string userId, string email)` with the ID of the user and the email address to add as an alias. ``` BoxEmailAlias alias = await client.UsersManager .AddEmailAliasAsync(userId: "33333", email: "user+foo@example.com"); ``` ## Delete Email Alias To delete a users email alias, call `UsersManager.DeleteEmailAliasAsync(string userId, string emailAliasId)` with the ID of the user to whom the alias belongs and the ID of the email alias. ``` await client.UsersManager.DeleteEmailAliasAsync(userId: "33333", emailAliasId: "12345"); ``` ## Get Enterprise Users Get a list of users in the current enterprise by calling the `UsersManager.GetEnterpriseUsersAsync(string filterTerm = null, uint offset = 0, uint limit = 100, IEnumerable<string> fields = null, string userType = null, string externalAppUserId = null, bool autoPaginate = false)` method. ``` BoxCollection<BoxUser> users = await client.UsersManager.GetEnterpriseUsersAsync(); ``` ## Transfer User Content To transfer one managed user's content to another user's account, call the `MoveUserFolderAsync(string userId, string ownedByUserId, string folderId = "0", bool notify = false)` method with the IDs of the source and destination users. **Note:** Currently, only moving the user's root folder (with ID "0") is supported. ``` var sourceUserId = "33333"; var destinationUserId = "44444"; BoxFolder movedFolder = await client.MoveUserFolderAsync(sourceUserId, destinationUserId); ``` --- ### Users **Type:** page | **Section:** Additional Resources Users Users represent an individual's account on Box. Get Current User Get User Upload User Avatar Get User Avatar Delete User Avatar Create… # Users Users represent an individual's account on Box. - [Get Current User](#get-current-user) - [Get User](#get-user) - [Upload User Avatar](#upload-user-avatar) - [Get User Avatar](#get-user-avatar) - [Delete User Avatar](#delete-user-avatar) - [Create User](#create-user) - [Create App User](#create-app-user) - [Update User](#update-user) - [Change User Login](#change-user-login) - [Delete User](#delete-user) - [Get Enterprise Users](#get-enterprise-users) - [Invite User to Enterprise](#invite-user-to-enterprise) - [Move User Content](#move-user-content) - [Get User Email Aliases](#get-user-email-aliases) - [Add User Email Alias](#add-user-email-alias) - [Remove User Email Alias](#remove-user-email-alias) - [Roll User Out of Enterprise](#roll-user-out-of-enterprise) ## Get Current User To retrieve information about the currently authenticated user, call [`client.users.getCurrent(fields:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/UsersModule.html#/s:6BoxSDK11UsersModuleC10getCurrent6fields10completionySaySSGSg_ys6ResultOyAA4UserCAA0A8SDKErrorCGctF). ``` client.users.getCurrent(fields: ["name", "login"]) { (result: Result<User, BoxSDKError>) in guard case let .success(user) = result else { print("Error getting user information") return } print("Authenticated as \(user.name), with login \(user.login)") } ``` ## Get User To retrieve information about a specific user, call [`client.users.get(userId:fields:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/UsersModule.html#/s:6BoxSDK11UsersModuleC3get6userId6fields10completionySS_SaySSGSgys6ResultOyAA4UserCAA0A8SDKErrorCGctF) with the ID of the user. ``` client.users.get(userId: "33333", fields: ["name", "login"]) { (result: Result<User, BoxSDKError>) in guard case let .success(user) = result else { print("Error getting user information") return } print("Got user \(user.name), with login \(user.login)") } ``` ## Upload User Avatar To add or update the avatar for a user, call [`client.users.uploadAvatar(userId:data:name:progress:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/UsersModule.html#/s:6BoxSDK11UsersModuleC12uploadAvataryXeXeF) with the ID of the user, the data to be uploaded and the name of the file. Optionally you can also pass an progress closure, where upload progress will be reported. In return, you will get an object with links to several representations of an avatar within Box account The supported image extensions are `jpg`, `jpeg` and `png`. The image size cannot exceed 1024 * 1024 pixels or 1MB. ``` let image: UIImage = <YOUR_IMAGE_HERE> // Initialize image here e.g. from UIImagePickerController let data = image.jpegData(compressionQuality: 1)! client.users.uploadAvatar(userId: "33333", data: data, name: "avatar.jpeg") { result in guard case let .success(uploadAvatar) = result else { print("Error uploading user avatar") return } print("User avatar uploaded successfully!") } ``` Alternatively, you can upload the avatar by passing the `InputStream` the method [`client.users.streamUploadAvatar(userId:stream:name:progress:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/UsersModule.html#/s:6BoxSDK11UsersModuleC18streamUploadAvataryXeXeF). ``` let stream = InputStream(fileAtPath: "PATH_TO_IMAGE_FILE_HERE") client.users.streamUploadAvatar(userId: "33333", stream: data, name: "avatar.jpeg") { result in guard case let .success(uploadAvatar) = result else { print("Error uploading user avatar") return } print("User avatar uploaded successfully!") } ``` Please remember that in both of these methods, the `name` parameter should also contains file extension (.jpg, .jpeg or .png). ## Get User Avatar To retrieve the avatar image for a user, call [`client.users.getAvatar(userId:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/UsersModule.html#/s:6BoxSDK11UsersModuleC9getAvatar6userId10completionySS_ys6ResultOy10Foundation4DataVAA0A8SDKErrorCGctF) with the ID of the user. ``` client.users.getAvatar(userId: "33333") { (result: Result<Data, BoxSDKError>) in guard case let .success(avatarData) = result else { print("Error getting user avatar") return } let avatarImage = UIImage(data: avatarData) } ``` ## Delete User Avatar To remove existing user avatar, call [`client.users.deleteAvatar(userId:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/UsersModule.html#/s:6BoxSDK11UsersModuleC12deleteAvatar6userId10completionySS_ys6ResultOyytAA0A8SDKErrorCGctF) with the ID of the user. ``` client.users.deleteAvatar(userId: "33333") { result in guard case .success = result else { print("Error deleting avatar") return } print("Avatar successfully deleted") } ``` ## Create User As an admin user or service account, create a new user in your enterprise by calling [`client.users.create(login:name:...)`](https://opensource.box.com/box-ios-sdk/Classes/UsersModule.html#/s:6BoxSDK11UsersModuleC6create5login4name4role8language13isSyncEnabled8jobTitle5phone7address11spaceAmount13trackingCodes013canSeeManagedC08timezone0J24ExternalCollabRestricted0J22ExemptFromDeviceLimits0J27ExemptFromLoginVerification6status6fields10completionySS_SSAA8UserRoleOSgSSSgSbSgA3Zs5Int64VSgSayAA4UserC12TrackingCodeVGSgA_AZA_A_A_AA10UserStatusOSgSaySSGSgys6ResultOyA4_AA0A8SDKErrorCGctF) with the login email address and name for the user. ``` client.users.create(login: "new.user@example.com", name: "New User") { (result: Result<User, BoxSDKError>) in guard case let .success(user) = result else { print("Error creating user") return } print("Created user \(user.name), with login \(user.login)") } ``` ## Create App User To create an [app user](https://developer.box.com/docs/user-types#section-app-user), call [`client.users.createAppUser(name:...)`](https://opensource.box.com/box-ios-sdk/Classes/UsersModule.html#/s:6BoxSDK11UsersModuleC13createAppUser4name8language8jobTitle8timezone5phone7address11spaceAmount6status26isExternalCollabRestricted013canSeeManagedC06fields10completionySS_SSSgA4Qs5Int64VSgAA0G6StatusOSgSbSgAXSaySSGSgys6ResultOyAA0G0CAA0A8SDKErrorCGctF) with the a name for that user. ``` client.users.createAppUser(name: "Doug") { (result: Result<User, BoxSDKError>) in guard case let .success(appUser) = result else { print("Error creating app user") return } print("Created app user with ID \(appUser.id)") } ``` ## Update User To update the information on a user, call [`client.users.updateUser(userId:...)`](https://opensource.box.com/box-ios-sdk/Classes/UsersModule.html#/s:6BoxSDK11UsersModuleC6update6userId5login4name4role8language13isSyncEnabled8jobTitle5phone7address11spaceAmount13trackingCodes013canSeeManagedC08timezone0L24ExternalCollabRestricted0L22ExemptFromDeviceLimits0L27ExemptFromLoginVerification6status6fields10completionySS_SSSgAxA8UserRoleOSgAXSbSgA3Xs5Int64VSgSayAA4UserC12TrackingCodeVGSgA0_AXA0_A0_A0_AA10UserStatusOSgSaySSGSgys6ResultOyA5_AA0A8SDKErrorCGctF) with the ID of the user and the properties to update. The result is the updated user object. ``` // Restrict the user from collaborating content externally client.users.update(userId: "33333", isExternalCollabRestricted: true) { (result: Result<User, BoxSDKError>) in guard case let .success(user) = result else { print("Error updating user") return } print("Updated user \(user.name), with login \(user.login)") } ``` ## Change User Login **Note:** In order to change the user's login email, the new email address must first be added as an email alias and the address must be confirmed. To change a user's login email, call [`client.users.changeLogin(userId:login:fields:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/UsersModule.html#/s:6BoxSDK11UsersModuleC11changeLogin6userId5login6fields10completionySS_SSSaySSGSgys6ResultOyAA4UserCAA0A8SDKErrorCGctF) with the ID of the user and the new login email. ``` client.users.changeLogin(userId: "33333", login: "updated.address@example.com") { (result: Result<User, BoxSDKError>) in guard case let .success(user) = result else { print("Error updating user email") return } print("User \(user.name) (ID: \(user.id)) now has login \(user.login)") } ``` ## Delete User To delete a user, which removes their access to Box, call [`client.users.delete(userId:notify:force:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/UsersModule.html#/s:6BoxSDK11UsersModuleC6delete6userId6notify5force10completionySS_SbSgAIys6ResultOyytAA0A8SDKErrorCGctF) with the ID of the user. By default, the user will not be deleted if they have any content remaining in their account. To delete the user and any content that is in their account, set the `force` parameter to `true`. ``` client.users.delete(userId: "33333") { (result: Result<Void, BoxSDKError>) in guard case .success = result else { print("Error deleting user") return } print("User successfully deleted") } ``` ## Get Enterprise Users To retrieve the users in an enterprise, call [`client.users.listForEnterprise(filterTerm:fields:offset:limit:)`](https://opensource.box.com/box-ios-sdk/Classes/UsersModule.html#/s:6BoxSDK11UsersModuleC17listForEnterprise10filterTerm6fields9usemarker6marker6offset5limit10completionySSSg_SaySSGSgSbSgALSiSgAPys6ResultOyAA14PagingIteratorCyAA4UserCGAA0A8SDKErrorCGctF). The method returns an iterator object, which is used to get the users. ``` let iterator = client.users.listForEnterprise() iterator.next { result in switch results { case let .success(page): for user in page.entries { print("\(user.name) (ID: \(user.id))") } case let .failure(error): print(error) } } ``` ## Invite User to Enterprise To invite a user who already has a Box account to join an enterprise, call [`client.users.inviteToJoinEnterprise(login:enterpriseId:fields:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/UsersModule.html#/s:6BoxSDK11UsersModuleC22inviteToJoinEnterprise5login12enterpriseId6fields10completionySS_SSSaySSGSgys6ResultOyAA6InviteCAA0A8SDKErrorCGctF) with the login email of the user and the ID of the enterprise. ``` client.users.inviteToJoinEnterprise( login: "user@example.com", enterpriseId: "12345" ) { (result: Result<Invite, BoxSDKError>) in guard case let .success(invite) = result else { print("Error inviting user to enterprise") return } print("Invited user \(invite.actionableBy.name) to \(invite.invitedTo.name)") } ``` ## Move User Content Before deleting a user, it is recommended to move all content they own to another user. This can be done by calling [`client.users.moveItemsOwnedByUser(withID:toUserWithID:notify:fields:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/UsersModule.html#/s:6BoxSDK11UsersModuleC20moveItemsOwnedByUser6withID02toi4WithK06notify6fields10completionySS_SSSbSgSaySSGSgys6ResultOyAA6FolderCAA0A8SDKErrorCGctF) with the ID of the source and destination users. The result of this method is a new folder created in the destination user's root folder, containing all content previously owned by the source user. ``` client.users.moveItemsOwnedByUser(withID: "33333", toUserWithID: "44444") { (result: Result<Folder, BoxSDKError>) in guard case let .success(folder) = result else { print("Error moving user content") return } print("Folder ID \(folder.id) created with migrated content") } ``` ## Get User Email Aliases To retrieve the list of email aliases associated with a user, call [`client.users.listEmailAliases(userId:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/UsersModule.html#/s:6BoxSDK11UsersModuleC16listEmailAliases6userId10completionySS_ys6ResultOyAA14EntryContainerCyAA0F5AliasCGAA0A8SDKErrorCGctF) with the ID of the user. ``` client.users.listEmailAliases(userId: "33333") { (result: Result<EntryContainer<User>, BoxSDKError>) in guard case let .success(aliasCollection) = result else { print("Error retrieving email aliases") return } print("User has \(aliasCollection.totalCount) email aliases:") for alias in aliasCollection.entries { print("- \(alias.email) (\(alias.isConfirmed ? "Confirmed" : "Not Confirmed"))") } } ``` ## Add User Email Alias To associate a new email alias with a user, call [`client.users.createEmailAlias(userId:email:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/UsersModule.html#/s:6BoxSDK11UsersModuleC23createEmailAliasForUser6userId5email10completionySS_SSys6ResultOyAA0fG0CAA0A5ErrorOGctF) with the ID of the user and the email address to add as an alias. ``` client.users.createEmailAlias( userId: "33333", email: "user+alias@example.com" ) { (result: Result<EmailAlias, BoxSDKError>) in guard case let .success(alias) = result else { print("Error adding email alias") return } print("Added email alias \(alias.email) — user must confirm") } ``` ## Remove User Email Alias To remove a user's email alias, call [`client.users.deleteEmailAlias(userId:emailAliasId:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/UsersModule.html#/s:6BoxSDK11UsersModuleC16deleteEmailAlias6userId05emailgI010completionySS_SSys6ResultOyytAA0A8SDKErrorCGctF) with the ID of the user and the ID of the email alias to remove. ``` client.users.deleteEmailAlias(userId: "33333", emailAliasId: "99999") { (result: Result<Void, BoxSDKError>) in guard case .success = result else { print("Error removing email alias") return } print("Successfully removed email alias") } ``` ## Roll User Out of Enterprise To roll a user out of an enterprise, converting them to a free user, call [`client.users.rollOutOfEnterprise(userId:notify:fields:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/UsersModule.html#/s:6BoxSDK11UsersModuleC19rollOutOfEnterprise6userId6notify6fields10completionySS_SbSgSaySSGSgys6ResultOyAA4UserCAA0A8SDKErrorCGctF) with the ID of the user. ``` client.users.rollOutOfEnterprise(userId: "33333") { (result: Result<User, BoxSDKError>) in guard case let .success(user) = result else { print("Error removing user from enterprise") return } print("User \(user.name) successfully removed from enterprise") } ``` --- ### Users **Type:** page | **Section:** Additional Resources Users Users represent an individual's account on Box. Get Current User Get User Upload User Avatar Get User Avatar Delete User Avatar Create… # Users Users represent an individual's account on Box. - [Get Current User](#get-current-user) - [Get User](#get-user) - [Upload User Avatar](#upload-user-avatar) - [Get User Avatar](#get-user-avatar) - [Delete User Avatar](#delete-user-avatar) - [Create User](#create-user) - [Create App User](#create-app-user) - [Update User](#update-user) - [Change User Login](#change-user-login) - [Delete User](#delete-user) - [Get Enterprise Users](#get-enterprise-users) - [Invite User to Enterprise](#invite-user-to-enterprise) - [Move User Content](#move-user-content) - [Get User Email Aliases](#get-user-email-aliases) - [Add User Email Alias](#add-user-email-alias) - [Remove User Email Alias](#remove-user-email-alias) - [Roll User Out of Enterprise](#roll-user-out-of-enterprise) ## Get Current User To retrieve information about the currently authenticated user, call [`client.users.getCurrent(fields:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/UsersModule.html#/s:6BoxSDK11UsersModuleC10getCurrent6fields10completionySaySSGSg_ys6ResultOyAA4UserCAA0A8SDKErrorCGctF). ``` client.users.getCurrent(fields: ["name", "login"]) { (result: Result<User, BoxSDKError>) in guard case let .success(user) = result else { print("Error getting user information") return } print("Authenticated as \(user.name), with login \(user.login)") } ``` ## Get User To retrieve information about a specific user, call [`client.users.get(userId:fields:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/UsersModule.html#/s:6BoxSDK11UsersModuleC3get6userId6fields10completionySS_SaySSGSgys6ResultOyAA4UserCAA0A8SDKErrorCGctF) with the ID of the user. ``` client.users.get(userId: "33333", fields: ["name", "login"]) { (result: Result<User, BoxSDKError>) in guard case let .success(user) = result else { print("Error getting user information") return } print("Got user \(user.name), with login \(user.login)") } ``` ## Upload User Avatar To add or update the avatar for a user, call [`client.users.uploadAvatar(userId:data:name:progress:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/UsersModule.html#/s:6BoxSDK11UsersModuleC12uploadAvataryXeXeF) with the ID of the user, the data to be uploaded and the name of the file. Optionally you can also pass an progress closure, where upload progress will be reported. In return, you will get an object with links to several representations of an avatar within Box account The supported image extensions are `jpg`, `jpeg` and `png`. The image size cannot exceed 1024 * 1024 pixels or 1MB. ``` let image: UIImage = <YOUR_IMAGE_HERE> // Initialize image here e.g. from UIImagePickerController let data = image.jpegData(compressionQuality: 1)! client.users.uploadAvatar(userId: "33333", data: data, name: "avatar.jpeg") { result in guard case let .success(uploadAvatar) = result else { print("Error uploading user avatar") return } print("User avatar uploaded successfully!") } ``` Alternatively, you can upload the avatar by passing the `InputStream` the method [`client.users.streamUploadAvatar(userId:stream:name:progress:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/UsersModule.html#/s:6BoxSDK11UsersModuleC18streamUploadAvataryXeXeF). ``` let stream = InputStream(fileAtPath: "PATH_TO_IMAGE_FILE_HERE") client.users.streamUploadAvatar(userId: "33333", stream: data, name: "avatar.jpeg") { result in guard case let .success(uploadAvatar) = result else { print("Error uploading user avatar") return } print("User avatar uploaded successfully!") } ``` Please remember that in both of these methods, the `name` parameter should also contains file extension (.jpg, .jpeg or .png). ## Get User Avatar To retrieve the avatar image for a user, call [`client.users.getAvatar(userId:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/UsersModule.html#/s:6BoxSDK11UsersModuleC9getAvatar6userId10completionySS_ys6ResultOy10Foundation4DataVAA0A8SDKErrorCGctF) with the ID of the user. ``` client.users.getAvatar(userId: "33333") { (result: Result<Data, BoxSDKError>) in guard case let .success(avatarData) = result else { print("Error getting user avatar") return } let avatarImage = UIImage(data: avatarData) } ``` ## Delete User Avatar To remove existing user avatar, call [`client.users.deleteAvatar(userId:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/UsersModule.html#/s:6BoxSDK11UsersModuleC12deleteAvatar6userId10completionySS_ys6ResultOyytAA0A8SDKErrorCGctF) with the ID of the user. ``` client.users.deleteAvatar(userId: "33333") { result in guard case .success = result else { print("Error deleting avatar") return } print("Avatar successfully deleted") } ``` ## Create User As an admin user or service account, create a new user in your enterprise by calling [`client.users.create(login:name:...)`](https://opensource.box.com/box-ios-sdk/Classes/UsersModule.html#/s:6BoxSDK11UsersModuleC6create5login4name4role8language13isSyncEnabled8jobTitle5phone7address11spaceAmount13trackingCodes013canSeeManagedC08timezone0J24ExternalCollabRestricted0J22ExemptFromDeviceLimits0J27ExemptFromLoginVerification6status6fields10completionySS_SSAA8UserRoleOSgSSSgSbSgA3Zs5Int64VSgSayAA4UserC12TrackingCodeVGSgA_AZA_A_A_AA10UserStatusOSgSaySSGSgys6ResultOyA4_AA0A8SDKErrorCGctF) with the login email address and name for the user. ``` client.users.create(login: "new.user@example.com", name: "New User") { (result: Result<User, BoxSDKError>) in guard case let .success(user) = result else { print("Error creating user") return } print("Created user \(user.name), with login \(user.login)") } ``` ## Create App User To create an [app user](https://developer.box.com/docs/user-types#section-app-user), call [`client.users.createAppUser(name:...)`](https://opensource.box.com/box-ios-sdk/Classes/UsersModule.html#/s:6BoxSDK11UsersModuleC13createAppUser4name8language8jobTitle8timezone5phone7address11spaceAmount6status26isExternalCollabRestricted013canSeeManagedC06fields10completionySS_SSSgA4Qs5Int64VSgAA0G6StatusOSgSbSgAXSaySSGSgys6ResultOyAA0G0CAA0A8SDKErrorCGctF) with the a name for that user. ``` client.users.createAppUser(name: "Doug") { (result: Result<User, BoxSDKError>) in guard case let .success(appUser) = result else { print("Error creating app user") return } print("Created app user with ID \(appUser.id)") } ``` ## Update User To update the information on a user, call [`client.users.updateUser(userId:...)`](https://opensource.box.com/box-ios-sdk/Classes/UsersModule.html#/s:6BoxSDK11UsersModuleC6update6userId5login4name4role8language13isSyncEnabled8jobTitle5phone7address11spaceAmount13trackingCodes013canSeeManagedC08timezone0L24ExternalCollabRestricted0L22ExemptFromDeviceLimits0L27ExemptFromLoginVerification6status6fields10completionySS_SSSgAxA8UserRoleOSgAXSbSgA3Xs5Int64VSgSayAA4UserC12TrackingCodeVGSgA0_AXA0_A0_A0_AA10UserStatusOSgSaySSGSgys6ResultOyA5_AA0A8SDKErrorCGctF) with the ID of the user and the properties to update. The result is the updated user object. ``` // Restrict the user from collaborating content externally client.users.update(userId: "33333", isExternalCollabRestricted: true) { (result: Result<User, BoxSDKError>) in guard case let .success(user) = result else { print("Error updating user") return } print("Updated user \(user.name), with login \(user.login)") } ``` ## Change User Login **Note:** In order to change the user's login email, the new email address must first be added as an email alias and the address must be confirmed. To change a user's login email, call [`client.users.changeLogin(userId:login:fields:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/UsersModule.html#/s:6BoxSDK11UsersModuleC11changeLogin6userId5login6fields10completionySS_SSSaySSGSgys6ResultOyAA4UserCAA0A8SDKErrorCGctF) with the ID of the user and the new login email. ``` client.users.changeLogin(userId: "33333", login: "updated.address@example.com") { (result: Result<User, BoxSDKError>) in guard case let .success(user) = result else { print("Error updating user email") return } print("User \(user.name) (ID: \(user.id)) now has login \(user.login)") } ``` ## Delete User To delete a user, which removes their access to Box, call [`client.users.delete(userId:notify:force:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/UsersModule.html#/s:6BoxSDK11UsersModuleC6delete6userId6notify5force10completionySS_SbSgAIys6ResultOyytAA0A8SDKErrorCGctF) with the ID of the user. By default, the user will not be deleted if they have any content remaining in their account. To delete the user and any content that is in their account, set the `force` parameter to `true`. ``` client.users.delete(userId: "33333") { (result: Result<Void, BoxSDKError>) in guard case .success = result else { print("Error deleting user") return } print("User successfully deleted") } ``` ## Get Enterprise Users To retrieve the users in an enterprise, call [`client.users.listForEnterprise(filterTerm:fields:offset:limit:)`](https://opensource.box.com/box-ios-sdk/Classes/UsersModule.html#/s:6BoxSDK11UsersModuleC17listForEnterprise10filterTerm6fields9usemarker6marker6offset5limit10completionySSSg_SaySSGSgSbSgALSiSgAPys6ResultOyAA14PagingIteratorCyAA4UserCGAA0A8SDKErrorCGctF). The method returns an iterator object, which is used to get the users. ``` let iterator = client.users.listForEnterprise() iterator.next { result in switch results { case let .success(page): for user in page.entries { print("\(user.name) (ID: \(user.id))") } case let .failure(error): print(error) } } ``` ## Invite User to Enterprise To invite a user who already has a Box account to join an enterprise, call [`client.users.inviteToJoinEnterprise(login:enterpriseId:fields:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/UsersModule.html#/s:6BoxSDK11UsersModuleC22inviteToJoinEnterprise5login12enterpriseId6fields10completionySS_SSSaySSGSgys6ResultOyAA6InviteCAA0A8SDKErrorCGctF) with the login email of the user and the ID of the enterprise. ``` client.users.inviteToJoinEnterprise( login: "user@example.com", enterpriseId: "12345" ) { (result: Result<Invite, BoxSDKError>) in guard case let .success(invite) = result else { print("Error inviting user to enterprise") return } print("Invited user \(invite.actionableBy.name) to \(invite.invitedTo.name)") } ``` ## Move User Content Before deleting a user, it is recommended to move all content they own to another user. This can be done by calling [`client.users.moveItemsOwnedByUser(withID:toUserWithID:notify:fields:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/UsersModule.html#/s:6BoxSDK11UsersModuleC20moveItemsOwnedByUser6withID02toi4WithK06notify6fields10completionySS_SSSbSgSaySSGSgys6ResultOyAA6FolderCAA0A8SDKErrorCGctF) with the ID of the source and destination users. The result of this method is a new folder created in the destination user's root folder, containing all content previously owned by the source user. ``` client.users.moveItemsOwnedByUser(withID: "33333", toUserWithID: "44444") { (result: Result<Folder, BoxSDKError>) in guard case let .success(folder) = result else { print("Error moving user content") return } print("Folder ID \(folder.id) created with migrated content") } ``` ## Get User Email Aliases To retrieve the list of email aliases associated with a user, call [`client.users.listEmailAliases(userId:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/UsersModule.html#/s:6BoxSDK11UsersModuleC16listEmailAliases6userId10completionySS_ys6ResultOyAA14EntryContainerCyAA0F5AliasCGAA0A8SDKErrorCGctF) with the ID of the user. ``` client.users.listEmailAliases(userId: "33333") { (result: Result<EntryContainer<User>, BoxSDKError>) in guard case let .success(aliasCollection) = result else { print("Error retrieving email aliases") return } print("User has \(aliasCollection.totalCount) email aliases:") for alias in aliasCollection.entries { print("- \(alias.email) (\(alias.isConfirmed ? "Confirmed" : "Not Confirmed"))") } } ``` ## Add User Email Alias To associate a new email alias with a user, call [`client.users.createEmailAlias(userId:email:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/UsersModule.html#/s:6BoxSDK11UsersModuleC23createEmailAliasForUser6userId5email10completionySS_SSys6ResultOyAA0fG0CAA0A5ErrorOGctF) with the ID of the user and the email address to add as an alias. ``` client.users.createEmailAlias( userId: "33333", email: "user+alias@example.com" ) { (result: Result<EmailAlias, BoxSDKError>) in guard case let .success(alias) = result else { print("Error adding email alias") return } print("Added email alias \(alias.email) — user must confirm") } ``` ## Remove User Email Alias To remove a user's email alias, call [`client.users.deleteEmailAlias(userId:emailAliasId:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/UsersModule.html#/s:6BoxSDK11UsersModuleC16deleteEmailAlias6userId05emailgI010completionySS_SSys6ResultOyytAA0A8SDKErrorCGctF) with the ID of the user and the ID of the email alias to remove. ``` client.users.deleteEmailAlias(userId: "33333", emailAliasId: "99999") { (result: Result<Void, BoxSDKError>) in guard case .success = result else { print("Error removing email alias") return } print("Successfully removed email alias") } ``` ## Roll User Out of Enterprise To roll a user out of an enterprise, converting them to a free user, call [`client.users.rollOutOfEnterprise(userId:notify:fields:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/UsersModule.html#/s:6BoxSDK11UsersModuleC19rollOutOfEnterprise6userId6notify6fields10completionySS_SbSgSaySSGSgys6ResultOyAA4UserCAA0A8SDKErrorCGctF) with the ID of the user. ``` client.users.rollOutOfEnterprise(userId: "33333") { (result: Result<User, BoxSDKError>) in guard case let .success(user) = result else { print("Error removing user from enterprise") return } print("User \(user.name) successfully removed from enterprise") } ``` --- ### UsersManager **Type:** page | **Section:** Additional Resources UsersManager List enterprise users Create user Get current user Get user Update user Delete user List enterprise users Returns a list of all… # UsersManager - [List enterprise users](#list-enterprise-users) - [Create user](#create-user) - [Get current user](#get-current-user) - [Get user](#get-user) - [Update user](#update-user) - [Delete user](#delete-user) ## List enterprise users Returns a list of all users for the Enterprise along with their `user_id`, `public_name`, and `login`. The application and the authenticated user need to have the permission to look up users in the entire enterprise. This operation is performed by calling function `getUsers`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-users/). ``` await client.users.getUsers(); ``` ### Arguments queryParams `GetUsersQueryParams` - Query parameters of getUsers method headersInput `GetUsersHeadersInput` - Headers of getUsers method cancellationToken `undefined | CancellationToken` - Token used for request cancellation. ### Returns This function returns a value of type `Users`. Returns all of the users in the enterprise. ## Create user Creates a new managed user in an enterprise. This endpoint is only available to users and applications with the right admin permissions. This operation is performed by calling function `createUser`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-users/). ``` await client.users.createUser({ name: userName, login: userLogin, isPlatformAccessOnly: true, } satisfies CreateUserRequestBody); ``` ### Arguments requestBody `CreateUserRequestBody` - Request body of createUser method optionalsInput `CreateUserOptionalsInput` ### Returns This function returns a value of type `UserFull`. Returns a user object for the newly created user. ## Get current user Retrieves information about the user who is currently authenticated. In the case of a client-side authenticated OAuth 2.0 application this will be the user who authorized the app. In the case of a JWT, server-side authenticated application this will be the service account that belongs to the application by default. Use the `As-User` header to change who this API call is made on behalf of. This operation is performed by calling function `getUserMe`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-users-me/). ``` await client.users.getUserMe(); ``` ### Arguments queryParams `GetUserMeQueryParams` - Query parameters of getUserMe method headersInput `GetUserMeHeadersInput` - Headers of getUserMe method cancellationToken `undefined | CancellationToken` - Token used for request cancellation. ### Returns This function returns a value of type `UserFull`. Returns a single user object. ## Get user Retrieves information about a user in the enterprise. The application and the authenticated user need to have the permission to look up users in the entire enterprise. This endpoint also returns a limited set of information for external users who are collaborated on content owned by the enterprise for authenticated users with the right scopes. In this case, disallowed fields will return null instead. This operation is performed by calling function `getUserById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-users-id/). ``` await client.users.getUserById(user.id); ``` ### Arguments userId `string` - The ID of the user. Example: "12345" optionalsInput `GetUserByIdOptionalsInput` ### Returns This function returns a value of type `UserFull`. Returns a single user object. Not all available fields are returned by default. Use the [fields](#param-fields) query parameter to explicitly request any specific fields using the [fields](#get-users-id--request--fields) parameter. ## Update user Updates a managed or app user in an enterprise. This endpoint is only available to users and applications with the right admin permissions. This operation is performed by calling function `updateUserById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-users-id/). ``` await client.users.updateUserById(user.id, { requestBody: { name: updatedUserName } satisfies UpdateUserByIdRequestBody, } satisfies UpdateUserByIdOptionalsInput); ``` ### Arguments userId `string` - The ID of the user. Example: "12345" optionalsInput `UpdateUserByIdOptionalsInput` ### Returns This function returns a value of type `UserFull`. Returns the updated user object. ## Delete user Deletes a user. By default this will fail if the user still owns any content. Move their owned content first before proceeding, or use the `force` field to delete the user and their files. This operation is performed by calling function `deleteUserById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-users-id/). ``` await client.users.deleteUserById(user.id); ``` ### Arguments userId `string` - The ID of the user. Example: "12345" optionalsInput `DeleteUserByIdOptionalsInput` ### Returns This function returns a value of type `undefined`. Removes the user and returns an empty response. --- ### UsersManager **Type:** page | **Section:** Additional Resources UsersManager List enterprise users Create user Get current user Get user Update user Delete user List enterprise users Returns a list of all… # UsersManager - [List enterprise users](#list-enterprise-users) - [Create user](#create-user) - [Get current user](#get-current-user) - [Get user](#get-user) - [Update user](#update-user) - [Delete user](#delete-user) ## List enterprise users Returns a list of all users for the Enterprise along with their `user_id`, `public_name`, and `login`. The application and the authenticated user need to have the permission to look up users in the entire enterprise. This operation is performed by calling function `get_users`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-users/). ``` client.users.get_users() ``` ### Arguments filter_term `Optional[str]` - Limits the results to only users who's `name` or `login` start with the search term. For externally managed users, the search term needs to completely match the in order to find the user, and it will only return one user at a time. user_type `Optional[GetUsersUserType]` - Limits the results to the kind of user specified. _ `all` returns every kind of user for whom the `login` or `name` partially matches the `filter_term`. It will only return an external user if the login matches the `filter_term` completely, and in that case it will only return that user. _ `managed` returns all managed and app users for whom the `login` or `name` partially matches the `filter_term`. * `external` returns all external users for whom the `login` matches the `filter_term` exactly. external_app_user_id `Optional[str]` - Limits the results to app users with the given `external_app_user_id` value. When creating an app user, an `external_app_user_id` value can be set. This value can then be used in this endpoint to find any users that match that `external_app_user_id` value. fields `Optional[List[str]]` - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested. offset `Optional[int]` - The offset of the item at which to begin the response. Queries with offset parameter value exceeding 10000 will be rejected with a 400 response. limit `Optional[int]` - The maximum number of items to return per page. usemarker `Optional[bool]` - Specifies whether to use marker-based pagination instead of offset-based pagination. Only one pagination method can be used at a time. By setting this value to true, the API will return a `marker` field that can be passed as a parameter to this endpoint to get the next page of the response. marker `Optional[str]` - Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `Users`. Returns all of the users in the enterprise. ## Create user Creates a new managed user in an enterprise. This endpoint is only available to users and applications with the right admin permissions. This operation is performed by calling function `create_user`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-users/). ``` client.users.create_user(user_name, login=user_login, is_platform_access_only=True) ``` ### Arguments name `str` - The name of the user. login `Optional[str]` - The email address the user uses to log in Required, unless `is_platform_access_only` is set to `true`. is_platform_access_only `Optional[bool]` - Specifies that the user is an app user. role `Optional[CreateUserRole]` - The user’s enterprise role. language `Optional[str]` - The language of the user, formatted in modified version of the [ISO 639-1](https://ja.developer.box.com/guides/api-calls/language-codes) format. is_sync_enabled `Optional[bool]` - Whether the user can use Box Sync. job_title `Optional[str]` - The user’s job title. phone `Optional[str]` - The user’s phone number. address `Optional[str]` - The user’s address. space_amount `Optional[int]` - The user’s total available space in bytes. Set this to `-1` to indicate unlimited storage. tracking_codes `Optional[List[TrackingCode]]` - Tracking codes allow an admin to generate reports from the admin console and assign an attribute to a specific group of users. This setting must be enabled for an enterprise before it can be used. can_see_managed_users `Optional[bool]` - Whether the user can see other enterprise users in their contact list. timezone `Optional[str]` - The user's timezone. is_external_collab_restricted `Optional[bool]` - Whether the user is allowed to collaborate with users outside their enterprise. is_exempt_from_device_limits `Optional[bool]` - Whether to exempt the user from enterprise device limits. is_exempt_from_login_verification `Optional[bool]` - Whether the user must use two-factor authentication. status `Optional[CreateUserStatus]` - The user's account status. external_app_user_id `Optional[str]` - An external identifier for an app user, which can be used to look up the user. This can be used to tie user IDs from external identity providers to Box users. fields `Optional[List[str]]` - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `UserFull`. Returns a user object for the newly created user. ## Get current user Retrieves information about the user who is currently authenticated. In the case of a client-side authenticated OAuth 2.0 application this will be the user who authorized the app. In the case of a JWT, server-side authenticated application this will be the service account that belongs to the application by default. Use the `As-User` header to change who this API call is made on behalf of. This operation is performed by calling function `get_user_me`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-users-me/). ``` client.users.get_user_me() ``` ### Arguments fields `Optional[List[str]]` - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `UserFull`. Returns a single user object. ## Get user Retrieves information about a user in the enterprise. The application and the authenticated user need to have the permission to look up users in the entire enterprise. This endpoint also returns a limited set of information for external users who are collaborated on content owned by the enterprise for authenticated users with the right scopes. In this case, disallowed fields will return null instead. This operation is performed by calling function `get_user_by_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-users-id/). ``` client.users.get_user_by_id(user.id) ``` ### Arguments user_id `str` - The ID of the user. Example: "12345" fields `Optional[List[str]]` - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `UserFull`. Returns a single user object. Not all available fields are returned by default. Use the [fields](#param-fields) query parameter to explicitly request any specific fields using the [fields](#get-users-id--request--fields) parameter. ## Update user Updates a managed or app user in an enterprise. This endpoint is only available to users and applications with the right admin permissions. This operation is performed by calling function `update_user_by_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-users-id/). ``` client.users.update_user_by_id(user.id, name=updated_user_name) ``` ### Arguments user_id `str` - The ID of the user. Example: "12345" enterprise `Optional[str]` - Set this to `null` to roll the user out of the enterprise and make them a free user. notify `Optional[bool]` - Whether the user should receive an email when they are rolled out of an enterprise. name `Optional[str]` - The name of the user. login `Optional[str]` - The email address the user uses to log in Note: If the target user's email is not confirmed, then the primary login address cannot be changed. role `Optional[UpdateUserByIdRole]` - The user’s enterprise role. language `Optional[str]` - The language of the user, formatted in modified version of the [ISO 639-1](https://ja.developer.box.com/guides/api-calls/language-codes) format. is_sync_enabled `Optional[bool]` - Whether the user can use Box Sync. job_title `Optional[str]` - The user’s job title. phone `Optional[str]` - The user’s phone number. address `Optional[str]` - The user’s address. tracking_codes `Optional[List[TrackingCode]]` - Tracking codes allow an admin to generate reports from the admin console and assign an attribute to a specific group of users. This setting must be enabled for an enterprise before it can be used. can_see_managed_users `Optional[bool]` - Whether the user can see other enterprise users in their contact list. timezone `Optional[str]` - The user's timezone. is_external_collab_restricted `Optional[bool]` - Whether the user is allowed to collaborate with users outside their enterprise. is_exempt_from_device_limits `Optional[bool]` - Whether to exempt the user from enterprise device limits. is_exempt_from_login_verification `Optional[bool]` - Whether the user must use two-factor authentication. is_password_reset_required `Optional[bool]` - Whether the user is required to reset their password. status `Optional[UpdateUserByIdStatus]` - The user's account status. space_amount `Optional[int]` - The user’s total available space in bytes. Set this to `-1` to indicate unlimited storage. notification_email `Optional[UpdateUserByIdNotificationEmail]` - An alternate notification email address to which email notifications are sent. When it's confirmed, this will be the email address to which notifications are sent instead of to the primary email address. Set this value to `null` to remove the notification email. external_app_user_id `Optional[str]` - An external identifier for an app user, which can be used to look up the user. This can be used to tie user IDs from external identity providers to Box users. Note: In order to update this field, you need to request a token using the application that created the app user. fields `Optional[List[str]]` - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `UserFull`. Returns the updated user object. ## Delete user Deletes a user. By default this will fail if the user still owns any content. Move their owned content first before proceeding, or use the `force` field to delete the user and their files. This operation is performed by calling function `delete_user_by_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-users-id/). ``` client.users.delete_user_by_id(user.id) ``` ### Arguments user_id `str` - The ID of the user. Example: "12345" notify `Optional[bool]` - Whether the user will receive email notification of the deletion. force `Optional[bool]` - Whether the user should be deleted even if this user still own files. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `None`. Removes the user and returns an empty response. --- ### Version Lifecycle **Type:** page | **Section:** Additional Resources Version Lifecycle We use a modified version of Semantic Versioning for all changes. It is strongly encouraged that you pin at least the… # Version Lifecycle We use a modified version of [Semantic Versioning](https://semver.org/) for all changes. It is strongly encouraged that you pin at least the major version and potentially the minor version to avoid pulling in breaking changes. Increasing the major version of an SDK indicates that this SDK underwent significant and substantial changes to support new idioms and patterns in the language. Major versions are introduced when public interfaces (e.g. classes, methods, types, etc.), behaviours, or semantics have changed. Semantic Versions take the form of `MAJOR.MINOR.PATCH`. When bugs are fixed in the library in a backwards-compatible way, the PATCH level will be incremented by one. PATCH changes should not break your code and are generally safe for upgrade. When a new feature set comes online or a small breaking change is introduced, the MINOR version will be incremented by one and the PATCH version resets to zero. MINOR changes may require some amount of manual code change for upgrade. These backwards-incompatible changes will mostly be limited to a small number of function signature changes. The MAJOR version is used to indicate the family of technology represented by the library. Breaking changes that require extensive reworking of code will cause the MAJOR version to be incremented by one, and the MINOR and PATCH versions will be reset to zero. Since frequent major updates can be very disruptive, we will only introduce this type of breaking change when absolutely necessary. New MAJOR versions will be communicated in advance via: - An email announcement is sent to affected accounts, announcing our plans to end support for the specific SDK version. The email will outline the path to end-of-support, specify the campaign timelines, and provide upgrade guidance. - Box SDK documentation, such as API reference documentation, user guides, SDK product marketing pages, and GitHub readme(s) are updated to indicate the campaign timeline and provide guidance on upgrading affected applications. - Deprecation warnings are added to the SDKs, outlining the path to end-of-support and linking to the SDK documentation. Deprecations are introduced in minor releases. We will not introduce new deprecations in patch releases. These deprecations will preserve the existing behaviour while emitting a warning that provide guidance on: - How to achieve similar behaviour if an alternative is available - The version in which the deprecation will be enforced. Deprecations will only be enforced in major releases. For example, if a behaviour is deprecated in version 1.2.0, it will continue to work, with a warning, for all releases in the 1.x series. The behaviour will change and the deprecation will be removed in the next major release (2.x.x). --- ### Version Lifecycle **Type:** page | **Section:** Additional Resources Version Lifecycle We use a modified version of Semantic Versioning for all changes. It is strongly encouraged that you pin at least the… # Version Lifecycle We use a modified version of [Semantic Versioning](https://semver.org/) for all changes. It is strongly encouraged that you pin at least the major version and potentially the minor version to avoid pulling in breaking changes. Increasing the major version of an SDK indicates that this SDK underwent significant and substantial changes to support new idioms and patterns in the language. Major versions are introduced when public interfaces (e.g. classes, methods, types, etc.), behaviours, or semantics have changed. Semantic Versions take the form of `MAJOR.MINOR.PATCH`. When bugs are fixed in the library in a backwards-compatible way, the PATCH level will be incremented by one. PATCH changes should not break your code and are generally safe for upgrade. When a new feature set comes online or a small breaking change is introduced, the MINOR version will be incremented by one and the PATCH version resets to zero. MINOR changes may require some amount of manual code change for upgrade. These backwards-incompatible changes will mostly be limited to a small number of function signature changes. The MAJOR version is used to indicate the family of technology represented by the library. Breaking changes that require extensive reworking of code will cause the MAJOR version to be incremented by one, and the MINOR and PATCH versions will be reset to zero. Since frequent major updates can be very disruptive, we will only introduce this type of breaking change when absolutely necessary. New MAJOR versions will be communicated in advance via: - An email announcement is sent to affected accounts, announcing our plans to end support for the specific SDK version. The email will outline the path to end-of-support, specify the campaign timelines, and provide upgrade guidance. - Box SDK documentation, such as API reference documentation, user guides, SDK product marketing pages, and GitHub readme(s) are updated to indicate the campaign timeline and provide guidance on upgrading affected applications. - Deprecation warnings are added to the SDKs, outlining the path to end-of-support and linking to the SDK documentation. Deprecations are introduced in minor releases. We will not introduce new deprecations in patch releases. These deprecations will preserve the existing behaviour while emitting a warning that provide guidance on: - How to achieve similar behaviour if an alternative is available - The version in which the deprecation will be enforced. Deprecations will only be enforced in major releases. For example, if a behaviour is deprecated in version 1.2.0, it will continue to work, with a warning, for all releases in the 1.x series. The behaviour will change and the deprecation will be removed in the next major release (2.x.x). --- ### Version Lifecycle **Type:** page | **Section:** Additional Resources Version Lifecycle We use a modified version of Semantic Versioning for all changes. It is strongly encouraged that you pin at least the… # Version Lifecycle We use a modified version of [Semantic Versioning](https://semver.org/) for all changes. It is strongly encouraged that you pin at least the major version and potentially the minor version to avoid pulling in breaking changes. Increasing the major version of an SDK indicates that this SDK underwent significant and substantial changes to support new idioms and patterns in the language. Major versions are introduced when public interfaces (e.g. classes, methods, types, etc.), behaviours, or semantics have changed. Semantic Versions take the form of `MAJOR.MINOR.PATCH`. When bugs are fixed in the library in a backwards-compatible way, the PATCH level will be incremented by one. PATCH changes should not break your code and are generally safe for upgrade. When a new feature set comes online or a small breaking change is introduced, the MINOR version will be incremented by one and the PATCH version resets to zero. MINOR changes may require some amount of manual code change for upgrade. These backwards-incompatible changes will mostly be limited to a small number of function signature changes. The MAJOR version is used to indicate the family of technology represented by the library. Breaking changes that require extensive reworking of code will cause the MAJOR version to be incremented by one, and the MINOR and PATCH versions will be reset to zero. Since frequent major updates can be very disruptive, we will only introduce this type of breaking change when absolutely necessary. New MAJOR versions will be communicated in advance via: - An email announcement is sent to affected accounts, announcing our plans to end support for the specific SDK version. The email will outline the path to end-of-support, specify the campaign timelines, and provide upgrade guidance. - Box SDK documentation, such as API reference documentation, user guides, SDK product marketing pages, and GitHub readme(s) are updated to indicate the campaign timeline and provide guidance on upgrading affected applications. - Deprecation warnings are added to the SDKs, outlining the path to end-of-support and linking to the SDK documentation. Deprecations are introduced in minor releases. We will not introduce new deprecations in patch releases. These deprecations will preserve the existing behaviour while emitting a warning that provide guidance on: - How to achieve similar behaviour if an alternative is available - The version in which the deprecation will be enforced. Deprecations will only be enforced in major releases. For example, if a behaviour is deprecated in version 1.2.0, it will continue to work, with a warning, for all releases in the 1.x series. The behaviour will change and the deprecation will be removed in the next major release (2.x.x). --- ### Version Lifecycle **Type:** page | **Section:** Additional Resources Version Lifecycle We use a modified version of Semantic Versioning for all changes. It is strongly encouraged that you pin at least the… # Version Lifecycle We use a modified version of [Semantic Versioning](https://semver.org/) for all changes. It is strongly encouraged that you pin at least the major version and potentially the minor version to avoid pulling in breaking changes. Increasing the major version of an SDK indicates that this SDK underwent significant and substantial changes to support new idioms and patterns in the language. Major versions are introduced when public interfaces (e.g. classes, methods, types, etc.), behaviours, or semantics have changed. Semantic Versions take the form of `MAJOR.MINOR.PATCH`. When bugs are fixed in the library in a backwards-compatible way, the PATCH level will be incremented by one. PATCH changes should not break your code and are generally safe for upgrade. When a new feature set comes online or a small breaking change is introduced, the MINOR version will be incremented by one and the PATCH version resets to zero. MINOR changes may require some amount of manual code change for upgrade. These backwards-incompatible changes will mostly be limited to a small number of function signature changes. The MAJOR version is used to indicate the family of technology represented by the library. Breaking changes that require extensive reworking of code will cause the MAJOR version to be incremented by one, and the MINOR and PATCH versions will be reset to zero. Since frequent major updates can be very disruptive, we will only introduce this type of breaking change when absolutely necessary. New MAJOR versions will be communicated in advance via: - An email announcement is sent to affected accounts, announcing our plans to end support for the specific SDK version. The email will outline the path to end-of-support, specify the campaign timelines, and provide upgrade guidance. - Box SDK documentation, such as API reference documentation, user guides, SDK product marketing pages, and GitHub readme(s) are updated to indicate the campaign timeline and provide guidance on upgrading affected applications. - Deprecation warnings are added to the SDKs, outlining the path to end-of-support and linking to the SDK documentation. Deprecations are introduced in minor releases. We will not introduce new deprecations in patch releases. These deprecations will preserve the existing behaviour while emitting a warning that provide guidance on: - How to achieve similar behaviour if an alternative is available - The version in which the deprecation will be enforced. Deprecations will only be enforced in major releases. For example, if a behaviour is deprecated in version 1.2.0, it will continue to work, with a warning, for all releases in the 1.x series. The behaviour will change and the deprecation will be removed in the next major release (2.x.x). --- ### Version Lifecycle **Type:** page | **Section:** Additional Resources Version Lifecycle We use a modified version of Semantic Versioning for all changes. It is strongly encouraged that you pin at least the… # Version Lifecycle We use a modified version of [Semantic Versioning](https://semver.org/) for all changes. It is strongly encouraged that you pin at least the major version and potentially the minor version to avoid pulling in breaking changes. Increasing the major version of an SDK indicates that this SDK underwent significant and substantial changes to support new idioms and patterns in the language. Major versions are introduced when public interfaces (e.g. classes, methods, types, etc.), behaviours, or semantics have changed. Semantic Versions take the form of `MAJOR.MINOR.PATCH`. When bugs are fixed in the library in a backwards-compatible way, the PATCH level will be incremented by one. PATCH changes should not break your code and are generally safe for upgrade. When a new feature set comes online or a small breaking change is introduced, the MINOR version will be incremented by one and the PATCH version resets to zero. MINOR changes may require some amount of manual code change for upgrade. These backwards-incompatible changes will mostly be limited to a small number of function signature changes. The MAJOR version is used to indicate the family of technology represented by the library. Breaking changes that require extensive reworking of code will cause the MAJOR version to be incremented by one, and the MINOR and PATCH versions will be reset to zero. Since frequent major updates can be very disruptive, we will only introduce this type of breaking change when absolutely necessary. New MAJOR versions will be communicated in advance via: - An email announcement is sent to affected accounts, announcing our plans to end support for the specific SDK version. The email will outline the path to end-of-support, specify the campaign timelines, and provide upgrade guidance. - Box SDK documentation, such as API reference documentation, user guides, SDK product marketing pages, and GitHub readme(s) are updated to indicate the campaign timeline and provide guidance on upgrading affected applications. - Deprecation warnings are added to the SDKs, outlining the path to end-of-support and linking to the SDK documentation. Deprecations are introduced in minor releases. We will not introduce new deprecations in patch releases. These deprecations will preserve the existing behaviour while emitting a warning that provide guidance on: - How to achieve similar behaviour if an alternative is available - The version in which the deprecation will be enforced. Deprecations will only be enforced in major releases. For example, if a behaviour is deprecated in version 1.2.0, it will continue to work, with a warning, for all releases in the 1.x series. The behaviour will change and the deprecation will be removed in the next major release (2.x.x). --- ### Version Lifecycle **Type:** page | **Section:** Additional Resources Version Lifecycle We use a modified version of Semantic Versioning for all changes. It is strongly encouraged that you pin at least the… # Version Lifecycle We use a modified version of [Semantic Versioning](https://semver.org/) for all changes. It is strongly encouraged that you pin at least the major version and potentially the minor version to avoid pulling in breaking changes. Increasing the major version of an SDK indicates that this SDK underwent significant and substantial changes to support new idioms and patterns in the language. Major versions are introduced when public interfaces (e.g. classes, methods, types, etc.), behaviours, or semantics have changed. Semantic Versions take the form of `MAJOR.MINOR.PATCH`. When bugs are fixed in the library in a backwards-compatible way, the PATCH level will be incremented by one. PATCH changes should not break your code and are generally safe for upgrade. When a new feature set comes online or a small breaking change is introduced, the MINOR version will be incremented by one and the PATCH version resets to zero. MINOR changes may require some amount of manual code change for upgrade. These backwards-incompatible changes will mostly be limited to a small number of function signature changes. The MAJOR version is used to indicate the family of technology represented by the library. Breaking changes that require extensive reworking of code will cause the MAJOR version to be incremented by one, and the MINOR and PATCH versions will be reset to zero. Since frequent major updates can be very disruptive, we will only introduce this type of breaking change when absolutely necessary. New MAJOR versions will be communicated in advance via: - An email announcement is sent to affected accounts, announcing our plans to end support for the specific SDK version. The email will outline the path to end-of-support, specify the campaign timelines, and provide upgrade guidance. - Box SDK documentation, such as API reference documentation, user guides, SDK product marketing pages, and GitHub readme(s) are updated to indicate the campaign timeline and provide guidance on upgrading affected applications. - Deprecation warnings are added to the SDKs, outlining the path to end-of-support and linking to the SDK documentation. Deprecations are introduced in minor releases. We will not introduce new deprecations in patch releases. These deprecations will preserve the existing behaviour while emitting a warning that provide guidance on: - How to achieve similar behaviour if an alternative is available - The version in which the deprecation will be enforced. Deprecations will only be enforced in major releases. For example, if a behaviour is deprecated in version 1.2.0, it will continue to work, with a warning, for all releases in the 1.x series. The behaviour will change and the deprecation will be removed in the next major release (2.x.x). --- ### Version Lifecycle **Type:** page | **Section:** Additional Resources Version Lifecycle We use a modified version of Semantic Versioning for all changes. It is strongly encouraged that you pin at least the… # Version Lifecycle We use a modified version of [Semantic Versioning](https://semver.org/) for all changes. It is strongly encouraged that you pin at least the major version and potentially the minor version to avoid pulling in breaking changes. Increasing the major version of an SDK indicates that this SDK underwent significant and substantial changes to support new idioms and patterns in the language. Major versions are introduced when public interfaces (e.g. classes, methods, types, etc.), behaviours, or semantics have changed. Semantic Versions take the form of `MAJOR.MINOR.PATCH`. When bugs are fixed in the library in a backwards-compatible way, the PATCH level will be incremented by one. PATCH changes should not break your code and are generally safe for upgrade. When a new feature set comes online or a small breaking change is introduced, the MINOR version will be incremented by one and the PATCH version resets to zero. MINOR changes may require some amount of manual code change for upgrade. These backwards-incompatible changes will mostly be limited to a small number of function signature changes. The MAJOR version is used to indicate the family of technology represented by the library. Breaking changes that require extensive reworking of code will cause the MAJOR version to be incremented by one, and the MINOR and PATCH versions will be reset to zero. Since frequent major updates can be very disruptive, we will only introduce this type of breaking change when absolutely necessary. New MAJOR versions will be communicated in advance via: - An email announcement is sent to affected accounts, announcing our plans to end support for the specific SDK version. The email will outline the path to end-of-support, specify the campaign timelines, and provide upgrade guidance. - Box SDK documentation, such as API reference documentation, user guides, SDK product marketing pages, and GitHub readme(s) are updated to indicate the campaign timeline and provide guidance on upgrading affected applications. - Deprecation warnings are added to the SDKs, outlining the path to end-of-support and linking to the SDK documentation. Deprecations are introduced in minor releases. We will not introduce new deprecations in patch releases. These deprecations will preserve the existing behaviour while emitting a warning that provide guidance on: - How to achieve similar behaviour if an alternative is available - The version in which the deprecation will be enforced. Deprecations will only be enforced in major releases. For example, if a behaviour is deprecated in version 1.2.0, it will continue to work, with a warning, for all releases in the 1.x series. The behaviour will change and the deprecation will be removed in the next major release (2.x.x). --- ### Version Lifecycle **Type:** page | **Section:** Additional Resources Version Lifecycle We use a modified version of Semantic Versioning for all changes. It is strongly encouraged that you pin at least the… # Version Lifecycle We use a modified version of [Semantic Versioning](https://semver.org/) for all changes. It is strongly encouraged that you pin at least the major version and potentially the minor version to avoid pulling in breaking changes. Increasing the major version of an SDK indicates that this SDK underwent significant and substantial changes to support new idioms and patterns in the language. Major versions are introduced when public interfaces (e.g. classes, methods, types, etc.), behaviours, or semantics have changed. Semantic Versions take the form of `MAJOR.MINOR.PATCH`. When bugs are fixed in the library in a backwards-compatible way, the PATCH level will be incremented by one. PATCH changes should not break your code and are generally safe for upgrade. When a new feature set comes online or a small breaking change is introduced, the MINOR version will be incremented by one and the PATCH version resets to zero. MINOR changes may require some amount of manual code change for upgrade. These backwards-incompatible changes will mostly be limited to a small number of function signature changes. The MAJOR version is used to indicate the family of technology represented by the library. Breaking changes that require extensive reworking of code will cause the MAJOR version to be incremented by one, and the MINOR and PATCH versions will be reset to zero. Since frequent major updates can be very disruptive, we will only introduce this type of breaking change when absolutely necessary. New MAJOR versions will be communicated in advance via: - An email announcement is sent to affected accounts, announcing our plans to end support for the specific SDK version. The email will outline the path to end-of-support, specify the campaign timelines, and provide upgrade guidance. - Box SDK documentation, such as API reference documentation, user guides, SDK product marketing pages, and GitHub readme(s) are updated to indicate the campaign timeline and provide guidance on upgrading affected applications. - Deprecation warnings are added to the SDKs, outlining the path to end-of-support and linking to the SDK documentation. Deprecations are introduced in minor releases. We will not introduce new deprecations in patch releases. These deprecations will preserve the existing behaviour while emitting a warning that provide guidance on: - How to achieve similar behaviour if an alternative is available - The version in which the deprecation will be enforced. Deprecations will only be enforced in major releases. For example, if a behaviour is deprecated in version 1.2.0, it will continue to work, with a warning, for all releases in the 1.x series. The behaviour will change and the deprecation will be removed in the next major release (2.x.x). --- ### Watermarking **Type:** page | **Section:** Additional Resources Watermarking Watermarking allows you to place a semi-transparent overlay on an embedded file preview that displays a viewer's email address… # Watermarking Watermarking allows you to place a semi-transparent overlay on an embedded file preview that displays a viewer's email address or user ID and the time of access over a file's content. Once a watermark is applied to a file or folder via the API, the watermark will be displayed on any file preview. - [Get Watermark on a File](#get-watermark-on-a-file) - [Apply Watermark to a File](#apply-watermark-to-a-file) - [Remove Watermark from a File](#remove-watermark-from-a-file) - [Get Watermark on a Folder](#get-watermark-on-a-folder) - [Apply Watermark to a Folder](#apply-watermark-to-a-folder) - [Remove Watermark from a Folder](#remove-watermark-from-a-folder) ## Get Watermark on a File To get watermark information for a file call the [`files.getWatermark(fileID, options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Files.html#getWatermark) method. ``` client.files.getWatermark('11111') .then(watermark => { /* watermark -> { watermark: { created_at: '2016-10-31T15:33:33-07:00', modified_at: '2016-10-31T15:33:33-07:00' } } */ }); ``` ## Apply Watermark to a File To apply or update the watermark to a file call the [`files.applyWatermark(fileID, options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Files.html#applyWatermark) method. ``` client.files.applyWatermark('11111') .then(watermark => { /* watermark -> { watermark: { created_at: '2016-10-31T15:33:33-07:00', modified_at: '2016-10-31T15:33:33-07:00' } } */ }); ``` ## Remove Watermark from a File A file's watermark can be removed by calling [`files.removeWatermark(fileID, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Files.html#removeWatermark). ``` client.files.removeWatermark('11111') .then(() => { // removal succeeded — no value returned }); ``` ## Get Watermark on a Folder To get watermark information for a folder call the [`folders.getWatermark(folderID, options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Folders.html#getWatermark) method. ``` client.folders.getWatermark('22222') .then(watermark => { /* watermark -> { watermark: { created_at: '2016-10-31T15:33:33-07:00', modified_at: '2016-10-31T15:33:33-07:00' } } */ }); ``` ## Apply Watermark to a Folder To apply or update the watermark for a folder call the [`folders.applyWatermark(folderID, options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Folders.html#applyWatermark) method. ``` client.folders.applyWatermark('22222') .then(watermark => { /* watermark -> { watermark: { created_at: '2016-10-31T15:33:33-07:00', modified_at: '2016-10-31T15:33:33-07:00' } } */ }); ``` ## Remove Watermark from a Folder A folder's watermark can be removed by calling [`folders.removeWatermark(folderID, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Folders.html#removeWatermark). ``` client.folders.removeWatermark('22222') .then(() => { // removal succeeded — no value returned }); ``` --- ### Watermarking **Type:** page | **Section:** Additional Resources Watermarking The ability to watermark files and folders is represented as a sub-resource on the Files and Folders resources, respectively… # Watermarking The ability to watermark files and folders is represented as a sub-resource on the Files and Folders resources, respectively. You can think of the sub-resource as a "label" marking whether the file or folder is watermarked or not. If you apply a watermark label to a folder, then all files inside of it will be protected by the watermark (e.g. previews will be watermarked). However, those files' watermark sub-resource is independent from the folder that got watermarked. This allows you to watermark files and folders independently. - [Get Watermark on File](#get-watermark-on-file) - [Apply Watermark on File](#apply-watermark-on-file) - [Remove Watermark on File](#remove-watermark-on-file) - [Get Watermark on Folder](#get-watermark-on-folder) - [Apply Watermark on Folder](#apply-watermark-on-folder) - [Remove Watermark on Folder](#remove-watermark-on-folder) ## Get Watermark on File Calling [`getWatermark(String... fields)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFile.html#getWatermark-java.lang.String...-) will return a BoxWatermark object containing information about the watermark associated for this file. If the file does not have a watermark applied on it, a 404 Not Found will be returned. ``` BoxFile file = new BoxFile(api, id); BoxWatermark watermark = file.getWatermark(); ``` ## Apply Watermark on File To apply watermark on file, call [`applyWatermark()`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFile.html#applyWatermark--) method. While the endpoint accepts a JSON body describing the watermark to apply, custom watermarks are not supported yet. The method will return a BoxWatermark object containing information about the watermark applied on this file. ``` BoxFile file = new BoxFile(api, id); file.applyWatermark(); ``` ## Remove Watermark on File A watermark can be removed by calling the [`removeWatermark()`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFile.html#removeWatermark--) method. If the file did not have a watermark applied on it, a 404 Not Found will be returned by API. ``` BoxFile file = new BoxFile(api, id); file.removeWatermark(); ``` ## Get Watermark on Folder Calling [`getWatermark(String... fields)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFolder.html#getWatermark-java.lang.String...-) will return a BoxWatermark object containing information about the watermark associated for this folder. If the folder does not have a watermark applied on it, a 404 Not Found will be returned. ``` BoxFolder folder = new BoxFolder(api, id); BoxWatermark watermark = folder.getWatermark(); ``` ## Apply Watermark on Folder To apply watermark on folder, call [`applyWatermark()`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFolder.html#applyWatermark--) method. The method will return a BoxWatermark object containing information about the watermark applied on this folder. ``` BoxFolder folder = new BoxFolder(api, id); fodler.applyWatermark(); ``` ## Remove Watermark on Folder A watermark can be removed by calling the [`removeWatermark()`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFolder.html#removeWatermark--) method. If the folder did not have a watermark applied on it, a 404 Not Found will be returned by API. ``` BoxFolder folder = new BoxFolder(api, id); folder.removeWatermark(); ``` --- ### Watermarking **Type:** page | **Section:** Additional Resources Watermarking The ability to watermark files and folders is represented as a sub-resource on the Files and Folders resources, respectively… # Watermarking The ability to watermark files and folders is represented as a sub-resource on the Files and Folders resources, respectively. You can think of the sub-resource as a "label" marking whether the file or folder is watermarked or not. If you apply a watermark label to a folder, then all files inside of it will be protected by the watermark (e.g. previews will be watermarked). However, those files' watermark sub-resource is independent from the folder that got watermarked. This allows you to watermark files and folders independently. [Watermarking](#watermarking) - [Get Watermark on File or Folder](#get-watermark-on-file-or-folder) - [Apply Watermark on File or Folder](#apply-watermark-on-file-or-folder) - [Remove Watermark on File or Folder](#remove-watermark-on-file-or-folder) ## Get Watermark on File or Folder To get a watermark object, call [`file.get_watermark()`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.file.File.get_watermark()) or [`folder.get_watermark()`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.folder.Folder.get_watermark()) will return the [`Watermark`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.watermark.Watermark) object populated with data from the API. ``` watermark = client.file(file_id='12345').get_watermark() print(f'Watermark created at {watermark.created_at} and modified at {watermark.modified_at}') ``` ``` watermark = client.folder(folder_id='11111').get_watermark() print(f'Watermark created at {watermark.created_at} and modified at {watermark.modified_at}') ``` ## Apply Watermark on File or Folder To assign a watermark on a file or folder, call [file.apply_watermark()](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.file.File.apply_watermark()) or [folder.apply_watermark()][apply-folder-watermark] will return the [`Watermark`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.watermark.Watermark) object populated with data from the API. ``` watermark = client.file(file_id='12345').apply_watermark() print(f'Watermark created at {watermark.created_at} and modified at {watermark.modified_at}') ``` ``` watermark = client.folder(folder_id='11111').apply_watermark() print(f'Watermark created at {watermark.created_at} and modified at {watermark.modified_at}') ``` ## Remove Watermark on File or Folder To remove a watermark from a file or folder, call [file.delete_watermark()](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.file.File.delete_watermark()) or [folder.delete_watermark()][delete-folder-watermark] will return `True` to indicate that the deletion was successful. ``` client.file(file_id='12345').delete_watermark() print('The file watermark was deleted!') ``` ``` client.folder(folder_id='11111').delete_watermark() print('The folder watermark was deleted!') ``` --- ### Watermarking **Type:** page | **Section:** Additional Resources Watermarking Watermarking allows you to place a semi-transparent overlay on an embedded file preview that displays a viewer's email address… # Watermarking Watermarking allows you to place a semi-transparent overlay on an embedded file preview that displays a viewer's email address or user ID and the time of access over a file's content. Once a watermark is applied to a file or folder via the API, the watermark will be displayed on any file preview. - [Get Watermark on a File](#get-watermark-on-a-file) - [Apply Watermark to a File](#apply-watermark-to-a-file) - [Remove Watermark from a File](#remove-watermark-from-a-file) - [Get Watermark on a Folder](#get-watermark-on-a-folder) - [Apply Watermark to a Folder](#apply-watermark-to-a-folder) - [Remove Watermark from a Folder](#remove-watermark-from-a-folder) ## Get Watermark on a File To get watermark information for a file call the `FilesManager.GetWatermarkAsync(string id)` method with the ID of the file. ``` BoxWatermark watermark = await client.FilesManager.GetWatermarkAsync("11111"); ``` ## Apply Watermark to a File To apply or update the watermark to a file call the `FilesManager.ApplyWatermarkAsync(string id, BoxApplyWatermarkRequest applyWatermarkRequest = null)` method with the ID of the file. ``` BoxWatermark watermark = await client.FilesManager.ApplyWatermarkAsync("11111"); ``` ## Remove Watermark from a File A file's watermark can be removed by calling `FilesManager.RemoveWatermarkAsync(string id)` with the ID of the watermarked file. ``` await client.FilesManager.RemoveWatermarkAsync("11111"); ``` ## Get Watermark on a Folder To get watermark information for a folder call the `FoldersManager.GetWatermarkAsync(string id)` method with the ID of the folder. ``` BoxWatermark watermark = await client.FoldersManager.GetWatermarkAsync("22222"); ``` ## Apply Watermark to a Folder To apply or update the watermark for a folder call the `FoldersManager.ApplyWatermarkAsync(string id, BoxApplyWatermarkRequest applyWatermarkRequest = null)` method with the ID of the folder. ``` BoxWatermark watermark = await client.FoldersManager.ApplyWatermarkAsync("22222"); ``` ## Remove Watermark from a Folder A folder's watermark can be removed by calling `FoldersManager.RemoveWatermarkAsync(string id)` with the ID of the watermarked folder. ``` await client.FoldersManager.RemoveWatermarkAsync("22222"); ``` --- ### Web Links **Type:** page | **Section:** Additional Resources Web Links Web links are objects that point to URLs. These objects are also known as bookmarks within the Box web application. Web link… # Web Links Web links are objects that point to URLs. These objects are also known as bookmarks within the Box web application. Web link objects are treated similarly to file objects, so they will also support shared links, copy, permanent delete, and restore. - [Create a Web Link](#create-a-web-link) - [Get a Web Link's information](#get-a-web-links-information) - [Update a Web Link](#update-a-web-link) - [Delete a Web Link](#delete-a-web-link) - [Copy a Web Link](#copy-a-web-link) - [Move a Web Link](#move-a-web-link) ## Create a Web Link To create a web link call the [`weblinks.create(url, parentID, options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/WebLinks.html#create) method. ``` client.weblinks.create( 'https://www.box.com', '22222', { name: 'Box Website!', description: 'Cloud Content Management' }) .then(weblink => { /* weblink -> { type: 'web_link', id: '11111', sequence_id: '0', etag: '0', name: 'Box Website!', url: 'https://www.box.com', created_by: { type: 'user', id: '33333', name: 'Example User', login: 'user@example.com' }, created_at: '2015-05-07T15:00:01-07:00', modified_at: '2015-05-07T15:00:01-07:00', parent: { type: 'folder', id: '22222', sequence_id: '1', etag: '1', name: 'Bookmarks' }, description: 'Enterprise Cloud Content Management', item_status: 'active', trashed_at: null, purged_at: null, shared_link: null, path_collection: { total_count: 2, entries: [ { type: 'folder', id: '0', sequence_id: null, etag: null, name: 'All Files' }, { type: 'folder', id: '22222', sequence_id: '1', etag: '1', name: 'Bookmarks' } ] }, modified_by: { type: 'user', id: '33333', name: 'Example User', login: 'user@example.com' }, owned_by: { type: 'user', id: '33333', name: 'Example User', login: 'user@example.com' } } */ }); ``` ## Get a Web Link's information You can request a web link object by ID by calling [`weblinks.get(weblinkID, options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/WebLinks.html#get). ``` client.weblinks.get('11111') .then(weblink => { /* weblink -> { type: 'web_link', id: '11111', sequence_id: '0', etag: '0', name: 'Box Website!', url: 'https://www.box.com', created_by: { type: 'user', id: '33333', name: 'Example User', login: 'user@example.com' }, created_at: '2015-05-07T15:00:01-07:00', modified_at: '2015-05-07T15:00:01-07:00', parent: { type: 'folder', id: '22222', sequence_id: '1', etag: '1', name: 'Bookmarks' }, description: 'Enterprise Cloud Content Management', item_status: 'active', trashed_at: null, purged_at: null, shared_link: null, path_collection: { total_count: 2, entries: [ { type: 'folder', id: '0', sequence_id: null, etag: null, name: 'All Files' }, { type: 'folder', id: '22222', sequence_id: '1', etag: '1', name: 'Bookmarks' } ] }, modified_by: { type: 'user', id: '33333', name: 'Example User', login: 'user@example.com' }, owned_by: { type: 'user', id: '33333', name: 'Example User', login: 'user@example.com' } } */ }); ``` Requesting information for only the fields you need with the `fields` option can improve performance and reduce the size of the network request. ``` client.weblinks.get('11111', {fields: 'url,name,description'}) .then(weblink => { /* weblink -> { type: 'web_link', id: '11111', sequence_id: '0', etag: '0', name: 'Box Website!', url: 'https://www.box.com', description: 'Enterprise Cloud Content Management' } */ }); ``` ## Update a Web Link To update a web link call the [`weblinks.update(weblinkID, updates, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/WebLinks.html#update) method with the fields to update and their new values. ``` client.weblinks.update( '11111', { name: 'Box Marketing Site', description: 'First page that customers land on' }) .then(weblink => { /* weblink -> { type: 'web_link', id: '11111', sequence_id: '0', etag: '0', name: 'Box Marketing Site', url: 'https://www.box.com', created_by: { type: 'user', id: '33333', name: 'Example User', login: 'user@example.com' }, created_at: '2015-05-07T15:00:01-07:00', modified_at: '2017-06-13T12:34:51-07:00', parent: { type: 'folder', id: '22222', sequence_id: '1', etag: '1', name: 'Bookmarks' }, description: 'First page that customers land on', item_status: 'active', trashed_at: null, purged_at: null, shared_link: null, path_collection: { total_count: 2, entries: [ { type: 'folder', id: '0', sequence_id: null, etag: null, name: 'All Files' }, { type: 'folder', id: '22222', sequence_id: '1', etag: '1', name: 'Bookmarks' } ] }, modified_by: { type: 'user', id: '33333', name: 'Example User', login: 'user@example.com' }, owned_by: { type: 'user', id: '33333', name: 'Example User', login: 'user@example.com' } } */ }); ``` ## Delete a Web Link To move a web link to the trash call the [`weblinks.delete(weblinkID, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/WebLinks.html#delete) method. ``` client.weblinks.delete('11111') .then(() => { // deletion succeeded — no value returned }); ``` ## Copy a Web Link Call the [`weblinks.copy(webLinkID, destinationFolderID, options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/WebLinks.html#copy) method to copy a web link into another folder. ``` client.weblinks.copy('11111', '0') .then(webLinkCopy => { /* webLinkCopy -> { type: 'web_link', id: '11112', sequence_id: '0', etag: '0', name: 'Renamed web link copy', url: 'http://example.com', created_by: { type: 'user', id: '22222', name: 'Example User', login: 'user@example.com' }, created_at: '2019-03-26T12:49:06-07:00', modified_at: '2019-03-26T12:49:06-07:00', parent: { type: 'folder', id: '0', sequence_id: null, etag: null, name: 'All Files' }, description: '', item_status: 'active', trashed_at: null, purged_at: null, shared_link: null, path_collection: { total_count: 1, entries: [ { type: 'folder', id: '0', sequence_id: null, etag: null, name: 'All Files' } ] }, modified_by: { type: 'user', id: '22222', name: 'Example User', login: 'user@example.com' }, owned_by: { type: 'user', id: '22222', name: 'Example User', login: 'user@example.com' } } */ }); ``` An optional `name` parameter can also be passed to rename the folder on copy. This can be used to avoid a name conflict when there is already an item with the same name in the target folder. ``` client.weblinks.copy('12345', '0', {name: 'Renamed web link'}) .then(webLinkCopy => { // ... }); ``` ## Move a Web Link Call the [`weblinks.move(webLinkID, destinationFolderID, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/WebLinks.html#move) method with the destination you want the folder moved to. ``` var webLinkID = '88888'; var destinationFolderID = '0'; client.weblinks.move(webLinkID, destinationFolderID) .then(webLink => { /* webLink -> { type: 'web_link', id: '88888', sequence_id: '0', etag: '0', name: 'Example Web Link', url: 'http://example.com', created_by: { type: 'user', id: '22222', name: 'Example User', login: 'user@example.com' }, created_at: '2019-03-26T12:49:06-07:00', modified_at: '2019-03-26T12:49:06-07:00', parent: { type: 'folder', id: '0', sequence_id: null, etag: null, name: 'All Files' }, description: '', item_status: 'active', trashed_at: null, purged_at: null, shared_link: null, path_collection: { total_count: 1, entries: [ { type: 'folder', id: '0', sequence_id: null, etag: null, name: 'All Files' } ] }, modified_by: { type: 'user', id: '22222', name: 'Example User', login: 'user@example.com' }, owned_by: { type: 'user', id: '22222', name: 'Example User', login: 'user@example.com' } } */ }); ``` --- ### Web Links **Type:** page | **Section:** Additional Resources Web Links Web links are objects that point to URLs. These objects are also known as bookmarks within the Box web application. Web link… # Web Links Web links are objects that point to URLs. These objects are also known as bookmarks within the Box web application. Web link objects are treated similarly to file objects. - [Create Web Link](#create-web-link) - [Get Web Link](#get-web-link) - [Update Web Link](#update-web-link) - [Delete Web Link](#delete-web-link) - [Create Shared Link](#create-shared-link) - [Remove Shared Link](#remove-shared-link) ## Create Web Link Calling [`BoxFolder.createWebLink(String name, URL url, String description)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFolder.html#createWebLink-java.lang.String-java.net.URL-java.lang.String-) will let you create a new web link with a specified name and description. ``` BoxFolder folder = new BoxFolder(api, id); URL url = new URL("https://www.example.com"); folder.createWebLink("Link to Example", url, "This goes to an example page"); ``` Name and description params are optional, so it is possible to create web link with only one of them or with URL only: [`BoxFolder.createWebLink(URL url)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxFolder.html#createWebLink-java.net.URL-) ``` BoxFolder folder = new BoxFolder(api, id); URL url = new URL("https://www.example.com"); BoxWebLink.Info webLinkInfo = folder.createWebLink(url); ``` ## Get Web Link A web link info can be retrieved by calling the [`getInfo(String... fields)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxWebLink.html#getInfo-java.lang.String...-) method. Optional parameters can be used to retrieve specific fields of the Device Pin object. ``` BoxWebLink webLink = new BoxWebLink(api, id); BoxWebLink.Info webLinkInfo = webLink.getInfo(); ``` ## Update Web Link A web link can be updated by calling the [`updateInfo(BoxWebLink.Info fieldsToUpdate)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxWebLink.html#updateInfo-com.box.sdk.BoxWebLink.Info-) method. ``` BoxWebLink webLink = new BoxWebLink(api, id); BoxWebLink.Info webLinkInfo = webLink.new Info(); webLinkInfo.setName("new name for weblink"); webLink.updateInfo(webLinkInfo); ``` ## Delete Web Link A web link can be deleted by calling the [`delete()`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxWebLink.html#delete--) method. ``` BoxWebLink webLink = new BoxWebLink(api, id); webLink.delete(); ``` ## Create Shared Link You can create a shared link for a web link by calling the [`createSharedLink(BoxSharedLinkWithoutPermissionsRequest sharedLinkRequest)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxWebLink.html#createSharedLink-com.box.sdk.sharedlink.BoxSharedLinkWithoutPermissionsRequest-) method. ``` // Optionally we can calculate and set the date when shared link will automatically be disabled final long ONE_WEEK_MILLIS = 1000 * 60 * 60 * 24 * 7; long unsharedTimestamp = System.currentTimeMillis() + ONE_WEEK_MILLIS; Date unsharedDate = new Date(unsharedTimestamp); BoxWebLink webLink = new BoxWebLink(api, "id"); BoxSharedLinkWithoutPermissionsRequest sharedLinkRequest = new BoxSharedLinkWithoutPermissionsRequest() .access(OPEN) .unsharedDate(unsharedDate); BoxSharedLink sharedLink = webLink.createSharedLink(sharedLinkRequest); ``` ## Remove Shared Link You can remove a shared link for a web link by calling the [`removeSharedLink`](remove-shared-link) method. ``` BoxWebLink webLink = new BoxWebLink(api, "12345"); BoxWebLink.Info webLinkInfo = webLink.getInfo(); info.removeSharedLink() webLink.updateInfo(info) ``` --- ### Web Links **Type:** page | **Section:** Additional Resources Web Links Web links are objects that point to URLs. These objects are also known as bookmarks within the Box web application. Web link… # Web Links Web links are objects that point to URLs. These objects are also known as bookmarks within the Box web application. Web link objects are treated similarly to file objects. **Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)* - [Create Web Link](#create-web-link) - [Get Web Link](#get-web-link) - [Update Web Link](#update-web-link) - [Move a Web Link](#move-a-web-link) - [Copy a Web Link](#copy-a-web-link) - [Rename a Web Link](#rename-a-web-link) - [Delete Web Link](#delete-web-link) - [Create a Shared Link](#create-a-shared-link) - [Update a Shared Link](#update-a-shared-link) - [Get a Shared Link](#get-a-shared-link) - [Remove a Shared Link](#remove-a-shared-link) ## Create Web Link To create a web link object, calling [`folder.create_web_link(target_url, name=None, description=None)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.folder.Folder.create_web_link) will let you create a new web link with a specified name and description. This method return an newly created [`WebLink`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.web_link.WebLink) object populated with data from the API, leaving the original object unmodified. ``` web_link = client.folder(folder_id='12345').create_web_link('https://example.com', 'Example Link', 'This is the description') print(f'Web Link url is {web_link.url} and its description is {web_link.description}') ``` ## Get Web Link To get a web link object, first call [`client.web_link(web_link_id)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.client.html#boxsdk.client.client.Client.web_link) to construct the appropriate [`WebLink`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.web_link.WebLink) object, and then calling [`web_link.get(*, fields=None, headers=None, **kwargs)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.base_object.BaseObject.get) will return the [`WebLink`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.web_link.WebLink) object populated with data from the API, leaving the original object unmodified. ``` web_link = client.web_link(web_link_id='12345').get() print(f'Web Link ID is {web_link.id} and its type is {web_link.type}') ``` ## Update Web Link To update a web link object, call [`web_link.update_info(data=data_to_update)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.base_object.BaseObject.update_info) with a `dict` of properties to update on the web link. This method returns a newly updated ['WebLink'](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.web_link.WebLink) object, leaving the original object unmodified. ``` updated_web_link = client.web_link(web_link_id='12345').update_info(data={'url': 'https://newurl.com'}) ``` ## Move a Web Link To move a web link from one folder into another, call [`web_link.move(parent_folder, name=None)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.base_item.BaseItem.move) with the destination folder to move the web link into. You can optionally provide a `name` parameter to automatically rename the web link in case of a name conflict in the destination folder. This method returns the updated [`WebLink`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.web_link.WebLink) object in the new folder. ``` web_link_id = '11111' destination_folder_id = '44444' web_link_to_move = client.web_link(web_link_id) destination_folder = client.folder(destination_folder_id) moved_web_link = web_link_to_move.move(parent_folder=destination_folder) print(f'Web link "{moved_web_link.name}" has been moved into folder "{moved_web_link.parent.name}"') ``` ## Copy a Web Link A web link can be copied to a new folder by calling [`web_link.copy(*, parent_folder, name=None, **_kwargs)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.base_item.BaseItem.copy) with the destination folder and an optional new name for the web link in case there is a name conflict in the destination folder. This method returns a [`WebLink`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.web_link.WebLink) object representing the copy of the web link in the destination folder. ``` web_link = client.web_link(web_link_id='12345') web_link_copy = web_link_to_copy.copy(parent_folder=destination_folder) print(f'Web link "{web_link_copy.name}" has been copied into folder "{web_link_copy.parent.name}"') ``` ## Rename a Web Link A web link can be renamed by calling [`web_link.rename(name)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.base_item.BaseItem.rename). This method returns the updated [`WebLink`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.web_link.WebLink) object with a new name. ``` web_link = client.web_link(web_link_id='12345') renamed_web_link = web_link.rename("new-name") print(f'Web link was renamed to "{renamed_web_link.name}"') ``` ## Delete Web Link To delete a web link, call [`web_link.delete()`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.base_object.BaseObject.delete). This method returns `True` to indicate that the deletion was successful. ``` client.web_link('12345').delete() print('The web link was deleted!') ``` ## Create a Shared Link A shared link for a web link can be generated by calling [`web_link.get_shared_link(*, access=None, unshared_at=SDK_VALUE_NOT_SET, password=None, vanity_name=None, **kwargs)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.web_link.WebLink.get_shared_link). This method returns a `unicode` string containing the shared link URL. ``` url = client.web_link('12345').get_shared_link(access='open') print(f'The web link shared link URL is: {url}') ``` ## Update a Shared Link A shared link for a web link can be updated by calling [`web_link.get_shared_link(*, access=None, unshared_at=SDK_VALUE_NOT_SET, password=None, vanity_name=None, **kwargs)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.web_link.WebLink.get_shared_link) with an updated list of properties. This method returns a `unicode` string containing the shared link URL. ``` url = client.web_link('12345').get_shared_link(access='open', password='letmein') print(f'The web link shared link URL is: {url}') ``` ## Get a Shared Link To check for an existing shared link on a web link, simply call `web_link.shared_link` This method returns a `unicode` string containing the shared link URL. ``` shared_link = client.web_link('12345').get().shared_link url = shared_link['url'] ``` ## Remove a Shared Link A shared link for a web link can be removed by calling [`web_link.remove_shared_link(**kwargs)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.web_link.WebLink.remove_shared_link). ``` client.web_link('12345').remove_shared_link() ``` --- ### Web Links **Type:** page | **Section:** Additional Resources Web Links Web links are objects that point to URLs. These objects are also known as bookmarks within the Box web application. Web link… # Web Links Web links are objects that point to URLs. These objects are also known as bookmarks within the Box web application. Web link objects are treated similarly to file objects, so they will also support shared links, copy, permanent delete, and restore. - [Create a Web Link](#create-a-web-link) - [Get a Web Link's information](#get-a-web-links-information) - [Update a Web Link](#update-a-web-link) - [Delete a Web Link](#delete-a-web-link) - [Copy a Web Link](#copy-a-web-link) - [Create or update a Shared Link](#create-or-update-a-shared-link) - [Remove a Shared Link](#remove-a-shared-link) ## Create a Web Link To create a web link call `WebLinksManager.CreateWebLinkAsync(BoxWebLinkRequest createWebLinkRequest)`. ``` var weblinkParams = new BoxWebLinkRequest() { Url = new Uri("http://www.example.com"), Parent = new BoxRequestEntity() { Id = "22222" } }; BoxWebLink link = await client.WebLinksManager.CreateWebLinkAsync(weblinkParams); ``` ## Get a Web Link's information You can request a web link object by ID by calling `WebLinksManager.GetWebLinkAsync(string webLinkId)` with the ID of the web link object. ``` BoxWebLink link = await client.WebLinksManager.GetWebLinkAsync("11111"); ``` ## Update a Web Link To update a web link call the `WebLinksManager.UpdateWebLinkAsync(string webLinkId, BoxWebLinkRequest updateWebLinkRequest)` method with the fields to update and their new values. ``` var updates = new BoxWebLinkRequest() { Name = "New Name for Weblink" }; BoxWebLink updatedLink = await client.WebLinksManager.UpdateWebLinkAsync("11111", updates); ``` ## Delete a Web Link To move a web link to the trash call `WebLinksManager.DeleteWebLinkAsync(string webLinkId)` with the ID of the web link object to delete. ``` await client.WebLinksManager.DeleteWebLinkAsync("11111"); ``` ## Copy a Web Link To make a copy of a web link, call `WebLinksManager.CopyAsync(string webLinkId, string destinationFolderId, IEnumerable<string> fields = null)` with the ID of the web link and the ID of the folder into which it should be copied. ``` BoxWebLink copiedLink = await client.WebLinksManager.CopyAsync("11111", "22222"); ``` ## Create or update a Shared Link A shared link for a web link can be created or updated by calling `WebLinksManager.CreateSharedLinkAsync(string id, BoxSharedLinkRequest sharedLinkRequest, IEnumerable<string> fields = null)`. ``` string webLinkId = "11111"; var sharedLinkParams = new BoxSharedLinkRequest() { Access = BoxSharedLinkAccessType.open }; BoxWebLink link = client.WebLinksManager .CreateSharedLinkAsync(webLinkId, sharedLinkParams); string sharedLinkUrl = link.SharedLink.Url; ``` ## Remove a Shared Link To remove a shared link from a web link, call `WebLinksManager.DeleteSharedLinkAsync(string id, IEnumerable<string> fields = null)` with the ID of the web link. ``` BoxWebLink updatedLink = client.WebLinksManager.DeleteSharedLinkAsync("11111"); ``` --- ### Web Links **Type:** page | **Section:** Additional Resources Web Links Web links are objects that point to URLs. These objects are also known as bookmarks within the Box web application. Web link… # Web Links Web links are objects that point to URLs. These objects are also known as bookmarks within the Box web application. Web link objects are treated similarly to file objects. - [Create Web Link](#create-web-link) - [Get Web Link](#get-web-link) - [Update Web Link](#update-web-link) - [Delete Web Link](#delete-web-link) - [Set Shared Link](#set-shared-link) - [Remove Shared Link](#remove-shared-link) ## Create Web Link To create a web link with a specified name and description, call [`client.webLinks.create(url:parentId:name:description:fields:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/WebLinksModule.html#/s:6BoxSDK14WebLinksModuleC6create3url8parentId4name11description6fields10completionySS_S2SSgAKSaySSGSgys6ResultOyAA0C4LinkCAA0A8SDKErrorCGctF). ``` client.webLinks.create( url: "https://www.example.com", parentId: "22222", name: "Link to Example", description: "This goes to an example page" ) { (result: Result<WebLink, BoxSDKError>) in guard case let .success(webLink) = result else { print("Error creating web link") return } print("WebLink \(webLink.name) was created at \(webLink.createdAt)") } ``` ## Get Web Link To retrieve information about a web link, call [`client.webLinks.get(webLinkId:fields:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/WebLinksModule.html#/s:6BoxSDK14WebLinksModuleC3get9webLinkId6fields10completionySS_SaySSGSgys6ResultOyAA0cH0CAA0A8SDKErrorCGctF) with the ID of web link. You can control which fields are returned in the resulting `WebLink` object by passing the `fields` parameter. ``` client.webLinks.get(webLinkId: "11111", fields: ["name", "created_at"]) { (result: Result<WebLink, BoxSDKError>) in guard case let .success(webLink) = result else { print("Error retrieving web link information") return } print("WebLink \(webLink.name) was created at \(webLink.createdAt)") } ``` ## Update Web Link To update a web link record, call [`client.webLinks.update(webLinkId:url:parentId:name:description:sharedLink:fields:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/WebLinksModule.html#/s:6BoxSDK14WebLinksModuleC6update9webLinkId3url06parentI04name11description06sharedH06fields10completionySS_SSSgA3mA17NullableParameterOyAA06SharedH4DataVGSgSaySSGSgys6ResultOyAA0cH0CAA0A8SDKErrorCGctF) with the ID of the web link to update and the properties to update. ``` client.webLinks.update(webLinkId: "11111", name: "new name for weblink") { (result: Result<WebLink, BoxSDKError>) in guard case let .success(webLink) = result else { print("Error updating web link information") return } print("WebLink \(webLink.name) was updated successfully") } ``` ## Delete Web Link To delete a web link, call [`client.webLinks.delete(webLinkId:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/WebLinksModule.html#/s:6BoxSDK14WebLinksModuleC6delete9webLinkId10completionySS_ys6ResultOyytAA0A8SDKErrorCGctF) with the ID of the web link to delete. ``` client.webLinks.delete(webLinkId: "11111") { (result: Result<Void, BoxSDKError>) in guard case .success = result else { print("Error removing web link") return } print("WebLink removed") } ``` ## Set Shared Link To add or update the shared link for a web link, call [`client.webLinks.setSharedLink(forWebLink:access:unsharedAt:vanityName:password:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/WebLinksModule.html#/s:6BoxSDK14WebLinksModuleC13setSharedLink03forcH06access10unsharedAt10vanityName8password10completionySS_AA0gH6AccessOSgAA17NullableParameterOy10Foundation4DateVGSgAOySSGSgAVys6ResultOyAA0gH0CAA0A8SDKErrorCGctF) with the ID of the web link and the shared link properties to set. ``` client.webLinks.setSharedLink(forWebLink: "11111", access: .open) { (result: Result<SharedLink, BoxSDKError>) in guard case let .success(sharedLink) = result else { print("Error setting weblink shared link") return } print("WebLink shared link URL is \(sharedLink.url), with \(sharedLink.access) access") } ``` ## Remove Shared Link To remove a webLink's shared link, call [`client.webLinks.deleteSharedLink(forWebLink:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/WebLinksModule.html#/s:6BoxSDK14WebLinksModuleC16deleteSharedLink03forcH010completionySS_ys6ResultOyytAA0A8SDKErrorCGctF) with the ID of the file. ``` client.webLinks.deleteSharedLink(forWebLink: "11111") { (result: Result<Void, BoxSDKError>) in guard case .success = result else { print("Error removing weblink shared link") return } print("WebLink shared link removed") } ``` --- ### Web Links **Type:** page | **Section:** Additional Resources Web Links Web links are objects that point to URLs. These objects are also known as bookmarks within the Box web application. Web link… # Web Links Web links are objects that point to URLs. These objects are also known as bookmarks within the Box web application. Web link objects are treated similarly to file objects. - [Create Web Link](#create-web-link) - [Get Web Link](#get-web-link) - [Update Web Link](#update-web-link) - [Delete Web Link](#delete-web-link) - [Set Shared Link](#set-shared-link) - [Remove Shared Link](#remove-shared-link) ## Create Web Link To create a web link with a specified name and description, call [`client.webLinks.create(url:parentId:name:description:fields:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/WebLinksModule.html#/s:6BoxSDK14WebLinksModuleC6create3url8parentId4name11description6fields10completionySS_S2SSgAKSaySSGSgys6ResultOyAA0C4LinkCAA0A8SDKErrorCGctF). ``` client.webLinks.create( url: "https://www.example.com", parentId: "22222", name: "Link to Example", description: "This goes to an example page" ) { (result: Result<WebLink, BoxSDKError>) in guard case let .success(webLink) = result else { print("Error creating web link") return } print("WebLink \(webLink.name) was created at \(webLink.createdAt)") } ``` ## Get Web Link To retrieve information about a web link, call [`client.webLinks.get(webLinkId:fields:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/WebLinksModule.html#/s:6BoxSDK14WebLinksModuleC3get9webLinkId6fields10completionySS_SaySSGSgys6ResultOyAA0cH0CAA0A8SDKErrorCGctF) with the ID of web link. You can control which fields are returned in the resulting `WebLink` object by passing the `fields` parameter. ``` client.webLinks.get(webLinkId: "11111", fields: ["name", "created_at"]) { (result: Result<WebLink, BoxSDKError>) in guard case let .success(webLink) = result else { print("Error retrieving web link information") return } print("WebLink \(webLink.name) was created at \(webLink.createdAt)") } ``` ## Update Web Link To update a web link record, call [`client.webLinks.update(webLinkId:url:parentId:name:description:sharedLink:fields:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/WebLinksModule.html#/s:6BoxSDK14WebLinksModuleC6update9webLinkId3url06parentI04name11description06sharedH06fields10completionySS_SSSgA3mA17NullableParameterOyAA06SharedH4DataVGSgSaySSGSgys6ResultOyAA0cH0CAA0A8SDKErrorCGctF) with the ID of the web link to update and the properties to update. ``` client.webLinks.update(webLinkId: "11111", name: "new name for weblink") { (result: Result<WebLink, BoxSDKError>) in guard case let .success(webLink) = result else { print("Error updating web link information") return } print("WebLink \(webLink.name) was updated successfully") } ``` ## Delete Web Link To delete a web link, call [`client.webLinks.delete(webLinkId:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/WebLinksModule.html#/s:6BoxSDK14WebLinksModuleC6delete9webLinkId10completionySS_ys6ResultOyytAA0A8SDKErrorCGctF) with the ID of the web link to delete. ``` client.webLinks.delete(webLinkId: "11111") { (result: Result<Void, BoxSDKError>) in guard case .success = result else { print("Error removing web link") return } print("WebLink removed") } ``` ## Set Shared Link To add or update the shared link for a web link, call [`client.webLinks.setSharedLink(forWebLink:access:unsharedAt:vanityName:password:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/WebLinksModule.html#/s:6BoxSDK14WebLinksModuleC13setSharedLink03forcH06access10unsharedAt10vanityName8password10completionySS_AA0gH6AccessOSgAA17NullableParameterOy10Foundation4DateVGSgAOySSGSgAVys6ResultOyAA0gH0CAA0A8SDKErrorCGctF) with the ID of the web link and the shared link properties to set. ``` client.webLinks.setSharedLink(forWebLink: "11111", access: .open) { (result: Result<SharedLink, BoxSDKError>) in guard case let .success(sharedLink) = result else { print("Error setting weblink shared link") return } print("WebLink shared link URL is \(sharedLink.url), with \(sharedLink.access) access") } ``` ## Remove Shared Link To remove a webLink's shared link, call [`client.webLinks.deleteSharedLink(forWebLink:completion:)`](https://opensource.box.com/box-ios-sdk/Classes/WebLinksModule.html#/s:6BoxSDK14WebLinksModuleC16deleteSharedLink03forcH010completionySS_ys6ResultOyytAA0A8SDKErrorCGctF) with the ID of the file. ``` client.webLinks.deleteSharedLink(forWebLink: "11111") { (result: Result<Void, BoxSDKError>) in guard case .success = result else { print("Error removing weblink shared link") return } print("WebLink shared link removed") } ``` --- ### Webhooks **Type:** page | **Section:** Additional Resources Webhooks A webhook object enables you to attach events triggers to Box files and folders. These event triggers monitor events on Box objects… # Webhooks A webhook object enables you to attach events triggers to Box files and folders. These event triggers monitor events on Box objects and notify your application, via HTTP requests to a URL of your choosing, when they occur. - [Create a Webhook](#create-a-webhook) - [Get a Webhook's Information](#get-a-webhooks-information) - [Get all Webhooks Information](#get-all-webhooks-information) - [Update a Webhook](#update-a-webhook) - [Delete a Webhook](#delete-a-webhook) - [Validate a Webhook Message](#validate-a-webhook-message) ## Create a Webhook To attach a webhook to an item, call the [`webhooks.create(fileID, targetType, notificationURL, triggerTypes, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Webhooks.html#create) method with the type and ID of the item, a URL to send notifications to, and a list of triggers. The notification URL must be a valid HTTPS URL that you specify when you create a webhook. The triggerTypes param is an array of strings. Available options are documented here: [https://developer.box.com/guides/webhooks/triggers/](https://developer.box.com/guides/webhooks/triggers/) ``` // Attach a webhook that sends a notification to https://example.com/webhook when // file 11111 is renamed or downloaded. client.webhooks.create( '11111', client.itemTypes.FILE, 'https://example.com/webhook', [ client.webhooks.triggerTypes.FILE.RENAMED, client.webhooks.triggerTypes.FILE.DOWNLOADED ]) .then(webhook => { /* webhook -> { id: '12345', type: 'webhook', target: { id: '11111', type: 'file' }, created_by: { type: 'user', id: '33333', name: 'Example User', login: 'user@example.com' }, created_at: '2016-05-09T17:41:27-07:00', address: 'https://example.com/webhook', triggers: [ 'FILE.RENAMED', 'FILE.UPLOADED' ] } */ }); ``` ``` // Attach a webhook that sends a notification to https://example.com/webhook when // files are uploaded or downloaded within folder 22222. client.webhooks.create( '22222', client.itemTypes.FOLDER, 'https://example.com/webhook', [ client.webhooks.triggerTypes.FILE.UPLOADED, client.webhooks.triggerTypes.FILE.DOWNLOADED ]) .then(webhook => { /* webhook -> { id: '1234', type: 'webhook', target: { id: '22222', type: 'folder' }, created_by: { type: 'user', id: '33333', name: 'Example User', login: 'user@example.com' }, created_at: '2016-05-09T17:41:27-07:00', address: 'https://example.com/webhook', triggers: [ 'FILE.DOWNLOADED', 'FILE.UPLOADED' ] } */ }); ``` ## Get a Webhook's Information Retrieve information about a specific webhook by calling [`webhooks.get(webhookID, options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Webhooks.html#get) to retrieve a webhook by ID. ``` client.webhooks.get('1234') .then(webhook => { /* webhook -> { id: '1234', type: 'webhook', target: { id: '22222', type: 'folder' }, created_by: { type: 'user', id: '33333', name: 'Example User', login: 'user@example.com' }, created_at: '2016-05-09T17:41:27-07:00', address: 'https://example.com/webhook', triggers: [ 'FILE.DOWNLOADED', 'FILE.UPLOADED' ] } */ }); ``` ## Get all Webhooks Information Get a list of all webhooks for the requesting application and user by calling the [`webhooks.getAll(options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Webhooks.html#getAll) method. The maximum limit per page of results is 200, Box uses the default limit of 100. ``` client.webhooks.getAll() .then(webhooks => { /* webhooks -> { next_marker: 'ZmlQZS0xLTE%3D', entries: [ { id: '1234', type: 'webhook', target: { id: '22222', type: 'folder' } }, { id: '5678', type: 'webhook', target: { id: '11111', type: 'file' } } ], limit: 2 } */ }); ``` ## Update a Webhook Update a file or folder's webhook by calling [`webhooks.update(webhookID, updates, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Webhooks.html#update) with the field you want to update as `updates.address` or `updates.trigger`. ``` client.webhooks.update('678901', {address: "https://example.com/webhooks/fileActions"}) .then(webhook => { /* webhook -> { id: '1234', type: 'webhook', target: { id: '22222', type: 'folder' }, created_by: { type: 'user', id: '33333', name: 'Example User', login: 'user@example.com' }, created_at: '2016-05-09T17:41:27-07:00', address: 'https://example.com/webhooks/fileActions', triggers: [ 'FILE.DOWNLOADED', 'FILE.UPLOADED' ] } */ }); ``` ## Delete a Webhook A file or folder's webhook can be removed by calling [`webhooks.delete(webhookID, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/Webhooks.html#delete). ``` client.webhooks.delete('1234') .then(() => { // deletion succeeded — no value returned }); ``` ## Validate a Webhook Message When you receive a webhook message from Box, you should validate it by calling [`BoxSDK.validateWebhookMessage(body, headers, primarySignatureKey, secondarySignatureKey, maxMessageAge)`](http://opensource.box.com/box-node-sdk/jsdoc/Webhooks.html#.validateMessage), also available as `webhooks.validateMessage(body, headers, primarySignatureKey, secondarySignatureKey, maxMessageAge)`. ``` const BoxSDK = require('box-node-sdk'); let body = '{"type":"webhook_event","webhook":{"id":"1234567890"},"trigger":"FILE.UPLOADED","source":{"id":"1234567890","type":"file","name":"Test.txt"}}', headers = { 'box-delivery-id': 'f96bb54b-ee16-4fc5-aa65-8c2d9e5b546f', 'box-delivery-timestamp': '2020-01-01T00:00:00-07:00', 'box-signature-algorithm': 'HmacSHA256', 'box-signature-primary': '6TfeAW3A1PASkgboxxA5yqHNKOwFyMWuEXny/FPD5hI=', 'box-signature-secondary': 'v+1CD1Jdo3muIcbpv5lxxgPglOqMfsNHPV899xWYydo=', 'box-signature-version': '1' }, primaryKey = 'SamplePrimaryKey', secondaryKey = 'SampleSecondaryKey'; let isValid = BoxSDK.validateWebhookMessage(body, headers, primaryKey, secondaryKey); if (isValid) { // message is valid, accept } else { // message is NOT valid, reject } ``` --- ### Webhooks **Type:** page | **Section:** Additional Resources Webhooks Webhooks enable you to attach event triggers to Box files and folders. Event triggers monitor events on Box objects and notify your… # Webhooks Webhooks enable you to attach event triggers to Box files and folders. Event triggers monitor events on Box objects and notify your application when they occur. A webhook notifies your application by sending HTTP requests to a URL of your choosing. - [Get a Webhook](#get-a-webhook) - [Get All Webhooks](#get-all-webhooks) - [Create a Webhook](#create-a-webhook) - [Delete a Webhook](#delete-a-webhook) - [Update a Webhook](#update-a-webhook) - [Verify a Webhook Message](#verify-a-webhook-message) ## Get a Webhook A webhook infocan be retrieved by calling the [`getInfo(String... fields)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxWebHook.html#getInfo-java.lang.String...-) method. ``` BoxWebHook webhook = new BoxWebHook(api, id); BoxWebHook.Info info = webhook.getInfo(); ``` ## Get All Webhooks Calling the static [`all(BoxAPIConnection api, String... fields)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxWebHook.html#all-com.box.sdk.BoxAPIConnection-java.lang.String...-) will return an iterable that will page through all defined webhooks for the requesting application and user. ``` Iterable<BoxWebHook.Info> webhooks = BoxWebHook.all(api); for (BoxWebHook.Info webhookInfo: webhooks) { // Do something with the webhook. } ``` ## Create a Webhook The static [`create(BoxResource targetItem, URL callbackURL, BoxWebHook.Trigger... triggerEvents)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxWebHook.html#create-com.box.sdk.BoxResource-java.net.URL-com.box.sdk.BoxWebHook.Trigger...-) method will let you create a new webhook for a specified target object. ``` // Listen for preview events for a file BoxFile file = new BoxFile(api, id); BoxWebHook.Info webhookInfo = BoxWebHook.create(file, url, BoxWebHook.Trigger.FILE.PREVIEWED); ``` ``` // Listen for file upload events in the specified folder BoxFolder folder = new BoxFolder(api, id); BoxWebHook.Info webhookInfo = BoxWebHook.create(folder, url, BoxWebHook.Trigger.FILE_UPLOADED); ``` ## Delete a Webhook A webhook can be deleted by calling the [`delete()`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxWebHook.html#delete--) method. ``` BoxWebHook webhook = new BoxWebHook(api, id); webhook.delete(); ``` ## Update a Webhook A webhook can be updated by calling the [`update(BoxWebHook.Info fieldsToUpdate)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxWebHook.html#updateInfo-com.box.sdk.BoxWebHook.Info-) method. ``` BoxWebHook webhook = new BoxWebHook(api, id); BoxWebHook.Info info = webhook.new Info(); info.setAddress(url); webhook.update(info); ``` ## Verify a Webhook Message When you receive a webhook message from Box, you should validate that it actually came from Box by calling [`BoxWebHookSignatureVerifier#verify(String sigVersion, String sigAlgorithm, String primarySignature, String secondarySignature, String payload, String deliveryTimestamp)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxWebHookSignatureVerifier.html#verify-java.lang.String-java.lang.String-java.lang.String-java.lang.String-java.lang.String-java.lang.String-) **Note:** It is recommended to ensure that your application and verifier use both a primary and secondary key to ensure that these keys can be safely rotated. ``` // Webhook message contents are shown for demonstration purposes // Normally these would come from your HTTP handler // Webhook message HTTP body String messagePayload = "{" + "\"type\":\"webhook_event"," + "\"webhook\":{" + "\"id\":\"1234567890\"" + "}," + "\"trigger\":\"FILE.UPLOADED\"," + "\"source\":{" + "\"id\":\"1234567890\"," + "\"type\":\"file\"," + "\"name\":\"Test.txt\"" + "}}"; // Webhook message HTTP headers Map<String, String> messageHeaders = new HashMap<String, String>(); headers.put("BOX-DELIVERY-ID", "f96bb54b-ee16-4fc5-aa65-8c2d9e5b546f"); headers.put("BOX-DELIVERY-TIMESTAMP", "2020-01-01T00:00:00-07:00"); headers.put("BOX-SIGNATURE-ALGORITHM", "HmacSHA256"); headers.put("BOX-SIGNATURE-PRIMARY", "6TfeAW3A1PASkgboxxA5yqHNKOwFyMWuEXny/FPD5hI="); headers.put("BOX-SIGNATURE-SECONDARY", "v+1CD1Jdo3muIcbpv5lxxgPglOqMfsNHPV899xWYydo="); headers.put("BOX-SIGNATURE-VERSION", "1"); // Your application's webhook keys, obtained from the Box Developer Console String primaryKey = "4py2I9eSFb0ezXH5iPeQRcFK1LRLCdip"; String secondaryKey = "Aq5EEEjAu4ssbz8n9UMu7EerI0LKj2TL"; BoxWebHookSignatureVerifier verifier = new BoxWebHookSignatureVerifier(primaryKey, secondaryKey); boolean isValidMessage = verifier.verify( headers.get("BOX-SIGNATURE-VERSION"), headers.get("BOX-SIGNATURE-ALGORITHM"), headers.get("BOX-SIGNATURE-PRIMARY"), headers.get("BOX-SIGNATURE-SECONDARY"), messagePayload, headers.get("BOX-DELIVERY-TIMESTAMP") ); if (isValidMessage) { // Message is valid, handle it } else { // Message is invalid, reject it } ``` --- ### Webhooks **Type:** page | **Section:** Additional Resources Webhooks Webhooks enable you to attach event triggers to Box files and folders. Event triggers monitor events on Box objects and notify your… # Webhooks Webhooks enable you to attach event triggers to Box files and folders. Event triggers monitor events on Box objects and notify your application when they occur. A webhook notifies your application by sending HTTP requests to a URL of your choosing. - [Get Information about Webhook](#get-information-about-webhook) - [List all Webhooks](#list-all-webhooks) - [Create Webhook](#create-webhook) - [Delete Webhook](#delete-webhook) - [Update Webhook](#update-webhook) - [Validate Webhook Message](#validate-webhook-message) ## Get Information about Webhook To get a webhook object, first call [`client.webhook(webhook_id)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.client.html#boxsdk.client.client.Client.webhook) to construct the appropriate [`Webhook`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.webhook.Webhook) object, and then calling [`webhook.get(*, fields=None, headers=None, **kwargs)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.base_object.BaseObject.get) will return the [`Webhook`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.webhook.Webhook) object populated with data from the API. ``` webhook = client.webhook(webhook_id='12345').get() print(f'Webhooks ID is {webhook.id} and the address is {webhook.address}') ``` ## List all Webhooks To retrieve all webhooks for an enterprise, call [`client.get_webhooks(limit=None, marker=None, fields=None)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.client.html#boxsdk.client.client.Client.get_webhooks). This method returns a `BoxObjectCollection` that allows you to iterate over the [`Webhook`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.webhook.Webhook) objects in the collection. ``` webhooks = client.get_webhooks() for webhook in webhooks: print(f'The webhook ID is {webhook.id} and the address is {webhook.address}') ``` ## Create Webhook To create a webhook object, call [`client.create_webhook(target_url, name=None, description=None)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.client.html#boxsdk.client.client.Client.create_webhook) will let you create a new webhook object with the specified target url, name, and description. This method will return an updated [`Webhook`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.webhook.Webhook) object populated with data from the API, leaving the original object unmodified. ``` file = client.file(file_id='12345') webhook = client.create_webhook(file, ['FILE.PREVIEWED'], 'https://example.com') print(f'Webhook ID is {webhook.id} and the address is {webhook.address}') ``` ``` folder = client.folder(folder_id='12345') webhook = client.create_webhook(folder, ['FILE.UPLOADED', 'FILE.PREVIEWED'], 'https://example.com') print(f'Webhook ID is {webhook.id} and the address is {webhook.address}') ``` ## Delete Webhook To delete a webhook, call [`webhook.delete()`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.base_object.BaseObject.delete). This method returns `True` to indicate that the deletion was successful. ``` client.webhook(webhook_id='12345').delete() print('The webhook was successfully deleted!') ``` ## Update Webhook To update a webhook object, first call [`client.webhook(webhook_id)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.client.html#boxsdk.client.client.Client.webhook) to construct the appropriate [`Webhook`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.webhook.Webhook) object, and then calling [`webhook.update_info(data=update_object)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.base_object.BaseObject.update_info) with a `dict` of properties to update on the webhook. This method returns a new updated [`Webhook`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.webhook.Webhook) object, leaving the original object unmodified. ``` update_object = { 'triggers': ['FILE.COPIED'], 'address': 'https://newexample.com', } webhook = client.webhook(webhook_id='12345').update_info(data=update_object) print(f'Updated the webhook info for triggers: {webhook.triggers} and address: {webhook.address}') ``` ## Validate Webhook Message When you receive a webhook message from Box, you should validate it by calling [`Webhook.validate_message(body, headers, primary_key, secondary_key)`][validate_webhook]. This will protect your application against attacks. Verification ensures that the notifications were actually sent by Box and not by a malicious party and that the contents of the notification haven't been changed. ``` body = b'{"webhook":{"id":"1234567890"},"trigger":"FILE.UPLOADED","source":{"id":"1234567890","type":"file","name":"Test.txt"}}' headers = { 'box-delivery-id': 'f96bb54b-ee16-4fc5-aa65-8c2d9e5b546f', 'box-delivery-timestamp': '2020-01-01T00:00:00-07:00', 'box-signature-algorithm': 'HmacSHA256', 'box-signature-primary': '4KvFa5/unRL8aaqOlnbInTwkOmieZkn1ZVzsAJuRipE=', 'box-signature-secondary': 'yxxwBNk7tFyQSy95/VNKAf1o+j8WMPJuo/KcFc7OS0Q=', 'box-signature-version': '1', } is_validated = Webhook.validate_message(body, headers, primary_key, secondary_key) print(f'The webhook message is validated to: {is_validated}') ``` --- ### Webhooks **Type:** page | **Section:** Additional Resources Webhooks A webhook object enables you to attach events triggers to Box files and folders. These event triggers monitor events on Box objects… # Webhooks A webhook object enables you to attach events triggers to Box files and folders. These event triggers monitor events on Box objects and notify your application, via HTTP requests to a URL of your choosing, when they occur. - [Create a Webhook](#create-a-webhook) - [Get All Webhooks](#get-all-webhooks) - [Get a Webhook"s Information](#get-a-webhooks-information) - [Validate a Webhook Message](#validate-a-webhook-message) - [Delete a Webhook](#delete-a-webhook) - [Update a Webhook](#update-a-webhook) ## Create a Webhook To attach a webhook to an item, call the `WebhooksManager.CreateWebhookAsync(BoxWebhookRequest webhookRequest)` method with the type and ID of the item, a URL to send notifications to, and a list of triggers. ``` var webhookParams = new BoxWebhookRequest() { Target = new BoxRequestEntity() { Type = BoxType.file, Id = "22222" }, Triggers = new List<string>() { "FILE.PREVIEWED" }, Address = "https://example.com/webhook" }; BoxWebhook webhook = await client.WebhooksManager.CreateWebhookAsync(webhookParams); ``` Similarly, webhooks can be created for folders. ``` var webhookParams = new BoxWebhookRequest() { Target = new BoxRequestEntity() { Type = BoxType.folder, Id = "22222" }, Triggers = new List<string>() { "FILE.UPLOADED", "FILE.DOWNLOADED" }, Address = "https://example.com/webhook }; BoxWebhook webhook = await client.WebhooksManager.CreateWebhookAsync(webhookParams); ``` ## Get All Webhooks Get a list of all webhooks for the requesting application and user by calling the `WebhooksManager.GetWebhooksAsync (int limit = 100, string nextMarker = null, bool autoPaginate=false)` method. The maximum limit per page of results is 200, Box uses the default limit of 100. ``` BoxCollectionMarkerBased<BoxWebhook> webhooks = await client.WebhooksManager.GetWebhooksAsync(); ``` ## Get a Webhook"s Information Retrieve information about a specific webhook by calling `WebhooksManager.GetWebhookAsync(string id)` to retrieve a webhook by ID. ``` BoxWebhook webhook = await client.WebhooksManager.GetWebhookAsync("12345"); ``` ## Validate a Webhook Message When you receive a webhook message from Box, you should validate it by calling the static `WebhooksManager.VerifyWebhook(string deliveryTimestamp, string signaturePrimary, string signatureSecondary, string payload, string primaryWebhookKey, string secondaryWebhookKey)` method with the components of the webhook message. ``` using Box.V2.Managers; var body = "{\"type\":\"webhook_event\",\"webhook\":{\"id\":\"1234567890\"},\"trigger\":\"FILE.UPLOADED\",\"source\":{\"id\":\"1234567890\",\"type\":\"file\",\"name\":\"Test.txt\"}}"; var headers = new Dictionary<string, string>() { { "box-delivery-id", "f96bb54b-ee16-4fc5-aa65-8c2d9e5b546f" }, { "box-delivery-timestamp", "2020-01-01T00:00:00-07:00" }, { "box-signature-algorithm", "HmacSHA256" } , { "box-signature-primary", "6TfeAW3A1PASkgboxxA5yqHNKOwFyMWuEXny/FPD5hI=" }, { "box-signature-secondary", "v+1CD1Jdo3muIcbpv5lxxgPglOqMfsNHPV899xWYydo=" }, { "box-signature-version", "1" } }; var primaryKey = "Fd28OJrZ8oNxkgmS7TbjXNgrG8v"; var secondaryKey = "KWkROAOiof4zhYUHbAmiVn63cMj" bool isValid = BoxWebhooksManager.VerifyWebhook( deliveryTimestamp: headers["box-delivery-timestamp"], signaturePrimary: headers["box-signature-primary"], signatureSecondary: headers["box-signature-secondary"], payload: body, primaryWebhookKey: primaryKey, secondaryWebhookKey: secondaryKey ); ``` ## Delete a Webhook A file or folder's webhook can be removed by calling `WebhooksManager.DeleteWebhookAsync(string id)` with the ID of the webhook object. ``` await client.WebhooksManager.DeleteWebhookAsync("11111"); ``` ## Update a Webhook Update a file or folder's webhook by calling `WebhooksManager.UpdateWebhookAsync(BoxWebhookRequest webhookRequest)` with the fields of the webhook object to update. ``` var updates = new BoxWebhookRequest() { Id = "12345", Address = "https://example.com/webhooks/fileActions }; BoxWebhook updatedWebhook = await client.WebhooksManager.UpdateWebhookAsync(updates); ``` --- ### Webhooks **Type:** page | **Section:** Additional Resources Webhooks Webhooks enable you to attach event triggers to Box files and folders. Event triggers monitor events on Box objects and notify your… # Webhooks Webhooks enable you to attach event triggers to Box files and folders. Event triggers monitor events on Box objects and notify your application when they occur. A webhook notifies your application by sending HTTP requests to a URL of your choosing. A webhook object contains information about a webhook like the triggers, the URL, etc. - [Get Webhooks](#get-webhooks) - [Get Webhook Info](#get-webhook-info) - [Create Webhook](#create-webhook) - [Update Webhook](#update-webhook) - [Delete Webhook](#delete-webhook) ## Get Webhook Info To retrieve information about a webhook, call [`client.webhooks.get(webhookId: String, fields: [String]?, completion: @escaping Callback<Webhook>)`](https://opensource.box.com/box-ios-sdk/Classes/WebhooksModule.html#/s:6BoxSDK14WebhooksModuleC3get9webhookId6fields10completionySS_SaySSGSgys6ResultOyAA7WebhookCAA0A8SDKErrorCGctF) with the ID of the webhook. You can control which fields are returned in the resulting `Webhook` object by passing the `fields` parameter. ``` client.folders.get(webhookId: "22222", fields: ["id", "created_at"]) { (result: Result<Webhook, BoxSDKError>) in guard case let .success(webhook) = result else { print("Error getting webhook information") return } print("Webhook \(webhook.id) was created at \(webhook.createdAt)") } ``` ## List Webhooks To retrieve information about webhooks in an enterprise, call [`client.webhook.list(webhookId: String, marker: String?, limit: Int?, fields: [String]?)`](https://opensource.box.com/box-ios-sdk/Classes/WebhooksModule.html#/s:6BoxSDK14WebhooksModuleC4list6marker5limit6fields10completionySSSg_SiSgSaySSGSgys6ResultOyAA14PagingIteratorCyAA7WebhookCGAA0A8SDKErrorCGctF). This method will return an iterator object, which is used to get the webhooks. ``` let iterator = client.webhooks.list() iterator.next { results in switch results { case let .success(page): for webhook in page.entries { print("Webhook \(webhook.id) was created at \(webhook.createdAt)") } case let .failure(error): print(error) } } ``` ## Create Webhook To create a new webhook, call [`client.webhooks.create(targetType: String, targetId: String, triggers: [Webhook.EventTriggers], address: String, fields: [String]?, completion: @escaping Callback<Webhook>`](https://opensource.box.com/box-ios-sdk/Classes/WebhooksModule.html#/s:6BoxSDK14WebhooksModuleC6create10targetType0F2Id8triggers7address6fields10completionySS_SSSayAA7WebhookC13EventTriggersOGSSSaySSGSgys6ResultOyAlA0A8SDKErrorCGctF) ``` client.webhooks.create(targetType: "file", targetId: "1234", triggers: [.fileDownloaded], address: "www.testurl.com") { (result: Result<Webhook, BoxSDKError>) in guard case let .success(webhook) = result else { print("Error creating webhook") return } print("Created webhook \"\(webhook.id)\"") } ``` ## Update Webhook To update a webhook, call [`client.webhooks.update(webhookId: String, targetType: String?, targetId: String?, triggers: [Webhook.EventTriggers]?, address: String?, fields: [String]?, completion: @escaping Callback<Webhook>`](https://opensource.box.com/box-ios-sdk/Classes/WebhooksModule.html#/s:6BoxSDK14WebhooksModuleC6update9webhookId10targetType0hG08triggers7address6fields10completionySS_SSSgALSayAA7WebhookC13EventTriggersOGSgALSaySSGSgys6ResultOyAnA0A8SDKErrorCGctF) ``` client.webhooks.update(webhookId: "1234", targetType: "file", targetId: "1234", address: "www.testurl.com") { (result: Result<Webhook, BoxSDKError>) in guard case let .success(webhook) = result else { print("Error updating webhook") return } print("Updated webhook address to \"\(webhook.address)\"") } ``` ## Delete Webhook To delete a webhook, call [`client.webhooks.delete(webhookId: String, completion: @escaping Callback<Void>`](https://opensource.box.com/box-ios-sdk/Classes/WebhooksModule.html#/s:6BoxSDK14WebhooksModuleC6delete9webhookId10completionySS_ys6ResultOyytAA0A8SDKErrorCGctF) ``` client.webhooks.delete(webhookId: "22222") { result: Result<Void, BoxSDKError>} in guard case .success = result else { print("Error deleting webhook") return } print("Webhook successfully deleted") } ``` --- ### Webhooks **Type:** page | **Section:** Additional Resources Webhooks Webhooks enable you to attach event triggers to Box files and folders. Event triggers monitor events on Box objects and notify your… # Webhooks Webhooks enable you to attach event triggers to Box files and folders. Event triggers monitor events on Box objects and notify your application when they occur. A webhook notifies your application by sending HTTP requests to a URL of your choosing. A webhook object contains information about a webhook like the triggers, the URL, etc. - [Get Webhooks](#get-webhooks) - [Get Webhook Info](#get-webhook-info) - [Create Webhook](#create-webhook) - [Update Webhook](#update-webhook) - [Delete Webhook](#delete-webhook) ## Get Webhook Info To retrieve information about a webhook, call [`client.webhooks.get(webhookId: String, fields: [String]?, completion: @escaping Callback<Webhook>)`](https://opensource.box.com/box-ios-sdk/Classes/WebhooksModule.html#/s:6BoxSDK14WebhooksModuleC3get9webhookId6fields10completionySS_SaySSGSgys6ResultOyAA7WebhookCAA0A8SDKErrorCGctF) with the ID of the webhook. You can control which fields are returned in the resulting `Webhook` object by passing the `fields` parameter. ``` client.folders.get(webhookId: "22222", fields: ["id", "created_at"]) { (result: Result<Webhook, BoxSDKError>) in guard case let .success(webhook) = result else { print("Error getting webhook information") return } print("Webhook \(webhook.id) was created at \(webhook.createdAt)") } ``` ## List Webhooks To retrieve information about webhooks in an enterprise, call [`client.webhook.list(webhookId: String, marker: String?, limit: Int?, fields: [String]?)`](https://opensource.box.com/box-ios-sdk/Classes/WebhooksModule.html#/s:6BoxSDK14WebhooksModuleC4list6marker5limit6fields10completionySSSg_SiSgSaySSGSgys6ResultOyAA14PagingIteratorCyAA7WebhookCGAA0A8SDKErrorCGctF). This method will return an iterator object, which is used to get the webhooks. ``` let iterator = client.webhooks.list() iterator.next { results in switch results { case let .success(page): for webhook in page.entries { print("Webhook \(webhook.id) was created at \(webhook.createdAt)") } case let .failure(error): print(error) } } ``` ## Create Webhook To create a new webhook, call [`client.webhooks.create(targetType: String, targetId: String, triggers: [Webhook.EventTriggers], address: String, fields: [String]?, completion: @escaping Callback<Webhook>`](https://opensource.box.com/box-ios-sdk/Classes/WebhooksModule.html#/s:6BoxSDK14WebhooksModuleC6create10targetType0F2Id8triggers7address6fields10completionySS_SSSayAA7WebhookC13EventTriggersOGSSSaySSGSgys6ResultOyAlA0A8SDKErrorCGctF) ``` client.webhooks.create(targetType: "file", targetId: "1234", triggers: [.fileDownloaded], address: "www.testurl.com") { (result: Result<Webhook, BoxSDKError>) in guard case let .success(webhook) = result else { print("Error creating webhook") return } print("Created webhook \"\(webhook.id)\"") } ``` ## Update Webhook To update a webhook, call [`client.webhooks.update(webhookId: String, targetType: String?, targetId: String?, triggers: [Webhook.EventTriggers]?, address: String?, fields: [String]?, completion: @escaping Callback<Webhook>`](https://opensource.box.com/box-ios-sdk/Classes/WebhooksModule.html#/s:6BoxSDK14WebhooksModuleC6update9webhookId10targetType0hG08triggers7address6fields10completionySS_SSSgALSayAA7WebhookC13EventTriggersOGSgALSaySSGSgys6ResultOyAnA0A8SDKErrorCGctF) ``` client.webhooks.update(webhookId: "1234", targetType: "file", targetId: "1234", address: "www.testurl.com") { (result: Result<Webhook, BoxSDKError>) in guard case let .success(webhook) = result else { print("Error updating webhook") return } print("Updated webhook address to \"\(webhook.address)\"") } ``` ## Delete Webhook To delete a webhook, call [`client.webhooks.delete(webhookId: String, completion: @escaping Callback<Void>`](https://opensource.box.com/box-ios-sdk/Classes/WebhooksModule.html#/s:6BoxSDK14WebhooksModuleC6delete9webhookId10completionySS_ys6ResultOyytAA0A8SDKErrorCGctF) ``` client.webhooks.delete(webhookId: "22222") { result: Result<Void, BoxSDKError>} in guard case .success = result else { print("Error deleting webhook") return } print("Webhook successfully deleted") } ``` --- ### WebhooksManager **Type:** page | **Section:** Additional Resources WebhooksManager List all webhooks Create webhook Get webhook Update webhook Remove webhook Validate a webhook message List all webhooks… # WebhooksManager - [List all webhooks](#list-all-webhooks) - [Create webhook](#create-webhook) - [Get webhook](#get-webhook) - [Update webhook](#update-webhook) - [Remove webhook](#remove-webhook) - [Validate a webhook message](#validate-a-webhook-message) ## List all webhooks Returns all defined webhooks for the requesting application. This API only returns webhooks that are applied to files or folders that are owned by the authenticated user. This means that an admin can not see webhooks created by a service account unless the admin has access to those folders, and vice versa. This operation is performed by calling function `getWebhooks`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-webhooks/). ``` await client.webhooks.getWebhooks(); ``` ### Arguments queryParams `GetWebhooksQueryParams` - Query parameters of getWebhooks method headersInput `GetWebhooksHeadersInput` - Headers of getWebhooks method cancellationToken `undefined | CancellationToken` - Token used for request cancellation. ### Returns This function returns a value of type `Webhooks`. Returns a list of webhooks. ## Create webhook Creates a webhook. This operation is performed by calling function `createWebhook`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-webhooks/). ``` await client.webhooks.createWebhook({ target: { id: folder.id, type: 'folder' as CreateWebhookRequestBodyTargetTypeField, } satisfies CreateWebhookRequestBodyTargetField, address: 'https://example.com/new-webhook', triggers: ['FILE.UPLOADED' as CreateWebhookRequestBodyTriggersField], } satisfies CreateWebhookRequestBody); ``` ### Arguments requestBody `CreateWebhookRequestBody` - Request body of createWebhook method optionalsInput `CreateWebhookOptionalsInput` ### Returns This function returns a value of type `Webhook`. Returns the new webhook object. ## Get webhook Retrieves a specific webhook. This operation is performed by calling function `getWebhookById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-webhooks-id/). ``` await client.webhooks.getWebhookById(webhook.id!); ``` ### Arguments webhookId `string` - The ID of the webhook. Example: "3321123" optionalsInput `GetWebhookByIdOptionalsInput` ### Returns This function returns a value of type `Webhook`. Returns a webhook object. ## Update webhook Updates a webhook. This operation is performed by calling function `updateWebhookById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-webhooks-id/). ``` await client.webhooks.updateWebhookById(webhook.id!, { requestBody: { address: 'https://example.com/updated-webhook', } satisfies UpdateWebhookByIdRequestBody, } satisfies UpdateWebhookByIdOptionalsInput); ``` ### Arguments webhookId `string` - The ID of the webhook. Example: "3321123" optionalsInput `UpdateWebhookByIdOptionalsInput` ### Returns This function returns a value of type `Webhook`. Returns the new webhook object. ## Remove webhook Deletes a webhook. This operation is performed by calling function `deleteWebhookById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-webhooks-id/). ``` await client.webhooks.deleteWebhookById(webhook.id!); ``` ### Arguments webhookId `string` - The ID of the webhook. Example: "3321123" optionalsInput `DeleteWebhookByIdOptionalsInput` ### Returns This function returns a value of type `undefined`. An empty response will be returned when the webhook was successfully deleted. ## Validate a webhook message Validate a webhook message by verifying the signature and the delivery timestamp This operation is performed by calling function `validateMessage`. ``` await WebhooksManager.validateMessage( body, headersWithCorrectDatetime, primaryKey, { secondaryKey: secondaryKey } satisfies ValidateMessageOptionalsInput, ); ``` ### Arguments body `string` - The request body of the webhook message headers `{ readonly [key: string]: string; }` - The headers of the webhook message primaryKey `string` - The primary signature to verify the message with optionalsInput `ValidateMessageOptionalsInput` ### Returns This function returns a value of type `boolean`. --- ### WebhooksManager **Type:** page | **Section:** Additional Resources WebhooksManager List all webhooks Create webhook Get webhook Update webhook Remove webhook Validate a webhook message List all webhooks… # WebhooksManager - [List all webhooks](#list-all-webhooks) - [Create webhook](#create-webhook) - [Get webhook](#get-webhook) - [Update webhook](#update-webhook) - [Remove webhook](#remove-webhook) - [Validate a webhook message](#validate-a-webhook-message) ## List all webhooks Returns all defined webhooks for the requesting application. This API only returns webhooks that are applied to files or folders that are owned by the authenticated user. This means that an admin can not see webhooks created by a service account unless the admin has access to those folders, and vice versa. This operation is performed by calling function `get_webhooks`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-webhooks/). ``` client.webhooks.get_webhooks() ``` ### Arguments marker `Optional[str]` - Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`. limit `Optional[int]` - The maximum number of items to return per page. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `Webhooks`. Returns a list of webhooks. ## Create webhook Creates a webhook. This operation is performed by calling function `create_webhook`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-webhooks/). ``` client.webhooks.create_webhook( CreateWebhookTarget(id=folder.id, type=CreateWebhookTargetTypeField.FOLDER), "https://example.com/new-webhook", [CreateWebhookTriggers.FILE_UPLOADED], ) ``` ### Arguments target `CreateWebhookTarget` - The item that will trigger the webhook. address `str` - The URL that is notified by this webhook. triggers `List[CreateWebhookTriggers]` - An array of event names that this webhook is to be triggered for. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `Webhook`. Returns the new webhook object. ## Get webhook Retrieves a specific webhook. This operation is performed by calling function `get_webhook_by_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-webhooks-id/). ``` client.webhooks.get_webhook_by_id(webhook.id) ``` ### Arguments webhook_id `str` - The ID of the webhook. Example: "3321123" extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `Webhook`. Returns a webhook object. ## Update webhook Updates a webhook. This operation is performed by calling function `update_webhook_by_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-webhooks-id/). ``` client.webhooks.update_webhook_by_id( webhook.id, address="https://example.com/updated-webhook" ) ``` ### Arguments webhook_id `str` - The ID of the webhook. Example: "3321123" target `Optional[UpdateWebhookByIdTarget]` - The item that will trigger the webhook. address `Optional[str]` - The URL that is notified by this webhook. triggers `Optional[List[UpdateWebhookByIdTriggers]]` - An array of event names that this webhook is to be triggered for. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `Webhook`. Returns the new webhook object. ## Remove webhook Deletes a webhook. This operation is performed by calling function `delete_webhook_by_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-webhooks-id/). ``` client.webhooks.delete_webhook_by_id(webhook.id) ``` ### Arguments webhook_id `str` - The ID of the webhook. Example: "3321123" extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `None`. An empty response will be returned when the webhook was successfully deleted. ## Validate a webhook message Validate a webhook message by verifying the signature and the delivery timestamp This operation is performed by calling function `validate_message`. ``` WebhooksManager.validate_message( body, headers_with_correct_datetime, primary_key, secondary_key=secondary_key ) ``` ### Arguments body `str` - The request body of the webhook message headers `Dict[str, str]` - The headers of the webhook message primary_key `str` - The primary signature to verify the message with secondary_key `Optional[str]` - The secondary signature to verify the message with max_age `Optional[int]` - The maximum age of the message in seconds, defaults to 10 minutes ### Returns This function returns a value of type `bool`. --- ### WebLinksManager **Type:** page | **Section:** Additional Resources WebLinksManager Create web link Get web link Update web link Remove web link Create web link Creates a web link object within a folder. This… # WebLinksManager - [Create web link](#create-web-link) - [Get web link](#get-web-link) - [Update web link](#update-web-link) - [Remove web link](#remove-web-link) ## Create web link Creates a web link object within a folder. This operation is performed by calling function `createWebLink`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-web-links/). ``` await client.webLinks.createWebLink({ url: 'https://www.box.com', parent: { id: parent.id } satisfies CreateWebLinkRequestBodyParentField, name: getUuid(), description: 'Weblink description', } satisfies CreateWebLinkRequestBody); ``` ### Arguments requestBody `CreateWebLinkRequestBody` - Request body of createWebLink method optionalsInput `CreateWebLinkOptionalsInput` ### Returns This function returns a value of type `WebLink`. Returns the newly created web link object. ## Get web link Retrieve information about a web link. This operation is performed by calling function `getWebLinkById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-web-links-id/). ``` await client.webLinks.getWebLinkById(weblink.id); ``` ### Arguments webLinkId `string` - The ID of the web link. Example: "12345" optionalsInput `GetWebLinkByIdOptionalsInput` ### Returns This function returns a value of type `WebLink`. Returns the web link object. ## Update web link Updates a web link object. This operation is performed by calling function `updateWebLinkById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-web-links-id/). ``` await client.webLinks.updateWebLinkById(weblink.id, { requestBody: { name: updatedName, sharedLink: { access: 'open' as UpdateWebLinkByIdRequestBodySharedLinkAccessField, password: password, } satisfies UpdateWebLinkByIdRequestBodySharedLinkField, } satisfies UpdateWebLinkByIdRequestBody, } satisfies UpdateWebLinkByIdOptionalsInput); ``` ### Arguments webLinkId `string` - The ID of the web link. Example: "12345" optionalsInput `UpdateWebLinkByIdOptionalsInput` ### Returns This function returns a value of type `WebLink`. Returns the updated web link object. ## Remove web link Deletes a web link. This operation is performed by calling function `deleteWebLinkById`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-web-links-id/). ``` await client.webLinks.deleteWebLinkById(webLinkId); ``` ### Arguments webLinkId `string` - The ID of the web link. Example: "12345" optionalsInput `DeleteWebLinkByIdOptionalsInput` ### Returns This function returns a value of type `undefined`. An empty response will be returned when the web link was successfully deleted. --- ### WebLinksManager **Type:** page | **Section:** Additional Resources WebLinksManager Create web link Get web link Update web link Remove web link Create web link Creates a web link object within a folder. This… # WebLinksManager - [Create web link](#create-web-link) - [Get web link](#get-web-link) - [Update web link](#update-web-link) - [Remove web link](#remove-web-link) ## Create web link Creates a web link object within a folder. This operation is performed by calling function `create_web_link`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-web-links/). ``` client.web_links.create_web_link( "https://www.box.com", CreateWebLinkParent(id=parent.id), name=get_uuid(), description="Weblink description", ) ``` ### Arguments url `str` - The URL that this web link links to. Must start with `"http://"` or `"https://"`. parent `CreateWebLinkParent` - The parent folder to create the web link within. name `Optional[str]` - Name of the web link. Defaults to the URL if not set. description `Optional[str]` - Description of the web link. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `WebLink`. Returns the newly created web link object. ## Get web link Retrieve information about a web link. This operation is performed by calling function `get_web_link_by_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-web-links-id/). ``` client.web_links.get_web_link_by_id(weblink.id) ``` ### Arguments web_link_id `str` - The ID of the web link. Example: "12345" boxapi `Optional[str]` - The URL, and optional password, for the shared link of this item. This header can be used to access items that have not been explicitly shared with a user. Use the format `shared_link=[link]` or if a password is required then use `shared_link=[link]&shared_link_password=[password]`. This header can be used on the file or folder shared, as well as on any files or folders nested within the item. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `WebLink`. Returns the web link object. ## Update web link Updates a web link object. This operation is performed by calling function `update_web_link_by_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/put-web-links-id/). ``` client.web_links.update_web_link_by_id( weblink.id, name=updated_name, shared_link=UpdateWebLinkByIdSharedLink( access=UpdateWebLinkByIdSharedLinkAccessField.OPEN, password=password ), ) ``` ### Arguments web_link_id `str` - The ID of the web link. Example: "12345" url `Optional[str]` - The new URL that the web link links to. Must start with `"http://"` or `"https://"`. parent `Optional[UpdateWebLinkByIdParent]` name `Optional[str]` - A new name for the web link. Defaults to the URL if not set. description `Optional[str]` - A new description of the web link. shared_link `Optional[UpdateWebLinkByIdSharedLink]` - The settings for the shared link to update. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `WebLink`. Returns the updated web link object. ## Remove web link Deletes a web link. This operation is performed by calling function `delete_web_link_by_id`. See the endpoint docs at [API Reference](https://developer.box.com/reference/delete-web-links-id/). ``` client.web_links.delete_web_link_by_id(web_link_id) ``` ### Arguments web_link_id `str` - The ID of the web link. Example: "12345" extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `None`. An empty response will be returned when the web link was successfully deleted. --- ### WorkflowsManager **Type:** page | **Section:** Additional Resources WorkflowsManager List workflows Starts workflow based on request body List workflows Returns list of workflows that act on a given folder ID… # WorkflowsManager - [List workflows](#list-workflows) - [Starts workflow based on request body](#starts-workflow-based-on-request-body) ## List workflows Returns list of workflows that act on a given `folder ID`, and have a flow with a trigger type of `WORKFLOW_MANUAL_START`. You application must be authorized to use the `Manage Box Relay` application scope within the developer console in to use this endpoint. This operation is performed by calling function `getWorkflows`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-workflows/). ``` await adminClient.workflows.getWorkflows({ folderId: workflowFolderId, } satisfies GetWorkflowsQueryParams); ``` ### Arguments queryParams `GetWorkflowsQueryParams` - Query parameters of getWorkflows method optionalsInput `GetWorkflowsOptionalsInput` ### Returns This function returns a value of type `Workflows`. Returns the workflow. ## Starts workflow based on request body Initiates a flow with a trigger type of `WORKFLOW_MANUAL_START`. You application must be authorized to use the `Manage Box Relay` application scope within the developer console. This operation is performed by calling function `startWorkflow`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-workflows-id-start/). ``` await adminClient.workflows.startWorkflow(workflowToRun.id!, { type: 'workflow_parameters' as StartWorkflowRequestBodyTypeField, flow: { type: 'flow', id: workflowToRun.flows![0].id!, } satisfies StartWorkflowRequestBodyFlowField, files: [ { type: 'file' as StartWorkflowRequestBodyFilesTypeField, id: workflowFileId, } satisfies StartWorkflowRequestBodyFilesField, ], folder: { type: 'folder' as StartWorkflowRequestBodyFolderTypeField, id: workflowFolderId, } satisfies StartWorkflowRequestBodyFolderField, } satisfies StartWorkflowRequestBody); ``` ### Arguments workflowId `string` - The ID of the workflow. Example: "12345" requestBody `StartWorkflowRequestBody` - Request body of startWorkflow method optionalsInput `StartWorkflowOptionalsInput` ### Returns This function returns a value of type `undefined`. Starts the workflow. --- ### WorkflowsManager **Type:** page | **Section:** Additional Resources WorkflowsManager List workflows Starts workflow based on request body List workflows Returns list of workflows that act on a given folder ID… # WorkflowsManager - [List workflows](#list-workflows) - [Starts workflow based on request body](#starts-workflow-based-on-request-body) ## List workflows Returns list of workflows that act on a given `folder ID`, and have a flow with a trigger type of `WORKFLOW_MANUAL_START`. You application must be authorized to use the `Manage Box Relay` application scope within the developer console in to use this endpoint. This operation is performed by calling function `get_workflows`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-workflows/). ``` admin_client.workflows.get_workflows(workflow_folder_id) ``` ### Arguments folder_id `str` - The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. trigger_type `Optional[str]` - Type of trigger to search for. limit `Optional[int]` - The maximum number of items to return per page. marker `Optional[str]` - Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `Workflows`. Returns the workflow. ## Starts workflow based on request body Initiates a flow with a trigger type of `WORKFLOW_MANUAL_START`. You application must be authorized to use the `Manage Box Relay` application scope within the developer console. This operation is performed by calling function `start_workflow`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-workflows-id-start/). ``` admin_client.workflows.start_workflow( workflow_to_run.id, StartWorkflowFlow(type="flow", id=workflow_to_run.flows[0].id), [StartWorkflowFiles(type=StartWorkflowFilesTypeField.FILE, id=workflow_file_id)], StartWorkflowFolder( type=StartWorkflowFolderTypeField.FOLDER, id=workflow_folder_id ), type=StartWorkflowType.WORKFLOW_PARAMETERS, ) ``` ### Arguments workflow_id `str` - The ID of the workflow. Example: "12345" type `Optional[StartWorkflowType]` - The type of the parameters object. flow `StartWorkflowFlow` - The flow that will be triggered. files `List[StartWorkflowFiles]` - The array of files for which the workflow should start. All files must be in the workflow's configured folder. folder `StartWorkflowFolder` - The folder object for which the workflow is configured. outcomes `Optional[List[Outcome]]` - A configurable outcome the workflow should complete. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `None`. Starts the workflow. --- ### Write the Box file contents to disk **Type:** page | **Section:** Additional Resources Files File objects represent individual files in Box. They can be used to download a file's contents, upload new versions, and perform other… # Files File objects represent individual files in Box. They can be used to download a file's contents, upload new versions, and perform other common file operations (move, copy, delete, etc.). [Files](#files) - [Get a File's Information](#get-a-files-information) - [Update a File's Information](#update-a-files-information) - [Download a File](#download-a-file) - [Get Download URL](#get-download-url) - [Upload a File](#upload-a-file) [Chunked Upload](#chunked-upload) [Automatic Uploader](#automatic-uploader) - [Upload new file](#upload-new-file) - [Upload new file version](#upload-new-file-version) - [Preflight check before upload](#preflight-check-before-upload) - [Resume Upload](#resume-upload) - [Abort Chunked Upload](#abort-chunked-upload) [Manual Process](#manual-process) - [Create Upload Session for File Version](#create-upload-session-for-file-version) - [Create Upload Session for File](#create-upload-session-for-file) - [Upload Part](#upload-part) - [Commit Upload Session](#commit-upload-session) - [Abort Upload Session](#abort-upload-session) - [List Upload Parts](#list-upload-parts) [Move a File](#move-a-file) [Copy a File](#copy-a-file) [Rename a File](#rename-a-file) [Delete a File](#delete-a-file) [Get Previous Versions of a File](#get-previous-versions-of-a-file) [Upload a New Version of a File](#upload-a-new-version-of-a-file) [Promote a Previous Version of a File](#promote-a-previous-version-of-a-file) [Delete a Previous Version of a File](#delete-a-previous-version-of-a-file) [Lock a File](#lock-a-file) [Unlock a File](#unlock-a-file) [Create a Shared Link Download URL](#create-a-shared-link-download-url) [Find a File for a Shared Link](#find-a-file-for-a-shared-link) [Create or update a Shared Link](#create-or-update-a-shared-link) [Get a Shared Link](#get-a-shared-link) [Remove a Shared Link](#remove-a-shared-link) [Get an Embed Link](#get-an-embed-link) [Get File Representations](#get-file-representations) [Get Thumbnail (Deprecated)](#get-thumbnail-deprecated) [Get Thumbnail](#get-thumbnail) [Set Metadata](#set-metadata) [Get Metadata](#get-metadata) [Remove Metadata](#remove-metadata) [Get All Metadata](#get-all-metadata) [Set a Classification](#set-a-classification) [Retrieve a Classification](#retrieve-a-classification) [Remove a Classification](#remove-a-classification) [Set retention policy expiration date](#set-retention-policy-expiration-date) ## Get a File's Information Calling [`file.get(*, fields=None, etag=None, **kwargs)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.base_object.BaseObject.get) on a [`File`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.file.File) retrieves information about the file from the API. This method returns a new [`File`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.file.File) object populated with the information retrieved. You can specify an `Iterable` of fields to retrieve from the API in the `fields` parameter. ``` file_id = '11111' file_info = client.file(file_id).get() print(f'File "{file_info.name}" has a size of {file_info.size} bytes') ``` ## Update a File's Information To update fields on the [`File`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.file.File) object, call [`file.update_info(data=data_to_update)`][update_info] with a `dict` of fields to update. This method returns the updated [`File`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.file.File) object, leaving the original it was called on unmodified. ``` file_id = '11111' updated_file = client.file(file_id).update_info(data={'description': 'My file'}) ``` ## Download a File A file can be downloaded in two ways: by returning the entire contents of the file as `bytes` or by providing an output stream to which the contents of the file will be written. For both methods, you can optionally download a specific version of the file by passing the desired [`FileVersion`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.file_version.FileVersion) in the `file_version` parameter. You may also wish to download only a certain chunk of the file by passing a tuple of byte offsets via the `byte_range` parameter — the lower and upper bounds you wish to download. To get the entire contents of the file as `bytes`, call [`file.content(file_version=None, byte_range=None)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.file.File.content). ``` file_id = '11111' file_content = client.file(file_id).content() ``` For users with premium accounts, previous versions of a file can be downloaded. ``` file_id = '11111' file_version = client.file_version('12345') version_content = client.file(file_id).content(file_version=file_version) ``` Additonally, only a part of the file can be downloaded by specifying a byte range. ``` file_id = '11111' beginning_of_file_content = client.file(file_id).content(byte_range=(0,99)) ``` To download the file contents to an output stream, call [`file.download_to(writeable_stream, file_version=None, byte_range=None)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.file.File.download_to) with the stream. ``` file_id = '11111' # Write the Box file contents to disk with open('file.pdf', 'wb') as output_file: client.file(file_id).download_to(output_file) ``` ## Get Download URL To get a download URL suitable for passing to a web browser or other application, which will allow someone to download the file, call [`file.get_download_url(file_version=None)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.file.File.get_download_url). The will return a `unicode` string containing the file's download URL. You can optionally pass a [`FileVersion`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.file_version.FileVersion) via the `file_version` parameter to get a download URL for a specific version of the file. ``` file_id = '11111' download_url = client.file(file_id).get_download_url() print(f'The file\'s download URL is: {download_url}') ``` ## Upload a File Files are uploaded to a folder in one of two ways: by providing a path to a file on disk, or via a readable stream containing the file contents. To upload a file from a path on disk, call the [`folder.upload(file_path, file_name=None, file_description=None,preflight_check=False, preflight_expected_size=0)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.folder.Folder.upload) method on the [`Folder`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.folder.Folder) you want to upload the file into. By default, the file uploaded to Box will have the same file name as the one on disk; you can override this by passing a different name in the `file_name` parameter. You can, optionally, also choose to set a file description upon upload by using the `file_description` parameter. This method returns a [`File`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.file.File) object representing the newly-uploaded file. ``` folder_id = '22222' new_file = client.folder(folder_id).upload('/home/me/document.pdf') print(f'File "{new_file.name}" uploaded to Box with file ID {new_file.id}') ``` To upload a file from a readable stream, call [`folder.upload_stream(file_stream, file_name, file_description=None, preflight_check=False, preflight_expected_size=0)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.folder.Folder.upload_stream) with the stream and a name for the file. This method returns a [`File`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.file.File) object representing the newly-uploaded file. ``` file_name = 'file.pdf' stream = open('/path/to/file.pdf', 'rb') folder_id = '22222' new_file = client.folder(folder_id).upload_stream(stream, file_name) print(f'File "{new_file.name}" uploaded to Box with file ID {new_file.id}') ``` **NOTE:** Both methods `folder.upload()` and `folder.upload_stream()` include the `stream_file_content` parameter, which controls how the file content is uploaded. If you are uploading a large file, you may want to stream the request to avoid excessive memory usage. According to `requests'` library [docs](https://docs.python-requests.org/en/latest/user/quickstart/#post-a-multipart-encoded-file), by default, the `requests` library does not support streaming uploads, and all the data must be read into memory before being sent to the server. However, the `requests-toolbelt` package includes a `MultipartEncoder` class, which enables file uploads without loading the entire file into memory. This approach is the default in the Box Python SDK. That said, handling 307 Temporary Redirects presents a challenge with streamed file uploads. 307 redirect requires that both the request method and body remain unchanged. This can be problematic when uploading a file stream because the stream will already be exhausted when the redirect occurs. To address this issue, the `stream_file_content` parameter has been introduced in upload methods. This allows you to choose between: Streaming the file (`stream_file_content=True`): Optimizes memory usage but may cause issues with redirects. Using the default `requests'` library behavior (`stream_file_content=False`): Ensures the file can be re-read if a redirect occurs but may consume more memory. This is especially important when working with proxy servers. ## Chunked Upload For large files or in cases where the network connection is less reliable, you may want to upload the file in parts. This allows a single part to fail without aborting the entire upload, and failed parts can then be retried. Since box-python-sdk 3.11.0 release, by default the SDK uses upload urls provided in response when creating a new upload session. This allowes to always upload your content to the closest Box data center and can significantly improve upload speed. You can always disable this feature and always use base upload url by setting `use_upload_session_urls` flag to `False` when creating upload session. ### Automatic Uploader Since box-python-sdk 3.7.0 release, automatic uploader uses multiple threads, which significantly speeds up the upload process. By default, automatic chunked uploader will use 5 threads. You can change this number by setting `API.CHUNK_UPLOAD_THREADS` to a new number. ``` from boxsdk.config import API API.CHUNK_UPLOAD_THREADS = 6 ``` #### Upload new file The SDK provides a method of automatically handling a chunked upload. First get a folder you want to upload the file to. Then call [`folder.get_chunked_uploader(file_path, rename_file=False, use_upload_session_urls=True)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.folder.Folder.get_chunked_uploader) to retrieve a [`ChunkedUploader`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.chunked_uploader.ChunkedUploader) object. Setting `use_upload_session_urls` to `True` inilializes the uploader that utlizies urls returned by the `Create Upload Session` endpoint response unless a custom API.UPLOAD_URL was set in the config. Setting `use_upload_session_urls` to `False` inilializes the uploader that uses always base upload urls. Calling the method [`chunked_upload.start()`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.chunked_uploader.ChunkedUploader.start) will kick off the chunked upload process and return the [File](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.file.File) object that was uploaded. ``` # uploads large file to a root folder chunked_uploader = client.folder('0').get_chunked_uploader(file_path='/path/to/file.txt', file_name='new_name.txt') uploaded_file = chunked_uploader.start() print(f'File "{uploaded_file.name}" uploaded to Box with file ID {uploaded_file.id}') ``` You can also upload file stream by creating a [`UploadSession`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.upload_session.UploadSession) first. This can be done by calling [`folder.create_upload_session(file_size, file_name=None, use_upload_session_urls=True)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.folder.Folder.create_upload_session) method. `use_upload_session_urls` flag is used to determine if the upload session should use urls returned by the `Create Upload Session` endpoint or should it always use base upload urls. Then you can call method [`upload_session.get_chunked_uploader_for_stream(content_stream, file_size)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.upload_session.UploadSession.get_chunked_uploader_for_stream). ``` test_file_path = '/path/to/large_file.mp4' with open(test_file_path, 'rb') as content_stream: total_size = os.stat(test_file_path).st_size upload_session = client.folder('0').create_upload_session(file_size=total_size, file_name='large_file.mp4') chunked_uploader = upload_session.get_chunked_uploader_for_stream(content_stream=content_stream, file_size=total_size) uploaded_file = chunked_uploader.start() print(f'File "{uploaded_file.name}" uploaded to Box with file ID {uploaded_file.id}') ``` #### Upload new file version To upload a new file version for a large file, first get a file you want to replace. Then call [`file.get_chunked_uploader(file_path, rename_file=False, use_upload_session_urls=True)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.file.File.get_chunked_uploader) to retrieve a [`ChunkedUploader`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.chunked_uploader.ChunkedUploader) object. Calling the method [`chunked_upload.start()`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.chunked_uploader.ChunkedUploader.start) will kick off the chunked upload process and return the updated [File](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.file.File). ``` # uploads new large file version chunked_uploader = client.file('existing_big_file_id').get_chunked_uploader(file_path='/path/to/file') uploaded_file = chunked_uploader.start() print(f'File "{uploaded_file.name}" uploaded to Box with file ID {uploaded_file.id}') # the uploaded_file.id will be the same as 'existing_big_file_id' ``` #### Preflight check before upload To check if a file can be uploaded with given name to a specific folder call [`folder.preflight_check(size, name)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.folder.Folder.preflight_check). If the check did not pass, this method will raise an exception including some details on why it did not pass. ``` file_name = 'large_file.mp4' test_file_path = '/path/to/large_file.mp4' total_size = os.stat(test_file_path).st_size destination_folder_id = '0' try: client.folder(destination_folder_id).preflight_check(size=total_size, name=file_name) except BoxAPIException as e: print(f'File {file_name} cannot be uploaded to folder with id: {destination_folder_id}. Reason: {e.message}') ``` #### Resume Upload Sometimes an upload can be interrupted, in order to resume uploading where you last left off, simply call the [`chunked_uploader.resume()`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.chunked_uploader.ChunkedUploader.resume) method. This will return the [File](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.file.File) object that was uploaded. ``` chunked_uploader = client.file('12345').get_chunked_uploader('/path/to/file') try: uploaded_file = chunked_uploader.start() except: uploaded_file = chunked_uploader.resume() print(f'File "{uploaded_file.name}" uploaded to Box with file ID {uploaded_file.id}') ``` #### Abort Chunked Upload To abort a running upload, which cancels all currently uploading chunks and aborts the upload session, call the method [`chunked_uploader.abort()`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.upload_session.UploadSession.abort). ``` from boxsdk.exception import BoxNetworkException test_file_path = '/path/to/large_file.mp4' content_stream = open(test_file_path, 'rb') total_size = os.stat(test_file_path).st_size chunked_uploader = client.file('existing_big_file_id').get_chunked_uploader(file_path='/path/to/file') try: uploaded_file = chunked_uploader.start() except BoxNetworkException: chunked_uploader.abort() ``` ### Manual Process For more complicated upload scenarios, such as those being coordinated across multiple processes or when an unrecoverable error occurs with the automatic uploader, the endpoints for chunked upload operations are also exposed directly. For example, this is roughly how a chunked upload is done manually: ``` import hashlib import os test_file_path = '/path/to/large_file.mp4' total_size = os.stat(test_file_path).st_size sha1 = hashlib.sha1() content_stream = open(test_file_path, 'rb') upload_session = client.folder(folder_id='11111').create_upload_session(file_size=total_size, file_name='test_file_name.mp4') part_array = [] for part_num in range(upload_session.total_parts): copied_length = 0 chunk = b'' while copied_length < upload_session.part_size: bytes_read = content_stream.read(upload_session.part_size - copied_length) if bytes_read is None: # stream returns none when no bytes are ready currently but there are # potentially more bytes in the stream to be read. continue if len(bytes_read) == 0: # stream is exhausted. break chunk += bytes_read copied_length += len(bytes_read) uploaded_part = upload_session.upload_part_bytes(chunk, part_num*upload_session.part_size, total_size) part_array.append(uploaded_part) updated_sha1 = sha1.update(chunk) content_sha1 = sha1.digest() uploaded_file = upload_session.commit(content_sha1=content_sha1, parts=part_array) print(f'File ID: {uploaded_file.id} and File Name: {uploaded_file.name}') ``` The individual endpoint methods are detailed below: #### Create Upload Session for File Version To create an upload session for uploading a large version, call [`file.create_upload_session(file_size, file_name=None, use_upload_session_urls=True)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.file.File.create_upload_session) with the size of the file to be uploaded. You can optionally specify a new `file_name` to rename the file on upload. `use_upload_session_urls` flag is used to determine if the upload session should use urls returned by the `Create Upload Session` endpoint or should it always use base upload urls. This method returns an [`UploadSession`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.upload_session.UploadSession) object representing the created upload session. ``` file_size = 26000000 upload_session = client.file('11111').create_upload_session(file_size) print(f'Created upload session {upload_session.id} with chunk size of {upload_session.part_size} bytes') ``` #### Create Upload Session for File To create an upload session for uploading a new large file, call [`folder.create_upload_session(file_size, file_name, use_upload_session_urls=True)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.folder.Folder.create_upload_session) with the size and filename of the file to be uploaded. `use_upload_session_urls` flag is used to determine if the upload session should use urls returned by the `Create Upload Session` endpoint or should it always use base upload urls. This method returns an [`UploadSession`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.upload_session.UploadSession) object representing the created upload session. ``` file_size = 26000000 file_name = 'test_file.pdf' upload_session = client.folder('22222').create_upload_session(file_size, file_name) print(f'Created upload session {upload_session.id} with chunk size of {upload_session.part_size} bytes') ``` #### Upload Part To upload a part of the file to this session, call [`upload_session.upload_part_bytes(part_bytes, offset, total_size, part_content_sha1=None)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.upload_session.UploadSession.upload_part_bytes) with the `bytes` to be uploaded, the byte offset within the file (which should be a multiple of the upload session `part_size`), and the total size of the file being uploaded. This method returns a `dict` for the part record; these records should be kept for the commit operation. **Note:** The number of bytes uploaded for each part must be exactly `upload_sesion.part_size`, except for the last part (which just includes however many bytes are left in the file). ``` upload_session = client.upload_session('11493C07ED3EABB6E59874D3A1EF3581') offset = upload_session.part_size * 3 total_size = 26000000 part_bytes = b'abcdefgh' part = upload_session.upload_part_bytes(part_bytes, offset, total_size) print(f'Successfully uploaded part ID {part["part_id"]}') ``` #### Commit Upload Session After uploading all parts of the file, commit the upload session to Box by calling [`upload_session.commit(content_sha1, parts=None, file_attributes=None, etag=None)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.upload_session.UploadSession.commit) with the SHA1 hash of the entire file. For best consistency guarantees, you should also pass an `Iterable` of the parts `dict`s via the `parts` parameter; otherwise, the list of parts will be retrieved from the API. You may also pass a `dict` of `file_attributes` to set on the new file. ``` import hashlib sha1 = hashlib.sha1() # sha1 should have been updated with all the bytes of the file file_atributes = { 'description': 'A file uploaded via Chunked Upload', } upload_session = client.upload_session('11493C07ED3EABB6E59874D3A1EF3581') uploaded_file = upload_session.commit(sha1.digest(), file_atributes=file_atributes) print(f'Successfully uploaded file {uploaded_file.id} with description {uploaded_file.description}') ``` #### Abort Upload Session To abort a chunked upload and lose all uploaded file parts, call [`upload_session.abort()`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.upload_session.UploadSession.abort). This method returns `True` to indicate that the deletion succeeded. ``` client.upload_session('11493C07ED3EABB6E59874D3A1EF3581').abort() print('Upload was successfully canceled') ``` #### List Upload Parts To return the list of parts uploaded so far, call [`upload_session.get_parts(limit=None, offset=None)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.upload_session.UploadSession.get_parts). This method returns a `BoxObjectCollection` that allows you to iterate over the part `dict`s in the collection. ``` parts = client.upload_session('11493C07ED3EABB6E59874D3A1EF3581').get_parts() for part in parts: print(f'Part {part["part_id"]} at offset {part["offset"]} has already been uploaded') ``` ## Move a File To move a file from one folder into another, call [`file.move(parent_folder, name=None)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.base_item.BaseItem.move) with the destination folder to move the file into. You can optionally provide a `name` parameter to automatically rename the file in case of a name conflict in the destination folder. This method returns the updated [`File`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.file.File) object in the new folder. ``` file_id = '11111' destination_folder_id = '44444' file_to_move = client.file(file_id) destination_folder = client.folder(destination_folder_id) moved_file = file_to_move.move(parent_folder=destination_folder) print(f'File "{moved_file.name}" has been moved into folder "{moved_file.parent.name}"') ``` ## Copy a File A file can be copied to a new folder by calling [`file.copy(*, parent_folder, name=None, file_version=None, **_kwargs)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.base_item.BaseItem.copy) with the destination folder and an optional new name for the file in case there is a name conflict in the destination folder. This method returns a [`File`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.file.File) object representing the copy of the file in the destination folder. ``` file_id = '11111' destination_folder_id = '44444' file_to_copy = client.file(file_id) destination_folder = client.folder(destination_folder_id) file_copy = file_to_copy.copy(parent_folder=destination_folder) print(f'File "{file_copy.name}" has been copied into folder "{file_copy.parent.name}"') ``` ## Rename a File A file can be renamed by calling [`file.rename(name)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.base_item.BaseItem.rename). This method returns the updated [`File`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.file.File) object with a new name. Remeber to provide also extension of the file along with the new name. ``` file = client.file(file_id='11111') renamed_file = file.rename("new-name.pdf") print(f'File was renamed to "{renamed_file.name}"') ``` ## Delete a File Calling the [`file.delete()`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.item.Item.delete) method will delete the file. Depending on enterprise settings, this will either move the file to the user's trash or permanently delete the file. This method returns `True` to signify that the deletion was successful. ``` client.file(file_id='11111').delete() ``` ## Get Previous Versions of a File Previous versions of a file can be retrieved with the [`file.get_previous_versions(limit=None, offset=None, fields=None)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.file.File.get_previous_versions) method. This method returns a [`BoxObjectCollection`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.pagination.html#boxsdk.pagination.box_object_collection.BoxObjectCollection) that can iterate over the [`FileVersion`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.file_version.FileVersion) objects in the collection. ``` file_id = '11111' file_versions = client.file(file_id).get_previous_versions() for version in file_versions: print(f'File version {version.id} was created at {version.created_at}') ``` ## Upload a New Version of a File New versions of a file can be uploaded in one of two ways: by providing a path to a file on disk, or via a readable stream containing the file contents. To upload a new file version from a path on disk, call the [`file.update_contents(file_path, etag=None, preflight_check=False, preflight_expected_size=0)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.file.File.update_contents) method. This method returns a [`File`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.file.File) object representing the updated file. ``` file_id = '11111' file_path = '/path/to/file.pdf' updated_file = client.file(file_id).update_contents(file_path) print(f'File "{updated_file.name}" has been updated') ``` To upload a file version from a readable stream, call [`file.update_contents_with_stream(file_stream, etag=None, preflight_check=False, preflight_expected_size=0)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.file.File.update_contents_with_stream) with the stream. This method returns a [`File`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.file.File) object representing the newly-uploaded file. ``` file_id = '11111' stream = open('/path/to/file.pdf', 'rb') updated_file = client.file(file_id).update_contents_with_stream(stream) print(f'File "{updated_file.name}" has been updated') ``` ## Promote a Previous Version of a File A previous version of a file can be promoted by calling the [`file.promote_version(file_version)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.file.File.promote_version) method to become the current version of the file with the [`FileVersion`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.file_version.FileVersion) to promote. This create a copy of the old file version and puts it on the top of the versions stack. This method returns the new copy [`FileVersion`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.file_version.FileVersion) object. ``` file_id = '11111' file_version_id = '12345' version_to_promote = client.file_version(file_version_id) new_version = client.file(file_id).promote_version(version_to_promote) print(f'Version {file_version_id} promoted; new version {new_version.id} created') ``` ## Delete a Previous Version of a File A version of a file can be deleted and moved to the trash by calling [`file.delete_version(file_version, etag=None)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.file.File.delete_version) with the [`FileVersion`] to delete. ``` file_id = '11111' version_id = '12345' version_to_delete = client.file_version(version_id) client.file(file_id).delete_version(version_to_delete) ``` ## Lock a File A locked file cannot be modified by any other user until it is unlocked. This is useful if you want to "check out" a file while you're working on it, to ensure that other collaborators do not make changes while your changes are in progress. To lock a file, call [`file.lock(prevent_download=False, expire_time=None)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.file.File.lock). You can optionally prevent other users from downloading the file while it is locked by passing `True` for the `prevent_download` parameter. You can also set an expiration time for the lock, which will automatically release the lock at the specified time. The expiration time is formatted as an [RFC3339 datetime](https://tools.ietf.org/html/rfc3339#section-5.8). This method returns the updated [`File`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.file.File) object. ``` file_id = '11111' updated_file = client.file(file_id).lock(expiration_time='2020-01-01T00:00:00-08:00') print(f'File "{updated_file.name}" has been locked!') ``` ## Unlock a File A locked file can be unlocked by calling [`file.unlock()`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.file.File.unlock). This method returns the updated [`File`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.file.File) object. ``` file_id = '11111' updated_file = client.file(file_id).unlock() print(f'File "{updated_file.name}" has been unlocked!') ``` ## Create a Shared Link Download URL A shared link for a file can be generated by calling [`file.get_shared_link_download_url(access=None, etag=None, unshared_at=None, allow_preview=None, password=None, vanity_name=None)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.file.File.get_shared_link_download_url). This method returns a `unicode` string containing the shared link URL. ``` file_id = '11111' url = client.file(file_id).get_shared_link_download_url(access='collaborators', vanity_name="my-unique-vanity-name") print(f'The file shared link download URL is: {url}') ``` ## Find a File for a Shared Link To find a file given a shared link, use the [`client.get_shared_item`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.client.html?highlight=get_shared_item#boxsdk.client.client.Client.get_shared_item) method. ``` file = client.get_shared_item('https://app.box.com/s/gjasdasjhasd', password='letmein') ``` ## Create or update a Shared Link A shared link for a file can be generated or updated by calling [`file.get_shared_link(*, access=None, etag=None, unshared_at=None, allow_download=None, allow_preview=None, allow_edit=None, password=None, vanity_name=None, **kwargs)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.file.File.get_shared_link). This method returns a `unicode` string containing the shared link URL. ``` file_id = '11111' url = client.file(file_id).get_shared_link(access='open', allow_download=True, allow_edit=True) print(f'The file shared link URL is: {url}') ``` ## Get a Shared Link To check for an existing shared link on a file, simply call `file.shared_link` This method returns a `unicode` string containing the shared link URL. ``` file_id = '11111' shared_link = client.file(file_id).get().shared_link url = shared_link['url'] ``` ## Remove a Shared Link A shared link for a file can be removed by calling [`file.remove_shared_link(*, etag=None, **kwargs)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.item.Item.remove_shared_link). ``` file_id = '11111' client.file(file_id).remove_shared_link() ``` ## Get an Embed Link A file embed URL can be generated by calling [`file.get_embed_url()`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.file.File.get_embed_url). This method returns a `unicode` string containing a URL suitable for embedding in an `<iframe>` to embed the a file viewer in a web page. ``` file_id = '11111' embed_url = client.file(file_id).get_embed_url() print(f'<iframe src="{embed_url}"></iframe>') ``` ## Get File Representations To get the preview representations of a file, call the [`file.get_representation_info(rep_hints=None)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.file.File.get_representation_info) method with the [representation hints](https://developer.box.com/en/reference/get-files-id/#param-X-Rep-Hints) to fetch — if no hints are provided, limited information about all available representations will be returned. This method returns a `list` of `dict`s containing the information about the requested [representations](https://developer.box.com/en/reference/resources/representations). Note that this method only provides information about a set of available representations; your application will need to handle checking the status of the representations and downloading them via the provided content URL template. ``` file_id = '11111' rep_hints = '[pdf][extracted_text]' representations = client.file(file_id).get_representation_info(rep_hints) for rep in representations: print(f'{rep["representation"]} representation has status {rep["status"]["state"]}') print(f'Info URL for this representation is: {rep["info"]["url"]}') print(f'Content URL template is: {rep["content"]["url_template"]}') ``` ## Get Thumbnail (Deprecated) A thumbnail for a file can be retrieved by calling [`file.get_thumbnail(extension='png', min_width=None, min_height=None, max_width=None, max_height=None)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.file.File.get_thumbnail). This method returns the `bytes` of the thumbnail image. ``` file_id = '11111' thumbnail = client.file(file_id).get_thumbnail(extension='jpg') ``` ## Get Thumbnail A thumbnail for a file can now be retrieved by calling [`file.get_thumbnail_representation(dimensions, extension='png')`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.file.File.get_thumbnail_representation). This method returns the `bytes` of the thumbnail image. You must pass in a dimension that is valid for the extension you pass in for this file. To find valid dimensions, you must first make a call with [`file.get_representation_info(rep_hints=None)`]. This will return a `dict` of all available representations with their extensions and dimensions. More details about can be found on our developer docs [here](https://developer.box.com/guides/representations/list-all-representations/). ``` file_id = '11111' thumbnail = client.file(file_id).get_thumbnail_representation('92x92', extension='jpg') ``` ## Set Metadata To set metadata on a file call the [`file.metadata(scope='global', template='properties')`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.item.Item.metadata) to specify the scope and template key of the metadata template to attach. Then, call the [`metadata.set(data)`][metadata_set] method with the key/value pairs to attach. This method returns a `dict` containing the applied metadata instance. Note: This method will unconditionally apply the provided metadata, overwriting the existing metadata for the keys provided. To specifically create or update metadata, see the `create()` or `update()` methods. ``` metadata = { 'foo': 'bar', } applied_metadata = client.file(file_id='11111').metadata(scope='enterprise', template='testtemplate').set(metadata) print(f'Set metadata in instance ID {applied_metadata["$id"]}') ``` Metadata can be added to a file either as free-form key/value pairs or from an existing template. To add metadata to a file, first call [`file.metadata(scope='global', template='properties')`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.item.Item.metadata) to specify the scope and template key of the metadata template to attach (or use the default values to attach free-form keys and values). Then, call [`metadata.create(data)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.metadata.Metadata.create) with the key/value pairs to attach. This method can only be used to attach a given metadata template to the file for the first time, and returns a `dict` containing the applied metadata instance. Note: This method will only succeed if the provided metadata template is not currently applied to the file, otherwise it will fail with a Conflict error. ``` metadata = { 'foo': 'bar', 'baz': 'quux', } applied_metadata = client.file(file_id='11111').metadata().create(metadata) print(f'Applied metadata in instance ID {applied_metadata["$id"]}') ``` Updating metadata values is performed via a series of discrete operations, which are applied atomically against the existing file metadata. First, specify which metadata will be updated by calling [`file.metadata(scope='global', template='properties')`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.item.Item.metadata). Then, start an update sequence by calling [`metadata.start_update()`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.metadata.Metadata.start_update) and add update operations to the returned [`MetadataUpdate`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.metadata.MetadataUpdate). Finally, perform the update by calling [`metadata.update(metadata_update)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.metadata.Metadata.update). This final method returns a `dict` of the updated metadata instance. Note: This method will only succeed if the provided metadata template has already been applied to the file; If the file does not have existing metadata, this method will fail with a Not Found error. This is useful you know the file will already have metadata applied, since it will save an API call compared to `set()`. ``` file_obj = client.file(file_id='11111') file_metadata = file_obj.metadata(scope='enterprise', template='myMetadata') updates = file_metadata.start_update() updates.add('/foo', 'bar') updates.update('/baz', 'murp', old_value='quux') # Ensure the old value was "quux" before updating to "murp" updated_metadata = file_metadata.update(updates) print('Updated metadata on file!') print(f'foo is now {updated_metadata["foo"]} and baz is now {updated_metadata["baz"]}') ``` ## Get Metadata To retrieve the metadata instance on a file for a specific metadata template, first call [`file.metadata(scope='global', template='properties')`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.item.Item.metadata) to specify the scope and template key of the metadata template to retrieve, then call [`metadata.get()`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.metadata.Metadata.get) to retrieve the metadata values attached to the file. This method returns a `dict` containing the applied metadata instance. ``` metadata = client.file(file_id='11111').metadata(scope='enterprise', template='myMetadata').get() print(f'Got metadata instance {metadata["$id"]}') ``` ## Remove Metadata To remove a metadata instance from a file, call [`file.metadata(scope='global', template='properties')`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.item.Item.metadata) to specify the scope and template key of the metadata template to remove, then call [`metadata.delete()`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.metadata.Metadata.delete) to remove the metadata from the file. This method returns `True` to indicate that the removal succeeded. ``` client.file(file_id='11111').metadata(scope='enterprise', template='myMetadata').delete() ``` ## Get All Metadata To retrieve all metadata attached to a file, call [`file.get_all_metadata()`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.item.Item.get_all_metadata). This method returns a [`BoxObjectCollection`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.pagination.html#boxsdk.pagination.box_object_collection.BoxObjectCollection) that can be used to iterate over the `dict`s representing each metadata instance attached to the file. ``` file_metadata = client.file(file_id='11111').get_all_metadata() for instance in file_metadata: if 'foo' in instance: print(f'Metadata instance {instance["id"]} has value "{instance["foo"]}" for foo') ``` ## Set a Classification It is important to note that this feature is only available if you have Governance. To add classification to a [`File`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.file.File), call [`file.set_classification(classification)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.item.Item.set_classification). This method returns the classification type on the [`File`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.file.File) object. If a classification already exists then this call will update the existing classification with the new [`ClassificationType`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.item.ClassificationType). ``` from boxsdk.object.item import ClassificationType classification = client.file(file_id='11111').set_classification(ClassificationType.PUBLIC) print(f'Classification Type is: {classification}') ``` The set method will always work no matter the state your [`File`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.file.File) is in. For cases already where a classification value already exists [`set_classification(classification)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.item.Item.set_classification) may make multiple API calls. Alternatively, if you already know you have a classification and you are simple updating it, you can use the [`update_classification(classification)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.item.Item.update_classification). This will ultimately help you save one extra API call. ``` classification = client.file(file_id='11111').update_classification(ClassificationType.NONE) print(f'Classification Type is: {classification}') ``` ## Retrieve a Classification To retrieve a classification from a [`File`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.file.File), call [`file.get_classification()`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.item.Item.get_classification). This method returns the classification type on the [`File`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.file.File) object. ``` classification = client.file(file_id='11111').get_classification() print(f'Classification Type is: {classification}') ``` ## Remove a Classification To remove a classification from a [`File`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.file.File), call [`file.remove_classification()`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.item.Item.remove_classification). ``` client.file(file_id='11111').remove_classification() ``` ## Set retention policy expiration date To set new retention policy expiration date for the file, call [`set_disposition_at(date_time)`](https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.file.File.set_disposition_at). This method will only work for files under retention with `permanently_delete` disposition action set. Remember that disposition date can't be shortened once set on a file. As the `date_time` parameter you can use either datetime string, e.g. '2035-03-04T10:14:24+14:00' or `datetime.datetime` object. ``` import datetime, pytz new_disposition_date = datetime.datetime(year=2029, month=3, day=4, hour=10, minute=14, second=24, tzinfo=pytz.timezone('US/Alaska')) client.file(file_id='11111').set_disposition_at(date_time=new_disposition_date) ``` If `datetime.datetime` object doesn't have timezone specified, the local timezone will be used. To get the current disposition date you can use the snippet below. ``` disposition_date = client.file(file_id='11111').get(fields=('disposition_at',)).disposition_at ``` --- ### Zip **Type:** page | **Section:** Additional Resources Zip Allows you to create a temporary zip file on Box, containing Box files and folders, and then download it. Download a Zip File Download a… # Zip Allows you to create a temporary zip file on Box, containing Box files and folders, and then download it. - [Download a Zip File](#download-a-zip-file) ## Download a Zip File Calling [`client.download_zip(name, items, writable_stream)`][create_zip] will let you create a new zip file with the specified name and with the specified items and download it to the stream that is passed in. The response is a status `dict` that contains information about the download, including whether it was successful. The created zip file does not show up in your Box account. ``` name = 'test' file = mock_client.file('466239504569') folder = mock_client.folder('466239504580') items = [file, folder] output_file = open('test.zip', 'wb') status = client.download_zip(name, items, output_file) print(f'The status of the zip download is {status["state"]}') ``` --- ### Zip Download **Type:** page | **Section:** Additional Resources Zip Download Allows you to create a temporary zip file of Box files and folders and download them. Create a Zip File Download a Zip File… # Zip Download Allows you to create a temporary zip file of Box files and folders and download them. - [Create a Zip File](#create-a-zip-file) - [Download a Zip File](#download-a-zip-file) ## Create a Zip File Calling [`BoxZip.create(String name, List<BoxZipItem> items)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxZip.html) will let you create a new zip file with the specified name and with the specified items and will return a `BoxZipInfo` object with the download link. This file does not show up in your Box account, but will be temporarily available for download. ``` ArrayList<BoxZipItem> items = new ArrayList<BoxZipItem>(); BoxZipItem file = new BoxZipItem("file", "12345"); BoxZipItem folder = new BoxZipItem("folder", "156472"); items.add(file); items.add(folder); BoxZip zip = new BoxZip(api); BoxZipInfo zipInfo = zip.create("Awesome Zip File", items); ``` ## Download a Zip File Calling [`BoxZip.download(String name, List<BoxZipItem> items, OutputStream output)`](http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxZip.html) will let you create a new zip file with the specified name and with the specified items and download it to the stream that is passed in. The return object is a `BoxZipDownloadStatus` object that contains information about the download, including whether it was successful. The created zip file does not show up in your Box account. ``` ArrayList<BoxZipItem> items = new ArrayList<BoxZipItem>(); BoxZipItem file = new BoxZipItem("file", "12345"); BoxZipItem folder = new BoxZipItem("folder", "156472"); items.add(file); items.add(folder); BoxZip zip = new BoxZip(api); FileOutputStream stream = new FileOutputStream(); BoxZipDownloadStatus zipDownloadStatus = zip.download("Another Awesome Zip File", items, stream); stream.close(); if (zipDownloadStatus.getState() == BoxZipDownloadStatus.State.SUCCEEDED) { System.out.println("Zip downloaded successfully"); } ``` --- ### ZipDownloadsManager **Type:** page | **Section:** Additional Resources ZipDownloadsManager Create zip download Download zip archive Get zip download status Download ZIP Create zip download Creates a request to… # ZipDownloadsManager - [Create zip download](#create-zip-download) - [Download zip archive](#download-zip-archive) - [Get zip download status](#get-zip-download-status) - [Download ZIP](#download-zip) ## Create zip download Creates a request to download multiple files and folders as a single `zip` archive file. This API does not return the archive but instead performs all the checks to ensure that the user has access to all the items, and then returns a `download_url` and a `status_url` that can be used to download the archive. The limit for an archive is either the Account's upload limit or 10,000 files, whichever is met first. **Note**: Downloading a large file can be affected by various factors such as distance, network latency, bandwidth, and congestion, as well as packet loss ratio and current server load. For these reasons we recommend that a maximum ZIP archive total size does not exceed 25GB. This operation is performed by calling function `createZipDownload`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-zip-downloads/). ``` await client.zipDownloads.createZipDownload({ items: [ { id: file1.id, type: 'file' as ZipDownloadRequestItemsTypeField, } satisfies ZipDownloadRequestItemsField, { id: file2.id, type: 'file' as ZipDownloadRequestItemsTypeField, } satisfies ZipDownloadRequestItemsField, { id: folder1.id, type: 'folder' as ZipDownloadRequestItemsTypeField, } satisfies ZipDownloadRequestItemsField, ], downloadFileName: 'zip', } satisfies ZipDownloadRequest); ``` ### Arguments requestBody `ZipDownloadRequest` - Request body of createZipDownload method optionalsInput `CreateZipDownloadOptionalsInput` ### Returns This function returns a value of type `ZipDownload`. If the `zip` archive is ready to be downloaded, the API will return a response that will include a `download_url`, a `status_url`, as well as any conflicts that might have occurred when creating the request. ## Download zip archive Returns the contents of a `zip` archive in binary format. This URL does not require any form of authentication and could be used in a user's browser to download the archive to a user's device. By default, this URL is only valid for a few seconds from the creation of the request for this archive. Once a download has started it can not be stopped and resumed, instead a new request for a zip archive would need to be created. The URL of this endpoint should not be considered as fixed. Instead, use the [Create zip download](e://post_zip_downloads) API to request to create a `zip` archive, and then follow the `download_url` field in the response to this endpoint. This operation is performed by calling function `getZipDownloadContent`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-zip-downloads-id-content/). ``` await client.zipDownloads.getZipDownloadContent(zipDownload.downloadUrl!); ``` ### Arguments downloadUrl `string` - The URL that can be used to download created `zip` archive. Example: `https://dl.boxcloud.com/2.0/zip_downloads/29l00nfxDyHOt7RphI9zT_w==nDnZEDjY2S8iEWWCHEEiptFxwoWojjlibZjJ6geuE5xnXENDTPxzgbks_yY=/content` optionalsInput `GetZipDownloadContentOptionalsInput` ### Returns This function returns a value of type `ByteStream`. Returns the content of the items requested for this download, formatted as a stream of files and folders in a `zip` archive. ## Get zip download status Returns the download status of a `zip` archive, allowing an application to inspect the progress of the download as well as the number of items that might have been skipped. This endpoint can only be accessed once the download has started. Subsequently this endpoint is valid for 12 hours from the start of the download. The URL of this endpoint should not be considered as fixed. Instead, use the [Create zip download](e://post_zip_downloads) API to request to create a `zip` archive, and then follow the `status_url` field in the response to this endpoint. This operation is performed by calling function `getZipDownloadStatus`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-zip-downloads-id-status/). ``` await client.zipDownloads.getZipDownloadStatus(zipDownload.statusUrl!); ``` ### Arguments statusUrl `string` - The URL that can be used to get the status of the `zip` archive being downloaded. Example: `https://dl.boxcloud.com/2.0/zip_downloads/29l00nfxDyHOt7RphI9zT_w==nDnZEDjY2S8iEWWCHEEiptFxwoWojjlibZjJ6geuE5xnXENDTPxzgbks_yY=/status` optionalsInput `GetZipDownloadStatusOptionalsInput` ### Returns This function returns a value of type `ZipDownloadStatus`. Returns the status of the `zip` archive that is being downloaded. ## Download ZIP Creates a zip and downloads its content This operation is performed by calling function `downloadZip`. ``` await client.zipDownloads.downloadZip({ items: [ { id: file1.id, type: 'file' as ZipDownloadRequestItemsTypeField, } satisfies ZipDownloadRequestItemsField, { id: file2.id, type: 'file' as ZipDownloadRequestItemsTypeField, } satisfies ZipDownloadRequestItemsField, { id: folder1.id, type: 'folder' as ZipDownloadRequestItemsTypeField, } satisfies ZipDownloadRequestItemsField, ], downloadFileName: 'zip', } satisfies ZipDownloadRequest); ``` ### Arguments requestBody `ZipDownloadRequest` - Zip download request body optionalsInput `DownloadZipOptionalsInput` ### Returns This function returns a value of type `ByteStream`. --- ### ZipDownloadsManager **Type:** page | **Section:** Additional Resources ZipDownloadsManager Create zip download Download zip archive Get zip download status Download ZIP Create zip download Creates a request to… # ZipDownloadsManager - [Create zip download](#create-zip-download) - [Download zip archive](#download-zip-archive) - [Get zip download status](#get-zip-download-status) - [Download ZIP](#download-zip) ## Create zip download Creates a request to download multiple files and folders as a single `zip` archive file. This API does not return the archive but instead performs all the checks to ensure that the user has access to all the items, and then returns a `download_url` and a `status_url` that can be used to download the archive. The limit for an archive is either the Account's upload limit or 10,000 files, whichever is met first. **Note**: Downloading a large file can be affected by various factors such as distance, network latency, bandwidth, and congestion, as well as packet loss ratio and current server load. For these reasons we recommend that a maximum ZIP archive total size does not exceed 25GB. This operation is performed by calling function `create_zip_download`. See the endpoint docs at [API Reference](https://developer.box.com/reference/post-zip-downloads/). ``` client.zip_downloads.create_zip_download( [ CreateZipDownloadItems(id=file_1.id, type=DownloadZipItemsTypeField.FILE), CreateZipDownloadItems(id=file_2.id, type=DownloadZipItemsTypeField.FILE), CreateZipDownloadItems(id=folder_1.id, type=DownloadZipItemsTypeField.FOLDER), ], download_file_name="zip", ) ``` ### Arguments items `List[CreateZipDownloadItems]` - A list of items to add to the `zip` archive. These can be folders or files. download_file_name `Optional[str]` - The optional name of the `zip` archive. This name will be appended by the `.zip` file extension, for example `January Financials.zip`. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `ZipDownload`. If the `zip` archive is ready to be downloaded, the API will return a response that will include a `download_url`, a `status_url`, as well as any conflicts that might have occurred when creating the request. ## Download zip archive Returns the contents of a `zip` archive in binary format. This URL does not require any form of authentication and could be used in a user's browser to download the archive to a user's device. By default, this URL is only valid for a few seconds from the creation of the request for this archive. Once a download has started it can not be stopped and resumed, instead a new request for a zip archive would need to be created. The URL of this endpoint should not be considered as fixed. Instead, use the [Create zip download](e://post_zip_downloads) API to request to create a `zip` archive, and then follow the `download_url` field in the response to this endpoint. This operation is performed by calling function `get_zip_download_content`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-zip-downloads-id-content/). ``` client.zip_downloads.get_zip_download_content(zip_download.download_url) ``` ### Arguments download_url `str` - The URL that can be used to download created `zip` archive. Example: `https://dl.boxcloud.com/2.0/zip_downloads/29l00nfxDyHOt7RphI9zT_w==nDnZEDjY2S8iEWWCHEEiptFxwoWojjlibZjJ6geuE5xnXENDTPxzgbks_yY=/content` extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `ByteStream`. Returns the content of the items requested for this download, formatted as a stream of files and folders in a `zip` archive. ## Get zip download status Returns the download status of a `zip` archive, allowing an application to inspect the progress of the download as well as the number of items that might have been skipped. This endpoint can only be accessed once the download has started. Subsequently this endpoint is valid for 12 hours from the start of the download. The URL of this endpoint should not be considered as fixed. Instead, use the [Create zip download](e://post_zip_downloads) API to request to create a `zip` archive, and then follow the `status_url` field in the response to this endpoint. This operation is performed by calling function `get_zip_download_status`. See the endpoint docs at [API Reference](https://developer.box.com/reference/get-zip-downloads-id-status/). ``` client.zip_downloads.get_zip_download_status(zip_download.status_url) ``` ### Arguments status_url `str` - The URL that can be used to get the status of the `zip` archive being downloaded. Example: `https://dl.boxcloud.com/2.0/zip_downloads/29l00nfxDyHOt7RphI9zT_w==nDnZEDjY2S8iEWWCHEEiptFxwoWojjlibZjJ6geuE5xnXENDTPxzgbks_yY=/status` extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `ZipDownloadStatus`. Returns the status of the `zip` archive that is being downloaded. ## Download ZIP Creates a zip and downloads its content This operation is performed by calling function `download_zip`. ``` client.zip_downloads.download_zip( [ DownloadZipItems(id=file_1.id, type=DownloadZipItemsTypeField.FILE), DownloadZipItems(id=file_2.id, type=DownloadZipItemsTypeField.FILE), DownloadZipItems(id=folder_1.id, type=DownloadZipItemsTypeField.FOLDER), ], download_file_name="zip", ) ``` ### Arguments items `List[DownloadZipItems]` - A list of items to add to the `zip` archive. These can be folders or files. download_file_name `Optional[str]` - The optional name of the `zip` archive. This name will be appended by the `.zip` file extension, for example `January Financials.zip`. extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. ### Returns This function returns a value of type `ByteStream`. --- ### クイックスタート **Type:** quick-start | **Category:** ガイド | **Section:** Additional Resources # クイックスタート **Source:** [https://ja.developer.box.com/get-started/](https://ja.developer.box.com/get-started/) --- ### コミュニティプロジェクト **Type:** page | **Category:** サポートとコミュニティ | **Section:** Additional Resources コミュニティプロジェクト コミュニティプロジェクトには、Box Developer Communityによって作成され公開されたツールとサービスが表示されます。これらは、SDKとラッパー、APIコネクタ、ツールの… # コミュニティプロジェクト コミュニティプロジェクトには、Box Developer Communityによって作成され公開されたツールとサービスが表示されます。これらは、SDKとラッパー、APIコネクタ、ツールの3つの主要カテゴリに分けられています。 コミュニティプロジェクトとコネクタはコミュニティで作成、管理されており、Boxが所有または管理するものではありません。 プロジェクトを投稿する方法については、[投稿ガイドライン](https://github.com/box-community/community-guidelines/blob/master/.github/CONTRIBUTING.md)を参照するか、[メール](mailto:developer@box.com)で当社にご連絡ください。 ## SDKとラッパー | 名前 | 言語 | 説明 | | --- | --- | --- | | Box Javaラッパー | Java | Claus Ibsenによって作成された、Box API用のJavaラッパー。GitHubリポジトリについては、こちらを参照してください。 | | Box JavaScript SDK | Javascript | Box APIにリクエストを行うためのプロミスベースのクライアントサイドSDK | | Box Ruby SDK | Ruby | Box Content API用のRubyクライアントライブラリ | | Box R SDK | R | Box API用のRインターフェース | | Box Powershell SDK | Powershell | Box APIを呼び出すためのPowerShell SDK | | Powershellモジュール | Powershell | Box Windows SDKを利用してBox環境を管理するPowershellモジュール。Boxを完全に自動化できます。 | | Box PHP/Laravelラッパー | PHP | Box API用のPHPラッパー | | Box PHPラッパー | PHP | Box API用のPHPラッパー | ## APIコネクタ | 名前 | 説明 | | --- | --- | | Azure Logic Apps | Boxから取得したデータに基づいてビジネスフローを構築できます。 | | Cloud Elements | BoxをHubspot、Salesforce、Microsoft Dynamics、その他の一般的なクラウドサービスと簡単に統合できます。 | | IBM Bluemix | BoxをIBM Bluemixアプリケーションに統合して、コンテンツとデータを活用できます。 | | Kloudless | アプリをBoxやその他のCRM、カレンダー、ITSMソフトウェアサービスに統合して、機能を強化できます。 | | Mendix | Mendixアプリケーションプラットフォームで作成したアプリにBoxを接続できます。 | | Microsoft Flow | お好きなアプリとサービスを結ぶ自動化ワークフローを作成して、通知の取得、ファイル同期、データ収集などに利用できます。 | | Mulesoft | BoxとサードパーティCRM、CMS、モバイルアプリケーション、ソーシャルアプリケーションとのデータ同期とプロセス自動化を実現します。 | | Stamplay | 実際のビジネスプロセスをBoxに接続する自動化ワークフローを構築できます。 | | Workato | BoxをCRM、マーケティング、ERP、サポート、会計アプリと統合することで、ドキュメントワークフローを自動化できます。 | ## ツール | 名前 | 言語 | 説明 | | --- | --- | --- | | ShareX | C# | Boxにアップロードできるオープンソースのスクリーンキャプチャツール | **Source:** [https://ja.developer.box.com/support/community-projects/](https://ja.developer.box.com/support/community-projects/) --- ### サポートとコミュニティ **Type:** page | **Category:** サポートとコミュニティ | **Section:** Additional Resources サポートとコミュニティ Boxのコミュニティおよびサポートでは、お客様の質問に答え、Box Platformとの統合をサポートすることを目的としています。 ご意見やご提案、問題や改善すべき点などは、以下のいずれかのチャネルから英語でお送りください。 Box Developer… # サポートとコミュニティ Boxのコミュニティおよびサポートでは、お客様の質問に答え、Box Platformとの統合をサポートすることを目的としています。 ご意見やご提案、問題や改善すべき点などは、以下のいずれかのチャネルから英語でお送りください。 - [Box Developer Community](https://community.box.com/): コード、技術統合、一般的なリクエストのサポート - [Twitter](https://twitter.com/BoxPlatform): 一般的な質問とサポート - [サポートチケットの送信](https://support.box.com/hc/ja/requests/new): アカウント固有の質問とサポート コミュニティプロジェクトやPlatformの変更に関する最新情報を入手するには、以下のチャネルをご利用ください。 - [変更ログ](page://changelog): APIの変更、非推奨のサービス、リリース - [開発者向けニュースレター](page://newsletter): 主なイベント、プロジェクト、リリースに関する定期的なお知らせ **Source:** [https://ja.developer.box.com/support/](https://ja.developer.box.com/support/) --- ### 開発者向けニュースレター **Type:** page | **Category:** 開発者向けニュースレター | **Section:** Additional Resources … # 開発者向けニュースレター 当社ではトップ開発者のイベント、製品リリース、コミュニティのハイライトを掲載したニュースレターを、年間を通してコミュニティに送信しています。 ニュースレターの送信をご希望の方は、[開発者コンソール](https://cloud.app.box.com/developers/console)への初回アクセス後、自動的にサインアップされます。 ## 過去のニュースレター これまでに送信されたニュースレターのアーカイブを以下に示します。 | 年 | 月 | アーカイブ | | --- | --- | --- | | 2019 | 9月 | Preview | | 2019 | 12月 | Preview | | 2020 | 4月 | Preview | | 2020 | 7月 | Preview | | 2020 | 12月 | Preview | | 2021 | 4月 | Preview | | 2021 | 8月 | Preview | | 2021 | 11月 | Preview | | 2022 | 2月 | Preview | | 2022 | 6月 | Preview | | 2022 | 8月 | Preview | | 2022 | 9月 | Preview | | 2022 | 11月 | Preview | | 2023 | 2月 | Preview | | 2023 | 5月 | Preview | | 2023 | 6月 | Preview | | 2023 | 8月 | Preview | | 2023 | 11月 | Preview | | 2023 | 12月 | Preview | | 2024 | 1月 | Preview | | 2024 | 2月 | Preview | | 2024 | 3月 | Preview | | 2024 | 4月 | Preview | | 2024 | 5月 | Preview | | 2024 | 6月 | Preview | | 2024 | 7月 | Preview | | 2024 | 8月 | Preview | | 2024 | 9月 | Preview | | 2024 | 10月 | Preview | | 2024 | 11月 | Preview | **Source:** [https://ja.developer.box.com/newsletter/](https://ja.developer.box.com/newsletter/) --- ## sign ### APIの基本 **Type:** page | **Category:** Box Signの使用 | **Section:** sign APIの基本 Sign API… # APIの基本 ## Sign API 署名リクエストを作成して管理するには、署名リクエストのエンドポイントを使用します。署名リクエストは、作成、再送信、キャンセルできます。また、すべての署名リクエストのリストを取得したり、特定の署名リクエストの詳細を取得したりすることもできます。 エンドポイントは`https://{api.box.com}/2.0/sign_requests`です。次の表に、このエンドポイントで実行できる操作を示します。 | 操作 | エンドポイント | 説明 | | --- | --- | --- | | GET | /sign_requests | すべての署名リクエストのリストを取得します。 | | GET | /sign_requests/:id | 特定の署名リクエストの詳細を取得します。 | | POST | /sign_requests | 署名リクエストを作成します。 | | POST | /sign_requests/:id/resend | 署名リクエストを再送信します。 | | POST | /sign_requests/:id/cancel | 署名リクエストをキャンセルします。 | リクエストとレスポンスのパラメータの詳細については、[署名リクエストAPIリファレンス](resource://sign-request)を参照してください。 ## SignテンプレートAPI テンプレートのリストと詳細を取得するには、Signテンプレートエンドポイントを使用します。 このAPIを使用してテンプレートを作成、編集、削除することはできません。これらのテンプレートは、Boxウェブアプリでのみ管理されます。 エンドポイントは`https://{api.box.com}/2.0/sign_templates`です。次の表に、このエンドポイントで実行できる操作を示します。 | 操作 | エンドポイント | 説明 | | --- | --- | --- | | GET | /sign_templates | すべてのテンプレートのリストを取得します。 | | GET | /sign_templates/:id | 特定のテンプレートの詳細を取得します。 | リクエストとレスポンスのパラメータの詳細については、[SignテンプレートリクエストAPIリファレンス](resource://sign-template)を参照してください。 **Source:** [https://ja.developer.box.com/sign/quick-start/api-basics/](https://ja.developer.box.com/sign/quick-start/api-basics/) --- ### Box Signの使用 **Type:** page | **Category:** Box Signの使用 | **Section:** sign Box Signの使用 この学習ページでは、アプリケーションへのBox Platform Signエンジンの統合を促進することを目的に、Box Sign… # Box Signの使用 この学習ページでは、アプリケーションへのBox Platform Signエンジンの統合を促進することを目的に、[Box Sign](https://www.box.com/esignature)の使用に関する実践的なインサイトを開発者に提供します。 ## クイックスタート [クイックスタート](page://sign/quick-start)を使用すると、すぐに署名リクエストの作成に着手することができます。 ## 技術的なユースケース [技術的なユースケース](page://sign/technical-use-cases)では、準備手順が必要な非構造化ドキュメントから、テンプレート、署名する準備ができている生成済みドキュメントまで、署名リクエストで使用できるさまざまな種類のドキュメントを処理する方法について説明します。 ## リクエストのオプション [リクエストのオプション](page://sign/request-options)では、Box Sign APIを使用して署名リクエストを送信する際に利用できるカスタマイズと構成のオプションについて詳しく説明します。アプリケーションのユーザーインターフェース、ワークフロー、特定の要件に合うように署名エクスペリエンスを調整する方法を確認してください。 それでは、始めましょう。 **Source:** [https://ja.developer.box.com/sign/](https://ja.developer.box.com/sign/) --- ## box-ui-elements ### Box UI Elements **Type:** page | **Category:** Box UI Elements | **Section:** box-ui-elements Box UI Elements エクスペリエンスを 構築: Box UI Elements Box UI Elementsは、メインのBoxウェブアプリの要素を使用してカスタムポータルを拡張できるようにする、組み込みのUIコンポーネントです。 対話型のデモ Box UI… # Box UI Elements エクスペリエンスを 構築: Box UI Elements Box UI Elementsは、メインのBoxウェブアプリの要素を使用してカスタムポータルを拡張できるようにする、組み込みのUIコンポーネントです。 対話型のデモ Box UI Elementsは、Reactコンポーネントとしても、フレームワークに依存しないJavaScriptライブラリとしても使用できます。 開始する Box UI Elementsの詳細を確認 すぐに使用できるように、さらに多くのガイドやドキュメントを参照しましょう。 コンテンツプレビューUI ElementにBox AIを埋め込む方法を確認できます。 コンテンツアップローダーを埋め込み、ユーザーがファイルをアップロードできるようにします。 コンテンツエクスプローラーを使用して、指定されたメタデータに基づいたファイルを表示します。 コンテンツプレビュー内にコラボレーション機能を提供します。 カスタムポータルの構築 Box UI Elementsに関連した動画、ブログ記事、サンプルコードで詳細を確認しましょう。 Box UI Elementsを使用して、エクスペリエンスをカスタマイズしたコンテンツポータルを構築します。 Box API、Box UI Elements、React、Tailwind CSS、Vercelについて説明します。 コンテンツプレビューUI ElementにBox AIを埋め込む方法を確認できます。 **Source:** [https://ja.developer.box.com/box-ui-elements/](https://ja.developer.box.com/box-ui-elements/) --- ## sign ### Sign Webhook **Type:** page | **Category:** Box Signの使用 | **Section:** sign Sign Webhook Sign Webhookを使用すると、Box Signの署名リクエストに伴って発生したイベントに関する通知を受信することができます。Sign Webhookを使用して、自分のアプリケーションで操作をトリガーしたり、Box Sign… # Sign Webhook Sign Webhookを使用すると、Box Signの署名リクエストに伴って発生したイベントに関する通知を受信することができます。Sign Webhookを使用して、自分のアプリケーションで操作をトリガーしたり、Box Signで発生したイベントについてユーザーに通知したりできます。 署名リクエストが非同期処理で、署名者はいつでも (場合によってはアプリケーション外部でも) 署名リクエストを操作できるので、これは特に重要になります。 ## Sign関連のイベント WebhookをトリガーできるBox Sign関連のイベントがあります。Boxイベントの大半と同様、リスナーはフォルダレベルまたはドキュメントレベルで設定されます。 最も一般的なユースケースでは、署名リクエストが作成されるフォルダでイベントをリッスンします。これにより、そのフォルダに作成されるすべての署名リクエストをリッスンできます。 リッスンできるイベントの例を以下に示します。 - `SIGN_REQUEST.COMPLETED`: 署名リクエストが完了した。 - `SIGN_REQUEST.DECLINED`: 署名リクエストが拒否された。 - `SIGN_REQUEST.EXPIRED`: 署名リクエストの有効期限が切れた。 - `SIGN_REQUEST.SIGNER_EMAIL_BOUNCED`: 署名者のメールが差し戻された。 - `SIGN_REQUEST.SIGNER_SIGNED`: 署名リクエストが署名された。 - `SIGN_REQUEST.SIGNATURE_REQUESTED`: 署名が署名者にリクエストされた。 - `SIGN_REQUEST.ERROR_FINALIZING`: 署名リクエストを処理できなかった。 **Source:** [https://ja.developer.box.com/sign/webhooks/](https://ja.developer.box.com/sign/webhooks/) --- ### カスタムメールと通知 **Type:** page | **Category:** Box Signの使用 | **Section:** sign カスタムメールと通知 メールの件名と本文 署名者に送信されるメールには、デフォルトで、ドキュメントへのリンク、一般的な件名、一般的なメッセージが記載されています。 Box… # カスタムメールと通知 ## メールの件名と本文 署名者に送信されるメールには、デフォルトで、ドキュメントへのリンク、一般的な件名、一般的なメッセージが記載されています。 Box内で管理されているテンプレートを使用する場合、件名とメッセージ本文はテンプレート自体で設定できます。 ただし、テンプレートを使用しない場合も、`email_subject`パラメータと`email_message`パラメータを渡すことで、署名者に送信されるメールメッセージをカスタマイズすることができます。 どちらのパラメータにも文字列を使用できますが、`email_message`パラメータには、いくつか制限はあるもののHTMLも使用できます。 使用できるのは、一部のHTMLタグだけです。また、メッセージに含まれるリンクは、メールではハイパーリンクに変換されます。 メッセージパラメータには、以下のHTMLタグを含めることができます。 - `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, `strong` これらのタグにカスタムスタイルを適用することはできません。 テキストとHTMLの比率が大きすぎると、メールがスパムフィルタに入ったり、切り取られたりする可能性があることにご注意ください。 例: ``` curl --location 'https://api.box.com/2.0/sign_requests' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer ej...3t' \ --data-raw '{ "email_subject": "All we need is your signature to get started", "parent_folder": { "id": "234102987614", "type": "folder" }, "source_files": [ { "id": "1358047520478", "type": "file" } ], "signers": [ { "email": "signer@example.com", "role": "signer" } ] }' ``` ``` def sign_doc_single_more_options( client: Client, ... email_subject: str = None, email_message: str = None, ) -> SignRequest: ... # sign document sign_request = client.sign_requests.create_sign_request( ... email_subject=email_subject, email_message=email_message, ) return sign_request def main(): ... # Sign with custom email subject sign_custom_email_subject = sign_doc_single_more_options( client, SIMPLE_PDF, SIGN_DOCS_FOLDER, SIGNER_A, prep_needed=False, email_subject="All we need is your signature to get started", ) ``` ## 手動による通知 ここまでで、署名リクエストでは、デフォルトで署名者にメール通知が送信されることがわかりました。このメールは`box.com`ドメインおよびメールシステムから送信されます。 `embed_url_external_user_id`パラメータに特定の署名者を表す任意の識別子を設定することで、通知プロセスを引き継ぐことができます。 このパラメータを設定すると、署名者にはメール通知が送信されず、署名リクエスト内で`embed_url`と`iframeable_embed_url`の両方が返されます。 `embed_url`は直接開くことができるので、アプリからメールで送信したり、署名者が開く他の通知システムで送信したりするのに適しています。 `iframeable_embed_url`は、[Box Signクライアントの埋め込み機能](g://box-sign/embedded-sign-client)との併用に適しており、ウェブアプリ内のiframeにBox Signクライアントを埋め込むことができます。 たとえば、次のリクエストを確認してください。 ``` --header 'Content-Type: application/json' \ --header 'Authorization: Bearer fN...dD' \ --data-raw '{ "is_document_preparation_needed": false, "parent_folder": { "id": "234102987614", "type": "folder" }, "source_files": [ { "id": "1355143830404", "type": "file" } ], "signers": [ { "email": "signer@example.com", "embed_url_external_user_id": "1234", "role": "signer" } ] }' ``` ``` def sign_doc_embed_url( client: Client, document_id: str, destination_folder_id: str, signer_email: str, signer_embed_url_id: str, ) -> SignRequest: # Sign request params source_file = FileBase(id=document_id, type=FileBaseTypeField.FILE) destination_folder = FolderMini( id=destination_folder_id, type=FolderBaseTypeField.FOLDER ) signer = SignRequestCreateSigner( email=signer_email, embed_url_external_user_id=signer_embed_url_id, ) # sign document sign_request = client.sign_requests.create_sign_request( signers=[signer], parent_folder=destination_folder, source_files=[source_file], ) return sign_request def main(): """Simple script to demonstrate how to use the Box SDK""" conf = ConfigOAuth() client = get_client_oauth(conf) # Sign with phone verification sign_with_embed_url = sign_doc_embed_url( client, SIMPLE_PDF, SIGN_DOCS_FOLDER, SIGNER_A, SIGNER_A_EXTERNAL_ID, ) check_sign_request(sign_with_embed_url) ``` 結果は次のとおりです (簡略化されています)。 ``` { "is_document_preparation_needed": false, "signers": [ { "email": "sender@example.com", "role": "final_copy_reader", }, { "email": "signer@example.com", "role": "signer", "embed_url_external_user_id": "1234", "embed_url": "https://app.box.com/sign/document/22a990ce-4e24-463b-b2f4-124820fe161a/9331fe9ac85650d61645d4b0fd30fe3e0ebee7921720ab6ecca587654d3cd875/", "iframeable_embed_url": "https://app.box.com/embed/sign/document/22a990ce-4e24-463b-b2f4-124820fe161a/9331fe9ac85650d61645d4b0fd30fe3e0ebee7921720ab6ecca587654d3cd875/" } ], "id": "22a990ce-4e24-463b-b2f4-124820fe161a", } ``` ``` Simple sign request: 22a990ce-4e24-463b-b2f4-124820fe161a-defddc79c946 Status: created Signers: 2 final_copy_reader: sender@example.com signer: signer@example.com embed_url: https://app.box.com/sign/document/... iframeable_embed_url: https://app.box.com/embed/sign/document/... Prepare url: None ``` これで、埋め込みURLを取得して、独自の通知プロセスを使用したり、自分のアプリ内に署名クライアントを埋め込んだりできるようになりました。 **Source:** [https://ja.developer.box.com/sign/request-options/custom-email/](https://ja.developer.box.com/sign/request-options/custom-email/) --- ### クイックスタート **Type:** page | **Category:** Box Signの使用 | **Section:** sign クイックスタート Box Sign APIの構造と、最初の署名リクエストの作成方法の趣旨を把握しましょう。 Sign APIは従来のCRUD… # クイックスタート [Box Sign API](page://sign/quick-start/api-basics)の構造と、最初の署名リクエストの作成方法の趣旨を把握しましょう。 Sign APIは従来のCRUDモデルに従っていません。署名リクエストは、作成、再送信、キャンセルできます。また、すべての署名リクエストのリストを取得したり、特定の署名リクエストの詳細を取得したりすることもできます。 SignテンプレートAPIは読み取り専用です。すべてのテンプレートのリストを取得したり、特定のテンプレートの詳細を取得したりすることができます。 APIの趣旨を把握したら、[最初の署名リクエスト](page://sign/quick-start/your-first-request)を作成できます。 **Source:** [https://ja.developer.box.com/sign/quick-start/](https://ja.developer.box.com/sign/quick-start/) --- ### セキュリティの強化 (2要素認証) **Type:** page | **Category:** Box Signの使用 | **Section:** sign セキュリティの強化 (… # セキュリティの強化 (2要素認証) ドキュメントへの署名手順で署名者に対してパスワードや電話認証を要求することで、署名リクエストの[セキュリティレベルを高める](https://support.box.com/hc/en-us/articles/4406861109907-Additional-Signer-Authentication)方法について説明します。 テンプレート内または署名リクエストの作成時にセキュリティレベルを高めることができます。 ## 電話認証 署名者の`verification_phone_number`パラメータとともに電話番号を渡すことにより、署名リクエストを完了するために携帯電話から2要素認証を使用するよう署名者に要求することができます。 例: ``` curl --location 'https://api.box.com/2.0/sign_requests' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer ej...3t' \ --data-raw '{ "is_document_preparation_needed": true, "parent_folder": { "id": "234102987614", "type": "folder" }, "source_files": [ { "id": "1358047520478", "type": "file" } ], "signers": [ { "email": "verify@example.com", "role": "signer", "verification_phone_number": "+15551232190" } ] }' ``` ``` def sign_doc_verify_phone( client: Client, document_id: str, destination_folder_id: str, signer_email: str, signer_phone: str, ) -> SignRequest: # Sign request params source_file = FileBase(id=document_id, type=FileBaseTypeField.FILE) destination_folder = FolderMini( id=destination_folder_id, type=FolderBaseTypeField.FOLDER ) signer = SignRequestCreateSigner( email=signer_email, verification_phone_number=signer_phone, ) # sign document sign_request = client.sign_requests.create_sign_request( signers=[signer], parent_folder=destination_folder, source_files=[source_file], is_phone_verification_required_to_view=True, ) return sign_request def main(): ... # Sign with phone verification sign_with_phone_verification = sign_doc_verify_phone( client, SIMPLE_PDF, SIGN_DOCS_FOLDER, SIGNER_A, SIGNER_A_PHONE, ) check_sign_request(sign_with_phone_verification) ``` 署名者が署名リクエストにアクセスしようとすると、電話認証のダイアログがポップアップ表示されます。 その後、署名者はSMSで送信されたコードを入力するよう求められます。 ## パスワード認証 `signer`オブジェクトに`password`パラメータを渡すことにより、署名リクエストを開くためにパスワードを使用するよう署名者に要求することができます。次に例を示します。 ``` curl --location 'https://api.box.com/2.0/sign_requests' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer ej...3t' \ --data-raw '{ "is_document_preparation_needed": true, "parent_folder": { "id": "234102987614", "type": "folder" }, "source_files": [ { "id": "1358047520478", "type": "file" } ], "signers": [ { "email": "verify@example.com", "role": "signer", "password": "1234" } ] }' ``` ``` def sign_doc_verify_password( client: Client, document_id: str, destination_folder_id: str, signer_email: str, signer_password: str, ) -> SignRequest: # Sign request params source_file = FileBase(id=document_id, type=FileBaseTypeField.FILE) destination_folder = FolderMini( id=destination_folder_id, type=FolderBaseTypeField.FOLDER ) # signer signer = SignRequestCreateSigner( email=signer_email, password=signer_password, ) # sign document sign_request = client.sign_requests.create_sign_request( signers=[signer], parent_folder=destination_folder, source_files=[source_file], ) return sign_request def main(): ... # Sign with phone verification sign_with_password_verification = sign_doc_verify_password( client, SIMPLE_PDF, SIGN_DOCS_FOLDER, SIGNER_A, "1234", ) ``` 署名者が署名リクエストを開くと、次のような画面が表示されます。 パスワード認証は最初の手順で行われるため、正しいパスワードが入力されるまで、署名者はドキュメントにアクセスできません。 **Source:** [https://ja.developer.box.com/sign/request-options/extra-security/](https://ja.developer.box.com/sign/request-options/extra-security/) --- ### テンプレートを使用した署名 **Type:** page | **Category:** Box Signの使用 | **Section:** sign テンプレートを使用した署名 Box Sign… # テンプレートを使用した署名 [Box Signテンプレート](https://support.box.com/hc/en-us/sections/21356768117651-Templates)は、テキストだけでなく、署名の要件や配置も含む特定の種類のドキュメントです。これは署名用に事前に準備されているため、署名者 (複数可) に直接送信できます。 必須フィールドには、署名パッド、フルネーム、日付などがあります。 これらのフィールドには1人の所有者が設定されています。つまり、フィールドは特定の署名者が入力し、署名者間で共有することはできません。これらは、`mandatory`または`optional`にすることができるほか、アプリケーションによって事前入力することもできます。ただし、事前に入力されている場合でも、`signer`がいつでも変更できます。 Boxウェブアプリ内では、テンプレートによって、署名フィールドだけでなく、署名者の数、署名の順序、他の役割と受信者 (`approver`や`final_copy_recipient`など)、メール通知の設定、その他いくつかのオプションも設定されます。 署名リクエストのオプションの詳細については、[リクエストのオプション](page://sign/request-options)セクションを参照してください。 これらのテンプレートは、Box Signウェブアプリでのみ作成および管理され、APIまたはウェブアプリを使用して署名リクエストを作成する際に使用できます。 最初に、テンプレートを作成しましょう。 ## テンプレートの作成 Boxアプリで、左側の [Sign] メニューに移動し、[テンプレート] を選択します。 次に、[新しいテンプレート] ボタンをクリックし、Boxからドキュメントを選択またはアップロードします。 次のように、日付、名前、署名パッドをテンプレートにドラッグアンドドロップします。 受信者の[セキュリティレベルを高める](page://sign/request-options/extra-security)ことができます。メールアドレスがあらかじめ定義された定義済みの受信者と、テンプレートユーザーがメールアドレスを指定する必要があるプレースホルダの受信者の両方が対象です。 テンプレートを保存します。 ## テンプレートの識別 Box Sign APIでテンプレートを使用するには、`template_id`が必要になります。ユーザーが利用できるすべてのテンプレートのリストを取得するための次のメソッドを考えてみます。 ``` curl --location 'https://api.box.com/2.0/sign_templates' \ --header 'Authorization: Bearer E9...Q0' ``` ``` def sign_templates_list(client: Client): """List all sign templates""" sign_templates = client.sign_templates.get_sign_templates() print(f"\nSign templates: {len(sign_templates.entries)}") for sign_template in sign_templates.entries: print(f" {sign_template.id} - {sign_template.name}") def main(): """Simple script to demonstrate how to use the Box SDK""" conf = ConfigOAuth() client = get_client_oauth(conf) user = client.users.get_user_me() print(f"\nHello, I'm {user.name} ({user.login}) [{user.id}]") sign_templates_list(client) ``` 次のような結果が返されます (簡略化されています)。 ``` { "limit": 10, "next_marker": null, "prev_marker": null, "entries": [ { "type": "sign-template", "id": "f2ec720d-47a6-4052-8210-9bfa8d6c349c", "name": "Simple-DOC.pdf", "parent_folder": { "id": "157064745449", "type": "folder", "name": "My Sign Requests" }, "source_files": [ { "id": "1393013714313", "type": "file", } ], "signers": [ { "email": "", "label": "", "role": "final_copy_reader", "inputs": [] }, { "email": "", "label": "Signer", "role": "signer", "inputs": [ { "document_tag_id": null, "id": "d02c8e16-5050-475e-b74b-9a952193e4f8", "type": "date", "date_value": null, "content_type": "date", }, { "document_tag_id": null, "id": "bdcc966e-2ebf-4b3b-aaee-99d4e1161a9e", "type": "text", "text_value": null, "is_required": true, "content_type": "full_name", }, { "document_tag_id": null, "id": "1a8f4cb1-5c09-46bd-96f5-0ab449f19640", "type": "signature", "text_value": null, "is_required": true, "content_type": "signature", } ] } ], } ] } ``` ``` Hello, I'm Rui Barbosa [18622116055] Sign templates: 1 94e3815b-f7f5-4c2c-8a26-e9ba5c486031 - Simple-PDF.pdf ``` ## テンプレートからの署名リクエストの作成 テンプレートを使用する大きなメリットは、ドキュメントの準備について心配する必要がないことです。ほとんどの署名オプションはテンプレート自体で設定できます。 フローは次のようになります。 署名テンプレートを使って署名リクエストを作成し、最終的にドキュメントに署名します。 次の例を確認してください。 ``` curl --location 'https://api.box.com/2.0/sign_requests' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer E9...Q0' \ --data-raw '{ "template_id": "f2ec720d-47a6-4052-8210-9bfa8d6c349c", "parent_folder": { "id": "234102987614", "type": "folder" }, "signers": [ { "email": "signer@example.com", "role": "signer" } ] }' ``` ``` def create_sign_request(client: Client, template_id: str, signer_email: str): """Create sign request from template""" parent_folder = FolderMini( id=SIGN_DOCS_FOLDER, type=FolderBaseTypeField.FOLDER ) signer = SignRequestCreateSigner( email=signer_email, ) sign_request = client.sign_requests.create_sign_request( signers=[signer], parent_folder=parent_folder, template_id=template_id, ) return sign_request def main(): ... # Create sign request from template sign_request = create_sign_request(client, TEMPLATE_SIMPLE, SIGNER_A) check_sign_request(sign_request) ``` 結果は次のとおりです (簡略化されています)。 ``` { "signers": [ { "email": "sender@example.com", "role": "final_copy_reader", }, { "email": "signer@example.com", "role": "signer", } ], "id": "71e86670-5850-44cc-8b4d-9f5eab6c04de", "parent_folder": { "id": "234102987614", "type": "folder", "name": "signed docs" }, "name": "Simple-DOC (1).pdf", "type": "sign-request", "status": "created", "sign_files": { "files": [ { "id": "1393030489686", "type": "file", "name": "Simple-DOC (1).pdf", } ], }, "template_id": "f2ec720d-47a6-4052-8210-9bfa8d6c349c" } ``` ``` Simple sign request: b25674a2-540b-4201-ae18-a78f05ef1a9a Status: created Signers: 2 final_copy_reader: sender@example.com signer: signer@example.com Prepare url: None ``` 署名者は、ドキュメントへのリンクが記載されたメールをBox.comから受信すると、そのドキュメントに署名できます。 テンプレートにはすでに署名要件が設定されているため、ドキュメントの準備は必要ありませんでした。日付には現在の日付が自動的に入力されていることに注意してください。 ## 署名の属性の事前入力 使いやすさの観点から、ユーザーに求める入力データを事前入力することをお勧めします。 一部の入力データは意図的に入力されていない可能性があります。たとえば、法務部門では、署名者が明示的に「はい、同意します」と設定する必要があると規定している場合があります。 BoxアプリのSignテンプレートエディタを使用すると、各入力データに`external_id`を割り当てて、アプリに任意のデータソースから入力データを入力させることができます。 これを名前に実装しましょう。 テンプレートのデザインに戻り、名前フィールドにIDを追加します。 テンプレートを保存します。 名前を事前入力する新しいメソッドを作成しましょう。 ``` curl --location 'https://api.box.com/2.0/sign_requests' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer E9..Q0' \ --data-raw '{ "template_id": "f2ec720d-47a6-4052-8210-9bfa8d6c349c", "parent_folder": { "id": "234102987614", "type": "folder" }, "signers": [ { "email": "signer@example.com", "role": "signer" } ], "prefill_tags": [ { "document_tag_id": "signer_full_name", "text_value": "Signer A" } ] }' ``` ``` def create_sign_request_name_default( client: Client, template_id: str, signer_name, signer_email: str ): """Create sign request from template""" parent_folder = FolderMini( id=SIGN_DOCS_FOLDER, type=FolderBaseTypeField.FOLDER ) signer = SignRequestCreateSigner( email=signer_email, ) # tags tag_full_name = SignRequestPrefillTag( document_tag_id="signer_full_name", text_value=signer_name, ) sign_request = client.sign_requests.create_sign_request( signers=[signer], parent_folder=parent_folder, prefill_tags=[tag_full_name], template_id=template_id, ) return sign_request def main(): ... # Create sign request from template with name sign_request_name = create_sign_request_name_default( client, TEMPLATE_SIMPLE, "Signer A", SIGNER_A ) check_sign_request(sign_request_name) ``` 結果は次のとおりです (簡略化されています)。 ``` { "signers": [ { "email": "sender@example.com", "role": "final_copy_reader", }, { "email": "signer@example.com", "role": "signer", "is_in_person": false, } ], "id": "6f42a041-7ed8-4e08-9958-78a97259f80d", "prefill_tags": [ { "document_tag_id": "signer_full_name", "text_value": "Signer A", } ], "parent_folder": { "id": "234102987614", "type": "folder", "name": "signed docs" }, "name": "Simple-DOC (2).pdf", "type": "sign-request", "status": "created", "sign_files": { "files": [ { "id": "1393047116817", "type": "file", "name": "Simple-DOC (2).pdf", } ], }, "template_id": "f2ec720d-47a6-4052-8210-9bfa8d6c349c" } ``` ``` Simple sign request: adab1740-eeba-4392-a3f5-defddc79c946 Status: created Signers: 2 final_copy_reader: sender@example.com signer: signer@example.com Prepare url: None ``` 署名者の受信トレイを開き、署名リクエストを完了します。 `signer`は、ドキュメントを表示した際にその名前を変更できます。 ## テンプレートに関する詳細情報の取得 ユーザーが利用できるテンプレートのリストを取得できることはわかりましたが、特定のテンプレートに関する詳細情報を取得することもできます。 テンプレートの基本情報を返すほか、署名要件をすべて列挙するメソッドを作成しましょう。 ``` curl --location 'https://api.box.com/2.0/sign_templates/ f2ec720d-47a6-4052-8210-9bfa8d6c349c' \ --header 'Authorization: Bearer OL..BQ' ``` ``` def sign_template_print_info(client: Client, template_id: str): sign_template = client.sign_templates.get_sign_template_by_id(template_id) print(f"\nSign template: {sign_template.id} - {sign_template.name}") print(f" Signers: {len(sign_template.signers)}") for signer in sign_template.signers: print(f" {signer.role.value}") if len(signer.inputs) > 0: print(" Tag ID\t Type\t Required") for input in signer.inputs: print( f" {input.document_tag_id} {input.type.value} {input.is_required}" ) def main(): ... # Print sign template details sign_template_print_info(client, TEMPLATE_SIMPLE) ``` 結果は次のとおりです (簡略化されています)。 ``` { "type": "sign-template", "id": "f2ec720d-47a6-4052-8210-9bfa8d6c349c", "name": "Simple-DOC.pdf", "parent_folder": { "id": "234102987614", "type": "folder", "name": "signed docs" }, "source_files": [ { "id": "1393013714313", "type": "file", } ], "signers": [ { "email": "", "label": "", "role": "final_copy_reader", }, { "email": "", "label": "Signer", "role": "signer", "inputs": [ { "document_tag_id": null, "id": "d02c8e16-5050-475e-b74b-9a952193e4f8", "type": "date", "is_required": true, "date_value": null, "content_type": "date", }, { "document_tag_id": "signer_full_name", "id": "bdcc966e-2ebf-4b3b-aaee-99d4e1161a9e", "type": "text", "text_value": null, "is_required": true, "content_type": "full_name", }, { "document_tag_id": null, "id": "1a8f4cb1-5c09-46bd-96f5-0ab449f19640", "type": "signature", "is_required": true, "content_type": "signature", } ] } ], } ``` ``` Sign template: 94e3815b-f7f5-4c2c-8a26-e9ba5c486031 - Simple-PDF.pdf Signers: 2 final_copy_reader signer Tag ID Type Required None date True signer_full_name text True None signature True ``` `signer_full_name`は、名前を事前に入力するために使用した`tag_id`であることに注意してください。 ## まとめ テンプレートは、署名用の構造化されたドキュメントの一種で、署名要件がすでに定義され、ドキュメントに配置されています。 これは、契約管理チームにとって便利なだけでなく、ユーザーの労力をあまり必要としない一貫性のあるプロセスを構築します。 さらに、ドキュメントの署名要件に多くのオプションがある場合は、別のデータソースからこれらを事前に入力して、ユーザーの時間を節約することができます。これらのプロパティを所有するユーザーはいつでもプロパティを変更できることを忘れないでください。 テンプレートを作成するためのAPIエントリポイントはないため、Box Signエンジンで使用できる署名タグがすでにドキュメントに含まれている場合を除き、Boxアプリから手動でテンプレートを作成して管理する必要があります。詳細については、[構造化されたドキュメント](page://sign/technical-use-cases/sign-structured-docs)のセクションを参照してください。 **Source:** [https://ja.developer.box.com/sign/technical-use-cases/sign-template/](https://ja.developer.box.com/sign/technical-use-cases/sign-template/) --- ### リクエストのオプション **Type:** page | **Category:** Box Signの使用 | **Section:** sign リクエストのオプション Box Sign API… # リクエストのオプション Box Sign APIには、署名リクエストを送信する際のカスタマイズと構成のさまざまなオプションが用意されています。開発者はこれらのオプションを使用することで、アプリケーションに固有の要件に合わせてユーザーエクスペリエンスとワークフローをカスタマイズできます。 **Source:** [https://ja.developer.box.com/sign/request-options/](https://ja.developer.box.com/sign/request-options/) --- ### リクエストの再送信 **Type:** page | **Category:** Box Signの使用 | **Section:** sign リクエストの再送信 署名者がメールを受信できなかった場合や、メールを紛失したり、署名者が誤ってメールを削除したりした場合はどうなるでしょうか。 署名リクエストメールは、手動でsigner… # リクエストの再送信 署名者がメールを受信できなかった場合や、メールを紛失したり、署名者が誤ってメールを削除したりした場合はどうなるでしょうか。 署名リクエストメールは、手動で`signer`に再送信することも、自動再送信オプションをオンにすることもできます。 ## 手動による再送信 署名リクエストメールを手動で署名者に再送信するには、`sign_requests`オブジェクトで`resend_sign_request`メソッドを呼び出します。この操作は、10分間に1回しか実行できません。 以下に例を示します。 ``` curl --location --request POST 'https://api.box.com/2.0/sign_requests/ 52f6f86c-c0b3-401e-a4ec-1709f277c469/resend' \ --header 'Authorization: Bearer ej...3t' ``` ``` def sign_send_reminder(client: Client, sign_request_id: str): """Send reminder to signers""" sign_request = client.sign_requests.resend_sign_request(sign_request_id) return sign_request ``` ## 自動再送信 自動再送信オプションを使用すると、ドキュメントにまだ署名していない署名者に対して3日後、8日後、13日後、18日後にリマインダメールが送信されます。 自動再送信を有効にするには、`are_reminders_enabled`パラメータを`true`に設定します。以下に例を示します。 ``` curl --location 'https://api.box.com/2.0/sign_requests' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer <access token>' \ --data-raw '{ "are_reminders_enabled": true, "parent_folder": { "id": "234102987614", "type": "folder" }, "source_files": [ { "id": "1355143830404", "type": "file" } ], "signers": [ { "email": "signer@example.com", "role": "signer" } ] }' ``` ``` def sign_doc_single_more_options( client: Client, document_id: str, destination_folder_id: str, signer_email: str, prep_needed: bool = False, auto_reminder: bool = False, ) -> SignRequest: """Single doc sign by single signer""" # Sign request params source_file = FileBase(id=document_id, type=FileBaseTypeField.FILE) destination_folder = FolderMini( id=destination_folder_id, type=FolderBaseTypeField.FOLDER ) # signer signer = SignRequestCreateSigner(signer_email) # sign document sign_request = client.sign_requests.create_sign_request( signers=[signer], parent_folder=destination_folder, source_files=[source_file], is_document_preparation_needed=prep_needed, are_reminders_enabled=auto_reminder, ) return sign_request def main(): ... # Sign with redirects sign_with_auto_reminder = sign_doc_single_more_options( client, SIMPLE_PDF, SIGN_DOCS_FOLDER, SIGNER_A, prep_needed=False, auto_reminder = True, ) ``` **Source:** [https://ja.developer.box.com/sign/request-options/resend-requests/](https://ja.developer.box.com/sign/request-options/resend-requests/) --- ### リクエストの有効期限 **Type:** page | **Category:** Box Signの使用 | **Section:** sign リクエストの有効期限 場合によっては、署名リクエストの有効期限を設定する必要があります。 たとえば、3… # リクエストの有効期限 場合によっては、署名リクエストの[有効期限を設定する](https://support.box.com/hc/en-us/articles/4404105810195-Sending-a-document-for-signature#:~:text=Step%205%3A%20Setting%20an%20expiration)必要があります。 たとえば、30日間有効なサービスの見積もりを想像してみてください。この提案書には期日までに署名する必要があり、署名しなかった場合、この見積もりに対する署名リクエストは無効になります。 必要なのは、`days_valid`パラメータを渡すことだけです。 例: ``` curl --location 'https://api.box.com/2.0/sign_requests' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer ej...3t' \ --data-raw '{ "days_valid": 30, "parent_folder": { "id": "234102987614", "type": "folder" }, "source_files": [ { "id": "1358047520478", "type": "file" } ], "signers": [ { "email": "signer@example.com", "role": "signer" } ] }' ``` ``` def sign_doc_single_more_options( ... days_valid: int = None, ) -> SignRequest: ... # sign document sign_request = client.sign_requests.create_sign_request( ... days_valid=days_valid, ) return sign_request ``` **Source:** [https://ja.developer.box.com/sign/request-options/request-expiration/](https://ja.developer.box.com/sign/request-options/request-expiration/) --- ### リダイレクトURL **Type:** page | **Category:** Box Signの使用 | **Section:** sign リダイレクトURL ドキュメントに署名した後に、会社ではユーザーをお礼のページやオンボーディングページのような特定のウェブページにリダイレクトしたい場合もよくあります。このような要件をサポートする機能は… # リダイレクトURL ドキュメントに署名した後に、会社ではユーザーをお礼のページやオンボーディングページのような特定のウェブページにリダイレクトしたい場合もよくあります。このような要件をサポートする機能は2つあります。 署名者が署名プロセスを完了したときに、その署名者をウェブページにリダイレクトできます。署名者が署名リクエストを拒否した場合も同様です。 `redirect_url`パラメータと`decline_redirect_url`パラメータを渡すことで、これらのページをカスタマイズできます。 例: ``` curl --location 'https://api.box.com/2.0/sign_requests' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer ej...3t' \ --data-raw '{ "is_document_preparation_needed": true, "redirect_url": "https://community.box.com/", "declined_redirect_url": "https://developer.box.com/", "parent_folder": { "id": "234102987614", "type": "folder" }, "source_files": [ { "id": "1358047520478", "type": "file" } ], "signers": [ { "email": "signer@example.com", "role": "signer" } ] }' ``` ``` def sign_doc_single_more_options( ... redirect_url: str = None, declined_redirect_url: str = None, ) -> SignRequest: ... # sign document sign_request = client.sign_requests.create_sign_request( ... redirect_url=redirect_url, declined_redirect_url=declined_redirect_url, ) return sign_request def main(): ... # Sign with redirects sign_with_redirects = sign_doc_single_more_options( client, SIMPLE_PDF, SIGN_DOCS_FOLDER, SIGNER_A, prep_needed=False, redirect_url="https://community.box.com/", declined_redirect_url="https://developer.box.com/", ) check_sign_request(sign_with_redirects) ``` 署名した場合、フォーラムページにリダイレクトされます。拒否した場合は、開発者向けのページにリダイレクトされます。 **Source:** [https://ja.developer.box.com/sign/request-options/custom-urls/](https://ja.developer.box.com/sign/request-options/custom-urls/) --- ### 最初のリクエスト **Type:** page | **Category:** Box Signの使用 | **Section:** sign 最初のリクエスト Box… # 最初のリクエスト Boxに保存されているドキュメントがあり、署名をもらうために顧客に送信することを想像してみてください。少なくとも、アプリでは、署名対象のドキュメント、署名済みドキュメントの保存先、署名者のメールアドレスを認識する必要があります。 ## 署名リクエストの作成 署名リクエストの作成には、Box Sign APIまたは使用可能ないずれかのSDKを使用できます。次の例を参照してください。 ``` curl --location 'https://api.box.com/2.0/sign_requests' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer <access token>' \ --data-raw '{ "is_document_preparation_needed": true, "parent_folder": { "id": "234102987614", "type": "folder" }, "source_files": [ { "id": "1355143830404", "type": "file" } ], "signers": [ { "email": "signer@example.com", "role": "signer" } ] }' ``` ``` def sign_doc_single( client: Client, document_id: str, destination_folder_id: str, signer_email: str, prep_needed: bool = False, ) -> SignRequest: # Sign request params source_file = FileBase(id=document_id, type=FileBaseTypeField.FILE) destination_folder = FolderMini( id=destination_folder_id, type=FolderBaseTypeField.FOLDER ) signer = SignRequestCreateSigner(signer_email) # sign document sign_request = client.sign_requests.create_sign_request( signers=[signer], parent_folder=destination_folder, source_files=[source_file], is_document_preparation_needed=prep_needed, ) return sign_request def main(): conf = ConfigOAuth() client = get_client_oauth(conf) # Simple sign a pdf request with preparation sign_pdf_prep = sign_doc_single( client, SIMPLE_PDF, SIGN_DOCS_FOLDER, SIGNER_A, True ) if sign_pdf_prep.prepare_url is not None: open_browser(sign_pdf_prep.prepare_url) ``` この結果、ドキュメント準備のURL (簡略化されています) を含む署名リクエストが作成されます。 ``` { "is_document_preparation_needed": true, "signers": [ { "email": "requester@example.com", "role": "final_copy_reader", }, { "email": "signer@example.com", "role": "signer", } ], "id": "348decab-48a8-4f2c-9436-8967afebf7bb", "prepare_url": "https://app.box.com/sign/document/xyz-abc-123/.../prepare_doc/", "source_files": [ { "id": "1355143830404", "type": "file", } ], "parent_folder": { "id": "234102987614", "type": "folder", }, "name": "Simple-PDF.pdf", "type": "sign-request", "status": "converting", "sign_files": { "files": [ { "id": "1381301154812", "type": "file", } ], "is_ready_for_download": true }, "template_id": null } ``` ``` Simple sign request with prep: xyz-abc-123 Status: converting Signers: signer@example.com Prepare url: https://app.box.com/sign/document/xyz-abc-123/.../prepare_doc/ ``` ## 署名リクエストのステータスの確認 署名リクエストの作成は非同期処理であり、エラーが発生する可能性があります。アプリケーションでは、処理を進める前にリクエストのステータスを確認し、エラーがあれば処理する必要があります。 署名リクエストのステータスを以下に示します。 - `converting`: 署名リクエストが送信された後、ファイルが署名プロセスのために`.pdf`に変換されている。 - `error_converting`: ファイルを`.pdf`に変換中に問題が発生した。 - `created`: `document_preparation_is_needed`が`true`に設定されているが、`prepare_url`がまだアクセスされていない。 - `sent`: リクエストが正常に送信されたが、どの署名者も対応していない。 - `error_sending`: リクエストの送信中に問題が発生した。 - `viewed`: 最初 (または唯一) の署名者が署名用メールの [**ドキュメントをレビュー**] をクリックするか、署名用URLにアクセスした。 - `downloaded`: 署名者がドキュメントをダウンロードした。 - `signed`: すべての署名者がリクエストの処理を完了した。 - `signed and downloaded`: 署名者がドキュメントに署名してダウンロードした。 - `declined`: いずれかの署名者がリクエストを拒否した。 - `cancelled`: リクエストがUIまたはAPIを介してキャンセルされた。 - `expired`: 署名が未完了、不十分のまま、有効期限が過ぎた。 - `finalizing`: すべての署名者がリクエストに署名済みでも、署名された最終的なドキュメントと署名ログがまだ生成されていない。 - `error_finalizing`: `finalizing`フェーズが正常に完了しなかった。 ## ドキュメントの準備 技術的なユースケースによっては、ドキュメントの準備が必要になる場合があります。この具体的な例では、PDFに署名していますが、Box Signエンジンは、署名フィールドやその他の入力データの配置場所を認識しません。そのため、`is_document_preparation_needed`フラグを使用しました。 準備のURLが存在する場合、アプリケーションはそのURLをブラウザで開く必要があります。そこで、リクエスト送信者は、署名者がドキュメントでの作業を完了するために必要な署名フィールドやその他の入力データを追加できます。 ドキュメントが準備できたら、リクエスト送信者は署名リクエストを署名者に送信できます。 この準備手順は必須ではありません。詳細については、[技術的なユースケース](page://sign/technical-use-cases)を参照してください。 ## 署名リクエストの完了 署名者には、署名リクエストへのリンクが記載されたメールがBoxから届きます。署名者はリンクをクリックしてドキュメントに署名できます。 処理が完了すると、メタデータを含む署名ログと署名済みドキュメントの両方が保存先フォルダに格納されます。 これで、最初の署名リクエストを正常に作成できました。 これは、Box Signの基本的なユースケースを示しています。`create`メソッドには、署名リクエストのカスタマイズに使用できる多くのオプションがあります。 詳細については、[リクエストのオプション](page://sign/request-options)と[技術的なユースケース](page://sign/technical-use-cases)のセクションを確認してください。 **Source:** [https://ja.developer.box.com/sign/quick-start/your-first-request/](https://ja.developer.box.com/sign/quick-start/your-first-request/) --- ### 対面での署名 **Type:** page | **Category:** Box Signの使用 | **Section:** sign … # 対面での署名 営業担当者が顧客と対面していて、サービスへの加入や購入の確認など、即座に署名が必要になったときに、アプリケーションを使用する場合を考えてみましょう。 この場合、営業担当者はアプリケーションを使用して署名リクエストを作成した後、顧客にデバイスを手渡してドキュメントに署名してもらうことで、すぐに取引を成立させることができます。 Boxウェブアプリを使用して、例えばテンプレートからこの作業を行うことは非常に簡単です。署名者が署名済みドキュメントのコピーを受信できるように署名者 (複数可) のメールアドレスを設定し、対面での署名というフラグを設定します。リクエストを送信するとすぐに、Signのインターフェースが開き、最初の署名者に署名をリクエストし、その後、2番目の署名者、3番目の署名者のように続きます。 アプリケーション内でこれを使用するには、署名者ごとに`is_in_person`フラグを`true`に設定して署名リクエストを作成する必要があります。 ただし、アプリケーションではSignのインターフェースを署名者に表示する必要があるため、埋め込みURLが返されるように`embed_url_external_user_id`を使用してから、ブラウザウィンドウを開くか、iframeを使用して署名インターフェースを表示する必要があります。 ## 対面での署名リクエストの作成 例として、1人の署名者を設定したテンプレートを使用します。 ``` curl --location 'https://api.box.com/2.0/sign_requests' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer Le...Cb' \ --data-raw '{ "template_id": "ee9a689e-96b6-4076-92a0-b9b765eb09ca", "parent_folder": { "id": "234102987614", "type": "folder" }, "signers": [ { "email": "signer@example.com", "role": "signer", "is_in_person": true, "embed_url_external_user_id": "1234" } ] }' ``` ``` def sign_doc_in_person( client: Client, document_id: str, destination_folder_id: str, signer_email: str, signer_embed_url_id: str, ) -> SignRequest: # Sign request params source_file = FileBase(id=document_id, type=FileBaseTypeField.FILE) destination_folder = FolderMini( id=destination_folder_id, type=FolderBaseTypeField.FOLDER ) signer = SignRequestCreateSigner( email=signer_email, embed_url_external_user_id=signer_embed_url_id, is_in_person=True, ) # sign document sign_request = client.sign_requests.create_sign_request( signers=[signer], parent_folder=destination_folder, source_files=[source_file], ) return sign_request def main(): """Simple script to demonstrate how to use the Box SDK""" conf = ConfigOAuth() client = get_client_oauth(conf) # Sign with phone verification sign_with_embed_url = sign_doc_embed_url( client, SIMPLE_PDF, SIGN_DOCS_FOLDER, SIGNER_A, SIGNER_A_EXTERNAL_ID, ) check_sign_request(sign_with_embed_url) ``` 結果は次のとおりです (簡略化されています)。 ``` { "signers": [ { "email": "sender@example.com", "role": "final_copy_reader", "is_in_person": false, }, { "email": "signer@example.com", "role": "signer", "is_in_person": true, "embed_url_external_user_id": "1234", "embed_url": "https://app.box.com/sign/document/...", "iframeable_embed_url": "https://app.box.com/embed/sign/document/..." } ], "id": "a9159d31-d2fb-4e88-9306-02c00de013d1", "parent_folder": { "id": "234102987614", "type": "folder", "name": "signed docs" }, "name": "Simple-PDF (1).pdf", "type": "sign-request", "status": "created", "template_id": "ee9a689e-96b6-4076-92a0-b9b765eb09ca" } ``` ``` Simple sign request: a9159d31-d2fb-4e88-9306-02c00de013d1 Status: created Signers: 2 final_copy_reader: sender@example.com signer: signer@example.com embed_url: https://app.box.com/sign/document/... iframeable_embed_url: https://app.box.com/embed/sign/document/... Prepare url: None ``` レスポンスの`embed_url`と`iframeable_embed_url`に注目してください。埋め込みURLを参照すると、署名インターフェースが表示されます。 署名が完了すると、署名者には署名済みドキュメントのコピーがメールで送信されます。 ## 複数の署名者による対面での署名 署名者に`is_in_person`というフラグが設定されている限り、リクエストに含まれるすべての署名者に署名インターフェースが繰り返されます。 たとえば、リクエストに2人目の署名者を追加する場合は、次のようになります。 ``` curl --location 'https://api.box.com/2.0/sign_requests' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer Le...Cb' \ --data-raw '{ "template_id": "ee9a689e-96b6-4076-92a0-b9b765eb09ca", "parent_folder": { "id": "234102987614", "type": "folder" }, "signers": [ { "email": "signer_a@example.com", "role": "signer", "is_in_person": true, "embed_url_external_user_id": "1234" }, { "email": "signer_b@example.com", "role": "signer", "is_in_person": true } ] }' ``` ``` def sign_doc_in_person_multiple( client: Client, document_id: str, destination_folder_id: str, signer_a_email: str, signer_a_embed_url_id: str, signer_b_email: str, ) -> SignRequest: # Sign request params source_file = FileBase(id=document_id, type=FileBaseTypeField.FILE) destination_folder = FolderMini( id=destination_folder_id, type=FolderBaseTypeField.FOLDER ) signer_a = SignRequestCreateSigner( email=signer_email, embed_url_external_user_id=signer_embed_url_id, is_in_person=True, ) signer_b = SignRequestCreateSigner( email=signer_email, is_in_person=True, ) # sign document sign_request = client.sign_requests.create_sign_request( signers=[signer_a, signer_b], parent_folder=destination_folder, source_files=[source_file], ) return sign_request def main(): """Simple script to demonstrate how to use the Box SDK""" conf = ConfigOAuth() client = get_client_oauth(conf) # Sign with phone verification sign_with_embed_url = sign_doc_embed_url( client, SIMPLE_PDF, SIGN_DOCS_FOLDER, SIGNER_A, SIGNER_A_EXTERNAL_ID, SIGNER_B ) check_sign_request(sign_with_embed_url) ``` 結果は次のとおりです (簡略化されています)。 ``` { "signers": [ { "email": "sender@example.com", "role": "final_copy_reader", "is_in_person": false, }, { "email": "signer_a@example.com", "role": "signer", "is_in_person": true, "embed_url": "https://app.box.com/sign/document/...", "iframeable_embed_url": "https://app.box.com/embed/sign/document/..." }, { "email": "signer_b@example.com", "role": "signer", "is_in_person": true, "embed_url": null, "iframeable_embed_url": null } ], "id": "d066575f-f22b-42fc-b9e2-701468776475", "parent_folder": { "id": "234102987614", "type": "folder", "name": "signed docs" }, "name": "Simple-PDF (3).pdf", "type": "sign-request", "status": "created", "template_id": "ee9a689e-96b6-4076-92a0-b9b765eb09ca" } ``` ``` Simple sign request: d066575f-f22b-42fc-b9e2-701468776475 Status: created Signers: 3 final_copy_reader: sender@example.com signer: signer_a@example.com embed_url: https://app.box.com/sign/document/... iframeable_embed_url: https://app.box.com/embed/sign/document/... signer: signer_b@example.com Prepare url: None ``` 埋め込みURLを参照すると、最初の署名者に署名インターフェースが表示されます。 最初の署名者が署名すると、署名インターフェースは自動的に2番目の署名者に切り替わります。 **Source:** [https://ja.developer.box.com/sign/request-options/in-person/](https://ja.developer.box.com/sign/request-options/in-person/) --- ### 技術的なユースケース **Type:** page | **Category:** Box Signの使用 | **Section:** sign 技術的なユースケース アプリケーションでは、多くのソースからのさまざまなドキュメントに署名することになります。このようなドキュメントをBox Sign… # 技術的なユースケース アプリケーションでは、多くのソースからのさまざまなドキュメントに署名することになります。このようなドキュメントをBox Signサービスに認識させるためにアプリケーションでどのように処理すればよいのでしょうか。 署名リクエストには、従来の署名 (名前、日付、イニシャルなど) 以外に、複数の要件 (入力データ) を設定することができます。こうした入力データは署名プロパティと呼ばれます。Box Signサービスでは、これらの入力データをドキュメント内のどこに配置し、どのように認識するかを把握しておく必要があります。 最初の手順として、Box Signサービスが署名プロパティを認識するために必要な情報をドキュメントに含めるかどうかを検討します。 含めない場合、[ドキュメントは構造化されていない](page://sign/technical-use-cases/sign-unstructured-docs)ので、署名リクエストを送信する前に準備する必要があります。これはドキュメントの準備と呼ばれ、Box Signサービスによって自動的に作成される追加の手順です。 Box Signサービスが署名プロパティを認識するために必要な情報をすでに含んでいるドキュメントは、他に2種類あります。1つは、Boxアプリケーションで管理される[Signテンプレート](page://sign/technical-use-cases/sign-template)で、もう1つは[構造化されたドキュメント](page://sign/technical-use-cases/sign-structured-docs)です。構造化されたドキュメントは、署名プロパティを表す特定のタグを含む、動的に生成されるドキュメントです。 非構造化ドキュメントへの署名 **Source:** [https://ja.developer.box.com/sign/technical-use-cases/](https://ja.developer.box.com/sign/technical-use-cases/) --- ### 構造化されたドキュメントへの署名 **Type:** page | **Category:** Box Signの使用 | **Section:** sign 構造化されたドキュメントへの署名 Box Signのコンテキストにおける構造化されたドキュメントとは、Box Sign API… # 構造化されたドキュメントへの署名 Box Signのコンテキストにおける構造化されたドキュメントとは、Box Sign APIが認識できる特殊なタグを含むドキュメントのことです。これらのタグは、特定の署名者に関連付けられた署名プロパティ (名前、日付、署名など) をドキュメント内に配置するために使用されます。 これにより、アプリでは、署名の準備が整った、動的に生成されたドキュメントを処理できます。これには、いくつかの利点があります。 ドキュメントを動的に生成できます。また、署名リクエストを作成する前に署名プロパティをドキュメントに追加できるため、実質的にドキュメントの準備手順を省略できます。 ドキュメントの形式はBox Signテンプレートの外部で処理できるため、柔軟性が高まり、外部のドキュメント管理システムとの統合が可能になります。 ## 構造化されたドキュメントの詳細 構造化されたドキュメントの例を以下に示します。この例では、Microsoft Wordドキュメントにタグを配置する際に使用される書式を示しています。 上の例では、`[[c|1]]`は署名者1に割り当てられたチェックボックスを指し、`[[s| 1]]`は署名者1に割り当てられた署名パッドを指します。署名パッドでフォントサイズ48を使用して、署名用のスペースを縦方向に確保していることに注目してください。 `[[t|1|id:tag_full_name|n:enter your complete name]]`は、ラベル`enter your complete name`とID `tag_full_name`を使用して、署名者1に割り当てられた名前タグを指します。 利用可能なすべてのタグの詳細な説明については、こちらの[ドキュメント](https://support.box.com/hc/en-us/articles/4404085855251-Creating-templates-using-tags)を参照してください。 タグを背景と同じ`color`に設定すると、タグは見えなくなりますが、そこに存在はしています。 タグ内の番号は、署名の順序ではなく、署名者の番号を指すため、`[[c|1]]`は署名者1のチェックボックス、`[[c|2]]`は署名者2のチェックボックスのようになります。 タグ0は送信者用に予約されており、必ず存在します。そのため、送信者がドキュメントにデータを入力する必要がない場合でも、他の署名者には1以降の番号を割り当てる必要があります。 ## 構造化されたドキュメントからの署名リクエストの作成 これは、非構造化ドキュメントから署名リクエストを作成する場合と同じです。少なくとも、ドキュメント、受信用フォルダ、および`signer`のメールアドレスを指定する必要があります。 構造化されたドキュメントにはすでに署名プロパティの詳細と場所が含まれているため、ドキュメントの準備は省略できます。 このフローは次のようになり、ドキュメントの生成から始まり、署名リクエストを作成して、最後にドキュメントに署名します。 次のメソッドを考えてみましょう。 ``` curl --location 'https://api.box.com/2.0/sign_requests' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer nQ...xY' \ --data-raw '{ "source_files": [ { "type": "file", "id": "1363379762284" } ], "parent_folder": { "id": "234102987614", "type": "folder" }, "signers": [ { "email": "signer@example.com", "role": "signer" } ] }' ``` ``` def create_sign_request_structured( client: Client, file_id: str, signer_email: str ) -> SignRequest: """Create a sign request with structured data""" # Sign request params source_file = FileBase(id=file_id, type=FileBaseTypeField.FILE) parent_folder = FolderMini( id=SIGN_DOCS_FOLDER, type=FolderBaseTypeField.FOLDER ) signer = SignRequestCreateSigner(signer_email) # Create a sign request sign_request = client.sign_requests.create_sign_request( signers=[signer], parent_folder=parent_folder, source_files=[source_file], ) return sign_request def main(): ... # Create a sign request with structured data sign_request = create_sign_request_structured( client, STRUCTURED_DOC, SIGNER_A ) check_sign_request(sign_request) ``` 結果は次のとおりです (簡略化されています)。 ``` { "is_document_preparation_needed": false, "signers": [ { "email": "sender@example.com", "role": "final_copy_reader", }, { "email": "signer@example.com", "role": "signer", } ], "id": "28199d6c-4662-471e-8426-4cbba9affcf1", "source_files": [ { "id": "1363379762284", "type": "file", "name": "Box-Dive-Waiver.docx", } ], "parent_folder": { "id": "234102987614", "type": "folder", "name": "signed docs" }, "name": "Box-Dive-Waiver.pdf", "type": "sign-request", "status": "converting", "sign_files": { "files": [ { "id": "1393138856442", "type": "file", "name": "Box-Dive-Waiver.pdf", } ], }, } ``` ``` Simple sign request: 6878e048-e9bd-4fb1-88c6-8e502783e8d0 Status: converting Signers: 2 final_copy_reader: sender@example.com signer: signer@example.com Prepare url: None ``` **署名者**のメールの受信トレイに移動し、Box Signからのメールを開き、[**ドキュメントをレビュー**] ボタンをクリックすると、署名プロパティが所定の位置に配置されているドキュメントが表示されます。 処理を完了すると、署名済みドキュメントは次のようになります。 ## 署名の属性の事前入力 ドキュメントのタグに外部IDが設定されている場合は、その外部IDを使用して値を事前入力できます。たとえば、`tag_full_name`を使用して署名者の名前を事前に入力できます。 次のメソッドを確認してください。 ``` curl --location 'https://api.box.com/2.0/sign_requests' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer nQ...xY' \ --data-raw '{ "prefill_tags": [ { "document_tag_id": "tag_full_name", "text_value": "Signer A" } ], "source_files": [ { "type": "file", "id": "1363379762284" } ], "parent_folder": { "id": "234102987614", "type": "folder" }, "signers": [ { "email": "signer@example.com", "role": "signer" } ] }' ``` ``` def create_sign_request_structured_with_prefill( client: Client, file_id: str, signer_name, signer_email: str ) -> SignRequest: """Create a sign request with structured data""" # Sign request params source_file = FileBase(id=file_id, type=FileBaseTypeField.FILE) parent_folder = FolderMini( id=SIGN_DOCS_FOLDER, type=FolderBaseTypeField.FOLDER ) signer = SignRequestCreateSigner(signer_email) # tags tag_full_name = SignRequestPrefillTag( document_tag_id="tag_full_name", text_value=signer_name, ) # Create a sign request sign_request = client.sign_requests.create_sign_request( signers=[signer], parent_folder=parent_folder, source_files=[source_file], prefill_tags=[tag_full_name], ) return sign_request def main(): ... # Create a sign request with name pre populate sign_request_pre_pop = create_sign_request_structured_with_prefill( client, STRUCTURED_DOC, "Signer A", SIGNER_A ) check_sign_request(sign_request_pre_pop) ``` 結果は次のとおりです (簡略化されています)。 ``` { "is_document_preparation_needed": false, "redirect_url": null, "declined_redirect_url": null, "are_text_signatures_enabled": true, "signature_color": null, "is_phone_verification_required_to_view": false, "email_subject": null, "email_message": null, "are_reminders_enabled": false, "signers": [ { "email": "sender@example.com", "role": "final_copy_reader", }, { "email": "signer@example.com", "role": "signer", } ], "id": "11ecebc0-a2b2-4c14-a892-3f56333cc4fa", "prefill_tags": [ { "document_tag_id": "tag_full_name", "text_value": "Signer A", } ], "source_files": [ { "id": "1363379762284", "type": "file", "name": "Box-Dive-Waiver.docx", } ], "parent_folder": { "id": "234102987614", "type": "folder", "name": "signed docs" }, "name": "Box-Dive-Waiver (1).pdf", "type": "sign-request", "status": "converting", "sign_files": { "files": [ { "id": "1393142670032", "type": "file", "name": "Box-Dive-Waiver (1).pdf", } ], }, } ``` ``` Simple sign request: 7b86e46c-72ba-4568-a6ff-787077cca007 Status: converting Signers: 2 final_copy_reader: sender@example.com signer: signer@example.com Prepare url: None ``` これで、ドキュメントには名前が事前入力されるようになりました。 ## 署名済みドキュメントからの情報の抽出 たとえば、署名者の名前とその他のプロパティを署名済みドキュメントから抽出したいとします。これは、署名リクエストの情報を再度システムに紐付ける必要がある場合に便利です。 署名済みリクエストから情報を抽出するメソッドを作成しましょう。 ``` curl --location 'https://api.box.com/2.0/sign_requests/ 11ecebc0-a2b2-4c14-a892-3f56333cc4fa' \ --header 'Authorization: Bearer nQ...xY' ``` ``` def check_sign_request_by_id(client: Client, sign_request_id: str): """Check sign request by id""" sign_request = client.sign_requests.get_sign_request_by_id(sign_request_id) print(f"\nSimple sign request: {sign_request.id}") print(f" Status: {sign_request.status.value}") print(f" Signers: {len(sign_request.signers)}") for signer in sign_request.signers: print(f" {signer.role.value}: {signer.email}") for input in signer.inputs: content_type = input.content_type value = None if content_type == SignRequestSignerInputTypeField.CHECKBOX: value = input.checkbox_value elif content_type == SignRequestSignerInputTypeField.TEXT: value = input.text_value elif content_type == SignRequestSignerInputTypeField.DATE: value = input.date_value print( f" {input.type.value}: {value if value is not None else '<other>'}" ) print(f" Prepare url: {sign_request.prepare_url}") def main(): ... # Latest sign request LATEST_SIGN_REQUEST = "7b86e46c-72ba-4568-a6ff-787077cca007" check_sign_request_by_id(client, LATEST_SIGN_REQUEST) ``` 結果は次のとおりです (簡略化されています)。 ``` { "signers": [ { "email": "sender@example.com", "role": "final_copy_reader", }, { "email": "signer@example.com", "role": "signer", "signer_decision": { "type": "signed", "finalized_at": "2023-12-19T14:53:10.547Z", }, "inputs": [ { "document_tag_id": null, "checkbox_value": true, "type": "checkbox", "content_type": "checkbox", }, { "document_tag_id": "tag_full_name", "text_value": "Signer A", "type": "text", "content_type": "text", }, { "document_tag_id": null, "text_value": "Dec 19, 2023", "date_value": "2023-12-19", "type": "date", "content_type": "date", }, { "document_tag_id": null, "type": "signature", "content_type": "signature", } ], } ], "id": "11ecebc0-a2b2-4c14-a892-3f56333cc4fa", "prefill_tags": [ { "document_tag_id": "tag_full_name", "text_value": "Signer A", } ], "source_files": [ { "id": "1363379762284", "type": "file", "name": "Box-Dive-Waiver.docx", } ], "parent_folder": { "id": "234102987614", "type": "folder", "name": "signed docs" }, "name": "Box-Dive-Waiver (1).pdf", "type": "sign-request", "signing_log": { "id": "1393140642252", "type": "file", "name": "Box-Dive-Waiver (1) Signing Log.pdf", }, "status": "signed", "sign_files": { "files": [ { "id": "1393142670032", "type": "file", "name": "Box-Dive-Waiver (1).pdf", } ], }, } ``` ``` Simple sign request: 7b86e46c-72ba-4568-a6ff-787077cca007 Status: signed Signers: 2 final_copy_reader: sender@example.com signer: signer@example.com checkbox: True text: Rui Barbosa date: 2023-11-15 signature: <other> Prepare url: None ``` ## まとめ 構造化されたドキュメントの使用は、外部のドキュメント管理システムと統合して、署名可能な動的ドキュメントを作成するのに最適です。 ドキュメントの署名要件に多くの選択肢がある場合は、別のデータソースからこれらを事前に入力して、ユーザーの時間を節約することができます。ただし、これらのプロパティを所有するユーザーはいつでもプロパティを変更できます。 ドキュメントが署名された後に署名リクエストから情報を抽出することができるので、その情報を再度システムに紐付ける必要がある場合に便利です。 **Source:** [https://ja.developer.box.com/sign/technical-use-cases/sign-structured-docs/](https://ja.developer.box.com/sign/technical-use-cases/sign-structured-docs/) --- ### 複数の署名者と役割 **Type:** page | **Category:** Box Signの使用 | **Section:** sign 複数の署名者と役割 複数の署名者 複数の人に署名してもらう必要があるドキュメントがある場合はどうなるでしょうか。これは、2つ以上の事業体の間で結ばれる契約でよく見られます。 複数の署名者を設定すると、Box Sign… # 複数の署名者と役割 ## 複数の署名者 複数の人に署名してもらう必要があるドキュメントがある場合はどうなるでしょうか。これは、2つ以上の事業体の間で結ばれる契約でよく見られます。 複数の署名者を設定すると、Box Signのプロセスには、署名者がドキュメントに署名する順序という別の要素が導入されます。 順序を指定しない場合、リクエストは全員に同時に送信されます。さらに、関係者全員がドキュメントへの署名を完了すると、各関係者は、すべての署名を含むコピーを受け取ります。 署名の順序を指定すると、署名リクエストは最初の署名者に送信されます。最初の署名者がドキュメントに署名した場合にのみ、このリクエストは2番目の署名者に送信されます (それ以降も同様)。 大学と学生の間で交わされる奨学金の契約の例を使用してこの仕組みを見てみましょう。この場合は、教育機関/教員が最初にドキュメントに署名する必要があります。 このためのメソッドを作成します。 ``` curl --location 'https://api.box.com/2.0/sign_requests' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer ej...3t' \ --data-raw '{ "is_document_preparation_needed": true, "parent_folder": { "id": "234102987614", "type": "folder" }, "source_files": [ { "id": "1358047520478", "type": "file" } ], "signers": [ { "email": "institution@example.com", "role": "signer", "order": 1 }, { "email": "student@example.com", "role": "signer", "order": 2 }, ] }' ``` ``` def sign_contract( client: Client, document_id: str, destination_folder_id: str, institution_email: str, student_email: str, prep_needed: bool = False, ) -> SignRequest: """Sign contract""" # Sign request params source_file = FileBase(id=document_id, type=FileBaseTypeField.FILE) destination_folder = FolderMini( id=destination_folder_id, type=FolderBaseTypeField.FOLDER ) # signers institution = SignRequestCreateSigner( email=institution_email, role=SignRequestCreateSignerRoleField.SIGNER, order=1, ) student = SignRequestCreateSigner( email=student_email, role=SignRequestCreateSignerRoleField.SIGNER, order=2, ) # create sign request sign_request = client.sign_requests.create_sign_request( signers=[institution, student], parent_folder=destination_folder, source_files=[source_file], is_document_preparation_needed=prep_needed, ) return sign_request def main(): ... # Multiple signers sign_contract_multi = sign_contract( client, CONTRACT, SIGN_DOCS_FOLDER, institution_email=SIGNER_A, student_email=SIGNER_B, prep_needed=True, ) if sign_contract_multi.prepare_url is not None: open_browser(sign_contract_multi.prepare_url) ``` この例では、ドキュメントを準備する必要があるため、ブラウザで準備のURLを開きます。 署名パッド、フルネーム、日付をドキュメント内の適切な場所にドラッグし、[リクエストの送信] をクリックします。 この時点で2人の署名者が設定され、順序もすでに指定されていることに注目してください。また、`color`は署名者を識別するために重要で (この場合、教育機関は青、教員は緑)、どの署名者にどの署名パッド、名前、日付が属しているかを特定します。 署名リクエストの詳細を確認すると、次のように表示されます。 最初のリクエストは送信済みですが、2番目のリクエストは最初のリクエストが完了するのを待っていることを示します。 先に進み、両方の署名者の署名プロセスを完了します。 2番目のリクエストを受け取った時点で、すでに最初の署名者は署名済みであることに注意してください。 ## ロール ここまでは、役割として`signer`を使用してきましたが、署名プロセスのカスタマイズに使用できる[他の役割](https://support.box.com/hc/en-us/articles/4404105660947-Roles-for-signers)もあります。 使用可能な役割は、`signer`、`approver`、`final copy reader`です。 開発者の視点から見ると、これは以下を意味します。 **signer (署名者)**: ドキュメントにデータを追加できる人。これには、署名、イニシャル、日付の追加だけでなく、署名が含まれていなくても、テキストフィールド、チェックボックス、ラジオボタンへの入力も含まれます。 **approver (承認者)**: この役割は、署名リクエストを承認するかどうかを尋ねられます。この承認は、準備手順の前 (有効な場合) およびリクエストが署名者に送信される前に行われます。この役割は、ドキュメントを署名者に送信する前に誰かから承認を得る必要がある場合に便利です。 **final copy reader (最終的なコピー受信者)**: この役割は、署名プロセスには関与しませんが、署名済みドキュメントのコピーを受け取ります。 役割を使用して、この奨学金の例ではもう少し工夫してみましょう。 奨学金は学部長による承認が必要であることと、法務部門が契約書の最終的なコピーを受け取ることを想像してみてください。 フローは署名リクエストで始まり、学部長による承認、教育機関による署名、学生による署名と続き、最後に、法務部門が署名済みドキュメントのコピーを受け取ります。 このためのメソッドを作成しましょう。 ``` curl --location 'https://api.box.com/2.0/sign_requests' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer ej...3t' \ --data-raw '{ "is_document_preparation_needed": true, "parent_folder": { "id": "234102987614", "type": "folder" }, "source_files": [ { "id": "1358047520478", "type": "file" } ], "signers": [ { "email": "institution@example.com", "role": "signer", "order": 1 }, { "email": "student@example.com", "role": "signer", "order": 2 }, { "email": "dean@example.com", "role": "approver" }, { "email": "legal@example.com", "role": "final_copy_reader" } ] }' ``` ``` def sign_contract_step( client: Client, document_id: str, destination_folder_id: str, institution_email: str, student_email: str, dean_email: str, legal_email: str, ) -> SignRequest: """Sign contract""" # Sign request params source_file = FileBase(id=document_id, type=FileBaseTypeField.FILE) destination_folder = FolderMini( id=destination_folder_id, type=FolderBaseTypeField.FOLDER ) # signers institution = SignRequestCreateSigner( email=institution_email, role=SignRequestCreateSignerRoleField.SIGNER, order=1, ) student = SignRequestCreateSigner( email=student_email, role=SignRequestCreateSignerRoleField.SIGNER, order=2, ) dean = SignRequestCreateSigner( email=dean_email, role=SignRequestCreateSignerRoleField.APPROVER, ) legal = SignRequestCreateSigner( email=legal_email, role=SignRequestCreateSignerRoleField.FINAL_COPY_READER, ) # create sign request sign_request = client.sign_requests.create_sign_request( signers=[institution, student, dean, legal], parent_folder=destination_folder, source_files=[source_file], is_document_preparation_needed=True, ) return sign_request def main(): ... # Multiple signers and steps sign_contract_multi_step = sign_contract_step( client, CONTRACT, SIGN_DOCS_FOLDER, institution_email=SIGNER_A, student_email=SIGNER_B, dean_email=APPROVER, legal_email=FINAL_COPY, ) if sign_contract_multi_step.prepare_url is not None: open_browser(sign_contract_multi_step.prepare_url) ``` 先ほどと同様、ドキュメントを準備する必要があるため、ブラウザで準備のURLを開きます。 この例では、教育機関が左側に青で示され、学生が右側に緑で示されており、どちらも署名者であることに注目してください。 `approver`にも`final copy reader`にも入力データを関連付けることはできません。関連付けると、その役割は`signer`に変更されます。 署名プロセスを続行します。 - 学部長が奨学金を承認する - 教育機関が奨学金に署名する - 学生が奨学金に署名する - 法務部門が署名済みドキュメントのコピーを受け取る **Source:** [https://ja.developer.box.com/sign/request-options/multiple-signers/](https://ja.developer.box.com/sign/request-options/multiple-signers/) --- ### 非構造化ドキュメントへの署名 **Type:** page | **Category:** Box Signの使用 | **Section:** sign … # 非構造化ドキュメントへの署名 ユーザーがドキュメントをアップロードし、誰にでもそのドキュメントへの署名を依頼できるドキュメント管理アプリを想像してみてください。この場合、アプリは、署名対象のドキュメントと署名する必要がある人を認識しますが、署名やそのプロパティ (名前、日付、イニシャルなど) を配置する場所は認識しません。 これは、[テンプレート](page://sign/technical-use-cases/sign-template)や[構造化されたドキュメント](page://sign/technical-use-cases/sign-structured-docs)を使用する場合とは対照的です。これらを使用する場合、アプリは、署名プロパティの内容や場所を認識します。 このような場合、各ドキュメントに異なる構造を使用できるため、常に`is_document_preparation_needed`フラグを`true`に設定することをお勧めします。これにより、署名者がリクエストを受け取る前に、送信者は署名プロパティを選択してドキュメントに配置できるようになります。 このフローには、署名リクエストの作成、ドキュメントの準備、署名という3つのステップがあります。フローは次のようになります。 次の例を考えてみます。 ``` curl --location 'https://api.box.com/2.0/sign_requests' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer <access token>' \ --data-raw '{ "is_document_preparation_needed": true, "parent_folder": { "id": "234102987614", "type": "folder" }, "source_files": [ { "id": "1355143830404", "type": "file" } ], "signers": [ { "email": "signer@example.com", "role": "signer" } ] }' ``` ``` def sign_doc_single( client: Client, document_id: str, destination_folder_id: str, signer_email: str, prep_needed: bool = False, ) -> SignRequest: # Sign request params source_file = FileBase(id=document_id, type=FileBaseTypeField.FILE) destination_folder = FolderMini( id=destination_folder_id, type=FolderBaseTypeField.FOLDER ) signer = SignRequestCreateSigner(signer_email) # sign document sign_request = client.sign_requests.create_sign_request( signers=[signer], parent_folder=destination_folder, source_files=[source_file], is_document_preparation_needed=prep_needed, ) return sign_request def main(): conf = ConfigOAuth() client = get_client_oauth(conf) # Simple sign a pdf request with preparation sign_pdf_prep = sign_doc_single( client, SIMPLE_PDF, SIGN_DOCS_FOLDER, SIGNER_A, True ) if sign_pdf_prep.prepare_url is not None: open_browser(sign_pdf_prep.prepare_url) ``` これの結果、ドキュメント準備のURL (簡略化されています) を含む署名リクエストが作成されます。 ``` { "is_document_preparation_needed": true, "signers": [ { "email": "requester@example.com", "role": "final_copy_reader", }, { "email": "signer@example.com", "role": "signer", } ], "id": "348decab-48a8-4f2c-9436-8967afebf7bb", "prepare_url": "https://app.box.com/sign/document/xyz-abc-123/.../prepare_doc/", "source_files": [ { "id": "1355143830404", "type": "file", } ], "parent_folder": { "id": "234102987614", "type": "folder", }, "name": "Simple-PDF.pdf", "type": "sign-request", "status": "converting", "sign_files": { "files": [ { "id": "1381301154812", "type": "file", } ], "is_ready_for_download": true }, "template_id": null } ``` ``` Simple sign request with prep: xyz-abc-123 Status: converting Signers: signer@example.com Prepare url: https://app.box.com/sign/document/xyz-abc-123/.../prepare_doc/ ``` 上記のスクリプトでは、ドキュメント準備のURLが署名リクエストによって生成された場合、アプリによってそのURLのためにブラウザが開くことに注意してください。その後、リクエスト送信者は、次のようにさまざまな署名プロパティを適用できます。 ドキュメントが準備できたら、リクエスト送信者は署名リクエストを署名者に送信できます。 Boxアプリに戻ると、ステータスが`In Progress`になっていることがわかります。 その後、署名リクエストへのリンクが記載されたメールがBoxから署名者に送信されます。 処理が完了すると、メタデータを含む署名ログと署名済みドキュメントの両方が保存先フォルダに格納されます。 **Source:** [https://ja.developer.box.com/sign/technical-use-cases/sign-unstructured-docs/](https://ja.developer.box.com/sign/technical-use-cases/sign-unstructured-docs/)