管理ポータルガイド

Red Hat 3scale API Management 2.8

Red Hat 3scale API Management に関する諸要素の管理

概要

本ガイドでは、Red Hat 3scale API Management の管理について説明します。

はじめに

本ガイドは、管理ポータルで利用可能な機能を使用して 3scale インストール環境を管理する際に役立ちます。

パート I. アカウント設定

第1章 アカウント設定

アカウントを作成したら、ご自分の会社に関する基本情報を更新します。住所を設定し、連絡先情報を追加します。

注記
The account view is only visible to administrators, not to members.

1.1. 会社情報の追加

新規アカウントを作成したら、以下の手順により会社情報を追加します。

  1. 上部ナビゲーションバーの右にある歯車アイコンをクリックします。Overview ウィンドウが表示されます。
  2. Account Details の見出しの横にある Edit のリンクをクリックします。
  3. アカウントの情報を入力します。

ここで指定する住所には、2 つの用途があります。

  • 有料プランを利用している場合には、当社は請求のためにこの住所を使用します。
  • 請求および支払いモジュールを使用している場合には、顧客に送付する請求書にもこの住所が表示されます。

1.2. 希望するタイムゾーンの選択

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

第2章 3scale 管理ポータル用 Red Hat Single Sign On

本章では、3scale 管理ポータルで Red Hat Single Sign On (RH-SSO) を設定して使用する方法について説明します。

2.1. RH-SSO または Auth0 メンバー認証の有効化

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

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

注記

複数の SSO メンバー認証タイプを有効にすることができます。

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

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

2.1.1. RH-SSO 使用の前提条件

2.1.2. Auth0 使用の前提条件

  • Auth0 のサブスクリプションおよびアカウント

2.1.3. RH-SSO の有効化

RH-SSO または Auth0 を有効にするには、3scale 管理ポータルで管理者として以下の手順を実施します。

  1. 希望の SSO プロバイダー (前提条件を参照) が正しく設定されていることを確認します。
  2. Account Settings の SSO Integrations に移動します。

    • ページ右上隅にある歯車アイコンをクリックします。
    • Account Settings (歯車アイコン) > Users > SSO Integrations の順に移動し、New SSO Integration をクリックします。
  3. ドロップダウンリストから、希望の SSO プロバイダーを選択します。
  4. 必須の情報を入力します (SSO を設定した際に指定したもの)。

    • Client
    • Client Secret
    • Realm or Site
  5. Create Authentication Provider をクリックします。
注記

テスト中にコールバック URL の不一致が発生した場合には、エラーメッセージに示されるコールバック URL を Auth0 が許可するコールバック URL に追加します。

2.2. 3scale での RH-SSO の使用

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

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

  1. 3scale のログインページに移動します。

    https://<organization>-admin.3scale.net/p/login
  2. ご自分の IdP で 3scale を承認します。
  3. 状況に応じて、必要な情報を入力してサインアップを完了します。

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

2.3. 3scale ログインの RH-SSO オプションへのリダイレクト

本セクションでは、RH-SSO を使用したアイデンティティープロバイダー (IdP) のログインウィンドウへのリダイレクトについて説明します。3scale API Management の管理者は、以下の手順を実施して、ご自分の 3scale アカウントをオプションのシングルサインオン (SSO) のログインページ経由でアクセス可能にすることができます。

2.3.1. 前提条件

  • 3scale 2.8
  • デベロッパーポータルの作成の RH SSO の設定 セクションに記載の手順に従って、RH-SSO インスタンスおよびレルムが設定されている。
注記

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

2.3.2. 必要な手順

  1. 3scale ドキュメントの Red Hat Single Sign-On for the 3scale Admin Portal セクションの RH-SSO を設定するための手順にアクセスし、それに従ってください。
  2. RH-SSO の管理者に 3scale の URL を提供します。この URL が RH-SSO 内でリダイレクトの基盤となり、セキュアなログオンが確保されます。URL には以下のフォーマットを使用します。

    https://<organization>-admin.3scale.net/auth/<system_name>/bounce
  3. <system_name> は、管理ポータルの SSO Integration の詳細ページで取得することができます。

    https://<organization>.3scale.net/p/admin/account/authentication_providers/<ID>
  4. Keycloak_0123456aaaaa も、以下のように SSO Integration の詳細ページの Callback URL for OAuth flow test フィールドから確認することができます。

    https://<organization>.3scale.net/auth/keycloak_0123456aaaaa/callback

第3章 ユーザーの招待および権限の管理

注記

招待 機能を利用することができるのは、Pro および Enterprise のお客様だけです。

API 管理のワークロードを分散するために、3scale 管理ポータルにアクセスできるように同じ組織のチームメンバーを招待したい場合があります。以下の手順で、1 人または複数のチームメンバーに 3scale 管理ポータルへのアクセス権限を付与する方法を説明します。

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

  • 管理者: すべての機能およびサービスに対するフルアクセス権限を持ち、他のメンバーを招待することができる (プランで許可される場合)。
  • メンバー: 一部の製品機能に対するアクセス権限を持ち (例: 解析、デベロッパーポータル)、Enterprise のお客様であればサービスに対しても限定的なアクセス権限を持つ。

シングルサインオン (SSO) インテグレーションから新しい 3scale ユーザーを作成する場合、SSO トークンの内容に関係なく、このユーザーはデフォルトで メンバー ロールを持ちます。3scale では、そのロールを SSO ロールにマッピングしません。

3.1. ユーザー管理画面への移動

ご自分の 3scale インストール環境内のユーザーを一覧表示するには、管理ポータルのページで以下の手順に従います。

  1. ウィンドウ上部のナビゲーションバーの右にある歯車アイコンをクリックします。
  2. 左側のメニューから、Users > Listing の順に移動します。

3.2. 招待状の送信

ユーザーのリストから、新しいチームメンバーを招待することができます。招待状を送信するには、以下の手順を実施します。

  1. リストの右上にある Invite user のリンクをクリックします。
  2. 招待するユーザーのメールアドレスを入力し、Send をクリックします。
  3. 送信の確認として、ウィンドウの右上隅に Invitation was successfully sent. というメッセージが表示されます。

入力したアドレスに招待メールが送信されます。電子メールが届かない場合には、受取人のメールアカウントで迷惑メールと識別されていないことを確認します。

また、Users > Invitations で、送信した招待状のリストおよびステータスを確認することができます。

3.3. 招待の応諾

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

3.4. 新しいユーザー権限の付与

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

  • 機能別: 解析、請求、開発者の管理など。
  • サービス別: すべてのサービスの中から、メンバーにアクセス権限を付与するサービスを選択します。注記: この機能を利用することができるのは、Enterprise のお客様だけです。

新しいユーザー権限を付与するには、ユーザーメニューからユーザーを選択し、Edit をクリックしてそのユーザーを編集します。ユーザーロールには、以下のタイプがあります。

  • ユーザーのロールを Admin に変更すると、管理ポータルを制御するためのフルアクセス権限が付与されます。
  • ユーザーのロールを Member に変更すると、さらにチームメンバーがアクセス権限を持つ機能およびサービスを選択することができます。

    • Member の場合には、機能を選択すると、その機能に関して利用可能なすべてのサービスが一覧表示されます。

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

  • Developer accounts — Applications: Account management API へのアクセス権限が付与されます
  • Analytics: Analytics API へのアクセス権限が付与されます
  • Billing: Billing API へのアクセス権限が付与されます
Rights by area and service

第4章 通知

Red Hat 3scale API Management のユーザーインターフェイスおよび 3scale API に関する操作を行うと、通知が送信されます。開発者がトリガーとなり、管理者、その他のメンバー、および 3scale に通知が送信されます。API 通知については、アクセス権限のある API に関する通知しか受け取ることができません。

4.1. 通知のタイプ

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

  • アカウント
  • 請求
  • アプリケーション
  • サービスサブスクリプション
  • 使用量に関するアラート

4.2. 制約

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

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

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

4.3. メール通知へのサブスクライブ

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

  1. Account Settings (ナビゲーションバーの歯車アイコン) > Personal > Notification Preferences の順に移動します。
  2. 受け取りを希望する通知を選択します。
  3. Update Notification Preferences をクリックします。

4.4. Web 通知

メール通知に加えて、Dashboard で活動に関する履歴情報を確認することができます。

Accounts dashboard

第5章 個人設定

Personal 設定では、チームメンバーとして個人設定を編集することができます。管理者の場合には、アカウント設定を編集することもできます。そのためには、アカウント設定 のチュートリアルを参照してください。

個人設定を編集するには、以下の手順を実施します。

  1. ナビゲーションバーの歯車アイコンをクリックします。
  2. 左側のパネルで Personal に移動します。ここから 3 つのタイプの設定を編集することができます。

    • Personal Details: 名前、メールアドレス、パスワード等。
    • Tokens: 3scale API (Billing、Account Management、および Analytics) に対する認証を行うためのアクセストークンを作成し、ActiveDocs (インタラクティブドキュメント) 内から使用します。詳細については、3scale トークン を参照してください。
    • Notification Preferences: 受け取りを希望する通知を選択します。注記: Enterprise のお客様でメンバーの場合には、表示される通知は機能およびサービスでフィルターリングされます。つまり、アクセス権限が付与されている機能およびサービスに関する通知だけをサブスクライブすることができます。通知の個人設定に関する詳細は、通知 を参照してください。

第6章 トークン

本チュートリアルでは、トークンとは何か、その仕組み、作成方法など、3scale トークンについて説明します。

3scale には、アクセストークン (ユーザーにより作成される) および サービストークン (3scale で新規サービスを作成する際に自動的に作成される) の 2 種類のトークンがあります。

6.1. アクセストークン

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

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

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

6.2. アクセストークンの作成

アクセストークンは、Tokens のページで作成することができます。トークンを作成するには、以下の手順に従います。

  1. ナビゲーションバーの歯車アイコンをクリックします。
  2. Personal > Tokens の順に移動します。
  3. Add Access Token をクリックします。
  4. 名前を指定し、対象となる API を 1 つまたは複数選択し、トークンの権限を選択します。
  5. 新しいトークンを保存するには、Create Access token をクリックします。

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

アクセストークンは、必要なだけ作成することができます。セキュリティー上の理由から、トークンは 3scale に保存されません。新しいトークンを作成すると、トークンを保存するように要求されます。保存したそのトークンを使用して、3scale API にリクエストを行うことができます。

トークンを紛失した場合には、トークンを削除することを推奨します。これにより、トークンが無効になり、効力が無くなります。その後、新しいトークンを作成します。

6.3. アクセストークンの使用

アクセストークンを使用して 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)。

パート II. マルチテナントへの対応

第7章 マルチテナントへの対応

Red Hat 3scale API Management では、複数の独立した 3scale アカウントのインスタンスが単一のオンプレミスデプロイメントに存在する設定が可能です。アカウントは互いに独立に機能し、情報を共有することはできません。

7.1. マスター管理ポータル

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

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

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

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

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

<MASTER_NAME>.<WILDCARD_DOMAIN>

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

Master Admin Portal flag

7.1.2. マスター管理ポータルからのアカウント追加

マスター管理ポータルからアカウントを追加するには、以下の手順に従います。

  1. マスター管理ポータル にログインします。
  2. Accounts に移動します。
  3. Create をクリックします。
  4. 必須のユーザー情報を指定します。

    1. ユーザー名
    2. メールアドレス
    3. パスワード
    4. パスワードの確認
  5. 必須の組織情報を指定します。

    1. 組織/グループ名
  6. Create をクリックします。

