@abcnews/terminus-fetch 中文文档教程

Question

@abcnews/terminus-fetch

根据当前执行域，从 Preview / Live Terminus 内容 API 获取一个或多个

$ npm i @abcnews/terminus-fetch

Usage

import { fetchOne, search } from '@abcnews/terminus-fetch';
// We export fetchOne by default, as it's most commmonly used:
import fetchOne from '@abcnews/terminus-fetch';

// By default, we assume you want an Article docment from
// Core Media, using News' API key, so you can pass a CMID:

fetchOne(10736062, (err, doc) => {
  if (!err) {
    console.log(doc);
    // > { id: 10736062, docType: "Article", contentSource: "coremedia", ... }
  }
});

// ...or you can pass an options object to override the defaults (see API below):

fetchOne({ id: 10734902, type: 'video' }, (err, doc) => {
  if (!err) {
    console.log(doc);
    // > {id: 10734902, docType: "Video", contentSource: "coremedia", ... }
  }
});

// You can use promises instead of callbacks:

fetchOne({ id: 123860, type: 'show', source: 'iview' })
  .then(doc => {
    console.log(doc);
    // > { id: 123860, docType: "show", contentSource: "iview", ... }
  })
  .catch(err => console.error(err));

// Searching is also supported:

search({ limit: 3, doctype: 'image' }), (err, docs) => {
  if (!err) {
    console.log(docs);
    // > [
    //     { id: 11405582, docType: "Image", contentSource: "coremedia", ... },
    //     { id: 11404970, docType: "Image", contentSource: "coremedia", ... },
    //     { id: 11405258, docType: "Image", contentSource: "coremedia", ... }
    //   ]
  }
});

// ...for all sources...:

search({ limit: 1, source: 'mapi', service: 'triplej'})
  .then(docs => {
    console.log(docs);
    // > [
    //     { id: "maaYa1B4YP", docType: "Artist", ... },
    //     { id: "mpr9PpbkRd", docType: "Play", ... },
    //     { id: "mtOKj2DbNK", docType: "Recording", ... },
    //     { id: "mrDXgzL4Ry", docType: "Release", ... }
    //   ]
  })
  .catch(err => console.error(err));

文档用于预览 Terminus (https://api-preview.terminus.abc-prod.net.au/api/v1/{teasable}content)，否则将用于 Live Terminus （https://api.abc.net.au/terminus/api/v1/{teasable}content）。

如果您想将单个请求定向到 Live Terminus，而不考虑当前的执行域，请将 forceLive: true 作为选项传递。

如果您想将单个请求定向到 Preview Terminus，而不考虑当前的执行域，请将 forcePreview: true 作为选项传递。

如果您只需要文档的元数据（例如没有全文内容的文章），将 isTeasable: true 作为选项传递，文档将从 /teasablecontent/ 中获取API，而不是 /content/ API。

API

fetchOne

declare function fetchOne(
  options:
    | string
    | number
    | {
        source?: string;
        type?: string;
        id?: string | number;
        apikey?: string;
        forceLive?: boolean;
        forcePreview?: boolean;
        isTeasable?: string;
      },
  done?: (err?: ProgressEvent | Error, doc?: Object) => void
): void | Promise<Object>;

如果省略 done 回调，则返回值将是一个 Promise。

Default options

{
  source: 'coremedia',
  type: 'article',
  apikey: '54564fe299e84f46a57057266fcf233b' /* (News) */
}

search

declare function search(
  options: {
    source?: string;
    apikey?: string;
    forceLive?: boolean;
    forcePreview?: boolean;
    ...searchParams: Object;
  },
  done?: (err?: ProgressEvent | Error, doc?: Object) => void
): void | Promise<Object>;

…您的 searchParams 是您的 options 对象的附加属性，用于查询 API。

例如，如果您想要将最后 20 张图像添加到 Core Media，您的 searchParams 将是：

{
  limit: 20,
  doctype: 'image'
}

如果省略 done 回调，则返回值将是一个 Promise。

Default options

这些与 fetchOne 相同，只是分为两个选项参数。

getImages

这会获取从终端返回的图像文档（Imge、ImageProxy 或 CustomImage 文档类型）并返回 一个规范化的对象，包括可用的图像再现。

declare function getImages(doc: any, targetWidths?: number[]): ImageData;

targetWidths argument (optional)

无法保证返回的对象将包含使用 targetWidths 参数请求的宽度。 这个库的消费者应该经常检查结果，看看他们是否得到了他们想要的并相应地行动。

此参数的默认值为：[160, 240, 480, 700, 940, 1400, 2150]

该参数是可选的，根据传递的文档是来自对 v1 还是 v2 的请求，其行为略有不同的API。

• v1 documents: this argument is completely ignored and the returned object will contain all available image sizes.
• v2 documents: rendition URLs for every available aspect ratio will be generated for every requested width.

注意：也无法保证给定图像的纵横比可用。

Returned object

结果具有以下类型：

declare type ImageData = {
  cmid: string;
  title?: string;
  alt?: string;
  caption?: string;
  attribution?: string;
  canonicalURL: string;
  renditions: ImageRendition[];
};
declare type ImageRendition = {
  width: number;
  height: number;
  ratio: string;
  url: string;
  isUndersizedBinary: boolean;
};

这里有几个与图像代理相关的陷阱。 cmid 和 canonicalURL 属性将是代理的属性，而不是目标图像的属性。 虽然可以从 v1 文档返回代理图像的 ID，但它不在 v2 上。 所以为了标准化，两者都将返回代理 ID 和 URL。

在 v2 响应中，再现指向的二进制 URL 实际上可能小于对象中的维度。 这是因为图像缩放器永远不会放大小原件，但仍然可以请求。 这种情况由 isUn​​dersizedBinary 属性标记。

Developing

要运行 /example 项目：

1. Start the development server with: npm run example
2. Visit http:<machine_name>.aus.aunty.abc.net.au:1234
3. Open the browser's development console

Releasing

npm run release 将为您处理版本冲突、git 推送和 npm 发布。

Authors

• Colin Gourlay (Gourlay.Colin@abc.net.au)