dropbox访问_使用PHP访问Dropbox

dropbox访问

In this article we’ll explore the Dropbox PHP API by building a simple client for accessing files in a Dropbox account. The client will perform some basic operations, such as authentication, listing files, and uploading and downloading files.

在本文中，我们将通过构建一个简单的客户端来访问Dropbox帐户中的文件，来探索Dropbox PHP API。客户端将执行一些基本操作，例如身份验证，列出文件以及上载和下载文件。

To keep the article short and readable, I’ll keep the included code to a minimum and instead refer you to the full code available on GitHub. To run the code, you’ll need PHP with cURL support and obviously a Dropbox account.

为了使文章简短易读，我将所包含的代码保持在最低限度，而请您参考GitHub上的完整代码。要运行代码，您将需要具有cURL支持PHP，并且显然需要一个Dropbox帐户。

Your starting point for anything related to development with Dropbox should be the Dropbox Developers Center where you can find the API reference along with its basic concepts and best practices. You can also download the official SDKs, but PHP isn’t listed among the supported languages. There’s a link to a third party PHP SDK on Github.

与Dropbox开发相关的任何事物的起点应该是Dropbox开发人员中心，您可以在其中找到API参考以及其基本概念和最佳实践。您也可以下载官方的SDK，但是在支持的语言中未列出PHP。 Github上有指向第三方PHP SDK的链接。

Our client will be structured more like the official Python client, but I took some ideas and code from the PHP SDK above, especially for the OAuth part. We’ll have a DropboxSession object and a DropboxClient object. The first will take care of the hard part: obtaining and managing access credentials from Dropbox. The client object will then use the session object to perform the API calls and get the data. Underneath the session object there is a DropboxRESTClient object to perform the HTTP calls using cURL.

我们的客户端的结构将更像正式的Python客户端，但是我从上面PHP SDK中获取了一些想法和代码，尤其是对于OAuth部分。我们将有一个DropboxSession对象和一个DropboxClient对象。第一个将解决困难的部分：从Dropbox获取和管理访问凭据。然后，客户端对象将使用会话对象执行API调用并获取数据。在会话对象下面，有一个DropboxRESTClient对象，用于使用cURL执行HTTP调用。

告诉Dropbox有关您的应用的信息 (Tell Dropbox About your App)

First of all we need to register our application with Dropbox in order to obtain a unique API key pair. We’ll need these keys to “introduce” our application and ask for authorization.

首先，我们需要向Dropbox注册我们的应用程序，以获得唯一的API密钥对。我们将需要这些密钥来“引入”我们的应用程序并请求授权。

Log into the Developers Center and follow the “MyApps” link, then select “Create an App”. Dropbox will ask you for a name, description, and access type for your application.

登录开发人员中心，然后点击“ MyApps”链接，然后选择“创建应用程序”。 Dropbox会询问您应用程序的名称，描述和访问类型。

The access type parameter specifies where your application will be able to read and write files. The recommended value is “App folder”, a sandbox directory that will be created inside the user’s home. By selecting “Full Dropbox” the application will see the user’s entire Dropbox.

访问类型参数指定应用程序将在何处读取和写入文件。推荐值为“应用程序文件夹”，这是将在用户家中创建的沙箱目录。通过选择“ Full Dropbox”，应用程序将看到用户的整个Dropbox。

Once your application is created, there will be an options page where you can edit its details and find its access credentials.

创建应用程序后，将出现一个选项页面，您可以在其中编辑其详细信息并找到其访问凭据。

Newly created application are in “Development status”. This allows us to start developing immediately and enables up to five other users to test it. When the app is ready for release, we can apply for productions status and the Dropbox team will review it to make sure that it conforms to their terms and conditions and branding guidelines.

新创建的应用程序处于“开发状态”。这使我们可以立即开始开发，并允许多达五个其他用户对其进行测试。当应用准备好发布时，我们可以申请生产状态，Dropbox团队将对其进行审核，以确保其符合其条款和条件以及品牌准则。

编码应用 (Coding the Application)

I placed my code in a subdirectory of my local Apache set-up so that it’s reachable at the URL http://localhost/mydropbox. The directory structure is:

