drive_v3 0.2.0

data/examples/file_download_content

@@ -0,0 +1,27 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Read the content of a data file
+
+require 'drive_v3'
+require 'json'
+require 'stringio'
+
+drive_service = DriveV3.drive_service
+
+file_id = ARGV[0] || ENV.fetch('FILE_ID', nil)
+raise 'Missing file_id' unless file_id
+
+# download_dest can be an IO object that responds to `write` that will receive
+# the content of the file, or a string naming an existing file to be written
+# to.
+download_dest = StringIO.new
+
+# Read content from file
+#
+begin
+  drive_service.get_file(file_id, download_dest:)
+  puts JSON.pretty_generate(download_dest.string)
+rescue StandardError => e
+  puts "An error occurred: #{e.message}"
+end

data/examples/file_export_spreadsheet

@@ -0,0 +1,48 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Export a spreadsheet to a .tsv file
+#
+# To export a specific sheet, use the sheet_id parameter. To export multiple
+# sheets, use the sheet_ids parameter. Omitting the sheet_id parameter exports
+# the first sheet.
+#
+# To export to a different file type, change the mimeType parameter.
+
+require 'drive_v3'
+require 'json'
+
+drive_service = DriveV3.drive_service
+
+# First create a spreadsheet, populating with some data.
+# Then get the file id of the spreadsheet.
+
+name = 'My Test Spreadsheet'
+parents = [] # Create in the user's My Drive root folder
+mime_type = 'application/vnd.google-apps.spreadsheet'
+file_metadata = { name:, parents:, mime_type: }
+fields = 'id, name'
+upload_source = StringIO.new("1,2,3\n4,5,6\n7,8,9")
+content_type = 'text/csv'
+begin
+  file = drive_service.create_file(file_metadata, fields:, upload_source:, content_type:)
+  puts JSON.pretty_generate(file.to_h)
+rescue StandardError => e
+  puts "An error occurred: #{e.message}"
+  exit 1
+end
+
+# Export the spreadsheet to a PDF file nameed 'My Test Spreadsheet.pdf'
+
+file_id = file.id
+mime_type = 'application/pdf'
+download_dest = "#{file.name}.pdf"
+
+begin
+  drive_service.export_file(file_id, mime_type, download_dest:)
+rescue StandardError => e
+  puts "An error occurred: #{e.message}"
+  exit 1
+end
+
+puts "Exported #{file.name} to #{download_dest}"

data/examples/file_get

@@ -0,0 +1,37 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# `get_file` shows how to get a
+# [File](https://github.com/googleapis/google-api-ruby-client/blob/main/generated/google-apis-drive_v3/lib/google/apis/drive_v3/classes.rb)
+# from the drive controlling which fields are returned.
+
+require 'drive_v3'
+
+drive_service = DriveV3.drive_service
+
+file_id = ARGV[0] || '1MNb_59W87lj75-9HqrEQoFBdrQiNl96rDlRy87sDIjs'
+
+# If `fields` is not specified, the following fields are returned for each file:
+# id, name, mimeType, and kind.
+#
+# Could return all possible fields by specifying `fields: '*'`. See
+# [Return specific fields for a file](https://developers.google.com/drive/api/guides/fields-parameter)
+# for more information about how to retrieve other fields.
+#
+# fields = 'id, name, parents, web_view_link'
+fields = '*'
+
+# If `supports_all_drives` is false or not specified, the request will fail if
+# the file is in a shared drive.
+#
+# See [Search for files & folders](https://developers.google.com/drive/api/v3/search-files)
+# for more information about how to search for files in shared drives.
+#
+supports_all_drives = true
+
+begin
+  file = drive_service.get_file(file_id, fields:, supports_all_drives:)
+  puts JSON.pretty_generate(file.to_h)
+rescue StandardError => e
+  puts "An error occurred: #{e.message}"
+end

data/examples/file_recover_from_trash

