README

Forrest是Laravel 4的Force.com REST API客户端。它通过OAuth 2.0提供对受限Salesforce信息的访问。REST是SOAP API的轻量级替代品，对移动用户非常有用。

尽管此包是为Laravel构建的，但它已被解耦，因此它可以扩展到任何框架或纯PHP应用程序。

安装

如果您正在升级到1.0版本，请务必重新发布您的配置文件。

可以通过composer安装Forrest。打开您的composer.json文件，并在require键下添加以下内容

"omniphx/forrest": "1.*"

然后从命令行运行composer update以安装包。

如果您正在使用Laravel，请将服务提供者添加到您的app/config/app.php文件中

'Omniphx\Forrest\Providers\Laravel\ForrestServiceProvider'

然后是别名

'Forrest' => 'Omniphx\Forrest\Providers\Laravel\Facades\Forrest'

配置

您需要一个配置文件来添加您的凭据。使用artisan命令发布配置文件

php artisan config:publish omniphx/forrest

您可以在以下位置找到配置文件：app/config/omniphx/forrest/config.php

在设置好连接的应用程序（见下文）之后，请使用consumerKey、consumerSecret、loginURL和callbackURI更新您的配置文件。

入门指南

设置连接应用程序

1. 登录到您的Salesforce组织
2. 在右上角的菜单中点击“设置”
3. 在“构建”下点击创建 > 应用程序
4. 滚动到页面底部，在“连接应用程序”下点击“新建”
5. 为远程应用程序输入以下详细信息
   • 连接应用程序名称
   • API名称
   • 联系邮箱
   • 在API下拉菜单下启用OAuth设置
   • 回调URL
   • 选择访问范围（如果您需要刷新令牌，请在此指定）
6. 点击“保存”

保存后，您现在将获得一个消费者密钥和消费者密钥。将它们添加到您的配置文件中。

设置

Forrest将包含以下路由作为其包的一部分

Web服务器身份验证流程

Route::get('/authenticate', function()
{
    return Forrest::authenticate();
});

Route::get('/callback', function()
{
    Forrest::callback();

    $url = Config::get('forrest::authRedirect');

    return Redirect::to($url);
});

用户名-密码身份验证流程

Route::get('/authenticate', function()
{
    Forrest::authenticate();

    $url = Config::get('forrest::authRedirect');

    return Redirect::to($url);
});

注意：如果您想自定义身份验证过程，可以在您的route.php文件中覆盖这些路由。您可以根据需要命名路由，但回调必须与您的连接应用程序设置和配置文件中配置的相匹配。

自定义登录URL

有时用户需要连接到沙盒或自定义URL。为此，只需将URL作为认证方法的参数传递即可。

Route::get('/authenticate', function()
{
    $loginURL = 'https://test.salesforce.com';

    return Forrest::authenticate($loginURL);
});

用法

查询记录

回调函数将在用户的会话中存储加密的认证令牌，现在可以使用该令牌进行API请求，例如

Forrest::query('SELECT Id FROM Account');

结果

{
    "totalSize": 2,
    "done": true,
    "records": [
        {
            "attributes": {
                "type": "Account",
                "url": "\/services\/data\/v30.0\/sobjects\/Account\/001i000000xxx"
            },
            "Id": "001i000000xxx"
        },
        {
            "attributes": {
                "type": "Account",
                "url": "\/services\/data\/v30.0\/sobjects\/Account\/001i000000xxx"
            },
            "Id": "001i000000xxx"
        }
    ]
}

默认格式是JSON，但它可以更改为XML

创建新记录

可以使用以下格式创建记录。

$body = ['Name' => 'New Account'];
Forrest::sobjects('Account',[
    'method' => 'post',
    'body'   => $body]);

更新记录

使用PUT方法更新记录。

$body = [
    'Name'  => 'Acme'
    'Phone' => '555-555-5555'];

Forrest::sobjects('Account/001i000000xxx',[
    'method' => 'put',
    'body'   => $body]);

Upsert记录

使用PATCH方法更新记录，如果外部ID不存在，它将插入新记录。

$body = [
    'Phone' => '555-555-5555',
    'External_Id__c' => 'XYZ1234'];

Forrest::sobjects('Account',[
    'method' => 'patch',
    'body'   => $body]);

删除记录

使用DELETE方法删除记录。

Forrest::sobjects('Account/001i000000xxx', ['method' => 'delete']);

XML格式

使用format密钥将请求/响应格式更改为XML，或在您的配置文件中将它设置为默认值。

