تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

أنشئ نصًا لاجتماعات العمل باستخدام "مستندات Google" التعلم الآلي

1. نظرة عامة

في هذا الدرس التطبيقي حول الترميز، ستتعرّف على كيفية إرسال ملف صوتي من خلال Google Cloud Speech to Text API، ثم إخراج النص إلى مستند Google. إنّ واجهة برمجة التطبيقات Speech to Text API سهلة الاستخدام، ويتم فيها استخدام شبكات عصبية فعالة تتيح للمطوّرين تحويل الصوت إلى نص. بالإضافة إلى ذلك، إنه مدعوم من خلال التعلم الآلي.

ستستخدم Google Docs API لإنشاء مستند جديد والكتابة إليه. ستقوم بإنشاء تطبيق سطر أوامر Java وتشغيل التعليمة البرمجية باستخدام نظام إنشاء gradle ثم استخدام واجهة برمجة تطبيقات محرر المستندات لعرض النتائج.

ما ستتعرَّف عليه

كيفية استخدام واجهة برمجة التطبيقات Google Cloud Speech to Text API
كيفية استخدام Google Docs API لإنشاء مستند جديد
كيفية استخدام واجهة برمجة التطبيقات Docs API للكتابة في مستند

المتطلبات

تثبيت Java (الإصدار 7 أو أعلى)
تم تثبيت Gradle (الإصدار 5 أو أعلى)
الوصول إلى الإنترنت ومتصفّح الويب
حساب Google
مشروع Google Cloud Platform

2. إعداد مشروعك

إنشاء مشروعك على السحابة الإلكترونية

سجِّل الدخول إلى Cloud Console وأنشِئ مشروعًا جديدًا أو أعِد استخدام مشروع حالي. (إذا لم يكن لديك حساب على Gmail أو Workspace، عليك إنشاء حساب.)

dMbN6g9RawQj_VXCSYpdYncY-DbaRzr2GbnwoV7jFf1u3avxJtmGPmKpMYgiaMH-qu80a_NJ9p2IIXFppYk8x3wyymZXavjglNLJJhuXieCem56H30hwXtd8PvXGpXJO9gEUDu3cZw

ci9Oe6PgnbNuSYlMyvbXF1JdQyiHoEgnhl4PlV_MFagm2ppzhueRkqX4eLjJllZco_2zCp0V0bpTupUSKji9KkQyWqj11pqit1K1faS1V6aFxLGQdkuzGp4rsQTan7F01iePL5DtqQ

8-tA_Lheyo8SscAVKrGii2coplQp2_D1Iosb2ViABY0UUO1A8cimXUu6Wf1R9zJIRExL5OB2j946aIiFtyKTzxDcNnuznmR45vZ2HMoK3o67jxuoUJCAnqvEX6NgPGFjCVNgASc-lg

يُرجى تذكُّر رقم تعريف المشروع، وهو اسم فريد في جميع مشاريع Google Cloud (سبق أن تم استخدام الاسم أعلاه ولن يكون مناسبًا لك). ستتم الإشارة إليها لاحقًا في هذا الدرس التطبيقي حول الترميز باسم PROJECT_ID.

بعد ذلك، عليك تفعيل الفوترة في Cloud Console لاستخدام موارد Google Cloud.

إنّ تنفيذ هذا الدرس التطبيقي حول الترميز لن يكون مكلفًا أو مكلفًا على الإطلاق. احرص على اتّباع أي تعليمات في قسم "الحذف سريعًا". الذي يقدم لك نصائح حول كيفية إيقاف تشغيل الموارد حتى لا تتكبّد أي فواتير خارج نطاق هذا البرنامج التعليمي. يكون مستخدمو Google Cloud الجدد مؤهَّلون للانضمام إلى برنامج الفترة التجريبية المجانية التي تبلغ قيمتها 300 دولار أمريكي.

الحصول على مفتاح حساب خدمة لواجهة Cloud Speech-to-Text API

انتقِل إلى وحدة تحكُّم Google Cloud Platform وابحث عن مشروعك الجديد.
إنشاء حساب خدمة
تنزيل مفتاح حساب الخدمة بتنسيق JSON
اضبط متغيّر البيئة GOOGLE_APPLICATION_CREDENTIALS على مسار ملف ملف JSON الذي يحتوي على مفتاح حساب الخدمة. إذا أعدت تشغيل جلسة Shell، ستحتاج إلى ضبط المتغيّر مرة أخرى.

