初始化开发工具包

云眼About 9 min

初始化开发工具包

本主题介绍如何在应用程序中初始化云眼灰度发布（特性标帜）AB实验 Ruby SDK。

使用instantiate方法初始化 Ruby SDK 并实例化 Eyeofcloud 客户端类的实例，该实例公开 API 方法（如 Decide 方法）。每个客户端对应于表示特定环境的项目状态的数据文件。

版本

SDK v3.3.2 及更高版本

描述

构造函数接受配置对象来配置云眼灰度发布（特性标帜）AB实验。

某些参数是可选的，因为 SDK 提供默认实现，但开发者可能希望为生产环境覆盖这些参数。例如，开发者可能希望设置错误处理程序和记录器来捕获问题，设置事件调度程序来管理网络调用，以及用户配置文件服务以确保粘性分桶。

参数

下表列出了该方法的必需参数和可选参数：start

参数类型描述
数据文件(可选)字符串表示项目的 JSON 字符串。
event_dispatcher(可选)事件调度程序用于管理网络调用的事件处理程序。
记录器(可选)记录用于记录问题的记录器实现。
error_handler(可选)错误处理程序用于处理错误的错误处理程序对象。
user_profile_service(可选)用户配置文件服务用户配置文件服务。
skip_json_validation(可选)布尔指定是否应验证 JSON。设置为true以跳过架构上的 JSON 验证，或false执行验证。
access_token(可选)字符串（仅限服务器端）云眼灰度发布（特性标帜）AB实验 SDK 可以使用访问令牌（与 SDK 密钥结合使用）从经过身份验证的终结点提取数据文件。在 Eyeofcloud 应用程序的设置>环境中找到数据文件访问令牌。选择安全环境，然后复制_数据文件访问令牌_。
default_decide_options(可选)数组Arrary of EyeofcloudDecideOption enums.当使用此参数构造 Eyeofcloud 客户端时，它会设置默认的 decide 选项，这些选项将应用于在 Eyeofcloud 客户端的生命周期内进行的所有 Decide 调用。将选项传递给各个 Decide 方法将覆盖这些默认值。
有关决定选项的详细信息，请参阅云眼决策选项。

Returns

实例化云眼灰度发布（特性标帜）AB实验类的实例。

例子

云眼灰度发布（特性标帜）AB实验提供了开箱即用的功能，用于动态管理客户端或服务器上的数据文件（配置文件）。Ruby SDK 提供了ProjectConfigManager .该软件包还包括一个工厂类 EyeofcloudFactory，可以使用它使用 HttpProjectConfigManager 的默认配置实例化 Eyeofcloud Feature Experimentation SDK。

每当实验配置发生更改时，SDK 都会使用自动数据文件管理 （ADM） 来为你处理更改。在 Ruby SDK 中，可以提供sdkKey和datafile的其中之一或两者兼而有之。

  • 仅使用 SDK 密钥初始化时，SDK 将定期在后台轮询数据文件更改。
  • 仅使用数据文件初始化时，SDK 不会在后台轮询数据文件更改。
  • 同时使用 SDK 密钥和数据文件进行初始化时，SDK 将使用给定的数据文件，并在后台开始轮询数据文件更改。

使用 SDK 密钥进行实例化（推荐）

在 Ruby SDK 中，只需传递 SDK 密钥值即可实例化客户端。每当实验配置发生更改时，SDK 都会为你处理更改。

sdkKey作为字符串属性包含在传递给createInstance方法的选项对象中。

当您提供sdkKey时，SDK 实例将下载与该sdkKey关联的数据文件。下载完成后，SDK 实例会自行更新以使用下载的数据文件。

基本示例

下面的代码示例显示了基本的 Ruby ADM 用法。

Rubby

require 'eyeofcloud' 
require 'eyeofcloud/eyeofcloud_factory'  

# Initialize an Eyeofcloud client 
eyeofcloud_instance = Eyeofcloud::EyeofcloudFactory.default_instance('put_your_sdk_key_here')

高级示例

下面是一个代码示例，显示了 Ruby ADM 的高级配置。 以下各节介绍了高级配置属性。

此高级示例演示如何直接构造各个组件以覆盖各种配置。这使可以完全控制要使用的实现以及如何使用它们。

Rubby

require 'eyeofcloud' 
require 'eyeofcloud/eyeofcloud_factory' 
require 'eyeofcloud/config_manager/http_project_config_manager'    

