@google-cloud/nodejs-common 2.0.16-alpha → 2.1.0

package/README.md

@@ -18,10 +18,11 @@ and [Data Tasks Coordinator]. This library includes:
    - Google Ads click conversions upload
    - Google Ads customer match upload
    - Google Ads enhanced conversions upload
+   - Google Ads offline userdata job data upload
    - Google Ads conversions scheduled uploads based on Google Sheets
    - Measurement Protocol Google Analytics 4
 
-1. Wrapper for some Google APIs for reporting, mainly
+2. Wrapper for some Google APIs for reporting, mainly
    for [Data Tasks Coordinator]:
 
    - Google Ads reporting
@@ -31,7 +32,7 @@ and [Data Tasks Coordinator]. This library includes:
    - YouTube Data API
    - Ads Data Hub querying
 
-1. Utilities wrapper class for Google Cloud Products:
+3. Utilities wrapper class for Google Cloud Products:
 
    - **Firestore Access Object**: Firestore has two modes[[comparison]] which
      have different API. This class, with its two successors, offer a unified
@@ -66,7 +67,7 @@ and [Data Tasks Coordinator]. This library includes:
      an adapter to wrap a Node8 Cloud Functions into Node6 and Node8 compatible
      functions.~~ (This has been removed since v1.9.0)
 
-1. A share library for [Bash] to facilitate installation tasks.
+4. A share library for [Bash] to facilitate installation tasks.
 
 [gmp and google ads connector]: https://github.com/GoogleCloudPlatform/cloud-for-marketing/tree/master/marketing-analytics/activation/gmp-googleads-connector
 [data tasks coordinator]: https://github.com/GoogleCloudPlatform/cloud-for-marketing/tree/master/marketing-analytics/activation/data-tasks-coordinator

package/bin/google_ads.sh

@@ -15,7 +15,7 @@
 # limitations under the License.
 
 # Google Ads API version
-GOOGLE_ADS_API_VERSION=13
+GOOGLE_ADS_API_VERSION=16
 
 #######################################
 # Verify whether the current OAuth token, CID and developer token can work.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@google-cloud/nodejs-common",
-  "version": "2.0.16-alpha",
+  "version": "2.1.0",
   "description": "A NodeJs common library for solutions based on Cloud Functions",
   "author": "Google Inc.",
   "license": "Apache-2.0",

package/src/apis/base/ads_api_common.js