上記の手順を完了すると、Red Hat 3scale は Organization/Group Name フィールドの情報を元にご自分のアカウントのアカウントサブドメインを作成します。また、作成したアカウントの情報が含まれるページが表示されます。

7.1.3. マスター管理ポータルを使用した単一のゲートウェイの作成

マスター管理ポータルを使用して、すべてのテナント用に単一のゲートウェイを作成することができます。そのためには、THREESCALE_PORTAL_ENDPOINT 環境変数を設定します。このゲートウェイは、ホスト型 3scale (SaaS) の Hosted APIcast に類似しています (OpenShift テンプレートを使用してデプロイされたデフォルトの apicast-staging および apicast-production ゲートウェイは、このようにして設定されます)。

マスター管理ポータルを使用して単一のゲートウェイを作成するには、以下の手順に従います。

  1. ご自分の 3scale プロジェクトの system-master-apicast シークレットから、ACCESS_TOKEN の値を取得します。あるいは、マスター管理ポータルで 新規アクセストークンを作成する ことができます。
  2. APIcast のデプロイ時に、以下のコマンドを使用します。

     THREESCALE_PORTAL_ENDPOINT="https://<ACCESS_TOKEN>@<public url to master admin portal>/master/api/proxy/configs"
    • URL の最後は、/master/api/proxy/configs のようになります。これは、マスター の場合には、デフォルトの /admin/api/services.json とは異なるエンドポイントに configs が保管されるためです。

7.2. アカウントの管理

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

7.2.1. マスター管理ポータルからのアカウントの管理

マスター管理ポータルからアカウントを管理するには、以下の手順を実施する必要があります。

  1. マスター管理ポータル にログインします。
  2. Accounts のページに移動します。
  3. 管理するグループまたは組織を選択します。

Accounts のページから、管理操作を実施することができます (特定組織の 3scale アカウントの管理者として活動する、アカウントを一時中断する等)。以下のアカウント属性を管理することもできます。

  • アプリケーション
  • ユーザー
  • 招待状
  • グループメンバー
  • 組織/グループ名

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

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

Master API section

7.3. マルチテナント対応サブドメインについて

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

user.example.com

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

  • マスター管理ユーザー
  • MASTER_NAME パラメーターにより定義される、マスター管理ポータルのルート

    <MASTER_NAME>.<WILDCARD_DOMAIN>
  • アカウント管理ユーザー
  • TENANT_NAME パラメーターにより定義される、アカウント管理ポータルのルート

    <TENANT_NAME>-admin.<WILDCARD_DOMAIN>
  • アカウントのデベロッパーポータルのルート

    <TENANT_NAME>.<WILDCARD_DOMAIN>
  • 実稼働およびステージング用 Embedded APIcast ゲートウェイのルート

    <API_NAME>-<TENANT_NAME>-apicast-staging.<WILDCARD_DOMAIN>
    <API_NAME>-<TENANT_NAME>-apicast-production.<WILDCARD_DOMAIN>
    This example illustrates the output users and routes of a standard multitenant deployment of 3scale:
    ----
    --> Deploying template "3scale-project/3scale-api-management" for "amp.yml" to project project
    3scale API Management
    ---------
    3scale API Management main system
         Login on https://user-admin.3scale-project.example.com as admin/xXxXyz123
         ...
         * With parameters:
          * ADMIN_PASSWORD=xXxXyz123 # generated
          * ADMIN_USERNAME=admin
          * TENANT_NAME=user
          ...
          * MASTER_NAME=master
          * MASTER_USER=master
          * MASTER_PASSWORD=xXxXyz123 # generated
          ...
    --> Success
        Access your application via route 'user-admin.3scale-project.example.com'
        Access your application via route 'master-admin.3scale-project.example.com'
        Access your application via route 'backend-user.3scale-project.example.com'
        Access your application via route 'user.3scale-project.example.com'
        Access your application via route 'api-user-apicast-staging.3scale-project.example.com'
        Access your application via route 'api-user-apicast-production.3scale-project.example.com'
        Access your application via route 'apicast-wildcard.3scale-project.example.com'
        ...
    ----

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

7.4. テナントアカウントの削除

7.4.1. 管理ポータルを使用したアカウントの削除

以下の手順によりアカウントの削除がスケジュールされ、15 日後に削除されます。削除がスケジュールされている間、アカウントの取り扱いは以下のようになります。

  • ユーザーはアカウントにログインすることができない。
  • アカウントを編集することはできない。ただし、マスター管理ユーザーはアカウントを approved の状態に戻すことができます。

また、実際に削除された場合と同様に、テナントのドメイン (管理ドメインおよびデベロッパーポータル) を利用することはできません。

前提条件:

手順

  1. Accounts に移動し、アカウントのリストを表示します。
  2. 削除するアカウントをクリックします。
  3. アカウント名の横にある Edit をクリックします。
  4. アカウントの詳細ページで、Delete アイコンをクリックします。
  5. 削除を確認します。

7.4.2. コンソールを使用したテナントの削除

アカウントを直ちに削除する場合には、コンソールからその操作を行うことができます。

  1. 以下のコマンドを使用して、コンソールを開きます。

    oc rsh -c system-master "$(oc get pods --selector deploymentconfig=system-app -o name)"
    bundle exec rails console
  2. 以下の行により、直ちに削除を行います。

    tenant = Account.find(PROVIDER_ID)
    tenant.schedule_for_deletion!
    DeleteAccountHierarchyWorker.perform_later(tenant)

    各行の処理内容を以下に示します。

    • 1 行目: アカウントを探し、それを変数 tenant に保存します。
    • 2 行目: アカウントの削除をスケジュールします。これは、管理ポータルから削除をスケジュールしていない場合にのみ必要です。
    • 3 行目: アカウントの削除をスケジュールしているか、アカウントが一時中断のステータスの場合にのみ、バックグラウンドプロセスのテナントを削除します。アカウントが approved のステータスの場合には、削除は行われません。

7.5. テナントアカウントの復帰

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

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

  • 以前のすべてのアプリケーションが存在する。
  • すべての履歴統計値が維持される。
  • 有効であるべきすべてのトークンが再び有効になる。
  • アプリケーションが再び承認を開始する。

前提条件:

  • マスター管理アカウントにログインしている。

手順

  1. Accounts に移動し、アカウントのリストを表示します。
  2. 削除するアカウントをクリックします。
  3. アカウントの詳細ページで、Resume をクリックします。
  4. Ok をクリックして、アカウントの復帰を確認します。

パート III. サービスディスカバリー

以下の章では、OpenShift クラスターからサービスをインポートするのに役立つ 3scale 機能であるサービスディスカバリーについて説明します。

第8章 サービスディスカバリー

3scale の提供するサービスディスカバリー機能を使用すると、OpenShift からサービスをインポートすることができます。

8.1. サービスディスカバリーについて

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

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

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

  • クラスター API を使用して、正しく検出のアノテーションが付けられたサービスのクエリーを行う。
  • クラスター内の内部エンドポイントを使用してサービスにアクセスするように 3scale を設定する。
  • サービスに関連付けられた OpenAPI Specification を 3scale ActiveDocs としてインポートする。
  • OpenShift と Red Hat Single Sign-On (RH-SSO) の承認フローをサポートする。
  • Fuse バージョン 7.2 以降の Red Hat Fuse と協調する。

検出可能なサービスをインポートする場合、その namespace はサービスが属するプロジェクト内に維持されます。インポートされたサービスは、新しい顧客がアクセスする API (プロダクト) およびそれに対応する内部 API (バックエンド) になります。

  • オンプレミス型 3scale では、3scale API プロバイダーは固有の namespace およびサービスを持つ場合があります。検出されたサービスは、3scale の既存ネイティブサービスと共存することができます。
  • Fuse の検出可能サービスは、Fuse のプロダクション namespace にデプロイされます。

8.1.1. 検出可能サービスの条件

3scale が OpenShift クラスターの API を検出できるためには、その API は以下に示す各要素の条件を満たしている必要があります。

Content-Type ヘッダー

API 仕様の Content-Type ヘッダーの値は、以下のいずれかでなければなりません。

  • application/swagger+json
  • application/vnd.oai.openapi+json
  • application/json

OpenShift Service Object YAML 定義

  • OpenShift Service Object YAML 定義には、以下のメタデータが含まれている必要があります。

    • discovery.3scale.net ラベル (必須):true に設定します。検出が必要なすべてのサービスを探すために 3scale がセレクター定義を実行する際に、このラベルが使用されます。
    • また、以下のアノテーションが含まれている必要があります。

      discovery.3scale.net/discovery-version (オプション): 3scale の検出プロセスのバージョン。

      discovery.3scale.net/scheme (必須): サービスをホストする URL のスキーム部分。設定可能な値は http および https です。

      discovery.3scale.net/port (必須): クラスター内のサービスのポート番号。

      discovery.3scale.net/path (オプション): サービスをホストする URL の相対ベースパス。パスがルート (/) の場合には、このアノテーションを省略することができます。

      discovery.3scale.net/description-path: サービスの OpenAPI サービス記述ドキュメントへのパス。

      以下に例を示します。

          metadata:
            annotations:
              discovery.3scale.net/scheme: "https"
              discovery.3scale.net/port: '8081'
              discovery.3scale.net/path: "/api"
              discovery.3scale.net/description-path: "/api/openapi/json"
           labels:
              discovery.3scale.net: "true"
           name: i-task-api
           namespace: fuse
    • 管理者権限を持つ OpenShift ユーザーであれば、OpenShift のコンソールで API サービスの YAML ファイルを表示することができます。

      1. Applications > Services の順に選択します。
      2. サービスを選択し (例: i-task-api)、その Details のページを表示します。
      3. Actions > Edit YAML の順に選択し、YAML ファイルを開きます。
      4. ファイルの表示を終えたら、Cancel を選択します。

ovs-networkpolicy プラグインを持つクラスター

  • OpenShift と 3scale プロジェクト間のトラフィックを許可する場合、ovs-networkpolicy プラグインを持つクラスターには、アプリケーションプロジェクト内で作成された NetworkPolicy オブジェクトが必要です。
  • NetworkPolicy オブジェクトの設定についての詳細は、Networking の About network policy を参照してください。

8.2. サービスディスカバリーを有効にするための OpenShift 設定

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

OAuth サーバーと共に 3scale サービスディスカバリーを設定する場合、ユーザーが 3scale にサインインした際のフローは以下のとおりです。

  • ユーザーが OAuth サーバーにリダイレクトされる。
  • ユーザーがまだ OAuth サーバーにログインしていなければ、ログインを求められる。
  • ユーザーが 3scale のサービスディスカバリーと SSO の組み合わせを初めて実装する場合には、OAuth サーバーは必要なアクションを実行するために承認を要求する。
  • ユーザーが再度 3scale にリダイレクトされる。

OAuth サーバー と組み合わせてサービスディスカバリーを設定する場合には、以下のオプションがあります。

OAuth サーバーと組み合わせずにサービスディスカバリーを設定する 場合、ユーザーが 3scale にサインインしてもリダイレクトされません。その代わりに、サービスディスカバリーのために、3scale Single Service Account がクラスターに対してシームレスに認証を行います。3scale を通じて API サービスを検出する間、すべての 3scale テナント管理ユーザーはクラスターに対して同じアクセスレベルを持ちます。

