Bagikan melalui

Menggunakan REST API secara terprogram

  • Artikel

Terjemahan Dokumen adalah fitur berbasis cloud dari layanan Penerjemah Azure AI. Anda dapat menggunakan DOCUMENT Translation API untuk menerjemahkan seluruh dokumen secara asinkron dalam bahasa yang didukung dan berbagai format file sambil mempertahankan struktur dokumen sumber dan pemformatan teks. Dalam panduan cara ini, Anda belajar menggunakan API Terjemahan Dokumen dengan bahasa pemrograman pilihan Anda dan HTTP REST API.

Prasyarat

Catatan

  • Biasanya, saat Anda membuat sumber daya Azure AI di portal Azure, Anda memiliki opsi untuk membuat kunci multi-layanan atau kunci layanan tunggal. Namun, Terjemahan Dokumen saat ini hanya didukung di sumber daya Penerjemah (layanan tunggal), dan tidak termasuk dalam sumber daya layanan Azure AI (multi-layanan).

  • Terjemahan Dokumen didukung dalam Paket Layanan Standar S1 (Bayar sesuai penggunaan) dan Paket Diskon Volume C2, C3, C4, dan D3. Lihat Harga layanan Azure AI—Penerjemah.

Untuk memulai, Anda memerlukan:

  • Akun Azure aktif. Jika Anda tidak memilikinya, Anda dapat membuat akun gratis

  • Akun Azure Blob Storage. Anda juga perlu membuat kontainer di akun Azure Blob Storage untuk file sumber dan target Anda:

    • Kontainer sumber. Kontainer ini adalah tempat Anda mengunggah file yang akan diterjemahkan (wajib).
    • Kontainer target. Kontainer ini adalah tempat file terjemahan Anda disimpan (diperlukan).

  • Sumber daya Penerjemah layanan tunggal (bukan sumber daya layanan Azure AI multi-layanan):

    Selesaikan proyek Penerjemah dan bidang detail instans sebagai berikut:

    1. Langganan. Pilih salah satu langganan Azure Anda yang tersedia.

    2. Grup Sumber Daya. Anda dapat membuat grup sumber daya baru atau menambahkan sumber daya Anda ke grup sumber daya yang sudah ada sebelumnya, yang memiliki siklus hidup, izin, dan kebijakan yang sama.

    3. Wilayah Sumber Daya. Pilih Global kecuali bisnis atau aplikasi Anda memerlukan wilayah tertentu. Jika Anda berencana menggunakan identitas terkelola yang ditetapkan sistem untuk autentikasi, pilih wilayah geografis seperti AS Barat.

    4. Nama. Masukkan nama yang Anda pilih untuk sumber daya Anda. Nama yang Anda pilih harus unik dalam Azure.

      Catatan

      Penerjemahan Dokumen memerlukan titik akhir domain kustom. Nilai yang Anda masukkan dalam bidang Nama akan menjadi parameter nama domain kustom untuk titik akhir.

    5. Tingkat harga. Penerjemahan Dokumen tidak didukung di tingkat gratis. Untuk mencoba layanan, pilih Standar S1.

    6. Pilih Tinjau + Buat.

    7. Tinjau ketentuan layanan dan pilih Buat untuk menyebarkan sumber daya Anda.

    8. Setelah sumber daya Anda berhasil disebarkan, pilih Buka sumber daya untuk mengambil kunci dan titik akhir Anda.

Mengambil kunci dan titik akhir domain kustom Anda

  • Permintaan ke layanan Penerjemah memerlukan kunci baca-saja dan titik akhir kustom untuk mengautentikasi akses. Titik akhir domain kustom adalah URL yang diformat dengan nama sumber daya, nama host, dan subdirektor Penerjemah Anda dan tersedia di portal Azure.

  1. Jika Anda membuat sumber daya baru, setelah disebarkan, pilih Buka sumber daya. Jika Anda memiliki sumber daya Terjemahan Dokumen yang sudah ada, langsung buka halaman sumber daya.

  2. Di rel kiri, di bagian Manajemen Sumber Daya, pilih Kunci dan Titik Akhir.

  3. Salin dan tempel lokasi Anda key dan document translation endpoint di lokasi yang nyaman, seperti Microsoft Notepad. Hanya satu kunci yang diperlukan untuk melakukan panggilan API.

  4. Anda key dan document translation endpoint ke dalam sampel kode untuk mengautentikasi permintaan Anda ke layanan Terjemahan Dokumen.

    Cuplikan layar memperlihatkan bidang dapatkan kunci Anda di portal Azure.

Mendapatkan kunci Anda