$ export GOOGLE_APPLICATION_CREDENTIALS="[PATH]"

على سبيل المثال:

$ export GOOGLE_APPLICATION_CREDENTIALS="/home/usr/downloads/ServiceAccount.json"

الحصول على بيانات الاعتماد لواجهة Docs API

ارجِع إلى وحدة تحكُّم Google Cloud Platform، وانتقِل إلى بيانات الاعتماد.
أنشِئ مفتاح OAuth 2.0 ونزِّله كملف JSON.
أعِد تسمية الملف credentials.json وتأكَّد من أنّه في دليل src/main/resources/ ضمن الرمز البرمجي.

تفعيل واجهات برمجة التطبيقات

اختَر علامة التبويب لوحة البيانات، وانقر على الزر تفعيل واجهات برمجة التطبيقات والخدمات وفعِّل واجهتَي برمجة التطبيقات التاليتَين:
تحويل الكلام إلى نص
مستندات Google

أنت الآن جاهز للمضي قدمًا وبدء العمل على التعليمة البرمجية.

3- إعداد الرمز

الحصول على الرمز النموذجي

للحصول على الرمز النموذجي، يمكنك إما تنزيل الملف المضغوط على جهاز الكمبيوتر...

...أو استنساخ مستودع جيت هب من سطر الأوامر.

$ git clone git@github.com:googleworkspace/docs-transcript-codelab.git

العمل في ملف CreateTranscript.java داخل دليل start يجب عدم تعديل ملفات Gradle.

في الدليل، انتقِل إلى المجلد start وافتح ملف CreateTranscript.java. انتقِل للأسفل وصولاً إلى بيان الفئة CreateTranscript.

public class CreateTranscript {
  private static final String CREDENTIALS_FILE_PATH = "/credentials.json";
  
