Foundry と Gotham 間のドラッグアンドドロップを実装する

以下のチュートリアルでは、データエンリッチメントを実装するためのステップを説明します。ドラッグアンドドロップゾーンにエンリッチメントを追加するセクションがありますが、ユーザーのワークフローに応じて、ドラッグゾーンまたはドロップゾーンのどちらかでエンリッチメントを行えば十分です。詳細はエンリッチメントガイドラインを参照してください。

ドラッグアンドドロップエンリッチメントチュートリアル

ステップは以下の通りです。

1. Data Bank Service が同義データを返すことを確認する。
2. エンリッチメントユーティリティ関数を作成する。
3. ドラッグゾーンにエンリッチメントを追加する または ドロップゾーンにエンリッチメントを追加する。

Data Bank Service が同義データを返すことを確認する

データエンリッチメントを実装するには、まず Data Bank Service が期待通りに同義データを返すことを確認する必要があります。

サポートされているメディアタイプ

現在、Data Bank Service は以下のリストにあるメディアタイプのエンリッチメントをサポートしており、Foundry オブジェクト RID メディアタイプのデータを Gotham オブジェクト メディアタイプのデータでエンリッチすること、およびその逆が可能です。

"application/x-vnd.palantir.rid.phonograph2-objects.object",
"application/x-vnd.palantir.rid.gotham.object",

これらはMIMEタイプを表しています。application/x-vnd.palantir.rid.phonograph2-objects.objectとapplication/x-vnd.palantir.rid.gotham.objectは、Palantirという企業の特定のプロダクトやサービスに関連するオブジェクトを示すカスタムMIMEタイプです。MIMEタイプは、インターネット上で送受信されるデータの形式を特定するために使用されます。

必要なデータ構造

以下は、Data Bank Service リクエストに必要なデータ構造の例です。Data Bank Service リクエストには、まず JSON オブジェクトをシリアライズする必要があることに注意してください。これについては、次のステップでJSON.stringify ↗️の使用方法を説明します。リクエスト形式は以下の通りです。

Copied!
1
2
3
4
5
{
    "dataTransfers": [serializedData1, serializedData2, ...]
    // "dataTransfers" はデータ転送のリストを表しています。
    // 各要素はシリアライズされたデータ (serializedData) です。
}

上記のスニペット内の serializedData は、シリアライズされた後に Data Bank Service に送信されてエンリッチされるデータを指します。上記の dataTransfers オブジェクトは DataTransfer オブジェクト と混同しないでください。名前は似ていますが、目的は異なります。上記のオブジェクトにはエンリッチしたいデータが含まれており、エンリッチは DataTransfer オブジェクトに書き込む前、または DataTransfer オブジェクトがドロップゾーンにドロップされた後に行われる可能性があります。

各 serializedData オブジェクトは以下の構造を持っています。

Copied!
1
2
3
{<media type>: <serialized data>}
// <media type>にはメディアの種類（例: 画像、音声など）が入ります
// <serialized data>にはメディアデータがシリアライズ（直列化）された形式で入ります

たとえば、Gotham オブジェクト識別子があり、このデータを同義の Foundry データで豊かにしたい場合、シリアライズされたデータ表現は次のようになります。

Copied!
1
2
3
4
5
6
7
{
    "dataTransfers": [
        {
            "[\"application/x-vnd.palantir.rid.gotham.object\"]: [\"ri.gotham.XXXXXXXX\", \"ri.gotham.YYYYYYYY\", \"ri.gotham.ZZZZZZZZZZ\"]"
        }
    ]
}

Copied!
1
2
3
4
5
6
7
8
{
    "dataTransfers": [
        {
            // データ転送リストの一部として、特定のアプリケーション形式に対応するリソース識別子（RID）のリストを含む
            "[\"application/x-vnd.palantir.rid.gotham.object\"]: [\"ri.gotham.XXXXXXXX\", \"ri.gotham.YYYYYYYY\", \"ri.gotham.ZZZZZZZZZZ\"]"
        }
    ]
}

上記のスニペットでは、メディアタイプは application/x-vnd.palantir.rid.gotham.object であり、そのメディアタイプを持つデータの配列が続きます。Data Bank Service は、マップされた同義のメディアタイプと、そのメディアタイプのデータを返します。シリアライズされた配列を正しくフォーマットするためには、引用符（"）を \ でエスケープする必要があることに注意してください。