8.2.1. OpenShift OAuth サーバーと組み合わせたサービスディスカバリーの設定

3scale のシステム管理者は、ユーザーが OpenShift の組み込み OAuth サーバーを使用して、個別に認証、3scale を承認して API を検出するのを許可することができます。

前提条件

  • OpenShift クラスター (バージョン 3.11 以降) に 3scale 2.8 をデプロイしている必要があります。
  • 3scale を OpenShift にデプロイするには、3scale-amp-openshift-templates を使用する必要があります。
  • 3scale でサービスディスカバリーを使用する 3scale ユーザーは、OpenShift クラスターにアクセスできる必要があります。

手順

  1. 3scale 用の OpenShift OAuth クライアントを作成します。詳細は、OpenShift の認証に関するドキュメント を参照してください。以下の例で、<provide-a-client-secret> を生成するシークレットに、<3scale-master-domain-route> を 3scale マスター管理ポータルにアクセスするための URL に、それぞれ置き換えます。

        $ oc project default
        $ cat <<-EOF | oc create -f -
        kind: OAuthClient
        apiVersion: v1
        metadata:
         name: 3scale
        secret: "<provide-a-client-secret>"
        redirectURIs:
         - "<3scale-master-domain-route>"
        grantMethod: prompt
        EOF
  2. 3scale サービスディスカバリーの設定ファイルを開きます。

        $ oc project <3scale-project>
        $ oc edit configmap system
  3. 以下のように設定します。

        service_discovery.yml:
          production:
            enabled: true
            authentication_method: oauth
            oauth_server_type: builtin
            client_id: '3scale'
            client_secret: '<choose-a-client-secret>'
  4. ユーザーが適切なアクセス権限を持ち、検出可能なサービスが含まれるクラスタープロジェクトを表示できるようにしてください。

    <user> で表される管理ユーザーに、検出されるサービスが含まれる <namespace> プロジェクトを表示する権限を付与するには、以下のコマンドを使用します。

    oc adm policy add-role-to-user view <user> -n <namespace>
  5. configmap を変更したら、system-app および system-sidekiq Pod を再デプロイし、変更を適用する必要があります。

    oc rollout latest dc/system-app
    oc rollout latest dc/system-sidekiq
  6. ロールアウトのステータスを表示し、読み込みが完了したことを確認します。

    oc rollout status dc/system-app
    oc rollout status dc/system-sidekiq

補足説明

OpenShift OAuth トークンについての詳細は、認証の 内部 OAuth サーバーの設定 を参照してください。

8.2.2. RH-SSO サーバー (Keycloak) と組み合わせたサービスディスカバリーの設定

システム管理者は、ユーザーが OpenShift 向け Red Hat Single Sign-On を使用して、個別に認証、3scale を承認してサービスを検出するのを許可することができます。

OpenShift の承認ゲートウェイとして RH-SSO デプロイメントを使用する OpenShift の設定例については、この ワークフロー を参照してください。

前提条件

  • OpenShift クラスター (バージョン 3.11 以降) に 3scale 2.8 をデプロイしている必要があります。
  • 3scale を OpenShift にデプロイするには、3scale-amp-openshift-templates を使用する必要があります。
  • 3scale でサービスディスカバリーを使用する 3scale ユーザーは、OpenShift クラスターにアクセスできる必要があります。

手順

  1. Red Hat OAuth サーバー (Keycloak) に、3scale 用の OAuth クライアントを作成します。

    注記

    クライアント設定で、OpenShift がアカウントをリンクすることができるように、usernamepreferred_username にマッピングされていることを確認します。

  2. 3scale サービスディスカバリーの設定を編集します。

        $ oc project <3scale-project>
        $ oc edit configmap system
  3. 以下のように設定されていることを確認します。ここで、<the-client-secret-from-Keycloak> は、OAuth クライアントの作成時に Keycloak が自動生成した値です。

        service_discovery.yml:
          production:
            enabled: true
            authentication_method: oauth
            oauth_server_type: rh_sso
            client_id: '3scale'
            client_secret: '<the-client-secret-from-Keycloak>'
  4. ユーザーが適切なアクセス権限を持ち、検出可能なサービスが含まれるクラスタープロジェクトを表示できるようにしてください。

    たとえば、<user><namespace> プロジェクトを表示する権限を付与するには、以下のコマンドを使用します。

    oc adm policy add-role-to-user view <user> -n <namespace>
  5. configmap を変更したら、system-app および system-sidekiq Pod を再デプロイし、変更を適用する必要があります。

補足説明:

  • トークンの有効期限:Keycloak Server Administration Guide の Session and Token Timeouts に記載されるように、デフォルトではセッショントークンの有効期限は 1 分です。ただし、タイムアウトを妥当な値 (たとえば 1 日) に設定することを推奨します。

8.2.3. OAuth サーバーと組み合わせないサービスディスカバリーの設定

OAuth サーバーを使用しない状況で 3scale のサービスディスカバリーを設定する場合には、3scale Single Service Account を使用して OpenShift API サービスに対する認証を行うことができます。

前提条件

  • OpenShift クラスター (バージョン 3.11 以降) に 3scale 2.8 をデプロイしている必要があります。
  • 3scale を OpenShift にデプロイするには、3scale-amp-openshift-templates を使用する必要があります。
  • 3scale でサービスディスカバリーを使用する 3scale ユーザーは、OpenShift クラスターにアクセスできる必要があります。

手順

  1. 3scale プロジェクトをアクティブなプロジェクトにします。

       $ oc project <3scale-project>
  2. エディターで 3scale サービスディスカバリーの設定を開きます。

       $ oc edit configmap system
  3. 以下のように設定されていることを確認します。

    service_discovery.yml:
       production:
          enabled: <%= cluster_token_file_exists = File.exists?(cluster_token_file_path = '/var/run/secrets/kubernetes.io/serviceaccount/token') %>
          bearer_token: "<%= File.read(cluster_token_file_path) if cluster_token_file_exists %>"
          authentication_method: service_account
  4. 以下のいずれかのオプションに従って、3scale デプロイメントの amp サービスアカウントに、検出可能なサービスが含まれるプロジェクトを表示するための適切な権限を付与します。

    • 3scale デプロイメントの amp サービスアカウントに、クラスターレベルの 表示 権限を付与する。

      oc adm policy add-cluster-role-to-user view system:serviceaccount:<3scale-project>:amp
    • Developer Guide の Service Accounts で説明するように、より厳しいポリシーを適用する。

8.3. 検出されたサービスのインポート

OpenShift クラスターから、OpenAPI Specification に準拠する新しい API サービスをインポートすることができます。この API を 3scale で管理することができます。

前提条件

  • OpenShift の管理者が、OpenShift クラスターにサービスディスカバリーを設定している。たとえば、OpenShift の管理者は、Fuse Online カスタムリソースを編集して 3scale ユーザーインターフェイスの URL を指定し、3scale の検出機能を有効にしている必要があります。
  • サービスディスカバリーについて で説明するように、3scale の管理者が 3scale デプロイメントでサービスディスカバリーを設定している。
  • 3scale の管理者が、3scale ユーザーまたはサービスアカウント (設定されている認証モードによる) に、API サービスおよびその namespace を表示するのに必要な権限を付与している。詳細は、OpenShift プロジェクトへの 3scale アクセスの承認 を参照してください。
  • 検出可能サービスの条件 で説明するように、サービスディスカバリーを有効にする正しいアノテーションが API に付けられている。
  • API サービスが、3scale をインストールしたクラスターと同じ OpenShift クラスターにデプロイされている。
  • API のサービス名およびその namespace (OpenShift プロジェクト) を把握している。

手順

  1. 3scale 管理ポータルにログインします。
  2. 管理ポータルの Dashboard で、NEW API をクリックします。
  3. Import from OpenShift を選択します。

  4. Namespace フィールドで、API が含まれる OpenShift プロジェクトを指定または選択します (例: fuse)。
  5. Name フィールドで、上記 namespace 内の OpenShift サービスの名前を入力または選択します (例: i-task-api)。
  6. Create Service をクリックします。
  7. 新しい API サービスが 3scale に非同期的にインポートされるのを待ちます。管理ポータル右上のセクションに、The service will be imported shortly. You will receive a notification when it is done. というメッセージが表示されます。

次のステップ

API 管理の詳細については、Red Hat 3scale API Management のドキュメント を参照してください。

8.4. OpenShift プロジェクトへの 3scale アクセスの承認

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

前提条件

  • OpenShift プロジェクトの管理者としてのクレデンシャルが設定されている。
  • OpenShift の管理者が、OpenShift クラスターにサービスディスカバリーを設定している。たとえば、Fuse Online API の場合、OpenShift の管理者は Fuse Online サービスの CONTROLLERS_EXPOSE_VIA3SCALE 環境変数を true に設定する必要があります。
  • 「サービスディスカバリーについて」 で説明するように、3scale の管理者が 3scale デプロイメントで Service Discovery を設定している。
  • API サービスの名前およびその OpenShift プロジェクトの namespace を把握している。
  • API サービスが、3scale をインストールしたクラスターと同じ OpenShift クラスターにデプロイされている。
  • 「サービスディスカバリーについて」 で説明するように、サービスディスカバリーを有効にする正しいアノテーションが API に付けられている。

手順

  1. Authenticate to enable this option のリンクをクリックします。
  2. namespace 管理者のクレデンシャルを使用して OpenShift にログインします。
  3. Allow selected permissions をクリックし、3scale ユーザーのアクセスを承認します。

次のステップ

API 管理の詳細については、Red Hat 3scale API Management のドキュメント を参照してください。

8.5. サービスの更新

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

前提条件

  • サービスが以前にクラスターからインポートされている。

手順

  1. 3scale 管理ポータルにログインします。
  2. API プロダクトの Overview ページに移動します。
  3. Source: OpenSource の横にある Refresh のリンクをクリックします。
  4. 新しい API サービスが 3scale に非同期的にインポートされるのを待ちます。

パート IV. アクセス制御

第9章 API の定義 (メソッドおよびメトリクス)

API プロダクトレベルとバックエンドレベルの両方で、メソッドおよびメトリクスを追加して API を定義することができます。API プロダクトとは、1 つまたは複数の API バックエンドをバンドルしたものです。プロダクトレベルでは、メソッドおよびメトリクスにより、プロダクトのあらゆるアプリケーションプランの制限および課金ルールを設定することができます。バックエンドレベルでは、メソッドおよびメトリクスを使用して、バックエンドをバンドルするあらゆるプロダクトのアプリケーションプランの制限および課金ルールを設定することができます。

メトリクスは、プロダクトレベルとバックエンドレベルの両方で、API の使用状況を追跡するのに適しています。Hits は組み込みのメトリクスです。各 API に設定され、API に対するヒット数を追跡するのに使用されます。Hits メトリクス下で メソッド を定義することにより、API の使用状況をより細かな粒度で追跡することができます。メソッドにトラフィックがレポートされると、メソッドおよび Hits メトリクスのカウンターが自動的に加算されます。API バックエンドのエンドポイントごとに個別のメソッドを定義することや、エンドポイントと HTTP メソッドの組み合わせを定義することができます。API のエンドポイントをここで定義するメソッドにマッピングする方法については、マッピングルール の章を参照してください。

