Migrar da edição Basic para a Advanced

Os usuários atuais da versão Basic (v2) do Cloud Translation que querem usar os recursos mais recentes do Cloud Translation, como glossários e modelos do AutoML, precisam migrar os aplicativos para usar a versão Advanced (v3) do Cloud Translation. Para uma comparação, consulte Comparar as configurações das versões Basic e Advanced.

A migração para a edição Advanced inclui o uso do gerenciamento de identidade e acesso (IAM) e as bibliotecas de cliente da edição Advanced. As seções a seguir descrevem as tarefas de migração e as principais diferenças entre as duas edições.

Como migrar para a Advanced

As etapas a seguir descrevem as ações necessárias para atualizar seus aplicativos da versão Basic do Cloud Translation a versão Advanced.

1. Faça um inventário dos seus projetos, aplicativos e usuários do Google Cloud que acessam a API Basic do Cloud Translation. Você precisará fornecer contas de serviço e atualizá-las para usar as bibliotecas de cliente da edição Advanced do Cloud Translation.
2. Configure contas de serviço e autenticação para seu aplicativo.
3. Use os papéis do IAM para definir permissões em contas de serviço.
4. Ative o Cloud Translation - Advanced para seu projeto. Se você usa modelos AutoML com a versão Advanced do Cloud Translation, também precisa ativar o AutoML. Para ver mais informações, consulte o guia Configuração
5. Use os métodos e as bibliotecas de cliente da versão Advanced do Cloud Translation. Para solicitações da edição Advanced do Cloud Translation, inclua o número (ou ID) e o local do projeto, que costuma ser global ou us-central1.
6. Verifique se o tamanho das suas solicitações de tradução para o Cloud Translation - Advanced não excede o limite.
7. Planeje seu monitoramento de cota de solicitação de tradução. As duas versões da API compartilham as mesmas cotas diárias e mensais.
8. Analise as possíveis alterações no faturamento.

Principais diferenças entre a edição Advanced e a Basic

Para entender as tarefas de migração, as seções a seguir descrevem as principais diferenças entre as edições Advanced e Basic.

Contas de serviço

No Cloud Translation - Basic, é possível enviar solicitações autenticadas usando chaves de API ou contas de serviço.

O Cloud Translation - Advanced tem funcionalidades que exigem recursos gerenciados pelo cliente, como o gerenciamento de permissões e papéis do IAM. Por essa razão, não é possível usar chaves de API para autenticar para o serviço. Em vez disso, você precisa usar contas de serviço ao autenticar para a versão Advanced do Cloud Translation.

Para mais informações, consulte o guia Configuração.

Papéis IAM

Quando você usa contas de serviço para a versão Basic do Cloud Translation, elas são usadas apenas para autenticação. É possível fazer chamadas para o Cloud Translation - Basic, independentemente das permissões associadas à conta de serviço. No entanto, para a versão Advanced do Cloud Translation, as permissões se aplicam.

Para conceder permissões a contas de serviço para chamar o Cloud Translation - Advanced, atribua papéis do IAM a elas. Com o Cloud Translation - Advanced, você tem acesso a vários papéis do IAM que podem ser atribuídos à sua conta de serviço para acessar recursos específicos no seu projeto. Por exemplo, se você quiser usar sua conta de serviço para traduzir textos, atribua o papel roles/cloudtranslate.user a ela. Para mais informações, consulte os papéis do IAM em Detalhes do Cloud Translation - Advanced.

Se você planeja usar modelos do AutoML ou qualquer recurso que dependa do Cloud Storage, também precisa incluir os papéis apropriados para esses serviços. Para visualizar uma lista de todos os papéis do IAM, consulte a documentação sobre papéis do IAM.

Modelos de tradução

Quando você solicita uma tradução usando a versão Basic do Cloud Translation, o Google usa um modelo de tradução automática neural (NMT) pré-treinado. Para a versão Advanced do Cloud Translation, é possível usar o modelo NMT pré-treinado ou um modelo personalizado do AutoML Translation.

As contas de serviço usadas para solicitações de tradução precisam ter as permissões de acesso aos modelos NMT e AutoML, que estão localizados em projetos diferentes. Por exemplo, é possível ter um projeto central que contenha modelos de tradução para simplificar a manutenção e o faturamento. As contas de serviço nesse ou em outros projetos podem usar esses modelos, mas exigem permissões para fazer isso.

Para mais informações sobre modelos de tradução, consulte Como traduzir textos (Advanced).

Bibliotecas de cliente

As bibliotecas de cliente e os métodos da edição Advanced do Cloud Translation são diferentes da versão Basic do Cloud Translation. Por exemplo, as chamadas para a edição Advanced do Cloud Translation exigem nomes de recurso. Para mais informações, consulte a visão geral das bibliotecas de cliente da versão do Cloud Translation ou use o guia de início rápido do texto traduzido (edição Advanced).

Recursos, projetos e locais

As solicitações para a versão Advanced do Cloud Translation exigem o nome do recurso que você quer usar. Um recurso geralmente é um nome qualificado que inclui o nome do projeto e o local dele, que especifica onde a solicitação é executada. Por exemplo, o nome de um modelo do AutoML é um nome de recurso.

Se o projeto do Google Cloud tiver o nome my-project e o local do recurso for us-central1, o nome completo dos seus recursos poderá ser semelhante a este:

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

O URL para o qual você envia uma solicitação getSupportedLanguages pode ser semelhante ao seguinte:

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

Observação: todos os seus recursos de uma solicitação para a edição Advanced do Cloud Translation precisam ter o mesmo local. Atualmente, apenas os locais global e us-central1 são compatíveis. Para todos os recursos personalizados, como modelos AutoML, glossários e operações de longa duração, é preciso usar us-central1. Também é possível utilizar us-central1 ao usar modelos de tradução geral e detecção de idioma. Só é possível usar o local global quando você usa modelos de tradução geral e detecção de idioma.

O Cloud Translation: a versão avançada também oferece endpoints multirregionais, como translate-eu.googleapis.com, para manter o processamento de dados na UE. Esse é um endpoint exclusivo para a UE e não uma configuração de localização na API global. Para mais informações, consulte Endpoints globais e multirregionais.

Limite de conteúdo por solicitação

A API Cloud Translation é otimizada para tradução de solicitações menores. O tamanho máximo recomendado para cada solicitação é de 5.000 caracteres (pontos de código). No entanto, quanto mais você incluir, maior será a latência de resposta. Para a Cloud Translation - Advanced, o número máximo de pontos de código para uma única solicitação é de 30.000. O tamanho máximo para solicitações da Cloud Translation - Basic é de 100.000 bytes.

A API Cloud Translation rejeitará solicitações maiores que o limite e enviará um erro 400 INVALID_ARGUMENT, independentemente da cota disponível.

Para mais informações sobre cotas e limites, consulte esta página.

A seguir

Use a edição Advanced do Cloud Translation para traduzir textos, criar glossários ou fazer solicitações em lote.