本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 連線至 HubSpot
HubSpot 的 CRM 平台具有行銷、銷售、內容管理和客戶服務所需的所有工具和整合。
+ 行銷 Hub - 可協助您擴展流量、轉換更多訪客，以及大規模執行完整集客式行銷活動的行銷軟體。
+ 銷售 Hub - 銷售 CRM 軟體，可協助您更深入了解潛在客戶、自動化您擁有的任務，以及更快地完成更多交易。
+ 服務 Hub - 客戶服務軟體，可協助您與客戶建立聯繫、超越期望，並將其轉換為促進業務成長的推廣者。
+ 營運 Hub - 可同步您的應用程式、清理和建立客戶資料，以及自動化程序的操作軟體，因此您的所有系統和團隊都能更順暢地運作。
**Topics**
+ [AWS Glue 支援 HubSpot](hubspot-support.md)
+ [包含用於建立和使用連線的 API 操作的政策](hubspot-configuring-iam-permissions.md)
+ [設定 HubSpot](hubspot-configuring.md)
+ [設定 HubSpot 連線](hubspot-configuring-connections.md)
+ [從 HubSpot 實體讀取](hubspot-reading-from-entities.md)
+ [寫入到 HubSpot 實體](hubspot-writing-to-entities.md)
+ [HubSpot 連線選項](hubspot-connection-options.md)
+ [HubSpot 連接器的限制和備註](hubspot-connector-limitations.md)
# AWS Glue 支援 HubSpot
AWS Glue 支援 HubSpot，如下所示：
**支援作為來源？**
是 – 同步和非同步。您可以使用 AWS Glue ETL 任務從 HubSpot 查詢資料。
**支援作為目標？**
是。您可以使用 AWS Glue ETL 任務將資料寫入 HubSpot。
**支援的 HubSpot API 版本**
支援以下 HubSpot API 版本：
+ v1
+ v2
+ v3
+ v4
如需特定版本的實體支援，請參閱 [同步來源支援的實體](hubspot-reading-from-entities.md#sync-table) 和 [非同步來源支援的實體](hubspot-reading-from-entities.md#async-table)。
# 包含用於建立和使用連線的 API 操作的政策
下列範例政策說明建立和使用 連線所需的 AWS IAM 許可。如果您要建立新角色，請建立包含下列項目的政策：
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"glue:ListConnectionTypes",
"glue:DescribeConnectionType",
"glue:RefreshOAuth2Tokens",
"glue:ListEntities",
"glue:DescribeEntity"
],
"Resource": "*"
}
]
}
```
------
如果不想使用上述方法，可選擇使用下列受管 IAM 政策：
+ [AWSGlueServiceRole](https://console.aws.amazon.com/iam/home#policies/arn:aws:iam::aws:policy/service-role/AWSGlueServiceRole) – 准許存取各種 AWS Glue 程序代表您執行所需的資源。這些資源包括 AWS Glue Amazon S3、IAM、CloudWatch Logs 和 Amazon EC2。如果您遵循此政策中指定資源的命名慣例，則 AWS Glue 程序具有必要的許可。此政策通常會連接至定義編目程式、工作和開發端點時所指定的角色。
+ [AWSGlueConsoleFullAccess](https://console.aws.amazon.com/iam/home#policies/arn:aws:iam::aws:policy/AWSGlueConsoleFullAccess) – 當政策連接至 的身分使用 AWS 管理主控台時，授予 AWS Glue 資源的完整存取權。如果您依照此政策中指定的資源命名慣例，使用者就能擁有完整的主控台功能。此政策通常連接到 AWS Glue 主控台的使用者。
# 設定 HubSpot
您必須先符合下列要求，才能使用 從 HubSpot AWS Glue 傳輸資料：
## 最低需求
以下是最低要求：
+ 您具有 HubSpot 帳戶。如需詳細資訊，請參閱[建立 HubSpot 帳戶](#hubspot-configuring-creating-hubspot-account)。
+ 您的 HubSpot 帳戶已啟用 API 存取。
+ 您的 HubSpot 開發人員帳戶下應該有應用程式，提供用戶端登入資料，在對您的帳戶進行身分驗證呼叫時 AWS Glue ，使用 安全地存取您的資料。如需詳細資訊，請參閱[建立 HubSpot 開發人員應用程式](#hubspot-configuring-creating-hubspot-developer-app)。
如果您符合這些要求，就可以 AWS Glue 連線到 HubSpot 帳戶。對於一般連線，您無需在 HubSpot 中執行任何其他動作。
## 建立 HubSpot 帳戶
若要建立 HubSpot 帳戶，請執行以下操作：
1. 前往 [HubSpot CRM SignUp URL](https://app.hubspot.com/login)。
1. 輸入您的電子郵件地址，然後選擇**驗證電子郵件** (或者，您可以選擇註冊 Google、Microsoft 或 Apple 帳戶)。
1. 檢查您的收件匣是否有來自 HubSpot 的驗證碼。
1. 輸入 6 位數驗證碼，然後按一下**下一步**。
1. 輸入密碼，然後按一下**下一步**。
1. 輸入您的名字和姓氏，然後按一下**下一步**，或使用**註冊 Google **連結註冊。
1. 輸入您的產業，然後按一下**下一步**。
1. 輸入您的任務角色，然後按一下**下一步**。
1. 輸入貴公司名稱，然後按一下**下一步**。
1. 選取貴公司的規模 (在貴公司工作的員工人數)，然後按一下**下一步**。
1. 輸入貴公司網站，然後按一下**下一步**。
1. 選取您的資料應託管的位置 (美國或歐洲)，然後按一下**建立帳戶**。
1. 選取您帳戶建立的目的，然後按一下**下一步**。
1. 選擇**連接 Google 帳戶**，或選擇自行新增聯絡人，以將您的聯絡人與您的 HubSpot 帳戶連結。
1. 如果您選擇**連接 Google 帳戶**選項來連結聯絡人並開始使用 HubSpot 帳戶，請登入您的 Google 帳戶。
## 建立 HubSpot 開發人員應用程式
應用程式開發人員帳戶旨在建立和管理應用程式、整合及開發人員測試帳戶。這些也是您可以建立和管理 App Marketplace 清單的地方。不過，應用程式開發人員帳戶及其關聯的測試帳戶不會連線到標準 HubSpot 帳戶。他們無法將資料或資產同步到另一個 HubSpot 帳戶或從中同步。若要取得用戶端 ID 和用戶端機密，您可以建立開發人員帳戶。
1. 前往 https://developers.hubspot.com/
1. 選擇**建立開發人員帳戶**，並向下捲動。
1. 系統會要求您建立應用程式開發人員帳戶、私有應用程式帳戶或 CMS 開發人員沙盒帳戶。選擇**建立應用程式開發人員帳戶**。
1. 由於您已建立 HubSpot 帳戶，可以選擇**繼續此使用者**。
1. 按一下**開始上傳**。
1. 輸入您的任務角色，然後按一下**下一步**。
1. 為您的開發人員帳戶命名並按一下**下一步**，然後按一下**略過**。
1. 選擇 **Create App (建立應用程式)**。
1. 建立應用程式後，請選擇**驗證**。
1. 在「驗證」下，記下用戶端 ID 和用戶端機密。
1. 將區域特定的**重新導向 URL** 新增為 https:*//*.console.aws.amazon.com/gluestudio/oauth。例如，為 us-east-1 區域新增 https://us-east-1.console.aws.amazon.com/gluestudio/oauth。
1. 向下捲動並查找範圍。在標題「CRM」和「標準」下，必須選取兩種類型的範圍。
1. 新增下列範圍：
```
content
automation
oauth
crm.objects.owners.read
forms
tickets
crm.objects.contacts.write
e-commerce
crm.schemas.custom.read
crm.objects.custom.read
sales-email-read
crm.objects.custom.write
crm.objects.companies.write
crm.lists.write
crm.objects.companies.read
crm.lists.read
crm.objects.deals.read
crm.objects.deals.write
crm.objects.contacts.read
```
1. 按一下**儲存**，您的開發帳戶現在即可使用。
1. 向上捲動以尋找**用戶端 ID**。
1. 在相同頁面上，按一下**顯示**以取得**用戶端機密**。
## 建立 HubSpot 開發人員測試帳戶
在應用程式開發人員帳戶內，您可以建立開發人員測試帳戶來測試應用程式和整合，而不會影響任何真實的 HubSpot 資料。開發人員測試帳戶不會鏡像生產帳戶，而是可以存取企業版行銷、銷售、服務、CMS 和營運中樞的 90 天試用版，提供測試大多數 HubSpot 工具和 API 的能力。
1. 按一下**首頁**。
1. 按一下**建立測試帳戶**。
1. 按一下**建立應用程式測試帳戶**。
1. 新視窗隨即出現。輸入應用程式測試帳戶名稱，然後按一下**建立**。
您的應用程式測試帳戶現在已建立。
**注意**
開發人員帳戶與 API 整合等開發活動相關，而應用程式測試帳戶用於查看開發人員帳戶建立或提取的資料。
# 設定 HubSpot 連線
HubSpot 支援 OAuth2 的 AUTHORIZATION\$1CODE 授權類型。
+ 此授權類型被視為「三條腿的」OAuth，因為其依賴將使用者重新導向至第三方授權伺服器來驗證使用者。透過 AWS Glue 主控台建立連線時，會使用它。建立連線的使用者需要為 HubSpot 用戶端應用程式提供 OAuth 相關資訊，例如用戶端 ID 和用戶端機密。 AWS Glue 主控台會將使用者重新導向至 HubSpot，使用者必須在其中登入 AWS Glue ，並允許請求的許可存取其 HubSpot 執行個體。
+ 使用者仍然可以選擇在 HubSpot 中建立自己的連線應用程式，並在透過 AWS Glue 主控台建立連線時提供自己的用戶端 ID 和用戶端秘密。在此案例中，它們仍會重新導向至 HubSpot 以登入並授權 AWS Glue 存取其資源。
+ 此授權類型會產生重新整理字符和存取字符。存取字符是短期存留的，可以使用重新整理字符自動重新整理，而無需使用者互動。
+ 如需為授權碼 OAuth 流建立連接應用程式的公有 HubSpot 文件，請參閱[公有應用程式](https://developers.hubspot.com/docs/api/creating-an-app)。
如需設定 HubSpot 連線，請執行以下操作：
1. 在 AWS Secrets Manager 中，建立包含下列詳細資訊的秘密：
1. 對於客戶管理的連線應用程式，機密應包含以 `USER_MANAGED_CLIENT_APPLICATION_CLIENT_SECRET` 作為金鑰的連線應用程式消費者機密。
1. 注意：必須在 AWS Glue中建立連線機密。
1. 在 AWS Glue Glue Studio 中，依照下列步驟在 **Data Connections** 下建立連線：
1. 在選取**連線類型**時，選取 HubSpot。
1. 提供 HubSpot 環境。
1. 選取 AWS Glue 可以擔任並具有下列動作許可的 AWS IAM 角色：
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"secretsmanager:DescribeSecret",
"secretsmanager:GetSecretValue",
"secretsmanager:PutSecretValue",
"ec2:CreateNetworkInterface",
"ec2:DescribeNetworkInterfaces",
"ec2:DeleteNetworkInterface"
],
"Resource": "*"
}
]
}
```
------
1. 選取您要用於此連線`secretName`的 AWS Glue ，以放置字符。
1. 如果想要使用您的網路，請選取網路選項。
1. 授予與您的 AWS Glue 任務相關聯的 IAM 角色讀取 的許可`secretName`。
1. 在您的 AWS Glue 任務組態中，提供 `connectionName`做為**其他網路連線**。
# 從 HubSpot 實體讀取
**必要條件**
您要從中讀取的 HubSpot 物件。您將需要物件名稱，例如聯絡人或任務。下表顯示 Sync 來源支援的實體。
## 同步來源支援的實體
| 實體 | API 版本 | 可以篩選 | 支援限制 | 支援排序依據 | 支援選取 \$1 | 支援分區 |
| --- | --- | --- | --- | --- | --- | --- |
| 行銷活動 | v1 | 否 | 是 | 否 | 是 | 否 |
| 公司 | v3 | 是 | 是 | 是 | 是 | 是 |
| 聯絡人 | v3 | 是 | 是 | 是 | 是 | 是 |
| 聯絡人清單 | v1 | 否 | 是 | 否 | 是 | 否 |
| 交易 | v3 | 是 | 是 | 是 | 是 | 是 |
| CRM 管道 (交易管道) | v1 | 否 | 否 | 否 | 是 | 否 |
| 電子郵件事件 | v1 | 否 | 是 | 否 | 是 | 否 |
| 呼叫 | v3 | 是 | 是 | 是 | 是 | 是 |
| 備註 | v3 | 是 | 是 | 是 | 是 | 是 |
| 電子郵件 | v3 | 是 | 是 | 是 | 是 | 是 |
| 會議 | v3 | 是 | 是 | 是 | 是 | 是 |
| 任務 | v3 | 是 | 是 | 是 | 是 | 是 |
| 郵政郵件 | v3 | 是 | 是 | 是 | 是 | 是 |
| 自訂物件 | v3 | 是 | 是 | 是 | 是 | 是 |
| 表單 | v2 | 否 | 否 | 否 | 是 | 否 |
| 擁有者 | v3 | 否 | 是 | 否 | 是 | 否 |
| 產品 | v3 | 是 | 是 | 是 | 是 | 是 |
| 票證 | v3 | 是 | 是 | 是 | 是 | 是 |
| 工作流程 | v3 | 否 | 否 | 否 | 是 | 否 |
| 關聯 | v4 | 是 | 否 | 否 | 是 | 否 |
| 關聯標籤 | v4 | 否 | 否 | 否 | 是 | 否 |
**範例**：
```
hubspot_read = glueContext.create_dynamic_frame.from_options(
connection_type="hubspot",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "contact",
"API_VERSION": "v3"
}
```
## 非同步來源支援的實體
| 實體 | API 版本 | 可以篩選 | 支援限制 | 支援排序依據 | 支援選取 \$1 | 支援分區 |
| --- | --- | --- | --- | --- | --- | --- |
| 公司 | v3 | 是 | 否 | 是 | 是 | 否 |
| 聯絡人 | v3 | 是 | 否 | 是 | 是 | 否 |
| 交易 | v3 | 是 | 否 | 是 | 是 | 否 |
| 呼叫 | v3 | 是 | 否 | 是 | 是 | 否 |
| 備註 | v3 | 是 | 否 | 是 | 是 | 否 |
| 電子郵件 | v3 | 是 | 否 | 是 | 是 | 否 |
| 會議 | v3 | 是 | 否 | 是 | 是 | 否 |
| 任務 | v3 | 是 | 否 | 是 | 是 | 否 |
| 郵政郵件 | v3 | 是 | 否 | 是 | 是 | 否 |
| 自訂物件 | v3 | 是 | 否 | 是 | 是 | 否 |
| 產品 | v3 | 是 | 否 | 是 | 是 | 否 |
| 票證 | v3 | 是 | 否 | 是 | 是 | 否 |
**範例**：
```
hubspot_read = glueContext.create_dynamic_frame.from_options(
connection_type="hubspot",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "contact",
"API_VERSION": "v3",
"TRANSFER_MODE": "ASYNC"
}
```
**HubSpot 實體和欄位詳細資訊**：
**HubSpot API v4**：
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/hubspot-reading-from-entities.html)
**注意**
針對 `Associations` 物件，若要擷取兩個物件之間的關聯，您需要在建立 AWS Glue 任務時，透過強制性篩選條件提供 'from Id' （第一個物件的 ID)。在這種情況下，如果您想要擷取多個 ID 的關聯，則必須在 `where` 子句中提供多個 ID。例如：若要擷取聯絡人 ID '1' 和 '151' 的`Associations`，您需要提供一個篩選條件，如 `where id=1 AND id=151`。
**HubSpot API v3**：
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/hubspot-reading-from-entities.html)
對於下列實體，HubSpot 會提供端點來動態擷取中繼資料，以便在每個實體的資料類型層級擷取運算子支援。
**注意**
`DML_STATUS` 是在執行時期新增至每個記錄的虛擬欄位，以判斷其在同步模式中的狀態 (CREATED/UPDATED)。非同步模式不支援 `CONTAINS/LIKE` 運算子。
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/hubspot-reading-from-entities.html)
**HubSpot API v2**：
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/hubspot-reading-from-entities.html)
**HubSpot API v1**：
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/hubspot-reading-from-entities.html)
## 分區查詢
如果想要在 Spark 中使用並行，可以提供其他 Spark 選項 `PARTITION_FIELD`、`LOWER_BOUND`、`UPPER_BOUND` 和 `NUM_PARTITIONS`。使用這些參數，原始查詢會分區為可由 Spark 任務並行執行的子查詢的 `NUM_PARTITIONS` 數目。
+ `PARTITION_FIELD`：用來分區查詢的欄位名稱。
+ `LOWER_BOUND`：所選分區欄位的**包含**下限值。
對於 DateTime 欄位，接受 ISO 格式的值。
有效值的範例：
```
“2024-01-01T10:00:00.115Z"
```
+ `UPPER_BOUND`：所選分區欄位的**唯一**上限值。
+ `NUM_PARTITIONS`：分區數目。
下表說明實體分區欄位支援詳細資訊：
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/hubspot-reading-from-entities.html)
範例：
```
hubspot_read = glueContext.create_dynamic_frame.from_options(
connection_type="hubspot",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "company",
"API_VERSION": "v3",
"PARTITION_FIELD": "hs_object_id"
"LOWER_BOUND": "50"
"UPPER_BOUND": "16726619290"
"NUM_PARTITIONS": "10"
}
```
# 寫入到 HubSpot 實體
## 先決條件
+ 您要寫入到的 HubSpot 物件。將需要物件名稱，例如聯絡人或票證。
+ HubSpot 連接器支援下列寫入操作：
+ INSERT
+ UPDATE
+ 使用 `UPDATE` 寫入操作時，必須提供 `ID_FIELD_NAMES` 選項來指定記錄的 ID 欄位。
## 同步目的地的支援實體
| 實體 | API 版本 | 將支援為目的地連接器 | 可以插入 | 可以更新 |
| --- | --- | --- | --- | --- |
| 公司 | v3 | 是 | 是 (單一、大量) | 是 (單一、大量) |
| 聯絡人 | v3 | 是 | 是 (單一、大量) | 是 (單一、大量) |
| 交易 | v3 | 是 | 是 (單一、大量) | 是 (單一、大量) |
| 產品 | v3 | 是 | 是 (單一、大量) | 是 (單一、大量) |
| 呼叫 | v3 | 是 | 是 (單一、大量) | 是 (單一、大量) |
| 會議 | v3 | 是 | 是 (單一、大量) | 是 (單一、大量) |
| 備註 | v3 | 是 | 是 (單一、大量) | 是 (單一、大量) |
| 電子郵件 | v3 | 是 | 是 (單一、大量) | 是 (單一、大量) |
| 任務 | v3 | 是 | 是 (單一、大量) | 是 (單一、大量) |
| 郵政郵件 | v3 | 是 | 是 (單一、大量) | 是 (單一、大量) |
| 自訂物件 | v3 | 是 | 是 (單一、大量) | 是 (單一、大量) |
| 票證 | v3 | 是 | 是 (單一、大量) | 是 (單一、大量) |
| 關聯 | v4 | 是 | 是 (單一、大量) | 否 |
| 關聯標籤 | v4 | 是 | 是 (單一、大量) | 是 (單一、大量) |
**範例**：
**INSERT 操作**
```
hubspot_write = glueContext.write_dynamic_frame.from_options(
frame=frameToWrite,
connection_type="hubspot",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "contact",
"API_VERSION": "v3",
"WRITE_OPERATION": "INSERT"
}
)
```
**UPDATE 操作**
```
hubspot_write = glueContext.write_dynamic_frame.from_options(
frame=frameToWrite,
connection_type="hubspot",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "deal",
"API_VERSION": "v3",
"WRITE_OPERATION": "UPDATE",
"ID_FIELD_NAMES": "hs_object_id"
}
)
```
# HubSpot 連線選項
以下是 HubSpot 的連線選項：
+ `ENTITY_NAME`(String) - (必要) 用於讀取。HubSpot 中物件的名稱。
+ `API_VERSION`(String) - (必要) 用於讀取。您要使用的 HubSpot Rest API 版本。例如：v1、v2、v3、v4。
+ `SELECTED_FIELDS`(List) - 預設：empty(SELECT \$1)。用於讀取。您要為物件選取的資料欄。
+ `FILTER_PREDICATE`(String) - 預設：空白。用於讀取。其應該為 Spark SQL 格式。
+ `QUERY`(String) - 預設：空白。用於讀取。完整的 Spark SQL 查詢。
+ `PARTITION_FIELD`(String) - 用於讀取。用於分區查詢的欄位。
+ `LOWER_BOUND`(String) - 用於讀取。所選分區欄位的包含下限值。
+ `UPPER_BOUND`(String) - 用於讀取。所選分區欄位的唯一上限值。
+ `NUM_PARTITIONS`(Integer) - 預設：1。用於讀取。要讀取的分區數目。
+ `TRANSFER_MODE`(String) - 用於指示是否應在非同步模式下執行查詢。
+ `WRITE_OPERATION`(String) - 預設：INSERT。用於寫入。值應為 INSERT 或 UPDATE。
+ `ID_FIELD_NAMES`(String) - 預設：null。UPDATE 的必要項目。
# HubSpot 連接器的限制和備註
以下是 HubSpot 連接器的限制或備註：
+ 任何指定查詢的搜尋端點總結果限制為 1 萬個。任何超過 1 萬筆記錄的分區區都會導致 400 錯誤。
+ 連接器的其他重要限制如[限制](https://developers.hubspot.com/docs/api/crm/search#limitations)中所述。
+ HubSpot 最多接受三個篩選陳述式。
+ 目前，HubSpot 支援標準 HubSpot 物件 (例如聯絡人、公司、交易或票證) 與自訂物件之間的關聯。
+ 對於免費帳戶：每個物件配對 (例如聯絡人和公司) 之間最多只能建立 10 個關聯類型。
+ 對於超級管理員帳戶：每個物件配對之間最多只能建立 50 個關聯類型。
+ 如需詳細資訊，請參閱[關聯 v4](https://developers.hubspot.com/docs/api/crm/) 和[建立和使用關聯標籤](https://knowledge.hubspot.com/object-settings/create-and-use-association-labels)。
+ 關聯中不存在 'Quote' 和 'Communications' 物件，因為連接器目前不對其進行支援。
+ 對於非同步，SaaS 只會以遞增順序排序值。
+ 對於 `Ticket` 實體，SaaS 不會以非同步模式傳回 `hs_object_id` 欄位。