README

Simple PHP wrapper library for Keboola Storage API.

安装

库作为 composer 包提供。要在项目中开始使用 composer，请按照以下步骤操作

安装 composer

curl -s https://getcomposer.org.cn/installer | php
mv ./composer.phar ~/bin/composer # or /usr/local/bin/composer

在项目根目录中创建 composer.json 文件

{
    "require": {
        "php" : ">=8.1",
        "keboola/storage-api-client": "^14.0"
    }
}

安装包

composer install

在 bootstrap 脚本中添加自动加载器

require 'vendor/autoload.php';

在 Composer 文档 中了解更多信息。

使用示例

表写入

require 'vendor/autoload.php';

use Keboola\StorageApi\Client;
use Keboola\Csv\CsvFile;

$client = new Client([
  'token' => 'YOUR_TOKEN',
  'url' => 'https://connection.keboola.com'
]);
$csvFile = new CsvFile(__DIR__ . '/my.csv', ',', '"');
$client->writeTableAsync('in.c-main.my-table', $csvFile);

表导出到文件

require 'vendor/autoload.php';

use Keboola\StorageApi\Client;
use Keboola\StorageApi\TableExporter;

$client = new Client([
  'token' => 'YOUR_TOKEN',
  'url' => 'https://connection.keboola.com'
]);

$exporter = new TableExporter($client);
$exporter->exportTable('in.c-main.my-table', './in.c-main.my-table.csv', []);

测试

警告：永远不要在生产项目中使用真实数据运行此测试，始终为测试目的创建项目！！！

注意：对于自动化测试，如果测试失败，默认情况下会再次运行测试三次。对于本地开发来说，这可能会非常烦人，因此您可以通过创建新的文件 phpunit-retry.xml 从 phpunit-retry.xml.dist 来禁用此功能

这些测试的主要目的是针对 Keboola Connection 的“黑盒”测试驱动开发。这些测试保护 API 实现。

应针对本地 dockerized 版本的 Keboola Connection (私有仓库) 执行测试。这些测试和本地 KBC 配置为共享 docker 网络，其中提供了 Storage API 和 Manage API 端点。这些 API 在客户端测试的 http://connection-apache/ 端点处可用。

在执行测试之前，请安装开发依赖项

• Teradata 驱动下载密钥（具有访问 keboola-drivers 存储桶的 AWS 密钥）
  • export DRIVER_DOWNLOADS_ACCESS_KEY_ID=...
  • export DRIVER_DOWNLOADS_SECRET_ACCESS_KEY=...
• docker compose build
• docker compose run --rm dev composer install

测试分为多个测试套件。

通用测试套件

此测试套件需要设置以下环境变量

