Esta página foi traduzida pela API Cloud Translation.

Publicar as suas APIs

Esta página aplica-se ao Apigee e ao Apigee Hybrid.

Veja a documentação do Apigee Edge.

Publique APIs no seu portal para as disponibilizar para consumo por parte dos programadores de apps, conforme descrito nas secções seguintes.

Vista geral da publicação de APIs

O processo de publicação de APIs no seu portal é um processo de dois passos:

Selecione o produto API que quer publicar no seu portal.
Renderize a documentação de referência da API a partir do seu documento OpenAPI ou esquema GraphQL para permitir que os programadores de apps saibam mais sobre as suas APIs. (Para mais informações, consulte o artigo Acerca da documentação da API)

O que é publicado no portal?

Quando publica uma API, as seguintes atualizações são feitas automaticamente no seu portal:

Documentação de referência da API. A interface fornecida depende de se publica a sua API através de um documento OpenAPI ou de um esquema GraphQL. Veja:
- SmartDocs (OpenAPI)
- GraphQL Explorer
É adicionado um link para a página de referência da API à página APIs
A página APIs (incluída no portal de exemplo) apresenta uma lista de todas as APIs publicadas no seu portal, apresentadas por ordem alfabética, com links para a documentação de referência da API respetiva para mais informações. Opcionalmente, pode personalizar o seguinte:
- Imagem apresentada para cada cartão da API
- Categorias usadas para etiquetar APIs para permitir que os programadores descubram APIs relacionadas na página de APIs
Nota: não pode editar o conteúdo desta página diretamente. Esta não é apresentada na lista de páginas no seu portal. Pode editar o estilo da página quando personaliza o tema.

SmartDocs (OpenAPI)

Quando publica uma API através de um documento OpenAPI, a documentação de referência da API SmartDocs é adicionada ao seu portal.

Os programadores podem rever a documentação de referência da API SmartDocs e usar o painel Experimentar esta API para fazer um pedido de API e ver o resultado. A opção Experimentar esta API funciona com pontos finais não seguros ou pontos finais seguros através da autenticação básica, da chave de API ou do OAuth, com base no método de segurança definido no seu documento OpenAPI. Para o OAuth, são suportados os seguintes fluxos: código de autorização, palavra-passe e credenciais do cliente.

Página de documentação de referência da API com indicações que mostram como autorizar a chamada API, desancorar o painel Experimentar esta API, transferir a especificação relevante e executar a API.

Clique em Ecrã inteiro para expandir o painel Experimentar esta API. O painel expandido permite-lhe ver os curl exemplos de chamadas e código em vários formatos, como HTTP, Python, Node.js e muito mais, conforme mostrado abaixo.

GraphQL Explorer

Quando publica uma API através de um esquema GraphQL, o explorador GraphQL é adicionado ao seu portal. O GraphQL Explorer é um ambiente de testes interativo para executar consultas na sua API. O explorador baseia-se no GraphiQL, uma implementação de referência do IDE GraphQL desenvolvida pela GraphQL Foundation.

Os programadores podem usar o GraphQL Explorer para explorar a documentação interativa baseada em esquemas, criar e executar consultas, ver os resultados das consultas e transferir o esquema. Para proteger o acesso à sua API, os programadores podem transmitir cabeçalhos de autorização no painel Cabeçalhos de pedido. Para mais informações sobre o GraphQL, consulte graphql.org.

Explorador de GraphQL no portal

Acerca da documentação da API

Cada documento OpenAPI ou GraphQL serve como fonte de informações fidedignas ao longo do ciclo de vida de uma API. O mesmo documento é usado em cada fase do ciclo de vida da API, desde o desenvolvimento à publicação e à monitorização. Quando modifica um documento, tem de estar atento ao impacto que as alterações têm na sua API através de outras fases do ciclo de vida, conforme descrito em O que acontece se modificar um documento?

Quando publica a sua API num portal, guarda uma versão do documento OpenAPI ou GraphQL para renderizar a documentação de referência da API. Se modificar o documento, pode decidir atualizar a documentação de referência da API publicada no portal para refletir as alterações mais recentes.

Acerca dos URLs de retorno

Se as suas apps exigirem um URL de retorno de chamada, como quando usam o tipo de concessão de código de autorização OAuth 2.0 (frequentemente denominado OAuth de três partes), pode exigir que os programadores especifiquem um URL de retorno de chamada quando registam as respetivas apps. Normalmente, o URL de chamada de retorno especifica o URL de uma app designada para receber um código de autorização em nome da app cliente. Para mais informações, consulte o artigo Implementar o tipo de concessão de código de autorização.

Pode configurar se é necessário ou não um URL de retorno de chamada durante o registo da app quando adiciona uma API ao seu portal. Pode modificar esta definição em qualquer altura, conforme descrito em Gerir o URL de retorno de chamada para uma API.

Ao registar uma app, os programadores têm de introduzir um URL de retorno de chamada para todas as APIs que o exijam, conforme descrito no artigo Registar apps.

Configure o proxy de API para suportar o painel Experimentar esta API

Antes de publicar as suas APIs através de um documento OpenAPI, tem de configurar o proxy de API para suportar a realização de pedidos no painel Experimentar esta API na documentação de referência da API SmartDocs, da seguinte forma:

Adicione compatibilidade com CORS aos seus proxies de API para aplicar pedidos de origem cruzada do lado do cliente.
O CORS é um mecanismo padrão que permite que as chamadas JavaScript XMLHttpRequest (XHR) executadas numa página Web interajam com recursos de domínios não originais. A CORS é uma solução implementada frequentemente para a política de mesma origem aplicada por todos os navegadores.
Atualize a configuração do proxy de API se estiver a usar a autenticação básica ou o OAuth 2.0.

