初めまして、長谷川と申します。
主だった担当領域は

KARTE Action や KARTE Datahub クエリのクライアントさまのニーズに合わせた設計と作り込み、運用支援
KARTE Action や KARTE Craft の機能テンプレート開発

の周辺となります。以後よろしくお願いいたします！

早速ですが、お手持ちのInstagramアカウントの投稿をKARTEの接客アクションとしてサイトに埋め込みたい…と考えたことはございませんか？
このところ弊ブログにて言及されることの多い"KARTE Craft"を用いることで実現できちゃいます！
KARTE Craftのユースケースとしてもバッチリ記載のある本件ですが、
今回の記事にて"Instagram連携"として内容をもう少し掘り下げてみたいと思います。
お題目は以下の通りの流れで進めて参ります。

そもそも、なぜ KARTE Craft が必要なのか？
KARTE Craft に含まれる一連の機能とその役割
"Instagram連携" のユースケースについて
当ソリューションにおける Craft Functions 実装時の注意点と実装例
処理アイデア: Craft Functions における外部API利用の一例
処理アイデア: Craft Key-Value Store(KVS) に アクションテーブル 中の1レコードを保存する
おわりに

そもそも、なぜKARTE Craftが必要なのか？

Instagram上の投稿に関する情報を取得するためには、"Instagram Graph API"へのリクエスト & レスポンスを用います。
そしてリクエストURLには MetaアプリとInstagramアカウントに係るクレデンシャルを含める 必要があります。
このURLが他人から見える状態での通信は意図された利用方法ではなく、かつ非常にリスキーです。
よって、"Graph APIにGETでリクエストを投げ、レスポンスをパースし、1投稿を1レコードとしてDBへInsertする"といういかにもサーバサイドな役割を誰かが果たさねばなりません。
そこへ颯爽と KARTE Craft の機能たちが登場するのです！

KARTE Craftに含まれる一連の機能とその役割

KARTE Craftは複数の機能を包括しており、今回の"Instagram連携"においては各機能が以下のような役割となります。

Craft Secret Manager
- MetaアプリとInstagramアカウントに係るクレデンシャルの管理
Craft Functions
- 上記クレデンシャルを用いてInstagram Graph APIと通信 & レスポンスをパースして アクションテーブル へ挿入するサーバサイド処理を記述
Craft Scheduler Trigger
- 上記サーバサイド処理を任意のタイミングで起動
Craft Key-Value Store(KVS)
- Craft Functionsからはアクションテーブルの内容を参照できないため、擬似的なアクションテーブルとして用いる
- 投稿の削除、いいねの数、コメントの数といった情報をInstagramとアクションテーブル間で連携させるための仕組み

"KARTE Craft" 、 "Instagram Graph API" それぞれの関係性は次の画像のようになります。

そして、上記機能でアクションテーブルに挿入されたレコードが KARTE Action によって Instagram接客 の形でブラウザ上に表示され、
晴れて"Instagram連携"というソリューションとなります👏

実際にWebサイトへ埋め込むと、上記画像の赤枠で囲った部分のようになります.

"Instagram連携"のユースケースについて

では、"Instagram連携"を用いた上で実際に何ができるのか？
あくまでも一つのInstagramアカウントとの連携を想定した形ではありますが、
実店舗 & EC系での例をいくつか考えてみました。

投稿のコメントによりカテゴリ分けして表示、よりリッチで活気のあるサイトの雰囲気作りに
- "コメントに特定文字列(例: category:new_products)を含む投稿のみを表示する接客"を条件ごとに用意して埋め込み先を変えてあげると、以下のように出し分けができます
  - サイトトップページには、新着商品紹介カテゴリの投稿を表示する 接客を埋め込む
  - 特定商品のページには、その商品のコーディネートに関連する投稿を表示する 接客を埋め込む
投稿したスタッフさんの情報と、投稿の閲覧回数やCV回数を紐付ける
- 上記の投稿コメントによる条件付けの応用として、コメント中にスタッフさんに紐づく文字列を含めていただく
- 埋め込み接客中の投稿クリック or タップで、スタッフさん情報を含めた専用のイベントを発火させる
  - イベント発火回数による"人気の投稿"レコメンドや記事内容の分析
  - CV紐付き回数による個人の評価と記事内容の分析

