# 连接到 Microsoft Dynamics 365 CRM


 Microsoft Dynamics 365 是一系列企业资源规划和客户关系管理智能业务应用程序产品。

**Topics**
+ [

# Amazon Glue 对 Microsoft Dynamics 365 的支持
](microsoft-dynamics-365-support.md)
+ [

# 包含创建和使用连接的 API 操作的策略
](microsoft-dynamics-365-configuring-iam-permissions.md)
+ [

# 配置 Microsoft Dynamics 365 CRM
](microsoft-dynamics-365-configuring.md)
+ [

# 配置 Microsoft Dynamics 365 CRM 连接
](microsoft-dynamics-365-configuring-connections.md)
+ [

# 从 Microsoft Dynamics 365 CRM 实体读取
](microsoft-dynamics-365-reading-from-entities.md)
+ [

# Microsoft Dynamics 365 CRM 连接选项参考
](microsoft-dynamics-365-connection-options.md)
+ [

# 限制
](microsoft-dynamics-365-connector-limitations.md)

# Amazon Glue 对 Microsoft Dynamics 365 的支持


Amazon Glue 支持 Microsoft Dynamics 365，如下所示：

**是否支持作为来源？**  
是。可以使用 Amazon Glue ETL 作业查询 Microsoft Dynamics 365 中的数据。

**是否支持作为目标？**  
否。

**支持的 Microsoft Dynamics 365 CRM API 版本**  
 v9.2。

# 包含创建和使用连接的 API 操作的策略
IAM 策略

 以下示例策略描述了创建和使用连接所需的 Amazon 权限。如果您要创建新角色，请创建包含以下内容的策略：

------
#### [ JSON ]

****  

```
{
  "Version":"2012-10-17",		 	 	 
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "glue:ListConnectionTypes",
        "glue:DescribeConnectionType",
        "glue:RefreshOAuth2Tokens",
        "glue:ListEntities",
        "glue:DescribeEntity"
      ],
      "Resource": "*"
    }
  ]
}
```

------

