Identitas terkelola untuk Document Translation

Identitas terkelola untuk sumber daya Azure adalah perwakilan layanan yang membuat identitas Microsoft Entra dan izin khusus untuk sumber daya terkelola Azure. Identitas terkelola adalah cara yang lebih aman untuk memberikan akses ke data penyimpanan dan mengganti persyaratan bagi Anda untuk menyertakan token tanda tangan akses bersama (SAS) dengan URL sumber dan target Anda.

• Anda dapat menggunakan identitas terkelola untuk memberikan akses ke sumber daya apa pun yang mendukung autentikasi Microsoft Entra, termasuk aplikasi Anda sendiri.

• Untuk memberikan akses ke sumber daya Azure, tetapkan peran Azure ke identitas terkelola menggunakan kontrol akses berbasis peran Azure (Azure RBAC).

• Tidak ada biaya tambahan untuk menggunakan identitas terkelola di Azure.

Penting

• Saat menggunakan identitas terkelola, jangan sertakan URL token SAS dengan permintaan HTTP Anda, karena permintaan Anda akan gagal. Menggunakan identitas terkelola menggantikan persyaratan bagi Anda untuk menyertakan token tanda tangan akses bersama (SAS) dengan URL sumber dan target Anda.

• Untuk menggunakan identitas terkelola untuk operasi Terjemahan Dokumen, Anda harus membuat sumber daya Penerjemah di wilayah Azure geografis tertentu seperti AS Timur. Jika wilayah sumber daya Penerjemah Anda diatur ke Global, maka Anda tidak dapat menggunakan identitas terkelola untuk Terjemahan Dokumen. Anda masih dapat menggunakan token Tanda Tangan Akses Bersama (SAS) untuk Terjemahan Dokumen.

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

Prasyarat

Untuk memulai, Anda memerlukan:

• Akun Azure yang aktif—jika belum memilikinya, Anda dapat membuat akun gratis.

• Sumber daya Penerjemah layanan tunggal (bukan layanan Azure AI multi-layanan) yang ditetapkan ke wilayah geografis seperti AS Barat. Untuk langkah-langkah mendetail, lihat Membuat sumber daya layanan Azure AI.

• Pemahaman singkat tentang kontrol akses berbasis peran Azure (Azure RBAC) menggunakan portal Azure.

• Akun Azure Blob Storage di wilayah yang sama dengan sumber daya Penerjemah Anda. Anda juga perlu membuat kontainer untuk menyimpan dan mengatur data blob dalam akun penyimpanan Anda.

• Jika akun penyimpanan Anda berada di belakang firewall, Anda harus mengaktifkan konfigurasi berikut:

  1. Buka portal Azure dan masuk ke akun Azure Anda.

  2. Pilih akun Penyimpanan.

  3. Di grup Keamanan + jaringan di panel kiri, pilih Jaringan.

  4. Di tab Firewall dan jaringan virtual, pilih Diaktifkan dari jaringan virtual dan alamat IP yang dipilih.

     

  5. Batal pilih semua kotak centang.

  6. Pastikan perutean jaringan Microsoft dipilih.

  7. Di bawah bagian Instans sumber daya, pilih Microsoft.CognitiveServices/accounts sebagai jenis sumber daya dan pilih sumber daya Penerjemah Anda sebagai nama instans.

  8. Pastikan bahwa kotak Izinkan layanan Azure pada daftar layanan tepercaya untuk mengakses akun penyimpanan ini dicentang. Untuk informasi selengkapnya tentang mengelola pengecualian, lihat Mengonfigurasi firewall Azure Storage dan jaringan virtual.

     

  9. Pilih Simpan.

     Catatan

     Mungkin perlu waktu hingga 5 menit agar perubahan jaringan disebarluaskan.

  Meskipun akses jaringan sekarang diizinkan, sumber daya Penerjemah Anda masih tidak dapat mengakses data di akun Penyimpanan Anda. Anda perlu membuat identitas terkelola untuk dan menetapkan peran akses tertentu ke sumber daya Penerjemah Anda.

Penugasan identitas terkelola

