管理ポータルガイド

新しいアカウントを作成したら、上部のナビゲーションバーにある歯車のアイコンをクリックし、アカウント → 概要 をクリックして、詳細 項目の 編集 をクリックします。アカウントの情報を入力します。

ここに入力する住所は、請求目的で使用されるもの (有料プランの場合) であり、請求および支払いモジュールを使用している場合は、ユーザーが請求書に表示するものでもあります。

同じページで、すべてのシステム画面で使用されるタイムゾーンを選択することもできます。解析のグラフには、この設定が反映されます。ただし、請求サイクルの計算は UTC 時間に従って処理されます。

3scale では、メンバーおよび管理者に対するシングルサインオン (SSO) 認証がサポートされます。

3scale 管理ポータルでは以下の SSO プロバイダーがサポートされ、それぞれさまざまな ID ブローカリングおよびメンバーフェデレーションオプションに対応しています。

RH SSO または Auth0 に追加されているユーザーだけが、SSO を通じて 3scale 管理ポータルにアクセスすることができます。ロールまたはユーザーグループによりさらにアクセスを制限する場合には、RH SSO または Auth0 のサポートポータルで、該当するステップバイステップのチュートリアルを参照してください。

選択したプロバイダーで SSO を確立したら、それを 3scale 管理ポータルで設定して有効にする必要があります。

SSO を設定したら、メンバーは接続された IdP のアカウントクレデンシャルを使用してサインオンすることができます。

SSO を使用して 3scale 管理ポータルにログインするには、以下の手順に従います。

サインアップに成功すると、API プロバイダー組織下にメンバーアカウントが作成され、自動的にログインされます。

以下の手順により、3scale API Management の管理者に、アイデンティティープロバイダー (IdP) のログイン画面 (RH SSO) にリダイレクトする方法を説明します。以下の手順を完了すると、オプションのシングルサインオン (SSO) のログインページを通じてご自分の 3scale アカウントにアクセスすることができます。

管理ポータルのトップナビゲーションバーで、歯車のアイコンをクリックします。左側のメニューから、Users > Listing の順に移動します。

ユーザーとは、チームのメンバーのことです。3scale 管理ポータルには、2 種類のユーザーが存在します。

メニューから ユーザーを招待 リンクをクリックします。

招待状は ユーザー > 招待 状 で見つけることができます。

招待するユーザーのメールアドレスを入力し、send をクリックします。入力したアドレスに招待メールが送信されます。メールが届かない場合は、スパムとしてマークされていないことを確認してください。

新たな管理者またはメンバーは、招待メールのリンクをクリックし、フォームに入力してプロセスを完了する必要があります。フォームが送信されると、アカウントがアクティブになります。

チームメンバーへの権限付与には、大きく分けて 2 つのタイプがあります。

新しいユーザー権限を付与するには、ユーザーメニューからユーザーを選択し、Edit をクリックしてそのユーザーを編集します。

ユーザーのロールを admin に変更すると、管理ポータルを制御するためのフルアクセス権限が付与されます。

ユーザーのロールを member に変更すると、さらにチームメンバーがアクセス権限を持つ機能およびサービスを選択することができます。

管理ポータルの特定機能へのアクセス権限を付与すると、メンバーには該当する API へのアクセス権限だけが与えられます。

以下に示すように、通知にはさまざまなタイプがあります。

管理ユーザーは、すべての通知に対するアクセス権限を持ちます。

メンバーユーザーは、アクセス権限が付与されている機能に関する通知にしかアクセスすることができません。たとえば、メンバーに請求機能へのアクセス権限が付与されている場合には、そのメンバーは請求に関する通知にのみアクセスすることができます。

Enterprise アカウント の場合には、メンバーユーザーは、アクセス権限が付与されているサービスの活動に関する通知にしかアクセスすることができません。

サブスクリプションは個人的な設定で、これらの通知を受け取るユーザーだけが変更可能です。ご自分のサブスクリプションを編集するには、以下の手順を実施します。

電子メール通知に加えて、これらはダッシュボードで見つけることができます:

ここから 3 つのタイプの設定を編集することができます。

アクセストークンにより、API プロバイダーの管理者およびメンバーは、3scale API (Billing、Account Management、および Analytics) に対する認証を行うことができます。トークンは、ActiveDocs (インタラクティブドキュメント) 内から使用します。

アクセストークンにより、読み取り/書き込みアクセス権限、または読み取り専用アクセス権限のいずれかが許可されます。

考慮すべき重要なことは、メンバーの権限に応じてアクセストークンの機能する仕組みが変わるという点です。管理者は、3 つすべての 3scale API に対する認証を行うためのトークンを作成することができます。メンバーの場合には、アクセス権限を持つ管理ポータル機能によって作成できるトークンが制限されます。たとえば、請求機能に対するアクセス権限を持たないメンバーは、Billing API に対する認証を行うためのトークンを作成することができません。

アクセストークンは、Tokens のページで作成することができます。トークンページにアクセスするには、ページの右上隅にある歯車アイコンをクリックし、Personal > Tokens に移動します。

Add Access Token を クリックし、名前、スコープ、およびアクセス許可を選択します。

メンバーの場合には、すべての API が表示されるとは限らない点に注意してください。アカウントの管理者からアクセス権限が付与された API だけが表示されます。

アクセストークンは必要な数だけ作成できますが、セキュリティー上の理由から、それらは 3scale に保存されないことを考慮してください。新しいトークンを作成すると、トークンを保存するように要求されます。保存したそのトークンを使用して、3scale API にリクエストを行うことができます。トークンを紛失した場合には、トークンを削除することを推奨します。これにより、トークンが無効になり、効力が無くなります。その後、新しいトークンを作成します。

アクセストークンを使用して 3scale API を呼び出すと、アクセス権限のあるサービスによって結果が絞りこまれます。

たとえば、Self-managed APIcast をデプロイする場合、APIcast API ゲートウェイが Account Management API を使用してサービスの設定をプルできるように、アクセストークンが必要になります。

