1. Oracle Mobile HubアプリケーションからのRESTデータへのアクセス
  2. ファサードRESTサービスのカスタムAPIの実装

ファサードRESTサービスのカスタムAPIの実装

モバイル・アプリケーションを開発する場合は、通常、最初にユーザー・インタフェース・レイヤーから開始し、次にREST Webサービスを使用してアプリケーションを別のアプリケーションに接続します。この方法は、小規模または単純なアプリケーションに適しています。アプリケーションが大きく、複数のバックエンド・サービスに接続する場合、パフォーマンスとセキュリティの問題を誤って発生させる可能性があります。

ベスト・プラクティスは、外部バックエンド・サービスとユーザー・インタフェースの間のファサードAPIレイヤーの構築を開始して、可能なかぎりバックエンド・サービスへのコール数を減らすことです。たとえば、モバイル・アプリケーションは、他のRESTサービスへのコールを処理するファサードAPIレイヤーへの単一のコールを実行し、すべての受信データをモバイル・アプリケーションへの単一のレスポンスに統合できます。

完全なカスタムAPIの作成

Oracle Mobile Hubを使用して完全なカスタムAPIを作成するには。

サイド・メニューを開くアイコンをクリックし、サイド・メニューから「開発」、「API」の順に選択します。APIがすでに作成されている場合(ドラフト状態でも公開済状態でも)、APIのリストが表示されます。カスタムAPIがない場合は、ページに「New API」ボタンが表示されています。すでに作成したAPIをクリックするか、「New API」をクリックして作業を開始します。

エンドポイントの定義

リソースを作成してAPIのエンドポイントを定義します。リソースはAPIの最重要ポイントです。リソースにはタイプがあり、なんらかのデータが関連付けられており、他のリソースとの関係があり、リソースに対して実行される1つ以上のメソッドが含まれます。イメージ、テキスト・ファイル、他のリソースのコレクション、論理トランザクション、プロシージャなど、ほぼ何でもリソースになります。

  1. Click the Endpoints navigation link to begin.
  2. 「New Resource」をクリックして、いくつかの基本情報を追加します。

    「New Resource」をクリックするたびに、トップレベル(ルート)リソースが作成されます。子(ネストされた)リソースを追加する場合は、トップレベル・リソースの横にある「Add」(+)をクリックします。「X」をクリックして、リソースを削除します。

    ノート:

    「Methods」リンクの下のアイコンがわかりますか。リソースに対してメソッドを定義するたびに、そのメソッドのアイコンが「Methods」リンクの下に表示されます。これらをショートカットとして使用して、リソースにすでに定義されているメソッドを確認します。アイコンをクリックして、「Methods」ページの定義に直接移動します。
  3. リソース・パスを指定します。これは、(ベースURIに相対する)URIです。たとえば、ベースURIが/mobile/custom/audits/の場合、リソースfindings (/mobile/custom/audits/findings)を追加できます。
  4. 表示名を指定します。これは、APIドキュメントの識別を容易にするリソースの名前です。
    リソースは、「API Test」ページの左側に表示名別にリストされます。
  5. リソースの簡単な説明を入力します。

    説明を入力すると、説明フィールドの下にURIが表示されます。

  6. (オプション)RAMLリソース・タイプを指定します。これはリソース・タイプ(resourcesType:)です。リソース・タイプを指定する必要はありません。リソース・タイプを使用したいが、定義されていない場合は、「Types」リンクをクリックして定義します。

リソースのメソッドを作成すると、そのメソッドの記号が「Methods」リンクの下に表示されます。リソース定義を確認する必要がある場合は、どのメソッドがリソースに定義されているかをすぐに確認できます。アイコンをクリックして、そのメソッド定義に直接移動します。

「コンパクト・モード」(「新規リソース」の右にある)に切り替えることで、クラッターをクリアしてリソースをより迅速に見つけることができます。コンパクト表示にすると、リソースの説明、リソース・タイプおよびパスが非表示になります。

メソッドをリソースに追加

