문서 번역에 대한 관리 ID
Azure 리소스에 대한 관리 ID는 Azure 관리되는 리소스에 대한 Microsoft Entra ID 및 특정 권한을 만드는 서비스 주체입니다. 관리 ID는 스토리지 데이터에 대한 액세스 권한을 부여하고 SAS(공유 액세스 서명 토큰)를 원본 및 대상 URL에 포함해야 하는 요구 사항을 바꾸는 더 안전한 방법입니다.
관리 ID를 사용하여 사용자 고유의 애플리케이션을 포함하여 Microsoft Entra 인증을 지원하는 모든 리소스에 대한 액세스 권한을 부여할 수 있습니다.
Azure 리소스에 대한 액세스 권한을 부여하려면
Azure RBAC(Azure 역할 기반 액세스 제어)를 사용하여 관리 ID에 Azure 역할을 할당합니다.Azure에서 관리 ID를 사용하는 데 추가되는 비용은 없습니다.
Important
관리 ID를 사용하는 경우 HTTP 요청에 SAS 토큰 URL을 포함하지 마세요. 요청이 실패합니다. 관리 ID 사용은 SAS(공유 액세스 서명 토큰)를 원본 및 대상 URL에 포함해야 하는 요구 사항을 대체합니다.
문서 번역 작업에 관리 ID를 사용하려면 미국 동부와 같은 특정 지리적 Azure 지역에 Translator 리소스를 만들어야 합니다. Translator 리소스 지역이 전역으로 설정된 경우 문서 번역에 관리 ID를 사용할 수 없습니다. 문서 번역에 SAS(공유 액세스 서명 토큰)를 계속 사용할 수 있습니다.
문서 번역은 S1 표준 서비스 계획(종량제) 또는 D3 볼륨 할인 플랜에서만 사용할 수 있습니다. Azure AI 서비스 가격 책정 - 번역기를 참조하세요.
필수 조건
시작하려면 다음이 필요합니다.
단일 서비스 Translator(다중 서비스 Azure AI Services가 아님) 리소스가 미국 서부와 같은 지리적 지역에 할당되었습니다. 자세한 단계는 다중 서비스 리소스 만들기를 참조하세요.
Azure Portal을 사용하여
Azure RBAC(Azure 역할 기반 액세스 제어)를 간략히 이해합니다.Translator 리소스와 동일한 지역의 Azure Blob Storage 계정. 또한 스토리지 계정 내에서 Blob 데이터를 저장하고 구성하는 컨테이너를 만들어야 합니다.
스토리지 계정이 방화벽 뒤에 있는 경우 다음과 같은 구성을 사용하도록 설정해야 합니다.
Azure Portal로 이동하여 Azure 계정에 로그인합니다.
스토리지 계정을 선택합니다.
왼쪽 창의 보안 + 네트워킹 그룹에서 네트워킹을 선택합니다.
방화벽 및 가상 네트워크 탭에서 선택한 가상 네트워크 및 IP 주소에서 사용을 선택합니다.
모든 확인란을 선택 취소합니다.
Microsoft 네트워크 라우팅이 선택되어 있는지 확인합니다.
리소스 인스턴스 섹션에서 Microsoft.CognitiveServices/accounts를 리소스 종류로 선택하고 Translator 리소스를 인스턴스 이름으로 선택합니다.
신뢰할 수 있는 서비스 목록의 Azure 서비스에서 이 스토리지 계정에 액세스하도록 허용 확인란이 선택되어 있는지 확인합니다. 예외 관리에 대한 자세한 내용은 Azure Storage 방화벽 및 가상 네트워크 구성을 참조하세요.
저장을 선택합니다.
참고 항목
네트워크 변경 내용이 전파되는 데 최대 5분이 걸릴 수 있습니다.
이제 네트워크 액세스가 허용되었지만 Translator 리소스는 여전히 Storage 계정의 데이터에 액세스할 수 없습니다. Translator 리소스에 대한 관리 ID를 만들고특정 액세스 역할을 할당해야 합니다.
관리 ID 할당
관리 ID에는 시스템 할당 및 사용자 할당의 두 가지 유형이 있습니다. 현재 문서 번역은 시스템 할당 관리 ID를 지원합니다.
시스템이 할당한 관리 ID는 서비스 인스턴스에서 직접 사용하도록 설정됩니다. 기본적으로 사용하도록 설정되지 않습니다. 리소스로 이동하여 ID 설정을 업데이트해야 합니다.
시스템이 할당한 관리 ID는 수명 주기 내내 리소스에 연결됩니다. 리소스를 삭제하면 관리 ID도 삭제됩니다.
다음 단계에서는 시스템 할당 관리 ID를 사용하도록 설정하고 Azure Blob Storage 계정에 대한 제한된 액세스 권한을 Translator 리소스에 부여합니다.
시스템 할당 관리 ID 사용
Blob을 만들거나 읽거나 삭제하려면 먼저 스토리지 계정에 대한 액세스 권한을 Translator에 부여해야 합니다. 시스템 할당 관리 ID를 사용하여 Translator를 사용하도록 설정한 후에는 Azure RBAC(Azure 역할 기반 액세스 제어)를 사용하여 Azure Storage 컨테이너에 대한 Translator 액세스 권한을 부여할 수 있습니다.
Azure Portal로 이동하여 Azure 계정에 로그인합니다.
Translator 리소스를 선택합니다.
왼쪽 창의 리소스 관리 그룹에서 ID를 선택합니다.
시스템 할당 탭 내에서 상태 토글을 켭니다.
Important
사용자가 할당한 관리 ID는 일괄 처리 기록 스토리지 계정 시나리오에 대한 요구 사항을 충족하지 않습니다. 시스템이 할당한 관리 ID를 사용하도록 설정해야 합니다.
저장을 선택합니다.
Translator 리소스에 대한 스토리지 계정 액세스 권한 부여
Important
시스템 할당 관리 ID 역할을 할당하려면 스토리지 리소스에 대한 스토리지 범위에서 소유자 또는 사용자 액세스 관리자와 같은 Microsoft.Authorization/roleAssignments/write 권한이 필요합니다.
Azure Portal로 이동하여 Azure 계정에 로그인합니다.
Translator 리소스를 선택합니다.
왼쪽 창의 리소스 관리 그룹에서 ID를 선택합니다.
권한에서 Azure 역할 할당을 선택합니다.
열린 Azure 역할 할당 페이지의 드롭다운 메뉴에서 구독을 선택한 다음, + 역할 할당 추가를 선택합니다.
다음으로, 번역기 서비스 리소스에 Storage Blob 데이터 기여자 역할을 할당합니다. Storage Blob 데이터 기여자 역할은 Blob 컨테이너 및 데이터에 대한 읽기, 쓰기 및 삭제 권한을 Translator(시스템 할당 관리 ID로 표시됨)에 제공합니다. 역할 할당 추가 팝업 창에서 다음과 같이 필드를 완료하고 저장을 선택합니다.
필드 값 범위 저장. 구독 스토리지 리소스와 연결된 구독입니다. 리소스 스토리지 리소스의 이름. 역할 Storage Blob 데이터 기여자. 
추가된 역할 할당 확인 메시지가 표시된 후 페이지를 새로 고쳐 추가된 역할 할당을 확인합니다.
새로운 역할 할당이 즉시 표시되지 않으면 기다렸다가 페이지를 한 번 더 새로 고쳐 보세요. 역할 할당을 할당하거나 제거하는 경우 변경 내용이 적용되는 데 최대 30분이 걸릴 수 있습니다.
HTTP 요청
비동기 일괄 처리 변환 요청은 POST 요청을 통해 번역기 서비스 엔드포인트에 제출됩니다.
관리 ID 및
Azure RBAC를 사용하면 더 이상 SAS URL을 포함할 필요가 없습니다.성공하면 POST 메서드는
202 Accepted응답 코드를 반환하고 서비스는 일괄 처리 요청을 만듭니다.번역된 문서가 대상 컨테이너에 표시됩니다.
헤더
각 Document Translation API 요청에는 다음 헤더가 포함됩니다.
| HTTP 헤더 | 설명 |
|---|---|
| Ocp-Apim-Subscription-Key | 필수: 값은 번역기 또는 Azure AI 서비스 리소스에 대한 Azure 키입니다. |
| 콘텐츠-형식 | 필수: 페이로드의 콘텐츠 형식을 지정합니다. 허용되는 값은 application/json 또는 charset=UTF-8입니다. |
POST 요청 본문
- 요청 URL은 POST
https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.1/batches입니다. - 요청 본문은
inputs라는 JSON 개체입니다. inputs개체는 원본 및 대상 언어 쌍에 대한sourceURL및targetURL컨테이너 주소를 모두 포함합니다. 시스템 할당 관리 ID를 사용하면 일반 스토리지 계정 URL(SAS 또는 기타 추가 항목 없음)을 사용합니다. 형식은https://<storage_account_name>.blob.core.windows.net/<container_name>입니다.prefix및suffix필드(선택 사항)는 폴더를 포함하여 컨테이너의 문서를 필터링하는 데 사용됩니다.glossaries필드(선택 사항)의 값은 문서가 번역될 때 적용됩니다.- 각 대상 언어의
targetUrl은 고유해야 합니다.
Important
이름이 같은 파일이 대상에 이미 있으면 작업이 실패합니다. 관리 ID를 사용하는 경우 HTTP 요청에 SAS 토큰 URL을 포함하지 마세요. 포함하면 요청이 실패합니다.
컨테이너의 모든 문서 번역
이 샘플 요청 본문은 대상 언어로 번역할 모든 문서에 대한 원본 컨테이너를 참조합니다.
자세한 내용은 요청 매개 변수를 참조하세요.
{
"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"
}
]
}
]
}
컨테이너의 특정 문서 번역
이 샘플 요청 본문은 두 개의 대상 언어로 번역할 단일 원본 문서를 참조합니다.
Important
앞에서 설명한 요청 매개 변수 외에도 "storageType": "File"을 포함해야 합니다. 그렇지 않으면 원본 URL이 컨테이너 수준에 있는 것으로 간주됩니다.
{
"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"
}
]
}
]
}
사용자 지정 용어집을 사용하여 컨테이너의 모든 문서 번역
이 샘플 요청 본문은 용어집을 사용하여 대상 언어로 번역할 모든 문서에 대한 원본 컨테이너를 참조합니다.
자세한 내용은 요청 매개 변수를 참조하세요.
{
"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"
}
]
}
]
}
]
}
좋습니다! 시스템 할당 관리 ID를 사용하도록 설정하고 사용하는 방법을 알아보았습니다. Azure 리소스 및 Azure RBAC에 대한 관리 ID를 사용하면 HTTP 요청에 SAS 토큰을 포함하지 않고 스토리지 리소스에 대한 특정 액세스 권한을 Translator에 부여했습니다.