Clientbibliotheken voor Batch-documentomzetting

Documentomzetting is een cloudfunctie van de Azure AI Vertalen-service waarmee asynchroon hele documenten in ondersteunde talen en verschillende bestandsindelingen worden vertaald. In deze snelstartgids leert u hoe u documentomzetting kunt gebruiken met een programmeertaal van uw keuze om een brondocument te vertalen in een doeltaal en tegelijkertijd structuur en tekstopmaak te behouden.

Belangrijk

• Documentomzetting wordt momenteel alleen ondersteund in de resource Vertalen (één service) en is niet opgenomen in de Azure AI-servicesresource (multiservice).

• Documentomzetting wordt ondersteund in betaalde lagen. Language Studio ondersteunt alleen de S1- of D3-exemplaarlagen. U wordt aangeraden Standard S1 te selecteren om documentomzetting uit te proberen. Zieprijzen voor Azure AI-services: Vertalen.

Vereisten

Om aan de slag te gaan, hebt u het volgende nodig:

• Een actief Azure-account. Als u nog geen account hebt, kunt u een gratis account aanmaken.

• Een resource met één service Vertalen (geen Azure AI-servicesresource met meerdere services). Als u van plan bent om de functie Documentvertaling te gebruiken met autorisatie voor beheerde identiteiten, kiest u een geografische regio, zoals VS - oost. Selecteer de Standard S1- of D3 - of prijscategorie.

• Een Azure Blob Storage-account. U maakt containers in uw Azure Blob Storage-account voor uw bron- en doelbestanden:

  • Broncontainer. In deze container uploadt u uw bestanden voor vertaling (vereist).
  • Doelcontainer. In deze container worden uw vertaalde bestanden opgeslagen (vereist).

Autorisatie van opslagcontainers

U kunt een van de volgende opties kiezen om toegang tot uw Vertalen resource te autoriseren.

✔️ Beheerde identiteit. Een beheerde identiteit is een service-principal waarmee een Microsoft Entra-identiteit en specifieke machtigingen voor een door Azure beheerde resource worden gemaakt. Met beheerde identiteiten kunt u uw Vertalen toepassing uitvoeren zonder referenties in uw code in te sluiten. Beheerde identiteiten zijn een veiligere manier om toegang te verlenen tot opslaggegevens en om de vereiste voor het opnemen van sas-tokens (Shared Access Signature) te vervangen door uw bron- en doel-URL's.

ZieBeheerde identiteiten voor documentomzetting voor meer informatie.

✔️ Shared Access Signature (SAS). Een handtekening voor gedeelde toegang is een URL die gedurende een opgegeven periode beperkte toegang verleent aan uw Vertalen-service. Als u deze methode wilt gebruiken, moet u SAS-tokens (Shared Access Signature) maken voor uw bron- en doelcontainers. Het sourceUrl en targetUrl moet een SAS-token (Shared Access Signature) bevatten, toegevoegd als een querytekenreeks. Het token kan worden toegewezen aan uw container of specifieke blobs.

• Uw broncontainer of -blob moet lees- en lijsttoegang aanwijzen.
• Uw doelcontainer of blob moet schrijf- en lijsttoegang aanwijzen.

ZieSAS-tokens maken voor meer informatie.

Uw toepassing bouwen

Er zijn verschillende hulpprogramma's beschikbaar voor het maken, bouwen en uitvoeren van Vertalen C#/.NET-toepassingen. Hier begeleiden we u bij het gebruik van de opdrachtregelinterface (CLI) of Visual Studio. Selecteer een van de volgende tabbladen om aan de slag te gaan:

.NET CLI

Uw project instellen

Gebruik in een consolevenster (zoals cmd, PowerShell of Bash) de opdracht dotnet new om een nieuwe console-app te maken met de naam batch-document-translation. Met deze opdracht maakt u een eenvoudig C#-project Hallo wereld met één bronbestand: Program.cs.