メソッドは、リソースで実行できるアクションです。「Method」ページには、一度に1つのメソッドのみ表示されます。2つ以上のメソッドを定義したら、ページの上部でメソッドのアイコンをクリックして詳細を表示できます。

  1. 「Methods」をクリックして、リソースにいくつかのメソッドを追加します。

    メソッドを定義しているリソースにパス・パラメータがある場合は、「Add Method」の上に表示されます。

    1. (オプション)メソッドごとにパス・パラメータを渡す場合は、「Required」をクリックします。
      パラメータ名が表示されます。
    2. パラメータの表示名とサンプル・コードを入力します。
    3. ドロップダウン・リストから、パラメータに有効な値タイプを選択します。
  2. 「Add Method」をクリックして、必要なメソッドを選択します。

    メソッドはリソースごとに1回しか使用しないため、メソッドを選択すると、そのメソッドはメソッド・リストに表示されなくなります(たとえば、1つのリソースに2つのDELETEメソッドを定義することはできません)。定義したそれぞれのメソッドのアイコンがページの上部に表示されます。メソッドのアイコンをクリックすると、その定義に直接移動できます。

  3. (オプション)「説明」フィールドに、メソッドの簡単な説明を入力します。
  4. (オプション)メソッドの表示名を入力します。
  5. (オプション)メソッドに適用する特質を指定します。

    リソースの特質が定義されていない場合は、「Endpoints」をクリックしてリソース・ページに戻り、「Traits」リンクをクリックして定義します。特質によって、類似する操作のコレクションを定義できます。

リソースのメソッドを定義したら、それらのメソッドのリクエストとレスポンスを定義できます。

メソッドのリクエストの定義

メソッドを選択したので、接続するサービスに対するリクエストを定義します。たとえば、POSTメソッドを選択した場合、次に何を作成するかを定義できます。それには、パラメータおよびサービスに送信するデータの説明を含むリクエスト本文を追加します。

  1. 「Request」をクリックしてリクエストを定義します。
  2. 「パラメータの追加」をクリックしてパラメータ・タイプ(「問合せ」または「ヘッダー」)を選択します。メソッドにとってそのパラメータが必須の場合は、「Required」を選択します。
    1. パラメータの名前と表示名を指定します。
    2. 有効値タイプ(「文字列」、「数値」、「整数」、「日付」または「ブール」)を選択します。
    3. (オプション)エンドポイントの有効性をテストする際に使用する、パラメータの説明と例を入力します。たとえば、auditsリソースに、数値を取得する問合せパラメータauditorIDおよび文字列を取得する別のパラメータauditNameを追加できます。
      /audits: 
  get: 
    description: | 
      Gets list of audits, organizations etc.     
    queryParameters: 
      auditorID:  
        id: Auditor ID
        description: | 
          display auditor identifier 
        type: integer 
        example: |
          1234
        required: false      
      auditName:
        displayName: auditName
        description: |
          Audit name
        example: "Payroll Process Audit"

      この例では、問合せパラメータauditorIDおよびauditNameを使用してGETメソッドが定義されています。

    4. (オプション)ネストされたプロパティをパラメータに追加するには、「More Properties」をクリックします。現在のパラメータを複数追加するには、「Repeat」をクリックします。
    5. メソッドの別の上位パラメータを追加するには、「パラメータの追加」をクリックします。
  3. 選択したメソッドによっては、「Add Media Type」をクリックしてメソッド本文を定義します。本文には、サーバーに送信するデータが含まれます。たとえば、POSTメソッドを定義する際は、新規顧客リストやサービス・リクエストなど、作成するアイテムを定義する必要があります。GETメソッドを定義する場合はメソッド本文を送信する必要があるため、メディア・タイプを指定する必要はありません。
    1. メソッド本文のメディア・タイプを選択します。これは、テキスト、イメージ、Webフォームなど、送信するメッセージの形式です。
      タイプによっては(たとえば、イメージ・タイプにはスキーマは入力しません)、スキーマまたは例あるいはその両方を追加できます。

      スキーマを定義する場合は、リソースの目的に必要なデータのみを追加します。転送速度が遅くなりエラーが発生する可能性が増加するため、不必要なデータは追加しないでください。

    2. (オプション)「Schema」をクリックして、エディタ・ペインにスキーマ(JSON形式)を入力します。スキーマは、本文のテンプレートのようなものです。メッセージの内容を定義する際に使用します。
    3. (オプション)「Example」をクリックして、例(JSON形式)をエディタ・ペインに入力します。これは、メソッドのモック・レスポンスとしてモック実装で使用されます。モック・データを使用すると、メソッドの動作を検証しやすくなります。次の例は、auditsリソースのPOSTメソッドで定義された、メッセージ本文に送信されるデータのモック値を示しています。
      body: 
  application/json: 
    example: | 
      { 
        "Title": "Leaking Water Heater",
        "Username": "joh1017",  
        "imageLink": "storage/collections/2e029813-d1a9-4957-a69a-fbd0d7431d77/objects/6cdaa3a8-097e-49f7-9bd2-88966c45668f?user=lynn1014", 
        "Notes": "my water heater is broken"
      }
  4. 「メディア・タイプの追加」をクリックして、メディア・タイプを追加します。メソッドが必要ない場合は、バナーでXをクリックして削除します。

