cap-connector-dev

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Scope Note

范围说明

This skill is for Domo Custom Connector IDE projects.
It is not for Domo App Platform custom app/card builds.

本技能适用于Domo Custom Connector IDE项目。
不适用于Domo App Platform自定义应用/卡片构建。

Rule: Domo Custom Connector Development

规则：Domo Custom Connector开发

You are building a custom Domo connector (data connector or writeback connector) using the Domo IDE. Custom connectors allow you to integrate external APIs and data sources into Domo.

Note: This rule covers custom connector development in the Domo IDE, not custom app development. Custom connectors run server-side after being published via the custom connector IDE

你正在使用Domo IDE构建自定义Domo连接器（数据连接器或回写连接器）。自定义连接器可让你将外部API和数据源集成到Domo中。

注意： 本规则涵盖Domo IDE中的自定义连接器开发，而非自定义应用开发。自定义连接器通过自定义连接器IDE发布后在服务器端运行

Prerequisites

前提条件

Access to Domo's Custom Connector IDE
Understanding of the external API you're integrating with
Knowledge of JavaScript (connectors are written in JavaScript)

拥有Domo Custom Connector IDE的访问权限
了解你要集成的外部API
掌握JavaScript知识（连接器使用JavaScript编写）

File Structure

文件结构

Custom connectors consist of JavaScript files:

authentication.js
— Validates credentials and authenticates with the external API
dataProcessing.js
— Fetches and processes data from the external API
README.md
— Documents available reports/parameters for the connector

