Mulai penerjemahan

  • Artikel

Layanan Referensi
: Versi API Terjemahan
Dokumen Azure AI: v1.1

Gunakan API ini untuk memulai permintaan penerjemahan dengan layanan Document Translation. Setiap permintaan dapat berisi beberapa dokumen dan harus berisi kontainer sumber dan tujuan untuk setiap dokumen.

Filter awalan dan akhiran (jika disediakan) digunakan untuk memfilter folder. Awalan diterapkan ke subpath setelah nama kontainer.

Memori Glosarium/Terjemahan dapat disertakan dalam permintaan dan diterapkan oleh layanan saat dokumen diterjemahkan.

Jika glosarium tidak valid atau tidak dapat dijangkau selama terjemahan, kesalahan ditunjukkan dalam status dokumen. Jika file dengan nama yang sama sudah ada di tujuan, pekerjaan gagal. TargetUrl untuk setiap bahasa sasaran harus unik.

URL Permintaan

Kirim permintaan POST ke:

POST https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.1/batches

Pelajari cara menemukan nama domain kustom Anda.

Penting

  • Semua permintaan API ke layanan Terjemahan Dokumen memerlukan titik akhir domain kustom.
  • Anda tidak dapat menggunakan titik akhir yang ditemukan di halaman Kunci dan Titik Akhir sumber daya portal Azure atau titik akhir penerjemah global— api.cognitive.microsofttranslator.com —untuk membuat permintaan HTTP ke Penerjemahan Dokumen.

Header permintaan

Header permintaan adalah:

Header Deskripsi
Ocp-Apim-Subscription-Key Header permintaan yang diperlukan

BatchRequest (isi)

