可起草比较 API - Node.js 客户端库

一个细的 JavaScript 客户端 可起草的 API 将所有可用的端点包起来,并处理认证和签名.

见 aPI 完整文档 用于介绍API、使用说明和其他参考材料.

• 所需资源
• 开始
• API 参考
  • 初始化客户端
  • 获取比较
  • 删除比较
  • 创建比较
  • 显示比较
  • 导出比较
  • 工具函数
• 其他资料
  • 浏览器支持
  • 自签名证书
• 许可证

所需资源

• 操作系统:任意维护的 Linux, macOS, 或 Windows 发布
• 节点.js 运行时间: 任意 维护版本

开始

• 创建免费 API 账户
• 获取你的 全权证书
• 安装库

npm install @draftable/compare-api

• 向客户提供证据

var client = require('@draftable/compare-api').client('<yourAccountId>', '<yourAuthToken>');
var comparisons = client.comparisons;

• 开始创建比较

comparisons.create({
    left: {
        source: 'https://api.draftable.com/static/test-documents/code-of-conduct/left.rtf',
        fileType: 'rtf',
    },
    right: {
        source: 'https://api.draftable.com/static/test-documents/code-of-conduct/right.pdf',
        fileType: 'pdf',
    },
}).then(function(comparison) {
    console.log("Comparison created: %s", comparison);
    // Generate a signed viewer URL to access the private comparison. The expiry
    // time defaults to 30 minutes if the valid_until parameter is not provided.
    const viewerURL = comparisons.signedViewerURL(comparison.identifier);
    console.log("Viewer URL (expires in 30 mins): %s", viewerURL);
});

API 参考

• 所有 API 请求返回 承诺数字 :
  • 成功调用返回数据决心 Comparison 对象
  • 成功调用不返回数据决心 null (例如a) DELETE 请求)
  • 以任何理由失败的电话会拒绝 Promise 带有 Error 对象

初始化客户端

软件包导出一个创建函数 Client 你的API账户.

Client 页:1 comparisons 属性生成 a ComparisonsClient 用于管理您的 API 账户的比较.

创建一个 Client 根据使用的 API 端点略有不同 :

// Draftable API (default endpoint)
var comparisons = require('@draftable/compare-api').client(
    '<yourAccountId>',  // Replace with your API credentials from:
    '<yourAuthToken>'   // https://api.draftable.com/account/credentials
).comparisons;

// Draftable API regional endpoint or Self-hosted
var comparisons = require('@draftable/compare-api').client(
    '<yourAccountId>',  // Replace with your API credentials from the regional
    '<yourAuthToken>',  // Draftable API endpoint or your Self-hosted container
    'https://draftable.example.com/api/v1'  // Replace with the endpoint URL
).comparisons;

对于 API 您可能需要自行托管 压制 TLS 证书验证 如果服务器使用自签名的证书(默认值).

获取比较

• getAll()
  回返a Promise 它决定了你们所有比较的列表 从最新的到最古老的 这可能是一项昂贵的行动.
• get(identifier: string)
  回返a Promise 解决指定的 Comparison 如果指定的比较标识符不存在,则拒绝.

Comparison 对象具有下列属性:

• identifier: string
  比较的独特标识符
• left: object 编号 : right: object
  比较的两边信息
  • fileType: string
    文件扩展名
  • sourceURL: string (可选)
    如果原始请求由 URL 指定, 文件的 URL
  • displayName: string (可选)
    如果在原始请求中给出文件的显示名称
• publiclyAccessible: boolean
  说明比较是否公开
• creationTime: Date
  在协调世界时创建比较的时间
• expiryTime: Date (可选)
  比较期的到期时间
• ready: boolean
  显示是否准备显示比较

如果有的话 Comparison 实值 准备 (即已处理)它有下列其他属性:

• failed: boolean
  显示比较处理失败