Forrest::describe('Account',['format'=>'xml']);

API请求

除了search和query资源外，所有请求都是通过方法重载动态执行的。可用的资源存储在用户认证时用户的会话中。

首先，通过调用

Session::get('resources');

或

Forrest::resources();

任一方式都将返回以下数组

Array
(
    [sobjects] => /services/data/v30.0/sobjects
    [connect] => /services/data/v30.0/connect
    [query] => /services/data/v30.0/query
    [theme] => /services/data/v30.0/theme
    [queryAll] => /services/data/v30.0/queryAll
    [tooling] => /services/data/v30.0/tooling
    [chatter] => /services/data/v30.0/chatter
    [analytics] => /services/data/v30.0/analytics
    [recent] => /services/data/v30.0/recent
    [process] => /services/data/v30.0/process
    [identity] => https://login.salesforce.com/id/00Di0000000XXXXXX/005i0000000aaaaAAA
    [flexiPage] => /services/data/v30.0/flexiPage
    [search] => /services/data/v30.0/search
    [quickActions] => /services/data/v30.0/quickActions
    [appMenu] => /services/data/v30.0/appMenu
)

接下来，您可以通过指定的键来调用资源。例如

Forrest::theme();

或

Forrest::appMenu();

可以通过将额外的参数传递给第一个参数来扩展资源URL

Forrest::sobjects('Account/describe/approvalLayouts/');

您还可以向请求添加可选参数

Forrest::theme(['format'=>'xml']);

其他API请求

刷新

如果设置了刷新令牌，服务器可以代表用户刷新访问令牌。刷新令牌仅在您使用Web服务器流时提供。

Forrest::refresh();

如果您需要刷新令牌，请确保在您的已连接应用程序中的“访问范围”下指定此信息。您也可以通过添加'scope' => 'full refresh_token'到配置文件中来指定此信息。在配置文件中设置范围访问是可选的，默认范围访问由您的Salesforce组织决定。

撤销

这将撤销授权令牌。会话将继续存储令牌，但它将变为无效。

Forrest::revoke();

版本

返回所有当前支持的版本。包括版本、标签以及每个版本根的链接

Forrest::versions();

资源

返回特定API的可用的资源列表。

Forrest::resources();

身份

返回有关登录用户的信息。

Forrest::identity();

限制

列出有关组织限制的信息。适用于API版本29.0及更高版本。

注意：此调用是试点项目的一部分，并且可能不会在未经Salesforce请求的所有组织中可用。

Forrest::limits();

描述

描述组织中所有可用的全局对象。

Forrest::describe();

查询

返回指定SOQL查询的结果。

Forrest::query('SELECT Id FROM Account');

查询解释

返回Salesforce将如何处理您的查询的详细信息。适用于API版本30.0或更高版本。

Forrest::queryExplain('SELECT Id FROM Account');

查询所有

返回指定SOQL查询的结果，但也将包括已删除的记录。

Forrest::queryAll('SELECT Id FROM Account');

搜索

返回指定的SOSL查询

Forrest::search('Find {foo}');

范围顺序

全局搜索会跟踪用户与之交互的对象，并在用户执行全局搜索时对它们进行排序。此调用将返回此有序对象列表。

Forrest::scopeOrder();

搜索布局

返回查询字符串中对象的搜索结果布局。列表应格式化为字符串，但用逗号分隔。

Forrest::searchLayouts('Account,Contact,Lead');

建议文章

根据搜索查询返回Salesforce知识文章列表。将额外参数传递给第二个参数。适用于API版本30.0或更高版本。

必须启用Salesforce知识才能使用此功能。

Forrest::suggestedArticles('foo', [
    'parameters' => [
        'channel' => 'App',
        'publishStatus' => 'Draft']]);

建议查询

根据搜索文本查询返回建议的搜索列表。与Suggest Articles类似，可以通过使用带有parameters键的第二个参数传递额外的参数。适用于API版本30.0或更高版本。

Forrest::suggestedQueries('app, [
    'parameters' => ['foo' => 'bar']]);

有关API资源的完整列表，请参阅Force.com REST API开发者指南

自定义Apex端点

如果您使用Apex创建自定义API，您可以使用custom()方法来消费它们。

Forrest::custom('/myEndpoint');

可以像这样传递额外的选项和参数

Forrest::custom('/myEndpoint', [
    'method' => 'post',
    'body' => ['foo' => 'bar'],
    'parameters' => ['flim' => 'flam']]);

有关更多信息，请阅读使用Apex REST创建REST API