Publikowanie interfejsów API

Wyświetlasz dokumentację Apigee Edge.
Otwórz dokumentację Apigee X. info

Opublikuj interfejsy API w portalu, aby udostępnić je deweloperom aplikacji, jak opisano w sekcjach poniżej.

Omówienie publikowania interfejsów API

Proces publikowania interfejsów API w portalu składa się z 2 etapów:

  1. Wybierz usługę API, którą chcesz opublikować w portalu.
  2. Wyświetlaj dokumentację API z dokumentu OpenAPI lub schematu GraphQL, aby deweloperzy aplikacji mogli dowiedzieć się więcej o Twoich interfejsach API. (Więcej informacji o zrzutach znajdziesz w artykule Co to jest zrzut?).

Co jest publikowane w portalu?

Gdy opublikujesz interfejs API, w portalu automatycznie zostaną wprowadzone te zmiany:

  • Dokumentacja API Dostępny interfejs zależy od tego, czy publikujesz interfejs API za pomocą dokumentu OpenAPI czy schematu GraphQL. Zobacz:
  • Na stronie interfejsów API dodano link do strony dokumentacji interfejsu API

    Strona interfejsów API (dołączona do przykładowego portalu) zawiera listę wszystkich interfejsów API opublikowanych w Twoim portalu, ułożonych w porządku alfabetycznym, z linkami do dokumentacji referencyjnej poszczególnych interfejsów API, w której znajdziesz więcej informacji. Opcjonalnie możesz dostosować:

    • Obraz wyświetlany na każdej karcie interfejsu API
    • Kategorie używane do tagowania interfejsów API, aby umożliwić programistom odkrywanie powiązanych interfejsów API na stronie interfejsów API.

    Strona interfejsów API w portalu na żywo z 2 kategoriami i obrazami

SmartDocs (OpenAPI)

Gdy opublikujesz interfejs API za pomocą dokumentu OpenAPI, do portalu zostanie dodana dokumentacja referencyjna interfejsu SmartDocs API.

Deweloperzy mogą zapoznać się z dokumentacją referencyjną interfejsu API SmartDocs i użyć panelu Wypróbuj ten interfejs API, aby wysłać żądanie do interfejsu API i wyświetlić dane wyjściowe. Wypróbuj ten interfejs API działa z niezabezpieczonymi lub zabezpieczonymi punktami końcowymi, które korzystają z uwierzytelniania podstawowego, za pomocą klucza interfejsu API lub OAuth, w zależności od metody zabezpieczeń zdefiniowanej w dokumencie OpenAPI. W przypadku OAuth obsługiwane są te przepływy: kod autoryzacji, hasło i dane logowania klienta.

Strona dokumentacji API z objaśnieniami, które pokazują, jak autoryzować wywołanie interfejsu API, oddokować panel Wypróbuj ten interfejs API, pobrać odpowiednią specyfikację i wykonać interfejs API.

Kliknij  Pełny ekran, aby rozwinąć panel Wypróbuj ten interfejs API. Rozwinięty panel umożliwia wyświetlanie wywołania curl i przykładowych fragmentów kodu w różnych formatach, takich jak HTTP, Python, Node.js i inne, jak pokazano na poniższym rysunku.

Rozwinięty panel Wypróbuj ten interfejs API

Eksplorator GraphQL

Gdy opublikujesz interfejs API za pomocą schematu GraphQL, do portalu zostanie dodany Eksplorator GraphQL. GraphQL Explorer to interaktywne środowisko do uruchamiania zapytań w interfejsie API. Eksplorer jest oparty na GraphiQL, czyli referencyjnej implementacji środowiska IDE GraphQL opracowanej przez GraphQL Foundation.

Programiści mogą używać eksploratora GraphQL do przeglądania interaktywnej dokumentacji opartej na schemacie, tworzenia i uruchamiania zapytań, wyświetlania wyników zapytań oraz pobierania schematu. Aby zabezpieczyć dostęp do interfejsu API, deweloperzy mogą przekazywać nagłówki autoryzacji w panelu Nagłówki żądania.

Więcej informacji o GraphQL znajdziesz na stronie graphql.org.

Eksplorator GraphQL w portalu

Co to jest migawka?

Każdy dokument OpenAPI lub GraphQL jest źródłem informacji w całym cyklu życia interfejsu API. Ten sam dokument jest używany na każdym etapie cyklu życia interfejsu API, od tworzenia po publikowanie i monitorowanie. Gdy modyfikujesz dokument, musisz pamiętać o wpływie zmian na interfejs API w innych fazach cyklu życia, zgodnie z opisem w sekcji Co się stanie, jeśli zmodyfikuję dokument?.

Gdy opublikujesz interfejs API, utworzysz zrzut dokumentu OpenAPI lub GraphQL, aby wyrenderować dokumentację API. Ten zrzut reprezentuje konkretną wersję dokumentu. Jeśli zmodyfikujesz dokument, możesz zrobić kolejny zrzut, aby odzwierciedlić najnowsze zmiany w dokumentacji API.

Informacje o adresach URL wywołania zwrotnego

Jeśli Twoje aplikacje wymagają adresu URL wywołania zwrotnego, np. w przypadku korzystania z typu przyznawania kodu autoryzacji OAuth 2.0 (często określanego jako trzyskładnikowe uwierzytelnianie OAuth), możesz wymagać od deweloperów podania adresu URL wywołania zwrotnego podczas rejestrowania aplikacji. Adres URL wywołania zwrotnego zwykle określa adres URL aplikacji, która jest przeznaczona do otrzymywania kodu autoryzacji w imieniu aplikacji klienta. Więcej informacji znajdziesz w artykule Implementowanie typu przyznawania uprawnień za pomocą kodu autoryzacji.

Podczas dodawania interfejsu API do portalu możesz skonfigurować, czy podczas rejestracji aplikacji wymagany jest URL wywołania zwrotnego. To ustawienie możesz zmienić w każdej chwili, postępując zgodnie z instrukcjami w artykule Zarządzanie adresem URL wywołania zwrotnego interfejsu API.

Podczas rejestrowania aplikacji deweloperzy muszą podać adres URL wywołania zwrotnego dla wszystkich interfejsów API, które tego wymagają, zgodnie z opisem w sekcji Rejestrowanie aplikacji.

Konfigurowanie proxy interfejsu API pod kątem obsługi funkcji „Wypróbuj ten interfejs API”

Zanim opublikujesz interfejsy API za pomocą dokumentu OpenAPI, musisz skonfigurować proxy interfejsu API, aby obsługiwał wysyłanie żądań w panelu Wypróbuj ten interfejs API w dokumentacji referencyjnej interfejsu SmartDocs API. Aby to zrobić:

  • Dodawanie obsługi CORS do proxy interfejsów API w celu wymuszania żądań z różnych domen po stronie klienta

    CORS to standardowy mechanizm, który umożliwia wywoływanie w JavaScript XMLHttpRequest (XHR) wykonywanych na stronie internetowej w celu interakcji z zasobami z domen innych niż domena źródłowa. CORS to powszechnie stosowane rozwiązanie zasady dotyczącej tej samej domeny, która jest egzekwowana przez wszystkie przeglądarki.

  • Zaktualizuj konfigurację proxy interfejsu API, jeśli używasz uwierzytelniania podstawowego lub OAuth2.

W tabeli poniżej znajdziesz podsumowanie wymagań dotyczących konfiguracji proxy interfejsu API, które umożliwiają obsługę panelu Wypróbuj ten interfejs API w dokumentacji referencyjnej interfejsu SmartDocs API na podstawie dostępu do uwierzytelniania.

Dostęp do uwierzytelniania Wymagania dotyczące konfiguracji zasad
Brak lub klucz interfejsu API Dodaj obsługę CORS do proxy interfejsu API. Aby ułatwić sobie pracę, skorzystaj z  przykładowego rozwiązania CORS udostępnionego w GitHubie lub wykonaj czynności opisane w  sekcji Dodawanie obsługi CORS do proxy interfejsu API.
Podstawowe uwierzytelnianie Wykonaj te czynności:
  1. Dodaj obsługę CORS do proxy interfejsu API. Aby ułatwić sobie pracę, skorzystaj z  przykładowego rozwiązania CORS udostępnionego w GitHubie lub wykonaj czynności opisane w sekcji Dodawanie obsługi CORS do proxy interfejsu API.
  2. W zasadzie Add CORS AssignMessage upewnij się, że nagłówek Access-Control-Allow-Headers zawiera atrybut authorization. Na przykład:
    <Header name="Access-Control-Allow-Headers">
      origin, x-requested-with, accept, content-type, authorization
    </Header>