sdk_key = ‘123456’   
http_project_config_manager = Eyeofcloud::HTTPProjectConfigManager.new(     
    sdk_key: sdk_key,     
    polling_interval: 10,   
)   

eyeofcloud_instance = Eyeofcloud::EyeofcloudFactory.default_instance_with_config_manager (http_project_config_manager )

Rubby

# Starting in 3.2+ there are convienence factory methods for instantiating clients 
require 'eyeofcloud/eyeofcloud_factory'  

# Instantiate with just the SDK key. The SDK will pull the datafile remotely. 
sdk_key = 'AWDj34sdlfklsdfks' eyeofcloud_client = Eyeofcloud::EyeofcloudFactory.default_instance(sdk_key)  

# You can optionally instantiate with a hard-coded datafile as well  
datafile = '{ revision: "42" }' 
eyeofcloud_client = Eyeofcloud::EyeofcloudFactory.default_instance(sdk_key, datafile)

具有其他可选参数的必需开发工具包密钥

Rubby

require 'eyeofcloud'   
eyeofcloud_instance = Eyeofcloud::EyeofcloudFactory.custom_instance(       
    'put_your_sdk_key_here',       
    datafile,       
    event_dispatcher,       
    logger,       
    error_handler,       
    skip_json_validation,       
    user_profile_service,       
    config_manager,       
    notification_center     
)

使用数据文件实例化

还可以使用硬编码的数据文件进行实例化。如果不传入 SDK 密钥，云眼客户端将不会自动同步较新版本的数据文件。每次检索更新的数据文件时，只需重新实例化同一客户端即可。

对于简单的应用程序，实例化客户端所需提供的只是一个数据文件，该文件指定给定环境的项目配置。对于大多数高级实现，需要根据特定要求自定义记录器或错误处理程序。

Rubby

# Instantiate with both SDK key and datafile. The SDK will use the hard-coded datafile and will start polling for new datafiles remotely. 
datafile = '{ revision: "42" }' 
eyeofcloud_client = Eyeofcloud::EyeofcloudFactory.default_instance(sdk_key, datafile)  

# You can also customize the various components of the SDK (i.e. logger, error handler) 
eyeofcloud_client = Eyeofcloud::EyeofcloudFactory.custom_instance(   
    sdk_key,    
    datafile   
    # event_dispatcher   
    # logger 
)  

# Prior to 3.2 you can instantiate with just a JSON datafile string 
eyeofcloud_client = Eyeofcloud::Project.new(datafile)

在 Rails 应用程序中初始化

要在 Rails 应用程序中使用 SDK，可以使用以下代码片段配置 SDK：

Rubby

# initialize a client 
Rails.configuration.eyeofcloud_client = Eyeofcloud::EyeofcloudFactory.default_instance('SDK_KEY_HERE')  

# you can access the client in your Rails controllers from the application config 
Rails.application.config.eyeofcloud_client

SDK 在初始化时会生成多个线程。这些线程具有无限循环，用于获取数据文件，以及在后台批处理和调度事件。在生成多个子进程的 Web 服务器中使用时，需要在生成这些子进程或工作线程后初始化 SDK：

Unicorn

Rubby

after_fork do |server, worker|    
    Rails.configuration.eyeofcloud_client = Eyeofcloud::EyeofcloudFactory.default_instance('SDK_KEY_HERE') 
end

Puma

Rubby

on_worker_boot do    
    Rails.configuration.eyeofcloud_client = Eyeofcloud::EyeofcloudFactory.default_instance('SDK_KEY_HERE') 
end

Passenger

Rubby

PhusionPassenger.on_event(:starting_worker_process) do |forked|  
    if forked    
        Rails.configuration.eyeofcloud_client = Eyeofcloud::EyeofcloudFactory.default_instance('SDK_KEY_HERE')  
    end 
end

HttpProjectConfigManager

HttpProjectConfigManager是ProjectConfigManageropen in new window接口的实现，它轮询数据文件并根据更新间隔更新DatafileProjectConfig。为了保持请求的异步性质，它使用AsyncScheduler，该程序向配置的URL发出HTTP GET请求，以异步下载项目数据文件并初始化DatafileProjectConfig的实例。

默认情况下，HttpProjectConfigManager 将阻塞，直到第一次成功检索数据文件，直到可配置的阻塞超时。设置初始化配置管理器时轮询方法的频率和阻塞超时。

Rubby