A tabela seguinte resume os requisitos de configuração do proxy de API para suportar o painel Experimentar esta API na documentação de referência da API SmartDocs com base no acesso de autenticação.

Acesso de autorização	Requisitos de configuração da política
Nenhuma ou chave da API	Adicione suporte para CORS ao seu proxy de API. Siga os passos descritos no artigo Adicionar suporte para CORS a um proxy de API.
Autenticação básica	Siga estes passos: Adicione suporte para CORS ao seu proxy de API. Siga os passos descritos no artigo Adicionar suporte para CORS a um proxy de API. Na política de CORS adicionada, certifique-se de que o cabeçalho `Access-Control-Allow-Headers` inclui o atributo `authorization`. Por exemplo: `<Header name="Access-Control-Allow-Headers"> origin, x-requested-with, accept, content-type, authorization </Header>`
OAuth 2.0	Adicione suporte para CORS ao seu proxy de API. Siga os passos descritos no artigo Adicionar suporte para CORS a um proxy de API. Na política de CORS adicionada, certifique-se de que o cabeçalho `Access-Control-Allow-Headers` inclui o atributo `authorization`. Por exemplo: `<Header name="Access-Control-Allow-Headers"> origin, x-requested-with, accept, content-type, authorization </Header>` Corrija o comportamento não compatível com a RFC na sua Política de OAuth 2.0. Para maior comodidade, use a solução de OAuth 2.0 de exemplo disponibilizada no GitHub ou siga os passos seguintes: Certifique-se de que o elemento `<GrantType>` na política OAuth 2.0 está definido como `request.formparam.grant_type` (parâmetro de formulário). Para mais informações, consulte <GrantType>. Certifique-se de que o `token_type` na política de OAuth 2.0 está definido como `Bearer` e não como `BearerToken`, que é a predefinição.

Faça a gestão das APIs

Faça a gestão das suas APIs conforme descrito nas secções seguintes.

Explore APIs

Use a consola ou o comando curl para ver as APIs que estão no seu portal.

Para ver o catálogo de APIs:

Consola

IU da Cloud Console

Na consola do Apigee in Cloud, aceda à página Distribuição > Portais.

Aceda a Portais
Clique no portal.
Clique em Catálogo de APIs.
Clique no separador APIs. É apresentada uma lista das APIs que foram adicionadas ao seu portal.

IU clássica

Selecione Publicar > Portais e selecione o seu portal.
Clique em Catálogo de APIs na página inicial do portal.
Em alternativa, pode selecionar Catálogo de APIs no menu pendente do portal no menu de navegação superior.
O separador APIs no catálogo de APIs apresenta uma lista das APIs que foram adicionadas ao seu portal.

O separador APIs permite-lhe:

Veja os detalhes das APIs disponíveis no seu portal
Adicione uma API ao seu portal
Edite uma API no seu portal realizando uma ou mais das seguintes tarefas:
Remova uma API do seu portal
Faça a gestão das categorias
Identifique rapidamente APIs órfãs cujo produto API associado foi removido da Google Cloud Console e recrie o produto API ou elimine a API do seu portal

curl

Para listar APIs através de organizations.sites.apidocs/list:

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

Substitua o seguinte:

ORG_NAME com o nome da organização. Por exemplo, my-org.
SITE_ID com o nome do portal, no formato ORG_NAME-PORTAL_NAME, onde ORG_NAME é o nome da organização e PORTAL_NAME é o nome do portal convertido para tudo em minúsculas e com espaços e travessões removidos. Por exemplo, my-org-myportal.

Consulte as Notas de paginação para obter instruções sobre como usar a paginação no payload de resposta.

Payload de resposta:

{
  "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": ""
}

Onde:

modified: Hora em que o item do catálogo foi modificado pela última vez em milissegundos desde a época. Por exemplo, 1698165480000.
id: O ID do artigo do catálogo. Por exemplo, 399668.

Notas de paginação:

Tamanho da página: use pageSize para especificar o número de itens da lista a devolver numa página. A predefinição é 25 e o máximo é 100. Se existirem páginas adicionais, nextPageToken é preenchido com um 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)"

Substituição:

PAGE_SIZE com o número de itens da lista a devolver numa página. Por exemplo, 10.

Payload de resposta:

{
  "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"
}

Símbolo de página:

Use pageToken para obter páginas subsequentes quando houver mais do que uma:
```
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)"
```
Substituição:
- PAGE_SIZE com o número de itens da lista a devolver numa página. Por exemplo, 10.
- PAGE_TOKEN com o valor nextPageToken. Por exemplo, 7zcqrin9l6xhi4nbrb9.

Adicione uma API

Para adicionar uma API ao seu portal:

Consola

Aceda ao catálogo de APIs.
Clique no separador APIs, se ainda não estiver selecionado.
Adicione uma API.
IU da Cloud Console
1. Clique em + API. É apresentada a caixa de diálogo Adicionar uma API.
2. Selecione o produto API que quer adicionar ao seu portal.
IU clássica
1. Clique em Adicionar.
  
  É apresentada a caixa de diálogo Adicionar um produto de API ao catálogo.
2. Selecione o produto API que quer adicionar ao seu portal.
3. Clicar em Seguinte. É apresentada a página Detalhes da API.

