README

概要

该库旨在使与 SurveyGizmo 集成比直接使用 API 更容易、更快。以下对象通过此库支持，并全部命名空间在 SurveyGizmo 下（例如，\SurveyGizmo\Resources\Survey）。

需求

PHP 5.3+
cURL
有效的 SurveyGizmo 账户

手动安装

下载库并将其添加到您的项目中。
包含 SurveyGizmoAutoLoader.php 文件，将 <LIBRARY_PATH> 替换为适当的路径。

require_once "<LIBRARY_PATH>/SurveyGizmoAutoLoader.php";

配置

如果您不在我们的美国数据中心使用，则需要选择适当的区域（美国、加拿大或欧洲）。如果您不确定是否使用的是美国、欧洲或加拿大 API，请参阅：https://apihelp.surveygizmo.com/help/us-eu-or-ca-api

try {
	\SurveyGizmo\SurveyGizmoAPI::setRegion('EU');
} catch (Exception $e) {
	die('Region not available');
}

使用您的 SurveyGizmo API 密钥和密钥进行认证。

try {
	\SurveyGizmo\SurveyGizmoAPI::auth("<YOUR API_KEY>", "<YOUR API_SECRET>");
} catch (Exception $e) {
	die("Error Authenticating");
}

如果需要，配置速率限制。

//set max retries of requests to 10, when request is rate limited it will be retried after 5 seconds.
\SurveyGizmo\ApiRequest::setRepeatRateLimitedRequest(10);

如果需要，配置请求超时持续时间（以秒为单位，如果未指定，则默认为 35）

//this is the maximum wait period before aborting requests, you may need to
//increase this from the default of 35 seconds if working with oversize surveys
\SurveyGizmo\ApiRequest::setRequestTimeout(60);

代码示例

有关更详细的示例用法，请参阅示例文件夹。

要使用这些示例，请复制示例文件，然后提供您自己的凭据

$ cd Samples
$ cp .credentials.example .credentials
$ vi .credentials # then supply your credentials accordingly
$ php new_survey.php # run once prior to running manipulate_survey.php
$ php manipulate_survey.php

支持的对象

调查
- 响应
- 问题
- 页面
- 统计信息
- 报告
- 活动
  - 电子邮件消息
账户
- 用户
- 团队
联系人
联系人列表
- 联系人

API 对象参考

此库使用版本 5 的 SurveyGizmo API，有关更多信息，请参阅我们的 API 文档。

所有对象都使用以下标准函数

<OBJECT>::fetch(<FILTERS>,<OPTIONS>);

基于筛选和分页选项返回对象数组。

<OBJECT>::get($id);

基于 ID 返回单个对象。

<OBJECT>->save();

保存新创建或更新的对象实例。

<OBJECT>->delete();

删除对象实例。

调查

获取调查

请参阅以下筛选和分页。

$surveys = \SurveyGizmo\Resources\Survey::fetch(<FILTER>,<OPTIONS>);

获取单个调查

$survey_id = <SURVEY_ID>;
$survey = \SurveyGizmo\Resources\Survey::get(survey_id);

更新调查

$survey->title = "TEST UPDATE FROM API LIBRARY";
$survey->save();

创建调查

$survey = new \SurveyGizmo\Resources\Survey();
$survey->title = "NEW SURVEY";
$results = $survey->save();

删除调查

$survey = $survey->delete();

调查辅助函数

调查对象提供了一些辅助函数，以便轻松访问相关集合和对象。

	//get questions
	$survey->getQuestions(<FILTER>,<PAGE>);
	$survey->getQuestion($question_id);
	//get responses
	$survey->getResponses(<FILTER>,<PAGE>);
	$survey->getResponse($id);
	//get reports
	$survey->getReports(<FILTER>,<PAGE>);
	$survey->getReport($id);
	//get statistics
	$survey->getStatistics();
	$survey->getStatisticsByID($question_id);
	//get campaigns
	$survey->getCampaigns();
	$survey->getCampaign($id);
	//get email messages
	$survey->getCampaign($id)->getEmailMessages();
	$survey->getCampaign($id)->getEmailMessage($email_id);

问题

要访问调查中的问题，您需要 \SurveyGizmo\Resources\Survey 对象的实例。

获取所有调查问题

$questions = $survey->getQuestions();

获取和更新调查问题

$question = $survey->getQuestion(<QUESTION question_id>);
$question->title->English = "LIBRARY TEST";
$ret = $question->save();

响应

要访问调查的响应，您需要 \SurveyGizmo\Resources\Survey 对象的实例。请参阅筛选和分页。

获取所有调查响应

$responses = $survey->getResponses(<FILTER>,<OPTIONS>);

获取单个响应

$responses = $survey->getResponse(<RESPONSE_ID);

更新响应

$response->survey_data[$question_id]['answer'] = 'YES';
$ret = $response->save();

筛选和分页对象

所有获取方法都接受可选的 $filter 和 $options 参数。

筛选

$filter = new \SurveyGizmo\Helpers\Filter();
$filter_item = new \SurveyGizmo\Helpers\FilterItem();
$filter_item->setField('title');
$filter_item->setOperator('=');
$filter_item->setCondition('TEST from API');
$filter->addFilterItem($filter_item);
$surveys = \SurveyGizmo\Resources\Survey::fetch($filter);

分页集合

有时您需要翻页浏览对象集合。为了适应这一点，您可以在任何获取方法中使用可选的 $options 参数；

$options = array( 'page' => 3, 'limit' => 100 );
$surveys = \SurveyGizmo\Resources\Survey::fetch($filter,$options);

错误消息与响应

在出现错误的情况下，我们将返回以下响应和状态码

Method not implemented (404)
Method not supported (405)
Not Authorized (401)

简单的API请求

要执行不通过特定资源类的API调用，请使用 \SurveyGizmo\ApiRequest::call。

$response = \SurveyGizmo\ApiRequest::call('contactlist', null, null, null);

测试

单元测试包含在 /Tests 目录下。它们可以通过在 Tests 文件夹内调用 PHPUnit 来运行

$ phpunit

贡献者

该库由 SurveyGizmo 开发团队开发和维护。

许可证

本项目根据 MIT 许可证条款授权。

surveygizmo / surveygizmo-api

维护者

详细信息