Erste Schritte: REST-APIs zur Dokumentenübersetzung von Translator

Die Dokumentübersetzung ist ein cloudbasiertes Feature des Azure Translator in Foundry Tools-Diensts , das asynchron ganze Dokumente in unterstützten Sprachen und verschiedenen Dateiformaten übersetzt. In dieser Schnellstartanleitung erfahren Sie, wie Sie die Dokumentübersetzung mit einer Programmiersprache Ihrer Wahl verwenden können, um ein Quelldokument in eine Zielsprache zu übersetzen und dabei Struktur und Textformatierung beizubehalten.

Die Dokumentübersetzung-API unterstützt zwei Übersetzungsprozesse:

• Die asynchrone Batchübersetzung unterstützt die Verarbeitung mehrerer Dokumente und großer Dateien. Für den Batchübersetzungsprozess ist ein Azure Blob-Speicherkonto mit Speichercontainern für Ihre Quell- und übersetzten Dokumente erforderlich.

• Die synchrone Einzeldateiübersetzung unterstützt die Verarbeitung einzelner Dateiübersetzungen. Für den Dateiübersetzungsprozess ist kein Azure Blob Storage-Konto erforderlich. Die endgültige Antwort enthält das übersetzte Dokument und wird direkt an den aufrufenden Client zurückgegeben.

Fangen wir an.

Voraussetzungen

Sie benötigen ein aktives Azure-Abonnement. Falls Sie über kein Azure-Abonnement verfügen, können Sie ein kostenloses Konto erstellen.

• Nachdem Sie Ihr Azure-Abonnement haben, erstellen Sie eine Azure Translator-Ressource im Azure-Portal.

  Hinweis

  • Für diesen Schnellstart wird empfohlen, eine globale Azure Übersetzer-Textressource mit einem Dienst zu verwenden, es sei denn, Ihr Unternehmen oder Ihre Anwendung erfordert eine bestimmte Region. Wenn Sie planen, eine systemseitig zugewiesene verwaltete Identität für die Authentifizierung zu verwenden, wählen Sie eine geografische Region aus, z. B. USA, Westen.
  • Mit einer globalen Einzeldienst-Ressource schließen Sie einen Autorisierungsheader (Ocp-Apim-Subscription-Key) in die REST-API-Anforderung ein. Der Wert Ocp-Apim-Subscription-key ist Ihr geheimer Azure-Schlüssel für Ihr Azure Translator Text-Abonnement.

• Wählen Sie nach erfolgter Bereitstellung Ihrer Ressource Zu Ressource wechseln aus, und rufen Sie Ihren Schlüssel und Endpunkt ab.

  • Sie benötigen den Schlüssel und endpunkt aus der Ressource, um Ihre Anwendung mit dem Azure Translator zu verbinden. Den Schlüssel und den Endpunkt werden Sie später im Schnellstart in den Code einfügen. Diese Werte sind im Azure-Portal auf der Seite Schlüssel und Endpunkt aufgeführt.

    

• Für dieses Projekt verwenden wir das Befehlszeilentool cURL, um REST-API-Aufrufe auszuführen.

  Hinweis

  Das cURL-Paket ist in den meisten Windows 10- und Windows 11-Versionen sowie den meisten macOS- und Linux-Distributionen vorinstalliert. Sie können die Paketversion mithilfe der folgenden Befehle überprüfen: Windows: curl.exe -V, macOS: curl -V, Linux: curl --version

Asynchrones Übersetzen von Dokumenten (POST)

1. Erstellen Sie mit Ihrem bevorzugten Editor oder Ihrer bevorzugten IDE ein neues Verzeichnis namens document-translation für Ihre App.

2. Erstellen Sie eine neue JSON-Datei namens document-translation.json in Ihrem Verzeichnis document-translation.

3. Kopieren Sie das Anforderungsbeispiel für die Dokumentübersetzung, und fügen Sie es in Ihre Datei document-translation.json ein. Ersetzen Sie {your-source-container-SAS-URL} und {your-target-container-SAS-URL} durch die Werte Ihrer Speicherkontocontainer-Instanz aus dem Azure-Portal.

   Anforderungsbeispiel:

   {
     "inputs":[
       {
         "source":{
           "sourceUrl":"{your-source-container-SAS-URL}"
         },
         "targets":[
           {
             "targetUrl":"{your-target-container-SAS-URL}",
             "language":"fr"
           }
         ]
       }
     ]
   }
   

Speichercontainerautorisierung

Sie können eine der folgenden Optionen auswählen, um den Zugriff auf Ihre Azure Translator-Ressource zu autorisieren.

✔️ Verwaltete Identität. Eine verwaltete Identität ist ein Dienstprinzipal, der eine Microsoft Entra-Identität und bestimmte Berechtigungen für von Azure verwaltete Ressourcen erstellt. Mit verwalteten Identitäten können Sie Ihre Azure Translator-Anwendung ausführen, ohne Anmeldeinformationen in Ihren Code einbetten zu müssen. Verwaltete Identitäten sind eine sicherere Möglichkeit, Zugriff auf Speicherdaten zu gewähren und die Anforderung zu ersetzen, dass Sie freigegebene Zugriffssignaturtoken (SAS) mit Ihren Quell- und Ziel-URLs einschließen.

