
.. title:: ZK FPEngine Web Service API

.. _intro:


中控指纹识别服务器简介
===========================

中控指纹识别服务器是一个全功能的指纹识别服务器。它集成了业界领先的中控指纹识别算法ZKFinger 10.0 版，具有非常优秀的识别率和识别性能。

中控指纹识别服务器具有如下功能:

  * 指纹特征提取
  * 人员指纹数据维护（登记、删除、修改、查询）
  * 1：1比对
  * 1：N识别

中控指纹识别服务器通过http协议监听默认的18001端口，提供业界标准的 Web Service API 接口，供其他程序进行调用。


.. _mode_cb:

Web Service API 
==================

ZKFPEngine Web API 调用遵循 RESTful 约定。系统执行了对应功能后以json格式返回执行的结果数据；若对应功能不能正常执行，则返回如下json形式的错误信息::

  { error_code: ...,  message: "... ..."}

其中，error_code 为错误代码， message 为错误信息。  

系统仅仅处理8位灰度图像，可以是Bitmap格式，也可以是无如何格式的Raw Image，图像以二进制方式传送到服务器。系统接口中，无论是传送给服务器的指纹模板，还是服务器返回的指纹模板，均采用 base64 不换行编码模式。

系统信息
-----------------

调用方法与地址::

  GET http://zkfpserver:18001/zkfinger/info

此接口用于读取系统信息。

服务器返回:

    ================= ==========================================
    字段名            值   
    ================= ==========================================
    db_template_count 数据库中的指纹模板数
    db_template_limit 数据库中的指纹模板数上限
    server_version    服务器版本号
    fp_engine_version 指纹识别算法版本号
    start             服务器启动时间  
    ================= ==========================================

示例::

    $ curl http://localhost:18001/zkfinger/info
    {
     db_template_limit: 50000, 
     db_template_count: 10292, 
     start: "2012-03-09 11:12:10",
     server_version: "10.0",
     fp_engine_version: "10.0",
    }


.. _extract:

提取特征模板
-----------------

调用方法与地址::

  POST http://zkfpserver:18001/zkfinger/extract?height=<height>&width=<width>

此接口用于从指纹图像中提取出指纹模板。支持256级灰度图像，可以是Bitmap格式和RAW格式。RAW格式时，必须用height参数指定图像高度，用width参数指定图像宽度，Bitmap格式不需指定这两个参数。

服务器返回:

    =============== ==========================================
    字段名          值   
    =============== ==========================================
    length          模板的长度（base64编码前）
    template        从图像中提取的指纹模板，以base64方式编码
    =============== ==========================================

示例::

    $ curl --data-binary @fp1.bmp http://localhost:18001/zkfinger/extract
    {length: 930, template: " ... ... "}


保存(登记或修改)
-----------------

调用方法与地址::

  POST http://zkfpserver:18001/zkfinger/db/<id>?height=<height>&width=<width>

保存指纹模板到数据库。<id>是一个由字母、数字、减号和下划线等组成的一个有效标识符，其最大长度为100. 若指定id对应的指纹模板在数据库中不存在，则新增，否则修改已经存在的对应指纹模板。

POST 的内容可以是图像，也可以是指纹模板。若是图像，则先对图像提取特征模板，在保存到数据库中，图像的格式和参数参考 :ref:`extract` 。若POST是指纹模板，则每一行是一个指纹模板，可以有最多5个指纹模板，这些指纹模板会被合成成为一个指纹模板再存到数据库中。注意，多个指纹模板必须是同一指纹的图像上提取的。

服务器返回:

    =============== ==========================================
    字段名          值   
    =============== ==========================================
    count           1
    =============== ==========================================

示例::

    $ curl --data-binary @richard_1.ftmp http://localhost:18001/zkfinger/db/richard_1
    { count: 1 }

查询
-----------------

调用方法与地址::

  GET http://zkfpserver:18001/zkfinger/db/<id>

查询数据库中的指纹模板。

