Aracıları OpenAPI araçlarına bağlama

OpenAPI 3.0 ve 3.1 belirtimlerini kullanarak Microsoft Foundry aracılarınızı dış API'lere bağlayın. Aracınızı destekleyen Foundry modeli dış hizmetleri çağırabilir, gerçek zamanlı verileri alabilir ve özelliklerini yerleşik işlevlerin ötesine genişletebilir.

OpenAPI belirtimleri , mevcut hizmetleri aracılarınızla tümleştirebilmeniz için HTTP API'lerini açıklamak için standart bir yol tanımlar. Microsoft Foundry üç kimlik doğrulama yöntemini destekler: anonymous, API key ve managed identity. Kimlik doğrulama yöntemi seçmeyle ilgili yardım için bkz. Kimlik doğrulama yöntemi seçme.

Kullanım desteği

Aşağıdaki tabloda SDK ve kurulum desteği gösterilmektedir.

Microsoft Foundry desteği Python SDK C# SDK'sı JavaScript SDK'sı Java SDK REST API Temel aracı kurulumu Standart ajan kurulumu
✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️

Not

Java için OpenAPI aracı araçları için com.azure:azure-ai-agents paketini kullanın. Paket com.azure:azure-ai-projects şu anda OpenAPI aracı araç türlerini kullanıma sunmaz.

Önkoşullar

Başlamadan önce şunları yaptığınızdan emin olun:

  • Doğru izinlere sahip bir Azure aboneliği.
  • Azure RBAC rolü: Foundry projesinde Katkıda Bulunan veya Sahip.
  • Yapılandırılmış bir uç nokta ile oluşturulmuş bir Dökümhane projesi.
  • Projenizde dağıtılan bir yapay zeka modeli.
  • Temel veya standart aracı ortamı.
  • Tercih ettiğiniz dil için yüklenen SDK:
    • Python: azure-ai-projects
    • C#: Azure.AI.Extensions.OpenAI
    • TypeScript/JavaScript: @azure/ai-projects
    • Java: com.azure:azure-ai-agents

Ortam değişkenleri

Değişken Açıklama
FOUNDRY_PROJECT_ENDPOINT Foundry proje uç noktası URL'niz (dış OpenAPI hizmet uç noktası değil).
FOUNDRY_MODEL_DEPLOYMENT_NAME Dağıtılan modelin adı.
OPENAPI_PROJECT_CONNECTION_NAME (API anahtarı kimlik doğrulaması için) OpenAPI hizmeti için proje bağlantı adınız.
  • Bu gereksinimleri karşılayan OpenAPI 3.0 veya 3.1 belirtim dosyası:
    • Her işlevin bir operationId değeri olmalıdır (OpenAPI aracı için gereklidir).
    • operationId yalnızca harfleri, - ve _ içermelidir.
    • Modellerin hangi işlevin kullanılacağına verimli bir şekilde karar vermesine yardımcı olması için açıklayıcı adlar kullanın.
    • Desteklenen istek gövdesi içerik türleri: application/json, application/json-patch+json
  • Yönetilen kimlik doğrulaması için: Hedef hizmet kaynaklarında Okuyucu rolü veya daha yüksek bir yetki.
  • API anahtarı/belirteç kimlik doğrulaması için: API anahtarınız veya belirteciniz ile yapılandırılmış bir proje bağlantısı. Bkz. Projenize yeni bağlantı ekleme.

Not

FOUNDRY_PROJECT_ENDPOINT değeri, dış OpenAPI hizmet uç noktasını değil Microsoft Foundry proje uç noktanızı ifade eder. Bu uç noktayı projenizin Genel Bakış sayfasının altındaki Microsoft Foundry portalında bulabilirsiniz. Bu uç nokta, aracı hizmetinin kimliğini doğrulamak için gereklidir ve belirtim dosyanızda tanımlanan tüm OpenAPI uç noktalarından ayrıdır.

Sınırlamaları anlama

  • OpenAPI belirtiminizin her işlem için içermesi operationId gerekir ve operationId yalnızca , ve -harflerini _içerebilir.
  • Desteklenen istek gövdesi içerik türleri: application/json, application/json-patch+json.
  • API anahtarı kimlik doğrulaması için OpenAPI aracı başına bir API anahtarı güvenlik düzeni kullanın. Birden çok güvenlik düzenine ihtiyacınız varsa, birden çok OpenAPI aracı oluşturun.

Kod örneği

Not

  • En son SDK paketine ihtiyacınız vardır. .NET SDK şu anda önizleme aşamasındadır. Ayrıntılar için hızlı başlangıç bölümüne bakın.
  • Kimlik doğrulaması için API anahtarı kullanıyorsanız bağlantı kimliğiniz /subscriptions/{{subscriptionID}}/resourceGroups/{{resourceGroupName}}/providers/Microsoft.CognitiveServices/accounts/{{foundryAccountName}}/projects/{{foundryProjectName}}/connections/{{foundryConnectionName}} biçiminde olmalıdır.

Önemli

API anahtarı kimlik doğrulamasının çalışması için OpenAPI belirtim dosyanız şunları içermelidir:

  1. securitySchemes Başlık adı ve parametre adı gibi API anahtar yapılandırmanızı içeren bir bölüm.
  2. security Güvenlik düzenine başvuran bir bölüm.
  3. Eşleşen anahtar adı ve değeriyle yapılandırılmış bir proje bağlantısı.

Bu yapılandırmalar olmadan API anahtarı isteklere dahil değildir. Ayrıntılı kurulum yönergeleri için API anahtarıyla kimlik doğrulaması bölümüne bakın.

Proje bağlantısında belirteci depolayarak, belirteç tabanlı kimlik doğrulamasını (örneğin, Bearer belirteç) de kullanabilirsiniz. Taşıyıcı jeton kimlik doğrulaması için anahtarı Authorization ve değeri Bearer <token> olarak ayarlanmış özel bir anahtarlar bağlantısı oluşturun (değeri gerçek jetonunuzla değiştirin<token>). Sözcük Bearer ardından bir boşlukla birlikte değere eklenmelidir. Ayrıntılar için bkz. Taşıyıcı belirteci bağlantısı ayarlama.

Tam örnek

import os
import jsonref
from typing import Any, cast
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import (
    PromptAgentDefinition,
    OpenApiTool,
    OpenApiFunctionDefinition,
    OpenApiAnonymousAuthDetails,
)

# Format: "https://resource_name.ai.azure.com/api/projects/project_name"
PROJECT_ENDPOINT = "your_project_endpoint"
OPENAPI_CONNECTION_NAME = "my-openapi-connection"

# Create clients to call Foundry API
project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
)
openai = project.get_openai_client()

weather_asset_file_path = os.path.abspath(
    os.path.join(os.path.dirname(__file__), "../assets/weather_openapi.json")
)

with open(weather_asset_file_path, "r") as f:
    openapi_weather = cast(dict[str, Any], jsonref.loads(f.read()))

# Initialize agent OpenAPI tool using the read in OpenAPI spec
weather_tool = OpenApiTool(
    openapi=OpenApiFunctionDefinition(
        name="get_weather",
        spec=openapi_weather,
        description="Retrieve weather information for a location.",
        auth=OpenApiAnonymousAuthDetails(),
    )
)

