1# Batch
2
3Each HTTP connection that your application makes results in a certain amount of overhead.
4This library supports batching,
5to allow your application to put several API calls into a single HTTP request.
6Examples of situations when you might want to use batching:
7* You have many small requests to make and would like to minimize HTTP request overhead.
8* A user made changes to data while your application was offline,
9  so your application needs to synchronize its local data with the server
10  by sending a lot of updates and deletes.
11
12**Note**: You're limited to 1000 calls in a single batch request.
13If you need to make more calls than that, use multiple batch requests.
14
15**Note**: You cannot use a
16[media upload](/api-client-library/python/guide/media_upload)
17object in a batch request.
18
19## Details
20You create batch requests by calling `new_batch_http_request()` on your service
21object, which returns a
22[BatchHttpRequest](https://google.github.io/google-api-python-client/docs/epy/googleapiclient.http.BatchHttpRequest-class.html)
23object, and then calling `add()` for each request you want to execute.
24You may pass in a callback with each request that is called with the response to that request.
25The callback function arguments are:
26a unique request identifier for each API call,
27a response object which contains the API call response,
28and an exception object which may be set to an exception raised by the API call.
29After you've added the requests, you call `execute()` to make the requests.
30The `execute()` function blocks until all callbacks have been called.
31
32In the following code snippet,
33two API requests are batched to a single HTTP request,
34and each API request is supplied a callback:
35  <pre class="prettyprint">
36See below</pre>
37You can also supply a single callback that gets called for each response:
38
39  <pre class="prettyprint">See below</pre>
40
41The
42[add()](https://google.github.io/google-api-python-client/docs/epy/googleapiclient.http.BatchHttpRequest-class.html#add)
43method also allows you to supply a <code>request_id</code> parameter for each request.
44These IDs are provided to the callbacks.
45If you don't supply one, the library creates one for you.
46The IDs must be unique for each API request,
47otherwise `add()` raises an exception.
48
49If you supply a callback to both `new_batch_http_request()` and `add()`, they both get called.
50
51
52---
53
54```python
55def list_animals(request_id, response, exception):
56  if exception is not None:
57    # Do something with the exception
58    pass
59  else:
60    # Do something with the response
61    pass
62
63def list_farmers(request_id, response):
64  """Do something with the farmers list response."""
65  pass
66
67service = build('farm', 'v2')
68
69batch = service.new_batch_http_request()
70
71batch.add(service.animals().list(), callback=list_animals)
72batch.add(service.farmers().list(), callback=list_farmers)
73batch.execute()
74```
75
76```python
77
78def insert_animal(request_id, response, exception):
79  if exception is not None:
80    # Do something with the exception
81    pass
82  else:
83    # Do something with the response
84    pass
85
86service = build('farm', 'v2')
87
88batch = service.new_batch_http_request(callback=insert_animal)
89
90batch.add(service.animals().insert(name="sheep"))
91batch.add(service.animals().insert(name="pig"))
92batch.add(service.animals().insert(name="llama"))
93batch.execute()
94```
95