Przegląd

Interfejs API Formularzy Google to interfejs typu REST, który umożliwia tworzenie i modyfikowanie formularzy oraz testów, pobieranie odpowiedzi z formularzy i ocen z testów, konfigurowanie kluczy odpowiedzi do testów z automatycznym przekazywaniem informacji zwrotnych oraz otrzymywanie powiadomień push. Typowe zastosowania tego interfejsu API to między innymi:

  • Tworzenie formularza lub testu
  • Aktualizowanie formularza lub testu
  • Pobieranie odpowiedzi z formularza lub testu
  • Odczytywanie treści i metadanych formularza
  • Konfigurowanie i odbieranie powiadomień push

Poniżej znajduje się lista typowych terminów używanych w interfejsie Formularzy API:

Formularz

Dokument z Formularzy Google utworzony i zapisany na Dysku. Każdy formularz jest reprezentowany przez zasób Form i ma unikalną wartość formId, która zawiera litery, cyfry, łączniki i podkreślenia. Identyfikator formularza znajdziesz w adresie URL Formularzy Google:

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

Test

Specjalny typ dokumentu w Formularzach Google, który umożliwia ocenianie odpowiedzi w formularzu według klucza odpowiedzi. Test można utworzyć tylko za pomocą metody batchUpdate(), aby zaktualizować ustawienie isQuiz w istniejącym formularzu do wartości true.

Ocenianie
Wartość punktowa, klucz odpowiedzi i opinia dotycząca pytania są stosowane, gdy wartość isQuiz ma wartość true. Reprezentowane przez zasób Grading.
Prześlij opinię
Odpowiedź udzielana użytkownikowi podczas odpowiadania na pytanie w quizie. Reprezentowana przez zasób Feedback.
Element

Pojedynczy element formularza reprezentowany przez zasób Item. Item to powtarzający się element, który może zawierać sekcję, grupę pytań, pytanie, tekst, obraz lub film.

Pytanie

Pojedyncze pytanie w formularzu reprezentowane przez zasób Question.

Grupa pytań

Grupa pytań, które mają ten sam zestaw możliwych odpowiedzi (np. siatka ocen od 1 do 5). Reprezentowane przez zasób QuestionGroupItem.

Sekcja

Sekcja to sposób na podzielenie formularza na wiele stron i dodanie logiki warunkowej (np. wyświetlanie określonych pytań w zależności od odpowiedzi użytkownika). Sekcje odpowiadają zasobowi PageBreakItem.

Odpowiedź

Odpowiedź użytkownika na pytanie, przedstawiona za pomocą zasobu Answer. Zawiera zarówno informacje o ocenie (jeśli występują), metadane i treść odpowiedzi.

Odpowiedź

Przesłanie formularza przez użytkownika reprezentowanego przez zasób FormResponse.

Oglądaj

Aktywator, który śledzi zmiany w zmianach schematu formularzy (np. edycja pytań) lub przesłania odpowiedzi w formularzu i wysyła powiadomienie push, gdy zajdzie taka zmiana. Reprezentowane przez zasób Watch.

Struktura formularza

Określanie różnych pól podczas zarządzania formularzami i testami może być skomplikowane, ponieważ wiele obiektów formularzy można zagnieżdżać wewnątrz innych na wiele sposobów. Jeśli chcesz zobaczyć, jak wizualizacja formularza jest mapowana na pola, zalecamy utworzenie w interfejsie kilku przykładowych formularzy, które może wygenerować Twoja aplikacja. Następnie pobierz odpowiedni plik JSON za pomocą metody forms.get(), aby móc porównać wyniki. Na przykład ten przykładowy test odpowiada temu plikowi 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"
              }
            ]
          }
        }
      }
    }
  ]
}

Dalsze kroki

  • Więcej informacji o programowaniu z użyciem interfejsów Google Workspace API, w tym o obsłudze uwierzytelniania i autoryzacji, znajdziesz w artykule Pierwsze kroki jako programista Workspace.
  • Aby dowiedzieć się, jak skonfigurować i uruchomić prostą aplikację interfejsu Formularzy API, przeczytaj krótkie wprowadzenie.