dotnet new console -n batch-document-translation

Wijzig uw map in de zojuist gemaakte app-map. Bouw uw toepassing met de volgende opdracht:

dotnet build

De build-uitvoer mag geen waarschuwingen of fouten bevatten.

...
Build succeeded.
 0 Warning(s)
 0 Error(s)
...

De clientbibliotheek installeren

Installeer in de toepassingsmap de clientbibliotheek voor documentomzetting voor .NET:

dotnet add package Azure.AI.Translation.Document --version 1.0.0

Een document of batchbestanden vertalen

1. Voor dit project hebt u een brondocument nodig dat is geüpload naar uw broncontainer. U kunt ons voorbeelddocument voor documentomzetting downloaden voor deze quickstart. De brontaal is Engels.

2. Open vanuit de projectmap het bestand Program.cs in uw favoriete editor of IDE. Verwijder de bestaande code, inclusief de regel Console.WriteLine("Hello World!").

3. Maak in de Program.cs van de toepassing variabelen voor uw sleutel en aangepast eindpunt. ZieUw sleutel en aangepast domeineindpunt ophalen voor meer informatie.

   private static readonly string endpoint = "<your-document-translation-endpoint>";
   private static readonly string key = "<your-key>";
   

4. Roep de StartTranslationAsync methode aan om een vertaalbewerking te starten voor een of meer documenten in één blobcontainer.

5. Als u wilt aanroepen StartTranslationAsync, moet u een DocumentTranslationInput object initialiseren dat de sourceUri, targetUrien targetLanguageCode parameters bevat:

   • Maak voor autorisatie van beheerde identiteit de volgende variabelen:

     • sourceUri. De URL voor de broncontainer met documenten die moeten worden vertaald.

     • targetUri De URL voor de doelcontainer waarnaar de vertaalde documenten worden geschreven.

     • targetLanguageCode. De taalcode voor de vertaalde documenten. U vindt taalcodes op onze ondersteuningspagina voor talen.

       Als u uw bron- en doel-URL's wilt vinden, gaat u naar uw opslagaccount in Azure Portal. Selecteer in de linkerzijbalk onder Gegevensopslag de optie Containers en volg deze stappen om uw brondocumenten en doelcontainer URLSop te halen.

       Source	Target
       1. Schakel het selectievakje naast de broncontainer in	1. Schakel het selectievakje naast de doelcontainer in.
       2. Selecteer in het hoofdvenstergebied een bestand of documenten voor vertaling.	2. Selecteer het beletselteken aan de rechterkant en kies Eigenschappen.
       3. De bron-URL bevindt zich boven aan de lijst Eigenschappen.	3. De doel-URL bevindt zich boven aan de lijst Eigenschappen.

   • Voor SAS-autorisatie (Shared Access Signature) maakt u deze variabelen

     • sourceUri. De SAS-URI, waaraan een SAS-token is toegevoegd als een querytekenreeks, zodat de broncontainer met documenten moet worden vertaald.
     • targetUri De SAS-URI, met een SAS-token toegevoegd als een querytekenreeks, voor de doelcontainer waarnaar de vertaalde documenten worden geschreven.
     • targetLanguageCode. De taalcode voor de vertaalde documenten. U vindt taalcodes op onze ondersteuningspagina voor talen.

Voorbeeld van code

Belangrijk

Vergeet niet de sleutel uit uw code te verwijderen wanneer u klaar bent, en maak deze sleutel nooit openbaar. Gebruik voor productie een veilige manier om uw referenties op te slaan en te openen, zoals Azure Key Vault. Zie Beveiliging van Azure AI-services voor meer informatie.

Voer het volgende codevoorbeeld in het Program.cs-bestand van uw toepassing in:

using Azure;
using Azure.AI.Translation.Document;
using System;
using System.Threading;
using System.Text;

class Program {