アクセストークンが機能する仕組みは、以下のとおりです。ご自分の組織が 3scale で 3 つのサービスを設定していると仮定します。メンバーであるあなたは、サービス 1 へのアクセス権限はあるが 2 および 3 へのアクセス権限はありません。また Account Management API へのアクセス権限があります。この場合には、トークンを作成して Account Management API にリクエストを行うと、サービス 1 を使用するアプリケーションだけを取得することができます。

同じ例において、Account Management API へのアクセス権限はあるがどのサービスへのアクセス権限も持たない場合には、呼び出しを行うと access denied エラーが返されます。

6.3.1. サービストークン

サービストークンを使用して、3scale Service Management API に対する認証を行います。サービストークンは、3scale で新規サービスを作成する際に自動的に生成され、サービスごとに固有です。このトークンは、3scale アカウントのユーザー間で共有されます。管理ポータルの Dashboard で、ユーザーがアクセス権限を持つサービスのサービストークンを確認することができます (Account Settings (歯車アイコン) > Personal > Tokens)。

マスター管理者は、マスター管理ポータルおよび API エンドポイントを通じて 3scale アカウントを監視および管理します。標準の 管理ポータル (Admin Portal) と同様に、マスター管理ポータルにはデプロイメント内のすべてのアカウントに関する情報が含まれ、固有のアカウントページでアカウントおよびユーザーを管理することできます。

アカウント管理者の操作に関する詳細は、アカウント設定 を参照してください。

7.1.1. マスター管理ポータルへのアクセス

マスター管理ポータルにアクセスするには、オンプレミスへのインストール プロセス中に特別にマスター管理ポータル用として定義したクレデンシャルおよび URL を使用する必要があります。

マスター管理ポータルの URL は、MASTER_NAME (テンプレートのデフォルトでは master) および WILDCARD_DOMAIN で設定されます。

<MASTER_NAME>.<WILDCARD_DOMAIN>

マスター管理ポータルは、Master フラグで識別することができます。

マスター管理ポータルから、または API コールを使用して、アカウントを管理することができます。

7.2.2. API コールを使用したアカウントの管理

マスター管理 API コールを使用して、アカウントを管理することができます。この呼び出しの詳細については、マスター管理ポータルの右上隅にある疑問符 (?) アイコンをクリックして 3scale API Docs を選択し、Master API セクションを参照してください。

同じ OpenShift クラスタードメインに複数のアカウントが存在することから、サブドメインとして、個々のアカウントの名前には OpenShift クラスターのドメイン名が付加されます。たとえば、ドメインが example.com のクラスター上の user という名前のアカウントのルートは、以下のようになります。

user.example.com

標準的なマルチテナントのデプロイメントには、以下の要素が含まれます。

マスター管理ポータルから追加した 追加アカウントには、その名前に応じたサブドメインが割り当てられます。

テナントアカウントを復帰させると、削除をスケジュールしたアカウントが元の状態に戻ります。アカウントの削除をスケジュールしてから 15 日間は、テナントアカウントを復帰させることができます。

アカウントの復帰後は、以下のような状態になります。

サービスディスカバリーを使用すると、同じ OpenShift クラスター内で実行されている検出可能な API サービスの有無をスキャンし、関連する API 定義を 3scale に自動的にインポートすることができます。

いつでも API インテグレーションおよび OpenAPI Specification を更新して、再度それらをクラスターと同期することもできます。

サービスディスカバリーにより、以下の機能を利用することができます。

検出可能なサービスをインポートする場合には、その namespace が維持されます。

3scale の管理者は、OAuth サーバーの使用/不使用とは独立に、サービスディスカバリーを設定することができます。

3scale を使用した管理のために、OpenAPI Specification (OAS、Swagger 仕様とも呼ばれる) に対応する新しい API サービスを検出することができます (該当する場合には、クラスターから検出されます)。

OAuth トークンが有効ではない場合、OpenShift プロジェクトの管理者は 3scale ユーザーが namespace にアクセスするのを承認することができます。

3scale の既存 API サービスを、クラスターの最新サービス定義で更新 (リフレッシュ) することができます。

メソッドの定義は、後で変更することができます。メソッド名をクリックし (Method 列)、フィールドを更新して Update Method をクリックするだけです。

メソッドとメトリクスのシステム名を変更したり、それらを削除したりする場合は十分に注意してください!メソッドの以前のシステム名を指すマッピングルールがある場合、すでにデプロイメントされている 3scale 統合が壊れる可能性があります。

新しいメトリックを作成するには、新しいメトリックをクリックし、必要なパラメーターを指定します。単位を指定するときは、Analytics グラフで自動的に複数形になるため、単数形の名詞 (hit など) を使用します。

これらの新たなメソッドおよびメトリクスは、現在および今後のすべてのプランで使用することができます。Your_API_service > Applications > Application Plans > plan_you_want_to_edit に移動して、各プランの制限と価格設定ルールを編集できるようになりました。

API に多数のエンドポイントがある場合、3scale では新たな 2 つの手法でメソッドおよびメトリクスを自動的に作成することができます。

デフォルトでは、3scale アカウントが作成されると、Basic および Unlimited の 2 つのプランが設定されます。これらのプランを維持して編集することも、専用のプランを作成することもできます。必要な数だけプランを作成することができます。

新たなアプリケーションプランを作成するには、以下の手順に従います。

次の画面で、新しいプランの名前とシステム名 (システム名は一意である必要があります) を選択します。アプリケーションに承認が必要な場合は? チェックボックスが選択されている場合、アプリケーションは承認なしで API にアクセスできません。

プランを作成したら、流量制御 をプロビジョニングし、有料プラン を設定することができます。

すべてのプランを作成したら、ユーザーがサインアップしてアプリケーションを登録する際のデフォルトプランを選択することができます。これを行うには、Your_API_service > Applications > Application Plans に移動し、デフォルトプランを選択します。

デフォルトのアプリケーションプランを指定しない場合、新しいユーザーがサインアップして API にアクセスするときに、デフォルトではアプリケーションが作成されません (つまり、実際には API にアクセスできません)。

