GraphQL API

GraphQLはAPI用のクエリ言語です。GraphQLを使用すると、必要なデータを正確にリクエストできるため、必要なリクエストの数を限定することができます。

GraphQLデータは型別に配置されているため、クライアントはクライアント側のGraphQLライブラリを使用してAPIを消費することで、手動の解析を回避することができます。

GraphQL APIはバージョンなしです。

はじめに

GitLab GraphQL APIを初めて使用する場合は、GitLab GraphQL APIのスタートガイドを参照してください。

利用可能なリソースは、GraphQL APIリファレンスで確認できます。

GitLab GraphQL APIエンドポイントは/api/graphqlにあります。

インタラクティブGraphQLエクスプローラー

次のいずれかで、インタラクティブGraphQLエクスプローラーを使用してGraphQL APIを調査できます。

• GitLab.com。
• https://<your-gitlab-site.com>/-/graphql-explorerでのGitLab Self-Managed。

詳細については、GraphiQLを参照してください。

GraphQLの例を見る

GitLab.comのパブリックプロジェクトからデータをプルするサンプルクエリを使用できます。

• 監査レポートを作成する
• イシューボードを特定する
• ユーザーのクエリ
• カスタム絵文字を使用する

スタートガイドページには、GraphQLクエリをカスタマイズするためのさまざまな方法が記載されています。

認証

一部のクエリには認証無しでアクセスできますが、その他のクエリには認証が必要です。ミューテーションには常に認証が必要です。

次のいずれかを使用して認証できます。

• トークン
• セッションクッキー

認証情報が無効である場合、GitLabはステータスコード401とエラーメッセージを返します。

{"errors":[{"message":"Invalid token"}]}

トークン認証

次のいずれかのトークンを使用して、GraphQL APIで認証します。

• OAuth 2.0トークン
• パーソナルアクセストークン
• プロジェクトアクセストークン
• グループアクセストークン

リクエストヘッダーで、またはパラメータとしてトークンを渡すことにより、トークンで認証します。

トークンには正しいスコープが必要です。

ヘッダー認証

Authorization: Bearer <token>リクエストヘッダーを使用したトークン認証の例:

curl --request POST \
  --url "https://gitlab.com/api/graphql" \
  --header "Authorization: Bearer <token>" \
  --header "Content-Type: application/json" \
  --data "{\"query\": \"query {currentUser {name}}\"}"

パラメータ認証

access_tokenパラメータでOAuth 2.0トークンを使用する例:

curl --request POST \
  --url "https://gitlab.com/api/graphql?access_token=<oauth_token>" \
  --header "Content-Type: application/json" \
  --data "{\"query\": \"query {currentUser {name}}\"}"

private_tokenパラメータを使用して、パーソナルアクセストークン、プロジェクトアクセストークン、またはグループアクセストークンを渡すことができます。

curl --request POST \
  --url "https://gitlab.com/api/graphql?private_token=<access_token>" \
  --header "Content-Type: application/json" \
  --data "{\"query\": \"query {currentUser {name}}\"}"

トークンスコープ

GraphQL APIにアクセスするには、トークンに次のいずれかの正しいスコープが必要です。

セッションクッキー認証

メインのGitLabアプリケーションにサインインすると、_gitlab_sessionセッションクッキーが設定されます。

インタラクティブGraphQLエクスプローラーとGitLab自体のWebフロントエンドは、この認証方法を使用します。

オブジェクト識別子

GitLab GraphQL APIは、さまざまな識別子を使用します。

グローバルID、フルパス、内部ID（IID）はすべて、GitLab GraphQL APIで引数として使用されますが、多くの場合、スキーマの特定の部分は、これらのすべてを同時に受け入れるわけではありません。

これまで、この点に関してGitLab GraphQL APIは一貫性がありませんでしたが、一般的には次のことが言えます。

• オブジェクトがプロジェクト、グループ、またはネームスペースである場合は、オブジェクトのフルパスを使用します。
• オブジェクトにIIDがある場合は、フルパスとIIDの組み合わせを使用します。
• その他のオブジェクトについては、グローバルIDを使用します。

たとえば、フルパス"gitlab-org/gitlab"でプロジェクトを見つける場合は、次のように使用します。

{
  project(fullPath: "gitlab-org/gitlab") {
    id
    fullPath
  }
}