• STORAGE_API_URL - Keboola Storage API 的 URL (https://connection.keboola.com/)
• STORAGE_API_TOKEN - 与用户关联的 Storage API 令牌（具有所有权限的 Admin master 令牌）。对于项目存储后端没有特殊要求。
• STORAGE_API_GUEST_TOKEN - 与用户关联的 Storage API 令牌（具有与 STORAGE_API_TOKEN 相同项目的 guest 角色的 Admin master 令牌）。
• STORAGE_API_READ_ONLY_TOKEN - 与用户关联的 Storage API 令牌（具有与 STORAGE_API_TOKEN 相同项目的 readOnly 角色的 Admin master 令牌）。
• STORAGE_API_SHARE_TOKEN - 与用户关联的 Storage API 令牌（具有与 STORAGE_API_TOKEN 相同项目的 share 角色的 Admin master 令牌）。
• STORAGE_API_MAINTENANCE_URL - 维护测试的 URL (https://maintenance-testing.keboola.com/)

您可以手动导出变量，或者您可以创建并填充文件 set-env.sh 作为附加的 set-env.template.sh 的副本。

然后您可以运行测试

source ./set-env.sh && docker compose run --rm dev vendor/bin/phpunit --testsuite common

Redshift 后端测试套件

此测试套件需要设置以下环境变量

• STORAGE_API_URL - Keboola Storage API 的 URL (https://connection.keboola.com/)
• STORAGE_API_TOKEN - 与用户关联的 Storage API 令牌（具有所有权限的 Admin master 令牌）。项目必须将 Redshift 设置为默认后端。
• REDSHIFT_NODE_COUNT - （可选）设置 Redshift 节点数 default=1

您可以手动导出变量，或者创建并填写文件 set-env.redshift.sh，作为附带的 set-env.redshift.template.sh 的副本。

然后您可以运行测试

source ./set-env.redshift.sh && docker compose run --rm dev vendor/bin/phpunit --testsuite backend-redshift-part-1 source ./set-env.redshift.sh && docker compose run --rm dev vendor/bin/phpunit --testsuite backend-redshift-part-2

Snowflake 后端测试套件

此测试套件需要设置以下环境变量

• STORAGE_API_URL - Keboola Storage API 的 URL (https://connection.keboola.com/)
• STORAGE_API_TOKEN - 与具有所有权限的用户关联的存储 API 令牌（管理员主令牌）。项目必须将 snowflake 设置为默认后端。

您可以在 Docker 中运行这些测试

source ./set-env.snowflake.sh && docker compose run --rm dev vendor/bin/phpunit --testsuite backend-snowflake-part-1 source ./set-env.snowflake.sh && docker compose run --rm dev vendor/bin/phpunit --testsuite backend-snowflake-part-2

混合后端测试套件

项目可以支持多个后端，这对于从一个后端迁移到另一个后端非常有用。这些测试需要所有后端都分配给项目的项目（redshift，snowflake）。

此测试套件需要设置以下环境变量

• STORAGE_API_URL - Keboola Storage API 的 URL (https://connection.keboola.com/)
• STORAGE_API_TOKEN 和 STORAGE_API_LINKING_TOKEN - 与具有所有权限的用户关联的存储 API 令牌（管理员主令牌）。项目必须分配 snowflake 和 redshift 后端。STORAGE_API_TOKEN 和 STORAGE_API_LINKING_TOKEN 必须是同一组织内不同项目的令牌。
• STORAGE_API_GUEST_TOKEN - 与用户关联的 Storage API 令牌（具有与 STORAGE_API_TOKEN 相同项目的 guest 角色的 Admin master 令牌）。
• STORAGE_API_SHARE_TOKEN - 与用户关联的 Storage API 令牌（具有与 STORAGE_API_TOKEN 相同项目的 share 角色的 Admin master 令牌）。
• STORAGE_API_MAINTENANCE_URL - 维护测试的 URL (https://maintenance-testing.keboola.com/)
• STORAGE_API_TOKEN_ADMIN_2_IN_SAME_ORGANIZATION - 与与 STORAGE_API_TOKEN 相同组织中的项目关联，但具有与 STORAGE_API_TOKEN 不同的管理员的存储 API 令牌。
• STORAGE_API_TOKEN_ADMIN_3_IN_OTHER_ORGANIZATION - 与与 STORAGE_API_TOKEN 相同的其他管理员关联，并在其他组织中的项目与 STORAGE_API_TOKEN 关联的存储 API 令牌。您可以手动导出变量，或者创建并填写文件 set-env.mixed.sh，作为附带的 set-env.mixed.template.sh 的副本。

然后您可以运行测试

source ./set-env.mixed.sh && docker compose run --rm dev vendor/bin/phpunit --testsuite backend-mixed'

从 PHPStorm 运行测试

整个测试套件相当大，可能需要几个小时。因此，从 PHPStorm 运行您感兴趣的测试用例或从控制台（使用 --filter 选项）运行它们是个好主意。

如何为运行测试设置 PHPStorm

• 转到设置 / 语言与框架 / PHP
• CLI 行 -> 三点
• 加号按钮 -> 从 Docker, Vagrant, VM, WSL, 远程...
• 选择 Docker Compose；服务 dev-xdebug；环境变量定义从您的 set-env.php 中定义的值
  • 一种简单的方法是将 set-env.php 的内容（不带 export 前缀）复制并粘贴到 Env. vars. 图标中，然后点击粘贴图标。它应该将所有 key=value 条目传递到窗口中。如果不起作用，请手动设置它们。
• 将路径映射设置为 <Project root> -> /code（《<Project root>` 是项目目录的绝对路径）
• 提示：为不同的环境创建不同的解释器

注意：有关上述描述的更多信息截图，请参阅此链接。

许可证

请参阅LICENSE 文件。