Usar APIs REST programaticamente
A Tradução de Documentos é um recurso baseado em nuvem do serviço Azure AI Translator . Você pode usar a API de Tradução de Documentos para traduzir de forma assíncrona documentos inteiros em idiomas suportados e vários formatos de arquivo, preservando a estrutura do documento de origem e a formatação do texto. Neste guia de instruções, você aprenderá a usar APIs de tradução de documentos com uma linguagem de programação de sua escolha e a API REST HTTP.
Pré-requisitos
Nota
Normalmente, quando cria um recurso de IA do Azure no portal do Azure, tem a opção de criar uma chave multisserviço ou uma chave de serviço único. No entanto, a Tradução de Documentos tem atualmente suporte apenas no recurso Tradutor (serviço único) e não está incluída no recurso Serviços de IA do Azure (multisserviços).
A tradução de documentos é suportada no Plano de Serviço Padrão S1 (Pagamento conforme o uso) e nos Planos de Desconto por Volume C2, C3, C4 e D3. Consulte Preços dos serviços de IA do Azure — Tradutor.
Para começar, precisa do seguinte:
Uma conta ativa do Azure. Se não tiver uma, pode criar uma conta gratuita
Uma conta de Armazenamento de Blob do Azure. Você também precisa criar contêineres em sua conta de Armazenamento de Blob do Azure para seus arquivos de origem e de destino:
- Recipiente de origem. Este contentor é onde carrega os seus ficheiros para tradução (obrigatório).
- Recipiente de destino. Este contêiner é onde seus arquivos traduzidos são armazenados (obrigatório).
Um recurso de Tradutor de serviço único (não um recurso de serviços de IA do Azure multisserviço):
Preencha os campos de detalhes do projeto e da instância do Translator da seguinte maneira:
Subscrição. Selecione uma das suas subscrições do Azure disponíveis.
Grupo de Recursos. Você pode criar um novo grupo de recursos ou adicionar seu recurso a um grupo de recursos pré-existente que compartilha o mesmo ciclo de vida, permissões e políticas.
Região de Recursos. Escolha Global , a menos que sua empresa ou aplicativo exija uma região específica. Se você estiver planejando usar uma identidade gerenciada atribuída ao sistema para autenticação, escolha uma região geográfica como West US.
Nome. Introduza o nome que escolheu para o seu recurso. O nome escolhido deve ser exclusivo no Azure.
Nota
A Tradução de Documentos requer um ponto de extremidade de domínio personalizado. O valor inserido no campo Nome será o parâmetro de nome de domínio personalizado para seu ponto de extremidade.
Escalão de preço. A tradução de documentos não é suportada no nível gratuito. Para experimentar o serviço, selecione Standard S1.
Selecione Rever + Criar.
Revise os termos de serviço e selecione Criar para implantar seu recurso.
Depois que o recurso for implantado com êxito, selecione Ir para o recurso para recuperar a chave e o ponto de extremidade.
Recuperar sua chave e ponto de extremidade de domínio personalizado
- As solicitações ao serviço Tradutor exigem uma chave somente leitura e um ponto de extremidade personalizado para autenticar o acesso. O ponto de extremidade de domínio personalizado é uma URL formatada com seu nome de recurso, nome de host e subdiretórios do Tradutor e está disponível no portal do Azure.
Se você criou um novo recurso, depois que ele for implantado, selecione Ir para recurso. Se você tiver um recurso de Tradução de Documentos existente, navegue diretamente para a página do recurso.
No trilho esquerdo, em Gerenciamento de Recursos, selecione Chaves e Ponto de Extremidade.
Copie e cole o seu
keyedocument translation endpointem um local conveniente, como o Bloco de Notas da Microsoft. Só é necessária uma chave para fazer uma chamada à API.Você
keyedocument translation endpointos exemplos de código para autenticar sua solicitação ao serviço de Tradução de Documentos.
Obtenha a sua chave
As solicitações ao serviço Tradutor exigem uma chave somente leitura para autenticar o acesso.
- Se você criou um novo recurso, depois que ele for implantado, selecione Ir para recurso. Se você tiver um recurso de Tradução de Documentos existente, navegue diretamente para a página do recurso.
- No trilho esquerdo, em Gerenciamento de Recursos, selecione Chaves e Ponto de Extremidade.
- Copie e cole sua chave em um local conveniente, como o Bloco de Notas da Microsoft.
- Cole no exemplo de código para autenticar sua solicitação no serviço de tradução de documentos.
Criar contêineres de Armazenamento de Blob do Azure
Você precisa criar contêineres em sua conta de Armazenamento de Blob do Azure para arquivos de origem e de destino.
- Recipiente de origem. Este contentor é onde carrega os seus ficheiros para tradução (obrigatório).
- Recipiente de destino. Este contêiner é onde seus arquivos traduzidos são armazenados (obrigatório).
Nota
A Tradução de Documentos suporta glossários como blobs em recipientes de destino (não em recipientes de glossário separados). Se quiser incluir um glossário personalizado, adicione-o ao contêiner de destino e inclua o glossaryUrl com a solicitação. Se o par linguístico de tradução não estiver presente no glossário, não será aplicado. Consulte Traduzir documentos usando um glossário personalizado
Criar tokens de acesso SAS para Tradução de Documentos
O sourceUrl , targetUrl e opcional glossaryUrl deve incluir um token SAS (Assinatura de Acesso Compartilhado), anexado como uma cadeia de caracteres de consulta. O token pode ser atribuído ao seu contêiner ou blobs específicos. Consulte Criar tokens SAS para o processo de tradução de documentos.
- Seu contêiner ou blob de origem deve designar acesso de leitura e lista .
- Seu contêiner ou blob de destino deve designar acesso de gravação e lista .
- Seu blob de glossário deve designar acesso de leitura e lista .
Gorjeta
- Se você estiver traduzindo vários arquivos (blobs) em uma operação, delegue o acesso SAS no nível do contêiner.
- Se você estiver traduzindo um único arquivo (blob) em uma operação, delegue o acesso SAS no nível de blob.
- Como alternativa aos tokens SAS, você pode usar uma identidade gerenciada atribuída ao sistema para autenticação.
Pedidos HTTP
Uma solicitação de tradução em lote assíncrona é enviada ao ponto de extremidade do serviço Translator por meio de uma solicitação POST. Se for bem-sucedido, o método POST retorna um código de 202 Accepted resposta e o serviço cria uma solicitação em lote. Os documentos traduzidos estão listados no contêiner de destino.
Para obter informações detalhadas sobre os limites de solicitação do Serviço Azure AI Translator, consulte Limites de solicitação de tradução de documentos.
Cabeçalhos de HTTP
Os cabeçalhos a seguir estão incluídos em cada solicitação da API de Tradução de Documentos:
| Cabeçalho HTTP | Description |
|---|---|
| Ocp-Apim-Subscription-Key | Obrigatório: o valor é a chave do Azure para o seu Tradutor ou recurso de serviços de IA do Azure. |
| Tipo de Conteúdo | Obrigatório: especifica o tipo de conteúdo da carga útil. Os valores aceitos são application/json ou charset=UTF-8. |
Propriedades do corpo da solicitação POST
- O URL da solicitação POST é POST
https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.1/batches. - O corpo da solicitação POST é um objeto JSON chamado
inputs. - O
inputsobjeto contém endereços detargetURLcontêinersourceURLpara seus pares de idiomas de origem e de destino. - As
prefixcadeias de caracteres esuffixdiferenciam maiúsculas de minúsculas para filtrar documentos no caminho de origem para tradução. Oprefixcampo é frequentemente usado para delinear subpastas para tradução. Osuffixcampo é mais frequentemente usado para extensões de arquivo. - Um valor para o
glossariescampo (opcional) é aplicado quando o documento está sendo traduzido. - O
targetUrlpara cada língua de chegada deve ser único.
Nota
Se já existir um arquivo com o mesmo nome no destino, o trabalho falhará.
Traduzir todos os documentos em um contêiner
{
"inputs": [
{
"source": {
"sourceUrl": "{sourceSASUrl}"
},
"targets": [
{
"targetUrl": "{targetSASUrl}",
"language": "fr"
}
]
}
]
}
Traduzir um documento específico em um contêiner
- Especifique
"storageType": "File". - Se você não estiver usando uma identidade gerenciada atribuída pelo sistema para autenticação, certifique-se de ter criado a URL de origem & tokens SAS para o blob/documento específico (não para o contêiner).
- Certifique-se de especificar o nome do arquivo de destino como parte da URL de destino – embora o token SAS ainda seja para o contêiner.
- Esta solicitação de exemplo retorna um único documento traduzido em dois idiomas de destino.
{
"inputs": [
{
"storageType": "File",
"source": {
"sourceUrl": "{sourceSASUrl}"
},
"targets": [
{
"targetUrl": "{targetSASUrl}",
"language": "es"
},
{
"targetUrl": "{targetSASUrl}",
"language": "de"
}
]
}
]
}
Traduzir documentos usando um glossário personalizado
{
"inputs": [
{
"source": {
"sourceUrl": "{sourceSASUrl}"
},
"targets": [
{
"targetUrl": "{targetSASUrl}",
"language": "es",
"glossaries": [
{
"glossaryUrl": "{glossaryUrl/en-es.xlf}",
"format": "xliff"
}
]
}
]
}
]
}
Use o código para enviar solicitações de tradução de documentos
Configurar a sua plataforma de codificação
- Criar um projeto novo.
- Substitua Program.cs pelo exemplo de código C#.
- Defina seus valores de URL de ponto de extremidade, chave e contêiner em Program.cs.
- Adicione o pacote Newtonsoft.Json usando a CLI do .NET para processar dados JSON.
- Execute o programa a partir do diretório do projeto.
Importante
Para os exemplos de código, você codificará sua URL de Assinatura de Acesso Compartilhado (SAS) onde indicado. Lembre-se de remover o URL SAS do seu código quando terminar e nunca publicá-lo publicamente. Para produção, use uma maneira segura de armazenar e acessar suas credenciais, como o Azure Managed Identity. Para obter mais informações, consulte Segurança do Armazenamento do Azure.
Pode ser necessário atualizar os seguintes campos, dependendo da operação:
endpointbasePathkeysourceURLtargetURLglossaryURLid(ID do trabalho)
Localizando o id valor
- Você pode encontrar o trabalho
idno valor URL do cabeçalhoOperation-Locationde resposta do método POSTstart-batch-translation. A cadeia alfanumérica que segue o/document/parâmetro é o trabalhoidda operação:
| Cabeçalho da resposta | URL de resposta |
|---|---|
| Local de Operação | {document-translation-endpoint}/translator/document/9dce0aa9-78dc-41ba-8cae-2e2f3c2ff8ec?api-version={date} |
- Você também pode usar uma solicitação get-translations-status para recuperar uma lista de trabalhos de tradução e seus
ids.
Iniciar a tradução em lote assíncrona
using System;
using System.Net.Http;
using System.Threading.Tasks;
using System.Text;
class Program
{
static readonly string route = "?api-version={date}";
private static readonly string basePath = "{your-document-translation-endpoint}/translator/document/batches";
private static readonly string key = "{your-api-key}";
static readonly string json = ("{\"inputs\": [{\"source\": {\"sourceUrl\": \"https://YOUR-SOURCE-URL-WITH-READ-LIST-ACCESS-SAS\",\"storageSource\": \"AzureBlob\",\"language\": \"en\"}, \"targets\": [{\"targetUrl\": \"https://YOUR-TARGET-URL-WITH-WRITE-LIST-ACCESS-SAS\",\"storageSource\": \"AzureBlob\",\"category\": \"general\",\"language\": \"es\"}]}]}");
static async Task Main(string[] args)
{
using HttpClient client = new HttpClient();
using HttpRequestMessage request = new HttpRequestMessage();
{
StringContent content = new StringContent(json, Encoding.UTF8, "application/json");
request.Method = HttpMethod.Post;
request.RequestUri = new Uri(basePath + route);
request.Headers.Add("Ocp-Apim-Subscription-Key", key);
request.Content = content;
HttpResponseMessage response = await client.SendAsync(request);
string result = response.Content.ReadAsStringAsync().Result;
if (response.IsSuccessStatusCode)
{
Console.WriteLine($"Status code: {response.StatusCode}");
Console.WriteLine();
Console.WriteLine($"Response Headers:");
Console.WriteLine(response.Headers);
}
else
Console.Write("Error");
}
}
}
Obter formatos de documento suportados
Recupere uma lista de formatos de arquivo suportados. Se for bem-sucedido, esse método retornará um código de 200 OK resposta.
using System;
using System.Net.Http;
using System.Threading.Tasks;
class Program
{
private static readonly string basePath = "{your-document-translation-endpoint}/translator/document/formats";
static readonly string route = "?api-version={date}&type=document";
private static readonly string key = "{your-api-key}";
static async Task Main(string[] args)
{
HttpClient client = new HttpClient();
using HttpRequestMessage request = new HttpRequestMessage();
{
request.Method = HttpMethod.Get;
request.RequestUri = new Uri(basePath + route);
request.Headers.Add("Ocp-Apim-Subscription-Key", key);
HttpResponseMessage response = await client.SendAsync(request);
string result = response.Content.ReadAsStringAsync().Result;
Console.WriteLine($"Status code: {response.StatusCode}");
Console.WriteLine($"Response Headers: {response.Headers}");
Console.WriteLine();
Console.WriteLine(result);
}
}
Obter status para um trabalho de tradução
Obtenha o status atual de um único trabalho e um resumo de todos os trabalhos em uma solicitação de Tradução de Documentos. Se for bem-sucedido, esse método retornará um código de 200 OK resposta.
using System;
using System.Net.Http;
using System.Threading.Tasks;
class Program
{
private static readonly string basePath = "{your-document-translation-endpoint}/translator/document/batches/{id}";
static readonly string route = "?api-version={date}";
private static readonly string key = "{your-api-key}";
static async Task Main(string[] args)
{
HttpClient client = new HttpClient();
using HttpRequestMessage request = new HttpRequestMessage();
{
request.Method = HttpMethod.Get;
request.RequestUri = new Uri(basePath + route);
request.Headers.Add("Ocp-Apim-Subscription-Key", key);
HttpResponseMessage response = await client.SendAsync(request);
string result = response.Content.ReadAsStringAsync().Result;
Console.WriteLine($"Status code: {response.StatusCode}");
Console.WriteLine($"Response Headers: {response.Headers}");
Console.WriteLine();
Console.WriteLine(result);
}
}
}
Obter o status de um documento específico
Breve visão geral
Recupere o status de um documento específico em uma solicitação de Tradução de Documento. Se for bem-sucedido, esse método retornará um código de 200 OK resposta.
using System;
using System.Net.Http;
using System.Threading.Tasks;
class Program
{
private static readonly string basePath = "{document-translation-endpoint}/translator/document/batches/{id}/documents/{documentId}";
static readonly string route = "?api-version={date}";
private static readonly string key = "{your-api-key}";
static async Task Main(string[] args)
{
HttpClient client = new HttpClient();
using HttpRequestMessage request = new HttpRequestMessage();
{
request.Method = HttpMethod.Get;
request.RequestUri = new Uri(basePath + route);
request.Headers.Add("Ocp-Apim-Subscription-Key", key);
HttpResponseMessage response = await client.SendAsync(request);
string result = response.Content.ReadAsStringAsync().Result;
Console.WriteLine($"Status code: {response.StatusCode}");
Console.WriteLine($"Response Headers: {response.Headers}");
Console.WriteLine();
Console.WriteLine(result);
}
}
Eliminar trabalho
Breve visão geral
Cancelar o trabalho atualmente em processamento ou em fila. Apenas os documentos cuja tradução não foi iniciada são cancelados.
using System;
using System.Net.Http;
using System.Threading.Tasks;
class Program
{
private static readonly string basePath = "{your-document-translation-endpoint}/translator/document/batches/{id}";
static readonly string route = "?api-version={date}";
private static readonly string key = "{your-api-key}";
static async Task Main(string[] args)
{
HttpClient client = new HttpClient();
using HttpRequestMessage request = new HttpRequestMessage();
{
request.Method = HttpMethod.Delete;
request.RequestUri = new Uri(basePath + route);
request.Headers.Add("Ocp-Apim-Subscription-Key", key);
HttpResponseMessage response = await client.SendAsync(request);
string result = response.Content.ReadAsStringAsync().Result;
Console.WriteLine($"Status code: {response.StatusCode}");
Console.WriteLine($"Response Headers: {response.Headers}");
Console.WriteLine();
Console.WriteLine(result);
}
}
Códigos de status HTTP comuns
| Código de estado de HTTP | Description | Motivo possível |
|---|---|---|
| 200 | OK | O pedido foi bem-sucedido. |
| 400 | Pedido Incorreto | Um parâmetro necessário está ausente, vazio ou nulo. Ou, o valor passado para um parâmetro obrigatório ou opcional é inválido. Um problema comum é um cabeçalho muito longo. |
| 401 | Não autorizado | O pedido não está autorizado. Verifique se a sua chave ou token está válido e na região correta. Ao gerenciar sua assinatura no portal do Azure, verifique se você está usando o recurso de serviço único do Translator e não o recurso multisserviço de serviços de IA do Azure. |
| 429 | Demasiados pedidos | Você excedeu a cota ou a taxa de solicitações permitidas para sua assinatura. |
| 502 | Gateway Inválido | Problema de rede ou do lado do servidor. Também pode indicar cabeçalhos inválidos. |
Mais informações
Próximos passos
Comentários
Brevemente: Ao longo de 2024, vamos descontinuar progressivamente o GitHub Issues como mecanismo de feedback para conteúdos e substituí-lo por um novo sistema de feedback. Para obter mais informações, veja: https://aka.ms/ContentUserFeedback.
Submeter e ver comentários