Memsource REST API を利用することも可能です。詳細は「Memsource REST API の概要」をご参照ください。
この記事では、API コールのサンプルを含む単純な API シナリオをご紹介し、さらにそれらを組み合わせることで簡単なアクションを Memsource API のみで完了させる方法について説明します。
各セクションでは、簡単なシナリオを例に API コールのサンプルをご紹介し、さらに正確な API コールおよび追加の情報を確認できるリンクも掲載します。ただし、API でできることは非常に豊富なので、この記事ですべてを扱うことはできません。API で利用できるすべての機能について詳しくは、Memsource API マニュアルの各セクションを参照してください。
ここで紹介するレスポンスは、シナリオに関連する情報のみを抜粋したサンプルです。完全なレスポンス、およびそれに含まれる情報の範囲については、上記のマニュアルを参照してください。
これらのシナリオは、Postman という Google Chrome 拡張機能やアプリケーションでテストすることができます。
概要
この記事で取り扱うシナリオは、以下の通り進行します。
まずは、ユーザーが任意の操作を実行できるように自身を認証します（ログインに相当するAPI）。続いてのステップは、シンプルなプロジェクトの作成、ジョブのアップロード、リンギストのアサイン、そしてそれに関連したメール通知です。エディタの種類を問わず、実際の翻訳作業は、この API シナリオに含まれていません。アサインされたリンギストによって翻訳が完了した時点からシナリオの続きとなり、プロジェクトのステータスを「完了」に変更し、完成したドキュメントをプロジェクトからダウンロードするところまでを説明します。
メソッド
Memsource のコールは、GET メソッドと POST メソッドの両方をサポートしています。Memsource API ユーザーマニュアルも参照しながら、ご自身でより適切なメソッドを選択してください。
GETの場合：https://cloud.memsource.com/web/api/v3/project/list?token=lJtc9C8srT....
POSTの場合：https://cloud.memsource.com/web/api/v3/project/list に加えてボディでパラメータを送信します。
POST メソッドでは、URL とボディのパラメータを組み合わせることができます。たとえば、トークンを URL に含め、他のパラメータをボディで送信できます。
例えば「ジョブの作成」などでは、ボディでファイルを送信するため POST メソッドが必須であることにご注意ください（GET メソッドでは実行できません）。
Postman で API をテストする方法
添付のスクリーンショットには、Postman で下記の API シナリオをテストする方法が記入されています。
ステップ 1：認証
認証には2つの方法があります。
- 認証 API コール - 24時間有効な認証トークンを生成するコールです。生成したトークンを、以下の API すべてに含める必要があります。これにより、ユーザーが認証され、アカウント内で他の操作を実行できるようになります。
- oAuth 2.0 - 特定のアプリケーションを Memsource に認証させることができます。これにより、次回以降の認証が不要になり、Memsource との継続的な通信が可能になります。
このシナリオでは、認証トークンを利用する1つ目の方法を用います。このトークンは、以下のすべての API コールに必要であり、サンプルのパラメータには含まれていません。
自身を認証するには、API コール api/v3/auth/login および適切なパラメータ（この場合はユーザー名とパスワード）を使用します。
- コールの例：https://cloud.memsource.com/web/api/v3/auth/login?userName=USERNAME&password=PASSWORD
- レスポンス：認証トークン
ステップ 2：プロジェクトの作成、インポート、アサイン
プロジェクトの作成は、API コール api/v3/project/create を通じて行われ、name、sourceLang、targetLang が必須のパラメータです。
- コールの例：https://cloud.memsource.com/web/api/v3/project/create?token=AUTHENTICATION TOKEN&name=PROJECT&sourceLang=ja&targetLang=en
- レスポンス：Project UID（例：KmtNyVlz1skQd2aMVEipp7）
上記のコールで取得した UID を利用して、api/v8/job/create に必須パラメータの project、targetLang、file を含めることで、新しく作成されたプロジェクトに新規ジョブを直接追加することができます。
このコールには、オプションのパラメータとして Linguist を含めることもできます（下記の例にはリンギストが含まれています）。このパラメータを含まない場合は、ジョブをアサインするために別のコール（api/v8/job/edit）が必要になります。コールに含めるリンギストの ID は、複数の方法で取得できます。
- Memsource Cloud で、ユーザーのページを開き、API を使用してアサインしたいリンギストの名前をクリックします。リンギストの ID が URL の一部としてアドレスバーに表示されます（例：https://cloud.memsource.com/web/user/show/94573）。
- API コール api/v3/user/getByUserName およびパラメータ username を使用します。
- API コール api/v3/user/listを使用します。この API コールはパラメータを必要とせず、アカウント内のすべてのユーザーのリストが返されます。レスポンスにはユーザー名と ID の両方が含まれます。
- コールの例：https://cloud.memsource.com/web/api/v8/job/create?token=AUTHENTICATION TOKEN&targetLang=en&project=KmtNyVlz1skQd2aMVEipp7&linguist=94573
- レスポンス：JobPart ID（例：62399196）
次に、上記で取得した JobPart ID と、使用したいメールテンプレートの ID を表すパラメータ emailTemplate を、api/v8/job/notifyAssignedLinguist で使用します。メールテンプレートの ID は、Memsource Cloud の UI もしくは api/v2/emailTemplate/list から取得できます。
- コールの例：token=AUTHENTICATION TOKEN&jobPart=62399196&emailTemplate=7303
- レスポンス：なし
ここまで完了すると、Memsource Cloud の UI で一連の作業を行った場合と同様に、リンギストは自分のアカウントで作業を開始することができます。ジョブが終了すると、担当の PM に通知が届き、シナリオのステップ 3 を開始できます。コールバック（webhooksの詳細をご参照ください）により以下のステップを自動的に開始することも可能ですが、この記事では単純なシナリオを例にします。
ステップ 3：プロジェクトの完了、ダウンロード
ジョブ（このシナリオではプロジェクト内に1つのみ）が完了したら、必須パラメータの project と status を指定して api/v3/project/setStatus を利用することで、プロジェクト全体のステータスを「完了」に変更できます。この変更は手動によるものです。プロジェクトステータスオートメーション機能を使用すると、ステータスは自動的に変更されます。また、webhookを待機し、受け取ったコールバックに基づいて他のアクションを開始することもできます。
- コールの例：https://cloud.memsource.com/web/api/v3/project/setStatus?token=AUTHENTICATION TOKEN&project=KmtNyVlz1skQd2aMVEipp7&status=COMPLETED
- レスポンス：なし
プロジェクトが完了したら（または完了前でも）、API コール api/v8/job/getCompletedFile とパラメータ jobPart を使用して、翻訳済みのファイルを取得できます。
- コールの例：https://cloud.memsource.com/web/api/v8/job/getCompletedFile?token=AUTHENTICATION TOKEN&jobPart=62399196
- レスポンス：バイナリ形式の完了ファイル