基于 Cloud Functions 和 Pub/Sub 部署无服务器集成解决方案

本教程介绍如何根据 Google Marketing Platform 的无服务器集成解决方案中所述的概念设置和测试数据集成解决方案。

有关此无服务器解决方案的演示,请参阅 GitHub 上的开源演示。该解决方案附带 API 和 shell 脚本,可帮助您在 Google Cloud 中设置解决方案。

本教程适合要使用 API 或其他编程集成方案(如 SFTP Upload)将数据与目标系统自动集成的数据工程师或架构师。

目标

  • 部署无服务器集成解决方案。
  • 在目标系统中为目标 API 设置集成。
  • 要测试此解决方案,请在 Google 表格中加载 CSV 文件。

费用

本教程使用 Google Cloud 的以下收费组件:

您可使用价格计算器根据您的预计使用情况来估算费用。 Google Cloud 新用户可能有资格申请免费试用

完成本教程后,您可以删除所创建的资源以避免继续计费。如需了解详情,请参阅清理

准备工作

  1. 登录您的 Google Cloud 帐号。如果您是 Google Cloud 新手,请创建一个帐号来评估我们的产品在实际场景中的表现。新客户还可获享 $300 赠金,用于运行、测试和部署工作负载。
  2. 在 Google Cloud Console 的项目选择器页面上,选择或创建一个 Google Cloud 项目。

    转到“项目选择器”

  3. 确保您的 Cloud 项目已启用结算功能。 了解如何确认您的项目是否已启用结算功能

  4. 在 Google Cloud Console 的项目选择器页面上,选择或创建一个 Google Cloud 项目。

    转到“项目选择器”

  5. 确保您的 Cloud 项目已启用结算功能。 了解如何确认您的项目是否已启用结算功能

  6. 打开 Cloud Shell。
  7. 打开 Cloud Shell

安装解决方案

  1. 在 Cloud Shell 中,克隆包含您用于本教程的代码的代码库:

    git clone https://github.com/GoogleCloudPlatform/cloud-for-marketing.git
    
  2. 运行安装脚本:

    cd cloud-for-marketing/marketing-analytics/activation/gmp-googleads-connector; chmod a+x deploy.sh; ./deploy.sh
    

    该脚本会运行一系列进程,例如检查环境和编译依赖项。

  3. 收到提示时,输入您要在本教程中使用的 Cloud 项目 ID。

  4. 选择 Cloud Functions 函数的部署区域,并将数据存储在 Cloud Storage 中,例如 us-east1

  5. 选择您要使用的内置 API,或按 Enter 将其全部选中。此解决方案附带以下目标 API:

    • Google Analytics(分析)Measurement Protocol
    • Google Analytics(分析)Management API (Data Import)
    • Campaign Manager Conversions Upload
    • SFTP Upload,用于将商家数据上传到 Search Ads 360
    • Google Sheets API,用于根据 Google 表格定期上传 Google Ads 转化数据
    • Search Ads 360 Conversions Upload

    包括 Google Sheets API,因为您将在安装后运行使用该 API 的测试。系统会执行检查,确定是否存在执行安装所需的权限。如果检查失败,您必须向管理员申请缺少的权限,然后重新运行脚本。

  6. 输入用于存储数据的 Cloud Storage 存储分区的名称。如果存储分区不存在,请选择一个区域,脚本随后就会创建该存储分区。(我们建议您使用默认区域,该区域与 Cloud Functions 函数的部署位置匹配。)

  7. 输入此解决方案监控的 Cloud Storage 文件夹,或按 Enter 选择默认文件夹。

  8. 输入 Pub/Sub 主题和订阅的前缀,或按 Enter 使用默认前缀。

  9. 收到提示时,输入 Y 进行确认,并将您的设置保存到 config.json 文件中。

    随即将创建 Pub/Sub 主题和订阅。

  10. 如果您启用的 API 需要服务帐号,请输入服务帐号的名称,然后确认您要下载密钥文件。

  11. 自动部署 Cloud Functions 函数后,脚本会指示 Firestore 或 Datastore 实例是否准备就绪。如果尚未准备就绪,请输出说明指示如何启动 Firestore。

准备数据

您现已安装该解决方案,接下来可为目标系统准备数据。

文件格式

此解决方案中内置的 API 在某些情况下需要特定的文件格式:

  • SFTP Upload 没有格式请求。无论文件格式如何,此集成都会通过 SFTP 将文件上传到服务器。
  • Google Analytics(分析)Management API (Data Import) 和 Google Sheets API 需要 CSV 文件。
  • 对于所有其他 API,系统需要以换行符分隔的 JSON (NDJSON)。每一行都是有效的 JSON 字符串。如需查看示例,请参阅 BigQuery 导出格式

API 配置

