Integracja interfejsu API i zestaw narzędzi Code Assist

Aby przyspieszyć migrację do Merchant API i tworzenie nowych integracji za pomocą narzędzi programistycznych opartych na AI, użyj pakietu API Integration and Code Assist Toolkit.

Przegląd

Podczas migracji z Content API for Shopping do Merchant API lub tworzenia nowej integracji musisz poznać nowe struktury usług, nazwy zasobów i metody. Narzędzia programistyczne oparte na AI są szczególnie przydatne w przypadku tych operacji:

  • Tłumaczenie i migracja kodu: pomaga zrozumieć i przekonwertować starszy kod Content API for Shopping na nowy format Merchant API. Obejmuje to mapowanie atrybutów produktu na nową strukturę i aktualizowanie plików zarządzania zależnościami.
  • Wiedza o dokumentacji interfejsu API: zawiera jasne wyjaśnienia dotyczące zasobów, metod, pól, limitów i sprawdzonych metod Merchant API na podstawie wiarygodnego kontekstu z oficjalnej dokumentacji interfejsu API Google.
  • Generowanie kodu: generuje fragmenty kodu do różnych zadań Merchant API w językach takich jak Python, Java, PHP i inne.
  • Rozwiązywanie problemów: pomaga w diagnozowaniu i naprawianiu typowych błędów interfejsu API.

Wybierz opcję, która najlepiej pasuje do Twojego środowiska programistycznego i konkretnego przypadku użycia. Aby dostosować konfigurację do preferowanego przepływu pracy, użyj pakietu API Integration and Code Assist Toolkit:

Poniższy diagram przedstawia opcje konfiguracji migracji kodu z pomocą AI w najczęściej używanych zintegrowanych środowiskach programistycznych (IDE), takich jak Antigravity, Visual Studio Code, Cursor czy Copilot. Można skonfigurować asystentów kodowania, takich jak Gemini, Claude, ChatGPT czy Grok, i wzbogacić ich możliwości za pomocą serwera MCP dokumentacji dla deweloperów Merchant API lub umiejętności agenta Merchant API, aby zwiększyć ich wiarygodność i przyspieszyć integrację.

(Merchant API) Diagram asystenta kodowania integracji AI

Serwer MCP dokumentacji dla programistów Merchant API

Uzyskaj informacje kontekstowe o Merchant API od wybranego asystenta kodowania. W zintegrowanym środowisku programistycznym możesz teraz uzyskać dostęp do dokumentacji dla programistów za pomocą usługi Model Context Protocol (MCP). Ta usługa przekazuje asystentowi kodowania kluczowe informacje z oficjalnej dokumentacji API Google. Więcej informacji o samym protokole znajdziesz w standardzie Model Context Protocol.

Jak to działa

Gdy zadajesz pytanie asystentowi kodowania w IDE z włączonym protokołem MCP dotyczące Merchant API, usługa pobiera najbardziej odpowiednie fragmenty tekstu i kodu z oficjalnych zasobów i zwraca je jako kontekst do asystenta kodowania za pomocą specjalnego backendu generowania wspomaganego wyszukiwaniem (RAG). System RAG to system, który poprawia jakość odpowiedzi z modeli LLM, łącząc je z zewnętrznymi, aktualnymi źródłami wiedzy. Dzięki temu asystent może udzielać dokładnych i aktualnych odpowiedzi bez konieczności opuszczania środowiska programistycznego.

Przykładowy przepływ pracy:

  1. Zadajesz pytanie asystentowi kodowania lub agentowi zgodnemu z protokołem MCP (np. pytanie w języku naturalnym, prośba o przykładowy kod lub tłumaczenie kodu).
  2. Asystent kodowania wysyła żądanie kontekstu do punktu końcowego MCP.
  3. Usługa MCP przeszukuje zindeksowany zbiór oficjalnej dokumentacji, przewodników i przykładowych kodów Merchant API.
  4. Usługa zwraca wiarygodne fragmenty jako kontekst do asystenta kodowania.
  5. Asystent kodowania wykorzystuje ten kontekst do wygenerowania wiarygodnej odpowiedzi lub zadania tłumaczenia kodu.

