יצירת בקשות API וטיפול בתגובות

במאמר הזה מוסבר איך ליצור בקשות ל-API ואיך לטפל בתשובות ל-API מ-Compute Engine API. המאמר מסביר איך:

יוצרים את גוף הבקשה.
קובעים את ה-URI של המשאב שנדרש לבקשה.
טיפול בתגובות מה-API.
לבדוק אם בקשת API הצליחה.

במאמר הזה לא מוסבר איך לבצע אימות ל-API. כדי ללמוד איך לאמת את הגישה ל-API, אפשר לעיין במאמר בנושא אימות ב-Compute Engine.

לפני שמתחילים

מומלץ להכיר את ממשקי REST API.
איך מאמתים את הגישה ל-Compute Engine API.

יצירת בקשת API

הבקשות ל-Compute Engine API צריכות להיות בפורמט JSON. כדי לשלוח בקשת API, אפשר לשלוח בקשת HTTP ישירה באמצעות כלים כמו curl או httplib2, או להשתמש באחת מספריות הלקוח הזמינות.

כששולחים בקשת API שדורשת גוף בקשה, כמו בקשת POST,‏ UPDATE או PATCH, גוף הבקשה מכיל מאפייני משאב שרוצים להגדיר בבקשה הזו. לדוגמה, הפקודה curl הבאה שולחת בקשת POST ל-URI של משאב Instances. הבקשה יוצרת מופע עם המאפיינים שמוגדרים בגוף הבקשה. גוף הבקשה מסומן בדגל -d:

curl -X POST -H "Authorization: Bearer [OAUTH_TOKEN]" -H "Content-Type: application/json" \
https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances -d \
'{
  "disks":[
    {
      "boot":"true",
      "initializeParams":{
        "sourceImage":"https://www.googleapis.com/compute/v1/projects/debian-cloud/global/images/debian-10-buster-v20210122"
      }
    }
  ],
  "machineType":"https://www.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/machineTypes/e2-standard-2",
  "name":"VM_NAME",
  "networkInterfaces":[
    {
      "accessConfigs":[
        {
          "name":"external-nat",
          "type":"ONE_TO_ONE_NAT"
        }
      ],
      "network":"https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/networks/default"
    }
  ]
}'

ל-URI של התמונה יש מזהה פרויקט שונה (debian-cloud) ממזהה הפרויקט שלכם, כי התמונות שייכות לפרויקטים שונים, בהתאם לסוג התמונה. לדוגמה, כל תמונות Debian שזמינות לציבור ומוצעות על ידי Compute Engine מתארחות בפרויקט debian-cloud.

כשמפנים למשאב אחר, צריך להשתמש ב-URI המלא של המשאב. לדוגמה, המאפיין network משתמש במזהה משאבים אחיד (URI) מוגדר במלואו ברשת default.

דוגמאות לבקשות API

Python

def create_instance(
    compute: object,
    project: str,
    zone: str,
    name: str,
    bucket: str,
) -> str:
    """Creates an instance in the specified zone.

    Args:
      compute: an initialized compute service object.
      project: the Google Cloud project ID.
      zone: the name of the zone in which the instances should be created.
      name: the name of the instance.
      bucket: the name of the bucket in which the image should be written.

    Returns:
      The instance object.
    """
    # Get the latest Debian Jessie image.
    image_response = (
        compute.images()
        .getFromFamily(project="debian-cloud", family="debian-11")
        .execute()
    )
    source_disk_image = image_response["selfLink"]

    # Configure the machine
    machine_type = "zones/%s/machineTypes/n1-standard-1" % zone
    startup_script = open(
        os.path.join(os.path.dirname(__file__), "startup-script.sh")
    ).read()
    image_url = "http://storage.googleapis.com/gce-demo-input/photo.jpg"
    image_caption = "Ready for dessert?"

    config = {
        "name": name,
        "machineType": machine_type,
        # Specify the boot disk and the image to use as a source.
        "disks": [
            {
                "boot": True,
                "autoDelete": True,
                "initializeParams": {
                    "sourceImage": source_disk_image,
                },
            }
        ],
        # Specify a network interface with NAT to access the public
        # internet.
        "networkInterfaces": [
            {
                "network": "global/networks/default",
                "accessConfigs": [{"type": "ONE_TO_ONE_NAT", "name": "External NAT"}],
            }
        ],
        # Allow the instance to access cloud storage and logging.
        "serviceAccounts": [
            {
                "email": "default",
                "scopes": [
                    "https://www.googleapis.com/auth/devstorage.read_write",
                    "https://www.googleapis.com/auth/logging.write",
                ],
            }
        ],
        # Metadata is readable from the instance and allows you to
        # pass configuration from deployment scripts to instances.
        "metadata": {
            "items": [
                {
                    # Startup script is automatically executed by the
                    # instance upon startup.
                    "key": "startup-script",
                    "value": startup_script,
                },
                {"key": "url", "value": image_url},
                {"key": "text", "value": image_caption},
                {"key": "bucket", "value": bucket},
            ]
        },
    }

    return compute.instances().insert(project=project, zone=zone, body=config).execute()

