Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We鈥檒l occasionally send you account related emails.
Already on GitHub? Sign in to your account
feat: Add support for using static discovery documents #1109
feat: Add support for using static discovery documents #1109
Changes from all commits
4b8f07c
e953990
4fe4fec
cec0d4c
a55e09d
9b049bd
e4cf59c
ea0237a
356512f
a774407
18281da
cc2461d
b6b6dbb
770ab9f
3fa2160
File filter
Filter by extension
Conversations
Jump to
There are no files selected for viewing
Getting Started
This 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.
Setup
There are a few setup steps you need to complete before you can use this library:
Authentication and authorization
It 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.
1. Simple API access (API keys)
These 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.
API key: To authenticate your application, use an API key for your Google Cloud Console project. Every simple access call your application makes must include this key.
2. Authorized API access (OAuth 2.0)
These 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 and libraries written for it.
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.
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.
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 of the Google Cloud. There are several types of client IDs, so be sure to get the correct type for your application:
Building and calling a service
This section describes how to build an API-specific service object, make calls to the service, and process the response.
Build the service object
Whether you are using simple or authorized API access, you use the 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 page.
The service object isWhenbuild()
is called, a service object will attempt to be constructed with methods specific to the given API.httplib2
, the underlying transport library, makes all connections persistent by default. Use the service object with a context manager or callclose
to avoid leaving sockets open.Note: Under the hood, the
build()
function retrieves a discovery artifact in order to construct the service object. If thecache_discovery
argument ofbuild()
is set toTrue
, the library will attempt to retrieve the discovery artifact from the legacy cache which is only supported withoauth2client<4.0
. If the artifact is not available in the legacy cache and thestatic_discovery
argument ofbuild()
is set toTrue
, 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 setstatic_discovery=False
to retrieve the service definition from the internet.Collections
Each 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:It is also possible for collections to be nested:
Methods and requests
Every collection has a list of methods defined by the API. Calling a collection's method returns an HttpRequest object. If the given API collection has a method named
list
that takes an argument calledcents
, you create a request object for that method like this:Execution and response
Creating a request does not actually call the API. To execute the request and get a response, call the
execute()
function:Alternatively, you can combine previous steps on a single line:
Working with the response
The 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:
For example, if the printed JSON is the following:
You can access the data like this:
Finding information about the APIs
Use the APIs Explorer to browse APIs, list available methods, and even try API calls from your browser.
Library reference documentation
Core library documentation. and Library reference documentation by API. is available.