שילוב פתרון SaaS עם Google Cloud Marketplace API באמצעות Producer Portal (Python)

1. מבוא

פתרונות SaaS ב-Google Cloud Marketplace הם פתרונות תוכנה שפועלים בתשתית שלכם, ללא קשר למיקום, אבל Google מחייבת אתכם עליהם.

ב-codelab הזה תגדירו פתרון SaaS בסיסי שמשתלב עם Google Cloud Marketplace כדי:

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

ב-codelab הזה תלמדו על ממשקי ה-API של הרכש ושל בקרת השירות ב-Google Cloud Marketplace. שימו לב: המדריך הזה לא מספק סביבת מוצר מלאה לבדיקה.

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

  • אם עדיין לא הפעלתם את ה-codelab בפרויקט שלכם, אתם יכולים לעשות זאת באמצעות Producer Portal.

הקישור הישיר ל-Producer Portal הוא:

https://console.cloud.google.com/producer-portal?project=YOUR_PROJECT_ID

כדי להפעיל את ה-codelab, לוחצים על Enable (הפעלה) בחלונית Codelabs בצד שמאל של המסך.

  • מתקינים את Python 3 במחשב, עם המודולים הבאים:
  • ‫ Python Google Client APIs.
  • ספריית הלקוח google-cloud-pubsub.

כדי להתקין את מודולי Python, משתמשים בפקודה הבאה:

pip install --upgrade google-api-python-client google-cloud-pubsub
  • משכפלים או מורידים את מאגר GitHub של ה-codelab הזה באמצעות הפקודה הבאה:
git clone https://github.com/googlecodelabs/gcp-marketplace-integrated-saas.git
cd gcp-marketplace-integrated-saas

  • מגדירים את משתנה הסביבה GOOGLE_CLOUD_PROJECT למזהה של הפרויקט הזה:
  • Linux:
export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"
  • Windows:
set GOOGLE_CLOUD_PROJECT=YOUR_PROJECT_ID
  • מגדירים את משתנה הסביבה GOOGLE_APPLICATION_CREDENTIALS לנתיב המלא של הקובץ שהורד:
  • Linux:
export GOOGLE_APPLICATION_CREDENTIALS="[YOUR_MACHINE]/path/service-account-key.json"
  • Windows:
set GOOGLE_APPLICATION_CREDENTIALS=[YOUR_MACHINE]/path/service-account-key.json
  • כדי לראות פתרון לדוגמה ב-Google Cloud Marketplace, נכנסים לפורטל של הספק ולוחצים על Codelab product (מוצר Codelab) בחלונית Codelabs. אפשר גם לגשת ישירות לפתרון בכתובת https://console.cloud.google.com/marketplace/product/DEMO-YOUR_PROJECT_ID/isaas-codelab
  • במסוף Google Cloud, בפרויקט החדש, מפעילים את Partner Procurement API.

לאחר מכן, מגדירים את ה-backend של הפתרון לדוגמה.

3. שילוב עם Google Cloud Marketplace

באופן כללי, אפשר לשלב את הפתרון לדוגמה עם Google Cloud Marketplace בדרכים הבאות:

  • שילוב עם Cloud Pub/Sub כדי לקבל התראות מ-Google Cloud Marketplace, למשל כשמשתמש נרשם לפתרון שלכם. מהנדס השותף יוצר נושא ב-Cloud Pub/Sub שאליו אתם צריכים להירשם כדי לקבל התראות.
  • כדי ליצור חשבונות ללקוחות חדשים, צריך לבצע שילוב עם Partner Procurement API. אתם משתמשים ב-Partner Procurement API כדי לעדכן את החשבונות כשהמשתמשים בוחרים, משנים או מבטלים את תוכניות המינוי שלהם. כדי לבצע שילוב עם ה-API, תצטרכו ליצור ספריית לקוח משלכם.
  • שילוב עם Google Service Control כדי לדווח על פרטי שימוש.

4. הרשמה לנושא ב-Cloud Pub/Sub

כשמשתמש בוחר תוכנית מינוי, אתם מקבלים התראה מ-Google Cloud Marketplace דרך נושא Cloud Pub/Sub.

