مشاركة عبر

البرنامج التعليمي: إنشاء منتج ونشره

ينطبق على: جميع مستويات إدارة واجهة برمجة التطبيقات

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

تلميح

يمكن لفرق واجهة برمجة التطبيقات استخدام هذه الميزة في مساحات العمل. توفر مساحات العمل وصولا إداريا معزولا إلى واجهات برمجة التطبيقات وبيئات وقت تشغيل واجهة برمجة التطبيقات الخاصة بها.

في هذا البرنامج التعليمي، تتعلم كيفية:

  • إنشاء منتج ونشره
  • إضافة واجهة برمجة تطبيقات إلى المنتج
  • عملية الوصول إلى واجهات برمجة تطبيقات المنتج

منتجات إدارة واجهة برمجة التطبيقات في المدخل

المتطلبات الأساسية

إنشاء منتج ونشره

  1. سجل الدخول إلى مدخل Azure، وانتقل إلى مثيل إدارة واجهة برمجة التطبيقات الخاصة بك.

  2. في جزء التنقل الأيسر، حدد المنتجات>+ إضافة.

    إضافة المنتج في مدخل Microsoft Azure

  3. في إطار إضافة منتج، أدخل القيم الموضحة في الجدول التالي لإنشاء المنتج الخاص بك.

    إضافة نافذة المنتج

    الاسم ‏‏الوصف
    ‏‫اسم العرض‬ الاسم كما تريد أن يظهر في مدخل المطور.
    ‏‏الوصف قدم معلومات حول المنتج مثل الغرض منه وواجهات برمجة التطبيقات التي يوفر الوصول إليها وتفاصيل أخرى.
    المنطقة حدد Published إذا كنت تريد نشر المنتج إلى مدخل المطور. قبل أن يتمكن المطورون من اكتشاف واجهات برمجة التطبيقات في المنتج، يجب نشر المنتج. بشكل افتراضي، لا يتم نشر المنتجات الجديدة.
    يتطلب الاشتراك حدد ما إذا كان المستخدم مطالبًا بالاشتراك في استخدام المنتج (المنتج محمي)، ويتعين استخدام مفتاح اشتراك للوصول إلى API للمنتج. في حالة لم يكن الاشتراك مطلوبًا (المنتج مفتوح)، فلن يكون مفتاح الاشتراك مطلوبًا للوصول إلى API للمنتج. راجع الوصول إلى API للمنتج لاحقًا في هذه المقالة.
    يتطلب الموافقة حدد ما إذا كنت تريد أن يقوم المسؤول بمراجعة وقبول أو رفض محاولات الاشتراك في هذا المنتج. في حالة عدم التحديد، تتم الموافقة على محاولات الاشتراك تلقائيًا.
    حد عدد الاشتراكات حدد عدد الاشتراكات المتزامنة المتعددة بشكل اختياري. الحد الأدنى للقيمة: 1
    ‏‏الشروط القانونية يمكنك تضمين شروط استخدام المنتج التي يجب على المشتركين قبولها من أجل استخدام المنتج.
    واجهات برمجة التطبيقات تحديد واجهة برمجة تطبيقات أو أكثر. يمكنك أيضًا إضافة واجهات برمجة التطبيقات بعد إنشاء المنتج. لمزيد من المعلومات، راجع إضافة واجهات برمجة التطبيقات إلى منتج في وقت لاحق من هذه المقالة.

    في حالة كان المنتج مفتوحًا (لا يتطلب اشتراكًا)، يمكنك فقط إضافة API غير مقترنة بمنتج مفتوح آخر.

  4. حدد إنشاء لإنشاء منتجك الجديد.

تنبيه

استخدم الرعاية عند تكوين منتج لا تتطلب اشتراكًا. قد يكون هذا التكوين متساهلًا بشكل مفرط وقد يجعل API الخاصة بالمنتج أكثر عرضة لـ تهديدات أمان معينة لـ API.

إضافة المزيد من التكوينات

متابعة تكوين المنتج بعد حفظه. في مثيل إدارة واجهة برمجة التطبيقات، حدد المنتج من نافذة المنتجات. إضافة أو تحديث:

عنصر ‏‏الوصف
إعدادات بيانات تعريف المنتج وحالته
واجهات برمجة التطبيقات واجهات برمجة التطبيقات المرتبطة بالمنتج
السياسات السياسات المطبقة على واجهات برمجة التطبيقات للمنتجات
عنصر تحكم الوصول رؤية المنتج للمطورين أو الضيوف
الاشتراكات المشتركون في المنتجات

إضافة واجهات برمجة التطبيقات إلى منتج

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

إضافة واجهة برمجة تطبيقات إلى منتج موجود

  1. في التنقل الأيمن لمثيل إدارة واجهة برمجة التطبيقات، حددالمنتجات.
  2. حدد منتجًا، ثم حدد API.
  3. حدد + Add API.
  4. حدد واحدة أو أكثر من API ثم حدد.

إضافة واجهة برمجة تطبيقات إلى منتج موجود

الوصول إلى واجهات برمجة تطبيقات الخاصة بالمنتج

بمجرد نشر منتج، يمكن للمطورين الوصول إلى واجهات برمجة التطبيقات. اعتمادًا على طريقة تكوين المنتج، قد يحتاجون إلى الاشتراك في المنتج للوصول إليه.

  • المنتج المحمي - يتعين على المطورين أولًا الاشتراك في منتج محمٍ للوصول إلى واجهات برمجة التطبيقات الخاصة بالمنتج. عندما يشتركون، يحصلون على مفتاح اشتراك مميز لأي واجهة برمجة تطبيقات في هذا المنتج. إذا قمت بإنشاء مثيل APIM، فأنت مسؤول بالفعل، لذلك يتم الاشتراك في كل منتج بشكل افتراضي. للحصول على مزيدٍ من المعلومات فيما يتعلق بالاشتراكات، راجع الاشتراكات في إدارة Azure API.

    عندما يقوم عميل بإجراء طلب واجهة برمجة تطبيقات بمفتاح اشتراك منتج صالح، تعالج APIM الطلب وتوفر الوصول في سياق المنتج. يمكن تطبيق النهج وقواعد التحكم في الوصول التي كونت للمنتج.

    تلميح

    يمكنك إنشاء أو تحديث اشتراك مستخدم لمنتج باستخدام مفاتيح الاشتراك المخصصة من خلال أمر REST API أو PowerShell.

  • فتح المنتج - يمكن للمطورين الوصول إلى واجهات برمجة التطبيقات الخاصة بمنتج مفتوح دون مفتاح الاشتراك. ومع ذلك، يمكنك تكوين آليات أخرى لتأمين عملية وصول العميل إلى واجهات برمجة التطبيقات، بما في ذلك OAuth 2.0، وشهادات العميل، وتقييد عناوين IP للمتصل.

    إشعار

    لا يتم سرد المنتجات المفتوحة في مدخل المطور للمطورين للتعرف عليها أو الاشتراك فيها. وهي مرئية فقط لمجموعة المسؤولين . ستحتاج إلى استخدام آلية أخرى لإعلام المطورين بواجهات برمجة التطبيقات التي يمكن الوصول إليها دون مفتاح اشتراك.

    عندما يقوم عميل بإجراء طلب واجهة برمجة تطبيقات دون مفتاح اشتراك:

    • تتحقق APIM مما إذا كانت واجهة برمجة التطبيقات مقترنة بالمنتج المفتوح. يمكن ربط واجهة برمجة التطبيقات بمنتج مفتوح واحد على الأكثر.

    • في حالة كان المنتج المفتوح موجودًا، فإنه يعالج الطلب في سياق هذا المنتج المفتوح. يمكن تطبيق النهج وقواعد التحكم في الوصول التي تم تكوينها لمنتج مفتوح.

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

الخطوات التالية

في هذا البرنامج التعليمي، نتعلم طريقة القيام بما يأتي:

  • إنشاء منتج ونشره
  • إضافة واجهة برمجة تطبيقات إلى المنتج
  • عملية الوصول إلى واجهات برمجة تطبيقات المنتج

تقدم إلى البرنامج التعليمي الآتي:

إنشاء واجهة برمجة تطبيقات فارغة ونماذج من استجابات واجهة برمجة التطبيقات

