Basic から Advanced に移行する

現在 Cloud Translation - Basic（v2）を使用していて、Cloud Translation の最新の機能（用語集や AutoML モデルなど）を利用する場合は、Cloud Translation - Advanced（v3）を使用するようにアプリケーションを移行する必要があります。比較については、Basic と Advanced の比較をご覧ください。

Advanced エディションに移行するには、Identity and Access Management（IAM）と Advanced エディションのクライアント ライブラリを使用します。以降のセクションでは、移行タスクと 2 つのエディションの主な違いについて説明します。

Advanced への移行

以下の手順で、既存のアプリケーションを Cloud Translation - Basic から Cloud Translation - Advanced に更新するために必要な操作の概要を説明します。

  1. Cloud Translation - Basic API にアクセスする Google Cloud プロジェクト、アプリケーション、ユーザーのインベントリを取得します。Cloud Translation - Advanced クライアント ライブラリを使用するには、サービス アカウントを指定して更新する必要があります。
  2. アプリケーション用のサービス アカウントと認証を設定します。
  3. IAM のロールを使用して、サービス アカウントに権限を設定します。
  4. プロジェクトで Cloud Translation - Advanced を有効にします。Cloud Translation - Advanced で AutoML モデルを使用する場合は、AutoML も有効にする必要があります。詳細については、設定ガイドをご覧ください。
  5. Cloud Translation - Advanced クライアント ライブラリとメソッドを使用します。Cloud Translation - Advanced リクエストには、プロジェクト番号（またはプロジェクト ID）とプロジェクト ロケーション（global または us-central1 など）を含める必要があります。
  6. Cloud Translation - Advanced への翻訳リクエストのサイズが上限を超えていないことを確認します。
  7. 翻訳リクエストの割り当てのモニタリング計画を立てます。日ごとの割り当てと月ごとの割り当てについては、どちらの API バージョンでも同じ割り当てを共有します。
  8. 課金に影響のある変更がないかを確認します。

Advanced と Basic の主な違い

移行タスクを理解するために、次のセクションでは Advanced エディションと Basic エディションの主な違いについて説明します。

サービス アカウント

Cloud Translation - Basic の場合、API キーまたはサービス アカウントを使用して認証済みのリクエストを送信できます。

Cloud Translation - Advanced では顧客管理のリソースを必要とする機能があり、これらのリソースには IAM ロールと権限管理が必要です。このため、サービスの認証に API キーは使用できません。代わりに、Cloud Translation - Advanced の認証時には、サービス アカウントを使用する必要があります。

詳細については、設定ガイドをご覧ください。

IAM ロール

Cloud Translation - Basic でサービス アカウントを使用する場合、サービス アカウントは認証にのみ使用されます。サービス アカウントに関連付けられている権限に関係なく、Cloud Translation - Basic を呼び出すことができます。ただし、Cloud Translation - Advanced については、権限が適用されます。

Cloud Translation - Advanced を呼び出す権限をサービス アカウントに付与するには、IAM ロールを割り当てます。Cloud Translation - Advanced には、プロジェクト内の特定のリソースにアクセスできるようサービス アカウントに割り当てることができる複数の IAM ロールがあります。たとえば、サービス アカウントを使用してテキストを翻訳する場合は、roles/cloudtranslate.user ロールを割り当てます。詳細については、Cloud Translation - Advanced の詳細の IAM ロールをご覧ください。

AutoML モデルまたは Cloud Storage に依存する機能を使用する場合は、これらのサービスに適切なロールを含める必要があります。すべての IAM ロールのリストを確認するには、IAM ロールのドキュメントをご覧ください。

翻訳モデル

Cloud Translation - Basic を使用して翻訳をリクエストすると、Google は事前トレーニング済みのニューラル機械翻訳（NMT）モデルを使用します。Cloud Translation - Advanced の場合は、事前トレーニング済みの NMT モデルまたは AutoML Translation カスタムモデルを使用できます。

翻訳リクエストに使用するサービス アカウントには、NMT モデルと AutoML モデルにアクセスする権限が必要です。これは、さまざまなプロジェクトに配置できます。たとえば、メンテナンスと請求を簡素化するために、翻訳モデルを含む中央プロジェクトがあるとします。そのプロジェクトまたは他のプロジェクトのサービス アカウントで、これらのモデルを使用できますが、そのための権限が必要です。

翻訳モデルの詳細については、テキストの翻訳（Advanced）をご覧ください。

クライアント ライブラリ

Cloud Translation - Advanced のクライアント ライブラリとメソッドは Cloud Translation - Basic とは異なります。たとえば、Cloud Translation - Advanced の呼び出しにはリソース名が必要です。詳細については、Cloud Translation - Advanced クライアント ライブラリの概要をご覧いただくか、翻訳テキスト（Advanced エディション）のクイックスタートをお試しください。

リソース、プロジェクト、ロケーション

Cloud Translation - Advanced へのリクエストには、使用するリソースの名前が必要です。リソースは通常、プロジェクト名とそのロケーションを含む修飾名です。これによりリクエストが実行される場所が指定されます。たとえば、AutoML モデルの名前はリソース名です。

Google Cloud プロジェクトの名前が my-project で、リソースのロケーションが us-central1 の場合、リソースの完全な名称は次のようになります。

projects/MY_PROJECT/locations/us-central1/...

getSupportedLanguages リクエストを送信する URL は次のようになります。

https://translation.googleapis.com/v3/projects/my-project/locations/us-central1/supportedLanguages

リクエストあたりのコンテンツの上限

Cloud Translation API は短いリクエストの翻訳向けに最適化されています。リクエストの長さの推奨上限は、1 リクエストあたり 5,000 文字（コードポイント）です。ただし、含める文字数が多くなるほど、レスポンスのレイテンシが高くなります。Cloud Translation - Advanced の場合、1 リクエストあたりの最大コードポイント数は 30,000 です。Cloud Translation - Basic は最大リクエスト サイズが 10 万バイトです。

利用可能な割り当てにかかわらず、上限を超えるリクエストは Cloud Translation API によって拒否され、400 INVALID_ARGUMENT エラーが発生します。

割り当てと上限の詳細については、割り当てをご覧ください。

次のステップ

Cloud Translation - Advanced を使用して、テキストの翻訳、用語集の作成、一括リクエストの作成のいずれかを行います。