The photos space will sunset in early January 2018. Your users can continue to access Google Photos via the drive space by enabling the Google Photos folder in My Drive in the Drive client settings

Batching Requests

This document shows how to batch API calls together to reduce the number of HTTP connections your client has to make.

This document is specifically about making a batch request by sending an HTTP request. If, instead, you're using a Google client library to make a batch request, see the client library's documentation.

Overview

Each HTTP connection that your client makes results in a certain amount of overhead. The Drive API supports batching, to allow your client to put several API calls into a single HTTP request.

Examples of situations when you might want to use batching:

  • Retrieving metadata for a large number of files.
  • Updating metadata or properties in bulk.
  • Changing permissions for a large number of files, such as adding a new user or group.
  • Synchronizing local client data for the first time or after being offline for an extended time.

In each case, instead of sending each call separately, you can group them together into a single HTTP request. You can even group requests for multiple users or multiple Google APIs.

You're limited to 100 calls in a single batch request. If you need to make more calls than that, use multiple batch requests.

Note: The batch system for the Drive API uses the same syntax as the OData batch processing system, but the semantics differ.

Note: Currently, Google Drive does not support batch operations for media, either for upload or download.

Batch details

A batch request consists of multiple API calls combined into one HTTP request. This section describes the batch syntax in detail; later, there's an example.

Note: A set of n requests batched together counts toward your usage limit as n requests, not as one request. The batch request is taken apart into a set of requests before processing.

Format of a batch request

A batch request is a single standard HTTP request containing multiple Drive API calls, using the multipart/mixed content type. Within that main HTTP request, each of the parts contains a nested HTTP request.

Each part begins with its own Content-Type: application/http HTTP header. It can also have an optional Content-ID header. However, the part headers are just there to mark the beginning of the part; they're separate from the nested request. After the server unwraps the batch request into separate requests, the part headers are ignored.

The body of each part is itself a complete HTTP request, with its own verb, URL, headers, and body. The HTTP request must only contain the path portion of the URL; full URLs are not allowed in batch requests.

The HTTP headers for the outer batch request, except for the Content- headers such as Content-Type, apply to every request in the batch. If you specify a given HTTP header in both the outer request and an individual call, then the individual call header's value overrides the outer batch request header's value. The headers for an individual call apply only to that call.

For example, if you provide an Authorization header for a specific call, then that header applies only to that call. If you provide an Authorization header for the outer request, then that header applies to all of the individual calls unless they override it with Authorization headers of their own.

When the server receives the batched request, it applies the outer request's query parameters and headers (as appropriate) to each part, and then treats each part as if it were a separate HTTP request.

Response to a batch request

The server's response is a single standard HTTP response with a multipart/mixed content type; each part is the response to one of the requests in the batched request, in the same order as the requests.

Like the parts in the request, each response part contains a complete HTTP response, including a status code, headers, and body. And like the parts in the request, each response part is preceded by a Content-Type header that marks the beginning of the part.

If a given part of the request had a Content-ID header, then the corresponding part of the response has a matching Content-ID header, with the original value preceded by the string response-, as shown in the following example.

Note: The server may perform your calls in any order. Don't count on their being executed in the order in which you specified them. If you want to ensure that two calls occur in a given order, you can't send them in a single request; instead, send the first one by itself, then wait for the response to the first one before sending the second one.

Example

The following example shows the use of batching with the Drive API.

Example batch request

POST https://www.googleapis.com/batch

Accept-Encoding: gzip
User-Agent: Google-HTTP-Java-Client/1.20.0 (gzip)
Content-Type: multipart/mixed; boundary=END_OF_PART
Content-Length: 963

--END_OF_PART Content-Length: 337 Content-Type: application/http content-id: 1 content-transfer-encoding: binary

POST https://www.googleapis.com/drive/v3/files/fileId/permissions?fields=id Authorization: Bearer authorization_token Content-Length: 70 Content-Type: application/json; charset=UTF-8

{ "emailAddress":"example@appsrocks.com", "role":"writer", "type":"user" } --END_OF_PART Content-Length: 353 Content-Type: application/http content-id: 2 content-transfer-encoding: binary

POST https://www.googleapis.com/drive/v3/files/fileId/permissions?fields=id&sendNotificationEmail=false Authorization: Bearer authorization_token Content-Length: 58 Content-Type: application/json; charset=UTF-8

{ "domain":"appsrocks.com", "role":"reader", "type":"domain" } --END_OF_PART--

Example batch response

This is the response to the example request in the previous section.