Configure o conteúdo da documentação de referência da API e a respetiva visibilidade no portal:

Campo	Descrição
Publicado	Selecione Publicado para publicar a API no seu portal. Desmarque a caixa de verificação se não tiver tudo pronto para publicar a API. Pode alterar a definição mais tarde, conforme descrito no artigo Publicar ou anular a publicação de uma API.
Título de apresentação	Atualize o título da sua API apresentado no catálogo. Por predefinição, é usado o nome do produto API. Pode alterar o título de apresentação mais tarde, conforme descrito no artigo Edite o título de apresentação e a descrição.
Descrição do anúncio de display	Atualize a descrição da sua API apresentada no catálogo. Por predefinição, é usada a descrição do produto da API. Pode alterar a descrição de apresentação mais tarde, conforme descrito no artigo Edite o título e a descrição de apresentação.
Exija que os programadores especifiquem um URL de retorno	Ative esta opção se quiser exigir que os programadores de apps especifiquem um URL de retorno. Pode adicionar ou atualizar o URL de retorno mais tarde, conforme descrito em Gerir o URL de retorno de uma API.
Documentação da API	Para usar um documento OpenAPI: IU da Cloud Console Selecione Documento OpenAPI. Clique em Selecionar. Realize um dos seguintes passos: Clique no separador Carregar e carregue um ficheiro. Clique no separador URL e importe uma especificação indicando um nome e um URL a partir dos quais importar. Clique em Selecionar. IU clássica Selecione Documento OpenAPI. Clique em Selecionar documento. Realize um dos seguintes passos: Clique no separador Carregar ficheiro e carregue um ficheiro. Clique no separador Importar de um URL e importe uma especificação indicando um nome e um URL a partir dos quais importar. Clique em Selecionar. Para usar um esquema GraphQL: IU da Cloud Console Selecione Esquema GraphQL. Clique em Selecionar. Navegue para o esquema GraphQL e selecione-o. Especifique o URL do ponto final, que é o URI do ponto final GraphQL a ser consultado pelos consumidores da API. Clique em Selecionar. IU clássica Selecione Esquema GraphQL. Clique em Selecionar documento. Navegue para o esquema GraphQL e selecione-o. Clique em Abrir. Especifique o URL do ponto final, que é o URI do ponto final GraphQL a ser consultado pelos consumidores da API. Clique em Guardar. Em alternativa, pode selecionar Sem documentação e adicionar uma mais tarde, depois de adicionar a API, conforme descrito no artigo Faça a gestão da documentação da API. Nota: quando importa um documento OpenAPI através de um URL, os redirecionamentos não são seguidos.
Visibilidade	Se não tiver inscrito na versão de pré-visualização da funcionalidade de gestão de públicos-alvo, selecione uma das seguintes opções: Utilizadores anónimos para permitir que todos os utilizadores vejam a API. Utilizadores registados para permitir que apenas os utilizadores registados vejam a API. Se tiver inscrito na versão de pré-visualização da funcionalidade de gestão de públicos-alvo, selecione uma das seguintes opções: Público (visível para qualquer pessoa) para permitir que todos os utilizadores vejam a API. Utilizadores autenticados para permitir que apenas os utilizadores registados vejam a API. Públicos-alvo selecionados para selecionar os públicos-alvo específicos que quer poder ver na API. Pode gerir a visibilidade do público-alvo mais tarde, conforme descrito em Gerir a visibilidade de uma API.
Imagem de apresentação	Para apresentar uma imagem no cartão da API na página APIs, clique em Selecionar imagem. Na caixa de diálogo Selecionar imagem, selecione uma imagem existente, carregue uma nova imagem ou indique o URL de uma imagem externa e clique em Selecionar. Pré-visualize a miniatura da API e clique em Selecionar. Pode adicionar uma imagem mais tarde, conforme descrito em Gerir a imagem de um cartão de API. Quando especifica o URL de uma imagem externa, a imagem não é carregada para os seus recursos. Além disso, o carregamento da imagem no portal integrado está sujeito à respetiva disponibilidade, que pode ser bloqueada ou restrita por políticas de segurança de conteúdo.
Categorias	Adicione as categorias com as quais a API vai ser etiquetada para permitir que os programadores de apps descubram APIs relacionadas na página de APIs. Para identificar uma categoria: Selecione uma categoria na lista pendente. Adicione uma nova categoria, conforme descrito em Adicione uma categoria. A nova categoria é adicionada à página Categorias e fica disponível quando adiciona ou edita outras APIs.

Clique em Guardar.

curl

Para adicionar uma API ao seu portal através de organizations.sites.apidocs.create:

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",
         }'

Substitua o seguinte:

ORG_NAME com o nome da organização. Por exemplo, my-org.
SITE_ID com o nome do portal, no formato ORG_NAME-PORTAL_NAME, onde ORG_NAME é o nome da organização e PORTAL_NAME é o nome do portal convertido para tudo em minúsculas e com espaços e travessões removidos. Por exemplo, my-org-myportal.
TITLE com o título de apresentação. Por exemplo, Hello World 2.
DESCRIPTION com a descrição do ecrã. Por exemplo, Simple hello world example.
ANON_TRUE_OR_FALSE com true ou false (predefinição), em que true ativa o acesso de utilizadores anónimos. Esta definição é ignorada se tiver inscrito na versão de pré-visualização da funcionalidade de gestão de públicos-alvo.
IMAGE_URL com o URL de uma imagem externa usada para o item do catálogo ou um caminho de ficheiro para ficheiros de imagem armazenados no portal, por exemplo, /files/book-tree.jpg. Quando especifica o URL de uma imagem externa, a imagem não é carregada para os seus recursos. Além disso,o carregamento da imagem no portal integrado está sujeito à respetiva disponibilidade, que pode ser bloqueada ou restrita por políticas de segurança de conteúdo.
CALLBACK_TRUE_OR_FALSE com true ou false (predefinição), em que true requer que um utilizador do portal introduza um URL ao gerir a app.
CATEGORY_ID com o ID da categoria. Por exemplo, bf6505eb-2a0f-47af-a00a-ded40ac72960. Separe vários IDs de categorias com uma vírgula. Obtenha o ID da categoria com o comando list API categories.