Java

public static Operation startInstance(Compute compute, String instanceName) throws IOException {
  System.out.println("================== Starting New Instance ==================");

  // Create VM Instance object with the required properties.
  Instance instance = new Instance();
  instance.setName(instanceName);
  instance.setMachineType(
      String.format(
          "https://www.googleapis.com/compute/v1/projects/%s/zones/%s/machineTypes/e2-standard-1",
          PROJECT_ID, ZONE_NAME));
  // Add Network Interface to be used by VM Instance.
  NetworkInterface ifc = new NetworkInterface();
  ifc.setNetwork(
      String.format(
          "https://www.googleapis.com/compute/v1/projects/%s/global/networks/default",
          PROJECT_ID));
  List<AccessConfig> configs = new ArrayList<>();
  AccessConfig config = new AccessConfig();
  config.setType(NETWORK_INTERFACE_CONFIG);
  config.setName(NETWORK_ACCESS_CONFIG);
  configs.add(config);
  ifc.setAccessConfigs(configs);
  instance.setNetworkInterfaces(Collections.singletonList(ifc));

  // Add attached Persistent Disk to be used by VM Instance.
  AttachedDisk disk = new AttachedDisk();
  disk.setBoot(true);
  disk.setAutoDelete(true);
  disk.setType("PERSISTENT");
  AttachedDiskInitializeParams params = new AttachedDiskInitializeParams();
  // Assign the Persistent Disk the same name as the VM Instance.
  params.setDiskName(instanceName);
  // Specify the source operating system machine image to be used by the VM Instance.
  params.setSourceImage(SOURCE_IMAGE_PREFIX + SOURCE_IMAGE_PATH);
  // Specify the disk type as Standard Persistent Disk
  params.setDiskType(
      String.format(
          "https://www.googleapis.com/compute/v1/projects/%s/zones/%s/diskTypes/pd-standard",
          PROJECT_ID, ZONE_NAME));
  disk.setInitializeParams(params);
  instance.setDisks(Collections.singletonList(disk));

  // Initialize the service account to be used by the VM Instance and set the API access scopes.
  ServiceAccount account = new ServiceAccount();
  account.setEmail("default");
  List<String> scopes = new ArrayList<>();
  scopes.add("https://www.googleapis.com/auth/devstorage.full_control");
  scopes.add("https://www.googleapis.com/auth/compute");
  account.setScopes(scopes);
  instance.setServiceAccounts(Collections.singletonList(account));

  // Optional - Add a startup script to be used by the VM Instance.
  Metadata meta = new Metadata();
  Metadata.Items item = new Metadata.Items();
  item.setKey("startup-script-url");
  // If you put a script called "vm-startup.sh" in this Google Cloud Storage
  // bucket, it will execute on VM startup.  This assumes you've created a
  // bucket named the same as your PROJECT_ID.
  // For info on creating buckets see:
  // https://cloud.google.com/storage/docs/cloud-console#_creatingbuckets
  item.setValue(String.format("gs://%s/vm-startup.sh", PROJECT_ID));
  meta.setItems(Collections.singletonList(item));
  instance.setMetadata(meta);

  System.out.println(instance.toPrettyString());
  Compute.Instances.Insert insert = compute.instances().insert(PROJECT_ID, ZONE_NAME, instance);
  return insert.execute();
}

יצירת כתובות URI של משאבים

