1. Homepage
  2. DataGraph
  3. Anypoint DataGraph 入門

  4. API スキーマの要素の理解

API スキーマの要素の理解

Anypoint DataGraph は、クライアントが使用できるようにするために選択したすべてのデータを統合スキーマに整理します。統合スキーマは、追加するすべての API のすべてのスキーマの単一コレクションで、常に最新です。

統合スキーマに新しい API を追加すると、Anypoint DataGraph は API の RAML または OAS 仕様から API スキーマを生成します。各 API スキーマは、その API が追加されたときに作成されるため、統合スキーマは常に最新です。また、すべての API スキーマは組織内に個別に保存されるため、他のスキーマの整合性に影響を与えることなく、個別に編集できます。

Anypoint DataGraph が生成する API スキーマには、API 仕様で定義した GET リソースとエンティティのコレクション、およびそれらの間のリレーションが含まれます。統合スキーマに新しい API スキーマを追加するときはいつでも、統合スキーマに含まれる種別と項目を設定できます。

種別に適用できるさまざまな設定について学習する前に、次のトピックを参照し、API 仕様に応じて API スキーマに存在する可能性があるさまざまな種別を理解してください。

オブジェクト種別と項目

スキーマで最も一般的な種別であるオブジェクト種別は、GET 応答の一部として返される API 仕様のエンティティを表します。オブジェクト種別にはわかりやすい名前が付けられ、オブジェクトのプロパティを示す項目が含まれています。

たとえば、RAML 仕様では、仕様の各種別要素はオブジェクト種別、列挙種別、結合種別のいずれかになります。また、各種別要素のプロパティは、API スキーマ内のそれらのオブジェクト種別の項目です。

RAML API 仕様 API スキーマ 
#%RAML 1.0
title: Order API

types:
  Order:
    type: object
    properties:
      orderId:
      date:
      status:


  Product:
    type: object
    properties:
      productId:
      name:
      brand:

/orders/​{id}​:
  get:
    displayName: Get Order by ID
 
ordersById(id): Order
--------------------
--------------------
Order
--------------------
orderId: ID!
date: String
status: String
--------------------
--------------------
Product
--------------------
productId: ID!
name: String
brand: String

Order​ と ​Product​ は両方とも異なるオブジェクト種別であり、それぞれに異なる項目があり、次のように表すことができます。

type Order {
  orderId: ID!
  date: String!
  status: String!
}
type Product {
  productId: ID!
  name:String!
  brand: String!
}

項目のデータ型

各項目は、クエリの応答で返される型のデータセットを表します。デフォルトでは、5 個のスカラー型があります。

  • Int​:
    符号付き 32 ビット整数。

  • Float​:
    符号付き倍精度浮動小数点値。

  • String​:
    UTF-8 文字シーケンス。

  • Boolean​:
    true​ または ​false​。

  • ID​:
    ID スカラー型は一意の識別子を表し、オブジェクトの再取得やクエリメソッドのキーとしてよく使用されます。ID 型は、文字列と同じ方法でシリアル化されます。ただし、ID としての定義は人間が読める形式ではないことを意味します。

null 不可能な項目

!​ 記号で表された値を含む項目は null 不可能です。つまり、項目は null 値で応答できません。たとえば、​Product​ 種別では、ID を null にすることはできません。

type Product {
  productId: ID!
  name:String
  brand: String
}

また、​Order​ 種別では、どの値も null にすることはできません。

type Order {
  orderId: ID!
  name: String!
  price: String!
  brand: Int!
}

クエリ種別とクエリメソッド

クエリ種別は、要求を行うときの API スキーマへのエントリポイントです。クエリ種別には、API 仕様で定義した GET エンドポイントを表すクエリメソッドが含まれます。

たとえば、​/orders/{id}​ で GET エンドポイントを定義する RAML 仕様では、スキーマのクエリメソッドは ​ordersById(id)​ です。

RAML API 仕様 API スキーマ 
#%RAML 1.0
title: Order API