@@ -0,0 +1,116 @@
+// Copyright 2024 Google Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this fileAccessObject except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+/**
+ * @fileoverview Common functions for Google Ads and Search Ads API classes.
+ */
+
+'use strict';
+
+const { Transform } = require('stream');
+const {
+  extractObject,
+  changeObjectNamingFromLowerCamelToSnake,
+  getLogger,
+} = require('../../components/utils.js');
+
+/**
+ * Returns a integer format CID by removing dashes and spaces.
+ * @param {string} cid
+ * @return {string}
+ */
+function getCleanCid(cid) {
+  return cid.toString().trim().replace(/-/g, '');
+}
+
+const START_TAG = '"results":';
+const FIELD_MASK_TAG = '"fieldMask"';
+const END_TAG = '"requestId"';
+
+/**
+ * Generates a function that can convert a given JSON object to a JSON string
+ * with only specified fields(fieldMask), in specified naming convention.
+ * @param {string} fieldMask The 'fieldMask' string from response.
+ * @param {boolean=} snakeCase Whether or not output JSON in snake naming.
+ */
+function generateProcessFn(fieldMask, snakeCase = false) {
+  const extractor = extractObject(fieldMask.split(','));
+  return (originalObject) => {
+    const extracted = extractor(originalObject);
+    const generatedObject = snakeCase
+      ? changeObjectNamingFromLowerCamelToSnake(extracted) : extracted;
+    return JSON.stringify(generatedObject);
+  };
+};
+
+/**
+ * A stream.Transform that can extract properties and convert naming of the
+ * reponse of Google/Search Ads report from REST interface.
+ */
+class RestSearchStreamTransform extends Transform {
+
+  /**
+   * @constructor
+   * @param {boolean=} snakeCase Whether or not output JSON in snake naming.
+   */
+  constructor(snakeCase = false) {
+    super({ objectMode: true });
+    this.snakeCase = snakeCase;
+    this.chunks = [Buffer.from('')];
+    this.processFn; // The function to process a row of the report.
+    this.logger = getLogger('ADS.STREAM.T');
+    this.stopwatch = Date.now();
+  }
+
+  _transform(chunk, encoding, callback) {
+    const latest = Buffer.concat([this.chunks[this.chunks.length - 1], chunk]);
+    const endIndex = latest.indexOf(END_TAG);
+    if (endIndex > -1) {
+      this.chunks.push(chunk);
+      const rawString = Buffer.concat(this.chunks).toString();
+      const startIndex = rawString.indexOf(START_TAG) + START_TAG.length;
+      const maskIndex = rawString.lastIndexOf(FIELD_MASK_TAG);
+      if (!this.processFn) {
+        const fieldMask = rawString
+          .substring(maskIndex + FIELD_MASK_TAG.length, rawString.indexOf(END_TAG))
+          .split('"')[1];
+        this.logger.debug(`Got fieldMask: ${fieldMask}`);
+        this.processFn = generateProcessFn(fieldMask, this.snakeCase);
+      }
+      const resultsWithTailing = rawString.substring(startIndex, maskIndex);
+      const results = resultsWithTailing.substring(
+        0, resultsWithTailing.lastIndexOf(','));
+      const rows = JSON.parse(results);
+      const data = rows.map(this.processFn).join('\n') + '\n';
+      // Clear cached chunks.
+      this.chunks = [latest.subarray(latest.indexOf(END_TAG) + END_TAG.length)];
+
+      this.logger.debug(`Got ${rows.length} rows. Process time:`,
+        Date.now() - this.stopwatch);
+      this.stopwatch = Date.now();
+      callback(null, data);
+    } else {
+      if (chunk.length < END_TAG.length) {// Update latest chunk for short chunk
+        this.chunks[this.chunks.length - 1] = latest;
+      } else {
+        this.chunks.push(chunk);
+      }
+      callback();
+    }
+  }
+}
+
+module.exports = {
+  getCleanCid,
+  RestSearchStreamTransform,
+};

package/src/apis/display_video.js