OAuth2
  1. Dodaj obsługę CORS do proxy interfejsu API. Aby ułatwić sobie pracę, skorzystaj z  przykładowego rozwiązania CORS udostępnionego w GitHubie lub wykonaj czynności opisane w sekcji Dodawanie obsługi CORS do proxy interfejsu API.
  2. W zasadzie Add CORS AssignMessage upewnij się, że nagłówek Access-Control-Allow-Headers zawiera atrybut authorization. Na przykład:
    <Header name="Access-Control-Allow-Headers">
      origin, x-requested-with, accept, content-type, authorization
    </Header>
  3. Popraw zachowanie niezgodne z normą RFC w zasadach OAuth2. Aby ułatwić sobie pracę, skorzystaj z  przykładowego rozwiązania OAuth2 udostępnionego na GitHubie lub wykonaj te czynności:
    • Sprawdź, czy element <GrantType> w zasadach OAuth2 jest ustawiony na request.formparam.grant_type (parametr formularza). Więcej informacji znajdziesz w sekcji <GrantType>.
    • Sprawdź, czy w zasadach OAuth2 wartość token_type jest ustawiona na Bearer, a nie na domyślną wartość BearerToken.

Zarządzaj interfejsami API

Zarządzaj interfejsami API w sposób opisany w sekcjach poniżej.

Przeglądaj interfejsy API

Aby wyświetlić interfejsy API w portalu, użyj interfejsu lub polecenia curl.

UI

Aby wyświetlić katalog interfejsów API:

  1. Kliknij Opublikuj > Portale i wybierz portal.
  2. Na stronie głównej portalu kliknij Katalog interfejsów API. Możesz też wybrać Katalog interfejsów API w menu portalu na pasku nawigacyjnym u góry.

Na karcie Interfejsy API w katalogu interfejsów API wyświetla się lista interfejsów API, które zostały dodane do portalu.

Karta Interfejsy API, która zawiera informacje o interfejsach API, w tym nazwę, opis, widoczność, kategorie, powiązaną specyfikację i czas modyfikacji.

Jak widać na poprzednim rysunku, karta Interfejsy API umożliwia:

curl

Aby wyświetlić listę interfejsów API:

curl -X GET "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs" \
    -H "Authorization: Bearer ACCESS_TOKEN"

Zastąp następujące elementy:

  • ORG_NAME nazwą organizacji. Na przykład: my-org.
  • SITE_ID z nazwą portalu w formacie ORG_NAME-PORTAL_NAME, gdzie ORG_NAME to nazwa organizacji, a PORTAL_NAME to nazwa portalu przekonwertowana na małe litery z usuniętymi spacjami i myślnikami. Na przykład: my-org-myportal.
  • ACCESS_TOKEN z tokenem uwierzytelniania używanym do uzyskiwania dostępu do interfejsu Apigee Edge API. Więcej informacji o uwierzytelnianiu i tokenach znajdziesz w artykule Uwierzytelnianie dostępu do interfejsu Edge API.

Instrukcje dotyczące używania podziału na strony w treści odpowiedzi znajdziesz w uwagach na temat podziału na strony.

Ładunek odpowiedzi:

{
  "status": "success",
  "message": "one page of apidocs returned",
  "data": [
    {
      "id": 622759,
      "siteId": "my-org-myportal",
      "title": "Test",
      "description": "",
      "published": false,
      "visibility": false,
      "apiId": "apiproducttest18",
      "apiProductName": "apiproduct_test18",
      "edgeAPIProductName": "apiproduct_test18",
      "specId": null,
      "specContent": null,
      "specTitle": null,
      "snapshotExists": false,
      "snapshotModified": null,
      "modified": 1724144471000,
      "anonAllowed": false,
      "imageUrl": null,
      "snapshotState": null,
      "requireCallbackUrl": false,
      "categoryIds": [],
      "specFormat": null,
      "specModified": null,
      "snapshotOutdated": false,
      "snapshotSourceMissing": false,
      "graphqlSchema": null,
      "graphqlEndpointUrl": null,
      "graphqlSchemaDisplayName": null,
      "grpcFileName": null,
      "grpcZipContent": null
    }
  ],
  "code": null,
  "request_id": "1452867334",
  "error_code": null,
  "next_page_token": ""
}

Gdzie:

  • modified: czas ostatniej modyfikacji elementu katalogu w milisekundach od początku epoki. Na przykład: 1698165480000.
  • id: identyfikator produktu w katalogu. Na przykład: 399668.

Uwagi dotyczące paginacji:

  • Rozmiar strony: użyj parametru pageSize, aby określić liczbę elementów listy, które mają być zwracane na jednej stronie. Wartość domyślna to 25, a maksymalna – 100. Jeśli są dodatkowe strony, pole nextPageToken jest wypełniane tokenem:

    curl -X GET "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs?pageSize=PAGE_SIZE" \
       -H "Authorization: Bearer ACCESS_TOKEN"
    

    Zastąp:

    • PAGE_SIZE z liczbą elementów listy, które mają być zwracane na jednej stronie. Na przykład 10.

    Ładunek odpowiedzi:

    {
      "status": "success",
      "message": "one page of apidocs returned",
      "data": [
        {
          "id": 638007,
          "siteId": "tsnow-mint-liztest",
          "title": "Testing",
          "description": "",
          "published": false,
          "visibility": false,
          "apiId": "testcatalog",
          "apiProductName": "testcatalog",
          "edgeAPIProductName": "testcatalog",
          "specId": "Petstore",
          "specContent": null,
          "specTitle": null,
          "snapshotExists": true,
          "snapshotModified": 1726508367000,
          "modified": 1728582504000,
          "anonAllowed": false,
          "imageUrl": null,
          "snapshotState": "OK_SUBMITTED",
          "requireCallbackUrl": false,
          "categoryIds": [],
          "specFormat": "YAML",
          "specModified": null,
          "snapshotOutdated": false,
          "snapshotSourceMissing": false,
          "graphqlSchema": null,
          "graphqlEndpointUrl": null,
          "graphqlSchemaDisplayName": null,
          "grpcFileName": null,
          "grpcZipContent": null
        }
      ],
      "code": null,
      "request_id": "1068810934",
      "error_code": null,
      "next_page_token": ""
    }
    

  • Token strony: użyj pageToken, aby pobrać kolejne strony, jeśli jest ich więcej niż jedna:

    curl -X GET "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs?pageSize=PAGE_SIZE&pageToken=PAGE_TOKEN" \
          -H "Authorization: Bearer ACCESS_TOKEN"
    

    Zastąp:

    • PAGE_SIZE z liczbą elementów listy, które mają być zwracane na jednej stronie. Na przykład 10.
    • PAGE_TOKEN z wartością nextPageToken. Na przykład: 7zcqrin9l6xhi4nbrb9.

Dodaj interfejs API

Aby dodać interfejsy API do portalu, użyj interfejsu lub polecenia curl:

UI