ב-Compute Engine API, הפניה למשאב אחר Google Cloud מופיעה כ-URI מוגדר במלואו:

https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/RESOURCE_TYPE/SPECIFIC_RESOURCE

בכל פעם שמציינים תמונה, סוג מכונה, רשת או כל משאב אחר, צריך לספק את ה-URI של המשאב כשמשתמשים ב-API. כלים ללקוחות כמו Google Cloud CLI ומסוף Google Cloud מסתירים את המורכבות הזו ומטפלים ביצירת מזהי ה-URI של המשאבים בשבילכם, אבל כשמתקשרים עם ה-API ישירות, צריך ליצור את מזהי ה-URI של המשאבים בעצמכם.

יש מזהי URI שונים למשאבים מסוגים שונים. לדוגמה, למשאב של תחום מוגדר יש את המפרט zone ב-URI:

https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/machineTypes/e2-standard-2

משאבים אזוריים מחליפים את המפרט zone במפרט region:

https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION/addresses/ADDRESS_NAME

באופן דומה, למשאבים גלובליים יש את המפרט global:

https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/global/images/VM_NAME

‫Compute Engine API מקבל גם כתובות URI חלקיות, כי השירות יכול להסיק מידע כמו מזהה הפרויקט. לכן, גם הגרסאות החלקיות הבאות של מזהי ה-URI הקודמים מקובלות:

zones/ZONE/machineTypes/e2-standard-2

regions/REGION/addresses/ADDRESS_NAME

project/PROJECT_ID/global/images/VM_NAME

במזהי ה-URI החלקיים, גם מזהי ה-URI האזוריים וגם מזהי ה-URI של האזורים לא כללו את מזהה הפרויקט, אבל מזהה ה-URI של התמונה כן כלל אותו. הסיבה לכך היא שתמונות שזמינות לציבור ומוצעות על ידי Compute Engine מתארחות בפרויקטים אחרים, כמו debian-cloud לכל תמונות Debian ו-ubuntu-os-cloud לכל תמונות Ubuntu. כדי להשתמש בתמונות האלה, צריך לספק את מזהה הפרויקט המתאים. אם לא מציינים את מזהה הפרויקט של התמונות, ‏ Compute Engine מנסה למצוא את התמונה בפרויקט, והבקשה נכשלת כי התמונה לא קיימת.

עם זאת, אם משתמשים בתמונה בהתאמה אישית ששייכת לפרויקט (אותו פרויקט שבו יוצרים את המשאב הזה), אפשר להשמיט את הגדרת הפרויקט כשמספקים URI של תמונה.

זיהוי מאפייני חובה

בתיעוד העזר של Compute Engine API, שזמינים ל-API בגרסה v1 ול-API בגרסת בטא, מפורטות כל האפשרויות להגדרת מאפיינים של משאב ספציפי. במסמכי העזר יש הבחנה בין מאפיינים שניתנים לשינוי לבין מאפיינים שלא ניתן לשנות (מסומנים ב-[Output Only] בתיאור המאפיין), אבל כדי לדעת אילו מאפיינים נדרשים למשאב מסוים, צריך לעיין במסמכים שספציפיים למשימה הזו.

לדוגמה, אם אתם יוצרים מכונה, כדאי לקרוא את מאמרי העזרה יצירת מכונה מתמונה כדי לראות את מאפייני ה-API שנדרשים לבקשה. אם אתם רוצים ליצור כתובת IP חיצונית סטטית ב-API, כדאי לקרוא את מאמרי העזרה בנושא כתובות IP חיצוניות סטטיות.

אימות בקשות API

כדי לאמת את בקשות ה-API:

בהפניה ל-API של Compute Engine, מחפשים את ה-method שהקוד קורא לו. לדוגמה, v1/compute.instances.insert.
בתפריט התוכן, לוחצים על אפשר לנסות! ייפתח החלון Try this API.
בקטע Request parameters (פרמטרים של בקשה), לא צריך לספק project (פרויקט) או zone (אזור) כי האימות לא דורש שליחת הבקשה.
בקטע Request body, מדביקים את הבקשה.

אלמנטים בבקשה שהפורמט שלהם שגוי יודגשו בקו תחתון כחול. כדי לקבל מידע נוסף על הבעיה שצריך לטפל בה, לוחצים על כל חלק עם קו תחתון.