@@ -34,8 +34,8 @@ const API_SCOPES = Object.freeze([
 const API_VERSION = 'v3';
 
 /**
- * Display and Video 360 API v2 stub.
- * @see https://developers.google.com/display-video/api/reference/rest/v2
+ * Display and Video 360 API v3 stub.
+ * @see https://developers.google.com/display-video/api/reference/rest/v3
  * This is not the same to Reports Display & Video 360 API which is from Google
  * Bid Manager API.
  * @see https://developers.google.com/bid-manager/reference/rest

package/src/apis/google_ads_api.js

@@ -22,7 +22,7 @@
 
 const { Transform } = require('stream');
 const lodash = require('lodash');
-
+const { request: gaxiosRequest } = require('gaxios');
 const {
   ConversionAdjustmentUploadServiceClient,
   ConversionUploadServiceClient,
@@ -33,6 +33,8 @@ const {
   UserListServiceClient,
   protos: { google: { ads: { googleads } } },
 } = require('google-ads-nodejs-client');
+
+const API_VERSION = Object.keys(googleads)[0];
 const {
   common: {
     Consent,
@@ -88,19 +90,23 @@ const {
     UserListTypeEnum: { UserListType },
     CustomerMatchUploadKeyTypeEnum: { CustomerMatchUploadKeyType },
   },
-} = googleads.v16;
+} = googleads[API_VERSION];
 
 const AuthClient = require('./auth_client.js');
 const {
   getLogger,
   BatchResult,
   extractObject,
+  changeNamingFromSnakeToLowerCamel,
   changeObjectNamingFromSnakeToLowerCamel,
+  changeObjectNamingFromLowerCamelToSnake,
 } = require('../components/utils.js');
+const { getCleanCid, RestSearchStreamTransform }
+  = require('./base/ads_api_common.js');
 
 /** @type {!ReadonlyArray<string>} */
 const API_SCOPES = Object.freeze(['https://www.googleapis.com/auth/adwords']);
-
+const API_ENDPOINT = 'https://googleads.googleapis.com';
 /**
  * List of properties that will be taken from the data file as elements of a
  * conversion or a conversion adjustment.
@@ -255,6 +261,9 @@ let ConversionConfig;
  * If audience listId is not present, 'listName' and 'uploadKeyType' need to
  * be there so they can be used to create a customer match user list.
  * operation must be one of 'create' or 'remove'.
+ * `customerMatchUserListMetadata` offers a request level metadata, including
+ * 'consent'. While the top level 'consent', if presents, it will serve as the
+ * fallback value for each UserIdentifier.
  * Should not include `userIdentifierSource` based on:
  * @see https://developers.google.com/google-ads/api/reference/rpc/latest/UserIdentifier
  * @see https://developers.google.com/google-ads/api/reference/rpc/latest/UserDataOperation
@@ -265,6 +274,7 @@ let ConversionConfig;
  *   listId: (string|undefined),
  *   listName: (string|undefined),
  *   uploadKeyType: ('CONTACT_INFO'|'CRM_ID'|'MOBILE_ADVERTISING_ID'|undefined),
+ *   customerMatchUserListMetadata: (undefined|CustomerMatchUserListMetadata),
  *   operation: ('create'|'remove'),
  *   consent: (!Consent),
  * }}
@@ -282,6 +292,9 @@ let CustomerMatchConfig;
  *  create a customer match user list.
  * For job type 'CUSTOMER_MATCH_WITH_ATTRIBUTES', 'user_attribute' can be used
  * to store shared additional user attributes.
+ * For job type 'CUSTOMER_MATCH_*', `customerMatchUserListMetadata` offers a job
+ * level metadata, including 'consent'. While the top level 'consent',
+ * if presents, it will serve as the fallback value for each UserIdentifier.
  * For job type 'STORE_SALES_UPLOAD_FIRST_PARTY', `storeSalesMetadata` is
  * required to offer StoreSalesMetadata. Besides that, for the store sales data,
  * common data (e.g. `currencyCode`, `conversionAction`) in
@@ -296,6 +309,7 @@ let CustomerMatchConfig;
  *   operation: ('create'|'remove'),
  *   type: !OfflineUserDataJobType,
  *   storeSalesMetadata: (undefined|StoreSalesMetadata),
+ *   customerMatchUserListMetadata: (undefined|CustomerMatchUserListMetadata),
  *   transactionAttribute: (undefined|TransactionAttribute),
  *   userAttribute: (undefined|UserAttribute),
  *   userIdentifierSource: (!UserIdentifierSource|undefined),
@@ -354,7 +368,7 @@ class GoogleAdsApi {
   async getReport(customerId, loginCustomerId, query) {
     const request = new SearchGoogleAdsRequest({
       query,
-      customerId: this.getCleanCid_(customerId),
+      customerId: getCleanCid(customerId),
     });
     return this.getReport_(request, loginCustomerId, true);
   }
@@ -380,7 +394,7 @@ class GoogleAdsApi {
     const request = new SearchGoogleAdsRequest(
       Object.assign({
         query,
-        customerId: this.getCleanCid_(customerId),
+        customerId: getCleanCid(customerId),
         pageSize: 10000,
       }, options)
     );
@@ -411,7 +425,6 @@ class GoogleAdsApi {
     return result;
   }
 
-  //TODO: Test a big report see how the event 'data' is triggered
   /**
    * Gets stream report of a given Customer account. The stream will send
    * `SearchGoogleAdsResponse` objects with the event 'data'.
@@ -424,7 +437,7 @@ class GoogleAdsApi {
     const client = await this.getGoogleAdsServiceClient_();
     const request = new SearchGoogleAdsRequest({
       query,
-      customerId: this.getCleanCid_(customerId),
+      customerId: getCleanCid(customerId),
     });
     const callOptions = this.getCallOptions_(loginCustomerId);
     const response = await client.searchStream(request, callOptions);
@@ -438,23 +451,76 @@ class GoogleAdsApi {
    * `results` in JSON format strings with the delimit of a line breaker.
    * @param {string} customerId
    * @param {string} loginCustomerId Login customer account ID (Mcc Account id).
-   * @param {string} query
-   * @return {!Promise<string>}
+   * @param {string} query A Google Ads Query string.
+   * @param {boolean} snakeCase Output JSON objects in snake_case.
+   * @return {!Promise<stream>}
    */
-  async cleanedStreamReport(customerId, loginCustomerId, query) {
+  async cleanedStreamReport(customerId, loginCustomerId, query,
+    snakeCase = false) {
     const cleanReportStream = new Transform({
       writableObjectMode: true,
       transform(chunk, encoding, callback) {
         const { fieldMask: { paths } } = chunk;
-        const extractor = extractObject(paths);
+        const camelPaths = paths.map((path) => {
+          return path.split('.').map(changeNamingFromSnakeToLowerCamel).join('.');
+        });
+        const extractor = extractObject(camelPaths);
+        const results = snakeCase
+          ? chunk.results.map(extractor).map(changeObjectNamingFromLowerCamelToSnake)
+          : chunk.results.map(extractor);
         // Add a line break after each chunk to keep files in proper format.
-        const data = chunk.results.map(extractor).map(JSON.stringify).join('\n')
-          + '\n';
+        const data = results.map(JSON.stringify).join('\n') + '\n';
         callback(null, data);
       }
     });
     const stream = await this.streamReport(customerId, loginCustomerId, query);
-    return stream.pipe(cleanReportStream);
+    return stream.on('error', (error) => cleanReportStream.emit('error', error))
+      .pipe(cleanReportStream);
+  }
+
+  /**
+   * Gets the report stream through REST interface.
+   * @param {string} customerId
+   * @param {string} loginCustomerId Login customer account ID (Mcc Account id).
+   * @param {string} query A Google Ads Query string.
+   * @return {!Promise<stream>}
+   */
+  async restStreamReport(customerId, loginCustomerId, query) {
+    await this.authClient.prepareCredentials();
+    const headers = Object.assign(
+      await this.authClient.getDefaultAuth().getRequestHeaders(),
+      this.getGoogleAdsHeaders_(loginCustomerId)
+    );
+    const options = {
+      baseURL: `${API_ENDPOINT}/${API_VERSION}/`,
+      url: `customers/${getCleanCid(customerId)}/googleAds:searchStream`,
+      headers,
+      data: { query },
+      method: 'POST',
+      responseType: 'stream',
+    };
+    const response = await gaxiosRequest(options);
+    return response.data;
+  }
+
+  /**
+   * Gets the report stream through REST interface.
+   * Based on the `fieldMask` in the response to filter out
+   * selected fields of the report and returns an array of JSON format strings
+   * with the delimit of a line breaker.
+   * @param {string} customerId
+   * @param {string} loginCustomerId Login customer account ID (Mcc Account id).
+   * @param {string} query A Google Ads Query string.
+   * @param {boolean} snakeCase Output JSON objects in snake_case.
+   * @return {!Promise<stream>}
+   */
+  async cleanedRestStreamReport(customerId, loginCustomerId, query,
+    snakeCase = false) {
+    const transform = new RestSearchStreamTransform(snakeCase);
+    const stream =
+      await this.restStreamReport(customerId, loginCustomerId, query);
+    return stream.on('error', (error) => transform.emit('error', error))
+      .pipe(transform);
   }
 
   /**
@@ -462,20 +528,19 @@ class GoogleAdsApi {
    * https://developers.google.com/google-ads/api/docs/concepts/field-service
    * Note, it looks like this function doesn't check the CID, just using
    * developer token and OAuth.
-   * @param {string|number} loginCustomerId Login customer account ID.
    * @param {Array<string>} adFields Array of Ad fields.
    * @param {Array<string>} metadata Select fields, default values are:
    *     name, data_type, is_repeated, type_url.
    * @return {!Promise<!Array<GoogleAdsField>>}
    */
-  async searchMetaData(loginCustomerId, adFields, metadata = [
-    'name', 'data_type', 'is_repeated', 'type_url',]) {
+  async searchReportField(adFields,
+    metadata = ['name', 'data_type', 'is_repeated', 'type_url',]) {
     const client = await this.getGoogleAdsFieldServiceClient_();
     const selectClause = metadata.join(',');
     const fields = adFields.join('","');
     const query = `SELECT ${selectClause} WHERE name IN ("${fields}")`;
     const request = new SearchGoogleAdsFieldsRequest({ query });
-    const callOptions = this.getCallOptions_(loginCustomerId);
+    const callOptions = this.getCallOptions_();
     const [results] = await client.searchGoogleAdsFields(request, callOptions);
     return results;
   }
@@ -559,8 +624,8 @@ class GoogleAdsApi {
     functionName, propertyForDebug) {
     /** @type {!ConversionConfig} */
     const adsConfig = this.getCamelConfig_(conversionConfig);
-    adsConfig.customerId = this.getCleanCid_(customerId);
-    adsConfig.loginCustomerId = this.getCleanCid_(loginCustomerId);
+    adsConfig.customerId = getCleanCid(customerId);
+    adsConfig.loginCustomerId = getCleanCid(loginCustomerId);
     /**
      * Sends a batch of hits to Google Ads API.
      * @param {!Array<string>} lines Data for single request. It should be
@@ -875,7 +940,7 @@ class GoogleAdsApi {
       SELECT user_list.id, user_list.resource_name
       FROM user_list
       WHERE user_list.name = '${listName}'
-        AND customer.id = ${this.getCleanCid_(customerId)}
+        AND customer.id = ${getCleanCid(customerId)}
         AND user_list.type = CRM_BASED
         AND user_list.membership_status = OPEN
         AND user_list.crm_based_user_list.upload_key_type = ${uploadKeyType}
@@ -905,7 +970,7 @@ class GoogleAdsApi {
       crmBasedUserList: { uploadKeyType },
     });
     const request = new MutateUserListsRequest({
-      customerId: this.getCleanCid_(customerId),
+      customerId: getCleanCid(customerId),
       operations: [{ create: userList }],
       validateOnly: this.debugMode, // when true makes no changes
       partialFailure: false, // Simplify error handling in creating userlist
@@ -1011,9 +1076,9 @@ class GoogleAdsApi {
     const operations = userDataList.map(
       (userData) => new UserDataOperation({ [operation]: new UserData(userData) })
     );
-    const metadata = this.buildCustomerMatchUserListMetadata_(customerId, listId);
+    const metadata = this.buildCustomerMatchUserListMetadata_(config);
     const request = new UploadUserDataRequest({
-      customerId: this.getCleanCid_(customerId),
+      customerId: getCleanCid(customerId),
       operations,
       customerMatchUserListMetadata: metadata,
     });
@@ -1025,16 +1090,20 @@ class GoogleAdsApi {
   /**
    * Creates CustomerMatchUserListMetadata.
    * @see https://developers.google.com/google-ads/api/reference/rpc/latest/CustomerMatchUserListMetadata
-   * @param {string} customerId part of the ResourceName to be mutated
-   * @param {string} userListId part of the ResourceName to be mutated
+   * @param {{
+   *     customerId: string,
+   *     listId: string,
+   *     customerMatchUserListMetadata: undefined|!CustomerMatchUserListMetadata
+   *   }}  config Configuration for CustomerMatchUserListMetadata
    * @return {!CustomerMatchUserListMetadata}
    * @private
    */
-  buildCustomerMatchUserListMetadata_(customerId, userListId) {
-    const resourceName = `customers/${customerId}/userLists/${userListId}`;
-    return new CustomerMatchUserListMetadata({
+  buildCustomerMatchUserListMetadata_(config) {
+    const { customerId, listId, customerMatchUserListMetadata } = config;
+    const resourceName = `customers/${customerId}/userLists/${listId}`;
+    return new CustomerMatchUserListMetadata(Object.assign({
       userList: resourceName,
-    });
+    }, customerMatchUserListMetadata));
   }
 
   /**
@@ -1080,8 +1149,7 @@ class GoogleAdsApi {
     const jobData = { type };
     // https://developers.google.com/google-ads/api/rest/reference/rest/latest/OfflineUserDataJobs?hl=en#CustomerMatchUserListMetadata
     if (type.startsWith('CUSTOMER_MATCH')) {
-      const metadata = this.buildCustomerMatchUserListMetadata_(customerId,
-        listId);
+      const metadata = this.buildCustomerMatchUserListMetadata_(config);
       jobData.customerMatchUserListMetadata = metadata;
       // https://developers.google.com/google-ads/api/rest/reference/rest/latest/OfflineUserDataJob?hl=en#StoreSalesMetadata
     } else if (type.startsWith('STORE_SALES')) {
@@ -1095,7 +1163,7 @@ class GoogleAdsApi {
     }
     const job = new OfflineUserDataJob(jobData);
     const request = new CreateOfflineUserDataJobRequest({
-      customerId: this.getCleanCid_(customerId),
+      customerId: getCleanCid(customerId),
       job,
       validateOnly: this.debugMode, // when true makes no changes
       enableMatchRateRangePreview: true,
@@ -1248,16 +1316,6 @@ class GoogleAdsApi {
     }
   }
 
-  /**
-   * Returns a integer format CID by removing dashes.
-   * @param {string} cid
-   * @return {string}
-   * @private
-   */
-  getCleanCid_(cid) {
-    return cid.toString().replace(/-/g, '');
-  }
-
   /**
    * Historically, we used a 3rd party library that adopted snake naming
    * convention as the protobuf files and API documents. However, the
@@ -1279,10 +1337,11 @@ class GoogleAdsApi {
    * @private
    */
   getGoogleAdsHeaders_(loginCustomerId) {
-    return {
-      "developer-token": this.developerToken,
-      "login-customer-id": loginCustomerId,
-    };
+    const headers = { 'developer-token': this.developerToken };
+    if (loginCustomerId) {
+      headers['login-customer-id'] = getCleanCid(loginCustomerId);
+    }
+    return headers;
   }
 
   /**
@@ -1295,7 +1354,7 @@ class GoogleAdsApi {
   getCallOptions_(loginCustomerId) {
     return {
       otherArgs: {
-        headers: this.getGoogleAdsHeaders_(this.getCleanCid_(loginCustomerId)),
+        headers: this.getGoogleAdsHeaders_(loginCustomerId),
       },
     };
   }
@@ -1536,6 +1595,7 @@ const debugGoogleAdsFailure = (failures, request) => {
 }
 
 module.exports = {
+  GoogleAdsField,
   ConversionConfig,
   CustomerMatchRecord,
   CustomerMatchConfig,

package/src/apis/search_ads.js

@@ -18,13 +18,17 @@
 
 'use strict';
 
+const { request: gaxiosRequest } = require('gaxios');
 const { google } = require('googleapis');
 const AuthClient = require('./auth_client.js');
 const { getLogger } = require('../components/utils.js');
+const { getCleanCid, RestSearchStreamTransform }
+  = require('./base/ads_api_common.js');
 
 const API_SCOPES = Object.freeze([
   'https://www.googleapis.com/auth/doubleclicksearch',
 ]);
+const API_ENDPOINT = 'https://searchads360.googleapis.com';
 const API_VERSION = 'v0';
 
 /**
@@ -56,13 +60,15 @@ class SearchAds {
    * @private
    */
   async getApiClient_(loginCustomerId) {
-    this.logger.debug(`Initialized Search Ads reporting instance for ${loginCustomerId}`);
-    this.searchads360 = google.searchads360({
+    this.logger.debug(`Initialized SA reporting for ${loginCustomerId}`);
+    const options = {
       version: API_VERSION,
       auth: await this.getAuth_(),
-      headers: { 'login-customer-id': loginCustomerId },
-    });
-    return this.searchads360;
+    };
+    if (loginCustomerId) {
+      options.headers = { 'login-customer-id': getCleanCid(loginCustomerId) };
+    }
+    return google.searchads360(options);
   }
 
   /**
@@ -77,61 +83,117 @@ class SearchAds {
   }
 
   /**
-   * Returns all rows that match the search stream query.
-   * The streamed content is not NDJSON format, but one JSON object with the
-   * property `results`. The whole JSON string can be parsed to an object and
-   * the `results` be extracted and converted to NDJSON lines. If the report
-   * is too large to be handled in this way, a possible solution is to parse
-   * the string directly to get the content of `results`.
-   * @see https://developers.google.com/search-ads/reporting/api/reference/rest/v0/customers.searchAds360/searchStream
+   * Gets a report synchronously from a given Customer account.
+   * If there is a `nextPageToken` in the response, it means the report is not
+   * finished and there are more pages.
+   * @see https://developers.google.com/search-ads/reporting/api/reference/rpc/google.ads.searchads360.v0.services#searchads360service
    * @param {string} customerId
    * @param {string} loginCustomerId Login customer account ID (Mcc Account id).
    * @param {string} query
-   * @return {!ReadableStream}
+   * @param {object=} options Options for `SearchSearchAds360Request`.
+   * @see https://developers.google.com/search-ads/reporting/api/reference/rpc/google.ads.searchads360.v0.services#searchsearchads360request
+   * @return {!SearchAds360Field}
+   * @see https://developers.google.com/search-ads/reporting/api/reference/rpc/google.ads.searchads360.v0.services#searchsearchads360response
    */
-  async streamReport(customerId, loginCustomerId, query) {
+  async getPaginatedReport(customerId, loginCustomerId, query, options = {}) {
     const searchads = await this.getApiClient_(loginCustomerId);
+    const requestBody = Object.assign({
+      query,
+      pageSize: 10000,
+    }, options);
     const response = await searchads.customers.searchAds360.search({
-      customerId,
-      requestBody: { query },
-    }, { responseType: 'stream' });
+      customerId: getCleanCid(customerId),
+      requestBody,
+    });
     return response.data;
   }
 
   /**
-   * Gets a report synchronously from a given Customer account.
-   * This is for test as it does not handle page token. For product env, use
-   * function `streamReport`.
-   * @see https://developers.google.com/search-ads/reporting/api/reference/rest/v0/customers.searchAds360/search#request-body
+   * Gets a report stream from a Search Ads 360 reporting API.
+   * The streamed content is not NDJSON format, but an array of JSON objects
+   * with each element has a property `results`.
+   * `data` support `batchSize` to set how many rows in one result element.
    * @param {string} customerId
    * @param {string} loginCustomerId Login customer account ID (Mcc Account id).
    * @param {string} query
-   * @return {!SearchAds360Field}
-   * @see https://developers.google.com/search-ads/reporting/api/reference/rest/v0/searchAds360Fields#SearchAds360Field
+   * @return {!Promise<stream>}
+   * @see https://developers.google.com/search-ads/reporting/api/reference/rest/search
    */
-  async getReport(customerId, loginCustomerId, query) {
-    const searchads = await this.getApiClient_(loginCustomerId);
-    const response = await searchads.customers.searchAds360.search({
-      customerId,
-      requestBody: { query },
+  async restStreamReport(customerId, loginCustomerId, query) {
+    const auth = await this.getAuth_();
+    const headers = Object.assign(
+      await auth.getRequestHeaders(), {
+      'login-customer-id': getCleanCid(loginCustomerId),
     });
-    return response.data.results;
+    const options = {
+      baseURL: `${API_ENDPOINT}/${API_VERSION}/`,
+      url: `customers/${getCleanCid(customerId)}/searchAds360:searchStream`,
+      headers,
+      data: { query },
+      method: 'POST',
+      responseType: 'stream',
+    };
+    const response = await gaxiosRequest(options);
+    return response.data;
+  }
+
+  /**
+   * Gets the report stream through REST interface.
+   * Based on the `fieldMask` in the response to filter out
+   * selected fields of the report and returns an array of JSON format strings
+   * with the delimit of a line breaker.
+   * @param {string} customerId
+   * @param {string} loginCustomerId Login customer account ID (Mcc Account id).
+   * @param {string} query A Google Ads Query string.
+   * @param {boolean=} snakeCase Output JSON objects in snake_case.
+   * @return {!Promise<stream>}
+   */
+  async cleanedRestStreamReport(customerId, loginCustomerId, query,
+    snakeCase = false) {
+    const transform = new RestSearchStreamTransform(snakeCase);
+    const stream =
+      await this.restStreamReport(customerId, loginCustomerId, query);
+    return stream.on('error', (error) => transform.emit('error', error))
+      .pipe(transform);
   }
 
   /**
    * Returns the requested field or resource (artifact) used by SearchAds360Service.
    * This service doesn't require `login-customer-id` HTTP header.
    * @see https://developers.google.com/search-ads/reporting/api/reference/rest/v0/searchAds360Fields/get
-   * @param {string} resourceName
+   * @param {string} fieldName
    * @return {!SearchAds360Field}
    * @see https://developers.google.com/search-ads/reporting/api/reference/rest/v0/searchAds360Fields#SearchAds360Field
    */
-  async getReportField(resourceName) {
+  async getReportField(fieldName) {
     const searchads = await this.getApiClient_();
-    const response = await searchads.searchAds360Fields.get({ resourceName });
+    const resourceName = `searchAds360Fields/${fieldName}`;
+    const response =
+      await searchads.searchAds360Fields.get({ resourceName });
     return response.data;
   }
 
+  /**
+   * Returns resources information from Search Ads API.
+   * @see: https://developers.google.com/search-ads/reporting/api/reference/rest/v0/searchAds360Fields
+   * Note, it looks like this function doesn't check the CID, just using OAuth.
+   * @param {Array<string>} adFields Array of Ad fields.
+   * @param {Array<string>} metadata Select fields, default values are:
+   *     name, data_type, is_repeated, type_url.
+   * @return {!Promise<!Array<GoogleAdsField>>}
+   * @see GoogleAdsApi.searchReportField
+   */
+  async searchReportField(adFields,
+    metadata = ['name', 'data_type', 'is_repeated', 'type_url',]) {
+    const searchads = await this.getApiClient_();
+    const selectClause = metadata.join(',');
+    const fields = adFields.join('","');
+    const query = `SELECT ${selectClause} WHERE name IN ("${fields}")`;
+    const response =
+      await searchads.searchAds360Fields.search({ query, pageSize: 10000 });
+    return response.data.results;
+  }
+
   /**
    * Returns all the custom columns associated with the customer in full detail.
    * @see https://developers.google.com/search-ads/reporting/api/reference/rest/v0/customers.customColumns/list

package/src/components/utils.js

@@ -489,7 +489,7 @@ const extractObject = (paths) => {
     paths.forEach((path) => {
       const [value, owner, property] = path.split('.')
           .reduce(transcribe, [sourceObject, output, undefined]);
-      if (value) {
+      if (typeof value !== 'undefined') {
         owner[property] = value;
       }
     });
@@ -539,6 +539,16 @@ const changeNamingFromSnakeToLowerCamel = (name) => {
       (initial) => initial.substring(1).toUpperCase());
 };
 
+/**
+ * For more details, see:
+ * https://developers.google.com/google-ads/api/docs/rest/design/json-mappings
+ * @param {string} name Identifiers.
+ * @return {string}
+ */
+const changeNamingFromLowerCamelToSnake = (name) => {
+  return name.replace(/([a-z])([A-Z])/g, '$1_$2').toLowerCase();
+};
+
 /**
  * Converts a JSON object which has snake naming convention to lower camel
  * naming.
@@ -561,6 +571,28 @@ const changeObjectNamingFromSnakeToLowerCamel = (obj) => {
   }
 }
 
+/**
+ * Converts a JSON object which has lower camel naming convention to snake
+ * naming.
+ *
+ * @param {object} obj
+ * @return {object}
+ */
+const changeObjectNamingFromLowerCamelToSnake = (obj) => {
+  if (Array.isArray(obj)) {
+    return obj.map(changeObjectNamingFromLowerCamelToSnake);
+  } else if (typeof obj === 'object') {
+    const newObj = {};
+    Object.keys(obj).forEach((key) => {
+      newObj[changeNamingFromLowerCamelToSnake(key)] =
+        changeObjectNamingFromLowerCamelToSnake(obj[key]);
+    });
+    return newObj;
+  } else {
+    return obj;
+  }
+}
+
 /**
  * Returns the response data for a HTTP request. It will retry the specific
  * times if there was errors happened.
@@ -606,6 +638,8 @@ module.exports = {
   getObjectByPath,
   changeNamingFromSnakeToUpperCamel,
   changeNamingFromSnakeToLowerCamel,
+  changeNamingFromLowerCamelToSnake,
   changeObjectNamingFromSnakeToLowerCamel,
+  changeObjectNamingFromLowerCamelToSnake,
   requestWithRetry,
 };