Ada dua jenis identitas terkelola: identitas yang ditetapkan sistem dan identitas yang ditetapkan pengguna. Saat ini, Document Translation mendukung identitas terkelola yang ditetapkan sistem:

• Identitas terkelola yang ditetapkan sistem diaktifkan langsung di instans layanan Azure. Ini tidak diaktifkan secara default; Anda harus mengakses sumber daya Anda dan memperbarui pengaturan identitasnya.

• Identitas terkelola yang ditetapkan sistem dikaitkan dengan sumber daya Anda sepanjang siklus hidupnya. Jika Anda menghapus sumber daya, identitas terkelola juga akan dihapus.

Dalam langkah-langkah berikut, kami mengaktifkan identitas terkelola yang ditetapkan sistem dan memberikan akses terbatas sumber daya Penerjemah Anda ke akun Azure Blob Storage Anda.

Mengaktifkan identitas terkelola yang ditetapkan sistem

Anda harus memberikan akses sumber daya Penerjemah ke akun penyimpanan Anda sebelum dapat membuat, membaca, atau menghapus blob. Setelah mengaktifkan sumber daya Penerjemah dengan identitas terkelola yang ditetapkan sistem, Anda dapat menggunakan kontrol akses berbasis peran Azure (Azure RBAC), untuk memberikan akses Penerjemah ke kontainer penyimpanan Azure Anda.

1. Buka portal Azure dan masuk ke akun Azure Anda.

2. Pilih sumber daya Penerjemah.

3. Di grup Manajemen Sumber Daya di panel kiri, pilih Identitas.

4. Di dalam tab Sistem yang ditetapkan, aktifkan tombol Status .

   

   Penting

   Identitas terkelola yang ditetapkan pengguna tidak akan memenuhi persyaratan untuk skenario akun penyimpanan transkripsi batch. Pastikan untuk mengaktifkan identitas terkelola yang ditetapkan sistem.

5. Pilih Simpan.

Memberikan akses akun penyimpanan untuk sumber daya Penerjemah Anda

Penting

Untuk menetapkan peran identitas terkelola yang ditetapkan sistem, Anda memerlukan izin Microsoft.Authorization/roleAssignments/write, seperti Pemilik atau Administrator Akses Pengguna di cakupan penyimpanan untuk sumber daya penyimpanan.

1. Buka portal Azure dan masuk ke akun Azure Anda.

2. Pilih sumber daya Penerjemah.

3. Di grup Manajemen Sumber Daya di panel kiri, pilih Identitas.

4. Di bawah Izin pilih Penetapan peran Azure:

   

5. Pada halaman penetapan peran Azure yang dibuka, pilih langganan Anda dari menu drop-down lalu pilih + Tambahkan penetapan peran.

   

6. Selanjutnya, tetapkan peran Kontributor Data Blob Penyimpanan ke sumber daya layanan Penerjemah Anda. Peran Kontributor Data Blob Penyimpanan memberi Penerjemah (diwakili oleh identitas terkelola yang ditetapkan sistem) akses membaca, menulis, dan menghapus ke kontainer dan data blob. Di jendela pop-up Tambahkan penetapan peran, isi bidang seperti berikut dan pilih Simpan:

   Bidang	Nilai
   Cakupan	Penyimpanan.
   Langganan	Langganan yang terkait dengan sumber daya penyimpanan Anda.
   Sumber daya	Nama sumber daya penyimpanan Anda.
   Peran	Kontributor Data Blob Penyimpanan.

   

7. Setelah pesan konfirmasi Penetapan Peran Ditambahkan muncul, refresh halaman untuk melihat penetapan peran yang ditambahkan.

   

8. Jika Anda tidak segera melihat penetapan peran baru, tunggu dan coba refresh halaman lagi. Saat Anda menetapkan atau menghapus penetapan peran, diperlukan waktu hingga 30 menit agar perubahan diterapkan.

   

Permintaan HTTP

• Permintaan terjemahan batch asinkron dikirimkan ke titik akhir layanan Penerjemah Anda melalui permintaan POST.

• Dengan identitas terkelola dan Azure RBAC, Anda tidak perlu lagi menyertakan URL SAS.