Permintaan ke layanan Penerjemah memerlukan kunci baca-saja untuk mengautentikasi akses.

  1. Jika Anda membuat sumber daya baru, setelah disebarkan, pilih Buka sumber daya. Jika Anda memiliki sumber daya Terjemahan Dokumen yang sudah ada, langsung buka halaman sumber daya.
  2. Di rel kiri, di bagian Manajemen Sumber Daya, pilih Kunci dan Titik Akhir.
  3. Salin dan tempel kunci di lokasi yang mudah diakses, seperti Microsoft Notepad.
  4. Anda menempelkannya ke dalam sampel kode untuk mengautentikasi permintaan Anda ke layanan Terjemahan Dokumen.

Gambar bidang dapatkan kunci Anda di portal Azure.

Membuat kontainer Azure Blob Storage

Anda perlu membuat kontainer di akun Azure Blob Storage untuk file sumber dan target.

  • Kontainer sumber. Kontainer ini adalah tempat Anda mengunggah file yang akan diterjemahkan (wajib).
  • Kontainer target. Kontainer ini adalah tempat file terjemahan Anda disimpan (diperlukan).

Catatan

Terjemahan Dokumen mendukung glosarium sebagai blob dalam kontainer target (bukan wadah glosarium terpisah). Jika ingin menyertakan glosarium khusus, tambahkan ke wadah target dan sertakan glossaryUrl dengan permintaan. Jika pasangan bahasa terjemahan tidak ada dalam glosarium, itu tidak akan diterapkan. Lihat Menerjemahkan dokumen menggunakan glosarium khusus

Membuat token akses SAS untuk Terjemahan Dokumen

sourceUrl, targetUrl, dan glossaryUrl opsional harus menyertakan token Tanda Tangan Akses Bersama (SAS), yang ditambahkan sebagai string kueri. Token dapat ditetapkan ke kontainer Anda atau blob tertentu. Lihat Membuat token SAS untuk pemrosesan Terjemahan Dokumen.

  • Kontainer sumber atau blob Anda harus menunjuk akses baca dan daftar.
  • Kontainer atau blob target Anda harus menunjuk akses tulis dan daftar.
  • Blob glosarium Anda harus menunjuk akses baca dan daftar.

Tip

  • Jika Anda menerjemahkan beberapa file (blob) dalam suatu operasi, delegasikan akses SAS pada tingkat kontainer.
  • Jika Anda menerjemahkan satu file (blob) dalam operasi, delegasikan akses SAS di tingkat blob.
  • Sebagai alternatif token SAS, Anda dapat menggunakan identitas terkelola yang ditetapkan sistem untuk autentikasi.

Permintaan HTTP

Permintaan terjemahan batch asinkron dikirimkan ke titik akhir layanan Penerjemah Anda melalui permintaan POST. Jika berhasil, metode POST mengembalikan 202 Accepted kode respons dan layanan membuat permintaan batch. Dokumen yang diterjemahkan tercantum dalam kontainer target Anda.

Untuk informasi terperinci mengenai batas permintaan Layanan Penerjemah Azure AI, lihat Batas permintaan Terjemahan Dokumen.

Header HTTP

Header berikut disertakan dengan setiap permintaan Document Translation API:

Header HTTP Deskripsi
Ocp-Apim-Subscription-Key Diperlukan: Nilainya adalah kunci Azure untuk sumber daya layanan Penerjemah atau Azure AI Anda.
Content-Type Wajib: Tentukan jenis konten payload. Nilai yang diterima adalah application/json atau charset=UTF-8.

Properti isi permintaan POST

  • URL permintaan POST adalah POST https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.1/batches.
  • Isi permintaan POST adalah objek JSON bernama inputs.
  • Objek inputs berisi alamat kontainer sourceURL dan targetURL untuk pasangan bahasa sumber dan target Anda.
  • prefix dan suffix adalah string yang peka huruf besar/kecil untuk memfilter dokumen di jalur sumber untuk penerjemahan. Bidang prefix sering digunakan untuk menguraikan subfolder untuk penerjemahan. Bidang suffix paling sering digunakan untuk ekstensi file.
  • Nilai untuk bidang glossaries (opsional) diterapkan saat dokumen sedang diterjemahkan.
  • targetUrl untuk bahasa target harus unik.

Catatan

Jika file dengan nama yang sama sudah ada di tujuan, pekerjaan akan gagal.

Menerjemahkan semua dokumen dalam kontainer

{
    "inputs": [
        {
            "source": {
                "sourceUrl": "{sourceSASUrl}"
            },
            "targets": [
                {
                    "targetUrl": "{targetSASUrl}",
                    "language": "fr"
                }
            ]
        }
    ]
}