羅列的で恐縮なのですが、すぐ思いつく限り上記のような使い道がございます。
個人的にアツいポイントとして、

一度セッティングしてしまえば、Instagramへ投稿するだけで上記の仕組みを利用できるお手軽感
Instagramの投稿に対するリアクションを数値化することで生まれる新たな価値

あたりを推していきたい所存です。
先日の記事中にある KARTEでSTAFF STARTライト導入プラン と組み合わせるのも面白そうですね。
KARTE Craftの可能性と合わせて使い道もできることも無限大でございます…！

当ソリューションにおけるCraft Functions実装時の注意点と実装例

さて、ここからは技術的な色が濃くなって参ります。
さっそくですが Craft Functions を利用するにあたって、いくつかの制約と注意すべき性質がございます。
その点を踏まえて、今回の"Instagram連携"に係る処理は以下に留意して実装します。

Craft Functions それ自体には関数単位の 重複実行を防ぐ仕組み がない
- 重複して実行されるべきでない関数は、こちらの記事のように自らで重複実行を防ぐ必要があります
Craft Functionsの1実行あたりの起動時間の上限は30秒
- 上限を超えた場合は処理が強制終了される場合があります
Craft Functions から アクションテーブル へのupsert or deleteの実行には間隔制限がある
- ご契約プラン次第とはなりますが、基本的にはこちらの通り最長6秒, 最短2秒の実行間隔が必要になります
- 制限はプロジェクト単位に係るため、Craft Functions からの アクションテーブル 操作は必要最低限とするのが望ましい
- よって、"Graph APIレスポンスをレコードとしてアクションテーブルへ挿入する", "アクションテーブルからレコードを削除する"それぞれ動作に対して以下のような条件を設けます
  - 挿入条件: "アクションテーブル中に存在しない" もしくは "いいねの数、コメント数、サムネイルURLのいずれかに変動がある"
  - 削除条件: "Graph APIからのレスポンス中に存在しない"
ColdStartの関係で、処理時間が想定以上に伸びる場合がある
- 実行トリガーにスケジューリングを用いるかつ実行間隔が長い場合は対策が必要となる場合があります
  - この辺りについては、別記事にてご紹介できればと思います…！
- mustではありませんが「処理の各段階までに何秒かかったか？」をこまめにログ出ししつつ、実装と検証を進めていただくことをオススメいたします

注意点を踏まえた処理のポイント

Craft Key-Value Store(KVS)を用いて重複実行のチェックと、"実行中か否か"のステータス管理を行う
Craft Secret Managerを用いて以下の値を取得
- Graph APIへのリクエスト用クレデンシャル
- API v2アクセストークン
Graph APIのレスポンスに対するvalidation
アクションテーブルへのupsert or deleteの要不要判定のために、Craft Key-Value Store(KVS)を擬似的アクションテーブルとして用いる
- KVSには1valueあたりのサイズ制限がある
処理の段階ごとに、"処理開始から何秒経ったか？"を記録する仕組みを設ける

処理概要

処理の概要自体は以下のような形です。

重複実行のチェック
- すでに実行中なら処理終了
"実行中"ステータスとする
Craft Secret Managerより、クレデンシャルの取得
Graph API(クレデンシャルを含むURL)へリクエスト
Graph APIのレスポンスをvalidationし、パース(mapping)
Craft Key-Value Store(KVS)より、アクションテーブル内レコードを復元
アクションテーブルから、Graph APIのレスポンス中に存在しないレコードをdelete
Graph APIのレスポンスをCraft Key-Value Store(KVS)にwrite
- 条件により、アクションテーブルへupsert
"実行中"ステータスの解除

上記概要に沿ってソースコードとしてみると…

const ACTION_TABLE_NAME = "Instagram連携用テーブル名";

const EXCLUSION = {
    isDuplicatedExec: async () => /* すでに本処理が実行中か？ */,
    startSuppressDuplicates: async () => { /* "実行中"ステータスとする */ },
    endSuppressDuplicates: async () => { /* "実行中"ステータスを解除する */ }
};