您还可以使用以下托管 IAM 策略允许访问权限：
+  [AWSGlueServiceRole](https://console.amazonaws.cn/iam/home#policies/arn:aws:iam::aws:policy/service-role/AWSGlueServiceRole)：授予对各种 Amazon Glue 进程代表您运行所需的资源的访问权限。这些资源包括 Amazon Glue、Amazon S3、IAM、CloudWatch Logs 和 Amazon EC2。如果您遵循此策略中指定的资源的命名约定，则 Amazon Glue 进程具有所需的权限。此策略通常附加到在定义爬网程序、作业和开发终端节点时指定的角色。
+  [AWSGlueConsoleFullAccess](https://console.amazonaws.cn/iam/home#policies/arn:aws:iam::aws:policy/AWSGlueConsoleFullAccess)：当策略所附加到的身份使用 Amazon 管理控制台时，授予对 Amazon Glue 资源的完全访问权限。如果遵循此策略中指定的资源的命名约定，则用户具有完全控制台功能。此策略通常附加到 Amazon Glue 控制台的用户。

# 配置 Microsoft Dynamics 365 CRM


必须满足以下要求，才能使用 Amazon Glue 从 Microsoft Dynamics 365 CRM 传输数据：

## 最低要求

+  您有一个带有 ClientId 和密钥的 Microsoft Dynamics 365 CRM 开发人员账户。
+  您的 Microsoft Dynamics 365 CRM 账户拥有 API 访问权限及有效的许可证。

 如果满足这些要求，就可以将 Amazon Glue 连接到 Microsoft Dynamics 365 CRM 账户。对于常见连接，无需在 Microsoft Dynamics 365 CRM 中执行任何其他操作。

# 配置 Microsoft Dynamics 365 CRM 连接


 **AUTHORIZATION\$1CODE 授权类型** 
+  此授权类型被视为“三足型”OAuth，因为它依赖于将用户重定向到第三方授权服务器来对用户进行身份验证。它用于通过 Amazon Glue 控制台创建连接。Amazon Glue 控制台会将用户重定向到 Microsoft Dynamics 365 CRM，用户必须在此登录并向 Amazon Glue 授予所请求的权限，以访问其 Microsoft Dynamics 365 CRM 实例。
+  用户可以选择在 Microsoft Dynamics 365 CRM 中创建自己的关联应用程序，并在通过 Amazon Glue 控制台创建连接时，提供自己的客户端 ID 和客户端密钥。在这种情况下，他们仍会重定向到 Microsoft Dynamics 365 CRM，以便登录并授权 Amazon Glue 访问其资源。
+  此授权类型会生成刷新令牌和访问令牌。访问令牌的有效期很短，可以通过刷新令牌在不需要用户干预的情况下自动刷新。
+  有关为授权码 OAuth 流创建关联应用程序的 Microsoft Dynamics 365 CRM 公共文档，请参阅 \$1 Microsoft Learn。[Microsoft 应用程序注册](https://learn.microsoft.com/en-us/power-apps/developer/data-platform/authenticate-oauth#app-registration)。

Microsoft Dynamics 365 CRM 支持 OAuth2.0 身份验证。

配置 Microsoft Dynamics 365 CRM 连接：

1.  在 Amazon Secrets Manager 中，创建一个包含以下详细信息的密钥。需要为 Amazon Glue 中的每个连接创建一个密钥。
   +  对于 AuthorizationCode 授权类型：

      对于客户托管的关联应用程序：密钥应包含关联应用程序的客户端密钥，并将 `USER_MANAGED_CLIENT_APPLICATION_CLIENT_SECRET` 作为键。

1. 在 Amazon Glue Studio 中，按照以下步骤在**数据连接**下创建连接：

   1. 选择**数据来源**时，请选择 Microsoft Dynamics 365 CRM。

   1. 选择想要连接到的 Microsoft Dynamics 365 CRM 实例的 **INSTANCE\$1URL** 。

   1.  选择 Amazon Glue 可以担任并有权执行以下操作的 IAM 角色：

------
#### [ JSON ]

****  

      ```
      {
        "Version":"2012-10-17",		 	 	 
        "Statement": [
          {
            "Effect": "Allow",
            "Action": [
              "secretsmanager:DescribeSecret",
              "secretsmanager:GetSecretValue",
              "secretsmanager:PutSecretValue",
              "ec2:CreateNetworkInterface",
              "ec2:DescribeNetworkInterfaces",
              "ec2:DeleteNetworkInterface"
            ],
            "Resource": "*"
          }
        ]
      }
      ```

------

   1.  选择**令牌 URL** 和**授权码 URL** 以访问您的 Microsoft Dynamics 365 CRM 工作区。

   1.  提供 Microsoft Dynamics 365 CRM 应用程序的**用户托管客户端应用程序 ClientId**。

   1.  在 Amazon Glue 中选择您要用于此连接的 `secretName`，然后放置令牌。

   1.  如果要使用网络，请选择网络选项。

1.  向与您的 Amazon Glue 作业关联的 IAM 角色授予读取 `secretName` 的权限。选择**下一步**。

1.  在 Amazon Glue 作业配置中，提供 `connectionName` 作为**附加网络连接**。

# 从 Microsoft Dynamics 365 CRM 实体读取


 **先决条件** 
+  要从中读取内容的 Microsoft Dynamics 365 CRM 对象。您将需要联系人或账户等对象名称。下表显示支持的实体。

 **支持的实体** 


| 实体 | 可以筛选 | 支持限制 | 支持排序依据 | 支持 Select \$1 | 支持分区 | 
| --- | --- | --- | --- | --- | --- | 
| 动态实体 | 支持 | 是 | 是 | 是 | 是 | 

 **示例** 

```
dynamics365_read = glueContext.create_dynamic_frame.from_options(
    connection_type="microsoftdynamics365crm",
    connection_options={
        "connectionName": "connectionName",
        "ENTITY_NAME": "dynamic_entity",
        "API_VERSION": "v9.2",
        "INSTANCE_URL": "https://{tenantID}.api.crm.dynamics.com"
    }
```

## Microsoft Dynamics 365 CRM 实体和字段详细信息


 **具有动态元数据的实体**：

Microsoft Dynamics 365 CRM 提供用于动态获取元数据的端点。因此，对于动态实体，可在数据类型级别捕获运算符支持。

<a name="microsoft-dynamics-365-metadata-table"></a>[\[See the AWS documentation website for more details\]](http://docs.amazonaws.cn/glue/latest/dg/microsoft-dynamics-365-reading-from-entities.html)

 **对查询进行分区** 

Microsoft Dynamics 365 CRM 仅支持基于字段的分区。

 如果您想在 Spark 中利用并发，可以提供附加 Spark 选项 `PARTITION_FIELD`、`LOWER_BOUND`、`UPPER_BOUND` 和 `NUM_PARTITIONS`。使用这些参数，原始查询将被拆分为 `NUM_PARTITIONS` 个子查询，这些子查询可以由 Spark 任务同时执行。
+  `PARTITION_FIELD`：用于对查询进行分区的字段的名称。
+  `LOWER_BOUND`：所选分区字段的包含下限值。

   对于日期时间，我们接受 Spark SQL 查询中使用的 Spark 时间戳格式。有效值示例：`"2024-01-30T06:47:51.000Z"`。
+  `UPPER_BOUND`：所选分区字段的排除上限值。
+  `NUM_PARTITIONS`：分区的数量。

 基于实体的分区字段支持详细信息如下表中所示：


| 实体名称 | 分区字段 | DataType | 
| --- | --- | --- | 
| 动态实体（标准实体） | 可查询的动态日期时间字段 | createdon、modifiedon | 
| 动态实体（自定义实体） | createdon、modifiedon | createdon、modifiedon | 

 **示例** 

```
dynamics365_read = glueContext.create_dynamic_frame.from_options(
    connection_type="microsoftdynamics365crm",
    connection_options={
        "connectionName": "connectionName",
        "ENTITY_NAME": "dynamic_entity",
        "API_VERSION": "v9.2",
        "instanceUrl": "https://{tenantID}.api.crm.dynamics.com"
        "PARTITION_FIELD": "createdon"
        "LOWER_BOUND": "2024-01-30T06:47:51.000Z"
        "UPPER_BOUND": "2024-06-30T06:47:51.000Z"
        "NUM_PARTITIONS": "10"
    }
```

# Microsoft Dynamics 365 CRM 连接选项参考


以下是 Microsoft Dynamics 365 CRM 的连接选项：
+  `ENTITY_NAME`（字符串）：（必填）用于读取。Microsoft Dynamics 365 CRM 中对象的名称。
+  `API_VERSION`（字符串）：（必填）用于读取。要使用的 Microsoft Dynamics 365 CRM Rest API 版本。
+  `SELECTED_FIELDS`（列表<字符串>）–默认：empty(SELECT \$1)。用于读取。您想要为对象选择的列。
+  `FILTER_PREDICATE`（字符串）– 默认：空。用于读取。应采用 Spark SQL 格式。
+  `QUERY`（字符串）– 默认：空。用于读取。完整的 Spark SQL 查询。
+  `INSTANCE_URL`（字符串）：（必填）有效的 Microsoft Dynamics 365 CRM 实例 URL，格式为：`https://{tenantID}.api.crm.dynamics.com`
+  `NUM_PARTITIONS`（整数）– 默认：1。用于读取。要读取的分区数。
+  `PARTITION_FIELD`（字符串）– 用于读取。用于分区查询的字段。
+  `LOWER_BOUND`（字符串）– 用于读取。所选分区字段的包含下限值。示例：`2024-01-30T06:47:51.000Z`。
+  `UPPER_BOUND`（字符串）– 用于读取。所选分区字段的排除上限值。示例：`2024-06-30T06:47:51.000Z`。

# 限制


以下是 Microsoft Dynamics 365 CRM 连接器的限制：
+  Microsoft Dynamics 365 CRM 中不支持基于记录的分区，因为其不支持偏移参数，因此无法支持基于记录的分区。
+  分页设置为每页最多 500 条记录，以避免 SaaS 因数据大小和速率限制组合而导致内部服务器异常。
  + [关于分页的 SaaS 文档](https://learn.microsoft.com/en-us/power-apps/developer/data-platform/webapi/query/page-results?view=dataverse-latest)
  + [关于速率限制的 SaaS 文档](https://learn.microsoft.com/en-us/power-apps/developer/data-platform/api-limits?tabs=sdk)
+  Microsoft Dynamics 365 CRM 仅对所有实体的父字段支持 `order by`。子字段不支持 `order by`。
  + ASC 和 DESC 方向排序均支持。
  + 对多个字段支持 `order by`。
+  对 `aadusers` 标准实体的“createddatetime”字段进行筛选会引发来自 SaaS 的不正确的请求错误，尽管该字段支持筛选。由于元数据的动态性质，尚无特定证据显示任何其他实体存在类似问题，也无法确定根本原因。因此，无法处理该问题。
+  Struct、List 和 Map 等复杂对象类型不支持筛选。
+  在动态元数据响应中，许多可以从响应中检索的字段都将 `isRetrievable` 标记为 `false`。为避免数据丢失，所有字段的 `isRetrievable` 均设置为 `true`。
+  如果满足以下标准，则所有实体均支持基于字段的分区：
  + 标准实体中应包含日期时间可查询字段，或者自定义实体中应包含 `createdon` 和 `modifiedon`（系统生成）字段。
  + 任何 SaaS 元数据 API 都没有系统生成字段的专属标识或可为空属性，但通用的做法是：只有默认提供的字段方可筛选且不可为空。因此，上述字段选择标准被视为空值安全，如果其可筛选，则符合分区的条件。