Handle an Open URL

Stay organized with collections Save and categorize content based on your preferences.

When a user selects a file and clicks the "Open with" context menu item, Drive redirects the user to that app's Open URL defined when you Configure a Drive integration.

If you checked the "Importing" box when you configured a Drive integration, the user can select a combination of app-specific and Google Workspace files to open. App-specific files are defined in the Default Mime Types and Default File Extensions fields when you configured a Drive integration. Google Workspace files are defined in the Secondary Mime Types and Secondary File Extensions fields when you configured a Drive integration.

For each file that the user wants to open, Drive checks the MIME types against the default and secondary mime types you defined:

  • For MIME types defined in the Default Mime Types field, the fileID is passed on to your app. For information on how to handle app-specific files, refer to Handle an Open URL for an app-specific document

  • For MIME types defined in the Secondary Mime Types field, the Drive UI displays a dialog asking the user what file type to convert the Google Workspace file to. For example, if you select a Google Doc in the Drive UI and Secondary Mime Types field suggests your app supports text/html, text/plain, or application/pdf, the Drive UI asks the user if they want to convert to HTML, Plain text, or PDF. For information on how to handle Google Workspace files, refer to Handle an Open URL for a Google Workspace document. For a list of Google Workspace Documents, conversion formats, and corresponding mime types, refer to Google Workspace documents and corresponding export MIME types.

Handle an Open URL for an app-specific document

As mentioned in Configure a drive UI integration, your app receives template variables holding information for your app to open the file. Your app receives a default set of template variables within a state parameter. The default state information for an app-specific Open URL is:

{
  "ids": ["0Bz0bd"],
  "resourceKeys":{"0Bz0bd":"AAshj23Ad1"},
  "action":"open",
  "userId":"103354693083460731603"
}

To handle this information:

  1. Detect the open value in the state parameter to verify that this is a request to open a file.

  2. Check permissions, fetch file metadata, and download the file content using the files.get method.

The state parameter is URL-encoded, so your app must handle the escape characters and parse it as JSON.

Handle an Open URL for a Google Workspace document

As mentioned in Configure a drive UI integration, your app receives a default set of template variables within a state parameter. The default state information for an app-specific Open URL is:

{
  "exportIds": ["0Bz0bd"],
  "resourceKeys":{"0Bz0bd":"AAshj23Ad1"},
  "action":"open",
  "userId":"103354693083460731603"
}

To handle this information:

  1. Detect the open value in the state parameter to verify that this is a request to open a file.

  2. Check permissions, fetch file metadata, and determine mime type.

  3. Convert the file content using the files.export method. The following snippet shows how to convert a file as a new file type.

    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
    from __future__ import print_function

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
    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;
    }

}

  4. Display converted files as read-only or present a dialog box allowing the user to save the file as a file of the new type.

The state parameter is URL-encoded, so your app must handle the escape characters and parse it as JSON.

Handle "Open with" events

Drive apps should treat all "Open with" events as potential logins. Some users may have multiple accounts, so the user ID in the state parameter might not match the current session. If the user ID in the state parameter doesn't match the current session, end the current session for your app and log in as the requested user.

Next step

In addition to launching an application from Google Drive UI, applications can display a file picker to select content from within the app itself. See the files picker guide for additional details.

Apps should display converted files as read-only, or let users save them as new files.