# Usar a API do GraphQL para discussões
Saiba como usar a API do GitHub Discussions GraphQL.
A GitHub Discussions API do GraphQL permite que você obtenha, crie, edite e exclua postagens de discussão. Para obter mais informações sobre GitHub Discussions, confira [Sobre discussões](/pt/enterprise-server@3.22/discussions/collaborating-with-your-community-using-discussions/about-discussions).
Essa API está disponível para usuários autenticados, OAuth apps e aplicativos GitHub. Os tokens de acesso exigem o escopo `repo` para repositórios privados e o escopo `public_repo` para repositórios públicos. Para saber mais, confira [Escopos para aplicativos OAuth](/pt/enterprise-server@3.22/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps).
## Campos
### Repository.discussions
Liste as discussões dentro de um repositório. Se `categoryId` for especificado, somente os resultados nessa categoria serão retornados. Se `answered` não for especificado, as discussões respondidas e não respondidas serão retornadas.
*Assinatura:*
```graphql
discussions(
after: String,
before: String,
first: Int,
last: Int,
categoryId: ID = null,
answered: Boolean = null,
orderBy: DiscussionOrder = {field: UPDATED_AT, direction: DESC}
) : Discussion
```
#### Ordem de Discussão
```graphql
"""
Ways in which discussions can be ordered.
"""
input DiscussionOrder {
"""
The field by which to order discussions.
"""
field: DiscussionOrderField!
"""
The direction in which to order discussions by the specified field.
"""
direction: OrderDirection!
}
```
```graphql
"""
Properties by which discussion connections can be ordered.
"""
enum DiscussionOrderField {
"""
Order discussions by creation time.
"""
CREATED_AT
"""
Order discussions by most recent modification time.
"""
UPDATED_AT
}
```
### Repository.discussionCategories
Retorna as categorias de discussão disponíveis definidas neste repositório. Cada repositório pode ter até 25 categorias. Para obter mais informações sobre as categorias de discussões, confira [Gerenciar categorias para discussões](/pt/enterprise-server@3.22/discussions/managing-discussions-for-your-community/managing-categories-for-discussions#about-categories-for-discussions).
*Assinatura:*
```graphql
discussionCategories(
after: String,
before: String,
first: Int,
last: Int,
) : DiscussionCategoryConnection!
```
### Repository.discussion
Participe de uma discussão Retornará `null` se a discussão com a ID especificada não existir.
*Assinatura:*
```graphql
discussion(number: Int!) : Discussion
```
### Repository.pinnedDiscussions
Discussões de retorno fixadas a este repositório, ordenada pela posição do da marcação.
*Assinatura:*
```graphql
pinnedDiscussions(
after: String,
before: String,
first: Int,
last: Int,
) : PinnedDiscussionConnection!
```
## Objetos
**Observação:** para simplificar, os tipos de conexão não são expandidos aqui. Cada tipo de conexão mencionada no esquema segue o mesmo padrão que outras conexões na API do GraphQL. Para saber mais, confira [Introdução ao GraphQL](/pt/enterprise-server@3.22/graphql/guides/introduction-to-graphql#connection).
```graphql
query {
repository(owner: "github", name: "some-repo") {
discussions(first: 10) {
# type: DiscussionConnection
totalCount # Int!
pageInfo {
# type: PageInfo (from the public schema)
startCursor
endCursor
hasNextPage
hasPreviousPage
}
edges {
# type: DiscussionEdge
cursor
node {
# type: Discussion
id
}
}
nodes {
# type: Discussion
id
}
}
}
}
```
### Discussão
Campos:
```graphql
"""
A discussion in a repository.
"""
type Discussion implements Comment & Deletable & Lockable & Node & Reactable & RepositoryNode & Subscribable & Updatable {
"""
Reason that the conversation was locked.
"""
activeLockReason: LockReason
"""
Check if this discussion has been answered
"""
isAnswered: Boolean!
"""
The comment chosen as this discussion's answer, if any.
"""
answer: DiscussionComment
"""
The time when a user chose this discussion's answer, if answered.
"""
answerChosenAt: DateTime
"""
The user who chose this discussion's answer, if answered.
"""
answerChosenBy: Actor
"""
The actor who authored the comment.
"""
author: Actor
"""
Author's association with the subject of the comment.
"""
authorAssociation: CommentAuthorAssociation!
"""
The main text of the discussion post.
"""
body: String!
"""
The body rendered to HTML.
"""
bodyHTML: HTML!
"""
The body rendered to text.
"""
bodyText: String!
"""
The category for this discussion.
"""
category: DiscussionCategory!
"""
The replies to the discussion.
"""
comments(
"""
Returns the elements in the list that come after the specified cursor.
"""
after: String
"""
Returns the elements in the list that come before the specified cursor.
"""
before: String
"""
Returns the first _n_ elements from the list.
"""
first: Int
"""
Returns the last _n_ elements from the list.
"""
last: Int
): DiscussionCommentConnection!
"""
Identifies the date and time when the object was created.
"""
createdAt: DateTime!
"""
Check if this comment was created via an email reply.
"""
createdViaEmail: Boolean!
"""
Identifies the primary key from the database.
"""
databaseId: Int
"""
The actor who edited the comment.
"""
editor: Actor
id: ID!
"""
Check if this comment was edited and includes an edit with the creation data
"""
includesCreatedEdit: Boolean!
"""
The moment the editor made the last edit
"""
lastEditedAt: DateTime
"""
`true` if the object is locked
"""
locked: Boolean!
"""
The number identifying this discussion within the repository.
"""
number: Int!
"""
Identifies when the comment was published at.
"""
publishedAt: DateTime
"""
A list of reactions grouped by content left on the subject.
"""
reactionGroups: [ReactionGroup!]
"""
A list of Reactions left on the Issue.
"""
reactions(
"""
Returns the elements in the list that come after the specified cursor.
"""
after: String
"""
Returns the elements in the list that come before the specified cursor.
"""
before: String
"""
Allows filtering Reactions by emoji.
"""
content: ReactionContent
"""
Returns the first _n_ elements from the list.
"""
first: Int
"""
Returns the last _n_ elements from the list.
"""
last: Int
"""
Allows specifying the order in which reactions are returned.
"""
orderBy: ReactionOrder
): ReactionConnection!
"""
The repository associated with this node.
"""
repository: Repository!
"""
The path for this discussion.
"""
resourcePath: URI!
"""
The title of this discussion.
"""
title: String!
"""
Identifies the date and time when the object was last updated.
"""
updatedAt: DateTime!
"""
The URL for this discussion.
"""
url: URI!
"""
A list of edits to this content.
"""
userContentEdits(
"""
Returns the elements in the list that come after the specified cursor.
"""
after: String
"""
Returns the elements in the list that come before the specified cursor.
"""
before: String
"""
Returns the first _n_ elements from the list.
"""
first: Int
"""
Returns the last _n_ elements from the list.
"""
last: Int
): UserContentEditConnection
"""
Check if the current viewer can delete this object.
"""
viewerCanDelete: Boolean!
"""
Can user react to this subject
"""
viewerCanReact: Boolean!
"""
Check if the viewer is able to change their subscription status for the repository.
"""
viewerCanSubscribe: Boolean!
"""
Check if the current viewer can update this object.
"""
viewerCanUpdate: Boolean!
"""
Did the viewer author this comment.
"""
viewerDidAuthor: Boolean!
"""
Identifies if the viewer is watching, not watching, or ignoring the subscribable entity.
"""
viewerSubscription: SubscriptionState
}
```
### DiscussionComment
Campos
```graphql
"""
A comment on a discussion.
"""
type DiscussionComment implements Comment & Deletable & Minimizable & Node & Reactable & Updatable & UpdatableComment {
"""
The actor who authored the comment.
"""
author: Actor
"""
Author's association with the subject of the comment.
"""
authorAssociation: CommentAuthorAssociation!
"""
The body as Markdown.
"""
body: String!
"""
The body rendered to HTML.
"""
bodyHTML: HTML!
"""
The body rendered to text.
"""
bodyText: String!
"""
Identifies the date and time when the object was created.
"""
createdAt: DateTime!
"""
Check if this comment was created via an email reply.
"""
createdViaEmail: Boolean!
"""
Identifies the primary key from the database.
"""
databaseId: Int
"""
The time when this replied-to comment was deleted
"""
deletedAt: DateTime
"""
The discussion this comment was created in
"""
discussion: Discussion
"""
The actor who edited the comment.
"""
editor: Actor
id: ID!
"""
Check if this comment was edited and includes an edit with the creation data
"""
includesCreatedEdit: Boolean!
"""
Has this comment been chosen as the answer of its discussion?
"""
isAnswer: Boolean!
"""
Returns whether or not a comment has been minimized.
"""
isMinimized: Boolean!
"""
The moment the editor made the last edit
"""
lastEditedAt: DateTime
"""
Returns why the comment was minimized.
"""
minimizedReason: String
"""
Identifies when the comment was published at.
"""
publishedAt: DateTime
"""
A list of reactions grouped by content left on the subject.
"""
reactionGroups: [ReactionGroup!]
"""
A list of Reactions left on the Issue.
"""
reactions(
"""
Returns the elements in the list that come after the specified cursor.
"""
after: String
"""
Returns the elements in the list that come before the specified cursor.
"""
before: String
"""
Allows filtering Reactions by emoji.
"""
content: ReactionContent
"""
Returns the first _n_ elements from the list.
"""
first: Int
"""
Returns the last _n_ elements from the list.
"""
last: Int
"""
Allows specifying the order in which reactions are returned.
"""
orderBy: ReactionOrder
): ReactionConnection!
"""
The threaded replies to this comment.
"""
replies(
"""
Returns the elements in the list that come after the specified cursor.
"""
after: String
"""
Returns the elements in the list that come before the specified cursor.
"""
before: String
"""
Returns the first _n_ elements from the list.
"""
first: Int
"""
Returns the last _n_ elements from the list.
"""
last: Int
): DiscussionCommentConnection!
"""
The discussion comment this comment is a reply to
"""
replyTo: DiscussionComment
"""
The path for this discussion comment.
"""
resourcePath: URI!
"""
Identifies the date and time when the object was last updated.
"""
updatedAt: DateTime!
"""
The URL for this discussion comment.
"""
url: URI!
"""
A list of edits to this content.
"""
userContentEdits(
"""
Returns the elements in the list that come after the specified cursor.
"""
after: String
"""
Returns the elements in the list that come before the specified cursor.
"""
before: String
"""
Returns the first _n_ elements from the list.
"""
first: Int
"""
Returns the last _n_ elements from the list.
"""
last: Int
): UserContentEditConnection
"""
Check if the current viewer can delete this object.
"""
viewerCanDelete: Boolean!
"""
Can the current user mark this comment as an answer?
"""
viewerCanMarkAsAnswer: Boolean!
"""
Check if the current viewer can minimize this object.
"""
viewerCanMinimize: Boolean!
"""
Can user react to this subject
"""
viewerCanReact: Boolean!
"""
Can the current user unmark this comment as an answer?
"""
viewerCanUnmarkAsAnswer: Boolean!
"""
Check if the current viewer can update this object.
"""
viewerCanUpdate: Boolean!
"""
Reasons why the current viewer can not update this comment.
"""
viewerCannotUpdateReasons: [CommentCannotUpdateReason!]!
"""
Did the viewer author this comment.
"""
viewerDidAuthor: Boolean!
}
```
### Categoria de Discussão
Campos
```graphql
"""
A category for discussions in a repository.
"""
type DiscussionCategory implements Node & RepositoryNode {
"""
Identifies the date and time when the object was created.
"""
createdAt: DateTime!
"""
A description of this category.
"""
description: String
"""
An emoji representing this category.
"""
emoji: String!
"""
This category's emoji rendered as HTML.
"""
emojiHTML: HTML!
id: ID!
"""
Whether or not discussions in this category support choosing an answer with the markDiscussionCommentAsAnswer mutation.
"""
isAnswerable: Boolean!
"""
The name of this category.
"""
name: String!
"""
The repository associated with this node.
"""
repository: Repository!
"""
Identifies the date and time when the object was last updated.
"""
updatedAt: DateTime!
}
```
### PinnedDiscussion
Campos:
```graphql
"""
A Pinned discussion is a discussion pinned to a repository's index page.
"""
type PinnedDiscussion implements Node & RepositoryNode {
"""
Identifies the date and time when the object was created.
"""
createdAt: DateTime!
"""
Identifies the primary key from the database.
"""
databaseId: Int
"""
The discussion that was pinned.
"""
discussion: Discussion!
"""
Color stops of the chosen gradient
"""
gradientStopColors: [String!]!
id: ID!
"""
Background texture pattern
"""
pattern: PinnedDiscussionPattern!
"""
The actor that pinned this discussion.
"""
pinnedBy: Actor!
"""
Preconfigured background gradient option
"""
preconfiguredGradient: PinnedDiscussionGradient
"""
The repository associated with this node.
"""
repository: Repository!
"""
Identifies the date and time when the object was last updated.
"""
updatedAt: DateTime!
}
```
#### PadrãoDeDiscussãoFixada
Valores
```graphql
"""
Preconfigured background patterns that may be used to style discussions pinned within a repository.
"""
enum PinnedDiscussionPattern {
"""
An upward-facing chevron pattern
"""
CHEVRON_UP
"""
A hollow dot pattern
"""
DOT
"""
A solid dot pattern
"""
DOT_FILL
"""
A heart pattern
"""
HEART_FILL
"""
A friendly octocat face pattern
"""
OCTOFACE
"""
A plus sign pattern
"""
PLUS
}
```
#### PinnedDiscussionGradient
Valores
```graphql
"""
Preconfigured gradients that may be used to style discussions pinned within a repository.
"""
enum PinnedDiscussionGradient {
"""
A gradient of blue to mint
"""
BLUE_MINT
"""
A gradient of blue to purple
"""
BLUE_PURPLE
"""
A gradient of pink to blue
"""
PINK_BLUE
"""
A gradient of purple to coral
"""
PURPLE_CORAL
"""
A gradient of red to orange
"""
RED_ORANGE
}
```
## Interfaces
### AutorDaDiscussãoDoRepositório
Implementado pelos tipos `User` e `Organization`.
**Observação:** uma `Organization` só terá discussões associadas se tiver sido convertida de um `User`.
Campos
```graphql
"""
Represents an author of discussions in repositories.
"""
interface RepositoryDiscussionAuthor {
"""
Discussions this user has started.
"""
repositoryDiscussions(
"""
Returns the elements in the list that come after the specified cursor.
"""
after: String
"""
Filter discussions to only those that have been answered or not. Defaults to
including both answered and unanswered discussions.
"""
answered: Boolean = null
"""
Returns the elements in the list that come before the specified cursor.
"""
before: String
"""
Returns the first _n_ elements from the list.
"""
first: Int
"""
Returns the last _n_ elements from the list.
"""
last: Int
"""
Ordering options for discussions returned from the connection.
"""
orderBy: DiscussionOrder = {field: CREATED_AT, direction: DESC}
"""
Filter discussions to only those in a specific repository.
"""
repositoryId: ID
): DiscussionConnection!
}
```
### AutorDoComentárioDaDiscussãoDoRepositório
Também implementado pelos tipos `User` e `Organization`.
Campos
```graphql
"""
Represents an author of discussion comments in repositories.
"""
interface RepositoryDiscussionCommentAuthor {
"""
Discussion comments this user has authored.
"""
repositoryDiscussionComments(
"""
Returns the elements in the list that come after the specified cursor.
"""
after: String
"""
Returns the elements in the list that come before the specified cursor.
"""
before: String
"""
Returns the first _n_ elements from the list.
"""
first: Int
"""
Returns the last _n_ elements from the list.
"""
last: Int
"""
Filter discussion comments to only those that were marked as the answer
"""
onlyAnswers: Boolean = false
"""
Filter discussion comments to only those in a specific repository.
"""
repositoryId: ID
): DiscussionCommentConnection!
}
```
## Mutações
Essas mutações seguem o mesmo padrão de implementação das outras mutações na API do GraphQL. Cada mutação aceita um só argumento de um tipo `Input`, nomeado com base na mutação, e retorna um tipo `Payload` que contém os campos especificados.
Por exemplo, essa é uma mutação `createDiscussion` básica que criará uma discussão:
```graphql
mutation {
# input type: CreateDiscussionInput
createDiscussion(input: {repositoryId: "1234", categoryId: "5678", body: "The body", title: "The title"}) {
# response type: CreateDiscussionPayload
discussion {
id
}
}
}
```
### criarDiscussão
Campos de entrada:
* `body: String!` O corpo da nova discussão.
* `title: String!` O título da nova discussão.
* `repositoryId: ID!` A ID de um repositório no qual a discussão será criada.
* `categoryId: ID!` O ID de um `DiscussionCategory` neste repositório.
* `clientMutationId: String` Um identificador exclusivo para o cliente que realiza a mutação.
Campos de tipo de retorno:
* `clientMutationId: String` O identificador exclusivo fornecido como entrada.
* `discussion: Discussion` A discussão que foi gerada.
### atualizarDiscussão
Campos de entrada:
* `discussionId: ID!` A ID de nó da discussão a ser atualizada.
* `body: String` O novo conteúdo da seção de discussão.
* `title: String` O novo título da discussão.
* `categoryId: ID` A ID de nó de uma `DiscussionCategory` no mesmo repositório para o qual essa discussão será alterada.
* `clientMutationId: String` Um identificador exclusivo para o cliente que realiza a mutação.
Campos de tipo de retorno:
* `clientMutationId: String` O identificador exclusivo fornecido como entrada.
* `discussion: Discussion` A discussão que foi modificada.
### excluirDiscussão
Campos de entrada:
* `id: ID!` A ID de nó da discussão a ser excluída.
* `clientMutationId: String` Um identificador exclusivo para o cliente que realiza a mutação.
Campos de tipo de retorno:
* `clientMutationId: String` O identificador exclusivo fornecido como entrada.
* `discussion: Discussion` A discussão que foi excluída.
### addDiscussionComment
Campos de entrada:
* `body: String!` O conteúdo do comentário.
* `discussionId: ID!` A ID de nó da discussão sobre a qual será feito um comentário.
* `replyToId: ID` A ID de nó do comentário da discussão que será respondido. Se ausente, o comentário criado será um comentário de nível superior.
* `clientMutationId: String` Um identificador exclusivo para o cliente que realiza a mutação.
Campos de tipo de retorno:
* `clientMutationId: String` O identificador exclusivo fornecido como entrada.
* `comment: DiscussionComment` O comentário da discussão que foi criado.
### atualizarComentárioDiscussão
Campos de entrada:
* `body: String!` O novo conteúdo do corpo do comentário.
* `commentId: ID!` A ID de nó do comentário da discussão a ser atualizado.
* `clientMutationId: String` Um identificador exclusivo para o cliente que realiza a mutação.
Campos de tipo de retorno:
* `clientMutationId: String` O identificador exclusivo fornecido como entrada.
* `comment: DiscussionComment` O comentário da discussão que foi atualizado.
### deleteDiscussionComment
Campos de entrada:
* `id: ID!` A ID de nó do comentário da discussão a ser excluído.
* `clientMutationId: String` Um identificador exclusivo para o cliente que realiza a mutação.
Campos de tipo de retorno:
* `clientMutationId: String` O identificador exclusivo fornecido como entrada.
* `comment: DiscussionComment` O comentário da discussão que foi excluído.
### marcarComentárioDaDiscussãoComoResposta
Campos de entrada:
* `id: ID!` A ID de nó do comentário da discussão a ser marcado como uma resposta.
* `clientMutationId: String` Um identificador exclusivo para o cliente que realiza a mutação.
Campos de tipo de retorno:
* `clientMutationId: String` O identificador exclusivo fornecido como entrada.
* `discussion: Discussion` A discussão que inclui o comentário escolhido.
### desmarcarComentarioDeDiscussaoComoResposta
Campos de entrada:
* `id: ID!` A ID de nó do comentário da discussão a ser desmarcado como uma resposta.
* `clientMutationId: String` Um identificador exclusivo para o cliente que realiza a mutação.
Campos de tipo de retorno:
* `clientMutationId: String` O identificador exclusivo fornecido como entrada.
* `discussion: Discussion` A discussão que inclui o comentário não marcado.
## Pesquisa
A discussão pode ser retornada do campo `search` de nível superior. Para pesquisar uma discussão, especifique `type` como `DISCUSSION`. O tipo `SearchResultItemConnection` tem um campo `discussionCount` para relatar o número de discussões retornadas, e o tipo `Discussion` é adicionado à união `SearchResultItem`. Para saber mais, confira [Pesquisa](/pt/enterprise-server@3.22/graphql/reference/search#query-searchresultitemconnection) e [Pesquisar discussões](/pt/enterprise-server@3.22/search-github/searching-on-github/searching-discussions).