Skip to main content

Usar a API do GraphQL para discussões

Aprenda a usar a API do GraphQL de GitHub Discussions.

A API do GraphQL do GitHub Discussions permite que você obtenha, crie, edite e exclua publicações de discussão. Para mais informações sobre GitHub Discussions, confira Sobre discussões.

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.

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:

discussions(
  after: String,
  before: String,
  first: Int,
  last: Int,
  categoryId: ID = null,
  
  answered: Boolean = null,
  
  orderBy: DiscussionOrder = {field: UPDATED_AT, direction: DESC}
) : Discussion

DiscussionOrder

"""
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!
}
"""
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 Sobre discussões.

Assinatura:

discussionCategories(
  after: String,
  before: String,
  first: Int,
  last: Int,
) : DiscussionCategoryConnection!

Repository.discussion

Obtenha uma discussão. Retornará null se a discussão com a ID especificada não existir.

Assinatura:

discussion(number: Int!) : Discussion

Repository.pinnedDiscussions

Discussões de retorno fixadas a este repositório, ordenada pela posição do da marcação.

Assinatura:

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.

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:
"""
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
"""
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!
}

DiscussionCategory

Campos
"""
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:
"""
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!
}

PinnedDiscussionPattern

Valores
"""
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
"""
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

RepositoryDiscussionAuthor

Implementado pelos tipos User e Organization. Observação: uma Organization só terá discussões associadas se tiver sido convertida de um User.

Campos
"""
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!
}

RepositoryDiscussionCommentAuthor

Também implementado pelos tipos User e Organization.

Campos
"""
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:

mutation {
  # input type: CreateDiscussionInput
  createDiscussion(input: {repositoryId: "1234", categoryId: "5678", body: "The body", title: "The title"}) {

    # response type: CreateDiscussionPayload
    discussion {
      id
    }
  }
}

createDiscussion

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! A ID de uma DiscussionCategory nesse 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 uma entrada.
  • discussion: Discussion A discussão que foi criada.

updateDiscussion

Campos de entrada:

  • discussionId: ID! A ID de nó da discussão a ser atualizada.
  • body: String O novo conteúdo do corpo da 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 uma entrada.
  • discussion: Discussion A discussão que foi modificada.

deleteDiscussion

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 uma 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 uma entrada.
  • comment: DiscussionComment O comentário da discussão que foi criado.

updateDiscussionComment

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 uma 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 uma entrada.
  • comment: DiscussionComment O comentário da discussão que foi excluído.

markDiscussionCommentAsAnswer

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 uma entrada.
  • discussion: Discussion A discussão que inclui o comentário escolhido.

unmarkDiscussionCommentAsAnswer

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 uma entrada.
  • discussion: Discussion A discussão que inclui o comentário não marcado.

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 Consultas e Pesquisar discussões.