メソッドのレスポンスの定義

リクエストによって、レスポンスが必要な場合があります。レスポンスは、サービスから結果を返すプロセスを示します。リクエストしたデータが返されたことを確認するレスポンス、またはリクエストが受信されたかどうかを確認するレスポンスを定義できます。レスポンスの定義は、リクエストの定義と同じです。主な相違点は、接続結果を知らせるステータス・コードを選択する必要がある点です。

  1. Click Response to define one or more responses.
  2. 「Add Response」をクリックして、返されるステータス・コードを選択します。

    デフォルトでステータス・コード200が提供されていますが、これが必要なコードでない場合は、ドロップダウン・リストから選択します。

    • 2xx: 成功した接続を示します。

    • 3xx: リダイレクトが行われたことを示します。

    • 4xx: ユーザー・エラーが発生したことを示します。

    • 5xx: サーバー・エラーが発生したことを示します。

    構成しているAPIの潜在的なエラーの理由をAPIのユーザーが把握できるように、HTTPステータス・コードを使用して、エラー状況に最適なコードを返します。

  3. コードが示す内容の説明を入力します。
  4. 「Add Header」をクリックし、レスポンス「Header」または「Query」を選択し、ヘッダーまたは問合せの名前およびヘッダーの表示名、およびヘッダーの有効な値タイプを指定します。
  5. 「Add Media Type」をクリックして、レスポンスの形式を選択します。選択したメディア・タイプによっては、リクエスト本文のときと同様に、パラメータ、スキーマまたは例を追加できます。
    1. テキストベースのメディア・タイプ(application/JSONまたはtext/xmlなど)の場合、「Schema」をクリックして本文のスキーマ(JSON形式)を入力します。
      リクエストボディと同様に、関連するデータだけをレスポンスボディに追加します。操作に実際に必要とするデータよりデータは含まないでください。
    2. 「Example」をクリックして、レスポンス本文にモック・データ(JSON形式)を追加します。モック・データを使用して、実データをテストする前にメソッドの動作を検証します。
    3. フォームベースのメディア・タイプ(multipart/form-dataなど)の場合、「パラメータの追加」をクリックし、パラメータが必須の場合は「必須」を選択します。その後、名前を指定して値タイプを選択します。オプションで、パラメータ名を指定できます。
    4. イメージベースのメディア・タイプ(image/pngなど)の場合、指定するスキーマや属性がないため、何もする必要はありません。
次の例は、新規リソースが正常に作成されたことを示すステータス・コード201で、auditsリソースのPOSTメソッドのレスポンスが作成されたことを示しています。また、この例では、返信レスポンス形式がapplication/jsonで、Locationヘッダーが追加され、メッセージ本文にモック・データが含まれることも示されています。
responses: 
  201: 
    description: | 
      The request has been fulfilled and resulted in a new resource 
      being created. The newly created resource can be referenced  
      by the URI(s)returned in the entity of the response, with the 
      most specific URI for the resource given by a Location header
      field.  

    headers:
      Location:
        displayName: Location
        description: |
          Identifies the location of the newly created resource.

        type: string
        example: |
          /20934

        required: true

    body: 
      application/json: 
        example: | 
          {
            "id": 20934,
            "title": "Lynn's Leaking Water Heater",
            "contact": {
               "name": "Lynn Adams",                 
               "street": "45 O'Connor Street",
               "city": "Ottawa", 
               "postalcode": "a1a1a1",
               "username": "johnbeta"
              },
           "status": "New",
           "driveTime": 30,
           "priority": "high",
           "notes": "My notes",
           "createdon": "2014-01-20 23:15:03 EDT",
           "imageLink": "storage/collections/2e029813-d1a9-4957-a69a-fbd0d74331d77/objects/6cdaa3a8-097e-49f7--9bd2-88966c45668f?user=lynn1014"
          }

レスポンスを定義するときに、エンドポイントをテストするか、ナビゲーション・バーの「エンドポイント」をクリックして「リソース」のメイン・ページに戻るかを決定できます。そこからAPI Designerの別のページに進んで、ルート、リソース・タイプまたは特質を作成したり、APIドキュメントを追加できます。

メソッドが必要ない場合は、バナーでXをクリックして削除します。

RESTコネクタAPIの作成

RESTコネクタAPIウィザードを使用して、コネクタAPIを作成、構成およびテストします。

基本的な機能を持つコネクタAPIを取得するには、コネクタAPIの名前および外部サービスのURLを指定するだけです。