כדי להאזין להודעות בנושא Cloud Pub/Sub, קודם צריך ליצור מינוי.

כדי ליצור מינוי, משתמשים בסקריפט create_subscription.py:

cd gcp-marketplace-integrated-saas/tools
python create_subscription.py

כדי לראות את המינוי, פותחים את לוח הבקרה של Cloud Pub/Sub במסוף Cloud:

https://console.cloud.google.com/cloudpubsub/subscriptions

ניסיון לשלוח בקשה למינוי לבדיקה

כדי לבדוק את האפליקציה לדוגמה הזו בתור משתמש, פותחים את מוצר ה-codelab ב-Marketplace בכתובת https://console.cloud.google.com/marketplace/product/DEMO-YOUR_PROJECT_ID/isaas-codelab. מוודאים שהפרויקט שלכם ב-codelab נבחר, ובוחרים תוכנית מינוי.

כדי לראות את ההודעות של Cloud Pub/Sub שנשלחות כשבוחרים תוכנית, עוברים אל ספריית הבסיס python3 במאגר ומריצים את הפקודה הבאה:

~/gcp-marketplace-integrated-saas/python3$ python -m impl.step_1_pubsub.app

כדי לראות את קוד הדוגמה שמקשיב להודעות Cloud Pub/Sub, אפשר לעיין בכתובת https://github.com/googlecodelabs/gcp-marketplace-integrated-saas/blob/master/python3/impl/step_1_pubsub/app.py.

בשדה eventType בהודעה של Cloud Pub/Sub מוצגות הסיבות לשליחת ההודעה. כשבוחרים תוכנית, אמורה להופיע הודעה לגבי eventType: ENTITLEMENT_CREATION_REQUESTED, שמייצגת את הבחירה הקודמת שלכם בתוכנית המינוי.

אם תבטלו את המינוי בזמן שהסקריפט הזה פועל, תופיע הודעה חדשה, למשך eventType: ENTITLEMENT_CANCELLED.

שימו לב: בדוגמה שלמעלה אין אישור על קבלת ההודעות. כך תוכלו לבדוק בקלות רבה יותר את האפליקציה, כי בכל פעם שתפעילו אותה תקבלו את אותן הודעות.

כדי לסגור את התסריט, לוחצים על CTRL + \.

5. אישור הבקשה לגישה לחשבון

עכשיו, אחרי שאתם יכולים לקבל הודעות מ-Google Cloud Marketplace, אתם צריכים להתחיל לטפל במשאבים ששירות הרכש של Google Cloud Marketplace יוצר בשם הלקוח.

הראשון הוא משאב החשבון. חשבון מייצג את הקשר של לקוח למוצר שלכם. אתם צריכים לאחסן במסד הנתונים שלכם את מזהה חשבון הרכש של הלקוח, כדי למפות את הקשר בין חשבון Google שלו לבין החשבון שלו בשירות שלכם.

כשלקוח בוחר תוכנית, Google Cloud Marketplace שולח התראה ב-Cloud Pub/Sub שהלקוח מבקש לפתוח חשבון. האפליקציה צריכה לאשר את הבקשה. ב-codelab הזה, מאשרים את בקשות החשבון כשההודעות של Cloud Pub/Sub מתקבלות.

יצירת מסד הנתונים של פרטי החשבון

ב-codelab הזה אנחנו משתמשים במסד נתונים פשוט של JSON שיכול לעקוב אחרי חשבונות של לקוחות ורכישות.

כדי לבדוק את הדוגמה הזו, יוצרים קובץ עם אובייקט JSON ריק, בכל מקום בתחנת העבודה:

{}

מגדירים את משתנה הסביבה PROCUREMENT_CODELAB_DATABASE לנתיב המלא של הקובץ:

  • Linux:
export PROCUREMENT_CODELAB_DATABASE="YOUR_MACHINE/path/EMPTY_JSON_OBJECT.json"
  • Windows:
set PROCUREMENT_CODELAB_DATABASE=YOUR_MACHINE/path/EMPTY_JSON_OBJECT.json

המודול שקורא וכותב את מסד הנתונים נמצא ב-python3/impl/database.