في هذه المقالة، يمكنك استخدام Terraform لإنشاء مثيل Azure API Management وواجهة برمجة تطبيقات ومنتج ومجموعة وارتباطات بين المنتج وواجهة برمجة التطبيقات والمنتج والمجموعة.

يتيح Terraform تعريف البنية الأساسية السحابية ومعاينتها ونشرها. باستخدام Terraform، يمكنك إنشاء ملفات التكوين باستخدام بناء جملة HCL. يسمح لك بناء الجملة بلغة HCL بتحديد موفر الخدمة السحابية، مثل خدمة Azure، وتحديد العناصر التي تشكل البنية الأساسية للخدمة السحابية. بعد إنشاء ملفات التكوين الخاصة بك، يمكنك إنشاء خطة تنفيذ تسمح لك بمعاينة تغييرات البنية الأساسية قبل نشرها. بمجرد التحقق من التغييرات، يمكنك تطبيق خطة التنفيذ لنشر البنية الأساسية.

  • حدد الإصدار المطلوب من Terraform والموفرين المطلوبين.
  • تعريف المتغيرات لبادئة اسم مجموعة الموارد وموقع مجموعة الموارد وتنسيق المحتوى والقيمة لاستيراد تعريف واجهة برمجة التطبيقات.
  • إنشاء مجموعة موارد باسم عشوائي.
  • إنشاء خدمة APIM باسم عشوائي.
  • إنشاء واجهة برمجة تطبيقات باسم عشوائي.
  • إنشاء منتج باسم عشوائي في خدمة APIM.
  • إنشاء مجموعة باسم عشوائي.
  • إقران واجهة برمجة التطبيقات بالمنتج.
  • إقران المجموعة بالمنتج.
  • إخراج القيم العشوائية مثل أسماء مجموعة الموارد وخدمة APIM وواجهة برمجة التطبيقات والمنتج والمجموعة.

المتطلبات الأساسية

تنفيذ كود Terraform

إشعار

يوجد نموذج التعليمات البرمجية لهذه المقالة في مستودع Azure Terraform GitHub. يمكنك عرض ملف السجل الذي يحتوي على نتائج الاختبار من الإصدارات الحالية والسابقة من Terraform.

راجع المزيد من المقالات ونماذج التعليمات البرمجية التي توضح كيفية استخدام Terraform لإدارة موارد Azure.

  1. إنشاء دليل لاختبار وتشغيل نموذج تعليمة برمجية Terraform وجعله الدليل الحالي.

  2. أنشئ ملفا باسم main.tf، وأدرج التعليمات البرمجية التالية:

    resource "random_pet" "rg_name" {
  prefix = var.resource_group_name_prefix
}

resource "azurerm_resource_group" "rg" {
  location = var.resource_group_location
  name     = random_pet.rg_name.id
}

resource "random_string" "apim_service_name" {
  length  = 8
  lower   = true
  numeric = false
  special = false
  upper   = false
}

resource "azurerm_api_management" "apim_service" {
  name                = "${random_string.apim_service_name.result}-apim-service"
  location            = azurerm_resource_group.rg.location
  resource_group_name = azurerm_resource_group.rg.name
  publisher_name      = "Example Publisher"
  publisher_email     = "publisher@example.com"
  sku_name            = "Developer_1"
  tags = {
    Environment = "Example"
  }
  policy {
    xml_content = <<XML
    <policies>
      <inbound />
      <backend />
      <outbound />
      <on-error />
    </policies>
XML
  }
}

resource "random_string" "api_name" {
  length  = 8
  lower   = true
  numeric = false
  special = false
  upper   = false
}

resource "random_string" "content_value" {
  length  = 8
  lower   = true
  numeric = false
  special = false
  upper   = false
}

resource "azurerm_api_management_api" "api" {
  name                = "${random_string.api_name.result}-api"
  resource_group_name = azurerm_resource_group.rg.name
  api_management_name = azurerm_api_management.apim_service.name
  revision            = "1"
  display_name        = "${random_string.api_name.result}-api"
  path                = "example"
  protocols           = ["https", "http"]
  description         = "An example API"
  import {
    content_format = var.open_api_spec_content_format
    content_value  = var.open_api_spec_content_value
  }
}