Nota: já tem de ter categorias definidas para as adicionar aqui. Consulte os artigos Adicione uma categoria e Explore as categorias para ver instruções.
PUBLISHED_TRUE_OR_FALSE com true ou false (predefinição), onde true indica que a API está disponível publicamente.
API_PRODUCT com o nome do produto API. Por exemplo, Hello World 2.

Payload de resposta:

{
  "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"
  }
}

Onde:

modified: Hora em que o item do catálogo foi modificado pela última vez em milissegundos desde a época. Por exemplo, 1698165480000.
id: O ID do artigo do catálogo. Por exemplo, 399668.

Edite uma API

Depois de adicionar uma API, use a consola ou uma chamada API para fazer edições.

Esta secção fornece um exemplo detalhado dos passos a seguir para modificar uma API existente no seu portal.

Consulte as secções seguintes para ver definições de modificação específicas.

Consola

Aceda ao catálogo de APIs.
Clique no separador APIs, se ainda não estiver selecionado.
Clique na linha da API que quer editar.
Clique em Editar.
Faça as modificações pretendidas. Veja as descrições das opções em Adicionar uma API.
Clique em Guardar.

curl

Depois de adicionar uma API, use a chamada organizations.sites.apidocs.update para fazer edições.

Este exemplo explica os passos necessários para alterar o estado de publicação da sua API no portal de true para false. Pode alterar mais do que uma definição numa chamada API, se necessário.

Obtenha uma lista das APIs no seu portal usando organizations.sites.apidocs/list para localizar o idgerado que identifica exclusivamente 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)"

Substitua o seguinte:

ORG_NAME com o nome da organização. Por exemplo, my-org.
SITE_ID com o nome do portal, no formato ORG_NAME-PORTAL_NAME, onde ORG_NAME é o nome da organização e PORTAL_NAME é o nome do portal convertido para tudo em minúsculas e com espaços e travessões removidos. Por exemplo, my-org-myportal.

Payload de resposta:

{
  "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"
    }
  ]
}

Onde:

modified: Hora em que o item do catálogo foi modificado pela última vez em milissegundos desde a época. Por exemplo, 1698165480000.
id: O ID do artigo do catálogo. Por exemplo, 399668.

Use a chamada organizations.sites.apidocs.get para devolver os valores atuais de uma 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)"

Substitua o seguinte:

ORG_NAME com o nome da organização. Por exemplo, my-org.
SITE_ID com o nome do portal, no formato ORG_NAME-PORTAL_NAME, onde ORG_NAME é o nome da organização e PORTAL_NAME é o nome do portal convertido para tudo em minúsculas e com espaços e travessões removidos. Por exemplo, my-org-myportal.
API_DOC com o id gerado do documento. Por exemplo, 399668. Use o comando list API docs para encontrar este valor.

Payload de resposta:

{
  "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"
  }
}

Inclua os valores mutáveis que quer manter na chamada organizations.sites.apidocs.update e modifique os valores que quer alterar. Se omitir uma linha, é usada a predefinição. Para este exemplo, altere a definição published de true para 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",
     }'