初めに決めなければならないことは、課金モデルでレイヤー間を区別する方法です。レベルはボリューム/使用量、API 機能、他のリソースへのアクセス、またはそれらの組み合わせによって決まりますか?

課金ドライバーを決定したら、レイヤーが定額サブスクリプション、変動レート、または 1 回限りの前払い料金のいずれに基づくかを決定する必要があります。上記の 3 つの課金ドライバーは、すべて 1 回限りの前払い料金または 1 カ月の定額サブスクリプションに対応しています。ヒット数またはリソースの消費量に基づいて課金することを選択した場合には、当然課金は変動要素を持ちます。

新たなアプリケーションプランを作成することも、既存のプランを編集することもできます。新規アプリケーションプランを作成する場合には、前払い料金または定額サブスクリプションを自由に設定することができます。

アプリケーションの編集ビューで、前払い料金および定額サブスクリプションを入力または変更することができます。

次に、ステップ 1 で決定した価格決定要因を設定します。それらの一部がメトリックとしてすでに存在する場合は、アイテムを編集するだけです。

価格設定ルールの設定が完了したら、必ずアプリケーションプランの更新 をクリックしてください。

単一のアプリケーションプランで API の有料プランを定義することもできます。すべての課金ルールがボリュームまたはリソースドライバーにより定義される場合は、通常これに該当します。ただし、開発者コミュニティーのさまざまなセグメントに個別のプランを提供する場合は、さらにアプリケーションプランを追加する必要があります。

そのための最も簡単な方法は、最初のアプリケーションプランをアプリケーションプランの概要ページからコピーすることです。これにより、既存のメトリクスおよび課金ルールが、すべて事前に入力されます。最初に完全なプランを作成するのに多くの注意を払うほど、プランのコピー機能により多くの時間を節約することができます。

プランをプロビジョニングするには、開発者は新しいアプリケーションを作成し、新しい有料プランの 1 つを選択する必要があります。管理コンソールから、開発者に代わってこの作業を行うこともできます。既存のアプリケーションに関して、既存のプランから新しい有料プランのいずれかに変更することもできます。

定額の課金プランに加えて、流量制御を使用してレイヤー間を区別するのも一般的です。これについては、流量制御のプロビジョニング で説明します。

アプリケーションプランをまだ定義していない場合には、まず始めにプランを作成します。定義している場合には、流量制御を設定するプランを選択して、edit をクリックします。

必要な制限の設定が完了したら、Update Application plan をクリックして変更を保存します。

流量制御を定義したので、以下のような状況になります。

流量制御が有効になると、ダッシュボードに制限に達しつつあるユーザーが表示され、プランをアップグレードする可能性のあるユーザーをすばやく簡単に確認することができます。

流量制御を設定する以外に、同じメトリクスに対して変動課金ルールを設定することもできます。有料プランのプロビジョニング を参照してください。

3scale での請求は暦月に基づき、前払い および 後払い の設定が可能です。

詳細は、自動請求プロセス を参照してください。

この設定により、クレジットカードを使用した支払いが有効になります。このチェックボックスが選択されていると、期限を迎えたすべての請求書に対する課金が、選択した支払いゲートウェイを使用して行われます。このチェックボックスを未選択のままにすると、請求が行われ請求書は発行されますが、実際の支払い行為は発生しません。

請求およびクレジットカードによる支払いを行う際の通貨を選択します。選択した通貨が支払いゲートウェイでサポートされていることを確認してください。これはグローバルな設定で、すべての請求書および支払いに適用されます。開発者アカウントごとに異なる通貨を設定することはできません。

Invoice footnote フィールドに入力されたテキストは、すべての PDF ファイルの請求書の最下部に表示されます。このフィールドを使用して、顧客の課金および請求ポリシーに関する補足情報を提供することができます。

脚注のテキストが変更されても、PDF ファイルがすでに生成されている請求書には自動的に適用されません。ただし、請求書の PDF ファイルを再生成することにより、変更を適用することが可能です。

請求を行うアカウントの VAT/消費税が 0% の場合に、このフィールドを使用して PDF ファイルの請求書にテキストメッセージを追加します。この行は、VAT/消費税が明示的に 0 に設定されている場合にのみ表示され、それ以外の場合には表示されません。このテキストは、管理ポータルの Invoice のページにも表示されます。

この設定の詳細は、VAT/消費税セクション をご覧ください

3scale の請求書には、2 種類の ID があります。

以下の設定により、請求書の平易な ID のフォーマットを定義します。

Billing periods for invoice ids を monthly から yearly に変更しても、平易な ID のフォーマットが変わるだけで、請求サイクルの期間は変更されません。3scale API Management では、月ごとの請求サイクルしかサポートされません。経理部門からそのような指示があった場合には、請求書 ID のフォーマットを yearly に変更します。

顧客に対して年額の課金を行う必要がある場合には、請求を手作業で処理する必要があります。新たな請求書を作成し、年額の費用項目を追加することができます。年額の課金を希望する場合には、毎月請求書の生成や課金が自動的に行われないように、アプリケーションプランを無料に設定する必要もあります。

ここでは、以下のページへのパスを設定することができます。

3scale では、クレジットカードによる支払いに関して以下の支払いゲートウェイとのインテグレーションが提供されます。

14.8.1. Stripe インテグレーション (推奨)

以下の手順により、アカウントの支払いゲートウェイとして Stripe を設定する方法を説明します。これにより、開発者は自分のクレジットカード情報を入力し、お客様は API へのアクセスに対する課金を計算された請求書に従って Stripe を通じて自動的に行うことができます。

有料 API 用にクレジットカードへの課金を有効にする場合、主要なステップの 1 つは 支払いゲートウェイ を設定することです。3scale アカウントで使用することのできる支払いゲートウェイは多数あります。ここでは、Stripe に関する手順を説明します。

14.8.1.1. 前提条件

以下の手順を始める前に、Stripe のアカウントを作成する必要があります。

14.8.1.2. Stripe からの API キーの取得