resource "random_string" "product_name" {
  length  = 8
  lower   = true
  numeric = false
  special = false
  upper   = false
}

resource "azurerm_api_management_product" "product" {
  product_id            = "${random_string.product_name.result}-product"
  resource_group_name   = azurerm_resource_group.rg.name
  api_management_name   = azurerm_api_management.apim_service.name
  display_name          = "${random_string.product_name.result}-product"
  subscription_required = true
  approval_required     = false
  published             = true
  description           = "An example Product"
}

resource "random_string" "group_name" {
  length  = 8
  lower   = true
  numeric = false
  special = false
  upper   = false
}

resource "azurerm_api_management_group" "group" {
  name                = "${random_string.group_name.result}-group"
  resource_group_name = azurerm_resource_group.rg.name
  api_management_name = azurerm_api_management.apim_service.name
  display_name        = "${random_string.group_name.result}-group"
  description         = "An example group"
}

resource "azurerm_api_management_product_api" "product_api" {
  resource_group_name = azurerm_resource_group.rg.name
  api_management_name = azurerm_api_management.apim_service.name
  product_id          = azurerm_api_management_product.product.product_id
  api_name            = azurerm_api_management_api.api.name
}

resource "azurerm_api_management_product_group" "product_group" {
  resource_group_name = azurerm_resource_group.rg.name
  api_management_name = azurerm_api_management.apim_service.name
  product_id          = azurerm_api_management_product.product.product_id
  group_name          = azurerm_api_management_group.group.name
}

  3. أنشئ ملفا باسم outputs.tf، وأدرج التعليمات البرمجية التالية:

    output "resource_group_name" {
  value = azurerm_resource_group.rg.name
}

output "apim_service_name" {
  value = azurerm_api_management.apim_service.name
}

output "api_name" {
  value = azurerm_api_management_api.api.name
}

output "product_name" {
  value = azurerm_api_management_product.product.product_id
}

output "group_name" {
  value = azurerm_api_management_group.group.name
}

output "service_id" {
  description = "The ID of the API Management Service created"
  value       = azurerm_api_management.apim_service.id
}

output "gateway_url" {
  description = "The URL of the Gateway for the API Management Service"
  value       = azurerm_api_management.apim_service.gateway_url
}

output "service_public_ip_addresses" {
  description = "The Public IP addresses of the API Management Service"
  value       = azurerm_api_management.apim_service.public_ip_addresses
}

output "api_outputs" {
  description = "The IDs, state, and version outputs of the APIs created"
  value = {
    id             = azurerm_api_management_api.api.id
    is_current     = azurerm_api_management_api.api.is_current
    is_online      = azurerm_api_management_api.api.is_online
    version        = azurerm_api_management_api.api.version
    version_set_id = azurerm_api_management_api.api.version_set_id
  }
}

output "product_id" {
  description = "The ID of the Product created"
  value       = azurerm_api_management_product.product.id
}

output "product_api_id" {
  description = "The ID of the Product/API association created"
  value       = azurerm_api_management_product_api.product_api.id
}

output "product_group_id" {
  description = "The ID of the Product/Group association created"
  value       = azurerm_api_management_product_group.product_group.id
}

  4. أنشئ ملفا باسم providers.tf، وأدرج التعليمات البرمجية التالية:

    terraform {
  required_version = ">=1.0"
  
  required_providers {
    azurerm = {
      source  = "hashicorp/azurerm"
      version = "~>3.0"
    }
    random = {
      source  = "hashicorp/random"
      version = "~>3.0"
    }
  }
}

provider "azurerm" {
  features {}
}

  5. أنشئ ملفا باسم variables.tf، وأدرج التعليمات البرمجية التالية:

    variable "resource_group_name_prefix" {
  type        = string
  default     = "rg"
  description = "Prefix of the resource group name that's combined with a random ID so name is unique in your Azure subscription."
}

variable "resource_group_location" {
  type        = string
  default     = "eastus"
  description = "Location of the resource group."
}