/orders/​{id}​:
  get:
    displayName: Get Order by ID
 
ordersById(id): Order

レベル-1 種別とネストされた種別

スキーマ内の種別は、種別とクエリメソッド間のリレーションに依存するカテゴリに属しています。

  • レベル-1 種別
    これらの種別にはクエリメソッドが関連付けられているため、直接アクセスできます。

    たとえば、前の API 仕様では、​order/{id}​ エンドポイントに GET が関連付けられているため、​Order​ はレベル-1 オブジェクト種別です。

    このオブジェクト種別には、クエリメソッドを直接使用してアクセスできます。

    ordersById (orderId: “123”) {
  orderId
  date
}

  • ネストされた種別
    これらの種別にはクエリメソッドが関連付けられていないため、レベル-1 種別のクエリメソッドを介してのみアクセスできます。

    たとえば、前の API 仕様では、​Product​ はクエリメソッドが関連付けられていないオブジェクト種別です。​Product​ 種別の項目を照会するには、そのレベル-1 種別 ​Order​ に関連付けられているメソッドを照会する必要があります。

    ordersById(id: "123") {
     orderId
     product {
         name
         price
     }
}

この構造に従うと、クエリメソッドはレベル 0 種別とみなされます。

列挙種別

列挙種別は、特定の値のセットのみを返すことができる種別です。API 仕様で列挙種別を宣言して、項目が常に有限の値のセットを返すようにすることができます。

たとえば、オブジェクト種別 ​Processing​、​Completed​、​Canceled​ のいずれかを返す必要がある ​OrderStatus​ 種別を定義する RAML 仕様があるとします。

RAML API 仕様 API スキーマ 
#%RAML 1.0
title: Order API

types:
  OrderStatus:
    type: string
    description: Current status of the order
    enum: [Processing, Completed, Canceled]
 
enum OrderStatus {
  Processing
  Completed
  Canceled
}

結合種別

結合種別は、他のオブジェクト種別を使用してデータのインスタンスを説明します。結合種別は 1 つ以上の特定のオブジェクト種別で構成されます。

たとえば、RAML 仕様では、​Notebook​ や ​Phone​ などの他の種別を使用して ​Product​ 種別を定義できます。

RAML API 仕様 API スキーマ 
#%RAML 1.0
title: Order API

types:

  Product:
    type: Phone | Notebook

  Notebook:
    type: object
    properties:
      manufacturer:
        type: string
      numberOfUSBPorts:
        type: number
      kind: string

  Phone:
    type: object
    properties:
      manufacturer:
        type: string
      numberOfSIMCards:
        type: number
      kind: string
 
Product
--------------------
Notebook
Phone
--------------------
--------------------
Notebook
--------------------
manufacturer: String
numberOfUSBPorts: int
--------------------
--------------------
Phone
--------------------
manufacturer: String
numberOfSIMCards: int

変異および入力種別

変異​は、データオブジェクトを追加、更新、および削除するために使用する操作です。GraphQL では、変異操作は REST API 仕様で定義した POST、PATCH、PUT、DELETE、および HTTP メソッドを表します。

たとえば、この RAML 仕様は ​/createOrder/{OrderInput}​ で POST エンドポイントを定義し、スキーマの変異メソッドは ​createOrder(input:OrderInput)​ です。

RAML API 仕様 API スキーマ 
#%RAML 1.0
title: Order API

/createOrder/​{OrderInput}​:
  post:
    displayName: Create Order by OrderInput
 
createOrder(input:OrderInput): Order

入力種別は、変異操作によって作成されたオブジェクトの属性を表します。入力種別は、変異を実行するときに統合スキーマの情報を変更するために使用する POST、PUT、および DELETE 要求オブジェクトです。

たとえば、​/createOrder/{OrderInput}:​ 変異を使用して ​OrderInput​ 入力種別に送信できます。

createOrder (input: “123”) {
  orderId
  customerEmail
  cutomerID
  orderDate
  product
  status
  totalAmount
}

関連リソース