الدمج مع واجهة مستخدم Drive "؛الفتح باستخدام" قائمة السياق

عندما يختار المستخدم ملفًا وينقر على عنصر القائمة "فتح باستخدام" في واجهة مستخدم Drive، يعيد Drive توجيه المستخدم إلى عنوان URL الخاص بالتطبيق والمحدّد في ضبط عملية الدمج مع واجهة مستخدم Drive.

إذا وضعت علامة في المربّع "استيراد" عند إعداد عملية دمج واجهة مستخدم Drive، يمكن للمستخدم اختيار مجموعة من الملفات الخاصة بالتطبيق وملفات Google Workspace لفتحها. عند ضبط عملية دمج واجهة مستخدم Drive، يتم تحديد الملفات الخاصة بالتطبيق في الحقلَين "أنواع MIME التلقائية" و"امتدادات الملفات التلقائية"، بينما يتم تحديد ملفات Google Workspace في الحقلَين "أنواع MIME الثانوية" و "امتدادات الملفات الثانوية".

بالنسبة إلى كل ملف يريد المستخدم فتحه، يتحقّق Drive من أنواع MIME مقارنةً بأنواع MIME التلقائية والثانوية التي حدّدتها:

  • بالنسبة إلى أنواع MIME المحدّدة في الحقل "أنواع MIME التلقائية"، يتم تمرير معرّف الملف إلى تطبيقك. وللحصول على معلومات حول كيفية التعامل مع الملفات الخاصة بالتطبيق، راجِع مقالة التعامل مع عنوان URL مفتوح للمستندات الخاصة بالتطبيق.

  • بالنسبة إلى أنواع MIME المحدّدة في حقل "أنواع MIME الثانوية"، تعرض واجهة مستخدم Drive مربّع حوار يسأل المستخدم عن نوع الملف الذي يريد تحويل ملف Google Workspace إليه. على سبيل المثال، إذا اخترت ملفًا بتنسيق "مستندات Google" في واجهة مستخدم Drive واقترح حقل "أنواع MIME الثانوية" أنّ تطبيقك يتوافق مع text/plain أو application/pdf، ستسأل واجهة مستخدم Drive المستخدم عمّا إذا كان يريد التحويل إلى "نص عادي" أو PDF.

    للحصول على معلومات حول كيفية التعامل مع ملفات Google Workspace، يُرجى الاطّلاع على التعامل مع عنوان URL مفتوح لمستندات Google Workspace. للاطّلاع على قائمة بمستندات Google Workspace وتنسيقات تحويل أنواع MIME، يُرجى الاطّلاع على تصدير أنواع MIME لمستندات Google Workspace.

التعامل مع طلب فتح عنوان URL لمستندات خاصة بالتطبيق

كما هو موضّح في إعداد عملية دمج لواجهة مستخدم Drive، يتلقّى تطبيقك متغيّرات النموذج التي تتضمّن معلومات تتيح لتطبيقك فتح الملف. يتلقّى تطبيقك مجموعة تلقائية من متغيّرات النموذج ضمن المَعلمة state. في ما يلي معلومات state تلقائية لعنوان URL خاص بتطبيق معيّن:

{
  "ids": ["ID"],
  "resourceKeys":{"RESOURCE_KEYS":"RESOURCE_KEYS"},
  "action":"open",
  "userId":"USER_ID"
}

يتضمّن هذا الناتج القيم التالية:

  • ID: معرّف المجلد الرئيسي
  • RESOURCE_KEYS: قاموس JSON لمعرّفات الملفات التي تم ربطها بمفاتيح الموارد الخاصة بها.
  • open: الإجراء الذي يتم تنفيذه القيمة هي open عند استخدام Open URL.
  • USER_ID: رقم تعريف الملف الشخصي الذي يحدّد المستخدم بشكل فريد.

يجب أن يتّخذ تطبيقك إجراءً بشأن هذا الطلب باتّباع الخطوات التالية:

  1. تأكَّد من أنّ الحقل action يتضمّن القيمة open وأنّ الحقل ids متوفّر.
  2. استخدِم القيمة userId لإنشاء جلسة جديدة للمستخدم. لمزيد من المعلومات عن المستخدمين الذين سجّلوا الدخول، اطّلِع على المستخدمون والأحداث الجديدة.
  3. استخدِم طريقة files.get للتحقّق من الأذونات وجلب البيانات الوصفية للملف وتنزيل محتوى الملف باستخدام قيم ID.
  4. إذا تم ضبط resourceKeys في الطلب، اضبط عنوان الطلب X-Goog-Drive-Resource-Keys. لمزيد من المعلومات حول مفاتيح الموارد، يُرجى الاطّلاع على الوصول إلى الملفات التي تتم مشاركتها باستخدام رابط من خلال مفاتيح الموارد.

