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

Red Hat 3scale 2-saas

確実に API を利用してもらうためには、優れたデベロッパーポータルが不可欠です。今すぐ作成しましょう。

Red Hat Customer Content Services

概要

本ガイドでは、Red Hat 3scale 2-saas のデベロッパーポータルについて説明します。

多様性を受け入れるオープンソースの強化

Red Hat では、コード、ドキュメント、Web プロパティーにおける配慮に欠ける用語の置き換えに取り組んでいます。まずは、マスター (master)、スレーブ (slave)、ブラックリスト (blacklist)、ホワイトリスト (whitelist) の 4 つの用語の置き換えから始めます。この取り組みは膨大な作業を要するため、今後の複数のリリースで段階的に用語の置き換えを実施して参ります。詳細は、CTO である Chris Wright のメッセージ をご覧ください。

第1章 デベロッパーポータル

本セクションを完了すると、デベロッパーポータルの構造、使用方法、および機能を理解することができます。

実際のブランディングに合わせて、デベロッパーポータル全体の外観や操作感をカスタマイズできます。ポータルのすべての要素を完全に制御できるので、開発者に API の使用方法を容易に理解してもらうことができます。API デベロッパーポータルが適切に作成されていれば、開発者はコンセプトをごく短時間のうちに実際のアプリケーションに具体化することができます。

1.1. デベロッパーポータルの概要

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

  • 左側のメニュー: Content、Drafts、Redirects、Groups、Feature Visibility、ActiveDocs、Legal Terms、Settings、および Liquid のドキュメントにアクセスできます。
  • メインエリア: 上記セクションの詳細が表示されます。
Developer portal page overview

1.2. Content

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

Developer portal content page

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

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

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

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

Developer Portal preview mode

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

Find content in Developer Portal

1.3. Layouts および Partials

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

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

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

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

{% include "partial_name" %}

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

  • レイアウトテンプレート用のテキストエディター
  • ドラフトを保存する、現在のバージョンを公開する、最後の公開バージョンに戻すことができます。
  • テキストエディターをドラフトバージョンと公開バージョンで切り替える、バージョン履歴を一覧表示する、ポップアップエディターを起動することができます。
Developer portal layout highlight

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

1.4. Redirects および Changes

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

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

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

1.5. ローカルアセットの更新

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

  • 3scale 2.8 から、新しいデベロッパーポータルはすべて cdn_asset タグを使用して作成されます。
  • 既存のデベロッパーポータルインスタンスについては、cdn_asset タグを使用してアセットを更新する必要があります。この機能により、他の Web サイトからダウンロードする必要のあるアセットへの依存がなくなりました。すべての外部アセットがコンテンツ配信ネットワーク (CDN) からコードベースに移行されたためです。

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

  1. Audience > Developer Portal > Content の順に移動します。
  2. ウィンドウの左側にあるメニューリストから、Main layout を選択します。

    Developer Portal: main layout
  3. {{ '//netdna.bootstrapcdn.com/font-awesome/4.3.0/css/font-awesome.css' | stylesheet_link_tag }}

    {% cdn_asset /font-awesome/4.3.0/css/font-awesome.css %} に置き換えます。

  4. {{ '//ajax.googleapis.com/ajax/libs/jquery/1.7.1/jquery.min.js' | javascript_include_tag }}

    {% cdn_asset /jquery/1.7.1/jquery.min.js %} に置き換えます。

  5. Publish をクリックし、続いて Save をクリックします。
  6. ウィンドウの左側にあるメニューリストから、Partials を選択します。
  7. stats/chart を選択します。

    Developer Portal: main layout
  8. {{ '//ajax.googleapis.com/ajax/libs/jqueryui/1.11.4/themes/ui-lightness/jquery-ui.css' | stylesheet_link_tag }}

    {% cdn_asset /jquery-ui/1.11.4/jquery-ui.css %} に置き換えます。

  9. Publish をクリックし、続いて Save をクリックします。

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

第2章 カスタムのサインアップフォームフィールド

ここでは、カスタムのサインアップフィールドを追加する方法およびこの機能に関するさまざまなオプションについて説明します。

デフォルトの 3scale では、共通的に使用されるフィールドはユーザー/アカウント/アプリケーションのサインアップで設定します。これらの共通的なデフォルトフィールドに、独自のカスタムフィールドを追加する必要が生じる場合があります。

管理ポータルで Audience > Accounts > Field Definitions の順に移動し、ここでデフォルトのフォームフィールドを表示し、新規フィールドを定義することができます。

field definitions default fields

新しいアカウント/ユーザーのサインアップページは、実際には最初の 2 つのセクションを統合したものです。アカウントフィールドが上部に表示され、その後にユーザーフィールドが、そしてパスワードフィールド (設定の必要はない) が続きます。

new user sign-up default

新たにフィールドを 3 つ追加してみます。2 つをユーザーサインアップセクションに、1 つをアカウントセクションに追加します。Create をクリックして以下の新規フィールド定義を追加し、フィールド定義を作成します。Required チェックボックスを選択すると、当然、サインアップフォームで必須になります。フィールドを非表示や読み取り専用にするオプションも可能です。たとえば、新しいサインアップページに、デフォルトでは空である access_restricted_areas のようなユーザーの目に触れさせる必要のないフィールドセットを設定する場合、非表示フィールドを追加することができます。管理者は、後からこれをユーザーごとに true に更新できます。ページロジックはこれを読み取り、表示する項目を判断することができます。読み取り専用フィールドの例としては、ページの読み込み時に JavaScript を使用して設定することのできる、ブラウザーの位置情報が挙げられます。

new last name

次に、ユーザーサインアップフォームにドロップダウンを追加してみます。「Employment type」を追加するとします。選択したフィールドに、コンマ区切りの値 (Full time, Part time, Contract) を追加します。ドロップダウンに、これらの値が反映されます。

new drop down

ここで、事前定義済みのフィールドをアカウントに追加します。通常、追加するフィールドにはシステム機能がありません。フィールドは後からアクセス可能なデータを保持するだけです。(「コンテンツの制限」を参照してください。)

通常どおりにフィールドを作成します。次に、「Name」の上のドロップダウンリストで、po_number を選択します。このフィールドを使用すると、この開発者アカウントに送付される 3scale 生成の請求書に PO 番号が表示されます。システムの生成するフィールドは、いつでも管理者が上書きすることができます。「PO number」のような名前を付けて、フィールドを作成します。

new pre defined

次に作業内容を確認します。ユーザーセクションに、自由記述の姓フィールドと、雇用タイプのドロップダウンが追加されていることを確認できます。同様に自由記述の PO 番号のシステムフィールドが、アカウントセクションに追加されています。

signup with new fields

これで 3scale ActiveDocs を使用してこれらのカスタムフィールドを設定できます (例: application create)。

第3章 サインアップフローの設定

本セクションでは、サインアップワークフローを調整するために行う設定について説明します。

サインアップワークフローは、デベロッパーポータルを通じて提供する開発者体験の最も重要な部分です。このプロセスは、完全自動のセルフサービスから、逆に誰が何にアクセスできるかを完全に管理するものまで、さまざまな粒度レベルに対応しています。

3scale プラットフォームでは、アカウント (オプション)、サービス (オプション)、およびアプリケーションプランの組み合わせを使用して API をモデル化できます。これらの各プランについて、API プロバイダーの承認を要するかどうかを制御できます。それぞれについて、デフォルトを提供するか、あるいは開発者が次の手順に進んで選択する必要があるかも決定します。

最大限の自動化とセルフサービスを許容する極端なケースでは、すべての承認ステップを削除し可能なデフォルトプランをすべて有効にします。これにより、サインアップ直後にキーを発行して、API へのアクセスを提供することができます。

3.1. すべての承認ステップの削除

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

Developer signup flow signup

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

Developer signup flow remove approvals

3.2. すべてのデフォルトプランの有効化

アプリケーションプラン

Developer signup flow app plan

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

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

Developer signup flow account plan defaults

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

Developer signup flow service plan

3.3. ワークフローのテスト

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

Developer signup flow email templates

第4章 マルチサービスへのサインアップ

本セクションを完了すると、マルチサービスへのサインアップページを作成およびカスタマイズする手順を理解することができます。

マルチサービスの機能を使用している場合は、顧客がさまざまなサービスにサブスクライブできるようにサインアップ手順をカスタマイズすることができます。

4.1. 前提条件

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

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

4.2. はじめに

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

developer portal introduction

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

4.3. マルチサービスへのサインアップ

4.3.1. サービスに関する情報の取得

適切なサインアップリンクを構築する必要があるサービスについて、その情報をすべて取得するためには、サービスオブジェクトをループスルーしなければなりません。サービスは、モデルオブジェクトの一部です。

{% for service in provider.services %}
  .
  .
  .
{% endfor %}

4.3.2. サインアップカラムの設定

すでにレイアウトとサービスオブジェクトにアクセスするループがあります。次に、サービスとサインアップリンクに関する情報の表示方法を決定します。たとえば、カラムに分けて、サービスの説明とサインアップリンク (カラム下部) を表示します。すべてのカラムは service-column クラスの div ボックスに対応し、ここに必要なすべての情報が収められます。

{% for service in provider.services %}
  <div class="service-column">
    <p>{{ service.name }}</p>
    <p>{{ service.description }}</p>
    .
    .
    .
  </div>
{% endfor %}

コンテナー内部はカスタムの説明フィールドとして機能します。service.name はサービスの名前で、ここではコンテナーの名前になります。

4.3.3. サブスクリプションの設定

次は、カスタムのサービスサインアップの主要部分です。サインアップリンクを作成するため、サインアップ URL とサービス ID を抽出します。URL のオブジェクトからサインアップ URL を、ループで繰り返すサービスオブジェクトからサービス ID を、それぞれ取得します。最終的なリンクコードは以下のようになります。

<a href="{{ urls.signup }}?{{ service | toparam }}">Signup to {{ service.name }}</a>

いくつかのサービスについて、ユーザーがすでにサインアップ済みであることも考慮する必要があります。確認するための条件ブロックを作成します。

{% unless service.subscribed? %}
  <a href="{{ urls.signup }}?{{ service | toparam }}">Signup to {{ service.name }}</a>
{% endunless %}

これを使用して、最終的なコードを生成できます。

{% for service in provider.services %}
  <div class="service-column">
      <p>{{ service.name }}</p>
      <p>{{ service.description }}</p>
      {% unless service.subscribed? %}
        <a href="{{ urls.signup }}?{{ service | to_param }}">Signup to {{ service.name }}</a>
      {% endunless %}
  </div>
{% endfor %}

4.3.4. スタイリング

対象のサービスの数に応じて、生成したマークアップに最終的な仕上げを行います。この例ではサービスが 2 つあるので、service-column div の CSS コードは以下のようになります。

.service-column {
    float: left;
    margin-left: 10%;
    width: 45%;
}
.service-column:first-child {
  margin-left: 0;
}

この例では、パーセントベースのレイアウトを使用して、含まれる div の大きさを元にカラムの幅を動的に割り当てています。

これで、正常に動作し見た目の整った複数サービスのサブスクリプションページができたはずです。お疲れさまでした。

カラムを特定の順序で表示する場合は、サービス名または利用可能なその他の値を条件とする条件式 (if/else/case) を使ってみてください。

第5章 デベロッパーポータルの認証

デベロッパーポータルへのアクセスを設定するには、以下の手順に従います。

本章では、開発者のサインアップまたはサインインを許可するためにデベロッパーポータルで利用可能なさまざまなタイプの認証について、有効および無効にする方法を説明します。

現時点で、デベロッパーポータルへの認証に関して、3scale はさまざまな方法をサポートしています。それらを以降のセクションで説明します。

デフォルトでは、デベロッパーポータルで有効にできる認証方法は 1 つだけですが、3scale.net でサインアップした場合は 2 つになります。

  • ユーザー名/メールアドレスおよびパスワードによる認証
  • GitHub による認証 (3scale GitHub アプリケーションを使用): デフォルトでは 3scale.net でサインアップした場合にのみ有効
GitHub Authentication
注記

2015 年 12 月 14 日より前に作成された古い 3scale アカウントの場合、GitHub 認証および Auth0 認証を有効にするためには、また別の手順に従わなければならない可能性があります。

これに該当する場合、ログインおよびサインアップ用のフォームでこの機能を有効にするためには、以下のコードスニペットを両方のテンプレートに追加する必要が生じます。

    {% include 'login/sso' %}

5.1. ユーザー名/メールアドレスおよびパスワードによる認証の有効化と無効化

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

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

GitHub Authentication

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

5.2. GitHub による認証の有効化および無効化

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

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

  • 3scale GitHub アプリケーションを使用する (ホスト型 3scale アカウントではデフォルトで有効)
  • 専用の GitHub アプリケーションを使用する (オンプレミス型のインストール環境用)

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

SSO integrations

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

Edit SSO integrations

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

  1. デベロッパーポータルでの GitHub 認証を利用可能にしたり利用不可にしたりする。その操作は、「Published」チェックボックスを選択または選択を解除するだけです。
  2. 3scale ブランドの GitHub アプリケーションを選択する、または専用の GitHub アプリケーションを追加する。3scale GitHub アプリケーションはデフォルトで有効です (公開されています)。Edit をクリックし、GitHub で作成した OAuth アプリケーションの詳細 (「Client」と「Client secret」) を入力することで、専用の GitHub アプリケーションを設定できます。専用の GitHub アプリケーションでインテグレーションを適切に機能させるためには、「custom branded」オプションを切り替えた後に表示される「Callback URL」を使用して GitHub アプリケーションの承認コールバック URL を設定しなければならないことに留意してください (例: https://yourdomain.3scale.net/auth/github/callback)。
  3. 設定した認証フローが想定どおりに機能することをテストする。

5.3. Auth0 による認証の有効化および無効化

5.3.1. 注記

この機能は、Enterprise プランでのみ利用可能です。

開発者が Auth0 を使用して認証できるようにするためには、まず有効な Auth0 サブスクリプションが必要です。

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

3scale 管理ポータルで Audience > Developer Portal > SSO Integrations の順に移動し、Auth0 をクリックします。

SSO with Auth0

この設定画面で、Auth0 アカウントの詳細情報を追加する必要があります。クライアント ID、クライアントシークレット、およびサイトを入力したら、「Published」チェックボックスを選択して Create Auth0 をクリックし、デベロッパーポータルで利用できるようにします。

5.4. Red Hat Single Sign-On による認証の有効化および無効化

注記

この機能は、Enterprise プランでのみ利用可能です。

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

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

5.4.1. 操作を始める前に

Red Hat Single Sign-On を 3scale と統合する前に、動作状態にある Red Hat Single Sign-On インスタンスが必要です。RH-SSO 7.2 のインストール に関する手順については、Red Hat Single Sign-On のドキュメントを参照してください。

5.4.2. デベロッパーポータルを認証するための RH SSO の設定

Red Hat Single Sign-On を設定するには、以下の手順を実施します。

  1. Red Hat Single Sign-On のドキュメント に記載の手順に従って、レルムを作成します。
  2. Clients に移動して Create をクリックし、クライアントを追加します。
  3. 以下のフィールドと値を考慮してフォームに入力します。

    • Client ID: クライアントの希望の名前を入力します。
    • Enabled: ON に切り替えます。
    • Consent Required: OFF に切り替えます。
    • Client Protocol: openid-connect を選択します。
    • Access Type: confidential を選択します。
    • Standard Flow Enabled: ON に切り替えます。
    • Root URL: 3scale 管理ポータルの URL を入力します。これは、デベロッパーポータルへのログインに使用する URL アドレスでなければなりません (例: https://yourdomain.3scale.net またはカスタムの URL)。
    • Valid Redirect URLs: /* を付けて再度デベロッパーポータルを入力します (例: https://yourdomain.3scale.net/*)。

      その他のパラメーターはすべて空のままにするか、OFF に切り替える必要があります。

  4. 以下の手順によりクライアントシークレットを取得します。

    • 前のステップで作成したクライアントに移動します。
    • Credentials タブをクリックします。
    • Client Authenticator フィールドで、Client Id and Secret を選択します。

      RH-SSO
  5. email_verified マッパーを設定します。3scale では、ユーザーデータの email_verified 要求が true に設定されている必要があります。「Email Verified」ユーザー属性を email_verified 要求にマッピングするには、以下の手順を実施します。

    • クライアントの Mappers タブに移動します。
    • Add Builtin をクリックします。

      RH-SSO
    • email verified オプションのチェックボックスを選択し、Add selected をクリックして変更を保存します。

      RH-SSO

      Red Hat Single Sign-On ローカルデータベースでユーザーを管理する場合は、必ずユーザーの Email Verified 属性を ONに設定してください。

      ユーザーフェデレーション を使用する場合は、3scale SSO インテグレーション用に前のステップで作成したクライアントで、トークン名を email_verified とし要求の値を true に設定して、ハードコーディングされた要求を設定することができます。

  6. オプションとして、org_name マッパーを設定します。
    ユーザーは 3scale にサインアップするとき、サインアップフォームに組織名の値を入力するよう求められます。デベロッパーポータルでのサインアップフォームの入力を不要にして、ユーザーが Red Hat Single Sign-On によるサインアップを意識しないようにするには、さらに org_name マッパーを設定する必要があります。

    • クライアントの Mappers タブに移動します。
    • Create をクリックします。
    • 以下のようにマッパーのパラメーターを入力します。

      • Name: 希望する任意の名前を入力します (例: org_name)。
      • Consent Required: OFF に切り替えます。
      • Mapper Type: User Attribute を選択します。
      • User Attribute: org_name を入力します。
      • Token Claim Name: org_name を入力します。
      • Claim JSON Type: String を選択します。
      • Add to ID token: ON に切り替えます。
      • Add to access token: ON に切り替えます。
      • Add to userinfo: ON に切り替えます。
      • Multivalued: OFF に切り替えます。
    • Save をクリックします。

      RH-SSO

      Red Hat Single Sign-On のユーザーに org_name 属性があれば、3scale は自動的にアカウントを作成することができます。属性がないユーザーについては、アカウント作成の前に組織名を指定するよう求められます。あるいは、Red Hat Single Sign-On アカウントでサインインするすべてのユーザーについて、Hardcoded claim タイプのマッパーを作成して、組織名をハードコーディング値に設定することもできます。

  7. インテグレーションをテストするには、ユーザーを追加する必要があります。そのためには、Users に移動し、Add user をクリックして必須フィールドに入力します。Red Hat Single Sign-On でユーザーを作成する場合、Email Verified 属性 (email_verified) が ON に設定されている必要があることに留意してください。設定されていないと、ユーザーが 3scale でアクティブ化されません。

Red Hat Single Sign-On のアイデンティティーブローカーとしての使用

Red Hat Single Sign-On をアイデンティティーブローカーとして使用することや、外部データベースをフェデレーションするように設定することができます。これらの設定方法については、Red Hat Single Sign-On のドキュメントで、アイデンティティーブローカー設定 および ユーザーフェデレーション に関する章を参照してください。

アイデンティティーブローカーとして Red Hat Single Sign-On の使用を選択し、さらに開発者が RH-SSO と 3scale のアカウント作成手順の両方をスキップできるようにすることを希望する場合は、下記の設定を行うことを推奨します。以下の例では、アイデンティティープロバイダーとして GitHub を使用しています。

  1. Red Hat Single Sign-On で、アイデンティティープロバイダー に GitHub を設定してから、Mappers というタブに移動し、Create をクリックします。

    RH-SSO
  2. 名前を付けて、識別できるようにします。
  3. Mapper TypeAttribute Importer を選択します。
  4. Social Profile JSON Field Path に company を追加します。これは GitHub での属性の名前です。
  5. User Attribute Name に org_name を追加します。これは Red Hat Single Sign-On での属性の呼び方です。

    注記

    Red Hat Single Sign-On では、必須フィールドとして姓および名に加えてメールアドレスの入力が必要です。3scale では、メールアドレス、ユーザー名、および組織名が必要です。したがって、組織名のマッパーを設定することに加え、ユーザーが両方のサインアップフォームをスキップできるよう、以下のことを確認してください。

    • IdP アカウントで、姓と名が設定されている。
    • IdP アカウントで、メールアドレスにアクセスできる。つまり、GitHub で、メールアドレスがプライベートに設定されている場合、共有されません。

5.4.3. デベロッパーポータルを認証するための 3scale の設定

API プロバイダーは、Red Hat Single Sign-On (RH-SSO) を使用したデベロッパーポータルの認証が可能になるように 3scale を設定します。

注記

RH-SSO を使用した認証は、デフォルトでは有効になっていません。RH-SSO は、エンタープライズ 3scale アカウントでのみ利用可能です。したがって、アカウントマネージャーに RH-SSO による認証を有効にするように依頼する必要があります。

前提条件

  • エンタープライズ 3scale アカウントが、RH-SSO を有効にするように設定されている。
  • デベロッパーポータルを認証するために RH SSO を設定した後、以下の詳細情報を取得している。

    • クライアント: RH-SSO でのクライアント名
    • クライアントシークレット: RH-SSO でのクライアントシークレット
    • レルム: レルム名および RH-SSO アカウントへの URL アドレス

手順

  1. 3scale 管理ポータルで Audience > Developer Portal > SSO Integrations の順に選択します。
  2. Red Hat Single Sign-On をクリックします。
  3. 「デベロッパーポータルを認証するための RH SSO の設定」で設定した RH-SSO クライアントの詳細 (クライアント、クライアントシークレット、およびレルム) を指定します。
  4. 変更を保存するには、Create Red Hat Single Sign-On をクリックします。

第6章 デベロッパーポータル用の Red Hat Single Sign On

Red Hat Single Sign On (RH SSO) を使用すると、独立した複数のシステムのアクセス制御を管理できます。本章の手順に従うと、ご自分のシステムにログインするユーザーは、再度ログインを求められることなく、3scale デベロッパーポータルに自動的にログインすることができます。

ここでは、Web サイトの既存のユーザークレデンシャルを使って、どのように 3scale デベロッパーポータルに自動的にログインするかを説明します。

この機能は、API 消費者の ID (ユーザー名およびパスワード) をすでに所有している API プロバイダー向けのものです (たとえば、API プロバイダーがアイデンティティープロバイダーでもあるケース)。

6.1. 3scale プラットフォームでのユーザーの作成

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

6.3. 自動ログインによるユーザーのリダイレクト

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

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

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

注記

URL のアドレスはエスケープ解除する必要があります。これをブラウザーで手動で行う場合には、ブラウザーで &amp& に置き換えるのを忘れないでください。また、トークンの % エンコーディングは、すべてその非エスケープ文字で置き換える必要があります。

第7章 コンテンツの制限

本章では、デベロッパーポータルのコンテンツを一部のユーザーにしか見えないようにする方法を説明します。

デベロッパーポータルの一部のページについて、ページの一部またはあるメニュー項目を、特定の開発者グループだけがアクセスできるように設定しなければならない場合があります。いずれの場合も、以下で紹介する 2 つの手法により目的を達成することが可能です。

7.1. ページの制限

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

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

New private secton

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

New group

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

Group permissions

7.2. コンテンツブロックの制限

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

Group permissions

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

{{ 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」と入力するだけです。

7.3. 追加フィールドの設定の自動化

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

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

  1. ウィンドウの右上にある Documentation (疑問符 (?)) をクリックします。
  2. 3scale API Docs を選択します。
  3. Webhook 要求によって送信されたメッセージをチェックして、制限付きコンテンツにアクセスする開発者の新しいプランを取得します。
  4. 開発者の新しいプランに基づいて、partner フィールドを更新する API を呼び出すことで、プライベートコンテンツへのアクセス権限を付与することができます。

7.4. ユーザーログインの要求

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

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

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

第8章 メールテンプレート

本章では、カスタムメールテンプレートを編集して保存する方法について説明します。

開発者とのあらゆる標準メール通信のコンテンツを完全にカスタマイズすることができるので、デベロッパーポータルに設定してあるワークフローに厳密にマッチさせることが可能です。

8.1. メールテンプレートのカスタマイズ

8.1.1. メール設定の前に行うワークフローの定義

メールテンプレートオプションは多数ありますが、一部のテンプレートだけがご自分のワークフローに関連します。メールテンプレートの編集を始める前に、時間節約のため、ワークフローに問題がないことを確認します。こうすることで、実際に使用するテンプレートだけを編集することができます。

8.1.2. ワークフローのテストおよび有効なメールテンプレートを識別

最終的なワークフローのドライランを実行し、考え得る状況 (承認や拒否など) をすべて確実にテストします。次に、テスト用の開発者アカウントが受信する各メール通知を識別し、次のステップで何を編集すべきかを判断します。

8.1.3. カスタムテンプレートの編集および保存

テンプレートを初めて編集する場合、実際にカスタムテンプレートを「作成」することになります。その後の編集で、変更を保存します。警告: バージョン管理はありません。変更を元に戻せるようにしたい場合は、ローカルコピーを作成することを推奨します。

電子メールの動的コンテンツに Liquid タグを使用できます。Liquid タグに変更を加える場合は特に、バックアップを作成することを推奨します。

Developer portal email template edit

8.1.4. ワークフロー内の全テンプレートについての反復

ワークフローで考え得るすべての状況をカバーするまで、同じ手順を実施します。

8.2. 補足情報

第9章 メールドメインの設定

お客様に代わって 3scale システムから開発者に送付されるメールは、SendGrid により配布されます。本セクションの設定ガイドラインにより、メールが 3scale からではなくご自分のドメインのいずれかから送信されるようにすることが可能です。

この機能は、Personal プランのアカウントでは利用できません。

ご自分のメール設定を定義したら、Red Hat カスタマーポータルで サポートケースを作成し、プロセスを完了します。SSL 証明書と同様に、できるだけ早くこの手順を完了することを推奨します。

Email configuration flow diagram

9.1. 手順

9.1.1. メールドメインの設定

  1. ドメイン CNAME を SendGrid に追加します。(APIMAIL.YOURDOMAIN サブドメインに任意の項目を選択します)。

    APIMAIL.YOURDOMAIN.com CNAME u11705.wl206.sendgrid.net
  2. 以下の TXT レコードを APIMAIL.YOURDOMAIN.com に追加します。

    APIMAIL.YOURDOMAIN.com TXT v=spf1 include:u11705.wl206.sendgrid.net -all

    または、以下の行を既存のレコードに追加します。

    include:u11705.wl206.sendgrid.net
  3. ドメインキーを追加して、メールが配信されるようにします。

    s1._domainkey.YOURDOMAIN.com CNAME s1.domainkey.u11705.wl206.sendgrid.net
    s2._domainkey.YOURDOMAIN.com CNAME s2.domainkey.u11705.wl206.sendgrid.net
    o1.APIMAIL.YOURDOMAIN.com A 167.89.103.115

9.1.2. DNS 変更の確認

コマンドラインから以下の DIG ステートメントを使用し、DNS の変更が適切に実装されていることを確認します。

  dig cname APIMAIL.YOURDOMAIN.com
  # should return "u11705.wl206.sendgrid.net"

  dig cname s1._domainkey.YOURDOMAIN.com
  # should return "s1.domainkey.u11705.wl206.sendgrid.net"

  dig cname s2._domainkey.YOURDOMAIN.com
  # should return "s2.domainkey.u11705.wl206.sendgrid.net"

  dig a o1.APIMAIL.YOURDOMAIN.com
  # should return "167.89.103.115"

  dig txt APIMAIL.YOURDOMAIN.com
  # should return "v=spf1 include:u11705.wl206.sendgrid.net -all"

9.1.3. メールドメインの変更を確定するためのサポートへの通知

最後のステップとして、メールの変更を開始するためにサポートに以下の情報を通知します。

  • 送信メール用に希望するメールアドレス。メールアドレスは、apicontact@YOURDOMAIN.com の形式で指定する必要があります。
  • APIMAIL.YOURDOMAIN に使用したエントリー。
  • 会社の正確な住所 (国名を含む)
  • 連絡先電話番号

第10章 カスタムドメインの設定

https://developer.mydomain.com または https://api.mydomain.com のように、ご自分の企業ドメイン名に属するデベロッパーポータルのブランディングを設定することができます。3scale のお客様の中で最も人気のあるオプションは developer.mydomain.com です。

カスタムデベロッパーポータルドメイン用に、SaaS 版 3scale プラットフォームは Let's Encrypt 認証局が発行する SSL 証明書を管理します。

以下の手順に従って、デベロッパーポータルの URL をご自分の企業ドメイン名に属するものに変更します。

10.1. 前提条件

  • 有料の 3scale プランにサブスクライブする必要があります。
  • 有効な 3scale エンタイトルメントが設定された Red Hat アカウントが必要です。

Red Hat アカウントに関してサポートが必要であれば、Red Hat カスタマーサービス にお問い合わせください。

10.2. 手順

10.2.1. DNS 設定への CNAME エントリーの追加

DNS において、ドメイン名を autossl.3scale.net にポイントする CNAME レコードを追加します。たとえば、autossl.3scale.net にポイントするドメイン developer.mydomain.com は、以下のようになります。

developer.mydomain.com.  CNAME  autossl.3scale.net.

通常、デベロッパーポータルへのパブリックアクセスを許可する前に、カスタムドメインに変更を加えます。パブリックユーザーがすでにいる場合は、mydomain.3scale.net からカスタムドメインへのリダイレクトを定義することができないことに注意してください。そのため、ドメインの変更についてユーザーに通知する必要があります。

事前に CNAME を実装することが推奨されます。上記が不可能なまれなケースでは (そのドメインで一般に公開されている既存サイトがある場合など)、Red Hat サポート に問い合わせてスイッチオーバーを同期させるのに最適な方法を判断してください。

DNS の変更が反映されるまでに、多少時間がかかる場合があります。CNAME レコードが正しく設定されていることを確認します。以下のコマンドを使用して、CNAME 設定を確認することができます。

dig cname developer.mydomain.com

または

nslookup developer.mydomain.com

10.2.2. DNS 設定への CAA レコードの追加 (オプション)

認証局の承認 (CAA) を使用している場合は、ルートドメインの letsencrypt.org アドレスの CAA レコードを追加して、Let's Encrypt 認証局がドメインの証明書を発行できるようにする必要があります。たとえば、letsencrypt.org にポイントするドメイン mydomain.com は、以下のようになります。

mydomain.com.  CAA 0 issue "letsencrypt.org"

DNS プロバイダーによっては、 0 issue "letsencrypt.org" フラグ、タグ、および値をルートドメインの CAA レコードの認証局リストに追加しなければならない場合があります。CAA レコードの設定方法は、お使いの DNS プロバイダーにお問い合せください。

10.2.3. Red Hat サポートへの問い合わせ

CNAME エントリーを追加し、オプションで CAA レコードを DNS 設定に追加したら、デベロッパーポータルのドメイン変更を要求するために Red Hat サポートケース を作成して以下の情報を指定する必要があります。

  • 「Red Hat 3scale API Management Platform」製品を選択します
  • ケースの説明には、以下を追加します。

    • 3scale アカウントの管理ポータルドメイン (例: mydomain-admin.3scale.net)。
    • デベロッパーポータルで使用するカスタムドメイン (例: developer.mydomain.com)。

チケットを送信すると、Red Hat サポートは DNS 設定を検証し、変更が適用されたら確認したことを通知するか、あるいは必要に応じて応答します。

10.2.4. デベロッパーポータルの確認

ドメインの変更に関する Red Hat サポートからの確認を受け取ったら、デベロッパーポータルを確認し、テストします。カスタムドメインへの非相対リンクが更新されていることを確認します。

第11章 Liquid: デベロッパーポータル

このセクションでは、マークアップのさまざまな要素、その要素のつながり、デベロッパーポータルでの使用方法の簡単な例など、Liquid フォーマットのタグおよびそれらが 3scale システム内で機能する仕組みについて説明します。

Liquid の基本を知るには、『Liquid Reference』を参照してください。

11.1. デベロッパーポータルでの Liquid の使用

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

11.1.1. Liquid の有効化

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

developer portal configuration liquids enable

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

11.1.2. ページ、パーシャル、およびレイアウトでの使用方法の違い

Liquid の使用方法は通常、ページ、パーシャル、およびレイアウトによって若干異なります。ページ内では、Liquid は使用が 1 回限りの要素ですが、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>

11.1.3. CSS/JS との使用

Liquid マークアップは HTML で機能するだけでなく、CSS や JavaScript コードと簡単に組み合わせて制御を強化することもできます。スタイルシートまたは JS で Liquid を有効にするには、これをページとして作成し、通常のページで有効にするのと同じ手順に従います。これにより、CSS に条件マークアップを追加することや、JavaScript でサーバー側のデータを使用することが可能です。ページのコンテンツタイプを CSS または JS として設定するのを忘れないでください。

11.2. メールテンプレートでの Liquid の使用

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

11.2.1. デベロッパーポータルでの使用との相違点

前述のように、Liquid タグを使用してユーザーに送信されるメールテンプレートをカスタマイズすることもできます。前述した Liquid を記述する際の一般規則は、すべてメールテンプレートにも適用されますが、一部の例外があります。

  • すべてのテンプレートで利用可能な、一般に共有される変数リストはありません。代わりに、前述の {% debug:help %} タグを使用してテストを行う必要があります。
  • 電子メールは本質的に Web ページとは異なるため、使用に制約のあるタグや使用できないタグがあります。たとえば、電子メールには URL がないため、{{ request.request_uri }} は意味を持ちません。

11.3. トラブルシューティング

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

11.3.1. デバッグ

正常に保存はされているが何かが意図したとおりに機能しない場合は、以下の点を確認してください。

  • すべてのタグが正しく閉じられていること。
  • 現在のページで利用可能な変数を参照していること。
  • 配列へのアクセスを試みていないこと (たとえば、current_account.applications はアプリケーションの配列です)。
  • 論理が正しいこと。

11.3.2. 典型的な誤りとその解決方法

  • Liquid エラーのためにドキュメントを保存できない原因は、通常タグまたはドロップが正しく閉じられていないことです。{% %} タグや {{ }} タグがすべて正しく閉じられていること、また iffor などの論理式が endifenfor などで正しく終了していることを確認します。この場合は通常、エディターの上のページ最上部に、エラーを説明するメッセージと共にエラーが表示されます。
  • すべてが正しく保存されているにも関わらずタグの効果が見られない場合、空の要素を参照していないか、また、コンテンツの表示に論理タグを使用していないかを確認します。すでにより複雑なタグとドロップのセットのエイリアスであるタグでの使用を除き、{% %} がコンテンツをレンダリングすることはありません。
  • # 記号のみが表示される場合は、表示しようとしている要素が配列であることを意味します。「Hierarchy」セクションを確認してください。

11.3.3. サポートへの問い合わせ

問題が解決しない場合は、Red Hat カスタマーポータル から新しいケースを作成することができます。

第12章 Liquid: メールテンプレート

3scale では、ご自分の組織独自のメッセージと用語を使用して、メールテンプレートをカスタマイズする機能を提供します。Liquid ドロップを活用して、各顧客に合わせてカスタマイズした情報を表示することもできます。

デベロッパーポータルで Liquid ドロップが使用されるのと同様に、各メールテンプレートには独自のコンテキストがあります。つまり、あるメールテンプレートで使用可能な Liquid ドロップが、他のメールテンプレートでも使用可能であるとは限りません。

本章では、内容ごとにグループ化されたメールテンプレートおよびそこでサポートされる Liquid ドロップのセットを使用して、どの Liquid ドロップをどこで使用できるのかについて概要を説明します。

12.1. アカウント管理

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

  • Buyer Account confirmed
  • Buyer Account approved
  • Buyer account rejected

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

  • user ⇒ User
  • domain ⇒ String
  • account ⇒ Account
  • provider ⇒ Provider
  • support_email ⇒ String

また、テンプレート

  • Password recovery for buyer

    これらの Liquid ドロップへのアクセスがあること。

  • user ⇒ User
  • provider ⇒ Provider
  • url ⇒ url

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

  • Invitation

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

  • account ⇒ Account
  • provider ⇒ Provider
  • url ⇒ url

12.2. クレジットカードに関する通知

  • Credit card expired notification for provider
  • Credit card expired notification for buyer

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

  • user_account ⇒ Account
  • account ⇒ Account
  • provider_account ⇒ Provider
  • provider ⇒ Provider

12.3. 制限に対するアラート

  • Alert notification for provider (>= 100%)
  • Alert notification for buyer (>= 100%)
  • Alert notification for provider (< 100%)
  • Alert notification for buyer (< 100%)

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

  • application ⇒ Application
  • account ⇒ Account
  • provider ⇒ Provider
  • service ⇒ Service
  • alert ⇒ Alert

12.4. アプリケーション

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

  • Application created for provider

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

  • url ⇒ url

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

  • Plan change request for buyer
  • Plan change request for provider

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

  • application ⇒ Application
  • provider ⇒ Provider
  • account ⇒ Account
  • user ⇒ User
  • plan ⇒ Plan
  • credit_card_url ⇒ credit_card_url

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

  • Application plan changed for buyer
  • Application plan changed for provider
  • Application trial period expired for buyer

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

  • provider ⇒ Provider
  • account ⇒ Account
  • user ⇒ User
  • plan ⇒ Plan

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

  • Application suspended for buyer
  • Application accepted for buyer
  • Application rejected for buyer
  • Application contract cancelled for provider

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

  • application ⇒ Application
  • service ⇒ Service

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

  • Application key created for buyer
  • Application key deleted for buyer
  • key ⇒ key

12.5. 請求

メールテンプレート

  • Review invoices prior to charging for provider

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

  • provider ⇒ Provider
  • url ⇒ String>

また、テンプレート

  • Invoice charge failure for provider without retry
  • Invoice upcoming charge for buyer
  • Invoice charge failure for provider with retry
  • Invoice charge failure for buyer without retry
  • Invoice charged successfully for buyer
  • Invoice charge failure for buyer with retry

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

  • account ⇒ Account
  • provider ⇒ Provider
  • cost ⇒ cost
  • invoice_url ⇒ invoice_url
  • payment_url ⇒ payment_url

12.6. サービス

メールテンプレート

  • Service contract cancelled for provider
  • Service trial period expired for buyer
  • Service plan changed for provider
  • Service contract suspended for buyer

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

  • provider ⇒ Provider
  • account ⇒ Account
  • user ⇒ User
  • plan ⇒ Plan

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

  • Service created for provider
  • Service accepted for buyer
  • Service rejected for buyer

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

  • service ⇒ Service
  • service_contract ⇒ Contract
  • subscription ⇒ Contract

12.7. サインアップ

メールテンプレート

  • Sign-up notification for provider
  • Sign-up notification for buyer

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

  • user ⇒ User
  • provider ⇒ Provider
  • url ⇒ activate_url

第13章 デベロッパーポータルのレイアウトのカスタマイズ

実際のブランディングに合わせて、デベロッパーポータル全体の外観や操作感をカスタマイズできます。カスタマイズを簡単に行うための出発点として、標準の CSS スタイルシートを使用できます。

このチュートリアルでは、デベロッパーポータルに独自の CSS カスタマイズを追加し、リロードして新しいスタイルの変更を反映させる方法について説明します。

13.1. 新規 CSS ファイルの作成

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

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

13.2. ページレイアウトへのスタイルシートのリンク

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

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

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

第14章 組み込みページの変更

本章では、システム生成ページの任意の要素を変更または表示/非表示にする方法について説明します。

システムによって生成される要素には、Signup、Dashboard、Account ページなど、デベロッパーポータルから変更できないものがあります。本ガイドでは、CSS および Javascript を使用してこれらのページのコンテンツをカスタマイズする方法について説明します。

注意

3scale のシステム生成ページは、変更の対象です (ただしまれです)。これらの変更により、本ガイドに従って実装するカスタマイズが機能しなくなる可能性があります。これらの変更手法を使用せずに済む場合は、使用を避けてください。設定変更を続行する前に、サービスの提供を阻害する変更を識別し、ポータルの機能を正常な状態に維持するのに必要なメンテナンス作業を実施できることを確認してください。

14.1. 要素の特定

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

Developer portal modify built-in pages CSS

14.2. 要素の変更または非表示

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

14.3. オプション A: CSS

たとえば、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;
}

14.4. オプション B: jQuery

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

#three-scale #submenu li a

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

Developer portal modify built-in pages

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

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

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

第15章 Webhook

本章では、デベロッパーポータル で Webhook を設定し、操作を行う方法について説明します。

Webhook を使用すると、3scale をバックオフィスのワークフローと密接に連携させることができます。3scale システムで指定のイベントが発生すると、Webhook メッセージによりアプリケーションに通知が届き、新規アカウントのサインアップからのデータなどを使用して、デベロッパーポータルに反映させることができます。

15.1. Webhook の概要

Webhook は、Webhook 設定ウィンドウで利用可能なイベントから選択されたイベントによってトリガーされるカスタム HTTP コールバックです。これらのイベントのいずれかが発生すると、3scale システムは、Webhook セクションで指定した URL アドレスに対して HTTP または HTTPS リクエストを行います。API プロバイダー側では、リスナーを設定してイベント追跡などの目的の動作を呼び出すことができます。

Webhook を設定するには、以下の手順を実施します。

  1. Account Settings > Integrate > Webhooks の順に移動します。Account Settings は、ウィンドウの右上にある歯車アイコンです。
  2. Webhook の動作を指定します。2 つのオプションがあります。

    • Webhooks enabled: Webhook を有効または無効にするには、このチェックボックスを選択します。
    • Actions in the admin portal also trigger webhooks: イベント発生時に Webhooks をトリガーするには、このチェックボックスを選択します。以下の点を考慮してください。

      • トリガーとなるイベントが設定された内部 3scale API への呼び出しを行う場合は、プロバイダーキーではなくアクセストークンを使用します。
      • このチェックボックスを選択しないままにすると、デベロッパーポータルのアクションだけが Webhook のトリガーになります。
  3. 選択したイベントがトリガーとなった際にイベントを通知するための URL アドレスを指定します。
  4. 指定した URL アドレスへのコールバックのトリガーとなるイベントを選択します。

設定が完了したら、Update webhooks settings をクリックして変更を保存します。

15.2. 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>

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

  • <type>: applicationaccount など、イベントの主体を表します。
  • <action>: updatedcreateddeleted などの値を使用してアクションを指定します。
  • <object>: Account Management API によって返される、同じフォーマットの XML オブジェクト自体です。インタラクティブな ActiveDocs を使用して確認できます。

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

15.3. トラブルシューティング

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

  • 配信に失敗した Webhook の一覧
  • 配信に失敗した Webhook の削除

第16章 契約条件の設定

開発者がご自分の API にサインアップするのを許可する場合、アクセス権限を付与する前に開発者に契約条件に同意してもらい、ポリシーを明確にする必要が生じます。

開発者に守ってもらう契約条件には、さまざまなバージョンが存在する可能性があります。これらは、登録プロセス中のさまざまなステップで簡単に設定できます。以下に例を示します。

  1. サインアップの契約条件
  2. アプリケーションの契約条件
  3. サービス/サブスクリプションの契約条件 (複数のサービスがある場合のみ利用可能)

さらに、API の使用を有料にする場合は、クレジットカードポリシーを明示しなければならない場合があります。3scale では、以下のようなクレジットカードポリシーの URL を簡単に設定することができます。

  1. 法律上の条件
  2. プライバシー
  3. 払い戻し

16.1. 契約条件

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

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

Developer legal terms

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

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

Developer accept terms

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

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

16.2. クレジットカードポリシー

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

Developer policy urls

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

Developer portal policy and terms

完了したら、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>

これで完了です。

第17章 要約: デベロッパーポータルのビギナーからエキスパートに

API 開発のベストプラクティスの調査からは、適切な構成のデベロッパーポータルと優れたドキュメントが、確実に API を利用してもらうための鍵であることが分かっています。デベロッパーポータルは、単なるドキュメントのソースではありません。開発者とのやり取りを管理するためのメインハブでもあり、また開発者はデベロッパーポータルを通じて API キーにセキュアにアクセスすることができます。

17.1. 目的

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

17.2. デベロッパーポータルの設定

17.2.1. ポータルのコンセプトのプランニング

初期の段階から、デベロッパーポータルの概念をプランニングすることを推奨します。プランで考慮すべき最も重要な要素には以下が含まれます。

  • サイトマップ: ポータル構造の骨格
  • トップメニューバー: すべてのページで繰り返し表示されるナビゲーション
  • サイドメニューバー: 各セクション内の個々のページへのアクセス用
  • ページレイアウトのガイドライン: ポータルの外観と操作感に一貫性を持たせる

17.2.2. 編集環境の設定

編集環境に最適なセットアップは、以下のとおりです。

  • 管理者クレデンシャルでログインする yourcompany-admin.3scale.net/p/admin/cms を示すタブ。ポータルのデベロッパーポータルにアクセスすることができます。
  • ポータルの公開ビューである yourcompany.3scale.net をポイントする別のタブ (Site リンクでこれにアクセスする場合、アクセスコードを心配する必要はありません)。

管理パネルでは、左側のサイドバーにデベロッパーポータルの要素がすべて表示されます。

Developer Portal home page

17.2.3. ページレイアウトテンプレートの定義

一般的な考え方としては、ポータルのさまざまなページスタイルごとに、個別のレイアウトを定義します。設定開始時には、「main layout」という 1 つの標準レイアウトがあります。このレイアウトはすべてのシステム生成ページで使用されるので、デベロッパーポータルの使用に十分に慣れるまでは、何も変更すべきではありません。通常、ご自分のポータルのホームページには固有のスタイルが必要になります。

  1. main layout テンプレートが、カスタマイズの出発点となります。新しいレイアウトを作成し、main layout のコンテンツをコピーしてそこに貼り付けます。

    Developer Portal Layouts
  2. 「home layout」から以下の行を削除して、サイドバーメニューを削除します。

    {% include 'submenu'%}
    Developer Portal Layouts edit

17.2.4. ページ階層の作成

  1. サイトマップのルートレベルから始め、各トップメニュー項目に対して新しいセクションを追加します (右側の「new」ボタンを展開してセクションを追加します)。タイトル、親セクション、およびパスを割り当てます。

    Developer Portal Sitemap
  2. セクションの追加と同様に、ページを追加します。URL パスの構造に一貫性を持たせるため、目的のセクションを選択します。次に、ページで使用するレイアウトを選択します。ページコンテンツが完成したら、「Create Page」をクリックします。多くのコンテンツを作成する場合は、Textile や Markdown などのマークアップ言語の使用が望ましい可能性があります (高度なページ設定で選択できます)。

    Developer Portal Sitemap new page
  3. ドラフトのプレビューを表示し、満足のできる公開バージョンができるまで、ページコンテンツを改良します。

    Developer Portal publish page
  4. セクションのすべてのページに対して手順を繰り返します。
  5. 次に、サイトのすべてのセクションに対して手順を繰り返します。

17.2.5. ページヘッダーの編集

ヘッダーやフッターなどの繰り返し表示されるページ要素は、すべてポータルのデベロッパーポータルの「Partials」というセクションで定義されます。レイアウトが 1 つしかない場合、あるいは極めて少ない場合は、レイアウトコード内にヘッダーとフッターを含めることで、この手順を省略することができます。ただし、レイアウトでこれらの要素をカスタマイズするのを忘れないでください。たとえば、デフォルトの「menu」パーシャルを、実際のサイトマップに対応するように編集する必要があります。

Developer Portal Partials

17.2.6. イメージおよび他のアセットの追加

イメージまたは他のファイルについては、まずファイルをコンテンツライブラリーに読み込み、次にリンクをテキストコンテンツに挿入します。

  1. ファイルを選択するために New File を選択し、これをサイト内のどこに保存するかを指定します。
  2. イメージの URL をコピーします。
  3. これで、HTML または <a> タグを追加して、イメージの URL に貼り付けることができます。
Developer Portal add image

17.2.7. ブランディングを使用したカスタマイズ

デフォルトの default.css というスタイルシートがありますが、これは非常に大きく複雑です。これを拡張するよりも、カスタム設定で専用のスタイルシートを作成し、デフォルトを上書きする方が適切です。

ページの作成と同じ方法で、新しいスタイルシートを作成することができます。高度なページ設定で適切な MIME コンテンツタイプを選択するのを忘れないでください。次に、レイアウトテンプレートで、default.css へのリンクの後にカスタム CSS へのリンクを追加します (以下に例を示します)。

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

17.2.8. 実稼働環境への移行

最後のタスクは、ポータルサイト全体を調べ、すべてのワークフローを確認することです。各ページまたは Changes セクションのすべてのページを公開できます。すべて問題がなければ、すべてのページが公開されていることを最終確認します。

これで、ポータルのアクセスコードを削除する準備ができました。

Developer portal access code

お疲れさまでした。これでデベロッパーポータルが公開され、開発者コミュニティー構築を支援する準備が整いました。

17.3. デベロッパーポータルの追加設定オプション

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

法律上の通知

Copyright © 2021 Red Hat, Inc.
The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, the Red Hat logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
Node.js® is an official trademark of Joyent. Red Hat is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.