次のことを実行できます:

  • アクセスするデータの特定のリクエストまたはレスポンスを形成するルールを定義します。

  • アクセスしているサービスのクライアント側のセキュリティ・ポリシーを構成します。

  • 接続をテストし、接続に対して行われたコールの結果をテストします。

アプリケーションでコネクタAPIをコールし、APIおよび実装を自動的に生成できるようにするには、カスタムAPIおよび実装を作成する必要があります。手動で実行する場合は、適切なリソースを使用してカスタムAPIを作成してから、カスタム・コードを実装する必要があります。

基本コネクタの設定

REST Connector APIウィザードの最初の2ページを完了することで、機能するコネクタを作成できます。

  1. サイド・メニューを開くアイコンをクリックし、サイド・メニューから「開発」、「API」の順に選択します。

  2. 「REST」(作成する最初のコネクタAPIの場合)または「New Connector」をクリックして、ドロップダウン・リストから「REST」を選択します。

  3. 次を指定して、新しいRESTコネクタAPIを特定します。

    1. API表示名:コネクタAPIのリストに表示される名前。

    2. API名:コネクタAPIの名前。

      デフォルトでは、この名前がコネクタAPIのリソース名として相対ベースURIに追加されます。ベースURIは API Nameフィールドの下に表示されます。

      このコネクタAPIの新しいバージョン以外、他のコネクタAPIで同じリソース名を持つことはできません。

    3. 短い説明:このAPIを選択したときに、この説明がコネクタ・ページに表示されます。

  4. 「Create」をクリックします。

  5. RESTコネクタAPIダイアログ・ボックスの「一般」ページで、タイムアウト値を設定します:

    • HTTP Read Timeout:データ読取り待機に費やすことができる最大時間(ミリ秒)。値を入力しない場合、デフォルト値の20秒が使用されます。

    • HTTP Connection Timeout:リモートURLへの接続に要した時間(ミリ秒)。0mmsは、無制限のタイムアウトが許容されることを意味します。

      HTTPタイムアウト値は、Network_HttpRequestTimeoutポリシー(デフォルト値は40,000ミリ秒)未満である必要があります。

      ノート:

      サービス開発者ロールに加えてモバイル・クラウド管理者ロールを持つ場合、「Administrator」ビューでpolicies.propertiesファイルを開き、現在の環境のネットワーク・ポリシーの値を確認できます。そうでない場合は、モバイル・クラウド管理者に値を尋ねてください。

  6. 「ディスクリプタ」をクリックして、サービスの接続情報を入力します。

    SwaggerディスクリプタURLを指定すると、使用可能なリソースが識別されて表示され、必要なリソースを選択できます。

    ノート:

    サポートされているのは、標準のインターネット・アクセス・ポート80および443のみです。カスタム・ポートを使用してサービスに接続することはできません。

  7. 「保存」をクリックします。

  8. (オプション)「テスト」をクリックして認証資格証明を選択し、テスト・コールをサービスに行います。

そこから、次の方法でコネクタをさらに構成できます:

  • (ディスクリプタ・ページでディスクリプタを指定した場合)「リソース」ページに移動し、公開されたリソースのメソッドを選択します。

  • ルールの定義

  • セキュリティ・ポリシーの設定

コネクタAPIが有効であることを確認するために、公開前に徹底的にテストする必要があります(Connector API Testページからだけでなく)。すなわち、このコネクタAPIを使用するカスタムAPI(およびその実装)もテストする必要があります。特に、コネクタAPIを公開する準備ができたら、それを呼び出すカスタムAPIを公開する準備もできている必要があります。

ルールの設定

モバイル・アプリケーションとサービスとの間の相互作用を定義するルールを設定します。ルールを使用すると、サービスのリソースへのすべての呼び出し、特定のプロキシパスへの呼び出し、特定タイプの操作(動詞)への呼び出しに対するデフォルトのパラメータ値を追加できます。これは、URL文字列の構文の一貫性を確保し、カスタム・コード開発者がこれらの値を挿入しなくても済むよう支援し、分析を通じて様々な呼出しを追跡するのに役立ちます。

1つ以上のルールを作成できます。各ルールには、QueryおよびHeaderタイプの1つ以上のパラメータを設定できます。