Stripe アカウントにログインし、https://dashboard.stripe.com/account/apikeys で API キーを取得します。秘密鍵および公開鍵の 2 つの鍵が必要です。テストを行う場合にはテストセットを使用し、課金を開始する準備ができたらライブセットを使用します。

14.8.1.3. 3scale 設定の定義

これらの API キーの使用を開始するように 3scale を設定する必要があります。そのためには、3scale 管理ポータルにログインし、Audience > Billing > Charging & Gateway の順に移動します。

Charging enabled のチェックボックスが選択されていない場合には、選択して Save をクリックします。

ページ最下部近くの Gateway セクションに、ドロップダウンが表示されるはずです。それを Stripe に変更します。

ドロップダウンの下のフォームが変わり、2 つのフィールドが表示されるはずです。Stripe の API キーを入力し、Save をクリックします。

支払いゲートウェイを変更すると、いくつかの警告が表示される場合があります。これは想定される状況です。表示されたら、警告を読んで了承してください。

これで支払いゲートウェイは設定されましたが、CMS では設定されていないため、ユーザーはまだ使用できない可能性があります。デベロッパーポータルに移動し、左側のナビゲーションペインでテンプレート Payment Gateway および Show をクリックします。

{% when "braintree_blue" %} の前に以下のコードがまだ表示されていない場合には、コード追加します。

{% when "stripe" %}
 <p><a href="{{ current_account.edit_stripe_billing_address_url }}">Edit billing address</a></p>

 {% if current_account.has_billing_address? %}
   {% stripe_form "Edit Credit Card Details" %}
 {% else %}
   <p>After entering billing address, the option to enter credit card will be enabled.</p>
 {% endif %}

最後に、Save および Publish をクリックします。これで、ユーザーは Stripe ゲートウェイを使用して費用を支払うことができるはずです。

注記

Stripe からのデータを 3scale のデータとマッピングするには、Stripe フィールド metadata.3scale_account_reference を使用することができます (設定は 3scale-[PROVIDER_ID]-[DEVELOPER_ACCOUNT_ID])。

14.8.2. Braintree の統合

API の使用に対する課金を行うために Braintree ゲートウェイを設定する手順を以下に示します。

14.8.2.1. Braintree からの API キーの取得

Braintree のアカウントを作成する必要があります。Gateway および Merchant アカウントならびに Vault が必要です。オプションとして、支払い方法として American Express カードを許可する選択が可能です。

まず初めに、Braintree アカウントにログインします。次に、Account > MyUser セクションでご自分の API キーを探します。

API キーのページではまだ秘密鍵は非表示の状態なので、表示するオプションを選択します。

最終的に、公開鍵、秘密鍵、および業者 ID が得られます。これらの情報が 3scale の請求設定で必要です。

14.8.2.2. 3scale 設定の定義

これらの API キーの使用を開始するように 3scale を設定する必要があります。そのためには、3scale 管理ポータルにログインし、Audience > Billing > Charging & Gateway の順に移動します。

請求のページで指定した通貨のタイプが、Braintree の業者アカウントで使用される通貨のタイプと一致するようにしてください。

Charging enabled のチェックボックスが選択されていない場合には、選択して Save をクリックします。

ページ最下部近くの Gateway セクションに、ドロップダウンが表示されるはずです。それを Braintree (Blue Platform) に変更します。

ドロップダウンの下のフォームが変わり、2 つのフィールドが表示されるはずです。Braintree のキーを入力し、Save をクリックします。

支払いゲートウェイを変更すると、いくつかの警告が表示される場合があります。これは想定される状況です。表示されたら、警告を読んで了承してください。

これで、ユーザーは Braintree ゲートウェイを使用して費用を支払うことができるはずです。

注記

Braintree からのデータを 3scale のデータとマッピングするには、Braintree フィールド customer.id を使用することができます (設定は 3scale-[PROVIDER_ID]-[DEVELOPER_ACCOUNT_ID])。

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

アカウントがサンドボックスモードにあり、何らかの問題が発生した場合には、実稼働モードに変更する必要があります。

14.8.3. 非推奨の支払いゲートウェイ

このセクションでは、非推奨となった支払いゲートウェイ Adyen に関する一般的な情報を提供します。ここで説明する情報は、既存のインテグレーションだけが対象です。これらのゲートウェイとの新たなインテグレーションはサポートされません。

14.8.3.1. Adyen インテグレーション

重要

Adyen インテグレーションは非推奨となりました。新たなインテグレーションはサポートされません。2019 年 8 月 22 日より前に存在していたインテグレーションについては、Red Hat ではサポートを提供しますが、完全にサポートされる支払いゲートウェイ (Stripe および Braintree) のいずれかに移行することを推奨します。

以下の手順により、アカウントの支払いゲートウェイとして Adyen を設定する方法を説明します。これにより、開発者は自分のクレジットカード情報を入力し、お客様は API へのアクセスに対する課金を計算された請求書に従って Adyen を通じて自動的に行うことができます。

有料 API の使用に対してクレジットカードへの課金を有効にする場合、支払いゲートウェイを設定することが主要なステップです。3scale アカウントで使用することのできる支払いゲートウェイは多数あります。ここでは、Adyen に関する手順を説明します。

14.8.3.1.1. 前提条件

• 以下の手順を始める前に、Adyen のアカウントを作成する必要があります。
• そのサブアカウントとして、Company アカウントおよび Merchant アカウントが必要です。
• Adyen のライブアカウントを申請するには、満たさなければならない要求事項が多数あります。要求事項の詳細については、こちら をご確認ください。
• アカウントは実稼働モードでなければなりません。

14.8.3.1.2. Adyen インテグレーションの設定

Adyen アカウント情報の確認

1. まず初めに、Adyen アカウントにログインします。次に、Settings > Users セクションでご自分のクレデンシャルを探し、以下に示すビューのドロップダウンメニューから System を選択します。

2. Company アカウント (リストの一番上にあるアカウント) をクリックします。これにより、Company アカウントの設定ビューに移動します。