以下の curl リクエストでこのリクエストフォーマットを使用し、application/x-vnd.palantir.rid.gotham.object メディアタイプをユーザーのメディアタイプに置き換え、エンリッチする予定のデータを追加してください。<BEARER TOKEN> をユーザーのベアラートークンに、<HOSTNAME> をユーザーのエンロールメントホスト名に置き換えてください。メディアタイプのデータは文字列形式であり、内部の引用符を \ 文字でエスケープすることに注意してください。

Copied!
1
2
3
4
5
6
7
8
9
10
curl --location --request PUT "https://<HOSTNAME>/data-bank-service/api/data-transfer/batchEnrichDataTransfer" \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <BEARER TOKEN>' \
--data '{
    "dataTransfers": [
        {
           "application/x-vnd.palantir.rid.gotham.object": "[\"ri.gotham.XXXXXXXX\", \"ri.gotham.YYYYYYYY\", \"ri.gotham.ZZZZZZZZZZ\"]"
        }
    ]
}'

このスクリプトは curl を使用してHTTP PUTリクエストを送信しています。以下は各部分の説明です：

• --location: サーバーがリダイレクトを返した場合に、そのリダイレクト先に自動的にフォローします。
• --request PUT: HTTPメソッドとしてPUTを指定しています。データの作成や更新に使用されます。
• https://<HOSTNAME>/data-bank-service/api/data-transfer/batchEnrichDataTransfer: リクエストを送信するURLです。<HOSTNAME> は実際のホスト名に置き換える必要があります。
• --header 'Content-Type: application/json': リクエストのContent-TypeをJSONに設定します。送信するデータがJSONフォーマットであることを示します。
• --header 'Authorization: Bearer <BEARER TOKEN>': 認証ヘッダーを設定しています。<BEARER TOKEN> は実際のトークンに置き換える必要があります。
• --data: 送信するデータを指定しています。この場合、dataTransfers というキーの配列としてデータを送信しています。

このリクエストは、特定のオブジェクトID（ri.gotham.XXXXXXXX など）を使ってデータをバッチで転送し、エンリッチするために使用されます。 ユーザーのデータに同義語がある場合、以下のような応答が得られるはずです。

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
    "dataTransfers": [
        {
            "dataTransfer": {
                // PalantirのGothamオブジェクトのデータ転送
                "application/x-vnd.palantir.rid.gotham.object": "[\"ri.gotham.XXXXXXXX\", \"ri.gotham.YYYYYYYY\", \"ri.gotham.ZZZZZZZZZZ\"]",
                // PalantirのPhonograph2オブジェクトのデータ転送
                "application/x-vnd.palantir.rid.phonograph2-objects.object": "[\"ri.phonograph2-objects.main.object.XXXXXXXX\", \"ri.phonograph2-objects.main.object.YYYYYYYY\", \"ri.phonograph2-objects.main.object.ZZZZZZZZZZ\"]",
            },
            // エラーがない場合の空配列
            "errors": []
        }
    ]
}

上記で言及した dataTransfers オブジェクト、Gotham メディアタイプ application/x-vnd.palantir.rid.gotham.object に続くそのメディアタイプのデータ、そして Foundry メディアタイプ application/x-vnd.palantir.rid.phonograph2-objects.object に続くそのメディアタイプのデータに注意してください。

オブジェクトの同義語が得られない場合、エンロールメントとオントロジーでタイプマッピングが有効になっていることを確認してください。オントロジーでタイプマッピングが有効になっている場合、タイプマッピングドキュメントに従って、オブジェクトタイプのタイプマッピングが有効になっていることを確認してください。また、送信しているデータが期待される同義メディアタイプにマッピングされており、それがData Bank Serviceでサポートされていることを確認することもお勧めします。

このチュートリアルの残りの部分では、このリクエストを使用する手順を分解し、ドラッグアンドドロップワークフローを強化するためのレスポンスの使用方法を示します。

エンリッチメントユーティリティ関数を作成する

