Apigee データソースを使用する

アプリの作成者は、Apigee データソース タイプを使用した Apigee が管理する API に公開されるデータを使用した AppSheet でアプリを構築できます。

注: Apigee X と Apigee Edge の両方をサポートしています。

現時点では、AppSheet アプリを Apigee API に接続するには、主に次の 2 つのオプションがあります。

  • 手動
  • OpenAPI 仕様

この記事では、AppSheet アプリから Apigee マネージド API への接続を設定するために必要な API の詳細な手順と前提条件について説明します。

 クイック スタート動画

AppSheet で Apigee データソースを使用する方法について詳しくは動画をご覧ください。

注: この動画のコンセプトは現在でも有効ですが、AppSheet の UI はこの動画撮影時から変更されています。

Apigee と AppSheet での API を活用したアプリの開発

AppSheet の Apigee データソースを設定する

AppSheet の Apigee データソースを設定するには、以下の手順を実行します。

  1. Apigee で認証を設定する
  2. AppSheet で Apigee データソースを作成する

Apigee で認証を設定する

Apigee データソースで認証を行うには、以下の表で示すいずれかのオプションを選択します。

認証

説明

OAuth

Apigee で OAuth 検証を設定し、API にアクセスするために承認されている方法を提供します。詳しくは以下をご覧ください。

注: 現在、AppSheet の Apigee データソースは、クライアント認証情報付与タイプのみをサポートしています。詳しくは以下をご覧ください。

API キー

Apigee で API キー検証を設定し、API にアクセスするために承認されている方法を提供します。詳しくは以下をご覧ください。

注: API キーは、AppSheet からの各リクエストの x-apikey ヘッダーに返されます。

認証なし

API キーを選択し、空でない任意の値（ABC など）を API キーフィールドに入力します

AppSheet で Apigee データソースを作成する

始める前に: API の認証を構成した後、Apigee データソースを作成する前に、その API が AppSheet で利用できることを確認するために、Apigee API プロキシの前提条件を確認してください。

AppSheet で Apigee データソースを作成し、Apigee への接続を作成します。

  1. appsheet.com にログインします。
  2. 上部のナビゲーション バーにある [My account] をクリックします。
  3. [Sources] タブを選択します。
  4. [+ New Data Source] をクリックします。
  5. 新しいデータソースに名前を付け、[Apigee] を選択します。
    Apigee API 接続情報ダイアログを追加

次のセクションで説明するように、OpenAPI Spec または Manual Apigee 接続を構成します。

OpenAPI Spec Apigee 接続を構成する

API プロキシに OpenAPI 仕様がある場合、OpenAPI Spec Apigee 接続を構成できます。

OpenAPI Spec Apigee 接続を構成するには:

  1. [Add Apigee API connection information] ダイアログで、[OpenAPI Spec] をクリックします。
  2. OAuth 認証を使用するには、[OAuth] を Authentication Type として選択し、次の設定を構成します。

    設定

    説明

    Apigee Client ID

    Apigee が生成したクライアント ID。

    Apigee Client Secret

    Apigee が生成したクライアント シークレット。

    OpenAPI Spec URL

    OpenAPI 3.0 Spec を指す URL。AppSheet は JSON または YAML 形式を受け入れます。URL は REST エンドポイントとして一般公開のアクセス可能な状態になっている必要があります。

    Appsheet は URL に GET 呼び出しを送信して OpenAPI Spec を取得します。
  3. API キー認証を使用するには、[ApiKey] を Authentication Type として選択し、次の設定を構成します。

    設定

    説明

    Apigee API Key

    Apigee が生成した API キー。

    OpenAPI Spec URL

    URL から OpenAPI Spec へ。
    Custom Headers

    Apigee へのすべてのリクエストとともに送信されるカスタム ヘッダー。[Add] をクリックして、ヘッダーの名前と値を指定します。さらにカスタム ヘッダーを追加するには、これを繰り返します。

    注: カスタム ヘッダーは 20 個まで追加できます。カスタム ヘッダーの名前と値は、それぞれ 1000 文字を超えることはできません。
  4. 接続を検証するには、[Validate] をクリックします。
    AppSheet は OpenAPI Spec URL に GET 呼び出しを実行して、OpenAPI Spec を解析します。その後、AppSheet は、OpenAPI Spec が推論した各テーブル リソースに対して GET 呼び出しを行います。
  5. [Authorize Access] をクリックして、データソースを追加します。

Manual Apigee 接続を構成する

API の OpenAPI Specification を利用できない場合は、Manual Apigee 接続を構成します。

