転送元 - GitHub(GraphQL)
  • 27 Apr 2022
  • 1 分で読み終わります
  • ダーク
    ライト

転送元 - GitHub(GraphQL)

  • ダーク
    ライト

概要

GitHub API v4(GraphQL)を用いてデータを転送する設定のヘルプページです。

GitHub API v4(GraphQL)を利用し、GraphQLクエリを記述することで各種クエリ結果をJSONレコードとして取得することができます。

取得可能なデータ

GitHub API v4でGraphQLクエリにより取得可能な全ての項目が対象です。
クエリ結果(JSON)に対し、転送対象のフィールドを絞ることが出来ます。絞り込みはJSON Path形式で対象パスを指定することで可能です。

また、絞り込み結果対象が配列の場合は1要素1行として取り込むことができます。
例)Issues一覧を取得した場合、Issuesの集合をパス指定することで各issueごとに取り込みことが可能です。

ページングが必要な項目については、 trocco 組み込みの GraphQL Varibales ( $__trocco_githubEndCursor__ )を利用することで
cursorをずらしながらのAPIリクエストが可能です。
詳しくは下記「ページネーションの仕組み」をご覧ください。

設定項目

STEP1 基本設定

項目 必須 デフォルト値 内容
GitHub接続情報 Yes - troccoに登録したGitHub接続情報を指定します。
GraphQLクエリ Yes ※クエリサンプル有 GitHub GraphQL API Explorer でクエリ結果を確認することが出来ます。
また、ページネーションを利用する場合はVariablesとして$\_\_trocco_githubEndCursor__を利用して複数ページに渡るリクエストを記述することが出来ます。
取り込み対象のパス(JSON Path) Yes - JSON結果から取得対象を絞り込むことができます。

例)
GraphQLクエリ結果として以下のJSONが取得できるとします。
{
"data": {
"repository": {
"issues": [{<#issue1>}, {<#issue2>}]
}
}
}

issuesだけを取り出したい場合、issuesの場所をJSON Path形式で指定します。
$.data.repository.issues
出力結果は以下になります
\[\{\<#issue1>}, \{\<#issue2>}]
出力結果が配列のため、issue1、issue2は別々の行として取り込まれます。
ページネーション Yes 無効 -
endCursorのパス(JSON Path) No
(ページネーションの場合Yes)
- クエリ結果のJSONに含まれるendCursorのパスを指定します。
なお、結果にendCursorを含むためには、GraphQLクエリでpageInfoを指定する必要があります。
詳しくは下記「ページネーションの仕組み」をご覧ください。

例)
$.data.repository.issues.pageInfo.endCursor
hasNextPageのパス(JSON Path) No
(ページネーションの場合Yes)
- クエリ結果のJSONに含まれるhasNextPageのパスを指定します。
なお、結果にhasNextPageを含むためには、GraphQLクエリでhasNextPageを指定する必要があります。
詳しくは下記「ページネーションの仕組み」をご覧ください。

例)
$.data.repository.issues.pageInfo.hasNextPage

※GraphQLクエリにはあらかじめクエリサンプルがデフォルト値として以下のように記述してあります。
image.png

ページネーションの仕組み

GitHub GraphQL API v4では、開始cursorをafterに指定することでEdgeの開始位置を指定することができます。
troccoでは、クエリレスポンスに含まれる最終cursorを取得し、組み込み変数の$\_\_trocco__githubEndCursor__に値を渡します。
次のページが存在する場合、クエリのafterに組み込み変数を指定することで次ページのリクエストを行います。
なお、取得上限は10,000ページです。

設定例

Organizationに所属するmembersの取得

Organization配下のmember のアカウント名、名前、roleを取得してみます。

GraphQLクエリ

※oraganizationのloginはお客様のOrganization名に書き換えてください。

query {
  organization(login: "primenumber-dev") {
    membersWithRole(first: 2) {
      edges {
        node {
          login
          name
        }
        role
      }
    }
  }
}

GitHub GraphQL API Explorerでクエリ結果を確認すると、以下のようなJSONであることが確認できます。

クエリ結果

{
  "data": {
    "organization": {
      "membersWithRole": {
        "edges": [
          {
            "node": {
              "login": "trocco-taro",
              "name": "trocco Taro"
            },
            "role": "ADMIN"
              },
        {
          "node": {
            "login": "trocco-hanako",
            "name": "trocco Hanako"
          },
          "role": "ADMIN"
        }
    }
  }
}
}

取り込みたいのは各memberの情報なので、 以下のように data > organization > memberWithRole > edges をJSON Pathで指定し、
member単位でレコードとして取り込みます。

取り込み対象パスの指定 (JSON Path)

$.data.organization.memberWithRole.edges
このとき、edgesは配列のため、1要素ごと1レコードとして取り込むことができます。

最終的に以下のように取り込むことができました。

records
{"node": { "login": "trocco-taro", "name": "trocco Taro" }, "role": "ADMIN"}
{"node": { "login": "trocco-hanako", "name": "trocco Hanako" }, "role": "ADMIN"}

Repository配下の全Issues取得(ページネーション利用)

GraphQLクエリ

query($__trocco__githubEndCursor__:String){
  repository(owner: "<#input your organization>", name: "<#input your repository>") {
    issues(first: 100, states: OPEN, after:$__trocco__githubEndCursor__) {
      edges {
        node {
          title
          url
          number
          updatedAt
        }
      }
      pageInfo {
        endCursor
        hasNextPage
      }
    }
  }
}

パスの指定

取り込み対象のパス $.data.repository.issues.edges[*].node
pageInfo.endCursor のパス $.data.repository.issues.pageInfo.endCursor
pageInfo.hasNextPage のパス $.data.repository.issues.pageInfo.hasNextPage

この記事は役に立ちましたか?