kintoneの「現在の作業者」をPostmanでどうにか一括更新する

# はじめに
## この記事の概要
- kintoneにはcsvでレコードを一括更新する機能が備わっていますが、プロセス管理を有効にした際の「現在の作業者」を一括更新する手段がありません。
    - 例えばあるアプリの作業者に組織を指定している場合、あとから組織に追加されたユーザーは既存のレコードの「現在の作業者」としては自動的に追加されてくれません。
- そこで既存のレコードの「現在の作業者」を一括で更新したいと考えますが、唯一の一括更新手段であるcsv読み込みでは「現在の作業者」を更新できません。(ちなみに「ステータス」も同様)
    - 参考：https://jp.cybozu.help/k/ja/id/040770.html#import_records_app_to_import_1020
- JavaScriptを駆使すればkintone APIを通して一括更新できますが、たった一度の作業のためにいちいちコードを書きたくない・・・というようなシーンでお役に立てる記事かと思います。
- kintoneの仕様については、執筆時点 (2023/04/17) のものに従いました。

:::note warn
ご利用は自己責任でお願いいたします。
:::

## 想定している読者
- kintoneのレコードについて、「ファイルを読み込む」で更新できない項目を一括更新したい人
- HTTP周辺の用語をある程度理解している人

## 用意するもの
- [Postman](https://www.postman.com/downloads/)
    - この記事ではWindows版 v10.12.13を利用しています。

# 手順
## 0. kintone側 (事前確認・準備)
- こんなアプリを例にしてみます。(5件くらいなら手動で更新した方が早いですが・・・。)
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2349419/29185d33-8251-1ea0-a39a-35cba64e6caa.png)
    - 今はすべて作業者が「てすと」のみとなっていますが、ここに後から「保守運用担当」に異動してきた「hoge」さんを承認者として追加していきたいと思います。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2349419/87dadff8-f4a8-9739-1b78-014db3cf7be4.png)

### 0-1. 権限の確認
- 今回はPostmanを利用してAPIでkintoneのレコードを更新しますが、そもそも更新に利用しようとしているユーザーが対象のアプリについてkintoneのレコード編集権限を付与されているか確認してください。
    - 認証方法によって確認ポイントが変わりますが、この記事ではパスワード認証を利用しますのでレコード更新権限を持っていることが必須になります。
    - 今回の例では「てすと」というユーザーを利用するので、「てすと」というユーザーにレコードの更新権限が付いているかを確認します。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2349419/eae5ce48-5cef-855b-7d8c-1d1d0458eee2.png)

### 0-2. 更新対象レコード情報の取得
- 一括更新したいアプリから、更新対象のレコードの「レコード番号」をファイルに書き出してください。
    - 「レコード番号」だけで大丈夫です。
    - [文字コード] を「Unicode (UTF-8)」で出力しておくと後々楽になります。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2349419/35f749c4-c5bf-932f-b668-346be8fc09d4.png)

## 1. Postman側
### 1-1. 起動
- 事前準備・確認が終わったらいざPostmanの操作に移ります。起動すると下記の画面が表示されます。
- そもそもアカウントをもっていないという方は [Create Free Account] でアカウントを作成するか、左下の [Skip and go to the app] をクリックしてアカウントなしで進みましょう。
    - アカウントを作成するとブラウザ版と作業内容を共有したりできます。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2349419/418358a3-15fa-faf6-dde6-b6b7f5316fd5.png)
- サインインするかアカウント作成をスキップすると、下記のような画面が表示されます。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2349419/0ff4fbe3-122b-0e84-3feb-fd5eca9cf536.png)

### 1-2. Collectionの作成
- まずは左メニューの [Collections] が選択された状態で、左上の [+] ボタンをクリックまたは [Create Collection] のリンクをクリックしてCollectionを作成します。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2349419/e58467da-8714-0f5a-e0f4-11df17b089e9.png)
    - 名前は任意です。あとで内容を把握しやすいよう、「kintone bulk update」などとしておくと良いかもしれません。
    - [Type] は「No Auth」のままで大丈夫です。(他もデフォルトのまま)
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2349419/ab6d583f-07b3-9e75-5901-1a3aca083f63.png)

### 1-3. requestの作成
- 続いて、実際にkintone APIにアクセスするためのrequestを作成しましょう。
    - [collections] に追加した「kintone bulk update」を展開して表示される [Add a request] リンクをクリックするか、「kintone bulk update」のマウスオーバーで表示されるメニュー [...] から、[Add request] をクリックします。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2349419/21ec0b95-70c1-413b-a45c-c8857682018a.png)
- 名称はやはり任意ですが、ここでは「update assignees」としておきます。
- まずリクエストメソッドを「GET」から「PUT」に変えておきましょう。
    - なお[レコードの作業者を更新する](https://cybozu.dev/ja/kintone/docs/rest-api/records/update-assignees/)APIを利用します。
- URLは「https://{サブドメイン}.cybozu.com/k/v1/record/assignees.json」です。
- また、[Headers] に次の値を設定します。
        - X-Cybozu-Authorization：`ログイン名:パスワード`を Base64 エンコードした値
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2349419/c6f67da8-e90e-a28d-a7af-6f83a0cc4084.png)