我将代码放在本地Apache设置的子目录中，以便可以通过URL http://localhost/mydropbox 。目录结构为：

The bootstrap.php file performs the application’s start-up and will be included in each of the front-end files, so let’s start by discussing that.

bootstrap.php文件执行应用程序的启动，并将包含在每个前端文件中，因此让我们从讨论开始。

I initialize a global $config variable as an empty array and then specify some configuration values. The first three are Dropbox-related: the access key, secret key, and access type from your app’s details page. I then define some other useful settings: the base root path of the application, the path to save some data, and the path of a PHP file that will contain the access token for the application.

我将全局$config变量初始化为一个空数组，然后指定一些配置值。前三个与Dropbox相关：访问密钥，秘密密钥和应用程序详细信息页面中的访问类型。然后，我定义一些其他有用的设置：应用程序的基本根路径，保存一些数据的路径以及将包含应用程序访问令牌PHP文件的路径。

This access token file file doesn’t exist in the beginning; it’s created by the authorize.php page and is filled with the credentials provided by Dropbox. It will be a standard PHP file, and if exists will be included later by this script. The contents of the token file will be similar to:

此访问令牌文件文件开头不存在；它是由authorize.php页面创建的，并填充了Dropbox提供的凭据。这将是一个标准PHP文件，并且如果以后将包含在此脚本中。令牌文件的内容将类似于：

<?php
$access_token = array (
"oauth_token_secret" => "abcdefghilmnopqr",
"oauth_token" => "stuvwxyzabcdefgh",
"uid" => "1234567"
);

oauth_token and oauth_token_secret are the access credentials, and uid is the unique ID of the user.

oauth_token和oauth_token_secret是访问凭据，而uid是用户的唯一ID。

In the next section of the bootstrap file I set PHP error behavior and perform some requirements check; in order to run the application the data directory must exists and be writable and the auth.php file must be writable if it exists. This ensures the application can do its job freely.

在引导文件的下一部分中，我将设置PHP错误行为并执行一些需求检查。为了运行该应用程序，数据目录必须存在并且可写，而auth.php文件必须存在(如果存在)。这样可以确保应用程序可以自由地完成其工作。

Finally, I include our libraries, initialize the PHP session, set an empty $access_token (which will be filled later), and, if it exists, include the auth.php file.

最后，我包括我们的库，初始化PHP会话，设置一个空的$access_token (稍后将填充)，并且如果存在，则包括auth.php文件。

Each frontend script will run inside a main try/catch block. Before digging into the library code we first need to understand the flow, so I’ll start with the authorization cycle.

每个前端脚本将在主try / catch块中运行。在深入研究库代码之前，我们首先需要了解流程，因此我将从授权周期开始。

授权书 (Authorization)

The first time our application is run, the following condition in the index.php file will be true:

第一次运行我们的应用程序时， index.php文件中的以下条件将为true：

<?php
if (!isset($access_token)) {
header("Location: authorize.php");
exit;
}

The access token is empty so I’m redirecting the user to the authorize.php page that will manage the authorization process.

访问令牌为空，因此我将用户重定向到将管理授权过程的authorize.php页面。

After the bootstrap phase, I make another check for an existing token. This ensures that this script is run only if we don’t have a token. In order to avoid an infinite redirect loop, the auth.php file is deleted by the main catch block of a script if the error code returned is 401 (invalid token).

引导阶段结束后，我再次检查现有令牌。这样可以确保仅当我们没有令牌时才运行此脚本。为了避免无限重定向循环，如果返回的错误代码为401(无效令牌)，则脚本的主catch块将auth.php文件删除。

The first thing I do in every script is create a new DropboxSession object with our API keys. When we call the script directly, the first condition will be false and the else block is executed. The session object connects to Dropbox and asks for a temporary token. The token is then parsed into an array and stored into the $_SESSION variable for the next phase.

在每个脚本中，我要做的第一件事是使用我们的API密钥创建一个新的DropboxSession对象。当我们直接调用脚本时，第一个条件将为false，然后执行else块。会话对象连接到Dropbox并要求一个临时令牌。然后将令牌解析为数组，并存储到$_SESSION变量中以用于下一阶段。