# If you want to use key-based authentication
# IMPORTANT: Your OpenAPI spec must include securitySchemes and security sections
# Example spec structure for API key auth:
# {
#   "components": {
#     "securitySchemes": {
#       "apiKeyHeader": {
#         "type": "apiKey",
#         "name": "x-api-key",  # This must match the key name in your project connection
#         "in": "header"
#       }
#     }
#   },
#   "security": [{"apiKeyHeader": []}]
# }
#
# For Bearer token authentication, use this securitySchemes structure instead:
# {
#   "components": {
#     "securitySchemes": {
#       "bearerAuth": {
#         "type": "apiKey",
#         "name": "Authorization",
#         "in": "header"
#       }
#     }
#   },
#   "security": [{"bearerAuth": []}]
# }
# Then set connection key = "Authorization" and value = "Bearer <token>"
# The word "Bearer" followed by a space MUST be included in the value.

openapi_connection = project.connections.get(OPENAPI_CONNECTION_NAME)
connection_id = openapi_connection.id

openapi_key_auth_tool = {
    "type": "openapi",
    "openapi": {
        "name": "get_weather",
        "spec": openapi_weather,  # Must include securitySchemes and security sections
        "auth": {
            "type": "project_connection",
            "security_scheme": {
                "project_connection_id": connection_id
            }
        },
    }
}

# If you want to use Managed Identity authentication
openapi_mi_auth_tool = {
    "type": "openapi",
    "openapi": {
        "name": "get_weather",
        "description": "Retrieve weather information for a location.",
        "spec": openapi_weather,
        "auth": {
            "type": "managed_identity",
            "security_scheme": {
                "audience": "https://storage.azure.com"  # Resource identifier of the target service
            }
        },
    }
}

agent = project.agents.create_version(
    agent_name="MyAgent",
    definition=PromptAgentDefinition(
        model="gpt-4.1-mini",
        instructions="You are a helpful assistant.",
        tools=[weather_tool],
    ),
)
response = openai.responses.create(
    input="What's the weather in Seattle?",
    extra_body={"agent_reference": {"name": agent.name, "type": "agent_reference"}},
)
print(response.output_text)

# Clean up resources
project.agents.delete_version(agent_name=agent.name, agent_version=agent.version)

Bu kod ne yapar?

Bu örnek, anonim kimlik doğrulaması kullanarak wttr.in hava durumu API'sini çağıran bir OpenAPI aracısıyla bir aracı oluşturur. Kodu çalıştırdığınızda:

  1. Yerel bir JSON dosyasından hava Durumu OpenAPI belirtimini yükler.
  2. Anonim erişim için yapılandırılmış hava durumu aracıyla bir aracı oluşturur.
  3. Seattle'ın hava durumunu soran bir sorgu gönderir.
  4. Aracı, hava durumu API'sini çağırmak için OpenAPI aracını kullanır ve biçimlendirilmiş sonuçlar döndürür.
  5. Aracı sürümünü silerek temizler.

Gerekli girişler

  • Betiğin en üstündeki dize değerleri: PROJECT_ENDPOINT, OPENAPI_CONNECTION_NAME
  • Yerel dosya: weather_openapi.json (OpenAPI belirtimi)

Beklenen çıkış

Agent created (id: asst_abc123, name: MyAgent23, version: 1)
Response created: The weather in Seattle is currently cloudy with a temperature of 52°F (11°C)...

Cleaning up...
Agent deleted

Yaygın hatalar

  • FileNotFoundError: OpenAPI belirtim dosyası belirtilen yolda bulunamadı
  • AuthenticationError: API anahtarı kimlik doğrulaması için OpenAPI belirtiminde geçersiz kimlik bilgileri veya yetersiz izinler veya eksik securitySchemes
  • OpenAPI belirtiminde geçersiz operationId biçim araç kaydı hatasına neden oluyor
  • API anahtarı eklenmedi: OpenAPI belirtiminizin hem hem de securitySchemessecurity bölümleri içerdiğini ve anahtar adının proje bağlantınızla eşleşip eşleşmediğini doğrulayın

OpenAPI aracısıyla aracı kullanma örneği

Bu örnekte, aracı kullanarak OpenAPI belirtimi tarafından açıklanan hizmetlerin nasıl kullanılacağı gösterilmektedir. Hava durumunu ve belirtim dosyasını weather_openapi.json almak için wttr.in hizmetini kullanır. Bu örnek, Azure AI Projeleri istemci kitaplığının zaman uyumlu yöntemlerini kullanır. Zaman uyumsuz yöntemler kullanan bir örnek için, GitHub .NET deposu için Azure SDK sample bölümüne bakın.

using System;
using System.IO;
using System.Runtime.CompilerServices;
using Azure.AI.Projects;
using Azure.AI.Extensions.OpenAI;
using Azure.Identity;

class OpenAPIDemo
{
    // Utility method to get the OpenAPI specification file from the Assets folder.
    private static string GetFile([CallerFilePath] string pth = "")
    {
        var dirName = Path.GetDirectoryName(pth) ?? "";
        return Path.Combine(dirName, "Assets", "weather_openapi.json");
    }

    public static void Main()
    {
        // Format: "https://resource_name.ai.azure.com/api/projects/project_name"
        var projectEndpoint = "your_project_endpoint";

        // Create project client to call Foundry API
        AIProjectClient projectClient = new(
            endpoint: new Uri(projectEndpoint),
            tokenProvider: new DefaultAzureCredential());

        // Create an Agent with `OpenAPIAgentTool` and anonymous authentication.
        string filePath = GetFile();
        OpenAPIFunctionDefinition toolDefinition = new(
            name: "get_weather",
            spec: BinaryData.FromBytes(File.ReadAllBytes(filePath)),
            auth: new OpenAPIAnonymousAuthenticationDetails()
        );
        toolDefinition.Description = "Retrieve weather information for a location.";
        OpenAPITool openapiTool = new(toolDefinition);

        // Create the agent definition and the agent version.
        DeclarativeAgentDefinition agentDefinition = new(model: "gpt-4.1-mini")
        {
            Instructions = "You are a helpful assistant.",
            Tools = { openapiTool }
        };
        AgentVersion agentVersion = projectClient.AgentAdministrationClient.CreateAgentVersion(
            agentName: "myAgent",
            options: new(agentDefinition));

        // Create a response object and ask the question about the weather in Seattle, WA.
        ProjectResponsesClient responseClient = projectClient.ProjectOpenAIClient.GetProjectResponsesClientForAgent(agentVersion.Name);
        ResponseResult response = responseClient.CreateResponse(
                userInputText: "Use the OpenAPI tool to print out, what is the weather in Seattle, WA today."
            );
        Console.WriteLine(response.GetOutputText());

        // Finally, delete all the resources created in this sample.
        projectClient.AgentAdministrationClient.DeleteAgentVersion(agentName: agentVersion.Name, agentVersion: agentVersion.Version);
    }
}

Bu kod ne yapar?

Bu C# örneği, anonim kimlik doğrulaması kullanarak wttr.in hava durumu bilgilerini alan bir OpenAPI aracıyla bir aracı oluşturur. Kodu çalıştırdığınızda:

  1. Yerel bir JSON dosyasından hava durumu OpenAPI belirtimini okur.
  2. Hava durumu aracının yapılandırıldığı bir aracı oluşturur.
  3. OpenAPI aracını kullanarak Seattle'ın hava durumunu soran bir istek gönderir.
  4. Ajan hava durumu API'sini çağırır ve sonuçları döndürür.
  5. Aracıyı silerek temizler.

Gerekli girişler

  • Satır içi dize değeri: projectEndpoint (Dökümhane proje uç noktanız)
  • Yerel dosya: Assets/weather_openapi.json (OpenAPI belirtimi)

Beklenen çıkış

The weather in Seattle, WA today is cloudy with temperatures around 52°F...

