ContentfulにAPI経由でメディアをアップロードして公開する #JavaScript

この記事は「つながる勉強会 Advent Calendar 2022」の 3日目の記事です。

1日目の記事はこちら「フルリモートで働くうえで”テキストコミュニケーション”で気をつけていること」
2日目の記事はこちら「生産性を爆上げするおすすめツール達」

フロントエンドエンジニア兼デザイナーのりょーた（@RyoTa___0222）です。
神戸（たまに大阪）でつながる勉強会というオフラインの勉強会の運営をしています。

本記事では、勉強会のコミュニティで利用するWebアプリケーションにおいて、ContentfulというHeadless CMSにAPI経由でメディア（画像やドキュメントなど）をアップロードする機能を実装したため、その手順をまとめます。作成しているアプリケーションの概要については最後に記載しておりますので興味のある方はぜひ最後までお読みください

環境 / ライブラリ情報

環境

Node.jsで実装をしています。

> node -v
v16.17.1

ライブラリ情報

Contentful内のコンテンツを更新するために、Contentful Management APIを利用します。
公式でライブラリが公開されているのでそちらをインストールしてください。

"contentful-management": "^10.21.4"

実装方針

大まかな手順は以下の通りです。

対象のファイルデータがBase64にエンコードされた状態であれば一時ファイルを作成（パスに存在するファイルの場合はスキップ）
対象のファイルを読み込み
Contentfulに対象のファイルをアップロード
アップロードしたファイルを元にContentfulでアセットを作成し公開
一時ファイルの削除（1.で作成していない場合はスキップ）

実装する上で詰まった点を説明していきたいと思います。

1. 対象のファイルデータがBase64にエンコードされた状態であれば一時ファイルを作成

「アプリケーション上で、ユーザーがアップロードしたファイルを元に、公開する」といったケースの場合、Base64にエンコードされたデータとしてプログラム上保有していると思いますが、このままContentfulにアップロードしても、空のファイルが作成されてしまいます。そのため、一度、以下のようにファイルを作成する必要があります。

fs.writeFileSync(`./${ここにファイル名}`, `${Base64エンコードされたデータ}`, {
    encoding: "base64",
});

4. アップロードしたファイルを元にContentfulでアセットを作成し公開

Contentulには "Asset" という概念があります。アセットはメディアファイルを格納する箱のようなもので、Contentful上ではこのアセットを通して、参照、データの削除、更新などの処理が行われます。
そのため、3. でファイルをアップロードしただけだと、そういった処理ができないため、アセットを作成し紐付ける必要があります。

ソースコード

適宜必要な箇所だけ参照ください

import { MIME_TYPES } from "@mantine/dropzone";
import { Asset } from "contentful-management";
import fs from "fs";
import path from "path";
import { createClient } from "contentful-management";

const client = createClient({
  accessToken: process.env.CONTENTFUL_ACCESS_TOKEN as string,
});

const TMP_FILE_NAME = "tmp";

export const CONTENTFUL_BASE_INFO = {
  space: "",
  environment: "master",
};

export interface Params {
  data: string;
  extension: keyof typeof MIME_TYPES;
  title: string;
}

/**
 * contentfulへファイルアップロード
 *
 * @param {Params} params
 * @returns {Promise<Asset>}
 */