We build the authorization URL using this token. The user should be redirected or prompted to visit the URL where he will decides whether to allow or deny access to his data.

我们使用此令牌构建授权URL。应该重定向用户或提示用户访问URL，他将在该URL上决定是允许还是拒绝对其数据的访问。

The authorization URL can contain the return URL as an optional parameter. I just pass the current script’s URL, so if the user authorizes the application he’s redirected back to our script, this time with the oauth_token and uid values passed by query string. The first condition now evaluates true, so we can go on and request a permanent access token.

授权URL可以包含返回URL作为可选参数。我只是传递当前脚本的URL，因此，如果用户授权将他重定向到我们的脚本，则这次使用通过查询字符串传递的oauth_token和uid值。现在第一个条件的评估结果为true，因此我们可以继续请求永久访问令牌。

The $token array for this request is built with this new oauth_token and the previous oauth_token_secret, this is then passed to the obtainAccessToken() method. In case of success we have our permanent (until revoked) access token. This must be stored somewhere; the obvious choice is a database, but for this example we’ll export it as valid PHP code using the native var_export() function and write it to our auth.php file. Then the user is redirected to the index page which is the simplest script.

此请求的$token数组是使用此新的oauth_token和以前的oauth_token_secret构建的，然后将其传递给obtainAccessToken()方法。如果成功，我们将拥有永久的(直到撤销)访问令牌。必须将其存储在某个地方。显而易见的选择是数据库，但是在本示例中，我们将使用本地var_export()函数将其导出为有效PHP代码，并将其写入auth.php文件。然后，将用户重定向到最简单的脚本的索引页。

At the beginning of our try/catch block a new DropboxSession object is created, this time with the permanent $access_token as fourth argument. This object is used to create the DropboxClient object. These two steps are common for all the other scripts.

在我们的try / catch块的开头，创建了一个新的DropboxSession对象，这次使用永久性$access_token作为第四个参数。该对象用于创建DropboxClient对象。这两个步骤对于所有其他脚本都是通用的。

The public methods of the client are mapped to the corresponding Dropbox API calls. I’m calling the accountInfo() method that returns an array containing the user’s details: unique id, name, email, quota info and referral link (refer to the official documentation for more details).

客户端的公共方法映射到相应的Dropbox API调用。我正在调用accountInfo()方法，该方法返回一个包含用户详细信息的数组：唯一ID，名称，电子邮件，配额信息和引荐链接(有关更多详细信息，请参阅官方文档)。

幕后：REST和会话对象 (Behind the Scenes: the REST and Session Objects)

Now that we have an overview of the surface flow, let’s see what happens under the hood, our Dropbox library is contained in the lib/dropbox directory and consists of three classes.

现在，我们已经对表面流进行了概述，让我们来看看幕后的情况，我们的Dropbox库包含在lib/dropbox目录中，并且由三个类组成。

REST对象 (The REST Object)

The lowest level class of our library is the REST client (see lib/dropbox/rest.php). This class is a simple wrapper for cURL. It performs the HTTP calls and return the output in raw or encoded format, or throws an exception in case of an error.

我们的库中最底层的类是REST客户端(请参阅lib/dropbox/rest.php )。此类是cURL的简单包装。它执行HTTP调用并以原始或编码格式返回输出，或者在出现错误的情况下引发异常。

The constructor checks if cURL is installed on the system, or throws an exception. Then it tries to initialize the internal $curl handler with the $curlDefaults setting. The handler is unset inside the destructor.

构造函数检查cURL是否已安装在系统上，或引发异常。然后，它尝试使用$curlDefaults设置初始化内部$curl处理程序。处理程序未在析构函数内设置。

The error(), errno(), and close() methods are self-explanatory. Then, we have a series of utility methods, get(), post(), and put(), all simple wrappers for the main request() method that does the real work.

error() ， errno()和close()方法是不言自明的。然后，我们有一系列实用程序方法get() ， post()和put() ，它们是完成实际工作的main request()方法的所有简单包装器。

