OpenAPI Explorer:OpenAPI MCP Server Core Tool Usage Guide

ListProducts

Hangi Alibaba Cloud ürünlerinin mevcut olduğunu öğrenmeniz gerektiğinde AI Agent bu aracı kullanarak ürün kataloğunu sorgular. Örneğin, “Alibaba Cloud'un hangi hesaplama ile ilgili ürünleri var” ifadesini girdiğinizde AI Agent anahtar kelimeleri çıkarır ve ürün listesini buna göre filtreler.

Kullanım Rehberi

• Açıklamaya ürün anahtar kelimelerini ekleyin. Örneğin, “Alibaba Cloud'un hangi ürünleri var” yerine “Alibaba Cloud'un hangi hesaplama ile ilgili ürünleri var” ifadesi daha iyidir.

• Sorgu sonuçları sonraki konuşmalar için bağlam olarak kullanılabilir. Örneğin önce “Hangi veritabanı ürünleri mevcut?” diye sorun, ardından belirli bir ürün için özel operasyonel ayrıntıları takip edin.

{
  "filter": "compute"
}

[
  {
    "code": "Ess",
    "name": "Auto Scaling",
    "group": "Elastic Computing",
    "style": "RPC",
    "versions": ["2014-08-28", "2022-02-22"],
    "defaultVersion": "2022-02-22"
  },
  {
    "code": "Ecs",
    "name": "Elastic Compute Service",
    "group": "Elastic Computing",
    "style": "RPC",
    "versions": ["2014-05-26"],
    "defaultVersion": "2014-05-26"
  },
  {
    "code": "Eci",
    "name": "Elastic Container Instance",
    "group": "Elastic Computing",
    "style": "RPC",
    "versions": ["2018-08-08"],
    "defaultVersion": "2018-08-08"
  }
]
// More results returned, only 3 shown here

ListApis

Bir kullanıcı işlemi belirli bir ürünü içerdiğinde ancak AI Agent'ın tam API işlemini onaylaması gerektiğinde bu araç ürün API listesine göz atmak için kullanılır. Örneğin, “Bir ECS örneğine genel IP ata” ifadesini girdiğinizde AI Agent önce hangi ECS API'lerinin ilgili olduğunu sorgulayabilir, ardından uygun olanı seçip çalıştırabilir.

Kullanım Rehberi

• Operasyonel niyeti açıklarken ürün ve eylemi mümkün olduğunca spesifik belirtin. Örneğin, “IP ata” yerine “bir ECS örneğine genel IP ata” ifadesi daha iyidir.

{
  "product": "Ecs",
  "filter": "Instance"
}

[
  {
    "summary": "Allocates a public IP address to an ECS instance.",
    "apiName": "AllocatePublicIpAddress",
    "title": "Allocate Public IP"
  },
  {
    "summary": "Attaches a RAM role to one or more ECS instances.",
    "apiName": "AttachInstanceRamRole",
    "title": "Attach RAM Role to Instance"
  }
]
// More results returned, only 2 shown here

GetApiDefinition

Bir kullanıcı isteği bir API çağrısını içerdiğinde AI Agent genellikle önce SearchApis veya ListApis aracılığıyla hedef API'yi bulur, ardından bu aracı kullanarak API parametre tanımlarını alır ve son olarak doğru çağrıyı oluşturur. Örneğin, “Hangzhou bölgesindeki ECS örneklerini sorgula” ifadesini girdiğinizde AI Agent önce DescribeInstances API'sini bulur, ardından çalıştırmadan önce gerekli parametreleri bu araç aracılığıyla onaylar.

Kullanım Rehberi

• Operasyonel niyeti açıklarken mümkün olduğunca spesifik olun. AI Agent doğru API'yi bulduktan sonra parametreleri otomatik olarak onaylar ve çalıştırır.

{
  "product": "Ecs",
  "apiVersion": "2014-05-26",
  "apiName": "DescribeInstances"
}

{
  "summary": "Queries an instance list based on different request conditions",
  "methods": ["post", "get"],
  "parameters": ["...45 parameters total, omitted here"],
  "responses": {"...": "omitted"},
  "errorCodes": ["...omitted"]
}

SearchApis

Tam API adı bilinmediğinde AI Agent bu aracı kullanarak doğal dil açıklamasına göre ilgili Alibaba Cloud OpenAPI'yi eşleştirir. Örneğin, “ECS örnek izleme verileri nasıl görüntülenir” ifadesini girdiğinizde AI Agent arama yaparak ilgili izleme API'lerini bulur.

Kullanım Rehberi

• Açıklamaya ürün adını dahil edin. Örneğin, “güvenlik gruplarını sorgula” yerine “ECS güvenlik grubu kurallarını sorgula” ifadesi daha iyidir.

• Karmaşık gereksinimleri, her biri tek bir API işlemini temsil eden birden fazla bağımsız soruya bölün.

• API adı zaten biliniyorsa arama adımını atlamak için bunu doğrudan AI Agent'a belirtin (örneğin, “sorgulamak için DescribeInstances kullan”).

{
  "prompt": "How to view ECS instance monitoring data",
  "limit": 3
}

[
  {
    "apiName": "DescribeInstanceMonitorData",
    "code": "Ecs",
    "description": "Calls DescribeInstanceMonitorData to query monitoring information for an ECS instance. Available metrics include vCPU utilization, burstable instance credits, received data traffic, sent data traffic, and average bandwidth.",
    "weight": 0.98,
    "version": "2014-05-26"
  },
  {
    "apiName": "QueryMetricList",
    "code": "Cms",
    "description": "Queries monitoring data for a specified product instance over a period of time.",
    "weight": 0.85,
    "version": "2016-09-22"
  },
  {
    "apiName": "DescribeMetricLast",
    "code": "Cms",
    "description": "Queries the latest monitoring data for a specified metric.",
    "weight": 0.75,
    "version": "2019-01-01"
  }
]

ListProductRegions

Bir işlem bölge seçimi içerdiğinde AI Agent bu aracı kullanarak hedef bölgenin ürünü destekleyip desteklemediğini onaylar. Örneğin, “ECS Ulanqab'da kullanılabilir mi” veya “Singapur'da bir ECS örneği oluştur” ifadelerini girdiğinizde AI Agent önce bölge kullanılabilirliğini doğrular.

Kullanım Rehberi

• Sorguda hem ürün adını hem de hedef bölgeyi belirtin. Örneğin, “Ulanqab'da kullanılabilir mi” yerine “ECS Ulanqab'da kullanılabilir mi” ifadesi daha iyidir.

• Birden fazla bölge söz konusu olduğunda her birini belirtin. Örneğin, “ECS'in Hangzhou, Şanghay ve Singapur'da mevcut olup olmadığını onayla”.

{
  "product": "Ecs"
}

{
  "code": 0,
  "data": {
    "type": "regional",
    "endpoints": [
      {
        "regionId": "us-west-1",
        "regionName": "US (Silicon Valley)",
        "public": "ecs.us-west-1.aliyuncs.com",
        "vpc": "ecs-vpc.us-west-1.aliyuncs.com"
      },
      {
        "regionId": "cn-hangzhou",
        "regionName": "China (Hangzhou)",
        "public": "ecs.cn-hangzhou.aliyuncs.com",
        "vpc": "ecs-vpc.cn-hangzhou.aliyuncs.com"
      }
    ]
  }
}
// More results returned, only 2 shown here

GenerateCLICommand

“Yalnızca komutu oluştur, çalıştırma” talimatı verildiğinde veya AI Agent'ın bir komutu önizlemesi gerektiğinde bu araç bir CLI komut dizesi oluşturur. AI Agent genellikle önce GetApiDefinition aracılığıyla parametreleri onaylar, ardından bu araç aracılığıyla komutu oluşturur ve son olarak CallCLI aracılığıyla çalıştırır. Örneğin, “Hangzhou'daki ECS örneklerini sorgulamak için bir komut oluştur” ifadesini girdiğinizde yerel terminalde çalıştırılabilecek eksiksiz bir komut döndürülür.

