これは、サンプルAPI呼び出しとそれらを連結して単純なアクションを完了する方法に関するシンプルなAPIシナリオです。APIを介して設定できるオプションは広範囲にわたります。利用可能なすべてのオプションについては、REST APIドキュメントの該当セクションを参照してください。
このシナリオを作成するために、Postman APIプラットフォームが使用されました。
これらの例では、標準リクエストURLはhttps://cloud.memsource.com
で始まります。米国データセンターの組織がAPIを使用する場合、リクエストURLはhttps://us.cloud.memsource.com
で始まる必要があります。
シナリオ
-
認証
ユーザーは認証されます(APIのログインに相当します)。
-
作成
シンプルなプロジェクトの作成、アップロードされたジョブ、およびメール通知付きのリンギスト割り当て。
-
翻訳
APIシナリオの外で行われる翻訳作業(任意のエディタで)。
-
API機能
割り当てが完了すると(リンギストによって完了としてマークされる)、プロジェクトのステータスは完了に設定され、完了したドキュメントがプロジェクトからダウンロードされます。
方法論
各個別のREST API呼び出しには、適切なメソッドがリストされています。不正なメソッドを使用すると(例:プロジェクト作成呼び出しでPOSTの代わりにGET)、API呼び出しが失敗します。
ステップ1:認証
認証方法は2つあります:
-
24 時間有効な認証トークンを生成します。トークンはすべての次の API に挿入する必要があります。トークンはユーザーを検証し、プロファイル内の他のすべての機能を実行できるようにします。
-
アプリケーションの検証を可能にします。検証されたアプリケーションは継続的に通信し、追加の認証は必要ありません。
このシナリオでは、認証 API コールが使用されます。生成されたトークンはすべての次の API コールに必要であり、例のパラメータにはリストされていません。
認証には、必要なパラメータを使用して ログイン API を使用してください。この場合、ユーザー名 と パスワード が必要です。
-
メソッド
POST
-
リクエスト URL
https://cloud.memsource.com/web/api2/v3/auth/login
-
リクエストボディ:
{ "userName":"username", "password":"password"}
-
レスポンス
認証トークン
複数の TMS 組織のメンバーは、複数のアカウントに対して同じユーザー名とパスワードを持っています。この場合、userUid
をリクエストボディに追加して、ユーザーがログインしたい組織を指定する必要があります。指定されていない場合、ユーザーは指定されたユーザー名とパスワードに関連付けられたデフォルトアカウントにログインします。
ステップ 2:プロジェクトの作成、インポート、および割り当て
プロジェクトの作成
プロジェクト API コールを使用して、必須パラメータ 名前、ソース言語、および ターゲット言語 を使用してプロジェクトを作成します。
-
メソッド
POST
-
リクエスト URL
https://cloud.memsource.com/web/api2/v3/projects
-
リクエストボディ
{ "name":"My project", "sourceLang":"en", "targetLangs":[ "de","fr" ]}
-
レスポンス
プロジェクト UID (例: KmtNyVlz1skQd2aMVEipp7)
最後のコールからのプロジェクト UID を使用して、プロジェクトテンプレートを作成
API コールを使用してプロジェクトテンプレートを作成することができます。
-
メソッド
POST
-
リクエスト URL
https://cloud.memsource.com/web/api2/v1/projectTemplates
-
リクエストボディ
{ "project": { "uid": "string" }, "name": "string", "importSettings": { "uid": "string" }, "useDynamicTitle": true, "dynamicTitle": "string" }
-
レスポンス
プロジェクトテンプレート UID (例: AmtNyVlz1skQd2aMVEipp8)
プロジェクトを作成する最も効率的な方法は、プロジェクトテンプレートを使用することです。最後のコールからのプロジェクトテンプレート UID を使用して、テンプレートからプロジェクトを作成 でプロジェクトテンプレートの設定に基づいて新しいプロジェクトを作成します。
式 {templateUid}
は、取得したプロジェクトテンプレート UID が挿入されるリクエスト URL のプレースホルダーとして機能します。
-
メソッド
POST
-
リクエスト URL
https://cloud.memsource.com/web/api2/v2/projects/applyTemplate/oNQiljwTGHpd2l1nnQRiu4
-
リクエストボディ
{ "name": "string", "sourceLang": "string", "targetLangs": [ "string" ], "workflowSteps": [ { "id": "string" } ], "dateDue":"2019-08-24T14:15:22Z", "note": "string", "client": { "id": "string" }, "businessUnit": { "id": "string" }, "domain": { "id": "string" }, "subDomain": { "id": "string" }, "costCenter": { "id": "string" } }{ "project": { "uid": "string" }, "name": "string", "importSettings": { "uid": "string" }, "useDynamicTitle": true, "dynamicTitle": "string" }
-
レスポンス
プロジェクト UID (例: BmtNyVlz1skQd2aMVEipp9)
ジョブの作成
最後のコールからのプロジェクト UID を使用して、新しいジョブを ジョブを作成 を使用して新しく作成されたプロジェクトに直接追加できます。
式 {projectUid}
は、取得したプロジェクト UID が挿入されるリクエスト URL のプレースホルダーとして機能します。ジョブ作成 API コールを使用すると、リクエストの ヘッダー を変更して、Phrase が要求するものと一致させる必要があります(他のコールでは、Postman が自動的にリクエストに適切なヘッダーを追加します)。
すべてのインポートパラメータは、カスタム Memsource ヘッダーに挿入する必要があります。
コンテンツ-ディスポジション ヘッダーには、インポートリクエストを正しく処理するために、事前定義された形式のファイル名を含める必要があります。
ソースファイルをインポートするには、本文に移動し、
を選択すると、 オプションが表示されます。-
メソッド
POST
-
リクエスト URL
https://cloud.memsource.com/web/api2/v1/projects/KmtNyVlz1skQd2aMVEipp7/jobs
-
(ヘッダー) コンテンツ-ディスポジション
filename*=UTF-8''file.txt
-
(ヘッダー) Memsource
{"targetLangs":["de","fr"]}
-
(ヘッダー) コンテンツ-タイプ
application/octet-stream
-
レスポンス
ジョブUID(例:dOYgeXzAdAbj4xFjuEVZP2)
AsyncRequest UID
非同期リクエストを取得を使用して、ジョブ作成呼び出しからの非同期リクエストUIDを使用して、ジョブが正常に作成され、機能していることを確認します。
返されたジョブUIDは、プロジェクトの各ワークフローステップで一意です。したがって、ジョブがワークフローを持つプロジェクトで作成されると、応答は各ワークフローステップに対して一意のジョブUIDを返します。
再利用可能なインポート設定は、インポート設定を作成呼び出しで構成できます。作成ジョブ呼び出しで使用できるインポート設定UIDが応答で受信されます。
プロバイダをジョブに割り当てるには(作成ジョブ呼び出しで直接割り当てられていない限り)、ジョブを編集呼び出しを使用します。
呼び出しに挿入されたプロバイダのIDは、2つの方法で取得できます:
-
フレーズアプリケーションからIDを取得するには、次の手順に従います:
-
使用する ユーザー一覧 APIコール。
この API コールはパラメータを必要とせず、アカウント内のすべてのユーザーのリストが返されます。レスポンスにはユーザー名と ID の両方が含まれます。
オプションのパラメータ、ユーザー名をクエリに追加することで、特定のユーザー名を持つユーザーのみを一覧表示できます。
割り当てられたユーザーに通知する
ジョブUIDは、割り当てられたユーザーに通知するコールのオプションパラメータとして使用でき、使用するメールテンプレートのIDを表すメールテンプレートパラメータと共に使用されます。これは、メールテンプレート一覧コールを使用することで取得できます。
-
リクエスト URL
https://cloud.memsource.com/web/api2/v1/projects/KmtNyVlz1skQd2aMVEipp7/jobs/notifyAssigned
-
レスポンス
空 (ステータス204:コンテンツなし)
ここが翻訳者が自分のプロファイルで作業を開始する場所であり、Phrase UIが使用されているかのように作業します。ジョブが完了すると、担当のPMが通知を受け取り、シナリオの次の部分が開始されます。コールバックは、ウェブフックを介してインターセプトされ、シナリオの次の部分を自動的に開始できますが、この例では扱いません。
ステップ3:翻訳された(完了)ファイルをダウンロードし、プロジェクトを完了に設定する
翻訳されたファイルをダウンロードする
このシナリオは、翻訳者が自分の任務を完了する(ジョブを完了としてマークする)という前提で機能しますが、完了したファイルはいつでもダウンロードでき、ジョブは完了ステータスである必要はありません。
翻訳されたファイルをダウンロードするには、2つのAPIコールが必要です:ターゲットファイルをダウンロード(非同期)と非同期リクエストに基づいてターゲットファイルをダウンロードコール。
最初のステップは、ターゲットファイルをダウンロード(非同期)をプロジェクトUIDとジョブUIDパラメータで呼び出すことです。複数のワークフローステップを持つプロジェクトから完了したファイルをダウンロードする場合は、完了したファイルをダウンロードしたい特定のワークフローステップからのジョブUIDを使用してください。例えば、改訂ワークフローステップです。
-
Phraseアプリケーションから特定のワークフローステップのジョブUIDを取得するには、次の手順に従ってください:
-
プロジェクトを開く。
-
ジョブテーブルで、ダウンロードしたい完了ファイルのワークフローステップに切り替えます。
-
ブラウザから/jobの後のURLのユニークな部分をコピーします。
-
-
使用する ジョブ一覧 APIコール。
このエンドポイントは、指定されたプロジェクト内のジョブの一覧を返します。
workflowLevel
クエリパラメータを使用してコールします。このパラメータは、返されたジョブが属するワークフローステップを示す非ゼロベースのパラメータです。指定しない場合、その値はデフォルトで1
(=最初のワークフローステップ)に設定されます。例えば、リビジョンステップからジョブを取得する必要がある場合、そのステップの番号をクエリパラメータに指定します。すなわち2
。
ダウンロードターゲットファイル(非同期)コールは、翻訳を含むターゲットファイルを生成してダウンロードする非同期リクエストを開始します。レスポンス内でターゲットファイルを直接提供するのではなく、次のコールに必要なasyncRequestIdを提供します。
-
メソッド
PUT
-
リクエスト URL
https://cloud.memsource.com/web/api2/v2/projects/KmtNyVlz1skQd2aMVEipp7/jobs/dOYgeXzAdAbj4xFjuEVZP2/targetFile
-
レスポンス
AsyncRequest ID
レスポンスからのasyncRequestIDを使用して非同期リクエストを取得する。リクエストが完了したか確認します。非同期リクエストが完了したら、非同期リクエストに基づいてターゲットファイルをダウンロードするコールを使用してターゲットファイルをダウンロードできます。asyncRequestIdは一度だけ使用できます。ダウンロードが開始されると、asyncRequestIdは今後の使用のために無効になります。
-
メソッド
取得
-
リクエスト URL
https://cloud.memsource.com/web/api2/v2/projects/KmtNyVlz1skQd2aMVEipp7/jobs/dOYgeXzAdAbj4xFjuEVZP2/downloadTargetFile/1291716982
-
レスポンス
完了したファイル自体のバイナリレスポンス
プロジェクトを完了に設定
プロジェクトを完了するために、プロジェクト内のジョブが完了したら、必須パラメータプロジェクトUIDとステータスを使用して、プロジェクトのステータスを編集する呼び出しを行い、プロジェクト全体のステータスを完了に変更します。この変更は手動ですが、プロジェクトステータス自動化が使用されると、ステータスは自動的に変更されます。ウェブフックを待機し、受信したコールバックに基づいて他のアクションを開始することも可能です。
-
メソッド
POST
-
リクエスト URL
https://cloud.memsource.com/web/api2/v1/projects/KmtNyVlz1skQd2aMVEipp7/setStatus
-
リクエストボディ
{ "status":"COMPLETED"}
-
レスポンス
空 (ステータス204:コンテンツなし)