Aby dodać interfejs API do portalu:

  1. Uzyskaj dostęp do katalogu interfejsów API.
  2. Kliknij kartę Interfejsy API, jeśli nie jest jeszcze wybrana.
  3. Kliknij + Dodaj.

    Wyświetli się okno Dodaj produkt interfejsu API do katalogu.

  4. Wybierz usługę API, którą chcesz dodać do portalu.

  5. Kliknij Dalej. Wyświetli się strona Szczegóły interfejsu API.

  6. Skonfiguruj zawartość dokumentacji API i jej widoczność w portalu:

    Pole Opis
    Opublikowano Aby opublikować interfejs API w portalu, kliknij Opublikowano. Jeśli nie chcesz jeszcze opublikować interfejsu API, wyczyść pole wyboru. Możesz później zmienić to ustawienie, jak opisano w artykule Publikowanie i wycofywanie interfejsu API w portalu.
    Wyświetl tytuł Zaktualizuj tytuł interfejsu API wyświetlany w katalogu. Domyślnie używana jest nazwa usługi API. Wyświetlaną nazwę możesz później zmienić, jak opisano w sekcji Edytowanie wyświetlanej nazwy i opisu.
    Wyświetl opis Zaktualizuj opis interfejsu API wyświetlany w katalogu. Domyślnie używany jest opis usługi API. Wyświetlany opis możesz później zmienić zgodnie z instrukcjami w artykule Edytowanie wyświetlanego tytułu i opisu.
    Wymagaj od programistów określania adresu URL wywołania zwrotnego Włącz tę opcję, jeśli chcesz wymagać od programistów aplikacji określania adresu URL wywołania zwrotnego. Adres URL wywołania zwrotnego możesz dodać lub zaktualizować później, zgodnie z opisem w sekcji Zarządzanie adresem URL wywołania zwrotnego interfejsu API.
    Dokumentacja API

    Aby użyć dokumentu OpenAPI:

    1. Kliknij Dokument OpenAPI.
    2. Kliknij Wybierz dokument.
    3. Wykonaj jedną z tych czynności:
      • Kliknij kartę Moje specyfikacje i wybierz specyfikację z Centrum specyfikacji.
      • Kliknij kartę Prześlij plik i prześlij plik.
      • Kliknij kartę Importuj z adresu URL i zaimportuj specyfikację z adresu URL.
    4. Kliknij Wybierz.

    Aby użyć schematu GraphQL:

    1. Wybierz Schemat GraphQL.
    2. Kliknij Wybierz dokument.
    3. Znajdź i wybierz schemat GraphQL.
    4. Kliknij Wybierz.

    Możesz też kliknąć No documentation (Brak dokumentacji) i dodać dokument później, po dodaniu interfejsu API, zgodnie z opisem w artykule Zarządzanie migawką dokumentu.

    Widoczność interfejsu API

    Jeśli nie korzystasz z wersji beta funkcji zarządzania odbiorcami, wybierz jedną z tych opcji:

    • Anonimowi użytkownicy, aby umożliwić wszystkim użytkownikom wyświetlanie interfejsu API.
    • Zarejestrowani użytkownicy, aby zezwolić na wyświetlanie interfejsu API tylko zarejestrowanym użytkownikom.

    Jeśli korzystasz z wersji beta funkcji zarządzania odbiorcami, wybierz jedną z tych opcji:

    • Publiczny (widoczny dla każdego), aby umożliwić wszystkim użytkownikom wyświetlanie interfejsu API.
    • Uwierzytelnieni użytkownicy, aby zezwolić na wyświetlanie interfejsu API tylko zarejestrowanym użytkownikom.
    • Wybrani odbiorcy, aby wybrać konkretnych odbiorców, którzy będą mogli wyświetlać interfejs API.

    Widocznością odbiorców możesz zarządzać później, zgodnie z opisem w artykule Zarządzanie widocznością interfejsu API w portalu.

    Wyświetlany obrazy Aby wyświetlić obraz na karcie interfejsu API na stronie Interfejsy API, kliknij Wybierz obraz. W oknie Wybierz obraz wybierz istniejący obraz, prześlij nowy lub podaj adres URL zewnętrznego obrazu i kliknij Wybierz. Wyświetl podgląd miniatury interfejsu API i kliknij Wybierz. Obraz możesz dodać później, zgodnie z instrukcjami w artykule Zarządzanie obrazem na karcie interfejsu API. Jeśli określisz obraz za pomocą zewnętrznego adresu URL, nie zostanie on przesłany do Twoich zasobów. Ponadto wczytywanie obrazu w zintegrowanym portalu będzie zależeć od jego dostępności, która może być blokowana lub ograniczana przez zasady bezpieczeństwa treści.
    Kategorie

    Dodaj kategorie, do których będzie przypisany interfejs API, aby umożliwić deweloperom aplikacji odkrywanie powiązanych interfejsów API na stronie interfejsów API. Aby zidentyfikować kategorię:

    • Wybierz kategorię z listy.
    • Dodaj nową kategorię, wpisując jej nazwę i naciskając Enter. Nowa kategoria zostanie dodana do strony Kategorie i będzie dostępna podczas dodawania lub edytowania innych interfejsów API.

  7. Kliknij Zapisz.

curl

Aby dodać interfejs API do portalu :

curl -X POST "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs" \
    -H "Authorization: Bearer ACCESS_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
       "title": "TITLE",
       "description": "DESCRIPTION",
       "anonAllowed": ANON_TRUE_OR_FALSE,
       "imageUrl": "IMAGE_URL",
       "requireCallbackUrl": CALLBACK_TRUE_OR_FALSE,
       "categoryIds": [
         "CATEGORY_ID1",
         "CATEGORY_ID2"
       ],
       "published": PUBLISHED_TRUE_OR_FALSE,
        "apiProductName": "API_PRODUCT"
    }'

Zastąp następujące elementy:

  • ORG_NAME nazwą organizacji. Na przykład: my-org.
  • SITE_ID z nazwą portalu w formacie ORG_NAME-PORTAL_NAME, gdzie ORG_NAME to nazwa organizacji, a PORTAL_NAME to nazwa portalu przekonwertowana na małe litery z usuniętymi spacjami i myślnikami. Na przykład: my-org-myportal.
  • ACCESS_TOKEN z tokenem uwierzytelniania używanym do uzyskiwania dostępu do interfejsu Apigee Edge API. Więcej informacji o uwierzytelnianiu i tokenach znajdziesz w artykule Uwierzytelnianie dostępu do interfejsu Edge API.
  • TITLE z wyświetlanym tytułem. Na przykład: Hello World 2.
  • DESCRIPTION z opisem wyświetlacza. Na przykład: Simple hello world example.
  • ANON_TRUE_OR_FALSEtrue lub false (domyślnie), gdzie: true oznacza, że ten interfejs API jest publicznie widoczny i można go wyświetlać anonimowo; w przeciwnym razie mogą go wyświetlać tylko zarejestrowani użytkownicy.
  • IMAGE_URL adresem URL zewnętrznego obrazu używanego w przypadku produktu w katalogu lub ścieżką do plików obrazów przechowywanych w portalu, np. /files/book-tree.jpg. Jeśli podasz adres URL zewnętrznego obrazu, nie zostanie on przesłany do Twoich komponentów. Ponadto wczytywanie obrazu w zintegrowanym portalu będzie zależeć od jego dostępności, która może być blokowana lub ograniczana przez zasady bezpieczeństwa treści.
  • CALLBACK_TRUE_OR_FALSEtrue lub false (domyślnie), gdzie: true wymaga od użytkownika portalu wpisania adresu URL podczas zarządzania aplikacją.
  • CATEGORY_ID z identyfikatorem kategorii. Na przykład: bf6505eb-2a0f-47af-a00a-ded40ac72960. Kolejne identyfikatory kategorii oddziel przecinkami. Pobierz identyfikator kategorii za pomocą polecenia list API categories.
  • PUBLISHED_TRUE_OR_FALSE z wartością true lub false (domyślnie), gdzie true oznacza, że interfejs API jest dostępny publicznie. Po opublikowaniu możesz zezwolić na dostęp wszystkim użytkownikom, uwierzytelnionym użytkownikom lub konkretnym użytkownikom.
  • API_PRODUCT z nazwą usługi API. Na przykład: Hello World 2.

Ładunek odpowiedzi:

{
  "status": "success",
  "message": "API created",
  "data": {
    "id": 662423,
    "siteId": "my-org-myportal",
    "title": "My Test Catalog 4",
    "description": "",
    "published": false,
    "visibility": false,
    "apiId": "uxb9wjua",
    "apiProductName": "uXB9wJUa",
    "edgeAPIProductName": "uXB9wJUa",
    "specId": null,
    "specContent": null,
    "specTitle": null,
    "snapshotExists": false,
    "snapshotModified": null,
    "modified": 1729635493000,
    "anonAllowed": false,
    "imageUrl": null,
    "snapshotState": null,
    "requireCallbackUrl": false,
    "categoryIds": [],
    "specFormat": null,
    "specModified": null,
    "snapshotOutdated": null,
    "snapshotSourceMissing": false,
    "graphqlSchema": null,
    "graphqlEndpointUrl": null,
    "graphqlSchemaDisplayName": null,
    "grpcFileName": null,
    "grpcZipContent": null
  },
  "code": null,
  "request_id": "893346193",
  "error_code": null
}

Gdzie:

  • modified: czas ostatniej modyfikacji elementu katalogu w milisekundach od początku epoki. Na przykład: 1698165480000.
  • id: identyfikator produktu w katalogu. Na przykład: 399668.

Edytowanie interfejsu API

Po dodaniu interfejsu API możesz wprowadzać zmiany za pomocą interfejsu lub wywołania interfejsu API.

W tej sekcji znajdziesz szczegółowy przykład czynności, które należy wykonać, aby zmodyfikować istniejący interfejs API w portalu.

Szczegółowe ustawienia modyfikacji znajdziesz w kolejnych sekcjach.

UI