Definisi untuk permintaan terjemahan batch input. Setiap permintaan dapat berisi beberapa dokumen dan harus berisi kontainer sumber dan target untuk setiap dokumen. Jenis media sumber: application/json, text/json, application/*+json.


{
  "inputs": [
    {
      "source": {
        "sourceUrl": "https://myblob.blob.core.windows.net/Container/",
        "filter": {
          "prefix": "FolderA",
          "suffix": ".txt"
        },
        "language": "en",
        "storageSource": "AzureBlob"
      },
      "targets": [
        {
          "targetUrl": "https://myblob.blob.core.windows.net/TargetUrl/",
          "category": "general",
          "language": "fr",
          "glossaries": [
            {
              "glossaryUrl": "https://myblob.blob.core.windows.net/Container/myglossary.tsv",
              "format": "XLIFF",
              "version": "2.0",
              "storageSource": "AzureBlob"
            }
          ],
          "storageSource": "AzureBlob"
        }
      ],
      "storageType": "Folder"
    }
  ],
  "options": {
    "experimental": true
  }
}

Input

Definisi untuk permintaan terjemahan batch input.

Parameter kunci Jenis Wajib Parameter permintaan Deskripsi
Input array Benar • sumber (objek)

• target (array)

• storageType (string)		 Input data sumber.

inputs.source

Definisi untuk data sumber.

Parameter kunci Jenis Wajib Parameter permintaan Deskripsi
inputs.source object Benar • sourceUrl (string)

• filter (objek)

• bahasa (string)

• storageSource (string)		 Data sumber untuk dokumen input.
inputs.source.sourceUrl string Benar •String Lokasi kontainer untuk file atau folder sumber.
inputs.source.filter object Salah • awalan (string)

• akhiran (string)		 String peka huruf besar/kecil untuk memfilter dokumen di jalur sumber.
inputs.source.filter.prefix string Salah •String String awalan peka huruf besar/kecil untuk memfilter dokumen di jalur sumber untuk terjemahan. Sering digunakan untuk menunjuk subfolder untuk terjemahan. Contoh: "FolderA".
inputs.source.filter.suffix string Salah •String String akhiran peka huruf besar/kecil untuk memfilter dokumen di jalur sumber untuk terjemahan. Paling sering digunakan untuk ekstensi file. Contoh: ".txt"
inputs.source.language string Salah •String Kode bahasa untuk dokumen sumber. Jika tidak ditentukan, autodetect diimplementasikan.
inputs.source.storageSource string Salah •String Sumber penyimpanan untuk input. Default ke AzureBlob.

inputs.targets

Definisi untuk data target dan glosarium.

Parameter kunci Jenis Wajib Parameter permintaan Deskripsi
inputs.targets array Benar • targetUrl (string)

• kategori (string)

• bahasa (string)

• glosarium (array)

• storageSource (string)		 Data target dan glosarium untuk dokumen yang diterjemahkan.
inputs.targets.targetUrl string Benar •String Lokasi lokasi kontainer untuk dokumen yang diterjemahkan.
inputs.targets.category string Salah •String Klasifikasi atau kategori untuk permintaan terjemahan. Contoh: umum.
inputs.targets.language string Benar •String Kode bahasa target. Contoh: "fr".
inputs.targets.glossaries array Salah • glosariumUrl (string)

• format (string)

• versi (string)

• storageSource (string)		 LihatMembuat dan menggunakan glosarium
inputs.targets.glossaries.glossaryUrl string Benar (jika menggunakan glosarium) •String Lokasi glosarium. Ekstensi file digunakan untuk mengekstrak pemformatan jika parameter format tidak disediakan. Jika pasangan bahasa terjemahan tidak ada di glosarium, itu tidak diterapkan.
inputs.targets.glossaries.format string Salah •String Format file yang ditentukan untuk glosarium. Untuk memeriksa apakah format file Anda didukung, lihatMendapatkan format glosarium yang didukung.
inputs.targets.glossaries.version string Salah •String Indikator versi. Contoh: "2.0".
inputs.targets.glossaries.storageSource string Salah •String Sumber penyimpanan untuk glosarium. Default ke _AzureBlob_.
inputs.targets.storageSource string Salah •String Sumber penyimpanan untuk target. Default ke _AzureBlob_.

inputs.storageType

Definisi entitas penyimpanan untuk dokumen input.

Parameter kunci Jenis Wajib Parameter permintaan Deskripsi
inputs.storageType string Salah •Folder

• File		 Jenis penyimpanan untai (karakter) sumber dokumen input. Hanya "Folder" atau "File" yang merupakan nilai yang valid.

Opsi

Definisi untuk permintaan terjemahan batch input.

Parameter kunci Jenis Wajib Parameter permintaan Deskripsi
opsi object Salah Informasi sumber untuk dokumen input.
options.experimental boolean Salah •true

• false		 Menunjukkan apakah permintaan menyertakan fitur eksperimental (jika berlaku). Hanya boolean atau truefalse nilai yang valid.

Contoh permintaan

Berikut ini adalah contoh permintaan batch.

Catatan

Dalam contoh berikut, akses terbatas telah diberikan ke konten kontainer Azure Storage menggunakan token tanda tangan akses bersama (SAS).

Menerjemahkan semua dokumen dalam kontainer

{
    "inputs": [
        {
            "source": {
                "sourceUrl": "https://my.blob.core.windows.net/source-en?sv=2019-12-12&st=2021-03-05T17%3A45%3A25Z&se=2021-03-13T17%3A45%3A00Z&sr=c&sp=rl&sig=SDRPMjE4nfrH3csmKLILkT%2Fv3e0Q6SWpssuuQl1NmfM%3D"
            },
            "targets": [
                {
                    "targetUrl": "https://my.blob.core.windows.net/target-fr?sv=2019-12-12&st=2021-03-05T17%3A49%3A02Z&se=2021-03-13T17%3A49%3A00Z&sr=c&sp=wdl&sig=Sq%2BYdNbhgbq4hLT0o1UUOsTnQJFU590sWYo4BOhhQhs%3D",
                    "language": "fr"
                }
            ]
        }
    ]
}

Menerjemahkan semua dokumen dalam kontainer yang menerapkan glosarium

{
    "inputs": [
        {
            "source": {
                "sourceUrl": "https://my.blob.core.windows.net/source-en?sv=2019-12-12&st=2021-03-05T17%3A45%3A25Z&se=2021-03-13T17%3A45%3A00Z&sr=c&sp=rl&sig=SDRPMjE4nfrH3csmKLILkT%2Fv3e0Q6SWpssuuQl1NmfM%3D"
            },
            "targets": [
                {
                    "targetUrl": "https://my.blob.core.windows.net/target-fr?sv=2019-12-12&st=2021-03-05T17%3A49%3A02Z&se=2021-03-13T17%3A49%3A00Z&sr=c&sp=wdl&sig=Sq%2BYdNbhgbq4hLT0o1UUOsTnQJFU590sWYo4BOhhQhs%3D",
                    "language": "fr",
                    "glossaries": [
                        {
                            "glossaryUrl": "https://my.blob.core.windows.net/glossaries/en-fr.xlf?sv=2019-12-12&st=2021-03-05T17%3A45%3A25Z&se=2021-03-13T17%3A45%3A00Z&sr=c&sp=rl&sig=BsciG3NWoOoRjOYesTaUmxlXzyjsX4AgVkt2AsxJ9to%3D",
                            "format": "xliff",
                            "version": "1.2"
                        }
                    ]

                }
            ]
        }
    ]
}

Menerjemahkan folder tertentu dalam kontainer

Pastikan Anda menentukan nama folder (peka huruf besar/kecil) sebagai awalan dalam filter.

{
    "inputs": [
        {
            "source": {
                "sourceUrl": "https://my.blob.core.windows.net/source-en?sv=2019-12-12&st=2021-03-05T17%3A45%3A25Z&se=2021-03-13T17%3A45%3A00Z&sr=c&sp=rl&sig=SDRPMjE4nfrH3csmKLILkT%2Fv3e0Q6SWpssuuQl1NmfM%3D",
                "filter": {
                    "prefix": "MyFolder/"
                }
            },
            "targets": [
                {
                    "targetUrl": "https://my.blob.core.windows.net/target-fr?sv=2019-12-12&st=2021-03-05T17%3A49%3A02Z&se=2021-03-13T17%3A49%3A00Z&sr=c&sp=wdl&sig=Sq%2BYdNbhgbq4hLT0o1UUOsTnQJFU590sWYo4BOhhQhs%3D",
                    "language": "fr"
                }
            ]
        }
    ]
}

Menerjemahkan dokumen tertentu dalam kontainer

  • Tentukan "storageType": File.
  • Buat URL sumber & token SAS untuk blob/dokumen tertentu.
  • Tentukan filename target sebagai bagian dari URL target – meskipun token SAS masih untuk kontainer.

Permintaan sampel ini menunjukkan satu dokumen yang diterjemahkan ke dalam dua bahasa target.

{
    "inputs": [
        {
            "storageType": "File",
            "source": {
                "sourceUrl": "https://my.blob.core.windows.net/source-en/source-english.docx?sv=2019-12-12&st=2021-01-26T18%3A30%3A20Z&se=2021-02-05T18%3A30%3A00Z&sr=c&sp=rl&sig=d7PZKyQsIeE6xb%2B1M4Yb56I%2FEEKoNIF65D%2Fs0IFsYcE%3D"
            },
            "targets": [
                {
                    "targetUrl": "https://my.blob.core.windows.net/target/try/Target-Spanish.docx?sv=2019-12-12&st=2021-01-26T18%3A31%3A11Z&se=2021-02-05T18%3A31%3A00Z&sr=c&sp=wl&sig=AgddSzXLXwHKpGHr7wALt2DGQJHCzNFF%2F3L94JHAWZM%3D",
                    "language": "es"
                },
                {
                    "targetUrl": "https://my.blob.core.windows.net/target/try/Target-German.docx?sv=2019-12-12&st=2021-01-26T18%3A31%3A11Z&se=2021-02-05T18%3A31%3A00Z&sr=c&sp=wl&sig=AgddSzXLXwHKpGHr7wALt2DGQJHCzNFF%2F3L94JHAWZM%3D",
                    "language": "de"
                }
            ]
        }
    ]
}

Kode status respons

Berikut ini adalah kemungkinan kode status HTTP yang dihasilkan oleh permintaan.

Kode status Deskripsi
202 Diterima. Permintaan berhasil dan permintaan batch dibuat. Header Operation-Location menunjukkan url status dengan operasi ID.HeadersOperation-Location: string
400 Permintaan Buruk. Permintaan tidak valid. Periksa parameter input.
401 Tidak Sah. Memeriksa info masuk Anda.
429 Tingkat permintaan terlalu tinggi.
500 Kesalahan Server Internal.
503 Saat ini layanan tidak tersedia. Coba lagi nanti.
Kode Status Lainnya • Terlalu banyak permintaan
• Server sementara tidak tersedia

Respons kesalahan

Parameter kunci Jenis Deskripsi
kode string Enum yang berisi kode galat tingkat tinggi. Nilai yang mungkin:
  • InternalServerError
  • InvalidArgument
  • InvalidRequest
  • RequestRateTooHigh
  • ResourceNotFound
  • ServiceUnavailable
  • Tidak diizinkan
pesan string Mendapatkan pesan kesalahan tingkat tinggi.
innerError InnerTranslationError Format Kesalahan Dalam baru yang sesuai dengan Panduan API layanan Azure AI. Pesan kesalahan ini berisi properti yang diperlukan: ErrorCode, pesan, dan target properti opsional, detail(pasangan nilai kunci), dan kesalahan dalam (dapat ditumpuk).
inner.Errorcode string Mendapatkan untai kesalahan kode.
innerError.message string Mendapatkan pesan kesalahan tingkat tinggi.
innerError.target string Mendapatkan sumber kesalahan. Misalnya, itu akan menjadi documents atau document id jika dokumen tidak valid.

Contoh

Contoh respons berhasil

Informasi berikut dikembalikan dalam respons yang berhasil.

Anda dapat menemukan ID pekerjaan di header respons metode POST nilai Operation-Location URL. Parameter terakhir dari URL adalah ID pekerjaan operasi (string berikut "/operation/").

Operation-Location: https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.1/operation/0FA2822F-4C2A-4317-9C20-658C801E0E55

Contoh respons kesalahan

{
  "error": {
    "code": "ServiceUnavailable",
    "message": "Service is temporary unavailable",
    "innerError": {
      "code": "ServiceTemporaryUnavailable",
      "message": "Service is currently unavailable.  Please try again later"
    }
  }
}

Langkah berikutnya

Ikuti mulai cepat kami untuk mempelajari lebih lanjut tentang menggunakan Terjemahan Dokumen dan pustaka klien.

Memulai Terjemahan Dokumen