טיפול בתגובות מה-API

אם שולחים בקשה שמשנה נתונים, Compute Engine מחזיר אובייקט Operation שאפשר לשלוח לו שאילתות כדי לקבל את סטטוס הפעולות של הבקשה. משאב Operation נראה כך:

{
 "kind": "compute#operation",
 "id": "7127550864823803662",
 "name": "operation-1458856416788-52ed27a803e22-1c3bd86a-9e95017b",
 "zone": "https://www.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE",
 "operationType": "insert",
 "targetLink": "https://www.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/EXAMPLE_VM",
 "targetId": "4132355614508179214",
 "status": "PENDING",
 "user": "user@example.com",
 "progress": 0,
 "insertTime": "2016-03-24T14:53:37.788-07:00",
 "selfLink": "https://www.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/operations/operation-1458856416788-52ed27a803e22-1c3bd86a-9e95017b"
}

אם הבקשה המקורית היא לשנות משאב של תחום מוגדר – לדוגמה, ליצור תמונת מצב של דיסק או להפסיק מכונה –‏ Compute Engine מחזיר אובייקט zoneOperations. באופן דומה, משאבים אזוריים וגלובליים מחזירים אובייקט regionOperations או globalOperations, בהתאמה. כדי לקבל את הסטטוס של פעולה, צריך לבצע בקשה באמצעות השיטה get או wait למשאב Operation הספציפי ולציין את name של הפעולה.

הבקשה תושלם רק אחרי שהסטטוס של המשאב Operation יהיה DONE. הזמן שיידרש לטיפול בבקשה תלוי באופי הבקשה. אחרי שהסטטוס של רכיב Operation חוזר כ-DONE, אפשר לבדוק אם הפעולה הצליחה ואם היו שגיאות.

לדוגמה, התגובה הבאה מציינת שהפעולה הקודמת הושלמה, כפי שמצוין בסטטוס DONE:

endTime: '2016-03-24T14:54:07.119-07:00'
id: '7127550864823803662'
insertTime: '2016-03-24T14:53:37.788-07:00'
kind: compute#operation
name: operation-1458856416788-52ed27a803e22-1c3bd86a-9e95017b
operationType: insert
progress: 100
selfLink: https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/operations/operation-1458856416788-52ed27a803e22-1c3bd86a-9e95017b
startTime: '2016-03-24T14:53:38.397-07:00'
status: DONE
targetId: '4132355614508179214'
targetLink: https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/EXAMPLE_VM
user: user@example.com
zone: https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE

כדי לוודא, שולחים בקשת get למשאב כדי לבדוק שהוא קיים ופועל. לדוגמה:

GET /compute/v1/projects/PROJECT_ID/zones/ZONE/instances/EXAMPLE_VM