```
Substitua o seguinte:
- TITLE com o título de apresentação. Por exemplo, Hello World 2.
- DESCRIPTION com a descrição do ecrã. Por exemplo, Simple hello world example.
- ANON_TRUE_OR_FALSE com true ou false (predefinição), em que true ativa o acesso de utilizadores anónimos. Esta definição é ignorada se tiver inscrito na versão de pré-visualização da funcionalidade de gestão de públicos-alvo.
- IMAGE_URL com o URL de uma imagem externa usada para o item do catálogo ou um caminho de ficheiro para ficheiros de imagem armazenados no portal, por exemplo, /files/book-tree.jpg. Quando especifica o URL de uma imagem externa, a imagem não é carregada para os seus recursos. Além disso,o carregamento da imagem no portal integrado está sujeito à respetiva disponibilidade, que pode ser bloqueada ou restrita por políticas de segurança de conteúdo.
- CALLBACK_TRUE_OR_FALSE com true ou false (predefinição), em que true requer que um utilizador do portal introduza um URL ao gerir a app.
- CATEGORY_ID com o ID da categoria. Por exemplo, bf6505eb-2a0f-47af-a00a-ded40ac72960. Separe vários IDs de categorias com uma vírgula. Obtenha o ID da categoria com o comando list API categories.
- API_PRODUCT com o nome do produto API. Por exemplo, Hello World 2.
Payload de resposta:
```
{
  "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"
  }
}
```

Publique ou anule a publicação de uma API

A publicação é o processo de disponibilização das suas APIs aos programadores de apps para consumo.

Para publicar ou anular a publicação de uma API no seu portal:

Consola

Aceda ao catálogo de APIs.
Clique no separador APIs, se ainda não estiver selecionado.
Clique na linha da API que quer editar.
Clique em Editar.
Selecione ou desmarque a opção Publicado (listado no catálogo) para publicar ou anular a publicação da API no seu portal, respetivamente.
Clique em Guardar.

curl

Inclua um dos seguintes elementos na chamada update:

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

Para editar a API:

Use a chamada organizations.sites.apidocs.get para devolver os valores atuais:

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)"

Use a chamada organizations.sites.apidocs.update para editar a API. Inclua os valores mutáveis que quer manter e modifique os valores que quer alterar. Se omitir uma definição mutável, é usado o valor predefinido.

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",
     }'

Consulte o artigo Edite uma API para ver um exemplo detalhado dos passos, das variáveis e da carga útil devolvida.

Faça a gestão da visibilidade de uma API

Faça a gestão da visibilidade de uma API no seu portal permitindo o acesso a:

Público (visível para qualquer pessoa)
Utilizadores autenticados
Públicos-alvo selecionados (se tiver inscrito na versão de pré-visualização da funcionalidade de gestão de públicos-alvo)

Nota: se definir a visibilidade como Utilizadores autenticados ou Públicos-alvo selecionados, a API não é indexada pelos motores de pesquisa.

Para gerir a visibilidade de uma API no seu portal:

Consola

Aceda ao catálogo de APIs.
Clique no separador APIs, se ainda não estiver selecionado.
Clique na linha da API que quer editar.
Clique em Editar.
Selecione a definição de visibilidade. Se tiver inscrito na versão de pré-visualização da funcionalidade de públicos-alvo, selecione uma das seguintes opções em Visibilidade da API:
- Público (visível para qualquer pessoa) para permitir que todos os utilizadores vejam a página.
- Utilizadores autenticados para permitir que apenas os utilizadores registados vejam a página.
- Públicos-alvo selecionados para selecionar os públicos-alvo específicos que quer poder ver a página. Consulte o artigo Gerir os públicos-alvo do seu portal.
Caso contrário, selecione uma das seguintes opções em Público-alvo:
- Utilizadores anónimos para permitir que todos os utilizadores vejam a página.
- Utilizadores registados para permitir que apenas os utilizadores registados vejam a página.
Clique em Guardar.

curl

Se tiver inscrito na versão de pré-visualização da funcionalidade de gestão de públicos-alvo, use a consola para gerir públicos-alvo.

Se não se inscreveu na funcionalidade de gestão de públicos-alvo, a visibilidade é gerida através de anonAllowed.

Inclua um dos seguintes elementos na chamada 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 a API:

Use a chamada organizations.sites.apidocs.get para devolver os valores atuais:

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",
     }'

Consulte o artigo Edite uma API para ver um exemplo detalhado dos passos, das variáveis e da carga útil devolvida.

Faça a gestão do URL de retorno de uma API

Faça a gestão do URL de retorno de uma API. Consulte o artigo Acerca dos URLs de retorno de chamada.

Para gerir o URL de retorno de uma API:

Consola

Aceda ao catálogo de APIs.
Clique no separador APIs, se ainda não estiver selecionado.
Clique na linha da API que quer editar.
Clique em Editar.
Selecione ou desmarque a opção Exigir que os programadores especifiquem um URL de retorno de chamada para especificar se um URL de retorno de chamada é obrigatório ou não, respetivamente.
Clique em Guardar.

curl

Inclua um dos seguintes elementos na chamada update:

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

Para editar a API:

Use a chamada organizations.sites.apidocs.get para devolver os valores atuais:

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",
     }'

Consulte o artigo Edite uma API para ver um exemplo detalhado dos passos, das variáveis e da carga útil devolvida.

Faça a gestão da imagem de um cartão de API

Faça a gestão da imagem que aparece com um cartão de API na página APIs adicionando ou alterando a imagem atual.

Para gerir a imagem de um cartão de API:

Consola

Aceda ao catálogo de APIs.
Clique no separador APIs, se ainda não estiver selecionado.
Clique na linha da API que quer editar.
Clique em Editar.
Localize e selecione uma imagem:
IU da Cloud Console
- Clique em Selecionar para especificar uma imagem.
- Clique em x para remover a imagem.
IU clássica
- Clique em Selecionar imagem para especificar uma imagem se não tiver sido selecionada nenhuma.
- Clique em Alterar imagem para especificar uma imagem diferente.
- Clique em x na imagem para a remover.
Quando especificar uma imagem, especifique uma imagem com um URL externo usado para o item do catálogo ou um caminho de ficheiro para ficheiros de imagem armazenados no portal, por exemplo, /files/book-tree.jpg. Quando especifica o URL de uma imagem externa, a imagem não é carregada para os seus recursos. Além disso, o carregamento da imagem no portal integrado está sujeito à respetiva disponibilidade, que pode ser bloqueada ou restrita por políticas de segurança de conteúdo.
Clique em Guardar.

curl

Inclua o seguinte na chamada update:

  # Omit line for no image file

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

Para editar a API:

Use a chamada organizations.sites.apidocs.get para devolver os valores atuais:

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",
     }'

Consulte o artigo Edite uma API para ver um exemplo detalhado dos passos, das variáveis e da carga útil devolvida.

Etiquete uma API com categorias

A utilização de categorias ajuda os programadores de apps a descobrirem APIs relacionadas. Consulte também o artigo Faça a gestão das categorias.

Para etiquetar uma API com categorias:

Consola

Aceda ao catálogo de APIs.
Clique no separador APIs, se ainda não estiver selecionado.
Clique na linha da API que quer editar.
Clique em Editar.
Especifique uma categoria.
IU da Cloud Console
1. Selecione uma ou mais categorias na lista pendente Categorias. Consulte o artigo Faça a gestão das categorias se não existirem categorias.
2. Clique em OK.
IU clássica
1. Clique no campo Categorias e execute um dos seguintes passos:
  - Selecione uma categoria na lista pendente.
  - Adicione uma nova categoria escrevendo o respetivo nome e premindo Enter. A nova categoria é adicionada à página Categorias e fica disponível quando adiciona ou edita outras APIs.
2. Repita para etiquetar a API com mais categorias.
Clique em Guardar.

curl

Inclua o seguinte na chamada update:

  # Omit line for no categories

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

Use o comando list categories para obter os números de ID das categorias.

Para editar a API:

Use a chamada organizations.sites.apidocs.get para devolver os valores atuais:

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",
     }'

Consulte o artigo Edite uma API para ver um exemplo detalhado dos passos, das variáveis e da carga útil devolvida.

Edite o título e a descrição a apresentar

Para editar o título e a descrição a apresentar:

Consola

Aceda ao catálogo de APIs.
Clique no separador APIs, se ainda não estiver selecionado.
Clique na linha da API que quer editar.
Clique em Editar.
Edite os campos Título a apresentar e Descrição a apresentar, conforme necessário.
Clique em Guardar.

curl

Inclua o seguinte na chamada update:

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

Para editar a API:

Use a chamada organizations.sites.apidocs.get para devolver os valores atuais:

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",
     }'

Consulte o artigo Edite uma API para ver um exemplo detalhado dos passos, das variáveis e da carga útil devolvida.

Remova uma API

Para remover uma API do seu portal:

Consola

Aceda ao catálogo de APIs.
Selecione o separador APIs, se ainda não estiver selecionado.
Elimine a API.
IU da Cloud Console
Clique em Mais > Eliminar.
IU clássica
1. Posicione o cursor sobre a API na lista para apresentar o menu de ações.
2. Clique em Eliminar.
Clique em Eliminar para confirmar.

curl

Para remover uma API do seu portal através do organizations.sites.apidocs.delete:

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)"

Substitua o seguinte:

ORG_NAME com o nome da organização. Por exemplo, my-org.
SITE_ID com o nome do portal, no formato ORG_NAME-PORTAL_NAME, onde ORG_NAME é o nome da organização e PORTAL_NAME é o nome do portal convertido para tudo em minúsculas e com espaços e travessões removidos. Por exemplo, my-org-myportal.
API_DOC com o id gerado do documento. Por exemplo, 399668. Use o comando list API docs para encontrar este valor.

Payload de resposta:

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

Faça a gestão da documentação da API

As secções seguintes descrevem como atualizar, transferir ou remover documentação da API.

Atualize a documentação da API

Depois de publicar a API, pode carregar uma nova versão do documento OpenAPI ou GraphQL em qualquer altura.

Para carregar uma versão diferente da documentação da API:

Consola

Aceda ao catálogo de APIs.
Clique no separador APIs, se ainda não estiver selecionado.
Clique na linha da API que quer editar.
Clique em Editar.
Para aceder à documentação da API, selecione uma das seguintes opções:
- Documento OpenAPI
- Esquema GraphQL
Localize o ficheiro.
IU da Cloud Console
1. Clique em Selecionar.
2. Procure e selecione o ficheiro.
IU clássica
1. Clique em Selecionar documento e selecione a versão mais recente do documento.
Para o GraphQL, especifique o URL do ponto final.
Clique em Selecionar.
Clique em Guardar.

curl

Para atualizar o conteúdo da documentação OpenAPI ou GraphQL através do organizations.sites.apidocs.updateDocumentation:

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"}
            }
        }'

Substitua o seguinte:

ORG_NAME com o nome da organização. Por exemplo, my-org.
SITE_ID com o nome do portal, no formato ORG_NAME-PORTAL_NAME, onde ORG_NAME é o nome da organização e PORTAL_NAME é o nome do portal convertido para tudo em minúsculas e com espaços e travessões removidos. Por exemplo, my-org-myportal.
API_DOC com o id gerado do documento. Por exemplo, 399668. Use o comando list API docs para encontrar este valor.
DISPLAY_NAME com o nome a apresentar da documentação da API. Por exemplo, Hello World 2.
CONTENTS com a string codificada em base64 do conteúdo da documentação da API. A maioria dos ambientes de desenvolvimento contém uma utilidade de conversão base64 ou existem muitas ferramentas de conversão online.

Payload de resposta:

{
 "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"
          }
      }'

Substitua o seguinte:

ORG_NAME com o nome da organização. Por exemplo, my-org.
SITE_ID com o nome do portal, no formato ORG_NAME-PORTAL_NAME, onde ORG_NAME é o nome da organização e PORTAL_NAME é o nome do portal convertido para tudo em minúsculas e com espaços e travessões removidos. Por exemplo, my-org-myportal.
API_DOC com o id gerado do documento. Por exemplo, 399668. Use o comando list API docs para encontrar este valor.
DISPLAY_NAME com o nome a apresentar da documentação da API. Por exemplo, Hello World 2.
ENDPOINT_URI com o nome do domínio do URI do seu ponto final. Por exemplo, https://demo.google.com/graphql.
CONTENTS com a string codificada em base64 do conteúdo da documentação da API. A maioria dos ambientes de desenvolvimento contém uma utilidade de conversão base64 ou existem muitas ferramentas de conversão online.

Payload de resposta:

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

A documentação de referência da API é renderizada a partir do documento e adicionada à página APIs do portal em direto.

Transfira a documentação da API

Depois de publicar a API, pode transferir em qualquer altura a documentação de referência OpenAPI ou GraphQL publicada no seu portal.

Para transferir a documentação da API através do organizations.sites.apidocs.getDocumentation:

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)"

Substitua o seguinte:

ORG_NAME com o nome da organização. Por exemplo, my-org.
SITE_ID com o nome do portal, no formato ORG_NAME-PORTAL_NAME, onde ORG_NAME é o nome da organização e PORTAL_NAME é o nome do portal convertido para tudo em minúsculas e com espaços e travessões removidos. Por exemplo, my-org-myportal.
API_DOC com o id gerado do documento. Por exemplo, 399668. Use o comando list API docs para encontrar este valor.

Payload de resposta:

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

Onde:

contents: A string codificada em base64 do conteúdo da documentação da API.

Remova a documentação da API

Para remover a documentação da API:

Consola

Aceda ao catálogo de APIs.
Clique no separador APIs, se ainda não estiver selecionado.
Clique na linha da API que quer editar.
Clique em Editar.
Para documentação da API, selecione Sem documentação.
Clique em Guardar.

curl

Para remover o conteúdo de documentos da API através de uma API, limpe as definições existentes enviando um corpo do pedido vazio.

Para enviar um corpo do pedido vazio e limpar o conteúdo existente através de organizations.sites.apidocs.updateDocumentation:

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 '{}'

Substitua o seguinte:

ORG_NAME com o nome da organização. Por exemplo, my-org.
SITE_ID com o nome do portal, no formato ORG_NAME-PORTAL_NAME, onde ORG_NAME é o nome da organização e PORTAL_NAME é o nome do portal convertido para tudo em minúsculas e com espaços e travessões removidos. Por exemplo, my-org-myportal.
API_DOC com o id gerado do documento. Por exemplo, 399668. Use o comando list API docs para encontrar este valor.

Payload de resposta:

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

Faça a gestão de categorias

Etiquete uma API com categorias para permitir que os programadores de apps descubram APIs relacionadas na página APIs do portal em direto. Adicione e faça a gestão de categorias, conforme descrito nas secções seguintes.

Explore as categorias

Use a consola ou o comando curl para ver as categorias.

Consola

Aceda à página Portais.
IU da Cloud Console
1. Na consola do Apigee in Cloud, aceda à página Distribuição > Portais.
  
  Aceda a Portais
2. Clique no portal.
IU clássica
1. Selecione Publicar > Portais e selecione o seu portal.
Clique em Catálogo de APIs.
Clique no separador Categorias. O separador Categorias no catálogo de APIs apresenta a lista das categorias que foram definidas para o seu portal A página APIs permite-lhe
- Veja as categorias e as APIs às quais estão etiquetadas
- Adicione uma categoria
- Edite uma categoria
- Elimine uma categoria
- Faça a gestão das APIs publicadas no seu portal. Consulte o artigo Explore APIs.

curl

Para listar categorias através de organizations.sites.apicategories.list:

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

Substitua o seguinte:

ORG_NAME com o nome da organização. Por exemplo, my-org.
SITE_ID com o nome do portal, no formato ORG_NAME-PORTAL_NAME, onde ORG_NAME é o nome da organização e PORTAL_NAME é o nome do portal convertido para tudo em minúsculas e com espaços e travessões removidos. Por exemplo, my-org-myportal.

Payload de resposta:

{
  "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"
}

Onde:

id: O ID do artigo da categoria. Por exemplo, 61c1014c-89c9-40e6-be3c-69cca3505620.

Adicione uma categoria

Para adicionar uma categoria:

Consola

Aceda à página Categorias.
Adicione uma categoria.
IU da Cloud Console
1. Clique em + Categoria.
2. Introduza o nome da nova categoria.
3. Opcionalmente, selecione uma ou mais APIs para etiquetar na categoria.
4. Clique em Adicionar.
IU clássica
1. Clique em Adicionar.
2. Introduza o nome da nova categoria.
3. Opcionalmente, selecione uma ou mais APIs para etiquetar na categoria.
4. Clique em Criar.

curl

Para adicionar uma categoria através de organizations.sites.apicategories.create:

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" }'

Substitua o seguinte:

ORG_NAME com o nome da organização. Por exemplo, my-org.
SITE_ID com o nome do portal, no formato ORG_NAME-PORTAL_NAME, onde ORG_NAME é o nome da organização e PORTAL_NAME é o nome do portal convertido para tudo em minúsculas e com espaços e travessões removidos. Por exemplo, my-org-myportal.
CATEGORY_NAME com o nome da categoria. Por exemplo, demo-backend.

Payload de resposta:

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

Edite uma categoria

Para editar uma categoria:

Consola

Aceda à página Categorias.
Edite uma categoria.
IU da Cloud Console
1. Na linha da categoria que quer editar, clique em Mais > Editar.
2. Edite o nome da categoria.
3. Adicione ou remova etiquetas de API.
4. Clique em Adicionar.
IU clássica
1. Aceda à página Categorias.
2. Posicione o cursor sobre a categoria que quer editar para apresentar o menu de ações.
3. Clique em Editar.
4. Edite o nome da categoria.
5. Adicione ou remova etiquetas de API.
6. Clique em Guardar.

curl

Para editar uma categoria através do organizations.sites.apicategories.patch:

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" }'

Substitua o seguinte:

ORG_NAME com o nome da organização. Por exemplo, my-org.
SITE_ID com o nome do portal, no formato ORG_NAME-PORTAL_NAME, onde ORG_NAME é o nome da organização e PORTAL_NAME é o nome do portal convertido para tudo em minúsculas e com espaços e travessões removidos. Por exemplo, my-org-myportal.
CATEGORY_ID com o ID da categoria. Por exemplo, bf6505eb-2a0f-47af-a00a-ded40ac72960. Obtenha o ID da categoria com o comando list API categories.
CATEGORY_NAME com o nome da categoria. Por exemplo, demo-backend.

Payload de resposta:

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

Elimine uma categoria

Quando elimina uma categoria, todas as etiquetas de API associadas a essa categoria também são eliminadas.

Para eliminar uma categoria:

Consola

Aceda à página Categorias.
Elimine uma categoria.
IU da Cloud Console
Na linha da categoria que quer editar, clique em Mais > Eliminar.
IU clássica
1. Posicione o cursor sobre a categoria que quer eliminar para apresentar o menu de ações.
2. Clique em Eliminar.
Clique em Eliminar para confirmar.

curl

Para eliminar uma categoria através do organizations.sites.apicategories.delete:

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"

Substitua o seguinte:

ORG_NAME com o nome da organização. Por exemplo, my-org.
SITE_ID com o nome do portal, no formato ORG_NAME-PORTAL_NAME, onde ORG_NAME é o nome da organização e PORTAL_NAME é o nome do portal convertido para tudo em minúsculas e com espaços e travessões removidos. Por exemplo, my-org-myportal.
CATEGORY_ID com o ID da categoria. Por exemplo, bf6505eb-2a0f-47af-a00a-ded40ac72960. Obtenha o ID da categoria com o comando list API categories.

Payload de resposta:

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

Resolva problemas com as suas APIs publicadas

As secções seguintes fornecem informações para ajudar a resolver problemas específicos com as nossas APIs publicadas.

Erro: falha ao obter o erro devolvido ao usar a API Try this

Quando usar a opção Experimentar esta API, se for devolvido o erro TypeError: Failed to fetch, considere as seguintes possíveis causas e resoluções:

Para erros de conteúdo misto, o erro pode ser causado por um problema conhecido da swagger-ui. Uma possível solução alternativa é certificar-se de que especifica HTTPS antes de HTTP na definição de schemes no seu documento OpenAPI. Por exemplo:
```
schemes:
   - https
   - http
