README

此文档作为 CRM 骨架 文档的补充，与创建和注册 API 处理程序相关。

它描述了该模块提供的 API 处理程序，供他人使用。

启用模块

确保您已将扩展添加到 app/config/config.neon 文件中。

extensions:
	- Crm\ApiModule\DI\ApiModuleExtension

配置

预请求

模块允许您配置预请求处理。将以下代码片段添加到您的 config.neon 文件中

services:
	# ...
	apiHeadersConfig:
		setup:
			- setAllowedOrigins('*')
			- setAllowedHeaders('Content-Type', 'Authorization', 'X-Requested-With')
			- setAllowedHttpMethods('*')
			- setAllowedCredentials(true)
			- setAccessControlMaxAge(600) # seconds

您可以通过明确指定它们或使用通配符来配置允许的源。以下配置是有效的

• setAllowedOrigins("*")。匹配一切
• setAllowedOrigins("foo.bar", "*.foo.bar")。匹配 foo.bar 及其所有子域。
• setAllowedOrigins("foo.bar", "1.foo.bar")。匹配 foo.bar 和 1.foo.bar，但不是其他内容（也不是任何其他子域）。

API 请求日志记录

您可以在 CRM 管理员 - 配置部分全局启用或禁用 API 日志记录。如果启用日志记录，您可以进一步配置哪些特定路径应该记录或不应记录。

我们建议使用黑名单配置而不是白名单配置。否则，您可能会遇到这种情况，即在我们的一些 API 中，当您需要它们时，可能会缺少日志。

要启用黑名单，将以下代码片段添加到您的 config.neon 文件中

services:
	# ...
	apiLoggerConfig:
		setup:
			- setPathBlacklist([
				Crm\ApiModule\Models\LoggerEndpointIdentifier('1', 'foo', 'bar'),
			])

LoggerEndpointIdentifier 需要三个参数： version、package 和 apiCall - 与您注册新 API 处理程序时使用的相同参数。上面的代码片段将不会记录对 /api/v1/foo/bar 端点的请求。

在必要时，您也可以使用通配符

• Crm\ApiModule\Models\LoggerEndpointIdentifier('*', 'foo', 'bar') 将匹配所有前往 /api/*/foo/bar 的请求。
• Crm\ApiModule\Models\LoggerEndpointIdentifier('1', '*', '*') 将匹配所有前往 /api/v3/*/* 的请求。

黑名单和白名单不能结合使用，后者配置的优先。

数据保留配置

您可以通过在项目配置文件中设置 application:cleanup 来配置删除旧仓库数据和它使用的列之前的时间。

apiLogsRepository:
	setup:
		- setRetentionThreshold('-2 months', 'created_at')

数据库表迁移

由于需要更改主键（int -> bigint），在包含大量数据（或具有主键溢出风险的 int）的表中，我们不得不创建迁移过程。由于一些表非常暴露，不能锁定超过几秒钟，我们决定创建新表，手动迁移数据，并在迁移过程中保持旧表和新表同步。

此迁移过程对于在特定版本后安装特定表的安装是必要的，并且是两步过程。

Api 日志迁移（安装版本低于 2.5.0）

包括 api_logs 表的迁移。

步骤

1. 运行 phinx 迁移命令 phinx:migrate，该命令创建新表 api_logs_v2（如果表中没有数据，迁移仅更改主键类型，下一步不再需要）。
2. 运行命令 api:convert_api_logs_to_bigint，该命令将旧表中的数据复制到新表（例如，从 api_logs 到 api_logs_v2）。命令在迁移成功后原子性地重命名表（例如，api_logs -> api_logs_old 和 api_logs_v2 -> api_logs），因此当迁移结束时，仅使用新表。

建议在成功迁移后至少运行2周（以保留备份数据，以防出现任何问题），再执行application:bigint_migration_cleanup api_logs命令来删除剩余的表。

API文档

所有示例都使用http://crm.press作为基础域名。请在执行示例之前将主机更改为您使用的域名。

所有示例都使用XXX作为默认的授权令牌值，请将其替换为实际的令牌。

• API令牌。标准API密钥用于服务器间通信。它将调用应用程序作为一个整体进行识别。它们可以在CRM管理员界面（/api/api-tokens-admin/）中生成，每个API密钥都必须白名单才能访问特定的API端点。默认情况下，API密钥没有任何端点访问权限。
• 用户令牌。在登录过程中为每个用户生成，令牌在系统不同部分之间通信时识别单个用户。令牌可以从以下位置读取：
  • n_token cookie（如果用户通过CRM登录）。
  • /api/v1/users/login端点的响应中 - 您可以将响应存储到自己的cookie/local storage/session中。

API响应可以包含以下HTTP代码

如果可能，响应将包含application/json编码的有效载荷，其中包含进一步解释错误的消息。

GET /api/v1/token/check

API服务器用于检查在头部提供的Bearer令牌的有效性。

头部

示例

curl -v –X GET http://crm.press/api/v1/token/check \ 
-H "Content-Type:application/json" \
-H "Authorization: Bearer XXX"

响应

{
    "status": "ok"
}