שילוב עם ממשק המשתמש של Drive's "פתיחה באמצעות" תפריט ההקשר

כשמשתמש בוחר קובץ ולוחץ על הפריט 'פתיחה באמצעות' בתפריט של ממשק המשתמש של Drive, מערכת Drive מפנה את המשתמש לכתובת ה-URL לפתיחה של האפליקציה הזו, שמוגדרת במאמר הגדרת שילוב של ממשק המשתמש של Drive.

אם סימנתם את התיבה 'ייבוא' כשקבעתם שילוב של ממשק משתמש של Drive, המשתמש יכול לבחור שילוב של קבצים ספציפיים לאפליקציה וקבצים של Google Workspace כדי לפתוח אותם. כשמגדירים שילוב של ממשק משתמש של Drive, קבצים ספציפיים לאפליקציה מוגדרים בשדות 'סוגי MIME שמוגדרים כברירת מחדל' ו'סיומות קבצים שמוגדרות כברירת מחדל', ואילו קבצים של Google Workspace מוגדרים בשדות 'סוגי MIME משניים' ו'סיומות קבצים משניות'.

עבור כל קובץ שהמשתמש רוצה לפתוח, Drive בודק את סוגי ה-MIME מול סוגי ה-MIME שמוגדרים כברירת מחדל וכמשניים:

  • עבור סוגי MIME שמוגדרים בשדה Default MIME types (סוגי MIME שמוגדרים כברירת מחדל), מזהה הקובץ מועבר לאפליקציה. למידע על טיפול בקבצים ספציפיים לאפליקציה, אפשר לעיין במאמר טיפול בכתובת URL לפתיחה של מסמכים ספציפיים לאפליקציה.

  • עבור סוגי MIME שמוגדרים בשדה 'סוגי MIME משניים', בממשק המשתמש של Drive מוצג דו-שיח שבו המשתמש נשאל לאיזה סוג קובץ להמיר את קובץ Google Workspace. לדוגמה, אם בוחרים קובץ Google Docs בממשק המשתמש של Drive והשדה Secondary MIME types (סוגי MIME משניים) מציין שהאפליקציה תומכת ב-text/plain או ב-application/pdf, ממשק המשתמש של Drive ישאל את המשתמש אם הוא רוצה להמיר ל-Plain Text (טקסט פשוט) או ל-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 כשמשתמשים בכתובת 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 כשמשתמשים בכתובת URL פתוחה.
  • USER_ID: מזהה הפרופיל שמזהה את המשתמש.

האפליקציה צריכה לפעול לפי השלבים הבאים בתגובה לבקשה הזו:

  1. כדי לוודא שמדובר בבקשה לפתיחת קובץ, צריך לזהות את הערך open בשדה state ואת הנוכחות של השדה exportIds.

  2. משתמשים בשיטה files.get כדי לבדוק הרשאות, לאחזר מטא-נתונים של קובץ ולקבוע את סוג ה-MIME באמצעות הערכים EXPORT_ID.

  3. ממירים את תוכן הקובץ באמצעות ה-method‏ 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.