ההטמעה לדוגמה משתמשת בסכימה שאפשר להרחיב אם משלבים יותר ממוצר אחד עם Google Cloud Marketplace. זוהי דוגמה לרשומה במסד נתונים של משתמש שנרשם למינוי לתוכנית Very Good באפליקציה לדוגמה:

{
   "a2b3c4d5-b3f1-4dea-b134-generated_id":{
      "procurement_account_id":"generated-b3f1-4dea-b134-4a1d100c0335",
      "internal_account_id":"generated-45b7-4f4d-1bcd-2abb114f77de",
      "products":{
         "isaas-codelab":{
            "start_time":"2019-01-04T01:21:16.188Z",
            "plan_id":"very-good",
            "product_id":"isaas-codelab",
            "consumer_id":"project_number:123123345345"
         }
      }
   }
}

ביישום הסופי, אתם צריכים לקשר את האפליקציה למסדי הנתונים שלכם כדי לקשר בין חשבונות הלקוחות ב-Google Cloud Marketplace לבין משאבי הלקוחות שלכם.

אישור החשבון

כדי לאשר את הבקשה לחשבון, מריצים את הפקודה הבאה:

~/gcp-marketplace-integrated-saas/python3$ python3 -m impl.step_2_account.app

קוד לדוגמה לאישור חשבון נמצא ב- impl/step_2_account.

ההטמעה לדוגמה משתמשת בProcurement class, שמטפל באינטראקציות עם Procurement API. אלה השיטות get_account() ו-approve_account() שלו:

step_2_account/app.py

def _get_account_name(self, account_id):
    return 'providers/DEMO-{}/accounts/{}'.format(PROJECT_ID,
                                                  account_id)

def get_account(self, account_id):
    """Gets an account from the Procurement Service."""
    name = self._get_account_name(account_id)
    request = self.service.providers().accounts().get(name=name)
    try:
        response = request.execute()
        return response
    except HttpError as err:
        if err.resp.status == 404:
            return None

def approve_account(self, account_id):
    """Approves the account in the Procurement Service."""
    name = self._get_account_name(account_id)
    request = self.service.providers().accounts().approve(
        name=name, body={'approvalName': 'signup'})
    request.execute()

ב-codelab הזה, מזהה הספק בשירות הרכש הוא DEMO-YOUR_PROJECT_ID, כאשר YOUR_PROJECT_ID הוא הפרויקט שיצרתם. כשמבצעים אינטראקציה עם Procurement API, שם החשבון צריך להיות בפורמט הבא:

providers/DEMO-YOUR_PROJECT_ID/accounts/account-id

לאחר מכן מאשרים הרשאה, שהיא תיעוד של הרכישה של הלקוח.

6. אישור הזכאות

כשלקוח בוחר תוכנית מינוי ב-Google Cloud Marketplace, נוצר חשבון ואז נוצרת מיד בקשה חדשה להרשאה. הזכאות מייצגת רכישה של שירות. כדי שהלקוח יוכל להתחיל להשתמש בשירות, אתם צריכים לאשר את בקשת ההרשאה ואז להגדיר את השירות כדי שהלקוח יוכל להתחיל להשתמש בו.

כשהאפליקציה לדוגמה מקבלת הודעה מ-Cloud Pub/Sub עם eventType ENTITLEMENT_CREATION_REQUESTED, הזכאות מאושרת והאפליקציה צריכה להמתין להודעה ENTITLEMENT_ACTIVE כדי לתעד את הזכאות במסד הנתונים, ואז להגדיר את המשאבים עבור הלקוח.

כדי ליצור את ההרשאה, מריצים את הפקודה הבאה:

~/gcp-marketplace-integrated-saas/python3$ python3 -m impl.step_3_entitlement_create.app

הקוד לאישור הזכאות מופיע בדוגמה להטמעה.

בשלב הבא, מטפלים במצבים שבהם לקוח מבקש לשנות את תוכנית המינוי שלו.

7. אישור שינויים בהרשאה

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

אם לשירות שלכם יש רק תוכנית אחת, דלגו אל טיפול ברכישות שבוטלו.

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

step_4_entitlement_change/app.py