ヒット数以外で API の使用状況を測定するために、新たな メトリクス を定義して使用状況を別の単位で報告することができます。この単位は数値化が可能で、ビジネス目標に対して意味を持つものでなければなりません (例: メガバイト数、CPU 時間、API によって返される要素数など)。CPU 時間や mb 等の hits 以外のメトリクスは、すべてデフォルトの 3scale には含まれておらず、ユーザーが設定する外部サービスによって定期的に呼び出されるエンドポイントを使用して報告する必要があります。

メソッドとメトリクスは、API をパッケージングする際の基礎でもあります。それぞれのアプリケーションプランでは、メソッドおよびメトリクスごとに異なる使用制限および課金ルールを定義することができます。メトリクスおよびメソッドにレポートされる使用状況についての詳細は、API の解析 セクションを参照してください。

関連情報

API プロダクトおよび API バックエンドの詳細は、3Scale のスタートガイド を参照してください。

9.1. メソッドおよびメトリクスの追加

プロダクトまたはバックエンドに新たなメソッドを追加するには、以下の手順に従います。

  1. [Your_product_name] > Integration > Methods & Metrics または [Your_backend_name] > Methods & Metrics の順に移動します。
  2. メソッドリストの右上にある New method のリンクをクリックします。
  3. 以下のパラメーターを指定します。

    • Friendly name はメソッドの簡単な説明で、3scale 管理ポータルのさまざまなセクションに表示されます。この名前は、プロダクト単位で一意でなければなりません。
    • System name は、3scale Service Management API を通じて使用状況を報告するのに使用されるメソッドの名前です。この値も一意でなければならず、英数字、アンダースコア (_)、ハイフン (-)、およびスラッシュ (/) しか使用することはできません (スペースを使用することはできません)。それ以外は、自由に System name を指定することができます。エンドポイントとまったく同じにすることも (/status)、たとえばメソッドおよびパスを含めることもできます (GET_/status)。
    • Description フィールドはオプションで、メソッドをより詳細に説明する場合に使用することができます。

      New Method Details
  4. 最後に、Create Method をクリックします。

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

メソッドおよびメトリクスのシステム名を変更する場合やそれらを削除する場合は、十分に注意してください。メソッドの変更前のシステム名/削除したメソッドをポイントするマッピングルールがあると、これらの変更によりデプロイ済みの 3scale インテグレーションが機能しなくなります。

新たなメトリクスを作成するには、New metric をクリックして必要なパラメーターを指定します。単位を指定する際には、単数形の名詞 (例:hit) を使用します。Analytics のグラフでは、自動的に複数形になります。

これらの新たなメソッドおよびメトリクスは、現在および今後のすべてのプランで使用することができます。これ以降、各プランでメソッド/メトリクスに対する制限および課金ルールを編集することができます ([Your_product_name] > Applications > Application Plans > [plan_you_want_to_edit] の順に移動)。

9.2. メソッドおよびメトリクスの自動インポート

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

第10章 アプリケーションプラン

アプリケーションプランでは、API の利用者に許可するアクセス権限のさまざまなセットを定義します。これらのプランで、流量制御からアクセス可能なメソッドまたはリソース、有効な機能に至るまで、あらゆる設定を定義することができます。

10.1. アプリケーションプランの作成方法

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

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

  1. [Your_product_name] > Applications > Application Plans の順に移動します。
  2. Create Application Plan のボタンをクリックします。
  3. Create Application Plan のページで、新しいプランの名前およびシステム名を入力します (システム名は一意でなければなりません)。
  4. アプリケーションがご自分の API にアクセスする前に承認を要求する場合には、Applications require approval? のチェックボックスを選択します。

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

10.2. デフォルトのアプリケーションプランの設定

すべてのプランを作成したら、ユーザーがサインアップしてアプリケーションを登録する際のデフォルトプランを選択することができます。

デフォルトのアプリケーションプランを選択するには、以下の手順を実施します。

  1. [Your_product_name] > Applications > Application Plans の順に移動します。
  2. Default Plan セクションのドロップダウンリストからプランを選択します。

デフォルトのアプリケーションプランを指定しないと、新規ユーザーがご自分の API にアクセスするためにサインアップしても、デフォルトではアプリケーションは作成されません。つまり、ユーザーは API にアクセスすることができません。

第11章 マッピングルール

メソッドおよびメトリクスを追加して API を定義したら、API のエンドポイントまたはパスを Definition のページで定義したメソッドにマッピングすることができます。そのためには、以下の手順を実施します。

  1. [Your_product_name] > Integration > Mapping Rules の順に移動します。
  2. Add Mapping Rule のリンクをクリックします。
  3. HTTP メソッド、パターン、メトリクス (またはメソッド)、およびその増分を選択します。
  4. Create Mapping Rule のボタンをクリックします。
  5. マッピングルールを確認するには、[Your_product_name] > Integration > Methods & Metrics の順に移動します。各メソッドおよびメトリクスの Mapped 列に、チェックマークが付いているはずです。

    Mapping Rules verified

第12章 有料プランのプロビジョニング

API (プロダクトまたはバックエンドのいずれか) を収益化する最も一般的な方法の 1 つは、使用量に応じたサブスクリプション料を定義することです。本セクションでは、アプリケーションプランを使用して課金レイヤーをプロビジョニングする方法、および有料プランを設定する方法について説明します。プロダクトおよびバックエンドレベルに加えて、アカウントレベルで課金ルールを適用することもできます。これらのトピックは、本章の以降の項目で説明します。

12.1. 課金モデルの決定

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

  • ボリューム/使用量。ボリュームに基づいてレイヤー間を区別するのが最も一般的な方法です。通常ボリュームは、顧客に提供する価値およびサービスのコストと強い相関があるためです。プロダクトへの呼び出しにグローバルなヒットカウントを適用することや、メソッドレベルでより細かな粒度の測定を適用することができます。ボリュームドライバー は、グローバルな hits メトリクスレベルで、または hits 下の個々のメソッドに適用されます。どのメトリクスにも、複数の課金ルールを適用することができます。ヒット数の計算は、1 カ月の請求サイクルにわたって累積される点に注意してください。
  • 機能。レイヤーに応じて、プロダクトの特定部分へのアクセスを有効または無効にすることができます。これは、標準レベルとプレミアムレベルを区別するのに適した手法です。
  • リソース。他のリソース (顧客に価値を提供したり、ご自分のインフラストラクチャーでの費用発生の原因になったりする) へのアクセスに基づいて、レイヤーを作成することもできます。リソースの例としては、消費した帯域幅のギガビット数、ユーザーの数、またはトランザクションの値などが挙げられます。リソースドライバー はボリュームドライバーと類似していますが、カスタムメトリクスに適用されます。

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

12.2. アプリケーションプランへの課金ルールの設定

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

Create new application plan or edit existing

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

次に、「課金モデルの決定」で選択した課金ドライバーを設定します。

  1. [Your_product_name] > Overview > Applications > Application Plans の順に移動します。
  2. アプリケーションプランの名前をクリックします。
  3. Metrics, Methods, Limits & Pricing Rules セクションに移動します。ここで、総ヒット数のレベルで、メソッドのレベルで、またはその他のカスタムメトリクスに対して、課金ルールを定義することができます。

いくつかの課金ドライバーがすでにメトリクスとして存在する場合には、その項目を編集することができます。

課金ルールの設定が完了したら、Update Application plan をクリックします。

12.3. 追加課金レイヤーの作成

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

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

12.4. 有料プランのプロビジョニング

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

12.5. その他の参考情報

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

第13章 流量制御のプロビジョニング

流量制御により、API リソース (プロダクトおよびバックエンド) へのアクセスにスロットリングを適用することができます。アプリケーションプランを使用して、開発者グループごとに異なる制限を設定することができます。

流量制御の設定が完了すると、これらの制限により、開発者が 3scale バックエンドに承認を要求する呼び出しを行う際に受け取るレスポンスがコントロールされます。

13.1. アプリケーションプランの設定

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

アプリケーションプラン作成の詳細については、アプリケーションプラン を参照してください。

13.2. 流量制御の設定

流量制御を設定するには、以下の手順を実施します。

  1. [Your_product_name] > Overview > Applications > Application Plans の順に移動します。
  2. 設定するアプリケーションプランの名前をクリックします。
  3. Metrics, Methods, Limits and Pricing Rules までスクロールダウンします。
  4. Limits をクリックします。
  5. プロダクトまたはバックエンドレベルで制限を設定します。
  6. 必要な制限の設定が完了したら、Update Application plan をクリックして変更を保存します。

13.3. 新しい流量制御の適用

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

  • アラートを設定している場合には、通知を送信する時期を決定するのに新しい制限が使用されます。
  • 3scale バックエンドへの呼び出しの数を超えると、制限が考慮され、関連するエラーメッセージが表示されます。APIcast のエラーメッセージに関する詳細は、API ゲートウェイの管理の エラーメッセージの設定 を参照してください。

流量制御が有効になると、ダッシュボードに制限に達しつつあるユーザーが表示され、プランをアップグレードする可能性のあるユーザーをすばやく簡単に確認することができます。ソフトな制限およびハードな制限の詳細については、スタートガイドでアドバンストパスの アプリケーションプランによる API アクセスポリシーの設定 を参照してください。

13.4. 補足情報

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

パート V. 請求

第14章 請求設定の定義

本項では、3scale での請求機能の仕組みについて説明します。

請求設定は Charging & Gateway および Credit Card Policies からなり、共に管理ポータルの Audience > Billing で設定することができます。

14.1. Mode (Charging & Gateway)

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

  • 前払いモードでは、すべての固定費および開設費が月の初めまたはあん分した請求期間の初めに請求されます。変動費は、必ず翌月の初めに計算され請求されます。
  • 後払いモードでは、すべての固定費および変動費が翌月の初めに請求されます。

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

14.2. Charging enabled (Charging & Gateway)

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

14.3. Currency (Charging & Gateway)

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

14.4. Invoice footnote (Charging & Gateway)

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

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

14.5. Text to show if VAT/Sales Tax is 0% (Charging & Gateway)

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

この設定の詳細については、VAT レート/消費税 セクションを参照してください。

14.6. Billing periods for invoice ids (Charging & Gateway)

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

