googleapiclient.discovery

module documentation

Client for discovery based APIs.

A client library for Google's discovery based APIs.

Class	`Resource`	A class for interacting with a resource.
Class	`ResourceMethodParameters`	Represents the parameters associated with a method.
Exception	`APICoreVersionError`	Undocumented
Function	`build`	Construct a Resource for interacting with an API.
Function	`build_from_document`	Create a Resource for interacting with an API.
Function	`createMethod`	Creates a method for attaching to a Resource.
Function	`createNextMethod`	Creates any _next methods for attaching to a Resource.
Function	`fix_method_name`	Fix method names to avoid '$' characters and reserved word conflicts.
Function	`key2param`	Converts key names into parameter names.
Constant	`BODY_PARAMETER_DEFAULT_VALUE`	Undocumented
Constant	`DEFAULT_METHOD_DOC`	Undocumented
Constant	`DEFAULT_UNIVERSE`	Undocumented
Constant	`DISCOVERY_URI`	Undocumented
Constant	`GOOGLE_API_USE_CLIENT_CERTIFICATE`	Undocumented
Constant	`GOOGLE_API_USE_MTLS_ENDPOINT`	Undocumented
Constant	`GOOGLE_CLOUD_UNIVERSE_DOMAIN`	Undocumented
Constant	`HTTP_PAYLOAD_METHODS`	Undocumented
Constant	`MEDIA_BODY_PARAMETER_DEFAULT_VALUE`	Undocumented
Constant	`MEDIA_MIME_TYPE_PARAMETER_DEFAULT_VALUE`	Undocumented
Constant	`RESERVED_WORDS`	Undocumented
Constant	`STACK_QUERY_PARAMETER_DEFAULT_VALUE`	Undocumented
Constant	`STACK_QUERY_PARAMETERS`	Undocumented
Constant	`URITEMPLATE`	Undocumented
Constant	`V2_DISCOVERY_URI`	Undocumented
Constant	`VARNAME`	Undocumented
Variable	`__author__`	Undocumented
Variable	`HAS_UNIVERSE`	Undocumented
Variable	`logger`	Undocumented
Class	`_BytesGenerator`	Undocumented
Function	`_cast`	Convert value to a string based on JSON Schema type.
Function	`_check_api_core_compatible_with_credentials_universe`	Undocumented
Function	`_discovery_service_uri_options`	Returns Discovery URIs to be used for attempting to build the API Resource.
Function	`_findPageTokenName`	Search field names for one like a page token.
Function	`_fix_up_media_path_base_url`	Update the media upload base url if its netloc doesn't match base url netloc.
Function	`_fix_up_media_upload`	Adds 'media_body' and 'media_mime_type' parameters if supported by method.
Function	`_fix_up_method_description`	Updates a method description in a discovery document.
Function	`_fix_up_parameters`	Updates parameters of an API method with values specific to this library.
Function	`_media_path_url_from_info`	Creates an absolute media path URL.
Function	`_media_size_to_long`	Convert a string media size, such as 10GB or 3TB into an integer.
Function	`_methodProperties`	Get properties of a field in a method description.
Function	`_retrieve_discovery_doc`	Retrieves the discovery_doc from cache or the internet.
Function	`_urljoin`	Custom urljoin replacement supporting : before / in url.
Constant	`_MEDIA_SIZE_BIT_SHIFTS`	Undocumented
Constant	`_PAGE_TOKEN_NAMES`	Undocumented

@positional(2)
def build(serviceName, version, http=None, discoveryServiceUrl=None, developerKey=None, model=None, requestBuilder=HttpRequest, credentials=None, cache_discovery=True, cache=None, client_options=None, adc_cert_path=None, adc_key_path=None, num_retries=1, static_discovery=None, always_use_jwt_access=False): ¶

Construct a Resource for interacting with an API.

Construct a Resource object for interacting with an API. The serviceName and version are the names from the Discovery service.