  // Specify audio file name below.
  private static final String AUDIO_FILENAME = "audioFile.wav";
  private static final String TOKENS_DIRECTORY_PATH = "tokens";
  private static final JsonFactory JSON_FACTORY = JacksonFactory.getDefaultInstance();
  private static final String APPLICATION_NAME = "CreateTranscript";
  private static final List<String> SCOPES = Collections.singletonList(DocsScopes.DOCUMENTS);

بالنسبة إلى متغيّر SCOPES، لقد حددت أنّ الرمز سيتمكّن من عرض مستندات المستخدم في "مستندات Google" وإدارتها. إذا كان الرمز يتطلب تفويضًا خارج نطاق هذا الوصول أو مختلفًا عنه، تأكَّد من ضبط هذا المتغيّر وفقًا لذلك استنادًا إلى نطاقات OAuth 2.0 Google API.

على سبيل المثال، إذا لم تكن تكتب في "مستند Google"، يمكنك تغيير النطاق إلى DOCUMENTS_READONLY. من الضروري استخدام المتغيّر SCOPES ليس فقط لكي يحصل تطبيقك على أذونات الوصول المناسبة، ولكن أيضًا للحفاظ على الشفافية مع المستخدمين. يتم عرض النطاقات المحدَّدة التي تطلبها للمستخدم في صفحة التحقُّق من بروتوكول OAuth حيث يجب أن يوافق على استخدام التطبيق.

إعادة تسمية المتغيّرات

تأكد من الإعلان عن المتغيرات المذكورة أعلاه بشكل صحيح لمشروعك.

تأكَّد من ضبط AUDIO_FILENAME على اسم ملف العرض التوضيحي الذي ترسله إلى واجهة برمجة تطبيقات Speech to Text API. في ملف CreateTranscript.java، من المفترض أن يكون قد تم ضبطه بشكل صحيح.
أعِد تسمية CREDENTIALS_FILE_PATH باسم ملف بيانات الاعتماد الذي تم تنزيله (يجب أن يكون "/credentials.json'"). تأكَّد من أنّ هذا الملف داخل دليل src/main/resources في المجلد، لذا احرص على إنشاء هذا الدليل إذا لم يؤدِّ استنساخ GitHub إلى تنفيذ ذلك.

الآن، يمكنك البدء في تشغيل التعليمات البرمجية الخاصة بك!

4. إعداد برنامج مستندات

في ملف CreateTranscript.java، ابحث عن تعريف الطريقة الرئيسية وألقِ نظرة على ما بداخله:

final NetHttpTransport HTTP_TRANSPORT = GoogleNetHttpTransport.newTrustedTransport();
Docs service = new Docs.Builder(HTTP_TRANSPORT, JSON_FACTORY,
    getCredentials(HTTP_TRANSPORT))
          .setApplicationName(APPLICATION_NAME)
          .build();

تفويض الدالة

المهمة الأولى التي تؤديها هنا هي إنشاء Docs service (المتغيّر). تمثل الخدمة عميل واجهة برمجة تطبيقات معتمد، ويحتفظ ببيانات اعتمادك، وفي هذه الحالة، مصادقة المستخدم.

في الرمز البرمجي الخاص بك، أي دالة تُجري اتصالاً بواجهة برمجة التطبيقات لتطبيق "مستندات Google" ستحتاج إلى استخدام متغيّر service هذا لتنفيذ المهام المتعلّقة بالمستندات.

5- إنشاء مستند Google

ستنشئ "مستند Google" جديدًا بعنوان محدد. إذًا، لننسخ الرمز أدناه في الدالة createDocument.

Document doc = new Document().setTitle("Transcript for " +
    AUDIO_FILENAME);
doc = service.documents().create(doc).execute();
String documentId = doc.getDocumentId();
return documentId;

تعرض هذه الدالة معرّف ملف Drive لمستند Google. هذا المعرّف نفسه يمكن العثور عليه ضمن عنوان URL للمستند.

بعد ذلك، ستقوم بتهيئة برنامج "تحويل الكلام إلى نص".

6- واجهة برمجة تطبيقات Speech to Text API

المهمة التالية التي تريد تنفيذها في التعليمة البرمجية هي الحصول على النص المكتوب للملف الصوتي. في داخل CreateTranscript.java، ابحث عن الدالة getTranscript().

أولاً، عليك الحصول على مسار الملف الصوتي ووحدات البايت الصوتية:

SpeechClient speech = SpeechClient.create();
Path path = Paths.get(AUDIO_FILENAME);
byte[] data = Files.readAllBytes(path);
ByteString audioBytes = ByteString.copyFrom(data);

إعداد ميزة "التعرّف على الكلام"

بعد ذلك، عليك إعداد المتغيّر RecognitionConfig بشكل صحيح.

هنا، تقدّم config معلومات حول الطريقة التي يجب أن تعالج بها أداة التعرّف على الكلام طلبك. ستحتاج إلى تعديل setLanguageCode() إذا كان ملفك الصوتي مثلاً بلغة غير الإنجليزية، وتغيير setSampleRateHertz() إذا كان معدّل البيانات في الملف الصوتي مختلفًا بترميز Hertz (يكون 1600 هو الأمثل).

RecognitionConfig config =
    RecognitionConfig.newBuilder()
        .setEncoding(AudioEncoding.LINEAR16)
        .setLanguageCode("en-US")
        .setSampleRateHertz(8000)
        .build();
RecognitionAudio audio =
    RecognitionAudio.newBuilder().setContent(audioBytes).build();
RecognizeResponse response = speech.recognize(config, audio);
List<SpeechRecognitionResult> results = response.getResultsList();

تحضير النص

وأخيرًا، يمكنك التعامل مع متغيّر نص الملف الصوتي result وإعداده لإدراجه في مستند.

كل عنصر في النتائج هو نص من النوع SpeechRecognitionAlternatives. وبالتالي، يحتوي كل عنصر على جزأين: نص نصي ودرجة الثقة المقابلة لواجهة برمجة التطبيقات.

List<Request> requests = new ArrayList<>();
for (SpeechRecognitionResult result : results) {
     // Using the first + most likely alternative transcript
     SpeechRecognitionAlternative alternative =
         result.getAlternativesList().get(0);
     String toInsert = alternative.getTranscript();

     // Add requests array list to return.
     requests.add(
         new Request()
             .setInsertText(
                 new InsertTextRequest()
                     .setText(toInsert)
                     .setEndOfSegmentLocation(new
     EndOfSegmentLocation().setSegmentId(""))));
}
return requests;

7. إدراج نص في مستند

يمكنك الآن إدراج نص النص في مستند Google. لإجراء أي تعديلات على مستند، عليك استخدام الطريقة BatchUpdate. BatchUpdate هي حاوية لأنواع مختلفة من طلبات الكتابة، وستستخدم هنا InsertTextRequest.

EndOfSegmentLocation هي مَعلمة مهمة تحدّد المكان الذي تريد طباعة النص فيه في مستندك. في رمز المصدر، ستُدرج نصًا في النص الأساسي للمستند.

هيا نعرض الرمز أدناه في الدالة لنرى كيف يمكن لنتائج واجهة برمجة التطبيقات Speech-to-Text إلى جانب الطلبات على Docs API أن تسمح لنا بإدراج نص ملف صوتي في مستند Google:

BatchUpdateDocumentRequest body = new BatchUpdateDocumentRequest();
service.documents().batchUpdate(docId,
    body.setRequests(insertRequests)).execute();

إنشاء الطلب

عند تقديم طلب "BatchUpdate"، يجب ضبط خاصيتَين مهمتَين جدًا، وهما: ما تريد طباعته (.setText()) والمكان الذي تريد إجراء ذلك فيه في المستند (.setIndex(1)).

لقد أدرجت الآن نص الملف الصوتي في المستند الذي أنشأته.

8. تشغيل الرمز البرمجي

والآن بعد أن أصبح لديك كل الرموز البرمجية التي تحتاجها لالتقاط ملف صوتي والحصول على نصه وطباعة نصه في مستند Google تم إنشاؤه حديثًا، لنبدأ هذا العرض.

بما أنّك ستُشغِّل رمز JavaScript باستخدام نظام إنشاء Gradle، عليك إخبار ملف build.gradle بما يجب إنشاؤه وتشغيله بالضبط. في هذا المشروع وغيره من المشاريع، تأكّد من الحفاظ على اتساق mainClassName مع فئة جافا التي تريد تشغيلها.

رائع! أنت الآن جاهز لتشغيل التعليمة البرمجية. ولإجراء ذلك، اكتب ما يلي في سطر الأوامر:

$ gradle run

مصادقة المستخدم

عند تشغيل هذا الرمز لأول مرة، سترى عنوان URL مطبوعًا في الوحدة الطرفية يطلب منك تسجيل الدخول إلى حساب الخدمة وتفويض الوصول إلى "مستندات Google". بعد السماح بالوصول، ستلاحظ ملفًا جديدًا تم تخزينه في الدليل.

داخل دليل العمل، سيظهر لك مجلد تم إنشاؤه حديثًا بعنوان الرموز المميّزة ويحتوي على ملف باسم StoredCredential. هذا هو الرمز المميّز للمصادقة الذي قدّمته للتو، والذي طلبه العميل من خادم مصادقة Google، واستخرجه من ردّه، وسيرسله الآن إلى أي واجهة برمجة تطبيقات تطلبها.

الحل

إذا لم يعمل الرمز، ألق نظرة على ملف CreateTranscript.java في المجلد CreateTranscript.java. يحتوي هذا الملف على كل التعليمات البرمجية الخاصة بك بالضبط كما ينبغي أن تكون لكي يعمل بنجاح.

الآن لنلقِ نظرة على النتيجة.

9. عرض النتائج

لقد أنشأت للتو مستندًا جديدًا من مستندات Google يحتوي على نص الملف الصوتي، لذا هيا نلقي نظرة عليه.

تم إنشاء هذا المستند من خلال الحساب الذي قدّم المستخدم النهائي من خلاله الإذن. يتمثل أحد التوسعات المحتملة في أنه يمكنك مشاركة هذا المستند تلقائيًا مع الآخرين باستخدام Drive API.

باستخدام رمز المصدر والملف الصوتي المقدَّم، إليك ما يُفترض أن يظهر لك:

10. تهانينا!

لقد تعرفت الآن على كيفية إنشاء مستند Google وإجراء مكالمة مع واجهة برمجة تطبيقات Speech-to-Text API وإخراج نص الملف الصوتي إلى مستندك الذي تم إنشاؤه.

التحسينات المحتملة

في ما يلي بعض الأفكار حول كيفية إجراء عملية دمج أكثر جاذبية:

يمكنك إعداد الرمز البرمجي للاستماع إليه عند إضافة ملف صوتي إلى Drive وتخزين البيانات على Google Cloud، وتشغيل وظيفة Google Cloud لتنفيذ هذا الرمز.
تجربة ميزة إدراج نص غير فارغ في "مستند Google"

مزيد من المعلومات

الاطّلاع على وثائق مطوّر برامج واجهة برمجة تطبيقات "مستندات Google"
يمكنك نشر الأسئلة والعثور على إجابات في Stack Overflow ضمن علامة google-docs-api.