プロジェクトのフルパス"gitlab-org/gitlab"とイシューのIID"1"によってイシューをロックする別の例:

mutation {
  issueSetLocked(input: { projectPath: "gitlab-org/gitlab", iid: "1", locked: true }) {
    issue {
      id
      iid
    }
  }
}

グローバルIDでCI Runnerを見つける例は次のとおりです。

{
  runner(id: "gid://gitlab/Ci::Runner/1") {
    id
  }
}

これまで、フルパスフィールドとIIDフィールドおよび引数の型に関して、GitLab GraphQL APIは一貫性がありませんでしたが、一般的には次のことが言えます。

• フルパスフィールドと引数は、GraphQL ID型です。
• IIDフィールドと引数はGraphQL String型です。

グローバルID

GitLab GraphQL APIでは、idという名前のフィールドまたは引数は、ほぼすべての場合、グローバルIDであり、データベースのプライマリキーIDではありません。GitLab GraphQL APIのグローバルIDは、"gid://gitlab/"で始まります。例: "gid://gitlab/Issue/123"。

グローバルIDは、慣例としてクライアント側の一部のライブラリでキャッシュとフェッチに使用されます。

GitLabのグローバルIDは変更される可能性があります。変更された場合、古いグローバルIDの引数としての使用は非推奨となり、非推奨と破壊的な変更のプロセスに従ってサポートされます。キャッシュされたグローバルIDがGitLab GraphQLの非推奨サイクル期間を超えて有効になることは想定されていません。

利用可能なトップレベルクエリ

すべてのクエリのトップレベルのエントリポイントは、GraphQLリファレンスのQuery型で定義されています。

多重クエリ

GitLabは、クエリを1つのリクエストにまとめることをサポートしています。詳細については、マルチプレックスを参照してください。

破壊的な変更

GitLab GraphQL APIはバージョンなしであり、APIの変更については、基本的に下位互換性があります。

ただし、GitLabは下位互換性なしでGraphQL APIを変更する場合があります。これらの変更は破壊的な変更と見なされ、フィールド、引数、またはスキーマのその他の部分の削除または名前変更が含まれる場合があります。GitLabは破壊的な変更を作成する場合、非推奨と削除のプロセスに従います。

破壊的な変更がインテグレーションに影響を与えないようにするには、次のようにする必要があります。

• 非推奨と削除のプロセスを理解する。
• 将来の破壊的な変更のスキーマに対してAPIコールを頻繁に検証する。

GitLab Self-Managedの場合、EEインスタンスからCEへの復元は破壊的な変更を引き起こします。

破壊的な変更の適用除外

GraphQL APIリファレンスで実験とラベル付けされたスキーマアイテムは、非推奨プロセスの対象外です。これらのアイテムは、予告なしにいつでも削除または変更される可能性があります。

機能フラグで制御されており、デフォルトで無効になっているフィールドは、非推奨と削除のプロセスに従いません。これらのフィールドは、予告なしにいつでも削除される可能性があります。

将来の破壊的な変更スキーマを検証する

すべての非推奨アイテムがすでに削除されているかのように、GraphQL APIを呼び出すことができます。このようにすると、アイテムが実際にスキーマから削除される前に、破壊的な変更のリリースに先立ってAPIコールを検証できます。

これらの呼び出しを行うには、remove_deprecated=trueクエリパラメータをGraphQL APIエンドポイントに追加します。たとえば、GitLab.comのGraphQLの場合は、https://gitlab.com/api/graphql?remove_deprecated=trueになります。

非推奨と削除のプロセス

GitLab GraphQL APIからの削除対象としてマークされたスキーマの一部は、最初に非推奨になりますが、少なくとも6つのリリースでは引き続き利用できます。その後、次のXX.0メジャーリリース中に完全に削除されます。

アイテムは以下で非推奨とマークされます。

• スキーマ。
• GraphQL APIリファレンス。
• 非推奨機能の削除スケジュール。このスケジュールはリリース投稿からリンクされています。
• GraphQL APIのイントロスペクションクエリ。

非推奨メッセージは、該当する場合、非推奨スキーマアイテムの代替案を提供します。

破壊的な変更が発生しないようにするには、GraphQL APIコールから非推奨スキーマをできるだけ早く削除する必要があります。非推奨スキーマアイテムなしでスキーマに対するAPIコールを検証する必要があります。