実際の ID
データベース内で請求書を一意に識別する。数値による ID で、請求書の URL に使用される (例: https://<dashboard_domain>/buyers/accounts/<acount_id>/invoices/<invoice_id>) と共に、Billing API で請求書 ID として使用されます。
平易な ID
請求書に表示される、人間にとって分かりやすい ID。平易な ID が重複していても技術的には問題ありませんが、3scale アカウント内で一意にすべきです。システムにより ID の重複が感知されると、This invoice id is already in use and should probably be changed という警告が表示されます。平易な ID が 24 時間以上 fix と表示される場合には、サポートにご連絡ください。

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

monthly (デフォルト)
YYYY-MM-XXXXXXXX: ID には、年、月、および請求書の番号が含まれます。たとえば 2018-02-00000013 というフォーマットになります。
yearly
YYYY-XXXXXXXX: 年および番号だけが含まれます。たとえば 2018-00000001 というフォーマットになります。

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

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

14.7. Credit Card Policies

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

  • 契約条項のページ
  • プライバシーポリシーのページ
  • 払い戻しポリシーのページ

14.8. クレジットカードゲートウェイ

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

  • Braintree
  • Stripe

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 つの鍵が必要です。テストを行う場合にはテストセットを使用し、課金を開始する準備ができたらライブセットを使用します。

Stripe Integration

14.8.1.3. 3scale 設定の定義

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

Billing page

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

Enable charging

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

Billing gateway

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

Stripe billing gateway

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

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

Developer portal - Billing

{% 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 キーを探します。

Braintree Settings

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

Braintree keys

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

Braintree keys

14.8.2.2. 3scale 設定の定義

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

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

Billing

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

Billing charging enabled

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

Billing Gateway

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

Ogone billing gateway

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

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

注記

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

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

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

第15章 課金設定

本セクションでは、API の使用に対して開発者に課金を行うさまざまな方法について説明します。

開設費
サービスのサブスクリプションに適用される 1 回限りの課金で、別のプランに切り替える場合には適用されません。サブスクリプションの初回月にのみ請求書/クレジットカードに現れます。アプリケーションプラン、サービスプラン、およびアカウントプランに設定することができます。
月額費用
毎月、繰り返し課金される費用です。サブスクリプションが月の途中で発生した場合には、日割り計算されます。固定費と呼ばれることもあります。アプリケーションプラン、サービスプラン、およびアカウントプランに設定することができます。
変動費
アプリケーションプランに設定された各メソッド/メトリクスに適用される課金ルールにより生じる費用です。この費用は API の使用量に基づくため、予め把握することはできず、請求期間が終了して初めて確定します。アプリケーションプランにのみ利用可能です。

If you have a plan with monthly cost of $10, but want to charge your developer a $5 setup fee. The initial charge would be for $15, while all subsequent charges would be for $10.

15.1. 課金ルール

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

例 1

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.

例 2

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.

例 3

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

注記

課金ルールは、メトリクスおよびメソッドに対して定義されます。実際の API リクエストは、マッピングルールを介してこれらのメトリクスおよびメソッドにマッピングされます。

15.2. 課金ルールの設定

  1. [Your_API_service] > Applications > Application Plans の順に移動します。
  2. 既存のアプリケーションプランを選択するか、新たなプランを作成します。
  3. Metrics, Methods, Limits & Pricing Rules セクションで、Pricing (x) をクリックして課金セクションを開きます。
  4. new pricing rule をクリックします。
  5. From、To、および Cost per Unit の値を設定し、Create pricing rule をクリックします。

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

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

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

15.3. 既存課金ルールの更新

  1. edit をクリックします。
  2. From、To、および Cost per Unit フィールドに関して、必要な修正を行います。
  3. Update pricing rule をクリックします。

第16章 請求書

開発者アカウントがいずれかの有料サービスにサブスクライブしている場合には、請求プロセスによりそのアカウントに対して請求書が作成されます。設定された支払いゲートウェイを使用して、請求書に対する課金が行われます。

16.1. 請求書の一覧表示

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

Total
キャンセル分を除くすべての請求書
In process
未確定、確定済み、および支払い待ちの請求書
Overdue
回収不能および課金に失敗した請求書
Paid
支払い済みの請求書

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

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

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

16.2. 請求書ビュー

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

16.2.1. 請求書の詳細

タイトルには、請求書の月および年、ならびに請求書が手動または自動請求プロセスで作成されたかが表示されます (例: Invoice for February 2018 (manually created))。

その下の Details ブロックには、請求書の平易な ID、請求書のステータス、請求書の確定/発行日、ならびに支払い期限および支払い日が表示されます。PDF ファイルがすでに生成されている場合には、PDF ファイルをダウンロードするためのリンクも表示されます。

Issued by および Issued to ブロックには、それぞれ API プロバイダーおよび開発者アカウントの名前および住所が表示されます。

その下は 費用項目 が含まれるブロックで、計算された VAT/消費税、合計費用、および Text to show if VAT/Sales Tax is 0% のテキスト (設定されている場合) が表示されます。

請求書の Transactions ブロックには、支払いのステータス、そのタイムスタンプ、参照番号、支払いゲートウェイからのメッセージ、および金額など、クレジットカードによる支払いの試みがすべてリストとして表示されます。参照番号を使用して、支払いゲートウェイの管理コンソールで支払いを探すことができます。

16.2.2. 請求書の編集

請求書が未確定または確定済みのステータスの場合には、請求書の詳細の一部を編集することができます。

請求書ビューの右上隅にある Edit のリンクをクリックすると、平易な ID および請求期間を変更することができます。

請求書の費用項目を追加および削除することもできます (合計、VAT/消費税、VAT/消費税込合計などの計算された費用項目を除く)。新たな費用項目を追加するには、Add をクリックして Name、Quantity (費用には影響を与えない)、Description、および Cost を入力します。

請求書ビュー最下部にあるリンクからは、請求書に対するアクションを実行することができます。請求書の現在のステータスに応じて、異なるアクションを実行することができます (例: PDF ファイルの生成、請求書の発行、請求書のキャンセル、PDF ファイルの再生成、課金、支払い済みの識別)。これらのアクション (PDF 関連を除く) により、請求書のステータスが変わります。

16.3. 請求書のステータス

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

Open
請求書は作成されたが、自動計算はまだ完了していない。
Finalized
現在の請求期間の課金項目がすべて請求書に反映されている。
Pending
請求書は開発者に発行され、支払い待ちである。
Unpaid
請求額に対する課金に失敗したが、自動リトライ待ちである。
Paid
請求額に対する課金が正常に行われている。
Failed
請求額に対する課金に失敗し、これ以上自動リトライは行われない。
Cancelled
管理者によってキャンセルされている。

16.4. 自動請求プロセス

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

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

16.4.1. 各月の初日

後払い

  • 月の変動費を請求する (費用は未確定請求書の費用項目に含まれます)。
  • 月の未確定請求書を確定する。
  • 月の固定費を請求する (当月用に新たな請求書を Open のステータスで作成します)。

前払い

  • 固定費を請求する ( 月)。
  • 変動費を請求する ( 月)。

月の初めに確定した請求書に関する通知が API 管理者に送信されるので、管理者は請求書を確認して必要な調整を行うことができます。

上記の処理に加えて、日々行われるすべての操作も、月の初日に発生します。

16.4.2. 毎日

  • トライアル期間が終了した契約およびまだ請求されていない新規契約を請求する (当月用に新たな請求書を Open のステータスで作成します)。
  • (前払い モードのみ) すべての未確定請求書を確定する (ステータスが Finalized に変わります)。
  • 請求書を発行する (ステータスが Pending に変わります)。

    • 通常、請求書は確定してから 2 - 3 日後に発行されます。請求書のIssued Onの日付はその日に設定され、Due Onの日付 (請求書に対する課金が行われる日) は Issued On の 2 日後に設定されます。
    • 請求書が開発者に発行されると、開発者はメール通知を受け取り、発行された請求書をデベロッパーポータルで確認することができます。
  • 請求書に対する課金を行う。

    • Due On の日付がその日またはそれ以前で、ステータスが Unpaid および Pending の請求書に対する課金が行われます。
    • 支払いが完了しなかった場合には、請求書のステータスは Unpaid に変わります。3 日後に課金がリトライされます。リトライに 3 回失敗すると、請求書のステータスは Failed に変わり、それ以上課金はリトライされなくなります。
  • クレジットカードの有効期限切れに関する通知を行う。

    • 間もなくクレジットカードの有効期限が切れる開発者アカウントに、メール通知が送信されます。

16.4.3. 自動および手動の請求書生成

自動請求プロセスによって生成された請求書のヘッダーには、(automatically created) のラベルが付きます。たとえば、Invoice for January 2019 (automatically created) というラベルが付きます。

手動で生成した請求書は、請求書の詳細ページで (manually created) と識別されます。

自動請求プロセスでは、当月 open のステータスにある既存の請求書を使用して、費用項目を追加する場合があります。ただし、その対象となるのは自動的に作成された請求書だけです。手動で作成した請求書は、自動請求プロセスにより更新されることはありません。

16.4.4. 期中のアップグレード

アプリケーション (またはアカウント/サービスサブスクリプション) が月の途中でアップグレードされた場合には、月額費用は残り日数に応じて日割り計算されます。アプリケーションプランで設定された制限はあん分されません。

アプリケーションが無料プランから有料プランにアップグレードされた場合には、次回の請求時に、日割り計算された月額費用を含む新しい請求書が生成されます。

アプリケーションが有料プランからより高額な有料プランにアップグレードされた場合には、さまざまな要素を加味して請求書が発行されます。

  • 請求のモード: 前払い後払い
  • いつプランが変更されたか

16.4.4.1. 前払い請求モード

  1. アプリケーションプランが 請求日 (請求日は 8am UTC に始まります) に 変更された場合には (つまり、アプリケーションプランに対する請求がまだ行われていない)、古いプランの固定費が請求書に記載され払い戻しの費用項目でディスカウントされます。新しいプランの固定費も請求書に追加されます。

    例: 顧客が月の初日にプラン A ($200) にサインアップし、同じ日に プラン B ($300) にアップグレードした。この場合には、以下の費用項目が含まれる 1 通の請求書が生成されます。

    説明費用

    固定費 (プラン A)

    200

    払い戻し (プラン A)

    -200

    アプリケーションのアップグレード (プラン A からプラン B へ)

    300

    Total

    300

    顧客が月の途中でサインアップした場合には、固定費の 200 および 払い戻しの 200 は日割り計算される点に注意してください。

  2. アプリケーションの 請求書がすでに発行された後に アプリケーションプランが変更された場合。

    • アップグレード の場合には、開発者には 2 通の請求書が発行されます。1 つは当初請求用で、もう 1 つはアップグレード用です。

      例: 顧客が月の初日にプラン A ($200) にサインアップした後に、月の途中でプラン B ($300) にアップグレードした。この場合には、以下のような請求書が生成されます。

      説明費用

      固定費 (プラン A)

      200

      Total

      200

      説明費用

      払い戻し (プラン A)

      -100

      アプリケーションのアップグレード (プラン A からプラン B へ)

      150

      Total

      50

      請求期間の途中でアップグレードが行われたので、2 通目の請求書では、払い戻された費用 ($100) および新たな費用 ($150) は日割り計算されます。

    • アプリケーションの ダウングレード (より低額なプランへの変更) に伴う払い戻しは、現在サポートされていません。

16.4.4.2. 後払い請求モード

後払い請求モードでは、払い戻し および アプリケーションのアップグレード に関する費用項目が含まれる 1 通の請求書が発行されます。

重要: この動作は、以下の変更と共に 2018 年 4 月 20 日 に導入されました。

  • アプリケーションが作成と同じ日にアップグレードされた場合に、当初請求額 (元のアプリケーションプラン用) が請求書に追加されない、というバグが修正されました。
  • 従来は、アプリケーションのアップグレード時には、新旧プランの差額に関する 1 つの費用項目しか追加されませんでした。たとえば、上記 前払い請求モード セクションで説明したシナリオ 2 では ($200 のプラン A から $300 のプラン B へのアップグレード)、2 番目に生成される請求書は以下のようになりました。
説明費用

アプリケーションのアップグレード (プラン A からプラン B へ)

50

Total

50

ここで、$50 は月の残りを考慮して日割り計算した新旧プランの差額です ($150 - $100)。

2018 年 4 月 20 日 以降は、合計費用は以前と同じままですが、請求書の計算がより明確に反映され、払い戻しと課金が別々に追加されるようになりました。

16.5. アカウントごとの請求/課金の有効化/無効化

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

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

  • Monthly billing is enabled/disabled
  • Monthly charging is enabled/disabled

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

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

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

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

16.6. トライアル期間が設定されたプラン

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

アプリケーションのトライアル期間のステータスは、アプリケーションリスト ([Your_product_name] > 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 プロバイダーに連絡する必要があります。

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

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

16.7. VAT レート/消費税

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

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

16.7.1. VAT rate フィールドの設定

VAT レートは、請求書の合計費用に適用される数値です (パーセント単位)。VAT レートを設定するには、管理ポータルの Dashboard から以下の手順に従います。

  1. Audience > Accounts > Fields Definitions の順に移動します。
  2. Account セクションで Create をクリックします。
  3. [new field] のドロップダウンリストで vat_rate を選択します。
  4. Label の値を設定します。
  5. チェックボックスを設定して、開発者に対してフィールドを Required (必須) とするか、Read only (読み取り専用) とするか、または Hidden (非表示) とするかを定義します。

    注記:Choices フィールドに入力することができるのは文字列だけです。したがって、このフィールドを使用することはできません。

  6. Create をクリックします。

16.7.2. VAT code フィールドの設定

VAT コードは、VAT の識別番号です。VAT コードを設定するには、管理ポータルの Dashboard から以下の手順に従います。

  1. Audience > Accounts > Fields Definitions の順に移動します。
  2. Account セクションで Create をクリックします。
  3. [new field] のドロップダウンリストで vat_code を選択します。
  4. Label の値を設定します。
  5. チェックボックスを設定して、開発者に対してフィールドを Required (必須) とするか、Read only (読み取り専用) とするか、または Hidden (非表示) とするかを定義します。
  6. Create をクリックします。

16.7.3. アカウントの VAT 値の設定

VAT code および VAT rate フィールドを追加したら、開発者アカウントの Edit フォームで対応する値を設定することができます。フィールド定義で選択したチェックボックスに応じて、開発者はデベロッパーポータルでフィールドを表示したり編集したりすることもできます。

VAT コードには任意の文字列を使用することができます。

VAT レートは数値でなければなりません。整数または小数のいずれかを設定可能で (例: 21、23.5)、VAT として含まれる費用のパーセンテージを表します。

16.7.4. VAT が含まれる請求書

ゼロではない VAT レートが設定された開発者アカウントに対して請求書が生成されると、請求書には以下の費用項目が含まれます。

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

<VAT rate> は、VAT rate フィールドで設定した Label の値に置き換えられます。<VAT rate value> は、請求書が発行されるアカウントに設定した値です。

VAT コードは、VAT コードのフィールド定義で Label として指定したラベルと共に、請求書の PDF バージョンに追加されます。値は、開発者アカウントの詳細で設定された値に対応します。

フィールド vat_rate および vat_code は、3scale Account Management API からでも読み取りおよび書き込みが可能です。

16.8. デベロッパーポータルビュー

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

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

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

注記

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

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

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

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

16.9. クレジットカードに関する作業フロー

16.9.1. 有料プランへのサインアップ

開発者が有料プランにサインアップすると、アプリケーションのクレデンシャルを表示するために、クレジットカード情報の入力が要求されます。開発者が初めてデベロッパーポータルにログインすると、Credit Card Details のページにリダイレクトされます。開発者アカウントの他のページにアクセスを試みても、再び Credit Card Details のページにリダイレクトされます。

Liquid タグを使用してすべてのメニュー項目を非表示にすることができます。ただし、該当するデベロッパーポータルテンプレートをカスタマイズして、Credit Card Details タブを除外することができます。

current_account Liquid drop はメソッド requires_credit_card_now? を公開します。このメソッドは、クレジットカード情報が登録されていないが必要な場合 (管理ポータルで Billing が設定されている場合のみ) には true を返し、それ以外の場合には false を返します。

submenu および users_menu パートのメニュー項目およびその他のユーザーインターフェイス要素を、非表示にすることができます。そのためには、それらを以下の条件でラップします。

{% unless current_account.requires_credit_card_now? %}
...
{%  endunless %}

16.9.2. 無料プランから有料プランへのアップグレード

既存アプリケーションのプラン変更については、複数のオプションを設定することができます (例: 開発者が直接プランを変更する、開発者がプランの変更を要求する等)。アプリケーションを無料プランから有料プランにアップグレードする場合には、アップグレードの前に開発者がクレジットカード情報を入力していることが重要です。カード情報の入力方法は、[Your_product_name] > Integration > SettingsAPPLICATION PLAN CHANGING セクションで、以下のオプションにより設定することができます。

開発者がクレジットカードを所有している場合には、直接プランを変更します。それ以外の場合には、
・プラン変更の要求だけをする
・有料プラン用にクレジットカード情報の入力を要求する

開発者が変更を要求することだけを許可する場合には、最初のオプションを選択してください。この場合、クレジットカード情報が入力された後に手動でアップグレードを実行します。

有料プランにアップグレードするにはクレジットカード情報を入力する必要があることを開発者に通知する場合には、2 番目のオプションを選択してください。プラン変更のウィジェットで開発者に You cannot change plan until you enter your Credit Card details というメッセージが表示され、クレジットカード情報のフォームがポイントされます。

16.10. 請求先住所フィールド

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

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

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

  1. Audience > Accounts > Fields Definitions の順に移動します。
  2. Account ブロックで Create をクリックします。
  3. ドロップダウンリストから billing_address を選択し、ラベルを追加して Read only のチェックボックスを選択し、Create をクリックします。

これで、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

第17章 メール通知

請求に関するさまざまなイベントがトリガーとなり、API プロバイダーおよび開発者にメール通知が送信されます。

17.1. プロバイダーへの通知

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

Action required: review invoices
請求サイクル最終日の数日前に送信されるので、顧客に送信する前に請求書を確認することができます。
Customer downgraded
顧客がより低額の月額固定プランに変更した際に送信されます。
Expiring credit card
間もなく顧客のクレジットカードの有効期限が切れる場合に送信されます。
Payment error (retry)
課金に失敗し、請求書のステータスが Unpaid となりリトライ対象となった場合に送信されます。
Payment error (final)
課金の最後のリトライに失敗し、請求書のステータスが Failed となった場合に送信されます。

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

17.2. 開発者へのメール通知

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

Credit card expired notification for buyer
間もなくクレジットカードの有効期限が切れる場合に送信されます。
Invoice charged successfully for buyer
請求書に対する課金が正常に完了した場合に送信されます。
Invoice charge failure for buyer with retry
請求書に対する課金に失敗し、請求書が Unpaid のステータスとなり、課金のリトライが行われる場合に送信されます。
Invoice charge failure for buyer without retry
請求書に対する 3 回目の課金に失敗し、請求書が Failed のステータスとなり、それ以上課金のリトライは行われません。
Upcoming invoice charge for buyer
請求書が開発者に発行された場合に送信されます。

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

17.2.1. 請求に関するメールアドレス

請求に関する問題を解決するために顧客が連絡することのできるメールアドレスを設定することができます (例: billing@example.com)。その設定は、Audience > Messages > Support EmailsFinance support email フィールドで行います。

電子メールのテンプレートは、Liquid drop {{ provider.finance_support_email }} を使用してメールアドレスを参照します。

第18章 Billing API

Billing API により、共通的な請求プロセスを自動化することができます。

Billing API のすべてのエンドポイントは、管理ポータルの Documentation (?) > 3scale API Docs > Billing API で確認することができます。

Billing API には、以下の要件を満たす有効なアクセストークンが必要です。

  • プロバイダーアカウントの管理ユーザーまたは Billing 権限を持つメンバーユーザーのいずれかに属していること
  • Billing API スコープが含まれていること

パラメーターとして請求書 ID が必要な場合には、平易な請求書 ID ではなく 請求書 ID を指す点に注意してください。

API エンドポイントの XML レスポンスは見て直ぐに理解でき、請求書のフィールドは Web および PDF 版の情報と同じ内容を示しています。

注意を要するレスポンスのフィールド

  • creation_type:manual(手動で作成された請求書の場合) またはbackground(3scale の自動請求プロセスにより作成された請求書の場合) どちらかの値をとります。
  • provider: API プロバイダー (管理アカウント) の詳細で、請求書の Issued by セクションに対応します。
  • buyer: 開発者アカウントの詳細で、請求書の Issued to セクションに対応します。

XML 版の請求書には、line-items フィールドに費用項目のリストも含まれます。

一部の費用項目 (特に自動的に作成された項目) では、一般的な名前、説明、量、および費用 (価格) 以外に、以下の項目が表示されます。

  • type: 費用項目のタイプで、以下の値を取ります。

    • LineItem::PlanCost: 定額プランの費用項目の場合
    • LineItem::VariableCost: 変動費の費用項目の場合
  • metric_id: 変動費の費用項目用で、費用が関連付けられているメトリクスの ID
  • contract_id: 費用が関連付けられているサービスまたはアプリケーションの ID

パート VI. 開発者アカウントの管理

第19章 開発者の追加

API へのアクセス用に新たな開発者アカウントを追加する手順を以下に示します。

手動で開発者を招待するワークフローを設定している場合に、ここでは新たな開発者を追加する方法について説明します。

19.1. 新たな開発者アカウントの作成

  1. 管理ポータルの Audience セクションで、Accounts のリンクをクリックします。
  2. Create をクリックします。

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

Create new developer account

19.2. アプリケーションの設定

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

Add applications to new account

19.3. 開発者への通知

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

第20章 開発者の承認

本セクションでは、サインアップワークフローの各ステップで承認を行う方法について説明します。

手動の承認ステップを含むサインアップワークフローを実装したら、いくつかのオプションを選択することができます。承認プロセスには、そのトリガーおよび承認の対象によって若干の違いがあります。メール通知を受け取った場合には、次のセクションの指示に従ってください。それ以外の場合には、承認の対象 (アカウント、サービス、またはアプリケーション) より手順が異なります。

20.1. メール通知からの承認

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

20.2. アカウントの承認

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

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

Developer approval account signup

20.3. サービスの承認

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

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

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

Developer approval service subscription

20.4. アプリケーションの承認

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

  1. Audience > Applications > Listing の順に移動します。
  2. State のドロップダウンリストで Pending を選択し、Search をクリックします。

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

Developer bulk approvals apps

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

Developer individual app approval 1
Developer individual app approval 2

第21章 アプリケーションプランの変更

本セクションでは、アカウント、サービス、またはアプリケーションのプランを変更する方法について説明します。

管理者は、自分の判断で、または開発者からのプラン変更要求に対応して、開発者のプランを変更する場合があります。

注記

プラン変更の手順には、変更するプランのタイプごとに若干の違いがあります。

21.1. アカウントプランの変更

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

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

developer change account plans

21.2. サービスプランの変更

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

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

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

Change service plan

21.3. アプリケーションプランの変更

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

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

Change plans for multiple applications

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

Change application plan

21.3.1. 補足情報

別の標準プランに変更するのではなく、1 つの特定アプリケーション用のプランに変更を加えるだけの場合には、プランのカスタマイズ 機能を使用することができます。

第22章 開発者への連絡

本章では、特定のアプリケーションを管理する開発者アカウントを把握して、3scale 機能および外部の手段を使用して開発者と連絡を取る方法について説明します。

API の運用中に、API を使用している開発者に緊急に連絡を取らなければならない場合があります。

22.1. システム内の該当アプリケーションおよびアカウントの把握

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

Accounts View

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

22.2. 開発者への内部メッセージの送信

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

Send message

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

22.3. 他の手段による連絡

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

  • 企業アカウントページ (一般的な連絡先情報が主ですが、電話番号が含まれる場合があります)
  • ユーザー独自ファイルの開発者/ユーザー固有情報

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

第23章 プランのカスタマイズ

本セクションでは、特定の開発者向けにアプリケーションプランをカスタマイズする方法について説明します。

アプリケーションプランは、開発者コミュニティーのさまざまなグループに標準ポリシーを適用するのに適しています。ただし、独自の要件を持つ個々の開発者向けに、標準プランを柔軟にカスタマイズすることができます。

プランをカスタマイズすると、元のプランへのリンクは失われます。元のプランに変更を加えても、カスタムプランではこれらの変更は継承されません。したがって、カスタムプランが多くなりすぎて効果的に管理できなくならないように、このカスタマイズ機能は慎重に使用する必要があります。

開発者は、現在の請求期間がすでに始まっているので、次の価格帯にアップグレードせずに現在の制限を引き上げることを希望します。制限を引き上げ発生した変動費だけを請求するカスタマイズは、この状況に対処するのに適した手段です。このカスタマイズは、次の請求月にアップグレードを奨励するのにも役立ちます。

23.1. アカウントの選択

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

  1. Audience > Accounts > Listing の順に移動します。
  2. 開発者アカウントを選択します。
Select Account

23.2. アプリケーションの選択

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

Select App

23.3. アプリケーションプランのカスタマイズ

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

Customize Plans

23.3.1. 補足情報

プランのカスタマイズを開始する前に、必ず初めに新しい標準プラン (デベロッパーポータルで非表示にすることができる) の方が良いかどうかを検討してください。標準プランが望ましければ、標準プランに変更 します。そのプランが複数の開発者パートナーに適用される場合には、再利用のメリットを得ることができます。

第24章 セルフサービスによるサインアップの有効化

セルフサービスモードまたは手動モードを実装して、開発者のサインアップを設定します。

開発者のサインアップワークフローを、セルフサービスまたは手動の招待のみのいずれかに設定することができます。セルフサービスのサインアップは、開発者がデベロッパーポータルを通じて行います。一方、手動の招待は管理者が管理ポータルを通じて処理します。

デフォルトでは、開発者は自分でサインアップを行うことができます。開発者のセルフサービスを有効にした場合には、開発者アカウントをアクティブにするのに、管理者承認を要求することができます。

そのためには、Audience > Accounts > Settings > Usage Rules の順に移動します。

Enable self-service developer signup

第25章 アプリケーションの特定

本章では、名前、API キー、またはアプリケーションの ID のいずれかを元に、管理ポータルでアプリケーションを素早く特定する方法について説明します。

API の運用中に、ご自分の API にアクセスしているアプリケーションに関する情報を素早く把握しなければならない場合があります。サポートを提供する、設定を変更する、またはアプリケーションが誤動作しているので無効にする必要がある、等がその理由として挙げらます。

25.1. 必要な情報の入手

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

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

  • API キーのみによる認証パターン: API キー
  • アプリケーション ID とアプリケーションキーによる認証パターン: アプリケーション ID (アプリケーションキーによる検索はサポートされません)
  • OpenID Connect による認証パターン: client_id (シークレットによる検索はサポートされません)

25.2. アプリケーションの検索

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

Finding an application part 1

25.3. アプリケーション情報へのアクセス

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

Finding an application part 2

第26章 開発者の招待

開発者アカウントに新しい開発者ユーザーを追加する方法を、以下の手順に示します。

開発者アカウントを手動で作成する場合には、管理ポータルから開発者ユーザーをそのアカウントに招待することができます。

  1. Audience > Accounts > Listing の順に移動します。
  2. 対象のアカウントを選択します。
  3. Invitations を選択し、続いて Invite user をクリックします。
Developer invite user

第27章 開発者のサービスからのサブスクライブ解除

管理者は、開発者のサービスへのサブスクライブを解除することができます。特定の 1 人の開発者または複数の開発者 (サービスが非推奨となった場合) に対して、この操作を実施しなければならない場合があります。

27.1. 1 人の開発者のサービスからのサブスクライブ解除

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

  1. 管理ポータルの Dashboard で、Audience > Accounts > Listing > [select an account] > Service Subscriptions の順に移動します。
  2. 開発者のサブスクライブを解除するサービスの Unsubscribe を選択します。

27.2. 複数開発者のサービスからのサブスクライブ解除

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

注記

この手法を適用することができるのは、削除された/一時中断されたサービスだけです。アクティブなサービスに対して、一括のサブスクライブ解除処理を行うことはできません。

  1. Dashboard で、Audience > Accounts > Subscriptions の順に移動します。
  2. 一括でステータスの変更を行います。
  3. サービスのドロップダウンメニューを使用して、開発者のサブスクライブを解除するサービスを選択します。
  4. 左側のチェックボックスを使用して、サブスクライブを解除する開発者を選択します。
  5. Change state > Suspend の順に選択し、選択した開発者のサブスクリプションを一時中断します。

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

第28章 アプリケーションの一時中断

本章では、アプリケーションのキーおよびアクセストークンをすべて無効にする方法について説明します。

アプリケーションがご自分の API を誤用し、他のトラフィックに影響を及ぼしている場合には、担当する開発者に連絡してコードまたは設定の修正を依頼する前に、直ちにその運用を一時中断しなければならない場合があります。

28.1. アプリケーションの特定

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

28.2. アプリケーションの無効化

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

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

Suspend an Application
注記

エージェントでキャッシュを使用している場合には、直ちに一時中断されず若干時間を要する場合があります。

28.3. 開発者への連絡

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

Contact Developer

第29章 アプリケーションの削除

管理ポータルからアプリケーションを削除するには、以下の手順に従う必要があります。

オプション 1: [Your_API_name] の全アプリケーションのリストからアプリケーションを削除する。

  1. Dashboard で [Your_API_name] をクリックします。
  2. Overview タブをクリックします。
  3. Overview のページの左側パネルで、Applications をクリックします。
  4. Listing を選択します。
  5. アプリケーションをクリックします。
  6. アプリケーションの詳細が含まれるページが表示されます。Edit をクリックします。
  7. アプリケーションを削除するには、Delete をクリックします。
  8. 確認メッセージが表示されます。OK をクリックして削除を確認します。

オプション 2: 特定のアプリケーションプランに基づいてアプリケーションを削除する。

  1. 管理ポータルで、Dashboard をクリックします。
  2. API を選択します。
  3. Published Application Plans セクションで、アプリケーションを選択します。
  4. アプリケーションをクリックします。
  5. アプリケーションの詳細が含まれるページが表示されます。Edit をクリックします。
  6. アプリケーションを削除するには、Delete をクリックします。
  7. 確認メッセージが表示されます。OK をクリックして削除を確認します。

あるいは、Application Delete という操作により、3scale API Docs を介してアプリケーションを削除することもできます。

第30章 API の削除

API のサービスを削除して、API を削除することができます。サービスを削除すると、API のアプリケーション、アプリケーションプラン、メトリクス、課金ルール、機能、サービスプラン、およびサブスクリプションが削除されます。

API を削除するには、以下の手順を実施します。

  1. [Your_product_name] > Overview > Edit の順に移動します。
  2. サービスの削除セクションで、リンクをクリックしてサービスを削除します。

パート VII. 解析

第31章 API の解析

本章は、API の解析をカスタマイズし、最も使用されているアプリケーションや時間と共に傾向が変化する様子を確認する等、把握すべき項目を追跡するのに役立つように意図されています。トラフィックを管理し、ピーク時に対応し、API に最も多くのリクエストを送信しているユーザーを特定するためには、ご自分の API がどのように使用されているかを知ることが重要なステップとなります。

3scale では、API 解析の追跡に使用するメソッドおよびメトリクスを、以下に示す 2 つのレベルで定義することができます。

  • プロダクト: Hits メトリクスは、Hits 自身および対応するメソッドにマッピングされたヒット、ならびにバックエンドレベルの Hits メトリクスおよびそのメソッドにマッピングされたすべてのヒットをカウントします。
  • バックエンド: 3scale では、メソッドおよびメトリクスが API バックエンドに登録されます。これにより、メソッドおよびメトリクスがバックエンドを使用する各プロダクトに属するかのように機能します。バックエンドレベルのメトリクスの制限および課金ルールを、プロダクトレベルで定義されるアプリケーションプランに設定することができます。

31.1. 前提条件

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

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

31.2. 追跡するメトリクスとメソッドの決定

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

  • Hits/transactions: API プロダクトへの呼び出しの数。Hits は、すべての API にデフォルトでメトリクスとして含まれています。Hits は、API プロダクトへの全呼び出し数とすることも、API プロダクトの個々のメソッドにブレークダウンすることもできます。
  • Data transfer: API プロダクトを通じてアップロードおよびダウンロードされたデータ量 (MB/GB 単位)
  • CPU hours: API プロダクトへの呼び出しに関連する処理時間 (またはその他の内部リソース)
  • Results returned: 返されているレコードまたはデータオブジェクト数のカウント
  • Disk storage: アカウントにより使用されているディスクストレージの合計

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

31.3. メトリクスおよびメソッドの作成

メトリクスを選択したら、それらを管理ポータルで登録します。

  • プロダクトにメソッドおよびメトリクスを追加するには、[Your_product_name] > Integration > Methods & Metrics の順に移動します。
  • バックエンドにメソッドおよびメトリクスを追加するには、[Your_backend_name] > Methods & Metrics の順に移動します。

選択したプロダクトまたはバックエンドにメトリクスおよびメソッドを追加することができます。それらに分かりやすい名前およびシステム名を設定します (3scale はこれらの名前をプラグイン設定で使用します)。メソッドおよびメトリクス作成の詳細については、3scale での API の定義 (メソッドおよびメトリクス) を参照してください。

31.4. レポートの設定

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

レポートを設定する際には、以下の点を考慮してください。

  • アプリケーションは、着信 API コールで決められたとおりに、適切なメトリクス/メソッド名をプラグインに渡す必要があります。必要なメトリクス/メソッドの値および増分は、プラグインが公開する承認またはレポートメソッドの引数です。
  • 特定の API メソッドのトラフィックを報告する場合には、メトリクスの引数で system name メソッドを使用します。これにより、報告されたメソッドと hits メトリクスの両方のカウンターに、自動的に増分が加算されます。
  • 3scale Service Management API を使用して、トラフィックを報告することもできます。さまざまなエンドポイントについての補足詳細は、3scale APIs ActiveDocs (管理ポータルの Documentation → 3scale API Docs からアクセス可能) を参照してください。

31.5. トラフィックが正しく報告されることの確認

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

  1. Audience > Applications > Listing の順に移動し、既存アプリケーションのリストを表示します。
  2. 名前をクリックしてアプリケーションを選択します。
  3. 選択したアプリケーションの API クレデンシャルを確認します。クレデンシャルは選択した認証タイプによって異なり、ユーザーキー (API キー)、アプリケーション ID とアプリケーションキー、またはクライアント ID とクライアントシークレットのいずれかです。利用可能な認証モードの詳細については、認証パターン に関するドキュメントを参照してください。

    図31.1 API クレデンシャル

    API credentials
  4. これらのキーを使用して、通常の方法で API を呼び出します。たとえば、cURL を使用してコマンドラインから呼び出すか、GET メソッドを使用して API エンドポイントのブラウザーから呼び出します。呼び出しの詳細は、実際の API プロダクトのメソッド構造により異なります。これらの呼び出しからのトラフィックが、API プロダクトの Analytics セクションに表示されます。

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

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

  • 承認/レポート呼び出しは正常に応答しているか ?

    すべてのプラグインは 3scale Service Management API を呼び出しますが、この API には事前に定義されたレスポンスコードがあります。有効なキーによる承認呼び出しは、HTTP コード 200 と共にレスポンスを返します。レポート呼び出しは、コード 202 と共に応答します。

  • インテグレーションエラーコンソールにエラーは表示されていないか ?

    3scale によって検出されたインテグレーションエラーのログは、[your_product_name] > Analytics > Integration Errors で確認することができます。

  • 正しいメトリクスおよびメソッド名が使用されているか ?

    異常が発生する最も一般的な原因は、レポート呼び出しに渡されるメソッドおよびメトリクス名が、ご自分の管理ポータルの API 設定で作成される名前に対応していないことです。それぞれのメトリクス/メソッドについて、正しい システム名 が使用されていることを確認してください。

31.7. 解析の表示権限の制御

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

31.8. API およびメールレポートによる解析データの取得

Analytics セクションの使用状況グラフ以外にも、以下の手段により解析データにアクセスすることができます。

  • Analytics API

    3scale Analytics API により、API プロダクトのすべての解析データを、XML または JSON いずれかの形式で柔軟に抽出することができます。

第32章 解析機能の拡張

本章では、スクリプトを作成して 3scale に組み込まれた現在の解析機能を拡張する方法について説明します。

Account Management API および Analytics API を使用すると (Enterprise のみ)、必要な情報を希望の形式で取得するスクリプトを作成することができます。本章では特定のユースケースについて説明しますが、同じ手法を使用して必要なデータを 3scale から取得することができます。

32.1. カスタムスクリプトが重要な理由

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

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

32.2. 具体的な例

あるお客様は、毎週、数千人もの新規開発者を受け入れていました。3scale では必要な作業 (キーのプロビジョニング、サインアップワークフロー、電子メールによる連絡など) が自動化されているため、このお客様は受け入れプロセスにある程度対応することができていました。しかし、お客様にとって非常に重要だが、3scale では実施できないことがありました。

お客様は多数の開発者を受け入れていたため、運用およびマーケティングチームが新規開発者とより効果的に交流できるように、API の使用状況に応じて新規開発者を分類するためのシンプルな手段が必要でした。このような機能は、少なくとも求められるレベルの詳細さでは、3scale で提供される組み込み解析ツールではまだ利用することができませんでした。しかし、すべてのデータにはシステムからアクセスすることができたので、3scale の Account API および Analytics API を使用してそのデータを抽出することができました。

32.3. 例: お客様の要求

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

まず、サインアップはしたがお客様の API を全く使用しなかった開発者の数を知りたいと考えました。

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

  • ある期間 (10 日間のうち初めの 5 日間など) API を使用した後、使用を止めた開発者。これらの開発者は、使ってはみたがアクティブではなくなったグループです。
  • API を継続的に使用している開発者。このグループについては、使用率の増加 (または減少) を知りたいと考えました。

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

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

32.4. 実際の実装

32.4.1. 最高のレシピ

カスタム作業を行う際に、このレシピでより良い結果が得られます。

  • ActiveDocs について少し見てみましょう。3scale ActiveDocs は、管理ポータルの Account Settings (右上隅の歯車アイコン) > Integrate > 3scale API Docs から利用可能です。3scale の API は、すべて ActiveDocs として利用可能です。したがって、ブラウザーから使用することができます。これにより、ニーズに最適なリクエストを探し、リクエスト (curl に類似) を取得し、レスポンスを得ることができます。以下に例を示します。

    DIY Analytics

これは、解析機能を拡張するスクリプトで使用されるすべてのアプリケーションを取得する API リクエストの ActiveDocs です。

  • ActiveDocs の調査を完了したら、リクエストを好みのスクリプト言語に落とし込みます (当社の場合は平凡な Ruby です)。
  • 希望の処理を実行するスクリプトが書き上がるまで、この作業を繰り返します。解析機能の拡張を例に取ると、ここから スクリプトを確認することができます。これをご自分のアカウントで試すことができます。

ActiveDocs により、API のできることを素早く理解することができます。後は、実行したいタスクに必要な 3 つか 4 つのリクエストを探し、スクリプトを 1 つにまとめます。

32.4.2. ステップバイステップのガイド

このお客様が必要としたカスタム解析機能を得るために実施したステップを以下に示します。

  1. 全アプリケーションのリストを取得する。この操作にはページネーションが必要です。

    def api_call_applications_list(domain, provider_key)
      done = false
      res = Array.new
      page = 1
    
          while !done
        url = "https://#{domain}/admin/api/applications.xml?provider_key=#{provider_key}&page=#{page}&per_page=100"
        page += 1
        response = RestClient.get url
        raise Exception.new("Wrong response code (#{response.code}) in request #{url}") if response.code!=200
        document = Nokogiri::XML(response.to_str)    done = document.xpath("applications/@current_page").text == document.xpath("applications/@total_pages").text
        document.xpath("//application").each do |item|
          app = Hash.new
          app["created_at"] = DateTime.parse(item.xpath("created_at").text)
          app["plan_name"] = item.xpath("plan/name").text
          app["service_id"] = item.xpath("plan/service_id").text
          app["account_id"] = item.xpath("user_account_id").text
          app["id"] = item.xpath("id").text
          res << app
        end
      end
      return res
    end
  2. 条件を満たしていないアプリケーションを除外する (評価版のプランで、かつ 10 日前以降のものに絞り込む)。

    def filter_applications(domain, provider_key, plan_name, num_of_days)
      res = api_call_applications_list(domain, provider_key)
      res.each do |item|
        res.delete(item) if item["plan_name"] != plan_name
        res.delete(item) if item["created_at"] > (DateTime.now - num_of_days)
      end
      return res
    end
  3. 続いて、条件を満たすそれぞれのアプリケーションについて、その使用状況 (過去 10 日間のアプリケーションのヒットカウント) を取得する。

    def api_call_application_usage(domain, provider_key, application_id, metric, from, to, granularity)
      url = "https://#{domain}/stats/applications/#{application_id}/usage.xml?provider_key=#{provider_key}&metric_name=#{metric}&since=#{from}&until=#{to}&granularity=#{granularity}"
      response = RestClient.get url
      raise Exception.new("Wrong response code (#{response.code}) in request #{url}") if response.code!=200
      document = Nokogiri::XML(response.to_str)
      return document.xpath("//usage/data/values").text.split(",")
    end
  4. 開発者の情報はアカウントオブジェクトに保存されるため、アプリケーションをアカウントに紐付けする。

    def api_call_account_read(domain, provider_key, account_id)
      url = "https://#{domain}/admin/api/accounts/#{account_id}.xml?provider_key=#{provider_key}"
      response = RestClient.get url
      raise Exception.new("Wrong response code (#{response.code}) in request #{url}") if response.code!=200
      document = Nokogiri::XML(response.to_str)
      account = Hash.new
      account["email"] = document.xpath("//users/user/email").text
      account["name"] = document.xpath("//users/user/first_name").text + " " + document.xpath("//users/user/last_name").text
      return account
    end

    後はすべてを 1 つにまとめるだけで、スクリプトは完了です。このスクリプトで、3scale に組み込まれた解析機能ではまだ利用できなかった情報を取得することができます。完成したスクリプト を参照してください。

32.5. まとめ

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

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

第33章 標準の解析機能

本チュートリアルでは、アプリケーションのトラフィックに関するビジュアル情報を取得する方法について説明します。

API を使用する各アプリケーションには、3scale システムのトラフィックトレースがあり、管理ポータルから表示できるだけでなく、API によって復元することもできます。

アプリケーションのトラフィック解析を表示するには、以下の手順を実施します。

  1. 解析を表示するアプリケーションに移動します。

    Audience > Accounts > Listing または Audience > Applications > Listing の順に移動し、Applications タブでアプリケーションを特定することができます。あるいは、 アプリケーションの特定 に記載のチュートリアルにの手順に従って、アプリケーションを検索することができます。

  2. アプリケーションを特定すると、以下の図に示すようなアプリケーションに関する情報が含まれる概要ページが表示されます。

    Application display

    図でラベルを付けた項目が、それぞれ以下の情報に対応しています。

    1. 開発者が指定したアプリケーションの名前
    2. アプリケーション用に取得されたメタデータ (取得するデータの設定方法については、アドバンストセクションで説明します)
    3. アプリケーションのステータス (Live または Suspended)
    4. アプリケーションの現在有効な API 識別子、キー、および証明書。このビューは、API を 3scale に統合する際に使用する認証方法により異なります。
    5. アプリケーションのトラフィックに関する統計の要約
    6. アプリケーションに適用されるアプリケーションプランおよび適用される流量制御に関する情報
  3. アプリケーション名の上にある Analytics のリンクをクリックします。アプリケーションの使用状況に関するチャートが表示されます。メトリクス、メソッド、および時間範囲を変更すると、アプリケーションに関するさまざまなタイプのデータを確認することができます。

第34章 レスポンスコードの追跡

本チュートリアルでは、3scale システムでレスポンスコードのログを設定して使用する方法について説明します。

API プロダクトからのレスポンスコードを追跡することで、顧客の API の使用状況を把握し、サーバーに問題がないかどうかをリアルタイムで確認することができます。

レスポンスコードの追跡機能を有効にするには、Docker または OpenShift デプロイメントを使用して APIcast ゲートウェイを起動する際に、APICAST_RESPONSE_CODES 環境変数を 1 または true に設定します。

有効にすると、APIcast ゲートウェイは、承認呼び出しに関してアップストリームサービスによって返される API レスポンスの HTTP ステータスコードを取得し、それらを Service Management API に送信します (authrep コール)。以下に例を示します。

https://su1.3scale.net/transactions/authrep.xml?service_token={SERVICE_TOKEN}&service_id={SERVICE_ID}&user_key={USER_KEY}&usage%5Bhits%5D=1&log%5Bcode%5D=200"

上記の例では、log[code]=200 が送信されています (API が 200 のステータスコードと共に応答した)。

インテグレーションを確認するには、有効な 3scale クレデンシャルを使用して API プロダクトを呼び出してから、Analytics > Usage のページで呼び出しが正しく報告されたことを確認します。

注記
  • 応答コード追跡は、すべての応答を正確にカウントすることを意図したものではありません。
  • このビューの価値は、一定期間の傾向を視覚的に表現することです。
  • Response Code Tracking と 3scale Auth Caching モード: None は、サポートされている組み合わせではありません。
Usage screen

ここまで問題がなければ、Analytics >Response codes のページに移動します。レスポンス (2xx、4xx、または 5xx) に応じて色分けされた最新トラフィックのグラフが表示されるはずです。

response codes screen

グラフツールにより、レスポンスコードの履歴を表示することができます。異なる期間および細かさのレベルでレスポンスコードの統計を確認することもできます。期間選択バーをクリックして、ニーズに合った期間と細かさを定義するだけです。