Parameters
serviceName	string, name of the service.
version	string, the version of the service.
http	httplib2.Http, An instance of httplib2.Http or something that acts like it that HTTP requests will be made through.
discoveryServiceUrl	string, a URI Template that points to the location of the discovery service. It should have two parameters {api} and {apiVersion} that when filled in produce an absolute URI to the discovery document for that service.
developerKey	string, key obtained from https://code.google.com/apis/console.
model	googleapiclient.Model, converts to and from the wire format.
requestBuilder	googleapiclient.http.HttpRequest, encapsulator for an HTTP request.
credentials	oauth2client.Credentials or google.auth.credentials.Credentials, credentials to be used for authentication.
cache_discovery	Boolean, whether or not to cache the discovery doc.
cache	googleapiclient.discovery_cache.base.CacheBase, an optional cache object for the discovery documents.
client_options	Mapping object or google.api_core.client_options, client options to set user options on the client. (1) The API endpoint should be set through client_options. If API endpoint is not set, `GOOGLE_API_USE_MTLS_ENDPOINT` environment variable can be used to control which endpoint to use. (2) client_cert_source is not supported, client cert should be provided using client_encrypted_cert_source instead. In order to use the provided client cert, `GOOGLE_API_USE_CLIENT_CERTIFICATE` environment variable must be set to `true`. More details on the environment variables are here: https://google.aip.dev/auth/4114
adc_cert_path	str, client certificate file path to save the application default client certificate for mTLS. This field is required if you want to use the default client certificate. `GOOGLE_API_USE_CLIENT_CERTIFICATE` environment variable must be set to `true` in order to use this field, otherwise this field doesn't nothing. More details on the environment variables are here: https://google.aip.dev/auth/4114
adc_key_path	str, client encrypted private key file path to save the application default client encrypted private key for mTLS. This field is required if you want to use the default client certificate. `GOOGLE_API_USE_CLIENT_CERTIFICATE` environment variable must be set to `true` in order to use this field, otherwise this field doesn't nothing. More details on the environment variables are here: https://google.aip.dev/auth/4114
num_retries	Integer, number of times to retry discovery with randomized exponential backoff in case of intermittent/connection issues.
static_discovery	Boolean, whether or not to use the static discovery docs included in the library. The default value for `static_discovery` depends on the value of `discoveryServiceUrl`. `static_discovery` will default to `True` when `discoveryServiceUrl` is also not provided, otherwise it will default to `False`.
always_use_jwt_access	Boolean, whether always use self signed JWT for service account credentials. This only applies to google.oauth2.service_account.Credentials.
Returns
A Resource object with methods for interacting with the service.
Raises
`google.auth.exceptions.MutualTLSChannelError`	if there are any problems setting up mutual TLS channel.

@positional(1)
def build_from_document(service, base=None, future=None, http=None, developerKey=None, model=None, requestBuilder=HttpRequest, credentials=None, client_options=None, adc_cert_path=None, adc_key_path=None, always_use_jwt_access=False): ¶

Create a Resource for interacting with an API.

Same as build(), but constructs the Resource object from a discovery document that is it given, as opposed to retrieving one over HTTP.

