次のメソッドとクラスは、Google+ ログイン ボタンと HTTP API を使用する場合に便利です。Google JavaScript Client API リファレンス リストには、他のメソッドとクラスも掲載されています。
JavaScript API の読み込み
ほとんどのプラグインで、サイトに含める必要があるのは Google+ JavaScript API(plus.js
)のみです。Google+ JavaScript API は、次のスクリプト タグで読み込むことができます。
<script src="https://apis.google.com/js/plus.js"></script>
ログイン ボタン、インタラクティブな投稿、REST ウェブ サービスを使用するアプリを作成している場合は、スクリプト タブでクライアントも読み込む必要があります。
<script src="https://apis.google.com/js/client:plus.js"></script>
onload コールバックの指定
スクリプトが正常に読み込まれたときに実行される onload
コールバックを定義することができます。このコールバックは、スクリプトが適切なタイミングで実行されたことを確認するのに便利です。
<script src="https://apis.google.com/js/plus.js?onload=OnLoadCallback"></script>
JavaScript API の非同期読み込み
ページの読み込み時間短縮のため、JavaScript を非同期に読み込むことができます。この方法では、ページと JavaScript ファイルを並行してブラウザに読み込むことができます。最適なパフォーマンスを実現するために、次の JavaScript を </body>
タグの前に挿入します。
<script type="text/javascript">
(function() {
var po = document.createElement('script'); po.type = 'text/javascript'; po.async = true;
po.src = 'https://apis.google.com/js/plusone.js?onload=OnLoadCallback';
var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(po, s);
})();
</script>
非同期読み込みを使ってすべての依存関係を読み込んだ後にコードの実行を確認する場合は、必ず onload
コールバックを使用してください。
設定オプション
プラグインの読み込み処理方法とプラグインで使用する言語を指定できます。これらのオプションは、JavaScript API を読み込む前に <script /> 要素内で定義するか、または JavaScript API を読み込むのと同じ <script /> 要素内で定義する必要があります。次に例を示します。
<script src="https://apis.google.com/js/plus.js?onload=OnLoadCallback">
// 次の設定オプションを定義します。
window.___gcfg = {
lang: 'en-US',
parsetags: 'explicit'
}
</script>
lang
- タイプ: 文字列。ページ上のすべてのプラグインで使用される言語を設定します。サポートされる言語の一覧をご覧ください。parsetags
- タイプ: 文字列。使用する読み込み方法を設定します。- onload: ページ読み込み後、ページ上のすべてのプラグインが自動的に表示されます。
- explicit: プラグインは
go
メソッドまたはrender
メソッドの明示的な呼び出しによってのみ表示されます。ページ内の特定のコンテナを参照する go と render の呼び出しと共に明示的に読み込むと、スクリプトは DOM 全体を走査する必要がなくなり、ボタンのレンダリング時間を短縮できます。
また、Google アナリティクスのソーシャル分析など、別の Google JavaScript API でも設定オプションの定義にこのオブジェクトを使用しています。
メソッド
次に示すメソッドは、Google+ の機能の操作に便利な JavaScript 用 Google API クライアントのサブセットです。たとえば、Google+ ログイン ボタンによって返されるトークンを取得、設定してから、gapi.client.request()
メソッドでそれ以降のクライアント側 API 呼び出しを行う場合です。
gapi.auth.authorize(parameters, callback)
OAuth 2.0 承認プロセスを開始します。ユーザーに対して、認証と承認を求めるポップアップ ウィンドウが表示されます(ユーザーはポップアップ ブロッカーを無効にする必要があります)。承認プロセスが完了したら、ポップアップが閉じ、コールバック関数が起動します。
引数:
parameters
- タイプ: オブジェクト。リクエストのパラメータのキー/値のマッピング。キーが、予期される OAuth 2.0 パラメータのいずれでもない場合(下記を参照)は、クエリ パラメータとして URI に追加されます。OAuth 2.0 パラメータの有効なキーには次のものがあります。client_id
- タイプ: 文字列。アプリケーションのクライアント ID。OAuth 2.0 クライアント ID を取得するには、Google APIs Console にアクセスします。immediate
- タイプ: ブール値。true
の場合、ログインでは「即時モード」を使用します。トークンはバックグラウンドで更新され、ユーザーに UI は表示されません。response_type
- タイプ: 文字列。OAuth 2.0 の応答タイプ プロパティ。デフォルト: トークン。scope
- タイプ: 配列。認証を受けるスコープ。各 API の認証スコープについては、それぞれのドキュメントをご覧ください。
callback
- タイプ: 関数。ログイン プロセスの完了時に呼び出す関数。唯一のパラメータとして OAuth 2.0 トーク オブジェクトを受け取ります。
gapi.auth.checkSessionState(sessionParams, callback)
クライアント ID と、ユーザーが初めて承認した際に作成されたセッション データが引き続き有効であることを確認することで、そのユーザーに有効な Google セッションがあるかどうかをチェックします。このメソッドは、ユーザーが Google からログアウトした場合、別の Google アカウントでログインした場合、または Google で再認証している場合を識別するのに役立ちます。null
を sessionParams.session_state
に渡すと、ユーザーが以前アプリを承認したかどうかにかかわらず、Google にログインしているかどうかをチェックできます。
このメソッドは、ウェブ アプリでユーザーをログアウトするかどうか判断する際に便利です。
引数:
sessionParams
- タイプ: オブジェクト。オブジェクト。次のパラメータを含める必要があります。client_id
- タイプ: 文字列。アプリのクライアント ID。必須。session_state
- タイプ: 文字列。OAuth 2.0 トークンの session_state。ユーザーが Google にログインしているかどうか判断するだけの場合は null。
callback
- タイプ: 関数。チェックが完了した時点で呼び出す関数。この関数では、ユーザーのセッション状態を表す引数を渡します。引数が true の場合、指定した session_state は引き続き有効です。引数が false の場合は、セッションの有効期限が切れ、アプリケーションは新しい再承認フローでimmediate
をtrue
に設定して最新のアクセス トークンを取得する必要があります。そうしない場合、未承認または存在しない Google ログイン セッションが検出されます。
gapi.auth.getToken(key, returnError)
アプリケーションの OAuth 2.0 トークンを取得します。
引数:
key
- タイプ: 文字列。token
オブジェクトを取得するために使用される ID。省略可能です。デフォルト:token
。returnError
- タイプ: ブール値。フラグ。省略可能です。true
の場合、トークンが使用できなければこの関数はエラー オブジェクトを返します。それ以外の場合は null が返されます。デフォルト:false
。
戻り値: タイプ: オブジェクト。OAuth 2.0 トークン。下記の OAuth 2.0 トークンをご覧ください。
gapi.auth.setToken(key, token)
アプリケーションの OAuth 2.0 トークンを設定します。この関数は、キーを使用せずに 1 つの引数(gapi.auth.setToken(token))を使用して呼び出すこともできます。
引数:
key
- タイプ: 文字列。token
オブジェクトを保存して後で取得するために使用される ID。省略可能です。複数のトークンを保存する必要がある場合に、この引数を使用します。デフォルト:token
。token
- タイプ: オブジェクト。設定するトークン。下記の OAuth 2.0 トークンをご覧ください。
gapi.client.load(name, version, callback)
特定の API とのクライアント インターフェースを読み込みます。新しい API インターフェースは gapi.client.api.collection.method の形式で指定します。たとえば、Moderator API でメソッドを作成する場合は gapi.client.moderator.series.list
のような形式になります。近日提供: API ごとのドキュメント。
引数:
name
- タイプ: 文字列。読み込む API の名前。version
- タイプ: 文字列。読み込む API のバージョン。callback
- タイプ: 関数。API インターフェースが読み込まれたら呼び出す関数。省略可能です。
gapi.client.request(args)
RESTful リクエストを作成するために HTTP リクエストを作成します。
引数:
args
- タイプ: オブジェクト。このメソッドの各種引数をカプセル化したオブジェクト。パスは必須ですが、それ以外は省略可能です。値の詳細については、下記をご覧ください。path
- タイプ: 文字列。リクエストを処理する URL。method
- タイプ: 文字列。使用する HTTP リクエスト。デフォルトは 「GET」です。params
- タイプ: オブジェクト: キー/値ペア形式の URL パラメータ。headers
- タイプ: オブジェクト: 追加の HTTP リクエスト ヘッダー。body
- タイプ: 文字列。HTTP リクエスト本文(PUT または POST に適用)。callback
- タイプ: 関数: 指定した場合、リクエストは即時実行され、gapi.client.HttpRequest オブジェクトは返されません。
戻り値: タイプ: gapi.client.HttpRequest|undefined。コールバックを指定しない場合、リクエスト オブジェクトが返されます。その後、このリクエストを gapi.client.HttpRequest.execute(callback)
経由で実行できます。
gapi.client.setApiKey(apiKey)
アプリの API キーを設定します。これはデベロッパー コンソールで見ることができます。キーを設定しなければ動作しない API もあります。
引数:
apiKey
: タイプ: 文字列。設定する API キー。
クラス
OAuth 2.0 トークン オブジェクト
OAuth 2.0 トークン オブジェクトは、OAuth 2.0 トークンとその関連データを表します。このオブジェクトのプロパティには次のものがあります。
access_token
- タイプ: 文字列。OAuth 2.0 トークン。成功の応答にのみ存在します。error
- タイプ: 文字列。エラーの詳細情報。エラーの応答にのみ存在します。expires_in
- タイプ: 文字列。トークンの有効期間(秒単位)。成功の応答にのみ存在します。state
- タイプ: 文字列。このトークンに関連する Google API スコープ。
gapi.client.HttpRequest
HTTP 応答をカプセル化したオブジェクト。このオブジェクトは直接インスタンス化されるのではなく、gapi.client.request によって返されます。次の 1 つのメソッドを定義します。
gapi.client.HttpRequest.execute(callback)
リクエストを実行し、指定したコールバックを応答時に実行します。
引数:
callback(jsonResp, rawResp)
- タイプ: 関数。リクエストが成功または失敗したときに実行されるコールバック関数。jsonResp
には JSON として解析される応答が含まれます。応答が JSON ではない場合、このフィールドはfalse
です。rawResp
は HTTP 応答です。これは JSON であり、body
、headers
、status
、statusText
のフィールドを含むオブジェクトとして解析可能です。
Google JavaScript Client API リファレンス リストには、他のメソッドとクラスも掲載されています。