@@ -0,0 +1,24 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# `recover_trashed_file` shows how to recover a file from the trash.
+#
+# Moving a file to the trash is done by updating the file's trashed attribute to
+# true. To recover a trashed file is done by updating the file's trashed attribute
+# to false.
+
+require 'drive_v3'
+
+drive_service = DriveV3.drive_service
+
+file_id = ARGV[0] || ENV.fetch('FILE_ID', nil)
+raise 'Missing file_id' unless file_id
+
+begin
+  print 'Recovering trashed file...'
+  file_object = { trashed: false }
+  file = drive_service.update_file(file_id, file_object)
+  puts "update_file result:\n#{file.to_h.pretty_inspect}"
+rescue StandardError => e
+  puts "An error occurred: #{e.message}"
+end

data/examples/file_search

@@ -0,0 +1,86 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Search for files owned by the current user
+#
+# Returns a [FileList](https://github.com/googleapis/google-api-ruby-client/blob/main/generated/google-apis-drive_v3/lib/google/apis/drive_v3/classes.rb)
+# object. The FileList object has a `files` property that is an array of files returned.
+#
+# This example illustrates how to:
+#   1. specify a search query (to omit files in the trash)
+#   2. specify which fields to return for each file
+#   3. retrieve pagenated results
+#
+# Use the `jq` command to format the output of this script. For example:
+#   * List names: `bundle exec examples/list_files | jq '.[].name'`
+#   * List names and id's: `bundle exec examples/list_files | jq '[.[] | {name: .name, id: .id}]'`
+#   * List names and parents: `bundle exec examples/list_files | jq '[.[] | {name: .name, parents: .parents}]'`
+
+require 'drive_v3'
+
+@drive_service = DriveV3.drive_service
+
+@parents = {}
+
+def parent(id)
+  @parents[id] ||= @drive_service.get_file(id, fields: 'name, web_view_link')
+end
+
+files = []
+
+# Number of files to return with each request
+#
+# Limiting to 5 for this example, normally this would be a lot higher
+# (default is 100)
+#
+page_size = 100
+
+# Signal to get first page of results
+#
+# nextPageToken property returns the page_token of the next page
+# of results. If nextPageToken is empty, there are no more pages.
+#
+page_token = nil
+
+# By default `list_files` returns all files even files in the trash. To omit trashed
+# files add `trashed=false` to the q (query) parameter.
+#
+# See [Search for files & folders](https://developers.google.com/drive/api/v3/search-files)
+# for more information about how to use the `q` parameter.
+#
+# q = "trashed=false and '1V6RS_7_YgJmLDH-BDw3dpD8Np60Oi9ET' in parents"
+q = 'trashed=false'
+
+# If `fields` is not specified, the following fields are returned for each file:
+# id, name, mimeType, and kind.
+#
+# Could return all possible fields by specifying `fields: '*'`. In this example,
+# we only need `nextPageToken` for the request and `id`, `name`, and `parents`,
+# and `web_view_link` for each file.
+#
+# If you give fields, you must explicitly include `nextPageToken` if you want it.
+#
+# See [Return specific fields for a file](https://developers.google.com/drive/api/guides/fields-parameter)
+# for more information about how to retrieve other fields.
+#
+# fields = 'nextPageToken, files(id, name, parents, web_view_link)'
+fields = '*'
+
+# If `include_items_from_all_drives` is false or omitted, only files from the user's
+# default drive are returned.
+#
+include_items_from_all_drives = true
+
+loop do
+  file_list = @drive_service.list_files(
+    q:, fields:, include_items_from_all_drives:,
+    page_token:, page_size:
+  )
+  files += file_list.files.map(&:to_h)
+  # Stop looping if there are no more pages
+  break unless (page_token = file_list.next_page_token)
+end
+
+# Print as JSON with links to each file and its parents
+
+puts JSON.pretty_generate(files)

data/examples/file_send_to_trash

@@ -0,0 +1,24 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# `trash_file` shows how to move a file to the trash.
+#
+# Moving a file to the trash is done by updating the file's trashed attribute to
+# true. The process involves using the update method on the file you wish to move
+# to the trash.
+
+require 'drive_v3'
+
+drive_service = DriveV3.drive_service
+
+file_id = ARGV[0] || ENV.fetch('FILE_ID', nil)
+raise 'Missing file_id' unless file_id
+
+begin
+  print 'Trash file...'
+  file_object = { trashed: true }
+  file = drive_service.update_file(file_id, file_object)
+  puts "update_file result:\n#{file.to_h.pretty_inspect}"
+rescue StandardError => e
+  puts "An error occurred: #{e.message}"
+end