First we set the URL to fetch, then the HTTP method and the required parameters, additional headers and POST fields (if any). The parameters for the GET and PUT methods are passed along the URL by the caller method.

首先，我们将URL设置为fetch，然后设置HTTP方法和所需的参数，其他标头和POST字段(如果有)。 GET和PUT方法的参数由调用方方法沿URL传递。

Before making the call, we need to tell cURL to retrieve the full content including HTTP headers (set option CURLOPT_HEADER) because some API methods (ex file_get()) put their information in the headers.

在进行调用之前，我们需要告诉cURL检索包括HTTP标头(设置选项CURLOPT_HEADER )在内的完整内容，因为某些API方法(例如file_get() )将其信息放入标头中。

The cURL request is executed with curl_exec() storing the result into $response and the $info variable is filled by curl_info() with the details about the last execution. If the method is PUT we’ll also have to close the input file handle.

使用curl_exec()执行cURL请求，将结果存储到$response ，并且$info变量由curl_info()填充有关上一次执行的详细信息。如果方法是PUT，我们还必须关闭输入文件句柄。

With the $response content and the $info values we parse the result and separate the HTTP headers from the body. By default, the body is returned as JSON-decoded unless the $raw argument is set true.

使用$response内容和$info值，我们分析结果并将HTTP标头与正文分开。默认情况下，除非$raw参数设置为true，否则主体将以JSON解码的形式返回。

Before going on, there’s an error check. The Dropbox API uses HTTP error codes for error notifications. If the status code is greater than 400 then something went wrong and an error message is stored in the body content. I extract this message and throw an exception. If there are no errors the HTTP headers are parsed and the result is returned as array containing the status code, the headers, and the body.

在继续之前，有一个错误检查。 Dropbox API使用HTTP错误代码进行错误通知。如果状态代码大于400，则出了点问题，并且错误消息存储在主体内容中。我提取此消息并引发异常。如果没有错误，则解析HTTP标头，并将结果作为包含状态码，标头和正文的数组返回。

会话对象 (The Session Object)

The DropboxSession object extends the basic REST client to fill our needs:

DropboxSession对象扩展了基本的REST客户端，以满足我们的需求：

perform the initial authentication/authorization flow,执行初始身份验证/授权流程，
include the obtained authentication data in each subsequent REST request.将获得的身份验证数据包括在每个后续的REST请求中。

The constructor simply initiazlizes the internal variables. Another simple method is buildAuthorizeURL() which builds the authorization URL from the temporary token. The most important methods of the class are:

构造函数只是简单地初始化内部变量。另一个简单的方法是buildAuthorizeURL() ，它从临时令牌构建授权URL。该类最重要的方法是：

obtainRequestToken() – request a temporary OAuth access token.

obtainRequestToken() –请求一个临时的OAuth访问令牌。
obtainAccessToken() – request the permanent OAuth access token for the application.

obtainAccessToken() –为应用程序请求永久的OAuth访问令牌。
fetch() – perform a REST call including all the necessary authentication and signature parameters.

fetch() –执行REST调用，包括所有必要的身份验证和签名参数。

These three methods have a similar flow. First they build the basic destination URL and fill the $params associative array with the required oauth_* keys/values to send. Every API call must provide a timestamp and a unique random-generated hash, the $nonce parameter.

这三种方法具有相似的流程。首先，他们构建基本的目标URL，并用要发送的必需的oauth_*键/值填充$params关联数组。每个API调用都必须提供时间戳记和唯一的随机生成的哈希，即$nonce参数。

Then the signature is generated using the HTTP method name, the URL, and the parameters. It’s then queued to the $params array using the oauth_signature key. The URL is fetched with the given HTTP method and the body part of the response is returned. For the GET and PUT methods, the query string is generated and appended to the URL using the native http_build_query() function.

然后，使用HTTP方法名称，URL和参数生成签名。然后使用oauth_signature键将其排队到$params数组中。使用给定的HTTP方法获取URL，并返回响应的正文部分。对于GET和PUT方法，将使用本机http_build_query()函数生成查询字符串并将其附加到URL。