Parameters
service	string or object, the JSON discovery document describing the API. The value passed in may either be the JSON string or the deserialized JSON.
base	string, base URI for all HTTP requests, usually the discovery URI. This parameter is no longer used as rootUrl and servicePath are included within the discovery document. (deprecated)
future	string, discovery document with future capabilities (deprecated).
http	httplib2.Http, An instance of httplib2.Http or something that acts like it that HTTP requests will be made through.
developerKey	string, Key for controlling API usage, generated from the API Console.
model	Model class instance that serializes and de-serializes requests and responses.
requestBuilder	Takes an http request and packages it up to be executed.
credentials	oauth2client.Credentials or google.auth.credentials.Credentials, credentials to be used for authentication.
client_options	Mapping object or google.api_core.client_options, client options to set user options on the client. (1) The API endpoint should be set through client_options. If API endpoint is not set, `GOOGLE_API_USE_MTLS_ENDPOINT` environment variable can be used to control which endpoint to use. (2) client_cert_source is not supported, client cert should be provided using client_encrypted_cert_source instead. In order to use the provided client cert, `GOOGLE_API_USE_CLIENT_CERTIFICATE` environment variable must be set to `true`. More details on the environment variables are here: https://google.aip.dev/auth/4114
adc_cert_path	str, client certificate file path to save the application default client certificate for mTLS. This field is required if you want to use the default client certificate. `GOOGLE_API_USE_CLIENT_CERTIFICATE` environment variable must be set to `true` in order to use this field, otherwise this field doesn't nothing. More details on the environment variables are here: https://google.aip.dev/auth/4114
adc_key_path	str, client encrypted private key file path to save the application default client encrypted private key for mTLS. This field is required if you want to use the default client certificate. `GOOGLE_API_USE_CLIENT_CERTIFICATE` environment variable must be set to `true` in order to use this field, otherwise this field doesn't nothing. More details on the environment variables are here: https://google.aip.dev/auth/4114
always_use_jwt_access	Boolean, whether always use self signed JWT for service account credentials. This only applies to google.oauth2.service_account.Credentials.
Returns
A Resource object with methods for interacting with the service.
Raises
`google.auth.exceptions.MutualTLSChannelError`	if there are any problems setting up mutual TLS channel.

def createMethod(methodName, methodDesc, rootDesc, schema): ¶

Creates a method for attaching to a Resource.

Parameters
methodName	string, name of the method to use.
methodDesc	object, fragment of deserialized discovery document that describes the method.
rootDesc	object, the entire deserialized discovery document.
schema	object, mapping of schema names to schema descriptions.

def createNextMethod(methodName, pageTokenName='pageToken', nextPageTokenName='nextPageToken', isPageTokenParameter=True): ¶

Creates any _next methods for attaching to a Resource.

The _next methods allow for easy iteration through list() responses.

Parameters
methodName	string, name of the method to use.
pageTokenName	string, name of request page token field.
nextPageTokenName	string, name of response page token field.
isPageTokenParameter	Boolean, True if request page token is a query parameter, False if request page token is a field of the request body.

def fix_method_name(name): ¶

Fix method names to avoid '$' characters and reserved word conflicts.

Parameters
name	string, method name.
Returns
The name with '_' appended if the name is a reserved word and '$' and '-' replaced with '_'.

def key2param(key): ¶

Converts key names into parameter names.

For example, converting "max-results" -> "max_results"

Parameters
key	string, the method key name.
Returns
A safe method name based on the key name.

BODY_PARAMETER_DEFAULT_VALUE: dict[str, str] = ¶

Undocumented

Value

{'description': 'The request body.', 'type': 'object'}

DEFAULT_METHOD_DOC: str = ¶

Undocumented

Value

'A description of how to use this function'

DEFAULT_UNIVERSE: str = ¶

Undocumented

Value

'googleapis.com'

DISCOVERY_URI: str = ¶

Undocumented

Value

'https://www.googleapis.com/discovery/v1/apis/{api}/{apiVersion}/rest'

GOOGLE_API_USE_CLIENT_CERTIFICATE: str = ¶

Undocumented

Value

'GOOGLE_API_USE_CLIENT_CERTIFICATE'

GOOGLE_API_USE_MTLS_ENDPOINT: str = ¶

Undocumented

Value

'GOOGLE_API_USE_MTLS_ENDPOINT'

GOOGLE_CLOUD_UNIVERSE_DOMAIN: str = ¶

Undocumented

Value

'GOOGLE_CLOUD_UNIVERSE_DOMAIN'

HTTP_PAYLOAD_METHODS = ¶

Undocumented

Value

frozenset(['PUT', 'POST', 'PATCH'])

MEDIA_BODY_PARAMETER_DEFAULT_VALUE: dict = ¶

Undocumented

Value

{'description': 'The filename of the media request body, or an instance of a Med↵
iaUpload object.',
 'type': 'string',
 'required': False}

