Package google.ads.fullcirclequery.v1

Index

FullCircleQuery

The Ads Data Hub Query API lets you use predefined queries to generate reports from your data in BigQuery joined with Google data. To use the API, you need to provide the name of the query, the applicable arguments for that query, and a destination table in your BigQuery shared dataset. A service account with access to Google data runs the query on your behalf and stores the results in the destination table. When the query finishes running, you can access the results through BigQuery.

ExecuteQuery

rpc ExecuteQuery(ExecuteQueryRequest) returns (QueryResponse)

Executes a query and returns when it is complete. This method can be used to run queries synchronously. This method is equivalent to a call to StartQuery followed by a call to WaitOperation using the operation id that was returned by StartQuery.

Authorization Scopes

Requires one of the following OAuth scopes:

  • https://www.googleapis.com/auth/adsdatahub
  • https://www.googleapis.com/auth/xapi.zoo
ListCustomers

rpc ListCustomers(ListCustomersRequest) returns (ListCustomersResponse)

Retrieves customers you are associated with.

Authorization Scopes

Requires one of the following OAuth scopes:

  • https://www.googleapis.com/auth/adsdatahub
  • https://www.googleapis.com/auth/xapi.zoo
ListQueries

rpc ListQueries(ListQueriesRequest) returns (ListQueriesResponse)

Retrieves every query that you have access to.

Authorization Scopes

Requires one of the following OAuth scopes:

  • https://www.googleapis.com/auth/adsdatahub
  • https://www.googleapis.com/auth/xapi.zoo
StartQuery

rpc StartQuery(StartQueryRequest) returns (Operation)

Executes a query asynchronously and writes the results to the specified destination table in your BigQuery shared dataset. The returned operation id (Operation.name) can be used to poll for status or wait for completion. When the query completes, Operation.result is populated wtih a QueryResponse message (the same one that ExecuteQuery would return).

Authorization Scopes

Requires one of the following OAuth scopes:

  • https://www.googleapis.com/auth/adsdatahub
  • https://www.googleapis.com/auth/xapi.zoo
WaitOperation

rpc WaitOperation(WaitOperationRequest) returns (QueryResponse)

Waits a given amount of time for a job to complete. If it does not complete within this time, sends a cancel request and returns an error.

Authorization Scopes

Requires one of the following OAuth scopes:

  • https://www.googleapis.com/auth/adsdatahub
  • https://www.googleapis.com/auth/xapi.zoo

ArgType

The list of acceptable argument types. When the query is run, the passed in argument value must conform to the given ArgType.

Enums
DATE Follows yyyy-MM-dd format.
NUMBER Double
TABLE BigQuery table name
NUMBER_LIST List of numbers
STRING String
STRING_LIST List of strings.

Customer

Represents a customer and its information.

Fields
customer_id

int64

Customer ID

customer_name

string

Descriptive name of the customer.

default_api_version

int32

The preferred version for requests from a Customer. Used to indicate that the customer may have access to a newer (beta) API.

ExecuteQueryRequest

Request to execute a query and wait for it to complete.

Fields
spec

QuerySpec

The query to execute.

dest_table

string

Destination table for query results. Format: "project:dataset.table_name". Your Ads Data Hub service account must have edit permissions for the dataset. If "project:dataset" is not specified, it defaults to your Ads Data Hub shared dataset.

timeout_ms

int64

Time to wait for the operation to complete. Default value is 10 seconds. If the operation does not complete within this time, a cancel request is sent. An explicit value of 0 is ignored; the default value of 10 seconds is used instead.

job_id

string

A job id that you supply. You can use this id to refererence your job at operations/job_id. If you omit this field, an id is generated by the server. If you have an existing job with this id, the result is an error.

ListCustomersRequest

Request to retrieve a list of you associated customers.

ListCustomersResponse

Response to a ListCustomers request. It will have customers that you has access to.

Fields
customers[]

Customer

List of customers for the request.

is_admin

bool

Indicates your admin status.

ListQueriesRequest

Request to retrieve list of available queries.

Fields
page_size

int32

Maximum number of results to be returned by the server.

page_token

string

When ListQueriesRequest was previously called and there were more than page_size results, use page_token to retrieve subsequent pages of results. The required token is provided as part of response from the previous query.

include_query

bool

If true, return saved queries as well as query names; otherwise, return query names only.

customer_id

int64

Retrieve queries belonging to this specified Customer

ListQueriesResponse

Response to a ListQueries request. Contains the queries that you have access to, sorted by query name.

Fields
queries[]

Query

Your available queries. The number of results returned is limited by the page_size parameter in ListQueriesRequest.

next_page_token

string

If page_size limit is reached and there are remaining queries to be retrieved, this is the token for the next ListQueries request. If this field is empty or null, then there are no more queries to retrieve.

Query

Returned when requested for a list of queries or a specific query.

Fields
query_name

string

Query's unique name.

query_string

string

Query text.

arguments

map<string, QueryArgument>

Any additional arguments expected by the query. Maps each argument name to its argument type.

is_global

bool

True if the query is defined as global; otherwise the query can be used only by a particular customer (or set of customers).

in_development

bool

This field defines whether a query is still in development. If it is in development, it should not be executable except by admin user.

QueryArgument

Information about a specific argument.

Fields
type
(deprecated)

ArgType

Type of argument.

param_type

string

Type of argument.

QueryResponse

Response for a completed query. If this response is returned, then the query completed without errors.

QuerySpec

The core of a request to execute a query: the query name and arguments.

Fields
query_name

string

The query's unique name.

start_date

string

The start date of the date range for the query.

end_date

string

The end date (inclusive) of the date range for the query.

arguments

map<string, string>

Any additional arguments expected by the query. Maps each argument name to its bound value.

full_circle_customer_id

int64

ID of customer as which this query should be run. May be absent if the user only has access to one customer account.

role_name

string

Name of role as which this query should be run. If absent, will use the default role for the customer.

StartQueryRequest

Request to start a query asynchronously and store results in your BigQuery shared dataset.

Fields
spec

QuerySpec

The query to execute.

dest_table

string

Destination table for query results. Format: "project:dataset.table_name". Your Ads Data Hub service account must have edit permissions for the dataset. If "project:dataset" is not specified, it defaults to your Ads Data Hub shared dataset.

job_id

string

A job id that you supply. You can use this id to refererence your job at operations/job_id. If you omit this field, an id is generated by the server. If you have an existing job with this id, the result is an error.

WaitOperationRequest

Request to wait for a running BigQuery job to complete.

Fields
name

string

The name of the operation resource.

timeout_ms

int64

Time to wait for the operation to complete. Default value is 10 seconds. If the operation does not complete within this time, a cancel request is sent. An explicit value of 0 is ignored; the default value of 10 seconds is used instead.