Aby edytować interfejs API:

  1. Uzyskaj dostęp do katalogu interfejsów API.
  2. Kliknij kartę Interfejsy API, jeśli nie jest jeszcze wybrana.
  3. Kliknij wiersz interfejsu API, który chcesz edytować.
  4. Kliknij ikona edycjiEdytuj.
  5. Wprowadź zmiany w sekcji Szczegóły interfejsu API. Opisy opcji znajdziesz w sekcji Dodawanie interfejsu API.
  6. Kliknij Zapisz.

curl

Po dodaniu interfejsu API użyj wywołania update, aby wprowadzić zmiany.

W tym przykładzie pokazujemy, jak zmienić stan opublikowania interfejsu API w portalu z true na false. W razie potrzeby możesz zmienić więcej niż jedno ustawienie w jednym wywołaniu interfejsu API.

  1. Aby znaleźć wygenerowany id, który jednoznacznie identyfikuje każdy interfejs API, pobierz listę interfejsów API w portalu zgodnie z opisem w sekcji Eksplorowanie interfejsów API.
  2. Zwracanie bieżących wartości dla konkretnego interfejsu API:

    curl -X GET "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
    -H "Authorization: Bearer ACCESS_TOKEN"
    

    Zastąp następujące elementy:

    • ORG_NAME nazwą organizacji. Na przykład: my-org.
    • SITE_ID z nazwą portalu w formacie ORG_NAME-PORTAL_NAME, gdzie ORG_NAME to nazwa organizacji, a PORTAL_NAME to nazwa portalu przekonwertowana na małe litery z usuniętymi spacjami i myślnikami. Na przykład: my-org-myportal.
    • API_DOC z wygenerowanym id dokumentu. Na przykład: 399668. Aby znaleźć tę wartość, użyj polecenia list API docs (lista dokumentów interfejsu API).
    • ACCESS_TOKEN z tokenem uwierzytelniania używanym do uzyskiwania dostępu do interfejsu Apigee Edge API. Więcej informacji o uwierzytelnianiu i tokenach znajdziesz w artykule Uwierzytelnianie dostępu do interfejsu Edge API.

    Ładunek odpowiedzi:

    {
      "status": "success",
      "message": "apidoc returned",
      "data": {
        "id": 662423,
        "siteId": "my-org-myportal",
        "title": "My Test Catalog 4",
        "description": "",
        "published": false,
        "visibility": false,
        "apiId": "uxb9wjua",
        "apiProductName": "uXB9wJUa",
        "edgeAPIProductName": "uXB9wJUa",
        "specId": null,
        "specContent": null,
        "specTitle": null,
        "snapshotExists": false,
        "snapshotModified": null,
        "modified": 1729635493000,
        "anonAllowed": false,
        "imageUrl": null,
        "snapshotState": null,
        "requireCallbackUrl": false,
        "categoryIds": [],
        "specFormat": null,
        "specModified": null,
        "snapshotOutdated": false,
        "snapshotSourceMissing": false,
        "graphqlSchema": null,
        "graphqlEndpointUrl": null,
        "graphqlSchemaDisplayName": null,
        "grpcFileName": null,
        "grpcZipContent": null
      },
      "code": null,
      "request_id": "601210268",
      "error_code": null
    }
    

  1. W wywołaniu update uwzględnij wartości, które chcesz zachować, i zmodyfikuj te, które chcesz zmienić. Jeśli pominiesz wiersz, użyte zostanie ustawienie domyślne. W tym przykładzie zmień ustawienie publikacji z false na true:

    curl -X PUT "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
     -H "Authorization: Bearer ACCESS_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
        "title": "TITLE",
        "anonAllowed": true,
        "published": true
     }'
    

    Zastąp następujące elementy:

    • TITLE z wyświetlanym tytułem. Na przykład: Hello World 2.

    Ładunek odpowiedzi:

    {
      "status": "success",
      "message": "ApiDoc updated",
      "data": {
        "id": 662423,
        "siteId": "my-org-myportal",
        "title": "My Test Catalog 4",
        "description": "",
        "published": true,
        "visibility": true,
        "apiId": "uxb9wjua",
        "apiProductName": "uXB9wJUa",
        "edgeAPIProductName": "uXB9wJUa",
        "specId": null,
        "specContent": null,
        "specTitle": null,
        "snapshotExists": false,
        "snapshotModified": null,
        "modified": 1729989250000,
        "anonAllowed": true,
        "imageUrl": null,
        "snapshotState": null,
        "requireCallbackUrl": false,
        "categoryIds": [],
        "specFormat": null,
        "specModified": null,
        "snapshotOutdated": null,
        "snapshotSourceMissing": false,
        "graphqlSchema": null,
        "graphqlEndpointUrl": null,
        "graphqlSchemaDisplayName": null,
        "grpcFileName": null,
        "grpcZipContent": null
      },
      "code": null,
      "request_id": "738172002",
      "error_code": null
    }
    

Zarządzanie zrzutem dokumentu

Po opublikowaniu interfejsu API możesz w dowolnym momencie utworzyć nowy zrzut dokumentu OpenAPI lub GraphQL, aby zaktualizować dokumentację API opublikowaną w portalu.

Aby zarządzać zrzutem dokumentu:

  1. Uzyskaj dostęp do katalogu interfejsów API.
  2. Kliknij kartę Interfejsy API, jeśli nie jest jeszcze wybrana.
  3. Kliknij wiersz interfejsu API, który chcesz edytować.
  4. Sprawdź stan zrzutu. Jeśli jest nieaktualny, wyświetli się ten komunikat:Ikona i komunikat wskazujące, że zrzut jest nieaktualny
  5. Kliknij ikona edycji.
  6. Wykonaj jedną z tych czynności:
    • Aby odświeżyć nieaktualny zrzut dokumentu OpenAPI, kliknij Odśwież zrzut.
    • Aby zmienić dokument używany do generowania dokumentacji interfejsu API, w sekcji Dokumentacja interfejsu API kliknij Wybierz dokument i wybierz nowy dokument.
  7. Kliknij Zapisz.

Publikowanie i cofanie publikacji interfejsu API w portalu

Publikowanie to proces udostępniania interfejsów API programistom aplikacji do wykorzystania.

Użyj interfejsu lub polecenia curl, aby opublikować lub cofnąć publikację interfejsu API w portalu.

UI

Aby opublikować interfejs API w portalu lub cofnąć jego publikację:

  1. Uzyskaj dostęp do katalogu interfejsów API.
  2. Kliknij kartę Interfejsy API, jeśli nie jest jeszcze wybrana.
  3. Kliknij wiersz interfejsu API, który chcesz edytować.
  4. Kliknij Edytuj ikonę Edytuj.
  5. W sekcji Szczegóły interfejsu API zaznacz lub odznacz opcję Opublikowany (w katalogu), aby odpowiednio opublikować lub wycofać publikację interfejsu API w portalu.
  6. Kliknij Zapisz.

curl

W wywołaniu aktualizacji umieść jeden z tych elementów:

"published": true,    # API is published to your portal
"published": false,   # API is not published in your portal

Aby edytować interfejs API:

  1. Zwróć bieżące wartości:

    curl -X GET "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs" \
    -H "Authorization: Bearer ACCESS_TOKEN"
  2. Aby edytować interfejs API, użyj wywołania update. Uwzględnij zmienne wartości, które chcesz zachować, i zmodyfikuj wartości, które chcesz zmienić. Jeśli pominiesz ustawienie, które można zmieniać, zostanie ono zastąpione wartością domyślną.

    curl -X PUT "https://api.enterprise.apigee.com/v1/organizations/  ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
     -H "Authorization: Bearer ACCESS_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
        "title": "TITLE",
        "description": "DESCRIPTION",
        "anonAllowed": ANON_TRUE_OR_FALSE,
        "imageUrl": IMAGE_URL,
        "requireCallbackUrl": CALLBACK_TRUE_OR_FALSE,
        "categoryIds": [
          "CATEGORY_ID1",
         "CATEGORY_ID2"
        ],
        "published": PUBLISHED_TRUE_OR_FALSE
    }

Szczegółowy przykład kroków, zmiennych i zwróconego ładunku znajdziesz w artykule Zarządzanie wersją dokumentu.

Zarządzanie widocznością interfejsu API w portalu

Zarządzaj widocznością interfejsu API w portalu, zezwalając na dostęp do:

  • Publiczne (widoczne dla każdego)
  • Uwierzytelnieni użytkownicy:
  • Wybrani odbiorcy (jeśli uczestniczysz w programie beta funkcji zarządzania odbiorcami)

Aby zarządzać widocznością interfejsu API w portalu, użyj interfejsu lub polecenia curl:

UI