const SECRETS = {
    collectCredentials: async (secret) => await {
        /* Graph APIリクエストURL用クレデンシャル,  */
        /* API v2アクセストークン */
    }
};

const EXTERNAL_API = {
    __fetch__: async (url) => {
        const _result = await fetch(url);

        if(!_result.ok) { /* エラー処理 */ }

        const _json = await _result.json();

        /* バリデーション1段目 */
        someValidation(_json);

        return _json;
    },
    createURL: (tokens) => "https://graph.facebook.com/v16.0/"
        + tokens.IG_USER_ID + "/media"
        + "?fields=id,comments_count,like_count,caption,"
        + "media_product_type,media_type,"
        + "media_url,permalink,thumbnail_url,timestamp,children"
        + "&access_token=" + tokens.IG_ACCESS_TOKEN,
    doFetch: async (url) => {
        const _callFetch = async (url, currentRecords = []) => {
            const _body = await EXTERNAL_API.__fetch__(url);

            const _combinedRecords = [...currentRecords, _body.data];

            return (次の投稿ページングURLが存在する || _combinedRecords.length < Instagram投稿取得数上限)
                ? _combinedRecords
                : await _callFetch(_body.paging.next, _combinedRecords);
        };

        return await _callFetch(url);
    },
    resultMapper: (result) => {
        /* バリデーション2段目, プロパティ & 型チェック */
        return someValidation(result).map(/* mapping... */);
    }
};

const KVS = {
    collectRecords: async (kvs) => await {
        IG_RECORDS_COUNT: "kvs中に存在するレコード件数",
        IG_RECORDS: [ /* レコード */ ]
    }
};

export default async function(data, { MODULES }) {
    const { logger, secret, kvs } = MODULES;
    /* 処理開始のロギング ()*/

    try {
        /* すでに当処理が実行中か？ */
        if(await EXCLUSION.isDuplicatedExec()) {
            logger.log("すでに起動しています");
            return;
        }

        /* "実行中"ステータスとする  */
        await EXCLUSION.startSuppressDuplicates();

        /* Craft Secret Managerより、クレデンシャルの取得 */
        const credentials = await SECRETS.collectCredentials(secret);

        /* Graph API(クレデンシャルを含むURL)へリクエスト */
        const graphApiRecords = await EXTERNAL_API.doFetch(
            EXTERNAL_API.createURL({
                IG_USER_ID: credentials["IGユーザーID"],
                IG_ACCESS_TOKEN: credentials["アプリユーザーのユーザーアクセストークン"]
            })
        );

        /* レスポンスのパース(mapping) */
        const instagramRecords = EXTERNAL_API.resultMapper(graphApiRecords);

        /* Craft Key-Value Store(KVS)より、アクションテーブル値の復元 */
        const actionTableRecords = await KVS.collectRecords(kvs);

        /* API v2利用準備 */
        const action = api("@dev-karte/v1.0#hf33ldnvhh4c");
        action.auth(credentials["secretから取得したAPI v2アクセストークン"]);

        /* アクションテーブルからのdelete */
        let deletedCount = 0;
        const deleteRecordKeys = actionTableRecords.IG_RECORDS.filter((nRecord) => /* 削除条件に一致するレコードのkey */);
        await action.postV2betaActionActiontableRecordsDelete({
            table: ACTION_TABLE_NAME,
            keys: deleteRecordKeys // 実際は10件毎の分割が必要！！
        });
        deletedCount = deleteRecordKeys.length;

        /* アクションテーブルupsert, kvsへwrite */
        let actionTableRecordsCount = 0,
            upsertedCount = 0;

        instagramRecords.forEach((nRecord) => {
            if(/* upsert条件を満たす */) {
                await action.postV2betaActionActiontableRecordsUpsert({
                    table: ACTION_TABLE_NAME,
                    data: nRecord
                });

                upsertedCount++;
                await sleep(`${実行間隔に応じた待機}`);
            }

            /* 1レコード */
            await kvs.write({
                key: `IG_RECORD_${actionTableRecordsCount}`,
                minutesToExpire: `${実行間隔に応じた保存期間}`,
                value: nRecord
            });

            actionTableRecordsCount++;

            /* kvs中に存在するレコード件数 */
            await kvs.write({
                key: IG_RECORDS_COUNT
                minutesToExpire: `${実行間隔に応じた保存期間}`,
                value: { IG_RECORDS_COUNT: actionTableRecordsCount }
            });
        });

        logger.log({
            instagramRecordsCount: instagramRecords.length,
            upsertedRecordsCount: upsertedCount,
            deletedRecordsCount: deletedCount
        });
    }
    catch (err) {
        /* エラー内容のロギング() */
    }
    finally {
        /* "実行中"ステータスを解除する */
        await EXCLUSION.endSuppressDuplicates();
    }

    /* 各段階までの所要処理時間記録のロギング() */
}

