senzing/senzing-api-server

senzing-api-server

概述

Java实现的Senzing REST API服务器。

http://editor.swagger.io/?url=https://raw.githubusercontent.com/Senzing/senzing-rest-api/main/senzing-rest-api.yaml 文档详细说明了可用的API方法、参数及响应格式。

目录

1. 使用命令行演示
   1. 依赖项
   2. 构建
   3. 运行
   4. 使用SSL运行
2. 使用Docker演示
   1. Docker预期
   2. 配置
   3. 外部数据库
   4. 数据库支持
   5. 运行Docker容器
   6. 测试Docker容器
3. 许可证
4. 参考资料

图例

1. :thinking: - “思考者”图标表示可能需要额外思考。也许需要做出一些选择，或者这是一个可选步骤。
2. :pencil2: - “铅笔”图标表示执行前可能需要修改说明。
3. :warning: - “警告”图标表示存在需要注意的复杂情况。

使用命令行演示

依赖项

构建Senzing REST API服务器需要Apache Maven（推荐3.6.1或更高版本）以及OpenJDK 11.0.x（推荐11.0.6+10或更高版本）。

运行Senzing REST API服务器还需要Senzing产品安装，但构建时不需要。Senzing REST API服务器可以在未安装Senzing的情况下构建（包括运行自动测试）。注意：如果要使用实时Senzing产品而不是缓存的测试数据运行端到端（E2E）自动测试，仍需要Senzing产品。

1. 配置环境。如前所述，API依赖于原生库，环境必须正确配置以找到这些库：

   1. Linux

      console
      export SENZING_G2_DIR=/opt/senzing/g2
      
      export LD_LIBRARY_PATH=${SENZING_G2_DIR}/lib:${SENZING_G2_DIR}/lib/debian:$LD_LIBRARY_PATH
      

   2. Windows

      console
      set SENZING_G2_DIR="C:\Program Files\Senzing\g2"
      
      set Path=%SENZING_G2_DIR%\lib;%Path%
      

2. 确保OpenAPI规范GIT子模块（senzing-rest-api-specification）已克隆：

   console
   git submodule update --init --recursive
   

构建

执行以下命令构建：

console
mvn install

注意：如果要使用实时Senzing产品将自动化测试作为端到端（E2E）测试运行，可以绕过缓存测试数据的重放，直接执行API，使用以下替代构建命令：

console
mvn install -Dcom.senzing.api.test.replay.direct=true

JAR文件将位于target目录中，名称为senzing-api-server-[version].jar，其中[version]是pom.xml文件中的版本号。

运行

使用java -jar执行服务器。假设环境已按照“依赖项”部分正确配置。

启动时必须提供Senzing原生API的初始化参数，可通过以下一种方式提供：

• --init-file（指定包含初始化参数的JSON文件路径）
• --init-json（指定包含初始化参数的JSON文本）
• --ini-file（指定包含初始化参数的INI文件路径）
• --init-env-var（指定从中读取JSON文本的环境变量）

通常应从初始化参数中排除G2CONFIGFILE路径，以加载为存储库设置的默认配置。仍可指定引用文件系统上配置的G2CONFIGFILE参数；但通过这种方式启动时，配置更改（如默认配置更改）不会自动重新初始化，需手动同步配置并重启Senzing REST API服务器以刷新配置。

其他命令行选项可能也有用。执行

console
java -jar target/senzing-api-server-3.3.0.jar --help

获取描述所有可用选项的帮助信息。例如：

console
java -jar senzing-api-server-3.3.0.jar --help

以下是部分常用选项说明：

