1# Getting Started 2 3This document provides all the basic information you need to start using the library. It covers important library concepts, shows examples for various use cases, and gives links to more information. 4 5## Setup 6 7There are a few setup steps you need to complete before you can use this library: 8 91. If you don't already have a Google account, [sign up](https://www.google.com/accounts). 102. If you have never created a Google APIs Console project, read the [Managing Projects page](http://developers.google.com/console/help/managing-projects) and create a project in the [Google API Console](https://console.developers.google.com/). 113. [Install](http://developers.google.com/api-client-library/python/start/installation) the library. 12 13## Authentication and authorization 14 15It is important to understand the basics of how API authentication and authorization are handled. All API calls must use either simple or authorized access (defined below). Many API methods require authorized access, but some can use either. Some API methods that can use either behave differently, depending on whether you use simple or authorized access. See the API's method documentation to determine the appropriate access type. 16 17### 1. Simple API access (API keys) 18 19These API calls do not access any private user data. Your application must authenticate itself as an application belonging to your Google Cloud project. This is needed to measure project usage for accounting purposes. 20 21**API key**: To authenticate your application, use an [API key](https://cloud.google.com/docs/authentication/api-keys) for your Google Cloud Console project. Every simple access call your application makes must include this key. 22 23> **Warning**: Keep your API key private. If someone obtains your key, they could use it to consume your quota or incur charges against your Google Cloud project. 24 25### 2. Authorized API access (OAuth 2.0) 26 27These API calls access private user data. Before you can call them, the user that has access to the private data must grant your application access. Therefore, your application must be authenticated, the user must grant access for your application, and the user must be authenticated in order to grant that access. All of this is accomplished with [OAuth 2.0](https://developers.google.com/identity/protocols/OAuth2) and libraries written for it. 28 29* **Scope**: Each API defines one or more scopes that declare a set of operations permitted. For example, an API might have read-only and read-write scopes. When your application requests access to user data, the request must include one or more scopes. The user needs to approve the scope of access your application is requesting. A list of accessible OAuth 2.0 scopes can be [found here](https://developers.google.com/identity/protocols/oauth2/scopes). 30* **Refresh and access tokens**: When a user grants your application access, the OAuth 2.0 authorization server provides your application with refresh and access tokens. These tokens are only valid for the scope requested. Your application uses access tokens to authorize API calls. Access tokens expire, but refresh tokens do not. Your application can use a refresh token to acquire a new access token. 31 32 > **Warning**: Keep refresh and access tokens private. If someone obtains your tokens, they could use them to access private user data. 33 34* **Client ID and client secret**: These strings uniquely identify your application and are used to acquire tokens. They are created for your Google Cloud project on the [API Access pane](https://console.developers.google.com/apis/credentials) of the Google Cloud. There are several types of client IDs, so be sure to get the correct type for your application: 35 36 * Web application client IDs 37 * Installed application client IDs 38 * [Service Account](https://developers.google.com/identity/protocols/OAuth2ServiceAccount) client IDs 39 40 > **Warning**: Keep your client secret private. If someone obtains your client secret, they could use it to consume your quota, incur charges against your Google Cloud project, and request access to user data. 41 42## Building and calling a service 43 44This section describes how to build an API-specific service object, make calls to the service, and process the response. 45 46### Build the service object 47 48Whether you are using simple or authorized API access, you use the [build()](http://googleapis.github.io/google-api-python-client/docs/epy/googleapiclient.discovery-module.html#build) function to create a service object. It takes an API name and API version as arguments. You can see the list of all API versions on the [Supported APIs](dyn/index.md) page. When `build()` is called, a service object will attempt to be constructed with methods specific to the given API. 49 50`httplib2`, the underlying transport library, makes all connections persistent by default. Use the service object with a context manager or call `close` to avoid leaving sockets open. 51 52 53```python 54from googleapiclient.discovery import build 55 56service = build('drive', 'v3') 57# ... 58service.close() 59``` 60 61```python 62from googleapiclient.discovery import build 63 64with build('drive', 'v3') as service: 65 # ... 66``` 67 68**Note**: Under the hood, the `build()` function retrieves a discovery artifact in order to construct the service object. If the `cache_discovery` argument of `build()` is set to `True`, the library will attempt to retrieve the discovery artifact from the legacy cache which is only supported with `oauth2client<4.0`. If the artifact is not available in the legacy cache and the `static_discovery` argument of `build()` is set to `True`, which is the default, the library will use the service definition shipped in the library. If always using the latest version of a service definition is more important than reliability, users should set `static_discovery=False` to retrieve the service definition from the internet. 69 70### Collections 71 72Each API service provides access to one or more resources. A set of resources of the same type is called a collection. The names of these collections are specific to the API. The service object is constructed with a function for every collection defined by the API. If the given API has a collection named `stamps`, you create the collection object like this: 73 74 75```python 76collection = service.stamps() 77``` 78 79It is also possible for collections to be nested: 80 81 82```python 83nested_collection = service.featured().stamps() 84``` 85 86### Methods and requests 87 88Every collection has a list of methods defined by the API. Calling a collection's method returns an [HttpRequest](http://google.github.io/google-api-python-client/docs/epy/googleapiclient.http.HttpRequest-class.html) object. If the given API collection has a method named `list` that takes an argument called `cents`, you create a request object for that method like this: 89 90```python 91request = collection.list(cents=5) 92``` 93 94### Execution and response 95 96Creating a request does not actually call the API. To execute the request and get a response, call the `execute()` function: 97 98```python 99try: 100 response = request.execute() 101except HttpError as e: 102 print('Error response status code : {0}, reason : {1}'.format(e.status_code, e.error_details)) 103``` 104 105Alternatively, you can combine previous steps on a single line: 106 107```python 108response = service.stamps().list(cents=5).execute() 109``` 110 111### Working with the response 112 113The response is a Python object built from the JSON response sent by the API server. The JSON structure is specific to the API; for details, see the API's reference documentation. You can also simply print the JSON to see the structure: 114 115```python 116import json 117... 118print(json.dumps(response, sort_keys=True, indent=4)) 119``` 120 121For example, if the printed JSON is the following: 122 123```json 124{ 125 "count": 2, 126 "items": [ 127 { 128 "cents": 5, 129 "name": "#586 1923-26 5-cent blue Theodore Roosevelt MLH perf 10" 130 }, 131 { 132 "cents": 5, 133 "name": "#628 1926 5-cent Ericsson Memorial MLH" 134 } 135 ] 136} 137``` 138 139You can access the data like this: 140 141```python 142print('Num 5 cent stamps: %d'.format(response['count'])) 143print('First stamp name: %s'.format(response['items'][0]['name'])) 144``` 145 146## Finding information about the APIs 147 148Use the [APIs Explorer](https://developers.google.com/apis-explorer/) to browse APIs, list available methods, and even try API calls from your browser. 149 150## Library reference documentation 151 152[Core library documentation](http://googleapis.github.io/google-api-python-client/docs/epy/index.html) 153and [Library reference documentation by API](dyn/index.md) are available. 154