Weitere Informationen finden Sie unterVerwaltete Identitäten für die Dokumentübersetzung.

✔️ Shared Access Signature (SAS). Eine Signatur für freigegebenen Zugriff ist eine URL, die eingeschränkten Zugriff für einen bestimmten Zeitraum für Ihren Übersetzer gewährt. Um diese Methode zu verwenden, müssen Sie SAS-Token (Shared Access Signature) für Ihre Quell- und Zielcontainer erstellen. Die sourceUrl und targetUrl müssen ein Shared Access Signature (SAS)-Token enthalten, das als Abfragezeichenfolge angefügt wird. Das Token kann Ihrem Container oder bestimmten Blobs zugewiesen werden.

• Ihr Quellcontainer oder Blob muss über Zugriff vom Typ Lesen und Auflisten verfügen.
• Ihr Zielcontainer oder Blob muss über Zugriff vom Typ Schreiben und Auflisten verfügen.

Weitere Informationen finden Sie unterErstellen von SAS-Token.

Erstellen und Ausführen der POST-Anforderung

Ersetzen Sie vor dem Ausführen der POST-Anforderung{your-document-translator-endpoint} und {your-key} durch die Werte aus Ihrer Azure-Portal-Azure-Translator-Instanz.

PowerShell

cmd /c curl "{document-translation-endpoint}/translator/document/batches?api-version={date}" -i -X POST --header "Content-Type: application/json" --header "Ocp-Apim-Subscription-Key: {your-key}" --data "@document-translation.json"

Eingabeaufforderung /Terminal

curl "{document-translation-endpoint}/translator/document/batches?api-version={date}" -i -X POST --header "Content-Type: application/json" --header "Ocp-Apim-Subscription-Key: {your-key}" --data "@document-translation.json"

Nach erfolgreichem Abschluss:

• Die übersetzten Dokumente befinden sich in Ihrem Zielcontainer.
• Bei erfolgreicher Ausführung gibt die POST-Methode den Antwortcode 202 Accepted zurück, der anzeigt, dass die Batch-Anforderung vom Dienst erstellt wurde.
• Die POST-Anfrage gibt außerdem Antwortheader zurück, unter anderem Operation-Location. Dieser Header stellt einen Wert bereit, der in nachfolgenden GET-Anforderungen verwendet wird.

Synchrones Übersetzen eines einzelnen Dokuments (POST)

Zum Aufrufen des Features für synchrone Übersetzung über die REST-API müssen Sie in jede Anforderung die folgenden Header einschließen. Das braucht Sie nicht zu beunruhigen, wir fügen für Sie die Header in den Beispielcode ein.

✔️ Weitere Informationen zu contentTypefinden Sie unterUnterstützte Dokumentformate.

Erstellen und Ausführen der synchronen POST-Anforderung

1. Für dieses Projekt benötigen Sie ein Beispieldokument. Sie können unser Microsoft Word-Beispieldokument für diesen Schnellstart herunterladen. Die Quellsprache ist Englisch.

2. Ersetzen Sie vor dem Ausführen der POST-Anforderung{your-document-translation-endpoint} und {your-key} durch die Werte aus Ihrer Azure-Portal-Azure-Translator-Instanz.

   Wichtig

   Denken Sie daran, den Schlüssel aus Ihrem Code zu entfernen, wenn Sie fertig sind, und ihn niemals zu veröffentlichen. Verwenden Sie für die Produktion eine sichere Art der Speicherung und des Zugriffs auf Ihre Anmeldeinformationen wie Azure Key Vault. Weitere Informationen finden Sie unterFoundry Tools Security.

   Eingabeaufforderung /Terminal

   
   curl -i -X POST "{document-translation-endpoint}/translator/document:translate?targetLanguage={target_language}&api-version={date}" -H "Ocp-Apim-Subscription-Key:{your-key}"  -F "document={path-to-your-document-with-file-extension};type={ContentType}/{file-extension}" -F "glossary={path-to-your-glossary-with-file-extension};type={ContentType}/{file-extension}" -o "{path-to-output-file}"
   

   PowerShell

   cmd /c curl "{document-translation-endpoint}/translator/document:translate?targetLanguage={target_language}&api-version={date}" -i -X POST  -H "Ocp-Apim-Subscription-Key: {your-key}" -F "{path-to-your-document-with-file-extension};type=text/{file-extension}" -o "{path-to-output-file}
   
   

   ✔️ Weitere Informationen zu Query parametersfinden Sie untersynchrone Dokumentübersetzung.

Nach erfolgreichem Abschluss:

• Das übersetzte Dokument wird mit der Antwort zurückgegeben.
• Bei erfolgreicher Ausführung gibt die POST-Methode den Antwortcode 200 OK zurück, der anzeigt, dass der Dienst die Anforderung erstellt hat.

Das war's, herzlichen Glückwunsch! Sie haben gerade gelernt, Dokumente mithilfe von Azure Translator zu übersetzen.

Nächste Schritte