3. こうして、ログイン名、シークレットパスワード、クライアント暗号化用公開鍵、業者 ID、および ライブラリーの場所 を把握することができます。これらの情報が 3scale の請求設定で必要です。
4. 公開鍵 を表示するには、Generate Password をクリックしてこのパスワードをどこかにコピーする必要があります。

3scale アカウントでの支払いゲートウェイの設定

1. Audience > Billing > Charging & Gateway の順に移動し、チェックボックスを選択してクレジットカードへの課金を有効にし、Save をクリックします。
2. Adyen ゲートウェイへのリンクを作成するために設定しなければならないフィールドが、すべて表示されます。
3. Gateway のドロップダウンメニューから Adyen を選択し、変更を保存する必要があります。

Adyen API レスポンスでの alias 追加データの有効化

デフォルトでは、クレジットカード承認リクエストが 3scale から Adyen に送信されると、返されるレスポンスにはクレジットカードの一意の識別子は含まれません。

正しいクレジットカードの参照が 3scale に保存され、正しいカードに課金が行われるようにするには、この追加データを有効にする必要があります。

Adyen のサポートに連絡し、承認リクエストのレスポンスで alias 追加データを有効にします。

請求ワークフローのテスト

1. 前払いモード を有効にして 1 日程度で請求書が生成されるようにし、テストサイクルを短縮します。

2. 続いて、既存のテスト用アカウントを選択し、請求用の費用項目を追加して請求書を作成します。

   1. 直ちにアカウントに対して課金を行います。
   2. このテスト法には若干のコストが発生しますが、その価値はあります。ご自分の API を使用する開発者に実際に請求を行う前に、すべてが正常に動作することを確認できるので、安心材料となります。

これで支払いゲートウェイは設定されましたが、CMS では設定されていないため、ユーザーはまだ使用できない可能性があります。Developer Portal タブに移動し、左側のナビゲーションペインでテンプレート Payment Gateway / Show をクリックします。

{% when "stripe" %} で始まるコードブロックの後に以下のスニペットがまだ表示されていない場合には、スニペット追加します。

{% when "adyen12" %}
{% if current_account.has_billing_address? %}
  {% adyen12_form %}
{% else %}
  <p><a href="{{ current_account.edit_adyen12_billing_address_url }}">First add a billing address</a></p>
{% endif %}

注記

• Adyen からのデータを 3scale のデータとマッピングするには、Adyen フィールド shopperReference を使用することができます (設定は 3scale-[PROVIDER_ID]-[DEVELOPER_ACCOUNT_ID])。

課金ルールにより、それぞれの API リクエストの費用を定義します。同じメトリクスに複数の課金ルールを設定した場合には、課金ルールが適用される範囲が分割されます。課金ルールは暦月に基づき、カウンターは各月の初日の 00:00 UTC にリセットされます。

Until 100 calls per month (from 1 to 100) each API call can be charged at $0.04, and starting from the call 101 (from 101 to infinity) the calls are charged at $0.10.

The first 1000 calls are not charged (cost $0), because they are included in the plan which has a monthly fixed cost. Starting from call 1001, each call is charged at $0.50.

Calls from 1 to 100 are charged at $0.30, 100 to 500 – at $0.40, and 500 and further – at $0.50.

最後の 2 つのステップを繰り返し、必要なすべての課金ルール範囲を作成します。

ルールをそれ以降すべてに設定するには、To フィールドを空欄のままにします。

費用のメトリクスの小数部の最大桁数は 4 桁に設定されています。数値が 4 桁を超える場合には、4 桁の数字に丸められます。

Audience > Billing > Earning by month セクションに、期限を迎えた請求書および受領済みの支払いの概要が表示されます。その月に発行した請求書のステータスごとに、すべての請求書の合計値が計算されます。

特定の月をクリックすると、その月の請求書をすべて一覧表示することができます。

Audience > Billing > Invoices の順に移動して、請求書のリストを表示することもできます。ここでは、ID (平易な ID)、アカウント名、月、およびステータスで請求書を絞り込むことができます。

特定開発者アカウントの請求書は、アカウントの詳細ページ (Audience > Accounts > Listing > [selected account]) に表示されるパンくずリストの X Invoices から表示することもできます。ここで、X はそのアカウントの請求書数です。

請求書リストで請求書の平易な ID をクリックすると、その請求書の詳細が表示されます。

請求書のステータスは、以下のいずれかです。

3scale では、請求プロセスは毎日実施されます。請求書を生成し、請求フローに従ってステータスを変更し、設定された支払いゲートウェイを使用して課金処理を実施します。

前払いモードと後払いモードでは、請求フローにわずかな違いがあります。3scale における請求は暦月に基づいているため、月の初日に特別なイベントが発生します。

自動請求プロセスでは、有料サービスにサブスクライブしているすべての開発者アカウントの請求書が生成されます。

請求はグローバルに有効または無効にすることができます。請求についての詳細は、請求設定の定義 を参照してください。ただし、開発者アカウントごとに、請求および課金の両方を有効または無効にすることもできます。これらの操作を行うには、Audience > Accounts > Listing の順に移動し、Group/Org 列で変更を行う開発者アカウントをクリックし、続いて該当するボタン (Enable/Disable) をクリックします。

課金を無効にして請求を有効にした場合には、開発者には請求書は発行されますが、課金は行われません。これは、課金を別個に処理する場合 (送金など) に便利です。

両方を無効にすると、開発者には請求書は発行されず、課金も行われません。

請求を無効にして課金を有効にした場合には、開発者には新たな請求書は発行されませんが、支払いの済んでいない請求書 (Pending および Failed) は引き続き課金されます。

この Billing Status ブロックで、アカウントでクレジットカード情報が設定されているかどうかを確認することもできます。クレジットカード情報が設定されている場合には、カードの有効期限の月および年が表示されます。クレジットカード情報の有無により、サインアップおよびプラン変更時のデベロッパーポータルのフローが異なる場合があります (詳細については、「クレジットカードに関する作業フロー」を参照してください)。