MEDIA_MIME_TYPE_PARAMETER_DEFAULT_VALUE: dict = ¶

Undocumented

Value

{'description': 'The MIME type of the media request body, or an instance of a Me↵
diaUpload object.',
 'type': 'string',
 'required': False}

RESERVED_WORDS = ¶

Undocumented

Value

frozenset(['body'])

STACK_QUERY_PARAMETER_DEFAULT_VALUE: dict[str, str] = ¶

Undocumented

Value

{'type': 'string', 'location': 'query'}

STACK_QUERY_PARAMETERS = ¶

Undocumented

Value

frozenset(['trace', 'pp', 'userip', 'strict'])

URITEMPLATE = ¶

Undocumented

Value

re.compile(r'\{[^\}]*\}')

V2_DISCOVERY_URI: str = ¶

Undocumented

Value

'https://{api}.googleapis.com/$discovery/rest?version={apiVersion}'

VARNAME = ¶

Undocumented

Value

re.compile(r'[a-zA-Z0-9_-]+')

__author__: str = ¶

Undocumented

HAS_UNIVERSE: bool = ¶

Undocumented

logger = ¶

Undocumented

def _cast(value, schema_type): ¶

Convert value to a string based on JSON Schema type.

See http://tools.ietf.org/html/draft-zyp-json-schema-03 for more details on JSON Schema.

Parameters
value	any, the value to convert
schema_type	string, the type that value should be interpreted as
Returns
A string representation of 'value' based on the schema_type.

def _check_api_core_compatible_with_credentials_universe(credentials): ¶

Undocumented

def _discovery_service_uri_options(discoveryServiceUrl, version): ¶

Returns Discovery URIs to be used for attempting to build the API Resource.

Parameters
discoveryServiceUrl	string, the Original Discovery Service URL preferred by the customer.
version	string, API Version requested
Returns
A list of URIs to be tried for the Service Discovery, in order.

def _findPageTokenName(fields): ¶

Search field names for one like a page token.

Parameters
fields	container of string, names of fields.
Returns
First name that is either 'pageToken' or 'nextPageToken' if one exists, otherwise None.

def _fix_up_media_path_base_url(media_path_url, base_url): ¶

Update the media upload base url if its netloc doesn't match base url netloc.

This can happen in case the base url was overridden by client_options.api_endpoint.

Parameters
media_path_url	String; the absolute URI for media upload.
base_url	string, base URL for the API. All requests are relative to this URI.
Returns
String; the absolute URI for media upload.

def _fix_up_media_upload(method_desc, root_desc, path_url, parameters): ¶

Adds 'media_body' and 'media_mime_type' parameters if supported by method.

SIDE EFFECTS: If there is a 'mediaUpload' in the method description, adds 'media_upload' key to parameters.

