drive_v3 0.2.0

data/Rakefile

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+desc 'Run the same tasks that the CI build will run'
+if RUBY_PLATFORM == 'java'
+  task default: %w[spec rubocop bundle:audit build]
+else
+  task default: %w[spec rubocop yard bundle:audit build]
+end
+
+# Bundler Audit
+
+require 'bundler/audit/task'
+Bundler::Audit::Task.new
+
+# Bundler Gem Build
+
+require 'bundler'
+require 'bundler/gem_tasks'
+
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  warn e.message
+  warn 'Run `bundle install` to install missing gems'
+  exit e.status_code
+end
+
+CLEAN << 'pkg'
+CLEAN << 'Gemfile.lock'
+
+# RSpec
+
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new do
+  if RUBY_PLATFORM == 'java'
+    ENV['JAVA_OPTS'] = '-Djdk.io.File.enableADS=true'
+    ENV['JRUBY_OPTS'] = '--debug'
+    ENV['NOCOV'] = 'TRUE'
+  end
+end
+
+CLEAN << 'coverage'
+CLEAN << '.rspec_status'
+CLEAN << 'rspec-report.xml'
+
+# Rubocop
+
+require 'rubocop/rake_task'
+
+RuboCop::RakeTask.new do |t|
+  t.options = %w[
+    --display-cop-names
+    --display-style-guide
+    --extra-details
+    --format progress
+    --format json --out rubocop-report.json
+  ]
+end
+
+CLEAN << 'rubocop-report.json'
+
+unless RUBY_PLATFORM == 'java'
+  # yard:build
+
+  require 'yard'
+
+  YARD::Rake::YardocTask.new('yard:build') do |t|
+    t.files = %w[lib/**/*.rb]
+    t.stats_options = ['--list-undoc']
+  end
+
+  CLEAN << '.yardoc'
+  CLEAN << 'doc'
+
+  # yard:audit
+
+  desc 'Run yardstick to show missing YARD doc elements'
+  task :'yard:audit' do
+    sh "yardstick 'lib/**/*.rb'"
+  end
+
+  # yard:coverage
+
+  require 'yardstick/rake/verify'
+
+  Yardstick::Rake::Verify.new(:'yard:coverage') do |verify|
+    verify.threshold = 100
+    verify.require_exact_threshold = false
+  end
+
+  task yard: %i[yard:build yard:audit yard:coverage]
+
+  # github-pages:publish
+
+  require 'github_pages_rake_tasks'
+  GithubPagesRakeTasks::PublishTask.new do |task|
+    # task.doc_dir = 'documentation'
+    task.verbose = true
+  end
+end

data/examples/README.md