  // create variables for your custom endpoint and resource key
  private static readonly string endpoint = "<your-document-translation-endpoint>";
  private static readonly string key = "<your-key>";

  static async Task Main(string[] args) {

    // create variables for your sourceUrl, targetUrl, and targetLanguageCode
    Uri sourceUri = new Uri("<sourceUrl>");
    Uri targetUri = new Uri("<targetUrl>");
    string targetLanguage = "<targetLanguageCode>"

    // initialize a new instance  of the DocumentTranslationClient object to interact with the Document Translation feature
    DocumentTranslationClient client = new DocumentTranslationClient(new Uri(endpoint), new AzureKeyCredential(key));

    // initialize a new instance of the `DocumentTranslationInput` object to provide the location of input for the translation operation
    DocumentTranslationInput input = new DocumentTranslationInput(sourceUri, targetUri, targetLanguage);

    // initialize a new instance of the DocumentTranslationOperation class to track the status of the translation operation
    DocumentTranslationOperation operation = await client.StartTranslationAsync(input);

    await operation.WaitForCompletionAsync();

    Console.WriteLine($"  Status: {operation.Status}");
    Console.WriteLine($"  Created on: {operation.CreatedOn}");
    Console.WriteLine($"  Last modified: {operation.LastModified}");
    Console.WriteLine($"  Total documents: {operation.DocumentsTotal}");
    Console.WriteLine($"    Succeeded: {operation.DocumentsSucceeded}");
    Console.WriteLine($"    Failed: {operation.DocumentsFailed}");
    Console.WriteLine($"    In Progress: {operation.DocumentsInProgress}");
    Console.WriteLine($"    Not started: {operation.DocumentsNotStarted}");

    await foreach(DocumentStatusResult document in operation.Value) {
      Console.WriteLine($"Document with Id: {document.Id}");
      Console.WriteLine($"  Status:{document.Status}");
      if (document.Status == DocumentTranslationStatus.Succeeded) {
        Console.WriteLine($"  Translated Document Uri: {document.TranslatedDocumentUri}");
        Console.WriteLine($"  Translated to language: {document.TranslatedToLanguageCode}.");
        Console.WriteLine($"  Document source Uri: {document.SourceDocumentUri}");
      } else {
        Console.WriteLine($"  Error Code: {document.Error.Code}");
        Console.WriteLine($"  Message: {document.Error.Message}");
      }
    }
  }
}

Uw toepassing uitvoeren

Nadat u het codevoorbeeld aan uw toepassing hebt toegevoegd, voert u uw toepassing uit vanuit de projectmap door de volgende opdracht in uw terminal te typen:

  dotnet run

Hier volgt een fragment van de verwachte uitvoer:

Visual Studio

Uw C#/.NET-omgeving instellen

Voor deze quickstart gebruiken we de nieuwste versie van Visual Studio IDE om de toepassing te bouwen en uit te voeren.

1. Start Visual Studio.

2. Kies Een nieuw project maken op de pagina Aan de slag .

   

3. Voer op de pagina Een nieuw project maken de console in het zoekvak in. Kies de consoletoepassingssjabloon en kies vervolgens Volgende.

   

4. Voer asynchronous-sdk in het dialoogvenster Uw nieuwe project configureren het vak Projectnaam in. Kies vervolgens Volgende.

   

5. Selecteer in het dialoogvenster Aanvullende informatie .NET 6.0 (langetermijnondersteuning) en selecteer vervolgens Maken.

   

De clientbibliotheek installeren met NuGet

1. Klik met de rechtermuisknop op uw Vertalen-text-sdk-project en selecteer NuGet-pakketten beheren...

2. Selecteer het tabblad Bladeren en typ Azure.AI.Translation.Document.

   

3. Selecteer en installeer het pakket in uw project.

   

Uw C#-toepassing bouwen

Notitie

