Informações gerais

A API Google Forms é uma interface RESTful que permite criar e modificar formulários e testes, recuperar respostas de formulários e notas, configurar chaves de respostas com feedback automático e receber notificações push. Os usos mais comuns dessa API incluem as seguintes tarefas:

  • Criar um teste ou formulário
  • Atualizar um teste ou formulário
  • Recuperar respostas de um formulário ou teste
  • Ler o conteúdo e os metadados de formulários
  • Configurar e receber notificações push

Veja abaixo uma lista de termos comuns usados na API Forms:

Formulário

Um documento do Formulários Google, criado e armazenado no Drive. Cada forma é representada por um recurso Form e tem um valor formId exclusivo, contendo letras, números, hifens ou sublinhados. É possível encontrar o ID do formulário em um URL do app Formulários Google:

https://docs.google.com/forms/d/FORM_ID/edit

Teste

Um tipo específico de arquivo do Formulários Google que permite avaliar as respostas do formulário em relação a uma chave de resposta. Um teste só pode ser criado usando o método batchUpdate() para atualizar a configuração isQuiz de um formulário existente para true.

Avaliação
Uma pontuação, uma chave de resposta e um feedback para uma pergunta, aplicados quando isQuiz é true. Representado pelo recurso Grading.
Feedback
Uma resposta dada ao usuário final ao responder a uma pergunta em um teste, representada pelo recurso Feedback.
Item

Um único elemento em um formulário, representado pelo recurso Item. Item é um elemento recorrente que pode conter uma seção, grupo de perguntas, pergunta, texto, imagem ou vídeo.

Question

Uma única pergunta no formulário, representada pelo recurso Question.

Grupo de perguntas

Um grupo de perguntas que compartilham o mesmo conjunto de respostas possíveis (por exemplo, uma grade de classificações de 1 a 5). Representado pelo recurso QuestionGroupItem.

Section

Uma seção é uma maneira de dividir um formulário em várias páginas e adicionar lógica condicional, como mostrar apenas determinadas perguntas com base nas respostas do usuário. As seções correspondem ao recurso PageBreakItem.

Resposta

A resposta do usuário final a uma pergunta, representada pelo recurso Answer. Inclui informações da nota (se houver), metadados e o conteúdo da resposta.

Resposta

O envio de um formulário pelo usuário final, representado pelo recurso FormResponse.

Assista

Um acionador que rastreia alterações em mudanças no esquema de formulários (como edições em perguntas) ou envios de resposta de formulário e envia uma notificação push quando ocorre uma mudança. Representado pelo recurso Watch.

Estrutura do formulário

Ao gerenciar formulários e testes, entender como especificar campos diferentes pode ser complicado, já que muitos dos objetos do formulário podem ser aninhados de várias maneiras. Para conferir como a representação visual de um formulário é mapeada para os campos, recomendamos usar a interface para criar alguns exemplos de formulários que podem ser gerados pelo app. Em seguida, recupere o JSON correspondente usando o método forms.get() para comparar. Por exemplo, este exemplo de teste corresponde ao seguinte JSON:

{
  "formId": "FORM_ID",
  "info": {
    "title": "Famous Black Women",
    "description": "Please complete this quiz based off of this week's readings for class.",
    "documentTitle": "API Example Quiz"
  },
  "settings": {
    "quizSettings": {
      "isQuiz": true
    }
  },
  "revisionId": "00000021",
  "responderUri": "https://docs.google.com/forms/d/e/1FAIpQLSd0iBLPh4suZoGW938EU1WIxzObQv_jXto0nT2U8HH2KsI5dg/viewform",
  "items": [
    {
      "itemId": "5d9f9786",
      "imageItem": {
        "image": {
          "contentUri": "DIRECT_URL",
          "properties": {
            "alignment": "LEFT"
          }
        }
      }
    },
    {
      "itemId": "72b30353",
      "title": "Which African American woman authored \"I Know Why the Caged Bird Sings\"?",
      "questionItem": {
        "question": {
          "questionId": "25405d4e",
          "required": true,
          "grading": {
            "pointValue": 2,
            "correctAnswers": {
              "answers": [
                {
                  "value": "Maya Angelou"
                }
              ]
            }
          },
          "choiceQuestion": {
            "type": "RADIO",
            "options": [
              {
                "value": "Maya Angelou"
              },
              {
                "value": "bell hooks"
              },
              {
                "value": "Alice Walker"
              },
              {
                "value": "Roxane Gay"
              }
            ]
          }
        }
      }
    },
    {
      "itemId": "0a4859c8",
      "title": "Who was the first Dominican-American woman elected to state office?",
      "questionItem": {
        "question": {
          "questionId": "37fff47a",
          "grading": {
            "pointValue": 2,
            "correctAnswers": {
              "answers": [
                {
                  "value": "Grace Diaz"
                }
              ]
            }
          },
          "choiceQuestion": {
            "type": "RADIO",
            "options": [
              {
                "value": "Rosa Clemente"
              },
              {
                "value": "Grace Diaz"
              },
              {
                "value": "Juana Matias"
              },
              {
                "value": "Sabrina Matos"
              }
            ]
          }
        }
      }
    }
  ]
}

Próximas etapas