- 仕上げに、[Body] を作成します。
    - [Body] から「raw」を選択し、以下を入力します。形式が「Text」になっている場合は「JSON」を選択してください。(下記画像の「JSON」になっている箇所)
```json
{
    "app": 451,
    "id": {{レコード番号}},
    "assignees": [
        "test",
        "hoge"
    ]
}
```
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2349419/fc3a382b-0056-6f40-f74d-250cf8ec8105.png)


- 簡単に解説しておくと、それぞれ以下の通りの意味です。
    - app：対象となるアプリID
    - id：0-2. で出力した「レコード番号」を代入するための変数
    - assignees：作業者 (ログイン名) の配列
- 特に注意が必要なのは [assignees] で、「現在の作業者」がこの値の通りに上書きされます。追加ではないことに注意してください。
:::note warn
そんなニーズは滅多にないと思いますが、このAPIでは100を超える作業者を設定できません。その場合は手動で更新するより他ないと思います。
:::

### 1-4. Testsの設定
- ここまでで一括更新の準備はほとんど終わりましたが、最後に念のためTestsの設定をしておきます。
    - 「update assignees」内の[Tests]タブをクリックし、テストコードを記述します。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2349419/cddcb3b5-4ad5-55bc-c7eb-c2343d3c7aa0.png)
- これは実行結果が成功したか失敗したかを視認しやすくするための設定です。
- そんなに厳密にテストしたいわけではないので、下記くらいを設定しておきます。

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

pm.test("Body has revision", function () {
    pm.expect(pm.response.json()['revision']).to.match(/[0-9]+/);
});
```

- ここでは細かく解説しませんが、興味のある方は[公式サイト](https://learning.postman.com/docs/writing-scripts/test-scripts/)にて確認してください。
- それぞれ、「レスポンスのステータスが200であること」「レスポンスに『revision』が含まれ、その値が数値であること」をテストしています。

### 1-5. Collectionの実行
- 最後にいよいよCollectionの実行です。
- 左側の「kintone bulk update」をマウスオーバーして表示されるメニュー [...] から、 [Run Collection] をクリックします。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2349419/318848a1-93fe-7c8c-7071-9c1662ea58e7.png)

- すると [Runner] タブが表示されますので、それぞれ次のように入力・選択します。
- Delay：100ms (任意の値)
    - 各リクエスト間の間隔です。行数が多い場合はkintoneに負荷をかけないよう、500msなど大きめの数字にしておきます。(その分全体の実行時間は長くなってしまいますが。)
- Data：0-2. で出力したcsvファイル
    - ファイルを選択すると [Iterations] に自動で行数が設定されます。
    - [Preview] でファイルの内容がプレビューできます。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2349419/09e6e3a4-39d9-59a9-3f10-7416c6a091a3.png)
- ではいよいよ [Run kintone bulk update] ボタンをクリックして処理を開始してみましょう。
- 個々のリクエストが成功していれば、下図のように [Tests] に設定したテストの結果が出力されます。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2349419/0a98b16b-d516-dd92-dfe0-5db54f12fc13.png)
- [View Summary] をクリックするとサマリに切り替わります。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2349419/1a24b8f4-f738-cfe0-69d2-1159724ddf89.png)
- 今回は5レコードに対して一括処理を実行したので、[Passed] が (10) ですべて成功していることがわかります。 (1レコードにつきテスト2つ設定しているため 2*5=10)
- ちなみにリクエストが失敗した場合は下記のように「Fail」の文字とエラーメッセージが出力されるので、解析して再実行します。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2349419/1036fef1-2779-7e6d-2ee0-1d232f1bb53c.png)

## 2. 結果
- 無事すべてのレコードに作業者「hoge」が追加されました。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2349419/235079e6-97f2-c4af-adc3-ba2b77efd6ab.png)

## 3. 最後に
- この方法を使えば、ステータスの一括更新も可能です。
- 0-2. で更新対象レコードを抽出しますが、抽出後に他のユーザーがレコードを更新した場合、一括更新で意図しない結果になる可能性があります。
    - その場合はレコードのリビジョン番号を指定して更新すれば意図しない更新を避けることができます。
    - ただしリビジョン番号の取得にはひと手間必要ですので、一括更新作業の際は可能であればそのアプリの利用を一時止めてもらうという方が現実的かも知れません。
        - リビジョン番号を指定する場合、Postmanのrequestには下記を指定します。
        - csvの方には「リビジョン番号」列が必要になります。kintoneの「ファイルに書き出す」では出力されませんので、[複数のレコードを取得する](https://cybozu.dev/ja/kintone/docs/rest-api/records/get-records/)APIなどで取得する必要があります。
```json
{
    "app": 451,
    "id": {{レコード番号}},
    "revision": {{リビジョン番号}},
    "assignees": [
        "test",
        "hoge"
    ]
}
```
以上。