デベロッパーポータルの作成

デベロッパーポータルの構成要素は以下のとおりです。

このセクションは、デベロッパーポータルシステムのビューで最も重要な部分です。Content セクションにはサイト構造と階層が表示され、またページ内のコンテンツを編集することができます。つまり、サイト構造、ページ、およびそこに保存されたその他のアセットを管理できます。ポータルの階層は、ディレクトリーツリーの形式で表示されます。

上記の図は、Content セクション内のあるページのサンプルビューを示しています。図に示すように、サイトのパス階層を維持したまま、すべてのファイル (ページ、イメージ、スタイルシート、JavaScript など) が表示されます。前述のように、セクションは機能的にディレクトリーと同じです。

右側には、ページ編集ビューが表示されます。ここにはページ名 (標準ページか組み込みページかどうかも示されます) と、コンテンツに新しい要素 (ページ、レイアウト、パーシャル、セクション、ファイル、またはポートレット) を追加するためのボタンが表示されます。その下では、ページで使用するレイアウトを選択したり、Liquid タグの機能を切り替えたりすることができます。それに続く部分はテキストエディターで、コードの強調表示、表作成、行番号など多くの機能に対応しています。タブボタンの Draft と Published を使用すると、編集したドキュメントのドラフトバージョンと公開バージョンが切り替わります。それに続くのは、ドキュメントのバージョンを一覧表示するアイコン、およびポップアップ編集ウィンドウを開くアイコンです。

ページのコンテンツを編集するには、目的のレイアウトを選択し、コンテンツタイプや URL パスなどのいくつかの追加オプションを設定してから、HTML、Markdown、または Textile 形式でコードを入力するだけです。

このビューのもう 1 つの重要な機能は、Preview ボタンです。ページの公開バージョンまたはドラフトバージョンをプレビュー表示するかどうかを選択できます。ボタンをクリックするとデベロッパーポータルモードにリダイレクトされ、レンダリングされたページの公開 (またはドラフト) バージョンと共に、ダークグレーの縦長のバーが表示されます (右側)。このバーには、デベロッパーポータルのページ、レイアウト、およびパーシャルの編集ビューへのリンクが含まれています。ここでは、ドラフトと公開ビューを切り替えることができます。

フィルター機能もあり、検索フィールドとして機能するだけでなく、表示される要素をスタイルシート、JavaScript またはその他の指定タイプのみに制限することができます。

Layouts および Partials セクションでは、テンプレートとページの再利用可能な部分を管理します。それらの機能は Content セクションの機能に類似しています。

Layouts セクションは、ページで使用されるテンプレートの定義で構成されます。レイアウトはページの主要構造で、このテンプレートのコンテンツが、そのレイアウトを使用するすべてのページでレンダリングされます。ページのパーシャル、ポートレット、および実際のコンテンツがテンプレートの内部に存在します。

パーシャルとは、コードの再利用可能な部分で、異なるページの多くの場所に適用できます。たとえば、フッターはどのレイアウトでも同じで、サイドバーもレイアウトが異なるものの、複数ページで同じものが使用されます。

レイアウト、パーシャル、メールテンプレート、またはポートレットにパーシャルを含めるには、以下のコマンドを使用します。

{% include "partial_name" %}

ポータルの他の部分と同様、レイアウトとパーシャルにもドラフトと公開の状態があり、以下の機能を含む、完全なバージョン履歴を確認できます。

Liquid タグの詳細ガイドは、『Liquid Reference』 を参照してください。

Content の最後のサブセクションは Portlets です。難易度の高いコーディングを必要とすることなく、高度な機能を利用できます。デベロッパーポータルでは、以下の 3 つの異なるポートレットを利用することができます。

必要なポートレットを作成する際には、タイトル、システム名、および外部 RSS フィードポートレットの URL フィードなど、必要なデータを設定ページで入力する必要があります。

デベロッパーポータルの最後の要素は、Redirects セクションと Changes セクションです。これらは、Content セクションよりもかなりシンプルですが、やはり重要なセクションであり、いくつかのカスタム機能を利用することができます。

Redirects は、あるポータル URL から別のポータル URL へのリダイレクトを設定するのに役立ちます。これは、たとえば古いページを非推奨にするが、すべてのリンクを変更したくない場合に便利です。Redirects は組み込みのデベロッパーポータルページには使用できません。自分で作成したページにしか使用することはできません。