data/examples/file_upload_content

@@ -0,0 +1,25 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Replace a file's content
+
+require 'drive_v3'
+
+drive_service = DriveV3.drive_service
+
+file_id = ARGV[0] || ENV.fetch('FILE_ID', nil)
+raise 'Missing file_id' unless file_id
+
+# upload_source can be an IO object that responds to `read` and `size` (e.g.
+# StringIO) or a string that names an existing file to upload.
+#
+upload_source = StringIO.new('This is the content that replaced the original content')
+
+# Replace the content of an existing file
+#
+begin
+  file = drive_service.update_file(file_id, upload_source:)
+  puts JSON.pretty_generate(file.to_h)
+rescue StandardError => e
+  puts "An error occurred: #{e.message}"
+end

data/examples/permission_create

@@ -0,0 +1,165 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Creates a new permission for a file
+#
+# To add a permission:
+#
+#   1. Create a permission object with the `type` and `role`. If type=user or
+#      type=group, provide an `email_address`. If type=domain, provide a `domain`.
+#   2. Call the `create_permission` method with the id for the associated file
+#      or folder.
+#   3. The response returns an instance of a Permission resource, including the
+#      assigned id.
+
+require 'drive_v3'
+require 'optparse'
+
+# Parse the command line
+#
+# @example For a user or group
+#   permission-create FILE_ID \
+#     --type {user|group} \
+#     --email EMAIL \
+#     --role ROLE \
+#     [--expiration TIME] \
+#     [{--allow-file-discovery | --no-allow-file-discovery}]
+#
+# @example For a domain
+#   permission-create FILE_ID \
+#     --type domain \
+#     --domain NAME \
+#     --role ROLE \
+#     [--expiration TIME] \
+#     [{--allow-file-discovery | --no-allow-file-discovery}]
+#
+# @example For a anyone
+#   permission-create FILE_ID \
+#     --type anyone \
+#     --role ROLE \
+#     [--expiration TIME] \
+#     [{--allow-file-discovery | --no-allow-file-discovery}]
+#
+class PermissionCreateCli
+  def initialize(argv)
+    @argv = argv.dup
+    default_options
+    parser.parse!(@argv)
+    @file_id = @argv.shift || ENV.fetch('FILE_ID', nil)
+    validate(@argv)
+  end
+
+  attr_reader :file_id, :permission_id, :permission
+
+  def to_s
+    "'#{file_id}', #{permission}"
+  end
+
+  private
+
+  def banner = <<~BANNER
+    Usage:
+    #{$PROGRAM_NAME} FILE_ID [options]
+
+    Creates permission for a file.
+
+    Options:
+  BANNER
+
+  def parser
+    @parser ||= OptionParser.new(banner) do |opts|
+      option_definitions.each { |option_definition| opts.on(*option_definition) }
+    end
+  end
+
+  def help
+    puts parser
+    exit
+  end
+
+  def option_definitions
+    [
+      help_definition,
+      type_definition, email_definition, domain_definition, role_definition,
+      allow_file_discovery_definition, expiration_definition
+    ].freeze
+  end
+
+  def help_definition = ['-h', '--help', '', ->(_value) { help }]
+  def type_definition = ['--type=TYPE', ->(value) { @permission[:type] = value }]
+  def email_definition = ['--email=EMAIL', ->(value) { @permission[:email_address] = value }]
+  def domain_definition = ['--domain=DOMAIN', ->(value) { @permission[:domain] = value }]
+  def role_definition = ['--role=ROLE', ->(value) { @permission[:role] = value }]
+
+  def allow_file_discovery_definition
+    [
+      '--[no-]allow-file-discovery',
+      ->(value) { @permission[:allow_file_discovery] = value }
+    ]
+  end
+
+  def expiration_definition
+    [
+      '--expiration=TIME',
+      ->(value) { @permission[:expiration_time] = DateTime.parse(value) }
+    ]
+  end
+
+  def default_options
+    @file_id = nil
+    @permission = {
+      type: nil, email_address: nil, domain: nil, role: nil,
+      allow_file_discovery: nil, expiration_time: nil
+    }
+  end
+
+  def validate(argv)
+    raise "Extra command line arguments: #{argv}" unless argv.empty?
+
+    raise 'Missing file_id' unless file_id
+  end
+end
+
+# The new permission to create
+#
+# `type` can be user, group, domain, or anyone.
+#
+# When type=user or type=group, you must also provide an `email_address`.
+#
+# When type=domain, you must also provide a `domain``.
+#
+# See [Share files, folders & drives](https://developers.google.com/drive/api/guides/manage-sharing)
+#
+# See [Roles & permissions](https://developers.google.com/drive/api/guides/ref-roles)
+# for more information about the different roles.
+#
+# allow_file_discovery is not valid for individual users.
+#
+# @example: when type is 'anyone'
+#   permission = {
+#     allow_file_discovery: true,
+#     type: 'anyone',
+#     role: 'writer'
+#   }
+#
+# @example: when type is 'user'
+#   permission = {
+#     type: 'user',
+#     role: 'writer',
+#     email_address: 'jcouball@gmail.com'
+#   }
+#
+
+drive_service = DriveV3.drive_service
+
+options = PermissionCreateCli.new(ARGV)
+fields = '*'
+
+begin
+  result = drive_service.create_permission(options.file_id, options.permission, fields:)
+  # The result.id is 'anyoneWithLink' if type=anyone
+  # The result.id is of the existing permission if it already exists
+  puts JSON.pretty_generate(result.to_h)
+rescue StandardError => e
+  puts "An error occurred: #{e.message}"
+end