どのルールも適用されない場合、すべての呼出しはプロキシを介して既存のサービスに渡されます。

  1. コネクタがまだ開いていない場合は、サイド・メニュー・アイコンをクリックして、サイド・メニューから「開発」、「API」の順に選択します。
  2. 編集するコネクタAPIを選択し、「開く」をクリックします。
  3. 「ロール」を選択します。
  4. 「新規ルール」をクリックします。
  5. 「パラメータの追加」をクリックして「問合せ」または「ヘッダー」パラメータ・タイプを選択し、問合せまたはヘッダー名、その値を入力します。

    ノート:

    デフォルトで特定のヘッダーを設定するルールを定義することもできますが、カスタム・コードから直接またはWebブラウザやモバイル・アプリケーションなどから間接的にコネクタを呼び出すクライアントが、すでに同じヘッダーを設定していた場合、このルールは適用されません。

    特に、リクエスト本文の形式の設定は通常、Content-Typeヘッダーとともにカスタム・コードで行われます(RESTコネクタ・ルールとしてではなく)。同様に、レスポンス本文の形式の設定は、RESTコネクタ・ルールとしてではなく、Acceptヘッダーとともにカスタム・コードでも行われます。

    1つのルールには、必要なだけいくつでもパラメータを追加できますが、ルールに多数の操作をオーバーロードしないようにしてください。ルールの構成が簡単な方が、トラブルシューティングが容易になります。

  6. 「Resources」を開き、リモートURLを編集して、ルールを適用するリソースを指定します。ベースURLの値は基本情報設定ステップで入力したものであり、編集できません。
  7. ルールをリモートURLで指定したリソース・レベルにのみ適用する場合は、「適用しない」を選択します。
  8. (オプション)定義したルールに適用しないHTTPメソッドを選択します。デフォルトでは、すべてのメソッドが選択されます。
  9. (オプション)「New Rule」をクリックして別のルールを作成します。

    ノート:

    別の規則と競合する規則を定義した場合、適用された最初の規則が優先され、競合する規則は無視されます。

    完了したら、「Save」、「Next」(>)の順にクリックして、コネクタAPIの構成の次のステップに移動します。

定義したルールの説明が、「デフォルト・パラメータ」セクションのすぐ上のルール・バナーに表示されます。たとえば、次の値が指定されたとします。

  • リモートURL = https://maps.googleapis.com/maps/api/directions/json?origin=los+angeles&destination=seattle

  • ローカルURI = myMapAPI

  • 次のパラメータを持つルール: Query:key:A3FAEAJ903022

  • GETおよびPUT HTTPメソッド

ルールの説明は、次のようになります。

myMapAPI/directionsで使用可能なGETからhttps://maps.googleapis.com/maps/api/directions/json?origin=los+angeles&destination=seattleには、Query:key=A3FAEAJ903022を含めます。

いずれのルールも作成されない場合は、説明は次のようになります。

myMapAPIで使用可能なhttps://maps.googleapis.com/maps/api/directionsへのすべての方法の場合、デフォルト・パラメータは適用されません。

既存のサービスにマップするベースURIが設定されました。たとえば:

mobile/connector/myMapAPI/directions/json?origin=los+angeles&destination=seattleはhttps://maps.googleapis.com/maps/api/directions/json?origin=los+angeles&destination=seattleにマップされます。

セキュリティ・ポリシーおよびオーバーライド・プロパティの構成

コネクタAPIを最終決定する前に、セキュリティの処理方法を考慮する必要があります。セキュリティ・ポリシーまたは認可ヘッダーのいずれかを使用できます。接続先のサービスの認証スキームを記述するセキュリティ・ポリシーを選択することをお薦めします。

各セキュリティ・ポリシーにはオーバーライドと呼ばれるプロパティがあり、これは構成可能です。ポリシー構成プロパティをオーバーライドする理由の1つは、保守するポリシーの数を制限するためです: 多彩な構成でポリシーを作成するのではなく、同じ汎用ポリシーを使用し、要件に合せて特定の値をオーバーライドできます。

セキュリティ・ポリシーを選択して、ポリシーのオーバーライドを設定するには:

  1. コネクタがまだ開いていない場合は、サイド・メニュー・アイコンをクリックして、サイド・メニューから「開発」、「API」の順に選択します。
  2. 編集するコネクタAPIを選択し、「開く」をクリックします。
  3. 「セキュリティ」を選択します。
  4. 使用可能なポリシーのリストからセキュリティ・ポリシーを選択し、右矢印をクリックして「Selected Policies」リストに移動します。
    コネクタAPIに1つのポリシーのみを選択します。リストの下に、選択したポリシーの説明が表示されます。
  5. デフォルト値を使用しない場合は、選択したポリシーに対してオーバーライド(該当する場合)を指定します。
    プロパティをオーバーライドするには、デフォルト以外の値を入力または選択します。
  6. 「Save」をクリックして作業を保存するか「Save and Close」をクリックして作業を保存してREST Connector APIウィザードを終了します。
  7. Click Next (>) to go to the next step.