variable "open_api_spec_content_format" {
  type        = string
  default     = "swagger-link-json"
  description = "The format of the content from which the API Definition should be imported. Possible values are: openapi, openapi+json, openapi+json-link, openapi-link, swagger-json, swagger-link-json, wadl-link-json, wadl-xml, wsdl and wsdl-link."
  validation {
    condition     = contains(["openapi", "openapi+json", "openapi+json-link", "openapi-link", "swagger-json", "swagger-link-json", "wadl-link-json", "wadl-xml", "wsdl", "wsdl-link"], var.open_api_spec_content_format)
    error_message = "open_api_spec_content_format must be one of the following: openapi, openapi+json, openapi+json-link, openapi-link, swagger-json, swagger-link-json, wadl-link-json, wadl-xml, wsdl and wsdl-link."
  }
}

variable "open_api_spec_content_value" {
  type        = string
  default     = "https://petstore3.swagger.io/api/v3/openapi.json"
  description = "The Content from which the API Definition should be imported. When a content_format of *-link-* is specified this must be a URL, otherwise this must be defined inline."
}

تهيئة Terraform

قم بتشغيل terraform init لتهيئة توزيع Terraform. يقوم هذا الأمر بتنزيل موفر Azure المطلوب لإدارة موارد Azure.

terraform init -upgrade

النقاط الرئيسية:

  • تقوم -upgrade المعلمة بترقية مكونات الموفر الإضافية الضرورية إلى أحدث إصدار يتوافق مع قيود إصدار التكوين.

إنشاء خطة تنفيذ Terraform

قم بتشغيل خطة terraform لإنشاء خطة تنفيذ.

terraform plan -out main.tfplan

النقاط الرئيسية:

  • ينشئ الأمر terraform plan خطة تنفيذ، لكنه لا ينفذها. بدلًا من ذلك، يحدد الإجراءات الضرورية لإنشاء التكوين المحدد في ملفات التكوين الخاصة بك. يسمح لك هذا النمط بالتحقق مما إذا كانت خطة التنفيذ تتطابق مع توقعاتك قبل إجراء أي تغييرات على الموارد الفعلية.
  • تسمح المعلمة -out الاختيارية بتحديد ملف الإخراج للخطة. يضمن استخدام -out المعلمة أن الخطة التي راجعتها هي بالضبط ما يتم تطبيقها.

تطبيق خطة تنفيذ Terraform

قم بتشغيل تطبيق terraform لتطبيق خطة التنفيذ على البنية الأساسية السحابية الخاصة بك.

terraform apply main.tfplan

النقاط الرئيسية:

  • يفترض الأمر المثال terraform apply أنك قمت بتشغيل terraform plan -out main.tfplanمسبقا .
  • إذا قمت بتحديد اسم ملف مختلف للمعلمة -out، فاستخدم نفس اسم الملف في الاستدعاء terraform apply.
  • إذا لم تستخدم المعلمة -out، استدع terraform apply دون أي معلمات.

تحقق من النتائج

قم بتشغيل az apim show لعرض Azure API Management:


az apim show --<apim_service_name> --<resource_group_name>

تنظيف الموارد

عندما لم تعد بحاجة إلى الموارد التي تم إنشاؤها عبر Terraform، قم بالخطوات التالية:

  1. قم بتشغيل خطة terraform وحدد العلامة destroy.

    terraform plan -destroy -out main.destroy.tfplan

    النقاط الرئيسية:

    • ينشئ الأمر terraform plan خطة تنفيذ، لكنه لا ينفذها. بدلًا من ذلك، يحدد الإجراءات الضرورية لإنشاء التكوين المحدد في ملفات التكوين الخاصة بك. يسمح لك هذا النمط بالتحقق مما إذا كانت خطة التنفيذ تتطابق مع توقعاتك قبل إجراء أي تغييرات على الموارد الفعلية.
    • تسمح المعلمة -out الاختيارية بتحديد ملف الإخراج للخطة. يضمن استخدام -out المعلمة أن الخطة التي راجعتها هي بالضبط ما يتم تطبيقها.

  2. قم بتشغيل تطبيق terraform لتطبيق خطة التنفيذ.

    terraform apply main.destroy.tfplan

استكشاف أخطاء Terraform على Azure وإصلاحها

استكشاف المشكلات الشائعة وإصلاحها عند استخدام Terraform على Azure.

الخطوات التالية

إنشاء واجهة برمجة تطبيقات فارغة واستجابات وهمية لواجهة برمجة التطبيقات.