obnizクラウドAPI

obnizクラウドAPIはアカウントに紐づくデバイスやサーバーレスイベントなどを操作するためのAPIです。WebAppを作成し、ユーザーから承認を得ることで自分または他のユーザーに対して利用できます。現在以下の情報が操作できます。

  • WebApp自体
  • WebAppのインストール情報
  • 承認したユーザーのユーザー情報
  • 承認したユーザーの所有デバイス
  • 承認したユーザーのサーバーレスイベント

GraphQL API

GraphQL

obnizクラウドAPIはGraphQLを採用しています。エンドポイントは以下です

https://api.obniz.com/v1/graphql

エンドポイントに対してトークンとクエリを与えることで結果が取得できます。

const graphQLClient = new GraphQLClient(`https://api.obniz.com/v1/graphql`, {
  headers: {
    authorization: `Bearer ${token}`,
  },
});
const query = `{
  user {
    id,
    name,
    email
  }
}`;
const user = await graphQLClient.request(query);

GraphQLの通信はHTTPSプロトコルを使用して行われます。
そのため、GraphQLクライアントを使用できない場合でも、通常のHTTPリクエストと同様に扱うことが出来ます。
詳細はこちらをご覧ください。

GraphQLについて

GraphQLは必要なデータのみ取得することを可能とするクエリ言語で、SQLのSELECT文のようなものです。

GraphQL APIにはQueryとMutationが存在し、下記のように扱うことが出来ます。

  • Query ≒ SELECT文
  • Mutation ≒ UPDATE文

詳細はこちらをご覧ください。

ドキュメント

https://api.obniz.com/v1/graphql
をブラウザで開くことでドキュメントと共にAPIのデモ画面を開くことができます。
APIの利用にはトークンのヘッダへの付与が必要になるためオンラインデモ画面では利用できません。

実際の利用にはリクエストヘッダにトークンの付与ができるデスクトップ用のGraphQLアプリを活用するのが便利です。

Altair
Apollo

SDK

GraphQL endpointを使うためのTypeScript/JavaScriptのSDKを公開しています。
https://github.com/obniz/obniz-cloud-sdk

型定義がされているため、IDEの補完やTypeScriptの型チェックを利用することができます。

使い方はREADMEを参照ください

トークン

APIを利用し、ユーザー情報にアクセスするには、WebAppを作成しユーザーにWebAppを承認してもらう必要があります。承認することでトークンが発行されます。また、トークンにはユーザーごとに発行されるものと、WebApp自体のトークンの2種類があります。

  • WebApp トークン: WebApp自体のトークンです。インストール情報が取得できます。
  • OAuth トークン: ユーザーが承認した場合に得られるユーザーごとのトークンです。ユーザーに紐づく情報が操作できます。

それぞれ取得にはWebAppが必要です。詳しくはアプリを御覧ください。

トークンはGraphQL APIを叩く際のリクエストヘッダーに付与します

authorization: Bearer oauth_xxxxxxx

サンプルコード

APIを利用するサンプルコードがGitHubに公開されています。

OAuthを利用したユーザー情報やデバイス情報の操作について
https://github.com/obniz/obniz-webapp-example-oauth

インストールを用いたユーザーがインストールしたアプリ情報の取得とWebサービスの開発方法について
https://github.com/obniz/obniz-webapp-example-install

インストール

IoT開発では同じプログラムを複数のデバイス共通で利用し、かつデバイスごとに違う設定で稼働させるシーンがあります。そこで、obnizのWebAppではユーザーが承認しアクセストークンを発行するだけでなく、ユーザーがWebAppを設定とともに複数「インストール」することができるようになっています。WebAppはアクセストークンを利用してそのインストール情報を取得することでWebAppを構成することができます。

ユーザーがインストールする流れは以下となります。

  1. サーバーシステムをAWSなどクラウドサービスで稼働しWebAppとしてobnizクラウド上に登録。
  2. ユーザーがWebAppを承認
  3. ユーザーがWebAppをインストール
    インストール時にはWebAppで用意されている設定事項がユーザーに質問され、インストール時に保存されます。
    また、WebAppにWebhook URLが設定されている場合はインストール時にwebhookが発行されます。
  4. WebAppがobnizクラウドAPIを呼び出し、インストールされている全てのWebAppを取得。
  5. WebApp内でインストール情報を元にプログラムを実行・場合によってはオートスケールアウトなどを実施
  6. ユーザーのインストールイベントごと(インストールの作成/更新/削除)発行されるwebhookまたは定期的なfetchによりユーザーの設定とWebAppを同期させる

WebAppのインストールについて詳しくは以下をご覧ください。

WebApp/インストール

関連の質問