有料プランにトライアル期間を設定し (日数単位)、指定した日数だけ課金を遅らせることができます。

トライアル期間のステータスは、アプリケーションリスト ([Your_API_service] > Applications > Listing) の State 列 (live – trial expires in N daysと表示) およびアプリケーションの詳細ページの Trial days left フイールドに表示されます。

トライアル期間中、アプリケーションではすべての機能およびプランで定義した使用制限を使用することができます (制約はありません)。

一度トライアル期間を設定したら、トライアルをキャンセルしたり期間を延長したりすることはできません。別のプランにアップグレードしても、トライアル日数のカウンターはリセットされません。

トライアル期間が終了する 10 日前に、間もなくトライアル期間が終了することを知らせるメール通知が開発者アカウントに送信されます。この電子メールのテンプレートは、Audience > Messages > Email Templates の順に移動し、Application trial period expired for buyer(アプリケーションプラン用) およびService trial period expired for buyer(トライアル期間が設定されたサービスプラン用) で設定することができます。開発者は、現在のプランをそのまま使用するか、別のプランに切り替えるか、またはサブスクリプションをキャンセルする場合には API プロバイダーに連絡する必要があります。

トライアル期間が終了すると、次回自動請求が実行される時に (「自動請求プロセス」を参照) 開発者に課金が行われます。この課金は、現在アプリケーションまたはサービスに設定されているプランに規定された費用に基づきます。トライアル期間が終了した後もアプリケーションがブロックまたは一時中断 されることはなく、引き続き機能する点に注意してください。

技術的には無料プランにトライアル期間を設定することはできますが、機能の有用性が失われるため推奨されません。

付加価値税 (VAT) は、欧州連合内で販売される商品およびサービスに適用される税です。他の国には、消費税などの類似の税があります。API サービスの使用に対して顧客に課金する API プロバイダーは、既存の規則に準拠するために、通常は税金を請求してそれを請求書に反映する必要があります。

3scale の請求では、設定により VAT を自動的に請求書に含めることができます。

_Total cost (without <VAT rate>)_ +
_<VAT rate> Amount_ +
_Total cost (<VAT rate> <VAT rate value>% included)_

開発者は、デベロッパーポータルでクレジットカード情報を管理し、請求書を表示することができます。

開発者がデベロッパーポータルで請求に関する要素を確認できるためには、Finance スイッチ (Audience > Developer Portal > Feature Visibility) が Visible のステータスでなければなりません。

ログインしているユーザーは、Settings > Credit Card Details でクレジットカード情報を更新することができます。設定されている支払いゲートウェイによってフォームが異なる場合や、初めに請求先住所を入力しなければならない場合があります。

*注意:* クレジットカードの詳細は 3scale API 管理データベースには保存されず、支払いゲートウェイによって管理されます。3scale API Management データベースには、支払いゲートウェイから提供されたクレジットカード番号の最後の 4 桁、有効期限、および参照のみが保存されます。

デベロッパーポータルでは、開発者は 1 つのクレジットカードしか使用することができません。

クレジットカード情報をデベロッパーポータルから削除することはできません。開発者アカウントのユーザーがクレジットカード情報の削除を希望する場合には、API プロバイダーにクレジットカード情報をシステムから削除するよう要求する必要があります。

請求書を表示するには、Settings > Invoices の順に移動します。そこで各請求書の詳細を表示するか、請求書の PDF ファイルをダウンロードすることができます。

開発者がデベロッパーポータルの Credit Card Details のページで請求先住所を入力する際、この住所は法人アカウント住所とは別に保管されます。

デフォルトでは、請求書の Issued to フィールドには法人住所が表示されます。ただし、開発者が正式な住所を設定しておらず、請求先住所のみを設定している場合は、後者が請求書で使用されます (注: この場合、組織名は住所の一部と見なされます)。

デフォルトでは、請求先住所は管理ポータルまたは API では表示されません。ただし、以下の手順により追加することができます。

これで、Account Management API および Webhook の Accounts の XML モデルに、<billing_address> フィールドが表示されるようになります。対応する請求先住所が、管理ポータルの Account および Edit account のページで読み取り専用として表示されます。

開発者は、デベロッパーポータルの Credit Card Details セクションで、請求先住所を変更することができます。管理者は管理ポータルで請求先住所を変更することはできませんが、以下のフィールドを使用して (追加フィールドとして)、Account Management API の Account Edit エンドポイントにより変更することができます。

billing_address_name
billing_address_address1
billing_address_address2
billing_address_country
billing_address_city
billing_address_state
billing_address_zip
billing_address_phone

3scale アカウントのユーザー (管理者および Billing 権限を持つメンバー) は、請求に関する通知をサブスクライブおよびサブスクライブを解除することができます。その設定は、Account Settings (右上の歯車アイコン) > Personal > Notification Preferences の Billing セクションで行います。

注記: 3scale アカウントのすべての管理ユーザーは、請求に関する通知をサブスクライブしている場合、それらの通知を受け取ります。

開発者アカウントに送信されるメール通知は、Audience > Messages > Email Templates で設定することができます。以下のメール通知を利用することができます。

開発者アカウントのすべての管理ユーザーは、上記の通知を受け取ります。

管理者であれば、必須フィールドの一部を省略することができます。ユーザーを安全にアカウントに招待する場合には、パスワードフィールドも省略することができます。ただし、このメインの管理アカウントのメールアドレスは、すべてのユーザーに対して一意でなければなりません。

アカウントのアプリケーションキーを事前に設定する場合には、開発者に代わってアプリケーションを追加することもできます。そうでなければ、開発者が行う初期ステップの一部として、本セクションを省略します。

手動で開発者に招待メールを送信するか、手順に従って 開発者の招待 機能を使用することができます。

管理者が電子メールを受け取り、開発者の 1 人に承認待ちの項目があることを認識した場合には、その承認項目の URL をコピーしてブラウザーに貼り付けると、承認を行うページに直接移動することができます。