يتم ترميز المَعلمة state باستخدام ترميز عنوان URL، لذا يجب أن يتعامل تطبيقك مع أحرف الإلغاء ويحلّلها بتنسيق JSON.

التعامل مع عنوان URL مفتوح لمستندات Google Workspace

كما هو موضّح في إعداد عملية دمج لواجهة مستخدم Drive، يتلقّى تطبيقك مجموعة تلقائية من متغيّرات النموذج ضمن المَعلمة state. state المعلومات التلقائية لفتح عنوان URL في Google Workspace هي:

{
  "exportIds": ["ID"],
  "resourceKeys":{"RESOURCE_KEYS":"RESOURCE_KEYS"},
  "action":"open",
  "userId":"USER_ID"
}

يتضمّن هذا الناتج القيم التالية:

  • EXPORT_ID: قائمة بأرقام تعريف الملفات مفصولة بفواصل يتم تصديرها (يتم استخدامها فقط عند فتح مستندات Google المضمّنة).
  • RESOURCE_KEYS: قاموس JSON لمعرّفات الملفات التي تم ربطها بمفاتيح الموارد الخاصة بها.
  • open: الإجراء الذي يتم تنفيذه القيمة هي open عند استخدام Open URL.
  • USER_ID: رقم تعريف الملف الشخصي الذي يحدّد المستخدم.