http_project_config_manager = Eyeofcloud::HTTPProjectConfigManager.new(   
    datafile: datafile   
    sdk_key: sdk_key,   
    polling_interval: 10,   
    blocking_timeout: 15 
)

开发工具包密钥

SDK 密钥用于将出站 HTTP 请求撰写到云眼 cdn 上的默认数据文件位置。

轮询间隔

轮询间隔用于指定数据文件的连续 HTTP 请求之间的固定延迟。

初始数据文件

可以在初始化配置管理器时提供初始数据文件以引导项目配置管理器，以便可以立即使用它而不会阻止执行。如果无法建立 HTTP 连接，初始数据文件还用作回退数据文件。这在无法保证互联网连接的移动环境中很有用。

初始数据文件将在第一次成功的数据文件轮询后被丢弃。

高级配置

以下属性可用于自定义 HttpProjectConfigManager 配置。

属性默认值描述
数据文件零初始数据文件，通常来自本地缓存源。
网址零用于为数据文件指定自定义 HTTP 源的 URL 覆盖位置。
url_template零通过 SDK 密钥参数化数据文件 URL。
polling_interval5 分钟修复了数据文件提取之间的延迟。有效持续时间介于 1 到 2592000 秒之间。否则，使用默认值。
blocking_timeout15 秒阻塞超时期限用于指定等待初始引导的最长时间。有效阻止超时期限介于 1 到 2592000 秒之间。否则，使用默认值。
sdk_key零云眼灰度发布（特性标帜）AB实验项目SDK密钥;除非源 URL 被覆盖，否则是必需的。
auto_update真布尔标帜，用于指定数据文件轮询的回调是需要无限执行还是仅执行一次。
start_by_default真布尔标帜，用于指定是否应在初始化 HTTPConfigManager 后立即开始数据文件轮询。

更新配置通知

每当获取新的数据文件并更新相应的项目配置时，都会触发通知信号。要订阅这些通知，请使用notification_center.add_notification_listener()方法。

Rubby

notification_center.add_notification_listener(Eyeofcloud::NotificationCenter::NOTIFICATION_TYPES[:EYEOFCLOUD_CONFIG_UPDATE], @callback );

云眼工厂

EyeofcloudFactory 提供了基本的实用程序，以最少数量的配置选项实例化 Eyeofcloudopen in new window 功能实验 SDK。

EyeofcloudFactory 不会捕获所有配置和初始化选项。有关更多用例，请使用其构造函数构建资源。

必须在运行时直接通过工厂方法提供 SDK 密钥：

Ruby

eyeofcloud_instance = Eyeofcloud::EyeofcloudFactory.default_instance(   ’123456’ )

启用 JSON 机构验证

跳过 JSON 架构验证可提高实例化期间的性能。在 Ruby SDK 中，可以控制在实例化客户端时是否验证数据文件的 JSON 架构。此示例演示如何跳过 JSON 架构验证：

Rubby

# Skip JSON schema validation (SDK versions 0.1.1 and above) 
eyeofcloud_client = Eyeofcloud::Project.new(datafile, nil, nil, nil, true)

在安全环境中使用经过身份验证的数据文件

📘

测试版功能

如果有兴趣成为经过身份验证的数据文件的早期用户，作为测试版安全环境功能的一部分，请联系客户成功经理。

可以使用服务器端（仅限）云眼灰度发布（特性标帜）AB实验 SDK 从经过身份验证的终结点提取 Eyeofcloud 数据文件。若要使用经过身份验证的数据文件，请从**“设置****>环境**”中的应用下载环境的访问令牌。选择安全环境，然后复制_数据文件访问令牌_。下面的示例显示了如何使用访问令牌和sdk_key初始化 Eyeofcloud 客户端，使客户端能够获取经过身份验证的数据文件并完成初始化。

Rubby

# fetch the datafile from an authenticated endpoint 
require "eyeofcloud"  

sdk_key = '<YOUR_SDK_KEY>' 
datafile_access_token = '<YOUR_DATAFILE_ACCESS_TOKEN>'  

config_manager = Eyeofcloud::HTTPProjectConfigManager.new(     
    sdk_key: sdk_key,     
    datafile_access_token: datafile_access_token   
)  

eyeofcloud_client = Eyeofcloud::Project.new(         
    nil ,nil, nil, nil, nil, nil,         
    nil, config_manager, nil, nil       
)
Last update:
Contributors: zhangweixue,“zhangweixue”