def handleActiveEntitlement(self, entitlement, customer, accountId):
  """Updates the database to match the active entitlement."""

  product = {
      'product_id': entitlement['product'],
      'plan_id': entitlement['plan'],
  }

  if 'consumerId' in entitlement:
    product['consumer_id'] = entitlement['consumerId']

  customer['products'][entitlement['product']] = product

  self.db.write(accountId, customer)

הקטע הבא בודק אם הערך של eventType הוא ENTITLEMENT_PLAN_CHANGE_REQUESTED או ENTITLEMENT_PLAN_CHANGED:

step_4_entitlement_change/app.py

elif eventType == 'ENTITLEMENT_PLAN_CHANGE_REQUESTED':
  if state == 'ENTITLEMENT_PENDING_PLAN_CHANGE_APPROVAL':
    # Don't write anything to our database until the entitlement becomes
    # active within the Procurement Service.
    self.approveEntitlementPlanChange(id, entitlement['newPendingPlan'])
    return True

elif eventType == 'ENTITLEMENT_PLAN_CHANGED':
  if state == 'ENTITLEMENT_ACTIVE':
    # Handle an active entitlement after a plan change.
    self.handleActiveEntitlement(entitlement, customer, accountId)
    return True

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

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

אפשר לראות את הקוד שבודק ומאשר שינויים בהרשאות בהטמעה לדוגמה.

בשלב הבא, אתם מטפלים במצבים שבהם לקוחות מבטלים את הרכישות שלהם.

8. טיפול ברכישות שבוטלו

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

כשלקוח מבטל את הרכישה, נשלחת הודעה עם eventType ENTITLEMENT_PENDING_CANCELLATION. אם הגדרתם את המוצר לעיבוד ביטולים באופן מיידי, הודעה עם eventType ENTITLEMENT_CANCELLED תישלח זמן קצר לאחר מכן.

step_5_entitlement_cancel/app.py

elif eventType == 'ENTITLEMENT_CANCELLED':
  # Clear out our records of the customer's plan.
  if entitlement['product'] in customer['products']:
    del customer['products'][entitlement['product']]

  ### TODO: Turn off customer's service. ###
  self.db.write(accountId, customer)
  return True

elif eventType == 'ENTITLEMENT_PENDING_CANCELLATION':
  # Do nothing. We want to cancel once it's truly canceled. For now it's
  # just set to not renew at the end of the billing cycle.
  return True

elif eventType == 'ENTITLEMENT_CANCELLATION_REVERTED':
  # Do nothing. The service was already active, but now it's set to renew
  # automatically at the end of the billing cycle.
  return True

השירות שלכם צריך להמתין להודעה ENTITLEMENT_CANCELLED כדי להסיר את ההרשאה ממסד הנתונים ולהשבית את השירות עבור הלקוח.

אחרי ביטול ההרשאה, היא נמחקת מהמערכות של Google, ונשלחת הודעה עם eventType ENTITLEMENT_DELETED:

step_5_entitlement_cancel/app.py

elif eventType == 'ENTITLEMENT_DELETED':
  # Do nothing. Entitlements can only be deleted when they are already
  # cancelled, so our state is already up-to-date.
  return True

בדוגמה להטמעה אפשר לראות את הקוד לביטול הרשאה.

9. שליחת דוחות שימוש

בחלק מהשירותים יש רכיבים שמבוססים על שימוש, ולכן Google צריכה לדעת על השימוש של הלקוחות בשירות כדי לחייב אותם בסכום הנכון. השירות שלכם צריך לדווח על השימוש דרך Google Service Control API.

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

מידע מפורט על שליחת דוחות שימוש זמין במסמכי ההצטרפות.

דוחות השימוש צריכים להישלח ל-Google Service Control API מדי שעה. ב-codelab הזה, הדוחות נשלחים באמצעות סקריפט שאפשר לתזמן אותו כעבודת cron. הסקריפט שומר את השעה של דוח השימוש האחרון במסד הנתונים, ומשתמש בה כשעת ההתחלה למדידת השימוש.