非推奨の例

次のフィールドは、さまざまなマイナーリリースで非推奨になっていますが、GitLab 17.0で両方とも削除されます。

削除されたアイテムのリスト

以前のリリースで削除されたアイテムのリストを表示します。

制限

次の制限がGitLab GraphQL APIに適用されます。

最大クエリ複雑度

GitLab GraphQL APIは、クエリの複雑度にスコアを付けます。一般的に、クエリが大きいほど、複雑度のスコアが高くなります。この制限は、API全体のパフォーマンスに悪影響を与える可能性のあるクエリの実行からAPIを保護するように設計されています。

クエリの複雑度スコアとリクエストの制限をクエリできます。

クエリが複雑度の制限を超えると、エラーメッセージ応答が返されます。

一般的に、クエリ内の各フィールドは複雑度スコアに1を追加しますが、特定のフィールドの場合は、値がこれより高くなるか、低くなる可能性があります。また、特定の引数を追加すると、クエリの複雑度が増大する場合があります。

データ制限

Blobのリクエストは以下に制限されます:

• 任意のサイズの単一のblob。
• 合計サイズが20 MB以下の複数のblob。

20 MBを超えるblobは個別にリクエストする必要があります。この制限は、blobデータを含むフィールドをリクエストする場合にのみ適用されます。

データ制限内に収めるには、リクエスト内のパスの数を制限する必要がある場合があります。データフィールドを除外し、sizeフィールドにリクエストを行ってください:

{
  project(fullPath: "gitlab-org/gitlab") {
    repository {
      blobs(paths: ["big_file.rb", "small_file.rb", "huge_file.rb", ..., etc.], ref: "master") {
        nodes {
          path
          size
        }
      }
    }
  }
}

レスポンスを使用して合計サイズを計算し、後続のリクエストが20 MBのデータ制限を超えないことを確認してください。

スパムとして検出されたミューテーションを解決する

GraphQLミューテーションはスパムとして検出される可能性があります。ミューテーションがスパムとして検出されたときは、次のようになります。

• CAPTCHAサービスが設定されていない場合、GraphQLトップレベルエラーが発生します。例:

  {
    "errors": [
      {
        "message": "Request denied. Spam detected",
        "locations": [ { "line": 6, "column": 7 } ],
        "path": [ "updateSnippet" ],
        "extensions": {
          "spam": true
        }
      }
    ],
    "data": {
      "updateSnippet": {
        "snippet": null
      }
    }
  }

• CAPTCHAサービスが設定されている場合、次の内容の応答が返されます。

  • needsCaptchaResponseがtrueに設定されます。
  • spamLogIdフィールドとcaptchaSiteKeyフィールドが設定されます。

  例:

  {
    "errors": [
      {
        "message": "Request denied. Solve CAPTCHA challenge and retry",
        "locations": [ { "line": 6, "column": 7 } ],
        "path": [ "updateSnippet" ],
        "extensions": {
          "needsCaptchaResponse": true,
          "captchaSiteKey": "6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI",
          "spamLogId": 67
        }
      }
    ],
    "data": {
      "updateSnippet": {
        "snippet": null,
      }
    }
  }

• 適切なCAPTCHA APIを使用して、captchaSiteKeyでCAPTCHAの応答値を取得します。Google reCAPTCHA v2のみがサポートされています。

• X-GitLab-Captcha-ResponseヘッダーとX-GitLab-Spam-Log-Idヘッダーを設定して、リクエストを再送信します。

export CAPTCHA_RESPONSE="<CAPTCHA response obtained from CAPTCHA service>"
export SPAM_LOG_ID="<spam_log_id obtained from initial REST response>"
curl --request POST \
  --header "Authorization: Bearer $PRIVATE_TOKEN" \
  --header "Content-Type: application/json" \
  --header "X-GitLab-Captcha-Response: $CAPTCHA_RESPONSE" \
  --header "X-GitLab-Spam-Log-Id: $SPAM_LOG_ID" \
  --data-binary '{"query": "mutation {createSnippet(input: {title: \"Title\" visibilityLevel: public blobActions: [ { action: create filePath: \"BlobPath\" content: \"BlobContent\" } ] }) { snippet { id title } errors }}"}' "https://gitlab.example.com/api/graphql"