ניהול הגדרות השירות

בדף הזה מוסבר איך לנהל הגדרות שירות באמצעות Service Infrastructure.

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

ה-methods של Service Management API שבדרך כלל מעורבים בניהול הגדרות השירות:

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

לפני שמיישמים את הדוגמאות במדריך הזה, חשוב לסיים את ההגדרה הראשונית לפי ההוראות במאמר תחילת השימוש ב-Service Management API.

שליחת קובצי מקור של הגדרת שירות

כדי לעדכן את הגדרת השירות, צריך לשלוח ל-Service Management API רשימה של קובצי המקור של הגדרות השירות, והשרת יהדר (compile) אותם להגדרת שירות תקפה.

קובצי המקור יכולים להיות בפורמטים הבאים:

ה-Service Management API לא תומך בקובצי .proto. עליכם ליצור מתארי protobuf מקובצי .proto לפני שתשלחו אותם. כדי ליצור קובצי מתאר, השתמשו בפקודה הבאה:

$ protoc hello.proto --include_source_info --include_imports --descriptor_set_out=service.descriptors *.proto

הדרך המומלצת לשליחת קובצי מקור של הגדרת שירות היא באמצעות CLI של gcloud.

$ gcloud auth login
$ gcloud endpoints services deploy [a list of service configuration source files]

אפשר גם לקרוא ישירות ל-Service Management API כדי לשלוח קובצי מקור. לדוגמה, אם קיימת הגדרת OpenAPI הבאה (hello.json):

{
  "swagger": "2.0",
  "info": {
    "title": "Hello Endpoints API.",
    "description": "Hello Endpoints API.",
    "version": "v1"
  },
  "host": "endpointsapis.appspot.com",
  "schemes": ["https"],
  "paths": {
    "/v1/hello": {
      "get": {
        "tags": ["endpointsapis"],
        "operationId": "GetHello",
        "description": "Returns \"Hello\" with given name in the response.",
        "parameters": [
          {
            "name": "name",
            "description": "Name to be greeted.",
            "in": "query",
            "type": "string"
          }
        ],
        "responses": {
          "default": {
            "description": "Successful operation",
            "schema": {
              "$ref": "#/definitions/GetHelloResponse"
            }
          }
        }
      }
    }
  },
  "definitions": {
    "GetHelloResponse": {
      "description": "Response message for GetHello method.",
      "type": "object",
      "properties": {
        "response": {
          "description": "String of \"Hello \" + `name` provided in the request.",
          "type": "string"
        }
      }
    }
  }
}

כדי לשלוח את המפרט של OpenAPI אפשר לבצע את הקריאה הבאה ל-API:

$ gcurl -d "
{
  'serviceName': 'endpointsapis.appspot.com',
  'configSource':
  {
    'files': [
      {
        'fileContents': '$(base64 hello.json | sed ':a;N;$!ba;s/\n//g')',
        'fileType': 'OPEN_API_JSON',
        'filePath': 'hello.json',
      }
    ]
  }
}" https://servicemanagement.googleapis.com/v1/services/endpointsapis.appspot.com/configs:submit
{
  "name": "operations/serviceConfigs.endpointsapis.appspot.com:a7651c15-9017-4274-b065-d644cc337847",
  "metadata": {
    "@type": "type.googleapis.com/google.api.servicemanagement.v1.OperationMetadata",
    "resourceNames": [
      "services/endpointsapis.appspot.com/configs/2016-07-29r10"
    ],
    "startTime": "2016-07-29r10T23:59:21.081Z",
    "persisted": true
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.api.servicemanagement.v1.SubmitConfigSourceResponse",
    "serviceConfig": {
      "name": "endpointsapis.appspot.com",
      "title": "Hello Endpoints API.",
  ...
}

יצירת דוחות של הגדרת שירות

לפני ששולחים גרסה חדשה של הגדרת שירות, כדאי לקרוא ל-method ‏services.generateConfigReport כדי לקבל דוח על השינויים ביחס לגרסה קיימת של הגדרת השירות. תוכלו לציין את הגרסה להשוואה באמצעות השדה old_config שמופיע בבקשה, או פשוט לדלג על השדה הזה כדי ליצור דוח ביחס לגרסה העדכנית ביותר של הגדרת השירות.

בהנחה שקובץ התצורה החדש של OpenAPI נקרא hello.json, תוכלו להריץ את הפקודה הבאה:

$ gcurl -d "
{
  'newConfig':
  {
    '@type': 'type.googleapis.com/google.api.servicemanagement.v1.ConfigSource',
    'files': [
      {
        'fileContents': '$(base64 hello.json | sed ':a;N;$!ba;s/\n//g')',
        'fileType': 'OPEN_API_JSON',
        'filePath': 'hello.json',
      }
    ],
  }
}" https://servicemanagement.googleapis.com/v1/services:generateConfigReport

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

# Generate config report for the local configuration from `/tmp/hello.json`
# and the configuration version `2016-07-29r10`.
$ gcurl -d "
{
  'newConfig':
  {
    '@type': 'type.googleapis.com/google.api.servicemanagement.v1.ConfigSource',
    'files': [
      {
        'fileContents': '$(base64 hello.json | sed ':a;N;$!ba;s/\n//g')',
        'fileType': 'OPEN_API_JSON',
        'filePath': 'hello.json',
      }
    ],
  },
  'oldConfig':
  {
    '@type': 'type.googleapis.com/google.api.servicemanagement.v1.ConfigRef',
    'name': 'services/endpointsapis.appspot.com/configs/2016-07-29r10'
  }
}" https://servicemanagement.googleapis.com/v1/services:generateConfigReport

הצגת גרסאות קודמות של הגדרת שירות

ב-Service Management API נשמרת היסטוריית הגרסאות של הגדרות השירות שנשלחו. אפשר לקבל פירוט שלהן או לאחזר גרסה ספציפית באמצעות ‎services.configs.list method‎ או ‎services.configs.get method‎, כפי שמתואר בפקודות הבאות:

# List the service configuration history for a managed service.
$ gcurl https://servicemanagement.googleapis.com/v1/services/endpointsapis.appspot.com/configs
{
  "serviceConfigs": [
    {
      "name": "endpointsapis.appspot.com",
      "title": "Hello Endpoints API",
      "id": "2016-07-16r1",
      ...
    },
    {
      "name": "endpointsapis.appspot.com",
      "title": "Hello Endpoints API",
      "id": "2016-07-16r0",
      ...
    }
  ]
}

# Get a specific version of the service configuration for a managed service.
$ gcurl https://servicemanagement.googleapis.com/v1/services/endpointsapis.appspot.com/configs/2016-07-16r0
{
  "name": "endpointsapis.appspot.com",
  "title": "Hello Endpoints API",
  "id": "2016-07-16r0",
  ...
}