Kullanım Rehberi

• Bir komutu yerel terminalde manuel olarak çalıştırmak için AI Agent'tan “yalnızca komutu oluştur, çalıştırma” istemesini isteyin. Oluşturulan komut kopyalanıp doğrudan kullanılabilir.

{
  "product": "Ecs",
  "apiVersion": "2014-05-26",
  "apiName": "DescribeInstances",
  "regionId": "cn-hangzhou",
  "jsonApiParameters": "{\"Status\": \"Running\", \"PageSize\": 100}"
}

{
  "cli": "aliyun ecs describe-instances --page-size 100 --status Running --region cn-hangzhou"
}

CallCLI

AI Agent hangi API işleminin çalıştırılacağını tam olarak bildiğinde çağrıyı doğrudan yapmak için bu aracı kullanır. Bu, Core Edition'da API çağrıları için birincil araçtır. Örneğin, “Hangzhou bölgesinde çalışan ECS örneklerini sorgula” ifadesini girdiğinizde AI Agent bir CLI komutu oluşturur ve sorguyu çalıştırır.

Kullanım Rehberi

• Bu araç tarafından çalıştırılan CLI komutları uzak bir sunucuda çalışır ve yerel dosyaları okuyamaz.

• Yazma işlemleri (kaynak oluşturma, değiştirme veya silme) ücretlendirmeye neden olabilir. AI Agent'tan çalıştırmadan önce işlem içeriğini onaylamasını isteyin.

{
  "command": "aliyun ecs describe-instances --biz-region-id cn-hangzhou --status Running"
}

{
  "Instances": {
    "Instance": []
  },
  "PageNumber": 1,
  "PageSize": 10,
  "TotalCount": 0
}

RunScript

Tek bir API çağrısı gereksinimi karşılayamadığında AI Agent bu aracı kullanarak toplu işlemler için betikler yazar. Örneğin, “Tüm bölgelerdeki ECS örneklerini say” veya “Tüm güvenlik gruplarını yüksek riskli kurallara karşı kontrol et” ifadelerini girdiğinizde AI Agent birden fazla kaynağı aynı anda sorgulamak için eşzamanlı betikler yazar.

Kullanım Rehberi

• Toplama, karşılaştırma veya toplu işlemler gerektiğinde kapsam ve amacı net bir şekilde açıklayın. Örneğin, “Tüm bölgelerdeki ECS örneklerini say” veya “Tüm güvenlik gruplarını yüksek riskli kurallara karşı kontrol et”.

• Betik çalıştırma birkaç saniye ila onlarca saniye sürebilir. Sonucun dönmesini sabırla bekleyin.

{
  "script": "regions = ['cn-hangzhou', 'cn-shanghai', 'cn-beijing']\nresponses = await asyncio.gather(*[\n    call_cli(product='Ecs', action='DescribeInstances',\n             params={'RegionId': r, 'PageSize': 100})\n    for r in regions\n], return_exceptions=True)\nresult = {r: res.get('TotalCount', 0) if isinstance(res, dict) else str(res)\n    for r, res in zip(regions, responses)}"
}

{
  "processID": "proc_1f7b02be133a41ee89135fafb833a972",
  "status": "Running",
  "nextAction": "CallGetTask",
  "result": null,
  "waitTimedOut": true,
  "message": "Task not in terminal state. Call AlibabaCloud___GetTask to wait for result.",
  "error": null
}

GetTask

Bir RunScript veya RunIaC görevinin çalıştırılması uzun sürdüğünde AI Agent bu aracı kullanarak görevin tamamlanmasını bekler ve sonucu alır. Bu araç, bölgeler arası denetim veya Terraform dağıtımı gibi zaman alan işlemler sırasında tetiklenebilir.

Kullanım Rehberi

• Zaman alan işlemler (bölgeler arası denetim veya toplu sorgular gibi) için sonucun dönmesini sabırla bekleyin.

