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

データエンリッチメントにアクセスするには、エンロールメントに Gotham と Foundry の両方があり、タイプマッピングが有効になっている必要があります。アプリケーションが Gotham のみ、または Foundry のみでドラッグアンドドロップ操作を行う場合、データエンリッチメントを実装する必要はありません。

次のチュートリアルでは、データエンリッチメントを実装するために必要な手順を説明します。ドラッグゾーンとドロップゾーンにエンリッチメントを追加するセクションが含まれていますが、ワークフローに応じて、ドラッグゾーンまたはドロップゾーンのいずれかでのみエンリッチメントを行う必要があります。詳細については、エンリッチメントのガイドラインを参照してください。

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

手順は次のとおりです。

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

アプリケーションと Palantir プラットフォーム間のドラッグアンドドロップの相互運用性を高めるため、プラットフォームの最新バージョンをインストールすることを推奨します。

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",

必要なデータ構造

以下は、Data Bank Service のリクエストに必要なデータ構造の例です。Data Bank Service のリクエストでは、JSON オブジェクトをまずシリアライズする必要があります。以降の手順では、この処理に JSON.stringify ↗ を使用する方法を説明します。リクエストの形式は次のとおりです。

Copied!1
2
3
{
    "dataTransfers": [serializedData1, serializedData2, ...]
}

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

各 serializedData オブジェクトの構造は次のとおりです。

Copied!1
{<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\"]"
        }
    ]
}

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

以下の curl リクエストでこのリクエスト形式を使用し、application/x-vnd.palantir.rid.gotham.object メディアタイプを使用するメディアタイプに置き換え、エンリッチメントする予定のデータを追加します。<BEARER TOKEN> を Bearer トークンに、<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\"]"
        }
    ]
}'

データに同義のデータがある場合、次のようなレスポンスが返されるはずです。

Copied!1
2
3
4
5
6
7
8
9
10
11
{
    "dataTransfers": [
        {
            "dataTransfer": {
                "application/x-vnd.palantir.rid.gotham.object": "[\"ri.gotham.XXXXXXXX\", \"ri.gotham.YYYYYYYY\", \"ri.gotham.ZZZZZZZZZZ\"]",
                "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 でサポートされていることを確認することも推奨します。

このチュートリアルの残りの部分では、このリクエストを使用する手順を詳しく説明し、レスポンスを使用してドラッグアンドドロップのワークフローをエンリッチメントする方法を示します。

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

Data Bank Service にリクエストを送信する関数を作成します。以下は、Fetch API ↗ を使用して 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
23
24
25
26
27
28
// シリアライズされたデータを使ってリクエストオプションのオブジェクトを作成する関数を作成します
function getRequestOptions(
    bearerToken
    // serializedData は、メディアタイプから、そのデータのシリアライズされたバージョンへのマッピングです
    serializedData
){
    return {
        method: "PUT",
        headers: new Headers({
            "Authorization": bearerToken,
            "Content-Type": "application/json"
        }),
        body: JSON.stringify({
            "dataTransfers": [ serializedData ]
        }),
        redirect: "follow"
    };
}

// この関数を次のように使います
// <BEARER TOKEN> をお使いの Bearer トークンに置き換えます
const requestOptions = getRequestOptions(
    "<BEARER TOKEN>",
    {
        ["application/x-vnd.palantir.rid.gotham.object"]:
        "[\"ri.gotham.XXXXXXXX\", \"ri.gotham.YYYYYYYY\", \"ri.gotham.ZZZZZZZZZZ\"]"
    }
);

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> をお使いのエンロールメントの 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;
}

このエンドポイントは、オブジェクトのシリアライズされたリストを返します。各オブジェクトには、解決されたエンリッチメント済みのデータと、そのエンリッチメントに関連するエラーのリストが含まれる場合があります。このエンドポイントは、次の形式でデータを返します。

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>...]"
                },
            ...
            ]
    }

注意すべきエラーとして、リクエストのメディアタイプが Data Bank Service でサポートされていない場合があります。

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

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

ドラッグゾーンにエンリッチメントを追加するには、前のセクションのステップ2にある getEnrichedData 関数を呼び出します。エンリッチメントは、dragstart ハンドラー内ではなく、ページまたはコンポーネントがマウントされたときに行うようにしてください。これは、dragstart ハンドラー内では、処理コストが高いブロッキング呼び出しを行えないためです。返されるエンリッチメント済みのデータには、リクエスト内の元のデータに加えて、同義のデータが含まれます。
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
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)}
    );

    const enrichedFoundryIdData = enrichedData?.["application/x-vnd.palantir.rid.phonograph2-objects.object"]

    if (enrichedFoundryIdData != null){
        try {
            return JSON.parse(enrichedFoundryIdData);
        } catch (error) {
            // データのパースに失敗しました
            console.error(error);
            return undefined;
        }
    }
}

let enrichedFoundryIdData = null;

// ここでは、エンリッチされたデータを非同期で更新します
// 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 の両方のドロップゾーンでドラッグペイロードを受け入れられるようにできます。

ドラッグゾーンを受け入れられるドロップゾーンを見つけるには、Palantir メディアタイプのドキュメントを参照してください。

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

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

ドロップゾーンにエンリッチメントを追加するには、イベントの 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("Unable to parse data", error)
    }
}

上記のコードを使用すると、ドロップゾーンは Gotham と Foundry の両方のデータを受け入れられます。Palantir のメディアタイプのドキュメントを参照して、ドロップゾーンにドラッグできるドラッグゾーンを確認してください。

まとめ

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

←

PREVIOUSFoundry と Gotham 間のドラッグアンドドロップ

NEXTデザインガイドライン

→