הסקריפט בודק כל לקוח פעיל של השירות, ושולח דוח שימוש ל-Google Service Control באמצעות השדה consumer_id של הרשאת הלקוח. לאחר מכן הסקריפט מעדכן את הרשומה במסד הנתונים של הלקוח כך שהערך של last_report_time יהיה שווה לזמן הסיום של דוח השימוש שנשלח זה עתה.

ב-Google Service Control יש שתי שיטות: check ו-report. תמיד צריך לקרוא לפונקציה הראשונה מיד לפני קריאה לפונקציה השנייה. אם יש שגיאות בשירות הראשון, צריך להשבית את השירות של הלקוח עד שהשגיאות יתוקנו.

כל השימוש בזכאות מסוימת משויך לusageReportingId אחד. עם זאת, כשמדובר במוצרי SaaS, השימוש הזה משויך לפריט השורה [Charges not specific to a project] בחיוב ב-Google Cloud. אם המוצר שלכם מסוג SaaS עשוי להיות משותף באופן נרחב בארגון של לקוח, ואתם רוצים לתמוך בשיוך עלויות, מומלץ שכל השירותים שלכם יכללו את השדה האופציונלי userLabels בדוח השימוש שלהם operation.

מערכת Google Cloud Marketplace שומרת את מפתחות התוויות cloudmarketplace.googleapis.com/resource_name ו-cloudmarketplace.googleapis.com/container_name. התוויות האלה נועדו לתעד את ההקשר של השימוש בהיררכיית המשאבים והשירותים המקוריים שלכם. השמות שהוקצו למשאבים האלה על ידי הלקוח ייכללו כערכי תוויות בדוחות השימוש. מומלץ לכלול את התוויות האלה בדוחות השימוש כברירת מחדל.

מפתח התווית

ערך התווית

תיאור

cloudmarketplace.googleapis.com/resource_name

RESOURCE_NAME

השם של המשאב שמשויך למדד שימוש.

cloudmarketplace.googleapis.com/container_name

CONTAINER_NAME

השם של מאגר משאבים.

בקטע הקוד הבא מדווח על השימוש באפליקציית ההדגמה, והשימוש במוצר ה-SaaS משויך למשאב שהוקצה ללקוח בשם products_db. ב-codelab הזה, service_name הוא isaas-codelab.mp-marketplace-partner-demos.appspot.com.

operation = {
  'operationId': '<UUID>',
  'operationName': 'Codelab Usage Report',
  'consumerId': 'project_number:<Project Number>',
  'startTime': '<Timestamp>',
  'endTime': '<Timestamp>',
  'metricValues': [{
      'int64Value': 100,
  }],
  'userLabels': {
    'cloudmarketplace.googleapis.com/container_name': 'saas-storage-solutions',
    'cloudmarketplace.googleapis.com/resource_name': 'products_db'
  }
}

service.services().report(
    serviceName=service_name, body={
        'operations': [operation]
    }).execute()
product['last_report_time'] = end_time
database.write(customer_id, customer)

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

~/gcp-marketplace-integrated-saas/python3$ python3 -m impl.step_6_usage_reporting.report isaas-codelab.mp-marketplace-partner-demos.appspot.com

10. מעולה!

למדתם איך פתרון SaaS יכול להשתלב עם Google Cloud Marketplace כדי לנהל חשבונות והרשאות של לקוחות, ולדווח על שימוש בשירות. שלבי השילוב המלאים מפורטים במסמכי התיעוד בנושא שילוב עם ה-Backend.

הסרת המשאבים

אם אתם לא מתכוונים להשתמש יותר במשאבים האלה, אתם יכולים למחוק אותם:

  • המינוי ל-Cloud Pub/Sub
  • חשבון השירות והמפתחות שלו
  • אופציונלי: הפרויקט שיצרתם
  • אופציונלי: החשבון לחיוב שיצרתם

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

שילוב הקצה הקדמי

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

מידע על שילוב חזית האפליקציה זמין במסמכי התיעוד של Google Cloud Marketplace.

מידע נוסף על הצעת פתרונות SaaS

סקירה כללית על הצעת פתרונות SaaS ב-Google Cloud Marketplace זמינה במאמר בנושא הצעת פתרונות SaaS.