• errorMessage: string (仅在 failed(中文(简体) )
  比较处理失败

示例用途

var identifier = '<identifier>';

comparisons.get(identifier).then(function(comparison) {
    const visibility = comparison.publiclyAccessible ? 'private' : 'public';
    const status = comparison.ready ? 'ready' : 'not ready';
    console.log("Comparison '%s' (%s) is %s.", comparison.identifier, visibility, status);

    if (comparison.ready && comparison.failed) {
        console.log("The comparison failed with error: %s", comparison.errorMessage);
    }
});

删除比较

• destroy(identifier: string)
  回返a Promise 如果不存在这种比较,则决定成功删除指定的比较或拒绝.

示例用途

comparisons.getAll().then(function(oldest_comparisons) {
    console.log("Deleting oldest 10 comparisons ...");
    const deleteStartIndex = Math.max(0, oldest_comparisons.length - 10);

    for (let i = deleteStartIndex; i < oldest_comparisons.length; ++i) {
        const identifier = oldest_comparisons[i].identifier;
        comparisons.destroy(identifier).then(function() {
            console.log("Comparison '%s' deleted.", identifier);
        });
    }
});

创建比较

• create(options)
  回返a Promise 它决定了一个新的 Comparison 对象.

options 由下列参数组成:

• left: object 编号 : right: object
  描述左右文件(见下文)
• identifier: string (可选)
  用于比较的标识符:
  • 如果指定,标识符必须是独一无二的(即尚未使用)
  • 如果未指定, API 将自动生成一个独特的标识符
• publiclyAccessible: boolean (可选)
  指定比较可见度 :
  • 若为 false 查看比较时需要使用或未说明的认证
  • 若为 true 任何熟悉 URL 的人都可以访问此比较
• expires: Date | string (可选)
  删除比较的时间 :
  • 必须指定为 Date 对象或一个 string 可以用 Date.parse
  • 如果指明,规定的终止时间必须是世界协调时,而且今后
  • 如果未作说明,比较将永远不会到期(但可明确删除)

options.left 财务报告和审定财务报表 options.right 由下列参数组成:

• source: buffer | string
  指定比较的这一侧源 :
  • 提供时 buffer,包含文件数据(例如. {source: fs.readFileSync('path/to/file')}(中文(简体) )
  • 提供时 string,服务器将从中下载文件的URL(例如. {source: 'https://example.com/path/to/file'}(中文(简体) )
• fileType: string
  提交文件的类型 :
  • PDF : (英语) pdf
  • 词: docx, (中文(简体) ), docm, (中文(简体) ), doc, (中文(简体) ), rtf
  • 电源点 : pptx, (中文(简体) ), pptm, (中文(简体) ), ppt
  • 文本 : txt
• displayName: string (可选)
  比较查看器中显示的文件名称

示例用途

var identifier = comparisons.generateIdentifier();

comparisons.create({

    identifier: identifier,

    left: {
        source: 'https://domain.com/left.pdf',
        fileType: 'pdf',
        displayName: 'Document.pdf',
    },

    right: {
        source: fs.readFileSync('path/to/right/file.docx'),
        fileType: 'docx',
        displayName: 'Document (revised).docx',
    },

    // Expire this comparison in 2 hours (default is no expiry)
    expires: new Date(Date.now() + 1000 * 60 * 120),

}).then(function(comparison) {
    console.log("Created comparison: %s", comparison);
});

显示比较

• publicViewerURL(identifier: string, wait?: boolean)
  生成用于指定比较的公共查看器 URL
• signedViewerURL(identifier: string, valid_until?: Date | string, wait?: boolean)
  为指定的比较生成一个签名的查看器 URL

这两个函数都使用以下共同参数:

• identifier
  用于生成 查看器 URL
• wait (可选)
  指定所提供比较不存在的查看者的行为
  • 若为 false 或未说明,如果 identifier 不存在
  • 若为 true,观看者将等待 与提供的比较 identifier 存在
    注意,如果 identifier 从未创建

这个 signedViewerURL 函数还支持以下参数:

• valid_until (可选)
  URL 到期时间( 不再装入)
  • 必须指定为 Date 对象或一个 string 可以用 Date.parse
  • 如果指明,规定的终止时间必须是世界协调时,而且今后
  • 如果未指定, URL 将随着默认的30分钟到期生成

参见 API 文档 其他细节.

示例用途

var identifier = '<identifier>'

// Retrieve a signed viewer URL which is valid for 1 hour. The viewer will wait
// for the comparison to exist in the event processing has not yet completed.
var valid_until = new Date(Date.now() + 1000 * 60 * 60)
var viewerURL = comparisons.signedViewerURL(identifier, valid_until, true);
console.log("Viewer URL (expires in 1 hour): %s", viewerURL);

导出比较

通过发送比较标识符和所请求的导出类型,导出与PDF的比较.

• 支持四种出口类型.
  • 单页: 仅显示右侧文档并显示显示 diff 的突出显示和删除标记
  • 组合:显示左右两侧
  • 左: 只显示左侧
  • 右: 只显示右侧

在创建导出后, 您必须使用导出标识符进行投票以获取导出文档的 URL .

Export 对象具有下列属性:

• identifier: string 导出的唯一标识符
• comparison: string 比较的独特标识符
• url: string
  如果原始请求由 URL 指定, 文件的 URL
• kind: string 导出类型,以下一种 single_page, (中文(简体) ), combined左侧或 right
• ready: boolean 说明出口是否准备得到
• failed: boolean 显示导出失败

导出示例使用

出口后要求

client.exports
  .requestExport({
    comparison: "<identifier>",
    kind: "combined",
    include_cover_page: false,
  })
  .then((result: ExportResult) => {
    console.log(result);
  }

获取请求导出

client.exports.get(requestResponse.identifier).then((result: ExportResult) => {
    console.log(result);
  });

工具函数

• generateIdentifier()
  生成随机唯一比较标识符

其他资料

浏览器支持

此库主要为服务器侧使用而设计. 目前不支持在网页浏览器(客户端-侧面)中使用.

通过客户端 JavaScript 调用可起草的 API 被普遍劝阻,因为这意味着与最终用户共享 API 证书 .

自签名证书

如果连接到一个使用自签名证书( 默认) 的 API 自动托管端点, 您需要压制证书验证 。 可以通过设置 NODE_TLS_REJECT_UNAUTHORIZED 环境变量改为 0。 。 。 .

不同操作系统和 shell 环境的示例如下. 注意所有实例只设置运行中 shell 的变量, 它不会持久 。 要坚持设置, 请查看您的外壳环境的文档 。 应当谨慎行事,因为此设置会压制证书的验证 全部 节点运行时的连接 !

(ba)sh (Linux, macOS, WSL) (英语)

export NODE_TLS_REJECT_UNAUTHORIZED=0

动力壳:

$env:NODE_TLS_REJECT_UNAUTHORIZED=0

命令提示( 窗口) :

SET NODE_TLS_REJECT_UNAUTHORIZED=0

在生产环境中设置这种环境可变因素会大大降低安全性,因此受到强烈的阻碍。 我们只建议在开发环境中设置这个环境变量,前提是无法配置一个 CA 签名的 API 自我托管证书 .

许可证

所有内容都根据以下条款获得许可: 麻省理工学院许可证。 。 。 .