README

针对访问MDirector API服务的OAuth客户端库，使用PHP编写。

此包为PHP League的OAuth 2.0 Client提供了MDirector OAuth 2.0支持。

目前，仅提供MDirector电子邮件营销和事务应用程序的OAuth2实现。该包由两个oauth2-client提供者（用于电子邮件营销和事务服务）及其包装器组成，以隐藏所需的OAuth2协商的负担。

作为消费者，您可以选择只使用提供者或客户端包装器，具体取决于您的需求。

还有一个命令行脚本来帮助您从shell中进行测试。

要求

支持以下版本的PHP。

• PHP 5.6
• PHP 7.0
• PHP 7.1
• PHP 7.2

安装

composer require antevenio/oauth2-mdirector 

使用

如前所述，您可以选择只使用提供者或其包装器。以下您可以找到每个情况的示例

1. MDirector Oauth2-client提供者（电子邮件营销应用）

您可以在oauth2-client提供者下找到OAuth2/Client/Provider，对于通用使用说明，请参阅oauth2-client github项目中的通用使用。

MDirector电子邮件营销提供者目前仅提供名为 webapp 的通用clientId的 Resource Owner Password Credentials Grant。以下是一个获取有效accessToken的示例

$provider = new \MDOAuth\OAuth2\Client\Provider\MDirector();

try {
    // Try to get an access token using the resource owner password credentials grant.
    $accessToken = $provider->getAccessToken('password', [
        'username' => '{yourCompanyId}',
        'password' => '{yourApiSecret}'
    ]);
} catch (\League\OAuth2\Client\Provider\Exception\IdentityProviderException $e) {
    // Failed to get the access token
    exit($e->getMessage());
}

当构建对mdirector API的请求时，请注意我们的API期望参数在GET请求的查询字符串中，或在任何其他方法的请求体中为application/x-www-form-urlencoded

例如：POST，PUT，DELETE等。

2. 事务Oauth2-client提供者（事务应用）

您可以在oauth2-client提供者下找到OAuth2/Client/Provider，对于通用使用说明，请参阅oauth2-client github项目中的通用使用。

事务提供者目前仅提供名为 webapp 的通用clientId的 Resource Owner Password Credentials Grant。以下是一个获取有效accessToken的示例

$provider = new \MDOAuth\OAuth2\Client\Provider\Transactional();

try {
    // Try to get an access token using the resource owner password credentials grant.
    $accessToken = $provider->getAccessToken('password', [
        'username' => '{yourCompanyId}',
        'password' => '{yourApiSecret}'
    ]);
} catch (\League\OAuth2\Client\Provider\Exception\IdentityProviderException $e) {
    // Failed to get the access token
    exit($e->getMessage());
}

当构建对事务API的请求时，请注意我们的API期望参数在GET请求的查询字符串中，或在任何其他方法的请求体中为application/json encoded

例如：POST，PUT，DELETE等。

以下内容

Content-Type: application/json

和

Accept: application/json

在每个请求中都是必需的。

3. 包装客户端

包装客户端提供了一种简化的调用API的方式。它们负责获取令牌并在需要时刷新它们。您只需将参数作为关联数组设置，包装器知道如何根据指定的方法传递它们。您还可以指定一个自定义的用户代理，用于请求头（默认为"oauth2-mdirector client"）

使用示例

$companyId = 'yourCompanyId';
$secret = 'yourApiSecret';

$client = (new \MDOAuth\OAuth2\Wrapper\MDirector\Factory())->create($companyId, $secret);
$response = $client->setUri('https://api.mdirector.com/api_contact')
    ->setMethod('get')
    ->setParameters([
        'email' => 'myemail@mydomain.org'    
    ])
    ->setUserAgent('MyOwnUserAgent 1.0')
    ->request();

echo $response->getBody()->getContents();

3. Shell脚本

该库还提供了一个console客户端，您可以从shell调用mdirector API。为此，请运行

$ ./bin/mdirector-oauth-client oauth2:mdirector --help    

该命令将显示一些关于其使用和参数的简单说明。

4. 其他

如果您计划使用其他客户端实现，或者必须使用除PHP以外的语言调用API，这里将提供您需要了解的一些基本信息。

您将使用"webapp"作为固定的clientId，指定密码作为授权类型，您的公司ID作为用户名，您的密钥作为密码来请求访问令牌。

获取此类令牌（或刷新它们）的端点将是

https://app.mdirector.com/oauth2

您将在请求中将令牌携带在Bearer标题中。（https://oauth.ac.cn/2/bearer-tokens/）