不同的 API 具有不同的配置,并且一个 API 可能有多个不同用途的配置。因此,配置按 API 进行分组,在文件 config_api.json 中合并单个 JSON 对象。来自本教程 GitHub 代码库的 JSON 模板文件中的以下列表显示了配置的组织方式。

{
  "CM": {
    "foo": {
      "cmAccountId": "[YOUR-DCM-ACCOUNT-ID]",
      "cmConfig": {
        "idType": "encryptedUserId",
        "conversion": {
          "floodlightConfigurationId": "[YOUR-FL-CONFIG-ID]",
          "floodlightActivityId": "[YOUR-FL-ACTIVITY-ID]",
          "quantity": 1
        },
        "customVariables": [
          "[YOUR-U-VARIABLES-NAME-1]", "[YOUR-U-VARIABLES-NAME-2]"
        ],
        "encryptionInfo": {
          "encryptionEntityId": "[YOUR-ENCRYPTION-ID]",
          "encryptionEntityType": "DCM_ADVERTISER",
          "encryptionSource": "AD_SERVING"
        }
      }
    }
  },
  "GA": {
    "bar": {
      "dataImportHeader": "[YOUR-DATA-IMPORT-HEADER]",
      "gaConfig": {
        "accountId": "[YOUR-GA-ACCOUNT-ID]",
        "webPropertyId": "[YOUR-WEB-PROPERTY-ID]",
        "customDataSourceId": "[YOUR-CUSTOM-DATASOURCE-ID]"
      }
    }
  },
  "MP": {
    "baz": {
      "mpConfig":{
        "v": "1",
        "t": "transaction",
        "ni": "1",
        "dl": "[YOUR-SOMETHING-URL]",
        "tid": "[YOUR-WEB-PROPERTY-ID]"
      }
    }
  },
  "SFTP": {
    "qux": {
      "sftp":{
        "host": "[YOUR-SFTP-HOST]",
        "port": "[YOUR-SFTP-PORT]",
        "username": "[YOUR-SFTP-USERNAME]",
        "password": "[YOUR-SFTP-PASSWORD]"
      }
    }
  },
  "GS": {
    "foo": {
      "spreadsheetId": "[YOUR-SPREADSHEET-ID]",
      "sheetName": "[YOUR-SHEET-NAME]",
      "sheetHeader": "[ANYTHING-PUT-AHEAD-OF-CSV]",
      "pasteData": {
        "coordinate": {
          "rowIndex": 0,
          "columnIndex": 0
        },
        "delimiter": ","
      }
    }
  },
  "SA": {
    "bar": {
      "saConfig": {
        "currencyCode": "[YOUR-CURRENCY-CODE]",
        "type": "TRANSACTION",
        "segmentationType": "FLOODLIGHT",
        "segmentationId": "[YOUR-SEGMENTATION-ID]",
        "state": "ACTIVE"
      },
      "availabilities": [
        {
          "agencyId": "[YOUR-AGENCY-ID]",
          "advertiserId": "[YOUR-ADVERTISER-ID]",
          "segmentationType": "FLOODLIGHT",
          "segmentationId": "[YOUR-SEGMENTATION-ID]"
        }
      ]
    }
  },
  "ACLC": {
    "foo" : {
      "customerId": "[YOUR-GOOGLE-ADS-ACCOUNT-ID]",
      "loginCustomerId": "[YOUR-LOGIN-GOOGLE-ADS-ACCOUNT-ID]",
      "developerToken": "[YOUR-GOOGLE-ADS-DEV-TOKEN]",
      "adsConfig": {
        "conversion_action": "[YOUR-CONVERSION-ACTION-NAME]",
        "conversion_value": "[YOUR-CONVERSION-VALUE]",
        "currency_code": "[YOUR-CURRENCY-CODE]"
      }
    }
  },
  "ACM": {
    "foo" : {
      "developerToken": "[YOUR-GOOGLE-ADS-DEV-TOKEN]",
      "customerMatchConfig": {
        "customer_id": "[YOUR-GOOGLE-ADS-ACCOUNT-ID]",
        "login_customer_id": "[YOUR-LOGIN-GOOGLE-ADS-ACCOUNT-ID]",
        "list_id": "[YOUR-CUSTOMER-MATCH-LIST-ID]",
        "list_type": "[YOUR-CUSTOMER-MATCH-LIST-TYPE],
        "operation": "create|remove"
      }
    }
  }
}

您可以将模板文件名重命名为 config_api.json,仅保留目标 API 部分,并修改配置的详细信息。如果您有多个配置,请复制这些配置并为其指定不同的名称。之后,在 Firestore 中更新配置:

./deploy.sh update_api_config

文件名惯例