```
Para erros de restrição da partilha de recursos de origem cruzada (CORS), certifique-se de que o CORS é suportado para os seus proxies de API. O CORS é um mecanismo padrão que permite pedidos de origem cruzada do lado do cliente. Consulte o artigo Configurar o proxy de API para suportar o painel Experimentar esta API.

Erro: o campo do cabeçalho do pedido não é permitido

Quando usar a opção Experimentar esta API, se receber um erro semelhante ao exemplo seguinte, pode ter de atualizar os cabeçalhos suportados na política CORS.Request header field not allowed Por exemplo:

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

Neste exemplo, tem de adicionar o cabeçalho content-type à secção Access-Control-Allow-Headers na sua política AssignMessage CORS, conforme descrito em Anexar uma política CORS a um novo proxy de API.

Erro: acesso negado ao chamar um proxy de API através do OAuth 2.0

A política OAuthV2 da consola Google Cloud devolve uma resposta de token que contém determinadas propriedades não conformes com a RFC. Por exemplo, a política devolve um token com o valor BearerToken, em vez do valor em conformidade com a RFC esperado Bearer. Esta resposta token_type inválida pode resultar num erro Access denied quando usar a opção Experimentar esta API.

Para corrigir este problema, pode criar uma política de JavaScript ou AssignMessage para transformar o resultado da política num formato em conformidade. Para mais informações, consulte o artigo sobre o comportamento não compatível com RFC.

Publicar as suas APIs Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Vista geral da publicação de APIs

O que é publicado no portal?

SmartDocs (OpenAPI)

GraphQL Explorer

Acerca da documentação da API

Acerca dos URLs de retorno

Configure o proxy de API para suportar o painel Experimentar esta API

Faça a gestão das APIs

Explore APIs

Consola

IU da Cloud Console

IU clássica

curl

Adicione uma API

Consola

IU da Cloud Console

IU clássica

IU da Cloud Console

IU clássica

IU da Cloud Console

IU clássica

curl

Edite uma API

Consola

curl

Publique ou anule a publicação de uma API

Consola

curl

Faça a gestão da visibilidade de uma API

Consola

curl

Faça a gestão do URL de retorno de uma API

Consola

curl

Faça a gestão da imagem de um cartão de API

Consola

IU da Cloud Console

IU clássica

curl

Etiquete uma API com categorias

Consola

IU da Cloud Console

IU clássica

curl

Edite o título e a descrição a apresentar

Consola

curl

Remova uma API

Consola

IU da Cloud Console

IU clássica

curl

Faça a gestão da documentação da API

Atualize a documentação da API

Consola

IU da Cloud Console

IU clássica

curl

OpenAPI

GraphQL

Transfira a documentação da API

Remova a documentação da API

Consola

curl

Faça a gestão de categorias

Explore as categorias

Consola

IU da Cloud Console

IU clássica

curl

Adicione uma categoria

Consola

IU da Cloud Console

IU clássica

curl

Edite uma categoria

Consola

IU da Cloud Console

IU clássica

Publicar as suas APIs