• Vanaf .NET 6 genereren nieuwe projecten met behulp van de console sjabloon een nieuwe programmastijl die verschilt van eerdere versies.
• De nieuwe uitvoer maakt gebruik van recente C#-functies die de code vereenvoudigen die u moet schrijven.
• Wanneer u de nieuwere versie gebruikt, hoeft u alleen de hoofdtekst van de Main methode te schrijven. U hoeft geen instructies op het hoogste niveau, globaal gebruik van instructies of impliciet gebruik van instructies op te nemen.
• ZieNieuwe C#-sjablonen voor meer informatie over het genereren van instructies op het hoogste niveau.

1. Open het Program.cs-bestand .

2. Verwijder de bestaande code, inclusief de regel Console.WriteLine("Hello World!").

3. Maak in de Program.cs van de toepassing variabelen voor uw sleutel en aangepast eindpunt. ZieUw sleutel en aangepast domeineindpunt ophalen voor meer informatie.

private static readonly string endpoint = "<your-document-translation-endpoint>";
private static readonly string key = "<your-key>";

1. Als u een vertaalbewerking voor een of meer documenten in één blobcontainer wilt starten, roept u de StartTranslationAsync methode aan.

2. Als u een aanroep wilt aanroepen StartTranslationAsync, moet u een DocumentTranslationInput object initialiseren dat de sourceUri en targetUri parameters bevat:

   • Maak voor autorisatie van beheerde identiteit de volgende variabelen:

     • sourceUri. De URL voor de broncontainer met documenten die moeten worden vertaald.

     • targetUri De URL voor de doelcontainer waarnaar de vertaalde documenten worden geschreven.

     • targetLanguageCode. De taalcode voor de vertaalde documenten. U vindt taalcodes op onze ondersteuningspagina voor talen.

       Als u uw bron- en doel-URL's wilt vinden, gaat u naar uw opslagaccount in Azure Portal. Selecteer in de linkerzijbalk onder Gegevensopslag de optie Containers en volg deze stappen om uw brondocumenten en doelcontainer URLSop te halen.

       Source	Target
       1. Schakel het selectievakje naast de broncontainer in	1. Schakel het selectievakje naast de doelcontainer in.
       2. Selecteer in het hoofdvenstergebied een bestand of documenten voor vertaling.	2. Selecteer het beletselteken aan de rechterkant en kies Eigenschappen.
       3. De bron-URL bevindt zich boven aan de lijst Eigenschappen.	3. De doel-URL bevindt zich boven aan de lijst Eigenschappen.

   • Voor SAS-autorisatie (Shared Access Signature) maakt u deze variabelen

     • sourceUri. De SAS-URI, waaraan een SAS-token is toegevoegd als een querytekenreeks, zodat de broncontainer met documenten moet worden vertaald.
     • targetUri De SAS-URI, met een SAS-token toegevoegd als een querytekenreeks, voor de doelcontainer waarnaar de vertaalde documenten worden geschreven.
     • targetLanguageCode. De taalcode voor de vertaalde documenten. U vindt taalcodes op onze ondersteuningspagina voor talen.

Voorbeeld van code

Belangrijk

Vergeet niet de sleutel uit uw code te verwijderen wanneer u klaar bent, en maak deze sleutel nooit openbaar. Gebruik voor productie een veilige manier om uw referenties op te slaan en te openen, zoals Azure Key Vault. Zie Beveiliging van Azure AI-services voor meer informatie.

Voer het volgende codevoorbeeld in het Program.cs-bestand van uw toepassing in:

using Azure;
using Azure.AI.Translation.Document;

class Program {

  // create variables for your custom endpoint and resource key
  private static readonly string endpoint = "<your-document-translation-endpoint>";
  private static readonly string key = "<your-key>";