• Manuel onay gerekiyorsa istemlere göre onay sürecini tamamlayın ve sonuç dönmeye devam edecektir.

{
  "processID": "proc_1f7b02be133a41ee89135fafb833a972",
  "waitTimeoutSeconds": 25
}

{
  "processID": "proc_1f7b02be133a41ee89135fafb833a972",
  "status": "Succeeded",
  "nextAction": "None",
  "result": {
    "cn-hangzhou": 0,
    "cn-shanghai": 0,
    "cn-beijing": 0
  }
}

GetPresignedUrl

RunIaC veya RunScript araçlarının harici dosyalara başvurması gerektiğinde AI Agent bu aracı kullanarak geçici bir yükleme bağlantısı oluşturur. Örneğin, Terraform kodu 64 KB'yi aştığında veya bir betiğin önceden yüklenmiş veri dosyalarını işlemesi gerektiğinde AI Agent sonraki işlemleri çalıştırmadan önce bu araç aracılığıyla dosyayı yükler.

Kullanım Rehberi

• Büyük dosya yüklemeleri söz konusu olduğunda sonraki işlemleri çalıştırmadan önce yüklemenin tamamlanmasını beklemeniz gerekebilir.

RunIaC

Cloud kaynaklarının oluşturulması, değiştirilmesi veya yok edilmesi gerektiğinde AI Agent altyapıyı Terraform aracılığıyla yönetmek için bu aracı kullanabilir. Örneğin, “CIDR bloğu 172.16.0.0/16 olan Hangzhou'da bir VPC oluştur” ifadesini girdiğinizde AI Agent önce kaynak yapılandırmasını oluşturur ve değişiklikleri önizler, ardından onayınızdan sonra oluşturma işlemini çalıştırır.

Kullanım Rehberi

• Kaynak gereksinimlerini açıklarken bölgeyi, teknik özellikleri ve adı net bir şekilde belirtin. Örneğin, “CIDR bloğu 172.16.0.0/16 olan, mcp-demo-vpc adında Hangzhou'da bir VPC oluştur”.

• Kaynak değişiklikleri manuel onay gerektirebilir. İsteme göre onay sürecini tamamlayın.

SearchDocuments

Ürün kullanımı, yapılandırma yöntemleri veya hata giderme hakkında bilgi tabanlı bir soru sorulduğunda AI Agent bu aracı kullanarak Alibaba Cloud resmi dokümantasyonunu arar. Örneğin, “Function Compute soğuk başlatma nasıl optimize edilir” veya “OSS Bucket Policy nasıl yapılandırılır” ifadelerini girdiğinizde eşleşen resmi dokümanlar için bir arama tetiklenir.

Kullanım Rehberi

• Sorguya ürün adını dahil etmek arama sonuçlarının alakasını artırır. Örneğin, “cross-origin yapılandırması” yerine “OSS cross-origin yapılandırması” ifadesi daha iyidir.

• Belirli bir ürün için dokümantasyona ihtiyaç duyulduğunda ürün adını belirtin. Örneğin, “soğuk başlatma optimizasyonu” yerine “Function Compute soğuk başlatma optimizasyonu dokümantasyonu” ifadesi daha iyidir.

{
  "query": "ECS instance creation",
  "limit": 3
}

{
  "results": [
    {
      "doc_id": 108442,
      "title": "Creation Methods",
      "url": "https://www.alibabacloud.com/help/zh/ecs/user-guide/create-instances/",
      "product": "Elastic Compute Service",
      "content": "This topic describes several methods of creating ECS instances...",
      "website": "cn",
      "language": "zh"
    },
    {
      "doc_id": 151725,
      "title": "ECS Instance Provisioning Methods",
      "url": "https://www.alibabacloud.com/help/zh/ecs/user-guide/provisioning-methods-of-ecs-instances",
      "product": "Elastic Compute Service",
      "content": "Manually create one or more instances...",
      "website": "cn",
      "language": "zh"
    }
  ],
  "matched_filters": {
    "product": "",
    "doc_type": null,
    "website": "cn",
    "language": "zh"
  }
}