Parameters
method_desc	Dictionary with metadata describing an API method. Value comes from the dictionary of methods stored in the 'methods' key in the deserialized discovery document.
root_desc	Dictionary; the entire original deserialized discovery document.
path_url	String; the relative URL for the API method. Relative to the API root, which is specified in the discovery document.
parameters	A dictionary describing method parameters for method described in method_desc.
Returns
Triple(`accept`, `max_size`, `media_path_url)` where	accept is a list of strings representing what content types are accepted for media upload. Defaults to empty list if not in the discovery document. max_size is a long representing the max size in bytes allowed for a media upload. Defaults to 0L if not in the discovery document. media_path_url is a String; the absolute URI for media upload for the API method. Constructed using the API root URI and service path from the discovery document and the relative path for the API method. If media upload is not supported, this is None.

def _fix_up_method_description(method_desc, root_desc, schema): ¶

Updates a method description in a discovery document.

SIDE EFFECTS: Changes the parameters dictionary in the method description with extra parameters which are used locally.

Parameters
method_desc	Dictionary with metadata describing an API method. Value comes from the dictionary of methods stored in the 'methods' key in the deserialized discovery document.
root_desc	Dictionary; the entire original deserialized discovery document.
schema	Object, mapping of schema names to schema descriptions.
Returns
Tuple(`path_url`, `http_method`, `method_id`, `accept`, `max_size`, `media_path_url)`	where: path_url is a String; the relative URL for the API method. Relative to the API root, which is specified in the discovery document. http_method is a String; the HTTP method used to call the API method described in the method description. method_id is a String; the name of the RPC method associated with the API method, and is in the method description in the 'id' key. accept is a list of strings representing what content types are accepted for media upload. Defaults to empty list if not in the discovery document. max_size is a long representing the max size in bytes allowed for a media upload. Defaults to 0L if not in the discovery document. media_path_url is a String; the absolute URI for media upload for the API method. Constructed using the API root URI and service path from the discovery document and the relative path for the API method. If media upload is not supported, this is None.

def _fix_up_parameters(method_desc, root_desc, http_method, schema): ¶

Updates parameters of an API method with values specific to this library.

Specifically, adds whatever global parameters are specified by the API to the parameters for the individual method. Also adds parameters which don't appear in the discovery document, but are available to all discovery based APIs (these are listed in STACK_QUERY_PARAMETERS).

SIDE EFFECTS: This updates the parameters dictionary object in the method description.

Parameters
method_desc	Dictionary with metadata describing an API method. Value comes from the dictionary of methods stored in the 'methods' key in the deserialized discovery document.
root_desc	Dictionary; the entire original deserialized discovery document.
http_method	String; the HTTP method used to call the API method described in method_desc.
schema	Object, mapping of schema names to schema descriptions.
Returns
The updated Dictionary stored in the 'parameters' key of the method description dictionary.

def _media_path_url_from_info(root_desc, path_url): ¶

Creates an absolute media path URL.

Constructed using the API root URI and service path from the discovery document and the relative path for the API method.

Parameters
root_desc	Dictionary; the entire original deserialized discovery document.
path_url	String; the relative URL for the API method. Relative to the API root, which is specified in the discovery document.
Returns
String; the absolute URI for media upload for the API method.

def _media_size_to_long(maxSize): ¶

Convert a string media size, such as 10GB or 3TB into an integer.

Parameters
maxSize	string, size as a string, such as 2MB or 7GB.
Returns
The size as an integer value.

def _methodProperties(methodDesc, schema, name): ¶

Get properties of a field in a method description.

Parameters
methodDesc	object, fragment of deserialized discovery document that describes the method.
schema	object, mapping of schema names to schema descriptions.
name	string, name of top-level field in method description.
Returns
Object representing fragment of deserialized discovery document corresponding to 'properties' field of object corresponding to named field in method description, if it exists, otherwise empty dict.

def _retrieve_discovery_doc(url, http, cache_discovery, serviceName, version, cache=None, developerKey=None, num_retries=1, static_discovery=True): ¶

Retrieves the discovery_doc from cache or the internet.

Parameters
url	string, the URL of the discovery document.
http	httplib2.Http, An instance of httplib2.Http or something that acts like it through which HTTP requests will be made.
cache_discovery	Boolean, whether or not to cache the discovery doc.
serviceName	string, name of the service.
version	string, the version of the service.
cache	googleapiclient.discovery_cache.base.Cache, an optional cache object for the discovery documents.
developerKey	string, Key for controlling API usage, generated from the API Console.
num_retries	Integer, number of times to retry discovery with randomized exponential backoff in case of intermittent/connection issues.
static_discovery	Boolean, whether or not to use the static discovery docs included in the library.
Returns
A unicode string representation of the discovery document.

def _urljoin(base, url): ¶

Custom urljoin replacement supporting : before / in url.

_MEDIA_SIZE_BIT_SHIFTS: dict[str, int] = ¶

Undocumented

Value

{'KB': 10, 'MB': 20, 'GB': 30, 'TB': 40}

_PAGE_TOKEN_NAMES: tuple[str, ...] = ¶

Undocumented

Value

('pageToken', 'nextPageToken')