Esta página se ha traducido con Cloud Translation API.

Publicar APIs

Esta página se aplica a Apigee y Apigee Hybrid.

Consulta la documentación de Apigee Edge.

Publica APIs en tu portal para que los desarrolladores de aplicaciones puedan usarlas, tal como se describe en las siguientes secciones.

Descripción general de la publicación de APIs

El proceso de publicación de APIs en tu portal consta de dos pasos:

Selecciona el producto de API que quieras publicar en tu portal.
Genera documentación de referencia de la API a partir de tu documento de OpenAPI o esquema de GraphQL para que los desarrolladores de aplicaciones puedan obtener información sobre tus APIs. Para obtener más información, consulta Acerca de la documentación de la API.

¿Qué se publica en el portal?

Cuando publicas una API, se realizan los siguientes cambios en tu portal automáticamente:

Documentación de referencia de la API La interfaz proporcionada depende de si publicas tu API mediante un documento OpenAPI o un esquema GraphQL. Consulta:
- SmartDocs (OpenAPI)
- Explorador de GraphQL
Se añade un enlace a la página de referencia de la API en la página APIs
La página APIs (incluida en el portal de ejemplo) proporciona una lista de todas las APIs publicadas en tu portal, ordenadas alfabéticamente, con enlaces a la documentación de referencia de cada API para obtener más información. También puedes personalizar lo siguiente:
- Imagen que se muestra en cada tarjeta de API
- Categorías usadas para etiquetar APIs y permitir que los desarrolladores descubran APIs relacionadas en la página de APIs
Nota: No puedes editar el contenido de esta página directamente, ya que no aparece en la lista de páginas de tu portal. Puedes editar el estilo de la página cuando personalices tu tema.

SmartDocs (OpenAPI)

Cuando publicas una API mediante un documento de OpenAPI, la documentación de referencia de la API de SmartDocs se añade a tu portal.

Los desarrolladores pueden consultar la documentación de referencia de la API de SmartDocs y usar el panel Probar esta API para hacer una solicitud a la API y ver el resultado. Probar esta API funciona con endpoints no seguros o seguros que usan autenticación básica, con clave de API u OAuth, en función del método de seguridad definido en tu documento OpenAPI. En el caso de OAuth, se admiten los siguientes flujos: código de autorización, contraseña y credenciales de cliente.

Página de documentación de referencia de la API con recuadros que muestran cómo autorizar la llamada a la API, desacoplar el panel Probar esta API, descargar la especificación pertinente y ejecutar la API.

Haz clic en Pantalla completa para ampliar el panel Probar esta API. El panel ampliado te permite ver la llamada curl y ejemplos de código en varios formatos, como HTTP, Python, Node.js y más, como se muestra a continuación.

Explorador de GraphQL

Cuando publicas una API mediante un esquema GraphQL, el Explorador de GraphQL se añade a tu portal. GraphQL Explorer es un espacio de pruebas interactivo para ejecutar consultas en tu API. El explorador se basa en GraphiQL, una implementación de referencia del IDE de GraphQL desarrollada por la fundación GraphQL.

Los desarrolladores pueden usar el Explorador de GraphQL para consultar la documentación interactiva basada en esquemas, crear y ejecutar consultas, ver los resultados de las consultas y descargar el esquema. Para proteger el acceso a tu API, los desarrolladores pueden enviar encabezados de autorización en el panel Encabezados de solicitud. Para obtener más información sobre GraphQL, consulta graphql.org.

Explorador de GraphQL en el portal

Acerca de la documentación de la API

Cada documento de OpenAPI o GraphQL sirve como fuente de información veraz durante todo el ciclo de vida de una API. El mismo documento se usa en cada fase del ciclo de vida de la API, desde el desarrollo hasta la publicación y la monitorización. Cuando modificas un documento, debes tener en cuenta el impacto que tienen los cambios en tu API en otras fases del ciclo de vida, tal como se describe en ¿Qué ocurre si modifico un documento?

Cuando publicas tu API en un portal, guardas una versión del documento OpenAPI o GraphQL para generar la documentación de referencia de la API. Si modificas el documento, puedes actualizar la documentación de referencia de la API publicada en el portal para reflejar los últimos cambios.

Acerca de las URLs de retrollamada

Si tus aplicaciones requieren una URL de retrollamada, como cuando se usa el tipo de concesión de código de autorización de OAuth 2.0 (a menudo denominado OAuth de tres pasos), puedes pedir a los desarrolladores que especifiquen una URL de retrollamada cuando registren sus aplicaciones. La URL de retrollamada suele especificar la URL de una aplicación designada para recibir un código de autorización en nombre de la aplicación cliente. Para obtener más información, consulta Implementar el tipo de concesión de código de autorización.

Puedes configurar si quieres que se requiera una URL de retrollamada durante el registro de la aplicación al añadir una API a tu portal. Puedes modificar este ajuste en cualquier momento, tal como se describe en Gestionar la URL de retrollamada de una API.

Al registrar una aplicación, los desarrolladores deben introducir una URL de retrollamada para todas las APIs que lo requieran, tal como se describe en el artículo Registrar aplicaciones.

Configurar el proxy de API para que admita el panel Probar esta API

Antes de publicar tus APIs mediante un documento de OpenAPI, tendrás que configurar tu proxy de API para que admita solicitudes en el panel Probar esta API de la documentación de referencia de la API SmartDocs. Para ello, sigue estos pasos:

Añade compatibilidad con CORS a tus proxies de API para aplicar solicitudes entre orígenes del lado del cliente.
CORS es un mecanismo estándar que permite que las llamadas XMLHttpRequest (XHR) de JavaScript ejecutadas en una página web interactúen con recursos de dominios que no son de origen. CORS es una solución que se implementa habitualmente para la política de coincidencia de origen que aplican todos los navegadores.
Actualiza la configuración de tu proxy de API si usas la autenticación básica o OAuth 2.0.

En la siguiente tabla se resumen los requisitos de configuración del proxy de API para admitir el panel Probar esta API en la documentación de referencia de la API SmartDocs en función del acceso de autenticación.

Acceso de autenticación	Requisitos de configuración de las políticas
Ninguna o clave de API	Para añadir compatibilidad con CORS a tu proxy de API, sigue los pasos descritos en el artículo Añadir compatibilidad con CORS a un proxy de API.
Autenticación básica	Sigue estos pasos: Para añadir compatibilidad con CORS a tu proxy de API, sigue los pasos descritos en el artículo Añadir compatibilidad con CORS a un proxy de API. En la política de CORS, asegúrate de que el encabezado `Access-Control-Allow-Headers` incluya el atributo `authorization`. Por ejemplo: `<Header name="Access-Control-Allow-Headers"> origin, x-requested-with, accept, content-type, authorization </Header>`
OAuth 2.0	Para añadir compatibilidad con CORS a tu proxy de API, sigue los pasos descritos en el artículo Añadir compatibilidad con CORS a un proxy de API. En la política de CORS, asegúrate de que el encabezado `Access-Control-Allow-Headers` incluya el atributo `authorization`. Por ejemplo: `<Header name="Access-Control-Allow-Headers"> origin, x-requested-with, accept, content-type, authorization </Header>` Corrija el comportamiento no conforme con RFC en su política de OAuth 2.0. Para mayor comodidad, usa la solución de ejemplo de OAuth 2.0 que se proporciona en GitHub o sigue estos pasos: Comprueba que el elemento `<GrantType>` de la política de OAuth 2.0 se haya definido como `request.formparam.grant_type` (parámetro de formulario). Para obtener más información, consulta <GrantType>. Asegúrate de que el `token_type` de la política de OAuth 2.0 esté configurado como `Bearer` y no como el valor predeterminado `BearerToken`.

