新しいBox .NET SDKの使用
Boxは最近、新しい.NET SDKをリリースしました。このSDKは、APIを全面的にカバーし、生成されたSDKという性質のおかげで迅速かつ予測可能な更新が可能になり、以前の.NET SDKよりもさらに使いやすくなります。また、このSDKは、最近Nugetにも公開されたため、その機能を最大限に活用する方法を学ぶには絶好のタイミングです。
前提条件
[アプリアクセスレベル] を [アプリ + Enterpriseアクセス] に設定してBoxカスタムJWTアプリを作成します。この作成方法については、Olga StefaniukのJWT認証に関する記事 (翻訳) を確認してください。また、Boxアプリで使用できる他の認証方法に興味がある場合は、Alex Novotnyの記事Box Platformの基本: 認証方法の基礎 (翻訳) を確認してください。
以下のスコープを有効にしていることを確認します。
- Boxに格納されているすべてのファイルとフォルダの読み取り
- ユーザーを管理する
[高度な機能] で [ユーザーアクセストークンを生成する] をオンにします。
また、管理コンソールでこれらの設定を有効にした後は、必ずアプリケーションを再承認してください。
Microsoftの公式ウェブサイトから入手できる.NET SDKも必要です。現在、新しい.NET SDKでは、.NETバージョン6以降がサポートされています。利用しているオペレーティングシステムに応じて、Build apps — SDKセクションから適切なインストーラをダウンロードして実行する必要があります。
Visual StudioはC# .NETアプリケーションの作成に推奨されるIDEですが、必須ではないため、ご自身に最適なIDEをご利用いただけます。
.NETアプリケーションの設定
新しいコンソールアプリケーションを作成するには、ターミナルで次のコマンドを実行します。
dotnet new console --framework net6.0 --name BoxWithNextGenSDKこのコマンドにより、同じ名前で新しいフォルダが作成されます。このフォルダ内には、BoxWithNextGenSDK.csprojプロジェクトファイルのほか、コンソールアプリケーションのエントリポイントであるmain関数を含むProgram.csがあります。コンピュータにインストールされている.NETのバージョンに応じて、framework引数には異なるバージョンの.NETを指定できます。
このフォルダに移動し、次のコマンドを実行してBox.Sdk.Genをパッケージの依存関係として追加します。
dotnet add package Box.Sdk.Gen最後に、このアプリケーションを実行して、すべてが正常に動作することを確認します。
dotnet runターミナルに次の出力が表示されます。
Hello, World!生成した新しい.NET SDKとJWTの使用
Box開発者コンソールの [構成] タブで [公開/秘密キーペアを生成] をクリックして、JWTの構成をダウンロードします。
ダウンロードしたファイルの名前をconfig.jsonに変更し、新しく作成した.NETコンソールアプリケーションのルートフォルダに配置します。
次のコードをBoxWithNextGenSdk.csprojに追加して、構成ファイルがコンパイル出力に含まれるようにします。
<ItemGroup>
<None Update="config.json">
<CopyToOutputDirectory>Always</CopyToOutputDirectory>
</None>
</ItemGroup>⚠️ 注: 秘密情報をプレーンテキストで追加することは、ユースケースによっては危険な場合があります。安全に保管するための他の方法をぜひ検討してください。
新しいBox .NET SDKの使用を開始するには、Program.csファイルの先頭にusingディレクティブを追加します。
using Box.Sdk.Gen;新しいSDKでは、提供される名前空間の数が減るため、使用する必要があるusingディレクティブは以前よりも少なくなります。より便利なのは、すべてのリクエストモデルとレスポンスモデルを含むBox.Sdk.Gen.Schemasと、特定のAPI機能に関連した関数へのアクセスに使用されるすべてのマネージャを含むBox.Sdk.Gen.Managersです。
ファイルから変数に構成を読み込むには、既存の.NET APIを使用できます。
var path = "config.json";
var json = File.ReadAllText(path);新しい.NET SDKには、使いやすくするために便利な関数が多数用意されています。その中には、json文字列から直接構成を読み込むことができる関数もあります。
var jwtConfig = JwtConfig.FromConfigJsonString(json);次に、Box APIとの通信時に使用する認証方法を決定する、Authクラスのインスタンスを作成します。選択した認証方法によっては、別のクラスを使用する必要があります。
var auth = new BoxJwtAuth(jwtConfig);最後に、BoxClientのインスタンスを作成します。これは、Box APIとの通信に使用するSDKの中心的な部分となります。
var client = new BoxClient(auth: auth);SDKを使用してBox APIと通信できるかどうかを確認するには、現在のユーザーの名前を表示するシンプルなAPIコールを実行してみてください。
var me = await client.Users.GetUserMeAsync();
Console.WriteLine($"Hello, {me.Name}!");このコードを実行すると、Boxアプリケーション名を含む出力が表示されます。dotnet runコマンドを使用してアプリケーションを実行します。
Hello, BoxWithNextGenSDK!構成ファイルにenterpriseIdが存在する場合、SDKは企業としての認証を試みます。これは、リクエストのsubクレームがenterpriseで、subject_idがenterpriseIdというデフォルトの設定によります。
別のユーザー (管理対象ユーザーなど) として操作する場合は、そのユーザーのuserIdを使用して、前に作成した既存のauthオブジェクトを複製し、それを使用してBoxClientの新しいインスタンスを作成できます。
var userClient = new BoxClient(auth.AsUser("user_id"));
var managedUser = await userClient.Users.GetUserMeAsync();
Console.WriteLine($"Hello, {managedUser.Name}!");さまざまな認証方法の使用方法については、認証のドキュメントを確認してください。
フォルダ項目の取得
この記事で最後に説明するのは、特定のフォルダ内のすべての項目を取得する方法です。以下のコードサンプルは、ルートフォルダからデータを取得する場合を示しています。
var folderItems = await userClient.Folders.GetFolderItemsAsync("0");
if (folderItems.Entries != null)
{
foreach (var item in folderItems.Entries)
{
if (item.FolderMini != null)
{
Console.WriteLine($"Folder: {item.FolderMini.Name}");
}
else if (item.FileFull != null)
{
Console.WriteLine($"File: {item.FileFull.Name}");
}
else if (item.WebLink != null)
{
Console.WriteLine($"WebLink: {item.WebLink.Name}");
}
else
{
Console.WriteLine($"Unknown item: {item}");
}
}
}出力の例は次のようになります。
Folder: My Box Notes
Folder: My Stuff
File: logs.txt
File: report.pdfGetFolderItemsAsyncを呼び出すと、特定のフォルダ内のすべての項目が含まれるEntriesのコレクションを含むオブジェクトが返されます。各項目は、フォルダ、ファイル、またはウェブリンクになります。これはプロパティに基づいて決まります。つまり、プロパティの対応する値がnull値に設定されていない場合は、その種類の項目であることを意味します。対応するプロパティの値がnullに設定されている場合は、オブジェクトがその種類ではないため、他のプロパティをnull値と比較する必要があることを意味します。
この方法は、単一のコレクションまたはプロパティでさまざまな種類の要素が返される場合に、SDKを通して確認できます。
以上です。新しい生成された.NET SDK の詳細については、GitHubページを参照するか、こちらのドキュメントを確認してください。古いBox .NET SDKから移行する場合は、移行ガイドを参照してください。
Program.csのソースコード:
using Box.Sdk.Gen;
var path = "config.json";
var json = File.ReadAllText(path);
var jwtConfig = JwtConfig.FromConfigJsonString(json);
var auth = new BoxJwtAuth(jwtConfig);
var client = new BoxClient(auth: auth);
var me = await client.Users.GetUserMeAsync();
Console.WriteLine($"Hello, {me.Name}!");
var userClient = new BoxClient(auth.AsUser("user_id"));
var managedUser = await userClient.Users.GetUserMeAsync();
Console.WriteLine($"Hello, {managedUser.Name}!");
var folderItems = await userClient.Folders.GetFolderItemsAsync("0");
if (folderItems.Entries != null)
{
foreach (var item in folderItems.Entries)
{
if (item.FolderMini != null)
{
Console.WriteLine($"Folder: {item.FolderMini.Name}");
}
else if (item.FileFull != null)
{
Console.WriteLine($"File: {item.FileFull.Name}");
}
else if (item.WebLink != null)
{
Console.WriteLine($"WebLink: {item.WebLink.Name}");
}
else
{
Console.WriteLine($"Unknown item: {item}");
}
}
}BoxWithNextGenSDK.csprojの内容:
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<OutputType>Exe</OutputType>
<TargetFramework>net6.0</TargetFramework>
<ImplicitUsings>enable</ImplicitUsings>
<Nullable>enable</Nullable>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="Box.Sdk.Gen" Version="0.2.0" />
</ItemGroup>
<ItemGroup>
<None Update="config.json">
<CopyToOutputDirectory>Always</CopyToOutputDirectory>
</None>
</ItemGroup>
</Project>サポートが必要な場合はBox Developer Community (英語のみ) にご参加ください。
