Skillsメタデータの書き込み

機械学習システムからデータインサイトを取得できたら、次の手順はBoxに保存されているファイルのメタデータとしてデータを書き戻すことです。このプロセスには以下の3つの手順が含まれます。

1. 元のイベントペイロードを介して送信された書き込みトークンを使用して、Boxクライアントを設定します。
2. Skillsメタデータを適切な形式で準備します。
3. メタデータをファイルに書き戻します。

書き込みトークンを使用したBoxクライアントの設定

イベントペイロードから書き込みトークンが抽出されたら、開発者トークンの場合と同じ方法で新しい基本のBoxクライアントを作成できます。このクライアントを利用して、ファイルにメタデータを書き込むことができます。

var config = new BoxConfig("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET", new Uri("http://localhost"));
var session = new OAuthSession("YOUR_DEVELOPER_TOKEN", "N/A", 3600, "bearer");
var client = new BoxClient(config, session);

BoxAPIConnection api = new BoxAPIConnection("YOUR-DEVELOPER-TOKEN");

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('My user ID is {0}'.format(me.id))

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');

Skillsメタデータの準備

Skillsメタデータは、グローバルに利用可能なboxSkillsCardsという名前のメタデータテンプレートを使用します。このテンプレートは、関連ファイルに保存されるJSON構造の特定の形式に従います。

"cards": [{
    "created_at": "{{CURRENT_TIMESTAMP}}",
    "type": "skill_card",
    "skill_card_type": "{{SKILLS_CARD_TYPE}}",
    "skill_card_title": {
        "message": "{{CARD_TITLE}}"
    },
    "skill": {
        "type": "service",
        "id": "{{SKILL_ID}}"
    },
    "invocation": {
        "type": "skill_invocation",
        "id": "{{FILE_ID}}"
    },
    "duration": "{{DURATION_IN_SECONDS}}",
    "entries": "{{CARD_ENTRIES}}"
}]}

ルートのcardsオブジェクトはオブジェクトの配列であるため、一度に1つまたは複数のカードをメタデータに適用できます。

上記のサンプルには、{{ VALUE }}としてラップされた動的な値が複数あります。これを、以下に説明する値に置き換える必要があります。

• CURRENT_TIMESTAMP: メタデータが作成された時刻。現在のタイムスタンプを設定する必要があります。
• SKILLS_CARD_TYPE: 作成するカードのタイプ。利用可能なオプションについては、下の「Skillsカードのタイプ」セクションを参照してください。
• CARD_TITLE: 書き込まれるカードのタイトル。コンテンツに付ける任意のタイトルです。
• SKILL_ID: スキルのID。Skillsアプリケーション名を設定する必要があります。
• FILE_ID: メタデータを書き込むファイルのID。イベントペイロードから抽出されます。
• DURATION_IN_SECONDS (省略可): 動画ファイルや音声ファイルなど、継続時間を持つコンテンツがある場合にのみ使用するオプションパラメータです。使用する場合、コンテンツの長さを秒単位で指定する必要があります。
• CARD_ENTRIES: 機械学習システムから取得されるデータ。この値はオブジェクトの配列です。下の「Skillsカードエントリ」を参照してください。

Skillsカードのタイプ

以下に、Box Skillsで使用できるすべてのカードタイプを示します。メタデータJSONオブジェクトのSKILLS_CARD_TYPE値を、以下の表に示すカードのメタデータ値に置き換えてください。

Skillsカードエントリ

CARD_ENTRIESフィールドには、特定の形式のカードタイプのすべてのデータが含まれます。エントリは、関連データを含むオブジェクトの配列である必要があります。エントリオブジェクトには、カードタイプに応じて以下の形式のいずれかを使用します。

キーワードカードエントリ

キーワードカードエントリにはオブジェクトごとに以下の2つの値が含まれます。

• text: 表示されるキーワードテキスト。
• type: 常にtext。

[
    { "text": "Keyword1", "type": "text" },
    { "text": "Keyword2", "type": "text" },
    ...
]

トランスクリプトカードエントリ

トランスクリプトカードエントリには以下の複数の値が含まれます。

• text: トランスクリプト行エントリに表示するテキスト。

• appears: 行エントリの開始時間と終了時間を含むオブジェクトの配列。

  • start: 開始時間(秒)。
  • end: 終了時間(秒)。

[
    { "text": "Line1", "appears": [{ "start": 0, "end": 10 }] },
    { "text": "Line2", "appears": [{ "start": 11, "end": 20 }] },
    ...
]

フェイスカードエントリ

フェイスカードエントリには以下の複数の値が含まれます。

• text: 項目に表示するテキスト。

• appears: 行エントリの開始時間と終了時間を含むオブジェクトの配列。

  • start: 開始時間(秒)。
  • end: 終了時間(秒)。
• image_url (省略可): 項目の脇に表示する画像。

[
    {
        "text": "Callout 1",
        "appears": [{ "start": 0, "end": 10 }],
        "image_url": "https://mysite.com/image1.jpg"
    },
    {
        "text": "Callout 2",
        "appears": [{ "start": 11, "end": 20 }],
        "image_url": "https://mysite.com/image2.jpg"
    },
    ...
]

ファイルへのSkillsメタデータの書き込み

Box内のファイルにメタデータオブジェクトを再適用するには、書き込みトークンを使用して作成されたクライアントオブジェクトを使用して、ファイルにメタデータを作成するためのリクエストを作成します。

メタデータを作成するメソッドを呼び出すときに、メタデータテンプレートをboxSkillsCardsに設定し、上の手順で作成したオブジェクトにメタデータを設定します。