Como gerar relatórios de uso com rótulos (Advanced)

A API Cloud Translation é compatível com a adição de rótulos definidos pelo usuário (pares de chave-valor) às solicitações TranslateText, BatchTranslateText e DetectLanguage. As informações sobre o uso de uma solicitação são encaminhadas ao sistema de faturamento. Nele, é possível filtrar as cobranças por rótulo.

Caso de uso

Com relação aos rótulos, um caso de uso importante é quando empresas fornecem serviços de tradução a vários clientes. É possível usar um único projeto para vários clientes. Para fins de faturamento, é essencial associar solicitações específicas aos respectivos clientes. É aí que os rótulos são usados. Ao fazer uma chamada em nome de um cliente, você inclui um rótulo específico dele na solicitação. Esses rótulos estão disponíveis para filtragem na seção Relatórios do Google Cloud.

Requisitos dos rótulos

Os rótulos aplicados a uma solicitação precisam atender aos requisitos a seguir:

Cada solicitação pode ter vários rótulos. O número máximo é de 64.
Cada rótulo precisa ser um par de chave-valor.
As chaves têm comprimento mínimo de 1 e máximo de 63 caracteres. Além disso, elas não podem estar vazias. Os valores podem estar vazios e ter um comprimento máximo de 63 caracteres.
As chaves e os valores contêm apenas letras minúsculas, caracteres numéricos, sublinhados e traços. Todos os caracteres precisam usar a codificação UTF-8. Caracteres internacionais são permitidos.
A parte da chave de um rótulo precisa ser única em uma solicitação. Por exemplo, {'country':'india'} é apropriado, mas {'country':'india','country':'sweden'} não é permitido.
As chaves precisam começar com uma letra minúscula ou um caractere internacional.

Rótulos e faturamento

No Cloud Translation, é possível usar rótulos para organizar as taxas por conta de faturamento. Você não será cobrado pelo uso de rótulos do Cloud Translation.

As taxas são associadas à conta de faturamento do projeto que inclui a solicitação. Ou, se um modelo personalizado ou de tradução automática neural (NMT) for usado, as taxas serão associadas ao projeto que contém o modelo.

Para fins de cobrança, todas as solicitações faturáveis podem ter rótulos próprios. Elas incluem tradução em lote, detecção de idiomas e tradução de textos.

Como criar e gerenciar rótulos por meio da API Cloud Translation

Use a API Cloud Translation para adicionar rótulos a uma solicitação.

REST

No exemplo a seguir, os rótulos {'country':'russia'} e {'env':'test'} são adicionados à solicitação translateText.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

PROJECT_NUMBER_OR_ID: o ID numérico ou alfanumérico do projeto do Google Cloud

Método HTTP e URL:

POST https://translation.googleapis.com/v3/projects/PROJECT_NUMBER_OR_ID:translateText

Corpo JSON da solicitação:

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

Para enviar a solicitação, expanda uma destas opções:

curl (Linux, macOS ou Cloud Shell)

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que faz login automaticamente na CLI gcloud. É possível verificar a conta ativa atual executando gcloud auth list.

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

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)

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login . É possível verificar a conta ativa atual executando gcloud auth list.

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

$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

Você receberá uma resposta JSON semelhante a esta:

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

Preços dos relatórios

Acesse o console de faturamento do Google Cloud, na visualização Relatórios, para usar esses rótulos como filtros de uso de solicitações.

No painel, clique no ícone de hambúrguer no canto superior à esquerda e selecione “Faturamento” no menu suspenso. Se tiver várias contas de faturamento, será exibida uma página que solicitará a você a escolha de uma opção. Clique em "Ir para a conta de faturamento vinculada".
Na página "Faturamento", selecione Relatórios no painel de navegação à esquerda.
Utilize os filtros no painel de navegação à direita para verificar o uso das solicitações.