PR

3scaleの基本的な使い方

2019年7月4日(木)
田畑 義之

はじめに

今回は、3scaleの基本的な使い方を解説します。図1のように、実際にAPIバックエンドに存在する(APIプロバイダが提供する)Hello APIを、3scaleを使って公開するというユースケース(Step 1~Step 3)に沿って解説します。

図1:今回の構成図

Hello APIは、”user_key”クエリに指定した値と、リクエストヘッダの値をJSON形式で返却する簡単なAPIです。

$ curl "http://api_backend.oss.example.co.jp:18080/myapp/api/hello?user_key=api_key"
{
  "your_user_key": "api_key",
  "your_request_headers": {
    "User-Agent": [
      "curl/7.29.0"
    ],
    "Accept": [
      "*/*"
    ],
    "Host": [
      "api_backend.oss.example.co.jp:18080"
    ]
  }
}

ここでは、既にこのような簡単なAPIが存在することを前提に解説を進めていきます。

Step 1. APIを公開してみよう

それでは、早速APIバックエンドに存在するHello APIを3scaleで公開してみましょう。以下の3つを設定します。

  • プロキシ設定
    • APIゲートウェイのURL(クライアントアプリケーション(APIコンシューマ)がコールするURL)と、APIバックエンドのURLとをマッピングする
  • 認証用設定
    • Hello APIを利用するクライアントアプリケーションを定義する
  • 分析用設定
    • Hello APIのコール数をカウントできるようにする

まず、管理ポータルのダッシュボードから[NEW API]を選択します(図2)。

図2:管理ポータルのダッシュボード

3scaleでは、手動でAPIを追加する方法と、サービスディスカバリ機能(OpenShift上にデプロイされたAPIサービスをシームレスに3scaleに取り込む機能)を用いてAPIを追加する方法があります。ここでは、手動でAPIを追加してみましょう(図3)。

図3:API追加画面

これでサービス(3scaleでは“API”と“サービス”は同義)の定義ができあがりました(図4)。以降、具体的な設定をしていきます。

図4:Hello APIの概要画面

プロキシ設定

まず、プロキシを設定します。Hello APIの概要画面から[Configuration]→[add the base URL of your API and save the configuration]を選択すると、Hello APIのインテグレーション画面が表示されます(図5)。プロキシの設定や認証用の設定など、APIの構成に関わる設定は、基本的にこのインテグレーション画面を用いて設定します。

[Private Base URL]にAPIバックエンドのURL、[Staging Public Base URL]および[Production Public Base URL]にAPIゲートウェイのURLを定義することで、APIゲートウェイのURLとAPIバックエンドのURLとをマッピングします。

APIゲートウェイのURLが2つありますが、これらは名前の通り、それぞれステージング環境用と本番環境用のAPIゲートウェイです。

図5:Hello APIのインテグレーション画面

前述したように、3scaleにはOpenShiftのサービスとしてステージング環境用と本番環境用のAPIゲートウェイが存在します。新しくAPIを追加した場合は、そのゲートウェイに設定したURLとOpenShiftのサービスとをマッピングする必要があります。そのマッピングは、OpenShiftのルートを2つ(ステージング環境用と本番環境用)作成することで実現できます(図6)。

図6:OpenShiftのルート一覧画面

認証用設定

次に認証用の設定をします。Hello APIを利用するクライアントアプリケーションを作成するには、そのクライアントアプリケーションの開発者のアカウントを作成する必要があります。

管理ポータルのダッシュボードから[Audience]→[Create]を選択し、開発者アカウントを作成します(図7)。

図7:開発者アカウント作成画面

開発者アカウントを作成すると、デフォルトでクライアントアプリケーションが1つ作成されます(図8)。このデフォルトクライアントアプリケーションは、デフォルトサービスである”API”を利用するように設定されています。ここではサービスとしてHello APIを用いるため、このデフォルトクライアントアプリケーションは利用できません。

図8:クライアントアプリケーションの概要画面

新規クライアントアプリケーションを作成する前に、まずクライアントアプリケーションとサービスとをマッピングするためのアプリケーションプランを作成します。アプリケーションプランとは、流量制御やマネタイズ等のルールをクライアントアプリケーション単位で設定するための枠組みです。

Hello APIの概要画面から[Create Application Plan]を選択すると、アプリケーションプラン作成画面が表示されます(図9)。アプリケーションプランを作成後、作成したアプリケーションプランを[Publish]します。

図9:アプリケーションプラン作成画面

次に、新規クライアントアプリケーションを作成します(図10)。ここでは、”test application”というアプリケーションを作成します。[Application Plan]には、先ほど作成したHello APIの”Basic”アプリケーションプランを設定します。

図10:アプリケーション作成画面

分析用設定

最後に分析用の設定を行います。まずはメソッドを設定しましょう。3scaleでは、APIのパスをメソッドと呼びます(図11)。