Aby zarządzać widocznością interfejsu API w portalu:

  1. Uzyskaj dostęp do katalogu interfejsów API.
  2. Kliknij kartę Interfejsy API, jeśli nie jest jeszcze wybrana.
  3. Kliknij wiersz interfejsu API, który chcesz edytować.
  4. Kliknij Edytuj ikonę Edytuj.
  5. Wybierz ustawienie widoczności. Jeśli uczestniczysz w programie testów beta funkcji odbiorców, wybierz jedną z tych opcji:

    • Publiczny (widoczny dla wszystkich), aby umożliwić wszystkim użytkownikom wyświetlanie strony.
    • Uwierzytelnieni użytkownicy, aby zezwolić na wyświetlanie strony tylko zarejestrowanym użytkownikom.
    • Wybrani odbiorcy, aby wybrać konkretnych odbiorców, którzy mają mieć możliwość wyświetlania strony. Zobacz Zarządzanie odbiorcami w portalu.
    W przeciwnym razie wybierz jedną z tych opcji:
    • Anonimowi użytkownicy, aby umożliwić wszystkim użytkownikom wyświetlanie strony.
    • Zarejestrowani użytkownicy, aby zezwolić na wyświetlanie strony tylko zarejestrowanym użytkownikom.

  6. Kliknij Prześlij.

curl

Jeśli masz dostęp do wersji beta funkcji zarządzania odbiorcami, używaj interfejsu do zarządzania odbiorcami.

Jeśli nie korzystasz z funkcji zarządzania odbiorcami, widoczność jest kontrolowana za pomocą anonAllowed.

W wywołaniu update umieść jeden z tych elementów:

  # When not enrolled in the beta release of the audience management feature:

  "anonAllowed": true,      # Anonymous users can see the API
  "anonAllowed": false,     # Only registered users can see the API

Aby edytować interfejs API:

  1. Zwróć bieżące wartości:

    curl -X GET "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
         -H "Authorization: Bearer ACCESS_TOKEN"
    
  2. Aby edytować interfejs API, użyj wywołania update. Uwzględnij zmienne wartości, które chcesz zachować, i zmień wartości, które chcesz zmienić. Jeśli pominiesz ustawienie podlegające zmianom, używana jest wartość domyślna.

    curl -X PUT "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
         -H "Authorization: Bearer ACCESS_TOKEN" \
         -H "Content-Type: application/json" \
         -d '{
            "title": "TITLE",
            "description": "DESCRIPTION",
            "anonAllowed": ANON_TRUE_OR_FALSE,
            "imageUrl": IMAGE_URL,
            "requireCallbackUrl": CALLBACK_TRUE_OR_FALSE,
            "categoryIds": [
              "CATEGORY_ID1",
              "CATEGORY_ID2"
            ],
            "published": PUBLISHED_TRUE_OR_FALSE
         }'

Szczegółowy przykład czynności, zmiennych i zwracanego ładunku znajdziesz w artykule Edytowanie interfejsu API.

Zarządzanie adresem URL wywołania zwrotnego interfejsu API

Zarządzaj adresem URL wywołania zwrotnego interfejsu API. Zobacz artykuł o adresach URL wywołania zwrotnego.

Aby zarządzać adresem URL wywołania zwrotnego interfejsu API, użyj interfejsu lub polecenia curl:

UI

Aby zarządzać adresem URL wywołania zwrotnego interfejsu API:

  1. Uzyskaj dostęp do katalogu interfejsów API.
  2. Kliknij kartę Interfejsy API, jeśli nie jest jeszcze wybrana.
  3. Kliknij wiersz interfejsu API, który chcesz edytować.
  4. Kliknij Edytuj ikonę Edytuj.
  5. W sekcji Szczegóły interfejsu API zaznacz lub odznacz pole wyboru Wymagaj od programistów określania adresu URL wywołania zwrotnego.
  6. Kliknij Zapisz.

curl

W wywołaniu update umieść jeden z tych elementów:

  "requireCallbackUrl": true,    # Portal user is required to input a URL
  "requireCallbackUrl": false,   # Portal user is not required to input a URL

Aby edytować interfejs API:

  1. Zwróć bieżące wartości:

    curl -X GET "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
         -H "Authorization: Bearer ACCESS_TOKEN"
    
  2. Aby edytować interfejs API, użyj wywołania update. Uwzględnij zmienne wartości, które chcesz zachować, i zmień wartości, które chcesz zmienić. Jeśli pominiesz ustawienie podlegające zmianom, używana jest wartość domyślna.

    curl -X PUT "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
         -H "Authorization: Bearer ACCESS_TOKEN" \
         -H "Content-Type: application/json" \
         -d '{
            "title": "TITLE",
            "description": "DESCRIPTION",
            "anonAllowed": ANON_TRUE_OR_FALSE,
            "imageUrl": IMAGE_URL,
            "requireCallbackUrl": CALLBACK_TRUE_OR_FALSE,
            "categoryIds": [
              "CATEGORY_ID1",
              "CATEGORY_ID2"
            ],
            "published": PUBLISHED_TRUE_OR_FALSE
         }'

Szczegółowy przykład czynności, zmiennych i zwracanego ładunku znajdziesz w artykule Edytowanie interfejsu API.

Zarządzanie obrazem karty interfejsu API

Zarządzaj obrazem, który pojawia się na karcie interfejsu API na stronie interfejsów API, dodając lub zmieniając bieżący obraz.

Aby zarządzać obrazem na karcie interfejsu API, użyj interfejsu lub polecenia curl:

UI

Aby zarządzać obrazem na karcie interfejsu API:

  1. Uzyskaj dostęp do katalogu interfejsów API.
  2. Kliknij kartę Interfejsy API, jeśli nie jest jeszcze wybrana.
  3. Kliknij wiersz interfejsu API, który chcesz edytować.
  4. Kliknij Edytuj ikonę Edytuj.
  5. W sekcji Szczegóły interfejsu API:

    • Jeśli nie wybrano obrazu, kliknij Wybierz obraz, aby wskazać lub przesłać obraz.
    • Aby określić lub przesłać inny obraz, kliknij Zmień obraz.
    • Aby usunąć obraz, kliknij x na obrazie.

    Podczas określania obrazu podaj obraz z zewnętrznym adresem URL używanym w przypadku produktu w katalogu lub ścieżkę do plików obrazów przechowywanych w portalu, np. /files/book-tree.jpg. Jeśli podasz adres URL zewnętrznego obrazu, nie zostanie on przesłany do Twoich komponentów. Ponadto wczytywanie obrazu w zintegrowanym portalu będzie zależeć od jego dostępności, która może być blokowana lub ograniczana przez zasady bezpieczeństwa treści.

  6. Kliknij Zapisz.

curl

W wywołaniu update uwzględnij te elementy:

  # Omit line for no image file

  "imageUrl": "IMAGE_URL"    # URL of the external image or name of the image file

Aby edytować interfejs API:

  1. Zwróć bieżące wartości:

    curl -X GET "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
         -H "Authorization: Bearer ACCESS_TOKEN"
    
  2. Aby edytować interfejs API, użyj wywołania update. Uwzględnij zmienne wartości, które chcesz zachować, i zmień wartości, które chcesz zmienić. Jeśli pominiesz ustawienie podlegające zmianom, używana jest wartość domyślna.

    curl -X PUT "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
         -H "Authorization: Bearer ACCESS_TOKEN" \
         -H "Content-Type: application/json" \
         -d '{
            "title": "TITLE",
            "description": "DESCRIPTION",
            "anonAllowed": ANON_TRUE_OR_FALSE,
            "imageUrl": IMAGE_URL,
            "requireCallbackUrl": CALLBACK_TRUE_OR_FALSE,
            "categoryIds": [
              "CATEGORY_ID1",
              "CATEGORY_ID2"
            ],
            "published": PUBLISHED_TRUE_OR_FALSE
         }'

Szczegółowy przykład czynności, zmiennych i zwracanego ładunku znajdziesz w artykule Edytowanie interfejsu API.

Tagowanie interfejsu API za pomocą kategorii

Korzystanie z kategorii pomaga deweloperom aplikacji odkrywać powiązane interfejsy API. Zobacz też Zarządzanie kategoriami.

Otaguj interfejs API za pomocą kategorii w jeden z tych sposobów:

  • Podczas edytowania interfejsu API możesz zarządzać kategoriami, do których jest on przypisany, zgodnie z opisem poniżej.
  • Zarządzaj interfejsami API przypisanymi do kategorii podczas edytowania kategorii.

Aby otagować interfejs API za pomocą kategorii, użyj interfejsu lub polecenia curl:

UI

Aby przypisać interfejs API do kategorii podczas jego edytowania:

  1. Uzyskaj dostęp do katalogu interfejsów API.
  2. Kliknij kartę Interfejsy API, jeśli nie jest jeszcze wybrana.
  3. Kliknij wiersz interfejsu API, który chcesz edytować.
  4. Kliknij Edytuj ikonę Edytuj.
  5. Kliknij pole Kategorie i wykonaj jedną z tych czynności:
    • Wybierz kategorię z listy.
    • Dodaj nową kategorię, wpisując jej nazwę i naciskając Enter. Nowa kategoria zostanie dodana do strony Kategorie i będzie dostępna podczas dodawania lub edytowania innych interfejsów API.
  6. Powtórz tę czynność, aby przypisać interfejs API do większej liczby kategorii.
  7. Kliknij Zapisz.

curl

W wywołaniu update uwzględnij te elementy:

  # Omit line for no categories

  "categoryIds": [
      "CATEGORY_ID1",      # A category ID number
      "CATEGORY_ID2"       # A category ID number
    ],

Użyj polecenia list categories (wyświetl kategorie), aby uzyskać numery identyfikatorów kategorii.

Aby edytować interfejs API:

  1. Zwróć bieżące wartości:

    curl -X GET "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
         -H "Authorization: Bearer ACCESS_TOKEN"
    
  2. Aby edytować interfejs API, użyj wywołania update. Uwzględnij zmienne wartości, które chcesz zachować, i zmień wartości, które chcesz zmienić. Jeśli pominiesz ustawienie podlegające zmianom, używana jest wartość domyślna.

    curl -X PUT "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
         -H "Authorization: Bearer ACCESS_TOKEN" \
         -H "Content-Type: application/json" \
         -d '{
            "title": "TITLE",
            "description": "DESCRIPTION",
            "anonAllowed": ANON_TRUE_OR_FALSE,
            "imageUrl": IMAGE_URL,
            "requireCallbackUrl": CALLBACK_TRUE_OR_FALSE,
            "categoryIds": [
              "CATEGORY_ID1",
              "CATEGORY_ID2"
            ],
            "published": PUBLISHED_TRUE_OR_FALSE
         }'

Szczegółowy przykład czynności, zmiennych i zwracanego ładunku znajdziesz w artykule Edytowanie interfejsu API.

Edytowanie wyświetlanego tytułu i opisu

Aby edytować tytuł i opis wyświetlania, użyj interfejsu lub polecenia curl:

UI

Aby edytować wyświetlaną nazwę i opis:

  1. Uzyskaj dostęp do katalogu interfejsów API.
  2. Kliknij kartę Interfejsy API, jeśli nie jest jeszcze wybrana.
  3. Kliknij wiersz interfejsu API, który chcesz edytować.
  4. Kliknij Edytuj ikonę Edytuj.
  5. W razie potrzeby zmień pola Wyświetlany tytuł i Wyświetlany opis.
  6. Kliknij Zapisz.

curl

W wywołaniu update uwzględnij te elementy:

  "title": "TITLE",    # Display title
  "description": "DESCRIPTION",  # Display description

Aby edytować interfejs API:

  1. Zwróć bieżące wartości:

    curl -X GET "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
         -H "Authorization: Bearer ACCESS_TOKEN"
    
  2. Aby edytować interfejs API, użyj wywołania update. Uwzględnij zmienne wartości, które chcesz zachować, i zmień wartości, które chcesz zmienić. Jeśli pominiesz ustawienie podlegające zmianom, używana jest wartość domyślna.

    curl -X PUT "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
         -H "Authorization: Bearer ACCESS_TOKEN" \
         -H "Content-Type: application/json" \
         -d '{
            "title": "TITLE",
            "description": "DESCRIPTION",
            "anonAllowed": ANON_TRUE_OR_FALSE,
            "imageUrl": IMAGE_URL,
            "requireCallbackUrl": CALLBACK_TRUE_OR_FALSE,
            "categoryIds": [
              "CATEGORY_ID1",
              "CATEGORY_ID2"
            ],
            "published": PUBLISHED_TRUE_OR_FALSE
         }'

Szczegółowy przykład czynności, zmiennych i zwracanego ładunku znajdziesz w artykule Edytowanie interfejsu API.

Usuwanie interfejsu API z portalu

Aby usunąć interfejs API z portalu, użyj interfejsu lub polecenia curl:

UI

Aby usunąć interfejs API z portalu:

  1. Uzyskaj dostęp do katalogu interfejsów API.
  2. Wybierz Interfejsy API, jeśli nie są jeszcze wybrane.
  3. Umieść kursor nad interfejsem API na liście, aby wyświetlić menu działań.
  4. Kliknij Ikona usuwania Usuń.

curl

Aby usunąć interfejs API z portalu:

curl -X DELETE "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
    -H "Authorization: Bearer ACCESS_TOKEN"

Zastąp następujące elementy:

  • ORG_NAME nazwą organizacji. Na przykład: my-org.
  • SITE_ID z nazwą portalu w formacie ORG_NAME-PORTAL_NAME, gdzie ORG_NAME to nazwa organizacji, a PORTAL_NAME to nazwa portalu przekonwertowana na małe litery z usuniętymi spacjami i myślnikami. Na przykład: my-org-myportal.
  • API_DOC z wygenerowanym id dokumentu. Na przykład: 399668. Aby znaleźć tę wartość, użyj polecenia list API docs (lista dokumentów interfejsu API).
  • ACCESS_TOKEN z tokenem uwierzytelniania używanym do uzyskiwania dostępu do interfejsu Apigee Edge API. Więcej informacji o uwierzytelnianiu i tokenach znajdziesz w artykule Uwierzytelnianie dostępu do interfejsu Edge API.

Ładunek odpowiedzi:

{
  "status": "success",
  "message": "Apidoc deleted",
  "data": {
  },
  "code": null,
  "request_id": "1790036484",
  "error_code": null
}

Zarządzanie dokumentacją API

W sekcjach poniżej znajdziesz informacje o tym, jak aktualizować, pobierać i usuwać dokumentację interfejsu API.

Dokumentacja interfejsu Update API

Aby przesłać inną wersję dokumentacji API:

UI

  1. Uzyskaj dostęp do katalogu interfejsów API.
  2. Kliknij kartę Interfejsy API, jeśli nie jest jeszcze wybrana.
  3. Kliknij wiersz interfejsu API, który chcesz edytować.
  4. Sprawdź stan zrzutu. Jeśli jest nieaktualny, wyświetli się ten komunikat:Ikona i komunikat wskazujące, że zrzut jest nieaktualny
  5. Kliknij Edytuj.
  6. Wykonaj jedną z tych czynności:
    • Aby odświeżyć nieaktualny zrzut dokumentu OpenAPI, kliknij Odśwież zrzut.
    • Aby zmienić dokument używany do generowania dokumentacji API, w sekcji Dokumentacja API kliknij Wybierz dokument i wybierz nowy dokument.
  7. W panelu dokumentacja interfejsu API wybierz jedną z tych opcji:
    • Dokument OpenAPI
    • Schemat GraphQL
  8. Kliknij Wybierz dokument i wybierz najnowszą wersję dokumentu.
  9. W przypadku GraphQL podaj URL punktu końcowego.
  10. Kliknij Zapisz.

Dokumentacja API jest renderowana z dokumentu i dodawana do strony Dokumentacja API. Stan zrzutu zostanie zaktualizowany do bieżącego:

Ikona i komunikat wskazują, że zrzut jest aktualny

curl

Aby zaktualizować zawartość dokumentacji OpenAPI lub GraphQL:

OpenAPI

curl -X PATCH "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC/documentation" \
    -H "Authorization: Bearer ACCESS_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"oasDocumentation": {
           "spec":{ "displayName":"DISPLAY_NAME",
                    "contents":"CONTENTS"}
            }
        }'

Zastąp następujące elementy:

  • ORG_NAME nazwą organizacji. Na przykład: my-org.
  • SITE_ID z nazwą portalu w formacie ORG_NAME-PORTAL_NAME, gdzie ORG_NAME to nazwa organizacji, a PORTAL_NAME to nazwa portalu przekonwertowana na małe litery z usuniętymi spacjami i myślnikami. Na przykład: my-org-myportal.
  • API_DOC z wygenerowanym id dokumentu. Na przykład: 399668. Aby znaleźć tę wartość, użyj polecenia list API docs (lista dokumentów interfejsu API).
  • DISPLAY_NAME z wyświetlaną nazwą dokumentacji API. Na przykład: Hello World 2.
  • CONTENTS z ciągiem tekstowym zakodowanym w formacie base64, który zawiera dokumentację interfejsu API. Większość środowisk deweloperskich zawiera narzędzie do konwersji base64. Dostępnych jest też wiele narzędzi do konwersji online.

