この記事では、Dropbox API 用のシンプルなクライアントを構築して、Dropbox アカウント内のファイルにアクセスする方法を検討します。クライアントは、認証、ファイルの一覧表示、ファイルのアップロードとダウンロードなど、いくつかの基本的な操作を実行します。
記事を短く読みやすくするために、コードは最小限にとどめ、代わりに PHPMaster の GitHub で入手可能な完全なコードを参照してください。コードを実行するには、当然ながら、curl をサポートする PHP Dropbox アカウントが必要です。
Dropbox を使用した開発に関連するものは、Dropbox デベロッパー センターから始める必要があります。Dropbox デベロッパー センターでは、基本概念とベスト プラクティスに関する API リファレンスを見つけることができます。公式 SDK をダウンロードすることもできますが、PHP はサポートされている言語にリストされていません。 GitHub にはサードパーティの PHP SDK へのリンクもあります。
私たちのクライアントは、公式の Python クライアントに似た構造になりますが、特に OAuth の部分で、上記の PHP SDK のアイデアとコードがいくつかあることに気付きました。 DropboxSession オブジェクトと DropboxClient オブジェクトがあります。まず最も難しい部分、つまり Dropbox からのアクセス資格情報の取得と管理に取り組んでください。クライアント オブジェクト。API 呼び出しを実行してデータを取得するために使用されます。以下のセッション オブジェクトは、cURL を使用して HTTP 呼び出しを実行するために使用される DropboxRESTClient オブジェクトです。
あなたのアプリについて Dropbox に伝えてください
まず、アプリケーションを登録して、Dropbox に一意の API キー ペアを取得する必要があります。アプリケーションを「インポート」するにはこれらのキーが必要であり、認証が必要です。
開発センターにログインし、「MyApps」リンクをクリックして「アプリの作成」を選択します。 Dropbox はアプリケーションの名前、説明、アクセス タイプを尋ねます。
アクセス タイプ パラメーターは、アプリケーションがファイルの読み取りと書き込みができることを指定します。推奨される値は、サンドボックスが作成されるユーザーのホーム内の「アプリケーション フォルダー」ディレクトリです。 「フル Dropbox」アプリを選択すると、ユーザーの Dropbox 全体にアクセスします。
アプリケーションが作成されると、オプション ページが表示され、詳細を編集したり、アクセス資格情報を検索したりできます。
新しく作成されたアプリケーションは「開発状態」になります。これにより、すぐに開発を開始でき、最大 5 人の他のユーザーがテストできるようになります。アプリのリリース準備が整ったら、運用ステータスを申請し、Dropbox チームがアプリを審査して利用規約とブランド ガイドラインに準拠していることを確認します。
コーディングアプリ
コードをローカルの Apache セットアップのサブディレクトリに置き、URL http://localhost/mydropbox でアクセスできるようにしました。ディレクトリ構造は次のとおりです:
アプリケーションの起動を実行する bootstrap.php ファイルはすべてのフロントエンド ファイルに含まれるので、それから始めましょう。
グローバル構成を空の配列変数として初期化し、いくつかの構成値を指定します。アプリの詳細ページからの上位 3 つの Dropbox 関連のアクセス キー、キー、アクセス タイプ。次に、その他の便利な設定を定義します。データの一部が保存されるアプリケーションのベース ルートへのパスと、アプリケーションのアクセス トークンを含む PHP ファイルへのパスです。
このアクセス トークン ファイルはファイルの先頭には存在しません。このファイルは authorize.php ページによって作成され、Dropbox によって提供される認証情報が入力されます。これは標準の PHP ファイルであり、存在する場合は後でこのスクリプトに組み込まれます。トークン ファイルの内容は次のようになります:
$access_token = 配列 (
"oauth_token_secret" => "abcdefghilmnopqr",
"oauth_token" => "stuvwxyzabcdefgh",
"uid" => "1234567"
);
oauth_token および oauth_token_secret アクセス資格情報。UID はユーザーの一意の ID です。
ブートストラップ ファイルの次のセクションで PHP のエラー動作を設定し、いくつかの要件チェックを実行します。アプリケーションを実行するには、データ ディレクトリが存在して書き込み可能である必要があり、auth.php ファイルが存在する場合は書き込み可能である必要があります。これにより、アプリケーションは自由に作業を実行できるようになります。
最後に、ライブラリをインクルードし、PHP セッションを初期化し、空の $access_token (後で入力します) を設定し、存在する場合は auth.php ファイルをインクルードします。
各フロントエンド スクリプトは、メインの try/catch ブロック内で実行されます。ライブラリ コードを詳しく説明する前に、まずトラフィックを理解する必要があるため、承認サイクルから始めます。
認可
アプリケーションを初めて実行するとき、index.php ファイルは次の条件下で true になります:
1
2 if (!isset($access_token)) {
3 header("場所: authorize.php");
4 出口;
5}
アクセス トークンは空であるため、ユーザーを authorize.php ページにリダイレクトします。このページが承認プロセスを管理します。
ブートストラップ フェーズの後、既存のトークンを再度チェックします。これにより、このスクリプトはトークンがない場合にのみ実行されるようになります。無限リダイレクト ループを回避するために、返されたエラー コードが 401 (無効なトークン) だった場合、auth.php ファイルがメインの catch スクリプト ブロックから削除されました。
すべてのスクリプトで最初に行うことは、API キーを使用して新しい DropboxSession オブジェクトを作成することです。スクリプトを直接呼び出すと、最初の条件は false になり、他のブロックが実行されます。セッション オブジェクトは Dropbox に接続し、一時トークンを必要とします。次に、トークンは配列に解析され、次のステージのために変数 $_SESSION に保存されます。
このトークンの使用を許可された URL を構築します。ユーザーは、データへのアクセスを許可するか拒否するかを決定する URL にリダイレクトされるか、アクセスするよう求められます。
認可 URL には、オプションのパラメータである戻り URL を含めることができます。現在のスクリプトの URL を渡しているだけなので、ユーザーが承認すると、クエリ文字列で渡された時刻の oauth_token と UID 値を使用するスクリプトのアプリにリダイレクトされます。最初の条件が true と評価されるようになったので、次に永続的なアクセス トークンを要求できます。
この要求された $token の配列は、以前の oauth_token_secret を使用して構築されたこの新しい oauth_token であり、その後、obtainAccessToken() メソッドに渡されます。成功すると、永続的な (取り消されるまで) アクセス トークンが得られます。これはどこかに保存する必要があり、当然の選択はデータベースですが、この例では、ネイティブの var_export() 関数を使用して有効な PHP コードとしてエクスポートし、auth.php ファイルに書き込みます。次に、ユーザーをインデックス ページにリダイレクトします。これは最も単純なスクリプトです。
try/catch ブロックの先頭で、新しい DropboxSession オブジェクトが、今回は $access_token を 4 番目の引数として永続的に作成されます。このオブジェクトは DropboxClient オブジェクトの作成に使用されます。これら 2 つの手順は、他のすべてのスクリプトに共通です。
クライアントのパブリック メソッドは、対応する Dropbox API 呼び出しにマップされます。 AccountInfo() メソッドを呼び出しています。このメソッドは、ユーザーの詳細 (一意の ID、名前、電子メール、クォータ情報、紹介リンク) を含む配列を返します (詳細については、公式ドキュメントを参照してください)。
舞台裏: REST とセッション オブジェクト
Surface Flow の概要がわかり、内部で何が起こっているかを確認できるようになりました。Dropbox ライブラリは lib/Dropbox ディレクトリに含まれており、3 つのカテゴリで構成されています。
静止物体
最下位クラスのライブラリは REST クライアントです (lib/dropbox/rest.php を参照)。このクラスは、curl の単純なラッパーです。 HTTP 呼び出しを実行し、生の形式またはエンコードされた形式で出力を返すか、エラーの場合は例外をスローします。
コンストラクターは、cURL がシステムにインストールされているかどうかを確認するか、例外をスローします。次に、$curlDefaults を設定して内部 Curl ハンドラーを初期化しようとします。デストラクターにはハンドラーが設定されていません。
() error と errno()、() メソッドは一目瞭然です。次に、一連のユーティリティ メソッドである get()、post()、および put() メソッドを用意します。これらは、() メソッドが実際に動作するためのすべての主要な要件を囲む単純なラッパーです。
まず、HTTP メソッドと必要なパラメータ、追加のヘッダー、および POST (存在する場合) を取得するための URL を設定します。パラメーターは、GET メソッドと PUT メソッドの URL 呼び出し元メソッドに沿って渡されます。
一部の API メソッド (もちろん、file_get()) は情報をヘッダーに入れるため、呼び出しを行う前に、HTTP ヘッダー (オプション CURLOPT_HEADER を設定) を含むコンテンツ全体を取得するようにcurlに指示する必要があります。
実行中のcurlリクエストはcurl_exec()の結果をレスポンスに保存し、メタ情報変数にはcurl_info()によって関連する実行の詳細が設定されます。提案されたアプローチの場合、入力ファイル ハンドルも閉じる必要があります。
私たちが解析するメタ応答コンテンツとメタ情報は結果であり、HTTP ヘッダーを本文から分離します。デフォルトでは、$raw パラメーターが true に設定されていない限り、本文は JSON デコードされたものとして返されます。
その前に何が起こっているかというと、バグチェックがあります。 Dropbox の API は、エラー通知に HTTP エラー コードを使用します。ステータス コードが 400 より大きい場合は、エラーが発生しており、エラー メッセージが本文に保存されます。このメッセージを抽出して例外をスローします。エラーがない場合、HTTP ヘッダーの解析結果はステータス コード、ヘッダー、本文を含む配列を返します。
セッションオブジェクト
ニーズを満たすために DropboxSession オブジェクトによって拡張された基本的な REST クライアント:
初期認証/認可トラフィックを実行します。
検証データを取得するために、後続のすべての REST リクエストに含まれます。
内部変数を初期化する単純な構造を構築します。もう 1 つの簡単な方法は、buildAuthorizeURL() を使用して一時的なトークン認証 URL を構築することです。クラスの最も重要なメソッドは次のとおりです:
getRequestToken() - 一時的な OAuth アクセス トークンを要求します。
getAccessToken() - 永続的な OAuth を必要とするアプリケーションのアクセス トークン。
get() - 必要なすべての認証および署名パラメータを含む残りの呼び出しを実行します。
これら 3 つの方法も同様のフローを持ちます。まず、ベース ターゲット URL を設定し、$params に値を入力し、必要な oauth_* キー/値を含む関連配列を送信します。各 API 呼び出しでは、タイムスタンプと、ランダムに生成された一意のハッシュである $nonce パラメーターを指定する必要があります。
次に、HTTP メソッドの名前、URL、パラメーターを使用して署名を生成します。次に、oauth_signature キーを使用して $params 配列をキューに入れます。 URL は指定された HTTP メソッドで取得され、応答の本文の一部として返されます。 GET メソッドと PUT メソッドの場合、生成されたクエリ文字列は、ローカルの http_build_query() 関数を使用して URL に追加されます。
getRequestToken と getAccessToken() はほぼ同じです。一方はトークンを使用せず、GET HTTP メソッドを呼び出します。 POST と呼ばれる 2 番目の HTTP メソッドには、前の呼び出しで取得したトークンが含まれている必要があります。このトークンは、後続のすべての API 呼び出しの署名キーの一部として使用されます。
get() メソッドはいくつかの追加タスクを実行します。まず、ファイルをアップロード/ダウンロードするためのリソースやパスのリストなど、特定の API に必要な追加パラメータを含む $args という名前の配列が必要です。これらのパラメーターは、署名を生成する前に $params 配列と結合されます。唯一の例外は、PUT メソッドを使用してファイルをアップロードし、ファイルにパラメータを入力し、後で使用できるように抽出して保存することです。 switch ステートメントは、呼び出す正しい HTTP メソッドを指示するために使用されます。
DropboxSession クラスには、encodeParams() と getSignature() という 2 つのユーティリティ メソッドがあります。上記のメイン メソッド呼び出しでは、encodeParams() が署名用のリクエスト パラメーターを準備し、getSignature() が特定の API 呼び出しで OAuth に必要な署名を生成します。
最後に DropboxClient オブジェクト
DropboxClient オブジェクトは、Dropbox への高レベルのインターフェイスです。これは、中間レベルの DropboxSession オブジェクトを使用して API 呼び出しを実行し、呼び出しの出力を処理するスクリプトを返すパブリック API メソッドを公開します。この投稿では、限られたメソッドのセットを実装しました:
AccountInfo() – 現在の Dropbox ユーザーの詳細を取得します。
metadata() - Dropbox オブジェクト (ファイルまたはフォルダー) に関する情報を取得し、フォルダー オブジェクトのコンテンツのリストを取得します。
GETFILE() - ファイルとそのメタデータをダウンロードし、オプションでディスクに保存します。
PUTFILE() - ローカル ファイルをリモート Dropbox にアップロードするパス。
セッション オブジェクトとベース API への URL は内部変数として保存され、コンストラクターで初期化されます。
すべての方法は多かれ少なかれ同じアプローチに従っているため、違いを指摘します。すべてのパス処理メソッドでは、各呼び出しの Dropbox ルート パスを考慮する必要があります。ルート パスはアプリケーションのアクセス タイプによって異なり、アプリケーションに完全なアクセス権がある場合は「ドロップボックス」、アプリケーションが制限されたアクセス権を持つ場合は「サンドボックス」になります。この値がアプリケーションのリモート設定と一致しない場合、エラーが返されます。
各方法で実行される一般的な手順は次のとおりです:
パラメータリストを確認して準備します。
HTTP 呼び出しを実行します。
解析して応答を返します。
AccountInfo() メソッドは最も単純で、パラメータなしで URL を呼び出し、応答の連想配列を返します。
list.php の filemetadata() メソッドを使用して、ディレクトリの内容を取得して表示します。唯一の必須パラメータは、チェックするファイルまたはディレクトリへのパスですが、これにより、対応する API 呼び出しの他のすべてのパラメータを指定できます。 $PATH パラメータがファイルの場合、返される配列にはメタデータが含まれます。フォルダーの場合、ドルリスト引数が false でない限り、コンテンツ アイテムにはそのファイル リストが含まれます。 $fileLimit パラメーターを使用してコンテンツのサイズを制限でき (最大 25000)、特定のファイルまたはフォルダーのリビジョンを要求できます (詳細については API リファレンスを参照)。
Dropbox API は呼び出しごとにハッシュ値を返すことに注意することが重要です。フォルダーの内容をリストし、メソッドへの最後の呼び出し以降に変更されたハッシュ パラメーターを指定すると、API は出力が存在するかどうかを確認します。そうでない場合は、301 ステータス コード (変更できません) が返されます。 Dropbox のチームは、パフォーマンスを最適化するために、結果をキャッシュし、これらのフォルダー リストの値に依存することを推奨しています。
GETFILE() メソッドは、ユーザーの Dropbox に保存されているファイルを取得するために使用されます。 X-Dropbox のメタデータへの呼び出しが成功すると、ファイル コンテンツ全体が JSON 文字列として返され、そのメタデータはカスタム HTTP ヘッダーに保存されます。このメソッドの戻り値は、名前、MIME タイプ、メタデータ、コンテンツを含む連想配列です。さらに、ファイルをディスクに直接保存するために $outfile パラメーターを追加しました。
download.php ファイルには、これがどのように行われるかのデモンストレーションが示されています。この例では、ダウンロードされたファイルはアプリケーションのデータ ディレクトリに直接保存され、応答の一部がクリアされます。
PUTFILE() メソッドは、PUT HTTP メソッドを使用して、ローカル ストレージからユーザーの Dropbox にファイルをアップロードします。これは、Dropbox チームが公開する代わりに推奨している方法です。このメソッドは、他の一般的なアクションの前に、ローカル ファイルが存在し、150MB の API 制限を超えていないことを確認します。
このメソッドでサポートされている引数には、ソース ファイルへのパス、宛先フォルダー、オプションの代替名、およびオーバーライド オプションがあります。この最後のオプションが false で、リモート ファイルが存在する場合、アップロードされたファイルにはプログレッシブ番号が付けられます (例: test(1).txt は test.txt になります)。 API では、オプションのparent_rev パラメータを使用して変更を管理することもできますが、物事をシンプルにするためにこれを無視することにしました。
まとめ
これは Dropbox API のほんの一部ですが、独自のアプリケーションを開発する出発点としては十分です。私にとって、これは OAuth を試す素晴らしい機会でもあります。ニーズに合わせてこの記事を自由に改善および拡張してください。いつものように、コードのコーディングを楽しんでください。
![[Web フロントエンド] Node.js クイック スタート](https://img.php.cn/upload/course/000/000/067/662b5d34ba7c0227.png)
