ラベル付き使用状況の報告（Advanced）

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

ユースケース

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

ラベルの要件

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

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

ラベルと課金

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

料金は、リクエストを含むプロジェクトの請求先アカウントに関連付けられます。カスタムモデルまたはニューラル機械翻訳（NMT）モデルが使用される場合、料金はモデルを含むプロジェクトに関連付けられます。

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

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（Linux、macOS、Cloud Shell）

注: 次のコマンドは、gcloud init または gcloud auth login を実行して、ユーザーアカウントで gcloud CLI にログインしているか、Cloud Shell を使用して自動的に gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

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

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

PowerShell（Windows）

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

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "PROJECT_NUMBER_OR_ID" }

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

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