Gestiona APIs

Gestiona tus APIs como se describe en las siguientes secciones.

Ver APIs

Usa la consola o el comando curl para ver las APIs que hay en tu portal.

Para ver el catálogo de APIs, sigue estos pasos:

Consola

Interfaz de usuario de Cloud Console

En la consola de Apigee en Cloud, ve a la página Distribución > Portales.

Ir a Portales
Haz clic en tu portal.
Haz clic en API Catalog (Catálogo de APIs).
Haz clic en la pestaña APIs. Se muestra una lista de las APIs que se han añadido a tu portal.

Interfaz clásica

Seleccione Publicar > Portales y elija el portal.
En la página principal del portal, haz clic en Catálogo de APIs.
También puedes seleccionar Catálogo de APIs en el menú desplegable del portal en el menú de navegación superior.
En la pestaña APIs del catálogo de APIs se muestra una lista de las APIs que se han añadido a tu portal.

La pestaña APIs le permite hacer lo siguiente:

Ver los detalles de las APIs disponibles en tu portal
Añadir una API a tu portal
Para editar una API en tu portal, realiza una o varias de las siguientes tareas:
Quitar una API de tu portal
Gestionar las categorías
Identifica rápidamente las APIs huérfanas cuyo producto de API asociado se ha eliminado de la consola de Google Cloud y vuelve a crear el producto de API o elimina la API de tu portal.

curl

Para enumerar las APIs con organizations.sites.apidocs/list, sigue estos pasos:

curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)"

Haz los cambios siguientes:

ORG_NAME con el nombre de la organización. Por ejemplo, my-org.
SITE_ID con el nombre del portal, en el formato ORG_NAME-PORTAL_NAME, donde ORG_NAME es el nombre de la organización y PORTAL_NAME es el nombre del portal convertido a minúsculas y con los espacios y los guiones eliminados. Por ejemplo, my-org-myportal.

Consulta las notas sobre la paginación para obtener instrucciones sobre cómo usar la paginación en la carga útil de la respuesta.

Carga útil de la respuesta:

{
  "status": "success",
  "message": "one page of apidocs returned",
  "requestId": "1167960478",
  "data": [
    {
      "siteId": "my-org-myportal",
      "title": "Hello New World",
      "description": "Simple hello new world example",
      "specId": "hellowworld",
      "modified": "1695841621000",
      "anonAllowed": true,
      "imageUrl": "/files/camper1.jpg?v=1695841491415",
      "id": "381054",
      "categoryIds": [
        "e0518597-ece2-4d7d-ba7c-d1793df0f8db",
        "61c1014c-89c9-40e6-be3c-69cca3505620"
      ],
      "published": true,
      "apiProductName": "Hello New World"
    },
    {
      "siteId": "my-org-myportal",
      "title": "mock-product",
      "description": "Mock product",
      "specId": "apigee spec",
      "modified": "1698956849000",
      "anonAllowed": true,
      "id": "399638",
      "categoryIds": [
        "e0518597-ece2-4d7d-ba7c-d1793df0f8db"
      ],
      "published": true,
      "apiProductName": "mock-product"
    },
    {
      "siteId": "my-org-myportal",
      "title": "Hello World 2",
      "description": "Simple hello world example",
      "specId": "hello-new-world",
      "modified": "1698950207000",
      "anonAllowed": true,
      "imageUrl": "/files/book-tree.jpg?v=1698165437881",
      "id": "399668",
      "categoryIds": [
        "e0518597-ece2-4d7d-ba7c-d1793df0f8db",
        "61c1014c-89c9-40e6-be3c-69cca3505620"
      ],
      "published": true,
      "apiProductName": "Hello World 2"
    }
  ],
  "nextPageToken": ""
}

Donde:

modified: Hora en la que se modificó por última vez el elemento del catálogo en milisegundos desde el inicio del registro de tiempo. Por ejemplo, 1698165480000.
id: El ID del artículo del catálogo. Por ejemplo, 399668.

Notas sobre la paginación:

Tamaño de página: Use pageSize para especificar el número de elementos de la lista que se devolverán en una página. El valor predeterminado es 25 y el máximo es 100. Si hay más páginas, nextPageToken se rellena con un token:

curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs?pageSize=PAGE_SIZE" \
   -H "Authorization: Bearer $(gcloud auth print-access-token)"

Sustituye:

PAGE_SIZE con el número de elementos de la lista que se devolverán en una página. Por ejemplo, 10.

Carga útil de la respuesta:

{
  "status": "success",
  "message": "one page of apidocs returned",
  "requestId": "918815495",
  "data": [
    {
      "siteId": "my-org-myportal",
      "title": "Hello New World",
      "description": "Simple hello new world example",
      "specId": "apigee",
      "modified": "1699146887000",
      "anonAllowed": true,
      "imageUrl": "/files/camper1.jpg?v=1695841491415",
      "id": "381054",
      "categoryIds": [
        "e0518597-ece2-4d7d-ba7c-d1793df0f8db",
        "61c1014c-89c9-40e6-be3c-69cca3505620"
      ],
      "published": true,
      "apiProductName": "Hello New World"
    }
  ],
  "nextPageToken": "7zcqrin9l6xhi4nbrb9"
}

Token de página:

Usa pageToken para obtener las páginas siguientes cuando haya más de una:
```
curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs?pageSize=PAGE_SIZE&pageToken=PAGE_TOKEN" \
      -H "Authorization: Bearer $(gcloud auth print-access-token)"
```
Sustituye:
- PAGE_SIZE con el número de elementos de la lista que se devolverán en una página. Por ejemplo, 10.
- PAGE_TOKEN con el valor nextPageToken. Por ejemplo, 7zcqrin9l6xhi4nbrb9.

Añadir una API

Para añadir una API a tu portal, sigue estos pasos:

Consola

Acceder al catálogo de APIs.
Haga clic en la pestaña APIs, si aún no lo ha hecho.
Añade una API.
Interfaz de usuario de Cloud Console
1. Haz clic en + API. Se muestra el cuadro de diálogo Añadir una API.
2. Selecciona el producto de API que quieras añadir a tu portal.
Interfaz clásica
1. Haz clic en Añadir.
  
  Se muestra el cuadro de diálogo Añadir un producto de API al catálogo.
2. Selecciona el producto de API que quieras añadir a tu portal.
3. Haz clic en Siguiente. Se muestra la página Detalles de la API.

