【GraphQL】基礎的な書き方から、AniList API用のMutationクエリ（複数レコード更新）まで。

はじまり#

リサちゃん

あぁぁ、目が回りそうだぁ！

135ml

GraphQLを組み立てているね

リサちゃん

これって、()なの？　{}なの？

135ml

おさらいしてみましょうか

GraphQLを触ってみました#

なので、今回はGraphQLに関する記事を書いてみます。本記事では、GraphQLの基礎的な書き方をから、初心者でも迷わずにクエリを構築できるように、基本的なQueryとMutationの書き方を紹介します。後の方では、実際にAniListというサービスで叩いた結果を紹介します。

GraphQLの基本的な部分#

まず、GraphQLとは？

スゴイざっくり言うと、「APIにアクセスするための仕組み」です。

LinuxでおなじみのRed Hatさんの記事ではこう書いてあります。（会社の業務で触ったLinuxなつかしい・・・）

GraphQL (グラフキューエル、グラフQL) とは、API (アプリケーション・プログラミング・インタフェース向けのクエリ言語とサーバーサイドのランタイムの両方を指します。GraphQL は、クライアントがリクエストしたデータのみを返すことを優先します。
ここから引用

なるほど、クエリだけじゃなくてランタイムも引っくるめて「GraphQL」なんだな。 GraphQLは、同じAPIの仕組みの一つである「Rest API」と比べて、としては、データの取得や更新が行いやすいクエリ言語を備えています。

クエリを書く前に#

クエリを書く前に、以下の2点を確認する必要があります。

1. GraphQLスキーマ#

GraphQLスキーマは、GraphQLサーバーで提供されているデータの種類と構造を定義するものです。スキーマは、SDL（Schema Definition Language）と呼ばれる言語で記述されます。

2. 取得したいデータ#

どのようなデータを取得したいかを明確にしましょう。具体的な項目名や関連データなども考慮する必要があります。

クエリの書き方#

基本構文#

GraphQLクエリの基本構文は次のとおりです。

1
query {
2
  # 取得したいデータのフィールドを記述
3
}

例えば、ユーザー情報と投稿情報を取得するクエリは次のようになります。

1
query {
2
  user {
3
    id
4
    name
5
    birthDate
6
  }
7
  posts {
8
    id
9
    title
10
    content
11
  }
12
}

このクエリは、userフィールドとpostsフィールドを指定しています。userフィールドではIDとユーザー名を取得し、postsフィールドではID、題名、内容を取得します。

Arguments#

取得する情報に条件を付けることが出来ます。

1
query {
2
  users(name: "Tom") {
3
    id
4
    name
5
    age
6
    birthDate
7
  }
8
}

この場合は、名前が「Tom」だけのユーザーを取得することになります。

Nest#

ときどき、取得する情報が細分化されて、さらに属性を持っていたりもします。

1
query {
2
  users(name: "Tom") {
3
    id
4
    name
5
    age
6
    birthDate {
7
      year
8
      month
9
      day
10
    }
11
  }
12
}

この場合は、ユーザーの誕生日が、さらに年、月、日に分かれているパターンとなります。

Variables#

そして、属性のパラメータ値は、まとめて別の場所で宣言することが出来ます。例えば、こんなクエリに対して、

1
query {
2
  users(name: "Tom") {
3
    id
4
    name
5
    age
6
    birthDate(year: 2023) {
7
      year
8
      month
9
      day
10
    }
11
  }
12
}

queryフィールドとは別に、variablesフィールドとして、パラメータを一括に宣言できます。宣言方法は次の節で・・・

1
{
2
  userName: "Tom"
3
  birthYear: 2023
4
}
5

6
query ($username: String, $birthYear: Int) {
7
  users(name: $userName) {
8
    id
9
    name
10
    age
11
    birthDate(year: $birthYear) {
12
      year
13
      month
14
      day
15
    }
16
  }
17
}

パラメータに使える型は、String、Int、Float、Booleanなど、色々あります。

JavaScriptとかでJSON.stringifyすれば・・・#

JavaScritpなどでクエリを作る際に、JSON.stringify()を使えば、クエリとは別にvariablesを宣言できます。例えば、JavaScriptライクな言語「Google Apps Script」からGraphQLを打つ場合は、こんな感じでAPIにアクセスする記述が出来ます。

1
let variables = {
2
  userName: "Tom"
3
  birthYear: 2023
4
}
5

6
let query = `query ($username: String, $birthYear: Int) {
7
  users(name: $userName) {
8
    id
9
    name
10
    age
11
    birthDate(year: $birthYear) {
12
      year
13
      month
14
      day
15
    }
16
  }
17
}
18
`;
19

20
let options = {
21
  method: "POST"
22
  , headers: {
23
    "Content-Type": "application/json",
24
    "Accept": "application/json"
25
  }, payload: JSON.stringify({
26
    query: query
27
    , variables: variables
28
  })
29
};
30

31
let response = UrlFetchApp.fetch(url, options);

Mutation#

さて、queryフィールドでは、データを参照するのが主な用途ですが、データを書き換えたりもしたくなります。そこで使うのが、mutationフィールドです。

1
mutation {
2
  createUser(input: { name: "Mary", age: 94 }) {
3
    id
4
    name
5
    age
6
  }
7
}

mutationフィールドでは、編集する属性を指定して、どの属性をレスポンスとして受け取るかを指定することが出来ます。上記のクエリの場合だと、IDがアッチ側で自動採番だとしてこんな風に返ってきます。

1
{"data":{"createUser":{"id":3,"name":"Mary,"age":94}}}

Mutationでvariables#

mutationフィールドでも、もちろんvariablesが利用できます。宣言方法は、「JavaScriptとかでJSON.stringifyすれば・・・」の節と同様。

1
variables = {
2
  userName: "Mary"
3
  age: 94
4
}
5

6
mutation ($userName: String, $age: Int) {
7
  createUser(input: { name: $userName, age: $age }) {
8
    id
9
    name
10
    age
11
  }
12
}

Mutation内のNestにvariablesを使う#

mutationフィールド内で入れ子になっている部分にvariablesを使いたい場合に、こんがらがってしまうかもしれません。（実際に僕はこんがらがりました。）こんな風にします。

1
variables = {
2
  userName: "Mary"
3
  age: 94
4
  birthYear: 2005
5
}
6

7
mutation ($userName: String, $age: Int) {
8
  createUser(input: { name: $userName, age: $age, birthDate: {year: $birthYear}) {
9
    id
10
    name
11
    age
12
    birthDate {
13
      year
14
      month
15
      day
16
    }
17
  }
18
}

あくまで、createUserの「{}」の中身は「参照」したい属性なので、「()」の引数に変数を「設定」しましょう。

1
variables = {
2
  userName: "Mary"
3
  age: 94
4
  birthYear: 2005
5
}
6

7
mutation ($userName: String, $age: Int) {                                           // <- 変数を設定したい
8
  createUser(input: { name: $userName, age: $age, birthDate: {year: $birthYear}) {  // <- 対象を設定したい
9
    id                             // <- 参照したい
10
    name                           // <- 参照したい
11
    age                            // <- 参照したい
12
    birthDate {
13
      year                         // <- 参照したい
14
      month                        // <- 参照したい
15
      day                          // <- 参照したい
16
    }
17
  }
18
}

そして、実際にAniList APIで叩いてみた#

「AniList」というのは、自分が今までに見たアニメや、これから見たいアニメ、読みたいマンガなどを登録、管理できるサービスです。

AniList

anilist.co

APIのリファレンスのGetting-Startedはここで、GraphQLの属性のリファレンスはここです。

その管理しているデータベースには、「AniList API」を使って参照することができて、編集することも出来ます。こんな風に打ち込みます。まずはqueryでデータ取得です。

1
variables = {
2
  username: "anilistUserName"
3
  , userid: "anilistUserId"
4
}
5

6
query ($username: String, $id: Int) {
7
  MediaListCollection(userName: $username, userId: $id, type: ANIME) {
8
    lists {
9
      entries {
10
        media {
11
          id
12
          title {
13
            native
14
          }
15
          coverImage {
16
            extraLarge
17
          }
18
          siteUrl
19
          studios (isMain: true, sort: FAVOURITES) {
20
            nodes {
21
              name
22
            }
23
          }
24
        }
25
        score (format: POINT_100)
26
        status
27
        progress
28
        completedAt {
29
            year
30
            month
31
            day
32
        }
33
        notes
34
        updatedAt
35
      }
36
    }
37
  }
38
}

次で、mutationでデータの編集をしています。

1
variables = {
2
  mediaId: 21127
3
  , status: "CURRENT"
4
  , score: 100
5
  , progress: 13
6
  , completedAtYear: 2022
7
  , completedAtMonth: 1
8
  , completedAtDay: 13
9
  , notes: "エル・プサイ・コングルゥ。"
10
}
11

12
mutation ($mediaId: Int, $status: MediaListStatus, $score: Float, $progress: Int, $completedAtYear: Int, $completedAtMonth: Int, $completedAtDay: Int, $notes: String) {
13
  SaveMediaListEntry (mediaId: $mediaId, status: $status, score: $score, progress: $progress, notes: $notes, completedAt: {year: $completedAtYear, month: $completedAtMonth, day: $completedAtDay}) {
14
    id
15
    mediaId
16
    status
17
    score (format: POINT_100)
18
    progress
19
    completedAt {
20
      year
21
      month
22
      day
23
    }
24
    notes
25
  }
26
}

レスポンス:

1
{"data":{"SaveMediaListEntry":{"id":246757832,"mediaId":21127,"status":"CURRENT","score":100,"progress":13,"completedAt":{"year":2022,"month":1,"day":13},"notes":"\u30a8\u30eb\u30fb\u30d7\u30b5\u30a4\u30fb\u30b3\u30f3\u30b0\u30eb\u30a5\u3002"}}}

複数レコードを編集したいときは？#

AniList APIでは、「1分間に90リクエストまで」のレート制限が設けられています。そのため、複数のアニメを編集したいときは、クエリをまとめて送りたいですよね。 Google Apps Scriptで組むと、こんな風に複数レコードに対する1クエリが作成できます。

1
let variableses = [
2
      {
3
        "mediaId": 21127
4
        , "status": "CURRENT"
5
        , "score": 100
6
        , "progress": 13
7
        , "completedAtYear": 2021
8
        , "completedAtMonth": 1
9
        , "completedAtDay": 13
10
        , "notes": "エル・プサイ・コングルゥ。"
11
      }
12
      , {
13
        "mediaId": 9253
14
        , "status": "PLANNING"
15
        , "score": 90
16
        , "progress": 13
17
        , "completedAtYear": 2017
18
        , "completedAtMonth": 3
19
        , "completedAtDay": 15
20
        , "notes": "ファーーーハッハッハッハ"
21
      }
22
    ];
23
    console.log(variableses.length);
24
    console.log(`getRequestOptionsAnilist: 3333333333333333333333333333333333333333333333`);
25
    for(let i = 0; i < variableses.length; i++){
26
      query = `
27
        ${query}
28
        saveMedia${i}: SaveMediaListEntry (mediaId: ${variableses[i]["mediaId"]}, status: ${variableses[i]["status"]}, score: ${variableses[i]["score"]}, progress: ${variableses[i]["progress"]}, notes: "${variableses[i]["notes"]}", completedAt: {year: ${variableses[i]["completedAtYear"]}, month: ${variableses[i]["completedAtMonth"]}, day: ${variableses[i]["completedAtDay"]}}) {
29
          id
30
          mediaId
31
          status
32
          score (format: POINT_100)
33
          progress
34
          completedAt {
35
            year
36
            month
37
            day
38
          }
39
          notes
40
        }
41
      `;
42
    }
43
    query = `mutation {${query}}`;
44
    console.log(query);
45
    console.log(`getRequestOptionsAnilist: 44444444444444444444444444444444444444444444`);
46

47
    options = {
48
      method: "POST",
49
      headers: {
50
        "Authorization": `Bearer ${access_token}`,
51
        "Content-Type": `application/json`,
52
        "Accept": `application/json`,
53
      }
54
      , payload: JSON.stringify({
55
        query: query
56
      })
57
      , muteHttpExceptions : true
58
    }

上記でミソなのは、SaveMediaListEntryの前に、saveMedia${i}:という風にフィールドに名前を付けている点です。

少し脱線しますが、1つのリクエストに付きのクエリの長さのレート制限は、確認することが出来ませんでした。まあ程々にでしょうか。

まとめ#

以上がGraphQLの基礎的なクエリの書き方と少し応用といった感じでした。 queryとmutationを使いこなして、効果的にデータを取得・変更できるようになると、GraphQLの真価がより体感できるでしょう。ぜひこれを参考に、日々の活動でGraphQLを活用してみてください。

おしまい#

リサちゃん

ほぁぁ、こう書くのか！

135ml

一回書けてしまえばなぁ。

以上になります！

音楽

音楽

はじまり#

GraphQLを触ってみました#

GraphQLの基本的な部分#

クエリを書く前に#

1. GraphQLスキーマ#

2. 取得したいデータ#

クエリの書き方#

基本構文#

Arguments#

Nest#

Variables#

JavaScriptとかでJSON.stringifyすれば・・・#

Mutation#

Mutationでvariables#

Mutation内のNestにvariablesを使う#

そして、実際にAniList APIで叩いてみた#

複数レコードを編集したいときは？#

まとめ#

おしまい#

記事を共有

音楽

目次