{
  "cpuPlatform": "Intel Haswell",
  "creationTimestamp": "2016-03-24T14:53:37.170-07:00",
  "disks": [
    ..[snip]..
  "selfLink": "https://www.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/EXAMPLE_VM",
  "status": "RUNNING",
  "tags": {
    "fingerprint": "42WmSpB8rSM="
  },
  "zone": "https://www.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE"
}

פעולות דגימה

אפשר לכתוב קוד שידגום את הפעולה מעת לעת באמצעות בקשת get או wait, שתחזיר תשובה כשהסטטוס של הפעולה יהיה DONE.

בבקשת get, הפעולה מוחזרת באופן מיידי, ללא קשר לסטטוס שלה. צריך לבצע דגימה של הפעולה באופן קבוע כדי לדעת מתי היא תסתיים.

אם שולחים בקשת wait, הבקשה מוחזרת כשהפעולה היא DONE או אם הבקשה מתקרבת למועד האחרון של 2 דקות. אתם יכולים להשתמש בשיטה wait או בשיטה get כדי לדגום את הפעולות שלכם, אבל לשיטה wait יש יתרונות מסוימים על פני השיטה get:

אפשר להגדיר את הלקוחות כך שיבדקו את סטטוס הפעולה בתדירות נמוכה יותר, וכך להקטין את השימוש ב-QPS ב-Compute Engine API.
זמן האחזור הממוצע בין סיום הפעולה לבין העדכון של הלקוח על סיום הפעולה קצר משמעותית, כי השרת מגיב ברגע שהפעולה מסתיימת.
השיטה מספקת זמני המתנה מוגבלים. השיטה ממתינה לזמן קצוב לתפוגה של HTTP (2 דקות) ואז מחזירה את המצב הנוכחי של הפעולה, שיכול להיות DONE או עדיין בתהליך.

השיטה wait היא API מסוג best-effort. אם השרת עמוס מדי, יכול להיות שהבקשה תחזור לפני שהיא תגיע למועד האחרון שמוגדר כברירת מחדל, או אחרי המתנה של אפס שניות בלבד. בנוסף, לא מובטח שהשיטה תחזיר ערך רק כשהפעולה היא DONE. לדוגמה, אם הבקשה מתקרבת למועד האחרון של 2 דקות, השיטה מחזירה ערך גם אם הפעולה לא הסתיימה. כדי לבדוק את הפעולות, מומלץ להשתמש בשיטה wait או בשיטה get – בלולאת ניסיון חוזר עם השהיה בין הניסיונות – כדי לדגום מעת לעת את סטטוס הפעולה. המרווח המקסימלי לניסיון חוזר לא יכול להיות ארוך יותר מתקופת השמירה המינימלית של הפעולה.

דוגמה לסקר

בדוגמאות הבאות נעשה שימוש במתודה get. אפשר להחליף את השיטה get בשיטה wait:

Python

def wait_for_operation(
    compute: object,
    project: str,
    zone: str,
    operation: str,
) -> dict:
    """Waits for the given operation to complete.

    Args:
      compute: an initialized compute service object.
      project: the Google Cloud project ID.
      zone: the name of the zone in which the operation should be executed.
      operation: the operation ID.

    Returns:
      The result of the operation.
    """
    print("Waiting for operation to finish...")
    while True:
        result = (
            compute.zoneOperations()
            .get(project=project, zone=zone, operation=operation)
            .execute()
        )

        if result["status"] == "DONE":
            print("done.")
            if "error" in result:
                raise Exception(result["error"])
            return result

        time.sleep(1)

Java

/**
 * Wait until {@code operation} is completed.
 *
 * @param compute the {@code Compute} object
 * @param operation the operation returned by the original request
 * @param timeout the timeout, in millis
 * @return the error, if any, else {@code null} if there was no error
 * @throws InterruptedException if we timed out waiting for the operation to complete
 * @throws IOException if we had trouble connecting
 */
public static Operation.Error blockUntilComplete(
    Compute compute, Operation operation, long timeout) throws Exception {
  long start = System.currentTimeMillis();
  final long pollInterval = 5 * 1000;
  String zone = getLastWordFromUrl(operation.getZone()); // null for global/regional operations
  String region = getLastWordFromUrl(operation.getRegion());
  String status = operation.getStatus();
  String opId = operation.getName();
  while (operation != null && !status.equals("DONE")) {
    Thread.sleep(pollInterval);
    long elapsed = System.currentTimeMillis() - start;
    if (elapsed >= timeout) {
      throw new InterruptedException("Timed out waiting for operation to complete");
    }
    System.out.println("waiting...");
    if (zone != null) {
      Compute.ZoneOperations.Get get = compute.zoneOperations().get(PROJECT_ID, zone, opId);
      operation = get.execute();
    } else if (region != null) {
      Compute.RegionOperations.Get get = compute.regionOperations().get(PROJECT_ID, region, opId);
      operation = get.execute();
    } else {
      Compute.GlobalOperations.Get get = compute.globalOperations().get(PROJECT_ID, opId);
      operation = get.execute();
    }
    if (operation != null) {
      status = operation.getStatus();
    }
  }
  return operation == null ? null : operation.getError();
}

יצירת בקשות API וטיפול בתגובות קל לארגן דפים בעזרת אוספים אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.

לפני שמתחילים

יצירת בקשת API

דוגמאות לבקשות API

Python

Java

יצירת כתובות URI של משאבים

זיהוי מאפייני חובה

אימות בקשות API

טיפול בתגובות מה-API

פעולות דגימה

דוגמה לסקר

Python

Java

יצירת בקשות API וטיפול בתגובות