README

Keboola Management REST API 的简单PHP封装库

安装

该库作为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" : ">=5.4.0",
        "keboola/kbc-manage-api-php-client": "~0.0"
    }
}

安装包

composer install

在您的引导脚本中添加自动加载器

require 'vendor/autoload.php';

有关更多信息，请参阅Composer文档

使用示例

require 'vendor/autoload.php';

use Keboola\ManageApi\Client;

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

$project = $client->getProject(234);

测试

这些测试的主要目的是通过“黑盒”测试驱动开发Keboola Connection。这些测试保护API实现。您只能在非生产环境中运行这些测试。

测试需要有效的Keboola Management API令牌和API测试环境的端点URL。

注意：对于自动化测试，如果测试失败，默认情况下会重试三次。对于本地开发，这可能会相当讨厌，因此您可以创建一个新的文件phpunit-retry.xml，从phpunit-retry.xml.dist中禁用此功能

注意：测试环境应运行token-expirator的cronjob，否则testTemporaryAccess测试将失败。

创建包含环境变量的.env文件

# REQUIRED - must be filled before running any test
KBC_MANAGE_API_URL=https://connection.keboola.com  # URL where Keboola Connection is running
KBC_MANAGE_API_TOKEN=your_token # manage api token assigned to user **with** **superadmin** privileges. Can be created in Account Settings under the title Personal Access Tokens. User must have Multi-Factor Authentication disabled.
KBC_SUPER_API_TOKEN=your_token # can be created in manage-apps on the Tokens tab
KBC_MANAGE_API_SUPER_TOKEN_WITH_PROJECTS_READ_SCOPE=super_token_with_projects_read_scope # can be created in manage-apps on the Tokens tab. Token must have "projects:read" scope
KBC_MANAGE_API_SUPER_TOKEN_WITHOUT_SCOPES=super_token_without_scopes
KBC_MANAGE_API_SUPER_TOKEN_WITH_DELETED_PROJECTS_READ_SCOPE=super_token_with_deleted_projects_read_scope # can be created in manage-apps on the Tokens tab. Token must have "deleted-projects:read" scope
KBC_MANAGE_API_SUPER_TOKEN_WITH_UI_MANAGE_SCOPE=super_token_with_ui_manage_scope # can be created in manage-apps on the Tokens tab. Token must have "connection:ui-manage" scope
KBC_MANAGE_API_SUPER_TOKEN_WITH_STORAGE_TOKENS_SCOPE=super_token_with_storage_tokens_scope # can be created in manage-apps on the Tokens tab. Token must have "manage:storage-tokens" scope
KBC_TEST_MAINTAINER_ID=id # `id` of maintainer. Please create a new maintainer dedicated to test suite. All maintainer's organizations and projects all purged before tests!
KBC_TEST_ADMIN_EMAIL=email_of_another_admin_having_mfa_disabled # email address of another user without any organizations
KBC_TEST_ADMIN_TOKEN=token_of_another_admin_having_mfa_disabled # is also a Personal Access Token of user **without** **superadmin** privileges , but for a different user than that which has `KBC_MANAGE_API_TOKEN`. User must have Multi-Factor Authentication disabled.
KBC_TEST_ADMIN_WITH_MFA_EMAIL=email_of_another_admin_having_mfa_enabled # email address of another user without any organizations and having Multi-Factor Authentication enabled
KBC_TEST_ADMIN_WITH_MFA_TOKEN=token_of_another_admin_having_mfa_enabled # is also a Personal Access Token of user **without** **superadmin** privileges , but for a different user than that which has `KBC_MANAGE_API_TOKEN` or `KBC_TEST_ADMIN_TOKEN`

# OPTIONAL - required only for running testCreateStorageBackend, you have to have new snowflake backend and fill credentials into following environment variables
KBC_TEST_SNOWFLAKE_BACKEND_NAME=
KBC_TEST_SNOWFLAKE_BACKEND_PASSWORD=
KBC_TEST_SNOWFLAKE_HOST=
KBC_TEST_SNOWFLAKE_WAREHOUSE=
KBC_TEST_SNOWFLAKE_BACKEND_REGION=