The obtainRequestToken() and obtainAccessToken() are nearly identical: the first doesn’t use a token and is called with a GET HTTP method. The second is called with a POST HTTP method and must include the token obtained with the previous call. This token is then used as part of the signature key for all the following API calls.

obtainRequestToken()和obtainAccessToken()几乎相同：第一个不使用令牌，而是使用GET HTTP方法调用。第二个是使用POST HTTP方法调用的，并且必须包含在上一个调用中获得的令牌。然后，此令牌将用作以下所有API调用的签名密钥的一部分。

The fetch() method performs some additional tasks. First it takes an array called $args with any additional arguments required by the specific API, for example the path of the resource to list or the file to upload/download. These parameters are merged with the $params array before the signature is generated. The only exception is the input file argument, used by the PUT method to upload a file, which is extracted and kept for later. A switch statement is used to tell the right HTTP method to call.

fetch()方法执行一些其他任务。首先，它需要一个名为$args的数组，其中包含特定API所需的任何其他参数，例如，要列出的资源的路径或要上传/下载的文件。在生成签名之前，将这些参数与$params数组合并。唯一的例外是输入文件参数，PUT方法使用该参数上传文件，然后将其提取并保留以供以后使用。 switch语句用于告诉正确的HTTP方法进行调用。

The DropboxSession class has also two utility methods, encodeParams() and getSignature(), called by the main methods above. encodeParams() prepares the request’s parameters to be signed, while getSignature() generates an OAuth request signature for the given API call.

DropboxSession类还有两个实用程序方法， encodeParams()和getSignature() ，由上面的主要方法调用。 encodeParams()准备要签名的请求参数，而getSignature()为给定的API调用生成OAuth请求签名。

最终的DropboxClient对象 (The Final DropboxClient Object)

The DropboxClient object is our high-level interface with Dropbox. It exposes the public API methods, uses the mid-level DropboxSession object to perform the API calls, and returns a processed output to the calling script. For this article I’ve implemented a limited suite of methods:

DropboxClient对象是我们与Dropbox的高级接口。它公开了公共API方法，使用中级DropboxSession对象执行API调用，并将处理后的输出返回到调用脚本。对于本文，我实现了一组有限的方法：

accountInfo() – fetch the current Dropbox user’s details.

accountInfo() –获取当前Dropbox用户的详细信息。
metadata() – fetch information about a Dropbox object (file or folder) and retrieve a list of the content for folder objects.

metadata() –获取有关Dropbox对象(文件或文件夹)的信息，并检索文件夹对象的内容列表。
getFile() – download a file and its metadata and optionally saves it to disk.

getFile() –下载文件及其元数据，还可以选择将其保存到磁盘。
putFile() – upload a local file to a remote Dropbox path.

putFile() –将本地文件上传到远程Dropbox路径。

The session object and the base API URLs are stored as internal variables and initialized by the constructor.

会话对象和基本API URL被存储为内部变量，并由构造函数初始化。

All the methods follow more or less the same approach, so I’ll point out the differences. All methods that deal with a path must prepend the Dropbox root path to each call. The root path depends on the access type of the application, and can be “dropbox” if the application has full access or “sandbox” if the application has limited access. If this value doesn’t match the application’s remote settings, an error is returned.

所有方法或多或少都遵循相同的方法，因此我将指出它们之间的差异。所有处理路径的方法必须在Dropbox根路径之前添加每个调用。根路径取决于应用程序的访问类型，如果应用程序具有完全访问权限，则根路径可以为“ dropbox”，如果应用程序具有有限访问权限，则可以为“沙盒”。如果此值与应用程序的远程设置不匹配，则返回错误。

The common steps performed by each method are:

每种方法执行的常见步骤是：

Check and prepare the argument list.检查并准备参数列表。
Perform the HTTP call.执行HTTP调用。
Parse and return the response.解析并返回响应。

The accountInfo() method is the simplest; it calls its URL with no arguments and returns the associative array with the response.

accountInfo()方法是最简单的。它调用不带参数的URL，并返回带有响应的关联数组。