特定のアカウントを検索する、または (承認が)pending ステータスにあるアカウントに絞り込むには、Audience > Accounts > Listing の順に移動します。承認待ちのアカウントだけを表示するには、State のドロップダウンリストで Pending を選択し、Search をクリックします。

それぞれの行で個別に直接承認を行うことも、一度に複数の行を選択して一括して承認を行うこともできます。

特定のサービスサブスクリプションを検索する、または (承認が)pending ステータスにあるサブスクリプションに絞り込むには、Audience > Accounts > Subscriptions の順に移動します。

サブスクリプションを表示するには、Audience > Accounts > Usage Rules で Service Plans のチェックボックスを選択します。

1 つのサブスクリプションを選択することも、一度に複数のサブスクリプションを選択して一括して承認を行うこともできます。

特定のアプリケーションを検索する、または (承認が)pending ステータスにあるアプリケーションに絞り込むには、以下の手順を実施します。

1 つのアプリケーションを選択することも、一度に複数のアプリケーションを選択して一括して承認を行うこともできます。

開発者アカウントの詳細ページから操作を開始することもできます。そこで承認するアプリケーションを選択し、アプリケーションの詳細ページで承認を行います。

特定のアカウントを検索する、または特定のアカウントに絞り込むには、Audience > Accounts > Listing の順に移動します。

1 つまたは一度に複数の行を選択し、プランを変更することができます。

特定のサービスサブスクリプションを検索する、または特定のサービスサブスクリプションに絞り込むには、Audience > Accounts > Subscriptions の順に移動します。

Settings のページで Service Plans のチェックボックスを選択している場合に限り、サブスクリプションが表示されます。

1 つまたは一度に複数のサブスクリプションを選択し、プランを変更することができます。

特定のアプリケーションを検索する、または特定のアプリケーションに絞り込むには、Audience > Applications > Listing の順に移動します。

1 つまたは一度に複数のアプリケーションを選択し、プランを変更することができます。

もう 1 つのシナリオは、開発者アカウントの詳細ページから操作を開始するものです。そこでプランを変更するアプリケーションを選択します。アプリケーションの詳細ページで、プランを変更することができます。

問題のアプリケーションを管理しているアカウントおよび開発者がすでに分かっている場合には、以下に示すように Accounts のページ (Audience > Accounts > Listing) からそのアカウントに移動します。

アプリケーション ID または API キーしか分からない場合には、Accounts のページ (Audience > Accounts > Listing) の検索ボックスを使用して、該当するアカウントを特定することができます。アプリケーションの特定に関する詳細は、ここ を参照してください。

以下に示すように、アカウントプロファイルのページに移動したら、メッセージアイコンをクリックします。

ここで作成されるメッセージは、そのアカウントのすべての開発者がメッセージを確認できるアカウントシステムダッシュボードに送信されると共に、そのアカウントで管理者ステータスを持つ開発者アカウントのユーザーに電子メールで送信されます。

緊急事態が発生し電子メールの対応では間に合わないと考えられる場合には、サインアップ時に開発者が入力した連絡先情報を使用することもできます。この情報は、以下の場所に表示されます。

サインアップ時に、連絡先電話番号を必須フィールドにできる点に注意してください。

対象となる開発者アカウントの詳細ページを表示するには、以下の手順を実施します。

プランをカスタマイズするアプリケーションを選択します。

カスタマイズするオプションを選択します。この操作により表示されるページで、このアカウントが所有するアプリケーションに適用されるプランの要素をすべてカスタマイズすることができます。

アプリケーションを特定するには、アプリケーションが属するアカウントの名前またはアプリケーションの名前が必要です。この情報がない場合には、アクセスログを確認することができます。検索を実行するには、Applications のページに移動します (Audience > Applications > Listing)。

認証タイプの識別子で検索する場合には、以下の情報が必要です。

特定のアプリケーションを検索するには、Applications のページに移動し (Audience > Applications > Listing)、以下の図に示す検索ボックスを使用します。

検索結果が返されたら、アクセスするアプリケーションをクリックすると、そのアプリケーションのホームページが表示されます。ホームページには、以下の図に示すような情報が含まれています。

管理ポータルから、1 人の開発者のサービスへのサブスクライブを解除します。

一括処理を実施して、複数の開発者の非推奨となった/削除されたサービスへのサブスクライブを解除します。

Service Plans のチェックボックスを選択している必要がある点に注意してください。

Accounts もしくは Applications タブから、または ここ で説明するように検索を行い、アプリケーションを特定することができます。

アプリケーションを特定してアプリケーションの概要ページを表示したら、State の値の横にある Suspend アイコンをクリックします。この操作により、アプリケーションが直ちに API から無効になり、すべてのキーの動作が一時中断されます。これらのアプリケーションキーを使用した呼び出しは、制御システムによって拒否されます。

問題のある挙動が修正されたら、同じボタンを使用してアプリケーションの一時中断を解除することができます。

アプリケーションの開発者への連絡方法は、ワークフローおよびポリシーによって異なります。同じページでアカウント名をクリックすると、アカウントビューが表示され、アプリケーションを所有するアカウントのメイン管理者を特定することができます。電子メールにより、または以下の図に示す Send message ボタンをクリックしてユーザー用のダッシュボードメッセージを生成して、管理者に連絡を取ります。

本章の手順を実施するには、スタートガイドの手順を完了している必要があります。

本章では、既存の 3scale コードプラグインのいずれかを使用してインテグレーションを行っていると仮定しています。他のインテグレーション方法でも、類似の作業フローをたどることができます。利用可能なインテグレーションオプションの詳細については、API ゲートウェイの管理の APIcast の運用 の章を参照してください。

ご自分の API の統計処理に関して、3scale は無限にスケーラブルなデータリポジトリーとして機能し、API のほぼすべてのメトリクスを追跡することができます。以下に例を示します。

ご自分の API に関連するより多くのメトリクスを追跡することができます。時間の経過と共に増加する数量であれば、3scale では任意の数のメトリクスおよびメソッドを追加することができます。