実際の処理内容とは異なりますが、概ね上記のような流れになるかと思います。

処理アイデア: Craft Functionsにおける外部API利用の一例

サーバ処理において、処理中で外部のAPIを利用することはよくあるケースかと思います。
では、Craft Functions から外部のAPIを叩くにあたり

そもそも本件においてどのAPIを用いるべきか？
どのエンドポイント(ノード)を叩くべきか？

という部分も含め、処理の一例を軽くご紹介できればと思います。
まずは Instagramプラットフォームの開発者ドキュメント を眺めてみましょう…。

そもそも本件においてどのAPIを用いるべきか？

"自分のInstagramアカウントの投稿を取得したい"という本件の目的においては、

InstagramグラフAPI

Instagram基本表示API

のどちらかが使えそうですね。
Instagram基本表示API の説明には

このAPIは、ビジネスおよびクリエイター以外のInstagramユーザーを対象にしています。

との表記がございますので、今回は必然的に InstagramグラフAPI を用いることになるかと思います。

どのエンドポイント(ノード)を叩くべきか？

InstagramグラフAPIの リファレンス を眺めてみると、IGユーザー というノードがニーズに合致しそうです。
文中の リクエストの構文 にて次のようなURLが登場します。

GET https://graph.facebook.com/{api-version}/{ig-user-id}
  ?fields={fields}
  &access_token={access-token}

{api-version}の部分には、グラフAPIリファレンスに記述のある 最新バージョンv16.0を指定すれば良さそうです。
{ig-user-id}と{access-token}はそれぞれ、 パスパラメーター と クエリ文字列パラメーター の部分にある

必須。 IGユーザーID。
必須。 アプリユーザーのユーザーアクセストークン。

これですね。
この二つはそもそも、なぜKARTE Craftが必要なのか？でご紹介した

MetaアプリとInstagramアカウントに係るクレデンシャル

に該当する部分です！
この二つはInstagramアカウントの所有者側で取得し、
Craft Secret Manager に保存した上で Craft Functions 側から利用します。

ここまでの情報とエッジ"media"を組み合わせ{fields}の部分に取得したい項目をパラメータとして指定することで、
自分の投稿に関連する情報を取得できるようになります。
何も指定しない場合は投稿のユニークIDしか取得できませんので、IGメディアを参考にしながら

caption
comments_count
id
like_count
media_product_type
media_type
media_url
permalink
thumbnail_url
timestamp

このあたりを指定しておけば、接客(アクション)として描画するにあたり困ることはなさそうです。
上記を踏まえてInstagram Graph APIへのリクエストURLを生成する処理を書くとしたら

const createURL = (tokens) => "https://graph.facebook.com/v16.0/"
    + tokens.IG_USER_ID
    + "/media" // エッジ"media"
    + "?fields=id,comments_count,like_count,caption,"
    + "media_product_type,media_type,"
    + "media_url,permalink,thumbnail_url,timestamp"
    + "&access_token=" + tokens.IG_ACCESS_TOKEN

このような形になるでしょうか。
では、このURLを元にしてリクエストしてみましょう