Ładunek odpowiedzi:

{
 "status":"success",
 "message":"Api documentation updated",
 "requestId":"645138278"
 "data": {
   "oasDocumentation": {
     "spec": {
        "displayName": "Hello World 2"
      },
     "Format": "YAML"
   }
 }
}

GraphQL

curl -X PATCH "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC/documentation" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"graphqlDocumentation": {
         "schema":{"displayName":"DISPLAY_NAME",
         "contents":"CONTENTS"},
         "endpointUri": "ENDPOINT_URI"
          }
      }'

Zastąp następujące elementy:

  • ORG_NAME nazwą organizacji. Na przykład: my-org.
  • SITE_ID z nazwą portalu w formacie ORG_NAME-PORTAL_NAME, gdzie ORG_NAME to nazwa organizacji, a PORTAL_NAME to nazwa portalu przekonwertowana na małe litery z usuniętymi spacjami i myślnikami. Na przykład: my-org-myportal.
  • API_DOC z wygenerowanym id dokumentu. Na przykład: 399668. Aby znaleźć tę wartość, użyj polecenia list API docs (lista dokumentów interfejsu API).
  • DISPLAY_NAME z wyświetlaną nazwą dokumentacji API. Na przykład: Hello World 2.
  • ENDPOINT_URI nazwą domeny identyfikatora URI punktu końcowego. Na przykład:https://demo.google.com/graphql.
  • CONTENTS z ciągiem tekstowym zakodowanym w formacie base64, który zawiera dokumentację interfejsu API. Większość środowisk deweloperskich zawiera narzędzie do konwersji base64. Dostępnych jest też wiele narzędzi do konwersji online.

Ładunek odpowiedzi:

{
"status": "success",
"message": "ApiDocDocumentation updated",
"data": {
  "oasDocumentation": null,
  "graphqlDocumentation": {
    "schema": {
      "displayName": "schema.docs.graphql",
      "contents": ""
    },
    "endpointUri": "https://demo.google.com/graphql"
  }
},
"code": null,
"request_id": "640336173",
"error_code": null
}

Dokumentacja interfejsu API jest renderowana z dokumentu i dodawana do strony interfejsów API w aktywnym portalu.

Pobieranie dokumentacji API

Aby pobrać dokumentację API:

UI

curl

Aby pobrać dokumentację API za pomocą polecenia get documentation:

curl -X GET "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC/documentation" \
    -H "Authorization: Bearer ACCESS_TOKEN"

Zastąp następujące elementy:

  • ORG_NAME nazwą organizacji. Na przykład: my-org.
  • SITE_ID z nazwą portalu w formacie ORG_NAME-PORTAL_NAME, gdzie ORG_NAME to nazwa organizacji, a PORTAL_NAME to nazwa portalu przekonwertowana na małe litery z usuniętymi spacjami i myślnikami. Na przykład: my-org-myportal.
  • API_DOC z wygenerowanym id dokumentu. Na przykład: 399668. Aby znaleźć tę wartość, użyj polecenia list API docs (lista dokumentów interfejsu API).

    Ładunek odpowiedzi:

{
  "status": "success",
  "message": "ApiDocDocumentation returned",
  "data": {
    "oasDocumentation": {
      "spec": {
        "displayName": "mock",
        "contents": "b3BlbmFwaTogMy4wLjAKaW5mbzoKICBkZXNjcmlw ..."
      },
      "format": "YAML"
    },
    "graphqlDocumentation": null
  },
  "code": null,
  "request_id": "269996898",
  "error_code": null
}

Gdzie:

contents: ciąg znaków zakodowany w formacie base64, który zawiera dokumentację API.

Usuwanie dokumentacji API

Aby usunąć dokumentację API:

UI

  1. Uzyskaj dostęp do katalogu interfejsów API.
  2. Kliknij kartę Interfejsy API, jeśli nie jest jeszcze wybrana.
  3. Kliknij wiersz interfejsu API, który chcesz edytować.
  4. Kliknij Edytuj.
  5. W panelu dokumentacja API wybierz Brak dokumentacji.
  6. Kliknij Zapisz.

curl

Aby usunąć istniejące treści, użyj interfejsu API aktualizacji:

curl -X PATCH "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC/documentation" \
    -H "Authorization: Bearer ACCESS_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{}'

Zastąp następujące elementy:

  • ORG_NAME nazwą organizacji. Na przykład: my-org.
  • SITE_ID z nazwą portalu w formacie ORG_NAME-PORTAL_NAME, gdzie ORG_NAME to nazwa organizacji, a PORTAL_NAME to nazwa portalu przekonwertowana na małe litery z usuniętymi spacjami i myślnikami. Na przykład: my-org-myportal.
  • API_DOC z wygenerowanym id dokumentu. Na przykład: 399668. Aby znaleźć tę wartość, użyj polecenia list API docs (lista dokumentów interfejsu API).

Ładunek odpowiedzi:

{
  "status": "success",
  "message": "ApiDocDocumentation updated",
  "data": {
    "oasDocumentation": null,
    "graphqlDocumentation": null
  },
  "code": null,
  "request_id": "304329676",
  "error_code": null
}

Zarządzanie kategoriami używanymi do wykrywania powiązanych interfejsów API

Oznacz interfejs API za pomocą kategorii, aby umożliwić programistom aplikacji odkrywanie powiązanych interfejsów API na stronie interfejsów API w aktywnym portalu. Dodawaj kategoriami i zarządzaj nimi zgodnie z opisem w sekcjach poniżej.

Odkrywaj kategorie

Aby wyświetlić interfejsy API w portalu, użyj interfejsu lub polecenia curl.

UI

Aby wyświetlić stronę Kategorie:

  1. Kliknij Opublikuj > Portale i wybierz portal.
  2. Na stronie głównej portalu kliknij Katalog interfejsów API.

    Możesz też wybrać Katalog interfejsów API w menu portalu w górnym pasku nawigacyjnym.

  3. Kliknij kartę Kategorie.

Na karcie Kategorie w katalogu interfejsów API wyświetla się lista kategorii zdefiniowanych w Twoim portalu.

Karta Kategorie, na której wyświetlają się nazwy kategorii oraz nazwy i łączna liczba przypisanych interfejsów API.

Jak widać na poprzednim rysunku, strona Interfejsy API umożliwia:

curl

Aby wyświetlić listę kategorii:

curl -X GET "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apicategories" \
    -H "Authorization: Bearer ACCESS_TOKEN"

Zastąp następujące elementy:

  • ORG_NAME nazwą organizacji. Na przykład: my-org.
  • SITE_ID z nazwą portalu w formacie ORG_NAME-PORTAL_NAME, gdzie ORG_NAME to nazwa organizacji, a PORTAL_NAME to nazwa portalu przekonwertowana na małe litery z usuniętymi spacjami i myślnikami. Na przykład: my-org-myportal.
  • ACCESS_TOKEN z tokenem uwierzytelniania używanym do uzyskiwania dostępu do interfejsu Apigee Edge API. Więcej informacji o uwierzytelnianiu i tokenach znajdziesz w artykule Uwierzytelnianie dostępu do interfejsu Edge API.

Ładunek odpowiedzi:

{
  "status": "success",
  "message": "all ApiCategory items returned",
  "data": [
    {
      "id": "e0518597-ece2-4d7d-ba7c-d1793df0f8db",
      "siteId": "my-org-myportal",
      "name": "My Category"
    },
    {
      "id": "61c1014c-89c9-40e6-be3c-69cca3505620",
      "siteId": "my-org-myportal",
      "name": "test2"
    }
  ],
  "code": null,
  "request_id": "1263510680",
  "error_code": null
}

Gdzie:

  • id: identyfikator elementu kategorii. Na przykład: 61c1014c-89c9-40e6-be3c-69cca3505620.

Dodawanie kategorii

Dodaj kategorię na jeden z tych sposobów:

Nowa kategoria zostanie dodana do strony Kategorie i będzie dostępna podczas dodawania lub edytowania innych interfejsów API.

Aby dodać kategorię, użyj interfejsu lub polecenia curl:

UI

Aby dodać kategorię ręcznie:

  1. Otwórz stronę Kategorie.
  2. Kliknij + Dodaj.
  3. Wpisz nazwę nowej kategorii.
  4. Opcjonalnie możesz wybrać co najmniej 1 interfejs API, który chcesz przypisać do kategorii.
  5. Kliknij Utwórz.