All files should be written in JavaScript (

.js

自定义连接器由JavaScript文件组成：

authentication.js
— 验证凭据并与外部API进行身份验证
dataProcessing.js
— 从外部API获取并处理数据
README.md
— 记录连接器的可用报表/参数

所有文件都应使用JavaScript（

.js

）编写。

Common Patterns

常见模式

Authentication Pattern

身份验证模式

javascript

// Validate input format
let tokenFormat = /^[a-zA-Z0-9_-]+$/;
let accessToken = metadata.account.apikey;

if (tokenFormat.test(accessToken)) {
    httprequest.addHeader('Accept', 'application/json');
    httprequest.addHeader('Authorization', `Bearer ${accessToken}`);
    
    // Test authentication with a simple API call
    let res = httprequest.get('https://api.example.com/test');
    let statusCode = httprequest.getStatusCode();
    
    if (statusCode === 200) {
        auth.authenticationSuccess();
    } else {
        auth.authenticationFailed('Authentication failed. Please check your credentials.');
    }
} else {
    auth.authenticationFailed('Invalid token format.');
}

javascript

// Validate input format
let tokenFormat = /^[a-zA-Z0-9_-]+$/;
let accessToken = metadata.account.apikey;

if (tokenFormat.test(accessToken)) {
    httprequest.addHeader('Accept', 'application/json');
    httprequest.addHeader('Authorization', `Bearer ${accessToken}`);
    
    // Test authentication with a simple API call
    let res = httprequest.get('https://api.example.com/test');
    let statusCode = httprequest.getStatusCode();
    
    if (statusCode === 200) {
        auth.authenticationSuccess();
    } else {
        auth.authenticationFailed('Authentication failed. Please check your credentials.');
    }
} else {
    auth.authenticationFailed('Invalid token format.');
}

Data Processing Pattern

数据处理模式

javascript

// Set headers
httprequest.addHeader('Accept', 'application/json');
httprequest.addHeader('Authorization', `Bearer ${metadata.account.apikey}`);

// Determine endpoint based on report selection
let endpoint = '';
switch(metadata.report) {
    case 'Report1':
        endpoint = 'https://api.example.com/data1';
        break;
    case 'Report2':
        endpoint = 'https://api.example.com/data2';
        break;
}

// Fetch and process data with pagination
let URL = endpoint;
do {
    let res = httprequest.get(URL);
    let statusCode = httprequest.getStatusCode();
    
    if (statusCode !== 200) {
        throw new Error(`API request failed: ${statusCode}`);
    }
    
    let responseData = JSON.parse(res);
    
    // Parse JSON array into Domo dataset
    datagrid.magicParseJSON(responseData.results);
    
    // Handle pagination
    URL = responseData.paging?.next?.link || false;
} while (URL);

javascript

// Set headers
httprequest.addHeader('Accept', 'application/json');
httprequest.addHeader('Authorization', `Bearer ${metadata.account.apikey}`);

// Determine endpoint based on report selection
let endpoint = '';
switch(metadata.report) {
    case 'Report1':
        endpoint = 'https://api.example.com/data1';
        break;
    case 'Report2':
        endpoint = 'https://api.example.com/data2';
        break;
}

// Fetch and process data with pagination
let URL = endpoint;
do {
    let res = httprequest.get(URL);
    let statusCode = httprequest.getStatusCode();
    
    if (statusCode !== 200) {
        throw new Error(`API request failed: ${statusCode}`);
    }
    
    let responseData = JSON.parse(res);
    
    // Parse JSON array into Domo dataset
    datagrid.magicParseJSON(responseData.results);
    
    // Handle pagination
    URL = responseData.paging?.next?.link || false;
} while (URL);

Error Handling

错误处理

javascript

try {
    let res = httprequest.get(url);
    let statusCode = httprequest.getStatusCode();
    
    if (statusCode !== 200) {
        let errorMsg = `Request failed: ${statusCode}`;
        try {
            let errorData = JSON.parse(res);
            if (errorData.message) {
                errorMsg = errorData.message;
            }
        } catch (e) {
            errorMsg += `. Response: ${res.substring(0, 200)}`;
        }
        throw new Error(errorMsg);
    }
    
    // Process successful response
    let data = JSON.parse(res);
    datagrid.magicParseJSON(data.results);
    
} catch (error) {
    // Handle error appropriately
    throw error;
}

javascript

try {
    let res = httprequest.get(url);
    let statusCode = httprequest.getStatusCode();
    
    if (statusCode !== 200) {
        let errorMsg = `Request failed: ${statusCode}`;
        try {
            let errorData = JSON.parse(res);
            if (errorData.message) {
                errorMsg = errorData.message;
            }
        } catch (e) {
            errorMsg += `. Response: ${res.substring(0, 200)}`;
        }
        throw new Error(errorMsg);
    }
    
    // Process successful response
    let data = JSON.parse(res);
    datagrid.magicParseJSON(data.results);
    
} catch (error) {
    // Handle error appropriately
    throw error;
}

Important Notes

重要说明

Input Sanitization — Always sanitize inputs (like API keys) to prevent cross-site scripting and SQL injection attacks
Consistent Columns — Every row in the dataset must have the same number of columns (use
```
null
```
for missing values)
Use Domo-provided JavaScript Library - These methods are provided by Domo in the Connector Dev Studio to make it easier for you to build your custom connector. You can reference them here: https://developer.domo.com/portal/e415bb99d21b2-reference
JSON Parsing — When APIs return JSON arrays, use
```
datagrid.magicParseJSON(jsonString)
```
instead of manual parsing
Error Messages — Provide clear, actionable error messages in
```
auth.authenticationFailed()
```

输入清理 — 始终清理输入（如API密钥）以防止跨站脚本和SQL注入攻击
列一致性 — 数据集中的每一行必须具有相同数量的列（缺失值使用
```
null
```
填充）
使用Domo提供的JavaScript库 - 这些方法由Domo在Connector Dev Studio中提供，可帮助你更轻松地构建自定义连接器。你可以在此处参考它们：https://developer.domo.com/portal/e415bb99d21b2-reference
JSON解析 — 当API返回JSON数组时，使用
```
datagrid.magicParseJSON(jsonString)
```
而非手动解析
错误消息 — 在
```
auth.authenticationFailed()
```
中提供清晰、可操作的错误消息

Checklist

检查清单

```
authentication.js
```
validates input format and tests credentials

authentication.js

calls

auth.authenticationSuccess()

auth.authenticationFailed()

appropriately

```
dataProcessing.js
```
handles pagination correctly
```
dataProcessing.js
```
checks HTTP status codes before parsing JSON

dataProcessing.js

uses

datagrid.magicParseJSON()

for JSON arrays

All inputs are sanitized to prevent security vulnerabilities
Error handling provides clear messages
```
README.md
```
documents all available reports/parameters
All rows have consistent column counts

```
authentication.js
```
验证输入格式并测试凭据

authentication.js

正确调用

auth.authenticationSuccess()

或

auth.authenticationFailed()

```
dataProcessing.js
```
正确处理分页
```
dataProcessing.js
```
在解析JSON前检查HTTP状态码

dataProcessing.js

对JSON数组使用

datagrid.magicParseJSON()

所有输入都经过清理以防止安全漏洞
错误处理提供清晰的消息
```
README.md
```
记录所有可用的报表/参数
所有行的列数一致