יצירה וניהול של מפתחות API

בדף הזה מוסבר איך ליצור ולנהל מפתחות API באמצעות API של מפתחות API.

במאמר שימוש במפתחות API מוסבר איך להשתמש במפתח API בקריאות ל-API. Cloud de Confiance by S3NS

יצירת מפתח API

אפשר ליצור מפתח API באמצעות method‏ CreateKey. השיטה דורשת פרמטר Key. אפשר לציין רק את השדות displayName ו-restrictions של האובייקט Key. ‫CreateKey היא לא שיטה סינכרונית. במקום זאת, כשמבצעים קריאה ל-CreateKey, מתחילה פעולה ממושכת. בדוגמה הבאה מבוצעת קריאה ל-CreateKey כדי ליצור מפתח API ללא הגבלות:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d '{
          "displayName" : "Example API key"
        }' \
     'https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys'

אם הפעולה בוצעה ללא שגיאות, השיטה מחזירה פעולה ממושכת בתגובה. כמו שמתואר במאמר בנושא דגימה של פעולות ממושכות, צריך לבצע שוב ושוב קריאות של operations.get עם הערך מהשדה name. כשהתשובה מ-operations.get מכילה את "done": true, האובייקט response מכיל את Key, בדומה לדוגמה הבאה:

{
  "name": "operations/akmf.p7-103621867718-06f94db2-7e91-4c58-b826-e6b80e4dc3eb",
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.api.apikeys.v2.Key",
    "name": "projects/PROJECT_NUMBER/locations/global/keys/aecd7943-98ff-4ce2-a876-ec1b37c671ca",
    "displayName": "Example API key",
    "keyString": "----REDACTED----",
    "createTime": "2021-03-23T17:39:46.721099Z",
    "uid": "aecd7943-98ff-4ce2-a876-ec1b37c671ca",
    "updateTime": "2021-03-23T17:39:47.046746Z",
    "etag": "k0bsYGkIvSxDVwNxyw49NQ=="
  }
}

באובייקט response:

  • השדה name מכיל מזהה ייחודי של מפתח ה-API. משתמשים בערך בשדה name בשיטות אחרות שבהן נדרש שם מפתח. הערך הזה לא מוצג ב- Cloud de Confiance console, אבל אפשר להתקשר לשיטה ListKeys כדי לקבל את names לכל מפתחות ה-API. השדה Key.name תמיד בפורמט הבא: projects/PROJECT_NUMBER/locations/global/keys/KEY_ID.
  • השדה displayName ממופה לשדה Name במסוףCloud de Confiance , ולכן כדאי לספק displayName כשקוראים ל-CreateKey.
  • השדה keyString מכיל את המחרוזת ששולחים לממשקי ה-API שדורשים מפתח API. השדה keyString ממופה לשדה API key במסוףCloud de Confiance . אפשר להפעיל את method ‏GetKeyString כדי לקבל את keyString של מפתח API.
  • השדה etag מכיל סכום ביקורת שמחושב על ידי השרת על סמך הערך הנוכחי של המפתח. צריך להעביר את הערך etag כשמבצעים קריאה לשיטות UpdateKey ו-DeleteKey.

מזהה מפתח שצוין על ידי המשתמש

אפשר לציין את keyId כפרמטר של שאילתה לשיטה CreateKey. אם מציינים ערך, הוא הופך לרכיב הסופי של Key.name.

לדוגמה, נבחן את הקריאה הבאה לפונקציה CreateKey:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d '{
          "displayName" : "Example API key with user-specified ID"
        }' \
     'https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys?keyId=my-test-key1'

בדוגמה הזו, השדה Key.name מכיל את הערך הבא:

"name": "projects/PROJECT_NUMBER/locations/global/keys/my-test-key1"

עדכון השם המוצג

כדי לשנות את displayName של מפתח API או להוסיף displayName למפתח API שנוצר ללא displayName, צריך להפעיל את method‏ UpdateKey. כשמתקשרים אל UpdateKey, מתחילה פעולה ממושכת שמעדכנת את המפתח.

בדוגמה הבאה אפשר לראות איך מפעילים את UpdateKey:

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d '{
          "displayName": "New display name",
          "etag" : "ETAG"
        }' \
     'https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys/KEY_ID?updateMask=displayName'

כשהתשובה מ-operations.get מכילה את "done": true, response מכיל אובייקט Key עם displayName מעודכן.

מחיקת מפתח API

כדי למחוק מפתח API, משתמשים ב-method ‏DeleteKey. כשמפעילים את DeleteKey, מתחילה פעולה ממושכת שמסמנת את המפתח כ-DELETED.

בדוגמה הבאה אפשר לראות איך מפעילים את DeleteKey:

curl -X DELETE \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H 'If-Match: "ETAG"' \
     'https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys/KEY_ID'

אם התשובה מ-operations.get מכילה את "done": true, התשובה מ-response תהיה דומה לדוגמה הבאה:

{
  "name": "operations/akmf.cdabc4df-cbff-4420-8c7e-65dc832c945d",
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.api.apikeys.v2.Key"
    "name": "projects/PROJECT_NUMBER/locations/global/keys/aecd7943-98ff-4ce2-a876-ec1b37c671ca",
    "displayName": "Example API key",
    "keyString": "----REDACTED----",
    "createTime": "2021-03-23T17:39:46.721099Z",
    "uid": "aecd7943-98ff-4ce2-a876-ec1b37c671ca",
    "updateTime": "2021-03-23T17:39:47.046746Z",
    "deleteTime": "2021-03-24T22:35:37.290544Z",
    "etag": "k0bsYGkIvSxDVwNxyw49NQ=="
  }
}

אי אפשר להשתמש במפתח API שמסומן בסימן DELETED, אבל הוא גם לא מוסר לגמרי מהמערכת שלנו. כדי להציג רשימה של מפתחות API שעדיין קיימים אבל מסומנים כ-DELETED, צריך להגדיר את show_deleted כ-true עבור method ‏ListKeys:

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     'https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys?show_deleted=true'

אחרי 30 יום, מפתח ה-API נמחק סופית.

שחזור מפתח API

כדי לשחזר מפתח API לפני שהוא נמחק באופן סופי, צריך להפעיל את method‏ UndeleteKey. כשמפעילים את UndeleteKey, מתחילה פעולה ממושכת שמסמנת את המפתח כ-ACTIVE.

בדוגמה הבאה אפשר לראות איך מפעילים את UndeleteKey:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     'https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys/KEY_ID/:undelete'

המאמרים הבאים