◇はじめに

以前に別記事にて、iPhoneショートカットを使ってkintoneレコードを登録する記事を書きました。
この時の記事では、kintoneのREST API機能を用いてレコードを追加していましたが、添付ファイルをレコードに追加する場合、REST APIの呼び出し方が変わってくるため、そのやり方についてまとめつつ、Postmanを使って実際に添付ファイルを登録してみました。
以前書いた記事はこちらになります。

◇環境等

使用デバイス
- Windows PC
  - Windows 11
使用ツール・サービス
- Edge
- kintone（PCブラウザ経由）
  - （kintone開発者ライセンスを使用）
- Postman

仕様の確認

まず、kintoneのREST APIに関するドキュメントを確認し、その手順について調べます。

一時保管領域にファイルをアップロードします。
一時保管領域とは、このAPIを利用してアップロードしたファイルが一時的に保管される場所です。

アップロードしたファイルのファイルキーを他のAPIで利用することで、一時保管領域のファイルをレコードやスペースなどに添付できます。

一度にアップロードできるファイルは、1つです。

レコードを取得するAPIで取得できるファイルキーは、ファイルアップロードには利用できません。

公式サイトに記載されているように、画像を含む添付ファイルをkintoneのレコードに登録する場合、
kintone上の一時保管領域にファイルをアップロードし、そこで受け取るファイルキーを使ってレコードに登録する2段階の対応が必要です。

自分なりのイメージ図をまとめるとこんな感じです。

の順で記載していきます。

なお、添付ファイルではない文字列などのフィールドをPostmanを使って登録する手順については、公式ドキュメントでも紹介されています。

レコード登録用のkintoneアプリの作成

まずは登録用のkintoneアプリを作成します。
※今回作成したアプリもkintone開発者ライセンスでつくってます

「はじめから作成」から、以下３つのフィールドを配置します。

レコード番号
日時
attach

アプリ名はわかりやすく、「ファイル添付APIテスト」としています。
attachフィールドに画像ファイルを登録します。

REST API用のトークン発行

アプリの作成完了後、設定画面からAPIトークンを発行します。
APIトークンの作成方法は公式ヘルプも参照ください。

先ほど作成したアプリの設定画面から、⚙アイコンを選択し、設定タブ内にあるAPIトークンを選択します。

APIトークン設定の画面左上にある生成するボタンをクリックし、APIトークンを発行します。発行されたAPIトークンはレコード追加のチェックが有効ではないので、チェックを入れて有効化します。

これでAPIトークンの準備が完了しました。

Postmanを使った画像ファイルのアップロード

kintoneアプリにREST APIで登録する準備ができたので、Postmanからデータを登録します。

まずは、一時保存領域に画像ファイルをアップロードする手順です。
先ほどのイメージ図の左側部分です。

過去の記事でも解説しているので、一部手順は省きます。
ファイルを登録する以外は基本的に手順は変わりません。

変数の設定

Postman上で、コレクションを登録し、変数のタブを開きます。
以下、3つの変数を追加します。

baseUrl
apiToken
appId

作成したアプリのURL上の表記から、baseUrlとappIdを探して入力し、apiTokenは先ほど発行した文字列を入力します。

一時保存領域へのファイルの登録

作成したコレクション内で「リクエストを追加」を実行します。
任意の名称を入力し、メソッドはPOSTを選択します。

URL部分には、先ほど作成した変数を使用し、

{{baseUrl}}k/v1/file.json

と入力します。

ヘッダー部分には、キーにX-Cybozu-API-Token、値に{{apiToken}}と入力します。
なお、この辺の記載方法は公式ドキュメントの記載を基に設定しています。

※公式ドキュメント上では、Content-Typeの設定も記載がありますが、Postmanが自動で設定してくれるため、今回は省略しています

最後にボディ部分についてですが、形式はform-dataを選択します。
ここでは、1つのデータを登録します。

キーにfileと入力し、形式をファイルとします。
値の部分は、Select filesの部分でNew file from local machineをクリックしてローカルにある画像ファイルを選択します。

今回は、Qiitaのアイコン画像（qiita-icon.png）を添付しています。

ここまでで、APIを実行する準備ができたので、右上の「送信」を実行します。

画面下のレスポンス画面上に200 OKと出れば成功です。

レスポンスで出力されるfileKeyの文字列がこの後のレコード登録で必要となるので、どこかにコピーしておきます。

{
    "fileKey": "xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx"
}

注意
公式ドキュメントにも記載のあるように、以下の制限があります。