Manual Apigee 接続を構成するには:

  1. [Add Apigee API connection information] ダイアログで、[Manual] をクリックします。
  2. OAuth 認証を使用するには、[OAuth] を Authentication Type として選択し、次の設定を構成します。
     

    設定

    説明

    Apigee Authorization Token URL

    アクセス トークンの生成を行う API プロキシの URL。

    Apigee Client ID

    Apigee が生成したクライアント ID。

    Apigee Client Secret

    Apigee が生成したクライアント シークレット。

    Authorization Scopes（省略可）

    ポリシーに定義されている場合、承認のスコープ。

    Apigee API Base Path

    Apigee プロキシのベースパス。

    API Resource Paths

    API プロキシ エンドポイントのカンマ区切りのリスト。パスは AppSheet のテーブル名に対応しています。
  3. API キー認証を使用するには、[ApiKey] を Authentication Type として選択し、次の設定を構成します。

    設定

    説明

    Apigee API Key

    Apigee が生成した API キー。

    Apigee API Base Path

    Apigee プロキシのベースパス。

    API Resource Paths

    API プロキシ エンドポイントのカンマ区切りのリスト。パスは AppSheet のテーブル名に対応しています。
    Custom Headers

    Apigee へのすべてのリクエストとともに送信されるカスタム ヘッダー。[Add] をクリックして、ヘッダーの名前と値を指定します。さらにカスタム ヘッダーを追加するには、これを繰り返します。

    注: カスタム ヘッダーは 20 個まで追加できます。カスタム ヘッダーの名前と値は、それぞれ 1000 文字を超えることはできません。
  4. 接続をテストするには、[Test Connection] をクリックします。
    • OAuth 認証の場合: AppSheet は、Apigee Authorization Token URL に Apigee Client Id と Apigee Client Secret を指定して、POST 呼び出しを行い、アクセス トークンを取得します。その後、アクセス トークン AppSheet はすべての {Apigee API Base Path}/{API Resource Path} パスに対して GET 呼び出しを行ってアクセスを検証します。
    • API キー認証の場合: AppSheet は、すべての {Apigee API Base Path}/{API Resource Path} パスに対して GET 呼び出しを行ってアクセスを検証します。
  5. [Authorize Access] をクリックして、データソースを追加します。

API プロキシの前提条件

Apigee データソースの設定の種類（Manual または OpenAPI Spec）によっては、AppSheet との互換性を確保するために、基盤となる Apigee API プロキシ API にいくつかの追加要件があります。

OpenAPI Spec Apigee 接続

OpenAPI Spec の Apigee 接続を構成する場合、Apigee API プロキシが API プロキシに必要なオペレーションで説明されている必須の API オペレーションをサポートしていることを確認してください。

さらに、OpenAPI Spec は次のガイドラインを満たす必要があります。

  • サーバーは、ベースパスとしてエントリを 1 つのみ配置できます。
  • OAuth 認証タイプの場合:
    • components:securitySchemes セクションを含める必要があります。
    • components:securitySchemes タイプが oauth2 の場合、フローは clientCredentials に指定する必要があります。
    • tokenUrl を指定する必要があります。
    • scopes は省略可です。


    OpenAPI Spec の components スニペットの例:

    components:
    securitySchemes:
      oAuth2ClientCredentials:
        type: oauth2
        Description:  Experimental Apigee APIs
        Flows:
          clientCredentials:
            tokenUrl: https://appsheet-test.apigee.net/oauth2/token/
            scopes:  #Can be empty {}
              read: Grant read-only access

  • GET /tableName/{id} のレスポンス本文のスキーマを指定する場合、AppSheet はそこから列タイプを推測します。そうでない場合、AppSheet は実際のレスポンスから列タイプを直接推測しようとします。

OpenAPI Spec エンドポイントは、Apigee の内部または外部でホストできます。SwaggerHub での例: OpenAPI Specification のサンプル

app.swaggerhub.com を api.swaggerhub.com で置き換えて、正しい API ベースの URL を取得します。

注: 提供された API キーは、OpenAPI Spec を取得するリクエストを行う際に、x-apikey としてヘッダーに渡されます。

Manual Apigee 接続

Manual Apigee 接続を設定する場合、Apigee API プロキシが API プロキシに必要なオペレーションで説明されている必須の API オペレーションをサポートしていることを確認してください。

API プロキシに必要なオペレーション

各テーブルで、以下の操作が必要となります。

次の API オペレーションは省略可能です。

テーブルのすべてのエントリを取得する（必須）

