نسخه های خاصی از منابع را دریافت کنید

هر منبع یک فیلد نسخه دارد که هر بار که منبع تغییر می‌کند، تغییر می‌کند - فیلد etag . ETag ها بخش استاندارد HTTP هستند و در API تقویم گوگل برای دو مورد پشتیبانی می‌شوند:

  • در مورد تغییرات منبع، برای اطمینان از اینکه هیچ نوشتن دیگری در این منبع در این فاصله رخ نداده است (تغییر مشروط).
  • در بازیابی منبع، داده‌ها فقط در صورتی بازیابی شوند که منبع تغییر کرده باشد (بازیابی مشروط).

اصلاح شرطی

اگر می‌خواهید منبعی را فقط در صورتی به‌روزرسانی یا حذف کنید که از آخرین بازیابی آن تغییر نکرده باشد، می‌توانید یک سرآیند If-Match که حاوی مقدار ETag از بازیابی قبلی است را مشخص کنید. این به جلوگیری از از دست رفتن تغییرات روی منابع کمک می‌کند. کلاینت‌ها می‌توانند منبع را دوباره بازیابی کرده و تغییرات را دوباره اعمال کنند.

اگر ورودی (و ETag آن) از آخرین بازیابی تغییر نکرده باشد، تغییر موفقیت‌آمیز بوده و سرور نسخه جدید منبع را با ETag جدید برمی‌گرداند. در غیر این صورت، سرور کد پاسخ 412 Precondition Failed برمی‌گرداند.

نمونه زیر نحوه انجام تغییرات شرطی با کتابخانه کلاینت جاوا را نشان می‌دهد:

  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));
    }
  }

بازیابی مشروط

اگر می‌خواهید منبعی را فقط در صورتی بازیابی کنید که از آخرین بازیابی شما تغییر کرده باشد، می‌توانید یک هدر If-None-Match تعیین کنید که حاوی مقدار ETag از بازیابی قبلی باشد. اگر ورودی (و بنابراین ETag آن) از آخرین بازیابی تغییر کرده باشد، سرور نسخه جدید منبع را با ETag جدید برمی‌گرداند. در غیر این صورت، سرور کد پاسخ 304 Not Modified را برمی‌گرداند.

نمونه زیر نحوه انجام بازیابی شرطی با کتابخانه کلاینت جاوا را نشان می‌دهد:

  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;
      }
    }
  }