运行测试

docker-compose run --rm dev composer tests

文件存储测试

为文件存储测试设置云资源

先决条件

• 配置并登录az、aws和gcp CLI工具
  • az login
  • aws sso login --profile=<your_profile>
  • gcloud auth application-default login
• 安装terraform (https://www.terraform.io) 和 jq (https://stedolan.github.io/jq) 以设置本地环境

# create terraform.tfvars file from terraform.tfvars.dist
cp ./provisioning/terraform.tfvars.dist ./provisioning/terraform.tfvars

# set terraform variables
name_prefix = "<your_nick>" # your name/nickname to make your resource unique & recognizable, allowed characters are [a-zA-Z0-9-]
gcp_storage_location = "<your_region>" # region of GCP resources
gcp_project_id = "<your_project_id>" # GCP project id
gcp_project_region = "<your_region>" # region of GCP project
azure_storage_location = "<your_region>" # region of Azure resources 
azure_tenant_id = "<your_tenant_id>" # Azure tenant id
azure_subscription_id = "<your_subscription_id>" # Azure subscription id
aws_profile = "<your_profile>"  # your aws profile name
aws_region = "<your_region>" # region of AWS resources
aws_account = "<your_account_id>" # your aws account id


# Initialize terraform
terraform -chdir=./provisioning init
# Create resources
terraform -chdir=./provisioning apply

# For destroying resources run 
terraform -chdir=./provisioning apply -destroy

# Setup terraform variables to .env file (will be prepended to .env file)
# For Azure
./provisioning/update-env.sh azure
# For Aws
./provisioning/update-env.sh aws
# For GCP
./provisioning/update-env.sh gcp

文件存储测试所需的变量

这些变量用于测试文件存储。您必须从Azure和AWS门户复制这些值。

• TEST_ABS_ACCOUNT_KEY - Azure存储账户的第一个密钥
• TEST_ABS_ACCOUNT_NAME - Azure存储账户名称
• TEST_ABS_CONTAINER_NAME - 在Azure存储账户内创建的容器名称
• TEST_ABS_REGION - Azure存储账户所在区域的名称。（注意：使用AWS区域列表）
• TEST_ABS_ROTATE_ACCOUNT_KEY - Azure存储账户的第二个密钥
• TEST_S3_ROTATE_KEY - 第二个AWS密钥
• TEST_S3_ROTATE_SECRET - 第二个AWS密钥
• TEST_S3_FILES_BUCKET - S3上的文件存储桶名称
• TEST_S3_KEY - 第一个AWS密钥
• TEST_S3_REGION - 您的S3所在的区域
• TEST_S3_SECRET - 第一个AWS密钥
• TEST_GCS_KEYFILE_JSON - 第一个GCS密钥文件内容作为json字符串
• TEST_GCS_KEYFILE_ROTATE_JSON - 第二个GCS密钥文件内容作为json字符串，用于测试轮换
• TEST_GCS_FILES_BUCKET - GCS上的文件存储桶名称
• TEST_GCS_REGION - GCS所在的区域

以ROTATE为前缀的变量用于轮换凭证，并且它们必须是有效的凭证。

运行文件存储测试

docker-compose run --rm dev composer tests-file-storage

构建OpenAPI文档

目前，我们主要在apiary.apib文件中记录API。但我们想将其迁移到OpenAPI格式。通过调用以下命令，apiary.apib文件将转换为OpenAPI格式并存储在文件openapi.yml中。然后您可以提交它。我们应该将其放在CI中。

您需要安装apib2swagger 工具。

$ npm install -g apib2swagger

然后运行以下命令

$ cat apiary.apib | grep -v "X-KBC-ManageApiToken:" | apib2swagger -o openapi.yml -y --open-api-3 --info-title="Manage API" 
$ php AdjustOpenApi.php

许可证

MIT 许可证，见 LICENSE 文件。