メインコンテンツへスキップ
注釈は、新しいBox Viewでサポートされる主な機能の1つです。開発者はこの機能を使用して、アプリケーションに埋め込まれたプレビュー内から直接、コラボレーション機能を提供できます。 Box Viewでは、ハイライトのみ、ハイライトによる注釈、およびポイント注釈という3つの注釈の種類をサポートしています。注釈はドキュメントと画像のプレビューのみでサポートされます。
注釈トークンのしくみ

​
注釈トークンとは

注釈トークンとは、ユーザーが注釈を付けることができるファイルに対してアプリケーションがプレビューの埋め込みリンクを作成できるようにするアクセストークンです。アプリケーションでは、アプリケーションのユーザーそれぞれに新しいApp Userが作成されない可能性があるため、注釈トークンを使用すると、注釈を付けたユーザーを追跡できます。 The Annotator Token is used instead of a regular Access Token or File Token to generate a preview session (an expiring embed link) that is linked to a unique user ID and display name.
注釈トークンを使用して生成されたプレビューセッションは特定の外部ユーザーに関連付けられるため、アプリケーションでは、アプリケーションのエンドユーザーごとに異なる注釈トークンを使用して、個別にプレビューセッションを生成することを強くお勧めします。

​
外部ユーザー情報

注釈に関連付けられた外部の表示名は、実際のところ、注釈に追加されるステートレスな「ラベル」です。つまり、注釈が追加されると、その表示名は完全に注釈と関連付けられるため、注釈を削除し、更新した表示名を使用して再度追加しなければ更新できません。

​
SDKを使用せずに作成

注釈トークンを作成するには、JWTを使用して手動で認証する手順に従いますが、その際、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),
};
パラメータ型説明
subStringこの注釈を関連付ける外部ユーザーID。このIDには、アプリケーションで追跡される任意のIDを使用できます。
box_sub_typeString外部ユーザーIDを示す場合はexternal
box_sub_typeStringこの注釈を関連付ける外部ユーザー名。これはBox UIに表示されます。
Then, convert this claim to an assertion according to the guide and pass this assertion to the endpoint together with an existing valid Access Token or File Token, as well as a set of scopes, and the resource for which to create the 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"),
});
パラメータ説明
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
    });