Configura el contenido de la documentación de referencia de la API y su visibilidad en el portal:

Campo	Descripción
Publicado	Selecciona Publicado para publicar la API en tu portal. Desmarque la casilla si no está listo para publicar la API. Puede cambiar el ajuste más adelante, tal como se describe en el artículo sobre cómo publicar o dejar de publicar una API.
Título visible	Actualiza el título de tu API que se muestra en el catálogo. De forma predeterminada, se usa el nombre del producto de la API. Puedes cambiar el título visible más adelante, tal como se describe en Editar el título visible y la descripción.
Descripción de la pantalla	Actualiza la descripción de tu API que se muestra en el catálogo. De forma predeterminada, se usa la descripción del producto de la API. Puedes cambiar la descripción visible más adelante, tal como se describe en el artículo Editar el título y la descripción visibles.
Requerir que los desarrolladores especifiquen una URL de retrollamada	Habilita esta opción si quieres que los desarrolladores de aplicaciones especifiquen una URL de retrollamada. Puedes añadir o actualizar la URL de retrollamada más adelante, tal como se describe en el artículo Gestionar la URL de retrollamada de una API.
Documentación de la API	Para usar un documento de OpenAPI, haz lo siguiente: Interfaz de usuario de Cloud Console Selecciona Documento de OpenAPI. Haz clic en Seleccionar. Sigue uno de estos pasos: Haz clic en la pestaña Subir y sube un archivo. Haga clic en la pestaña URL e importe una especificación proporcionando un nombre y una URL desde la que importar. Haz clic en Seleccionar. Interfaz clásica Selecciona Documento de OpenAPI. Haz clic en Seleccionar documento. Sigue uno de estos pasos: Haga clic en la pestaña Subir archivo y suba un archivo. Haz clic en la pestaña Importar desde una URL e importa una especificación proporcionando un nombre y una URL desde la que importar. Haz clic en Seleccionar. Para usar un esquema de GraphQL, haz lo siguiente: Interfaz de usuario de Cloud Console Selecciona Esquema de GraphQL. Haz clic en Seleccionar. Ve al esquema de GraphQL y selecciónalo. Especifica la URL de endpoint, que es el URI del endpoint de GraphQL que consultarán los consumidores de la API. Haz clic en Seleccionar. Interfaz clásica Selecciona Esquema de GraphQL. Haz clic en Seleccionar documento. Ve al esquema de GraphQL y selecciónalo. Haz clic en Abrir. Especifica la URL de endpoint, que es el URI del endpoint de GraphQL que consultarán los consumidores de la API. Haz clic en Guardar. También puedes seleccionar Sin documentación y añadirla más adelante, una vez que se haya añadido la API, tal como se describe en Gestionar la documentación de la API. Nota: Cuando se importa un documento de OpenAPI mediante una URL, no se siguen las redirecciones.
Visibilidad	Si no te has registrado en la versión preliminar de la función de gestión de audiencias, selecciona una de las siguientes opciones: Usuarios anónimos para permitir que todos los usuarios vean la API. Usuarios registrados: permite que solo los usuarios registrados vean la API. Si te has registrado en la versión de vista previa de la función de gestión de audiencias, selecciona una de las siguientes opciones: Público (visible para cualquier persona) para permitir que todos los usuarios vean la API. Usuarios autenticados: para permitir que solo los usuarios registrados vean la API. Audiencias seleccionadas para seleccionar las audiencias específicas que quieres que puedan ver la API. Puedes gestionar la visibilidad de la audiencia más adelante, tal como se describe en el artículo Gestionar la visibilidad de una API.
Imagen visible	Para mostrar una imagen en la tarjeta de la API en la página APIs, haz clic en Seleccionar imagen. En el cuadro de diálogo Seleccionar imagen, elija una imagen, suba una nueva o proporcione la URL de una imagen externa y haga clic en Seleccionar. Previsualiza la miniatura de la API y haz clic en Seleccionar. Puedes añadir una imagen más adelante, tal como se describe en Gestionar la imagen de una tarjeta de API. Cuando especifique la URL de una imagen externa, esta no se subirá a sus recursos. Además, la carga de la imagen en el portal integrado estará sujeta a su disponibilidad, que puede estar bloqueada o restringida por las políticas de seguridad de contenido.
Categorías	Añade las categorías con las que se etiquetará la API para que los desarrolladores de aplicaciones puedan descubrir APIs relacionadas en la página de APIs. Para identificar una categoría, sigue estos pasos: Selecciona una categoría de la lista desplegable. Añade una categoría nueva como se describe en la sección Añadir una categoría. La nueva categoría se añade a la página Categorías y está disponible al añadir o editar otras APIs.

Haz clic en Guardar.

curl

Para añadir una API a tu portal mediante organizations.sites.apidocs.create, sigue estos pasos:

curl -X POST "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs" \
         -H "Authorization: Bearer $(gcloud auth print-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",
         }'

Haz los cambios siguientes:

ORG_NAME con el nombre de la organización. Por ejemplo, my-org.
SITE_ID con el nombre del portal, en el formato ORG_NAME-PORTAL_NAME, donde ORG_NAME es el nombre de la organización y PORTAL_NAME es el nombre del portal convertido a minúsculas y con los espacios y los guiones eliminados. Por ejemplo, my-org-myportal.
TITLE con el título visible. Por ejemplo, Hello World 2.
DESCRIPTION con la descripción de la pantalla. Por ejemplo, Simple hello world example.
ANON_TRUE_OR_FALSE con true o false (valor predeterminado), donde true habilita el acceso de usuarios anónimos. Este ajuste se ignora si te has registrado en la versión preliminar de la función de gestión de audiencias.
IMAGE_URL con la URL de una imagen externa que se usa en el artículo del catálogo o una ruta de archivo de archivos de imagen almacenados en el portal, por ejemplo, /files/book-tree.jpg. Cuando especifiques la URL de una imagen externa, esta no se subirá a tus recursos. Además,la carga de la imagen en el portal integrado estará sujeta a su disponibilidad, que puede estar bloqueada o restringida por las políticas de seguridad de contenido.
CALLBACK_TRUE_OR_FALSE con true o false (valor predeterminado), donde true requiere que el usuario del portal introduzca una URL al gestionar la aplicación.
CATEGORY_ID con el ID de la categoría. Por ejemplo, bf6505eb-2a0f-47af-a00a-ded40ac72960. Separa los diferentes IDs de categoría con comas. Obtén el ID de la categoría con el comando list API categories.

Nota: Para añadir categorías aquí, ya debes haberlas definido. Consulta las instrucciones para añadir una categoría y explorar categorías.
PUBLISHED_TRUE_OR_FALSE con true o false (valor predeterminado), donde true indica que la API está disponible públicamente.
API_PRODUCT con el nombre del producto de API. Por ejemplo, Hello World 2.

Carga útil de la respuesta:

{
  "status": "success",
  "message": "API created",
  "requestId": "1662161889",
  "data": {
    "siteId": "my-org-myportal",
    "title": "Hello World 2",
    "description": "Simple hello world example",
    "modified": "1698948807000",
    "anonAllowed": true,
    "imageUrl": "/files/book-tree.jpg",
    "id": "409405",
    "requireCallbackUrl": true,
    "categoryIds": [
      "88fbfd1d-9300-49f7-bfc2-531ade4c63d4",
      "630c4cf9-109a-48b0-98cc-ef4c12ae4474"
    ],
    "published": true,
    "apiProductName": "Hello World 2"
  }
}

Donde:

modified: Hora en la que se modificó por última vez el elemento del catálogo en milisegundos desde el inicio del registro de tiempo. Por ejemplo, 1698165480000.
id: El ID del artículo del catálogo. Por ejemplo, 399668.

Editar una API

Una vez que hayas añadido una API, usa la consola o una llamada a la API para hacer cambios.

En esta sección se ofrece un ejemplo detallado de los pasos que debes seguir para modificar una API en tu portal.

Consulta las secciones siguientes para ver los ajustes de modificación específicos.

Consola

Acceder al catálogo de APIs.
Haga clic en la pestaña APIs, si aún no lo ha hecho.
Haz clic en la fila de la API que quieras editar.
Haz clic en Editar.
Haz las modificaciones que quieras. Consulta las descripciones de las opciones en Añadir una API.
Haz clic en Guardar.

curl

Una vez que hayas añadido una API, usa la llamada organizations.sites.apidocs.update para hacer cambios.

En este ejemplo se muestran los pasos necesarios para cambiar el estado de publicación de tu API en el portal de true a false. Si es necesario, puedes cambiar más de un ajuste en una llamada a la API.

Obtén una lista de las APIs de tu portal con organizations.sites.apidocs/list para localizar el id generado que identifica de forma única cada API:

curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)"

Haz los cambios siguientes:

ORG_NAME con el nombre de la organización. Por ejemplo, my-org.
SITE_ID con el nombre del portal, en el formato ORG_NAME-PORTAL_NAME, donde ORG_NAME es el nombre de la organización y PORTAL_NAME es el nombre del portal convertido a minúsculas y con los espacios y los guiones eliminados. Por ejemplo, my-org-myportal.

Carga útil de la respuesta:

{
  "status": "success",
  "message": "one page of apidocs returned",
  "requestId": "1167960478",
  "data": [
    {
      "siteId": "my-org-myportal",
      "title": "Hello New World",
      "description": "Simple hello new world example",
      "specId": "hellowworld",
      "modified": "1695841621000",
      "anonAllowed": true,
      "imageUrl": "/files/camper1.jpg?v=1695841491415",
      "id": "381054",
      "categoryIds": [
        "e0518597-ece2-4d7d-ba7c-d1793df0f8db",
        "61c1014c-89c9-40e6-be3c-69cca3505620"
      ],
      "published": true,
      "apiProductName": "Hello New World"
    },
    {
      "siteId": "my-org-myportal",
      "title": "mock-product",
      "description": "Mock product",
      "specId": "apigee spec",
      "modified": "1698956849000",
      "anonAllowed": true,
      "id": "399638",
      "categoryIds": [
        "e0518597-ece2-4d7d-ba7c-d1793df0f8db"
      ],
      "published": true,
      "apiProductName": "mock-product"
    },
    {
      "siteId": "my-org-myportal",
      "title": "Hello World 2",
      "description": "Simple hello world example",
      "specId": "hello-new-world",
      "modified": "1698950207000",
      "anonAllowed": true,
      "imageUrl": "/files/book-tree.jpg?v=1698165437881",
      "id": "399668",
      "categoryIds": [
        "e0518597-ece2-4d7d-ba7c-d1793df0f8db",
        "61c1014c-89c9-40e6-be3c-69cca3505620"
      ],
      "published": true,
      "apiProductName": "Hello World 2"
    }
  ]
}

Donde:

modified: Hora en la que se modificó por última vez el elemento del catálogo en milisegundos desde el inicio del registro de tiempo. Por ejemplo, 1698165480000.
id: El ID del artículo del catálogo. Por ejemplo, 399668.

Usa la llamada organizations.sites.apidocs.get para devolver los valores actuales de una API específica:

curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)"

Haz los cambios siguientes:

ORG_NAME con el nombre de la organización. Por ejemplo, my-org.
SITE_ID con el nombre del portal, en el formato ORG_NAME-PORTAL_NAME, donde ORG_NAME es el nombre de la organización y PORTAL_NAME es el nombre del portal convertido a minúsculas y con los espacios y los guiones eliminados. Por ejemplo, my-org-myportal.
API_DOC con la id generada del documento. Por ejemplo, 399668. Usa el comando list API docs para encontrar este valor.

Carga útil de la respuesta:

{
  "status": "success",
  "message": "apidoc returned",
  "requestId": "2072952505",
  "data": {
    "siteId": "my-org-myportal",
    "title": "Hello World 2",
    "description": "Simple hello world example",
    "specId": "hello-new-world",
    "modified": "1698950207000",
    "anonAllowed": true,
    "imageUrl": "/files/book-tree.jpg?v=1698165437881",
    "id": "399668",
    "categoryIds": [
      "e0518597-ece2-4d7d-ba7c-d1793df0f8db",
      "61c1014c-89c9-40e6-be3c-69cca3505620"
    ],
    "published": true,
    "apiProductName": "Hello World 2"
  }
}

Incluya los valores mutables que quiera conservar en la llamada organizations.sites.apidocs.update y modifique los valores que quiera cambiar. Si omite una línea, se usará la configuración predeterminada. En este ejemplo, cambia el ajuste published de true a false:
```
curl -X PUT "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
     -H "Authorization: Bearer $(gcloud auth print-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": false,
        "apiProductName": "API_PRODUCT",
     }'
```
Haz los cambios siguientes:
- TITLE con el título visible. Por ejemplo, Hello World 2.
- DESCRIPTION con la descripción de la pantalla. Por ejemplo, Simple hello world example.
- ANON_TRUE_OR_FALSE con true o false (valor predeterminado), donde true habilita el acceso de usuarios anónimos. Este ajuste se ignora si te has registrado en la versión preliminar de la función de gestión de audiencias.
- IMAGE_URL con la URL de una imagen externa que se usa en el artículo del catálogo o una ruta de archivo de archivos de imagen almacenados en el portal, por ejemplo, /files/book-tree.jpg. Cuando especifiques la URL de una imagen externa, esta no se subirá a tus recursos. Además,la carga de la imagen en el portal integrado estará sujeta a su disponibilidad, que puede estar bloqueada o restringida por las políticas de seguridad de contenido.
- CALLBACK_TRUE_OR_FALSE con true o false (valor predeterminado), donde true requiere que el usuario del portal introduzca una URL al gestionar la aplicación.
- CATEGORY_ID con el ID de la categoría. Por ejemplo, bf6505eb-2a0f-47af-a00a-ded40ac72960. Separa los diferentes IDs de categoría con comas. Obtén el ID de la categoría con el comando list API categories.
- API_PRODUCT con el nombre del producto de API. Por ejemplo, Hello World 2.
Carga útil de la respuesta:
```
{
  "status": "success",
  "message": "ApiDoc updated",
  "requestId": "197181831",
  "data": {
    "siteId": "my-org-myportal",
    "title": "Hello World 2",
    "description": "Simple hello world example.",
    "modified": "1698884328000",
    "anonAllowed": true,
    "imageUrl": "/files/book-tree.jpg",
    "id": "408567",
    "requireCallbackUrl": true,
    "categoryIds": [
      "88fbfd1d-9300-49f7-bfc2-531ade4c63d4",
      "630c4cf9-109a-48b0-98cc-ef4c12ae4474"
    ],
    "published": PUBLISHED_TRUE_OR_FALSE,
    "apiProductName": "Hello World 2"
  }
}
```