メトリクスを選択したら、それらを 3scale 管理ポータルで登録します。[Your_API_name] > Integration > Methods & Metrics に移動します。

図30.1 新しいメソッドを作成

メトリクスとメソッドをサービスに追加します。フレンドリ名とシステム名を提供します。これは後でプラグイン設定で使用されます。メソッドおよびメトリクス作成の詳細については、3scale での API の定義 (メソッドおよびメトリクス) を参照してください。

3scale システムで追跡するメトリクスの名前を設定したら、適切なメトリクスを報告するようにプラグインの設定を微調整します。この操作の詳細な手順は、使用しているプラグインまたはインテグレーション手段によって異なります。デフォルトでは、プラグインは hits (API トランザクション) メトリクスしか報告しません。

一般的には、以下の手順に従う必要があります。

特定の API メソッドのトラフィックを報告する場合には、メトリクスの引数でメソッド system name を使用します。これにより、報告されたメソッドと hits メトリクスの両方のカウンターに、自動的に増分が加算されます。

API と 3scale の接続が確立されたら、トラフィックを API に送信し、それが登録されることを API Analytics ダッシュボードで確認することができます。本セクションの手順を実施するには、既存の開発者アカウントおよびアプリケーション (および API クレデンシャル) が必要です。以下の手順に従って開発者アカウントを作成し、API クレデンシャルと共にアプリケーションを取得します。

トラフィックが Analytics セクションの使用状況チャートに表示されない場合には、以下に示す項目について確認を行います。

デフォルトでは、API プロバイダーは管理ポータルを通じて、アプリケーションを作成した開発者はデベロッパーポータルを通じて、それぞれ使用状況の統計を表示することができます。(それぞれの開発者は、自分自身のアプリケーションの使用状況の統計しか表示することはできません。) デベロッパーポータルから解析ビューを非表示にすることができます。デベロッパーポータルのカスタマイズに関する詳細は、デベロッパーポータルの作成 を参照してください。

分析セクションの使用状況グラフ以外にも、API の分析データを取得する方法があります。

3scale では、API Dashboard で利用可能な機能を継続的に改善しています。しかし、お客様が当社の開発プランに先立ち、まだサポートされていない非常に特殊な機能を必要とする場合があります。

API 管理のニーズを満たすために、3scale にはすべてのデータにアクセスするためのツールが常に用意されています。カスタムスクリプトにはある程度のコストがかかりますが (スクリプトを作成するのにいくらかのリソースが必要です)、本章で示すように、そのコストはそれほど大きくありません。さらに重要なことは、DIY による完全な柔軟性と制御性により、考え得るあらゆるユースケースに対応した実装が可能だという点です。

先ごろ、3scale では簡単には解決できない非常に特殊なニーズをお持ちのお客様がお越しになりました。

そのお客様は、毎週、数千人もの新規開発者を獲得していました。3scale API Management Platform のおかげで、お客様はこのような盛況ぶりを乗り切っていました。このように多数の開発者を受け入れるのは大変な作業ですが、幸い 3scale では必要な作業 (キーのプロビジョニング、サインアップワークフロー、電子メールによる連絡など) が自動化されています。ここまでは順調でした。

しかし、お客様にとって非常に重要だが、3scale では実施できないことがありました。非常に多数の開発者を受け入れているため、新規開発者を分類するためのシンプルな手段が必要でした。運用およびマーケティングチームが新規開発者とより効果的に交流できるように、お客様の API の使用状況に応じて新規開発者を分類する必要がありました。

このような機能は、少なくとも求められるレベルの詳細さでは、3scale に組み込まれた解析ツールではまだ利用することができません。しかし、すべてのデータにはアクセスすることができるので、3scale の Account API および Analytics API を使用してそのデータを抽出することができます。

お客様は、過去 10 日間に無料の評価版プランにサインアップした新規開発者の数を知り、それをいくつかのグループに分けたいと考えました。

まず、サインアップはしたがお客様の API を全く使用しなかった開発者の数を知りたいと考えました。この情報を使用してお客様がやりたかったことは本章のスコープから外れますが、これは API 採用の助けとなる明らかに貴重な情報です。

次に、API を使用した開発者を以下の 2 つのグループに分けたいと考えました。

この情報は、3scale の組み込み解析機能で利用可能です。問題は、集約データとして表示するビューがないことで、これは非常に面倒な状況です。

この問題に対する典型的な答えは、この分類方法は、今後の解析機能の改善で取り扱いますです。(面白いことに、実際にそうでした。) しかし、今それが必要な場合には、これでは問題の解決になりません。3scale では、当社のリリーススケジュールに依存せずに必要なことをすべて行うことができるように、ツールを提供したいと考えています。

3scale は DIY に柔軟に対応可能です。誰でも、契約したサービスの現在の機能を拡張できるべきだと考えています。すべてのニーズに対応できるとどれほど考えても、特定の要素については必ずニーズが先行します。非常に特殊なニーズだったからかも知れませんし、単に他の機能を実装するのに忙しかったからかも知れません。いずれにせよ、すぐには何かを実施することができない時に、お客様の作業をブロックすることは避けたいと考えています。3scale ではデータへのフルアクセスが可能で、そのデータを処理するための完全なツールセットを利用することができます。

当社および他の 3scale ユーザーと共有したいスクリプトがありましたら、当社にお送りください。それらのスクリプトを集めて公開したいと考えています。

Audience > Accounts > Listing もしくは Audience > Applications > Listing の順に移動して、または アプリケーションの特定 で説明するように検索を行い、アプリケーションを特定することができます。

アプリケーションを見つけると、次の図に示すように、アプリケーションに関する情報を含む概要画面が表示されます。

図でラベル付けされた項目は、次の情報に対応しています。

アプリケーションの Analytics ページにアクセスするには、アプリケーションに移動し、アプリケーション名の上にあるリンクの Analytics をクリックします。これにより、下のイメージに示すように、アプリケーションの使用チャートビューが表示されます。

メトリクス、メソッド、および時間範囲を変更すると、アプリケーションに関するさまざまなタイプのデータを確認することができます。