テーブルのすべてのエントリを取得するには、Apigee API プロキシが以下の API オペレーションをサポートしている必要があります。

GET /{tableName}  

ここで

  • {tableName} - テーブルの名前

レスポンスの本文は、テーブル名（例: "orders"）をキーとする JSON ペイロードで構成され、テーブルのすべての行の詳細を含みます。次に例を示します。

{
  "orders": [
  {
    "ID": 1,
    "TextValue": "Order1",
    "DecimalValue": 1.10,
    "DateTime": "1/1/2016 1:01:01 AM",
    "PhoneValue": "111 111 1111",
    "EmailValue": "email1@appsheet.com"
  },
  {
    "ID": 2,
    "TextValue": "Order2",
    "DecimalValue": 1.11,
    "DateTime": "2/1/2016 1:01:01 AM",
    "PhoneValue": "111 112 1111",
    "EmailValue": "email2@appsheet.com"
  }
  ]
}

テーブルのエントリを取得する（書き込みオペレーションで必須）

注: この API オペレーションは、書き込みオペレーションをサポートするために必要です。

テーブルのエントリを取得するには、Apigee API プロキシが以下の API オペレーションをサポートしている必要があります。

GET /{tableName}/{id} 

ここで

レスポンスの本文は、選択された行の詳細を含む JSON ペイロードで構成されます。

テーブルのエントリを作成する（省略可）

テーブルのエントリの作成をサポートするには、Apigee API プロキシが以下の API オペレーションをサポートしている必要があります。

POST /{tableName}

ここで

リクエストの本文には、作成される行の詳細が含まれます。ペイロードで指定された列は、AppSheet のキーと編集可能の列を設定するで説明しているように、アプリ作成者がエディタで Editable としてマークする必要があります。

テーブルのエントリを更新する（省略可）

テーブルのエントリを更新するには、Apigee API プロキシが以下の API オペレーションをサポートしている必要があります。

PUT /{tableName}/{id} 

ここで

リクエストの本文には、更新される行の詳細が含まれます。更新される列は、AppSheet のキーと編集可能の列を設定するで説明しているように、アプリ作成者がエディタで Editable としてマークする必要があります。

テーブルのエントリを削除する（省略可）

テーブルのエントリを削除するには、Apigee API プロキシが以下の API オペレーションをサポートしている必要があります。

DELETE /{tableName}/{id}

ここで

AppSheet のキーと編集可能の列を設定する

テーブル エントリの書き込みオペレーションをサポートするには、テーブル列で以下の設定を有効にする必要があります。

  • [Key?] - テーブル エントリを一意に識別します。キーとはをご覧ください。
  • [Editable?] - 列に対する書き込みオペレーションを可能にします。

テーブルの [Columns] ビュー。[KEY?] フィールドと [EDITABLE] フィールドがハイライト表示されている。キーとして [id] が選択されており、[id]、[age]、[name] はすべて編集可能

書き込みオペレーションを呼び出す際に、AppSheet はリクエストの本文を使用して、API を /{tableName}/{id} に送信します。上の例では、id がキー列です。ID フィールドのベスト プラクティスをご覧ください。リクエスト本文のフィールドに、Editable とマークされた列が含まれます。たとえば、上の例では、id、age、name です。

ID フィールドのベスト プラクティス

望ましいソリューションは、UNIQUEID() のような式を使用して、AppSheet で生成された 1 つの ID フィールドを持つことです。バックエンドで id フィールドが生成される場合は次のようになります。

  • API ペイロードには、そのエントリの主キーとして機能する 2 つのフィールドを使用することをおすすめします。一つは AppSheet が POST リクエスト本文で生成して送信するもので、もう一つはバックエンドが生成するものです。
  • AppSheet が生成した ID の場合、最初の値として UNIQUEID() の式を使用できます。
  • バックエンドが生成した ID フィールドは、POST リクエスト本文では空のままで、新しい行が作成された後の次の同期で入力されます。

API は、{id} パラメータに AppSheet ID またはバックエンドが生成した ID を入力して操作する必要があります。つまり、ID 照合はどちらの列の値でも機能する必要があります。AppSheet では、API 呼び出しに常に AppSheet が生成した ID が使用されます。