図11:3scaleにおけるメソッドの定義

次にHello APIの概要画面から[Methods]を選択し、新規メソッドとしてHello methodを作成しましょう(図12)。

図12:メソッド作成画面

続けて、作成したメソッドとAPIのパスとをマッピングします。Hello APIのインテグレーション画面で[Add Mapping Rule]を選択し、マッピングルールを追加します(図13)。

図13:Hello APIのインテグレーション画面(マッピングルールの設定)

以上で設定は完了です。最後にHello APIのインテグレーション画面で[Update & test in Staging Environment]ボタンを押下し、インテグレーションテスト(ステージング環境用のAPIゲートウェイからAPIバックエンドまでの疎通テスト)に成功することを確認しましょう(図14)。

図14:Hello APIのインテグレーション画面(インテグレーションテスト成功)

ステージング環境用のAPIゲートウェイを用いて、Hello APIをコールしてみます。”user_key”クエリには、作成したクライアントアプリケーションのAPIキーを付与します。APIキーは、クライアントアプリケーションの概要画面で確認できます。

$ curl "https://hello-3scale-apicast-staging.192.168.99.113.nip.io:443/myapp/api/hello?user_key=cf6e6569d04dc087541b2f49b486a2f1"
{
  "your_user_key": "cf6e6569d04dc087541b2f49b486a2f1",
  "your_request_headers": {
    "Accept": [
      "*/*"
    ],
    "User-Agent": [
      "curl/7.29.0"
    ],
    "X-Forwarded-Host": [
      "hello-3scale-apicast-staging.192.168.99.113.nip.io"
    ],
    "X-Forwarded-Proto": [
      "https"
    ],
    "Forwarded": [
      "for=192.168.99.113;host=hello-3scale-apicast-staging.192.168.99.113.nip.io;proto=https;proto-version="
    ],
    "X-Forwarded-For": [
      "192.168.99.113"
    ],
    "Host": [
      "api_backend.oss.example.co.jp:18080"
    ],
    "X-Real-IP": [
      "172.17.0.1"
    ],
    "X-3scale-proxy-secret-token": [
      "Shared_secret_sent_from_proxy_to_API_backend_9b581ebf1068c969"
    ],
    "X-Forwarded-Port": [
      "443"
    ]
  }
}

ステージング環境用のAPIゲートウェイを用いて、Hello APIをコールすることに成功しました。

続いて、本番環境用のAPIゲートウェイを用いてHello APIをコールしてみます。本番環境用のAPIゲートウェイにHello APIをデプロイするためには、コンフィギュレーション画面で[Promote]ボタンを押下します(図15)。

図15:Hello APIのコンフィギュレーション画面

本番環境用のAPIゲートウェイを用いて、Hello APIをコールします。

$ curl "https://hello-3scale-apicast-production.192.168.99.113.nip.io:443/myapp/api/hello?user_key=cf6e6569d04dc087541b2f49b486a2f1"
{
  "your_user_key": "cf6e6569d04dc087541b2f49b486a2f1",
  "your_request_headers": {
    "Accept": [
      "*/*"
    ],
    "User-Agent": [
      "curl/7.29.0"
    ],
    "X-Forwarded-Host": [
      "hello-3scale-apicast-production.192.168.99.113.nip.io"
    ],
    "X-Forwarded-Proto": [
      "https"
    ],
    "Forwarded": [
      "for=192.168.99.113;host=hello-3scale-apicast-production.192.168.99.113.nip.io;proto=https;proto-version="
    ],
    "X-Forwarded-For": [
      "192.168.99.113"
    ],
    "Host": [
      "api_backend.oss.example.co.jp:18080"
    ],
    "X-Real-IP": [
      "172.17.0.1"
    ],
    "X-3scale-proxy-secret-token": [
      "Shared_secret_sent_from_proxy_to_API_backend_9b581ebf1068c969"
    ],
    "X-Forwarded-Port": [
      "443"
    ]
  }
}

本番環境用のAPIゲートウェイを用いて、Hello APIをコールすることに成功しました。Hello APIの概要画面から[Analytics]を選択するとHello APIの分析画面が表示され、Hello APIの使用量等を確認できます(図16)。

図16:Hello APIの分析画面

株式会社 日立製作所
OSSソリューションセンタにて、API管理や認証周りのOSSの開発/サポート/普及活動に従事。3scaleのapicastリポジトリのコントリビュータであり、流量制御ポリシーやスコープチェックポリシーを中心に多数のコードをコミットしている。

連載バックナンバー

Think IT会員サービス無料登録受付中

Think ITでは、より付加価値の高いコンテンツを会員サービスとして提供しています。会員登録を済ませてThink ITのWebサイトにログインすることでさまざまな限定特典を入手できるようになります。

Think IT会員サービスの概要とメリットをチェック

他にもこの記事が読まれています