GetDocument

AI Agent SearchDocuments aracılığıyla ilgili dokümanları bulduktan sonra soruyu yanıtlamak için tam içeriği okumak üzere bu aracı kullanır. Örneğin, “Function Compute soğuk başlatma nasıl optimize edilir?” ifadesini girdiğinizde AI Agent önce dokümanı arar ve bulur, ardından tam metni okuyup cevabı düzenler.

Kullanım Rehberi

• AI Agent dokümanları bulduktan sonra içeriği otomatik olarak okur ve düzenler. Sürecin tamamı kullanıcı için şeffaftır.

{
  "doc_id": 108442,
  "max_length": 500
}

{
  "doc_id": 108442,
  "url": "https://www.alibabacloud.com/help/ecs/user-guide/create-instances",
  "title": "Create Instances",
  "product": "ecs",
  "content": "This topic describes several methods of creating ECS instances..."
}

GetDocumentTree

Bir kullanıcı bir ürünün dokümantasyon yapısını anlamak istediğinde AI Agent bu aracı kullanarak doküman dizini ağacında gezinir. Örneğin, “OSS dokümantasyon yapısı nasıldır” veya “ECS'in hangi kullanıcı kılavuzları var” ifadelerini girdiğinizde.

Kullanım Rehberi

• Sorguda ürün adını belirtin. Örneğin, “OSS'in hangi doküman kategorileri var” veya “ECS kullanıcı kılavuzu altında hangi bölümler var”.

{
  "doc_id": 108442,
  "depth": 1
}

{
  "product": "Elastic Compute Service",
  "website": "cn",
  "language": "zh",
  "children": [
    {"title": "User Guide", "doc_id": 2399509, "url": "https://www.alibabacloud.com/help/ecs/user-guide", "children": []},
    {"title": "Developer Reference", "doc_id": 2399511, "url": "https://www.alibabacloud.com/help/ecs/developer-reference", "children": []},
    {"title": "Billing", "doc_id": 25396, "children": []},
    {"title": "FAQ", "doc_id": 2983136, "children": []}
  ]
}
// This example uses depth=1, returning only top-level nodes. Set depth to 2 or 3 to include sub-chapters

GrepDocuments

Bir soru belirli terimler, yapılandırma öğeleri veya hata kodları içerdiğinde AI Agent bu aracı kullanarak belirtilen ürün dokümantasyonu içinde tam anahtar kelime eşleştirmesi yapar. Örneğin, “ECS dokümantasyonunda InstanceChargeType'ın hangi değerleri vardır” veya “OSS dokümantasyonunda CORS ile ilgili içeriği ara” ifadelerini girdiğinizde.

Kullanım Rehberi

• Sorguda hem ürünü hem de anahtar kelimeyi belirtin. Örneğin, “ECS dokümantasyonunda DescribeInstanceAttribute'ı ara”.

• Daha kesin anahtar kelimeler daha alakalı sonuçlar verir. Birden fazla anahtar kelimenin AND ilişkisi vardır.

{
  "product": "ecs",
  "pattern": "DescribeInstanceAttribute",
  "limit": 3
}

{
  "product_code": "ecs",
  "pattern": "DescribeInstanceAttribute",
  "matches": [
    {
      "title": "DescribeInstanceAttribute - Query instance attribute information",
      "url": "https://www.alibabacloud.com/help/ecs/developer-reference/api-ecs-2014-05-26-describeinstanceattribute",
      "matched_text": "DescribeInstanceTypes - Query instance type information list\nDescribeInstanceAttribute - Query instance attribute information\nModifyInstanceAttribute - Modify instance attribute information",
      "line_no": 986
    }
  ],
  "total": 1,
  "truncated": false,
  "llms_txt_url": "https://www.alibabacloud.com/help/zh/ecs/llms.txt"
}

Check the security group rules in the Hangzhou region

Count the number of ECS instances in Hangzhou, Shanghai, and Beijing regions

Function Compute cold start latency is high. What optimization options are available?