تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

استخدام واجهة برمجة التطبيقات

مقدمة

هذا المستند مخصص لمطوّري البرامج الذين يريدون كتابة مكتبات العملاء ومكوّنات IDE الإضافية وأدوات أخرى للتفاعل مع Google APIs. تتيح لك خدمة استكشاف واجهات برمجة التطبيقات الخاصة بـ Google تنفيذ كل ما سبق من خلال الكشف عن البيانات الوصفية القابلة للقراءة آليًا حول واجهات برمجة تطبيقات Google الأخرى من خلال واجهة برمجة تطبيقات بسيطة. يقدِّم هذا الدليل نظرة عامة على كل قسم من مستندات "اقتراحات"، بالإضافة إلى نصائح مفيدة حول كيفية استخدام المستند.

جميع الطلبات المُرسَلة إلى واجهة برمجة التطبيقات هي طلبات REST لم تتم مصادقتها ومستندة إلى JSON. وتستخدم هذه الطلبات طلبات طبقة المقابس الآمنة، أي تبدأ عناوين URL بـ https.

إذا لم تكن على دراية بمفاهيم خدمة استكشاف واجهات برمجة التطبيقات الخاصة بخدمة Google APIs، يجب قراءة البدء قبل البدء في الترميز.

تنسيق مستند "اقتراحات"

يقدّم هذا القسم نظرة عامة على مستند "اقتراحات".

تستخدم جميع الأمثلة أدناه المستند أثناء التصفّح من Google Cloud Service Management API. يمكنك تحميل مستند أثناء التصفّح لواجهة برمجة تطبيقات إدارة خدمة Google Cloud Service من خلال تنفيذ طلب GET هذا:

GET https://servicemanagement.googleapis.com/$discovery/rest?version=v1

يتضمّن تنسيق المستند أثناء التصفّح معلومات تندرج ضمن ست فئات رئيسية:

الوصف الأساسي لواجهة برمجة التطبيقات.
معلومات المصادقة لواجهة برمجة التطبيقات.
تفاصيل المورد والمخطط التي تصف بيانات واجهة برمجة التطبيقات.
تفاصيل حول طرق واجهة برمجة التطبيقات
معلومات عن أي ميزات مخصّصة تتيحها واجهة برمجة التطبيقات
المستندات المضمّنة التي تصف العناصر الرئيسية لواجهة برمجة التطبيقات.

يتم وصف كل قسم من أقسام مستند "اقتراحات". لمزيد من التفاصيل عن كل موقع، يُرجى الرجوع إلى مستندات المراجع.

وصف واجهة برمجة التطبيقات الأساسية

يحتوي مستند "اقتراحات" على مجموعة من المواقع الخاصة بواجهة برمجة التطبيقات:

"kind": "discovery#restDescription",
"name": "servicemanagement",
"version": "v1",
"title": "Service Management API",
"description": "Google Service Management allows service producers to publish their services on Google Cloud Platform so that they can be discovered and used by service consumers.",
"protocol": "rest",
"rootUrl": "https://servicemanagement.googleapis.com/. Root URL under which all API services live",
"servicePath": "",

تحتوي هذه المواقع على مستوى واجهة برمجة التطبيقات على تفاصيل عن إصدار معيّن من واجهة برمجة التطبيقات، بما في ذلك name وversion وtitle وdescription. دائمًا ما يكون لقيمة protocol قيمة rest، لأن خدمة Discovery API لا تتوافق إلا مع طرق RESTful للوصول إلى واجهات برمجة التطبيقات.

يشير الحقل servicePath إلى بادئة المسار لإصدار واجهة برمجة التطبيقات المحدّد.

المصادقة

يحتوي القسم auth على تفاصيل حول نطاقات مصادقة OAuth 2.0 لواجهة برمجة التطبيقات. للتعرّف على مزيد من المعلومات عن كيفية استخدام النطاقات مع OAuth 2.0، يُرجى الانتقال إلى استخدام OAuth 2.0 للوصول إلى واجهات برمجة تطبيقات Google.