export const uploadFileToContentful = async (
  params: Params
): Promise<Asset> => {
  const { data, extension, title } = params;
  const mimeType = MIME_TYPES[params.extension];
  const tmpFileName = `${TMP_FILE_NAME}.${extension}`
  const fileName = `${title}.${extension}`
  // 1. Base64にエンコードされたデータから一時ファイルを作成
  fs.writeFileSync(`./public/${tmpFileName}`, data, {
    encoding: "base64",
  });
  // 2. 対象のファイルを読み込み
  const filePath = path.resolve("./public", tmpFileName);
  const tmpFile = fs.readFileSync(filePath);
  // 3. Contentfulに対象のファイルをアップロード
  const upload = await client
    .getSpace(CONTENTFUL_BASE_INFO.space)
    .then((space) => space.getEnvironment(CONTENTFUL_BASE_INFO.environment))
    .then((environment) =>
      environment.createUpload({
        file: tmpFile,
      })
    )
    .then((upload) => {
      return upload;
    });
  // 4. アップロードしたファイルを元にContentfulでアセットを作成し公開
  const asset = await client
    .getSpace(CONTENTFUL_BASE_INFO.space)
    .then((space) => space.getEnvironment(CONTENTFUL_BASE_INFO.environment))
    .then((environment) => {
      return environment
        .createAsset({
          fields: {
            title: {
              "en-US": title,
            },
            file: {
              "en-US": {
                contentType: mimeType,
                fileName: `${fileName}`,
                uploadFrom: {
                  sys: {
                    type: "Link",
                    linkType: "Upload",
                    id: upload.sys.id,
                  },
                },
              },
            },
          },
        })
        .then((asset) => {
          return asset.processForAllLocales({ processingCheckWait: 2000 });
        })
        .then((asset) => {
          return asset.publish();
        })
        .then((asset) => {
          return asset;
        });
    });
  // 5. 一時ファイルの削除
  fs.unlink(`./public/${tmpFileName}`, (err) => {
    if (err) throw err;
  });
  return asset;
};

補足を書いていきます

access tokenについて

こちらはpersonal access tokenを管理画面上で発行しています（参照）

アップロードするファイルの拡張子について

アセットを作成する際に、ファイルのコンテンツタイプを指定する必要があるのですが、として私のケースだとアップロードするファイルの形式を予め限定できなかったので、プログラム上で取得するようにしています。
このアプリケーションではUIフレームワークにMantineを利用しており、その中でMIMEタイプの一覧を定義してあるので、それを利用しています。

export declare const MIME_TYPES: {
    readonly png: "image/png";
    readonly gif: "image/gif";
    readonly jpeg: "image/jpeg";
    readonly svg: "image/svg+xml";
    readonly webp: "image/webp";
    readonly mp4: "video/mp4";
    readonly zip: "application/zip";
    readonly csv: "text/csv";
    readonly pdf: "application/pdf";
    readonly doc: "application/msword";
    readonly docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document";
    readonly xls: "application/vnd.ms-excel";
    readonly xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet";
    readonly ppt: "application/vnd.ms-powerpoint";
    readonly pptx: "application/vnd.openxmlformats-officedocument.presentationml.presentation";
    readonly exe: "application/vnd.microsoft.portable-executable";
};

Mantineを利用していない方は、よくある MIME タイプを参考にしてみてください。（Mantineめっちゃ便利ですよおすすめです）

実装手順の説明は以上となります

参考文献

作成しているアプリケーションの概要

つながる勉強会では、Slackをコミュニティのスペースとして活用していたのですが、Freeプランでは90日を経過したログが削除されるようになりました。
そのため、資産として削除されたくないデータは外部に移行しようということになり、その取り組みの１つとして、LTの登壇資料を閲覧 / アップロードできるアプリケーションの作成を行っています。

技術的な内容としては、Slack認証を実装しており、Slackに招待されたユーザーのみがアップロードされたLT資料を閲覧することが可能です。また、データの管理については、Firebase Cloud Firestoreを利用しており、メディアファイルのみContentfulにアップロードしています。

開発、運用コストは永遠0円

をモットーに必要なアプリケーションを開発していく予定なので、今後も技術的知見が溜まったら共有していきたいと思います。

また、基本的には認証が必要なアプリケーションになるかと思いますが、勉強会内で利用しているタイマーアプリは、誰でも利用可能となっていますのでぜひご覧ください。

この記事を読んで興味をもたれた方がいらっしゃいましたらぜひご参加お待ちしております

終わりに

Contentfulは本来コンテンツ管理のサービスですが、このような変化球な使い方も無料である程度できるのは便利ですね
Management API関連の記事だと日本語のものが少なかったので、また機会があればまとめていきたいと思います