最後の Changes セクションも重要です。ここには新しく編集され公開されていないすべてのページの一覧が含まれ、個別に公開するか、すべてを 1 度に公開するかを選択できます。

本セクションでは、デベロッパーポータルのローカルアセット更新の詳細について説明します。その際のベースを以下に示します。

したがって、既存のデベロッパーポータルインスタンスを更新し、新しいローカルアセットを使用するには、以下の手順に従います。

上述のインスタンス (Main layout および stats/chart) をベースに他のインスタンスファイルを作成している場合は、それらも更新する必要があります。詳細は、porta での Liquid タグ についてのドキュメントを参照してください。

承認ステップを削除するには、Audience > Accounts > Usage Rules の順に移動して、SIGNUP セクションで Developers are allowed to sign up themselves オプションのチェックボックスを選択します。

オプションとして、アカウントプランとサービスプランを有効にしている場合は、どちらのケースでも、ページをスクロールダウンして Change the plan directly オプションのチェックボックスを選択します。

アプリケーションプラン

オプションとして、アカウントプランとサービスプランを有効にしている場合は、そのデフォルトプランも選択します。

アカウントプラン (オプション)

サービスプラン (オプション)

必要な設定変更を行ったら、デベロッパーポータルに移動して新しい開発者としてサインアップを試み、結果をテストします。完全な API のワークフローが得られるように、テストを行い必要な調整を加えます。ワークフローが満足できるものになったら、メール通知を確認して、開発者に適切な情報が提供されるようにします。

レイアウトとページ作成の手順、ならびに Liquid フォーマットタグの基本に関する知識が必要です。Liquid タグの詳細については、『Liquid Reference』を参照してください。「マルチサービス」機能をご自分のアカウントでも有効にする必要があります (Pro 以上のプランで利用可能)。

サインアップワークフロー に関する手順を読み理解することを強く推奨します。こうすることで、すべての設定を完了し、その仕組みを理解することができます。

新しいレイアウトの作成からプロセスを開始します。このレイアウトは、マルチサービスへのサインアップページのテンプレートとして機能します。CMS システムの Layouts セクションに移動し、新しいレイアウトを作成します。他のレイアウトと簡単に区別できるようにするため、これを multipleservicesignup と呼ぶことにします。エディターで、標準レイアウト (home または main layout 等) の一般構造を貼り付けます。次に、必要ではないもの (コンテナー、サイドバー、その他のボックスなど) をすべて削除します。

レイアウトのベースを作成したら、サインアップ用コードのカスタマイズに進みます。

デベロッパーポータルでは、デフォルトでユーザー名/メールアドレスおよびパスワードによる認証が有効です。これは開発者がアカウントを作成してログインするための標準的な方法なので、通常は、ここを変更することはありません。

ただし、まれにですが、この認証タイプを削除する必要があります。そのためには、下記のスクリーンショットで示すように Login > New テンプレートを編集します。

デベロッパーポータルにユーザー名/メールアドレスおよびパスワードによる認証を追加して元の状態に戻す必要がある場合は、前のステップで追加した Liquid コメントタグを削除するだけです。

専用の GitHub アプリケーションを有効にするには、まずアプリケーションを作成し、対応するクレデンシャルを取得する必要があります。

GitHub による認証を設定するには、2 種類の方法があります。

このデフォルト設定に変更を加える場合、3scale 管理ポータルで Audience > Developer Portal > SSO Integrations の順に移動すると、以下のような画面が表示されます。

GitHub をクリックして設定画面にアクセスします。

この画面では、以下の操作を行うことができます。

Red Hat Single Sign-On (RH-SSO) は、統合サインオンソリューション (SSO) です。3scale と組み合わせて使用すると、利用可能な任意の RH-SSO アイデンティティーブローカー機能とユーザーフェデレーションオプションを使用して、開発者を認証することができます。

3scale との互換性がある Red Hat Single Sign-On のバージョンについての情報は、サポートされる構成 に関するページを参照してください。

5.4.3. 3scale の設定

Red Hat Single Sign-On による認証をデフォルトで有効にすることはできません。デベロッパーポータルへのアクセスを管理するために 3scale と Red Hat Single Sign-On アカウントを組み合わせて使用する場合は、以下の手順に従ってその設定を行うことができます。

3scale 管理ポータルで Audience > Developer Portal > SSO Integrations の順に移動し、Red Hat Single Sign-On をクリックします。(備考: これはエンタープライズ専用の機能なので、この機能を有効にするようアカウントマネージャーに依頼しなければならない場合があります。)

以下の設定画面で、前の手順で設定した Red Hat Single Sign-On クライアントの詳細情報を追加する必要があります。

• Client: Red Hat Single Sign-On でのクライアントの名前
• Client Secret: Red Hat Single Sign-On でのクライアントシークレット
• Realm: レルム名および Red Hat Single Sign-On への URL アドレス

これらを入力したら、「Published」チェックボックスを選択し、Create RH-SSO をクリックしてデベロッパーポータルで利用できるようにします。

まず、API 消費者は、デベロッパーポータルにアカウントがなければなりません。Account Management API を使用してユーザーを 3scale にインポートすることも、手動で作成することもできます。3scale ActiveDocs (管理ポータルの Documentation (右上隅の疑問符 (?) のアイコン) → 3scale API Docs セクションから利用可能) で Account Management API を検索します。

ユーザーが存在すると、API リクエストコールを使用して、組み込み SSO トークンにより URL を生成できます。

curl -X POST -d "provider_key=YOUR_PROVIDER_KEY&username=USERNAME&expires_in=60" https://YOUR_ADMIN_PORTAL.3scale.net/admin/api/sso_tokens.xml

この呼び出しには 2 つのパラメーターがあります。誰のトークンをリクエストするのかを指定する username と、トークンが有効である秒数 (デフォルトでは 10 分) の expires_in です。

ユーザーが正常にログインした後にリダイレクトされる場所と共に追加パラメーターの redirect_url を渡すこともできます。このパラメーターは、パーセントエンコーディング されている必要があります。XML レスポンスには、シークレットトークンが含まれる URL が含まれます。

<?xml version="1.0" encoding="UTF-8"?>
<sso_url>
https://YOUR_DEVELOPER_PORTAL/session/create?expires_at=1365087501&token=Q0dNWGtjL2h2MnloR11yWmNwazVZY0NhenlabnBoRUNaNUlyWjZaVG8wMnBGdVNhT0VGN1NUb3FRc1pwSnRrclBZSTIwOUFwRkVTc3NuK1JTbjUrMEE9PS0tY1ZrOGFldzFJNkxna1hrQzQyZ0NGQT09--712f2990ac9248ab4b8962be6467fb149b346000
</sso_url>

レスポンスには、トークンが含まれる RH SSO ログイン URL が含まれます。

https://YOUR_DEVELOPER_PORTAL/session/create?expires_at=1365087501&token=Q0dNWGtjL2h2MnloR11yWmNwazVZY0NhenlabnBoRUNaNUlyWjZaVG8wMnBGdVNhT0VGN1NUb3FRc1pwSnRrclBZSTIwOUFwRkVTc3NuK1JTbjUrMEE9PS0tY1ZrOGFldzFJNkxna1hrQzQyZ0NGQT09--712f2990ac9248ab4b8962be6467fb149b346000

URL には、3scale デベロッパーポータル SSO がログインを許可するのに必要なすべての情報が含まれます。これを Web に直接埋め込むことができます。ただし、URL はユーザーがクリックする前に期限切れになることがあるので、ページには、動的に新しい SSO URL をリクエストしてそこにリダイレクトする汎用リンクを用意することが推奨されます。このようにして、ユーザーをデベロッパーポータルにシームレスにログインさせます。

制限付きのセクションを作成する場合、各セクションをユーザーの論理グループにマッピングさせると便利です。以下の例では、「partners」という開発者グループがあると仮定します。

アクセスを制限するすべてのページまたはページのグループについて、デベロッパーポータルで新しいセクションを作成します。「public」ステータスフィールドのチェックボックスの選択を解除します。次に、このセクション内に必要なすべてのページをドラッグアンドドロップします。

グループを作成して、作成したセクションへのアクセス権限を付与します。

これで、このセクションへのアクセス権限をユーザーの一部に付与するときには、このグループに割り当てるだけで済みます。そのためには、該当するアカウントの詳細ページから「Group Permissions」に移動します。 移動したら、許可するセクションのチェックボックスを選択します。

Liquid タグを使用すると、デベロッパーポータルを自由にカスタマイズすることができます。本章の用途に Liquid タグを使用して、条件に基づきページの一部を表示/非表示にします。3scale では、アカウント、アプリケーション、およびユーザーにカスタムフィールドを作成できます。これを利用して、API プロバイダーに役立つ情報を格納できます。ここでは、すべてのアカウントにアタッチされるカスタムフィールドを作成し、これを使ってそのアカウントがパートナーかそうでないかを識別します。Audience > Account > Field Definitions の順に移動して、このフィールドを作成することができます。Account セクションにフィールドを追加してそれを非表示として設定すると、サインアップページやポータルのどのページにも表示されなくなります。

カスタムフィールドを設定すると、以下のスニペットに示すように条件でラップすることで、パートナーに特別なコンテンツを表示できるようになります。

{{ if current_account.extra_fields.partner == 'true' }}
  // content only accessible to partners
{{ endif }}

また、その方が適切であれば、逆のロジックを使用します。

{{ unless current_account.extra_fields.partner == 'true' }}
  // content forbidden for partners
{{ endunless }}

これ以降、この非表示コンテンツをユーザーに表示する場合には、該当ユーザーのアカウント詳細ページで partner フィールドに「true」と入力するだけです。

開発者に制限付きコンテンツへのアクセス権限を付与する場合があります。たとえば、アプリケーションプランをアップグレードした場合などです。

Account Management API と Webhook を組み合わせて使用して、このプロセスを簡素化します。Account Management API は、管理ポータルにある 3scale ActiveDocs に含まれています。

コンテンツへのアクセスを制限する上述の 2 つの手法に加えて、ユーザーにログインを要求するという別の有用な手法があります。

これは、Liquid タグを使用して非常に簡単に実施することができます。ログインしたユーザーのみが利用できるコンテンツを、以下の条件内にラップするだけです。

{{ if current_user }}
  // only visible if the user is logged in
{{ endif }}

本セクションでは、レイアウトおよびページで Liquid マークアップ処理を有効にする方法を説明します。

9.1.1. Liquid の有効化

Liquid マークアップ処理は、すべてのパーシャルとメールテンプレートに対してデフォルトで有効です。レイアウトで Liquid を有効にするには、system_name 入力フィールドの右下にあるチェックボックスを選択します。ただし、ページで有効にする場合は、そのページの ADVANCED OPTIONS セクションに移動する必要があります。

ADVANCED OPTIONS セクションを展開して、Liquid enabled チェックボックスを選択します。これ以降、Liquid マークアップはすべて内部エンジンで処理され、デベロッパーポータルの組み込みエディターでも、Liquid コードが強調表示されます。

<!-- if we are inside '/documentation' URL -->
<li class="{% if request.request_uri contains "/documentation" %}active{% endif %}"><!-- add the active class to the menu item -->
  <a href="/documentation">Documentation</a>
</li>

本セクションでは、Liquid タグを使用してメールテンプレートをカスタマイズする方法を説明します。

このトラブルシューティングセクションは、一般的に発生する可能性のあるエラーをデバッグして修正する場合に役立ちます。

これらのメールテンプレートは、アカウント管理カテゴリーに分類されます。

これらのテンプレートでは、以下の Liquid ドロップを使用できます。

また、テンプレート

追加のユーザーをアカウントに招待するメールテンプレート

以下の Liquid ドロップを使用できます。

では、以下の Liquid ドロップを使用できます。

以下のメールテンプレートは、すべてアプリケーションおよびアプリケーションプランの通知に関するものです。

これらは以下の Liquid ドロップを使用できます。

アプリケーションプランの変更リクエストに関する通知のメールテンプレート:

これらは以下の Liquid ドロップを使用できます。

以下のメールテンプレートには、以下のような利用可能なドロップが多数含まれています。

これらは以下の Liquid ドロップを使用できます。

上記のすべての Liquid ドロップに加え、アプリケーションプランに関するメッセージ

では、さらに以下の Liquid ドロップを使用できます。

アプリケーションキーに関する以下のメールテンプレートでは、さらに使用できる Liquid ドロップが増えます。

メールテンプレート

では、以下の Liquid ドロップを使用できます。

さらに、テンプレート

では、以下の Liquid ドロップをすべて使用できます。

メールテンプレート

では、以下の Liquid ドロップを使用できます。

上記の Liquid ドロップに加え、サービステンプレート

では、さらに以下の Liquid ドロップを使用できます。

メールテンプレート

では、以下の Liquid ドロップを使用できます。

デフォルトのスタイルシート default.css があります。これは非常に大きく複雑であるため、これを拡張するよりも、独自のカスタム用に専用のスタイルシートを作成し、デフォルトを上書きする方が適切です。ページの作成と同じ方法で、新しいスタイルシートを作成します (高度なページ設定で適切な MIME コンテンツタイプを選択するのを忘れないでください)。

選択したレイアウトが空であることが重要です。そうでないと、ページレイアウトの HTML で CSS ルールが分かりにくくなります。

各レイアウトテンプレート (または共通の HEAD セクションがある場合はパーシャル) で、bootstrap.css へのリンクの後に、カスタム CSS へのリンクを追加します。以下に例を示します。

<link rel="stylesheet" href="/stylesheets/custom.css">

これで、美しい独自のブランディングを楽しむことができます。

何よりも重要なことは、非表示にする対象の特定です。これには、Firebug (または Chrome Developer や Opera Dragonfly など、その他の開発者ツール) を使用します。目的の要素を選択し、コンソールでその要素を右クリックして Copy CSS Path を選択します。これにより、正確な CSS パスを保存して、操作を簡単にすることができます。要素がサイドバーナビゲーションウィジェットの一部である場合は、リスト内での位置も指定する必要がある点に注意してください。これには、「+」セレクター (たとえば、3 番目の li 要素を選択する場合: ul + li + li + li) または :nth-child(n) CSS3 疑似クラスのどちらかを使用できます。

要素を特定したので、表示設定を変更することができます。要素のタイプに応じて、CSS 操作または jQuery スクリプトという 2 つの手法からどちらかを選択できます。CSS 操作の方が軽量で信頼性に優れますが、多くのページに存在するある種の要素に対しては適切に機能しません (たとえば、管理ポータルの Dashboard にあるサイドバーの 3 番目の要素は、Account セクションにも存在するが、値が違う)。一部のテクニカルな実装には、古いブラウザーではサポートされない CSS3 の使用が必要です。次の 2 つの手順で、これらの両アプローチを説明します。

たとえば、Dashboard ページから、最新のフォーラム投稿ボックスを非表示にしてみます。最初のステップで、その CSS パスを以下のように特定しました。

#three-scale .dashboard_bubble

同じパスを持つ 2 番目のボックスなので、「+」セレクターを使用する点に留意してください。これで、パスは以下のようになります。

.main_layout #three-scale .dashboard_bubble + .dashboard_bubble
/* or */
.main_layout #three-scale .dashboard_bubble:nth-child(1)

display プロパティーを none に変更すると、そのボックスが非表示になります。

.main_layout #three-scale .dashboard_bubble:nth-child(1) {
  display: none;
}

サイドバーメニューの要素など、テクニカルな要素を非表示にする場合は、jQuery を使用する方が適切です。これらの要素の CSS パスは Dashboard と Account セクションとで同一ですが、両方のセクションで要素を非表示にする必要はありません。そこで、CSS パスとコンテンツに基づいて要素を選択します。ここでの例は、Dashboard のサイドバーから messages セクションを非表示にする場合を想定しています。CSS パスは以下のとおりです。

#three-scale #submenu li a

コンテンツと一致させるには、.text() 関数を使用します。また、ドキュメントのヘッドと ready 関数内にコードを含め、すべてのコンテンツが生成された後に実行されるようにします。

作成されるコードスニペットは以下のようになります。

$(function() {
  $('#three-scale #submenu li a').each(function() {
    if ($(this).text() == "Messages")
      $(this).parent().css('display', 'none');
  });
});

これが唯一のソリューションという訳ではありません。実行可能な方法の 1 つを示しているだけです。属性の値に基づき Pure.CSS と CSS3 セレクターを使用しても、例と同じことができます。CSS3 セレクターの詳細な仕様については、こちら を参照してください。

Webhook は、イベントによってトリガーされるカスタムの HTTP コールバックです。3scale システムでは、考え得るすべてのイベントが Account Settings (右上隅の歯車アイコン) の Integrate > Webhooks に表示されます。

