获取特定版本的资源

每个资源都有一个版本字段，每次资源发生更改时，该字段都会随之更改，即 etag 字段。Etag 是 HTTP 的标准组成部分，日历 API 在以下两种情况下支持 Etag：

  • 在资源修改时，确保在此期间没有对该资源进行其他写入（有条件修改）
  • 在资源检索时，仅在资源已更改时检索资源数据（条件检索）

有条件修改

如果您只想在资源自上次检索以来未发生更改时更新或删除该资源，可以指定一个 If-Match 标头，其中包含上次检索的 etag 值。这对于防止资源上的修改丢失非常有用。客户端可以选择重新检索资源并重新应用更改。

如果自上次检索以来，相应条目（及其 ETag）未发生变化，则修改成功，并返回具有新 ETag 的资源新版本。否则，您会收到 412（前提条件失败）响应代码。

下面的示例代码段演示了如何使用 Java 客户端库执行有条件修改。

  private static void run() throws IOException {
    // Create a test event.
    Event event = Utils.createTestEvent(client, "Test Event");
    System.out.println(String.format("Event created: %s", event.getHtmlLink()));

    // Pause while the user modifies the event in the Calendar UI.
    System.out.println("Modify the event's description and hit enter to continue.");
    System.in.read();

    // Modify the local copy of the event.
    event.setSummary("Updated Test Event");

    // Update the event, making sure that we don't overwrite other changes.
    int numAttempts = 0;
    boolean isUpdated = false;
    do {
      Calendar.Events.Update request = client.events().update("primary", event.getId(), event);
      request.setRequestHeaders(new HttpHeaders().setIfMatch(event.getEtag()));
      try {
        event = request.execute();
        isUpdated = true;
      } catch (GoogleJsonResponseException e) {
        if (e.getStatusCode() == 412) {
          // A 412 status code, "Precondition failed", indicates that the etag values didn't
          // match, and the event was updated on the server since we last retrieved it. Use
          // {@link Calendar.Events.Get} to retrieve the latest version.
          Event latestEvent = client.events().get("primary", event.getId()).execute();

          // You may want to have more complex logic here to resolve conflicts. In this sample we're
          // simply overwriting the summary.
          latestEvent.setSummary(event.getSummary());
          event = latestEvent;
        } else {
          throw e;
        }
      }
      numAttempts++;
    } while (!isUpdated && numAttempts <= MAX_UPDATE_ATTEMPTS);

    if (isUpdated) {
      System.out.println("Event updated.");
    } else {
      System.out.println(String.format("Failed to update event after %d attempts.", numAttempts));
    }
  }
ConditionalModificationSample.java

条件检索

如果您只想在资源自上次检索以来发生更改时检索该资源，可以指定一个 If-None-Match 标头，其中包含上次检索时获得的 etag 值。如果条目（以及其 ETag）自上次检索以来发生了变化，系统将返回具有新 ETag 的资源的新版本。否则，您将收到 304（未修改）响应代码。

下面的示例代码段演示了如何使用 Java 客户端库执行条件检索。

  private static void run() throws IOException {
    // Create a test event.
    Event event = Utils.createTestEvent(client, "Test Event");
    System.out.println(String.format("Event created: %s", event.getHtmlLink()));

    // Pause while the user modifies the event in the Calendar UI.
    System.out.println("Modify the event's description and hit enter to continue.");
    System.in.read();

    // Fetch the event again if it's been modified.
    Calendar.Events.Get getRequest = client.events().get("primary", event.getId());
    getRequest.setRequestHeaders(new HttpHeaders().setIfNoneMatch(event.getEtag()));
    try {
      event = getRequest.execute();
      System.out.println("The event was modified, retrieved latest version.");
    } catch (GoogleJsonResponseException e) {
      if (e.getStatusCode() == 304) {
        // A 304 status code, "Not modified", indicates that the etags match, and the event has
        // not been modified since we last retrieved it.
        System.out.println("The event was not modified, using local version.");
      } else {
        throw e;
      }
    }
  }
ConditionalRetrievalSample.java