const doFetch = async (url) => {
    const __fetch__ = async (url) => {
        const _result = await fetch(url);

        if(!_result.ok) { /* エラー処理 */ }

        const _json = await _result.json();

        /* バリデーション1段目 */
        someValidation(_json);

        return _json;
    },
    __callFetch__ = async (url, currentRecords = []) => {
        const _body = await __fetch__(url);

        const _combinedRecords = [...currentRecords, _body.data];

        return (次の投稿ページングURLが存在する || _combinedRecords.length < Instagram投稿取得数上限)
            ? _combinedRecords
            : await __callFetch__(_body.paging.next, _combinedRecords);
    };

    return await __callFetch__(url);
};

/* 自分のInstagram投稿情報を取得 */
const records = await doFetch({/* Craft Secret Managerから復元した"ig-user-id"と"access-token" */});

先ほどのURLへのリクエストに対するレスポンスとして、Instagramアカウントに係る投稿の情報がレスポンス.json().dataに配列で入ってきます。
また、投稿の配列はある程度の個数でページングされ、レスポンス.json().paging.nextに入ってくるURLに対して再度リクエストを投げることで取得できます。
投稿の配列は投稿日時の新しい順の並びが保証されているわけではないので、どこまでページングを辿るかは注意が必要ですね。

処理アイデア: Craft Key-Value Store(KVS)にアクションテーブル中の1レコードを保存する

実装にあたり留意する点として記述いたしましたが、
アクションテーブルへのupsert or deleteの要不要判定のために、
Craft Key-Value Store(KVS)を擬似的アクションテーブルとして用いる必要がありました。
KVSについては1valueあたりのサイズ制限があり、例えば今回の場合ですと…

/* writeの例 */
await kvs.write({
    key:'InstagramRecords',
    value: [
        {
            id: 000000000000,
            count_comments: 0,
            count_likes: 10,
            thumbnail_url: "サムネurl_1"
        }, {
            id: 000000000001,
            count_comments: 5,
            count_likes: 15,
            thumbnail_url: "サムネurl_2"
        }, {
            id: 000000000002,
            ...
        }
    ]
);

このような"1つのkeyでテーブル丸ごとvalueとしてwriteする"的使い方はできません。
よって、あくまで1key対1レコードで保存しつつ"KVS中に存在するレコード数"という情報もKVSに含めてみます。
もちろんkvs.write()のvalueに渡すobjectのサイズが制限内である前提ではありますが…。

/* writeの例 */
let actionTableRecordsCount = 0;
instagramRecords.forEach((nRecord) => {
    /* 1レコード */
    await kvs.write({
        key: `IG_RECORD_${actionTableRecordsCount}`,
        minutesToExpire: `${実行間隔に応じた保存期間}`,
        value: {
            id: nRecord.id,
            count_comments: nRecord.count_comments,
            count_likes: nRecord.count_likes,
            thumbnail_url: nRecord.thumbnail_url
        }
    });

    actionTableRecordsCount++;

    /* kvs中に存在するレコード件数 */
    await kvs.write({
        key: IG_RECORDS_COUNT
        minutesToExpire: `${実行間隔に応じた保存期間}`,
        value: { IG_RECORDS_COUNT: actionTableRecordsCount }
    });
});

上記でwriteしたvalue達をgetする場合、たとえば処理概要ソースコード中のKVS.collectRecords()の中身は

/* getの例 */
const recordsCount = await kvs.get({ key: "IG_RECORDS_COUNT" }),
    kvsValues = {
        IG_RECORDS_COUNT: recordsCount.value.IG_RECORDS_COUNT,
        IG_RECORDS: []
    };

for(let recordsIdx = 0; recordsIdx < kvsValues.IG_RECORDS_COUNT; recordsIdx++) {
    const record = await kvs.get({ key: `IG_RECORD_${recordsIdx}` });
    kvsValues.IG_RECORDS.push(record.value);
}

return kvsValues;

このような形になりそうです。

おわりに

さて、ユースケースも含めて"Instagram連携"について駆け足でご説明して参りました。
この記事が皆様の「こんな使い方をしたい！」というアイデアに繋がれば幸いです。
Instagram連携 導入ご希望の方はぜひご一報くださいませ！
KARTE Craftそれ自体はβ版(※執筆時点)ということもあり、
当ソリューションも含めて今後皆様のご要望によりどんどん進化して参ります！

KARTEを使ってInstagramの投稿をWebサイト上に自由に表示する