@@ -0,0 +1,300 @@
+# Google Drive Examples
+
+Annotated examples written in Ruby.
+
+Checked (✅︎) topics are completed. Topics without a check still need to be added.
+
+* [Getting started](#getting-started)
+  * [✅︎ Creating a Google API service account](#︎-creating-a-google-api-service-account)
+  * [✅︎ Creating a DriveService instance](#︎-creating-a-driveservice-instance)
+  * [✅︎ Batching DriveService requests](#︎-batching-driveservice-requests)
+* [Files and folders](#files-and-folders)
+  * [✅︎ Search for files](#︎-search-for-files)
+  * [✅︎ Get file](#︎-get-file)
+  * [✅︎ Create an empty data file](#︎-create-an-empty-data-file)
+  * [✅︎ Create a folder](#︎-create-a-folder)
+  * [✅︎ Create a spreadsheet, document, or presentation](#︎-create-a-spreadsheet-document-or-presentation)
+  * [✅︎ Upload file data](#︎-upload-file-data)
+  * [✅︎ Download file data](#︎-download-file-data)
+  * [✅︎ Export file](#︎-export-file)
+  * [✅︎ Send file to trash](#︎-send-file-to-trash)
+  * [✅︎ Recover file from trash](#︎-recover-file-from-trash)
+  * [✅︎ Delete a file](#︎-delete-a-file)
+* [Share files, folders, and drives](#share-files-folders-and-drives)
+  * [✅︎ Create permission](#︎-create-permission)
+  * [✅︎ List permissions](#︎-list-permissions)
+  * [✅︎ Update permission](#︎-update-permission)
+  * [✅︎ Delete permission](#︎-delete-permission)
+* [Shortcuts](#shortcuts)
+  * [Create a shortcut to a file](#create-a-shortcut-to-a-file)
+  * [Search for shortcuts](#search-for-shortcuts)
+* [Other](#other)
+  * [File revisions](#file-revisions)
+  * [Store application-specific data](#store-application-specific-data)
+  * [Manage file metadata](#manage-file-metadata)
+  * [Manage comments and replies](#manage-comments-and-replies)
+  * [Add custom file properties](#add-custom-file-properties)
+  * [Create a shortcut to a Drive file](#create-a-shortcut-to-a-drive-file)
+  * [Create a shortcut to app content](#create-a-shortcut-to-app-content)
+  * [Protect file content from modification](#protect-file-content-from-modification)
+  * [Access link-shared files using resource keys](#access-link-shared-files-using-resource-keys)
+* [Handle changes](#handle-changes)
+  * [Identify which change log to track](#identify-which-change-log-to-track)
+  * [Track changes for users and shared drives](#track-changes-for-users-and-shared-drives)
+  * [Retrieve changes](#retrieve-changes)
+  * [Receive notifications for resource changes](#receive-notifications-for-resource-changes)
+* [Manage labels](#manage-labels)
+  * [Manage labels](#manage-labels-1)
+  * [Set label field](#set-label-field)
+  * [Unset label field](#unset-label-field)
+  * [Remove label](#remove-label)
+  * [List labels from file](#list-labels-from-file)
+  * [Return specific labels from a file](#return-specific-labels-from-a-file)
+  * [Search by label or field](#search-by-label-or-field)
+
+## Getting started
+
+### ✅︎ Creating a Google API service account
+
+See the [Getting started](https://github.com/main-branch/drive_v3#getting-started)
+section in the project README.md
+
+### ✅︎ Creating a DriveService instance
+
+See [Obtaining an authenticated DriveService](https://github.com/main-branch/drive_v3#obtaining-an-authenticated-driveservice)
+section in the project README.md
+
+### ✅︎ Batching DriveService requests
+
+Each HTTP connection that your client makes results in a certain amount of overhead.
+The Google Drive API supports batching, to allow your client to put several API
+calls into a single HTTP request.
+
+See [examples/drive_service_batch](https://github.com/main-branch/drive_v3/blob/main/examples/drive_service_batch)
+for an example of how to batch Drive API.
+
+You're limited to 100 calls in a single batch request. If you need to make more
+calls than that, use multiple batch requests.
+
+## Files and folders
+
+Google Drive organizes files in collections, describes files by types, and provides
+specific attributes for each file to facilitate file manipulation.
+
+The Google Drive API represents files stored on Drive as a File resource.
+
+See [File & folders overview](https://developers.google.com/drive/api/guides/about-files)
+in the Google Drive API documentation for more information.
+
+Folders are treated as a type of file. For more details about folders, see
+[File types](https://developers.google.com/drive/api/guides/about-files#types).
+
+### ✅︎ Search for files
+
+[examples/file_search](https://github.com/main-branch/drive_v3/blob/main/examples/file_search)
+shows how to list all the files for the authenticated user.
+
+This example illustrates how to:
+1. Use a search query to filter results with specific examples for:
+   * Omitting files that are in the trash
+   * Only returning files in a specific folder
+2. Specify which data to return about each file
+3. How to retrieve the name of the containing folder for each file
+4. How to retrieve pagenated results
+
+### ✅︎ Get file
+
+[examples/file_get](https://github.com/main-branch/drive_v3/blob/main/examples/file_get)
+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 and controlling which fields are returned.
+
+### ✅︎ Create an empty data file
+
+To create a file that contains no metadata or content, use the `drive_service.create_file`
+method with no parameters. The file is given a kind of drive.file, an id, a name of
+"Untitled," and a mimeType of application/octet-stream.
+
+Use the `:parents` parameter to give the id of the folder that should contain the
+file. Omitting this parameter or passing an empty array will place the new file
+in the user's `My Drive` root folder.
+
+[examples/file_create](https://github.com/main-branch/drive_v3/blob/main/examples/file_create)
+shows how to create an empty data file and write data to it.
+
+### ✅︎ Create a folder
+
+[examples/file_create_folder](https://github.com/main-branch/drive_v3/blob/main/examples/file_create_folder)
+shows how to create a folder by setting the appropriate mime-type.
+
+See [Create and populate folders](https://developers.google.com/drive/api/guides/folder#create-folder)
+for more information.
+
+### ✅︎ Create a spreadsheet, document, or presentation
+
+[examples/file_create_spreadsheet](https://github.com/main-branch/drive_v3/blob/main/examples/file_create_spreadsheet)
+shows how to create a blank spreadsheet by setting the appropriate mime-type.
+
+See [Create a spreadsheet](https://developers.google.com/sheets/api/guides/create#work_with_folders)
+for more information.
+
+Use the following mime-types for Google apps:
+* Spreadsheet: **application/vnd.google-apps.spreadsheet**
+* Document: **application/vnd.google-apps.document**
+* Presentation: **application/vnd.google-apps.presentation**
+
+See [Google Workspace & Google Drive supported MIME types](https://developers.google.com/drive/api/guides/mime-types)
+for a comprehensive list of MIME types supported by Google Drive.
+
+### ✅︎ Upload file data
+
+Use `drive_service.update_file` to upload file content.
+
+The Drive API does not allow for partial modifications or appending data directly on
+the server. To achieve this, the entire file must first be downloaded from the
+server. After downloading, any alterations or additions are made locally.
+Once these modifications are complete, the updated file must be uploaded in its
+entirety back to the server, effectively replacing the original file.
+
+This approach ensures data integrity, but it might not be bandwidth-efficient,
+especially for large files.
+
+[examples/file_upload_content](https://github.com/main-branch/drive_v3/blob/main/examples/file_upload_content)
+shows how to overwrite a file's content.
+
+### ✅︎ Download file data
+
+Use `drive_service.get_file` to download file content.
+
+[examples/file_download_content](https://github.com/main-branch/drive_v3/blob/main/examples/file_download_content)
+shows how to download a file's content.
+
+### ✅︎ Export file
+
+To export Google Workspace document, use the `files.export` method with
+the ID of the file to export and the correct MIME type. Exported content is limited
+to 10 MB.
+
+See [Export MIME types for Google Workspace documents](https://developers.google.com/drive/api/guides/ref-export-formats)
+for a list of possible MIME types for each document type.
+
+See [examples/file_export_spreasheet](https://github.com/main-branch/drive_v3/blob/main/examples/file_export_spreadsheet)
+for an example of how to export a spreadsheet to a PDF.
+
+### ✅︎ Send file to trash
+
+To send a file to the trash, use `drive_service.update_file` to set the `trashed`
+file attribute to `true`.
+
+[examples/file_send_to_trash](https://github.com/main-branch/drive_v3/blob/main/examples/file_send_to_trash)
+shows how to send a file to the trash.
+
+### ✅︎ Recover file from trash
+
+To recover a file from the trash, use `drive_service.update_file` to set the `trashed`
+file attribute to `false`.
+
+[examples/file_recover_from_trash](https://github.com/main-branch/drive_v3/blob/main/examples/file_recover_from_trash)
+shows how to recover a file from the trash.
+
+### ✅︎ Delete a file
+
+Use `drive_service.delete_file` to delete a file without sending it to the trash.
+
+[examples/file_delete](https://github.com/main-branch/drive_v3/blob/main/examples/file_delete)
+shows how to delete a file.
+
+## Share files, folders, and drives
+
+Every Google Drive file, folder, and shared drive have associated
+[permission](https://developers.google.com/drive/api/v3/reference/permissions)
+resources. Each resource identifies the permission for a specific `type` (user, group,
+domain, anyone) and `role`, such as "commenter" or "reader." For example, a file might
+have a permission granting a specific user (`type=user`) read-only access (`role=reader`)
+while another permission grants members of a specific group (`type=group`) the ability
+to add comments to a file (`role=commenter`).
+
+For a complete list of roles and the operations permitted by each, refer to
+[Roles & permissions-(https://developers.google.com/drive/api/guides/ref-roles).
+
+### ✅︎ Create permission
+
+Use `drive_service.create_permission` to create a permission on a file.
+
+[examples/permission_create](https://github.com/main-branch/drive_v3/blob/main/examples/permission_create)
+shows how to create a permission for a file.
+
+### ✅︎ List permissions
+
+Use `drive_service.list_permissions` to list the permissions on a file.
+
+[examples/permission_list](https://github.com/main-branch/drive_v3/blob/main/examples/permission_list)
+shows how to list the permissions for a file.
+
+### ✅︎ Update permission
+
+Use `drive_service.update_permission` to list the permissions on a file.
+
+[examples/permission_update](https://github.com/main-branch/drive_v3/blob/main/examples/permission_update)
+shows how to update a permissions for a file.
+
+### ✅︎ Delete permission
+
+Use `drive_service.delete_permission` to delete a permission for a file.
+
+[examples/permission_delete](https://github.com/main-branch/drive_v3/blob/main/examples/permission_delete)
+shows how to delete a permissions for a file.
+
+## Shortcuts
+
+https://developers.google.com/drive/api/guides/shortcuts
+
+### Create a shortcut to a file
+
+### Search for shortcuts
+
+## Other
+
+### File revisions
+
+### Store application-specific data
+
+### Manage file metadata
+
+### Manage comments and replies
+
+### Add custom file properties
+
+### Create a shortcut to a Drive file
+
+### Create a shortcut to app content
+
+### Protect file content from modification
+
+### Access link-shared files using resource keys
+
+## Handle changes
+
+### Identify which change log to track
+
+### Track changes for users and shared drives
+
+### Retrieve changes
+
+### Receive notifications for resource changes
+
+## Manage labels
+
+### Manage labels
+
+### Set label field
+
+### Unset label field
+
+### Remove label
+
+### List labels from file
+
+### Return specific labels from a file
+
+### Search by label or field

data/examples/drive_service_batch

@@ -0,0 +1,72 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# `batch` allows you to batch multiple requests into a single HTTP request
+#
+# See [Batching Requests](https://developers.google.com/drive/api/v3/batch)
+#
+# ```Ruby
+# drive_service.batch do |service|
+#   service.some_method(...)
+#   service.some_other_method(...)
+# end
+# ```
+#
+# The `batch` method yields a service object that can be used to make requests.
+#
+# Requests made within the block are sent in a single network request to the server.
+# These requests are not performed within a transaction. If one request fails,
+# subsequent requests will still be executed.
+#
+# The `batch` method returns after all requests have been completed.
+#
+# The return value should be ignored.
+#
+# The service methods calls within the block return nil. To collect the results
+# of the requests, you must pass a block to the service method as follows:
+#
+# ```Ruby
+# results = [].tap do |results|
+#   drive_service.batch do |service|
+#   service.some_method(...) do |res, err|
+#     results << (res || err)
+#   end
+# end
+#
+
+require 'drive_v3'
+
+@spreadsheet_ids = %w[
+  1MNb_59W87lj75-9HqrEQoFBdrQiNl96rDlRy87sDIjs
+  1AG9PC6iGXRmezc5lcF9MX-tR4rR2lvEC6zZZ0AOnqLk
+  1bQlb77ID8_AL1F0hEiJVfit4YUpy3Nw-qLckwpWLCcI
+  BOGUS_ID
+]
+
+drive_service = DriveV3.drive_service
+
+permission = Google::Apis::DriveV3::Permission.new(
+  type: 'user',
+  email_address: 'jcouball@gmail.com',
+  role: 'writer'
+)
+
+begin
+  results = [].tap do |request_results|
+    drive_service.batch do |service|
+      @spreadsheet_ids.each do |spreadsheet_id|
+        # In the batch block, `create_permission` returns nil instead of the result
+        #
+        # Collect the result (or error if there is one) in the block passed to
+        # `create_permission`
+        service.create_permission(spreadsheet_id, permission) do |res, err|
+          request_results << (res || err.message)
+        end
+      end
+    end
+  end
+
+  puts "Permission created: #{results.pretty_inspect}"
+rescue StandardError => e
+  puts "An error occurred: #{e.message}"
+end

data/examples/file_create

@@ -0,0 +1,66 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Create a data file
+#
+# When creating a data file, upload_source should be an IO object that
+# responds to `read` and `size` (e.g. StringIO) or a string that names
+# an existing file to upload.
+
+require 'drive_v3'
+require 'json'
+
+drive_service = DriveV3.drive_service
+
+# If name is not specified as part of a create request, the file name is named
+# 'Untitled'.
+name = 'My data file'
+
+# If parents not specified as part of a create request or is an empty array, the
+# file is placed directly in the user's My Drive folder
+#
+# parents = ['id1', 'id2']
+parents = ['1V6RS_7_YgJmLDH-BDw3dpD8Np60Oi9ET']
+
+# The MIME type of the file. Drive will attempt to automatically detect an
+# appropriate value from uploaded content if no value is provided. The value
+# cannot be changed unless a new revision is uploaded.
+#
+# The default MIME type is 'text/plain'
+#
+# mime_type = nil
+mime_type = 'application/vnd.google-apps.spreadsheet'
+
+file_metadata = { name:, parents:, mime_type: }
+
+# If fields is not specified, the following default fields are returned:
+# id, name, kind, and mime_type. '*' can by used to return all fields.
+# See https://developers.google.com/drive/api/v3/reference/files#resource
+#
+fields = '*'
+
+# When creating the data file, upload_source should be an IO object that
+# responds to `read` and `size` (e.g. StringIO) or a string that names
+# an existing file to upload.
+#
+# If upload_source is not specified, the file will be created as an empty
+# data file.
+#
+# upload_source = StringIO.new("This is my letter to the World\nThat never wrote to Me")
+upload_source = StringIO.new("1,2,3\n4,5,6\n7,8,9")
+
+# Content type indicates the MIME type of the upload_source. If not specified,
+# the content type will be determined by calling MIME::Types.of with the
+# upload_source's filename.
+#
+# content_type = 'text/plain'
+# CSV content type
+# content_type = nil
+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}"
+end

data/examples/file_create_folder

@@ -0,0 +1,46 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Create a folder
+#
+# When creating a Google Drive folder, you create a file with a MIME type of
+# 'application/vnd.google-apps.folder' and a name. You can also specify the
+# folder's parent folder(s) and other metadata.
+
+require 'drive_v3'
+require 'json'
+
+drive_service = DriveV3.drive_service
+
+# If name is not specified as part of a create request, the file name is named
+# 'Untitled'.
+name = 'My New Folder'
+
+# If parents not specified as part of a create request or is an empty array, the
+# folder is placed directly in the user's My Drive folder
+#
+# parents = ['id1', 'id2']
+parents = []
+
+# The MIME type of the file. Drive will attempt to automatically detect an
+# appropriate value from uploaded content if no value is provided. The value
+# cannot be changed unless a new revision is uploaded.
+#
+# A folder MIME type is 'application/vnd.google-apps.folder'
+#
+mime_type = 'application/vnd.google-apps.folder'
+
+# If fields is not specified, the following default fields are returned:
+# id, name, kind, and mime_type. '*' can by used to return all fields.
+# See https://developers.google.com/drive/api/v3/reference/files#resource
+#
+fields = '*'
+
+file_metadata = { name:, parents:, mime_type: }
+
+begin
+  file = drive_service.create_file(file_metadata, fields:)
+  puts JSON.pretty_generate(file.to_h)
+rescue StandardError => e
+  puts "An error occurred: #{e.message}"
+end

data/examples/file_create_spreadsheet

@@ -0,0 +1,70 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Create a Google Sheets spreadsheet in Google Drive
+#
+# When creating a spreadsheet, you create a file with a MIME type of
+# 'application/vnd.google-apps.spreadsheet' and a name. You can also specify the
+# spreadsheet's parent folder and other metadata.
+#
+# The file_create method allows loading an Excel spreadheet or a sheet of data
+# from CSV or TSV data. Specify the data to load using `upload_source` and
+# `content_type` parameters. If `upload_source` is not specified, the file will
+# be created as an empty spreadsheet.
+
+require 'drive_v3'
+require 'json'
+
+drive_service = DriveV3.drive_service
+
+# If name is not specified as part of a create request, the file name is named
+# 'Untitled'.
+name = 'My spreadsheet file'
+
+# If parents not specified as part of a create request or is an empty array, the
+# file is placed directly in the user's My Drive folder
+#
+# parents = ['id1', 'id2']
+parents = []
+
+# The MIME type of the file. Drive will attempt to automatically detect an
+# appropriate value from uploaded content if no value is provided. The value
+# cannot be changed unless a new revision is uploaded.
+#
+# The default MIME type is 'text/plain'
+#
+# mime_type = nil
+mime_type = 'application/vnd.google-apps.spreadsheet'
+
+file_metadata = { name:, parents:, mime_type: }
+
+# If fields is not specified, the following default fields are returned:
+# id, name, kind, and mime_type. '*' can by used to return all fields.
+# See https://developers.google.com/drive/api/v3/reference/files#resource
+#
+fields = '*'
+
+# When creating the data file, upload_source should be an IO object that
+# responds to `read` and `size` (e.g. StringIO) or a string that names
+# an existing file to upload.
+#
+# If upload_source is not specified, the file will be created as an empty
+# data file.
+#
+upload_source = StringIO.new("1,2,3\n4,5,6\n7,8,9")
+
+# Content type indicates the MIME type of `upload_source`. If not specified,
+# the content type will be determined by calling MIME::Types.of with the
+# upload_source's filename.
+#
+# content_type = 'text/plain'
+# CSV content type
+# content_type = nil
+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}"
+end

data/examples/file_delete

@@ -0,0 +1,24 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Permanently delete a file without moving it 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 'Delete file...'
+  # Does not return anything
+  drive_service.delete_file(file_id)
+  puts 'Success'
+rescue StandardError => e
+  puts "An error occurred: #{e.message}"
+end