Cloud Translation API를 사용하면 TranslateText, BatchTranslateText, DetectLanguage 요청에 사용자 정의 라벨(키-값 쌍)을 추가할 수 있습니다.
요청 사용량에 대한 정보는 결제 시스템으로 전달되며, 라벨을 기준으로 필터링하여 청구액의 상세 내역을 확인할 수 있습니다.
사용 사례
라벨의 중요한 사용 사례에는 다수의 클라이언트에 번역 서비스를 제공하는 고객이 포함됩니다. 하나의 프로젝트를 여러 클라이언트에 사용할 수 있습니다. 결제 용도로 특정 요청을 해당 클라이언트와 연결해야 합니다. 이때 라벨이 사용됩니다. 클라이언트를 대신하여 호출할 때 요청에 클라이언트별 라벨을 지정합니다. 이러한 라벨은 Google Cloud의 보고서 섹션에서 필터링에 사용할 수 있습니다.
라벨 요구사항
요청에 적용된 라벨은 다음 요구사항을 충족해야 합니다.
각 요청에는 라벨이 최대 64개까지 있을 수 있습니다.
각 라벨은 키-값 쌍이어야 합니다.
키는 길이는 최소 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
[[["이해하기 쉬움","easyToUnderstand","thumb-up"],["문제가 해결됨","solvedMyProblem","thumb-up"],["기타","otherUp","thumb-up"]],[["이해하기 어려움","hardToUnderstand","thumb-down"],["잘못된 정보 또는 샘플 코드","incorrectInformationOrSampleCode","thumb-down"],["필요한 정보/샘플이 없음","missingTheInformationSamplesINeed","thumb-down"],["번역 문제","translationIssue","thumb-down"],["기타","otherDown","thumb-down"]],["최종 업데이트: 2025-04-28(UTC)"],[],[],null,["# Reporting usage with labels (Advanced)\n======================================\n\nThe Cloud Translation API supports adding user-defined labels (key-value pairs)\nto `TranslateText`, `BatchTranslateText` and `DetectLanguage` requests.\nInformation about a request's usage is forwarded to the billing system where\nyou can break down your billing charges by filtering by label.\n\nUse case\n--------\n\nAn important use case for labels involves customers who provide translation\nservices to many clients. A single project can be used for multiple clients. For\nbilling purposes it's important to associate specific requests with their\nrespective clients. That's where labels come in. When making a call on behalf of\na client, you label the request with a client specific label. These labels are\nthen available for filtering purposes in the **Reports** section of\nthe Google Cloud.\n\nRequirements for labels\n-----------------------\n\nThe labels applied to a request must meet the following requirements:\n\n- Each request can have multiple labels, up to a maximum of 64.\n- Each label must be a key-value pair.\n- Keys have a minimum length of 1 character and a maximum length of 63 characters, and cannot be empty. Values can be empty, and have a maximum length of 63 characters.\n- Keys and values contain only lowercase letters, numeric characters, underscores, and dashes. All characters must use UTF-8 encoding, and international characters are allowed.\n- The key portion of a label must be unique within a single request (for example, `{'country':'india'}` is fine, but `{'country':'india','country':'sweden'}` is not allowed).\n- Keys must start with a lowercase letter or international character.\n\nLabels and billing\n------------------\n\nIn Cloud Translation, you can use labels to organize [fees](/translate/pricing)\nby billing account. You aren't changed for the use of Cloud Translation\nlabels.\n\nFees are associated with the billing account of the project that contains the\nrequest. Or, if a custom or Neural Machine Translation (NMT) model is used, fees\nare associated with the [project that contains the\nmodel](/translate/pricing#charged-projects).\n\nFor billing purposes, all billable requests can have labels of their own. These\nbillable requests include batch translation, detect language, and translate\ntext.\n\nCreating and managing labels using the Cloud Translation API\n------------------------------------------------------------\n\nUse the Cloud Translation API to add labels to a request.\n\n\n### REST\n\nIn the following example, the labels `{'country':'russia'}`,`{'env':'test'}` are added to the `translateText` request.\n\n\nBefore using any of the request data,\nmake the following replacements:\n\n- \u003cvar translate=\"no\"\u003ePROJECT_NUMBER_OR_ID\u003c/var\u003e: the numeric or alphanumeric ID of your Google Cloud project\n\n\nHTTP method and URL:\n\n```\nPOST https://translation.googleapis.com/v3/projects/PROJECT_NUMBER_OR_ID:translateText\n```\n\n\nRequest JSON body:\n\n```\n{\n source_language_code: 'en',\n target_language_code: 'ru',\n contents: 'Dr. Watson, come here!',\n labels: {'country':'russia','env':'test'}\n}\n\n```\n\nTo send your request, expand one of these options:\n\n#### curl (Linux, macOS, or Cloud Shell)\n\n| **Note:** The following command assumes that you have logged in to the `gcloud` CLI with your user account by running [`gcloud init`](/sdk/gcloud/reference/init) or [`gcloud auth login`](/sdk/gcloud/reference/auth/login) , or by using [Cloud Shell](/shell/docs), which automatically logs you into the `gcloud` CLI . You can check the currently active account by running [`gcloud auth list`](/sdk/gcloud/reference/auth/list).\n\n\nSave the request body in a file named `request.json`,\nand execute the following command:\n\n```\ncurl -X POST \\\n -H \"Authorization: Bearer $(gcloud auth print-access-token)\" \\\n -H \"x-goog-user-project: PROJECT_NUMBER_OR_ID\" \\\n -H \"Content-Type: application/json; charset=utf-8\" \\\n -d @request.json \\\n \"https://translation.googleapis.com/v3/projects/PROJECT_NUMBER_OR_ID:translateText\"\n```\n\n#### PowerShell (Windows)\n\n| **Note:** The following command assumes that you have logged in to the `gcloud` CLI with your user account by running [`gcloud init`](/sdk/gcloud/reference/init) or [`gcloud auth login`](/sdk/gcloud/reference/auth/login) . You can check the currently active account by running [`gcloud auth list`](/sdk/gcloud/reference/auth/list).\n\n\nSave the request body in a file named `request.json`,\nand execute the following command:\n\n```\n$cred = gcloud auth print-access-token\n$headers = @{ \"Authorization\" = \"Bearer $cred\"; \"x-goog-user-project\" = \"PROJECT_NUMBER_OR_ID\" }\n\nInvoke-WebRequest `\n -Method POST `\n -Headers $headers `\n -ContentType: \"application/json; charset=utf-8\" `\n -InFile request.json `\n -Uri \"https://translation.googleapis.com/v3/projects/PROJECT_NUMBER_OR_ID:translateText\" | Select-Object -Expand Content\n```\n\nYou should receive a JSON response similar to the following:\n\n```\n{\n \"translations\": [\n {\n \"translatedText\": \"Доктор Ватсон, иди сюда!\"\n }\n ]\n}\n```\n\n\u003cbr /\u003e\n\nPricing report\n--------------\n\nGo to the [Google Cloud](https://console.cloud.google.com/billing)\nbilling console **Reports** view to use these labels as filters for request\nusage.\n\n1. From the dashboard, click the hamburger icon on the upper left-hand side and select \"Billing\" from the drop-down. If you have multiple billing accounts a page appears that asks you to make a selection. Click \"Go to linked billing account.\"\n2. From the Billing page, select **Reports** in the left-hand nav.\n3. Use the filters in the right-hand nav to check usage of requests."]]