يجب أن يتّخذ تطبيقك إجراءً بشأن هذا الطلب باتّباع الخطوات التالية:

  1. تأكَّد من أنّ هذا الطلب يهدف إلى فتح ملف من خلال رصد كلّ من القيمة open في الحقل state ووجود الحقل exportIds.

  2. استخدِم طريقة files.get للتحقّق من الأذونات واسترداد البيانات الوصفية للملفات وتحديد نوع MIME باستخدام قيم EXPORT_ID.

  3. حوِّل محتوى الملف باستخدام الطريقة files.export. يوضّح نموذج الرمز التالي كيفية تصدير مستند Google Workspace إلى نوع MIME المطلوب.

  4. إذا تم ضبط resourceKey في الطلب، اضبط عنوان الطلب X-Goog-Drive-Resource-Keys. لمزيد من المعلومات حول مفاتيح الموارد، يُرجى الاطّلاع على الوصول إلى الملفات التي تتم مشاركتها باستخدام رابط من خلال مفاتيح الموارد.

    Java

    drive/snippets/drive_v3/src/main/java/ExportPdf.java
    import com.google.api.client.googleapis.json.GoogleJsonResponseException;
    import com.google.api.client.http.HttpRequestInitializer;
    import com.google.api.client.http.javanet.NetHttpTransport;
    import com.google.api.client.json.gson.GsonFactory;
    import com.google.api.services.drive.Drive;
    import com.google.api.services.drive.DriveScopes;
    import com.google.auth.http.HttpCredentialsAdapter;
    import com.google.auth.oauth2.GoogleCredentials;
    import java.io.ByteArrayOutputStream;
    import java.io.IOException;
    import java.io.OutputStream;
    import java.util.Arrays;
    
    /* Class to demonstrate use-case of drive's export pdf. */
    public class ExportPdf {
    
      /**
       * Download a Document file in PDF format.
       *
       * @param realFileId file ID of any workspace document format file.
       * @return byte array stream if successful, {@code null} otherwise.
       * @throws IOException if service account credentials file not found.
       */
      public static ByteArrayOutputStream exportPdf(String realFileId) throws IOException {
        // Load pre-authorized user credentials from the environment.
        // TODO(developer) - See https://developers.google.com/identity for
        // guides on implementing OAuth2 for your application.
        GoogleCredentials credentials = GoogleCredentials.getApplicationDefault()
            .createScoped(Arrays.asList(DriveScopes.DRIVE_FILE));
        HttpRequestInitializer requestInitializer = new HttpCredentialsAdapter(
            credentials);
    
        // Build a new authorized API client service.
        Drive service = new Drive.Builder(new NetHttpTransport(),
            GsonFactory.getDefaultInstance(),
            requestInitializer)
            .setApplicationName("Drive samples")
            .build();
    
        OutputStream outputStream = new ByteArrayOutputStream();
        try {
          service.files().export(realFileId, "application/pdf")
              .executeMediaAndDownloadTo(outputStream);
    
          return (ByteArrayOutputStream) outputStream;
        } catch (GoogleJsonResponseException e) {
          // TODO(developer) - handle error appropriately
          System.err.println("Unable to export file: " + e.getDetails());
          throw e;
        }
      }
    }

    Python

    drive/snippets/drive-v3/file_snippet/export_pdf.py
    import io
    
    import google.auth
    from googleapiclient.discovery import build
    from googleapiclient.errors import HttpError
    from googleapiclient.http import MediaIoBaseDownload
    
    
    def export_pdf(real_file_id):
      """Download a Document file in PDF format.
      Args:
          real_file_id : file ID of any workspace document format file
      Returns : IO object with location
    
      Load pre-authorized user credentials from the environment.
      TODO(developer) - See https://developers.google.com/identity
      for guides on implementing OAuth2 for the application.
      """
      creds, _ = google.auth.default()
    
      try:
        # create drive api client
        service = build("drive", "v3", credentials=creds)
    
        file_id = real_file_id
    
        # pylint: disable=maybe-no-member
        request = service.files().export_media(
            fileId=file_id, mimeType="application/pdf"
        )
        file = io.BytesIO()
        downloader = MediaIoBaseDownload(file, request)
        done = False
        while done is False:
          status, done = downloader.next_chunk()
          print(f"Download {int(status.progress() * 100)}.")
    
      except HttpError as error:
        print(f"An error occurred: {error}")
        file = None
    
      return file.getvalue()
    
    
    if __name__ == "__main__":
      export_pdf(real_file_id="1zbp8wAyuImX91Jt9mI-CAX_1TqkBLDEDcr2WeXBbKUY")

    Node.js

    drive/snippets/drive_v3/file_snippets/export_pdf.js
    /**
     * Download a Document file in PDF format
     * @param{string} fileId file ID
     * @return{obj} file status
     * */
    async function exportPdf(fileId) {
      const {GoogleAuth} = require('google-auth-library');
      const {google} = require('googleapis');
    
      // Get credentials and build service
      // TODO (developer) - Use appropriate auth mechanism for your app
      const auth = new GoogleAuth({
        scopes: 'https://www.googleapis.com/auth/drive',
      });
      const service = google.drive({version: 'v3', auth});
    
      try {
        const result = await service.files.export({
          fileId: fileId,
          mimeType: 'application/pdf',
        });
        console.log(result.status);
        return result;
      } catch (err) {
        // TODO(developer) - Handle error
        throw err;
      }
    }

    PHP

    drive/snippets/drive_v3/src/DriveExportPdf.php
    <?php
    use Google\Client;
    use Google\Service\Drive;
    function exportPdf()
    {
        try {
            $client = new Client();
            $client->useApplicationDefaultCredentials();
            $client->addScope(Drive::DRIVE);
            $driveService = new Drive($client);
            $realFileId = readline("Enter File Id: ");
            $fileId = '1ZdR3L3qP4Bkq8noWLJHSr_iBau0DNT4Kli4SxNc2YEo';
            $fileId = $realFileId;
            $response = $driveService->files->export($fileId, 'application/pdf', array(
                'alt' => 'media'));
            $content = $response->getBody()->getContents();
            return $content;
    
        }  catch(Exception $e) {
             echo "Error Message: ".$e;
        }
    
    }

عرض الملفات المحوَّلة كملفات للقراءة فقط أو عرض مربّع حوار يتيح للمستخدم حفظ الملف بنوع الملف الجديد

يتم ترميز المَعلمة state باستخدام ترميز عنوان URL، لذا يجب أن يتعامل تطبيقك مع أحرف الإلغاء ويحلّلها بتنسيق JSON.

المستخدمون والأحداث الجديدة

يجب أن تتعامل تطبيقات Drive مع جميع أحداث "فتح باستخدام" على أنّها عمليات تسجيل دخول محتملة. قد يكون لدى بعض المستخدمين حسابات متعددة، لذا قد لا يتطابق معرّف المستخدم في المَعلمة state مع الجلسة الحالية. إذا كان معرّف المستخدم في المَعلمة state لا يتطابق مع الجلسة الحالية، عليك إنهاء الجلسة الحالية لتطبيقك وتسجيل الدخول بصفتك المستخدم المطلوب.

بالإضافة إلى فتح تطبيق من واجهة مستخدم Google Drive، يمكن للتطبيقات عرض أداة اختيار ملفات لاختيار المحتوى من داخل التطبيق. لمزيد من المعلومات، اطّلِع على Google Picker.