  static async Task Main(string[] args) {

    // create variables for your sourceUrl, targetUrl, and targetLanguageCode
    Uri sourceUri = new Uri("<sourceUrl>");
    Uri targetUri = new Uri("<targetUrl>");
    string targetLanguage = "<targetLanguageCode>";

    // initialize a new instance  of the DocumentTranslationClient object to interact with the Document Translation feature
    DocumentTranslationClient client = new DocumentTranslationClient(new Uri(endpoint), new AzureKeyCredential(key));

    // initialize a new instance of the `DocumentTranslationInput` object to provide source and target locations and target language for the translation operation
    DocumentTranslationInput input = new DocumentTranslationInput(sourceUri, targetUri, targetLanguage);

    // initialize a new instance of the DocumentTranslationOperation class to track the status of the translation operation
    DocumentTranslationOperation operation = await client.StartTranslationAsync(input);

    await operation.WaitForCompletionAsync();

    Console.WriteLine($"  Status: {operation.Status}");
    Console.WriteLine($"  Created on: {operation.CreatedOn}");
    Console.WriteLine($"  Last modified: {operation.LastModified}");
    Console.WriteLine($"  Total documents: {operation.DocumentsTotal}");
    Console.WriteLine($"    Succeeded: {operation.DocumentsSucceeded}");
    Console.WriteLine($"    Failed: {operation.DocumentsFailed}");
    Console.WriteLine($"    In Progress: {operation.DocumentsInProgress}");
    Console.WriteLine($"    Not started: {operation.DocumentsNotStarted}");

    await foreach(DocumentStatusResult document in operation.Value) {
      Console.WriteLine($"Document with Id: {document.Id}");
      Console.WriteLine($"  Status:{document.Status}");
      if (document.Status == DocumentTranslationStatus.Succeeded) {
        Console.WriteLine($"  Translated Document Uri: {document.TranslatedDocumentUri}");
        Console.WriteLine($"  Translated to language: {document.TranslatedToLanguageCode}.");
        Console.WriteLine($"  Document source Uri: {document.SourceDocumentUri}");
      } else {
        Console.WriteLine($"  Error Code: {document.Error.Code}");
        Console.WriteLine($"  Message: {document.Error.Message}");
      }
    }
  }
}

Uw toepassing uitvoeren

Zodra u het codevoorbeeld aan uw toepassing hebt toegevoegd, kiest u de groene startknop naast formRecognizer_quickstart om uw programma te bouwen en uit te voeren, of drukt u op F5.

Hier volgt een fragment van de verwachte uitvoer:

Dat is het! U hebt zojuist een programma gemaakt om documenten in een opslagcontainer te vertalen met behulp van de .NET-clientbibliotheek.

Uw project instellen

Zorg ervoor dat de nieuwste versie van Python is geïnstalleerd.

De clientbibliotheek installeren

Installeer de nieuwste versie van de clientbibliotheek voor documentomzetting:

pip install azure-ai-translation-document==1.0.0

Een document of batchbestanden vertalen

1. Voor dit project hebt u een brondocument nodig dat is geüpload naar uw broncontainer. U kunt ons voorbeelddocument voor documentomzetting downloaden voor deze quickstart. De brontaal is Engels.

2. Maak in uw Python-toepassingsbestand variabelen voor uw resourcesleutel en aangepast eindpunt. ZieUw sleutel en aangepast domeineindpunt ophalen voor meer informatie.

key = "<your-key>"
endpoint = "<your-custom-endpoint>"

1. Initialiseer een DocumentTranslationClient object dat uw endpoint en key parameters bevat.

