CloudWorks—This is How We Use It, Part 3: The CloudWorks API

[#1]

在我们的CloudWorks的第3部分中 - 这就是我们使用IT系列的方式，we will introduce you to the CloudWorks API.

这篇博客文章通常适用于对REST API概念和编程的观众。

如果您需要关于什么是Cloudworks的复习，请参阅第1部分，or on How to set it up, see第2部分。

CloudWorks API will allow you to create & execute connections and integrations extending integration automation capabilities between Amazon AWS S3 & Anaplan.

We will use a typical CloudWorks workflow to build and run integrations using REST API & Postman. To follow along, download the set of Jupyter Notebooks and data set that will walk you through each step of this workflow using Python (CloudWorksAPIBasic.zip and AccountDetailsS3.zip).

The following are minimum requirements to be able to perform the steps described in this blog.

• Required Software
  • Download & Install Postman (https://www.postman.com/downloads），Python 3.8.2，Jupyter笔记本。
  • Anaplan：Create a Model, LIST (Accounts), Module (AccountDetails), Import AccountDetailsS3.csv into LIST (Create Import Action), Import AccountDetailsS3.csv into Module (Create Import Action).
  • AWS S3：AWS帐户，创建访问密钥，秘密访问密钥，创建一个存储桶，上传源文件（accountdetailss3.csv）到S3存储桶。
• Working knowledge of Anaplan Model Building Concepts, REST API, Postman, Python, Jupyter.
• 熟悉Anaplan身份验证和集成REST API。

步骤1 -Anaplan设置

• Download AccountDetailsS3.csv from this blog and save it to your workstation.
• 创建一个新的Anaplan模型。提供适当的型号名称。
• 创建名称的列表帐户。Import AccountID into this LIST from AccountDetailsS3.csv.
• Create a Module named AccountDetails with帐户as a dimension.
• 创建以下行项目：
  • 帐户名（文本），行业（文本），年度收益（编号），imploeecount（编号）
• 导入AccountDetailss3.CSV到AccountDetails模块中。
• Import Action Name for LIST (Accounts): ______________________
• Import Action Name for Module (AccountDetails): __________________________

步骤2 -AWS设置

• Assumptions: AWS Access Key & Secret Access Key have been generated in AWS Console.
• Create an S3 bucket namedAnaplandemo。
• Create a folder named资源。
• 上传AccountDetailS3.csvAnaplandemo/来源in AWS S3.

Step 3 - Postman Setup

• Create a collection namedCloudworks。
• 在集合中创建以下文件夹结构Cloudworks。

• 我们将在API请求中使用变量。在集合中创建以下变量Cloudworks。

现在，我们已经完成了Anaplan，AWS S3＆Postman中所需的准备工作，我们将提出CloudWorks API请求，以构建和执行集成，以将数据从AWS S3加载到Anaplan。我们将遵循以下典型的CloudWorks任务中概述的步骤，以构建此集成。CloudWorks REST API请求将使用Postman提出。

Step 4 - CloudWorks API

Each Anaplan API request begins with generating an Authentication Token using Anaplan Authentication Services REST API. Generated Auth Token is then passed in the header of CloudWorks API request for Anaplan authentication. Keep in mind, Anaplan Authtoken is valid for only 30 min. Once expired, you will need to regenerate the token and update CloudWorks API header.

我们将在Postman中执行以下任务，以将AWS S3数据带到Anaplan。

• Create a connection: Using AWS S3 connector, we will create a CloudWorks connection to AWS S3 Bucket.
• 创建集成：使用AWS连接和Anaplan信息（WorkspaceID，ModelID，FileID，导入操作ID），我们将创建一个CloudWorks Integration。
• Run an integration: Run integration using CloudWorks API.
• 检索集成信息：获取集成运行信息。 

Generate Authentication Token (Basic Authentication)

The first step in any Anaplan API request, including CloudWorks, is generating Anaplan Authentication Token. The authentication token can be generated using Anaplan Authentication Services API. URL for authentication services ishttps://auth.anaplan.com/token/authentication。

Authentication Services API to generate token has the following REST structure:

方法	邮政
API终点	https://auth.anaplan.com/token/authenticate
Headers	Authorization: Basic username:password (username:password string must be base64 encoded)

Copy value fortokenValue收集变量token_value。您将在API请求中使用变量而不是硬编码值。令牌值每30分钟到期。您将需要重新生成一个令牌并更新token_value值变量如果遇到身份验证失败。

Create a Connection Using CloudWorks API

The first step in building a CloudWorks integration is to create a connection to AWS S3 bucket. PassingAuthToken在API请求的标题中，我们将在此步骤中创建与AWS S3存储桶的连接。Create Connection API具有以下REST结构。

方法	邮政
API终点	https://api.cloudworks.anaplan.com/1/0/integrations/connection
Authorization	No Auth
Headers	Authorization: AnaplanAuthToken {{token_value}} Content-Type: application/json
Body	{ “类型”：“ Amazons3”， "body": { "name":"AWS_CW_API", “ AccessKeyId”：“ XXXXXXXXXXXXXXXX”， "secretAccessKey":"XXXXXXXXXXXXXXXXXXXXXXX", “ bucketname”：“ anaplandemo” } } 不要更改“类型”的值。 Provide name for following elements: name, accessKeyId, secretAccessKey, & bucketName

• 选择POST方法和API终点。https://api.cloudworks.anaplan.com/1/0/integrations/connections.

• 为授权类型选择“ NOAUTH”。我们将在请求的标题中传递身份验证令牌。

• 创建以下标题：授权和内容类型。

• 将以下JSON结构复制到您的请求正文中。替换值accessKeyId，，，，secretAccessKey，，，，andbucketName带有您的价值观。

{

“类型”：“ Amazons3”，

"body": {

"name":"AWS_CW_API",

“ AccessKeyId”：“ XXXXXXXXXXXXXXXX”，

"secretAccessKey":"XXXXXXXXXXXXXXXXXXXXXXX",

“ bucketname”：“ anaplandemo”

}

}

• 一旦提交API请求,服务商店uld return a successful response back with HTTP code 200 and a value for connection id. You will save this connection id, to be used in the next API request in creating a CloudWorks integration. Copy the value forConnectionIDin a notepad and update it for collection variableconnection_id。

• 登录到Anaplan Cloudworks。您应该看到您在下面创建的连接Connections.

使用CloudWorks API创建集成

In this second step, we will create a CloudWorks integration. In the integration, we will provide connectivity information for both AWS S3 and Anaplan. Two types of integrations can be built:

• AWS S3 (Source)  Anaplan (Target): Data from a file on AWS S3 is selected as a source and Anaplan Import Action as a target.
• Anaplan（源）AWS S3：来自Anaplan的数据使用导出操作（源）导出，并写入AWS S3 Bucket（Target）上的文件。

Create integration API has the following REST structure:

方法	邮政
API终点	https://api.cloudworks.anaplan.com/1/0/integrations
Authorization	No Auth
Headers	Authorization: AnaplanAuthToken {{token_value}} Content-Type: application/json
Body	{ "name": "CWAPI_AWSS3_Anaplan", "jobs": [ { “ type”：“ amazons3toanaplan”， "sources": [ { “类型”：“ Amazons3”， “ ConnectionID”：“ A2FB43A9-3BC8-4BCB-9F37-DD59A75EEB940”， “ file”：“ source/accountss3.csv” } 这是给予的，，，， "targets": [ { “类型”：“ Anaplan”， "actionId": "112000000005", "fileId": "113000000000", "workspaceId": "8a81b09d5e8c6f27015ece3402487d33", “国防部elId": "35A6EF893D7F47EEA5A554D5CC7DC330" } 这是给予的 } 这是给予的 } Do not change the value for “type”: “AmazonS3ToAnaplan”, “type”:”AmazonS3”, “type”:”Anaplan” 为以下元素提供值：ConnectionID，ActionID，FileID，WorkspaceID，ModelID。

• 选择帖子方法和API终点https://api.cloudworks.anaplan.com/1/0/integrations。另外，选择授权的“无验证”。

• 创建以下标题：授权和内容类型

• 将以下JSON结构复制到您的请求正文中。替换值ConnectionID，，，，file，，，，ActionID，FileID，WorkspaceID和ModelID。您可以使用Anaplan Integration API获得导入操作（ActionID）和数据源文件（FileID）的值。详细信息集成APIcan be found on Anapedia. You can obtain values for workspaceId & modeled from Anaplan UX.

{

"name": "CWAPI_AWSS3_Anaplan",

"jobs": [

{

“ type”：“ amazons3toanaplan”，

"sources": [

{

“类型”：“ Amazons3”，

“ ConnectionID”：“ A2FB43A9-3BC8-4BCB-9F37-DD59A75EEB940”，

“ file”：“ source/accountss3.csv”

}

这是给予的，，，，

"targets": [

{

“类型”：“ Anaplan”，

"actionId": "112000000005",

"fileId": "113000000000",

"workspaceId": "8a81b09d5e8c6f27015ece3402487d33",

“国防部elId": "35A6EF893D7F47EEA5A554D5CC7DC330"

}

这是给予的

}

这是给予的

}

• 一旦提交API请求,服务商店uld return a successful response back with HTTP code 200 and a value for integration id. Copy & paste value forintegrationId收集变量s3_anaplan_int_id。We will useintegrationIdin a later step when we gather run details for an integration.

• 登录到Anaplan Cloudworks。You should see the integration you created underIntegrations.

Run an Integration Using CloudWorks API

Now that we have created an integration, we will run the integration that loads data from a file on AWS S3 bucket to an Anaplan module. Once the integration is run, we will retrieve a history of integration runs and its details. We will do this in the next step. CloudWorks APIs can be used to schedule integrations. However, in this blog, we will focus on executing integrations via API.

You will need to provide the following details in your API request:

方法	邮政
API终点	https://api.cloudworks.anaplan.com/1/0/integrations//run
Authorization	No Auth
Headers	Authorization: AnaplanAuthToken {{token_value}} Content-Type: application/json
Body	None

• 选择帖子方法和API终点https://api.cloudworks.anaplan.com/1/0/integrations。另外，选择授权的“无验证”。

• 创建以下标题：授权和内容类型

• 提交API请求后，该服务应以HTTP代码200返回成功的响应。亚搏彩票手机版免费下载

• View integration run status & details in Anaplan CloudWorks UX.

• 如果集成运行失败，还将通过电子邮件通知您。

获取集成史的历史

CloudWorks API provides end points to get details on integration run history. REST structure for this end point is:

方法	GET
API终点	https://api.cloudworks.anaplan.com/1/0/integrations/runs/
参数	Offset = 0 限制= 2
Authorization	No Auth
Headers	Authorization: AnaplanAuthToken {{token_value}} Content-Type: application/json
Body	None

• 选择帖子方法和API终点https://api.cloudworks.anaplan.com/1/0/integrations/runs/。Also select “No Auth” for Authorization.

• 创建两个参数偏移和限制。将其值分别设置为0和2。

• 创建以下标题：授权和内容类型

• The service request should return a successful response back with HTTP code 200 and details for each run for selected integration.

[Jareddolich]

@annejulie杰出的。谢谢你。