これらのイベントのいずれかが発生すると、3scale システムは、Webhook セクションに設定された URI に対して HTTP (または HTTPS) リクエストを行います。API プロバイダー側では、リスナーを設定してイベント追跡などの目的の動作を呼び出すことができます。

スクリーンショットの 2 つのチェックボックスは、Webhook を有効にするためのものと (「Webhooks are」スイッチ)、管理ポータルのアクションでも Webhook がトリガーされるかどうかの設定です。デフォルトの動作では、デベロッパーポータル内のアクションでしか Webhook はトリガーされません。つまり、すべてのイベントでトリガーされるわけではないことを念頭に置いておいてください。

Webhook のフォーマットは常に同じです。以下の構造の XML ドキュメントでエンドポイントにポストします。

<?xml version="1.0" encoding="UTF-8"?>
<event>
  <type>application</type>
  <action>updated</action>
  <object>
    THE APPLICATION OBJECT AS WOULD BE RETURNED BY A GET ON THE ACCOUNT MANAGEMENT
    API
  </object>
</event>

各要素では、以下の情報を提供します。

Webhook が 3scale によって実行されたことを保証する必要がある場合は、HTTPS Webhook URL を公開し、3scale の Webhook 宣言にカスタムパラメーターを追加します。たとえば、https://your-webhook-endpoint?someSecretParameterName=someSecretParameterValue となります。パラメーター名と値を指定します。続いて、Webhook エンドポイント内で、このパラメーター値があることを確認します。

リッスンしているエンドポイントに障害が発生した場合、失敗した配信を回復できます。エンドポイントがコード 200 を返す場合に、3scale は Webhook が配信されたとみなします。そうでない場合は、60 秒間隔で 5 回リトライします。障害からの復旧後に、または定期的にチェックを実行し、必要に応じキューをクリーンアップする必要があります。ActiveDocs では、以下のメソッドの詳細情報を確認できます。

ワークフローのこの部分は、下記の手順に従い、管理ポータルで簡単に設定することができます。

Audience > Developer Portal > Signup の順に移動すると、サインアップの契約条項を入力するブランクページが表示されます。HTML、JavaScript、および CSS を自由に組み合わせて使用できます。また、Insert toggling code をクリックすると、トグルコードが提示されます。このボックスで作成するコンテンツは、デベロッパーポータルの Signup ページで Sign Up ボタンのすぐ上に表示されます。

契約条件を入力したら、Update をクリックして保存します。

トグルコードを使用している場合、「By signing up you agree to the following Legal Terms and Conditions」の後に、指定した契約条件の表示と非表示を切り替えるリンクが表示されます。

この契約条件は、デフォルトでは Signup ページに配置されますが、デベロッパーポータルのどこにでも含めることができるパーシャル (signup_licence) です。Signup ページからこの契約条件を削除するには、ページから {% include 'signup_licence' %} の行を削除するだけです。同様に、他の場所にこれを含める場合には、スニペットによって同じパーシャルを使用し、デベロッパーポータルのどこにでも配置することができます。

また、ユーザーが新しいアプリケーションを作成する場合 (new_application_licence パーシャル)、または新しいサービスをサブスクライブする場合 (service_subscription_licence パーシャル) には、別の契約条件のセットを承諾してもらう必要が生じます。これらを設定するには、上で概説したものと同じ手順に従います。

さまざまなポリシーを規定する他の URL を定義することもできます。Audience > Billing > Credit Card Policies の順に移動し、ポリシーページの場所のパスを設定して、URL の設定を行います。

これらのリンクを機能させるためには、デベロッパーポータルに新しいページを作成する必要があります。

完了したら、URL の Liquid ドロップを使用してこれらを参照することができます。以下に例を示します。

<a href="{{ urls.credit_card_terms }}">Legal Terms</a>
<a href="{{ urls.credit_card_privacy }}">Privacy</a>
<a href="{{ urls.credit_card_refunds }}">Refunds</a>

これで完了です。

本チュートリアルでは、デベロッパーポータルを稼動状態にして API をプロモートし、開発者がサインアップしてアカウントを作成し、API キーにアクセスするのを許可する方法について説明します。

他にもデベロッパーポータルの操作箇所で、設定可能なエリアがあります。