data/examples/permission_delete

@@ -0,0 +1,22 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# List permissions for a file or folder
+
+require 'drive_v3'
+
+file_id = ARGV.shift || ENV.fetch('FILE_ID', nil)
+raise 'Missing file_id' unless file_id
+
+permission_id = ARGV.shift || ENV.fetch('PERMISSION_ID', nil)
+raise 'Missing permission_id' unless permission_id
+
+raise "Extra arguments: #{ARGV}" unless ARGV.empty?
+
+drive_service = DriveV3.drive_service
+
+begin
+  drive_service.delete_permission(file_id, permission_id)
+rescue StandardError => e
+  puts "An error occurred: #{e.message}"
+end

data/examples/permission_list

@@ -0,0 +1,49 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# List permissions for a file or folder
+
+require 'drive_v3'
+
+file_id = ARGV[0] || ENV.fetch('FILE_ID', nil)
+raise 'Missing file_id' unless file_id
+
+drive_service = DriveV3.drive_service
+
+permissions = []
+
+# Number of files to return with each request
+#
+# Limiting to 2 for this example, normally this would be a lot higher
+# (default is 100)
+#
+page_size = 2
+
+# Signal to get first page of results
+#
+# nextPageToken property returns the page_token of the next page
+# of results. If nextPageToken is empty, there are no more pages.
+#
+page_token = nil
+
+# If `fields` is not specified, the following fields are returned for each permission:
+# ???
+#
+# Could return all possible fields by specifying `fields: '*'`.
+#
+# If you give fields, you must explicitly include `nextPageToken` if you want it.
+#
+# See [Return specific fields for a file](https://developers.google.com/drive/api/guides/fields-parameter)
+# for more information about how to retrieve other fields.
+#
+# fields = 'nextPageToken, files(id, name, parents, web_view_link)'
+fields = '*'
+
+loop do
+  permission_list = drive_service.list_permissions(file_id, fields:, page_token:, page_size:)
+  permissions += permission_list.permissions.map(&:to_h)
+  # Stop looping if there are no more pages
+  break unless (page_token = permission_list.next_page_token)
+end
+
+puts JSON.pretty_generate(permissions)

data/examples/permission_update