1. Data Bank Service にリクエストを送る関数を作成します。以下は、Fetch API ↗️を使用してData Bank Serviceリクエストのオプションを作成する例です。
2. Data Bank Service のエンリッチメントエンドポイントにアクセスして、ドラッグまたはドロップゾーンを強化するために使用できる追加の同義メディアタイプとそのデータを取得します。

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
// <HOSTNAME> をあなたの登録されたホスト名に置き換えてください
const batchEnrichDataTransferURL =
    "https://<HOSTNAME>/data-bank-service/api/data-transfer/batchEnrichDataTransfer";

// bearerToken は文字列型
// serializedData は {[mediaType: string]: string} 型
function getEnrichedData(
    bearerToken,
    serializedData
){
    // ステップ1で定義された関数を呼び出す
    const requestOptions = getRequestOptions(bearerToken, serializedData);

    const enrichedData =
        await fetch(batchEnrichDataTransferURL, requestOptions)
            .then((response) => response.json())
            .catch((error) => console.error(error));

    // データ転送を1つだけ強化するので、最初のエントリを取得
    const enrichedFirstDataTransfer = enrichedData.dataTransfers?.[0]?.dataTransfer;
    return enrichedFirstDataTransfer;
}

このコードは、指定されたエンドポイントを使ってデータを強化するための関数 getEnrichedData を定義しています。bearerToken は認証用トークンで、serializedData は強化対象のデータです。fetch 関数を使用して、データをリクエストし、最初のデータ転送を取得します。 このエンドポイントは、解決された強化データとその強化に関連するエラーのリストを含むシリアル化されたオブジェクトのリストを返します。このエンドポイントは、以下の形式でデータを返します。

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
    {
        "dataTransfers":
            [
                {
                    "dataTransfer": {"<media type>": "<serialized data>"},
                    "errors": "[<error1>, <error2>...]"
                },
                {
                    "dataTransfer": {"<media type>": "<serialized data>"},
                    "errors": "[<error1>, <error2>...]"
                },
            ...
            ]
    }

このJSON構造は、dataTransfersというキーの下に複数のデータ転送オブジェクトを含む配列を表しています。それぞれのデータ転送オブジェクトは以下の要素を持ちます：

• dataTransfer: <media type>（メディアタイプ）に関連する<serialized data>（シリアライズされたデータ）を示します。
• errors: データ転送時に発生した可能性のあるエラーのリストを示しています。<error1>, <error2>などがエラーのプレースホルダーです。

この構造は、データ転送の結果とエラー情報を管理するのに役立ちます。 データ バンク サービスによって要求メディアタイプがサポートされていない可能性があるため、エラーに注意してください。

ドラッグゾーンにエンリッチメントを追加する

エンリッチメントはドラッグゾーンまたはドロップゾーンのどちらかに追加するだけで十分です。エンリッチメントのガイドラインを参照して、このチュートリアルのセクションがユーザーのワークフローに関連しているかどうかを確認してください。

1. ドラッグゾーンにエンリッチメントを追加するために、前のセクションのステップ2で getEnrichedData 関数を呼び出します。エンリッチメントは、ページまたはコンポーネントがマウントされるときに実行する必要があり、dragstart ハンドラー内で実行すべきではありません。これは、dragstart ハンドラー内で高コストでブロックする呼び出しを行うことができないためです。返されるエンリッチされたデータには、リクエスト内の元のデータと追加の同義データが含まれます。

2. dragstart ハンドラーでは、取得したエンリッチされたデータをドラッグイベントの DataTransfer に追加します。このデータがドラッグイベントの DataTransfer に追加されると、エンリッチメントが成功した場合に、ユーザーはこのペイロードを Foundry や Gotham のドロップゾーンにドラッグできるようになります。以下のコードは、Gotham オブジェクト ID でエンリッチされたデータをリクエストし、データを文字列形式にするために JSON.stringify ↗️ を使用する方法を示しています。

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
const gothamObjectIds = ["ri.gotham.XXXXXXXX", "ri.gotham.YYYYYYYY", "ri.gotham.ZZZZZZZZZZ"];