curl

Aby dodać kategorię:

curl -X POST "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apicategories" \
    -H "Authorization: Bearer ACCESS_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"name": "CATEGORY_NAME" }'

Zastąp następujące elementy:

  • ORG_NAME nazwą organizacji. Na przykład: my-org.
  • SITE_ID z nazwą portalu w formacie ORG_NAME-PORTAL_NAME, gdzie ORG_NAME to nazwa organizacji, a PORTAL_NAME to nazwa portalu przekonwertowana na małe litery z usuniętymi spacjami i myślnikami. Na przykład: my-org-myportal.
  • ACCESS_TOKEN z tokenem uwierzytelniania używanym do uzyskiwania dostępu do interfejsu Apigee Edge API. Więcej informacji o uwierzytelnianiu i tokenach znajdziesz w artykule Uwierzytelnianie dostępu do interfejsu Edge API.
  • CATEGORY_NAME z nazwą kategorii. Na przykład: demo-backend.

Ładunek odpowiedzi:

{
  "status": "success",
  "message": "API category created",
  "data": {
    "id": "61de810e-b48b-4cc1-8f22-959038aadcce",
    "siteId": "my-org-myportal",
    "name": "demo-backend"
  },
  "code": null,
  "request_id": "363146927",
  "error_code": null
}

Edytowanie kategorii

Aby edytować kategorię, użyj interfejsu lub polecenia curl:

UI

Aby edytować kategorię:

  1. Otwórz stronę Kategorie.
  2. Kliknij Edytuj.
  3. Edytuj nazwę kategorii.
  4. Dodawanie i usuwanie tagów API.
  5. Kliknij Zapisz.

curl

Aby edytować kategorię:

curl -X PATCH "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apicategories/CATEGORY_ID"  \
    -H "Authorization: Bearer ACCESS_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"name": "CATEGORY_NAME" }'

Zastąp następujące elementy:

  • ORG_NAME nazwą organizacji. Na przykład: my-org.
  • SITE_ID z nazwą portalu w formacie ORG_NAME-PORTAL_NAME, gdzie ORG_NAME to nazwa organizacji, a PORTAL_NAME to nazwa portalu przekonwertowana na małe litery, z usuniętymi spacjami i myślnikami. Na przykład: my-org-myportal.
  • CATEGORY_ID z identyfikatorem kategorii. Na przykład: bf6505eb-2a0f-47af-a00a-ded40ac72960. Kolejne identyfikatory kategorii oddziel przecinkami. Pobierz identyfikator kategorii za pomocą polecenia list API categories.
  • ACCESS_TOKEN z tokenem uwierzytelniania używanym do uzyskiwania dostępu do interfejsu Apigee Edge API. Więcej informacji o uwierzytelnianiu i tokenach znajdziesz w artykule Uwierzytelnianie dostępu do interfejsu Edge API.
  • CATEGORY_NAME z nazwą kategorii. Na przykład: demo-backend.

Ładunek odpowiedzi:

{
  "status": "success",
  "message": "ApiCategory updated",
  "data": {
    "id": "61de810e-b48b-4cc1-8f22-959038aadcce",
    "siteId": "my-org-myportal",
    "name": "demo-backend-test"
  },
  "code": null,
  "request_id": "1976875617",
  "error_code": null
}

Usuwanie kategorii

Gdy usuniesz kategorię, zostaną też usunięte wszystkie przypisane do niej tagi interfejsu API.

Aby usunąć kategorię, użyj interfejsu lub polecenia curl:

UI

Aby usunąć kategorię:

  1. Otwórz stronę Kategorie.
  2. Umieść kursor nad kategorią, którą chcesz edytować, aby wyświetlić menu działań.
  3. Kliknij  Usuń.
  4. Kliknij Usuń, aby potwierdzić.

curl

Aby usunąć kategorię:

curl -X DELETE "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apicategories/CATEGORY_ID" \
    -H "Authorization: Bearer ACCESS_TOKEN" \
    -H "Content-Type: application/json"

Zastąp następujące elementy:

  • ORG_NAME nazwą organizacji. Na przykład: my-org.
  • SITE_ID z nazwą portalu w formacie ORG_NAME-PORTAL_NAME, gdzie ORG_NAME to nazwa organizacji, a PORTAL_NAME to nazwa portalu przekonwertowana na małe litery, z usuniętymi spacjami i myślnikami. Na przykład: my-org-myportal.
  • CATEGORY_ID z identyfikatorem kategorii. Na przykład:bf6505eb-2a0f-47af-a00a-ded40ac72960. Pobierz identyfikator kategorii za pomocą polecenia list API categories.
  • ACCESS_TOKEN z tokenem uwierzytelniania używanym do uzyskiwania dostępu do interfejsu Apigee Edge API. Więcej informacji o uwierzytelnianiu i tokenach znajdziesz w artykule Uwierzytelnianie dostępu do interfejsu Edge API.

Ładunek odpowiedzi:

{
  "status": "success",
  "message": "ApiCategory deleted",
  "data": {
  },
  "code": null,
  "request_id": "2032819627",
  "error_code": null
}

Rozwiązywanie problemów z opublikowanymi interfejsami API

W kolejnych sekcjach znajdziesz informacje, które pomogą Ci rozwiązać konkretne błędy związane z naszymi opublikowanymi interfejsami API.

Błąd: podczas korzystania z opcji „Wypróbuj ten interfejs API” wystąpił błąd pobierania

Jeśli podczas korzystania z opcji Wypróbuj ten interfejs API pojawi się błąd TypeError: Failed to fetch, sprawdź te możliwe przyczyny i rozwiązania:

Błąd: nagłówek „Access-Control-Allow-Origin” zawiera wiele wartości „*, *”, ale dozwolona jest tylko jedna

Podczas korzystania z opcji Wypróbuj ten interfejs API możesz zobaczyć ten komunikat o błędzie, jeśli nagłówek Access-Control-Allow-Origin już istnieje:

The Access-Control-Allow-Origin header contains multiple values '*, *', but only one is allowed.

Aby naprawić ten błąd, zmodyfikuj zasadę AssignMessage, aby używać <Set> do ustawiania nagłówków CORS zamiast <Add>, jak pokazano w poniższym fragmencie. Więcej informacji znajdziesz w artykule Błąd CORS : nagłówek zawiera wiele wartości „*, *”, ale dozwolona jest tylko jedna.

<AssignMessage async="false" continueOnError="false" enabled="true" name="add-cors">
    <DisplayName>Add CORS</DisplayName>
    <FaultRules/>
    <Properties/>
    <Set>
        <Headers>
            <Header name="Access-Control-Allow-Origin">{request.header.origin}</Header>
            <Header name="Access-Control-Allow-Headers">origin, x-requested-with, accept, content-type, authorization</Header>
            <Header name="Access-Control-Max-Age">3628800</Header>
            <Header name="Access-Control-Allow-Methods">GET, PUT, POST, DELETE</Header>
        </Headers>
    </Set>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <AssignTo createNew="false" transport="http" type="response"/>
</AssignMessage>

Błąd: niedozwolone pole nagłówka żądania

Jeśli podczas korzystania z opcji Wypróbuj ten interfejs API pojawi się błąd Request header field not allowed podobny do tego poniżej, być może trzeba zaktualizować nagłówki obsługiwane w zasadach CORS. Na przykład:

Access to XMLHttpRequest ... has been blocked by CORS policy: Request header field
content-type is not allowed by Access-Control-Allow-Headers in preflight response

W tym przykładzie musisz dodać nagłówek content-type do sekcji Access-Control-Allow-Headers w zasadach AssignMessage CORS, zgodnie z opisem w artykule Dołączanie zasad Add CORS do nowego serwera proxy interfejsu API.

Błąd: odmowa dostępu podczas wywoływania serwera proxy interfejsu API za pomocą OAuth2

Zasady OAuthV2 Apigee zwracają odpowiedź tokena, która zawiera pewne właściwości niezgodne ze standardem RFC. Na przykład zasady zwrócą token o wartości BearerToken zamiast oczekiwanej wartości zgodnej z RFC Bearer. Ta nieprawidłowa odpowiedź token_type może spowodować błąd Access denied podczas korzystania z funkcji Wypróbuj ten interfejs API.

Aby rozwiązać ten problem, możesz utworzyć zasadę JavaScript lub AssignMessage, która przekształci dane wyjściowe zasady w format zgodny z zasadami. Więcej informacji znajdziesz w artykule zachowanie niezgodne z RFC.