ラベル付き使用状況の報告(Advanced)

Cloud Translation API では、TranslateTextBatchTranslateTextDetectLanguage リクエストにユーザー定義ラベル(Key-Value ペア)を追加できます。リクエストの使用状況に関する情報は課金システムに転送され、そこでラベルを基準にして請求料金をフィルタリングすることで分類できます。

ユースケース

ラベルの主なユースケースとして、多数のクライアントに翻訳サービスを提供するお客様が挙げられます。1 つのプロジェクトが複数のクライアントに対して使用される場合があります。課金の際は、特定のリクエストをそれぞれのクライアントに関連付けることが重要です。ここで必要になるのがラベルです。クライアントに代わって呼び出しを行う場合は、クライアント固有のラベルをリクエストに付けます。これらのラベルは、Google Cloud の [レポート] セクションでフィルタリングするために使用できます。

ラベルの要件

リクエストに適用するラベルは、次の要件を満たす必要があります。

  • 1 つのリクエストに使用できるラベルは、最大 64 個です。
  • ラベルは、Key-Value ペアでなければなりません。
  • キーは 1 文字以上、63 文字までにする必要があります。空にすることはできません。値は 63 文字以下にします。空にすることもできます。
  • キーと値には、小文字、数字、アンダースコア、ダッシュのみを使用できます。すべての文字は UTF-8 でエンコードする必要があります。国際文字も使用できます。
  • 単一のリクエスト内で、ラベルのキーの部分は一意である必要があります(たとえば、{'country':'india'} は使用できますが、{'country':'india','country':'sweden'} は使用できません)。
  • キーは、小文字または国際文字で始める必要があります。

ラベルと課金

Cloud Translation では、ラベルを使用して請求先アカウントごとに料金を整理できます。Translation ラベルの使用は課金されません。

料金は、リクエストを含むプロジェクトの請求先アカウントに関連付けられます。また、カスタムモデルまたは一般的なモデルが使用される場合、料金はモデルを含むプロジェクトに関連付けられます。

請求を行う際には、請求可能なすべてのリクエストにそれ自体のラベルを付けることができます。請求可能なリクエストには、一括翻訳、言語の検出、テキストの翻訳などがあります。

Cloud Translation API を使用してラベルを作成、管理する

Cloud Translation API を使用して、リクエストにラベルを追加します。

REST とコマンドライン

次の例では、ラベル {'country':'russia'}{'env':'test'}translateText リクエストに追加されます。

後述のリクエストのデータを使用する前に、次のように置き換えます。

  • project-number-or-id: Google Cloud プロジェクト番号または ID

HTTP メソッドと URL:

POST https://translation.googleapis.com/v3/projects/project-number-or-id:translateText

JSON 本文のリクエスト:

{
  source_language_code: 'en',
  target_language_code: 'ru',
  contents: 'Dr. Watson, come here!',
  labels: {'country':'russia','env':'test'}
}

リクエストを送信するには、次のいずれかのオプションを選択します。

curl

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

curl -X POST \
-H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
https://translation.googleapis.com/v3/projects/project-number-or-id:translateText

PowerShell

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

$cred = gcloud auth application-default print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://translation.googleapis.com/v3/projects/project-number-or-id:translateText " | Select-Object -Expand Content

次のような JSON レスポンスが返されます。

{
  "translations": [
    {
      "translatedText": "Доктор Ватсон, иди сюда!"
    }
  ]
}

料金レポート

Google Cloud の課金コンソールの [レポート] ビューに移動して、こうしたラベルをリクエスト使用のフィルタとして使用します。

  1. ダッシュボードで、左上のハンバーガー型アイコンをクリックし、プルダウン リストから [支払いと請求] を選択します。請求先アカウントが複数ある場合は、選択を求めるページが表示されます。[リンクされた請求先アカウントに移動] をクリックします。
  2. [支払いと請求] ページの左側にあるナビゲーションで [レポート] を選択します。
  3. 右側のナビゲーションにあるフィルタを使用して、リクエストの使用状況を確認します。