async function getEnrichedFoundryData(){
    const enrichedData = await getEnrichedData(
        "<BEARER TOKEN>",
        {"application/x-vnd.palantir.rid.gotham.object": JSON.stringify(gothamObjectIds)}
    );

    // enrichedDataから特定のキーに対応するデータを取得
    const enrichedFoundryIdData = enrichedData?.["application/x-vnd.palantir.rid.phonograph2-objects.object"]

    if (enrichedFoundryIdData != null){
        try {
            // JSON文字列をパースしてオブジェクトを返す
            return JSON.parse(enrichedFoundryIdData);
        } catch (error) {
            // データのパースに失敗した場合のエラーハンドリング
            console.error(error);
            return undefined;
        }
    }
}

let enrichedFoundryIdData = null;

// 非同期でenrichedデータを更新する
// dragstartハンドラーでのブロッキングを避けるために必要
getEnrichedFoundryData().then((data) => {
    enrichedFoundryIdData = data;
});

async function handleDragStart(event) {
    event.dataTransfer.setData("application/x-vnd.palantir.rid.gotham.object", JSON.stringify(gothamObjectIds));

    if(enrichedFoundryIdData != null){
        event.dataTransfer.setData("application/x-vnd.palantir.rid.phonograph2-objects.object", enrichedFoundryIdData)
    }

    // event.dataTransferは元のGothamオブジェクトメディアタイプデータと同義のFoundryデータを含む
    event.dataTransfer.effectAllowed = "move";
}

上記のコードを使用すると、Foundryの同義語を持つオブジェクトのGothamオブジェクトIDがある場合、同義データをDataTransferに追加することで、GothamとFoundryの両方のドロップゾーンでドラッグペイロードを受け入れることができます。

ドロップゾーンにエンリッチメントを追加する

エンリッチメントはドラッグゾーンまたはドロップゾーンのいずれかに追加するだけでよいことに注意してください。ユーザーのワークフローにこのチュートリアルのセクションが関連しているかどうかを判断するには、エンリッチメントのガイドラインを参照してください。

ドロップゾーンにエンリッチメントを追加するには、イベントのDataTransferからデータをエンリッチする必要があります。以下のコードスニペットでは、GothamオブジェクトIDを想定していますが、DataTransferにGothamオブジェクトのメディアタイプがない場合はDataTransferからデータをエンリッチすることができます。簡単にするために、以下のドロップハンドラーはまずDataTransferから直接Gothamオブジェクトデータにアクセスしようとし、失敗した場合、以下のコードブロックでのエンリッチメントに移行すると仮定します。

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
function handleDrop(event) {
    // デフォルトのリンクを開く動作を防ぐ
    event.preventDefault();

    // スタイリングのクリーンアップを行う
    removeStylingFromDropZone("valid-small-hover");
    removeStylingFromDropZone("valid-small");
    dropHoveringOverDropZoneCount = 0;
    dragInsideApplicationCount = 0;

    // <DataTransferからGothamオブジェクトデータにアクセスを試み、成功した場合は早期にリターンし、それ以外の場合は続行>

    // FoundryオブジェクトRIDのメディアタイプデータはGothamオブジェクトメディアタイプデータに拡充できる
    const foundryData = event.dataTransfer.getData(
        "application/x-vnd.palantir.rid.phonograph2-objects.object"
    );

    try {
        if(foundryData != null && foundryData !== ""){
            // 返されたデータを解析し、拡充リクエストを送信することを試みる
            // データを解析できない場合は、フォーマットが間違っている可能性がある
            const foundryDataParsed = JSON.parse(foundryData);

            const serializedData = {
                ["application/x-vnd.palantir.rid.phonograph2-objects.object"]: foundryDataParsed
            }

            const enrichedData = await getEnrichedData(
                "<BEARER TOKEN>",
                serializedData
            );

            if(enrichedData?.["application/x-vnd.palantir.rid.gotham.object"] != null){
                doCoolThingWithGothamObjectIds(
                    enrichedData["application/x-vnd.palantir.rid.gotham.object"]
                );
            }
        }
    } catch (error) {
        console.error("データを解析できません", error)
    }
}

結論

上記のコードスニペットを使用して、Data Bank Service エンドポイントにリクエストを送信し、GothamとFoundryの両方で互換性のある同義語を含むようにデータを強化できます。これにより、ドラッグ可能なデータがGothamとFoundryの両方のドロップゾーンで受け入れられるようになり、ドロップゾーンがFoundryとGothamの両方のデータを受け入れることができるようになります。