The metadata() method is used by list.php file to fetch and display the contents of the directory. The only required parameter is the path of the file or directory to check, but it allows us to specify all of the other parameters of the corresponding API call. If the $path argument is a file, the returned array contains its metadata. If it’s a folder, the content key contains the list of its files unless the $list argument is false. We can limit the size of the content with the $fileLimit argument (up to a maximum of 25,000) and we can ask for a specific revision of the file or folder (see the API reference for details).

list.php文件使用metadata()方法来获取和显示目录的内容。唯一需要的参数是要检查的文件或目录的路径，但是它允许我们指定相应API调用的所有其他参数。如果$path参数是文件，则返回的数组包含其元数据。如果它是文件夹，则除非$list参数为false，否则content密钥将包含其文件$list 。我们可以使用$fileLimit参数限制内容的大小(最大25,000)，并且可以要求文件或文件夹的特定版本(有关详细信息，请参阅API参考)。

It’s important to note that the Dropbox API returns a hash value for each call. If we want to list the contents of a folder and provide a $hash parameter to our method, the API checks whether the output has changed since the last call. If not, it returns a status code of 301 (not modified). The Dropbox team recommends caching the results and relying on these values for folder listings to optimize performance.

请务必注意，Dropbox API会为每个调用返回一个哈希值。如果我们要列出文件夹的内容并为我们的方法提供$hash参数，则API会检查自上次调用以来输出是否已更改。如果不是，它将返回状态代码301(未修改)。 Dropbox团队建议将结果缓存并依靠这些值来列出文件夹，以优化性能。

The getFile() method is used to retrieve a file stored in the user’s Dropbox. The entire file content is returned by the call in case of success, and its metadata is stored in the custom HTTP header x-dropbox-metadata as a JSON string. The return value of this method is an associative array that contains the name, mime type, metadata and content. In addition I’ve added an $outFile parameter to save the file directly on disk.

getFile()方法用于检索存储在用户Dropbox中的文件。如果成功，则调用将返回整个文件内容，其元x-dropbox-metadata作为JSON字符串存储在自定义HTTP标头x-dropbox-metadata中。此方法的返回值是一个关联数组，其中包含名称，mime类型，元数据和内容。另外，我添加了一个$outFile参数以将文件直接保存在磁盘上。

The download.php file shows a demo of this method in action. In this example, the downloaded file is saved directly to the application’s data directory and the content part of the response is emptied.

download.php文件演示了此方法的演示。在此示例中，下载的文件直接保存到应用程序的数据目录，并且响应的内容部分为空。

The putFile() method uploads a file from our local storage to the user’s Dropbox using the PUT HTTP method, which is preferred by the Dropbox team instead of POST. This method checks that the local file exists and doesn’t exceed the 150MB API limit before any other common action.

putFile()方法使用PUT HTTP方法将文件从我们的本地存储上传到用户的Dropbox，Dropbox团队更喜欢使用该方法，而不是POST。此方法将在执行任何其他常规操作之前，检查本地文件是否存在并且未超过150MB API限制。

The supported parameters for this method, in addition to the source file path, are the destination folder, an optional alternative name and an overwrite option. If this last option is false and the remote file exists, the uploaded file is renamed with a progressive number (for example, test.txt becomes test (1).txt). The API also allows for an optional parent_rev parameter to manage revisions, but in order to keep things simple I decided to omit it.

除了源文件路径之外，此方法支持的参数还有目标文件夹，可选的备用名称和覆盖选项。如果最后一个选项为false并且远程文件存在，则上载的文件将使用渐进编号重命名(例如， test.txt变为test (1).txt )。该API还允许使用可选的parent_rev参数来管理修订，但是为了简化起见，我决定忽略它。

摘要 (Summary)

This is just a small part of the Dropbox API, but it can be enough as a starting point to develop your own applications. For me, it was also a good occasion to play with OAuth. Feel free to refine and expand the code that accompanies this article to suit your needs and, as always: happy coding!

这只是Dropbox API的一小部分，但足以作为开发您自己的应用程序的起点。对我来说，这也是玩OAuth的好时机。随意改进和扩展本文随附的代码，以适应您的需求，并且一如既往：祝您编程愉快！

Image via Fotolia

图片来自Fotolia

翻译自: https://www.sitepoint.com/access-dropbox-using-php/

dropbox访问