@adobe/fetch 中文文档教程

Question

adobe-fetch

调用 Adob​​e API

Goals

调用 Adob​​e API一阵微风！

这个包将处理 JWT 身份验证、令牌缓存和存储。
否则它的工作方式与 fetch 完全相同。

该库现在也可以在浏览器中使用，请参阅下面的信息。

Installation

npm install --save @adobe/fetch

Common Usage

    const AdobeFetch = require('@adobe/fetch');
    const fs = require('fs');

    const config = { 
      auth: {
          clientId: 'asasdfasf',
          clientSecret: 'aslfjasljf-=asdfalasjdf==asdfa',
          technicalAccountId: 'asdfasdfas@techacct.adobe.com',
          orgId: 'asdfasdfasdf@AdobeOrg',
          metaScopes: ['ent_dataservices_sdk']
      }
    };

    config.auth.privateKey = fs.readFileSync('private.key');

    const adobefetch = AdobeFetch.config(config);

    adobefetch("https://platform.adobe.io/some/adobe/api", { method: 'get'})
      .then(response => response.json())
      .then(json => console.log('Result: ',json));

Config Auth object

config.auth 对象是您传递所有必需和可选参数以验证 API 调用的地方。

parameter	integration name	required	type	default
clientId	API Key (Client ID)	true	String
technicalAccountId	Technical account ID	true	String
orgId	Organization ID	true	String
clientSecret	Client secret	true	String
privateKey		true	String
passphrase		false	String
metaScopes		true	Comma separated Sting or an Array
ims		false	String	https://ims-na1.adobelogin.com

为了确定您需要注册哪些 metaScopes，您可以在此 方便的表格。

例如，如果您需要通过身份验证才能为 GDPR 和用户管理调用 API，您将 查找它们，发现它们是：

• GDPR: https://ims-na1.adobelogin.com/s/ent_gdpr_sdk
• User Management: https://ims-na1.adobelogin.com/s/ent_user_sdk

然后您将创建一个 metaScopes 数组作为 config 对象的一部分. 例如：

const config = {
  auth: {
      clientId: 'asasdfasf',
      clientSecret: 'aslfjasljf-=asdfalasjdf==asdfa',
      technicalAccountId: 'asdfasdfas@techacct.adobe.com',
      orgId: 'asdfasdfasdf@AdobeOrg',
      metaScopes: [
        'https://ims-na1.adobelogin.com/s/ent_gdpr_sdk',
        'https://ims-na1.adobelogin.com/s/ent_user_sdk'
      ]
  }
};

但是，如果您省略 IMS URL，程序包会在调用生成 JWT 时自动为您添加它。

例如：

const config = {
  auth: {
      clientId: 'asasdfasf',
      clientSecret: 'aslfjasljf-=asdfalasjdf==asdfa',
      technicalAccountId: 'asdfasdfas@techacct.adobe.com',
      orgId: 'asdfasdfasdf@AdobeOrg',
      metaScopes: ['ent_gdpr_sdk', 'ent_user_sdk']
  }
};

这是推荐的方法。

Alternative authentication methods

要将此库与替代身份验证流程（如 OAuth）一起使用，或在 adobe-fetch 之外执行 JWT 身份验证流程，可以使用 Provided 模式并将访问令牌直接提供给 adobe-fetch通过异步函数：

    const AdobeFetch = require('@adobe/fetch');
    const { AUTH_MODES } = AdobeFetch;

    const adobefetch = AdobeFetch).config({ 
      auth: {
          mode: AUTH_MODES.Provided,
          clientId: 'asasdfasf',
          orgId: 'asdfasdfasdf@AdobeOrg',
          tokenProvider: async () => { ... Logic returning a valid access token object ... }
      }
    });

    adobefetch("https://platform.adobe.io/some/adobe/api", { method: 'get'})
      .then(response => response.json())
      .then(json => console.log('Result: ',json));

当上面的 adobefetch 调用第一次发生时，它将调用提供的 tokenProvider 函数并等待它返回访问令牌。 然后缓存并持久化访问令牌，如果它过期或被 API 拒绝，将再次调用 tokenProvider 函数以获取新令牌。

有效的令牌具有以下结构：

  {
    token_type: 'bearer',
    access_token: <<<TOKEN>>>,
    expires_in: <<<EXPIRY_IN_MILLISECONDS>>>
  }

Using in the browser

在浏览器中，仅允许使用上面解释的 Provided 模式，不支持 JWT。

这是因为 JWT 工作流需要直接访问私钥，并且出于安全原因应该在服务器中完成。 使用 Provided 模式，可以通过标准 OAuth 身份验证流程获取访问令牌，然后由 adobe-fetch 使用来调用 Adob​​e API。

在 Web 应用程序中使用 require('@adobe/fetch') 将自动使用浏览器版本。
您还可以将 bundled JS 文件直接包含在脚本标记中。

Predefined Headers

如果您有每个请求都需要的 HTTP 标头，您可以在配置中提供它们。 然后它们将自动添加到每个请求中。

您可以提供值或函数。 当您需要为每个请求生成动态标头值时，可以使用函数。

例如：

const config = {
  auth: {
    ... Auth Configuration ...
  },
  headers: {
    'x-sandbox-name': 'prod',
    'x-request-id': () => idGenerationFunc()
  }
};

以下标头是自动添加的。 您可以使用上面显示的值或函数覆盖这些标头，授权 除外：

• authorization (Can not be overridden)
• x-api-key
• x-request-id
• x-gw-ims-org-id

Custom Storage

默认情况下， node-persist 用于在本地存储所有活动令牌。
令牌将存储在 /.node-perist/storage

下。可以使用任何其他存储来持久化令牌。 这是通过提供 read 和 write 方法完成的，如下所示：

const config = {
  auth: {
      clientId: 'asasdfasf',

      ...

      storage: {
        read: function() {
          return new Promise(function(resolve, reject) {
            let tokens;

            // .. Some logic to read the tokens ..

            resolve(tokens);
          });
        },
        write: function(tokens) {
          return new Promise(function(resolve, reject) {

            // .. Some logic to save the tokens ..

            resolve();
          });
        }
      }
  }
};

或者，使用 async/await：

const config = {
  auth: {
      clientId: 'asasdfasf',

      ...

      storage: {
        read: async function() {
          return await myGetTokensImplementation();            
        },
        write: async function(tokens) {
          await myStoreTokensImplementation(tokens);
        }
      }
  }
};

Logging

每个请求都将包含一个通过 x-request 发送的唯一请求标识符-id.
请求标识符可以通过标头提供来覆盖：

fetch(url, {
  headers: { 'x-request-id': myRequestID }
});

我们使用 debug 来记录请求。 为了查看所有调试输出，包括请求标识符，请使用包含 @adobe/fetch 范围的 DEBUG 环境变量运行您的应用程序，如下所示：

DEBUG=@adobe/fetch

Contributing

欢迎贡献！ 阅读贡献指南了解更多信息。

Licensing

这个项目是根据 Apache V2 许可证获得许可的。 有关详细信息，请参阅许可证。