fingerprintjs/python-sdk
GitHub: fingerprintjs/python-sdk
Fingerprint Pro Server API 的官方 Python SDK，用于在服务端查询访客识别事件、管理数据并验证 Webhook 签名。
Stars: 21 | Forks: 5
# Fingerprint Server Python SDK
[Fingerprint](https://fingerprint.com) 是一个提供业界领先准确性的设备智能平台。
Fingerprint Server Python SDK 是一种从你的 Python 应用程序与 Fingerprint [Server API](https://dev.fingerprint.com/reference/pro-server-api) 进行交互的简便方法。你可以检索访问者历史记录或单独的识别事件。
此 Python 包由 [OpenAPI Generator](https://openapi-generator.tech) 项目自动生成：
- API 版本：4
- 包版本：9.2.0
- 生成器版本：7.19.0
- 构建包：org.openapitools.codegen.languages.PythonClientCodegen
## 环境要求
支持以下 Python 版本：
- Python 3.9+
## 安装与使用
### pip install
你可以直接从 Github 安装该包
```
pip install git+https://github.com/fingerprintjs/python-sdk.git
```
或者从 PyPI 安装
```
pip install fingerprint_server_sdk
```
然后导入该包：
```
import fingerprint_server_sdk
```
### Setuptools
通过 [Setuptools](http://pypi.python.org/pypi/setuptools) 安装。
```
python setup.py install --user
```
（或者使用 `sudo python setup.py install` 为所有用户安装该包）
然后导入该包：
```
import fingerprint_server_sdk
```
## 入门指南
请按照[安装步骤](#installation--usage)操作，然后运行以下命令：
```
import os
import fingerprint_server_sdk
from fingerprint_server_sdk.configuration import Region
# 配置 API key 授权和区域
configuration = fingerprint_server_sdk.Configuration(
api_key = os.environ["SECRET_API_KEY"],
region = Region.US
)
# 创建 API 类的实例
api_instance = fingerprint_server_sdk.FingerprintApi(configuration)
```
## 示例
使用 `visitorId` 删除访问者数据：
```
import os
import fingerprint_server_sdk
from fingerprint_server_sdk import ApiException, ErrorResponse
from fingerprint_server_sdk.configuration import Region
# 配置 API key 授权和区域
configuration = fingerprint_server_sdk.Configuration(
api_key = os.environ["SECRET_API_KEY"],
region = Region.US
)
api_instance = fingerprint_server_sdk.FingerprintApi(configuration)
visitor_id = 'visitor_id_example'
try:
api_instance.delete_visitor_data(visitor_id)
except ApiException as e:
if e.body is not None:
error_response = ErrorResponse.from_json(e.body)
if error_response is not None:
message = f"API request failed: {error_response.error.code} {error_response.error.message}"
else:
message = f"API request failed with unexpected error format: {e}"
else:
message = f'Exception when calling FingerprintApi->delete_visitor_data: {e}'
print(message)
```
了解更多信息，请参考位于 [examples/delete_visitor_example.py](examples/delete_visitor_example.py) 的示例。
获取 `eventId` 的事件详情：
```
import os
import fingerprint_server_sdk
from fingerprint_server_sdk import ApiException, ErrorResponse
from fingerprint_server_sdk.configuration import Region
# 配置 API key 授权和区域
configuration = fingerprint_server_sdk.Configuration(
api_key = os.environ["SECRET_API_KEY"],
region = Region.US
)
api_instance = fingerprint_server_sdk.FingerprintApi(configuration)
event_id = 'event_id_example'
try:
events_response = api_instance.get_event(event_id)
except ApiException as e:
if e.body is not None:
error_response = ErrorResponse.from_json(e.body)
if error_response is not None:
message = f"API request failed: {error_response.error.code} {error_response.error.message}"
else:
message = f"API request failed with unexpected error format: {e}"
else:
message = f'Exception when calling FingerprintApi->get_event: {e}'
print(message)
```
了解更多信息，请参考位于 [examples/get_event_example.py](examples/get_event_example.py) 的示例。
使用自定义过滤器搜索事件：
```
import os
import fingerprint_server_sdk
from fingerprint_server_sdk import ApiException, SearchEventsBot, ErrorResponse
from fingerprint_server_sdk.configuration import Region
# 配置 API key 授权和区域
configuration = fingerprint_server_sdk.Configuration(
api_key = os.environ["SECRET_API_KEY"],
region = Region.US
)
api_instance = fingerprint_server_sdk.FingerprintApi(configuration)
limit = 20
pagination_key = 'key_example'
visitor_id = 'VISITOR_ID'
bot = SearchEventsBot.GOOD
ip_address = '192.168.0.1/32'
linked_id = 'linked_id_example'
start = 1738687200000
end = 1738773600000
reverse = True
suspect = False
try:
# Get events via search
api_response = api_instance.search_events(limit, pagination_key=pagination_key, visitor_id=visitor_id, bot=bot, ip_address=ip_address, linked_id=linked_id, start=start, end=end, reverse=reverse, suspect=suspect)
print(api_response)
except ApiException as e:
if e.body is not None:
error_response = ErrorResponse.from_json(e.body)
if error_response is not None:
message = f"API request failed: {error_response.error.code} {error_response.error.message}"
else:
message = f"API request failed with unexpected error format: {e}"
else:
message = f'Exception when calling FingerprintApi->get_event: {e}'
print(message)
```
了解更多信息，请参考位于 [examples/search_events_example.py](examples/search_events_example.py) 的示例。
更新 `eventId` 对应的事件：
```
import os
import fingerprint_server_sdk
from fingerprint_server_sdk import ApiException, EventUpdate, ErrorResponse
from fingerprint_server_sdk.configuration import Region
# 配置 API key 授权和区域
configuration = fingerprint_server_sdk.Configuration(
api_key = os.environ["SECRET_API_KEY"],
region = Region.US
)
api_instance = fingerprint_server_sdk.FingerprintApi(configuration)
event_id = 'event_id_example'
body = EventUpdate(linked_id='foo')
# body = EventUpdate(tags={'bar': 123})
# body = EventUpdate(suspect=True)
# body = EventUpdate(linked_id='foo', tags={'bar': 123}, suspect=False)
try:
api_instance.update_event(event_id, body)
except ApiException as e:
if e.body is not None:
error_response = ErrorResponse.from_json(e.body)
if error_response is not None:
message = f"API request failed: {error_response.error.code} {error_response.error.message}"
else:
message = f"API request failed with unexpected error format: {e}"
else:
message = f'Exception when calling FingerprintApi->update_event: {e}'
print(message)
```
了解更多信息，请参考位于 [examples/update-event_example.py](examples/update_event_example.py) 的示例。
## 密封结果
此 SDK 提供用于解码[密封结果](https://dev.fingerprint.com/docs/sealed-client-results)的实用方法。
```
import base64
import os
from dotenv import load_dotenv
from fingerprint_server_sdk import unseal_event_response, DecryptionKey, DecryptionAlgorithm
load_dotenv()
sealed_result = base64.b64decode(os.environ["BASE64_SEALED_RESULT"])
key = base64.b64decode(os.environ["BASE64_KEY"])
try:
event_response = unseal_event_response(sealed_result, [DecryptionKey(key, DecryptionAlgorithm['Aes256Gcm'])])
print("\n\n\nEvent response: \n", event_response)
except Exception as e:
print(f'Exception when calling unsealing events response: {e}\n')
exit(1)
print("Unseal successful!")
exit(0)
```
了解更多信息，请参考位于 [examples/sealed_results_example.py](examples/sealed_results_example.py) 的示例。
## Webhook 签名验证
此 SDK 提供用于验证传入 webhook 请求 HMAC 签名的实用方法。
```
import os
from flask import Flask, request, jsonify
from fingerprint_server_sdk import WebhookValidation
app = Flask(__name__)
@app.route('/api/webhook', methods=['POST'])
def webhook_handler():
try:
# Retrieve the secret key from environment variables
secret = os.getenv("WEBHOOK_SIGNATURE_SECRET")
if not secret:
return jsonify({"message": "Secret key is not configured."}), 400
# Get the "fpjs-event-signature" header from the incoming request
header = request.headers.get('fpjs-event-signature')
if not header:
return jsonify({"message": "Missing fpjs-event-signature header."}), 400
# Read the raw body of the incoming request
data = request.get_data()
# Validate the webhook signature
is_valid = WebhookValidation.is_valid_webhook_signature(header, data, secret)
if not is_valid:
return jsonify({"message": "Webhook signature is invalid."}), 403
# Process the webhook data here
return jsonify({"message": "Webhook received."}), 200
except Exception as e:
# Handle any unexpected errors
return jsonify({"error": str(e)}), 500
if __name__ == '__main__':
# Start the Flask application on the specified host and port
app.run(host='0.0.0.0', port=5000)
```
了解更多信息，请参考位于 [examples/webhook_signature_example.py](examples/webhook_signature_example.py) 的示例。
## API 端点文档
所有 URI 都相对于 *https://api.fpjs.io/v4*
类 | 方法 | HTTP 请求 | 描述
------------ | ------------- | ------------- | -------------
*FingerprintApi* | [**delete_visitor_data**](docs/FingerprintApi.md#delete_visitor_data) | **DELETE** /visitors/{visitor_id} | 根据访问者 ID 删除数据
*FingerprintApi* | [**get_event**](docs/FingerprintApi.md#get_event) | **GET** /events/{event_id} | 根据事件 ID 获取事件
*FingerprintApi* | [**search_events**](docs/FingerprintApi.md#search_events) | **GET** /events | 搜索事件
*FingerprintApi* | [**update_event**](docs/FingerprintApi.md#update_event) | **PATCH** /events/{event_id} | 更新事件
## 模型文档
- [BotInfo](docs/BotInfo.md)
- [BotResult](docs/BotResult.md)
- [BrowserDetails](docs/BrowserDetails.md)
- [Canvas](docs/Canvas.md)
- [Emoji](docs/Emoji.md)
- [Error](docs/Error.md)
- [ErrorCode](docs/ErrorCode.md)
- [ErrorResponse](docs/ErrorResponse.md)
- [Event](docs/Event.md)
- [EventRuleAction](docs/EventRuleAction.md)
- [EventRuleActionAllow](docs/EventRuleActionAllow.md)
- [EventRuleActionBlock](docs/EventRuleActionBlock.md)
- [EventSearch](docs/EventSearch.md)
- [EventUpdate](docs/EventUpdate.md)
- [FontPreferences](docs/FontPreferences.md)
- [Geolocation](docs/Geolocation.md)
- [GeolocationSubdivisionsInner](docs/GeolocationSubdivisionsInner.md)
- [IPBlockList](docs/IPBlockList.md)
- [IPInfo](docs/IPInfo.md)
- [IPInfoV4](docs/IPInfoV4.md)
- [IPInfoV6](docs/IPInfoV6.md)
- [Identification](docs/Identification.md)
- [IdentificationConfidence](docs/IdentificationConfidence.md)
- [IncrementalIdentificationStatus](docs/IncrementalIdentificationStatus.md)
- [Integration](docs/Integration.md)
- [IntegrationSubintegration](docs/IntegrationSubintegration.md)
- [PluginsInner](docs/PluginsInner.md)
- [PluginsInnerMimeTypesInner](docs/PluginsInnerMimeTypesInner.md)
- [Proximity](docs/Proximity.md)
- [ProxyConfidence](docs/ProxyConfidence.md)
- [ProxyDetails](docs/ProxyDetails.md)
- [RareDevicePercentileBucket](docs/RareDevicePercentileBucket.md)
- [RawDeviceAttributes](docs/RawDeviceAttributes.md)
- [RequestHeaderModifications](docs/RequestHeaderModifications.md)
- [RuleActionHeaderField](docs/RuleActionHeaderField.md)
- [RuleActionType](docs/RuleActionType.md)
- [SDK](docs/SDK.md)
- [SearchEventsBot](docs/SearchEventsBot.md)
- [SearchEventsIncrementalIdentificationStatus](docs/SearchEventsIncrementalIdentificationStatus.md)
- [SearchEventsRareDevicePercentileBucket](docs/SearchEventsRareDevicePercentileBucket.md)
- [SearchEventsSdkPlatform](docs/SearchEventsSdkPlatform.md)
- [SearchEventsVpnConfidence](docs/SearchEventsVpnConfidence.md)
- [SupplementaryIDHighRecall](docs/SupplementaryIDHighRecall.md)
- [TamperingConfidence](docs/TamperingConfidence.md)
- [TamperingDetails](docs/TamperingDetails.md)
- [TouchSupport](docs/TouchSupport.md)
- [Velocity](docs/Velocity.md)
- [VelocityData](docs/VelocityData.md)
- [VpnConfidence](docs/VpnConfidence.md)
- [VpnMethods](docs/VpnMethods.md)
- [WebGlBasics](docs/WebGlBasics.md)
- [WebGlExtensions](docs/WebGlExtensions.md)
## 密封结果文档
- [SealedResults](docs/SealedResults.md)
- [DecryptionKey](docs/DecryptionKey.md)
## 支持
如需报告问题、提问或提供反馈，请使用 [Issues](https://github.com/fingerprintjs/python-sdk/issues)。
如果你需要私人支持，可以通过 [oss-support@fingerprint.com](mailto:oss-support@fingerprint.com) 给我们发送电子邮件。
## 许可证
本项目基于 [MIT License](https://github.com/fingerprintjs/python-sdk/blob/main/LICENSE) 授权。
标签：API集成, Fingerprint Pro, PyPI, Python, Server API, Streamlit, 反欺诈, 可观测性, 开源, 无后门, 机器人检测, 浏览器指纹, 网络安全, 设备指纹, 设备智能, 访客识别, 访问控制, 逆向工具, 隐私保护