HTTP/1.1 200 OK
Alt-Svc: quic=":443"; p="1"; ma=604800
Server: GSE
Alternate-Protocol: 443:quic,p=1
X-Frame-Options: SAMEORIGIN
Content-Encoding: gzip
X-XSS-Protection: 1; mode=block
Content-Type: multipart/mixed; boundary=batch_6VIxXCQbJoQ_AATxy_GgFUk
Transfer-Encoding: chunked
X-Content-Type-Options: nosniff
Date: Fri, 13 Nov 2015 19:28:59 GMT
Cache-Control: private, max-age=0
Vary: X-Origin
Vary: Origin
Expires: Fri, 13 Nov 2015 19:28:59 GMT

--batch_6VIxXCQbJoQ_AATxy_GgFUk Content-Type: application/http Content-ID: response-1

HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 Date: Fri, 13 Nov 2015 19:28:59 GMT Expires: Fri, 13 Nov 2015 19:28:59 GMT Cache-Control: private, max-age=0 Content-Length: 35

{ "id": "12218244892818058021i" }

--batch_6VIxXCQbJoQ_AATxy_GgFUk Content-Type: application/http Content-ID: response-2

HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 Date: Fri, 13 Nov 2015 19:28:59 GMT Expires: Fri, 13 Nov 2015 19:28:59 GMT Cache-Control: private, max-age=0 Content-Length: 35

{ "id": "04109509152946699072k" }

--batch_6VIxXCQbJoQ_AATxy_GgFUk--

Using client libraries

The following code samples demonstrate how to make batch requests using the Google APIs client libraries. See the respective quickstart guides for more information on how to install the libraries and set them up.

Java

String fileId = "1sTWaJ_j7PkjzaBWtNc3IzovK5hQf21FbOw9yLeeLPNQ";
JsonBatchCallback<Permission> callback = new JsonBatchCallback<Permission>() {
  @Override
  public void onFailure(GoogleJsonError e,
                        HttpHeaders responseHeaders)
      throws IOException {
    // Handle error
    System.err.println(e.getMessage());
  }

  @Override
  public void onSuccess(Permission permission,
                        HttpHeaders responseHeaders)
      throws IOException {
    System.out.println("Permission ID: " + permission.getId());
  }
};
BatchRequest batch = driveService.batch();
Permission userPermission = new Permission()
    .setType("user")
    .setRole("writer")
    .setEmailAddress("user@example.com");
driveService.permissions().create(fileId, userPermission)
    .setFields("id")
    .queue(batch, callback);

Permission domainPermission = new Permission()
    .setType("domain")
    .setRole("reader")
    .setDomain("example.com");
driveService.permissions().create(fileId, domainPermission)
    .setFields("id")
    .queue(batch, callback);

batch.execute();

Python

file_id = '1sTWaJ_j7PkjzaBWtNc3IzovK5hQf21FbOw9yLeeLPNQ'
def callback(request_id, response, exception):
    if exception:
        # Handle error
        print exception
    else:
        print "Permission Id: %s" % response.get('id')

batch = drive_service.new_batch_http_request(callback=callback)
user_permission = {
    'type': 'user',
    'role': 'writer',
    'emailAddress': 'user@example.com'
}
batch.add(drive_service.permissions().create(
        fileId=file_id,
        body=user_permission,
        fields='id',
))
domain_permission = {
    'type': 'domain',
    'role': 'reader',
    'domain': 'example.com'
}
batch.add(drive_service.permissions().create(
        fileId=file_id,
        body=domain_permission,
        fields='id',
))
batch.execute()

PHP

$fileId = '1sTWaJ_j7PkjzaBWtNc3IzovK5hQf21FbOw9yLeeLPNQ';
$driveService->getClient()->setUseBatch(true);
try {
    $batch = $driveService->createBatch();

    $userPermission = new Google_Service_Drive_Permission(array(
        'type' => 'user',
        'role' => 'writer',
        'emailAddress' => 'user@example.com'
    ));
    $request = $driveService->permissions->create(
        $fileId, $userPermission, array('fields' => 'id'));
    $batch->add($request, 'user');
    $domainPermission = new Google_Service_Drive_Permission(array(
        'type' => 'domain',
        'role' => 'reader',
        'domain' => 'example.com'
    ));
    $request = $driveService->permissions->create(
        $fileId, $domainPermission, array('fields' => 'id'));
    $batch->add($request, 'domain');
    $results = $batch->execute();

    foreach ($results as $result) {
        if ($result instanceof Google_Service_Exception) {
            // Handle error
            printf($result);
        } else {
            printf("Permission ID: %s\n", $result->id);
        }
    }
} finally {
    $driveService->getClient()->setUseBatch(false);
}

.NET

