Draft Annotations API

概述

Draft Annotations API是一个微服务，提供对存储在PAC中的内容草稿注释的访问。

安装

下载源代码、依赖项和测试依赖项：

mkdir $GOPATH/src/github.com/Financial-Times/draft-annotations-api
cd $GOPATH/src/github.com/Financial-Times
git clone [***]
cd draft-annotations-api
GO111MODULE=on go build -mod=readonly

本地运行

1. 运行测试并安装二进制文件

GO111MODULE=on go test -mod=readonly ./...
go install

2. 运行二进制文件（使用help标志查看可用的可选参数）

$GOPATH/bin/draft-annotations-api [--help]

选项：
  --app-system-code="draft-annotations-api"                                        应用的系统代码 ($APP_SYSTEM_CODE)
  --app-name="draft-annotations-api"                                               应用名称 ($APP_NAME)
  --port="8080"                                                                    监听端口 ($APP_PORT)
  --annotations-rw-endpoint="http://localhost:8888"                                从数据库获取草稿注释的端点 ($ANNOTATIONS_RW_ENDPOINT)
  --upp-annotations-endpoint="[***]"       公共注释API端点 ($ANNOTATIONS_ENDPOINT)
  --internal-concordances-endpoint="[***]"   从UPP获取概念的端点 ($INTERNAL_CONCORDANCES_ENDPOINT)
  --internal-concordances-batch-size=30                                            查询UPP Internal Concordances API时使用的概念ID最大批大小 ($INTERNAL_CONCORDANCES_BATCH_SIZE)
  --upp-api-key=""                                                                 访问UPP的API密钥 ($UPP_APIKEY)
  --api-yml="./_ft/api.yml"                                                        API Swagger YML文件的位置 ($API_YML)
  --http-timeout="8s"                                                              请求超时前的等待时间 ($HTTP_TIMEOUT)
  --log-level="INFO"                                                               日志级别 ($LOG_LEVEL)

3. 测试

方法一：使用curl

curl http://localhost:8080/draft/content/b7b871f6-8a89-11e4-8e24-00144feabdc0/annotations | json_pp

方法二：使用httpie

http GET http://localhost:8080/draft/content/b7b871f6-8a89-11e4-8e24-00144feabdc0/annotations

构建与部署

• 该应用作为Docker镜像构建，并通过Helm chart部署到Kubernetes集群。内部Jenkins作业负责在创建标签时将Docker镜像推送到Docker Hub并部署chart。Docker Hub仓库地址：coco/draft-annotations-api
• CI由CircleCI提供：draft-annotations-api

服务端点

有关服务API端点的完整描述，请参阅Open API规范。

GET - 从PAC读取草稿注释

使用curl：

curl http://localhost:8080/draft/content/{content-uuid}/annotations | jq

此端点上的GET请求通过调用Generic RW Aurora获取特定内容的草稿注释。成功时，通过调用UPP Concept Search API为注释添加概念信息。如果PAC中没有可用的注释，Draft Annotations API会通过调用UPP Public Annotations API获取已发布的注释。获取已发布注释是在PAC中动态导入遗留注释策略的一部分。

响应体示例：

{
  "annotations": [
    {
      "predicate": "[***]",
      "id": "[***]",
      "apiUrl": "[***]",
      "type": "[***]",
      "prefLabel": "Emily Cadman",
      "isFTAuthor": true
    },
    {
      "predicate": "[***]",
      "id": "[***]",
      "apiUrl": "[***]",
      "type": "[***]",
      "prefLabel": "Lisa Barrett",
      "isFTAuthor": true
    },
    {
      "predicate": "[***]",
      "id": "[***]",
      "apiUrl": "[***]",
      "type": "[***]",
      "prefLabel": "Global economic growth"
    }
  ]
}

PUT - 向PAC写入草稿注释

使用curl：

curl -X PUT \
  http://localhost:8080/drafts/content/{content-uuid}/annotations \
  -d '{
    "annotations": [
      {
        "predicate": "[***]",
        "id": "[***]",
        "apiUrl": "[***]",
        "type": "[***]",
        "prefLabel": "Lisa Barrett"
      },
      {
        "predicate": "[***]",
        "id": "[***]",
        "apiUrl": "[***]",
        "type": "[***]",
        "prefLabel": "Global economic growth"
      },
      {
        "predicate": "[***]",
        "id": "[***]",
        "apiUrl": "[***]",
        "type": "[***]",
        "prefLabel": "Global economic growth"
      }
    ]
  }'

此端点上的PUT请求将草稿注释写入PAC。输入体是注释JSON对象数组，其中仅predicate和id是必填字段。如果写入操作成功，应用将返回规范化的输入体，并附带HTTP 200响应码。

规范化响应示例：

{
  "annotations": [
    {
      "predicate": "[***]",
      "id": "[***]"
    },
    {
      "predicate": "[***]",
      "id": "[***]"
    },
    {
      "predicate": "[***]",
      "id": "[***]"
    }
  ]
}

DELETE - 从PAC中删除草稿编辑注释

使用curl：

curl http://localhost:8080/draft/content/{content-uuid}/annotations/{concept-uuid} | jq

此端点上的DELETE请求从特定内容的编辑已发布注释中删除单个概念的所有注释。为了检索这些特定注释，它会使用“lifecycle”参数调用UPP Public Annotations API。如果操作成功，应用将返回规范化的输入体，并附带HTTP 200响应码。

响应体示例：

{
  "annotations": [
    {
      "predicate": "[***]",
      "id": "[***]"
    },
    {
      "predicate": "[***]",
      "id": "[***]"
    },
    {
      "predicate": "[***]",
      "id": "[***]"
    }
  ]
}

健康检查

管理端点包括：

• /__gtg
• /__health
• /__build-info

目前，/__health和/__gtg检查UPP Public Annotations API的可用性。

日志

• 应用使用logrus；日志器在main.go中初始化。
• 日志输出到标准输出。
• 注意：/__build-info和/__gtg端点不会被记录，因为它们每秒都会被varnish/vulcand调用，这些信息在日志/Splunk中不需要。