Pierwsze kroki

Aby zintegrować i używać protokołu MCP, wykonaj te czynności:

1. Użyj zgodnego narzędzia

Otwórz zintegrowane środowisko programistyczne lub asystenta kodowania, który obsługuje protokół Model Context Protocol z transportem HTTP z możliwością przesyłania strumieniowego.

2. Skonfiguruj punkt końcowy

Aby połączyć zintegrowane środowisko programistyczne lub asystenta kodowania z protokołem MCP, użyj podanych szczegółów zdalnego punktu końcowego, które mogą wymagać wpisania bezpośredniego adresu URL usługi lub definicji MCP w zależności od konfiguracji narzędzia:

Ustawienia konfiguracji:

Antigravity

Postępuj zgodnie z instrukcjami w dokumentacji Antigravity.

"mcpServers": {
  "mapi-devdocs": {
    "command": "npx",
    "args": [
      "-y",
      "mcp-remote",
      "https://merchantapi.googleapis.com/devdocs/mcp"
    ]
  }
}

Visual Studio Code

Postępuj zgodnie z instrukcjami w dokumentacji Visual Studio Code.

"servers": {
"mapi-devdocs": {
  "type": "http",
  "url": "https://merchantapi.googleapis.com/devdocs/mcp/"
  }
}

3. Dodaj instrukcje dla agenta (opcjonalnie)

Aby umożliwić agentowi bezpośrednie tłumaczenie kodu za pomocą protokołu MCP, podaj mu instrukcje systemowe: Merchant Integrator Agent Protocol. Te instrukcje pomagają agentowi prawidłowo korzystać z protokołu MCP do tłumaczenia kodu. W zależności od narzędzia możesz podać te instrukcje w konfiguracji instrukcji systemowych lub jako dodatkowy plik kontekstu dla agenta.

Przykładowe scenariusze użycia

Protokół MCP może przyspieszyć przepływ pracy w tych typowych przypadkach użycia:

Scenariusz 1. Migracja kodu products.insert

Możesz poprosić agenta o bezpośrednią migrację kodu integracji products.insert Content API for Shopping do Merchant API.

Prompt użytkownika:

„Migruj kod products.insert do Merchant API”

Jeśli podasz agentowi instrukcje systemowe i dostęp do protokołu MCP, agent może tłumaczyć kod Content API for Shopping na kod Merchant API bezpośrednio w zintegrowanym środowisku programistycznym. W tym przypadku zidentyfikuje productInputs.insert jako równoważne wywołanie i zmapuje atrybuty produktu ze starego formatu na nowy format wymagany przez Merchant API. Może też zaktualizować wymagane importy i plik zarządzania zależnościami (np. requirements.txt, pom.xml lub package.json). Możesz poprosić agenta o wprowadzenie zmian w miejscu lub utworzenie nowego folderu.

Scenariusz 2. Znajdowanie równoważnej funkcjonalności

Masz istniejącą aplikację korzystającą z Content API for Shopping i musisz ją zaktualizować. Możesz zapytać o konkretną starszą metodę, aby uzyskać szczegółowe informacje o nowej implementacji i odpowiedni przykładowy kod.

Prompt użytkownika:

„Jaki jest odpowiednik metody `accountstatuses.get` w Content API for Shopping w Merchant API?”

Usługa MCP udostępnia kontekst z oficjalnych przewodników migracji i dokumentacji, dzięki czemu asystent może odpowiedzieć szczegółowo, w tym podać nową nazwę interfejsu API, accounts.issues.

Scenariusz 3. Znajdowanie przykładowego kodu

Implementujesz nową funkcję i potrzebujesz praktycznego przykładu.

Prompt użytkownika:

„Pokaż mi przykładowy kod w Pythonie, który dodaje nową usługę dostawy za pomocą Merchant API”.

Usługa MCP pobiera odpowiednie przykłady kodu z oficjalnych repozytoriów Google na GitHubie i przewodników dla programistów. Asystent może wtedy przedstawić kompletny blok kodu gotowy do dostosowania.

Scenariusz 4. Poznawanie koncepcji interfejsu API

Natrafiasz na nową koncepcję lub chcesz poznać strukturę zasobu albo ogólny wzorzec Merchant API.

Prompt użytkownika:

„Jak zaktualizować stan magazynowy produktu za pomocą Merchant API?”

Usługa MCP zwraca kontekst z dokumentacji zasobu products i odpowiednich przewodników. Asystent może wtedy wyjaśnić, jak używać metody accounts.productInputs.insert, i podać częściowy zasób produktu zawierający tylko productId i pola związane ze stanem magazynowym, które musisz zaktualizować.

„Jak autoryzować wywołania aplikacji za pomocą Merchant API?”

Usługa MCP pobiera kontekst z oficjalnych przewodników uwierzytelniania, które obejmują różne metody autoryzacji. Asystent może wtedy wyjaśnić dostępne opcje podstawowe, takie jak używanie konta usługi do interakcji między serwerami lub identyfikatora klienta OAuth 2.0 podczas działania w imieniu użytkownika.

Scenariusz 5. Dostosowywanie się do zmian w interfejsie API

Merchant API wprowadza nowe wzorce, takie jak grupowanie żądań, które różnią się od Content API for Shopping. Content API for Shopping używa konkretnych metod custombatch, a Merchant API – wbudowanej, ogólnej funkcji grupowania HTTP.

Prompt użytkownika:

„Jaki jest nowy sposób wykonywania `products.custombatch` w Merchant API?”

Usługa MCP pobiera kontekst z Refactor code for concurrent requests wyjaśniając, że w Merchant API nie ma dedykowanych metod custombatch. Zamiast tego udostępnia dokumentację dotyczącą używania grupowania HTTP z wartością multipart w nagłówku Content-Type. Asystent może wtedy wyjaśnić, jak utworzyć jedno żądanie HTTP zawierające wiele wywołań interfejsu API, wysłane do punktu końcowego https://merchantapi.googleapis.com/batch/{sub-api}/v1, i podać przykład struktury żądania wieloczęściowego. Dzięki temu potencjalnie mylące zadanie migracji staje się procesem z przewodnikiem.

Scenariusz 6. Tłumaczenie zapytania dotyczącego raportowania

Możesz poprosić agenta o przetłumaczenie zapytania dotyczącego raportowania z Content API for Shopping na Merchant API.

Prompt użytkownika:

„Przenieś to zapytanie dotyczące raportowania z Content API do Merchant API: SELECT metrics.impressions, metrics.clicks, metrics.ctr FROM MerchantPerformanceView WHERE segments.date BETWEEN '2020-12-01' AND '2020-12-30'”

Usługa MCP pobiera najnowszą dokumentację dotyczącą raportowania, przewodniki dla programistów i przewodniki migracji. Na podstawie tych informacji przekształca zapytanie w nową strukturę i aktualizuje pola do nowych nazw i wartości.

Umiejętności agenta Merchant API

Specyfikacja umiejętności agenta to otwarty standard przyjęty w narzędziach programistycznych opartych na AI. Używaj umiejętności agenta, aby zwiększyć wygodę programowania i zoptymalizować zarówno migrację z Content API for Shopping, jak i tworzenie nowych integracji. Umiejętności agenta Merchant API łączą wiedzę i narzędzia specyficzne dla domeny, aby zwiększyć możliwości agentów AI, oraz zapewniają na żądanie pomoc ekspertów w zakresie zapytań dotyczących dokumentacji, generowania kodu i rozwiązywania problemów.

