Amazon Mechanical Turkを使う時に知っておくべき知識集

# はじめに

以下では、Amazon Mechanical Turk (MTurk)上で使われる様々な概念について説明を記しておきます。
意味を知りたい時に辞書として引いたり、注意事項が知りたい時に読んでもらえると幸いです。

なお、下記のコンテンツはある程度プログラミングの知識があるリクエスタ視点で書かれています。
一部[Amazon Mechanical Turk API](https://docs.aws.amazon.com/ja_jp/AWSMechTurk/latest/AWSMturkAPI/)の知識を伴いますので、適宜公式ドキュメントも合わせてご参照ください。

<font color="red">書きかけの記事です。随時更新していきます。</font>

# 用語

## Requester

#### 定義

リクエスターと読みます。HIT（マイクロタスク）を所有し、ワーカーに対して依頼するユーザー。

#### アカウント作成

[ここ](https://requester.mturk.com/begin_signin)（Sandboxは[ここ](https://requestersandbox.mturk.com/begin_signup)）から。Amazon.com（日本のAmazon.co.jpとは異なる）のアカウントでログインし、そこへMTurkリクエスタ用アカウントを別途作成して紐付けることになります。

## Worker

#### 定義

ワーカーと読みます。HITを作業し、報酬を受け取るユーザー。2021年1月現在、日本からも登録が可能。
稼いだ報酬は銀行口座に米ドル、またはAmazon.comギフトカードとして換金できる[^1]。

#### アカウント作成

[ここ](https://worker.mturk.com/)（Sandboxは[ここ](https://workersandbox.mturk.com/)）から。リクエスタと同様、Amazon.com（日本のAmazon.co.jpとは異なる）のアカウントでログインし、そこへMTurkワーカー用アカウントを別途作成して紐付けることになります。
**本番アカウントの承認には2日ほどかかる場合があるので注意。**

[^1]: Amazon Mechanical Turk FAQs - How do I get paid? https://www.mturk.com/worker/help

## HIT

#### 定義

ヒットと読みます。MTurkにおいてワーカーが実際に作業を行い報酬を得るという手順を踏むための最小単位で、実体としては１つの静的なウェブページを指します。

ワーカーは普段、以下のような**HITグループ（後述）**の一覧ページから、

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/1052741/51088c2b-4a87-1761-d68a-4d4e5818c9a0.png)

あるグループにて公開されているHITを確認（**Discover**）したのち、そのHITの１つを試し見（**Preview**）するか、あるいは回答権を取得（**Accept**）します。その時、以下のような画面が提示されます。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/1052741/553b5ad6-9e5d-9ddf-533c-bb32018622da.png)

ここでは、「Receipt Transcription」というHITグループに含まれる、1万を超えるHITのうちの１つ（ランダムに選ばれる）がページ内のIFrameとして組み込まれて表示されます。このHITで作業し回答を提出（**Submit**）した結果が、UI上部に示された額の報酬が支払われる対象となります。この時ウェブページ全体が一度リロードされ、他のHITの回答権がまだあれば、それらのうちどれか一つがランダムに選ばれて表示されます。

## Sandbox

#### 定義

本番環境のプラットフォーム（本物のワーカーへタスクを依頼する場所）とそっくりに作られたテスト環境。リクエスタ側・ワーカー側どちらも存在するが、いずれもリクエスタが開発作業中にテストできるようにすることを目的として用意されています。**本番環境とは別にMTurkアカウントの作成が必要です**。

Sandboxプラットフォームに入ると、以下のようにページ上部にオレンジ色の帯が入るのが目印。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/1052741/65ca6676-f829-f8d7-a4fd-ed90ade2b6d1.png)

#### 留意事項

<font color="red">**HITを開発して本番環境に公開する前に、必ずSandboxで動作テストをしましょう。**</font>開発したHITのウェブページは、バグや不具合を含むことで、**Submitに失敗する・Submitボタンが押せない・メディアがリンク切れしている・制限時間の設定が短すぎる**　など、エラーが非常に発生しやすいです。
ここを怠ると、数々のワーカーからのメールへの返信と補填の作業に追われることになります。

## Assignment

[公式ドキュメント](https://docs.aws.amazon.com/ja_jp/AWSMechTurk/latest/AWSMturkAPI/ApiReference_AssignmentDataStructureArticle.html)

あるHITにおける、あるワーカーの作業情報を指します。HITがAccept/Submit/承認（**Approve**）または棄却(**Reject**)されたときのタイムスタンプや、回答内容そのものの情報を持っています。

AssignmentIdは、ワーカーがHITをAcceptしたタイミングで発行されます。**ただし、そのAssignmentにおいてHITがSubmitされない限り、APIからは参照不可能です（存在しないものとして扱われる）。**

HITとAssignmentの関係は**１対多**です。Assignmentの数は、0以上かつHITの`MaxAssignments`の数以下となります。

<font color="darkgrey">以前、同じようなタイミングで同じHITをAcceptした異なるワーカーに同一のAsssignmentIdが振られた事例があった気がした... おそらくMTurkのバグ？</font>

## HITGroup

## HITType

## HITLayout

## HIT#Question

## Qualification

# MTurk API

## Operations

注意事項があるもののみ記載しています。
全てのOperationリストは[こちら（公式ドキュメント）](https://docs.aws.amazon.com/ja_jp/AWSMechTurk/latest/AWSMturkAPI/ApiReference_OperationsArticle.html)。

### AssociateQualificationWithWorker [[doc]](https://docs.aws.amazon.com/ja_jp/AWSMechTurk/latest/AWSMturkAPI/ApiReference_AssociateQualificationWithWorkerOperation.html)

Qualificationをワーカーに付与する。

- 付与したらワーカーにメールで知らせる`SendNotification`がデフォルトで有効化されている。

### CreateHITWithHITType [[doc]](https://docs.aws.amazon.com/ja_jp/AWSMechTurk/latest/AWSMturkAPI/ApiReference_ApproveAssignmentOperation.html)

HITTypeを作成する。`CreateHIT`するときに指定するとパラメータが少なくなって楽。

- 消す方法が用意されてない。

### GetAccountBalance [[doc]](https://docs.aws.amazon.com/ja_jp/AWSMechTurk/latest/AWSMturkAPI/ApiReference_GetAccountBalanceOperation.html)

リクエスターアカウントのプリペイド残高を取得する。

- Sandboxの場合、いつも$10000.00が返る。
- プリペイドではないAWS Billingに支払い方法を変更した場合、いつも$0.00が返る。

### ListHITs [[doc]](https://docs.aws.amazon.com/ja_jp/AWSMechTurk/latest/AWSMturkAPI/ApiReference_ListHITsOperation.html)

作成したHIT一覧を返す。

- 日時**昇順**。
- `MaxResults`（一度に返すHIT件数）の上限は100。
- （`ListHITs`に限ったことではないが）`MaxResults`に収まりきらなかったデータは、その時返ってきた`NextToken`を次の実行の`NextToken`パラメータに渡せばOK。一番後ろにたどり着いた時点で`NextToken=None`となる。

### NotifyWorkers [[doc]](https://docs.aws.amazon.com/ja_jp/AWSMechTurk/latest/AWSMturkAPI/ApiReference_NotifyWorkersOperation.html)

ワーカー（複数可）にメールを送る。

- 一度も自分のHITをSubmitしたことがない（＝いずれのHITにもAssignmentの記録が存在しない）ワーカーには送れない。
- ワーカーからメールが来たor返ってきた時には直接メールに返信でOK。

### RejectAssignment [[doc]](https://docs.aws.amazon.com/ja_jp/AWSMechTurk/latest/AWSMturkAPI/ApiReference_RejectAssignmentOperation.html)

ワーカー回答を棄却する（＝報酬を支払わない）。

- 棄却した後も、**回答から30日以内かつHITが消えていなければ**、`ApproveAssignment`を`OverrideRejection=True`で実行すれば承認できる。

### SendBonus [[doc]](https://docs.aws.amazon.com/ja_jp/AWSMechTurk/latest/AWSMturkAPI/ApiReference_ListHITsOperation.html)

ワーカーにボーナス（追加の報酬）を支払う。

- 回答を受け付けた後でないと実行できない。（`AssignmentId`パラメータが指定できないので）
- メールの文面にそのまま載る`Reason`パラメータで、ボーナス額の根拠をしっかり示してあげるのを推奨。
- 「基本報酬を安くしてボーナスを沢山支払う」ようなHITは**バッドプラクティス**。本当に払ってくれるかどうか疑わしいお金は金額に関わらずワーカーに好まれない。基本報酬は満足ラインで保証した上で、報酬額が満たなかった場合に補填したり、良い働きをしたワーカーに**チップ的感覚で払う**のが健全な使い方。

### UpdateExpirationForHIT [[doc]](https://docs.aws.amazon.com/ja_jp/AWSMechTurk/latest/AWSMturkAPI/ApiReference_UpdateExpirationForHITOperation.html)

HITの有効期限を変更する。

- 今すぐ有効期限切れにしたければ今より前の適当な時間を渡せばOK。