Publicar o dejar de publicar una API

La publicación es el proceso de poner tus APIs a disposición de los desarrolladores de aplicaciones para que las consuman.

Para publicar o anular la publicación de una API en tu portal, sigue estos pasos:

Consola

Acceder al catálogo de APIs.
Haga clic en la pestaña APIs, si aún no lo ha hecho.
Haz clic en la fila de la API que quieras editar.
Haz clic en Editar.
Selecciona o desmarca Publicado (aparece en el catálogo) para publicar o anular la publicación de la API en tu portal, respectivamente.
Haz clic en Guardar.

curl

Incluye una de las siguientes opciones en la llamada update:

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

Para editar la API, sigue estos pasos:

Usa la llamada organizations.sites.apidocs.get para devolver los valores actuales:

curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
     -H "Authorization: Bearer $(gcloud auth print-access-token)"

Usa la llamada organizations.sites.apidocs.update para editar la API. Incluye los valores mutables que quieras conservar y modifica los que quieras cambiar. Si omite un ajuste mutable, se usará el valor predeterminado.

curl -X PUT "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
     -H "Authorization: Bearer $(gcloud auth print-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",
     }'

Consulta Editar una API para ver un ejemplo detallado de los pasos, las variables y la carga útil devuelta.

Gestionar la visibilidad de una API

Gestiona la visibilidad de una API en tu portal permitiendo el acceso a lo siguiente:

Público (visible para cualquier persona)
Usuarios autenticados
Audiencias seleccionadas (si te has registrado en la versión de vista previa de la función de gestión de audiencias)

Nota: Si define la visibilidad como Usuarios autenticados o Audiencias seleccionadas, los motores de búsqueda no indexarán la API.

Para gestionar la visibilidad de una API en tu portal, sigue estos pasos:

Consola

Acceder al catálogo de APIs.
Haga clic en la pestaña APIs, si aún no lo ha hecho.
Haz clic en la fila de la API que quieras editar.
Haz clic en Editar.
Selecciona el ajuste de visibilidad. Si te has registrado en la versión preliminar de la función de audiencias, selecciona una de las siguientes opciones en Visibilidad de la API:
- Público (visible para cualquier persona) para permitir que todos los usuarios vean la página.
- Usuarios autenticados para permitir que solo los usuarios registrados vean la página.
- Audiencias seleccionadas para elegir las audiencias específicas que quieres que puedan ver la página. Consulta Gestionar las audiencias de tu portal.
De lo contrario, seleccione una de las siguientes opciones en Audiencia:
- Usuarios anónimos para permitir que todos los usuarios vean la página.
- Usuarios registrados para permitir que solo los usuarios registrados vean la página.
Haz clic en Guardar.

curl

Si te has registrado en la versión preliminar de la función de gestión de audiencias, usa la consola para gestionar las audiencias.

Si no te has registrado en la función de gestión de audiencias, la visibilidad se gestiona mediante anonAllowed.

Incluye una de las siguientes opciones en la llamada update:

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

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

Para editar la API, sigue estos pasos:

Usa la llamada organizations.sites.apidocs.get para devolver los valores actuales:

curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
     -H "Authorization: Bearer $(gcloud auth print-access-token)"

curl -X PUT "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
     -H "Authorization: Bearer $(gcloud auth print-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",
     }'

Consulta Editar una API para ver un ejemplo detallado de los pasos, las variables y la carga útil devuelta.

Gestionar la URL de retrollamada de una API

Gestionar la URL de retrollamada de una API. Consulta Información sobre las URLs de retrollamada.

Para gestionar la URL de retrollamada de una API, sigue estos pasos:

Consola

Acceder al catálogo de APIs.
Haga clic en la pestaña APIs, si aún no lo ha hecho.
Haz clic en la fila de la API que quieras editar.
Haz clic en Editar.
Seleccione o desactive la opción Requerir que los desarrolladores especifiquen una URL de retrollamada para indicar si es obligatoria o no.
Haz clic en Guardar.

curl

Incluye una de las siguientes opciones en la llamada update:

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

Para editar la API, sigue estos pasos:

Usa la llamada organizations.sites.apidocs.get para devolver los valores actuales:

curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
     -H "Authorization: Bearer $(gcloud auth print-access-token)"

curl -X PUT "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
     -H "Authorization: Bearer $(gcloud auth print-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",
     }'

Consulta Editar una API para ver un ejemplo detallado de los pasos, las variables y la carga útil devuelta.

Gestionar la imagen de una tarjeta de API

Gestiona la imagen que aparece con una tarjeta de API en la página APIs añadiendo o cambiando la imagen actual.

Para gestionar la imagen de una tarjeta de API, sigue estos pasos:

Consola

Acceder al catálogo de APIs.
Haga clic en la pestaña APIs, si aún no lo ha hecho.
Haz clic en la fila de la API que quieras editar.
Haz clic en Editar.
Localiza y selecciona una imagen:
Interfaz de usuario de Cloud Console
- Haz clic en Seleccionar para especificar una imagen.
- Haz clic en x para quitar la imagen.
Interfaz clásica
- Haz clic en Seleccionar imagen para especificar una imagen si no hay ninguna seleccionada.
- Haz clic en Cambiar imagen para especificar otra imagen.
- Haz clic en la x de la imagen para quitarla.
Cuando especifique una imagen, indique una imagen con una URL externa utilizada para el elemento de catálogo o una ruta de archivo para archivos de imagen almacenados en el portal, por ejemplo, /files/book-tree.jpg. Cuando especifiques la URL de una imagen externa, esta no se subirá a tus recursos. Además, la carga de la imagen en el portal integrado estará sujeta a su disponibilidad, que puede estar bloqueada o restringida por las políticas de seguridad del contenido.
Haz clic en Guardar.

curl

Incluye lo siguiente en la llamada update:

  # Omit line for no image file

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

Para editar la API, sigue estos pasos:

Usa la llamada organizations.sites.apidocs.get para devolver los valores actuales:

curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
     -H "Authorization: Bearer $(gcloud auth print-access-token)"

curl -X PUT "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
     -H "Authorization: Bearer $(gcloud auth print-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",
     }'

Consulta Editar una API para ver un ejemplo detallado de los pasos, las variables y la carga útil devuelta.

Etiquetar una API con categorías

Las categorías ayudan a los desarrolladores de aplicaciones a descubrir APIs relacionadas. Consulta también Gestionar categorías.