Umiejętności agenta Merchant API są zgodne z różnymi narzędziami wiersza poleceń i zintegrowanymi środowiskami programistycznymi opartymi na AI, takimi jak Gemini i Claude Code.

Jak to działa

Umiejętności agenta Merchant API to specjalny pakiet wiedzy oparty na otwartym standardzie umiejętności agenta. Nasza umiejętność agenta mapi-developer-assistant działa jako inteligentna warstwa między narzędziami programistycznymi opartymi na AI a serwerem MCP dokumentacji dla programistów Merchant API. Zawiera wiedzę o domenie i wskazówki proceduralne, a także te właściwości:

  • Zero konfiguracji: automatycznie zarządza połączeniami z serwerem MCP, eliminując konieczność ręcznej konfiguracji punktu końcowego.
  • Przepływy pracy ekspertów: optymalizuje prompty użytkowników w zapytania, aby skutecznie pobierać najbardziej odpowiednie informacje.
  • Zarządzanie kontekstem i wydajność tokenów: używa „progresywnego ujawniania”, aby wczytywać informacje na żądanie i zachowywać okno kontekstu AI.
  • Ulepszone formatowanie danych wyjściowych: zawiera instrukcje formatowania i strukturyzowania danych wyjściowych, aby uzyskać praktyczne, czytelne i spójne odpowiedzi.

Przykładowy przepływ pracy:

  1. Zadajesz pytanie dotyczące Merchant API w narzędziu programistycznym opartym na AI.
  2. Umiejętność agenta Merchant API analizuje Twoje intencje, formułuje precyzyjne zapytanie i stosuje do żądania swoją wiedzę proceduralną.
  3. Umiejętność agenta wysyła żądanie kontekstu do serwera MCP dokumentacji dla programistów Merchant API znajdującego się pod adresem merchantapi.googleapis.com/devdocs/mcp/.
  4. Usługa MCP przeszukuje zindeksowany zbiór oficjalnej dokumentacji, przewodników i przykładowych kodów Merchant API.
  5. Agent AI wykorzystuje te informacje, aby udzielić syntetycznej i praktycznej odpowiedzi.

Pierwsze kroki

Plik README umiejętności agenta Merchant API zawiera szczegółowe instrukcje dotyczące:

  • Wymagań wstępnych dotyczących narzędzi takich jak narzędzie wiersza poleceń Gemini.
  • Włączania obsługi umiejętności agenta w wybranym narzędziu.
  • Instalowania umiejętności mapi-developer-assistant z repozytorium GitHub zgodnie z instrukcjami w pliku README.
  • Sprawdzania instalacji.
  • Podstawowych poleceń zarządzania umiejętnościami.

Szczegółowe instrukcje instalacji i konfiguracji różnych narzędzi AI, w tym narzędzia wiersza poleceń Gemini, Claude Code i innych, znajdziesz w pliku README.

Przykładowe prompty

Po zainstalowaniu i włączeniu w narzędziach programistycznych opartych na AI umiejętność mapi-developer-assistant jest zwykle aktywowana automatycznie, gdy zadajesz pytania związane z Merchant API.

„Jak wstawić produkt za pomocą Merchant API w Pythonie?”

„Jaki jest odpowiednik metody accountstatuses.get w Content API w Merchant API?”

„Pokaż mi przykład w Javie, jak obsługiwać uwierzytelnianie za pomocą Merchant API”.

„Podczas wywoływania productInputs.insert otrzymuję błąd „400: Nieprawidłowe żądanie” z błędem weryfikacji. Jak rozwiązać ten problem?”

„Jaka jest różnica między ProductInput a Product w Merchant API?”

Źródła bazy wiedzy

Usługa MCP tworzy bazę wiedzy wyłącznie na podstawie źródeł publicznych i oficjalnych, aby zapewnić dokładność i wiarygodność kontekstu. Usługa indeksuje całą zawartość oficjalnej witryny dla programistów i repozytorium przykładowych kodów, w tym: