Formbricks GraphQL API：查询调查数据教程-优快云博客

Formbricks GraphQL API：查询调查数据教程

【免费下载链接】formbricks Open Source Survey Toolbox 项目地址: https://gitcode.com/GitHub_Trending/fo/formbricks

引言：为什么选择GraphQL查询调查数据？

你是否还在为整合多个REST API端点获取完整调查数据而烦恼？是否在面对复杂的嵌套数据结构时感到力不从心？本文将带你探索如何利用Formbricks GraphQL API高效查询调查数据，一次请求获取所有所需信息，显著提升数据获取效率。

读完本文后，你将能够：

理解Formbricks GraphQL API的核心优势
掌握GraphQL查询的基本语法和高级技巧
构建复杂的嵌套查询获取调查数据
处理和优化GraphQL查询性能
实现常见的调查数据分析场景

Formbricks GraphQL API概述

GraphQL vs REST：核心差异对比

特性	GraphQL	REST
请求数量	单次请求获取所有数据	多次请求不同端点
数据结构	按需定制返回结构	固定结构
版本控制	无需版本控制	通常需要（如v1, v2）
类型系统	强类型，自文档化	松散类型，依赖外部文档
缓存机制	需额外实现	内置HTTP缓存
学习曲线	较陡峭	较平缓

Formbricks GraphQL API架构

mermaid

Formbricks GraphQL API采用分层架构，主要包含以下组件：

API网关：处理认证、请求验证和路由
GraphQL解析器：解析查询并获取所需数据
数据服务层：实现业务逻辑和数据访问
数据库：存储所有调查相关数据

快速开始：首次查询

API端点与认证

Formbricks GraphQL API的主要端点为：

https://api.formbricks.com/graphql

认证方式采用Bearer Token，在请求头中添加：

Authorization: Bearer YOUR_API_KEY

获取API密钥：登录Formbricks账户，进入设置 > API集成 > 创建新API密钥，选择"读取调查数据"权限。

第一个查询：获取调查列表

query GetSurveys {
  surveys {
    id
    name
    description
    status
    createdAt
    updatedAt
    questionCount
  }
}

响应示例：

{
  "data": {
    "surveys": [
      {
        "id": "surv_123456",
        "name": "用户满意度调查",
        "description": "评估用户对我们产品的满意度",
        "status": "PUBLISHED",
        "createdAt": "2025-08-15T10:30:00Z",
        "updatedAt": "2025-08-16T14:20:00Z",
        "questionCount": 8
      },
      {
        "id": "surv_789012",
        "name": "功能使用频率调查",
        "description": "了解用户使用各功能的频率",
        "status": "DRAFT",
        "createdAt": "2025-08-20T09:15:00Z",
        "updatedAt": "2025-08-20T09:15:00Z",
        "questionCount": 5
      }
    ]
  }
}

核心查询操作

获取单个调查详情

query GetSurveyDetails($surveyId: ID!) {
  survey(id: $surveyId) {
    id
    name
    description
    status
    createdAt
    updatedAt
    questions {
      id
      text
      type
      options {
        id
        text
        value
      }
      required
      position
    }
    audience {
      totalCount
      completedCount
      responseRate
    }
  }
}

变量：

{
  "surveyId": "surv_123456"
}

查询调查响应数据

query GetSurveyResponses($surveyId: ID!, $limit: Int = 10, $offset: Int = 0) {
  surveyResponses(surveyId: $surveyId, limit: $limit, offset: $offset) {
    totalCount
    responses {
      id
      personId
      completed
      startedAt
      completedAt
      answers {
        questionId
        questionText
        value
        selectedOptions {
          id
          text
        }
      }
      metadata {
        userAgent
        ipAddress
        deviceType
        browser
        operatingSystem
      }
    }
  }
}

高级过滤与排序

query FilteredSurveys {
  surveys(
    filter: {
      status: PUBLISHED
      createdAt: { greaterThan: "2025-01-01T00:00:00Z" }
      questionCount: { greaterThan: 5 }
    }
    sort: { field: CREATED_AT, direction: DESC }
    limit: 20
  ) {
    id
    name
    createdAt
    questionCount
    responseCount
  }
}

高级查询技巧

嵌套查询与片段

fragment QuestionDetails on Question {
  id
  text
  type
  required
  position
}

fragment AnswerDetails on Answer {
  questionId
  questionText
  value
  selectedOptions {
    id
    text
  }
}

query GetSurveyWithResponses($surveyId: ID!) {
  survey(id: $surveyId) {
    id
    name
    questions {
      ...QuestionDetails
    }
    responses(limit: 5) {
      id
      personId
      completedAt
      answers {
        ...AnswerDetails
      }
    }
  }
}

条件查询与别名

query SurveyAnalytics($surveyId: ID!) {
  publishedSurvey: survey(id: $surveyId) {
    id
    name
    status
    responseRate
    averageCompletionTime
  }
  
  draftSurveys: surveys(filter: { status: DRAFT }) {
    id
    name
    createdAt
  }
}

聚合查询与统计数据

query SurveyStatistics($surveyId: ID!) {
  surveyStatistics(surveyId: $surveyId) {
    totalResponses
    completedResponses
    incompleteResponses
    averageTimeToComplete
    responseRate
    completionRate
    questionStatistics {
      questionId
      questionText
      responseCount
      skipRate
      averageResponseTime
    }
  }
}

常见查询场景

场景一：获取调查结果摘要

query SurveyResultsSummary($surveyId: ID!) {
  survey(id: $surveyId) {
    id
    name
    questions {
      id
      text
      type
      options {
        id
        text
        responseCount
        percentage
      }
      averageRating # 适用于评分类型问题
      textResponses(limit: 5) { # 适用于文本类型问题
        id
        value
        createdAt
      }
    }
  }
}

场景二：用户响应追踪

query PersonSurveyResponses($personId: ID!) {
  person(id: $personId) {
    id
    name
    email
    surveys {
      id
      name
      status
      response {
        id
        completed
        startedAt
        completedAt
        answers {
          questionId
          questionText
          value
        }
      }
    }
  }
}

场景三：时间序列分析

query ResponseTimeSeries($surveyId: ID!) {
  responseTimeSeries(surveyId: $surveyId, interval: DAILY) {
    date
    newResponses
    completedResponses
    cumulativeResponses
  }
}

响应示例：

{
  "data": {
    "responseTimeSeries": [
      {
        "date": "2025-08-01",
        "newResponses": 15,
        "completedResponses": 12,
        "cumulativeResponses": 12
      },
      {
        "date": "2025-08-02",
        "newResponses": 28,
        "completedResponses": 25,
        "cumulativeResponses": 37
      },
      // 更多日期数据...
    ]
  }
}

查询性能优化

分页策略

Formbricks GraphQL API支持两种分页方式：

偏移分页（适用于小型数据集）：

query PaginatedResponses($surveyId: ID!, $limit: Int!, $offset: Int!) {
  surveyResponses(surveyId: $surveyId, limit: $limit, offset: $offset) {
    totalCount
    responses {
      id
      personId
      completedAt
    }
  }
}

游标分页（适用于大型数据集）：

query CursorPaginatedResponses($surveyId: ID!, $first: Int!, $after: String) {
  surveyResponses(surveyId: $surveyId, first: $first, after: $after) {
    pageInfo {
      hasNextPage
      endCursor
    }
    edges {
      cursor
      node {
        id
        personId
        completedAt
      }
    }
  }
}

查询复杂度与深度限制

Formbricks GraphQL API实施查询复杂度限制，默认最大复杂度为1000，深度限制为10级。可以通过以下方式优化复杂查询：

拆分大型查询为多个小型查询
使用片段复用常用字段集
限制嵌套深度，避免过深的嵌套查询
指定确切字段，避免请求不必要的数据

缓存策略

mermaid

推荐的缓存策略：

使用Apollo Client等客户端库自动管理缓存
为频繁查询添加cacheControl指令
实现基于实体ID的规范化缓存

错误处理与调试

常见错误类型及解决方案

错误类型	错误信息示例	解决方案
认证错误	"未授权访问"	检查API密钥是否有效，权限是否正确
格式错误	"语法错误在位置123"	验证GraphQL语法，使用GraphQL Playground调试
字段不存在	"无法查询字段'xyz'在类型'Survey'"	检查字段名称是否正确，参考API文档
速率限制	"已超出速率限制"	实现请求限流，或联系支持提升限制
复杂度超限	"查询复杂度超出限制"	简化查询，减少请求字段或嵌套深度

使用GraphQL Playground

Formbricks提供交互式GraphQL Playground：

https://api.formbricks.com/graphql/playground

主要功能：

交互式查询编辑和执行
自动补全和语法高亮
文档浏览和类型检查
查询历史记录
响应格式化和分析

最佳实践与性能优化

查询设计原则

只请求需要的字段：避免使用... on获取所有字段
使用变量：而非硬编码值，提高复用性和安全性
分页处理：避免一次请求过多数据
监控查询性能：使用@debug指令分析慢查询
批量请求：合并多个相关查询，减少网络往返

代码示例：使用Apollo Client集成

import { ApolloClient, InMemoryCache, gql } from '@apollo/client';

// 初始化Apollo客户端
const client = new ApolloClient({
  uri: 'https://api.formbricks.com/graphql',
  cache: new InMemoryCache(),
  headers: {
    authorization: `Bearer ${process.env.FORMBRICKS_API_KEY}`,
  },
});

// 定义查询
const GET_SURVEY_RESULTS = gql`
  query GetSurveyResults($surveyId: ID!) {
    survey(id: $surveyId) {
      id
      name
      questions {
        id
        text
        type
        options {
          id
          text
          responseCount
          percentage
        }
      }
    }
  }
`;

// 执行查询
async function fetchSurveyResults(surveyId) {
  try {
    const result = await client.query({
      query: GET_SURVEY_RESULTS,
      variables: { surveyId },
    });
    return result.data.survey;
  } catch (error) {
    console.error('Error fetching survey results:', error);
    throw error;
  }
}

性能优化清单

使用精确字段选择，避免过度请求
实现分页加载大型数据集
添加适当的缓存策略
监控和优化慢查询
避免N+1查询问题
使用批量操作处理多个实体

高级应用：数据可视化集成

示例：使用Chart.js可视化调查结果

<!DOCTYPE html>
<html>
<head>
    <title>Formbricks调查结果可视化</title>
    <script src="https://cdn.jsdelivr.net/npm/chart.js@4.4.8/dist/chart.umd.min.js"></script>
    <script src="https://cdn.jsdelivr.net/npm/@apollo/client@3.10.4/dist/main.umd.min.js"></script>
</head>
<body>
    <canvas id="surveyChart" width="400" height="400"></canvas>
    
    <script>
        // 初始化Apollo客户端
        const client = new ApolloClient({
            uri: 'https://api.formbricks.com/graphql',
            cache: new InMemoryCache(),
            headers: {
                authorization: `Bearer YOUR_API_KEY`,
            },
        });
        
        // GraphQL查询
        const GET_SURVEY_DATA = gql`
            query GetSurveyData($surveyId: ID!) {
                survey(id: $surveyId) {
                    id
                    name
                    questions {
                        id
                        text
                        options {
                            id
                            text
                            responseCount
                        }
                    }
                }
            }
        `;
        
        // 获取并可视化数据
        client.query({
            query: GET_SURVEY_DATA,
            variables: { surveyId: 'surv_123456' }
        }).then(result => {
            const survey = result.data.survey;
            const firstQuestion = survey.questions[0];
            
            // 准备图表数据
            const labels = firstQuestion.options.map(option => option.text);
            const data = firstQuestion.options.map(option => option.responseCount);
            
            // 创建图表
            new Chart(
                document.getElementById('surveyChart'),
                {
                    type: 'bar',
                    data: {
                        labels: labels,
                        datasets: [{
                            label: firstQuestion.text,
                            data: data,
                            backgroundColor: 'rgba(54, 162, 235, 0.5)'
                        }]
                    }
                }
            );
        });
    </script>
</body>
</html>

总结与展望

核心知识点回顾

Formbricks GraphQL API提供了灵活的数据查询能力，支持按需获取调查数据
基本查询结构包括查询名称、变量、字段和片段
认证使用Bearer Token，需正确配置API密钥和权限
常见查询场景包括调查列表、详情、结果统计和用户响应
性能优化关键在于合理设计查询、实现分页和使用缓存

高级功能预告

Formbricks团队正在开发以下GraphQL API高级功能：

实时订阅（使用WebSocket）获取调查响应更新
批量操作API，支持同时更新多个实体
自定义报告生成和导出
高级分析和预测功能

学习资源

官方文档：https://docs.formbricks.com/graphql-api
GraphQL规范：https://spec.graphql.org/
Apollo Client文档：https://www.apollographql.com/docs/react/
GraphQL学习平台：https://graphql.org/learn/

如果你有任何问题或需要进一步帮助，请访问Formbricks社区论坛或联系技术支持。

附录：完整类型定义参考

type Survey {
  id: ID!
  name: String!
  description: String
  status: SurveyStatus!
  createdAt: DateTime!
  updatedAt: DateTime!
  questions: [Question!]!
  responses: [Response!]!
  responseCount: Int!
  completionRate: Float!
  averageTimeToComplete: Int
  # 更多字段...
}

enum SurveyStatus {
  DRAFT
  PUBLISHED
  ARCHIVED
  SCHEDULED
}

type Question {
  id: ID!
  text: String!
  description: String
  type: QuestionType!
  required: Boolean!
  position: Int!
  options: [QuestionOption!]
  # 更多字段...
}

enum QuestionType {
  TEXT
  PARAGRAPH
  MULTIPLE_CHOICE
  CHECKBOX
  DROPDOWN
  RATING
  DATE
  EMAIL
  NUMBER
}

# 更多类型定义...

希望本教程能帮助你充分利用Formbricks GraphQL API查询和分析调查数据。如有任何问题或建议，请在评论区留言或联系我们的支持团队。

如果你觉得本教程有帮助，请点赞并分享给其他Formbricks用户！下期我们将探讨如何使用GraphQL mutations创建和更新调查数据。```markdown