# Getting started with GitLab GraphQL API > 原文：[https://docs.gitlab.com/ee/api/graphql/getting_started.html](https://docs.gitlab.com/ee/api/graphql/getting_started.html) * [Running examples](#running-examples) * [Command line](#command-line) * [GraphiQL](#graphiql) * [Queries and mutations](#queries-and-mutations) * [Graph traversal](#graph-traversal) * [Authorization](#authorization) * [Mutations](#mutations) * [Creation mutations](#creation-mutations) * [Update mutations](#update-mutations) * [Deletion mutations](#deletion-mutations) * [Introspective queries](#introspective-queries) * [Sorting](#sorting) * [Pagination](#pagination) # Getting started with GitLab GraphQL API[](#getting-started-with-gitlab-graphql-api "Permalink") 本指南演示了 GitLab 的 GraphQL API 的基本用法. 請參見[GraphQL API 樣式指南，](../../development/api_graphql_styleguide.html)以了解針對希望開發 API 本身的開發人員的實現細節. ## Running examples[](#running-examples "Permalink") 此處記錄的示例可以使用以下命令運行： * 命令行. * GraphiQL. ### Command line[](#command-line "Permalink") 您可以在本地計算機上的命令行中的`curl`請求中運行 GraphQL 查詢. 可以將 GraphQL 請求作為對`/api/graphql`的`POST`請求，并將查詢作為有效負載. 您可以通過生成[個人訪問令牌](../../user/profile/personal_access_tokens.html)以用作承載令牌來授權您的請求. Example: ``` GRAPHQL_TOKEN=<your-token> curl 'https://gitlab.com/api/graphql' --header "Authorization: Bearer $GRAPHQL_TOKEN" --header "Content-Type: application/json" --request POST --data "{\"query\": \"query {currentUser {name}}\"}" ``` ### GraphiQL[](#graphiql "Permalink") GraphiQL（發音為"圖形"）允許您使用語法突出顯示和自動完成功能直接針對服務器端點運行查詢. 它還允許您探索模式和類型. 下面的例子： * 可以直接在 GitLab 11.0 或更高版本上運行，盡管某些類型和字段在較早的版本中可能不受支持. * 無需任何進一步設置即可在 GitLab.com 上運行. 確保您已登錄并導航到[GraphiQL Explorer](https://gitlab.com/-/graphql-explorer) . 如果要在本地或在自管實例上運行查詢，則需要執行以下任一操作： * 創建`gitlab-org`組，并在其下創建一個名為`graphql-sandbox`的項目. 在項目中創建多個問題. * 編輯查詢以將`gitlab-org/graphql-sandbox`替換為您自己的組和項目. 有關更多信息，請參考[運行 GraphiQL](index.html#graphiql) . **注意：**如果您正在運行 GitLab 11.0 到 12.0，請啟用`graphql` [功能標記](../features.html#set-or-create-a-feature) . ## Queries and mutations[](#queries-and-mutations "Permalink") GitLab GraphQL API 可用于執行： * 數據檢索查詢. * 用于創建，更新和刪除數據的[突變](#mutations) . **注意：**在 GitLab GraphQL API 中， `id`通常是指全局 ID，它是對象標識符，格式為`gid://gitlab/Issue/123` . [GitLab 的 GraphQL Schema](reference/index.html)概述了哪些對象和字段可供客戶端查詢以及它們對應的數據類型. 示例：在`gitlab-org`組中，僅獲取當前登錄用戶可以訪問的所有項目的名稱（最大限制，稍后再介紹）. ``` query { group(fullPath: "gitlab-org") { id name projects { nodes { name } } } } ``` 示例：獲得一個特定的項目和標題＃2. ``` query { project(fullPath: "gitlab-org/graphql-sandbox") { name issue(iid: "2") { title } } } ``` ### Graph traversal[](#graph-traversal "Permalink") 檢索子節點時，請使用： * the `edges { node { } }` syntax. * 縮寫形式`nodes { }`語法. 在它的下面是一個我們正在遍歷的圖，因此命名為 GraphQL. 示例：獲得一個項目（僅名稱）及其所有期刊的標題. ``` query { project(fullPath: "gitlab-org/graphql-sandbox") { name issues { nodes { title description } } } } ``` 有關查詢的更多信息： [GraphQL 文檔](https://s0graphql0org.icopy.site/learn/queries/) ### Authorization[](#authorization "Permalink") 授權使用與 GitLab 應用程序（和 GitLab.com）相同的引擎. 因此，如果您已經登錄到 GitLab 并使用 GraphiQL，則所有查詢都將以您（登錄用戶）的身份執行. 有關更多信息，請參見[GitLab API 文檔](../README.html#authentication) . ### Mutations[](#mutations "Permalink") 變異會改變數據. 我們可以更新，刪除或創建新記錄. 變異通常使用 InputTypes 和變量，在此都不會出現. 變異有： * 輸入. 例如，參數，例如您想要授予的表情符號以及對象. * 返回語句. 也就是說，成功后您希望獲得什么. * 錯誤. 總是問出什么問題了，以防萬一. #### Creation mutations[](#creation-mutations "Permalink") 示例：讓我們喝點茶-在問題中添加`:tea:`反應表情符號. ``` mutation { awardEmojiAdd(input: { awardableId: "gid://gitlab/Issue/27039960", name: "tea" }) { awardEmoji { name description unicode emoji unicodeVersion user { name } } errors } } ``` 示例：在問題上添加評論（我們使用的是`GitLab.com`問題的 ID，但是如果您使用的是本地實例，則需要獲取可以寫入的問題的 ID）. ``` mutation { createNote(input: { noteableId: "gid://gitlab/Issue/27039960", body: "*sips tea*" }) { note { id body discussion { id } } errors } } ``` #### Update mutations[](#update-mutations "Permalink") 當您看到創建的注釋的結果`id`時，請記下它. 現在，讓我們對其進行編輯以更快地 ip 飲！ ``` mutation { updateNote(input: { id: "gid://gitlab/Note/<note id>", body: "*SIPS TEA*" }) { note { id body } errors } } ``` #### Deletion mutations[](#deletion-mutations "Permalink") 讓我們刪除評論，因為我們的茶都沒了. ``` mutation { destroyNote(input: { id: "gid://gitlab/Note/<note id>" }) { note { id body } errors } } ``` 您應該得到類似以下輸出的內容： ``` { "data": { "destroyNote": { "errors": [], "note": null } } } ``` 我們已經要求提供注釋的詳細信息，但是它不再存在，因此我們得到`null` . 有關突變的更多信息： [GraphQL Docs](https://s0graphql0org.icopy.site/learn/queries/) . ### Introspective queries[](#introspective-queries "Permalink") 客戶端可以查詢 GraphQL 端點以獲取有關其自身架構的信息. 通過進行[內省性查詢](https://s0graphql0org.icopy.site/learn/introspection/) . 通過自省查詢， [GraphiQL 查詢資源管理器](https://gitlab.com/-/graphql-explorer)獲得了有關我們的 GraphQL 模式的所有知識，以執行自動補全并提供其交互式`Docs`選項卡. 示例：獲取架構中的所有類型名稱. ``` { __schema { types { name } } } ``` 示例：獲取與 Issue 相關的所有字段. `kind`告訴我們該類型的枚舉值，例如`OBJECT` ， `SCALAR`或`INTERFACE` . ``` query IssueTypes { __type(name: "Issue") { kind name fields { name description type { name } } } } ``` 有關自省的更多信息： [GraphQL 文檔](https://s0graphql0org.icopy.site/learn/introspection/) ## Sorting[](#sorting "Permalink") GitLab 的一些 GraphQL 端點允許您指定想要對對象集合進行排序的方式. 您只能按架構允許的排序. 示例：可以按創建日期對問題進行排序： ``` query { project(fullPath: "gitlab-org/graphql-sandbox") { name issues(sort: created_asc) { nodes { title createdAt } } } } ``` ## Pagination[](#pagination "Permalink") 分頁是僅詢問記錄子集（例如前 10 個）的一種方法. 如果我們想要更多，我們可以從服務器再次請求下 10 條記錄（例如"請給我下 10 條記錄"）. 默認情況下，GitLab 的 GraphQL API 將僅返回任何集合的前 100 條記錄. 可以使用`first`或`last`參數來更改. 這兩個參數都有一個值，因此`first: 10`將返回前 10 條記錄， `last: 10`將最后 10 條記錄. 示例：僅檢索前兩個問題（切片）. `cursor`字段為我們提供了一個位置，從中可以檢索相對于該位置的其他記錄. ``` query { project(fullPath: "gitlab-org/graphql-sandbox") { name issues(first: 2) { edges { node { title } } pageInfo { endCursor hasNextPage } } } } ``` 示例：檢索下一個 3.（游標值`eyJpZCI6IjI3MDM4OTMzIiwiY3JlYXRlZF9hdCI6IjIwMTktMTEtMTQgMDU6NTY6NDQgVVRDIn0`可能有所不同，但它是上面返回的第二個問題返回的`cursor`值.） ``` query { project(fullPath: "gitlab-org/graphql-sandbox") { name issues(first: 3, after: "eyJpZCI6IjI3MDM4OTMzIiwiY3JlYXRlZF9hdCI6IjIwMTktMTEtMTQgMDU6NTY6NDQgVVRDIn0") { edges { node { title } cursor } pageInfo { endCursor hasNextPage } } } } ``` 有關分頁和游標的更多信息： [GraphQL 文檔](https://s0graphql0org.icopy.site/learn/pagination/)