===== 認証 ===== http://developer.foursquare.com/docs/oauth.html .. The foursquare APIv2 can only be accessed via OAuth 2.0. This is really important to help us track usage of the API by your applications while keeping our users' data safe. It's a standard used by various large API providers, including the Facebook Graph API. Foursquare APIv2 は `OAuth2.0 `_ を通してし か使用できません。これはあなたのアプリケーションがユーザのデータを安全 に保っていることと、我々がAPIの利用状況を追跡することを手助けすることの ために重要なことです。OAuth 2.0はFacebookのGraph APIなどの様々な巨大な APIプロバイダーで使われている標準です。 .. If you had a rough experience trying to use OAuth 1.0, rest assured the new version is radically simpler and more awesome. There are various tutorials floating around, but one we found helpful was this blog post. もし、OAuth 1.0を使った経験があるならば、新しいバージョンはもっと簡単で もっと素晴らしいことが分かるでしょう。周囲にはさまざまなチュートリアル がありますが、そのうちの一つ、 `このblog記事 `_ が参考になるでしょう。 ---------------------------- 1. サインアップ ---------------------------- .. Start by registering your application and obtaining your API credentials. You may want to sign up under a separate account with an extra-secure password to own these credentials. Since each credential is tied to a particular URL, you may want to create a set of development credentials which point to your development server URL, and production credentials which point to your production server URL. For the purposes of OAuth2, your "key" from that registration process is your "id" here, and your secret from registering is your secret here. 始めるにあたり、まず、あなたの `アプリケーションを登録 `_ し、APIのクレデンシャルを取得します。 さらに安全なパスワードを使って、別のアカウントで登録することもできます。 それぞれのクレデンシャルは対応するURLと結びついているため、開発サーバの URLを示す開発用クレデンシャル、製品サーバのURLを示す製品クレデンシャル のセットを作ることも出来ます。OAuth2のために、登録処理によって得られた あなたの"キー"はあなたの"id"であり、登録時のあなたのシークレットはあな たのシークレットとなります。(訳註: 訳不正確) ----------------------------- 2. アクセストークンの取得 ----------------------------- 新しいAPIを使用するには、大きく分けて三つの方法があります。 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Web アプリケーション ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ (PHP, Perl, Ruby, Python, Java, Scala, など) - 認証をしたいユーザを以下に **リダイレクト** :: https://foursquare.com/oauth2/authenticate ?client_id=YOUR_CLIENT_ID &response_type=code &redirect_uri=YOUR_REGISTERED_REDIRECT_URI - もしユーザが了承したら、以下のURLに再びリダイレクト :: https://YOUR_REGISTERED_REDIRECT_URI/?code=CODE - あなたのサーバは以下の **リクエストを生成** :: https://foursquare.com/oauth2/access_token ?client_id=YOUR_CLIENT_ID &client_secret=YOUR_CLIENT_SECRET &grant_type=authorization_code &redirect_uri=YOUR_REGISTERED_REDIRECT_URI &code=CODE - レスポンスはJSONで返ってきます :: { access_token: ACCESS_TOKEN } - あなたのデータベースにこのアクセストークンを **保存** します ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 純粋な AJAX アプリケーション ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ (Javascript) - 認証をしたいユーザを以下に **リダイレクト** :: https://foursquare.com/oauth2/authenticate ?client_id=CLIENT_ID &response_type=token &redirect_uri=YOUR_REGISTERED_REDIRECT_URI - もしユーザが了承したら、以下のURLに再びリダイレクト :: http://YOUR_REGISTERED_REDIRECT_URI/#access_token=ACCESS_TOKEN ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 携帯電話あるいはクライアント側のアプリケーション ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ (Android Java, iOS Objective-C, など) .. if you have a server that works with your application, we strongly prefer you use the server flow above, possibly in an embedded browser. Similar to the Facebook API, you can add display=touch to your authorize or authenticate URLs to get a mobile optimized interface. もし、あなたのアプリケーションと一緒になって動くサーバがある場合、私た ちは上記のサーバの場合を使うことを強く勧めます。これは埋め込みのブラウ ザで動作するかもしれません。Facebook APIと同じように、モバイル用に最適 化されたインタフェースを得るために、あなたの認証や認証用URLに `display=touch` を付け加えても構いません。 ------------------------------------------------------ 3. リクエストの作成 ------------------------------------------------------ .. Once you have an access token. It's easy to use any of the endpoints, but just adding oauth_token=ACCESS_TOKEN to your GET or POST request. For example, from the command line, you can do 一度アクセストークンを得たら、どんな :doc:`エンドポイント ` も使うのは簡単です。oauth_token=ACCESS_TOKEN をGETかPOSTに付け加えるだ けです。例えばコマンドラインから、以下のようにします。 :: curl https://api.foursquare.com/checkin/history?oauth_token=ACCESS_TOKEN いえい!たったこれだけです! ----------------------------------- API v1 からの移行 ----------------------------------- .. If you have users who already registered with OAuth 1.0 for the old foursquare API, don't worry! All you have to do is use the user's secret as the oauth_token in APIv2 and you're good to go. もしもあなたが古いfoursquare APIのために、OAuth 1.0で既に登録している場 合、心配しないでください!ユーザのシークレットをAPIv2のoauth_tokenとし て使うだけです。 .. _auth-useless: ----------------------------------- 無意味なアクセス ----------------------------------- .. Some endpoints (e.g. venue search) allow you to not act as any particular user. We will return unpersonalized data suitable for generic use, and the performance should be slightly better. In these cases, pass your client ID as client_id and your client secret as client_secret. Although the draft 11 of the OAuth2 spec provides a mechanism for consumers to act via token entitled Client Credentials, we do not currently support this. (Venue 検索などの)いくつかのエンドポイントは特定のユーザに対してなにか を行うわけではありません。この場合、私たちは使用個人情報に基づかない全 体のデータを返します。この時の性能は他のエンドポイントへのアクセスより わずかに優れています。これらのエンドポイントの場合、あなたのクライアン トIDを `client_id` として、あなたのクライアントシークレットを `client_secret` として渡します。OAuth2仕様書のdraft 11によれば、 "Client Credentials"という名前のトークンを利用してコンシューマに対する 機構を提供する方法がありますが、私たちは現在この方式をサポートしていま せん。 ----------------------------------- 注意 ----------------------------------- .. OAuth2 can pass secrets in the clear without requiring manual signing of requests. The catch is that all requests must be via HTTPS, and you'll see errors when not using HTTPS. OAuth2はリクエストの手動での署名を求めない場合、平文で送ることが出来ま す。全てのリクエストはHTTPSを通して行われなければなりません。HTTPSを使 わない場合、エラーとなります。 .. Be sure to note that although API requests are against api.foursquare.com, OAuth token and authorization requests are against foursquare.com. APIのリクエストは `api.foursquare.com` に対して行われていることに注意し てください。OAuthトークンと認証リクエストは `foursquare.com` に対して行 われます。 .. The examples above use /authenticate instead of /authorize. Following precedent established by Twitter and LinkedIn, the /authenticate page is like /authorize except it will automatically redirect if a user has already authorized the calling page. 上記の例では `/authorize` の代わりに `/authenticate` を使用しています。 TwitterとLinkedInによる前例にならうと、 /authenticate ページは /authorize と同じですが、もしユーザが既に認証されている場合は、自動的に リダイレクトされる点が異なります。 .. The OAuth2 spec provides for Resource Owner Password Credentials, exchanging the user's password for a token, but we do not allow third-party clients to use this flow for security reasons. OAuth2の仕様書ではユーザのパスワードをトークンと入れ替える Resource Owner Password Credentials がありますが、私たちはセキュリティ上の理由に より、サードパーティのクライアントにこれを使用することを許可していません。 .. One issue you may run into on Android is that foursquare uses a wildcard SSL cert. For more information, see this Stack Overflow answer. foursquareがワイルドカードSSL証明書を使用しているため、Android上で動か す時に、問題があるかもしれません。より詳細な情報は `Stack Overflowの回 答 `_ を見てください。 .. Although at this time we do not expire OAuth access tokens, you should be prepared for this possibility in the future. Also remember that a user may revoke access via the foursquare settings page at any time. 現在のところOAuthのアクセストークンが期限切れになることはありませんが、 あなたは将来的に期限切れになる可能性に備える必要があります。さらに、ユー ザはいつでもfoursquareの設定ページでアクセスを中止することが出来る点を 覚えておいてください。