Para etiquetar una API con categorías, sigue estos pasos:

Consola

Acceder al catálogo de APIs.
Haga clic en la pestaña APIs, si aún no lo ha hecho.
Haz clic en la fila de la API que quieras editar.
Haz clic en Editar.
Especifica una categoría.
Interfaz de usuario de Cloud Console
1. Selecciona una o varias categorías en la lista desplegable Categorías. Si no hay categorías, consulte Gestionar categorías.
2. Haz clic en Aceptar.
Interfaz clásica
1. Haga clic en el campo Categorías y siga uno de estos pasos:
  - Selecciona una categoría de la lista desplegable.
  - Añade una categoría nueva escribiendo su nombre y pulsando Intro. La nueva categoría se añadirá a la página Categorías y estará disponible al añadir o editar otras APIs.
2. Repite el proceso para etiquetar la API con más categorías.
Haz clic en Guardar.

curl

Incluye lo siguiente en la llamada update:

  # Omit line for no categories

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

Usa el comando list categories para obtener los números de ID de las categorías.

Para editar la API, sigue estos pasos:

Usa la llamada organizations.sites.apidocs.get para devolver los valores actuales:

curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
     -H "Authorization: Bearer $(gcloud auth print-access-token)"

curl -X PUT "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
     -H "Authorization: Bearer $(gcloud auth print-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",
     }'

Consulta Editar una API para ver un ejemplo detallado de los pasos, las variables y la carga útil devuelta.

Editar el título y la descripción

Para editar el título y la descripción que se muestran, sigue estos pasos:

Consola

Acceder al catálogo de APIs.
Haga clic en la pestaña APIs, si aún no lo ha hecho.
Haz clic en la fila de la API que quieras editar.
Haz clic en Editar.
Edita los campos Título visible y Descripción visible según sea necesario.
Haz clic en Guardar.

curl

Incluye lo siguiente en la llamada update:

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

Para editar la API, sigue estos pasos:

Usa la llamada organizations.sites.apidocs.get para devolver los valores actuales:

curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
     -H "Authorization: Bearer $(gcloud auth print-access-token)"

curl -X PUT "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
     -H "Authorization: Bearer $(gcloud auth print-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",
     }'

Consulta Editar una API para ver un ejemplo detallado de los pasos, las variables y la carga útil devuelta.

Eliminar una API

Para quitar una API de tu portal, sigue estos pasos:

Consola

Acceder al catálogo de APIs.
Seleccione la pestaña APIs, si aún no lo ha hecho.
Elimina la API.
Interfaz de usuario de Cloud Console
Haz clic en Más > Eliminar.
Interfaz clásica
1. Coloca el cursor sobre la API de la lista para que se muestre el menú de acciones.
2. Haz clic en Eliminar.
Haz clic en Eliminar para confirmar la acción.

curl

Para eliminar una API de tu portal mediante organizations.sites.apidocs.delete, sigue estos pasos:

curl -X DELETE "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)"

Haz los cambios siguientes:

ORG_NAME con el nombre de la organización. Por ejemplo, my-org.
SITE_ID con el nombre del portal, en el formato ORG_NAME-PORTAL_NAME, donde ORG_NAME es el nombre de la organización y PORTAL_NAME es el nombre del portal convertido a minúsculas y con los espacios y los guiones eliminados. Por ejemplo, my-org-myportal.
API_DOC con la id generada del documento. Por ejemplo, 399668. Usa el comando list API docs para encontrar este valor.

Carga útil de la respuesta:

{
  "status":"success",
  "message":"Apidoc deleted",
  "requestId":"645138256"
}

Gestionar la documentación de la API

En las siguientes secciones se describe cómo actualizar, descargar o eliminar la documentación de la API.

Actualizar la documentación de la API

Una vez que hayas publicado tu API, podrás subir una nueva versión del documento OpenAPI o GraphQL en cualquier momento.

Para subir otra versión de la documentación de la API, sigue estos pasos:

Consola

Acceder al catálogo de APIs.
Haga clic en la pestaña APIs, si aún no lo ha hecho.
Haz clic en la fila de la API que quieras editar.
Haz clic en Editar.
Para consultar la documentación de la API, selecciona una de las siguientes opciones:
- Documento de OpenAPI
- Esquema de GraphQL
Busca el archivo.
Interfaz de usuario de Cloud Console
1. Haz clic en Seleccionar.
2. Busca el archivo y selecciónalo.
Interfaz clásica
1. Haz clic en Seleccionar documento y elige la última versión del documento.
En GraphQL, especifica la URL de endpoint.
Haz clic en Seleccionar.
Haz clic en Guardar.

curl

Para actualizar el contenido de la documentación de OpenAPI o GraphQL mediante organizations.sites.apidocs.updateDocumentation, sigue estos pasos:

OpenAPI

curl -X PATCH "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC/documentation" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{"oasDocumentation": {
           "spec":{ "displayName":"DISPLAY_NAME",
                    "contents":"CONTENTS"}
            }
        }'

Haz los cambios siguientes:

ORG_NAME con el nombre de la organización. Por ejemplo, my-org.
SITE_ID con el nombre del portal, en el formato ORG_NAME-PORTAL_NAME, donde ORG_NAME es el nombre de la organización y PORTAL_NAME es el nombre del portal convertido a minúsculas y con los espacios y los guiones eliminados. Por ejemplo, my-org-myportal.
API_DOC con la id generada del documento. Por ejemplo, 399668. Usa el comando list API docs para encontrar este valor.
DISPLAY_NAME con el nombre visible de la documentación de la API. Por ejemplo, Hello World 2.
CONTENTS con la cadena codificada en base64 del contenido de la documentación de la API. La mayoría de los entornos de desarrollo contienen una utilidad de conversión base64, o bien hay muchas herramientas de conversión online.

Carga útil de la respuesta:

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

GraphQL

curl -X PATCH "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC/documentation" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{"graphqlDocumentation": {
         "schema":{"displayName":"DISPLAY_NAME",
         "contents":"CONTENTS"},
         "endpointUri": "ENDPOINT_URI"
          }
      }'

Haz los cambios siguientes:

ORG_NAME con el nombre de la organización. Por ejemplo, my-org.
SITE_ID con el nombre del portal, en el formato ORG_NAME-PORTAL_NAME, donde ORG_NAME es el nombre de la organización y PORTAL_NAME es el nombre del portal convertido a minúsculas y con los espacios y los guiones eliminados. Por ejemplo, my-org-myportal.
API_DOC con la id generada del documento. Por ejemplo, 399668. Usa el comando list API docs para encontrar este valor.
DISPLAY_NAME con el nombre visible de la documentación de la API. Por ejemplo, Hello World 2.
ENDPOINT_URI con el nombre de dominio de tu URI de endpoint. Por ejemplo, https://demo.google.com/graphql.
CONTENTS con la cadena codificada en base64 del contenido de la documentación de la API. La mayoría de los entornos de desarrollo contienen una utilidad de conversión base64, o bien hay muchas herramientas de conversión online.

Carga útil de la respuesta:

{
 "status":"success",
 "message":"Api documentation updated",
 "requestId":"645138278"
  "data": {
    "graphqlDocumentation": {
      "schema": {
        "displayName": "Hello World 2"
      },
     "endpointUri": "https://demo.google.com/graphql"
    }
  }
}

La documentación de referencia de la API se genera a partir del documento y se añade a la página de APIs del portal activo.

Descargar documentación de la API

Una vez que hayas publicado tu API, podrás descargar en cualquier momento la documentación de referencia de OpenAPI o GraphQL que se haya publicado en tu portal.

Para descargar la documentación de la API con organizations.sites.apidocs.getDocumentation, sigue estos pasos:

curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC/documentation" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)"

Haz los cambios siguientes:

ORG_NAME con el nombre de la organización. Por ejemplo, my-org.
SITE_ID con el nombre del portal, en el formato ORG_NAME-PORTAL_NAME, donde ORG_NAME es el nombre de la organización y PORTAL_NAME es el nombre del portal convertido a minúsculas y con los espacios y los guiones eliminados. Por ejemplo, my-org-myportal.
API_DOC con la id generada del documento. Por ejemplo, 399668. Usa el comando list API docs para encontrar este valor.

Carga útil de la respuesta:

{
  "status":"success",
  "message":"Api documentation downloaded",
  "requestId":"645138256",
  "data": {
      "oasDocumentation":{
          "spec":{
            "displayName":"Hello World 2",
            "contents":"c3dhZ2dlcjogJzIuMCcKaW5mbzoKICBkZXNlI ..."
          },
          "Format": YAML
      }
  }
}

Donde:

contents: Cadena codificada en base64 del contenido de la documentación de la API.

Eliminar documentación de la API

Para quitar la documentación de la API, sigue estos pasos:

Consola

Acceder al catálogo de APIs.
Haga clic en la pestaña APIs, si aún no lo ha hecho.
Haz clic en la fila de la API que quieras editar.
Haz clic en Editar.
Para consultar la documentación de la API, seleccione No documentation (Sin documentación).
Haz clic en Guardar.

curl

Para eliminar el contenido de un documento de API mediante una API, borra la configuración actual enviando un cuerpo de solicitud vacío.

Para enviar un cuerpo de solicitud vacío y borrar el contenido actual con organizations.sites.apidocs.updateDocumentation, sigue estos pasos:

curl -X PATCH "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC/documentation" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{}'

Haz los cambios siguientes:

ORG_NAME con el nombre de la organización. Por ejemplo, my-org.
SITE_ID con el nombre del portal, en el formato ORG_NAME-PORTAL_NAME, donde ORG_NAME es el nombre de la organización y PORTAL_NAME es el nombre del portal convertido a minúsculas y con los espacios y los guiones eliminados. Por ejemplo, my-org-myportal.
API_DOC con la id generada del documento. Por ejemplo, 399668. Usa el comando list API docs para encontrar este valor.

Carga útil de la respuesta:

{
   "status":"success",
   "message":"Api documentation updated",
   "requestId":"645138279"
}

Gestionar categorías

Etiqueta una API con categorías para que los desarrolladores de aplicaciones puedan descubrir APIs relacionadas en la página APIs del portal activo. Añade y gestiona categorías, tal como se describe en las secciones siguientes.

Ver categorías

Usa la consola o el comando curl para ver las categorías.

Consola

Ve a la página Portales.
Interfaz de usuario de Cloud Console
1. En la consola de Apigee en Cloud, ve a la página Distribución > Portales.
  
  Ir a Portales
2. Haz clic en tu portal.
Interfaz clásica
1. Seleccione Publicar > Portales y elija el portal.
Haz clic en Catálogo de APIs.
Haga clic en la pestaña Categorías. En la pestaña Categorías del catálogo de APIs se muestra la lista de categorías que se han definido para tu portal. En la página APIs puedes hacer lo siguiente:
- Ver las categorías y las APIs a las que están etiquetadas
- Añadir una categoría
- Editar una categoría
- Eliminar una categoría
- Gestionar las APIs publicadas en tu portal. Consulta Ver APIs.

curl

Para enumerar las categorías con organizations.sites.apicategories.list, sigue estos pasos:

curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apicategories" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)"

Haz los cambios siguientes:

ORG_NAME con el nombre de la organización. Por ejemplo, my-org.
SITE_ID con el nombre del portal, en el formato ORG_NAME-PORTAL_NAME, donde ORG_NAME es el nombre de la organización y PORTAL_NAME es el nombre del portal convertido a minúsculas y con los espacios y los guiones eliminados. Por ejemplo, my-org-myportal.

Carga útil de la respuesta:

{
  "data": [
    {
      "siteId": "my-org-myportal",
      "name": "Get Started",
      "id": "e0518597-ece2-4d7d-ba7c-d1793df0f8db"
    },
    {
      "siteId": "my-org-myportal",
      "name": "Test",
      "id": "61c1014c-89c9-40e6-be3c-69cca3505620"
    }
  ],
  "status": "success",
  "message": "all ApiCategory items returned",
  "requestId": "602661435"
}

Donde:

id: El ID del elemento de categoría. Por ejemplo, 61c1014c-89c9-40e6-be3c-69cca3505620.

Añadir una categoría

Para añadir una categoría:

Consola

Accede a la página Categorías.
Añade una categoría.
Interfaz de usuario de Cloud Console
1. Haz clic en + Categoría.
2. Escribe el nombre de la nueva categoría.
3. Opcionalmente, selecciona una o varias APIs para etiquetarlas en la categoría.
4. Haz clic en Añadir.
Interfaz clásica
1. Haz clic en Añadir.
2. Escribe el nombre de la nueva categoría.
3. Opcionalmente, selecciona una o varias APIs para etiquetarlas en la categoría.
4. Haz clic en Crear.

curl

Para añadir una categoría con organizations.sites.apicategories.create, sigue estos pasos:

curl  -X POST "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apicategories" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{"name": "CATEGORY_NAME" }'

Haz los cambios siguientes:

ORG_NAME con el nombre de la organización. Por ejemplo, my-org.
SITE_ID con el nombre del portal, en el formato ORG_NAME-PORTAL_NAME, donde ORG_NAME es el nombre de la organización y PORTAL_NAME es el nombre del portal convertido a minúsculas y con los espacios y los guiones eliminados. Por ejemplo, my-org-myportal.
CATEGORY_NAME con el nombre de la categoría. Por ejemplo, demo-backend.

Carga útil de la respuesta:

{
  "data": {
    "siteId": "my-org-myportal",
    "name": "demo-backend",
    "id": "ed0b6c1d-eb49-419f-8475-9a428ed5b8d1"
  },
  "status": "success",
  "message": "API category created",
  "requestId": "295617049"
}

Editar una categoría

Para editar una categoría, sigue estos pasos:

Consola