2. Roep de begin_translation methode aan en geef de sourceUriparameters targetUritargetLanguageCode door.

   • Maak voor autorisatie van beheerde identiteit de volgende variabelen:

     • sourceUri. De URL voor de broncontainer met documenten die moeten worden vertaald.

     • targetUri De URL voor de doelcontainer waarnaar de vertaalde documenten worden geschreven.

     • targetLanguageCode. De taalcode voor de vertaalde documenten. U vindt taalcodes op onze ondersteuningspagina voor talen.

       Als u uw bron- en doel-URL's wilt vinden, gaat u naar uw opslagaccount in Azure Portal. Selecteer in de linkerzijbalk onder Gegevensopslag de optie Containers en volg deze stappen om uw brondocumenten en doelcontainer URLSop te halen.

       Source	Target
       1. Schakel het selectievakje naast de broncontainer in	1. Schakel het selectievakje naast de doelcontainer in.
       2. Selecteer in het hoofdvenstergebied een bestand of documenten voor vertaling.	2. Selecteer het beletselteken aan de rechterkant en kies Eigenschappen.
       3. De bron-URL bevindt zich boven aan de lijst Eigenschappen.	3. De doel-URL bevindt zich boven aan de lijst Eigenschappen.

   • Voor SAS-autorisatie (Shared Access Signature) maakt u deze variabelen

     • sourceUri. De SAS-URI, waaraan een SAS-token is toegevoegd als een querytekenreeks, zodat de broncontainer met documenten moet worden vertaald.
     • targetUri De SAS-URI, met een SAS-token toegevoegd als een querytekenreeks, voor de doelcontainer waarnaar de vertaalde documenten worden geschreven.
     • targetLanguageCode. De taalcode voor de vertaalde documenten. U vindt taalcodes op onze ondersteuningspagina voor talen.

Codevoorbeeld

Belangrijk

Vergeet niet de sleutel uit uw code te verwijderen wanneer u klaar bent, en maak deze sleutel nooit openbaar. Gebruik voor productie een veilige manier om uw referenties op te slaan en te openen, zoals Azure Key Vault. Zie Beveiliging van Azure AI-services voor meer informatie.

Voer het volgende codevoorbeeld in uw Python-toepassing in:

#  import libraries
from azure.core.credentials import AzureKeyCredential
from azure.ai.translation.document import DocumentTranslationClient

# create variables for your resource key, custom endpoint, sourceUrl, targetUrl, and targetLanguage
key = "<your-key>"
endpoint = "<your-custom-endpoint>"
sourceUri = "<your-container-sourceUrl>"
targetUri = "<your-container-targetUrl>"
targetLanguage = "<target-language-code>"


# initialize a new instance of the DocumentTranslationClient object to interact with the Document Translation feature
client = DocumentTranslationClient(endpoint, AzureKeyCredential(key))

# include source and target locations and target language code for the begin translation operation
poller = client.begin_translation(sourceUri, targetUri, targetLanguage)
result = poller.result()

print("Status: {}".format(poller.status()))
print("Created on: {}".format(poller.details.created_on))
print("Last updated on: {}".format(poller.details.last_updated_on))
print(
    "Total number of translations on documents: {}".format(
        poller.details.documents_total_count
    )
)

print("\nOf total documents...")
print("{} failed".format(poller.details.documents_failed_count))
print("{} succeeded".format(poller.details.documents_succeeded_count))

for document in result:
    print("Document ID: {}".format(document.id))
    print("Document status: {}".format(document.status))
    if document.status == "Succeeded":
        print("Source document location: {}".format(document.source_document_url))
        print(
            "Translated document location: {}".format(document.translated_document_url)
        )
        print("Translated to language: {}\n".format(document.translated_to))
    else:
        print(
            "Error Code: {}, Message: {}\n".format(
                document.error.code, document.error.message
            )
        )

Uw toepassing uitvoeren

Nadat u het codevoorbeeld aan uw toepassing hebt toegevoegd, typt u de volgende opdracht in uw terminal:

python asynchronous-sdk.py

Hier volgt een fragment van de verwachte uitvoer:

Dat is het! U hebt zojuist een programma gemaakt om documenten in een opslagcontainer te vertalen met behulp van de Python-clientbibliotheek.

Volgende stap

Meer informatie over documentomzettingsbewerkingen