Yaygın hatalar

  • FileNotFoundException: OpenAPI belirtim dosyası Varlıklar klasöründe bulunamadı
  • UnauthorizedAccessException: Geçersiz kimlik bilgileri veya yetersiz RBAC izinleri
  • API anahtarı eklenmedi: OpenAPI belirtiminizin hem (içindesecuritySchemes) components hem de security eşleşen düzen adlarına sahip bölümleri içerdiğini doğrulayın

OpenAPI aracını kullanan Web hizmetinde aracı kullanımı örneği, kimlik doğrulaması gerektirir.

Bu örnekte, kimlik doğrulaması gerektiren bir senaryoda aracıyı kullanarak hizmetleri OpenAPI belirtimi ile kullanırsınız. TripAdvisor spesifikasyonunu kullanıyorsunuz.

TripAdvisor hizmeti anahtar tabanlı kimlik doğrulaması gerektirir. Azure portalında bağlantı oluşturmak için Microsoft Foundry'yi açın ve sol panelde Yönetme merkezi'ı ve ardından Bağlantılı kaynaklar'i seçin. Son olarak, Özel anahtar türünde yeni bir bağlantı oluşturun. Ad verin tripadvisor ve bir anahtar değer çifti ekleyin. adlı key anahtarı ekleyin ve TripAdvisor anahtarınızla bir değer girin.

class OpenAPIConnectedDemo
{
    // Utility method to get the OpenAPI specification file from the Assets folder.
    private static string GetFile([CallerFilePath] string pth = "")
    {
        var dirName = Path.GetDirectoryName(pth) ?? "";
        return Path.Combine(dirName, "Assets", "tripadvisor_openapi.json");
    }

    public static void Main()
    {
        // Format: "https://resource_name.ai.azure.com/api/projects/project_name"
        var projectEndpoint = "your_project_endpoint";

        // Create project client to call Foundry API
        AIProjectClient projectClient = new(
            endpoint: new Uri(projectEndpoint),
            tokenProvider: new DefaultAzureCredential());

        // Create an Agent with `OpenAPIAgentTool` and authentication by project connection security scheme.
        string filePath = GetFile();
        AIProjectConnection tripadvisorConnection = projectClient.Connections.GetConnection("tripadvisor");
        OpenAPIFunctionDefinition toolDefinition = new(
            name: "tripadvisor",
            spec: BinaryData.FromBytes(File.ReadAllBytes(filePath)),
            auth: new OpenAPIProjectConnectionAuthenticationDetails(new OpenAPIProjectConnectionSecurityScheme(
                projectConnectionId: tripadvisorConnection.Id
            ))
        );
        toolDefinition.Description = "Trip Advisor API to get travel information.";
        OpenAPITool openapiTool = new(toolDefinition);

        // Create the agent definition and the agent version.
        DeclarativeAgentDefinition agentDefinition = new(model: "gpt-4.1-mini")
        {
            Instructions = "You are a helpful assistant.",
            Tools = { openapiTool }
        };
        AgentVersion agentVersion = projectClient.AgentAdministrationClient.CreateAgentVersion(
            agentName: "myAgent",
            options: new(agentDefinition));

        // Create a response object and ask the question about the hotels in France.
        // Test the Web service access before you run production scenarios.
        // It can be done by setting:
        // ToolChoice = ResponseToolChoice.CreateRequiredChoice()`
        // in the ResponseCreationOptions. This setting will
        // force Agent to use tool and will trigger the error if it is not accessible.
        ProjectResponsesClient responseClient = projectClient.ProjectOpenAIClient.GetProjectResponsesClientForAgent(agentVersion.Name);
        CreateResponseOptions responseOptions = new()
        {
            ToolChoice = ResponseToolChoice.CreateRequiredChoice(),
            InputItems =
            {
                ResponseItem.CreateUserMessageItem("Recommend me 5 top hotels in paris, France."),
            }
        };
        ResponseResult response = responseClient.CreateResponse(
            options: responseOptions
        );
        Console.WriteLine(response.GetOutputText());

        // Finally, delete all the resources we have created in this sample.
        projectClient.AgentAdministrationClient.DeleteAgentVersion(agentName: agentVersion.Name, agentVersion: agentVersion.Version);
    }
}

Bu kod ne yapar?

Bu C# örneği, proje bağlantısı aracılığıyla API anahtarı kimlik doğrulaması ile OpenAPI aracının kullanılmasını gösterir. Kodu çalıştırdığınızda:

  1. TripAdvisor OpenAPI belirtimini yerel bir dosyadan yükler.
  2. tripadvisor API anahtarınızı içeren proje bağlantısını alır.
  3. TripAdvisor aracının, kimlik doğrulaması için bağlantıyı kullanacak şekilde yapılandırılmasıyla bir yetkilendirme aracı oluşturur.
  4. Paris'te otel önerileri için bir istek gönderir.
  5. Aracı, depolanan API anahtarınızı kullanarak TripAdvisor API'sini çağırır ve sonuçları döndürür.
  6. Aracıyı silerek temizler.

Gerekli girişler

  • Satır içi dize değeri: projectEndpoint (Dökümhane proje uç noktanız)
  • Yerel dosya: Assets/tripadvisor_openapi.json
  • Project bağlantısı: tripadvisor geçerli bir API anahtarı yapılandırılmış

Beklenen çıkış

Here are 5 top hotels in Paris, France:
1. Hotel Name - Rating: 4.5/5, Location: ...
2. Hotel Name - Rating: 4.4/5, Location: ...
...

Yaygın hatalar

  • ConnectionNotFoundException: Adlı tripadvisor proje bağlantısı bulunamadı.
  • AuthenticationException: Proje bağlantısında geçersiz API anahtarı veya OpenAPI belirtiminde eksik/yanlış securitySchemes yapılandırma.
  • Kullanılmayan araç: Araç kullanımını zorladığını doğrulamak için ToolChoice = ResponseToolChoice.CreateRequiredChoice() kontrol edin.
  • API anahtarı API'ye geçirilmedi: OpenAPI belirtiminin düzgün securitySchemes olduğundan ve security bölümlerin yapılandırıldığından emin olun.

OpenAPI aracı özellikleriyle Java aracısı oluşturma

Bu Java örnek, com.azure:azure-ai-agents ve yerel bir OpenAPI belirtim dosyası kullanarak OpenAPI aracısıyla bir aracı oluşturur. Örnek anonim kimlik doğrulaması kullanır ve genel API uç noktasını çağırır.

import com.azure.ai.agents.AgentsClient;
import com.azure.ai.agents.AgentsClientBuilder;
import com.azure.ai.agents.ConversationsClient;
import com.azure.ai.agents.ResponsesClient;
import com.azure.ai.agents.models.*;
import com.azure.core.util.BinaryData;
import com.azure.identity.DefaultAzureCredentialBuilder;
import com.azure.json.JsonProviders;
import com.azure.json.JsonReader;
import com.openai.models.conversations.Conversation;
import com.openai.models.conversations.items.ItemCreateParams;
import com.openai.models.responses.EasyInputMessage;
import com.openai.models.responses.Response;
import com.openai.models.responses.ResponseCreateParams;

import java.nio.file.Paths;
import java.util.Arrays;
import java.util.Map;