Accede a la página Categorías.
Edita una categoría.
Interfaz de usuario de Cloud Console
1. En la fila de la categoría que quieras editar, haz clic en Más > Editar.
2. Edita el nombre de la categoría.
3. Añade o elimina etiquetas de API.
4. Haz clic en Añadir.
Interfaz clásica
1. Accede a la página Categorías.
2. Coloca el cursor sobre la categoría que quieras editar para que se muestre el menú de acciones.
3. Haz clic en Editar.
4. Edita el nombre de la categoría.
5. Añade o elimina etiquetas de API.
6. Haz clic en Guardar.

curl

Para editar una categoría con organizations.sites.apicategories.patch, sigue estos pasos:

curl -X PATCH "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apicategories/CATEGORY_ID"  \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{"name": "CATEGORY_NAME" }'

Haz los cambios siguientes:

ORG_NAME con el nombre de la organización. Por ejemplo, my-org.
SITE_ID con el nombre del portal, en el formato ORG_NAME-PORTAL_NAME, donde ORG_NAME es el nombre de la organización y PORTAL_NAME es el nombre del portal convertido a minúsculas y con los espacios y los guiones eliminados. Por ejemplo, my-org-myportal.
CATEGORY_ID con el ID de la categoría. Por ejemplo, bf6505eb-2a0f-47af-a00a-ded40ac72960. Obtén el ID de la categoría con el comando list API categories.
CATEGORY_NAME con el nombre de la categoría. Por ejemplo, demo-backend.

Carga útil de la respuesta:

{
  "data": {
    "siteId": "my-org-myportal",
    "name": "demo-backend-test",
    "id": "ed0b6c1d-eb49-419f-8475-9a428ed5b8d1"
  },
  "status": "success",
  "message": "ApiCategory updated",
  "requestId": "192211979"
}

Eliminar una categoría

Cuando eliminas una categoría, también se eliminan todas las etiquetas de API de esa categoría.

Para eliminar una categoría, sigue estos pasos:

Consola

Accede a la página Categorías.
Eliminar una categoría.
Interfaz de usuario de Cloud Console
En la fila de la categoría que quieras editar, haz clic en Más > Eliminar.
Interfaz clásica
1. Coloca el cursor sobre la categoría que quieras eliminar para que se muestre el menú de acciones.
2. Haz clic en Eliminar.
Haz clic en Eliminar para confirmar la acción.

curl

Para eliminar una categoría con organizations.sites.apicategories.delete, sigue estos pasos:

curl -X DELETE "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apicategories/CATEGORY_ID" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json"

Haz los cambios siguientes:

ORG_NAME con el nombre de la organización. Por ejemplo, my-org.
SITE_ID con el nombre del portal, en el formato ORG_NAME-PORTAL_NAME, donde ORG_NAME es el nombre de la organización y PORTAL_NAME es el nombre del portal convertido a minúsculas y con los espacios y los guiones eliminados. Por ejemplo, my-org-myportal.
CATEGORY_ID con el ID de la categoría. Por ejemplo, bf6505eb-2a0f-47af-a00a-ded40ac72960. Obtén el ID de la categoría con el comando list API categories.

Carga útil de la respuesta:

{
  "status": "success",
  "message": "ApiCategory deleted",
  "requestId": "1610396471"
}

Solucionar problemas con las APIs publicadas

En las siguientes secciones se proporciona información para ayudarte a solucionar errores específicos con nuestras APIs publicadas.

Error: no se ha podido obtener el error devuelto al usar la API Try this

Cuando se usa Probar esta API, si se devuelve el error TypeError: Failed to fetch, tenga en cuenta las siguientes posibles causas y soluciones:

En el caso de los errores de contenido mixto, el problema puede deberse a un problema conocido de swagger-ui. Una posible solución alternativa es especificar HTTPS antes de HTTP en la definición schemes de tu documento OpenAPI. Por ejemplo:
```
schemes:
   - https
   - http
```
Si se producen errores de restricción de uso compartido de recursos entre dominios (CORS), asegúrese de que CORS sea compatible con sus proxies de API. CORS es un mecanismo estándar que permite enviar solicitudes entre orígenes desde el lado del cliente. Consulta Configurar un proxy de API para que sea compatible con el panel Probar esta API.

Error: Request header field not allowed (Campo de encabezado de solicitud no permitido)

Cuando uses Probar esta API, si recibes un error Request header field not allowed similar al del ejemplo siguiente, puede que tengas que actualizar los encabezados admitidos en la política CORS. Por ejemplo:

field content-type is not allowed by Access-Control-Allow-Headers in preflight
response

En este ejemplo, debe añadir el encabezado content-type a la sección Access-Control-Allow-Headers de su política AssignMessage de CORS, tal como se describe en Asociar una política de CORS a un nuevo proxy de API.

Error: acceso denegado al llamar a un proxy de API mediante OAuth 2.0

La política OAuthV2 de la consola de Google Cloud devuelve una respuesta de token que contiene determinadas propiedades que no cumplen el RFC. Por ejemplo, la política devolverá un token con el valor BearerToken en lugar del valor Bearer, que cumple el RFC. Esta respuesta token_type no válida puede provocar un error Access denied al usar la opción Probar esta API.

Para corregir este problema, puede crear una política de JavaScript o AssignMessage para transformar el resultado de la política en un formato conforme. Para obtener más información, consulta el artículo sobre el comportamiento no conforme a RFC.

Publicar APIs Organízate con las colecciones Guarda y clasifica el contenido según tus preferencias.

Descripción general de la publicación de APIs

¿Qué se publica en el portal?

SmartDocs (OpenAPI)

Explorador de GraphQL

Acerca de la documentación de la API

Acerca de las URLs de retrollamada

Configurar el proxy de API para que admita el panel Probar esta API

Gestiona APIs

Ver APIs

Consola

Interfaz de usuario de Cloud Console

Interfaz clásica

curl

Añadir una API

Consola

Interfaz de usuario de Cloud Console

Interfaz clásica

Interfaz de usuario de Cloud Console

Interfaz clásica

Interfaz de usuario de Cloud Console

Interfaz clásica

curl

Editar una API

Consola

curl

Publicar o dejar de publicar una API

Consola

curl

Gestionar la visibilidad de una API

Consola

curl

Gestionar la URL de retrollamada de una API

Consola

curl

Gestionar la imagen de una tarjeta de API

Consola

Interfaz de usuario de Cloud Console

Interfaz clásica

curl

Etiquetar una API con categorías

Consola

Interfaz de usuario de Cloud Console

Interfaz clásica

curl

Editar el título y la descripción

Consola

curl

Eliminar una API

Consola

Interfaz de usuario de Cloud Console

Interfaz clásica

curl

Gestionar la documentación de la API

Actualizar la documentación de la API

Consola

Interfaz de usuario de Cloud Console

Interfaz clásica

curl

OpenAPI

GraphQL

Descargar documentación de la API

Eliminar documentación de la API

Consola

curl

Gestionar categorías

Ver categorías

Consola

Interfaz de usuario de Cloud Console

Interfaz clásica

curl

Añadir una categoría

Consola

Interfaz de usuario de Cloud Console

Interfaz clásica

curl

Editar una categoría

Consola

Interfaz de usuario de Cloud Console

Interfaz clásica

Publicar APIs