يحتوي القسم auth على القسمين oauth2 وscopes المتداخلين. يمثّل القسم scopes عملية ربط المفتاح/القيمة من قيمة النطاق إلى مزيد من التفاصيل حول النطاق:

"auth": {
  "oauth2": {
    "scopes": {
      "https://www.googleapis.com/auth/cloud-platform.read-only": {
        "description": "View your data across Google Cloud Platform services"
      },
      "https://www.googleapis.com/auth/service.management.readonly": {
        "description": "View your Google API service configuration"
      },
      "https://www.googleapis.com/auth/cloud-platform": {
        "description": "View and manage your data across Google Cloud Platform services"
      },
      "https://www.googleapis.com/auth/service.management": {
        "description": "Manage your Google API service configuration"
      }
    }
  }
}

يحدّد القسم auth نطاقات واجهة برمجة تطبيقات معيّنة فقط. لمعرفة كيفية ارتباط هذه النطاقات بطريقة واجهة برمجة تطبيقات، يمكنك الرجوع إلى قسم الطرق أدناه.

المراجع والمخططات

تعمل عمليات واجهة برمجة التطبيقات على كائنات البيانات التي تحمل الاسم resources. يستند مستند Discovery إلى مفهوم الموارد. يحتوي كل مستند من "اقتراحات" على قسم resources من المستوى الأعلى الذي يجمع كل الموارد المرتبطة بواجهة برمجة التطبيقات. على سبيل المثال، تتضمّن Google Cloud Service Management API موردًا services وموردًا واحدًا (operations) ضمن المستوى الأعلى resources، ويحتوي مورد services على ثلاثة موارد فرعية، وهي configs وrollouts وconsumers:

"resources": {
  "services": {
    // Methods and sub-resources associated with the services resource
    "configs": {
      // Methods and sub-resources associated with the services.configs resource
    },
    "rollouts": {
      // Methods and sub-resources associated with the services.rollouts resource
    },
    "consumers": {
      // Methods and sub-resources associated with the services.consumers resource
    }
  },
  "operations": {
    // Methods and sub-resources associated with the operations resource
  }
}

داخل كل قسم من أقسام المورد هناك طرق مرتبطة بهذا المورد. على سبيل المثال، تتضمّن Google Cloud Service Management API ثلاث طرق مرتبطة بمورد services.rollouts: get وlist وcreate.

توضّح المخطّطات الشكل الذي تظهر به الموارد في واجهة برمجة التطبيقات. يحتوي كل مستند أثناء التصفّح على قسم schemas من المستوى الأعلى، والذي يتضمن زوجًا من الاسم/القيمة من رقم تعريف المخطط إلى العنصر. أرقام تعريف المخططات فريدة لكل واجهة برمجة تطبيقات، ويتم استخدامها لتعريف المخطط بشكل فريد في القسم methods من مستند أثناء التصفّح:

"schemas": {
  "Rollout": {
    // JSON Schema of the Rollout resource.
  }
}

تستخدم خدمة Discovery API JSON Schema project-03 في تمثيلات المخططات. في ما يلي مقتطف لمخطط JSON لمورد عنوان URL، إلى جانب مورد استجابة فعلي:

طرح مخطط JSON للموارد:

الاستجابة الفعلية لمصدر عملية الطرح:

{
  "Rollout": {
    "id": "Rollout",
    "type": "object",
    "description": "...",
    "properties": {
      "serviceName": {
        "type": "string",
        "description": "..."
      },
      "rolloutId": {
        "type": "string",
        "description": "..."
      },
      "status": {
        "type": "string",
        "enum": [
          "ROLLOUT_STATUS_UNSPECIFIED",
          "IN_PROGRESS",
          "SUCCESS",
          "CANCELLED",
          "FAILED",
          "PENDING",
          "FAILED_ROLLED_BACK"
        ],
        "enumDescriptions": [
          ...
        ],
        "description": "..."
      },
      "trafficPercentStrategy": {
        "$ref": "TrafficPercentStrategy",
        "description": "..."
      },
      "deleteServiceStrategy": { ... },
      "createTime": { ... },
      "createdBy": { ... }
    }
  }
}