[ 标准选项 ] --help 显示帮助信息，服务器不启动。 --version 显示G2 REST API服务器版本，服务器不启动。 --read-only [true|false] 禁用修改实体存储库数据的功能，相关函数返回403 Forbidden响应。默认true（若未指定）。 --> 环境变量：SENZING_API_SERVER_READ_ONLY --http-port <port-number> 设置HTTP通信端口，默认8250。指定0则随机选择可用端口。若配置SSL客户端认证，则禁止此选项。 --> 环境变量：SENZING_API_SERVER_PORT --bind-addr <ip-address|loopback|all> 设置HTTP通信绑定地址，默认环回地址。 --> 环境变量：SENZING_API_SERVER_BIND_ADDR --concurrency <thread-count> 设置用于执行Senzing API函数的线程数，默认8。 --> 环境变量：SENZING_API_SERVER_CONCURRENCY

（完整选项列表可通过--help查看）

示例：在端口8080运行服务器，绑定所有网络接口，并发数16：

console
java -jar target/senzing-api-server-[version].jar \
  --concurrency 16 \
  --http-port 8080 \
  --bind-addr all \
  --init-file ~/senzing/data/g2-init.json

使用SSL运行

启用基本SSL支持

默认情况下，Senzing REST API服务器仅在单个端口上接受HTTP连接，默认HTTP端口8250（可通过--http-port修改）。也可启动仅HTTPS支持或同时支持HTTP和HTTPS（不同端口）。

要启用HTTPS，需通过--key-store选项提供包含服务器私钥的加密PKCS12密钥库，通过--key-store-password提供解密密码。若密钥库包含多个密钥且需使用非第一个密钥，可通过--key-alias指定密钥别名。提供服务器私钥后，HTTPS默认在8263端口启用，可通过--https-port配置。

注意：启用HTTPS后，HTTP默认禁用。可通过显式提供--http-port选项同时启用两者。

示例：使用自签名证书启用HTTPS

1. 创建服务器PKCS12密钥库（sz-api-server-store.p12）：

   console
   keytool -genkey \
           -alias sz-api-server \
           -keystore sz-api-server-store.p12 \
           -storetype PKCS12 \
           -keyalg RSA \
           -storepass change-it \
           -validity 730 \
           -keysize 2048
   

2. 使用服务器密钥库启动Senzing API服务器：

   console
   java -jar senzing-api-server-2.7.0.jar \
             --ini-file /etc/opt/senzing/G2Module.ini \
             --key-store sz-api-server-store.p12 \
             --key-store-password change-it \
             --key-alias sz-api-server
   

3. 使用curl测试（自签名证书需加-k）：

   console
   curl -k https://localhost:8263/heartbeat
   

SSL客户端认证

除服务器HTTPS外，还可配置服务器仅接受使用特定SSL证书通信的客户端。若配置SSL客户端认证，则不允许HTTP支持（无法通过HTTP识别客户端），因此禁止--http-port命令行选项。

SSL客户端认证通过--client-key-store（指定包含授权客户端公钥的密钥库）和--client-key-store-password（解密密钥库的密码）配置。

使用Docker演示

Docker预期

假设已安装Docker，且用户具有运行Docker命令的权限。

配置

需配置Senzing初始化参数（如数据库连接信息），可通过环境变量或挂载配置文件提供。

外部数据库

支持使用外部数据库（如PostgreSQL、MySQL等）存储Senzing数据，需在初始化参数中配置数据库连接信息。

数据库支持

支持主流数据库，具体配置需参考Senzing文档中的数据库连接参数。

运行Docker容器

示例命令：

console
docker run -d \
  --name senzing-api-server \
  -p 8250:8250 \
  -e SENZING_API_SERVER_PORT=8250 \
  -e SENZING_API_SERVER_BIND_ADDR=all \
  -e SENZING_API_SERVER_INIT_JSON='{"PIPELINE":{...}}' \
  senzing/senzing-api-server:latest

测试Docker容器

测试HTTP端点：

console
curl http://localhost:8250/heartbeat

许可证

详见https://github.com/Senzing/senzing-api-server/blob/main/LICENSE%E3%80%82

参考资料

• http://editor.swagger.io/?url=https://raw.githubusercontent.com/Senzing/senzing-rest-api/main/senzing-rest-api.yaml
• Senzing官方文档