public class OpenApiAgentJavaSample {
    public static void main(String[] args) throws Exception {
        // Format: "https://resource_name.ai.azure.com/api/projects/project_name"
        String projectEndpoint = "your_project_endpoint";

        AgentsClientBuilder builder = new AgentsClientBuilder()
            .endpoint(projectEndpoint)
            .credential(new DefaultAzureCredentialBuilder().build());

        AgentsClient agentsClient = builder.buildAgentsClient();
        ResponsesClient responsesClient = builder.buildResponsesClient();
        ConversationsClient conversationsClient = builder.buildConversationsClient();

        Map<String, BinaryData> spec = OpenApiFunctionDefinition.readSpecFromFile(
            Paths.get("openapi_spec.json"));

        OpenApiFunctionDefinition toolDefinition = new OpenApiFunctionDefinition(
            "httpbin_get",
            spec,
            new OpenApiAnonymousAuthDetails())
            .setDescription("Get request metadata from an OpenAPI endpoint.");

        PromptAgentDefinition agentDefinition = new PromptAgentDefinition("gpt-4.1-mini")
            .setInstructions("Use the OpenAPI tool for HTTP request metadata.")
            .setTools(Arrays.asList(new OpenApiTool(toolDefinition)));

        AgentVersionDetails agentVersion = agentsClient.createAgentVersion("openapiValidationAgentJava", agentDefinition);
        System.out.println("Agent: " + agentVersion.getName() + ", version: " + agentVersion.getVersion());

        Conversation conversation = conversationsClient.getConversationService().create();
        conversationsClient.getConversationService().items().create(
            ItemCreateParams.builder()
                .conversationId(conversation.id())
                .addItem(EasyInputMessage.builder()
                    .role(EasyInputMessage.Role.USER)
                    .content("Use the OpenAPI tool and summarize the returned URL and origin in one sentence.")
                    .build())
                .build());

        try {
            AgentReference agentReference = new AgentReference(agentVersion.getName()).setVersion(agentVersion.getVersion());
            ResponseCreateParams.Builder options = ResponseCreateParams.builder().maxOutputTokens(300L);
            Response response = responsesClient.createAzureResponse(
                new AzureCreateResponseOptions().setAgentReference(agentReference),
                options.conversation(conversation.id()));

            String text = response.output().stream()
                .filter(item -> item.isMessage())
                .map(item -> item.asMessage().content()
                    .get(item.asMessage().content().size() - 1)
                    .asOutputText()
                    .text())
                .reduce((first, second) -> second)
                .orElse("<no message output>");

            System.out.println("Status: " + response.status().map(Object::toString).orElse("unknown"));
            System.out.println("Response: " + text);
        } finally {
            agentsClient.deleteAgentVersion(agentVersion.getName(), agentVersion.getVersion());
            System.out.println("Agent deleted");
        }
    }
}

Bu kod ne yapar?

Bu Java örneği, OpenAPI aracını kullanarak bir aracı oluşturur ve konuşma kapsamlı bir yanıt işlemi yürütür.

  1. OpenAPI spesifikasyonunu openapi_spec.json'den yükler.
  2. ile OpenApiToolbir aracı sürümü oluşturur.
  3. Bir konuşma oluşturur ve bir kullanıcı iletisi ekler.
  4. AgentReference ve konuşma kimliğini geçirerek bir yanıt oluşturur.
  5. Aracı sürümünü silerek temizler.

Gerekli girişler

  • Satır içi dize değeri: projectEndpoint (Dökümhane proje uç noktanız)
  • Yerel dosya: openapi_spec.json (OpenAPI 3.0 veya 3.1 belirtimi)

Beklenen çıkış

Agent: openapiValidationAgentJava, version: 1
Status: completed
Response: The API response reports URL ... and origin ...
Agent deleted

Yaygın hatalar

  • Invalid OpenAPI specification: OpenAPI JSON dosyasını OpenApiFunctionDefinition'e geçirmeden önce bir nesneye ayrıştırın.
  • Invalid conversation id: Bir konuşma oluşturun ve conversation.id()'i ResponseCreateParams.builder().conversation() aracılığıyla createAzureResponse'ye geçirin.
  • AuthenticationFailedException: Oturum açmış hesabınız için belirteç alabildiğini doğrulayın DefaultAzureCredential .

Aşağıdaki örneklerde, REST API kullanarak OpenAPI aracının nasıl çağrıldığı gösterilmektedir.

Erişim belirteci alma:

export AGENT_TOKEN=$(az account get-access-token --scope "https://ai.azure.com/.default" --query accessToken -o tsv)

Anonim kimlik doğrulaması

curl --request POST \
  --url "$FOUNDRY_PROJECT_ENDPOINT/openai/v1/responses" \
  --header "Authorization: Bearer $AGENT_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "'$FOUNDRY_MODEL_DEPLOYMENT_NAME'",
    "input": "Use the OpenAPI tool to get the weather in Seattle, WA today.",
    "tools": [
      {
        "type": "openapi",
        "openapi": {
          "name": "weather",
          "description": "Tool to get weather data",
          "auth": { "type": "anonymous" },
          "spec": {
            "openapi": "3.1.0",
            "info": {
              "title": "get weather data",
              "description": "Retrieves current weather data for a location.",
              "version": "v1.0.0"
            },
            "servers": [{ "url": "https://wttr.in" }],
            "paths": {
              "/{location}": {
                "get": {
                  "description": "Get weather information for a specific location",
                  "operationId": "GetCurrentWeather",
                  "parameters": [
                    {
                      "name": "location",
                      "in": "path",
                      "description": "City or location to retrieve the weather for",
                      "required": true,
                      "schema": { "type": "string" }
                    },
                    {
                      "name": "format",
                      "in": "query",
                      "description": "Format in which to return data. Always use 3.",
                      "required": true,
                      "schema": { "type": "integer", "default": 3 }
                    }
                  ],
                  "responses": {
                    "200": {
                      "description": "Successful response",
                      "content": {
                        "text/plain": {
                          "schema": { "type": "string" }
                        }
                      }
                    },
                    "404": { "description": "Location not found" }
                  }
                }
              }
            }
          }
        }
      }
    ]
  }'

API anahtarı kimlik doğrulaması (proje bağlantısı)

curl --request POST \
  --url "$FOUNDRY_PROJECT_ENDPOINT/openai/v1/responses" \
  --header "Authorization: Bearer $AGENT_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "'$FOUNDRY_MODEL_DEPLOYMENT_NAME'",
    "input": "Use the OpenAPI tool to get the weather in Seattle, WA today.",
    "tools": [
      {
        "type": "openapi",
        "openapi": {
          "name": "weather",
          "description": "Tool to get weather data",
          "auth": {
            "type": "project_connection",
            "security_scheme": {
              "project_connection_id": "'$WEATHER_APP_PROJECT_CONNECTION_ID'"
            }
          },
          "spec": {
            "openapi": "3.1.0",
            "info": {
              "title": "get weather data",
              "description": "Retrieves current weather data for a location.",
              "version": "v1.0.0"
            },
            "servers": [{ "url": "https://wttr.in" }],
            "paths": {
              "/{location}": {
                "get": {
                  "description": "Get weather information for a specific location",
                  "operationId": "GetCurrentWeather",
                  "parameters": [
                    {
                      "name": "location",
                      "in": "path",
                      "description": "City or location to retrieve the weather for",
                      "required": true,
                      "schema": { "type": "string" }
                    },
                    {
                      "name": "format",
                      "in": "query",
                      "description": "Format in which to return data. Always use 3.",
                      "required": true,
                      "schema": { "type": "integer", "default": 3 }
                    }
                  ],
                  "responses": {
                    "200": {
                      "description": "Successful response",
                      "content": {
                        "text/plain": {
                          "schema": { "type": "string" }
                        }
                      }
                    },
                    "404": { "description": "Location not found" }
                  }
                }
              }
            },
            "components": {
              "securitySchemes": {
                "apiKeyHeader": {
                  "type": "apiKey",
                  "name": "x-api-key",
                  "in": "header"
                }
              }
            },
            "security": [
              { "apiKeyHeader": [] }
            ]
          }
        }
      }
    ]
  }'

Yönetilen kimlik doğrulaması

curl --request POST \
  --url "$FOUNDRY_PROJECT_ENDPOINT/openai/v1/responses" \
  --header "Authorization: Bearer $AGENT_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "'$FOUNDRY_MODEL_DEPLOYMENT_NAME'",
    "input": "Use the OpenAPI tool to get the weather in Seattle, WA today.",
    "tools": [
      {
        "type": "openapi",
        "openapi": {
          "name": "weather",
          "description": "Tool to get weather data",
          "auth": {
            "type": "managed_identity",
            "security_scheme": {
              "audience": "'$MANAGED_IDENTITY_AUDIENCE'"
            }
          },
          "spec": {
            "openapi": "3.1.0",
            "info": {
              "title": "get weather data",
              "description": "Retrieves current weather data for a location.",
              "version": "v1.0.0"
            },
            "servers": [{ "url": "https://wttr.in" }],
            "paths": {
              "/{location}": {
                "get": {
                  "description": "Get weather information for a specific location",
                  "operationId": "GetCurrentWeather",
                  "parameters": [
                    {
                      "name": "location",
                      "in": "path",
                      "description": "City or location to retrieve the weather for",
                      "required": true,
                      "schema": { "type": "string" }
                    },
                    {
                      "name": "format",
                      "in": "query",
                      "description": "Format in which to return data. Always use 3.",
                      "required": true,
                      "schema": { "type": "integer", "default": 3 }
                    }
                  ],
                  "responses": {
                    "200": {
                      "description": "Successful response",
                      "content": {
                        "text/plain": {
                          "schema": { "type": "string" }
                        }
                      }
                    },
                    "404": { "description": "Location not found" }
                  }
                }
              }
            }
          }
        }
      }
    ]
  }'

Bu kod ne yapar?

Bu REST API örneği, farklı kimlik doğrulama yöntemleriyle bir OpenAPI aracının nasıl çağrılacaklarını gösterir. İstek:

  1. Aracıya Seattle'ın hava durumunu soran bir sorgu gönderir.
  2. OpenAPI araç tanımını hava durumu API belirtimine uygun olarak doğrudan içerir.
  3. Açıklamalı alternatifler olarak üç kimlik doğrulama seçeneği (anonim, proje bağlantısı aracılığıyla API anahtarı, yönetilen kimlik) gösterir.
  4. Aracı, hava durumu API'sini çağırır ve biçimlendirilmiş sonuçlar döndürür.

Gerekli girişler

  • Ortam değişkenleri: FOUNDRY_PROJECT_ENDPOINT, AGENT_TOKEN, FOUNDRY_MODEL_DEPLOYMENT_NAME.
  • API anahtarı kimlik doğrulaması için: WEATHER_APP_PROJECT_CONNECTION_ID.
  • Yönetilen kimlik doğrulaması için: MANAGED_IDENTITY_AUDIENCE.
  • İstek gövdesinde satır içi OpenAPI belirtimi.

Beklenen çıkış

{
  "id": "resp_abc123",
  "object": "response",
  "output": [
    {
      "type": "message",
      "content": [
        {
          "type": "text",
          "text": "The weather in Seattle, WA today is cloudy with a temperature of 52°F (11°C)..."
        }
      ]
    }
  ]
}

Yaygın hatalar

  • 401 Unauthorized: OpenAPI belirtiminizde geçersiz veya eksik AGENT_TOKEN, veya API anahtarı eklenmedi çünkü securitySchemes ve security eksik.
  • 404 Not Found: Yanlış uç nokta veya model dağıtım adı
  • 400 Bad Request: Hatalı biçimlendirilmiş OpenAPI belirtimi veya geçersiz kimlik doğrulama yapılandırması
  • API anahtarı istekle gönderilmedi: OpenAPI belirtimlerinizdeki bölümün components.securitySchemes düzgün yapılandırıldığını (boş olmadığını) ve proje bağlantı anahtarı adınızla eşleşip eşleşmediğini doğrulayın

OpenAPI aracı özelliklerine sahip bir ajan oluşturun

Aşağıdaki TypeScript kod örneği, OpenApiTool ve zaman uyumlu Azure AI Projeleri istemcisini kullanarak OpenAPI araç özellikleriyle yapay zeka aracısının nasıl oluşturulacağını gösterir. Aracı, OpenAPI belirtimleri tarafından tanımlanan dış API'leri çağırabilir. Bu örneğin JavaScript sürümü için, GitHub javascript deposu için Azure SDK sample bölümüne bakın.

import { DefaultAzureCredential } from "@azure/identity";
import {
  AIProjectClient,
  OpenApiTool,
  OpenApiFunctionDefinition,
  OpenApiAnonymousAuthDetails,
} from "@azure/ai-projects";
import * as fs from "fs";
import * as path from "path";

// Format: "https://resource_name.ai.azure.com/api/projects/project_name"
const PROJECT_ENDPOINT = "your_project_endpoint";
const weatherSpecPath = path.resolve(__dirname, "../assets", "weather_openapi.json");

function loadOpenApiSpec(specPath: string): unknown {
  if (!fs.existsSync(specPath)) {
    throw new Error(`OpenAPI specification not found at: ${specPath}`);
  }

  try {
    const data = fs.readFileSync(specPath, "utf-8");
    return JSON.parse(data);
  } catch (error) {
    throw new Error(`Failed to read or parse OpenAPI specification at ${specPath}: ${error}`);
  }
}

function createWeatherTool(spec: unknown): OpenApiTool {
  const auth: OpenApiAnonymousAuthDetails = { type: "anonymous" };
  const definition: OpenApiFunctionDefinition = {
    name: "get_weather",
    description: "Retrieve weather information for a location using wttr.in",
    spec,
    auth,
  };

  return {
    type: "openapi",
    openapi: definition,
  };
}

export async function main(): Promise<void> {
  const weatherSpec = loadOpenApiSpec(weatherSpecPath);

  // Create clients to call Foundry API
  const project = new AIProjectClient(PROJECT_ENDPOINT, new DefaultAzureCredential());
  const openai = project.getOpenAIClient();

  // Create an agent with the OpenAPI weather tool
  const agent = await project.agents.createVersion("MyOpenApiAgent", {
    kind: "prompt",
    model: "gpt-4.1-mini",
    instructions:
      "You are a helpful assistant that can call external APIs defined by OpenAPI specs to answer user questions.",
    tools: [createWeatherTool(weatherSpec)],
  });

  // Send a request and stream the response
  const streamResponse = await openai.responses.create(
    {
      input:
        "What's the weather in Seattle and how should I plan my outfit for the day based on the forecast?",
      stream: true,
    },
    {
      body: {
        agent: { name: agent.name, type: "agent_reference" },
        tool_choice: "required",
      },
    },
  );

  // Process the streaming response
  for await (const event of streamResponse) {
    if (event.type === "response.output_text.delta") {
      process.stdout.write(event.delta);
    } else if (event.type === "response.output_text.done") {
      console.log("\n");
    }
  }

  // Clean up resources
  await project.agents.deleteVersion(agent.name, agent.version);
}

main().catch((err) => {
  console.error("The sample encountered an error:", err);
});

Bu kod ne yapar?

Bu TypeScript örneği, anonim kimlik doğrulaması kullanarak hava durumu verileri için OpenAPI aracıyla bir aracı oluşturur. Kodu çalıştırdığınızda:

  1. Yerel bir JSON dosyasından hava Durumu OpenAPI belirtimini yükler.
  2. Hava durumu aracının yapılandırıldığı bir aracı oluşturur.
  3. Seattle'ın hava durumu ve kıyafet planlaması hakkında soru soran bir akış isteği gönderir.
  4. Akış yanıtını işler ve deltaları geldikçe görüntüler.
  5. tool_choice: "required" kullanarak API'nin çağrıldığından emin olmak için araç kullanımını zorlar.
  6. Aracıyı silerek temizler.

Gerekli girişler

  • Satır içi dize değeri: PROJECT_ENDPOINT (Dökümhane proje uç noktanız)
  • Yerel dosya: ../assets/weather_openapi.json (OpenAPI belirtimi)

Beklenen çıkış

Loading OpenAPI specifications from assets directory...
Creating agent with OpenAPI tool...
Agent created (id: asst_abc123, name: MyOpenApiAgent, version: 1)

Sending request to OpenAPI-enabled agent with streaming...
Follow-up response created with ID: resp_xyz789
The weather in Seattle is currently...
Tool call completed: get_weather

Follow-up completed!

Cleaning up resources...
Agent deleted

OpenAPI agent sample completed!

Yaygın hatalar

  • Error: OpenAPI specification not found: Dosya yolu yanlış veya dosya eksik
  • AuthenticationError: Geçersiz Azure kimlik bilgileri
  • API anahtarı çalışmıyor: Anonim kimlik doğrulamasından API anahtarı kimlik doğrulamasına geçiş yapıyorsanız, OpenAPI belirtiminizin ve securitySchemes, security yapılandırmalarınızın düzgün ayarlandığından emin olun.

Proje bağlantısıyla kimliği doğrulanmış OpenAPI araçlarını kullanan bir aracı oluşturma

Aşağıdaki TypeScript kod örneği, proje bağlantısı aracılığıyla kimliği doğrulanmış OpenAPI araçlarını kullanan bir yapay zeka aracısının nasıl oluşturulacağını gösterir. Aracı, yerel varlıklardan TripAdvisor OpenAPI belirtimini yükler ve api'yi yapılandırılan proje bağlantısı aracılığıyla çağırabilir. Bu örneğin JavaScript sürümü için, GitHub javascript deposu için Azure SDK sample bölümüne bakın.

import { DefaultAzureCredential } from "@azure/identity";
import {
  AIProjectClient,
  OpenApiTool,
  OpenApiFunctionDefinition,
  OpenApiProjectConnectionAuthDetails,
} from "@azure/ai-projects";
import * as fs from "fs";
import * as path from "path";

// Format: "https://resource_name.ai.azure.com/api/projects/project_name"
const PROJECT_ENDPOINT = "your_project_endpoint";
const TRIPADVISOR_CONNECTION_ID = "your-tripadvisor-connection-id";
const tripAdvisorSpecPath = path.resolve(__dirname, "../assets", "tripadvisor_openapi.json");

function loadOpenApiSpec(specPath: string): unknown {
  if (!fs.existsSync(specPath)) {
    throw new Error(`OpenAPI specification not found at: ${specPath}`);
  }

  try {
    const data = fs.readFileSync(specPath, "utf-8");
    return JSON.parse(data);
  } catch (error) {
    throw new Error(`Failed to read or parse OpenAPI specification at ${specPath}: ${error}`);
  }
}

function createTripAdvisorTool(spec: unknown): OpenApiTool {
  const auth: OpenApiProjectConnectionAuthDetails = {
    type: "project_connection",
    security_scheme: {
      project_connection_id: TRIPADVISOR_CONNECTION_ID,
    },
  };

  const definition: OpenApiFunctionDefinition = {
    name: "get_tripadvisor_location_details",
    description:
      "Fetch TripAdvisor location details, reviews, or photos using the Content API via project connection auth.",
    spec,
    auth,
  };

  return {
    type: "openapi",
    openapi: definition,
  };
}

export async function main(): Promise<void> {
  const tripAdvisorSpec = loadOpenApiSpec(tripAdvisorSpecPath);

  // Create clients to call Foundry API
  const project = new AIProjectClient(PROJECT_ENDPOINT, new DefaultAzureCredential());
  const openai = project.getOpenAIClient();

  // Create an agent with the OpenAPI project-connection tool
  const agent = await project.agents.createVersion("MyOpenApiConnectionAgent", {
    kind: "prompt",
    model: "gpt-4.1-mini",
    instructions:
      "You are a travel assistant that consults the TripAdvisor Content API via project connection to answer user questions about locations.",
    tools: [createTripAdvisorTool(tripAdvisorSpec)],
  });

  // Send a request and stream the response
  const streamResponse = await openai.responses.create(
    {
      input:
        "Provide a quick overview of the TripAdvisor location 293919 including its name, rating, and review count.",
      stream: true,
    },
    {
      body: {
        agent: { name: agent.name, type: "agent_reference" },
        tool_choice: "required",
      },
    },
  );

  // Process the streaming response
  for await (const event of streamResponse) {
    if (event.type === "response.output_text.delta") {
      process.stdout.write(event.delta);
    } else if (event.type === "response.output_text.done") {
      console.log("\n");
    }
  }

  // Clean up resources
  await project.agents.deleteVersion(agent.name, agent.version);
}

main().catch((err) => {
  console.error("The sample encountered an error:", err);
});

Bu kod ne yapar?

Bu TypeScript örneği, proje bağlantısı aracılığıyla API anahtarı kimlik doğrulaması ile OpenAPI aracının kullanılmasını gösterir. Kodu çalıştırdığınızda:

  1. TripAdvisor OpenAPI belirtimini yerel bir dosyadan yükler.
  2. Kimlik doğrulamasını TRIPADVISOR_CONNECTION_ID sabiti kullanarak yapılandırır.
  3. TripAdvisor aracı kullanan ve API anahtarı kimlik doğrulaması için proje bağlantısını kullanan bir ajan oluşturur.
  4. TripAdvisor konum ayrıntıları için bir aktarım isteği gönderir.
  5. tool_choice: "required" kullanarak API'nin çağrıldığından emin olmak için araç kullanımını zorlar.
  6. Akış yanıtını anında işler ve görüntüler.
  7. Aracıyı silerek temizleme işlemi gerçekleştirilir.

Gerekli girişler

  • Satır içi dize değerleri: PROJECT_ENDPOINT, TRIPADVISOR_CONNECTION_ID
  • Yerel dosya: ../assets/tripadvisor_openapi.json
  • TripAdvisor API anahtarıyla yapılandırılmış Project bağlantısı

Beklenen çıkış

Loading TripAdvisor OpenAPI specification from assets directory...
Creating agent with OpenAPI project-connection tool...
Agent created (id: asst_abc123, name: MyOpenApiConnectionAgent, version: 1)

Sending request to TripAdvisor OpenAPI agent with streaming...
Follow-up response created with ID: resp_xyz789
Location 293919 is the Eiffel Tower in Paris, France. It has a rating of 4.5 stars with over 140,000 reviews...
Tool call completed: get_tripadvisor_location_details

Follow-up completed!

Cleaning up resources...
Agent deleted

TripAdvisor OpenAPI agent sample completed!

Yaygın hatalar

  • Error: OpenAPI specification not found: Dosya yolunu denetleyin.
  • Bağlantı bulunamadı: Doğru olduğunu ve bağlantının mevcut olduğunu doğrulayın TRIPADVISOR_CONNECTION_ID .
  • AuthenticationException: Proje bağlantısında geçersiz API anahtarı.
  • api anahtarı isteklere eklenmedi: OpenAPI belirtiminiz düzgün securitySchemes (altında components) ve security bölümler içermelidir. içindeki securitySchemes anahtar adı proje bağlantınızdaki anahtarla eşleşmelidir.
  • Content type is not supported: Şu anda yalnızca şu iki istek gövdesi içerik türü desteklenir: application/json ve application/json-patch+json. Yanıt içerik türleri kısıtlanmamıştır.