• Jika berhasil, metode POST mengembalikan 202 Accepted kode respons dan layanan membuat permintaan batch.

• Dokumen yang diterjemahkan muncul di kontainer target Anda.

Header

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.

Isi permintaan POST

• URL permintaan 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. Dengan identitas terkelola yang ditetapkan sistem, Anda menggunakan URL Akun Penyimpanan biasa (tidak ada SAS atau tambahan lainnya). Formatnya adalah https://<storage_account_name>.blob.core.windows.net/<container_name>.
• Bidang prefix dan suffix (opsional) digunakan untuk memfilter dokumen dalam kontainer termasuk folder.
• Nilai untuk bidang glossaries (opsional) diterapkan saat dokumen sedang diterjemahkan.
• targetUrl untuk bahasa target harus unik.

Penting

Jika file dengan nama yang sama sudah ada di tujuan, pekerjaan akan gagal. Saat menggunakan identitas terkelola, jangan sertakan URL token SAS dengan permintaan HTTP Anda. Jika Anda melakukannya, permintaan Anda akan gagal.

Menerjemahkan semua dokumen dalam kontainer

Isi permintaan sampel ini mereferensikan kontainer sumber untuk semua dokumen yang akan diterjemahkan ke bahasa target.

Untuk informasi selengkapnya, lihat parameter permintaan.

{
    "inputs": [
        {
            "source": {
                "sourceUrl": "https://<storage_account_name>.blob.core.windows.net/<source_container_name>"
            },
            "targets": [
                {
                    "targetUrl": "https://<storage_account_name>.blob.core.windows.net/<target_container_name>"
                    "language": "fr"
                }
            ]
        }
    ]
}

Menerjemahkan dokumen tertentu dalam kontainer

Isi permintaan sampel ini mereferensikan satu dokumen sumber yang akan diterjemahkan ke dalam dua bahasa target.

Penting

Selain parameter permintaan yang dicatat sebelumnya, Anda harus menyertakan "storageType": "File". Jika tidak, URL sumber diasumsikan berada di tingkat kontainer.

{
    "inputs": [
        {
            "storageType": "File",
            "source": {
                "sourceUrl": "https://<storage_account_name>.blob.core.windows.net/<source_container_name>/source-english.docx"
            },
            "targets": [
                {
                    "targetUrl": "https://<storage_account_name>.blob.core.windows.net/<target_container_name>/Target-Spanish.docx"
                    "language": "es"
                },
                {
                    "targetUrl": "https://<storage_account_name>.blob.core.windows.net/<target_container_name>/Target-German.docx",
                    "language": "de"
                }
            ]
        }
    ]
}

Menerjemahkan semua dokumen dalam kontainer menggunakan glosarium kustom

Isi permintaan sampel ini mereferensikan kontainer sumber untuk semua dokumen yang akan diterjemahkan ke bahasa target menggunakan glosarium.

Untuk informasi selengkapnya, lihat parameter permintaan.

{
    "inputs": [
        {
            "source": {
                "sourceUrl": "https://<storage_account_name>.blob.core.windows.net/<source_container_name>",
                "filter": {
                    "prefix": "myfolder/"
                }
            },
            "targets": [
                {
                    "targetUrl": "https://<storage_account_name>.blob.core.windows.net/<target_container_name>",
                    "language": "es",
                    "glossaries": [
                        {
                            "glossaryUrl": "https://<storage_account_name>.blob.core.windows.net/<glossary_container_name>/en-es.xlf",
                            "format": "xliff"
                        }
                    ]
                }
            ]
        }
    ]
}

Bagus! Anda baru saja mempelajari cara mengaktifkan dan menggunakan identitas terkelola yang ditetapkan sistem. Dengan identitas terkelola untuk Sumber Daya Azure dan Azure RBAC, Anda memberikan hak akses khusus Penerjemah ke sumber daya penyimpanan Anda tanpa menyertakan token SAS dengan permintaan HTTP Anda.

Langkah berikutnya

Mulai Cepat: Mulai menggunakan Terjemahan Dokumen

Tutorial: Mengakses Azure Storage dari aplikasi web menggunakan identitas terkelola