@@ -0,0 +1,134 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Updates an existing permission for a file
+#
+# Use permission_list to list the existing permissions for a file.
+
+require 'drive_v3'
+require 'optparse'
+require 'time'
+
+# Parse command line arguments
+#
+# Usage: permission-update FILE_ID PERMISSION_ID \
+#   --remove-expiration \
+#   --type TYPE \
+#   --email EMAIL \
+#   --domain DOMAIN \
+#   --role ROLE \
+#   --[no-]allow-file-discovery \
+#   --expiration TIME
+#
+# Examples:
+#   permission-update 12345678 12345678 --expiration 2023-12-31T00:00:00-07:00
+#   permission-update 12345678 12345678 --remove-expiration
+#   permission-update 12345678 12345678 --role reader
+#   permission-update 12345678 12345678 --email jcouball@yahoo.com
+#   permission-update 12345678 12345678 --email jcouball@yahoo.com --role reader
+#   permission-update 12345678 12345678 --allow-file-discovery
+#   permission-update 12345678 12345678 --no-allow-file-discovery
+#
+class PermissionUpdateCli
+  def initialize(argv)
+    @argv = argv.dup
+    default_options
+    parser.parse!(@argv)
+    @file_id = @argv.shift || ENV.fetch('FILE_ID', nil)
+    @permission_id = @argv.shift || ENV.fetch('PERMISSION_ID', nil)
+    validate(@argv)
+  end
+
+  attr_reader :file_id, :permission_id, :permission, :remove_expiration
+
+  def to_s
+    "'#{file_id}', '#{permission_id}', #{permission}, remove_expiration: #{remove_expiration}"
+  end
+
+  private
+
+  def banner = <<~BANNER
+    Usage:
+    #{$PROGRAM_NAME} FILE_ID PERMISSION_ID [options]
+
+    Updates a permission for a file.
+    Use permission-create to create a new permission for a file.
+    User permission-list to list permissions for a file.
+
+    Options:
+  BANNER
+
+  def parser
+    @parser ||= OptionParser.new(banner) do |opts|
+      option_definitions.each { |option_definition| opts.on(*option_definition) }
+    end
+  end
+
+  def help
+    puts parser
+    exit
+  end
+
+  def option_definitions
+    [
+      help_definition, remove_expiration_definition, type_definition,
+      email_definition, domain_definition, role_definition,
+      allow_file_discovery_definition, expiration_definition
+    ].freeze
+  end
+
+  def help_definition = ['-h', '--help', '', ->(_value) { help }]
+  def type_definition = ['--type=TYPE', ->(value) { @permission[:type] = value }]
+  def email_definition = ['--email=EMAIL', ->(value) { @permission[:email_address] = value }]
+  def domain_definition = ['--domain=DOMAIN', ->(value) { @permission[:domain] = value }]
+  def role_definition = ['--role=ROLE', ->(value) { @permission[:role] = value }]
+  def remove_expiration_definition = ['--remove-expiration', ->(_value) { @remove_expiration = true }]
+
+  def allow_file_discovery_definition
+    [
+      '--[no-]allow-file-discovery',
+      ->(value) { @permission[:allow_file_discovery] = value }
+    ]
+  end
+
+  def expiration_definition
+    [
+      '--expiration=TIME',
+      ->(value) { @permission[:expiration_time] = DateTime.parse(value) }
+    ]
+  end
+
+  def default_options
+    @file_id = nil
+    @permission_id = nil
+    @permission = {
+      type: nil, email_address: nil, domain: nil, role: nil,
+      allow_file_discovery: nil, expiration_time: nil
+    }
+    @remove_expiration = nil
+  end
+
+  def validate(argv)
+    raise "Extra command line arguments: #{argv}" unless argv.empty?
+
+    raise 'Missing file_id' unless file_id
+
+    raise 'Missing permission_id' unless permission_id
+  end
+end
+
+drive_service = DriveV3.drive_service
+
+options = PermissionUpdateCli.new(ARGV)
+file_id = options.file_id
+permission_id = options.permission_id
+permission = options.permission
+remove_expiration = options.remove_expiration
+fields = '*'
+
+begin
+  result = drive_service.update_permission(file_id, permission_id, permission, remove_expiration:, fields:)
+  puts "Permission updated: #{result.to_h.pretty_inspect}"
+rescue StandardError => e
+  puts "An error occurred: #{e.message}"
+end