为了实现不同类型的 API 和配置的灵活性,我们在此解决方案中对传入文件采用命名惯例。文件名应包含 API[X]config[Y] 模式。

  • X 代表目标 API 的代码。在此解决方案中,X 可以是:
    • MP:Google Analytics(分析)Measurement Protocol
    • GA:Google Analytics(分析)Management API (Data Import)
    • CM:DCM/DFA Reporting and Trafficking API
    • SFTP:SFTP Upload
    • GS:Google Sheets API
    • SA:Search Ads 360 API
  • Y 是配置名称,例如模板代码中的 foobar

例如,名为 API[GA]_config[bar]_20191111.csv 的文件表示以下内容:

  • [GA] 表示 Google Analytics(分析)是目标系统,Data Import 是目标 API。
  • [bar] 表示使用存储在模板配置文件中的 JSON 对象的 bar 键将文件发送到目标系统。

文件名的可选格式包括:

  • 如果文件名包含 dryrun,则进程遵循所有步骤,但不会将数据发送到 API 服务器。
  • 如果文件名包含 _size[Z]_size[Zmb],则传入文件会被分为多个文件,且 Cloud Storage 中小于 Z MB 的文件大小符合某些 API 的文件大小限制。例如,Data Import 的限制为 1 GB。

例如,名为 API[GA]_config[bar]_dryrun_20191111.csv 的文件不会发送到 Google Analytics(分析),但会通过整个集成系统传输。名为 API[GA]_config[bar]_size[100]_20191111.csv 的文件会拆分为一组大小不超过 100 MB 的文件,每个文件都通过 Data Import 单独发送到 Google Analytics(分析)。

测试解决方案

安装解决方案后,您可以创建 CSV 文件,并将该文件中的数据自动加载到目标 Google 表格电子表格中来测试集成。

向服务帐号授予权限

  1. 创建新的 Google 表格电子表格,然后对其进行重命名,例如 Integration Test
  2. 点击共享
  3. 在 Cloud Shell 中,获取您在安装步骤中使用的服务帐号的电子邮件地址:

    ./deploy.sh print_service_account
    
  4. 人员字段中,复制服务帐号的电子邮件地址,然后选择 可修改,为其分配 Editor 权限。

获取目标电子表格的 ID

  • 复制您的目标 Google 表格电子表格的电子表格 ID

    电子表格 ID 是电子表格网址中 /d//edit 之间的值(例如 spreadsheetId),如下所示:

    https://docs.google.com/spreadsheets/d/spreadsheetId/edit#gid=0
    

更新 API 配置

  1. 在 Cloud Shell 中,转到安装解决方案的文件夹,例如 ~/cloud-for-marketing/marketing-analytics/activation/gmp-googleads-connector
  2. 打开名为 config_api.json 的 JSON 文件,并将内容替换为以下代码:

    {
      "GS": {
        "foo": {
          "spreadsheetId": "your-spreadsheet-id",
          "sheetName": "your-sheet-name",
          "sheetHeader": "This is a test integration",
          "pasteData": {
            "coordinate": {
              "rowIndex": 0,
              "columnIndex": 0
            },
            "delimiter": ","
          }
        }
      }
    }
    

    替换以下内容:

    • your-spreadsheet-id:您的电子表格 ID。
    • your-sheet-name:您的 Google 表格电子表格中目标表格的名称。
  3. 将配置上传到 Firestore 或 Datastore:

    ./deploy.sh update_api_config
    

    输出如下所示:

    Init ApiConfig based on Datastore.
      Import Config for API[GS]_config[foo]
    

准备要发送的文件

在此测试中,您将 CSV 文件中的数据加载到目标表格中。

  • 在 Cloud Shell 中,创建一个 CSV 文件,其中包含一些内置 API 的内容:

    cat > API[GS]_config[foo]_test.csv <<EOF
    #What are Tentacles built in APIs
    Target System, Target API, Code
    Google Analytics, Measurement Protocol, MP
    Google Analytics, Google Analytics Management API, GA
    Campaign Manager, DCM/DFA Reporting and Trafficking API, CM
    Search Ads 360, SFTP, SFTP
    EOF
    

将文件上传到 Cloud Storage

  • 将文件上传到 Cloud Storage 存储分区:

    ./deploy.sh copy_file_to_gcs API[GS]_config[foo]_test.csv
    

    输出内容如下所示:

    Copy integration data file to target folder…
    Copying file:...
      Operation completed over...
    

验证结果

  • 打开您之前创建的 Google 表格电子表格。

    Sheet1 已调整大小,并加载了 CSV 文件中的数据。

    显示上传到 Google 表格电子表格的数据的屏幕截图。

清除数据

为避免支付费用,最简单的方法是删除您为本教程创建的项目。

  1. 在 Cloud Console 中,转到管理资源页面。

    转到“管理资源”

  2. 在项目列表中,选择要删除的项目,然后点击删除
  3. 在对话框中输入项目 ID,然后点击关闭以删除项目。

后续步骤