服务器返回:

    =============== ==========================================
    字段名          值   
    =============== ==========================================
    length          模板的长度（base64编码前）
    template        对应的指纹模板，以base64方式编码
    =============== ==========================================

示例::

    $ curl http://localhost:18001/zkfinger/db/richard_1
    {length: 922, template: " ... ... "}

删除    
-----------------

调用方法与地址::

  DELETE http://zkfpserver:18001/zkfinger/db/<id>

此接口用于从数据库中删除指定的指纹模板

服务器返回:

    =============== ==========================================
    字段名          值   
    =============== ==========================================
	count           1
    =============== ==========================================

示例::

    $ curl -X DELETE http://localhost:18001/zkfinger/db/richard_1
    { count: 1 }

清空数据库
-----------------

调用方法与地址::

  DELETE http://zkfpserver:18001/zkfinger/clear

清空数据库中登记的全部指纹。

服务器返回:

    =============== ==========================================
    字段名          值   
    =============== ==========================================
    count           被删除的数据库中的指纹数
    =============== ==========================================

示例::

    $ curl -X DELETE http://localhost:18001/zkfinger/clear
    { count: 2019202 }


比对两个模板
-----------------

调用方法与地址::

  POST http://zkfpserver:18001/zkfinger/verify

该函数把两个模板发送到服务器上进行1:1比对。post数据中，两个模板分为两行（即他们之间用 '\\n' 分隔）。

服务器返回:

    =============== ==========================================
    字段名          值   
    =============== ==========================================
    score           指纹模板之间的匹配分数
    =============== ==========================================

示例::

    $ curl --data-binary @c1.txt http://localhost:18001/zkfinger/verify
    {score: 100}


1：1 比对
-----------------

调用方法与地址::

  POST http://zkfpserver:18001/zkfinger/verify/<id>?height=<height>&width=<width>

该函数把一个指纹图像或模板发送到服务器上进行1:1比对。<id>用于指定同数据库中的那一个指纹模板进行比对。服务器自动判断发送的是图像还是模板，若发送的是图像，则会先提取模板再进行比对。图像的格式和参数参考 :ref:`extract` 。

服务器返回:

    =============== ==========================================
    字段名          值   
    =============== ==========================================
    score           指纹模板之间的匹配分数
    =============== ==========================================


示例::

    $ curl --data-binary @fp1.ftmp http://localhost:18001/zkfinger/verify/richard_1
    {score: 91}

    $ curl --data-binary @fp1.bmp http://localhost:18001/zkfinger/verify/richard_1
    {score: 91}

    $ curl --data-binary @fp1.raw http://localhost:18001/zkfinger/verify/richard_1?height=360&width=256
    {score: 91}

1：N 识别
-----------------

调用方法与地址::

    POST http://zkfpserver:18001/zkfinger/identify?height=<height>&width=<width>&max_return=<max_return>&min_score=<min_score>

该函数把一个指纹图像或模板发送到服务器上进行1:N识别。服务器自动判断发送的是图像还是模板，若发送的是图像，则会先提取模板再进行识别。图像的格式和参数参考 :ref:`extract` 。参数 max_return 用于指定返回最为相似的前几名指纹模板，默认为1，最大为20；参数min_score 表示识别时最小匹配分数，默认值为60.

服务器返回:

    =============== ================================================
    字段名          值   
    =============== ================================================
    ids             匹配中满足最低分数阈值的列表，按照相似度降序排列
    .id             匹配的指纹id
    .score          相似度分数
    =============== ================================================

示例::

    $ curl --data-binary @fp1.ftmp http://localhost:18001/zkfinger/identify?min_score=20
    {ids:[
          {id: "richard_1", score: 91}, 
          {id: "smith", score: 21}
    ]}

    $ curl --data-binary @fp1.bmp http://localhost:18001/zkfinger/identify
    {ids:[
          {id: "richard_1", score: 91}
    ]}

    $ curl --data-binary @fp1.raw http://localhost:18001/zkfinger/verify/richard_1?height=360&width=256
    {ids:[
          {id: "richard_1", score: 91}
    ]}