Güvenlik ve veriyle ilgili dikkat edilmesi gerekenler

Bir aracıyı OpenAPI aracısına bağladığınızda, aracı kullanıcı girişinden türetilen istek parametrelerini hedef API'ye gönderebilir.

  • Gizli diziler (API anahtarları ve belirteçler) için proje bağlantılarını kullanın. Gizli bilgileri OpenAPI belirtim dosyasına veya kaynak koduna yerleştirmekten kaçının.
  • Aracı üretimde kullanmadan önce API'nin aldığı verileri ve döndürdüğü verileri gözden geçirin.
  • En az ayrıcalıklı erişimi kullanın. Yönetilen kimlik için yalnızca hedef hizmetin gerektirdiği rolleri atayın.

API anahtarıyla kimlik doğrulaması

API anahtarı kimlik doğrulamasını kullanarak, API anahtarı veya Taşıyıcı belirteci gibi çeşitli yöntemleri kullanarak OpenAPI belirtiminizin kimliğini doğrulayabilirsiniz. OpenAPI belirtimi başına yalnızca bir API anahtarı güvenlik şeması kullanabilirsiniz. Birden çok güvenlik şemasına ihtiyacınız varsa, birden çok OpenAPI belirtimi aracı oluşturun.

  1. OpenAPI belirtim güvenlik şemalarınızı güncelleştirin. securitySchemes bölümü ve apiKey türünde bir şeması vardır. Örneğin:

     "securitySchemes": {
     "apiKeyHeader": {
             "type": "apiKey",
             "name": "x-api-key",
             "in": "header"
         }
 }

    Genellikle yalnızca bağlantıdaki name adına key karşılık gelen alanı güncelleştirmeniz gerekir. Güvenlik düzenleri birden çok düzen içeriyorsa, bunlardan yalnızca birini tutun.

  2. OpenAPI belirtiminizi security bölümü içerecek şekilde güncelleyin.

    "security": [
     {  
     "apiKeyHeader": []  
     }  
 ]

  3. Bu makalenin ilerleyen bölümlerinde açıklandığı gibi, API anahtarı depolandığından ve bağlantı üzerinden geçirildiğinden, OpenAPI belirtiminde API anahtarı gerektiren tüm parametreleri kaldırın.

  4. API anahtarınızı depolamak için bir bağlantı oluşturun.

  5. Dökümhane portalına gidin ve projenizi açın.

  6. Gizli bilgiyi depolayan bir bağlantı oluşturun veya seçin. Bkz. Projenize yeni bağlantı ekleme.

    Not

    API anahtarını daha sonraki bir tarihte yeniden oluşturursanız, bağlantıyı yeni anahtarla güncelleştirmeniz gerekir.

  7. Aşağıdaki bilgileri girin

    • key: name güvenlik düzeninizin alanı. Bu örnekte, x-api-key

             "securitySchemes": {
          "apiKeyHeader": {
                    "type": "apiKey",
                    "name": "x-api-key",
                    "in": "header"
                }
        }

    • değer: YOUR_API_KEY

  8. Bağlantı oluşturduktan sonra SDK veya REST API aracılığıyla kullanabilirsiniz. Kod örneklerini görmek için bu makalenin üst kısmındaki sekmeleri kullanın.

Bearer jetonu bağlantısı kurma

API anahtarları için kullanılan project_connection kimlik doğrulama türüyle birlikte belirteç tabanlı kimlik doğrulamasını (örneğin, Taşıyıcı belirteç) kullanabilirsiniz. Önemli fark, hem OpenAPI belirtimini hem de proje bağlantısını nasıl yapılandırdığınızdır.

OpenAPI belirtiminiz şu şekilde görünür:

  BearerAuth:
    type: http
    scheme: bearer
    bearerFormat: JWT

Yapmanız gerekenler:

  1. OpenAPI belirtiminizi securitySchemes üst bilgi adı olarak Authorization kullanmak için güncelleyin.

    "securitySchemes": {
    "bearerAuth": {
        "type": "apiKey",
        "name": "Authorization",
        "in": "header"
    }
}

  2. Şemaya başvuran bir security bölüm ekleyin:

    "security": [
    {
        "bearerAuth": []
    }
]

  3. Foundry projenizde Özel anahtarlar bağlantısı oluşturun:

    1. Dökümhane portalına gidin ve projenizi açın.
    2. Gizli bilgiyi depolayan bir bağlantı oluşturun veya seçin. Bkz. Projenize yeni bağlantı ekleme.
    3. Aşağıdaki değerleri girin:
      • key: Authorization (sizin securitySchemes içinde yer almakta olan name alanıyla eşleşmelidir)
      • value: Bearer <token> (değerini gerçek belirtecinizle değiştirin <token> )

    Önemli

    Değer, belirtecin önüne bir boşluk eklenerek sözcüğü Bearer içermelidir. Örneğin: Bearer eyJhbGciOiJSUzI1NiIs.... atlarsanız Bearer , API gerekli yetkilendirme şeması ön eki olmadan bir ham belirteç alır ve istek başarısız olur.

  4. Bağlantıyı oluşturduktan sonra, API anahtar kimlik doğrulaması için yaptığınız gibi kodunuzda project_connection kimlik doğrulama türünü kullanın. Bağlantı kimliği aynı biçimi kullanır: /subscriptions/{{subscriptionID}}/resourceGroups/{{resourceGroupName}}/providers/Microsoft.CognitiveServices/accounts/{{foundryAccountName}}/projects/{{foundryProjectName}}/connections/{{foundryConnectionName}}.

Yönetilen kimliği kullanarak (Microsoft Entra ID) kimlik doğrulaması yapın.

Microsoft Entra ID çalışanlarınızın dış kaynaklara erişmek için kullanabileceği bulut tabanlı bir kimlik ve erişim yönetimi hizmetidir. Microsoft Entra ID kullanarak API anahtarlarını kullanmanıza gerek kalmadan API'lerinize ek güvenlik ekleyebilirsiniz. Yönetilen kimlik doğrulamasını ayarladığınızda, ajan Foundry aracını kullanarak kimlik doğrulamasını gerçekleştirir.

Önemli

Yönetilen kimlik kimlik doğrulaması yalnızca hedef hizmet Microsoft Entra ID belirteçleri kabul ettiğinde çalışır. Hedef API Microsoft Entra ID desteklemeyen bir özel kimlik doğrulama düzeni kullanıyorsa bunun yerine API anahtarı veya Bearer belirteci kimlik doğrulamasını kullanın.

hedef kitle URI'sini anlama

audience (bazen kaynak tanımlayıcısı veya Uygulama Kimliği URI), belirtecin hangi hizmete veya API'ye erişmeyi amaçladığını, Microsoft Entra ID'ye belirtir. Hedef kitle değeri hedef hizmetin beklediği değerle eşleşmelidir veya kimlik doğrulaması 401 hatasıyla başarısız olur.

Not

İzleyici kitlesi, Foundry proje uç noktanız değildir. OpenAPI aracınızın çağırdığını hedef hizmetin kaynak tanımlayıcısıdır.

Aşağıdaki tabloda, yaygın Azure hizmetleri için hedef kitle URI'leri listelenmektedir:

Hedef hizmet hedef kitle URI'si
Azure Depolama https://storage.azure.com
Azure Key Vault https://vault.azure.net
Azure Yapay Zeka Arama https://search.azure.com
Azure Logic Apps https://logic.azure.com
Azure API Management (yönetim düzlemi) https://management.azure.com
Microsoft Entra uygulama kaydıyla korunan API (OAuth ile APIM dahil) Uygulama kaydınızdaki Uygulama Kimliği URI'si (örneğin, api://<client-id>)

Ipucu

OAuth 2.0 doğrulama ilkesiyle özel bir API'yi korumak için Azure API Management kullanırsanız hedef kitle, değil API'yi koruyan uygulama kaydından https://management.azure.com olur. Yönetim düzlemi hedef kitlesi yalnızca APIM kaynağının kendisinde Azure Resource Manager işlemler için geçerlidir.

Ajanların Microsoft Entra Kimliği ile nasıl kimlik doğruladıkları hakkında daha fazla bilgi için bkz. Agent identity and authentication.

Hedef kitlenizi bulma ve doğrulama

Doğru hedef kitle değerini belirlemek ve doğrulamak için aşağıdaki adımları kullanın:

  • Azure hizmetleri için: hizmetin Microsoft Entra ID kaynak tanımlayıcısı belgelerine bakın. çoğu Azure hizmet, kimlik doğrulama belgelerinde hedef kitle URI'sini listeler.
  • Microsoft Entra uygulama kaydıyla korunan API'ler için: Azure portalında, Microsoft Entra ID>Uygulama Kayıtları> seçin ve uygulamanızı seçin, ardından >Bir API'yi Görüntüle. Sayfanın üst kısmındaki Uygulama Kimliği URI'si hedef kitlenizin değeridir.
  • Belirtecin hedef kitlesini doğrulamak için: Erişim belirtecini https://jwt.ms çözümleyin ve aud talebini denetleyin. Değer aud , hedef hizmetinizin beklediği hedef kitleyle eşleşmelidir.

Yönetilen kimlik doğrulamayı ayarlama

Yönetilen Kimlik kullanarak kimlik doğrulamasını ayarlamak için:

  1. Foundry kaynağınızda sistem tarafından atanmış yönetilen kimliğin etkinleştirildiğinden emin olun.

    Azure portalında yönetilen kimlik seçicisini gösteren ekran görüntüsü.

  2. OpenAPI belirtimi aracılığıyla bağlanmak istediğiniz hizmet için bir kaynak oluşturun.

  3. Kaynağa uygun erişim atayın.

    1. Kaynağınız için Access Control seçin.

    2. Ekle'yi seçin ve ardından ekranın üst kısmında rol ataması ekleyin.

      Azure portalda rol atama seçicisini gösteren bir ekran görüntüsü.

    3. Gereken uygun rol atamasını seçin; genellikle en azından OKUYUCU rolünü gerektirir. Ardından İleri'yi seçin.

    4. Yönetilen kimlik'i ve ardından üyeleri seç'i seçin.

    5. Yönetilen kimlik açılır menüsünde Foundry hesabı arayın ve ardından aracınızın Foundry hesabını seçin.

    6. Son'u seçin.

  4. Kurulumu tamamladığınızda, Aracı Kullanarak Döküm Portalı, SDK veya REST API aracılığıyla devam edebilirsiniz. Kod örneklerini görmek için bu makalenin üst kısmındaki sekmeleri kullanın.

Yaygın hataları giderme

Semptom Olası neden Çözünürlük
API anahtarı isteklere dahil değildir. OpenAPI belirtimi dosyası securitySchemes veya security bölümler eksik. OpenAPI belirtiminizin hem components.securitySchemes hem de üst düzey security bölümü içerdiğini doğrulayın. Düzenin name proje bağlantınızdaki anahtar adıyla eşleştiğinden emin olun.
Aracı OpenAPI aracını çağırmaz. Araç seçimi ayarlanmadı veya operationId açıklayıcı değil. Araç çağrılmasını zorlamak için tool_choice="required" kullanın. Modelin doğru işlemi seçebilmesi için değerlerin açıklayıcı olduğundan emin olun operationId .
Yönetilen kimlik için kimlik doğrulaması başarısız oluyor. Yönetilen kimlik etkinleştirilmedi veya rol ataması eksik. Foundry kaynağınızda sistem tarafından atanan yönetilen kimliği etkinleştirin. Hedef hizmette gerekli rolü ("Okuyucu" veya üzeri) atayın.
Yönetilen kimlik, rol atanmış olsa bile 401 döndürür. Hedef kitle URI'si hedef hizmetin beklediğiyle eşleşmiyor. hedef kitle URI'sinin hedef hizmetin kaynak tanımlayıcısı ile eşleştiğinden emin olun. Azure hizmetleri için hizmet belgelerine bakın. Microsoft Entra korumalı API'ler için uygulama kaydınızdaki Uygulama Kimliği URI'sini kullanın. adresinde belirtecin https://jwt.ms kodunu çözerek talep eşleşmelerini aud onaylayın. Bkz. İzleyici URI'sini anlama.
Yönetilen kimlik belirteci hedef API tarafından reddedildi. Hedef hizmet Microsoft Entra ID jetonlarını kabul etmez. Hedef hizmetin Microsoft Entra ID kimlik doğrulamasını desteklediğini onaylayın. Aksi takdirde API anahtarı veya Bearer jetonu kimlik doğrulama için kullanın.
İstek 400 Hatalı İstek ile başarısız oluyor. OpenAPI belirtimi gerçek API ile eşleşmiyor. OpenAPI belirtiminizi gerçek API'ye göre doğrulayın. Parametre adlarını, türlerini ve gerekli alanları denetleyin.
İstek 401 Yetkisiz ile başarısız oluyor. API anahtarı veya belirteci geçersiz veya süresi dolmuş. API anahtarını/belirtecini yeniden oluşturun ve proje bağlantınızı güncelleştirin. Bağlantı kimliğinin doğru olduğunu doğrulayın.
Araç beklenmeyen yanıt biçimi döndürür. Yanıt şeması OpenAPI belirtiminde tanımlanmadı. Daha iyi model anlamak için OpenAPI belirtiminize yanıt şemaları ekleyin.
operationId doğrulama hatası. içinde operationIdgeçersiz karakterler. Yalnızca harfleri, - ve _ etiketlerini operationId değerlerinde kullanın. Sayıları ve özel karakterleri kaldırın.
Bağlantı bulunamadı hatası. Bağlantı adı veya kimlik uyuşmazlığı. Bağlantı adı Foundry projenizde eşleşiyor mu diye OPENAPI_PROJECT_CONNECTION_NAME doğrulayın.
Taşıyıcı token doğru gönderilmedi. Bağlantı değeri için başlangıç kodu Bearer eksik. Bağlantı değerini Bearer <token> olarak ayarlayın (belirteci kullanmadan önce sözcüğü Bearer ve boşluk bırakın). OpenAPI belirtiminin securitySchemes kullandığını "name": "Authorization"doğrulayın.

Kimlik doğrulama yöntemi seçme

Aşağıdaki tablo, OpenAPI aracınız için doğru kimlik doğrulama yöntemini seçmenize yardımcı olur:

Kimlik doğrulama yöntemi En iyisi için Kurulum karmaşıklığı
Anonim Kimlik doğrulaması olmayan genel API'ler Düşük
API anahtarı Anahtar tabanlı erişime sahip Microsoft olmayan API'ler Orta
Yönetilen kimlik Azure hizmetleri ve Microsoft Entra ID korumalı API'ler. Hedef hizmetin, Microsoft Entra ID belirteçlerini kabul etmesi ve Azure RBAC veya Microsoft Entra tabanlı erişim denetimini desteklemesi gerekir. Orta-Yüksek

İlgili içerik

  • Last updated on