一時保管領域に保存されたファイルは、レコードやスペースなどに添付されない場合、3日間で削除されます。
一時保管領域のファイルも、ディスク使用量に含まれます。

Postmanを使った画像ファイルのレコード登録

次に、このfileKeyを使って、レコードに画像ファイルを登録します。
先ほどのイメージ図の右側部分です。

ここでのやり方は過去の記事とほぼ手順は変わりません。

公式ドキュメントは以下を参考にしています。

まず、先ほどのfileKeyを扱いやすくするため、変数に追加します。

次に、新しいHTTPリクエストを追加します。
今回も、任意の名称を入力し、メソッドはPOSTを選択します。

URL部分には、今回は以下のように設定します。

{{baseUrl}}k/v1/record.json

と入力します。

ヘッダー部分は先ほど同様、キーにX-Cybozu-API-Token、値に{{apiToken}}と入力します。

次に、ボディの部分は形式をRaw-JSONを選択し、以下のように入力します。
ここで記載のattachは、kintoneアプリで作成したフィールドコードになります。別のフィールドコードを設定している場合はそれに合わせて変更してください。

{
  "app": {{appId}},
  "record": {
    "attach": {
        "value": [
            {
                "fileKey": "{{fileKey}}"
            }
        ]
    }
  }
}

添付ファイル形式のフィールドを追加する場合のフィールド形式は公式ドキュメントの以下のサイトに従って入力しています。

ここまでで、APIを実行する準備ができたので、右上の「送信」を実行します。

画面下のレスポンス画面上に200 OKと出れば成功です。

ここで出力されるidがkintone側のレコード番号となります。

kintone側を確認すると、以下のようにレコード番号4にQiitaのアイコン画像が登録されていることを確認できました。

◇Postmanコレクションランナーを使った動作確認

ここまでのやり方の場合、手動でAPIを2回実行する必要があり、さらに1回目のリクエストのレスポンス内容(fileKey)を基に変数を書き換える必要がありました。

そこで、最後にPostmanが提供するスクリプト機能とコレクションランナー機能を使って、この作業を自動化してみます。

注意
アップロードする画像は固定（事前に設定した画像ファイル）です。

Postmanスクリプト機能

Postmanスクリプト機能には、リクエスト実行前に処理されるPre-requestとリクエスト実行後に処理されるPost-responseがあります。

この辺の詳細は、以下サイトに掲載されている資料や動画が参考になります。

今回は、Post-response機能を使います。
ファイルアップロードのリクエスト実行後のレスポンスに含まれる、fileKeyの内容を取得し、変数に格納します。

「ファイルをアップロードする」リクエスト側の「スクリプト」タブ-「Post-response」を選択します。

スクリプト入力欄に以下の内容で記述します。

const responseJson = pm.response.json();
const fileKey = responseJson["fileKey"];

pm.collectionVariables.set("fileKey", fileKey);

pm.test("Response status code is 200", function () {
    pm.response.to.have.status(200);
});

レスポンスで返ってくるJSONデータの中から、fileKeyの中身を取り出し、コレクション変数であるfileKeyの中に代入しています。

最後に、保存して完了です。

Postmanコレクションランナー

次に、コレクションランナー機能を使って、2つのリクエストを順に実行させます。

コレクションランナーはコレクション内のAPIを実行するための仕組みで、APIテストなどを行うための機能です。
こちらも、詳細は以下サイトに掲載されている資料や動画が参考になります。

コレクションランナーを実行する場合、コレクション右側にある三点リーダーから、「コレクションを実行」を選択します。

コレクションランナーの設定画面では以下のように設定します。
リクエストの実行順序だけ注意し、後は基本的に初期設定（マニュアル実行、実行回数1回）でOKです。

設定が終わったら、「Run kintone」を実行し、結果を待ちます。

実行結果画面では、2つのリクエストの結果が200 OKになっていることを確認します。
また、1つ目のリクエストのレスポンスのfileKeyの内容が変数に格納されていることも確認します。

今回も最後にkintone側でレコードが追加されていることを最後に確認すれば成功です。

◇おわりに

今回は、Postmanを使って、kintoneに画像ファイルをアップロードする手順をまとめました。
次のステップとして、iPhoneショートカットを使って、同様に画像ファイルをアップロードする記事をまとめたいと考えています。
最終的には、以前LTした以下の内容について、その手順をQiitaの記事にまとめる予定です。

たぶん、あと2つ記事を書く必要がありそう・・・（続編を公開したらここにリンクを貼ります）

🔚END