var fileId = "1sTWaJ_j7PkjzaBWtNc3IzovK5hQf21FbOw9yLeeLPNQ";
var batch = new BatchRequest(driveService);
BatchRequest.OnResponse<Permission> callback = delegate (
    Permission permission,
    RequestError error,
    int index,
    System.Net.Http.HttpResponseMessage message)
{
    if (error != null)
    {
        // Handle error
        Console.WriteLine(error.Message);
    }
    else
    {
        Console.WriteLine("Permission ID: " + permission.Id);
    }
};
Permission userPermission = new Permission()
{
    Type = "user",
    Role = "writer",
    EmailAddress = "user@example.com"
};
var request = driveService.Permissions.Create(userPermission, fileId);
request.Fields = "id";
batch.Queue(request, callback);

Permission domainPermission = new Permission()
{
    Type = "domain",
    Role = "reader",
    Domain = "example.com"
};
request = driveService.Permissions.Create(domainPermission, fileId);
request.Fields = "id";
batch.Queue(request, callback);
var task = batch.ExecuteAsync();

Ruby

file_id = '1sTWaJ_j7PkjzaBWtNc3IzovK5hQf21FbOw9yLeeLPNQ'
callback = lambda do |res, err|
  if err
    # Handle error...
    puts err.body
  else
    puts "Permission ID: #{res.id}"
  end
end
drive_service.batch do |service|
  user_permission = {
      type: 'user',
      role: 'writer',
      email_address: 'user@example.com'
  }
  service.create_permission(file_id,
                            user_permission,
                            fields: 'id',
                            &callback)
  domain_permission = {
      type: 'domain',
      role: 'reader',
      domain: 'example.com'
  }
  service.create_permission(file_id,
                            domain_permission,
                            fields: 'id',
                            &callback)
end

Node.js

var fileId = '1sTWaJ_j7PkjzaBWtNc3IzovK5hQf21FbOw9yLeeLPNQ';
var permissions = [
  {
    'type': 'user',
    'role': 'writer',
    'emailAddress': 'user@example.com'
  }, {
    'type': 'domain',
    'role': 'writer',
    'domain': 'example.com'
  }
];
// Using the NPM module 'async'
async.eachSeries(permissions, function (permission, permissionCallback) {
  drive.permissions.create({
    resource: permission,
    fileId: fileId,
    fields: 'id',
  }, function (err, res) {
    if (err) {
      // Handle error...
      console.error(err);
      permissionCallback(err);
    } else {
      console.log('Permission ID: ', res.id)
      permissionCallback();
    }
  });
}, function (err) {
  if (err) {
    // Handle error
    console.error(err);
  } else {
    // All permissions inserted
  }
});

Objective-C

NSString *fileId = @"1sTWaJ_j7PkjzaBWtNc3IzovK5hQf21FbOw9yLeeLPNQ";
GTLRBatchQuery *batchQuery = [GTLRBatchQuery batchQuery];

GTLRDrive_Permission *userPermission = [GTLRDrive_Permission object];
userPermission.type = @"user";
userPermission.role = @"writer";
userPermission.emailAddress = @"user@example.com";
GTLRDriveQuery_PermissionsCreate *createUserPermission =
    [GTLRDriveQuery_PermissionsCreate queryWithObject:userPermission
                                               fileId:fileId];
createUserPermission.fields = @"id";
createUserPermission.completionBlock = ^(GTLRServiceTicket *ticket,
                           GTLRDrive_Permission *permission,
                           NSError *error) {
    if (error == nil) {
        NSLog(@"Permisson ID: %@", permission.identifier);
    } else {
        NSLog(@"An error occurred: %@", error);
    }

};
[batchQuery addQuery:createUserPermission];

GTLRDrive_Permission *domainPermission = [GTLRDrive_Permission object];
domainPermission.type = @"domain";
domainPermission.role = @"reader";
domainPermission.domain = @"example.com";

GTLRDriveQuery_PermissionsCreate *createDomainPermission =
    [GTLRDriveQuery_PermissionsCreate queryWithObject:domainPermission
                                               fileId:fileId];
createDomainPermission.fields = @"id";
createDomainPermission.completionBlock = ^(GTLRServiceTicket *ticket,
                           GTLRDrive_Permission *permission,
                           NSError *error) {
    if (error == nil) {
        NSLog(@"Permisson ID: %@", permission.identifier);
    } else {
        NSLog(@"An error occurred: %@", error);
    }
};
[batchQuery addQuery:createDomainPermission];

[driveService executeQuery:batchQuery completionHandler:^(GTLRServiceTicket *ticket,
                                                     GTLRBatchResult *batchResult,
                                                     NSError *error) {
    if (error) {
        NSLog(@"An error occurred: %@", error);
    }
}];

发送以下问题的反馈:

此网页
Drive REST API
Drive REST API