Menerjemahkan dokumen tertentu dalam kontainer

  • Tentukan "storageType": "File".
  • Jika Anda tidak menggunakan identitas terkelola yang ditetapkan sistem untuk autentikasi, pastikan Anda membuat URL sumber & token SAS untuk blob/dokumen tertentu (bukan untuk kontainer).
  • Pastikan Anda menentukan nama file target sebagai bagian dari URL target – meskipun token SAS masih untuk kontainer.
  • Permintaan sampel ini mengembalikan satu dokumen yang diterjemahkan ke dalam dua bahasa target.
{
    "inputs": [
        {
            "storageType": "File",
            "source": {
                "sourceUrl": "{sourceSASUrl}"
            },
            "targets": [
                {
                    "targetUrl": "{targetSASUrl}",
                    "language": "es"
                },
                {
                    "targetUrl": "{targetSASUrl}",
                    "language": "de"
                }
            ]
        }
    ]
}

Menerjemahkan dokumen menggunakan glosarium kustom

{
    "inputs": [
        {
            "source": {
                "sourceUrl": "{sourceSASUrl}"
             },
            "targets": [
                {
                    "targetUrl": "{targetSASUrl}",
                    "language": "es",
                    "glossaries": [
                        {
                            "glossaryUrl": "{glossaryUrl/en-es.xlf}",
                            "format": "xliff"
                        }
                    ]
                }
            ]
        }
    ]
}

Menggunakan kode untuk mengirimkan permintaan Terjemahan Dokumen

Menyiapkan Platform pengodean

  • Buat proyek baru.
  • Ganti Program.cs dengan sampel kode C#.
  • Atur nilai titik akhir, kunci langganan, dan URL kontainer Anda dalam Program.cs.
  • Tambahkan paket Newtonsoft.Json menggunakan .NET CLI untuk memproses data JSON.
  • Jalankan program dari direktori proyek.

Penting

Untuk sampel kode, Anda akan membuat kode keras URL Tanda Tangan Akses Bersama (SAS) jika ditunjukkan. Ingatlah untuk menghapus URL SAS dari kode Anda setelah selesai, dan jangan pernah mempostingnya secara publik. Untuk produksi, gunakan cara yang aman untuk menyimpan dan mengakses informasi masuk Anda seperti Azure Managed Identity. Untuk informasi selengkapnya, lihat Keamanan Azure Storage.

Anda mungkin perlu memperbarui bidang berikut, bergantung pada operasi:

  • endpoint
  • basePath
  • key
  • sourceURL
  • targetURL
  • glossaryURL
  • id (ID pekerjaan)

Mencari nilai id

  • Anda dapat menemukan pekerjaan id di nilai URL Header Operation-Location respons metode POSTstart-batch-translation. String alfanumerik yang /document/ mengikuti parameter adalah pekerjaan idoperasi :
Header respons URL Respons
Operasi-Lokasi {document-translation-endpoint}/translator/document/9dce0aa9-78dc-41ba-8cae-2e2f3c2ff8ec?api-version={date}
  • Anda juga dapat menggunakan permintaan status get-translations untuk mengambil daftar pekerjaan terjemahan dan tugasnyaid.

Mulai terjemahan batch asinkron


    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");

            }

        }

    }

Dapatkan format dokumen yang didukung

Ambil daftar format file yang didukung. Jika berhasil, metode ini akan menampilkan kode respons 200 OK.


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);
            }
}

Mendapatkan status untuk pekerjaan terjemahan

Dapatkan status saat ini untuk satu pekerjaan dan ringkasan semua pekerjaan pada permintaan Terjemahan Dokumen. Jika berhasil, metode ini akan menampilkan kode respons 200 OK.


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);
            }
    }
}

Mendapatkan status untuk dokumen tertentu

Ringkasan singkat

Ambil status untuk dokumen tertentu dalam permintaan Terjemahan Dokumen. Jika berhasil, metode ini akan menampilkan kode respons 200 OK.


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);
            }
}

Menghapus pekerjaan

Ringkasan singkat

Batalkan tugas yang saat ini sedang diproses atau diantrikan. Hanya dokumen yang terjemahannya tidak dimulai yang dibatalkan.


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);
            }
}

Kode status HTTP umum

Kode status HTTP Deskripsi Kemungkinan alasan
200 OK Permintaan berhasil.
400 Permintaan Buruk Parameter yang diperlukan hilang, kosong, atau null. Atau, nilai yang diteruskan ke parameter yang diperlukan atau opsional tidak valid. Masalah umum adalah header yang terlalu panjang.
401 Tidak diizinkan Permintaan tersebut tidak diotorisasi. Periksa untuk memastikan kunci atau token Anda valid dan berada di wilayah yang benar. Saat mengelola langganan Anda di portal Azure, pastikan Anda menggunakan sumber daya layanan tunggal Penerjemah bukan sumber daya multi-layanan layanan Azure AI.
429 Terlalu Banyak Permintaan Anda melebihi kuota atau tingkat permintaan yang diizinkan untuk langganan Anda.
502 Gateway buruk Masalah jaringan atau sisi server. Juga dapat menunjukkan header yang tidak valid.

Pelajari lebih lanjut

Langkah berikutnya

Membuat sistem bahasa kustom menggunakan Penerjemah Kustom