API がバックエンドによって生成される 1 つの ID フィールドしかサポートできない場合、次のようになります。

  • AppSheet は、API の {id}フィールドで一時的な一意の ID を生成する必要があります（API ID 列の [Initial Value] 設定の UNIQUEID() 式を使用します）。
  • POST オペレーションが呼び出されると、バックエンドはエントリの独自のキーを生成し、AppSheet が生成して POST 本文に渡した値を上書きします。
  • 作成（POST）操作が終了した後の次の Sync で、AppSheet はバックエンドによって生成された ID を取得し、AppSheet によって生成された一時的な ID は上書きされます。
  • これは、Sync オペレーションが発生する前に行が作成され、更新（または削除）された場合に問題になることがあります。オペレーションはキューに入っているため、更新操作に使用される ID は AppSheet が生成した一時的な ID となり、バックエンドには存在しなくなります。

ページ分割を有効にする

注: ページ分割は、OpenAPI Spec Apigee 接続でのみ有効にできます。

API でページ分割を有効にするには、OpenAPI Spec で GET ALL オペレーションの x-pagination 拡張機能を OpenAPI 拡張機能として指定する必要があります。Apigee データソースは、オフセット ベースとカーソルベースのページネーション ディレクティブをサポートしています。

一般的なパラメータ:

  • Type（必須）: オフセット | カーソル
  • limitParam（必須）: パラメータ オブジェクトの param キー。例: limit
  • defaultLimit: limit のデフォルト値。指定しない場合は 50 に設定されます。

オフベースのパラメータ:

  • offsetParam（必須）: パラメータ オブジェクトのオフセット param キー。
  • defaultOffset: オフセットのデフォルト値。指定しない場合は 0 に設定されます。

カーソルベースのパラメータ:

  • cursorParam（必須）: パラメータ オブジェクトのカーソル param キー。

例: OpenAPI Spec YAML のオフセットベースのパラメータ

/users:
    get:
      tags:
      - person
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          format: int64
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: Array of all person in the system with filter and pagination
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Person'
      x-pagination:
        type: offset
        limitParam: limit
        defaulLimit: 30
        offsetParam: offset
        defaultOffset: 0

URL：

api/users?limit=30&offset=0

 

例: OpenAPI Spec YAML のカーソルベースのパラメータ

/users:
get:
      tags:
      - person
      parameters:
      - name: page_size
        in: query
        required: false
        schema:
          type: integer
          format: int64
      - name: page_token
        in: query
        required: false
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: Array of all person in the system with filter and pagination
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Person'
      x-pagination:
        type: cursor
        limitParam: page_size
        defaulLimit: 30
        cursorParam: page_token

URL：

api/users?page_size=30&page_token=GIYDAOBNGEYS2MBWKQYDAO

フィルタ パラメータ（クエリ パラメータ / セキュリティ フィルタ）を指定する

注: フィルタ パラメータは、OpenAPI Spec Apigee 接続にのみ使用できます。

テーブルにフィルタを指定するには、OpenAPI Spec で GET ALL オペレーションの x-filter 拡張機能を OpenAPI 拡張機能として指定して、フィルタのタイプを指定する必要があります。Apigee データソースは、RHS-Colon と LHS-Brackets のみをサポートしています。

例: RHS-Colon

/users:
    get:
      tags:
      - publisher
      summary: Get all person
      responses:
        '200':
          description: Array of all person in the system with filter and pagination
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Person'
        '500':
          description: Internal server error.
      x-filter:
        type: RHS-Colon

 

type: と RHS-Colon または LHS-Brackets の間には必ずスペースを入れてください。

たとえば、次の構文は機能しません: type:RHS-Colon

スペースを含めた正しい構文: type: RHS-Colon

x-filter ディレクティブは、以下の表の演算子のみをサポートしています。この表は、セキュリティ フィルタのリソースと URL リクエストの間のマッピングも示しています（ユーザー テーブルでは例として年齢を使用しています）。

AppSheet の Apigee データソースのセキュリティ フィルタは、OpenAPI Spec で指定されているスキーム（RHS-Colon または LHS-Brackets）を使用して、これらのクエリ パラメータを介して API に渡されます。サポートされる演算子を以下の表に示します。

AppSheet Security Filter Operator

AppSheet Security Filter の例

フィルタ演算子

RHS-Colon の例

LHS-Brackets の例

=

[age]=25

eq

api/users?age=eq:25

api/users?age[eq]=25

<>

[age]<>25

neq

api/users?age=neq:25

api/users?age[neq]=25

>

[age]>25

gt

api/users?age=gt:25

api/users?age[gt]=25

>=

[age]>=25

gte

api/users?age=gte:25

api/users?age[gte]=25

<

[age]<25

lt

api/users?age=lt:25

api/users?age[lt]=25

<=

[age]<=25

lte

api/users?age=lte:25

api/users?age[lte]=25

API パスで複数のパラメータをサポートする