{
  "serviceName": "discovery.googleapis.com",
  "rolloutId": "2020-01-01R0",
  "status": "SUCCESS",
  "trafficPercentStrategy":{
    "precentages":{
      "2019-12-01R0": 70.00,
      "2019-11-01R0": 30.00
    }
  }
}

توضّح الحقول بالخط الغامق الربط بين مخطط JSON والاستجابة الفعلية.

وقد تتضمّن المخططات أيضًا إشارات إلى مخططات أخرى. إذا كنت تعمل على إنشاء مكتبة عملاء، يمكن أن يساعدك ذلك في وضع نماذج فعّالة لعناصر واجهة برمجة التطبيقات في فئات نماذج البيانات. في المثال Rollout أعلاه، تمثّل السمة trafficPercentStrategy مرجعًا لمخطّط يتضمّن رقم التعريف TrafficPercentStrategy. إذا اطّلعت على القسم "schemas"، سيظهر لك مخطط TrafficPercentStrategy. يمكن استبدال قيمة هذا المخطط بالخاصية trafficPercentStrategy في المورد Rollout (لاحظ أن بنية $ref تأتي من مواصفات مخطط JSON).

قد تشير الأساليب أيضًا إلى المخططات عند الإشارة إلى نصوص الطلبات والاستجابة. يمكنك الرجوع إلى قسم الطرق للحصول على مزيد من التفاصيل.

الطُرق

يعتمد أساس مستند Discovery على الطرق. الطرق هي العمليات التي يمكن تنفيذها على واجهة برمجة تطبيقات. يمكنك العثور على القسم methods في أقسام مختلفة من مستند "اقتراحات"، بما في ذلك المستوى الأعلى (الذي نُطلق عليه الطرق على مستوى واجهة برمجة التطبيقات) أو على المستوى resources.

"methods": {
  // API-level methods
}
"resources": {
  "resource1": {
    "methods": {
      // resource-level methods
    }
    "resources": {
      "nestedResource": {
        "methods": {
          // methods can even be found in nested-resources
        }
      }
    }
  }
}

بينما قد تحتوي واجهة برمجة التطبيقات على طرق على مستوى واجهة برمجة التطبيقات، يجب أن يحتوي المورد على قسم methods.

يمثّل كل قسم methods ربطًا رئيسيًا/قيمة من اسم الطريقة إلى تفاصيل أخرى عن تلك الطريقة. ويوضّح المثال التالي ثلاث طرق، get وlist وcreate:

"methods": {
  "get": { //details about the "get" method },
  "list": { //details about the "list" method },
  "create": { //details about the "create" method }
}

وأخيرًا، يوضح كل قسم من هذه الطرق تفاصيل مختلفة عن هذه الطريقة. في ما يلي مثال على طريقة get:

"get": {
  "id": "servicemanagement.services.rollouts.get",
  "path": "v1/services/{serviceName}/rollouts/{rolloutId}",
  "flatPath": "v1/services/{serviceName}/rollouts/{rolloutId}",
  "httpMethod": "GET",
  "description": "Gets a service configuration rollout.",
  "response": { "$ref": "Rollout" },
  "parameters": { // parameters related to the method },
  "parameterOrder": [ // parameter order related to the method ],
  "scopes": [ // OAuth 2.0 scopes applicable to this method ],
  "mediaUpload": { // optional media upload information },
},

يتضمن هذا القسم تفاصيل عامة للطريقة مثل ID فريدة لتحديد الطريقة، وhttpMethod للاستخدام، وpath للطريقة (للحصول على تفاصيل حول كيفية استخدام السمة path لحساب عنوان URL للطريقة الكاملة، راجع قسم إنشاء طلب). بالإضافة إلى سمات السمات العامة هذه، هناك بعض الخصائص التي تربط الطريقة بأقسام أخرى في مستند "اقتراحات".

المناظير

يحتوي قسم auth المحدّد سابقًا في هذه المستند على معلومات عن جميع النطاقات التي تتيحها واجهة برمجة تطبيقات معيّنة. إذا كانت إحدى الطرق متوافقة مع أحد هذه النطاقات، ستحتوي على مصفوفة نطاقات. هناك إدخال واحد في هذه المصفوفة لكل نطاق يتوافق مع هذه الطريقة. على سبيل المثال، يبدو قسم scopes من طريقة Google Cloud Service Management API get كما يلي:

"scopes": [
  "https://www.googleapis.com/auth/cloud-platform",
  "https://www.googleapis.com/auth/cloud-platform.read-only",
  "https://www.googleapis.com/auth/service.management",
  "https://www.googleapis.com/auth/service.management.readonly"
]

يُرجى ملاحظة أن اختيار نطاق المصادقة لاستخدامه في تطبيقك يعتمد على عوامل مختلفة، مثل الطرق التي يتم طلبها والمعلَمات التي يتم إرسالها مع الطريقة. لذلك، يصبح قرار النطاق الذي سيتم استخدامه لمطوّر البرامج. وتوضّح أثناء التصفّح فقط النطاقات الصالحة لطريقة معيّنة.

الطلب والرد

إذا كانت الطريقة تحتوي على طلب أو ردّ، سيتم توثيق ذلك في القسمين request أو response على التوالي. في المثال get أعلاه، تحتوي الطريقة على نص response:

"response": {
  "$ref": "Rollout"
}

تشير البنية أعلاه إلى أنه يتم تحديد نص الاستجابة بواسطة مخطط JSON برقم تعريف Rollout. يمكن العثور على هذا المخطط في قسم المخططات ذات المستوى الأعلى. تستخدم نصوص الطلب والاستجابة بنية $ref للإشارة إلى المخططات.

المعلَمات

إذا كانت إحدى الطرق تحتوي على معلّمات يجب أن يحدّدها المستخدم، يتم توثيق هذه المعلّمات في القسم parameters على مستوى الطريقة. يحتوي هذا القسم على ربط مفتاح/قيمة لاسم المعلمة لمزيد من التفاصيل حول هذه المعلمة:

"parameters": {
  "serviceName": {
    "type": "string",
    "description": "Required. The name of the service.",
    "required": true,
    "location": "path"
  },
  "rolloutId": { ... }
},
"parameterOrder": [
  "serviceName",
  "rolloutId"
]

في المثال أعلاه، هناك معلّمتَان لطريقة get:serviceName وrolloutId. ويمكن أن تنتقل المعلّمات إلى path أو عنوان URL query، بينما تشير الخاصية location إلى المكان الذي يجب أن تضع فيه مكتبة العميل المعلّمة.

وهناك العديد من الخصائص الأخرى التي تصف المعلَمة، بما في ذلك بيانات المعلّمة type (مفيدة للغات مكتوبة بشدة)، وما إذا كانت المعلّمة required، وما إذا كانت المعلّمة تعدادًا. راجِع الدليل المرجعي للاطّلاع على مزيد من التفاصيل عن المواقع.

ترتيب المعلَمات

هناك العديد من الطرق لمكتبات العملاء لتنظيم واجهاتها. تتمثل إحدى الطرق في استخدام طريقة مع كل معلمة من واجهات برمجة التطبيقات في توقيع الطريقة. ومع ذلك، نظرًا لأن تنسيق JSON غير مُرتَّب، من الصعب معرفة كيفية ترتيب المعلَمات آليًا في توقيع الطريقة. توفّر المصفوفة parameterOrder ترتيبًا ثابتًا للمعلَمات لإجراء الطلبات. تسرد المصفوفة اسم كل معلمة بترتيب الأهمية. ويمكن أن تحتوي هذه المعلمة على مسار أو معلمات طلب بحث، ولكن كل معلمة في المصفوفة مطلوبة. في المثال أعلاه، قد يظهر توقيع طريقة Java على النحو التالي:

public Rollout get(String serviceName, String rolloutId, Map<String, Object> optionalParameters);

تكون القيمة الأولى في المصفوفة parameterOrder، serviceName، هي أيضًا العنصر الأول في توقيع الطريقة. في حال توفّر معلّمات أخرى في المصفوفة parameterOrder، سيتم نقلها بعد المعلّمة serviceName. بما أنّ المصفوفة parameterOrder تحتوي على المعلّمات المطلوبة فقط، من المفيد تضمين طريقة للمستخدمين لتحديد معلّمات اختيارية أيضًا. يجري المثال أعلاه إجراءً باستخدام الخريطة optionalParameters.

تحميل الوسائط

إذا كانت إحدى الطرق تتيح تحميل الوسائط، مثل الصور أو الصوت أو الفيديو، سيتم توثيق الموقع والبروتوكولات المتوافقة لتحميل هذه الوسائط في القسم mediaUpload. يتضمّن هذا القسم تفاصيل عن بروتوكولات التحميل المتوافقة ومعلومات عن أنواع الوسائط التي يمكن تحميلها:

"supportsMediaUpload": true,
"mediaUpload": {
  "accept": [
    "image/*"
  ],
  "maxSize": "10MB",
  "protocols": {
    "simple": {
      "multipart": true,
      "path": "/upload/storage/v1beta1/b/{bucket}/o"
    },
    "resumable": {
     "multipart": true,
     "path": "/resumable/upload/storage/v1beta1/b/{bucket}/o"
    }
  }
}

في المثال أعلاه، السمة supportsMediaUpload هي قيمة منطقية تحدد ما إذا كانت الطريقة تسمح بتحميل الوسائط. وإذا كانت القيمة صحيحة، يوثّق القسم mediaUpload أنواع الوسائط التي يمكن تحميلها.

تعرض السمة accept قائمة بنطاقات الوسائط التي تحدّد أنواع MIME التي يمكن تحميلها. ستقبل نقطة النهاية المعروضة في المثال أعلاه أي تنسيق صورة.

تستخدم الخاصية maxSize الحد الأقصى لحجم التحميل. تكون القيمة سلسلة بوحدات ميغابايت أو غيغابايت أو تيرابايت. في المثال أعلاه، تقتصر عمليات التحميل على 10 ميغابايت بحدٍ أقصى. لاحظ أن هذه القيمة لا تعكس حصة مساحة التخزين المتبقية للمستخدم الفردي لواجهة برمجة التطبيقات هذه، لذلك حتى إذا كان التحميل يقل عن maxSize، يجب أن تظل مكتبة العميل جاهزة لمعالجة التحميل الذي فشل بسبب عدم توفر مساحة كافية.

يسرد القسم protocols بروتوكولات التحميل المتوافقة مع إحدى الطرق. يعمل البروتوكول simple فقط على نشر الوسائط إلى نقطة النهاية المحددة في طلب HTTP واحد. يشير بروتوكول resumable إلى أن نقطة النهاية المقدَّمة في معرّف الموارد المنتظم (URI) لنظام التشغيل path تتوافق مع بروتوكول التحميل القابل للاستئناف. إذا كانت السمة multipart هي true، تقبل نقطة النهاية عمليات التحميل المتعدّدة الأجزاء، ما يعني أنّه يمكن تضمين كل من طلب JSON والوسائط معًا في نص متعدد أو مرتبط ثم إرسالهما معًا. يُرجى العِلم أنّ البروتوكولَين simple وresumable قد يتيحان تحميل عدة أجزاء.

السمة path هي نموذج معرّف موارد منتظم (URI) ويجب توسيعه مثل السمة path للطريقة، كما هو موضّح في القسمإنشاء طلب.

تنزيل الوسائط

إذا كانت هناك طريقة تتيح تنزيل الوسائط، مثل الصور أو الملفات الصوتية أو الفيديوهات، ستتم الإشارة إلى ذلك في المعلَمة supportsMediaDownload:

"supportsMediaDownload": true,

عند تنزيل الوسائط، يجب ضبط معلَمة طلب البحث alt على media في عنوان URL للطلب.

إذا كانت السمة useMediaDownloadService لطريقة واجهة برمجة التطبيقات هي true، يمكنك إدراج /download قبل servicePath لتجنُّب إعادة التوجيه. على سبيل المثال، مسار التنزيل هو /download/youtube/v3/captions/{id} إذا كانت سلسلة servicePath وpath هي /youtube/v3/captions/{id}. ويُنصح بإنشاء عنوان URL لتنزيل الوسائط باستخدام العلامة /download حتى إذا كانت السمة useMediaDownloadService غير صحيحة.

المعلمات الشائعة

يحتوي مستند أثناء التصفّح على المستوى الأعلى على السمة parameters. يشبه هذا القسم قسم المعلّمات لكل طريقة، ولكن يمكن تطبيق هذه المعلمات على أي طريقة في واجهة برمجة التطبيقات.

على سبيل المثال، يمكن أن تتضمّن واجهات الحصول على واجهة برمجة التطبيقات لإدارة خدمة Google Cloud Service أو إدراجها أو سردها معلّمة prettyPrint في معلّمات الطلب، ما سيؤدي إلى تنسيق الاستجابة لكل هذه الطرق بتنسيق يمكن للمستخدمين قراءته. في ما يلي قائمة بالمَعلمات الشائعة:

المعلمة	المعنى	ملاحظات	قابلية التطبيق
`access_token`	رمز OAuth 2.0 المميز للمستخدم الحالي.	إحدى الطرق الممكنة لتقديم رمز OAuth 2.0 المميز.
`alt`	تنسيق البيانات للاستجابة.	القيم الصالحة: `json` و`atom` و`csv`. القيمة التلقائية: تختلف حسب واجهة برمجة التطبيقات. لا تتوفر كل القيم لكل واجهة برمجة تطبيقات.	ينطبق هذا الإجراء على جميع العمليات لجميع الموارد.
`callback`	دالة معاودة الاتصال.	اسم دالة رد اتصال JavaScript التي تستجيب للاستجابة. تُستخدَم في طلبات JavaScript JSON-P.
`fields`	أداة اختيار تحدد مجموعة فرعية من الحقول لتضمينها في الاستجابة.	لمزيد من المعلومات، يُرجى الاطّلاع على وثائق الاستجابة الجزئية. استخدِم هذه البيانات لتحسين الأداء.
`key`	مفتاح واجهة برمجة التطبيقات. (مطلوبة*)	*مطلوب ما لم توفّر رمز OAuth 2.0 المميز. يحدّد مفتاح واجهة برمجة التطبيقات مشروعك، ويتيح لك الوصول إلى واجهة برمجة التطبيقات والحصص والتقارير. يمكنك الحصول على مفتاح واجهة برمجة التطبيقات لمشروعك من وحدة تحكم واجهات برمجة التطبيقات.
`prettyPrint`	تعرض الاستجابة مع المعرّفات وفواصل الأسطر.	لعرض الاستجابة بتنسيق يمكن للمستخدمين قراءته إذا كانت `true`. القيمة التلقائية: تختلف حسب واجهة برمجة التطبيقات. عندما يكون `false` هو، يمكن أن يقلل حجم حمولة الاستجابة، ما قد يؤدي إلى أداء أفضل في بعض البيئات.
`quotaUser`	البديل لـ `userIp`.	يسمح لك هذا الإعداد بفرض حصص لكل مستخدم من تطبيق على الخادم، حتى في الحالات التي يكون فيها عنوان IP غير معروف للمستخدم. ويمكن أن يحدث ذلك، على سبيل المثال، مع التطبيقات التي تشغّل وظائف corn على App Engine نيابة عن المستخدم. ويمكنك اختيار أي سلسلة عشوائية تعرّف المستخدم بشكل فريد، ولكنها تقتصر على 40 حرفًا. تلغي السياسة `userIp` إذا تم توفير كليهما. مزيد من المعلومات حول الحد من الاستخدام.
`userIp`	عنوان IP للمستخدم النهائي الذي يتم إجراء استدعاء واجهة برمجة التطبيقات له.	يتيح لك فرض حصص لكل مستخدم عند استدعاء واجهة برمجة التطبيقات من تطبيق من جانب الخادم. مزيد من المعلومات حول الحد من الاستخدام.

الميزات

هناك بعض الحالات التي تتيح فيها واجهات برمجة التطبيقات الميزات المخصّصة خارج نطاق بقية مستند Discovery. ويتم جمع هذه القيم في المصفوفة features. تحتوي مصفوفة الميزات على تصنيف سلسلة لكل ميزة خاصة متوافقة مع واجهة برمجة التطبيقات. حاليًا، الميزة الوحيدة المتوافقة مع dataWrapper، ولكن قد تكون الميزات الأخرى متاحة في المستقبل.

"features": dataWrapper

تشير الميزة dataWrapper إلى أنه يتم تضمين جميع الطلبات والردود من واجهة برمجة التطبيقات في كائن data JSON. هذه ميزة في واجهات برمجة تطبيقات Google القديمة، ولكن سيتم إيقافها من الآن فصاعدًا. تتيح واجهات برمجة التطبيقات التالية ميزة dataWrapper: الإصدار 1 من المشرف والترجمة بالإصدار 2.

بصفتك مطوِّر برامج في مكتبة العملاء، إذا كانت واجهة برمجة التطبيقات متوافقة مع ميزة "dataWrapper"، يجب تنفيذ ما يلي:

في الطلبات: يمكنك لف مورد الطلب في كائن JSON data.
في الردود: ابحث عن المورد داخل كائن JSON بتنسيق data.

لا تحتوي المخططات في مستند Discovery على برنامج تضمين البيانات، لذا يجب إضافتها بوضوح وإزالتها. على سبيل المثال، لنفترض أن هناك واجهة برمجة تطبيقات بها مورد باسم "Foo" يبدو أنّه:

{
  "id": 1,
  "foo": "bar"
}

قبل إدراج هذا المورد باستخدام واجهة برمجة التطبيقات، يجب وضعه في عنصر بيانات:

{
  "data": {
    "id": 1,
    "foo": "bar"
  }
}

من ناحية أخرى، عندما تتلقى ردًا من واجهة برمجة التطبيقات، فإنها تحتوي أيضًا على برنامج تضمين البيانات:

{
  "data": {
    "id": 1,
    "foo": "bar"
  }
}

للحصول على المورد المحدد بواسطة المخطط، يجب إزالة برنامج تضمين البيانات:

{
  "id": 1,
  "foo": "bar"
}

الوثائق المضمّنة

تتم إضافة تعليقات توضيحية إلى كل مستند من"اقتراحات"مع عدد من الحقول description التي توفّر مستندات مضمّنة لواجهة برمجة التطبيقات. يمكن العثور على الحقول description لعناصر واجهة برمجة التطبيقات التالية:

واجهة برمجة التطبيقات نفسها
نطاقات OAuth
مخططات الموارد
طرق واجهة برمجة التطبيقات
معلّمات الطريقة
القيم المقبولة لمعلّمات معيّنة

تُعد هذه الحقول مفيدة بشكل خاص إذا كنت تريد استخدام خدمة استكشاف واجهات برمجة التطبيقات الخاصة بـ Google لإنشاء مستندات يمكن قراءتها لمكتبة عميل، مثل JavaDoc.

الخطوات اللاحقة

إنشاء مكتبة عملاء