注: 複数パスのパラメータは、OpenAPI Spec Apigee 接続にのみ使用できます。

OpenAPI Spec Apigee 接続は、OpenAPI Spec で定義された API パスの複数のパラメータをサポートします。例:

/parentName/{parent}/tableName/{id}:
    get:
      parameters:
      - name: parent
        in: path
        required: true
        schema:
          type: integer
          format: int64
      - name: id
        in: path
        required: true
        schema:
          type: integer
          format: int64

...

パスパラメータの {parent} と {id} は、GET /myTable レスポンスで有効な列にマッピングされる必要があります。

  • tableName の主キーは {id} と推測されます。
  • tableNameの親テーブルキーは {parent} と推測されます。
  • 親テーブルは同じ OpenAPI Spec で定義されている必要があります。たとえば、/publishers/{id} と /publishers/{publisher}/books/{id} の両方で定義されている必要があります。

子テーブルを使用して、2 つのパスパラメータを持つ OpenAPI Spec を使用してアプリを作成する場合、Apigee データソースは 2 つのテーブル（一つは親テーブル、もう一つは子テーブル）を生成し、テーブル間の参照列を自動的に設定します。この場合、親テーブルは同じ OpenAPI Spec で定義されている必要があります。たとえば、/publishers/{id} と /publishers/{publisher}/books/{id} の両方が Spec で定義されている必要があります。

注:

  • 現在、AppSheet の Apigee データソースは、OpenAPI Spec の 2 つ のパスパラメータのみをサポートしています。

  • 各 OpenAPI Spec パスは、AppSheet の Apigee データソースの OpenAPI Spec 3.0 の要件を満たしている必要があります。

制限事項と報告されている問題

次に、制限事項と既知の問題を示します。

OpenAPI Spec ベースの Apigee 接続は、OpenAPI を厳密には守っていません。

  • OpenAPI Spec のリソース定義を使用せず、GET /resources からのレスポンスのスーパーセットを使用して列を構築します。
  • AppSheet は、最初のデータソース作成時に必要に応じてメールと電話番号のデータタイプを割り当てます。アプリ作成者は、アプリにテーブルが作成された後にデータを調整できます。
  • API キーのセキュリティ スキームを認識しません。AppSheet は API キーを x-apikey ヘッダーとしてのみ送信します。

トラブルシューティング

アプリを作成したりテストしたりする際に、以下のような例外が発生することがあります。例と可能な解決策を示します。

Your client credentials are invalid. Please ensure your Apigee client credentials and token url are correct.

認証情報が正しいことを確認してください。OAuth タイプでは、以下の curl コマンドを呼び出すことで認証情報を確認できます（curl は Linux ベースのシステムで利用可能です。MS DOS の場合は、サードパーティの curl プログラムのインストールが必要なことがあります）。サポートが必要な場合は、Apigee の管理者、デベロッパー、または IT スタッフにお問い合わせください。

curl -X POST -H "Content-Type: application/x-www-form-urlencoded" \
“tokenUrl” \
-d "client_id={key}&client_secret={secret}"

レスポンス本文に access_token を含む 200 のレスポンスが得られます。例:
{
   ...
   "token_type" : "BearerToken",
   "client_id" : "xNnREu1DNGfiwzQZ5HUN8IAUwZSW1GZW",
   "access_token" : "GTPY9VUHCqKVMRB0cHxnmAp0RXc0",
   "refresh_token_expires_in" : "30000", //--in seconds
   ...
}

次に、アクセス トークンを使って API を呼び出します。

curl https://{org-name}-test.apigee.net/tablename \
-H "Authorization: Bearer {access-token}"

Parsing of OpenAPI Spec failed. Error: The Apigee data source requires both the `GET /tableName` and 'GET /tableName/id'

Spec のすべてのテーブルに GET tableName と GET /tableName/id オペレーションが含まれていることを確認してください。詳細は、API プロキシの前提条件をご覧ください。

Error: Table 'table' is no longer connected to its schema/column structure. 

Apigee データソースが正常にテストのステップに合格し、認証されているにもかかわらず、アプリの作成中にこのエラーが表示される場合は、GET tableName のレスポンス形式を確認してください。この API は、このリストのキーを使用した行のリストをテーブル名 / プロキシ エンドポイントとして返すと想定されています。詳細は、API プロキシの前提条件をご覧ください。

この情報は役に立ちましたか？

改善できる点がありましたらお聞かせください。
true
検索
検索をクリア
検索を終了
Google アプリ
メインメニュー
921222196499201678
true
ヘルプセンターを検索
false
true
true
true
false
false
false
false